mirror of
git://git.gnupg.org/gnupg.git
synced 2024-11-09 21:28:51 +01:00
42b0e9558a
-- These are non-substantive corrections for minor spelling mistakes within the GnuPG codebase. With something like this applied to the codebase, and a judiciously tuned spellchecker integrated as part of a standard test suite, it should be possible to keep a uniform orthography within the project. GnuPG-bug-id: 7116
1366 lines
51 KiB
Plaintext
1366 lines
51 KiB
Plaintext
@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
|
|
option is deprecated and 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 --compatibility-flags @var{flags}
|
|
@opindex compatibility-flags
|
|
Set compatibility flags to work around certain problems or to emulate
|
|
bugs. The @var{flags} are given as a comma separated list of flag
|
|
names and are OR-ed together. The special flag "none" clears the list
|
|
and allows one to start over with an empty list. To get a list of
|
|
available flags the sole word "help" can be used.
|
|
|
|
@item --faked-system-time @var{epoch}
|
|
@opindex faked-system-time
|
|
This option is only useful for testing; it sets the system time back or
|
|
forth to @var{epoch} which is the number of seconds elapsed since the year
|
|
1970. Alternatively @var{epoch} may be given as a full ISO time string
|
|
(e.g. "20070924T154812").
|
|
|
|
@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 debug flags. All flags are or-ed and @var{flags} 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.
|
|
This option is only useful for debugging and the behavior may change
|
|
at any time without notice.
|
|
|
|
@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 availability of
|
|
Tor is done by trying to connect 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
|
|
@option{--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 or "ldap" for the LDAP
|
|
keyservers. 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.
|
|
|
|
Some keyservers synchronize with each other, so there is not always a
|
|
need to send keys to more than one server. Some 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}. To avoid the
|
|
use of a default keyserver the value @code{none} can be used.
|
|
|
|
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. If on Windows the option is used but
|
|
the environment variable is not set, the proxy settings are taken
|
|
from the system.
|
|
|
|
@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 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 should in general not be used.
|
|
|
|
This option might be 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.
|
|
|
|
Caveat emptor: Using this option may enable denial-of-service attacks
|
|
and leak search requests to unknown third parties. This is because
|
|
arbitrary servers are added to the internal list of LDAP servers which
|
|
in turn is used for all unspecific LDAP queries as well as a fallback
|
|
for queries which did not return a result.
|
|
|
|
|
|
@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-crl-extension @var{oid}
|
|
@opindex ignore-crl-extension
|
|
Add @var{oid} to the list of ignored CRL extensions. The @var{oid} is
|
|
expected to be in dotted decimal form. Critical flagged CRL
|
|
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 to 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
|
|
|
|
Several options control the use of trusted certificates for TLS and
|
|
CRLs. Here is an Overview on the use and origin of those Root CA
|
|
certificates:
|
|
@table @asis
|
|
|
|
@item System
|
|
|
|
These System root certificates are used by: FIXME
|
|
|
|
The origin of the system provided certificates depends on the
|
|
platform. On Windows all certificates from the Windows System Stores
|
|
@code{ROOT} and @code{CA} are used.
|
|
|
|
On other platforms the certificates are read from the first file found
|
|
form this list: @file{/etc/ssl/ca-bundle.pem},
|
|
@file{/etc/ssl/certs/ca-certificates.crt},
|
|
@file{/etc/pki/tls/cert.pem},
|
|
@file{/usr/local/share/certs/ca-root-nss.crt},
|
|
@file{/etc/ssl/cert.pem}.
|
|
|
|
@item GnuPG
|
|
|
|
The GnuPG specific certificates stored in the directory
|
|
@file{/etc/gnupg/trusted-certs} are only used to validate CRLs.
|
|
|
|
@c Note that dirmngr's VALIDATE command also uses them but that
|
|
@c command is anyway only intended for debugging.
|
|
|
|
@item OpenPGP keyserver
|
|
|
|
For accessing the OpenPGP keyservers the only certificates used are
|
|
those set with the configuration option @option{hkp-cacert}.
|
|
|
|
@item OpenPGP keyserver pool
|
|
|
|
This is usually only one certificate read from the file
|
|
@file{@value{DATADIR}/gnupg/sks-keyservers.netCA.pem}. If this
|
|
certificate exists it is used to access the special keyservers
|
|
@code{hkps.pool.sks-keyservers.net} (or @file{hkps://keys.gnupg.net}).
|
|
|
|
@end table
|
|
|
|
Please note that @command{gpgsm} accepts Root CA certificates for its
|
|
own purposes only if they are listed in its file @file{trustlist.txt}.
|
|
@command{dirmngr} does not make use of this list --- except FIXME.
|
|
|
|
|
|
@mansect notes
|
|
|
|
To be able to see diagnostics it is often useful to put at least the
|
|
following lines into the configuration file
|
|
@file{~/gnupg/dirmngr.conf}:
|
|
|
|
@example
|
|
log-file ~/dirmngr.log
|
|
verbose
|
|
@end example
|
|
|
|
You may want to check the log file to see whether all desired root CA
|
|
certificates are correctly loaded.
|
|
|
|
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 or that after the installation
|
|
of a new GnuPG versions the right dirmngr version is running, you
|
|
should kill an existing dirmngr so that a new instance is started as
|
|
needed by the other components:
|
|
|
|
@example
|
|
gpgconf --kill dirmngr
|
|
@end example
|
|
|
|
Direct interfaction with the dirmngr is possible by using the command
|
|
|
|
@example
|
|
gpg-connect-agent --dirmngr
|
|
@end example
|
|
|
|
Enter @code{HELP} at the prompt to see a list of commands and enter
|
|
@code{HELP} followed by a command name to get help on that command.
|
|
|
|
|
|
|
|
@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 error 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 functionality 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 eventually 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
|