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
36 substitute a value from another section using the syntax $section::name
37 or ${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
41 calling 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
54 systems.
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 ]
68 dir = /etc/ocspd
70 md = sha1
71 ocspd_certificate = $dir/certs/ocspd_cert.pem
73 ocspd_key = $dir/private/ocspd_key.pem
74 pidfile = $dir/ocspd.pid
75 user = ocspd
77 group = daemon
78 bind = *
79 port = 2560
80 max_childs_num = 5
81 max_req_size = 8192
82 request = ocsp_req
84 response = ocsp_response
85 dbms = dbms_ldap # Example using the LDAP for CRL
87 # retrivial
88 #dbms = dbms_file # Example using file for CRL
90 engine = HSM # ENGINE section
92 ####################################################################
94 [ ocsp_req ]
95 default_keyfile = key.pem
96 ####################################################################
98 [ ocsp_response ]
99 dir = /etc/ocspd
100 ocsp_add_response_certs = $dir/certs/chain_certs.pem
101 ocsp_add_response_keyid = yes
102 next_update_days = 0
103 next_update_mins = 5
104 ####################################################################
106 [ dbms_ldap ]
107 # It is possible to use an URI to identify a CRL and/or the
109 # CA certificate, the general format is:
110 #
111 # [protocol]://[user[:pwd]@]server[:port]/[path]
112 #
113 # where:
114 # protocol - specifies the protocol to be used, supported are
115 # file, ldap, http
116 # user - is the user for auth (meaningful only if ldap or
117 # http is used)
118 # pwd - password used for auth (meaningful only if ldap
119 # or http is used)
120 # port - port to connect to (meaningful only if ldap or
121 # http is used)
122 # path - complete path to the object (meaningful only if
123 # http is used)
124 #
125 # You can have the CRLs/CA certificates on a simple file
126 # crl_url = file:///etc/ocspd/crl.pem
127 #
128 # You can retrieve the CRLs/CA certificates from a web server
129 # crl_urt = http://server/ca/cacert.der
130 #
131 # You can store the CRL into an LDAP server, simply
132 # store it in certificateRevocationList;binary attribute
133 #
134 # There are different way, all legal, to specify the CRL
135 # URL address:
136 # crl_url = ldap://user:pwd@ldap.server.org:389
137 # crl_url = ldap://ldap.server.org:389
138 crl_url = ldap://localhost
139 # The CRL entry DN is the DN to look for when retrieving the
141 # date from the LDAP server. Put here the complete DN (usually
142 # the DN of the CA's certificate).
143 crl_entry_dn = "email=email@address, cn=Certification Auth, \
144 o=Organization, c=IT"
145 ####################################################################
147 [ dbms_file ]
148 # You can have the CRL on a simple file in PEM format
150 crl_url = file:///etc/ocspd/crl.pem
151 [ HSM ]
153 # Hardware accelerators support via the ENGINE interface
154 engine_id = MyAccelerator
155 0.engine_pre = login:1:10:11:myPassword
156 # 0.engine_post = logout:1:10:11
157 Let's analyze the options in detail.
159 default_ocspd section
161 In this section of the configuration file are set the general
162 options used by the responder, some of which are available using
163 the command line options too ( see ocspd(3)).
164 dir specifies the directory where everything is kept.
166 md specifies the digest to be used. Default is sha1.
168 ocspd_certificate
170 path to the certificate to be used by the responder.
171 ocspd_key
173 path to the private key file to be used by the responder.
174 pidfile
176 path to the pid file where the responder will write its pid
177 when starting.
178 user user id the responder will try to run as, this must be a
180 valid UID. If not specified the responder will run as the
181 user who started the daemon.
182 group group id the responder will try to run as, this must be a
184 valid GID. If not specified the responder will run as the
185 user who started the daemon.
186 bind address to listen to. You can force the responder to listen
188 to just one of the available addresses. If you want the
189 responder to listen to every available interface, simply use
190 '*' (default).
191 port specifies the port to listen to.
193 threads_num
195 Number of threads that shall be created at startup time, the
196 more threads, the better for handling very high traffic. We
197 expect to have better performances on multi-threaded machines
198 and processors.
199 From version 1.5+ the server is not pre-forked, instead it is
201 a pre-threaded one. In order to run the server needs support
202 for POSIX1.c as found in most modern UNiX systems.
203 max_client_num
205 Size of the system socket queue: when all service threads are
206 busy, up to this number of unserved requests are accepted in
207 queue and will be processed as soon as a thread becomes
208 available; additional connection requests will be denied.
209 Default: 30.
210 chroot_dir
212 Chroot the application into the specified directory, watch
213 out because if you chroot the application, all the paths
214 should be relative to the new root for CRL reloading or
215 (better solution) you have to download the CRLs from HTTP or
216 LDAP. If you chroot and you do not provide support for
217 privileges dropping, privileges will not be dropped and an
218 error will be written in the logfile, but the server will
219 continue to run assuming the chroot() is sufficiently
220 isolated to prevent abuse of the machine.
221 max_req_size
223 maximum size of received request, if a received request is
224 bigger it will be trashed. Usually simple requests are
225 200/300 bytes long (more or less).
226 request section
228 Currently not used
229 response section
231 Here are kept options tied to responses' building.
232 dbms section
234 Here are kept options tied to the revoked certificates' list.
235 ocsp_add_response_certs
237 specifies path to a file containing certificates to be added to
238 the response (usually the whole certification chain).
239 Certificates have to be in PEM format one after another (a
240 simple cat of the certificates will do fine).
241 ocsp_add_response_keyid
243 specifies if adding of the key id to the response.
244 next_update_days
246 specifies the number of days till next update is available. A
247 response will be valid in the period following the request till
248 the days+mins.
249 next_update_mins
251 specifies the number of minutes till next update is available.
252 A response will be valid in the period following the request
253 till the days+mins.
254 ca_url
256 specifies the URI where the CA certificate (which identifies
257 the single CA) is located. Three different protocols are
258 implemented ( file:// http:// or ldap:// ). If file is chosen,
259 then the parameter should carry the path to the CA file (i.e.
260 file:///etc/ocspd/certs/ca.pem). If ldap or http is chosen,
261 you can specify the address, and the port of the server where
262 to connect to (i.e. ldap://server.addr:port).
263 crl_url
265 specifies the URI where the CRL (list of revoked certificates,
266 actually used for building responses) is located. Three
267 different protocols are actually implemented ( file:// http://
268 or ldap:// ). If file is chosen, then the parameter should
269 have the path to the crl file (i.e.
270 file:///etc/ocspd/crls/cacrl.pem). If ldap or http is chosen,
271 you can specify the address, and the port of the server where
272 to connect to (i.e. ldap://server.addr:port).
273 crl_entry_dn
275 specifies, if ldap:// protocol is chosen within the crl_url
276 parameter, the entry where to look for the
277 certificateRevocationList attribute where the CRL should be
278 present (usually this is also the base of the LDAP tree, but
279 different installations are also possible).
280 ENGINE section
282 engine_id
283 Specifies the ENGINE id to be used - check OpenSSL and your
284 HSM vendor to get more info about this parameter.
285 engine_pre
287 Some HSM need initialisation before access to the crypto
288 accelerated functions is granted. It is possible, by using
289 the 'engine_pre' options to issue needed commands directly to
290 the HSM.
291 The format is as follows:
293 0.engine_pre = cmd:values
294 1.engine_pre = cmd2:values
295 ... It is possible to have as many commands as needed.
296 engine_post
298 Some HSMs need to perform commands after the ENGINE
299 initialisation which are taken from the 'engine_post' option.
300 Usage and format is exactly the same as 'engine_pre', the
301 difference is that commands are sent to the HSM after the
302 ENGINE_init() function. Refer to your HSM documentation for
303 more informations
304
306 Massimiliano Pala <madwolf@openca.org>
307
309 ocspd(3),openca(3),openssl(1), ocsp(1)
310
312 Hey! The above document had some coding errors, which are explained
313 below:
314 Around line 162:
316 '=item' outside of any '=over'
317 Around line 348:
319 You forgot a '=back' before '=head1'
320openca-ocspd 1.5.1 2009-08-22 ocspd.conf.3(3)