* keyserver-internal.h, keyserver.c (keyserver_import_pka): Use the
[gnupg.git] / doc / gpg.texi
index 9337fbf..5dccd70 100644 (file)
@@ -141,11 +141,12 @@ For each signature listed, there are several flags in between the
 each signature. From left to right, they are the numbers 1-3 for
 certificate check level (see --ask-cert-level), "L" for a local or
 non-exportable signature (see --lsign-key), "R" for a nonRevocable
-signature (see --nrsign-key), "P" for a signature that contains a
-policy URL (see --cert-policy-url), "N" for a signature that contains
-a notation (see --cert-notation), "X" for an eXpired signature (see
---ask-cert-expire), and the numbers 1-9 or "T" for 10 and above to
-indicate trust signature levels (see the --edit-key command "tsign").
+signature (see the --edit-key command "nrsign"), "P" for a signature
+that contains a policy URL (see --cert-policy-url), "N" for a
+signature that contains a notation (see --cert-notation), "X" for an
+eXpired signature (see --ask-cert-expire), and the numbers 1-9 or "T"
+for 10 and above to indicate trust signature levels (see the
+--edit-key command "tsign").
 
 @item --check-sigs 
 Same as --list-sigs, but the signatures are verified.
@@ -177,35 +178,34 @@ related tasks:
 @table @asis
 
 @item sign
-Make a signature on key of user @code{name}
-If the key is not yet signed by the default
-user (or the users given with -u), the
-program displays the information of the key
-again, together with its fingerprint and
-asks whether it should be signed. This
-question is repeated for all users specified
-with -u.
+Make a signature on key of user @code{name} If the key is not yet
+signed by the default user (or the users given with -u), the program
+displays the information of the key again, together with its
+fingerprint and asks whether it should be signed. This question is
+repeated for all users specified with
+-u.
 
 @item lsign
-Same as --sign but the signature is marked as
-non-exportable and will therefore never be used
-by others. This may be used to make keys valid
-only in the local environment.
+Same as "sign" but the signature is marked as non-exportable and will
+therefore never be used by others. This may be used to make keys
+valid only in the local environment.
 
 @item nrsign
-Same as --sign but the signature is marked as non-revocable and can
+Same as "sign" but the signature is marked as non-revocable and can
 therefore never be revoked.
 
-@item nrlsign
-Combines the functionality of nrsign and lsign to make a signature
-that is both non-revocable and
-non-exportable.
-
 @item tsign
 Make a trust signature. This is a signature that combines the notions
 of certification (like a regular signature), and trust (like the
 "trust" command). It is generally only useful in distinct communities
 or groups.
+@end table
+
+Note that "l" (for local / non-exportable), "nr" (for non-revocable,
+and "t" (for trust) may be freely mixed and prefixed to "sign" to
+create a signature of any type desired.
+
+@table @asis
 
 @item revsig
 Revoke a signature. For every signature which has been generated by
@@ -257,6 +257,17 @@ 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}
+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
 Remove a subkey.
 
@@ -311,33 +322,47 @@ the preferences in effect by including the implied preferences of
 are not already included in the preference list.
 
 @item setpref @code{string}
-Set the list of user ID preferences to @code{string}, 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 remove the
-preferences. Use "gpg --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.
-
-@item updpref
-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 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.
+Set the list of user ID preferences to @code{string} for all (or just
+the selected) user IDs. Calling setpref with no arguments sets the
+preference list to the default (either built-in or set via
+--default-preference-list), and calling setpref with "none" as the
+argument sets an empty preference list. Use "gpg --version" to get a
+list of available algorithms. 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.
 
 @item 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
---keyserver-option honor-keyserver-url. Note that some versions of
-PGP interpret the presence of a keyserver URL as an instruction to
-enable PGP/MIME mail encoding. Setting a value of "none" removes a
-existing preferred keyserver.
+--keyserver-option honor-keyserver-url for more on how this works.
+Note that some versions of PGP interpret the presence of a keyserver
+URL as an instruction to enable PGP/MIME mail encoding. Setting a
+value of "none" removes a existing preferred keyserver.
 
 @item toggle
 Toggle between public and secret key listing.
 
