     [file version.texi not included]

Dirmngr
*******

This manual is for Dirmngr (version VERSION, UPDATED), which is an X.509 CRL and OCSP manager.

Copyright © 2002 Klarälvdalens Datakonsult AB

Copyright © 2004, 2005, 2006 g10 Code GmbH

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. The text of the license can be found in the section entitled ``Copying''.

About Dirmngr.
**************

Dirmngr is a server for managing and downloading certificate revocation lists (CRLs) for X.509 certificates and for downloading the certificates themselves. Dirmngr also handles OCSP requests as an alternative to CRLs. Dirmngr is either invoked internally by gpgsm (from gnupg 1.9) or when running as a system daemon through the dirmngr-client tool.

How to install Dirmngr.
***********************

Installation is decribed in the file INSTALL and given that you are already reading this documentation we can only give some hints on further configuration.  If you plan to use dirmngr as a system daemon and not only as a part of gnupg 1.9, you should read on.

If dirmngr is started in system daemon mode, it uses a directory layout as common for system daemon and does not make use of the drefault ~/.gnupg directory.  To comply with the rules on GNU/Linux systems you should have build time configured dirmngr using:

     ./configure --sysconfdir=/etc --localstatedir=/var

This is to make sure that the configuration file is searched in the directory /etc/dirmngr and the variable data below /var; the default would be to install them in the /usr/local too where the binaries get installed.  If you selected to use the --prefix=/ you obviously don't need those option as they are the default then.  Further on we assume that you used these options.

Dirmngr makes use of several directories when running in daemon mode:

/etc/dirmngr
     This is where all the configuration files are expected by default.

/etc/dirmngr/trusted-certs
     This directory should be filled with certificates of Root CAs you are trusting in checking the CRLS and signing OCSP Reponses.  Usually these are the same certificates you use with the applications making use of dirmngr.  It is expected that each of these certificates files contain exactly one DER encoded certificate in a file with the suffix .crt.  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.

     Note that for OCSP responses the certificate specified using the option --ocsp-signer is always considered valid to sign OCSP requests.

/var/lib/dirmngr/extra-certs
     This directory may contain extra certificates which are preloaded into the interal cache on startup.  This is convenient in cases you have a couple intermediate CA certificates or certificates ususally used to sign OCSP reponses.  These certificates are first tried before going out to the net to look for them.  These certificates must also be DER encoded and suffixed with .crt.

/var/run/dirmngr
     This directory keeps the socket file for accsing dirmngr services. The name of the socket file will be socket.  Make sure that this directory has the proper permissions to let dirmngr create the socket file and that eligible users may read and write to that socket.

/var/cache/dirmngr/crls.d
     This directory is used to store cached CRLs.  The crls.d part will be created by dirmngr if it does not exists but you need to make sure that the upper directory exists.

To be able to see what's going on you should create the configure file /etc/dirmngr/dirmngr.conf with at least one line:

     log-file /var/log/dirmngr/dirmngr.log

To be able to perform OCSP requests you probably want to add the line:

     allow-ocsp

Now you may start dirmngr as a system daemon using:

     dirmngr --daemon

Please ignore the output; it is not needed anymore.  Check the log file to see whether all trusted root certificates have benn loaded correctly.

Commands
********

Commands are not distinguished from options execpt for the fact that only one command is allowed.

--version
     Print the program version and licensing information.  Note that you can abbreviate this command.

--help, -h
     Print a usage message summarizing the most useful command-line options. Not that you can abbreviate this command.

--server
     Run in server mode and wait for commands on the stdin.  The default mode is to create a socket and listen for commands there.

--daemon
     Run in background daemon mode and listen for commands on a socket. Note that this also changes the default home directory and enables the internal certificate validation code.

--list-crls
     List the contents of the CRL cache on stdout. This is probably only useful for debugging purposes.

--load-crl FILE
     This command requires a filename as additional argument, and it will make dirmngr try to import the CRL in 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 gpgsm's --call-dirmngr loadcrl filename command so that gpgsm can help dirmngr.

--fetch-crl URL
     This command requires an URL as additional argument, and it will make dirmngr try to retrieve an import the CRL from that URL into it's cache.  This is mainly useful for debugging purposes.

--shutdown
     This commands shuts down an running instance of Dirmngr.  This command has corrently no effect.

--flush
     This command removes all CRLs from Dirmngr's cache.  Client requests will thus trigger reading of fresh CRLs.

Option Summary
**************

--options FILE
     Reads configuration from FILE instead of from the default per-user configuration file.  The default configuration file is named gpgsm.conf and expected in the home directory.

--homedir DIR
     Set the name of the home directory to DIR.  This option is only effective when used on the command line.  The default depends on the running mode:

     With --daemon given on the commandline
          the directory named /etc/dirmngr for configuration files, /var/lib/dirmngr/ for extra data and /var/cache/dirmngr for cached CRLs.

     Without --daemon given on the commandline
          the directory named .gnupg directly below the home directory of the user unless the environment variable GNUPGHOME has been set in which case its value will be used.  All kind of data is stored below this directory.

