See ChangeLog: Tue Jan 12 11:17:18 CET 1999 Werner Koch
[gnupg.git] / doc / gpg.1pod
1 =head1 NAME
2
3 gpg, gpgm - 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<gpg> 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 additional 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 B<--export-all> [I<names>]
188     Same as B<--export> but does also export keys which
189     are not compatible to OpenPGP.
190
191 B<--export-secret-keys> [I<names>]
192     Same as B<--export>, but does export the secret keys.
193     This is normally not very useful.
194
195 B<--import>, B<--fast-import>
196     Import/merge keys.  The fast version does not build
197     the trustdb; this can be deon at anytime with the
198     command B<--update-trustdb>.
199
200 B<--export-ownertrust>
201     List the assigned ownertrust values in ascii format
202     for backup purposes [B<gpgm> only].
203
204 B<--import-ownertrust> [I<filename>]
205     Update the trustdb with the ownertrust values stored
206     in I<filename> (or stdin if not given); existing
207     values will be overwritten. [B<gpgm> only].
208
209 =head1 OPTIONS
210
211 Long options can be put in an options file (default F<~/.gnupg/options>);
212 do not write the 2 dashes, but simply the name of the option and any
213 arguments if required.  Lines with a hash as the first non-white-space
214 character are ignored. Commands may be put in this file too, but that
215 does not make sense.
216
217 B<gpg> recognizes these options:
218
219
220 B<-a>, B<--armor>
221     Create ASCII armored output.
222
223 B<-o> I<file>, B<--output> I<file>
224     Write output to I<file>.
225
226 B<-u> I<name>, B<--local-user> I<name>
227     Use I<name> as the user-id to sign.
228     This option is silently ignored for the list commands,
229     so that it can be used in an options file.
230
231 B<--default-key>  I<name>
232     Use I<name> as default user-id for signatures.  If this
233     is not used the default user-id is the first user-id
234     from the secret keyring.
235
236 B<--trusted-key>  I<keyid>
237     Assume that the key with the I<keyid> (which must be
238     a full (8 byte) keyid) is as trustworthy as one of
239     your own secret keys.  This may be used to make keys
240     valid which are not directly certified by you but
241     by a CA you trust.  The advantage of this option is
242     that it shortens the path of certification.
243
244     You may also use this option to skip the verification
245     of your own secret keys which is normally done every
246     time GnuPG starts up:  Use for I<keyid> the one of
247     your key.
248
249 B<-r>  I<name>, B<--remote-user>  I<name>
250     Use I<name> as the user-id for encryption.
251     This option is silently ignored for the list commands,
252     so that it can be used in an options file.
253
254 B<-v>, B<--verbose>
255     Give more information during processing. If used
256     twice, the input data is listed in detail.
257
258 B<-q>, B<--quiet>
259     Be somewhat more quiet in some cases.
260
261 B<-z> I<n>
262     Set compress level to I<n>. A value of 0 for I<n>
263     disables compression. Default is to use the default
264     compression level of zlib (which is 6).
265
266 B<-t>, B<--textmode>
267     Use canonical text mode.  If B<-t> (but not
268     B<--textmode>) is used together with armoring
269     and signing, this enables clearsigned messages.
270     This kludge is needed for PGP compatibility;
271     normally you would use B<--sign> or B<--clearsign>
272     to selected the type os signatures.
273
274 B<-n>, B<--dry-run>
275     Don't make any changes (not yet implemented).
276
277 B<--batch>
278     Batch mode; never ask, do not allow interactive
279     commands.
280
281 B<--no-batch>
282     Disable batch mode; this may be used if B<batch>
283     is used in the options file.
284
285 B<--yes>
286     Assume "yes" on most questions.
287
288 B<--no>
289     Assume "no" on most questions.
290
291 B<--keyring> I<file>
292     Add I<file> to the list of keyrings.
293     If I<file> begins with a tilde and a slash, these
294     are replaced by the HOME directory. If the filename
295     does not contain a slash, it is assumed to be in the
296     home-directory (F<~/.gnupg> if B<--homedir>) is not used.
297     The filename may be prefixed with a scheme:
298       "gnupg-ring:" is the default one.
299       "gnupg-gdbm:" may be used for a GDBM ring.
300
301 B<--secret-keyring> I<file>
302     Same as B<--keyring> but for secret keyrings.
303
304
305 B<--homedir> I<dir>
306     Set the name of the home directory to I<dir>. If this
307     option is not used it defaults to F<~/.gnupg>. It does
308     not make sense to use this in a options file. This
309     also overrides the environment variable C<GNUPGHOME>.
310
311 B<--charset> I<name>
312     Set the name of the native character set.  This is used
313     to convert some strings to proper UTF-8 encoding.
314     Valid values for I<name> are:
315       B<iso-8859-1>  This is the default.
316       B<koi8-r>      The usual Russian set (rfc1489).
317
318 B<--options> I<file>
319     Read options from I<file> and do not try to read
320     them from the default options file in the homedir
321     (see B<--homedir>). This option is ignored when used
322     in an options file.
323
324 B<--no-options>
325     Shortcut for B<--options> I</dev/null>.  This option is
326     detected before an attempt to open an option file.
327
328 B<--load-extension> I<modulename>
329     Load an extension module. If I<modulename> does not
330     contain a slash it is searched in B</usr/local/lib/gnupg>
331     See the manual for more information about extensions.
332
333 B<--debug> I<flags>
334     Set debugging flags. All flags are or-ed and I<flags> may
335     be given in C syntax (e.g. 0x0042).
336
337 B<--debug-all>
338     Set all useful debugging flags.
339
340 B<--status-fd> I<n>
341     Write special status strings to the file descriptor I<n>.
342
343 B<--no-comment>
344     Do not write comment packets.  This option affects only
345     the generation of secret keys.  Output of option packets
346     is disabled since version 0.4.2.
347
348 B<--comment> I<string>
349     Use I<string> as comment string in clear text signatures.
350
351 B<--set-filename> I<string>
352     Use I<string> as the name of file which is stored in
353     messages.
354
355 B<--completes-needed> I<n>
356     Number of completely trusted users to introduce a new
357     key signator (defaults to 1).
358
359 B<--marginals-needed> I<n>
360     Number of marginally trusted users to introduce a new
361     key signator (defaults to 3)
362
363 B<--max-cert-depth> I<n>
364     Maximum depth of a certification chain (default is 5).
365
366 B<--cipher-algo> I<name>
367     Use I<name> as cipher algorithm. Running the program
368     with the command B<--version> yields a list of supported
369     algorithms. If this is not used the cipher algorithm is
370     selected from the preferences stored with the key.
371
372 B<--digest-algo> I<name>
373     Use I<name> as message digest algorithm. Running the
374     program with the command B<--version> yields a list of
375     supported algorithms.  Please note that using this
376     option may violate the OpenPGP requirement, that a
377     160 bit hash is to be used for DSA.
378
379 B<--s2k-cipher-algo> I<name>
380     Use I<name> as the cipher algorithm used to protect secret
381     keys.  The default cipher is BLOWFISH.  This cipher is
382     also used for conventional encryption if B<--cipher-algo>
383     is not given.
384
385 B<--s2k-digest-algo> I<name>
386     Use I<name> as the digest algorithm used to mangle the
387     passphrases.  The default algorithm is RIPE-MD-160.
388     This digest algorithm is also used for conventional
389     encryption if B<--digest-algo> is not given.
390
391 B<--s2k-mode> I<number>
392     Selects how passphrases are mangled: A number of I<0>
393     uses the plain passphrase (which is not recommended),
394     a I<1> (default) adds a salt to the passphrase and
395     I<3> iterates the whole process a couple of times.
396     Unless -B<--rfc1991> is used, this mode is also used
397     for conventional encryption.
398
399 B<--compress-algo> I<number>
400     Use compress algorithm I<number>. Default is I<2> which is
401     RFC1950 compression; you may use I<1> to use the old zlib
402     version which is used by PGP.
403     The default algorithm may give better
404     results because the window size is not limited to 8K.
405     If this is not used the OpenPGP behavior is used; i.e.
406     the compression algorithm is selected from the preferences.
407
408 B<--digest-algo> I<name>
409     Use I<name> as message digest algorithm. Running the
410     program with the command B<--version> yields a list of
411     supported algorithms.
412
413
414 B<--throw-keyid>
415     Do not put the keyid into encrypted packets.  This option
416     hides the receiver of the message and is a countermeasure
417     against traffic analysis.  It may slow down the decryption
418     process because all available secret keys are tried.
419
420 B<--not-dash-escaped>
421     This option changes the behavior of cleartext signature
422     so that they can be used for patch files. You should not
423     send such an armored file via email because all spaces
424     and line endings are hashed too.  You can not use this
425     option for data which has 5 dashes somewhere at the
426     beginning of a line - patch files don't have this.
427     A special armor header line tells GnuPG about this
428     cleartext signature framework.
429
430 B<--escape-from-lines>
431     Because some mailers change lines starting with "From "
432     to ">From " it is good to handle such lines in a special
433     way when creating cleartext signatures; all other PGP
434     versions do it this way too.  Because this would violate
435     rfc2440, this option is not enabled per default.
436
437 B<--passphrase-fd> I<n>
438     Read the passphrase from file descriptor I<n>. If you use
439     0 for I<n>, the passphrase will be read from stdin.  This
440     can only be used if only one passphrase is supplied.
441     B<Don't use this option if you can avoid it>
442
443 B<--rfc1991>
444     Try to be more RFC1991 (PGP 2.x) compliant.
445
446 B<--force-v3-sigs>
447     OpenPGP states that a implementation should generate
448     v4 signatures but PGP 5.x does only recognize such
449     signatures on key material.  This options forces
450     v3 signatures for signatures on data.
451
452 B<--lock-once>
453     Lock the file the first time a lock is requested
454     and do not release the lock until the process
455     terminates.
456
457 B<--no-verbose>
458     Reset verbose level to 0.
459
460 B<--no-greeting>
461     Suppress the initial copyright message but do not
462     enter batch mode.
463
464 B<--no-armor>
465     Assume the input data is not in ASCII armored format.
466
467 B<--no-default-keyring>
468     Do not add the default keyrings to the list of
469     keyrings.
470
471 B<--skip-verify>
472     Skip the signature verification step.  This may be
473     used to make the encryption faster if the signature
474     verification is not needed.
475
476 B<--version>
477     Print version information along with a list
478     of supported algorithms.
479
480 B<--with-colons>
481     Print key listings delimited by colons.
482
483 B<--warranty>
484     Print warranty information.
485
486 B<-h>, B<--help>
487     Print usage information.
488
489
490 =head1 RETURN VALUE
491
492 The Program returns 0 if everything was fine, 1 if at least
493 a signature was bad and other errorcode for fatal errors.
494
495 =head1 EXAMPLES
496
497   -se -r Bob [file]          sign and encrypt for user Bob
498   -sat [file]                make a clear text signature
499   -sb  [file]                make a detached signature
500   -k   [userid]              show keys
501   -kc  [userid]              show fingerprint
502
503 =head1 ENVIRONMENT
504
505 C<HOME>       Used to locate the default home directory.
506 C<GNUPGHOME>  If set directory used instead of F<~/.gnupg>.
507
508 =head1 FILES
509
510 F<~/.gnupg/secring.gpg>      The secret keyring
511 F<~/.gnupg/secring.gpg.lock> and the lock file
512
513 F<~/.gnupg/pubring.gpg>      The public keyring
514 F<~/.gnupg/pubring.gpg.lock> and the lock file
515
516 F<~/.gnupg/trustdb.gpg>      The trust database
517 F<~/.gnupg/trustdb.gpg.lock> and the lock file
518
519 F<~/.gnupg/options>         May contain options
520 F</usr[/local]/share/gnupg/options.skel> Skeleton file
521
522 F</usr[/local]/lib/gnupg/>  Default location for extensions
523
524 =head1 SEE ALSO
525
526 gpg(1)  gpgm(1)
527
528
529 =head1 WARNINGS
530
531 Use a B<good> password for your user account and a B<good> passphrase
532 to protect your secret key.  This passphrase is the weakest part of the
533 whole system.  Programs to do dictionary attacks on your secret keyring
534 are very easy to write and so you should protect your B<~/.gnupg/>
535 directory very good.
536
537 Keep in mind that, if this program is used over a network (telnet), it
538 is B<very> easy to spy out your passphrase!
539
540 =head1 BUGS
541
542 On many systems this program should be installed as setuid(root); this
543 is necessary to lock some pages of memory. If you get no warning message
544 about insecure memory your OS kernel supports locking without being root;
545 setuid is dropped as soon as this memory is allocated.
546