HTTP Public Key Pinning (HPKP)

HTTP Public Key Pinning is a mechanism that can prevent Man-in-the-Middle attacks against TLS connections to HTTP services.  Essentially, the web service tells the browser which certificates it should expect and that it should reject all others.  It is a header and looks a little like this:

Public-Key-Pins: pin-sha256=”eZ2mT3Q9rS+P5WO3beF1Du9Jojk2oaO3eM0BYjl+uKk=”; pin-sha256=”2RvDQRJ3jUJaIvGRBMATMgSMrTecA3HXQXeUgRFKIcc=”; max-age=5184000; includeSubDomains

Each of the sections prefixed with “pin-sha256” are the identifiers for the certificates and they are known as “pins”.  Pins are base64 encoded, sha256 hashes of the public keys.  You need to have two pins, one is your current certificate, and one is a backup certificate in case the current one is compromised or expires.  The good news is, you can produce this hash based on the CSR (Certificate Signing Request) and you don’t actually need to buy a cert at this stage to be able to have a backup pin in place!

The “max-age” section is better thought of as a Time To Live (TTL).  That is because it is the value in seconds for which the browser is instructed to honour the security header.  5,184,000 is approximately 2 months.

Optionally, you can include all subdomains as well – though you need to think about this and make sure it is appropriate for your environment.

To get the current certificate pin you can cheat a little and use this web service ( written by Scott Helme.  You only need the pin is associated with your site which is usually the top entry when the service finishes its analysis.  The ones below are not required and potentially weaken the policy – they are after all pins for certificates that are outside your control!

The backup pin is required – without it, browsers will ignore the header.  It is important to have a backup pin in place anyway just in case your existing cert becomes compromised or deleted, or (and more likely) the certificate expires.  To generate the backup pin, first get yourself a private key and CSR.  Once you have these you can use OpenSSL:

openssl req -in yoursigningrequest.csr -pubkey -noout | openssl rsa -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64

As for sticking them in your web server config, this can be pretty easy.  For example, with Apache you can simply add the header to your .htaccess file.  For example:

Header always set Public-Key-Pins “pin-sha256=\”eZ2mT3Q9rS+P5WO3beF1Du9Jojk2oaO3eM0BYjl+uKk=\”; pin-sha256=\”2RvDQRJ3jUJaIvGRBMATMgSMrTecA3HXQXeUgRFKIcc=\”; max-age=5184000; includeSubDomains”

Another good tool, also by Scott, for analysing your configuration is here (

At the time of writing, this header is relatively new and isn’t really deployed much.  It is also worth knowing that there appears to be slight implementation differences in browsers.  The main one that my colleague and I noticed is that on one machine running Firefox 38 ESR, the HPKP header didn’t work until its configuration was tweaked.  At the same time, Firefox 43 seemed to work exactly as we would expect without any configuration tweaks.  The tweak was to change:


From false to true.  This was not required in Firefox 43.  The only theory I have about the cause of this is that the certificate being used requires an additional “sf_bundle” to be included in the Apache configuration as the CA root is listed as part of the default store in both versions of Firefox.

Whilst discussing Firefox, there may be a tweak that the neurotic amongst us want to change…  It seems their are four states for this protection in Firefox:

0 – HPKP Disabled
1 – HPKP Enforced, except when certificate is chained to user-supplied root CA
2 – HPKP Fully Enforced
3 – HPKP Enforced Testing

This is controlled by the setting:


Personally, I have chosen to change it to “2” as there should not be any user-supplied root CA in my Firefox configuration.  Having said that, it is fair to say that if an attacker is able to insert a root CA into my machine, they can probably do a lot of other attacks as well.  Including simply disabling HPKP.  Both of these values can be found in “about:config” within Firefox.

And final note on this topic, make sure you replace your certs well in advance of them expiring!  If you do not have a backup pin in place for the next certificate, clients will not be able to connect to your web service once you change certificate.  This is because the mechanism is designed to only accept the known certificate, so even if it is a legitimate cert which is chained to a legitimate root CA, it will be ignored.

This entry was posted in Security Basics. Bookmark the permalink.

3 Responses to HTTP Public Key Pinning (HPKP)

  1. Pingback: Añadir cabeceras HTTP de seguridad en WordPress

  2. Jan Jurkus says:

    How would this compare to the DANE/TLSA thingy? Shouldn’t that provide somewhat more security, provided if everything works on the DNSSEC side?

    For instance, with a phising attack with a faked banking site?

    • Felix says:

      Hey. they are actually fairly different defensive measures. HPKP is about proving that this particular TLS/SSL cert is the one that the site authors approve. The most obvious attack that this will have an impact on are those where the attacker has access to a root CA that is installed in the browser. Such an attacker might be nation state or organised crime and have coerced their way, technically or otherwise, to the point where they can create valid TLS/SSL certificates for a victim service. For instance the certs that Symantec made for Google, without Googles permission. The idea is that trust doesn’t just get chained back to a root certificate anymore.
      DNSSEC and so on, don’t do any service-based TLS certificate validation, for example, at the HTTP layer, instead it is a mechanism whereby the client can in theory verify that they are connecting to the correct IP and that the DNS service hasn’t been poisoned.
      Hope that helps!

Leave a Reply

Your email address will not be published. Required fields are marked *