OpenPGP Web of Trust

= OpenPGP Web of Trust = As a distributed, online community grows it develops an increasing need for its members to be able to recognize one another electronically. The OpenPGP Standard is the mechanism preferred for this throughout most of the global free software culture. The OpenStack project relies on OpenPGP signatures for activities such as:


 * Version Control Tags
 * Release Tarballs
 * Security Advisories

= GNU Privacy Guard = While there are a variety of utilities and even devices available to create and manage OpenPGP keys and signatures, this document will provide examples for GNU Privacy Guard (sometimes abbreviated GnuPG or GPG) as the most popular and portable toolset. These recommendations should translate generally to most other solutions as well.

GNU Privacy Guard Installation
Use the latest available GPG 2.X version for your platform (as opposed to the less feature-rich 1.X series). On modern Debian and Red Hat based operating stystems the package name is gnupg2 but the command-line utility is invoked as gpg2.

On embedded systems or other resource-constrained platforms, a recent 1.X version can be installed instead as a lighter-weight alternative. Note that on Debian derivatives, the gnupg (1.X) packages lack HKPS support, so if you want to use them with the example configuration below you'll also need the optional gnupg-curl package.

GNU Privacy Guard Sample Configuration

 * 1) A basic ~/.gnupg/gpg.conf using stronger than default message
 * 2) digests and transport protocols. For the most part, defaults in
 * 3) modern versions are chosen for an optimal balance of security and
 * 4) interoperability, but you may wish to override them in favor of
 * 5) slightly more secure modes of operation. This example should
 * 6) evolve over time, as new cryptographic recommendations emerge and
 * 7) software defaults shift to adopt them.

cert-digest-algo SHA512
 * 1) Use a strong message digest algorithm (not MD5 or SHA1) when
 * 2) signing keys.

personal-digest-preferences SHA512 SHA384 SHA256 SHA224
 * 1) Override the algorithm priority order in recipient key
 * 2) preferences. The first hash in this list is also used when
 * 3) signing without encryption.

default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
 * 1) Define the priority order for hashes, ciphers and compression.

keyserver hkps://hkps.pool.sks-keyservers.net
 * 1) Receive, send and search for keys in the SKS keyservers pool using
 * 2) HKPS (OpenPGP HTTP Keyserver Protocol via TLS/SSL).

keyserver-options ca-cert-file=~/.gnupg/sks-keyservers.netCA.pem
 * 1) Set the path to the public certificate for the
 * 2) sks-keyservers.net CA used to verify connections to servers in
 * 3) the pool above.

keyserver-options no-honor-keyserver-url
 * 1) Ignore keyserver URLs specified in retrieved/refreshed keys
 * 2) so they don't direct you to update from non-HKPS sources.

keyid-format 0xlong
 * 1) Display key IDs in a more accurate 16-digit hexidecimal format
 * 2) and add 0x at the beginning for clarity.

list-options show-uid-validity verify-options show-uid-validity
 * 1) Display the calculated validity of user IDs when listing keys or
 * 2) showing signatures.


 * 1) If you have multiple keys (maybe you replaced an older, weaker
 * 2) one), specify the one you normally use. You can still override
 * 3) this with --local-user when needed.
 * 4) default-key 0xfedcba9876543210

The HKPS configuration above also requires a CA certificate so GPG can confirm the validity of keyservers with which it communicates. Retrieve it with: wget -P ~/.gnupg/ https://sks-keyservers.net/sks-keyservers.netCA.pem{,.asc} Then confirm it's legitimate by verifying the signature provided with it: gpg2 --verify ~/.gnupg/sks-keyservers.netCA.pem{.asc,} The output should indicate that it was made using RSA key 0x0B7F8B60E3EDFAE3.

