gpg: New command --quick-adduid.
[gnupg.git] / doc / gpg.texi
index bc12cbc..887a624 100644 (file)
@@ -3,10 +3,9 @@
 @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.
+@c Note that we use this texinfo file for all GnuPG-2 branches.
+@c The macro "gpgtwoone" controls parts which are only
+@c valid for GnuPG 2.1 and later.
 
 @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
+@c Begin algorithm defaults
 
-@mansect synopsis
-@ifset manverb
-.B  gpg
-.RB [ \-\-homedir
-.IR dir ]
-.RB [ \-\-options
-.IR file ]
-.RI [ options ]
-.I command
-.RI [ args ]
-@end ifset
+@ifclear gpgtwoone
+@set DEFSYMENCALGO CAST5
+@end ifclear
+
+@ifset gpgtwoone
+@set DEFSYMENCALGO AES128
 @end ifset
-@c End GnuPG 1.x specific stuff
 
-@c Begin GnuPG 2 specific stuff
-@ifclear gpgone
+@c End algorithm defaults
+
+
 @macro gpgname
 gpg2
 @end macro
@@ -61,8 +46,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 +55,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 +190,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{DEFSYMENCALGO}, 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 +214,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 +266,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 +283,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 +304,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 +314,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 +321,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 +333,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 +343,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 +355,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.
 
@@ -408,8 +375,8 @@ removed first. In batch mode the key must be specified by fingerprint.
 @opindex export
 Either export all keys from all keyrings (default keyrings and those
 registered via option @option{--keyring}), or if at least one name is given,
-those of the given name. The new keyring is written to STDOUT or to the
-file given with option @option{--output}. Use together with
+those of the given name. The exported keys are written to STDOUT or to the
+file given with option @option{--output}.  Use together with
 @option{--armor} to mail those keys.
 
 @item --send-keys @code{key IDs}
@@ -424,14 +391,30 @@ or changed by you.  If no key IDs are given, @command{gpg} does nothing.
 @itemx --export-secret-subkeys
 @opindex export-secret-keys
 @opindex export-secret-subkeys
-Same as @option{--export}, but exports the secret keys instead.  This is
-normally not very useful and a security risk.  The second form of the
-command has the special property to render the secret part of the
-primary key useless; this is a GNU extension to OpenPGP and other
-implementations can not be expected to successfully import such a key.
+Same as @option{--export}, but exports the secret keys instead.  The
+exported keys are written to STDOUT or to the file given with option
+@option{--output}.  This command is often used along with the option
+@option{--armor} to allow easy printing of the key for paper backup;
+however the external tool @command{paperkey} does a better job for
+creating backups on paper.  Note that exporting a secret key can be a
+security risk if the exported keys are send over an insecure channel.
+
+The second form of the command has the special property to render the
+secret part of the primary key useless; this is a GNU extension to
+OpenPGP and other implementations can not be expected to successfully
+import such a key.  Its intended use is to generated a full key with
+an additional signing subkey on a dedicated machine and then using
+this command to export the key without the primary key to the main
+machine.
+
+@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 such
-an exported key with an older OpenPGP implementation.
+See the option @option{--simple-sk-checksum} if you want to import an
+exported secret key into ancient OpenPGP implementations.
 @end ifclear
 
 @item --import
@@ -563,6 +546,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
 
 
@@ -576,14 +565,44 @@ 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 a 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
+given user id already exists in the key ring.
+
+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.
+
+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.
+@end ifset
+
 @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.
 
-There is an experimental 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.
+@ifset gpgtwoone
+@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}.
+
+@end ifset
+There is also a feature which allows you to create keys in batch
+mode. See the the manual section ``Unattended key generation'' on how
+to use this.
 
 @item --gen-revoke @code{name}
 @opindex gen-revoke
@@ -786,7 +805,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}.
 
@@ -908,7 +927,7 @@ 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
@@ -916,21 +935,31 @@ interaction.  The @code{fpr} must be the verified primary fingerprint
 of a key in the local keyring. If no @code{names} are given, all
 useful user ids are signed; with given [@code{names}] only useful user
 ids matching one of theses names are signed.  The command
