Skip to content

docs: fix init epilog about what none mode can (not) detect (1.4-maint) - #10343

Merged
ThomasWaldmann merged 1 commit into
borgbackup:1.4-maintfrom
ThomasWaldmann:docs-none-mode-integrity-1.4
Sep 9, 2026
Merged

docs: fix init epilog about what none mode can (not) detect (1.4-maint)#10343
ThomasWaldmann merged 1 commit into
borgbackup:1.4-maintfrom
ThomasWaldmann:docs-none-mode-integrity-1.4

Conversation

@ThomasWaldmann

Copy link
Copy Markdown
Member

The "About modes without encryption" paragraph of the borg init epilog (also in the generated borg-init man page) says that using any mode other than none "allows Borg to detect accidental corruption or malicious tampering with the repo", which implies none mode detects neither.

That is only half true. none mode (PlaintextKey) still:

  • verifies the CRC32 of every repository object on read and in the repository check,
  • verifies the SHA-256 chunk IDs in decrypt() (assert_id), i.e. on extract, mount, borg check --verify-data, etc.,
  • verifies the manifest/archive TAMs, but with a key derived from public data only.

So accidental corruption is detected. What none mode cannot detect is malicious tampering, because none of these checks involve a secret key: anyone with write access can modify data and recompute everything up the chain (or simply run borg against the repo). The borg check epilog already states this correctly ("Tamper-resistance is only guaranteed ... against attackers without access to the keys").

Verified on a 1.4-maint build with -e none repos:

Scenario borg check check --verify-data extract
flip one data byte in a segment segment entry checksum mismatch same IntegrityError
flip one byte and recompute the CRC32 passes (plain check never reads content chunks, in any mode) id verification failed id verification failed
borg recreate --exclude without any key/passphrase clean clean n/a

This PR only rewords that paragraph; the generated docs/usage/init.rst.inc and man page are left for the usual release-time regeneration.

🤖 Generated with Claude Code

The "About modes without encryption" paragraph claimed that only modes
other than "none" let borg detect accidental corruption or malicious
tampering. That is only half true: "none" mode still verifies the CRC32
of every repository object and the SHA-256 chunk IDs (e.g. on extract or
with "borg check --verify-data"), so accidental corruption is detected.
What "none" mode cannot detect is malicious tampering, because none of
these checks involve a secret key.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@codecov

codecov Bot commented Sep 9, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.13%. Comparing base (d2fb419) to head (8e13924).
⚠️ Report is 1 commits behind head on 1.4-maint.

Additional details and impacted files
@@              Coverage Diff              @@
##           1.4-maint   #10343      +/-   ##
=============================================
- Coverage      82.13%   82.13%   -0.01%     
=============================================
  Files             38       38              
  Lines          11478    11478              
  Branches        1808     1808              
=============================================
- Hits            9428     9427       -1     
- Misses          1465     1466       +1     
  Partials         585      585              

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

@ThomasWaldmann
ThomasWaldmann merged commit 4ef44b0 into borgbackup:1.4-maint Sep 9, 2026
14 of 15 checks passed
@ThomasWaldmann
ThomasWaldmann deleted the docs-none-mode-integrity-1.4 branch September 9, 2026 15:43
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