* keygen.c (set_one_pref, keygen_set_std_prefs): Allow using the full
[gnupg.git] / doc / gpg.sgml
index 145ad7c..fb1c21e 100644 (file)
@@ -43,6 +43,7 @@
 <!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">
@@ -220,8 +221,10 @@ ones given on the command line.
 <varlistentry>
 <term>--list-secret-keys &OptParmNames;</term>
 <listitem><para>
-List all keys from the secret keyrings, or just the
-ones given on the command line.
+List all keys from the secret keyrings, or just the ones given on the
+command line.  A '#' after the letters 'sec' means that the secret key
+is not usable (for example, if it was created via
+--export-secret-subkeys).
 </para></listitem></varlistentry>
 
 
@@ -310,10 +313,10 @@ non-exportable.</para></listitem></varlistentry>
     <varlistentry>
     <term>revsig</term>
     <listitem><para>
-Revoke a signature.  GnuPG asks for every
-signature which has been done by one of
-the secret keys, whether a revocation
-certificate should be generated.</para></listitem></varlistentry>
+Revoke a signature.  For every signature which has been generated by
+one of the secret keys, GnuPG asks whether a revocation certificate
+should be generated.
+</para></listitem></varlistentry>
     <varlistentry>
     <term>trust</term>
     <listitem><para>
@@ -348,7 +351,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>
@@ -356,10 +362,10 @@ Revoke a subkey.</para></listitem></varlistentry>
     <varlistentry>
     <term>expire</term>
     <listitem><para>
-Change the key expiration time.  If a key is
-selected, the time of this key will be changed.
-With no selection the key expiration of the
-primary key is changed.</para></listitem></varlistentry>
+Change the key expiration time.  If a subkey is selected, the
+expiration time of this subkey will be changed.  With no selection,
+the key expiration of the primary key is changed.
+</para></listitem></varlistentry>
     <varlistentry>
     <term>passwd</term>
     <listitem><para>
@@ -396,27 +402,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>
@@ -476,19 +492,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>
@@ -575,6 +595,15 @@ Import the keys with the given key IDs from a keyserver. Option
 </para></listitem></varlistentry>
 
 <varlistentry>
+<term>--refresh-keys &ParmKeyIDs;</term>
+<listitem><para>
+Request updates from a keyserver for keys that already exist on the
+local keyring.  This is useful for updating a key with the latest
+signatures, user IDs, etc.  Option --keyserver must be used to give
+the name of this keyserver.
+</para></listitem></varlistentry>
+
+<varlistentry>
 <term>--search-keys &OptParmNames;</term>
 <listitem><para>
 Search the keyserver for the given names.  Multiple names given here
@@ -628,6 +657,13 @@ in &ParmFiles; (or stdin if not given); existing
 values will be overwritten.
 </para></listitem></varlistentry>
 
+<varlistentry>
+<term>--rebuild-keydb-caches</term>
+<listitem><para>
+When updating from version 1.0.6 to 1.0.7 this command should be used
+to create signature caches in the keyring.  It might be handy in other
+situations too.
+</para></listitem></varlistentry>
 
 <varlistentry>
 <term>--print-md <parameter>algo</parameter> &OptParmFiles;</term>
@@ -688,11 +724,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:
@@ -936,7 +974,8 @@ from, send keys to, and search for keys on.  The format of the
 the type of keyserver: "hkp" for the Horowitz (or compatible)
 keyservers, "ldap" for the NAI LDAP keyserver, or "mailto" for the
 Horowitz email keyserver.  Note that your particular installation of
-GnuPG may have other keyserver types available as well.
+GnuPG may have other keyserver types available as well.  Keyserver
+schemes are case-insensitive.
 </para><para>
 Most keyservers synchronize with each other, so there is generally no
 need to send keys to more than one server.  Using the command "host -l
@@ -951,17 +990,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>
@@ -973,6 +1016,14 @@ keyservers, as they do not support disabling keys.
 </para></listitem></varlistentry>
 
 <varlistentry>
+<term>include-subkeys</term>
+<listitem><para>
+When receiving a key, include subkeys in the search.  Note that this
+option is not used with HKP keyservers, as they do not support
+retrieving keys by subkey id.
+</para></listitem></varlistentry>
+
+<varlistentry>
 <term>use-temp-files</term>
 <listitem><para>
 On most Unix-like platforms, GnuPG communicates with the keyserver