-v

--verbose
     Outputs additional information while running. You can increase the verbosity by giving several verbose commands to DIRMNGR, such as -vv.

--log-file FILE
     Append all logging output to FILE.  This is very helpful in seeing what the agent actually does.

--debug-level LEVEL
     Select the debug level for investigating problems. LEVEL may be one of:

     none
          no debugging at all.

     basic
          some basic debug messages

     advanced
          more verbose debug messages

     expert
          even more detailed messages

     guru
          all of the debug messages you can get

     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.

--debug FLAGS
     This option is only useful for debugging and the behaviour may change at any time without notice.  FLAGS are bit encoded and may be given in usual C-Syntax.

--debug-all
     Same as --debug=0xffffffff

--debug-wait N
     When running in server mode, wait N seconds before entering the actual processing loop and print the pid.  This gives time to attach a debugger.

-s
--sh
-c
--csh
     Format the info output in daemon mode for use with the standard Bourne shell respective the C-shell . The default ist to guess it based on the environment variable SHELL which is in almost all cases sufficient.

--force
     Enabling this option forces loading of expired CRLs; this is only useful for debugging.

--disable-ldap
     Entirely disables the use of LDAP.

--disable-http
     Entirely disables the use of HTTP.

--ignore-http-dp
     When looking for the location of a CRL, the to be tested certificate usually contains so called 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 HTTP scheme are ignored when looking for a suitable DP.

--ignore-ldap-dp
     This is similar to --ignore-http-dp but ignores entries using the LDAP scheme.  Both options may be combined resulting in ignoring DPs entirely.

--honor-http-proxy
     If the environment variable http_proxy has been set, use its value to access HTTP servers.

--http-proxy HOST[:PORT]
     Use HOST and PORT to access HTTP servers.  The use of this options overrides the environment variable http_proxy regardless whether --honor-http-proxy has been set.

--ldap-proxy HOST[:PORT]
     Use HOST and PORT to connect to LDAP servers.  If PORT is ommitted, port 389 (standard LDAP port) is used.  This overrides any specified host and port part in a LDAP URL and will also be used if host and port have been ommitted from the URL.

--only-ldap-proxy
     Never use anything else but the LDAP "proxy" as configured with --ldap-proxy.  Usually dirmngr tries to use other configured LDAP server if the connection using the "proxy" failed.

