Using Git-Crypt in a Git Repository to Encrypt Sensitive Files with Gpg Keys

By: Luke Reimer

At SPINEN, we use a tool called git-crypt to encrypt sensitive files in git repositories. This allows us to use our normal distribution channel for code to also distribute and share sensitive files. In this post, we give step-by-step instructions on how you can implement this process.

Step 1: Install git-crypt and gpg with homebrew.

brew install git-crypt
brew install gpg

Step 2: Generate a gpg key.

These instructions are copied from this link. For this example, we’ll suppose that we are making a gpg key for David Palmer.

Using the gpg command line tool:

gpg --gen-key

This will give you a series of prompts:

1. First, choose the key encryption algorithm. We normally choose 1
   Please select what kind of key you want:
(1) RSA and RSA (default)
(2) DSA and Elgamal
(3) DSA (sign only)
(4) RSA (sign only)
Your selection?
2. Next, choose a key size. 2048 is usually sufficient. You can choose this option by simply typing <return>
   RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048)
3. Now, choose an expiration date for your key.
   Please specify how long the key should be valid.
0 = key does not expire
<n>  = key expires in n days
<n>w = key expires in n weeks
<n>m = key expires in n months
<n>y = key expires in n years
Key is valid for? (0)
4. Next, the prompt will ask for a name, email and comment. Here’s what that looks like for David Palmer, our greatest fictional President.
   Real name: David Palmer
Email address: [email protected]
Comment: This key belongs to a former fictional president
5. Finally, the gpg tool will ask you to enter and re-enter a passphrase for your key. Be sure to pick a good one. (Note: You will be prompted to enter your passphrase twice.)
   Enter passphrase

   Passphrase --------------------------

   <OK>       <Cancel>

Now that we’ve created a key, we’re ready to use git-crypt in our repo.

Step 3: Initialize git-crypt in your repo.

You’ll need to cd into your repo and initialize git-crypt in your repo with git-crypt init

This will initialize git-crypt in the repository, but it does not encrypt any files by default. git_crypt uses the .gitattributes file to define what files it will manage. Naturally, you want to do this before you create the sensitive files.

Therefore, you must first edit the .gitattributes before creating the file you wish to encrypt. For the purposes of this example, let’s suppose that we want to encrypt a file called encrypted-file.txt. Then we would need to add this line:

encrypted-file.txt filter=git-crypt diff=git-crypt

For collaborators

Create a gpg key, exactly the same way.

Now, it’s necessary to export the public key to be added to the repo. To do this, we need to get the $KEY_ID. You can list your public keys with the command gpg ––list–keys The output will look like this:

pub 2048R/95A7A51C 2016-11-30 [expires: 2016-12-05]
uid     [ full ] Chef Chef (test key for chef) <[email protected]>
sub 2048R/725BE18E 2016-11-30 [expires: 2016-12-05]

In this case, the $KEY_ID is 95A7A51C

So, our export command looks like this:

gpg --armor --export --output davidpalmer_pubkey.gpg 95A7A51C

This will result in a file named davidpalmer_pubkey.gpg in our current directory.

That’s it! You’ve exported your key, and now you just need to ship the .gpg file to the git-crypt keeper via email or some other secure mechanism.

Importing the key

Anyone who already has the authority to decrypt the repo with git-crypt can add a key to git-crypt. To do so, you need only the public key from a collaborator who you wish to add.

Adding the key to your gpg keyring

gpg --import davidpalmer_pubkey.gpg

This will add the key to your keyring, but does not trust the key, so you can’t use it quite yet. First, we need to edit the trust level of the key. You can do this with the command gpg ––edit–key 95A7A51C (naturally, you’ll want to use the appropriate key id.)

This command will lead you to another gpg prompt. Best practice at this point is to contact the person whose key you are importing, either by phone or in person, and verify that the key fingerprints match. You can print the key fingerprint at the gpg prompt with the fpr command.

If you are satisfied that the public key is the one you want to trust, then you can type sign into the prompt. You can exit the gpg command prompt with save which saves the changes you made and exits the prompt. If for any reason you wish to quit without saving, you can do so with quit.

Adding the key to the git-crypt protected repo

Now that you have added the collaborator’s public key to your keyring, all that’s left to do is add that key to the git-crypt credentials in your repo. You can do that with the commmand git-crypt add-gpg-user 95A7A51C. This will not only add the collaborator’s key as a verified decrypter but also serves as a git commit. At this point, you can git push the repo and the new encryption will be pushed out.

Unlocking the repo

As a collaborator, once your key has been added you have only one step left. In the encrypted repo, type git-crypt unlock to unlock the encrypted files. From then on, you can use git as you normally would and all files managed by git-crypt will be encrypted before being pushed.