1DIRMNGR(8)                   GNU Privacy Guard 2.2                  DIRMNGR(8)
2
3
4

NAME

6       dirmngr - CRL and OCSP daemon
7

SYNOPSIS

9       dirmngr [options] command [args]
10
11

DESCRIPTION

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
20
21
22
23
24

COMMANDS

26       Commands are not distinguished from options except for  the  fact  that
27       only one command is allowed.
28
29
30       --version
31              Print  the program version and licensing information.  Note that
32              you cannot abbreviate this command.
33
34
35       --help, -h
36              Print a usage message summarizing the most  useful  command-line
37              options.  Note that you cannot abbreviate this command.
38
39
40       --dump-options
41              Print  a  list of all available options and commands.  Note that
42              you cannot abbreviate this command.
43
44
45       --server
46              Run in server mode and wait for  commands  on  the  stdin.   The
47              default  mode  is  to  create  a  socket and listen for commands
48              there.  This is only used for testing.
49
50
51       --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
57
58       --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 is useful when running under systemd or other sim‐
62              ilar process supervision schemes.  This option is not  supported
63              on Windows.
64
65
66       --list-crls
67              List  the  contents of the CRL cache on stdout. This is probably
68              only useful for debugging purposes.
69
70
71       --load-crl file
72              This command requires a filename as additional argument, and  it
73              will make Dirmngr try to import the CRL in file into it's cache.
74              Note, that this is only possible if Dirmngr is able to  retrieve
75              the  CA's  certificate directly by its own means.  In general it
76              is better to use gpgsm's --call-dirmngr loadcrl filename command
77              so that gpgsm can help dirmngr.
78
79
80       --fetch-crl url
81              This command requires an URL as additional argument, and it will
82              make dirmngr try to retrieve and import the CRL  from  that  url
83              into  it's cache.  This is mainly useful for debugging purposes.
84              The dirmngr-client provides the same feature for a running dirm‐
85              ngr.
86
87
88       --shutdown
89              This  commands  shuts down an running instance of Dirmngr.  This
90              command has currently no effect.
91
92
93       --flush
94              This command removes all  CRLs  from  Dirmngr's  cache.   Client
95              requests will thus trigger reading of fresh CRLs.
96
97

OPTIONS

