common/
[gnupg.git] / doc / gpg.texi
index 6fdc247..1b85129 100644 (file)
@@ -328,7 +328,7 @@ The status of the verification is indicated by a flag directly following
 the "sig" tag (and thus before the flags described above for
 @option{--list-sigs}).  A "!" indicates that the signature has been
 successfully verified, a "-" denotes a bad signature and a "%" is used
-if an error occured while checking the signature (e.g. a non supported
+if an error occurred while checking the signature (e.g. a non supported
 algorithm).
 
 @ifclear gpgone
@@ -589,6 +589,16 @@ line.
 @c ******** Begin Edit-key Options **********
 @table @asis
 
+@item uid @code{n}
+@opindex keyedit:uid
+Toggle selection of user ID or photographic user ID with index @code{n}.
+Use @code{*} to select all and @code{0} to deselect all.
+
+@item key @code{n}
+@opindex keyedit:key
+Toggle selection of subkey with index @code{n}.
+Use @code{*} to select all and @code{0} to deselect all.
+
 @item sign
 @opindex keyedit:sign
 Make a signature on key of user @code{name} If the key is not yet
@@ -625,106 +635,47 @@ create a signature of any type desired.
 
 @table @asis
 
+@item delsig
+@opindex keyedit:delsig
+Delete a signature. Note that it is not possible to retract a signature,
+once it has been send to the public (i.e. to a keyserver).  In that case
+you better use @code{revsig}.
+
 @item revsig
 @opindex keyedit:revsig
 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.
 
-@item trust
-@opindex keyedit:trust
-Change the owner trust value. This updates the
-trust-db immediately and no save is required.
-
-@item disable
-@itemx enable
-@opindex keyedit:disable
-@opindex keyedit:enable
-Disable or enable an entire key. A disabled key can not normally be
-used for encryption.
+@item check
+@opindex keyedit:check
+Check the signatures on all selected user IDs.
 
 @item adduid
 @opindex keyedit:adduid
-Create an alternate user id.
+Create an additional user ID.
 
 @item addphoto
 @opindex keyedit:addphoto
-Create a photographic user id. This will prompt for a JPEG file that
+Create a photographic user ID. This will prompt for a JPEG file that
 will be embedded into the user ID. Note that a very large JPEG will make
 for a very large key. Also note that some programs will display your
 JPEG unchanged (GnuPG), and some programs will scale it to fit in a
 dialog box (PGP).
 
+@item showphoto
+@opindex keyedit:showphoto
+Display the selected photographic user ID.
+
 @item deluid
 @opindex keyedit:deluid
-Delete a user id.  Note that it is not possible to retract a user id,
-once it has been send to the public (i.e. to a keyserver).  In that case
-you better use @code{revuid}.
-
-@item delsig
-@opindex keyedit:delsig
-Delete a signature. Note that it is not possible to retract a signature,
-once it has been send to the public (i.e. to a keyserver).  In that case
-you better use @code{revsig}.
+Delete a user ID or photographic user ID.  Note that it is not
+possible to retract a user id, once it has been send to the public
+(i.e. to a keyserver).  In that case you better use @code{revuid}.
 
 @item revuid
 @opindex keyedit:revuid
-Revoke a user id.
-
-@item addkey
-@opindex keyedit:addkey
-Add a subkey to this key.
-
-@item addcardkey
-@opindex keyedit:addcardkey
-Generate a key on a card and add it to this key.
-
-@item keytocard
-@opindex keyedit:keytocard
-Transfer the selected secret key (or the primary key if no key has been
-selected) to a smartcard. The secret key in the keyring will be replaced
-by a stub if the key could be stored successfully on the card and you
-use the save command later. Only certain key types may be transferred to
-the card. A sub menu allows you to select on what card to store the
-key. Note that it is not possible to get that key back from the card -
-if the card gets broken your secret key will be lost unless you have a
-backup somewhere.
-
-@item bkuptocard @code{file}
-@opindex keyedit:bkuptocard
-Restore the given file to a card. This command may be used to restore a
-backup key (as generated during card initialization) to a new card. In
-almost all cases this will be the encryption key. You should use this
-command only with the corresponding public key and make sure that the
-file given as argument is indeed the backup to restore. You should then
-select 2 to restore as encryption key.  You will first be asked to enter
-the passphrase of the backup key and then for the Admin PIN of the card.
-
-@item delkey
-@opindex keyedit:delkey
-Remove a subkey (secondart key). Note that it is not possible to retract
-a subkey, once it has been send to the public (i.e. to a keyserver).  In
-that case you better use @code{revkey}.
-
-@item addrevoker
-@opindex keyedit:addrevoker
-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).
-
-@item revkey
-@opindex keyedit:revkey
-Revoke a subkey.
-
-@item expire
-@opindex keyedit:expire
-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.
-
-@item passwd
-@opindex keyedit:passwd
-Change the passphrase of the secret key.
+Revoke a user ID or photographic user ID.
 
 @item primary
 @opindex keyedit:primary