+@item clean
+Cleans keys by removing unusable pieces. This command can be used to
+keep keys neat and clean, and it has no effect aside from that.
+
+@table @asis
+
+@item sigs
+Remove any signatures that are not usable by the trust calculations.
+For example, this removes any signature that does not validate. It
+also removes any signature that is superceded by a later signature, or
+signatures that were revoked.
+
+@item uids
+Compact (by removing all signatures except the selfsig) any user ID
+that is no longer usable (e.g. revoked, or expired).
+@end table
+
+@noindent
+If invoked with no arguments, both `sigs' and `uids' are cleaned.
+
 @item save
 Save all changes to the key rings and quit.
 
@@ -378,19 +403,29 @@ Fully trusted.
 Ultimately trusted.
 @end table
 
+@item --card-edit
+Present a menu to work with a smartcard. The subcommand "help" provides
+an overview on available commands. For a detailed description, please
+see the Card HOWTO at 
+http://www.gnupg.org/documentation/howtos.html#GnuPG-cardHOWTO .
+
+@item --card-status
+Show the content of the smart card.
+
+@item --change-pin
+Present a menu to allow changing the PIN of a smartcard. This
+functionality is also available as the subcommand "passwd" with the
+--card-edit command.
+
 @item --sign-key @code{name}
 Signs a public key with your secret key. This is a shortcut version of
-the subcommand "sign" from --edit.
+the subcommand "sign" from --edit. 
 
 @item --lsign-key @code{name}
 Signs a public key with your secret key but marks it as
 non-exportable. This is a shortcut version of the subcommand "lsign"
 from --edit.
 
-@item --nrsign-key @code{name}
-Signs a public key with your secret key but marks it as non-revocable.
-This is a shortcut version of the subcommand "nrsign" from --edit.
-
 @item --delete-key @code{name}
 Remove key from the public keyring. In batch mode either --yes is
 required or the key must be specified by fingerprint. This is a
@@ -465,6 +500,10 @@ keyservers set (see --keyserver-option honor-keyserver-url).
 Search the keyserver for the given names. Multiple names given here
 will be joined together to create the search string for the keyserver.
 Option --keyserver must be used to give the name of this keyserver.
+Keyservers that support different search methods allow using the
+syntax specified in "How to specify a user ID" below. Note that
+different keyserver types support different search methods. Currently
+only LDAP supports them all.
 
 @item --update-trustdb
 Do trust database maintenance. This command iterates over all keys
@@ -578,18 +617,16 @@ used, the default key is the first key found in the secret keyring.
 Note that -u or --local-user overrides this option.
 
 @item -r, --recipient @code{name}
-@itemx 
 Encrypt for user id @code{name}. If this option or --hidden-recipient
 is not specified, GnuPG asks for the user-id unless
 --default-recipient is given.
 
 @item -R, --hidden-recipient @code{name}
-@itemx 
-Encrypt for user id @code{name}, but hide the keyid of the key. This
-option hides the receiver of the message and is a countermeasure
-against traffic analysis. If this option or --recipient is not
-specified, GnuPG asks for the user-id unless --default-recipient is
-given.
+Encrypt for user ID @code{name}, but hide the key ID of this user's
+key. This option helps to hide the receiver of the message and is a
+limited countermeasure against traffic analysis. If this option or
+--recipient is not specified, GnuPG asks for the user ID unless
+--default-recipient is given.
 
 @item --default-recipient @code{name}
 Use @code{name} as default recipient if option --recipient is not used and
@@ -695,11 +732,6 @@ this option is not specified, the certification level used is set via
 specific levels and how they are used. --no-ask-cert-level disables
 this option. This option defaults to no.
 
