HOWTO: Use the GNU Privacy Guard

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

Legal Notices

This document is (c) 2002, 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 cortana at


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.1, and that's the version this HOWTO will cover.

If your distro doesn't have a GnuPG 1.2.1 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.1 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:

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 2048-bit key is wonderful. I personally use a 3072-bit key, but don't think for a moment that I do so because I think it's necessary.

(Footnote: 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 of nigh-apocalyptic importance. 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.

The ~/.gnupg/gpg.conf file

A well-configured gpg.conf file can save you from worlds of trouble. So let me show you the gpg.conf file I use:

... Instead of 2CBE2E25 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. :)

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 2CBE2E25'' 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 2CBE2E25'' 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-key --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

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.

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 every 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.0.8 while writing this; Evolution 1.2 and 2.0 may be slightly different, but should be mostly similar.

Getting it working is a pretty straightforward process:

  1. Open up the Mail Settings window (Tools->Mail Settings).
  2. Select the ``Other'' tab.
  3. In the ``PGP Binary Path'' entrybox, enter the full path to GnuPG (usually /usr/bin/gpg).
  4. Click on the "Accounts" tab.
  5. Select the correct email account and click Edit to open the Evolution Account Editor.
  6. In the Evolution Account Editor, click Security.
From now on, whenever you send email out from that email account, you'll be signing it with your GnuPG key.

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

Using GnuPG with KMail

Making KMail 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 all four checkboxes in the ``Options'' frame 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!

If you wish to encrypt a message as well as sign it, click on the Encrypt button in the mail composition toolbar.

Using GnuPG with Codebook

Codebook is a small app that I wrote to make GnuPG easier to use with programs which don't have GnuPG support built in. You can download it from my home page, in either source form or a Mandrake 9.0 RPM. In source form you'll need Gtkmm-2.0 (available from SourceForge) and a CVS snapshot of GPGME (available at the GnuPG site). In RPM form you'll need Gtkmm-2.0 and GPGME RPMs installed; both should be available from Mandrake Cooker.

Fire it up and you'll see a simple four-panel window, much like this:

First tab of Codebook

All you have to do is select your recipients one at a time, either by double-clicking on their menu entry or single-clicking and then clicking ``Add encryption key''. The next page is very similar:

Second tab of Codebook

Here you do likewise, but here you select which keys you wish to sign with. In the third tab, you enter your text and click on the proper button. The button will be labeled with "Encrypt" if you have only recipients; "Sign" if you only have signers; "Encrypt and Sign" if you have both; and "Decrypt and/or Verify" if you have neither. Whatever the button says it'll do, that's what Codebook will do. If you want to change what the button says, change your recipients, signers, etc.

This may seem slightly awkward, but it's a conscious design decision. When you click the button, you know exactly what it's going to do; there's no doubt as to whether or not you have it set up correctly for a given task.

Third tab of Codebook

And finally, in the fourth tab you see the result of your operation.

Fourth tab of Codebook

You can cut-and-paste (using standard X highlight-and-middle-click) into and out of the input buffer; and you can cut-and-paste out of the output buffer.

As a word of warning, Codebook is in a 0.3.2 release and is nowhere near done. For instance, it doesn't do signature verification for now. Watch this space; it's still a work in progress.