@@ -735,24 +686,21 @@ as primary makes it primary over other photo user IDs, and setting a
 regular user ID as primary makes it primary over other regular user
 IDs.
 
-@item uid @code{n}
-@opindex keyedit:uid
-Toggle selection of user id with index @code{n}.
-Use 0 to deselect all.
-
-@item key @code{n}
-@opindex keyedit:key
-Toggle selection of subkey with index @code{n}.
-Use 0 to deselect all.
-
-@item check
-@opindex keyedit:check
-Check all selected user ids.
+@item keyserver
+@opindex keyedit:keyserver
+Set a preferred keyserver for the specified user ID(s). This allows
+other users to know where you prefer they get your key from. See
+@option{--keyserver-options honor-keyserver-url} for more on how this
+works.  Setting a value of "none" removes an existing preferred
+keyserver.
 
-@item showphoto
-@opindex keyedit:showphoto
-Display the selected photographic user
-id.
+@item notation
+@opindex keyedit:notation
+Set a name=value notation for the specified user ID(s). See
+@option{--cert-notation} for more on how this works. Setting a value of
+"none" removes all notations, setting a notation prefixed with a minus
+sign (-) removes that notation, and setting a notation name (without the
+=value) prefixed with a minus sign removes all notations with that name.
 
 @item pref
 @opindex keyedit:pref
@@ -790,21 +738,72 @@ message.  It will, however, only choose an algorithm that is present
 on the preference list of every recipient key.  See also the
 INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS section below.
 
-@item keyserver
-@opindex keyedit:keyserver
-Set a preferred keyserver for the specified user ID(s). This allows
-other users to know where you prefer they get your key from. See
-@option{--keyserver-options honor-keyserver-url} for more on how this
-works.  Setting a value of "none" removes an existing preferred
-keyserver.
+@item addkey
+@opindex keyedit:addkey
+Add a subkey to this key.
 
-@item notation
-@opindex keyedit:notation
-Set a name=value notation for the specified user ID(s). See
-@option{--cert-notation} for more on how this works. Setting a value of
-"none" removes all notations, setting a notation prefixed with a minus
-sign (-) removes that notation, and setting a notation name (without the
-=value) prefixed with a minus sign removes all notations with that name.
+@item addcardkey
+@opindex keyedit:addcardkey
+Generate a subkey on a card and add it to this key.
+
+@item keytocard
+@opindex keyedit:keytocard
+Transfer the selected secret subkey (or the primary key if no subkey
+has been selected) to a smartcard. The secret key in the keyring will
+be replaced by a stub if the key could be stored successfully on the
+card and you use the save command later. Only certain key types may be
+transferred to the card. A sub menu allows you to select on what card
+to store the key. Note that it is not possible to get that key back
+from the card - if the card gets broken your secret key will be lost
+unless you have a backup somewhere.
+
+@item bkuptocard @code{file}
+@opindex keyedit:bkuptocard
+Restore the given file to a card. This command may be used to restore a
+backup key (as generated during card initialization) to a new card. In
+almost all cases this will be the encryption key. You should use this
+command only with the corresponding public key and make sure that the
+file given as argument is indeed the backup to restore. You should then
+select 2 to restore as encryption key.  You will first be asked to enter
+the passphrase of the backup key and then for the Admin PIN of the card.
+
+@item delkey
+@opindex keyedit:delkey
+Remove a subkey (secondart key). Note that it is not possible to retract
+a subkey, once it has been send to the public (i.e. to a keyserver).  In
+that case you better use @code{revkey}.
+
+@item revkey
+@opindex keyedit:revkey
+Revoke a subkey.
+
+@item expire
+@opindex keyedit:expire
+Change the key or subkey 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.
+
+@item trust
+@opindex keyedit:trust
+Change the owner trust value for the key. This updates the trust-db
+immediately and no save is required.
+
+@item disable
+@itemx enable
+@opindex keyedit:disable
+@opindex keyedit:enable
+Disable or enable an entire key. A disabled key can not normally be
+used for encryption.
+
+@item addrevoker
+@opindex keyedit:addrevoker
+Add a designated revoker to the key. This takes one optional argument:
+"sensitive". If a designated revoker is marked as sensitive, it will
+not be exported by default (see export-options).
+
+@item passwd
+@opindex keyedit:passwd
+Change the passphrase of the secret key.
 
 @item toggle
 @opindex keyedit:toggle
