doc/en/gnupg-user.xml

<?xml version='1.0' encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gnupg-user.xml,v 1.40 2006/11/29 15:48:57 nightmorph Exp $ -->

<guide link = "/doc/en/gnupg-user.xml">
<title>GnuPG Gentoo user guide</title>
<author title="Author">
  <mail link="humpback@gentoo.org">Gustavo Felisberto</mail>
</author>
<author title="Editor">
  <mail link="zhen@gentoo.org">John P. Davis</mail>
</author>
<author title="Editor">
  <mail link="swift@gentoo.org">Sven Vermeulen</mail>
</author>

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

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>1.8</version>
<date>2007-02-20</date>

<chapter>
<title>Introduction</title>
<section>
<title>What you will get in this guide</title>
<body>

<p>
This guide assumes that you are familiar with public-key cryptography,
encryption, and digital signatures. If this is not the case jump to <uri
link="#doc_chap6">Public Key Cryptography</uri> or take a look at the
<uri link="http://www.gnupg.org/(en)/documentation/guides.html">GnuPG 
handbook</uri>, chapter 2, and then come back.
</p>

<p>
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.
</p>

</body>
</section>
<section>
<title>Installation of required software</title>
<body>

<p>
At a very basic level you need to <c>emerge gnupg</c>. Many aplications today
have some sort of support for gpg, so having <e>crypt</e> in your USE variable
is probably a good idea. If you wish to have an email client capable of using
gnupg you can use pine (<c>emerge pinepgp</c>), mutt (<c>emerge mutt</c>),
Mozilla Thunderbird (<c>emerge mozilla-thunderbird</c>), evolution (evolution is
a GNOME Microsoft Outlook work alike) and KDE's own KMail (KMail is part of the
kdepim package).
</p>

<p>
<c>Kgpg</c> 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.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Generating your key and adding keys to your public keyring</title>
<section>
<title>Creating your key</title>
<body>

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

<pre caption="key generation process" >
$ <i>gpg --gen-key</i>
gpg (GnuPG) 1.0.7; Copyright (C) 2002 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)
   (4) ElGamal (sign and encrypt)
   (5) RSA (sign only)
   Your selection? <i>1</i>
</pre>

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

<p>
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.
</p>

<pre caption="Choosing key size" >
DSA keypair will have 1024 bits.
About to generate a new ELG-E keypair.
              minimum keysize is  768 bits
              default keysize is 1024 bits
    highest suggested keysize is 2048 bits
    What keysize do you want? (1024) <i>2048</i>
Requested keysize is 2048 bits       
Please specify how long the key should be valid.
         0 = key does not expire
 &lt;n&gt;= key expires in n days
 &lt;n&gt;w = key expires in n weeks
 &lt;n&gt;m = key expires in n months
 &lt;n&gt;y = key expires in n years
 Key is valid for? (0) <i>0</i>
Key does not expire at all
</pre>

<p>
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.
</p>

<pre caption="Entering user information" >
Is this correct (y/n)? <i>y</i>
                        
You need a User-ID to identify your key; the software constructs the user id
from Real Name, Comment and Email Address in this form:
"Heinrich Heine (Der Dichter) &lt;heinrichh@duesseldorf.de&gt;"

Real name: <i>John Doe</i>
Email address: <i>john@nowhere.someplace.flick</i>
Comment: <i>The Real John Doe</i>
You selected this USER-ID:
"John Doe (The Real John Doe) &lt;john@nowhere.someplace.flick&gt;"

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

Enter passphrase: 
</pre>

<p>
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.
</p>

<p>
Then, 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.
</p>

</body>
</section>
<section>
<title>Generating a revocation certificate</title>
<body>

<impo>
This part is very important and you must do it <e>NOW</e>.
</impo>

<p>
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).
</p>

