doc: Clarify constraints on who modifies files in ~/.gnupg
[gnupg.git] / doc / gpg.texi
index d0da837..c0632b3 100644 (file)
@@ -3,10 +3,7 @@
 @c This is part of the GnuPG manual.
 @c For copying conditions, see the file gnupg.texi.
 
-@c Note that we use this texinfo file for all versions of GnuPG: 1.4.x,
-@c 2.0 and 2.1.  The macro "gpgone" controls parts which are only valid
-@c for GnuPG 1.4, the macro "gpgtwoone" controls parts which are only
-@c valid for GnupG 2.1 and later.
+@include defs.inc
 
 @node Invoking GPG
 @chapter Invoking GPG
 @cindex command options
 @cindex options, GPG command
 
-@c Begin GnuPG 1.x specific stuff
-@ifset gpgone
-@macro gpgname
-gpg
-@end macro
-@manpage gpg.1
-@ifset manverb
-.B gpg
-\- OpenPGP encryption and signing tool
-@end ifset
-
-@mansect synopsis
-@ifset manverb
-.B  gpg
-.RB [ \-\-homedir
-.IR dir ]
-.RB [ \-\-options
-.IR file ]
-.RI [ options ]
-.I command
-.RI [ args ]
-@end ifset
-@end ifset
-@c End GnuPG 1.x specific stuff
-
-@c Begin GnuPG 2 specific stuff
-@ifclear gpgone
 @macro gpgname
 gpg2
 @end macro
@@ -61,8 +31,7 @@ gpg2
 .I command
 .RI [ args ]
 @end ifset
-@end ifclear
-@c Begin GnuPG 2 specific stuff
+
 
 @mansect description
 @command{@gpgname} is the OpenPGP part of the GNU Privacy Guard (GnuPG). It
@@ -71,28 +40,17 @@ OpenPGP standard. @command{@gpgname} features complete key management and
 all bells and whistles you can expect from a decent OpenPGP
 implementation.
 
-@ifset gpgone
-This is the standalone version of @command{gpg}.  For desktop use you
-should consider using @command{gpg2} @footnote{On some platforms gpg2 is
-installed under the name @command{gpg}}.
-@end ifset
-
-@ifclear gpgone
-In contrast to the standalone version @command{gpg}, which is more
-suited for server and embedded platforms, this version is commonly
-installed under the name @command{gpg2} and more targeted to the desktop
-as it requires several other modules to be installed.  The standalone
-version will be kept maintained and it is possible to install both
-versions on the same system.  If you need to use different configuration
-files, you should make use of something like @file{gpg.conf-2} instead
-of just @file{gpg.conf}.
-@end ifclear
+In contrast to the standalone command gpg from GnuPG 1.x, which is
+might be better suited for server and embedded platforms, the 2.x
+version is commonly installed under the name @command{gpg2} and
+targeted to the desktop as it requires several other modules to be
+installed.
 
 @manpause
-@ifclear gpgone
-Documentation for the old standard @command{gpg} is available as a man
-page and at @inforef{Top,GnuPG 1,gpg}.
-@end ifclear
+The old 1.x version will be kept maintained and it is possible to
+install both versions on the same system.  Documentation for the old
+GnuPG 1.x command is available as a man page and at
+@inforef{Top,GnuPG 1,gpg}.
 
 @xref{Option Index}, for an index to @command{@gpgname}'s commands and options.
 @mancont
@@ -217,7 +175,7 @@ decrypted via a secret key or a passphrase).
 @itemx -c
 @opindex symmetric
 Encrypt with a symmetric cipher using a passphrase. The default
-symmetric cipher used is CAST5, but may be chosen with the
+symmetric cipher used is @value{GPGSYMENCALGO}, but may be chosen with the
 @option{--cipher-algo} option. This option 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
@@ -241,16 +199,22 @@ files which don't begin with an encrypted message.
 
 @item --verify
 @opindex verify
-Assume that the first argument is a signed file or a detached signature
-and verify it without generating any output. With no arguments, the
-signature packet is read from STDIN. If only a sigfile is given, it may
-be a complete signature or a detached signature, in which case the
-signed stuff is expected in a file without the ".sig" or ".asc"
-extension.  With more than 1 argument, the first should be a detached
-signature and the remaining files are the signed stuff. To read the
-signed stuff 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.
+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.
+
+With more than 1 argument, the first should be a detached signature
+and the remaining files ake 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.
+
+Note: If the option @option{--batch} is not used, @command{@gpgname}
+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.
 
 Note: When verifying a cleartext signature, @command{gpg} verifies
 only what makes up the cleartext signed data and not any extra data
@@ -287,12 +251,6 @@ Identical to @option{--multifile --decrypt}.
 @opindex list-keys
 List all keys from the public keyrings, or just the keys given on the
 command line.
-@ifset gpgone
-@option{-k} is slightly different from @option{--list-keys} in that it
-allows only for one argument and takes the second argument as the
-keyring to search.  This is for command line compatibility with PGP 2
-and has been removed in @command{gpg2}.
-@end ifset
 
 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