@@ -829,7 +828,9 @@ each user ID except for the most recent self-signature.
 Add cross-certification signatures to signing subkeys that may not
 currently have them. Cross-certification signatures protect against a
 subtle attack against signing subkeys. See
-@option{--require-cross-certification}.
+@option{--require-cross-certification}.  All new keys generated have
+this signature by default, so this option is only useful to bring
+older keys up to date.
 
 @item save
 @opindex keyedit:save
@@ -844,7 +845,8 @@ key rings.
 
 @c man:.RS
 The listing shows you the key with its secondary keys and all user
-ids. Selected keys or user ids are indicated by an asterisk. The trust
+ids.  The primary user id is indicated by a dot, and selected keys or
+user ids are indicated by an asterisk.  The trust
 value is displayed with the primary key: the first is the assigned owner
 trust and the second is the calculated trust value. Letters are used for
 the values:
@@ -887,6 +889,13 @@ 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}.
 
+@ifclear gpgone
+@item --passwd @var{user_id}
+@opindex passwd
+Change the passphrase of the secret key belonging to the certificate
+specified as @var{user_id}.  This is a shortcut for the sub-command
+@code{passwd} of the edit key menu.
+@end ifclear
 
 @end table
 
@@ -900,7 +909,7 @@ from @option{--edit-key}.
 @node GPG Options
 @section Option Summary
 
-@command{@gpgname} comes features a bunch of options to control the exact
+@command{@gpgname} features a bunch of options to control the exact
 behaviour and to change the default configuration.
 
 @menu
@@ -1376,8 +1385,9 @@ Locate a key using DNS CERT, as specified in rfc4398.
 Locate a key using DNS PKA.
 
 @item ldap
