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 be reloading gpg-agent.  The use of  --no-use-tor  disables
215              the 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 function is used.
224
225
226       --recursive-resolver
227              When  possible  use  a  recursive  resolver  instead  of  a stub
228              resolver.
229
230
231       --resolver-timeout n
232              Set the timeout for the DNS resolver to N seconds.  The  default
233              are 30 seconds.
234
235
236       --connect-timeout n
237
238       --connect-quick-timeout n
239              Set  the timeout for HTTP and generic TCP connection attempts to
240              N seconds.  The value set with the quick variant  is  used  when
241              the  --quick  option  has been given to certain Assuan commands.
242              The quick value is capped at the value of  the  regular  connect
243              timeout.   The  default  values are 15 and 2 seconds.  Note that
244              the timeout values are for each connection attempt; the  connec‐
245              tion  code  will  attempt  to connect all addresses listed for a
246              server.
247
248
249       --listen-backlog n
250              Set the size of the queue for pending connections.  The  default
251              is 64.
252
253
254       --allow-version-check
255              Allow  Dirmngr  to  connect to https://versions.gnupg.org to get
256              the list of  current  software  versions.   If  this  option  is
257              enabled  the  list  is retrieved in case the local copy does not
258              exist or is older than 5 to 7 days.  See the option --query-swdb
259              of  the command gpgconf for more details.  Note, that regardless
260              of this option a version check can  always  be  triggered  using
261              this command:
262
263                gpg-connect-agent --dirmngr 'loadswdb --force' /bye
264
265
266
267       --keyserver name
268              Use  name as your keyserver.  This is the server that gpg commu‐
269              nicates with to receive keys, send keys, and  search  for  keys.
270              The   format  of  the  name  is  a  URI:  `scheme:[//]keyserver‐
271              name[:port]' The scheme is the type of keyserver: "hkp" for  the
272              HTTP (or compatible) keyservers, "ldap" for the LDAP keyservers,
273              or "mailto" for the Graff email keyserver. Note that  your  par‐
274              ticular  installation  of  GnuPG  may have other keyserver types
275              available as well. Keyserver schemes are case-insensitive. After
276              the keyserver name, optional keyserver configuration options may
277              be provided.  These are the same as the  --keyserver-options  of
278              gpg, but apply only to this particular keyserver.
279
280              Most  keyservers synchronize with each other, so there is gener‐
281              ally no need to send keys to more than one server. The keyserver
282              hkp://keys.gnupg.net  uses  round  robin DNS to give a different
283              keyserver each time you use it.
284
285              If exactly two keyservers are configured and only one is  a  Tor
286              hidden  service  (.onion),  Dirmngr selects the keyserver to use
287              depending on whether Tor is locally running or not.   The  check
288              for a running Tor is done for each new connection.
289
290              If  no  keyserver is explicitly configured, dirmngr will use the
291              built-in default of hkps://hkps.pool.sks-keyservers.net.
292
293
294       --nameserver ipaddr
295              In ``Tor mode'' Dirmngr  uses  a  public  resolver  via  Tor  to
296              resolve  DNS  names.   If  the default public resolver, which is
297              8.8.8.8, shall not be used a different one can  be  given  using
298              this  option.   Note  that  a numerical IP address must be given
299              (IPv6 or IPv4) and that no error checking is done for ipaddr.
300
301
302       --disable-ipv4
303
304       --disable-ipv6
305              Disable the use of all IPv4 or IPv6 addresses.
306
307
308       --disable-ldap
309              Entirely disables the use of LDAP.
310
311
312       --disable-http
313              Entirely disables the use of HTTP.
314
315
316       --ignore-http-dp
317              When looking for the location of a CRL, the to  be  tested  cer‐
318              tificate  usually contains so called CRL Distribution Point (DP)
319              entries which are URLs describing the way  to  access  the  CRL.
320              The  first found DP entry is used.  With this option all entries
321              using the HTTP scheme are ignored when looking  for  a  suitable
322              DP.
323
324
325       --ignore-ldap-dp
326              This  is  similar  to --ignore-http-dp but ignores entries using
327              the LDAP scheme.  Both options  may  be  combined  resulting  in
328              ignoring DPs entirely.
329
330
331       --ignore-ocsp-service-url
332              Ignore  all  OCSP URLs contained in the certificate.  The effect
333              is to force the use of the default responder.
334
335
336       --honor-http-proxy
337              If the environment variable ‘http_proxy’ has been set,  use  its
338              value to access HTTP servers.
339
340
341       --http-proxy host[:port]
342              Use  host  and  port  to  access  HTTP servers.  The use of this
343              option overrides the environment variable  ‘http_proxy’  regard‐
344              less whether --honor-http-proxy has been set.
345
346
347
348       --ldap-proxy host[:port]
349              Use  host and port to connect to LDAP servers.  If port is omit‐
350              ted, port 389 (standard LDAP port) is used.  This overrides  any
351              specified host and port part in a LDAP URL and will also be used
352              if host and port have been omitted from the URL.
353
354
355       --only-ldap-proxy
356              Never use anything else but the LDAP "proxy" as configured  with
357              --ldap-proxy.   Usually  dirmngr  tries  to use other configured
358              LDAP server if the connection using the "proxy" failed.
359
360
361
362       --ldapserverlist-file file
363              Read the list of LDAP servers to consult for CRLs  and  certifi‐
364              cates from file instead of the default per-user ldap server list
365              file. The default value for file is ‘dirmngr_ldapservers.conf’.
366
367              This server list file contains one LDAP server per line  in  the
368              format
369
370              hostname:port:username:password:base_dn
371
372              Lines starting with a  '#' are comments.
373
374              Note  that as usual all strings entered are expected to be UTF-8
375              encoded.  Obviously this will lead to problems if  the  password
376              has originally been encoded as Latin-1.  There is no other solu‐
377              tion here than to put such a password  in  the  binary  encoding
378              into  the  file  (i.e.  non-ascii characters won't show up read‐
379              able). ([The gpgconf tool might be helpful for frontends  as  it
380              enables  editing  this  configuration file using percent-escaped
381              strings.])
382
383
384
385       --ldaptimeout secs
386              Specify the number of seconds to wait for an LDAP  query  before
387              timing out.  The default are 15 seconds.  0 will never timeout.
388
389
390
391       --add-servers
392              This option makes dirmngr add any servers it discovers when val‐
393              idating certificates  against  CRLs  to  the  internal  list  of
394              servers to consult for certificates and CRLs.
395
396              This option is useful when trying to validate a certificate that
397              has a CRL distribution point that points to a server that is not
398              already  listed in the ldapserverlist. Dirmngr will always go to
399              this server and try to download the CRL, but  chances  are  high
400              that the certificate used to sign the CRL is located on the same
401              server. So if dirmngr doesn't add that new server  to  list,  it
402              will often not be able to verify the signature of the CRL unless
403              the --add-servers option is used.
404
405              Note: The current version of dirmngr has this option disabled by
406              default.
407
408
409
410       --allow-ocsp
411              This option enables OCSP support if requested by the client.
412
413              OCSP  requests  are rejected by default because they may violate
414              the privacy of the user; for example it is possible to track the
415              time when a user is reading a mail.
416
417
418
419       --ocsp-responder url
420              Use  url  as  the default OCSP Responder if the certificate does
421              not contain information about an assigned responder.  Note, that
422              --ocsp-signer must also be set to a valid certificate.
423
424
425       --ocsp-signer fpr|file
426              Use  the  certificate  with  the  fingerprint  fpr  to check the
427              responses of the default OCSP Responder.  Alternatively a  file‐
428              name  can  be given in which case the response is expected to be
429              signed by one of the certificates described in that  file.   Any
430              argument  which  contains  a slash, dot or tilde is considered a
431              filename.  Usual filename expansion takes place: A tilde at  the
432              start  followed by a slash is replaced by the content of ‘HOME’,
433              no slash at start describes a relative filename  which  will  be
434              searched  at  the home directory.  To make sure that the file is
435              searched in the home directory, either  prepend  the  name  with
436              "./" or use a name which contains a dot.
437
438              If  a  response  has  been  signed by a certificate described by
439              these fingerprints no further check upon the  validity  of  this
440              certificate is done.
441
442              The  format  of the FILE is a list of SHA-1 fingerprint, one per
443              line with optional colons between the bytes.   Empty  lines  and
444              lines prefix with a hash mark are ignored.
445
446
447
448       --ocsp-max-clock-skew n
449              The number of seconds a skew between the OCSP responder and them
450              local clock is accepted.  Default is 600 (10 minutes).
451
452
453       --ocsp-max-period n
454              Seconds a response is at maximum considered valid after the time
455              given in the thisUpdate field.  Default is 7776000 (90 days).
456
457
458       --ocsp-current-period n
459              The number of seconds an OCSP response is considered valid after
460              the time given in the NEXT_UPDATE datum.  Default  is  10800  (3
461              hours).
462
463
464
465       --max-replies n
466              Do  not  return  more that n items in one query.  The default is
467              10.
468
469
470       --ignore-cert-extension oid
471              Add oid to the list of ignored certificate extensions.  The  oid
472              is  expected  to be in dotted decimal form, like 2.5.29.3.  This
473              option may be used more than once.  Critical flagged certificate
474              extensions  matching  one of the OIDs in the list are treated as
475              if they are actually handled and thus the certificate  won't  be
476              rejected  due to an unknown critical extension.  Use this option
477              with care because extensions are usually flagged as critical for
478              a reason.
479
480
481       --hkp-cacert file
482              Use  the  root  certificates in file for verification of the TLS
483              certificates used with hkps (keyserver access over TLS).  If the
484              file  is  in  PEM  format a suffix of .pem is expected for file.
485              This option may be given multiple times to add  more  root  cer‐
486              tificates.  Tilde expansion is supported.
487
488              If  no hkp-cacert directive is present, dirmngr will make a rea‐
489              sonable choice: if the keyserver in question is the special pool
490              hkps.pool.sks-keyservers.net,  it will use the bundled root cer‐
491              tificate for that pool.  Otherwise, it will use the system CAs.
492
493

EXAMPLES

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

FILES

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

SIGNALS

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

SEE ALSO

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