Public-Key-Pins-Report-Only: Syntax, Directive, Examples

The Public-Key-Pins-Report-Only is an HTTP Response Header created for pinning violations. The HTTP Public-Key-Pins-Report-Only response header sends a report to the report-URI (Uniform Resource Identifier) for pinning violations. Pinning is a method that permits you to define a cryptographic identity. Pinning provides security improvement for a website that depends on SSL Certificates. SSL (Secure Sockets Layer) certificate is a digital authenticated certificate that validates the identity of a web browser and allows the connection with the encrypted web server. URI(Uniform Resource Identifier) identifies the device, but unlike URL (Uniform Resource Locator), it does not recognize or indicate where to locate the device. A cryptographic identity, also known as Identity-based cryptography is a type of public-key cryptography, where a public key is used to represent a group, team, organization, or individual. The cryptographic identity will be accepted by user agents before visiting a website. The Public key is a public string that can be represented by an IP address, domain, or email address. The disadvantage of the HTTP Public-Key-Pins-Report-Only response header is not like the HTTP Public-Key-Pins response header, even if pinning is violated, it still allows search engine crawlers and web browsers to connect to the webserver. The support for HPKP (HTTP Public Key Pinning) is not available with the HTTP Public-Key-Pins-Report-Only response header. Due to limited restrictions, the HTTP Public-Key-Pins-Report-Only response header no longer works on modern browsers (such as Chrome and Edge). HTTP Public-Key-Pins is a response header used to link a specific cryptographic public key with a web server to reduce the risk of MITM (man in the middle) attacks with forged certificates. MITM (man in the middle) attacks refer to cyberattacks, wherein a hacker prevents the communication between the client and the webserver.

What is Public-Key-Pins-Report-Only?

The HTTP Public-Key-Pins-Report-Only response header fields, also known as the HTTP PKP-RO header fields, are used by a web server to specify that the User-Agent to is required for a Pin Validation before visiting a website. When pinning violation occurs, the HTTP Public-Key-Pins-Report-Only response header sends a report to report-URI. Although this still allows the search engine crawlers and web browsers to access the webserver, this feature is no longer recommended. The Public-Key-Pinning method was devalued, the capabilities were overshadowed by the Certificate Transparency and Expect-CT header. The Expect-CT Header 

allows the websites to choose the enforcement of Certificate Transparency requirements, to reduce the undetected use of wrongly issued certificates. Certificate Transparency is an open framework created to provide security and monitor the wrongly issued certificates. Certificate Transparency requires all new certificates to be publicly logged which maintains a cryptographic record of issued TLS(Transport Layer Security) certificates. Transport Layer Security certificate is a public key certificate issued by the Certificate Authority.

What is the Syntax of Public-Key-Pins-Report-Only?

The syntax for the HTTP Public-Key-Pins-Report-Only response header is below.

Public-Key-Pins-Report-Only: pin-sha256="<pin-value>";
max-age=<expire-time>;
includeSubDomains;
report-uri="<uri>"

What is the Directive of Public-Key-Pins-Report-Only?

The directives for the HTTP Public-Key-Pins-Report-Only response header are described below.

  • pin-sha256=”<pin-value>”: The quoted string is the Base64 encoded Subject Public Key Information (SPKI) fingerprint. We can have multiple pins for various public keys.
  • max-age=<expire-time>: This directive will be insignificant for the HTTP Public-Key-Pins-Report-Only response header. The header will not be cached.
  • includeSubDomains Optional: This optional parameter is identified, which applies to all subdomains on the site.
  • report-uri=”<uri>”: Failed pin validation is reported and this directive should be used with this header; otherwise, this header will be a no-op.

How to use Public-Key-Pins-Report-Only?

The syntax for the HTTP Public-Key-Pins-Report-Only response header is used by a web server to specify that the User-Agent to is required for a Pin Validation before visiting a website. The HTTP Public-Key-Pins-Report-Only response header sends a report to the report-URI (Uniform Resource Identifier) for pinning violations. Even if there is a failure on pin violation, the web browsers will still be allowed to connect to the webserver.

Examples of Public-Key-Pins-Report-Only Use

An example for HTTP Public-Key-Pins-Report-Only response header is below.

In this example, “pin-sha256=”dOFcREXWKaEVoYWhhneDttWpY3oDEkE5g6+soQD7xXz=” pins the server’s public key used in verification. The second pin validation “pin-sha256=”N7SgtCzM3elUxkcjR2S5P4hhyBNf6lHkmjAHKhpGPXO=” also pins the backup key. Moreover, the key pinning will also be valid for all subdomains, which is told by the includeSubDomains declaration. Finally, report-uri=”https://www.sample.org/hpkp-report” explains where to report failed pin validation.

Public-Key-Pins-Report-Only:
pin-sha256 = "dOFcREXWKaEVoYWhhneDttWpY3oDEkE5g6+soQD7xXz=";
pin-sha256 = "N7SgtCzM3elUxkcjR2S5P4hhyBNf6lHkmjAHKhpGPXO="; includeSubDomains;
report-uri = ”https://www.sample.org/hpkp-report” 

What are the Specification Documents for Public-Key-Pins-Report-Only?

The specification documents for the HTTP Public-Key-Pins-Report-Only response header are below.

  • RFC5234: The RFC5234 is an Augmented BNF(Backus-Naur Form) for syntax specifications. RFC5234 is a chained string of values in a compact form, that uses a period (“.”) to separate the characters within that value. 
  • RFC7230: The RFC7230 is HTTP/1.1 Message Syntax and Routing for request and response protocols. 

What are the similar HTTP Headers to the Public-Key-Pins-Report-Only?

A similar header for the HTTP Public-Key-Pins-Report-Only response header is below.

HTTP Public-Key-Pins response header: The HTTP Public-Key-Pins response header and HTTP Public-Key-Pins-Report-Only response header fields, also recognized as the PKP and PKP-RO header fields. The PKP and PKP-RO header fields are applied by a server to require a pin validation from the User-Agent.

Koray Tuğberk GÜBÜR

Leave a Comment