* keygen.c (set_one_pref, keygen_set_std_prefs): Allow using the full
[gnupg.git] / doc / gpg.sgml
index 98610b6..fb1c21e 100644 (file)
@@ -221,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>
 
 
@@ -311,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>
@@ -360,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>
@@ -593,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
@@ -646,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>
@@ -706,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:
@@ -954,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
@@ -978,10 +999,12 @@ keyserver types, some common options are:
 <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>
@@ -993,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
@@ -1188,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>
@@ -1243,10 +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"
-Extension are in gernal not useful anymore; the use of this 
-option is deprecated.
+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>
 
 
@@ -1675,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>
@@ -1759,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>
@@ -1812,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>
@@ -1890,6 +1943,7 @@ Suppress the warning about unsafe file permissions.
 Suppress the warning about missing MDC integrity protection.
 </para></listitem></varlistentry>
 
+
 <varlistentry>
 <term>--no-armor</term>
 <listitem><para>
@@ -2311,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>
 
@@ -2361,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>
@@ -2396,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>