* gpg.sgml: Clarify meaning of keyserver option include-revoked.
[gnupg.git] / doc / gpg.sgml
index 99c0421..6695534 100644 (file)
@@ -349,7 +349,10 @@ Remove a subkey.</para></listitem></varlistentry>
     <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>
@@ -397,27 +400,37 @@ id.</para></listitem></varlistentry>
     <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>
-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>
-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
-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>
@@ -477,19 +490,23 @@ This is a shortcut version of the subcommand "nrsign" from --edit.
 <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>
-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>
-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>
@@ -689,11 +706,13 @@ all options.
 <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:
@@ -952,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
-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>
-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>
@@ -1017,11 +1040,80 @@ keyring.
 </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>
-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>
 
@@ -1048,6 +1140,15 @@ stdin"
 </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
@@ -1148,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"
-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>
 
 
@@ -1417,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
-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>
 
 
@@ -1607,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
-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>
@@ -1710,14 +1816,22 @@ clock problem.
 <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
-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>
 
+<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>
@@ -1782,6 +1896,12 @@ Suppress the warning about "using insecure memory".
 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>
@@ -2254,8 +2374,14 @@ be used to overide it.</para></listitem>
 </varlistentry>
 
 <varlistentry>
+<term>~/.gnupg/gpg.conf</term>
+<listitem><para>Default configuration file</para></listitem>
+</varlistentry>
+
+<varlistentry>
 <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>