1GPG(1)                       GNU Privacy Guard 2.2                      GPG(1)
2
3
4

NAME

6       gpg - OpenPGP encryption and signing tool
7

SYNOPSIS

9       gpg [--homedir dir] [--options file] [options] command [args]
10
11
12
13

DESCRIPTION

15       gpg  is the OpenPGP part of the GNU Privacy Guard (GnuPG). It is a tool
16       to provide digital encryption and signing services  using  the  OpenPGP
17       standard.  gpg  features  complete key management and all the bells and
18       whistles you would expect from a full OpenPGP implementation.
19
20       There are two main versions of GnuPG: GnuPG 1.x and GnuPG  2.x.   GnuPG
21       2.x  supports modern encryption algorithms and thus should be preferred
22       over GnuPG 1.x.  You only need  to  use  GnuPG  1.x  if  your  platform
23       doesn't  support  GnuPG 2.x, or you need support for some features that
24       GnuPG 2.x has deprecated, e.g.,  decrypting  data  created  with  PGP-2
25       keys.
26
27       If  you  are  looking for version 1 of GnuPG, you may find that version
28       installed under the name gpg1.
29
30
31
32
33
34
35

RETURN VALUE

37       The program returns 0 if everything was fine, 1 if at least a signature
38       was bad, and other error codes for fatal errors.
39
40

WARNINGS

42       Use  a *good* password for your user account and a *good* passphrase to
43       protect your secret key. This passphrase is the  weakest  part  of  the
44       whole  system. Programs to do dictionary attacks on your secret keyring
45       are very easy to write and  so  you  should  protect  your  "~/.gnupg/"
46       directory very well.
47
48       Keep  in mind that, if this program is used over a network (telnet), it
49       is *very* easy to spy out your passphrase!
50
51       If you are going to verify detached signatures, make sure that the pro‐
52       gram  knows about it; either give both filenames on the command line or
53       use '-' to specify STDIN.
54
55       For scripted or other unattended use  of  gpg  make  sure  to  use  the
56       machine-parseable  interface  and  not  the  default interface which is
57       intended for direct use by  humans.   The  machine-parseable  interface
58       provides  a stable and well documented API independent of the locale or
59       future changes of gpg.   To  enable  this  interface  use  the  options
60       --with-colons  and  --status-fd.   For  certain  operations  the option
61       --command-fd may come handy too.   See  this  man  page  and  the  file
62DETAILS’  for the specification of the interface.  Note that the GnuPG
63       ``info'' pages as well as the PDF version of the GnuPG manual  features
64       a  chapter  on  unattended use of GnuPG.  As an alternative the library
65       GPGME can be used as a high-level abstraction on top of that interface.
66
67

INTEROPERABILITY

69       GnuPG tries to be a very flexible implementation of the  OpenPGP  stan‐
70       dard. In particular, GnuPG implements many of the optional parts of the
71       standard, such as the SHA-512 hash, and the ZLIB and BZIP2  compression
72       algorithms.  It  is important to be aware that not all OpenPGP programs
73       implement these optional algorithms and that by forcing their  use  via
74       the  --cipher-algo,  --digest-algo,  --cert-digest-algo, or --compress-
75       algo options in GnuPG, it is  possible  to  create  a  perfectly  valid
76       OpenPGP message, but one that cannot be read by the intended recipient.
77
78       There  are dozens of variations of OpenPGP programs available, and each
79       supports a slightly different subset of these optional algorithms.  For
80       example,  until  recently,  no  (unhacked) version of PGP supported the
81       BLOWFISH cipher algorithm. A message using BLOWFISH simply could not be
82       read by a PGP user. By default, GnuPG uses the standard OpenPGP prefer‐
83       ences system that will always do the right thing  and  create  messages
84       that  are usable by all recipients, regardless of which OpenPGP program
85       they use. Only override this safe default if you really know  what  you
86       are doing.
87
88       If you absolutely must override the safe default, or if the preferences
89       on a given key are invalid for some reason,  you  are  far  better  off
90       using  the --pgp6, --pgp7, or --pgp8 options. These options are safe as
91       they do not force any particular algorithms in  violation  of  OpenPGP,
92       but rather reduce the available algorithms to a "PGP-safe" list.
93
94

COMMANDS