<pre caption="Generating revoke certificate">
$ <i>gpg --list-keys</i>
/home/humpback/.gnupg/pubring.gpg
---------------------------------
pub  1024D/75447B14 2002-12-08 John Doe (The Real John Doe) &lt;john@nowhere.someplace.flick&gt;
sub  2048g/96D6CDAD 2002-12-08

$ <i>gpg --output revoke.asc --gen-revoke 75447B14</i>

sec  1024D/75447B14 2002-12-08   John Doe (The Real John Doe) &lt;john@nowhere.someplace.flick&gt;

Create a revocation certificate for this key? <i>y</i>
Please select the reason for the revocation:   
  0 = No reason specified
  1 = Key has been compromised
  2 = Key is superseded
  3 = Key is no longer used
  Q = Cancel
(Probably you want to select 1 here)
Your decision? <i>1</i>
Enter an optional description; end it with an empty line:
&gt; <i>Someone cracked me and got my key and passphrase</i>
&gt;
Reason for revocation: Key has been compromised
Someone cracked me and got my key and passphrase
Is this okay? <i>y</i>

You need a passphrase to unlock the secret key for
user: "John Doe (The Real John Doe) &lt;john@nowhere.someplace.flick&gt;"
1024-bit DSA key, ID 75447B14, created 2002-12-08

ASCII armored output forced.
Revocation certificate created.

Please move it to a medium which you can hide away; if Mallory gets
access to this certificate he can use it to make your key unusable.
It is smart to print this certificate and store it away, just in case
your media become unreadable.  But have some caution:  The print system of
your machine might store the data and make it available to others!
</pre>