@@ -1016,11 +1067,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>
 
@@ -1047,6 +1167,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
@@ -1090,16 +1219,21 @@ also overrides the environment variable "GNUPGHOME".
 <term>--charset &ParmName;</term>
 <listitem><para>
 Set the name of the native character set.  This is used
-to convert some strings to proper UTF-8 encoding.
+to convert some strings to proper UTF-8 encoding. If this option is not used, the default character set is determined
+from the current locale.  A verbosity level of 3 shows the used one.
 Valid values for &ParmName; are:</para>
 <variablelist>
 <varlistentry>
-<term>iso-8859-1</term><listitem><para>This is the default Latin 1 set.</para></listitem>
+<term>iso-8859-1</term><listitem><para>This is the Latin 1 set.</para></listitem>
 </varlistentry>
 <varlistentry>
 <term>iso-8859-2</term><listitem><para>The Latin 2 set.</para></listitem>
 </varlistentry>
 <varlistentry>
+<term>iso-8859-15</term><listitem><para>This is currently an alias for
+the Latin 1 set.</para></listitem>
+</varlistentry>
+<varlistentry>
 <term>koi8-r</term><listitem><para>The usual Russian set (rfc1489).</para></listitem>
 </varlistentry>
 <varlistentry>
@@ -1145,9 +1279,10 @@ Using this option will also prevent the creation of a
 <varlistentry>
 <term>--load-extension &ParmName;</term>
 <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.
+Load an extension module. If &ParmName; 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.
 </para></listitem></varlistentry>
 
 
@@ -1416,7 +1551,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>
 
 
@@ -1573,7 +1711,8 @@ available, but the MIT release is a good common baseline.
 This option implies `--rfc1991 --no-openpgp --disable-mdc
 --no-force-v4-certs --no-comment --escape-from-lines --force-v3-sigs
 --no-ask-sig-expire --no-ask-cert-expire --cipher-algo IDEA
---digest-algo MD5 --compress-algo 1'
+--digest-algo MD5 --compress-algo 1'.  It also disables --textmode
+when encrypting.
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -1606,8 +1745,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>
@@ -1656,13 +1796,21 @@ changes the default hash algorithm for v3 RSA keys from MD5 to SHA-1.
 Reset the --force-v4-certs option.
 </para></listitem></varlistentry>
 
-
 <varlistentry>
 <term>--force-mdc</term>
 <listitem><para>
-Force the use of encryption with appended manipulation code.  This is
-always used with the newer ciphers (those with a blocksize greater
-than 64 bit).
+Force the use of encryption with a modification detection code.  This
+is always used with the newer ciphers (those with a blocksize greater
+than 64 bits), or if the recipient key has one of those ciphers as a
+preference.
+</para></listitem></varlistentry>
+
+<varlistentry>
+<term>--disable-mdc</term>
+<listitem><para>
+Disable the use of the modification detection code.  Note that by
+using this option, the encrypted message becomes vulnerable to a
+message modification attack.
 </para></listitem></varlistentry>
 
 <varlistentry>
@@ -1709,14 +1857,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>
@@ -1781,6 +1937,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>
@@ -1977,12 +2139,16 @@ Experimental use only.
 </para></listitem></varlistentry>
 
 <varlistentry>
-<term>--group &ParmNameValue;</term>
+<term>--group &ParmNameValues;</term>
 <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
-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>
@@ -2199,11 +2365,12 @@ 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 --gpg-agent-info can
-be used to overide it.</para></listitem>
+be used to override it.</para></listitem>
 </varlistentry>
 <varlistentry>
 <term>http_proxy</term>
-<listitem><para>Only honored when the option --honor-http-proxy is set.</para></listitem>
+<listitem><para>Only honored when the keyserver-option
+honor-http-proxy is set.</para></listitem>
 </varlistentry>
     </variablelist>
 
@@ -2249,8 +2416,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>
@@ -2284,7 +2457,7 @@ is *very* easy to spy out your passphrase!
 <para>
 If you are going to verify detached signatures, make sure that the
 program knows about it; either be giving both filenames on the
-commandline or using <literal>-</literal> to specify stdin.
+command line or using <literal>-</literal> to specify stdin.
 </para>
 </refsect1>