agent: Stop scdaemon after reload when disable_scdaemon.
[gnupg.git] / doc / gpg.texi
index ba1df4b..fd7dcdd 100644 (file)
@@ -434,9 +434,8 @@ file given with option @option{--output}.  Use together with
 @item --send-keys @var{keyIDs}
 @opindex send-keys
 Similar to @option{--export} but sends the keys to a keyserver.
-Fingerprints may be used instead of key IDs.  Option
-@option{--keyserver} must be used to give the name of this
-keyserver. Don't send your complete keyring to a keyserver --- select
+Fingerprints may be used instead of key IDs.
+Don't send your complete keyring to a keyserver --- select
 only those keys which are new or changed by you.  If no @var{keyIDs}
 are given, @command{@gpgname} does nothing.
 
@@ -491,27 +490,25 @@ signatures, user-IDs and subkeys.
 @opindex receive-keys
 @itemx --recv-keys @var{keyIDs}
 @opindex recv-keys
-Import the keys with the given @var{keyIDs} from a keyserver. Option
-@option{--keyserver} must be used to give the name of this keyserver.
+Import the keys with the given @var{keyIDs} from a keyserver.
 
 @item --refresh-keys
 @opindex refresh-keys
 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. Calling this with no arguments will refresh
-the entire keyring. Option @option{--keyserver} must be used to give the
-name of the keyserver for all keys that do not have preferred keyservers
-set (see @option{--keyserver-options honor-keyserver-url}).
+the entire keyring.
 
 @item --search-keys @var{names}
 @opindex search-keys
-Search the keyserver for the given @var{names}. Multiple names given here will
-be joined together to create the search string for the keyserver.
-Option @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.
+Search the keyserver for the given @var{names}. Multiple names given
+here will be joined together to create the search string for the
+keyserver.  Note that keyservers search for @var{names} in a different
+and simpler way than gpg does.  The best choice is to use a mail
+address.  Due to data privacy reasons keyservers may even not even
+allow searching by user id or mail address and thus may only return
+results when being used with the @option{--recv-key} command to
+search by key fingerprint or keyid.
 
 @item --fetch-keys @var{URIs}
 @opindex fetch-keys
@@ -624,9 +621,9 @@ fingerprint (preferred) or their keyid.
 @end table
 
 
-@c *******************************************
-@c *******  KEY MANGEMENT COMMANDS  **********
-@c *******************************************
+@c ********************************************
+@c *******  KEY MANAGEMENT COMMANDS  **********
+@c ********************************************
 @node OpenPGP Key Management
 @subsection How to manage your keys
 
@@ -1328,6 +1325,10 @@ give the opposite meaning.  The options are:
   meaningful when using @option{--with-colons} along with
   @option{--check-signatures}.
 
+  @item show-only-fpr-mbox
+  @opindex list-options:show-only-fpr-mbox
+  For each user-id which has a valid mail address print
+  only the fingerprint followed by the mail address.
 @end table
 
 @item --verify-options @var{parameters}
