ocspd.conf - Man Page

A configuration file is divided into a number of sections. Each section starts with a line [ section_name ] and ends when a new section is started or end of file is reached. A section name can consist of alphanumeric characters and underscores.

The first section of a configuration file is special and is referred to as the default section this is usually unnamed and is from the start of file until the first named section. When a name is being looked up it is first looked up in a named section (if any) and then the default section.

The environment is mapped onto a section called ENV.

Comments can be included by preceding them with the # character

Each section in a configuration file consists of a number of name and value pairs of the form name=value

The name string can contain any alphanumeric characters as well as a few punctuation symbols such as . , ; and _.

The value string consists of the string following the = character until end of line with any leading and trailing white space removed.

The value string undergoes variable expansion. This can be done by including the form $var or ${var}: this will substitute the value of the named variable in the current section. It is also possible to substitute a value from another section using the syntax $section::name or ${section::name}. By using the form $ENV::name environment variables can be substituted. It is also possible to assign values to environment variables by using the name ENV::name, this will work if the program looks up environment variables using the CONF library instead of calling getenv() directly.

It is possible to escape certain characters by using any kind of quote or the \ character. By making the last character of a line a \ a value string can be spread across multiple lines. In addition the sequences \n, \r, \b and \t are recognized.

If a configuration file attempts to expand a variable that doesn't exist then an error is flagged and the file will not load. This can happen if an attempt is made to expand an environment variable that doesn't exist. For example the default OpenSSL master configuration file used the value of HOME which may not be defined on non Unix systems.

Following is a sample configuration file:

 # OCSPd example configuration file.
 # (c) 2001 by Massimiliano Pala - OpenCA Project.
 # All rights reserved

 [ ocspd ]
 default_ocspd   = OCSPD_default

 [ OCSPD_default ]

 dir              = /usr/local/etc/ocspd
 db               = $dir/index.txt
 md               = sha1

 ca_certificate    = $dir/certs/cacert.pem
 ocspd_certificate = $dir/certs/ocspd_cert.pem
 ocspd_key         = $dir/private/ocspd_key.pem
 pidfile           = $dir/ocspd.pid

 user                    = ocspd
 group                   = daemon
 bind                    = *
 port                    = 2560
 threads_num             = 150
 max_req_size            = 8192

 request          = ocsp_req
 response         = ocsp_response

 dbms                    = dbms_ldap     # Example using the LDAP for CRL
                                         # retrivial

 #dbms                   = dbms_file     # Example using file for CRL

 engine = HSM                            # ENGINE section

 ####################################################################
 [ ocsp_req ]
 default_keyfile         = key.pem

 ####################################################################
 [ ocsp_response ]
 dir                     = /usr/local/etc/ocspd
 ocsp_add_response_certs = $dir/certs/chain_certs.pem
 ocsp_add_response_keyid = yes
 next_update_days        = 0
 next_update_mins        = 5

 ####################################################################
 [ dbms_ldap ]

 # It is possible to use an URI to identify a CRL and/or the
 # CA certificate, the general format is:
 #
 #      [protocol]://[user[:pwd]@]server[:port]/[path]
 #
 # where:
 #   protocol - specifies the protocol to be used, supported are
 #              file, ldap, http
 #   user     - is the user for auth (meaningful only if ldap or
 #              http is used)
 #   pwd      - password used for auth (meaningful only if ldap
 #              or http is used)
 #   port     - port to connect to (meaningful only if ldap or
 #              http is used)
 #   path     - complete path to the object (meaningful only if
 #              http is used)
 #
 # You can have the CRLs/CA certificates on a simple file
 #    crl_url = file:///usr/local/etc/ocspd/crl.pem
 #    ca_url = file:///usr/local/etc/ocspd/ca.pem
 #
 # You can retrieve the CRLs/CA certificates from a web server
 #    crl_url = http://server/ca/cacert.crl.der
 #    ca_url = http://server/ca/cacert.der
 #
 # You can store the CRL into an LDAP server, simply
 # store it in certificateRevocationList;binary attribute
 #
 # There are different way, all legal, to specify the CRL/CA
 # URL address:
 # crl_url = ldap://user:pwd@ldap.server.org:389
 # crl_url = ldap://ldap.server.org:389
 crl_url = ldap://localhost
 ca_url = ldap://localhost

 # The CRL entry DN is the DN to look for when retrieving the
 # date from the LDAP server. Put here the complete DN (usually
 # the DN of the CA's certificate).
 crl_entry_dn = "email=email@address, cn=Certification Auth, \
                                             o=Organization, c=IT"

 # To retrieve the CRL from LDAP the attribute where it is stored is to
 # be specified. Usually this should be set to:
 #
 #     certificateRevocationList;binary
 #
 # anyway existing LDAP installations or new standards can mandate
 # for different attributes for storing CRLs into. Use this parameter
 # to specify the attribute used to retrieve the CRL from.
 #
 # This option is needed only if the CRL is stored on LDAP
 crl_entry_attribute = "certificateRevocationList;binary"

 # We need the CA certificate for every CA we support. Upon loading
 # the CRL and the CA certificate a simple check is made to ensure
 # the CRL/CA certificate matching. Also the CA certificate is used
 # to retrieve the CID used to identify the certificate being
 # requested by the client (CID of the Issuer + serial Number).
 # Like the CRL URL, the URL scheme for the CA may be file, ldap or http.
 ca_url  = ldap://localhost

 # DN where the cACertificate;binary value can be downloaded
 # This option is needed only if the CA Certificate is stored on LDAP
 ca_entry_dn = "o=Organisation, c=IT"

 # This is the attribute used to store the CA.
 ca_entry_attribute = "caCertificate;binary"

 # Server Certificate to attach to the response
 server_cert = file:///etc/ocspd/certs/ocspd_cert.pem

 ####################################################################
 [ dbms_file ]

 # You can have the CRL on a simple file in PEM format
 crl_url = file:///usr/local/etc/ocspd/crl.pem

 [ HSM ]
 # Hardware accelerators support via the ENGINE interface
 engine_id = MyAccelerator
 0.engine_pre = login:1:10:11:myPassword
 # 0.engine_post = logout:1:10:11

