GnuPG/en

This small guide will teach you the basics of using GnuPG, a tool for secure communication.

What you will get in this guide
This guide assumes that you are familiar with public-key cryptography, encryption, and digital signatures. If this is not the case take a look at the GnuPG handbook, chapter 2, and then come back.

This guide will teach you how to install GnuPG, how to create your key pair, how to add keys to your keyring, how to submit your public key to a key server and how to sign, encrypt, verify or decode messages you send or receive. You will also learn how to encrypt files on your local computer to prevent people from reading their contents.

Other software
At a very basic level you need to emerge gnupg. Many applications today have some sort of support for gpg, so having  as a USE variable is a good idea. If you wish to have an email client capable of using gnupg you can use, , Mozilla Thunderbird , evolution (a GNOME Microsoft Outlook work alike; ) and KDE's own KMail.

Installing Kgpg might interest you if you use KDE. This small program allows you to generate key pairs, import keys from ASCII files, sign imported keys, export keys and a few more features.

Creating your key
To create your key, just run gpg --gen-key. The first time you run it, it will create some directories; run it again to create the keys:

Here you can choose the type of key you want to use. Most users will go for the default RSA and RSA. Next is the key size - remember that bigger is better but don't use a size larger than 2048 with DSA/ElGamal keys. Generally 2048 is more than enough for normal email.

After size comes the expiration date. Here smaller is better, but most users can go for a key that never expires or to something like 2 or 3 years.

Now it is time to enter some personal information about yourself. If you are going to send your public key to other people you have to use your real email address here.

Now enter your key passphrase twice. It is a good idea to use a strong password. If someone ever gets hold of your private key and cracks your password, they will be able to send messages signed by "you", making everyone believe the mails were sent by you.

Next, GnuPG will generate your key. Moving the mouse or having a mp3 playing in the background will help speed up the process because it generates random data.

Generating a revocation certificate
After creating your keys you should create a revocation certificate. Doing this allows you to revoke your key in case something nasty happens to your key (someone gets hold of your key/passphrase).

