crypto: misc. improvements to code and docs

[ThomasWaldmann]

Fixes #6501.

Claude says: Implements the assessment items from #6501 (comment), plus some related crypto code/docs fixes found while working on it.

Limit the data encrypted with one aes256-ocb session key (item 2)

AES-OCB has a birthday-type security bound in the amount of data encrypted using one key: the attacker's advantage is about 6 * sigma^2 / 2^128, sigma being the number of 128bit cipher blocks (Krovetz/Rogaway OCB3, Theorem 1). RFC 7253 derives its "use a key for at most 2^48 blocks (4PiB)" rule of thumb from that bound, which corresponds to an advantage of 2^-32.

We now aim higher and start a new session after 2^37 blocks (2TiB), giving an advantage of about 2^-51, in line with the target probability used in the examples of draft-irtf-cfrg-aead-limits.

AEADKeyBase.encrypt counts the cipher blocks processed with the current session key (payload and AAD rounded up separately, +2 for the per-message cipher setup) and starts a new session before the limit would be exceeded. Starting a new session is just a new random session id, a new derived session key and IV counting from 0 again - cheap (one sha256) and fully transparent, because the session id is part of every chunk header, so old chunks stay decryptable and nothing changes for reading existing repositories. No repository format change.

Rekeying that often is also what helps in the multi-key setting: the advantages of the individual session keys just add up, so the quantity that matters over the lifetime of a borg key is sum(sigma_i^2) and not (sum sigma_i)^2.

chacha20-poly1305 keeps MAX_SESSION_BLOCKS = None (no limit, and no per-chunk counting overhead): its confidentiality bound does not depend on the amount of data encrypted at all (draft-irtf-cfrg-aead-limits 6.3.1) and its integrity bound only limits the number of forgery attempts, which is counted over all keys (7.2.1) and thus can not be improved by using more session keys anyway.

Document the AEAD usage limits (items 3 + 4)

New "AEAD usage limits" section in docs/internals/data-structures.rst: the IV range limits the number of messages per session key (2^48, never binding), the amount of data per session key is limited by the cipher security bounds (see above), and the forgery attempts limit (chacha20-poly1305, about 2^33 for our biggest messages at p 2^-50, counted over all keys) is deliberately not counted/enforced - borg refuses tampered data and usually aborts, and reaching the limit would need more tampered data than a real repository will ever hold. Cross-referenced from the in-depth crypto docs (security.rst) and noted at the decrypt code.

Fix the "internal 32bit counter" claim (item 6)

"AES-OCB, CHACHA20 ciphers all add a internal 32bit counter to the 96bit IV we provide" was only true for chacha20-poly1305; AES-OCB has no such counter, it derives the per-block offsets from the nonce (RFC 7253). The conclusions drawn from the claim (2^32 blocks per message check, increment IV by 1 per message) stay valid for both ciphers and are now explained correctly. Also fixed the stale API sketch in the module docstring (next_iv() takes no argument etc.).

Truncated envelope fix (found in review)

A truncated envelope (shorter than header + auth tag; for the legacy AES-CTR modes: header + mac + iv) ended up calling EVP_DecryptUpdate with a negative length, which OpenSSL luckily rejects, surfacing as CryptoError('EVP_DecryptUpdate failed') - which no caller catches, so e.g. a 32..47 byte tampered chunk gave an ugly crash instead of clean error handling. Now the envelope length is checked first and IntegrityError is raised, which the upper layers already handle as corrupted/tampered data.

Also: requirements_check() raised the NotImplemented constant (a TypeError at runtime) instead of NotImplementedError; the _AEAD_BASE key docstring called the AEAD key an "encrypt-then-mac key"; low_level.pyi declared an AES class that does not exist in this module - the stub moved to a new borg/legacy/crypto/low_level.pyi, where the legacy AES wrapper actually lives; removed unused cimports/extern declarations.

Tests

• test_ocb_session_key_rollover: with the limit monkeypatched down, the session id changes, the IV starts from the beginning in each new session, and all chunks still decrypt.
• test_chpo_no_session_key_rollover: chacha20-poly1305 keeps one session id.
• test_AEAD_truncated_envelope / test_AE_truncated_envelope: truncated envelopes raise IntegrityError for both AEAD ciphers and the legacy CTR mode.
• Manually, end-to-end with the limit forced down to 16kiB: one borg create of 8MiB used 15 session keys, an unpatched borg check and borg extract then read it back byte-identical.
• Docs build cleanly (sphinx, no warnings).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.87%. Comparing base (fb7c717) to head (b890e9c).
⚠️ Report is 1 commits behind head on master.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #9979   +/-   ##
=======================================
  Coverage   85.86%   85.87%           
=======================================
  Files          95       95           
  Lines       17064    17078   +14     
  Branches     2614     2616    +2     
=======================================
+ Hits        14652    14665   +13     
  Misses       1673     1673           
- Partials      739      740    +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.