gpg: New option --quick-set-expire.
[gnupg.git] / doc / dirmngr.texi
index 6a4d6d6..62a41b6 100644 (file)
@@ -34,11 +34,6 @@ providing access to OCSP providers.  Dirmngr is invoked internally by
 @command{gpg}, @command{gpgsm}, or via the @command{gpg-connect-agent}
 tool.
 
-For historical reasons it is also possible to start @command{dirmngr}
-in a system daemon mode which uses a different directory layout.
-However, this mode is deprecated and may eventually be removed.
-
-
 @manpause
 @noindent
 @xref{Option Index},for an index to @command{DIRMNGR}'s commands and
@@ -71,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
@@ -87,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
@@ -107,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.
 
@@ -139,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
-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
@@ -168,7 +161,8 @@ verbose commands to @sc{dirmngr}, such as @option{-vv}.
 @item --log-file @var{file}
 @opindex log-file
 Append all logging output to @var{file}.  This is very helpful in
-seeing what the agent actually does.
+seeing what the agent actually does.  Use @file{socket://} to log to
+socket.
 
 @item --debug-level @var{level}
 @opindex debug-level
@@ -200,7 +194,7 @@ 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
+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.
 
@@ -218,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.
 
+@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
@@ -227,7 +227,7 @@ debugger.
 @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.
 
@@ -244,6 +244,22 @@ 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.
 
+@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 --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}
@@ -263,6 +279,13 @@ need to send keys to more than one server. The keyserver
 @code{hkp://keys.gnupg.net} uses round robin DNS to give a different
 keyserver each time you use it.
 
+If exactly two keyservers are configured and only one is a Tor hidden
+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
@@ -307,6 +330,7 @@ value to access HTTP servers.
 
 @item --http-proxy @var{host}[:@var{port}]
 @opindex http-proxy
+@efindex http_proxy
 Use @var{host} and @var{port} to access HTTP servers.  The use of this
 option overrides the environment variable @env{http_proxy} regardless
 whether @option{--honor-http-proxy} has been set.
@@ -315,9 +339,9 @@ whether @option{--honor-http-proxy} has been set.
 @item --ldap-proxy @var{host}[:@var{port}]
 @opindex ldap-proxy
 Use @var{host} and @var{port} to connect to LDAP servers.  If @var{port}
-is ommitted, port 389 (standard LDAP port) is used.  This overrides any
+is omitted, port 389 (standard LDAP port) is used.  This overrides any
 specified host and port part in a LDAP URL and will also be used if host
-and port have been ommitted from the URL.
+and port have been omitted from the URL.
 
 @item --only-ldap-proxy
 @opindex only-ldap-proxy
@@ -330,8 +354,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
 
@@ -340,12 +363,12 @@ This server list file contains one LDAP server per line in the format
 Lines starting with a  @samp{#} are comments.
 
 Note that as usual all strings entered are expected to be UTF-8 encoded.
-Obviously this will lead to problems if the password has orginally been
+Obviously this will lead to problems if the password has originally been
 encoded as Latin-1.  There is no other solution here than to put such a
 password in the binary encoding into the file (i.e. non-ascii characters
 won't show up readable).@footnote{The @command{gpgconf} tool might be
-helpful for frontends as it allows to edit this configuration file using
-percent escaped strings.}
+helpful for frontends as it enables editing this configuration file using
+percent-escaped strings.}
 
 
 @item --ldaptimeout @var{secs}
@@ -356,11 +379,11 @@ out. The default is currently 100 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
@@ -389,8 +412,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
@@ -411,7 +434,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
@@ -447,6 +470,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
 
 
@@ -462,13 +490,11 @@ Dirmngr makes use of several directories when running in daemon mode:
 @table @file
 
 @item ~/.gnupg
-@itemx /etc/gnupg
-The first is the standard home directory for all configuration files.
-In the deprecated system daemon mode the second directory is used instead.
+This is the standard home directory for all configuration files.
 
 @item /etc/gnupg/trusted-certs
 This directory should be filled with certificates of Root CAs you
-are trusting in checking the CRLs and signing OCSP Reponses.
+are trusting in checking the CRLs and signing OCSP Responses.
 
 Usually these are the same certificates you use with the applications
 making use of dirmngr.  It is expected that each of these certificate
@@ -487,28 +513,18 @@ 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 reponses.
+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}.
 
-@item @value{LOCALRUNDIR}
-This directory is only used in the deprecated system daemon mode.  It
-keeps the socket file for accessing @command{dirmngr} services.  The
-name of the socket file will be @file{S.dirmngr}.  Make sure that this
-directory has the proper permissions to let @command{dirmngr} create
-the socket file and that eligible users may read and write to that
-socket.
-
 @item ~/.gnupg/crls.d
-@itemx @value{LOCALCACHEDIR}/crls.d
-The first directory is used to store cached CRLs.  The @file{crls.d}
+This directory is used to store cached CRLs.  The @file{crls.d}
 part will be created by dirmngr if it does not exists but you need to
-make sure that the upper directory exists.  The second directory is
-used instead in the deprecated systems daemon mode.
+make sure that the upper directory exists.
 
 @end table
 @manpause
@@ -543,7 +559,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.
@@ -554,7 +570,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
@@ -751,7 +767,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
@@ -760,7 +776,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
@@ -788,7 +804,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:
@@ -820,7 +836,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
 
@@ -835,7 +851,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
@@ -887,7 +903,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
@@ -909,7 +925,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
@@ -945,7 +961,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
@@ -1017,7 +1033,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.
@@ -1034,10 +1050,6 @@ as a binary blob.
 @c works. Note that mainly testing purposes this functionality may be
 @c called directly using @cmd{dirmngr-client --validate @file{foo.crt}}.
 @c
-@c For backward compatibility this function returns success if Dirmngr is
-@c not used as a system daemon.  Thus not validating the certicates at
-@c all. FIXME:  This is definitely not correct and should be fixed ASAP.
-@c
 @c The function takes the target certificate and a mode argument as
 @c parameters and returns an error code and optionally the closes
 @c expiration time of all certificates in the chain.
@@ -1080,8 +1092,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.