spelling: Fix "synchronize"
[gnupg.git] / doc / gpg.texi
index 7c27fba..c9262c6 100644 (file)
@@ -404,7 +404,10 @@ functionality is also available as the subcommand "passwd" with the
 @opindex delete-keys
 Remove key from the public keyring. In batch mode either @option{--yes} is
 required or the key must be specified by fingerprint. This is a
 @opindex delete-keys
 Remove key from the public keyring. In batch mode either @option{--yes} is
 required or the key must be specified by fingerprint. This is a
-safeguard against accidental deletion of multiple keys.
+safeguard against accidental deletion of multiple keys.  If the
+exclamation mark syntax is used with the fingerprint of a subkey only
+that subkey is deleted; if the exclamation mark is used with the
+fingerprint of the primary key the entire public key is deleted.
 
 @item --delete-secret-keys @var{name}
 @opindex delete-secret-keys
 
 @item --delete-secret-keys @var{name}
 @opindex delete-secret-keys
@@ -413,7 +416,10 @@ specified by fingerprint.  The option @option{--yes} can be used to
 advice gpg-agent not to request a confirmation.  This extra
 pre-caution is done because @command{@gpgname} can't be sure that the
 secret key (as controlled by gpg-agent) is only used for the given
 advice gpg-agent not to request a confirmation.  This extra
 pre-caution is done because @command{@gpgname} can't be sure that the
 secret key (as controlled by gpg-agent) is only used for the given
-OpenPGP public key.
+OpenPGP public key.  If the exclamation mark syntax is used with the
+fingerprint of a subkey only the secret part of that subkey is
+deleted; if the exclamation mark is used with the fingerprint of the
+primary key only the secret part of the primary key is deleted.
 
 
 @item --delete-secret-and-public-key @var{name}
 
 
 @item --delete-secret-and-public-key @var{name}
@@ -434,9 +440,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.
 @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.
 
 only those keys which are new or changed by you.  If no @var{keyIDs}
 are given, @command{@gpgname} does nothing.
 
@@ -491,27 +496,25 @@ signatures, user-IDs and subkeys.
 @opindex receive-keys
 @itemx --recv-keys @var{keyIDs}
 @opindex recv-keys
 @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
 
 @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
 
 @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
 
 @item --fetch-keys @var{URIs}
 @opindex fetch-keys
@@ -624,9 +627,9 @@ fingerprint (preferred) or their keyid.
 @end table
 
 
 @end table
 
 
-@c *******************************************
-@c *******  KEY MANGEMENT COMMANDS  **********
-@c *******************************************
+@c ********************************************
+@c *******  KEY MANAGEMENT COMMANDS  **********
+@c ********************************************
 @node OpenPGP Key Management
 @subsection How to manage your keys
 
 @node OpenPGP Key Management
 @subsection How to manage your keys
 
@@ -675,6 +678,10 @@ supplied passphrase is used for the new key and the agent does not ask
 for it.  To create a key without any protection @code{--passphrase ''}
 may be used.
 
 for it.  To create a key without any protection @code{--passphrase ''}
 may be used.
 
+Note that it is possible to create a primary key and a subkey using
+non-default algorithms by using ``default'' and changing the default
+parameters using the option @option{--default-new-key-algo}.
+
 @item --quick-set-expire @var{fpr} @var{expire} [*|@var{subfprs}]
 @opindex quick-set-expire
 With two arguments given, directly set the expiration time of the
 @item --quick-set-expire @var{fpr} @var{expire} [*|@var{subfprs}]
 @opindex quick-set-expire
 With two arguments given, directly set the expiration time of the
@@ -702,7 +709,8 @@ and other ECC curves.  For example the string ``rsa'' adds an RSA key
 with the default key length; a string ``rsa4096'' requests that the
 key length is 4096 bits.  The string ``future-default'' is an alias
 for the algorithm which will likely be used as default algorithm in
 with the default key length; a string ``rsa4096'' requests that the
 key length is 4096 bits.  The string ``future-default'' is an alias
 for the algorithm which will likely be used as default algorithm in
-future versions of gpg.
+future versions of gpg.  To list the supported ECC curves the command
+@code{gpg --with-colons --list-config curve} can be used.
 
 Depending on the given @var{algo} the subkey may either be an
 encryption subkey or a signing subkey.  If an algorithm is capable of
 
 Depending on the given @var{algo} the subkey may either be an
 encryption subkey or a signing subkey.  If an algorithm is capable of
@@ -1323,6 +1331,10 @@ give the opposite meaning.  The options are:
   meaningful when using @option{--with-colons} along with
   @option{--check-signatures}.
 
   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}
 @end table
 
 @item --verify-options @var{parameters}
@@ -1420,19 +1432,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.
 
 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
 
 @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
 
 @item --keyring @var{file}
 @opindex keyring
@@ -1719,7 +1736,8 @@ Set what trust model GnuPG should follow. The models are:
   @opindex trust-model:auto
   Select the trust model depending on whatever the internal trust
   database says. This is the default model if such a database already
   @opindex trust-model:auto
   Select the trust model depending on whatever the internal trust
   database says. This is the default model if such a database already
-  exists.
+  exists.  Note that a tofu trust model is not considered here and
+  must be enabled explicitly.
 @end table
 
 @item --auto-key-locate @var{mechanisms}
 @end table
 
 @item --auto-key-locate @var{mechanisms}
