From 594d83aad57d44352cffc68536470141f99ea66c Mon Sep 17 00:00:00 2001 From: Christopher Klooz Date: Sat, 14 May 2022 22:57:22 +0200 Subject: [PATCH] docs: authentication primitives: improved security and performance infos (master) (#6667) docs: authentication primitives: improved security and performance infos --- docs/internals/security.rst | 29 +++++++++++++++++++++-------- 1 file changed, 21 insertions(+), 8 deletions(-) diff --git a/docs/internals/security.rst b/docs/internals/security.rst index 8ca4b8aa0..69f22a804 100644 --- a/docs/internals/security.rst +++ b/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. + in a keyed mode. - 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. + 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