<p>
The <c>gpg --list-keys</c> 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 - <path>revoke.asc</path>) to some 
secure medium (two floppy's or a CD-R you store in safe location). Remember 
that <path>revoke.asc</path> can be used to revoke your keys and make them 
unusable in the future.
</p>

<note>
If you have several email addresses that you would like to use with this
key, you can run <c>gpg --edit-key YOUR_ID</c> and then use the <c>adduid</c>
command. It will ask you for the name, email and comment of the second ID you
will be using.
</note>

</body>
</section>
<section>
<title>Exporting keys</title>
<body>

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

</body>
</section>
<section>
<title>Importing keys</title>
<body>

<p>
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.
</p>

<note>
You should be careful when verifying keys. This is one of the weak points of
public key cryptography.
</note>

<p>
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 <c>fpr</c> 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.
</p>

<pre caption="Importing and signing keys">
$ <i>gpg --import luis.asc</i>
gpg: key 462405BB: public key imported
gpg: Total number processed: 1
gpg:               imported: 1
$ <i>gpg --list-keys</i>
/home/humpback/.gnupg/pubring.gpg
---------------------------------
pub  1024D/75447B14 2002-12-08 John Doe (The Real John Doe) &lt;john@nowhere.someplace.flick&gt;
sub  2048g/96D6CDAD 2002-12-08

pub  1024D/462405BB 2002-12-01 Luis Pinto &lt;lmpinto@student.dei.uc.pt&gt;
uid                            Luis Pinto &lt;lmpinto@dei.uc.pt&gt;
sub  4096g/922175B3 2002-12-01 [expires: 2003-12-01]

$ <i>gpg --edit-key lmpinto@dei.uc.pt</i>
gpg (GnuPG) 1.0.7; Copyright (C) 2002 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.


gpg: checking the trustdb
gpg: checking at depth 0 signed=0 ot(-/q/n/m/f/u)=0/0/0/0/0/1
pub  1024D/462405BB  created: 2002-12-01 expires: 2003-12-01 trust: -/-
sub  4096g/922175B3  created: 2002-12-01 expires: 2003-12-01
(1)  Luis Pinto &lt;lmpinto@dei.uc.pt&gt;
(2). Luis Pinto &lt;lmpinto@student.dei.uc.pt&gt;

Command> <i>fpr</i>
pub  1024D/462405BB 2002-12-01 Luis Pinto &lt;lmpinto@dei.uc.pt&gt;
             Fingerprint: F056 3697 ADE3 CF98 B80B  8494 0AD3 E57B 4624 05BB
     
Command> <i>sign</i>
Really sign all user IDs? <i>y</i>
                           
pub  1024D/462405BB  created: 2002-12-01 expires: 2003-12-01 trust: -/-
             Fingerprint: F056 3697 ADE3 CF98 B80B  8494 0AD3 E57B 4624 05BB

     Luis Pinto &lt;lmpinto@dei.uc.pt&gt;
     Luis Pinto &lt;lmpinto@student.dei.uc.pt&gt;

This key is due to expire on 2003-12-01.
Do you want your signature to expire at the same time? (Y/n) <i>Y</i>
How carefully have you verified the key you are about to sign actually belongs
to the person named above?  If you don't know what to answer, enter "0".

   (0) I will not answer. (default)
   (1) I have not checked at all.
   (2) I have done casual checking.
   (3) I have done very careful checking.

   Your selection? <i>3</i>
Are you really sure that you want to sign this key
with your key: "John Doe (The Real John Doe) &lt;john@nowhere.someplace.flick&gt;"

I have checked this key very carefully.

Really sign? <i>y</i>
              
You need a passphrase to unlock the secret key for
user: "John Doe (The Real John Doe) &lt;john@nowhere.someplace.flick&gt;"
1024-bit DSA key, ID 75447B14, created 2002-12-08

Command> <i>check</i>
uid  Luis Pinto &lt;lmpinto@dei.uc.pt&gt;
sig!3       462405BB 2002-12-01   [self-signature]
sig!3       75447B14 2002-12-08   John Doe (The Real John Doe) &lt;john@nowhe
uid  Luis Pinto &lt;lmpinto@student.dei.uc.pt&gt;
sig!3       462405BB 2002-12-01   [self-signature]
sig!3       75447B14 2002-12-08   John Doe (The Real John Doe) &lt;john@nowhe
</pre>

</body>
</section>
</chapter>

<chapter>
<title>Exchanging keys with keyservers</title>
<section>
<title>Sending keys to keyservers</title>
<body>

<p>
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 Luis's key to the subkeys.pgp.net
server. This uses HTTP, so if you need to use a proxy for HTTP traffic don't
forget to set it (<c>export http_proxy=http://proxy_host:port/</c>). The command
for sending the key is:  <c>gpg --keyserver subkeys.pgp.net --keyserver-options
honor-http-proxy --send-key 75447B14</c> where <c>75447B14</c> is the key ID. 
If you don't need a HTTP proxy you can remove the <e>--keyserver-options 
honor-http-proxy</e>.
</p>

<p>
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' key.
</p>

</body>
</section>
<section>
<title>Getting Keys from keyservers</title>
<body>

<p>
Now we are going to search for Gustavo Felisberto's key and add it to the
keyring of John Doe (just in case you did not notice Gustavo Felisberto is the
author this guide :) ).
</p>

<pre caption="Searching keys from keyservers">
$ <i>gpg --keyserver subkeys.pgp.net --keyserver-options honor-http-proxy --search-keys humpback@felisberto.net</i>
gpg: searching for "humpback@felisberto.net" from HKP server subkeys.pgp.net
Keys 1-5 of 5 for "humpback@felisberto.net"
(1)Gustavo Felisberto (apt-get install anarchy) &lt;humpback@felisberto.net&gt; 1024
  created 2002-12-06, key B9F2D52A
(2)Gustavo Felisberto &lt;humpback@altavista.net&gt; 1024
  created 1999-08-03, key E97E0B46
(3)Gustavo A.S.R. Felisberto &lt;humpback@altavista.net&gt; 1024
  created 1998-12-10, key B59AB043
(4)Gustavo Adolfo Silva Ribeiro Felisberto &lt;humpback@altavista.net&gt; 1024
  created 1998-08-26, key 39EB133D
(5)Gustavo Adolfo Silva Ribeiro Felisberto &lt;humpback@altavista.net&gt; 1024
  created 1998-06-14, key AE02AF87
  Enter number(s), N)ext, or Q)uit &gt;<i>1</i>
