Skip to main content

Git-crypt

We use git-crypt for securing secrets committed to git. It uses a symmetric encryption key which is then encrypted for users using their GPG keys.

Adding new user to the keyring

  1. Ask the user (Slack, email, keyserver, etc) for their public key and import it into your keyring:

    gpg --import <<EOF
    -----BEGIN PGP PUBLIC KEY BLOCK-----
    
    mQGiBEN5tJ0RBADwLLzmO1AR10KILHRJMMq+MtnscrVsOawA4vUhC8oTZHPUXRgE
    AbJgYgUlxMpjsaT14d5xiTUqU1C+85FT764rIk51aEB1AsjudZf/tlv7gCieT64C
    DRDjqr7g7Df5L80zDuPuVdOHn+KlGIlT5X3gypstFKDvSKqN/qQMQhf5KwCg77aq
    ----------------------------------------------------------------
    ------------------- HERE USER PUBLIC KEY -----------------------
    ----------------------------------------------------------------
    3omjJRX0AnQtfN1udwOK0N2FfyZLqChI2ied42DurIeQk+qYoSHhK/sCh4E3BjOg
    U5hJ21cQRxlN1sa1RFaNjoQlIkBH0q2xZSb3p+LM9Ez7keF96VGXZSy0K2Q9xtPi
    NS+0Yc13JFAzDubGfxGOnACePwZ5mNcJB6JNaZXPZN4E5AqDdEg=
    =yaF+
    -----END PGP PUBLIC KEY BLOCK-----
    EOF
    
  2. Using KeyID/email trust the key as “5 = I trust ultimately”:

gpg --edit-key "my-name@digital.justice.gov.uk" trust quit
  1. Create a new branch inside the git repository where user is going to be added:
git checkout -b add-alejandro-gpg
  1. Use git-crypt CLI to add the user:
git-crypt add-gpg-user my-name@digital.justice.gov.uk
  1. Push the branch and create a PR:
git push origin add-alejandro-gpg

Rotating the git-crypt key

When rotating the git-crypt symmetric key, you should follow the steps below:

1. Ensure you have unlocked the repository:

git-crypt unlock

2. Make a list of the current users:

  • for every file found, extract its filename minus the suffix, which corresponds to the user’s key id
ls .git-crypt/keys/default/0/*.gpg | xargs -I{} -- basename {} .gpg > git-crypt-users

3. Make a list of the encrypted files:

  • for every currently encrypted file, extract its path, relative to the root of the repository
git-crypt status -e | awk '{ print $2; }' > git-crypt-files

4. Remove git-crypt configuration:

rm -rf .git-crypt .git/git-crypt

5. Re-initialise git-crypt,

git-crypt init
  • make sure you have all the users’ keys,
cat git-crypt-users | xargs -I{} gpg --recv-key {}
  • and add all the users back,
cat git-crypt-users | xargs -I{} git-crypt add-gpg-user -n --trusted {}
  • At this point, your git index will have a number of pending changes, do not commit them yet.

6. Re-encrypt all the secrets: the list of secrets was extracted in git-crypt-files (see step 2. above). Since the master encryption key is being rotated, all of the secrets that have been encrypted with it must be rotated. Once finished, you can add the files to the index

cat git-crypt-files | xargs git add

7. Commit your changes. One way to check that the files in the git index are properly encrypted before you commit your changes is like so:

git show :<path-to-file>
  • or after committing (and before you’ve pushed):
git show HEAD:<path-to-file>
  • where <path-to-file> is either absolute from the base of the git repo or relative (eg.: git show:./my-secret-file.yaml)

  • You should see binary output which begins with ^@GITCRYPT^@.

Note: If you need to checkout an older commit, branch, tag etc., make sure to git-crypt lock your repository beforehand in order to avoid a broken local working directory. Once you’ve locked and checked out the desired revision, you can git-crypt unlock.

This page was last reviewed on 1 September 2021. It needs to be reviewed again on 1 December 2021 by the page owner #cloud-platform .
This page was set to be reviewed before 1 December 2021 by the page owner #cloud-platform. This might mean the content is out of date.