@@ -310,10 +268,8 @@ secret key is not usable (for example, if it was created via
 @item --list-sigs
 @opindex list-sigs
 Same as @option{--list-keys}, but the signatures are listed too.
-@ifclear gpgone
 This command has the same effect as
 using @option{--list-keys} with @option{--with-sig-list}.
-@end ifclear
 
 For each signature listed, there are several flags in between the "sig"
 tag and keyid. These flags give additional information about each
@@ -333,10 +289,8 @@ command "tsign").
 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.
-@ifclear gpgone
 This command has the same effect as
 using @option{--list-keys} with @option{--with-sig-check}.
-@end ifclear
 
 The status of the verification is indicated by a flag directly following
 the "sig" tag (and thus before the flags described above for
@@ -345,7 +299,6 @@ 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).
 
-@ifclear gpgone
 @item --locate-keys
 @opindex locate-keys
 Locate the keys given as arguments.  This command basically uses the
@@ -353,8 +306,6 @@ same algorithm as used when locating keys for encryption or signing and
 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.
-@end ifclear
-
 
 @item --fingerprint
 @opindex fingerprint
@@ -367,8 +318,9 @@ listed too.
 
 @item --list-packets
 @opindex list-packets
-List only the sequence of packets. This is mainly
-useful for debugging.
+List only the sequence of packets. This is mainly useful for
+debugging.  When used with option @option{--verbose} the actual MPI
+values are dumped and not only their lengths.
 
 
 @item --card-edit
@@ -376,7 +328,7 @@ useful for debugging.
 Present a menu to work with a smartcard. The subcommand "help" provides
 an overview on available commands. For a detailed description, please
 see the Card HOWTO at
-http://www.gnupg.org/documentation/howtos.html#GnuPG-cardHOWTO .
+https://gnupg.org/documentation/howtos.html#GnuPG-cardHOWTO .
 
 @item --card-status
 @opindex card-status
@@ -388,14 +340,14 @@ 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.
 
-@item --delete-key @code{name}
-@opindex delete-key
+@item --delete-keys @code{name}
+@itemx --delete-keys @code{name}
 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-key @code{name}
-@opindex delete-secret-key
+@item --delete-secret-keys @code{name}
+@opindex delete-secret-keys
 Remove key from the secret keyring. In batch mode the key
 must be specified by fingerprint.
 
@@ -440,15 +392,9 @@ 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.
 
-@ifset gpgtwoone
 GnuPG may ask you to enter the passphrase for the key.  This is
 required because the internal protection method of the secret key is
 different from the one specified by the OpenPGP protocol.
-@end ifset
-@ifclear gpgtwoone
-See the option @option{--simple-sk-checksum} if you want to import an
-exported secret key into ancient OpenPGP implementations.
-@end ifclear
 
 @item --import
 @itemx --fast-import
@@ -579,6 +525,12 @@ Use the source, Luke :-). The output format is still subject to change.
 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.
 
+
+@c @item --server
+@c @opindex server
+@c Run gpg in server mode.  This feature is not yet ready for use and
+@c thus not documented.
+
 @end table
 
 
@@ -592,10 +544,9 @@ This section explains the main commands for key management
 
 @table @gnupgtabopt
 
-@ifset gpgtwoone
 @item --quick-gen-key @code{user-id}
 @opindex quick-gen-key
-This is simple command to generate a standard key with one user id.
+This is simple command to generate a standard key with one user id.
 In contrast to @option{--gen-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
@@ -605,16 +556,28 @@ 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
 force the creation of the key will show up.
-@end ifset
+
+If this command is used with @option{--batch},
+@option{--pinentry-mode} has been set to @code{loopback}, and one of
+the passphrase options (@option{--passphrase},
+@option{--passphrase-fd}, or @option{passphrase-file}) is used, the
+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.
 
 @item --gen-key
 @opindex gen-key
-Generate a new key pair. This command is normally only used
-interactively.
+Generate a new key pair using teh current default parameters.  This is
+the standard command to create a new key.
+
+@item --full-gen-key
+@opindex gen-key
+Generate a new key pair with dialogs for all options.  This is an
+extended version of @option{--gen-key}.
 
 There is also a feature which allows you to create keys in batch
-mode. See the file @file{doc/DETAILS} in the source distribution on
-how to use this.
+mode. See the the manual section ``Unattended key generation'' on how
+to use this.
 
 @item --gen-revoke @code{name}
 @opindex gen-revoke
@@ -817,7 +780,7 @@ create a signature of any type desired.
 
   @item delkey
   @opindex keyedit:delkey
-  Remove a subkey (secondart key). Note that it is not possible to retract
+  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}.
 
@@ -937,9 +900,8 @@ 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}.
 
-@ifset gpgtwoone
 @item --quick-sign-key @code{fpr} [@code{names}]
-@itemx --quick-lsign-key @code{name}
+@itemx --quick-lsign-key @code{fpr} [@code{names}]
 @opindex quick-sign-key
 @opindex quick-lsign-key
 Directly sign a key from the passphrase without any further user
