Enable HTTP Public Key Pinning (HPKP) Nginx With report-uri

Previously, we have talked about HTTP Public Key Pinning (HPKP). HPKP is a security feature is to prevent fraud TLS certificates. Here Are the Steps to Enable HTTP Public Key Pinning (HPKP) on Nginx. We are using Ubuntu 16.04 LTS and latest version of Nginx. Reader will need to adjust some come commands for non deb GNU/Linux distro.

What is HTTP Public Key Pinning (HPKP) and Why We Need?

If a bad steal the CA’s private key and browser trusts the certificate, the bad can forge valid certificates for any website. So performing a man-in-the-middle (MITM) attack against every website is not impossible. HTTP Public Key Pinning (HPKP) significantly decrease the risk of MITM by allowing website operators to limit the certificates that can participate in their website’s chain of trust and to detect in-progress attacks.

HTTP Public Key Pinning (HPKP) is a security measure for the HTTPS websites to nullify the chance of impersonation by script-kiddies using fraudulent certificates. Nginx web server will serve a list of public key hashes by header, client browser will expect that the server will use one or more of those public keys in its certificate chain. HTTP Public Key Pinning (HPKP) is standardized in RFC 7469. The Nginx Server will communicate to the HPKP policy to the user agent via an HTTP response header field named Public-Key-Pins or Public-Key-Pins-Report-Only. The HPKP policy specifies :

1. hashes of the subject public key info of one of the certificates in the website’s authentic X.509 public key certificate chain
2. at least one backup key
3. a time duration which the user agent shall enforce public key pinning via max-age directive
4. optional includeSubDomains directive to include all subdomains
5. optional report-uri directive with URL where to send pinning violation reports.

At least one of the public keys of the certificates in the certificate chain needs to match a pinned public key in order for the chain to be considered valid by the user agent. At the time of publishing this guide, RFC 7469 allowed hash algorithm SHA-256. Hashes for HPKP policy can be generated by shell commands or third-party tools. The HTTP Public Key Pinning (HPKP) will not be valid without minimum one backup key. Report URI should not be on same domain.

Steps to Enable HTTP Public Key Pinning (HPKP) : Nginx

Users can register for report-uri.io‘s free service. You will get few of the needed stuffs :

1. HTTP Public Key Pinning keys
2. Reporting URI service
3. Testing tools

Technically, we can generate it with this command, where our web server’s certificate is www.thecustomizewindows.com.csr and we are at that directory :

You will get something as output like :

That is “KEY”.

More detailed steps are written on our old guide. report.io service does the work. We need minimum another TLS certificate or any other web server specific certificate to run the above command to get another “KEY”. The second one is “Backup Key”. Further information can be found on :

Normally, users use /etc/nginx/sites-available/default file for Nginx we save site configuration. We have to add in this format for Nginx with add_header directive :

Run nginx config test and restart Nginx. Test with SSL Lab’s test. You can test our header :

You’ll get the response :