gpg: Split a utility function out of a large function.
[gnupg.git] / doc / dirmngr.texi
index 7b2f92c..06da87e 100644 (file)
@@ -3,6 +3,8 @@
 @c This is part of the GnuPG manual.
 @c For copying conditions, see the file gnupg.texi.
 
+@include defs.inc
+
 @node Invoking DIRMNGR
 @chapter Invoking DIRMNGR
 @cindex DIRMNGR command options
 @end ifset
 
 @mansect description
-Dirmngr is a server for managing and downloading certificate revocation
-lists (CRLs) for X.509 certificates and for downloading the certificates
-themselves. Dirmngr also handles OCSP requests as an alternative to
-CRLs. Dirmngr is either invoked internally by gpgsm or when running as a
-system daemon through the @command{dirmngr-client} tool.
+Since version 2.1 of GnuPG, @command{dirmngr} takes care of accessing
+the OpenPGP keyservers.  As with previous versions it is also used as
+a server for managing and downloading certificate revocation lists
+(CRLs) for X.509 certificates, downloading X.509 certificates, and
+providing access to OCSP providers.  Dirmngr is invoked internally by
+@command{gpg}, @command{gpgsm}, or via the @command{gpg-connect-agent}
+tool.
 
-If @command{dirmngr} is started in system daemon mode, it uses a
-directory layout as common for system daemons and does not make use of
-the default @file{~/.gnupg} directory.
+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
@@ -78,12 +82,13 @@ abbreviate this command.
 @opindex server
 Run in server mode and wait for commands on the @code{stdin}.  The
 default mode is to create a socket and listen for commands there.
+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.
+internal certificate validation code.  This mode is deprecated.
 
 @item --list-crls
 @opindex list-crls
@@ -140,9 +145,8 @@ running mode:
 @table @asis
 
 @item With @code{--daemon} given on the commandline
-the directory named @file{/etc/gnupg} for configuration files,
-@file{/var/lib/gnupg/} for extra data and @file{/var/cache/gnupg}
-for cached CRLs.
+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
 the directory named @file{.gnupg} directly below the home directory
@@ -232,6 +236,33 @@ sufficient.
 Enabling this option forces loading of expired CRLs; this is only
 useful for debugging.
 