gpg: requesting key B9F2D52A from HKP keyserver subkeys.pgp.net
gpg: key B9F2D52A: public key imported
gpg: Total number processed: 1
gpg:               imported: 1
</pre>

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

</body>
</section>
</chapter>

<chapter id="gpg-agent">
<title>Using a GPG Agent</title>
<section>
<title>What is a GPG Agent?</title>
<body>

<p>
There are cases, when working with certain applications, where you 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, this however disallowed sharing this cache across
programs (how secure would that be?) and forced applications to reinvent the
wheel over and over again.
</p>

<p>
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.
</p>

<p>
Gentoo provides a few GPG agent applications. The <c>app-crypt/gnupg-1.9.*</c>
package contains what could be considered the reference one, and will be the
one we'll use in this document.
</p>

</body>
</section>
<section>
<title>Installing and Configuring gpg-agent and pinentry</title>
<body>

<p>
You should install <c>gnupg-1.9.*</c>, which includes <c>gpg-agent</c>, and
<c>pinentry</c>. <c>pinentry</c> is the 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 library (depending on the USE
flag you set when emerging it).
</p>

<pre caption="Installing gpg-agent and pinentry">
# <i>emerge \>=gnupg-1.9.20 pinentry</i>
</pre>

<p>
Next, create a file called <path>~/.gnupg/gpg-agent.conf</path> 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 Qt version of pinentry).
</p>

<pre caption="Editing ~/.gnupg/gpg-agent.conf">
pinentry-program /usr/bin/pinentry-qt
no-grab
default-cache-ttl 1800
</pre>

<p>
Now configure GnuPG to use an agent when appropriate. Edit
<path>~/.gnupg/gpg.conf</path> and add the following line:
</p>

<pre caption="Configuring GnuPG to use a GPG Agent">
use-agent
</pre>

<p>
Now your system is (almost) set to use the GPG agent.
</p>

</body>
</section>
<section>
<title>Automatically Starting the GPG Agent</title>
<body>

<p>
If you use KDE as graphical environment, edit
<path>/usr/kde/3.x/env/agent-startup.sh</path> (system-wide) or
<path>~/.kde/env/gpgagent.sh</path> (local user) and add the following command
to it to have KDE automatically starting the GPG agent:
</p>

<pre caption="Make KDE automatically start the GPG agent">
eval "$(gpg-agent --daemon)"
</pre>

<p>
If you use a different graphical environment, put that line (the same one as
mentioned above) in <path>~/.xinitrc</path> (if you use <c>startx</c>) or
<path>~/.xsession</path> (if you use XDM/GDM/KDM/...).
</p>

</body>
</section>
</chapter>

<chapter>
<title>Working with documents</title>
<section>
<title>Encrypting and signing</title>
<body>

<p>
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.
</p>

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

<pre caption="Encrypting and Signing files">
$ <i>gpg --output doc.gpg --encrypt --recipient lmpinto@dei.uc.pt doc_to_encrypt</i>
$ <i>gpg --output doc.gpg --sign --recipient lmpinto@dei.uc.pt doc_to_sign</i>
$ <i>gpg --output doc.gpg --encrypt --sign --recipient lmpinto@dei.uc.pt doc_to_encrypt_and_sign</i>
</pre>

<p>
This will create binary files. If you wish to create ASCII files, just add a
<c>--clearsign</c> to the beginning of the command.
</p>

</body>
</section>
<section>
<title>Decrypting and verifying signatures</title>
<body>

