Day 5: Team – multiple recipients and rotation
Goal: You add a colleague to the team and remove her again, rotate the data key, change your own age key and know why the secret itself still has to be changed in the end. · Duration: approx. 75 min · Prerequisite: Day 4
Briefing
- Two levels: recipients (who can open the data key) and the data key (what the values are encrypted with).
sops updatekeysaligns a file’s recipients with.sops.yaml. The data key and allENC[…]values stay the same.sops rotategenerates a new data key and re-encrypts all values. With--add-age/--rm-ageit also changes recipients along the way – bypassing.sops.yaml.- Git forgets nothing: old commits stay readable for the old recipients.
| Event | Command | Is that enough? |
|---|---|---|
| New team member | .sops.yaml + updatekeys |
yes |
| Member leaves | .sops.yaml + updatekeys +
rotate |
no: change the secret |
| Own key renewed | new identity + updatekeys |
yes, old key gone |
Drill 1: Read as your colleague
Your colleague has had a key since Day 1 (kollegin.key).
To work “as your colleague” on the same VM, sops has to overlook your
key: it reads keys.txt under
$XDG_CONFIG_HOME/sops/age/ – if the variable points
nowhere, only SOPS_AGE_KEY_FILE remains.
# on argo
mkdir -p ~/sops/tag05 && cd ~/sops/repo
XDG_CONFIG_HOME=/nirgends SOPS_AGE_KEY_FILE=~/sops/tag01/kollegin.key \
sops decrypt dev/notes-db.yaml 2>&1 | sed -n '1p;4p'Expected:
Failed to get the data key required to decrypt the SOPS file.
age126j96yd6te036uya83l76w0afmlaj9vyyluxrmdeheew3u0wzdmslw69y2: FAILED
The file is encrypted only for you; your colleague’s key matches no recipient.
Save your progress? Sign up for free
Drill 2: Add your colleague
# on argo
cd ~/sops/repo
cp dev/notes-db.yaml ~/sops/tag05/vorher.yaml
K=$(age-keygen -y ~/sops/tag01/kollegin.key)
yq -i '(.creation_rules[] | select(.path_regex == "^dev/.*\\.yaml$") | .age)
+= ",'$K'"' .sops.yaml
yq '.creation_rules[1].age' .sops.yaml | tr ',' '\n'
sops updatekeys dev/notes-db.yaml </dev/null; echo "rc=$?"Expected (abridged):
age126j96yd6te036uya83l76w0afmlaj9vyyluxrmdeheew3u0wzdmslw69y2
age1yct8f7sq5lpdw2p09h0lmkz3ue65d669c99cnhz4zkzj9hkd7vaqxl7q5s
The following changes will be made to the file's groups:
Group 1
age126j96yd6te036uya83l76w0afmlaj9vyyluxrmdeheew3u0wzdmslw69y2
+++ age1yct8f7sq5lpdw2p09h0lmkz3ue65d669c99cnhz4zkzj9hkd7vaqxl7q5s
Is this okay? (y/n):rc=1
EOF
updatekeys first shows what it intends to do
(+++ new, --- gone) and asks. Without an
answer (here: empty input, hence EOF) nothing happens. With
-y it proceeds without asking:
# on argo
cd ~/sops/repo
sops updatekeys -y dev/notes-db.yaml 2>&1 | grep -v Syncing
yq '.sops.age[].recipient' dev/notes-db.yaml
XDG_CONFIG_HOME=/nirgends SOPS_AGE_KEY_FILE=~/sops/tag01/kollegin.key \
sops decrypt --extract '["data"]["password"]' dev/notes-db.yaml | base64 -d; echoExpected (abridged):
The following changes will be made to the file's groups:
Group 1
age126j96yd6te036uya83l76w0afmlaj9vyyluxrmdeheew3u0wzdmslw69y2
+++ age1yct8f7sq5lpdw2p09h0lmkz3ue65d669c99cnhz4zkzj9hkd7vaqxl7q5s
2026/11/20 16:25:29 File /home/ubuntu/sops/repo/dev/notes-db.yaml synced with new keys
age126j96yd6te036uya83l76w0afmlaj9vyyluxrmdeheew3u0wzdmslw69y2
age1yct8f7sq5lpdw2p09h0lmkz3ue65d669c99cnhz4zkzj9hkd7vaqxl7q5s
lab-db-dev-123
For updatekeys you need access yourself: sops opens the
data key with your identity and additionally encrypts it for your
colleague.
Save your progress? Sign up for free
Drill 3: What updatekeys does not touch
# on argo
cd ~/sops/repo
diff <(yq '.data' ~/sops/tag05/vorher.yaml) <(yq '.data' dev/notes-db.yaml) \
&& echo "data unverändert"
sops updatekeys -y dev/notes-db.yaml 2>&1 | cut -c21-
sops updatekeys -y dev/app.env 2>&1 | cut -c21-
git diff --stat
git commit -qam "tag05: Kollegin für dev" && git push -qExpected (data unverändert means “data
unchanged”):
data unverändert
Syncing keys for file /home/ubuntu/sops/repo/dev/notes-db.yaml
File /home/ubuntu/sops/repo/dev/notes-db.yaml already up to date
Syncing keys for file /home/ubuntu/sops/repo/dev/app.env
File /home/ubuntu/sops/repo/dev/app.env already up to date
.sops.yaml | 2 +-
dev/notes-db.yaml | 19 ++++++++++++++-----
2 files changed, 15 insertions(+), 6 deletions(-)
The values stay byte for byte the same; only one age
entry is added. dev/app.env is “up to date” because the
dotenv rule does not name your colleague – updatekeys
follows the rule that matches the path.
Save your progress? Sign up for free
Drill 4: Your colleague leaves
# on argo
cd ~/sops/repo
ICH=$(age-keygen -y ~/.config/sops/age/keys.txt)
yq -i '(.creation_rules[] | select(.path_regex == "^dev/.*\\.yaml$") | .age)
= "'$ICH'"' .sops.yaml
sops updatekeys -y dev/notes-db.yaml 2>&1 | grep -E '^(---|\+\+\+)'
XDG_CONFIG_HOME=/nirgends SOPS_AGE_KEY_FILE=~/sops/tag01/kollegin.key \
sops decrypt dev/notes-db.yaml 2>&1 | head -1Expected:
--- age1yct8f7sq5lpdw2p09h0lmkz3ue65d669c99cnhz4zkzj9hkd7vaqxl7q5s
Failed to get the data key required to decrypt the SOPS file.
Done? No. Your colleague has cloned the repo:
# on argo
cd ~/sops/repo
git show HEAD:dev/notes-db.yaml > ~/sops/tag05/alt.yaml
XDG_CONFIG_HOME=/nirgends SOPS_AGE_KEY_FILE=~/sops/tag01/kollegin.key \
sops decrypt --extract '["data"]["password"]' ~/sops/tag05/alt.yaml | base64 -d
echo
diff <(yq '.data' ~/sops/tag05/alt.yaml) <(yq '.data' dev/notes-db.yaml) \
&& echo "data unverändert"Expected:
lab-db-dev-123
data unverändert
Two leaks: the last commit is still encrypted for her, and the
current ENC[…] values are encrypted with the same
data key that she knows from the old state. With it she could
read every future change that sops makes with this data key.
Save your progress? Sign up for free
Drill 5: Rotate the data key
# on argo
cd ~/sops/repo
sops rotate -i dev/notes-db.yaml; echo "rc=$?"
diff <(yq '.data' ~/sops/tag05/alt.yaml) <(yq '.data' dev/notes-db.yaml) \
>/dev/null || echo "data neu verschlüsselt"
sops decrypt --extract '["data"]["password"]' dev/notes-db.yaml | base64 -d; echo
git commit -qam "tag05: Kollegin raus, Datenschlüssel rotiert" && git push -qExpected (data neu verschlüsselt means
“data re-encrypted”):
rc=0
data neu verschlüsselt
lab-db-dev-123
Now the old data key no longer helps her with future states. But she
knows the password lab-db-dev-123 – from the old commit. No
tool can take that back: the secret itself has to be changed
(Challenge).
Save your progress? Sign up for free
Drill 6: rotate bypassing the rules
sops rotate --add-age adds a recipient directly to the
file – handy for emergency access, but .sops.yaml knows
nothing about it.
# on argo
cd ~/sops/repo
ICH=$(age-keygen -y ~/.config/sops/age/keys.txt)
SOPS_AGE_KEY_FILE=~/sops/tag04/prod.key sops rotate -i --add-age $ICH \
prod/notes-db.yaml
yq '.sops.age[].recipient' prod/notes-db.yaml
sops decrypt prod/notes-db.yaml | yq .data.password | base64 -d; echo
SOPS_AGE_KEY_FILE=~/sops/tag04/prod.key sops updatekeys -y prod/notes-db.yaml \
2>&1 | grep -E '^(---|\+\+\+)'
yq '.sops.age[].recipient' prod/notes-db.yaml
git checkout prod/notes-db.yamlExpected:
age1r025nv6kv083tjhqa7xpslvkc0m8qm2jljd0aqn55nzr859xqe7q4798ks
age126j96yd6te036uya83l76w0afmlaj9vyyluxrmdeheew3u0wzdmslw69y2
lab-db-prod-123
--- age126j96yd6te036uya83l76w0afmlaj9vyyluxrmdeheew3u0wzdmslw69y2
age1r025nv6kv083tjhqa7xpslvkc0m8qm2jljd0aqn55nzr859xqe7q4798ks
Updated 1 path from the index
The next updatekeys takes the access away again.
Remember: the truth about recipients lives in .sops.yaml;
exceptions in individual files do not last.
Save your progress? Sign up for free
Drill 7: Change your own key
Your laptop is replaced or the key is a year old: new key, re-encrypt
all files, old key gone. During the change both identities are in
keys.txt – one file may contain several.
# on argo
cd ~/sops/repo
ALT=$(age-keygen -y ~/sops/tag01/ich.key)
age-keygen -o ~/sops/tag05/ich-2026.key
NEU=$(age-keygen -y ~/sops/tag05/ich-2026.key)
cat ~/sops/tag05/ich-2026.key >> ~/.config/sops/age/keys.txt
grep -c AGE-SECRET ~/.config/sops/age/keys.txt
sed -i "s/$ALT/$NEU/g" .sops.yaml
grep -c $NEU .sops.yaml
for f in notes/app.enc.yaml dev/notes-db.yaml dev/app.env; do
sops updatekeys -y $f 2>&1 | grep -E 'synced|up to date' | cut -c21-; done
grep -rl --exclude-dir=.git $ALT . ; echo "alter Schlüssel noch in Dateien: $?"Expected
(alter Schlüssel noch in Dateien means “old key still in
files”):
Public key: age1rnz4tqupd0f3lm4kfs564cfgys5j80497rk7ajzn2ekxh3d2g3uqdtdnv2
2
3
File /home/ubuntu/sops/repo/notes/app.enc.yaml synced with new keys
File /home/ubuntu/sops/repo/dev/notes-db.yaml synced with new keys
File /home/ubuntu/sops/repo/dev/app.env synced with new keys
alter Schlüssel noch in Dateien: 1
grep exits with 1: no file names the old key any more.
Now it goes out of keys.txt:
# on argo
cd ~/sops/repo
cp ~/sops/tag05/ich-2026.key ~/.config/sops/age/keys.txt
for f in notes/app.enc.yaml dev/notes-db.yaml dev/app.env; do
sops decrypt $f >/dev/null && echo "$f ok"; done
git add -A && git commit -qm "tag05: eigener Schlüssel gewechselt" && git push -q
git log --oneline | head -3Expected:
notes/app.enc.yaml ok
dev/notes-db.yaml ok
dev/app.env ok
83a0c0a tag05: eigener Schlüssel gewechselt
ca110ea tag05: Kollegin raus, Datenschlüssel rotiert
3a19232 tag05: Kollegin für dev
From now on age1rnz4… is your key;
~/sops/tag01/ich.key is the old one. A data key change is
not needed here – only you had the old key.
Save your progress? Sign up for free
Exercise: Speed Drills
- Count which recipients the three dev and notes files are encrypted for. Target time: 30 s
- List all recipients from
.sops.yaml, each once. Target time: 30 s
Solution
# on argo
cd ~/sops/repo
yq '.sops.age[].recipient' dev/notes-db.yaml notes/app.enc.yaml | grep age1 \
| sort | uniq -c
grep recipient dev/app.env | cut -c1-50
yq '.creation_rules[].age' .sops.yaml | tr ',' '\n' | sort -uExpected:
2 age1rnz4tqupd0f3lm4kfs564cfgys5j80497rk7ajzn2ekxh3d2g3uqdtdnv2
sops_age__list_0__map_recipient=age1rnz4tqupd0f3lm
age1r025nv6kv083tjhqa7xpslvkc0m8qm2jljd0aqn55nzr859xqe7q4798ks
age1rnz4tqupd0f3lm4kfs564cfgys5j80497rk7ajzn2ekxh3d2g3uqdtdnv2
yq does not read dotenv files – grep helps
there.
Save your progress? Sign up for free
Checkpoint
# on argo
cd ~/sops/repo && git status -sb
grep -c AGE-SECRET ~/.config/sops/age/keys.txt
age-keygen -y ~/.config/sops/age/keys.txtExpected:
## main...origin/main
1
age1rnz4tqupd0f3lm4kfs564cfgys5j80497rk7ajzn2ekxh3d2g3uqdtdnv2
Challenge
Your colleague knows lab-db-dev-123. Change the dev
password to lab-db-dev-456 without a plaintext file, commit
and push. How many commits in the history of
dev/notes-db.yaml still contain states that encrypt the old
password?
Hint: data expects base64 – and
sops set expects JSON.
Solution
# on argo
cd ~/sops/repo
sops set dev/notes-db.yaml '["data"]["password"]' \
"\"$(printf lab-db-dev-456 | base64)\""
sops decrypt --extract '["data"]["password"]' dev/notes-db.yaml | base64 -d; echo
git commit -qam "tag05: dev-Passwort gewechselt" && git push -q
git log --oneline -- dev/notes-db.yaml | wc -lExpected:
lab-db-dev-456
5
Four of the five states contain the old password – that is fine because it is now invalid (in real life: changed in the database). Rewriting history is rarely necessary; changing secrets always is.
Save your progress? Sign up for free
Interview Note
- A developer leaves the team – what do you do? Remove the
recipient from
.sops.yaml, runupdatekeys,rotatefor a new data key – and above all change every secret they could ever read. The Git history stays readable. - Difference between
updatekeysandrotate?updatekeysonly changes whom the data key is encrypted for;rotategenerates a new data key and re-encrypts all values.
Enterprise Note
- One group per team in
.sops.yaml, changes only via review; an offboarding runbook withupdatekeys+rotate+ secret change. - Instead of many personal keys: a KMS or OpenBao Transit (Day 7), access via groups in the identity system – then offboarding is a group change.
- Plan key changes (e.g. yearly) and destroy old identities afterwards.
- Check
updatekeysacross the whole repo in CI: a file whose recipients differ from.sops.yamlis a finding.