agent: Stop scdaemon after reload when disable_scdaemon.
[gnupg.git] / doc / gpg.texi
index 01dfeb7..fd7dcdd 100644 (file)
@@ -196,11 +196,13 @@ Make a detached signature.
 @item --encrypt
 @itemx -e
 @opindex encrypt
-Encrypt data. 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).
+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
@@ -212,7 +214,10 @@ symmetric cipher used is @value{GPGSYMENCALGO}, but may be chosen with the
 @option{--encrypt} (for a message that may be decrypted via a secret key
 or a passphrase), or @option{--sign} and @option{--encrypt} together
 (for a signed message that may be decrypted via a secret key or a
-passphrase).
+passphrase).  @command{@gpgname} caches the passphrase used for
+symmetric encryption so that a decrypt operation may not require that
+the user needs to enter the passphrase.  The option
+@option{--no-symkey-cache} can be used to disable this feature.
 
 @item --store
 @opindex store
@@ -304,48 +309,41 @@ 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
+offline (for example, a primary key can be taken offline by exporting
 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 --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}.
-
-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-signatures
 @opindex check-signatures
 @itemx --check-sigs
 @opindex check-sigs
-Same as @option{--list-signatures}, 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-signatures}).  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 available 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
@@ -355,12 +353,22 @@ may thus be used to see what keys @command{@gpgname} might use.  In
 particular external methods as defined by @option{--auto-key-locate} may
 be used to locate a key.  Only public keys are listed.
 
+@item --show-keys
+@opindex show-keys
+This commands takes OpenPGP keys as input and prints information about
+them in the same way the command @option{--list-keys} does for locally
+stored key.  In addition the list options @code{show-unusable-uids},
+@code{show-unusable-subkeys}, @code{show-notations} and
+@code{show-policy-urls} are also enabled.  As usual for automated
+processing, this command should be combined with the option
+@option{--with-colons}.
+
 @item --fingerprint
 @opindex fingerprint
 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-signatures} or @option{--check-signatures}.  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".
@@ -426,9 +434,8 @@ file given with option @option{--output}.  Use together with
 @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
+Fingerprints may be used instead of key IDs.
+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.
 
@@ -483,27 +490,25 @@ signatures, user-IDs and subkeys.
 @opindex receive-keys
 @itemx --recv-keys @var{keyIDs}
 @opindex recv-keys
-Import the keys with the given @var{keyIDs} from a keyserver. Option
-@option{--keyserver} must be used to give the name of this keyserver.
+Import the keys with the given @var{keyIDs} from a keyserver.
 
 @item --refresh-keys
 @opindex refresh-keys
 Request updates from a keyserver for keys that already exist on the
 local keyring. This is useful for updating a key with the latest
 signatures, user IDs, etc. Calling this with no arguments will refresh
-the entire keyring. Option @option{--keyserver} must be used to give the
-name of the keyserver for all keys that do not have preferred keyservers
-set (see @option{--keyserver-options honor-keyserver-url}).
+the entire keyring.
 
 @item --search-keys @var{names}
 @opindex search-keys
-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
-the syntax specified in "How to specify a user ID" below. Note that
-different keyserver types support different search methods. Currently
-only LDAP supports them all.
+Search the keyserver for the given @var{names}. Multiple names given
+here will be joined together to create the search string for the
+keyserver.  Note that keyservers search for @var{names} in a different
+and simpler way than gpg does.  The best choice is to use a mail
+address.  Due to data privacy reasons keyservers may even not even
+allow searching by user id or mail address and thus may only return
+results when being used with the @option{--recv-key} command to
+search by key fingerprint or keyid.
 
 @item --fetch-keys @var{URIs}
 @opindex fetch-keys
@@ -616,9 +621,9 @@ fingerprint (preferred) or their keyid.
 @end table
 
 
-@c *******************************************
-@c *******  KEY MANGEMENT COMMANDS  **********
-@c *******************************************
+@c ********************************************
+@c *******  KEY MANAGEMENT COMMANDS  **********
+@c ********************************************
 @node OpenPGP Key Management
 @subsection How to manage your keys
 
@@ -627,7 +632,9 @@ This section explains the main commands for key management.
 @table @gnupgtabopt
 
 @item --quick-generate-key @var{user-id} [@var{algo} [@var{usage} [@var{expire}]]]
+@itemx --quick-gen-key
 @opindex quick-generate-key
