summaryrefslogtreecommitdiffstats
path: root/doc/dirmngr.texi
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/dirmngr.texi1200
1 files changed, 1200 insertions, 0 deletions
diff --git a/doc/dirmngr.texi b/doc/dirmngr.texi
new file mode 100644
index 0000000..843fdbf
--- /dev/null
+++ b/doc/dirmngr.texi
@@ -0,0 +1,1200 @@
+@c Copyright (C) 2002 Klar"alvdalens Datakonsult AB
+@c Copyright (C) 2004, 2005, 2006, 2007 g10 Code GmbH
+@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
+@cindex command options
+@cindex options, DIRMNGR command
+
+@manpage dirmngr.8
+@ifset manverb
+.B dirmngr
+\- CRL and OCSP daemon
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B dirmngr
+.RI [ options ]
+.I command
+.RI [ args ]
+@end ifset
+
+@mansect description
+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.
+
+@manpause
+@noindent
+@xref{Option Index},for an index to @command{DIRMNGR}'s commands and
+options.
+@mancont
+
+@menu
+* Dirmngr Commands:: List of all commands.
+* Dirmngr Options:: List of all options.
+* Dirmngr Configuration:: Configuration files.
+* Dirmngr Signals:: Use of signals.
+* Dirmngr Examples:: Some usage examples.
+* Dirmngr Protocol:: The protocol dirmngr uses.
+@end menu
+
+
+@node Dirmngr Commands
+@section Commands
+@mansect commands
+
+Commands are not distinguished from options except for the fact that
+only one command is allowed.
+
+@table @gnupgtabopt
+@item --version
+@opindex version
+Print the program version and licensing information. Note that you cannot
+abbreviate this command.
+
+@item --help, -h
+@opindex help
+Print a usage message summarizing the most useful command-line options.
+Note that you cannot abbreviate this command.
+
+@item --dump-options
+@opindex dump-options
+Print a list of all available options and commands. Note that you cannot
+abbreviate this command.
+
+@item --server
+@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.
+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
+List the contents of the CRL cache on @code{stdout}. This is probably
+only useful for debugging purposes.
+
+@item --load-crl @var{file}
+@opindex load-crl
+This command requires a filename as additional argument, and it will
+make Dirmngr try to import the CRL in @var{file} into it's cache.
+Note, that this is only possible if Dirmngr is able to retrieve the
+CA's certificate directly by its own means. In general it is better
+to use @code{gpgsm}'s @code{--call-dirmngr loadcrl filename} command
+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 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.
+
+@item --shutdown
+@opindex shutdown
+This commands shuts down an running instance of Dirmngr. This command
+has currently no effect.
+
+@item --flush
+@opindex flush
+This command removes all CRLs from Dirmngr's cache. Client requests
+will thus trigger reading of fresh CRLs.
+
+@end table
+
+
+@mansect options
+@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}
+@opindex options
+Reads configuration from @var{file} instead of from the default
+per-user configuration file. The default configuration file is named
+@file{dirmngr.conf} and expected in the home directory.
+
+@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 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. Many kinds of data are stored within
+this directory.
+
+
+@item -v
+@item --verbose
+@opindex v
+@opindex verbose
+Outputs additional information while running.
+You can increase the verbosity by giving several
+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. Use @file{socket://} to log to
+socket.
+
+@item --debug-level @var{level}
+@opindex debug-level
+Select the debug level for investigating problems. @var{level} may be a
+numeric value or by a keyword:
+
+@table @code
+@item none
+No debugging at all. A value of less than 1 may be used instead of
+the keyword.
+@item basic
+Some basic debug messages. A value between 1 and 2 may be used
+instead of the keyword.
+@item advanced
+More verbose debug messages. A value between 3 and 5 may be used
+instead of the keyword.
+@item expert
+Even more detailed messages. A value between 6 and 8 may be used
+instead of the keyword.
+@item guru
+All of the debug messages you can get. A value greater than 8 may be
+used instead of the keyword. The creation of hash tracing files is
+only enabled if the keyword is used.
+@end table
+
+How these messages are mapped to the actual debugging flags is not
+specified and may change with newer releases of this program. They are
+however carefully selected to best aid in debugging.
+
+@item --debug @var{flags}
+@opindex debug
+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 --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
+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
+@itemx --csh
+@opindex s
+@opindex sh
+@opindex c
+@opindex csh
+Format the info output in daemon mode for use with the standard Bourne
+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.
+
+@item --force
+@opindex force
+Enabling this option forces loading of expired CRLs; this is only
+useful for debugging.
+
+@item --use-tor
+@itemx --no-use-tor
+@opindex use-tor
+@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 by reloading dirmngr. 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 option is used. Using this together with enabled
+Tor mode returns the error ``Not Enabled''.
+
+@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
+Use @var{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 @var{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 @option{--keyserver-options} of
+@command{gpg}, 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.
+
+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 @code{hkps://hkps.pool.sks-keyservers.net}.
+
+Windows users with a keyserver running on their Active Directory
+should use @code{ldap:///} for @var{name} to access this directory.
+
+For accessing anonymous LDAP keyservers @var{name} is in general just
+a @code{ldaps://ldap.example.com}. A BaseDN parameter should never be
+specified. If authentication is required the value of @var{name} is
+for example:
+
+@example
+ keyserver ldaps://ldap.example.com/????bindname=uid=USERNAME
+ %2Cou=GnuPG%20Users%2Cdc=example%2Cdc=com,password=PASSWORD
+@end example
+
+ Put this all on one line without any spaces and keep the '%2C' as given.
+ Replace USERNAME, PASSWORD, and the 'dc' parts according to the
+ instructions received from the LDAP administrator. Note that only
+ simple authentication (i.e. cleartext passwords) is supported and thus
+ using ldaps is strongly suggested.
+
+@item --nameserver @var{ipaddr}
+@opindex nameserver
+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}.
+
+@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
+Entirely disables the use of LDAP.
+
+@item --disable-http
+@opindex disable-http
+Entirely disables the use of HTTP.
+
+@item --ignore-http-dp
+@opindex ignore-http-dp
+When looking for the location of a CRL, the to be tested certificate
+usually contains so called @dfn{CRL Distribution Point} (DP) entries
+which are URLs describing the way to access the CRL. The first found DP
+entry is used. With this option all entries using the @acronym{HTTP}
+scheme are ignored when looking for a suitable DP.
+
+@item --ignore-ldap-dp
+@opindex ignore-ldap-dp
+This is similar to @option{--ignore-http-dp} but ignores entries using
+the @acronym{LDAP} scheme. Both options may be combined resulting in
+ignoring DPs entirely.
+
+@item --ignore-ocsp-service-url
+@opindex ignore-ocsp-service-url
+Ignore all OCSP URLs contained in the certificate. The effect is to
+force the use of the default responder.
+
+@item --honor-http-proxy
+@opindex honor-http-proxy
+If the environment variable @env{http_proxy} has been set, use its
+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.
+
+
+@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 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 omitted from the URL.
+
+@item --only-ldap-proxy
+@opindex only-ldap-proxy
+Never use anything else but the LDAP "proxy" as configured with
+@option{--ldap-proxy}. Usually @command{dirmngr} tries to use other
+configured LDAP server if the connection using the "proxy" failed.
+
+
+@item --ldapserverlist-file @var{file}
+@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}.
+
+This server list file contains one LDAP server per line in the format
+
+@sc{hostname:port:username:password:base_dn}
+
+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 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 enables editing this configuration file using
+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 are 15 seconds. 0 will never timeout.
+
+
+@item --add-servers
+@opindex add-servers
+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 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
+to sign the CRL is located on the same server. So if dirmngr doesn't add
+that new server to list, it will often not be able to verify the
+signature of the CRL unless the @code{--add-servers} option is used.
+
+Note: The current version of dirmngr has this option disabled by default.
+
+
+@item --allow-ocsp
+@opindex allow-ocsp
+This option enables OCSP support if requested by the client.
+
+OCSP requests are rejected by default because they may violate the
+privacy of the user; for example it is possible to track the time when
+a user is reading a mail.
+
+
+@item --ocsp-responder @var{url}
+@opindex ocsp-responder
+Use @var{url} as the default OCSP Responder if the certificate does
+not contain information about an assigned responder. Note, that
+@code{--ocsp-signer} must also be set to a valid certificate.
+
+@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. 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
+content of @env{HOME}, no slash at start describes a relative filename
+which will be searched at the home directory. To make sure that the
+@var{file} is searched in the home directory, either prepend the name
+with "./" or use a name which contains a dot.
+
+If a response has been signed by a certificate described by these
+fingerprints no further check upon the validity of this certificate is
+done.
+
+The format of the @var{FILE} is a list of SHA-1 fingerprint, one per
+line with optional colons between the bytes. Empty lines and lines
+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 (10 minutes).
+
+@item --ocsp-max-period @var{n}
+@opindex ocsp-max-period
+Seconds a response is at maximum considered valid after the time given
+in the thisUpdate field. Default is 7776000 (90 days).
+
+@item --ocsp-current-period @var{n}
+@opindex ocsp-current-period
+The number of seconds an OCSP response is considered valid after the
+time given in the NEXT_UPDATE datum. Default is 10800 (3 hours).
+
+
+@item --max-replies @var{n}
+@opindex max-replies
+Do not return more that @var{n} items in one query. The default is
+10.
+
+@item --ignore-cert-extension @var{oid}
+@opindex ignore-cert-extension
+Add @var{oid} to the list of ignored certificate extensions. The
+@var{oid} is expected to be in dotted decimal form, like
+@code{2.5.29.3}. This option may be used more than once. Critical
+flagged certificate extensions matching one of the OIDs in the list
+are treated as if they are actually handled and thus the certificate
+won't be rejected due to an unknown critical extension. Use this
+option with care because extensions are usually flagged as critical
+for a reason.
+
+@item --hkp-cacert @var{file}
+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. 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
+
+
+@c
+@c Dirmngr Configuration
+@c
+@mansect files
+@node Dirmngr Configuration
+@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 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
+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
+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 /etc/gnupg/extra-certs
+This directory may contain extra certificates which are preloaded
+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 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 ~/.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.
+
+@end table
+@manpause
+
+To be able to see what's going on you should create the configure file
+@file{~/gnupg/dirmngr.conf} with at least one line:
+
+@example
+log-file ~/dirmngr.log
+@end example
+
+To be able to perform OCSP requests you probably want to add the line:
+
+@example
+allow-ocsp
+@end example
+
+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
+gpgconf --kill dirmngr
+@end example
+
+You may check the log file to see whether all desired root
+certificates have been loaded correctly.
+
+
+@c
+@c Dirmngr Signals
+@c
+@mansect signals
+@node Dirmngr 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.
+
+Here is a list of supported signals:
+
+@table @gnupgtabopt
+
+@item SIGHUP
+@cpindex SIGHUP
+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
+@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. You may also use
+@example
+gpgconf --kill dirmngr
+@end example
+instead of this signal
+
+@item SIGINT
+@cpindex SIGINT
+Shuts down the process immediately.
+
+
+@item SIGUSR1
+@cpindex SIGUSR1
+This prints some caching statistics to the log file.
+
+@end table
+
+
+
+@c
+@c Examples
+@c
+@mansect examples
+@node Dirmngr Examples
+@section Examples
+
+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
+ gpg-connect-agent --dirmngr 'keyserver --hosttable' /bye
+@end example
+
+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
+
+The description of the @code{keyserver} command can be printed using
+
+@example
+ gpg-connect-agent --dirmngr 'help keyserver' /bye
+@end example
+
+
+
+@c
+@c Assuan Protocol
+@c
+@manpause
+@node Dirmngr Protocol
+@section Dirmngr's Assuan Protocol
+
+Assuan is the IPC protocol used to access dirmngr. This is a
+description of the commands implemented by dirmngr.
+
+@menu
+* Dirmngr LOOKUP:: Look up a certificate via LDAP
+* Dirmngr ISVALID:: Validate a certificate using a CRL or OCSP.
+* Dirmngr CHECKCRL:: Validate a certificate using a CRL.
+* Dirmngr CHECKOCSP:: Validate a certificate using OCSP.
+* Dirmngr CACHECERT:: Put a certificate into the internal cache.
+* Dirmngr VALIDATE:: Validate a certificate for debugging.
+@end menu
+
+@node Dirmngr LOOKUP
+@subsection Return the certificate(s) found
+
+Lookup certificate. To allow multiple patterns (which are ORed)
+quoting is required: Spaces are to be translated into "+" or into
+"%20"; obviously this requires that the usual escape quoting rules
+are applied. The server responds with:
+
+@example
+ S: D <DER encoded certificate>
+ S: END
+ S: D <second DER encoded certificate>
+ S: END
+ S: OK
+@end example
+
+In this example 2 certificates are returned. The server may return
+any number of certificates; OK will also be returned when no
+certificates were found. The dirmngr might return a status line
+
+@example
+ S: S TRUNCATED <n>
+@end example
+
+
+To indicate that the output was truncated to N items due to a
+limitation of the server or by an arbitrary set limit.
+
+The option @option{--url} may be used if instead of a search pattern a
+complete URL to the certificate is known:
+
+@example
+ C: LOOKUP --url CN%3DWerner%20Koch,o%3DIntevation%20GmbH,c%3DDE?userCertificate
+@end example
+
+If the option @option{--cache-only} is given, no external lookup is done
+so that only certificates from the cache are returned.
+
+With the option @option{--single}, the first and only the first match
+will be returned. Unless option @option{--cache-only} is also used, no
+local lookup will be done in this case.
+
+
+
+@node Dirmngr ISVALID
+@subsection Validate a certificate using a CRL or OCSP
+
+@example
+ ISVALID [--only-ocsp] [--force-default-responder] @var{certid}|@var{certfpr}
+@end example
+
+Check whether the certificate described by the @var{certid} has been
+revoked. Due to caching, the Dirmngr is able to answer immediately in
+most cases.
+
+The @var{certid} is a hex encoded string consisting of two parts,
+delimited by a single dot. The first part is the SHA-1 hash of the
+issuer name and the second part the serial number.
+
+Alternatively the certificate's SHA-1 fingerprint @var{certfpr} may be
+given in which case an OCSP request is done before consulting the CRL.
+If the option @option{--only-ocsp} is given, no fallback to a CRL check
+will be used. If the option @option{--force-default-responder} is
+given, only the default OCSP responder will be used and any other
+methods of obtaining an OCSP responder URL won't be used.
+
+@noindent
+Common return values are:
+
+@table @code
+@item GPG_ERR_NO_ERROR (0)
+This is the positive answer: The certificate is not revoked and we have
+an up-to-date revocation list for that certificate. If OCSP was used
+the responder confirmed that the certificate has not been revoked.
+
+@item GPG_ERR_CERT_REVOKED
+This is the negative answer: The certificate has been revoked. Either
+it is in a CRL and that list is up to date or an OCSP responder informed
+us that it has been revoked.
+
+@item GPG_ERR_NO_CRL_KNOWN
+No CRL is known for this certificate or the CRL is not valid or out of
+date.
+
+@item GPG_ERR_NO_DATA
+The OCSP responder returned an ``unknown'' status. This means that it
+is not aware of the certificate's status.
+
+@item GPG_ERR_NOT_SUPPORTED
+This is commonly seen if OCSP support has not been enabled in the
+configuration.
+@end table
+
+If DirMngr has not enough information about the given certificate (which
+is the case for not yet cached certificates), it will inquire the
+missing data:
+
+@example
+ S: INQUIRE SENDCERT <CertID>
+ C: D <DER encoded certificate>
+ C: END
+@end example
+
+A client should be aware that DirMngr may ask for more than one
+certificate.
+
+If Dirmngr has a certificate but the signature of the certificate
+could not been validated because the root certificate is not known to
+dirmngr as trusted, it may ask back to see whether the client trusts
+this the root certificate:
+
+@example
+ S: INQUIRE ISTRUSTED <CertHexfpr>
+ C: D 1
+ C: END
+@end example
+
+Only this answer will let Dirmngr consider the certificate as valid.
+
+
+@node Dirmngr CHECKCRL
+@subsection Validate a certificate using a CRL
+
+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 known, the function inquires the
+certificate using:
+
+@example
+ S: INQUIRE TARGETCERT
+ C: D <DER encoded certificate>
+ C: END
+@end example
+
+Thus the caller is expected to return the certificate for the request
+(which should match FINGERPRINT) as a binary blob. Processing then
+takes place without further interaction; in particular dirmngr tries
+to locate other required certificate by its own mechanism which
+includes a local certificate store as well as a list of trusted root
+certificates.
+
+@noindent
+The return code is 0 for success; i.e. the certificate has not been
+revoked or one of the usual error codes from libgpg-error.
+
+@node Dirmngr CHECKOCSP
+@subsection Validate a certificate using OCSP
+
+@example
+ CHECKOCSP [--force-default-responder] [@var{fingerprint}]
+@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 appropriate
+OCSP responder. If the fingerprint has not been given or the
+certificate is not known by Dirmngr, the function inquires the
+certificate using:
+
+@example
+ S: INQUIRE TARGETCERT
+ C: D <DER encoded certificate>
+ C: END
+@end example
+
+Thus the caller is expected to return the certificate for the request
+(which should match @var{fingerprint}) as a binary blob. Processing
+then takes place without further interaction; in particular dirmngr
+tries to locate other required certificates by its own mechanism which
+includes a local certificate store as well as a list of trusted root
+certificates.
+
+If the option @option{--force-default-responder} is given, only the
+default OCSP responder is used. This option is the per-command variant
+of the global option @option{--ignore-ocsp-service-url}.
+
+
+@noindent
+The return code is 0 for success; i.e. the certificate has not been
+revoked or one of the usual error codes from libgpg-error.
+
+@node Dirmngr CACHECERT
+@subsection Put a certificate into the internal cache
+
+Put a certificate into the internal cache. This command might be
+useful if a client knows in advance certificates required for a test and
+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
+
+@example
+ S: INQUIRE TARGETCERT
+ C: D <DER encoded certificate>
+ C: END
+@end example
+
+Thus the caller is expected to return the certificate for the request
+as a binary blob.
+
+@noindent
+The return code is 0 for success; i.e. the certificate has not been
+successfully cached or one of the usual error codes from libgpg-error.
+
+@node Dirmngr VALIDATE
+@subsection Validate a certificate for debugging
+
+Validate a certificate using the certificate validation function used
+internally by dirmngr. This command is only useful for debugging. To
+get the actual certificate, this command immediately inquires it using
+
+@example
+ S: INQUIRE TARGETCERT
+ C: D <DER encoded certificate>
+ C: END
+@end example
+
+Thus the caller is expected to return the certificate for the request
+as a binary blob.
+
+
+@mansect see also
+@ifset isman
+@command{gpgsm}(1),
+@command{dirmngr-client}(1)
+@end ifset
+@include see-also-note.texi
+
+@c
+@c !!! UNDER CONSTRUCTION !!!
+@c
+@c
+@c @section Verifying a Certificate
+@c
+@c There are several ways to request services from Dirmngr. Almost all of
+@c them are done using the Assuan protocol. What we describe here is the
+@c Assuan command CHECKCRL as used for example by the dirmnr-client tool if
+@c invoked as
+@c
+@c @example
+@c dirmngr-client foo.crt
+@c @end example
+@c
+@c This command will send an Assuan request to an already running Dirmngr
+@c instance. foo.crt is expected to be a standard X.509 certificate and
+@c dirmngr will receive the Assuan command
+@c
+@c @example
+@c CHECKCRL @var [{fingerprint}]
+@c @end example
+@c
+@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 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
+@c @example
+@c INQUIRE TARGETCERT
+@c @end example
+@c
+@c The caller (in our example dirmngr-client) is then expected to return
+@c the certificate for the request (which should match @var{fingerprint})
+@c as a binary blob.
+@c
+@c Dirmngr now passes control to @code{crl_cache_cert_isvalid}. This
+@c function checks whether a CRL item exists for target certificate. These
+@c CRL items are kept in a database of already loaded and verified CRLs.
+@c This mechanism is called the CRL cache. Obviously timestamps are kept
+@c there with each item to cope with the expiration date of the CRL. The
+@c possible return values are: @code{0} to indicate that a valid CRL is
+@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 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 calls @code{clr_cache_reload_crl} and if this succeeds calls
+@c @code{crl_cache_cert_isvald) once more. All further errors are
+@c immediately returned to the caller.
+@c
+@c @code{crl_cache_reload_crl} is the actual heart of the CRL management.
+@c It locates the corresponding CRL for the target certificate, reads and
+@c verifies this CRL and stores it in the CRL cache. It works like this:
+@c
+@c * Loop over all crlDPs in the target certificate.
+@c * If the crlDP is invalid immediately terminate the loop.
+@c * Loop over all names in the current crlDP.
+@c * If the URL scheme is unknown or not enabled
+@c (--ignore-http-dp, --ignore-ldap-dp) continues with
+@c the next name.
+@c * @code{crl_fetch} is called to actually retrieve the CRL.
+@c In case of problems this name is ignore and we continue with
+@c the next name. Note that @code{crl_fetch} does only return
+@c a descriptor for the CRL for further reading so does the CRL
+@c does not yet end up in memory.
+@c * @code{crl_cache_insert} is called with that descriptor to
+@c actually read the CRL into the cache. See below for a
+@c description of this function. If there is any error (e.g. read
+@c problem, CRL not correctly signed or verification of signature
+@c not possible), this descriptor is rejected and we continue
+@c with the next name. If the CRL has been successfully loaded,
+@c the loop is terminated.
+@c * If no crlDP has been found in the previous loop use a default CRL.
+@c Note, that if any crlDP has been found but loading of the CRL failed,
+@c this condition is not true.
+@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 immediately without
+@c checking the rest of the servers from the first step.
+@c * Ready.
+@c
+@c
+@c The @code{crl_cache_insert} function takes care of reading the bulk of
+@c the CRL, parsing it and checking the signature. It works like this: A
+@c new database file is created using a temporary file name. The CRL
+@c parsing machinery is started and all items of the CRL are put into
+@c this database file. At the end the issuer certificate of the CRL
+@c needs to be retrieved. Three cases are to be distinguished:
+@c
+@c a) An authorityKeyIdentifier with an issuer and serialno exits: The
+@c certificate is retrieved using @code{find_cert_bysn}. If
+@c the certificate is in the certificate cache, it is directly
+@c returned. Then the requester (i.e. the client who requested the
+@c CRL check) is asked via the Assuan inquiry ``SENDCERT'' whether
+@c he can provide this certificate. If this succeed the returned
+@c certificate gets cached and returned. Note, that dirmngr does not
+@c verify in any way whether the expected certificate is returned.
+@c It is in the interest of the client to return a useful certificate
+@c as otherwise the service request will fail due to a bad signature.
+@c The last way to get the certificate is by looking it up at
+@c external resources. This is done using the @code{ca_cert_fetch}
+@c and @code{fetch_next_ksba_cert} and comparing the returned
+@c certificate to match the requested issuer and seriano (This is
+@c needed because the LDAP layer may return several certificates as
+@c LDAP as no standard way to retrieve by serial number).
+@c
+@c b) An authorityKeyIdentifier with a key ID exists: The certificate is
+@c retrieved using @code{find_cert_bysubject}. If the certificate is
+@c in the certificate cache, it is directly returned. Then the
+@c requester is asked via the Assuan inquiry ``SENDCERT_SKI'' whether
+@c he can provide this certificate. If this succeed the returned
+@c certificate gets cached and returned. Note, that dirmngr does not
+@c verify in any way whether the expected certificate is returned.
+@c It is in the interest of the client to return a useful certificate
+@c as otherwise the service request will fail due to a bad signature.
+@c The last way to get the certificate is by looking it up at
+@c external resources. This is done using the @code{ca_cert_fetch}
+@c and @code{fetch_next_ksba_cert} and comparing the returned
+@c certificate to match the requested subject and key ID.
+@c
+@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 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
+@c certificate gets cached and returned. Note, that dirmngr does not
+@c verify in any way whether the expected certificate is returned.
+@c It is in the interest of the client to return a useful certificate
+@c as otherwise the service request will fail due to a bad signature.
+@c The last way to get the certificate is by looking it up at
+@c external resources. This is done using the @code{ca_cert_fetch}
+@c and @code{fetch_next_ksba_cert} and comparing the returned
+@c certificate to match the requested subject; the first certificate
+@c with a matching subject is then returned.
+@c
+@c If no certificate was found, the function returns with the error
+@c GPG_ERR_MISSING_CERT. Now the signature is verified. If this fails,
+@c the erro is returned. On success the @code{validate_cert_chain} is
+@c used to verify that the certificate is actually valid.
+@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 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
+@c broken PKI. However, due to overlapping expiring times and imprecise
+@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 In the end the same fucntionality is used, albeit hidden by a couple
+@c of indirection and argument and result code mangling. It furthere
+@c ingetrages OCSP checking depending on options are the way it is
+@c called. GPGSM still uses this command but might eventuall switch over
+@c to CHECKCRL and CHECKOCSP so that ISVALID can be retired.
+@c
+@c
+@c @section Validating a certificate
+@c
+@c We describe here how the internal function @code{validate_cert_chain}
+@c works. Note that mainly testing purposes this functionality may be
+@c called directly using @cmd{dirmngr-client --validate @file{foo.crt}}.
+@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.
+@c
+@c We first check that the certificate may be used for the requested
+@c purpose (i.e. OCSP or CRL signing). If this is not the case
+@c GPG_ERR_WRONG_KEY_USAGE is returned.
+@c
+@c The next step is to find the trust anchor (root certificate) and to
+@c assemble the chain in memory: Starting with the target certificate,
+@c the expiration time is checked against the current date, unknown
+@c critical extensions are detected and certificate policies are matched
+@c (We only allow 2.289.9.9 but I have no clue about that OID and from
+@c where I got it - it does not even seem to be assigned - debug cruft?).
+@c
+@c Now if this certificate is a self-signed one, we have reached the
+@c trust anchor. In this case we check that the signature is good, the
+@c certificate is allowed to act as a CA, that it is a trusted one (by
+@c checking whether it is has been put into the trusted-certs
+@c configuration directory) and finally prepend into to our list
+@c representing the certificate chain. This steps ends then.
+@c
+@c If it is not a self-signed certificate, we check that the chain won't
+@c get too long (current limit is 100), if this is the case we terminate
+@c with the error GPG_ERR_BAD_CERT_CHAIN.
+@c
+@c Now the issuer's certificate is looked up: If an
+@c authorityKeyIdentifier is available, this one is used to locate the
+@c certificate either using issuer and serialnumber or subject DN
+@c (i.e. the issuer's DN) and the keyID. The functions
+@c @code{find_cert_bysn) and @code{find_cert_bysubject} are used
+@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 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}.
+@c
+@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 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
+@c After the end of the loop and if no error as been encountered
+@c (i.e. the certificate chain has been assempled correctly), a check is
+@c done whether any certificate expired or a critical policy has not been
+@c met. In any of these cases the validation terminates with an
+@c appropriate error.
+@c
+@c Finally the function @code{check_revocations} is called to verify no
+@c certificate in the assempled chain has been revoked: This is an
+@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 certificate has
+@c been removed from the list of trusted certificates.
+@c
+@c
+@c
+@c
+@c @section Looking up certificates through LDAP.
+@c
+@c This describes the LDAP layer to retrieve certificates.
+@c the functions @code{ca_cert_fetch} and @code{fetch_next_ksba_cert} are
+@c used for this. The first one starts a search and the second one is
+@c used to retrieve certificate after certificate.
+@c