howto: Use the gnu Privacy Guard

This howto is badly out of date and almost entirely obsolete. If you would like to update it, please feel free.

  1. Legal Notices
  2. Introduction
  3. Purpose of this HOWTO
  4. Beginning with GnuPG
  5. The gpg.conf file
  6. Sharing Your Key With the World
  7. Using Other People’s Keys with GnuPG
  8. Using GnuPG with Evolution
  9. Using GnuPG with KMail

Legal notices:

This document is © 2002—2004, Robert J. Hansen.

Permission is granted to copy, distribute and/or modify this document under terms of the GNU Free Documentation License, version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front–Cover Texts, and no Back–Cover Texts. A copy of the license may be found at gnu’s site.

Nothing in this document is deliberately false, but I make no claim of it being completely technically correct. If you find any errors, please email me at rjh at

not legally binding, but …:

If you link to this HOWTO, please email me. That way, if I ever shuffle my site around or switch ISPs, I can keep you updated with changes.

If you’re going to edit this text, please make sure it validates against whatever standard you’re using. Right now it validates just fine against XHTML 1.0 Strict, and I'd like it a lot if it could continue to be an example of a standards–conformant page.


the dangers of email

Almost all of us in the online world use email daily. It’s quick, convenient, and you can check it anywhere in the world you’ve got a computer and a Net connection. Unfortunately, it’s not a very private medium. It was never intended to be.

When you send an email off into the world, it gets handed off to a computer system whose administrators you probably don’t know. From there it gets handed off to another computer system, and another, and another, until somehow it gets to the intended recipient. At any link in this chain, your email can be read—perhaps by an unscrupulous sysadmin who satisfies his delusions of grandeur by peeking into people’s private lives, or by an FBI investigation that’s hoovering up all emails that pass through a site suspected of being used for criminal activity, or … the possibilities are limitless. But what it boils down to is when you send an email, you don’t know who’s going to read it. Your intended recipient, hopefully… but maybe other people, too.

what people decided to do about it

In the early 1990s, a few people decided they didn’t like this state of affairs. Using cryptography—the science of codes and ciphers—they developed software which would transform data into gobbledygook. You’d send this nonsense to your recipient, who would decrypt it and recover the original message. Several people came up with different email encryption standards, from Mark Riordan’s Privacy–Enhanced Mail (PEM) to Phil Zimmermann’s Pretty Good Privacy (PGP) to RSA Data Security, Inc.’s corporate offerings to …


Today things have stabilized to the point where there are only two major competing email encryption standards: PGP and S/MIME. Both of these have undergone IETF standardization processes, and as a result anyone can create their own implementation of either. The IETF standard governing PGP is RFC2440, also called “OpenPGP”.

purpose of this howto:

This HOWTO will teach you how to start working with the GNU Privacy Guard—a complete implementation of OpenPGP. We’ll start from scratch; we’ll create a set of cryptographic keys; and then we’ll start using our keys with Evolution and KMail. We’ll also cover how to share your keys with other people, how to get keys from Internet key databases, and how to use Codebook, a quick and simple app that I wrote to make GnuPG use easier.


It’s very hard to speak accurately about cryptography without using sophisticated math. This is because cryptography is a branch of mathematics. Most people aren’t very comfortable with mathematics, though, and so I’m going to simplify things so that they can be explained in plain English.

While nothing I’m telling you is a lie, there are a lot of places where I’m not going to be telling the whole truth.

beginning with gnupg

getting gnupg

Your distro probably included GnuPG; as of this writing it’s a standard part of Red Hat, Mandrake, Debian, Slackware, SuSE, FreeBSD and more. Even if GnuPG came with your distro, though, please check and see if an update is available. As of this writing, the most recent version of GnuPG is 1.2.4, and that’s the version this HOWTO will cover.

If your distro doesn’t have a GnuPG 1.2.4 package, then try checking out the main GnuPG website at Source downloads and binary packages for many operating systems are available from there.

Once you have GnuPG 1.2.4 installed, we can get this show on the road.

how gnupg works

Please read this section carefully.

Imagine that you have a box with two separate keyholes and two separate keys. One keyhole is used to lock the box; the other key is used to open it. The locking key you give to the world, and the opening key you keep for yourself. If a friend wants to leave you a message, they put their message in the box and lock it using the key you gave them. Later on, you visit the box and unlock it with your own key. You then reach inside and get the message your friend left.

