* gpg.texi: Document --s2k-count.
[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 @item --s2k-count @code{n}
1870 Specify how many times the passphrase mangling is repeated.  This
1871 value may range between 1024 and 65011712 inclusive, and the default
1872 is 65536.  Note that not all values in the 1024-65011712 range are
1873 legal and if an illegal value is selected, GnuPG will round up to the
1874 nearest legal value.  This option is only meaningful if
1875 @option{--s2k-mode} is 3.
1876
1877
1878 @end table
1879
1880 @c ***************************
1881 @c ******* Compliance ********
1882 @c ***************************
1883 @subsection Compliance options
1884
1885 These options control what GnuPG is compliant to. Only one of these
1886 options may be active at a time. Note that the default setting of
1887 this is nearly always the correct one. See the INTEROPERABILITY WITH
1888 OTHER OPENPGP PROGRAMS section below before using one of these
1889 options.
1890
1891 @table @gnupgtabopt
1892
1893 @item --gnupg
1894 @opindex gnupg
1895 Use standard GnuPG behavior. This is essentially OpenPGP behavior
1896 (see @option{--openpgp}), but with some additional workarounds for common
1897 compatibility problems in different versions of PGP. This is the
1898 default option, so it is not generally needed, but it may be useful to
1899 override a different compliance option in the gpg.conf file.
1900
1901 @item --openpgp
1902 @opindex openpgp
1903 Reset all packet, cipher and digest options to strict OpenPGP
1904 behavior. Use this option to reset all previous options like
1905 @option{--rfc1991}, @option{--force-v3-sigs}, @option{--s2k-*},
1906 @option{--cipher-algo}, @option{--digest-algo} and
1907 @option{--compress-algo} to OpenPGP compliant values. All PGP
1908 workarounds are disabled.
1909
1910 @item --rfc2440
1911 @opindex rfc2440
1912 Reset all packet, cipher and digest options to strict RFC-2440
1913 behavior. Note that this is currently the same thing as @option{--openpgp}.
1914
1915 @item --rfc1991
1916 @opindex rfc1991
1917 Try to be more RFC-1991 (PGP 2.x) compliant.
1918
1919 @item --pgp2
1920 @opindex pgp2
1921 Set up all options to be as PGP 2.x compliant as possible, and warn if
1922 an action is taken (e.g. encrypting to a non-RSA key) that will create
1923 a message that PGP 2.x will not be able to handle. Note that `PGP
1924 2.x' here means `MIT PGP 2.6.2'. There are other versions of PGP 2.x
1925 available, but the MIT release is a good common baseline.
1926
1927 This option implies @option{--rfc1991 --disable-mdc --no-force-v4-certs
1928 --no-sk-comment --escape-from-lines --force-v3-sigs --no-ask-sig-expire
1929 --no-ask-cert-expire --cipher-algo IDEA --digest-algo MD5
1930 --compress-algo 1}. It also disables @option{--textmode} when
1931 encrypting.
1932
1933 @item --pgp6
1934 @opindex pgp6
1935 Set up all options to be as PGP 6 compliant as possible. This
1936 restricts you to the ciphers IDEA (if the IDEA plugin is installed),
1937 3DES, and CAST5, the hashes MD5, SHA1 and RIPEMD160, and the
1938 compression algorithms none and ZIP. This also disables
1939 --throw-keyids, and making signatures with signing subkeys as PGP 6
1940 does not understand signatures made by signing subkeys.
1941
1942 This option implies @option{--disable-mdc --no-sk-comment
1943 --escape-from-lines --force-v3-sigs --no-ask-sig-expire}.
1944
1945 @item --pgp7
1946 @opindex pgp7
1947 Set up all options to be as PGP 7 compliant as possible. This is
1948 identical to @option{--pgp6} except that MDCs are not disabled, and the
1949 list of allowable ciphers is expanded to add AES128, AES192, AES256, and
1950 TWOFISH.
1951
1952 @item --pgp8
1953 @opindex pgp8
1954 Set up all options to be as PGP 8 compliant as possible. PGP 8 is a lot
1955 closer to the OpenPGP standard than previous versions of PGP, so all
1956 this does is disable @option{--throw-keyids} and set
1957 @option{--escape-from-lines}.  All algorithms are allowed except for the
1958 SHA224, SHA384, and SHA512 digests.
1959
1960 @end table
1961
1962
1963 @c *******************************************
1964 @c ********  ESOTERIC OPTIONS  ***************
1965 @c *******************************************
1966 @node GPG Esoteric Options
1967 @subsection Doing things one usually don't want to do.
1968
1969 @table @gnupgtabopt
1970
1971 @item -n
1972 @itemx --dry-run
1973 @opindex dry-run
1974 Don't make any changes (this is not completely implemented).
1975
1976 @item --list-only
1977 Changes the behaviour of some commands. This is like @option{--dry-run} but
1978 different in some cases. The semantic of this command may be extended in
1979 the future. Currently it only skips the actual decryption pass and
1980 therefore enables a fast listing of the encryption keys.
1981
1982 @item -i
1983 @itemx --interactive
1984 @opindex interactive
1985 Prompt before overwriting any files.
1986
1987 @item --debug @var{flags}
1988 @opindex debug
1989 Set debugging flags. All flags are or-ed and @var{flags} may
1990 be given in C syntax (e.g. 0x0042).
1991
1992 @item --debug-all
1993 Set all useful debugging flags.
1994
1995 @ifset gpgone
1996 @item --debug-ccid-driver
1997 Enable debug output from the included CCID driver for smartcards.
1998 Note that this option is only available on some system.
1999 @end ifset
2000
2001 @item --enable-progress-filter
2002 Enable certain PROGRESS status outputs. This option allows frontends
2003 to display a progress indicator while gpg is processing larger files.
2004 There is a slight performance overhead using it.
2005
2006 @item --status-fd @code{n}
2007 Write special status strings to the file descriptor @code{n}.
2008 See the file DETAILS in the documentation for a listing of them.
2009
2010 @item --status-file @code{file}
2011 Same as @option{--status-fd}, except the status data is written to file
2012 @code{file}.
2013
2014 @item --logger-fd @code{n}
2015 Write log output to file descriptor @code{n} and not to stderr.
2016
2017 @item --logger-file @code{file}
2018 Same as @option{--logger-fd}, except the logger data is written to file
2019 @code{file}.
2020
2021 @item --attribute-fd @code{n}
2022 Write attribute subpackets to the file descriptor @code{n}. This is most
2023 useful for use with @option{--status-fd}, since the status messages are
2024 needed to separate out the various subpackets from the stream delivered
2025 to the file descriptor.
2026
2027 @item --attribute-file @code{file}
2028 Same as @option{--attribute-fd}, except the attribute data is written to
2029 file @code{file}.
2030
2031 @item --comment @code{string}
2032 @itemx --no-comments
2033 Use @code{string} as a comment string in clear text signatures and ASCII
2034 armored messages or keys (see @option{--armor}). The default behavior is
2035 not to use a comment string. @option{--comment} may be repeated multiple
2036 times to get multiple comment strings. @option{--no-comments} removes
2037 all comments.  It is a good idea to keep the length of a single comment
2038 below 60 characters to avoid problems with mail programs wrapping such
2039 lines.  Note that comment lines, like all other header lines, are not
2040 protected by the signature.
2041
2042 @item --emit-version
2043 @itemx --no-emit-version
2044 Force inclusion of the version string in ASCII armored output.
2045 @option{--no-emit-version} disables this option.
2046
2047 @item --sig-notation @code{name=value}
2048 @itemx --cert-notation @code{name=value}
2049 @itemx -N, --set-notation @code{name=value}
2050 Put the name value pair into the signature as notation data.
2051 @code{name} must consist only of printable characters or spaces, and
2052 must contain a '@@' character in the form keyname@@domain.example.com
2053 (substituting the appropriate keyname and domain name, of course).  This
2054 is to help prevent pollution of the IETF reserved notation
2055 namespace. The @option{--expert} flag overrides the '@@'
2056 check. @code{value} may be any printable string; it will be encoded in
2057 UTF8, so you should check that your @option{--display-charset} is set
2058 correctly. If you prefix @code{name} with an exclamation mark (!), the
2059 notation data will be flagged as critical
2060 (rfc2440:5.2.3.15). @option{--sig-notation} sets a notation for data
2061 signatures. @option{--cert-notation} sets a notation for key signatures
2062 (certifications). @option{--set-notation} sets both.
2063
2064 There are special codes that may be used in notation names. "%k" will
2065 be expanded into the key ID of the key being signed, "%K" into the
2066 long key ID of the key being signed, "%f" into the fingerprint of the
2067 key being signed, "%s" into the key ID of the key making the
2068 signature, "%S" into the long key ID of the key making the signature,
2069 "%g" into the fingerprint of the key making the signature (which might
2070 be a subkey), "%p" into the fingerprint of the primary key of the key
2071 making the signature, "%c" into the signature count from the OpenPGP
2072 smartcard, and "%%" results in a single "%". %k, %K, and %f are only
2073 meaningful when making a key signature (certification), and %c is only
2074 meaningful when using the OpenPGP smartcard.
2075
2076 @item --sig-policy-url @code{string}
2077 @itemx --cert-policy-url @code{string}
2078 @itemx --set-policy-url @code{string}
2079 Use @code{string} as a Policy URL for signatures (rfc2440:5.2.3.19).  If
2080 you prefix it with an exclamation mark (!), the policy URL packet will
2081 be flagged as critical. @option{--sig-policy-url} sets a policy url for
2082 data signatures. @option{--cert-policy-url} sets a policy url for key
2083 signatures (certifications). @option{--set-policy-url} sets both.
2084
2085 The same %-expandos used for notation data are available here as well.
2086
2087 @item --sig-keyserver-url @code{string}
2088 Use @code{string} as a preferred keyserver URL for data signatures. If
2089 you prefix it with an exclamation mark, the keyserver URL packet will
2090 be flagged as critical.
2091
2092 The same %-expandos used for notation data are available here as well.
2093
2094 @item --set-filename @code{string}
2095 Use @code{string} as the filename which is stored inside messages.
2096 This overrides the default, which is to use the actual filename of the
2097 file being encrypted.
2098
2099 @item --for-your-eyes-only
2100 @itemx --no-for-your-eyes-only
2101 Set the `for your eyes only' flag in the message. This causes GnuPG
2102 to refuse to save the file unless the @option{--output} option is given, and
2103 PGP to use the "secure viewer" with a Tempest-resistant font to
2104 display the message. This option overrides @option{--set-filename}.
2105 @option{--no-for-your-eyes-only} disables this option.
2106
2107 @item --use-embedded-filename
2108 @itemx --no-use-embedded-filename
2109 Try to create a file with a name as embedded in the data. This can be
2110 a dangerous option as it allows to overwrite files. Defaults to no.
2111
2112 @item --cipher-algo @code{name}
2113 Use @code{name} as cipher algorithm. Running the program with the
2114 command @option{--version} yields a list of supported algorithms. If
2115 this is not used the cipher algorithm is selected from the preferences
2116 stored with the key. In general, you do not want to use this option as
2117 it allows you to violate the OpenPGP standard.
2118 @option{--personal-cipher-preferences} is the safe way to accomplish the
2119 same thing.
2120
2121 @item --digest-algo @code{name}
2122 Use @code{name} as the message digest algorithm. Running the program
2123 with the command @option{--version} yields a list of supported algorithms. In
2124 general, you do not want to use this option as it allows you to
2125 violate the OpenPGP standard. @option{--personal-digest-preferences} is the
2126 safe way to accomplish the same thing.
2127
2128 @item --compress-algo @code{name}
2129 Use compression algorithm @code{name}. "zlib" is RFC-1950 ZLIB
2130 compression. "zip" is RFC-1951 ZIP compression which is used by PGP.
2131 "bzip2" is a more modern compression scheme that can compress some
2132 things better than zip or zlib, but at the cost of more memory used
2133 during compression and decompression. "uncompressed" or "none"
2134 disables compression. If this option is not used, the default
2135 behavior is to examine the recipient key preferences to see which
2136 algorithms the recipient supports. If all else fails, ZIP is used for
2137 maximum compatibility.
2138
2139 ZLIB may give better compression results than ZIP, as the compression
2140 window size is not limited to 8k. BZIP2 may give even better
2141 compression results than that, but will use a significantly larger
2142 amount of memory while compressing and decompressing. This may be
2143 significant in low memory situations. Note, however, that PGP (all
2144 versions) only supports ZIP compression. Using any algorithm other
2145 than ZIP or "none" will make the message unreadable with PGP. In
2146 general, you do not want to use this option as it allows you to
2147 violate the OpenPGP standard. @option{--personal-compress-preferences} is the
2148 safe way to accomplish the same thing.
2149
2150 @item --cert-digest-algo @code{name}
2151 Use @code{name} as the message digest algorithm used when signing a
2152 key. Running the program with the command @option{--version} yields a
2153 list of supported algorithms. Be aware that if you choose an algorithm
2154 that GnuPG supports but other OpenPGP implementations do not, then some
2155 users will not be able to use the key signatures you make, or quite
2156 possibly your entire key.
2157
2158 @item --disable-cipher-algo @code{name}
2159 Never allow the use of @code{name} as cipher algorithm.
2160 The given name will not be checked so that a later loaded algorithm
2161 will still get disabled.
2162
2163 @item --disable-pubkey-algo @code{name}
2164 Never allow the use of @code{name} as public key algorithm.
2165 The given name will not be checked so that a later loaded algorithm
2166 will still get disabled.
2167
2168 @item --throw-keyids
2169 @itemx --no-throw-keyids
2170 Do not put the recipient key IDs into encrypted messages. This helps
2171 to hide the receivers of the message and is a limited countermeasure
2172 against traffic analysis. On the receiving side, it may slow down the
2173 decryption process because all available secret keys must be tried.
2174 @option{--no-throw-keyids} disables this option. This option is essentially
2175 the same as using @option{--hidden-recipient} for all recipients.
2176
2177 @item --not-dash-escaped
2178 This option changes the behavior of cleartext signatures
2179 so that they can be used for patch files. You should not
2180 send such an armored file via email because all spaces
2181 and line endings are hashed too. You can not use this
2182 option for data which has 5 dashes at the beginning of a
2183 line, patch files don't have this. A special armor header
2184 line tells GnuPG about this cleartext signature option.
2185
2186 @item --escape-from-lines
2187 @itemx --no-escape-from-lines
2188 Because some mailers change lines starting with "From " to ">From " it
2189 is good to handle such lines in a special way when creating cleartext
2190 signatures to prevent the mail system from breaking the signature. Note
2191 that all other PGP versions do it this way too.  Enabled by
2192 default. @option{--no-escape-from-lines} disables this option.
2193
2194 @item --passphrase-fd @code{n}
2195 Read the passphrase from file descriptor @code{n}. Only the first line
2196 will be read from file descriptor @code{n}. If you use 0 for @code{n},
2197 the passphrase will be read from stdin. This can only be used if only
2198 one passphrase is supplied.
2199 @ifclear gpgone
2200 Note that this passphrase is only used if the option @option{--batch}
2201 has also been given.  This is different from @command{gpg}.
2202 @end ifclear
2203
2204 @item --passphrase-file @code{file}
2205 Read the passphrase from file @code{file}. Only the first line will
2206 be read from file @code{file}. This can only be used if only one
2207 passphrase is supplied. Obviously, a passphrase stored in a file is
2208 of questionable security if other users can read this file. Don't use
2209 this option if you can avoid it.
2210 @ifclear gpgone
2211 Note that this passphrase is only used if the option @option{--batch}
2212 has also been given.  This is different from @command{gpg}.
2213 @end ifclear
2214
2215 @item --passphrase @code{string}
2216 Use @code{string} as the passphrase. This can only be used if only one
2217 passphrase is supplied. Obviously, this is of very questionable
2218 security on a multi-user system. Don't use this option if you can
2219 avoid it.
2220 @ifclear gpgone
2221 Note that this passphrase is only used if the option @option{--batch}
2222 has also been given.  This is different from @command{gpg}.
2223 @end ifclear
2224
2225 @item --command-fd @code{n}
2226 This is a replacement for the deprecated shared-memory IPC mode.
2227 If this option is enabled, user input on questions is not expected
2228 from the TTY but from the given file descriptor. It should be used
2229 together with @option{--status-fd}. See the file doc/DETAILS in the source
2230 distribution for details on how to use it.
2231
2232 @item --command-file @code{file}
2233 Same as @option{--command-fd}, except the commands are read out of file
2234 @code{file}
2235
2236 @item --allow-non-selfsigned-uid
2237 @itemx --no-allow-non-selfsigned-uid
2238 Allow the import and use of keys with user IDs which are not
2239 self-signed. This is not recommended, as a non self-signed user ID is
2240 trivial to forge. @option{--no-allow-non-selfsigned-uid} disables.
2241
2242 @item --allow-freeform-uid
2243 Disable all checks on the form of the user ID while generating a new
2244 one. This option should only be used in very special environments as
2245 it does not ensure the de-facto standard format of user IDs.
2246
2247 @item --ignore-time-conflict
2248 GnuPG normally checks that the timestamps associated with keys and
2249 signatures have plausible values. However, sometimes a signature
2250 seems to be older than the key due to clock problems. This option
2251 makes these checks just a warning. See also @option{--ignore-valid-from} for
2252 timestamp issues on subkeys.
2253
2254 @item --ignore-valid-from
2255 GnuPG normally does not select and use subkeys created in the future.
2256 This option allows the use of such keys and thus exhibits the
2257 pre-1.0.7 behaviour. You should not use this option unless you there
2258 is some clock problem. See also @option{--ignore-time-conflict} for timestamp
2259 issues with signatures.
2260
2261 @item --ignore-crc-error
2262 The ASCII armor used by OpenPGP is protected by a CRC checksum against
2263 transmission errors. Occasionally the CRC gets mangled somewhere on
2264 the transmission channel but the actual content (which is protected by
2265 the OpenPGP protocol anyway) is still okay. This option allows GnuPG
2266 to ignore CRC errors.
2267
2268 @item --ignore-mdc-error
2269 This option changes a MDC integrity protection failure into a warning.
2270 This can be useful if a message is partially corrupt, but it is
2271 necessary to get as much data as possible out of the corrupt message.
2272 However, be aware that a MDC protection failure may also mean that the
2273 message was tampered with intentionally by an attacker.
2274
2275 @item --no-default-keyring
2276 Do not add the default keyrings to the list of keyrings. Note that
2277 GnuPG will not operate without any keyrings, so if you use this option
2278 and do not provide alternate keyrings via @option{--keyring} or
2279 @option{--secret-keyring}, then GnuPG will still use the default public or
2280 secret keyrings.
2281
2282 @item --skip-verify
2283 Skip the signature verification step. This may be
2284 used to make the decryption faster if the signature
2285 verification is not needed.
2286
2287 @item --with-key-data
2288 Print key listings delimited by colons (like @option{--with-colons}) and
2289 print the public key data.
2290
2291 @item --fast-list-mode
2292 Changes the output of the list commands to work faster; this is achieved
2293 by leaving some parts empty. Some applications don't need the user ID
2294 and the trust information given in the listings. By using this options
2295 they can get a faster listing. The exact behaviour of this option may
2296 change in future versions.  If you are missing some information, don't
2297 use this option.
2298
2299 @item --no-literal
2300 This is not for normal use. Use the source to see for what it might be useful.
2301
2302 @item --set-filesize
2303 This is not for normal use. Use the source to see for what it might be useful.
2304
2305 @item --show-session-key
2306 Display the session key used for one message. See
2307 @option{--override-session-key} for the counterpart of this option.
2308
2309 We think that Key Escrow is a Bad Thing; however the user should have
2310 the freedom to decide whether to go to prison or to reveal the content
2311 of one specific message without compromising all messages ever
2312 encrypted for one secret key. DON'T USE IT UNLESS YOU ARE REALLY
2313 FORCED TO DO SO.
2314
2315 @item --override-session-key @code{string}
2316 Don't use the public key but the session key @code{string}. The format
2317 of this string is the same as the one printed by
2318 @option{--show-session-key}. This option is normally not used but comes
2319 handy in case someone forces you to reveal the content of an encrypted
2320 message; using this option you can do this without handing out the
2321 secret key.
2322
2323 @item --ask-sig-expire
2324 @itemx --no-ask-sig-expire
2325 When making a data signature, prompt for an expiration time. If this
2326 option is not specified, the expiration time set via
2327 @option{--default-sig-expire} is used. @option{--no-ask-sig-expire}
2328 disables this option. Note that by default, @option{--force-v3-sigs} is
2329 set which also disables this option. If you want signature expiration,
2330 you must set @option{--no-force-v3-sigs} as well as turning
2331 @option{--ask-sig-expire} on.
2332
2333 @item --default-sig-expire
2334 The default expiration time to use for signature expiration. Valid
2335 values are "0" for no expiration, a number followed by the letter d
2336 (for days), w (for weeks), m (for months), or y (for years) (for
2337 example "2m" for two months, or "5y" for five years), or an absolute
2338 date in the form YYYY-MM-DD. Defaults to "0".
2339
2340 @item --ask-cert-expire
2341 @itemx --no-ask-cert-expire
2342 When making a key signature, prompt for an expiration time. If this
2343 option is not specified, the expiration time set via
2344 @option{--default-cert-expire} is used. @option{--no-ask-cert-expire}
2345 disables this option.
2346
2347 @item --default-cert-expire
2348 The default expiration time to use for key signature expiration.
2349 Valid values are "0" for no expiration, a number followed by the
2350 letter d (for days), w (for weeks), m (for months), or y (for years)
2351 (for example "2m" for two months, or "5y" for five years), or an
2352 absolute date in the form YYYY-MM-DD. Defaults to "0".
2353
2354 @item --allow-secret-key-import
2355 This is an obsolete option and is not used anywhere.
2356
2357 @item --allow-multisig-verification
2358 Allow verification of concatenated signed messages. This will run a
2359 signature verification for each data+signature block. There are some
2360 security issues with this option and thus it is off by default. Note
2361 that versions of GPG prior to version 1.4.3 implicitly allowed this.
2362
2363 @item --enable-special-filenames
2364 This options enables a mode in which filenames of the form
2365 @file{-&n}, where n is a non-negative decimal number,
2366 refer to the file descriptor n and not to a file with that name.
2367
2368 @item --no-expensive-trust-checks
2369 Experimental use only.
2370
2371 @item --preserve-permissions
2372 Don't change the permissions of a secret keyring back to user
2373 read/write only. Use this option only if you really know what you are doing.
2374
2375 @item --default-preference-list @code{string}
2376 @opindex default-preference-list
2377 Set the list of default preferences to @code{string}. This preference
2378 list is used for new keys and becomes the default for "setpref" in the
2379 edit menu.
2380
2381 @item --default-keyserver-url @code{name}
2382 @opindex default-keyserver-url
2383 Set the default keyserver URL to @code{name}. This keyserver will be
2384 used as the keyserver URL when writing a new self-signature on a key,
2385 which includes key generation and changing preferences.
2386
2387 @item --list-config
2388 @opindex list-config
2389 Display various internal configuration parameters of GnuPG. This option
2390 is intended for external programs that call GnuPG to perform tasks, and
2391 is thus not generally useful. See the file @file{doc/DETAILS} in the
2392 source distribution for the details of which configuration items may be
2393 listed. @option{--list-config} is only usable with
2394 @option{--with-colons} set.
2395
2396 @end table
2397
2398 @c *******************************
2399 @c ******* Deprecated ************
2400 @c *******************************
2401 @subsection Deprecated options
2402
2403 @table @gnupgtabopt
2404
2405 @ifset gpgone
2406 @item --load-extension @code{name}
2407 Load an extension module. If @code{name} does not contain a slash it is
2408 searched for in the directory configured when GnuPG was built
2409 (generally "/usr/local/lib/gnupg"). Extensions are not generally
2410 useful anymore, and the use of this option is deprecated.
2411 @end ifset
2412
2413 @item --show-photos
2414 @itemx --no-show-photos
2415 Causes @option{--list-keys}, @option{--list-sigs},
2416 @option{--list-public-keys}, @option{--list-secret-keys}, and verifying
2417 a signature to also display the photo ID attached to the key, if
2418 any. See also @option{--photo-viewer}. These options are deprecated. Use
2419 @option{--list-options [no-]show-photos} and/or @option{--verify-options
2420 [no-]show-photos} instead.
2421
2422 @item --show-keyring
2423 Display the keyring name at the head of key listings to show which
2424 keyring a given key resides on. This option is deprecated: use
2425 @option{--list-options [no-]show-keyring} instead.
2426
2427 @item --ctapi-driver @code{file}
2428 Use @code{file} to access the smartcard reader. The current default
2429 is `libtowitoko.so'. Note that the use of this interface is
2430 deprecated; it may be removed in future releases.
2431
2432 @item --always-trust
2433 Identical to @option{--trust-model always}. This option is deprecated.
2434
2435 @item --show-notation
2436 @itemx --no-show-notation
2437 Show signature notations in the @option{--list-sigs} or @option{--check-sigs} listings
2438 as well as when verifying a signature with a notation in it. These
2439 options are deprecated. Use @option{--list-options [no-]show-notation}
2440 and/or @option{--verify-options [no-]show-notation} instead.
2441
2442 @item --show-policy-url
2443 @itemx --no-show-policy-url
2444 Show policy URLs in the @option{--list-sigs} or @option{--check-sigs}
2445 listings as well as when verifying a signature with a policy URL in
2446 it. These options are deprecated. Use @option{--list-options
2447 [no-]show-policy-url} and/or @option{--verify-options
2448 [no-]show-policy-url} instead.
2449
2450
2451 @end table
2452
2453
2454 @c *******************************************
2455 @c ***************            ****************
2456 @c ***************   FILES    ****************
2457 @c ***************            ****************
2458 @c *******************************************
2459 @mansect files
2460 @node GPG Configuration
2461 @section Configuration files
2462
2463 There are a few configuration files to control certain aspects of
2464 @command{@gpgname}'s operation. Unless noted, they are expected in the
2465 current home directory (@pxref{option --homedir}).
2466
2467 @table @file
2468
2469 @item gpg.conf
2470 @cindex gpgsm.conf
2471 This is the standard configuration file read by @command{@gpgname} on
2472 startup.  It may contain any valid long option; the leading two dashes
2473 may not be entered and the option may not be abbreviated.  This default
2474 name may be changed on the command line (@pxref{option
2475   --options}).
2476
2477 @end table
2478
2479 @c man:.RE
2480 Note that on larger installations, it is useful to put predefined files
2481 into the directory @file{/etc/skel/.gnupg/} so that newly created users
2482 start up with a working configuration.  For existing users the a small
2483 helper script is provided to create these files (@pxref{addgnupghome}).
2484
2485 For internal purposes @command{@gpgname} creates and maintaines a few other
2486 files; They all live in in the current home directory (@pxref{option
2487 --homedir}).  Only the @command{@gpgname} may modify these files.
2488
2489
2490 @table @file
2491 @item ~/.gnupg/secring.gpg
2492 The secret keyring.
2493
2494 @item ~/.gnupg/secring.gpg.lock
2495 and the lock file
2496
2497 @item ~/.gnupg/pubring.gpg
2498 The public keyring
2499
2500 @item ~/.gnupg/pubring.gpg.lock
2501 and the lock file
2502
2503 @item ~/.gnupg/trustdb.gpg
2504 The trust database
2505
2506 @item ~/.gnupg/trustdb.gpg.lock
2507 and the lock file
2508
2509 @item ~/.gnupg/random_seed
2510 used to preserve the internal random pool
2511
2512 @item /usr[/local]/share/gnupg/options.skel
2513 Skeleton options file
2514
2515 @item /usr[/local]/lib/gnupg/
2516 Default location for extensions
2517
2518 @end table
2519
2520 @c man:.RE
2521 Operation is further controlled by a few environment variables:
2522
2523 @table @asis
2524
2525 @item HOME
2526 Used to locate the default home directory.
2527
2528 @item GNUPGHOME
2529 If set directory used instead of "~/.gnupg".
2530
2531 @item GPG_AGENT_INFO
2532 Used to locate the gpg-agent.
2533 @ifset gpgone
2534 This is only honored when @option{--use-agent} is set.
2535 @end ifset
2536 The value consists of 3 colon delimited fields: The first is the path
2537 to the Unix Domain Socket, the second the PID of the gpg-agent and the
2538 protocol version which should be set to 1. When starting the gpg-agent
2539 as described in its documentation, this variable is set to the correct
2540 value. The option @option{--gpg-agent-info} can be used to override it.
2541
2542 @item COLUMNS
2543 @itemx LINES
2544 Used to size some displays to the full size of the screen.
2545
2546 @end table
2547
2548
2549 @c *******************************************
2550 @c ***************            ****************
2551 @c ***************  EXAMPLES  ****************
2552 @c ***************            ****************
2553 @c *******************************************
2554 @mansect examples
2555 @node GPG Examples
2556 @section Examples
2557
2558 @table @asis
2559
2560 @item gpg -se -r @code{Bob} @code{file}
2561 sign and encrypt for user Bob
2562
2563 @item gpg --clearsign @code{file}
2564 make a clear text signature
2565
2566 @item gpg -sb @code{file}
2567 make a detached signature
2568
2569 @item gpg --list-keys @code{user_ID}
2570 show keys
2571
2572 @item gpg --fingerprint @code{user_ID}
2573 show fingerprint
2574
2575 @item gpg --verify @code{pgpfile}
2576 @itemx gpg --verify @code{sigfile}
2577 Verify the signature of the file but do not output the data. The
2578 second form is used for detached signatures, where @code{sigfile}
2579 is the detached signature (either ASCII armored or binary) and
2580 are the signed data; if this is not given, the name of
2581 the file holding the signed data is constructed by cutting off the
2582 extension (".asc" or ".sig") of @code{sigfile} or by asking the
2583 user for the filename.
2584 @end table
2585
2586
2587 @c *******************************************
2588 @c ***************            ****************
2589 @c ***************  USER ID   ****************
2590 @c ***************            ****************
2591 @c *******************************************
2592 @mansect how to specify a user id
2593 @ifset isman
2594 @include specify-user-id.texi
2595 @end ifset
2596
2597 @mansect return vaue
2598 @chapheading RETURN VALUE
2599
2600 The program returns 0 if everything was fine, 1 if at least
2601 a signature was bad, and other error codes for fatal errors.
2602
2603 @mansect warnings
2604 @chapheading WARNINGS
2605
2606 Use a *good* password for your user account and a *good* passphrase
2607 to protect your secret key. This passphrase is the weakest part of the
2608 whole system. Programs to do dictionary attacks on your secret keyring
2609 are very easy to write and so you should protect your "~/.gnupg/"
2610 directory very well.
2611
2612 Keep in mind that, if this program is used over a network (telnet), it
2613 is *very* easy to spy out your passphrase!
2614
2615 If you are going to verify detached signatures, make sure that the
2616 program knows about it; either give both filenames on the command line
2617 or use @samp{-} to specify stdin.
2618
2619 @mansect interoperability
2620 @chapheading INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS
2621
2622 GnuPG tries to be a very flexible implementation of the OpenPGP
2623 standard. In particular, GnuPG implements many of the optional parts
2624 of the standard, such as the SHA-512 hash, and the ZLIB and BZIP2
2625 compression algorithms. It is important to be aware that not all
2626 OpenPGP programs implement these optional algorithms and that by
2627 forcing their use via the @option{--cipher-algo}, @option{--digest-algo},
2628 @option{--cert-digest-algo}, or @option{--compress-algo} options in GnuPG, it is
2629 possible to create a perfectly valid OpenPGP message, but one that
2630 cannot be read by the intended recipient.
2631
2632 There are dozens of variations of OpenPGP programs available, and each
2633 supports a slightly different subset of these optional algorithms.
2634 For example, until recently, no (unhacked) version of PGP supported
2635 the BLOWFISH cipher algorithm. A message using BLOWFISH simply could
2636 not be read by a PGP user. By default, GnuPG uses the standard
2637 OpenPGP preferences system that will always do the right thing and
2638 create messages that are usable by all recipients, regardless of which
2639 OpenPGP program they use. Only override this safe default if you
2640 really know what you are doing.
2641
2642 If you absolutely must override the safe default, or if the preferences
2643 on a given key are invalid for some reason, you are far better off using
2644 the @option{--pgp6}, @option{--pgp7}, or @option{--pgp8} options. These
2645 options are safe as they do not force any particular algorithms in
2646 violation of OpenPGP, but rather reduce the available algorithms to a
2647 "PGP-safe" list.
2648
2649 @mansect bugs
2650 @chapheading BUGS
2651
2652 On many systems this program should be installed as setuid(root). This
2653 is necessary to lock memory pages. Locking memory pages prevents the
2654 operating system from writing memory pages (which may contain
2655 passphrases or other sensitive material) to disk. If you get no
2656 warning message about insecure memory your operating system supports
2657 locking without being root. The program drops root privileges as soon
2658 as locked memory is allocated.
2659
2660 @mansect see also
2661 @ifset isman
2662 @command{gpgv}(1), 
2663 @command{gpgsm}(1), 
2664 @command{gpg-agent}(1)
2665 @end ifset
2666 @include see-also-note.texi