docs: key enc: correct / clarify some stuff, link to internals/security

docs/internals/data-structures.rst

@@ -467,11 +467,16 @@ or prompted for interactive usage.
 Key files
 ---------
 
+.. seealso:: The :ref:`key_encryption` section for an in-depth review of the key encryption.
+
 When initialized with the ``init -e keyfile`` command, |project_name|
 needs an associated file in ``$HOME/.config/borg/keys`` to read and write
 the repository. The format is based on msgpack_, base64 encoding and
 PBKDF2_ SHA256 hashing, which is then encoded again in a msgpack_.
 
+The same data structure is also used in the "repokey" modes, which store
+it in the repository in the configuration file.
+
 The internal data structure is as follows:
 
 version
@@ -492,12 +497,14 @@ id_key
 chunk_seed
   the seed for the buzhash chunking table (signed 32 bit integer)
 
-Those fields are processed using msgpack_. The utf-8 encoded passphrase
+These fields are packed using msgpack_. The utf-8 encoded passphrase
 is processed with PBKDF2_ (SHA256_, 100000 iterations, random 256 bit salt)
-to give us a derived key. The derived key is 256 bits long.
-A `HMAC-SHA256`_ checksum of the above fields is generated with the derived
-key, then the derived key is also used to encrypt the above pack of fields.
-Then the result is stored in a another msgpack_ formatted as follows:
+to derive a 256 bit key encryption key (KEK).
+
+A `HMAC-SHA256`_ checksum of the packed fields is generated with the KEK,
+then the KEK is also used to encrypt the same packed fields using AES-CTR.
+
+The result is stored in a another msgpack_ formatted as follows:
 
 version
   currently always an integer, 1
@@ -513,18 +520,16 @@ algorithm
   checksum (currently the string ``sha256``)
 
 hash
-  the HMAC of the encrypted derived key
+  HMAC-SHA256 of the *plaintext* of the packed fields.
 
 data
-  the derived key, encrypted with AES over a PBKDF2_ SHA256 key
-  described above
+  The encrypted, packed fields.
 
 The resulting msgpack_ is then encoded using base64 and written to the
 key file, wrapped using the standard ``textwrap`` module with a header.
 The header is a single line with a MAGIC string, a space and a hexadecimal
 representation of the repository id.
 
-
 Compression
 -----------
 

docs/internals/security.rst

@@ -174,6 +174,8 @@ Decryption::
 
        Borg does not support "passphrase" mode otherwise any more.
 
+.. _key_encryption:
+
 Offline key security
 --------------------
 
@@ -185,12 +187,11 @@ user-chosen passphrase.
 
 A 256 bit key encryption key (KEK) is derived from the passphrase
 using PBKDF2-HMAC-SHA256 with a random 256 bit salt which is then used
-to Encrypt-then-MAC a packed representation of the keys with
-AES-256-CTR with a constant initialization vector of 0 (this is the
-same construction used for Encryption_ with HMAC-SHA-256).
-
-The resulting MAC is stored alongside the ciphertext, which is
-converted to base64 in its entirety.
+to Encrypt-*and*-MAC (unlike the Encrypt-*then*-MAC approach used
+otherwise) a packed representation of the keys with AES-256-CTR with a
+constant initialization vector of 0. A HMAC-SHA256 of the plaintext is
+generated using the same KEK and is stored alongside the ciphertext,
+which is converted to base64 in its entirety.
 
 This base64 blob (commonly referred to as *keyblob*) is then stored in
 the key file or in the repository config (keyfile and repokey modes
@@ -198,9 +199,19 @@ respectively).
 
 This scheme, and specifically the use of a constant IV with the CTR
 mode, is secure because an identical passphrase will result in a
-different derived KEK for every encryption due to the salt.
+different derived KEK for every key encryption due to the salt.
+
+The use of Encrypt-and-MAC instead of Encrypt-then-MAC is seen as
+uncritical (but not ideal) here, since it is combined with AES-CTR mode,
+which is not vulnerable to padding attacks.
+
+
+.. seealso::
+
+   Refer to the :ref:`key_files` section for details on the format.
 
-Refer to the :ref:`key_files` section for details on the format.
+   Refer to issue :issue:`747` for suggested improvements of the encryption
+   scheme and password-based key derivation.
 
 Implementations used
 --------------------
@@ -223,6 +234,8 @@ Implemented cryptographic constructions are:
 
 - Encrypt-then-MAC based on AES-256-CTR and either HMAC-SHA-256
   or keyed BLAKE2b256 as described above under Encryption_.
+- Encrypt-and-MAC based on AES-256-CTR and HMAC-SHA-256
+  as described above under `Offline key security`_.
 - HKDF_-SHA-512
 
 .. _Horton principle: https://en.wikipedia.org/wiki/Horton_Principle