Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 5 commits into from
May 14, 2022
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 22 additions & 9 deletions docs/internals/security.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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`_.
Expand Down Expand Up @@ -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
Expand Down