Public key pinning
Public key pinning is a technique to associate SSL/TLS hosts with specific public keys. It is very similar to certificate pinning, but verifies only public key of the certificate (in most cases public key is the only important factor for pinning, because attacker can use public key only if he has corresponding private key; in most cases certificate with pinned public key is publicly available from SSL server).
Public key pinning (and certificate pinning) protects clients against fraudulent SSL certificates. Such certificates can be issued either by malicious or hacked certificate authorities (CAs) or, in most cases, by (partial) compromise of victim's upstream network infrastructure (in some cases such compromise could allow even issuance of fraudulent EV certificates).
Public Key Pinning Extension for HTTP (HPKP)
Public Key Pinning Extension for HTTP (HPKP) a.k.a. RFC 7469 is an Internet standard for instructing HTTP clients (user agents) to do public key pinning for HTTPS websites that send appropriate HTTP header (or are included in preloaded pins list).
Basically, according to the standard, user agents (e.g. web browsers) note public key hashes mentioned in Public-Key-Pins HTTP header and associate them with HTTPS address (and optionally all its subdomains) that had sent the header. During next max-age (specified in the header) seconds SSL/TLS connections to that address will succeed only if server certificate (or any certificate in its certificate chain) has public key with matching hash. Backup pins (hashes of backup public keys) are required, otherwise it would be impossible to change keys of server. When changing keys, new backup keys/pins must be generated (taking into account that whole set of keys can rotate in time no less than max-age). Although CA certificates can be pinned (in such case all certificates signed by pinned CA certificate will be considered valid while verifying public key pinning), there are risks that CAs may change their certificates or that customer's account (or entire CA) may get compromised.
Public Key Pinning Extension for HTTP also provides reporting of public key pinning validation failures via HTTP POST requests to URL mentioned in report-uri directive (see the standard for details). Reporting is outside of scope of this calculator.
GitHub Pages hosted copy
A copy hosted on GitHub Pages is available at: https://hpkpcalc.github.io/
GitHub repository of this copy is available here. All involved files are exact copies of latest release in main GitHub repository of this project.
Verification of downloaded files
All files are signed by OpenPGP key from this site.
File forge.min.js can be re-created as described in README.md, other files are clearly readable and simple enough to be easily audited.
The following table shows releases and their Git commit SHA1s:
|Release date||Release number||Commit SHA1|
|2014.06.22. timestamped 2014.07.06.||v1.0.1||e509aa2693ce4b10a6567725e472a64a5ff0f282|
Releases (all changed files, their signatures and Git commit SHA1) are timestamped using BitCoin network.
In all cases result verification by shell commands is highly recommended.
Other HPKP calculators
There are some other public key pins calculators available. They can be used in conjunction with this calculator (or with one another) to verify calculated pins.
- https://tools.ietf.org/html/rfc7469#appendix-A - POSIX (Linux) shell commands to calculate public key pins, mentioned in the standard. Very handy for verification of results of other calculators (including this calculator).
- https://gist.github.com/woodrow/9130294 - sample Linux shell commands that calculate public key pins (see comments for modified commands). Very handy for verification of results of other calculators (including this calculator).
- https://github.com/hannob/hpkp - Linux shell script (using commands very similar to those mentioned above) that calculates public key pins from certificate/CSR files.
- http://blog.stalkr.net/2011/08/hsts-preloading-public-key-pinning-and.html - article and Python script for public key pin calculation from certificates in PEM format.
- https://certpins.appspot.com/ - online public key pin calculator that makes calculations on server.
- https://www.imperialviolet.org/2011/05/04/pinning.html - article on public key pinning.
- https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security - Wikipedia article on HTTP Strict Transport Security (HSTS).
- https://en.wikipedia.org/wiki/HTTP_Public_Key_Pinning - Wikipedia article on HTTP Public Key Pinning (HPKP).
- https://developer.mozilla.org/en-US/docs/Web/Security/Public_Key_Pinning - MDN article on HTTP Public Key Pinning (HPKP).