99       Note  that all long options with the exception of --options and --home‐
100       dir may also be given in the configuration file after stripping off the
101       two leading dashes.
102
103
104
105       --options file
106              Reads  configuration  from file instead of from the default per-
107              user configuration file.   The  default  configuration  file  is
108              named ‘dirmngr.conf’ and expected in the home directory.
109
110
111       --homedir dir
112              Set  the name of the home directory to dir.  This option is only
113              effective when used on the command line.   The  default  is  the
114              directory  named  ‘.gnupg’  directly below the home directory of
115              the user unless the environment variable GNUPGHOME has been  set
116              in  which  case  its value will be used.  Many kinds of data are
117              stored within this directory.
118
119
120
121       -v
122
123       --verbose
124              Outputs additional information while running.  You can  increase
125              the  verbosity  by  giving  several verbose commands to dirmngr,
126              such as -vv.
127
128
129
130       --log-file file
131              Append all logging output to file.  This is very helpful in see‐
132              ing  what  the  agent  actually does.  Use ‘socket://’ to log to
133              socket.
134
135
136       --debug-level level
137              Select the debug level for investigating problems.  level may be
138              a numeric value or by a keyword:
139
140
141              none   No  debugging at all.  A value of less than 1 may be used
142                     instead of the keyword.
143
144              basic  Some basic debug messages.  A value between 1 and  2  may
145                     be used instead of the keyword.
146
147              advanced
148                     More verbose debug messages.  A value between 3 and 5 may
149                     be used instead of the keyword.
150
151              expert Even more detailed messages.  A value between 6 and 8 may
152                     be used instead of the keyword.
153
154              guru   All  of  the  debug messages you can get. A value greater
155                     than 8 may be used instead of the keyword.  The  creation
156                     of  hash  tracing files is only enabled if the keyword is
157                     used.
158
159       How these messages are mapped to the  actual  debugging  flags  is  not
160       specified  and may change with newer releases of this program. They are
161       however carefully selected to best aid in debugging.
162
163
164       --debug flags
165              Set debugging flags.  This option is only useful  for  debugging
166              and  its  behavior may change with a new release.  All flags are
167              or-ed and may be given in C syntax (e.g. 0x0042) or as  a  comma
168              separated  list  of  flag names.  To get a list of all supported
169              flags the single word "help" can be used.
170
171
172       --debug-all
173              Same as --debug=0xffffffff
174
175
176       --tls-debug level
177              Enable debugging of the TLS layer at level.  The details of  the
178              debug  level  depend  on the used TLS library and are not set in
179              stone.
180
181
182       --debug-wait n
183              When running in server mode, wait n seconds before entering  the
184              actual  processing  loop  and print the pid.  This gives time to
185              attach a debugger.
186
187
188       --disable-check-own-socket
189              On some platforms dirmngr is able to detect the removal  of  its
190              socket file and shutdown itself.  This option disable this self-
191              test for debugging purposes.
192
193
194       -s
195       --sh
196       -c
197       --csh  Format the info output in daemon mode for use with the  standard
198              Bourne  shell respective the C-shell. The default is to guess it
199              based on the environment variable SHELL which is in  almost  all
200              cases sufficient.
201
202
203       --force
204              Enabling  this  option  forces  loading of expired CRLs; this is
205              only useful for debugging.
206
207
208       --use-tor
209       --no-use-tor
210              The option --use-tor switches Dirmngr and thus GnuPG into  ``Tor
211              mode''  to  route  all network access via Tor (an anonymity net‐
212              work).  Certain other features are disabled in this  mode.   The
213              effect of --use-tor cannot be overridden by any other command or
214              even by reloading dirmngr.  The use of --no-use-tor disables the
215              use  of  Tor.   The  default is to use Tor if it is available on
216              startup or after reloading dirmngr.
217
218
219       --standard-resolver
220              This option forces the use of the system's standard DNS resolver
221              code.   This is mainly used for debugging.  Note that on Windows
222              a standard resolver is not used and all DNS access  will  return
223              the  error  ``Not  Implemented''  if this option is used.  Using
224              this together with enabled Tor  mode  returns  the  error  ``Not
225              Enabled''.
226
227
228       --recursive-resolver
229              When  possible  use  a  recursive  resolver  instead  of  a stub
230              resolver.
231
232
233       --resolver-timeout n
234              Set the timeout for the DNS resolver to N seconds.  The  default
235              are 30 seconds.
236
237
238       --connect-timeout n
239
240       --connect-quick-timeout n
241              Set  the timeout for HTTP and generic TCP connection attempts to
242              N seconds.  The value set with the quick variant  is  used  when
243              the  --quick  option  has been given to certain Assuan commands.
244              The quick value is capped at the value of  the  regular  connect
245              timeout.   The  default  values are 15 and 2 seconds.  Note that
246              the timeout values are for each connection attempt; the  connec‐
247              tion  code  will  attempt  to connect all addresses listed for a
248              server.
249
250
251       --listen-backlog n
252              Set the size of the queue for pending connections.  The  default
253              is 64.
254
255
256       --allow-version-check
257              Allow  Dirmngr  to  connect to https://versions.gnupg.org to get
258              the list of  current  software  versions.   If  this  option  is
259              enabled  the  list  is retrieved in case the local copy does not
260              exist or is older than 5 to 7 days.  See the option --query-swdb
261              of  the command gpgconf for more details.  Note, that regardless
262              of this option a version check can  always  be  triggered  using
263              this command:
264
265                gpg-connect-agent --dirmngr 'loadswdb --force' /bye
266
267
268
269       --keyserver name
270              Use  name as your keyserver.  This is the server that gpg commu‐
271              nicates with to receive keys, send keys, and  search  for  keys.
272              The   format  of  the  name  is  a  URI:  `scheme:[//]keyserver‐
273              name[:port]' The scheme is the type of keyserver: "hkp" for  the
274              HTTP (or compatible) keyservers, "ldap" for the LDAP keyservers,
275              or "mailto" for the Graff email keyserver. Note that  your  par‐
276              ticular  installation  of  GnuPG  may have other keyserver types
277              available as well. Keyserver schemes are case-insensitive. After
278              the keyserver name, optional keyserver configuration options may
279              be provided.  These are the same as the  --keyserver-options  of
280              gpg, but apply only to this particular keyserver.
281
282              Most  keyservers synchronize with each other, so there is gener‐
283              ally no need to send keys to more than one server. The keyserver
284              hkp://keys.gnupg.net  uses  round  robin DNS to give a different
285              keyserver each time you use it.
286
287              If exactly two keyservers are configured and only one is  a  Tor
288              hidden  service  (.onion),  Dirmngr selects the keyserver to use
289              depending on whether Tor is locally running or not.   The  check
290              for a running Tor is done for each new connection.
291
292              If  no  keyserver is explicitly configured, dirmngr will use the
293              built-in default of hkps://hkps.pool.sks-keyservers.net.
294
295
296       --nameserver ipaddr
297              In ``Tor mode'' Dirmngr  uses  a  public  resolver  via  Tor  to
298              resolve  DNS  names.   If  the default public resolver, which is
299              8.8.8.8, shall not be used a different one can  be  given  using
300              this  option.   Note  that  a numerical IP address must be given
301              (IPv6 or IPv4) and that no error checking is done for ipaddr.
302
303
304       --disable-ipv4
305
306       --disable-ipv6
307              Disable the use of all IPv4 or IPv6 addresses.
308
309
310       --disable-ldap
311              Entirely disables the use of LDAP.
312
313
314       --disable-http
315              Entirely disables the use of HTTP.
316
317
318       --ignore-http-dp
319              When looking for the location of a CRL, the to  be  tested  cer‐
320              tificate  usually contains so called CRL Distribution Point (DP)
321              entries which are URLs describing the way  to  access  the  CRL.
322              The  first found DP entry is used.  With this option all entries
323              using the HTTP scheme are ignored when looking  for  a  suitable
324              DP.
325
326
327       --ignore-ldap-dp
328              This  is  similar  to --ignore-http-dp but ignores entries using
329              the LDAP scheme.  Both options  may  be  combined  resulting  in
330              ignoring DPs entirely.
331
332
333       --ignore-ocsp-service-url
334              Ignore  all  OCSP URLs contained in the certificate.  The effect
335              is to force the use of the default responder.
336
337
338       --honor-http-proxy
339              If the environment variable ‘http_proxy’ has been set,  use  its
340              value to access HTTP servers.
341
342
343       --http-proxy host[:port]
344              Use  host  and  port  to  access  HTTP servers.  The use of this
345              option overrides the environment variable  ‘http_proxy’  regard‐
346              less whether --honor-http-proxy has been set.
347
348
349
350       --ldap-proxy host[:port]
351              Use  host and port to connect to LDAP servers.  If port is omit‐
352              ted, port 389 (standard LDAP port) is used.  This overrides  any
353              specified host and port part in a LDAP URL and will also be used
354              if host and port have been omitted from the URL.
355
356
357       --only-ldap-proxy
358              Never use anything else but the LDAP "proxy" as configured  with
359              --ldap-proxy.   Usually  dirmngr  tries  to use other configured
360              LDAP server if the connection using the "proxy" failed.
361
362
363
364       --ldapserverlist-file file
365              Read the list of LDAP servers to consult for CRLs  and  certifi‐
366              cates from file instead of the default per-user ldap server list
367              file. The default value for file is ‘dirmngr_ldapservers.conf’.
368
369              This server list file contains one LDAP server per line  in  the
370              format
371
372              hostname:port:username:password:base_dn
373
374              Lines starting with a  '#' are comments.
375
376              Note  that as usual all strings entered are expected to be UTF-8
377              encoded.  Obviously this will lead to problems if  the  password
378              has originally been encoded as Latin-1.  There is no other solu‐
379              tion here than to put such a password  in  the  binary  encoding
380              into  the  file  (i.e.  non-ascii characters won't show up read‐
381              able). ([The gpgconf tool might be helpful for frontends  as  it
382              enables  editing  this  configuration file using percent-escaped
383              strings.])
384
385
386
387       --ldaptimeout secs
388              Specify the number of seconds to wait for an LDAP  query  before
389              timing out.  The default are 15 seconds.  0 will never timeout.
390
391
392
393       --add-servers
394              This option makes dirmngr add any servers it discovers when val‐
395              idating certificates  against  CRLs  to  the  internal  list  of
396              servers to consult for certificates and CRLs.
397
398              This option is useful when trying to validate a certificate that
399              has a CRL distribution point that points to a server that is not
400              already  listed in the ldapserverlist. Dirmngr will always go to
401              this server and try to download the CRL, but  chances  are  high
402              that the certificate used to sign the CRL is located on the same
403              server. So if dirmngr doesn't add that new server  to  list,  it
404              will often not be able to verify the signature of the CRL unless
405              the --add-servers option is used.
406
407              Note: The current version of dirmngr has this option disabled by
408              default.
409
410
411
412       --allow-ocsp
413              This option enables OCSP support if requested by the client.
414
415              OCSP  requests  are rejected by default because they may violate
416              the privacy of the user; for example it is possible to track the
417              time when a user is reading a mail.
418
419
420
421       --ocsp-responder url
422              Use  url  as  the default OCSP Responder if the certificate does
423              not contain information about an assigned responder.  Note, that
424              --ocsp-signer must also be set to a valid certificate.
425
426
427       --ocsp-signer fpr|file
428              Use  the  certificate  with  the  fingerprint  fpr  to check the
429              responses of the default OCSP Responder.  Alternatively a  file‐
430              name  can  be given in which case the response is expected to be
431              signed by one of the certificates described in that  file.   Any
432              argument  which  contains  a slash, dot or tilde is considered a
433              filename.  Usual filename expansion takes place: A tilde at  the
434              start  followed by a slash is replaced by the content of ‘HOME’,
435              no slash at start describes a relative filename  which  will  be
436              searched  at  the home directory.  To make sure that the file is
437              searched in the home directory, either  prepend  the  name  with
438              "./" or use a name which contains a dot.
439
440              If  a  response  has  been  signed by a certificate described by
441              these fingerprints no further check upon the  validity  of  this
442              certificate is done.
443
444              The  format  of the FILE is a list of SHA-1 fingerprint, one per
445              line with optional colons between the bytes.   Empty  lines  and
446              lines prefix with a hash mark are ignored.
447
448
449
450       --ocsp-max-clock-skew n
451              The number of seconds a skew between the OCSP responder and them
452              local clock is accepted.  Default is 600 (10 minutes).
453
454
455       --ocsp-max-period n
456              Seconds a response is at maximum considered valid after the time
457              given in the thisUpdate field.  Default is 7776000 (90 days).
458
459
460       --ocsp-current-period n
461              The number of seconds an OCSP response is considered valid after
462              the time given in the NEXT_UPDATE datum.  Default  is  10800  (3
463              hours).
464
465
466
467       --max-replies n
468              Do  not  return  more that n items in one query.  The default is
469              10.
470
471
472       --ignore-cert-extension oid
473              Add oid to the list of ignored certificate extensions.  The  oid
474              is  expected  to be in dotted decimal form, like 2.5.29.3.  This
475              option may be used more than once.  Critical flagged certificate
476              extensions  matching  one of the OIDs in the list are treated as
477              if they are actually handled and thus the certificate  won't  be
478              rejected  due to an unknown critical extension.  Use this option
479              with care because extensions are usually flagged as critical for
480              a reason.
481
482
483       --hkp-cacert file
484              Use  the  root  certificates in file for verification of the TLS
485              certificates used with hkps (keyserver access over TLS).  If the
486              file  is  in  PEM  format a suffix of .pem is expected for file.
487              This option may be given multiple times to add  more  root  cer‐
488              tificates.  Tilde expansion is supported.
489
490              If  no hkp-cacert directive is present, dirmngr will make a rea‐
491              sonable choice: if the keyserver in question is the special pool
492              hkps.pool.sks-keyservers.net,  it will use the bundled root cer‐
493              tificate for that pool.  Otherwise, it will use the system CAs.
494
495

EXAMPLES

497       Here is an example on how to show dirmngr's internal table  of  OpenPGP
498       keyserver addresses.  The output is intended for debugging purposes and
499       not part of a defined API.
500
501           gpg-connect-agent --dirmngr 'keyserver --hosttable' /bye
502
503       To inhibit the use of a particular host you have noticed in one of  the
504       keyserver pools, you may use
505
506          gpg-connect-agent --dirmngr 'keyserver --dead pgpkeys.bnd.de' /bye
507
508       The description of the keyserver command can be printed using
509
510          gpg-connect-agent --dirmngr 'help keyserver' /bye
511
512
513
514
515

FILES

517       Dirmngr  makes  use of several directories when running in daemon mode:
518       There are a few configuration files whih control the operation of dirm‐
519       ngr.   By  default  they may all be found in the current home directory
520       (see: [option --homedir]).
521
522
523
524       dirmngr.conf
525              This is the standard  configuration  file  read  by  dirmngr  on
526              startup.   It may contain any valid long option; the leading two
527              dashes may not be entered and the option may not be abbreviated.
528              This  file  is  also read after a SIGHUP however not all options
529              will actually have an effect.  This default name may be  changed
530              on  the  command  line  (see:  [option  --options]).  You should
531              backup this file.
532
533
534       /etc/gnupg/trusted-certs
535              This directory should be filled with certificates  of  Root  CAs
536              you   are  trusting  in  checking  the  CRLs  and  signing  OCSP
537              Responses.
538
539              Usually these are the same certificates you use with the  appli‐
540              cations  making  use  of  dirmngr.   It is expected that each of
541              these certificate files contain exactly one DER encoded certifi‐
542              cate  in a file with the suffix ‘.crt’ or ‘.der’.  dirmngr reads
543              those certificates on startup and when given a SIGHUP.  Certifi‐
544              cates  which  are  not readable or do not make up a proper X.509
545              certificate are ignored; see the log file for details.
546
547              Applications using dirmngr (e.g. gpgsm) can request  these  cer‐
548              tificates  to complete a trust chain in the same way as with the
549              extra-certs directory (see below).
550
551              Note that for OCSP responses the certificate specified using the
552              option  --ocsp-signer  is  always  considered valid to sign OCSP
553              requests.
554
555
556       /etc/gnupg/extra-certs
557              This directory may contain extra  certificates  which  are  pre‐
558              loaded  into  the  internal cache on startup. Applications using
559              dirmngr (e.g. gpgsm) can request cached certificates to complete
560              a  trust  chain.   This is convenient in cases you have a couple
561              intermediate CA certificates or  certificates  usually  used  to
562              sign  OCSP responses.  These certificates are first tried before
563              going out to the net to look for them.  These certificates  must
564              also be DER encoded and suffixed with ‘.crt’ or ‘.der’.
565
566
567       ~/.gnupg/crls.d
568              This  directory is used to store cached CRLs.  The ‘crls.d’ part
569              will be created by dirmngr if it does not exists but you need to
570              make sure that the upper directory exists.
571
572
573

SIGNALS

575       A  running  dirmngr  may  be controlled by signals, i.e. using the kill
576       command to send a signal to the process.
577
578       Here is a list of supported signals:
579
580
581
582       SIGHUP This signal flushes all internally cached CRLs as  well  as  any
583              cached  certificates.   Then the certificate cache is reinitial‐
584              ized as on startup.  Options are re-read from the  configuration
585              file.  Instead of sending this signal it is better to use
586         gpgconf --reload dirmngr
587
588
589       SIGTERM
590              Shuts  down the process but waits until all current requests are
591              fulfilled.  If the process has received 3 of these  signals  and
592              requests  are still pending, a shutdown is forced.  You may also
593              use
594         gpgconf --kill dirmngr
595       instead of this signal
596
597
598       SIGINT Shuts down the process immediately.
599
600
601
602       SIGUSR1
603              This prints some caching statistics to the log file.
604
605

SEE ALSO

607       gpgsm(1), dirmngr-client(1)
608
609       The full documentation for this tool is maintained as a Texinfo manual.
610       If  GnuPG and the info program are properly installed at your site, the
611       command
612
613         info gnupg
614
615       should give you access to the complete manual including a  menu  struc‐
616       ture and an index.
617
618
619
620
621
622GnuPG 2.2.20                      2020-03-18                        DIRMNGR(8)
Impressum