<p>
Suppose that you have received a file which is encrypted to you. The command
to decrypt it is <c>gpg --output document --decrypt encrypted_doc.gpg</c>. This
will decrypt the document and verify the signature (if there is one).
</p>

</body>
</section>
<section>
<title>Advanced Features</title>
<body>

<p>
There are some nice advanced features in GnuPG. To find them, open the
<path>~/.gnupg/gpg.conf</path> file. 
</p>

<pre caption="~/.gnupg/gpg.conf">
#keyserver x-hkp://subkeys.pgp.net
#keyserver-options auto-key-retrieve include-disabled include-revoked
</pre>

<p>
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 <uri 
link="http://subkeys.pgp.net:11371/">subkeys.pgp.net</uri> and will try to fetch
it from there.
</p>

<p>
Another nice command is <c>gpg --refresh-keys</c>. 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 id's, 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.
</p>

</body>
</section>
</chapter>

<chapter>
<title>GnuPG interfaces</title>
<section>
<title>About email signatures</title>
<body>

<p>
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.
</p>

<p>
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:
</p>

<pre caption="A plain text signature">
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Test message

-----BEGIN PGP SIGNATURE-----
Version: PGPfreeware 6.5.8 for non-commercial use

iQA/AwUBP8461jMX0745gR7AEQIEOwCg011GbufXO3ED3FkLWXmfzg7xm1cAoJD0
0EU3Kd2EKNCqataEqM5qjpPs
=LchZ
-----END PGP SIGNATURE-----
</pre>

<p>
Messages this way are no good in todays world, where we have nice GUI's and
email readers that understand html.
</p>

<p>
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 the content, 
Microsoft's Outlook is famous for not working with this.
</p>

</body>
</section>
<section>
<title>Kgpg</title>
<body>

<p>
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 which to decrypt.
</p>

<figure link="/images/kgpg1.png" short="kgpg main window"/>

<p>
In this image you can see the Kgpg main window with ASCII armored and encrypted
text pasted into it. From here you can decrypt it (you will have to provide your
password), encrypt other files, paste new text to sign....
</p>

<figure link="/images/kgpg2.png" short="kgpg key manage window"/>

<p>
Now you can see the key managing window. From here we see our good key for John
Doe. The two trusted keys for Gustavo and Luis, and the untrusted key for Daniel
Robbins ( I still have not given him a call to check his fingerprint :) ).
</p>

</body>
</section>
<section>
<title>Seahorse</title>
<body>

<p>
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.
</p>

</body>
</section>
<section>
<title>Enigmail</title>
<body>

<p>
Enigmail is a plug-in for Mozilla-based email clients (such as Thunderbird and
Seamonkey) that is pretty simple to configure. In Seamonkey, you just go to
Preferences -> Privacy &amp; Security -> Enigmail. There you enter your key
email and that's it. You must first <c>emerge enigmail</c> to use it with
Thunderbird.  Then you can configure it by going to Edit -> Account Settings ->
OpenPGP Security.
</p>

<p>
Mails that come with an untrusted pgp or gpg signature will be marked with a
broken pen. Others that have good signatures will appear with a nice straight
pen. Enigmail even comes with the ability to get keys from keyservers, but if it
has problems it will print some very weird messages (but you still remember how
to use the command line, right?).
</p>

</body>
</section>
<section>
<title>KMail</title>
<body>

<p>
If you have the <c>crypt</c> 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
(see <uri link="#gpg-agent">Using a GPG Agent</uri>).
</p>

<p>
You can verify if KMail is properly configured by going to <c>Settings</c>,
<c>Configure KMail</c>, <c>Security</c>, <c>Crypto Backends</c>. 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 <c>Rescan</c>. If the
GpgME-based backend remains grayed out, KMail is not working properly.
</p>

<p>
If you still are unable to get KMail to behave, please see the 
<uri link="http://kmail.kde.org/kmail-pgpmime-howto.html">KMail PGP HowTo</uri> 
page for more information.
</p>

