doc: Add a hint about gpgsm and DECRYPTION_INFO.
[gnupg.git] / doc / dirmngr.texi
index d442103..76be528 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.
-Not that you cannot abbreviate this command.
+Note that you cannot abbreviate this command.
 
 @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.
-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
@@ -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
-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.
 
@@ -123,6 +131,10 @@ will thus trigger reading of fresh CRLs.
 @node Dirmngr Options
 @section Option Summary
 
+Note that all long options with the exception of @option{--options}
+and @option{--homedir} may also be given in the configuration file
+after stripping off the two leading dashes.
+
 @table @gnupgtabopt
 
 @item --options @var{file}
@@ -134,21 +146,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
-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
-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.
-@end table
 
 
 @item -v
@@ -196,17 +198,20 @@ however carefully selected to best aid in debugging.
 
 @item --debug @var{flags}
 @opindex debug
-This option is only useful for debugging and the behaviour may change at
-any time without notice.  FLAGS are bit encoded and may be given in
-usual C-Syntax.
+Set debugging flags.  This option is only useful for debugging and its
+behavior may change with a new release.  All flags are or-ed and may
+be given in C syntax (e.g. 0x0042) or as a comma separated list of
+flag names.  To get a list of all supported flags the single word
+"help" can be used.
 
 @item --debug-all
 @opindex debug-all
 Same as @code{--debug=0xffffffff}
 
-@item --gnutls-debug @var{level}
-@opindex gnutls-debug
-Enable debugging of GNUTLS at @var{level}.
+@item --tls-debug @var{level}
+@opindex tls-debug
+Enable debugging of the TLS layer at @var{level}.  The details of the
+debug level depend on the used TLS library and are not set in stone.
 
 @item --debug-wait @var{n}
 @opindex debug-wait
@@ -229,7 +234,7 @@ self-test for debugging purposes.
 @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.
 
@@ -239,12 +244,63 @@ Enabling this option forces loading of expired CRLs; this is only
 useful for debugging.
 
 @item --use-tor
+@itemx --no-use-tor
 @opindex use-tor
-This option switches Dirmngr and thus GnuPG into ``Tor mode'' to route
-all network access via Tor (an anonymity network).  WARNING: As of now
-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.
+@opindex no-use-tor
+The option @option{--use-tor} switches Dirmngr and thus GnuPG into
+``Tor mode'' to route all network access via Tor (an anonymity
+network).  Certain other features are disabled in this mode.  The
+effect of @option{--use-tor} cannot be overridden by any other command
+or even be reloading gpg-agent.  The use of @option{--no-use-tor}
+disables the use of Tor.  The default is to use Tor if it is available
+on startup or after reloading dirmngr.
+
+@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}
+@opindex resolver-timeout
+Set the timeout for the DNS resolver to N seconds.  The default are 30
+seconds.
+
+@item --connect-timeout @var{n}
+@item --connect-quick-timeout @var{n}
+@opindex connect-timeout
+@opindex connect-quick-timeout
+Set the timeout for HTTP and generic TCP connection attempts to N
+seconds.  The value set with the quick variant is used when the
+--quick option has been given to certain Assuan commands.  The quick
+value is capped at the value of the regular connect timeout.  The
+default values are 15 and 2 seconds.  Note that the timeout values are
+for each connection attempt; the connection code will attempt to
+connect all addresses listed for a server.
+
+@item --listen-backlog @var{n}
+@opindex listen-backlog
+Set the size of the queue for pending connections.  The default is 64.
+
+@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
+the list is retrieved in case 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.  Note, that regardless of this option a version check can
+always be triggered using this command:
+
+@example
+       gpg-connect-agent --dirmngr 'loadswdb --force' /bye
+@end example
+
 
 @item --keyserver @var{name}
 @opindex keyserver
@@ -270,6 +326,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.
 
+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
@@ -277,8 +335,13 @@ 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
-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-ipv4
+@item --disable-ipv6
+@opindex disable-ipv4
+@opindex disable-ipv6
+Disable the use of all IPv4 or IPv6 addresses.
 
 @item --disable-ldap
 @opindex disable-ldap
