What is an HTTP Public Key Pinning?

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. 

How HTTP Public Key Pinning looks like

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”. 

What are the Pins in cybersecurity?

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.

How to get the certificate pin?

To get the current certificate pin you can cheat a little and use this web service (https://report-uri.io/home/pkp_hash) 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 – after all, they are pins for certificates that are outside your control!

Importance of having a Backup Pin.

The backup pin is a must – 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 
• Deleted
• 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 webserver 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 (https://report-uri.io/home/pkp_analyse).

At the time of writing, this header is relatively new and people do not use it as much.  It is also worth knowing that there appear to be slight implementation differences in browsers. 

The main difference in browser, that my colleague and I noticed is that on one machine running Firefox 38 ESR, the HPKP header didn’t work until we tweaked the configuration.  At the same time, Firefox 43 seemed to work exactly as we would expect without any configuration tweaks. 

The tweak was to change:

security.cert_pinning.process_headers_from_non_builtin_roots

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 there 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:

security.cert_pinning.enforcement_level

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 a 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.

*** UPDATE *** Since this article was published HPKP has been deprecated and removed from all modern browsers. Other efforts have been put into place that attempt to deal with similar issues, however, nothing has filled the void completely. The reason for this being deprecated is reportedly because it was too easy to break your own web service (Denial of Service) with no was to recover.

For more information about our services Contact us