Repository navigation
docs: protect the borg passphrase with age, fixes #4549 - #10404
Merged
Merged
Conversation
ThomasWaldmann
force-pushed
the
docs-age
branch
from
September 22, 2026 16:16
eb12fd3 to
af9de8f
Compare
…keys) New deployment chapter showing how to combine BORG_PASSCOMMAND with age: a strong random borg passphrase stored age-encrypted, decrypted on demand - and, via the age plugin ecosystem, bound to hardware: any FIDO2 security key (age-plugin-fido2-hmac, touch-gated by CTAP spec, interactive use), YubiKey PIV (age-plugin-yubikey, policies allow silent unattended use), TPM 2.0 (age-plugin-tpm) and Apple Secure Enclave (age-plugin-se) for machine-bound unattended backups. The guide starts with a plain no-hardware example to introduce the pattern, gives an at-a-glance table of what works unattended vs. what requires user presence, covers multi-recipient redundancy (several YubiKeys / TPM unlocking the same passphrase), the offline paper copy as the recovery path, revocation (change-passphrase, not just re-encrypting) and an honest threat-model note (at-rest protection; presence-gated options prevent silent unlocking, device-bound ones do not). This is the supported way to use hardware-backed key protection with borg, instead of borg-native hardware integrations. See the discussion in borgbackup#8995 / borgbackup#10399. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
ThomasWaldmann
force-pushed
the
docs-age
branch
from
September 22, 2026 16:51
af9de8f to
08e891c
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
New deployment guide: protect the borg passphrase with age, and through age's plugin ecosystem, with hardware.
The pattern is simple and needs no borg changes: a strong random passphrase, stored age-encrypted, decrypted on demand via
BORG_PASSCOMMAND. The age identity that decrypts it can live in hardware:never)The guide starts with a no-hardware example to introduce the pattern, then covers the interactive touch-gated FIDO2 setup, unattended setups (YubiKey PIV with
neverpolicies, TPM, Secure Enclave), multi-recipient redundancy (several YubiKeys plus the TPM unlocking the same passphrase), the offline paper copy as the always-working recovery path, real revocation (borg key change-passphrase, since re-encrypting the file is not enough), and an honest threat-model section: all of this protects data at rest; presence-gated options additionally prevent silent unlocking by code on the machine, device-bound ones do not; the repo stays only as secure as its weakest borg key.Context: this follows the decision to support hardware-backed key protection through age instead of borg-native hardware integrations — one documented pattern covers all current and future holders (each new one is an age plugin, not a borg PR), including both the presence-gated interactive case and the touchless unattended case that backup jobs actually need. Supersedes the native approaches explored in #8995 and #10399.
All plugin invocations in the guide were checked against the current upstream documentation of the four plugins.
sphinx-build -Wclean.🤖 Generated with Claude Code