Day 1: age on its own
Goal: You generate age keys, encrypt files for one and for several recipients, also for SSH and post-quantum keys, and know what age cannot do. · Duration: approx. 60 min · Prerequisite: Day 0
Briefing
- age encrypts files. A key pair consists of the
identity (private,
AGE-SECRET-KEY-1…) and the recipient (public,age1…). - You encrypt for recipients and decrypt with an identity. Whoever has only the public key can encrypt but cannot read anything.
- age does exactly one thing: there are no signatures, no key servers, no configuration. SOPS (from Day 2 on) uses age as a key source.
- Today’s keys stay:
ich.key(“me”) is your key from Day 2 on,kollegin.keybelongs to your colleague on the team from Day 5 on.
Recipient age1… ──► age -r ──► datei.age ──► age -d -i ◄── Identity
(anyone may have it) (binary data) AGE-SECRET-KEY-1…
Drill 1: A key pair
# on argo
mkdir -p ~/sops/tag01 && cd ~/sops/tag01
age-keygen -o ich.key
ls -l ich.key
cut -c1-40 ich.key
age-keygen -y ich.keyExpected (abridged):
Public key: age126j96yd6te036uya83l76w0afmlaj9vyyluxrmdeheew3u0wzdmslw69y2
-rw------- 1 ubuntu ubuntu 184 Nov 20 16:13 ich.key
# created: 2026-11-20T16:13:21Z
# public key: age126j96yd6te036uya83l76w
AGE-SECRET-KEY-1FG9A49YMS9ESZV0DFC0LXT0T
age126j96yd6te036uya83l76w0afmlaj9vyyluxrmdeheew3u0wzdmslw69y2
The file contains a single line with the private key, preceded by two
comments. age-keygen creates it with 0600 and
never overwrites an existing file. -y derives the public
key from the identity – you do not need to write it down anywhere.
Warning: The book shows the private key only abridged. On your screen it appears in full – in real environments never in terminals that are recorded or shared.
Save your progress? Sign up for free
Drill 2: Encrypt for one recipient
# on argo
cd ~/sops/tag01
printf 'lab-db-123\n' > db.txt
age -r $(age-keygen -y ich.key) -o db.txt.age db.txt
ls -l db.txt db.txt.age
head -3 db.txt.age
age-inspect db.txt.age | head -9
age -d -i ich.key db.txt.ageExpected:
-rw-rw-r-- 1 ubuntu ubuntu 11 Nov 20 16:13 db.txt
-rw-rw-r-- 1 ubuntu ubuntu 211 Nov 20 16:13 db.txt.age
age-encryption.org/v1
-> X25519 nT2v71QVMBGrI8IH0+t9KWgrMcngJUqQ623rc++feT4
t9Qur/pN9/VDCkKZfnaMA2VtW4G4dzgKUHIOMgic+WM
db.txt.age is an age file, version "age-encryption.org/v1".
This file is encrypted to the following recipient types:
- "X25519"
This file does NOT use post-quantum encryption.
Size breakdown (assuming it decrypts successfully):
lab-db-123
Why 211 bytes for 11 bytes of content? The header (168 bytes) contains one stanza per recipient: the file key, encrypted for exactly this recipient. The public key itself is not in the file – whoever finds it cannot see whom it is meant for. Then comes the payload, encrypted with the file key (ChaCha20-Poly1305).
Save your progress? Sign up for free
Drill 3: Multiple recipients and ASCII armor
Your colleague gets her own key. A recipients file collects all public keys of the team.
# on argo
cd ~/sops/tag01
age-keygen -o kollegin.key
age-keygen -y ich.key > team.txt
age-keygen -y kollegin.key >> team.txt
cat team.txt
age -a -R team.txt -o db.txt.asc db.txt
head -2 db.txt.asc; tail -1 db.txt.asc
age-inspect db.txt.asc | sed -n '3,8p'
age -d -i kollegin.key db.txt.ascExpected:
Public key: age1yct8f7sq5lpdw2p09h0lmkz3ue65d669c99cnhz4zkzj9hkd7vaqxl7q5s
age126j96yd6te036uya83l76w0afmlaj9vyyluxrmdeheew3u0wzdmslw69y2
age1yct8f7sq5lpdw2p09h0lmkz3ue65d669c99cnhz4zkzj9hkd7vaqxl7q5s
-----BEGIN AGE ENCRYPTED FILE-----
YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSByUHhUTUZHM0JkMERXcEta
-----END AGE ENCRYPTED FILE-----
This file is ASCII-armored.
This file is encrypted to the following recipient types:
- "X25519"
- "X25519"
Two stanzas, one per recipient – each of the two can decrypt alone.
-a (armor) produces text instead of binary data, good for
e-mail, tickets or YAML. Empty lines and # comments are
allowed in the recipients file.
Save your progress? Sign up for free
Drill 4: The wrong key
Break it: A third key that was never a recipient.
# on argo
cd ~/sops/tag01
age-keygen -o fremd.key 2>/dev/nullSymptom:
# on argo
cd ~/sops/tag01
age -d -i fremd.key db.txt.age; echo "rc=$?"Expected:
age: error: no identity matched any of the recipients
age: report unexpected or unhelpful errors at https://filippo.io/age/report
rc=1
Cause: None of the given identities matches a stanza in the header. age cannot tell which key would have been needed – the file does not reveal its recipients.
Fix and verify: -i may appear several
times; age ignores identities that do not match.
# on argo
cd ~/sops/tag01
age -d -i fremd.key -i ich.key db.txt.ageExpected:
lab-db-123
You will see the same message again on Day 4 (Drill 3) – then wrapped in a sops message.
Save your progress? Sign up for free
Drill 5: An SSH key as recipient
Almost everyone already has an SSH key, and Git servers publish their
users’ public keys. age takes ssh-ed25519 and
ssh-rsa directly.
# on argo
cd ~/sops/tag01
ssh-keygen -q -t ed25519 -N '' -C lab-ssh -f lab_ssh
age -R lab_ssh.pub -o db.ssh.age db.txt
age-inspect db.ssh.age | sed -n '3,4p'
age -d -i lab_ssh db.ssh.ageExpected:
This file is encrypted to the following recipient types:
- "ssh-ed25519"
lab-db-123
Why? Convenient for a one-off handover (“send me the password, here is my GitHub key”). For teams with rotation, native age keys are better: an SSH key with a passphrase has to be unlocked for every decryption, and age cannot use SSH agents.
Save your progress? Sign up for free
Drill 6: Post-quantum keys
age 1.3 knows hybrid keys made of ML-KEM-768 and X25519
(-pq). They protect data encrypted today even against a
future quantum computer (“harvest now, decrypt later”).
# on argo
cd ~/sops/tag01
age-keygen -pq -o pq.key 2>&1 | cut -c1-60
age-keygen -y pq.key | wc -c
age -r $(age-keygen -y pq.key) -o db.pq.age db.txt
age-inspect db.pq.age | sed -n '3,6p'
ls -l db.pq.age
age -d -i pq.key db.pq.age
age -R team.txt -r $(age-keygen -y pq.key) db.txt 2>&1 >/dev/null | head -1Expected (line wrapped):
Public key: age1pq13rc8akjy9ccupy2ey9d9589yyktt3d9sprwn0yhse
1960
This file is encrypted to the following recipient types:
- "mlkem768x25519"
This file uses post-quantum encryption.
-rw-rw-r-- 1 ubuntu ubuntu 1670 Nov 20 16:13 db.pq.age
lab-db-123
age: error: incompatible recipients: can't mix post-quantum and classic recipients,
or the file would be vulnerable to quantum computers
The public key is almost 2000 characters long, and the file header is
correspondingly larger. age refuses to mix: a classic recipient would be
the weakest link. sops 3.13 accepts age1pq1… as well; the
book stays with the short X25519 keys so that the outputs remain
readable.
Save your progress? Sign up for free
Drill 7: Passphrases and protected identities
age -p encrypts with a passphrase (scrypt) and asks for
it on the terminal. For workflows without a terminal, age 1.3 ships the
plugin age-plugin-batchpass, which reads the passphrase
from AGE_PASSPHRASE. You can use it to protect an identity
file too:
# on argo
cd ~/sops/tag01
sudo install -m 0755 ~/sops/tag00/age/age-plugin-batchpass /usr/local/bin/
AGE_PASSPHRASE=lab-pass-123 age -e -j batchpass -o ich.key.age ich.key
age-inspect ich.key.age | sed -n '4p'
AGE_PASSPHRASE=lab-pass-123 age -d -j batchpass ich.key.age | age -d -i - db.txt.age
AGE_PASSPHRASE=falsch-123 age -d -j batchpass ich.key.age | head -1Expected:
- "scrypt"
lab-db-123
age: error: batchpass plugin: incorrect passphrase
age: report unexpected or unhelpful errors at https://filippo.io/age/report
-i - reads the identity from standard input – the
private key never lands unencrypted on disk. On a terminal it works
without the plugin: age -d -i ich.key.age db.txt.age
recognizes the passphrase-protected identity and asks for the
passphrase.
Tip: The help of
age-plugin-batchpasssays it itself: in 90 % of cases you do not need it. A machine that remembers a passphrase can just as well remember a real key.
Save your progress? Sign up for free
Exercise: Speed Drills
- Show the public key from
ich.keywithoutage-keygen. Target time: 10 s - Encrypt
db.txtas text for the whole team todb.team.asc. Target time: 20 s - Use
age-inspect --jsonto count how many recipientsdb.txt.ascis for. Target time: 30 s
Solution
# on argo
cd ~/sops/tag01
grep 'public key' ich.key
age -a -R team.txt -o db.team.asc db.txt && head -1 db.team.asc
age-inspect --json db.txt.asc | jq '.stanza_types | length'Expected:
# public key: age126j96yd6te036uya83l76w0afmlaj9vyyluxrmdeheew3u0wzdmslw69y2
-----BEGIN AGE ENCRYPTED FILE-----
2
Save your progress? Sign up for free
Checkpoint
# on argo
cd ~/sops/tag01
ls -1 ich.key kollegin.key team.txt
age -d -i ich.key db.txt.asc
age -d -i kollegin.key db.txt.ascExpected:
ich.key
kollegin.key
team.txt
lab-db-123
lab-db-123
Challenge
Pack a folder projekt with a file .env
(API_KEY=lab-key-123) and a notiz.txt into a
compressed archive, encrypt it for the team in one pass, and unpack it
as your colleague into a folder ziel – without an
unencrypted intermediate file.
Hint: age reads from standard input and writes to standard output.
Solution
# on argo
cd ~/sops/tag01
mkdir -p projekt && printf 'API_KEY=lab-key-123\n' > projekt/.env
printf 'x\n' > projekt/notiz.txt
tar -czf - projekt | age -R team.txt -o projekt.tar.gz.age
mkdir -p ziel && age -d -i kollegin.key projekt.tar.gz.age | tar -xzf - -C ziel
find ziel -type f | sort
cat ziel/projekt/.envExpected:
ziel/projekt/.env
ziel/projekt/notiz.txt
API_KEY=lab-key-123
Save your progress? Sign up for free
Cleanup
# on argo
cd ~/sops/tag01
rm -rf db.txt projekt ziel fremd.key
ls -1Expected:
db.pq.age
db.ssh.age
db.team.asc
db.txt.age
db.txt.asc
ich.key
ich.key.age
kollegin.key
lab_ssh
lab_ssh.pub
pq.key
projekt.tar.gz.age
team.txt
You need ich.key, kollegin.key and
team.txt from Day 2 on.
Interview Note
- What is the difference between recipient and identity? Recipient = public key for encrypting, identity = private key for decrypting. For each recipient, the header holds a stanza with the encrypted file key.
- age or GPG? age: small keys, no configuration, no web of trust, no signatures. GPG can sign and supports smartcards, but is hard to use correctly. For SOPS, age is the recommended standard today.
- Why post-quantum keys? Data captured today can be decrypted later; hybrid keys protect against that as long as one of the two parts holds.
Enterprise Note
- Private age keys belong in a password manager or on a hardware token (age plugins for YubiKey/TPM), not unprotected in the home directory.
- Recipients files are public and belong in the repo – they document who may read.
- age does not sign: anyone who knows a recipient can slip files to you. For proof of origin, sign additionally (cosign, minisign, signed commits).
- Encrypt long-term stored secrets (backups) with
-pq.