GnuPG

This small guide will teach Gentoo Linux users the basics of using GnuPG; a tool for secure communication.

What readers will get from this guide
This guide assumes the reader is familiar with public-key cryptography, encryption, and digital signatures. If this is not the case take a look at the official GnuPG handbook, specifically the second chapter, and then come back to this article.

This guide provides instructions to Gentoo users on how to install GnuPG, create a key pair, add keys to a keyring, submit a public key to a key server, how to sign, encrypt, verify or decode messages both sent and received. Readers will also learn how to encrypt files in order to prevent others from reading the content of the messages.

Basic public key cryptography
The concept of public key cryptography was originally devised by Whitfield Diffie and Martin Hellman in 1976. When I first heard the words "public key" and "cryptography" in the same sentence back in '93 I thought to myself that it would be impossible to do such a thing. In those days there was no Internet (well there was, but not for me) so I went to the public library and asked for books on Cryptography. I must say that I was 16 at the time so the clerk there looked to me in astonishment and brought me a book for children on substitution cyphers (those where you change a letter for another like the famous Caesar Cypher or ROT-13 (Tragbb Ebpxf, naq lbh xabj vg vf tbbq orpnhfr lbh ner ernqvat guvf qbp.), emerge rotix if the preceding text not be read). I was very upset with this and started to search for more info. It is good to have mathematicians in the family, because as soon as I talked to one of them I was introduced to a new world.

And now a bit of mathematics:

If I give you the number 35 and I tell you that this number is the product of two prime numbers it is easy to find that it was 5 and 7. But if I tell you the same for 1588522601 you will spend a lot of time (or CPU cycles) to find it was 49811*31891. And if this number is really really big this task becomes "impossible". So now if I give the world my large number that is the product of two primes I know something about that number that no one else knows.

This is the basis for Public Key Cryptography (PKC) implementations today. As an (unrealistic) example, I give anyone my number and that someone will use if for cyphering a message to me. Anyone can see the cyphered message, because I am the only one who knows a shortcut to read it, anyone else will first have to "split" that big number to be able to read the message, and it is a "fact" that it is impossible to do that in a short amount of time (today's methods and the fastest computers in the world would take thousands of years to do that). In this setup the two large prime numbers would be called the PRIVATE KEY, and the large non prime number is the PUBLIC KEY.

In practice this is not 100% accurate with reality, but will give a good idea to the newcomer. For more information, check Wikipedia on the Diffie-Hellman protocol. For even more info go to the public library and grab a copy of the "Handbook of Applied Cryptography" by Alfred J. Menezes, Paul C. van Oorschot and Scott A. Vanstone. This book is also available online for free at the above site.

One consequence of the above is that if you cypher a message to me, and you loose the original uncyphered message you will no longer be able to retrieve it from the cyphered version.

Signatures
From this article it is possible to see how a user can send a cyphered message if they have a public key, but how does one know that the author of the message is really who they claim to be? Or in other words: If Larry receives an email from Luic how do I really know it was you and not someone else claiming to be you?

Remember me saying that PKC was not as simple as I had said? The idea is that when you cypher a message to me you sign it with your private key so that, when I receive it, I can first use your public key to check your signature and then use my private key to decypher the message. As you can see we could not do that in the setup I described before.

It's also very important to sign messages so that you don't have to cypher them beforehand. Now you can create messages that can be read by anyone, but that come with your "branding". And if any single character is changed in the message it can (and will) be detected.

Key servers and signed keys
But let's say that I have no previous contact with you until you send me a message: how do I get your public key, and how do I really know it is yours?

To solve this problem public Key Servers were created. When you create your key pair (Public and Private key), you send your public key to the key server. After this everyone can retrieve your key from there. This solves the problem of finding the key. But how do I really know that that key is the author's key? For this another concept must be introduced, and that is key signing:

Key signing means that if I have the public key of another person, and I know for sure that it is really that persons key (it is my personal friend, someone I know in real life, etc.) I can sign that public key and send it to key servers, that way I am telling the world: "This key really belongs to the person it claims to belong.". That way persons that have my public key and trust me can use that trust to trust other keys.

This can sometimes be confusing so lets see a real world situation.

Let's imagine a 3 person situation: John, Mary, and Lisa. John is a good friend of Mary but does not know Lisa; Lisa is a good friend of Mary but does not know John. One day Lisa sends John a signed email. John will fetch Lisa's Public Key from the key server and test the message, if all went ok he will see that whoever wrote that message also created that key. But how do I know it was really the person it claims to be?

He then sees that it is signed by Mary, which he can check because he already has Mary's key and he trusts that key. With this ring of trust he continues to conclude that the email he received was really written by Lisa.

You are now ready to use this guide, you can go back to chapter 1 and learn how to use GPG.

Other software
At a very basic level GnuPG must be emerged. Many applications today have some sort of support for PGP, so having  as a USE variable is a good idea. When desiring an email client capable of using GnuPG any of the following options are well suited:
 * PinePGP ;
 * Mutt — A small but very powerful text-based mail client;
 * Thunderbird — Mozilla's e-mail solution;
 * Evolution — A GNOME Microsoft Outlook work alike;
 * KMail — KDE's mail client.

Installing Kgpg might be of interest if using the KDE desktop enviroment. This small program allows for the generation key pairs, importing of keys from ASCII files, signing imported keys, exporting keys, among a few other features.

Creating a key
To create a key, use the gpg --gen-key command. The first time it is ran, it will create some directories essential to the correct operation and implementation of GnuPG; run it again to create the keys:

Here the type of key can be chosen. Most users will go for the default RSA and RSA. Next is the key size — remember that bigger is better but do not use a size larger than 2048 with DSA/ElGamal keys. Generally 2048 is more than enough for normal email communication.

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

Now it is time to enter some personal information about the key's user. When sending a public key to other users it is important to an real email address here (as opposed to a fake e-mail address).

Now enter a key passphrase twice. It is a good idea to use a strong password. If someone is able to get a hold of the associated private key and cracks the password they will be able to impersonate the user by sending signed messages just as the user would. The malicious user could dupe the victims contacts into believing the e-mails or messages were sent by the victim. This could cause major problems.

Next, GnuPG will generate a key. Moving the mouse, browsing the web, or having streaming audio in the background will help speed up the process because will help GnuPG generate random data thereby increasing the security of the key pair.

Generating a revocation certificate
After creating the keys a revocation certificate should be created. Doing this allows the user to revoke the key in case something nasty happens (think of a malicious user gaining control of the key/passphrase).

The gpg --list-keys command lists keys in the public keyring. It may be used to see the ID of the key so that a revocation certificate can be created. It is a good idea to copy the entire directory and the revocation certificate (in ASCII armor - ) to some secure medium (a CD-R or a USB drive stored in a safe location). Remember that the file can be used to revoke the keys and make them unusable in the future.

Exporting keys
To export a key, type gpg --armor --output larry.asc --export Larry@TheBarn.someplace.flick. You can almost always use the key ID or something that identifies the key (in this example an email address was used). Larry now has a that he can send his friends, or place on his web page so that others can communicate safely with him.

Importing keys
To add files to a public keyring the following steps should be taken:
 * 1) Import it the key;
 * 2) Check the key fingerprint;
 * 3) After verifying the fingerprint, 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 key servers