-@item --min-cert-level
-When building the trust database, disregard any signatures with a
-certification level below this. Defaults to 2, which disregards level
-1 signatures.
-
 @item --default-cert-level @code{n}
 The default to use for the check level when signing a key.
 
@@ -729,6 +761,12 @@ and "extensive" mean to you.
 
 This option defaults to 0 (no particular claim).
 
+@item --min-cert-level
+When building the trust database, treat any signatures with a
+certification level below this as invalid. Defaults to 2, which
+disregards level 1 signatures. Note that level 0 "no particular
+claim" signatures are always accepted.
+
 @item --trusted-key @code{long key ID}
 Assume that the specified key (which must be given
 as a full 8 byte key ID) is as trustworthy as one of
@@ -844,10 +882,11 @@ timeout applies separately to each key retrieval, and not to the
 --recv-keys command as a whole. Defaults to 30 seconds.
 
 @item http-proxy
-For keyserver schemes that use HTTP (such as HKP), try to access the
-keyserver over a proxy. If a @code{value} is specified, use this as
-the HTTP proxy. If no @code{value} is specified, try to use the value
-of the environment variable "http_proxy".
+For HTTP-like keyserver schemes that (such as HKP and HTTP itself),
+try to access the keyserver over a proxy. If a @code{value} is
+specified, use this as the HTTP proxy. If no @code{value} is
+specified, try to use the value of the environment variable
+"http_proxy".
 
 @item auto-key-retrieve
 This option enables the automatic retrieving of keys from a keyserver
@@ -868,7 +907,7 @@ opposite meaning. The options are:
 
 @table @asis
 
-@item allow-local-sigs
+@item import-local-sigs
 Allow importing key signatures marked as "local". This is not
 generally useful unless a shared keyring scheme is being used.
 Defaults to no.
@@ -884,6 +923,19 @@ yes for keyserver --recv-keys.
 @item merge-only
 During import, allow key updates to existing keys, but do not allow
 any new keys to be imported. Defaults to no.
+
+@item import-clean-sigs
+After import, remove any signatures from the new key that are not
+usable. This is the same as running the --edit-key command "clean
+sigs" after import. Defaults to no.
+
+@item import-clean-uids
+After import, compact (remove all signatures from) any user IDs from
+the new key that are not usable. This is the same as running the
+--edit-key command "clean uids" after import. Defaults to no.
+
+@item import-clean
+Identical to "import-clean-sigs import-clean-uids".
 @end table
 
 @item --export-options @code{parameters}
@@ -893,19 +945,39 @@ opposite meaning. The options are:
 
 @table @asis
 
-@item include-local-sigs
+@item export-local-sigs
 Allow exporting key signatures marked as "local". This is not
 generally useful unless a shared keyring scheme is being used.
 Defaults to no.
 
-@item include-attributes
+@item export-attributes
 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.
 
-@item include-sensitive-revkeys
+@item export-sensitive-revkeys
 Include designated revoker information that was marked as
 "sensitive". Defaults to no.
+
+@item export-minimal
+Export the smallest key possible. Currently this is done by leaving
+out any signatures that are not self-signatures. Defaults to no.
+
+@item export-clean-sigs
+Do not export any signatures that are not usable. This is the same as
+running the --edit-key command "clean sigs" before export. Defaults
+to no.
+
+@item export-clean-uids
+Compact (remove all signatures from) user IDs on the key being
+exported if the user IDs are not usable. This is the same as running
+the --edit-key command "clean uids" before export. Defaults to no.
+
+@item export-reset-subkey-passwd
+When using the "--export-secret-subkeys" command, this option resets
+the passphrases for all exported subkeys to empty. This is useful
+when the exported subkey is to be used on an unattended machine where
+a passphrase doesn't necessarily make sense. Defaults to no.
 @end table
 
 @item --list-options @code{parameters}