+@opindex quick-gen-key
 This is a simple command to generate a standard key with one user id.
 In contrast to @option{--generate-key} the key is generated directly
 without the need to answer a bunch of prompts.  Unless the option
@@ -665,6 +672,10 @@ supplied passphrase is used for the new key and the agent does not ask
 for it.  To create a key without any protection @code{--passphrase ''}
 may be used.
 
+Note that it is possible to create a primary key and a subkey using
+non-default algorithms by using ``default'' and changing the default
+parameters using the option @option{--default-new-key-algo}.
+
 @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
@@ -692,7 +703,8 @@ 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.
+future versions of gpg.  To list the supported ECC curves the command
+@code{gpg --with-colons --list-config curve} can be used.
 
 Depending on the given @var{algo} the subkey may either be an
 encryption subkey or a signing subkey.  If an algorithm is capable of
@@ -1010,6 +1022,15 @@ signing.
   Make the key as small as possible. This removes all signatures from
   each user ID except for the most recent self-signature.
 
+  @item change-usage
+  @opindex keyedit:change-usage
+  Change the usage flags (capabilities) of the primary key or of
+  subkeys.  These usage flags (e.g. Certify, Sign, Authenticate,
+  Encrypt) are set during key creation.  Sometimes it is useful to
+  have the opportunity to change them (for example to add
+  Authenticate) after they have been created.  Please take care when
+  doing this; the allowed usage flags depend on the key algorithm.
+
   @item cross-certify
   @opindex keyedit:cross-certify
   Add cross-certification signatures to signing subkeys that may not
@@ -1031,38 +1052,13 @@ signing.
 
 @c man:.RS
 The listing shows you the key with its secondary keys and all user
-ids.  The primary user id is indicated by a dot, and selected keys or
-user ids are indicated by an asterisk.  The trust
-value is displayed with the primary key: the first is the assigned owner
-trust and the second is the calculated trust value. Letters are used for
-the values:
+IDs.  The primary user ID is indicated by a dot, and selected keys or
+user IDs are indicated by an asterisk.  The trust
+value is displayed with the primary key: "trust" is the assigned owner
+trust and "validity" is the calculated validity of the key.  Validity
+values are also displayed for all user IDs.
+For possible values of trust, @pxref{trust-values}.
 @c man:.RE
-
-@table @asis
-
-  @item -
-  No ownertrust assigned / not yet calculated.
-
-  @item e
-  Trust
-  calculation has failed; probably due to an expired key.
-
-  @item q
-  Not enough information for calculation.
-
-  @item n
-  Never trust this key.
-
-  @item m
-  Marginally trusted.
-
-  @item f
-  Fully trusted.
-
-  @item u
-  Ultimately trusted.
-
-@end table
 @c ******** End Edit-key Options **********
 
 @item --sign-key @var{name}
@@ -1129,7 +1125,9 @@ all affected self-signatures is set one second ahead.
 @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
-@code{passwd} of the edit key menu.
+@code{passwd} of the edit key menu.  When using together with the
+option @option{--dry-run} this will not actually change the passphrase
+but check that the current passphrase is correct.
 
 @end table
 
@@ -1254,7 +1252,7 @@ Assume "no" on most questions.
 @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-signatures}, @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:
@@ -1263,7 +1261,7 @@ give the opposite meaning.  The options are:
 
   @item show-photos
   @opindex list-options:show-photos
-  Causes @option{--list-keys}, @option{--list-signatures},
+  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}:
@@ -1279,7 +1277,7 @@ give the opposite meaning.  The options are:
 
   @item show-policy-urls
   @opindex list-options:show-policy-urls
-  Show policy URLs in the @option{--list-signatures} or @option{--check-signatures}
+  Show policy URLs in the  @option{--check-signatures}
   listings.  Defaults to no.
 
   @item show-notations
@@ -1289,11 +1287,11 @@ give the opposite meaning.  The options are:
   @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-signatures} or @option{--check-signatures} 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-signatures} or
+  Show any preferred keyserver URL in the
   @option{--check-signatures} listings. Defaults to no.
 
   @item show-uid-validity
@@ -1316,7 +1314,7 @@ give the opposite meaning.  The options are:
 
   @item show-sig-expire
   @opindex list-options:show-sig-expire
-  Show signature expiration dates (if any) during @option{--list-signatures} or
+  Show signature expiration dates (if any) during
   @option{--check-signatures} listings. Defaults to no.
 
   @item show-sig-subpackets
