1DIRMNGR(8) GNU Privacy Guard 2.3 DIRMNGR(8)
2
6 dirmngr - GnuPG's network access daemon
7
9 dirmngr [options] command [args]
10
13 Since version 2.1 of GnuPG, dirmngr takes care of accessing the OpenPGP
14 keyservers. As with previous versions it is also used as a server for
15 managing and downloading certificate revocation lists (CRLs) for X.509
16 certificates, downloading X.509 certificates, and providing access to
17 OCSP providers. Dirmngr is invoked internally by gpg, gpgsm, or via
18 the gpg-connect-agent tool.
19
26 Commands are not distinguished from options except for the fact that
27 only one command is allowed.
28 --version
31 Print the program version and licensing information. Note that
32 you cannot abbreviate this command.
33 --help, -h
36 Print a usage message summarizing the most useful command-line
37 options. Note that you cannot abbreviate this command.
38 --dump-options
41 Print a list of all available options and commands. Note that
42 you cannot abbreviate this command.
43 --server
46 Run in server mode and wait for commands on the stdin. The de‐
47 fault mode is to create a socket and listen for commands there.
48 This is only used for testing.
49 --daemon
52 Run in background daemon mode and listen for commands on a
53 socket. This is the way dirmngr is started on demand by the
54 other GnuPG components. To force starting dirmngr it is in gen‐
55 eral best to use gpgconf --launch dirmngr.
56 --supervised
59 Run in the foreground, sending logs to stderr, and listening on
60 file descriptor 3, which must already be bound to a listening
61 socket. This option is deprecated and not supported on Windows.
62 --list-crls
65 List the contents of the CRL cache on stdout. This is probably
66 only useful for debugging purposes.
67 --load-crl file
70 This command requires a filename as additional argument, and it
71 will make Dirmngr try to import the CRL in file into it's cache.
72 Note, that this is only possible if Dirmngr is able to retrieve
73 the CA's certificate directly by its own means. In general it
74 is better to use gpgsm's --call-dirmngr loadcrl filename command
75 so that gpgsm can help dirmngr.
76 --fetch-crl url
79 This command requires an URL as additional argument, and it will
80 make dirmngr try to retrieve and import the CRL from that url
81 into it's cache. This is mainly useful for debugging purposes.
82 The dirmngr-client provides the same feature for a running dirm‐
83 ngr.
84 --shutdown
87 This commands shuts down an running instance of Dirmngr. This
88 command has currently no effect.
89 --flush
92 This command removes all CRLs from Dirmngr's cache. Client re‐
93 quests will thus trigger reading of fresh CRLs.
94
97 Note that all long options with the exception of --options and --home‐
98 dir may also be given in the configuration file after stripping off the
99 two leading dashes.
100 --options file
104 Reads configuration from file instead of from the default per-
105 user configuration file. The default configuration file is
106 named ‘dirmngr.conf’ and expected in the home directory.
107 --homedir dir
110 Set the name of the home directory to dir. This option is only
111 effective when used on the command line. The default is the di‐
112 rectory named ‘.gnupg’ directly below the home directory of the
113 user unless the environment variable GNUPGHOME has been set in
114 which case its value will be used. Many kinds of data are
115 stored within this directory.
116 -v
120 --verbose
122 Outputs additional information while running. You can increase
123 the verbosity by giving several verbose commands to dirmngr,
124 such as -vv.
125 --log-file file
129 Append all logging output to file. This is very helpful in see‐
130 ing what the agent actually does. Use ‘socket://’ to log to
131 socket.
132 --debug-level level
135 Select the debug level for investigating problems. level may be
136 a numeric value or by a keyword:
137 none No debugging at all. A value of less than 1 may be used
140 instead of the keyword.
141 basic Some basic debug messages. A value between 1 and 2 may
143 be used instead of the keyword.
144 advanced
146 More verbose debug messages. A value between 3 and 5 may
147 be used instead of the keyword.
148 expert Even more detailed messages. A value between 6 and 8 may
150 be used instead of the keyword.
151 guru All of the debug messages you can get. A value greater
153 than 8 may be used instead of the keyword. The creation
154 of hash tracing files is only enabled if the keyword is
155 used.
156 How these messages are mapped to the actual debugging flags is not
158 specified and may change with newer releases of this program. They are
159 however carefully selected to best aid in debugging.
160 --debug flags
163 Set debug flags. All flags are or-ed and flags may be given in
164 C syntax (e.g. 0x0042) or as a comma separated list of flag
165 names. To get a list of all supported flags the single word
166 "help" can be used. This option is only useful for debugging
167 and the behavior may change at any time without notice.
168 --debug-all
171 Same as --debug=0xffffffff
172 --tls-debug level
175 Enable debugging of the TLS layer at level. The details of the
176 debug level depend on the used TLS library and are not set in
177 stone.
178 --debug-wait n
181 When running in server mode, wait n seconds before entering the
182 actual processing loop and print the pid. This gives time to
183 attach a debugger.
184 --disable-check-own-socket
187 On some platforms dirmngr is able to detect the removal of its
188 socket file and shutdown itself. This option disable this self-
189 test for debugging purposes.
190 -s
193 --sh
194 -c
195 --csh Format the info output in daemon mode for use with the standard
196 Bourne shell respective the C-shell. The default is to guess it
197 based on the environment variable SHELL which is in almost all
198 cases sufficient.
199 --force
202 Enabling this option forces loading of expired CRLs; this is
203 only useful for debugging.
204 --use-tor
207 --no-use-tor
208 The option --use-tor switches Dirmngr and thus GnuPG into ``Tor
209 mode'' to route all network access via Tor (an anonymity net‐
210 work). Certain other features are disabled in this mode. The
211 effect of --use-tor cannot be overridden by any other command or
212 even by reloading dirmngr. The use of --no-use-tor disables the
213 use of Tor. The default is to use Tor if it is available on
214 startup or after reloading dirmngr. The test on the availabil‐
215 ity of Tor is done by trying to connect to a SOCKS proxy at ei‐
216 ther port 9050 or 9150; if another type of proxy is listening on
217 one of these ports, you should use --no-use-tor.
218 --standard-resolver
221 This option forces the use of the system's standard DNS resolver
222 code. This is mainly used for debugging. Note that on Windows
223 a standard resolver is not used and all DNS access will return
224 the error ``Not Implemented'' if this option is used. Using
225 this together with enabled Tor mode returns the error ``Not En‐
226 abled''.
227 --recursive-resolver
230 When possible use a recursive resolver instead of a stub re‐
231 solver.
232 --resolver-timeout n
235 Set the timeout for the DNS resolver to N seconds. The default
236 are 30 seconds.
237 --connect-timeout n
240 --connect-quick-timeout n
242 Set the timeout for HTTP and generic TCP connection attempts to
243 N seconds. The value set with the quick variant is used when
244 the --quick option has been given to certain Assuan commands.
245 The quick value is capped at the value of the regular connect
246 timeout. The default values are 15 and 2 seconds. Note that
247 the timeout values are for each connection attempt; the connec‐
248 tion code will attempt to connect all addresses listed for a
249 server.
250 --listen-backlog n
253 Set the size of the queue for pending connections. The default
254 is 64.
255 --allow-version-check
258 Allow Dirmngr to connect to https://versions.gnupg.org to get
259 the list of current software versions. If this option is en‐
260 abled the list is retrieved in case the local copy does not ex‐
261 ist or is older than 5 to 7 days. See the option --query-swdb
262 of the command gpgconf for more details. Note, that regardless
263 of this option a version check can always be triggered using
264 this command:
265 gpg-connect-agent --dirmngr 'loadswdb --force' /bye
267 --keyserver name
271 Use name as your keyserver. This is the server that gpg commu‐
272 nicates with to receive keys, send keys, and search for keys.
273 The format of the name is a URI: `scheme:[//]keyserver‐
274 name[:port]' The scheme is the type of keyserver: "hkp" for the
275 HTTP (or compatible) keyservers, "ldap" for the LDAP keyservers,
276 or "mailto" for the Graff email keyserver. Note that your par‐
277 ticular installation of GnuPG may have other keyserver types
278 available as well. Keyserver schemes are case-insensitive. After
279 the keyserver name, optional keyserver configuration options may
280 be provided. These are the same as the --keyserver-options of
281 gpg, but apply only to this particular keyserver.
282 Most keyservers synchronize with each other, so there is gener‐
284 ally no need to send keys to more than one server. Somes key‐
285 servers use round robin DNS to give a different keyserver each
286 time you use it.
287 If exactly two keyservers are configured and only one is a Tor
289 hidden service (.onion), Dirmngr selects the keyserver to use
290 depending on whether Tor is locally running or not. The check
291 for a running Tor is done for each new connection.
292 If no keyserver is explicitly configured, dirmngr will use the
294 built-in default of https://keyserver.ubuntu.com.
295 Windows users with a keyserver running on their Active Directory
297 may use the short form ldap:/// for name to access this direc‐
298 tory.
299 For accessing anonymous LDAP keyservers name is in general just
301 a ldaps://ldap.example.com. A BaseDN parameter should never be
302 specified. If authentication is required things are more com‐
303 plicated and two methods are available:
304 The modern method (since version 2.2.28) is to use the very same
306 syntax as used with the option --ldapserver. Please see over
307 there for details; here is an example:
308 keyserver ldap:ldap.example.com::uid=USERNAME,ou=GnuPG Users,
310 dc=example,dc=com:PASSWORD::starttls
311 The other method is to use a full URL for name; for example:
313 keyserver ldaps://ldap.example.com/????bindname=uid=USERNAME
315 %2Cou=GnuPG%20Users%2Cdc=example%2Cdc=com,password=PASSWORD
316 Put this all on one line without any spaces and keep the '%2C'
318 as given. Replace USERNAME, PASSWORD, and the 'dc' parts
319 according to the instructions received from your LDAP
320 administrator. Note that only simple authentication
321 (i.e. cleartext passwords) is supported and thus using ldaps is
322 strongly suggested (since 2.2.28 "ldaps" defaults to port 389
323 and uses STARTTLS). On Windows authentication via AD can be
324 requested by adding gpgNtds=1 after the fourth question
325 mark instead of the bindname and password parameter.
326 --nameserver ipaddr
331 In ``Tor mode'' Dirmngr uses a public resolver via Tor to re‐
332 solve DNS names. If the default public resolver, which is
333 8.8.8.8, shall not be used a different one can be given using
334 this option. Note that a numerical IP address must be given
335 (IPv6 or IPv4) and that no error checking is done for ipaddr.
336 --disable-ipv4
339 --disable-ipv6
341 Disable the use of all IPv4 or IPv6 addresses.
342 --disable-ldap
345 Entirely disables the use of LDAP.
346 --disable-http
349 Entirely disables the use of HTTP.
350 --ignore-http-dp
353 When looking for the location of a CRL, the to be tested cer‐
354 tificate usually contains so called CRL Distribution Point (DP)
355 entries which are URLs describing the way to access the CRL.
356 The first found DP entry is used. With this option all entries
357 using the HTTP scheme are ignored when looking for a suitable
358 DP.
359 --ignore-ldap-dp
362 This is similar to --ignore-http-dp but ignores entries using
363 the LDAP scheme. Both options may be combined resulting in ig‐
364 noring DPs entirely.
365 --ignore-ocsp-service-url
368 Ignore all OCSP URLs contained in the certificate. The effect
369 is to force the use of the default responder.
370 --honor-http-proxy
373 If the environment variable ‘http_proxy’ has been set, use its
374 value to access HTTP servers.
375 --http-proxy host[:port]
378 Use host and port to access HTTP servers. The use of this op‐
379 tion overrides the environment variable ‘http_proxy’ regardless
380 whether --honor-http-proxy has been set.
381 --ldap-proxy host[:port]
385 Use host and port to connect to LDAP servers. If port is omit‐
386 ted, port 389 (standard LDAP port) is used. This overrides any
387 specified host and port part in a LDAP URL and will also be used
388 if host and port have been omitted from the URL.
389 --only-ldap-proxy
392 Never use anything else but the LDAP "proxy" as configured with
393 --ldap-proxy. Usually dirmngr tries to use other configured
394 LDAP server if the connection using the "proxy" failed.
395 --ldapserverlist-file file
399 Read the list of LDAP servers to consult for CRLs and X.509 cer‐
400 tificates from file instead of the default per-user ldap server
401 list file. The default value for file is ‘dirm‐
402 ngr_ldapservers.conf’.
403 This server list file contains one LDAP server per line in the
405 format
406 hostname:port:username:password:base_dn:flags
408 Lines starting with a ‘#’ are comments.
410 Note that as usual all strings entered are expected to be UTF-8
412 encoded. Obviously this will lead to problems if the password
413 has originally been encoded as Latin-1. There is no other solu‐
414 tion here than to put such a password in the binary encoding
415 into the file (i.e. non-ascii characters won't show up read‐
416 able). ([The gpgconf tool might be helpful for frontends as it
417 enables editing this configuration file using percent-escaped
418 strings.])
419 --ldapserver spec
423 This is an alternative way to specify LDAP servers for CRL and
424 X.509 certificate retrieval. If this option is used the servers
425 configured in ‘dirmngr_ldapservers.conf’ (or the file given by
426 --ldapserverlist-file) are cleared. Note that ‘dirm‐
427 ngr_ldapservers.conf’ is not read again by a reload signal. How‐
428 ever, --ldapserver options are read again.
429 spec is either a proper LDAP URL or a colon delimited list of
431 the form
432 hostname:port:username:password:base_dn:flags:
434 with an optional prefix of ldap: (but without the two slashes
436 which would turn this into a proper LDAP URL). flags is a list
437 of one or more comma delimited keywords:
438 plain The default: Do not use a TLS secured connection at all;
440 the default port is 389.
441 starttls
443 Use STARTTLS to secure the connection; the default port
444 is 389.
445 ldaptls
447 Tunnel LDAP through a TLS connection; the default port is
448 636.
449 ntds On Windows authenticate the LDAP connection using the Ac‐
451 tive Directory with the current user.
452 areconly
454 On Windows use only the A or AAAA record when resolving
455 the LDAP server name.
456 Note that in an URL style specification the scheme ldaps:// refers to
458 STARTTLS and _not_ to LDAP-over-TLS.
459 --ldaptimeout secs
463 Specify the number of seconds to wait for an LDAP query before
464 timing out. The default are 15 seconds. 0 will never timeout.
465 --add-servers
469 This option makes dirmngr add any servers it discovers when val‐
470 idating certificates against CRLs to the internal list of
471 servers to consult for certificates and CRLs. This option
472 should in general not be used.
473 This option might be useful when trying to validate a certifi‐
475 cate that has a CRL distribution point that points to a server
476 that is not already listed in the ldapserverlist. Dirmngr will
477 always go to this server and try to download the CRL, but
478 chances are high that the certificate used to sign the CRL is
479 located on the same server. So if dirmngr doesn't add that new
480 server to list, it will often not be able to verify the signa‐
481 ture of the CRL unless the --add-servers option is used.
482 Caveat emptor: Using this option may enable denial-of-service
484 attacks and leak search requests to unknown third parties. This
485 is because arbitrary servers are added to the internal list of
486 LDAP servers which in turn is used for all unspecific LDAP
487 queries as well as a fallback for queries which did not return a
488 result.
489 --allow-ocsp
493 This option enables OCSP support if requested by the client.
494 OCSP requests are rejected by default because they may violate
496 the privacy of the user; for example it is possible to track the
497 time when a user is reading a mail.
498 --ocsp-responder url
502 Use url as the default OCSP Responder if the certificate does
503 not contain information about an assigned responder. Note, that
504 --ocsp-signer must also be set to a valid certificate.
505 --ocsp-signer fpr|file
508 Use the certificate with the fingerprint fpr to check the re‐
509 sponses of the default OCSP Responder. Alternatively a filename
510 can be given in which case the response is expected to be signed
511 by one of the certificates described in that file. Any argument
512 which contains a slash, dot or tilde is considered a filename.
513 Usual filename expansion takes place: A tilde at the start fol‐
514 lowed by a slash is replaced by the content of ‘HOME’, no slash
515 at start describes a relative filename which will be searched at
516 the home directory. To make sure that the file is searched in
517 the home directory, either prepend the name with "./" or use a
518 name which contains a dot.
519 If a response has been signed by a certificate described by
521 these fingerprints no further check upon the validity of this
522 certificate is done.
523 The format of the FILE is a list of SHA-1 fingerprint, one per
525 line with optional colons between the bytes. Empty lines and
526 lines prefix with a hash mark are ignored.
527 --ocsp-max-clock-skew n
531 The number of seconds a skew between the OCSP responder and them
532 local clock is accepted. Default is 600 (10 minutes).
533 --ocsp-max-period n
536 Seconds a response is at maximum considered valid after the time
537 given in the thisUpdate field. Default is 7776000 (90 days).
538 --ocsp-current-period n
541 The number of seconds an OCSP response is considered valid after
542 the time given in the NEXT_UPDATE datum. Default is 10800 (3
543 hours).
544 --max-replies n
548 Do not return more that n items in one query. The default is
549 10.
550 --ignore-cert-extension oid
553 Add oid to the list of ignored certificate extensions. The oid
554 is expected to be in dotted decimal form, like 2.5.29.3. This
555 option may be used more than once. Critical flagged certificate
556 extensions matching one of the OIDs in the list are treated as
557 if they are actually handled and thus the certificate won't be
558 rejected due to an unknown critical extension. Use this option
559 with care because extensions are usually flagged as critical for
560 a reason.
561 --ignore-cert fpr|file
564 Entirely ignore certificates with the fingerprint fpr. As an
565 alternative to the fingerprint a filename can be given in which
566 case all certificates described in that file are ignored. Any
567 argument which contains a slash, dot or tilde is considered a
568 filename. Usual filename expansion takes place: A tilde at the
569 start followed by a slash is replaced by the content of ‘HOME’,
570 no slash at start describes a relative filename which will be
571 searched at the home directory. To make sure that the file is
572 searched in the home directory, either prepend the name with
573 "./" or use a name which contains a dot. The format of such a
574 file is a list of SHA-1 fingerprint, one per line with optional
575 colons between the bytes. Empty lines and lines prefixed with a
576 hash mark are ignored.
577 This option is useful as a quick workaround to exclude certain
579 certificates from the system store.
580 --hkp-cacert file
584 Use the root certificates in file for verification of the TLS
585 certificates used with hkps (keyserver access over TLS). If the
586 file is in PEM format a suffix of .pem is expected for file.
587 This option may be given multiple times to add more root cer‐
588 tificates. Tilde expansion is supported.
589 If no hkp-cacert directive is present, dirmngr will use the sys‐
591 tem CAs.
592
595 Here is an example on how to show dirmngr's internal table of OpenPGP
596 keyserver addresses. The output is intended for debugging purposes and
597 not part of a defined API.
598 gpg-connect-agent --dirmngr 'keyserver --hosttable' /bye
600 To inhibit the use of a particular host you have noticed in one of the
602 keyserver pools, you may use
603 gpg-connect-agent --dirmngr 'keyserver --dead pgpkeys.bnd.de' /bye
605 The description of the keyserver command can be printed using
607 gpg-connect-agent --dirmngr 'help keyserver' /bye
609
615 Dirmngr makes use of several directories when running in daemon mode:
616 There are a few configuration files to control the operation of dirm‐
617 ngr. By default they may all be found in the current home directory
618 (see: [option --homedir]).
619 dirmngr.conf
623 This is the standard configuration file read by dirmngr on
624 startup. It may contain any valid long option; the leading two
625 dashes may not be entered and the option may not be abbreviated.
626 This file is also read after a SIGHUP however not all options
627 will actually have an effect. This default name may be changed
628 on the command line (see: [option --options]). You should
629 backup this file.
630 /etc/gnupg/trusted-certs
633 This directory should be filled with certificates of Root CAs
634 you are trusting in checking the CRLs and signing OCSP Re‐
635 sponses.
636 Usually these are the same certificates you use with the appli‐
638 cations making use of dirmngr. It is expected that each of
639 these certificate files contain exactly one DER encoded certifi‐
640 cate in a file with the suffix ‘.crt’ or ‘.der’. dirmngr reads
641 those certificates on startup and when given a SIGHUP. Certifi‐
642 cates which are not readable or do not make up a proper X.509
643 certificate are ignored; see the log file for details.
644 Applications using dirmngr (e.g. gpgsm) can request these cer‐
646 tificates to complete a trust chain in the same way as with the
647 extra-certs directory (see below).
648 Note that for OCSP responses the certificate specified using the
650 option --ocsp-signer is always considered valid to sign OCSP re‐
651 quests.
652 /etc/gnupg/extra-certs
655 This directory may contain extra certificates which are pre‐
656 loaded into the internal cache on startup. Applications using
657 dirmngr (e.g. gpgsm) can request cached certificates to complete
658 a trust chain. This is convenient in cases you have a couple
659 intermediate CA certificates or certificates usually used to
660 sign OCSP responses. These certificates are first tried before
661 going out to the net to look for them. These certificates must
662 also be DER encoded and suffixed with ‘.crt’ or ‘.der’.
663 ~/.gnupg/crls.d
666 This directory is used to store cached CRLs. The ‘crls.d’ part
667 will be created by dirmngr if it does not exists but you need to
668 make sure that the upper directory exists.
669 Several options control the use of trusted certificates for TLS and
672 CRLs. Here is an Overview on the use and origin of those Root CA cer‐
673 tificates:
674 System
677 These System root certificates are used by: FIXME
679 The origin of the system provided certificates depends on the
681 platform. On Windows all certificates from the Windows System
682 Stores ROOT and CA are used.
683 On other platforms the certificates are read from the first file
685 found form this list: ‘/etc/ssl/ca-bundle.pem’,
686 ‘/etc/ssl/certs/ca-certificates.crt’, ‘/etc/pki/tls/cert.pem’,
687 ‘/usr/local/share/certs/ca-root-nss.crt’, ‘/etc/ssl/cert.pem’.
688 GnuPG
691 The GnuPG specific certificates stored in the directory
693 ‘/etc/gnupg/trusted-certs’ are only used to validate CRLs.
694 OpenPGP keyserver
698 For accessing the OpenPGP keyservers the only certificates used
700 are those set with the configuration option hkp-cacert.
701 OpenPGP keyserver pool
704 This is usually only one certificate read from the file
706 ‘/usr/share/gnupg/gnupg/sks-keyservers.netCA.pem’. If this cer‐
707 tificate exists it is used to access the special keyservers
708 hkps.pool.sks-keyservers.net (or ‘hkps://keys.gnupg.net’).
709 Please note that gpgsm accepts Root CA certificates for its own pur‐
712 poses only if they are listed in its file ‘trustlist.txt’. dirmngr
713 does not make use of this list - except FIXME.
714
718 To be able to see diagnostics it is often useful to put at least the
719 following lines into the configuration file ‘~/gnupg/dirmngr.conf’:
720 log-file ~/dirmngr.log
722 verbose
723 You may want to check the log file to see whether all desired root CA
725 certificates are correctly loaded.
726 To be able to perform OCSP requests you probably want to add the line:
728 allow-ocsp
730 To make sure that new options are read or that after the installation
732 of a new GnuPG versions the right dirmngr version is running, you
733 should kill an existing dirmngr so that a new instance is started as
734 needed by the otehr components:
735 gpgconf --kill dirmngr
737 Direct interfaction with the dirmngr is possible by using the command
739 gpg-connect-agent --dirmngr
741 Enter HELP at the prompt to see a list of commands and enter HELP fol‐
743 lowed by a command name to get help on that command.
744
750 A running dirmngr may be controlled by signals, i.e. using the kill
751 command to send a signal to the process.
752 Here is a list of supported signals:
754 SIGHUP This signal flushes all internally cached CRLs as well as any
758 cached certificates. Then the certificate cache is reinitial‐
759 ized as on startup. Options are re-read from the configuration
760 file. Instead of sending this signal it is better to use
761 gpgconf --reload dirmngr
762 SIGTERM
765 Shuts down the process but waits until all current requests are
766 fulfilled. If the process has received 3 of these signals and
767 requests are still pending, a shutdown is forced. You may also
768 use
769 gpgconf --kill dirmngr
770 instead of this signal
771 SIGINT Shuts down the process immediately.
774 SIGUSR1
778 This prints some caching statistics to the log file.
779
782 gpgsm(1), dirmngr-client(1)
783 The full documentation for this tool is maintained as a Texinfo manual.
785 If GnuPG and the info program are properly installed at your site, the
786 command
787 info gnupg
789 should give you access to the complete manual including a menu struc‐
791 ture and an index.
792GnuPG 2.3.8 2022-10-07 DIRMNGR(8)