JavaScript Public-Key-Pins (HPKP) calculator - JavaScript library for easy calculation of public key hashes for use in RFC 7469 Public Key Pinning Extension for HTTP. Ready to use HTML form is provided along with the library.
Version 1.0.3
Copyright (C) 2014-2016 Davis Mosenkovs
RFC 7469 Public Key Pinning Extension for HTTP is an Internet standard for instructing HTTP clients to associate servers with specific SSL certificates. Such associations should be able to mitigate most MITM attacks on HTTP over SSL/TLS connections.
JavaScript Public-Key-Pins (HPKP) calculator allows easy calculation of Public-Key-Pins HTTP header value for specified
X.509 certificates or certificate signing requests.
It can be used as offline HTML/JavaScript form or embedded into web site or other JavaScript application (using API provided by pkps.js).
Before using this program (tool) user should be familiar with RFC 7469 Public Key Pinning Extension for HTTP and RFC 6797 HTTP Strict Transport Security (HSTS)! Incorrect usage (or malfunction) of this program (tool) may lock users out of HTTPS server for time (in seconds) specified in max-age directive of HTTP header Public-Key-Pins. For use on production systems special precautions (e.g. result verification by POSIX commands or other calculators) are recommended.
All files contained in this repository can be downloaded (after reading and accepting LICENSE) for off-line use of calculator.html in web browser.
File forge.min.js can be re-created as specified below (ensuring its integrity), other files are clearly readable and simple enough to be easily audited.
Additionally all files are signed by OpenPGP key (fingerprint: ED9F BB77 211D 142E AAF8 E9C1 FA00 7FA5 D26E 2AE4) that must be mentioned on
https://projects.dm.id.lv/, GnuPG/PGP keyservers and https://keybase.io/davisnt.
All files (including signatures) and Git commit SHA1 of releases are timestamped on BitCoin network (see
project website for details).
Download of ZIP file is suggested for signature verification, because Git clients may break signatures by converting newlines in signed files.
It is suggested to use a secure off-line computer for generation of RSA key-pairs, Certificate Signing Requests (CSRs) and Public-Key-Pins. It is highly recommended to store backup keys (along with CSRs) in safe and secure off-line storage. It is a good practice to create several backup keys.
It must be taken in mind that during next max-age seconds only keys used in Public-Key-Pins generation can be used on HTTPS address (and optionally all subdomains) that sends generated Public-Key-Pins HTTP header. Thus several backup keys are recommended (one required by the standard). During key change one of backup keys must be used as the new key, a new backup key should/must (one backup key is required by the standard) be created, and new Public-Key-Pins value (containing pin of new backup key and not containing pin of old key) must be created and set up.
Key generation/storage on server is highly discouraged, because in case of server compromise attacker could gain access to private keys of all pinned keys and there would be no way to change key to uncompromised one (without locking users out of server or changing website address).
Also special precautions must be taken when pinning keys to all subdomains (using includeSubDomains directive). For example, if company's main website https://example.com sends Public-Key-Pins header containing includeSubDomains directive and customer self-service portal https://my.example.com uses key not pinned in Public-Key-Pins header, then users will be locked out of https://my.example.com
Although downloading (and verifying) off-line copy is preferred, 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.
API is documented in main script file pkps.js. Usage example can be found in calculator.html (it covers main functionality of this library).
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. http://www.gnu.org/copyleft/gpl.html
This project uses Forge library which is distributed under the
terms of either the BSD License or the GNU General Public License (GPL) Version 2.
The file forge.min.js was generated on CentOS by:
wget https://github.com/digitalbazaar/forge/archive/0.5.5.zip
unzip 0.5.5.zip
cd forge-0.5.5
npm install
npm run minify