Software and infastructure security is more prominent than ever, and an important part is signing stuff.

I have postponed using GnuPG for many years, but now is the time. GnuPG has a reputation for being cumbersome to use. One of its major intended uses apart from signing is to facilitate a web of trust in a community. Suprisingly, in my professional life related to software and infrastructure, I have seen nothing of this yet.

This post is about creating and managing a primary key and one subkey, and using the latter to sign Git commits. Also, it is shown how commits and other signatures can more easily be verified by others.

The main resources I used are listed at the end of this article.

Create a primary key for signing and certification only, using gpg --full-generate-key, choose ECC (sign only), Curve 25519, and a suitable expiry, e.g. 2 years. Create a strong passphrase, e.g. using Diceware. You can specify a comment to be included in your identity. Here, we create a key for Alice.

Use gpg --list-keys --keyid-format LONG to get the ID and the fingerprint of your primary key. Note that you can add part of your identity to this command as a filter, e.g. gpg --list-keys alice.

FE0306B61A94B0D7 is the key ID, and 48DC4FF5BC3343C2E427C7A2FE0306B61A94B0D7 is the fingerprint.

Create a subkey to be used for signing only. Some recommend a different subkey for each device you use and for each customer engagement.

Create the subkey using gpg --edit-key ID. ID can be the key ID, the fingerprint of the primary key, or a part of the identity.

At the gpg> prompt, type addkey, choose ECC (sign only), Curve 25519, and a suitable expiry, e.g. 2 years.

The output of gpg --list-keys alice is now:

Backup your public and secret keys, and the whole GnuPG directory for good measure:

Copy your backup securely to a secure place. This is a fascinating aspect in itself, but not discussed here. There are plenty of resources on the internet about this topic.

You might now like to change the local passphrase for your key, see https://wiki.debian.org/Subkeys.

Remove the primary secret key from the current device by deleting the file $HOME/.gnupg/private-keys-v1.d/KEYGRIP.key (GnuPG 2.1 or later).

The KEYGRIP can be obtained by running gpg --list-secret-keys --with-keygrip.

After having done that, the output of gpg --list-secret-keys indicates this by the # suffix added to the sec label.

Export the public key in ascii format:

This can e.g. be added to your GitHub account, as a new GPG key.

In order for others to verify a signature, the public key needs to be publicly accessible. It can be uploaded to a (known) key server. Alternatively, it can be uploaded to your website as plain document, accessible using https. I keep mine on openpgp.mgfeller.net, named using the key’s fingerprint.

For the key just generated, the URL of the public key might thus become https://openpgp.mgfeller.net/48DC4FF5BC3343C2E427C7A2FE0306B61A94B0D7.asc .

This URL can be included in the signature, and automatically be retreived by someone else’s GnuPG.

To achieve this, use the option --sig-keyserver-url to specify the URL. It can also be specified in the GnuPG config file.

Use gpg --list-secret-keys --keyid-format=long ID to get the ID of the subkey used for signing:

Configuring Git for signing commits with the chosen key is quite straightforward:

Using git commit -S -m "clarify description", commit the change and sign the commit.

The signature can be inspected like this:

Everything is good because we’re verifying it on our PC. Note that the preferred keyserver is the URL of the public key, as discussed above.

For another user, the signature cannot be verified yet as nothing has been done to download and import Alice’s public key.

Looking at the Git log will thus show

GnuPG can be configured to automatically download keys, and honor included key location by adding the following lines to ~/.gnupg/gpg.conf:

This results in

Of course, the key is not yet trusted. How to handle that will be topic of another blog post.

This articles described how to

Also, it was shown how another user can configure her GnuPG to automatically download public key referenced in the signature.

Configuration options can be specified in the file ~/.gnupg/gpg.conf, assuming the default GnuPG home directory.

The example used for this blogpost is