-@option{--quick-lsign-key} marks the signatures as non-exportable.
+@option{--quick-lsign-key} marks the signatures as non-exportable.  If
+such a non-exportable signature already exists the
+@option{--quick-sign-key} turns it into a exportable signature.
 
 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.
+Its intended use is to help unattended key signing by utilizing a list
+of verified fingerprints.
+@end ifset
+
+@ifset gpgtwoone
+@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.
 @end ifset
 
-@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
 
@@ -1063,6 +1092,13 @@ give the opposite meaning.  The options are:
   see @option{--attribute-fd} for the appropriate way to get photo data
   for scripts and other frontends.
 
+  @item show-usage
+  @opindex list-options:show-usage
+  Show usage information for keys and subkeys in the standard key
+  listing.  This is a list of letters indicating the allowed usage for a
+  key (@code{E}=encryption, @code{S}=signing, @code{C}=certification,
+  @code{A}=authentication).  Defaults to no.
+
   @item show-policy-urls
   @opindex list-options:show-policy-urls
   Show policy URLs in the @option{--list-sigs} or @option{--check-sigs}
@@ -1176,6 +1212,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
@@ -1226,7 +1271,13 @@ use the specified keyring alone, use @option{--keyring} along with
 
 @item --secret-keyring @code{file}
 @opindex secret-keyring
+@ifset gpgtwoone
+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.
+@end ifset
+@ifclear gpgtwoone
 Same as @option{--keyring} but for the secret keyrings.
+@end ifclear
 
 @item --primary-keyring @code{file}
 @opindex primary-keyring
@@ -1242,41 +1293,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
@@ -1436,7 +1455,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
@@ -1446,7 +1465,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
@@ -1503,8 +1522,8 @@ mechanisms, in the order they are to be tried:
   required if @code{local} is also used.
 
   @item clear
-  Clear all defined mechanisms.  This is usefule to override
-  mechanisms fiven in a config file.
+  Clear all defined mechanisms.  This is useful to override
+  mechanisms given in a config file.
 
 @end table
 
@@ -1536,7 +1555,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
@@ -1577,32 +1596,34 @@ 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.
 
+@ifclear gpgtwoone
   @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.
+@end ifclear
 
+@ifclear gpgtwoone
   @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.
+@end ifclear
 
   @item timeout
   Tell the keyserver helper program how long (in seconds) to try and
@@ -1613,9 +1634,13 @@ 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.
+@ifset gpgtwoone
+This overrides any proxy defined in @file{dirmngr.conf}.
+@end ifset
+@ifclear gpgtwoone
+This overrides the "http_proxy" environment variable, if any.
+@end ifclear
 
 @ifclear gpgtwoone
   @item max-cert-size
@@ -1623,26 +1648,42 @@ are available for all keyserver types, some common options are:
   Defaults to 16384 bytes.
 @end ifclear
 
+  @item verbose
+@ifset gpgtwoone
+This option has no more function since GnuPG 2.1.  Use the
+@code{dirmngr} configuration options instead.
+@end ifset
+@ifclear gpgtwoone
+Tell the keyserver helper program to be more verbose. This option can
+be repeated multiple times to increase the verbosity level.
+@end ifclear
+
   @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).
+@ifset gpgtwoone
+This option has no more function since GnuPG 2.1.  Use the
+@code{dirmngr} configuration options instead.
+@end ifset
+@ifclear gpgtwoone
+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).
+@end ifclear
 
   @item check-cert
 @ifset gpgtwoone
-  This option has no more function since GnuPG 2.1.  Use the
-  @code{dirmngr} configuration options instead.
+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.
+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.
+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
@@ -1712,33 +1753,22 @@ 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
+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.
+@ifclear gpgtwoone
+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
@@ -1752,6 +1782,14 @@ 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
 Lock the databases the first time a lock is requested
@@ -1961,7 +1999,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.
 
@@ -2014,6 +2052,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
@@ -2100,14 +2147,19 @@ 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
@@ -2124,9 +2176,20 @@ 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.
+
+@item --with-secret
+@opindex with-secret
+Include info about the presence of a secret key in public key listings
+done with @code{--with-colons}.
+
 @end ifset
 
 @end table
@@ -2151,14 +2214,7 @@ 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
-
+@ifclear gpgtwoone
 @item --force-v3-sigs
 @itemx --no-force-v3-sigs
 @opindex force-v3-sigs