@@ -338,8 +401,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
-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
 
@@ -359,16 +421,16 @@ percent-escaped strings.}
 @item --ldaptimeout @var{secs}
 @opindex ldaptimeout
 Specify the number of seconds to wait for an LDAP query before timing
-out. The default is currently 100 seconds.  0 will never timeout.
+out.  The default are 15 seconds.  0 will never timeout.
 
 
 @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.
 
-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
@@ -397,8 +459,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
-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
@@ -419,7 +481,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
-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
@@ -455,6 +517,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.
 
+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
 
 
@@ -466,11 +533,20 @@ root certificates.  Tilde expansion is supported.
 @section Configuration
 
 Dirmngr makes use of several directories when running in daemon mode:
+There are a few configuration files whih control the operation of
+dirmngr.  By default they may all be found in the current home
+directory (@pxref{option --homedir}).
 
 @table @file
 
-@item ~/.gnupg
-This is the standard home directory for all configuration files.
+@item dirmngr.conf
+@efindex dirmngr.conf
+This is the standard configuration file read by @command{dirmngr} on
+startup.  It may contain any valid long option; the leading two dashes
+may not be entered and the option may not be abbreviated.  This file
+is also read after a @code{SIGHUP} however not all options will
+actually have an effect.  This default name may be changed on the
+command line (@pxref{option --options}).  You should backup this file.
 
 @item /etc/gnupg/trusted-certs
 This directory should be filled with certificates of Root CAs you
@@ -493,10 +569,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
-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
-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}.
@@ -539,7 +615,7 @@ certificates have been loaded correctly.
 @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.
@@ -550,7 +626,7 @@ Here is a list of supported signals:
 
 @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
@@ -724,7 +800,7 @@ configuration.
 @end table
 
 If DirMngr has not enough information about the given certificate (which
-is the case for not yet cached certificates), it will will inquire the
+is the case for not yet cached certificates), it will inquire the
 missing data:
 
 @example
@@ -747,7 +823,7 @@ this the root certificate:
   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
@@ -756,7 +832,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
-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
@@ -784,7 +860,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
-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:
@@ -816,7 +892,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
-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
 
@@ -831,7 +907,7 @@ as a binary blob.
 
 @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
@@ -883,7 +959,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 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
@@ -905,7 +981,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 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
@@ -941,7 +1017,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       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
@@ -987,7 +1063,7 @@ as a binary blob.
 @c  c) No authorityKeyIdentifier exits: The certificate is retrieved
 @c     using @code{find_cert_bysubject} without the key ID argument.  If
 @c     the certificate is in the certificate cache the first one with a
-@c     matching subject is is directly returned.  Then the requester is
+@c     matching subject is directly returned.  Then the requester is
 @c     asked via the Assuan inquiry ``SENDCERT'' and an exact
 @c     specification of the subject whether he can
 @c     provide this certificate.  If this succeed the returned
@@ -1013,7 +1089,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 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.
@@ -1064,7 +1140,7 @@ as a binary blob.
 @c respectively. The have already been described above under the
 @c description of @code{crl_cache_insert}.  If no certificate was found
 @c or with no authorityKeyIdentifier, only the cache is consulted using
-@c @code{get_cert_bysubject}.  The latter is is done under the assumption
+@c @code{get_cert_bysubject}.  The latter is done under the assumption
 @c that a matching certificate has explicitly been put into the
 @c certificate cache.  If the issuer's certificate could not be found,
 @c the validation terminates with the error code @code{GPG_ERR_MISSING_CERT}.
@@ -1072,8 +1148,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 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.
@@ -1089,7 +1165,7 @@ as a binary blob.
 @c recursive process because a CRL has to be checked for each certificate
 @c in the chain except for the root certificate, of which we already know
 @c that it is trusted and we avoid checking a CRL here due to common
-@c setup problems and the assumption that a revoked root certifcate has
+@c setup problems and the assumption that a revoked root certificate has
 @c been removed from the list of trusted certificates.
 @c
 @c