gpg: Improve UID selction of --quick-sign-key.
[gnupg.git] / doc / gpg.texi
1 @c Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
2 @c               2008, 2009, 2010 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 @include defs.inc
7
8 @node Invoking GPG
9 @chapter Invoking GPG
10 @cindex GPG command options
11 @cindex command options
12 @cindex options, GPG command
13
14
15 @c Begin standard stuff
16 @ifclear gpgtwohack
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 ifclear
35 @c End standard stuff
36
37 @c Begin gpg2 hack stuff
38 @ifset gpgtwohack
39 @manpage gpg2.1
40 @ifset manverb
41 .B gpg2
42 \- OpenPGP encryption and signing tool
43 @end ifset
44
45 @mansect synopsis
46 @ifset manverb
47 .B  gpg2
48 .RB [ \-\-homedir
49 .IR dir ]
50 .RB [ \-\-options
51 .IR file ]
52 .RI [ options ]
53 .I command
54 .RI [ args ]
55 @end ifset
56 @end ifset
57 @c End gpg2 hack stuff
58
59
60 @mansect description
61 @command{@gpgname} is the OpenPGP part of the GNU Privacy Guard (GnuPG). It
62 is a tool to provide digital encryption and signing services using the
63 OpenPGP standard. @command{@gpgname} features complete key management and
64 all bells and whistles you can expect from a decent OpenPGP
65 implementation.
66
67 @ifclear gpgtwohack
68 Note that this version of GnuPG features all modern algorithms and
69 should thus be preferred over older GnuPG versions.  If you are
70 looking for version 1 of GnuPG, you may find that version installed
71 under the name @command{gpg1}.
72 @end ifclear
73 @ifset gpgtwohack
74 In contrast to the standalone command gpg from GnuPG 1.x, which
75 might be better suited for server and embedded platforms, the 2.x
76 version is commonly installed under the name @command{@gpgname} and
77 targeted to the desktop as it requires several other modules to be
78 installed.
79 @end ifset
80
81 @manpause
82
83 @xref{Option Index}, for an index to @command{@gpgname}'s commands and options.
84 @mancont
85
86 @menu
87 * GPG Commands::            List of all commands.
88 * GPG Options::             List of all options.
89 * GPG Configuration::       Configuration files.
90 * GPG Examples::            Some usage examples.
91
92 Developer information:
93 * Unattended Usage of GPG:: Using @command{gpg} from other programs.
94 @end menu
95
96 @c * GPG Protocol::        The protocol the server mode uses.
97
98
99 @c *******************************************
100 @c ***************            ****************
101 @c ***************  COMMANDS  ****************
102 @c ***************            ****************
103 @c *******************************************
104 @mansect commands
105 @node GPG Commands
106 @section Commands
107
108 Commands are not distinguished from options except for the fact that
109 only one command is allowed.
110
111 @command{@gpgname} may be run with no commands, in which case it will
112 perform a reasonable action depending on the type of file it is given
113 as input (an encrypted message is decrypted, a signature is verified,
114 a file containing keys is listed).
115
116 Please remember that option as well as command parsing stops as soon as
117 a non-option is encountered, you can explicitly stop parsing by
118 using the special option @option{--}.
119
120
121 @menu
122 * General GPG Commands::        Commands not specific to the functionality.
123 * Operational GPG Commands::    Commands to select the type of operation.
124 * OpenPGP Key Management::      How to manage your keys.
125 @end menu
126
127
128 @c *******************************************
129 @c **********  GENERAL COMMANDS  *************
130 @c *******************************************
131 @node General GPG Commands
132 @subsection Commands not specific to the function
133
134 @table @gnupgtabopt
135 @item --version
136 @opindex version
137 Print the program version and licensing information.  Note that you
138 cannot abbreviate this command.
139
140 @item --help
141 @itemx -h
142 @opindex help
143 Print a usage message summarizing the most useful command line options.
144 Note that you cannot abbreviate this command.
145
146 @item --warranty
147 @opindex warranty
148 Print warranty information.
149
150 @item --dump-options
151 @opindex dump-options
152 Print a list of all available options and commands.  Note that you cannot
153 abbreviate this command.
154 @end table
155
156
157 @c *******************************************
158 @c ********  OPERATIONAL COMMANDS  ***********
159 @c *******************************************
160 @node Operational GPG Commands
161 @subsection Commands to select the type of operation
162
163
164 @table @gnupgtabopt
165
166 @item --sign
167 @itemx -s
168 @opindex sign
169 Make a signature. This command may be combined with @option{--encrypt}
170 (for a signed and encrypted message), @option{--symmetric} (for a
171 signed and symmetrically encrypted message), or @option{--encrypt} and
172 @option{--symmetric} together (for a signed message that may be
173 decrypted via a secret key or a passphrase).  The key to be used for
174 signing is chosen by default or can be set with the
175 @option{--local-user} and @option{--default-key} options.
176
177 @item --clearsign
178 @opindex clearsign
179 Make a clear text signature.  The content in a clear text signature is
180 readable without any special software. OpenPGP software is only needed
181 to verify the signature.  Clear text signatures may modify end-of-line
182 whitespace for platform independence and are not intended to be
183 reversible.  The key to be used for signing is chosen by default or
184 can be set with the @option{--local-user} and @option{--default-key}
185 options.
186
187
188 @item --detach-sign
189 @itemx -b
190 @opindex detach-sign
191 Make a detached signature.
192
193 @item --encrypt
194 @itemx -e
195 @opindex encrypt
196 Encrypt data. This option may be combined with @option{--sign} (for a
197 signed and encrypted message), @option{--symmetric} (for a message that
198 may be decrypted via a secret key or a passphrase), or @option{--sign}
199 and @option{--symmetric} together (for a signed message that may be
200 decrypted via a secret key or a passphrase).
201
202 @item --symmetric
203 @itemx -c
204 @opindex symmetric
205 Encrypt with a symmetric cipher using a passphrase. The default
206 symmetric cipher used is @value{GPGSYMENCALGO}, but may be chosen with the
207 @option{--cipher-algo} option. This option may be combined with
208 @option{--sign} (for a signed and symmetrically encrypted message),
209 @option{--encrypt} (for a message that may be decrypted via a secret key
210 or a passphrase), or @option{--sign} and @option{--encrypt} together
211 (for a signed message that may be decrypted via a secret key or a
212 passphrase).
213
214 @item --store
215 @opindex store
216 Store only (make a simple literal data packet).
217
218 @item --decrypt
219 @itemx -d
220 @opindex decrypt
221 Decrypt the file given on the command line (or STDIN if no file
222 is specified) and write it to STDOUT (or the file specified with
223 @option{--output}). If the decrypted file is signed, the signature is also
224 verified. This command differs from the default operation, as it never
225 writes to the filename which is included in the file and it rejects
226 files which don't begin with an encrypted message.
227
228 @item --verify
229 @opindex verify
230 Assume that the first argument is a signed file and verify it without
231 generating any output.  With no arguments, the signature packet is
232 read from STDIN.  If only a one argument is given, it is expected to
233 be a complete signature.
234
235 With more than 1 argument, the first should be a detached signature
236 and the remaining files ake up the the signed data. To read the signed
237 data from STDIN, use @samp{-} as the second filename.  For security
238 reasons a detached signature cannot read the signed material from
239 STDIN without denoting it in the above way.
240
241 Note: If the option @option{--batch} is not used, @command{@gpgname}
242 may assume that a single argument is a file with a detached signature
243 and it will try to find a matching data file by stripping certain
244 suffixes.  Using this historical feature to verify a detached
245 signature is strongly discouraged; always specify the data file too.
246
247 Note: When verifying a cleartext signature, @command{gpg} verifies
248 only what makes up the cleartext signed data and not any extra data
249 outside of the cleartext signature or header lines following directly
250 the dash marker line.  The option @code{--output} may be used to write
251 out the actual signed data; but there are other pitfalls with this
252 format as well.  It is suggested to avoid cleartext signatures in
253 favor of detached signatures.
254
255 @item --multifile
256 @opindex multifile
257 This modifies certain other commands to accept multiple files for
258 processing on the command line or read from STDIN with each filename on
259 a separate line. This allows for many files to be processed at
260 once. @option{--multifile} may currently be used along with
261 @option{--verify}, @option{--encrypt}, and @option{--decrypt}. Note that
262 @option{--multifile --verify} may not be used with detached signatures.
263
264 @item --verify-files
265 @opindex verify-files
266 Identical to @option{--multifile --verify}.
267
268 @item --encrypt-files
269 @opindex encrypt-files
270 Identical to @option{--multifile --encrypt}.
271
272 @item --decrypt-files
273 @opindex decrypt-files
274 Identical to @option{--multifile --decrypt}.
275
276 @item --list-keys
277 @itemx -k
278 @itemx --list-public-keys
279 @opindex list-keys
280 List all keys from the public keyrings, or just the keys given on the
281 command line.
282
283 Avoid using the output of this command in scripts or other programs as
284 it is likely to change as GnuPG changes. See @option{--with-colons} for a
285 machine-parseable key listing command that is appropriate for use in
286 scripts and other programs.
287
288 @item --list-secret-keys
289 @itemx -K
290 @opindex list-secret-keys
291 List all keys from the secret keyrings, or just the ones given on the
292 command line. A @code{#} after the letters @code{sec} means that the
293 secret key is not usable (for example, if it was created via
294 @option{--export-secret-subkeys}).
295
296 @item --list-sigs
297 @opindex list-sigs
298 Same as @option{--list-keys}, but the signatures are listed too.
299 This command has the same effect as
300 using @option{--list-keys} with @option{--with-sig-list}.
301
302 For each signature listed, there are several flags in between the "sig"
303 tag and keyid. These flags give additional information about each
304 signature. From left to right, they are the numbers 1-3 for certificate
305 check level (see @option{--ask-cert-level}), "L" for a local or
306 non-exportable signature (see @option{--lsign-key}), "R" for a
307 nonRevocable signature (see the @option{--edit-key} command "nrsign"),
308 "P" for a signature that contains a policy URL (see
309 @option{--cert-policy-url}), "N" for a signature that contains a
310 notation (see @option{--cert-notation}), "X" for an eXpired signature
311 (see @option{--ask-cert-expire}), and the numbers 1-9 or "T" for 10 and
312 above to indicate trust signature levels (see the @option{--edit-key}
313 command "tsign").
314
315 @item --check-sigs
316 @opindex check-sigs
317 Same as @option{--list-sigs}, but the signatures are verified.  Note
318 that for performance reasons the revocation status of a signing key is
319 not shown.
320 This command has the same effect as
321 using @option{--list-keys} with @option{--with-sig-check}.
322
323 The status of the verification is indicated by a flag directly following
324 the "sig" tag (and thus before the flags described above for
325 @option{--list-sigs}).  A "!" indicates that the signature has been
326 successfully verified, a "-" denotes a bad signature and a "%" is used
327 if an error occurred while checking the signature (e.g. a non supported
328 algorithm).
329
330 @item --locate-keys
331 @opindex locate-keys
332 Locate the keys given as arguments.  This command basically uses the
333 same algorithm as used when locating keys for encryption or signing and
334 may thus be used to see what keys @command{@gpgname} might use.  In
335 particular external methods as defined by @option{--auto-key-locate} may
336 be used to locate a key.  Only public keys are listed.
337
338 @item --fingerprint
339 @opindex fingerprint
340 List all keys (or the specified ones) along with their
341 fingerprints. This is the same output as @option{--list-keys} but with
342 the additional output of a line with the fingerprint. May also be
343 combined with @option{--list-sigs} or @option{--check-sigs}.  If this
344 command is given twice, the fingerprints of all secondary keys are
345 listed too.
346
347 @item --list-packets
348 @opindex list-packets
349 List only the sequence of packets. This is mainly useful for
350 debugging.  When used with option @option{--verbose} the actual MPI
351 values are dumped and not only their lengths.
352
353
354 @item --card-edit
355 @opindex card-edit
356 Present a menu to work with a smartcard. The subcommand "help" provides
357 an overview on available commands. For a detailed description, please
358 see the Card HOWTO at
359 https://gnupg.org/documentation/howtos.html#GnuPG-cardHOWTO .
360
361 @item --card-status
362 @opindex card-status
363 Show the content of the smart card.
364
365 @item --change-pin
366 @opindex change-pin
367 Present a menu to allow changing the PIN of a smartcard. This
368 functionality is also available as the subcommand "passwd" with the
369 @option{--card-edit} command.
370
371 @item --delete-keys @code{name}
372 @itemx --delete-keys @code{name}
373 Remove key from the public keyring. In batch mode either @option{--yes} is
374 required or the key must be specified by fingerprint. This is a
375 safeguard against accidental deletion of multiple keys.
376
377 @item --delete-secret-keys @code{name}
378 @opindex delete-secret-keys
379 Remove key from the secret keyring. In batch mode the key
380 must be specified by fingerprint.
381
382 @item --delete-secret-and-public-key @code{name}
383 @opindex delete-secret-and-public-key
384 Same as @option{--delete-key}, but if a secret key exists, it will be
385 removed first. In batch mode the key must be specified by fingerprint.
386
387 @item --export
388 @opindex export
389 Either export all keys from all keyrings (default keyrings and those
390 registered via option @option{--keyring}), or if at least one name is given,
391 those of the given name. The exported keys are written to STDOUT or to the
392 file given with option @option{--output}.  Use together with
393 @option{--armor} to mail those keys.
394
395 @item --send-keys @code{key IDs}
396 @opindex send-keys
397 Similar to @option{--export} but sends the keys to a keyserver.
398 Fingerprints may be used instead of key IDs. Option @option{--keyserver}
399 must be used to give the name of this keyserver. Don't send your
400 complete keyring to a keyserver --- select only those keys which are new
401 or changed by you.  If no key IDs are given, @command{gpg} does nothing.
402
403 @item --export-secret-keys
404 @itemx --export-secret-subkeys
405 @opindex export-secret-keys
406 @opindex export-secret-subkeys
407 Same as @option{--export}, but exports the secret keys instead.  The
408 exported keys are written to STDOUT or to the file given with option
409 @option{--output}.  This command is often used along with the option
410 @option{--armor} to allow easy printing of the key for paper backup;
411 however the external tool @command{paperkey} does a better job for
412 creating backups on paper.  Note that exporting a secret key can be a
413 security risk if the exported keys are send over an insecure channel.
414
415 The second form of the command has the special property to render the
416 secret part of the primary key useless; this is a GNU extension to
417 OpenPGP and other implementations can not be expected to successfully
418 import such a key.  Its intended use is to generated a full key with
419 an additional signing subkey on a dedicated machine and then using
420 this command to export the key without the primary key to the main
421 machine.
422
423 GnuPG may ask you to enter the passphrase for the key.  This is
424 required because the internal protection method of the secret key is
425 different from the one specified by the OpenPGP protocol.
426
427 @item --export-ssh-key
428 @opindex export-ssh-key
429 This command is used to export a key in the OpenSSH public key format.
430 It requires the specification of one key by the usual means and
431 exports the latest valid subkey which has an authentication capability
432 to STDOUT or to the file given with option @option{--output}.  That
433 output can directly be added to ssh's @file{authorized_key} file.
434
435 By specifying the key to export using a key ID or a fingerprint
436 suffixed with an exclamation mark (!), a specific subkey or the
437 primary key can be exported.  This does not even require that the key
438 has the authentication capability flag set.
439
440 @item --import
441 @itemx --fast-import
442 @opindex import
443 Import/merge keys. This adds the given keys to the
444 keyring. The fast version is currently just a synonym.
445
446 There are a few other options which control how this command works.
447 Most notable here is the @option{--import-options merge-only} option
448 which does not insert new keys but does only the merging of new
449 signatures, user-IDs and subkeys.
450
451 @item --recv-keys @code{key IDs}
452 @opindex recv-keys
453 Import the keys with the given key IDs from a keyserver. Option
454 @option{--keyserver} must be used to give the name of this keyserver.
455
456 @item --refresh-keys
457 @opindex refresh-keys
458 Request updates from a keyserver for keys that already exist on the
459 local keyring. This is useful for updating a key with the latest
460 signatures, user IDs, etc. Calling this with no arguments will refresh
461 the entire keyring. Option @option{--keyserver} must be used to give the
462 name of the keyserver for all keys that do not have preferred keyservers
463 set (see @option{--keyserver-options honor-keyserver-url}).
464
465 @item --search-keys @code{names}
466 @opindex search-keys
467 Search the keyserver for the given names. Multiple names given here will
468 be joined together to create the search string for the keyserver.
469 Option @option{--keyserver} must be used to give the name of this
470 keyserver.  Keyservers that support different search methods allow using
471 the syntax specified in "How to specify a user ID" below. Note that
472 different keyserver types support different search methods. Currently
473 only LDAP supports them all.
474
475 @item --fetch-keys @code{URIs}
476 @opindex fetch-keys
477 Retrieve keys located at the specified URIs. Note that different
478 installations of GnuPG may support different protocols (HTTP, FTP,
479 LDAP, etc.)
480
481 @item --update-trustdb
482 @opindex update-trustdb
483 Do trust database maintenance. This command iterates over all keys and
484 builds the Web of Trust. This is an interactive command because it may
485 have to ask for the "ownertrust" values for keys. The user has to give
486 an estimation of how far she trusts the owner of the displayed key to
487 correctly certify (sign) other keys. GnuPG only asks for the ownertrust
488 value if it has not yet been assigned to a key. Using the
489 @option{--edit-key} menu, the assigned value can be changed at any time.
490
491 @item --check-trustdb
492 @opindex check-trustdb
493 Do trust database maintenance without user interaction. From time to
494 time the trust database must be updated so that expired keys or
495 signatures and the resulting changes in the Web of Trust can be
496 tracked. Normally, GnuPG will calculate when this is required and do it
497 automatically unless @option{--no-auto-check-trustdb} is set. This
498 command can be used to force a trust database check at any time. The
499 processing is identical to that of @option{--update-trustdb} but it
500 skips keys with a not yet defined "ownertrust".
501
502 For use with cron jobs, this command can be used together with
503 @option{--batch} in which case the trust database check is done only if
504 a check is needed. To force a run even in batch mode add the option
505 @option{--yes}.
506
507 @anchor{option --export-ownertrust}
508 @item --export-ownertrust
509 @opindex export-ownertrust
510 Send the ownertrust values to STDOUT. This is useful for backup purposes
511 as these values are the only ones which can't be re-created from a
512 corrupted trustdb.  Example:
513 @c man:.RS
514 @example
515   @gpgname{} --export-ownertrust > otrust.txt
516 @end example
517 @c man:.RE
518
519
520 @item --import-ownertrust
521 @opindex import-ownertrust
522 Update the trustdb with the ownertrust values stored in @code{files} (or
523 STDIN if not given); existing values will be overwritten.  In case of a
524 severely damaged trustdb and if you have a recent backup of the
525 ownertrust values (e.g. in the file @file{otrust.txt}, you may re-create
526 the trustdb using these commands:
527 @c man:.RS
528 @example
529   cd ~/.gnupg
530   rm trustdb.gpg
531   @gpgname{} --import-ownertrust < otrust.txt
532 @end example
533 @c man:.RE
534
535
536 @item --rebuild-keydb-caches
537 @opindex rebuild-keydb-caches
538 When updating from version 1.0.6 to 1.0.7 this command should be used
539 to create signature caches in the keyring. It might be handy in other
540 situations too.
541
542 @item --print-md @code{algo}
543 @itemx --print-mds
544 @opindex print-md
545 Print message digest of algorithm ALGO for all given files or STDIN.
546 With the second form (or a deprecated "*" as algo) digests for all
547 available algorithms are printed.
548
549 @item --gen-random @code{0|1|2} @code{count}
550 @opindex gen-random
551 Emit @var{count} random bytes of the given quality level 0, 1 or 2. If
552 @var{count} is not given or zero, an endless sequence of random bytes
553 will be emitted.  If used with @option{--armor} the output will be
554 base64 encoded.  PLEASE, don't use this command unless you know what
555 you are doing; it may remove precious entropy from the system!
556
557 @item --gen-prime @code{mode}  @code{bits}
558 @opindex gen-prime
559 Use the source, Luke :-). The output format is still subject to change.
560
561
562 @item --enarmor
563 @item --dearmor
564 @opindex enarmor
565 @opindex dearmor
566 Pack or unpack an arbitrary input into/from an OpenPGP ASCII armor.
567 This is a GnuPG extension to OpenPGP and in general not very useful.
568
569 @item --tofu-set-policy @code{auto|good|unknown|bad|ask}  @code{key...}
570 @opindex tofu-set-policy
571 Set the TOFU policy for all the bindings associated with the specified
572 keys.  For more information about the meaning of the policies,
573 @pxref{trust-model-tofu}.  The keys may be specified either by their
574 fingerprint (preferred) or their keyid.
575
576 @c @item --server
577 @c @opindex server
578 @c Run gpg in server mode.  This feature is not yet ready for use and
579 @c thus not documented.
580
581 @end table
582
583
584 @c *******************************************
585 @c *******  KEY MANGEMENT COMMANDS  **********
586 @c *******************************************
587 @node OpenPGP Key Management
588 @subsection How to manage your keys
589
590 This section explains the main commands for key management
591
592 @table @gnupgtabopt
593
594 @item --quick-gen-key @code{user-id}
595 @opindex quick-gen-key
596 This is a simple command to generate a standard key with one user id.
597 In contrast to @option{--gen-key} the key is generated directly
598 without the need to answer a bunch of prompts.  Unless the option
599 @option{--yes} is given, the key creation will be canceled if the
600 given user id already exists in the key ring.
601
602 If invoked directly on the console without any special options an
603 answer to a ``Continue?'' style confirmation prompt is required.  In
604 case the user id already exists in the key ring a second prompt to
605 force the creation of the key will show up.
606
607 If this command is used with @option{--batch},
608 @option{--pinentry-mode} has been set to @code{loopback}, and one of
609 the passphrase options (@option{--passphrase},
610 @option{--passphrase-fd}, or @option{passphrase-file}) is used, the
611 supplied passphrase is used for the new key and the agent does not ask
612 for it.  To create a key without any protection @code{--passphrase ''}
613 may be used.
614
615 @item --gen-key
616 @opindex gen-key
617 Generate a new key pair using the current default parameters.  This is
618 the standard command to create a new key.  In addition to the key a
619 revocation certificate is created and stored in the
620 @file{openpgp-revocs.d} directory below the GnuPG home directory.
621
622 @item --full-gen-key
623 @opindex gen-key
624 Generate a new key pair with dialogs for all options.  This is an
625 extended version of @option{--gen-key}.
626
627 There is also a feature which allows you to create keys in batch
628 mode. See the manual section ``Unattended key generation'' on how
629 to use this.
630
631 @item --gen-revoke @code{name}
632 @opindex gen-revoke
633 Generate a revocation certificate for the complete key.  To only revoke
634 a subkey or a key signature, use the @option{--edit} command.
635
636 This command merely creates the revocation certificate so that it can
637 be used to revoke the key if that is ever needed.  To actually revoke
638 a key the created revocation certificate needs to be merged with the
639 key to revoke.  This is done by importing the revocation certificate
640 using the @option{--import} command.  Then the revoked key needs to be
641 published, which is best done by sending the key to a keyserver
642 (command @option{--send-key}) and by exporting (@option{--export}) it
643 to a file which is then send to frequent communication partners.
644
645
646 @item --desig-revoke @code{name}
647 @opindex desig-revoke
648 Generate a designated revocation certificate for a key. This allows a
649 user (with the permission of the keyholder) to revoke someone else's
650 key.
651
652
653 @item --edit-key
654 @opindex edit-key
655 Present a menu which enables you to do most of the key management
656 related tasks.  It expects the specification of a key on the command
657 line.
658
659 @c ******** Begin Edit-key Options **********
660 @table @asis
661
662   @item uid @code{n}
663   @opindex keyedit:uid
664   Toggle selection of user ID or photographic user ID with index @code{n}.
665   Use @code{*} to select all and @code{0} to deselect all.
666
667   @item key @code{n}
668   @opindex keyedit:key
669   Toggle selection of subkey with index @code{n} or key ID @code{n}.
670   Use @code{*} to select all and @code{0} to deselect all.
671
672   @item sign
673   @opindex keyedit:sign
674   Make a signature on key of user @code{name} If the key is not yet
675   signed by the default user (or the users given with -u), the program
676   displays the information of the key again, together with its
677   fingerprint and asks whether it should be signed. This question is
678   repeated for all users specified with
679   -u.
680
681   @item lsign
682   @opindex keyedit:lsign
683   Same as "sign" but the signature is marked as non-exportable and will
684   therefore never be used by others. This may be used to make keys
685   valid only in the local environment.
686
687   @item nrsign
688   @opindex keyedit:nrsign
689   Same as "sign" but the signature is marked as non-revocable and can
690   therefore never be revoked.
691
692   @item tsign
693   @opindex keyedit:tsign
694   Make a trust signature. This is a signature that combines the notions
695   of certification (like a regular signature), and trust (like the
696   "trust" command). It is generally only useful in distinct communities
697   or groups.  For more information please read the sections
698   ``Trust Signature'' and ``Regular Expression'' in RFC-4880.
699 @end table
700
701 @c man:.RS
702 Note that "l" (for local / non-exportable), "nr" (for non-revocable,
703 and "t" (for trust) may be freely mixed and prefixed to "sign" to
704 create a signature of any type desired.
705 @c man:.RE
706
707 If the option @option{--only-sign-text-ids} is specified, then any
708 non-text based user ids (e.g., photo IDs) will not be selected for
709 signing.
710
711 @table @asis
712
713   @item delsig
714   @opindex keyedit:delsig
715   Delete a signature. Note that it is not possible to retract a signature,
716   once it has been send to the public (i.e. to a keyserver).  In that case
717   you better use @code{revsig}.
718
719   @item revsig
720   @opindex keyedit:revsig
721   Revoke a signature. For every signature which has been generated by
722   one of the secret keys, GnuPG asks whether a revocation certificate
723   should be generated.
724
725   @item check
726   @opindex keyedit:check
727   Check the signatures on all selected user IDs.  With the extra
728   option @code{selfsig} only self-signatures are shown.
729
730   @item adduid
731   @opindex keyedit:adduid
732   Create an additional user ID.
733
734   @item addphoto
735   @opindex keyedit:addphoto
736   Create a photographic user ID. This will prompt for a JPEG file that
737   will be embedded into the user ID. Note that a very large JPEG will make
738   for a very large key. Also note that some programs will display your
739   JPEG unchanged (GnuPG), and some programs will scale it to fit in a
740   dialog box (PGP).
741
742   @item showphoto
743   @opindex keyedit:showphoto
744   Display the selected photographic user ID.
745
746   @item deluid
747   @opindex keyedit:deluid
748   Delete a user ID or photographic user ID.  Note that it is not
749   possible to retract a user id, once it has been send to the public
750   (i.e. to a keyserver).  In that case you better use @code{revuid}.
751
752   @item revuid
753   @opindex keyedit:revuid
754   Revoke a user ID or photographic user ID.
755
756   @item primary
757   @opindex keyedit:primary
758   Flag the current user id as the primary one, removes the primary user
759   id flag from all other user ids and sets the timestamp of all affected
760   self-signatures one second ahead. Note that setting a photo user ID
761   as primary makes it primary over other photo user IDs, and setting a
762   regular user ID as primary makes it primary over other regular user
763   IDs.
764
765   @item keyserver
766   @opindex keyedit:keyserver
767   Set a preferred keyserver for the specified user ID(s). This allows
768   other users to know where you prefer they get your key from. See
769   @option{--keyserver-options honor-keyserver-url} for more on how this
770   works.  Setting a value of "none" removes an existing preferred
771   keyserver.
772
773   @item notation
774   @opindex keyedit:notation
775   Set a name=value notation for the specified user ID(s). See
776   @option{--cert-notation} for more on how this works. Setting a value of
777   "none" removes all notations, setting a notation prefixed with a minus
778   sign (-) removes that notation, and setting a notation name (without the
779   =value) prefixed with a minus sign removes all notations with that name.
780
781   @item pref
782   @opindex keyedit:pref
783   List preferences from the selected user ID. This shows the actual
784   preferences, without including any implied preferences.
785
786   @item showpref
787   @opindex keyedit:showpref
788   More verbose preferences listing for the selected user ID. This shows
789   the preferences in effect by including the implied preferences of 3DES
790   (cipher), SHA-1 (digest), and Uncompressed (compression) if they are
791   not already included in the preference list. In addition, the
792   preferred keyserver and signature notations (if any) are shown.
793
794   @item setpref @code{string}
795   @opindex keyedit:setpref
796   Set the list of user ID preferences to @code{string} for all (or just
797   the selected) user IDs. Calling setpref with no arguments sets the
798   preference list to the default (either built-in or set via
799   @option{--default-preference-list}), and calling setpref with "none"
800   as the argument sets an empty preference list. Use @command{@gpgname
801   --version} to get a list of available algorithms. Note that while you
802   can change the preferences on an attribute user ID (aka "photo ID"),
803   GnuPG does not select keys via attribute user IDs so these preferences
804   will not be used by GnuPG.
805
806   When setting preferences, you should list the algorithms in the order
807   which you'd like to see them used by someone else when encrypting a
808   message to your key.  If you don't include 3DES, it will be
809   automatically added at the end.  Note that there are many factors that
810   go into choosing an algorithm (for example, your key may not be the
811   only recipient), and so the remote OpenPGP application being used to
812   send to you may or may not follow your exact chosen order for a given
813   message.  It will, however, only choose an algorithm that is present
814   on the preference list of every recipient key.  See also the
815   INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS section below.
816
817   @item addkey
818   @opindex keyedit:addkey
819   Add a subkey to this key.
820
821   @item addcardkey
822   @opindex keyedit:addcardkey
823   Generate a subkey on a card and add it to this key.
824
825   @item keytocard
826   @opindex keyedit:keytocard
827   Transfer the selected secret subkey (or the primary key if no subkey
828   has been selected) to a smartcard. The secret key in the keyring will
829   be replaced by a stub if the key could be stored successfully on the
830   card and you use the save command later. Only certain key types may be
831   transferred to the card. A sub menu allows you to select on what card
832   to store the key. Note that it is not possible to get that key back
833   from the card - if the card gets broken your secret key will be lost
834   unless you have a backup somewhere.
835
836   @item bkuptocard @code{file}
837   @opindex keyedit:bkuptocard
838   Restore the given file to a card. This command may be used to restore a
839   backup key (as generated during card initialization) to a new card. In
840   almost all cases this will be the encryption key. You should use this
841   command only with the corresponding public key and make sure that the
842   file given as argument is indeed the backup to restore. You should then
843   select 2 to restore as encryption key.  You will first be asked to enter
844   the passphrase of the backup key and then for the Admin PIN of the card.
845
846   @item delkey
847   @opindex keyedit:delkey
848   Remove a subkey (secondary key). Note that it is not possible to retract
849   a subkey, once it has been send to the public (i.e. to a keyserver).  In
850   that case you better use @code{revkey}.
851
852   @item revkey
853   @opindex keyedit:revkey
854   Revoke a subkey.
855
856   @item expire
857   @opindex keyedit:expire
858   Change the key or subkey expiration time. If a subkey is selected, the
859   expiration time of this subkey will be changed. With no selection, the
860   key expiration of the primary key is changed.
861
862   @item trust
863   @opindex keyedit:trust
864   Change the owner trust value for the key. This updates the trust-db
865   immediately and no save is required.
866
867   @item disable
868   @itemx enable
869   @opindex keyedit:disable
870   @opindex keyedit:enable
871   Disable or enable an entire key. A disabled key can not normally be
872   used for encryption.
873
874   @item addrevoker
875   @opindex keyedit:addrevoker
876   Add a designated revoker to the key. This takes one optional argument:
877   "sensitive". If a designated revoker is marked as sensitive, it will
878   not be exported by default (see export-options).
879
880   @item passwd
881   @opindex keyedit:passwd
882   Change the passphrase of the secret key.
883
884   @item toggle
885   @opindex keyedit:toggle
886   This is dummy command which exists only for backward compatibility.
887
888   @item clean
889   @opindex keyedit:clean
890   Compact (by removing all signatures except the selfsig) any user ID
891   that is no longer usable (e.g. revoked, or expired). Then, remove any
892   signatures that are not usable by the trust calculations.
893   Specifically, this removes any signature that does not validate, any
894   signature that is superseded by a later signature, revoked signatures,
895   and signatures issued by keys that are not present on the keyring.
896
897   @item minimize
898   @opindex keyedit:minimize
899   Make the key as small as possible. This removes all signatures from
900   each user ID except for the most recent self-signature.
901
902   @item cross-certify
903   @opindex keyedit:cross-certify
904   Add cross-certification signatures to signing subkeys that may not
905   currently have them. Cross-certification signatures protect against a
906   subtle attack against signing subkeys. See
907   @option{--require-cross-certification}.  All new keys generated have
908   this signature by default, so this option is only useful to bring
909   older keys up to date.
910
911   @item save
912   @opindex keyedit:save
913   Save all changes to the key rings and quit.
914
915   @item quit
916   @opindex keyedit:quit
917   Quit the program without updating the
918   key rings.
919 @end table
920
921 @c man:.RS
922 The listing shows you the key with its secondary keys and all user
923 ids.  The primary user id is indicated by a dot, and selected keys or
924 user ids are indicated by an asterisk.  The trust
925 value is displayed with the primary key: the first is the assigned owner
926 trust and the second is the calculated trust value. Letters are used for
927 the values:
928 @c man:.RE
929
930 @table @asis
931
932   @item -
933   No ownertrust assigned / not yet calculated.
934
935   @item e
936   Trust
937   calculation has failed; probably due to an expired key.
938
939   @item q
940   Not enough information for calculation.
941
942   @item n
943   Never trust this key.
944
945   @item m
946   Marginally trusted.
947
948   @item f
949   Fully trusted.
950
951   @item u
952   Ultimately trusted.
953
954 @end table
955 @c ******** End Edit-key Options **********
956
957 @item --sign-key @code{name}
958 @opindex sign-key
959 Signs a public key with your secret key. This is a shortcut version of
960 the subcommand "sign" from @option{--edit}.
961
962 @item --lsign-key @code{name}
963 @opindex lsign-key
964 Signs a public key with your secret key but marks it as
965 non-exportable. This is a shortcut version of the subcommand "lsign"
966 from @option{--edit-key}.
967
968 @item --quick-sign-key @code{fpr} [@code{names}]
969 @itemx --quick-lsign-key @code{fpr} [@code{names}]
970 @opindex quick-sign-key
971 @opindex quick-lsign-key
972 Directly sign a key from the passphrase without any further user
973 interaction.  The @code{fpr} must be the verified primary fingerprint
974 of a key in the local keyring. If no @code{names} are given, all
975 useful user ids are signed; with given [@code{names}] only useful user
976 ids matching one of theses names are signed.  By default, or if a name
977 is prefixed with a '*', a case insensitive substring match is used.
978 If a name is prefixed with a '=' a case sensitive exact match is done.
979
980 The command @option{--quick-lsign-key} marks the signatures as
981 non-exportable.  If such a non-exportable signature already exists the
982 @option{--quick-sign-key} turns it into a exportable signature.
983
984 This command uses reasonable defaults and thus does not provide the
985 full flexibility of the "sign" subcommand from @option{--edit-key}.
986 Its intended use is to help unattended key signing by utilizing a list
987 of verified fingerprints.
988
989 @item --quick-adduid  @var{user-id} @var{new-user-id}
990 @opindex quick-adduid
991 This command adds a new user id to an existing key.  In contrast to
992 the interactive sub-command @code{adduid} of @option{--edit-key} the
993 @var{new-user-id} is added verbatim with only leading and trailing
994 white space removed, it is expected to be UTF-8 encoded, and no checks
995 on its form are applied.
996
997 @item --passwd @var{user_id}
998 @opindex passwd
999 Change the passphrase of the secret key belonging to the certificate
1000 specified as @var{user_id}.  This is a shortcut for the sub-command
1001 @code{passwd} of the edit key menu.
1002
1003 @end table
1004
1005
1006 @c *******************************************
1007 @c ***************            ****************
1008 @c ***************  OPTIONS   ****************
1009 @c ***************            ****************
1010 @c *******************************************
1011 @mansect options
1012 @node GPG Options
1013 @section Option Summary
1014
1015 @command{@gpgname} features a bunch of options to control the exact
1016 behaviour and to change the default configuration.
1017
1018 @menu
1019 * GPG Configuration Options::   How to change the configuration.
1020 * GPG Key related Options::     Key related options.
1021 * GPG Input and Output::        Input and Output.
1022 * OpenPGP Options::             OpenPGP protocol specific options.
1023 * Compliance Options::          Compliance options.
1024 * GPG Esoteric Options::        Doing things one usually don't want to do.
1025 * Deprecated Options::          Deprecated options.
1026 @end menu
1027
1028 Long options can be put in an options file (default
1029 "~/.gnupg/gpg.conf"). Short option names will not work - for example,
1030 "armor" is a valid option for the options file, while "a" is not. Do not
1031 write the 2 dashes, but simply the name of the option and any required
1032 arguments. Lines with a hash ('#') as the first non-white-space
1033 character are ignored. Commands may be put in this file too, but that is
1034 not generally useful as the command will execute automatically with
1035 every execution of gpg.
1036
1037 Please remember that option parsing stops as soon as a non-option is
1038 encountered, you can explicitly stop parsing by using the special option
1039 @option{--}.
1040
1041 @c *******************************************
1042 @c ********  CONFIGURATION OPTIONS  **********
1043 @c *******************************************
1044 @node GPG Configuration Options
1045 @subsection How to change the configuration
1046
1047 These options are used to change the configuration and are usually found
1048 in the option file.
1049
1050 @table @gnupgtabopt
1051
1052 @item --default-key @var{name}
1053 @opindex default-key
1054 Use @var{name} as the default key to sign with. If this option is not
1055 used, the default key is the first key found in the secret keyring.
1056 Note that @option{-u} or @option{--local-user} overrides this option.
1057 This option may be given multiple times.  In this case, the last key
1058 for which a secret key is available is used.  If there is no secret
1059 key available for any of the specified values, GnuPG will not emit an
1060 error message but continue as if this option wasn't given.
1061
1062 @item --default-recipient @var{name}
1063 @opindex default-recipient
1064 Use @var{name} as default recipient if option @option{--recipient} is
1065 not used and don't ask if this is a valid one. @var{name} must be
1066 non-empty.
1067
1068 @item --default-recipient-self
1069 @opindex default-recipient-self
1070 Use the default key as default recipient if option @option{--recipient} is not
1071 used and don't ask if this is a valid one. The default key is the first
1072 one from the secret keyring or the one set with @option{--default-key}.
1073
1074 @item --no-default-recipient
1075 @opindex no-default-recipient
1076 Reset @option{--default-recipient} and @option{--default-recipient-self}.
1077
1078 @item -v, --verbose
1079 @opindex verbose
1080 Give more information during processing. If used
1081 twice, the input data is listed in detail.
1082
1083 @item --no-verbose
1084 @opindex no-verbose
1085 Reset verbose level to 0.
1086
1087 @item -q, --quiet
1088 @opindex quiet
1089 Try to be as quiet as possible.
1090
1091 @item --batch
1092 @itemx --no-batch
1093 @opindex batch
1094 @opindex no-batch
1095 Use batch mode.  Never ask, do not allow interactive commands.
1096 @option{--no-batch} disables this option.  Note that even with a
1097 filename given on the command line, gpg might still need to read from
1098 STDIN (in particular if gpg figures that the input is a
1099 detached signature and no data file has been specified).  Thus if you
1100 do not want to feed data via STDIN, you should connect STDIN to
1101 @file{/dev/null}.
1102
1103 @item --no-tty
1104 @opindex no-tty
1105 Make sure that the TTY (terminal) is never used for any output.
1106 This option is needed in some cases because GnuPG sometimes prints
1107 warnings to the TTY even if @option{--batch} is used.
1108
1109 @item --yes
1110 @opindex yes
1111 Assume "yes" on most questions.
1112
1113 @item --no
1114 @opindex no
1115 Assume "no" on most questions.
1116
1117
1118 @item --list-options @code{parameters}
1119 @opindex list-options
1120 This is a space or comma delimited string that gives options used when
1121 listing keys and signatures (that is, @option{--list-keys},
1122 @option{--list-sigs}, @option{--list-public-keys},
1123 @option{--list-secret-keys}, and the @option{--edit-key} functions).
1124 Options can be prepended with a @option{no-} (after the two dashes) to
1125 give the opposite meaning.  The options are:
1126
1127 @table @asis
1128
1129   @item show-photos
1130   @opindex list-options:show-photos
1131   Causes @option{--list-keys}, @option{--list-sigs},
1132   @option{--list-public-keys}, and @option{--list-secret-keys} to
1133   display any photo IDs attached to the key.  Defaults to no. See also
1134   @option{--photo-viewer}.  Does not work with @option{--with-colons}:
1135   see @option{--attribute-fd} for the appropriate way to get photo data
1136   for scripts and other frontends.
1137
1138   @item show-usage
1139   @opindex list-options:show-usage
1140   Show usage information for keys and subkeys in the standard key
1141   listing.  This is a list of letters indicating the allowed usage for a
1142   key (@code{E}=encryption, @code{S}=signing, @code{C}=certification,
1143   @code{A}=authentication).  Defaults to yes.
1144
1145   @item show-policy-urls
1146   @opindex list-options:show-policy-urls
1147   Show policy URLs in the @option{--list-sigs} or @option{--check-sigs}
1148   listings.  Defaults to no.
1149
1150   @item show-notations
1151   @itemx show-std-notations
1152   @itemx show-user-notations
1153   @opindex list-options:show-notations
1154   @opindex list-options:show-std-notations
1155   @opindex list-options:show-user-notations
1156   Show all, IETF standard, or user-defined signature notations in the
1157   @option{--list-sigs} or @option{--check-sigs} listings. Defaults to no.
1158
1159   @item show-keyserver-urls
1160   @opindex list-options:show-keyserver-urls
1161   Show any preferred keyserver URL in the @option{--list-sigs} or
1162   @option{--check-sigs} listings. Defaults to no.
1163
1164   @item show-uid-validity
1165   @opindex list-options:show-uid-validity
1166   Display the calculated validity of user IDs during key listings.
1167   Defaults to yes.
1168
1169   @item show-unusable-uids
1170   @opindex list-options:show-unusable-uids
1171   Show revoked and expired user IDs in key listings. Defaults to no.
1172
1173   @item show-unusable-subkeys
1174   @opindex list-options:show-unusable-subkeys
1175   Show revoked and expired subkeys in key listings. Defaults to no.
1176
1177   @item show-keyring
1178   @opindex list-options:show-keyring
1179   Display the keyring name at the head of key listings to show which
1180   keyring a given key resides on. Defaults to no.
1181
1182   @item show-sig-expire
1183   @opindex list-options:show-sig-expire
1184   Show signature expiration dates (if any) during @option{--list-sigs} or
1185   @option{--check-sigs} listings. Defaults to no.
1186
1187   @item show-sig-subpackets
1188   @opindex list-options:show-sig-subpackets
1189   Include signature subpackets in the key listing. This option can take an
1190   optional argument list of the subpackets to list. If no argument is
1191   passed, list all subpackets. Defaults to no. This option is only
1192   meaningful when using @option{--with-colons} along with
1193   @option{--list-sigs} or @option{--check-sigs}.
1194
1195 @end table
1196
1197 @item --verify-options @code{parameters}
1198 @opindex verify-options
1199 This is a space or comma delimited string that gives options used when
1200 verifying signatures. Options can be prepended with a `no-' to give
1201 the opposite meaning. The options are:
1202
1203 @table @asis
1204
1205   @item show-photos
1206   @opindex verify-options:show-photos
1207   Display any photo IDs present on the key that issued the signature.
1208   Defaults to no. See also @option{--photo-viewer}.
1209
1210   @item show-policy-urls
1211   @opindex verify-options:show-policy-urls
1212   Show policy URLs in the signature being verified. Defaults to yes.
1213
1214   @item show-notations
1215   @itemx show-std-notations
1216   @itemx show-user-notations
1217   @opindex verify-options:show-notations
1218   @opindex verify-options:show-std-notations
1219   @opindex verify-options:show-user-notations
1220   Show all, IETF standard, or user-defined signature notations in the
1221   signature being verified. Defaults to IETF standard.
1222
1223   @item show-keyserver-urls
1224   @opindex verify-options:show-keyserver-urls
1225   Show any preferred keyserver URL in the signature being verified.
1226   Defaults to yes.
1227
1228   @item show-uid-validity
1229   @opindex verify-options:show-uid-validity
1230   Display the calculated validity of the user IDs on the key that issued
1231   the signature. Defaults to yes.
1232
1233   @item show-unusable-uids
1234   @opindex verify-options:show-unusable-uids
1235   Show revoked and expired user IDs during signature verification.
1236   Defaults to no.
1237
1238   @item show-primary-uid-only
1239   @opindex verify-options:show-primary-uid-only
1240   Show only the primary user ID during signature verification.  That is
1241   all the AKA lines as well as photo Ids are not shown with the signature
1242   verification status.
1243
1244   @item pka-lookups
1245   @opindex verify-options:pka-lookups
1246   Enable PKA lookups to verify sender addresses. Note that PKA is based
1247   on DNS, and so enabling this option may disclose information on when
1248   and what signatures are verified or to whom data is encrypted. This
1249   is similar to the "web bug" described for the auto-key-retrieve
1250   feature.
1251
1252   @item pka-trust-increase
1253   @opindex verify-options:pka-trust-increase
1254   Raise the trust in a signature to full if the signature passes PKA
1255   validation. This option is only meaningful if pka-lookups is set.
1256 @end table
1257
1258 @item --enable-large-rsa
1259 @itemx --disable-large-rsa
1260 @opindex enable-large-rsa
1261 @opindex disable-large-rsa
1262 With --gen-key and --batch, enable the creation of RSA secret keys as
1263 large as 8192 bit.  Note: 8192 bit is more than is generally
1264 recommended.  These large keys don't significantly improve security,
1265 but they are more expensive to use, and their signatures and
1266 certifications are larger.  This option is only available if the
1267 binary was build with large-secmem support.
1268
1269 @item --enable-dsa2
1270 @itemx --disable-dsa2
1271 @opindex enable-dsa2
1272 @opindex disable-dsa2
1273 Enable hash truncation for all DSA keys even for old DSA Keys up to
1274 1024 bit.  This is also the default with @option{--openpgp}.  Note
1275 that older versions of GnuPG also required this flag to allow the
1276 generation of DSA larger than 1024 bit.
1277
1278 @item --photo-viewer @code{string}
1279 @opindex photo-viewer
1280 This is the command line that should be run to view a photo ID. "%i"
1281 will be expanded to a filename containing the photo. "%I" does the
1282 same, except the file will not be deleted once the viewer exits.
1283 Other flags are "%k" for the key ID, "%K" for the long key ID, "%f"
1284 for the key fingerprint, "%t" for the extension of the image type
1285 (e.g. "jpg"), "%T" for the MIME type of the image (e.g. "image/jpeg"),
1286 "%v" for the single-character calculated validity of the image being
1287 viewed (e.g. "f"), "%V" for the calculated validity as a string (e.g.
1288 "full"), "%U" for a base32 encoded hash of the user ID,
1289 and "%%" for an actual percent sign. If neither %i or %I are present,
1290 then the photo will be supplied to the viewer on standard input.
1291
1292 The default viewer is "xloadimage -fork -quiet -title 'KeyID 0x%k'
1293 STDIN". Note that if your image viewer program is not secure, then
1294 executing it from GnuPG does not make it secure.
1295
1296 @item --exec-path @code{string}
1297 @opindex exec-path
1298 Sets a list of directories to search for photo viewers and keyserver
1299 helpers. If not provided, keyserver helpers use the compiled-in
1300 default directory, and photo viewers use the $PATH environment
1301 variable.
1302 Note, that on W32 system this value is ignored when searching for
1303 keyserver helpers.
1304
1305 @item --keyring @code{file}
1306 @opindex keyring
1307 Add @code{file} to the current list of keyrings. If @code{file} begins
1308 with a tilde and a slash, these are replaced by the $HOME directory. If
1309 the filename does not contain a slash, it is assumed to be in the GnuPG
1310 home directory ("~/.gnupg" if @option{--homedir} or $GNUPGHOME is not
1311 used).
1312
1313 Note that this adds a keyring to the current list. If the intent is to
1314 use the specified keyring alone, use @option{--keyring} along with
1315 @option{--no-default-keyring}.
1316
1317 @item --secret-keyring @code{file}
1318 @opindex secret-keyring
1319 This is an obsolete option and ignored.  All secret keys are stored in
1320 the @file{private-keys-v1.d} directory below the GnuPG home directory.
1321
1322 @item --primary-keyring @code{file}
1323 @opindex primary-keyring
1324 Designate @code{file} as the primary public keyring. This means that
1325 newly imported keys (via @option{--import} or keyserver
1326 @option{--recv-from}) will go to this keyring.
1327
1328 @item --trustdb-name @code{file}
1329 @opindex trustdb-name
1330 Use @code{file} instead of the default trustdb. If @code{file} begins
1331 with a tilde and a slash, these are replaced by the $HOME directory. If
1332 the filename does not contain a slash, it is assumed to be in the GnuPG
1333 home directory (@file{~/.gnupg} if @option{--homedir} or $GNUPGHOME is
1334 not used).
1335
1336 @include opt-homedir.texi
1337
1338
1339 @item --display-charset @code{name}
1340 @opindex display-charset
1341 Set the name of the native character set. This is used to convert
1342 some informational strings like user IDs to the proper UTF-8 encoding.
1343 Note that this has nothing to do with the character set of data to be
1344 encrypted or signed; GnuPG does not recode user-supplied data. If
1345 this option is not used, the default character set is determined from
1346 the current locale. A verbosity level of 3 shows the chosen set.
1347 Valid values for @code{name} are:
1348
1349 @table @asis
1350
1351   @item iso-8859-1
1352   @opindex display-charset:iso-8859-1
1353   This is the Latin 1 set.
1354
1355   @item iso-8859-2
1356   @opindex display-charset:iso-8859-2
1357   The Latin 2 set.
1358
1359   @item iso-8859-15
1360   @opindex display-charset:iso-8859-15
1361   This is currently an alias for
1362   the Latin 1 set.
1363
1364   @item koi8-r
1365   @opindex display-charset:koi8-r
1366   The usual Russian set (rfc1489).
1367
1368   @item utf-8
1369   @opindex display-charset:utf-8
1370   Bypass all translations and assume
1371   that the OS uses native UTF-8 encoding.
1372 @end table
1373
1374 @item --utf8-strings
1375 @itemx --no-utf8-strings
1376 @opindex utf8-strings
1377 Assume that command line arguments are given as UTF8 strings. The
1378 default (@option{--no-utf8-strings}) is to assume that arguments are
1379 encoded in the character set as specified by
1380 @option{--display-charset}. These options affect all following
1381 arguments. Both options may be used multiple times.
1382
1383 @anchor{gpg-option --options}
1384 @item --options @code{file}
1385 @opindex options
1386 Read options from @code{file} and do not try to read them from the
1387 default options file in the homedir (see @option{--homedir}). This
1388 option is ignored if used in an options file.
1389
1390 @item --no-options
1391 @opindex no-options
1392 Shortcut for @option{--options /dev/null}. This option is detected
1393 before an attempt to open an option file.  Using this option will also
1394 prevent the creation of a @file{~/.gnupg} homedir.
1395
1396 @item -z @code{n}
1397 @itemx --compress-level @code{n}
1398 @itemx --bzip2-compress-level @code{n}
1399 @opindex compress-level
1400 @opindex bzip2-compress-level
1401 Set compression level to @code{n} for the ZIP and ZLIB compression
1402 algorithms. The default is to use the default compression level of zlib
1403 (normally 6). @option{--bzip2-compress-level} sets the compression level
1404 for the BZIP2 compression algorithm (defaulting to 6 as well). This is a
1405 different option from @option{--compress-level} since BZIP2 uses a
1406 significant amount of memory for each additional compression level.
1407 @option{-z} sets both. A value of 0 for @code{n} disables compression.
1408
1409 @item --bzip2-decompress-lowmem
1410 @opindex bzip2-decompress-lowmem
1411 Use a different decompression method for BZIP2 compressed files. This
1412 alternate method uses a bit more than half the memory, but also runs
1413 at half the speed. This is useful under extreme low memory
1414 circumstances when the file was originally compressed at a high
1415 @option{--bzip2-compress-level}.
1416
1417
1418 @item --mangle-dos-filenames
1419 @itemx --no-mangle-dos-filenames
1420 @opindex mangle-dos-filenames
1421 @opindex no-mangle-dos-filenames
1422 Older version of Windows cannot handle filenames with more than one
1423 dot. @option{--mangle-dos-filenames} causes GnuPG to replace (rather
1424 than add to) the extension of an output filename to avoid this
1425 problem. This option is off by default and has no effect on non-Windows
1426 platforms.
1427
1428 @item --ask-cert-level
1429 @itemx --no-ask-cert-level
1430 @opindex ask-cert-level
1431 When making a key signature, prompt for a certification level. If this
1432 option is not specified, the certification level used is set via
1433 @option{--default-cert-level}. See @option{--default-cert-level} for
1434 information on the specific levels and how they are
1435 used. @option{--no-ask-cert-level} disables this option. This option
1436 defaults to no.
1437
1438 @item --default-cert-level @code{n}
1439 @opindex default-cert-level
1440 The default to use for the check level when signing a key.
1441
1442 0 means you make no particular claim as to how carefully you verified
1443 the key.
1444
1445 1 means you believe the key is owned by the person who claims to own
1446 it but you could not, or did not verify the key at all. This is
1447 useful for a "persona" verification, where you sign the key of a
1448 pseudonymous user.
1449
1450 2 means you did casual verification of the key. For example, this
1451 could mean that you verified the key fingerprint and checked the
1452 user ID on the key against a photo ID.
1453
1454 3 means you did extensive verification of the key. For example, this
1455 could mean that you verified the key fingerprint with the owner of the
1456 key in person, and that you checked, by means of a hard to forge
1457 document with a photo ID (such as a passport) that the name of the key
1458 owner matches the name in the user ID on the key, and finally that you
1459 verified (by exchange of email) that the email address on the key
1460 belongs to the key owner.
1461
1462 Note that the examples given above for levels 2 and 3 are just that:
1463 examples. In the end, it is up to you to decide just what "casual"
1464 and "extensive" mean to you.
1465
1466 This option defaults to 0 (no particular claim).
1467
1468 @item --min-cert-level
1469 @opindex min-cert-level
1470 When building the trust database, treat any signatures with a
1471 certification level below this as invalid. Defaults to 2, which
1472 disregards level 1 signatures. Note that level 0 "no particular
1473 claim" signatures are always accepted.
1474
1475 @item --trusted-key @code{long key ID}
1476 @opindex trusted-key
1477 Assume that the specified key (which must be given
1478 as a full 8 byte key ID) is as trustworthy as one of
1479 your own secret keys. This option is useful if you
1480 don't want to keep your secret keys (or one of them)
1481 online but still want to be able to check the validity of a given
1482 recipient's or signator's key.
1483
1484 @item --trust-model @code{pgp|classic|tofu|tofu+pgp|direct|always|auto}
1485 @opindex trust-model
1486 Set what trust model GnuPG should follow. The models are:
1487
1488 @table @asis
1489
1490   @item pgp
1491   @opindex trust-mode:pgp
1492   This is the Web of Trust combined with trust signatures as used in PGP
1493   5.x and later. This is the default trust model when creating a new
1494   trust database.
1495
1496   @item classic
1497   @opindex trust-mode:classic
1498   This is the standard Web of Trust as introduced by PGP 2.
1499
1500   @item tofu
1501   @opindex trust-mode:tofu
1502   @anchor{trust-model-tofu}
1503   TOFU stands for Trust On First Use.  In this trust model, the first
1504   time a key is seen, it is memorized.  If later another key is seen
1505   with a user id with the same email address, a warning is displayed
1506   indicating that there is a conflict and that the key might be a
1507   forgery and an attempt at a man-in-the-middle attack.
1508
1509   Because a potential attacker is able to control the email address
1510   and thereby circumvent the conflict detection algorithm by using an
1511   email address that is similar in appearance to a trusted email
1512   address, whenever a message is verified, statistics about the number
1513   of messages signed with the key are shown.  In this way, a user can
1514   easily identify attacks using fake keys for regular correspondents.
1515
1516   When compared with the Web of Trust, TOFU offers significantly
1517   weaker security guarantees.  In particular, TOFU only helps ensure
1518   consistency (that is, that the binding between a key and email
1519   address doesn't change).  A major advantage of TOFU is that it
1520   requires little maintenance to use correctly.  To use the web of
1521   trust properly, you need to actively sign keys and mark users as
1522   trusted introducers.  This is a time-consuming process and anecdotal
1523   evidence suggests that even security-conscious users rarely take the
1524   time to do this thoroughly and instead rely on an ad-hoc TOFU
1525   process.
1526
1527   In the TOFU model, policies are associated with bindings between
1528   keys and email addresses (which are extracted from user ids and
1529   normalized).  There are five policies, which can be set manually
1530   using the @option{--tofu-policy} option.  The default policy can be
1531   set using the @option{--tofu-default-policy} policy.
1532
1533   The TOFU policies are: @code{auto}, @code{good}, @code{unknown},
1534   @code{bad} and @code{ask}.  The @code{auto} policy is used by
1535   default (unless overridden by @option{--tofu-default-policy}) and
1536   marks a binding as marginally trusted.  The @code{good},
1537   @code{unknown} and @code{bad} policies mark a binding as fully
1538   trusted, as having unknown trust or as having trust never,
1539   respectively.  The @code{unknown} policy is useful for just using
1540   TOFU to detect conflicts, but to never assign positive trust to a
1541   binding.  The final policy, @code{ask} prompts the user to indicate
1542   the binding's trust.  If batch mode is enabled (or input is
1543   inappropriate in the context), then the user is not prompted and the
1544   @code{undefined} trust level is returned.
1545
1546   @item tofu+pgp
1547   @opindex trust-mode:tofu+pgp
1548   This trust model combines TOFU with the Web of Trust.  This is done
1549   by computing the trust level for each model and then taking the
1550   maximum trust level where the trust levels are ordered as follows:
1551   @code{unknown < undefined < marginal < fully < ultimate < expired <
1552   never}.
1553
1554   By setting @option{--tofu-default-policy=unknown}, this model can be
1555   used to implement the web of trust with TOFU's conflict detection
1556   algorithm, but without its assignment of positive trust values,
1557   which some security-conscious users don't like.
1558
1559   @item direct
1560   @opindex trust-mode:direct
1561   Key validity is set directly by the user and not calculated via the
1562   Web of Trust.
1563
1564   @item always
1565   @opindex trust-mode:always
1566   Skip key validation and assume that used keys are always fully
1567   valid. You generally won't use this unless you are using some
1568   external validation scheme. This option also suppresses the
1569   "[uncertain]" tag printed with signature checks when there is no
1570   evidence that the user ID is bound to the key.  Note that this
1571   trust model still does not allow the use of expired, revoked, or
1572   disabled keys.
1573
1574   @item auto
1575   @opindex trust-mode:auto
1576   Select the trust model depending on whatever the internal trust
1577   database says. This is the default model if such a database already
1578   exists.
1579 @end table
1580
1581 @item --auto-key-locate @code{parameters}
1582 @itemx --no-auto-key-locate
1583 @opindex auto-key-locate
1584 GnuPG can automatically locate and retrieve keys as needed using this
1585 option. This happens when encrypting to an email address (in the
1586 "user@@example.com" form), and there are no user@@example.com keys on
1587 the local keyring.  This option takes any number of the following
1588 mechanisms, in the order they are to be tried:
1589
1590 @table @asis
1591
1592   @item cert
1593   Locate a key using DNS CERT, as specified in rfc4398.
1594
1595   @item pka
1596   Locate a key using DNS PKA.
1597
1598   @item dane
1599   Locate a key using DANE, as specified
1600   in draft-ietf-dane-openpgpkey-05.txt.
1601
1602   @item ldap
1603   Using DNS Service Discovery, check the domain in question for any LDAP
1604   keyservers to use.  If this fails, attempt to locate the key using the
1605   PGP Universal method of checking @samp{ldap://keys.(thedomain)}.
1606
1607   @item keyserver
1608   Locate a key using whatever keyserver is defined using the
1609   @option{--keyserver} option.
1610
1611   @item keyserver-URL
1612   In addition, a keyserver URL as used in the @option{--keyserver} option
1613   may be used here to query that particular keyserver.
1614
1615   @item local
1616   Locate the key using the local keyrings.  This mechanism allows to
1617   select the order a local key lookup is done.  Thus using
1618   @samp{--auto-key-locate local} is identical to
1619   @option{--no-auto-key-locate}.
1620
1621   @item nodefault
1622   This flag disables the standard local key lookup, done before any of the
1623   mechanisms defined by the @option{--auto-key-locate} are tried.  The
1624   position of this mechanism in the list does not matter.  It is not
1625   required if @code{local} is also used.
1626
1627   @item clear
1628   Clear all defined mechanisms.  This is useful to override
1629   mechanisms given in a config file.
1630
1631 @end table
1632
1633 @item --keyid-format @code{short|0xshort|long|0xlong}
1634 @opindex keyid-format
1635 Select how to display key IDs. "short" is the traditional 8-character
1636 key ID. "long" is the more accurate (but less convenient)
1637 16-character key ID. Add an "0x" to either to include an "0x" at the
1638 beginning of the key ID, as in 0x99242560.  Note that this option is
1639 ignored if the option --with-colons is used.
1640
1641 @item --keyserver @code{name}
1642 @opindex keyserver
1643 This option is deprecated - please use the @option{--keyserver} in
1644 @file{dirmngr.conf} instead.
1645
1646 Use @code{name} as your keyserver. This is the server that
1647 @option{--recv-keys}, @option{--send-keys}, and @option{--search-keys}
1648 will communicate with to receive keys from, send keys to, and search for
1649 keys on. The format of the @code{name} is a URI:
1650 `scheme:[//]keyservername[:port]' The scheme is the type of keyserver:
1651 "hkp" for the HTTP (or compatible) keyservers, "ldap" for the LDAP
1652 keyservers, or "mailto" for the Graff email keyserver. Note that your
1653 particular installation of GnuPG may have other keyserver types
1654 available as well. Keyserver schemes are case-insensitive. After the
1655 keyserver name, optional keyserver configuration options may be
1656 provided. These are the same as the global @option{--keyserver-options}
1657 from below, but apply only to this particular keyserver.
1658
1659 Most keyservers synchronize with each other, so there is generally no
1660 need to send keys to more than one server. The keyserver
1661 @code{hkp://keys.gnupg.net} uses round robin DNS to give a different
1662 keyserver each time you use it.
1663
1664 @item --keyserver-options @code{name=value}
1665 @opindex keyserver-options
1666 This is a space or comma delimited string that gives options for the
1667 keyserver. Options can be prefixed with a `no-' to give the opposite
1668 meaning. Valid import-options or export-options may be used here as
1669 well to apply to importing (@option{--recv-key}) or exporting
1670 (@option{--send-key}) a key from a keyserver. While not all options
1671 are available for all keyserver types, some common options are:
1672
1673 @table @asis
1674
1675   @item include-revoked
1676   When searching for a key with @option{--search-keys}, include keys that
1677   are marked on the keyserver as revoked. Note that not all keyservers
1678   differentiate between revoked and unrevoked keys, and for such
1679   keyservers this option is meaningless. Note also that most keyservers do
1680   not have cryptographic verification of key revocations, and so turning
1681   this option off may result in skipping keys that are incorrectly marked
1682   as revoked.
1683
1684   @item include-disabled
1685   When searching for a key with @option{--search-keys}, include keys that
1686   are marked on the keyserver as disabled. Note that this option is not
1687   used with HKP keyservers.
1688
1689   @item auto-key-retrieve
1690   This option enables the automatic retrieving of keys from a keyserver
1691   when verifying signatures made by keys that are not on the local
1692   keyring.
1693
1694   Note that this option makes a "web bug" like behavior possible.
1695   Keyserver operators can see which keys you request, so by sending you
1696   a message signed by a brand new key (which you naturally will not have
1697   on your local keyring), the operator can tell both your IP address and
1698   the time when you verified the signature.
1699
1700   @item honor-keyserver-url
1701   When using @option{--refresh-keys}, if the key in question has a preferred
1702   keyserver URL, then use that preferred keyserver to refresh the key
1703   from. In addition, if auto-key-retrieve is set, and the signature
1704   being verified has a preferred keyserver URL, then use that preferred
1705   keyserver to fetch the key from. Note that this option introduces a
1706   "web bug": The creator of the key can see when the keys is
1707   refreshed.  Thus this option is not enabled by default.
1708
1709   @item honor-pka-record
1710   If auto-key-retrieve is set, and the signature being verified has a
1711   PKA record, then use the PKA information to fetch the key. Defaults
1712   to "yes".
1713
1714   @item include-subkeys
1715   When receiving a key, include subkeys as potential targets. Note that
1716   this option is not used with HKP keyservers, as they do not support
1717   retrieving keys by subkey id.
1718
1719   @item timeout
1720   Tell the keyserver helper program how long (in seconds) to try and
1721   perform a keyserver action before giving up. Note that performing
1722   multiple actions at the same time uses this timeout value per action.
1723   For example, when retrieving multiple keys via @option{--recv-keys}, the
1724   timeout applies separately to each key retrieval, and not to the
1725   @option{--recv-keys} command as a whole. Defaults to 30 seconds.
1726
1727   @item http-proxy=@code{value}
1728   This options is deprecated.
1729   Set the proxy to use for HTTP and HKP keyservers.
1730   This overrides any proxy defined in @file{dirmngr.conf}.
1731
1732   @item verbose
1733   This option has no more function since GnuPG 2.1.  Use the
1734   @code{dirmngr} configuration options instead.
1735
1736   @item debug
1737   This option has no more function since GnuPG 2.1.  Use the
1738   @code{dirmngr} configuration options instead.
1739
1740   @item check-cert
1741   This option has no more function since GnuPG 2.1.  Use the
1742   @code{dirmngr} configuration options instead.
1743
1744   @item ca-cert-file
1745   This option has no more function since GnuPG 2.1.  Use the
1746   @code{dirmngr} configuration options instead.
1747
1748 @end table
1749
1750 @item --completes-needed @code{n}
1751 @opindex compliant-needed
1752 Number of completely trusted users to introduce a new
1753 key signer (defaults to 1).
1754
1755 @item --marginals-needed @code{n}
1756 @opindex marginals-needed
1757 Number of marginally trusted users to introduce a new
1758 key signer (defaults to 3)
1759
1760 @item --tofu-default-policy @code{auto|good|unknown|bad|ask}
1761 @opindex tofu-default-policy
1762 The default TOFU policy (defaults to @code{auto}).  For more
1763 information about the meaning of this option, @xref{trust-model-tofu}.
1764
1765 @item --tofu-db-format @code{auto|split|flat}
1766 @opindex tofu-default-policy
1767 The format for the TOFU DB.
1768
1769 The split file format splits the data across many DBs under the
1770 @code{tofu.d} directory (one per email address and one per key).  This
1771 makes it easier to automatically synchronize the data using a tool
1772 such as Unison (@url{https://www.cis.upenn.edu/~bcpierce/unison/}),
1773 since the individual files change rarely.
1774
1775 The flat file format keeps all of the data in the single file
1776 @code{tofu.db}.  This format results in better performance.
1777
1778 If set to auto (which is the default), GnuPG will first check for the
1779 existence of @code{tofu.d} and @code{tofu.db}.  If one of these
1780 exists, the corresponding format is used.  If neither or both of these
1781 exist, then GnuPG defaults to the @code{split} format.  In the latter
1782 case, a warning is emitted.
1783
1784 @item --max-cert-depth @code{n}
1785 @opindex max-cert-depth
1786 Maximum depth of a certification chain (default is 5).
1787
1788 @item --no-sig-cache
1789 @opindex no-sig-cache
1790 Do not cache the verification status of key signatures.
1791 Caching gives a much better performance in key listings. However, if
1792 you suspect that your public keyring is not save against write
1793 modifications, you can use this option to disable the caching. It
1794 probably does not make sense to disable it because all kind of damage
1795 can be done if someone else has write access to your public keyring.
1796
1797 @item --auto-check-trustdb
1798 @itemx --no-auto-check-trustdb
1799 @opindex auto-check-trustdb
1800 If GnuPG feels that its information about the Web of Trust has to be
1801 updated, it automatically runs the @option{--check-trustdb} command
1802 internally.  This may be a time consuming
1803 process. @option{--no-auto-check-trustdb} disables this option.
1804
1805 @item --use-agent
1806 @itemx --no-use-agent
1807 @opindex use-agent
1808 This is dummy option. @command{@gpgname} always requires the agent.
1809
1810 @item --gpg-agent-info
1811 @opindex gpg-agent-info
1812 This is dummy option. It has no effect when used with @command{@gpgname}.
1813
1814
1815 @item --agent-program @var{file}
1816 @opindex agent-program
1817 Specify an agent program to be used for secret key operations.  The
1818 default value is determined by running @command{gpgconf} with the
1819 option @option{--list-dirs}.  Note that the pipe symbol (@code{|}) is
1820 used for a regression test suite hack and may thus not be used in the
1821 file name.
1822
1823 @item --dirmngr-program @var{file}
1824 @opindex dirmngr-program
1825 Specify a dirmngr program to be used for keyserver access.  The
1826 default value is @file{@value{BINDIR}/dirmngr}.  This is only used as a
1827 fallback when the environment variable @code{DIRMNGR_INFO} is not set or
1828 a running dirmngr cannot be connected.
1829
1830 @item --no-autostart
1831 @opindex no-autostart
1832 Do not start the gpg-agent or the dirmngr if it has not yet been
1833 started and its service is required.  This option is mostly useful on
1834 machines where the connection to gpg-agent has been redirected to
1835 another machines.  If dirmngr is required on the remote machine, it
1836 may be started manually using @command{gpgconf --launch dirmngr}.
1837
1838 @item --lock-once
1839 @opindex lock-once
1840 Lock the databases the first time a lock is requested
1841 and do not release the lock until the process
1842 terminates.
1843
1844 @item --lock-multiple
1845 @opindex lock-multiple
1846 Release the locks every time a lock is no longer
1847 needed. Use this to override a previous @option{--lock-once}
1848 from a config file.
1849
1850 @item --lock-never
1851 @opindex lock-never
1852 Disable locking entirely. This option should be used only in very
1853 special environments, where it can be assured that only one process
1854 is accessing those files. A bootable floppy with a stand-alone
1855 encryption system will probably use this. Improper usage of this
1856 option may lead to data and key corruption.
1857
1858 @item --exit-on-status-write-error
1859 @opindex exit-on-status-write-error
1860 This option will cause write errors on the status FD to immediately
1861 terminate the process. That should in fact be the default but it never
1862 worked this way and thus we need an option to enable this, so that the
1863 change won't break applications which close their end of a status fd
1864 connected pipe too early. Using this option along with
1865 @option{--enable-progress-filter} may be used to cleanly cancel long
1866 running gpg operations.
1867
1868 @item --limit-card-insert-tries @code{n}
1869 @opindex limit-card-insert-tries
1870 With @code{n} greater than 0 the number of prompts asking to insert a
1871 smartcard gets limited to N-1. Thus with a value of 1 gpg won't at
1872 all ask to insert a card if none has been inserted at startup. This
1873 option is useful in the configuration file in case an application does
1874 not know about the smartcard support and waits ad infinitum for an
1875 inserted card.
1876
1877 @item --no-random-seed-file
1878 @opindex no-random-seed-file
1879 GnuPG uses a file to store its internal random pool over invocations.
1880 This makes random generation faster; however sometimes write operations
1881 are not desired. This option can be used to achieve that with the cost of
1882 slower random generation.
1883
1884 @item --no-greeting
1885 @opindex no-greeting
1886 Suppress the initial copyright message.
1887
1888 @item --no-secmem-warning
1889 @opindex no-secmem-warning
1890 Suppress the warning about "using insecure memory".
1891
1892 @item --no-permission-warning
1893 @opindex permission-warning
1894 Suppress the warning about unsafe file and home directory (@option{--homedir})
1895 permissions. Note that the permission checks that GnuPG performs are
1896 not intended to be authoritative, but rather they simply warn about
1897 certain common permission problems. Do not assume that the lack of a
1898 warning means that your system is secure.
1899
1900 Note that the warning for unsafe @option{--homedir} permissions cannot be
1901 suppressed in the gpg.conf file, as this would allow an attacker to
1902 place an unsafe gpg.conf file in place, and use this file to suppress
1903 warnings about itself. The @option{--homedir} permissions warning may only be
1904 suppressed on the command line.
1905
1906 @item --no-mdc-warning
1907 @opindex no-mdc-warning
1908 Suppress the warning about missing MDC integrity protection.
1909
1910 @item --require-secmem
1911 @itemx --no-require-secmem
1912 @opindex require-secmem
1913 Refuse to run if GnuPG cannot get secure memory. Defaults to no
1914 (i.e. run, but give a warning).
1915
1916
1917 @item --require-cross-certification
1918 @itemx --no-require-cross-certification
1919 @opindex require-cross-certification
1920 When verifying a signature made from a subkey, ensure that the cross
1921 certification "back signature" on the subkey is present and valid.  This
1922 protects against a subtle attack against subkeys that can sign.
1923 Defaults to @option{--require-cross-certification} for
1924 @command{@gpgname}.
1925
1926 @item --expert
1927 @itemx --no-expert
1928 @opindex expert
1929 Allow the user to do certain nonsensical or "silly" things like
1930 signing an expired or revoked key, or certain potentially incompatible
1931 things like generating unusual key types. This also disables certain
1932 warning messages about potentially incompatible actions. As the name
1933 implies, this option is for experts only. If you don't fully
1934 understand the implications of what it allows you to do, leave this
1935 off. @option{--no-expert} disables this option.
1936
1937 @end table
1938
1939
1940 @c *******************************************
1941 @c ********  KEY RELATED OPTIONS  ************
1942 @c *******************************************
1943 @node GPG Key related Options
1944 @subsection Key related options
1945
1946 @table @gnupgtabopt
1947
1948 @item --recipient @var{name}
1949 @itemx -r
1950 @opindex recipient
1951 Encrypt for user id @var{name}. If this option or
1952 @option{--hidden-recipient} is not specified, GnuPG asks for the user-id
1953 unless @option{--default-recipient} is given.
1954
1955 @item --hidden-recipient @var{name}
1956 @itemx -R
1957 @opindex hidden-recipient
1958 Encrypt for user ID @var{name}, but hide the key ID of this user's
1959 key. This option helps to hide the receiver of the message and is a
1960 limited countermeasure against traffic analysis. If this option or
1961 @option{--recipient} is not specified, GnuPG asks for the user ID unless
1962 @option{--default-recipient} is given.
1963
1964 @item --encrypt-to @code{name}
1965 @opindex encrypt-to
1966 Same as @option{--recipient} but this one is intended for use in the
1967 options file and may be used with your own user-id as an
1968 "encrypt-to-self". These keys are only used when there are other
1969 recipients given either by use of @option{--recipient} or by the asked
1970 user id.  No trust checking is performed for these user ids and even
1971 disabled keys can be used.
1972
1973 @item --hidden-encrypt-to @code{name}
1974 @opindex hidden-encrypt-to
1975 Same as @option{--hidden-recipient} but this one is intended for use in the
1976 options file and may be used with your own user-id as a hidden
1977 "encrypt-to-self". These keys are only used when there are other
1978 recipients given either by use of @option{--recipient} or by the asked user id.
1979 No trust checking is performed for these user ids and even disabled
1980 keys can be used.
1981
1982 @item --encrypt-to-default-key
1983 @opindex encrypt-to-default-key
1984 If the default secret key is taken from @option{--default-key}, then
1985 also encrypt to that key.
1986
1987 @item --no-encrypt-to
1988 @opindex no-encrypt-to
1989 Disable the use of all @option{--encrypt-to} and
1990 @option{--hidden-encrypt-to} keys.
1991
1992 @item --group @code{name=value1 }
1993 @opindex group
1994 Sets up a named group, which is similar to aliases in email programs.
1995 Any time the group name is a recipient (@option{-r} or
1996 @option{--recipient}), it will be expanded to the values
1997 specified. Multiple groups with the same name are automatically merged
1998 into a single group.
1999
2000 The values are @code{key IDs} or fingerprints, but any key description
2001 is accepted. Note that a value with spaces in it will be treated as
2002 two different values. Note also there is only one level of expansion
2003 --- you cannot make an group that points to another group. When used
2004 from the command line, it may be necessary to quote the argument to
2005 this option to prevent the shell from treating it as multiple
2006 arguments.
2007
2008 @item --ungroup @code{name}
2009 @opindex ungroup
2010 Remove a given entry from the @option{--group} list.
2011
2012 @item --no-groups
2013 @opindex no-groups
2014 Remove all entries from the @option{--group} list.
2015
2016 @item --local-user @var{name}
2017 @itemx -u
2018 @opindex local-user
2019 Use @var{name} as the key to sign with. Note that this option overrides
2020 @option{--default-key}.
2021
2022 @item --try-secret-key @var{name}
2023 @opindex try-secret-key
2024 For hidden recipients GPG needs to know the keys to use for trial
2025 decryption.  The key set with @option{--default-key} is always tried
2026 first, but this is often not sufficient.  This option allows to set more
2027 keys to be used for trial decryption.  Although any valid user-id
2028 specification may be used for @var{name} it makes sense to use at least
2029 the long keyid to avoid ambiguities.  Note that gpg-agent might pop up a
2030 pinentry for a lot keys to do the trial decryption.  If you want to stop
2031 all further trial decryption you may use close-window button instead of
2032 the cancel button.
2033
2034 @item --try-all-secrets
2035 @opindex try-all-secrets
2036 Don't look at the key ID as stored in the message but try all secret
2037 keys in turn to find the right decryption key. This option forces the
2038 behaviour as used by anonymous recipients (created by using
2039 @option{--throw-keyids} or @option{--hidden-recipient}) and might come
2040 handy in case where an encrypted message contains a bogus key ID.
2041
2042 @item --skip-hidden-recipients
2043 @itemx --no-skip-hidden-recipients
2044 @opindex skip-hidden-recipients
2045 @opindex no-skip-hidden-recipients
2046 During decryption skip all anonymous recipients.  This option helps in
2047 the case that people use the hidden recipients feature to hide there
2048 own encrypt-to key from others.  If oneself has many secret keys this
2049 may lead to a major annoyance because all keys are tried in turn to
2050 decrypt something which was not really intended for it.  The drawback
2051 of this option is that it is currently not possible to decrypt a
2052 message which includes real anonymous recipients.
2053
2054
2055 @end table
2056
2057 @c *******************************************
2058 @c ********  INPUT AND OUTPUT  ***************
2059 @c *******************************************
2060 @node GPG Input and Output
2061 @subsection Input and Output
2062
2063 @table @gnupgtabopt
2064
2065 @item --armor
2066 @itemx -a
2067 @opindex armor
2068 Create ASCII armored output.  The default is to create the binary
2069 OpenPGP format.
2070
2071 @item --no-armor
2072 @opindex no-armor
2073 Assume the input data is not in ASCII armored format.
2074
2075 @item --output @var{file}
2076 @itemx -o @var{file}
2077 @opindex output
2078 Write output to @var{file}.
2079
2080 @item --max-output @code{n}
2081 @opindex max-output
2082 This option sets a limit on the number of bytes that will be generated
2083 when processing a file. Since OpenPGP supports various levels of
2084 compression, it is possible that the plaintext of a given message may be
2085 significantly larger than the original OpenPGP message. While GnuPG
2086 works properly with such messages, there is often a desire to set a
2087 maximum file size that will be generated before processing is forced to
2088 stop by the OS limits. Defaults to 0, which means "no limit".
2089
2090 @item --import-options @code{parameters}
2091 @opindex import-options
2092 This is a space or comma delimited string that gives options for
2093 importing keys. Options can be prepended with a `no-' to give the
2094 opposite meaning. The options are:
2095
2096 @table @asis
2097
2098   @item import-local-sigs
2099   Allow importing key signatures marked as "local". This is not
2100   generally useful unless a shared keyring scheme is being used.
2101   Defaults to no.
2102
2103   @item keep-ownertrust
2104   Normally possible still existing ownertrust values of a key are
2105   cleared if a key is imported.  This is in general desirable so that
2106   a formerly deleted key does not automatically gain an ownertrust
2107   values merely due to import.  On the other hand it is sometimes
2108   necessary to re-import a trusted set of keys again but keeping
2109   already assigned ownertrust values.  This can be achived by using
2110   this option.
2111
2112   @item repair-pks-subkey-bug
2113   During import, attempt to repair the damage caused by the PKS keyserver
2114   bug (pre version 0.9.6) that mangles keys with multiple subkeys. Note
2115   that this cannot completely repair the damaged key as some crucial data
2116   is removed by the keyserver, but it does at least give you back one
2117   subkey. Defaults to no for regular @option{--import} and to yes for
2118   keyserver @option{--recv-keys}.
2119
2120   @item merge-only
2121   During import, allow key updates to existing keys, but do not allow
2122   any new keys to be imported. Defaults to no.
2123
2124   @item import-clean
2125   After import, compact (remove all signatures except the
2126   self-signature) any user IDs from the new key that are not usable.
2127   Then, remove any signatures from the new key that are not usable.
2128   This includes signatures that were issued by keys that are not present
2129   on the keyring. This option is the same as running the @option{--edit-key}
2130   command "clean" after import. Defaults to no.
2131
2132   @item import-minimal
2133   Import the smallest key possible. This removes all signatures except
2134   the most recent self-signature on each user ID. This option is the
2135   same as running the @option{--edit-key} command "minimize" after import.
2136   Defaults to no.
2137 @end table
2138
2139 @item --export-options @code{parameters}
2140 @opindex export-options
2141 This is a space or comma delimited string that gives options for
2142 exporting keys. Options can be prepended with a `no-' to give the
2143 opposite meaning. The options are:
2144
2145 @table @asis
2146
2147   @item export-local-sigs
2148   Allow exporting key signatures marked as "local". This is not
2149   generally useful unless a shared keyring scheme is being used.
2150   Defaults to no.
2151
2152   @item export-attributes
2153   Include attribute user IDs (photo IDs) while exporting. This is
2154   useful to export keys if they are going to be used by an OpenPGP
2155   program that does not accept attribute user IDs. Defaults to yes.
2156
2157   @item export-sensitive-revkeys
2158   Include designated revoker information that was marked as
2159   "sensitive". Defaults to no.
2160
2161   @c Since GnuPG 2.1 gpg-agent manages the secret key and thus the
2162   @c export-reset-subkey-passwd hack is not anymore justified.  Such use
2163   @c cases may be implemented using a specialized secret key export
2164   @c tool.
2165   @c @item export-reset-subkey-passwd
2166   @c When using the @option{--export-secret-subkeys} command, this option resets
2167   @c the passphrases for all exported subkeys to empty. This is useful
2168   @c when the exported subkey is to be used on an unattended machine where
2169   @c a passphrase doesn't necessarily make sense. Defaults to no.
2170
2171   @item export-clean
2172   Compact (remove all signatures from) user IDs on the key being
2173   exported if the user IDs are not usable. Also, do not export any
2174   signatures that are not usable. This includes signatures that were
2175   issued by keys that are not present on the keyring. This option is
2176   the same as running the @option{--edit-key} command "clean" before export
2177   except that the local copy of the key is not modified. Defaults to
2178   no.
2179
2180   @item export-minimal
2181   Export the smallest key possible. This removes all signatures except the
2182   most recent self-signature on each user ID. This option is the same as
2183   running the @option{--edit-key} command "minimize" before export except
2184   that the local copy of the key is not modified. Defaults to no.
2185 @end table
2186
2187 @item --with-colons
2188 @opindex with-colons
2189 Print key listings delimited by colons. Note that the output will be
2190 encoded in UTF-8 regardless of any @option{--display-charset} setting. This
2191 format is useful when GnuPG is called from scripts and other programs
2192 as it is easily machine parsed. The details of this format are
2193 documented in the file @file{doc/DETAILS}, which is included in the GnuPG
2194 source distribution.
2195
2196
2197 @item --print-pka-records
2198 @opindex print-pka-records
2199 Modify the output of the list commands to print PKA records suitable
2200 to put into DNS zone files.  An ORIGIN line is printed before each
2201 record to allow diverting the records to the corresponding zone file.
2202
2203 @item --print-dane-records
2204 @opindex print-dane-records
2205 Modify the output of the list commands to print OpenPGP DANE records
2206 suitable to put into DNS zone files.  An ORIGIN line is printed before
2207 each record to allow diverting the records to the corresponding zone
2208 file.
2209
2210 @item --fixed-list-mode
2211 @opindex fixed-list-mode
2212 Do not merge primary user ID and primary key in @option{--with-colon}
2213 listing mode and print all timestamps as seconds since 1970-01-01.
2214 Since GnuPG 2.0.10, this mode is always used and thus this option is
2215 obsolete; it does not harm to use it though.
2216
2217 @item --legacy-list-mode
2218 @opindex legacy-list-mode
2219 Revert to the pre-2.1 public key list mode.  This only affects the
2220 human readable output and not the machine interface
2221 (i.e. @code{--with-colons}).  Note that the legacy format does not
2222 allow to convey suitable information for elliptic curves.
2223
2224 @item --with-fingerprint
2225 @opindex with-fingerprint
2226 Same as the command @option{--fingerprint} but changes only the format
2227 of the output and may be used together with another command.
2228
2229 @item --with-icao-spelling
2230 @opindex with-icao-spelling
2231 Print the ICAO spelling of the fingerprint in addition to the hex digits.
2232
2233 @item --with-keygrip
2234 @opindex with-keygrip
2235 Include the keygrip in the key listings.
2236
2237 @item --with-secret
2238 @opindex with-secret
2239 Include info about the presence of a secret key in public key listings
2240 done with @code{--with-colons}.
2241
2242 @end table
2243
2244 @c *******************************************
2245 @c ********  OPENPGP OPTIONS  ****************
2246 @c *******************************************
2247 @node OpenPGP Options
2248 @subsection OpenPGP protocol specific options.
2249
2250 @table @gnupgtabopt
2251
2252 @item -t, --textmode
2253 @itemx --no-textmode
2254 @opindex textmode
2255 Treat input files as text and store them in the OpenPGP canonical text
2256 form with standard "CRLF" line endings. This also sets the necessary
2257 flags to inform the recipient that the encrypted or signed data is text
2258 and may need its line endings converted back to whatever the local
2259 system uses. This option is useful when communicating between two
2260 platforms that have different line ending conventions (UNIX-like to Mac,
2261 Mac to Windows, etc). @option{--no-textmode} disables this option, and
2262 is the default.
2263
2264 @item --force-v3-sigs
2265 @itemx --no-force-v3-sigs
2266 @item --force-v4-certs
2267 @itemx --no-force-v4-certs
2268 These options are obsolete and have no effect since GnuPG 2.1.
2269
2270 @item --force-mdc
2271 @opindex force-mdc
2272 Force the use of encryption with a modification detection code. This
2273 is always used with the newer ciphers (those with a blocksize greater
2274 than 64 bits), or if all of the recipient keys indicate MDC support in
2275 their feature flags.
2276
2277 @item --disable-mdc
2278 @opindex disable-mdc
2279 Disable the use of the modification detection code. Note that by
2280 using this option, the encrypted message becomes vulnerable to a
2281 message modification attack.
2282
2283 @item --personal-cipher-preferences @code{string}
2284 @opindex personal-cipher-preferences
2285 Set the list of personal cipher preferences to @code{string}.  Use
2286 @command{@gpgname --version} to get a list of available algorithms,
2287 and use @code{none} to set no preference at all.  This allows the user
2288 to safely override the algorithm chosen by the recipient key
2289 preferences, as GPG will only select an algorithm that is usable by
2290 all recipients.  The most highly ranked cipher in this list is also
2291 used for the @option{--symmetric} encryption command.
2292
2293 @item --personal-digest-preferences @code{string}
2294 @opindex personal-digest-preferences
2295 Set the list of personal digest preferences to @code{string}.  Use
2296 @command{@gpgname --version} to get a list of available algorithms,
2297 and use @code{none} to set no preference at all.  This allows the user
2298 to safely override the algorithm chosen by the recipient key
2299 preferences, as GPG will only select an algorithm that is usable by
2300 all recipients.  The most highly ranked digest algorithm in this list
2301 is also used when signing without encryption
2302 (e.g. @option{--clearsign} or @option{--sign}).
2303
2304 @item --personal-compress-preferences @code{string}
2305 @opindex personal-compress-preferences
2306 Set the list of personal compression preferences to @code{string}.
2307 Use @command{@gpgname --version} to get a list of available
2308 algorithms, and use @code{none} to set no preference at all.  This
2309 allows the user to safely override the algorithm chosen by the
2310 recipient key preferences, as GPG will only select an algorithm that
2311 is usable by all recipients.  The most highly ranked compression
2312 algorithm in this list is also used when there are no recipient keys
2313 to consider (e.g. @option{--symmetric}).
2314
2315 @item --s2k-cipher-algo @code{name}
2316 @opindex s2k-cipher-algo
2317 Use @code{name} as the cipher algorithm for symmetric encryption with
2318 a passphrase if @option{--personal-cipher-preferences} and
2319 @option{--cipher-algo} are not given.  The default is @value{GPGSYMENCALGO}.
2320
2321 @item --s2k-digest-algo @code{name}
2322 @opindex s2k-digest-algo
2323 Use @code{name} as the digest algorithm used to mangle the passphrases
2324 for symmetric encryption.  The default is SHA-1.
2325
2326 @item --s2k-mode @code{n}
2327 @opindex s2k-mode
2328 Selects how passphrases for symmetric encryption are mangled. If
2329 @code{n} is 0 a plain passphrase (which is in general not recommended)
2330 will be used, a 1 adds a salt (which should not be used) to the
2331 passphrase and a 3 (the default) iterates the whole process a number
2332 of times (see @option{--s2k-count}).
2333
2334 @item --s2k-count @code{n}
2335 @opindex s2k-count
2336 Specify how many times the passphrases mangling for symmetric
2337 encryption is repeated.  This value may range between 1024 and
2338 65011712 inclusive.  The default is inquired from gpg-agent.  Note
2339 that not all values in the 1024-65011712 range are legal and if an
2340 illegal value is selected, GnuPG will round up to the nearest legal
2341 value.  This option is only meaningful if @option{--s2k-mode} is set
2342 to the default of 3.
2343
2344
2345 @end table
2346
2347 @c ***************************
2348 @c ******* Compliance ********
2349 @c ***************************
2350 @node Compliance Options
2351 @subsection Compliance options
2352
2353 These options control what GnuPG is compliant to. Only one of these
2354 options may be active at a time. Note that the default setting of
2355 this is nearly always the correct one. See the INTEROPERABILITY WITH
2356 OTHER OPENPGP PROGRAMS section below before using one of these
2357 options.
2358
2359 @table @gnupgtabopt
2360
2361 @item --gnupg
2362 @opindex gnupg
2363 Use standard GnuPG behavior. This is essentially OpenPGP behavior
2364 (see @option{--openpgp}), but with some additional workarounds for common
2365 compatibility problems in different versions of PGP. This is the
2366 default option, so it is not generally needed, but it may be useful to
2367 override a different compliance option in the gpg.conf file.
2368
2369 @item --openpgp
2370 @opindex openpgp
2371 Reset all packet, cipher and digest options to strict OpenPGP
2372 behavior. Use this option to reset all previous options like
2373 @option{--s2k-*}, @option{--cipher-algo}, @option{--digest-algo} and
2374 @option{--compress-algo} to OpenPGP compliant values. All PGP
2375 workarounds are disabled.
2376
2377 @item --rfc4880
2378 @opindex rfc4880
2379 Reset all packet, cipher and digest options to strict RFC-4880
2380 behavior. Note that this is currently the same thing as
2381 @option{--openpgp}.
2382
2383 @item --rfc2440
2384 @opindex rfc2440
2385 Reset all packet, cipher and digest options to strict RFC-2440
2386 behavior.
2387
2388 @item --pgp6
2389 @opindex pgp6
2390 Set up all options to be as PGP 6 compliant as possible. This
2391 restricts you to the ciphers IDEA (if the IDEA plugin is installed),
2392 3DES, and CAST5, the hashes MD5, SHA1 and RIPEMD160, and the
2393 compression algorithms none and ZIP. This also disables
2394 --throw-keyids, and making signatures with signing subkeys as PGP 6
2395 does not understand signatures made by signing subkeys.
2396
2397 This option implies @option{--disable-mdc --escape-from-lines}.
2398
2399 @item --pgp7
2400 @opindex pgp7
2401 Set up all options to be as PGP 7 compliant as possible. This is
2402 identical to @option{--pgp6} except that MDCs are not disabled, and the
2403 list of allowable ciphers is expanded to add AES128, AES192, AES256, and
2404 TWOFISH.
2405
2406 @item --pgp8
2407 @opindex pgp8
2408 Set up all options to be as PGP 8 compliant as possible. PGP 8 is a lot
2409 closer to the OpenPGP standard than previous versions of PGP, so all
2410 this does is disable @option{--throw-keyids} and set
2411 @option{--escape-from-lines}.  All algorithms are allowed except for the
2412 SHA224, SHA384, and SHA512 digests.
2413
2414 @end table
2415
2416
2417 @c *******************************************
2418 @c ********  ESOTERIC OPTIONS  ***************
2419 @c *******************************************
2420 @node GPG Esoteric Options
2421 @subsection Doing things one usually doesn't want to do.
2422
2423 @table @gnupgtabopt
2424
2425 @item -n
2426 @itemx --dry-run
2427 @opindex dry-run
2428 Don't make any changes (this is not completely implemented).
2429
2430 @item --list-only
2431 @opindex list-only
2432 Changes the behaviour of some commands. This is like @option{--dry-run} but
2433 different in some cases. The semantic of this command may be extended in
2434 the future. Currently it only skips the actual decryption pass and
2435 therefore enables a fast listing of the encryption keys.
2436
2437 @item -i
2438 @itemx --interactive
2439 @opindex interactive
2440 Prompt before overwriting any files.
2441
2442 @item --debug-level @var{level}
2443 @opindex debug-level
2444 Select the debug level for investigating problems. @var{level} may be
2445 a numeric value or by a keyword:
2446
2447 @table @code
2448   @item none
2449   No debugging at all.  A value of less than 1 may be used instead of
2450   the keyword.
2451   @item basic
2452   Some basic debug messages.  A value between 1 and 2 may be used
2453   instead of the keyword.
2454   @item advanced
2455   More verbose debug messages.  A value between 3 and 5 may be used
2456   instead of the keyword.
2457   @item expert
2458   Even more detailed messages.  A value between 6 and 8 may be used
2459   instead of the keyword.
2460   @item guru
2461   All of the debug messages you can get. A value greater than 8 may be
2462   used instead of the keyword.  The creation of hash tracing files is
2463   only enabled if the keyword is used.
2464 @end table
2465
2466 How these messages are mapped to the actual debugging flags is not
2467 specified and may change with newer releases of this program. They are
2468 however carefully selected to best aid in debugging.
2469
2470 @item --debug @var{flags}
2471 @opindex debug
2472 Set debugging flags. All flags are or-ed and @var{flags} may be given
2473 in C syntax (e.g. 0x0042) or as a comma separated list of flag names.
2474 To get a list of all supported flags the single word "help" can be
2475 used.
2476
2477 @item --debug-all
2478 @opindex debug-all
2479 Set all useful debugging flags.
2480
2481 @item --debug-iolbf
2482 @opindex debug-iolbf
2483 Set stdout into line buffered mode.  This option is only honored when
2484 given on the command line.
2485
2486 @item --faked-system-time @var{epoch}
2487 @opindex faked-system-time
2488 This option is only useful for testing; it sets the system time back or
2489 forth to @var{epoch} which is the number of seconds elapsed since the year
2490 1970.  Alternatively @var{epoch} may be given as a full ISO time string
2491 (e.g. "20070924T154812").
2492
2493 @item --enable-progress-filter
2494 @opindex enable-progress-filter
2495 Enable certain PROGRESS status outputs. This option allows frontends
2496 to display a progress indicator while gpg is processing larger files.
2497 There is a slight performance overhead using it.
2498
2499 @item --status-fd @code{n}
2500 @opindex status-fd
2501 Write special status strings to the file descriptor @code{n}.
2502 See the file DETAILS in the documentation for a listing of them.
2503
2504 @item --status-file @code{file}
2505 @opindex status-file
2506 Same as @option{--status-fd}, except the status data is written to file
2507 @code{file}.
2508
2509 @item --logger-fd @code{n}
2510 @opindex logger-fd
2511 Write log output to file descriptor @code{n} and not to STDERR.
2512
2513 @item --log-file @code{file}
2514 @itemx --logger-file @code{file}
2515 @opindex log-file
2516 Same as @option{--logger-fd}, except the logger data is written to file
2517 @code{file}.  Note that @option{--log-file} is only implemented for
2518 GnuPG-2.
2519
2520 @item --attribute-fd @code{n}
2521 @opindex attribute-fd
2522 Write attribute subpackets to the file descriptor @code{n}. This is most
2523 useful for use with @option{--status-fd}, since the status messages are
2524 needed to separate out the various subpackets from the stream delivered
2525 to the file descriptor.
2526
2527 @item --attribute-file @code{file}
2528 @opindex attribute-file
2529 Same as @option{--attribute-fd}, except the attribute data is written to
2530 file @code{file}.
2531
2532 @item --comment @code{string}
2533 @itemx --no-comments
2534 @opindex comment
2535 Use @code{string} as a comment string in clear text signatures and ASCII
2536 armored messages or keys (see @option{--armor}). The default behavior is
2537 not to use a comment string. @option{--comment} may be repeated multiple
2538 times to get multiple comment strings. @option{--no-comments} removes
2539 all comments.  It is a good idea to keep the length of a single comment
2540 below 60 characters to avoid problems with mail programs wrapping such
2541 lines.  Note that comment lines, like all other header lines, are not
2542 protected by the signature.
2543
2544 @item --emit-version
2545 @itemx --no-emit-version
2546 @opindex emit-version
2547 Force inclusion of the version string in ASCII armored output.  If
2548 given once only the name of the program and the major number is
2549 emitted (default), given twice the minor is also emitted, given triple
2550 the micro is added, and given quad an operating system identification
2551 is also emitted.  @option{--no-emit-version} disables the version
2552 line.
2553
2554 @item --sig-notation @code{name=value}
2555 @itemx --cert-notation @code{name=value}
2556 @itemx -N, --set-notation @code{name=value}
2557 @opindex sig-notation
2558 @opindex cert-notation
2559 @opindex set-notation
2560 Put the name value pair into the signature as notation data.
2561 @code{name} must consist only of printable characters or spaces, and
2562 must contain a '@@' character in the form keyname@@domain.example.com
2563 (substituting the appropriate keyname and domain name, of course).  This
2564 is to help prevent pollution of the IETF reserved notation
2565 namespace. The @option{--expert} flag overrides the '@@'
2566 check. @code{value} may be any printable string; it will be encoded in
2567 UTF8, so you should check that your @option{--display-charset} is set
2568 correctly. If you prefix @code{name} with an exclamation mark (!), the
2569 notation data will be flagged as critical
2570 (rfc4880:5.2.3.16). @option{--sig-notation} sets a notation for data
2571 signatures. @option{--cert-notation} sets a notation for key signatures
2572 (certifications). @option{--set-notation} sets both.
2573
2574 There are special codes that may be used in notation names. "%k" will
2575 be expanded into the key ID of the key being signed, "%K" into the
2576 long key ID of the key being signed, "%f" into the fingerprint of the
2577 key being signed, "%s" into the key ID of the key making the
2578 signature, "%S" into the long key ID of the key making the signature,
2579 "%g" into the fingerprint of the key making the signature (which might
2580 be a subkey), "%p" into the fingerprint of the primary key of the key
2581 making the signature, "%c" into the signature count from the OpenPGP
2582 smartcard, and "%%" results in a single "%". %k, %K, and %f are only
2583 meaningful when making a key signature (certification), and %c is only
2584 meaningful when using the OpenPGP smartcard.
2585
2586 @item --sig-policy-url @code{string}
2587 @itemx --cert-policy-url @code{string}
2588 @itemx --set-policy-url @code{string}
2589 @opindex sig-policy-url
2590 @opindex cert-policy-url
2591 @opindex set-policy-url
2592 Use @code{string} as a Policy URL for signatures (rfc4880:5.2.3.20).  If
2593 you prefix it with an exclamation mark (!), the policy URL packet will
2594 be flagged as critical. @option{--sig-policy-url} sets a policy url for
2595 data signatures. @option{--cert-policy-url} sets a policy url for key
2596 signatures (certifications). @option{--set-policy-url} sets both.
2597
2598 The same %-expandos used for notation data are available here as well.
2599
2600 @item --sig-keyserver-url @code{string}
2601 @opindex sig-keyserver-url
2602 Use @code{string} as a preferred keyserver URL for data signatures. If
2603 you prefix it with an exclamation mark (!), the keyserver URL packet
2604 will be flagged as critical.
2605
2606 The same %-expandos used for notation data are available here as well.
2607
2608 @item --set-filename @code{string}
2609 @opindex set-filename
2610 Use @code{string} as the filename which is stored inside messages.
2611 This overrides the default, which is to use the actual filename of the
2612 file being encrypted.  Using the empty string for @var{string}
2613 effectively removes the filename from the output.
2614
2615 @item --for-your-eyes-only
2616 @itemx --no-for-your-eyes-only
2617 @opindex for-your-eyes-only
2618 Set the `for your eyes only' flag in the message. This causes GnuPG to
2619 refuse to save the file unless the @option{--output} option is given,
2620 and PGP to use a "secure viewer" with a claimed Tempest-resistant font
2621 to display the message. This option overrides @option{--set-filename}.
2622 @option{--no-for-your-eyes-only} disables this option.
2623
2624 @item --use-embedded-filename
2625 @itemx --no-use-embedded-filename
2626 @opindex use-embedded-filename
2627 Try to create a file with a name as embedded in the data. This can be
2628 a dangerous option as it allows to overwrite files. Defaults to no.
2629
2630 @item --cipher-algo @code{name}
2631 @opindex cipher-algo
2632 Use @code{name} as cipher algorithm. Running the program with the
2633 command @option{--version} yields a list of supported algorithms. If
2634 this is not used the cipher algorithm is selected from the preferences
2635 stored with the key. In general, you do not want to use this option as
2636 it allows you to violate the OpenPGP standard.
2637 @option{--personal-cipher-preferences} is the safe way to accomplish the
2638 same thing.
2639
2640 @item --digest-algo @code{name}
2641 @opindex digest-algo
2642 Use @code{name} as the message digest algorithm. Running the program
2643 with the command @option{--version} yields a list of supported algorithms. In
2644 general, you do not want to use this option as it allows you to
2645 violate the OpenPGP standard. @option{--personal-digest-preferences} is the
2646 safe way to accomplish the same thing.
2647
2648 @item --compress-algo @code{name}
2649 @opindex compress-algo
2650 Use compression algorithm @code{name}. "zlib" is RFC-1950 ZLIB
2651 compression. "zip" is RFC-1951 ZIP compression which is used by PGP.
2652 "bzip2" is a more modern compression scheme that can compress some
2653 things better than zip or zlib, but at the cost of more memory used
2654 during compression and decompression. "uncompressed" or "none"
2655 disables compression. If this option is not used, the default
2656 behavior is to examine the recipient key preferences to see which
2657 algorithms the recipient supports. If all else fails, ZIP is used for
2658 maximum compatibility.
2659
2660 ZLIB may give better compression results than ZIP, as the compression
2661 window size is not limited to 8k. BZIP2 may give even better
2662 compression results than that, but will use a significantly larger
2663 amount of memory while compressing and decompressing. This may be
2664 significant in low memory situations. Note, however, that PGP (all
2665 versions) only supports ZIP compression. Using any algorithm other
2666 than ZIP or "none" will make the message unreadable with PGP. In
2667 general, you do not want to use this option as it allows you to
2668 violate the OpenPGP standard. @option{--personal-compress-preferences} is the
2669 safe way to accomplish the same thing.
2670
2671 @item --cert-digest-algo @code{name}
2672 @opindex cert-digest-algo
2673 Use @code{name} as the message digest algorithm used when signing a
2674 key. Running the program with the command @option{--version} yields a
2675 list of supported algorithms. Be aware that if you choose an algorithm
2676 that GnuPG supports but other OpenPGP implementations do not, then some
2677 users will not be able to use the key signatures you make, or quite
2678 possibly your entire key.
2679
2680 @item --disable-cipher-algo @code{name}
2681 @opindex disable-cipher-algo
2682 Never allow the use of @code{name} as cipher algorithm.
2683 The given name will not be checked so that a later loaded algorithm
2684 will still get disabled.
2685
2686 @item --disable-pubkey-algo @code{name}
2687 @opindex disable-pubkey-algo
2688 Never allow the use of @code{name} as public key algorithm.
2689 The given name will not be checked so that a later loaded algorithm
2690 will still get disabled.
2691
2692 @item --throw-keyids
2693 @itemx --no-throw-keyids
2694 @opindex throw-keyids
2695 Do not put the recipient key IDs into encrypted messages. This helps to
2696 hide the receivers of the message and is a limited countermeasure
2697 against traffic analysis.@footnote{Using a little social engineering
2698 anyone who is able to decrypt the message can check whether one of the
2699 other recipients is the one he suspects.}  On the receiving side, it may
2700 slow down the decryption process because all available secret keys must
2701 be tried.  @option{--no-throw-keyids} disables this option. This option
2702 is essentially the same as using @option{--hidden-recipient} for all
2703 recipients.
2704
2705 @item --not-dash-escaped
2706 @opindex not-dash-escaped
2707 This option changes the behavior of cleartext signatures
2708 so that they can be used for patch files. You should not
2709 send such an armored file via email because all spaces
2710 and line endings are hashed too. You can not use this
2711 option for data which has 5 dashes at the beginning of a
2712 line, patch files don't have this. A special armor header
2713 line tells GnuPG about this cleartext signature option.
2714
2715 @item --escape-from-lines
2716 @itemx --no-escape-from-lines
2717 @opindex escape-from-lines
2718 Because some mailers change lines starting with "From " to ">From " it
2719 is good to handle such lines in a special way when creating cleartext
2720 signatures to prevent the mail system from breaking the signature. Note
2721 that all other PGP versions do it this way too.  Enabled by
2722 default. @option{--no-escape-from-lines} disables this option.
2723
2724 @item --passphrase-repeat @code{n}
2725 @opindex passphrase-repeat
2726 Specify how many times @command{@gpgname} will request a new
2727 passphrase be repeated.  This is useful for helping memorize a
2728 passphrase.  Defaults to 1 repetition.
2729
2730 @item --passphrase-fd @code{n}
2731 @opindex passphrase-fd
2732 Read the passphrase from file descriptor @code{n}. Only the first line
2733 will be read from file descriptor @code{n}. If you use 0 for @code{n},
2734 the passphrase will be read from STDIN. This can only be used if only
2735 one passphrase is supplied.
2736
2737 Note that this passphrase is only used if the option @option{--batch}
2738 has also been given.  This is different from GnuPG version 1.x.
2739
2740 @item --passphrase-file @code{file}
2741 @opindex passphrase-file
2742 Read the passphrase from file @code{file}. Only the first line will
2743 be read from file @code{file}. This can only be used if only one
2744 passphrase is supplied. Obviously, a passphrase stored in a file is
2745 of questionable security if other users can read this file. Don't use
2746 this option if you can avoid it.
2747 Note that this passphrase is only used if the option @option{--batch}
2748 has also been given.  This is different from GnuPG version 1.x.
2749
2750 @item --passphrase @code{string}
2751 @opindex passphrase
2752 Use @code{string} as the passphrase. This can only be used if only one
2753 passphrase is supplied. Obviously, this is of very questionable
2754 security on a multi-user system. Don't use this option if you can
2755 avoid it.
2756 Note that this passphrase is only used if the option @option{--batch}
2757 has also been given.  This is different from GnuPG version 1.x.
2758
2759 @item --pinentry-mode @code{mode}
2760 @opindex pinentry-mode
2761 Set the pinentry mode to @code{mode}.  Allowed values for @code{mode}
2762 are:
2763 @table @asis
2764   @item default
2765   Use the default of the agent, which is @code{ask}.
2766   @item ask
2767   Force the use of the Pinentry.
2768   @item cancel
2769   Emulate use of Pinentry's cancel button.
2770   @item error
2771   Return a Pinentry error (``No Pinentry'').
2772   @item loopback
2773   Redirect Pinentry queries to the caller.  Note that in contrast to
2774   Pinentry the user is not prompted again if he enters a bad password.
2775 @end table
2776
2777 @item --command-fd @code{n}
2778 @opindex command-fd
2779 This is a replacement for the deprecated shared-memory IPC mode.
2780 If this option is enabled, user input on questions is not expected
2781 from the TTY but from the given file descriptor. It should be used
2782 together with @option{--status-fd}. See the file doc/DETAILS in the source
2783 distribution for details on how to use it.
2784
2785 @item --command-file @code{file}
2786 @opindex command-file
2787 Same as @option{--command-fd}, except the commands are read out of file
2788 @code{file}
2789
2790 @item --allow-non-selfsigned-uid
2791 @itemx --no-allow-non-selfsigned-uid
2792 @opindex allow-non-selfsigned-uid
2793 Allow the import and use of keys with user IDs which are not
2794 self-signed. This is not recommended, as a non self-signed user ID is
2795 trivial to forge. @option{--no-allow-non-selfsigned-uid} disables.
2796
2797 @item --allow-freeform-uid
2798 @opindex allow-freeform-uid
2799 Disable all checks on the form of the user ID while generating a new
2800 one. This option should only be used in very special environments as
2801 it does not ensure the de-facto standard format of user IDs.
2802
2803 @item --ignore-time-conflict
2804 @opindex ignore-time-conflict
2805 GnuPG normally checks that the timestamps associated with keys and
2806 signatures have plausible values. However, sometimes a signature
2807 seems to be older than the key due to clock problems. This option
2808 makes these checks just a warning. See also @option{--ignore-valid-from} for
2809 timestamp issues on subkeys.
2810
2811 @item --ignore-valid-from
2812 @opindex ignore-valid-from
2813 GnuPG normally does not select and use subkeys created in the future.
2814 This option allows the use of such keys and thus exhibits the
2815 pre-1.0.7 behaviour. You should not use this option unless there
2816 is some clock problem. See also @option{--ignore-time-conflict} for timestamp
2817 issues with signatures.
2818
2819 @item --ignore-crc-error
2820 @opindex ignore-crc-error
2821 The ASCII armor used by OpenPGP is protected by a CRC checksum against
2822 transmission errors. Occasionally the CRC gets mangled somewhere on
2823 the transmission channel but the actual content (which is protected by
2824 the OpenPGP protocol anyway) is still okay. This option allows GnuPG
2825 to ignore CRC errors.
2826
2827 @item --ignore-mdc-error
2828 @opindex ignore-mdc-error
2829 This option changes a MDC integrity protection failure into a warning.
2830 This can be useful if a message is partially corrupt, but it is
2831 necessary to get as much data as possible out of the corrupt message.
2832 However, be aware that a MDC protection failure may also mean that the
2833 message was tampered with intentionally by an attacker.
2834
2835 @item --allow-weak-digest-algos
2836 @opindex allow-weak-digest-algos
2837 Signatures made with known-weak digest algorithms are normally
2838 rejected with an ``invalid digest algorithm'' message.  This option
2839 allows the verification of signatures made with such weak algorithms.
2840 MD5 is the only digest algorithm considered weak by default.  See also
2841 @option{--weak-digest} to reject other digest algorithms.
2842
2843 @item --weak-digest @code{name}
2844 @opindex weak-digest
2845 Treat the specified digest algorithm as weak.  Signatures made over
2846 weak digests algorithms are normally rejected. This option can be
2847 supplied multiple times if multiple algorithms should be considered
2848 weak.  See also @option{--allow-weak-digest-algos} to disable
2849 rejection of weak digests.  MD5 is always considered weak, and does
2850 not need to be listed explicitly.
2851
2852 @item --no-default-keyring
2853 @opindex no-default-keyring
2854 Do not add the default keyrings to the list of keyrings. Note that
2855 GnuPG will not operate without any keyrings, so if you use this option
2856 and do not provide alternate keyrings via @option{--keyring} or
2857 @option{--secret-keyring}, then GnuPG will still use the default public or
2858 secret keyrings.
2859
2860 @item --skip-verify
2861 @opindex skip-verify
2862 Skip the signature verification step. This may be
2863 used to make the decryption faster if the signature
2864 verification is not needed.
2865
2866 @item --with-key-data
2867 @opindex with-key-data
2868 Print key listings delimited by colons (like @option{--with-colons}) and
2869 print the public key data.
2870
2871 @item --fast-list-mode
2872 @opindex fast-list-mode
2873 Changes the output of the list commands to work faster; this is achieved
2874 by leaving some parts empty. Some applications don't need the user ID
2875 and the trust information given in the listings. By using this options
2876 they can get a faster listing. The exact behaviour of this option may
2877 change in future versions.  If you are missing some information, don't
2878 use this option.
2879
2880 @item --no-literal
2881 @opindex no-literal
2882 This is not for normal use. Use the source to see for what it might be useful.
2883
2884 @item --set-filesize
2885 @opindex set-filesize
2886 This is not for normal use. Use the source to see for what it might be useful.
2887
2888 @item --show-session-key
2889 @opindex show-session-key
2890 Display the session key used for one message. See
2891 @option{--override-session-key} for the counterpart of this option.
2892
2893 We think that Key Escrow is a Bad Thing; however the user should have
2894 the freedom to decide whether to go to prison or to reveal the content
2895 of one specific message without compromising all messages ever
2896 encrypted for one secret key.
2897
2898 You can also use this option if you receive an encrypted message which
2899 is abusive or offensive, to prove to the administrators of the
2900 messaging system that the ciphertext transmitted corresponds to an
2901 inappropriate plaintext so they can take action against the offending
2902 user.
2903
2904 @item --override-session-key @code{string}
2905 @opindex override-session-key
2906 Don't use the public key but the session key @code{string}. The format
2907 of this string is the same as the one printed by
2908 @option{--show-session-key}. This option is normally not used but comes
2909 handy in case someone forces you to reveal the content of an encrypted
2910 message; using this option you can do this without handing out the
2911 secret key.
2912
2913 @item --ask-sig-expire
2914 @itemx --no-ask-sig-expire
2915 @opindex ask-sig-expire
2916 When making a data signature, prompt for an expiration time. If this
2917 option is not specified, the expiration time set via
2918 @option{--default-sig-expire} is used. @option{--no-ask-sig-expire}
2919 disables this option.
2920
2921 @item --default-sig-expire
2922 @opindex default-sig-expire
2923 The default expiration time to use for signature expiration. Valid
2924 values are "0" for no expiration, a number followed by the letter d
2925 (for days), w (for weeks), m (for months), or y (for years) (for
2926 example "2m" for two months, or "5y" for five years), or an absolute
2927 date in the form YYYY-MM-DD. Defaults to "0".
2928
2929 @item --ask-cert-expire
2930 @itemx --no-ask-cert-expire
2931 @opindex ask-cert-expire
2932 When making a key signature, prompt for an expiration time. If this
2933 option is not specified, the expiration time set via
2934 @option{--default-cert-expire} is used. @option{--no-ask-cert-expire}
2935 disables this option.
2936
2937 @item --default-cert-expire
2938 @opindex default-cert-expire
2939 The default expiration time to use for key signature expiration.
2940 Valid values are "0" for no expiration, a number followed by the
2941 letter d (for days), w (for weeks), m (for months), or y (for years)
2942 (for example "2m" for two months, or "5y" for five years), or an
2943 absolute date in the form YYYY-MM-DD. Defaults to "0".
2944
2945 @item --allow-secret-key-import
2946 @opindex allow-secret-key-import
2947 This is an obsolete option and is not used anywhere.
2948
2949 @item --allow-multiple-messages
2950 @item --no-allow-multiple-messages
2951 @opindex allow-multiple-messages
2952 Allow processing of multiple OpenPGP messages contained in a single file
2953 or stream.  Some programs that call GPG are not prepared to deal with
2954 multiple messages being processed together, so this option defaults to
2955 no.  Note that versions of GPG prior to 1.4.7 always allowed multiple
2956 messages.
2957
2958 Warning: Do not use this option unless you need it as a temporary
2959 workaround!
2960
2961
2962 @item --enable-special-filenames
2963 @opindex enable-special-filenames
2964 This options enables a mode in which filenames of the form
2965 @file{-&n}, where n is a non-negative decimal number,
2966 refer to the file descriptor n and not to a file with that name.
2967
2968 @item --no-expensive-trust-checks
2969 @opindex no-expensive-trust-checks
2970 Experimental use only.
2971
2972 @item --preserve-permissions
2973 @opindex preserve-permissions
2974 Don't change the permissions of a secret keyring back to user
2975 read/write only. Use this option only if you really know what you are doing.
2976
2977 @item --default-preference-list @code{string}
2978 @opindex default-preference-list
2979 Set the list of default preferences to @code{string}. This preference
2980 list is used for new keys and becomes the default for "setpref" in the
2981 edit menu.
2982
2983 @item --default-keyserver-url @code{name}
2984 @opindex default-keyserver-url
2985 Set the default keyserver URL to @code{name}. This keyserver will be
2986 used as the keyserver URL when writing a new self-signature on a key,
2987 which includes key generation and changing preferences.
2988
2989 @item --list-config
2990 @opindex list-config
2991 Display various internal configuration parameters of GnuPG. This option
2992 is intended for external programs that call GnuPG to perform tasks, and
2993 is thus not generally useful. See the file @file{doc/DETAILS} in the
2994 source distribution for the details of which configuration items may be
2995 listed. @option{--list-config} is only usable with
2996 @option{--with-colons} set.
2997
2998 @item --list-gcrypt-config
2999 @opindex list-gcrypt-config
3000 Display various internal configuration parameters of Libgcrypt.
3001
3002 @item --gpgconf-list
3003 @opindex gpgconf-list
3004 This command is similar to @option{--list-config} but in general only
3005 internally used by the @command{gpgconf} tool.
3006
3007 @item --gpgconf-test
3008 @opindex gpgconf-test
3009 This is more or less dummy action.  However it parses the configuration
3010 file and returns with failure if the configuration file would prevent
3011 @command{gpg} from startup.  Thus it may be used to run a syntax check
3012 on the configuration file.
3013
3014 @end table
3015
3016 @c *******************************
3017 @c ******* Deprecated ************
3018 @c *******************************
3019 @node Deprecated Options
3020 @subsection Deprecated options
3021
3022 @table @gnupgtabopt
3023
3024 @item --show-photos
3025 @itemx --no-show-photos
3026 @opindex show-photos
3027 Causes @option{--list-keys}, @option{--list-sigs},
3028 @option{--list-public-keys}, @option{--list-secret-keys}, and verifying
3029 a signature to also display the photo ID attached to the key, if
3030 any. See also @option{--photo-viewer}. These options are deprecated. Use
3031 @option{--list-options [no-]show-photos} and/or @option{--verify-options
3032 [no-]show-photos} instead.
3033
3034 @item --show-keyring
3035 @opindex show-keyring
3036 Display the keyring name at the head of key listings to show which
3037 keyring a given key resides on. This option is deprecated: use
3038 @option{--list-options [no-]show-keyring} instead.
3039
3040 @item --always-trust
3041 @opindex always-trust
3042 Identical to @option{--trust-model always}. This option is deprecated.
3043
3044 @item --show-notation
3045 @itemx --no-show-notation
3046 @opindex show-notation
3047 Show signature notations in the @option{--list-sigs} or @option{--check-sigs} listings
3048 as well as when verifying a signature with a notation in it. These
3049 options are deprecated. Use @option{--list-options [no-]show-notation}
3050 and/or @option{--verify-options [no-]show-notation} instead.
3051
3052 @item --show-policy-url
3053 @itemx --no-show-policy-url
3054 @opindex show-policy-url
3055 Show policy URLs in the @option{--list-sigs} or @option{--check-sigs}
3056 listings as well as when verifying a signature with a policy URL in
3057 it. These options are deprecated. Use @option{--list-options
3058 [no-]show-policy-url} and/or @option{--verify-options
3059 [no-]show-policy-url} instead.
3060
3061
3062 @end table
3063
3064
3065 @c *******************************************
3066 @c ***************            ****************
3067 @c ***************   FILES    ****************
3068 @c ***************            ****************
3069 @c *******************************************
3070 @mansect files
3071 @node GPG Configuration
3072 @section Configuration files
3073
3074 There are a few configuration files to control certain aspects of
3075 @command{@gpgname}'s operation. Unless noted, they are expected in the
3076 current home directory (@pxref{option --homedir}).
3077
3078 @table @file
3079
3080   @item gpg.conf
3081   @cindex gpg.conf
3082   This is the standard configuration file read by @command{@gpgname} on
3083   startup.  It may contain any valid long option; the leading two dashes
3084   may not be entered and the option may not be abbreviated.  This default
3085   name may be changed on the command line (@pxref{gpg-option --options}).
3086   You should backup this file.
3087
3088 @end table
3089
3090 @c man:.RE
3091 Note that on larger installations, it is useful to put predefined files
3092 into the directory @file{@value{SYSCONFSKELDIR}} so that
3093 newly created users start up with a working configuration.
3094 For existing users a small
3095 helper script is provided to create these files (@pxref{addgnupghome}).
3096
3097 For internal purposes @command{@gpgname} creates and maintains a few other
3098 files; They all live in in the current home directory (@pxref{option
3099 --homedir}).  Only the @command{@gpgname} program may modify these files.
3100
3101
3102 @table @file
3103   @item ~/.gnupg/pubring.gpg
3104   The public keyring.  You should backup this file.
3105
3106   @item ~/.gnupg/pubring.gpg.lock
3107   The lock file for the public keyring.
3108
3109   @item ~/.gnupg/pubring.kbx
3110   The public keyring using a different format.  This file is sharred
3111   with @command{gpgsm}.  You should backup this file.
3112
3113   @item ~/.gnupg/pubring.kbx.lock
3114   The lock file for @file{pubring.kbx}.
3115
3116   @item ~/.gnupg/secring.gpg
3117   A secret keyring as used by GnuPG versions before 2.1.  It is not
3118   used by GnuPG 2.1 and later.
3119
3120   @item ~/.gnupg/.gpg-v21-migrated
3121   File indicating that a migration to GnuPG 2.1 has been done.
3122
3123   @item ~/.gnupg/trustdb.gpg
3124   The trust database.  There is no need to backup this file; it is better
3125   to backup the ownertrust values (@pxref{option --export-ownertrust}).
3126
3127   @item ~/.gnupg/trustdb.gpg.lock
3128   The lock file for the trust database.
3129
3130   @item ~/.gnupg/random_seed
3131   A file used to preserve the state of the internal random pool.
3132
3133   @item ~/.gnupg/secring.gpg.lock
3134   The lock file for the secret keyring.
3135
3136   @item ~/.gnupg/openpgp-revocs.d/
3137   This is the directory where gpg stores pre-generated revocation
3138   certificates.  The file name corresponds to the OpenPGP fingerprint of
3139   the respective key.  It is suggested to backup those certificates and
3140   if the primary private key is not stored on the disk to move them to
3141   an external storage device.  Anyone who can access theses files is
3142   able to revoke the corresponding key.  You may want to print them out.
3143   You should backup all files in this directory and take care to keep
3144   this backup closed away.
3145
3146   @item @value{DATADIR}/options.skel
3147   The skeleton options file.
3148
3149   @item @value{LIBDIR}/
3150   Default location for extensions.
3151
3152 @end table
3153
3154 @c man:.RE
3155 Operation is further controlled by a few environment variables:
3156
3157 @table @asis
3158
3159   @item HOME
3160   Used to locate the default home directory.
3161
3162   @item GNUPGHOME
3163   If set directory used instead of "~/.gnupg".
3164
3165   @item GPG_AGENT_INFO
3166   This variable was used by GnuPG versions before 2.1
3167
3168   @item PINENTRY_USER_DATA
3169   This value is passed via gpg-agent to pinentry.  It is useful to convey
3170   extra information to a custom pinentry.
3171
3172   @item COLUMNS
3173   @itemx LINES
3174   Used to size some displays to the full size of the screen.
3175
3176
3177   @item LANGUAGE
3178   Apart from its use by GNU, it is used in the W32 version to override the
3179   language selection done through the Registry.  If used and set to a
3180   valid and available language name (@var{langid}), the file with the
3181   translation is loaded from
3182
3183   @code{@var{gpgdir}/gnupg.nls/@var{langid}.mo}.  Here @var{gpgdir} is the
3184   directory out of which the gpg binary has been loaded.  If it can't be
3185   loaded the Registry is tried and as last resort the native Windows
3186   locale system is used.
3187
3188 @end table
3189
3190
3191 @c *******************************************
3192 @c ***************            ****************
3193 @c ***************  EXAMPLES  ****************
3194 @c ***************            ****************
3195 @c *******************************************
3196 @mansect examples
3197 @node GPG Examples
3198 @section Examples
3199
3200 @table @asis
3201
3202 @item gpg -se -r @code{Bob} @code{file}
3203 sign and encrypt for user Bob
3204
3205 @item gpg --clearsign @code{file}
3206 make a clear text signature
3207
3208 @item gpg -sb @code{file}
3209 make a detached signature
3210
3211 @item gpg -u 0x12345678 -sb @code{file}
3212 make a detached signature with the key 0x12345678
3213
3214 @item gpg --list-keys @code{user_ID}
3215 show keys
3216
3217 @item gpg --fingerprint @code{user_ID}
3218 show fingerprint
3219
3220 @item gpg --verify @code{pgpfile}
3221 @itemx gpg --verify @code{sigfile}
3222 Verify the signature of the file but do not output the data. The
3223 second form is used for detached signatures, where @code{sigfile}
3224 is the detached signature (either ASCII armored or binary) and
3225 are the signed data; if this is not given, the name of
3226 the file holding the signed data is constructed by cutting off the
3227 extension (".asc" or ".sig") of @code{sigfile} or by asking the
3228 user for the filename.
3229 @end table
3230
3231
3232 @c *******************************************
3233 @c ***************            ****************
3234 @c ***************  USER ID   ****************
3235 @c ***************            ****************
3236 @c *******************************************
3237 @mansect how to specify a user id
3238 @ifset isman
3239 @include specify-user-id.texi
3240 @end ifset
3241
3242 @mansect return value
3243 @chapheading RETURN VALUE
3244
3245 The program returns 0 if everything was fine, 1 if at least
3246 a signature was bad, and other error codes for fatal errors.
3247
3248 @mansect warnings
3249 @chapheading WARNINGS
3250
3251 Use a *good* password for your user account and a *good* passphrase
3252 to protect your secret key. This passphrase is the weakest part of the
3253 whole system. Programs to do dictionary attacks on your secret keyring
3254 are very easy to write and so you should protect your "~/.gnupg/"
3255 directory very well.
3256
3257 Keep in mind that, if this program is used over a network (telnet), it
3258 is *very* easy to spy out your passphrase!
3259
3260 If you are going to verify detached signatures, make sure that the
3261 program knows about it; either give both filenames on the command line
3262 or use @samp{-} to specify STDIN.
3263
3264 @mansect interoperability
3265 @chapheading INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS
3266
3267 GnuPG tries to be a very flexible implementation of the OpenPGP
3268 standard. In particular, GnuPG implements many of the optional parts
3269 of the standard, such as the SHA-512 hash, and the ZLIB and BZIP2
3270 compression algorithms. It is important to be aware that not all
3271 OpenPGP programs implement these optional algorithms and that by
3272 forcing their use via the @option{--cipher-algo},
3273 @option{--digest-algo}, @option{--cert-digest-algo}, or
3274 @option{--compress-algo} options in GnuPG, it is possible to create a
3275 perfectly valid OpenPGP message, but one that cannot be read by the
3276 intended recipient.
3277
3278 There are dozens of variations of OpenPGP programs available, and each
3279 supports a slightly different subset of these optional algorithms.
3280 For example, until recently, no (unhacked) version of PGP supported
3281 the BLOWFISH cipher algorithm. A message using BLOWFISH simply could
3282 not be read by a PGP user. By default, GnuPG uses the standard
3283 OpenPGP preferences system that will always do the right thing and
3284 create messages that are usable by all recipients, regardless of which
3285 OpenPGP program they use. Only override this safe default if you
3286 really know what you are doing.
3287
3288 If you absolutely must override the safe default, or if the preferences
3289 on a given key are invalid for some reason, you are far better off using
3290 the @option{--pgp6}, @option{--pgp7}, or @option{--pgp8} options. These
3291 options are safe as they do not force any particular algorithms in
3292 violation of OpenPGP, but rather reduce the available algorithms to a
3293 "PGP-safe" list.
3294
3295 @mansect bugs
3296 @chapheading BUGS
3297
3298 On older systems this program should be installed as setuid(root). This
3299 is necessary to lock memory pages. Locking memory pages prevents the
3300 operating system from writing memory pages (which may contain
3301 passphrases or other sensitive material) to disk. If you get no
3302 warning message about insecure memory your operating system supports
3303 locking without being root. The program drops root privileges as soon
3304 as locked memory is allocated.
3305
3306 Note also that some systems (especially laptops) have the ability to
3307 ``suspend to disk'' (also known as ``safe sleep'' or ``hibernate'').
3308 This writes all memory to disk before going into a low power or even
3309 powered off mode.  Unless measures are taken in the operating system
3310 to protect the saved memory, passphrases or other sensitive material
3311 may be recoverable from it later.
3312
3313 Before you report a bug you should first search the mailing list
3314 archives for similar problems and second check whether such a bug has
3315 already been reported to our bug tracker at http://bugs.gnupg.org .
3316
3317 @c *******************************************
3318 @c ***************              **************
3319 @c ***************  UNATTENDED  **************
3320 @c ***************              **************
3321 @c *******************************************
3322 @manpause
3323 @node Unattended Usage of GPG
3324 @section Unattended Usage
3325
3326 @command{gpg} is often used as a backend engine by other software.  To help
3327 with this a machine interface has been defined to have an unambiguous
3328 way to do this.  The options @option{--status-fd} and @option{--batch}
3329 are almost always required for this.
3330
3331 @menu
3332 * Unattended GPG key generation::  Unattended key generation
3333 @end menu
3334
3335
3336 @node Unattended GPG key generation
3337 @subsection Unattended key generation
3338
3339 The command @option{--gen-key} may be used along with the option
3340 @option{--batch} for unattended key generation.  The parameters are
3341 either read from stdin or given as a file on the command line.
3342 The format of the parameter file is as follows:
3343
3344 @itemize @bullet
3345   @item Text only, line length is limited to about 1000 characters.
3346   @item UTF-8 encoding must be used to specify non-ASCII characters.
3347   @item Empty lines are ignored.
3348   @item Leading and trailing while space is ignored.
3349   @item A hash sign as the first non white space character indicates
3350   a comment line.
3351   @item Control statements are indicated by a leading percent sign, the
3352   arguments are separated by white space from the keyword.
3353   @item Parameters are specified by a keyword, followed by a colon.  Arguments
3354   are separated by white space.
3355   @item
3356   The first parameter must be @samp{Key-Type}; control statements may be
3357   placed anywhere.
3358   @item
3359   The order of the parameters does not matter except for @samp{Key-Type}
3360   which must be the first parameter.  The parameters are only used for
3361   the generated keyblock (primary and subkeys); parameters from previous
3362   sets are not used.  Some syntactically checks may be performed.
3363   @item
3364   Key generation takes place when either the end of the parameter file
3365   is reached, the next @samp{Key-Type} parameter is encountered or at the
3366   control statement @samp{%commit} is encountered.
3367 @end itemize
3368
3369 @noindent
3370 Control statements:
3371
3372 @table @asis
3373
3374 @item %echo @var{text}
3375 Print @var{text} as diagnostic.
3376
3377 @item %dry-run
3378 Suppress actual key generation (useful for syntax checking).
3379
3380 @item %commit
3381 Perform the key generation.  Note that an implicit commit is done at
3382 the next @asis{Key-Type} parameter.
3383
3384 @item %pubring @var{filename}
3385 @itemx %secring @var{filename}
3386 Do not write the key to the default or commandline given keyring but
3387 to @var{filename}.  This must be given before the first commit to take
3388 place, duplicate specification of the same filename is ignored, the
3389 last filename before a commit is used.  The filename is used until a
3390 new filename is used (at commit points) and all keys are written to
3391 that file. If a new filename is given, this file is created (and
3392 overwrites an existing one).  For GnuPG versions prior to 2.1, both
3393 control statements must be given. For GnuPG 2.1 and later
3394 @samp{%secring} is a no-op.
3395
3396 @item %ask-passphrase
3397 @itemx %no-ask-passphrase
3398 This option is a no-op for GnuPG 2.1 and later.
3399
3400 @item %no-protection
3401 Using this option allows the creation of keys without any passphrase
3402 protection.  This option is mainly intended for regression tests.
3403
3404 @item %transient-key
3405 If given the keys are created using a faster and a somewhat less
3406 secure random number generator.  This option may be used for keys
3407 which are only used for a short time and do not require full
3408 cryptographic strength.  It takes only effect if used together with
3409 the control statement @samp{%no-protection}.
3410
3411 @end table
3412
3413 @noindent
3414 General Parameters:
3415
3416 @table @asis
3417
3418 @item Key-Type: @var{algo}
3419 Starts a new parameter block by giving the type of the primary
3420 key. The algorithm must be capable of signing.  This is a required
3421 parameter.  @var{algo} may either be an OpenPGP algorithm number or a
3422 string with the algorithm name.  The special value @samp{default} may
3423 be used for @var{algo} to create the default key type; in this case a
3424 @samp{Key-Usage} shall not be given and @samp{default} also be used
3425 for @samp{Subkey-Type}.
3426
3427 @item Key-Length: @var{nbits}
3428 The requested length of the generated key in bits.  The default is
3429 returned by running the command @samp{@gpgname --gpgconf-list}.
3430
3431 @item Key-Grip: @var{hexstring}
3432 This is optional and used to generate a CSR or certificate for an
3433 already existing key.  Key-Length will be ignored when given.
3434
3435 @item Key-Usage: @var{usage-list}
3436 Space or comma delimited list of key usages.  Allowed values are
3437 @samp{encrypt}, @samp{sign}, and @samp{auth}.  This is used to
3438 generate the key flags.  Please make sure that the algorithm is
3439 capable of this usage.  Note that OpenPGP requires that all primary
3440 keys are capable of certification, so no matter what usage is given
3441 here, the @samp{cert} flag will be on.  If no @samp{Key-Usage} is
3442 specified and the @samp{Key-Type} is not @samp{default}, all allowed
3443 usages for that particular algorithm are used; if it is not given but
3444 @samp{default} is used the usage will be @samp{sign}.
3445
3446 @item Subkey-Type: @var{algo}
3447 This generates a secondary key (subkey).  Currently only one subkey
3448 can be handled.  See also @samp{Key-Type} above.
3449
3450 @item Subkey-Length: @var{nbits}
3451 Length of the secondary key (subkey) in bits.  The default is returned
3452 by running the command @samp{@gpgname --gpgconf-list}".
3453
3454 @item Subkey-Usage: @var{usage-list}
3455 Key usage lists for a subkey; similar to @samp{Key-Usage}.
3456
3457 @item Passphrase: @var{string}
3458 If you want to specify a passphrase for the secret key, enter it here.
3459 Default is to use the Pinentry dialog to ask for a passphrase.
3460
3461 @item Name-Real: @var{name}
3462 @itemx Name-Comment: @var{comment}
3463 @itemx Name-Email: @var{email}
3464 The three parts of a user name.  Remember to use UTF-8 encoding here.
3465 If you don't give any of them, no user ID is created.
3466
3467 @item Expire-Date: @var{iso-date}|(@var{number}[d|w|m|y])
3468 Set the expiration date for the key (and the subkey).  It may either
3469 be entered in ISO date format (e.g. "20000815T145012") or as number of
3470 days, weeks, month or years after the creation date.  The special
3471 notation "seconds=N" is also allowed to specify a number of seconds
3472 since creation.  Without a letter days are assumed.  Note that there
3473 is no check done on the overflow of the type used by OpenPGP for
3474 timestamps.  Thus you better make sure that the given value make
3475 sense.  Although OpenPGP works with time intervals, GnuPG uses an
3476 absolute value internally and thus the last year we can represent is
3477 2105.
3478
3479 @item  Creation-Date: @var{iso-date}
3480 Set the creation date of the key as stored in the key information and
3481 which is also part of the fingerprint calculation.  Either a date like
3482 "1986-04-26" or a full timestamp like "19860426T042640" may be used.
3483 The time is considered to be UTC.  The special notation "seconds=N"
3484 may be used to directly specify a the number of seconds since Epoch
3485 (Unix time).  If it is not given the current time is used.
3486
3487 @item Preferences: @var{string}
3488 Set the cipher, hash, and compression preference values for this key.
3489 This expects the same type of string as the sub-command @samp{setpref}
3490 in the @option{--edit-key} menu.
3491
3492 @item  Revoker: @var{algo}:@var{fpr} [sensitive]
3493 Add a designated revoker to the generated key.  Algo is the public key
3494 algorithm of the designated revoker (i.e. RSA=1, DSA=17, etc.)
3495 @var{fpr} is the fingerprint of the designated revoker.  The optional
3496 @samp{sensitive} flag marks the designated revoker as sensitive
3497 information.  Only v4 keys may be designated revokers.
3498
3499 @item Keyserver: @var{string}
3500 This is an optional parameter that specifies the preferred keyserver
3501 URL for the key.
3502
3503 @item Handle: @var{string}
3504 This is an optional parameter only used with the status lines
3505 KEY_CREATED and KEY_NOT_CREATED.  @var{string} may be up to 100
3506 characters and should not contain spaces.  It is useful for batch key
3507 generation to associate a key parameter block with a status line.
3508
3509 @end table
3510
3511 @noindent
3512 Here is an example on how to create a key:
3513 @smallexample
3514 $ cat >foo <<EOF
3515      %echo Generating a basic OpenPGP key
3516      Key-Type: DSA
3517      Key-Length: 1024
3518      Subkey-Type: ELG-E
3519      Subkey-Length: 1024
3520      Name-Real: Joe Tester
3521      Name-Comment: with stupid passphrase
3522      Name-Email: joe@@foo.bar
3523      Expire-Date: 0
3524      Passphrase: abc
3525      %pubring foo.pub
3526      %secring foo.sec
3527      # Do a commit here, so that we can later print "done" :-)
3528      %commit
3529      %echo done
3530 EOF
3531 $ @gpgname --batch --gen-key foo
3532  [...]
3533 $ @gpgname --no-default-keyring --secret-keyring ./foo.sec \
3534        --keyring ./foo.pub --list-secret-keys
3535 /home/wk/work/gnupg-stable/scratch/foo.sec
3536 ------------------------------------------
3537 sec  1024D/915A878D 2000-03-09 Joe Tester (with stupid passphrase) <joe@@foo.bar>
3538 ssb  1024g/8F70E2C0 2000-03-09
3539 @end smallexample
3540
3541
3542 @noindent
3543 If you want to create a key with the default algorithms you would use
3544 these parameters:
3545 @smallexample
3546      %echo Generating a default key
3547      Key-Type: default
3548      Subkey-Type: default
3549      Name-Real: Joe Tester
3550      Name-Comment: with stupid passphrase
3551      Name-Email: joe@@foo.bar
3552      Expire-Date: 0
3553      Passphrase: abc
3554      %pubring foo.pub
3555      %secring foo.sec
3556      # Do a commit here, so that we can later print "done" :-)
3557      %commit
3558      %echo done
3559 @end smallexample
3560
3561
3562
3563
3564 @mansect see also
3565 @ifset isman
3566 @command{gpgv}(1),
3567 @command{gpgsm}(1),
3568 @command{gpg-agent}(1)
3569 @end ifset
3570 @include see-also-note.texi