This is a simplification of how encryption works, but all in all it’s reasonably accurate. Just like in the metaphor, GnuPG uses two keys. One key you share with the world (a “public key”). One key you keep for yourself (a “private key”). Anything that is encrypted with the public key can only be decrypted with the private key (and vice–versa, as you’ll find out in the next paragraph). The system is safe only so long as you’re the only one with the private key. As soon as you lose control of the private key, the game is over.

The same math that lets encryption work also lets something called “signing” work. Without going into too much detail, the public and private keys are inverses of each other. If you encrypt something with the public key, only the private key can decrypt it. If you encrypt something with the private key, only the public key can decrypt it. So if you encrypt a message with your private key, anyone with your public key can decrypt it and see your message. This doesn’t sound very important, except for one thing—since you’re the only person who has your private key, you’re the only person who could have encrypted that message. This is what we mean when we talk about “signing” a message; you use the private key to guarantee to the world that a particular message really did come from you, and wasn’t forged.

running gnupg for the first time

Before you can do anything useful with GnuPG, you need to set up GnuPG’s needed directories. You can do this just by typing “gpg” at a command line. You’ll see a few informational messages and then GnuPG will wait for more input—just hit Ctrl–C to break out.

generating a keypair

Once you have GnuPG installed, the first thing to do is generate a keypair. Unfortunately, there are no good GUI–based tools for this (yet—but I am working on it). You have to use the command line. Fortunately, it’s pretty easy:

gpg --gen-key

Once you type this, you’ll see something like:

(Typical GnuPG output)

Unless you really know what you’re doing, choose 1. You’ll now be asked to choose a keysize. At this point you may be asking, “well, what’s a keysize?”

The answer is—it’s a lot of propellerhead nonsense that you don’t need to know about, much less understand, in order to use GnuPG. Unless you’re doing something really dramatic like plotting the overthrow of a government or securing nuclear weapon launch codes, a 1024–bit key is wonderful. I personally use a 1024–bit key with the plain–vanilla GnuPG defaults and I feel perfectly safe with it.

(Sidebar: if you talk to many cryptofreaks, you’ll discover they fall into two categories. There are rational ones who assess cryptography in terms of mathematics and what can be formally proven, and irrational ones who assess it in terms of paranoia and superstition. Rational ones will give a thoughtful nod to my recommendations here. Paranoids will insist that you need a 16,000–bit key in order to be safe. Learning how to tell the two types apart is an important skill.)

GnuPG will now ask you when these keys should expire—that is to say, how long these keys will be usable. Some people think it’s a good idea to have keys expire after a limited time—one year, two years, whatever. Others think it best for keys to last indefinitely. Good arguments exist on both sides of this issue. In the interests of keeping things simple, just type 0 here and your key will never expire.

Now ask you’ll be asked to give your name, email address and a comment. You don’t need to give a comment, but it’s almost always a good idea to give a name and address. For instance:

Real name: Jane Q. Hacker
Email address:
Comment: Chief Sysadmin, Yoyodyne Inc.

Now to select your passphrase!

what’s a passphrase, and why do i need one?

Protecting your private key is extremely important. It’s so important that GnuPG gives you the option of controlling access to your private key with a passphrase. If someone steals your private key, they can’t use it until and unless they also steal your passphrase.

Short passphrases can be brute–forced. As a result, using a single word—or even a pair of words—is usually no protection at all. A safe passphrase is one which is too long to be brute forced, too obscure to be guessed, and easy for you to remember.

back to the show…

Once you choose your passphrase, type it in. GnuPG will ask you to type it again, just to make sure. If you don’t want a passphrase—which is probably a really bad idea—just hit Return at the passphrase prompt.

GnuPG will throw what appears to be a bunch of line noise on your screen. Relax; everything’s going according to plan. The major caveat is if this is your first time running GnuPG, key generation will fail. Just go through this process again if that happens.

Soon, you’ll have a brand spanking new keypair. Wasn’t so difficult, was it? :)

GnuPG will display a few last lines of confusing data and then exit. One of the lines will read “Key fingerprint = ” followed by forty hexadecimal numbers listed in groups of four. Write down the last eight; you’ll need them in the next step.