The gpg --list-keys command lists keys in your public keyring. You may use it to see the ID of your key so that you can create the revocation certificate. Now it is a good idea to copy all the .gnupg directory and the revocation certificate (in ASCII armor - ) to some secure medium (two floppy's or a CD-R you store in safe location). Remember that can be used to revoke your keys and make them unusable in the future.

Exporting keys
To export your key, you type gpg --armor --output john.asc --export john@nowhere.someplace.flick. You can almost always use the key ID or something that identifies the key (here we used an email address). John now has a that he can send his friends, or place on his web page so that people can communicate safely with him.

Importing keys
To add files to your public keyring, you must first import it, then check the key fingerprint. After you have verified the fingerprint you should validate it.

Now we will be adding Luis Pinto's (a friend of mine) public key to our public keyring. After giving him a call and asking him for his key fingerprint, I compare the fingerprint with the output of the fpr command. As the key is authentic, I add it to the public keyring. In this particular case, Luis's key will expire in 2003-12-01 so I am asked if I want my signature on his key to expire at the same time.

Sending keys to keyservers
Now that you have your key, it is probably a good idea to send it to the world key server. There are a lot of keyservers in the world and most of them exchange keys between them. Here we are going to send John Doe's key to the keys.gnupg.net server. This uses HTTP, so if you need to use a proxy for HTTP traffic don't forget to set it ( export http_proxy= http://proxy_host:port/ ). The command for sending the key is: gpg --keyserver keys.gnupg.net --keyserver-options honor-http-proxy --send-key 75447B14 where 75447B14 is the key ID. If you don't need a HTTP proxy you can remove the --keyserver-options honor-http-proxy option.

You can also send other people's keys that you have signed to the keyserver. We could send Luis Pinto's key to the keyserver. This way someone who trusts your key can use the signature that you have placed there to trust Luis's key.

Getting Keys from keyservers
Now we are going to search for Gustavo Felisberto's key and add it to the keyring of Larry the cow (just in case you did not notice Gustavo Felisberto is the author this guide :)).

As you can see from the server response I have a few keys submitted to the key server, but I currently only use B9F2D52A. Now John Doe can get it and sign it if he trusts it.

What is a GPG Agent?
Sometimes working with certain applications requires you to use your GPG key very frequently, which means that you have to type your passphrase a lot of times. Several applications used to support a passphrase caching mechanism to make life easier for users. However, this disallowed sharing this cache across programs (how secure would that be?) and forced applications to reinvent the wheel over and over again.

A GPG agent is a separate application that GPG uses to cache the passphrase in a standard and secure way. It allows applications to use GPG concurrently: if you enter your passphrase while working in one application, the other application can work with GPG without reiterating the request for the passphrase to unlock the key - if the GPG agent is configured to allow so, of course.

Gentoo provides a few GPG agent applications. The package contains what could be considered the reference one, and will be the one we'll use in this document.

Configuring gpg-agent and pinentry
GnuPG includes. Pinentry is a helper application that gpg-agent uses to request the passphrase in a graphical window. It comes in three flavors: it can popup a window using the gtk+, Qt, or curses libraries (depending on the USE flags set in ).

If you installed with more than one popup window type, it is possible to choose between them with the eselect pinentry command:

Now create a file called and enter the following lines which define the default timeout of the passphrase (e.g. 30 minutes) and the application to be called for when the passphrase should be retrieved the first time (e.g. the gtk+ version of pinentry).

Now configure GnuPG to use an agent when appropriate. Edit and add the following line:

Now your system is (almost) set to use the GPG agent.

Automatically Starting the GPG Agent
If you use KDE as your graphical environment, edit and uncomment the following (system-wide) or  (local user) and add the following command to it to have KDE automatically starting the GPG agent:

Additionally, uncomment the following in (system-wide) or add it to  (local user):

If you use a different graphical environment, put that line (the same one as mentioned above) in (if you use  ) or  (if you use XDM/GDM/KDM/...).

Encrypting and signing
Let's say that you have a file that you wish to send Luis. You can encrypt it, sign it, or encrypt it and sign it. Encrypting means that only Luis will be able to open it. The signature tells Luis that it was really you who created the file.

The next three commands will do just that, encrypt, sign and encrypt/sign.

This will create binary files. If you wish to create ASCII files, just add a --clearsign option to the beginning of the command.

Decrypting and verifying signatures
Suppose that you have received a file which is encrypted to you. The command used to decrypt it is gpg --output document --decrypt encrypted_doc.gpg. This will decrypt the document and verify the signature (if there is one).

Encrypting and decrypting without keys
It is also possible to encrypt files using passwords instead of keys. Well, the password itself will function as the key - it will be used as a symmetric cypher. You can encrypt the file using gpg --symmetric ; decrypting uses the same command as we talked about before.

GnuPG will ask for a passphrase and a passphrase verification.

Advanced Features
There are some nice advanced features in GnuPG. To find them, open the file.

Search for the above two lines and uncomment them. With this any time GnuPG needs to check a signature and it does not find the public key on the local keyring it will contact the key server at keys.gnupg.net and will try to fetch it from there.

Another nice command is gpg --refresh-keys. This will contact the keyserver defined in the options file and refresh public keys in your local key ring from there, searching for revoked keys, new IDs, and new signatures on keys. You should probably run this once or twice a month so that if someone revokes his key you will be notified.

About email signatures
95% of the time you will use GnuPG with email, signing/encrypting your outgoing messages and reading signed/encrypted messages. So it is only fair that I talk about that first.

There are two ways two sign/encrypt a email with GnuPG, the old way and the new way. In the old way messages would appear in plain text, with no possible formatting and attached files would be unsigned/unencrypted. Here is an example of a message signed the old way:

Messages this way are no good in today's world, where we have nice GUIs and email readers that understand html.

To solve this an addition to the MIME (Multipurpose Internet Mail Extensions) was created. This adds a field to the email that tells the mail reader that the full content of the message is signed and/or encrypted. The problem with this is that not all mail readers support this. And some even mess up the content; Microsoft's Outlook is famous for not working with this.

Kgpg
Kgpg is a nice GUI for GnuPG. In the main screen you can paste the text that you wish to sign or encrypt, and you can also paste the ASCII armored text that you wish to decrypt.

From within the main screen you can decrypt text (you will have to provide your password), encrypt other files, paste new text to sign....

Seahorse
Seahorse aims to be a GnuPG GUI interface for the Gnome desktop. The software has been evolving fast, but it still lacks many important features that can be found in Kgpg or the command line version.

KMail
If you have the  USE flag set, KMail will be compiled with gpg support, and will be able to encrypt and decrypt inline PGP mails automatically as well as encrypting OpenPGP/MIME mails. If you want to decrypt OpenPGP/MIME mails as well (which you probably want) you need to have a running GPG agent.

To verify if KMail is properly configured navigate to. You should see a GpgME-based backend listed and you should be able to fill the OpenPGP checkbox. If it is listed but grayed out, click on. If the GpgME-based backend remains grayed out, KMail is not working properly.

If you still are unable to get KMail to behave, please see the KMail PGP HowTo page for more information.

Claws-Mail
This mail reader is very fast with big mailboxes, has all the nice features one wants in mail readers and works well with gpg. The only problem is that it does not work with the old PGP signatures, so when receiving those kind of mails the signatures must be hand checked.

To use your gpg key with Claws-Mail navigate to. Once there just choose which key to use, probably most users will go with the default key.

Some problems
I had some problems with photos in keys. Check the version you are using. If you have GnuPG 1.2.1-r1 and up you are probably OK, older versions may have problems. Also most keyservers don't like keys with photos, so you are better if you don't add photos.

The latest versions of gnupg don't seem to work with the gpg --send-keys that was used so send all keys in your keyring to the public server.

What is not here
is a very complex tool, it lets you do much more than what I have covered here. This document is for the user who is new to GnuPG. For more information, you should check the GnuPG Website.

I did not write about other tools like,  ,   and maybe Windows tools, but I will probably extend this document in the future.

Credits
John Michael Ashley's GnuPG Handbook it is a very good book for beginners.

Swift (Sven Vermeulen) for pushing me to re-write this.

Everyone in the #gentoo-doc team you guys rock.

Tiago Serra for getting me back to the privacy track.