doc: Clarify constraints on who modifies files in ~/.gnupg
[gnupg.git] / doc / gpg.texi
index a326233..c0632b3 100644 (file)
@@ -3,9 +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 GnuPG-2 branches.
-@c 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 algorithm defaults
-
-@ifclear gpgtwoone
-@set DEFSYMENCALGO CAST5
-@end ifclear
-
-@ifset gpgtwoone
-@set DEFSYMENCALGO AES128
-@end ifset
-
-@c End algorithm defaults
-
-
 @macro gpgname
 gpg2
 @end macro
@@ -190,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 @value{DEFSYMENCALGO}, 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
@@ -333,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
@@ -406,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
@@ -564,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
@@ -585,20 +564,17 @@ the passphrase options (@option{--passphrase},
 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 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}.
 
-@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.
@@ -924,7 +900,6 @@ 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{fpr} [@code{names}]
 @opindex quick-sign-key
@@ -942,7 +917,14 @@ 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 --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.
 
 @item --passwd @var{user_id}
 @opindex passwd
@@ -1260,13 +1242,8 @@ 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
@@ -1544,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
@@ -1585,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
@@ -1621,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
 
@@ -1677,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.
@@ -1734,20 +1663,13 @@ 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 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
@@ -1936,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
@@ -1948,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
@@ -2079,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
@@ -2114,6 +2032,13 @@ 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}
@@ -2121,22 +2046,18 @@ listing mode and print all timestamps as seconds since 1970-01-01.
 Since GnuPG 2.0.10, this mode is always used and thus this option is
 obsolete; it does not harm to use it though.
 
-@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.
@@ -2150,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 *******************************************
@@ -2174,34 +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.
 
-@ifclear gpgtwoone
-@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.
-@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
@@ -2251,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 @value{DEFSYMENCALGO}. 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
@@ -2266,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
@@ -2356,12 +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.
 
-@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
@@ -2436,13 +2328,20 @@ 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.
 
+@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
 This option is only useful for testing; it sets the system time back or
@@ -2715,7 +2614,6 @@ avoid it.
 Note that this passphrase is only used if the option @option{--batch}
 has also been given.  This is different from GnuPG version 1.x.
 
-@ifset gpgtwoone
 @item --pinentry-mode @code{mode}
 @opindex pinentry-mode
 Set the pinentry mode to @code{mode}.  Allowed values for @code{mode}
@@ -2733,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
@@ -3039,14 +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.
+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}).
 
 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
@@ -3056,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
@@ -3100,10 +2990,10 @@ files; They all live in in the current home directory (@pxref{option
   You should backup all files in this directory and take care to keep
   this backup closed away.
 
-  @item /usr[/local]/share/gnupg/options.skel
+  @item @value{DATADIR}/options.skel
   The skeleton options file.
 
-  @item /usr[/local]/lib/gnupg/
+  @item @value{LIBDIR}/
   Default location for extensions.
 
 @end table
@@ -3120,18 +3010,7 @@ Operation is further controlled by a few environment variables:
   If set directory used instead of "~/.gnupg".
 
   @item GPG_AGENT_INFO
-@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
@@ -3363,17 +3242,7 @@ 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 generations.
-@end ifclear
-@ifset gpgtwoone
 This option is a no-op for GnuPG 2.1 and later.
-@end ifset
 
 @item %no-protection
 Using this option allows the creation of keys without any passphrase