terraform/.gpg-keys/README.md

Initial set-up

On a new laptop, generate new key pair:

gpg --generate-key

Find the new key and note the fingerprint:

gpg --list-keys

[keyboxd]
---------
pub   rsa3072 2024-05-30 [SC] [expires: 2031-05-29]
      4F864F3EA770491488B90B4E8B6CEF1599D3CCB5
uid           [ unknown] Greg Matoga (Test Key) <greg.matoga@gmail.com>
sub   rsa3072 2024-05-30 [E] [expires: 2031-05-29]

Export the public part and place in this directory:

export FINGER_PRINT=4F864F3EA770491488B90B4E8B6CEF1599D3CCB5
gpg --export --armor $FINGER_PRINT > .gpg-keys/new-key.asc

Ensure all public keys are imported:

for key in .gpg-keys/*.asc; do              
    gpg --import "$key"
done

Now, in order to reencode the vault with new key:

sops -r -i --add-pgp $FINGER_PRINT tf-secret.enc.json

It should add the fingerprint to the .sops.yaml:

creation_rules:
  - pgp: D4EACAC991E3DF53D9E39FE0CB9CF7B8A8A86318,4F864F3EA770491488B90B4E8B6CEF1599D3CCB5

This will reencode all values with new master key and put public keys into the file. For other options, check doc adding or removing keys. Note that there might be some differences in the command options (e.g. -r instead of positional argument rotate).

More info - usage

In day to day usage, only a single private key is needed to decrypt secrets.

SOPS encrypts the file content with a "data key". That key is then encrypted with all the public keys (in this repo configured in the .sops.yaml file) and stored in the encoded version of the file under sops.pgp[].enc field. So, any of the private keys will be able to decrypt the data key.

The data key is encrypted using public keys - once per each public key.

The full public key set is only needed, when rotating the data key. This reencodes all secrets and stores new set of encoded data keys in the file. So, a developer wanting to add or remove a key from the set, needs to have all the public keys available. Since public keys aren't considered a secret, any developer with a single private key and the set of public keys will be able to that.

Keyserver

It's possible to host own keyserver: hockeypuck. After configuring gpg client, the public keys could be uploaded and searched for. This would alleviate the need to manually import all the keys.

Hockeypuck at base configuration expects a full gpg dump, so it's quite heavy as files are around 16gb total. It also needs a postgres database.