Introduction to GPG Encryption and git-crypt

While Open Source prides itself on open transparency, there are certain things that must be kept secret like team credentials or personal information.  GNU’s OpenPGP (GPG) encryption tool set coupled with git-crypt can be invaluable for sharing such information privately with colleagues.

For people unfamiliar with GPG it can seem a bit intimidating to start with, but it needn’t be! This article is a step-by-step introduction to getting set up with your own GPG key.

Install GPG

Since GPG has become pretty ubiquitous it should be straightforward to install via the usual method for your operating system.

debian/ubuntu:

$ sudo apt-get install gnupg

OSX (using ports):

$ sudo port install -v gnupg

etc.

Create Your Own GPG Key

Easy enough! The following command will ask for the info needed to make the key. Pick RSA with a key length of 4096 bits, and be very careful to set a unique GPG password that you’re not using anywhere else (but pick one you can remember!):

$ gpg --gen-key

This actually creates two keys, one public, one private. Together these are called your ‘keypair’. They’re stored in ~/.gnupg – keep this directory private and secure!

Display Your Key

After it’s done, you can view your registered keys:

$ gpg --list-keys

pub 1024D/F2345678 2010-01-01
 uid Foo Bar <foo@bar.org>
 sub 2048g/B9876543 2010-01-01

Your public <keyid> is the bit on the pub line following the slash, in this case ‘F2345678’.

You can print out your public key with this command:

$ gpg --export --armor <keyid>

Store it to a file like this:

$ gpg --armor --output ~/.gnupg/my_pubkey.txt --export <keyid>

Share Your Key

Your public gpg key can be shared freely – posted on websites, sent via email, printed out on business cards, or whatever suits your whimsy.

$ echo "Here's my GPG public key" | \
 mail -s "GPG pubkey" -a my_pubkey.txt someone@somewhere.org

A common convention is for people to send a copy of their public key to any one of the many PGP keyservers (they routinely sync up together, so send to whichever you desire). Here’s one way to do it:

$ gpg --keyserver certserver.pgp.com --send-key myname@mydomain.org

Or paste it to MIT’s web form:

https://pgp.mit.edu/

Once you’ve registered your key, you can share it by just supplying the (much shorter) keyid.

Accept and Trust Someone Else’s Key

You can receive public keys from any which way – websites, direct emails, keyservers… But there’s one problem: how do you trust that the key was sent by the person it purports to be from?

No mechanism is 100% foolproof; exchanging keys in person (face-to-face key signings) has traditionally been the best way. Barring that, you should strive to use the most secure and sensible way at hand. Since the goal is authentication of identity, it can be useful to validate the exchange via several different mechanisms (e.g. IRC + email + personal website + telephone) including the ones you’re most accustomed to for communicating with that individual.

Whatever the mechanism you choose to receive the public key, once you have satisfied yourself of its authenticity, add it to your local key ring like this:

$ gpg --import some_key.txt

If they gave you a keyid, you can download the key from a keyserver thusly:

$ gpg --keyserver certserver.pgp.com --recv-key <keyid>

You can then use their key securely for encrypted emails, sharing of encrypted files, and so on.

Use git-crypt to Encrypt Files in a Git Repository

Certainly, GPG by itself includes functionality for encrypting files for sharing, but if you need a more structured way to store and track these documents, git-crypt is a very handy tool.

Depending on your operating system, you may be able to simply install it your usual ways. E.g. on Ubuntu:

$ sudo apt-get install git-crypt

If it is not available for your system, it can be built from source fairly easily. Download it from https://www.agwa.name/projects/git-crypt and then:

$ make
$ sudo make install

git-crypt can be used in an existing git repository, even if not everyone that uses that repo will be using git-crypt.

$ cd repo
$ git-crypt init

git-crypt allows defining encryption on a file-by-file basis, however for storing of financial documents we want to set up a sub-directory named Secrets, where everything in it or below will automatically be encrypted. To do this, we need to add two files to our repository. The first is in the root dir of our repository:

# repo/.gitattributes
.gitattributes !filter !diff
.gitignore !filter !diff

This sets the repository’s defaults to no-encryption.

Next, we configure the Secrets subdirectory:

# repo/Secrets/.gitattributes
/** filter=git-crypt diff=git-crypt
.git* !filter !diff

This causes git to encrypt all files that don’t begin with .git* (we don’t want to encrypt the .gitattributes file after all).

Adding user access involves adding their key ids:

$ git-crypt add-gpg-user --trusted ABCD1234

or by the email address:

$ git-crypt add-gpg-user --trusted someone@someplace.com

This guide should have provided enough information for you to get up and running with GPG encryption. If you have your own tips, feel free to add them to the comments below!

Author: Bryce Harrington

Bryce is a founder and developer of the Inkscape project, but began his career in the aerospace industry as a spacecraft propulsions engineer.