mirror
/
borg
mirror of https://github.com/borgbackup/borg.git
1
0
Fork 0
Code Issues Releases Wiki Activity

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

docs: authentication primitives: improved security and performance infos
This commit is contained in:
Christopher Klooz 2022-05-14 22:57:22 +02:00 committed by GitHub
parent ac4666d7f4
commit 594d83aad5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 21 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
docs/internals/security.rst
View File

@ -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