A practical guide to age on Linux

· 25 min read

  • linux
  • security
  • cryptography

Before you start

age encrypts files with a single command line and keys that fit on one line of text. This guide shows every command actually running, the output it prints, and what happens under the hood.

All outputs below were captured with age v1.3.2 on Linux (and, where they appear, OpenSSH's ssh-keygen and sops 3.13.3). The keys shown were generated just for this article and have already been thrown away: never publish yours.

Who makes age

age (always written in lowercase) was designed by Filippo Valsorda (@FiloSottile) and Ben Cox (@benjojo). The pieces you'll run into:

WhatWhere
Format specificationc2sp.org/age
Reference implementation in Go (age, age-keygen, age-inspect)github.com/FiloSottile/age
Official binariesdl.filippo.io/age
Rust implementation, fully compatiblerage
TypeScript implementation (browser, Node.js)typage
Plugins, tools and integrationsawesome-age

Because the format is a public specification, a file made with age opens with rage and vice versa. For a tool you'll trust your data to, install it from these sources or from your distribution, not from a random mirror.

What age does, and what it doesn't

age does one thing: encrypt files so that only the holders of certain keys can read them. If you've used GPG, the difference is scope. GPG (OpenPGP) also signs, keeps keyrings, has a web of trust and dozens of options. age has no configuration, no keyrings and no signatures. Fewer features means fewer ways to get it wrong, but it also means there's one thing age doesn't tell you: who created a file.

Encrypting only takes the public key, which by design you hand out. So anyone who has it can create a file that opens cleanly with your private key. Here, a "message from someone else" encrypted to a key generated for this example:

bash
echo 'Please wire the payment to account 99-1234.' \
  | age -r age1kayung4jcqqar5m50l82jyd87zmkdz24fh7mcgqnwl963vmx696q79xdjk -o invoice.txt.age
age -d -i key.txt invoice.txt.age
output
Please wire the payment to account 99-1234.

No warning. age guarantees that nobody else can read the content and that nobody changed the file after it was created (section 2), but not that it came from whoever you expect. Passphrase files are the exception: only someone who knows the passphrase can create one (section 3).

When authorship matters, sign the encrypted file. The ssh-keygen you already have does it:

bash
ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n file report.age
output
Signing file report.age
Write signature to report.age.sig

Whoever receives it keeps an allowed_signers file with the keys they trust, one line per person (an identifier and the SSH public key):

text
[email protected] ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBqTqH...

And checks the signature before opening the file:

bash
ssh-keygen -Y verify -f allowed_signers -I [email protected] -n file -s report.age.sig < report.age
output
Good "file" signature for [email protected] with ED25519 key SHA256:BO8eWB7uElf7Lv2mWQSMgnFCQv4UKtc+3Z1pfxRL5WY

The same signature checked against the forged invoice:

output
Signature verification failed: incorrect signature
Could not verify signature.

-n file is a namespace: a signature made for files can't be reused as, say, a git commit signature. If you'd rather not sign with SSH keys, minisign does the same job.

Installation

On Ubuntu, the package comes straight from the repository:

bash
sudo apt install age
age --version
output
1.1.1

Notice the version. Ubuntu's repository usually lags behind the official release, and features like post-quantum keys (-pq) and the age-inspect command only exist from v1.3.0 onward. To get the latest version, download the official binary:

bash
curl -L -o age.tar.gz "https://dl.filippo.io/age/latest?for=linux/amd64"
tar xzf age.tar.gz
sudo install age/age age/age-keygen age/age-inspect /usr/local/bin/
age --version
output
v1.3.2

The package installs a few commands. The ones that matter day to day:

CommandWhat it does
ageEncrypts and decrypts
age-keygenGenerates keys and extracts the public key from a private one
age-inspectShows information about a .age file without opening it (v1.3.0+)

1. Generating your keys

Everything starts with a key pair: the private key (yours, secret) and the public key (the one you hand out). Anyone with the public key can lock files for you; only the private key unlocks them.

bash
mkdir -p ~/.config/age
chmod 700 ~/.config/age
age-keygen -o ~/.config/age/key.txt
output
Public key: age1ydslw3ud3lhduft004quqne7qtyqjt3df7wj6dw5puurfqayzymq8u6zg4

What happened: age-keygen drew 32 random bytes (the X25519 private key), computed the matching public key, wrote everything to key.txt and printed the public key to the screen. The file is created with 600 permissions (only you can read it):

bash
ls -l ~/.config/age/key.txt
output
-rw------- 1 david david 189 Oct  1 09:31 key.txt

Inside, key.txt has only three lines:

text
# created: 2026-10-01T09:31:13-03:00
# public key: age1ydslw3ud3lhduft004quqne7qtyqjt3df7wj6dw5puurfqayzymq8u6zg4
AGE-SECRET-KEY-1QUS6JV3SG65QCQHVHNVN4CEGY5QJKWVUDDMEYX067HVR5Y45LD0Q926WJ2
  • Lines starting with # are comments: creation date and the public key, for reference.
  • The AGE-SECRET-KEY-1... line is the entire private key. Whoever has that line can open all your files.
  • The format is Bech32 (the same one used in Bitcoin addresses): it has a built-in checksum, so a mistyped character is detected instead of silently producing a different key.

Recovering the public key later

Lost your age1...? It's derived from the private key, so you can recompute it at any time:

bash
age-keygen -y ~/.config/age/key.txt
output
age1ydslw3ud3lhduft004quqne7qtyqjt3df7wj6dw5puurfqayzymq8u6zg4

Overwrite protection

age-keygen refuses to overwrite an existing key, which keeps you from losing it by accident:

bash
age-keygen -o ~/.config/age/key.txt
output
age-keygen: error: failed to open output file "key.txt": open key.txt: file exists

Without -o, it prints the new key to the screen instead of writing it, which is handy for piping it straight into another command (we'll see this in section 8).

2. Encrypting and decrypting a file

Let's create a file with something sensitive and lock it to our own public key.

bash
printf 'Wifi password: banana123\nSafe box PIN: 4271\n' > notes.txt

age -r age1ydslw3ud3lhduft004quqne7qtyqjt3df7wj6dw5puurfqayzymq8u6zg4 \
    -o notes.txt.age notes.txt

Nothing shows up on screen. In the UNIX world, silence means success.

  • -r (recipient) says who you're encrypting for: the public key.
  • -o (output) is the output file. Without it, the result goes to standard output: that's what makes pipes and > work, but on a terminal age refuses to print binary (see Errors you'll run into). In practice, always end the command with -o, a > or a pipe.
  • The last argument is the input. Without it, age reads from standard input (which is why it works in pipes).

A shortcut for encrypting to yourself: instead of the public key, pass your own key file with -i. In that case -e (encrypt) is required, otherwise age assumes you forgot -d:

output
age: error: -i/--identity and -j can't be used in encryption mode unless symmetric encryption is explicitly selected with -e/--encrypt
age: hint: did you forget to specify -d/--decrypt?
bash
age -e -i ~/.config/age/key.txt -o notes.txt.age notes.txt

The result is the same: a file encrypted to your public key, which age derives from the private one.

What happened under the hood

  1. age drew a 16-byte file key, unique to this file.
  2. It generated a throwaway key pair, did an X25519 key agreement with your public key, and used the result to lock the file key. That "envelope" is the stanza.
  3. It computed a seal (HMAC) over the header, to detect tampering.
  4. It encrypted the content with ChaCha20-Poly1305, in 64 KiB chunks.

What a .age file looks like inside

The header is readable text; only the content is binary:

bash
head -c 200 notes.txt.age
output
age-encryption.org/v1                                   <- format version
-> X25519 s9NpeNrYYto2vMS96IR5GbM2oP+bXmN53bgC6wdiDUA   <- stanza: type + throwaway key
VzNEka0tpZrzqf57D5qJxRAA/Kja1jrc+v7l36mjlfI             <- locked file key
--- fxUc7YAlZIygGc+opSRyP0PfK7qEGzFfLpTQkWMtREU         <- header seal (MAC)
�'L`5&�"0�.�)���:6�>6�l ...                             <- encrypted content

The arrows and comments on the right were added for explanation; they're not part of the file.

An important detail: the header doesn't say which key the file was encrypted to. It only says it's X25519. Someone who intercepts the file can't tell it's yours.

Size

bash
ls -l notes.txt notes.txt.age
output
-rw-r--r-- 1 david david  44 Oct  1 09:31 notes.txt
-rw-r--r-- 1 david david 244 Oct  1 09:31 notes.txt.age

The extra 200 bytes are fixed: 168 for the header, 16 for the nonce and 16 for the authentication tag. For a 1 GB file, the overhead is negligible (16 bytes per 64 KiB).

Decrypting

bash
age -d -i ~/.config/age/key.txt -o notes.txt notes.txt.age
cat notes.txt
output
Wifi password: banana123
Safe box PIN: 4271
  • -d (decrypt) reverses the operation.
  • -i (identity) points to the private key. You can repeat -i with several keys; age tries all of them.

To just read it without writing to disk, leave out -o. The text goes to the screen or to another program:

bash
age -d -i ~/.config/age/key.txt notes.txt.age | less

Errors you'll run into

Wrong key:

output
age: error: no identity matched any of the recipients

None of the keys passed with -i can open any envelope in the header.

Modified or corrupted file (I changed a single byte at the end):

output
age: error: failed to decrypt and authenticate payload chunk, file may be corrupted or tampered with

age never silently hands you tampered content: if a byte changed, it stops.

Sending binary to the terminal (forgot -o):

output
age: error: refusing to output binary to the terminal
age: hint: did you mean to use -a/--armor?
age: hint: force anyway with "-o -"
age: report unexpected or unhelpful errors at https://filippo.io/age/report

Protection against flooding your screen with binary garbage. Use -o file, a pipe, or -a (section 7). The hint's -o - means "standard output": it doesn't save anything, it just forces the encrypted bytes onto the screen.

Watch out: age overwrites the -o file without asking, and doesn't delete the original. After encrypting, notes.txt is still there in plain text until you remove it, and removing it properly takes more than rm (section 14).

3. Using a passphrase instead of a key

To send a file to someone who doesn't have an age key, or to protect something quickly, use -p. No key needs to be generated beforehand.

bash
age -p -o secret.age notes.txt
output
Enter passphrase (leave empty to autogenerate a secure one):
age: using autogenerated passphrase "erase-resource-child-candy-example-pear-pave-finish-social-cinnamon"

What happened: I pressed Enter without typing anything and age generated a passphrase of 10 random words. It's strong (about 100 bits of entropy) and easier to read over the phone than a string of symbols. Copy it to your password manager: it won't be shown again.

If you'd rather type your own, age asks for it twice:

output
Enter passphrase (leave empty to autogenerate a secure one):
Confirm passphrase:

The passphrase never appears on screen and can't be passed as an argument. That's on purpose: an argument would end up in your shell history and be visible in ps to other users.

The header changes

text
age-encryption.org/v1
-> scrypt 8CmxPV7t2hEFpbJXxmtuKQ 18
luCBRo3+FegXbAvg5C1qn4K35ldq1S1xMQACKoG91Ms
--- NzEnS4EHMGRzBfGkjTORkJ7K10upGbpyJXsEy8MQm6U

The stanza is now scrypt. The two values are the random salt and the work factor 18, meaning 2^18 scrypt iterations. That's what makes each passphrase guess cost memory and time, making brute force expensive.

Opening it

No -i needed: age sees from the header that it's a passphrase and asks for it.

bash
age -d secret.age
output
Enter passphrase:
Wifi password: banana123
Safe box PIN: 4271

Wrong passphrase:

output
age: error: incorrect passphrase

Limitation

Passphrases and keys don't mix in the same file:

output
age: error: -p/--passphrase can't be combined with -r/--recipient

A passphrase-protected file has exactly one passphrase and no other recipients. The reason is in the specification: a passphrase file carries an implicit guarantee of authorship, since only someone who knows the passphrase could have created it. Adding a public key would break that, because anyone with the public key could create the file (see "What age does, and what it doesn't"). To share with several people, use keys (next section).

4. Multiple recipients

The same file can be opened by several keys. Just repeat -r:

bash
age -r age1ydslw3ud3lhduft004quqne7qtyqjt3df7wj6dw5puurfqayzymq8u6zg4 \
    -r age18cmdfem3afacqvmmaqajevjykjwqjvqh4rvxsmq3p66af2nk83hs2p2u8n \
    -o multi.age notes.txt

With many keys, the line becomes unreadable. It's better to keep the public keys in a file and use -R (uppercase).

To build that file from your own key, use age-keygen -y, which prints the public key of a private key (section 1). >> appends to the end of the file, so run it once per key, with a comment above to say whose it is (a single > would replace the file, which only works for the first key):

bash
echo "# David (laptop)" >> ~/.config/age/recipients.txt
age-keygen -y ~/.config/age/key.txt >> ~/.config/age/recipients.txt

For someone else's key, they send you their age1... line (it's public) and you append it the same way. An SSH public key (the line from a .pub file) also works (section 6). The result:

bash
cat ~/.config/age/recipients.txt
output
# David (laptop)
age1ydslw3ud3lhduft004quqne7qtyqjt3df7wj6dw5puurfqayzymq8u6zg4

# Backup server
age18cmdfem3afacqvmmaqajevjykjwqjvqh4rvxsmq3p66af2nk83hs2p2u8n
bash
age -R ~/.config/age/recipients.txt -o multi.age notes.txt

Empty lines and lines starting with # are ignored, so you can document whose key is whose. This file only contains public keys: it can go into git without any problem.

What changes in the file

The header now has two envelopes, one per key, both containing the same file key:

text
age-encryption.org/v1
-> X25519 CEWWVmjfNsH6CV2r8mo41d9yWWthHXgtjdfYfmjxuW0     <- envelope 1
XJLtj5tF6HfQetjxYo5aLY9xoiWVE6IdEngR/enCeLY
-> X25519 +tqbJAovTLWwj0tRCVw3e8ppTkAPHlOb0Z6VQIMGBEE     <- envelope 2
LsG4O64UFy26E208VtQLOO8IdgBwlTyb7ilYfi4IKwc
--- sqKMheXQyjVDCDUAZrb6h1Ier1sSej4Yft5yy72mm+s

The content is encrypted only once. Each extra recipient costs only about 100 bytes of header, regardless of file size: the 44-byte file went from 244 to 342 bytes.