@@ -1325,8 +1323,12 @@ give the opposite meaning.  The options are:
   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-signatures} or @option{--check-signatures}.
+  @option{--check-signatures}.
 
+  @item show-only-fpr-mbox
+  @opindex list-options:show-only-fpr-mbox
+  For each user-id which has a valid mail address print
+  only the fingerprint followed by the mail address.
 @end table
 
 @item --verify-options @var{parameters}
@@ -1424,19 +1426,24 @@ viewed (e.g. "f"), "%V" for the calculated validity as a string (e.g.
 and "%%" for an actual percent sign. If neither %i or %I are present,
 then the photo will be supplied to the viewer on standard input.
 
-The default viewer is "xloadimage -fork -quiet -title 'KeyID 0x%k'
-STDIN". Note that if your image viewer program is not secure, then
-executing it from GnuPG does not make it secure.
+On Unix the default viewer is
+@code{xloadimage -fork -quiet -title 'KeyID 0x%k' STDIN}
+with a fallback to
+@code{display -title 'KeyID 0x%k' %i}
+and finally to
+@code{xdg-open %i}.
+On Windows
+@code{!ShellExecute 400 %i} is used; here the command is a meta
+command to use that API call followed by a wait time in milliseconds
+which is used to give the viewer time to read the temporary image file
+before gpg deletes it again.  Note that if your image viewer program
+is not secure, then executing it from gpg does not make it secure.
 
 @item --exec-path @var{string}
 @opindex exec-path
 @efindex PATH
-Sets a list of directories to search for photo viewers and keyserver
-helpers. If not provided, keyserver helpers use the compiled-in
-default directory, and photo viewers use the @code{PATH} environment
-variable.
-Note, that on W32 system this value is ignored when searching for
-keyserver helpers.
+Sets a list of directories to search for photo viewers If not provided
+photo viewers use the @code{PATH} environment variable.
 
 @item --keyring @var{file}
 @opindex keyring
@@ -1644,7 +1651,7 @@ Set what trust model GnuPG should follow. The models are:
   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 occured
+  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
@@ -1723,17 +1730,22 @@ Set what trust model GnuPG should follow. The models are:
   @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.
+  exists.  Note that a tofu trust model is not considered here and
+  must be enabled explicitly.
 @end table
 
-@item --auto-key-locate @var{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
 
@@ -1749,7 +1761,6 @@ mechanisms, in the order they are to be tried:
 
   @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
@@ -1757,12 +1768,11 @@ mechanisms, in the order they are to be tried:
   PGP Universal method of checking @samp{ldap://keys.(thedomain)}.
 
   @item keyserver
-  Locate a key using whatever keyserver is defined using the
-  @option{--keyserver} option.
+  Locate a key using a keyserver.
 
   @item keyserver-URL
-  In addition, a keyserver URL as used in the @option{--keyserver} option
-  may be used here to query that particular keyserver.
+  In addition, a keyserver URL as used in the @command{dirmngr}
+  configuration may be used here to query that particular keyserver.
 
   @item local
   Locate the key using the local keyrings.  This mechanism allows the user to
@@ -1778,17 +1788,20 @@ mechanisms, in the order they are to be tried:
 
   @item clear
   Clear all defined mechanisms.  This is useful to override
-  mechanisms given in a config file.
+  mechanisms given in a config file.  Note that a @code{nodefault} in
+  @var{mechanisms} will also be cleared unless it is given after the
+  @code{clear}.
 
 @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
@@ -1883,32 +1896,12 @@ are available for all keyserver types, some common options are:
   retrieving keys by subkey id.
 
   @item timeout
-  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{--receive-keys}, the
-  timeout applies separately to each key retrieval, and not to the
-  @option{--receive-keys} command as a whole. Defaults to 30 seconds.
-
-  @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}.
-
-  @item verbose
-  This option has no more function since GnuPG 2.1.  Use the
-  @code{dirmngr} configuration options instead.
-
-  @item debug
-  This option has no more function since GnuPG 2.1.  Use the
-  @code{dirmngr} configuration options instead.
-
-  @item check-cert
-  This option has no more function since GnuPG 2.1.  Use the
-  @code{dirmngr} configuration options instead.
-
+  @itemx http-proxy=@var{value}
+  @itemx verbose
+  @itemx debug
+  @itemx check-cert
   @item ca-cert-file
-  This option has no more function since GnuPG 2.1.  Use the
+  These options have no more function since GnuPG 2.1.  Use the
   @code{dirmngr} configuration options instead.
 
 @end table
@@ -1972,6 +1965,9 @@ file name.
 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
@@ -2048,10 +2044,6 @@ place an unsafe gpg.conf file in place, and use this file to suppress
 warnings about itself. The @option{--homedir} permissions warning may only be
 suppressed on the command line.
 
-@item --no-mdc-warning
-@opindex no-mdc-warning
-Suppress the warning about missing MDC integrity protection.
-
 @item --require-secmem
 @itemx --no-require-secmem
 @opindex require-secmem
@@ -2209,8 +2201,8 @@ handy in case where an encrypted message contains a bogus key ID.
 @opindex skip-hidden-recipients
 @opindex no-skip-hidden-recipients
 During decryption skip all anonymous recipients.  This option helps in
-the case that people use the hidden recipients feature to hide there
-own encrypt-to key from others.  If oneself has many secret keys this
+the case that people use the hidden recipients feature to hide their
+own encrypt-to key from others.  If one has many secret keys this
 may lead to a major annoyance because all keys are tried in turn to
 decrypt something which was not really intended for it.  The drawback
 of this option is that it is currently not possible to decrypt a
@@ -2253,6 +2245,15 @@ works properly with such messages, there is often a desire to set a
 maximum file size that will be generated before processing is forced to
 stop by the OS limits. Defaults to 0, which means "no limit".
 
+@item --chunk-size @var{n}
+@opindex chunk-size
+The AEAD encryption mode encrypts the data in chunks so that a
+receiving side can check for transmission errors or tampering at the
+end of each chunk and does not need to delay this until all data has
+been received.  The used chunk size is 2^@var{n} byte.  The lowest
+allowed value for @var{n} is 6 (64 byte) and the largest is the
+default of 27 which creates chunks not larger than 128 MiB.
+
 @item --input-size-hint @var{n}
 @opindex input-size-hint
 This option can be used to tell GPG the size of the input data in
@@ -2306,7 +2307,9 @@ opposite meaning. The options are:
   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; the option @option{show-only} is a shortcut for this
-  combination.
+  combination.  The command @option{--show-keys} is another shortcut
+  for this.  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
@@ -2327,7 +2330,13 @@ opposite meaning. The options are:
   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
+  @item import-drop-uids
+  Do not import any user ids or their binding signatures.  This option
+  can be used to update only the subkeys or other non-user id related
+  information.
+
+  @item repair-keys
+  After import, fix various problems with the
   keys.  For example, this reorders signatures, and strips duplicate
   signatures.  Defaults to yes.
 
@@ -2417,6 +2426,11 @@ The available properties are:
   Boolean indicating whether a key or subkey is a secret one.
   (drop-subkey)
 
+  @item usage
+  A string indicating the usage flags for the subkey, from the
+  sequence ``ecsa?''.  For example, a subkey capable of just signing
+  and authentication would be an exact match for ``sa''. (drop-subkey)
+
   @item sig_created
   @itemx sig_created_d
   The first is the timestamp a signature packet was created.  The
@@ -2486,6 +2500,11 @@ opposite meaning.  The options are:
   running the @option{--edit-key} command "minimize" before export except
   that the local copy of the key is not modified. Defaults to no.
 
+  @item export-drop-uids
+  Do no export any user id or attribute packets or their associates
+  signatures.  Note that due to missing user ids the resulting output is
+  not strictly RFC-4880 compliant.
+
   @item export-pka
   Instead of outputting the key material output PKA records suitable
   to put into DNS zone files.  An ORIGIN line is printed before each
@@ -2589,18 +2608,25 @@ is the default.
 @itemx --no-force-v4-certs
 These options are obsolete and have no effect since GnuPG 2.1.
 
+@item --force-aead
+@opindex force-aead
+Force the use of AEAD encryption over MDC encryption.  AEAD is a
+modern and faster way to do authenticated encryption than the old MDC
+method.  See also options @option{--aead-algo} and
+@option{--chunk-size}.
+
+As of now this option requires the use of option @option{--rfc4880bis}
+to declare that a not yet standardized feature is used.
+
 @item --force-mdc
+@itemx --disable-mdc
 @opindex force-mdc
-Force the use of encryption with a modification detection code. This
-is always used with the newer ciphers (those with a blocksize greater
-than 64 bits), or if all of the recipient keys indicate MDC support in
-their feature flags.
-
-@item --disable-mdc
 @opindex disable-mdc
-Disable the use of the modification detection code. Note that by
-using this option, the encrypted message becomes vulnerable to a
-message modification attack.
+These options are obsolete and have no effect since GnuPG 2.2.8.  The
+MDC is always used unless the keys indicate that an AEAD algorithm can
+be used in which case AEAD is used.  But note: If the creation of a
+legacy non-MDC message is exceptionally required, the option
+@option{--rfc2440} allows for this.
 
 @item --disable-signer-uid
 @opindex disable-signer-uid
@@ -2620,6 +2646,16 @@ preferences, as GPG will only select an algorithm that is usable by
 all recipients.  The most highly ranked cipher in this list is also
 used for the @option{--symmetric} encryption command.
 
+@item --personal-aead-preferences @var{string}
+@opindex personal-aead-preferences
+Set the list of personal AEAD 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 cipher in this list is also
+used for the @option{--symmetric} encryption command.
+
 @item --personal-digest-preferences @var{string}
 @opindex personal-digest-preferences
 Set the list of personal digest preferences to @var{string}.  Use
@@ -2720,25 +2756,22 @@ keys or data may not be usable with future GnuPG versions.
 @item --rfc2440
 @opindex rfc2440
 Reset all packet, cipher and digest options to strict RFC-2440
-behavior.
+behavior.  Note that by using this option encryption packets are
+created in a legacy mode without MDC protection.  This is dangerous
+and should thus only be used for experiments.  See also option
+@option{--ignore-mdc-error}.
 
 @item --pgp6
 @opindex pgp6
-Set up all options to be as PGP 6 compliant as possible. This
-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
-@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}.
+This option is obsolete; it is handled as an alias for @option{--pgp7}
 
 @item --pgp7
 @opindex pgp7
-Set up all options to be as PGP 7 compliant as possible. This is
-identical to @option{--pgp6} except that MDCs are not disabled, and the
-list of allowable ciphers is expanded to add AES128, AES192, AES256, and
-TWOFISH.
+Set up all options to be as PGP 7 compliant as possible. This allowed
+the ciphers IDEA, 3DES, CAST5,AES128, AES192, AES256, and TWOFISH.,
+the hashes MD5, SHA1 and RIPEMD160, and the compression algorithms
+none and ZIP.  This option implies @option{--escape-from-lines} and
+disables @option{--throw-keyids},
 
 @item --pgp8
 @opindex pgp8
@@ -2826,6 +2859,19 @@ Set all useful debugging flags.
 Set stdout into line buffered mode.  This option is only honored when
 given on the command line.
 
+@item --debug-set-iobuf-size @var{n}
+@opindex debug-iolbf
+Change the buffer size of the IOBUFs to @var{n} kilobyte.  Using 0
+prints the current size.  Note well: This is a maintainer only option
+and may thus be changed or removed at any time without notice.
+
+@item --debug-allow-large-chunks
+@opindex debug-allow-large-chunks
+To facilitate in-memory decryption on the receiving site, the largest
+recommended chunk size is 128 MiB (@code{--chunk-size 27}).  This
+option allows to specify a limit of up to 4 EiB (@code{--chunk-size
+62}) for experiments.
+
 @item --faked-system-time @var{epoch}
 @opindex faked-system-time
 This option is only useful for testing; it sets the system time back or
@@ -2928,6 +2974,13 @@ smartcard, and "%%" results in a single "%". %k, %K, and %f are only
 meaningful when making a key signature (certification), and %c is only
 meaningful when using the OpenPGP smartcard.
 
+@item --known-notation @var{name}
+@opindex known-notation
+Adds @var{name} to a list of known critical signature notations.  The
+effect of this is that gpg will not mark a signature with a critical
+signature notation of that name as bad.  Note that gpg already knows
+by default about a few critical signatures notation names.
+
 @item --sig-policy-url @var{string}
 @itemx --cert-policy-url @var{string}
 @itemx --set-policy-url @var{string}
@@ -2970,7 +3023,8 @@ to display the message. This option overrides @option{--set-filename}.
 @itemx --no-use-embedded-filename
 @opindex use-embedded-filename
 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.
+a dangerous option as it enables overwriting files.  Defaults to no.
+Note that the option @option{--output} overrides this option.
 
 @item --cipher-algo @var{name}
 @opindex cipher-algo
@@ -2978,17 +3032,28 @@ 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
-it allows you to violate the OpenPGP standard.
+it allows you to violate the OpenPGP standard.  The option
 @option{--personal-cipher-preferences} is the safe way to accomplish the
 same thing.
 
+@item --aead-algo @var{name}
+@opindex aead-algo
+Specify that the AEAD algorithm @var{name} is to be used.  This is
+useful for symmetric encryption where no key preference are available
+to select the AEAD algorithm.  Running @command{@gpgname} with option
+@option{--version} shows the available AEAD algorithms.  In general,
+you do not want to use this option as it allows you to violate the
+OpenPGP standard.  The option @option{--personal-aead-preferences} is
+the safe way to accomplish the same thing.
+
 @item --digest-algo @var{name}
 @opindex digest-algo
 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.
+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.  The option
+@option{--personal-digest-preferences} is the safe way to accomplish
+the same thing.
 
 @item --compress-algo @var{name}
 @opindex compress-algo
@@ -3010,17 +3075,22 @@ significant in low memory situations. Note, however, that PGP (all
 versions) only supports ZIP compression. Using any algorithm other
 than ZIP or "none" will make the message unreadable with PGP. In
 general, you do not want to use this option as it allows you to
-violate the OpenPGP standard. @option{--personal-compress-preferences} is the
-safe way to accomplish the same thing.
+violate the OpenPGP standard.  The option
+@option{--personal-compress-preferences} is the safe way to accomplish
+the same thing.
 
 @item --cert-digest-algo @var{name}
 @opindex cert-digest-algo
 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.
+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.  Note also that a public key
+algorithm must be compatible with the specified digest algorithm; thus
+selecting an arbitrary digest algorithm may result in error messages
+from lower crypto layers or lead to security flaws.
+
 
 @item --disable-cipher-algo @var{name}
 @opindex disable-cipher-algo
@@ -3079,8 +3149,9 @@ 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.
+Note that since Version 2.0 this passphrase is only used if the
+option @option{--batch} has also been given. Since Version 2.1
+the @option{--pinentry-mode} also needs to be set to @code{loopback}.
 
 @item --passphrase-file @var{file}
 @opindex passphrase-file
@@ -3089,8 +3160,10 @@ 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.
+
+Note that since Version 2.0 this passphrase is only used if the
+option @option{--batch} has also been given. Since Version 2.1
+the @option{--pinentry-mode} also needs to be set to @code{loopback}.
 
 @item --passphrase @var{string}
 @opindex passphrase
@@ -3098,8 +3171,10 @@ 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.
+
+Note that since Version 2.0 this passphrase is only used if the
+option @option{--batch} has also been given. Since Version 2.1
+the @option{--pinentry-mode} also needs to be set to @code{loopback}.
 
 @item --pinentry-mode @var{mode}
 @opindex pinentry-mode
@@ -3119,6 +3194,21 @@ are:
   Pinentry the user is not prompted again if he enters a bad password.
 @end table
 
+@item --no-symkey-cache
+@opindex no-symkey-cache
+Disable the passphrase cache used for symmetrical en- and decryption.
+This cache is based on the message specific salt value
+(cf. @option{--s2k-mode}).
+
+@item --request-origin @var{origin}
+@opindex request-origin
+Tell gpg to assume that the operation ultimately originated at
+@var{origin}.  Depending on the origin certain restrictions are applied
+and the Pinentry may include an extra note on the origin.  Supported
+values for @var{origin} are: @code{local} which is the default,
+@code{remote} to indicate a remote origin or @code{browser} for an
+operation requested by a web browser.
+
 @item --command-fd @var{n}
 @opindex command-fd
 This is a replacement for the deprecated shared-memory IPC mode.
@@ -3172,10 +3262,11 @@ to ignore CRC errors.
 @item --ignore-mdc-error
 @opindex ignore-mdc-error
 This option changes a MDC integrity protection failure into a warning.
-This can be useful if a message is partially corrupt, but it is
-necessary to get as much data as possible out of the corrupt message.
-However, be aware that a MDC protection failure may also mean that the
-message was tampered with intentionally by an attacker.
+It is required to decrypt old messages which did not use an MDC.  It
+may also be useful if a message is partially garbled, but it is
+necessary to get as much data as possible out of that garbled message.
+Be aware that a missing or failed MDC can be an indication of an
+attack.  Use with great caution; see also option @option{--rfc2440}.
 
 @item --allow-weak-digest-algos
 @opindex allow-weak-digest-algos
@@ -3204,7 +3295,8 @@ secret keyrings.
 
 @item --no-keyring
 @opindex no-keyring
-Do not add use any keyrings even if specified as options.
+Do not use any keyring at all.  This overrides the default and all
+options which specify keyrings.
 
 @item --skip-verify
 @opindex skip-verify
@@ -3217,6 +3309,22 @@ verification is not needed.
 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.  This
+command can be used to create a list of signing keys missing in the
+local keyring; for example:
+
+@example
+      gpg --list-sigs --with-colons USERID | \
+        awk -F: '$1=="sig" && $2=="?" @{if($13)@{print $13@}else@{print $5@}@}'
+@end example
+
 @item --fast-list-mode
 @opindex fast-list-mode
 Changes the output of the list commands to work faster; this is achieved
@@ -3255,13 +3363,14 @@ user.
 @opindex override-session-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
+@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.
+table.  Often it is useful to combine this option with
+@option{--no-keyring}.
 
 @item --ask-sig-expire
 @itemx --no-ask-sig-expire
@@ -3298,9 +3407,14 @@ 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}.
+generation. The @var{string} is similar to the arguments required for
+the command @option{--quick-add-key} but slightly different.  For
+example the current default of @code{"rsa2048/cert,sign+rsa2048/encr"}
+(or @code{"rsa3072"}) can be changed to the value of what we currently
+call future default, which is @code{"ed25519/cert,sign+cv25519/encr"}.
+You need to consult the source code to learn the details.  Note that
+the advanced key generation commands can always be used to specify a
+key algorithm directly.
 
 @item --allow-secret-key-import
 @opindex allow-secret-key-import
