Release signing is not so difficult as it seems. The basics are simple:
- install the right tool
- generate a public/private gpg key (similar but distinct from your SSH keypair) using that tool
- add your public key to the KEYS file in the avalon CVS module (using copy-paste) and commit it
- use the tool to generate a special signature file for each distribution file. That signature can be used to verify that the distribution is official (ie it really came from us).
1. Get the right tool
I use GnuPG for all my keysigning work. It is a commandline utility available for linux, various unixes, windows, and cygwin. If you're on linux or you have cygwin, chances are it is already installed for you. The windows distribution currently resides at ftp://ftp.gnupg.org/gcrypt/binary/, but check http://www.gnupg.org/ for the latest files. You should at least glance at the GnuPG manual to get yourself started. Its pretty good and easy to follow.
2. Generate your keypair
Use the command
to generate your keys. The console UI is pretty easy to follow. Basically, you need to enter some information about yourself that uniquely identifies you. Note you only need to generate your key once, just like with SSH.
Next, you should generate what is called a *revocation certificate*. You'll need that in case your private key is compromised. It is an authoritive way to tell others your key has been hacked. Here's how you generate it:
gpg --armor --output revoke.asc --gen-revoke 'Your Name'
where you replace 'Your Name' with the name you entered when you generated the key. '--armor' means "give me textual (ASCII) output. '--output revoke.asc' means 'save the result in revoke.asc'. '--gen-revoke' is the command we give gpg, and 'Your Name' tells gpg which key you want to generate the revocation certificate for. Now print the generated revoke.asc file, and then erase it (not put it in the recycle bin, really erase it). Keep the printed copy in a safe place.
3. Add your public key to the KEYS file
Use gpg to export your public key into ascii format, then add that to the bottom of the avalon KEYS file:
gpg --armor --output my.public.gpg.key --export 'Your Name' echo >> ~/cvs/avalon/KEYS echo my.public.gpg.key >> ~/cvs/avalon/KEYS cd ~/cvs/avalon/KEYS cvs commit -m 'adding my public gpg key' KEYS
where you replace 'Your Name' with the name you entered when you generated the key. The above is mostly the unix version of "copy/paste the generated my.public.gpg.key file at the bottom of the KEYS file, then commit", but you can use any editor / cvs client to do this.
4. Use the tool to sign the distributions
Use gpg to sign the distribution files:
gpg --armor --detach-sig --output avalon-dagger-1.2.zip.asc avalon-dagger-1.2.zip
'--armor' selects ASCII output again. '--detach-sig' tells gpg not to scramble the distribution file, but rather to generate a seperate signature file. '--output blah' tells gpg to save the result to a file. The final argument is the file to sign.
entering this command and then your passphrase every time for every distribution file can become cumbersome. I wrote a simple shell script that will scan for all releases (it assumes a maven-style build structure with distributions in ./target/distributions and jars in ./target) and generate signatures for all these files. You will have to type your private key password for every file. Here's a sample usage:
cp sign.sh ~/cvs/avalon cd ~/cvs/avalon/dagger maven clean maven dist cd .. . ./sign.sh
You can find this sign.sh script in avalon-components cvs: http://cvs.apache.org/viewcvs.cgi/avalon-components/sign.sh. Using this script, you still need to enter your passphrase for every file. Since that is very annoying if you have to sign many files, you can temporarily disable your private key password. Before doing so, make sure your PC is disconnected from any network. Here's how (roughly, make sure you read the directions on screen):
gpg --edit-key 'Your Name' > key 1 > passwd <Enter your passphrase> <enter> <enter> yes > quit yes
where you replace 'Your Name' with the name you entered when you generated your key. 'key 1' tells gpg you want to edit the first key on your chain (my wild guess is that you have only one). 'passwd' tells gpg that what you want to change for this key is the password. After entering your old password, you enter an empty one twice. You'll have to confirm that as its a bad idea in general. Confirm, then quit, saving your changes.
Now, you can run the sign.sh script. After that, *put your password back on the key immmediately*:
gpg --edit-key 'Your Name' > key 1 > passwd <Enter your passphrase> <Enter your passphrase> > quit yes
you should be able to guess what the above means. After you've reinstated the password protection, you can reconnect your computer.
Not that difficult at all, is it?