16 April 2017, 22:41

This release offers an easy way to set HTTP Public Key Pinning (HPKP) headers. With other webservers, you need to construct this header manually via a set of complex openssl commands. These commands look like this:

openssl rsa -in my-rsa-key-file.key -outform der -pubout |
  openssl dgst -sha256 -binary | openssl enc -base64

Via the PublicKeyPins option, you simply tell Hiawatha where to find a file containing one or more X.509 certificates, certificate signing requests and/or public keys (all in PEM format) and Hiawatha will construct the HPKP header for you. No more messing around with openssl.

PublicKeyPins = <public key file>[, max_age=<value>[d]]

What is HPKP exactly?

Via HPKP, a webserver can tell a browser to remember a specific public key. This can be any public key in the certificate chain: the public key of the webserver certificate, the one from an intermediate CA or even the root CA. Every time that browser is used to make another visit to that website, it will check if the same public key is being used somewhere in the chain. If not, the browser will give a warning and will refuse the connection. This all will only work when your website has been visited at least once, because after that the browser has seen the HPKP header.

What problem does HPKP solve?

When you visit a website via HTTPS, your browser accepts certificates signed by any of the CA's of which it has a root certificate installed. If a false CA root certificate gets installed on your machine (for example, due to malware) or any of those CA's gets hacked (like DigiNotar), an attacker can perform a man-in-the-middle attack. By telling the browser to only trust a certain public key (the one from the actual webserver or the CA's root public key), you can prevent such attack.

Which public key should I enlist in the header?

Listing your webserver's public key gives the best security, because someone must steal the private key to imitate the webserver. It also causes the highest risk, because when you lose the private key, nobody will be able to access your website for the time specified via max-age. Listing your CA's public key makes your webserver's security depend on the security of the CA of your choice. But when you lose your private key, requesting a new certificate will allow users to still visit your website. HPKP allows you to list multiple public keys. So, you can create an extra key pair, add its public key to the HPKP list and store its private key in a safe place as backup. You can also list the public key of another CA. That way you can switch to another CA when the first one can no longer be trusted. HPKP can be a useful tool. It just requires careful thinking and planning.

What value should I use for the max-age?

Setting a high value gives the best security, but also causes the greatest problem in case something goes wrong with your private key. A lower value will allow users sooner access to your website again when something goes wrong, but also gives less security. My advice is to determine the average time interval between two visits by your average user, add a little (like 10%) to that value and use that for the max-age setting.

16 April 2017, 23:07
PublicKeyPins option cannot be found in the user's manual.
Hugo Leisink
16 April 2017, 23:25
Updated the online version of the manual page. Thanks for the heads up.
Chris Wadge
17 April 2017, 02:07
I had a flood which has taken my lab including one webserver and my build machine temporarily offline, but the primary mirror for Hiawatha Debian packages is still up, and I should be able to provide a package for Hiawatha 10.6 soon.

All the best,
Hugo Leisink
17 April 2017, 02:42
Hi Chris. How about the dotbalm.org domain? It is expired. Will it be back online?
17 April 2017, 04:57
I got syntax error on PublicKeyPins option.

Any idea?
17 April 2017, 05:21
I got the following error instead :

HPKP: PK - Invalid key tag or value : ASN1 - ASN1 tag was of an unexpected value (-0x3D62)
17 April 2017, 06:14
I found out the problem is that your sha-256 generation has problem. It should be :

openssl x509 -in /etc/hiawatha/tls/www.mysite.com.pem -pubkey -noout | openssl rsa -pubin -outform der | openssl dgst -sha256 -binary | base64

17 April 2017, 10:33
thanks for the new functionalities
Hugo Leisink
17 April 2017, 13:24
@Samiux: The sha256 generation by Hiawatha is good. Tools like SSL Labs [www.ssllabs.com] and ReportURI [report-uri.io] confirm that. What's going wrong in your case?
17 April 2017, 20:20

I send you email as I cannot post any link here.
Chris Wadge
18 April 2017, 01:38
OK, my flood situation has mostly been dealt with. Got the builds up on the usual Debian mirrors, no regressions detected during testing.

As for dotbalm.org, it's one of a few projects I haven't had a lot of time for lately, I'm afraid. I'll look into getting it back up.

Chris Wadge
18 April 2017, 06:32
Dotbalm.org is back now too. I really should get around to writing more articles, but life has been absolutely crazy. I'm about to do a site re-launch for a client using Hiawatha though, so I may just have new things to write about soon enough.