Re-enabled --passphrase-fd
[gnupg.git] / doc / gpg.texi
1 @c Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005
2 @c               2006 Free Software Foundation, Inc.
3 @c This is part of the GnuPG manual.
4 @c For copying conditions, see the file gnupg.texi.
5
6 @node Invoking GPG
7 @chapter Invoking GPG
8 @cindex GPG command options
9 @cindex command options
10 @cindex options, GPG command
11
12 @c Begin GnuPG 1.x specific stuff
13 @ifset gpgone
14 @macro gpgname
15 gpg
16 @end macro
17 @manpage gpg.1
18 @ifset manverb
19 .B gpg
20 \- OpenPGP encryption and signing tool
21 @end ifset
22
23 @mansect synopsis
24 @ifset manverb
25 .B  gpg
26 .RB [ \-\-homedir
27 .IR dir ]
28 .RB [ \-\-options
29 .IR file ]
30 .RI [ options ]  
31 .I command
32 .RI [ args ]
33 @end ifset
34 @end ifset
35 @c End GnuPG 1.x specific stuff
36
37 @c Begin GnuPG 2 specific stuff
38 @ifclear gpgone
39 @macro gpgname
40 gpg2
41 @end macro
42 @manpage gpg2.1
43 @ifset manverb
44 .B gpg2
45 \- OpenPGP encryption and signing tool
46 @end ifset
47
48 @mansect synopsis
49 @ifset manverb
50 .B  gpg2
51 .RB [ \-\-homedir
52 .IR dir ]
53 .RB [ \-\-options
54 .IR file ]
55 .RI [ options ]  
56 .I command
57 .RI [ args ]
58 @end ifset
59 @end ifclear
60 @c Begin GnuPG 2 specific stuff
61
62 @mansect description
63 @command{@gpgname} is the OpenPGP part of the GNU Privacy Guard (GnuPG). It
64 is a tool to provide digital encryption and signing services using the
65 OpenPGP standard. @command{@gpgname} features complete key management and
66 all bells and whistles you can expect from a decent OpenPGP
67 implementation.
68
69 @ifset gpgone
70 This is the standalone version of @command{gpg}.  For desktop use you
71 should consider using @command{gpg2}.
72 @end ifset
73
74 @ifclear gpgone
75 In contrast to the standalone version @command{gpg}, which is more
76 suited for server and embedded platforms, this version is installed
77 under the name @command{gpg2} and more targeted to the desktop as it
78 requires several other modules to be installed.  The standalone version
79 will be kept maintained and it is possible to install both versions on
80 the same system.  If you need to use different configuration files, you
81 should make use of something like @file{gpg.conf-2} instead of just
82 @file{gpg.conf}.
83 @end ifclear
84
85 @manpause
86 @ifclear gpgone
87 Documentation for the old standard @command{gpg} is available as a man
88 page and at @inforef{Top,GnuPG 1,gpg}.
89 @end ifclear
90
91 @xref{Option Index}, for an index to @command{@gpgname}'s commands and options.
92 @mancont
93
94 @menu
95 * GPG Commands::        List of all commands.
96 * GPG Options::         List of all options.
97 * GPG Configuration::   Configuration files.
98 * GPG Examples::        Some usage examples.
99
100 Developer information:
101 @c * Unattended Usage::      Using @command{gpg} from other programs.
102 @c * GPG Protocol::        The protocol the server mode uses.
103 @end menu
104
105
106
107 @c *******************************************
108 @c ***************            ****************
109 @c ***************  COMMANDS  ****************
110 @c ***************            ****************
111 @c *******************************************
112 @mansect commands
113 @node GPG Commands
114 @section Commands
115
116 Commands are not distinguished from options execpt for the fact that
117 only one command is allowed.
118
119 @command{@gpgname} may be run with no commands, in which case it will
120 perform a reasonable action depending on the type of file it is given
121 as input (an encrypted message is decrypted, a signature is verified,
122 a file containing keys is listed).
123
124 Please remember that option as well as command parsing stops as soon as
125 a non-option is encountered, you can explicitly stop parsing by
126 using the special option @option{--}.
127
128
129 @menu
130 * General GPG Commands::        Commands not specific to the functionality.
131 * Operational GPG Commands::    Commands to select the type of operation.
132 * OpenPGP Key Management::      How to manage your keys.
133 @end menu
134
135
136 @c *******************************************
137 @c **********  GENERAL COMMANDS  *************
138 @c *******************************************
139 @node General GPG Commands
140 @subsection Commands not specific to the function
141
142 @table @gnupgtabopt
143 @item --version
144 @opindex version
145 Print the program version and licensing information.  Note that you
146 cannot abbreviate this command.
147
148 @item --help
149 @itemx -h
150 @opindex help
151 Print a usage message summarizing the most useful command line options.
152 Not that you cannot abbreviate this command.
153
154 @item --warranty
155 @opindex warranty
156 Print warranty information.
157
158 @item --dump-options
159 @opindex dump-options
160 Print a list of all available options and commands.  Note that you cannot
161 abbreviate this command.
162 @end table
163
164
165 @c *******************************************
166 @c ********  OPERATIONAL COMMANDS  ***********
167 @c *******************************************
168 @node Operational GPG Commands
169 @subsection Commands to select the type of operation
170
171
172 @table @gnupgtabopt
173
174 @item --sign
175 @itemx -s
176 @opindex sign
177 Make a signature. This command may be combined with @option{--encrypt}
178 (for a signed and encrypted message), @option{--symmetric} (for a signed
179 and symmetrically encrypted message), or @option{--encrypt} and
180 @option{--symmetric} together (for a signed message that may be
181 decrypted via a secret key or a passphrase).
182
183 @item --clearsign
184 @opindex clearsign
185 Make a clear text signature. The content in a clear text signature is
186 readable without any special software. OpenPGP software is only
187 needed to verify the signature. Clear text signatures may modify
188 end-of-line whitespace for platform independence and are not intended
189 to be reversible.
190
191 @item --detach-sign
192 @itemx -b
193 @opindex detach-sign
194 Make a detached signature.
195
196 @item --encrypt
197 @itemx -e
198 @opindex encrypt
199 Encrypt data. This option may be combined with @option{--sign} (for a
200 signed and encrypted message), @option{--symmetric} (for a message that
201 may be decrypted via a secret key or a passphrase), or @option{--sign}
202 and @option{--symmetric} together (for a signed message that may be
203 decrypted via a secret key or a passphrase).
204
205 @item --symmetric
206 @itemx -c
207 @opindex symmetric
208 Encrypt with a symmetric cipher using a passphrase. The default
209 symmetric cipher used is CAST5, but may be chosen with the
210 @option{--cipher-algo} option. This option may be combined with
211 @option{--sign} (for a signed and symmetrically encrypted message),
212 @option{--encrypt} (for a message that may be decrypted via a secret key
213 or a passphrase), or @option{--sign} and @option{--encrypt} together
214 (for a signed message that may be decrypted via a secret key or a
215 passphrase).
216
217 @item --store
218 @opindex store
219 Store only (make a simple RFC1991 literal data packet).
220
221 @item --decrypt
222 @itemx -d
223 @opindex decrypt
224 Decrypt the file given on the command line (or @code{stdin} if no file
225 is specified) and write it to stdout (or the file specified with
226 @option{--output}). If the decrypted file is signed, the signature is also
227 verified. This command differs from the default operation, as it never
228 writes to the filename which is included in the file and it rejects
229 files which don't begin with an encrypted message.
230
231 @item --verify
232 @opindex verify
233 Assume that the first argument is a signed file or a detached signature
234 and verify it without generating any output. With no arguments, the
235 signature packet is read from stdin. If only a sigfile is given, it may
236 be a complete signature or a detached signature, in which case the
237 signed stuff is expected in a file without the ".sig" or ".asc"
238 extension.  With more than 1 argument, the first should be a detached
239 signature and the remaining files are the signed stuff. To read the
240 signed stuff from stdin, use @samp{-} as the second filename.  For
241 security reasons a detached signature cannot read the signed material
242 from stdin without denoting it in the above way.
243
244 @item --multifile
245 @opindex multifile
246 This modifies certain other commands to accept multiple files for
247 processing on the command line or read from stdin with each filename on
248 a separate line. This allows for many files to be processed at
249 once. @option{--multifile} may currently be used along with
250 @option{--verify}, @option{--encrypt}, and @option{--decrypt}. Note that
251 @option{--multifile --verify} may not be used with detached signatures.
252
253 @item --verify-files
254 @opindex verify-files
255 Identical to @option{--multifile --verify}.
256
257 @item --encrypt-files
258 @opindex encrypt-files
259 Identical to @option{--multifile --encrypt}.
260
261 @item --decrypt-files
262 @opindex decrypt-files
263 Identical to @option{--multifile --decrypt}.
264
265 @item --list-keys
266 @itemx -k
267 @itemx --list-public-keys
268 @opindex list-keys
269 List all keys from the public keyrings, or just the keys given on the
270 command line.
271 @ifset gpgone
272 @option{-k} is slightly different from @option{--list-keys} in that it
273 allows only for one argument and takes the second argument as the
274 keyring to search.  This is for command line compatibility with PGP 2
275 and has been removed in @command{gpg2}.
276 @end ifset
277
278 Avoid using the output of this command in scripts or other programs as
279 it is likely to change as GnuPG changes. See @option{--with-colons} for a
280 machine-parseable key listing command that is appropriate for use in
281 scripts and other programs.
282
283 @item --list-secret-keys
284 @itemx -K
285 @opindex list-secret-keys
286 List all keys from the secret keyrings, or just the ones given on the
287 command line. A @code{#} after the letters @code{sec} means that the
288 secret key is not usable (for example, if it was created via
289 @option{--export-secret-subkeys}).
290
291 @item --list-sigs
292 @opindex list-sigs
293 Same as @option{--list-keys}, but the signatures are listed too.
294
295 For each signature listed, there are several flags in between the "sig"
296 tag and keyid. These flags give additional information about each
297 signature. From left to right, they are the numbers 1-3 for certificate
298 check level (see @option{--ask-cert-level}), "L" for a local or
299 non-exportable signature (see @option{--lsign-key}), "R" for a
300 nonRevocable signature (see the @option{--edit-key} command "nrsign"),
301 "P" for a signature that contains a policy URL (see
302 @option{--cert-policy-url}), "N" for a signature that contains a
303 notation (see @option{--cert-notation}), "X" for an eXpired signature
304 (see @option{--ask-cert-expire}), and the numbers 1-9 or "T" for 10 and
305 above to indicate trust signature levels (see the @option{--edit-key}
306 command "tsign").
307
308 @item --check-sigs
309 @opindex check-sigs
310 Same as @option{--list-sigs}, but the signatures are verified.
311
312 @item --fingerprint
313 @opindex fingerprint
314 List all keys (or the specified ones) along with their
315 fingerprints. This is the same output as @option{--list-keys} but with
316 the additional output of a line with the fingerprint. May also be
317 combined with @option{--list-sigs} or @option{--check-sigs}.  If this
318 command is given twice, the fingerprints of all secondary keys are
319 listed too.
320
321 @item --list-packets
322 @opindex list-packets
323 List only the sequence of packets. This is mainly
324 useful for debugging.
325
326
327 @item --card-edit
328 @opindex card-edit
329 Present a menu to work with a smartcard. The subcommand "help" provides
330 an overview on available commands. For a detailed description, please
331 see the Card HOWTO at
332 http://www.gnupg.org/documentation/howtos.html#GnuPG-cardHOWTO .
333
334 @item --card-status
335 @opindex card-status
336 Show the content of the smart card.
337
338 @item --change-pin
339 @opindex change-pin
340 Present a menu to allow changing the PIN of a smartcard. This
341 functionality is also available as the subcommand "passwd" with the
342 @option{--card-edit} command.
343
344 @item --delete-key @code{name}
345 @opindex delete-key
346 Remove key from the public keyring. In batch mode either @option{--yes} is
347 required or the key must be specified by fingerprint. This is a
348 safeguard against accidental deletion of multiple keys.
349
350 @item --delete-secret-key @code{name}
351 @opindex delete-secret-key
352 Remove key from the secret and public keyring. In batch mode the key
353 must be specified by fingerprint.
354
355 @item --delete-secret-and-public-key @code{name}
356 @opindex delete-secret-and-public-key
357 Same as @option{--delete-key}, but if a secret key exists, it will be
358 removed first. In batch mode the key must be specified by fingerprint.
359
360 @item --export
361 @opindex export
362 Either export all keys from all keyrings (default keyrings and those
363 registered via option @option{--keyring}), or if at least one name is given,
364 those of the given name. The new keyring is written to stdout or to the
365 file given with option @option{--output}. Use together with
366 @option{--armor} to mail those keys.
367
368 @item --send-keys
369 @opindex send-keys
370 Same as @option{--export} but sends the keys to a keyserver.  Option
371 @option{--keyserver} must be used to give the name of this
372 keyserver. Don't send your complete keyring to a keyserver --- select
373 only those keys which are new or changed by you.
374
375 @item --export-secret-keys
376 @itemx --export-secret-subkeys
377 @opindex export-secret-keys
378 @opindex export-secret-subkeys
379 Same as @option{--export}, but exports the secret keys instead.  This is
380 normally not very useful and a security risk.  The second form of the
381 command has the special property to render the secret part of the
382 primary key useless; this is a GNU extension to OpenPGP and other
383 implementations can not be expected to successfully import such a key.
384 See the option @option{--simple-sk-checksum} if you want to import such
385 an exported key with an older OpenPGP implementation.
386
387 @item --import
388 @itemx --fast-import
389 @opindex import
390 Import/merge keys. This adds the given keys to the
391 keyring. The fast version is currently just a synonym.
392
393 There are a few other options which control how this command works.
394 Most notable here is the @option{--keyserver-options merge-only} option
395 which does not insert new keys but does only the merging of new
396 signatures, user-IDs and subkeys.
397
398 @item --recv-keys @code{key IDs}
399 @opindex recv-keys
400 Import the keys with the given key IDs from a keyserver. Option
401 @option{--keyserver} must be used to give the name of this keyserver.
402
403 @item --refresh-keys
404 @opindex refresh-keys
405 Request updates from a keyserver for keys that already exist on the
406 local keyring. This is useful for updating a key with the latest
407 signatures, user IDs, etc. Calling this with no arguments will refresh
408 the entire keyring. Option @option{--keyserver} must be used to give the
409 name of the keyserver for all keys that do not have preferred keyservers
410 set (see @option{--keyserver-options honor-keyserver-url}).
411
412 @item --search-keys @code{names}
413 @opindex search-keys
414 Search the keyserver for the given names. Multiple names given here will
415 be joined together to create the search string for the keyserver.
416 Option @option{--keyserver} must be used to give the name of this
417 keyserver.  Keyservers that support different search methods allow using
418 the syntax specified in "How to specify a user ID" below. Note that
419 different keyserver types support different search methods. Currently
420 only LDAP supports them all.
421
422 @item --fetch-keys @code{URIs}
423 @opindex fetch-keys
424 Retrieve keys located at the specified URIs. Note that different
425 installations of GnuPG may support different protocols (HTTP, FTP,
426 LDAP, etc.)
427
428 @item --update-trustdb
429 @opindex update-trustdb
430 Do trust database maintenance. This command iterates over all keys and
431 builds the Web of Trust. This is an interactive command because it may
432 have to ask for the "ownertrust" values for keys. The user has to give
433 an estimation of how far she trusts the owner of the displayed key to
434 correctly certify (sign) other keys. GnuPG only asks for the ownertrust
435 value if it has not yet been assigned to a key. Using the
436 @option{--edit-key} menu, the assigned value can be changed at any time.
437
438 @item --check-trustdb
439 @opindex check-trustdb
440 Do trust database maintenance without user interaction. From time to
441 time the trust database must be updated so that expired keys or
442 signatures and the resulting changes in the Web of Trust can be
443 tracked. Normally, GnuPG will calculate when this is required and do it
444 automatically unless @option{--no-auto-check-trustdb} is set. This
445 command can be used to force a trust database check at any time. The
446 processing is identical to that of @option{--update-trustdb} but it
447 skips keys with a not yet defined "ownertrust".
448
449 For use with cron jobs, this command can be used together with
450 @option{--batch} in which case the trust database check is done only if
451 a check is needed. To force a run even in batch mode add the option
452 @option{--yes}.
453
454 @item --export-ownertrust
455 @opindex export-ownertrust
456 Send the ownertrust values to stdout. This is useful for backup purposes
457 as these values are the only ones which can't be re-created from a
458 corrupted trust DB.
459
460 @item --import-ownertrust
461 @opindex import-ownertrust
462 Update the trustdb with the ownertrust values stored in @code{files} (or
463 stdin if not given); existing values will be overwritten.
464
465 @item --rebuild-keydb-caches
466 @opindex rebuild-keydb-caches
467 When updating from version 1.0.6 to 1.0.7 this command should be used
468 to create signature caches in the keyring. It might be handy in other
469 situations too.
470
471 @item --print-md @code{algo}
472 @itemx --print-mds
473 @opindex print-md
474 Print message digest of algorithm ALGO for all given files or stdin.
475 With the second form (or a deprecated "*" as algo) digests for all
476 available algorithms are printed.
477
478 @item --gen-random @code{0|1|2}
479 @opindex gen-random
480 Emit @var{count} random bytes of the given quality level. If count is
481 not given or zero, an endless sequence of random bytes will be emitted.
482 PLEASE, don't use this command unless you know what you are doing; it
483 may remove precious entropy from the system!
484
485 @item --gen-prime @code{mode}  @code{bits}
486 @opindex gen-prime
487 Use the source, Luke :-). The output format is still subject to change.
488
489
490 @item --enarmor
491 @item --dearmor
492 @opindex enarmor
493 @opindex --enarmor
494 Pack or unpack an arbitrary input into/from an OpenPGP ASCII armor.
495 This is a GnuPG extension to OpenPGP and in general not very useful.
496
497 @end table
498
499
500 @c *******************************************
501 @c *******  KEY MANGEMENT COMMANDS  **********
502 @c *******************************************
503 @node OpenPGP Key Management
504 @subsection How to manage your keys
505
506 This section explains the main commands for key management
507
508 @table @gnupgtabopt
509
510 @item --gen-key
511 @opindex gen-key
512 Generate a new key pair. This command is normally only used
513 interactively.
514
515 There is an experimental feature which allows you to create keys in
516 batch mode. See the file @file{doc/DETAILS} in the source distribution
517 on how to use this.
518
519 @item --gen-revoke @code{name}
520 @opindex gen-revoke
521 Generate a revocation certificate for the complete key. To revoke
522 a subkey or a signature, use the @option{--edit} command.
523
524 @item --desig-revoke @code{name}
525 @opindex desig-revoke
526 Generate a designated revocation certificate for a key. This allows a
527 user (with the permission of the keyholder) to revoke someone else's
528 key.
529
530
531 @item --edit-key
532 @opindex edit-key
533 Present a menu which enables you to do most of the key management
534 related tasks.  It expects the specification of a key on the command
535 line.
536
537 @c ******** Begin Edit-key Options **********
538 @table @asis
539
540 @item sign
541 @opindex keyedit:sign
542 Make a signature on key of user @code{name} If the key is not yet
543 signed by the default user (or the users given with -u), the program
544 displays the information of the key again, together with its
545 fingerprint and asks whether it should be signed. This question is
546 repeated for all users specified with
547 -u.
548
549 @item lsign
550 @opindex keyedit:lsign
551 Same as "sign" but the signature is marked as non-exportable and will
552 therefore never be used by others. This may be used to make keys
553 valid only in the local environment.
554
555 @item nrsign
556 @opindex keyedit:nrsign
557 Same as "sign" but the signature is marked as non-revocable and can
558 therefore never be revoked.
559
560 @item tsign
561 @opindex keyedit:tsign
562 Make a trust signature. This is a signature that combines the notions
563 of certification (like a regular signature), and trust (like the
564 "trust" command). It is generally only useful in distinct communities
565 or groups.
566 @end table
567
568 @c man:.RS
569 Note that "l" (for local / non-exportable), "nr" (for non-revocable,
570 and "t" (for trust) may be freely mixed and prefixed to "sign" to
571 create a signature of any type desired.
572 @c man:.RE
573
574 @table @asis
575
576 @item revsig
577 @opindex keyedit:revsig
578 Revoke a signature. For every signature which has been generated by
579 one of the secret keys, GnuPG asks whether a revocation certificate
580 should be generated.
581
582 @item trust
583 @opindex keyedit:trust
584 Change the owner trust value. This updates the
585 trust-db immediately and no save is required.
586
587 @item disable
588 @itemx enable
589 @opindex keyedit:disable
590 @opindex keyedit:enable
591 Disable or enable an entire key. A disabled key can not normally be
592 used for encryption.
593
594 @item adduid
595 @opindex keyedit:adduid
596 Create an alternate user id.
597
598 @item addphoto
599 @opindex keyedit:addphoto
600 Create a photographic user id. This will prompt for a JPEG file that
601 will be embedded into the user ID. Note that a very large JPEG will make
602 for a very large key. Also note that some programs will display your
603 JPEG unchanged (GnuPG), and some programs will scale it to fit in a
604 dialog box (PGP).
605
606 @item deluid
607 @opindex keyedit:deluid
608 Delete a user id.  Note that it is not possible to retract a user id,
609 once it has been send to the public (i.e. to a keyserver).  In that case
610 you better use @code{revuid}.
611
612 @item delsig
613 @opindex keyedit:delsig
614 Delete a signature. Note that it is not possible to retract a signature,
615 once it has been send to the public (i.e. to a keyserver).  In that case
616 you better use @code{revsig}.
617
618 @item revuid
619 @opindex keyedit:revuid
620 Revoke a user id.
621
622 @item addkey
623 @opindex keyedit:addkey
624 Add a subkey to this key.
625
626 @item addcardkey
627 @opindex keyedit:addcardkey
628 Generate a key on a card and add it to this key.
629
630 @item keytocard
631 @opindex keyedit:keytocard
632 Transfer the selected secret key (or the primary key if no key has been
633 selected) to a smartcard. The secret key in the keyring will be replaced
634 by a stub if the key could be stored successfully on the card and you
635 use the save command later. Only certain key types may be transferred to
636 the card. A sub menu allows you to select on what card to store the
637 key. Note that it is not possible to get that key back from the card -
638 if the card gets broken your secret key will be lost unless you have a
639 backup somewhere.
640
641 @item bkuptocard @code{file}
642 @opindex keyedit:bkuptocard
643 Restore the given file to a card. This command may be used to restore a
644 backup key (as generated during card initialization) to a new card. In
645 almost all cases this will be the encryption key. You should use this
646 command only with the corresponding public key and make sure that the
647 file given as argument is indeed the backup to restore. You should then
648 select 2 to restore as encryption key.  You will first be asked to enter
649 the passphrase of the backup key and then for the Admin PIN of the card.
650
651 @item delkey
652 @opindex keyedit:delkey
653 Remove a subkey (secondart key). Note that it is not possible to retract
654 a subkey, once it has been send to the public (i.e. to a keyserver).  In
655 that case you better use @code{revkey}.
656
657 @item addrevoker
658 @opindex keyedit:addrevoker
659 Add a designated revoker. This takes one optional argument:
660 "sensitive". If a designated revoker is marked as sensitive, it will not
661 be exported by default (see export-options).
662
663 @item revkey
664 @opindex keyedit:revkey
665 Revoke a subkey.
666
667 @item expire
668 @opindex keyedit:expire
669 Change the key expiration time. If a subkey is selected, the
670 expiration time of this subkey will be changed. With no selection,
671 the key expiration of the primary key is changed.
672
673 @item passwd
674 @opindex keyedit:passwd
675 Change the passphrase of the secret key.
676
677 @item primary
678 @opindex keyedit:primary
679 Flag the current user id as the primary one, removes the primary user
680 id flag from all other user ids and sets the timestamp of all affected
681 self-signatures one second ahead. Note that setting a photo user ID
682 as primary makes it primary over other photo user IDs, and setting a
683 regular user ID as primary makes it primary over other regular user
684 IDs.
685
686 @item uid @code{n}
687 @opindex keyedit:uid
688 Toggle selection of user id with index @code{n}.
689 Use 0 to deselect all.
690
691 @item key @code{n}
692 @opindex keyedit:key
693 Toggle selection of subkey with index @code{n}.
694 Use 0 to deselect all.
695
696 @item check
697 @opindex keyedit:check
698 Check all selected user ids.
699
700 @item showphoto
701 @opindex keyedit:showphoto
702 Display the selected photographic user
703 id.
704
705 @item pref
706 @opindex keyedit:pref
707 List preferences from the selected user ID. This shows the actual
708 preferences, without including any implied preferences.
709
710 @item showpref
711 @opindex keyedit:showpref
712 More verbose preferences listing for the selected user ID. This shows
713 the preferences in effect by including the implied preferences of 3DES
714 (cipher), SHA-1 (digest), and Uncompressed (compression) if they are
715 not already included in the preference list. In addition, the
716 preferred keyserver and signature notations (if any) are shown.
717
718 @item setpref @code{string}
719 @opindex keyedit:setpref
720 Set the list of user ID preferences to @code{string} for all (or just
721 the selected) user IDs. Calling setpref with no arguments sets the
722 preference list to the default (either built-in or set via
723 @option{--default-preference-list}), and calling setpref with "none" as
724 the argument sets an empty preference list. Use @command{@gpgname
725 --version} to get a list of available algorithms. Note that while you
726 can change the preferences on an attribute user ID (aka "photo ID"),
727 GnuPG does not select keys via attribute user IDs so these preferences
728 will not be used by GnuPG.
729
730 @item keyserver
731 @opindex keyedit:keyserver
732 Set a preferred keyserver for the specified user ID(s). This allows
733 other users to know where you prefer they get your key from. See
734 @option{--keyserver-options honor-keyserver-url} for more on how this
735 works.  Setting a value of "none" removes an existing preferred
736 keyserver.
737
738 @item notation
739 @opindex keyedit:notation
740 Set a name=value notation for the specified user ID(s). See
741 @option{--cert-notation} for more on how this works. Setting a value of
742 "none" removes all notations, setting a notation prefixed with a minus
743 sign (-) removes that notation, and setting a notation name (without the
744 =value) prefixed with a minus sign removes all notations with that name.
745
746 @item toggle
747 @opindex keyedit:toggle
748 Toggle between public and secret key listing.
749
750 @item clean
751 @opindex keyedit:clean
752 Compact (by removing all signatures except the selfsig) any user ID
753 that is no longer usable (e.g. revoked, or expired). Then, remove any
754 signatures that are not usable by the trust calculations.
755 Specifically, this removes any signature that does not validate, any
756 signature that is superseded by a later signature, revoked signatures,
757 and signatures issued by keys that are not present on the keyring.
758
759 @item minimize
760 @opindex keyedit:minimize
761 Make the key as small as possible. This removes all signatures from
762 each user ID except for the most recent self-signature.
763
764 @item cross-certify
765 @opindex keyedit:cross-certify
766 Add cross-certification signatures to signing subkeys that may not
767 currently have them. Cross-certification signatures protect against a
768 subtle attack against signing subkeys. See
769 @option{--require-cross-certification}.
770
771 @item save
772 @opindex keyedit:save
773 Save all changes to the key rings and quit.
774
775 @item quit
776 @opindex keyedit:quit
777 Quit the program without updating the
778 key rings.
779
780 @end table
781
782 @c man:.RS
783 The listing shows you the key with its secondary keys and all user
784 ids. Selected keys or user ids are indicated by an asterisk. The trust
785 value is displayed with the primary key: the first is the assigned owner
786 trust and the second is the calculated trust value. Letters are used for
787 the values:
788 @c man:.RE
789
790 @table @asis
791
792 @item -
793 No ownertrust assigned / not yet calculated.
794
795 @item e
796 Trust
797 calculation has failed; probably due to an expired key.
798
799 @item q
800 Not enough information for calculation.
801
802 @item n
803 Never trust this key.
804
805 @item m
806 Marginally trusted.
807
808 @item f
809 Fully trusted.
810
811 @item u
812 Ultimately trusted.
813 @end table
814 @c ******** End Edit-key Options **********
815
816 @item --sign-key @code{name}
817 @opindex sign-key
818 Signs a public key with your secret key. This is a shortcut version of
819 the subcommand "sign" from @option{--edit}.
820
821 @item --lsign-key @code{name}
822 @opindex lsign-key
823 Signs a public key with your secret key but marks it as
824 non-exportable. This is a shortcut version of the subcommand "lsign"
825 from @option{--edit-key}.
826
827
828 @end table
829
830
831 @c *******************************************
832 @c ***************            ****************
833 @c ***************  OPTIONS   ****************
834 @c ***************            ****************
835 @c *******************************************
836 @mansect options
837 @node GPG Options
838 @section Option Summary
839
840 @command{@gpgname} comes features a bunch of options to control the exact
841 behaviour and to change the default configuration.
842
843 @menu
844 * GPG Configuration Options::   How to change the configuration.
845 * GPG Key related Options::     Key related options.
846 * GPG Input and Output::        Input and Output.
847 * OpenPGP Options::             OpenPGP protocol specific options.
848 * GPG Esoteric Options::        Doing things one usually don't want to do.
849 @end menu
850
851 Long options can be put in an options file (default
852 "~/.gnupg/gpg.conf"). Short option names will not work - for example,
853 "armor" is a valid option for the options file, while "a" is not. Do not
854 write the 2 dashes, but simply the name of the option and any required
855 arguments. Lines with a hash ('#') as the first non-white-space
856 character are ignored. Commands may be put in this file too, but that is
857 not generally useful as the command will execute automatically with
858 every execution of gpg.
859
860 Please remember that option parsing stops as soon as a non-option is
861 encountered, you can explicitly stop parsing by using the special option
862 @option{--}.
863
864 @c *******************************************
865 @c ********  CONFIGURATION OPTIONS  **********
866 @c *******************************************
867 @node GPG Configuration Options
868 @subsection How to change the configuration
869
870 These options are used to change the configuraton and are usually found
871 in the option file.
872
873 @table @gnupgtabopt
874
875 @item --default-key @var{name}
876 @opindex default-key
877 Use @var{name} as the default key to sign with. If this option is not
878 used, the default key is the first key found in the secret keyring.
879 Note that @option{-u} or @option{--local-user} overrides this option.
880
881 @item --default-recipient @var{name}
882 @opindex default-recipient
883 Use @var{name} as default recipient if option @option{--recipient} is
884 not used and don't ask if this is a valid one. @var{name} must be
885 non-empty.
886
887 @item --default-recipient-self
888 @opindex default-recipient-self
889 Use the default key as default recipient if option @option{--recipient} is not
890 used and don't ask if this is a valid one. The default key is the first
891 one from the secret keyring or the one set with @option{--default-key}.
892
893 @item --no-default-recipient
894 @opindex no-default-recipient
895 Reset @option{--default-recipient} and @option{--default-recipient-self}.
896
897 @item -v, --verbose
898 @opindex verbose
899 Give more information during processing. If used
900 twice, the input data is listed in detail.
901
902 @item --no-verbose
903 @opindex no-verbose
904 Reset verbose level to 0.
905
906 @item -q, --quiet
907 @opindex quiet
908 Try to be as quiet as possible.
909
910 @item --list-options @code{parameters}
911 @opindex list-options
912 This is a space or comma delimited string that gives options used when
913 listing keys and signatures (that is, @option{--list-keys},
914 @option{--list-sigs}, @option{--list-public-keys},
915 @option{--list-secret-keys}, and the @option{--edit-key} functions).
916 Options can be prepended with a @option{no-} (after the two dashes) to
917 give the opposite meaning.  The options are:
918
919 @table @asis
920
921 @item show-photos
922 @opindex list-options:show-photos
923 Causes @option{--list-keys}, @option{--list-sigs},
924 @option{--list-public-keys}, and @option{--list-secret-keys} to display
925 any photo IDs attached to the key.  Defaults to no. See also
926 @option{--photo-viewer}.
927
928 @item show-policy-urls
929 @opindex list-options:show-policy-urls
930 Show policy URLs in the @option{--list-sigs} or @option{--check-sigs}
931 listings.  Defaults to no.
932
933 @item show-notations
934 @itemx show-std-notations
935 @itemx show-user-notations
936 @opindex list-options:show-notations
937 @opindex list-options:show-std-notations
938 @opindex list-options:show-user-notations
939 Show all, IETF standard, or user-defined signature notations in the
940 @option{--list-sigs} or @option{--check-sigs} listings. Defaults to no.
941
942 @item show-keyserver-urls
943
944 Show any preferred keyserver URL in the @option{--list-sigs} or
945 @option{--check-sigs} listings. Defaults to no.
946
947 @item show-uid-validity
948 Display the calculated validity of user IDs during key listings.
949 Defaults to no.
950
951 @item show-unusable-uids
952 Show revoked and expired user IDs in key listings. Defaults to no.
953
954 @item show-unusable-subkeys
955 Show revoked and expired subkeys in key listings. Defaults to no.
956
957 @item show-keyring
958 Display the keyring name at the head of key listings to show which
959 keyring a given key resides on. Defaults to no.
960
961 @item show-sig-expire
962 Show signature expiration dates (if any) during @option{--list-sigs} or
963 @option{--check-sigs} listings. Defaults to no.
964
965 @item show-sig-subpackets
966 Include signature subpackets in the key listing. This option can take an
967 optional argument list of the subpackets to list. If no argument is
968 passed, list all subpackets. Defaults to no. This option is only
969 meaningful when using @option{--with-colons} along with
970 @option{--list-sigs} or @option{--check-sigs}.
971 @end table
972
973 @item --verify-options @code{parameters}
974 This is a space or comma delimited string that gives options used when
975 verifying signatures. Options can be prepended with a `no-' to give
976 the opposite meaning. The options are:
977
978 @table @asis
979
980 @item show-photos
981 Display any photo IDs present on the key that issued the signature.
982 Defaults to no. See also @option{--photo-viewer}.
983
984 @item show-policy-urls
985 Show policy URLs in the signature being verified. Defaults to no.
986
987 @item show-notations
988 @itemx show-std-notations
989 @itemx show-user-notations
990 Show all, IETF standard, or user-defined signature notations in the
991 signature being verified. Defaults to IETF standard.
992
993 @item show-keyserver-urls
994 Show any preferred keyserver URL in the signature being verified.
995 Defaults to no.
996
997 @item show-uid-validity
998 Display the calculated validity of the user IDs on the key that issued
999 the signature. Defaults to no.
1000
1001 @item show-unusable-uids
1002 Show revoked and expired user IDs during signature verification.
1003 Defaults to no.
1004
1005 @item pka-lookups
1006 Enable PKA lookups to verify sender addresses. Note that PKA is based
1007 on DNS, and so enabling this option may disclose information on when
1008 and what signatures are verified or to whom data is encrypted. This
1009 is similar to the "web bug" described for the auto-key-retrieve
1010 feature.
1011
1012 @item pka-trust-increase
1013 Raise the trust in a signature to full if the signature passes PKA
1014 validation. This option is only meaningful if pka-lookups is set.
1015 @end table
1016
1017 @item --enable-dsa2
1018 @itemx --disable-dsa2
1019 Enables new-style DSA keys which (unlike the old style) may be larger
1020 than 1024 bit and use hashes other than SHA-1 and RIPEMD/160. Note
1021 that very few programs currently support these keys and signatures
1022 from them.
1023
1024 @item --photo-viewer @code{string}
1025 This is the command line that should be run to view a photo ID. "%i"
1026 will be expanded to a filename containing the photo. "%I" does the
1027 same, except the file will not be deleted once the viewer exits.
1028 Other flags are "%k" for the key ID, "%K" for the long key ID, "%f"
1029 for the key fingerprint, "%t" for the extension of the image type
1030 (e.g. "jpg"), "%T" for the MIME type of the image (e.g. "image/jpeg"),
1031 and "%%" for an actual percent sign. If neither %i or %I are present,
1032 then the photo will be supplied to the viewer on standard input.
1033
1034 The default viewer is "xloadimage -fork -quiet -title 'KeyID 0x%k'
1035 stdin". Note that if your image viewer program is not secure, then
1036 executing it from GnuPG does not make it secure.
1037
1038 @item --exec-path @code{string}
1039 Sets a list of directories to search for photo viewers and keyserver
1040 helpers. If not provided, keyserver helpers use the compiled-in
1041 default directory, and photo viewers use the $PATH environment
1042 variable.
1043 Note, that on W32 system this value is ignored when searching for
1044 keyserver helpers.
1045
1046 @item --keyring @code{file}
1047 Add @code{file} to the current list of keyrings. If @code{file} begins
1048 with a tilde and a slash, these are replaced by the $HOME directory. If
1049 the filename does not contain a slash, it is assumed to be in the GnuPG
1050 home directory ("~/.gnupg" if @option{--homedir} or $GNUPGHOME is not
1051 used).
1052
1053 Note that this adds a keyring to the current list. If the intent is to
1054 use the specified keyring alone, use @option{--keyring} along with
1055 @option{--no-default-keyring}.
1056
1057 @item --secret-keyring @code{file}
1058 Same as @option{--keyring} but for the secret keyrings.
1059
1060 @item --primary-keyring @code{file}
1061 Designate @code{file} as the primary public keyring. This means that
1062 newly imported keys (via @option{--import} or keyserver
1063 @option{--recv-from}) will go to this keyring.
1064
1065 @item --trustdb-name @code{file}
1066 Use @code{file} instead of the default trustdb. If @code{file} begins
1067 with a tilde and a slash, these are replaced by the $HOME directory. If
1068 the filename does not contain a slash, it is assumed to be in the GnuPG
1069 home directory (@file{~/.gnupg} if @option{--homedir} or $GNUPGHOME is
1070 not used).
1071
1072 @include opt-homedir.texi
1073
1074
1075 @item --pcsc-driver @code{file}
1076 Use @code{file} to access the smartcard reader. The current default is
1077 `libpcsclite.so.1' for GLIBC based systems,
1078 `/System/Library/Frameworks/PCSC.framework/PCSC' for MAC OS X,
1079 `winscard.dll' for Windows and `libpcsclite.so' for other systems.
1080
1081 @item --disable-ccid
1082 Disable the integrated support for CCID compliant readers. This
1083 allows to fall back to one of the other drivers even if the internal
1084 CCID driver can handle the reader. Note, that CCID support is only
1085 available if libusb was available at build time.
1086
1087 @item --reader-port @code{number_or_string}
1088 This option may be used to specify the port of the card terminal. A
1089 value of 0 refers to the first serial device; add 32768 to access USB
1090 devices. The default is 32768 (first USB device). PC/SC or CCID
1091 readers might need a string here; run the program in verbose mode to get
1092 a list of available readers. The default is then the first reader
1093 found.
1094
1095 @item --display-charset @code{name}
1096 Set the name of the native character set. This is used to convert
1097 some informational strings like user IDs to the proper UTF-8 encoding.
1098 Note that this has nothing to do with the character set of data to be
1099 encrypted or signed; GnuPG does not recode user supplied data. If
1100 this option is not used, the default character set is determined from
1101 the current locale. A verbosity level of 3 shows the chosen set.
1102 Valid values for @code{name} are:
1103
1104 @table @asis
1105
1106 @item iso-8859-1
1107 This is the Latin 1 set.
1108
1109 @item iso-8859-2
1110 The Latin 2 set.
1111
1112 @item iso-8859-15
1113 This is currently an alias for
1114 the Latin 1 set.
1115
1116 @item koi8-r
1117 The usual Russian set (rfc1489).
1118
1119 @item utf-8
1120 Bypass all translations and assume
1121 that the OS uses native UTF-8 encoding.
1122 @end table
1123
1124 @item --utf8-strings
1125 @itemx --no-utf8-strings
1126 Assume that command line arguments are given as UTF8 strings. The
1127 default (@option{--no-utf8-strings}) is to assume that arguments are
1128 encoded in the character set as specified by
1129 @option{--display-charset}. These options affect all following
1130 arguments. Both options may be used multiple times.
1131
1132 @item --options @code{file}
1133 Read options from @code{file} and do not try to read them from the
1134 default options file in the homedir (see @option{--homedir}). This
1135 option is ignored if used in an options file.
1136
1137 @item --no-options
1138 Shortcut for @option{--options /dev/null}. This option is detected
1139 before an attempt to open an option file.  Using this option will also
1140 prevent the creation of a @file{~/.gnupg} homedir.
1141
1142
1143
1144 @item -z @code{n}
1145 @itemx --compress-level @code{n}
1146 @itemx --bzip2-compress-level @code{n}
1147 Set compression level to @code{n} for the ZIP and ZLIB compression
1148 algorithms. The default is to use the default compression level of zlib
1149 (normally 6). @option{--bzip2-compress-level} sets the compression level
1150 for the BZIP2 compression algorithm (defaulting to 6 as well). This is a
1151 different option from @option{--compress-level} since BZIP2 uses a
1152 significant amount of memory for each additional compression level.
1153 @option{-z} sets both. A value of 0 for @code{n} disables compression.
1154
1155 @item --bzip2-decompress-lowmem
1156 Use a different decompression method for BZIP2 compressed files. This
1157 alternate method uses a bit more than half the memory, but also runs
1158 at half the speed. This is useful under extreme low memory
1159 circumstances when the file was originally compressed at a high
1160 @option{--bzip2-compress-level}.
1161
1162
1163 @item --mangle-dos-filenames
1164 @itemx --no-mangle-dos-filenames
1165 @opindex mangle-dos-filenames
1166 @opindex no-mangle-dos-filenames
1167 Older version of Windows cannot handle filenames with more than one
1168 dot. @option{--mangle-dos-filenames} causes GnuPG to replace (rather
1169 than add to) the extension of an output filename to avoid this
1170 problem. This option is off by default and has no effect on non-Windows
1171 platforms.
1172
1173 @item --ask-cert-level
1174 @itemx --no-ask-cert-level
1175 When making a key signature, prompt for a certification level. If this
1176 option is not specified, the certification level used is set via
1177 @option{--default-cert-level}. See @option{--default-cert-level} for
1178 information on the specific levels and how they are
1179 used. @option{--no-ask-cert-level} disables this option. This option
1180 defaults to no.
1181
1182 @item --default-cert-level @code{n}
1183 The default to use for the check level when signing a key.
1184
1185 0 means you make no particular claim as to how carefully you verified
1186 the key.
1187
1188 1 means you believe the key is owned by the person who claims to own
1189 it but you could not, or did not verify the key at all. This is
1190 useful for a "persona" verification, where you sign the key of a
1191 pseudonymous user.
1192
1193 2 means you did casual verification of the key. For example, this
1194 could mean that you verified that the key fingerprint and checked the
1195 user ID on the key against a photo ID.
1196
1197 3 means you did extensive verification of the key. For example, this
1198 could mean that you verified the key fingerprint with the owner of the
1199 key in person, and that you checked, by means of a hard to forge
1200 document with a photo ID (such as a passport) that the name of the key
1201 owner matches the name in the user ID on the key, and finally that you
1202 verified (by exchange of email) that the email address on the key
1203 belongs to the key owner.
1204
1205 Note that the examples given above for levels 2 and 3 are just that:
1206 examples. In the end, it is up to you to decide just what "casual"
1207 and "extensive" mean to you.
1208
1209 This option defaults to 0 (no particular claim).
1210
1211 @item --min-cert-level
1212 When building the trust database, treat any signatures with a
1213 certification level below this as invalid. Defaults to 2, which
1214 disregards level 1 signatures. Note that level 0 "no particular
1215 claim" signatures are always accepted.
1216
1217 @item --trusted-key @code{long key ID}
1218 Assume that the specified key (which must be given
1219 as a full 8 byte key ID) is as trustworthy as one of
1220 your own secret keys. This option is useful if you
1221 don't want to keep your secret keys (or one of them)
1222 online but still want to be able to check the validity of a given
1223 recipient's or signator's key.
1224
1225 @item --trust-model @code{pgp|classic|direct|always|auto}
1226 Set what trust model GnuPG should follow. The models are:
1227
1228 @table @asis
1229
1230 @item pgp
1231 This is the Web of Trust combined with trust signatures as used in PGP
1232 5.x and later. This is the default trust model when creating a new
1233 trust database.
1234
1235 @item classic
1236 This is the standard Web of Trust as used in PGP 2.x and earlier.
1237
1238 @item direct
1239 Key validity is set directly by the user and not calculated via the
1240 Web of Trust.
1241
1242 @item always
1243 Skip key validation and assume that used keys are always fully
1244 trusted. You generally won't use this unless you are using some
1245 external validation scheme. This option also suppresses the
1246 "[uncertain]" tag printed with signature checks when there is no
1247 evidence that the user ID is bound to the key.
1248
1249 @item auto
1250 Select the trust model depending on whatever the internal trust
1251 database says. This is the default model if such a database already
1252 exists.
1253 @end table
1254
1255 @item --auto-key-locate @code{parameters}
1256 @itemx --no-auto-key-locate
1257 GnuPG can automatically locate and retrieve keys as needed using this
1258 option. This happens when encrypting to an email address (in the
1259 "user@@example.com" form), and there are no user@@example.com keys on
1260 the local keyring. This option takes any number of the following
1261 arguments, in the order they are to be tried:
1262
1263 @table @asis
1264
1265 @item cert
1266 locate a key using DNS CERT, as specified in 2538bis (currently in
1267 draft): http://www.josefsson.org/rfc2538bis/
1268
1269 @item pka
1270 locate a key using DNS PKA.
1271
1272 @item ldap
1273 locate a key using the PGP Universal method of checking
1274 "ldap://keys.(thedomain)".
1275
1276 @item keyserver
1277 locate a key using whatever keyserver is defined using the
1278 @option{--keyserver} option.
1279
1280 @item (keyserver URL)
1281 In addition, a keyserver URL as used in the @option{--keyserver} option may be
1282 used here to query that particular keyserver.
1283 @end table
1284
1285 @item --keyid-format @code{short|0xshort|long|0xlong}
1286 Select how to display key IDs. "short" is the traditional 8-character
1287 key ID. "long" is the more accurate (but less convenient)
1288 16-character key ID. Add an "0x" to either to include an "0x" at the
1289 beginning of the key ID, as in 0x99242560.
1290
1291 @item --keyserver @code{name}
1292 Use @code{name} as your keyserver. This is the server that
1293 @option{--recv-keys}, @option{--send-keys}, and @option{--search-keys}
1294 will communicate with to receive keys from, send keys to, and search for
1295 keys on. The format of the @code{name} is a URI:
1296 `scheme:[//]keyservername[:port]' The scheme is the type of keyserver:
1297 "hkp" for the HTTP (or compatible) keyservers, "ldap" for the LDAP
1298 keyservers, or "mailto" for the Graff email keyserver. Note that your
1299 particular installation of GnuPG may have other keyserver types
1300 available as well. Keyserver schemes are case-insensitive. After the
1301 keyserver name, optional keyserver configuration options may be
1302 provided. These are the same as the global @option{--keyserver-options}
1303 from below, but apply only to this particular keyserver.
1304
1305 Most keyservers synchronize with each other, so there is generally no
1306 need to send keys to more than one server. The keyserver
1307 @code{hkp://subkeys.pgp.net} uses round robin DNS to give a different
1308 keyserver each time you use it.
1309
1310 @item --keyserver-options @code{name=value1 }
1311 This is a space or comma delimited string that gives options for the
1312 keyserver. Options can be prepended with a `no-' to give the opposite
1313 meaning. Valid import-options or export-options may be used here as well
1314 to apply to importing (@option{--recv-key}) or exporting
1315 (@option{--send-key}) a key from a keyserver. While not all options are
1316 available for all keyserver types, some common options are:
1317
1318 @table @asis
1319
1320 @item include-revoked
1321 When searching for a key with @option{--search-keys}, include keys that
1322 are marked on the keyserver as revoked. Note that not all keyservers
1323 differentiate between revoked and unrevoked keys, and for such
1324 keyservers this option is meaningless. Note also that most keyservers do
1325 not have cryptographic verification of key revocations, and so turning
1326 this option off may result in skipping keys that are incorrectly marked
1327 as revoked.
1328
1329 @item include-disabled
1330 When searching for a key with @option{--search-keys}, include keys that
1331 are marked on the keyserver as disabled. Note that this option is not
1332 used with HKP keyservers.
1333
1334 @item auto-key-retrieve
1335 This option enables the automatic retrieving of keys from a keyserver
1336 when verifying signatures made by keys that are not on the local
1337 keyring.
1338
1339 Note that this option makes a "web bug" like behavior possible.
1340 Keyserver operators can see which keys you request, so by sending you
1341 a message signed by a brand new key (which you naturally will not have
1342 on your local keyring), the operator can tell both your IP address and
1343 the time when you verified the signature.
1344
1345 @item honor-keyserver-url
1346 When using @option{--refresh-keys}, if the key in question has a preferred
1347 keyserver URL, then use that preferred keyserver to refresh the key
1348 from. In addition, if auto-key-retrieve is set, and the signature
1349 being verified has a preferred keyserver URL, then use that preferred
1350 keyserver to fetch the key from. Defaults to yes.
1351
1352 @item honor-pka-record
1353 If auto-key-retrieve is set, and the signature being verified has a
1354 PKA record, then use the PKA information to fetch the key. Defaults
1355 to yes.
1356
1357 @item include-subkeys
1358 When receiving a key, include subkeys as potential targets. Note that
1359 this option is not used with HKP keyservers, as they do not support
1360 retrieving keys by subkey id.
1361
1362 @item use-temp-files
1363 On most Unix-like platforms, GnuPG communicates with the keyserver
1364 helper program via pipes, which is the most efficient method. This
1365 option forces GnuPG to use temporary files to communicate. On some
1366 platforms (such as Win32 and RISC OS), this option is always enabled.
1367
1368 @item keep-temp-files
1369 If using `use-temp-files', do not delete the temp files after using
1370 them. This option is useful to learn the keyserver communication
1371 protocol by reading the temporary files.
1372
1373 @item verbose
1374 Tell the keyserver helper program to be more verbose. This option can
1375 be repeated multiple times to increase the verbosity level.
1376
1377 @item timeout
1378 Tell the keyserver helper program how long (in seconds) to try and
1379 perform a keyserver action before giving up. Note that performing
1380 multiple actions at the same time uses this timeout value per action.
1381 For example, when retrieving multiple keys via @option{--recv-keys}, the
1382 timeout applies separately to each key retrieval, and not to the
1383 @option{--recv-keys} command as a whole. Defaults to 30 seconds.
1384
1385 @item http-proxy
1386 For HTTP-like keyserver schemes that (such as HKP and HTTP itself),
1387 try to access the keyserver over a proxy. If a @code{value} is
1388 specified, use this as the HTTP proxy. If no @code{value} is
1389 specified, the value of the environment variable "http_proxy", if any,
1390 will be used.
1391
1392 @item max-cert-size
1393 When retrieving a key via DNS CERT, only accept keys up to this size.
1394 Defaults to 16384 bytes.
1395 @end table
1396
1397 @item --completes-needed @code{n}
1398 Number of completely trusted users to introduce a new
1399 key signer (defaults to 1).
1400
1401 @item --marginals-needed @code{n}
1402 Number of marginally trusted users to introduce a new
1403 key signer (defaults to 3)
1404
1405 @item --max-cert-depth @code{n}
1406 Maximum depth of a certification chain (default is 5).
1407
1408 @item --simple-sk-checksum
1409 Secret keys are integrity protected by using a SHA-1 checksum. This
1410 method is part of the upcoming enhanced OpenPGP specification but
1411 GnuPG already uses it as a countermeasure against certain attacks.
1412 Old applications don't understand this new format, so this option may
1413 be used to switch back to the old behaviour. Using this option bears
1414 a security risk. Note that using this option only takes effect when
1415 the secret key is encrypted - the simplest way to make this happen is
1416 to change the passphrase on the key (even changing it to the same
1417 value is acceptable).
1418
1419 @item --no-sig-cache
1420 Do not cache the verification status of key signatures.
1421 Caching gives a much better performance in key listings. However, if
1422 you suspect that your public keyring is not save against write
1423 modifications, you can use this option to disable the caching. It
1424 probably does not make sense to disable it because all kind of damage
1425 can be done if someone else has write access to your public keyring.
1426
1427 @item --no-sig-create-check
1428 GnuPG normally verifies each signature right after creation to protect
1429 against bugs and hardware malfunctions which could leak out bits from
1430 the secret key. This extra verification needs some time (about 115%
1431 for DSA keys), and so this option can be used to disable it.
1432 However, due to the fact that the signature creation needs manual
1433 interaction, this performance penalty does not matter in most settings.
1434
1435 @item --auto-check-trustdb
1436 @itemx --no-auto-check-trustdb
1437 If GnuPG feels that its information about the Web of Trust has to be
1438 updated, it automatically runs the @option{--check-trustdb} command
1439 internally.  This may be a time consuming
1440 process. @option{--no-auto-check-trustdb} disables this option.
1441
1442 @item --use-agent
1443 @itemx --no-use-agent
1444 @ifclear gpgone
1445 This is dummy option. @command{@gpgname} always requires the agent.
1446 @end ifclear
1447 @ifset gpgone
1448 Try to use the GnuPG-Agent.  With this option, GnuPG first tries to
1449 connect to the agent before it asks for a
1450 passphrase. @option{--no-use-agent} disables this option.
1451 @end ifset
1452
1453 @item --gpg-agent-info
1454 Override the value of the environment variable
1455 @samp{GPG_AGENT_INFO}. This is only used when @option{--use-agent} has
1456 been given
1457
1458 @item --lock-once
1459 Lock the databases the first time a lock is requested
1460 and do not release the lock until the process
1461 terminates.
1462
1463 @item --lock-multiple
1464 Release the locks every time a lock is no longer
1465 needed. Use this to override a previous @option{--lock-once}
1466 from a config file.
1467
1468 @item --lock-never
1469 Disable locking entirely. This option should be used only in very
1470 special environments, where it can be assured that only one process
1471 is accessing those files. A bootable floppy with a stand-alone
1472 encryption system will probably use this. Improper usage of this
1473 option may lead to data and key corruption.
1474
1475 @item --exit-on-status-write-error
1476 This option will cause write errors on the status FD to immediately
1477 terminate the process. That should in fact be the default but it never
1478 worked this way and thus we need an option to enable this, so that the
1479 change won't break applications which close their end of a status fd
1480 connected pipe too early. Using this option along with
1481 @option{--enable-progress-filter} may be used to cleanly cancel long
1482 running gpg operations.
1483
1484 @item --limit-card-insert-tries @code{n}
1485 With @code{n} greater than 0 the number of prompts asking to insert a
1486 smartcard gets limited to N-1. Thus with a value of 1 gpg won't at
1487 all ask to insert a card if none has been inserted at startup. This
1488 option is useful in the configuration file in case an application does
1489 not know about the smartcard support and waits ad infinitum for an
1490 inserted card.
1491
1492 @item --no-random-seed-file
1493 GnuPG uses a file to store its internal random pool over invocations.
1494 This makes random generation faster; however sometimes write operations
1495 are not desired. This option can be used to achieve that with the cost of
1496 slower random generation.
1497
1498 @item --no-greeting
1499 Suppress the initial copyright message.
1500
1501 @item --no-secmem-warning
1502 Suppress the warning about "using insecure memory".
1503
1504 @item --no-permission-warning
1505 Suppress the warning about unsafe file and home directory (@option{--homedir})
1506 permissions. Note that the permission checks that GnuPG performs are
1507 not intended to be authoritative, but rather they simply warn about
1508 certain common permission problems. Do not assume that the lack of a
1509 warning means that your system is secure.
1510
1511 Note that the warning for unsafe @option{--homedir} permissions cannot be
1512 suppressed in the gpg.conf file, as this would allow an attacker to
1513 place an unsafe gpg.conf file in place, and use this file to suppress
1514 warnings about itself. The @option{--homedir} permissions warning may only be
1515 suppressed on the command line.
1516
1517 @item --no-mdc-warning
1518 Suppress the warning about missing MDC integrity protection.
1519
1520 @item --require-secmem
1521 @itemx --no-require-secmem
1522 Refuse to run if GnuPG cannot get secure memory. Defaults to no
1523 (i.e. run, but give a warning).
1524
1525
1526 @item --require-cross-certification
1527 @itemx --no-require-cross-certification
1528 When verifying a signature made from a subkey, ensure that the cross
1529 certification "back signature" on the subkey is present and valid.  This
1530 protects against a subtle attack against subkeys that can sign.
1531 Defaults to @option{--require-cross-certification} for
1532 @command{@gpgname}.
1533
1534 @item --expert
1535 @itemx --no-expert
1536 Allow the user to do certain nonsensical or "silly" things like
1537 signing an expired or revoked key, or certain potentially incompatible
1538 things like generating unusual key types. This also disables certain
1539 warning messages about potentially incompatible actions. As the name
1540 implies, this option is for experts only. If you don't fully
1541 understand the implications of what it allows you to do, leave this
1542 off. @option{--no-expert} disables this option.
1543
1544
1545
1546
1547 @end table
1548
1549
1550 @c *******************************************
1551 @c ********  KEY RELATED OPTIONS  ************
1552 @c *******************************************
1553 @node GPG Key related Options
1554 @subsection Key related options
1555
1556 @table @gnupgtabopt
1557
1558 @item --recipient @var{name}
1559 @itemx -r
1560 @opindex recipient
1561 Encrypt for user id @var{name}. If this option or
1562 @option{--hidden-recipient} is not specified, GnuPG asks for the user-id
1563 unless @option{--default-recipient} is given.
1564
1565 @item --hidden-recipient @var{name}
1566 @itemx -R
1567 @opindex hidden-recipient
1568 Encrypt for user ID @var{name}, but hide the key ID of this user's
1569 key. This option helps to hide the receiver of the message and is a
1570 limited countermeasure against traffic analysis. If this option or
1571 @option{--recipient} is not specified, GnuPG asks for the user ID unless
1572 @option{--default-recipient} is given.
1573
1574 @item --encrypt-to @code{name}
1575 Same as @option{--recipient} but this one is intended for use in the
1576 options file and may be used with your own user-id as an
1577 "encrypt-to-self". These keys are only used when there are other
1578 recipients given either by use of @option{--recipient} or by the asked
1579 user id.  No trust checking is performed for these user ids and even
1580 disabled keys can be used.
1581
1582 @item --hidden-encrypt-to @code{name}
1583 Same as @option{--hidden-recipient} but this one is intended for use in the
1584 options file and may be used with your own user-id as a hidden
1585 "encrypt-to-self". These keys are only used when there are other
1586 recipients given either by use of @option{--recipient} or by the asked user id.
1587 No trust checking is performed for these user ids and even disabled
1588 keys can be used.
1589
1590 @item --no-encrypt-to
1591 Disable the use of all @option{--encrypt-to} and
1592 @option{--hidden-encrypt-to} keys.
1593
1594 @item --group @code{name=value1 }
1595 Sets up a named group, which is similar to aliases in email programs.
1596 Any time the group name is a recipient (@option{-r} or
1597 @option{--recipient}), it will be expanded to the values
1598 specified. Multiple groups with the same name are automatically merged
1599 into a single group.
1600
1601 The values are @code{key IDs} or fingerprints, but any key description
1602 is accepted. Note that a value with spaces in it will be treated as
1603 two different values. Note also there is only one level of expansion
1604 --- you cannot make an group that points to another group. When used
1605 from the command line, it may be necessary to quote the argument to
1606 this option to prevent the shell from treating it as multiple
1607 arguments.
1608
1609 @item --ungroup @code{name}
1610 Remove a given entry from the @option{--group} list.
1611
1612 @item --no-groups
1613 Remove all entries from the @option{--group} list.
1614
1615 @item --local-user @var{name}
1616 @itemx -u
1617 @opindex local-user
1618 Use @var{name} as the key to sign with. Note that this option overrides
1619 @option{--default-key}.
1620
1621 @item --try-all-secrets
1622 Don't look at the key ID as stored in the message but try all secret
1623 keys in turn to find the right decryption key. This option forces the
1624 behaviour as used by anonymous recipients (created by using
1625 @option{--throw-keyids}) and might come handy in case where an encrypted
1626 message contains a bogus key ID.
1627
1628
1629
1630
1631
1632 @end table
1633
1634 @c *******************************************
1635 @c ********  INPUT AND OUTPUT  ***************
1636 @c *******************************************
1637 @node GPG Input and Output
1638 @subsection Input and Output
1639
1640 @table @gnupgtabopt
1641
1642 @item --armor
1643 @itemx -a
1644 @opindex armor
1645 Create ASCII armored output.  The default is to create the binary
1646 OpenPGP format.
1647
1648 @item --no-armor
1649 Assume the input data is not in ASCII armored format.
1650
1651 @item --output @var{file}
1652 @itemx -o @var{file}
1653 @opindex output
1654 Write output to @var{file}.
1655
1656 @item --max-output @code{n}
1657 @opindex max-output
1658 This option sets a limit on the number of bytes that will be generated
1659 when processing a file. Since OpenPGP supports various levels of
1660 compression, it is possible that the plaintext of a given message may be
1661 significantly larger than the original OpenPGP message. While GnuPG
1662 works properly with such messages, there is often a desire to set a
1663 maximum file size that will be generated before processing is forced to
1664 stop by the OS limits. Defaults to 0, which means "no limit".
1665
1666 @item --import-options @code{parameters}
1667 This is a space or comma delimited string that gives options for
1668 importing keys. Options can be prepended with a `no-' to give the
1669 opposite meaning. The options are:
1670
1671 @table @asis
1672
1673 @item import-local-sigs
1674 Allow importing key signatures marked as "local". This is not
1675 generally useful unless a shared keyring scheme is being used.
1676 Defaults to no.
1677
1678 @item repair-pks-subkey-bug
1679 During import, attempt to repair the damage caused by the PKS keyserver
1680 bug (pre version 0.9.6) that mangles keys with multiple subkeys. Note
1681 that this cannot completely repair the damaged key as some crucial data
1682 is removed by the keyserver, but it does at least give you back one
1683 subkey. Defaults to no for regular @option{--import} and to yes for
1684 keyserver @option{--recv-keys}.
1685
1686 @item merge-only
1687 During import, allow key updates to existing keys, but do not allow
1688 any new keys to be imported. Defaults to no.
1689
1690 @item import-clean
1691 After import, compact (remove all signatures except the
1692 self-signature) any user IDs from the new key that are not usable.
1693 Then, remove any signatures from the new key that are not usable.
1694 This includes signatures that were issued by keys that are not present
1695 on the keyring. This option is the same as running the @option{--edit-key}
1696 command "clean" after import. Defaults to no.
1697
1698 @item import-minimal
1699 Import the smallest key possible. This removes all signatures except
1700 the most recent self-signature on each user ID. This option is the
1701 same as running the @option{--edit-key} command "minimize" after import.
1702 Defaults to no.
1703 @end table
1704
1705 @item --export-options @code{parameters}
1706 This is a space or comma delimited string that gives options for
1707 exporting keys. Options can be prepended with a `no-' to give the
1708 opposite meaning. The options are:
1709
1710 @table @asis
1711
1712 @item export-local-sigs
1713 Allow exporting key signatures marked as "local". This is not
1714 generally useful unless a shared keyring scheme is being used.
1715 Defaults to no.
1716
1717 @item export-attributes
1718 Include attribute user IDs (photo IDs) while exporting. This is
1719 useful to export keys if they are going to be used by an OpenPGP
1720 program that does not accept attribute user IDs. Defaults to yes.
1721
1722 @item export-sensitive-revkeys
1723 Include designated revoker information that was marked as
1724 "sensitive". Defaults to no.
1725
1726 @item export-reset-subkey-passwd
1727 When using the @option{--export-secret-subkeys} command, this option resets
1728 the passphrases for all exported subkeys to empty. This is useful
1729 when the exported subkey is to be used on an unattended machine where
1730 a passphrase doesn't necessarily make sense. Defaults to no.
1731
1732 @item export-clean
1733 Compact (remove all signatures from) user IDs on the key being
1734 exported if the user IDs are not usable. Also, do not export any
1735 signatures that are not usable. This includes signatures that were
1736 issued by keys that are not present on the keyring. This option is
1737 the same as running the @option{--edit-key} command "clean" before export
1738 except that the local copy of the key is not modified. Defaults to
1739 no.
1740
1741 @item export-minimal
1742 Export the smallest key possible. This removes all signatures except the
1743 most recent self-signature on each user ID. This option is the same as
1744 running the @option{--edit-key} command "minimize" before export except
1745 that the local copy of the key is not modified. Defaults to no.
1746 @end table
1747
1748 @item --with-colons
1749 @opindex with-colons
1750 Print key listings delimited by colons. Note that the output will be
1751 encoded in UTF-8 regardless of any @option{--display-charset} setting. This
1752 format is useful when GnuPG is called from scripts and other programs
1753 as it is easily machine parsed. The details of this format are
1754 documented in the file @file{doc/DETAILS}, which is included in the GnuPG
1755 source distribution.
1756
1757 @item --fixed-list-mode
1758 @opindex fixed-list-mode
1759 Do not merge primary user ID and primary key in @option{--with-colon}
1760 listing mode and print all timestamps as seconds since 1970-01-01.
1761
1762 @item --with-fingerprint
1763 @opindex with-fingerprint
1764 Same as the command @option{--fingerprint} but changes only the format
1765 of the output and may be used together with another command.
1766
1767
1768 @end table
1769
1770 @c *******************************************
1771 @c ********  OPENPGP OPTIONS  ****************
1772 @c *******************************************
1773 @node OpenPGP Options
1774 @subsection OpenPGP protocol specific options.
1775
1776 @table @gnupgtabopt
1777
1778 @item -t, --textmode
1779 @itemx --no-textmode
1780 Treat input files as text and store them in the OpenPGP canonical text
1781 form with standard "CRLF" line endings. This also sets the necessary
1782 flags to inform the recipient that the encrypted or signed data is text
1783 and may need its line endings converted back to whatever the local
1784 system uses. This option is useful when communicating between two
1785 platforms that have different line ending conventions (UNIX-like to Mac,
1786 Mac to Windows, etc). @option{--no-textmode} disables this option, and
1787 is the default.
1788
1789 @ifset gpgone
1790 If @option{-t} (but not @option{--textmode}) is used together with
1791 armoring and signing, this enables clearsigned messages. This kludge is
1792 needed for command-line compatibility with command-line versions of PGP;
1793 normally you would use @option{--sign} or @option{--clearsign} to select
1794 the type of the signature.
1795 @end ifset
1796
1797
1798
1799 @item --force-v3-sigs
1800 @itemx --no-force-v3-sigs
1801 OpenPGP states that an implementation should generate v4 signatures
1802 but PGP versions 5 through 7 only recognize v4 signatures on key
1803 material. This option forces v3 signatures for signatures on data.
1804 Note that this option overrides @option{--ask-sig-expire}, as v3 signatures
1805 cannot have expiration dates. @option{--no-force-v3-sigs} disables this
1806 option.
1807
1808 @item --force-v4-certs
1809 @itemx --no-force-v4-certs
1810 Always use v4 key signatures even on v3 keys. This option also
1811 changes the default hash algorithm for v3 RSA keys from MD5 to SHA-1.
1812 @option{--no-force-v4-certs} disables this option.
1813
1814 @item --force-mdc
1815 Force the use of encryption with a modification detection code. This
1816 is always used with the newer ciphers (those with a blocksize greater
1817 than 64 bits), or if all of the recipient keys indicate MDC support in
1818 their feature flags.
1819
1820 @item --disable-mdc
1821 Disable the use of the modification detection code. Note that by
1822 using this option, the encrypted message becomes vulnerable to a
1823 message modification attack.
1824
1825 @item --personal-cipher-preferences @code{string}
1826 Set the list of personal cipher preferences to @code{string}, this list
1827 should be a string similar to the one printed by the command "pref" in
1828 the edit menu. This allows the user to factor in their own preferred
1829 algorithms when algorithms are chosen via recipient key preferences.
1830 The most highly ranked cipher in this list is also used for the
1831 @option{--symmetric} encryption command.
1832
1833 @item --personal-digest-preferences @code{string}
1834 Set the list of personal digest preferences to @code{string}, this list
1835 should be a string similar to the one printed by the command "pref" in
1836 the edit menu. This allows the user to factor in their own preferred
1837 algorithms when algorithms are chosen via recipient key preferences.
1838 The most highly ranked digest algorithm in this list is algo used when
1839 signing without encryption (e.g. @option{--clearsign} or
1840 @option{--sign}). The default value is SHA-1.
1841
1842 @item --personal-compress-preferences @code{string}
1843 Set the list of personal compression preferences to @code{string}, this
1844 list should be a string similar to the one printed by the command
1845 "pref" in the edit menu. This allows the user to factor in their own
1846 preferred algorithms when algorithms are chosen via recipient key
1847 preferences. The most highly ranked algorithm in this list is also
1848 used when there are no recipient keys to consider (e.g. @option{--symmetric}).
1849
1850
1851
1852 @item --s2k-cipher-algo @code{name}
1853 Use @code{name} as the cipher algorithm used to protect secret keys.
1854 The default cipher is CAST5. This cipher is also used for
1855 conventional encryption if @option{--personal-cipher-preferences} and
1856 @option{--cipher-algo} is not given.
1857
1858 @item --s2k-digest-algo @code{name}
1859 Use @code{name} as the digest algorithm used to mangle the passphrases.
1860 The default algorithm is SHA-1.
1861
1862 @item --s2k-mode @code{n}
1863 Selects how passphrases are mangled. If @code{n} is 0 a plain
1864 passphrase (which is not recommended) will be used, a 1 adds a salt to
1865 the passphrase and a 3 (the default) iterates the whole process a
1866 couple of times. Unless @option{--rfc1991} is used, this mode is also used for
1867 conventional encryption.
1868
1869
1870
1871 @end table
1872
1873 @c ***************************
1874 @c ******* Compliance ********
1875 @c ***************************
1876 @subsection Compliance options
1877
1878 These options control what GnuPG is compliant to. Only one of these
1879 options may be active at a time. Note that the default setting of
1880 this is nearly always the correct one. See the INTEROPERABILITY WITH
1881 OTHER OPENPGP PROGRAMS section below before using one of these
1882 options.
1883
1884 @table @gnupgtabopt
1885
1886 @item --gnupg
1887 @opindex gnupg
1888 Use standard GnuPG behavior. This is essentially OpenPGP behavior
1889 (see @option{--openpgp}), but with some additional workarounds for common
1890 compatibility problems in different versions of PGP. This is the
1891 default option, so it is not generally needed, but it may be useful to
1892 override a different compliance option in the gpg.conf file.
1893
1894 @item --openpgp
1895 @opindex openpgp
1896 Reset all packet, cipher and digest options to strict OpenPGP
1897 behavior. Use this option to reset all previous options like
1898 @option{--rfc1991}, @option{--force-v3-sigs}, @option{--s2k-*},
1899 @option{--cipher-algo}, @option{--digest-algo} and
1900 @option{--compress-algo} to OpenPGP compliant values. All PGP
1901 workarounds are disabled.
1902
1903 @item --rfc2440
1904 @opindex rfc2440
1905 Reset all packet, cipher and digest options to strict RFC-2440
1906 behavior. Note that this is currently the same thing as @option{--openpgp}.
1907
1908 @item --rfc1991
1909 @opindex rfc1991
1910 Try to be more RFC-1991 (PGP 2.x) compliant.
1911
1912 @item --pgp2
1913 @opindex pgp2
1914 Set up all options to be as PGP 2.x compliant as possible, and warn if
1915 an action is taken (e.g. encrypting to a non-RSA key) that will create
1916 a message that PGP 2.x will not be able to handle. Note that `PGP
1917 2.x' here means `MIT PGP 2.6.2'. There are other versions of PGP 2.x
1918 available, but the MIT release is a good common baseline.
1919
1920 This option implies @option{--rfc1991 --disable-mdc --no-force-v4-certs
1921 --no-sk-comment --escape-from-lines --force-v3-sigs --no-ask-sig-expire
1922 --no-ask-cert-expire --cipher-algo IDEA --digest-algo MD5
1923 --compress-algo 1}. It also disables @option{--textmode} when
1924 encrypting.
1925
1926 @item --pgp6
1927 @opindex pgp6
1928 Set up all options to be as PGP 6 compliant as possible. This
1929 restricts you to the ciphers IDEA (if the IDEA plugin is installed),
1930 3DES, and CAST5, the hashes MD5, SHA1 and RIPEMD160, and the
1931 compression algorithms none and ZIP. This also disables
1932 --throw-keyids, and making signatures with signing subkeys as PGP 6
1933 does not understand signatures made by signing subkeys.
1934
1935 This option implies @option{--disable-mdc --no-sk-comment
1936 --escape-from-lines --force-v3-sigs --no-ask-sig-expire}.
1937
1938 @item --pgp7
1939 @opindex pgp7
1940 Set up all options to be as PGP 7 compliant as possible. This is
1941 identical to @option{--pgp6} except that MDCs are not disabled, and the
1942 list of allowable ciphers is expanded to add AES128, AES192, AES256, and
1943 TWOFISH.
1944
1945 @item --pgp8
1946 @opindex pgp8
1947 Set up all options to be as PGP 8 compliant as possible. PGP 8 is a lot
1948 closer to the OpenPGP standard than previous versions of PGP, so all
1949 this does is disable @option{--throw-keyids} and set
1950 @option{--escape-from-lines}.  All algorithms are allowed except for the
1951 SHA224, SHA384, and SHA512 digests.
1952
1953 @end table
1954
1955
1956 @c *******************************************
1957 @c ********  ESOTERIC OPTIONS  ***************
1958 @c *******************************************
1959 @node GPG Esoteric Options
1960 @subsection Doing things one usually don't want to do.
1961
1962 @table @gnupgtabopt
1963
1964 @item -n
1965 @itemx --dry-run
1966 @opindex dry-run
1967 Don't make any changes (this is not completely implemented).
1968
1969 @item --list-only
1970 Changes the behaviour of some commands. This is like @option{--dry-run} but
1971 different in some cases. The semantic of this command may be extended in
1972 the future. Currently it only skips the actual decryption pass and
1973 therefore enables a fast listing of the encryption keys.
1974
1975 @item -i
1976 @itemx --interactive
1977 @opindex interactive
1978 Prompt before overwriting any files.
1979
1980 @item --debug @var{flags}
1981 @opindex debug
1982 Set debugging flags. All flags are or-ed and @var{flags} may
1983 be given in C syntax (e.g. 0x0042).
1984
1985 @item --debug-all
1986 Set all useful debugging flags.
1987
1988 @ifset gpgone
1989 @item --debug-ccid-driver
1990 Enable debug output from the included CCID driver for smartcards.
1991 Note that this option is only available on some system.
1992 @end ifset
1993
1994 @item --enable-progress-filter
1995 Enable certain PROGRESS status outputs. This option allows frontends
1996 to display a progress indicator while gpg is processing larger files.
1997 There is a slight performance overhead using it.
1998
1999 @item --status-fd @code{n}
2000 Write special status strings to the file descriptor @code{n}.
2001 See the file DETAILS in the documentation for a listing of them.
2002
2003 @item --status-file @code{file}
2004 Same as @option{--status-fd}, except the status data is written to file
2005 @code{file}.
2006
2007 @item --logger-fd @code{n}
2008 Write log output to file descriptor @code{n} and not to stderr.
2009
2010 @item --logger-file @code{file}
2011 Same as @option{--logger-fd}, except the logger data is written to file
2012 @code{file}.
2013
2014 @item --attribute-fd @code{n}
2015 Write attribute subpackets to the file descriptor @code{n}. This is most
2016 useful for use with @option{--status-fd}, since the status messages are
2017 needed to separate out the various subpackets from the stream delivered
2018 to the file descriptor.
2019
2020 @item --attribute-file @code{file}
2021 Same as @option{--attribute-fd}, except the attribute data is written to
2022 file @code{file}.
2023
2024 @item --comment @code{string}
2025 @itemx --no-comments
2026 Use @code{string} as a comment string in clear text signatures and ASCII
2027 armored messages or keys (see @option{--armor}). The default behavior is
2028 not to use a comment string. @option{--comment} may be repeated multiple
2029 times to get multiple comment strings. @option{--no-comments} removes
2030 all comments.  It is a good idea to keep the length of a single comment
2031 below 60 characters to avoid problems with mail programs wrapping such
2032 lines.  Note that comment lines, like all other header lines, are not
2033 protected by the signature.
2034
2035 @item --emit-version
2036 @itemx --no-emit-version
2037 Force inclusion of the version string in ASCII armored output.
2038 @option{--no-emit-version} disables this option.
2039
2040 @item --sig-notation @code{name=value}
2041 @itemx --cert-notation @code{name=value}
2042 @itemx -N, --set-notation @code{name=value}
2043 Put the name value pair into the signature as notation data.
2044 @code{name} must consist only of printable characters or spaces, and
2045 must contain a '@@' character in the form keyname@@domain.example.com
2046 (substituting the appropriate keyname and domain name, of course).  This
2047 is to help prevent pollution of the IETF reserved notation
2048 namespace. The @option{--expert} flag overrides the '@@'
2049 check. @code{value} may be any printable string; it will be encoded in
2050 UTF8, so you should check that your @option{--display-charset} is set
2051 correctly. If you prefix @code{name} with an exclamation mark (!), the
2052 notation data will be flagged as critical
2053 (rfc2440:5.2.3.15). @option{--sig-notation} sets a notation for data
2054 signatures. @option{--cert-notation} sets a notation for key signatures
2055 (certifications). @option{--set-notation} sets both.
2056
2057 There are special codes that may be used in notation names. "%k" will
2058 be expanded into the key ID of the key being signed, "%K" into the
2059 long key ID of the key being signed, "%f" into the fingerprint of the
2060 key being signed, "%s" into the key ID of the key making the
2061 signature, "%S" into the long key ID of the key making the signature,
2062 "%g" into the fingerprint of the key making the signature (which might
2063 be a subkey), "%p" into the fingerprint of the primary key of the key
2064 making the signature, "%c" into the signature count from the OpenPGP
2065 smartcard, and "%%" results in a single "%". %k, %K, and %f are only
2066 meaningful when making a key signature (certification), and %c is only
2067 meaningful when using the OpenPGP smartcard.
2068
2069 @item --sig-policy-url @code{string}
2070 @itemx --cert-policy-url @code{string}
2071 @itemx --set-policy-url @code{string}
2072 Use @code{string} as a Policy URL for signatures (rfc2440:5.2.3.19).  If
2073 you prefix it with an exclamation mark (!), the policy URL packet will
2074 be flagged as critical. @option{--sig-policy-url} sets a policy url for
2075 data signatures. @option{--cert-policy-url} sets a policy url for key
2076 signatures (certifications). @option{--set-policy-url} sets both.
2077
2078 The same %-expandos used for notation data are available here as well.
2079
2080 @item --sig-keyserver-url @code{string}
2081 Use @code{string} as a preferred keyserver URL for data signatures. If
2082 you prefix it with an exclamation mark, the keyserver URL packet will
2083 be flagged as critical.
2084
2085 The same %-expandos used for notation data are available here as well.
2086
2087 @item --set-filename @code{string}
2088 Use @code{string} as the filename which is stored inside messages.
2089 This overrides the default, which is to use the actual filename of the
2090 file being encrypted.
2091
2092 @item --for-your-eyes-only
2093 @itemx --no-for-your-eyes-only
2094 Set the `for your eyes only' flag in the message. This causes GnuPG
2095 to refuse to save the file unless the @option{--output} option is given, and
2096 PGP to use the "secure viewer" with a Tempest-resistant font to
2097 display the message. This option overrides @option{--set-filename}.
2098 @option{--no-for-your-eyes-only} disables this option.
2099
2100 @item --use-embedded-filename
2101 @itemx --no-use-embedded-filename
2102 Try to create a file with a name as embedded in the data. This can be
2103 a dangerous option as it allows to overwrite files. Defaults to no.
2104
2105 @item --cipher-algo @code{name}
2106 Use @code{name} as cipher algorithm. Running the program with the
2107 command @option{--version} yields a list of supported algorithms. If
2108 this is not used the cipher algorithm is selected from the preferences
2109 stored with the key. In general, you do not want to use this option as
2110 it allows you to violate the OpenPGP standard.
2111 @option{--personal-cipher-preferences} is the safe way to accomplish the
2112 same thing.
2113
2114 @item --digest-algo @code{name}
2115 Use @code{name} as the message digest algorithm. Running the program
2116 with the command @option{--version} yields a list of supported algorithms. In
2117 general, you do not want to use this option as it allows you to
2118 violate the OpenPGP standard. @option{--personal-digest-preferences} is the
2119 safe way to accomplish the same thing.
2120
2121 @item --compress-algo @code{name}
2122 Use compression algorithm @code{name}. "zlib" is RFC-1950 ZLIB
2123 compression. "zip" is RFC-1951 ZIP compression which is used by PGP.
2124 "bzip2" is a more modern compression scheme that can compress some
2125 things better than zip or zlib, but at the cost of more memory used
2126 during compression and decompression. "uncompressed" or "none"
2127 disables compression. If this option is not used, the default
2128 behavior is to examine the recipient key preferences to see which
2129 algorithms the recipient supports. If all else fails, ZIP is used for
2130 maximum compatibility.
2131
2132 ZLIB may give better compression results than ZIP, as the compression
2133 window size is not limited to 8k. BZIP2 may give even better
2134 compression results than that, but will use a significantly larger
2135 amount of memory while compressing and decompressing. This may be
2136 significant in low memory situations. Note, however, that PGP (all
2137 versions) only supports ZIP compression. Using any algorithm other
2138 than ZIP or "none" will make the message unreadable with PGP. In
2139 general, you do not want to use this option as it allows you to
2140 violate the OpenPGP standard. @option{--personal-compress-preferences} is the
2141 safe way to accomplish the same thing.
2142
2143 @item --cert-digest-algo @code{name}
2144 Use @code{name} as the message digest algorithm used when signing a
2145 key. Running the program with the command @option{--version} yields a
2146 list of supported algorithms. Be aware that if you choose an algorithm
2147 that GnuPG supports but other OpenPGP implementations do not, then some
2148 users will not be able to use the key signatures you make, or quite
2149 possibly your entire key.
2150
2151 @item --disable-cipher-algo @code{name}
2152 Never allow the use of @code{name} as cipher algorithm.
2153 The given name will not be checked so that a later loaded algorithm
2154 will still get disabled.
2155
2156 @item --disable-pubkey-algo @code{name}
2157 Never allow the use of @code{name} as public key algorithm.
2158 The given name will not be checked so that a later loaded algorithm
2159 will still get disabled.
2160
2161 @item --throw-keyids
2162 @itemx --no-throw-keyids
2163 Do not put the recipient key IDs into encrypted messages. This helps
2164 to hide the receivers of the message and is a limited countermeasure
2165 against traffic analysis. On the receiving side, it may slow down the
2166 decryption process because all available secret keys must be tried.
2167 @option{--no-throw-keyids} disables this option. This option is essentially
2168 the same as using @option{--hidden-recipient} for all recipients.
2169
2170 @item --not-dash-escaped
2171 This option changes the behavior of cleartext signatures
2172 so that they can be used for patch files. You should not
2173 send such an armored file via email because all spaces
2174 and line endings are hashed too. You can not use this
2175 option for data which has 5 dashes at the beginning of a
2176 line, patch files don't have this. A special armor header
2177 line tells GnuPG about this cleartext signature option.
2178
2179 @item --escape-from-lines
2180 @itemx --no-escape-from-lines
2181 Because some mailers change lines starting with "From " to ">From " it
2182 is good to handle such lines in a special way when creating cleartext
2183 signatures to prevent the mail system from breaking the signature. Note
2184 that all other PGP versions do it this way too.  Enabled by
2185 default. @option{--no-escape-from-lines} disables this option.
2186
2187 @item --passphrase-fd @code{n}
2188 Read the passphrase from file descriptor @code{n}. Only the first line
2189 will be read from file descriptor @code{n}. If you use 0 for @code{n},
2190 the passphrase will be read from stdin. This can only be used if only
2191 one passphrase is supplied.
2192 @ifclear gpgone
2193 Note that this passphrase is only used if the option @option{--batch}
2194 has also been given.  This is different from @command{gpg}.
2195 @end ifclear
2196
2197 @item --passphrase-file @code{file}
2198 Read the passphrase from file @code{file}. Only the first line will
2199 be read from file @code{file}. This can only be used if only one
2200 passphrase is supplied. Obviously, a passphrase stored in a file is
2201 of questionable security if other users can read this file. Don't use
2202 this option if you can avoid it.
2203 @ifclear gpgone
2204 Note that this passphrase is only used if the option @option{--batch}
2205 has also been given.  This is different from @command{gpg}.
2206 @end ifclear
2207
2208 @item --passphrase @code{string}
2209 Use @code{string} as the passphrase. This can only be used if only one
2210 passphrase is supplied. Obviously, this is of very questionable
2211 security on a multi-user system. Don't use this option if you can
2212 avoid it.
2213 @ifclear gpgone
2214 Note that this passphrase is only used if the option @option{--batch}
2215 has also been given.  This is different from @command{gpg}.
2216 @end ifclear
2217
2218 @item --command-fd @code{n}
2219 This is a replacement for the deprecated shared-memory IPC mode.
2220 If this option is enabled, user input on questions is not expected
2221 from the TTY but from the given file descriptor. It should be used
2222 together with @option{--status-fd}. See the file doc/DETAILS in the source
2223 distribution for details on how to use it.
2224
2225 @item --command-file @code{file}
2226 Same as @option{--command-fd}, except the commands are read out of file
2227 @code{file}
2228
2229 @item --allow-non-selfsigned-uid
2230 @itemx --no-allow-non-selfsigned-uid
2231 Allow the import and use of keys with user IDs which are not
2232 self-signed. This is not recommended, as a non self-signed user ID is
2233 trivial to forge. @option{--no-allow-non-selfsigned-uid} disables.
2234
2235 @item --allow-freeform-uid
2236 Disable all checks on the form of the user ID while generating a new
2237 one. This option should only be used in very special environments as
2238 it does not ensure the de-facto standard format of user IDs.
2239
2240 @item --ignore-time-conflict
2241 GnuPG normally checks that the timestamps associated with keys and
2242 signatures have plausible values. However, sometimes a signature
2243 seems to be older than the key due to clock problems. This option
2244 makes these checks just a warning. See also @option{--ignore-valid-from} for
2245 timestamp issues on subkeys.
2246
2247 @item --ignore-valid-from
2248 GnuPG normally does not select and use subkeys created in the future.
2249 This option allows the use of such keys and thus exhibits the
2250 pre-1.0.7 behaviour. You should not use this option unless you there
2251 is some clock problem. See also @option{--ignore-time-conflict} for timestamp
2252 issues with signatures.
2253
2254 @item --ignore-crc-error
2255 The ASCII armor used by OpenPGP is protected by a CRC checksum against
2256 transmission errors. Occasionally the CRC gets mangled somewhere on
2257 the transmission channel but the actual content (which is protected by
2258 the OpenPGP protocol anyway) is still okay. This option allows GnuPG
2259 to ignore CRC errors.
2260
2261 @item --ignore-mdc-error
2262 This option changes a MDC integrity protection failure into a warning.
2263 This can be useful if a message is partially corrupt, but it is
2264 necessary to get as much data as possible out of the corrupt message.
2265 However, be aware that a MDC protection failure may also mean that the
2266 message was tampered with intentionally by an attacker.
2267
2268 @item --no-default-keyring
2269 Do not add the default keyrings to the list of keyrings. Note that
2270 GnuPG will not operate without any keyrings, so if you use this option
2271 and do not provide alternate keyrings via @option{--keyring} or
2272 @option{--secret-keyring}, then GnuPG will still use the default public or
2273 secret keyrings.
2274
2275 @item --skip-verify
2276 Skip the signature verification step. This may be
2277 used to make the decryption faster if the signature
2278 verification is not needed.
2279
2280 @item --with-key-data
2281 Print key listings delimited by colons (like @option{--with-colons}) and
2282 print the public key data.
2283
2284 @item --fast-list-mode
2285 Changes the output of the list commands to work faster; this is achieved
2286 by leaving some parts empty. Some applications don't need the user ID
2287 and the trust information given in the listings. By using this options
2288 they can get a faster listing. The exact behaviour of this option may
2289 change in future versions.  If you are missing some information, don't
2290 use this option.
2291
2292 @item --no-literal
2293 This is not for normal use. Use the source to see for what it might be useful.
2294
2295 @item --set-filesize
2296 This is not for normal use. Use the source to see for what it might be useful.
2297
2298 @item --show-session-key
2299 Display the session key used for one message. See
2300 @option{--override-session-key} for the counterpart of this option.
2301
2302 We think that Key Escrow is a Bad Thing; however the user should have
2303 the freedom to decide whether to go to prison or to reveal the content
2304 of one specific message without compromising all messages ever
2305 encrypted for one secret key. DON'T USE IT UNLESS YOU ARE REALLY
2306 FORCED TO DO SO.
2307
2308 @item --override-session-key @code{string}
2309 Don't use the public key but the session key @code{string}. The format
2310 of this string is the same as the one printed by
2311 @option{--show-session-key}. This option is normally not used but comes
2312 handy in case someone forces you to reveal the content of an encrypted
2313 message; using this option you can do this without handing out the
2314 secret key.
2315
2316 @item --ask-sig-expire
2317 @itemx --no-ask-sig-expire
2318 When making a data signature, prompt for an expiration time. If this
2319 option is not specified, the expiration time set via
2320 @option{--default-sig-expire} is used. @option{--no-ask-sig-expire}
2321 disables this option. Note that by default, @option{--force-v3-sigs} is
2322 set which also disables this option. If you want signature expiration,
2323 you must set @option{--no-force-v3-sigs} as well as turning
2324 @option{--ask-sig-expire} on.
2325
2326 @item --default-sig-expire
2327 The default expiration time to use for signature expiration. Valid
2328 values are "0" for no expiration, a number followed by the letter d
2329 (for days), w (for weeks), m (for months), or y (for years) (for
2330 example "2m" for two months, or "5y" for five years), or an absolute
2331 date in the form YYYY-MM-DD. Defaults to "0".
2332
2333 @item --ask-cert-expire
2334 @itemx --no-ask-cert-expire
2335 When making a key signature, prompt for an expiration time. If this
2336 option is not specified, the expiration time set via
2337 @option{--default-cert-expire} is used. @option{--no-ask-cert-expire}
2338 disables this option.
2339
2340 @item --default-cert-expire
2341 The default expiration time to use for key signature expiration.
2342 Valid values are "0" for no expiration, a number followed by the
2343 letter d (for days), w (for weeks), m (for months), or y (for years)
2344 (for example "2m" for two months, or "5y" for five years), or an
2345 absolute date in the form YYYY-MM-DD. Defaults to "0".
2346
2347 @item --allow-secret-key-import
2348 This is an obsolete option and is not used anywhere.
2349
2350 @item --allow-multisig-verification
2351 Allow verification of concatenated signed messages. This will run a
2352 signature verification for each data+signature block. There are some
2353 security issues with this option and thus it is off by default. Note
2354 that versions of GPG prior to version 1.4.3 implicitly allowed this.
2355
2356 @item --enable-special-filenames
2357 This options enables a mode in which filenames of the form
2358 @file{-&n}, where n is a non-negative decimal number,
2359 refer to the file descriptor n and not to a file with that name.
2360
2361 @item --no-expensive-trust-checks
2362 Experimental use only.
2363
2364 @item --preserve-permissions
2365 Don't change the permissions of a secret keyring back to user
2366 read/write only. Use this option only if you really know what you are doing.
2367
2368 @item --default-preference-list @code{string}
2369 @opindex default-preference-list
2370 Set the list of default preferences to @code{string}. This preference
2371 list is used for new keys and becomes the default for "setpref" in the
2372 edit menu.
2373
2374 @item --default-keyserver-url @code{name}
2375 @opindex default-keyserver-url
2376 Set the default keyserver URL to @code{name}. This keyserver will be
2377 used as the keyserver URL when writing a new self-signature on a key,
2378 which includes key generation and changing preferences.
2379
2380 @item --list-config
2381 @opindex list-config
2382 Display various internal configuration parameters of GnuPG. This option
2383 is intended for external programs that call GnuPG to perform tasks, and
2384 is thus not generally useful. See the file @file{doc/DETAILS} in the
2385 source distribution for the details of which configuration items may be
2386 listed. @option{--list-config} is only usable with
2387 @option{--with-colons} set.
2388
2389 @end table
2390
2391 @c *******************************
2392 @c ******* Deprecated ************
2393 @c *******************************
2394 @subsection Deprecated options
2395
2396 @table @gnupgtabopt
2397
2398 @ifset gpgone
2399 @item --load-extension @code{name}
2400 Load an extension module. If @code{name} does not contain a slash it is
2401 searched for in the directory configured when GnuPG was built
2402 (generally "/usr/local/lib/gnupg"). Extensions are not generally
2403 useful anymore, and the use of this option is deprecated.
2404 @end ifset
2405
2406 @item --show-photos
2407 @itemx --no-show-photos
2408 Causes @option{--list-keys}, @option{--list-sigs},
2409 @option{--list-public-keys}, @option{--list-secret-keys}, and verifying
2410 a signature to also display the photo ID attached to the key, if
2411 any. See also @option{--photo-viewer}. These options are deprecated. Use
2412 @option{--list-options [no-]show-photos} and/or @option{--verify-options
2413 [no-]show-photos} instead.
2414
2415 @item --show-keyring
2416 Display the keyring name at the head of key listings to show which
2417 keyring a given key resides on. This option is deprecated: use
2418 @option{--list-options [no-]show-keyring} instead.
2419
2420 @item --ctapi-driver @code{file}
2421 Use @code{file} to access the smartcard reader. The current default
2422 is `libtowitoko.so'. Note that the use of this interface is
2423 deprecated; it may be removed in future releases.
2424
2425 @item --always-trust
2426 Identical to @option{--trust-model always}. This option is deprecated.
2427
2428 @item --show-notation
2429 @itemx --no-show-notation
2430 Show signature notations in the @option{--list-sigs} or @option{--check-sigs} listings
2431 as well as when verifying a signature with a notation in it. These
2432 options are deprecated. Use @option{--list-options [no-]show-notation}
2433 and/or @option{--verify-options [no-]show-notation} instead.
2434
2435 @item --show-policy-url
2436 @itemx --no-show-policy-url
2437 Show policy URLs in the @option{--list-sigs} or @option{--check-sigs}
2438 listings as well as when verifying a signature with a policy URL in
2439 it. These options are deprecated. Use @option{--list-options
2440 [no-]show-policy-url} and/or @option{--verify-options
2441 [no-]show-policy-url} instead.
2442
2443
2444 @end table
2445
2446
2447 @c *******************************************
2448 @c ***************            ****************
2449 @c ***************   FILES    ****************
2450 @c ***************            ****************
2451 @c *******************************************
2452 @mansect files
2453 @node GPG Configuration
2454 @section Configuration files
2455
2456 There are a few configuration files to control certain aspects of
2457 @command{@gpgname}'s operation. Unless noted, they are expected in the
2458 current home directory (@pxref{option --homedir}).
2459
2460 @table @file
2461
2462 @item gpg.conf
2463 @cindex gpgsm.conf
2464 This is the standard configuration file read by @command{@gpgname} on
2465 startup.  It may contain any valid long option; the leading two dashes
2466 may not be entered and the option may not be abbreviated.  This default
2467 name may be changed on the command line (@pxref{option
2468   --options}).
2469
2470 @end table
2471
2472 @c man:.RE
2473 Note that on larger installations, it is useful to put predefined files
2474 into the directory @file{/etc/skel/.gnupg/} so that newly created users
2475 start up with a working configuration.  For existing users the a small
2476 helper script is provided to create these files (@pxref{addgnupghome}).
2477
2478 For internal purposes @command{@gpgname} creates and maintaines a few other
2479 files; They all live in in the current home directory (@pxref{option
2480 --homedir}).  Only the @command{@gpgname} may modify these files.
2481
2482
2483 @table @file
2484 @item ~/.gnupg/secring.gpg
2485 The secret keyring.
2486
2487 @item ~/.gnupg/secring.gpg.lock
2488 and the lock file
2489
2490 @item ~/.gnupg/pubring.gpg
2491 The public keyring
2492
2493 @item ~/.gnupg/pubring.gpg.lock
2494 and the lock file
2495
2496 @item ~/.gnupg/trustdb.gpg
2497 The trust database
2498
2499 @item ~/.gnupg/trustdb.gpg.lock
2500 and the lock file
2501
2502 @item ~/.gnupg/random_seed
2503 used to preserve the internal random pool
2504
2505 @item /usr[/local]/share/gnupg/options.skel
2506 Skeleton options file
2507
2508 @item /usr[/local]/lib/gnupg/
2509 Default location for extensions
2510
2511 @end table
2512
2513 @c man:.RE
2514 Operation is further controlled by a few environment variables:
2515
2516 @table @asis
2517
2518 @item HOME
2519 Used to locate the default home directory.
2520
2521 @item GNUPGHOME
2522 If set directory used instead of "~/.gnupg".
2523
2524 @item GPG_AGENT_INFO
2525 Used to locate the gpg-agent.
2526 @ifset gpgone
2527 This is only honored when @option{--use-agent} is set.
2528 @end ifset
2529 The value consists of 3 colon delimited fields: The first is the path
2530 to the Unix Domain Socket, the second the PID of the gpg-agent and the
2531 protocol version which should be set to 1. When starting the gpg-agent
2532 as described in its documentation, this variable is set to the correct
2533 value. The option @option{--gpg-agent-info} can be used to override it.
2534
2535 @item COLUMNS
2536 @itemx LINES
2537 Used to size some displays to the full size of the screen.
2538
2539 @end table
2540
2541
2542 @c *******************************************
2543 @c ***************            ****************
2544 @c ***************  EXAMPLES  ****************
2545 @c ***************            ****************
2546 @c *******************************************
2547 @mansect examples
2548 @node GPG Examples
2549 @section Examples
2550
2551 @table @asis
2552
2553 @item gpg -se -r @code{Bob} @code{file}
2554 sign and encrypt for user Bob
2555
2556 @item gpg --clearsign @code{file}
2557 make a clear text signature
2558
2559 @item gpg -sb @code{file}
2560 make a detached signature
2561
2562 @item gpg --list-keys @code{user_ID}
2563 show keys
2564
2565 @item gpg --fingerprint @code{user_ID}
2566 show fingerprint
2567
2568 @item gpg --verify @code{pgpfile}
2569 @itemx gpg --verify @code{sigfile}
2570 Verify the signature of the file but do not output the data. The
2571 second form is used for detached signatures, where @code{sigfile}
2572 is the detached signature (either ASCII armored or binary) and
2573 are the signed data; if this is not given, the name of
2574 the file holding the signed data is constructed by cutting off the
2575 extension (".asc" or ".sig") of @code{sigfile} or by asking the
2576 user for the filename.
2577 @end table
2578
2579
2580 @c *******************************************
2581 @c ***************            ****************
2582 @c ***************  USER ID   ****************
2583 @c ***************            ****************
2584 @c *******************************************
2585 @mansect how to specify a user id
2586 @ifset isman
2587 @include specify-user-id.texi
2588 @end ifset
2589
2590 @mansect return vaue
2591 @chapheading RETURN VALUE
2592
2593 The program returns 0 if everything was fine, 1 if at least
2594 a signature was bad, and other error codes for fatal errors.
2595
2596 @mansect warnings
2597 @chapheading WARNINGS
2598
2599 Use a *good* password for your user account and a *good* passphrase
2600 to protect your secret key. This passphrase is the weakest part of the
2601 whole system. Programs to do dictionary attacks on your secret keyring
2602 are very easy to write and so you should protect your "~/.gnupg/"
2603 directory very well.
2604
2605 Keep in mind that, if this program is used over a network (telnet), it
2606 is *very* easy to spy out your passphrase!
2607
2608 If you are going to verify detached signatures, make sure that the
2609 program knows about it; either give both filenames on the command line
2610 or use @samp{-} to specify stdin.
2611
2612 @mansect interoperability
2613 @chapheading INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS
2614
2615 GnuPG tries to be a very flexible implementation of the OpenPGP
2616 standard. In particular, GnuPG implements many of the optional parts
2617 of the standard, such as the SHA-512 hash, and the ZLIB and BZIP2
2618 compression algorithms. It is important to be aware that not all
2619 OpenPGP programs implement these optional algorithms and that by
2620 forcing their use via the @option{--cipher-algo}, @option{--digest-algo},
2621 @option{--cert-digest-algo}, or @option{--compress-algo} options in GnuPG, it is
2622 possible to create a perfectly valid OpenPGP message, but one that
2623 cannot be read by the intended recipient.
2624
2625 There are dozens of variations of OpenPGP programs available, and each
2626 supports a slightly different subset of these optional algorithms.
2627 For example, until recently, no (unhacked) version of PGP supported
2628 the BLOWFISH cipher algorithm. A message using BLOWFISH simply could
2629 not be read by a PGP user. By default, GnuPG uses the standard
2630 OpenPGP preferences system that will always do the right thing and
2631 create messages that are usable by all recipients, regardless of which
2632 OpenPGP program they use. Only override this safe default if you
2633 really know what you are doing.
2634
2635 If you absolutely must override the safe default, or if the preferences
2636 on a given key are invalid for some reason, you are far better off using
2637 the @option{--pgp6}, @option{--pgp7}, or @option{--pgp8} options. These
2638 options are safe as they do not force any particular algorithms in
2639 violation of OpenPGP, but rather reduce the available algorithms to a
2640 "PGP-safe" list.
2641
2642 @mansect bugs
2643 @chapheading BUGS
2644
2645 On many systems this program should be installed as setuid(root). This
2646 is necessary to lock memory pages. Locking memory pages prevents the
2647 operating system from writing memory pages (which may contain
2648 passphrases or other sensitive material) to disk. If you get no
2649 warning message about insecure memory your operating system supports
2650 locking without being root. The program drops root privileges as soon
2651 as locked memory is allocated.
2652
2653 @mansect see also
2654 @ifset isman
2655 @command{gpgv}(1), 
2656 @command{gpgsm}(1), 
2657 @command{gpg-agent}(1)
2658 @end ifset
2659 @include see-also-note.texi