Skip to content

remove the none-sha256 and none-blake3 encryption modes - #10381

Open
ThomasWaldmann wants to merge 5 commits into
borgbackup:masterfrom
ThomasWaldmann:remove-none-modes
Open

ThomasWaldmann wants to merge 5 commits into
borgbackup:masterfrom
ThomasWaldmann:remove-none-modes

Conversation

@ThomasWaldmann

@ThomasWaldmann ThomasWaldmann commented Sep 17, 2026

Copy link
Copy Markdown
Member

Removes the none-sha256 / none-blake3 modes. Every borg 2 mode has a borg key now: aes256-ocb, chacha20-poly1305, authenticated-sha256, authenticated-blake3.

No compatibility with repositories that older borg 2 betas created in a none-* mode: their key type bytes (0x80 / 0x90) are gone, opening such a repository gives UnsupportedPayloadError.

Changes

  • crypto.key: remove ChecksumKeyBase, ChecksumKey, Blake3ChecksumKey and KeyType.SHA256NONE / BLAKE3NONE. MACKeyBase now only serves the authenticated-* modes.
  • remove KeyBase.id_check_is_authentication: it only existed for the unkeyed modes. All borg 2 envelopes authenticate the chunk id, so RepoObj.parse verifies the id at the BORG_ASSERT_ID places and the mandatory ones (check --verify-data). RepoObj1.parse (borg 1.x repos) always verifies, as before.
  • has_secret_key stays, the read-only borg 1.x none key class still needs it (repo-create --other-repo).
  • repo-create: help / epilog / completion descriptions updated, the "you will need both KEY AND PASSPHRASE" hint is always shown.
  • borg key ...: remove the "This repository is not encrypted ..." guards and the NO_STORAGE check in KeyManager - they can not trigger any more (2nd commit). UnencryptedRepo is kept (not raised) so rc 46 stays reserved.
  • KeyType: no longer reserves 0x50, the key type of an older borg 2 beta mode - the next beta needs new repositories anyway (3rd commit).
  • legacy PlaintextKey: remove the empty crypt_key / id_key, which only existed to make derive_key() work for a key without key material (the chunkers call it for the key of the repository they write to - always a borg 2 key now), and test_derive_key_with_plaintext_key (4th commit).
  • KeyType: renumber SHA256AUTHENTICATED 0x60 -> 0x50 and BLAKE3AUTHENTICATED 0x70 -> 0x60, so the borg 2 key types are contiguous (0x10 .. 0x60). The type byte is covered by the envelope tag, so the golden vectors of test_format_is_stable changed, too (5th commit). Not a compatibility concern: the next beta can not read repositories of older betas anyway.
  • docs: README, internals (data-structures, packs, security), repo-create examples, BORG_ASSERT_ID / authenticated_no_key help texts.

borg 1.x "none" repositories

They use unkeyed sha256 chunk ids, which no borg 2 mode has any more. So borg transfer --from-borg1 from such a repository needs --chunker-params (like blake2 repositories do), and the new repository is created without --other-repo (there is no key material to copy). Documented in docs/usage/transfer.rst.

Tests

  • new make_test_key() helper (an authenticated-sha256 key with fixed key material) replaces ChecksumKey(...) where a test just needs some key.
  • archiver tests that used none-sha256 as the cheap default mode use authenticated-sha256 now; tests about the none modes themselves are removed.
  • repository swap detection tests: a borg key is labelled with its repository id, so the "attacker" repository now gets its repokey re-labelled for the faked id.
  • tests not using the archiver fixtures (test_with_lock, test_disk_full, cockpit) set BORG_PASSPHRASE themselves.

Local run on macOS (rebased onto master incl. #10377): 3061 passed, 1014 skipped (without mount_cmds_test.py, FUSE does not work on that machine currently; cockpit_test only runs on FreeBSD / Windows) - so CI has to cover these.

Not done here: the generated docs/usage/*.rst.inc / man pages still mention none-* until they get regenerated, and docs/changes.rst is untouched (the b25 entry for #9072 mentions none-*).

🤖 Generated with Claude Code

@codecov

codecov Bot commented Sep 17, 2026

Copy link
Copy Markdown

Codecov Report

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

Additional details and impacted files
@@            Coverage Diff             @@
##           master   #10381      +/-   ##
==========================================
+ Coverage   88.14%   88.16%   +0.02%     
==========================================
  Files         103      103              
  Lines       18896    18829      -67     
  Branches     2931     2921      -10     
==========================================
- Hits        16655    16600      -55     
+ Misses       1557     1552       -5     
+ Partials      684      677       -7     

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

ThomasWaldmann and others added 5 commits September 18, 2026 01:17
Every borg 2 mode has a borg key now: the AEAD modes (aes256-ocb,
chacha20-poly1305) and the authenticated-sha256 / authenticated-blake3
modes. There is no compatibility with repositories older borg 2 betas
created in a none-* mode.

- crypto.key: remove ChecksumKeyBase, ChecksumKey, Blake3ChecksumKey and
  the SHA256NONE / BLAKE3NONE key types.
- remove KeyBase.id_check_is_authentication: all borg 2 envelopes
  authenticate the chunk id, so RepoObj.parse verifies the id only at
  the BORG_ASSERT_ID places and the mandatory ones.
- repo-create: always show the key / passphrase hint.
- a borg 1.x "none" repository has unkeyed chunk ids, which no borg 2
  mode has, so transferring it needs --chunker-params (docs updated).
- tests: use authenticated-sha256 where none-sha256 was used as the
  cheap default mode, add make_test_key() for tests needing some key.
  The repository swap detection tests now re-label the repokey of the
  attacker's repository for the faked repository id.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
All borg 2 key classes are FlexiKey based and have a configurable key
location, so the "This repository is not encrypted ..." checks of the
borg key subcommands and the NO_STORAGE check of KeyManager could not
trigger anymore.

UnencryptedRepo is not raised anymore, the class stays defined to keep
its exit code (rc 46) reserved.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
0x50 was the beta "authenticated" mode with blake3 ids. Repositories of
older borg 2 betas can not be read anyway (repositories need to be
created anew), so there is no need to keep that byte reserved.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
They only existed to make derive_key() work for a key without key
material, as the chunkers call it for the key of the repository they
write to. That is always a borg 2 key with real key material now, the
borg 1.x PlaintextKey is only used to read a borg 1.x repository.

Also remove test_derive_key_with_plaintext_key, which tested that case.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
SHA256AUTHENTICATED 0x60 -> 0x50, BLAKE3AUTHENTICATED 0x70 -> 0x60, so
the borg 2 key types are contiguous (0x10 .. 0x60) again.

The type byte is covered by the envelope tag, so the golden vectors of
test_format_is_stable change, too (verified by recomputing them from the
documented envelope format, independently of the key classes).

This breaks authenticated-* repositories created by older borg 2 betas,
which is fine: the next beta needs new repositories anyway.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant