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