When opening, each person uses their own key and age tries the envelopes until it finds theirs:

bash
age -d -i server-key.txt multi.age
output
Wifi password: banana123
Safe box PIN: 4271

This is the mechanism behind a backup strategy with a recovery key: always encrypt to your everyday key and to a key stored offline.

The flip side: removing a key from recipients.txt only affects the files you create from then on. Files that already exist keep their envelope for that key (section 12).

5. Whole folders with tar and pipes

age encrypts a stream of bytes, not folders. For a folder, bundle everything with tar and pass the result straight to age through a pipe (|):

bash
tar czf - ~/Documents | age -R ~/.config/age/recipients.txt > documents.tar.gz.age

Reading left to right:

  1. tar czf - ~/Documents packs (c), compresses with gzip (z) and writes to the file -, which means standard output.
  2. | connects that output to age's input.
  3. age -R ... encrypts whatever arrives, without knowing or caring that it's a tar.
  4. > writes the result to disk.

Why a pipe and not two steps? If you ran tar czf docs.tar.gz and then age docs.tar.gz, a complete, readable copy of your documents would be written to disk, even if only for a few seconds. On an SSD, deleting it afterwards doesn't guarantee the data is gone. With a pipe, the plaintext only ever exists in memory.

Another advantage: age processes data in 64 KiB chunks, so a 50 GB folder doesn't need to fit in memory.