@@ -1756,12 +1774,11 @@ list.  The default is "local,wkd".
   PGP Universal method of checking @samp{ldap://keys.(thedomain)}.
 
   @item keyserver
   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
 
   @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
 
   @item local
   Locate the key using the local keyrings.  This mechanism allows the user to
@@ -1777,7 +1794,9 @@ list.  The default is "local,wkd".
 
   @item clear
   Clear all defined mechanisms.  This is useful to override
 
   @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
 
 
 @end table
 
@@ -1883,32 +1902,12 @@ are available for all keyserver types, some common options are:
   retrieving keys by subkey id.
 
   @item timeout
   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
   @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
   @code{dirmngr} configuration options instead.
 
 @end table
@@ -2337,7 +2336,13 @@ opposite meaning. The options are:
   on the keyring. This option is the same as running the @option{--edit-key}
   command "clean" after import. Defaults to no.
 
   on the keyring. This option is the same as running the @option{--edit-key}
   command "clean" after import. Defaults to no.
 
-  @item repair-keys.  After import, fix various problems with the
+  @item import-drop-uids
+  Do not import any user ids or their binding signatures.  This option
+  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
   keys.  For example, this reorders signatures, and strips duplicate
   signatures.  Defaults to yes.
 
   keys.  For example, this reorders signatures, and strips duplicate
   signatures.  Defaults to yes.
 
@@ -2501,6 +2506,11 @@ opposite meaning.  The options are:
   running the @option{--edit-key} command "minimize" before export except
   that the local copy of the key is not modified. Defaults to no.
 
   running the @option{--edit-key} command "minimize" before export except
   that the local copy of the key is not modified. Defaults to no.
 
+  @item export-drop-uids
+  Do no export any user id or attribute packets or their associates
+  signatures.  Note that due to missing user ids the resulting output is
+  not strictly RFC-4880 compliant.
+
   @item export-pka
   Instead of outputting the key material output PKA records suitable
   to put into DNS zone files.  An ORIGIN line is printed before each
   @item export-pka
   Instead of outputting the key material output PKA records suitable
   to put into DNS zone files.  An ORIGIN line is printed before each
@@ -2607,7 +2617,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
 @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}.
 
 method.  See also options @option{--aead-algo} and
 @option{--chunk-size}.
 
@@ -2763,7 +2773,7 @@ This option is obsolete; it is handled as an alias for @option{--pgp7}
 
 @item --pgp7
 @opindex 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
 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
@@ -2970,6 +2980,13 @@ smartcard, and "%%" results in a single "%". %k, %K, and %f are only
 meaningful when making a key signature (certification), and %c is only
 meaningful when using the OpenPGP smartcard.
 
 meaningful when making a key signature (certification), and %c is only
 meaningful when using the OpenPGP smartcard.
 
+@item --known-notation @var{name}
+@opindex known-notation
+Adds @var{name} to a list of known critical signature notations.  The
+effect of this is that gpg will not mark a signature with a critical
+signature notation of that name as bad.  Note that gpg already knows
+by default about a few critical signatures notation names.
+
 @item --sig-policy-url @var{string}
 @itemx --cert-policy-url @var{string}
 @itemx --set-policy-url @var{string}
 @item --sig-policy-url @var{string}
 @itemx --cert-policy-url @var{string}
 @itemx --set-policy-url @var{string}
@@ -3012,7 +3029,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
 @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
 
 @item --cipher-algo @var{name}
 @opindex cipher-algo
@@ -3028,7 +3046,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
 @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
 @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
@@ -3071,10 +3089,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
 @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
 
 @item --disable-cipher-algo @var{name}
 @opindex disable-cipher-algo
@@ -3279,7 +3301,8 @@ secret keyrings.
 
 @item --no-keyring
 @opindex no-keyring
 
 @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
 
 @item --skip-verify
 @opindex skip-verify
@@ -3301,7 +3324,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
 @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 | \
 
 @example
       gpg --list-sigs --with-colons USERID | \
@@ -3346,13 +3369,14 @@ user.
 @opindex override-session-key
 Don't use the public key but the session key @var{string} respective
 the session key taken from the first line read from file descriptor
 @opindex override-session-key
 Don't use the public key but the session key @var{string} respective
 the session key taken from the first line read from file descriptor
-@var{fd}.  The format of this string is the same as the one printed
-by @option{--show-session-key}. This option is normally not used but
+@var{fd}.  The format of this string is the same as the one printed by
+@option{--show-session-key}. This option is normally not used but
 comes handy in case someone forces you to reveal the content of an
 encrypted message; using this option you can do this without handing
 out the secret key.  Note that using @option{--override-session-key}
 may reveal the session key to all local users via the global process
 comes handy in case someone forces you to reveal the content of an
 encrypted message; using this option you can do this without handing
 out the secret key.  Note that using @option{--override-session-key}
 may reveal the session key to all local users via the global process
-table.
+table.  Often it is useful to combine this option with
+@option{--no-keyring}.
 
 @item --ask-sig-expire
 @itemx --no-ask-sig-expire
 
 @item --ask-sig-expire
 @itemx --no-ask-sig-expire
@@ -3643,6 +3667,15 @@ Operation is further controlled by a few environment variables:
 
 @end table
 
 
 @end table
 
+When calling the gpg-agent component @command{@gpgname} sends a set of
+environment variables to gpg-agent.  The names of these variables can
+be listed using the command:
+
+@example
+  gpg-connect-agent 'getinfo std_env_names' /bye | awk '$1=="D" @{print $2@}'
+@end example
+
+
 
 @c *******************************************
 @c ***************            ****************
 
 @c *******************************************
 @c ***************            ****************