* gpg.sgml: Clarify meaning of keyserver option include-revoked.
[gnupg.git] / doc / gpg.sgml
index 145ad7c..6695534 100644 (file)
@@ -43,6 +43,7 @@
 <!entity ParmString "<parameter>string</parameter>">
 <!entity ParmValue  "<parameter>value</parameter>">
 <!entity ParmNameValue "<parameter>name=value</parameter>">
 <!entity ParmString "<parameter>string</parameter>">
 <!entity ParmValue  "<parameter>value</parameter>">
 <!entity ParmNameValue "<parameter>name=value</parameter>">
+<!entity ParmNameValues        "<parameter>name=value1 <optional>value2 value3 ...</optional></parameter>">
 ]>
 
 <refentry id="gpg">
 ]>
 
 <refentry id="gpg">
@@ -348,7 +349,10 @@ Remove a subkey.</para></listitem></varlistentry>
     <varlistentry>
     <term>addrevoker</term>
     <listitem><para>
     <varlistentry>
     <term>addrevoker</term>
     <listitem><para>
-Add a designated revoker.</para></listitem></varlistentry>
+Add a designated revoker.  This takes one optional argument:
+"sensitive".  If a designated revoker is marked as sensitive, it will
+not be exported by default (see
+export-options).</para></listitem></varlistentry>
     <varlistentry>
     <term>revkey</term>
     <listitem><para>
     <varlistentry>
     <term>revkey</term>
     <listitem><para>
@@ -396,27 +400,37 @@ id.</para></listitem></varlistentry>
     <varlistentry>
     <term>pref</term>
     <listitem><para>
     <varlistentry>
     <term>pref</term>
     <listitem><para>
-List preferences.</para></listitem></varlistentry>
+List preferences from the selected user ID.  This shows the actual
+preferences, without including any implied preferences.
+</para></listitem></varlistentry>
     <varlistentry>
     <term>showpref</term>
     <listitem><para>
     <varlistentry>
     <term>showpref</term>
     <listitem><para>
-More verbose preferences listing.</para></listitem></varlistentry>
+More verbose preferences listing for the selected user ID.  This shows
+the preferences in effect by including the implied preferences of
+3DES (cipher), SHA-1 (digest), and Uncompressed (compression) if they
+are not already included in the preference list.
+</para></listitem></varlistentry>
     <varlistentry>
     <term>setpref &ParmString;</term>
     <listitem><para>
     <varlistentry>
     <term>setpref &ParmString;</term>
     <listitem><para>
