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