@@ -1022,6 +1094,8 @@ 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.
+Note, that on W32 system this value is ignored when searching for
+keyserver helpers.
 
 @item --show-keyring
 Display the keyring name at the head of key listings to show which
@@ -1060,12 +1134,39 @@ used it defaults to "~/.gnupg". It does not make sense to use this in
 a options file. This also overrides the environment variable
 $GNUPGHOME.
 
+@item --pcsc-driver @code{file}
+Use @code{file} to access the smartcard reader. The current default
+is `libpcsclite.so'. Instead of using this option you might also
+want to install a symbolic link to the default file name
+(e.g. from `libpcsclite.so.1').
+
+@item --ctapi-driver @code{file}
+Use @code{file} to access the smartcard reader. The current default
+is `libtowitoko.so'. Note that the use of this interface is
+deprecated; it may be removed in future releases.
+
+@item --disable-ccid
+Disable the integrated support for CCID compliant readers. This
+allows to fall back to one of the other drivers even if the internal
+CCID driver can handle the reader. Note, that CCID support is only
+available if libusb was available at build time.
+
+@item --reader-port @code{number_or_string}
+This option may be used to specify the port of the card terminal. A
+value of 0 refers to the first serial device; add 32768 to access USB
+devices. The default is 32768 (first USB device). PC/SC or CCID
+readers might need a string here; run the program in verbose mode to get
+a list of available readers. The default is then the first reader
+found.
+
 @item --display-charset @code{name}
 Set the name of the native character set. This is used to convert
-some informational strings like user IDs to the 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
-chosen set. Valid values for @code{name} are:
+some informational strings like user IDs to the proper UTF-8 encoding.
+Note that this has nothing to do with the character set of data to be
+encrypted or signed; GnuPG does not recode user supplied data. If
+this option is not used, the default character set is determined from
+the current locale. A verbosity level of 3 shows the chosen set.
+Valid values for @code{name} are:
 
 @table @asis
 
@@ -1133,22 +1234,26 @@ There is a slight performance overhead using it.
 Write special status strings to the file descriptor @code{n}.
 See the file DETAILS in the documentation for a listing of them.
 
+@item --status-file @code{file}
+Same as --status-fd, except the status data is written to file
+@code{file}.
+
 @item --logger-fd @code{n}
 Write log output to file descriptor @code{n} and not to stderr.
 
+@item --logger-file @code{file}
+Same as --logger-fd, except the logger data is written to file
+@code{file}.
+
 @item --attribute-fd @code{n}
 Write attribute subpackets to the file descriptor @code{n}. This is
 most useful for use with --status-fd, since the status messages are
 needed to separate out the various subpackets from the stream
 delivered to the file descriptor.
 
-@item --sk-comments
-@itemx --no-sk-comments
-Include secret key comment packets when exporting secret keys. This
-is a GnuPG extension to the OpenPGP standard, and is off by default.
-Please note that this has nothing to do with the comments in clear
-text signatures or armor headers. --no-sk-comments disables this
-option.
+@item --attribute-file @code{file}
+Same as --attribute-fd, except the attribute data is written to file
+@code{file}.
 
 @item --comment @code{string}
 @itemx --no-comments
@@ -1156,6 +1261,10 @@ Use @code{string} as a comment string in clear text signatures and
 ASCII armored messages or keys (see --armor). The default behavior is
 not to use a comment string. --comment may be repeated multiple times
 to get multiple comment strings. --no-comments removes all comments.
+It is a good idea to keep the length of a single comment below 60
+characters to avoid problems with mail programs wrapping such lines.
+Note that comment lines, like all other header lines, are not
+protected by the signature.
 
 @item --emit-version
 @itemx --no-emit-version
@@ -1167,15 +1276,16 @@ Force inclusion of the version string in ASCII armored output.
 @itemx -N, --set-notation @code{name=value}
 Put the name value pair into the signature as notation data.
 @code{name} must consist only of printable characters or spaces, and
-must contain a '@@' character. This is to help prevent pollution of
-the IETF reserved notation namespace. The --expert flag overrides the
-'@@' check. @code{value} may be any printable string; it will be
-encoded in UTF8, so you should check that your --display-charset is
-set correctly. If you prefix @code{name} with an exclamation mark (!),
-the notation data will be flagged as critical (rfc2440:5.2.3.15).
---sig-notation sets a notation for data signatures. --cert-notation
-sets a notation for key signatures (certifications). --set-notation
-sets both.
+must contain a '@@' character in the form keyname@@domain.example.com
+(substituting the appropriate keyname and domain name, of course).
+This is to help prevent pollution of the IETF reserved notation
+namespace. The --expert flag overrides the '@@' check. @code{value}
+may be any printable string; it will be encoded in UTF8, so you should
+check that your --display-charset is set correctly. If you prefix
+@code{name} with an exclamation mark (!), the notation data will be
+flagged as critical (rfc2440:5.2.3.15). --sig-notation sets a
+notation for data signatures. --cert-notation sets a notation for key
+signatures (certifications). --set-notation sets both.
 
 There are special codes that may be used in notation names. "%k" will
 be expanded into the key ID of the key being signed, "%K" into the
@@ -1350,11 +1460,12 @@ disables this option.
 
 @item --throw-keyids
 @itemx --no-throw-keyids
-Do not put the recipient keyid into encrypted packets. This option
-hides the receiver of the message and is a countermeasure against
-traffic analysis. It may slow down the decryption process because all
-available secret keys are tried. --no-throw-keyids disables this
-option.
+Do not put the recipient key IDs into encrypted messages. This helps
+to hide the receivers of the message and is a limited countermeasure
+against traffic analysis. On the receiving side, it may slow down the
+decryption process because all available secret keys must be tried.
+--no-throw-keyids disables this option. This option is essentially
+the same as using --hidden-recipient for all recipients.
 
 @item --not-dash-escaped
 This option changes the behavior of cleartext signatures
@@ -1379,6 +1490,17 @@ Read the passphrase from file descriptor @code{n}. If you use
 can only be used if only one passphrase is supplied.
 Don't use this option if you can avoid it.
 
+@item --passphrase-file @code{file}
+Read the passphrase from file @code{file}. This can only be used if
+only one passphrase is supplied. Obviously, a passphrase stored in a
+file is of questionable security. Don't use this option if you can
+avoid it.
+
+@item --passphrase @code{string}
+Use @code{string} as the passphrase. This can only be used if only one
+passphrase is supplied. Obviously, this is of very questionable
+security. Don't use this option if you can avoid it.
+
 @item --command-fd @code{n}
 This is a replacement for the deprecated shared-memory IPC mode.
 If this option is enabled, user input on questions is not expected
@@ -1386,6 +1508,10 @@ from the TTY but from the given file descriptor. It should be used
 together with --status-fd. See the file doc/DETAILS in the source
 distribution for details on how to use it.
 
+@item --command-file @code{file}
+Same as --command-fd, except the commands are read out of file
+@code{file}
+
 @item --use-agent
 @itemx --no-use-agent
 Try to use the GnuPG-Agent. Please note that this agent is still under
@@ -1546,6 +1672,23 @@ is accessing those files. A bootable floppy with a stand-alone
 encryption system will probably use this. Improper usage of this
 option may lead to data and key corruption.
 
+@item --exit-on-status-write-error
+This option will cause write errors on the status FD to immediately
+terminate the process. That should in fact be the default but it
+never worked this way and thus we need an option to enable this, so
+that the change won't break applications which close their end of a
+status fd connected pipe too early. Using this option along with
+--enable-progress-filter may be used to cleanly cancel long running
+gpg operations.
+
+@item --limit-card-insert-tries @code{n}
+With @code{n} greater than 0 the number of prompts asking to insert a
+smartcard gets limited to N-1. Thus with a value of 1 gpg won't at
+all ask to insert a card if none has been inserted at startup. This
+option is useful in the configuration file in case an application does
+not know about the smartcard support and waits ad infinitum for an
+inserted card.
+
 @item --no-random-seed-file
 GnuPG uses a file to store its internal random pool over invocations.
 This makes random generation faster; however sometimes write operations
@@ -1577,6 +1720,11 @@ supressed on the command line.
 @item --no-mdc-warning
 Suppress the warning about missing MDC integrity protection.
 
+@item --require-secmem
+@itemx --no-require-secmem
+Refuse to run if GnuPG cannot get secure memory. Defaults to no
+(i.e. run, but give a warning).
+
 @item --no-armor
 Assume the input data is not in ASCII armored format.
 
@@ -1650,22 +1798,38 @@ handing out the secret key.
 @item --ask-sig-expire
 @itemx --no-ask-sig-expire
 When making a data signature, prompt for an expiration time. If this
-option is not specified, the expiration time is "never".
---no-ask-sig-expire disables this option.
+option is not specified, the expiration time set via
+--default-sig-expire is used. --no-ask-sig-expire disables this
+option.
+
+@item --default-sig-expire
+The default expiration time to use for signature expiration. Valid
+values are "0" for no expiration, a number followed by the letter d
+(for days), w (for weeks), m (for months), or y (for years) (for
+example "2m" for two months, or "5y" for five years), or an absolute
+date in the form YYYY-MM-DD. Defaults to "0".
 
 @item --ask-cert-expire
 @itemx --no-ask-cert-expire
 When making a key signature, prompt for an expiration time. If this
-option is not specified, the expiration time is "never".
---no-ask-cert-expire disables this option.
+option is not specified, the expiration time set via
+--default-cert-expire is used. --no-ask-cert-expire disables this
+option.
+
+@item --default-cert-expire
+The default expiration time to use for key signature expiration.
+Valid values are "0" for no expiration, a number followed by the
+letter d (for days), w (for weeks), m (for months), or y (for years)
+(for example "2m" for two months, or "5y" for five years), or an
+absolute date in the form YYYY-MM-DD. Defaults to "0".
 
 @item --expert
 @itemx --no-expert
 Allow the user to do certain nonsensical or "silly" things like
 signing an expired or revoked key, or certain potentially incompatible
-things like generating deprecated key types. This also disables
-certain warning messages about potentially incompatible actions. As
-the name implies, this option is for experts only. If you don't fully
+things like generating unusual key types. This also disables certain
+warning messages about potentially incompatible actions. As the name
+implies, this option is for experts only. If you don't fully
 understand the implications of what it allows you to do, leave this
 off. --no-expert disables this option.
 
@@ -1737,10 +1901,9 @@ preferences. The most highly ranked algorithm in this list is also
 used when there are no recipient keys to consider (e.g. --symmetric).
 
 @item --default-preference-list @code{string}
-Set the list of default preferences to @code{string}, this list should
-be a string similar to the one printed by the command "pref" in the
-edit menu. This affects both key generation and "updpref" in the edit
-menu.
+Set the list of default preferences to @code{string}. This preference
+list is used for new keys and becomes the default for "setpref" in the
+edit menu.
 
 @item --list-config 
 Display various internal configuration parameters of GnuPG. This
@@ -1787,10 +1950,9 @@ Using an exact to match string. The equal sign indicates this.
 Using the email address part which must match exactly. The left angle bracket
 indicates this email address mode.
 
-@item +Heinrich Heine duesseldorf
-All words must match exactly (not case sensitive) but can appear in
-any order in the user ID. Words are any sequences of letters,
-digits, the underscore and all characters with bit 7 set.
+@item @@heinrichh
+Match within the <email.address> part of a user ID. The at sign
+indicates this email address mode.
 
 @item Heine
 @itemx *Heine