@@ -953,17 +915,22 @@ such a non-exportable signature already exists the
 
 This command uses reasonable defaults and thus does not provide the
 full flexibility of the "sign" subcommand from @option{--edit-key}.
-Its intended use to help unattended signing using a list of verified
-fingerprints.
-@end ifset
+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
+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.
 
-@ifclear gpgone
 @item --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
 @code{passwd} of the edit key menu.
-@end ifclear
 
 @end table
 
@@ -1216,6 +1183,15 @@ the opposite meaning. The options are:
   validation. This option is only meaningful if pka-lookups is set.
 @end table
 
+@item --enable-large-rsa
+@itemx --disable-large-rsa
+@opindex enable-large-rsa
+@opindex disable-large-rsa
+With --gen-key and --batch, enable the creation of larger RSA secret
+keys than is generally recommended (up to 8192 bits).  These large
+keys are more expensive to use, and their signatures and
+certifications are also larger.
+
 @item --enable-dsa2
 @itemx --disable-dsa2
 @opindex enable-dsa2
@@ -1266,7 +1242,8 @@ use the specified keyring alone, use @option{--keyring} along with
 
 @item --secret-keyring @code{file}
 @opindex secret-keyring
-Same as @option{--keyring} but for the secret keyrings.
+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}
 @opindex primary-keyring
@@ -1282,41 +1259,9 @@ 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
 not used).
 
-@ifset gpgone
-@anchor{option --homedir}
-@end ifset
 @include opt-homedir.texi
 
 
-@ifset gpgone
-@item --pcsc-driver @code{file}
-@opindex pcsc-driver
-Use @code{file} to access the smartcard reader. The current default is
-`libpcsclite.so.1' for GLIBC based systems,
-`/System/Library/Frameworks/PCSC.framework/PCSC' for MAC OS X,
-`winscard.dll' for Windows and `libpcsclite.so' for other systems.
-@end ifset
-
-@ifset gpgone
-@item --disable-ccid
-@opindex disable-ccid
-Disable the integrated support for CCID compliant readers. This
-allows to fall back to one of the other drivers even if the internal
-CCID driver can handle the reader. Note, that CCID support is only
-available if libusb was available at build time.
-@end ifset
-
-@ifset gpgone
-@item --reader-port @code{number_or_string}
-@opindex reader-port
-This option may be used to specify the port of the card terminal. A
-value of 0 refers to the first serial device; add 32768 to access USB
-devices. The default is 32768 (first USB device). PC/SC or CCID
-readers might need a string here; run the program in verbose mode to get
-a list of available readers. The default is then the first reader
-found.
-@end ifset
-
 @item --display-charset @code{name}
 @opindex display-charset
 Set the name of the native character set. This is used to convert
@@ -1476,7 +1421,7 @@ Set what trust model GnuPG should follow. The models are:
 
   @item classic
   @opindex trust-mode:classic
-  This is the standard Web of Trust as used in PGP 2.x and earlier.
+  This is the standard Web of Trust as introduced by PGP 2.
 
   @item direct
   @opindex trust-mode:direct
@@ -1486,7 +1431,7 @@ Set what trust model GnuPG should follow. The models are:
   @item always
   @opindex trust-mode:always
   Skip key validation and assume that used keys are always fully
-  trusted. You generally won't use this unless you are using some
+  valid. You generally won't use this unless you are using some
   external validation scheme. This option also suppresses the
   "[uncertain]" tag printed with signature checks when there is no
   evidence that the user ID is bound to the key.  Note that this
