some bug fixes
[gnupg.git] / doc / gpg.1pod
1 =head1 NAME
2
3 gpg - GNU Privacy Guard
4
5 =head1 SYNOPSIS
6
7 B<gpg> [--homedir name] [--options file] [options] command [args]
8
9 B<gpgm> [--homedir name] [--options file] [options] command [args]
10
11 =head1 DESCRIPTION
12
13 B<gpg> is the main program for the GNUPG system. B<gpgm> is a maintenance
14 tool which has some commands B<gpgm> does not have; it is there because
15 it does not handle sensitive data and therefore has no need to allocate
16 secure memory.
17
18 =head1 COMMANDS
19
20 B<gpg> recognizes these commands:
21
22 B<-s>, B<--sign>
23     Make a signature. This option may be combined
24     with B<--encrypt>.
25
26 B<--clearsign>
27     Make a clear text signature.
28
29 B<-b>, B<--detach-sign>
30     Make a detached signature.
31
32 B<-e>, B<--encrypt>
33     Encrypt data. This option may be combined with B<--sign>.
34
35 B<-c>, B<--symmetric>
36     Encrypt with symmetric cipher only
37     This command asks for a passphrase.
38
39 B<--store>
40     store only (make a simple RFC1991 packet).
41
42 B<--decrypt> [I<file>]
43     Decrypt file (or stdin if no file is specified) and
44     write it to stdout (or the file specified with
45     B<--output>). If the decrypted file is signed, the
46     signature is also verified. This command differs
47     from the default operation, as it never writes to the
48     filename which is included in the file and it
49     rejects files which don't begin with an encrypted
50     message.
51
52 B<--verify> [[I<sigfile>] {I<signed-files>}]
53     Assume that I<filename> is a signature and verify it
54     without generating any output.  With no arguments,
55     the signature packet is read from stdin (it may be a
56     detached signature when not used in batch mode). If
57     only a sigfile is given, it may be a complete
58     signature or a detached signature, in which case
59     the signed stuff is expected in a file without the
60     I<.sig> or I<.asc> extension (if such a file does
61     not exist it is expected at stdin - use B<-> as
62     filename to force a read from stdin). With more than
63     1 argument, the first should be a detached signature
64     and the remaining files are the signed stuff.
65
66 B<-k> [I<username>] [I<keyring>]
67     Kludge to be somewhat compatible with PGP.
68     Without arguments, all public keyrings are listed.
69     With one argument, only I<keyring> is listed.
70     Special combinations are also allowed, but it may
71     give strange results when combined with more options.
72     B<-kv>    Same as B<-k>
73     B<-kvv>   List the signatures with every key.
74     B<-kvvv>  Additionally check all signatures.
75     B<-kvc>   List fingerprints
76     B<-kvvc>  List fingerprints and signatures
77
78 B<--list-keys>  [I<names>]
79     List all keys from the public keyrings, or just the
80     ones given on the command line.
81
82 B<--list-secret-keys> [I<names>]
83     List all keys from the secret keyrings, or just the
84     ones given on the command line.
85
86 B<--list-sigs>  [I<names>]
87     Same as B<--list-keys>, but the signatures are listed
88     too.
89
90 B<--check-sigs> [I<names>]
91     Same as B<--list-sigs>, but the signatures are verified.
92
93 B<--fingerprint> [I<names>]
94     List all keys with their fingerprints. This is the
95     same output as B<list-keys> but with the additonal output
96     of a line with the fingerprint. May also be combined
97     with B<--list-sigs> or B<--check-sigs>.
98
99 B<--list-packets>
100     List only the sequence of packets. This is mainly
101     useful for debugging.
102
103 B<--gen-key>
104     Generate a new key pair. This command can only be
105     used interactive.
106
107
108 B<--edit-key> I<name>
109     Present a menu which enables you to do all key
110     related tasks:
111     B<sign>
112       Make a signature on key of user I<name>.
113       If the key is not yet signed by the default
114       user (or the users given with B<-u>), the
115       program displays the information of the key
116       again, together with its fingerprint and
117       asks whether it should be signed. This
118       question is repeated for all users specified
119       with B<-u>.
120     B<trust>
121       Change the owner trust value. This updates the
122       trust-db immediately and no save is required.
123     B<adduid>
124       Create an alternate user id.
125     B<deluid>
126       Delete an user id.
127     B<addkey>
128        Add a subkey to this key.
129     B<delkey>
130        Remove a subkey.
131     B<expire>
132        Change the key expiration time.  If a key is
133        select, the time of this key will be changed.
134        With no selection the key expiration of the
135        primary key is changed.
136     B<passwd>
137        Change the passphrase of the secret key.
138     B<uid> I<n>
139        Toggle selection of user id with index I<n>.
140        Use 0 to deselect all.
141     B<key> I<n>
142        Toggle selection of subkey with index I<n>.
143        Use 0 to deselect all.
144     B<check>
145        Check all selected user ids.
146     B<pref>
147        List preferences.
148     B<toggle>
149        Toggle between public and secret key listing.
150     B<save>
151        Save all changes to the key rings and quit.
152     B<quit>
153        Quit the program without updating the
154        key rings.
155     The listing shows you the key with its secondary
156     keys and all user ids. Selected keys or user ids
157     indicated by an asterisk. The trust value is
158     displayed with the primary key: The first one is the
159     assigned owner trust and the second the calculated
160     trust value; letters are used for the values:
161       B<->  No ownertrust assigned / not yet calculated.
162       B<e>  Trust calculation has failed.
163       B<q>  Not enough information for calculation.
164       B<n>  Never trust this key.
165       B<m>  Marginally trusted.
166       B<f>  Fully trusted.
167       B<u>  Ultimately trusted
168
169
170 B<--delete-key>
171     Remove key from the public keyring
172
173 B<--delete-secret-key>
174     Remove key from the secret and public keyring
175
176 B<--gen-revoke>
177     Generate a revocation certificate.
178
179 B<--export> [I<names>]
180     Either export all keys from all keyrings (default
181     keyrings and those registered via option B<--keyring>),
182     or if at least one name is given, those of the given
183     name. The new keyring is written to F<stdout> or to
184     the file given with option "output".  Use together
185     with B<-a> to mail those keys.
186
187
188 B<--export-secret-keys> [I<names>
189     Same as B<--export>, but does export the secret keys.
190     This is normally not very useful.
191
192 B<--import>, B<--fast-import>
193     Import/merge keys.  The fast version does not build
194     the trustdb; this can be deon at anytime with the
195     command B<--update-trustdb>.
196
197 B<--export-ownertrust>
198     List the assigned ownertrust values in ascii format
199     for backup purposes [B<gpgm> only].
200
201 B<--import-ownertrust> [I<filename>]
202     Update the trustdb with the ownertrust values stored
203     in I<filename> (or stdin if not given); existing
204     values will be overwritten. [B<gpgm> only].
205
206 =head1 OPTIONS
207
208 Long options can be put in an options file (default F<~/.gnupg/options>);
209 do not write the 2 dashes, but simply the name of the option and any
210 arguments if required.  Lines with a hash as the first non-white-space
211 character are ignored. Commands may be put in this file too, but that
212 does not make sense.
213
214 B<gpg> recognizes these options:
215
216
217 B<-a>, B<--armor>
218     Create ASCII armored output.
219
220 B<-o> I<file>, B<--output> I<file>
221     Write output to I<file>.
222
223 B<-u> I<name>, B<--local-user> I<name>
224     Use I<name> as the user-id to sign.
225     This option is silently ignored for the list commands,
226     so that it can be used in an options file.
227
228 B<--default-key>  I<name>
229     Use I<name> as default user-id for signatures.  If this
230     is not used the default user-id is the first user-id
231     from the secret keyring.
232
233 B<-r>  I<name>, B<--remote-user>  I<name>
234     Use I<name> as the user-id for encryption.
235     This option is silently ignored for the list commands,
236     so that it can be used in an options file.
237
238 B<-v>, B<--verbose>
239     Give more information during processing. If used
240     twice, the input data is listed in detail.
241
242 B<-q>, B<--quiet>
243     Be somewhat more quiet in some cases.
244
245 B<-z> I<n>
246     Set compress level to I<n>. A value of 0 for I<n>
247     disables compression. Default is to use the default
248     compression level of zlib (which is 6).
249
250 B<-t>, B<--textmode>
251     Use canonical text mode.  If B<-t> (but not
252     B<--textmode>) is used together with armoring
253     and signing, this enables clearsigned messages.
254     This kludge is needed for PGP compatibility;
255     normally you would use B<--sign> or b<--clearsign>
256     to selected the type os signatures.
257
258 B<-n>, B<--dry-run>
259     Don't make any changes (not yet implemented).
260
261 B<--batch>
262     Batch mode; never ask, do not allow interactive
263     commands.
264
265 B<--no-batch>
266     Disable batch mode; this may be used if B<batch>
267     is used in the options file.
268
269 B<--yes>
270     Assume "yes" on most questions.
271
272 B<--no>
273     Assume "no" on most questions.
274
275 B<--keyring> I<file>
276     Add I<file> to the list of keyrings.
277     If I<file> begins with a tilde and a slash, these
278     are replaced by the HOME directory. If the filename
279     does not contain a slash, it is assumed to be in the
280     home-directory (F<~/.gnupg> if B<--homedir>) is not used.
281     The filename may be prefixed with a scheme:
282       "gnupg-ring:" is the default one.
283       "gnupg-gdbm:" may be used for a GDBM ring.
284
285 B<--secret-keyring> I<file>
286     Same as B<--keyring> but for secret keyrings.
287
288
289 B<--homedir> I<dir>
290     Set the name of the home directory to I<dir>. If this
291     option is not used it defaults to F<~/.gnupg>. It does
292     not make sense to use this in a options file. This
293     also overrides the environment variable C<GNUPGHOME>.
294
295 B<--charset> I<name>
296     Set the name of the native character set.  This is used
297     to convert some strings to proper UTF-8 encoding.
298     Valid values for I<name> are:
299       B<iso-8859-1>  This is the default.
300       B<koi8-r>      The usual Russian set (rfc1489).
301
302 B<--options> I<file>
303     Read options from I<file> and do not try to read
304     them from the default options file in the homedir
305     (see B<--homedir>). This option is ignored when used
306     in an options file.
307
308 B<--no-options>
309     Shortcut for B<--options> I</dev/null>.  This option is
310     detected before an attempt to open an option file.
311
312 B<--load-extension> I<modulename>
313     Load an extension module. If I<modulename> does not
314     contain a slash it is searched in B</usr/local/lib/gnupg>
315     See the manual for more information about extensions.
316
317 B<--debug> I<flags>
318     Set debugging flags. All flags are or-ed and I<flags> may
319     be given in C syntax (e.g. 0x0042).
320
321 B<--debug-all>
322     Set all useful debugging flags.
323
324 B<--status-fd> I<n>
325     Write special status strings to the file descriptor I<n>.
326
327 B<--no-comment>
328     Do not write comment packets.  This option affects only
329     the generation of secret keys.  Output of option packets
330     is disabled since version 0.4.2.
331
332 B<--comment> I<string>
333     Use I<string> as comment string in clear text signatures.
334
335 B<--set-filename> I<string>
336     Use I<string> as the name of file which is stored in
337     messages.
338
339 B<--completes-needed> I<n>
340     Number of completely trusted users to introduce a new
341     key signator (defaults to 1).
342
343 B<--marginals-needed> I<n>
344     Number of marginally trusted users to introduce a new
345     key signator (defaults to 3)
346
347 B<--max-cert-depth> I<n>
348     Maximum depth of a certification chain (default is 5).
349
350 B<--cipher-algo> I<name>
351     Use I<name> as cipher algorithm. Running the program
352     with the command B<--version> yields a list of supported
353     algorithms. If this is not used the cipher algorithm is
354     selected from the preferences stored with the key.
355
356 B<--digest-algo> I<name>
357     Use I<name> as message digest algorithm. Running the
358     program with the command B<--version> yields a list of
359     supported algorithms.  Please note that using this
360     option may violate the OpenPGP requirement, that a
361     160 bit hash is to be used for DSA.
362
363 B<--s2k-cipher-algo> I<name>
364     Use I<name> as the cipher algorithm used to protect secret
365     keys.  The default cipher is BLOWFISH.  This cipher is
366     also used for conventional encryption if B<--cipher-algo>
367     is not given.
368
369 B<--s2k-digest-algo> I<name>
370     Use I<name> as the digest algorithm used to mangle the
371     passphrases.  The default algorithm is RIPE-MD-160.
372     This digest algorithm is also used for conventional
373     encryption if B<--digest-algo> is not given.
374
375 B<--s2k-mode> I<number>
376     Selects how passphrases are mangled: A number of I<0>
377     uses the plain passphrase (which is not recommended),
378     a I<1> (default) adds a salt to the passphrase and
379     I<3> interates the whole process a couple of times.
380     Unless -B<--rfc1991> is used, this mode is also used
381     for conventional encryption.
382
383 B<--compress-algo> I<number>
384     Use compress algorithm I<number>. Default is I<2> which is
385     RFC1950 compression; you may use I<1> to use the old zlib
386     version which is used by PGP. This is only used for
387     new messages. The default algorithm may give better
388     results because the window size is not limited to 8K.
389     If this is not used the OpenPGP behaviour is used; i.e.
390     the compression algorith is selected from the preferences.
391
392 B<--digest-algo> I<name>
393     Use I<name> as message digest algorithm. Running the
394     program with the command B<--version> yields a list of
395     supported algorithms.
396
397
398 B<--throw-keyid>
399     Do not put the keyid into encrypted packets.  This option
400     hides the receiver of the message and is a countermeasure
401     against traffic analysis.  It may slow down the decryption
402     process because all available secret keys are tried.
403
404 B<--passphrase-fd> I<n>
405     Read the passphrase from file descriptor I<n>. If you use
406     0 for I<n>, the passphrase will be read from stdin.  This
407     can only be used if only one passphrase is supplied.
408     B<Don't use this option if you can avoid it>
409
410 B<--rfc1991>
411     Try to be more RFC1991 (PGP 2.x) compliant.
412
413 B<--force-v3-sigs>
414     OpenPGP states that a implemenation should generate
415     v4 signatures but PGP 5.x does only recognize such
416     signatures on key material.  This options forces
417     v3 signatures for signatures on data.
418
419 B<--no-verbose>
420     Reset verbose level to 0.
421
422 B<--no-greeting>
423     Suppress the initial copyright message but do not
424     enter batch mode.
425
426 B<--no-armor>
427     Assume the input data is not in ASCCI armored format.
428
429 B<--no-default-keyring>
430     Do not add the default keyrings to the list of
431     keyrings.
432
433 B<--skip-verify>
434     Skip the signature verification step.  This may be
435     used to make the encryption faster if the signature
436     verification is not needed.
437
438 B<--version>
439     Print version information along with a list
440     of supported algorithms.
441
442 B<--with-colons>
443     Print key listings delimited by colons.
444
445 B<--warranty>
446     Print warranty information.
447
448 B<-h>, B<--help>
449     Print usage information.
450
451
452 =head1 RETURN VALUE
453
454 The Program returns 0 if everything was fine, 1 if at least
455 a signature was bad and other errorcode for fatal errors.
456
457 =head1 EXAMPLES
458
459   -se -r Bob [file]          sign and encrypt for user Bob
460   -sat [file]                make a clear text signature
461   -sb  [file]                make a detached signature
462   -k   [userid]              show keys
463   -kc  [userid]              show fingerprint
464
465 =head1 ENVIRONMENT
466
467 C<HOME>       Used to locate the default home directory.
468 C<GNUPGHOME>  If set, direcory used instead of F<~/.gnupg>.
469
470 =head1 FILES
471
472 F<~/.gnupg/secring.gpg>     The secret keyring
473
474 F<~/.gnupg/pubring.gpg>     The public keyring
475
476 F<~/.gnupg/trustdb.gpg>     The trust database
477
478 F<~/.gnupg/options>         May contain options
479
480 F</usr[/local]/lib/gnupg/>  Default location for extensions
481
482 =head1 SEE ALSO
483
484 gpg(1)  gpgm(1)
485
486
487 =head1 WARNINGS
488
489 Use a B<good> password for your user account and a B<good> passphrase
490 to protect your secret key.  This passphrase is the weakest part of the
491 whole system.  Programs to do dictionary attacks on your secret keyring
492 are very easy to write and so you should protect your B<~/.gnupg/>
493 directory very good.
494
495 Keep in mind that, if this program is used over a network (telnet), it
496 is B<very> easy to spy out your passphrase!
497
498 =head1 BUGS
499
500 On many systems this program should be installed as setuid(root); this
501 is necessary to lock some pages of memory. If you get no warning message
502 about insecure memory your OS kernel supports locking without being root;
503 setuid is dropped as soon as this memory is allocated.
504