@command{@gpgname} is the OpenPGP part of the GNU Privacy Guard (GnuPG). It
is a tool to provide digital encryption and signing services using the
OpenPGP standard. @command{@gpgname} features complete key management and
-all bells and whistles you can expect from a decent OpenPGP
+all the bells and whistles you would expect from a full OpenPGP
implementation.
+There are two main versions of GnuPG: GnuPG 1.x and GnuPG 2.x. GnuPG
+2.x supports modern encryption algorithms and thus should be preferred
+over GnuPG 1.x. You only need to use GnuPG 1.x if your platform
+doesn't support GnuPG 2.x, or you need support for some features that
+GnuPG 2.x has deprecated, e.g., decrypting data created with PGP-2
+keys.
+
@ifclear gpgtwohack
-Note that this version of GnuPG features all modern algorithms and
-should thus be preferred over older GnuPG versions. If you are
-looking for version 1 of GnuPG, you may find that version installed
-under the name @command{gpg1}.
+If you are looking for version 1 of GnuPG, you may find that version
+installed under the name @command{gpg1}.
@end ifclear
@ifset gpgtwohack
-In contrast to the standalone command gpg from GnuPG 1.x, which
-might be better suited for server and embedded platforms, the 2.x
-version is commonly installed under the name @command{@gpgname} and
-targeted to the desktop as it requires several other modules to be
-installed.
+In contrast to the standalone command @command{gpg} from GnuPG 1.x,
+the 2.x version is commonly installed under the name
+@command{@gpgname}.
@end ifset
@manpause
@section Commands
Commands are not distinguished from options except for the fact that
-only one command is allowed.
+only one command is allowed. Generally speaking, irrelevant options
+are silently ignored, and may not be checked for correctness.
-@command{@gpgname} may be run with no commands, in which case it will
+@command{@gpgname} may be run with no commands. In this case it will
perform a reasonable action depending on the type of file it is given
as input (an encrypted message is decrypted, a signature is verified,
-a file containing keys is listed).
-
-Please remember that option as well as command parsing stops as soon as
-a non-option is encountered, you can explicitly stop parsing by
-using the special option @option{--}.
+a file containing keys is listed, etc.).
@menu
@item --help
@itemx -h
@opindex help
-Print a usage message summarizing the most useful command line options.
-Note that you cannot abbreviate this command.
+Print a usage message summarizing the most useful command-line options.
+Note that you cannot arbitrarily abbreviate this command
+(though you can use its short form @option{-h}).
@item --warranty
@opindex warranty
@item --sign
@itemx -s
@opindex sign
-Make a signature. This command may be combined with @option{--encrypt}
-(for a signed and encrypted message), @option{--symmetric} (for a
-signed and symmetrically encrypted message), or @option{--encrypt} and
-@option{--symmetric} together (for a signed message that may be
-decrypted via a secret key or a passphrase). The key to be used for
-signing is chosen by default or can be set with the
+Sign a message. This command may be combined with @option{--encrypt}
+(to sign and encrypt a message), @option{--symmetric} (to sign and
+symmetrically encrypt a message), or both @option{--encrypt} and
+@option{--symmetric} (to sign and encrypt a message that can be
+decrypted using a secret key or a passphrase). The signing key is
+chosen by default or can be set explicitly using the
@option{--local-user} and @option{--default-key} options.
-@item --clearsign
+@item --clear-sign
+@opindex clear-sign
+@itemx --clearsign
@opindex clearsign
-Make a clear text signature. The content in a clear text signature is
+Make a cleartext signature. The content in a cleartext signature is
readable without any special software. OpenPGP software is only needed
-to verify the signature. Clear text signatures may modify end-of-line
+to verify the signature. cleartext signatures may modify end-of-line
whitespace for platform independence and are not intended to be
-reversible. The key to be used for signing is chosen by default or
-can be set with the @option{--local-user} and @option{--default-key}
+reversible. The signing key is chosen by default or can be set
+explicitly using the @option{--local-user} and @option{--default-key}
options.
@item --encrypt
@itemx -e
@opindex encrypt
-Encrypt data. This option may be combined with @option{--sign} (for a
-signed and encrypted message), @option{--symmetric} (for a message that
-may be decrypted via a secret key or a passphrase), or @option{--sign}
-and @option{--symmetric} together (for a signed message that may be
-decrypted via a secret key or a passphrase).
+Encrypt data to one or more public keys. This command may be combined
+with @option{--sign} (to sign and encrypt a message),
+@option{--symmetric} (to encrypt a message that can decrypted using a
+secret key or a passphrase), or @option{--sign} and
+@option{--symmetric} together (for a signed message that can be
+decrypted using a secret key or a passphrase). @option{--recipient}
+and related options specify which public keys to use for encryption.
@item --symmetric
@itemx -c
@opindex symmetric
Encrypt with a symmetric cipher using a passphrase. The default
symmetric cipher used is @value{GPGSYMENCALGO}, but may be chosen with the
-@option{--cipher-algo} option. This option may be combined with
+@option{--cipher-algo} option. This command may be combined with
@option{--sign} (for a signed and symmetrically encrypted message),
@option{--encrypt} (for a message that may be decrypted via a secret key
or a passphrase), or @option{--sign} and @option{--encrypt} together
@option{--output}). If the decrypted file is signed, the signature is also
verified. This command differs from the default operation, as it never
writes to the filename which is included in the file and it rejects
-files which don't begin with an encrypted message.
+files that don't begin with an encrypted message.
@item --verify
@opindex verify
Assume that the first argument is a signed file and verify it without
generating any output. With no arguments, the signature packet is
-read from STDIN. If only a one argument is given, it is expected to
-be a complete signature.
+read from STDIN. If only one argument is given, the specified file is
+expected to include a complete signature.
-With more than 1 argument, the first should be a detached signature
-and the remaining files make up the the signed data. To read the signed
-data from STDIN, use @samp{-} as the second filename. For security
-reasons a detached signature cannot read the signed material from
-STDIN without denoting it in the above way.
+With more than one argument, the first argument should specify a file
+with a detached signature and the remaining files should contain the
+signed data. To read the signed data from STDIN, use @samp{-} as the
+second filename. For security reasons, a detached signature will not
+read the signed material from STDIN if not explicitly specified.
Note: If the option @option{--batch} is not used, @command{@gpgname}
-may assume that a single argument is a file with a detached signature
+may assume that a single argument is a file with a detached signature,
and it will try to find a matching data file by stripping certain
suffixes. Using this historical feature to verify a detached
-signature is strongly discouraged; always specify the data file too.
+signature is strongly discouraged; you should always specify the data file
+explicitly.
-Note: When verifying a cleartext signature, @command{gpg} verifies
+Note: When verifying a cleartext signature, @command{@gpgname} verifies
only what makes up the cleartext signed data and not any extra data
-outside of the cleartext signature or header lines following directly
+outside of the cleartext signature or the header lines directly following
the dash marker line. The option @code{--output} may be used to write
-out the actual signed data; but there are other pitfalls with this
+out the actual signed data, but there are other pitfalls with this
format as well. It is suggested to avoid cleartext signatures in
favor of detached signatures.
+Note: Sometimes the use of the @command{gpgv} tool is easier than
+using the full-fledged @command{gpg} with this option. @command{gpgv}
+is designed to compare signed data against a list of trusted keys and
+returns with success only for a good signature. It has its own manual
+page.
+
+
@item --multifile
@opindex multifile
This modifies certain other commands to accept multiple files for
@itemx -k
@itemx --list-public-keys
@opindex list-keys
-List all keys from the public keyrings, or just the keys given on the
-command line.
+List the specified keys. If no keys are specified, then all keys from
+the configured public keyrings are listed.
-Avoid using the output of this command in scripts or other programs as
-it is likely to change as GnuPG changes. See @option{--with-colons}
-for a machine-parseable key listing command that is appropriate for
-use in scripts and other programs. Never use the regular output for
-scripts - it is only for human consumption.
+Never use the output of this command in scripts or other programs.
+The output is intended only for humans and its format is likely to
+change. The @option{--with-colons} option emits the output in a
+stable, machine-parseable format, which is intended for use by scripts
+and other programs.
@item --list-secret-keys
@itemx -K
@opindex list-secret-keys
-List all keys from the secret keyrings, or just the ones given on the
-command line. A @code{#} after the letters @code{sec} means that the
-secret key is not usable (for example, if it was created via
-@option{--export-secret-subkeys}). See also @option{--list-keys}.
-
-@item --list-sigs
-@opindex list-sigs
-Same as @option{--list-keys}, but the signatures are listed too.
-This command has the same effect as
-using @option{--list-keys} with @option{--with-sig-list}.
-
-For each signature listed, there are several flags in between the "sig"
-tag and keyid. These flags give additional information about each
-signature. From left to right, they are the numbers 1-3 for certificate
-check level (see @option{--ask-cert-level}), "L" for a local or
-non-exportable signature (see @option{--lsign-key}), "R" for a
-nonRevocable signature (see the @option{--edit-key} command "nrsign"),
-"P" for a signature that contains a policy URL (see
-@option{--cert-policy-url}), "N" for a signature that contains a
-notation (see @option{--cert-notation}), "X" for an eXpired signature
-(see @option{--ask-cert-expire}), and the numbers 1-9 or "T" for 10 and
-above to indicate trust signature levels (see the @option{--edit-key}
-command "tsign").
-
-@item --check-sigs
+List the specified secret keys. If no keys are specified, then all
+known secret keys are listed. A @code{#} after the initial tags
+@code{sec} or @code{ssb} means that the secret key or subkey is
+currently not usable. We also say that this key has been taken
+offline (for example, a primary key can be taken offline by exported
+the key using the command @option{--export-secret-subkeys}). A
+@code{>} after these tags indicate that the key is stored on a
+smartcard. See also @option{--list-keys}.
+
+@item --check-signatures
+@opindex check-signatures
+@itemx --check-sigs
@opindex check-sigs
-Same as @option{--list-sigs}, but the signatures are verified. Note
-that for performance reasons the revocation status of a signing key is
-not shown.
-This command has the same effect as
+Same as @option{--list-keys}, but the key signatures are verified and
+listed too. Note that for performance reasons the revocation status
+of a signing key is not shown. This command has the same effect as
using @option{--list-keys} with @option{--with-sig-check}.
-The status of the verification is indicated by a flag directly following
-the "sig" tag (and thus before the flags described above for
-@option{--list-sigs}). A "!" indicates that the signature has been
-successfully verified, a "-" denotes a bad signature and a "%" is used
-if an error occurred while checking the signature (e.g. a non supported
-algorithm).
+The status of the verification is indicated by a flag directly
+following the "sig" tag (and thus before the flags described below. A
+"!" indicates that the signature has been successfully verified, a "-"
+denotes a bad signature and a "%" is used if an error occurred while
+checking the signature (e.g. a non supported algorithm). Signatures
+where the public key is not availabale are not listed; to see their
+keyids the command @option{--list-sigs} can be used.
+
+For each signature listed, there are several flags in between the
+signature status flag and keyid. These flags give additional
+information about each key signature. From left to right, they are
+the numbers 1-3 for certificate check level (see
+@option{--ask-cert-level}), "L" for a local or non-exportable
+signature (see @option{--lsign-key}), "R" for a nonRevocable signature
+(see the @option{--edit-key} command "nrsign"), "P" for a signature
+that contains a policy URL (see @option{--cert-policy-url}), "N" for a
+signature that contains a notation (see @option{--cert-notation}), "X"
+for an eXpired signature (see @option{--ask-cert-expire}), and the
+numbers 1-9 or "T" for 10 and above to indicate trust signature levels
+(see the @option{--edit-key} command "tsign").
+
@item --locate-keys
@opindex locate-keys
List all keys (or the specified ones) along with their
fingerprints. This is the same output as @option{--list-keys} but with
the additional output of a line with the fingerprint. May also be
-combined with @option{--list-sigs} or @option{--check-sigs}. If this
+combined with @option{--check-signatures}. If this
command is given twice, the fingerprints of all secondary keys are
listed too. This command also forces pretty printing of fingerprints
if the keyid format has been set to "none".
this command may change with new releases.
-@item --card-edit
+@item --edit-card
+@opindex edit-card
+@itemx --card-edit
@opindex card-edit
Present a menu to work with a smartcard. The subcommand "help" provides
an overview on available commands. For a detailed description, please
@opindex change-pin
Present a menu to allow changing the PIN of a smartcard. This
functionality is also available as the subcommand "passwd" with the
-@option{--card-edit} command.
+@option{--edit-card} command.
-@item --delete-keys @code{name}
-@itemx --delete-keys @code{name}
+@item --delete-keys @var{name}
+@opindex delete-keys
Remove key from the public keyring. In batch mode either @option{--yes} is
required or the key must be specified by fingerprint. This is a
safeguard against accidental deletion of multiple keys.
-@item --delete-secret-keys @code{name}
+@item --delete-secret-keys @var{name}
@opindex delete-secret-keys
-gRemove key from the secret keyring. In batch mode the key must be
+Remove key from the secret keyring. In batch mode the key must be
specified by fingerprint. The option @option{--yes} can be used to
advice gpg-agent not to request a confirmation. This extra
-pre-caution is done because @command{gpg} can't be sure that the
+pre-caution is done because @command{@gpgname} can't be sure that the
secret key (as controlled by gpg-agent) is only used for the given
OpenPGP public key.
-@item --delete-secret-and-public-key @code{name}
+@item --delete-secret-and-public-key @var{name}
@opindex delete-secret-and-public-key
Same as @option{--delete-key}, but if a secret key exists, it will be
removed first. In batch mode the key must be specified by fingerprint.
file given with option @option{--output}. Use together with
@option{--armor} to mail those keys.
-@item --send-keys @code{key IDs}
+@item --send-keys @var{keyIDs}
@opindex send-keys
Similar to @option{--export} but sends the keys to a keyserver.
-Fingerprints may be used instead of key IDs. Option @option{--keyserver}
-must be used to give the name of this keyserver. Don't send your
-complete keyring to a keyserver --- select only those keys which are new
-or changed by you. If no key IDs are given, @command{gpg} does nothing.
+Fingerprints may be used instead of key IDs. Option
+@option{--keyserver} must be used to give the name of this
+keyserver. Don't send your complete keyring to a keyserver --- select
+only those keys which are new or changed by you. If no @var{keyIDs}
+are given, @command{@gpgname} does nothing.
@item --export-secret-keys
@itemx --export-secret-subkeys
Same as @option{--export}, but exports the secret keys instead. The
exported keys are written to STDOUT or to the file given with option
@option{--output}. This command is often used along with the option
-@option{--armor} to allow easy printing of the key for paper backup;
-however the external tool @command{paperkey} does a better job for
+@option{--armor} to allow for easy printing of the key for paper backup;
+however the external tool @command{paperkey} does a better job of
creating backups on paper. Note that exporting a secret key can be a
-security risk if the exported keys are send over an insecure channel.
+security risk if the exported keys are sent over an insecure channel.
The second form of the command has the special property to render the
secret part of the primary key useless; this is a GNU extension to
OpenPGP and other implementations can not be expected to successfully
-import such a key. Its intended use is to generated a full key with
-an additional signing subkey on a dedicated machine and then using
-this command to export the key without the primary key to the main
-machine.
+import such a key. Its intended use is in generating a full key with
+an additional signing subkey on a dedicated machine. This command
+then exports the key without the primary key to the main machine.
GnuPG may ask you to enter the passphrase for the key. This is
-required because the internal protection method of the secret key is
+required, because the internal protection method of the secret key is
different from the one specified by the OpenPGP protocol.
@item --export-ssh-key
which does not insert new keys but does only the merging of new
signatures, user-IDs and subkeys.
-@item --recv-keys @code{key IDs}
+@item --receive-keys @var{keyIDs}
+@opindex receive-keys
+@itemx --recv-keys @var{keyIDs}
@opindex recv-keys
-Import the keys with the given key IDs from a keyserver. Option
+Import the keys with the given @var{keyIDs} from a keyserver. Option
@option{--keyserver} must be used to give the name of this keyserver.
@item --refresh-keys
name of the keyserver for all keys that do not have preferred keyservers
set (see @option{--keyserver-options honor-keyserver-url}).
-@item --search-keys @code{names}
+@item --search-keys @var{names}
@opindex search-keys
-Search the keyserver for the given names. Multiple names given here will
+Search the keyserver for the given @var{names}. Multiple names given here will
be joined together to create the search string for the keyserver.
Option @option{--keyserver} must be used to give the name of this
keyserver. Keyservers that support different search methods allow using
different keyserver types support different search methods. Currently
only LDAP supports them all.
-@item --fetch-keys @code{URIs}
+@item --fetch-keys @var{URIs}
@opindex fetch-keys
-Retrieve keys located at the specified URIs. Note that different
+Retrieve keys located at the specified @var{URIs}. Note that different
installations of GnuPG may support different protocols (HTTP, FTP,
LDAP, etc.). When using HTTPS the system provided root certificates
are used by this command.
Update the trustdb with the ownertrust values stored in @code{files} (or
STDIN if not given); existing values will be overwritten. In case of a
severely damaged trustdb and if you have a recent backup of the
-ownertrust values (e.g. in the file @file{otrust.txt}, you may re-create
+ownertrust values (e.g. in the file @file{otrust.txt}), you may re-create
the trustdb using these commands:
@c man:.RS
@example
to create signature caches in the keyring. It might be handy in other
situations too.
-@item --print-md @code{algo}
+@item --print-md @var{algo}
@itemx --print-mds
@opindex print-md
-Print message digest of algorithm ALGO for all given files or STDIN.
-With the second form (or a deprecated "*" as algo) digests for all
+Print message digest of algorithm @var{algo} for all given files or STDIN.
+With the second form (or a deprecated "*" for @var{algo}) digests for all
available algorithms are printed.
-@item --gen-random @code{0|1|2} @code{count}
+@item --gen-random @var{0|1|2} @var{count}
@opindex gen-random
Emit @var{count} random bytes of the given quality level 0, 1 or 2. If
@var{count} is not given or zero, an endless sequence of random bytes
base64 encoded. PLEASE, don't use this command unless you know what
you are doing; it may remove precious entropy from the system!
-@item --gen-prime @code{mode} @code{bits}
+@item --gen-prime @var{mode} @var{bits}
@opindex gen-prime
-Use the source, Luke :-). The output format is still subject to change.
+Use the source, Luke :-). The output format is subject to change
+with ant release.
@item --enarmor
Pack or unpack an arbitrary input into/from an OpenPGP ASCII armor.
This is a GnuPG extension to OpenPGP and in general not very useful.
-@item --tofu-policy @code{auto|good|unknown|bad|ask} @code{key...}
+@item --tofu-policy @{auto|good|unknown|bad|ask@} @var{keys}
@opindex tofu-policy
Set the TOFU policy for all the bindings associated with the specified
-keys. For more information about the meaning of the policies,
-@pxref{trust-model-tofu}. The keys may be specified either by their
+@var{keys}. For more information about the meaning of the policies,
+@pxref{trust-model-tofu}. The @var{keys} may be specified either by their
fingerprint (preferred) or their keyid.
@c @item --server
@node OpenPGP Key Management
@subsection How to manage your keys
-This section explains the main commands for key management
+This section explains the main commands for key management.
@table @gnupgtabopt
-@item --quick-gen-key @code{user-id} [@code{algo} [@code{usage} [@code{expire}]]]
-@opindex quick-gen-key
+@item --quick-generate-key @var{user-id} [@var{algo} [@var{usage} [@var{expire}]]]
+@opindex quick-generate-key
This is a simple command to generate a standard key with one user id.
-In contrast to @option{--gen-key} the key is generated directly
+In contrast to @option{--generate-key} the key is generated directly
without the need to answer a bunch of prompts. Unless the option
@option{--yes} is given, the key creation will be canceled if the
-given user id already exists in the key ring.
+given user id already exists in the keyring.
If invoked directly on the console without any special options an
answer to a ``Continue?'' style confirmation prompt is required. In
-case the user id already exists in the key ring a second prompt to
+case the user id already exists in the keyring a second prompt to
force the creation of the key will show up.
-If any of the optional arguments are given, only the primary key is
-created and no prompts are shown. For a description of these optional
-arguments see the command @code{--quick-addkey}. The @code{usage}
-accepts also the value ``cert'' which can be used to create a
-certification only primary key; the default is to a create
-certification and signing key.
+If @var{algo} or @var{usage} are given, only the primary key is
+created and no prompts are shown. To specify an expiration date but
+still create a primary and subkey use ``default'' or
+``future-default'' for @var{algo} and ``default'' for @var{usage}.
+For a description of these optional arguments see the command
+@code{--quick-add-key}. The @var{usage} accepts also the value
+``cert'' which can be used to create a certification only primary key;
+the default is to a create certification and signing key.
+
+The @var{expire} argument can be used to specify an expiration date
+for the key. Several formats are supported; commonly the ISO formats
+``YYYY-MM-DD'' or ``YYYYMMDDThhmmss'' are used. To make the key
+expire in N seconds, N days, N weeks, N months, or N years use
+``seconds=N'', ``Nd'', ``Nw'', ``Nm'', or ``Ny'' respectively. Not
+specifying a value, or using ``-'' results in a key expiring in a
+reasonable default interval. The values ``never'', ``none'' can be
+used for no expiration date.
If this command is used with @option{--batch},
@option{--pinentry-mode} has been set to @code{loopback}, and one of
for it. To create a key without any protection @code{--passphrase ''}
may be used.
-@item --quick-addkey @code{fpr} [@code{algo} [@code{usage} [@code{expire}]]]
-@opindex quick-addkey
+@item --quick-set-expire @var{fpr} @var{expire} [*|@var{subfprs}]
+@opindex quick-set-expire
+With two arguments given, directly set the expiration time of the
+primary key identified by @var{fpr} to @var{expire}. To remove the
+expiration time @code{0} can be used. With three arguments and the
+third given as an asterisk, the expiration time of all non-revoked and
+not yet expired subkeys are set to @var{expire}. With more than two
+arguments and a list of fingerprints given for @var{subfprs}, all
+non-revoked subkeys matching these fingerprints are set to
+@var{expire}.
+
+
+@item --quick-add-key @var{fpr} [@var{algo} [@var{usage} [@var{expire}]]]
+@opindex quick-add-key
Directly add a subkey to the key identified by the fingerprint
-@code{fpr}. Without the optional arguments an encryption subkey is
+@var{fpr}. Without the optional arguments an encryption subkey is
added. If any of the arguments are given a more specific subkey is
added.
-@code{algo} may be any of the supported algorithms or curve names given
-in the format as used by key listings. To use the default algorithm
-the string ``default'' or ``-'' can be used. Supported algorithms are
-``rsa'', ``dsa'', ``elg'', ``ed25519'', ``cv25519'', and other ECC
-curves. For example the string ``rsa'' adds an RSA key with the
-default key length; a string ``rsa4096'' requests that the key length
-is 4096 bits.
-
-Depending on the given @code{algo} the subkey may either be an
+@var{algo} may be any of the supported algorithms or curve names
+given in the format as used by key listings. To use the default
+algorithm the string ``default'' or ``-'' can be used. Supported
+algorithms are ``rsa'', ``dsa'', ``elg'', ``ed25519'', ``cv25519'',
+and other ECC curves. For example the string ``rsa'' adds an RSA key
+with the default key length; a string ``rsa4096'' requests that the
+key length is 4096 bits. The string ``future-default'' is an alias
+for the algorithm which will likely be used as default algorithm in
+future versions of gpg.
+
+Depending on the given @var{algo} the subkey may either be an
encryption subkey or a signing subkey. If an algorithm is capable of
-signing and encryption and such a subkey is desired, a @code{usage}
+signing and encryption and such a subkey is desired, a @var{usage}
string must be given. This string is either ``default'' or ``-'' to
-keep the default or a comma delimited list of keywords: ``sign'' for a
-signing subkey, ``auth'' for an authentication subkey, and ``encr''
-for an encryption subkey (``encrypt'' can be used as alias for
-``encr''). The valid combinations depend on the algorithm.
-
-The @code{expire} argument can be used to specify an expiration date
-for the subkey. Several formats are supported; commonly the ISO
-YYYY-MM-DD format is used. The values ``never'', ``none'', or ``-''
-can be used for no expiration date.
-
-@item --gen-key
+keep the default or a comma delimited list (or space delimited list)
+of keywords: ``sign'' for a signing subkey, ``auth'' for an
+authentication subkey, and ``encr'' for an encryption subkey
+(``encrypt'' can be used as alias for ``encr''). The valid
+combinations depend on the algorithm.
+
+The @var{expire} argument can be used to specify an expiration date
+for the key. Several formats are supported; commonly the ISO formats
+``YYYY-MM-DD'' or ``YYYYMMDDThhmmss'' are used. To make the key
+expire in N seconds, N days, N weeks, N months, or N years use
+``seconds=N'', ``Nd'', ``Nw'', ``Nm'', or ``Ny'' respectively. Not
+specifying a value, or using ``-'' results in a key expiring in a
+reasonable default interval. The values ``never'', ``none'' can be
+used for no expiration date.
+
+@item --generate-key
+@opindex generate-key
+@itemx --gen-key
@opindex gen-key
Generate a new key pair using the current default parameters. This is
the standard command to create a new key. In addition to the key a
revocation certificate is created and stored in the
@file{openpgp-revocs.d} directory below the GnuPG home directory.
-@item --full-gen-key
-@opindex gen-key
+@item --full-generate-key
+@opindex full-generate-key
+@itemx --full-gen-key
+@opindex full-gen-key
Generate a new key pair with dialogs for all options. This is an
-extended version of @option{--gen-key}.
+extended version of @option{--generate-key}.
There is also a feature which allows you to create keys in batch
mode. See the manual section ``Unattended key generation'' on how
to use this.
-@item --gen-revoke @code{name}
+@item --generate-revocation @var{name}
+@opindex generate-revocation
+@itemx --gen-revoke @var{name}
@opindex gen-revoke
Generate a revocation certificate for the complete key. To only revoke
a subkey or a key signature, use the @option{--edit} command.
to a file which is then send to frequent communication partners.
-@item --desig-revoke @code{name}
+@item --generate-designated-revocation @var{name}
+@opindex generate-designated-revocation
+@itemx --desig-revoke @var{name}
@opindex desig-revoke
Generate a designated revocation certificate for a key. This allows a
user (with the permission of the keyholder) to revoke someone else's
@c ******** Begin Edit-key Options **********
@table @asis
- @item uid @code{n}
+ @item uid @var{n}
@opindex keyedit:uid
- Toggle selection of user ID or photographic user ID with index @code{n}.
+ Toggle selection of user ID or photographic user ID with index @var{n}.
Use @code{*} to select all and @code{0} to deselect all.
- @item key @code{n}
+ @item key @var{n}
@opindex keyedit:key
- Toggle selection of subkey with index @code{n} or key ID @code{n}.
+ Toggle selection of subkey with index @var{n} or key ID @var{n}.
Use @code{*} to select all and @code{0} to deselect all.
@item sign
@opindex keyedit:sign
- Make a signature on key of user @code{name} If the key is not yet
- signed by the default user (or the users given with -u), the program
+ Make a signature on key of user @code{name}. If the key is not yet
+ signed by the default user (or the users given with @option{-u}), the program
displays the information of the key again, together with its
fingerprint and asks whether it should be signed. This question is
repeated for all users specified with
- -u.
+ @option{-u}.
@item lsign
@opindex keyedit:lsign
not already included in the preference list. In addition, the
preferred keyserver and signature notations (if any) are shown.
- @item setpref @code{string}
+ @item setpref @var{string}
@opindex keyedit:setpref
- Set the list of user ID preferences to @code{string} for all (or just
+ Set the list of user ID preferences to @var{string} for all (or just
the selected) user IDs. Calling setpref with no arguments sets the
preference list to the default (either built-in or set via
@option{--default-preference-list}), and calling setpref with "none"
from the card - if the card gets broken your secret key will be lost
unless you have a backup somewhere.
- @item bkuptocard @code{file}
+ @item bkuptocard @var{file}
@opindex keyedit:bkuptocard
- Restore the given file to a card. This command may be used to restore a
+ Restore the given @var{file} to a card. This command may be used to restore a
backup key (as generated during card initialization) to a new card. In
almost all cases this will be the encryption key. You should use this
command only with the corresponding public key and make sure that the
@opindex keyedit:delkey
Remove a subkey (secondary key). Note that it is not possible to retract
a subkey, once it has been send to the public (i.e. to a keyserver). In
- that case you better use @code{revkey}.
+ that case you better use @code{revkey}. Also note that this only
+ deletes the public part of a key.
@item revkey
@opindex keyedit:revkey
currently have them. Cross-certification signatures protect against a
subtle attack against signing subkeys. See
@option{--require-cross-certification}. All new keys generated have
- this signature by default, so this option is only useful to bring
+ this signature by default, so this command is only useful to bring
older keys up to date.
@item save
@opindex keyedit:save
- Save all changes to the key rings and quit.
+ Save all changes to the keyrings and quit.
@item quit
@opindex keyedit:quit
Quit the program without updating the
- key rings.
+ keyrings.
@end table
@c man:.RS
@end table
@c ******** End Edit-key Options **********
-@item --sign-key @code{name}
+@item --sign-key @var{name}
@opindex sign-key
Signs a public key with your secret key. This is a shortcut version of
the subcommand "sign" from @option{--edit}.
-@item --lsign-key @code{name}
+@item --lsign-key @var{name}
@opindex lsign-key
Signs a public key with your secret key but marks it as
non-exportable. This is a shortcut version of the subcommand "lsign"
from @option{--edit-key}.
-@item --quick-sign-key @code{fpr} [@code{names}]
-@itemx --quick-lsign-key @code{fpr} [@code{names}]
+@item --quick-sign-key @var{fpr} [@var{names}]
+@itemx --quick-lsign-key @var{fpr} [@var{names}]
@opindex quick-sign-key
@opindex quick-lsign-key
Directly sign a key from the passphrase without any further user
-interaction. The @code{fpr} must be the verified primary fingerprint
-of a key in the local keyring. If no @code{names} are given, all
-useful user ids are signed; with given [@code{names}] only useful user
+interaction. The @var{fpr} must be the verified primary fingerprint
+of a key in the local keyring. If no @var{names} are given, all
+useful user ids are signed; with given [@var{names}] only useful user
ids matching one of theses names are signed. By default, or if a name
is prefixed with a '*', a case insensitive substring match is used.
If a name is prefixed with a '=' a case sensitive exact match is done.
Its intended use is to help unattended key signing by utilizing a list
of verified fingerprints.
-@item --quick-adduid @var{user-id} @var{new-user-id}
-@opindex quick-adduid
+@item --quick-add-uid @var{user-id} @var{new-user-id}
+@opindex quick-add-uid
This command adds a new user id to an existing key. In contrast to
the interactive sub-command @code{adduid} of @option{--edit-key} the
@var{new-user-id} is added verbatim with only leading and trailing
white space removed, it is expected to be UTF-8 encoded, and no checks
on its form are applied.
-@item --quick-revuid @var{user-id} @var{user-id-to-revoke}
-@opindex quick-revuid
-This command revokes a User ID on an existing key. It cannot be used
-to revoke the last User ID on key (some non-revoked User ID must
+@item --quick-revoke-uid @var{user-id} @var{user-id-to-revoke}
+@opindex quick-revoke-uid
+This command revokes a user ID on an existing key. It cannot be used
+to revoke the last user ID on key (some non-revoked user ID must
remain), with revocation reason ``User ID is no longer valid''. If
you want to specify a different revocation reason, or to supply
supplementary revocation text, you should use the interactive
sub-command @code{revuid} of @option{--edit-key}.
-@item --passwd @var{user_id}
+@item --quick-set-primary-uid @var{user-id} @var{primary-user-id}
+@opindex quick-set-primary-uid
+This command sets or updates the primary user ID flag on an existing
+key. @var{user-id} specifies the key and @var{primary-user-id} the
+user ID which shall be flagged as the primary user ID. The primary
+user ID flag is removed from all other user ids and the timestamp of
+all affected self-signatures is set one second ahead.
+
+
+@item --change-passphrase @var{user-id}
+@opindex change-passphrase
+@itemx --passwd @var{user-id}
@opindex passwd
Change the passphrase of the secret key belonging to the certificate
-specified as @var{user_id}. This is a shortcut for the sub-command
+specified as @var{user-id}. This is a shortcut for the sub-command
@code{passwd} of the edit key menu.
@end table
* GPG Input and Output:: Input and Output.
* OpenPGP Options:: OpenPGP protocol specific options.
* Compliance Options:: Compliance options.
-* GPG Esoteric Options:: Doing things one usually don't want to do.
+* GPG Esoteric Options:: Doing things one usually doesn't want to do.
* Deprecated Options:: Deprecated options.
@end menu
STDIN (in particular if gpg figures that the input is a
detached signature and no data file has been specified). Thus if you
do not want to feed data via STDIN, you should connect STDIN to
-@file{/dev/null}.
+g@file{/dev/null}.
+
+It is highly recommended to use this option along with the options
+@option{--status-fd} and @option{--with-colons} for any unattended use of
+@command{gpg}.
@item --no-tty
@opindex no-tty
Assume "no" on most questions.
-@item --list-options @code{parameters}
+@item --list-options @var{parameters}
@opindex list-options
This is a space or comma delimited string that gives options used when
listing keys and signatures (that is, @option{--list-keys},
-@option{--list-sigs}, @option{--list-public-keys},
+@option{--check-signatures}, @option{--list-public-keys},
@option{--list-secret-keys}, and the @option{--edit-key} functions).
Options can be prepended with a @option{no-} (after the two dashes) to
give the opposite meaning. The options are:
@item show-photos
@opindex list-options:show-photos
- Causes @option{--list-keys}, @option{--list-sigs},
+ Causes @option{--list-keys}, @option{--check-signatures},
@option{--list-public-keys}, and @option{--list-secret-keys} to
display any photo IDs attached to the key. Defaults to no. See also
@option{--photo-viewer}. Does not work with @option{--with-colons}:
@item show-policy-urls
@opindex list-options:show-policy-urls
- Show policy URLs in the @option{--list-sigs} or @option{--check-sigs}
+ Show policy URLs in the @option{--check-signatures}
listings. Defaults to no.
@item show-notations
@opindex list-options:show-std-notations
@opindex list-options:show-user-notations
Show all, IETF standard, or user-defined signature notations in the
- @option{--list-sigs} or @option{--check-sigs} listings. Defaults to no.
+ @option{--check-signatures} listings. Defaults to no.
@item show-keyserver-urls
@opindex list-options:show-keyserver-urls
- Show any preferred keyserver URL in the @option{--list-sigs} or
- @option{--check-sigs} listings. Defaults to no.
+ Show any preferred keyserver URL in the
+ @option{--check-signatures} listings. Defaults to no.
@item show-uid-validity
@opindex list-options:show-uid-validity
@item show-sig-expire
@opindex list-options:show-sig-expire
- Show signature expiration dates (if any) during @option{--list-sigs} or
- @option{--check-sigs} listings. Defaults to no.
+ Show signature expiration dates (if any) during
+ @option{--check-signatures} listings. Defaults to no.
@item show-sig-subpackets
@opindex list-options:show-sig-subpackets
optional argument list of the subpackets to list. If no argument is
passed, list all subpackets. Defaults to no. This option is only
meaningful when using @option{--with-colons} along with
- @option{--list-sigs} or @option{--check-sigs}.
+ @option{--check-signatures}.
@end table
-@item --verify-options @code{parameters}
+@item --verify-options @var{parameters}
@opindex verify-options
This is a space or comma delimited string that gives options used when
verifying signatures. Options can be prepended with a `no-' to give
@itemx --disable-large-rsa
@opindex enable-large-rsa
@opindex disable-large-rsa
-With --gen-key and --batch, enable the creation of RSA secret keys as
+With --generate-key and --batch, enable the creation of RSA secret keys as
large as 8192 bit. Note: 8192 bit is more than is generally
recommended. These large keys don't significantly improve security,
but they are more expensive to use, and their signatures and
that older versions of GnuPG also required this flag to allow the
generation of DSA larger than 1024 bit.
-@item --photo-viewer @code{string}
+@item --photo-viewer @var{string}
@opindex photo-viewer
This is the command line that should be run to view a photo ID. "%i"
will be expanded to a filename containing the photo. "%I" does the
STDIN". Note that if your image viewer program is not secure, then
executing it from GnuPG does not make it secure.
-@item --exec-path @code{string}
+@item --exec-path @var{string}
@opindex exec-path
@efindex PATH
Sets a list of directories to search for photo viewers and keyserver
Note, that on W32 system this value is ignored when searching for
keyserver helpers.
-@item --keyring @code{file}
+@item --keyring @var{file}
@opindex keyring
-Add @code{file} to the current list of keyrings. If @code{file} begins
+Add @var{file} to the current list of keyrings. If @var{file} begins
with a tilde and a slash, these are replaced by the $HOME directory. If
the filename does not contain a slash, it is assumed to be in the GnuPG
home directory ("~/.gnupg" if @option{--homedir} or $GNUPGHOME is not
use the specified keyring alone, use @option{--keyring} along with
@option{--no-default-keyring}.
-If the the option @option{--no-keyring} has been used no keyrings will
+If the option @option{--no-keyring} has been used no keyrings will
be used at all.
-@item --secret-keyring @code{file}
+@item --secret-keyring @var{file}
@opindex secret-keyring
This is an obsolete option and ignored. All secret keys are stored in
the @file{private-keys-v1.d} directory below the GnuPG home directory.
-@item --primary-keyring @code{file}
+@item --primary-keyring @var{file}
@opindex primary-keyring
-Designate @code{file} as the primary public keyring. This means that
+Designate @var{file} as the primary public keyring. This means that
newly imported keys (via @option{--import} or keyserver
@option{--recv-from}) will go to this keyring.
-@item --trustdb-name @code{file}
+@item --trustdb-name @var{file}
@opindex trustdb-name
-Use @code{file} instead of the default trustdb. If @code{file} begins
+Use @var{file} instead of the default trustdb. If @var{file} begins
with a tilde and a slash, these are replaced by the $HOME directory. If
the filename does not contain a slash, it is assumed to be in the GnuPG
home directory (@file{~/.gnupg} if @option{--homedir} or $GNUPGHOME is
@include opt-homedir.texi
-@item --display-charset @code{name}
+@item --display-charset @var{name}
@opindex display-charset
Set the name of the native character set. This is used to convert
some informational strings like user IDs to the proper UTF-8 encoding.
encrypted or signed; GnuPG does not recode user-supplied data. If
this option is not used, the default character set is determined from
the current locale. A verbosity level of 3 shows the chosen set.
-Valid values for @code{name} are:
+Valid values for @var{name} are:
@table @asis
@item koi8-r
@opindex display-charset:koi8-r
- The usual Russian set (rfc1489).
+ The usual Russian set (RFC-1489).
@item utf-8
@opindex display-charset:utf-8
@item --utf8-strings
@itemx --no-utf8-strings
@opindex utf8-strings
-Assume that command line arguments are given as UTF8 strings. The
+Assume that command line arguments are given as UTF-8 strings. The
default (@option{--no-utf8-strings}) is to assume that arguments are
encoded in the character set as specified by
@option{--display-charset}. These options affect all following
arguments. Both options may be used multiple times.
@anchor{gpg-option --options}
-@item --options @code{file}
+@item --options @var{file}
@opindex options
-Read options from @code{file} and do not try to read them from the
+Read options from @var{file} and do not try to read them from the
default options file in the homedir (see @option{--homedir}). This
option is ignored if used in an options file.
before an attempt to open an option file. Using this option will also
prevent the creation of a @file{~/.gnupg} homedir.
-@item -z @code{n}
-@itemx --compress-level @code{n}
-@itemx --bzip2-compress-level @code{n}
+@item -z @var{n}
+@itemx --compress-level @var{n}
+@itemx --bzip2-compress-level @var{n}
@opindex compress-level
@opindex bzip2-compress-level
-Set compression level to @code{n} for the ZIP and ZLIB compression
+Set compression level to @var{n} for the ZIP and ZLIB compression
algorithms. The default is to use the default compression level of zlib
(normally 6). @option{--bzip2-compress-level} sets the compression level
for the BZIP2 compression algorithm (defaulting to 6 as well). This is a
different option from @option{--compress-level} since BZIP2 uses a
significant amount of memory for each additional compression level.
-@option{-z} sets both. A value of 0 for @code{n} disables compression.
+@option{-z} sets both. A value of 0 for @var{n} disables compression.
@item --bzip2-decompress-lowmem
@opindex bzip2-decompress-lowmem
used. @option{--no-ask-cert-level} disables this option. This option
defaults to no.
-@item --default-cert-level @code{n}
+@item --default-cert-level @var{n}
@opindex default-cert-level
The default to use for the check level when signing a key.
disregards level 1 signatures. Note that level 0 "no particular
claim" signatures are always accepted.
-@item --trusted-key @code{long key ID}
+@item --trusted-key @var{long key ID}
@opindex trusted-key
Assume that the specified key (which must be given
as a full 8 byte key ID) is as trustworthy as one of
online but still want to be able to check the validity of a given
recipient's or signator's key.
-@item --trust-model @code{pgp|classic|tofu|tofu+pgp|direct|always|auto}
+@item --trust-model @{pgp|classic|tofu|tofu+pgp|direct|always|auto@}
@opindex trust-model
Set what trust model GnuPG should follow. The models are:
@table @asis
@item pgp
- @opindex trust-mode:pgp
+ @opindex trust-model:pgp
This is the Web of Trust combined with trust signatures as used in PGP
5.x and later. This is the default trust model when creating a new
trust database.
@item classic
- @opindex trust-mode:classic
+ @opindex trust-model:classic
This is the standard Web of Trust as introduced by PGP 2.
@item tofu
- @opindex trust-mode:tofu
+ @opindex trust-model:tofu
@anchor{trust-model-tofu}
TOFU stands for Trust On First Use. In this trust model, the first
- time a key is seen, it is memorized. If later another key is seen
- with a user id with the same email address, a warning is displayed
- indicating that there is a conflict and that the key might be a
- forgery and an attempt at a man-in-the-middle attack.
+ time a key is seen, it is memorized. If later another key with a
+ user id with the same email address is seen, both keys are marked as
+ suspect. In that case, the next time either is used, a warning is
+ displayed describing the conflict, why it might have occurred
+ (either the user generated a new key and failed to cross sign the
+ old and new keys, the key is forgery, or a man-in-the-middle attack
+ is being attempted), and the user is prompted to manually confirm
+ the validity of the key in question.
Because a potential attacker is able to control the email address
and thereby circumvent the conflict detection algorithm by using an
keys and email addresses (which are extracted from user ids and
normalized). There are five policies, which can be set manually
using the @option{--tofu-policy} option. The default policy can be
- set using the @option{--tofu-default-policy} policy.
+ set using the @option{--tofu-default-policy} option.
The TOFU policies are: @code{auto}, @code{good}, @code{unknown},
@code{bad} and @code{ask}. The @code{auto} policy is used by
@code{undefined} trust level is returned.
@item tofu+pgp
- @opindex trust-mode:tofu+pgp
+ @opindex trust-model:tofu+pgp
This trust model combines TOFU with the Web of Trust. This is done
by computing the trust level for each model and then taking the
maximum trust level where the trust levels are ordered as follows:
which some security-conscious users don't like.
@item direct
- @opindex trust-mode:direct
+ @opindex trust-model:direct
Key validity is set directly by the user and not calculated via the
- Web of Trust.
+ Web of Trust. This model is solely based on the key and does
+ not distinguish user IDs. Note that when changing to another trust
+ model the trust values assigned to a key are transformed into
+ ownertrust values, which also indicate how you trust the owner of
+ the key to sign other keys.
@item always
- @opindex trust-mode:always
+ @opindex trust-model:always
Skip key validation and assume that used keys are always fully
valid. You generally won't use this unless you are using some
external validation scheme. This option also suppresses the
disabled keys.
@item auto
- @opindex trust-mode:auto
+ @opindex trust-model:auto
Select the trust model depending on whatever the internal trust
database says. This is the default model if such a database already
exists.
@end table
-@item --auto-key-locate @code{parameters}
+@item --auto-key-locate @var{mechanisms}
@itemx --no-auto-key-locate
@opindex auto-key-locate
GnuPG can automatically locate and retrieve keys as needed using this
-option. This happens when encrypting to an email address (in the
-"user@@example.com" form), and there are no user@@example.com keys on
-the local keyring. This option takes any number of the following
-mechanisms, in the order they are to be tried:
+option. This happens when encrypting to an email address (in the
+"user@@example.com" form), and there are no "user@@example.com" keys
+on the local keyring. This option takes any number of the mechanisms
+listed below, in the order they are to be tried. Instead of listing
+the mechanisms as comma delimited arguments, the option may also be
+given several times to add more mechanism. The option
+@option{--no-auto-key-locate} or the mechanism "clear" resets the
+list. The default is "local,wkd".
@table @asis
@item cert
- Locate a key using DNS CERT, as specified in rfc4398.
+ Locate a key using DNS CERT, as specified in RFC-4398.
@item pka
Locate a key using DNS PKA.
@item wkd
Locate a key using the Web Key Directory protocol.
- This is an experimental method and semantics may change.
@item ldap
Using DNS Service Discovery, check the domain in question for any LDAP
@end table
+
@item --auto-key-retrieve
@itemx --no-auto-key-retrieve
@opindex auto-key-retrieve
@opindex no-auto-key-retrieve
-This option enables the automatic retrieving of keys from a keyserver
-when verifying signatures made by keys that are not on the local
-keyring.
+These options enable or disable the automatic retrieving of keys from
+a keyserver when verifying signatures made by keys that are not on the
+local keyring. The default is @option{--no-auto-key-retrieve}.
If the method "wkd" is included in the list of methods given to
-@option{auto-key-locate}, the Signer's User ID is part of the
+@option{auto-key-locate}, the signer's user ID is part of the
signature, and the option @option{--disable-signer-uid} is not used,
the "wkd" method may also be used to retrieve a key.
tell both your IP address and the time when you verified the
signature.
-@item --keyid-format @code{none|short|0xshort|long|0xlong}
+@item --keyid-format @{none|short|0xshort|long|0xlong@}
@opindex keyid-format
Select how to display key IDs. "none" does not show the key ID at all
but shows the fingerprint in a separate line. "short" is the
"0x" at the beginning of the key ID, as in 0x99242560. Note that this
option is ignored if the option @option{--with-colons} is used.
-@item --keyserver @code{name}
+@item --keyserver @var{name}
@opindex keyserver
This option is deprecated - please use the @option{--keyserver} in
@file{dirmngr.conf} instead.
-Use @code{name} as your keyserver. This is the server that
-@option{--recv-keys}, @option{--send-keys}, and @option{--search-keys}
+Use @var{name} as your keyserver. This is the server that
+@option{--receive-keys}, @option{--send-keys}, and @option{--search-keys}
will communicate with to receive keys from, send keys to, and search for
-keys on. The format of the @code{name} is a URI:
+keys on. The format of the @var{name} is a URI:
`scheme:[//]keyservername[:port]' The scheme is the type of keyserver:
"hkp" for the HTTP (or compatible) keyservers, "ldap" for the LDAP
keyservers, or "mailto" for the Graff email keyserver. Note that your
@code{hkp://keys.gnupg.net} uses round robin DNS to give a different
keyserver each time you use it.
-@item --keyserver-options @code{name=value}
+@item --keyserver-options @{@var{name}=@var{value}@}
@opindex keyserver-options
This is a space or comma delimited string that gives options for the
keyserver. Options can be prefixed with a `no-' to give the opposite
used with HKP keyservers.
@item auto-key-retrieve
- This is the same as the option @option{auto-key-retrieve}.
+ This is an obsolete alias for the option @option{auto-key-retrieve}.
+ Please do not use it; it will be removed in future versions..
@item honor-keyserver-url
When using @option{--refresh-keys}, if the key in question has a preferred
Tell the keyserver helper program how long (in seconds) to try and
perform a keyserver action before giving up. Note that performing
multiple actions at the same time uses this timeout value per action.
- For example, when retrieving multiple keys via @option{--recv-keys}, the
+ For example, when retrieving multiple keys via @option{--receive-keys}, the
timeout applies separately to each key retrieval, and not to the
- @option{--recv-keys} command as a whole. Defaults to 30 seconds.
+ @option{--receive-keys} command as a whole. Defaults to 30 seconds.
- @item http-proxy=@code{value}
- This options is deprecated.
+ @item http-proxy=@var{value}
+ This option is deprecated.
Set the proxy to use for HTTP and HKP keyservers.
This overrides any proxy defined in @file{dirmngr.conf}.
@end table
-@item --completes-needed @code{n}
+@item --completes-needed @var{n}
@opindex compliant-needed
Number of completely trusted users to introduce a new
key signer (defaults to 1).
-@item --marginals-needed @code{n}
+@item --marginals-needed @var{n}
@opindex marginals-needed
Number of marginally trusted users to introduce a new
key signer (defaults to 3)
-@item --tofu-default-policy @code{auto|good|unknown|bad|ask}
+@item --tofu-default-policy @{auto|good|unknown|bad|ask@}
@opindex tofu-default-policy
The default TOFU policy (defaults to @code{auto}). For more
-information about the meaning of this option, @xref{trust-model-tofu}.
+information about the meaning of this option, @pxref{trust-model-tofu}.
-@item --max-cert-depth @code{n}
+@item --max-cert-depth @var{n}
@opindex max-cert-depth
Maximum depth of a certification chain (default is 5).
@opindex no-sig-cache
Do not cache the verification status of key signatures.
Caching gives a much better performance in key listings. However, if
-you suspect that your public keyring is not save against write
+you suspect that your public keyring is not safe against write
modifications, you can use this option to disable the caching. It
probably does not make sense to disable it because all kind of damage
can be done if someone else has write access to your public keyring.
Specify a dirmngr program to be used for keyserver access. The
default value is @file{@value{BINDIR}/dirmngr}.
+@item --disable-dirmngr
+Entirely disable the use of the Dirmngr.
+
@item --no-autostart
@opindex no-autostart
Do not start the gpg-agent or the dirmngr if it has not yet been
@option{--enable-progress-filter} may be used to cleanly cancel long
running gpg operations.
-@item --limit-card-insert-tries @code{n}
+@item --limit-card-insert-tries @var{n}
@opindex limit-card-insert-tries
-With @code{n} greater than 0 the number of prompts asking to insert a
+With @var{n} greater than 0 the number of prompts asking to insert a
smartcard gets limited to N-1. Thus with a value of 1 gpg won't at
all ask to insert a card if none has been inserted at startup. This
option is useful in the configuration file in case an application does
@opindex recipient-file
This option is similar to @option{--recipient} except that it
encrypts to a key stored in the given file. @var{file} must be the
-name of a file containing exactly one key. @command{gpg} assumes that
+name of a file containing exactly one key. @command{@gpgname} assumes that
the key in this file is fully valid.
@item --hidden-recipient-file @var{file}
@opindex hidden-recipient-file
This option is similar to @option{--hidden-recipient} except that it
encrypts to a key stored in the given file. @var{file} must be the
-name of a file containing exactly one key. @command{gpg} assumes that
+name of a file containing exactly one key. @command{@gpgname} assumes that
the key in this file is fully valid.
-@item --encrypt-to @code{name}
+@item --encrypt-to @var{name}
@opindex encrypt-to
Same as @option{--recipient} but this one is intended for use in the
options file and may be used with your own user-id as an
user id. No trust checking is performed for these user ids and even
disabled keys can be used.
-@item --hidden-encrypt-to @code{name}
+@item --hidden-encrypt-to @var{name}
@opindex hidden-encrypt-to
Same as @option{--hidden-recipient} but this one is intended for use in the
options file and may be used with your own user-id as a hidden
Disable the use of all @option{--encrypt-to} and
@option{--hidden-encrypt-to} keys.
-@item --group @code{name=value1 }
+@item --group @{@var{name}=@var{value}@}
@opindex group
Sets up a named group, which is similar to aliases in email programs.
Any time the group name is a recipient (@option{-r} or
this option to prevent the shell from treating it as multiple
arguments.
-@item --ungroup @code{name}
+@item --ungroup @var{name}
@opindex ungroup
Remove a given entry from the @option{--group} list.
@item --output @var{file}
@itemx -o @var{file}
@opindex output
-Write output to @var{file}.
+Write output to @var{file}. To write to stdout use @code{-} as the
+filename.
-@item --max-output @code{n}
+@item --max-output @var{n}
@opindex max-output
This option sets a limit on the number of bytes that will be generated
when processing a file. Since OpenPGP supports various levels of
@opindex input-size-hint
This option can be used to tell GPG the size of the input data in
bytes. @var{n} must be a positive base-10 number. This option is
-only useful if the input is not taken from a file. GPG may use thos
+only useful if the input is not taken from a file. GPG may use this
hint to optimize its buffer allocation strategy. It is also used by
the @option{--status-fd} line ``PROGRESS'' to provide a value for
``total'' if that is not available by other means.
-@item --import-options @code{parameters}
+@item --key-origin @var{string}[,@var{url}]
+@opindex key-origin
+gpg can track the origin of a key. Certain origins are implicitly
+known (e.g. keyserver, web key directory) and set. For a standard
+import the origin of the keys imported can be set with this option.
+To list the possible values use "help" for @var{string}. Some origins
+can store an optional @var{url} argument. That URL can appended to
+@var{string} after a comma.
+
+@item --import-options @var{parameters}
@opindex import-options
This is a space or comma delimited string that gives options for
importing keys. Options can be prepended with a `no-' to give the
a formerly deleted key does not automatically gain an ownertrust
values merely due to import. On the other hand it is sometimes
necessary to re-import a trusted set of keys again but keeping
- already assigned ownertrust values. This can be achived by using
+ already assigned ownertrust values. This can be achieved by using
this option.
@item repair-pks-subkey-bug
that this cannot completely repair the damaged key as some crucial data
is removed by the keyserver, but it does at least give you back one
subkey. Defaults to no for regular @option{--import} and to yes for
- keyserver @option{--recv-keys}.
+ keyserver @option{--receive-keys}.
@item import-show
+ @itemx show-only
Show a listing of the key as imported right before it is stored.
This can be combined with the option @option{--dry-run} to only look
- at keys.
+ at keys; the option @option{show-only} is a shortcut for this
+ combination. Note that suffixes like '#' for "sec" and "sbb" lines
+ may or may not be printed.
@item import-export
Run the entire import code but instead of storing the key to the
on the keyring. This option is the same as running the @option{--edit-key}
command "clean" after import. Defaults to no.
+ @item repair-keys. After import, fix various problems with the
+ keys. For example, this reorders signatures, and strips duplicate
+ signatures. Defaults to yes.
+
@item import-minimal
Import the smallest key possible. This removes all signatures except
the most recent self-signature on each user ID. This option is the
same as running the @option{--edit-key} command "minimize" after import.
Defaults to no.
+
+ @item restore
+ @itemx import-restore
+ Import in key restore mode. This imports all data which is usually
+ skipped during import; including all GnuPG specific data. All other
+ contradicting options are overridden.
@end table
-@item --import-filter @code{@var{name}=@var{expr}}
-@itemx --export-filter @code{@var{name}=@var{expr}}
+@item --import-filter @{@var{name}=@var{expr}@}
+@itemx --export-filter @{@var{name}=@var{expr}@}
@opindex import-filter
@opindex export-filter
These options define an import/export filter which are applied to the
This filter will keep a user id packet and its dependent packets in
the keyblock if the expression evaluates to true.
+ @item drop-subkey
+ This filter drops the selected subkeys.
+ Currently only implemented for --export-filter.
+
@item drop-sig
This filter drops the selected key signatures on user ids.
- Self-signatures are not consideres.
+ Self-signatures are not considered.
Currently only implemented for --import-filter.
@end table
The addr-spec part of a user id with mailbox or the empty string.
(keep-uid)
+ @item key_algo
+ A number with the public key algorithm of a key or subkey packet.
+ (drop-subkey)
+
+ @item key_created
+ @itemx key_created_d
+ The first is the timestamp a public key or subkey packet was
+ created. The second is the same but given as an ISO string,
+ e.g. "2016-08-17". (drop-subkey)
+
@item primary
Boolean indicating whether the user id is the primary one. (keep-uid)
+ @item expired
+ Boolean indicating whether a user id (keep-uid), a key (drop-subkey), or a
+ signature (drop-sig) expired.
+
+ @item revoked
+ Boolean indicating whether a user id (keep-uid) or a key (drop-subkey) has
+ been revoked.
+
+ @item disabled
+ Boolean indicating whether a primary key is disabled. (not used)
+
+ @item secret
+ Boolean indicating whether a key or subkey is a secret one.
+ (drop-subkey)
+
@item sig_created
@itemx sig_created_d
The first is the timestamp a signature packet was created. The
- second is the same but given as an ISO string,
+ second is the same but given as an ISO date string,
e.g. "2016-08-17". (drop-sig)
@item sig_algo
@end table
-@item --export-options @code{parameters}
+@item --export-options @var{parameters}
@opindex export-options
This is a space or comma delimited string that gives options for
-exporting keys. Options can be prepended with a `no-' to give the
-opposite meaning. The options are:
+exporting keys. Options can be prepended with a `no-' to give the
+opposite meaning. The options are:
@table @asis
Defaults to no.
@item export-attributes
- Include attribute user IDs (photo IDs) while exporting. This is
- useful to export keys if they are going to be used by an OpenPGP
- program that does not accept attribute user IDs. Defaults to yes.
+ Include attribute user IDs (photo IDs) while exporting. Not
+ including attribute user IDs is useful to export keys that are going
+ to be used by an OpenPGP program that does not accept attribute user
+ IDs. Defaults to yes.
@item export-sensitive-revkeys
Include designated revoker information that was marked as
@c when the exported subkey is to be used on an unattended machine where
@c a passphrase doesn't necessarily make sense. Defaults to no.
+ @item backup
+ @itemx export-backup
+ Export for use as a backup. The exported data includes all data
+ which is needed to restore the key or keys later with GnuPG. The
+ format is basically the OpenPGP format but enhanced with GnuPG
+ specific data. All other contradicting options are overridden.
+
@item export-clean
Compact (remove all signatures from) user IDs on the key being
exported if the user IDs are not usable. Also, do not export any
Include the keygrip in the key listings. In @code{--with-colons} mode
this is implicitly enable for secret keys.
+@item --with-key-origin
+@opindex with-key-origin
+Include the locally held information on the origin and last update of
+a key in a key listing. In @code{--with-colons} mode this is always
+printed. This data is currently experimental and shall not be
+considered part of the stable API.
+
@item --with-wkd-hash
@opindex with-wkd-hash
-Print a Web Key Directory indentifier along with each user ID in key
+Print a Web Key Directory identifier along with each user ID in key
listings. This is an experimental feature and semantics may change.
@item --with-secret
@c ******** OPENPGP OPTIONS ****************
@c *******************************************
@node OpenPGP Options
-@subsection OpenPGP protocol specific options.
+@subsection OpenPGP protocol specific options
@table @gnupgtabopt
information can be helpful for verifier to locate the key; see
option @option{--auto-key-retrieve}.
-@item --personal-cipher-preferences @code{string}
+@item --personal-cipher-preferences @var{string}
@opindex personal-cipher-preferences
-Set the list of personal cipher preferences to @code{string}. Use
+Set the list of personal cipher preferences to @var{string}. Use
@command{@gpgname --version} to get a list of available algorithms,
and use @code{none} to set no preference at all. This allows the user
to safely override the algorithm chosen by the recipient key
all recipients. The most highly ranked cipher in this list is also
used for the @option{--symmetric} encryption command.
-@item --personal-digest-preferences @code{string}
+@item --personal-digest-preferences @var{string}
@opindex personal-digest-preferences
-Set the list of personal digest preferences to @code{string}. Use
+Set the list of personal digest preferences to @var{string}. Use
@command{@gpgname --version} to get a list of available algorithms,
and use @code{none} to set no preference at all. This allows the user
to safely override the algorithm chosen by the recipient key
preferences, as GPG will only select an algorithm that is usable by
all recipients. The most highly ranked digest algorithm in this list
is also used when signing without encryption
-(e.g. @option{--clearsign} or @option{--sign}).
+(e.g. @option{--clear-sign} or @option{--sign}).
-@item --personal-compress-preferences @code{string}
+@item --personal-compress-preferences @var{string}
@opindex personal-compress-preferences
-Set the list of personal compression preferences to @code{string}.
+Set the list of personal compression preferences to @var{string}.
Use @command{@gpgname --version} to get a list of available
algorithms, and use @code{none} to set no preference at all. This
allows the user to safely override the algorithm chosen by the
algorithm in this list is also used when there are no recipient keys
to consider (e.g. @option{--symmetric}).
-@item --s2k-cipher-algo @code{name}
+@item --s2k-cipher-algo @var{name}
@opindex s2k-cipher-algo
-Use @code{name} as the cipher algorithm for symmetric encryption with
+Use @var{name} as the cipher algorithm for symmetric encryption with
a passphrase if @option{--personal-cipher-preferences} and
@option{--cipher-algo} are not given. The default is @value{GPGSYMENCALGO}.
-@item --s2k-digest-algo @code{name}
+@item --s2k-digest-algo @var{name}
@opindex s2k-digest-algo
-Use @code{name} as the digest algorithm used to mangle the passphrases
+Use @var{name} as the digest algorithm used to mangle the passphrases
for symmetric encryption. The default is SHA-1.
-@item --s2k-mode @code{n}
+@item --s2k-mode @var{n}
@opindex s2k-mode
Selects how passphrases for symmetric encryption are mangled. If
-@code{n} is 0 a plain passphrase (which is in general not recommended)
+@var{n} is 0 a plain passphrase (which is in general not recommended)
will be used, a 1 adds a salt (which should not be used) to the
passphrase and a 3 (the default) iterates the whole process a number
of times (see @option{--s2k-count}).
-@item --s2k-count @code{n}
+@item --s2k-count @var{n}
@opindex s2k-count
Specify how many times the passphrases mangling for symmetric
encryption is repeated. This value may range between 1024 and
restricts you to the ciphers IDEA (if the IDEA plugin is installed),
3DES, and CAST5, the hashes MD5, SHA1 and RIPEMD160, and the
compression algorithms none and ZIP. This also disables
---throw-keyids, and making signatures with signing subkeys as PGP 6
+@option{--throw-keyids}, and making signatures with signing subkeys as PGP 6
does not understand signatures made by signing subkeys.
This option implies @option{--disable-mdc --escape-from-lines}.
@option{--escape-from-lines}. All algorithms are allowed except for the
SHA224, SHA384, and SHA512 digests.
+@item --compliance @var{string}
+@opindex compliance
+This option can be used instead of one of the options above. Valid
+values for @var{string} are the above option names (without the double
+dash) and possibly others as shown when using "help" for @var{value}.
+
@end table
@c ******** ESOTERIC OPTIONS ***************
@c *******************************************
@node GPG Esoteric Options
-@subsection Doing things one usually doesn't want to do.
+@subsection Doing things one usually doesn't want to do
@table @gnupgtabopt
@item --list-only
@opindex list-only
Changes the behaviour of some commands. This is like @option{--dry-run} but
-different in some cases. The semantic of this command may be extended in
+different in some cases. The semantic of this option may be extended in
the future. Currently it only skips the actual decryption pass and
therefore enables a fast listing of the encryption keys.
1970. Alternatively @var{epoch} may be given as a full ISO time string
(e.g. "20070924T154812").
+If you suffix @var{epoch} with an exclamation mark (!), the system time
+will appear to be frozen at the specified time.
+
@item --enable-progress-filter
@opindex enable-progress-filter
Enable certain PROGRESS status outputs. This option allows frontends
to display a progress indicator while gpg is processing larger files.
There is a slight performance overhead using it.
-@item --status-fd @code{n}
+@item --status-fd @var{n}
@opindex status-fd
-Write special status strings to the file descriptor @code{n}.
+Write special status strings to the file descriptor @var{n}.
See the file DETAILS in the documentation for a listing of them.
-@item --status-file @code{file}
+@item --status-file @var{file}
@opindex status-file
Same as @option{--status-fd}, except the status data is written to file
-@code{file}.
+@var{file}.
-@item --logger-fd @code{n}
+@item --logger-fd @var{n}
@opindex logger-fd
-Write log output to file descriptor @code{n} and not to STDERR.
+Write log output to file descriptor @var{n} and not to STDERR.
-@item --log-file @code{file}
-@itemx --logger-file @code{file}
+@item --log-file @var{file}
+@itemx --logger-file @var{file}
@opindex log-file
-Same as @option{--logger-fd}, except the logger data is written to file
-@code{file}. Note that @option{--log-file} is only implemented for
-GnuPG-2.
+Same as @option{--logger-fd}, except the logger data is written to
+file @var{file}. Use @file{socket://} to log to s socket.
-@item --attribute-fd @code{n}
+@item --attribute-fd @var{n}
@opindex attribute-fd
-Write attribute subpackets to the file descriptor @code{n}. This is most
+Write attribute subpackets to the file descriptor @var{n}. This is most
useful for use with @option{--status-fd}, since the status messages are
needed to separate out the various subpackets from the stream delivered
to the file descriptor.
-@item --attribute-file @code{file}
+@item --attribute-file @var{file}
@opindex attribute-file
Same as @option{--attribute-fd}, except the attribute data is written to
-file @code{file}.
+file @var{file}.
-@item --comment @code{string}
+@item --comment @var{string}
@itemx --no-comments
@opindex comment
-Use @code{string} as a comment string in clear text signatures and ASCII
+Use @var{string} as a comment string in cleartext signatures and ASCII
armored messages or keys (see @option{--armor}). The default behavior is
not to use a comment string. @option{--comment} may be repeated multiple
times to get multiple comment strings. @option{--no-comments} removes
@opindex emit-version
Force inclusion of the version string in ASCII armored output. If
given once only the name of the program and the major number is
-emitted, given twice the minor is also emitted, given triple
-the micro is added, and given quad an operating system identification
+emitted, given twice the minor is also emitted, given thrice
+the micro is added, and given four times an operating system identification
is also emitted. @option{--no-emit-version} (default) disables the version
line.
-@item --sig-notation @code{name=value}
-@itemx --cert-notation @code{name=value}
-@itemx -N, --set-notation @code{name=value}
+@item --sig-notation @{@var{name}=@var{value}@}
+@itemx --cert-notation @{@var{name}=@var{value}@}
+@itemx -N, --set-notation @{@var{name}=@var{value}@}
@opindex sig-notation
@opindex cert-notation
@opindex set-notation
Put the name value pair into the signature as notation data.
-@code{name} must consist only of printable characters or spaces, and
+@var{name} must consist only of printable characters or spaces, and
must contain a '@@' character in the form keyname@@domain.example.com
(substituting the appropriate keyname and domain name, of course). This
is to help prevent pollution of the IETF reserved notation
namespace. The @option{--expert} flag overrides the '@@'
-check. @code{value} may be any printable string; it will be encoded in
-UTF8, so you should check that your @option{--display-charset} is set
-correctly. If you prefix @code{name} with an exclamation mark (!), the
+check. @var{value} may be any printable string; it will be encoded in
+UTF-8, so you should check that your @option{--display-charset} is set
+correctly. If you prefix @var{name} with an exclamation mark (!), the
notation data will be flagged as critical
(rfc4880:5.2.3.16). @option{--sig-notation} sets a notation for data
signatures. @option{--cert-notation} sets a notation for key signatures
meaningful when making a key signature (certification), and %c is only
meaningful when using the OpenPGP smartcard.
-@item --sig-policy-url @code{string}
-@itemx --cert-policy-url @code{string}
-@itemx --set-policy-url @code{string}
+@item --sig-policy-url @var{string}
+@itemx --cert-policy-url @var{string}
+@itemx --set-policy-url @var{string}
@opindex sig-policy-url
@opindex cert-policy-url
@opindex set-policy-url
-Use @code{string} as a Policy URL for signatures (rfc4880:5.2.3.20). If
+Use @var{string} as a Policy URL for signatures (rfc4880:5.2.3.20). If
you prefix it with an exclamation mark (!), the policy URL packet will
be flagged as critical. @option{--sig-policy-url} sets a policy url for
data signatures. @option{--cert-policy-url} sets a policy url for key
The same %-expandos used for notation data are available here as well.
-@item --sig-keyserver-url @code{string}
+@item --sig-keyserver-url @var{string}
@opindex sig-keyserver-url
-Use @code{string} as a preferred keyserver URL for data signatures. If
+Use @var{string} as a preferred keyserver URL for data signatures. If
you prefix it with an exclamation mark (!), the keyserver URL packet
will be flagged as critical.
The same %-expandos used for notation data are available here as well.
-@item --set-filename @code{string}
+@item --set-filename @var{string}
@opindex set-filename
-Use @code{string} as the filename which is stored inside messages.
+Use @var{string} as the filename which is stored inside messages.
This overrides the default, which is to use the actual filename of the
file being encrypted. Using the empty string for @var{string}
effectively removes the filename from the output.
Try to create a file with a name as embedded in the data. This can be
a dangerous option as it enables overwriting files. Defaults to no.
-@item --cipher-algo @code{name}
+@item --cipher-algo @var{name}
@opindex cipher-algo
-Use @code{name} as cipher algorithm. Running the program with the
+Use @var{name} as cipher algorithm. Running the program with the
command @option{--version} yields a list of supported algorithms. If
this is not used the cipher algorithm is selected from the preferences
stored with the key. In general, you do not want to use this option as
@option{--personal-cipher-preferences} is the safe way to accomplish the
same thing.
-@item --digest-algo @code{name}
+@item --digest-algo @var{name}
@opindex digest-algo
-Use @code{name} as the message digest algorithm. Running the program
+Use @var{name} as the message digest algorithm. Running the program
with the command @option{--version} yields a list of supported algorithms. In
general, you do not want to use this option as it allows you to
violate the OpenPGP standard. @option{--personal-digest-preferences} is the
safe way to accomplish the same thing.
-@item --compress-algo @code{name}
+@item --compress-algo @var{name}
@opindex compress-algo
-Use compression algorithm @code{name}. "zlib" is RFC-1950 ZLIB
+Use compression algorithm @var{name}. "zlib" is RFC-1950 ZLIB
compression. "zip" is RFC-1951 ZIP compression which is used by PGP.
"bzip2" is a more modern compression scheme that can compress some
things better than zip or zlib, but at the cost of more memory used
violate the OpenPGP standard. @option{--personal-compress-preferences} is the
safe way to accomplish the same thing.
-@item --cert-digest-algo @code{name}
+@item --cert-digest-algo @var{name}
@opindex cert-digest-algo
-Use @code{name} as the message digest algorithm used when signing a
+Use @var{name} as the message digest algorithm used when signing a
key. Running the program with the command @option{--version} yields a
list of supported algorithms. Be aware that if you choose an algorithm
that GnuPG supports but other OpenPGP implementations do not, then some
users will not be able to use the key signatures you make, or quite
possibly your entire key.
-@item --disable-cipher-algo @code{name}
+@item --disable-cipher-algo @var{name}
@opindex disable-cipher-algo
-Never allow the use of @code{name} as cipher algorithm.
+Never allow the use of @var{name} as cipher algorithm.
The given name will not be checked so that a later loaded algorithm
will still get disabled.
-@item --disable-pubkey-algo @code{name}
+@item --disable-pubkey-algo @var{name}
@opindex disable-pubkey-algo
-Never allow the use of @code{name} as public key algorithm.
+Never allow the use of @var{name} as public key algorithm.
The given name will not be checked so that a later loaded algorithm
will still get disabled.
that all other PGP versions do it this way too. Enabled by
default. @option{--no-escape-from-lines} disables this option.
-@item --passphrase-repeat @code{n}
+@item --passphrase-repeat @var{n}
@opindex passphrase-repeat
Specify how many times @command{@gpgname} will request a new
passphrase be repeated. This is useful for helping memorize a
passphrase. Defaults to 1 repetition.
-@item --passphrase-fd @code{n}
+@item --passphrase-fd @var{n}
@opindex passphrase-fd
-Read the passphrase from file descriptor @code{n}. Only the first line
-will be read from file descriptor @code{n}. If you use 0 for @code{n},
+Read the passphrase from file descriptor @var{n}. Only the first line
+will be read from file descriptor @var{n}. If you use 0 for @var{n},
the passphrase will be read from STDIN. This can only be used if only
one passphrase is supplied.
Note that this passphrase is only used if the option @option{--batch}
has also been given. This is different from GnuPG version 1.x.
-@item --passphrase-file @code{file}
+@item --passphrase-file @var{file}
@opindex passphrase-file
-Read the passphrase from file @code{file}. Only the first line will
-be read from file @code{file}. This can only be used if only one
+Read the passphrase from file @var{file}. Only the first line will
+be read from file @var{file}. This can only be used if only one
passphrase is supplied. Obviously, a passphrase stored in a file is
of questionable security if other users can read this file. Don't use
this option if you can avoid it.
Note that this passphrase is only used if the option @option{--batch}
has also been given. This is different from GnuPG version 1.x.
-@item --passphrase @code{string}
+@item --passphrase @var{string}
@opindex passphrase
-Use @code{string} as the passphrase. This can only be used if only one
+Use @var{string} as the passphrase. This can only be used if only one
passphrase is supplied. Obviously, this is of very questionable
security on a multi-user system. Don't use this option if you can
avoid it.
Note that this passphrase is only used if the option @option{--batch}
has also been given. This is different from GnuPG version 1.x.
-@item --pinentry-mode @code{mode}
+@item --pinentry-mode @var{mode}
@opindex pinentry-mode
-Set the pinentry mode to @code{mode}. Allowed values for @code{mode}
+Set the pinentry mode to @var{mode}. Allowed values for @var{mode}
are:
@table @asis
@item default
Pinentry the user is not prompted again if he enters a bad password.
@end table
-@item --command-fd @code{n}
+@item --command-fd @var{n}
@opindex command-fd
This is a replacement for the deprecated shared-memory IPC mode.
If this option is enabled, user input on questions is not expected
together with @option{--status-fd}. See the file doc/DETAILS in the source
distribution for details on how to use it.
-@item --command-file @code{file}
+@item --command-file @var{file}
@opindex command-file
Same as @option{--command-fd}, except the commands are read out of file
-@code{file}
+@var{file}
@item --allow-non-selfsigned-uid
@itemx --no-allow-non-selfsigned-uid
MD5 is the only digest algorithm considered weak by default. See also
@option{--weak-digest} to reject other digest algorithms.
-@item --weak-digest @code{name}
+@item --weak-digest @var{name}
@opindex weak-digest
Treat the specified digest algorithm as weak. Signatures made over
weak digests algorithms are normally rejected. This option can be
Print key listings delimited by colons (like @option{--with-colons}) and
print the public key data.
+@item --list-signatures
+@opindex list-signatures
+@itemx --list-sigs
+@opindex list-sigs
+Same as @option{--list-keys}, but the signatures are listed too. This
+command has the same effect as using @option{--list-keys} with
+@option{--with-sig-list}. Note that in contrast to
+@option{--check-signatures} the key signatures are not verified.
+
+
@item --fast-list-mode
@opindex fast-list-mode
Changes the output of the list commands to work faster; this is achieved
inappropriate plaintext so they can take action against the offending
user.
-@item --override-session-key @code{string}
+@item --override-session-key @var{string}
+@itemx --override-session-key-fd @var{fd}
@opindex override-session-key
-Don't use the public key but the session key @code{string}. The format
-of this string is the same as the one printed by
-@option{--show-session-key}. This option is normally not used but comes
-handy in case someone forces you to reveal the content of an encrypted
-message; using this option you can do this without handing out the
-secret key.
+Don't use the public key but the session key @var{string} respective
+the session key taken from the first line read from file descriptor
+@var{fd}. The format of this string is the same as the one printed
+by @option{--show-session-key}. This option is normally not used but
+comes handy in case someone forces you to reveal the content of an
+encrypted message; using this option you can do this without handing
+out the secret key. Note that using @option{--override-session-key}
+may reveal the session key to all local users via the global process
+table.
@item --ask-sig-expire
@itemx --no-ask-sig-expire
(for example "2m" for two months, or "5y" for five years), or an
absolute date in the form YYYY-MM-DD. Defaults to "0".
+@item --default-new-key-algo @var{string}
+@opindex default-new-key-algo @var{string}
+This option can be used to change the default algorithms for key
+generation. Note that the advanced key generation commands can always
+be used to specify a key algorithm directly. Please consult the
+source code to learn the syntax of @var{string}.
+
@item --allow-secret-key-import
@opindex allow-secret-key-import
This is an obsolete option and is not used anywhere.
@item --enable-special-filenames
@opindex enable-special-filenames
-This options enables a mode in which filenames of the form
+This option enables a mode in which filenames of the form
@file{-&n}, where n is a non-negative decimal number,
refer to the file descriptor n and not to a file with that name.
Don't change the permissions of a secret keyring back to user
read/write only. Use this option only if you really know what you are doing.
-@item --default-preference-list @code{string}
+@item --default-preference-list @var{string}
@opindex default-preference-list
-Set the list of default preferences to @code{string}. This preference
+Set the list of default preferences to @var{string}. This preference
list is used for new keys and becomes the default for "setpref" in the
edit menu.
-@item --default-keyserver-url @code{name}
+@item --default-keyserver-url @var{name}
@opindex default-keyserver-url
-Set the default keyserver URL to @code{name}. This keyserver will be
+Set the default keyserver URL to @var{name}. This keyserver will be
used as the keyserver URL when writing a new self-signature on a key,
which includes key generation and changing preferences.
@opindex gpgconf-test
This is more or less dummy action. However it parses the configuration
file and returns with failure if the configuration file would prevent
-@command{gpg} from startup. Thus it may be used to run a syntax check
+@command{@gpgname} from startup. Thus it may be used to run a syntax check
on the configuration file.
@end table
@item --show-photos
@itemx --no-show-photos
@opindex show-photos
-Causes @option{--list-keys}, @option{--list-sigs},
+Causes @option{--list-keys}, @option{--list-signatures},
@option{--list-public-keys}, @option{--list-secret-keys}, and verifying
a signature to also display the photo ID attached to the key, if
any. See also @option{--photo-viewer}. These options are deprecated. Use
@item --show-notation
@itemx --no-show-notation
@opindex show-notation
-Show signature notations in the @option{--list-sigs} or @option{--check-sigs} listings
+Show signature notations in the @option{--list-signatures} or @option{--check-signatures} listings
as well as when verifying a signature with a notation in it. These
options are deprecated. Use @option{--list-options [no-]show-notation}
and/or @option{--verify-options [no-]show-notation} instead.
@item --show-policy-url
@itemx --no-show-policy-url
@opindex show-policy-url
-Show policy URLs in the @option{--list-sigs} or @option{--check-sigs}
+Show policy URLs in the @option{--list-signatures} or @option{--check-signatures}
listings as well as when verifying a signature with a policy URL in
it. These options are deprecated. Use @option{--list-options
[no-]show-policy-url} and/or @option{--verify-options
helper script is provided to create these files (@pxref{addgnupghome}).
For internal purposes @command{@gpgname} creates and maintains a few other
-files; They all live in in the current home directory (@pxref{option
+files; They all live in the current home directory (@pxref{option
--homedir}). Only the @command{@gpgname} program may modify these files.
@item ~/.gnupg/pubring.kbx
@efindex pubring.kbx
- The public keyring using a different format. This file is sharred
+ The public keyring using a different format. This file is shared
with @command{gpgsm}. You should backup this file.
@item ~/.gnupg/pubring.kbx.lock
You should backup all files in this directory and take care to keep
this backup closed away.
- @item @value{DATADIR}/options.skel
- @efindex options.skel
- The skeleton options file.
-
@end table
Operation is further controlled by a few environment variables:
language selection done through the Registry. If used and set to a
valid and available language name (@var{langid}), the file with the
translation is loaded from
-
@code{@var{gpgdir}/gnupg.nls/@var{langid}.mo}. Here @var{gpgdir} is the
directory out of which the gpg binary has been loaded. If it can't be
loaded the Registry is tried and as last resort the native Windows
@item gpg -se -r @code{Bob} @code{file}
sign and encrypt for user Bob
-@item gpg --clearsign @code{file}
-make a clear text signature
+@item gpg --clear-sign @code{file}
+make a cleartext signature
@item gpg -sb @code{file}
make a detached signature
show fingerprint
@item gpg --verify @code{pgpfile}
-@itemx gpg --verify @code{sigfile}
-Verify the signature of the file but do not output the data. The
-second form is used for detached signatures, where @code{sigfile}
-is the detached signature (either ASCII armored or binary) and
-are the signed data; if this is not given, the name of
-the file holding the signed data is constructed by cutting off the
-extension (".asc" or ".sig") of @code{sigfile} or by asking the
-user for the filename.
+@itemx gpg --verify @code{sigfile} [@code{datafile}]
+Verify the signature of the file but do not output the data unless
+requested. The second form is used for detached signatures, where
+@code{sigfile} is the detached signature (either ASCII armored or
+binary) and @code{datafile} are the signed data; if this is not given, the name of the
+file holding the signed data is constructed by cutting off the
+extension (".asc" or ".sig") of @code{sigfile} or by asking the user
+for the filename. If the option @option{--output} is also used the
+signed data is written to the file specified by that option; use
+@code{-} to write the signed data to stdout.
@end table
@item <
The numerical value of the field must be LT than the value.
- @item >=
+ @item >
The numerical value of the field must be GT than the value.
@item >=
The numerical value of the field must be GE than the value.
+ @item -le
+ The string value of the field must be less or equal than the value.
+
+ @item -lt
+ The string value of the field must be less than the value.
+
+ @item -gt
+ The string value of the field must be greater than the value.
+
+ @item -ge
+ The string value of the field must be greater or equal than the value.
+
@item -n
True if value is not empty (no value allowed).
Before you report a bug you should first search the mailing list
archives for similar problems and second check whether such a bug has
-already been reported to our bug tracker at http://bugs.gnupg.org .
+already been reported to our bug tracker at @url{https://bugs.gnupg.org}.
@c *******************************************
@c *************** **************
@node Unattended Usage of GPG
@section Unattended Usage
-@command{gpg} is often used as a backend engine by other software. To help
+@command{@gpgname} is often used as a backend engine by other software. To help
with this a machine interface has been defined to have an unambiguous
way to do this. The options @option{--status-fd} and @option{--batch}
are almost always required for this.
@menu
+* Programmatic use of GnuPG:: Programmatic use of GnuPG
+* Ephemeral home directories:: Ephemeral home directories
+* The quick key manipulation interface:: The quick key manipulation interface
* Unattended GPG key generation:: Unattended key generation
@end menu
+@node Programmatic use of GnuPG
+@subsection Programmatic use of GnuPG
+
+Please consider using GPGME instead of calling @command{@gpgname}
+directly. GPGME offers a stable, backend-independent interface for
+many cryptographic operations. It supports OpenPGP and S/MIME, and
+also allows interaction with various GnuPG components.
+
+GPGME provides a C-API, and comes with bindings for C++, Qt, and
+Python. Bindings for other languages are available.
+
+@node Ephemeral home directories
+@subsection Ephemeral home directories
+
+Sometimes you want to contain effects of some operation, for example
+you want to import a key to inspect it, but you do not want this key
+to be added to your keyring. In earlier versions of GnuPG, it was
+possible to specify alternate keyring files for both public and secret
+keys. In modern GnuPG versions, however, we changed how secret keys
+are stored in order to better protect secret key material, and it was
+not possible to preserve this interface.
+
+The preferred way to do this is to use ephemeral home directories.
+This technique works across all versions of GnuPG.
+
+Create a temporary directory, create (or copy) a configuration that
+meets your needs, make @command{@gpgname} use this directory either
+using the environment variable @var{GNUPGHOME}, or the option
+@option{--homedir}. GPGME supports this too on a per-context basis,
+by modifying the engine info of contexts. Now execute whatever
+operation you like, import and export key material as necessary. Once
+finished, you can delete the directory. All GnuPG backend services
+that were started will detect this and shut down.
+
+@node The quick key manipulation interface
+@subsection The quick key manipulation interface
+
+Recent versions of GnuPG have an interface to manipulate keys without
+using the interactive command @option{--edit-key}. This interface was
+added mainly for the benefit of GPGME (please consider using GPGME,
+see the manual subsection ``Programmatic use of GnuPG''). This
+interface is described in the subsection ``How to manage your keys''.
+
@node Unattended GPG key generation
@subsection Unattended key generation
-The command @option{--gen-key} may be used along with the option
-@option{--batch} for unattended key generation. The parameters are
-either read from stdin or given as a file on the command line.
-The format of the parameter file is as follows:
+The command @option{--generate-key} may be used along with the option
+@option{--batch} for unattended key generation. This is the most
+flexible way of generating keys, but it is also the most complex one.
+Consider using the quick key manipulation interface described in the
+previous subsection ``The quick key manipulation interface''.
+
+The parameters for the key are either read from stdin or given as a
+file on the command line. The format of the parameter file is as
+follows:
@itemize @bullet
@item Text only, line length is limited to about 1000 characters.
@item UTF-8 encoding must be used to specify non-ASCII characters.
@item Empty lines are ignored.
- @item Leading and trailing while space is ignored.
+ @item Leading and trailing white space is ignored.
@item A hash sign as the first non white space character indicates
a comment line.
@item Control statements are indicated by a leading percent sign, the
the next @asis{Key-Type} parameter.
@item %pubring @var{filename}
-@itemx %secring @var{filename}
Do not write the key to the default or commandline given keyring but
to @var{filename}. This must be given before the first commit to take
place, duplicate specification of the same filename is ignored, the
last filename before a commit is used. The filename is used until a
new filename is used (at commit points) and all keys are written to
that file. If a new filename is given, this file is created (and
-overwrites an existing one). For GnuPG versions prior to 2.1, both
-control statements must be given. For GnuPG 2.1 and later
-@samp{%secring} is a no-op.
+overwrites an existing one).
+
+See the previous subsection ``Ephemeral home directories'' for a more
+robust way to contain side-effects.
+
+@item %secring @var{filename}
+This option is a no-op for GnuPG 2.1 and later.
+
+See the previous subsection ``Ephemeral home directories''.
@item %ask-passphrase
@itemx %no-ask-passphrase
@item Subkey-Length: @var{nbits}
Length of the secondary key (subkey) in bits. The default is returned
-by running the command @samp{@gpgname --gpgconf-list}".
+by running the command @samp{@gpgname --gpgconf-list}.
@item Subkey-Usage: @var{usage-list}
Key usage lists for a subkey; similar to @samp{Key-Usage}.
@end table
@noindent
-Here is an example on how to create a key:
+Here is an example on how to create a key in an ephemeral home directory:
@smallexample
+$ export GNUPGHOME="$(mktemp -d)"
$ cat >foo <<EOF
%echo Generating a basic OpenPGP key
Key-Type: DSA
Name-Email: joe@@foo.bar
Expire-Date: 0
Passphrase: abc
- %pubring foo.pub
- %secring foo.sec
# Do a commit here, so that we can later print "done" :-)
%commit
%echo done
EOF
-$ @gpgname --batch --gen-key foo
+$ @gpgname --batch --generate-key foo
[...]
-$ @gpgname --no-default-keyring --secret-keyring ./foo.sec \
- --keyring ./foo.pub --list-secret-keys
-/home/wk/work/gnupg-stable/scratch/foo.sec
-------------------------------------------
-sec 1024D/915A878D 2000-03-09 Joe Tester (with stupid passphrase) <joe@@foo.bar>
-ssb 1024g/8F70E2C0 2000-03-09
+$ @gpgname --list-secret-keys
+/tmp/tmp.0NQxB74PEf/pubring.kbx
+-------------------------------
+sec dsa1024 2016-12-16 [SCA]
+ 768E895903FC1C44045C8CB95EEBDB71E9E849D0
+uid [ultimate] Joe Tester (with stupid passphrase) <joe@@foo.bar>
+ssb elg1024 2016-12-16 [E]
@end smallexample
-
@noindent
If you want to create a key with the default algorithms you would use
these parameters:
Name-Email: joe@@foo.bar
Expire-Date: 0
Passphrase: abc
- %pubring foo.pub
- %secring foo.sec
# Do a commit here, so that we can later print "done" :-)
%commit
%echo done
projects / gnupg.git / blobdiff