@@ -1576,7 +1521,7 @@ need to send keys to more than one server. The keyserver
 @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 @code{name=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
@@ -1617,33 +1562,20 @@ are available for all keyserver types, some common options are:
   keyserver URL, then use that preferred keyserver to refresh the key
   from. In addition, if auto-key-retrieve is set, and the signature
   being verified has a preferred keyserver URL, then use that preferred
-  keyserver to fetch the key from. Defaults to yes.
+  keyserver to fetch the key from. Note that this option introduces a
+  "web bug": The creator of the key can see when the keys is
+  refreshed.  Thus this option is not enabled by default.
 
   @item honor-pka-record
   If auto-key-retrieve is set, and the signature being verified has a
   PKA record, then use the PKA information to fetch the key. Defaults
-  to yes.
+  to "yes".
 
   @item include-subkeys
   When receiving a key, include subkeys as potential targets. Note that
   this option is not used with HKP keyservers, as they do not support
   retrieving keys by subkey id.
 
-  @item use-temp-files
-  On most Unix-like platforms, GnuPG communicates with the keyserver
-  helper program via pipes, which is the most efficient method. This
-  option forces GnuPG to use temporary files to communicate. On some
-  platforms (such as Win32 and RISC OS), this option is always enabled.
-
-  @item keep-temp-files
-  If using `use-temp-files', do not delete the temp files after using
-  them. This option is useful to learn the keyserver communication
-  protocol by reading the temporary files.
-
-  @item verbose
-  Tell the keyserver helper program to be more verbose. This option can
-  be repeated multiple times to increase the verbosity level.
-
   @item timeout
   Tell the keyserver helper program how long (in seconds) to try and
   perform a keyserver action before giving up. Note that performing
@@ -1653,45 +1585,24 @@ are available for all keyserver types, some common options are:
   @option{--recv-keys} command as a whole. Defaults to 30 seconds.
 
   @item http-proxy=@code{value}
-  Set the proxy to use for HTTP and HKP keyservers.  This overrides the
-  "http_proxy" environment variable, if any.
-
+  Set the proxy to use for HTTP and HKP keyservers.
+  This overrides any proxy defined in @file{dirmngr.conf}.
 
-@ifclear gpgtwoone
-  @item max-cert-size
-  When retrieving a key via DNS CERT, only accept keys up to this size.
-  Defaults to 16384 bytes.
-@end ifclear
+  @item verbose
+  This option has no more function since GnuPG 2.1.  Use the
+  @code{dirmngr} configuration options instead.
 
   @item debug
-  Turn on debug output in the keyserver helper program.  Note that the
-  details of debug output depends on which keyserver helper program is
-  being used, and in turn, on any libraries that the keyserver helper
-  program uses internally (libcurl, openldap, etc).
+  This option has no more function since GnuPG 2.1.  Use the
+  @code{dirmngr} configuration options instead.
 
   @item check-cert
-@ifset gpgtwoone
   This option has no more function since GnuPG 2.1.  Use the
   @code{dirmngr} configuration options instead.
-@end ifset
-@ifclear gpgtwoone
-  Enable certificate checking if the keyserver presents one (for hkps or
-  ldaps).  Defaults to on.
-@end ifclear
 
   @item ca-cert-file
-@ifset gpgtwoone
   This option has no more function since GnuPG 2.1.  Use the
   @code{dirmngr} configuration options instead.
-@end ifset
-@ifclear gpgtwoone
-  Provide a certificate store to override the system default.  Only
-  necessary if check-cert is enabled, and the keyserver is using a
-  certificate that is not present in a system default certificate list.
-
-  Note that depending on the SSL library that the keyserver helper is
-  built with, this may actually be a directory or a file.
-@end ifclear
 
 @end table
 
@@ -1709,20 +1620,6 @@ key signer (defaults to 3)
 @opindex max-cert-depth
 Maximum depth of a certification chain (default is 5).
 
-@ifclear gpgtwoone
-@item --simple-sk-checksum
-@opindex simple-sk-checksum
-Secret keys are integrity protected by using a SHA-1 checksum. This
-method is part of the upcoming enhanced OpenPGP specification but
-GnuPG already uses it as a countermeasure against certain attacks.
-Old applications don't understand this new format, so this option may
-be used to switch back to the old behaviour. Using this option bears
-a security risk. Note that using this option only takes effect when
-the secret key is encrypted - the simplest way to make this happen is
-to change the passphrase on the key (even changing it to the same
-value is acceptable).
-@end ifclear
-
 @item --no-sig-cache
 @opindex no-sig-cache
 Do not cache the verification status of key signatures.
@@ -1752,45 +1649,35 @@ process. @option{--no-auto-check-trustdb} disables this option.
 @item --use-agent
 @itemx --no-use-agent
 @opindex use-agent
-@ifclear gpgone
 This is dummy option. @command{@gpgname} always requires the agent.
-@end ifclear
-@ifset gpgone
-Try to use the GnuPG-Agent.  With this option, GnuPG first tries to
-connect to the agent before it asks for a
-passphrase. @option{--no-use-agent} disables this option.
-@end ifset
 
 @item --gpg-agent-info
 @opindex gpg-agent-info
-@ifclear gpgone
 This is dummy option. It has no effect when used with @command{gpg2}.
-@end ifclear
-@ifset gpgone
-Override the value of the environment variable
-@samp{GPG_AGENT_INFO}. This is only used when @option{--use-agent} has
-been given.  Given that this option is not anymore used by
-@command{gpg2}, it should be avoided if possible.
-@end ifset
 
 
-@ifclear gpgone
 @item --agent-program @var{file}
 @opindex agent-program
 Specify an agent program to be used for secret key operations.  The
-default value is the @file{/usr/bin/gpg-agent}.  This is only used
-as a fallback when the environment variable @code{GPG_AGENT_INFO} is not
-set or a running agent cannot be connected.
-@end ifclear
+default value is determined by running @command{gpgconf} with the
+option @option{--list-dirs}.  Note that the pipe symbol (@code{|}) is
+used for a regression test suite hack and may thus not be used in the
+file name.
 
-@ifset gpgtwoone
 @item --dirmngr-program @var{file}
 @opindex dirmngr-program
 Specify a dirmngr program to be used for keyserver access.  The
-default value is @file{/usr/sbin/dirmngr}.  This is only used as a
+default value is @file{@value{BINDIR}/dirmngr}.  This is only used as a
 fallback when the environment variable @code{DIRMNGR_INFO} is not set or
 a running dirmngr cannot be connected.
-@end ifset
+
+@item --no-autostart
+@opindex no-autostart
+Do not start the gpg-agent or the dirmngr if it has not yet been
+started and its service is required.  This option is mostly useful on
+machines where the connection to gpg-agent has been redirected to
+another machines.  If dirmngr is required on the remote machine, it
+may be started manually using @command{gpgconf --launch dirmngr}.
 
 @item --lock-once
 @opindex lock-once
@@ -1971,7 +1858,6 @@ Remove all entries from the @option{--group} list.
 Use @var{name} as the key to sign with. Note that this option overrides
 @option{--default-key}.
 
-@ifset gpgtwoone
 @item --try-secret-key @var{name}
 @opindex try-secret-key
 For hidden recipients GPG needs to know the keys to use for trial
@@ -1983,7 +1869,6 @@ the long keyid to avoid ambiguities.  Note that gpg-agent might pop up a
 pinentry for a lot keys to do the trial decryption.  If you want to stop
 all further trial decryption you may use close-window button instead of
 the cancel button.
-@end ifset
 
 @item --try-all-secrets
 @opindex try-all-secrets
@@ -2001,7 +1886,7 @@ 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
 may lead to a major annoyance because all keys are tried in turn to
-decrypt soemthing which was not really intended for it.  The drawback
+decrypt something which was not really intended for it.  The drawback
 of this option is that it is currently not possible to decrypt a
 message which includes real anonymous recipients.
 
@@ -2054,6 +1939,15 @@ opposite meaning. The options are:
   generally useful unless a shared keyring scheme is being used.
   Defaults to no.
 
+  @item keep-ownertrust
+  Normally possible still existing ownertrust values of a key are
+  cleared if a key is imported.  This is in general desirable so that
+  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
+  this option.
+
   @item repair-pks-subkey-bug
   During import, attempt to repair the damage caused by the PKS keyserver
   bug (pre version 0.9.6) that mangles keys with multiple subkeys. Note
@@ -2105,15 +1999,13 @@ opposite meaning. The options are:
 
   @c Since GnuPG 2.1 gpg-agent manages the secret key and thus the
   @c export-reset-subkey-passwd hack is not anymore justified.  Such use
-  @c cases need to be implemented using a specialized secret key export
+  @c cases may be implemented using a specialized secret key export
   @c tool.
-@ifclear gpgtwoone
-  @item export-reset-subkey-passwd
-  When using the @option{--export-secret-subkeys} command, this option resets
-  the passphrases for all exported subkeys to empty. This is useful
-  when the exported subkey is to be used on an unattended machine where
-  a passphrase doesn't necessarily make sense. Defaults to no.
-@end ifclear
+  @c @item export-reset-subkey-passwd
+  @c When using the @option{--export-secret-subkeys} command, this option resets
+  @c the passphrases for all exported subkeys to empty. This is useful
+  @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 export-clean
   Compact (remove all signatures from) user IDs on the key being
@@ -2140,30 +2032,36 @@ as it is easily machine parsed. The details of this format are
 documented in the file @file{doc/DETAILS}, which is included in the GnuPG
 source distribution.
 
+
+@item --print-pka-records
+@opindex print-pka-records
+Modify the output of the list commands to print PKA records suitable
+to put into DNS zone files.  An ORIGIN line is printed before each
+record to allow diverting the records to the corresponding zone file.
+
 @item --fixed-list-mode
 @opindex fixed-list-mode
 Do not merge primary user ID and primary key in @option{--with-colon}
 listing mode and print all timestamps as seconds since 1970-01-01.
-@ifclear gpgone
 Since GnuPG 2.0.10, this mode is always used and thus this option is
 obsolete; it does not harm to use it though.
-@end ifclear
 
-@ifset gpgtwoone
 @item --legacy-list-mode
 @opindex legacy-list-mode
 Revert to the pre-2.1 public key list mode.  This only affects the
 human readable output and not the machine interface
 (i.e. @code{--with-colons}).  Note that the legacy format does not
 allow to convey suitable information for elliptic curves.
-@end ifset
 
 @item --with-fingerprint
 @opindex with-fingerprint
 Same as the command @option{--fingerprint} but changes only the format
 of the output and may be used together with another command.
 
-@ifset gpgtwoone
+@item --with-icao-spelling
+@opindex with-icao-spelling
+Print the ICAO spelling of the fingerprint in addition to the hex digits.
+
 @item --with-keygrip
 @opindex with-keygrip
 Include the keygrip in the key listings.
@@ -2173,8 +2071,6 @@ Include the keygrip in the key listings.
 Include info about the presence of a secret key in public key listings
 done with @code{--with-colons}.
 
-@end ifset
-
 @end table
 
 @c *******************************************
@@ -2197,32 +2093,11 @@ platforms that have different line ending conventions (UNIX-like to Mac,
 Mac to Windows, etc). @option{--no-textmode} disables this option, and
 is the default.
 
-@ifset gpgone
-If @option{-t} (but not @option{--textmode}) is used together with
-armoring and signing, this enables clearsigned messages. This kludge is
-needed for command-line compatibility with command-line versions of PGP;
-normally you would use @option{--sign} or @option{--clearsign} to select
-the type of the signature.
-@end ifset
-
 @item --force-v3-sigs
 @itemx --no-force-v3-sigs
-@opindex force-v3-sigs
-OpenPGP states that an implementation should generate v4 signatures
-but PGP versions 5 through 7 only recognize v4 signatures on key
-material. This option forces v3 signatures for signatures on data.
-Note that this option implies @option{--no-ask-sig-expire}, and unsets
-@option{--sig-policy-url}, @option{--sig-notation}, and
-@option{--sig-keyserver-url}, as these features cannot be used with v3
-signatures.  @option{--no-force-v3-sigs} disables this option.
-Defaults to no.
-
 @item --force-v4-certs
 @itemx --no-force-v4-certs
-@opindex force-v4-certs
-Always use v4 key signatures even on v3 keys. This option also
-changes the default hash algorithm for v3 RSA keys from MD5 to SHA-1.
-@option{--no-force-v4-certs} disables this option.
+These options are obsolete and have no effect since GnuPG 2.1.
 
 @item --force-mdc
 @opindex force-mdc
@@ -2272,9 +2147,10 @@ to consider (e.g. @option{--symmetric}).
 @item --s2k-cipher-algo @code{name}
 @opindex s2k-cipher-algo
 Use @code{name} as the cipher algorithm used to protect secret keys.
-The default cipher is CAST5. This cipher is also used for
-conventional encryption if @option{--personal-cipher-preferences} and
-@option{--cipher-algo} is not given.
+The default cipher is @value{GPGSYMENCALGO}. This cipher is also used
+for symmetric encryption with a passphrase if
+@option{--personal-cipher-preferences} and @option{--cipher-algo} is
+not given.
 
 @item --s2k-digest-algo @code{name}
 @opindex s2k-digest-algo
@@ -2287,7 +2163,7 @@ Selects how passphrases are mangled. If @code{n} is 0 a plain
 passphrase (which is not recommended) will be used, a 1 adds a salt to
 the passphrase and a 3 (the default) iterates the whole process a
 number of times (see --s2k-count).  Unless @option{--rfc1991} is used,
-this mode is also used for conventional encryption.
+this mode is also used for symmetric encryption with a passphrase.
 
 @item --s2k-count @code{n}
 @opindex s2k-count
@@ -2342,9 +2218,11 @@ behavior. Note that this is currently the same thing as
 Reset all packet, cipher and digest options to strict RFC-2440
 behavior.
 
+@ifclear gpgtowone
 @item --rfc1991
 @opindex rfc1991
-Try to be more RFC-1991 (PGP 2.x) compliant.
+Try to be more RFC-1991 (PGP 2.x) compliant.  This option is
+deprecated will be removed in GnuPG 2.1.
 
 @item --pgp2
 @opindex pgp2
@@ -2355,18 +2233,17 @@ a message that PGP 2.x will not be able to handle. Note that `PGP
 available, but the MIT release is a good common baseline.
 
 This option implies
-@ifset gpgone
-@option{--rfc1991 --disable-mdc --no-force-v4-certs
- --escape-from-lines  --force-v3-sigs
- --cipher-algo IDEA --digest-algo MD5 --compress-algo ZIP}.
-@end ifset
-@ifclear gpgone
 @option{--rfc1991 --disable-mdc --no-force-v4-certs
  --escape-from-lines  --force-v3-sigs --allow-weak-digest-algos
  --cipher-algo IDEA --digest-algo MD5 --compress-algo ZIP}.
-@end ifclear
 It also disables @option{--textmode} when encrypting.
 
+This option is deprecated will be removed in GnuPG 2.1.  The reason
+for dropping PGP-2 support is that the PGP 2 format is not anymore
+considered safe (for example due to the use of the broken MD5 algorithm).
+Note that the decryption of PGP-2 created messages will continue to work.
+@end ifclear
+
 @item --pgp6
 @opindex pgp6
 Set up all options to be as PGP 6 compliant as possible. This
@@ -2376,8 +2253,7 @@ compression algorithms none and ZIP. This also disables
 --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
---force-v3-sigs}.
+This option implies @option{--disable-mdc --escape-from-lines}.
 
 @item --pgp7
 @opindex pgp7
