docs: authentication primitives: improved security and performance infos (master) (#6667)

docs: authentication primitives: improved security and performance infos

docs/internals/security.rst

@@ -141,7 +141,7 @@ Depending on the chosen mode (see :ref:`borg_init`) different AEAD ciphers are u
 
 The chunk ID is derived via a MAC over the plaintext (mac key taken from borg key):
 
-- HMAC-SHA256 - super fast IF you have hw accelerated SHA256.
+- HMAC-SHA256 - super fast IF you have hw accelerated SHA256 (see section "Encryption" below).
 - Blake2b - very fast, purely software based algorithm.
 
 For each borg invocation, a new session id is generated by `os.urandom`_.
@@ -223,14 +223,27 @@ Depending on the chosen mode (see :ref:`borg_init`) different primitives are use
   and is also tracked locally on the client to avoid counter reuse.
 
 - The authentication primitive is either HMAC-SHA-256 or BLAKE2b-256
-  in a keyed mode. HMAC-SHA-256 uses 256 bit keys, while BLAKE2b-256
-  uses 512 bit keys.
-
-  The latter is secure not only because BLAKE2b itself is not
-  susceptible to `length extension`_, but also since it truncates the
-  hash output from 512 bits to 256 bits, which would make the
-  construction safe even if BLAKE2b were broken regarding length
-  extension or similar attacks.
+  in a keyed mode. 
+
+  Both HMAC-SHA-256 and BLAKE2b have undergone extensive cryptanalysis  
+  and have proven secure against known attacks. The known vulnerability
+  of SHA-256 against length extension attacks does not apply to HMAC-SHA-256.
+  
+  The authentication primitive should be chosen based upon SHA hardware support.
+  With SHA hardware support, hmac-sha256 is likely to be much faster. 
+  If no hardware support is provided, Blake2b-256 will outperform hmac-sha256.
+  To find out if you have SHA hardware support, use::
+
+  $ borg benchmark cpu
+
+  The output will include an evaluation of cryptographic hashes/MACs like::
+
+  Cryptographic hashes / MACs ====================================
+  hmac-sha256              1GB        0.436s
+  blake2b-256              1GB        1.579s
+
+  Based upon your output, choose the primitive that is faster (in the above
+  example, hmac-sha256 is much faster, which indicates SHA hardware support).
 
 - The primitive used for authentication is always the same primitive
   that is used for deriving the chunk ID, but they are always