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