@@ -2452,19 +2328,19 @@ however carefully selected to best aid in debugging.
 
 @item --debug @var{flags}
 @opindex debug
-Set debugging flags. All flags are or-ed and @var{flags} may
-be given in C syntax (e.g. 0x0042).
+Set debugging flags. All flags are or-ed and @var{flags} may be given
+in C syntax (e.g. 0x0042) or as a comma separated list of flag names.
+To get a list of all supported flags the single word "help" can be
+used.
 
 @item --debug-all
 @opindex debug-all
 Set all useful debugging flags.
 
-@ifset gpgone
-@item --debug-ccid-driver
-@opindex debug-ccid-driver
-Enable debug output from the included CCID driver for smartcards.
-Note that this option is only available on some system.
-@end ifset
+@item --debug-iolbf
+@opindex debug-iolbf
+Set stdout into line buffered mode.  This option is only honored when
+given on the command line.
 
 @item --faked-system-time @var{epoch}
 @opindex faked-system-time
@@ -2715,10 +2591,9 @@ 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},
 the passphrase will be read from STDIN. This can only be used if only
 one passphrase is supplied.
-@ifclear gpgone
+
 Note that this passphrase is only used if the option @option{--batch}
-has also been given.  This is different from @command{gpg}.
-@end ifclear
+has also been given.  This is different from GnuPG version 1.x.
 
 @item --passphrase-file @code{file}
 @opindex passphrase-file
