Skip to content
Hands-on IT IT Drills

Day 6: Shamir – Key Groups

Goal: You encrypt an emergency secret so that only two of three key holders can open it together, replace a lost key and know the limits of updatekeys. · Duration: approx. 60 min · Prerequisite: Day 5

Briefing

  • Until now one matching key was enough. With key groups, sops splits the data key into shares using Shamir’s scheme: one share per group.
  • shamir_threshold: 2 means: two groups must deliver their share. Within a group, any key is enough.
  • Use cases: root passwords, unseal keys, emergency access – the “four-eyes principle” enforced by cryptography instead of a policy document.
 data key ──Shamir 2 of 3──┬─ share 1 ─► group 0: anna (+ me, later)
                           ├─ share 2 ─► group 1: ben
                           └─ share 3 ─► group 2: cleo
 Decrypt: any 2 shares ─► data key ─► values

Drill 1: Three key holders and one rule

# on argo
mkdir -p ~/sops/tag06 && cd ~/sops/tag06
for n in anna ben cleo; do age-keygen -o $n.key 2>&1; done
A=$(age-keygen -y anna.key); B=$(age-keygen -y ben.key); C=$(age-keygen -y cleo.key)
cd ~/sops/repo
cat >> .sops.yaml <<EOF
  - path_regex: ^tresor/.*\.yaml$
    shamir_threshold: 2
    key_groups:
      - age: [$A]
      - age: [$B]
      - age: [$C]
EOF
tail -6 .sops.yaml | cut -c1-60

Expected:

Public key: age14w75l5awdfnwylp6nrvrm92f037t3wdcg6chualy5tjrfqseqq8q85wa4n
Public key: age1z32l8zxdjjgc97375gfzvtf74976lh373e6fpagzyp58du7865useagh79
Public key: age1s4a2qerngelfdr3eg4j4quz9w2xzfvgans2u7dy2u69vehqdn9ssa3yuef
  - path_regex: ^tresor/.*\.yaml$
    shamir_threshold: 2
    key_groups:
      - age: [age14w75l5awdfnwylp6nrvrm92f037t3wdcg6chualy5t
      - age: [age1z32l8zxdjjgc97375gfzvtf74976lh373e6fpagzyp
      - age: [age1s4a2qerngelfdr3eg4j4quz9w2xzfvgans2u7dy2u6

In a rule, key_groups replaces the plain age:. A group may mix different key types (age, PGP, Transit from Day 7).

Save your progress? Sign up for free

Drill 2: Encrypt and inspect

# on argo
cd ~/sops/repo
mkdir -p tresor
printf 'root_password: lab-root-123\n' > tresor/notfall.yaml
sops encrypt -i tresor/notfall.yaml
yq '.sops | keys' tresor/notfall.yaml
yq '.sops.shamir_threshold, (.sops.key_groups | length)' tresor/notfall.yaml
yq '.sops.key_groups[].age[].recipient' tresor/notfall.yaml | cut -c1-30

Expected:

- key_groups
- lastmodified
- mac
- shamir_threshold
- unencrypted_suffix
- version
2
3
age14w75l5awdfnwylp6nrvrm92f03
age1z32l8zxdjjgc97375gfzvtf749
age1s4a2qerngelfdr3eg4j4quz9w2

Instead of age: directly under sops:, you now see key_groups. Each enc entry no longer holds the whole data key, only one share.

Save your progress? Sign up for free

Drill 3: One key is not enough

# on argo
cd ~/sops/repo
SOPS_AGE_KEY_FILE=~/sops/tag06/anna.key sops decrypt tresor/notfall.yaml 2>&1 \
  | grep -E '^Group|^  age1' | cut -c1-40
SOPS_AGE_KEY_FILE=~/sops/tag06/anna.key sops decrypt tresor/notfall.yaml 2>&1 \
  | tail -4

Expected:

Group 0: SUCCESS
Group 1: FAILED
  age1z32l8zxdjjgc97375gfzvtf74976lh37
Group 2: FAILED
  age1s4a2qerngelfdr3eg4j4quz9w2xzfvga
2, but only 1 part(s) were successfully recovered, one for each successful
key group. In order for SOPS to recover the file, at least 2 groups have to
be successful. In order for a group to be successful, decryption has to
succeed with any of the keys in that key group.

The message is unusually helpful: threshold, number of successful groups and the rule are all there. Anna alone gets nowhere – and neither do you with your own key, which is in no group.

Save your progress? Sign up for free

Drill 4: Two out of three

An identity file may contain several keys. In real life Anna and Cleo would sit together, or one would hand the other their share through a keyservice (Day 8).

# on argo
cd ~/sops/repo
cat ~/sops/tag06/anna.key ~/sops/tag06/cleo.key > ~/sops/tag06/anna-cleo.txt
SOPS_AGE_KEY_FILE=~/sops/tag06/anna-cleo.txt sops decrypt tresor/notfall.yaml
SOPS_AGE_KEY="$(grep -h AGE-SECRET ~/sops/tag06/ben.key ~/sops/tag06/cleo.key)" \
  sops decrypt tresor/notfall.yaml

Expected:

root_password: lab-root-123
root_password: lab-root-123

SOPS_AGE_KEY accepts several lines too. Any combination of two of the three groups opens the file.

Save your progress? Sign up for free

Drill 5: A group with two members

You should be able to stand in for Anna: you join her group. Your key then counts as share 1 – not as an additional share.

# on argo
cd ~/sops/repo
ICH=$(age-keygen -y ~/.config/sops/age/keys.txt)
yq -i '(.creation_rules[] | select(.path_regex == "^tresor/.*\\.yaml$")
  | .key_groups[0].age) += ["'$ICH'"]' .sops.yaml
SOPS_AGE_KEY_FILE=~/sops/tag06/anna-cleo.txt sops updatekeys -y \
  tresor/notfall.yaml 2>&1 | grep -vE '^20'
yq '.sops.key_groups[0].age[].recipient' tresor/notfall.yaml | cut -c1-30
SOPS_AGE_KEY_FILE=~/sops/tag06/ben.key sops decrypt tresor/notfall.yaml

Expected:

The following changes will be made to the file's groups:
shamir_threshold: 2
Group 1
    age14w75l5awdfnwylp6nrvrm92f037t3wdcg6chualy5tjrfqseqq8q85wa4n
+++ age1rnz4tqupd0f3lm4kfs564cfgys5j80497rk7ajzn2ekxh3d2g3uqdtdnv2
Group 2
    age1z32l8zxdjjgc97375gfzvtf74976lh373e6fpagzyp58du7865useagh79
Group 3
    age1s4a2qerngelfdr3eg4j4quz9w2xzfvgans2u7dy2u69vehqdn9ssa3yuef
age14w75l5awdfnwylp6nrvrm92f03
age1rnz4tqupd0f3lm4kfs564cfgys
root_password: lab-root-123

With key groups, updatekeys needs two shares to redistribute the data key – hence Anna and Cleo. Afterwards you (from keys.txt, group 0) and Ben (group 1) are enough. The updatekeys output counts groups from 1, the decryption error message from 0.

Save your progress? Sign up for free

Drill 6: A key is lost

Cleo’s laptop is gone. With two of three shares this is no emergency: Dora takes over Cleo’s group.

# on argo
cd ~/sops/repo
age-keygen -o ~/sops/tag06/dora.key 2>&1
C=$(age-keygen -y ~/sops/tag06/cleo.key); D=$(age-keygen -y ~/sops/tag06/dora.key)
sed -i "s/$C/$D/" .sops.yaml
SOPS_AGE_KEY_FILE=~/sops/tag06/ben.key sops updatekeys -y tresor/notfall.yaml 2>&1 \
  | grep -E '^(Group 3|\+\+\+|---)'
SOPS_AGE_KEY_FILE=~/sops/tag06/ben.key sops rotate -i tresor/notfall.yaml
cat ~/sops/tag06/ben.key ~/sops/tag06/dora.key > ~/sops/tag06/ben-dora.txt
XDG_CONFIG_HOME=/nirgends SOPS_AGE_KEY_FILE=~/sops/tag06/ben-dora.txt \
  sops decrypt tresor/notfall.yaml

Expected:

Public key: age1fylg8z028cgs2z47pnntwrwhu2fsc8nklzcfy2r7ckknvm9z2gfshkr0ej
Group 3
+++ age1fylg8z028cgs2z47pnntwrwhu2fsc8nklzcfy2r7ckknvm9z2gfshkr0ej
--- age1s4a2qerngelfdr3eg4j4quz9w2xzfvgans2u7dy2u69vehqdn9ssa3yuef
root_password: lab-root-123

Whoever finds Cleo’s laptop? Cleo’s key alone is useless, and after rotate her old shares no longer fit the new data key. If the loss was a theft, you still change the secret itself (Day 5).

# on argo
cd ~/sops/repo
git add .sops.yaml tresor
git commit -q -m "tag06: Notfall-Tresor 2 von 3" && git push -q
git log --oneline | head -1

Expected:

556364c tag06: Notfall-Tresor 2 von 3

Save your progress? Sign up for free

Exercise: Speed Drills

  1. Show the threshold and the number of groups of tresor/notfall.yaml. Target time: 15 s
  2. Open the file with yourself and Dora. Target time: 30 s

Solution

# on argo
cd ~/sops/repo
yq '.sops.shamir_threshold, (.sops.key_groups | length)' tresor/notfall.yaml
SOPS_AGE_KEY_FILE=~/sops/tag06/dora.key sops decrypt tresor/notfall.yaml

Expected:

2
3
root_password: lab-root-123

Your key joins in automatically from keys.txt.

Save your progress? Sign up for free

Checkpoint

# on argo
cd ~/sops/repo && git status -sb
SOPS_AGE_KEY_FILE=~/sops/tag06/anna.key sops decrypt tresor/notfall.yaml 2>&1 \
  | grep -c SUCCESS

Expected:

## main...origin/main
1

Anna alone (plus your key – both in group 0) only adds up to one successful group.

Challenge

The auditors demand “three of three”. Set shamir_threshold in .sops.yaml to 3, bring tresor/notfall.yaml to the new threshold and prove that Ben and Dora alone are no longer enough. Then restore the old state (2 of 3).

Hint: updatekeys only syncs the keys, not the threshold – check what it reports.

Solution

# on argo
cd ~/sops/repo
yq -i '(.creation_rules[] | select(.path_regex == "^tresor/.*\\.yaml$")
  | .shamir_threshold) = 3' .sops.yaml
SOPS_AGE_KEY_FILE=~/sops/tag06/ben.key sops updatekeys -y tresor/notfall.yaml \
  2>&1 | cut -c21-
yq '.sops.shamir_threshold' tresor/notfall.yaml
SOPS_AGE_KEY_FILE=~/sops/tag06/ben.key sops decrypt tresor/notfall.yaml \
  | sops encrypt --filename-override tresor/notfall.yaml /dev/stdin > neu.yaml
mv neu.yaml tresor/notfall.yaml
yq '.sops.shamir_threshold' tresor/notfall.yaml
XDG_CONFIG_HOME=/nirgends SOPS_AGE_KEY_FILE=~/sops/tag06/ben-dora.txt \
  sops decrypt tresor/notfall.yaml 2>&1 | grep -A1 Recovery
git checkout .sops.yaml tresor/notfall.yaml

Expected:

Syncing keys for file /home/ubuntu/sops/repo/tresor/notfall.yaml
File /home/ubuntu/sops/repo/tresor/notfall.yaml already up to date
2
3
Recovery failed because the file was encrypted with a Shamir threshold of
3, but only 2 part(s) were successfully recovered, one for each successful
Updated 2 paths from the index

The threshold is stored in the file and only changes when you re-encrypt – decrypt | encrypt with --filename-override, so that the rule for tresor/ applies. updatekeys reports “already up to date” and leaves you believing everything is done.

Save your progress? Sign up for free

Interview Note

  • How do you enforce a four-eyes principle for a secret? sops key groups with shamir_threshold: the data key is split, each group holds one share, and only the minimum number of shares puts it back together.
  • What happens when a key holder drops out? As long as enough groups remain, nothing; their group is refilled via .sops.yaml + updatekeys, followed by rotate.

Enterprise Note

  • Staff every group with at least two members or a KMS key plus a person, otherwise a single vacation takes out a whole group.
  • Shamir is meant for a few rarely opened emergency files; for day-to-day operations (GitOps) a single cluster key is common.
  • Document threshold changes and group changes in the change process and check them in CI with yq '.sops.shamir_threshold' – updatekeys does not apply the threshold.