Restoring

The reverse path: age decrypts and hands it over to tar to extract.

bash
age -d -i ~/.config/age/key.txt documents.tar.gz.age | tar xzvf -
output
Documents/
Documents/notes.txt
Documents/contract.pdf

tar's v lists each extracted file. To just see what's in the backup without extracting, swap x for t:

bash
age -d -i ~/.config/age/key.txt documents.tar.gz.age | tar tzf -

This same pattern works with anything that writes to standard output: pg_dump, mysqldump, docker save, zfs send. For example, a database dump encrypted on the fly:

bash
pg_dump my_database | age -R recipients.txt > db-$(date +%F).sql.age

6. Using the SSH keys you already have

If you already have an SSH key, age accepts it in place of an age key. The public key encrypts, the private key opens:

bash
age -R ~/.ssh/id_ed25519.pub -o ssh.age notes.txt
age -d -i ~/.ssh/id_ed25519 ssh.age
output
Wifi password: banana123
Safe box PIN: 4271

Notice I used -R with the .pub file: it's treated as a recipients file with one line. With -r, you'd pass the key contents in quotes.

If your SSH private key has a passphrase, age asks for it when opening. ssh-agent is not supported.

Sending something to someone via GitHub

GitHub publishes any user's SSH keys at github.com/<username>.keys. Combine that with -R - (read recipients from standard input):

bash
curl -s https://github.com/username.keys | age -R - report.pdf > report.pdf.age

The file comes out encrypted to every key the person has registered, and any one of them can open it.

What changes in the file, and why it matters

text
age-encryption.org/v1
-> ssh-ed25519 nQeBCQ VG6b+02qyQ27wq/sBjnKf8UA6eQxkH/ScBHfnrQbDiQ
2CSuE4Z+V0OhaekPTwgePe1EYcocZNk4tkkNuq9D8Hk
--- Js2SddA8dlfpSoncdyCEgVtKn9jgPyMaK7bzZrYs8no

nQeBCQ is a tag derived from the public key. It helps age find the right envelope quickly, but it has a side effect: I encrypted another file to the same key and the tag repeated (nQeBCQ again). Anyone holding several of your files can tell they were all encrypted to the same key, and anyone who knows your public key (which is on GitHub) can link them to you. This doesn't happen with age1... keys.

