dirmngr: New option --resolver-timeout.
[gnupg.git] / doc / dirmngr.texi
index b6b70ea..5b4e68b 100644 (file)
@@ -66,7 +66,7 @@ abbreviate this command.
 @item --help, -h
 @opindex help
 Print a usage message summarizing the most useful command-line options.
 @item --help, -h
 @opindex help
 Print a usage message summarizing the most useful command-line options.
-Not that you cannot abbreviate this command.
+Note that you cannot abbreviate this command.
 
 @item --dump-options
 @opindex dump-options
 
 @item --dump-options
 @opindex dump-options
@@ -82,8 +82,16 @@ This is only used for testing.
 @item --daemon
 @opindex daemon
 Run in background daemon mode and listen for commands on a socket.
 @item --daemon
 @opindex daemon
 Run in background daemon mode and listen for commands on a socket.
-Note that this also changes the default home directory and enables the
-internal certificate validation code.  This mode is deprecated.
+This is the way @command{dirmngr} is started on demand by the other
+GnuPG components.  To force starting @command{dirmngr} it is in
+general best to use @code{gpgconf --launch dirmngr}.
+
+@item --supervised
+@opindex supervised
+Run in the foreground, sending logs to stderr, and listening on file
+descriptor 3, which must already be bound to a listening socket.  This
+is useful when running under systemd or other similar process
+supervision schemes.  This option is not supported on Windows.
 
 @item --list-crls
 @opindex list-crls
 
 @item --list-crls
 @opindex list-crls
@@ -102,7 +110,7 @@ so that @code{gpgsm} can help dirmngr.
 @item --fetch-crl @var{url}
 @opindex fetch-crl
 This command requires an URL as additional argument, and it will make
 @item --fetch-crl @var{url}
 @opindex fetch-crl
 This command requires an URL as additional argument, and it will make
-dirmngr try to retrieve an import the CRL from that @var{url} into
+dirmngr try to retrieve and import the CRL from that @var{url} into
 it's cache.  This is mainly useful for debugging purposes.  The
 @command{dirmngr-client} provides the same feature for a running dirmngr.
 
 it's cache.  This is mainly useful for debugging purposes.  The
 @command{dirmngr-client} provides the same feature for a running dirmngr.
 
@@ -134,21 +142,11 @@ per-user configuration file.  The default configuration file is named
 @item --homedir @var{dir}
 @opindex options
 Set the name of the home directory to @var{dir}.  This option is only
 @item --homedir @var{dir}
 @opindex options
 Set the name of the home directory to @var{dir}.  This option is only
-effective when used on the command line.  The default depends on the
-running mode:
-
-@table @asis
-
-@item With @code{--daemon} given on the commandline
-the directory named @file{@value{SYSCONFDIR}} is used for configuration files
-and @file{@value{LOCALCACHEDIR}} for cached CRLs.
-
-@item Without @code{--daemon} given on the commandline
+effective when used on the command line.  The default is
 the directory named @file{.gnupg} directly below the home directory
 of the user unless the environment variable @code{GNUPGHOME} has been set
 the directory named @file{.gnupg} directly below the home directory
 of the user unless the environment variable @code{GNUPGHOME} has been set
-in which case its value will be used.  All kind of data is stored below
+in which case its value will be used.  Many kinds of data are stored within
 this directory.
 this directory.
-@end table
 
 
 @item -v
 
 
 @item -v
@@ -196,7 +194,7 @@ however carefully selected to best aid in debugging.
 
 @item --debug @var{flags}
 @opindex debug
 
 @item --debug @var{flags}
 @opindex debug
-This option is only useful for debugging and the behaviour may change at
+This option is only useful for debugging and the behavior may change at
 any time without notice.  FLAGS are bit encoded and may be given in
 usual C-Syntax.
 
 any time without notice.  FLAGS are bit encoded and may be given in
 usual C-Syntax.
 
@@ -214,6 +212,12 @@ When running in server mode, wait @var{n} seconds before entering the
 actual processing loop and print the pid.  This gives time to attach a
 debugger.
 
 actual processing loop and print the pid.  This gives time to attach a
 debugger.
 
