About

HPKPinx allows for automated, regularly renewed HPKP configuration using the following components:

• Nginx
• Let's Encrypt via the dehydrated client

The script has been tested and deployed successfully on CentOS 7 machines. Testing involved disaster recovery using the static backup pin, which is generated automatically upon install.

Installation

First off, you need to have private key rollover enabled, otherwise you may render your site inaccessible. Add to /opt/dehydrated/config:

PRIVATE_KEY_ROLLOVER="yes"

Then request a certificate renewal which generates new production and rollover private keys. Verify that you indeed have privkey.pem and privkey.roll.pem under dehydrated/certs/<hostname>.

dehydrated certs should be available under /etc/nginx/certs:

ln -sT /opt/dehydrated/certs /etc/nginx/certs

Now get a fresh copy of HPKPinx:

git clone https://github.com/bviktor/hpkpinx.git /opt/hpkpinx
cd /opt/hpkpinx
./install.sh

After this, you're prompted to move your backup private key off-server, which you should most definitely do right away.

Also make sure to regenerate the pins upon each renewal by calling hpkpinx.sh. For example, if you're using the Certzure DNS-01 hook, add to the end of /opt/certzure/certzure.sh:

/opt/hpkpinx/hpkpinx.sh $1 $2

Naturally, you also have to restart Nginx after each renewal, but that is already implied by using Let's Encrypt.

Then add to your Nginx host config:

include hpkp.conf;

Configuration

The config file is located at /opt/hpkpinx/config.sh. You have the following options:

HPKP_AGE

The time, in seconds, that the browser should remember that this site is only to be accessed using one of the defined keys.

STATIC_PIN

This is the pin of your backup key. Normally you shouldn't need to change this, unless you want to replace the generated backup key with your own. In this case, you can generate a pin for your private key with:

hpkpinx.sh generate_pin <your_key.pem>

DEPLOY_HPKP

• If set to 0 (the default), Nginx will only send the Public-Key-Pins-Report-Only header and HPKP is not applied.
• If set to 1, Nginx sends the Public-Key-Pins header and the HPKP policy for your site goes live in supported browsers.

Resources

• HPKP: HTTP Public Key Pinning by Scott Helme
• HPKP Analyser by Scott Helme
• SecurityHeaders.io by Scott Helme
• HPKP Reference by Mozilla
• HTTP Public-Key-Pinning Explained by Tim Taubert
• Getting started with Let's Encrypt! by Scott Helme