When to use SSH: to send something one-off to someone who only has an SSH key. When to avoid it: for long-term file storage, because SSH keys are often rotated or discarded without anyone remembering that files depended on them, and SSH keys on a YubiKey can't be used to decrypt.

7. Text format (armor)

A regular .age file is binary, which breaks if you paste it into a chat, an email or a YAML file. The -a (armor) option produces the same thing encoded as text:

bash
echo "token=abc123" | age -a -r age1ydslw3ud3lhduft004quqne7qtyqjt3df7wj6dw5puurfqayzymq8u6zg4
output
-----BEGIN AGE ENCRYPTED FILE-----
YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBHaEhydE42Tm1WY2d6S1E3
eTdEVnNZYmxtZ21CZkkvT1FtQk9sakl6YkhzCnpNcUMwOTNYc0lBV2tXNUVaWVht
eVRTN05ONHJlWXQ1ZndlN0p6RzN2SjQKLS0tIFMyUHNlLytKeUVzNzA3OUhGQWFK
U1N5dVU1aXVCWStlTEJhSUtwdmkrRlUKEkPt/tHuycOo+rAklxObxTCOogCoBydR
blr/KSzvZsDBT76g+zMLQ9q1ATGs
-----END AGE ENCRYPTED FILE-----

What happened: it's the same file as before, just run through Base64 and wrapped between the BEGIN and END lines (PEM format, the same as TLS certificates). If you decode the Base64, you'll find the age-encryption.org/v1 header inside. The size grows by about 33%.

To open it, you don't need to say it's armored: age detects it on its own.

bash
age -d -i ~/.config/age/key.txt << 'EOF'
-----BEGIN AGE ENCRYPTED FILE-----
YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBHaEhydE42Tm1WY2d6S1E3
...
-----END AGE ENCRYPTED FILE-----
EOF
output
token=abc123

<< 'EOF' is a heredoc: everything up to the EOF line becomes the command's input. It's a practical way to paste a block you received in a chat straight into the terminal.

When to use it: secrets in versioned config files, chat messages, text fields in a database. When not to: large files, because binary is smaller and faster.

Secrets in git: sops

For config files in a repository, the usual tool is sops, which uses age underneath. You declare who can read in a .sops.yaml:

yaml
creation_rules:
  - age: age1kayung4jcqqar5m50l82jyd87zmkdz24fh7mcgqnwl963vmx696q79xdjk
bash
sops encrypt --in-place secrets.yaml
cat secrets.yaml
output
database:
    user: ENC[AES256_GCM,data:+Cbo,iv:jewOHvfShqtXjrFDgWXfo4Ox/wFlWjPjgzu9SJWe1tU=,tag:yc4HU9+iKEGCVGspYTf8HQ==,type:str]
    password: ENC[AES256_GCM,data:BWALoqm5pg==,iv:UAyb4utFNLIdabUru/JQwzvs3lxm9J/NE5WVZbvIg9A=,tag:MWn1rA5pcd5Us0je9X1+9g==,type:str]
sops:
    age:
        - enc: |
            -----BEGIN AGE ENCRYPTED FILE-----
            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBjVElXdWtLbzFrNEUxRlp2
            ...
            -----END AGE ENCRYPTED FILE-----
          recipient: age1kayung4jcqqar5m50l82jyd87zmkdz24fh7mcgqnwl963vmx696q79xdjk

(Trimmed.) It's the envelope from section 2 again: sops encrypts the values with its own key and locks that key with age, in armor format. Only the values are encrypted: the names (database, user, password) stay readable, so git diffs still show what changed. That's convenient, and it's also metadata (section 11).

To read it:

bash
SOPS_AGE_KEY_FILE=~/.config/age/key.txt sops decrypt secrets.yaml
output
database:
    user: app
    password: hunter2

8. Protecting your own private key with a passphrase

key.txt is plain text: whoever copies the file can use the key. If the key will live somewhere less trustworthy (a USB stick, the cloud, a shared server), you can lock it with a passphrase using age itself:

bash
age-keygen | age -p -o ~/.config/age/key.age
output
Public key: age1va6rkr2j3klf7qewphexy37wcy3ndnmkrnr2wnghv2yr5kvdwalspmex6j
Enter passphrase (leave empty to autogenerate a secure one):
Confirm passphrase:

What happened: age-keygen without -o sent the new key to standard output, and the pipe handed it straight to age -p, which encrypted it with a passphrase. The plaintext key never touched the disk. The public key shows up on screen (age-keygen prints it separately, on stderr): write it down, because recovering it later will require the passphrase.

