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