A well–configured gpg.conf file can save you from worlds of trouble. The following isn’t exactly the configuration file I use, but it’s pretty close:

default–key 5B8709EB
encrypt–to 5B8709EB
keyserver x–hkp://
keyserver–options auto–key–retrieve

… Instead of 5B8709EB you’ll want to use the eight hex digit sequence you just wrote down. You want to use your key as the default, not mine. :) This configuration file will give you excellent interoperability with many different kinds of software, from Network Associates’ PGP 5.0 to PGP Corporation’s PGP 8.0.3.

Also, please note that it’s an eight digit sequence, not two four–digit sequences separated by a space.

how to share your public key:

Remember the metaphor of the lockbox? You want the world to have your public key; you want to keep your private key secret. So how do you share your public key with the world?

There’s an easy way and a hard way. The easy way is … well, easy. :)

The easy way is to use large Internet key databases, called keyservers. Now that you have your gpg.conf file set up properly, using the keyservers is quick, painless and easy. “gpg --send-key” and you’re done!

If you have to do it the hard way—first, relax: it’s not that hard.

If you type “gpg --armor --export > my_public_key.asc”, GnuPG will create a keyfile that you can email to anyone you like. Just send my_public_key.asc as an attachment to people, and they’ll have a copy of your public key. Simple, eh?

how to use others’ public keys:

getting other people’s keys

So what do you do if you get a keyfile attachment? First, save it to disk (for sake of argument, let’s say you save it as “foo_key.asc”). Then type “gpg --import foo_key.asc” and presto—the key is available to GnuPG.

Alternately, if your build of GnuPG has keyserver support, you can ask your recipient for his/her key ID. (Remember how I told you to write down the last eight hex digits of the fingerprint? That’s your key ID. If you forget, type “gpg --list–key”. The first row should read “pub 1024D/xxxxxxxx”. The letters after the “1024D/” are your key ID.)

Once armed with a key ID, you can search the keyservers by typing “gpg --recv–key <keyID>”.

Try it right now. Type “gpg --recv-key 5B8709EB” and, provided all goes well, you’ll import my public key to your keyring.

so who’s all on my keyring, anyway?

Now type “gpg --list-keys”. It’ll give you a listing of all the keys you have on your keyring, along with all the email addresses associated with each key. For instance, type “gpg --list–keys 5B8709EB” and you’ll see my key and all the email addresses I have associated with that key.

(Some people have a lot of email addresses associated with a key. Try importing 09AC0A6A and see how many email addresses he has on his key.)

validating other people’s keys

There’s a big problem with other people’s keys. In email, anybody can pretend to be anybody. If you receive an email that claims to be from your friend Joe, how do you really know it’s from Joe? How do you know this key which claims to belong to Joe really belongs to Joe?

You could call Joe up and ask him if he sent a key. But even if he did—imagine that you have an enemy named Eve who listens in on your email with Joe. When Joe sent you his key, Eve intercepted it and replaced it with her own key. Now, whenever you’re encrypting email to Joe, you’re really encrypting it to Eve. Eve gets the email, decrypts it, reads it, then re–encrypts it with Joe’s key and sends it on to him.

This is called a Man in the Middle attack, and it’s a very real concern. So whenever you get a key, you have to validate the key. That means calling Joe up, or sending a letter, or whatnot, and comparing the key you got against Joe’s own key. Don’t ask Joe in email what his key fingerprint is; if Eve is playing tricks in email, she can screw this one up for you and Joe. Ask in some medium other than email. The telephone is usually a good bet. (If you can’t do this, skip ahead two paragraphs to “What If I Can’t Verify the Key?”.)

You compare keys by comparing key fingerprints. Just like real fingerprints, a key fingerprint is a marker unique to the key which cannot be faked or forged. You can get a key’s fingerprint by giving the command “gpg --list-keys --with-fingerprint”.

Compare the fingerprint of the key you received with the fingerprint of Joe’s key. If the two match, then the next step is to sign Joe’s key. Signing Joe’s key is a way to announce to the world that you’ve checked the key and certify it to be valid. If you later send Joe’s key to the keyservers, or to another person, they’ll be able to look at Joe’s key and see that you’ve signed it. If they trust your judgment, they might be more inclined to trust Joe’s key.

