5.9 KiB
Using GPG
This document aims to be "just enough" for setting up and using GPG keys for signing artifacts with Leiningen for publication to Clojars.
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. 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, and has
only been tested under v1.x.
What is it?
GPG(http://www.gnupg.org/) (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 closely, and share it 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):
- via homebrew:
brew install gnupg - via macports:
port install gnupg - via a binary installer
Windows
GPG4Win provides a binary installer that
provides some possibly useful GUI tools in addition to providing the
gpg command.
Creating a keypair
Create a keypair with:
gpg --gen-key
This will prompt you for details about the keypair to be generated,
and store the resulting keypair in ~/.gnupg/.
The default key type (RSA and RSA) is fine for our purposes, as is the default keysize (2048). We recommend a validity period of 2 years.
You'll be prompted for a passphrase to protect your private key - it's important to use a strong one to help protect the integrity of your key.
Listing keys
GPG stores keys in a keystore located in ~/.gnupg/. This keystore
holds your keypair(s), along with any other public keys you have used.
To list your private keys:
gpg --list-secret-keys
To list all of the public keys:
gpg --list-keys
This will produce similar output, but will include any public keys you have used (if you've never used GPG before and just created your first keypair, you should just see your own key).
How Leiningen uses GPG
Leiningen uses gpg for two things: decrypting credential files, and signing release artifacts. We'll focus on artifact singing here; for information on credentials encryption/decryption, see the Leiningen deploy guide.
Signing a file
When you deploy a non-SNAPSHOT artifact to Clojars 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 to Clojars along with the artifacts. In order for Clojars to verify the signatures, you'll need to provide it with your public key (see below).
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.
Leiningen currently makes no effort to select a private key to use for
signing, and leaves that up to GPG. 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, you'll need to set a default key for GPG. To do
so, edit ~/.gnupg/gpg.conf and set the default-key option to the
id of the key you want to use. You can get the key id from the 'pub'
line in the key listing:
$ gpg --list-keys
↓↓↓↓↓↓↓↓
pub 2048R/2ADFB13E 2013-03-16 [expires: 2014-03-16]
uid Bob Bobson <bob@bobsons.net>
sub 2048R/8D2344D0 2013-03-16 [expires: 2014-03-16]
Clojars
Clojars requires that artifacts be signed and verified before being
promoted to the
releases
repository. In order to verify the signature, it needs a copy of your
public key. To view your public key, use gpg --export -a giving it
either the key id. Example:
$ gpg --export -a 2ADFB13E
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v1.4.11 (GNU/Linux)
mQENBFE/a/UBCAChmZrZWFFgzzYrhOVx0EiUa3S+0kV6UryqkxPASbHZLml3RlJI
<snipped>
=EaPb
-----END PGP PUBLIC KEY BLOCK-----
Copy the entire output (including the BEGIN and END lines), and paste it into the 'PGP public key' field of your Clojars profile.
lein deploy clojars vs. scp
Currently, publishing signatures to Clojars only works if you are
using lein deploy clojars. If you are using scp to deploy, you can
copy signatures along with the artifacts, but they will be
ignored.