</body>
</section>
<section>
<title>Sylpheed-Claws</title>
<body>

<p>
This is my email reader of choice. It is <e>very</e> fast with big mailboxes, 
has all the nice features one wants in mail readers and works pretty well with 
gpg. The only problem is that it does not work with the old PGP signatures, so 
when you receive those kind of mails you have to hand check the signatures.
</p>

<p>
To use your gpg key with Sylpheed-Claws just go to the acount configuration and
select the privacy tab. Once there just choose which key to use, probably most 
users will go with the default key.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Public Key Cryptography</title>
<section>
<title>Basic Public Key Cryptography</title>
<body>

<p>
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 tought 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 you cannot read the preceding text)). 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.
</p>

<p>
And now a bit of mathematics: 
</p>

<pre caption="Mathematical Concepts">
Definitions:

1- A prime number is a positive integer number greater than one that is only
divisible by 1 and itself (the remainder of the division is 0).
The first 8 prime numbers are 2,3,5,7,11,13,17,19

Theorem (No proof here)
1- For any non prime positive integer it is possible to break it as the product
of prime numbers, and that product is unique.
4=2*2
6=2*3
8=2*4=2*2*2
10=2*5
12=2*6=2*2*3

"Facts":
1- It is mathematically easy to multiply two large integers
2- It is hard to find the prime factors of a given positive integer.
</pre>

<p>
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 alot 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.
</p>

<p>
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 (todays 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.
</p>

<p>
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 <uri
link="http://en.wikipedia.org/wiki/Diffie-Hellman">Diffie-Hellman</uri>
protocol. For even more info go to the public library and grab a copy of the
<uri link="http://www.cacr.math.uwaterloo.ca/hac/">"Handbook of Applied
Cryptography"</uri> by Alfred J. Menezes, Paul C. van Oorschot and Scott A.
Vanstone,  also this book is available online for free at the above site.
</p>

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

</body>
</section>
<section>
<title>Signatures</title>
<body>

<p>
We already saw how someone can send us a cyphered message if they have our
public key. But how do we know that the author of the message is really who he
claims to be? Or in other words: If I receive an email from you how do I really
know it was you and not someone else claiming to be you? 
</p>

<p>
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.
</p>

<p>
Also very important, to sign messages you don't have to cypher them before. So
like that 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.
</p>

</body>
</section>
<section>
<title>Key Servers and Signed Keys</title>
<body>

<p>
But lets 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?
</p>

<p>
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:
</p>

<p>
Key signing means that, if I have the public key of another person, and I know 
<e>for sure</e> 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 
keyservers, 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.
</p>

<p>
This can sometimes be confusing so lets see a real world situation
</p>

<p>
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 keyserver 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?
</p>

<p>
He then see's 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.
</p>

<p>
You are now ready to use this guide, you can go back to chapter 1 and learn how
to use gpg.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Final thoughts and Credits</title>
<section>
<title>Some problems</title>
<body>

<p>
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.
</p>

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

</body>
</section>
<section>
<title>What is not here</title>
<body>

<p>
<c>gpg</c> 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 <uri link="http://www.gnupg.org">GnuPG 
Website</uri>.
</p>

<p>
I did not write about other tools like <c>pgp4pine</c>, <c>gpgpine</c>, 
<c>evolution</c> and maybe Windows tools, but I will probably extend this 
document in the future.
</p>

</body>
</section>
<section>
<title>Credits</title>
<body>

<p>
John Michael Ashley's <uri link="http://www.gnupg.org">GnuPG Handbook</uri>
it is a very good book for beginners.
</p>

<p>
Swift (Sven Vermeulen) for pushing me to re-write this.
</p>

<p>
Everyone in the #gentoo-doc team you guys rock.
</p>

<p>
Tiago Serra for getting me back to the privacy track.
</p>

</body>
</section>
</chapter>
</guide>