GPG (Pete's notes)

General

UCAR security policy requires that all sysadmins be capable of reading and writing email messages that are encrypted with PGP. GPG is the Gnu (free) version of PGP. On the Mac, you want to install GPGTools in order to get the command-line "gpg" command. You may also want GPGMail to give Apple Mail GPG capability.

GMail

With GMail, there seem to be two ways to deal with PGP messages:
  1. Mailvelope
  2. Use the Unix command-line to run gpg

decrypt with gpg

With GMail, to decrypt a message, do this:

  1. Make sure you have the keyring mounted, otherwise insert the USB drive and mount the gnupg virtual drive
  2. In GMail, do "show original"
  3. Highlight the PGP part (including the "BEGIN PGP MESSAGE" and "END PGP MESSAGE" lines) and copy it with Command-C
  4. Go to a Terminal window
  5.  
    cat >ttt.txt
  6. Paste the PGP part into the file
  7. Control-D
  8.  
    gpg2 --decrypt <filename>

encrypt with gpg

With GMail, to decrypt a message, do this:

  1. Go to a Terminal window
  2.  
    gpg -ae
  3. When it prompts, enter the recipient's email address
  4. When it prompts, enter "y" to confirm that you want to use the key
  5. When it prompts, enter the text of the message you want to send
  6. It'll output a PGP part. Cut/paste it, (including the "BEGIN PGP MESSAGE" and "END PGP MESSAGE" lines) into the GMail "compose" window

Resources

There are several resources for information about PGP and GPG. Here are the ones I liked best:

Install GPGTools

As of 2013-01, install GPGTools by downloading the installer from http://www.gpgtools.org/.

Clicking on GPGTools.mpkg will take you through the steps. It installs When it's done installing, you should be able to do
gpg --version
...and get 2.0.18 or later.

Install the newest GPGMail

When you installed GPGTools, you installed GPGMail as part of the pagkage. It probably wasn't the latest GPGMail. To see what version of GPGMAil isinstalled, start Apple Mail and do Preferences -> GPGMail. , so install GPGMail separately to be sure you have the latest version. Download the GPGMail installer from http://www.gpgmail.org/.

When you start Mail, you may get a dialog box that says

You don't have any OpenPGP key. You can't use GPGMail to encrypt or sign messages.

If you want to be able to encrypt or sign messages with OpenPGP, you need a personal OpenPGP key. To create a OpenPGP key, download and install MacGPG's GPG Keychain Access from http://macgpg.sourceforge.net/

I think this means that Mail needs access to your PGP private key, which means your USB drive needs to be mounted and the gnupg.dmg disk image needs to be mounted.

Once you're past that, and you've restarted Mail, Mail will read the bundle and you'll see new controls in Mail, like a "PGP" tab under "Preferences".

I learned some of the rest of this at http://www.swissunixsupport.com/mactips. That webpage says that gnupg2 requires that a gpg-agent process be running and that you need a package called pinentry-mac.app to handle display of dialog boxes. I followed the directions and then found that I could decrypt messages even when gpg-agent wasn't running. I got pinentry at http://media.arthurkoziel.com/pinentry-mac.0.02-1.tar.gz. I copied pinentry-mac.app to /Applications, then put this in ~/.gnupg/gpg-agent.conf (create if it doesn't exist):
pinentry-program "/Applications/pinentry-mac.app/Contents/MacOS/pinentry-mac"

Of course, the PGP parts of Mail work better if

Mailing lists for GPGTools problems (Lighthouse)

I have an account at Lighthouse that lets me access the mailing lists for the GPGTools. See 1Password.

Configure GPG

Edit the ~/.gnupg/gpg.conf file. Set:

default-key E4BA9BEC
keyserver hkp://wwwkeys.pgp.net
keyserver-options auto-key-retrieve no-include-revoked

Generate PGP keys

Create your key files in ~/gnupg.
		okapi$ gpg2 --gen-key
		gpg (GnuPG) 1.4.3; Copyright (C) 2006 Free Software Foundation, Inc.
		This program comes with ABSOLUTELY NO WARRANTY.
		This is free software, and you are welcome to redistribute it
		under certain conditions. See the file COPYING for details.

		Please select what kind of key you want:
		(1) DSA and Elgamal (default)
		(2) DSA (sign only)
		(5) RSA (sign only)
		Your selection? 1
		DSA keypair will have 1024 bits.
		ELG-E keys may be between 1024 and 4096 bits long.
		What keysize do you want? (2048)
		Requested keysize is 2048 bits
		Please specify how long the key should be valid.
		0 = key does not expire
		<n>  = key expires in n days
		<n>w = key expires in n weeks
		<n>m = key expires in n months
		<n>y = key expires in n years
		Key is valid for? (0) 0
		Key does not expire at all
		Is this correct? (y/N) y

		You need a user ID to identify your key; the software constructs the user ID
		from the Real Name, Comment and Email Address in this form:
		"Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>"

		Real name: Pete Siemsen
		Email address: siemsen@ucar.edu
		Comment:
		You selected this USER-ID:
		"Pete Siemsen <siemsen@ucar.edu>"

		Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
		You need a Passphrase to protect your secret key.

		We need to generate a lot of random bytes. It is a good idea to perform
		some other action (type on the keyboard, move the mouse, utilize the
		disks) during the prime generation; this gives the random number
		generator a better chance to gain enough entropy.
		+++++++++++++++++++++++++.+++++++++++++++++++++++++++++++++++
		We need to generate a lot of random bytes. It is a good idea to perform
		some other action (type on the keyboard, move the mouse, utilize the
		disks) during the prime generation; this gives the random number
		generator a better chance to gain enough entropy.
		+++++++++++++++.+++++.+++++..++++b+.+++++++++++++++b+++++k..x
		gpg: /Users/siemsen/.gnupg/trustdb.gpg: trustdb created
		gpg: key E4BA9BEC marked as ultimately trusted
		public and secret key created and signed.

		gpg: checking the trustdb
		gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
		gpg: depth: 0  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 1u
		pub   1024D/E4BA9BEC 2006-05-23
		Key fingerprint = D311 1402 4026 21AF 2F81  D861 4172 CF6A E4BA 9BEC
		uid                  Pete Siemsen <siemsen@ucar.edu>
		sub   2048g/331EA98A 2006-05-23

		okapi$
	

Verify your keys with

gpg --fingerprint

Generate a public key with

gpg --export --armor siemsen@ucar.edu > ~/.gnupg/my-key.asc

Register public key with key servers

To allow other users to get your public key, you want to register it with keyservers.

If/when the UCAR hkp server is up, register my public key with the UCAR keyserver:

gpg --send-keys --keyserver hkp://keyserver.ucar.edu E4BA9BEC

Register my public key with the public keyservers:

gpg --send-keys --keyserver pgp.mit.edu E4BA9BEC
gpg --send-keys --keyserver hkp://wwwkeys.pgp.net E4BA9BEC

Register public key with UCAR Security

First, register your public key with the UCAR keyserver as described above. Then get a paper copy of the form and fill in the fields with the key ID and fingerprint displayed by this command:

gpg --fingerprint

Hint: the fingerprint is 10 blocks of 4 hexadecimal characters, and the key ID is the last 8 characters of the fingerprint.

Once accepted, the UCAR security guys will sign the key that you stored in the UCAR keyserver, which verifies that it is valid. Then they'll send me a test email message that is encrypted. I'll have to read the message and respond to it to demonstrate that I can do PGP email.

Managing keys (keyrings and the keychain)

Each person has a public key. To make the key available so others can send encrypted mail to the person, each person should publicize their public key on a keyserver, and/or put their public key on a webpage somewhere. To read signed or encrypted mail sent to you, you need to have the sender's public key. To ease the problem of accessing a lot of other people's public keys, gpg maintains a "public keyring" in ~/gnupg/pubring.gpg. You store people's public keys in your public keyring as you learn them, and the mail reader uses the keys to decrypt incoming mail and/or to verify signatures in incoming mail messages.

The GPG keyring is different than the Mac "keychain", even though the Mac keychain can store PGP keys. Most people don't use the Mac keychain to store public keys - they use the GPG keyring instead. This is mainly because the GPGMail system uses the GPG keyring, not the keychain. As I understand it, there's no benefit to storing public keys in the keychain.

The GPG keyring is stored in ~/.gnupg/pubring.gpg. I need a copy of it on each machine that I readmail on, so I arrange to copy it from cisl-lorient to my other machines where I read mail (cisl-valencia).

There is also a secret GPG keyring, named secring.gpg, in which you store your secret key. It is needed when you want to sign or encrpyt an outgoing mail message. UCAR policy says to store your secret key on an encrypted disk image on a flash drive, so I do that. To minimize the mounting/unmounting of that drive, I copy my secret to gpg-agent when I log in. The details of this are described in the gpg-agent section.

To facilitate sharing keys easily, people can register their keys in a public keyserver. I use one of two keyservers: keyserver.ucar.edu or pgp.mit.edu. The first is the keyserver maintained by the UCAR security guys, and holds the keys of all the UCAR sysadmins. The second is the MIT one that is public.

GPG can be configured to look up keys on one keyserver automatically. GPG won't forward on key lookups - it only talks to one keyserver. I configured GPG to look them up from the UCAR keyserver.

Keys that you retrieve from a keyserver might be bullshit, so after you retrieve a key you have to assign it a "validity" or "trustworthiness" level. Once it's been trusted, Mail with GPGMail can decrypt mail messages from the person. You only have to import a person's public key and then trust it once - the trust level you assign is stored with the key in your public keyring.

Every once in a while, you'll want to update the GPG keyring, aka ~/.gnupg/pubring.gpg so that you can verify signed messages. As of 2014-04-07, I receive signed messages from these people:

As of 2014-04-07, I have their keys in my GPG keyring, so I can verify their signed messages. If I receive a signed message for someone that I don't have in my keyring, here's how to add them:

DO THIS ON CISL-LORIENT, where the "master" pubring.gpg resides, so it gets automatically copied to cisl-valencia when you do the next synchronize-petes-files.

first use the person's email address to find the their key ID:

			cisl-lorient$ gpg2 --search-keys --keyserver hkp://wwwkeys.pgp.net Alex_Hsia@noaa.gov
			gpg: searching for "Alex?Hsia@noaa.gov" from hkp server wwwkeys.pgp.net
			(1)     Alex Hsia 
			1024 bit DSA key 80C14108, created: 2003-03-27
			(2)     Alex Hsia 
			1024 bit DSA key 1D663A0A, created: 2003-03-27
			Keys 1-2 of 2 for "Alex?Hsia@noaa.gov".  Enter number(s), N)ext, or Q)uit > q
			okapi$
		