+@item --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.
+
+@item --keyserver @code{name}
+@opindex keyserver
+Use @code{name} as your keyserver.  This is the server that @command{gpg}
+communicates with to receive keys, send keys, and search for
+keys.  The format of the @code{name} is a URI:
+`scheme:[//]keyservername[:port]' The scheme is the type of keyserver:
+"hkp" for the HTTP (or compatible) keyservers, "ldap" for the LDAP
+keyservers, or "mailto" for the Graff email keyserver. Note that your
+particular installation of GnuPG may have other keyserver types
+available as well. Keyserver schemes are case-insensitive. After the
+keyserver name, optional keyserver configuration options may be
+provided. These are the same as the global @option{--keyserver-options}
+from below, but apply only to this particular keyserver.
+
+Most keyservers synchronize with each other, so there is generally no
+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.
+
 @item --disable-ldap
 @opindex disable-ldap
 Entirely disables the use of LDAP.
@@ -267,7 +298,7 @@ value to access HTTP servers.
 @item --http-proxy @var{host}[:@var{port}]
 @opindex http-proxy
 Use @var{host} and @var{port} to access HTTP servers.  The use of this
-options overrides the environment variable @env{http_proxy} regardless
+option overrides the environment variable @env{http_proxy} regardless
 whether @option{--honor-http-proxy} has been set.
 
 
@@ -404,7 +435,7 @@ Use the root certificates in @var{file} for verification of the TLS
 certificates used with @code{hkps} (keyserver access over TLS).  If
 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.
+root certificates.  Tilde expansion is supported.
 
 @end table
 
@@ -420,51 +451,63 @@ Dirmngr makes use of several directories when running in daemon mode:
 
 @table @file
 
-@item /etc/gnupg
-This is where all the configuration files are expected by default.
+@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.
 
 @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.  Usually
-these are the same certificates you use with the applications making
-use of dirmngr.  It is expected that each of these certificate files
-contain exactly one @acronym{DER} encoded certificate in a file with
-the suffix @file{.crt} or @file{.der}.  @command{dirmngr} reads those
-certificates on startup and when given a SIGHUP.  Certificates which
-are not readable or do not make up a proper X.509 certificate are
-ignored; see the log file for details.
+This directory should be filled with certificates of Root CAs you
+are trusting in checking the CRLs and signing OCSP Reponses.
+
+Usually these are the same certificates you use with the applications
+making use of dirmngr.  It is expected that each of these certificate
+files contain exactly one @acronym{DER} encoded certificate in a file
+with the suffix @file{.crt} or @file{.der}.  @command{dirmngr} reads
+those certificates on startup and when given a SIGHUP.  Certificates
+which are not readable or do not make up a proper X.509 certificate
+are ignored; see the log file for details.
+
+Applications using dirmngr (e.g. gpgsm) can request these
+certificates to complete a trust chain in the same way as with the
+extra-certs directory (see below).
 
 Note that for OCSP responses the certificate specified using the option
 @option{--ocsp-signer} is always considered valid to sign OCSP requests.
 
-
-@item /var/lib/gnupg/extra-certs
-This directory may contain extra certificates which are preloaded into
-the interal cache on startup.  This is convenient in cases you have a
-couple intermediate CA certificates or certificates ususally used to
-sign OCSP reponses.  These certificates are first tried before going out
-to the net to look for them.  These certificates must also be
+@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)
+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.
+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 /var/run/gnupg
-This directory keeps the socket file for accsing @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 /var/cache/gnupg/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.
+@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}
+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.
 
 @end table
 @manpause
 
 To be able to see what's going on you should create the configure file
-@file{/etc/dirmngr/dirmngr.conf} with at least one line:
+@file{~/gnupg/dirmngr.conf} with at least one line:
 
 @example
-log-file /var/log/gnupg/dirmngr.log
+log-file ~/dirmngr.log
 @end example
 
 To be able to perform OCSP requests you probably want to add the line:
@@ -473,14 +516,16 @@ To be able to perform OCSP requests you probably want to add the line:
 allow-ocsp
 @end example
 
-Now you may start dirmngr as a system daemon using:
+To make sure that new options are read and that after the installation
+of a new GnuPG versions the installed dirmngr is running, you may want
+to kill an existing dirmngr first:
 
 @example
-dirmngr --daemon
+gpgconf --kill dirmngr
 @end example
 
-Please ignore the output; it is not needed anymore.  Check the log file
-to see whether all trusted root certificates have been loaded correctly.
+You may check the log file to see whether all desired root
+certificates have been loaded correctly.
 
 
 @c
@@ -501,13 +546,21 @@ Here is a list of supported signals:
 @cpindex SIGHUP
 This signals 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.
+startup.  Options are re-read from the configuration file.  Instead of
+sending this signal it is better to use
+@example
+gpgconf --reload dirmngr
+@end example
 
 @item SIGTERM
 @cpindex SIGTERM
 Shuts down the process but waits until all current requests are
 fulfilled.  If the process has received 3 of these signals and requests
-are still pending, a shutdown is forced.
+are still pending, a shutdown is forced.  You may also use
+@example
+gpgconf --kill dirmngr
+@end example
+instead of this signal
 
 @item SIGINT
 @cpindex SIGINT
@@ -529,25 +582,25 @@ This prints some caching statistics to the log file.
 @node Dirmngr Examples
 @section Examples
 
-
-Dirmngr is supposed to be used as a system wide daemon, it should be
-started like:
+Here is an example on how to show dirmngr's internal table of OpenPGP
+keyserver addresses.  The output is intended for debugging purposes
+and not part of a defined API.
 
 @example
-  dirmngr --daemon
+  gpg-connect-agent --dirmngr 'keyserver --hosttable' /bye
 @end example
 
-This will force it to go into the backround, read the default
-certificates (including the trusted root certificates) and listen on a
-socket for client requests.  It does also print information about the
-socket used but they are only for compatibilty reasons with old GnuPG
-versions and may be ignored.
+To inhibit the use of a particular host you have noticed in one of the
+keyserver pools, you may use
+
+@example
+ gpg-connect-agent --dirmngr 'keyserver --dead pgpkeys.bnd.de' /bye
+@end example
 
-For debugging purposes it is also possible to start Dirmngr in the
-foreground:
+The description of the @code{keyserver} command can be printed using
 
 @example
-  dirmngr --server -v
+ gpg-connect-agent --dirmngr 'help keyserver' /bye
 @end example
 
 
@@ -949,7 +1002,7 @@ as a binary blob.
 @c
 @c Here we may encounter a recursive situation:
 @c @code{validate_cert_chain} needs to look at other certificates and
-@c also at CRLs to check whether tehse other certificates and well, the
+@c also at CRLs to check whether these other certificates and well, the
 @c CRL issuer certificate itself are not revoked.  FIXME: We need to make
 @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