Let's analyze the options in detail.

default_ocspd section

In this section of the configuration file are set the general options used by the responder, some of which are available using the command line options too ( see ocspd(3)).

dir

specifies the directory where everything is kept.

db

specifies the db where info about issued certificates are kept. Right now the only supported file format is the one from openssl(1). To reload the certificate's db simply send a SIGHUP to the main process ( kill -s SIGHUP pid ).

md

specifies the digest to be used. Default is sha1.

ca_certificate

path to the CA's certificate.

ocspd_certificate

path to the certificate to be used by the responder.

ocspd_key

path to the private key file to be used by the responder.

pidfile

path to the pid file where the responder will write its pid when starting.

user

user id the responder will try to run as, this must be a valid UID. If not specified the responder will run as the user who started the daemon.

group

group id the responder will try to run as, this must be a valid GID. If not specified the responder will run as the user who started the daemon.

bind

address to listen to. You can force the responder to listen to just one of the available addresses. If you want the responder to listen to every available interface, simply use '*' (default).

port

specifies the port to listen to.

max_req_size

Maximum size of received request, if a received request is bigger it will be trashed. Usually simple requests are 200/300 bytes long (more or less).

threads_num

Number of threads that shall be created at startup time, the more threads, the better for handling very high traffic. We expect to have better performances on multi-threaded machines and processors.

From version 1.5+ the server is not pre-forked, instead it is a pre-threaded one. In order to run the server needs support for POSIX1.c as found in most modern UNiX systems.

max_client_num

Length of the system's listen() queue. Up to this number of not-yet-served connection requests are queued by the system. Additional ones are dropped. Default is 30.

max_timeout_secs

Max timeout for request receiving. If a request is not received within the specified number of seconds then the socket is closed in order to free unused threads. If not set, the default value is 5 seconds.

http_proto

HTTP protocol version to be required. If 1.1 is specified, then the "Host: <addr>" name is also used in the header of HTTP GET requests.

chroot_dir

Chroot the application into the specified directory, watch out because if you chroot the application, all the paths should be relative to the new root for CRL reloading or (better solution) you have to download the CRLs from HTTP or LDAP. If you chroot and you do not provide support for privileges dropping, privileges will not be dropped and an error will be written in the logfile, but the server will continue to run assuming the chroot() is sufficiently isolated to prevent abuse of the machine.

crl_auto_reload

Auto Reload interval of CRL in seconds. If set to 0 or not present, to reload the CRL you'll need to send a SIGHUP (kill -1 <pid>) to the parent process.

crl_check_validity

CRL validity check period in seconds. If this parameter is set to #n then the CRL is checked every #n secs and if the CRL's validity period is expired then all the responses will be set to 'unknown'. If is set to '0' or not specified, all responses will be based on the loaded CRL, no matter if it is expired or not.

crl_reload_expired

If the currently loaded CRL is expired, reload it. Set this parameter to "yes" only if you are sure that the new CRL will be issued and put in the crl_url location.

request section

Currently not used

response section

Here are kept options tied to responses' building.

dbms section

Here are kept options tied to the revoked certificates' list.

ocsp_add_response_certs

specifies path to a file containing certificates to be added to the response (usually the whole certification chain). Certificates have to be in PEM format one after another (a simple cat of the certificates will do fine).

ocsp_add_response_keyid

specifies if adding of the key id to the response.

next_update_days

specifies the number of days till next update is available. A response will be valid in the period following the request till the days+mins.

next_update_mins

specifies the number of minutes till next update is available. A response will be valid in the period following the request till the days+mins.

ca_url

specifies the URI where the CA certificate (which identifies the single CA) is located. Three different protocols are implemented ( file:// http:// or ldap:// ). If file is chosen, then the parameter should carry the path to the CA file (i.e. file:///usr/local/etc/ca.pem). If ldap or http is chosen, you can specify the address, and the port of the server where to connect to (i.e. ldap://server.addr:port).

crl_url

specifies the URI where the CRL (list of revoked certificates, actually used for building responses) is located. Three different protocols are actually implemented ( file:// http:// or ldap:// ). If file is chosen, then the parameter should have the path to the crl file (i.e. file:///usr/local/etc/cacrl.pem). If ldap or http is chosen, you can specify the address, and the port of the server where to connect to (i.e. ldap://server.addr:port).

crl_entry_dn

specifies, if ldap:// protocol is chosen within the crl_url parameter, the entry where to look for the certificateRevocationList attribute where the CRL should be present (usually this is also the base of the LDAP tree, but different installations are also possible).

ENGINE section

engine_id

Specifies the ENGINE id to be used - check OpenSSL and your HSM vendor to get more info about this parameter.

engine_pre

Some HSM need initialisation before access to the crypto accelerated functions is granted. It is possible, by using the 'engine_pre' options to issue needed commands directly to the HSM.

The format is as follows:
  0.engine_pre = cmd:values
  1.engine_pre = cmd2:values
  ... It is possible to have as many commands as needed.

engine_post

Some HSMs need to perform commands after the ENGINE initialisation which are taken from the 'engine_post' option. Usage and format is exactly the same as 'engine_pre', the difference is that commands are sent to the HSM after the ENGINE_init() function. Refer to your HSM documentation for more informations

Massimiliano Pala <madwolf@openca.org>

ocspd(3),openca(3),openssl(1), ocsp(1)