doc: Show how to list envvars send to gpg-agent.
[gnupg.git] / doc / gpg.texi
index 908af7b..c4bc354 100644 (file)
@@ -328,7 +328,7 @@ 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
+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
@@ -353,6 +353,16 @@ 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
@@ -1040,38 +1050,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}
@@ -2066,10 +2051,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
@@ -2271,6 +2252,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
@@ -2324,7 +2314,8 @@ 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.  Note that suffixes like '#' for "sec" and "sbb" lines
+  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
@@ -2436,6 +2427,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
@@ -2608,18 +2604,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 encrytion 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
@@ -2639,6 +2642,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
@@ -2739,25 +2752,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 allowd
+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
@@ -2845,6 +2855,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
@@ -2947,6 +2970,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}
@@ -2997,17 +3027,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.  Runing @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
@@ -3029,8 +3070,9 @@ 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
@@ -3211,10 +3253,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
@@ -3263,8 +3306,14 @@ print the public key data.
 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.
+@option{--check-signatures} the key signatures are not verified.  This
+command can be used to create a list of signing keys missing in the
+lcoal 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
@@ -3348,7 +3397,7 @@ absolute date in the form YYYY-MM-DD. Defaults to "0".
 @opindex default-new-key-algo @var{string}
 This option can be used to change the default algorithms for key
 generation. The @var{string} is similar to the arguments required for
-the command @option{--quick-add-key} but slighly different.  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"}.
@@ -3362,16 +3411,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
@@ -3610,6 +3650,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 ***************            ****************
@@ -3792,6 +3841,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