ocspd.conf.3(3)

📦 version 1.9.0, in fedora 43, fedora 44

okay so bestie, this is ocspd.conf.3(3) from the OpenCA Contributed Manual and it's literally the whole lore on the OCSP Daemon config file 💖 buckle up, it's long, it's detailed, and it's kinda iconic.

✨ NAME ✨

ocspd.conf — the OCSP Daemon configuration file. that's it, that's the name 🎀

🦋 DESCRIPTION 🦋

okay so a config file is split into a bunch of sections. every section starts with a line that looks like [ section_name ] and it ends the moment a new section starts, or when you hit end of file. a section name can be made of alphanumeric characters and underscores. simple as that ✨

the first section of a config file is special — it's called the default section. it's usually unnamed and it runs from the start of the file until the first named section shows up. when something's name is being looked up, it gets looked up in a named section first (if there is one), and then in the default section. no cap 👑

the environment gets mapped onto a section called ENV.

you can drop comments in by putting a # character in front of them. very demure, very mindful 💅

every section in a config file is just a bunch of name and value pairs shaped like name=value.

the name string can hold any alphanumeric characters plus a few punctuation symbols like ., ,, ; and _.

the value string is everything after the = character until end of line, with any leading and trailing white space removed. squeaky clean 🧚

now the fun part — the value string goes through variable expansion. you do it by writing $var or ${var}, and that substitutes the value of the named variable in the current section. you can also pull a value from a different section using $section::name or ${section::name}. and by using the form $ENV::name you can substitute environment variables in. you can even assign values to environment variables by using the name ENV::name — and this works if the program looks up environment variables using the CONF library instead of calling getenv() directly. iykyk 🌈

escaping is a thing too: you can escape certain characters by using any kind of quote or the \ character. and if you make the last character of a line a \, the value string can be spread across multiple lines. on top of that, the sequences \n, \r, \b and \t are recognized. so you're covered 🫶

💀 NOTES 💀

real talk: if a config file tries to expand a variable that doesn't exist, then an error is flagged and the file will not load. periodt. this can totally happen if you try to expand an environment variable that isn't there. for example, the default OpenSSL master configuration file used the value of HOME, which may not be defined on non Unix systems. so watch out for that 🙈

🌸 EXAMPLE 🌸

here's a sample configuration file, bestie:

# 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 you set the general options used by the responder — and some of them are available through the command line options too (see ocspd(3)).

dir — specifies the directory where everything is kept. your whole little home base 🏠
db — specifies the db where info about issued certificates is 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 ). so casual 💅
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). main character energy, listening to everything ✨
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. they expect better performances on multi-threaded machines and processors. from version 1.5+ the server is not pre-forked — instead it's a pre-threaded one. in order to run, the server needs support for POSIX1.c as found in most modern UNiX systems. slay 🧵
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 bestie, 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. > so yeah, that's a real one — the server keeps running anyway, so make sure that chroot is doing the heavy lifting 💀
crl_auto_reload — okay so this is the auto reload interval of the CRL, in seconds. If you set it to 0 or it's not present at all, then to reload the CRL you'll need to send a SIGHUP (kill -1 <pid>) to the parent process. no cap. 💅
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 it's set to '0' or not specified, all responses will be based on the loaded CRL, no matter if it is expired or not. lowkey important. 🫶
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.

only if you are sure, bestie. no cap. 🚨

request section

Currently not used. it's giving placeholder energy, but fr it's just sitting there unused. 💀

response section

Here are kept options tied to responses' building. this is where the response glow-up happens. ✨

dbms section

Here are kept options tied to the revoked certificates' list. the revoked girlies live here. 📋

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). so just cat them together, fr fr. 🐈
ocsp_add_response_keyid — specifies if adding of the key id to the response. yes, that's the whole description, it's giving cryptic. 🔑
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.

so you can stack 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. 📚

AUTHOR

Massimiliano Pala <madwolf@openca.org> — iconic. 👑