@@ -2177,6 +2233,15 @@ Defaults to no.
 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.
+@end ifclear
+
+@ifset gpgtwoone
+@item --force-v3-sigs
+@itemx --no-force-v3-sigs
+@item --force-v4-certs
+@itemx --no-force-v4-certs
+These options are obsolete and have no effect since GnuPG 2.1.
+@end ifset
 
 @item --force-mdc
 @opindex force-mdc
@@ -2226,7 +2291,7 @@ 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
+The default cipher is @value{DEFSYMENCALGO}. This cipher is also used for
 conventional encryption if @option{--personal-cipher-preferences} and
 @option{--cipher-algo} is not given.
 
@@ -2296,9 +2361,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
@@ -2308,11 +2375,17 @@ a message that PGP 2.x will not be able to handle. Note that `PGP
 2.x' here means `MIT PGP 2.6.2'. There are other versions of PGP 2.x
 available, but the MIT release is a good common baseline.
 
-This option implies @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}. It also disables @option{--textmode} when
-encrypting.
+This option implies
+@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}.
+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
@@ -2323,8 +2396,12 @@ 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}.
+@ifclear gpgtwoone
+This option implies @option{--disable-mdc --escape-from-lines --force-v3-sigs}.
+@end ifclear
+@ifset gpgtwoone
+This option implies @option{--disable-mdc --escape-from-lines}.
+@end ifset
 
 @item --pgp7
 @opindex pgp7
@@ -2406,12 +2483,10 @@ be given in C syntax (e.g. 0x0042).
 @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
@@ -2662,10 +2737,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
@@ -2674,10 +2748,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
@@ -2685,10 +2757,8 @@ 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}
@@ -2774,7 +2844,6 @@ 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.
 
-
 @item --no-default-keyring
 @opindex no-default-keyring
 Do not add the default keyrings to the list of keyrings. Note that
@@ -2819,8 +2888,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
@@ -2916,6 +2990,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
@@ -2938,15 +3016,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
@@ -2963,14 +3032,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.
@@ -3025,10 +3086,8 @@ current home directory (@pxref{option --homedir}).
 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
+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
@@ -3036,18 +3095,33 @@ files; They all live in in the current home directory (@pxref{option
 
 
 @table @file
-  @item ~/.gnupg/secring.gpg
-  The secret keyring.  You should backup this file.
-
-  @item ~/.gnupg/secring.gpg.lock
-  The lock file for the secret keyring.
-
   @item ~/.gnupg/pubring.gpg
   The public keyring.  You should backup this file.
 
   @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
+
   @item ~/.gnupg/trustdb.gpg
   The trust database.  There is no need to backup this file; it is better
   to backup the ownertrust values (@pxref{option --export-ownertrust}).
@@ -3058,6 +3132,19 @@ files; They all live in in the current home directory (@pxref{option
   @item ~/.gnupg/random_seed
   A file used to preserve the state of the internal random pool.
 
+  @item ~/.gnupg/secring.gpg.lock
+  The lock file for the secret keyring.
+
+  @item ~/.gnupg/openpgp-revocs.d/
+  This is the directory where gpg stores pre-generated revocation
+  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 /usr[/local]/share/gnupg/options.skel
   The skeleton options file.
 
@@ -3078,15 +3165,18 @@ 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.
+@ifset gpgtwoone
+  This variable was used by GnuPG versions before 2.1
 @end ifset
+@ifclear gpgtwoone
+  Used to locate the gpg-agent.
+
   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.
+@end ifclear
 
   @item PINENTRY_USER_DATA
   This value is passed via gpg-agent to pinentry.  It is useful to convey
@@ -3318,17 +3408,19 @@ control statements must be given. For GnuPG 2.1 and later
 
 @item %ask-passphrase
 @itemx %no-ask-passphrase
+@ifclear gpgtwoone
 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.
+global control statements and affect all future key generations.
+@end ifclear
+@ifset gpgtwoone
+This option is a no-op for GnuPG 2.1 and later.
+@end ifset
 
 @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.
 
@@ -3386,8 +3478,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}
@@ -3407,7 +3499,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.
@@ -3495,9 +3587,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