what if i can’t verify the key?

If you can’t verify the key with Joe, for whatever reason, you can locally sign the key instead. A local signing says “I haven’t checked the key, but I believe it to be valid anyway.” If you later send Joe’s key to the keyserver, or to another person, they won’t see your signature on Joe’s key. A local signature is just that—a signature local to your computer.

So now let’s cover how to sign and locally sign keys.

the gpg --edit-key interface

Typing “gpg --edit-key” will bring up a short listing of the properties of Joe’s key, along with an (unhelpful) command prompt. First off, type “help”, just so you can see the staggering options available. The only commands we’re interested in are:

fpr … displays the fingerprint of the key

sign… signs the key with your key

lsign… locally signs the key with your key

trust… sets how much you trust the owner of this key

Now you need to decide if you want your signature to be local or not. Either “sign” or “lsign” as appropriate.

normal signatures

If you choose a normal signature, you’ll be asked to assess how carefully you verified the key, on a 0–3 scale. If you’ve followed all the steps so far, you can answer this one with a 3. GnuPG will ask you for your passphrase; enter it and you’re done. Now that you’ve signed it, you should consider either sending Joe his public key back or sending it to a keyserver. If other people trust you and see your signature on Joe’s key, they’ll be more inclined to trust Joe’s key.

local signatures

If you choose a local signature, you’ll likewise be asked to assess how carefully you verified the key. However, since you haven’t been able to verify the key, answer this one with a 1. GnuPG will ask you for your passphrase; enter it and you’re done. Don’t bother sending Joe his key back, though; since your signature is local, it doesn’t show up to anyone except you.


Remember how I said “if other people trust you and see your signature on Joe’s key, they’ll be more inclined to trust Joe’s key”? The trust interface (which you access by typing “trust”) is how you tell GnuPG which users you trust. When you edit someone’s trust, GnuPG will ask you to evaluate just how much you trust them on a 1–5 scale. A 1 means you don’t know how much you trust them; a 2 means you know for a fact they’re untrustworthy; a 3 means you have some trust in them; a 4 means you trust them completely. Even though GnuPG offers you another trust value, 5, I’d suggest you not use it for any key except your own.

If you get a key that’s signed by someone you trust, you won’t need to validate the signature in order to use the key. GnuPG will see the signature of your trusted friend and think, “Ah! This person has already validated Joe’s key, and I know I can trust them; so I can trust Joe’s key, too.”


You need to go through this process for each key you wish to validate.

using gnupg with evolution:

Now that you’ve got GnuPG set up, configured, and a couple of keys on the keyring, let’s get Evolution set up to use it. I used Evolution 1.4.6 for this.

Getting it working is a pretty straightforward process:

  1. Click on Tools—>Settings to access the Evolution Settings menu.
  2. Click on “Mail Accounts” in the leftmost pane.
  3. Click on one of your mail accounts in the center pane.
  4. Click “Edit” in the button panel on the right. This will bring up the Evolution Account Editor.
  5. Click the far rightmost tab, “Security”, in the Evolution Account Editor window.
  6. Under “PGP/GPG Key ID”, enter your key ID.
  7. Click “Always encrypt to myself when sending encrypted mail”
  8. Click on the others as you like. The others are a matter of personal preference.

If you want to encrypt a message as well as sign it, click on Security–>PGP Encrypt in the Mail Composer window.

using gnupg with kmail:

Making KMail 1.6.2 work with GnuPG is just as easy.

  1. Open up the Configure window (Settings–>Configure KMail).
  2. Click on “Security” in the lefthand window.
  3. Click on the “OpenPGP” tab in the “Security and Privacy Settings” window.
    • In the “Encryption Tool” frame, select “GNU Privacy Guard”.
    • Make sure “Always encrypt to self” and “Automatically encrypt messages whenever possible” are checked.
    • Click on “Apply”.
  4. Click on “Identity” in the lefthand window.
  5. Click on “Advanced” in the “Personal Information” window.
  6. To the right of the label reading “OpenPGP Key”, you’ll see a button labeled “Change”. Click on it, and select your key.
  7. Click “OK”.

… and you’re in business!

Email me.