-Locate a key using the PGP Universal method of checking
-@samp{ldap://keys.(thedomain)}.
+Using DNS Service Discovery, check the domain in question for any LDAP
+keyservers to use.  If this fails, attempt to locate the key using the
+PGP Universal method of checking @samp{ldap://keys.(thedomain)}.
 
 @item keyserver
 Locate a key using whatever keyserver is defined using the
@@ -1428,11 +1438,11 @@ keyserver each time you use it.
 
 @item --keyserver-options @code{name=value1 }
 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. Valid import-options or export-options may be used here as well
-to apply to importing (@option{--recv-key}) or exporting
-(@option{--send-key}) a key from a keyserver. While not all options are
-available for all keyserver types, some common options are:
+keyserver. Options can be prefixed with a `no-' to give the opposite
+meaning. Valid import-options or export-options may be used here as
+well to apply to importing (@option{--recv-key}) or exporting
+(@option{--send-key}) a key from a keyserver. While not all options
+are available for all keyserver types, some common options are:
 
 @table @asis
 
@@ -1514,6 +1524,18 @@ 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).
+
+@item check-cert
+Enable certificate checking if the keyserver presents one (for hkps or
+ldaps).  Defaults to on.
+
+@item ca-cert-file
+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 table
 
 @item --completes-needed @code{n}
@@ -1747,14 +1769,24 @@ Use @var{name} as the key to sign with. Note that this option overrides
 @option{--default-key}.
 
 @item --try-all-secrets
+@opindex try-all-secrets
 Don't look at the key ID as stored in the message but try all secret
 keys in turn to find the right decryption key. This option forces the
 behaviour as used by anonymous recipients (created by using
 @option{--throw-keyids}) and might come handy in case where an encrypted
 message contains a bogus key ID.
 
-
-
+@item --skip-hidden-recipients
+@itemx --no-skip-hidden-recipients
+@opindex skip-hidden-recipients
+@opindex no-skip-hidden-recipients
+During decryption skip all anonymous recipients.  This option helps in
+the case that people use the hidden recipients feature to hide there
+own encrypt-to key from others.  If oneself has many secret keys this
+may lead to a major annoyance because all keys are tried in turn to
+decrypt soemthing which was not really intended for it.  The drawback
+of this option is that it is currently not possible to decrypt a
+message which includes real anonymous recipients.
 
 
 @end table
@@ -1957,17 +1989,19 @@ message modification attack.
 Set the list of personal cipher preferences to @code{string}.  Use
 @command{@gpgname --version} to get a list of available algorithms,
 and use @code{none} to set no preference at all.  This allows the user
-to factor in their own preferred algorithms when algorithms are chosen
-via recipient key preferences.  The most highly ranked cipher in this
-list is also used for the @option{--symmetric} encryption command.
+to safely override the algorithm chosen by the recipient key
+preferences, as GPG will only select an algorithm that is usable by
+all recipients.  The most highly ranked cipher in this list is also
+used for the @option{--symmetric} encryption command.
 
 @item --personal-digest-preferences @code{string}
 Set the list of personal digest preferences to @code{string}.  Use
 @command{@gpgname --version} to get a list of available algorithms,
 and use @code{none} to set no preference at all.  This allows the user
-to factor in their own preferred algorithms when algorithms are chosen
-via recipient key preferences.  The most highly ranked digest
-algorithm in this list is also used when signing without encryption
+to safely override the algorithm chosen by the recipient key
+preferences, as GPG will only select an algorithm that is usable by
+all recipients.  The most highly ranked digest algorithm in this list
+is also used when signing without encryption
 (e.g. @option{--clearsign} or @option{--sign}). The default value is
 SHA-1.
 
@@ -1975,10 +2009,11 @@ SHA-1.
 Set the list of personal compression preferences to @code{string}.
 Use @command{@gpgname --version} to get a list of available
 algorithms, and use @code{none} to set no preference at all.  This
-allows the user to factor in their own preferred algorithms when
-algorithms are chosen via recipient key preferences.  The most highly
-ranked compression algorithm in this list is also used when there are
-no recipient keys to consider (e.g. @option{--symmetric}).
+allows the user to safely override the algorithm chosen by the
+recipient key preferences, as GPG will only select an algorithm that
+is usable by all recipients.  The most highly ranked compression
+algorithm in this list is also used when there are no recipient keys
+to consider (e.g. @option{--symmetric}).
 
 @item --s2k-cipher-algo @code{name}
 Use @code{name} as the cipher algorithm used to protect secret keys.
@@ -2061,9 +2096,9 @@ a message that PGP 2.x will not be able to handle. Note that `PGP
 available, but the MIT release is a good common baseline.
 
 This option implies @option{--rfc1991 --disable-mdc
---no-force-v4-certs --no-sk-comment --escape-from-lines
---force-v3-sigs --cipher-algo IDEA --digest-algo MD5 --compress-algo
-ZIP}. It also disables @option{--textmode} when encrypting.
+--no-force-v4-certs --escape-from-lines --force-v3-sigs --cipher-algo
+IDEA --digest-algo MD5 --compress-algo ZIP}. It also disables
+@option{--textmode} when encrypting.
 
 @item --pgp6
 @opindex pgp6
@@ -2074,8 +2109,8 @@ 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.
 
-This option implies @option{--disable-mdc --no-sk-comment
---escape-from-lines --force-v3-sigs}.
+This option implies @option{--disable-mdc --escape-from-lines
+--force-v3-sigs}.
 
 @item --pgp7
 @opindex pgp7
@@ -2119,6 +2154,34 @@ therefore enables a fast listing of the encryption keys.
 @opindex interactive
 Prompt before overwriting any files.
 
+@item --debug-level @var{level}
+@opindex debug-level
+Select the debug level for investigating problems. @var{level} may be
+a numeric value or by a keyword:
+
+@table @code
+@item none
+No debugging at all.  A value of less than 1 may be used instead of
+the keyword.
+@item basic  
+Some basic debug messages.  A value between 1 and 2 may be used
+instead of the keyword.
+@item advanced
+More verbose debug messages.  A value between 3 and 5 may be used
+instead of the keyword.
+@item expert
+Even more detailed messages.  A value between 6 and 8 may be used
+instead of the keyword.
+@item guru
+All of the debug messages you can get. A value greater than 8 may be
+used instead of the keyword.  The creation of hash tracing files is
+only enabled if the keyword is used.
+@end table
+
+How these messages are mapped to the actual debugging flags is not
+specified and may change with newer releases of this program. They are
+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
@@ -2133,6 +2196,13 @@ Enable debug output from the included CCID driver for smartcards.
 Note that this option is only available on some system.
 @end ifset
 
+@item --faked-system-time @var{epoch}
+@opindex faked-system-time
+This option is only useful for testing; it sets the system time back or
+forth to @var{epoch} which is the number of seconds elapsed since the year
+1970.  Alternatively @var{epoch} may be given as a full ISO time string
+(e.g. "20070924T154812").
+
 @item --enable-progress-filter
 Enable certain PROGRESS status outputs. This option allows frontends
 to display a progress indicator while gpg is processing larger files.
@@ -2660,7 +2730,7 @@ files; They all live in in the current home directory (@pxref{option
 The secret keyring.  You should backup this file.
 
 @item ~/.gnupg/secring.gpg.lock
-The lock file for teh secret keyring.
+The lock file for the secret keyring.
 
 @item ~/.gnupg/pubring.gpg
 The public keyring.  You should backup this file.
@@ -2676,7 +2746,7 @@ to backup the ownertrust values (@pxref{option --export-ownertrust}).
 The lock file for the trust database.
 
 @item ~/.gnupg/random_seed
-A file used to preserve the state of theinternal random pool.
+A file used to preserve the state of the internal random pool.
 
 @item /usr[/local]/share/gnupg/options.skel
 The skeleton options file.
@@ -2710,7 +2780,7 @@ value. The option @option{--gpg-agent-info} can be used to override it.
 
 @item PINENTRY_USER_DATA
 This value is passed via gpg-agent to pinentry.  It is useful to convey
-extra information to a custom pinentry
+extra information to a custom pinentry.
 
 @item COLUMNS
 @itemx LINES
@@ -2719,11 +2789,11 @@ Used to size some displays to the full size of the screen.
 
 @item LANGUAGE
 Apart from its use by GNU, it is used in the W32 version to override the
-language selection done through the Registry.  If used and set to a a
+language selection done through the Registry.  If used and set to a
 valid and available language name (@var{langid}), the file with the
 translation is loaded from
 @code{@var{gpgdir}/gnupg.nls/@var{langid}.mo}.  Here @var{gpgdir} is the
-directory out of which the gpg binary has been laoded.  If it can't be
+directory out of which the gpg binary has been loaded.  If it can't be
 loaded the Registry is tried and as last resort the native Windows
 locale system is used.  
 
@@ -2837,7 +2907,7 @@ violation of OpenPGP, but rather reduce the available algorithms to a
 @mansect bugs
 @chapheading BUGS
 
-On many systems this program should be installed as setuid(root). This
+On older systems this program should be installed as setuid(root). This
 is necessary to lock memory pages. Locking memory pages prevents the
 operating system from writing memory pages (which may contain
 passphrases or other sensitive material) to disk. If you get no
@@ -2852,6 +2922,10 @@ powered off mode.  Unless measures are taken in the operating system
 to protect the saved memory, passphrases or other sensitive material
 may be recoverable from it later.
 
+Before you report a bug you should first search the mailing list
+archives for similar problems and second check whether such a bug has
+already been reported to our bug tracker at http://bugs.gnupg.org .
+
 @mansect see also
 @ifset isman
 @command{gpgv}(1),