Quick start¶

Table of Contents

Documentation
System requirements
Installation
- From github (for developers)
- Upgrading
Troubleshooting
Compiling this package
Using stapled
- Named Arguments
Testing stapled
Caveats

Documentation ¶

Read the full documentation on Read the docs.

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 stapled’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 --recursive https://github.com/greenhost/stapled.git
# OR, as a TIP, which downloads all the repos simultaneously in threads:
git clone --recursive -j5 https://github.com/greenhost/stapled.git
# Enter the source directory
cd stapled/
# Setup a virtualenv
virtualenv -p python3 env/
# Load the virtualenv
source env/bin/activate
# Install the current directory with pip. This allows you to edit the code
pip install -e .

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

Upgrading ¶

If you had previously installed a version of stapled 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
# Clone submodules too
git submodule upgrade --init --recursive
# Install the current directory with pip. This allows you to edit the code
pip install -e . --upgrade

Troubleshooting ¶

In order to get HAPRoxy to serve staples, any valid staple file should exist at the moment it is started. If a staple file does not exist for your certificate stapling will remain disabled until you restart HAProxy. Even if stapled tries to send HAProxy a valid staple through its socket.

In order to get around this bootstrapping problem, add an empty staple file, which is also valid according to HAProxy’s documentation by running:

touch [path-to-certificate].pem.ocsp

For each of your domains.

We tested this for HAProxy 1.6, perhaps this behaviour will change in future versions.

Compiling this package ¶

There are 2 ways to compile the package and various target distributions.

Build locally ¶

Assuming you have the following packages installed on a debian based system:

build-essential
python-cffi
python3-cffi
libffi-dev
python-all
python3-all
python-dev
python3-dev
python-setuptools
python3-setuptools
python-pip
rpm
tar, gzip & bzip2
git
debhelper
stdeb (pip install --user stdeb)

Or the equivalents of these on another distribution. You can build the packages by running one or more of the following make commands.

# Clear out the cruft from any previous build
make clean
# Source distribution
make sdist
# Binary distribution
make bdist
# RPM package (Fedora, Redhat, CentOS) - untested!
make rpm
# Debian source package (Debian, Ubuntu)
make deb-src
# Debian package (Debian, Ubuntu)
make deb
# All of the above
make all

Everything is tested under Debian Stretch, your mileage may vary.

Docker build ¶

In order to be able to build a package reproducably by anyone, on any platform we have a Dockerfile that will install an instance of Debian Stretch in a docker container and can run the build process for you.

Assuming you have docker installed, you can simply run the below commands to build a package.

make docker-all

Remove any previous docker image and/or container named stapled then buil the image with the same dependencies we used. Then compile the packages, then place them in the ./docker-dist dir.

make docker-nuke

Throw away any previous docker image and/or container named stapled. This is part of the make docker-all target.

make docker-build

Build the docker image. This is part of the make docker-all target.

make docker-compile

Assuming you have a built image, this compiles the packages for you and places them in docker-dist. This is part of the make docker-all target.

make docker-install

Assuming you have a built image and compiled the packages, this installs the packages in the docker container. This is part of the make docker-all target.

make docker-run

Assuming you have a built image and compiled the packages, and installed them in the docker container, this runs the installed binary to test if it works.

Packages ¶

You can download packages here: https://github.com/greenhost/stapled/releases

Using stapled ¶

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

usage: stapled [-h] [-c CONFIG] [--minimum-validity MINIMUM_VALIDITY]
               [-t RENEWAL_THREADS] [--verbosity VERBOSITY] [-v] [-D]
               [--interactive] [--file-extensions FILE_EXTENSIONS]
               [-r REFRESH_INTERVAL] [-l [LOGDIR]] [--syslog] [-q]
               [-s HAPROXY_SOCKETS [HAPROXY_SOCKETS ...]]
               [--no-haproxy-sockets]
               [--haproxy-config HAPROXY_CONFIG [HAPROXY_CONFIG ...]]
               [-p CERT_PATHS [CERT_PATHS ...]] [-R] [--no-recycle]
               [-i IGNORE [IGNORE ...]] [-V]
               [-d DIRECTORIES [DIRECTORIES ...]]

Named Arguments ¶

`-c, --config`	Override the default config file locations (default=/home/docs/checkouts/readthedocs.org/user_builds/stapled/checkouts/latest/docs/source/stapled.conf, ~/.stapled.conf, /etc/stapled/stapled.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, can be 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.
`--interactive, --no-daemon`
	Disable daemon mode, overrides daemon mode if enabled in the config file, effectively starting interactive mode.
`--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/stapled/’. 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 stapled as follows:`./stapled /etc/haproxy1 /etc/haproxy2 -s /etc/haproxy1.sock /etc/haproxy2.sock`
`--no-haproxy-sockets`
	Disable HAProxy sockets, overrides `--haproxy-sockets` if specified in the config file.
`--haproxy-config`
	Path(s) to HAProxy config files, they will be scanned for certificates, certificate directories and HAProxy admin sockets based on `bind [..] crt [..]` directives and `stats [..] socket [..]` directives, the `crt-base` directive isrespected. Multiple config files may be specified separated by a space. See `--haproxy-sockets` for more information.
`-p, --cert-paths`
	Paths to certificates files or directories containing certificates used by HAProxy. Multiple paths may be specified separated by a space.
`-R, --recursive`
	Recursively scan given paths.
`--no-recycle`	Don’t re-use existing staples, force renewal.
`-i, --ignore`	Ignore files matching this pattern. Multiple patterns may be specified separated by a space. You can put the pattern in quotes to let stapled evaluate it instead of letting your shell evaluate it. You can use globbing patterns with `` or `?`. If a pattern starts with `/` it will be considered absolute, if it does not start with a `/`, the pattern will be compared to the last part of found files. e.g. the pattern `cert/snakeoil.pem` matches with path `/etc/ssl/cert/snakeoil.pem`. Don’t define relative paths* as patterns, paths are not patterns, e.g. `../certs/*.pem` will not cause pem files in a directory named `certs`, one directory up from `$PATH` to be ignored. Instead your pattern will cause a warning and will be ignored.
`-V, --version`	Show the version number and exit.
`-d, --directories`
	DEPRECATED, please see `--cert-paths`.

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 configure HAPRoxy or another proxy (e.g. nginx has support for serving OCSP staples) to serve the OCSP staples manually.

Testing stapled ¶

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 stapled, 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 stapled -vvvv -d testdata/* to get output printed to your terminal. The testdata/[domain].[tld] directories will be populated with [domain].[tld].ocsp files.

Caveats ¶

In order to get HAPRoxy to serve staples, any staple valid file should exist at the moment it is started. If a staple file does not exist for your certificate stapling will remain disabled until you restart HAProxy. Even if stapled tries to send HAProxy a valid staple through its socket.

In order to get around this bootstrapping problem, add an empty staple file, which is also valid according to HAProxy’s documentation by running:

touch [path-to-certificate].pem.ocsp

For each of your domains.

We tested this for HAProxy 1.6, perhaps this behaviour will change in future versions.