Then, use the their key ID to load their public key into the keyring:

			cisl-lorient$ gpg2 --recv-keys --keyserver hkp://wwwkeys.pgp.net 0x80C14108
			gpg: requesting key 80C14108 from hkp server wwwkeys.pgp.net
			gpg: key 80C14108: public key "Alex Hsia " imported
			gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
			gpg: depth: 0  valid:   1  signed:   1  trust: 0-, 0q, 0n, 0m, 0f, 1u
			gpg: depth: 1  valid:   1  signed:   0  trust: 0-, 0q, 0n, 0m, 1f, 0u
			gpg: next trustdb check due at 2011-01-22
			gpg: Total number processed: 1
			gpg:               imported: 1
			okapi$
		

After you do that, if you click on another email message in Apple Mail and click back on the original message, Mail should show "The message has been signed with PGP" instead "Missing Key 0xaaaaaaaa".

Managing keys with command lines

To see the keys in your local keyring:

gpg2 --list-keys

To load a key into the local keyring, cut the key id from wherever and paste it into one of these:

gpg2 --recv-keys --keyserver hkp://wwwkeys.pgp.net 0xaaaaaaaa
gpg2 --recv-keys --keyserver hkp://keyserver.ucar.edu 0xaaaaaaaa

To sign a key that's in your keyring:

gpg2 --sign-key AAAAAAAA

To assign a trust level to a key, it's easiest to use GPG Keychain Access.

Managing keys with GPG_Keychain_Access

Use the GPG Keychain Access app to display/import/export/delete them. The alternative is the "gpg" command.

If you want to assign a trust level (a.k.a.) validity, highlight an entry and do GPG->Update Trust Database.... It'll open a Terminal window to ask for the trust level - kludgy. Then, it doesn't let you assign trust levels for a specific key, but only for whatever keys don't have trust levels defined - so how do you change the trust level of a key?

Managing keys with Seahorse

Because GPG_Keychain_Access seems so kludgy, I downloaded Seahorse from http://seahorse.sourceforge.net/.

I got http://ftp.gnome.org/pub/GNOME/sources/seahorse/0.8/seahorse-0.9.1.tar.gz and Stuffit Expander created a seahorse-0.9.1 directory under Desktop. I copied it to /usr/src. When I tried to build it, it complained because XML::Parser wasn't in the Perl libraries. Seahorse seems to have lots of other dependencies, so I gave up. Sigh.

Initialize a "PETES KEYS" flash drive

I keep my SSH keys and my GPG secret keyring on a flash drive. This section describes how to write my secrets to an empty flash drive.

Erase and partition the flash drive

  1. Insert the flash drive into the Mac
  2. Start Disk Utility
  3. Select the flash drive
  4. select the Partition tab
  5. For Volume Scheme, select 1 Partition
  6. Set the Name to PETES KEYS
  7. Set the Format to MS-DOS File System (FAT16)
  8. Click Partition
  9. Click Partition in the pull-down verification box

