Public-Key-Pins-Report-Only

The HTTP Public-Key-Pins-Report-Only response header sent violation reports when certificate public key pins failed validation, without blocking connections.

Legacy

HTTP Public Key Pinning (HPKP) was defined in its specification and has been deprecated. Chrome and Firefox removed HPKP support. No modern browser implements this header. Certificate Transparency (CT) replaced HPKP as a safer alternative for certificate verification. CT is now enforced by default in all major browsers without requiring any header.

Table of Contents

Usage
Directives
Example
Takeaway
See also

Usage

Public-Key-Pins-Report-Only functioned as a testing variant of the Public-Key-Pins header. When a browser received this header, the browser stored the specified public key hashes and validated them on subsequent connections. Unlike Public-Key-Pins, validation failures triggered report submissions to the configured report-uri endpoint but did not block the connection from completing.

The header allowed site operators to test pin configurations before enforcing them. A site deployed Public-Key-Pins-Report-Only with candidate key hashes and monitored incoming violation reports. If reports appeared, the configuration contained errors or unintended key exclusions. Once reporting showed clean validation, operators switched to Public-Key-Pins to enforce the pin policy.

The directive syntax matched Public-Key-Pins, including pin-sha256, max-age, includeSubDomains, and report-uri. The max-age directive was ignored in the report-only variant, since the header never instructed browsers to cache or enforce pins beyond the current request.

HPKP carried serious risk. Misconfigured pins locked legitimate users out of sites for the duration of the pin lifetime. This self-imposed denial of service risk led browsers to deprecate and remove HPKP support entirely. Certificate Transparency logs now provide certificate monitoring without requiring sites to predict and pin future key hashes.

Directives

pin-sha256

The pin-sha256 directive contains a Base64-encoded SHA-256 hash of a certificate's Subject Public Key Info (SPKI). At least two pin-sha256 directives are required: one matching a key in the current certificate chain and one backup pin for a key not yet deployed.

max-age

The max-age directive is included for syntactic compatibility with Public-Key-Pins but browsers ignore this value when processing Public-Key-Pins-Report-Only. The report-only variant does not cache or enforce pins beyond the current connection.

includeSubDomains

The includeSubDomains directive extends the pin validation to all subdomains of the host. Without this directive, validation applies only to the exact hostname in the request.

report-uri

The report-uri directive specifies a URL where the browser sends JSON violation reports when pin validation fails. This is the primary purpose of the report-only header, allowing operators to detect certificate mismatches without blocking traffic.

Example

A server tests pin configuration with three public key hashes. The browser validates the pins on each connection and sends violation reports to the configured endpoint, but allows the connection to proceed regardless of validation outcome.

Public-Key-Pins-Report-Only: pin-sha256="WrVO/NVwDzspUoFoRGbR0vR7
gEj25C/saZilznWAQlM="; pin-sha256="5kJvNEMw0KjrCAu7eXY5HZdvyCS13
BbA0VJG1RSP91w="; pin-sha256="r/mIkG3eEpVdm+u/ko/cwxzOMo1bk4TyHI
lByibiA5E="; max-age=5184000; includeSubDomains; report-uri="https://
example.re/hpkp-report"

A minimal test configuration pins a single key along with a backup and specifies a reporting endpoint. The max-age value is present for syntax compatibility but browsers ignore the directive.

Public-Key-Pins-Report-Only: pin-sha256="cN0QSpPIkuwpT6iP2YjEo1bEw
GpH/yiUn6yhdy+HNto="; pin-sha256="WGJkyYjx1QMdMe0UqlyOKXtydPDVrk7
sl2fV+nNm1r4="; max-age=864000; report-uri="https://example.re/
pin-report"

Takeaway

The Public-Key-Pins-Report-Only header allowed sites to test certificate public key pinning configurations by sending violation reports without blocking connections. Modern browsers no longer support this deprecated mechanism, and Certificate Transparency provides certificate monitoring without the operational risks of HPKP.