* keyserver-internal.h, keyserver.c (keyserver_import_pka): Use the
[gnupg.git] / doc / gpg.texi
index 2871650..5dccd70 100644 (file)
@@ -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,21 +322,15 @@ 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
@@ -338,6 +343,26 @@ 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,9 +403,23 @@ 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
@@ -461,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
@@ -574,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
@@ -691,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.
 
@@ -725,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
@@ -881,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}
@@ -907,6 +962,22 @@ Include designated revoker information that was marked as
 @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}
@@ -1023,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
@@ -1061,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
 
@@ -1134,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
@@ -1157,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
@@ -1168,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
@@ -1351,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
@@ -1380,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
@@ -1387,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
@@ -1547,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
@@ -1656,14 +1798,30 @@ 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
@@ -1743,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
@@ -1793,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