doc: Change remaining http links to gnupg.org to https
[gnupg.git] / doc / gpg.texi
index a88ddca..ffb892e 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,30 @@ 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
+outside of the cleartext signature or header lines following directly
+the dash marker line.  The option @code{--output} may be used to write
+out the actual signed data; but there are other pitfalls with this
+format as well.  It is suggested to avoid cleartext signatures in
+favor of detached signatures.
 
 @item --multifile
 @opindex multifile
@@ -279,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
@@ -302,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
@@ -325,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
@@ -337,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
@@ -345,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
@@ -368,7 +342,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
@@ -380,14 +354,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.
 
@@ -400,8 +374,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}
@@ -416,14 +390,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
@@ -555,6 +545,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
 
 
@@ -568,14 +564,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 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.
+
+@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}.
 
-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.
+@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
@@ -778,7 +804,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}.
 
@@ -898,13 +924,31 @@ 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}.
 
-@ifclear gpgone
+@ifset gpgtwoone
+@item --quick-sign-key @code{fpr} [@code{names}]
+@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
+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.  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 is to help unattended key signing by utilizing a list
+of verified fingerprints.
+@end ifset
+
 @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
 
@@ -1037,6 +1081,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}
@@ -1150,6 +1201,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
@@ -1169,7 +1229,7 @@ for the key fingerprint, "%t" for the extension of the image type
 (e.g. "jpg"), "%T" for the MIME type of the image (e.g. "image/jpeg"),
 "%v" for the single-character calculated validity of the image being
 viewed (e.g. "f"), "%V" for the calculated validity as a string (e.g.
-"full"),
+"full"), "%U" for a base32 encoded hash of the user ID,
 and "%%" for an actual percent sign. If neither %i or %I are present,
 then the photo will be supplied to the viewer on standard input.
 
@@ -1200,7 +1260,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
@@ -1216,41 +1282,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
@@ -1410,7 +1444,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
@@ -1420,10 +1454,12 @@ 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.
+  evidence that the user ID is bound to the key.  Note that this
+  trust model still does not allow the use of expired, revoked, or
+  disabled keys.
 
   @item auto
   @opindex trust-mode:auto
@@ -1474,6 +1510,10 @@ mechanisms, in the order they are to be tried:
   position of this mechanism in the list does not matter.  It is not
   required if @code{local} is also used.
 
+  @item clear
+  Clear all defined mechanisms.  This is useful to override
+  mechanisms given in a config file.
+
 @end table
 
 @item --keyid-format @code{short|0xshort|long|0xlong}
@@ -1598,16 +1638,29 @@ are available for all keyserver types, some common options are:
   program uses internally (libcurl, openldap, etc).
 
   @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
 
 @item --completes-needed @code{n}
@@ -1667,27 +1720,43 @@ 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}.
+
+
+@item --agent-program @var{file}
+@opindex agent-program
+Specify an agent program to be used for secret key operations.  The
+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
-@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.
+
+@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
+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
@@ -1897,7 +1966,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.
 
@@ -1950,6 +2019,15 @@ opposite meaning. The options are:
   generally useful unless a shared keyring scheme is being used.
   Defaults to no.
 
+  @item import-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
@@ -2040,10 +2118,17 @@ source distribution.
 @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
@@ -2054,6 +2139,12 @@ of the output and may be used together with another command.
 @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
@@ -2078,14 +2169,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
@@ -2104,6 +2188,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
@@ -2153,7 +2246,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.
 
@@ -2223,9 +2316,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
@@ -2235,10 +2330,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 --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
@@ -2249,8 +2351,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
@@ -2332,13 +2438,6 @@ 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 --faked-system-time @var{epoch}
 @opindex faked-system-time
 This option is only useful for testing; it sets the system time back or
@@ -2400,8 +2499,12 @@ protected by the signature.
 @item --emit-version
 @itemx --no-emit-version
 @opindex emit-version
-Force inclusion of the version string in ASCII armored output.
-@option{--no-emit-version} disables this option.
+Force inclusion of the version string in ASCII armored output.  If
+given once only the name of the program and the major number is
+emitted (default), given twice the minor is also emitted, given triple
+the micro is added, and given quad an operating system identification
+is also emitted.  @option{--no-emit-version} disables the version
+line.
 
 @item --sig-notation @code{name=value}
 @itemx --cert-notation @code{name=value}
@@ -2584,10 +2687,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
@@ -2596,10 +2698,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
@@ -2607,10 +2707,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}
@@ -2690,6 +2788,12 @@ 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.
 
+@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.
+
 @item --no-default-keyring
 @opindex no-default-keyring
 Do not add the default keyrings to the list of keyrings. Note that
@@ -2853,15 +2957,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
@@ -2878,14 +2973,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.
@@ -2940,10 +3027,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
@@ -2951,18 +3036,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}).
@@ -2973,6 +3073,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.
 
@@ -2993,15 +3106,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
@@ -3233,17 +3349,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.
 
@@ -3301,8 +3419,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}
@@ -3322,7 +3440,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.
@@ -3410,9 +3528,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