Marked unused slots in the trustdb.
[gnupg.git] / doc / gph / c1.sgml
1 <chapter id="intro" xreflabel="1">
2 <docinfo>
3 <date>
4 $Id$
5 </date>
6 </docinfo>
7 <title>
8 Getting Started
9 </title>
10
11 <para>
12 &Gnupg; is a tool for secure communication.
13 This chapter is a quick-start guide that covers the core functionality
14 of &gnupg;.
15 This includes keypair creation, exchanging and verifying keys, encrypting
16 and decrypting documents, and making and verifying signatures.
17 It does not explain in detail the concepts behind public-key cryptography,
18 encryption, and digital signatures.
19 This is covered in Chapter <xref linkend="concepts">.
20 It also does not explain how to use &gnupg; wisely.
21 This is covered in Chapters <xref linkend="management"> and 
22 <xref linkend="wise">.
23 </para>
24
25 <para>
26 &Gnupg; uses public-key cryptography so that users may communicate securely.
27 In a public-key system, each user has a public/private keypair.
28 A user's private key is kept secret; it need never be revealed.
29 The public key may be given to anyone with whom the user wants to
30 communicate.
31 &Gnupg; uses a somewhat more sophisticated scheme in which a user has
32 a primary keypair and then zero or more additional subordinate keypairs.
33 The primary and subordinate keypairs are bundled to facilitate key
34 management and the bundle can often be considered simply as one keypair.
35 </para>
36
37 <sect1>
38 <title>
39 Generating a new keypair
40 </title>
41
42 <para>
43 The command-line option <link linkend="gen-key"><option>--gen-key</option></link>
44 is used to create a new primary keypair.
45
46 <screen width="80">
47 <prompt>alice%</prompt> <userinput>gpg --gen-key</userinput>
48 gpg (GnuPG) 0.9.4; Copyright (C) 1999 Free Software Foundation, Inc.
49 This program comes with ABSOLUTELY NO WARRANTY.
50 This is free software, and you are welcome to redistribute it
51 under certain conditions. See the file COPYING for details.
52
53 Please select what kind of key you want:
54    (1) DSA and ElGamal (default)
55    (2) DSA (sign only)
56    (4) ElGamal (sign and encrypt)
57 Your selection?
58 </screen>
59
60 <!--
61 REWRITE
62 From Thomas Zander (zander@microweb.nl):
63 In GPG you can create 3 type of keypairs. A keypair is the combination
64 of a publ ic key and a private key, see chapter X. A DSA keypair can
65 only be used to sign a message. A ElGamal subordinate keypair can be
66 used for encryption as well as s igning, but is not as compatible with
67 former standards.
68
69 Option 1 creates 2 keypairs; a DSA (signing) and a ElGamal (Encryption).
70 Option 2 creates a DSA keypair (Signing)
71 Option 4 creates a ElGemal keypair (Signing & Encryption).
72
73 note: option 3 xxxx
74
75 This doesn't quite work, but I agree the following paragraph is rough.
76 -->
77
78 &Gnupg; is able to create several different types of keypairs, but a primary
79 key must be capable of making signatures.
80 There are therefore only three options.
81 Option 1 actually creates two keypairs.
82 A DSA keypair is the primary keypair usable only for making signatures.
83 An ElGamal subordinate keypair is also created for encryption. 
84 Option 2 is similar but creates only a DSA keypair.
85 Option 4<footnote><para>Option 3 is to generate an ElGamal keypair that is
86 not usable for making signatures.</para></footnote> creates a single ElGamal 
87 keypair usable for both making signatures and performing encryption.
88 In all cases it is possible to later add additional subkeys for encryption
89 and signing.
90 For most users the default option is fine.
91 </para>
92
93 <para>
94 You must also choose a key size.
95 The size of a DSA key must be between 512 and 1024 bits, and an ElGamal
96 key may be of any size.
97 &Gnupg;, however, requires that keys be no smaller than 768 bits.
98 Therefore, if Option 1 was chosen and you choose a keysize larger than
99 1024 bits, the ElGamal key will have the requested size, but the DSA
100 key will be 1024 bits.
101
102 <screen width="80">
103 About to generate a new ELG-E keypair.
104               minimum keysize is  768 bits
105               default keysize is 1024 bits
106     highest suggested keysize is 2048 bits
107 What keysize do you want? (1024)
108 </screen>
109
110 The longer the key the more secure it is against brute-force attacks,
111 but for almost all purposes the default keysize is adequate since
112 it would be cheaper to circumvent the encryption than try to break it.
113 Also, encryption and decryption will be slower as the
114 key size is increased, and a larger keysize may affect signature length.
115 Once selected, the keysize can never be changed.
116 </para>
117
118 <para>
119 Finally, you must choose an expiration date.
120 If Option 1 was chosen, the expiration date will be used for both the
121 ElGamal and DSA keypairs.
122
123 <screen width="80">
124 Please specify how long the key should be valid.
125          0 = key does not expire
126       &lt;n>  = key expires in n days
127       &lt;n>w = key expires in n weeks
128       &lt;n>m = key expires in n months
129       &lt;n>y = key expires in n years
130 Key is valid for? (0) 
131 </screen>
132
133 For most users a key that does not expire is adequate.
134 The expiration time should be chosen with care, however,
135 since although it is possible to change the expiration date after the key
136 is created, it may be difficult to communicate a change
137 to users who have your public key.
138 </para>
139
140 <para>
141 You must provide a user ID in addition to the key parameters.
142 The user ID is used to associate the key being created with a real
143 person.
144
145 <screen width="80">
146 You need a User-ID to identify your key; the software constructs the user id
147 from Real Name, Comment and Email Address in this form:
148     "Heinrich Heine (Der Dichter) &lt;heinrichh@duesseldorf.de>"
149
150 Real name: 
151 </screen>
152
153 Only one user ID is created when a key is created, but it is possible
154 to create additional user IDs if you want to use the key in two or
155 more contexts, &eg;, as an employee at work and a political activist
156 on the side.
157 A user ID should be created carefully since it cannot be edited after
158 it is created.
159 </para>
160
161 <para>
162 &Gnupg; needs a passphrase to protect the primary and subordinate 
163 private keys that you keep in your possession.
164
165 <screen width="80">
166 You need a Passphrase to protect your private key.    
167
168 Enter passphrase: 
169 </screen>
170
171 There is no limit on the length of a passphrase, and it should be
172 carefully chosen.
173 From the perspective of security, the passphrase to unlock the private
174 key is one of the weakest points in &gnupg; (and other public-key 
175 encryption systems as well) since it is the only protection you 
176 have if another individual gets your private key.
177 Ideally, the passphrase should not use words from a dictionary and
178 should mix the case of alphabetic characters as well as use 
179 non-alphabetic characters.
180 A good passphrase is crucial to the secure use of &gnupg;.
181 </para>
182
183 <sect2 id="revocation">
184 <title>
185 Generating a revocation certificate
186 </title>
187
188 <para>
189 After your keypair is created you should immediately generate a revocation
190 certificate for the primary public key using the option
191 <link linkend="gen-revoke"><option>--gen-revoke</option></link>.
192 If you forget your passphrase or if your private key is compromised 
193 or lost, this revocation certificate may be published to notify others
194 that the public key should no longer be used.
195 A revoked public key can still be used to verify signatures made
196 by you in the past, but it cannot be used to encrypt future messages
197 to you.
198 It also does not affect your ability to decrypt messages sent to
199 you in the past if you still do have access to the private key.
200
201 <screen width="80">
202 <prompt>alice%</prompt> <userinput>gpg --output revoke.asc --gen-revoke mykey</userinput>
203 [...]
204 </screen>
205
206 The argument <userinput>mykey</userinput> must be a <emphasis>key
207 specifier</emphasis>,
208 either the key ID of your primary keypair or any part of a user ID
209 that identifies your keypair.
210 The generated certificate will be left in the file
211 <parameter>revoke.asc</parameter>.
212 If the <link linkend="output"><option>--output</option></link> option is 
213 omitted, the result will be placed on standard output.
214 Since the certificate is short, you may wish to print a hardcopy of
215 the certificate to store somewhere safe such as your safe deposit box.
216 The certificate should not be stored where others can access it since
217 anybody can publish the revocation certificate and render the
218 corresponding public key useless.
219 </para>
220 </sect2>
221 </sect1>
222
223 <sect1>
224 <title>
225 Exchanging keys
226 </title>
227
228 <para>
229 To communicate with others you must exchange public keys.
230 To list the keys on your public keyring use the command-line 
231 option <link linkend="list-keys"><option>--list-keys</option></link>.
232 </para>
233
234 <screen width="80">
235 <prompt>alice%</prompt> <userinput>gpg --list-keys</userinput>
236 /users/alice/.gnupg/pubring.gpg
237 ---------------------------------------
238 pub  1024D/BB7576AC 1999-06-04 Alice (Judge) &lt;alice@cyb.org>
239 sub  1024g/78E9A8FA 1999-06-04
240 </screen>
241
242 <sect2>
243 <title>
244 Exporting a public key
245 </title>
246
247 <para>
248 To send your public key to a correspondent you must first export it.
249 The command-line option <link linkend="export"><option>--export</option></link>
250 is used to do this.
251 It takes an additional argument identifying the public key to export.
252 As with the <option>--gen-revoke</option> option, either the key ID or any part of
253 the user ID may be used to identify the key to export.
254 </para>
255
256 <screen width="80">
257 <prompt>alice%</prompt> <userinput>gpg --output alice.gpg --export alice@cyb.org</userinput>
258 </screen>
259
260 <para>
261 The key is exported in a binary format, but this can be inconvenient
262 when the key is to be sent though email or published on a web page.
263 &Gnupg; therefore supports a command-line option 
264 <link linkend="armor"><option>--armor</option></link><footnote>
265 <para>Many
266 command-line options that are frequently used can also be set in a
267 <link linkend="optionsfile">configuration file</link>.
268 </para>
269 </footnote>
270 that that 
271 causes output to be generated in an ASCII-armored format similar to
272 uuencoded documents.
273 In general, any output from &gnupg;, &eg;, keys, encrypted documents, and
274 signatures, can be ASCII-armored by adding the <option>--armor</option> option.
275 </para>
276
277 <screen width="80">
278 <prompt>alice%</prompt> <userinput>gpg --armor --export alice@cyb.org</userinput>
279 -----BEGIN PGP PUBLIC KEY BLOCK-----
280 Version: GnuPG v0.9.7 (GNU/Linux)
281 Comment: For info see http://www.gnupg.org
282
283 [...]
284 -----END PGP PUBLIC KEY BLOCK-----
285 </screen>
286 </sect2>
287
288 <sect2>
289 <title>
290 Importing a public key
291 </title>
292
293 <para>
294 A public key may be added to your public keyring with the
295 <link linkend="import"><option>--import</option></link> option.
296 </para>
297
298 <screen width="80">
299 <prompt>alice%</prompt> <userinput>gpg --import blake.gpg</userinput>
300 gpg: key 9E98BC16: public key imported
301 gpg: Total number processed: 1
302 gpg:               imported: 1
303 <prompt>alice%</prompt> <userinput>gpg --list-keys</userinput>
304 /users/alice/.gnupg/pubring.gpg
305 ---------------------------------------
306 pub  1024D/BB7576AC 1999-06-04 Alice (Judge) &lt;alice@cyb.org>
307 sub  1024g/78E9A8FA 1999-06-04
308
309 pub  1024D/9E98BC16 1999-06-04 Blake (Executioner) &lt;blake@cyb.org>
310 sub  1024g/5C8CBD41 1999-06-04
311 </screen>
312
313 <para>
314 Once a key is imported it should be validated.
315 &Gnupg; uses a powerful and flexible trust model that does not require
316 you to personally validate each key you import.
317 Some keys may need to be personally validated, however.
318 A key is validated by verifying the key's fingerprint and then signing
319 the key to certify it as a valid key.
320 A key's fingerprint can be quickly viewed with the
321 <link linkend="fingerprint"><option>--fingerprint</option></link>
322 command-line option, but in order to certify the key you must edit it.
323
324 <screen width="80">
325 <prompt>alice%</prompt> <userinput>gpg --edit-key blake@cyb.org</userinput>
326
327 pub  1024D/9E98BC16  created: 1999-06-04 expires: never      trust: -/q
328 sub  1024g/5C8CBD41  created: 1999-06-04 expires: never     
329 (1)  Blake (Executioner) &lt;blake@cyb.org>
330
331 <prompt>Command></prompt> <userinput>fpr</userinput>
332 pub  1024D/9E98BC16 1999-06-04 Blake (Executioner) &lt;blake@cyb.org>
333              Fingerprint: 268F 448F CCD7 AF34 183E  52D8 9BDE 1A08 9E98 BC16
334 </screen>
335
336 Key verification is a weak point in public-key cryptography, so you
337 must be sure that the fingerprint is correct.
338 The fingerprint displayed should be checked with the key's owner.
339 This may be done in person or over the phone or through any other means
340 as long as you can guarantee that you are communicating with the key's
341 true owner.
342 Once verified you may sign the key to validate it.
343 </para>
344
345 <screen width="80">
346 <prompt>Command></prompt> <userinput>sign</userinput>
347              
348 pub  1024D/9E98BC16  created: 1999-06-04 expires: never      trust: -/q
349              Fingerprint: 268F 448F CCD7 AF34 183E  52D8 9BDE 1A08 9E98 BC16
350
351      Blake (Executioner) &lt;blake@cyb.org>
352
353 Are you really sure that you want to sign this key
354 with your key: "Alice (Judge) &lt;alice@cyb.org>"
355
356 Really sign?
357 </screen>
358
359 <para>
360 Once signed you can check the key to list the signatures on it and
361 see the signature that you have added.
362 Every user ID on the key will have one or more self-signatures as well
363 as a signature for each user that has validated the key.
364 </para>
365
366 <screen width="80">
367 <prompt>Command></prompt> <userinput>check</userinput>
368 uid  Blake (Executioner) &lt;blake@cyb.org>
369 sig!       9E98BC16 1999-06-04   [self-signature]
370 sig!       BB7576AC 1999-06-04   Alice (Judge) &lt;alice@cyb.org>
371 </screen>
372 </sect2>
373 </sect1>
374
375 <sect1>
376 <title>
377 Encrypting and decrypting documents
378 </title>
379
380 <para>
381 To encrypt a document the option 
382 <link linkend="encrypt"><option>--encrypt</option></link> is used.
383 You must have the public keys of the intended recipients.
384 The software expects the name of the document to encrypt as input or, if
385 omitted, on standard input.
386 The encrypted result is placed on standard output or as specified using
387 the option <option>--output</option>.
388 The document is compressed for additional security in addition to
389 encrypting it.
390
391 <screen width="80">
392 <prompt>alice%</prompt> <userinput>gpg --output doc.gpg --encrypt --recipient blake@cyb.org doc</userinput>
393 </screen>
394
395 The <link linkend="recipient"><option>--recipient</option></link> option
396 is used once for each recipient and takes an extra argument specifying
397 the public key to which the document should be encrypted.
398 The encrypted document can only be decrypted by someone with a private
399 key that complements one of the recipients' public keys.
400 In particular, you cannot decrypt a document encrypted by you unless
401 you included your own public key in the recipient list.
402 </para>
403
404 <para>
405 To decrypt a message the option 
406 <link linkend="decrypt"><option>--decrypt</option></link> is used.
407 You need the private key to which the message was encrypted.
408 Similar to the encryption process, the document to decrypt is
409 input, and the decrypted result is output.
410 </para>
411
412 <screen width="80">
413 <prompt>blake%</prompt> <userinput>gpg --output doc --decrypt doc.gpg</userinput>
414
415 You need a passphrase to unlock the secret key for
416 user: "Blake (Executioner) &lt;blake@cyb.org>"
417 1024-bit ELG-E key, ID 5C8CBD41, created 1999-06-04 (main key ID 9E98BC16)
418
419 Enter passphrase: 
420 </screen>
421
422 <para>
423 Documents may also be encrypted without using public-key cryptography.
424 Instead, only a symmetric cipher is used to encrypt the document.
425 The key used to drive the symmetric cipher is derived from a passphrase
426 supplied when the document is encrypted, and for good security, it
427 should not be the same passphrase that you use to protect your private key.
428 Symmetric encryption is useful for securing documents when the
429 passphrase does not need to be communicated to others.
430 A document can be encrypted with a symmetric cipher by using the
431 <link linkend="symmetric"><option>--symmetric</option></link> option.
432 </para>
433
434 <screen width="80">
435 <prompt>alice%</prompt> <userinput>gpg --output doc.gpg --symmetric doc</userinput>
436 Enter passphrase: 
437 </screen>
438 </sect1>
439
440 <sect1>
441 <title>
442 Making and verifying signatures
443 </title>
444
445 <para>
446 A digital signature certifies and timestamps a document.
447 If the document is subsequently modified in any way, a verification
448 of the signature will fail.
449 A digital signature can serve the same purpose as a hand-written signature
450 with the additional benefit of being tamper-resistant.
451 The &gnupg; source distribution, for example, is signed so that users can
452 verify that the source code has not been modified since it was packaged.
453 </para>
454
455 <para>
456 Creating and verifying signatures uses the public/private keypair
457 in an operation different from encryption and decryption.
458 A signature is created using the private key of the signer.
459 The signature is verified using the corresponding public key.
460 A consequence is that it is difficult to deny that you made a digital
461 signature since that would imply your private key had been compromised.
462 </para>
463
464 <para>
465 The command-line option <link linkend="sign"><option>--sign</option></link> is
466 used to make a digital signature.
467 The document to sign is input, and the signed document is output.
468
469 <screen width="80">
470 <prompt>alice%</prompt> <userinput>gpg --output doc.sig --sign doc</userinput>
471
472 You need a passphrase to unlock the private key for
473 user: "Alice (Judge) &lt;alice@cyb.org>"
474 1024-bit DSA key, ID BB7576AC, created 1999-06-04
475
476 Enter passphrase: 
477 </screen>
478
479 The document is compressed before signed, and the output is in binary
480 format.
481 </para>
482
483 <para>
484 Given a signed document, you can either check the signature or
485 check the signature and recover the original document.
486 To check the signature use the 
487 <link linkend="verify"><option>--verify</option></link> option.
488 To verify the signature and extract the document use the
489 <option>--decrypt</option>
490 option.
491 The signed document to verify and recover is input and the recovered
492 document is output.
493 </para>
494
495 <screen width="80">
496 <prompt>blake%</prompt> <userinput>gpg --output doc --decrypt doc.sig</userinput>
497 gpg: Signature made Fri Jun  4 12:02:38 1999 CDT using DSA key ID BB7576AC
498 gpg: Good signature from "Alice (Judge) &lt;alice@cyb.org>"
499 </screen>
500
501 <sect2>
502 <title>
503 Clearsigned documents
504 </title>
505
506 <para>
507 A common use of digital signatures is to sign usenet postings or
508 email messages.
509 In such situations it is undesirable to compress the document while
510 signing it.
511 The option 
512 <link linkend="clearsign"><option>--clearsign</option></link> 
513 causes the document to be wrapped in an ASCII-armored signature but 
514 otherwise does not modify the document.
515 </para>
516
517 <screen width="80">
518 <prompt>alice%</prompt> <userinput>gpg --clearsign doc</userinput>
519
520 You need a passphrase to unlock the secret key for
521 user: "Alice (Judge) &lt;alice@cyb.org>"
522 1024-bit DSA key, ID BB7576AC, created 1999-06-04
523
524 -----BEGIN PGP SIGNED MESSAGE-----
525 Hash: SHA1
526
527 [...]
528 -----BEGIN PGP SIGNATURE-----
529 Version: GnuPG v0.9.7 (GNU/Linux)
530 Comment: For info see http://www.gnupg.org
531
532 iEYEARECAAYFAjdYCQoACgkQJ9S6ULt1dqz6IwCfQ7wP6i/i8HhbcOSKF4ELyQB1
533 oCoAoOuqpRqEzr4kOkQqHRLE/b8/Rw2k
534 =y6kj
535 -----END PGP SIGNATURE-----
536 </screen>
537 </sect2>
538
539 <sect2>
540 <title>
541 Detached signatures
542 </title>
543
544 <para>
545 A signed document has limited usefulness.
546 Other users must recover the original document from the signed
547 version, and even with clearsigned documents, the signed document
548 must be edited to recover the original.
549 Therefore, there is a third method for signing a document that
550 creates a detached signature.
551 A detached signature is created using the 
552 <link linkend="detach-sig"><option>--detach-sig</option></link>
553 option.
554 </para>
555
556 <screen width="80">
557 <prompt>alice%</prompt> <userinput>gpg --output doc.sig --detach-sig doc</userinput>
558
559 You need a passphrase to unlock the secret key for
560 user: "Alice (Judge) &lt;alice@cyb.org>"
561 1024-bit DSA key, ID BB7576AC, created 1999-06-04
562
563 Enter passphrase: 
564 </screen>
565
566 <para>
567 Both the document and detached signature are needed to verify
568 the signature.
569 The <option>--verify</option> option can be to check the 
570 signature.
571 </para>
572
573 <screen width="80">
574 <prompt>blake%</prompt> <userinput>gpg --verify doc.sig doc</userinput>
575 gpg: Signature made Fri Jun  4 12:38:46 1999 CDT using DSA key ID BB7576AC
576 gpg: Good signature from "Alice (Judge) &lt;alice@cyb.org>"
577 </screen>
578 </sect2>
579 </sect1>
580 </chapter>
581
582 <!--
583 In the "Getting Started" chapter, it would be interesting to provide
584 a checklist of assumptions that the reader can consult to determine
585 whether or not she fits the "most users" profile.  Perhaps put this
586 at the end of the chapter (perhaps w/ forward pointer?).  You could
587 include cross references for each item on the list.  For example:
588
589     23.  Your use of public key encryption has property X with attribute Y.
590          (see Section 3.4.1 for a more detailed discussion of other
591           attributes of property X)
592
593 What prompted this was wondering, as I read through the generating keypair
594 section, "under what circumstances would these defaults be inappropriate?"
595
596 The notion of using the same key with different user IDs "as an employee at
597 work and a political activist on the side" is interesting.  Knowing one,
598 could you be traced to the other?  (Are they separate numeric ids, and is
599 that enough?)  (seems someone could just match the public keys)
600
601 It's a very nice touch that you don't cover every single prompt that the
602 system throws at you, but instead treat them functionally.  For example,
603 I can imagine other books going through the "Comment:" and "Email Address:"
604 prompts.
605 -->
606
607 <!--
608 "Key verification is a weak point in public-key cryptography ..."
609 Saying "weak point" makes it sound like a slam on public key stuff.
610 Although we've talked about weaknesses of the trust model, I'm guessing
611 the point here is that communication is only secure if you verify the
612 identity of the key's owner.
613
614 Key verification can be done through any means "as long as you can
615 guarantee that you are communicating with the key's true owner".
616 I suspect we'd also like to prevent leaking information that an
617 interceptor could use to pose as us in a key verification step with
618 another party.  I suppose the notion of bootstrapping may not be widely
619 appreciated as an analogy.
620
621 I'm almost inclined to want to see a section in the Getting Started
622 guide called "Why you should read the rest of this book".  Failing
623 that, or perhaps better yet, maybe it would work to have some margin
624 notes that point to other sections of the book for more information
625 ("a discussion of trust models begins on p. 95").
626 -->
627