Skip to content
Hands-on IT IT Drills

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.key belongs 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.key

Expected (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.age

Expected:

-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.asc

Expected:

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/null

Symptom:

# 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.age

Expected:

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.age

Expected:

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 -1

Expected (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 -1

Expected:

  - "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-batchpass says 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

  1. Show the public key from ich.key without age-keygen. Target time: 10 s
  2. Encrypt db.txt as text for the whole team to db.team.asc. Target time: 20 s
  3. Use age-inspect --json to count how many recipients db.txt.asc is 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.asc

Expected:

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/.env

Expected:

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 -1

Expected:

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.