Learn Borg Backup - Encryption & Key Management

#Introduction

In episode 3 you chose the encryption mode during borg init. Now we dissect that encryption fully: what is actually secured, where the key is stored, and how to manage the key so you never lose access. Remember the principle from episode 2: without the key, the repository is unreadable — even by you. This section is the one that most determines the fate of your data.

#The Encryption Modes at a Glance

#Repokey: Key Inside the Repository

In repokey mode, the encryption key is stored inside the repository and protected by a passphrase. The advantage is practical: no separate file to protect. The risk: anyone who steals the repository and manages to guess the passphrase can read the data. A strong, unique passphrase is non-negotiable.

#Keyfile: Key in a Separate File

In keyfile mode, the key is stored in a separate file (usually ~/.config/borg/keys/). A repository thief does not take the key with them — an extra security layer. The consequence is clear: the key file must be backed up. Losing the keyfile means losing access to all backups, even if you still remember the passphrase.

#Authenticated: Integrity Without Encryption

authenticated mode does not encrypt the data (making it readable on the server) but still verifies integrity. It is suitable when the storage is already encrypted at a lower layer (ZFS encryption, LUKS, encrypted cloud volumes) and you want to avoid CPU overhead. By contrast, none mode provides no security at all — only for experiments.

#The Choice Summarized

+----------------+-----------+-----------+-----------------------+
| Mode           | Encryption| Integrity | Key stored in         |
+----------------+-----------+-----------+-----------------------+
| repokey-blake2 | yes       | yes       | repository (passphrase)|
| keyfile-blake2 | yes       | yes       | separate file         |
| authenticated  | no        | yes       | -                     |
| none           | no        | no        | -                     |
+----------------+-----------+-----------+-----------------------+

#Key Management: Export, Import, and Password

#Exporting the Key

Borg provides borg key export to make a copy of the key:

borg key export /backup/borg /root/borg-key-backup.txt

borg key export --paper /backup/borg

--paper produces a base64 format that can be printed and stored in a separate physical location. Keep the export result somewhere different from the repository — the same principle as 3-2-1 for data.

#Importing the Key

If the key goes missing from its original location, import it from the backup:

borg key import /backup/borg /root/borg-key-backup.txt

#Changing the Passphrase

The passphrase can be changed at any time without touching the data (the key is re-encrypted):

borg key change-passphrase /backup/borg

#Storing the Passphrase and Keyfile Properly

#The Basic Rules

• Do not store the passphrase in git repositories, in scripts, or in dotfiles that get backed up.
• Use a password manager (KeePassXC, bitwarden, pass) or secret management (Vault, sops) to store the passphrase.
• For keyfile mode: back up the key file on separate media, plus a physical copy (paper backup) for extreme cases.

#BORG_PASSCOMMAND for Automation

Since episode 3 we have used BORG_PASSCOMMAND. This is also the doorway into secret management:

export BORG_PASSCOMMAND='pass show backup/borg'

export BORG_PASSCOMMAND='cat /root/.borg-passphrase'

With this pattern, the passphrase never appears in history, in ps, or in logs — it is only read when needed.

#Common Pitfalls

• The keyfile being backed up to the same repository: putting the keyfile in a directory backed up by the very same repo — protecting what? Keep them separate.
• A short, guessable passphrase: a repokey is only as strong as its passphrase. Use 20+ random characters.
• Not testing access after setup: after storing the key somewhere new, immediately test borg list from a clean environment to confirm access works.
• Sharing keys across hosts: for multi-host, each host should have its own repo and key (episode 14).

#Closing

• Repokey is practical (key in repo), keyfile is more secure (separate key), authenticated is without encryption.
• Exporting the key (borg key export, including --paper) is mandatory insurance.
• borg key import and borg key change-passphrase for recovery and rotation.
• Store the passphrase in a password manager; access it via BORG_PASSCOMMAND.
• Without the key/passphrase the repository is unreadable — manage both like you handle assets.

In episode 8 we manage history: prune & compact (retention) — deleting old archives measurably with borg prune, reclaiming space with borg compact, building a retention policy that fits your RPO/RTO, and using --keep-tag for tagged archives.