Using OpenPGP subkeys in Debian development
What are keys?
In public key cryptography, a key is really a pair: a public key, and a private key. You use the private key to digitally sign files, and others use the public key to verify the signature. Or, others use the public key to encrypt something, and you use the private key to decrypt it.
As long as only you have access to the private key, other people can rely on your digital signatures being made by you, and you can rely on nobody else being able to read messages encrypted for you.
GnuPG, the implementation used in Debian, picks the right key at any one time.
What are subkeys?
OpenPGP further supports subkeys, which are like the normal keys, except they're bound to a master key pair. A subkey can be used for signing or for encryption. The really useful part of subkeys is that they can be revoked independently of the master keys, and also stored separately from them.
In other words, subkeys are like a separate key pair, but automatically associated with your main key pair.
GnuPG actually uses a signing-only key as the master key, and creates an encryption subkey automatically. Without a subkey for encryption, you can't have encrypted e-mails with GnuPG at all. Debian requires you to have the encryption subkey so that certain kinds of things can be e-mailed to you safely, such as the initial password for your debian.org shell account.
Subkeys make key management easier. The master key pair is quite important: it is the best proof of your identity online, at least for Debian, and if you lose it, you'll need to start building your reputation from scratch. If anyone else gets access to your private master key or its private subkey, they can make everyone believe they're you: they can upload packages in your name, vote in your name, and do pretty much anything else you can do. This can be very harmful for Debian. You might dislike it as well. So you should keep all your private keys safe.
You should keep your private master key very, very safe. However, keeping all your keys extremely safe is inconvenient: every time you need to sign a new package upload, you need to copy the packages onto suitable portable media, go into your sub-basement, prove to the armed guards that you're you by using several methods of biometric and other identification, go through a deadly maze, feed the guard dogs the right kind of meat, and then finally open the safe, get out the signing laptop, and sign they packages. Then do the reverse to get back up to your Internet connection for uploading the packages.
Subkeys make this easier: you already have an automatically created encryption subkey and you create another subkey for signing, and you keep those on your main computer. You publish the subkeys on the normal keyservers, and everyone else will use them instead of the master keys, with one exception. Likewise, you will use the master keys only in exceptional circumstances.
The exceptions are:
- when you sign someone else's key, you do that by using the master private signing key
- when you need to create a new subkey, because binding the subkey to the master key needs a signature from the master private key
- when you need to revoke the subkeys, you do that using the master private key
In case your subkey gets stolen while your master key remains safe, you can revoke the compromised subkey and replace it with a new subkey without having to rebuild your reputation and without reducing reputation of other people's keys signed with your master key.
Unfortunately, GnuPG's user interface is not entirely fun to use. We'll take you through the necessary steps below.
These instructions assume you use one computer, and keep the master keys on an encrypted USB flash drive, or preferably at least two (you should keep backups of your secret keys). We also assume you already have a key; if not, see http://keyring.debian.org/creating-key.html for instructions.
Make backups of your existing GnuPG files ($HOME/.gnupg). Keep them safe. If something goes wrong during the following steps, you may need this to return to a known good place.
umask 077; tar -cf $HOME/gnupg-backup.tar -C $HOME .gnupg
- Create a new subkey for signing.
Find your key ID: gpg --list-keys yourname
gpg --edit-key YOURMASTERKEYID
At the gpg> prompt: addkey
- This asks for your passphrase, type it in.
- Choose the "RSA (sign only)" key type.
- It would be wise to choose 4096 (or 2048) bit key size.
- Choose an expiry date (you can rotate your subkeys more frequently than the master keys, or keep them for the life of the master key, with no expiry).
- GnuPG will (eventually) create a key, but you may have to wait for it to get enough entropy to do so.
Save the key: save
- You can repeat this, and create an "RSA (encrypt only)" sub key as well, if you like. For Debian, just the signing key is sufficient.
Now copy $HOME/.gnupg to your USB drives.
- Here comes the tricky part. You need to remove the private master key, and GnuPG does not provide a convenient way to do that. We need to export the subkey, remove the private key, and import the subkey back.
Find the key ID of your new secret subkey: gpg --list-secret-keys
Export the subkeys: gpg --export-secret-subkeys SUBKEYID1! .. SUBKEYIDn! > subkeys
Also export the public keys: gpg --export YOURMASTERKEYID > pubkeys
Remove your master key: gpg --delete-secret-key YOURKEYID
Import back: gpg --import pubkeys subkeys
Verify that gpg -K shows a sec# instead of just sec for your private key. That means the secret key is not really there.
Your computer is now ready for normal use.
When you need to use the master keys, mount the encrypted USB drive, and set the GNUPGHOME environment variable:
export GNUPGHOME=/media/something gpg -K
or use --home command-line argument:
gpg --home=/media/something -K
The latter command should now list your private key with sec and not sec#.
At this point, you have a subkey, and you need to send it to the Debian keyserver, if your key is already in the Debian keyring, and the general keyserver network:
gpg --send-key --keyserver keyring.debian.org YOURMASTERKEYID gpg --send-key --keyserver subkeys.pgp.net YOURMASTERKEYID
The upload to the Debian key server only works if your master public key is in the DD or DM keyrings already: the Debian key server accepts updates to existing keys, but not new keys. New keys are added by the keyring maintainers manually. Updates to keys further need a manual update to be added to the actual keyring used by Debian's servers, which usually happens about once a month. (See http://anonscm.debian.org/loggerhead/keyring/debian-keyring/changes to see if your subkey has been added.)
(First time your key gets added to the Debian keyrings: manual, when you get accepted as DD or DM. After that, uploading subkeys to key server: automatic. Copying updates from key server to the Debian keyrings: manual, once a month.)
After this, you should be able to upload packages to Debian using the subkey, rather than the master key.
If your key was already in the backports keyring, you will need to open a ticket in the debian request tracker to ask your key to be refreshed so that you are able to upload to backports.debian.org again.
If disaster strikes, and you need to revoke the subkey for whatever reason, do the following:
- Mount the encrypted USB drive.
gpg --edit-key YOURMASTERKEYID
At the gpg> prompt, list the keys (list), select the unwanted one (key 123), and generate a revocation certificate (revkey), then save.
- Send the updated key to the keyservers as above.