@@ -3308,16 +3422,7 @@ This is an obsolete option and is not used anywhere.
 
 @item --allow-multiple-messages
 @item --no-allow-multiple-messages
-@opindex allow-multiple-messages
-Allow processing of multiple OpenPGP messages contained in a single file
-or stream.  Some programs that call GPG are not prepared to deal with
-multiple messages being processed together, so this option defaults to
-no.  Note that versions of GPG prior to 1.4.7 always allowed multiple
-messages.
-
-Warning: Do not use this option unless you need it as a temporary
-workaround!
-
+These are obsolete options; they have no more effect since GnuPG 2.2.8.
 
 @item --enable-special-filenames
 @opindex enable-special-filenames
@@ -3556,6 +3661,15 @@ Operation is further controlled by a few environment variables:
 
 @end table
 
+When calling the gpg-agent component @command{@gpgname} sends a set of
+environment variables to gpg-agent.  The names of these variables can
+be listed using the command:
+
+@example
+  gpg-connect-agent 'getinfo std_env_names' /bye | awk '$1=="D" @{print $2@}'
+@end example
+
+
 
 @c *******************************************
 @c ***************            ****************
@@ -3738,6 +3852,10 @@ which is equivalent to
 imports only the user ids of a key containing the strings "Alfa"
 or "Alpha" but not the string "test".
 
+@mansect trust values
+@ifset isman
+@include trust-values.texi
+@end ifset
 
 @mansect return value
 @chapheading RETURN VALUE
@@ -3761,6 +3879,19 @@ If you are going to verify detached signatures, make sure that the
 program knows about it; either give both filenames on the command line
 or use @samp{-} to specify STDIN.
 
+For scripted or other unattended use of @command{gpg} make sure to use
+the machine-parseable interface and not the default interface which is
+intended for direct use by humans.  The machine-parseable interface
+provides a stable and well documented API independent of the locale or
+future changes of @command{gpg}.  To enable this interface use the
+options @option{--with-colons} and @option{--status-fd}.  For certain
+operations the option @option{--command-fd} may come handy too.  See
+this man page and the file @file{DETAILS} for the specification of the
+interface.  Note that the GnuPG ``info'' pages as well as the PDF
+version of the GnuPG manual features a chapter on unattended use of
+GnuPG.  As an alternative the library @command{GPGME} can be used as a
+high-level abstraction on top of that interface.
+
 @mansect interoperability
 @chapheading INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS