Operationalizing Mozilla's sops tool sharing secrets across a distributed open source team spanning multiple companies.
We assume that onboarding a new user (or equivalently, a user changing or adding encryption keys) is a reasonably rare occurrence. As such. we skip automating the onboarding process for simplicity's sake.
Simply clone this repo. Everything is contained within it, including the encrypted secrets themselves.
Generally, all tasks can be done through interacting with make
targets. The only required dependencies are GNU coreutils and the go
command (for installing binaries).
If you have access to the secret key corresponding to one of the identities listed in .sops.yaml
you can view and edit secrets.yaml
in plaintext:
make open
If you've added a new key via one of the methods below - whether age
or PGP - secrets.yaml
must
be updated before that new key can decrypt anything.
As long as you have at least one key which can decrypt secrets.yaml
, you can update everything in a single
command:
make updatekeys
Once you've updated, you can raise a pull request with everything as-is.
This would be common when onboarding a new user or replacing lost keys for an existing user.
In this case, either:
- send a key to someone who does have a private key so they can raise a pull request for you
- or raise a pull request with their key added in
keys/
(andkeys/pgp-keys
for PGP) and ensure that maintainers can edit the pull request. One of the maintainers can then runmake updatekeys
on the branch locally, which should pick up the new key.
age
is the best choice for generating a key locally and
there are helpers to automate the process of generating a key and adding it to .sops.yaml
.
Adding a key varies depending on the type of key. The simplest and most secure way to get started
is to have the tooling generate a new age
key entirely automatically.
NB: Adding a key isn't enough to use it for encrypting secrets! You'll also need to run
make updatekeys
(described above) for that.
๐ This is the simplest case.
To generate a new managed key and append it to .sops.yaml
automatically, run:
make GH_USERNAME="<github username>" append-age-managed-key
That's it! ๐ There's nothing more to do in this case except to make sure that you don't lose
age/managed-secret-key.txt
!
If you have an existing age
key which you want to use, there's a helper:
make GH_USERNAME="<github-username>" AGE_PUBKEY="<public-key>" append-age-single-key
age
instead.
There are multiple ways PGP keys can fail; they can not be valid for encryption, or they can expire, or they could have some invalid text in their ASCII-armored representation which makes them unparseable.
If you choose to use PGP keys, you must remember to put the ASCII-armored public key into keys/pgp-keys/
. When fetching from GitHub this happens automatically, but if adding a key manually other users will not be able to encrypt
secrets for you unless they have your ASCII-armored key!
If you happen to use git commit signing and you have your PGP key(s) registered on GitHub, use the
following command to download your GitHub key(s) and add to .sops.yaml
:
make GH_USERNAME=<your-username> append-pgp-key-from-github
If you want to add a PGP key which isn't registered on GitHub, place the ASCII-armored public key
file in pgp-keys
with a sensible name, then do the following:
./hack/pgp-fingerprints-from-file.sh pgp-keys/<yourkeyfile>
make GH_USERNAME="<your-gh-username>" FINGERPRINT="<output from above command>" append-pgp-key-from-fingerprint
sops supports KMS providers, but the catch with those providers is that the other open-source
maintainers on your project must have permissions to encrypt (but not necessarily to decrypt) using
the KMS keys you want to configure - otherwise, they won't be able to update secrets.yaml
.
It's assumed that most humans will use either PGP or - preferably - age
keys.
Adding KMS keys will be done by manually appending the relevant information to .sops.yaml
. See
the sops README for more information.