+@item --disable-check-own-socket
+@opindex disable-check-own-socket
+On some platforms @command{dirmngr} is able to detect the removal of
+its socket file and shutdown itself.  This option disable this
+self-test for debugging purposes.
+
 @item -s
 @itemx --sh
 @itemx -c
 @item -s
 @itemx --sh
 @itemx -c
@@ -223,7 +227,7 @@ debugger.
 @opindex c
 @opindex csh
 Format the info output in daemon mode for use with the standard Bourne
 @opindex c
 @opindex csh
 Format the info output in daemon mode for use with the standard Bourne
-shell respective the C-shell . The default ist to guess it based on the
+shell respective the C-shell. The default is to guess it based on the
 environment variable @code{SHELL} which is in almost all cases
 sufficient.
 
 environment variable @code{SHELL} which is in almost all cases
 sufficient.
 
@@ -240,6 +244,30 @@ this still leaks the DNS queries; e.g. to lookup the hosts in a
 keyserver pool.  Certain other features are disabled if this mode is
 active.
 
 keyserver pool.  Certain other features are disabled if this mode is
 active.
 
+@item --standard-resolver
+@opindex standard-resolver
+This option forces the use of the system's standard DNS resolver code.
+This is mainly used for debugging.  Note that on Windows a standard
+resolver is not used and all DNS access will return the error ``Not
+Implemented'' if this function is used.
+
+@item --recursive-resolver
+@opindex recursive-resolver
+When possible use a recursive resolver instead of a stub resolver.
+
+@item --resolver-timeout @var{n}
+Set the timeout for the DNS resolver to N seconds.  The default are 30
+seconds.
+
+@item --allow-version-check
+@opindex allow-version-check
+Allow Dirmngr to connect to @code{https://versions.gnupg.org} to get
+the list of current software versions.  If this option is enabled, or
+if @option{use-tor} is active, the list is retrieved when the local
+copy does not exist or is older than 5 to 7 days.  See the option
+@option{--query-swdb} of the command @command{gpgconf} for more
+details.
+
 @item --keyserver @var{name}
 @opindex keyserver
 Use @var{name} as your keyserver.  This is the server that @command{gpg}
 @item --keyserver @var{name}
 @opindex keyserver
 Use @var{name} as your keyserver.  This is the server that @command{gpg}
@@ -264,6 +292,8 @@ service (.onion), Dirmngr selects the keyserver to use depending on
 whether Tor is locally running or not.  The check for a running Tor is
 done for each new connection.
 
 whether Tor is locally running or not.  The check for a running Tor is
 done for each new connection.
 
+If no keyserver is explicitly configured, dirmngr will use the
+built-in default of hkps://hkps.pool.sks-keyservers.net.
 
 @item --nameserver @var{ipaddr}
 @opindex nameserver
 
 @item --nameserver @var{ipaddr}
 @opindex nameserver
@@ -271,8 +301,7 @@ In ``Tor mode'' Dirmngr uses a public resolver via Tor to resolve DNS
 names.  If the default public resolver, which is @code{8.8.8.8}, shall
 not be used a different one can be given using this option.  Note that
 a numerical IP address must be given (IPv6 or IPv4) and that no error
 names.  If the default public resolver, which is @code{8.8.8.8}, shall
 not be used a different one can be given using this option.  Note that
 a numerical IP address must be given (IPv6 or IPv4) and that no error
-checking is done for @var{ipaddr}.  DNS queries in Tor mode do only
-work if GnuPG as been build with ADNS support.
+checking is done for @var{ipaddr}.
 
 @item --disable-ldap
 @opindex disable-ldap
 
 @item --disable-ldap
 @opindex disable-ldap
@@ -332,8 +361,7 @@ configured LDAP server if the connection using the "proxy" failed.
 @opindex ldapserverlist-file
 Read the list of LDAP servers to consult for CRLs and certificates from
 file instead of the default per-user ldap server list file. The default
 @opindex ldapserverlist-file
 Read the list of LDAP servers to consult for CRLs and certificates from
 file instead of the default per-user ldap server list file. The default
-value for @var{file} is @file{dirmngr_ldapservers.conf} or
-@file{ldapservers.conf} when running in @option{--daemon} mode.
+value for @var{file} is @file{dirmngr_ldapservers.conf}.
 
 This server list file contains one LDAP server per line in the format
 
 
 This server list file contains one LDAP server per line in the format
 
@@ -358,11 +386,11 @@ out. The default is currently 100 seconds.  0 will never timeout.
 
 @item --add-servers
 @opindex add-servers
 
 @item --add-servers
 @opindex add-servers
-This options makes dirmngr add any servers it discovers when validating
+This option makes dirmngr add any servers it discovers when validating
 certificates against CRLs to the internal list of servers to consult for
 certificates and CRLs.
 
 certificates against CRLs to the internal list of servers to consult for
 certificates and CRLs.
 
-This options is useful when trying to validate a certificate that has
+This option is useful when trying to validate a certificate that has
 a CRL distribution point that points to a server that is not already
 listed in the ldapserverlist. Dirmngr will always go to this server and
 try to download the CRL, but chances are high that the certificate used
 a CRL distribution point that points to a server that is not already
 listed in the ldapserverlist. Dirmngr will always go to this server and
 try to download the CRL, but chances are high that the certificate used
@@ -391,8 +419,8 @@ not contain information about an assigned responder.  Note, that
 @item --ocsp-signer @var{fpr}|@var{file}
 @opindex ocsp-signer
 Use the certificate with the fingerprint @var{fpr} to check the
 @item --ocsp-signer @var{fpr}|@var{file}
 @opindex ocsp-signer
 Use the certificate with the fingerprint @var{fpr} to check the
-responses of the default OCSP Responder.  Alternativly a filename can be
-given in which case the respinse is expected to be signed by one of the
+responses of the default OCSP Responder.  Alternatively a filename can be
+given in which case the response is expected to be signed by one of the
 certificates described in that file.  Any argument which contains a
 slash, dot or tilde is considered a filename.  Usual filename expansion
 takes place: A tilde at the start followed by a slash is replaced by the
 certificates described in that file.  Any argument which contains a
 slash, dot or tilde is considered a filename.  Usual filename expansion
 takes place: A tilde at the start followed by a slash is replaced by the
@@ -413,7 +441,7 @@ prefix with a hash mark are ignored.
 @item --ocsp-max-clock-skew @var{n}
 @opindex ocsp-max-clock-skew
 The number of seconds a skew between the OCSP responder and them local
 @item --ocsp-max-clock-skew @var{n}
 @opindex ocsp-max-clock-skew
 The number of seconds a skew between the OCSP responder and them local
-clock is accepted.  Default is 600 (20 minutes).
+clock is accepted.  Default is 600 (10 minutes).
 
 @item --ocsp-max-period @var{n}
 @opindex ocsp-max-period
 
 @item --ocsp-max-period @var{n}
 @opindex ocsp-max-period
@@ -449,6 +477,11 @@ the file is in PEM format a suffix of @code{.pem} is expected for
 @var{file}.  This option may be given multiple times to add more
 root certificates.  Tilde expansion is supported.
 
 @var{file}.  This option may be given multiple times to add more
 root certificates.  Tilde expansion is supported.
 
+If no @code{hkp-cacert} directive is present, dirmngr will make a
+reasonable choice: if the keyserver in question is the special pool
+@code{hkps.pool.sks-keyservers.net}, it will use the bundled root
+certificate for that pool.  Otherwise, it will use the system CAs.
+
 @end table
 
 
 @end table
 
 
@@ -487,10 +520,10 @@ Note that for OCSP responses the certificate specified using the option
 
 @item /etc/gnupg/extra-certs
 This directory may contain extra certificates which are preloaded
 
 @item /etc/gnupg/extra-certs
 This directory may contain extra certificates which are preloaded
-into the interal cache on startup. Applications using dirmngr (e.g. gpgsm)
+into the internal cache on startup. Applications using dirmngr (e.g. gpgsm)
 can request cached certificates to complete a trust chain.
 This is convenient in cases you have a couple intermediate CA certificates
 can request cached certificates to complete a trust chain.
 This is convenient in cases you have a couple intermediate CA certificates
-or certificates ususally used to sign OCSP responses.
+or certificates usually used to sign OCSP responses.
 These certificates are first tried before going
 out to the net to look for them.  These certificates must also be
 @acronym{DER} encoded and suffixed with @file{.crt} or @file{.der}.
 These certificates are first tried before going
 out to the net to look for them.  These certificates must also be
 @acronym{DER} encoded and suffixed with @file{.crt} or @file{.der}.
@@ -533,7 +566,7 @@ certificates have been loaded correctly.
 @c
 @mansect signals
 @node Dirmngr Signals
 @c
 @mansect signals
 @node Dirmngr Signals
-@section Use of signals.
+@section Use of signals
 
 A running @command{dirmngr} may be controlled by signals, i.e. using
 the @command{kill} command to send a signal to the process.
 
 A running @command{dirmngr} may be controlled by signals, i.e. using
 the @command{kill} command to send a signal to the process.
@@ -544,7 +577,7 @@ Here is a list of supported signals:
 
 @item SIGHUP
 @cpindex SIGHUP
 
 @item SIGHUP
 @cpindex SIGHUP
-This signals flushes all internally cached CRLs as well as any cached
+This signal flushes all internally cached CRLs as well as any cached
 certificates.  Then the certificate cache is reinitialized as on
 startup.  Options are re-read from the configuration file.  Instead of
 sending this signal it is better to use
 certificates.  Then the certificate cache is reinitialized as on
 startup.  Options are re-read from the configuration file.  Instead of
 sending this signal it is better to use
@@ -741,7 +774,7 @@ this the root certificate:
   C: END
 @end example
 
   C: END
 @end example
 
-Only this answer will let Dirmngr consider the CRL as valid.
+Only this answer will let Dirmngr consider the certificate as valid.
 
 
 @node Dirmngr CHECKCRL
 
 
 @node Dirmngr CHECKCRL
@@ -750,7 +783,7 @@ Only this answer will let Dirmngr consider the CRL as valid.
 Check whether the certificate with FINGERPRINT (SHA-1 hash of the
 entire X.509 certificate blob) is valid or not by consulting the CRL
 responsible for this certificate.  If the fingerprint has not been
 Check whether the certificate with FINGERPRINT (SHA-1 hash of the
 entire X.509 certificate blob) is valid or not by consulting the CRL
 responsible for this certificate.  If the fingerprint has not been
-given or the certificate is not know, the function inquires the
+given or the certificate is not known, the function inquires the
 certificate using:
 
 @example
 certificate using:
 
 @example
@@ -778,7 +811,7 @@ revoked or one of the usual error codes from libgpg-error.
 @end example
 
 Check whether the certificate with @var{fingerprint} (the SHA-1 hash of
 @end example
 
 Check whether the certificate with @var{fingerprint} (the SHA-1 hash of
-the entire X.509 certificate blob) is valid by consulting the appropiate
+the entire X.509 certificate blob) is valid by consulting the appropriate
 OCSP responder.  If the fingerprint has not been given or the
 certificate is not known by Dirmngr, the function inquires the
 certificate using:
 OCSP responder.  If the fingerprint has not been given or the
 certificate is not known by Dirmngr, the function inquires the
 certificate using:
@@ -810,7 +843,7 @@ revoked or one of the usual error codes from libgpg-error.
 
 Put a certificate into the internal cache.  This command might be
 useful if a client knows in advance certificates required for a test and
 
 Put a certificate into the internal cache.  This command might be
 useful if a client knows in advance certificates required for a test and
-wnats to make sure they get added to the internal cache.  It is also
+wants to make sure they get added to the internal cache.  It is also
 helpful for debugging.  To get the actual certificate, this command
 immediately inquires it using
 
 helpful for debugging.  To get the actual certificate, this command
 immediately inquires it using
 
@@ -825,7 +858,7 @@ as a binary blob.
 
 @noindent
 The return code is 0 for success; i.e. the certificate has not been
 
 @noindent
 The return code is 0 for success; i.e. the certificate has not been
-succesfully cached or one of the usual error codes from libgpg-error.
+successfully cached or one of the usual error codes from libgpg-error.
 
 @node Dirmngr VALIDATE
 @subsection Validate a certificate for debugging
 
 @node Dirmngr VALIDATE
 @subsection Validate a certificate for debugging
@@ -877,7 +910,7 @@ as a binary blob.
 @c @var{fingerprint} is optional and expected to be the SHA-1 has of the
 @c DER encoding of the certificate under question.  It is to be HEX
 @c encoded.  The rationale for sending the fingerprint is that it allows
 @c @var{fingerprint} is optional and expected to be the SHA-1 has of the
 @c DER encoding of the certificate under question.  It is to be HEX
 @c encoded.  The rationale for sending the fingerprint is that it allows
-@c dirmngr to reply immediatly if it has already cached such a request.  If
+@c dirmngr to reply immediately if it has already cached such a request.  If
 @c this is not the case and no certificate has been found in dirmngr's
 @c internal certificate storage, dirmngr will request the certificate using
 @c the Assuan inquiry
 @c this is not the case and no certificate has been found in dirmngr's
 @c internal certificate storage, dirmngr will request the certificate using
 @c the Assuan inquiry
@@ -899,7 +932,7 @@ as a binary blob.
 @c available for the certificate and the certificate itself is not listed
 @c in this CRL, @code{GPG_ERR_CERT_REVOKED} to indicate that the certificate is
 @c listed in the CRL or @code{GPG_ERR_NO_CRL_KNOWN} in cases where no CRL or no
 @c available for the certificate and the certificate itself is not listed
 @c in this CRL, @code{GPG_ERR_CERT_REVOKED} to indicate that the certificate is
 @c listed in the CRL or @code{GPG_ERR_NO_CRL_KNOWN} in cases where no CRL or no
-@c information is available.  The first two codes are immediatly returned to
+@c information is available.  The first two codes are immediately returned to
 @c the caller and the processing of this request has been done.
 @c
 @c Only the @code{GPG_ERR_NO_CRL_KNOWN} needs more attention: Dirmngr now
 @c the caller and the processing of this request has been done.
 @c
 @c Only the @code{GPG_ERR_NO_CRL_KNOWN} needs more attention: Dirmngr now
@@ -935,7 +968,7 @@ as a binary blob.
 @c     * Try to load a CRL from all configured servers (ldapservers.conf)
 @c       in turn.  The first server returning a CRL is used.
 @c     * @code(crl_cache_insert) is then used to actually insert the CRL
 @c     * Try to load a CRL from all configured servers (ldapservers.conf)
 @c       in turn.  The first server returning a CRL is used.
 @c     * @code(crl_cache_insert) is then used to actually insert the CRL
-@c       into the cache.  If this failed we give up immediatley without
+@c       into the cache.  If this failed we give up immediately without
 @c       checking the rest of the servers from the first step.
 @c * Ready.
 @c
 @c       checking the rest of the servers from the first step.
 @c * Ready.
 @c
@@ -1007,7 +1040,7 @@ as a binary blob.
 @c sure that @code{validate_cert_chain} does not try to lookup the CRL we
 @c are currently processing. This would be a catch-22 and may indicate a
 @c broken PKI.  However, due to overlapping expiring times and imprecise
 @c sure that @code{validate_cert_chain} does not try to lookup the CRL we
 @c are currently processing. This would be a catch-22 and may indicate a
 @c broken PKI.  However, due to overlapping expiring times and imprecise
-@c clocks thsi may actually happen.
+@c clocks this may actually happen.
 @c
 @c For historical reasons the Assuan command ISVALID is a bit different
 @c to CHECKCRL but this is mainly due to different calling conventions.
 @c
 @c For historical reasons the Assuan command ISVALID is a bit different
 @c to CHECKCRL but this is mainly due to different calling conventions.
@@ -1066,8 +1099,8 @@ as a binary blob.
 @c If the issuer's certificate has been found, the signature of the
 @c actual certificate is checked and in case this fails the error
 @c #code{GPG_ERR_BAD_CERT_CHAIN} is returned.  If the signature checks out, the
 @c If the issuer's certificate has been found, the signature of the
 @c actual certificate is checked and in case this fails the error
 @c #code{GPG_ERR_BAD_CERT_CHAIN} is returned.  If the signature checks out, the
-@c maximum cahin length of the issueing certificate is checked as well as
-@c the capiblity of the certificate (i.e. whether he may be used for
+@c maximum chain length of the issuing certificate is checked as well as
+@c the capability of the certificate (i.e. whether he may be used for
 @c certificate signing).  Then the certificate is prepended to our list
 @c representing the certificate chain.  Finally the loop is continued now
 @c with the issuer's certificate as the current certificate.
 @c certificate signing).  Then the certificate is prepended to our list
 @c representing the certificate chain.  Finally the loop is continued now
 @c with the issuer's certificate as the current certificate.