1DIRMNGR(1) GNU Privacy Guard DIRMNGR(1)
2
6 dirmngr - CRL and OCSP daemon
7
9 dirmngr [options] command [args]
10
14 Dirmngr is a server for managing and downloading certificate revocation
15 lists (CRLs) for X.509 certificates and for downloading the certifi‐
16 cates themselves. Dirmngr also handles OCSP requests as an alternative
17 to CRLs. Dirmngr is either invoked internally by gpgsm (from GnuPG 2)
18 or when running as a system daemon through the dirmngr-client tool.
19
22 Commands are not distinguished from options execpt for the fact that
23 only one command is allowed.
24 --version
27 Print the program version and licensing information. Note that
28 you can abbreviate this command.
29 --help, -h
32 Print a usage message summarizing the most useful command-line
33 options. Not that you can abbreviate this command.
34 --server
37 Run in server mode and wait for commands on the stdin. The
38 default mode is to create a socket and listen for commands
39 there.
40 --daemon
43 Run in background daemon mode and listen for commands on a
44 socket. Note that this also changes the default home directory
45 and enables the internal certificate validation code.
46 --list-crls
49 List the contents of the CRL cache on stdout. This is probably
50 only useful for debugging purposes.
51 --load-crl file
54 This command requires a filename as additional argument, and it
55 will make dirmngr try to import the CRL in file into it's cache.
56 Note, that this is only possible if Dirmngr is able to retrieve
57 the CA's certificate directly by its own means. In general it
58 is better to use gpgsm's --call-dirmngr loadcrl filename command
59 so that gpgsm can help dirmngr.
60 --fetch-crl url
63 This command requires an URL as additional argument, and it will
64 make dirmngr try to retrieve an import the CRL from that url
65 into it's cache. This is mainly useful for debugging purposes.
66 The dirmngr-client provides the same feature for a running dirm‐
67 ngr.
68 --shutdown
71 This commands shuts down an running instance of Dirmngr. This
72 command has corrently no effect.
73 --flush
76 This command removes all CRLs from Dirmngr's cache. Client
77 requests will thus trigger reading of fresh CRLs.
78
83 --options file
84 Reads configuration from file instead of from the default per-
85 user configuration file. The default configuration file is
86 named `dirmngr.conf' and expected in the home directory.
87 --homedir dir
90 Set the name of the home directory to dir. This option is only
91 effective when used on the command line. The default depends on
92 the running mode:
93 With --daemon given on the commandline
97 the directory named `/etc/dirmngr' for configuration
98 files, `/var/lib/dirmngr/' for extra data and
99 `/var/cache/dirmngr' for cached CRLs.
100 Without --daemon given on the commandline
103 the directory named `.gnupg' directly below the home
104 directory of the user unless the environment variable
105 GNUPGHOME has been set in which case its value will be
106 used. All kind of data is stored below this directory.
107 -v
111 --verbose
113 Outputs additional information while running. You can increase
114 the verbosity by giving several verbose commands to dirmngr,
115 such as -vv.
116 --log-file file
121 Append all logging output to file. This is very helpful in see‐
122 ing what the agent actually does.
123 --debug-level level
126 Select the debug level for investigating problems. level may be
127 a numeric value or by a keyword:
128 none No debugging at all. A value of less than 1 may be used
131 instead of the keyword.
132 basic Some basic debug messages. A value between 1 and 2 may
134 be used instead of the keyword.
135 advanced
137 More verbose debug messages. A value between 3 and 5 may
138 be used instead of the keyword.
139 expert Even more detailed messages. A value between 6 and 8 may
141 be used instead of the keyword.
142 guru All of the debug messages you can get. A value greater
144 than 8 may be used instead of the keyword. The creation
145 of hash tracing files is only enabled if the keyword is
146 used.
147 How these messages are mapped to the actual debugging flags is not
149 specified and may change with newer releases of this program. They are
150 however carefully selected to best aid in debugging.
151 --debug flags
154 This option is only useful for debugging and the behaviour may
155 change at any time without notice. FLAGS are bit encoded and
156 may be given in usual C-Syntax.
157 --debug-all
160 Same as --debug=0xffffffff
161 --debug-wait n
164 When running in server mode, wait n seconds before entering the
165 actual processing loop and print the pid. This gives time to
166 attach a debugger.
167 -s
170 --sh
172 -c
174 --csh Format the info output in daemon mode for use with the standard
176 Bourne shell respective the C-shell . The default ist to guess
177 it based on the environment variable SHELL which is in almost
178 all cases sufficient.
179 --force
182 Enabling this option forces loading of expired CRLs; this is
183 only useful for debugging.
184 --disable-ldap
187 Entirely disables the use of LDAP.
188 --disable-http
191 Entirely disables the use of HTTP.
192 --ignore-http-dp
195 When looking for the location of a CRL, the to be tested cer‐
196 tificate usually contains so called CRL Distribution Point (DP)
197 entries which are URLs describing the way to access the CRL.
198 The first found DP entry is used. With this option all entries
199 using the HTTP scheme are ignored when looking for a suitable
200 DP.
201 --ignore-ldap-dp
204 This is similar to --ignore-http-dp but ignores entries using
205 the LDAP scheme. Both options may be combined resulting in
206 ignoring DPs entirely.
207 --ignore-ocsp-service-url
210 Ignore all OCSP URLs contained in the certificate. The effect
211 is to force the use of the default responder.
212 --honor-http-proxy
215 If the environment variable `http_proxy' has been set, use its
216 value to access HTTP servers.
217 --http-proxy host[:port]
220 Use host and port to access HTTP servers. The use of this
221 options overrides the environment variable `http_proxy' regard‐
222 less whether --honor-http-proxy has been set.
223 --ldap-proxy host[:port]
227 Use host and port to connect to LDAP servers. If port is ommit‐
228 ted, port 389 (standard LDAP port) is used. This overrides any
229 specified host and port part in a LDAP URL and will also be used
230 if host and port have been ommitted from the URL.
231 --only-ldap-proxy
234 Never use anything else but the LDAP "proxy" as configured with
235 --ldap-proxy. Usually dirmngr tries to use other configured
236 LDAP server if the connection using the "proxy" failed.
237 --ldapserverlist-file file
241 Read the list of LDAP servers to consult for CRLs and certifi‐
242 cates from file instead of the default per-user ldap server list
243 file. The default value for file is `dirmngr_ldapservers.conf'
244 or `ldapservers.conf' when running in --daemon mode.
245 This server list file contains one LDAP server per line in the
247 format
248 hostname:port:username:password:base_dn
250 Lines starting with a '#' are comments.
252 Note that as usual all strings entered are expected to be UTF-8
254 encoded. Obviously this will lead to problems if the password
255 has orginally been encoded as Latin-1. There is no other solu‐
256 tion here than to put such a password in the binary encoding
257 into the file (i.e. non-ascii characters won't show up read‐
258 able). ([The gpgconf tool might be helpful for frontends as it
259 allows to edit this configuration file using percent escaped
260 strings.])
261 --ldaptimeout secs
265 Specify the number of seconds to wait for an LDAP query before
266 timing out. The default is currently 100 seconds. 0 will never
267 timeout.
268 --add-servers
272 This options makes dirmngr add any servers it discovers when
273 validating certificates against CRLs to the internal list of
274 servers to consult for certificates and CRLs.
275 This options is useful when trying to validate a certificate
277 that has a CRL distribution point that points to a server that
278 is not already listed in the ldapserverlist. Dirmngr will always
279 go to this server and try to download the CRL, but chances are
280 high that the certificate used to sign the CRL is located on the
281 same server. So if dirmngr doesn't add that new server to list,
282 it will often not be able to verify the signature of the CRL
283 unless the --add-servers option is used.
284 Note: The current version of dirmngr has this option disabled by
286 default.
287 --allow-ocsp
291 This option enables OCSP support if requested by the client.
292 OCSP requests are rejected by default because they may violate
294 the privacy of the user; for example it is possible to track the
295 time when a user is reading a mail.
296 --ocsp-responder url
300 Use url as the default OCSP Responder if the certificate does
301 not contain information about an assigned responder. Note, that
302 --ocsp-signer must also be set to a valid certificate.
303 --ocsp-signer fpr|file
306 Use the certificate with the fingerprint fpr to check the
307 responses of the default OCSP Responder. Alternativly a file‐
308 name can be given in which case the respinse is expected to be
309 signed by one of the certificates described in that file. Any
310 argument which contains a slash, dot or tilde is considered a
311 filename. Usual filename expansion takes place: A tilde at the
312 start followed by a slash is replaced by the content of `HOME',
313 no slash at start describes a relative filename which will be
314 searched at the home directory. To make sure that the file is
315 searched in the home directory, either prepend the name with
316 "./" or use a name which contains a dot.
317 If a response has been signed by a certificate described by
319 these fingerprints no further check upon the validity of this
320 certificate is done.
321 The format of the FILE is a list of SHA-1 fingerprint, one per
323 line with optional colons between the bytes. Empty lines and
324 lines prefix with a hash mark are ignored.
325 --ocsp-max-clock-skew n
329 The number of seconds a skew between the OCSP responder and them
330 local clock is accepted. Default is 600 (20 minutes).
331 --ocsp-max-period n
334 Seconds a response is at maximum considered valid after the time
335 given in the thisUpdate field. Default is 7776000 (90 days).
336 --ocsp-current-period n
339 The number of seconds an OCSP response is considered valid after
340 the time given in the NEXT_UPDATE datum. Default is 10800 (3
341 hours).
342 --max-replies n
346 Do not return more that n items in one query. The default is
347 10.
348 --ignore-cert-extension oid
351 Add oid to the list of ignored certificate extensions. The oid
352 is expected to be in dotted decimal form, like 2.5.29.3. This
353 option may be used more than once. Critical flagged certificate
354 extensions matching one of the OIDs in the list are treated as
355 if they are actually handled and thus the certificate won't be
356 rejected due to an unknown critical extension. Use this option
357 with care because extensions are usually flagged as critical for
358 a reason.
359
365 A running dirmngr may be controlled by signals, i.e. using the kill
366 command to send a signal to the process.
367 Here is a list of supported signals:
369 SIGHUP This signals flushes all internally cached CRLs as well as any
373 cached certificates. Then the certificate cache is reinitial‐
374 ized as on startup. Options are re-read from the configuration
375 file.
376 SIGTERM
379 Shuts down the process but waits until all current requests are
380 fulfilled. If the process has received 3 of these signals and
381 requests are still pending, a shutdown is forced.
382 SIGINT Shuts down the process immediately.
385 SIGUSR1
389 This prints some caching statistics to the log file.
390
397 The way to start the dirmngr in the foreground (as done by tools if no
398 dirmngr is running in the background) is to use:
399 dirmngr --server -v
401 If a dirmngr is supposed to be used as a system wide daemon, it should
403 be started like:
404 dirmngr --daemon
406 This will force it to go into the backround, read the default certifi‐
408 cates (including the trusted root certificates) and listen on a socket
409 for client requests. It does also print information about the socket
410 used but they are only for compatibilty reasons with old GnuPG versions
411 and may be ignored.
412
416 Dirmngr makes use of several directories when running in daemon mode:
417 /etc/dirmngr
421 This is where all the configuration files are expected by
422 default.
423 /etc/dirmngr/trusted-certs
426 This directory should be filled with certificates of Root CAs
427 you are trusting in checking the CRLS and signing OCSP Reponses.
428 Usually these are the same certificates you use with the appli‐
429 cations making use of dirmngr. It is expected that each of
430 these certificate files contain exactly one DER encoded certifi‐
431 cate in a file with the suffix `.crt' or `.der'. dirmngr reads
432 those certificates on startup and when given a SIGHUP. Certifi‐
433 cates which are not readable or do not make up a proper X.509
434 certificate are ignored; see the log file for details.
435 Note that for OCSP responses the certificate specified using the
437 option --ocsp-signer is always considered valid to sign OCSP
438 requests.
439 /var/lib/dirmngr/extra-certs
443 This directory may contain extra certificates which are pre‐
444 loaded into the interal cache on startup. This is convenient in
445 cases you have a couple intermediate CA certificates or certifi‐
446 cates ususally used to sign OCSP reponses. These certificates
447 are first tried before going out to the net to look for them.
448 These certificates must also be DER encoded and suffixed with
449 `.crt' or `.der'.
450 /var/run/dirmngr
453 This directory keeps the socket file for accsing dirmngr ser‐
454 vices. The name of the socket file will be `socket'. Make sure
455 that this directory has the proper permissions to let dirmngr
456 create the socket file and that eligible users may read and
457 write to that socket.
458 /var/cache/dirmngr/crls.d
461 This directory is used to store cached CRLs. The `crls.d' part
462 will be created by dirmngr if it does not exists but you need to
463 make sure that the upper directory exists.
464
468 gpgsm(1), dirmngr-client(1)
469 The full documentation for this tool is maintained as a Texinfo manual.
471 If dirmngr and the info program are properly installed at your site,
472 the command
473 info dirmngr
475 should give you access to the complete manual including a menu struc‐
477 ture and an index.
478Dirmngr 1.1.0 2010-08-10 DIRMNGR(1)