1ocspd.conf.3(3) OpenCA Contributed Manual ocspd.conf.3(3)
2
6 ocspd.conf - OCSP Daemon configuration file
7
9 A configuration file is divided into a number of sections. Each section
10 starts with a line [ section_name ] and ends when a new section is
11 started or end of file is reached. A section name can consist of
12 alphanumeric characters and underscores.
13 The first section of a configuration file is special and is referred to
15 as the default section this is usually unnamed and is from the start of
16 file until the first named section. When a name is being looked up it
17 is first looked up in a named section (if any) and then the default
18 section.
19 The environment is mapped onto a section called ENV.
21 Comments can be included by preceding them with the # character
23 Each section in a configuration file consists of a number of name and
25 value pairs of the form name=value
26 The name string can contain any alphanumeric characters as well as a
28 few punctuation symbols such as . , ; and _.
29 The value string consists of the string following the = character until
31 end of line with any leading and trailing white space removed.
32 The value string undergoes variable expansion. This can be done by
34 including the form $var or ${var}: this will substitute the value of
35 the named variable in the current section. It is also possible to sub‐
36 stitute a value from another section using the syntax $section::name or
37 ${section::name}. By using the form $ENV::name environment variables
38 can be substituted. It is also possible to assign values to environment
39 variables by using the name ENV::name, this will work if the program
40 looks up environment variables using the CONF library instead of call‐
41 ing getenv() directly.
42 It is possible to escape certain characters by using any kind of quote
44 or the \ character. By making the last character of a line a \ a value
45 string can be spread across multiple lines. In addition the sequences
46 \n, \r, \b and \t are recognized.
47
49 If a configuration file attempts to expand a variable that doesn't
50 exist then an error is flagged and the file will not load. This can
51 happen if an attempt is made to expand an environment variable that
52 doesn't exist. For example the default OpenSSL master configuration
53 file used the value of HOME which may not be defined on non Unix sys‐
54 tems.
55
57 Following is a sample configuration file:
58 # OCSPd example configuration file.
60 # (c) 2001 by Massimiliano Pala - OpenCA Project.
61 # All rights reserved
62 [ ocspd ]
64 default_ocspd = OCSPD_default
65 [ OCSPD_default ]
67 dir = /usr/local/etc/ocspd
69 db = $dir/index.txt
70 md = sha1
71 ca_certificate = $dir/certs/cacert.pem
73 ocspd_certificate = $dir/certs/ocspd_cert.pem
74 ocspd_key = $dir/private/ocspd_key.pem
75 pidfile = $dir/ocspd.pid
76 user = ocspd
78 group = daemon
79 bind = *
80 port = 2560
81 threads_num = 150
82 max_req_size = 8192
83 request = ocsp_req
85 response = ocsp_response
86 dbms = dbms_ldap # Example using the LDAP for CRL
88 # retrivial
89 #dbms = dbms_file # Example using file for CRL
91 engine = HSM # ENGINE section
93 ####################################################################
95 [ ocsp_req ]
96 default_keyfile = key.pem
97 ####################################################################
99 [ ocsp_response ]
100 dir = /usr/local/etc/ocspd
101 ocsp_add_response_certs = $dir/certs/chain_certs.pem
102 ocsp_add_response_keyid = yes
103 next_update_days = 0
104 next_update_mins = 5
105 ####################################################################
107 [ dbms_ldap ]
108 # It is possible to use an URI to identify a CRL and/or the
110 # CA certificate, the general format is:
111 #
112 # [protocol]://[user[:pwd]@]server[:port]/[path]
113 #
114 # where:
115 # protocol - specifies the protocol to be used, supported are
116 # file, ldap, http
117 # user - is the user for auth (meaningful only if ldap or
118 # http is used)
119 # pwd - password used for auth (meaningful only if ldap
120 # or http is used)
121 # port - port to connect to (meaningful only if ldap or
122 # http is used)
123 # path - complete path to the object (meaningful only if
124 # http is used)
125 #
126 # You can have the CRLs/CA certificates on a simple file
127 # crl_url = file:///usr/local/etc/ocspd/crl.pem
128 # ca_url = file:///usr/local/etc/ocspd/ca.pem
129 #
130 # You can retrieve the CRLs/CA certificates from a web server
131 # crl_url = http://server/ca/cacert.crl.der
132 # ca_url = http://server/ca/cacert.der
133 #
134 # You can store the CRL into an LDAP server, simply
135 # store it in certificateRevocationList;binary attribute
136 #
137 # There are different way, all legal, to specify the CRL/CA
138 # URL address:
139 # crl_url = ldap://user:pwd@ldap.server.org:389
140 # crl_url = ldap://ldap.server.org:389
141 crl_url = ldap://localhost
142 ca_url = ldap://localhost
143 # The CRL entry DN is the DN to look for when retrieving the
145 # date from the LDAP server. Put here the complete DN (usually
146 # the DN of the CA's certificate).
147 crl_entry_dn = "email=email@address, cn=Certification Auth, \
148 o=Organization, c=IT"
149 # To retrieve the CRL from LDAP the attribute where it is stored is to
151 # be specified. Usually this should be set to:
152 #
153 # certificateRevocationList;binary
154 #
155 # anyway existing LDAP installations or new standards can mandate
156 # for different attributes for storing CRLs into. Use this parameter
157 # to specify the attribute used to retrieve the CRL from.
158 #
159 # This option is needed only if the CRL is stored on LDAP
160 crl_entry_attribute = "certificateRevocationList;binary"
161 # We need the CA certificate for every CA we support. Upon loading
163 # the CRL and the CA certificate a simple check is made to ensure
164 # the CRL/CA certificate matching. Also the CA certificate is used
165 # to retrieve the CID used to identify the certificate being
166 # requested by the client (CID of the Issuer + serial Number).
167 # Like the CRL URL, the URL scheme for the CA may be file, ldap or http.
168 ca_url = ldap://localhost
169 # DN where the cACertificate;binary value can be downloaded
171 # This option is needed only if the CA Certificate is stored on LDAP
172 ca_entry_dn = "o=Organisation, c=IT"
173 # This is the attribute used to store the CA.
175 ca_entry_attribute = "caCertificate;binary"
176 # Server Certificate to attach to the response
178 server_cert = file:///etc/ocspd/certs/ocspd_cert.pem
179 ####################################################################
181 [ dbms_file ]
182 # You can have the CRL on a simple file in PEM format
184 crl_url = file:///usr/local/etc/ocspd/crl.pem
185 [ HSM ]
187 # Hardware accelerators support via the ENGINE interface
188 engine_id = MyAccelerator
189 0.engine_pre = login:1:10:11:myPassword
190 # 0.engine_post = logout:1:10:11
191 Let's analyze the options in detail.
193
195In this section of the configuration file are set the general options used by
196the responder, some of which are available using the command line options too
197( see ocspd(3)).
198
200
202 now the only supported file format is the one from openssl(1). To
203 reload the certificate's db simply send a SIGHUP to the main process (
204 kill -s SIGHUP pid ).
205
207
209 path to the CA's certificate.
210
212 path to the certificate to be used by the responder.
213
215 path to the private key file to be used by the responder.
216
218 path to the pid file where the responder will write its pid when start‐
219 ing.
220
222 not specified the responder will run as the user who started the daemon.
223
225 not specified the responder will run as the user who started the daemon.
226
228 of the available addresses. If you want the responder to listen to every
229 available interface, simply use '*' (default).
230
232
234 Maximum size of received request, if a received request is bigger it
235 will be trashed. Usually simple requests are 200/300 bytes long (more or
236 less).
237
239 Number of threads that shall be created at startup time, the more
240 threads, the better for handling very high traffic. We expect to have
241 better performances on multi-threaded machines and processors.
242 From version 1.5+ the server is not pre-forked, instead it is a pre-
244 threaded one. In order to run the server needs support for POSIX1.c as
245 found in most modern UNiX systems.
246
248 Length of the system's listen() queue. Up to this number of not-yet-
249 served connection requests are queued by the system. Additional ones are
250 dropped. Default is 30.
251
253 Max timeout for request receiving. If a request is not received within
254 the specified number of seconds then the socket is closed in order to
255 free unused threads. If not set, the default value is 5 seconds.
256
258 HTTP protocol version to be required. If 1.1 is specified, then the
259 "Host: <addr>" name is also used in the header of HTTP GET requests.
260
262 Chroot the application into the specified directory, watch out because
263 if you chroot the application, all the paths should be relative to the
264 new root for CRL reloading or (better solution) you have to download the
265 CRLs from HTTP or LDAP. If you chroot and you do not provide support for
266 privileges dropping, privileges will not be dropped and an error will be
267 written in the logfile, but the server will continue to run assuming the
268 chroot() is sufficiently isolated to prevent abuse of the machine.
269
271 Auto Reload interval of CRL in seconds. If set to 0 or not present, to
272 reload the CRL you'll need to send a SIGHUP (kill -1 <pid>) to the par‐
273 ent process.
274
276 CRL validity check period in seconds. If this parameter is set to #n
277 then the CRL is checked every #n secs and if the CRL's validity period
278 is expired then all the responses will be set to 'unknown'. If is set
279 to '0' or not specified, all responses will be based on the loaded CRL,
280 no matter if it is expired or not.
281
283 If the currently loaded CRL is expired, reload it. Set this parameter to
284 "yes" only if you are sure that the new CRL will be issued and put in
285 the crl_url location.
286
288Currently not used
289
291Here are kept options tied to responses' building.
292
294Here are kept options tied to the revoked certificates' list.
295
297 specifies path to a file containing certificates to be added to the
298 response (usually the whole certification chain). Certificates have to be
299 in PEM format one after another (a simple cat of the certificates will do
300 fine).
301
303 specifies if adding of the key id to the response.
304
306 specifies the number of days till next update is available. A response
307 will be valid in the period following the request till the days+mins.
308
310 specifies the number of minutes till next update is available. A response
311 will be valid in the period following the request till the days+mins.
312
314 specifies the URI where the CA certificate (which identifies the single
315 CA) is located. Three different protocols are implemented ( file://
316 http:// or ldap:// ). If file is chosen, then the parameter should carry
317 the path to the CA file (i.e. file:///usr/local/etc/ca.pem). If ldap or
318 http is chosen, you can specify the address, and the port of the server
319 where to connect to (i.e. ldap://server.addr:port).
320
322 specifies the URI where the CRL (list of revoked certificates, actually
323 used for building responses) is located. Three different protocols are
324 actually implemented ( file:// http:// or ldap:// ). If file is chosen,
325 then the parameter should have the path to the crl file (i.e.
326 file:///usr/local/etc/cacrl.pem). If ldap or http is chosen, you can spec‐
327 ify the address, and the port of the server where to connect to (i.e.
328 ldap://server.addr:port).
329
331 specifies, if ldap:// protocol is chosen within the crl_url parameter, the
332 entry where to look for the certificateRevocationList attribute where the
333 CRL should be present (usually this is also the base of the LDAP tree, but
334 different installations are also possible).
335
338 Specifies the ENGINE id to be used - check OpenSSL and your HSM vendor
339 to get more info about this parameter.
340
342 Some HSM need initialisation before access to the crypto accelerated
343 functions is granted. It is possible, by using the 'engine_pre' options
344 to issue needed commands directly to the HSM.
345 The format is as follows:
347 0.engine_pre = cmd:values
348 1.engine_pre = cmd2:values
349 ... It is possible to have as many commands as needed.
350
352 Some HSMs need to perform commands after the ENGINE initialisation which
353 are taken from the 'engine_post' option. Usage and format is exactly the
354 same as 'engine_pre', the difference is that commands are sent to the
355 HSM after the ENGINE_init() function. Refer to your HSM documentation
356 for more informations
357
359 Massimiliano Pala <madwolf@openca.org>
360
362 ocspd(3),openca(3),openssl(1), ocsp(1)
363openca-ocspd 1.5.1 2006-10-13 ocspd.conf.3(3)