sops-secrets

Secrets Standard (sops 3.13+ / age)

Canonical workflow for sops (structured-file encryption) with age (modern key pairs) — encrypted secrets live in git next to the code they configure, and plaintext exists only in memory. This operationalizes the global "No Secrets in Output" rule: no plaintext secret ever touches disk, logs, or a commit.

1. Core Model

• age provides the key pair: one private key per machine/human, public recipients everywhere. Prefer age over PGP (simpler, no keyservers) and over cloud KMS for solo/portable use; add a gcp_kms recipient alongside age only when a team needs central revocation.
• sops encrypts the values of YAML/JSON/ENV files — keys stay readable, so diffs review cleanly and git log still tells you which secret changed, never what it is.
• Naming Convention: encrypted files are committed as *.enc.yaml / *.enc.json / *.enc.env; the sops.yaml rules key off that suffix, and any plaintext siblings stay gitignored.
• Policy As File: .sops.yaml at the repo root (sops.yaml) declares which paths get encrypted and for which recipients — creation is automatic, ad-hoc flags are never needed.

2. Key Management

1. Generate once per machine: age-keygen -o ~/.config/sops/age/keys.txt — sops' default key location; print the public half anytime with age-keygen -y ~/.config/sops/age/keys.txt.
2. Distribute only the public key: paste it as the age: recipient in each repo's sops.yaml.
3. Back up the private key in a password manager. Never commit it anywhere — in particular never chezmoi add it, since the dotfiles repository is public.
4. Rotate by adding the new recipient to .sops.yaml, running sops updatekeys <file> on every encrypted file, then removing the old recipient and repeating; sops rotate -i <file> re-keys the data key after a suspected exposure.

3. Daily Workflow

sops edit secrets.enc.yaml                      # create or edit (decrypts to $EDITOR, re-encrypts on save)
sops -e -i config.yaml                          # encrypt an existing file in place (then rename to *.enc.yaml)
sops -d secrets.enc.yaml                        # decrypt to stdout — for piping, never for redirecting to a file
sops exec-env secrets.enc.env 'mise run watch'  # inject as env vars, memory-only (preferred)
sops exec-file secrets.enc.json 'tool --config {}'  # tools that require a file path get a tmpfs one