The resulting file is a regular .age with an scrypt stanza:

text
age-encryption.org/v1
-> scrypt sa5OxAPP8cKFzORwhMpNMQ 18
JHJelDmEZGXtmSrJQJmJgsIrauj9WPd90jGiGm50CmM

Using it

Pass key.age to -i as if it were a key.txt. age notices it's encrypted and asks for the passphrase:

bash
age -d -i ~/.config/age/key.age file.age
output
Enter passphrase for identity file "key.age":
hi

Is it worth it? For your everyday key on a laptop with an encrypted disk, usually not: anyone who can read the file is already inside your session and can capture the passphrase too. It's worth it for backup copies of the key, which sit outside your direct control. It's the recommended way to keep the recovery key on a USB stick.

9. Post-quantum keys

Since v1.3.0, age generates keys that resist a future quantum computer. The risk they cover is someone storing your files today and breaking them 10 or 20 years from now.

bash
age-keygen -pq -o ~/.config/age/key-pq.txt
age-keygen -y ~/.config/age/key-pq.txt > recipient-pq.txt
output
Public key: age1pq1hetmtqfse3la3nges4v4x5zu4qzj3t5fhmxeyfg6tsh4mz5ymtu9dj7tf2mv2ul...

The real output is 1,959 characters on a single line (I cut it here). That's the main annoyance: the public key of the post-quantum algorithm ML-KEM is big. That's why the recommended flow is to save the public key to a file and use -R, instead of pasting it with -r.

The private key, on the other hand, stays short (AGE-SECRET-KEY-PQ-1...), because it's just a seed the keys are derived from.

Using them

Exactly as before:

bash
age -R recipient-pq.txt -o pq.age notes.txt
age -d -i ~/.config/age/key-pq.txt pq.age

The header now has the mlkem768x25519 stanza, the hybrid of ML-KEM-768 (post-quantum, standardized by NIST) and X25519 (classic). To break it, an attacker has to defeat both.

text
age-encryption.org/v1
-> mlkem768x25519 1GfS0gGndg60MDBCj2Ejhb7MXTmGCfzBJsJCR3UCs7aqMuHl/0A/FqWcUdH4cXG/...

Costs and restrictions

  • Size: the header went from 168 to 1,627 bytes. Irrelevant for a multi-gigabyte backup, noticeable for a thousand small files.
  • Doesn't mix with classic keys:
output
age: error: incompatible recipients: can't mix post-quantum and classic recipients, or the file would be vulnerable to quantum computers

That makes sense: if one of the keys were classic, the quantum attacker would simply open that envelope. If you want a recovery key, it also has to be -pq.

  • Passphrases are already post-quantum: files encrypted with -p use only symmetric cryptography, which quantum computers can't practically break. age-inspect confirms this (next section).
  • Version: the age 1.1.x from Ubuntu's repository doesn't understand these keys. Whoever opens the file needs v1.3.0+, or the age-plugin-pq binary installed.

10. Inspecting without opening

age-inspect (v1.3.0+) reads only the header and tells you what can be known without the key. Useful for answering "what kind of key did I lock that 2024 backup with?".

bash
age-inspect multi.age
output
multi.age is an age file, version "age-encryption.org/v1".

This file is encrypted to the following recipient types:
  - "X25519"
  - "X25519"

This file does NOT use post-quantum encryption.

Size breakdown (assuming it decrypts successfully):

    Header                       266 bytes
    Encryption overhead           32 bytes
    Payload                       44 bytes
                        -------------------
    Total                        342 bytes

Tip: for machine-readable output, use --json.

Reading the result:

  • Recipient types: one item per envelope. Two X25519 = encrypted to two age keys. Note that it shows the type, but not which key: that information doesn't exist in the file.
  • Post-quantum: whether the file resists a quantum computer.
  • Size breakdown: header, overhead (16 bytes of nonce + 16 of authentication per 64 KiB chunk) and the size of the original content. You can learn the exact plaintext size without opening it.

Comparing the files created in this guide:

FileRecipient typePost-quantumHeader
notes.txt.ageX25519No168 bytes
multi.ageX25519, X25519No266 bytes
secret.agescryptYes150 bytes
pq.agemlkem768x25519Yes1,627 bytes

For scripts, --json returns the same thing in structured form:

bash
age-inspect --json notes.txt.age
json
{
    "version": "age-encryption.org/v1",
    "postquantum": "no",
    "armor": false,
    "stanza_types": ["X25519"],
    "sizes": {"header": 168, "overhead": 32, "min_payload": 44, "max_payload": 44}
}