@@ -1425,19 +1426,24 @@ viewed (e.g. "f"), "%V" for the calculated validity as a string (e.g.
 and "%%" for an actual percent sign. If neither %i or %I are present,
 then the photo will be supplied to the viewer on standard input.
 
-The default viewer is "xloadimage -fork -quiet -title 'KeyID 0x%k'
-STDIN". Note that if your image viewer program is not secure, then
-executing it from GnuPG does not make it secure.
+On Unix the default viewer is
+@code{xloadimage -fork -quiet -title 'KeyID 0x%k' STDIN}
+with a fallback to
+@code{display -title 'KeyID 0x%k' %i}
+and finally to
+@code{xdg-open %i}.
+On Windows
+@code{!ShellExecute 400 %i} is used; here the command is a meta
+command to use that API call followed by a wait time in milliseconds
+which is used to give the viewer time to read the temporary image file
+before gpg deletes it again.  Note that if your image viewer program
+is not secure, then executing it from gpg does not make it secure.
 
 @item --exec-path @var{string}
 @opindex exec-path
 @efindex PATH
-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 @code{PATH} environment
-variable.
-Note, that on W32 system this value is ignored when searching for
-keyserver helpers.
+Sets a list of directories to search for photo viewers If not provided
+photo viewers use the @code{PATH} environment variable.
 
 @item --keyring @var{file}
 @opindex keyring
@@ -1762,12 +1768,11 @@ list.  The default is "local,wkd".
   PGP Universal method of checking @samp{ldap://keys.(thedomain)}.
 
   @item keyserver
-  Locate a key using whatever keyserver is defined using the
-  @option{--keyserver} option.
+  Locate a key using a keyserver.
 
   @item keyserver-URL
-  In addition, a keyserver URL as used in the @option{--keyserver} option
-  may be used here to query that particular keyserver.
+  In addition, a keyserver URL as used in the @command{dirmngr}
+  configuration may be used here to query that particular keyserver.
 
   @item local
   Locate the key using the local keyrings.  This mechanism allows the user to
@@ -1783,7 +1788,9 @@ list.  The default is "local,wkd".
 
   @item clear
   Clear all defined mechanisms.  This is useful to override
-  mechanisms given in a config file.
+  mechanisms given in a config file.  Note that a @code{nodefault} in
+  @var{mechanisms} will also be cleared unless it is given after the
+  @code{clear}.
 
 @end table
 
@@ -1889,32 +1896,12 @@ are available for all keyserver types, some common options are:
   retrieving keys by subkey id.
 
   @item timeout
-  Tell the keyserver helper program how long (in seconds) to try and
-  perform a keyserver action before giving up. Note that performing
-  multiple actions at the same time uses this timeout value per action.
-  For example, when retrieving multiple keys via @option{--receive-keys}, the
-  timeout applies separately to each key retrieval, and not to the
-  @option{--receive-keys} command as a whole. Defaults to 30 seconds.
-
-  @item http-proxy=@var{value}
-  This option is deprecated.
-  Set the proxy to use for HTTP and HKP keyservers.
-  This overrides any proxy defined in @file{dirmngr.conf}.
-
-  @item verbose
-  This option has no more function since GnuPG 2.1.  Use the
-  @code{dirmngr} configuration options instead.
-
-  @item debug
-  This option has no more function since GnuPG 2.1.  Use the
-  @code{dirmngr} configuration options instead.
-
-  @item check-cert
-  This option has no more function since GnuPG 2.1.  Use the
-  @code{dirmngr} configuration options instead.
-
+  @itemx http-proxy=@var{value}
+  @itemx verbose
+  @itemx debug
+  @itemx check-cert
   @item ca-cert-file
-  This option has no more function since GnuPG 2.1.  Use the
+  These options have no more function since GnuPG 2.1.  Use the
   @code{dirmngr} configuration options instead.
 
 @end table
@@ -2348,7 +2335,8 @@ opposite meaning. The options are:
   can be used to update only the subkeys or other non-user id related
   information.
 
-  @item repair-keys.  After import, fix various problems with the
+  @item repair-keys
+  After import, fix various problems with the
   keys.  For example, this reorders signatures, and strips duplicate
   signatures.  Defaults to yes.
 
@@ -2623,7 +2611,7 @@ These options are obsolete and have no effect since GnuPG 2.1.
 @item --force-aead
 @opindex force-aead
 Force the use of AEAD encryption over MDC encryption.  AEAD is a
-modern and faster way to do authenticated encrytion than the old MDC
+modern and faster way to do authenticated encryption than the old MDC
 method.  See also options @option{--aead-algo} and
 @option{--chunk-size}.
 
@@ -2779,7 +2767,7 @@ This option is obsolete; it is handled as an alias for @option{--pgp7}
 
 @item --pgp7
 @opindex pgp7
-Set up all options to be as PGP 7 compliant as possible. This allowd
+Set up all options to be as PGP 7 compliant as possible. This allowed
 the ciphers IDEA, 3DES, CAST5,AES128, AES192, AES256, and TWOFISH.,
 the hashes MD5, SHA1 and RIPEMD160, and the compression algorithms
 none and ZIP.  This option implies @option{--escape-from-lines} and
@@ -3035,7 +3023,8 @@ to display the message. This option overrides @option{--set-filename}.
 @itemx --no-use-embedded-filename
 @opindex use-embedded-filename
 Try to create a file with a name as embedded in the data. This can be
-a dangerous option as it enables overwriting files. Defaults to no.
+a dangerous option as it enables overwriting files.  Defaults to no.
+Note that the option @option{--output} overrides this option.
 
 @item --cipher-algo @var{name}
 @opindex cipher-algo
@@ -3051,7 +3040,7 @@ same thing.
 @opindex aead-algo
 Specify that the AEAD algorithm @var{name} is to be used.  This is
 useful for symmetric encryption where no key preference are available
-to select the AEAD algorithm.  Runing @command{@gpgname} with option
+to select the AEAD algorithm.  Running @command{@gpgname} with option
 @option{--version} shows the available AEAD algorithms.  In general,
 you do not want to use this option as it allows you to violate the
 OpenPGP standard.  The option @option{--personal-aead-preferences} is
@@ -3094,10 +3083,14 @@ the same thing.
 @opindex cert-digest-algo
 Use @var{name} as the message digest algorithm used when signing a
 key. Running the program with the command @option{--version} yields a
-list of supported algorithms. Be aware that if you choose an algorithm
-that GnuPG supports but other OpenPGP implementations do not, then some
-users will not be able to use the key signatures you make, or quite
-possibly your entire key.
+list of supported algorithms.  Be aware that if you choose an
+algorithm that GnuPG supports but other OpenPGP implementations do
+not, then some users will not be able to use the key signatures you
+make, or quite possibly your entire key.  Note also that a public key
+algorithm must be compatible with the specified digest algorithm; thus
+selecting an arbitrary digest algorithm may result in error messages
+from lower crypto layers or lead to security flaws.
+
 
 @item --disable-cipher-algo @var{name}
 @opindex disable-cipher-algo
@@ -3302,7 +3295,8 @@ secret keyrings.
 
 @item --no-keyring
 @opindex no-keyring
-Do not add use any keyrings even if specified as options.
+Do not use any keyring at all.  This overrides the default and all
+options which specify keyrings.
 
 @item --skip-verify
 @opindex skip-verify
@@ -3324,7 +3318,7 @@ command has the same effect as using @option{--list-keys} with
 @option{--with-sig-list}.  Note that in contrast to
 @option{--check-signatures} the key signatures are not verified.  This
 command can be used to create a list of signing keys missing in the
-lcoal keyring; for example:
+local keyring; for example:
 
 @example
       gpg --list-sigs --with-colons USERID | \