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 Note that in an URL style specification the scheme ldaps:// refers to
454 STARTTLS and _not_ to LDAP-over-TLS.
455 --ldaptimeout secs
459 Specify the number of seconds to wait for an LDAP query before
460 timing out. The default are 15 seconds. 0 will never timeout.
461 --add-servers
465 This option makes dirmngr add any servers it discovers when val‐
466 idating certificates against CRLs to the internal list of
467 servers to consult for certificates and CRLs. This option
468 should in general not be used.
469 This option might be useful when trying to validate a certifi‐
471 cate that has a CRL distribution point that points to a server
472 that is not already listed in the ldapserverlist. Dirmngr will
473 always go to this server and try to download the CRL, but
474 chances are high that the certificate used to sign the CRL is
475 located on the same server. So if dirmngr doesn't add that new
476 server to list, it will often not be able to verify the signa‐
477 ture of the CRL unless the --add-servers option is used.
478 Caveat emptor: Using this option may enable denial-of-service
480 attacks and leak search requests to unknown third parties. This
481 is because arbitrary servers are added to the internal list of
482 LDAP servers which in turn is used for all unspecific LDAP
483 queries as well as a fallback for queries which did not return a
484 result.
485 --allow-ocsp
489 This option enables OCSP support if requested by the client.
490 OCSP requests are rejected by default because they may violate
492 the privacy of the user; for example it is possible to track the
493 time when a user is reading a mail.
494 --ocsp-responder url
498 Use url as the default OCSP Responder if the certificate does
499 not contain information about an assigned responder. Note, that
500 --ocsp-signer must also be set to a valid certificate.
501 --ocsp-signer fpr|file
504 Use the certificate with the fingerprint fpr to check the re‐
505 sponses of the default OCSP Responder. Alternatively a filename
506 can be given in which case the response is expected to be signed
507 by one of the certificates described in that file. Any argument
508 which contains a slash, dot or tilde is considered a filename.
509 Usual filename expansion takes place: A tilde at the start fol‐
510 lowed by a slash is replaced by the content of ‘HOME’, no slash
511 at start describes a relative filename which will be searched at
512 the home directory. To make sure that the file is searched in
513 the home directory, either prepend the name with "./" or use a
514 name which contains a dot.
515 If a response has been signed by a certificate described by
517 these fingerprints no further check upon the validity of this
518 certificate is done.
519 The format of the FILE is a list of SHA-1 fingerprint, one per
521 line with optional colons between the bytes. Empty lines and
522 lines prefix with a hash mark are ignored.
523 --ocsp-max-clock-skew n
527 The number of seconds a skew between the OCSP responder and them
528 local clock is accepted. Default is 600 (10 minutes).
529 --ocsp-max-period n
532 Seconds a response is at maximum considered valid after the time
533 given in the thisUpdate field. Default is 7776000 (90 days).
534 --ocsp-current-period n
537 The number of seconds an OCSP response is considered valid after
538 the time given in the NEXT_UPDATE datum. Default is 10800 (3
539 hours).
540 --max-replies n
544 Do not return more that n items in one query. The default is
545 10.
546 --ignore-cert-extension oid
549 Add oid to the list of ignored certificate extensions. The oid
550 is expected to be in dotted decimal form, like 2.5.29.3. This
551 option may be used more than once. Critical flagged certificate
552 extensions matching one of the OIDs in the list are treated as
553 if they are actually handled and thus the certificate won't be
554 rejected due to an unknown critical extension. Use this option
555 with care because extensions are usually flagged as critical for
556 a reason.
557 --ignore-cert fpr|file
560 Entirely ignore certificates with the fingerprint fpr. As an
561 alternative to the fingerprint a filename can be given in which
562 case all certificates described in that file are ignored. Any
563 argument which contains a slash, dot or tilde is considered a
564 filename. Usual filename expansion takes place: A tilde at the
565 start followed by a slash is replaced by the content of ‘HOME’,
566 no slash at start describes a relative filename which will be
567 searched at the home directory. To make sure that the file is
568 searched in the home directory, either prepend the name with
569 "./" or use a name which contains a dot. The format of such a
570 file is a list of SHA-1 fingerprint, one per line with optional
571 colons between the bytes. Empty lines and lines prefixed with a
572 hash mark are ignored.
573 This option is useful as a quick workaround to exclude certain
575 certificates from the system store.
576 --hkp-cacert file
580 Use the root certificates in file for verification of the TLS
581 certificates used with hkps (keyserver access over TLS). If the
582 file is in PEM format a suffix of .pem is expected for file.
583 This option may be given multiple times to add more root cer‐
584 tificates. Tilde expansion is supported.
585 If no hkp-cacert directive is present, dirmngr will use the sys‐
587 tem CAs.
588
591 Here is an example on how to show dirmngr's internal table of OpenPGP
592 keyserver addresses. The output is intended for debugging purposes and
593 not part of a defined API.
594 gpg-connect-agent --dirmngr 'keyserver --hosttable' /bye
596 To inhibit the use of a particular host you have noticed in one of the
598 keyserver pools, you may use
599 gpg-connect-agent --dirmngr 'keyserver --dead pgpkeys.bnd.de' /bye
601 The description of the keyserver command can be printed using
603 gpg-connect-agent --dirmngr 'help keyserver' /bye
605
611 Dirmngr makes use of several directories when running in daemon mode:
612 There are a few configuration files to control the operation of dirm‐
613 ngr. By default they may all be found in the current home directory
614 (see: [option --homedir]).
615 dirmngr.conf
619 This is the standard configuration file read by dirmngr on
620 startup. It may contain any valid long option; the leading two
621 dashes may not be entered and the option may not be abbreviated.
622 This file is also read after a SIGHUP however not all options
623 will actually have an effect. This default name may be changed
624 on the command line (see: [option --options]). You should
625 backup this file.
626 /etc/gnupg/trusted-certs
629 This directory should be filled with certificates of Root CAs
630 you are trusting in checking the CRLs and signing OCSP Re‐
631 sponses.
632 Usually these are the same certificates you use with the appli‐
634 cations making use of dirmngr. It is expected that each of
635 these certificate files contain exactly one DER encoded certifi‐
636 cate in a file with the suffix ‘.crt’ or ‘.der’. dirmngr reads
637 those certificates on startup and when given a SIGHUP. Certifi‐
638 cates which are not readable or do not make up a proper X.509
639 certificate are ignored; see the log file for details.
640 Applications using dirmngr (e.g. gpgsm) can request these cer‐
642 tificates to complete a trust chain in the same way as with the
643 extra-certs directory (see below).
644 Note that for OCSP responses the certificate specified using the
646 option --ocsp-signer is always considered valid to sign OCSP re‐
647 quests.
648 /etc/gnupg/extra-certs
651 This directory may contain extra certificates which are pre‐
652 loaded into the internal cache on startup. Applications using
653 dirmngr (e.g. gpgsm) can request cached certificates to complete
654 a trust chain. This is convenient in cases you have a couple
655 intermediate CA certificates or certificates usually used to
656 sign OCSP responses. These certificates are first tried before
657 going out to the net to look for them. These certificates must
658 also be DER encoded and suffixed with ‘.crt’ or ‘.der’.
659 ~/.gnupg/crls.d
662 This directory is used to store cached CRLs. The ‘crls.d’ part
663 will be created by dirmngr if it does not exists but you need to
664 make sure that the upper directory exists.
665 Several options control the use of trusted certificates for TLS and
668 CRLs. Here is an Overview on the use and origin of those Root CA cer‐
669 tificates:
670 System
673 These System root certificates are used by: FIXME
675 The origin of the system provided certificates depends on the
677 platform. On Windows all certificates from the Windows System
678 Stores ROOT and CA are used.
679 On other platforms the certificates are read from the first file
681 found form this list: ‘/etc/ssl/ca-bundle.pem’,
682 ‘/etc/ssl/certs/ca-certificates.crt’, ‘/etc/pki/tls/cert.pem’,
683 ‘/usr/local/share/certs/ca-root-nss.crt’, ‘/etc/ssl/cert.pem’.
684 GnuPG
687 The GnuPG specific certificates stored in the directory
689 ‘/etc/gnupg/trusted-certs’ are only used to validate CRLs.
690 OpenPGP keyserver
694 For accessing the OpenPGP keyservers the only certificates used
696 are those set with the configuration option hkp-cacert.
697 OpenPGP keyserver pool
700 This is usually only one certificate read from the file
702 ‘/usr/share/gnupg/gnupg/sks-keyservers.netCA.pem’. If this cer‐
703 tificate exists it is used to access the special keyservers
704 hkps.pool.sks-keyservers.net (or ‘hkps://keys.gnupg.net’).
705 Please note that gpgsm accepts Root CA certificates for its own pur‐
708 poses only if they are listed in its file ‘trustlist.txt’. dirmngr
709 does not make use of this list - except FIXME.
710
714 To be able to see diagnostics it is often useful to put at least the
715 following lines into the configuration file ‘~/gnupg/dirmngr.conf’:
716 log-file ~/dirmngr.log
718 verbose
719 You may want to check the log file to see whether all desired root CA
721 certificates are correctly loaded.
722 To be able to perform OCSP requests you probably want to add the line:
724 allow-ocsp
726 To make sure that new options are read or that after the installation
728 of a new GnuPG versions the right dirmngr version is running, you
729 should kill an existing dirmngr so that a new instance is started as
730 needed by the otehr components:
731 gpgconf --kill dirmngr
733 Direct interfaction with the dirmngr is possible by using the command
735 gpg-connect-agent --dirmngr
737 Enter HELP at the prompt to see a list of commands and enter HELP fol‐
739 lowed by a command name to get help on that command.
740
746 A running dirmngr may be controlled by signals, i.e. using the kill
747 command to send a signal to the process.
748 Here is a list of supported signals:
750 SIGHUP This signal flushes all internally cached CRLs as well as any
754 cached certificates. Then the certificate cache is reinitial‐
755 ized as on startup. Options are re-read from the configuration
756 file. Instead of sending this signal it is better to use
757 gpgconf --reload dirmngr
758 SIGTERM
761 Shuts down the process but waits until all current requests are
762 fulfilled. If the process has received 3 of these signals and
763 requests are still pending, a shutdown is forced. You may also
764 use
765 gpgconf --kill dirmngr
766 instead of this signal
767 SIGINT Shuts down the process immediately.
770 SIGUSR1
774 This prints some caching statistics to the log file.
775
778 gpgsm(1), dirmngr-client(1)
779 The full documentation for this tool is maintained as a Texinfo manual.
781 If GnuPG and the info program are properly installed at your site, the
782 command
783 info gnupg
785 should give you access to the complete manual including a menu struc‐
787 ture and an index.
788GnuPG 2.3.7 2022-06-27 DIRMNGR(8)