summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc7469.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc7469.txt')
-rw-r--r--doc/rfc/rfc7469.txt1571
1 files changed, 1571 insertions, 0 deletions
diff --git a/doc/rfc/rfc7469.txt b/doc/rfc/rfc7469.txt
new file mode 100644
index 0000000..f500480
--- /dev/null
+++ b/doc/rfc/rfc7469.txt
@@ -0,0 +1,1571 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) C. Evans
+Request for Comments: 7469 C. Palmer
+Category: Standards Track R. Sleevi
+ISSN: 2070-1721 Google, Inc.
+ April 2015
+
+
+ Public Key Pinning Extension for HTTP
+
+Abstract
+
+ This document defines a new HTTP header that allows web host
+ operators to instruct user agents to remember ("pin") the hosts'
+ cryptographic identities over a period of time. During that time,
+ user agents (UAs) will require that the host presents a certificate
+ chain including at least one Subject Public Key Info structure whose
+ fingerprint matches one of the pinned fingerprints for that host. By
+ effectively reducing the number of trusted authorities who can
+ authenticate the domain during the lifetime of the pin, pinning may
+ reduce the incidence of man-in-the-middle attacks due to compromised
+ Certification Authorities.
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 5741.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ http://www.rfc-editor.org/info/rfc7469.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Evans, et al. Standards Track [Page 1]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+Copyright Notice
+
+ Copyright (c) 2015 IETF Trust and the persons identified as the
+ document authors. All rights reserved.
+
+ This document is subject to BCP 78 and the IETF Trust's Legal
+ Provisions Relating to IETF Documents
+ (http://trustee.ietf.org/license-info) in effect on the date of
+ publication of this document. Please review these documents
+ carefully, as they describe your rights and restrictions with respect
+ to this document. Code Components extracted from this document must
+ include Simplified BSD License text as described in Section 4.e of
+ the Trust Legal Provisions and are provided without warranty as
+ described in the Simplified BSD License.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Evans, et al. Standards Track [Page 2]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4
+ 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 5
+ 2. Server and Client Behavior . . . . . . . . . . . . . . . . . 5
+ 2.1. Response Header Field Syntax . . . . . . . . . . . . . . 5
+ 2.1.1. The Pin Directive . . . . . . . . . . . . . . . . . . 6
+ 2.1.2. The max-age Directive . . . . . . . . . . . . . . . . 7
+ 2.1.3. The includeSubDomains Directive . . . . . . . . . . . 7
+ 2.1.4. The report-uri Directive . . . . . . . . . . . . . . 7
+ 2.1.5. Examples . . . . . . . . . . . . . . . . . . . . . . 8
+ 2.2. Server Processing Model . . . . . . . . . . . . . . . . . 9
+ 2.2.1. HTTP-over-Secure-Transport Request Type . . . . . . . 9
+ 2.2.2. HTTP Request Type . . . . . . . . . . . . . . . . . . 9
+ 2.3. User Agent Processing Model . . . . . . . . . . . . . . . 10
+ 2.3.1. Public-Key-Pins Response Header Field Processing . . 10
+ 2.3.2. Interaction of Public-Key-Pins and Public-Key-Pins-
+ Report-Only . . . . . . . . . . . . . . . . . . . . . 11
+ 2.3.3. Noting a Pinned Host - Storage Model . . . . . . . . 11
+ 2.3.4. HTTP-Equiv <Meta> Element Attribute . . . . . . . . . 13
+ 2.4. Semantics of Pins . . . . . . . . . . . . . . . . . . . . 13
+ 2.5. Noting Pins . . . . . . . . . . . . . . . . . . . . . . . 14
+ 2.6. Validating Pinned Connections . . . . . . . . . . . . . . 15
+ 2.7. Interactions with Preloaded Pin Lists . . . . . . . . . . 16
+ 2.8. Pinning Self-Signed End Entities . . . . . . . . . . . . 16
+ 3. Reporting Pin Validation Failure . . . . . . . . . . . . . . 16
+ 4. Security Considerations . . . . . . . . . . . . . . . . . . . 19
+ 4.1. Maximum max-age . . . . . . . . . . . . . . . . . . . . . 19
+ 4.2. Using includeSubDomains Safely . . . . . . . . . . . . . 20
+ 4.3. Backup Pins . . . . . . . . . . . . . . . . . . . . . . . 21
+ 4.4. Interactions With Cookie Scoping . . . . . . . . . . . . 21
+ 4.5. Hostile Pinning . . . . . . . . . . . . . . . . . . . . . 21
+ 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 22
+ 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24
+ 7. Usability Considerations . . . . . . . . . . . . . . . . . . 24
+ 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 24
+ 8.1. Normative References . . . . . . . . . . . . . . . . . . 24
+ 8.2. Informative References . . . . . . . . . . . . . . . . . 26
+ Appendix A. Fingerprint Generation . . . . . . . . . . . . . . . 27
+ Appendix B. Deployment Guidance . . . . . . . . . . . . . . . . 27
+ Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 28
+ Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28
+
+
+
+
+
+
+
+
+
+Evans, et al. Standards Track [Page 3]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+1. Introduction
+
+ This document defines a new HTTP header that enables UAs to determine
+ which Subject Public Key Info (SPKI) structures will be present in a
+ web host's certificate chain in future Transport Layer Security (TLS)
+ [RFC5246] connections.
+
+ Deploying Public Key Pinning (PKP) safely will require operational
+ and organizational maturity due to the risk that hosts may make
+ themselves unavailable by pinning to a set of SPKIs that becomes
+ invalid (see Section 4). With care, host operators can greatly
+ reduce the risk of man-in-the-middle (MITM) attacks and other false-
+ authentication problems for their users without incurring undue risk.
+
+ PKP is meant to be used together with HTTP Strict Transport Security
+ (HSTS) [RFC6797], but it is possible to pin keys without requiring
+ HSTS.
+
+ A Pin is a relationship between a hostname and a cryptographic
+ identity (in this document, one or more of the public keys in a chain
+ of X.509 certificates). Pin Validation is the process a UA performs
+ to ensure that a host is in fact authenticated with its previously
+ established Pin.
+
+ Key pinning is a trust-on-first-use (TOFU) mechanism. The first time
+ a UA connects to a host, it lacks the information necessary to
+ perform Pin Validation; UAs can only apply their normal cryptographic
+ identity validation. (In this document, it is assumed that UAs apply
+ X.509 certificate chain validation in accord with [RFC5280].)
+
+ The UA will not be able to detect and thwart a MITM attacking the
+ UA's first connection to the host. (However, the requirement that
+ the MITM provide an X.509 certificate chain that can pass the UA's
+ validation requirements, without error, mitigates this risk
+ somewhat.) Worse, such a MITM can inject its own PKP header into the
+ HTTP stream, and pin the UA to its own keys. To avoid post facto
+ detection, the attacker would have to be in a position to intercept
+ all future requests to the host from that UA.
+
+ Thus, key pinning as described in this document is not a perfect
+ defense against MITM attackers capable of passing certificate chain
+ validation procedures -- nothing short of pre-shared keys can be.
+ However, it provides significant value by allowing host operators to
+ limit the number of certification authorities that can vouch for the
+ host's identity, and allows UAs to detect in-process MITM attacks
+ after the initial communication.
+
+
+
+
+
+Evans, et al. Standards Track [Page 4]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+1.1. Requirements Language
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in RFC 2119 [RFC2119].
+
+2. Server and Client Behavior
+
+2.1. Response Header Field Syntax
+
+ The "Public-Key-Pins" and "Public-Key-Pins-Report-Only" header
+ fields, also referred to within this specification as the PKP and
+ PKP-RO header fields, respectively, are new response headers defined
+ in this specification. They are used by a server to indicate that a
+ UA should perform Pin Validation (Section 2.6) for the host emitting
+ the response message, and to provide the necessary information for
+ the UA to do so.
+
+ Figure 1 describes the syntax (Augmented Backus-Naur Form) of the
+ header fields, using the grammar defined in [RFC5234] and the rules
+ defined in Section 3.2 of [RFC7230]. The field values of both header
+ fields conform to the same rules.
+
+ Public-Key-Directives = directive *( OWS ";" OWS directive )
+
+ directive = directive-name [ "=" directive-value ]
+ directive-name = token
+ directive-value = token
+ / quoted-string
+
+ Figure 1: HPKP Header Syntax
+
+ Optional white space (OWS) is used as defined in Section 3.2.3 of
+ [RFC7230]. token and quoted-string are used as defined in
+ Section 3.2.6 of [RFC7230].
+
+ The directives defined in this specification are described below.
+ The overall requirements for directives are:
+
+ 1. The order of appearance of directives is not significant.
+
+ 2. With the exception of pin-directives with the same pin-directive-
+ name (see below), a given directive MUST NOT appear more than
+ once in a given header field. Directives are either optional or
+ required, as stipulated in their definitions.
+
+ 3. Directive names are case insensitive.
+
+
+
+
+Evans, et al. Standards Track [Page 5]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+ 4. UAs MUST ignore any header fields containing directives, or other
+ header field value data, that do not conform to the syntax
+ defined in this specification. In particular, UAs must not
+ attempt to fix malformed header fields.
+
+ 5. If a header field contains any directive(s) the UA does not
+ recognize, the UA MUST ignore those directives.
+
+ 6. If the PKP or PKP-RO header field otherwise satisfies the above
+ requirements (1 through 5), the UA MUST process the directives it
+ recognizes.
+
+ Additional directives extending the semantic functionality of the
+ header fields can be defined in other specifications. The first such
+ specification will need to define a registry for such directives.
+ Such future directives will be ignored by UAs implementing only this
+ specification, as well as by generally non-conforming UAs.
+
+ When a connection passes Pin Validation using the UA's noted Pins for
+ the host at the time, the host becomes a Known Pinned Host.
+
+2.1.1. The Pin Directive
+
+ The pin directive specifies a way for web host operators to indicate
+ a cryptographic identity that should be bound to a given web host.
+ The syntax of a pin directive is as follows:
+
+ pin-directive = pin-directive-name "=" pin-directive-value
+
+ pin-directive-name = "pin-" token
+ pin-directive-value = quoted-string
+
+ Figure 2: Pin Directive Syntax
+
+ In the pin-directive, the token is the name of a cryptographic hash
+ algorithm. The only algorithm allowed at this time is "sha256",
+ i.e., the hash algorithm SHA256 [RFC6234]; additional algorithms may
+ be allowed for use in this context in the future. The quoted-string
+ is a sequence of base 64 digits: the base64-encoded SPKI Fingerprint
+ [RFC4648] (see Section 2.4).
+
+ According to the processing rules of Section 2.1, the UA MUST ignore
+ pin-directives with tokens naming hash algorithms it does not
+ recognize. If the set of remaining effective pin-directives is
+ empty, and if the host is a Known Pinned Host, the UA MUST cease to
+ consider the host as a Known Pinned Host (the UA should fail open).
+ The UA should indicate to users that the host is no longer a Known
+ Pinned Host.
+
+
+
+Evans, et al. Standards Track [Page 6]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+ Note, per the processing rules of Section 2.1, the pin-directive-name
+ is case insensitive.
+
+2.1.2. The max-age Directive
+
+ The "max-age" directive specifies the number of seconds after the
+ reception of the PKP header field during which the UA SHOULD regard
+ the host (from whom the message was received) as a Known Pinned Host.
+
+ The "max-age" directive is REQUIRED to be present within a "Public-
+ Key-Pins" header field. The "max-age" directive is meaningless
+ within a "Public-Key-Pins-Report-Only" header field, and UAs MUST
+ ignore it and not cache the header. See Section 2.3.3.
+
+ The max-age directive is REQUIRED to have a directive value, for
+ which the syntax (after quoted-string unescaping, if necessary) is
+ defined as:
+
+ max-age-value = delta-seconds
+ delta-seconds = 1*DIGIT
+
+ Figure 3: max-age Value Syntax
+
+ delta-seconds is used as defined in [RFC7234], Section 1.2.1.
+
+ See Section 2.3.3 for limitations on the range of values for max-age.
+
+2.1.3. The includeSubDomains Directive
+
+ The OPTIONAL includeSubDomains directive is a valueless directive
+ that, if present (i.e., it is "asserted"), signals to the UA that the
+ Pinning Policy applies to this Pinned Host as well as any subdomains
+ of the host's domain name.
+
+2.1.4. The report-uri Directive
+
+ The OPTIONAL report-uri directive indicates the URI to which the UA
+ SHOULD report Pin Validation failures (Section 2.6). The UA POSTs
+ the reports to the given URI as described in Section 3.
+
+ When used in the PKP or PKP-RO headers, the presence of a report-uri
+ directive indicates to the UA that in the event of Pin Validation
+ failure it SHOULD POST a report to the report-uri. If the header is
+ Public-Key-Pins, the UA should do this in addition to terminating the
+ connection (as described in Section 2.6).
+
+
+
+
+
+
+Evans, et al. Standards Track [Page 7]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+ Hosts may set report-uris that use HTTP or HTTPS. If the scheme in
+ the report-uri is one that uses TLS (e.g., HTTPS), UAs MUST perform
+ Pinning Validation when the host in the report-uri is a Known Pinned
+ Host; similarly, UAs MUST apply HSTS if the host in the report-uri is
+ a Known HSTS Host.
+
+ Note that the report-uri need not necessarily be in the same Internet
+ domain or web origin as the host being reported about.
+
+ UAs SHOULD make their best effort to report Pin Validation failures
+ to the report-uri, but they may fail to report in exceptional
+ conditions. For example, if connecting the report-uri itself incurs
+ a Pinning Validation failure or other certificate validation failure,
+ the UA MUST cancel the connection. Similarly, if Known Pinned Host A
+ sets a report-uri referring to Known Pinned Host B, and if B sets a
+ report-uri referring to A, and if both hosts fail Pin Validation, the
+ UA SHOULD detect and break the loop by failing to send reports to and
+ about those hosts.
+
+ In any case of report failure, the UA MAY attempt to re-send the
+ report later.
+
+ UAs SHOULD limit the rate at which they send reports. For example,
+ it is unnecessary to send the same report to the same report-uri more
+ than once per distinct set of declared Pins.
+
+2.1.5. Examples
+
+ Figure 4 shows some example PKP and PKP-RO response header fields.
+ (Lines are folded to fit.)
+
+ Public-Key-Pins: max-age=3000;
+ pin-sha256="d6qzRu9zOECb90Uez27xWltNsj0e1Md7GkYYkVoZWmM=";
+ pin-sha256="E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g="
+
+ Public-Key-Pins: max-age=2592000;
+ pin-sha256="E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g=";
+ pin-sha256="LPJNul+wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ="
+
+ Public-Key-Pins: max-age=2592000;
+ pin-sha256="E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g=";
+ pin-sha256="LPJNul+wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ=";
+ report-uri="http://example.com/pkp-report"
+
+ Public-Key-Pins-Report-Only: max-age=2592000;
+ pin-sha256="E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g=";
+ pin-sha256="LPJNul+wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ=";
+ report-uri="https://other.example.net/pkp-report"
+
+
+
+Evans, et al. Standards Track [Page 8]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+ Public-Key-Pins:
+ pin-sha256="d6qzRu9zOECb90Uez27xWltNsj0e1Md7GkYYkVoZWmM=";
+ pin-sha256="LPJNul+wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ=";
+ max-age=259200
+
+ Public-Key-Pins:
+ pin-sha256="d6qzRu9zOECb90Uez27xWltNsj0e1Md7GkYYkVoZWmM=";
+ pin-sha256="E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g=";
+ pin-sha256="LPJNul+wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ=";
+ max-age=10000; includeSubDomains
+
+ Figure 4: HTTP Public Key Pinning (HPKP) Header Examples
+
+2.2. Server Processing Model
+
+ This section describes the processing model that Pinned Hosts
+ implement. The model has 2 parts: (1) the processing rules for HTTP
+ request messages received over a secure transport (e.g.,
+ authenticated, non-anonymous TLS); and (2) the processing rules for
+ HTTP request messages received over non-secure transports, such as
+ TCP.
+
+2.2.1. HTTP-over-Secure-Transport Request Type
+
+ When replying to an HTTP request that was conveyed over a secure
+ transport, a Pinned Host SHOULD include in its response exactly one
+ PKP header field, exactly one PKP-RO header field, or one of each.
+ Each instance of either header field MUST satisfy the grammar
+ specified in Section 2.1.
+
+ Establishing a given host as a Known Pinned Host, in the context of a
+ given UA, is accomplished as follows:
+
+ 1. Over the HTTP protocol running over secure transport, by
+ correctly returning (per this specification) at least one valid
+ PKP header field to the UA.
+
+ 2. Through other mechanisms, such as a client-side preloaded Known
+ Pinned Host List.
+
+2.2.2. HTTP Request Type
+
+ Pinned Hosts SHOULD NOT include the PKP header field in HTTP
+ responses conveyed over non-secure transport. UAs MUST ignore any
+ PKP header received in an HTTP response conveyed over non-secure
+ transport.
+
+
+
+
+
+Evans, et al. Standards Track [Page 9]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+2.3. User Agent Processing Model
+
+ The UA processing model relies on parsing domain names. Note that
+ internationalized domain names SHALL be canonicalized according to
+ the scheme in Section 10 of [RFC6797].
+
+2.3.1. Public-Key-Pins Response Header Field Processing
+
+ If the UA receives, over a secure transport, an HTTP response that
+ includes a PKP header field conforming to the grammar specified in
+ Section 2.1, and there are no underlying secure transport errors or
+ warnings (see Section 2.5), the UA MUST either:
+
+ o Note the host as a Known Pinned Host if it is not already so noted
+ (see Section 2.3.3),
+
+ or,
+
+ o Update the UA's cached information for the Known Pinned Host if
+ any of the max-age, includeSubDomains, or report-uri header field
+ value directives convey information different from that already
+ maintained by the UA.
+
+ The max-age value is essentially a "time to live" value relative to
+ the time of the most recent observation of the PKP header field. If
+ the max-age header field value token has a value of 0, the UA MUST
+ remove its cached Pinning Policy information (including the
+ includeSubDomains directive, if asserted) if the Pinned Host is
+ Known, or, MUST NOT note this Pinned Host if it is not yet Known.
+
+ If a UA receives more than one PKP header field or more than one PKP-
+ RO header field in an HTTP response message over secure transport,
+ then the UA MUST process only the first PKP header field (if present)
+ and only the first PKP-RO header field (if present).
+
+ If the UA receives the HTTP response over insecure transport, or if
+ the PKP header is not a Valid Pinning Header (see Section 2.5), the
+ UA MUST ignore any present PKP header field(s). Similarly, if the UA
+ receives the HTTP response over insecure transport, the UA MUST
+ ignore any present PKP-RO header field(s). The UA MUST ignore any
+ PKP or PKP-RO header fields not conforming to the grammar specified
+ in Section 2.1.
+
+
+
+
+
+
+
+
+
+Evans, et al. Standards Track [Page 10]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+2.3.2. Interaction of Public-Key-Pins and Public-Key-Pins-Report-Only
+
+ A server MAY set both the "Public-Key-Pins" and "Public-Key-Pins-
+ Report-Only" headers simultaneously. The headers do not interact
+ with one another, but the UA MUST process the PKP header and SHOULD
+ process both.
+
+ The headers are processed according to Section 2.3.1.
+
+ When the PKP-RO header is used with a report-uri, the UA SHOULD POST
+ reports for Pin Validation failures to the indicated report-uri,
+ although the UA MUST NOT enforce Pin Validation. That is, in the
+ event of Pin Validation failure when the host has set the PKP-RO
+ header, the UA performs Pin Validation to check whether or not it
+ should POST a report, but not whether it should cause a connection
+ failure.
+
+ Note: There is no purpose to using the PKP-RO header without the
+ report-uri directive. User Agents MAY discard such headers without
+ interpreting them further.
+
+ When the PKP header is used with a report-uri, the UA SHOULD POST
+ reports for Pin Validation failures to the indicated report-uri, as
+ well as enforce Pin Validation.
+
+ If a host sets the PKP-RO header, the UA SHOULD note the Pins and
+ directives given in the PKP-RO header, ignoring any max-age
+ directive. If the UA does note the Pins and directives in the PKP-RO
+ header, it SHOULD evaluate the specified policy and SHOULD report any
+ would-be Pin Validation failures that would occur if the report-only
+ policy were enforced.
+
+ If a host sets both the PKP header and the PKP-RO header, the UA MUST
+ note and enforce Pin Validation as specified by the PKP header, and
+ SHOULD process the Pins and directives given in the PKP-RO header.
+ If the UA does process the Pins and directives in the PKP-RO header,
+ it SHOULD evaluate the specified policy and SHOULD report any would-
+ be Pin Validation failures that would occur if the report-only policy
+ were enforced.
+
+2.3.3. Noting a Pinned Host - Storage Model
+
+ The Effective Pin Date of a Known Pinned Host is the time that the UA
+ observed a Valid Pinning Header for the host. The Effective
+ Expiration Date of a Known Pinned Host is the Effective Pin Date plus
+ the max-age. A Known Pinned Host is "expired" if the Effective
+ Expiration Date refers to a date in the past. The UA MUST ignore any
+ expired Known Pinned Hosts in its cache.
+
+
+
+Evans, et al. Standards Track [Page 11]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+ For example, if a UA is beginning to perform Pin Validation for a
+ Known Pinned Host and finds that the cached pinning information for
+ the host indicates an Effective Expiration Date in the past, the UA
+ MUST NOT continue with Pin Validation for the host, and MUST consider
+ the host to no longer be a Known Pinned Host.
+
+ Known Pinned Hosts are identified only by domain names, and never IP
+ addresses. If the substring matching the host production from the
+ Request-URI (of the message to which the host responded)
+ syntactically matches the IP-literal or IPv4address productions from
+ Section 3.2.2 of [RFC3986], then the UA MUST NOT note this host as a
+ Known Pinned Host.
+
+ Otherwise, if the substring does not congruently match an existing
+ Known Pinned Host's domain name, per the matching procedure specified
+ in Section 8.2 of [RFC6797], then the UA MUST add this host to the
+ Known Pinned Host cache. The UA caches:
+
+ o the Pinned Host's domain name,
+
+ o the Effective Expiration Date, or enough information to calculate
+ it (the Effective Pin Date and the value of the max-age
+ directive),
+
+ o whether or not the includeSubDomains directive is asserted, and
+
+ o the value of the report-uri directive, if present.
+
+ If any other metadata from optional or future PKP header directives
+ are present in the Valid Pinning Header, and the UA understands them,
+ the UA MAY note them as well.
+
+ UAs MAY set an upper limit on the value of max-age, so that UAs that
+ have noted erroneous Pins (whether by accident or due to attack) have
+ some chance of recovering over time. If the server sets a max-age
+ greater than the UA's upper limit, the UA MAY behave as if the server
+ set the max-age to the UA's upper limit. For example, if the UA caps
+ max-age at 5,184,000 seconds (60 days), and a Pinned Host sets a max-
+ age directive of 90 days in its Valid Pinning Header, the UA MAY
+ behave as if the max-age were effectively 60 days. (One way to
+ achieve this behavior is for the UA to simply store a value of 60
+ days instead of the 90-day value provided by the Pinned Host.) For
+ UA implementation guidance on how to select a maximum max-age, see
+ Section 4.1.
+
+ The UA MUST NOT modify any pinning metadata of any superdomain
+ matched Known Pinned Host.
+
+
+
+
+Evans, et al. Standards Track [Page 12]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+ The UA MUST NOT cache information derived from a PKP-RO header.
+ (PKP-RO headers are useful only at the time of receipt and
+ processing.)
+
+2.3.4. HTTP-Equiv <Meta> Element Attribute
+
+ UAs MUST NOT heed http-equiv="Public-Key-Pins" or
+ http-equiv="Public-Key-Pins-Report-Only" attribute settings on <meta>
+ elements [W3C.REC-html401-19991224] in received content.
+
+2.4. Semantics of Pins
+
+ An SPKI Fingerprint is defined as the output of a known cryptographic
+ hash algorithm whose input is the DER-encoded ASN.1 representation of
+ the Subject Public Key Info (SPKI) of an X.509 certificate. A Pin is
+ defined as the combination of the known algorithm identifier and the
+ SPKI Fingerprint computed using that algorithm.
+
+ The SPKI Fingerprint is encoded in base 64 for use in an HTTP header
+ [RFC4648].
+
+ In this version of the specification, the known cryptographic hash
+ algorithm is SHA-256, identified as "sha256" [RFC6234]. (Future
+ specifications may add new algorithms and deprecate old ones.) UAs
+ MUST ignore Pins for which they do not recognize the algorithm
+ identifier. UAs MUST continue to process the rest of a PKP response
+ header field and note Pins for algorithms they do recognize.
+
+ Figure 5 reproduces the definition of the SubjectPublicKeyInfo
+ structure in [RFC5280].
+
+ SubjectPublicKeyInfo ::= SEQUENCE {
+ algorithm AlgorithmIdentifier,
+ subjectPublicKey BIT STRING }
+
+ AlgorithmIdentifier ::= SEQUENCE {
+ algorithm OBJECT IDENTIFIER,
+ parameters ANY DEFINED BY algorithm OPTIONAL }
+
+ Figure 5: SPKI Definition
+
+ If the certificate's Subject Public Key Info is incomplete when taken
+ in isolation, such as when holding a DSA key without domain
+ parameters, a public key pin cannot be formed.
+
+ We pin public keys, rather than entire certificates, to enable
+ operators to generate new certificates containing old public keys
+ (see [why-pin-key]).
+
+
+
+Evans, et al. Standards Track [Page 13]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+ See Appendix A for an example non-normative program that generates
+ SPKI Fingerprints from certificates.
+
+2.5. Noting Pins
+
+ Upon receipt of the PKP response header field, the UA notes the host
+ as a Known Pinned Host, storing the Pins and their associated
+ directives in non-volatile storage (for example, along with the HSTS
+ metadata). The Pins and their associated directives are collectively
+ known as Pinning Metadata.
+
+ The UA MUST note the Pins for a Host if and only if all three of the
+ following conditions hold:
+
+ o It received the PKP response header field over an error-free TLS
+ connection. If the host is a Pinned Host, this includes the
+ validation added in Section 2.6.
+
+ o The TLS connection was authenticated with a certificate chain
+ containing at least one of the SPKI structures indicated by at
+ least one of the given SPKI Fingerprints (see Section 2.6).
+
+ o The given set of Pins contains at least one Pin that does NOT
+ refer to an SPKI in the certificate chain. (That is, the host
+ must set a Backup Pin; see Section 4.3.)
+
+ If the PKP response header field does not meet all three of these
+ criteria, the UA MUST NOT note the host as a Pinned Host. A PKP
+ response header field that meets all these criteria is known as a
+ Valid Pinning Header.
+
+ Whenever a UA receives a Valid Pinning Header, it MUST set its
+ Pinning Metadata to the exact Pins, Effective Expiration Date
+ (computed from max-age), and (if any) report-uri given in the most
+ recently received Valid Pinning Header.
+
+ For forward compatibility, the UA MUST ignore any unrecognized PKP
+ and PKP-RO header directives, while still processing those directives
+ it does recognize. Section 2.1 specifies the directives max-age,
+ Pins, includeSubDomains, and report-uri, but future specifications
+ and implementations might use additional directives.
+
+ Upon receipt of a PKP-RO response header field, the UA SHOULD
+ evaluate the policy expressed in the field, and SHOULD generate and
+ send a report (see Section 3). However, failure to validate the Pins
+ in the field MUST have no effect on the validity or non-validity of
+ the policy expressed in the PKP field or in previously noted Pins for
+ the Known Pinned Host.
+
+
+
+Evans, et al. Standards Track [Page 14]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+ The UA need not note any Pins or other policy expressed in the PKP-RO
+ response header field, except for the purpose of determining that it
+ has already sent a report for a given policy. UAs SHOULD make a best
+ effort not to inundate report-uris with redundant reports.
+
+2.6. Validating Pinned Connections
+
+ When a UA connects to a Pinned Host using a TLS connection, if the
+ TLS connection has errors, the UA MUST terminate the connection
+ without allowing the user to proceed anyway. (This behavior is the
+ same as that required by [RFC6797].)
+
+ If the connection has no errors, then the UA will determine whether
+ to apply a new, additional correctness check: Pin Validation. A UA
+ SHOULD perform Pin Validation whenever connecting to a Known Pinned
+ Host, as soon as possible (e.g., immediately after receiving the
+ Server Certificate message). It is acceptable to allow Pin
+ Validation to be disabled for some Hosts according to local policy.
+ For example, a UA may disable Pin Validation for Pinned Hosts whose
+ validated certificate chain terminates at a user-defined trust
+ anchor, rather than a trust anchor built-in to the UA (or underlying
+ platform).
+
+ To perform Pin Validation, the UA will compute the SPKI Fingerprints
+ for each certificate in the Pinned Host's validated certificate
+ chain, using each supported hash algorithm for each certificate. (As
+ described in Section 2.4, certificates whose SPKI cannot be taken in
+ isolation cannot be pinned.) The UA MUST ignore superfluous
+ certificates in the chain that do not form part of the validating
+ chain. The UA will then check that the set of these SPKI
+ Fingerprints intersects the set of SPKI Fingerprints in that Pinned
+ Host's Pinning Metadata. If there is set intersection, the UA
+ continues with the connection as normal. Otherwise, the UA MUST
+ treat this Pin Validation failure as a non-recoverable error. Any
+ procedure that matches the results of this Pin Validation procedure
+ is considered equivalent.
+
+ A UA that has previously noted a host as a Known Pinned Host MUST
+ perform Pin Validation when setting up the TLS session, before
+ beginning an HTTP conversation over the TLS channel.
+
+ UAs send validation failure reports only when Pin Validation is
+ actually in effect. Pin Validation might not be in effect, e.g.,
+ because the user has elected to disable it, or because a presented
+ certificate chain chains up to a user-defined trust anchor. In such
+ cases, UAs SHOULD NOT send reports.
+
+
+
+
+
+Evans, et al. Standards Track [Page 15]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+2.7. Interactions with Preloaded Pin Lists
+
+ UAs MAY choose to implement additional sources of pinning
+ information, such as through built-in lists of pinning information.
+ Such UAs should allow users to override such additional sources,
+ including disabling them from consideration.
+
+ The effective policy for a Known Pinned Host that has both built-in
+ Pins and Pins from previously observed PKP header response fields is
+ implementation-defined.
+
+2.8. Pinning Self-Signed End Entities
+
+ If UAs accept hosts that authenticate themselves with self-signed end
+ entity certificates, they MAY also allow hosts to pin the public keys
+ in such certificates. The usability and security implications of
+ this practice are outside the scope of this specification.
+
+3. Reporting Pin Validation Failure
+
+ When a Known Pinned Host has set the report-uri directive, the UA
+ SHOULD report Pin Validation failures to the indicated URI. The UA
+ does this by POSTing a JSON [RFC7159] message to the URI; the JSON
+ message takes this form:
+
+ {
+ "date-time": date-time,
+ "hostname": hostname,
+ "port": port,
+ "effective-expiration-date": expiration-date,
+ "include-subdomains": include-subdomains,
+ "noted-hostname": noted-hostname,
+ "served-certificate-chain": [
+ pem1, ... pemN
+ ],
+ "validated-certificate-chain": [
+ pem1, ... pemN
+ ],
+ "known-pins": [
+ known-pin1, ... known-pinN
+ ]
+ }
+
+ Figure 6: JSON Report Format
+
+ Whitespace outside of quoted strings is not significant. The key/
+ value pairs may appear in any order, but each MUST appear only once.
+
+
+
+
+Evans, et al. Standards Track [Page 16]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+ The date-time indicates the time the UA observed the Pin Validation
+ failure. It is provided as a string formatted according to
+ Section 5.6, "Internet Date/Time Format", of [RFC3339].
+
+ The hostname is the hostname to which the UA made the original
+ request that failed Pin Validation. It is provided as a string.
+
+ The port is the port to which the UA made the original request that
+ failed Pin Validation. It is provided as an integer.
+
+ The effective-expiration-date is the Effective Expiration Date for
+ the noted Pins. It is provided as a string formatted according to
+ Section 5.6, "Internet Date/Time Format", of [RFC3339].
+
+ include-subdomains indicates whether or not the UA has noted the
+ includeSubDomains directive for the Known Pinned Host. It is
+ provided as one of the JSON identifiers "true" or "false".
+
+ noted-hostname indicates the hostname that the UA noted when it noted
+ the Known Pinned Host. This field allows operators to understand why
+ Pin Validation was performed for, e.g., foo.example.com when the
+ noted Known Pinned Host was example.com with includeSubDomains set.
+
+ The served-certificate-chain is the certificate chain, as served by
+ the Known Pinned Host during TLS session setup. It is provided as an
+ array of strings; each string pem1, ... pemN is the Privacy-Enhanced
+ Mail (PEM) representation of each X.509 certificate as described in
+ [RFC7468].
+
+ The validated-certificate-chain is the certificate chain, as
+ constructed by the UA during certificate chain verification. (This
+ may differ from the served-certificate-chain.) It is provided as an
+ array of strings; each string pem1, ... pemN is the PEM
+ representation of each X.509 certificate as described in [RFC7468].
+ UAs that build certificate chains in more than one way during the
+ validation process SHOULD send the last chain built. In this way,
+ they can avoid keeping too much state during the validation process.
+
+ The known-pins are the Pins that the UA has noted for the Known
+ Pinned Host. They are provided as an array of strings with the
+ syntax:
+
+ known-pin = token "=" quoted-string
+
+ Figure 7: Known Pin Syntax
+
+
+
+
+
+
+Evans, et al. Standards Track [Page 17]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+ As in Section 2.4, the token refers to the algorithm name, and the
+ quoted-string refers to the base64 encoding of the SPKI Fingerprint.
+ When formulating the JSON POST body, the UA MUST either use single-
+ quoted JSON strings or use double-quoted JSON strings and backslash-
+ escape the embedded double quotes in the quoted-string part of the
+ known-pin.
+
+ Figure 8 shows an example of a Pin Validation failure report. (PEM
+ strings are shown on multiple lines for readability.)
+
+ {
+ "date-time": "2014-04-06T13:00:50Z",
+ "hostname": "www.example.com",
+ "port": 443,
+ "effective-expiration-date": "2014-05-01T12:40:50Z"
+ "include-subdomains": false,
+ "served-certificate-chain": [
+ "-----BEGIN CERTIFICATE-----\n
+ MIIEBDCCAuygAwIBAgIDAjppMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT\n
+ ...
+ HFa9llF7b1cq26KqltyMdMKVvvBulRP/F/A8rLIQjcxz++iPAsbw+zOzlTvjwsto\n
+ WHPbqCRiOwY1nQ2pM714A5AuTHhdUDqB1O6gyHA43LL5Z/qHQF1hwFGPa4NrzQU6\n
+ yuGnBXj8ytqU0CwIPX4WecigUCAkVDNx\n
+ -----END CERTIFICATE-----",
+ ...
+ ],
+ "validated-certificate-chain": [
+ "-----BEGIN CERTIFICATE-----\n
+ MIIEBDCCAuygAwIBAgIDAjppMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT\n
+ ...
+ HFa9llF7b1cq26KqltyMdMKVvvBulRP/F/A8rLIQjcxz++iPAsbw+zOzlTvjwsto\n
+ WHPbqCRiOwY1nQ2pM714A5AuTHhdUDqB1O6gyHA43LL5Z/qHQF1hwFGPa4NrzQU6\n
+ yuGnBXj8ytqU0CwIPX4WecigUCAkVDNx\n
+ -----END CERTIFICATE-----",
+ ...
+ ],
+ "known-pins": [
+ 'pin-sha256="d6qzRu9zOECb90Uez27xWltNsj0e1Md7GkYYkVoZWmM="',
+ "pin-sha256=\"E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g=\""
+ ]
+ }
+
+ Figure 8: Pin Validation Failure Report Example
+
+
+
+
+
+
+
+
+Evans, et al. Standards Track [Page 18]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+4. Security Considerations
+
+ Pinning public keys helps hosts strongly assert their cryptographic
+ identity even in the face of issuer error, malfeasance, or
+ compromise. But, there is some risk that a host operator could lose
+ (or lose control of) their host's private key (such as by operator
+ error or host compromise). If the operator had pinned only the key
+ of the host's end-entity certificate, the operator would not be able
+ to serve their web site or application in a way that UAs would trust
+ for the duration of their pin's max-age. (Recall that UAs MUST close
+ the connection to a host upon Pin Failure.)
+
+ Therefore, there is a necessary trade-off between two competing
+ goods: pin specificity and maximal reduction of the scope of issuers
+ on the one hand; and flexibility and resilience of the host's
+ cryptographic identity on the other hand. One way to resolve this
+ trade-off is to compromise by pinning to the key(s) of the issuer(s)
+ of the host's end-entity certificate(s). Often, a valid certificate
+ chain will have at least two certificates above the end-entity
+ certificate: the intermediate issuer and the trust anchor. Operators
+ can pin any one or more of the public keys in this chain, and indeed
+ MUST pin to issuers not in the chain (as, for example, a Backup Pin).
+ Pinning to an intermediate issuer, or even to a trust anchor or root,
+ still significantly reduces the number of issuers who can issue end-
+ entity certificates for the Known Pinned Host, while still giving
+ that host flexibility to change keys without a disruption of service.
+
+4.1. Maximum max-age
+
+ As mentioned in Section 2.3.3, UAs MAY cap the max-age value at some
+ upper limit. There is a security trade-off in that low maximum
+ values provide a narrow window of protection for users who visit the
+ Known Pinned Host only infrequently, while high maximum values might
+ result in a UA's inability to successfully perform Pin Validation for
+ a Known Pinned Host if the UA's noted Pins and the host's true Pins
+ diverge.
+
+ Such divergence could occur for several reasons, including: UA error;
+ host operator error; network attack; or a Known Pinned Host that
+ intentionally migrates all pinned keys, combined with a UA that has
+ noted true Pins with a high max-age value and has not had a chance to
+ observe the new true Pins for the host. (This last example
+ underscores the importance for host operators to phase in new keys
+ gradually and to set the max-age value in accordance with their
+ planned key migration schedule.)
+
+
+
+
+
+
+Evans, et al. Standards Track [Page 19]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+ There is probably no ideal upper limit to the max-age directive that
+ would satisfy all use cases. However, a value on the order of 60
+ days (5,184,000 seconds) may be considered a balance between the two
+ competing security concerns.
+
+4.2. Using includeSubDomains Safely
+
+ It may happen that Pinned Hosts whose hostnames share a parent domain
+ use different Valid Pinning Headers. If a host whose hostname is a
+ parent domain for another host sets the includeSubDomains directive,
+ the two hosts' Pins may conflict with each other. For example,
+ consider two Known Pinned Hosts, example.com and
+ subdomain.example.com. Assume example.com sets a Valid Pinning
+ Header such as this:
+
+ Public-Key-Pins: max-age=12000; pin-sha256="ABC...";
+ pin-sha256="DEF..."; includeSubDomains
+
+ Figure 9: example.com Valid Pinning Header
+
+ Assume subdomain.example.com sets a Valid Pinning Header such as
+ this:
+
+ Public-Key-Pins: pin-sha256="GHI..."; pin-sha256="JKL..."
+
+ Figure 10: subdomain.example.com Valid Pinning Header
+
+ Assume a UA that has not previously noted any Pins for either of
+ these hosts. If the UA first contacts subdomain.example.com, it will
+ note the Pins in the Valid Pinning Header, and perform Pin Validation
+ as normal on subsequent connections. If the UA then contacts
+ example.com, again it will note the Pins and perform Pin Validation
+ on future connections.
+
+ However, if the UA happened to visit example.com before
+ subdomain.example.com, the UA would, due to example.com's use of the
+ includeSubDomains directive, attempt to perform Pin Validation for
+ subdomain.example.com using the SPKI hashes ABC... and DEF..., which
+ are not valid for the certificate chains subdomain.example.com (which
+ uses certificates with SPKIs GHI... and JLK...). Thus, depending on
+ the order in which the UA observes the Valid Pinning Headers for
+ hosts example.com and subdomain.example.com, Pin Validation might or
+ might not fail for subdomain.example.com, even if the certificate
+ chain the UA receives for subdomain.example.com is perfectly valid.
+
+ Thus, Pinned Host operators must use the includeSubDomains directive
+ with care. For example, they may choose to use overlapping pin sets
+ for hosts under a parent domain that uses includeSubDomains, or to
+
+
+
+Evans, et al. Standards Track [Page 20]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+ not use the includeSubDomains directive in their effective-second-
+ level domains, or to simply use the same pin set for all hosts under
+ a given parent domain.
+
+4.3. Backup Pins
+
+ The primary way to cope with the risk of inadvertent Pin Validation
+ failure is to keep a Backup Pin. A Backup Pin is a fingerprint for
+ the public key of a secondary, not-yet-deployed key pair. The
+ operator keeps the backup key pair offline, and sets a pin for it in
+ the PKP header. Then, in case the operator loses control of their
+ primary private key, they can deploy the backup key pair. UAs, who
+ have had the backup key pair pinned (when it was set in previous
+ Valid Pinning Headers), can connect to the host without error.
+
+ Because having a backup key pair is so important to recovery, UAs
+ MUST require that hosts set a Backup Pin (see Section 2.5). The down
+ side of keeping a not-yet-deployed key pair is that, if an attacker
+ gains control of the private key, she will be able to perform a MITM
+ attack without being discovered. Operators must take care to avoid
+ leaking the key such as keeping it offline.
+
+4.4. Interactions With Cookie Scoping
+
+ HTTP cookies [RFC6265] set by a Known Pinned Host can be stolen by a
+ network attacker who can forge web and DNS responses so as to cause a
+ client to send the cookies to a phony subdomain of the host. To
+ prevent this, hosts SHOULD set the "secure" attribute and precisely
+ scope the "domain" attribute on all security-sensitive cookies, such
+ as session cookies. These settings tell the browser that the cookie
+ should only be sent back to the specific host(s) (and not, e.g., all
+ subdomains of a given domain), and should only be sent over HTTPS
+ (not HTTP).
+
+4.5. Hostile Pinning
+
+ An attacker who is able to obtain a valid certificate for a domain,
+ either through misissuance by a Certification Authority or through
+ other means, such as being the prior owner of a given domain, may
+ attempt to perform 'hostile' pinning. In this scenario, the attacker
+ provides a Valid Pinning Header that pins to a set of SPKIs of the
+ attacker's choice. If a UA has not previously noted pins for that
+ host, it may note the attacker's pins, preventing access to the
+ legitimate site.
+
+ This attack is mitigated through several means. Most prominently,
+ the attack can only persist for the maximum max-age (see
+ Section 4.1). Web host operators can reduce the opportunity for
+
+
+
+Evans, et al. Standards Track [Page 21]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+ attack by working to preload the host's pins within the UA.
+ Operators may further detect such misissuance through other means,
+ such as certificate transparency ([RFC6962]).
+
+5. Privacy Considerations
+
+ Hosts can use HSTS or HPKP as a "super-cookie", by setting distinct
+ policies for a number of subdomains. For example, assume example.com
+ wishes to track distinct UAs without explicitly setting a cookie, or
+ that a previously set cookie is deleted from the UA's cookie store.
+ Here are two attack scenarios.
+
+ o example.com can use report-uri and the ability to pin arbitrary
+ identifiers to distinguish UAs.
+
+ 1. example.com sets a Valid Pinning Header in its response to
+ requests. The header asserts the includeSubDomains directive
+ and specifies a report-uri directive as well. Pages served by
+ the host also include references to subresource
+ https://bad.example.com/foo.png.
+
+ 2. The Valid Pinning Header includes a "pin" that is not really
+ the hash of an SPKI but is instead an arbitrary distinguishing
+ string sent only in response to a particular request. For
+ each request, the host creates a new, distinct distinguishing
+ string and sets it as if it were a pin.
+
+ 3. The certificate chain served by bad.example.com does not pass
+ Pin Validation given the pin set the host asserted in step
+ (1). The HPKP-conforming UA attempts to report the Pin
+ Validation failure to the specified report-uri, including the
+ certificate chain it observed and the SPKI hashes it expected
+ to see. Among the SPKI hashes is the distinguishing string in
+ step (2).
+
+ o Different site operators/origins can optionally collaborate by
+ setting the report-uri to be in an origin they share
+ administrative control of. UAs MAY, therefore, refuse to send
+ reports outside of the origin that set the PKP or PKP-RO header.
+
+ o example.com can use server name indication (SNI; [RFC3546]) and
+ subdomains to distinguish UAs.
+
+ 1. example.com sets a Valid Pinning Header in its response to
+ requests. The header asserts the includeSubDomains directive.
+
+
+
+
+
+
+Evans, et al. Standards Track [Page 22]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+ 2. On a subsequent page view, the host responds with a page
+ including the subresource https://0.fingerprint.example.com/
+ foo.png, and the server responds using a certificate chain
+ that does not pass Pin Validation for the pin-set defined in
+ the Valid Pinning Header in step (1). The HPKP-conforming UA
+ will close the connection, never completing the request to
+ 0.fingerprint.example.com. The host may thus note that this
+ particular UA had noted the (good) Pins for that subdomain.
+
+ 3. example.com can distinguish 2^N UAs by serving Valid Pinning
+ Headers from an arbitrary number N distinct subdomains. For
+ any given subdomain n.fingerprint.example.com, the host may
+ deliver a Valid Pinning Header to one UA, but not deliver it
+ to a different UA. The server may then change the
+ configuration for n.fingerprint.example.com. If the UA fails
+ to connect, it was in the set of UAs that were pinned, which
+ can be distinguished from the UAs that were not pinned, as
+ they will succeed in connecting. The host may repeat this for
+ a sufficient number of subdomains necessary to distinguish
+ individual UAs.
+
+ o Conforming implementations (as well as implementations conforming
+ to [RFC6797]) must store state about which domains have set
+ policies, hence which domains the UA has contacted. Because these
+ policies cause remotely detectable behaviors, it is advisable that
+ UAs have a way for privacy-sensitive users to clear current Pins
+ for Pinned Hosts and that UAs allow users to query the current
+ state of Pinned Hosts. In addition, note that because pinning a
+ host implies a degree of persistent state, an attacker with
+ physical access to a device may be able to recover information
+ about hosts a user has visited, even if the user has cleared other
+ parts of the UA's state.
+
+ o Pin reports, as noted in Section 3, contains information about the
+ certificate chain that has failed pin validation. In some cases,
+ such as organization-wide compromise of the end-to-end security of
+ TLS, this may include information about the interception tools and
+ design used by the organization that the organization would
+ otherwise prefer not be disclosed.
+
+
+
+
+
+
+
+
+
+
+
+
+Evans, et al. Standards Track [Page 23]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+6. IANA Considerations
+
+ IANA has registered the response headers described in this document
+ under "Permanent Message Header Field Names" in the "Message Headers"
+ registry [message-headers] with the following parameters:
+
+ o Header Field Names: Public-Key-Pins and Public-Key-Pins-Report-
+ Only
+
+ o Protocol: http
+
+ o Status: standard
+
+ o Reference: RFC 7469
+
+7. Usability Considerations
+
+ When pinning works to detect impostor Pinned Hosts, users will
+ experience denial of service. It is advisable for UAs to explain the
+ reason why, i.e., that it was impossible to verify the confirmed
+ cryptographic identity of the host.
+
+ It is advisable that UAs have a way for users to clear current Pins
+ for Pinned Hosts and that UAs allow users to query the current state
+ of Pinned Hosts.
+
+8. References
+
+8.1. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997,
+ <http://www.rfc-editor.org/info/rfc2119>.
+
+ [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
+ Timestamps", RFC 3339, July 2002,
+ <http://www.rfc-editor.org/info/rfc3339>.
+
+ [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
+ Resource Identifier (URI): Generic Syntax", STD 66, RFC
+ 3986, January 2005,
+ <http://www.rfc-editor.org/info/rfc3986>.
+
+ [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
+ Encodings", RFC 4648, October 2006,
+ <http://www.rfc-editor.org/info/rfc4648>.
+
+
+
+
+
+Evans, et al. Standards Track [Page 24]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+ [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
+ Specifications: ABNF", STD 68, RFC 5234, January 2008,
+ <http://www.rfc-editor.org/info/rfc5234>.
+
+ [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
+ (TLS) Protocol Version 1.2", RFC 5246, August 2008,
+ <http://www.rfc-editor.org/info/rfc5246>.
+
+ [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
+ Housley, R., and W. Polk, "Internet X.509 Public Key
+ Infrastructure Certificate and Certificate Revocation List
+ (CRL) Profile", RFC 5280, May 2008,
+ <http://www.rfc-editor.org/info/rfc5280>.
+
+ [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms
+ (SHA and SHA-based HMAC and HKDF)", RFC 6234, May 2011,
+ <http://www.rfc-editor.org/info/rfc6234>.
+
+ [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265,
+ April 2011, <http://www.rfc-editor.org/info/rfc6265>.
+
+ [RFC6797] Hodges, J., Jackson, C., and A. Barth, "HTTP Strict
+ Transport Security (HSTS)", RFC 6797, November 2012,
+ <http://www.rfc-editor.org/info/rfc6797>.
+
+ [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
+ Interchange Format", RFC 7159, March 2014,
+ <http://www.rfc-editor.org/info/rfc7159>.
+
+ [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
+ Protocol (HTTP/1.1): Message Syntax and Routing", RFC
+ 7230, June 2014, <http://www.rfc-editor.org/info/rfc7230>.
+
+ [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
+ Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
+ RFC 7234, June 2014,
+ <http://www.rfc-editor.org/info/rfc7234>.
+
+ [RFC7468] Josefsson, S. and S. Leonard, "Textual Encodings of PKIX,
+ PKCS, and CMS Structures", RFC 7468, April 2015,
+ <http://www.rfc-editor.org/info/rfc7468>.
+
+ [W3C.REC-html401-19991224]
+ Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01
+ Specification", World Wide Web Consortium Recommendation
+ REC-html401-19991224, December 1999,
+ <http://www.w3.org/TR/1999/REC-html401-19991224>.
+
+
+
+
+Evans, et al. Standards Track [Page 25]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+ [message-headers]
+ IANA, "Message Headers",
+ <http://www.iana.org/assignments/message-headers/>.
+
+8.2. Informative References
+
+ [RFC3546] Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J.,
+ and T. Wright, "Transport Layer Security (TLS)
+ Extensions", RFC 3546, June 2003,
+ <http://www.rfc-editor.org/info/rfc3546>.
+
+ [RFC6962] Laurie, B., Langley, A., and E. Kasper, "Certificate
+ Transparency", RFC 6962, June 2013,
+ <http://www.rfc-editor.org/info/rfc6962>.
+
+ [TACK] Marlinspike, M., "Trust Assertions for Certificate Keys",
+ Work in Progress, draft-perrin-tls-tack-02, January 2013.
+
+ [why-pin-key]
+ Langley, A., "Public Key Pinning", Imperial Violet: Adam
+ Langley's Weblog, May 2011,
+ <https://www.imperialviolet.org/2011/05/04/pinning.html>.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Evans, et al. Standards Track [Page 26]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+Appendix A. Fingerprint Generation
+
+ This Portable Operating System Interface (POSIX) shell program
+ generates SPKI Fingerprints, suitable for use in pinning, from PEM-
+ encoded certificates. It is non-normative.
+
+ openssl x509 -noout -in certificate.pem -pubkey | \
+ openssl asn1parse -noout -inform pem -out public.key
+ openssl dgst -sha256 -binary public.key | openssl enc -base64
+
+ Figure 11: Example SPKI Fingerprint Generation Code
+
+Appendix B. Deployment Guidance
+
+ This section is non-normative guidance that may smooth the adoption
+ of public key pinning.
+
+ o Operators should get the backup public key signed by a different
+ (root and/or intermediary) CA than their primary certificate, and
+ store the backup key pair safely offline. The semantics of an
+ SPKI Fingerprint do not require the issuance of a certificate to
+ construct a valid Pin. However, in many deployment scenarios, in
+ order to make a Backup Pin operational, the server operator will
+ need to have a certificate to deploy TLS on the host. Failure to
+ obtain a certificate through prior arrangement will leave clients
+ that recognize the site as a Known Pinned Host unable to
+ successfully perform Pin Validation until such a time as the
+ operator can obtain a new certificate from their desired
+ certificate issuer.
+
+ o It is most economical to have the backup certificate signed by a
+ completely different signature chain than the live certificate, to
+ maximize recoverability in the event of compromise of either the
+ root or intermediary signer.
+
+ o Operators should periodically exercise their Backup Pin plan -- an
+ untested backup is no backup at all.
+
+ o Operators should start small. Operators should first deploy
+ public key pinning by using the report-only mode together with a
+ report-uri directive that points to a reliable report collection
+ endpoint. When moving out of report-only mode, operators should
+ start by setting a max-age of minutes or a few hours and gradually
+ increase max-age as they gain confidence in their operational
+ capability.
+
+
+
+
+
+
+Evans, et al. Standards Track [Page 27]
+
+RFC 7469 Public Key Pinning Extension for HTTP April 2015
+
+
+Acknowledgements
+
+ Thanks to Tobias Gondrom, Jeff Hodges, Paul Hoffman, Ivan Krstic,
+ Adam Langley, Barry Leiba, Nicolas Lidzborski, SM, James Manger, Yoav
+ Nir, Trevor Perrin, Eric Rescorla, Pete Resnick, Tom Ritter, and Yan
+ Zhu for suggestions and edits that clarified the text.
+
+ TACK [TACK] is a fruitful source of alternative design
+ considerations.
+
+Authors' Addresses
+
+ Chris Evans
+ Google, Inc.
+ 1600 Amphitheatre Pkwy
+ Mountain View, CA 94043
+ United States
+
+ EMail: cevans@google.com
+
+
+ Chris Palmer
+ Google, Inc.
+ 1600 Amphitheatre Pkwy
+ Mountain View, CA 94043
+ United States
+
+ EMail: palmer@google.com
+
+
+ Ryan Sleevi
+ Google, Inc.
+ 1600 Amphitheatre Pkwy
+ Mountain View, CA 94043
+ United States
+
+ EMail: sleevi@google.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Evans, et al. Standards Track [Page 28]
+