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