Copy the gnupg directory to the flash drive

CSAC requires that sysadmins keep their GPG keys on a flashdrive. Greg Woods described how to do it on Macs in PGPUSBFlashFilesystems. Greg's description mentions FAT32, but I use FAT16 because it's just as good for drives smaller than 128GB, it's what the Mac Disk Utility can create, and according to some documentation it avoids weirdness with Finder.

NCAR best practice is to store my GPG secret key on a flashdrive in an encrypted form, so that if I lose the flashdrive, others won't be able to get the key. They recommend creating an AES-encrypted disk image on the flashdrive.

  1. Insert the flash drive into the Mac
  2. Start Disk Utility
  3. File->New->Blank Disk Image...
  4. Set Save As to gnupg
  5. Set Where to PETES KEYS
  6. Set Size to 2.5 MB
  7. Set Encryption to AES-128
  8. Leave Format as read/write disk image
  9. Click Create
  10. set the password to one you'll remember

At this point, you're either creating your primary flashdrive, or making a backup flashdrive. Either way, you need to have a secret keyring file (secring.gpg) to put on the new flashdrive. This file is usually stored only on flashdrives - it is only on the Mac's hard disk while you are in the process of creating flashdrives. When you first create your primary flashdrive, your secring.gpg file is sitting in ~/.gnupg because you created it as described in the Generate PGP keys section of this document. When you are making a backup flashdrive, you need to put a temporary copy of the file onto the Mac's hard disk like so:

  1. insert your primary flashdrive
  2. mount the gnupg disk image
  3. cp /Volumes/gnupg/secring.gpg ~/.gnupg
  4. eject the gnupg disk image
  5. eject the primary flashdrive

Now comes the one-time step: copying the secret key to the flash drive and deleting it from the Mac. From this point forward, you'll need to have your flashdrive inserted in order to sign or decrypt email. Also, to initialize new flashdrives, you'll have to copy the gnupg disk image from one flashdrive to another - like my ssh key, it's not anywhere on the Mac's hard disk.

  1. mount the new flashdrive
  2. mount the gnupg disk image
  3. cp ~/.gnupg/secring.gpg /Volumes/gnupg
  4. rm ~/.gnupg/secring.gpg

Then configure GPG to get the secret key from the flashdrive. Edit ~/.gnupg/gpg.conf and set

#
# I added these 2006-06-02 to implement getting my secret key from my
# flashdrive. See
#
# http://netserver.ucar.edu/intro/staff/siemsen/tools/gpg.html#diskimage
#
no-default-keyring
keyring ~/.gnupg/pubring.gpg
secret-keyring /Volumes/gnupg/secring.gpg

Copy the SSH id_dsa file to the flash drive

See my USB flash drive notes details.

Troubleshooting

Mail doesn't decrypt encrypted messages