Now that a key has been generated, it is probably a good idea to send it to a world key server. There are a lot of key servers in the world and most of them exchange keys. In this next example Larry the cow's key will be sent to the keys.gnupg.net server. Sending keys uses HTTP, so if a proxy is used for HTTP traffic do not forget to set it accordingly (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  is the key ID. If a HTTP proxy is not needed then the  option can be removed.

Sending other people's keys that Larry has signed signed to the key server is also a good idea. We could send Luis Pinto's key to the key server. This way someone who trusts Larry's key can use the signature that he has placed there to trust Luis's key.

Getting keys from key servers
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 :)).

From the server response it is possible to see few keys have been submitted to the key server, however only  is used. Now Larry the cow can get the key and sign it if he trusts it.

What is a GPG agent?
Sometimes working with certain applications requires the use of a GPG key very frequently, which means that a passphrase must be frequently entered. In the past many applications supported a passphrase caching mechanism. This would make life easier for users because passphrases were automatically entered. 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 the passphrase is entered 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 primary choice used in this article.

Configuring gpg-agent and pinentry
GnuPG includes gpg-agent. Pinentry is a helper application that gpg-agent</tt> 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 was installed with more than one popup window type, it is possible to choose between the windows with the eselect pinentry</tt> 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 the system is (almost) ready to use the GPG agent.

Automatically starting the GPG agent
If KDE is used as the desktop environment, edit the following (system-wide) or  (local user) file. Add the following command to the appropriate file to have KDE automatically starting the GPG Agent:

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

When using a desktop environment other than KDE, put that line (the same as mentioned above) in the file (if the startx</tt> command is used to invoke the GUI) or the  file (if XDM, GDM, KDM are used).

Encrypting and signing
Lets say that Larry has a file he wishes to send Luis. Larry 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 Larry who created the file.

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

This will create binary files. When wishing to create ASCII files, just add a  option to the beginning of the command.

Decrypting and verifying signatures
Suppose that Larry has received a file which is encrypted to him. The command used to decrypt it is gpg --output document --decrypt encrypted_doc.gpg</tt>. This will decrypt the document and verify the signature (if there is one).

Encrypting and decrypting without keys
It is possible to encrypt files using passwords instead of keys. The password itself will function as the key — it will be used as a symmetric cypher. The file can be encrypted using gpg --symmetric</tt>; decrypting uses the same command as mentioned previously.

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 modification made, any time GnuPG needs to check a signature and does not find the public key on the local keyring it will contact the key server at keys.gnupg.net in attempt to fetch the public key from from the server.

Another nice command is gpg --refresh-keys</tt>. This will contact the key server defined in the configuration file and refresh the public keys in the local key ring from there. It is capable of searching for revoked keys, new IDs, and new signatures on keys. It is a wise idea run this command once or twice a month; if a user revokes their key this can provide a notification the key can no longer be trusted.

About email signatures
95% of the time GnuPG is used with email by signing/encrypting outgoing messages or reading signed/encrypted messages.

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 not good in today's world, where there are 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 such features. Some even mess up the content (Microsoft's Outlook is famous for not working with this).

Kgpg
Kgpg is a wonderful GUI for GnuPG. The main screen provides an area to paste text to signed or encrypted, the reverse is also true; ASCII armored text to be decrypted can also be entered.

From within the main screen text decrypted (a password is needed), files encrypted, and pasted text can be signed.

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 the  USE flag is 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. To decrypt OpenPGP/MIME mails as well (most users want) a GPG agent must be running.

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

When unable to get KMail to behave, see the official KMail PGP 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 a GPG key with Claws-Mail navigate to. Once there choose which key to use, most users should 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 key servers do not like keys with photos, so you are better if you don't add photos.

The latest versions of GnuPG do not seem to work with the gpg --send-keys</tt> that was used to send all keys in a keyring to the public server.

What is not here
gpg</tt> is a very complex tool, it lets user do much more than what has been covered here. This document is for users who are new to GnuPG. For more information check out the official GnuPG website.

This article does not cover tools such as pgp4pine</tt>, gpgpine</tt>, evolution</tt>, and or Windows GPG tools.

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.