HTTP Public Key Pinning (HPKP) middleware

Common errors

• NET::ERR_SSL_PINNING_FAILURE

  cause The public key pins declared in the `Public-Key-Pins` HTTP header do not match the public key of the server's certificate presented during a TLS handshake.
  fix During testing, verify `sha256s` values. If in production, and users are locked out, you must either deploy a certificate matching one of the original pinned keys, or if no backup key is available, wait for `maxAge` to expire (which could be months). Using `reportOnly: true` initially can help avoid this.

• My HPKP header isn't being set on my Express/Connect application.

  cause The `hpkp` middleware might be placed incorrectly in the middleware chain, or the `setIf` option is preventing it from being applied under current request conditions (e.g., not an HTTPS request).
  fix Ensure the `hpkp` middleware is applied before any routes that should be protected. Check your `setIf` function's logic to confirm it evaluates to `true` for the requests you intend to pin. Verify that `maxAge` is a positive integer.

Warnings

• deprecated The HTTP Public Key Pinning (HPKP) standard itself has been widely deprecated by browser vendors, including Chrome, due to its inherent risks and potential for website self-DDoS.
  Fix: Avoid using HPKP in new applications. For existing applications, strongly consider migrating to alternative security mechanisms like Certificate Transparency and Expect-CT headers, which offer similar protections with fewer risks.
• breaking Misconfiguration of HPKP, particularly incorrect `sha256s` or loss of access to pinned keys, can permanently block legitimate users from accessing your website, as their browsers will refuse connections.
  Fix: Always use `reportOnly: true` and a very short `maxAge` (e.g., 60 seconds) during initial deployment and testing. Ensure robust processes for key rotation and backup key management. Never deploy HPKP without a verified fallback strategy for pin mismatches.
• gotcha The `hpkp` package is in maintenance mode and will not receive new feature development. This means it may not adapt to future security best practices or changes in related web standards.
  Fix: Consider that the underlying technology is no longer actively developed or recommended. If you must use it, be aware of its static nature and potential for obsolescence.
• gotcha The `sha256s` array must contain Base64-encoded Subject Public Key Information (SPKI) fingerprints. Using incorrect hash formats or non-SPKI hashes will lead to pinning failures.
  Fix: Ensure that the provided hashes are correctly derived from the SPKI of your active and backup certificates, and are properly Base64 encoded. Tools are available to generate these from certificate files.
• gotcha Browser support for HPKP is inconsistent and has been largely removed. Modern browsers like Chrome have dropped support, rendering the header ineffective for many users.
  Fix: Before deploying, understand that the impact of HPKP will be limited to older or specific browser versions that still honor the header. The security benefits are minimal given current browser landscape.

Install

• npm install hpkp npm
• yarn add hpkp yarn
• pnpm add hpkp pnpm

Imports

• hpkp
  wrong:

  import { hpkp } from 'hpkp'

  correct:

  import hpkp from 'hpkp'

  The `hpkp` package exports the middleware function as its default export.
• hpkp

  const hpkp = require('hpkp')

  CommonJS import for Node.js environments. This is shown in the official usage example.
• HpkpOptions
  wrong:

  import { HpkpOptions } from 'hpkp'

  correct:

  import type { HpkpOptions } from 'hpkp'

  If using TypeScript, `HpkpOptions` is the interface for the configuration object passed to the `hpkp` middleware. Use `import type` as it's a type-only import.

Quickstart

This quickstart demonstrates how to integrate the `hpkp` middleware into an Express.js application, setting a Public Key Pinning header with example SHA256 hashes and optional configurations. It highlights the use of `maxAge`, `sha256s`, and conditional header setting via `setIf`.

const express = require("express");
const hpkp = require("hpkp");

const app = express();

const ninetyDaysInSeconds = 7776000; // 90 days
app.use(
  hpkp({
    maxAge: ninetyDaysInSeconds,
    sha256s: [
      // These should be your actual SPKI hashes for primary and backup keys
      "AbCdEf123=", 
      "ZyXwVu456=" 
    ],
    includeSubDomains: true, // optional
    reportUri: "https://example.com/hpkp-report", // optional
    reportOnly: false, // optional, set to true for testing

    // Set the header based on a condition. This is optional.
    setIf(req, res) {
      return req.secure; // Only set HPKP for HTTPS requests
    },
  }),
);

app.get('/', (req, res) => {
  res.send('HPKP header should be set if using HTTPS');
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
  console.log('Remember HPKP is deprecated and risky. Use with extreme caution.');
});