1GPG2(1) GNU Privacy Guard GPG2(1)
2
6 gpg2 - OpenPGP encryption and signing tool
7
9 gpg2 [--homedir dir] [--options file] [options] command [args]
10
13 gpg2 is the OpenPGP part of the GNU Privacy Guard (GnuPG). It is a tool
14 to provide digital encryption and signing services using the OpenPGP
15 standard. gpg2 features complete key management and all bells and whis‐
16 tles you can expect from a decent OpenPGP implementation.
17 In contrast to the standalone version gpg, which is more suited for
20 server and embedded platforms, this version is commonly installed under
21 the name gpg2 and more targeted to the desktop as it requires several
22 other modules to be installed. The standalone version will be kept
23 maintained and it is possible to install both versions on the same sys‐
24 tem. If you need to use different configuration files, you should make
25 use of something like ‘gpg.conf-2’ instead of just ‘gpg.conf’.
26
34 The program returns 0 if everything was fine, 1 if at least a signature
35 was bad, and other error codes for fatal errors.
36
39 Use a *good* password for your user account and a *good* passphrase to
40 protect your secret key. This passphrase is the weakest part of the
41 whole system. Programs to do dictionary attacks on your secret keyring
42 are very easy to write and so you should protect your "~/.gnupg/"
43 directory very well.
44 Keep in mind that, if this program is used over a network (telnet), it
46 is *very* easy to spy out your passphrase!
47 If you are going to verify detached signatures, make sure that the pro‐
49 gram knows about it; either give both filenames on the command line or
50 use '-' to specify STDIN.
51
54 GnuPG tries to be a very flexible implementation of the OpenPGP stan‐
55 dard. In particular, GnuPG implements many of the optional parts of the
56 standard, such as the SHA-512 hash, and the ZLIB and BZIP2 compression
57 algorithms. It is important to be aware that not all OpenPGP programs
58 implement these optional algorithms and that by forcing their use via
59 the --cipher-algo, --digest-algo, --cert-digest-algo, or --compress-
60 algo options in GnuPG, it is possible to create a perfectly valid
61 OpenPGP message, but one that cannot be read by the intended recipient.
62 There are dozens of variations of OpenPGP programs available, and each
64 supports a slightly different subset of these optional algorithms. For
65 example, until recently, no (unhacked) version of PGP supported the
66 BLOWFISH cipher algorithm. A message using BLOWFISH simply could not be
67 read by a PGP user. By default, GnuPG uses the standard OpenPGP prefer‐
68 ences system that will always do the right thing and create messages
69 that are usable by all recipients, regardless of which OpenPGP program
70 they use. Only override this safe default if you really know what you
71 are doing.
72 If you absolutely must override the safe default, or if the preferences
74 on a given key are invalid for some reason, you are far better off
75 using the --pgp6, --pgp7, or --pgp8 options. These options are safe as
76 they do not force any particular algorithms in violation of OpenPGP,
77 but rather reduce the available algorithms to a "PGP-safe" list.
78
81 Commands are not distinguished from options except for the fact that
82 only one command is allowed.
83 gpg2 may be run with no commands, in which case it will perform a rea‐
85 sonable action depending on the type of file it is given as input (an
86 encrypted message is decrypted, a signature is verified, a file con‐
87 taining keys is listed).
88 Please remember that option as well as command parsing stops as soon as
90 a non-option is encountered, you can explicitly stop parsing by using
91 the special option --.
92 Commands not specific to the function
99 --version
103 Print the program version and licensing information. Note that
104 you cannot abbreviate this command.
105 --help
108 -h Print a usage message summarizing the most useful command line
110 options. Note that you cannot abbreviate this command.
111 --warranty
114 Print warranty information.
115 --dump-options
118 Print a list of all available options and commands. Note that
119 you cannot abbreviate this command.
120 Commands to select the type of operation
125 --sign
131 -s Make a signature. This command may be combined with --encrypt
133 (for a signed and encrypted message), --symmetric (for a signed
134 and symmetrically encrypted message), or --encrypt and --symmet‐
135 ric together (for a signed message that may be decrypted via a
136 secret key or a passphrase). The key to be used for signing is
137 chosen by default or can be set with the --local-user and
138 --default-key options.
139 --clearsign
142 Make a clear text signature. The content in a clear text signa‐
143 ture is readable without any special software. OpenPGP software
144 is only needed to verify the signature. Clear text signatures
145 may modify end-of-line whitespace for platform independence and
146 are not intended to be reversible. The key to be used for sign‐
147 ing is chosen by default or can be set with the --local-user and
148 --default-key options.
149 --detach-sign
153 -b Make a detached signature.
155 --encrypt
158 -e Encrypt data. This option may be combined with --sign (for a
160 signed and encrypted message), --symmetric (for a message that
161 may be decrypted via a secret key or a passphrase), or --sign
162 and --symmetric together (for a signed message that may be
163 decrypted via a secret key or a passphrase).
164 --symmetric
167 -c Encrypt with a symmetric cipher using a passphrase. The default
169 symmetric cipher used is CAST5, but may be chosen with the
170 --cipher-algo option. This option may be combined with --sign
171 (for a signed and symmetrically encrypted message), --encrypt
172 (for a message that may be decrypted via a secret key or a
173 passphrase), or --sign and --encrypt together (for a signed mes‐
174 sage that may be decrypted via a secret key or a passphrase).
175 --store
178 Store only (make a simple RFC1991 literal data packet).
179 --decrypt
182 -d Decrypt the file given on the command line (or STDIN if no file
184 is specified) and write it to STDOUT (or the file specified with
185 --output). If the decrypted file is signed, the signature is
186 also verified. This command differs from the default operation,
187 as it never writes to the filename which is included in the file
188 and it rejects files which don't begin with an encrypted mes‐
189 sage.
190 --verify
193 Assume that the first argument is a signed file or a detached
194 signature and verify it without generating any output. With no
195 arguments, the signature packet is read from STDIN. If only a
196 sigfile is given, it may be a complete signature or a detached
197 signature, in which case the signed stuff is expected in a file
198 without the ".sig" or ".asc" extension. With more than 1 argu‐
199 ment, the first should be a detached signature and the remaining
200 files are the signed stuff. To read the signed stuff from STDIN,
201 use '-' as the second filename. For security reasons a detached
202 signature cannot read the signed material from STDIN without
203 denoting it in the above way.
204 --multifile
207 This modifies certain other commands to accept multiple files
208 for processing on the command line or read from STDIN with each
209 filename on a separate line. This allows for many files to be
210 processed at once. --multifile may currently be used along with
211 --verify, --encrypt, and --decrypt. Note that --multifile --ver‐
212 ify may not be used with detached signatures.
213 --verify-files
216 Identical to --multifile --verify.
217 --encrypt-files
220 Identical to --multifile --encrypt.
221 --decrypt-files
224 Identical to --multifile --decrypt.
225 --list-keys
228 -k
230 --list-public-keys
232 List all keys from the public keyrings, or just the keys given
233 on the command line.
234 Avoid using the output of this command in scripts or other pro‐
236 grams as it is likely to change as GnuPG changes. See --with-
237 colons for a machine-parseable key listing command that is
238 appropriate for use in scripts and other programs.
239 --list-secret-keys
242 -K List all keys from the secret keyrings, or just the ones given
244 on the command line. A # after the letters sec means that the
245 secret key is not usable (for example, if it was created via
246 --export-secret-subkeys).
247 --list-sigs
250 Same as --list-keys, but the signatures are listed too. This
251 command has the same effect as using --list-keys with --with-
252 sig-list.
253 For each signature listed, there are several flags in between
255 the "sig" tag and keyid. These flags give additional information
256 about each signature. From left to right, they are the numbers
257 1-3 for certificate check level (see --ask-cert-level), "L" for
258 a local or non-exportable signature (see --lsign-key), "R" for a
259 nonRevocable signature (see the --edit-key command "nrsign"),
260 "P" for a signature that contains a policy URL (see --cert-pol‐
261 icy-url), "N" for a signature that contains a notation (see
262 --cert-notation), "X" for an eXpired signature (see --ask-cert-
263 expire), and the numbers 1-9 or "T" for 10 and above to indicate
264 trust signature levels (see the --edit-key command "tsign").
265 --check-sigs
268 Same as --list-sigs, but the signatures are verified. Note that
269 for performance reasons the revocation status of a signing key
270 is not shown. This command has the same effect as using --list-
271 keys with --with-sig-check.
272 The status of the verification is indicated by a flag directly
274 following the "sig" tag (and thus before the flags described
275 above for --list-sigs). A "!" indicates that the signature has
276 been successfully verified, a "-" denotes a bad signature and a
277 "%" is used if an error occurred while checking the signature
278 (e.g. a non supported algorithm).
279 --locate-keys
282 Locate the keys given as arguments. This command basically uses
283 the same algorithm as used when locating keys for encryption or
284 signing and may thus be used to see what keys gpg2 might use.
285 In particular external methods as defined by --auto-key-locate
286 may be used to locate a key. Only public keys are listed.
287 --fingerprint
291 List all keys (or the specified ones) along with their finger‐
292 prints. This is the same output as --list-keys but with the
293 additional output of a line with the fingerprint. May also be
294 combined with --list-sigs or --check-sigs. If this command is
295 given twice, the fingerprints of all secondary keys are listed
296 too.
297 --list-packets
300 List only the sequence of packets. This is mainly useful for
301 debugging.
302 --card-edit
306 Present a menu to work with a smartcard. The subcommand "help"
307 provides an overview on available commands. For a detailed
308 description, please see the Card HOWTO at
309 http://www.gnupg.org/documentation/howtos.html#GnuPG-cardHOWTO .
310 --card-status
313 Show the content of the smart card.
314 --change-pin
317 Present a menu to allow changing the PIN of a smartcard. This
318 functionality is also available as the subcommand "passwd" with
319 the --card-edit command.
320 --delete-key name
323 Remove key from the public keyring. In batch mode either --yes
324 is required or the key must be specified by fingerprint. This is
325 a safeguard against accidental deletion of multiple keys.
326 --delete-secret-key name
329 Remove key from the secret and public keyring. In batch mode the
330 key must be specified by fingerprint.
331 --delete-secret-and-public-key name
334 Same as --delete-key, but if a secret key exists, it will be
335 removed first. In batch mode the key must be specified by fin‐
336 gerprint.
337 --export
340 Either export all keys from all keyrings (default keyrings and
341 those registered via option --keyring), or if at least one name
342 is given, those of the given name. The new keyring is written to
343 STDOUT or to the file given with option --output. Use together
344 with --armor to mail those keys.
345 --send-keys key IDs
348 Similar to --export but sends the keys to a keyserver. Finger‐
349 prints may be used instead of key IDs. Option --keyserver must
350 be used to give the name of this keyserver. Don't send your com‐
351 plete keyring to a keyserver --- select only those keys which
352 are new or changed by you. If no key IDs are given, gpg does
353 nothing.
354 --export-secret-keys
357 --export-secret-subkeys
359 Same as --export, but exports the secret keys instead. This is
360 normally not very useful and a security risk. The second form
361 of the command has the special property to render the secret
362 part of the primary key useless; this is a GNU extension to
363 OpenPGP and other implementations can not be expected to suc‐
364 cessfully import such a key. See the option --simple-sk-check‐
365 sum if you want to import such an exported key with an older
366 OpenPGP implementation.
367 --import
370 --fast-import
372 Import/merge keys. This adds the given keys to the keyring. The
373 fast version is currently just a synonym.
374 There are a few other options which control how this command
376 works. Most notable here is the --import-options merge-only
377 option which does not insert new keys but does only the merging
378 of new signatures, user-IDs and subkeys.
379 --recv-keys key IDs
382 Import the keys with the given key IDs from a keyserver. Option
383 --keyserver must be used to give the name of this keyserver.
384 --refresh-keys
387 Request updates from a keyserver for keys that already exist on
388 the local keyring. This is useful for updating a key with the
389 latest signatures, user IDs, etc. Calling this with no arguments
390 will refresh the entire keyring. Option --keyserver must be used
391 to give the name of the keyserver for all keys that do not have
392 preferred keyservers set (see --keyserver-options honor-key‐
393 server-url).
394 --search-keys names
397 Search the keyserver for the given names. Multiple names given
398 here will be joined together to create the search string for the
399 keyserver. Option --keyserver must be used to give the name of
400 this keyserver. Keyservers that support different search meth‐
401 ods allow using the syntax specified in "How to specify a user
402 ID" below. Note that different keyserver types support different
403 search methods. Currently only LDAP supports them all.
404 --fetch-keys URIs
407 Retrieve keys located at the specified URIs. Note that different
408 installations of GnuPG may support different protocols (HTTP,
409 FTP, LDAP, etc.)
410 --update-trustdb
413 Do trust database maintenance. This command iterates over all
414 keys and builds the Web of Trust. This is an interactive command
415 because it may have to ask for the "ownertrust" values for keys.
416 The user has to give an estimation of how far she trusts the
417 owner of the displayed key to correctly certify (sign) other
418 keys. GnuPG only asks for the ownertrust value if it has not yet
419 been assigned to a key. Using the --edit-key menu, the assigned
420 value can be changed at any time.
421 --check-trustdb
424 Do trust database maintenance without user interaction. From
425 time to time the trust database must be updated so that expired
426 keys or signatures and the resulting changes in the Web of Trust
427 can be tracked. Normally, GnuPG will calculate when this is
428 required and do it automatically unless --no-auto-check-trustdb
429 is set. This command can be used to force a trust database check
430 at any time. The processing is identical to that of --update-
431 trustdb but it skips keys with a not yet defined "ownertrust".
432 For use with cron jobs, this command can be used together with
434 --batch in which case the trust database check is done only if a
435 check is needed. To force a run even in batch mode add the
436 option --yes.
437 --export-ownertrust
441 Send the ownertrust values to STDOUT. This is useful for backup
442 purposes as these values are the only ones which can't be re-
443 created from a corrupted trustdb. Example:
444 gpg2 --export-ownertrust > otrust.txt
445 --import-ownertrust
449 Update the trustdb with the ownertrust values stored in files
450 (or STDIN if not given); existing values will be overwritten.
451 In case of a severely damaged trustdb and if you have a recent
452 backup of the ownertrust values (e.g. in the file ‘otrust.txt’,
453 you may re-create the trustdb using these commands:
454 cd ~/.gnupg
455 rm trustdb.gpg
456 gpg2 --import-ownertrust < otrust.txt
457 --rebuild-keydb-caches
461 When updating from version 1.0.6 to 1.0.7 this command should be
462 used to create signature caches in the keyring. It might be
463 handy in other situations too.
464 --print-md algo
467 --print-mds
469 Print message digest of algorithm ALGO for all given files or
470 STDIN. With the second form (or a deprecated "*" as algo)
471 digests for all available algorithms are printed.
472 --gen-random 0|1|2 count
475 Emit count random bytes of the given quality level 0, 1 or 2. If
476 count is not given or zero, an endless sequence of random bytes
477 will be emitted. If used with --armor the output will be base64
478 encoded. PLEASE, don't use this command unless you know what
479 you are doing; it may remove precious entropy from the system!
480 --gen-prime mode bits
483 Use the source, Luke :-). The output format is still subject to
484 change.
485 --enarmor
489 --dearmor
491 Pack or unpack an arbitrary input into/from an OpenPGP ASCII
492 armor. This is a GnuPG extension to OpenPGP and in general not
493 very useful.
494 How to manage your keys
500 This section explains the main commands for key management
503 --gen-key
507 Generate a new key pair. This command is normally only used
508 interactively.
509 There is an experimental feature which allows you to create keys
511 in batch mode. See the file ‘doc/DETAILS’ in the source distri‐
512 bution on how to use this.
513 --gen-revoke name
516 Generate a revocation certificate for the complete key. To
517 revoke a subkey or a signature, use the --edit command.
518 --desig-revoke name
521 Generate a designated revocation certificate for a key. This
522 allows a user (with the permission of the keyholder) to revoke
523 someone else's key.
524 --edit-key
528 Present a menu which enables you to do most of the key manage‐
529 ment related tasks. It expects the specification of a key on
530 the command line.
531 uid n Toggle selection of user ID or photographic user ID with
535 index n. Use * to select all and 0 to deselect all.
536 key n Toggle selection of subkey with index n. Use * to select
539 all and 0 to deselect all.
540 sign Make a signature on key of user name If the key is not
543 yet signed by the default user (or the users given with
544 -u), the program displays the information of the key
545 again, together with its fingerprint and asks whether it
546 should be signed. This question is repeated for all users
547 specified with -u.
548 lsign Same as "sign" but the signature is marked as non-
551 exportable and will therefore never be used by others.
552 This may be used to make keys valid only in the local
553 environment.
554 nrsign Same as "sign" but the signature is marked as non-revoca‐
557 ble and can therefore never be revoked.
558 tsign Make a trust signature. This is a signature that combines
561 the notions of certification (like a regular signature),
562 and trust (like the "trust" command). It is generally
563 only useful in distinct communities or groups.
564 Note that "l" (for local / non-exportable), "nr" (for non-revo‐
566 cable, and "t" (for trust) may be freely mixed and prefixed to
567 "sign" to create a signature of any type desired.
568 delsig Delete a signature. Note that it is not possible to
572 retract a signature, once it has been send to the public
573 (i.e. to a keyserver). In that case you better use
574 revsig.
575 revsig Revoke a signature. For every signature which has been
578 generated by one of the secret keys, GnuPG asks whether a
579 revocation certificate should be generated.
580 check Check the signatures on all selected user IDs.
583 adduid Create an additional user ID.
586 addphoto
589 Create a photographic user ID. This will prompt for a
590 JPEG file that will be embedded into the user ID. Note
591 that a very large JPEG will make for a very large key.
592 Also note that some programs will display your JPEG
593 unchanged (GnuPG), and some programs will scale it to fit
594 in a dialog box (PGP).
595 showphoto
598 Display the selected photographic user ID.
599 deluid Delete a user ID or photographic user ID. Note that it
602 is not possible to retract a user id, once it has been
603 send to the public (i.e. to a keyserver). In that case
604 you better use revuid.
605 revuid Revoke a user ID or photographic user ID.
608 primary
611 Flag the current user id as the primary one, removes the
612 primary user id flag from all other user ids and sets the
613 timestamp of all affected self-signatures one second
614 ahead. Note that setting a photo user ID as primary makes
615 it primary over other photo user IDs, and setting a regu‐
616 lar user ID as primary makes it primary over other regu‐
617 lar user IDs.
618 keyserver
621 Set a preferred keyserver for the specified user ID(s).
622 This allows other users to know where you prefer they get
623 your key from. See --keyserver-options honor-keyserver-
624 url for more on how this works. Setting a value of
625 "none" removes an existing preferred keyserver.
626 notation
629 Set a name=value notation for the specified user ID(s).
630 See --cert-notation for more on how this works. Setting a
631 value of "none" removes all notations, setting a notation
632 prefixed with a minus sign (-) removes that notation, and
633 setting a notation name (without the =value) prefixed
634 with a minus sign removes all notations with that name.
635 pref List preferences from the selected user ID. This shows
638 the actual preferences, without including any implied
639 preferences.
640 showpref
643 More verbose preferences listing for the selected user
644 ID. This shows the preferences in effect by including the
645 implied preferences of 3DES (cipher), SHA-1 (digest), and
646 Uncompressed (compression) if they are not already
647 included in the preference list. In addition, the pre‐
648 ferred keyserver and signature notations (if any) are
649 shown.
650 setpref string
653 Set the list of user ID preferences to string for all (or
654 just the selected) user IDs. Calling setpref with no
655 arguments sets the preference list to the default (either
656 built-in or set via --default-preference-list), and call‐
657 ing setpref with "none" as the argument sets an empty
658 preference list. Use gpg2 --version to get a list of
659 available algorithms. Note that while you can change the
660 preferences on an attribute user ID (aka "photo ID"),
661 GnuPG does not select keys via attribute user IDs so
662 these preferences will not be used by GnuPG.
663 When setting preferences, you should list the algorithms
665 in the order which you'd like to see them used by someone
666 else when encrypting a message to your key. If you don't
667 include 3DES, it will be automatically added at the end.
668 Note that there are many factors that go into choosing an
669 algorithm (for example, your key may not be the only
670 recipient), and so the remote OpenPGP application being
671 used to send to you may or may not follow your exact cho‐
672 sen order for a given message. It will, however, only
673 choose an algorithm that is present on the preference
674 list of every recipient key. See also the INTEROPERABIL‐
675 ITY WITH OTHER OPENPGP PROGRAMS section below.
676 addkey Add a subkey to this key.
679 addcardkey
682 Generate a subkey on a card and add it to this key.
683 keytocard
686 Transfer the selected secret subkey (or the primary key
687 if no subkey has been selected) to a smartcard. The
688 secret key in the keyring will be replaced by a stub if
689 the key could be stored successfully on the card and you
690 use the save command later. Only certain key types may be
691 transferred to the card. A sub menu allows you to select
692 on what card to store the key. Note that it is not possi‐
693 ble to get that key back from the card - if the card gets
694 broken your secret key will be lost unless you have a
695 backup somewhere.
696 bkuptocard file
699 Restore the given file to a card. This command may be
700 used to restore a backup key (as generated during card
701 initialization) to a new card. In almost all cases this
702 will be the encryption key. You should use this command
703 only with the corresponding public key and make sure that
704 the file given as argument is indeed the backup to
705 restore. You should then select 2 to restore as encryp‐
706 tion key. You will first be asked to enter the
707 passphrase of the backup key and then for the Admin PIN
708 of the card.
709 delkey Remove a subkey (secondart key). Note that it is not pos‐
712 sible to retract a subkey, once it has been send to the
713 public (i.e. to a keyserver). In that case you better
714 use revkey.
715 revkey Revoke a subkey.
718 expire Change the key or subkey expiration time. If a subkey is
721 selected, the expiration time of this subkey will be
722 changed. With no selection, the key expiration of the
723 primary key is changed.
724 trust Change the owner trust value for the key. This updates
727 the trust-db immediately and no save is required.
728 disable
731 enable Disable or enable an entire key. A disabled key can not
733 normally be used for encryption.
734 addrevoker
737 Add a designated revoker to the key. This takes one
738 optional argument: "sensitive". If a designated revoker
739 is marked as sensitive, it will not be exported by
740 default (see export-options).
741 passwd Change the passphrase of the secret key.
744 toggle Toggle between public and secret key listing.
747 clean Compact (by removing all signatures except the selfsig)
750 any user ID that is no longer usable (e.g. revoked, or
751 expired). Then, remove any signatures that are not usable
752 by the trust calculations. Specifically, this removes
753 any signature that does not validate, any signature that
754 is superseded by a later signature, revoked signatures,
755 and signatures issued by keys that are not present on the
756 keyring.
757 minimize
760 Make the key as small as possible. This removes all sig‐
761 natures from each user ID except for the most recent
762 self-signature.
763 cross-certify
766 Add cross-certification signatures to signing subkeys
767 that may not currently have them. Cross-certification
768 signatures protect against a subtle attack against sign‐
769 ing subkeys. See --require-cross-certification. All new
770 keys generated have this signature by default, so this
771 option is only useful to bring older keys up to date.
772 save Save all changes to the key rings and quit.
775 quit Quit the program without updating the key rings.
778 The listing shows you the key with its secondary keys and all
781 user ids. The primary user id is indicated by a dot, and
782 selected keys or user ids are indicated by an asterisk. The
783 trust value is displayed with the primary key: the first is the
784 assigned owner trust and the second is the calculated trust
785 value. Letters are used for the values:
786 - No ownertrust assigned / not yet calculated.
790 e Trust calculation has failed; probably due to an expired
793 key.
794 q Not enough information for calculation.
797 n Never trust this key.
800 m Marginally trusted.
803 f Fully trusted.
806 u Ultimately trusted.
809 --sign-key name
812 Signs a public key with your secret key. This is a shortcut ver‐
813 sion of the subcommand "sign" from --edit.
814 --lsign-key name
817 Signs a public key with your secret key but marks it as non-
818 exportable. This is a shortcut version of the subcommand "lsign"
819 from --edit-key.
820 --passwd user_id
823 Change the passphrase of the secret key belonging to the cer‐
824 tificate specified as user_id. This is a shortcut for the sub-
825 command passwd of the edit key menu.
826
832 gpg2 features a bunch of options to control the exact behaviour and to
833 change the default configuration.
834 Long options can be put in an options file (default
837 "~/.gnupg/gpg.conf"). Short option names will not work - for example,
838 "armor" is a valid option for the options file, while "a" is not. Do
839 not write the 2 dashes, but simply the name of the option and any
840 required arguments. Lines with a hash ('#') as the first non-white-
841 space character are ignored. Commands may be put in this file too, but
842 that is not generally useful as the command will execute automatically
843 with every execution of gpg.
844 Please remember that option parsing stops as soon as a non-option is
846 encountered, you can explicitly stop parsing by using the special
847 option --.
848 How to change the configuration
852 These options are used to change the configuration and are usually
855 found in the option file.
856 --default-key name
860 Use name as the default key to sign with. If this option is not
861 used, the default key is the first key found in the secret
862 keyring. Note that -u or --local-user overrides this option.
863 --default-recipient name
866 Use name as default recipient if option --recipient is not used
867 and don't ask if this is a valid one. name must be non-empty.
868 --default-recipient-self
871 Use the default key as default recipient if option --recipient
872 is not used and don't ask if this is a valid one. The default
873 key is the first one from the secret keyring or the one set with
874 --default-key.
875 --no-default-recipient
878 Reset --default-recipient and --default-recipient-self.
879 -v, --verbose
882 Give more information during processing. If used twice, the
883 input data is listed in detail.
884 --no-verbose
887 Reset verbose level to 0.
888 -q, --quiet
891 Try to be as quiet as possible.
892 --batch
895 --no-batch
897 Use batch mode. Never ask, do not allow interactive commands.
898 --no-batch disables this option. Note that even with a filename
899 given on the command line, gpg might still need to read from
900 STDIN (in particular if gpg figures that the input is a detached
901 signature and no data file has been specified). Thus if you do
902 not want to feed data via STDIN, you should connect STDIN to
903 ‘/dev/null’.
904 --no-tty
907 Make sure that the TTY (terminal) is never used for any output.
908 This option is needed in some cases because GnuPG sometimes
909 prints warnings to the TTY even if --batch is used.
910 --yes Assume "yes" on most questions.
913 --no Assume "no" on most questions.
916 --list-options parameters
920 This is a space or comma delimited string that gives options
921 used when listing keys and signatures (that is, --list-keys,
922 --list-sigs, --list-public-keys, --list-secret-keys, and the
923 --edit-key functions). Options can be prepended with a no-
924 (after the two dashes) to give the opposite meaning. The
925 options are:
926 show-photos
930 Causes --list-keys, --list-sigs, --list-public-keys, and
931 --list-secret-keys to display any photo IDs attached to
932 the key. Defaults to no. See also --photo-viewer. Does
933 not work with --with-colons: see --attribute-fd for the
934 appropriate way to get photo data for scripts and other
935 frontends.
936 show-policy-urls
939 Show policy URLs in the --list-sigs or --check-sigs list‐
940 ings. Defaults to no.
941 show-notations
944 show-std-notations
946 show-user-notations
948 Show all, IETF standard, or user-defined signature nota‐
949 tions in the --list-sigs or --check-sigs listings.
950 Defaults to no.
951 show-keyserver-urls
954 Show any preferred keyserver URL in the --list-sigs or
956 --check-sigs listings. Defaults to no.
957 show-uid-validity
960 Display the calculated validity of user IDs during key
961 listings. Defaults to no.
962 show-unusable-uids
965 Show revoked and expired user IDs in key listings.
966 Defaults to no.
967 show-unusable-subkeys
970 Show revoked and expired subkeys in key listings.
971 Defaults to no.
972 show-keyring
975 Display the keyring name at the head of key listings to
976 show which keyring a given key resides on. Defaults to
977 no.
978 show-sig-expire
981 Show signature expiration dates (if any) during --list-
982 sigs or --check-sigs listings. Defaults to no.
983 show-sig-subpackets
986 Include signature subpackets in the key listing. This
987 option can take an optional argument list of the subpack‐
988 ets to list. If no argument is passed, list all subpack‐
989 ets. Defaults to no. This option is only meaningful when
990 using --with-colons along with --list-sigs or --check-
991 sigs.
992 --verify-options parameters
995 This is a space or comma delimited string that gives options
996 used when verifying signatures. Options can be prepended with a
997 `no-' to give the opposite meaning. The options are:
998 show-photos
1002 Display any photo IDs present on the key that issued the
1003 signature. Defaults to no. See also --photo-viewer.
1004 show-policy-urls
1007 Show policy URLs in the signature being verified.
1008 Defaults to no.
1009 show-notations
1012 show-std-notations
1014 show-user-notations
1016 Show all, IETF standard, or user-defined signature nota‐
1017 tions in the signature being verified. Defaults to IETF
1018 standard.
1019 show-keyserver-urls
1022 Show any preferred keyserver URL in the signature being
1023 verified. Defaults to no.
1024 show-uid-validity
1027 Display the calculated validity of the user IDs on the
1028 key that issued the signature. Defaults to no.
1029 show-unusable-uids
1032 Show revoked and expired user IDs during signature veri‐
1033 fication. Defaults to no.
1034 show-primary-uid-only
1037 Show only the primary user ID during signature verifica‐
1038 tion. That is all the AKA lines as well as photo Ids are
1039 not shown with the signature verification status.
1040 pka-lookups
1043 Enable PKA lookups to verify sender addresses. Note that
1044 PKA is based on DNS, and so enabling this option may dis‐
1045 close information on when and what signatures are veri‐
1046 fied or to whom data is encrypted. This is similar to the
1047 "web bug" described for the auto-key-retrieve feature.
1048 pka-trust-increase
1051 Raise the trust in a signature to full if the signature
1052 passes PKA validation. This option is only meaningful if
1053 pka-lookups is set.
1054 --enable-dsa2
1057 --disable-dsa2
1059 Enable hash truncation for all DSA keys even for old DSA Keys up
1060 to 1024 bit. This is also the default with --openpgp. Note
1061 that older versions of GnuPG also required this flag to allow
1062 the generation of DSA larger than 1024 bit.
1063 --photo-viewer string
1066 This is the command line that should be run to view a photo ID.
1067 "%i" will be expanded to a filename containing the photo. "%I"
1068 does the same, except the file will not be deleted once the
1069 viewer exits. Other flags are "%k" for the key ID, "%K" for the
1070 long key ID, "%f" for the key fingerprint, "%t" for the exten‐
1071 sion of the image type (e.g. "jpg"), "%T" for the MIME type of
1072 the image (e.g. "image/jpeg"), "%v" for the single-character
1073 calculated validity of the image being viewed (e.g. "f"), "%V"
1074 for the calculated validity as a string (e.g. "full"), and "%%"
1075 for an actual percent sign. If neither %i or %I are present,
1076 then the photo will be supplied to the viewer on standard input.
1077 The default viewer is "xloadimage -fork -quiet -title 'KeyID
1079 0x%k' STDIN". Note that if your image viewer program is not
1080 secure, then executing it from GnuPG does not make it secure.
1081 --exec-path string
1084 Sets a list of directories to search for photo viewers and key‐
1085 server helpers. If not provided, keyserver helpers use the com‐
1086 piled-in default directory, and photo viewers use the $PATH
1087 environment variable. Note, that on W32 system this value is
1088 ignored when searching for keyserver helpers.
1089 --keyring file
1092 Add file to the current list of keyrings. If file begins with a
1093 tilde and a slash, these are replaced by the $HOME directory. If
1094 the filename does not contain a slash, it is assumed to be in
1095 the GnuPG home directory ("~/.gnupg" if --homedir or $GNUPGHOME
1096 is not used).
1097 Note that this adds a keyring to the current list. If the intent
1099 is to use the specified keyring alone, use --keyring along with
1100 --no-default-keyring.
1101 --secret-keyring file
1104 Same as --keyring but for the secret keyrings.
1105 --primary-keyring file
1108 Designate file as the primary public keyring. This means that
1109 newly imported keys (via --import or keyserver --recv-from) will
1110 go to this keyring.
1111 --trustdb-name file
1114 Use file instead of the default trustdb. If file begins with a
1115 tilde and a slash, these are replaced by the $HOME directory. If
1116 the filename does not contain a slash, it is assumed to be in
1117 the GnuPG home directory (‘~/.gnupg’ if --homedir or $GNUPGHOME
1118 is not used).
1119 --homedir dir
1122 Set the name of the home directory to dir. If this option is not
1123 used, the home directory defaults to ‘~/.gnupg’. It is only
1124 recognized when given on the command line. It also overrides
1125 any home directory stated through the environment variable
1126 ‘GNUPGHOME’ or (on W32 systems) by means of the Registry entry
1127 HKCU\Software\GNU\GnuPG:HomeDir.
1128 --display-charset name
1136 Set the name of the native character set. This is used to con‐
1137 vert some informational strings like user IDs to the proper
1138 UTF-8 encoding. Note that this has nothing to do with the char‐
1139 acter set of data to be encrypted or signed; GnuPG does not
1140 recode user-supplied data. If this option is not used, the
1141 default character set is determined from the current locale. A
1142 verbosity level of 3 shows the chosen set. Valid values for
1143 name are:
1144 iso-8859-1
1148 This is the Latin 1 set.
1149 iso-8859-2
1152 The Latin 2 set.
1153 iso-8859-15
1156 This is currently an alias for the Latin 1 set.
1157 koi8-r The usual Russian set (rfc1489).
1160 utf-8 Bypass all translations and assume that the OS uses
1163 native UTF-8 encoding.
1164 --utf8-strings
1167 --no-utf8-strings
1169 Assume that command line arguments are given as UTF8 strings.
1170 The default (--no-utf8-strings) is to assume that arguments are
1171 encoded in the character set as specified by --display-charset.
1172 These options affect all following arguments. Both options may
1173 be used multiple times.
1174 --options file
1177 Read options from file and do not try to read them from the
1178 default options file in the homedir (see --homedir). This option
1179 is ignored if used in an options file.
1180 --no-options
1183 Shortcut for --options /dev/null. This option is detected before
1184 an attempt to open an option file. Using this option will also
1185 prevent the creation of a ‘~/.gnupg’ homedir.
1186 -z n
1191 --compress-level n
1193 --bzip2-compress-level n
1195 Set compression level to n for the ZIP and ZLIB compression
1196 algorithms. The default is to use the default compression level
1197 of zlib (normally 6). --bzip2-compress-level sets the compres‐
1198 sion level for the BZIP2 compression algorithm (defaulting to 6
1199 as well). This is a different option from --compress-level since
1200 BZIP2 uses a significant amount of memory for each additional
1201 compression level. -z sets both. A value of 0 for n disables
1202 compression.
1203 --bzip2-decompress-lowmem
1206 Use a different decompression method for BZIP2 compressed files.
1207 This alternate method uses a bit more than half the memory, but
1208 also runs at half the speed. This is useful under extreme low
1209 memory circumstances when the file was originally compressed at
1210 a high --bzip2-compress-level.
1211 --mangle-dos-filenames
1215 --no-mangle-dos-filenames
1217 Older version of Windows cannot handle filenames with more than
1218 one dot. --mangle-dos-filenames causes GnuPG to replace (rather
1219 than add to) the extension of an output filename to avoid this
1220 problem. This option is off by default and has no effect on non-
1221 Windows platforms.
1222 --ask-cert-level
1225 --no-ask-cert-level
1227 When making a key signature, prompt for a certification level.
1228 If this option is not specified, the certification level used is
1229 set via --default-cert-level. See --default-cert-level for
1230 information on the specific levels and how they are used. --no-
1231 ask-cert-level disables this option. This option defaults to no.
1232 --default-cert-level n
1235 The default to use for the check level when signing a key.
1236 0 means you make no particular claim as to how carefully you
1238 verified the key.
1239 1 means you believe the key is owned by the person who claims to
1241 own it but you could not, or did not verify the key at all. This
1242 is useful for a "persona" verification, where you sign the key
1243 of a pseudonymous user.
1244 2 means you did casual verification of the key. For example,
1246 this could mean that you verified that the key fingerprint and
1247 checked the user ID on the key against a photo ID.
1248 3 means you did extensive verification of the key. For example,
1250 this could mean that you verified the key fingerprint with the
1251 owner of the key in person, and that you checked, by means of a
1252 hard to forge document with a photo ID (such as a passport) that
1253 the name of the key owner matches the name in the user ID on the
1254 key, and finally that you verified (by exchange of email) that
1255 the email address on the key belongs to the key owner.
1256 Note that the examples given above for levels 2 and 3 are just
1258 that: examples. In the end, it is up to you to decide just what
1259 "casual" and "extensive" mean to you.
1260 This option defaults to 0 (no particular claim).
1262 --min-cert-level
1265 When building the trust database, treat any signatures with a
1266 certification level below this as invalid. Defaults to 2, which
1267 disregards level 1 signatures. Note that level 0 "no particular
1268 claim" signatures are always accepted.
1269 --trusted-key long key ID
1272 Assume that the specified key (which must be given as a full 8
1273 byte key ID) is as trustworthy as one of your own secret keys.
1274 This option is useful if you don't want to keep your secret keys
1275 (or one of them) online but still want to be able to check the
1276 validity of a given recipient's or signator's key.
1277 --trust-model pgp|classic|direct|always|auto
1280 Set what trust model GnuPG should follow. The models are:
1281 pgp This is the Web of Trust combined with trust signatures
1285 as used in PGP 5.x and later. This is the default trust
1286 model when creating a new trust database.
1287 classic
1290 This is the standard Web of Trust as used in PGP 2.x and
1291 earlier.
1292 direct Key validity is set directly by the user and not calcu‐
1295 lated via the Web of Trust.
1296 always Skip key validation and assume that used keys are always
1299 fully trusted. You generally won't use this unless you
1300 are using some external validation scheme. This option
1301 also suppresses the "[uncertain]" tag printed with signa‐
1302 ture checks when there is no evidence that the user ID is
1303 bound to the key.
1304 auto Select the trust model depending on whatever the internal
1307 trust database says. This is the default model if such a
1308 database already exists.
1309 --auto-key-locate parameters
1312 --no-auto-key-locate
1314 GnuPG can automatically locate and retrieve keys as needed using
1315 this option. This happens when encrypting to an email address
1316 (in the "user@example.com" form), and there are no user@exam‐
1317 ple.com keys on the local keyring. This option takes any number
1318 of the following mechanisms, in the order they are to be tried:
1319 cert Locate a key using DNS CERT, as specified in rfc4398.
1323 pka Locate a key using DNS PKA.
1326 ldap Using DNS Service Discovery, check the domain in question
1329 for any LDAP keyservers to use. If this fails, attempt
1330 to locate the key using the PGP Universal method of
1331 checking 'ldap://keys.(thedomain)'.
1332 keyserver
1335 Locate a key using whatever keyserver is defined using
1336 the --keyserver option.
1337 keyserver-URL
1340 In addition, a keyserver URL as used in the --keyserver
1341 option may be used here to query that particular key‐
1342 server.
1343 local Locate the key using the local keyrings. This mechanism
1346 allows to select the order a local key lookup is done.
1347 Thus using '--auto-key-locate local' is identical to
1348 --no-auto-key-locate.
1349 nodefault
1352 This flag disables the standard local key lookup, done
1353 before any of the mechanisms defined by the --auto-key-
1354 locate are tried. The position of this mechanism in the
1355 list does not matter. It is not required if local is
1356 also used.
1357 --keyid-format short|0xshort|long|0xlong
1361 Select how to display key IDs. "short" is the traditional
1362 8-character key ID. "long" is the more accurate (but less conve‐
1363 nient) 16-character key ID. Add an "0x" to either to include an
1364 "0x" at the beginning of the key ID, as in 0x99242560. Note
1365 that this option is ignored if the option --with-colons is used.
1366 --keyserver name
1369 Use name as your keyserver. This is the server that --recv-keys,
1370 --send-keys, and --search-keys will communicate with to receive
1371 keys from, send keys to, and search for keys on. The format of
1372 the name is a URI: `scheme:[//]keyservername[:port]' The scheme
1373 is the type of keyserver: "hkp" for the HTTP (or compatible)
1374 keyservers, "ldap" for the LDAP keyservers, or "mailto" for the
1375 Graff email keyserver. Note that your particular installation of
1376 GnuPG may have other keyserver types available as well. Key‐
1377 server schemes are case-insensitive. After the keyserver name,
1378 optional keyserver configuration options may be provided. These
1379 are the same as the global --keyserver-options from below, but
1380 apply only to this particular keyserver.
1381 Most keyservers synchronize with each other, so there is gener‐
1383 ally no need to send keys to more than one server. The keyserver
1384 hkp://keys.gnupg.net uses round robin DNS to give a different
1385 keyserver each time you use it.
1386 --keyserver-options name=value1
1389 This is a space or comma delimited string that gives options for
1390 the keyserver. Options can be prefixed with a `no-' to give the
1391 opposite meaning. Valid import-options or export-options may be
1392 used here as well to apply to importing (--recv-key) or export‐
1393 ing (--send-key) a key from a keyserver. While not all options
1394 are available for all keyserver types, some common options are:
1395 include-revoked
1399 When searching for a key with --search-keys, include keys
1400 that are marked on the keyserver as revoked. Note that
1401 not all keyservers differentiate between revoked and
1402 unrevoked keys, and for such keyservers this option is
1403 meaningless. Note also that most keyservers do not have
1404 cryptographic verification of key revocations, and so
1405 turning this option off may result in skipping keys that
1406 are incorrectly marked as revoked.
1407 include-disabled
1410 When searching for a key with --search-keys, include keys
1411 that are marked on the keyserver as disabled. Note that
1412 this option is not used with HKP keyservers.
1413 auto-key-retrieve
1416 This option enables the automatic retrieving of keys from
1417 a keyserver when verifying signatures made by keys that
1418 are not on the local keyring.
1419 Note that this option makes a "web bug" like behavior
1421 possible. Keyserver operators can see which keys you
1422 request, so by sending you a message signed by a brand
1423 new key (which you naturally will not have on your local
1424 keyring), the operator can tell both your IP address and
1425 the time when you verified the signature.
1426 honor-keyserver-url
1429 When using --refresh-keys, if the key in question has a
1430 preferred keyserver URL, then use that preferred key‐
1431 server to refresh the key from. In addition, if auto-key-
1432 retrieve is set, and the signature being verified has a
1433 preferred keyserver URL, then use that preferred key‐
1434 server to fetch the key from. Defaults to yes.
1435 honor-pka-record
1438 If auto-key-retrieve is set, and the signature being ver‐
1439 ified has a PKA record, then use the PKA information to
1440 fetch the key. Defaults to yes.
1441 include-subkeys
1444 When receiving a key, include subkeys as potential tar‐
1445 gets. Note that this option is not used with HKP key‐
1446 servers, as they do not support retrieving keys by subkey
1447 id.
1448 use-temp-files
1451 On most Unix-like platforms, GnuPG communicates with the
1452 keyserver helper program via pipes, which is the most
1453 efficient method. This option forces GnuPG to use tempo‐
1454 rary files to communicate. On some platforms (such as
1455 Win32 and RISC OS), this option is always enabled.
1456 keep-temp-files
1459 If using `use-temp-files', do not delete the temp files
1460 after using them. This option is useful to learn the key‐
1461 server communication protocol by reading the temporary
1462 files.
1463 verbose
1466 Tell the keyserver helper program to be more verbose.
1467 This option can be repeated multiple times to increase
1468 the verbosity level.
1469 timeout
1472 Tell the keyserver helper program how long (in seconds)
1473 to try and perform a keyserver action before giving up.
1474 Note that performing multiple actions at the same time
1475 uses this timeout value per action. For example, when
1476 retrieving multiple keys via --recv-keys, the timeout
1477 applies separately to each key retrieval, and not to the
1478 --recv-keys command as a whole. Defaults to 30 seconds.
1479 http-proxy=value
1482 Set the proxy to use for HTTP and HKP keyservers. This
1483 overrides the "http_proxy" environment variable, if any.
1484 max-cert-size
1487 When retrieving a key via DNS CERT, only accept keys up
1488 to this size. Defaults to 16384 bytes.
1489 debug Turn on debug output in the keyserver helper program.
1492 Note that the details of debug output depends on which
1493 keyserver helper program is being used, and in turn, on
1494 any libraries that the keyserver helper program uses
1495 internally (libcurl, openldap, etc).
1496 check-cert
1499 Enable certificate checking if the keyserver presents one
1500 (for hkps or ldaps). Defaults to on.
1501 ca-cert-file
1504 Provide a certificate store to override the system
1505 default. Only necessary if check-cert is enabled, and
1506 the keyserver is using a certificate that is not present
1507 in a system default certificate list.
1508 Note that depending on the SSL library that the keyserver
1510 helper is built with, this may actually be a directory or
1511 a file.
1512 --completes-needed n
1515 Number of completely trusted users to introduce a new key signer
1516 (defaults to 1).
1517 --marginals-needed n
1520 Number of marginally trusted users to introduce a new key signer
1521 (defaults to 3)
1522 --max-cert-depth n
1525 Maximum depth of a certification chain (default is 5).
1526 --simple-sk-checksum
1529 Secret keys are integrity protected by using a SHA-1 checksum.
1530 This method is part of the upcoming enhanced OpenPGP specifica‐
1531 tion but GnuPG already uses it as a countermeasure against cer‐
1532 tain attacks. Old applications don't understand this new for‐
1533 mat, so this option may be used to switch back to the old behav‐
1534 iour. Using this option bears a security risk. Note that using
1535 this option only takes effect when the secret key is encrypted -
1536 the simplest way to make this happen is to change the passphrase
1537 on the key (even changing it to the same value is acceptable).
1538 --no-sig-cache
1541 Do not cache the verification status of key signatures. Caching
1542 gives a much better performance in key listings. However, if you
1543 suspect that your public keyring is not save against write modi‐
1544 fications, you can use this option to disable the caching. It
1545 probably does not make sense to disable it because all kind of
1546 damage can be done if someone else has write access to your pub‐
1547 lic keyring.
1548 --no-sig-create-check
1551 GnuPG normally verifies each signature right after creation to
1552 protect against bugs and hardware malfunctions which could leak
1553 out bits from the secret key. This extra verification needs some
1554 time (about 115% for DSA keys), and so this option can be used
1555 to disable it. However, due to the fact that the signature cre‐
1556 ation needs manual interaction, this performance penalty does
1557 not matter in most settings.
1558 --auto-check-trustdb
1561 --no-auto-check-trustdb
1563 If GnuPG feels that its information about the Web of Trust has
1564 to be updated, it automatically runs the --check-trustdb command
1565 internally. This may be a time consuming process. --no-auto-
1566 check-trustdb disables this option.
1567 --use-agent
1570 --no-use-agent
1572 This is dummy option. gpg2 always requires the agent.
1573 --gpg-agent-info
1576 This is dummy option. It has no effect when used with gpg2.
1577 --lock-once
1580 Lock the databases the first time a lock is requested and do not
1581 release the lock until the process terminates.
1582 --lock-multiple
1585 Release the locks every time a lock is no longer needed. Use
1586 this to override a previous --lock-once from a config file.
1587 --lock-never
1590 Disable locking entirely. This option should be used only in
1591 very special environments, where it can be assured that only one
1592 process is accessing those files. A bootable floppy with a
1593 stand-alone encryption system will probably use this. Improper
1594 usage of this option may lead to data and key corruption.
1595 --exit-on-status-write-error
1598 This option will cause write errors on the status FD to immedi‐
1599 ately terminate the process. That should in fact be the default
1600 but it never worked this way and thus we need an option to
1601 enable this, so that the change won't break applications which
1602 close their end of a status fd connected pipe too early. Using
1603 this option along with --enable-progress-filter may be used to
1604 cleanly cancel long running gpg operations.
1605 --limit-card-insert-tries n
1608 With n greater than 0 the number of prompts asking to insert a
1609 smartcard gets limited to N-1. Thus with a value of 1 gpg won't
1610 at all ask to insert a card if none has been inserted at
1611 startup. This option is useful in the configuration file in case
1612 an application does not know about the smartcard support and
1613 waits ad infinitum for an inserted card.
1614 --no-random-seed-file
1617 GnuPG uses a file to store its internal random pool over invoca‐
1618 tions. This makes random generation faster; however sometimes
1619 write operations are not desired. This option can be used to
1620 achieve that with the cost of slower random generation.
1621 --no-greeting
1624 Suppress the initial copyright message.
1625 --no-secmem-warning
1628 Suppress the warning about "using insecure memory".
1629 --no-permission-warning
1632 Suppress the warning about unsafe file and home directory
1633 (--homedir) permissions. Note that the permission checks that
1634 GnuPG performs are not intended to be authoritative, but rather
1635 they simply warn about certain common permission problems. Do
1636 not assume that the lack of a warning means that your system is
1637 secure.
1638 Note that the warning for unsafe --homedir permissions cannot be
1640 suppressed in the gpg.conf file, as this would allow an attacker
1641 to place an unsafe gpg.conf file in place, and use this file to
1642 suppress warnings about itself. The --homedir permissions warn‐
1643 ing may only be suppressed on the command line.
1644 --no-mdc-warning
1647 Suppress the warning about missing MDC integrity protection.
1648 --require-secmem
1651 --no-require-secmem
1653 Refuse to run if GnuPG cannot get secure memory. Defaults to no
1654 (i.e. run, but give a warning).
1655 --require-cross-certification
1659 --no-require-cross-certification
1661 When verifying a signature made from a subkey, ensure that the
1662 cross certification "back signature" on the subkey is present
1663 and valid. This protects against a subtle attack against sub‐
1664 keys that can sign. Defaults to --require-cross-certification
1665 for gpg2.
1666 --expert
1669 --no-expert
1671 Allow the user to do certain nonsensical or "silly" things like
1672 signing an expired or revoked key, or certain potentially incom‐
1673 patible things like generating unusual key types. This also dis‐
1674 ables certain warning messages about potentially incompatible
1675 actions. As the name implies, this option is for experts only.
1676 If you don't fully understand the implications of what it allows
1677 you to do, leave this off. --no-expert disables this option.
1678 Key related options
1687 --recipient name
1692 -r Encrypt for user id name. If this option or --hidden-recipient
1694 is not specified, GnuPG asks for the user-id unless --default-
1695 recipient is given.
1696 --hidden-recipient name
1699 -R Encrypt for user ID name, but hide the key ID of this user's
1701 key. This option helps to hide the receiver of the message and
1702 is a limited countermeasure against traffic analysis. If this
1703 option or --recipient is not specified, GnuPG asks for the user
1704 ID unless --default-recipient is given.
1705 --encrypt-to name
1708 Same as --recipient but this one is intended for use in the
1709 options file and may be used with your own user-id as an
1710 "encrypt-to-self". These keys are only used when there are other
1711 recipients given either by use of --recipient or by the asked
1712 user id. No trust checking is performed for these user ids and
1713 even disabled keys can be used.
1714 --hidden-encrypt-to name
1717 Same as --hidden-recipient but this one is intended for use in
1718 the options file and may be used with your own user-id as a hid‐
1719 den "encrypt-to-self". These keys are only used when there are
1720 other recipients given either by use of --recipient or by the
1721 asked user id. No trust checking is performed for these user
1722 ids and even disabled keys can be used.
1723 --no-encrypt-to
1726 Disable the use of all --encrypt-to and --hidden-encrypt-to
1727 keys.
1728 --group name=value1
1731 Sets up a named group, which is similar to aliases in email pro‐
1732 grams. Any time the group name is a recipient (-r or --recipi‐
1733 ent), it will be expanded to the values specified. Multiple
1734 groups with the same name are automatically merged into a single
1735 group.
1736 The values are key IDs or fingerprints, but any key description
1738 is accepted. Note that a value with spaces in it will be treated
1739 as two different values. Note also there is only one level of
1740 expansion --- you cannot make an group that points to another
1741 group. When used from the command line, it may be necessary to
1742 quote the argument to this option to prevent the shell from
1743 treating it as multiple arguments.
1744 --ungroup name
1747 Remove a given entry from the --group list.
1748 --no-groups
1751 Remove all entries from the --group list.
1752 --local-user name
1755 -u Use name as the key to sign with. Note that this option over‐
1757 rides --default-key.
1758 --try-secret-key name
1761 For hidden recipients GPG needs to know the keys to use for
1762 trial decryption. The key set with --default-key is always
1763 tried first, but this is often not sufficient. This option
1764 allows to set more keys to be used for trial decryption.
1765 Although any valid user-id specification may be used for name it
1766 makes sense to use at least the long keyid to avoid ambiguities.
1767 Note that gpg-agent might pop up a pinentry for a lot keys to do
1768 the trial decryption. If you want to stop all further trial
1769 decryption you may use close-window button instead of the cancel
1770 button.
1771 --try-all-secrets
1774 Don't look at the key ID as stored in the message but try all
1775 secret keys in turn to find the right decryption key. This
1776 option forces the behaviour as used by anonymous recipients
1777 (created by using --throw-keyids or --hidden-recipient) and
1778 might come handy in case where an encrypted message contains a
1779 bogus key ID.
1780 --skip-hidden-recipients
1783 --no-skip-hidden-recipients
1785 During decryption skip all anonymous recipients. This option
1786 helps in the case that people use the hidden recipients feature
1787 to hide there own encrypt-to key from others. If oneself has
1788 many secret keys this may lead to a major annoyance because all
1789 keys are tried in turn to decrypt soemthing which was not really
1790 intended for it. The drawback of this option is that it is cur‐
1791 rently not possible to decrypt a message which includes real
1792 anonymous recipients.
1793 Input and Output
1799 --armor
1804 -a Create ASCII armored output. The default is to create the
1806 binary OpenPGP format.
1807 --no-armor
1810 Assume the input data is not in ASCII armored format.
1811 --output file
1814 -o file
1816 Write output to file.
1817 --max-output n
1820 This option sets a limit on the number of bytes that will be
1821 generated when processing a file. Since OpenPGP supports various
1822 levels of compression, it is possible that the plaintext of a
1823 given message may be significantly larger than the original
1824 OpenPGP message. While GnuPG works properly with such messages,
1825 there is often a desire to set a maximum file size that will be
1826 generated before processing is forced to stop by the OS limits.
1827 Defaults to 0, which means "no limit".
1828 --import-options parameters
1831 This is a space or comma delimited string that gives options for
1832 importing keys. Options can be prepended with a `no-' to give
1833 the opposite meaning. The options are:
1834 import-local-sigs
1838 Allow importing key signatures marked as "local". This is
1839 not generally useful unless a shared keyring scheme is
1840 being used. Defaults to no.
1841 repair-pks-subkey-bug
1844 During import, attempt to repair the damage caused by the
1845 PKS keyserver bug (pre version 0.9.6) that mangles keys
1846 with multiple subkeys. Note that this cannot completely
1847 repair the damaged key as some crucial data is removed by
1848 the keyserver, but it does at least give you back one
1849 subkey. Defaults to no for regular --import and to yes
1850 for keyserver --recv-keys.
1851 merge-only
1854 During import, allow key updates to existing keys, but do
1855 not allow any new keys to be imported. Defaults to no.
1856 import-clean
1859 After import, compact (remove all signatures except the
1860 self-signature) any user IDs from the new key that are
1861 not usable. Then, remove any signatures from the new key
1862 that are not usable. This includes signatures that were
1863 issued by keys that are not present on the keyring. This
1864 option is the same as running the --edit-key command
1865 "clean" after import. Defaults to no.
1866 import-minimal
1869 Import the smallest key possible. This removes all signa‐
1870 tures except the most recent self-signature on each user
1871 ID. This option is the same as running the --edit-key
1872 command "minimize" after import. Defaults to no.
1873 --export-options parameters
1876 This is a space or comma delimited string that gives options for
1877 exporting keys. Options can be prepended with a `no-' to give
1878 the opposite meaning. The options are:
1879 export-local-sigs
1883 Allow exporting key signatures marked as "local". This is
1884 not generally useful unless a shared keyring scheme is
1885 being used. Defaults to no.
1886 export-attributes
1889 Include attribute user IDs (photo IDs) while exporting.
1890 This is useful to export keys if they are going to be
1891 used by an OpenPGP program that does not accept attribute
1892 user IDs. Defaults to yes.
1893 export-sensitive-revkeys
1896 Include designated revoker information that was marked as
1897 "sensitive". Defaults to no.
1898 export-reset-subkey-passwd
1901 When using the --export-secret-subkeys command, this
1902 option resets the passphrases for all exported subkeys to
1903 empty. This is useful when the exported subkey is to be
1904 used on an unattended machine where a passphrase doesn't
1905 necessarily make sense. Defaults to no.
1906 export-clean
1909 Compact (remove all signatures from) user IDs on the key
1910 being exported if the user IDs are not usable. Also, do
1911 not export any signatures that are not usable. This
1912 includes signatures that were issued by keys that are not
1913 present on the keyring. This option is the same as run‐
1914 ning the --edit-key command "clean" before export except
1915 that the local copy of the key is not modified. Defaults
1916 to no.
1917 export-minimal
1920 Export the smallest key possible. This removes all signa‐
1921 tures except the most recent self-signature on each user
1922 ID. This option is the same as running the --edit-key
1923 command "minimize" before export except that the local
1924 copy of the key is not modified. Defaults to no.
1925 --with-colons
1928 Print key listings delimited by colons. Note that the output
1929 will be encoded in UTF-8 regardless of any --display-charset
1930 setting. This format is useful when GnuPG is called from scripts
1931 and other programs as it is easily machine parsed. The details
1932 of this format are documented in the file ‘doc/DETAILS’, which
1933 is included in the GnuPG source distribution.
1934 --fixed-list-mode
1937 Do not merge primary user ID and primary key in --with-colon
1938 listing mode and print all timestamps as seconds since
1939 1970-01-01. Since GnuPG 2.0.10, this mode is always used and
1940 thus this option is obsolete; it does not harm to use it though.
1941 --with-fingerprint
1944 Same as the command --fingerprint but changes only the format of
1945 the output and may be used together with another command.
1946 --with-keygrip
1949 Include the keygrip in the key listings.
1950 OpenPGP protocol specific options.
1955 -t, --textmode
1960 --no-textmode
1962 Treat input files as text and store them in the OpenPGP canoni‐
1963 cal text form with standard "CRLF" line endings. This also sets
1964 the necessary flags to inform the recipient that the encrypted
1965 or signed data is text and may need its line endings converted
1966 back to whatever the local system uses. This option is useful
1967 when communicating between two platforms that have different
1968 line ending conventions (UNIX-like to Mac, Mac to Windows, etc).
1969 --no-textmode disables this option, and is the default.
1970 --force-v3-sigs
1974 --no-force-v3-sigs
1976 OpenPGP states that an implementation should generate v4 signa‐
1977 tures but PGP versions 5 through 7 only recognize v4 signatures
1978 on key material. This option forces v3 signatures for signatures
1979 on data. Note that this option implies --no-ask-sig-expire, and
1980 unsets --sig-policy-url, --sig-notation, and --sig-keyserver-
1981 url, as these features cannot be used with v3 signatures. --no-
1982 force-v3-sigs disables this option. Defaults to no.
1983 --force-v4-certs
1986 --no-force-v4-certs
1988 Always use v4 key signatures even on v3 keys. This option also
1989 changes the default hash algorithm for v3 RSA keys from MD5 to
1990 SHA-1. --no-force-v4-certs disables this option.
1991 --force-mdc
1994 Force the use of encryption with a modification detection code.
1995 This is always used with the newer ciphers (those with a block‐
1996 size greater than 64 bits), or if all of the recipient keys
1997 indicate MDC support in their feature flags.
1998 --disable-mdc
2001 Disable the use of the modification detection code. Note that by
2002 using this option, the encrypted message becomes vulnerable to a
2003 message modification attack.
2004 --personal-cipher-preferences string
2007 Set the list of personal cipher preferences to string. Use gpg2
2008 --version to get a list of available algorithms, and use none to
2009 set no preference at all. This allows the user to safely over‐
2010 ride the algorithm chosen by the recipient key preferences, as
2011 GPG will only select an algorithm that is usable by all recipi‐
2012 ents. The most highly ranked cipher in this list is also used
2013 for the --symmetric encryption command.
2014 --personal-digest-preferences string
2017 Set the list of personal digest preferences to string. Use gpg2
2018 --version to get a list of available algorithms, and use none to
2019 set no preference at all. This allows the user to safely over‐
2020 ride the algorithm chosen by the recipient key preferences, as
2021 GPG will only select an algorithm that is usable by all recipi‐
2022 ents. The most highly ranked digest algorithm in this list is
2023 also used when signing without encryption (e.g. --clearsign or
2024 --sign).
2025 --personal-compress-preferences string
2028 Set the list of personal compression preferences to string. Use
2029 gpg2 --version to get a list of available algorithms, and use
2030 none to set no preference at all. This allows the user to
2031 safely override the algorithm chosen by the recipient key pref‐
2032 erences, as GPG will only select an algorithm that is usable by
2033 all recipients. The most highly ranked compression algorithm in
2034 this list is also used when there are no recipient keys to con‐
2035 sider (e.g. --symmetric).
2036 --s2k-cipher-algo name
2039 Use name as the cipher algorithm used to protect secret keys.
2040 The default cipher is CAST5. This cipher is also used for con‐
2041 ventional encryption if --personal-cipher-preferences and
2042 --cipher-algo is not given.
2043 --s2k-digest-algo name
2046 Use name as the digest algorithm used to mangle the passphrases.
2047 The default algorithm is SHA-1.
2048 --s2k-mode n
2051 Selects how passphrases are mangled. If n is 0 a plain
2052 passphrase (which is not recommended) will be used, a 1 adds a
2053 salt to the passphrase and a 3 (the default) iterates the whole
2054 process a number of times (see --s2k-count). Unless --rfc1991
2055 is used, this mode is also used for conventional encryption.
2056 --s2k-count n
2059 Specify how many times the passphrase mangling is repeated.
2060 This value may range between 1024 and 65011712 inclusive, and
2061 the default is 65536. Note that not all values in the
2062 1024-65011712 range are legal and if an illegal value is
2063 selected, GnuPG will round up to the nearest legal value. This
2064 option is only meaningful if --s2k-mode is 3.
2065 Compliance options
2071 These options control what GnuPG is compliant to. Only one of these
2074 options may be active at a time. Note that the default setting of this
2075 is nearly always the correct one. See the INTEROPERABILITY WITH OTHER
2076 OPENPGP PROGRAMS section below before using one of these options.
2077 --gnupg
2081 Use standard GnuPG behavior. This is essentially OpenPGP behav‐
2082 ior (see --openpgp), but with some additional workarounds for
2083 common compatibility problems in different versions of PGP. This
2084 is the default option, so it is not generally needed, but it may
2085 be useful to override a different compliance option in the
2086 gpg.conf file.
2087 --openpgp
2090 Reset all packet, cipher and digest options to strict OpenPGP
2091 behavior. Use this option to reset all previous options like
2092 --s2k-*, --cipher-algo, --digest-algo and --compress-algo to
2093 OpenPGP compliant values. All PGP workarounds are disabled.
2094 --rfc4880
2097 Reset all packet, cipher and digest options to strict RFC-4880
2098 behavior. Note that this is currently the same thing as
2099 --openpgp.
2100 --rfc2440
2103 Reset all packet, cipher and digest options to strict RFC-2440
2104 behavior.
2105 --rfc1991
2108 Try to be more RFC-1991 (PGP 2.x) compliant.
2109 --pgp2 Set up all options to be as PGP 2.x compliant as possible, and
2112 warn if an action is taken (e.g. encrypting to a non-RSA key)
2113 that will create a message that PGP 2.x will not be able to han‐
2114 dle. Note that `PGP 2.x' here means `MIT PGP 2.6.2'. There are
2115 other versions of PGP 2.x available, but the MIT release is a
2116 good common baseline.
2117 This option implies --rfc1991 --disable-mdc --no-force-v4-certs
2119 --escape-from-lines --force-v3-sigs --cipher-algo IDEA --digest-
2120 algo MD5 --compress-algo ZIP. It also disables --textmode when
2121 encrypting.
2122 --pgp6 Set up all options to be as PGP 6 compliant as possible. This
2125 restricts you to the ciphers IDEA (if the IDEA plugin is
2126 installed), 3DES, and CAST5, the hashes MD5, SHA1 and RIPEMD160,
2127 and the compression algorithms none and ZIP. This also disables
2128 --throw-keyids, and making signatures with signing subkeys as
2129 PGP 6 does not understand signatures made by signing subkeys.
2130 This option implies --disable-mdc --escape-from-lines --force-
2132 v3-sigs.
2133 --pgp7 Set up all options to be as PGP 7 compliant as possible. This is
2136 identical to --pgp6 except that MDCs are not disabled, and the
2137 list of allowable ciphers is expanded to add AES128, AES192,
2138 AES256, and TWOFISH.
2139 --pgp8 Set up all options to be as PGP 8 compliant as possible. PGP 8
2142 is a lot closer to the OpenPGP standard than previous versions
2143 of PGP, so all this does is disable --throw-keyids and set
2144 --escape-from-lines. All algorithms are allowed except for the
2145 SHA224, SHA384, and SHA512 digests.
2146 Doing things one usually doesn't want to do.
2152 -n
2157 --dry-run
2159 Don't make any changes (this is not completely implemented).
2160 --list-only
2163 Changes the behaviour of some commands. This is like --dry-run
2164 but different in some cases. The semantic of this command may be
2165 extended in the future. Currently it only skips the actual
2166 decryption pass and therefore enables a fast listing of the
2167 encryption keys.
2168 -i
2171 --interactive
2173 Prompt before overwriting any files.
2174 --debug-level level
2177 Select the debug level for investigating problems. level may be
2178 a numeric value or by a keyword:
2179 none No debugging at all. A value of less than 1 may be used
2182 instead of the keyword.
2183 basic Some basic debug messages. A value between 1 and 2 may
2185 be used instead of the keyword.
2186 advanced
2188 More verbose debug messages. A value between 3 and 5 may
2189 be used instead of the keyword.
2190 expert Even more detailed messages. A value between 6 and 8 may
2192 be used instead of the keyword.
2193 guru All of the debug messages you can get. A value greater
2195 than 8 may be used instead of the keyword. The creation
2196 of hash tracing files is only enabled if the keyword is
2197 used.
2198 How these messages are mapped to the actual debugging flags is not
2200 specified and may change with newer releases of this program. They are
2201 however carefully selected to best aid in debugging.
2202 --debug flags
2205 Set debugging flags. All flags are or-ed and flags may be given
2206 in C syntax (e.g. 0x0042).
2207 --debug-all
2210 Set all useful debugging flags.
2211 --faked-system-time epoch
2215 This option is only useful for testing; it sets the system time
2216 back or forth to epoch which is the number of seconds elapsed
2217 since the year 1970. Alternatively epoch may be given as a full
2218 ISO time string (e.g. "20070924T154812").
2219 --enable-progress-filter
2222 Enable certain PROGRESS status outputs. This option allows fron‐
2223 tends to display a progress indicator while gpg is processing
2224 larger files. There is a slight performance overhead using it.
2225 --status-fd n
2228 Write special status strings to the file descriptor n. See the
2229 file DETAILS in the documentation for a listing of them.
2230 --status-file file
2233 Same as --status-fd, except the status data is written to file
2234 file.
2235 --logger-fd n
2238 Write log output to file descriptor n and not to STDERR.
2239 --log-file file
2242 --logger-file file
2244 Same as --logger-fd, except the logger data is written to file
2245 file. Note that --log-file is only implemented for GnuPG-2.
2246 --attribute-fd n
2249 Write attribute subpackets to the file descriptor n. This is
2250 most useful for use with --status-fd, since the status messages
2251 are needed to separate out the various subpackets from the
2252 stream delivered to the file descriptor.
2253 --attribute-file file
2256 Same as --attribute-fd, except the attribute data is written to
2257 file file.
2258 --comment string
2261 --no-comments
2263 Use string as a comment string in clear text signatures and
2264 ASCII armored messages or keys (see --armor). The default behav‐
2265 ior is not to use a comment string. --comment may be repeated
2266 multiple times to get multiple comment strings. --no-comments
2267 removes all comments. It is a good idea to keep the length of a
2268 single comment below 60 characters to avoid problems with mail
2269 programs wrapping such lines. Note that comment lines, like all
2270 other header lines, are not protected by the signature.
2271 --emit-version
2274 --no-emit-version
2276 Force inclusion of the version string in ASCII armored output.
2277 --no-emit-version disables this option.
2278 --sig-notation name=value
2281 --cert-notation name=value
2283 -N, --set-notation name=value
2285 Put the name value pair into the signature as notation data.
2286 name must consist only of printable characters or spaces, and
2287 must contain a '@' character in the form keyname@domain.exam‐
2288 ple.com (substituting the appropriate keyname and domain name,
2289 of course). This is to help prevent pollution of the IETF
2290 reserved notation namespace. The --expert flag overrides the '@'
2291 check. value may be any printable string; it will be encoded in
2292 UTF8, so you should check that your --display-charset is set
2293 correctly. If you prefix name with an exclamation mark (!), the
2294 notation data will be flagged as critical (rfc2440:5.2.3.15).
2295 --sig-notation sets a notation for data signatures. --cert-nota‐
2296 tion sets a notation for key signatures (certifications). --set-
2297 notation sets both.
2298 There are special codes that may be used in notation names. "%k"
2300 will be expanded into the key ID of the key being signed, "%K"
2301 into the long key ID of the key being signed, "%f" into the fin‐
2302 gerprint of the key being signed, "%s" into the key ID of the
2303 key making the signature, "%S" into the long key ID of the key
2304 making the signature, "%g" into the fingerprint of the key mak‐
2305 ing the signature (which might be a subkey), "%p" into the fin‐
2306 gerprint of the primary key of the key making the signature,
2307 "%c" into the signature count from the OpenPGP smartcard, and
2308 "%%" results in a single "%". %k, %K, and %f are only meaningful
2309 when making a key signature (certification), and %c is only
2310 meaningful when using the OpenPGP smartcard.
2311 --sig-policy-url string
2314 --cert-policy-url string
2316 --set-policy-url string
2318 Use string as a Policy URL for signatures (rfc2440:5.2.3.19).
2319 If you prefix it with an exclamation mark (!), the policy URL
2320 packet will be flagged as critical. --sig-policy-url sets a pol‐
2321 icy url for data signatures. --cert-policy-url sets a policy url
2322 for key signatures (certifications). --set-policy-url sets both.
2323 The same %-expandos used for notation data are available here as
2325 well.
2326 --sig-keyserver-url string
2329 Use string as a preferred keyserver URL for data signatures. If
2330 you prefix it with an exclamation mark (!), the keyserver URL
2331 packet will be flagged as critical.
2332 The same %-expandos used for notation data are available here as
2334 well.
2335 --set-filename string
2338 Use string as the filename which is stored inside messages.
2339 This overrides the default, which is to use the actual filename
2340 of the file being encrypted.
2341 --for-your-eyes-only
2344 --no-for-your-eyes-only
2346 Set the `for your eyes only' flag in the message. This causes
2347 GnuPG to refuse to save the file unless the --output option is
2348 given, and PGP to use a "secure viewer" with a claimed Tempest-
2349 resistant font to display the message. This option overrides
2350 --set-filename. --no-for-your-eyes-only disables this option.
2351 --use-embedded-filename
2354 --no-use-embedded-filename
2356 Try to create a file with a name as embedded in the data. This
2357 can be a dangerous option as it allows to overwrite files.
2358 Defaults to no.
2359 --cipher-algo name
2362 Use name as cipher algorithm. Running the program with the com‐
2363 mand --version yields a list of supported algorithms. If this is
2364 not used the cipher algorithm is selected from the preferences
2365 stored with the key. In general, you do not want to use this
2366 option as it allows you to violate the OpenPGP standard. --per‐
2367 sonal-cipher-preferences is the safe way to accomplish the same
2368 thing.
2369 --digest-algo name
2372 Use name as the message digest algorithm. Running the program
2373 with the command --version yields a list of supported algo‐
2374 rithms. In general, you do not want to use this option as it
2375 allows you to violate the OpenPGP standard. --personal-digest-
2376 preferences is the safe way to accomplish the same thing.
2377 --compress-algo name
2380 Use compression algorithm name. "zlib" is RFC-1950 ZLIB compres‐
2381 sion. "zip" is RFC-1951 ZIP compression which is used by PGP.
2382 "bzip2" is a more modern compression scheme that can compress
2383 some things better than zip or zlib, but at the cost of more
2384 memory used during compression and decompression. "uncompressed"
2385 or "none" disables compression. If this option is not used, the
2386 default behavior is to examine the recipient key preferences to
2387 see which algorithms the recipient supports. If all else fails,
2388 ZIP is used for maximum compatibility.
2389 ZLIB may give better compression results than ZIP, as the com‐
2391 pression window size is not limited to 8k. BZIP2 may give even
2392 better compression results than that, but will use a signifi‐
2393 cantly larger amount of memory while compressing and decompress‐
2394 ing. This may be significant in low memory situations. Note,
2395 however, that PGP (all versions) only supports ZIP compression.
2396 Using any algorithm other than ZIP or "none" will make the mes‐
2397 sage unreadable with PGP. In general, you do not want to use
2398 this option as it allows you to violate the OpenPGP standard.
2399 --personal-compress-preferences is the safe way to accomplish
2400 the same thing.
2401 --cert-digest-algo name
2404 Use name as the message digest algorithm used when signing a
2405 key. Running the program with the command --version yields a
2406 list of supported algorithms. Be aware that if you choose an
2407 algorithm that GnuPG supports but other OpenPGP implementations
2408 do not, then some users will not be able to use the key signa‐
2409 tures you make, or quite possibly your entire key.
2410 --disable-cipher-algo name
2413 Never allow the use of name as cipher algorithm. The given name
2414 will not be checked so that a later loaded algorithm will still
2415 get disabled.
2416 --disable-pubkey-algo name
2419 Never allow the use of name as public key algorithm. The given
2420 name will not be checked so that a later loaded algorithm will
2421 still get disabled.
2422 --throw-keyids
2425 --no-throw-keyids
2427 Do not put the recipient key IDs into encrypted messages. This
2428 helps to hide the receivers of the message and is a limited
2429 countermeasure against traffic analysis. ([Using a little social
2430 engineering anyone who is able to decrypt the message can check
2431 whether one of the other recipients is the one he suspects.])
2432 On the receiving side, it may slow down the decryption process
2433 because all available secret keys must be tried. --no-throw-
2434 keyids disables this option. This option is essentially the same
2435 as using --hidden-recipient for all recipients.
2436 --not-dash-escaped
2439 This option changes the behavior of cleartext signatures so that
2440 they can be used for patch files. You should not send such an
2441 armored file via email because all spaces and line endings are
2442 hashed too. You can not use this option for data which has 5
2443 dashes at the beginning of a line, patch files don't have this.
2444 A special armor header line tells GnuPG about this cleartext
2445 signature option.
2446 --escape-from-lines
2449 --no-escape-from-lines
2451 Because some mailers change lines starting with "From " to
2452 ">From " it is good to handle such lines in a special way when
2453 creating cleartext signatures to prevent the mail system from
2454 breaking the signature. Note that all other PGP versions do it
2455 this way too. Enabled by default. --no-escape-from-lines dis‐
2456 ables this option.
2457 --passphrase-repeat n
2460 Specify how many times gpg2 will request a new passphrase be
2461 repeated. This is useful for helping memorize a passphrase.
2462 Defaults to 1 repetition.
2463 --passphrase-fd n
2466 Read the passphrase from file descriptor n. Only the first line
2467 will be read from file descriptor n. If you use 0 for n, the
2468 passphrase will be read from STDIN. This can only be used if
2469 only one passphrase is supplied. Note that this passphrase is
2470 only used if the option --batch has also been given. This is
2471 different from gpg.
2472 --passphrase-file file
2475 Read the passphrase from file file. Only the first line will be
2476 read from file file. This can only be used if only one
2477 passphrase is supplied. Obviously, a passphrase stored in a file
2478 is of questionable security if other users can read this file.
2479 Don't use this option if you can avoid it. Note that this
2480 passphrase is only used if the option --batch has also been
2481 given. This is different from gpg.
2482 --passphrase string
2485 Use string as the passphrase. This can only be used if only one
2486 passphrase is supplied. Obviously, this is of very questionable
2487 security on a multi-user system. Don't use this option if you
2488 can avoid it. Note that this passphrase is only used if the
2489 option --batch has also been given. This is different from gpg.
2490 --command-fd n
2493 This is a replacement for the deprecated shared-memory IPC mode.
2494 If this option is enabled, user input on questions is not
2495 expected from the TTY but from the given file descriptor. It
2496 should be used together with --status-fd. See the file
2497 doc/DETAILS in the source distribution for details on how to use
2498 it.
2499 --command-file file
2502 Same as --command-fd, except the commands are read out of file
2503 file
2504 --allow-non-selfsigned-uid
2507 --no-allow-non-selfsigned-uid
2509 Allow the import and use of keys with user IDs which are not
2510 self-signed. This is not recommended, as a non self-signed user
2511 ID is trivial to forge. --no-allow-non-selfsigned-uid disables.
2512 --allow-freeform-uid
2515 Disable all checks on the form of the user ID while generating a
2516 new one. This option should only be used in very special envi‐
2517 ronments as it does not ensure the de-facto standard format of
2518 user IDs.
2519 --ignore-time-conflict
2522 GnuPG normally checks that the timestamps associated with keys
2523 and signatures have plausible values. However, sometimes a sig‐
2524 nature seems to be older than the key due to clock problems.
2525 This option makes these checks just a warning. See also
2526 --ignore-valid-from for timestamp issues on subkeys.
2527 --ignore-valid-from
2530 GnuPG normally does not select and use subkeys created in the
2531 future. This option allows the use of such keys and thus
2532 exhibits the pre-1.0.7 behaviour. You should not use this option
2533 unless there is some clock problem. See also --ignore-time-con‐
2534 flict for timestamp issues with signatures.
2535 --ignore-crc-error
2538 The ASCII armor used by OpenPGP is protected by a CRC checksum
2539 against transmission errors. Occasionally the CRC gets mangled
2540 somewhere on the transmission channel but the actual content
2541 (which is protected by the OpenPGP protocol anyway) is still
2542 okay. This option allows GnuPG to ignore CRC errors.
2543 --ignore-mdc-error
2546 This option changes a MDC integrity protection failure into a
2547 warning. This can be useful if a message is partially corrupt,
2548 but it is necessary to get as much data as possible out of the
2549 corrupt message. However, be aware that a MDC protection fail‐
2550 ure may also mean that the message was tampered with intention‐
2551 ally by an attacker.
2552 --no-default-keyring
2555 Do not add the default keyrings to the list of keyrings. Note
2556 that GnuPG will not operate without any keyrings, so if you use
2557 this option and do not provide alternate keyrings via --keyring
2558 or --secret-keyring, then GnuPG will still use the default pub‐
2559 lic or secret keyrings.
2560 --skip-verify
2563 Skip the signature verification step. This may be used to make
2564 the decryption faster if the signature verification is not
2565 needed.
2566 --with-key-data
2569 Print key listings delimited by colons (like --with-colons) and
2570 print the public key data.
2571 --fast-list-mode
2574 Changes the output of the list commands to work faster; this is
2575 achieved by leaving some parts empty. Some applications don't
2576 need the user ID and the trust information given in the list‐
2577 ings. By using this options they can get a faster listing. The
2578 exact behaviour of this option may change in future versions.
2579 If you are missing some information, don't use this option.
2580 --no-literal
2583 This is not for normal use. Use the source to see for what it
2584 might be useful.
2585 --set-filesize
2588 This is not for normal use. Use the source to see for what it
2589 might be useful.
2590 --show-session-key
2593 Display the session key used for one message. See --override-
2594 session-key for the counterpart of this option.
2595 We think that Key Escrow is a Bad Thing; however the user should
2597 have the freedom to decide whether to go to prison or to reveal
2598 the content of one specific message without compromising all
2599 messages ever encrypted for one secret key. DON'T USE IT UNLESS
2600 YOU ARE REALLY FORCED TO DO SO.
2601 --override-session-key string
2604 Don't use the public key but the session key string. The format
2605 of this string is the same as the one printed by --show-session-
2606 key. This option is normally not used but comes handy in case
2607 someone forces you to reveal the content of an encrypted mes‐
2608 sage; using this option you can do this without handing out the
2609 secret key.
2610 --ask-sig-expire
2613 --no-ask-sig-expire
2615 When making a data signature, prompt for an expiration time. If
2616 this option is not specified, the expiration time set via
2617 --default-sig-expire is used. --no-ask-sig-expire disables this
2618 option.
2619 --default-sig-expire
2622 The default expiration time to use for signature expiration.
2623 Valid values are "0" for no expiration, a number followed by the
2624 letter d (for days), w (for weeks), m (for months), or y (for
2625 years) (for example "2m" for two months, or "5y" for five
2626 years), or an absolute date in the form YYYY-MM-DD. Defaults to
2627 "0".
2628 --ask-cert-expire
2631 --no-ask-cert-expire
2633 When making a key signature, prompt for an expiration time. If
2634 this option is not specified, the expiration time set via
2635 --default-cert-expire is used. --no-ask-cert-expire disables
2636 this option.
2637 --default-cert-expire
2640 The default expiration time to use for key signature expiration.
2641 Valid values are "0" for no expiration, a number followed by the
2642 letter d (for days), w (for weeks), m (for months), or y (for
2643 years) (for example "2m" for two months, or "5y" for five
2644 years), or an absolute date in the form YYYY-MM-DD. Defaults to
2645 "0".
2646 --allow-secret-key-import
2649 This is an obsolete option and is not used anywhere.
2650 --allow-multiple-messages
2653 --no-allow-multiple-messages
2655 Allow processing of multiple OpenPGP messages contained in a
2656 single file or stream. Some programs that call GPG are not pre‐
2657 pared to deal with multiple messages being processed together,
2658 so this option defaults to no. Note that versions of GPG prior
2659 to 1.4.7 always allowed multiple messages.
2660 Warning: Do not use this option unless you need it as a tempo‐
2662 rary workaround!
2663 --enable-special-filenames
2667 This options enables a mode in which filenames of the form
2668 ‘-&n’, where n is a non-negative decimal number, refer to the
2669 file descriptor n and not to a file with that name.
2670 --no-expensive-trust-checks
2673 Experimental use only.
2674 --preserve-permissions
2677 Don't change the permissions of a secret keyring back to user
2678 read/write only. Use this option only if you really know what
2679 you are doing.
2680 --default-preference-list string
2683 Set the list of default preferences to string. This preference
2684 list is used for new keys and becomes the default for "setpref"
2685 in the edit menu.
2686 --default-keyserver-url name
2689 Set the default keyserver URL to name. This keyserver will be
2690 used as the keyserver URL when writing a new self-signature on a
2691 key, which includes key generation and changing preferences.
2692 --list-config
2695 Display various internal configuration parameters of GnuPG. This
2696 option is intended for external programs that call GnuPG to per‐
2697 form tasks, and is thus not generally useful. See the file
2698 ‘doc/DETAILS’ in the source distribution for the details of
2699 which configuration items may be listed. --list-config is only
2700 usable with --with-colons set.
2701 --gpgconf-list
2704 This command is similar to --list-config but in general only
2705 internally used by the gpgconf tool.
2706 --gpgconf-test
2709 This is more or less dummy action. However it parses the con‐
2710 figuration file and returns with failure if the configuration
2711 file would prevent gpg from startup. Thus it may be used to run
2712 a syntax check on the configuration file.
2713 Deprecated options
2718 --show-photos
2724 --no-show-photos
2726 Causes --list-keys, --list-sigs, --list-public-keys, --list-
2727 secret-keys, and verifying a signature to also display the photo
2728 ID attached to the key, if any. See also --photo-viewer. These
2729 options are deprecated. Use --list-options [no-]show-photos
2730 and/or --verify-options [no-]show-photos instead.
2731 --show-keyring
2734 Display the keyring name at the head of key listings to show
2735 which keyring a given key resides on. This option is deprecated:
2736 use --list-options [no-]show-keyring instead.
2737 --always-trust
2741 Identical to --trust-model always. This option is deprecated.
2742 --show-notation
2745 --no-show-notation
2747 Show signature notations in the --list-sigs or --check-sigs
2748 listings as well as when verifying a signature with a notation
2749 in it. These options are deprecated. Use --list-options
2750 [no-]show-notation and/or --verify-options [no-]show-notation
2751 instead.
2752 --show-policy-url
2755 --no-show-policy-url
2757 Show policy URLs in the --list-sigs or --check-sigs listings as
2758 well as when verifying a signature with a policy URL in it.
2759 These options are deprecated. Use --list-options [no-]show-pol‐
2760 icy-url and/or --verify-options [no-]show-policy-url instead.
2761
2768 gpg -se -r Bob file
2769 sign and encrypt for user Bob
2770 gpg --clearsign file
2773 make a clear text signature
2774 gpg -sb file
2777 make a detached signature
2778 gpg -u 0x12345678 -sb file
2781 make a detached signature with the key 0x12345678
2782 gpg --list-keys user_ID
2785 show keys
2786 gpg --fingerprint user_ID
2789 show fingerprint
2790 gpg --verify pgpfile
2793 gpg --verify sigfile
2795 Verify the signature of the file but do not output the data. The
2796 second form is used for detached signatures, where sigfile is
2797 the detached signature (either ASCII armored or binary) and are
2798 the signed data; if this is not given, the name of the file
2799 holding the signed data is constructed by cutting off the exten‐
2800 sion (".asc" or ".sig") of sigfile or by asking the user for the
2801 filename.
2802
2807 There are different ways to specify a user ID to GnuPG. Some of them
2808 are only valid for gpg others are only good for gpgsm. Here is the
2809 entire list of ways to specify a key:
2810 By key Id.
2814 This format is deduced from the length of the string and its
2815 content or 0x prefix. The key Id of an X.509 certificate are the
2816 low 64 bits of its SHA-1 fingerprint. The use of key Ids is
2817 just a shortcut, for all automated processing the fingerprint
2818 should be used.
2819 When using gpg an exclamation mark (!) may be appended to force
2821 using the specified primary or secondary key and not to try and
2822 calculate which primary or secondary key to use.
2823 The last four lines of the example give the key ID in their long
2825 form as internally used by the OpenPGP protocol. You can see the
2826 long key ID using the option --with-colons.
2827 234567C4
2829 0F34E556E
2830 01347A56A
2831 0xAB123456
2832 234AABBCC34567C4
2834 0F323456784E56EAB
2835 01AB3FED1347A5612
2836 0x234AABBCC34567C4
2837 By fingerprint.
2842 This format is deduced from the length of the string and its
2843 content or the 0x prefix. Note, that only the 20 byte version
2844 fingerprint is available with gpgsm (i.e. the SHA-1 hash of the
2845 certificate).
2846 When using gpg an exclamation mark (!) may be appended to force
2848 using the specified primary or secondary key and not to try and
2849 calculate which primary or secondary key to use.
2850 The best way to specify a key Id is by using the fingerprint.
2852 This avoids any ambiguities in case that there are duplicated
2853 key IDs.
2854 1234343434343434C434343434343434
2856 123434343434343C3434343434343734349A3434
2857 0E12343434343434343434EAB3484343434343434
2858 0xE12343434343434343434EAB3484343434343434
2859 (gpgsm also accepts colons between each pair of hexadecimal digits
2862 because this is the de-facto standard on how to present X.509 finger‐
2863 prints.)
2864 By exact match on OpenPGP user ID.
2867 This is denoted by a leading equal sign. It does not make sense
2868 for X.509 certificates.
2869 =Heinrich Heine <heinrichh@uni-duesseldorf.de>
2871 By exact match on an email address.
2874 This is indicated by enclosing the email address in the usual
2875 way with left and right angles.
2876 <heinrichh@uni-duesseldorf.de>
2878 By word match.
2882 All words must match exactly (not case sensitive) but can appear
2883 in any order in the user ID or a subjects name. Words are any
2884 sequences of letters, digits, the underscore and all characters
2885 with bit 7 set.
2886 +Heinrich Heine duesseldorf
2888 By exact match on the subject's DN.
2891 This is indicated by a leading slash, directly followed by the
2892 RFC-2253 encoded DN of the subject. Note that you can't use the
2893 string printed by "gpgsm --list-keys" because that one as been
2894 reordered and modified for better readability; use --with-colons
2895 to print the raw (but standard escaped) RFC-2253 string
2896 /CN=Heinrich Heine,O=Poets,L=Paris,C=FR
2898 By exact match on the issuer's DN.
2901 This is indicated by a leading hash mark, directly followed by a
2902 slash and then directly followed by the rfc2253 encoded DN of
2903 the issuer. This should return the Root cert of the issuer.
2904 See note above.
2905 #/CN=Root Cert,O=Poets,L=Paris,C=FR
2907 By exact match on serial number and issuer's DN.
2911 This is indicated by a hash mark, followed by the hexadecimal
2912 representation of the serial number, then followed by a slash
2913 and the RFC-2253 encoded DN of the issuer. See note above.
2914 #4F03/CN=Root Cert,O=Poets,L=Paris,C=FR
2916 By keygrip
2919 This is indicated by an ampersand followed by the 40 hex digits
2920 of a keygrip. gpgsm prints the keygrip when using the command
2921 --dump-cert. It does not yet work for OpenPGP keys.
2922 &D75F22C3F86E355877348498CDC92BD21010A480
2924 By substring match.
2928 This is the default mode but applications may want to explicitly
2929 indicate this by putting the asterisk in front. Match is not
2930 case sensitive.
2931 Heine
2933 *Heine
2934 Please note that we have reused the hash mark identifier which was used
2938 in old GnuPG versions to indicate the so called local-id. It is not
2939 anymore used and there should be no conflict when used with X.509
2940 stuff.
2941 Using the RFC-2253 format of DNs has the drawback that it is not possi‐
2943 ble to map them back to the original encoding, however we don't have to
2944 do this because our key database stores this encoding as meta data.
2945
2951 There are a few configuration files to control certain aspects of
2952 gpg2's operation. Unless noted, they are expected in the current home
2953 directory (see: [option --homedir]).
2954 gpg.conf
2958 This is the standard configuration file read by gpg2 on startup.
2959 It may contain any valid long option; the leading two dashes may
2960 not be entered and the option may not be abbreviated. This
2961 default name may be changed on the command line (see: [option
2962 --options]). You should backup this file.
2963 Note that on larger installations, it is useful to put predefined files
2966 into the directory ‘/etc/skel/.gnupg/’ so that newly created users
2967 start up with a working configuration. For existing users the a small
2968 helper script is provided to create these files (see: [addgnupghome]).
2969 For internal purposes gpg2 creates and maintains a few other files;
2971 They all live in in the current home directory (see: [option --home‐
2972 dir]). Only the gpg2 may modify these files.
2973 ~/.gnupg/secring.gpg
2977 The secret keyring. You should backup this file.
2978 ~/.gnupg/secring.gpg.lock
2981 The lock file for the secret keyring.
2982 ~/.gnupg/pubring.gpg
2985 The public keyring. You should backup this file.
2986 ~/.gnupg/pubring.gpg.lock
2989 The lock file for the public keyring.
2990 ~/.gnupg/trustdb.gpg
2993 The trust database. There is no need to backup this file; it is
2994 better to backup the ownertrust values (see: [option --export-
2995 ownertrust]).
2996 ~/.gnupg/trustdb.gpg.lock
2999 The lock file for the trust database.
3000 ~/.gnupg/random_seed
3003 A file used to preserve the state of the internal random pool.
3004 /usr[/local]/share/gnupg/options.skel
3007 The skeleton options file.
3008 /usr[/local]/lib/gnupg/
3011 Default location for extensions.
3012 Operation is further controlled by a few environment variables:
3015 HOME Used to locate the default home directory.
3019 GNUPGHOME
3022 If set directory used instead of "~/.gnupg".
3023 GPG_AGENT_INFO
3026 Used to locate the gpg-agent. The value consists of 3 colon
3027 delimited fields: The first is the path to the Unix Domain
3028 Socket, the second the PID of the gpg-agent and the protocol
3029 version which should be set to 1. When starting the gpg-agent as
3030 described in its documentation, this variable is set to the cor‐
3031 rect value. The option --gpg-agent-info can be used to override
3032 it.
3033 PINENTRY_USER_DATA
3036 This value is passed via gpg-agent to pinentry. It is useful to
3037 convey extra information to a custom pinentry.
3038 COLUMNS
3041 LINES Used to size some displays to the full size of the screen.
3043 LANGUAGE
3047 Apart from its use by GNU, it is used in the W32 version to
3048 override the language selection done through the Registry. If
3049 used and set to a valid and available language name (langid),
3050 the file with the translation is loaded from
3051 gpgdir/gnupg.nls/langid.mo. Here gpgdir is the directory out of
3052 which the gpg binary has been loaded. If it can't be loaded the
3053 Registry is tried and as last resort the native Windows locale
3054 system is used.
3055
3061 On older systems this program should be installed as setuid(root). This
3062 is necessary to lock memory pages. Locking memory pages prevents the
3063 operating system from writing memory pages (which may contain
3064 passphrases or other sensitive material) to disk. If you get no warning
3065 message about insecure memory your operating system supports locking
3066 without being root. The program drops root privileges as soon as locked
3067 memory is allocated.
3068 Note also that some systems (especially laptops) have the ability to
3070 ``suspend to disk'' (also known as ``safe sleep'' or ``hibernate'').
3071 This writes all memory to disk before going into a low power or even
3072 powered off mode. Unless measures are taken in the operating system to
3073 protect the saved memory, passphrases or other sensitive material may
3074 be recoverable from it later.
3075 Before you report a bug you should first search the mailing list ar‐
3077 chives for similar problems and second check whether such a bug has
3078 already been reported to our bug tracker at http://bugs.gnupg.org .
3079
3083 gpgv(1), gpgsm(1), gpg-agent(1)
3084 The full documentation for this tool is maintained as a Texinfo manual.
3086 If GnuPG and the info program are properly installed at your site, the
3087 command
3088 info gnupg
3090 should give you access to the complete manual including a menu struc‐
3092 ture and an index.
3093GnuPG 2.0.18 2011-09-20 GPG2(1)