1 |
<?xml version='1.0' encoding="UTF-8"?> |
2 |
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
3 |
|
4 |
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gnupg-user.xml,v 1.41 2007/02/20 22:07:04 nightmorph Exp $ --> |
5 |
|
6 |
<guide link = "/doc/en/gnupg-user.xml"> |
7 |
<title>GnuPG Gentoo User Guide</title> |
8 |
|
9 |
<author title="Author"> |
10 |
<mail link="humpback@gentoo.org">Gustavo Felisberto</mail> |
11 |
</author> |
12 |
<author title="Editor"> |
13 |
<mail link="zhen@gentoo.org">John P. Davis</mail> |
14 |
</author> |
15 |
<author title="Editor"> |
16 |
<mail link="swift@gentoo.org">Sven Vermeulen</mail> |
17 |
</author> |
18 |
|
19 |
<abstract> |
20 |
This small guide will teach you the basics of using GnuPG, a tool for secure |
21 |
communication. |
22 |
</abstract> |
23 |
|
24 |
<!-- The content of this document is licensed under the CC-BY-SA license --> |
25 |
<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> |
26 |
<license/> |
27 |
|
28 |
<version>1.8</version> |
29 |
<date>2007-02-20</date> |
30 |
|
31 |
<chapter> |
32 |
<title>Introduction</title> |
33 |
<section> |
34 |
<title>What you will get in this guide</title> |
35 |
<body> |
36 |
|
37 |
<p> |
38 |
This guide assumes that you are familiar with public-key cryptography, |
39 |
encryption, and digital signatures. If this is not the case jump to <uri |
40 |
link="#doc_chap6">Public Key Cryptography</uri> or take a look at the |
41 |
<uri link="http://www.gnupg.org/(en)/documentation/guides.html">GnuPG |
42 |
handbook</uri>, chapter 2, and then come back. |
43 |
</p> |
44 |
|
45 |
<p> |
46 |
This guide will teach you how to install GnuPG, how to create your key pair, how |
47 |
to add keys to your keyring, how to submit your public key to a key server and |
48 |
how to sign, encrypt, verify or decode messages you send or receive. You will |
49 |
also learn how to encrypt files on your local computer to prevent people from |
50 |
reading their contents. |
51 |
</p> |
52 |
|
53 |
</body> |
54 |
</section> |
55 |
<section> |
56 |
<title>Installation of required software</title> |
57 |
<body> |
58 |
|
59 |
<p> |
60 |
At a very basic level you need to <c>emerge gnupg</c>. Many aplications today |
61 |
have some sort of support for gpg, so having <e>crypt</e> in your USE variable |
62 |
is probably a good idea. If you wish to have an email client capable of using |
63 |
gnupg you can use pine (<c>emerge pinepgp</c>), mutt (<c>emerge mutt</c>), |
64 |
Mozilla Thunderbird (<c>emerge mozilla-thunderbird</c>), evolution (evolution is |
65 |
a GNOME Microsoft Outlook work alike) and KDE's own KMail (KMail is part of the |
66 |
kdepim package). |
67 |
</p> |
68 |
|
69 |
<p> |
70 |
<c>Kgpg</c> might interest you if you use KDE. This small program allows you to |
71 |
generate key pairs, import keys from ASCII files, sign imported keys, export |
72 |
keys and a few more features. |
73 |
</p> |
74 |
|
75 |
</body> |
76 |
</section> |
77 |
</chapter> |
78 |
|
79 |
<chapter> |
80 |
<title>Generating your key and adding keys to your public keyring</title> |
81 |
<section> |
82 |
<title>Creating your key</title> |
83 |
<body> |
84 |
|
85 |
<p> |
86 |
To create your key, just run <c>gpg --gen-key</c>. The first time you run it, |
87 |
it will create some directories; run it again to create the keys: |
88 |
</p> |
89 |
|
90 |
<pre caption="key generation process" > |
91 |
$ <i>gpg --gen-key</i> |
92 |
gpg (GnuPG) 1.0.7; Copyright (C) 2002 Free Software Foundation, Inc. |
93 |
This program comes with ABSOLUTELY NO WARRANTY. |
94 |
This is free software, and you are welcome to redistribute it |
95 |
under certain conditions. See the file COPYING for details. |
96 |
|
97 |
Please select what kind of key you want: |
98 |
(1) DSA and ElGamal (default) |
99 |
(2) DSA (sign only) |
100 |
(4) ElGamal (sign and encrypt) |
101 |
(5) RSA (sign only) |
102 |
Your selection? <i>1</i> |
103 |
</pre> |
104 |
|
105 |
<p> |
106 |
Here you can choose the type of key you want to use. Most users will go for the |
107 |
default DSA and ElGamal. Next is the key size - remember that bigger is better |
108 |
but don't use a size larger than 2048 with DSA/ElGamal keys. Generally 1024 is |
109 |
more than enough for normal email. |
110 |
</p> |
111 |
|
112 |
<p> |
113 |
After size comes the expiration date. Here smaller is better, but most users can |
114 |
go for a key that never expires or to something like 2 or 3 years. |
115 |
</p> |
116 |
|
117 |
<pre caption="Choosing key size" > |
118 |
DSA keypair will have 1024 bits. |
119 |
About to generate a new ELG-E keypair. |
120 |
minimum keysize is 768 bits |
121 |
default keysize is 1024 bits |
122 |
highest suggested keysize is 2048 bits |
123 |
What keysize do you want? (1024) <i>2048</i> |
124 |
Requested keysize is 2048 bits |
125 |
Please specify how long the key should be valid. |
126 |
0 = key does not expire |
127 |
<n>= key expires in n days |
128 |
<n>w = key expires in n weeks |
129 |
<n>m = key expires in n months |
130 |
<n>y = key expires in n years |
131 |
Key is valid for? (0) <i>0</i> |
132 |
Key does not expire at all |
133 |
</pre> |
134 |
|
135 |
<p> |
136 |
Now it is time to enter some personal information about yourself. If you are |
137 |
going to send your public key to other people you have to use your real email |
138 |
address here. |
139 |
</p> |
140 |
|
141 |
<pre caption="Entering user information" > |
142 |
Is this correct (y/n)? <i>y</i> |
143 |
|
144 |
You need a User-ID to identify your key; the software constructs the user id |
145 |
from Real Name, Comment and Email Address in this form: |
146 |
"Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>" |
147 |
|
148 |
Real name: <i>John Doe</i> |
149 |
Email address: <i>john@nowhere.someplace.flick</i> |
150 |
Comment: <i>The Real John Doe</i> |
151 |
You selected this USER-ID: |
152 |
"John Doe (The Real John Doe) <john@nowhere.someplace.flick>" |
153 |
|
154 |
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? <i>O</i> |
155 |
You need a Passphrase to protect your secret key. |
156 |
|
157 |
Enter passphrase: |
158 |
</pre> |
159 |
|
160 |
<p> |
161 |
Now enter your key passphrase twice. It is a good idea to use a strong password. |
162 |
If someone ever gets hold of your private key and cracks your password, they |
163 |
will be able to send messages signed by "you", making everyone believe the mails |
164 |
were sent by you. |
165 |
</p> |
166 |
|
167 |
<p> |
168 |
Next, GnuPG will generate your key. Moving the mouse or having a mp3 playing in |
169 |
the background will help speed up the process because it generates random data. |
170 |
</p> |
171 |
|
172 |
</body> |
173 |
</section> |
174 |
<section> |
175 |
<title>Generating a revocation certificate</title> |
176 |
<body> |
177 |
|
178 |
<impo> |
179 |
This part is very important and you must do it <e>NOW</e>. |
180 |
</impo> |
181 |
|
182 |
<p> |
183 |
After creating your keys you should create a revocation certificate. Doing this |
184 |
allows you to revoke your key in case something nasty happens to your key |
185 |
(someone gets hold of your key/passphrase). |
186 |
</p> |
187 |
|
188 |
<pre caption="Generating revoke certificate"> |
189 |
$ <i>gpg --list-keys</i> |
190 |
/home/humpback/.gnupg/pubring.gpg |
191 |
--------------------------------- |
192 |
pub 1024D/75447B14 2002-12-08 John Doe (The Real John Doe) <john@nowhere.someplace.flick> |
193 |
sub 2048g/96D6CDAD 2002-12-08 |
194 |
|
195 |
$ <i>gpg --output revoke.asc --gen-revoke 75447B14</i> |
196 |
|
197 |
sec 1024D/75447B14 2002-12-08 John Doe (The Real John Doe) <john@nowhere.someplace.flick> |
198 |
|
199 |
Create a revocation certificate for this key? <i>y</i> |
200 |
Please select the reason for the revocation: |
201 |
0 = No reason specified |
202 |
1 = Key has been compromised |
203 |
2 = Key is superseded |
204 |
3 = Key is no longer used |
205 |
Q = Cancel |
206 |
(Probably you want to select 1 here) |
207 |
Your decision? <i>1</i> |
208 |
Enter an optional description; end it with an empty line: |
209 |
> <i>Someone cracked me and got my key and passphrase</i> |
210 |
> |
211 |
Reason for revocation: Key has been compromised |
212 |
Someone cracked me and got my key and passphrase |
213 |
Is this okay? <i>y</i> |
214 |
|
215 |
You need a passphrase to unlock the secret key for |
216 |
user: "John Doe (The Real John Doe) <john@nowhere.someplace.flick>" |
217 |
1024-bit DSA key, ID 75447B14, created 2002-12-08 |
218 |
|
219 |
ASCII armored output forced. |
220 |
Revocation certificate created. |
221 |
|
222 |
Please move it to a medium which you can hide away; if Mallory gets |
223 |
access to this certificate he can use it to make your key unusable. |
224 |
It is smart to print this certificate and store it away, just in case |
225 |
your media become unreadable. But have some caution: The print system of |
226 |
your machine might store the data and make it available to others! |
227 |
</pre> |
228 |
|
229 |
<p> |
230 |
The <c>gpg --list-keys</c> command lists keys in your public keyring. You may |
231 |
use it to see the ID of your key so that you can create the revocation |
232 |
certificate. Now it is a good idea to copy all the .gnupg directory and the |
233 |
revocation certificate (in ASCII armor - <path>revoke.asc</path>) to some |
234 |
secure medium (two floppy's or a CD-R you store in safe location). Remember |
235 |
that <path>revoke.asc</path> can be used to revoke your keys and make them |
236 |
unusable in the future. |
237 |
</p> |
238 |
|
239 |
<note> |
240 |
If you have several email addresses that you would like to use with this |
241 |
key, you can run <c>gpg --edit-key YOUR_ID</c> and then use the <c>adduid</c> |
242 |
command. It will ask you for the name, email and comment of the second ID you |
243 |
will be using. |
244 |
</note> |
245 |
|
246 |
</body> |
247 |
</section> |
248 |
<section> |
249 |
<title>Exporting keys</title> |
250 |
<body> |
251 |
|
252 |
<p> |
253 |
To export your key, you type <c>gpg --armor --output john.asc --export |
254 |
john@nowhere.someplace.flick</c>. You can almost always use the key ID or |
255 |
something that identifies the key (here we used an email address). John now has |
256 |
a <path>john.asc</path> that he can send his friends, or place on his web page |
257 |
so that people can communicate safely with him. |
258 |
</p> |
259 |
|
260 |
</body> |
261 |
</section> |
262 |
<section> |
263 |
<title>Importing keys</title> |
264 |
<body> |
265 |
|
266 |
<p> |
267 |
To add files to your public keyring, you must first import it, then check the |
268 |
key fingerprint. After you have verified the fingerprint you should validate it. |
269 |
</p> |
270 |
|
271 |
<note> |
272 |
You should be careful when verifying keys. This is one of the weak points of |
273 |
public key cryptography. |
274 |
</note> |
275 |
|
276 |
<p> |
277 |
Now we will be adding Luis Pinto's (a friend of mine) public key to our public |
278 |
keyring. After giving him a call and asking him for his key fingerprint, I |
279 |
compare the fingerprint with the output of the <c>fpr</c> command. As the key is |
280 |
authentic, I add it to the public keyring. In this particular case, Luis's key |
281 |
will expire in 2003-12-01 so I am asked if I want my signature on his key to |
282 |
expire at the same time. |
283 |
</p> |
284 |
|
285 |
<pre caption="Importing and signing keys"> |
286 |
$ <i>gpg --import luis.asc</i> |
287 |
gpg: key 462405BB: public key imported |
288 |
gpg: Total number processed: 1 |
289 |
gpg: imported: 1 |
290 |
$ <i>gpg --list-keys</i> |
291 |
/home/humpback/.gnupg/pubring.gpg |
292 |
--------------------------------- |
293 |
pub 1024D/75447B14 2002-12-08 John Doe (The Real John Doe) <john@nowhere.someplace.flick> |
294 |
sub 2048g/96D6CDAD 2002-12-08 |
295 |
|
296 |
pub 1024D/462405BB 2002-12-01 Luis Pinto <lmpinto@student.dei.uc.pt> |
297 |
uid Luis Pinto <lmpinto@dei.uc.pt> |
298 |
sub 4096g/922175B3 2002-12-01 [expires: 2003-12-01] |
299 |
|
300 |
$ <i>gpg --edit-key lmpinto@dei.uc.pt</i> |
301 |
gpg (GnuPG) 1.0.7; Copyright (C) 2002 Free Software Foundation, Inc. |
302 |
This program comes with ABSOLUTELY NO WARRANTY. |
303 |
This is free software, and you are welcome to redistribute it |
304 |
under certain conditions. See the file COPYING for details. |
305 |
|
306 |
|
307 |
gpg: checking the trustdb |
308 |
gpg: checking at depth 0 signed=0 ot(-/q/n/m/f/u)=0/0/0/0/0/1 |
309 |
pub 1024D/462405BB created: 2002-12-01 expires: 2003-12-01 trust: -/- |
310 |
sub 4096g/922175B3 created: 2002-12-01 expires: 2003-12-01 |
311 |
(1) Luis Pinto <lmpinto@dei.uc.pt> |
312 |
(2). Luis Pinto <lmpinto@student.dei.uc.pt> |
313 |
|
314 |
Command> <i>fpr</i> |
315 |
pub 1024D/462405BB 2002-12-01 Luis Pinto <lmpinto@dei.uc.pt> |
316 |
Fingerprint: F056 3697 ADE3 CF98 B80B 8494 0AD3 E57B 4624 05BB |
317 |
|
318 |
Command> <i>sign</i> |
319 |
Really sign all user IDs? <i>y</i> |
320 |
|
321 |
pub 1024D/462405BB created: 2002-12-01 expires: 2003-12-01 trust: -/- |
322 |
Fingerprint: F056 3697 ADE3 CF98 B80B 8494 0AD3 E57B 4624 05BB |
323 |
|
324 |
Luis Pinto <lmpinto@dei.uc.pt> |
325 |
Luis Pinto <lmpinto@student.dei.uc.pt> |
326 |
|
327 |
This key is due to expire on 2003-12-01. |
328 |
Do you want your signature to expire at the same time? (Y/n) <i>Y</i> |
329 |
How carefully have you verified the key you are about to sign actually belongs |
330 |
to the person named above? If you don't know what to answer, enter "0". |
331 |
|
332 |
(0) I will not answer. (default) |
333 |
(1) I have not checked at all. |
334 |
(2) I have done casual checking. |
335 |
(3) I have done very careful checking. |
336 |
|
337 |
Your selection? <i>3</i> |
338 |
Are you really sure that you want to sign this key |
339 |
with your key: "John Doe (The Real John Doe) <john@nowhere.someplace.flick>" |
340 |
|
341 |
I have checked this key very carefully. |
342 |
|
343 |
Really sign? <i>y</i> |
344 |
|
345 |
You need a passphrase to unlock the secret key for |
346 |
user: "John Doe (The Real John Doe) <john@nowhere.someplace.flick>" |
347 |
1024-bit DSA key, ID 75447B14, created 2002-12-08 |
348 |
|
349 |
Command> <i>check</i> |
350 |
uid Luis Pinto <lmpinto@dei.uc.pt> |
351 |
sig!3 462405BB 2002-12-01 [self-signature] |
352 |
sig!3 75447B14 2002-12-08 John Doe (The Real John Doe) <john@nowhe |
353 |
uid Luis Pinto <lmpinto@student.dei.uc.pt> |
354 |
sig!3 462405BB 2002-12-01 [self-signature] |
355 |
sig!3 75447B14 2002-12-08 John Doe (The Real John Doe) <john@nowhe |
356 |
</pre> |
357 |
|
358 |
</body> |
359 |
</section> |
360 |
</chapter> |
361 |
|
362 |
<chapter> |
363 |
<title>Exchanging keys with keyservers</title> |
364 |
<section> |
365 |
<title>Sending keys to keyservers</title> |
366 |
<body> |
367 |
|
368 |
<p> |
369 |
Now that you have your key, it is probably a good idea to send it to the world |
370 |
key server. There are a lot of keyservers in the world and most of them exchange |
371 |
keys between them. Here we are going to send Luis's key to the subkeys.pgp.net |
372 |
server. This uses HTTP, so if you need to use a proxy for HTTP traffic don't |
373 |
forget to set it (<c>export http_proxy=http://proxy_host:port/</c>). The command |
374 |
for sending the key is: <c>gpg --keyserver subkeys.pgp.net --keyserver-options |
375 |
honor-http-proxy --send-key 75447B14</c> where <c>75447B14</c> is the key ID. |
376 |
If you don't need a HTTP proxy you can remove the <e>--keyserver-options |
377 |
honor-http-proxy</e>. |
378 |
</p> |
379 |
|
380 |
<p> |
381 |
You can also send other people's keys that you have signed to the keyserver. We |
382 |
could send Luis Pinto's key to the keyserver. This way someone who trusts |
383 |
your key can use the signature that you have placed there to trust Luis's key. |
384 |
</p> |
385 |
|
386 |
</body> |
387 |
</section> |
388 |
<section> |
389 |
<title>Getting Keys from keyservers</title> |
390 |
<body> |
391 |
|
392 |
<p> |
393 |
Now we are going to search for Gustavo Felisberto's key and add it to the |
394 |
keyring of John Doe (just in case you did not notice Gustavo Felisberto is the |
395 |
author this guide :)). |
396 |
</p> |
397 |
|
398 |
<pre caption="Searching keys from keyservers"> |
399 |
$ <i>gpg --keyserver subkeys.pgp.net --keyserver-options honor-http-proxy --search-keys humpback@felisberto.net</i> |
400 |
gpg: searching for "humpback@felisberto.net" from HKP server subkeys.pgp.net |
401 |
Keys 1-5 of 5 for "humpback@felisberto.net" |
402 |
(1)Gustavo Felisberto (apt-get install anarchy) <humpback@felisberto.net> 1024 |
403 |
created 2002-12-06, key B9F2D52A |
404 |
(2)Gustavo Felisberto <humpback@altavista.net> 1024 |
405 |
created 1999-08-03, key E97E0B46 |
406 |
(3)Gustavo A.S.R. Felisberto <humpback@altavista.net> 1024 |
407 |
created 1998-12-10, key B59AB043 |
408 |
(4)Gustavo Adolfo Silva Ribeiro Felisberto <humpback@altavista.net> 1024 |
409 |
created 1998-08-26, key 39EB133D |
410 |
(5)Gustavo Adolfo Silva Ribeiro Felisberto <humpback@altavista.net> 1024 |
411 |
created 1998-06-14, key AE02AF87 |
412 |
Enter number(s), N)ext, or Q)uit ><i>1</i> |
413 |
gpg: requesting key B9F2D52A from HKP keyserver subkeys.pgp.net |
414 |
gpg: key B9F2D52A: public key imported |
415 |
gpg: Total number processed: 1 |
416 |
gpg: imported: 1 |
417 |
</pre> |
418 |
|
419 |
<p> |
420 |
As you can see from the server response I have a few keys submitted to the key |
421 |
server, but I currently only use <e>B9F2D52A</e>. Now John Doe can get it and |
422 |
sign it if he trusts it. |
423 |
</p> |
424 |
|
425 |
</body> |
426 |
</section> |
427 |
</chapter> |
428 |
|
429 |
<chapter id="gpg-agent"> |
430 |
<title>Using a GPG Agent</title> |
431 |
<section> |
432 |
<title>What is a GPG Agent?</title> |
433 |
<body> |
434 |
|
435 |
<p> |
436 |
Sometimes working with certain applications requires you to use your GPG key |
437 |
very frequently, which means that you have to type your passphrase a lot of |
438 |
times. Several applications used to support a passphrase caching mechanism to |
439 |
make life easier for users. However, this disallowed sharing this cache across |
440 |
programs (how secure would that be?) and forced applications to reinvent the |
441 |
wheel over and over again. |
442 |
</p> |
443 |
|
444 |
<p> |
445 |
A GPG agent is a separate application that GPG uses to cache the passphrase in |
446 |
a standard and secure way. It allows applications to use GPG concurrently: if |
447 |
you enter your passphrase while working in one application, the other |
448 |
application can work with GPG without reiterating the request for the |
449 |
passphrase to unlock the key - if the GPG agent is configured to allow so, of |
450 |
course. |
451 |
</p> |
452 |
|
453 |
<p> |
454 |
Gentoo provides a few GPG agent applications. The <c>app-crypt/gnupg-1.9.*</c> |
455 |
package contains what could be considered the reference one, and will be the |
456 |
one we'll use in this document. |
457 |
</p> |
458 |
|
459 |
</body> |
460 |
</section> |
461 |
<section> |
462 |
<title>Installing and Configuring gpg-agent and pinentry</title> |
463 |
<body> |
464 |
|
465 |
<p> |
466 |
You should install <c>gnupg-1.9.*</c>, which includes <c>gpg-agent</c>, and |
467 |
<c>pinentry</c>. <c>pinentry</c> is the helper application that gpg-agent uses |
468 |
to request the passphrase in a graphical window. It comes in three flavors: it |
469 |
can popup a window using the gtk+, Qt, or curses library (depending on the USE |
470 |
flag you set when emerging it). |
471 |
</p> |
472 |
|
473 |
<pre caption="Installing gpg-agent and pinentry"> |
474 |
# <i>emerge \>=gnupg-1.9.20 pinentry</i> |
475 |
</pre> |
476 |
|
477 |
<p> |
478 |
Next, create a file called <path>~/.gnupg/gpg-agent.conf</path> and enter the |
479 |
following lines which define the default timeout of the passphrase (e.g. 30 |
480 |
minutes) and the application to be called for when the passphrase should be |
481 |
retrieved the first time (e.g. the Qt version of pinentry). |
482 |
</p> |
483 |
|
484 |
<pre caption="Editing ~/.gnupg/gpg-agent.conf"> |
485 |
pinentry-program /usr/bin/pinentry-qt |
486 |
no-grab |
487 |
default-cache-ttl 1800 |
488 |
</pre> |
489 |
|
490 |
<p> |
491 |
Now configure GnuPG to use an agent when appropriate. Edit |
492 |
<path>~/.gnupg/gpg.conf</path> and add the following line: |
493 |
</p> |
494 |
|
495 |
<pre caption="Configuring GnuPG to use a GPG Agent"> |
496 |
use-agent |
497 |
</pre> |
498 |
|
499 |
<p> |
500 |
Now your system is (almost) set to use the GPG agent. |
501 |
</p> |
502 |
|
503 |
</body> |
504 |
</section> |
505 |
<section> |
506 |
<title>Automatically Starting the GPG Agent</title> |
507 |
<body> |
508 |
|
509 |
<p> |
510 |
If you use KDE as graphical environment, edit |
511 |
<path>/usr/kde/3.x/env/agent-startup.sh</path> (system-wide) or |
512 |
<path>~/.kde/env/gpgagent.sh</path> (local user) and add the following command |
513 |
to it to have KDE automatically starting the GPG agent: |
514 |
</p> |
515 |
|
516 |
<pre caption="Make KDE automatically start the GPG agent"> |
517 |
eval "$(gpg-agent --daemon)" |
518 |
</pre> |
519 |
|
520 |
<p> |
521 |
If you use a different graphical environment, put that line (the same one as |
522 |
mentioned above) in <path>~/.xinitrc</path> (if you use <c>startx</c>) or |
523 |
<path>~/.xsession</path> (if you use XDM/GDM/KDM/...). |
524 |
</p> |
525 |
|
526 |
</body> |
527 |
</section> |
528 |
</chapter> |
529 |
|
530 |
<chapter> |
531 |
<title>Working with documents</title> |
532 |
<section> |
533 |
<title>Encrypting and signing</title> |
534 |
<body> |
535 |
|
536 |
<p> |
537 |
Let's say that you have a file that you wish to send Luis. You can encrypt |
538 |
it, sign it, or encrypt it and sign it. Encrypting means that only Luis will be |
539 |
able to open it. The signature tells Luis that it was really you who created the |
540 |
file. |
541 |
</p> |
542 |
|
543 |
<p> |
544 |
The next three commands will do just that, encrypt, sign and encrypt/sign. |
545 |
</p> |
546 |
|
547 |
<pre caption="Encrypting and Signing files"> |
548 |
$ <i>gpg --output doc.gpg --encrypt --recipient lmpinto@dei.uc.pt doc_to_encrypt</i> |
549 |
$ <i>gpg --output doc.gpg --sign --recipient lmpinto@dei.uc.pt doc_to_sign</i> |
550 |
$ <i>gpg --output doc.gpg --encrypt --sign --recipient lmpinto@dei.uc.pt doc_to_encrypt_and_sign</i> |
551 |
</pre> |
552 |
|
553 |
<p> |
554 |
This will create binary files. If you wish to create ASCII files, just add a |
555 |
<c>--clearsign</c> to the beginning of the command. |
556 |
</p> |
557 |
|
558 |
</body> |
559 |
</section> |
560 |
<section> |
561 |
<title>Decrypting and verifying signatures</title> |
562 |
<body> |
563 |
|
564 |
<p> |
565 |
Suppose that you have received a file which is encrypted to you. The command |
566 |
to decrypt it is <c>gpg --output document --decrypt encrypted_doc.gpg</c>. This |
567 |
will decrypt the document and verify the signature (if there is one). |
568 |
</p> |
569 |
|
570 |
</body> |
571 |
</section> |
572 |
<section> |
573 |
<title>Advanced Features</title> |
574 |
<body> |
575 |
|
576 |
<p> |
577 |
There are some nice advanced features in GnuPG. To find them, open the |
578 |
<path>~/.gnupg/gpg.conf</path> file. |
579 |
</p> |
580 |
|
581 |
<pre caption="~/.gnupg/gpg.conf"> |
582 |
#keyserver x-hkp://subkeys.pgp.net |
583 |
#keyserver-options auto-key-retrieve include-disabled include-revoked |
584 |
</pre> |
585 |
|
586 |
<p> |
587 |
Search for the above two lines and uncomment them. With this any time GnuPG |
588 |
needs to check a signature and it does not find the public key on the local |
589 |
keyring it will contact the key server at <uri |
590 |
link="http://subkeys.pgp.net:11371/">subkeys.pgp.net</uri> and will try to fetch |
591 |
it from there. |
592 |
</p> |
593 |
|
594 |
<p> |
595 |
Another nice command is <c>gpg --refresh-keys</c>. This will contact the |
596 |
keyserver defined in the options file and refresh public keys in your local key |
597 |
ring from there, searching for revoked keys, new IDs, and new signatures on |
598 |
keys. You should probably run this once or twice a month so that if someone |
599 |
revokes his key you will be notified. |
600 |
</p> |
601 |
|
602 |
</body> |
603 |
</section> |
604 |
</chapter> |
605 |
|
606 |
<chapter> |
607 |
<title>GnuPG interfaces</title> |
608 |
<section> |
609 |
<title>About email signatures</title> |
610 |
<body> |
611 |
|
612 |
<p> |
613 |
95% of the time you will use GnuPG with email, signing/encrypting your outgoing |
614 |
messages and reading signed/encrypted messages. So it is only fair that I talk |
615 |
about that first. |
616 |
</p> |
617 |
|
618 |
<p> |
619 |
There are two ways two sign/encrypt a email with GnuPG, the old way and the new |
620 |
way :). In the old way messages would appear in plain text, with no possible |
621 |
formatting and attached files would be unsigned/unencrypted. Here is an example |
622 |
of a message signed the old way: |
623 |
</p> |
624 |
|
625 |
<pre caption="A plain text signature"> |
626 |
-----BEGIN PGP SIGNED MESSAGE----- |
627 |
Hash: SHA1 |
628 |
|
629 |
Test message |
630 |
|
631 |
-----BEGIN PGP SIGNATURE----- |
632 |
Version: PGPfreeware 6.5.8 for non-commercial use |
633 |
|
634 |
iQA/AwUBP8461jMX0745gR7AEQIEOwCg011GbufXO3ED3FkLWXmfzg7xm1cAoJD0 |
635 |
0EU3Kd2EKNCqataEqM5qjpPs |
636 |
=LchZ |
637 |
-----END PGP SIGNATURE----- |
638 |
</pre> |
639 |
|
640 |
<p> |
641 |
Messages this way are no good in today's world, where we have nice GUIs and |
642 |
email readers that understand html. |
643 |
</p> |
644 |
|
645 |
<p> |
646 |
To solve this an addition to the MIME (Multipurpose Internet Mail Extensions) |
647 |
was created. This adds a field to the email that tells the mail reader that the |
648 |
full content of the message is signed and/or encrypted. The problem with this |
649 |
is that not all mail readers support this. And some even mess up the content; |
650 |
Microsoft's Outlook is famous for not working with this. |
651 |
</p> |
652 |
|
653 |
</body> |
654 |
</section> |
655 |
<section> |
656 |
<title>Kgpg</title> |
657 |
<body> |
658 |
|
659 |
<p> |
660 |
Kgpg is a nice GUI for GnuPG. In the main screen you can paste the text that |
661 |
you wish to sign or encrypt, and you can also paste the ASCII armored text that |
662 |
you which to decrypt. |
663 |
</p> |
664 |
|
665 |
<figure link="/images/kgpg1.png" short="kgpg main window"/> |
666 |
|
667 |
<p> |
668 |
In this image you can see the Kgpg main window with ASCII armored and encrypted |
669 |
text pasted into it. From here you can decrypt it (you will have to provide your |
670 |
password), encrypt other files, paste new text to sign.... |
671 |
</p> |
672 |
|
673 |
<figure link="/images/kgpg2.png" short="kgpg key manage window"/> |
674 |
|
675 |
<p> |
676 |
Now you can see the key managing window. From here we see our good key for John |
677 |
Doe. The two trusted keys for Gustavo and Luis, and the untrusted key for Daniel |
678 |
Robbins (I still have not given him a call to check his fingerprint :)). |
679 |
</p> |
680 |
|
681 |
</body> |
682 |
</section> |
683 |
<section> |
684 |
<title>Seahorse</title> |
685 |
<body> |
686 |
|
687 |
<p> |
688 |
Seahorse aims to be a GnuPG GUI interface for the Gnome desktop. The software |
689 |
has been evolving fast, but it still lacks many important features that can be |
690 |
found in Kgpg or the command line version. |
691 |
</p> |
692 |
|
693 |
</body> |
694 |
</section> |
695 |
<section> |
696 |
<title>Enigmail</title> |
697 |
<body> |
698 |
|
699 |
<p> |
700 |
Enigmail is a plug-in for Mozilla-based email clients (such as Thunderbird and |
701 |
Seamonkey) that is pretty simple to configure. In Seamonkey, you just go to |
702 |
Preferences -> Privacy & Security -> Enigmail. There you enter your key |
703 |
email and that's it. You must first <c>emerge enigmail</c> to use it with |
704 |
Thunderbird. Then you can configure it by going to Edit -> Account Settings -> |
705 |
OpenPGP Security. |
706 |
</p> |
707 |
|
708 |
<p> |
709 |
Mails that come with an untrusted pgp or gpg signature will be marked with a |
710 |
broken pen. Others that have good signatures will appear with a nice straight |
711 |
pen. Enigmail even comes with the ability to get keys from keyservers, but if it |
712 |
has problems it will print some very weird messages (but you still remember how |
713 |
to use the command line, right?). |
714 |
</p> |
715 |
|
716 |
</body> |
717 |
</section> |
718 |
<section> |
719 |
<title>KMail</title> |
720 |
<body> |
721 |
|
722 |
<p> |
723 |
If you have the <c>crypt</c> USE flag set, KMail will be compiled with gpg |
724 |
support, and will be able to encrypt and decrypt inline PGP mails automatically |
725 |
as well as encrypting OpenPGP/MIME mails. If you want to decrypt OpenPGP/MIME |
726 |
mails as well (which you probably want) you need to have a running GPG agent |
727 |
(see <uri link="#gpg-agent">Using a GPG Agent</uri>). |
728 |
</p> |
729 |
|
730 |
<p> |
731 |
You can verify if KMail is properly configured by going to <c>Settings</c>, |
732 |
<c>Configure KMail</c>, <c>Security</c>, <c>Crypto Backends</c>. You should see |
733 |
a GpgME-based backend listed and you should be able to fill the OpenPGP |
734 |
checkbox. If it is listed but grayed out, click on <c>Rescan</c>. If the |
735 |
GpgME-based backend remains grayed out, KMail is not working properly. |
736 |
</p> |
737 |
|
738 |
<p> |
739 |
If you still are unable to get KMail to behave, please see the |
740 |
<uri link="http://kmail.kde.org/kmail-pgpmime-howto.html">KMail PGP HowTo</uri> |
741 |
page for more information. |
742 |
</p> |
743 |
|
744 |
</body> |
745 |
</section> |
746 |
<section> |
747 |
<title>Sylpheed-Claws</title> |
748 |
<body> |
749 |
|
750 |
<p> |
751 |
This is my email reader of choice. It is <e>very</e> fast with big mailboxes, |
752 |
has all the nice features one wants in mail readers and works pretty well with |
753 |
gpg. The only problem is that it does not work with the old PGP signatures, so |
754 |
when you receive those kind of mails you have to hand check the signatures. |
755 |
</p> |
756 |
|
757 |
<p> |
758 |
To use your gpg key with Sylpheed-Claws just go to the acount configuration and |
759 |
select the privacy tab. Once there just choose which key to use, probably most |
760 |
users will go with the default key. |
761 |
</p> |
762 |
|
763 |
</body> |
764 |
</section> |
765 |
</chapter> |
766 |
|
767 |
<chapter> |
768 |
<title>Public Key Cryptography</title> |
769 |
<section> |
770 |
<title>Basic Public Key Cryptography</title> |
771 |
<body> |
772 |
|
773 |
<p> |
774 |
The concept of public key cryptography was originally devised by Whitfield |
775 |
Diffie and Martin Hellman in 1976. When I first heard the words "public key" and |
776 |
"cryptography" in the same sentence back in '93 I thought to myself that it |
777 |
would be impossible to do such a thing. In those days there was no Internet |
778 |
(well there was, but not for me) so I went to the public library and asked for |
779 |
books on Cryptography. I must say that I was 16 at the time so the clerk there |
780 |
looked to me in astonishment and brought me a book for children on substitution |
781 |
cyphers (those where you change a letter for another like the famous Caesar |
782 |
Cypher or ROT-13 (Tragbb Ebpxf, naq lbh xabj vg vf tbbq orpnhfr lbh ner ernqvat |
783 |
guvf qbp.), (<c>emerge rotix</c> if you cannot read the preceding text)). I was |
784 |
very upset with this and started to search for more info. It is good to have |
785 |
mathematicians in the family, because as soon as I talked to one of them I was |
786 |
introduced to a new world. |
787 |
</p> |
788 |
|
789 |
<p> |
790 |
And now a bit of mathematics: |
791 |
</p> |
792 |
|
793 |
<pre caption="Mathematical Concepts"> |
794 |
Definitions: |
795 |
|
796 |
1- A prime number is a positive integer number greater than one that is only |
797 |
divisible by 1 and itself (the remainder of the division is 0). |
798 |
The first 8 prime numbers are 2,3,5,7,11,13,17,19 |
799 |
|
800 |
Theorem (No proof here) |
801 |
1- For any non prime positive integer it is possible to break it as the product |
802 |
of prime numbers, and that product is unique. |
803 |
4=2*2 |
804 |
6=2*3 |
805 |
8=2*4=2*2*2 |
806 |
10=2*5 |
807 |
12=2*6=2*2*3 |
808 |
|
809 |
"Facts": |
810 |
1- It is mathematically easy to multiply two large integers |
811 |
2- It is hard to find the prime factors of a given positive integer. |
812 |
</pre> |
813 |
|
814 |
<p> |
815 |
If I give you the number 35 and I tell you that this number is the product of |
816 |
two prime numbers it is easy to find that it was 5 and 7. But if I tell you the |
817 |
same for 1588522601 you will spend alot of time (or CPU cycles) to find it was |
818 |
49811*31891. And if this number is really really big this task becomes |
819 |
"impossible". So now if I give the world my large number that is the product of |
820 |
two primes I know something about that number that no one else knows. |
821 |
</p> |
822 |
|
823 |
<p> |
824 |
This is the basis for Public Key Cryptography (PKC) implementations today. As an |
825 |
(unrealistic) example, I give anyone my number and that someone will use if for |
826 |
cyphering a message to me. Anyone can see the cyphered message, because I am |
827 |
the only one who knows a shortcut to read it, anyone else will first have to |
828 |
"split" that big number to be able to read the message, and it is a "fact" |
829 |
that it is impossible to do that in a short amount of time (todays methods and |
830 |
the fastest computers in the world would take thousands of years to do that). |
831 |
In this setup the two large prime numbers would be called the PRIVATE KEY, and |
832 |
the large non prime number is the PUBLIC KEY. |
833 |
</p> |
834 |
|
835 |
<p> |
836 |
In practice this is not 100% accurate with reality, but will give a good idea to |
837 |
the newcomer. For more information, check Wikipedia on the <uri |
838 |
link="http://en.wikipedia.org/wiki/Diffie-Hellman">Diffie-Hellman</uri> |
839 |
protocol. For even more info go to the public library and grab a copy of the |
840 |
<uri link="http://www.cacr.math.uwaterloo.ca/hac/">"Handbook of Applied |
841 |
Cryptography"</uri> by Alfred J. Menezes, Paul C. van Oorschot and Scott A. |
842 |
Vanstone. This book is also available online for free at the above site. |
843 |
</p> |
844 |
|
845 |
<p> |
846 |
One consequence of the above is that if you cypher a message to me, and you |
847 |
loose the original uncyphered message you will no longer be able to retrieve it |
848 |
from the cyphered version. |
849 |
</p> |
850 |
|
851 |
</body> |
852 |
</section> |
853 |
<section> |
854 |
<title>Signatures</title> |
855 |
<body> |
856 |
|
857 |
<p> |
858 |
We already saw how someone can send us a cyphered message if they have our |
859 |
public key. But how do we know that the author of the message is really who he |
860 |
claims to be? Or in other words: If I receive an email from you how do I really |
861 |
know it was you and not someone else claiming to be you? |
862 |
</p> |
863 |
|
864 |
<p> |
865 |
Remember me saying that PKC was not as simple as I had said? The idea is that |
866 |
when you cypher a message to me you sign it with your private key so that, when |
867 |
I receive it, I can first use your public key to check your signature and then |
868 |
use my private key to decypher the message. As you can see we could not do |
869 |
that in the setup I described before. |
870 |
</p> |
871 |
|
872 |
<p> |
873 |
It's also very important to sign messages so that you don't have to cypher them |
874 |
beforehand. Now you can create messages that can be read by anyone, but that |
875 |
come with your "branding". And if any single character is changed in the message |
876 |
it can (and will) be detected. |
877 |
</p> |
878 |
|
879 |
</body> |
880 |
</section> |
881 |
<section> |
882 |
<title>Key Servers and Signed Keys</title> |
883 |
<body> |
884 |
|
885 |
<p> |
886 |
But let's say that I have no previous contact with you until you send me a |
887 |
message: how do I get your public key, and how do I really know it is yours? |
888 |
</p> |
889 |
|
890 |
<p> |
891 |
To solve this problem public Key Servers were created. When you create your key |
892 |
pair (Public and Private key), you send your public key to the key server. After |
893 |
this everyone can retrieve your key from there. This solves the problem of |
894 |
finding the key. But how do I really know that that key is the author's key? For |
895 |
this another concept must be introduced, and that is key signing: |
896 |
</p> |
897 |
|
898 |
<p> |
899 |
Key signing means that if I have the public key of another person, and I know |
900 |
<e>for sure</e> that it is really that persons key (it is my personal friend, |
901 |
someone I know in real life, etc.) I can sign that public key and send it to |
902 |
keyservers, that way I am telling the world: "This key really belongs to the |
903 |
person it claims to belong.". That way persons that have my public key and |
904 |
trust me can use that trust to trust other keys. |
905 |
</p> |
906 |
|
907 |
<p> |
908 |
This can sometimes be confusing so let's see a real world situation. |
909 |
</p> |
910 |
|
911 |
<p> |
912 |
Let's imagine a 3 person situation: John, Mary, and Lisa. John is a good |
913 |
friend of Mary but does not know Lisa; Lisa is a good friend of Mary but |
914 |
does not know John. One day Lisa sends John a signed email. John will fetch |
915 |
Lisa's Public Key from the keyserver and test the message, if all went ok he |
916 |
will see that whoever wrote that message also created that key. But how do I |
917 |
know it was really the person it claims to be? |
918 |
</p> |
919 |
|
920 |
<p> |
921 |
He then sees that it is signed by Mary, which he can check because he already |
922 |
has Mary's key and he trusts that key. With this ring of trust he continues to |
923 |
conclude that the email he received was really written by Lisa. |
924 |
</p> |
925 |
|
926 |
<p> |
927 |
You are now ready to use this guide, you can go back to chapter 1 and learn how |
928 |
to use gpg. |
929 |
</p> |
930 |
|
931 |
</body> |
932 |
</section> |
933 |
</chapter> |
934 |
|
935 |
<chapter> |
936 |
<title>Final thoughts and Credits</title> |
937 |
<section> |
938 |
<title>Some problems</title> |
939 |
<body> |
940 |
|
941 |
<p> |
942 |
I had some problems with photos in keys. Check the version you are using. If |
943 |
you have GnuPG 1.2.1-r1 and up you are probably OK, older versions may have |
944 |
problems. Also most keyservers don't like keys with photos, so you are better |
945 |
if you don't add photos. |
946 |
</p> |
947 |
|
948 |
<p> |
949 |
The latest versions of gnupg don't seem to work with the <c>gpg |
950 |
--send-keys</c> that was used so send all keys in your keyring to the public |
951 |
server. |
952 |
</p> |
953 |
|
954 |
</body> |
955 |
</section> |
956 |
<section> |
957 |
<title>What is not here</title> |
958 |
<body> |
959 |
|
960 |
<p> |
961 |
<c>gpg</c> is a very complex tool, it lets you do much more than what I have |
962 |
covered here. This document is for the user who is new to GnuPG. For more |
963 |
information, you should check the <uri link="http://www.gnupg.org">GnuPG |
964 |
Website</uri>. |
965 |
</p> |
966 |
|
967 |
<p> |
968 |
I did not write about other tools like <c>pgp4pine</c>, <c>gpgpine</c>, |
969 |
<c>evolution</c> and maybe Windows tools, but I will probably extend this |
970 |
document in the future. |
971 |
</p> |
972 |
|
973 |
</body> |
974 |
</section> |
975 |
<section> |
976 |
<title>Credits</title> |
977 |
<body> |
978 |
|
979 |
<p> |
980 |
John Michael Ashley's <uri link="http://www.gnupg.org">GnuPG Handbook</uri> |
981 |
it is a very good book for beginners. |
982 |
</p> |
983 |
|
984 |
<p> |
985 |
Swift (Sven Vermeulen) for pushing me to re-write this. |
986 |
</p> |
987 |
|
988 |
<p> |
989 |
Everyone in the #gentoo-doc team you guys rock. |
990 |
</p> |
991 |
|
992 |
<p> |
993 |
Tiago Serra for getting me back to the privacy track. |
994 |
</p> |
995 |
|
996 |
</body> |
997 |
</section> |
998 |
</chapter> |
999 |
</guide> |