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

docs: update security docs about new one-step KDF

This commit is contained in:
Thomas Waldmann 2023-11-30 21:32:34 +01:00
parent a4602c6f61
commit 74c34ba7c6
No known key found for this signature in database
GPG Key ID: 243ACFA951F78E01
3 changed files with 7 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/internals/encryption-aead.odg
View File

Binary file not shown.

BIN
docs/internals/encryption-aead.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 146 KiB

After

Width:  |  Height:  |  Size: 129 KiB

17
docs/internals/security.rst
View File

@ -124,7 +124,8 @@ The chunk ID is derived via a MAC over the plaintext (mac key taken from borg ke
For each borg invocation, a new session id is generated by `os.urandom`_.
From that session id, the initial key material (ikm, taken from the borg key)
and an application and cipher specific salt, borg derives a session key via HKDF.
and an application and cipher specific salt, borg derives a session key using a
"one-step KDF" based on just sha256.
For each session key, IVs (nonces) are generated by a counter which increments for
each encrypted message.
@ -132,9 +133,8 @@ each encrypted message.
Session::
sessionid = os.urandom(24)
ikm = crypt_key
salt = "borg-session-key-CIPHERNAME"
sessionkey = HKDF(ikm, sessionid, salt)
domain = "borg-session-key-CIPHERNAME"
sessionkey = sha256(crypt_key + sessionid + domain)
message_iv = 0
Encryption::
@ -155,7 +155,9 @@ Decryption::
ASSERT(type-byte is correct)
past_key = HKDF(ikm, past_sessionid, salt)
domain = "borg-session-key-CIPHERNAME"
past_key = sha256(crypt_key + past_sessionid + domain)
decrypted = AEAD_decrypt(past_key, past_message_iv, authenticated)
decompressed = decompress(decrypted)
@ -229,12 +231,7 @@ on widely used libraries providing them:
- HMAC and a constant-time comparison from Python's hmac_ standard library module are used.
- argon2 is used via argon2-cffi.
Implemented cryptographic constructions are:
- HKDF_-SHA-512 (using ``hmac.digest`` from Python's hmac_ standard library module)
.. _Horton principle: https://en.wikipedia.org/wiki/Horton_Principle
.. _HKDF: https://tools.ietf.org/html/rfc5869
.. _length extension: https://en.wikipedia.org/wiki/Length_extension_attack
.. _hashlib: https://docs.python.org/3/library/hashlib.html
.. _hmac: https://docs.python.org/3/library/hmac.html