The HPKP toolset!

HPKP is an incredibly powerful response header that allows you to whitelist the fingerprints of specific cryptographic identities. This offers you protection against a rogue Certificate Authority issuing a certificate for your site. My new HPKP toolset will make implementing and testing your HPKP policy much easier!

HTTP Public Key Pinning

HPKP is typically a little tricky to setup but you get a whole heap of protection that you simply can't get any other way. You can read my blog on HPKP: HTTP Public Key Pinning for an idea of exactly what HPKP is and does if you need a refresher and you can also see the slightly unfortunate way that you have to configure it at present. Requiring quite a few interactions at the command line, and with no way to verify that what you had actually done was correct, I wasn't all too pleased with the obstacles to implementing HPKP.

Making HPKP easy!

If we want to increase adoption of security technologies, then we need to lower the barrier to entry. With that said, I'm launching 3 new tools to help with the setup, implementation and testing of a HPKP policy for your own site.

hpkp tools

All of these tools are available on the tools page, which you can find here, and are free for anyone to use.

HPKP Analyser

The HPKP Analyser can be used to look at the HPKP policy on any site and to verify your own HPKP policy once you've implemented one. Simply navigate to the tool and insert the address of any site you'd like to check and hit 'Analyse'.

pkp analyse

The tool will fetch the response headers from the site you entered and extract any Public-Key-Pins or Public-Key-Pins-Report-Only headers. It will also follow redirects and defaults to http if no scheme is specified, so if the site in question doesn't redirect http to https, you will need to manually specify it, but the tool will inform you of that anyway. Once the HPKP policy has been extracted, it doesn't just display it to you, it will actually verify the pins and highlight any matches against the certificate chain that the site served! Here is my Public-Key-Pins header:

pkp match

Here is my Public-Key-Pins-Report-Only header too:

pkp ro match

The verification part here is crucial. The browser will not apply and cache the policy unless there is at least one valid pin in there. This is good because if you issued a policy that was totally wrong with no valid pins, you would DoS your site as the browser would never allow access until the policy expired! Whilst you don't have to worry about that, you do have to worry that the pins might not be correct and as such, no policy will ever be applied so you don't have the protection of HPKP. If you see a valid pin displayed then the browser will be caching and applying the policy, assuming you're using a good browser. Check support for HPKP here.

You can also pin at multiple levels. You can pin at the leaf certificate level, at the intermediate level or the root level. As you step up to the intermediate and again to the root, you increase your attack surface but also slightly reduce the chance that you can totally screw it up and DoS your site as you'd be able to get any new certificate issued by the same authority. To demonstrate what that looks like, I've setup a temporary header that you can analyse here.

strongssl pins

I've included pins in this policy for my leaf certificate, the intermediate and the root to show you how validation of those looks too.

HPKP Generator (URL)

If you want to generate the hash for your current certificate, don't worry about dropping down to the command line and digging around to find it and issue commands against it, just put the URL of your site in here and hit hash!

hpkp hash url

This tool will grab your current certificate and create the necessary hash for you with no hassle. It's also a great way to check a hash that you created yourself to make sure it's right. It outputs exactly the value that needs to go in your header so all you need to do is copy and paste.

pkp hash url complete

Update: The PKP Generator will now generate pins for all certificates in the chain so you can choose which level you would like to pin at.

HPKP Generator (PEM)

Another thing that you have to do for HPKP is to have some form of backup pin in your policy. This can be another certificate or a CSR (amongst other things). To make creating the hashes for those easier too, this version of the HPKP generator will take a PEM encoded certificate, CSR or public key.

pkp pub key hash

If you want to test it out I've create a PEM encoded CSR and public key on PasteBin that you can try out on the tool here. Similar to before, the tool will take any of those 3 valid inputs and create the hash value that you can insert straight into your HPKP header.

pkp pub key hash complete

One things that's crucial to note here is that you must never disclose your private key, in any way. I've included a private key in the PasteBin link so you can try it out and see that the tool throws a warning to let you know what happened. Please make sure that you do not do this with your own private key!

pub key hash private key error

As always, please let me know if you find any issues with the new tools either in the comments below or via email at the top of the page. I hope they prove to be useful and help to lower the difficulty in implementing a HPKP policy. Also, feedback is always welcome!

Author image
About Scott Helme