1
<chapter id="intro" xreflabel="1">
12
&Gnupg; is a tool for secure communication.
13
This chapter is a quick-start guide that covers the core functionality
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">.
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
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.
39
Generating a new keypair
43
The command-line option <link linkend="gen-key"><option>--gen-key</option></link>
44
is used to create a new primary keypair.
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.
53
Please select what kind of key you want:
54
(1) DSA and ElGamal (default)
56
(4) ElGamal (sign and encrypt)
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
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).
75
This doesn't quite work, but I agree the following paragraph is rough.
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
90
For most users the default option is fine.
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.
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)
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.
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.
124
Please specify how long the key should be valid.
125
0 = key does not expire
126
<n> = key expires in n days
127
<n>w = key expires in n weeks
128
<n>m = key expires in n months
129
<n>y = key expires in n years
130
Key is valid for? (0)
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.
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
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) <heinrichh@duesseldorf.de>"
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, ⪚, as an employee at work and a political activist
157
A user ID should be created carefully since it cannot be edited after
162
&Gnupg; needs a passphrase to protect the primary and subordinate
163
private keys that you keep in your possession.
166
You need a Passphrase to protect your private key.
171
There is no limit on the length of a passphrase, and it should be
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;.
183
<sect2 id="revocation">
185
Generating a revocation certificate
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
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.
202
<prompt>alice%</prompt> <userinput>gpg --output revoke.asc --gen-revoke mykey</userinput>
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.
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>.
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) <alice@cyb.org>
239
sub 1024g/78E9A8FA 1999-06-04
244
Exporting a public key
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>
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.
257
<prompt>alice%</prompt> <userinput>gpg --output alice.gpg --export alice@cyb.org</userinput>
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>
266
command-line options that are frequently used can also be set in a
267
<link linkend="optionsfile">configuration file</link>.
271
causes output to be generated in an ASCII-armored format similar to
273
In general, any output from &gnupg;, ⪚, keys, encrypted documents, and
274
signatures, can be ASCII-armored by adding the <option>--armor</option> option.
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
284
-----END PGP PUBLIC KEY BLOCK-----
290
Importing a public key
294
A public key may be added to your public keyring with the
295
<link linkend="import"><option>--import</option></link> option.
299
<prompt>alice%</prompt> <userinput>gpg --import blake.gpg</userinput>
300
gpg: key 9E98BC16: public key imported
301
gpg: Total number processed: 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) <alice@cyb.org>
307
sub 1024g/78E9A8FA 1999-06-04
309
pub 1024D/9E98BC16 1999-06-04 Blake (Executioner) <blake@cyb.org>
310
sub 1024g/5C8CBD41 1999-06-04
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.
325
<prompt>alice%</prompt> <userinput>gpg --edit-key blake@cyb.org</userinput>
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) <blake@cyb.org>
331
<prompt>Command></prompt> <userinput>fpr</userinput>
332
pub 1024D/9E98BC16 1999-06-04 Blake (Executioner) <blake@cyb.org>
333
Fingerprint: 268F 448F CCD7 AF34 183E 52D8 9BDE 1A08 9E98 BC16
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
342
Once verified you may sign the key to validate it.
346
<prompt>Command></prompt> <userinput>sign</userinput>
348
pub 1024D/9E98BC16 created: 1999-06-04 expires: never trust: -/q
349
Fingerprint: 268F 448F CCD7 AF34 183E 52D8 9BDE 1A08 9E98 BC16
351
Blake (Executioner) <blake@cyb.org>
353
Are you really sure that you want to sign this key
354
with your key: "Alice (Judge) <alice@cyb.org>"
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.
367
<prompt>Command></prompt> <userinput>check</userinput>
368
uid Blake (Executioner) <blake@cyb.org>
369
sig! 9E98BC16 1999-06-04 [self-signature]
370
sig! BB7576AC 1999-06-04 Alice (Judge) <alice@cyb.org>
377
Encrypting and decrypting documents
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
392
<prompt>alice%</prompt> <userinput>gpg --output doc.gpg --encrypt --recipient blake@cyb.org doc</userinput>
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.
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.
413
<prompt>blake%</prompt> <userinput>gpg --output doc --decrypt doc.gpg</userinput>
415
You need a passphrase to unlock the secret key for
416
user: "Blake (Executioner) <blake@cyb.org>"
417
1024-bit ELG-E key, ID 5C8CBD41, created 1999-06-04 (main key ID 9E98BC16)
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.
435
<prompt>alice%</prompt> <userinput>gpg --output doc.gpg --symmetric doc</userinput>
442
Making and verifying signatures
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.
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.
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.
470
<prompt>alice%</prompt> <userinput>gpg --output doc.sig --sign doc</userinput>
472
You need a passphrase to unlock the private key for
473
user: "Alice (Judge) <alice@cyb.org>"
474
1024-bit DSA key, ID BB7576AC, created 1999-06-04
479
The document is compressed before signed, and the output is in binary
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>
491
The signed document to verify and recover is input and the recovered
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) <alice@cyb.org>"
503
Clearsigned documents
507
A common use of digital signatures is to sign usenet postings or
509
In such situations it is undesirable to compress the document while
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.
518
<prompt>alice%</prompt> <userinput>gpg --clearsign doc</userinput>
520
You need a passphrase to unlock the secret key for
521
user: "Alice (Judge) <alice@cyb.org>"
522
1024-bit DSA key, ID BB7576AC, created 1999-06-04
524
-----BEGIN PGP SIGNED MESSAGE-----
528
-----BEGIN PGP SIGNATURE-----
529
Version: GnuPG v0.9.7 (GNU/Linux)
530
Comment: For info see http://www.gnupg.org
532
iEYEARECAAYFAjdYCQoACgkQJ9S6ULt1dqz6IwCfQ7wP6i/i8HhbcOSKF4ELyQB1
533
oCoAoOuqpRqEzr4kOkQqHRLE/b8/Rw2k
535
-----END PGP SIGNATURE-----
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>
557
<prompt>alice%</prompt> <userinput>gpg --output doc.sig --detach-sig doc</userinput>
559
You need a passphrase to unlock the secret key for
560
user: "Alice (Judge) <alice@cyb.org>"
561
1024-bit DSA key, ID BB7576AC, created 1999-06-04
567
Both the document and detached signature are needed to verify
569
The <option>--verify</option> option can be to check the
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) <alice@cyb.org>"
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:
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)
593
What prompted this was wondering, as I read through the generating keypair
594
section, "under what circumstances would these defaults be inappropriate?"
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)
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:"
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.
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.
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").
added
removed
doc/gph/c1.sgml