--ldapserverlist-file 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 FILE is dirmngr_ldapservers.conf or ldapservers.conf when running in --daemon mode.

     This server list file contains one LDAP server per line in the format

     HOSTNAME:PORT:USERNAME:PASSWORD:BASE_DN

     Lines starting with a  # are comments.

     Note that as usual all strings entered are expected to be UTF_8 encoded. Obviously this will lead to problems if the password has orginally been encoded as Latin-1.  tehre isno solutionhere than to put such a password in the binary encoding into the file (i.e. non-ascii characters won't show up readable). (The gpgconf tool might be helpful for frontends as it allows to edit this configuration file suing percent escaped strings.)

--ldaptimeout SECS
     Specify the number of seconds to wait for an LDAP query before timing out. The default is currently 100 seconds.  0 will never timeout.

--add-servers
     This options makes dirmngr add any servers it discovers when validating certificates against CRLs to the internal list of servers to consult for certificates and CRLs.

     This options is useful when trying to validate a certificate that has 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 --add-servers option is used.

     Note: The current version of dirmngr has this option disabled by default.

--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.

--ocsp-responder URL
     Use URL as the default OCSP Responder if the certificate does not contain information about an assigned responder.  Note, that --ocsp-signer must also be set to a valid certificate.

--ocsp-signer FPR
     Use the certificate with the fingerprint FPR to check the responses of the default OCSP Responder. Dirmngr will retrieve this certificate from the current client.

     If a response has been signed by this certificate no further check upon the validity of this certificate is done!

--ocsp-max-clock-skew N
     The number of seconds a skew between the OCSP respinder and them local clock is accepted.  Default is 600 (20 minutes).

--ocsp-current-period N
     The number of seconds an OCSP reponse is valid after the time given in the NEXT_UPDATE datum.  Default is 10800 (3 hours).

--max-replies N
     Do not return more that N items in one query.  The default is 10.

Use of signals.
***************

A running dirmngr may be controlled by signals, i.e. using the kill command to send a signal to the process.

Here is a list of supported signals:

SIGHUP
     This signals flushes all internally cached CRLs as well as any cached certificates.  Then the certificate cache is reinitialized as on startup.  Options are re-read from the configuration file.

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.

SIGINT
     Shuts down the process immediately.

SIGUSR1
     This prints some caching statistics to the log file.

Examples
********

The way to start the dirmngr in the foreground (as done by tools if no dirmngr is running in the background) is to use:

       dirmngr --server -v

If a dirmngr is supposed to be used as a system wide daemon, it should be started like:

       dirmngr --daemon

This will force it to go into the backround, read the default certificates (including the trusted root certificates) and listen on a socket for client requests.  It does also print information about the socket used but they are only for compatibilty reasons with old GnuPG versions and may be ignored.

gpgsm(1), dirmngr-client(1)
     [file see-also-note.texi not included]

Dirmngr's Assuan Protocol
*************************

Assuan is the IPC protocol used to access dirmngr.  This is a description of the commands implemented by dirmngr.

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:

       S: D <DER encoded certificate>
       S: END
       S: D <second DER encoded certificate>
       S: END
       S: OK

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

       S: S TRUNCATED <n>

To indicate that the output was truncated to N items due to a limitation of the server or by an arbitrary set limit.

Validate a certificate using a CRL or OCSP
==========================================

Check whether the certificate described by the certificate_ID (which is a fingerprint) has been revoked. Due to caching, the Dirmngr is able to answer immediately in most cases:

S: OK

Yes, the certificate is not revoked and we have a up-to-date revocation list for that certificate.

S: E 301 certificate has been revoked

The client may then issue another command to retrieve information on the revocation reason.

S: E 302 no CRL known for this certificate

S: E 303 CRL is too old and a new one could not be retrieved

If the DirMngr has not enough information about the given certificate which is the case for not yet cached certificates because the clients only passes the CertID, the DirMngr will will inquire the missing data:

       S: INQUIRE SENDCERT <CertID>
       C: D <DER encoded certificate>
       C: END

A client should be aware the the DirMngr may ask for more than one Certificate.

If the option --allow-ocsp is enabled, this command may alternativly run an OCSP request.  The client requests this by simply using the fingerrpint instead of the certificate-id.  There is no fall back to CRL checking if the OCSP requests could not be done for whatever reason.

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 know, the function inquires the certificate using:

       S: INQUIRE TARGETCERT
       C: D <DER encoded certificate>
       C: END

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.

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.

Validate a certificate using OCSP
=================================

Check whether the certificate with FINGERPRINT (SHA-1 hash of the entire X.509 certificate blob) is valid or not by consulting the appropiateOCSP responder.  If the fingerprint has not been given or the certificate is not know, the function inquires the certificate using:

       S: INQUIRE TARGETCERT
       C: D <DER encoded certificate>
       C: END

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.

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.

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 wnats 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

       S: INQUIRE TARGETCERT
       C: D <DER encoded certificate>
       C: END

Thus the caller is expected to return the certificate for the request as a binary blob.

The return code is 0 for success; i.e. the certificate has not been succesfully cached or one of the usual error codes from libgpg-error.

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

       S: INQUIRE TARGETCERT
       C: D <DER encoded certificate>
       C: END

Thus the caller is expected to return the certificate for the request as a binary blob.

The Client Tool
***************

The dirmngr-client is a simple tool to contact a running dirmngr and test whether a certificate has been revoked --- either by being listed in the corresponding CRL or by running the OCSP protocol. If no dirmngr is running, a new instances will be started but this is in general not a good idea due to the huge performance overhead.

The usual way to run this tool is either:

     dirmngr-client ACERT

or

     dirmngr-client <ACERT

Where ACERT is one DER encoded (binary) X.509 certificates to be tested. The return value of this command is

0
     The certificate under question is valid; i.e. there is a valid CRL available and it is not listed tehre or teh OCSP request returned that that certificate is valid.

1
     The certificate has been revoked

2 (and other values)
     There was a problem checking the revocation state of the certificate. A message to stderr has given more detailed information.  Most likely this is due to a missing or expired CRL or due to a network problem.

dirmngr-client may be called with the following options:

--version
     Print the program version and licensing information.  Note that you cannot abbreviate this command.

--help, -h
     Print a usage message summarizing the most useful command-line options. Note that you cannot abbreviate this command.

--quiet, -q
     Make the output extra brief by suppressing any informational messages.

-v

--verbose
     Outputs additional information while running. You can increase the verbosity by giving several verbose commands to DIRMNGR, such as -vv.

--pem
     Assume that the given certificate is in PEM (armored) format.

--ocsp
     Do the check using the COSP protocol and ignore any CRLs.

--ping
     Check whether the dirmngr daemon is up and running.

--cache-cert
     Put the given certificate into the cache of a running dirmngr.  This is mainly useful for debugging.

--validate
     Validate the given certificate using dirmngr's internal validation code. This is mainly useful for debugging.

--load-crl
     This command expects a list of filenames with DER encoded CRL files. All CRL will be vfalidated and then loaded into dirmngr's cache.

--lookup
     Take the remaining arguments and run a lookup command on each of them. The results are Base-64 encoded outputs (without header lines).  This may be used to retrieve certificates from a server. However the output format is not very well suited if more than one certificate is returned.

--squid-mode
     Run DIRMNGR-CLIENT in a mode suitable as a helper program for Squid's external_acl_type option.

dirmngr(1), gpgsm(1)
     [file see-also-note.texi not included]

     [file gpl.texi not included]

History
*******

  * Using DirMngr, 2002, Steffen Hansen, Klarälvdalens Datakonsult AB.

  * Using DirMngr, 2004, 2005, 2006 Werner Koch, g10 Code GmbH.