(Trimmed JSON; the real one also includes armor and padding fields.) One use case: scan the backups folder and list which files still aren't post-quantum.

bash
for f in backups/*.age; do
  age-inspect --json "$f" | grep -q '"postquantum": "no"' && echo "$f"
done

11. What an encrypted file still reveals

age hides the content, not everything around it:

bash
ls -l resignation-letter.txt.age
age-inspect resignation-letter.txt.age
output
-rw-rw-r-- 1 david david 238 Oct  1 18:47 resignation-letter.txt.age

Size breakdown (assuming it decrypts successfully):

    Header                       168 bytes
    Encryption overhead           32 bytes
    Payload                       38 bytes
                        -------------------
    Total                        238 bytes

(age-inspect output trimmed.)

  • The name: age doesn't touch it. resignation-letter.txt.age says plenty without being opened.
  • The exact size: the payload is exactly the 38 bytes of the original text, because age adds no padding ("max_padding": 0 in --json). For short, predictable content (a yes or no, a PIN, one of a few known documents), the size alone can give it away.
  • Dates and owner: the usual filesystem metadata, like any other file.
  • Who it's for, sometimes: age keys leave no trace in the header, but SSH keys leave a tag (section 6), and so do hardware keys (section 13).

When that matters, encrypt a bundle instead of individual files: tar plus age (section 5) leaves a single file with a neutral name, and the names, sizes and number of the files inside only show up after decrypting.

12. When a key leaks

age has no revocation. Each file keeps in its header an envelope for every key it was encrypted to, forever. If a private key leaks, every file ever encrypted to it can be opened, old backups included.

Taking the key out of recipients.txt doesn't change files that already exist. Here, a secret encrypted to two keys (a laptop and an old server), after the server's key leaked and was removed from the list:

bash
cat recipients.txt
age -d -i old-server.txt secrets.age
output
# laptop
age14smdf4csaq89p6740gykhwsrn8gsl5zxprswsczsl8gj5zvsxckqensy50
db password: hunter2

The fix is to re-encrypt to the current list. Do it through a pipe, so the plaintext never touches the disk:

bash
age -d -i laptop.txt secrets.age | age -R recipients.txt -o secrets.age.new && mv secrets.age.new secrets.age
age -d -i old-server.txt secrets.age
output
age: error: no identity matched any of the recipients

The && only replaces the file if the re-encryption worked.

Re-encrypting only protects the copies you control. Any copy made earlier (a backup somewhere else, a file already in someone else's hands) still opens with the leaked key. So, in practice:

  1. Generate a new key and update recipients.txt.
  2. Re-encrypt the files you control.
  3. Change the secrets themselves (passwords, tokens) that were inside files the old key could open. Assume they've been read.

13. Hardware keys and plugins

So far the private key is a line of text in a file: whoever copies the file has the key. Hardware keys, such as a YubiKey, keep it inside a chip it can't leave, and decrypting needs the device plugged in. age supports them through plugins: separate programs named age-plugin-<name> that age finds in your PATH and calls when it sees a key of their type.

Setting one up is covered in Hardware keys for age: YubiKey and plugins.

Two things matter for the rest of this guide:

  • Losing the device means losing the key, so always encrypt to a second key too, like the paper recovery key from section 14.
  • Hardware keys leave a tag, like SSH keys (section 6): whoever has the public key can tell a file was addressed to it.

14. Backing up your key, and testing the restore

The checklist at the end asks for a key backup and a restore test. Here's how to do both.

On paper

The private key is a single line, and that line is the whole backup:

bash
grep -v '^#' ~/.config/age/key.txt
output
AGE-SECRET-KEY-1WQ3AZLFDJMCPFR6YKKRD9VSD638GWR5V0T9G6WN8Q5VNTD9GL5SQMVX4VR

Print it or write it down by hand, and keep it outside your home. Copying it by hand is safer than it looks, thanks to Bech32 (section 1): after the prefix, the alphabet leaves out characters that are easy to confuse (1, b, i and o), and the checksum catches typos. With one wrong character:

output
age: error: reading "typo-key.txt": failed to read "typo-key.txt": error at line 1: malformed secret key: invalid checksum

One trap: type it back in uppercase. In lowercase, age doesn't recognize it:

output
age: error: reading "lower-key.txt": failed to read "lower-key.txt": error at line 1: unknown identity type

If you'd rather scan than type, PaperAge is a tool made for paper backups of secrets.

The restore test

A backup you've never restored is a hope, not a backup. Test it with only what you'd have after losing the laptop: the recovery key from the paper. Type it into a new file and open the backup:

bash
mkdir restore-test && cd restore-test
nano key-from-paper.txt   # the line from the paper
age -d -i key-from-paper.txt ../documents.tar.gz.age | tar xzf -

Then compare with the originals, byte for byte:

bash
(cd .. && sha256sum Documents/*) > ../original.sha
sha256sum -c ../original.sha
output
Documents/contract.pdf: OK
Documents/notes.txt: OK

When you're done, delete restore-test: key-from-paper.txt is your private key in plain text.

Deleting the original

After encrypting, the original is still there in plain text (section 2), and rm only removes the name: the data stays on disk until something overwrites it. The classic tool is shred, but its own documentation warns that it relies on the filesystem overwriting data in place, which journaling, RAID, snapshots and compressed filesystems don't guarantee (copy-on-write ones like btrfs and ZFS neither). On an SSD, the drive itself decides where each write lands, so overwriting a file usually fills new cells and leaves the old ones intact. And a backup or snapshot may already hold a copy.

What works in practice:

  1. Full-disk encryption (LUKS on Linux): whatever stays on the disk is unreadable anyway. This is the real protection.
  2. Pipes (section 5): plaintext that never touches the disk never needs deleting.
  3. Then a plain rm on the original.

15. Day-to-day shortcuts

Typing -R, -i and paths every time gets old. Put this at the end of your ~/.bashrc (or ~/.zshrc):

bash
# --- age ---
export AGE_KEY="$HOME/.config/age/key.txt"
export AGE_RECIPIENTS="$HOME/.config/age/recipients.txt"

# enc file1 file2 ...  -> creates file1.age, file2.age
enc() {
  for f in "$@"; do
    age -R "$AGE_RECIPIENTS" -o "$f.age" "$f" && echo "locked: $f.age"
  done
}

# dec file1.age ...  -> recreates file1
dec() {
  for f in "$@"; do
    [[ "$f" == *.age ]] || { echo "skipped (not .age): $f" >&2; continue; }
    age -d -i "$AGE_KEY" -o "${f%.age}" "$f" && echo "opened: ${f%.age}"
  done
}

# view file.age  -> shows the content without writing to disk
view() { age -d -i "$AGE_KEY" "$1"; }

# encdir folder  -> creates folder.tar.gz.age via pipe
encdir() {
  tar czf - "$1" | age -R "$AGE_RECIPIENTS" > "${1%/}.tar.gz.age" && echo "locked: ${1%/}.tar.gz.age"
}

Reload with source ~/.bashrc and try it:

bash
enc a.txt b.txt
rm a.txt
dec a.txt.age b.txt
view a.txt.age
encdir Documents/
output
locked: a.txt.age
locked: b.txt.age
opened: a.txt
skipped (not .age): b.txt
a
locked: Documents.tar.gz.age

${f%.age} is a bash expansion that strips the .age suffix from the name. The check in dec keeps you from overwriting a file by mistake when you pass the wrong name. Since enc uses recipients.txt, everything you lock is also encrypted to the recovery key, if it's listed there.

Summary

I want to...Command
Generate a keyage-keygen -o key.txt
See my public keyage-keygen -y key.txt
Encrypt for myselfage -R recipients.txt -o x.age x
Encrypt with a passphraseage -p -o x.age x
Openage -d -i key.txt -o x x.age
Just read, without writingage -d -i key.txt x.age
Whole foldertar czf - folder | age -R recipients.txt > folder.tar.gz.age
Restore folderage -d -i key.txt folder.tar.gz.age | tar xzf -
Text to pasteage -a -r age1...
Passphrase-protected keyage-keygen | age -p -o key.age
Post-quantumage-keygen -pq -o key-pq.txt
Inspectage-inspect x.age
Signssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n file x.age
Check a signaturessh-keygen -Y verify -f allowed_signers -I email -n file -s x.age.sig < x.age
Re-encrypt after a key changeage -d -i key.txt x.age | age -R recipients.txt -o x.age.new

Before trusting your data to age, check:

  • Key in ~/.config/age/ with 600 permissions, on an encrypted disk
  • recipients.txt with your everyday key and a recovery key stored offline
  • Key backup on paper or a USB stick, outside your home (section 14)
  • Restore test done using only the backup (section 14)
  • Pipes instead of intermediate plaintext files
  • Originals deleted after encrypting, on an encrypted disk (section 14)
  • Signatures on files whose authorship matters
  • A plan for a leaked key: re-encrypt and change the secrets (section 12)

Sources