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 1.9)
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 --honor-http-proxy
201 If the environment variable `http_proxy' has been set, use its
202 value to access HTTP servers.
203 --http-proxy host[:port]
206 Use host and port to access HTTP servers. The use of this
207 options overrides the environment variable `http_proxy' regard‐
208 less whether --honor-http-proxy has been set.
209 --ldap-proxy host[:port]
213 Use host and port to connect to LDAP servers. If port is ommit‐
214 ted, port 389 (standard LDAP port) is used. This overrides any
215 specified host and port part in a LDAP URL and will also be used
216 if host and port have been ommitted from the URL.
217 --only-ldap-proxy
220 Never use anything else but the LDAP "proxy" as configured with
221 --ldap-proxy. Usually dirmngr tries to use other configured
222 LDAP server if the connection using the "proxy" failed.
223 --ldapserverlist-file file
227 Read the list of LDAP servers to consult for CRLs and certifi‐
228 cates from file instead of the default per-user ldap server list
229 file. The default value for file is `dirmngr_ldapservers.conf'
230 or `ldapservers.conf' when running in --daemon mode.
231 This server list file contains one LDAP server per line in the
233 format
234 hostname:port:username:password:base_dn
236 Lines starting with a
238 are comments.
239 Note that as usual all strings entered are expected to be UTF_8
241 encoded. Obviously this will lead to problems if the password
242 has orginally been encoded as Latin-1. tehre isno solutionhere
243 than to put such a password in the binary encoding into the file
244 (i.e. non-ascii characters won't show up readable). ([The gpg‐
245 conf tool might be helpful for frontends as it allows to edit
246 this configuration file suing percent escaped strings.])
247 --ldaptimeout secs
251 Specify the number of seconds to wait for an LDAP query before
252 timing out. The default is currently 100 seconds. 0 will never
253 timeout.
254 --add-servers
258 This options makes dirmngr add any servers it discovers when
259 validating certificates against CRLs to the internal list of
260 servers to consult for certificates and CRLs.
261 This options is useful when trying to validate a certificate
263 that has a CRL distribution point that points to a server that
264 is not already listed in the ldapserverlist. Dirmngr will always
265 go to this server and try to download the CRL, but chances are
266 high that the certificate used to sign the CRL is located on the
267 same server. So if dirmngr doesn't add that new server to list,
268 it will often not be able to verify the signature of the CRL
269 unless the --add-servers option is used.
270 Note: The current version of dirmngr has this option disabled by
272 default.
273 --allow-ocsp
277 This option enables OCSP support if requested by the client.
278 OCSP requests are rejected by default because they may violate
280 the privacy of the user; for example it is possible to track the
281 time when a user is reading a mail.
282 --ocsp-responder url
286 Use url as the default OCSP Responder if the certificate does
287 not contain information about an assigned responder. Note, that
288 --ocsp-signer must also be set to a valid certificate.
289 --ocsp-signer fpr
292 Use the certificate with the fingerprint fpr to check the
293 responses of the default OCSP Responder. Dirmngr will retrieve
294 this certificate from the current client.
295 If a response has been signed by this certificate no further
297 check upon the validity of this certificate is done!
298 --ocsp-max-clock-skew n
301 The number of seconds a skew between the OCSP respinder and them
302 local clock is accepted. Default is 600 (20 minutes).
303 --ocsp-current-period n
306 The number of seconds an OCSP reponse is valid after the time
307 given in the NEXT_UPDATE datum. Default is 10800 (3 hours).
308 --max-replies n
312 Do not return more that n items in one query. The default is
313 10.
314
320 A running dirmngr may be controlled by signals, i.e. using the kill
321 command to send a signal to the process.
322 Here is a list of supported signals:
324 SIGHUP This signals flushes all internally cached CRLs as well as any
328 cached certificates. Then the certificate cache is reinitial‐
329 ized as on startup. Options are re-read from the configuration
330 file.
331 SIGTERM
334 Shuts down the process but waits until all current requests are
335 fulfilled. If the process has received 3 of these signals and
336 requests are still pending, a shutdown is forced.
337 SIGINT Shuts down the process immediately.
340 SIGUSR1
344 This prints some caching statistics to the log file.
345
352 The way to start the dirmngr in the foreground (as done by tools if no
353 dirmngr is running in the background) is to use:
354 dirmngr --server -v
355 If a dirmngr is supposed to be used as a system wide daemon, it should
357 be started like:
358 dirmngr --daemon
359 This will force it to go into the backround, read the default certifi‐
360 cates (including the trusted root certificates) and listen on a socket
361 for client requests. It does also print information about the socket
362 used but they are only for compatibilty reasons with old GnuPG versions
363 and may be ignored.
364
368 Dirmngr makes use of several directories when running in daemon mode:
369 /etc/dirmngr
373 This is where all the configuration files are expected by
374 default.
375 /etc/dirmngr/trusted-certs
378 This directory should be filled with certificates of Root CAs
379 you are trusting in checking the CRLS and signing OCSP Reponses.
380 Usually these are the same certificates you use with the appli‐
381 cations making use of dirmngr. It is expected that each of
382 these certificates files contain exactly one DER encoded cer‐
383 tificate in a file with the suffix `.crt'. dirmngr reads those
384 certificates on startup and when given a SIGHUP. Certificates
385 which are not readable or do not make up a proper X.509 certifi‐
386 cate are ignored; see the log file for details.
387 Note that for OCSP responses the certificate specified using the
389 option --ocsp-signer is always considered valid to sign OCSP
390 requests.
391 /var/lib/dirmngr/extra-certs
395 This directory may contain extra certificates which are pre‐
396 loaded into the interal cache on startup. This is convenient in
397 cases you have a couple intermediate CA certificates or certifi‐
398 cates ususally used to sign OCSP reponses. These certificates
399 are first tried before going out to the net to look for them.
400 These certificates must also be DER encoded and suffixed with
401 `.crt'.
402 /var/run/dirmngr
405 This directory keeps the socket file for accsing dirmngr ser‐
406 vices. The name of the socket file will be `socket'. Make sure
407 that this directory has the proper permissions to let dirmngr
408 create the socket file and that eligible users may read and
409 write to that socket.
410 /var/cache/dirmngr/crls.d
413 This directory is used to store cached CRLs. The `crls.d' part
414 will be created by dirmngr if it does not exists but you need to
415 make sure that the upper directory exists.
416
420 gpgsm(1), dirmngr-client(1)
421 The full documentation for this tool is maintained as a Texinfo manual.
423 If dirmngr and the info program are properly installed at your site,
424 the command
425 info dirmngr
427 should give you access to the complete manual including a menu struc‐
429 ture and an index.
430Dirmngr 1.0.0 2006-11-29 DIRMNGR(1)