View source for SecurityEngineering/Public Key Pinning/Implementation Details

== Public Key Pinning Implementation Cheat Sheet ==
This page attempts to document the implementation of HTTP Public Key Pinning (HPKP) in Firefox. Currently the implementation is limited to a set of preloaded pins that ships with the browser. This set of pins is generated partially from data provided by Mozilla and partially from data provided by Google's Chromium project.

=== Important Files ===
{|
|-
| [https://dxr.mozilla.org/mozilla-central/source/security/manager/ssl/StaticHPKPins.h security/manager/ssl/StaticHPKPins.h]
| The built-in preload list.
|-
| [https://dxr.mozilla.org/mozilla-central/source/security/manager/ssl/StaticHPKPins.errors security/manager/ssl/StaticHPKPins.errors]
| A log of debugging information from the last time the preload list was generated.
|-
| [https://mxr.mozilla.org/mozilla-central/source/security/manager/tools/genHPKPStaticPins.js security/manager/tools/genHPKPStaticPins.js]
| Generates the preload list.
|-
| [https://mxr.mozilla.org/mozilla-central/source/security/manager/tools/PreloadedHPKPins.json security/manager/tools/PreloadedHPKPins.json]
| Mozilla-specific information used when generating the preload list.
|-
| [https://dxr.mozilla.org/mozilla-central/source/security/manager/ssl/PublicKeyPinningService.cpp security/manager/ssl/PublicKeyPinningService.cpp]
| The core of the HPKP implementation.
|-
| [https://mxr.mozilla.org/mozilla-central/source/security/certverifier/NSSCertDBTrustDomain.cpp security/certverifier/NSSCertDBTrustDomain.cpp]
| NSSCertDBTrustDomain::IsChainValid is where certificate verification (indirectly) calls into the PublicKeyPinningService.
|-
| [https://mxr.mozilla.org/mozilla-central/source/security/certverifier/CertVerifier.cpp security/certverifier/CertVerifier.cpp]
| (See anything involving "chainValidation".)
|}

=== What to do when Firefox's root certs change ===
* Look at https://dxr.mozilla.org/mozilla-central/source/security/manager/tools/PreloadedHPKPins.json to see if the root is pinned by anyone.
* If the root is in use, file a Bugzilla bug (Product Core, Component Security:PSM) to request that the pinning list be regenerated and that the corresponding site operators be notified when the root change is checked in (linking back to the root change request bug).

=== Something is Broken, and we Think it's Pinning ===
TODO