HTTP Public Key Pinning (HPKP)

protects HTTPS websites from impersonation using fraudulent certificates

HTTP(s) Public Key Pinning (HPKP) is an https header used to protect HTTPS websites from impersonation by fraudulent certificates issued by compromised certificate authorities (CA). The owner of the web site provides the browser clients with a string which identifies one of the certificates the client browser should acknowledge when compared to the certificate chain from the certificate authority. If the client can not independently match the certificate from the CA chain compared to the web server's "public-key-pins" header, then the connection is aborted and an error page is shown.

A certificate authority is the only entity the browser can use to verify the server's HTTPS identity. When a certificate authority is compromised the attacker can generate certificates for the domain and trick users into believing they are securely connected to the correct server. HTTP(s) Public Key Pinning (HPKP) allows the server operator to independently inform the client what ssl certificate they should see when verifying the certificate chain against the certificate authority. HPKP is used by Facebook, Google, Twitter and more.

How exactly does Public Key Pinning (HPKP) work ?

When a client browser connects to a Public Key Pinning (HPKP) enabled site for the first time, the connection is expected to be on a clean network; also called Trust On First Use (TOFU). This means the client is on a network which should be free from man in the middle attackers like a coffee shop or convention center. The first time the client connects to the server the HTTP Public Key Pinning hash is verified by the client against the certificate chain. If, and only if, the HPKP hash matches one of the certificates in the chain is the HPKP hash saved in the client browser until the expiration time specified in the server's header.

When the client browser reconnects, the HTTP Public Key Pinning hash is recalled from the browser cache and compared to the current certificate chain validated by the certificate authority. If the HPKP hash matches then a connection is made. If the certificate authority sends a different certificate chain, like when a CA is hacked or the client is being SSL proxied, then the client will not connect to the server and an error page will be shown to the user.

Public Key Pinning (HPKP) is also an excellent "canary trap" to see if the current network is obfuscating the connection in some way. Once you have a HPKP enabled site verified by the browser on a trusted network, you can travel to another network and go to the same site. If the site loads then you know the SSL connection is not being proxied or manipulated.

FYI: Google Chrome has announced plans to remove support for HTTP Public Key Pinning (HPKP). The discussion refers to HPKP misconfiguration thus resulting in web server owners accidentally making their own site inaccessible by losing all pinned keys. Additionally, a proxied attacker could trick clients into accepting a false HPKP thus denying access for the lifetime of the false key. For reference, a dynamically server defined HPKP header is no longer supported in Firefox, Edge, IE or Safari. Expect-CT is the new, recommended security header.

Setting up Public Key Pinning (HPKP)

On your https server you will need access to the server's private ".key" file. Using OpenSSL, we will create a Base64 encoded string from the Subject Public Key Information (SPKI) of the server's private key. We are using our leaf certificate because it is the only certificate we have full control over, but you can use the intermediate or root certificates as well. It is imperative that you use the proper openssl command for the type of certificate you own. If you have an RSA certificate use the "openssl rsa" argument. For an ECDSA certificate, like we have at calomel.org, use the "openssl ec" argument.

The name of our private key file is "calomel_ssl.key" for this example.

## For RSA Certificates
$ openssl rsa -in calomel_ssl.key -outform der -pubout | openssl dgst -sha256 -binary | openssl enc -base64

## For ECDSA Certificates
$ openssl ec -in calomel_ssl.key -outform der -pubout | openssl dgst -sha256 -binary | openssl enc -base64

The openssl command will output a string which will be the SHA256, base64 encoded pin for use in the public-key-pins header. For example, on calomel.org the output looks like the following:

## create a SHA256, base64 pin from calomel.org's ECDSA certificate

$ openssl ec -in calomel_ssl.key -outform der -pubout | openssl dgst -sha256 -binary | openssl enc -base64
read EC key
writing EC key
FdFOH8lP8ipUaas4cnj92Ifk81feECxL/RGDps3otfw=

Add the public-key-pins https header

Once the HPKP hash string is generated it is placed in the public-key-pins header on the https server to be sent to the clients. The following is the default syntax for the public-key-pins header according to the RFC. At minimum, there are two(2) base64 hashes and max-age which is in seconds.

## default syntax for the public-key-pins header
Public-Key-Pins: pin-sha256="AAA"; pin-sha256="BBB"; max-age=CCC

You will notice that there are two(2) pin-sha256 strings. According to the RFC, two(2) pin-sha256 are required, but only one of the pin-sha256 hashes has to be a valid match to a certificate in the current certificate chain. The other pin-sha256 string is a hash of a BACKUP certificate which is NOT found in the current certificate chain. This is quite confusing and I will try to explain.

The first pin-sha256 is the hash for our current valid certificate that we generated in the previous step. Ideally, the second pin-sha256 should be a backup certificate you purchased from a completely different certificate authority (CA) in case the first certificate was compromised or the CA was hacked. The second pin-sha256 is ONLY there as a BACKUP and ignored if the other pin-sha256 hash matches one of the current certificates from the CA.

Now, what if you do not have a backup certificate to make a second pin-sha256 hash? We mentioned before that the second pin-sha256 hash can NOT be a hash of a certificate in the current certificate chain. Well, you could put any hash string in the second pin-sha256 hash then. The second string is not verified by the client because there is no access to a second certificate authority. Truthfully, you can put a random string in or just copy our string "pin-sha256=LeSTjTf..." and the full header would still be completely valid.