96       Commands  are  not  distinguished from options except for the fact that
97       only one command is allowed.  Generally  speaking,  irrelevant  options
98       are silently ignored, and may not be checked for correctness.
99
100       gpg  may  be run with no commands. In this case it will print a warning
101       perform a reasonable action depending on the type of file it  is  given
102       as input (an encrypted message is decrypted, a signature is verified, a
103       file containing keys is listed, etc.).
104
105       If you run into any problems, please add the option  --verbose  to  the
106       invocation to see more diagnostics.
107
108
109
110
111
112
113   Commands not specific to the function
114
115
116
117       --version
118              Print  the program version and licensing information.  Note that
119              you cannot abbreviate this command.
120
121
122       --help
123       -h     Print a usage message summarizing the most  useful  command-line
124              options.   Note that you cannot arbitrarily abbreviate this com‐
125              mand (though you can use its short form -h).
126
127
128       --warranty
129              Print warranty information.
130
131
132       --dump-options
133              Print a list of all available options and commands.   Note  that
134              you cannot abbreviate this command.
135
136   Commands to select the type of operation
137
138
139
140
141
142       --sign
143       -s     Sign  a message. This command may be combined with --encrypt (to
144              sign and encrypt a message), --symmetric (to sign and  symmetri‐
145              cally  encrypt a message), or both --encrypt and --symmetric (to
146              sign and encrypt a message that can be decrypted using a  secret
147              key  or  a passphrase).  The signing key is chosen by default or
148              can be set explicitly using the --local-user  and  --default-key
149              options.
150
151
152       --clear-sign
153       --clearsign
154              Make  a  cleartext signature.  The content in a cleartext signa‐
155              ture is readable without any special software. OpenPGP  software
156              is  only  needed  to verify the signature.  cleartext signatures
157              may modify end-of-line whitespace for platform independence  and
158              are not intended to be reversible.  The signing key is chosen by
159              default or can be set  explicitly  using  the  --local-user  and
160              --default-key options.
161
162
163
164       --detach-sign
165       -b     Make a detached signature.
166
167
168       --encrypt
169       -e     Encrypt  data  to  one  or more public keys. This command may be
170              combined with --sign (to sign and encrypt a message),  --symmet‐
171              ric  (to  encrypt a message that can be decrypted using a secret
172              key or a passphrase), or --sign and --symmetric together (for  a
173              signed  message  that  can  be decrypted using a secret key or a
174              passphrase).  --recipient and related options specify which pub‐
175              lic keys to use for encryption.
176
177
178       --symmetric
179       -c     Encrypt  with a symmetric cipher using a passphrase. The default
180              symmetric cipher used is AES-128, but may  be  chosen  with  the
181              --cipher-algo  option.  This command may be combined with --sign
182              (for a signed and symmetrically  encrypted  message),  --encrypt
183              (for  a  message  that  may  be  decrypted via a secret key or a
184              passphrase), or --sign and --encrypt together (for a signed mes‐
185              sage  that  may  be decrypted via a secret key or a passphrase).
186              gpg caches the passphrase used for symmetric encryption so  that
187              a decrypt operation may not require that the user needs to enter
188              the passphrase.  The option --no-symkey-cache  can  be  used  to
189              disable this feature.
190
191
192       --store
193              Store only (make a simple literal data packet).
194
195
196       --decrypt
197       -d     Decrypt  the file given on the command line (or STDIN if no file
198              is specified) and write it to STDOUT (or the file specified with
199              --output).  If  the  decrypted  file is signed, the signature is
200              also verified. This command differs from the default  operation,
201              as it never writes to the filename which is included in the file
202              and it rejects files that don't begin with an encrypted message.
203
204
205       --verify
206              Assume that the first argument is a signed file  and  verify  it
207              without generating any output.  With no arguments, the signature
208              packet is read from STDIN.  If only one argument is  given,  the
209              specified file is expected to include a complete signature.
210
211              With more than one argument, the first argument should specify a
212              file with a detached signature and the  remaining  files  should
213              contain the signed data. To read the signed data from STDIN, use
214              '-' as the second filename.  For security  reasons,  a  detached
215              signature  will  not  read the signed material from STDIN if not
216              explicitly specified.
217
218              Note: If the option --batch is not used, gpg may assume  that  a
219              single argument is a file with a detached signature, and it will
220              try to find a matching data file by stripping certain  suffixes.
221              Using  this historical feature to verify a detached signature is
222              strongly discouraged; you should always specify  the  data  file
223              explicitly.
224
225              Note:  When  verifying  a cleartext signature, gpg verifies only
226              what makes up the cleartext signed data and not any  extra  data
227              outside  of the cleartext signature or the header lines directly
228              following the dash marker line.  The option --output may be used
229              to  write  out  the actual signed data, but there are other pit‐
230              falls with this format as well.  It is suggested to avoid clear‐
231              text signatures in favor of detached signatures.
232
233              Note:  Sometimes  the  use of the gpgv tool is easier than using
234              the full-fledged gpg with this option.  gpgv is designed to com‐
235              pare signed data against a list of trusted keys and returns with
236              success only for a good signature.  It has its own manual page.
237
238
239
240       --multifile
241              This modifies certain other commands to  accept  multiple  files
242              for  processing on the command line or read from STDIN with each
243              filename on a separate line. This allows for many  files  to  be
244              processed  at once. --multifile may currently be used along with
245              --verify, --encrypt, and --decrypt. Note that --multifile --ver‐
246              ify may not be used with detached signatures.
247
248
249       --verify-files
250              Identical to --multifile --verify.
251
252
253       --encrypt-files
254              Identical to --multifile --encrypt.
255
256
257       --decrypt-files
258              Identical to --multifile --decrypt.
259
260
261       --list-keys
262       -k
263       --list-public-keys
264              List  the  specified  keys.   If no keys are specified, then all
265              keys from the configured public keyrings are listed.
266
267              Never use the output of this command in scripts  or  other  pro‐
268              grams.  The output is intended only for humans and its format is
269              likely to change.  The --with-colons option emits the output  in
270              a stable, machine-parseable format, which is intended for use by
271              scripts and other programs.
272
273
274       --list-secret-keys
275       -K     List the specified secret keys.  If no keys are specified,  then
276              all  known  secret  keys are listed.  A # after the initial tags
277              sec or ssb means that the secret key or subkey is currently  not
278              usable.   We  also say that this key has been taken offline (for
279              example, a primary key can be taken offline by exporting the key
280              using  the  command  --export-secret-subkeys).   A > after these
281              tags indicate that the key is stored on a smartcard.   See  also
282              --list-keys.
283
284
285       --check-signatures
286       --check-sigs
287              Same  as  --list-keys,  but  the key signatures are verified and
288              listed too.  Note that for performance  reasons  the  revocation
289              status of a signing key is not shown.  This command has the same
290              effect as using --list-keys with --with-sig-check.
291
292              The status of the verification is indicated by a  flag  directly
293              following  the  "sig"  tag  (and thus before the flags described
294              below.  A "!" indicates that the signature has been successfully
295              verified,  a "-" denotes a bad signature and a "%" is used if an
296              error occurred while checking the signature  (e.g.  a  non  sup‐
297              ported  algorithm).   Signatures  where  the  public  key is not
298              available are not  listed;  to  see  their  keyids  the  command
299              --list-sigs can be used.
300
301              For  each  signature  listed, there are several flags in between
302              the signature status flag and keyid.   These  flags  give  addi‐
303              tional  information  about  each  key  signature.   From left to
304              right, they are the numbers 1-3 for certificate check level (see
305              --ask-cert-level),  "L"  for a local or non-exportable signature
306              (see --lsign-key), "R" for a  nonRevocable  signature  (see  the
307              --edit-key  command "nrsign"), "P" for a signature that contains
308              a policy URL (see --cert-policy-url), "N" for a  signature  that
309              contains  a  notation  (see --cert-notation), "X" for an eXpired
310              signature (see --ask-cert-expire), and the numbers  1-9  or  "T"
311              for  10  and  above  to indicate trust signature levels (see the
312              --edit-key command "tsign").
313
314
315
316       --locate-keys
317       --locate-external-keys
318              Locate the keys given as arguments.  This command basically uses
319              the  same algorithm as used when locating keys for encryption or
320              signing and may thus be used to see what keys gpg might use.  In
321              particular  external methods as defined by --auto-key-locate may
322              be used to locate a key.  Only  public  keys  are  listed.   The
323              variant  --locate-external-keys  does  not  consider  a  locally
324              existing key and can thus be used to force the refresh of a  key
325              via the defined external methods.
326
327
328       --show-keys
329              This commands takes OpenPGP keys as input and prints information
330              about them in the same way  the  command  --list-keys  does  for
331              locally stored key.  In addition the list options show-unusable-
332              uids, show-unusable-subkeys, show-notations and show-policy-urls
333              are  also enabled.  As usual for automated processing, this com‐
334              mand should be combined with the option --with-colons.
335
336
337       --fingerprint
338              List all keys (or the specified ones) along with  their  finger‐
339              prints.  This  is  the  same  output as --list-keys but with the
340              additional output of a line with the fingerprint.  May  also  be
341              combined  with  --check-signatures.   If  this  command is given
342              twice, the fingerprints of all secondary keys  are  listed  too.
343              This  command also forces pretty printing of fingerprints if the
344              keyid format has been set to "none".
345
346
347       --list-packets
348              List only the sequence of packets.  This command is only  useful
349              for  debugging.   When used with option --verbose the actual MPI
350              values are dumped and not only their  lengths.   Note  that  the
351              output of this command may change with new releases.
352
353
354
355       --edit-card
356       --card-edit
357              Present  a  menu to work with a smartcard. The subcommand "help"
358              provides an overview  on  available  commands.  For  a  detailed
359              description, please see the Card HOWTO at https://gnupg.org/doc
360              umentation/howtos.html#GnuPG-cardHOWTO .
361
362
363       --card-status
364              Show the content of the smart card.
365
366
367       --change-pin
368              Present a menu to allow changing the PIN of  a  smartcard.  This
369              functionality  is also available as the subcommand "passwd" with
370              the --edit-card command.
371
372
373       --delete-keys name
374              Remove key from the public keyring. In batch mode  either  --yes
375              is required or the key must be specified by fingerprint. This is
376              a safeguard against accidental deletion of  multiple  keys.   If
377              the  exclamation  mark  syntax is used with the fingerprint of a
378              subkey only that subkey is deleted; if the exclamation  mark  is
379              used  with  the fingerprint of the primary key the entire public
380              key is deleted.
381
382
383       --delete-secret-keys name
384              Remove key from the secret keyring. In batch mode the  key  must
385              be  specified  by  fingerprint.  The option --yes can be used to
386              advice gpg-agent not to request a confirmation.  This extra pre-
387              caution  is  done  because gpg can't be sure that the secret key
388              (as controlled by gpg-agent) is only used for the given  OpenPGP
389              public  key.   If  the  exclamation mark syntax is used with the
390              fingerprint of a subkey only the secret part of that  subkey  is
391              deleted; if the exclamation mark is used with the fingerprint of
392              the primary key only the secret  part  of  the  primary  key  is
393              deleted.
394
395
396
397       --delete-secret-and-public-key name
398              Same  as  --delete-key,  but  if a secret key exists, it will be
399              removed first. In batch mode the key must be specified  by  fin‐
400              gerprint.   The option --yes can be used to advice gpg-agent not
401              to request a confirmation.
402
403
404       --export
405              Either export all keys from all keyrings (default  keyrings  and
406              those  registered via option --keyring), or if at least one name
407              is given, those of the given name. The exported keys are written
408              to  STDOUT  or  to  the  file  given  with option --output.  Use
409              together with --armor to mail those keys.
410
411
412       --send-keys keyIDs
413              Similar to --export but sends the keys to a keyserver.   Finger‐
414              prints may be used instead of key IDs.  Don't send your complete
415              keyring to a keyserver --- select only those keys which are  new
416              or changed by you.  If no keyIDs are given, gpg does nothing.
417
418
419       --export-secret-keys
420       --export-secret-subkeys
421              Same  as  --export,  but  exports  the secret keys instead.  The
422              exported keys are written to STDOUT or to the  file  given  with
423              option  --output.   This  command  is  often used along with the
424              option --armor to allow for easy printing of the key  for  paper
425              backup;  however the external tool paperkey does a better job of
426              creating backups on paper.  Note that exporting a secret key can
427              be  a  security risk if the exported keys are sent over an inse‐
428              cure channel.
429
430              The second form of the command has the special property to  ren‐
431              der  the  secret  part of the primary key useless; this is a GNU
432              extension to  OpenPGP  and  other  implementations  can  not  be
433              expected to successfully import such a key.  Its intended use is
434              in generating a full key with an additional signing subkey on  a
435              dedicated  machine.   This  command then exports the key without
436              the primary key to the main machine.
437
438              GnuPG may ask you to enter the passphrase for the key.  This  is
439              required,  because  the internal protection method of the secret
440              key is different from the one specified by the OpenPGP protocol.
441
442
443       --export-ssh-key
444              This command is used to export a key in the OpenSSH  public  key
445              format.   It  requires the specification of one key by the usual
446              means and exports the latest valid subkey which has an authenti‐
447              cation  capability  to  STDOUT  or to the file given with option
448              --output.  That output can directly be added  to  ssh's  ‘autho‐
449              rized_key’ file.
450
451              By  specifying the key to export using a key ID or a fingerprint
452              suffixed with an exclamation mark (!), a specific subkey or  the
453              primary  key  can  be exported.  This does not even require that
454              the key has the authentication capability flag set.
455
456
457       --import
458       --fast-import
459              Import/merge keys. This adds the given keys to the keyring.  The
460              fast version is currently just a synonym.
461
462              There  are  a  few  other options which control how this command
463              works.  Most notable here  is  the  --import-options  merge-only
464              option  which does not insert new keys but does only the merging
465              of new signatures, user-IDs and subkeys.
466
467
468       --receive-keys keyIDs
469       --recv-keys keyIDs
470              Import the keys with the given keyIDs from a keyserver.
471
472
473       --refresh-keys
474              Request updates from a keyserver for keys that already exist  on
475              the  local  keyring.  This is useful for updating a key with the
476              latest signatures, user IDs, etc. Calling this with no arguments
477              will refresh the entire keyring.
478
479
480       --search-keys names
481              Search  the  keyserver for the given names. Multiple names given
482              here will be joined together to create the search string for the
483              keyserver.  Note that keyservers search for names in a different
484              and simpler way than gpg does.  The best choice is to use a mail
485              address.   Due  to  data privacy reasons keyservers may even not
486              even allow searching by user id or mail  address  and  thus  may
487              only  return results when being used with the --recv-key command
488              to search by key fingerprint or keyid.
489
490
491       --fetch-keys URIs
492              Retrieve keys located at the specified URIs. Note that different
493              installations  of  GnuPG  may support different protocols (HTTP,
494              FTP, LDAP, etc.).  When using HTTPS  the  system  provided  root
495              certificates are used by this command.
496
497
498       --update-trustdb
499              Do  trust  database  maintenance. This command iterates over all
500              keys and builds the Web of Trust. This is an interactive command
501              because it may have to ask for the "ownertrust" values for keys.
502              The user has to give an estimation of how  far  she  trusts  the
503              owner  of  the  displayed  key to correctly certify (sign) other
504              keys. GnuPG only asks for the ownertrust value if it has not yet
505              been  assigned to a key. Using the --edit-key menu, the assigned
506              value can be changed at any time.
507
508
509       --check-trustdb
510              Do trust database maintenance  without  user  interaction.  From
511              time  to time the trust database must be updated so that expired
512              keys or signatures and the resulting changes in the Web of Trust
513              can  be  tracked.  Normally,  GnuPG  will calculate when this is
514              required and do it automatically unless  --no-auto-check-trustdb
515              is set. This command can be used to force a trust database check
516              at any time. The processing is identical to  that  of  --update-
517              trustdb but it skips keys with a not yet defined "ownertrust".
518
519              For  use  with cron jobs, this command can be used together with
520              --batch in which case the trust database check is done only if a
521              check  is  needed.  To  force  a  run even in batch mode add the
522              option --yes.
523
524
525
526       --export-ownertrust
527              Send the ownertrust values to STDOUT. This is useful for  backup
528              purposes  as  these  values are the only ones which can't be re-
529              created from a corrupted trustdb.  Example:
530                  gpg --export-ownertrust > otrust.txt
531
532
533
534       --import-ownertrust
535              Update the trustdb with the ownertrust values  stored  in  files
536              (or  STDIN  if  not given); existing values will be overwritten.
537              In case of a severely damaged trustdb and if you have  a  recent
538              backup of the ownertrust values (e.g. in the file ‘otrust.txt’),
539              you may re-create the trustdb using these commands:
540                  cd ~/.gnupg
541                  rm trustdb.gpg
542                  gpg --import-ownertrust < otrust.txt
543
544
545
546       --rebuild-keydb-caches
547              When updating from version 1.0.6 to 1.0.7 this command should be
548              used  to  create  signature  caches  in the keyring. It might be
549              handy in other situations too.
550
551
552       --print-md algo
553       --print-mds
554              Print message digest of algorithm algo for all  given  files  or
555              STDIN.   With  the  second  form  (or a deprecated "*" for algo)
556              digests for all available algorithms are printed.
557
558
559       --gen-random 0|1|2 count
560              Emit count random bytes of the given quality level 0, 1 or 2. If
561              count  is not given or zero, an endless sequence of random bytes
562              will be emitted.  If used with --armor the output will be base64
563              encoded.   PLEASE,  don't  use this command unless you know what
564              you are doing; it may remove precious entropy from the system!
565
566
567       --gen-prime mode bits
568              Use the source, Luke :-). The output format is subject to change
569              with ant release.
570
571
572
573       --enarmor
574       --dearmor
575              Pack  or  unpack  an  arbitrary input into/from an OpenPGP ASCII
576              armor.  This is a GnuPG extension to OpenPGP and in general  not
577              very useful.
578
579
580       --tofu-policy {auto|good|unknown|bad|ask} keys
581              Set  the  TOFU  policy  for all the bindings associated with the
582              specified keys.  For more information about the meaning  of  the
583              policies,  see:  [trust-model-tofu].   The keys may be specified
584              either by their fingerprint (preferred) or their keyid.
585
586
587
588   How to manage your keys
589
590
591       This section explains the main commands for key management.
592
593
594
595       --quick-generate-key user-id [algo [usage [expire]]]
596       --quick-gen-key
597              This is a simple command to generate a  standard  key  with  one
598              user  id.   In  contrast  to --generate-key the key is generated
599              directly without the need to answer a bunch of prompts.   Unless
600              the  option --yes is given, the key creation will be canceled if
601              the given user id already exists in the keyring.
602
603              If invoked directly on the console without any  special  options
604              an  answer  to  a  ``Continue?''  style  confirmation  prompt is
605              required.  In case the user id already exists in the  keyring  a
606              second prompt to force the creation of the key will show up.
607
608              If  algo or usage are given, only the primary key is created and
609              no prompts are shown.  To specify an expiration date  but  still
610              create  a  primary  and  subkey  use  ``default''  or  ``future-
611              default'' for algo and ``default'' for usage.  For a description
612              of  these  optional  arguments  see the command --quick-add-key.
613              The usage accepts also the value ``cert'' which can be  used  to
614              create  a  certification  only  primary key; the default is to a
615              create certification and signing key.
616
617              The expire argument can be used to specify  an  expiration  date
618              for  the  key.   Several formats are supported; commonly the ISO
619              formats ``YYYY-MM-DD'' or ``YYYYMMDDThhmmss'' are used.  To make
620              the  key  expire  in  N seconds, N days, N weeks, N months, or N
621              years use  ``seconds=N'',  ``Nd'',  ``Nw'',  ``Nm'',  or  ``Ny''
622              respectively.  Not specifying a value, or using ``-'' results in
623              a key expiring in a reasonable  default  interval.   The  values
624              ``never'', ``none'' can be used for no expiration date.
625
626              If  this  command is used with --batch, --pinentry-mode has been
627              set  to  loopback,   and   one   of   the   passphrase   options
628              (--passphrase, --passphrase-fd, or passphrase-file) is used, the
629              supplied passphrase is used for the new key and the  agent  does
630              not  ask  for  it.   To  create  a  key  without  any protection
631              --passphrase '' may be used.
632
633              To create an OpenPGP key from the keys  available  on  the  cur‐
634              rently  inserted  smartcard,  the special string ``card'' can be
635              used for algo.  If the card features an encryption and a signing
636              key,  gpg  will  figure them out and creates an OpenPGP key con‐
637              sisting of the usual primary key and  one  subkey.   This  works
638              only with certain smartcards.  Note that the interactive --full-
639              gen-key command allows to do the same but with greater flexibil‐
640              ity in the selection of the smartcard keys.
641
642              Note  that  it  is possible to create a primary key and a subkey
643              using non-default algorithms by using ``default''  and  changing
644              the default parameters using the option --default-new-key-algo.
645
646
647       --quick-set-expire fpr expire [*|subfprs]
648              With  two  arguments  given, directly set the expiration time of
649              the primary key identified by fpr  to  expire.   To  remove  the
650              expiration  time  0  can  be used.  With three arguments and the
651              third given as an asterisk, the  expiration  time  of  all  non-
652              revoked  and  not  yet  expired subkeys are set to expire.  With
653              more than two arguments and a list  of  fingerprints  given  for
654              subfprs, all non-revoked subkeys matching these fingerprints are
655              set to expire.
656
657
658
659       --quick-add-key fpr [algo [usage [expire]]]
660              Directly add a subkey to the key identified by  the  fingerprint
661              fpr.   Without  the  optional  arguments an encryption subkey is
662              added.  If any of the arguments are given a more specific subkey
663              is added.
664
665              algo may be any of the supported algorithms or curve names given
666              in the format as used by key listings.  To use the default algo‐
667              rithm  the  string  ``default'' or ``-'' can be used.  Supported
668              algorithms   are   ``rsa'',   ``dsa'',   ``elg'',   ``ed25519'',
669              ``cv25519'',  and  other  ECC  curves.   For  example the string
670              ``rsa'' adds an RSA key with the default key  length;  a  string
671              ``rsa4096''  requests  that  the  key  length is 4096 bits.  The
672              string ``future-default'' is an alias for  the  algorithm  which
673              will  likely  be used as default algorithm in future versions of
674              gpg.  To list the supported ECC curves the command  gpg  --with-
675              colons --list-config curve can be used.
676
677              Depending  on the given algo the subkey may either be an encryp‐
678              tion subkey or a signing subkey.  If an algorithm is capable  of
679              signing  and  encryption  and  such a subkey is desired, a usage
680              string must be given.  This  string  is  either  ``default''  or
681              ``-''  to  keep  the default or a comma delimited list (or space
682              delimited list) of keywords:  ``sign''  for  a  signing  subkey,
683              ``auth''  for  an  authentication  subkey,  and  ``encr'' for an
684              encryption  subkey  (``encrypt''  can  be  used  as  alias   for
685              ``encr'').  The valid combinations depend on the algorithm.
686
687              The  expire  argument  can be used to specify an expiration date
688              for the key.  Several formats are supported;  commonly  the  ISO
689              formats ``YYYY-MM-DD'' or ``YYYYMMDDThhmmss'' are used.  To make
690              the key expire in N seconds, N days, N weeks,  N  months,  or  N
691              years  use  ``seconds=N'',  ``Nd'',  ``Nw'',  ``Nm'',  or ``Ny''
692              respectively.  Not specifying a value, or using ``-'' results in
693              a  key  expiring  in  a reasonable default interval.  The values
694              ``never'', ``none'' can be used for no expiration date.
695
696
697       --generate-key
698       --gen-key
699              Generate a new key pair using the  current  default  parameters.
700              This  is  the standard command to create a new key.  In addition
701              to the key a revocation certificate is created and stored in the
702openpgp-revocs.d’ directory below the GnuPG home directory.
703
704
705       --full-generate-key
706       --full-gen-key
707              Generate  a  new key pair with dialogs for all options.  This is
708              an extended version of --generate-key.
709
710              There is also a feature which allows you to create keys in batch
711              mode.  See  the  manual section ``Unattended key generation'' on
712              how to use this.
713
714
715
716       --generate-revocation name
717       --gen-revoke name
718              Generate a revocation certificate for the complete key.  To only
719              revoke a subkey or a key signature, use the --edit command.
720
721              This  command  merely creates the revocation certificate so that
722              it can be used to revoke the key if that  is  ever  needed.   To
723              actually  revoke  a key the created revocation certificate needs
724              to be merged with the key to revoke.  This is done by  importing
725              the revocation certificate using the --import command.  Then the
726              revoked key needs to be published, which is best done by sending
727              the  key  to  a  keyserver (command --send-key) and by exporting
728              (--export) it to a file which is then send to frequent  communi‐
729              cation partners.
730
731
732
733       --generate-designated-revocation name
734       --desig-revoke name
735              Generate  a  designated  revocation  certificate for a key. This
736              allows a user (with the permission of the keyholder)  to  revoke
737              someone else's key.
738
739
740
741       --edit-key
742              Present  a  menu which enables you to do most of the key manage‐
743              ment related tasks.  It expects the specification of  a  key  on
744              the command line.
745
746
747
748              uid n  Toggle  selection of user ID or photographic user ID with
749                     index n.  Use * to select all and 0 to deselect all.
750
751
752              key n  Toggle selection of subkey with index n or key ID n.  Use
753                     * to select all and 0 to deselect all.
754
755
756              sign   Make  a  signature on key of user name. If the key is not
757                     yet signed by the default user (or the users  given  with
758                     -u),  the  program  displays  the  information of the key
759                     again, together with its fingerprint and asks whether  it
760                     should be signed. This question is repeated for all users
761                     specified with -u.
762
763
764              lsign  Same as "sign"  but  the  signature  is  marked  as  non-
765                     exportable  and  will  therefore never be used by others.
766                     This may be used to make keys valid  only  in  the  local
767                     environment.
768
769
770              nrsign Same as "sign" but the signature is marked as non-revoca‐
771                     ble and can therefore never be revoked.
772
773
774              tsign  Make a trust signature. This is a signature that combines
775                     the  notions of certification (like a regular signature),
776                     and trust (like the "trust"  command).  It  is  generally
777                     only  useful in distinct communities or groups.  For more
778                     information please read the sections ``Trust  Signature''
779                     and ``Regular Expression'' in RFC-4880.
780
781              Note  that "l" (for local / non-exportable), "nr" (for non-revo‐
782              cable, and "t" (for trust) may be freely mixed and  prefixed  to
783              "sign" to create a signature of any type desired.
784
785       If  the  option  --only-sign-text-ids  is  specified, then any non-text
786       based user ids (e.g., photo IDs) will not be selected for signing.
787
788
789
790              delsig Delete a signature. Note  that  it  is  not  possible  to
791                     retract  a signature, once it has been send to the public
792                     (i.e. to a keyserver).   In  that  case  you  better  use
793                     revsig.
794
795
796              revsig Revoke  a  signature.  For every signature which has been
797                     generated by one of the secret keys, GnuPG asks whether a
798                     revocation certificate should be generated.
799
800
801              check  Check  the signatures on all selected user IDs.  With the
802                     extra option selfsig only self-signatures are shown.
803
804
805              adduid Create an additional user ID.
806
807
808              addphoto
809                     Create a photographic user ID. This  will  prompt  for  a
810                     JPEG  file  that  will be embedded into the user ID. Note
811                     that a very large JPEG will make for a  very  large  key.
812                     Also  note  that  some  programs  will  display your JPEG
813                     unchanged (GnuPG), and some programs will scale it to fit
814                     in a dialog box (PGP).
815
816
817              showphoto
818                     Display the selected photographic user ID.
819
820
821              deluid Delete  a  user ID or photographic user ID.  Note that it
822                     is not possible to retract a user id, once  it  has  been
823                     send  to  the public (i.e. to a keyserver).  In that case
824                     you better use revuid.
825
826
827              revuid Revoke a user ID or photographic user ID.
828
829
830              primary
831                     Flag the current user id as the primary one, removes  the
832                     primary user id flag from all other user ids and sets the
833                     timestamp of  all  affected  self-signatures  one  second
834                     ahead. Note that setting a photo user ID as primary makes
835                     it primary over other photo user IDs, and setting a regu‐
836                     lar  user ID as primary makes it primary over other regu‐
837                     lar user IDs.
838
839
840              keyserver
841                     Set a preferred keyserver for the specified  user  ID(s).
842                     This allows other users to know where you prefer they get
843                     your key from. See  --keyserver-options  honor-keyserver-
844                     url  for  more  on  how  this  works.  Setting a value of
845                     "none" removes an existing preferred keyserver.
846
847
848              notation
849                     Set a name=value notation for the specified  user  ID(s).
850                     See --cert-notation for more on how this works. Setting a
851                     value of "none" removes all notations, setting a notation
852                     prefixed with a minus sign (-) removes that notation, and
853                     setting a notation name  (without  the  =value)  prefixed
854                     with a minus sign removes all notations with that name.
855
856
857              pref   List  preferences  from  the selected user ID. This shows
858                     the actual preferences,  without  including  any  implied
859                     preferences.
860
861
862              showpref
863                     More  verbose  preferences  listing for the selected user
864                     ID. This shows the preferences in effect by including the
865                     implied preferences of 3DES (cipher), SHA-1 (digest), and
866                     Uncompressed  (compression)  if  they  are  not   already
867                     included  in  the  preference list. In addition, the pre‐
868                     ferred keyserver and signature  notations  (if  any)  are
869                     shown.
870
871
872              setpref string
873                     Set the list of user ID preferences to string for all (or
874                     just the selected) user  IDs.  Calling  setpref  with  no
875                     arguments sets the preference list to the default (either
876                     built-in or set via --default-preference-list), and call‐
877                     ing  setpref  with  "none"  as the argument sets an empty
878                     preference list. Use gpg  --version  to  get  a  list  of
879                     available  algorithms. Note that while you can change the
880                     preferences on an attribute user  ID  (aka  "photo  ID"),
881                     GnuPG  does  not  select  keys  via attribute user IDs so
882                     these preferences will not be used by GnuPG.
883
884                     When setting preferences, you should list the  algorithms
885                     in the order which you'd like to see them used by someone
886                     else when encrypting a message to your key.  If you don't
887                     include  3DES, it will be automatically added at the end.
888                     Note that there are many factors that go into choosing an
889                     algorithm  (for  example,  your  key  may not be the only
890                     recipient), and so the remote OpenPGP  application  being
891                     used to send to you may or may not follow your exact cho‐
892                     sen order for a given message.  It  will,  however,  only
893                     choose  an  algorithm  that  is present on the preference
894                     list of every recipient key.  See also the INTEROPERABIL‐
895                     ITY WITH OTHER OPENPGP PROGRAMS section below.
896
897
898              addkey Add a subkey to this key.
899
900
901              addcardkey
902                     Generate a subkey on a card and add it to this key.
903
904
905              keytocard
906                     Transfer  the  selected secret subkey (or the primary key
907                     if no subkey has  been  selected)  to  a  smartcard.  The
908                     secret  key  in the keyring will be replaced by a stub if
909                     the key could be stored successfully on the card and  you
910                     use the save command later. Only certain key types may be
911                     transferred to the card. A sub menu allows you to  select
912                     on what card to store the key. Note that it is not possi‐
913                     ble to get that key back from the card - if the card gets
914                     broken  your  secret  key  will be lost unless you have a
915                     backup somewhere.
916
917
918              bkuptocard file
919                     Restore the given file to a card.  This  command  may  be
920                     used  to  restore  a backup key (as generated during card
921                     initialization) to a new card. In almost all  cases  this
922                     will  be  the encryption key. You should use this command
923                     only with the corresponding public key and make sure that
924                     the  file  given  as  argument  is  indeed  the backup to
925                     restore. You should then select 2 to restore  as  encryp‐
926                     tion   key.   You  will  first  be  asked  to  enter  the
927                     passphrase of the backup key and then for the  Admin  PIN
928                     of the card.
929
930
931              delkey Remove a subkey (secondary key). Note that it is not pos‐
932                     sible to retract a subkey, once it has been send  to  the
933                     public  (i.e.  to  a keyserver).  In that case you better
934                     use revkey.  Also note that this only deletes the  public
935                     part of a key.
936
937
938              revkey Revoke a subkey.
939
940
941              expire Change  the key or subkey expiration time. If a subkey is
942                     selected, the expiration time  of  this  subkey  will  be
943                     changed.  With  no  selection,  the key expiration of the
944                     primary key is changed.
945
946
947              trust  Change the owner trust value for the  key.  This  updates
948                     the trust-db immediately and no save is required.
949
950
951              disable
952              enable Disable  or  enable an entire key. A disabled key can not
953                     normally be used for encryption.
954
955
956              addrevoker
957                     Add a designated revoker  to  the  key.  This  takes  one
958                     optional  argument:  "sensitive". If a designated revoker
959                     is marked as  sensitive,  it  will  not  be  exported  by
960                     default (see export-options).
961
962
963              passwd Change the passphrase of the secret key.
964
965
966              toggle This is dummy command which exists only for backward com‐
967                     patibility.
968
969
970              clean  Compact (by removing all signatures except  the  selfsig)
971                     any  user  ID  that is no longer usable (e.g. revoked, or
972                     expired). Then, remove any signatures that are not usable
973                     by  the  trust  calculations.  Specifically, this removes
974                     any signature that does not validate, any signature  that
975                     is  superseded  by a later signature, revoked signatures,
976                     and signatures issued by keys that are not present on the
977                     keyring.
978
979
980              minimize
981                     Make  the key as small as possible. This removes all sig‐
982                     natures from each user ID  except  for  the  most  recent
983                     self-signature.
984
985
986              change-usage
987                     Change  the usage flags (capabilities) of the primary key
988                     or of subkeys.  These usage flags  (e.g.  Certify,  Sign,
989                     Authenticate,  Encrypt)  are  set  during  key  creation.
990                     Sometimes it is useful to have the opportunity to  change
991                     them  (for  example  to add Authenticate) after they have
992                     been created.  Please take  care  when  doing  this;  the
993                     allowed usage flags depend on the key algorithm.
994
995
996              cross-certify
997                     Add  cross-certification  signatures  to  signing subkeys
998                     that may not  currently  have  them.  Cross-certification
999                     signatures  protect against a subtle attack against sign‐
1000                     ing subkeys. See --require-cross-certification.  All  new
1001                     keys  generated  have  this signature by default, so this
1002                     command is only useful to bring older keys up to date.
1003
1004
1005              save   Save all changes to the keyrings and quit.
1006
1007
1008              quit   Quit the program without updating the keyrings.
1009
1010              The listing shows you the key with its secondary  keys  and  all
1011              user  IDs.   The  primary  user  ID  is  indicated by a dot, and
1012              selected keys or user IDs are indicated  by  an  asterisk.   The
1013              trust  value  is  displayed with the primary key: "trust" is the
1014              assigned owner trust and "validity" is the  calculated  validity
1015              of  the  key.   Validity  values are also displayed for all user
1016              IDs.  For possible values of trust, see: [trust-values].
1017
1018
1019       --sign-key name
1020              Signs a public key with your secret key. This is a shortcut ver‐
1021              sion of the subcommand "sign" from --edit.
1022
1023
1024       --lsign-key name
1025              Signs  a  public  key  with your secret key but marks it as non-
1026              exportable. This is a shortcut version of the subcommand "lsign"
1027              from --edit-key.
1028
1029
1030       --quick-sign-key fpr [names]
1031       --quick-lsign-key fpr [names]
1032              Directly sign a key from the passphrase without any further user
1033              interaction.  The fpr must be the verified  primary  fingerprint
1034              of a key in the local keyring. If no names are given, all useful
1035              user ids are signed; with given [names]  only  useful  user  ids
1036              matching  one  of  theses names are signed.  By default, or if a
1037              name is prefixed with a '*', a case insensitive substring  match
1038              is  used.   If  a  name  is prefixed with a '=' a case sensitive
1039              exact match is done.
1040
1041              The command  --quick-lsign-key  marks  the  signatures  as  non-
1042              exportable.   If  such a non-exportable signature already exists
1043              the --quick-sign-key turns it into a exportable signature.
1044
1045              This command uses reasonable defaults and thus does not  provide
1046              the  full  flexibility of the "sign" subcommand from --edit-key.
1047              Its intended use is to help unattended key signing by  utilizing
1048              a list of verified fingerprints.
1049
1050
1051       --quick-add-uid user-id new-user-id
1052              This command adds a new user id to an existing key.  In contrast
1053              to the interactive sub-command adduid  of  --edit-key  the  new-
1054              user-id  is  added verbatim with only leading and trailing white
1055              space removed, it is expected to be UTF-8 encoded, and no checks
1056              on its form are applied.
1057
1058
1059       --quick-revoke-uid user-id user-id-to-revoke
1060              This command revokes a user ID on an existing key.  It cannot be
1061              used to revoke the last user ID on key (some non-revoked user ID
1062              must  remain),  with  revocation  reason  ``User ID is no longer
1063              valid''.  If you want to specify a different revocation  reason,
1064              or  to  supply supplementary revocation text, you should use the
1065              interactive sub-command revuid of --edit-key.
1066
1067
1068       --quick-set-primary-uid user-id primary-user-id
1069              This command sets or updates the primary  user  ID  flag  on  an
1070              existing key.  user-id specifies the key and primary-user-id the
1071              user ID which shall be flagged as the primary user ID.  The pri‐
1072              mary  user  ID  flag  is removed from all other user ids and the
1073              timestamp of all affected  self-signatures  is  set  one  second
1074              ahead.
1075
1076
1077
1078       --change-passphrase user-id
1079       --passwd user-id
1080              Change  the  passphrase  of the secret key belonging to the cer‐
1081              tificate specified as user-id.  This is a shortcut for the  sub-
1082              command  passwd  of the edit key menu.  When using together with
1083              the  option  --dry-run  this  will  not  actually   change   the
1084              passphrase but check that the current passphrase is correct.
1085
1086

OPTIONS

1088       gpg  features  a bunch of options to control the exact behaviour and to
1089       change the default configuration.
1090
1091
1092       Long   options   can   be   put   in   an   options    file    (default
1093       "~/.gnupg/gpg.conf").  Short  option names will not work - for example,
1094       "armor" is a valid option for the options file, while "a"  is  not.  Do
1095       not  write  the  2  dashes,  but  simply the name of the option and any
1096       required arguments. Lines with a hash ('#')  as  the  first  non-white-
1097       space  character are ignored. Commands may be put in this file too, but
1098       that is not generally useful as the command will execute  automatically
1099       with every execution of gpg.
1100
1101       Please  remember  that  option parsing stops as soon as a non-option is
1102       encountered, you can explicitly  stop  parsing  by  using  the  special
1103       option --.
1104
1105
1106
1107   How to change the configuration
1108
1109
1110       These  options  are  used  to  change the configuration and are usually
1111       found in the option file.
1112
1113
1114
1115       --default-key name
1116              Use name as the default key to sign with. If this option is  not
1117              used,  the  default  key  is  the  first key found in the secret
1118              keyring.  Note that -u or --local-user  overrides  this  option.
1119              This option may be given multiple times.  In this case, the last
1120              key for which a secret key is available is used.  If there is no
1121              secret key available for any of the specified values, GnuPG will
1122              not emit an error message but continue as if this option  wasn't
1123              given.
1124
1125
1126       --default-recipient name
1127              Use  name as default recipient if option --recipient is not used
1128              and don't ask if this is a valid one. name must be non-empty.
1129
1130
1131       --default-recipient-self
1132              Use the default key as default recipient if  option  --recipient
1133              is  not  used  and don't ask if this is a valid one. The default
1134              key is the first one from the secret keyring or the one set with
1135              --default-key.
1136
1137
1138       --no-default-recipient
1139              Reset --default-recipient and --default-recipient-self.
1140
1141
1142       -v, --verbose
1143              Give  more  information  during  processing.  If used twice, the
1144              input data is listed in detail.
1145
1146
1147       --no-verbose
1148              Reset verbose level to 0.
1149
1150
1151       -q, --quiet
1152              Try to be as quiet as possible.
1153
1154
1155       --batch
1156       --no-batch
1157              Use batch mode.  Never ask, do not allow  interactive  commands.
1158              --no-batch disables this option.  Note that even with a filename
1159              given on the command line, gpg might still  need  to  read  from
1160              STDIN (in particular if gpg figures that the input is a detached
1161              signature and no data file has been specified).  Thus if you  do
1162              not  want  to  feed  data via STDIN, you should connect STDIN to
1163              g‘/dev/null’.
1164
1165              It is highly recommended to  use  this  option  along  with  the
1166              options  --status-fd and --with-colons for any unattended use of
1167              gpg.
1168
1169
1170       --no-tty
1171              Make sure that the TTY (terminal) is never used for any  output.
1172              This  option  is  needed  in  some cases because GnuPG sometimes
1173              prints warnings to the TTY even if --batch is used.
1174
1175
1176       --yes  Assume "yes" on most questions.
1177
1178
1179       --no   Assume "no" on most questions.
1180
1181
1182
1183       --list-options parameters
1184              This is a space or comma delimited  string  that  gives  options
1185              used  when  listing  keys  and signatures (that is, --list-keys,
1186              --check-signatures, --list-public-keys, --list-secret-keys,  and
1187              the  --edit-key functions).  Options can be prepended with a no-
1188              (after the two  dashes)  to  give  the  opposite  meaning.   The
1189              options are:
1190
1191
1192
1193              show-photos
1194                     Causes  --list-keys,  --check-signatures,  --list-public-
1195                     keys, and --list-secret-keys to  display  any  photo  IDs
1196                     attached  to  the key.  Defaults to no. See also --photo-
1197                     viewer.   Does   not   work   with   --with-colons:   see
1198                     --attribute-fd  for the appropriate way to get photo data
1199                     for scripts and other frontends.
1200
1201
1202              show-usage
1203                     Show usage information for keys and subkeys in the  stan‐
1204                     dard  key  listing.  This is a list of letters indicating
1205                     the allowed usage for  a  key  (E=encryption,  S=signing,
1206                     C=certification, A=authentication).  Defaults to yes.
1207
1208
1209              show-policy-urls
1210                     Show  policy  URLs  in  the  --check-signatures listings.
1211                     Defaults to no.
1212
1213
1214              show-notations
1215              show-std-notations
1216              show-user-notations
1217                     Show all, IETF standard, or user-defined signature  nota‐
1218                     tions in the --check-signatures listings. Defaults to no.
1219
1220
1221              show-keyserver-urls
1222                     Show  any  preferred  keyserver URL in the --check-signa‐
1223                     tures listings. Defaults to no.
1224
1225
1226              show-uid-validity
1227                     Display the calculated validity of user  IDs  during  key
1228                     listings.  Defaults to yes.
1229
1230
1231              show-unusable-uids
1232                     Show  revoked  and  expired  user  IDs  in  key listings.
1233                     Defaults to no.
1234
1235
1236              show-unusable-subkeys
1237                     Show  revoked  and  expired  subkeys  in  key   listings.
1238                     Defaults to no.
1239
1240
1241              show-keyring
1242                     Display  the  keyring name at the head of key listings to
1243                     show which keyring a given key resides  on.  Defaults  to
1244                     no.
1245
1246
1247              show-sig-expire
1248                     Show  signature expiration dates (if any) during --check-
1249                     signatures listings. Defaults to no.
1250
1251
1252              show-sig-subpackets
1253                     Include signature subpackets in  the  key  listing.  This
1254                     option can take an optional argument list of the subpack‐
1255                     ets to list. If no argument is passed, list all  subpack‐
1256                     ets.  Defaults to no. This option is only meaningful when
1257                     using --with-colons along with --check-signatures.
1258
1259
1260              show-only-fpr-mbox
1261                     For each user-id which has a  valid  mail  address  print
1262                     only the fingerprint followed by the mail address.
1263
1264
1265       --verify-options parameters
1266              This  is  a  space  or comma delimited string that gives options
1267              used when verifying signatures. Options can be prepended with  a
1268              `no-' to give the opposite meaning. The options are:
1269
1270
1271
1272              show-photos
1273                     Display  any photo IDs present on the key that issued the
1274                     signature.  Defaults to no. See also --photo-viewer.
1275
1276
1277              show-policy-urls
1278                     Show  policy  URLs  in  the  signature  being   verified.
1279                     Defaults to yes.
1280
1281
1282              show-notations
1283              show-std-notations
1284              show-user-notations
1285                     Show  all, IETF standard, or user-defined signature nota‐
1286                     tions in the signature being verified. Defaults  to  IETF
1287                     standard.
1288
1289
1290              show-keyserver-urls
1291                     Show  any  preferred keyserver URL in the signature being
1292                     verified.  Defaults to yes.
1293
1294
1295              show-uid-validity
1296                     Display the calculated validity of the user  IDs  on  the
1297                     key that issued the signature. Defaults to yes.
1298
1299
1300              show-unusable-uids
1301                     Show  revoked and expired user IDs during signature veri‐
1302                     fication.  Defaults to no.
1303
1304
1305              show-primary-uid-only
1306                     Show only the primary user ID during signature  verifica‐
1307                     tion.  That is all the AKA lines as well as photo Ids are
1308                     not shown with the signature verification status.
1309
1310
1311              pka-lookups
1312                     Enable PKA lookups to verify sender addresses. Note  that
1313                     PKA is based on DNS, and so enabling this option may dis‐
1314                     close information on when and what signatures  are  veri‐
1315                     fied or to whom data is encrypted. This is similar to the
1316                     "web bug" described for the --auto-key-retrieve option.
1317
1318
1319              pka-trust-increase
1320                     Raise the trust in a signature to full if  the  signature
1321                     passes  PKA validation. This option is only meaningful if
1322                     pka-lookups is set.
1323
1324
1325       --enable-large-rsa
1326       --disable-large-rsa
1327              With --generate-key and --batch,  enable  the  creation  of  RSA
1328              secret  keys  as large as 8192 bit.  Note: 8192 bit is more than
1329              is generally recommended.  These large keys don't  significantly
1330              improve  security, but they are more expensive to use, and their
1331              signatures and certifications are larger.  This option  is  only
1332              available if the binary was build with large-secmem support.
1333
1334
1335       --enable-dsa2
1336       --disable-dsa2
1337              Enable hash truncation for all DSA keys even for old DSA Keys up
1338              to 1024 bit.  This is also the  default  with  --openpgp.   Note
1339              that  older  versions  of GnuPG also required this flag to allow
1340              the generation of DSA larger than 1024 bit.
1341
1342
1343       --photo-viewer string
1344              This is the command line that should be run to view a photo  ID.
1345              "%i"  will  be expanded to a filename containing the photo. "%I"
1346              does the same, except the file will  not  be  deleted  once  the
1347              viewer exits.  Other flags are "%k" for the key ID, "%K" for the
1348              long key ID, "%f" for the key fingerprint, "%t" for  the  exten‐
1349              sion  of  the image type (e.g. "jpg"), "%T" for the MIME type of
1350              the image (e.g. "image/jpeg"),  "%v"  for  the  single-character
1351              calculated  validity  of the image being viewed (e.g. "f"), "%V"
1352              for the calculated validity as a string (e.g.  "full"), "%U" for
1353              a  base32  encoded  hash  of the user ID, and "%%" for an actual
1354              percent sign. If neither %i or %I are present,  then  the  photo
1355              will be supplied to the viewer on standard input.
1356
1357              On  Unix  the  default  viewer is xloadimage -fork -quiet -title
1358              'KeyID 0x%k' STDIN with a  fallback  to  display  -title  'KeyID
1359              0x%k'  %i  and finally to xdg-open %i.  On Windows !ShellExecute
1360              400 %i is used; here the command is a meta command to  use  that
1361              API  call  followed by a wait time in milliseconds which is used
1362              to give the viewer time to read the temporary image file  before
1363              gpg deletes it again.  Note that if your image viewer program is
1364              not secure, then executing it from gpg does not make it secure.
1365
1366
1367       --exec-path string
1368              Sets a list of directories to search for photo  viewers  If  not
1369              provided photo viewers use the PATH environment variable.
1370
1371
1372       --keyring file
1373              Add  file to the current list of keyrings. If file begins with a
1374              tilde and a slash, these are replaced by the $HOME directory. If
1375              the  filename  does  not contain a slash, it is assumed to be in
1376              the GnuPG home directory ("~/.gnupg" if --homedir or  $GNUPGHOME
1377              is not used).
1378
1379              Note that this adds a keyring to the current list. If the intent
1380              is to use the specified keyring alone, use --keyring along  with
1381              --no-default-keyring.
1382
1383              If  the  option  --no-keyring  has been used no keyrings will be
1384              used at all.
1385
1386
1387
1388       --secret-keyring file
1389              This is an obsolete option and ignored.   All  secret  keys  are
1390              stored in the ‘private-keys-v1.d’ directory below the GnuPG home
1391              directory.
1392
1393
1394       --primary-keyring file
1395              Designate file as the primary public keyring.  This  means  that
1396              newly imported keys (via --import or keyserver --recv-from) will
1397              go to this keyring.
1398
1399
1400       --trustdb-name file
1401              Use file instead of the default trustdb. If file begins  with  a
1402              tilde and a slash, these are replaced by the $HOME directory. If
1403              the filename does not contain a slash, it is assumed  to  be  in
1404              the  GnuPG home directory (‘~/.gnupg’ if --homedir or $GNUPGHOME
1405              is not used).
1406
1407
1408       --homedir dir
1409              Set the name of the home directory to dir. If this option is not
1410              used,  the  home  directory  defaults to ‘~/.gnupg’.  It is only
1411              recognized when given on the command line.   It  also  overrides
1412              any  home  directory  stated  through  the  environment variable
1413GNUPGHOME’ or (on Windows systems) by  means  of  the  Registry
1414              entry HKCU\Software\GNU\GnuPG:HomeDir.
1415
1416              On Windows systems it is possible to install GnuPG as a portable
1417              application.  In this case only this command line option is con‐
1418              sidered, all other ways to set a home directory are ignored.
1419
1420              To install GnuPG as a portable application under Windows, create
1421              an empty file named ‘gpgconf.ctl’ in the same directory  as  the
1422              tool  ‘gpgconf.exe’.   The root of the installation is then that
1423              directory; or, if  ‘gpgconf.exe’  has  been  installed  directly
1424              below  a  directory named ‘bin’, its parent directory.  You also
1425              need to make sure that the following directories exist  and  are
1426              writable:     ‘ROOT/home’     for    the    GnuPG    home    and
1427ROOT/var/cache/gnupg’ for internal cache files.
1428
1429
1430
1431       --display-charset name
1432              Set the name of the native character set. This is used  to  con‐
1433              vert  some  informational  strings  like  user IDs to the proper
1434              UTF-8 encoding.  Note that this has nothing to do with the char‐
1435              acter  set  of  data  to  be encrypted or signed; GnuPG does not
1436              recode user-supplied data. If  this  option  is  not  used,  the
1437              default  character  set is determined from the current locale. A
1438              verbosity level of 3 shows the chosen  set.   Valid  values  for
1439              name are:
1440
1441
1442
1443              iso-8859-1
1444                     This is the Latin 1 set.
1445
1446
1447              iso-8859-2
1448                     The Latin 2 set.
1449
1450
1451              iso-8859-15
1452                     This is currently an alias for the Latin 1 set.
1453
1454
1455              koi8-r The usual Russian set (RFC-1489).
1456
1457
1458              utf-8  Bypass  all  translations  and  assume  that  the OS uses
1459                     native UTF-8 encoding.
1460
1461
1462       --utf8-strings
1463       --no-utf8-strings
1464              Assume that command line arguments are given as  UTF-8  strings.
1465              The  default (--no-utf8-strings) is to assume that arguments are
1466              encoded in the character set as specified by  --display-charset.
1467              These  options  affect all following arguments. Both options may
1468              be used multiple times.
1469
1470
1471
1472       --options file
1473              Read options from file and do not try  to  read  them  from  the
1474              default options file in the homedir (see --homedir). This option
1475              is ignored if used in an options file.
1476
1477
1478       --no-options
1479              Shortcut for --options /dev/null. This option is detected before
1480              an  attempt to open an option file.  Using this option will also
1481              prevent the creation of a ‘~/.gnupg’ homedir.
1482
1483
1484       -z n
1485       --compress-level n
1486       --bzip2-compress-level n
1487              Set compression level to n for  the  ZIP  and  ZLIB  compression
1488              algorithms.  The default is to use the default compression level
1489              of zlib (normally 6). --bzip2-compress-level sets  the  compres‐
1490              sion  level for the BZIP2 compression algorithm (defaulting to 6
1491              as well). This is a different option from --compress-level since
1492              BZIP2  uses  a  significant amount of memory for each additional
1493              compression level.  -z sets both. A value of 0  for  n  disables
1494              compression.
1495
1496
1497       --bzip2-decompress-lowmem
1498              Use a different decompression method for BZIP2 compressed files.
1499              This alternate method uses a bit more than half the memory,  but
1500              also  runs  at  half the speed. This is useful under extreme low
1501              memory circumstances when the file was originally compressed  at
1502              a high --bzip2-compress-level.
1503
1504
1505
1506       --mangle-dos-filenames
1507       --no-mangle-dos-filenames
1508              Older  version of Windows cannot handle filenames with more than
1509              one dot. --mangle-dos-filenames causes GnuPG to replace  (rather
1510              than  add  to) the extension of an output filename to avoid this
1511              problem. This option is off by default and has no effect on non-
1512              Windows platforms.
1513
1514
1515       --ask-cert-level
1516       --no-ask-cert-level
1517              When  making  a key signature, prompt for a certification level.
1518              If this option is not specified, the certification level used is
1519              set   via  --default-cert-level.  See  --default-cert-level  for
1520              information on the specific levels and how they are used.  --no-
1521              ask-cert-level disables this option. This option defaults to no.
1522
1523
1524       --default-cert-level n
1525              The default to use for the check level when signing a key.
1526
1527              0  means  you  make  no particular claim as to how carefully you
1528              verified the key.
1529
1530              1 means you believe the key is owned by the person who claims to
1531              own it but you could not, or did not verify the key at all. This
1532              is useful for a "persona" verification, where you sign  the  key
1533              of a pseudonymous user.
1534
1535              2  means  you  did  casual verification of the key. For example,
1536              this could mean  that  you  verified  the  key  fingerprint  and
1537              checked the user ID on the key against a photo ID.
1538
1539              3  means you did extensive verification of the key. For example,
1540              this could mean that you verified the key fingerprint  with  the
1541              owner  of the key in person, and that you checked, by means of a
1542              hard to forge document with a photo ID (such as a passport) that
1543              the name of the key owner matches the name in the user ID on the
1544              key, and finally that you verified (by exchange of  email)  that
1545              the email address on the key belongs to the key owner.
1546
1547              Note  that  the examples given above for levels 2 and 3 are just
1548              that: examples. In the end, it is up to you to decide just  what
1549              "casual" and "extensive" mean to you.
1550
1551              This option defaults to 0 (no particular claim).
1552
1553
1554       --min-cert-level
1555              When  building  the  trust database, treat any signatures with a
1556              certification level below this as invalid. Defaults to 2,  which
1557              disregards  level 1 signatures. Note that level 0 "no particular
1558              claim" signatures are always accepted.
1559
1560
1561       --trusted-key long key ID
1562              Assume that the specified key (which must be given as a  full  8
1563              byte  key  ID) is as trustworthy as one of your own secret keys.
1564              This option is useful if you don't want to keep your secret keys
1565              (or  one  of them) online but still want to be able to check the
1566              validity of a given recipient's or signator's key.
1567
1568
1569       --trust-model {pgp|classic|tofu|tofu+pgp|direct|always|auto}
1570              Set what trust model GnuPG should follow. The models are:
1571
1572
1573
1574              pgp    This is the Web of Trust combined with  trust  signatures
1575                     as  used  in PGP 5.x and later. This is the default trust
1576                     model when creating a new trust database.
1577
1578
1579              classic
1580                     This is the standard Web of Trust as introduced by PGP 2.
1581
1582
1583              tofu
1584
1585                     TOFU stands for Trust On First Use.  In this trust model,
1586                     the  first time a key is seen, it is memorized.  If later
1587                     another key with a user id with the same email address is
1588                     seen, both keys are marked as suspect.  In that case, the
1589                     next time either is used, a warning is displayed describ‐
1590                     ing  the conflict, why it might have occurred (either the
1591                     user generated a new key and failed to cross sign the old
1592                     and  new keys, the key is forgery, or a man-in-the-middle
1593                     attack is being attempted), and the user is  prompted  to
1594                     manually confirm the validity of the key in question.
1595
1596                     Because a potential attacker is able to control the email
1597                     address and thereby  circumvent  the  conflict  detection
1598                     algorithm  by  using  an email address that is similar in
1599                     appearance to a trusted email address, whenever a message
1600                     is  verified,  statistics  about  the  number of messages
1601                     signed with the key are shown.  In this way, a  user  can
1602                     easily  identify attacks using fake keys for regular cor‐
1603                     respondents.
1604
1605                     When compared with the Web of Trust, TOFU offers signifi‐
1606                     cantly  weaker  security guarantees.  In particular, TOFU
1607                     only helps ensure consistency (that is, that the  binding
1608                     between a key and email address doesn't change).  A major
1609                     advantage of TOFU is that it requires little  maintenance
1610                     to  use correctly.  To use the web of trust properly, you
1611                     need to actively sign keys  and  mark  users  as  trusted
1612                     introducers.   This is a time-consuming process and anec‐
1613                     dotal  evidence  suggests  that  even  security-conscious
1614                     users  rarely  take  the  time  to do this thoroughly and
1615                     instead rely on an ad-hoc TOFU process.
1616
1617                     In the TOFU model, policies are associated with  bindings
1618                     between  keys  and  email  addresses (which are extracted
1619                     from user ids and normalized).  There are five  policies,
1620                     which can be set manually using the --tofu-policy option.
1621                     The default policy can be set using  the  --tofu-default-
1622                     policy option.
1623
1624                     The  TOFU policies are: auto, good, unknown, bad and ask.
1625                     The auto policy is used by default (unless overridden  by
1626                     --tofu-default-policy)  and marks a binding as marginally
1627                     trusted.  The good, unknown and bad policies mark a bind‐
1628                     ing  as fully trusted, as having unknown trust or as hav‐
1629                     ing trust never, respectively.   The  unknown  policy  is
1630                     useful  for  just  using TOFU to detect conflicts, but to
1631                     never assign positive trust to a binding.  The final pol‐
1632                     icy,  ask  prompts  the  user  to  indicate the binding's
1633                     trust.  If batch mode is enabled (or input is inappropri‐
1634                     ate  in  the  context), then the user is not prompted and
1635                     the undefined trust level is returned.
1636
1637
1638              tofu+pgp
1639                     This trust model combines TOFU with  the  Web  of  Trust.
1640                     This  is done by computing the trust level for each model
1641                     and then taking the maximum trust level where  the  trust
1642                     levels are ordered as follows: unknown < undefined < mar‐
1643                     ginal < fully < ultimate < expired < never.
1644
1645                     By setting --tofu-default-policy=unknown, this model  can
1646                     be  used  to  implement the web of trust with TOFU's con‐
1647                     flict detection algorithm, but without its assignment  of
1648                     positive  trust  values,  which  some  security-conscious
1649                     users don't like.
1650
1651
1652              direct Key validity is set directly by the user and  not  calcu‐
1653                     lated  via  the Web of Trust.  This model is solely based
1654                     on the key and does not distinguish user IDs.  Note  that
1655                     when  changing  to  another  trust model the trust values
1656                     assigned to a key are transformed into ownertrust values,
1657                     which also indicate how you trust the owner of the key to
1658                     sign other keys.
1659
1660
1661              always Skip key validation and assume that used keys are  always
1662                     fully  valid. You generally won't use this unless you are
1663                     using some external validation scheme. This  option  also
1664                     suppresses  the  "[uncertain]" tag printed with signature
1665                     checks when there is no evidence  that  the  user  ID  is
1666                     bound  to the key.  Note that this trust model still does
1667                     not allow the use of expired, revoked, or disabled keys.
1668
1669
1670              auto   Select the trust model depending on whatever the internal
1671                     trust  database says. This is the default model if such a
1672                     database already exists.  Note that a tofu trust model is
1673                     not considered here and must be enabled explicitly.
1674
1675
1676       --auto-key-locate mechanisms
1677       --no-auto-key-locate
1678              GnuPG can automatically locate and retrieve keys as needed using
1679              this option.  This happens when encrypting to an  email  address
1680              (in  the  "user@example.com" form), and there are no "user@exam‐
1681              ple.com" keys on the local keyring.  This option takes any  num‐
1682              ber  of the mechanisms listed below, in the order they are to be
1683              tried.  Instead of listing the  mechanisms  as  comma  delimited
1684              arguments,  the  option  may  also be given several times to add
1685              more mechanism.  The option --no-auto-key-locate or  the  mecha‐
1686              nism "clear" resets the list.  The default is "local,wkd".
1687
1688
1689
1690              cert   Locate a key using DNS CERT, as specified in RFC-4398.
1691
1692
1693              pka    Locate a key using DNS PKA.
1694
1695
1696              dane   Locate a key using DANE, as specified in draft-ietf-dane-
1697                     openpgpkey-05.txt.
1698
1699
1700              wkd    Locate a key using the Web Key Directory protocol.
1701
1702
1703              ldap   Using DNS Service Discovery, check the domain in question
1704                     for  any  LDAP keyservers to use.  If this fails, attempt
1705                     to locate the key  using  the  PGP  Universal  method  of
1706                     checking 'ldap://keys.(thedomain)'.
1707
1708
1709              keyserver
1710                     Locate a key using a keyserver.
1711
1712
1713              keyserver-URL
1714                     In  addition, a keyserver URL as used in the dirmngr con‐
1715                     figuration may be used here to query that particular key‐
1716                     server.
1717
1718
1719              local  Locate  the key using the local keyrings.  This mechanism
1720                     allows the user to select the order a local key lookup is
1721                     done.   Thus using '--auto-key-locate local' is identical
1722                     to --no-auto-key-locate.
1723
1724
1725              nodefault
1726                     This flag disables the standard local  key  lookup,  done
1727                     before  any  of the mechanisms defined by the --auto-key-
1728                     locate are tried.  The position of this mechanism in  the
1729                     list  does  not  matter.   It is not required if local is
1730                     also used.
1731
1732
1733              clear  Clear all defined mechanisms.  This is useful to override
1734                     mechanisms given in a config file.  Note that a nodefault
1735                     in mechanisms will also be cleared  unless  it  is  given
1736                     after the clear.
1737
1738
1739
1740
1741       --auto-key-retrieve
1742       --no-auto-key-retrieve
1743              These options enable or disable the automatic retrieving of keys
1744              from a keyserver when verifying signatures made by keys that are
1745              not  on  the  local  keyring.   The  default  is  --no-auto-key-
1746              retrieve.
1747
1748              The order of methods tried to lookup the key is:
1749
1750              1. If a preferred keyserver is specified in  the  signature  and
1751              the  option  honor-keyserver-url  is  active  (which  is not the
1752              default), that keyserver is tried.  Note that the creator of the
1753              signature  uses  the  option  --sig-keyserver-url to specify the
1754              preferred keyserver for data signatures.
1755
1756              2. If the  signature  has  the  Signer's  UID  set  (e.g.  using
1757              --sender while creating the signature) a Web Key Directory (WKD)
1758              lookup is done.  This is the default configuration  but  can  be
1759              disabled  by  removing  WKD  from the auto-key-locate list or by
1760              using the option --disable-signer-uid.
1761
1762              3. If the option honor-pka-record  is  active,  the  legacy  PKA
1763              method is used.
1764
1765              4.  If any keyserver is configured and the Issuer Fingerprint is
1766              part of the signature (since GnuPG 2.1.16), the configured  key‐
1767              servers are tried.
1768
1769              Note  that this option makes a "web bug" like behavior possible.
1770              Keyserver or Web Key Directory operators can see which keys  you
1771              request,  so  by sending you a message signed by a brand new key
1772              (which you naturally will not have on your local  keyring),  the
1773              operator  can  tell  both  your IP address and the time when you
1774              verified the signature.
1775
1776
1777       --keyid-format {none|short|0xshort|long|0xlong}
1778              Select how to display key IDs.  "none" does not show the key  ID
1779              at all but shows the fingerprint in a separate line.  "short" is
1780              the traditional 8-character key ID.  "long" is the more accurate
1781              (but  less  convenient)  16-character  key  ID.   Add an "0x" to
1782              either to include an "0x" at the beginning of the key ID, as  in
1783              0x99242560.   Note  that  this  option  is ignored if the option
1784              --with-colons is used.
1785
1786
1787       --keyserver name
1788              This option is deprecated - please use the --keyserver in ‘dirm‐
1789              ngr.conf’ instead.
1790
1791              Use  name  as your keyserver. This is the server that --receive-
1792              keys, --send-keys, and --search-keys will  communicate  with  to
1793              receive  keys  from,  send  keys to, and search for keys on. The
1794              format of the name is a  URI:  `scheme:[//]keyservername[:port]'
1795              The scheme is the type of keyserver: "hkp" for the HTTP (or com‐
1796              patible) keyservers, "ldap" for the LDAP keyservers, or "mailto"
1797              for the Graff email keyserver. Note that your particular instal‐
1798              lation of GnuPG may have  other  keyserver  types  available  as
1799              well.  Keyserver  schemes  are  case-insensitive. After the key‐
1800              server name, optional keyserver  configuration  options  may  be
1801              provided.  These  are the same as the global --keyserver-options
1802              from below, but apply only to this particular keyserver.
1803
1804              Most keyservers synchronize with each other, so there is  gener‐
1805              ally no need to send keys to more than one server. The keyserver
1806              hkp://keys.gnupg.net uses round robin DNS to  give  a  different
1807              keyserver each time you use it.
1808
1809
1810       --keyserver-options {name=value}
1811              This is a space or comma delimited string that gives options for
1812              the keyserver. Options can be prefixed with a `no-' to give  the
1813              opposite  meaning. Valid import-options or export-options may be
1814              used here as well to apply to importing (--recv-key) or  export‐
1815              ing  (--send-key)  a key from a keyserver. While not all options
1816              are available for all keyserver types, some common options are:
1817
1818
1819
1820              include-revoked
1821                     When searching for a key with --search-keys, include keys
1822                     that  are  marked  on the keyserver as revoked. Note that
1823                     not all  keyservers  differentiate  between  revoked  and
1824                     unrevoked  keys,  and  for such keyservers this option is
1825                     meaningless. Note also that most keyservers do  not  have
1826                     cryptographic  verification  of  key  revocations, and so
1827                     turning this option off may result in skipping keys  that
1828                     are incorrectly marked as revoked.
1829
1830
1831              include-disabled
1832                     When searching for a key with --search-keys, include keys
1833                     that are marked on the keyserver as disabled.  Note  that
1834                     this option is not used with HKP keyservers.
1835
1836
1837              auto-key-retrieve
1838                     This  is  an  obsolete  alias  for  the  option auto-key-
1839                     retrieve.  Please do not use it; it will  be  removed  in
1840                     future versions..
1841
1842
1843              honor-keyserver-url
1844                     When  using  --refresh-keys, if the key in question has a
1845                     preferred keyserver URL, then  use  that  preferred  key‐
1846                     server to refresh the key from. In addition, if auto-key-
1847                     retrieve is set, and the signature being verified  has  a
1848                     preferred  keyserver  URL,  then  use that preferred key‐
1849                     server to fetch the  key  from.  Note  that  this  option
1850                     introduces  a  "web  bug": The creator of the key can see
1851                     when the keys is refreshed.   Thus  this  option  is  not
1852                     enabled by default.
1853
1854
1855              honor-pka-record
1856                     If  --auto-key-retrieve  is used, and the signature being
1857                     verified has a PKA record, then use the  PKA  information
1858                     to fetch the key. Defaults to "yes".
1859
1860
1861              include-subkeys
1862                     When  receiving  a key, include subkeys as potential tar‐
1863                     gets. Note that this option is not  used  with  HKP  key‐
1864                     servers, as they do not support retrieving keys by subkey
1865                     id.
1866
1867
1868              timeout
1869              http-proxy=value
1870              verbose
1871              debug
1872              check-cert
1873
1874              ca-cert-file
1875                     These options have no more function since GnuPG 2.1.  Use
1876                     the dirmngr configuration options instead.
1877
1878
1879       The  default list of options is: "self-sigs-only, import-clean, repair-
1880       keys, repair-pks-subkey-bug, export-attributes, honor-pka-record".
1881
1882
1883
1884       --completes-needed n
1885              Number of completely trusted users to introduce a new key signer
1886              (defaults to 1).
1887
1888
1889       --marginals-needed n
1890              Number of marginally trusted users to introduce a new key signer
1891              (defaults to 3)
1892
1893
1894       --tofu-default-policy {auto|good|unknown|bad|ask}
1895              The default TOFU policy (defaults to auto).  For  more  informa‐
1896              tion about the meaning of this option, see: [trust-model-tofu].
1897
1898
1899       --max-cert-depth n
1900              Maximum depth of a certification chain (default is 5).
1901
1902
1903       --no-sig-cache
1904              Do not cache the verification status of key signatures.  Caching
1905              gives a much better performance in key listings. However, if you
1906              suspect that your public keyring is not safe against write modi‐
1907              fications, you can use this option to disable  the  caching.  It
1908              probably  does  not make sense to disable it because all kind of
1909              damage can be done if someone else has write access to your pub‐
1910              lic keyring.
1911
1912
1913       --auto-check-trustdb
1914       --no-auto-check-trustdb
1915              If  GnuPG  feels that its information about the Web of Trust has
1916              to be updated, it automatically runs the --check-trustdb command
1917              internally.   This  may  be a time consuming process. --no-auto-
1918              check-trustdb disables this option.
1919
1920
1921       --use-agent
1922       --no-use-agent
1923              This is dummy option. gpg always requires the agent.
1924
1925
1926       --gpg-agent-info
1927              This is dummy option. It has no effect when used with gpg.
1928
1929
1930
1931       --agent-program file
1932              Specify an agent program to be used for secret  key  operations.
1933              The  default  value  is  determined  by running gpgconf with the
1934              option --list-dirs.  Note that the pipe symbol (|) is used for a
1935              regression  test suite hack and may thus not be used in the file
1936              name.
1937
1938
1939       --dirmngr-program file
1940              Specify a dirmngr program to be used for keyserver access.   The
1941              default value is ‘/usr/bin/dirmngr’.
1942
1943
1944       --disable-dirmngr
1945              Entirely disable the use of the Dirmngr.
1946
1947
1948       --no-autostart
1949              Do not start the gpg-agent or the dirmngr if it has not yet been
1950              started and its service is required.  This option is mostly use‐
1951              ful on machines where the connection to gpg-agent has been redi‐
1952              rected to another machines.   If  dirmngr  is  required  on  the
1953              remote  machine,  it  may  be  started  manually  using  gpgconf
1954              --launch dirmngr.
1955
1956
1957       --lock-once
1958              Lock the databases the first time a lock is requested and do not
1959              release the lock until the process terminates.
1960
1961
1962       --lock-multiple
1963              Release  the  locks  every  time a lock is no longer needed. Use
1964              this to override a previous --lock-once from a config file.
1965
1966
1967       --lock-never
1968              Disable locking entirely. This option should  be  used  only  in
1969              very special environments, where it can be assured that only one
1970              process is accessing those  files.  A  bootable  floppy  with  a
1971              stand-alone  encryption  system will probably use this. Improper
1972              usage of this option may lead to data and key corruption.
1973
1974
1975       --exit-on-status-write-error
1976              This option will cause write errors on the status FD to  immedi‐
1977              ately  terminate the process. That should in fact be the default
1978              but it never worked this way and  thus  we  need  an  option  to
1979              enable  this,  so that the change won't break applications which
1980              close their end of a status fd connected pipe too  early.  Using
1981              this  option  along with --enable-progress-filter may be used to
1982              cleanly cancel long running gpg operations.
1983
1984
1985       --limit-card-insert-tries n
1986              With n greater than 0 the number of prompts asking to  insert  a
1987              smartcard  gets limited to N-1. Thus with a value of 1 gpg won't
1988              at all ask to insert  a  card  if  none  has  been  inserted  at
1989              startup. This option is useful in the configuration file in case
1990              an application does not know about  the  smartcard  support  and
1991              waits ad infinitum for an inserted card.
1992
1993
1994       --no-random-seed-file
1995              GnuPG uses a file to store its internal random pool over invoca‐
1996              tions.  This makes random generation faster;  however  sometimes
1997              write  operations  are  not  desired. This option can be used to
1998              achieve that with the cost of slower random generation.
1999
2000
2001       --no-greeting
2002              Suppress the initial copyright message.
2003
2004
2005       --no-secmem-warning
2006              Suppress the warning about "using insecure memory".
2007
2008
2009       --no-permission-warning
2010              Suppress the  warning  about  unsafe  file  and  home  directory
2011              (--homedir)  permissions.  Note  that the permission checks that
2012              GnuPG performs are not intended to be authoritative, but  rather
2013              they  simply  warn  about certain common permission problems. Do
2014              not assume that the lack of a warning means that your system  is
2015              secure.
2016
2017              Note that the warning for unsafe --homedir permissions cannot be
2018              suppressed in the gpg.conf file, as this would allow an attacker
2019              to  place an unsafe gpg.conf file in place, and use this file to
2020              suppress warnings about itself. The --homedir permissions  warn‐
2021              ing may only be suppressed on the command line.
2022
2023
2024       --require-secmem
2025       --no-require-secmem
2026              Refuse  to run if GnuPG cannot get secure memory. Defaults to no
2027              (i.e. run, but give a warning).
2028
2029
2030
2031       --require-cross-certification
2032       --no-require-cross-certification
2033              When verifying a signature made from a subkey, ensure  that  the
2034              cross  certification  "back  signature" on the subkey is present
2035              and valid.  This protects against a subtle attack  against  sub‐
2036              keys  that  can sign.  Defaults to --require-cross-certification
2037              for gpg.
2038
2039
2040       --expert
2041       --no-expert
2042              Allow the user to do certain nonsensical or "silly" things  like
2043              signing an expired or revoked key, or certain potentially incom‐
2044              patible things like generating unusual key types. This also dis‐
2045              ables  certain  warning  messages about potentially incompatible
2046              actions. As the name implies, this option is for  experts  only.
2047              If you don't fully understand the implications of what it allows
2048              you to do, leave this off. --no-expert disables this option.
2049
2050
2051   Key related options
2052
2053
2054
2055
2056       --recipient name
2057       -r     Encrypt for user id name. If this option  or  --hidden-recipient
2058              is  not  specified, GnuPG asks for the user-id unless --default-
2059              recipient is given.
2060
2061
2062       --hidden-recipient name
2063       -R     Encrypt for user ID name, but hide the key  ID  of  this  user's
2064              key.  This  option helps to hide the receiver of the message and
2065              is a limited countermeasure against traffic  analysis.  If  this
2066              option  or --recipient is not specified, GnuPG asks for the user
2067              ID unless --default-recipient is given.
2068
2069
2070       --recipient-file file
2071       -f     This option is similar to --recipient except that it encrypts to
2072              a key stored in the given file.  file must be the name of a file
2073              containing exactly one key.  gpg assumes that the  key  in  this
2074              file is fully valid.
2075
2076
2077       --hidden-recipient-file file
2078       -F     This  option  is  similar  to  --hidden-recipient except that it
2079              encrypts to a key stored in the given file.  file  must  be  the
2080              name of a file containing exactly one key.  gpg assumes that the
2081              key in this file is fully valid.
2082
2083
2084       --encrypt-to name
2085              Same as --recipient but this one is  intended  for  use  in  the
2086              options  file  and  may  be  used  with  your  own user-id as an
2087              "encrypt-to-self". These keys are only used when there are other
2088              recipients  given  either  by use of --recipient or by the asked
2089              user id.  No trust checking is performed for these user ids  and
2090              even disabled keys can be used.
2091
2092
2093       --hidden-encrypt-to name
2094              Same  as  --hidden-recipient but this one is intended for use in
2095              the options file and may be used with your own user-id as a hid‐
2096              den  "encrypt-to-self".  These keys are only used when there are
2097              other recipients given either by use of --recipient  or  by  the
2098              asked  user  id.   No trust checking is performed for these user
2099              ids and even disabled keys can be used.
2100
2101
2102       --no-encrypt-to
2103              Disable the use  of  all  --encrypt-to  and  --hidden-encrypt-to
2104              keys.
2105
2106
2107       --group {name=value}
2108              Sets up a named group, which is similar to aliases in email pro‐
2109              grams.  Any time the group name is a recipient (-r or  --recipi‐
2110              ent),  it  will  be  expanded  to the values specified. Multiple
2111              groups with the same name are automatically merged into a single
2112              group.
2113
2114              The  values are key IDs or fingerprints, but any key description
2115              is accepted. Note that a value with spaces in it will be treated
2116              as  two  different  values. Note also there is only one level of
2117              expansion --- you cannot make an group that  points  to  another
2118              group.  When  used from the command line, it may be necessary to
2119              quote the argument to this option  to  prevent  the  shell  from
2120              treating it as multiple arguments.
2121
2122
2123       --ungroup name
2124              Remove a given entry from the --group list.
2125
2126
2127       --no-groups
2128              Remove all entries from the --group list.
2129
2130
2131       --local-user name
2132       -u     Use  name  as  the key to sign with. Note that this option over‐
2133              rides --default-key.
2134
2135
2136       --sender mbox
2137              This option has two purposes.  mbox must either  be  a  complete
2138              user id with a proper mail address or just a mail address.  When
2139              creating a signature this option tells gpg the user id of a  key
2140              used  to  make a signature if the key was not directly specified
2141              by a user id.  When verifying a signature the mbox  is  used  to
2142              restrict  the  information  printed by the TOFU code to matching
2143              user ids.
2144
2145
2146       --try-secret-key name
2147              For hidden recipients GPG needs to know  the  keys  to  use  for
2148              trial  decryption.   The  key  set  with --default-key is always
2149              tried first, but this is  often  not  sufficient.   This  option
2150              allows  setting  more  keys  to  be  used  for trial decryption.
2151              Although any valid user-id specification may be used for name it
2152              makes sense to use at least the long keyid to avoid ambiguities.
2153              Note that gpg-agent might pop up a pinentry for a lot keys to do
2154              the  trial  decryption.   If  you want to stop all further trial
2155              decryption you may use close-window button instead of the cancel
2156              button.
2157
2158
2159       --try-all-secrets
2160              Don't  look  at  the key ID as stored in the message but try all
2161              secret keys in turn to  find  the  right  decryption  key.  This
2162              option  forces  the  behaviour  as  used by anonymous recipients
2163              (created by  using  --throw-keyids  or  --hidden-recipient)  and
2164              might  come  handy in case where an encrypted message contains a
2165              bogus key ID.
2166
2167
2168       --skip-hidden-recipients
2169       --no-skip-hidden-recipients
2170              During decryption skip all anonymous  recipients.   This  option
2171              helps  in the case that people use the hidden recipients feature
2172              to hide their own encrypt-to key from others.  If one  has  many
2173              secret  keys this may lead to a major annoyance because all keys
2174              are tried in turn to decrypt  something  which  was  not  really
2175              intended for it.  The drawback of this option is that it is cur‐
2176              rently not possible to decrypt a  message  which  includes  real
2177              anonymous recipients.
2178
2179
2180
2181   Input and Output
2182
2183
2184
2185
2186       --armor
2187       -a     Create  ASCII  armored  output.   The  default  is to create the
2188              binary OpenPGP format.
2189
2190
2191       --no-armor
2192              Assume the input data is not in ASCII armored format.
2193
2194
2195       --output file
2196       -o file
2197              Write output to file.  To write to stdout use - as the filename.
2198
2199
2200       --max-output n
2201              This option sets a limit on the number of  bytes  that  will  be
2202              generated when processing a file. Since OpenPGP supports various
2203              levels of compression, it is possible that the  plaintext  of  a
2204              given  message  may  be  significantly  larger than the original
2205              OpenPGP message. While GnuPG works properly with such  messages,
2206              there  is often a desire to set a maximum file size that will be
2207              generated before processing is forced to stop by the OS  limits.
2208              Defaults to 0, which means "no limit".
2209
2210
2211       --input-size-hint n
2212              This  option  can be used to tell GPG the size of the input data
2213              in bytes.  n must be a positive base-10 number.  This option  is
2214              only  useful if the input is not taken from a file.  GPG may use
2215              this hint to optimize its buffer  allocation  strategy.   It  is
2216              also  used  by  the  --status-fd  line ``PROGRESS'' to provide a
2217              value for ``total'' if that is not available by other means.
2218
2219
2220       --key-origin string[,url]
2221              gpg can track the origin of a key. Certain origins  are  implic‐
2222              itly  known  (e.g. keyserver, web key directory) and set.  For a
2223              standard import the origin of the keys imported can be set  with
2224              this option.  To list the possible values use "help" for string.
2225              Some origins can store an optional url argument.  That  URL  can
2226              appended to string after a comma.
2227
2228
2229       --import-options parameters
2230              This is a space or comma delimited string that gives options for
2231              importing keys. Options can be prepended with a  `no-'  to  give
2232              the opposite meaning. The options are:
2233
2234
2235
2236              import-local-sigs
2237                     Allow importing key signatures marked as "local". This is
2238                     not generally useful unless a shared  keyring  scheme  is
2239                     being used.  Defaults to no.
2240
2241
2242              keep-ownertrust
2243                     Normally  possible  still existing ownertrust values of a
2244                     key are cleared if a key is imported.  This is in general
2245                     desirable  so  that a formerly deleted key does not auto‐
2246                     matically gain an ownertrust values merely due to import.
2247                     On  the other hand it is sometimes necessary to re-import
2248                     a trusted set of keys again but keeping already  assigned
2249                     ownertrust  values.   This  can be achieved by using this
2250                     option.
2251
2252
2253              repair-pks-subkey-bug
2254                     During import, attempt to repair the damage caused by the
2255                     PKS  keyserver  bug (pre version 0.9.6) that mangles keys
2256                     with multiple subkeys. Note that this  cannot  completely
2257                     repair the damaged key as some crucial data is removed by
2258                     the keyserver, but it does at least  give  you  back  one
2259                     subkey.  Defaults  to  no for regular --import and to yes
2260                     for keyserver --receive-keys.
2261
2262
2263              import-show
2264              show-only
2265                     Show a listing of the key as imported right before it  is
2266                     stored.   This  can be combined with the option --dry-run
2267                     to only look at keys; the option show-only is a  shortcut
2268                     for this combination.  The command --show-keys is another
2269                     shortcut for this.  Note that suffixes like '#' for "sec"
2270                     and "sbb" lines may or may not be printed.
2271
2272
2273              import-export
2274                     Run the entire import code but instead of storing the key
2275                     to the local keyring write it to the output.  The  export
2276                     options  export-pka  and  export-dane  affect the output.
2277                     This option can be used to remove all invalid parts  from
2278                     a key without the need to store it.
2279
2280
2281              merge-only
2282                     During import, allow key updates to existing keys, but do
2283                     not allow any new keys to be imported. Defaults to no.
2284
2285
2286              import-clean
2287                     After import, compact (remove all signatures  except  the
2288                     self-signature)  any  user  IDs from the new key that are
2289                     not usable.  Then, remove any signatures from the new key
2290                     that  are not usable.  This includes signatures that were
2291                     issued by keys that are not present on the keyring.  This
2292                     option  is  the  same  as  running the --edit-key command
2293                     "clean" after import. Defaults to no.
2294
2295
2296              self-sigs-only
2297                     Accept only self-signatures while importing a  key.   All
2298                     other  key  signatures  are  skipped  at  an early import
2299                     stage.  This option can be used with keyserver-options to
2300                     mitigate  attempts  to  flood a key with bogus signatures
2301                     from a keyserver.  The drawback is that all  other  valid
2302                     key  signatures, as required by the Web of Trust are also
2303                     not imported.  Note that when  using  this  option  along
2304                     with  import-clean  it  suppresses  the  final clean step
2305                     after merging the imported key into the existing key.
2306
2307
2308              repair-keys
2309                     After import, fix various problems with  the  keys.   For
2310                     example,  this  reorders signatures, and strips duplicate
2311                     signatures.  Defaults to yes.
2312
2313
2314              import-minimal
2315                     Import the smallest key possible. This removes all signa‐
2316                     tures  except the most recent self-signature on each user
2317                     ID. This option is the same  as  running  the  --edit-key
2318                     command "minimize" after import.  Defaults to no.
2319
2320
2321              restore
2322              import-restore
2323                     Import  in key restore mode.  This imports all data which
2324                     is usually skipped during  import;  including  all  GnuPG
2325                     specific data.  All other contradicting options are over‐
2326                     ridden.
2327
2328
2329       --import-filter {name=expr}
2330       --export-filter {name=expr}
2331              These options define an import/export filter which  are  applied
2332              to  the  imported/exported  keyblock  right  before  it  will be
2333              stored/written.  name defines the type of filter  to  use,  expr
2334              the  expression  to  evaluate.   The  option can be used several
2335              times which then appends more expression to the same name.
2336
2337
2338              The available filter types are:
2339
2340
2341
2342              keep-uid
2343                     This filter will keep a user id packet and its  dependent
2344                     packets  in  the  keyblock if the expression evaluates to
2345                     true.
2346
2347
2348              drop-subkey
2349                     This filter drops the selected subkeys.   Currently  only
2350                     implemented for --export-filter.
2351
2352
2353              drop-sig
2354                     This  filter  drops  the  selected key signatures on user
2355                     ids.  Self-signatures are not considered.  Currently only
2356                     implemented for --import-filter.
2357
2358
2359       For  the syntax of the expression see the chapter "FILTER EXPRESSIONS".
2360       The property names for the expressions depend on the actual filter type
2361       and are indicated in the following table.
2362
2363       The available properties are:
2364
2365
2366
2367              uid    A string with the user id.  (keep-uid)
2368
2369
2370              mbox   The addr-spec part of a user id with mailbox or the empty
2371                     string.  (keep-uid)
2372
2373
2374              key_algo
2375                     A number with the public key algorithm of a key or subkey
2376                     packet.  (drop-subkey)
2377
2378
2379              key_created
2380              key_created_d
2381                     The  first is the timestamp a public key or subkey packet
2382                     was created.  The second is the same but given as an  ISO
2383                     string, e.g. "2016-08-17". (drop-subkey)
2384
2385
2386              primary
2387                     Boolean  indicating  whether  the  user id is the primary
2388                     one.  (keep-uid)
2389
2390
2391              expired
2392                     Boolean indicating whether a user id  (keep-uid),  a  key
2393                     (drop-subkey), or a signature (drop-sig) expired.
2394
2395
2396              revoked
2397                     Boolean  indicating whether a user id (keep-uid) or a key
2398                     (drop-subkey) has been revoked.
2399
2400
2401              disabled
2402                     Boolean indicating whether a  primary  key  is  disabled.
2403                     (not used)
2404
2405
2406              secret Boolean  indicating  whether  a key or subkey is a secret
2407                     one.  (drop-subkey)
2408
2409
2410              usage  A string indicating the usage flags for the subkey,  from
2411                     the sequence ``ecsa?''.  For example, a subkey capable of
2412                     just signing and authentication would be an  exact  match
2413                     for ``sa''. (drop-subkey)
2414
2415
2416              sig_created
2417              sig_created_d
2418                     The  first  is  the timestamp a signature packet was cre‐
2419                     ated.  The second is the same but given as  an  ISO  date
2420                     string, e.g. "2016-08-17". (drop-sig)
2421
2422
2423              sig_algo
2424                     A  number  with  the  public key algorithm of a signature
2425                     packet. (drop-sig)
2426
2427
2428              sig_digest_algo
2429                     A number with the digest algorithm of a signature packet.
2430                     (drop-sig)
2431
2432
2433
2434       --export-options parameters
2435              This is a space or comma delimited string that gives options for
2436              exporting keys.  Options can be prepended with a `no-'  to  give
2437              the opposite meaning.  The options are:
2438
2439
2440
2441              export-local-sigs
2442                     Allow exporting key signatures marked as "local". This is
2443                     not generally useful unless a shared  keyring  scheme  is
2444                     being used.  Defaults to no.
2445
2446
2447              export-attributes
2448                     Include  attribute  user IDs (photo IDs) while exporting.
2449                     Not including attribute user IDs is useful to export keys
2450                     that are going to be used by an OpenPGP program that does
2451                     not accept attribute user IDs.  Defaults to yes.
2452
2453
2454              export-sensitive-revkeys
2455                     Include designated revoker information that was marked as
2456                     "sensitive". Defaults to no.
2457
2458
2459
2460              backup
2461              export-backup
2462                     Export  for  use as a backup.  The exported data includes
2463                     all data which is needed to restore the key or keys later
2464                     with  GnuPG.   The format is basically the OpenPGP format
2465                     but enhanced with GnuPG specific data.  All other contra‐
2466                     dicting options are overridden.
2467
2468
2469              export-clean
2470                     Compact  (remove all signatures from) user IDs on the key
2471                     being exported if the user IDs are not usable.  Also,  do
2472                     not  export  any  signatures  that  are  not usable. This
2473                     includes signatures that were issued by keys that are not
2474                     present  on  the keyring. This option is the same as run‐
2475                     ning the --edit-key command "clean" before export  except
2476                     that  the local copy of the key is not modified. Defaults
2477                     to no.
2478
2479
2480              export-minimal
2481                     Export the smallest key possible. This removes all signa‐
2482                     tures  except the most recent self-signature on each user
2483                     ID. This option is the same  as  running  the  --edit-key
2484                     command  "minimize"  before  export except that the local
2485                     copy of the key is not modified. Defaults to no.
2486
2487
2488              export-pka
2489                     Instead of outputting the key material output PKA records
2490                     suitable  to  put into DNS zone files.  An ORIGIN line is
2491                     printed before each record to allow diverting the records
2492                     to the corresponding zone file.
2493
2494
2495              export-dane
2496                     Instead  of  outputting  the  key material output OpenPGP
2497                     DANE records suitable to put into  DNS  zone  files.   An
2498                     ORIGIN  line  is  printed  before  each  record  to allow
2499                     diverting the records to the corresponding zone file.
2500
2501
2502
2503       --with-colons
2504              Print key listings delimited by colons.  Note  that  the  output
2505              will  be  encoded  in  UTF-8 regardless of any --display-charset
2506              setting. This format is useful when GnuPG is called from scripts
2507              and  other  programs as it is easily machine parsed. The details
2508              of this format are documented in the file  ‘doc/DETAILS’,  which
2509              is included in the GnuPG source distribution.
2510
2511
2512       --fixed-list-mode
2513              Do  not  merge  primary  user ID and primary key in --with-colon
2514              listing  mode  and  print  all  timestamps  as   seconds   since
2515              1970-01-01.   Since  GnuPG  2.0.10, this mode is always used and
2516              thus this option is obsolete; it does not harm to use it though.
2517
2518
2519       --legacy-list-mode
2520              Revert to the pre-2.1 public key list mode.  This  only  affects
2521              the  human  readable  output and not the machine interface (i.e.
2522              --with-colons).  Note that the legacy  format  does  not  convey
2523              suitable information for elliptic curves.
2524
2525
2526       --with-fingerprint
2527              Same as the command --fingerprint but changes only the format of
2528              the output and may be used together with another command.
2529
2530
2531       --with-subkey-fingerprint
2532              If a fingerprint is printed for the  primary  key,  this  option
2533              forces  printing of the fingerprint for all subkeys.  This could
2534              also be achieved by using the --with-fingerprint  twice  but  by
2535              using  this option along with keyid-format "none" a compact fin‐
2536              gerprint is printed.
2537
2538
2539       --with-icao-spelling
2540              Print the ICAO spelling of the fingerprint in  addition  to  the
2541              hex digits.
2542
2543
2544       --with-keygrip
2545              Include  the keygrip in the key listings.  In --with-colons mode
2546              this is implicitly enable for secret keys.
2547
2548
2549       --with-key-origin
2550              Include the locally held information  on  the  origin  and  last
2551              update of a key in a key listing.  In --with-colons mode this is
2552              always printed.  This data is currently experimental  and  shall
2553              not be considered part of the stable API.
2554
2555
2556       --with-wkd-hash
2557              Print  a Web Key Directory identifier along with each user ID in
2558              key listings.  This is an experimental feature and semantics may
2559              change.
2560
2561
2562       --with-secret
2563              Include  info  about  the presence of a secret key in public key
2564              listings done with --with-colons.
2565
2566
2567   OpenPGP protocol specific options
2568
2569
2570
2571
2572       -t, --textmode
2573       --no-textmode
2574              Treat input files as text and store them in the OpenPGP  canoni‐
2575              cal  text form with standard "CRLF" line endings. This also sets
2576              the necessary flags to inform the recipient that  the  encrypted
2577              or  signed  data is text and may need its line endings converted
2578              back to whatever the local system uses. This  option  is  useful
2579              when  communicating  between  two  platforms that have different
2580              line ending conventions (UNIX-like to Mac, Mac to Windows, etc).
2581              --no-textmode disables this option, and is the default.
2582
2583
2584       --force-v3-sigs
2585       --no-force-v3-sigs
2586
2587       --force-v4-certs
2588       --no-force-v4-certs
2589              These options are obsolete and have no effect since GnuPG 2.1.
2590
2591
2592       --force-mdc
2593       --disable-mdc
2594              These options are obsolete and have no effect since GnuPG 2.2.8.
2595              The MDC is always used.  But note: If the creation of  a  legacy
2596              non-MDC  message is exceptionally required, the option --rfc2440
2597              allows for this.
2598
2599
2600       --disable-signer-uid
2601              By default the user ID of the signing key  is  embedded  in  the
2602              data  signature.  As of now this is only done if the signing key
2603              has been specified with local-user using a mail address, or with
2604              sender.   This information can be helpful for verifier to locate
2605              the key; see option --auto-key-retrieve.
2606
2607
2608       --personal-cipher-preferences string
2609              Set the list of personal cipher preferences to string.  Use  gpg
2610              --version to get a list of available algorithms, and use none to
2611              set no preference at all.  This allows the user to safely  over‐
2612              ride  the  algorithm chosen by the recipient key preferences, as
2613              GPG will only select an algorithm that is usable by all  recipi‐
2614              ents.   The  most highly ranked cipher in this list is also used
2615              for the --symmetric encryption command.
2616
2617
2618       --personal-digest-preferences string
2619              Set the list of personal digest preferences to string.  Use  gpg
2620              --version to get a list of available algorithms, and use none to
2621              set no preference at all.  This allows the user to safely  over‐
2622              ride  the  algorithm chosen by the recipient key preferences, as
2623              GPG will only select an algorithm that is usable by all  recipi‐
2624              ents.   The  most highly ranked digest algorithm in this list is
2625              also used when signing without encryption (e.g. --clear-sign  or
2626              --sign).
2627
2628
2629       --personal-compress-preferences string
2630              Set the list of personal compression preferences to string.  Use
2631              gpg --version to get a list of  available  algorithms,  and  use
2632              none  to  set  no  preference  at  all.  This allows the user to
2633              safely override the algorithm chosen by the recipient key  pref‐
2634              erences,  as GPG will only select an algorithm that is usable by
2635              all recipients.  The most highly ranked compression algorithm in
2636              this  list is also used when there are no recipient keys to con‐
2637              sider (e.g. --symmetric).
2638
2639
2640       --s2k-cipher-algo name
2641              Use name as the cipher algorithm for symmetric encryption with a
2642              passphrase  if  --personal-cipher-preferences  and --cipher-algo
2643              are not given.  The default is AES-128.
2644
2645
2646       --s2k-digest-algo name
2647              Use name as the digest algorithm used to mangle the  passphrases
2648              for symmetric encryption.  The default is SHA-1.
2649
2650
2651       --s2k-mode n
2652              Selects how passphrases for symmetric encryption are mangled. If
2653              n is 0 a plain passphrase (which is in general not  recommended)
2654              will  be used, a 1 adds a salt (which should not be used) to the
2655              passphrase and a 3 (the default) iterates the  whole  process  a
2656              number of times (see --s2k-count).
2657
2658
2659       --s2k-count n
2660              Specify  how  many  times the passphrases mangling for symmetric
2661              encryption is repeated.  This value may range between  1024  and
2662              65011712  inclusive.   The  default  is inquired from gpg-agent.
2663              Note that not all values in the 1024-65011712  range  are  legal
2664              and  if an illegal value is selected, GnuPG will round up to the
2665              nearest legal value.  This option is only meaningful  if  --s2k-
2666              mode is set to the default of 3.
2667
2668
2669
2670   Compliance options
2671
2672
2673       These  options  control  what  GnuPG is compliant to. Only one of these
2674       options may be active at a time. Note that the default setting of  this
2675       is  nearly  always the correct one. See the INTEROPERABILITY WITH OTHER
2676       OPENPGP PROGRAMS section below before using one of these options.
2677
2678
2679
2680       --gnupg
2681              Use standard GnuPG behavior. This is essentially OpenPGP  behav‐
2682              ior  (see  --openpgp),  but with some additional workarounds for
2683              common compatibility problems in different versions of PGP. This
2684              is the default option, so it is not generally needed, but it may
2685              be useful to override  a  different  compliance  option  in  the
2686              gpg.conf file.
2687
2688
2689       --openpgp
2690              Reset  all  packet,  cipher and digest options to strict OpenPGP
2691              behavior. Use this option to reset  all  previous  options  like
2692              --s2k-*,  --cipher-algo,  --digest-algo  and  --compress-algo to
2693              OpenPGP compliant values. All PGP workarounds are disabled.
2694
2695
2696       --rfc4880
2697              Reset all packet, cipher and digest options to  strict  RFC-4880
2698              behavior.  Note  that  this  is  currently  the  same  thing  as
2699              --openpgp.
2700
2701
2702       --rfc4880bis
2703              Enable experimental features from proposed updates to  RFC-4880.
2704              This  option  can  be  used  in addition to the other compliance
2705              options.  Warning:  The  behavior  may  change  with  any  GnuPG
2706              release  and  created keys or data may not be usable with future
2707              GnuPG versions.
2708
2709
2710       --rfc2440
2711              Reset all packet, cipher and digest options to  strict  RFC-2440
2712              behavior.  Note that by using this option encryption packets are
2713              created in a legacy mode without MDC protection.  This  is  dan‐
2714              gerous  and  should thus only be used for experiments.  See also
2715              option --ignore-mdc-error.
2716
2717
2718       --pgp6 Set up all options to be as PGP 6 compliant  as  possible.  This
2719              restricts  you  to  the  ciphers  IDEA  (if  the  IDEA plugin is
2720              installed), 3DES, and CAST5, the hashes MD5, SHA1 and RIPEMD160,
2721              and  the compression algorithms none and ZIP. This also disables
2722              --throw-keyids, and making signatures with  signing  subkeys  as
2723              PGP 6 does not understand signatures made by signing subkeys.
2724
2725              This option implies --escape-from-lines.
2726
2727
2728       --pgp7 Set up all options to be as PGP 7 compliant as possible. This is
2729              identical to --pgp6 except that MDCs are not disabled,  and  the
2730              list  of  allowable  ciphers  is expanded to add AES128, AES192,
2731              AES256, and TWOFISH.
2732
2733
2734       --pgp8 Set up all options to be as PGP 8 compliant as possible.  PGP  8
2735              is  a  lot closer to the OpenPGP standard than previous versions
2736              of PGP, so all this  does  is  disable  --throw-keyids  and  set
2737              --escape-from-lines.   All algorithms are allowed except for the
2738              SHA224, SHA384, and SHA512 digests.
2739
2740
2741       --compliance string
2742              This option can be used instead of one  of  the  options  above.
2743              Valid  values for string are the above option names (without the
2744              double dash) and possibly others as shown when using "help"  for
2745              value.
2746
2747
2748   Doing things one usually doesn't want to do
2749
2750
2751
2752
2753       -n
2754       --dry-run
2755              Don't make any changes (this is not completely implemented).
2756
2757
2758       --list-only
2759              Changes  the  behaviour of some commands. This is like --dry-run
2760              but different in some cases. The semantic of this option may  be
2761              extended  in  the  future.  Currently  it  only skips the actual
2762              decryption pass and therefore enables  a  fast  listing  of  the
2763              encryption keys.
2764
2765
2766       -i
2767       --interactive
2768              Prompt before overwriting any files.
2769
2770
2771       --debug-level level
2772              Select  the debug level for investigating problems. level may be
2773              a numeric value or by a keyword:
2774
2775
2776              none   No debugging at all.  A value of less than 1 may be  used
2777                     instead of the keyword.
2778
2779              basic  Some  basic  debug messages.  A value between 1 and 2 may
2780                     be used instead of the keyword.
2781
2782              advanced
2783                     More verbose debug messages.  A value between 3 and 5 may
2784                     be used instead of the keyword.
2785
2786              expert Even more detailed messages.  A value between 6 and 8 may
2787                     be used instead of the keyword.
2788
2789              guru   All of the debug messages you can get.  A  value  greater
2790                     than  8 may be used instead of the keyword.  The creation
2791                     of hash tracing files is only enabled if the  keyword  is
2792                     used.
2793
2794       How  these  messages  are  mapped  to the actual debugging flags is not
2795       specified and may change with newer releases of this program. They  are
2796       however carefully selected to best aid in debugging.
2797
2798
2799       --debug flags
2800              Set  debugging flags. All flags are or-ed and flags may be given
2801              in C syntax (e.g. 0x0042) or as a comma separated list  of  flag
2802              names.   To  get  a  list of all supported flags the single word
2803              "help" can be used.
2804
2805
2806       --debug-all
2807              Set all useful debugging flags.
2808
2809
2810       --debug-iolbf
2811              Set stdout into line buffered mode.  This option is only honored
2812              when given on the command line.
2813
2814
2815       --faked-system-time epoch
2816              This  option is only useful for testing; it sets the system time
2817              back or forth to epoch which is the number  of  seconds  elapsed
2818              since the year 1970.  Alternatively epoch may be given as a full
2819              ISO time string (e.g. "20070924T154812").
2820
2821              If you suffix epoch with an exclamation  mark  (!),  the  system
2822              time will appear to be frozen at the specified time.
2823
2824
2825       --enable-progress-filter
2826              Enable certain PROGRESS status outputs. This option allows fron‐
2827              tends to display a progress indicator while  gpg  is  processing
2828              larger files.  There is a slight performance overhead using it.
2829
2830
2831       --status-fd n
2832              Write  special status strings to the file descriptor n.  See the
2833              file DETAILS in the documentation for a listing of them.
2834
2835
2836       --status-file file
2837              Same as --status-fd, except the status data is written  to  file
2838              file.
2839
2840
2841       --logger-fd n
2842              Write log output to file descriptor n and not to STDERR.
2843
2844
2845       --log-file file
2846       --logger-file file
2847              Same  as  --logger-fd, except the logger data is written to file
2848              file.  Use ‘socket://’ to log to a socket.  Note  that  in  this
2849              version  of gpg the option has only an effect if --batch is also
2850              used.
2851
2852
2853       --attribute-fd n
2854              Write attribute subpackets to the file  descriptor  n.  This  is
2855              most  useful for use with --status-fd, since the status messages
2856              are needed to separate  out  the  various  subpackets  from  the
2857              stream delivered to the file descriptor.
2858
2859
2860       --attribute-file file
2861              Same  as --attribute-fd, except the attribute data is written to
2862              file file.
2863
2864
2865       --comment string
2866       --no-comments
2867              Use string as a comment string in cleartext signatures and ASCII
2868              armored  messages or keys (see --armor). The default behavior is
2869              not to use a comment string. --comment may be repeated  multiple
2870              times to get multiple comment strings. --no-comments removes all
2871              comments.  It is a good idea to keep the length of a single com‐
2872              ment  below  60  characters to avoid problems with mail programs
2873              wrapping such lines.  Note that comment lines,  like  all  other
2874              header lines, are not protected by the signature.
2875
2876
2877       --emit-version
2878       --no-emit-version
2879              Force  inclusion  of the version string in ASCII armored output.
2880              If given once only the name of the program and the major  number
2881              is  emitted, given twice the minor is also emitted, given thrice
2882              the micro is added, and given four  times  an  operating  system
2883              identification  is  also  emitted.   --no-emit-version (default)
2884              disables the version line.
2885
2886
2887       --sig-notation {name=value}
2888       --cert-notation {name=value}
2889       -N, --set-notation {name=value}
2890              Put the name value pair into the  signature  as  notation  data.
2891              name  must  consist  only of printable characters or spaces, and
2892              must contain a '@' character in  the  form  keyname@domain.exam‐
2893              ple.com  (substituting  the appropriate keyname and domain name,
2894              of course).  This is to  help  prevent  pollution  of  the  IETF
2895              reserved notation namespace. The --expert flag overrides the '@'
2896              check. value may be any printable string; it will be encoded  in
2897              UTF-8,  so  you  should check that your --display-charset is set
2898              correctly. If you prefix name with an exclamation mark (!),  the
2899              notation  data  will  be flagged as critical (rfc4880:5.2.3.16).
2900              --sig-notation sets a notation for data signatures. --cert-nota‐
2901              tion sets a notation for key signatures (certifications). --set-
2902              notation sets both.
2903
2904              There are special codes that may be used in notation names. "%k"
2905              will  be  expanded into the key ID of the key being signed, "%K"
2906              into the long key ID of the key being signed, "%f" into the fin‐
2907              gerprint  of  the  key being signed, "%s" into the key ID of the
2908              key making the signature, "%S" into the long key ID of  the  key
2909              making  the signature, "%g" into the fingerprint of the key mak‐
2910              ing the signature (which might be a subkey), "%p" into the  fin‐
2911              gerprint  of  the  primary  key of the key making the signature,
2912              "%c" into the signature count from the  OpenPGP  smartcard,  and
2913              "%%" results in a single "%". %k, %K, and %f are only meaningful
2914              when making a key signature  (certification),  and  %c  is  only
2915              meaningful when using the OpenPGP smartcard.
2916
2917
2918       --known-notation name
2919              Adds  name to a list of known critical signature notations.  The
2920              effect of this is that gpg will not  mark  a  signature  with  a
2921              critical  signature notation of that name as bad.  Note that gpg
2922              already knows by default about a few critical  signatures  nota‐
2923              tion names.
2924
2925
2926       --sig-policy-url string
2927       --cert-policy-url string
2928       --set-policy-url string
2929              Use  string  as  a Policy URL for signatures (rfc4880:5.2.3.20).
2930              If you prefix it with an exclamation mark (!),  the  policy  URL
2931              packet will be flagged as critical. --sig-policy-url sets a pol‐
2932              icy url for data signatures. --cert-policy-url sets a policy url
2933              for key signatures (certifications). --set-policy-url sets both.
2934
2935              The same %-expandos used for notation data are available here as
2936              well.
2937
2938
2939       --sig-keyserver-url string
2940              Use string as a preferred keyserver URL for data signatures.  If
2941              you  prefix  it  with an exclamation mark (!), the keyserver URL
2942              packet will be flagged as critical.
2943
2944              The same %-expandos used for notation data are available here as
2945              well.
2946
2947
2948       --set-filename string
2949              Use  string  as  the  filename  which is stored inside messages.
2950              This overrides the default, which is to use the actual  filename
2951              of  the file being encrypted.  Using the empty string for string
2952              effectively removes the filename from the output.
2953
2954
2955       --for-your-eyes-only
2956       --no-for-your-eyes-only
2957              Set the `for your eyes only' flag in the  message.  This  causes
2958              GnuPG  to  refuse to save the file unless the --output option is
2959              given, and PGP to use a "secure viewer" with a claimed  Tempest-
2960              resistant  font  to  display  the message. This option overrides
2961              --set-filename.  --no-for-your-eyes-only disables this option.
2962
2963
2964       --use-embedded-filename
2965       --no-use-embedded-filename
2966              Try to create a file with a name as embedded in the  data.  This
2967              can  be  a  dangerous  option  as  it enables overwriting files.
2968              Defaults to no.  Note that the option  --output  overrides  this
2969              option.
2970
2971
2972       --cipher-algo name
2973              Use  name as cipher algorithm. Running the program with the com‐
2974              mand --version yields a list of supported algorithms. If this is
2975              not  used  the cipher algorithm is selected from the preferences
2976              stored with the key. In general, you do not  want  to  use  this
2977              option as it allows you to violate the OpenPGP standard.  --per‐
2978              sonal-cipher-preferences is the safe way to accomplish the  same
2979              thing.
2980
2981
2982       --digest-algo name
2983              Use  name  as  the message digest algorithm. Running the program
2984              with the command --version yields  a  list  of  supported  algo‐
2985              rithms.  In  general,  you  do not want to use this option as it
2986              allows you to violate the OpenPGP  standard.  --personal-digest-
2987              preferences is the safe way to accomplish the same thing.
2988
2989
2990       --compress-algo name
2991              Use compression algorithm name. "zlib" is RFC-1950 ZLIB compres‐
2992              sion. "zip" is RFC-1951 ZIP compression which is  used  by  PGP.
2993              "bzip2"  is  a  more modern compression scheme that can compress
2994              some things better than zip or zlib, but at  the  cost  of  more
2995              memory used during compression and decompression. "uncompressed"
2996              or "none" disables compression. If this option is not used,  the
2997              default  behavior is to examine the recipient key preferences to
2998              see which algorithms the recipient supports. If all else  fails,
2999              ZIP is used for maximum compatibility.
3000
3001              ZLIB  may  give better compression results than ZIP, as the com‐
3002              pression window size is not limited to 8k. BZIP2 may  give  even
3003              better  compression  results  than that, but will use a signifi‐
3004              cantly larger amount of memory while compressing and decompress‐
3005              ing.  This  may  be  significant in low memory situations. Note,
3006              however, that PGP (all versions) only supports ZIP  compression.
3007              Using  any algorithm other than ZIP or "none" will make the mes‐
3008              sage unreadable with PGP. In general, you do  not  want  to  use
3009              this  option  as  it allows you to violate the OpenPGP standard.
3010              --personal-compress-preferences is the safe  way  to  accomplish
3011              the same thing.
3012
3013
3014       --cert-digest-algo name
3015              Use  name  as  the  message digest algorithm used when signing a
3016              key. Running the program with the  command  --version  yields  a
3017              list  of  supported  algorithms.  Be aware that if you choose an
3018              algorithm that GnuPG supports but other OpenPGP  implementations
3019              do  not,  then some users will not be able to use the key signa‐
3020              tures you make, or quite possibly your entire key.
3021
3022
3023       --disable-cipher-algo name
3024              Never allow the use of name as cipher algorithm.  The given name
3025              will  not be checked so that a later loaded algorithm will still
3026              get disabled.
3027
3028
3029       --disable-pubkey-algo name
3030              Never allow the use of name as public key algorithm.  The  given
3031              name  will  not be checked so that a later loaded algorithm will
3032              still get disabled.
3033
3034
3035       --throw-keyids
3036       --no-throw-keyids
3037              Do not put the recipient key IDs into encrypted  messages.  This
3038              helps  to  hide  the  receivers  of the message and is a limited
3039              countermeasure against traffic analysis. ([Using a little social
3040              engineering  anyone who is able to decrypt the message can check
3041              whether one of the other recipients is the  one  he  suspects.])
3042              On  the  receiving side, it may slow down the decryption process
3043              because all available secret keys must  be  tried.   --no-throw-
3044              keyids disables this option. This option is essentially the same
3045              as using --hidden-recipient for all recipients.
3046
3047
3048       --not-dash-escaped
3049              This option changes the behavior of cleartext signatures so that
3050              they  can  be  used for patch files. You should not send such an
3051              armored file via email because all spaces and line  endings  are
3052              hashed  too.  You  can  not use this option for data which has 5
3053              dashes at the beginning of a line, patch files don't have  this.
3054              A  special  armor  header  line tells GnuPG about this cleartext
3055              signature option.
3056
3057
3058       --escape-from-lines
3059       --no-escape-from-lines
3060              Because some mailers change  lines  starting  with  "From  "  to
3061              ">From  "  it is good to handle such lines in a special way when
3062              creating cleartext signatures to prevent the  mail  system  from
3063              breaking  the  signature. Note that all other PGP versions do it
3064              this way too.  Enabled by default.  --no-escape-from-lines  dis‐
3065              ables this option.
3066
3067
3068       --passphrase-repeat n
3069              Specify  how  many  times  gpg  will request a new passphrase be
3070              repeated.  This is useful for  helping  memorize  a  passphrase.
3071              Defaults to 1 repetition.
3072
3073
3074       --passphrase-fd n
3075              Read  the passphrase from file descriptor n. Only the first line
3076              will be read from file descriptor n. If you use  0  for  n,  the
3077              passphrase  will  be  read  from STDIN. This can only be used if
3078              only one passphrase is supplied.
3079
3080              Note that since Version 2.0 this passphrase is only used if  the
3081              option  --batch  has  also  been  given.  Since  Version 2.1 the
3082              --pinentry-mode also needs to be set to loopback.
3083
3084
3085       --passphrase-file file
3086              Read the passphrase from file file. Only the first line will  be
3087              read  from  file  file.  This  can  only  be  used  if  only one
3088              passphrase is supplied. Obviously, a passphrase stored in a file
3089              is  of  questionable security if other users can read this file.
3090              Don't use this option if you can avoid it.
3091
3092              Note that since Version 2.0 this passphrase is only used if  the
3093              option  --batch  has  also  been  given.  Since  Version 2.1 the
3094              --pinentry-mode also needs to be set to loopback.
3095
3096
3097       --passphrase string
3098              Use string as the passphrase. This can only be used if only  one
3099              passphrase  is supplied. Obviously, this is of very questionable
3100              security on a multi-user system. Don't use this  option  if  you
3101              can avoid it.
3102
3103              Note  that since Version 2.0 this passphrase is only used if the
3104              option --batch has  also  been  given.  Since  Version  2.1  the
3105              --pinentry-mode also needs to be set to loopback.
3106
3107
3108       --pinentry-mode mode
3109              Set the pinentry mode to mode.  Allowed values for mode are:
3110
3111              default
3112                     Use the default of the agent, which is ask.
3113
3114              ask    Force the use of the Pinentry.
3115
3116              cancel Emulate use of Pinentry's cancel button.
3117
3118              error  Return a Pinentry error (``No Pinentry'').
3119
3120              loopback
3121                     Redirect  Pinentry  queries  to the caller.  Note that in
3122                     contrast to Pinentry the user is not prompted again if he
3123                     enters a bad password.
3124
3125
3126       --no-symkey-cache
3127              Disable  the  passphrase  cache  used  for  symmetrical  en- and
3128              decryption.  This cache is based on the  message  specific  salt
3129              value (cf. --s2k-mode).
3130
3131
3132       --request-origin origin
3133              Tell  gpg  to assume that the operation ultimately originated at
3134              origin.   Depending  on  the  origin  certain  restrictions  are
3135              applied  and  the Pinentry may include an extra note on the ori‐
3136              gin.  Supported values  for  origin  are:  local  which  is  the
3137              default,  remote  to  indicate a remote origin or browser for an
3138              operation requested by a web browser.
3139
3140
3141       --command-fd n
3142              This is a replacement for the deprecated shared-memory IPC mode.
3143              If  this  option  is  enabled,  user  input  on questions is not
3144              expected from the TTY but from the  given  file  descriptor.  It
3145              should   be   used  together  with  --status-fd.  See  the  file
3146              doc/DETAILS in the source distribution for details on how to use
3147              it.
3148
3149
3150       --command-file file
3151              Same  as  --command-fd, except the commands are read out of file
3152              file
3153
3154
3155       --allow-non-selfsigned-uid
3156       --no-allow-non-selfsigned-uid
3157              Allow the import and use of keys with user  IDs  which  are  not
3158              self-signed.  This is not recommended, as a non self-signed user
3159              ID is trivial to forge. --no-allow-non-selfsigned-uid disables.
3160
3161
3162       --allow-freeform-uid
3163              Disable all checks on the form of the user ID while generating a
3164              new  one.  This option should only be used in very special envi‐
3165              ronments as it does not ensure the de-facto standard  format  of
3166              user IDs.
3167
3168
3169       --ignore-time-conflict
3170              GnuPG  normally  checks that the timestamps associated with keys
3171              and signatures have plausible values. However, sometimes a  sig‐
3172              nature  seems  to  be  older than the key due to clock problems.
3173              This  option  makes  these  checks  just  a  warning.  See  also
3174              --ignore-valid-from for timestamp issues on subkeys.
3175
3176
3177       --ignore-valid-from
3178              GnuPG  normally  does  not select and use subkeys created in the
3179              future.  This option allows  the  use  of  such  keys  and  thus
3180              exhibits the pre-1.0.7 behaviour. You should not use this option
3181              unless there is some clock problem. See also  --ignore-time-con‐
3182              flict for timestamp issues with signatures.
3183
3184
3185       --ignore-crc-error
3186              The  ASCII  armor used by OpenPGP is protected by a CRC checksum
3187              against transmission errors. Occasionally the CRC  gets  mangled
3188              somewhere  on  the  transmission  channel but the actual content
3189              (which is protected by the OpenPGP  protocol  anyway)  is  still
3190              okay. This option allows GnuPG to ignore CRC errors.
3191
3192
3193       --ignore-mdc-error
3194              This  option  changes  a MDC integrity protection failure into a
3195              warning.  It is required to decrypt old messages which  did  not
3196              use  an  MDC.   It  may also be useful if a message is partially
3197              garbled, but it is necessary to get as much data as possible out
3198              of  that garbled message.  Be aware that a missing or failed MDC
3199              can be an indication of an attack.  Use with great caution;  see
3200              also option --rfc2440.
3201
3202
3203       --allow-weak-digest-algos
3204              Signatures  made  with known-weak digest algorithms are normally
3205              rejected with an ``invalid  digest  algorithm''  message.   This
3206              option allows the verification of signatures made with such weak
3207              algorithms.  MD5 is the only digest algorithm considered weak by
3208              default.   See  also  --weak-digest to reject other digest algo‐
3209              rithms.
3210
3211
3212       --weak-digest name
3213              Treat the specified digest algorithm as weak.   Signatures  made
3214              over  weak digests algorithms are normally rejected. This option
3215              can be supplied multiple times if multiple algorithms should  be
3216              considered  weak.  See also --allow-weak-digest-algos to disable
3217              rejection of weak digests.  MD5 is always considered  weak,  and
3218              does not need to be listed explicitly.
3219
3220
3221       --allow-weak-key-signatures
3222              To  avoid  a  minor risk of collision attacks on third-party key
3223              signatures made using SHA-1, those key signatures are considered
3224              invalid.  This options allows to override this restriction.
3225
3226
3227       --no-default-keyring
3228              Do  not  add  the default keyrings to the list of keyrings. Note
3229              that GnuPG will not operate without any keyrings, so if you  use
3230              this  option and do not provide alternate keyrings via --keyring
3231              or --secret-keyring, then GnuPG will still use the default  pub‐
3232              lic or secret keyrings.
3233
3234
3235       --no-keyring
3236              Do  not  use any keyring at all.  This overrides the default and
3237              all options which specify keyrings.
3238
3239
3240       --skip-verify
3241              Skip the signature verification step. This may be used  to  make
3242              the  decryption  faster  if  the  signature  verification is not
3243              needed.
3244
3245
3246       --with-key-data
3247              Print key listings delimited by colons (like --with-colons)  and
3248              print the public key data.
3249
3250
3251       --list-signatures
3252       --list-sigs
3253              Same  as  --list-keys,  but the signatures are listed too.  This
3254              command has the same effect as using  --list-keys  with  --with-
3255              sig-list.   Note  that in contrast to --check-signatures the key
3256              signatures are not verified.  This command can be used to create
3257              a  list  of signing keys missing in the local keyring; for exam‐
3258              ple:
3259
3260               gpg --list-sigs --with-colons USERID | \
3261                 awk -F: '$1=="sig" && $2=="?" {if($13){print $13}else{print $5}}'
3262
3263
3264       --fast-list-mode
3265              Changes the output of the list commands to work faster; this  is
3266              achieved  by  leaving  some parts empty. Some applications don't
3267              need the user ID and the trust information given  in  the  list‐
3268              ings.  By  using this options they can get a faster listing. The
3269              exact behaviour of this option may change  in  future  versions.
3270              If you are missing some information, don't use this option.
3271
3272
3273       --no-literal
3274              This  is  not  for normal use. Use the source to see for what it
3275              might be useful.
3276
3277
3278       --set-filesize
3279              This is not for normal use. Use the source to see  for  what  it
3280              might be useful.
3281
3282
3283       --show-session-key
3284              Display  the  session  key used for one message. See --override-
3285              session-key for the counterpart of this option.
3286
3287              We think that Key Escrow is a Bad Thing; however the user should
3288              have  the freedom to decide whether to go to prison or to reveal
3289              the content of one specific  message  without  compromising  all
3290              messages ever encrypted for one secret key.
3291
3292              You can also use this option if you receive an encrypted message
3293              which is abusive or offensive, to prove to the administrators of
3294              the messaging system that the ciphertext transmitted corresponds
3295              to an inappropriate plaintext so they can  take  action  against
3296              the offending user.
3297
3298
3299       --override-session-key string
3300       --override-session-key-fd fd
3301              Don't  use  the public key but the session key string respective
3302              the session key  taken  from  the  first  line  read  from  file
3303              descriptor fd.  The format of this string is the same as the one
3304              printed by --show-session-key. This option is normally not  used
3305              but comes handy in case someone forces you to reveal the content
3306              of an encrypted message; using this option you can do this with‐
3307              out handing out the secret key.  Note that using --override-ses‐
3308              sion-key may reveal the session key to all local users  via  the
3309              global process table.  Often it is useful to combine this option
3310              with --no-keyring.
3311
3312
3313       --ask-sig-expire
3314       --no-ask-sig-expire
3315              When making a data signature, prompt for an expiration time.  If
3316              this  option  is  not  specified,  the  expiration  time set via
3317              --default-sig-expire is used. --no-ask-sig-expire disables  this
3318              option.
3319
3320
3321       --default-sig-expire
3322              The  default  expiration  time  to use for signature expiration.
3323              Valid values are "0" for no expiration, a number followed by the
3324              letter  d  (for  days), w (for weeks), m (for months), or y (for
3325              years) (for example "2m"  for  two  months,  or  "5y"  for  five
3326              years),  or an absolute date in the form YYYY-MM-DD. Defaults to
3327              "0".
3328
3329
3330       --ask-cert-expire
3331       --no-ask-cert-expire
3332              When making a key signature, prompt for an expiration  time.  If
3333              this  option  is  not  specified,  the  expiration  time set via
3334              --default-cert-expire  is  used.  --no-ask-cert-expire  disables
3335              this option.
3336
3337
3338       --default-cert-expire
3339              The default expiration time to use for key signature expiration.
3340              Valid values are "0" for no expiration, a number followed by the
3341              letter  d  (for  days), w (for weeks), m (for months), or y (for
3342              years) (for example "2m"  for  two  months,  or  "5y"  for  five
3343              years),  or an absolute date in the form YYYY-MM-DD. Defaults to
3344              "0".
3345
3346
3347       --default-new-key-algo string
3348              This option can be used to change the default algorithms for key
3349              generation.  The string is similar to the arguments required for
3350              the command --quick-add-key but slightly different.  For example
3351              the  current  default  of  "rsa2048/cert,sign+rsa2048/encr"  (or
3352              "rsa3072") can be changed to the value of what we currently call
3353              future  default, which is "ed25519/cert,sign+cv25519/encr".  You
3354              need to consult the source code to learn the details.  Note that
3355              the advanced key generation commands can always be used to spec‐
3356              ify a key algorithm directly.
3357
3358
3359       --allow-secret-key-import
3360              This is an obsolete option and is not used anywhere.
3361
3362
3363       --allow-multiple-messages
3364
3365       --no-allow-multiple-messages
3366              Allow processing of multiple OpenPGP  messages  contained  in  a
3367              single file or stream.  Some programs that call GPG are not pre‐
3368              pared to deal with multiple messages being  processed  together,
3369              so  this option defaults to no.  Note that versions of GPG prior
3370              to 1.4.7 always allowed multiple messages.
3371
3372              Warning: Do not use this option unless you need it as  a  tempo‐
3373              rary workaround!
3374
3375
3376
3377       --enable-special-filenames
3378              This option enables a mode in which filenames of the form ‘-&n’,
3379              where n is a non-negative decimal  number,  refer  to  the  file
3380              descriptor n and not to a file with that name.
3381
3382
3383       --no-expensive-trust-checks
3384              Experimental use only.
3385
3386
3387       --preserve-permissions
3388              Don't  change  the  permissions of a secret keyring back to user
3389              read/write only. Use this option only if you  really  know  what
3390              you are doing.
3391
3392
3393       --default-preference-list string
3394              Set  the  list of default preferences to string. This preference
3395              list is used for new keys and becomes the default for  "setpref"
3396              in the edit menu.
3397
3398
3399       --default-keyserver-url name
3400              Set  the  default  keyserver URL to name. This keyserver will be
3401              used as the keyserver URL when writing a new self-signature on a
3402              key, which includes key generation and changing preferences.
3403
3404
3405       --list-config
3406              Display various internal configuration parameters of GnuPG. This
3407              option is intended for external programs that call GnuPG to per‐
3408              form  tasks,  and  is  thus  not  generally useful. See the file
3409doc/DETAILS’ in the source  distribution  for  the  details  of
3410              which  configuration  items may be listed. --list-config is only
3411              usable with --with-colons set.
3412
3413
3414       --list-gcrypt-config
3415              Display various internal configuration parameters of Libgcrypt.
3416
3417
3418       --gpgconf-list
3419              This command is similar to --list-config  but  in  general  only
3420              internally used by the gpgconf tool.
3421
3422
3423       --gpgconf-test
3424              This  is  more or less dummy action.  However it parses the con‐
3425              figuration file and returns with failure  if  the  configuration
3426              file would prevent gpg from startup.  Thus it may be used to run
3427              a syntax check on the configuration file.
3428
3429
3430   Deprecated options
3431
3432
3433
3434
3435       --show-photos
3436       --no-show-photos
3437              Causes   --list-keys,   --list-signatures,   --list-public-keys,
3438              --list-secret-keys,  and  verifying  a signature to also display
3439              the photo ID attached to the key,  if  any.  See  also  --photo-
3440              viewer.   These   options  are  deprecated.  Use  --list-options
3441              [no-]show-photos   and/or   --verify-options    [no-]show-photos
3442              instead.
3443
3444
3445       --show-keyring
3446              Display  the  keyring  name  at the head of key listings to show
3447              which keyring a given key resides on. This option is deprecated:
3448              use --list-options [no-]show-keyring instead.
3449
3450
3451       --always-trust
3452              Identical to --trust-model always. This option is deprecated.
3453
3454
3455       --show-notation
3456       --no-show-notation
3457              Show  signature  notations  in the --list-signatures or --check-
3458              signatures listings as well as when verifying a signature with a
3459              notation in it. These options are deprecated. Use --list-options
3460              [no-]show-notation  and/or  --verify-options  [no-]show-notation
3461              instead.
3462
3463
3464       --show-policy-url
3465       --no-show-policy-url
3466              Show  policy URLs in the --list-signatures or --check-signatures
3467              listings as well as when verifying a signature with a policy URL
3468              in   it.   These  options  are  deprecated.  Use  --list-options
3469              [no-]show-policy-url and/or  --verify-options  [no-]show-policy-
3470              url instead.
3471
3472
3473

EXAMPLES

3475       gpg -se -r Bob file
3476              sign and encrypt for user Bob
3477
3478
3479       gpg --clear-sign file
3480              make a cleartext signature
3481
3482
3483       gpg -sb file
3484              make a detached signature
3485
3486
3487       gpg -u 0x12345678 -sb file
3488              make a detached signature with the key 0x12345678
3489
3490
3491       gpg --list-keys user_ID
3492              show keys
3493
3494
3495       gpg --fingerprint user_ID
3496              show fingerprint
3497
3498
3499       gpg --verify pgpfile
3500       gpg --verify sigfile [datafile]
3501              Verify  the  signature  of  the  file but do not output the data
3502              unless requested.  The second form is used for  detached  signa‐
3503              tures,  where  sigfile  is  the detached signature (either ASCII
3504              armored or binary) and datafile are the signed data; if this  is
3505              not  given, the name of the file holding the signed data is con‐
3506              structed by cutting off the extension (".asc" or ".sig") of sig‐
3507              file  or  by  asking  the  user for the filename.  If the option
3508              --output is also used the signed data is  written  to  the  file
3509              specified by that option; use - to write the signed data to std‐
3510              out.
3511

HOW TO SPECIFY A USER ID

3513       There are different ways to specify a user ID to GnuPG.  Some  of  them
3514       are  only  valid  for  gpg others are only good for gpgsm.  Here is the
3515       entire list of ways to specify a key:
3516
3517
3518
3519       By key Id.
3520              This format is deduced from the length of  the  string  and  its
3521              content or 0x prefix. The key Id of an X.509 certificate are the
3522              low 64 bits of its SHA-1 fingerprint.  The use  of  key  Ids  is
3523              just  a  shortcut,  for all automated processing the fingerprint
3524              should be used.
3525
3526              When using gpg an exclamation mark (!) may be appended to  force
3527              using  the specified primary or secondary key and not to try and
3528              calculate which primary or secondary key to use.
3529
3530              The last four lines of the example give the key ID in their long
3531              form as internally used by the OpenPGP protocol. You can see the
3532              long key ID using the option --with-colons.
3533
3534         234567C4
3535         0F34E556E
3536         01347A56A
3537         0xAB123456
3538
3539         234AABBCC34567C4
3540         0F323456784E56EAB
3541         01AB3FED1347A5612
3542         0x234AABBCC34567C4
3543
3544
3545
3546
3547       By fingerprint.
3548              This format is deduced from the length of  the  string  and  its
3549              content  or  the 0x prefix.  Note, that only the 20 byte version
3550              fingerprint is available with gpgsm (i.e. the SHA-1 hash of  the
3551              certificate).
3552
3553              When  using gpg an exclamation mark (!) may be appended to force
3554              using the specified primary or secondary key and not to try  and
3555              calculate which primary or secondary key to use.
3556
3557              The  best  way  to specify a key Id is by using the fingerprint.
3558              This avoids any ambiguities in case that  there  are  duplicated
3559              key IDs.
3560
3561         1234343434343434C434343434343434
3562         123434343434343C3434343434343734349A3434
3563         0E12343434343434343434EAB3484343434343434
3564         0xE12343434343434343434EAB3484343434343434
3565
3566
3567       gpgsm  also  accepts  colons  between  each  pair of hexadecimal digits
3568       because this is the de-facto standard on how to present  X.509  finger‐
3569       prints.   gpg  also allows the use of the space separated SHA-1 finger‐
3570       print as printed by the key listing commands.
3571
3572
3573       By exact match on OpenPGP user ID.
3574              This is denoted by a leading equal sign. It does not make  sense
3575              for X.509 certificates.
3576
3577         =Heinrich Heine <heinrichh@uni-duesseldorf.de>
3578
3579
3580       By exact match on an email address.
3581              This  is  indicated  by enclosing the email address in the usual
3582              way with left and right angles.
3583
3584         <heinrichh@uni-duesseldorf.de>
3585
3586
3587
3588       By partial match on an email address.
3589              This is indicated by prefixing the  search  string  with  an  @.
3590              This uses a substring search but considers only the mail address
3591              (i.e. inside the angle brackets).
3592
3593         @heinrichh
3594
3595
3596       By exact match on the subject's DN.
3597              This is indicated by a leading slash, directly followed  by  the
3598              RFC-2253 encoded DN of the subject.  Note that you can't use the
3599              string printed by gpgsm --list-keys because that  one  has  been
3600              reordered and modified for better readability; use --with-colons
3601              to print the raw (but standard escaped) RFC-2253 string.
3602
3603         /CN=Heinrich Heine,O=Poets,L=Paris,C=FR
3604
3605
3606       By exact match on the issuer's DN.
3607              This is indicated by a leading hash mark, directly followed by a
3608              slash  and  then directly followed by the RFC-2253 encoded DN of
3609              the issuer.  This should return the Root  cert  of  the  issuer.
3610              See note above.
3611
3612         #/CN=Root Cert,O=Poets,L=Paris,C=FR
3613
3614
3615
3616       By exact match on serial number and issuer's DN.
3617              This  is  indicated  by a hash mark, followed by the hexadecimal
3618              representation of the serial number, then followed  by  a  slash
3619              and the RFC-2253 encoded DN of the issuer. See note above.
3620
3621         #4F03/CN=Root Cert,O=Poets,L=Paris,C=FR
3622
3623
3624       By keygrip.
3625              This  is indicated by an ampersand followed by the 40 hex digits
3626              of a keygrip.  gpgsm prints the keygrip when using  the  command
3627              --dump-cert.
3628
3629         &D75F22C3F86E355877348498CDC92BD21010A480
3630
3631
3632
3633       By substring match.
3634              This is the default mode but applications may want to explicitly
3635              indicate this by putting the asterisk in front.   Match  is  not
3636              case sensitive.
3637
3638         Heine
3639         *Heine
3640
3641
3642       . and + prefixes
3643              These prefixes are reserved for looking up mails anchored at the
3644              end and for a word search mode.  They are  not  yet  implemented
3645              and using them is undefined.
3646
3647
3648              Please  note  that we have reused the hash mark identifier which
3649              was used in old GnuPG versions to indicate the so called  local-
3650              id.  It is not anymore used and there should be no conflict when
3651              used with X.509 stuff.
3652
3653              Using the RFC-2253 format of DNs has the drawback that it is not
3654              possible  to  map them back to the original encoding, however we
3655              don't have to do this  because  our  key  database  stores  this
3656              encoding as meta data.
3657
3658

FILTER EXPRESSIONS

3660       The  options  --import-filter  and --export-filter use expressions with
3661       this syntax (square brackets indicate an optional part and curly braces
3662       a repetition, white space between the elements are allowed):
3663
3664                  [lc] {[{flag}] PROPNAME op VALUE [lc]}
3665
3666       The  name  of a property (PROPNAME) may only consist of letters, digits
3667       and underscores.  The description for the filter type  describes  which
3668       properties  are defined.  If an undefined property is used it evaluates
3669       to the empty string.  Unless otherwise noted, the VALUE must always  be
3670       given  and  may not be the empty string.  No quoting is defined for the
3671       value, thus the value may not contain the strings && or ||,  which  are
3672       used  as  logical  connection  operators.   The  flag -- can be used to
3673       remove this restriction.
3674
3675       Numerical values are computed as long int; standard C notation applies.
3676       lc  is  the logical connection operator; either && for a conjunction or
3677       || for a disjunction.  A conjunction is assumed  at  the  begin  of  an
3678       expression.  Conjunctions have higher precedence than disjunctions.  If
3679       VALUE starts with one of the characters used in any op  a  space  after
3680       the op is required.
3681
3682
3683       The supported operators (op) are:
3684
3685
3686
3687       =~     Substring must match.
3688
3689
3690       !~     Substring must not match.
3691
3692
3693       =      The full string must match.
3694
3695
3696       <>     The full string must not match.
3697
3698
3699       ==     The numerical value must match.
3700
3701
3702       !=     The numerical value must not match.
3703
3704
3705       <=     The numerical value of the field must be LE than the value.
3706
3707
3708       <      The numerical value of the field must be LT than the value.
3709
3710
3711       >      The numerical value of the field must be GT than the value.
3712
3713
3714       >=     The numerical value of the field must be GE than the value.
3715
3716
3717       -le    The  string  value  of  the field must be less or equal than the
3718              value.
3719
3720
3721       -lt    The string value of the field must be less than the value.
3722
3723
3724       -gt    The string value of the field must be greater than the value.
3725
3726
3727       -ge    The string value of the field must be greater or equal than  the
3728              value.
3729
3730
3731       -n     True if value is not empty (no value allowed).
3732
3733
3734       -z     True if value is empty (no value allowed).
3735
3736
3737       -t     Alias for "PROPNAME != 0" (no value allowed).
3738
3739
3740       -f     Alias for "PROPNAME == 0" (no value allowed).
3741
3742
3743       Values for flag must be space separated.  The supported flags are:
3744
3745
3746       --     VALUE spans to the end of the expression.
3747
3748       -c     The string match in this part is done case-sensitive.
3749
3750       The  filter  options concatenate several specifications for a filter of
3751       the same type.  For example the four options in this example:
3752
3753                 --import-filter keep-uid="uid =~ Alfa"
3754                 --import-filter keep-uid="&& uid !~ Test"
3755                 --import-filter keep-uid="|| uid =~ Alpha"
3756                 --import-filter keep-uid="uid !~ Test"
3757
3758
3759       which is equivalent to
3760
3761                 --import-filter \
3762                  keep-uid="uid =~ Alfa" && uid !~ Test" || uid =~ Alpha" && "uid !~ Test"
3763
3764       imports only the user ids of a key containing  the  strings  "Alfa"  or
3765       "Alpha" but not the string "test".
3766
3767

TRUST VALUES

3769       Trust  values  are used to indicate ownertrust and validity of keys and
3770       user IDs.  They are displayed with letters or strings:
3771
3772
3773
3774       -
3775       unknown
3776              No ownertrust assigned / not yet calculated.
3777
3778
3779       e
3780       expired
3781
3782              Trust calculation has failed; probably due to an expired key.
3783
3784
3785       q
3786       undefined, undef
3787              Not enough information for calculation.
3788
3789
3790       n
3791       never  Never trust this key.
3792
3793
3794       m
3795       marginal
3796              Marginally trusted.
3797
3798
3799       f
3800       full   Fully trusted.
3801
3802
3803       u
3804       ultimate
3805              Ultimately trusted.
3806
3807
3808       r
3809       revoked
3810              For validity only: the key or the user ID has been revoked.
3811
3812
3813       ?
3814       err    The program encountered an unknown trust value.
3815
3816

FILES

3818       There are a few configuration files to control certain aspects of gpg's
3819       operation.  Unless  noted, they are expected in the current home direc‐
3820       tory (see: [option --homedir]).
3821
3822
3823
3824       gpg.conf
3825              This is the standard configuration file read by gpg on  startup.
3826              It may contain any valid long option; the leading two dashes may
3827              not be entered and the option  may  not  be  abbreviated.   This
3828              default  name  may  be  changed  on the command line (see: [gpg-
3829              option --options]).  You should backup this file.
3830
3831
3832       Note that on larger installations, it is useful to put predefined files
3833       into the directory ‘/etc/skel/.gnupg’ so that newly created users start
3834       up with a working configuration.  For existing  users  a  small  helper
3835       script is provided to create these files (see: [addgnupghome]).
3836
3837       For internal purposes gpg creates and maintains a few other files; They
3838       all live in the current home directory (see: [option --homedir]).  Only
3839       the gpg program may modify these files.
3840
3841
3842
3843       ~/.gnupg
3844              This  is the default home directory which is used if neither the
3845              environment variable  GNUPGHOME  nor  the  option  --homedir  is
3846              given.
3847
3848
3849       ~/.gnupg/pubring.gpg
3850              The public keyring.  You should backup this file.
3851
3852
3853       ~/.gnupg/pubring.gpg.lock
3854              The lock file for the public keyring.
3855
3856
3857       ~/.gnupg/pubring.kbx
3858              The  public  keyring  using  a  different  format.  This file is
3859              shared with gpgsm.  You should backup this file.
3860
3861
3862       ~/.gnupg/pubring.kbx.lock
3863              The lock file for ‘pubring.kbx’.
3864
3865
3866       ~/.gnupg/secring.gpg
3867              A secret keyring as used by GnuPG versions before  2.1.   It  is
3868              not used by GnuPG 2.1 and later.
3869
3870
3871       ~/.gnupg/secring.gpg.lock
3872              The lock file for the secret keyring.
3873
3874
3875       ~/.gnupg/.gpg-v21-migrated
3876              File indicating that a migration to GnuPG 2.1 has been done.
3877
3878
3879       ~/.gnupg/trustdb.gpg
3880              The trust database.  There is no need to backup this file; it is
3881              better to backup the ownertrust values (see:  [option  --export-
3882              ownertrust]).
3883
3884
3885       ~/.gnupg/trustdb.gpg.lock
3886              The lock file for the trust database.
3887
3888
3889       ~/.gnupg/random_seed
3890              A file used to preserve the state of the internal random pool.
3891
3892
3893       ~/.gnupg/openpgp-revocs.d/
3894              This  is the directory where gpg stores pre-generated revocation
3895              certificates.  The file name corresponds to the OpenPGP  finger‐
3896              print  of  the  respective key.  It is suggested to backup those
3897              certificates and if the primary private key is not stored on the
3898              disk to move them to an external storage device.  Anyone who can
3899              access theses files is able to  revoke  the  corresponding  key.
3900              You  may want to print them out.  You should backup all files in
3901              this directory and take care to keep this backup closed away.
3902
3903
3904       Operation is further controlled by a few environment variables:
3905
3906
3907
3908       HOME   Used to locate the default home directory.
3909
3910
3911       GNUPGHOME
3912              If set directory used instead of "~/.gnupg".
3913
3914
3915       GPG_AGENT_INFO
3916              This variable is obsolete; it was used by GnuPG versions  before
3917              2.1.
3918
3919
3920       PINENTRY_USER_DATA
3921              This value is passed via gpg-agent to pinentry.  It is useful to
3922              convey extra information to a custom pinentry.
3923
3924
3925       COLUMNS
3926       LINES  Used to size some displays to the full size of the screen.
3927
3928
3929       LANGUAGE
3930              Apart from its use by GNU, it is used  in  the  W32  version  to
3931              override  the  language selection done through the Registry.  If
3932              used and set to a valid and available  language  name  (langid),
3933              the    file    with    the    translation    is    loaded   from
3934              gpgdir/gnupg.nls/langid.mo.  Here gpgdir is the directory out of
3935              which the gpg binary has been loaded.  If it can't be loaded the
3936              Registry is tried and as last resort the native  Windows  locale
3937              system is used.
3938
3939
3940       When  calling  the  gpg-agent  component gpg sends a set of environment
3941       variables to gpg-agent.  The names of these  variables  can  be  listed
3942       using the command:
3943
3944           gpg-connect-agent 'getinfo std_env_names' /bye | awk '$1=="D" {print $2}'
3945
3946
3947
3948
3949

BUGS

3951       On older systems this program should be installed as setuid(root). This
3952       is necessary to lock memory pages. Locking memory  pages  prevents  the
3953       operating   system   from  writing  memory  pages  (which  may  contain
3954       passphrases or other sensitive material) to disk. If you get no warning
3955       message  about  insecure  memory your operating system supports locking
3956       without being root. The program drops root privileges as soon as locked
3957       memory is allocated.
3958
3959       Note  also  that  some systems (especially laptops) have the ability to
3960       ``suspend to disk'' (also known as ``safe  sleep''  or  ``hibernate'').
3961       This  writes  all  memory to disk before going into a low power or even
3962       powered off mode.  Unless measures are taken in the operating system to
3963       protect  the  saved memory, passphrases or other sensitive material may
3964       be recoverable from it later.
3965
3966       Before you report a bug you should first search the  mailing  list  ar‐
3967       chives  for  similar  problems  and second check whether such a bug has
3968       already been reported to our bug tracker at https://bugs.gnupg.org.
3969
3970
3971

SEE ALSO

3973       gpgv(1), gpgsm(1), gpg-agent(1)
3974
3975       The full documentation for this tool is maintained as a Texinfo manual.
3976       If  GnuPG and the info program are properly installed at your site, the
3977       command
3978
3979         info gnupg
3980
3981       should give you access to the complete manual including a  menu  struc‐
3982       ture and an index.
3983
3984
3985
3986GnuPG 2.2.18                      2019-11-23                            GPG(1)
Impressum