Weblog

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.