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.
X.509 certificates or certificate signing requests.
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.
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
GitHub Pages hosted copy
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.
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