/[gentoo]/xml/htdocs/doc/en/gnupg-user.xml
Gentoo

Contents of /xml/htdocs/doc/en/gnupg-user.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.49 - (hide annotations) (download) (as text)
Sun Jan 22 07:56:05 2012 UTC (2 years, 7 months ago) by nightmorph
Branch: MAIN
Changes since 1.48: +2 -2 lines
File MIME type: application/xml
fix internal link, bug 397707

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

  ViewVC Help
Powered by ViewVC 1.1.20