[tor-commits] [metrics-lib/master] Document signing and verifying releases.

[karsten at torproject.org]

commit c3202bdc5d84abf526d11dbde7ab8ffd344d6c54
Author: Karsten Loesing <karsten.loesing at gmx.net>
Date:   Wed Dec 2 14:44:21 2015 +0100

    Document signing and verifying releases.
---
 CONTRIB.md |   84 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md  |   57 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 141 insertions(+)

diff --git a/CONTRIB.md b/CONTRIB.md
index 574c549..62c7cf8 100644
--- a/CONTRIB.md
+++ b/CONTRIB.md
@@ -154,6 +154,90 @@ Regarding version numbers, we'll start with 1.0.0 and bump to 1.0.1,
 previously deprecated feature, making a backwards-incompatible change,
 we'll bump to 2.0.0.
 
+Releases are cryptographically signed on multiple levels: the Git tag
+created for the release is signed using GnuPG, the produced .jar files are
+signed using Java's jarsigner tool, and the produced tarball is again
+signed using GnuPG.  We'll assume that you're familiar with GnuPG and how
+to manage keys for it, but we're including some sample commands for
+managing keys for jarsigner using the less commonly known Java keytool
+below.
+
+First, generate a new key pair and create a certificate that expires after
+90 days using reasonable (yet compatible) cryptographic algorithms and
+parameters:
+
+```
+keytool -genkeypair -alias karsten -keyalg RSA -keysize 2048 \
+    -sigalg SHA256withRSA -validity 90 \
+    -dname "CN=Karsten Loesing, O=The Tor Project\, Inc, L=Cambridge, ST=MA, C=US"
+```
+
+Extend the certificate for the existing key pair when it expires:
+
+```
+keytool -selfcert -alias karsten
+```
+
+Export the certificate to a local file called CERT:
+
+```
+keytool -exportcert -alias karsten -rfc -file CERT
+```
+
+Also, in order to sign releases using Ant, you'll have to create a file
+`build.properties` with content similar to the content below (note that
+without such a file, the Ant targets starting at `signjar` won't work):
+
+```
+jarsigner.alias=karsten
+jarsigner.storepass=password
+```
+
+Putting out a new release requires a series of steps:
+
+Edit `build.xml` and raise the `release.version` property to the desired
+new release.
+
+Edit `CHANGELOG.md` and make sure it contains the correct date for the
+release.
+
+Commit these changes.
+
+Create a signed Git tag for the new release:
+
+```
+git tag -s descriptor-1.0.0 -m "DescripTor 1.0.0"
+```
+
+Push the branch.  Ideally, verify the tag signature by cloning it on
+another system and running the following command:
+
+```
+git verify-tag descriptor-1.0.0
+```
+
+Use Ant to first clean up and then create a tarball containing all sources
+and signed .jar files:
+
+```
+ant clean compile test jar signjar tar
+```
+
+Sign the produced tarball using GnuPG:
+
+```
+gpg --detach-sign --armor --local-user 0x4EFD4FDC3F46D41E \
+    descriptor-1.0.0.tar.gz
+```
+
+Verify the signed tarball, ideally on a different system, as described in
+`README.md`.
+
+Upload the tarball and signature file and announce the new version.
+
+Edit `build.xml` again and raise `release.version` to the current release
+plus `-dev`, e.g., `1.0.0-dev`.
+
 
 Packages
 --------
diff --git a/README.md b/README.md
index cbf2a11..764f143 100644
--- a/README.md
+++ b/README.md
@@ -24,3 +24,60 @@ running, batch-processing applications and not for continuously running
 applications that rely on learning about changes to an underlying
 descriptor source.
 
+
+Verifying releases
+------------------
+
+Releases can be cryptographically verified to get some more confidence that
+they were put together by a Tor developer.  The following steps explain the
+verification process by example.
+
+Download the release tarball and the separate signature file:
+
+```
+wget https://dist.torproject.org/descriptor/1.0.0/descriptor-1.0.0.tar.gz
+wget https://dist.torproject.org/descriptor/1.0.0/descriptor-1.0.0.tar.gz.asc
+```
+
+Attempt to verify the signature on the tarball:
+
+```
+gpg --verify descriptor-1.0.0.tar.gz.asc
+```
+
+If the signature cannot be verified due to the public key of the signer
+not being locally available, download that public key from one of the key
+servers and retry:
+
+```
+gpg --keyserver pgp.mit.edu --recv-key 0x4EFD4FDC3F46D41E
+gpg --verify descriptor-1.0.0.tar.gz.asc
+```
+
+If the signature still cannot be verified, something is wrong!
+
+But note that even if it can be verified, you now only know that the
+signature was made by the person claiming to own this key, which could be
+anyone.  You'll need a trust path to the owner of this key in order to
+trust this signature, but that's clearly out of scope here.  In short,
+your best chance is to meet a Tor developer in real life and enter the web
+of trust.
+
+If you want to go one step further in the verification game, you can
+verify the signature on the .jar files.
+
+Print and then import the provided X.509 certificate:
+
+```
+keytool -printcert -file CERT
+keytool -importcert -alias karsten -file CERT
+```
+
+Verify the signatures on the contained .jar files using Java's jarsigner
+tool:
+
+```
+jarsigner -verify descriptor-1.0.0.jar
+jarsigner -verify descriptor-1.0.0-sources.jar
+```
+