Learning Restic - Encryption & Keys

#Introduction

Since episode 1 we have kept saying "built-in AES-256 encryption". Episode 13 is the time to open the hood: how restic encrypts, who holds the keys, and how to manage keys without locking yourself out. This is the layer that sets restic apart from an ordinary backup tool — and the main reason you can store it on someone else's storage safely.

#The Encryption Scheme: AES-256-CTR + Poly1305-AES

Every blob in the repository is encrypted on two layers:

• Confidentiality: AES-256-CTR — a fast stream cipher mode well suited to large data. Its key is derived from the repository master key.
• Integrity: Poly1305-AES — a Message Authentication Code (MAC) that protects every blob from modification. If a single byte changes, the MAC does not match and restic detects it.

This "encrypt-then-MAC" combination means the repository is not only unreadable by others, but also cannot be silently altered — the foundation of the immutable snapshot claim from episode 1.

#Key Hierarchy

Restic uses a two-level hierarchy:

1. Repo key (password): you enter it every time you open the repository. It is never stored on the storage — only its derivative is.
2. Master key: the actual encryption key, randomly generated at restic init, encrypted with the repo key, then stored in the keys/ directory.

When opening the repository, restic decrypts the master key using your password. Losing the password = losing the master key = data unreadable forever — the reason for the warning in episode 3.

#Key Management with restic key

Because only the master key protects the data, the password can be changed without re-decrypting the entire repository — just re-encrypt the master key with a new password:

#Listing Keys

restic key list

#Adding a Key

Useful for granting access to team members without sharing the main password:

restic key add

#Changing the Password

restic key passwd

This is the first step you should take if the password is exposed (for example, leaked in git).

#Removing a Key

restic key remove <key-id>

Don't remove your own key without making sure another valid key remains — if all keys are removed, the master key cannot be decrypted and the repository dies completely.

#Passphrase Policy

The repository password is the single gate to your data. A healthy standard:

• Length ≥ 20 characters, random, a combination of unique words (passphrase) or diceware.
• Unique — never reused for other accounts.
• Stored in a vault/password manager (Bitwarden, KeePass, 1Password) or a secret manager (Vault/OpenBao — see the Learning Secret Management series).
• One repo, one passphrase documented in a location separate from the repository.

Example of generating a secure passphrase:

openssl rand -base64 30

Example output

k7Qp2xLm9zVt4aR8bN1cD6fH3jK0qW5

Keep a physical copy (printed) in a safe place as the last safety net — echoing the severity of "forgotten password = data lost".

#Conclusion

• Encryption: AES-256-CTR for confidentiality, Poly1305-AES (MAC) for integrity.
• Hierarchy: password → repo key → master key; a forgotten password = data lost.
• restic key list/add/passwd/remove manages repo keys without re-encrypting data.
• Change the password immediately (restic key passwd) if a key is exposed.
• Passphrase: ≥ 20 characters, unique, stored in a vault + a separate physical copy.
• Repo key ≠ backend credential — don't confuse them.

In the next episode, episode 14, we secure the path and storage: backend & transport security — why SFTP/HTTPS and not bare rsync, TLS for S3, firewalls, and immutability via bucket object lock and an --append-only repo for anti-ransomware defense.