= Key Generation and Publication = The manpage for gpg2 provides wonderfully detailed usage information, but here's a few tips to get you started if you've not used it before...
 * 1) If you don't have a key already, use gpg2 --gen-key to create one. The Ubuntu community has a great walkthrough you can follow, but the general takeaway is that default key generation options in modern versions of GPG are sane and secure enough so you'll just be hitting the enter key from there on mostly.
 * 2) Some people might feel obligated to choose a 4096-bit key size for extreme future-proofing, but honestly the 2048-bit default should be fine for a while.
 * 3) When it prompts for a real name, you want to make sure you enter one which matches as much as possible what you use on official identification (government-issued photo identification for example).
 * 4) It's best to leave the comment field of the user ID blank unless you need it to clarify your official name in some unusual way.
 * 5) It's really a good idea to encrypt your private key with a strong passphrase you don't use for anything else, but which you can remember--though printing out a recovery key and locking it up somewhere safe is good insurance against forgetting your passphrase.
 * 6) When you're done generating your key, make sure you publish it to the keyserver network! gpg2 --send-key 0xfedcba9876543210 (or whatever your key ID is) should be all you really need if you followed the configuration recommendations earlier.
 * 7) If you don't know your key ID, gpg2 --list-keys you@example.com (substituting an E-mail address you associated with that key) will show you. It's the line which starts out pub followed by the keysize and a letter indicating the key type (it'll be something like 2048R). The hexidecimal number following the slash (/) on that line is your key ID.
 * 8) If you just created your key, or even if you already have a key and you generated it within the last few years (it's probably good enough) there's a great set of recommendations you can use to make your workflow even more secure.
 * 9) If you have a key which is... older... (you know who you are), that dusty old 1024-bit relic with signatures from people you met at conferences a decade ago is not a badge of honor--instead, the cool kids are laughing at you from high atop their shiny new keys. (In summary, 1024-bit keys are no longer considered safe for long-term use.) Generate and transition to something less stale and musty. You'll be glad you did.

= Key Signing Process =

Using a signature to attest to the validity of another key, key signing, is what forms the web of trust. It enables you to determine the relative authenticity of a signature from someone you've never met, based purely on transitive signatures from other people you have met. The OpenStack community holds semi-annual key signing gatherings (following The 'Sassaman-Projected' Method) at its design summits, and scheduling/sign-up is discussed on the development mailing list a month or so in advance.

Ad-hoc key signing is also highly encouraged--conferences and local user group meetings are great places for this too--here are a few suggestions to make this easier...
 * 1) Keep official photo identification with you, appropriate to the setting. If it's an OSUG meet-up, then your local government ID (perhaps a driving license) or possibly even university ID might be fine. If at a large conference with international attendees then a full passport book would be better. The goal is to provide some reassurance to those signing your key that you are who you say you are, so it's best if you have identification with a photo which looks like you, is not trivially falsified/counterfitted, and which is clearly provided by an authority known to the signer so they can hope to confirm its legitimacy. Bringing more than one form of identification can also help.
 * 2) Carry slips of paper or maybe business cards with your name (as it appears on your photo identification and OpenPGP key), along with the associated key fingerprint (which can be obtained by running gpg2 --fingerprint 0xfedcba9876543210 substituting your real key ID in the command). Note that the key ID is itself considered insufficient validation by some signers, since shorter key IDs are relatively easy to counterfit (by brute-forcing key generation to create a new key with a similar/identical ID).
 * 3) When meeting someone whose key you would like to sign, look at their photo identification. Check that the picture on it looks like the person providing it. Check that it at least seems legitimate and comes from an authority known to you in some way (for example, a work badge provided by their employer is unlikely to be a great choice unless you work at the same place, since you probably haven't seen one before and don't know the circumstances under which they're issued). If you're not comfortable with the ID provided ask for an alternate form of identification instead, and feel free to choose not to engage in a key signing unless you're fairly certain of its authenticity. Make a note of the name on the photo ID and get their key fingerprint (this is easy if they brought them already printed out for you), for use later when you will actually sign their key.
 * 4) At some point after the exchange of information and ID verification (could be minutes or months), retrieve their key from a keyserver into your local keyring. This can be accomplished with gpg2 --recv-keys 0xfedcba9876543210 (or whatever their key ID is). Use the command mentioned earlier to see and carefully compare the fingerprint and real name on their key with your notes from the in-person meeting (because there's no certificate authority, manually checking a name and fingerprint is critical to the process). Preferably, use a tool like caff (part of the signing-party package in Debian, Mageia, OpenSuSE and Ubuntu or the pgp-tools package on Fedora, as well as third-party packages available for CentOS and RHEL) to help simplify validation, signing each UID and sending those signatures to the keyholder.
 * 5) When someone sends you a signature of your key, save it somewhere to import with gpg2 --import filename.asc and don't forget to gpg2 --send-key 0xfedcba9876543210 again to show off the new signature!
 * 6) If you find you're doing this a lot, you may want to settle on and publish your own signing policy detailing your personal key signing choices.
 * 7) Did we forgot to insist that you need to manually check the fingerprints of the keys you sign, and make sure it's right? :)