common/
[gnupg.git] / doc / gpg.texi
index 21af121..1b85129 100644 (file)
@@ -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
@@ -1521,10 +1530,12 @@ Enable certificate checking if the keyserver presents one (for hkps or
 ldaps).  Defaults to on.
 
 @item ca-cert-file
-Provide a certificate file to override the system default.  Only
+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}
@@ -1758,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
@@ -1968,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.
 
@@ -1986,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.
@@ -2130,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
@@ -2144,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.
@@ -2848,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
@@ -2863,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),