mirror/borg
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2025-01-18 13:31:52 +00:00
Code Issues Releases Wiki Activity

docs: update security docs about new one-step KDF

Browse source
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`_. 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) 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 For each session key, IVs (nonces) are generated by a counter which increments for
each encrypted message. each encrypted message.
@ -132,9 +133,8 @@ each encrypted message.
Session:: Session::
sessionid = os.urandom(24) sessionid = os.urandom(24)
ikm = crypt_key domain = "borg-session-key-CIPHERNAME"
salt = "borg-session-key-CIPHERNAME" sessionkey = sha256(crypt_key + sessionid + domain)
sessionkey = HKDF(ikm, sessionid, salt)
message_iv = 0 message_iv = 0
Encryption:: Encryption::
@ -155,7 +155,9 @@ Decryption::
ASSERT(type-byte is correct) 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) decrypted = AEAD_decrypt(past_key, past_message_iv, authenticated)
decompressed = decompress(decrypted) 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. - HMAC and a constant-time comparison from Python's hmac_ standard library module are used.
- argon2 is used via argon2-cffi. - 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 .. _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 .. _length extension: https://en.wikipedia.org/wiki/Length_extension_attack
.. _hashlib: https://docs.python.org/3/library/hashlib.html .. _hashlib: https://docs.python.org/3/library/hashlib.html
.. _hmac: https://docs.python.org/3/library/hmac.html .. _hmac: https://docs.python.org/3/library/hmac.html