Under Mail -> Preferences, GPGMail, under Reading, make sure "Enable OpenPGP/MIME" is checked.

GPG_CONFIG_ERROR_TITLE and/or GPG_CONFIG_ERROR_MESSAGE

This happened to me when I started Mail and I had a symbolic link named "~/.gnupg/secring.gpg" that pointed to "/Volumes/gnupg/secring.gpg" (on a USB drive) and I didn't have the USB drive mounted and the "gnupg" dmg mounted. Mounting them and restarting Mail made the error go away.

GPG Config Error - Ups, something went wrong. GPG was found on your system but there seems to be a problem with the config file. Please contact the GPGTools team http://www.gpgtools.org/about/html.

This happened to me when installing GPGTools and when trying to start /Applications/GPG Keychain Access.app when I had a symbolic link named "~/.gnupg/secring.gpg" that pointed to "/Volumes/gnupg/secring.gpg" (on a USB drive) and I didn't have the USB drive mounted and the "gnupg" dmg mounted. Mounting them and restarting Mail made the error go away.

Missing Key

If, when you click "Verify", Mail displays "Missing Key 0xaaaaaaaa", then you need to load the person's public key into your local public keyring. I use the command line. You can get the person's key from a keyserver, or as a block of text that you get from the person's webpage or something.

No Secret Key

If, when you click "Decrypt", Mail displays "<Name> no secret key", then you probably don't have the flashdrive mounted. Put the flash drive into the slot and do

open /Volumes/PETES\ KEYS\gnupg.dmg
Enter the password. Then try again.

PGP Encryption Failed

If, when signing or encrypting an an outbound message, you get a dialog box that says

PGP Encryption Failed

No valid personal key has been found. Either none
was selected, or selected key is revoked, disabled or
has expired.

Mail couldn't find your personal secret key, probably because you don't have the flashdrive mounted. Put the flash drive into the slot and do

open /Volumes/PETES\ KEYS\gnupg.dmg
Enter the password. Then try again.

gpg-agent

Briefly, gpg-agent is a superset of ssh-agent - it stores secret (priavate) keys in a process so you don't have to keep a sensitive file mounted all the time.

As described above, UCAR policy says my secret key has to be stored in an inconvenient place: in a secret keyring on an encrypted drive on a USB flash drive. This means that to use PGP, I have to go through this Royal Pain:

  1. physically insert the USB drive
  2. open it and double-click on the gnupg drive
  3. type a password to decrypt the subdrive
  4. start Mail
  5. don't pull out the USB drive
To make it worse, I have to tell Mail/GPGMail where the secret keyring is by configuring my gpg.conf file with "secret-keyring /Volumes/gnupg/secring.gpg". If that drive isn't mounted when I start Mail, it will generate error messages and Mail becomes unreliable (crashes every so often).

This is so onerous that people wouldn't use PGP at all, so someone came up with a solution: gpg-agent. Gpg-agent is a daemon that stores your secret key so you have to go through the Royal Pain much less often. You endure the Royal Pain once at login time to save the key in gpg-agent. Then Mail/GPGMail and the rest of the gpg system gets the key from gpg-agent. The GPGTools folks anticipated that you'll do this, so they set up gpg-agent for you - it's started as a launchd daemon at boot time. The trick is to get your secret key into gpg-agent at login time.

So we assume gpg-agent is already running, and we just have to load our secret key into it. The new Less Royal Pain procedure is

  1. physically insert the USB drive
  2. open it and double-click on the gnupg drive
  3. type a password to decrypt the subdrive
  4. load the secret key into gpg-agent
  5. unmount the subdrive
  6. unmount the USB drive
  7. pull out the USB drive
  8. start and stop Mail as often as you like

To load the secret key into gpg-agent,

ABKey: MacGPG integration with Address Book

ABKey is a plug-in for Address Book that shows GPG information in Address Book entries. See http://www.far-blue.co.uk/projects/keymanager.html. It works, but as the author warns, you have to move the mouse over an email address in an Address Book entry to activate it.


Address comments or questions about this Web page to the siemsen@ucar.edu.
Last modified: Thu Nov 9 14:56:49 MST 2006