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 --shutdown
69 This commands shuts down an running instance of Dirmngr. This
70 command has corrently no effect.
71 --flush
74 This command removes all CRLs from Dirmngr's cache. Client
75 requests will thus trigger reading of fresh CRLs.
76
81 --options file
82 Reads configuration from file instead of from the default per-
83 user configuration file. The default configuration file is
84 named `gpgsm.conf' and expected in the home directory.
85 --homedir dir
88 Set the name of the home directory to dir. This option is only
89 effective when used on the command line. The default depends on
90 the running mode:
91 With --daemon given on the commandline
95 the directory named `/etc/dirmngr' for configuration
96 files, `/var/lib/dirmngr/' for extra data and
97 `/var/cache/dirmngr' for cached CRLs.
98 Without --daemon given on the commandline
101 the directory named `.gnupg' directly below the home
102 directory of the user unless the environment variable
103 GNUPGHOME has been set in which case its value will be
104 used. All kind of data is stored below this directory.
105 -v
109 --verbose
111 Outputs additional information while running. You can increase
112 the verbosity by giving several verbose commands to dirmngr,
113 such as -vv.
114 --log-file file
119 Append all logging output to file. This is very helpful in see‐
120 ing what the agent actually does.
121 --debug-level level
124 Select the debug level for investigating problems. level may be
125 one of:
126 none no debugging at all.
129 basic some basic debug messages
131 advanced
133 more verbose debug messages
134 expert even more detailed messages
136 guru all of the debug messages you can get
138 How these messages are mapped to the actual debugging flags is not
140 specified and may change with newer releases of this program. They are
141 however carefully selected to best aid in debugging.
142 --debug flags
145 This option is only useful for debugging and the behaviour may
146 change at any time without notice. FLAGS are bit encoded and
147 may be given in usual C-Syntax.
148 --debug-all
151 Same as --debug=0xffffffff
152 --debug-wait n
155 When running in server mode, wait n seconds before entering the
156 actual processing loop and print the pid. This gives time to
157 attach a debugger.
158 -s
161 --sh
163 -c
165 --csh Format the info output in daemon mode for use with the standard
167 Bourne shell respective the C-shell . The default ist to guess
168 it based on the environment variable SHELL which is in almost
169 all cases sufficient.
170 --force
173 Enabling this option forces loading of expired CRLs; this is
174 only useful for debugging.
175 --disable-ldap
178 Entirely disables the use of LDAP.
179 --disable-http
182 Entirely disables the use of HTTP.
183 --ignore-http-dp
186 When looking for the location of a CRL, the to be tested cer‐
187 tificate usually contains so called CRL Distribution Point (DP)
188 entries which are URLs describing the way to access the CRL.
189 The first found DP entry is used. With this option all entries
190 using the HTTP scheme are ignored when looking for a suitable
191 DP.
192 --ignore-ldap-dp
195 This is similar to --ignore-http-dp but ignores entries using
196 the LDAP scheme. Both options may be combined resulting in
197 ignoring DPs entirely.
198 --ignore-ocsp-service-url
201 Ignore all OCSP URLs contained in the certificate. The effect
202 is to force the use of the default responder.
203 --honor-http-proxy
206 If the environment variable `http_proxy' has been set, use its
207 value to access HTTP servers.
208 --http-proxy host[:port]
211 Use host and port to access HTTP servers. The use of this
212 options overrides the environment variable `http_proxy' regard‐
213 less whether --honor-http-proxy has been set.
214 --ldap-proxy host[:port]
218 Use host and port to connect to LDAP servers. If port is ommit‐
219 ted, port 389 (standard LDAP port) is used. This overrides any
220 specified host and port part in a LDAP URL and will also be used
221 if host and port have been ommitted from the URL.
222 --only-ldap-proxy
225 Never use anything else but the LDAP "proxy" as configured with
226 --ldap-proxy. Usually dirmngr tries to use other configured
227 LDAP server if the connection using the "proxy" failed.
228 --ldapserverlist-file file
232 Read the list of LDAP servers to consult for CRLs and certifi‐
233 cates from file instead of the default per-user ldap server list
234 file. The default value for file is `dirmngr_ldapservers.conf'
235 or `ldapservers.conf' when running in --daemon mode.
236 This server list file contains one LDAP server per line in the
238 format
239 hostname:port:username:password:base_dn
241 Lines starting with a '#' are comments.
243 Note that as usual all strings entered are expected to be UTF-8
245 encoded. Obviously this will lead to problems if the password
246 has orginally been encoded as Latin-1. There is no other solu‐
247 tion here than to put such a password in the binary encoding
248 into the file (i.e. non-ascii characters won't show up read‐
249 able). ([The gpgconf tool might be helpful for frontends as it
250 allows to edit this configuration file using percent escaped
251 strings.])
252 --ldaptimeout secs
256 Specify the number of seconds to wait for an LDAP query before
257 timing out. The default is currently 100 seconds. 0 will never
258 timeout.
259 --add-servers
263 This options makes dirmngr add any servers it discovers when
264 validating certificates against CRLs to the internal list of
265 servers to consult for certificates and CRLs.
266 This options is useful when trying to validate a certificate
268 that has a CRL distribution point that points to a server that
269 is not already listed in the ldapserverlist. Dirmngr will always
270 go to this server and try to download the CRL, but chances are
271 high that the certificate used to sign the CRL is located on the
272 same server. So if dirmngr doesn't add that new server to list,
273 it will often not be able to verify the signature of the CRL
274 unless the --add-servers option is used.
275 Note: The current version of dirmngr has this option disabled by
277 default.
278 --allow-ocsp
282 This option enables OCSP support if requested by the client.
283 OCSP requests are rejected by default because they may violate
285 the privacy of the user; for example it is possible to track the
286 time when a user is reading a mail.
287 --ocsp-responder url
291 Use url as the default OCSP Responder if the certificate does
292 not contain information about an assigned responder. Note, that
293 --ocsp-signer must also be set to a valid certificate.
294 --ocsp-signer fpr|file
297 Use the certificate with the fingerprint fpr to check the
298 responses of the default OCSP Responder. Alternativly a file‐
299 name can be given in which case the respinse is expected to be
300 signed by one of the certificates described in that file. Any
301 argument which contains a slash, dot or tilde is considered a
302 filename. Usual filename expansion takes place: A tilde at the
303 start followed by a slash is replaced by the content of `HOME',
304 no slash at start describes a relative filename which will be
305 searched at the home directory. To make sure that the file is
306 searched in the home directory, either prepend the name with
307 "./" or use a name which contains a dot.
308 If a response has been signed by a certificate described by
310 these fingerprints no further check upon the validity of this
311 certificate is done.
312 The format of the FILE is a list of SHA-1 fingerprint, one per
314 line with optional colons between the bytes. Empty lines and
315 lines prefix with a hash mark are ignored.
316 --ocsp-max-clock-skew n
320 The number of seconds a skew between the OCSP responder and them
321 local clock is accepted. Default is 600 (20 minutes).
322 --ocsp-max-period n
325 Seconds a response is at maximum considered valid after the time
326 given in the thisUpdate field. Default is 7776000 (90 days).
327 --ocsp-current-period n
330 The number of seconds an OCSP response is considered valid after
331 the time given in the NEXT_UPDATE datum. Default is 10800 (3
332 hours).
333 --max-replies n
337 Do not return more that n items in one query. The default is
338 10.
339
345 A running dirmngr may be controlled by signals, i.e. using the kill
346 command to send a signal to the process.
347 Here is a list of supported signals:
349 SIGHUP This signals flushes all internally cached CRLs as well as any
353 cached certificates. Then the certificate cache is reinitial‐
354 ized as on startup. Options are re-read from the configuration
355 file.
356 SIGTERM
359 Shuts down the process but waits until all current requests are
360 fulfilled. If the process has received 3 of these signals and
361 requests are still pending, a shutdown is forced.
362 SIGINT Shuts down the process immediately.
365 SIGUSR1
369 This prints some caching statistics to the log file.
370
377 The way to start the dirmngr in the foreground (as done by tools if no
378 dirmngr is running in the background) is to use:
379 dirmngr --server -v
381 If a dirmngr is supposed to be used as a system wide daemon, it should
383 be started like:
384 dirmngr --daemon
386 This will force it to go into the backround, read the default certifi‐
388 cates (including the trusted root certificates) and listen on a socket
389 for client requests. It does also print information about the socket
390 used but they are only for compatibilty reasons with old GnuPG versions
391 and may be ignored.
392
396 Dirmngr makes use of several directories when running in daemon mode:
397 /etc/dirmngr
401 This is where all the configuration files are expected by
402 default.
403 /etc/dirmngr/trusted-certs
406 This directory should be filled with certificates of Root CAs
407 you are trusting in checking the CRLS and signing OCSP Reponses.
408 Usually these are the same certificates you use with the appli‐
409 cations making use of dirmngr. It is expected that each of
410 these certificate files contain exactly one DER encoded certifi‐
411 cate in a file with the suffix `.crt' or `.der'. dirmngr reads
412 those certificates on startup and when given a SIGHUP. Certifi‐
413 cates which are not readable or do not make up a proper X.509
414 certificate are ignored; see the log file for details.
415 Note that for OCSP responses the certificate specified using the
417 option --ocsp-signer is always considered valid to sign OCSP
418 requests.
419 /var/lib/dirmngr/extra-certs
423 This directory may contain extra certificates which are pre‐
424 loaded into the interal cache on startup. This is convenient in
425 cases you have a couple intermediate CA certificates or certifi‐
426 cates ususally used to sign OCSP reponses. These certificates
427 are first tried before going out to the net to look for them.
428 These certificates must also be DER encoded and suffixed with
429 `.crt' or `.der'.
430 /var/run/dirmngr
433 This directory keeps the socket file for accsing dirmngr ser‐
434 vices. The name of the socket file will be `socket'. Make sure
435 that this directory has the proper permissions to let dirmngr
436 create the socket file and that eligible users may read and
437 write to that socket.
438 /var/cache/dirmngr/crls.d
441 This directory is used to store cached CRLs. The `crls.d' part
442 will be created by dirmngr if it does not exists but you need to
443 make sure that the upper directory exists.
444
448 gpgsm(1), dirmngr-client(1)
449 The full documentation for this tool is maintained as a Texinfo manual.
451 If dirmngr and the info program are properly installed at your site,
452 the command
453 info dirmngr
455 should give you access to the complete manual including a menu struc‐
457 ture and an index.
458Dirmngr 1.0.3 2010-11-12 DIRMNGR(1)