Getting Started with GnuPG (+ git)

GnuPG (GPG) is a convenient standards-based (RFC4880) implementation of public-key cryptography. In a public-key cryptographic system, a pair of mathematically linked keys – a public key and a secret private key – is used for encrypting/decrypting messages and signing/verifying messages. Unlike symmetric-key cryptography, where the same key is used to encrypt and decrypt a message, public-key cryptography is asymmetric: if a public key is used to encrypt a message, its corresponding private key must be used to decrypt it.

Encryption/decryption enables confidential communication between two parties, and signing/verifying allows for authenticating a message (the digital signature is his signature) with non-repudiability (no one else could have made that signature).

GPG makes it easy to generate key pairs, import/export public keys, sign/verify messages, and encrypt/decrypt messages. Below is a quick a guide to using this basic functionality of GPG.

Generate a public/private key pair

$ gpg --gen-key

Follow the suggested defaults, but choose a finite expiration time in case you lose your private key. Fill out an appropriate user id. Choose a passphrase.

Your public key and encrypted private key will be stored in your public and secret key rings, which exist in ~/.gnupg/pubring.gpg and ~/.gnupg/secring.gpg, respectively. You should include these files in your regular backup.

Export your Public Key

Exporting your public key to an ASCII format will let you easily distribute your public key on your website and other text-based mediums, or on public key servers such as http://pgp.mit.edu/, so others can verify your digital signatures or encrypt messages intended only for you.

$ gpg --armor --output mypubkey.txt --export me@email.com

Import a Public Key

$ gpg --import alice.txt

Sign an ASCII Message

$ gpg --clearsign file

This will produce the file file.asc, which contains the original contents of file (binary or not) and a verifiable ASCII-friendly digital signature.

Verify an ASCII Message Signature

$ gpg --verify file.asc
gpg: Signature made Tue 01 Feb 2013 03:47:53 PM EST using RSA key ID EDB35BC9
gpg: Good signature from "Ivan (Vanya) A. Sergeev <vsergeev@gmail.com>"
$

Sign a Binary File (Detached Signature)

$ gpg --armor --detach-sign file

This will produce an ASCII-friendly detached signature file.sig, which can be distributed with file.

Verify a Detached Signature

$ gpg --verify file.sig
gpg: Signature made Tue 01 Feb 2013 03:53:25 PM EST using RSA key ID EDB35BC9
gpg: Good signature from "Ivan (Vanya) A. Sergeev <vsergeev@gmail.com>"
$

The verification of a detatched signature file.sig requires you to have file in the same directory.

Encrypt Files for Someone with their Public Key

$ gpg --output file.gpg --encrypt --recipient bob@bobsmail.com file

This will produce the encrypted file file.gpg, which can only be decrypted with Bob’s private key.

Decrypt Files with your Private Key

$ gpg --output file --decrypt file.gpg

This will produce the decrypted file file.

Create a signed tag in your git repository

You can create a signed tag in your git repository, so others can verify your seal of authenticity of the git repository up to that tagged commit.

If your git config identification corresponds to your GPG identification (e.g. the email), GPG will figure out which key to use by your git config identification when you create a signed tag:

$ git tag -s -m "tag description" tagname

Otherwise, find your GPG key id in your private keyring listing, the first hexadecimal number after the slash, and specify it explicitly when creating a signed tag:

$ gpg -K
$ git tag -u MYGPGKEYID -m "tag description" tagname

Remember to push created tags with:

$ git push remotename --tags

Verify a signed tag in a git repository

You can verify signed git tags if you have the signer’s public key in your public keyring.

$ git tag -v tagname

Store your public key as a tag-signed object in your git repository

You can store your public key as a tagged object in your git repository to make it convenient for others to import your public key and verify your other signed tags. Of course, users should corroborate this public key with other trusted distributions of your public key (such as your website, a public key database, friends, etc.).

1. Store your public key as a blob in your git repository.

$ git hash-object -w mypubkey.gpg
ca0224236afaae4ca20c9f633b31b8790be5c667

2. Create a signed tag for the blob hash id.

If your git config identification corresponds to your GPG identification (e.g. the email), GPG will figure out which key to use by your git config identification when you create a signed tag:

$ git tag -s pubkey ca0224236af -m "alice's public key"

Otherwise, find your GPG key id in your private keyring listing, the first hexadecimal number after the slash, and specify it explicitly when creating a signed tag:

$ gpg -K
$ git tag -u MYGPGKEYID -m "my public key" pubkey ca0224236af

Users can then extract and import the public key blob, and verify the signed tag referring to the public key with the extracted public key itself.

$ git cat-file blob pubkey > pubkey.gpg
$ gpg --import pubkey.gpg
$ git tag -v pubkey

---

Other excellent resources on GnuPG usage information can be found here: http://www.spywarewarrior.com/uiuc/gpg/gpg-com-4.htm and http://www.madboa.com/geek/gpg-quickstart/.