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