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