Rotation & multi-recipient

Many keys; rotate without downtime.

Intermediate12 min · lesson 7 of 12

A secret file can be encrypted to multiple recipients at once — several age keys, several KMS keys, a mix — and any one of them can decrypt it. This is how teams and automation share access: encrypt to each engineer’s key and the CI/cluster key, and everyone who needs it can decrypt with their own key, no shared secret. Adding or removing a recipient re-encrypts the data key for the new set without changing the secret values.

terminal

# add a new recipient (e.g. a new team member or a CI key) to an existing file
$ sops updatekeys secrets.enc.yaml     # re-encrypts the data key to the current .sops.yaml recipients
# or rotate the data key entirely (new data key, values re-encrypted):
$ sops -r -i secrets.enc.yaml

Rotation without re-sharing

Two rotations matter. Rotating recipients (add/remove keys) handles people and systems joining or leaving — remove a departing engineer’s key and run updatekeys so they can no longer decrypt new versions. Rotating the data key (-r) generates a fresh encryption key for the file, which you do periodically or after a suspected exposure. Because SOPS separates the per-file data key from the recipient keys, both rotations are cheap and do not require re-sharing the underlying secret.

.sops.yaml (remove a recipient)

# drop the departing engineer’s age key from creation_rules, then:
#   sops updatekeys <each file>
# they keep any secrets already checked out, but cannot decrypt FUTURE versions
# -> rotate the actual secret values too if the person should lose all access

Removing a recipient does not rotate the secret itself

updatekeys stops a removed recipient from decrypting future versions, but they may still hold a previously-decrypted copy or remember the value — so for a true revocation (a departing admin, a suspected leak) you must also rotate the underlying secret at its source (change the password, reissue the token). SOPS controls who can decrypt the file; it cannot un-know a secret someone already read. Rotate the secret, not just the keys.

.sops.yaml creation rulesFormats & integrations