Here are some configuration examples for Apache, Nginx and H2O. The first hash was created in the previous step using openssl. For this example, the second pin-sha256 hash is of our backup certificate. According to the RFC you can have as many pin-sha256 hashes as you want, but you must have at least two(2) pin-sha256 hashes.

## apache configuration
Header set public-key-pins "pin-sha256=\"FdFOH8lP8ipUaas4cnj92Ifk81feECxL/RGDps3otfw=\"; pin-sha256=\"LeSTjTfnibfKHJmDfIGoWrE7JwFWMUy/+3Ft55sBTGs=\"; max-age=604800; includeSubDomains"

## nginx configuration
add_header public-key-pins 'pin-sha256="FdFOH8lP8ipUaas4cnj92Ifk81feECxL/RGDps3otfw="; pin-sha256="LeSTjTfnibfKHJmDfIGoWrE7JwFWMUy/+3Ft55sBTGs="; max-age=604800; includeSubDomains';

## h2o configuration
header.add: "public-key-pins: pin-sha256=\"FdFOH8lP8ipUaas4cnj92Ifk81feECxL/RGDps3otfw=\"; pin-sha256=\"LeSTjTfnibfKHJmDfIGoWrE7JwFWMUy/+3Ft55sBTGs=\"; max-age=604800; includeSubDomains"

Verify the header with cURL

Use curl to verify the public-key-pins header is in place. The output has been shortened for clarity.

$ curl -kIL https://calomel.org/http_public_key_pinning_hpkp.html
...
public-key-pins: pin-sha256="FdFOH8lP8ipUaas4cnj92Ifk81feECxL/RGDps3otfw="; pin-sha256="LeSTjTfnibfKHJmDfIGoWrE7JwFWMUy/+3Ft55sBTGs="; max-age=604800; includeSubDomains
...

How to verify Public Key Pinning (HPKP) is working

Browsers will cache the HPKP if, and only if, the public-key-pins header is in the correct format and the browser can verify one of the pin-sha256 hashes against a certificate from the current certificate authority. If the syntax is wrong or if none of the pin-sha256 hashes match then the browser will completely ignore Public Key Pinning (HPKP) on the server and there will be no logs to help. HPKP problems are hard to diagnose.

In order for Public Key Pinning (HPKP) to be validated you must have a current version of the Firefox or Chrome browser for any modern OS; freebsd, linux, windows, android or iOS. We will be using Firefox and Chrome on linux to verify our website's Public Key Pinning (HPKP) setup and then you can use similar steps to verify your configuration.

Mozilla Firefox to verify HPKP

Open Firefox
Hit Ctrl-Shift-Q to open the developer Network Tab
Go to https://calomel.org/
In the Network Tab, click one the colored bars of one of the objects, like the first HTML file. This will open up a sub window with more tabs.
Click on the "Security" tab
Look for "Public Key Pinning: Enabled"
"Enabled" means Firefox accepted our Public Key Pinning and verified it is setup correctly. The certificate pinning is now saved so next time the browser opens our site the browser will compare the pinned hash against the certificate authorities response. Only if both match will our site load in the browser.

Google Chrome to verify HPKP

Open Google Chrome
In the first tab go to, https://calomel.org/
Open a send tab and go to, chrome://net-internals/#hsts
Enter our url "calomel.org" in the search box at the bottom under "Query domain".
Look for the line "dynamic_spki_hashes:" which will match the hash values we entered in the public-key-pins header for our server. If the values are populated then Google Chrome has verified our Public Key Pinning and saved the hashes for the next time the browser connects to calomel.org.

dynamic_pkp_domain: calomel.org
dynamic_pkp_include_subdomains: true
dynamic_pkp_observed: 145437751755.70646
dynamic_spki_hashes: sha256/FdFOH8lP8ipUaas4cnj92Ifk81feECxL/RGDps3otfw=,sha256/LeSTjTfnibfKHJmDfIGoWrE7JwFWMUy/+3Ft55sBTGs=

Questions?

Which browsers support Public Key Pinning (HPKP) ?

As of July of 2015 the latest versions of Mozilla Firefox and Google Chrome on any modern OS like Android, FreeBSD, Linux, IOS support HTTP Public Key Pinning.

How long should max-age be set ?

For review, max-age is the time in seconds the client browser should cache validated HPKP hashes and remember that this site is only to be accessed using one of the pinned keys. If you only have a single valid ssl certificate we suggest a short time frame of a few minutes to a few days. If you have a primary ssl certificate and a valid backup ssl certificate we suggest at least 60 days or 5184000 seconds.

What if I need to update my ssl certificate ?

The public-key-pins header tells clients the specified hashes are valid for at least "max-age" seconds. Before your current SSL certificate expires you should purchase another SSL certificate. Then add the pin-sha256 hash of your new certificate to your server's public-key-pins header at least "max-age" seconds before you expect to enable the new certificate and disable the old certificate.

If max-age is 604800 seconds, which is 7 days, then you need to make sure you have the new certificate's pin-sha256 hash in the public-key-pins header at least 7 days before you take out the old certificate. If not, clients will refuse to connect to the site because there is a "different" certificate which does not match any pin-sha256 hashes which were previously verified and locally cached for max-age seconds.