@@ -2727,10 +2602,8 @@ be read from file @code{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.
-@ifclear gpgone
 Note that this passphrase is only used if the option @option{--batch}
-has also been given.  This is different from @command{gpg}.
-@end ifclear
+has also been given.  This is different from GnuPG version 1.x.
 
 @item --passphrase @code{string}
 @opindex passphrase
@@ -2738,12 +2611,9 @@ Use @code{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.
-@ifclear gpgone
 Note that this passphrase is only used if the option @option{--batch}
-has also been given.  This is different from @command{gpg}.
-@end ifclear
+has also been given.  This is different from GnuPG version 1.x.
 
-@ifset gpgtwoone
 @item --pinentry-mode @code{mode}
 @opindex pinentry-mode
 Set the pinentry mode to @code{mode}.  Allowed values for @code{mode}
@@ -2761,7 +2631,6 @@ are:
   Redirect Pinentry queries to the caller.  Note that in contrast to
   Pinentry the user is not prompted again if he enters a bad password.
 @end table
-@end ifset
 
 @item --command-fd @code{n}
 @opindex command-fd
@@ -2821,13 +2690,11 @@ 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.
 
-@ifclear gpgone
 @item --allow-weak-digest-algos
 @opindex allow-weak-digest-algos
 Signatures made with the broken MD5 algorithm are normally rejected
 with an ``invalid digest algorithm'' message.  This option allows the
 verification of signatures made with such weak algorithms.
-@end ifclear
 
 @item --no-default-keyring
 @opindex no-default-keyring
@@ -2873,8 +2740,13 @@ Display the session key used for one message. See
 We think that Key Escrow is a Bad Thing; however the user should have
 the freedom to decide whether to go to prison or to reveal the content
 of one specific message without compromising all messages ever
-encrypted for one secret key. DON'T USE IT UNLESS YOU ARE REALLY
-FORCED TO DO SO.
+encrypted for one secret key.
+
+You can also use this option if you receive an encrypted message which
+is abusive or offensive, to prove to the administrators of the
+messaging system that the ciphertext transmitted corresponds to an
+inappropriate plaintext so they can take action against the offending
+user.
 
 @item --override-session-key @code{string}
 @opindex override-session-key
@@ -2970,6 +2842,10 @@ source distribution for the details of which configuration items may be
 listed. @option{--list-config} is only usable with
 @option{--with-colons} set.
 
+@item --list-gcrypt-config
+@opindex list-gcrypt-config
+Display various internal configuration parameters of Libgcrypt.
+
 @item --gpgconf-list
 @opindex gpgconf-list
 This command is similar to @option{--list-config} but in general only
@@ -2992,15 +2868,6 @@ on the configuration file.
 
 @table @gnupgtabopt
 
-@ifset gpgone
-@item --load-extension @code{name}
-@opindex load-extension
-Load an extension module. If @code{name} does not contain a slash it is
-searched for in the directory configured when GnuPG was built
-(generally "/usr/local/lib/gnupg"). Extensions are not generally
-useful anymore, and the use of this option is deprecated.
-@end ifset
-
 @item --show-photos
 @itemx --no-show-photos
 @opindex show-photos
@@ -3017,14 +2884,6 @@ Display the keyring name at the head of key listings to show which
 keyring a given key resides on. This option is deprecated: use
 @option{--list-options [no-]show-keyring} instead.
 
-@ifset gpgone
-@item --ctapi-driver @code{file}
-@opindex ctapi-driver
-Use @code{file} to access the smartcard reader. The current default
-is `libtowitoko.so'. Note that the use of this interface is
-deprecated; it may be removed in future releases.
-@end ifset
-
 @item --always-trust
 @opindex always-trust
 Identical to @option{--trust-model always}. This option is deprecated.
@@ -3077,16 +2936,14 @@ current home directory (@pxref{option --homedir}).
 
 @c man:.RE
 Note that on larger installations, it is useful to put predefined files
-into the directory @file{/etc/skel/.gnupg/} so that newly created users
-start up with a working configuration.
-@ifclear gpgone
-For existing users the a small
+into the directory @file{@value{SYSCONFSKELDIR}} so that
+newly created users start up with a working configuration.
+For existing users a small
 helper script is provided to create these files (@pxref{addgnupghome}).
-@end ifclear
 
 For internal purposes @command{@gpgname} creates and maintains a few other
 files; They all live in in the current home directory (@pxref{option
---homedir}).  Only the @command{@gpgname} may modify these files.
+--homedir}).  Only the @command{@gpgname} program may modify these files.
 
 
 @table @file
@@ -3096,26 +2953,19 @@ files; They all live in in the current home directory (@pxref{option
   @item ~/.gnupg/pubring.gpg.lock
   The lock file for the public keyring.
 
-@ifset gpgtwoone
   @item ~/.gnupg/pubring.kbx
   The public keyring using a different format.  This file is sharred
   with @command{gpgsm}.  You should backup this file.
 
   @item ~/.gnupg/pubring.kbx.lock
   The lock file for @file{pubring.kbx}.
-@end ifset
 
   @item ~/.gnupg/secring.gpg
-@ifclear gpgtwoone
-  The secret keyring.  You should backup this file.
-@end ifclear
-@ifset gpgtwoone
   A secret keyring as used by GnuPG versions before 2.1.  It is not
   used by GnuPG 2.1 and later.
 
   @item ~/.gnupg/.gpg-v21-migrated
-  File indicating that a migration to GnuPG 2.1 has taken place.
-@end ifset
+  File indicating that a migration to GnuPG 2.1 has been done.
 
   @item ~/.gnupg/trustdb.gpg
   The trust database.  There is no need to backup this file; it is better
@@ -3132,17 +2982,18 @@ files; They all live in in the current home directory (@pxref{option
 
   @item ~/.gnupg/openpgp-revocs.d/
   This is the directory where gpg stores pre-generated revocation
-  certificates.  It is suggested to backup those certificates and if the
-  primary private key is not stored on the disk to move them to an
-  external storage device.  Anyone who can access theses files is able to
-  revoke the corresponding key.  You may want to print them out.  You
-  should backup all files in this directory and take care to keep this
-  backup closed away.
-
-  @item /usr[/local]/share/gnupg/options.skel
+  certificates.  The file name corresponds to the OpenPGP fingerprint of
+  the respective key.  It is suggested to backup those certificates and
+  if the primary private key is not stored on the disk to move them to
+  an external storage device.  Anyone who can access theses files is
+  able to revoke the corresponding key.  You may want to print them out.
+  You should backup all files in this directory and take care to keep
+  this backup closed away.
+
+  @item @value{DATADIR}/options.skel
   The skeleton options file.
 
-  @item /usr[/local]/lib/gnupg/
+  @item @value{LIBDIR}/
   Default location for extensions.
 
 @end table
@@ -3159,15 +3010,7 @@ Operation is further controlled by a few environment variables:
   If set directory used instead of "~/.gnupg".
 
   @item GPG_AGENT_INFO
-  Used to locate the gpg-agent.
-@ifset gpgone
-  This is only honored when @option{--use-agent} is set.
-@end ifset
-  The value consists of 3 colon delimited fields: The first is the path
-  to the Unix Domain Socket, the second the PID of the gpg-agent and the
-  protocol version which should be set to 1. When starting the gpg-agent
-  as described in its documentation, this variable is set to the correct
-  value. The option @option{--gpg-agent-info} can be used to override it.
+  This variable was used by GnuPG versions before 2.1
 
   @item PINENTRY_USER_DATA
   This value is passed via gpg-agent to pinentry.  It is useful to convey
@@ -3399,17 +3242,9 @@ control statements must be given. For GnuPG 2.1 and later
 
 @item %ask-passphrase
 @itemx %no-ask-passphrase
-Enable (or disable) a mode where the command @option{passphrase} is
-ignored and instead the usual passphrase dialog is used.  This does
-not make sense for batch key generation; however the unattended key
-generation feature is also used by GUIs and this feature relinquishes
-the GUI from implementing its own passphrase entry code.  These are
-global control statements and affect all future key genrations.
+This option is a no-op for GnuPG 2.1 and later.
 
 @item %no-protection
-Since GnuPG version 2.1 it is not anymore possible to specify a
-passphrase for unattended key generation.  The passphrase command is
-simply ignored and @samp{%ask-passpharse} is thus implicitly enabled.
 Using this option allows the creation of keys without any passphrase
 protection.  This option is mainly intended for regression tests.
 
@@ -3467,8 +3302,8 @@ by running the command @samp{gpg2 --gpgconf-list}".
 Key usage lists for a subkey; similar to @samp{Key-Usage}.
 
 @item Passphrase: @var{string}
-If you want to specify a passphrase for the secret key,
-enter it here. Default is not to use any passphrase.
+If you want to specify a passphrase for the secret key, enter it here.
+Default is to use the Pinentry dialog to ask for a passphrase.
 
 @item Name-Real: @var{name}
 @itemx Name-Comment: @var{comment}
@@ -3488,7 +3323,7 @@ sense.  Although OpenPGP works with time intervals, GnuPG uses an
 absolute value internally and thus the last year we can represent is
 2105.
 
-@item  Ceation-Date: @var{iso-date}
+@item  Creation-Date: @var{iso-date}
 Set the creation date of the key as stored in the key information and
 which is also part of the fingerprint calculation.  Either a date like
 "1986-04-26" or a full timestamp like "19860426T042640" may be used.
@@ -3576,9 +3411,7 @@ these parameters:
 @mansect see also
 @ifset isman
 @command{gpgv}(1),
-@ifclear gpgone
 @command{gpgsm}(1),
 @command{gpg-agent}(1)
-@end ifclear
 @end ifset
 @include see-also-note.texi