NOTICE!!¶

tl;dr: This project was renamed to Stapled, which can be found here.

As of now this project has been renamed to Stapled because there are various other projects with the name ocspd which is confusing. Plus we want to implement functional tests in the near future, which are probably going to be based on a package also called ocsdp. This project will be kept here until June 30th 2018, in case you have this repo set as a dependency of some project.

From now on you will get a warning when you install the package, that tells you to use Stapled instead. From the 1st of January 2018 you will get an error instead. From June 30th 2018 onward the installation will stop working entirely.

You can find Stapled here.

Quick start¶

Table of Contents

Documentation
System requirements
Installation
Using ocspd
- Named Arguments
Testing ocspd

Documentation ¶

Read the full documentation on Read the docs.

System requirements ¶

This application requires Python 3.3+ or Python 2.7.9 and an installed version of PIP for the Python version you are using. It is also convenient to have virtualenv installed so you can make a separate environment for ocspd’s dependencies.

Installation ¶

Before installation make sure you have met the System requirements. You can install the ocsp daemon from the source code repository on our gitlab instance.

From github (for developers)¶

# Download the source from the repo
git clone https://github.com/greenhost/ocspd.git
# Enter the source directory
cd ocspd/
# Setup a virtualenv
virtualenv -p python3 env/
# Load the virtualenv
source env/bin/activate
# Install a dependency that is not yet it PyPi
pip install git+https://github.com/wbond/certvalidator.git@4383a4bfd5e769679bc4eedd1e4d334eb0c7d85a
# Install the current directory with pip. This allows you to edit the code
pip install .

Every time you want to run ocspd you will need to run source env/bin/activate to load the virtualenv first. Alternatively you can start the daemon by running ocspd

Upgrading ¶

If you had previously installed a version of ocspd from github, to upgrade run the following:

# Deactivate the virtualenv if active
deactivate
# Delete the virtualenv (we will start clean)
rm -rf ./env
# Make a new virtualenv
virtualenv -p python3 env/
# Update to the latest version
git pull
# Install a dependency that is not yet it PyPi
pip install git+https://github.com/wbond/certvalidator.git@4383a4bfd5e769679bc4eedd1e4d334eb0c7d85a --upgrade
# Install the current directory with pip. This allows you to edit the code
pip install . --upgrade

Debian package ¶

We package ocspd for Debian, but it will still have depenfencies that are not available as debian packages. This means you need to either still use PIP to install those dependencies, or you need to package them yourself.

There is a build script in the root of this project: build_deb_pkg.sh. It will automatically download the dependencies master branches from Github and package them, the finished packages including a package for ocspd will be in the build directory.

Warning

Do not use this, none of the source code you are about to check out will be audited, you will need to vet it yourself. Also it will cause side effects inluding but not limited to loss of hair, stress and diziness. This is not for production use. We do not take any responsibility for what you do with this script, we provide it as is, it will probably fail anyway but we may also stop supporting it at any time, in fact this is highly likely.

You have been warned, now please don’t continue at your own risk or go for the PIP install.

# Install available dependencies
apt install python-future python-all python-configargparse
# Download remaining dependencies and convert them to debian packages
./build_deb_pkg.sh
# Install all packages
dpkg -i build/*.deb

Using ocspd ¶

Update OCSP staples from CA’s and store the result so HAProxy can serve them to clients.

usage: ocspd [-h] [-c CONFIG] [--minimum-validity MINIMUM_VALIDITY]
             [-t RENEWAL_THREADS] [--verbosity VERBOSITY] [-v] [-D]
             [--file-extensions FILE_EXTENSIONS] [-r REFRESH_INTERVAL]
             [-l [LOGDIR]] [--syslog] [-q]
             [-s HAPROXY_SOCKETS [HAPROXY_SOCKETS ...]] -d DIRECTORIES
             [DIRECTORIES ...] [--no-recycle] [-i IGNORE [IGNORE ...]]

Named Arguments ¶

`-c, --config`	Override the default config file locations (default=~/.ocspd.conf, /etc/ocspd/ocspd.conf)
`--minimum-validity`
	If the staple is valid for less than this time in seconds an attempt will be made to get a new, valid staple (default: 7200).
`-t, --renewal-threads`
	Amount of threads to run for renewing staples. (default=2)
`--verbosity`	Verbose output argument should be an integer between 0 and 4, canbe overridden by the `-v` argument.
`-v`	Verbose output, repeat to increase verbosity, overrides the `verbosity` argument if provided
`-D, --daemon`	Daemonise the process, release from shell and process group, run under new process group.
`--file-extensions`
	Files with which extensions should be scanned? Comma separated list (default: crt,pem,cer)
`-r, --refresh-interval`
	Minimum time to wait between parsing cert dirs and certificates (default=60).
`-l, --logdir`	Enable logging to ‘/var/log/ocspd/’. It is possible to supply another directory. Traces of unexpected exceptions are placed here as well.
`--syslog`	Output to syslog.
`-q, --quiet`	Don’t print messages to stdout
`-s, --haproxy-sockets`
	Sockets to connect to HAProxy. Each directory you pass with the `directory` argument, should have its own haproxy socket. The order of the socket arguments should match the order of the directory arguments.Example:I have a directory `/etc/haproxy1` with certificates, and a HAProxy that serves these certificates and has stats socket `/etc/haproxy1/haproxy.sock`. I have another directory `/etc/haproxy2` with certificates and another haproxy instance that serves these and has stats socket `/etc/haproxy2/haproxy.sock`. I would then start ocspd as follows:`./ocspd /etc/haproxy1 /etc/haproxy2 -s /etc/haproxy1.sock /etc/haproxy2.sock`
`-d, --directories`
	Directories containing the certificates used by HAProxy. Multiple directories may be specified separated by a space.
`--no-recycle`	Don’t re-use existing staples, force renewal.
`-i, --ignore`	Ignore files matching this pattern. Multiple paths may be specified separated by a space. You can escape the pattern to let the daemon evaluate it instead of letting your shell evaluate it. You can use globbing patterns with `*` or `?`. Relative paths are also allowed.If the path starts with `/` it will be considered absolute if it does not, the pattern will be compared to the last part of found files.

The daemon will not serve OCSP responses, it can however inform HAPRoxy about the staples it creates using the --haproxy-sockets. argument. Alternatively you can configureHAPRoxy or another proxy (e.g. nginx has support for serving OCSP staples) to serve the OCSP staples manually.

Testing ocspd ¶

Testing an application like this is hard, but that is no excuse not to do testing. We want to have unit tests but to do that correctly we need to run an OCSP server locally, quite a setup. So until now we didn’t do so yet. Note that if you have experience with this kind of setup and you want to help this project move forward, you are welcome to help.

Obviously we do test ocspd, admittedly a little bit primitively. You can find a script in scripts/ called refresh_testdata.sh. It will delete any directory named testdata in the root of the project and create a fresh one. Then it will download 3 certificate chains from live servers. These will be placed in subdirectories with the same name as the domain name.

Next you can run python ocspd -vvvv -d testdata/* to get output printed to your terminal. The testdata/[domain].[tld] directories will be populated with [domain].[tld].ocsp files.