diff options
Diffstat (limited to 'doc/dirmngr.texi')
| -rw-r--r-- | doc/dirmngr.texi | 1273 |
1 files changed, 1273 insertions, 0 deletions
diff --git a/doc/dirmngr.texi b/doc/dirmngr.texi new file mode 100644 index 0000000..d6ef375 --- /dev/null +++ b/doc/dirmngr.texi @@ -0,0 +1,1273 @@ +@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 +\- GnuPG's network access 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. The test on the available of +Tor is done by trying to connects to a SOCKS proxy at either port 9050 +or 9150); if another type of proxy is listening on one of these ports, +you should use @option{--no-use-tor}. + +@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. Somes keyservers use 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{https://keyserver.ubuntu.com}. + +Windows users with a keyserver running on their Active Directory +may use the short form @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 things are more complicated +and two methods are available: + +The modern method (since version 2.2.28) is to use the very same syntax +as used with the option @option{--ldapserver}. Please see over +there for details; here is an example: + +@example + keyserver ldap:ldap.example.com::uid=USERNAME,ou=GnuPG Users, + dc=example,dc=com:PASSWORD::starttls +@end example + + The other method is to use a full URL for @var{name}; 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 your LDAP + administrator. Note that only simple authentication + (i.e. cleartext passwords) is supported and thus using ldaps is + strongly suggested (since 2.2.28 "ldaps" defaults to port 389 + and uses STARTTLS). On Windows authentication via AD can be + requested by adding @code{gpgNtds=1} after the fourth question + mark instead of the bindname and password parameter. + + + +@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 [http://]@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 X.509 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:flags} + +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 --ldapserver @var{spec} +@opindex ldapserver +This is an alternative way to specify LDAP servers for CRL and X.509 +certificate retrieval. If this option is used the servers configured +in @file{dirmngr_ldapservers.conf} (or the file given by +@option{--ldapserverlist-file}) are cleared. Note that +@file{dirmngr_ldapservers.conf} is not read again by a reload +signal. However, @option{--ldapserver} options are read again. + +@var{spec} is either a proper LDAP URL or a colon delimited list of +the form + +@sc{hostname:port:username:password:base_dn:flags:} + +with an optional prefix of @code{ldap:} (but without the two slashes +which would turn this into a proper LDAP URL). @sc{flags} is a list +of one or more comma delimited keywords: +@table @code +@item plain +The default: Do not use a TLS secured connection at all; the default +port is 389. +@item starttls +Use STARTTLS to secure the connection; the default port is 389. +@item ldaptls +Tunnel LDAP through a TLS connection; the default port is 636. +@item ntds +On Windows authenticate the LDAP connection using the Active Directory +with the current user. +@item areconly +On Windows use only the A or AAAA record when resolving the LDAP +server name. +@end table + +Note that in an URL style specification the scheme @code{ldaps://} +refers to STARTTLS and _not_ to LDAP-over-TLS. + + +@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 --ignore-cert @var{fpr}|@var{file} +@opindex ignore-cert +Entirely ignore certificates with the fingerprint @var{fpr}. As an +alternative to the fingerprint a filename can be given in which case +all certificates described in that file are ignored. 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. The format of such a file is a list of SHA-1 +fingerprint, one per line with optional colons between the bytes. +Empty lines and lines prefixed with a hash mark are ignored. + +This option is useful as a quick workaround to exclude certain +certificates from the system store. + + +@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 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 |