Skip to content

Public Key Pinning (HPKP)

Public Key Pinning is a security mechanism designed to protect against [[Man-in-the-Middle (MITM)|MITM]] attacks by reducing the reliance on external Certificate Authorities (CAs).^[600-developer-tools-security-strict-transport-security.md]

Overview

The HTTP header Public-Key-Pins allows a server to associate a specific domain with a cryptographic public key.^[600-developer-tools-security-strict-transport-security.md] By pinning these keys, the website operator instructs the client (browser) to reject connections if the presented TLS certificate does not match the pinned key, even if the certificate is signed by a trusted CA.^[600-developer-tools-security-strict-transport-security.md] This prevents attackers from using a fraudulently obtained CA certificate to intercept traffic.

Implementation

The header is set by the server and includes the hash of the public key (fingerprint) and a validity period.^[600-developer-tools-security-strict-transport-security.md]

Syntax Example: 

Public-Key-Pins: pin-sha256="base64=="; max-age=2592000; includeSubDomains

Configuration Steps: 1. Generate the Public Key: The public key is derived from the site's TLS certificate. 2. Create the Fingerprint: The public key is processed using a tool like openssl to generate a Base64-encoded SHA-256 hash (fingerprint). 3. Set the Header: The resulting hash replaces the base64== placeholder in the header directive^[600-developer-tools-security-strict-transport-security.md].

Directives

  • pin-sha256: The hashed value of the public key.
  • max-age: The time (in seconds) that the browser should remember the pin.
  • includeSubDomains: Applies the pinning policy to all subdomains of the current site.
  • [[HTTP Strict Transport Security (HSTS)]]
  • [[Content Security Policy (CSP)]]
  • [[TLS]]

Sources

  • 600-developer-tools-security-strict-transport-security.md