Public-Key-Pins calculator

From Projects by Davis Mosenkovs
Jump to: navigation, search

JavaScript Public-Key-Pins (HPKP) calculator is JavaScript library/application for easy calculation of public key hashes for use in Public Key Pinning Extension for HTTP.

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.

Browser compatibility

For browser compatibility with Public Key Pinning Extension for HTTP and HTTP Strict Transport Security (HSTS), see Public-Key-Pins test.

Online preview

Online preview hosted on this site is available here. It is HTML/JavaScript form from GitHub put online. All involved files are exact copies of latest release in GitHub.

WARNING! For high-security solutions offline form from GitHub repository and result verification by shell commands (mentioned below) is highly recommended.

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.

Download

Use of downloadable HTML/JavaScript form is recommended. HTML form for offline use can be downloaded from GitHub repository.

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
2014.07.13. v1.0.2 7fe0cf3fde37883bd3999562b057b99cfceb5bd7
2016.01.02. v1.0.3 6e3ca2469f1dc5d6f86cc8f1f3b40de7cbce0458

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://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.

More info