Package: ocspbot
The OCSP Bot’s job is to make sure up-to-date OCSP responses are kept
for a set of certificates.The bot should be run as a cronjob regularly (like, once per hour) and
will attempt to obtain OCSP responses for certificates for whichno valid OCSP response is currently stored, andthe existing OCSP response is expiring soon enough.The criteria for “expiring soon enough” can be defined in the
configuration.To install, usepip install ocspbot. If you want a one-file version,
please renameocspbot/__main__.pytoocspbot.pyand use that one.RequirementsOCSP Bot needspyyamlandOpenSSL.
It has been tested with OpenSSL 1.0.x and 1.1.0, but not with OpenSSL 0.9.x.Command Line InterfaceThe OCSP Bot can be invoked as follows:ocspbot.py [ <config file> ] [ -h | -help | --help ] [ -v | -version | --version ]In case-h,-helpor--helpis specified, a short help text
will be printed. In case-v,-versionor--versionis specified,
the program’s version will be printed.If no configuration file name is specified, it will useocspbot.yaml.
The configuration file will be parsed and the certificates specified
therein will be processed.OCSP Bot returns 0 for success (without changes), a positive return value
for the number of OCSP responses renewed, and negative return values for
errors:Return CodeMeaning-1An error occured while retrieving OCSP responses-2An error occured while parsing the configuration (parsing YAML, start logging)-3An error occured while parsing the configuration (interpreting configuration)-4Invalid command line argumentsNon-zero return values can be used to reload services which deliver the OCSP
responses. In case of negative return values, manual user invention might be
needed.Configuration File FormatConfiguration files must be inYAML format.
They can contain the following keys:ocsp_folder:<string>The folder in which the OCSP responses are stored. All OCSP response paths
will be interpreted relatively to this path.Default value is the empty string, i.e. the current directory.minimum_validity:<string>If an OCSP response is newer than the described time interval, the program
will try to renew it. The string is interpreted as a list of space separated
tokens of the form:? s, ? sec, ? second, ? seconds
? m, ? min, ? minute, ? minutes
? h, ? hour, ? hours
? d, ? day, ? days
? w, ? week, ? weeksExamples:2 hours 5 minutes 10 seconds1w 3d 5hminimum_validity_percentage:<number>Specifies a percentage (between0and100). If this percentage of the
OCSP response’s lifespan has elapsed, the response is renewed.parallel_threads:<number>An integer specifying how many threads should be run in parallel.
Default value is1.stop_on_error:<boolean>Specifies whether to stop on the first error found when processing OCSP
responses, or whether to try to renew all.make_backups:<boolean>If set to True, new OCSP responses are also copied in theocsp_folderdirectory to<filename>-<timestamp>as a backup (to keep track which
OCSP response was used when). Default value isFalse.openssl_executable:<string>The OpenSSL executable to use. Default isopenssl.domains:<dict>The dictionary maps a domain identifier to a dictionary with the
following entries:cert:<string>The path to the certificate file. Will be interpreted relative
to the current working directory. Must always be specified.chain:<string>The path to the certificate’s chain file. The chain must neither
contain the certificate itself nor the root certificate. Will be
interpreted relative to the current working directory. Must
always be specified.rootchain:<string>The path to the certificate’s root chain file. The root chain
must not include the certificate itself, but it must include
the root certificate. Will be interpreted relative
to the current working directory. Must always be specified.ocsp:<string>The path to the OCSP response file. Will be interpreted relative
toocsp_folder. Must always be specified.ocsp_responder_uri:<string>The URI of the OCSP responder for this certificate. Can be left
away or set to the special valuecertificateto extract the
URL from the certificate.The domain identifier will only be used in the output messages.scan_keys:<list>Every list entry must be a dictionary with the following entries:folder:<string>Default: (empty string, i.e. current working directory)recursive:<boolean>Default:Truecert_mask:<string>Default:{domain}.pemchain_mask:<string>Default:{domain}-chain.pemrootchain_mask:<string>Default:{domain}-rootchain.pemocsp_mask:<string>Default:{domain}.ocsp-respFor each dictionary, the program searches for all triples of files
(cert, chain, rootchain) in the specified folders (and its subfolders
ifrecursiveisTrue) which match the masks for the domain
identifier{domain}; the corresponding OCSP response filename is
chosen.When scanning recursively, and triples are found in subfolders, the
relative path of the triple’s files to the folder to scan is prepended
to the OCSP response filename.includes:<list>A list of folders which will be searched for YAML files with extensions.ymland.yaml. All found YAML files will be parsed anddomainsandscan_keysentries processed as in the main
configuration file.output_log:<string>error_log:<string>Writes output respectively error output into log files and not tostdoutresp.stderr. The filenames will be formatted with
the following replacements:{year}: the current year (four digits){month}:  the current month, 1 to 12 (two digits){day}: the current day per month, 1 to 31 (two digits){hour}: the current hour, 0 to 23 (two digits){minute}: the current minute, 0 to 59 (two digits){second}: the current second, 0 to 59 (two digits)Example Configuration FileThe following configuration file updates OCSP responses forexample.comandexample.orgso that the responses are valid at least for three days
or 42.8% of their validity period. Backups will be created, andstdoutoutput will be logged. The certificates are taken from/var/www/tls/certs/, and the responses will be written to/var/www/ocsp/responseswith backups.The minimum validity parameters are tuned forLet’s Encrypt. When running the CERT Bot
once per hour for some time,/var/www/ocsp/responsesmight have the
following files:example.com.ocsp-resp
example.com.ocsp-resp-20170415-060000
example.com.ocsp-resp-20170418-060000
example.com.ocsp-resp-20170421-060000
example.org.ocsp-resp
example.org.ocsp-resp-20170415-060000
example.org.ocsp-resp-20170418-060000
example.org.ocsp-resp-20170421-060000The current valid OCSP responses will beexample.com.ocsp-respandexample.org.ocsp-resp, with the last update having been on
April 21, 2017 at 06:00 am.The configuration file:---openssl_executable:opensslminimum_validity:3dminimum_validity_percentage:42.8ocsp_folder:/var/www/ocsp/responsesparallel_threads:1output_log:/var/www/ocsp/logs/example-{year}{month}{day}-{hour}{minute}{second}.logmake_backups:Truedomains:example.com:cert:/var/www/tls/certs/example.com.pemchain:/var/www/tls/certs/example.com-chain.pemrootchain:/var/www/tls/certs/example.com-rootchain.pemocsp:example.com.ocsp-respexample.org:cert:/var/www/tls/certs/example.org.pemchain:/var/www/tls/certs/example.org-chain.pemrootchain:/var/www/tls/certs/example.org-rootchain.pemocsp:example.org.ocsp-resp