Using GPG

This is an introduction to setting up and using
GPG keys with
Leiningen to sign artifacts for publication to
Clojars and to encrypt repository credentials.

There are two versions of GPG available: v1.x and v2.x. For our
purposes, they are functionally equivalent. Package managers generally
install v2.x as gpg2, and v1.x as gpg, except for Homebrew which
installs v2.x as gpg, and v1.x as gpg1. By default, Leiningen
expects the GPG command to be gpg. You're welcome to use any version
you like, but this primer will only cover installing v1.x (except under
macOS), and has only been tested under v1.x.

What is it?

GPG (or Gnu Privacy Guard) is a set of tools
for cryptographic key creation/management and encryption/signing of
data. If you are unfamiliar with the concepts of public key
cryptography, this
Wikipedia entry
serves as a good introduction.

An important concept to understand in public key cryptography is that
you are really dealing with two keys (a keypair): one public, the
other private (or secret). The public key can be freely shared, and is
used by yourself and others to encrypt data that only you, as the
holder of the private key, can decrypt. It can also be used to verify
the signature of a file, confirming that the file was signed by the
holder of the private key, and the contents of the file have not been
altered since it was signed. You should guard your private key
and passphrase closely, and share them with no one.

Installing GPG

Linux

Debian based distributions

Apt uses GPG v1, so it should already be installed. If not:

apt-get install gnupg

Fedora based distributions

Fedora and friends may have GPG v2 installed by default, but GPG v1 is
available via:

yum install gnupg

Mac

There are several options here, depending on which package manager you
have installed (if any):

The --fingerprint option will act just like --list-keys, but will
include the fingerprint of each certificate in the output. You can
filter the output of the --fingerprint option by providing a key id
or any substring from the uid (this trick also works for the
--list-keys option):

Publishing your public key

To make it easier for others that need your public key to find it,
you can publish it to a key server with:

gpg --send-keys 2ADFB13E # use your id instead

This pushes a copy of your public key to one of a cluster of free key
servers, and the key is propagated to all of the other servers in the
cluster in short order.

If your keypair is compromised, you can publish a revocation
certificate to the key server to let others know that your key can no
longer be trusted for any future signing or encryption. It's a good
idea to generate a revocation certificate whenever you create a new
keypair, and store it in a safe place. As long as you have that
revocation certificate, you can revoke a keypair even if you no longer
have the private key. You can generate a revocation certificate with:

$ gpg --output 2ADFB13E-revoke.asc --gen-revoke 2ADFB13E

Be sure to protect your revocation certificate carefully - anyone who
gains access to it can use it to revoke your keypair. The GPG
maintainers recommend printing it out and storing the hardcopy in a
safe place.

To revoke your certificate when the time comes (not now!), do the
following:

$ gpg --import 2ADFB13E-revoke.asc # ONLY WHEN YOU NEED TO REVOKE
$ gpg --send-keys 2ADFB13E # ONLY WHEN YOU NEED TO REVOKE

How Leiningen uses GPG

Leiningen uses GPG for three things: decrypting credential files,
signing release artifacts, and signing tags. We'll focus on artifact
signing here; for information on credentials encryption/decryption,
see the
deploy guide. Once
you are configured to sign releases, signing tags should be
straightforward.

On some systems you will be prompted for your GPG passphrase when it
is needed if you haven't entered it. If yours does not, you can
install Keychain, which provides
this functionality portably.

Signing a file

When you deploy a non-SNAPSHOT artifact via the deploy
task, Leiningen will attempt to create GPG signatures of the jar and
pom files. It does so by shelling out to gpg and using your default
private key to sign each artifact. This will create a signature file
for each artifact named by appending .asc to the artifact name.

Both signatures are then uploaded along with the artifacts. If you're
deploying to Clojars, you'll want to provide it with your public key
(see below) in order that the signatures can be verified.

To disable signing of releases, set :sign-releases to false in the
:repositories entry you are targeting. If you do this, everyone who
is depending on your library will not be able to confirm that the copy
they get has not been tampered with, so this is not recommended.

Overriding the gpg defaults

By default, Leiningen will try to call GPG as gpg, which assumes
that gpg is in your path, and your GPG binary is actually called
gpg. If either of those are false, you can override the command
Leiningen uses for GPG by setting the LEIN_GPG environment variable.

GPG by default will select the first private key it finds (which will
be the first key listed by gpg --list-secret-keys). If you have
multiple keys and want to sign with one other than first, or want to
use specific keys for a particular release repository, you can specify
which key to use either globally, per-project, or
per-deploy-repository. All three places use the same configuration
syntax, it's all about where you put it. You can specify the key by id
or by the uid.

To set a key globally, add it to your user profile in
~/.lein/profiles.clj:

{:user {...
:signing {:gpg-key "2ADFB13E"}}} ;; using the key id

To set a key for a particular project, add it to the project
definition:

Setting the gpg passphrase for unattended deploys

It's also possible to provide the passphrase required to unlock your
keyring. This is meant only for unattended deploys, for example in a
continuous integration system like Travis CI or CircleCI or Jenkins.