-Set the list of user ID preferences to &ParmString;, this should be 
-a string similar to the one printed by "pref".  Using an empty string
-will set the default preference string, using "none" will set the 
-preferences to nil.  Only available algorithms are allowed.  This
-command just initializes an internal list and does not change anything
-unless another command which changes the self-signatures is used.
+Set the list of user ID preferences to &ParmString;, this should be a
+string similar to the one printed by "pref".  Using an empty string
+will set the default preference string, using "none" will set the
+preferences to nil.  Use "gpg -v --version" to get a list of available
+algorithms.  This command just initializes an internal list and does
+not change anything unless another command (such as "updpref") which
+changes the self-signatures is used.
 </para></listitem></varlistentry>
     <varlistentry>
     <term>updpref</term>
     <listitem><para>
 Change the preferences of all user IDs (or just of the selected ones
 to the current list of preferences.  The timestamp of all affected
 </para></listitem></varlistentry>
     <varlistentry>
     <term>updpref</term>
     <listitem><para>
 Change the preferences of all user IDs (or just of the selected ones
 to the current list of preferences.  The timestamp of all affected
-self-signatures fill be advanced by one second.
+self-signatures will be advanced by one second.  Note that while you
+can change the preferences on an attribute user ID (aka "photo ID"),
+GnuPG does not select keys via attribute user IDs so these preferences
+will not be used by GnuPG.
 </para></listitem></varlistentry>
     <varlistentry>
     <term>toggle</term>
 </para></listitem></varlistentry>
     <varlistentry>
     <term>toggle</term>
@@ -476,19 +490,23 @@ This is a shortcut version of the subcommand "nrsign" from --edit.
 <varlistentry>
 <term>--delete-key &ParmName;</term>
 <listitem><para>
 <varlistentry>
 <term>--delete-key &ParmName;</term>
 <listitem><para>
-Remove key from the public keyring
+Remove key from the public keyring.  In batch mode either --yes is
+required or the key must be specified by fingerprint.  This is a
+safeguard against accidental deletion of multiple keys.
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>--delete-secret-key  &ParmName;</term>
 <listitem><para>
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>--delete-secret-key  &ParmName;</term>
 <listitem><para>
-Remove key from the secret and public keyring
+Remove key from the secret and public keyring. In batch mode the key
+must be specified by fingerprint.
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>--delete-secret-and-public-key  &ParmName;</term>
 <listitem><para>
 </para></listitem></varlistentry>
 
 <varlistentry>
 <term>--delete-secret-and-public-key  &ParmName;</term>
 <listitem><para>
-Same as --delete-key, but if a secret key exists, it will be removed first.
+Same as --delete-key, but if a secret key exists, it will be removed 
+first. In batch mode the key must be specified by fingerprint.
 </para></listitem></varlistentry>
 
 <varlistentry>
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -688,11 +706,13 @@ all options.
 <refsect1>
 <title>OPTIONS</title>
 <para>
 <refsect1>
 <title>OPTIONS</title>
 <para>
-Long options can be put in an options file (default "~/.gnupg/options").
-Do not write the 2 dashes, but simply the name of the option and any
-required arguments. Lines with a hash as the first non-white-space
-character are ignored. Commands may be put in this file too, but that
-does not make sense.
+Long options can be put in an options file (default
+"~/.gnupg/gpg.conf").  Short option names will not work - for example,
+"armor" is a valid option for the options file, while "a" is not.  Do
+not write the 2 dashes, but simply the name of the option and any
+required arguments.  Lines with a hash ('#') as the first
+non-white-space character are ignored.  Commands may be put in this
+file too, but that does not make sense.
 </para>
 <para>
 <command/gpg/ recognizes these options:
 </para>
 <para>
 <command/gpg/ recognizes these options:
@@ -951,17 +971,21 @@ each time.
 <listitem><para>
 This is a space or comma delimited string that gives options for the
 keyserver.  Options can be prepended with a `no-' to give the opposite
 <listitem><para>
 This is a space or comma delimited string that gives options for the
 keyserver.  Options can be prepended with a `no-' to give the opposite
-meaning.  While not all options are available for all keyserver types,
-some common options are:
+meaning.  Valid import-options or export-options may be used here as
+well to apply to importing (--recv-key) or exporting (--send-key) a
+key from a keyserver.  While not all options are available for all
+keyserver types, some common options are:
 <variablelist>
 
 <varlistentry>
 <term>include-revoked</term>
 <listitem><para>
 <variablelist>
 
 <varlistentry>
 <term>include-revoked</term>
 <listitem><para>
-When receiving or searching for a key, include keys that are marked on
-the keyserver as revoked.  Note that this option is always set when
-using the NAI HKP keyserver, as this keyserver does not differentiate
-between revoked and unrevoked keys.
+When searching for a key, include keys that are marked on the
+keyserver as revoked.  Note that this option is always set when using
+the NAI HKP keyserver, as this keyserver does not differentiate
+between revoked and unrevoked keys.  When using the LDAP keyserver,
+this applies to both searching (--search-keys) and receiving
+(--recv-keys).
 </para></listitem></varlistentry>
 
 <varlistentry>
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -1016,11 +1040,80 @@ keyring.
 </para></listitem></varlistentry>
 
 <varlistentry>
 </para></listitem></varlistentry>
 
 <varlistentry>
+<term>--import-options <parameter>parameters</parameter></term>
+<listitem><para>
+This is a space or comma delimited string that gives options for
+importing keys.  Options can be prepended with a `no-' to give the
+opposite meaning.  The options are:
+<variablelist>
+
+<varlistentry>
+<term>allow-local-sigs</term>
+<listitem><para>
+Allow importing key signatures marked as "local".  This is not
+generally useful unless a shared keyring scheme is being used.
+Defaults to no.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>repair-hkp-subkey-bug</term>
+<listitem><para>
+During import, attempt to repair the HKP keyserver mangling multiple
+subkeys bug.  Note that this cannot completely repair the damaged key
+as some crucial data is removed by the keyserver, but it does at least
+give you back one subkey.  Defaults to no for regular --import and to
+yes for keyserver --recv-keys.
+</para></listitem></varlistentry>
+
+</variablelist>
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>--export-options <parameter>parameters</parameter></term>
+<listitem><para>
+This is a space or comma delimited string that gives options for
+exporting keys.  Options can be prepended with a `no-' to give the
+opposite meaning.  The options are:
+<variablelist>
+
+<varlistentry>
+<term>include-non-rfc</term>
+<listitem><para>
+Include non-RFC compliant keys in the export.  Defaults to yes.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>include-local-sigs</term>
+<listitem><para>
+Allow exporting key signatures marked as "local".  This is not
+generally useful unless a shared keyring scheme is being used.
+Defaults to no.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>include-attributes</term>
+<listitem><para>
+Include attribute user IDs (photo IDs) while exporting.  This is
+useful to export keys if they are going to be used by an OpenPGP
+program that does not accept attribute user IDs.  Defaults to yes.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>include-sensitive-revkeys</term>
+<listitem><para>
+Include designated revoker information that was marked as
+"sensitive".  Defaults to no.
+</para></listitem></varlistentry>
+
+</variablelist>
+</para></listitem></varlistentry>
+
+<varlistentry>
 <term>--show-photos</term>
 <listitem><para>
 <term>--show-photos</term>
 <listitem><para>
-Causes --list-keys, --list-sigs, --list-public-keys, and
---list-secret-keys to also display the photo ID attached to a key, if
-any.
+Causes --list-keys, --list-sigs, --list-public-keys,
+--list-secret-keys, and verifying a signature to also display the
+photo ID attached to the key, if any.
 See also --photo-viewer.
 </para></listitem></varlistentry>
 
 See also --photo-viewer.
 </para></listitem></varlistentry>
 
@@ -1047,6 +1140,15 @@ stdin"
 </para></listitem></varlistentry>
 
 <varlistentry>
 </para></listitem></varlistentry>
 
 <varlistentry>
+<term>--exec-path &ParmString;</term>
+<listitem><para>
+Sets a list of directories to search for photo viewers and keyserver
+helpers.  If not provided, keyserver helpers use the compiled-in
+default directory, and photo viewers use the $PATH environment
+variable.
+</para></listitem></varlistentry>
+
+<varlistentry>
 <term>--show-keyring</term>
 <listitem><para>
 Causes --list-keys, --list-public-keys, and --list-secret-keys to
 <term>--show-keyring</term>
 <listitem><para>
 Causes --list-keys, --list-public-keys, and --list-secret-keys to
@@ -1147,7 +1249,8 @@ Using this option will also prevent the creation of a
 <listitem><para>
 Load an extension module. If &ParmName; does not
 contain a slash it is searched in "/usr/local/lib/gnupg"
 <listitem><para>
 Load an extension module. If &ParmName; does not
 contain a slash it is searched in "/usr/local/lib/gnupg"
-See the manual for more information about extensions.
+Extension are in gernal not useful anymore; the use of this 
+option is deprecated.
 </para></listitem></varlistentry>
 
 
 </para></listitem></varlistentry>
 
 
@@ -1416,7 +1519,10 @@ method will be part of an 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 this option
 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 this option
-bears a security risk.
+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).
 </para></listitem></varlistentry>
 
 
 </para></listitem></varlistentry>
 
 
@@ -1606,8 +1712,9 @@ Resets the --pgp6 option.
 <term>--pgp7</term>
 <listitem><para>
 Set up all options to be as PGP 7 compliant as possible.  This is
 <term>--pgp7</term>
 <listitem><para>
 Set up all options to be as PGP 7 compliant as possible.  This is
-identical to --pgp6 except that the list of allowable ciphers is
-expanded to add AES128, AES192, AES256, and TWOFISH.
+identical to --pgp6 except that MDCs are not disabled, and the list of
+allowable ciphers is expanded to add AES128, AES192, AES256, and
+TWOFISH.
 </para></listitem></varlistentry>
 
 <varlistentry>
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -1709,14 +1816,22 @@ clock problem.
 <varlistentry>
 <term>--ignore-crc-error</term>
 <listitem><para>
 <varlistentry>
 <term>--ignore-crc-error</term>
 <listitem><para>
-The ASCII armor used by OpenPG is protected by a CRC checksum against
+The ASCII armor used by OpenPGP is protected by a CRC checksum against
 transmission errors.  Sometimes it happens that the CRC gets mangled
 transmission errors.  Sometimes it happens that the CRC gets mangled
-somewhere on the transmission channel 
-but the actual content (which is anyway protected by
-the OpenPGP protocol) is still okay.  This option will let gpg ignore
-CRC errors.
+somewhere on the transmission channel but the actual content (which is
+protected by the OpenPGP protocol anyway) is still okay.  This option
+will let gpg ignore CRC errors.
 </para></listitem></varlistentry>
 
 </para></listitem></varlistentry>
 
+<varlistentry>
+<term>--ignore-mdc-error</term>
+<listitem><para>
+This option changes a MDC integrity protection failure into a warning.
+This can be useful if a message is partially corrupt, but it is
+necessary to get as much data as possible out of the corrupt message.
+However, be aware that a MDC protection failure may also mean that the
+message was tampered with intentionally by an attacker.
+</para></listitem></varlistentry>
 
 <varlistentry>
 <term>--lock-once</term>
 
 <varlistentry>
 <term>--lock-once</term>
@@ -1781,6 +1896,12 @@ Suppress the warning about "using insecure memory".
 Suppress the warning about unsafe file permissions.
 </para></listitem></varlistentry>
 
 Suppress the warning about unsafe file permissions.
 </para></listitem></varlistentry>
 
+<varlistentry>
+<term>--no-mdc-warning</term>
+<listitem><para>
+Suppress the warning about missing MDC integrity protection.
+</para></listitem></varlistentry>
+
 
 <varlistentry>
 <term>--no-armor</term>
 
 <varlistentry>
 <term>--no-armor</term>
@@ -1977,12 +2098,16 @@ Experimental use only.
 </para></listitem></varlistentry>
 
 <varlistentry>
 </para></listitem></varlistentry>
 
 <varlistentry>
-<term>--group &ParmNameValue;</term>
+<term>--group &ParmNameValues;</term>
 <listitem><para>
 <listitem><para>
-Sets up a name group, which is similar to aliases in email programs.
+Sets up a named group, which is similar to aliases in email programs.
 Any time the group name is a receipient (-r or --recipient), it will
 Any time the group name is a receipient (-r or --recipient), it will
-be expanded to the values specified.  Note there is only one level of
-expansion - you cannot make an group that points to another group.
+be expanded to the values specified.
+
+The values are &ParmKeyIDs; or fingerprints, but any key description
+is accepted.  Note that a value with spaces in it will be treated as
+two different values.  Note also there is only one level of expansion
+- you cannot make an group that points to another group.
 </para></listitem></varlistentry>
 
 <varlistentry>
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -2249,8 +2374,14 @@ be used to overide it.</para></listitem>
 </varlistentry>
 
 <varlistentry>
 </varlistentry>
 
 <varlistentry>
+<term>~/.gnupg/gpg.conf</term>
+<listitem><para>Default configuration file</para></listitem>
+</varlistentry>
+
+<varlistentry>
 <term>~/.gnupg/options</term>
 <term>~/.gnupg/options</term>
-<listitem><para>May contain options</para></listitem>
+<listitem><para>Old style configuration file; only used when gpg.conf
+is not found</para></listitem>
 </varlistentry>
 
 <varlistentry>
 </varlistentry>
 
 <varlistentry>