draft-ietf-websec-key-pinning-10.txt   draft-ietf-websec-key-pinning-11.txt 
Web Security C. Evans Web Security C. Evans
Internet-Draft C. Palmer Internet-Draft C. Palmer
Intended status: Standards Track R. Sleevi Intended status: Standards Track R. Sleevi
Expires: August 10, 2014 Google, Inc. Expires: August 12, 2014 Google, Inc.
February 6, 2014 February 8, 2014
Public Key Pinning Extension for HTTP Public Key Pinning Extension for HTTP
draft-ietf-websec-key-pinning-10 draft-ietf-websec-key-pinning-11
Abstract Abstract
This memo describes an extension to the HTTP protocol allowing web This memo describes an extension to the HTTP protocol allowing web
host operators to instruct user agents (UAs) to remember ("pin") the host operators to instruct user agents (UAs) to remember ("pin") the
hosts' cryptographic identities for a given period of time. During hosts' cryptographic identities for a given period of time. During
that time, UAs will require that the host present a certificate chain that time, UAs will require that the host present a certificate chain
including at least one Subject Public Key Info structure whose including at least one Subject Public Key Info structure whose
fingerprint matches one of the pinned fingerprints for that host. By fingerprint matches one of the pinned fingerprints for that host. By
effectively reducing the number of authorities who can authenticate effectively reducing the number of authorities who can authenticate
skipping to change at page 1, line 40 skipping to change at page 1, line 40
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on August 10, 2014. This Internet-Draft will expire on August 12, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 34 skipping to change at page 2, line 34
2.3. User Agent Processing Model . . . . . . . . . . . . . . . 8 2.3. User Agent Processing Model . . . . . . . . . . . . . . . 8
2.3.1. Public-Key-Pins Response Header Field Processing . . 8 2.3.1. Public-Key-Pins Response Header Field Processing . . 8
2.3.2. Noting a Pinned Host - Storage Model . . . . . . . . 9 2.3.2. Noting a Pinned Host - Storage Model . . . . . . . . 9
2.3.3. HTTP-Equiv <Meta> Element Attribute . . . . . . . . . 10 2.3.3. HTTP-Equiv <Meta> Element Attribute . . . . . . . . . 10
2.4. Semantics of Pins . . . . . . . . . . . . . . . . . . . . 10 2.4. Semantics of Pins . . . . . . . . . . . . . . . . . . . . 10
2.5. Noting Pins . . . . . . . . . . . . . . . . . . . . . . . 11 2.5. Noting Pins . . . . . . . . . . . . . . . . . . . . . . . 11
2.6. Validating Pinned Connections . . . . . . . . . . . . . . 12 2.6. Validating Pinned Connections . . . . . . . . . . . . . . 12
2.7. Interactions With Preloaded Pin Lists . . . . . . . . . . 12 2.7. Interactions With Preloaded Pin Lists . . . . . . . . . . 12
2.8. Pinning Self-Signed End Entities . . . . . . . . . . . . 13 2.8. Pinning Self-Signed End Entities . . . . . . . . . . . . 13
3. Reporting Pin Validation Failure . . . . . . . . . . . . . . 13 3. Reporting Pin Validation Failure . . . . . . . . . . . . . . 13
4. Security Considerations . . . . . . . . . . . . . . . . . . . 15 4. Security Considerations . . . . . . . . . . . . . . . . . . . 16
4.1. Maximum max-age . . . . . . . . . . . . . . . . . . . . . 15 4.1. Maximum max-age . . . . . . . . . . . . . . . . . . . . . 17
4.2. Using includeSubDomains Safely . . . . . . . . . . . . . 16 4.2. Using includeSubDomains Safely . . . . . . . . . . . . . 17
4.3. Backup Pins . . . . . . . . . . . . . . . . . . . . . . . 17 4.3. Backup Pins . . . . . . . . . . . . . . . . . . . . . . . 18
5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 17 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 19
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20
7. Usability Considerations . . . . . . . . . . . . . . . . . . 19 7. Usability Considerations . . . . . . . . . . . . . . . . . . 20
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 19 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 20
9. What's Changed . . . . . . . . . . . . . . . . . . . . . . . 19 9. What's Changed . . . . . . . . . . . . . . . . . . . . . . . 21
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 21
10.1. Normative References . . . . . . . . . . . . . . . . . . 20 10.1. Normative References . . . . . . . . . . . . . . . . . . 22
10.2. Informative References . . . . . . . . . . . . . . . . . 21 10.2. Informative References . . . . . . . . . . . . . . . . . 23
Appendix A. Fingerprint Generation . . . . . . . . . . . . . . . 21 Appendix A. Fingerprint Generation . . . . . . . . . . . . . . . 23
Appendix B. Deployment Guidance . . . . . . . . . . . . . . . . 22 Appendix B. Deployment Guidance . . . . . . . . . . . . . . . . 23
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24
1. Introduction 1. Introduction
We propose a new HTTP header to enable a web host to express to user We propose a new HTTP header to enable a web host to express to user
agents (UAs) which Subject Public Key Info (SPKI) structure(s) UAs agents (UAs) which Subject Public Key Info (SPKI) structure(s) UAs
SHOULD expect to be present in the host's certificate chain in future SHOULD expect to be present in the host's certificate chain in future
connections using TLS (see [RFC5246]). We call this "public key connections using TLS (see [RFC5246]). We call this "public key
pinning". At least one UA (Google Chrome) has experimented with the pinning". At least one UA (Google Chrome) has experimented with the
idea by shipping with a user-extensible embedded set of pins. idea by shipping with a user-extensible embedded set of Pins.
Although effective, this does not scale. This proposal addresses the Although effective, this does not scale. This proposal addresses the
scale problem. scale problem.
Deploying public key pinning safely will require operational and Deploying public key pinning safely will require operational and
organizational maturity due to the risk that hosts may make organizational maturity due to the risk that hosts may make
themselves unavailable by pinning to a SPKI that becomes invalid. themselves unavailable by pinning to a SPKI that becomes invalid.
(See Section 4.) We believe that, with care, host operators can (See Section 4.) We believe that, with care, host operators can
greatly reduce the risk of MITM attacks and other false- greatly reduce the risk of MITM attacks and other false-
authentication problems for their users without incurring undue risk. authentication problems for their users without incurring undue risk.
skipping to change at page 4, line 41 skipping to change at page 4, line 41
field. Directives are either optional or required, as stipulated field. Directives are either optional or required, as stipulated
in their definitions. in their definitions.
3. Directive names are case-insensitive. 3. Directive names are case-insensitive.
4. UAs MUST ignore any PKP header fields containing directives, or 4. UAs MUST ignore any PKP header fields containing directives, or
other header field value data, that do not conform to the syntax other header field value data, that do not conform to the syntax
defined in this specification. defined in this specification.
5. If a PKP header field contains any directive(s) the UA does not 5. If a PKP header field contains any directive(s) the UA does not
recognize, the UA MUST ignore the those directives. recognize, the UA MUST ignore those directives.
6. If the PKP header field otherwise satisfies the above 6. If the PKP header field otherwise satisfies the above
requirements (1 through 5), the UA MUST process the directives it requirements (1 through 5), the UA MUST process the directives it
recognizes. recognizes.
Additional directives extending the semantic functionality of the PKP Additional directives extending the semantic functionality of the PKP
header field can be defined in other specifications, with a registry header field can be defined in other specifications, with a registry
(having an IANA policy definition of IETF Review [RFC2616]) defined (having an IANA policy definition of IETF Review [RFC2616]) defined
for them at such time. Such future directives will be ignored by UAs for them at such time. Such future directives will be ignored by UAs
implementing only this specification, as well as by generally non- implementing only this specification, as well as by generally non-
skipping to change at page 6, line 9 skipping to change at page 6, line 9
When used in the Public-Key-Pins-Report-Only header, the UA SHOULD When used in the Public-Key-Pins-Report-Only header, the UA SHOULD
POST reports for Pin Validation failures to the indicated report-uri, POST reports for Pin Validation failures to the indicated report-uri,
although the UA MUST NOT enforce Pin Validation. That is, in the although the UA MUST NOT enforce Pin Validation. That is, in the
event of Pin Validation failure when the host has set the Public-Key- event of Pin Validation failure when the host has set the Public-Key-
Pins-Report-Only header, the UA performs Pin Validation only to check Pins-Report-Only header, the UA performs Pin Validation only to check
whether or not it should POST a report, but not for causing whether or not it should POST a report, but not for causing
connection failure. connection failure.
If a Host sets both the Public-Key-Pins header and the Public-Key- If a Host sets both the Public-Key-Pins header and the Public-Key-
Pins-Report-Only header, the UA MUST NOT enforce Pin Validation, and Pins-Report-Only header, the UA MUST NOT enforce Pin Validation, and
MUST note only the pins and directives given in the Public-Key-Pins- MUST note only the Pins and directives given in the Public-Key-Pins-
Report-Only header. Report-Only header.
When used in the Public-Key-Pins header, the presence of a report-uri When used in the Public-Key-Pins header, the presence of a report-uri
directive indicates to the UA that the UA MUST enforce Pin directive indicates to the UA that the UA MUST enforce Pin
Validation, and the UA SHOULD also, in the event of Pin Validation Validation, and the UA SHOULD also, in the event of Pin Validation
failure, POST a report to the report-uri. failure, POST a report to the report-uri.
Note that the report-uri need not necessarily be in the same Internet Note that the report-uri need not necessarily be in the same Internet
domain or web origin as the Known Pinned Host. domain or web origin as the Known Pinned Host.
skipping to change at page 6, line 43 skipping to change at page 6, line 43
referring to A, and if both hosts fail Pin Validation, the UA SHOULD 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 detect and break the loop by failing to send reports to and about
those hosts. those hosts.
UAs SHOULD limit the rate at which they send reports. For example, 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 it is unnecessary to send the same report to the same report-uri more
than once. than once.
2.1.4. Examples 2.1.4. Examples
Figure 3 shows some example response header fields using the pins Figure 3 shows some example response header fields using the Pins
extension (folded for clarity). extension (folded for clarity).
"d6qzRu9zOECb90Uez27xWltNsj0e1Md7GkYYkVoZWmM="
"E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g="
Public-Key-Pins: max-age=3000; Public-Key-Pins: max-age=3000;
pin-sha256="d6qzRu9zOECb90Uez27xWltNsj0e1Md7GkYYkVoZWmM="; pin-sha256="d6qzRu9zOECb90Uez27xWltNsj0e1Md7GkYYkVoZWmM=";
pin-sha256="E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g="; pin-sha256="E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g=";
Public-Key-Pins: max-age=2592000; Public-Key-Pins: max-age=2592000;
pin-sha256="E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g="; pin-sha256="E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g=";
pin-sha256="LPJNul+wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ=" pin-sha256="LPJNul+wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ="
Public-Key-Pins: max-age=2592000; Public-Key-Pins: max-age=2592000;
pin-sha256="E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g="; pin-sha256="E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g=";
skipping to change at page 9, line 48 skipping to change at page 9, line 48
with it the Effective Expiration Date (or enough information to with it the Effective Expiration Date (or enough information to
calculate it, i.e. the Effective Pin Date and the value of the max- calculate it, i.e. the Effective Pin Date and the value of the max-
age directive), whether or not the includeSubDomains directive is age directive), whether or not the includeSubDomains directive is
asserted, the value of the report-uri directive (if present). If any asserted, the value of the report-uri directive (if present). If any
other metadata from optional or future PKP header directives is other metadata from optional or future PKP header directives is
present in the Valid Pinning Header, the UA MAY note them if it present in the Valid Pinning Header, the UA MAY note them if it
understands them, and need not note them if it does not understand understands them, and need not note them if it does not understand
them. them.
UAs MAY set an upper limit on the value of max-age, so that UAs that 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 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 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 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 set the max-age to the UA's upper limit. For example, if the UA caps
max-age at 5184000 seconds (60 days), and a Pinned Host sets a max- max-age at 5184000 seconds (60 days), and a Pinned Host sets a max-
age directive of 90 days in its Valid Pinning Header, the UA MAY 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 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 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 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 UA implementation guidance on how to select a maximum max-age, see
Section 4.1. Section 4.1.
The UA MUST NOT modify any pinning metadata of any superdomain The UA MUST NOT modify any pinning metadata of any superdomain
matched Known Pinned Host. matched Known Pinned Host.
2.3.3. HTTP-Equiv <Meta> Element Attribute 2.3.3. HTTP-Equiv <Meta> Element Attribute
UAs MUST NOT heed http-equiv="Public-Key-Pins" attribute settings on UAs MUST NOT heed http-equiv="Public-Key-Pins" or http-equiv="Public-
<meta> elements [W3C.REC-html401-19991224] in received content. Key-Pins-Report-Only" attribute settings on <meta> elements
[W3C.REC-html401-19991224] in received content.
2.4. Semantics of Pins 2.4. Semantics of Pins
An SPKI Fingerprint is defined as the output of a known cryptographic An SPKI Fingerprint is defined as the output of a known cryptographic
hash algorithm whose input is the DER-encoded ASN.1 representation of hash algorithm whose input is the DER-encoded ASN.1 representation of
the SubjectPublicKeyInfo (SPKI) field of an X.509 certificate. A Pin the SubjectPublicKeyInfo (SPKI) field of an X.509 certificate. A Pin
is defined as the combination of the known algorithm identifier and is defined as the combination of the known algorithm identifier and
the SPKI Fingerprint computed using that algorithm. the SPKI Fingerprint computed using that algorithm.
The SPKI Fingerprint is encoded in base 64 for use in an HTTP header. The SPKI Fingerprint is encoded in base 64 for use in an HTTP header.
(See [RFC4648].) (See [RFC4648].)
In this version of the specification, the known cryptographic hash In this version of the specification, the known cryptographic hash
algorithm is SHA-256, identified as "sha256" ([RFC4634]). (Future algorithm is SHA-256, identified as "sha256" ([RFC4634]). (Future
versions of this specification may add new algorithms and deprecate versions of this specification may add new algorithms and deprecate
old ones.) UAs MUST ignore Pins for which they do not recognize the 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 algorithm identifier. UAs MUST continue to process the rest of a PKP
response header field and note Pins for algorithms they do recognize; response header field and note Pins for algorithms they do recognize;
UAs MUST recognize and "sha256". UAs MUST recognize "sha256".
Figure 4 reproduces the definition of the SubjectPublicKeyInfo Figure 4 reproduces the definition of the SubjectPublicKeyInfo
structure in [RFC5280]. structure in [RFC5280].
SubjectPublicKeyInfo ::= SEQUENCE { SubjectPublicKeyInfo ::= SEQUENCE {
algorithm AlgorithmIdentifier, algorithm AlgorithmIdentifier,
subjectPublicKey BIT STRING } subjectPublicKey BIT STRING }
AlgorithmIdentifier ::= SEQUENCE { AlgorithmIdentifier ::= SEQUENCE {
algorithm OBJECT IDENTIFIER, algorithm OBJECT IDENTIFIER,
skipping to change at page 12, line 4 skipping to change at page 12, line 4
Public-Key-Pins response header field that meets all these critera is Public-Key-Pins response header field that meets all these critera is
known as a Valid Pinning Header. known as a Valid Pinning Header.
Whenever a UA receives a Valid Pinning Header, it MUST set its Whenever a UA receives a Valid Pinning Header, it MUST set its
Pinning Metadata to the exact Pins, max-age, and (if any) report-uri Pinning Metadata to the exact Pins, max-age, and (if any) report-uri
given in the most recently received Valid Pinning Header. given in the most recently received Valid Pinning Header.
For forward compatibility, the UA MUST ignore any unrecognized For forward compatibility, the UA MUST ignore any unrecognized
Public-Key-Pins header directives, while still processing those Public-Key-Pins header directives, while still processing those
directives it does recognize. Section 2.1 specifies the directives directives it does recognize. Section 2.1 specifies the directives
max-age, pins, includeSubDomains, and report-uri but future max-age, Pins, includeSubDomains, and report-uri but future
specifications and implementations might use additional directives. specifications and implementations might use additional directives.
2.6. Validating Pinned Connections 2.6. Validating Pinned Connections
When a UA connects to a Pinned Host, if the TLS connection has When a UA connects to a Pinned Host, if the TLS connection has
errors, the UA MUST terminate the connection without allowing the errors, the UA MUST terminate the connection without allowing the
user to proceed anyway. (This behavior is the same as that required user to proceed anyway. (This behavior is the same as that required
by [RFC6797].) by [RFC6797].)
If the connection has no errors, then the UA will determine whether If the connection has no errors, then the UA will determine whether
skipping to change at page 13, line 15 skipping to change at page 13, line 15
UAs that support additional sources of pinning information MUST use UAs that support additional sources of pinning information MUST use
the most recently observed pinning information when performing Pin the most recently observed pinning information when performing Pin
Validation for a host. The most recently observed pinning Validation for a host. The most recently observed pinning
information is determined based upon the most recent Effective Pin information is determined based upon the most recent Effective Pin
Date, as described in Section 2.3.2. Date, as described in Section 2.3.2.
If the result of noting a Valid Pinning Header is to disable pinning If the result of noting a Valid Pinning Header is to disable pinning
for the host, such as through supplying a max-age directive with a for the host, such as through supplying a max-age directive with a
value of 0, UAs MUST allow this new information to override any other value of 0, UAs MUST allow this new information to override any other
pinning data. That is, a host must be able to un-pin itself, even in pinning data. That is, a host must be able to un-pin itself, even in
the presence of built-in pins. the presence of built-in Pins.
Example: A UA may ship with a pre-configured list of pins that are Example: A UA may ship with a pre-configured list of Pins that are
collected from past observations of Valid Pinning Headers supplied by collected from past observations of Valid Pinning Headers supplied by
hosts. In such a solution, the pre-configured list should track when hosts. In such a solution, the pre-configured list should track when
the Valid Pinning Header was last observed, in order to permit site the Valid Pinning Header was last observed, in order to permit site
operators to later update the value by supplying a new Valid Pinning operators to later update the value by supplying a new Valid Pinning
Header. Updates to such a pre-configured list should not update the Header. Updates to such a pre-configured list should not update the
Effective Pin Dates for each host unless the list vendor has actually Effective Pin Dates for each host unless the list vendor has actually
observed a more recent header. This is to prevent situations where observed a more recent header. This is to prevent situations where
updating the Effective Pin Date on a pre-configured list of pins may updating the Effective Pin Date on a pre-configured list of Pins may
effectively extend the max-age beyond the site operator's stated effectively extend the max-age beyond the site operator's stated
policy. policy.
Example: A UA may ship with a pre-configured list of pins that are Example: A UA may ship with a pre-configured list of Pins that are
collected through out-of-band means, such as direct contact with the collected through out-of-band means, such as direct contact with the
site operator. In such a solution, the site operator accepts site operator. In such a solution, the site operator accepts
responsibility for keeping the configured Valid Pinning Header in responsibility for keeping the configured Valid Pinning Header in
sync with the vendor's list, allowing the UA vendor to have each sync with the vendor's list, allowing the UA vendor to have each
update to the list be treated as as an update of the Effective Pin update to the list be treated as as an update of the Effective Pin
Date. Date.
2.8. Pinning Self-Signed End Entities 2.8. Pinning Self-Signed End Entities
If UAs accept hosts that authenticate themselves with self-signed end If UAs accept hosts that authenticate themselves with self-signed end
skipping to change at page 14, line 9 skipping to change at page 14, line 9
When a Known Pinned Host has set the report-uri directive, the UA When a Known Pinned Host has set the report-uri directive, the UA
SHOULD report Pin Validation failures to the indicated URI. The UA SHOULD report Pin Validation failures to the indicated URI. The UA
does this by POSTing a JSON ([RFC4627]) message to the URI; the JSON does this by POSTing a JSON ([RFC4627]) message to the URI; the JSON
message takes this form: message takes this form:
{ {
"date-time": date-time, "date-time": date-time,
"hostname": hostname, "hostname": hostname,
"port": port, "port": port,
"certificate-chain": [ "effective-expiration-date": expiration-date,
"include-subdomains": include-subdomains,
"served-certificate-chain": [
pem1, ... pemN
],
"validated-certificate-chain": [
pem1, ... pemN pem1, ... pemN
], ],
"known-pins": [ "known-pins": [
known-pin1, ... known-pinN known-pin1, ... known-pinN
] ]
} }
Figure 5: JSON Report Format Figure 5: JSON Report Format
Whitespace outside of quoted strings is not significant. The key/ Whitespace outside of quoted strings is not significant. The key/
skipping to change at page 14, line 34 skipping to change at page 14, line 39
failure. It is provided as a string formatted according to failure. It is provided as a string formatted according to
Section 5.6, "Internet Date/Time Format", of [RFC3339]. Section 5.6, "Internet Date/Time Format", of [RFC3339].
The hostname is the hostname to which the UA made the original The hostname is the hostname to which the UA made the original
request that failed Pin Validation. It is provided as a string. 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 The port is the port to which the UA made the original request that
failed Pin Validation. It is provided either as a string or as an failed Pin Validation. It is provided either as a string or as an
integer. integer.
The certificate-chain is the certificate chain, as constructed by the The effective-expiration-date is the Effective Expiration Date for
UA during certificate chain verification. (This may differ from the the noted Pins. It is provided as a string formatted according to
certificate chain as served by the Known Pinned Host, of course.) It Section 5.6, "Internet Date/Time Format", of [RFC3339].
is provided as an array of strings; each string pem1, ... pemN is the
PEM representation of each X.509 certificate as described in 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.
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 PEM
representation of each X.509 certificate as described in
[I-D.josefsson-pkix-textual].
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
[I-D.josefsson-pkix-textual]. [I-D.josefsson-pkix-textual].
The known-pins are the Pins that the UA has noted for the Known 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 Pinned Host. They are provided as an array of strings with the
syntax: syntax:
known-pin = token "=" quoted-string known-pin = token "=" quoted-string
Figure 6: Known Pin Syntax Figure 6: Known Pin Syntax
As in Section 2.4, the token refers to the algorithm name, and the As in Section 2.4, the token refers to the algorithm name, and the
quoted-string refers to the base 64 encoding of the SPKI Fingerprint. quoted-string refers to the base 64 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 \-escape
the embedded double quotes in the quoted-string part of the known-
pin.
Figure 7 shows an example of a Pin Validation failure report. (PEM
strings are shown on multiple lines for readability in this
document.)
{
"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 7: Pin Validation Failure Report Example
4. Security Considerations 4. Security Considerations
Pinning public keys helps hosts strongly assert their cryptographic Pinning public keys helps hosts strongly assert their cryptographic
identity even in the face of issuer error, malfeasance or compromise. identity even in the face of issuer error, malfeasance or compromise.
But there is some risk that a host operator could lose or lose 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 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 compromise). If the operator had pinned only the key of the
host's end entity certificate, the operator would not be able to 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 serve their web site or application in a way that UAs would trust for
skipping to change at page 15, line 40 skipping to change at page 17, line 25
still giving that host flexibility to change keys without a still giving that host flexibility to change keys without a
disruption of service. disruption of service.
4.1. Maximum max-age 4.1. Maximum max-age
As mentioned in Section 2.3.2, UAs MAY cap the max-age value at some As mentioned in Section 2.3.2, UAs MAY cap the max-age value at some
upper limit. There is a security trade-off in that low maximum upper limit. There is a security trade-off in that low maximum
values provide a narrow window of protection for users who visit the values provide a narrow window of protection for users who visit the
Known Pinned Host only infrequently, while high maximum values might Known Pinned Host only infrequently, while high maximum values might
potentially result in a UA's inability to successfully perform Pin potentially result in a UA's inability to successfully perform Pin
Validation for a Known Pinned Host if the UA's noted pins and the Validation for a Known Pinned Host if the UA's noted Pins and the
Host's true pins diverge. Host's true Pins diverge.
Such divergence could occur for several reasons, including: UA error; Such divergence could occur for several reasons, including: UA error;
Host operator error; network attack; or a Known Pinned Host that Host operator error; network attack; or a Known Pinned Host that
intentionally migrates all pinned keys, combined with a UA that has 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 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 observe the new true Pins for the Host. (This last example
underscores the importance for Host operators to phase in new keys underscores the importance for Host operators to phase in new keys
gradually, and to set the max-age value in accordance with their gradually, and to set the max-age value in accordance with their
planned key migration schedule.) planned key migration schedule.)
There is probably no ideal upper limit to the max-age directive that 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 would satisfy all use cases. However, a value on the order of 60
days (5184000 seconds) may be considered a balance between the two days (5184000 seconds) may be considered a balance between the two
competing security concerns. competing security concerns.
4.2. Using includeSubDomains Safely 4.2. Using includeSubDomains Safely
It may happen that Pinned Hosts whose hostnames share a parent domain It may happen that Pinned Hosts whose hostnames share a parent domain
use different Valid Pinning Headers. If a Host whose hostname is a use different Valid Pinning Headers. If a Host whose hostname is a
parent domain for another Host sets the includeSubDomains directive, parent domain for another Host sets the includeSubDomains directive,
skipping to change at page 16, line 14 skipping to change at page 17, line 47
There is probably no ideal upper limit to the max-age directive that 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 would satisfy all use cases. However, a value on the order of 60
days (5184000 seconds) may be considered a balance between the two days (5184000 seconds) may be considered a balance between the two
competing security concerns. competing security concerns.
4.2. Using includeSubDomains Safely 4.2. Using includeSubDomains Safely
It may happen that Pinned Hosts whose hostnames share a parent domain It may happen that Pinned Hosts whose hostnames share a parent domain
use different Valid Pinning Headers. If a Host whose hostname is a use different Valid Pinning Headers. If a Host whose hostname is a
parent domain for another Host sets the includeSubDomains directive, parent domain for another Host sets the includeSubDomains directive,
the two Hosts' pins may conflict with each other. For example, the two Hosts' Pins may conflict with each other. For example,
consider two Known Pinned Hosts, example.com and consider two Known Pinned Hosts, example.com and
subdomain.example.com. Assume example.com sets a Valid Pinning subdomain.example.com. Assume example.com sets a Valid Pinning
Header such as this: Header such as this:
Public-Key-Pins: pin-sha256="ABC..."; pin-sha256="DEF..."; includeSubDomains Public-Key-Pins: max-age=12000; pin-sha256="ABC..."; pin-sha256="DEF...";
includeSubDomains
Figure 7: example.com Valid Pinning Header Figure 8: example.com Valid Pinning Header
Assume subdomain.example.com sets a Valid Pinning Header such as Assume subdomain.example.com sets a Valid Pinning Header such as
this: this:
Public-Key-Pins: pin-sha256="GHI..."; pin-sha256="JKL..." Public-Key-Pins: pin-sha256="GHI..."; pin-sha256="JKL..."
Figure 8: subdomain.example.com Valid Pinning Header Figure 9: subdomain.example.com Valid Pinning Header
Assume a UA that has not previously noted any pins for either of 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 these Hosts. If the UA first contacts subdomain.example.com, it will
note the pins in the Valid Pinning Header, and perform Pin Validation note the Pins in the Valid Pinning Header, and perform Pin Validation
as normal on subsequent conections. If the UA then contacts as normal on subsequent conections. If the UA then contacts
example.com, again it will note the pins and perform Pin Validation example.com, again it will note the Pins and perform Pin Validation
on future connections. However, if the UA happened to first on future connections. However, if the UA happened to first
example.com before subdomain.example.com, the UA would, due to example.com before subdomain.example.com, the UA would, due to
example.com's use of the includeSubDomains directive, attempt to example.com's use of the includeSubDomains directive, attempt to
perform Pin Validation for subdomain.example.com using the SPKI perform Pin Validation for subdomain.example.com using the SPKI
hashes ABC... and DEF..., which are not valid for the certificate hashes ABC... and DEF..., which are not valid for the certificate
chains subdomain.example.com (which uses certificates with SPKIs chains subdomain.example.com (which uses certificates with SPKIs
GHI... and JLK...). Thus, depending on the order in which the UA GHI... and JLK...). Thus, depending on the order in which the UA
observes the Valid Pinning Headers for hosts example.com and observes the Valid Pinning Headers for hosts example.com and
subdomain.example.com, Pin Validation might or might not fail for subdomain.example.com, Pin Validation might or might not fail for
subdomain.example.com, even if the certificate chain the UA receives subdomain.example.com, even if the certificate chain the UA receives
skipping to change at page 17, line 35 skipping to change at page 19, line 22
hence which domains the UA has contacted. A forensic attacker might hence which domains the UA has contacted. A forensic attacker might
find this information useful, even if the user has cleared other find this information useful, even if the user has cleared other
parts of the UA's state. parts of the UA's state.
More importantly, Hosts can use HSTS or HPKP as a "super-cookie", by More importantly, Hosts can use HSTS or HPKP as a "super-cookie", by
setting distinct policies for a number of subdomains. For example, setting distinct policies for a number of subdomains. For example,
assume example.com wishes to track distinct UAs without explicitly assume example.com wishes to track distinct UAs without explicitly
setting a cookie, or if a previously-set cookie is deleted from the setting a cookie, or if a previously-set cookie is deleted from the
UA's cookie store. Here are two attack scenarios. UA's cookie store. Here are two attack scenarios.
1. example.com can use report-uri and the ability to pin arbitrary o example.com can use report-uri and the ability to pin arbitrary
identifiers to distinguish UAs. identifiers to distinguish UAs.
2.
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 1. example.com sets a Valid Pinning Header in its response to
the hash of an SPKI, but is instead an arbitrary requests. The header asserts the includeSubDomains directive,
distinguishing string sent only in response to a particular and specifies a report-uri directive as well. Pages served by
request. For each request, the Host creates a new, distinct the host also include references to subresource https://
distinguishing string and sets it as if it were a pin. bad.example.com/foo.png.
3. The certificate chain served by bad.example.com does not pass 2. The Valid Pinning Header includes a "pin" that is not really
Pin Validation given the pin set the Host asserted in (1). the hash of an SPKI, but is instead an arbitrary
The HPKP-conforming UA attempts to report the Pin Validation distinguishing string sent only in response to a particular
failure to the specified report-uri, including the request. For each request, the Host creates a new, distinct
certificate chain it observed and the SPKI hashes it expected distinguishing string and sets it as if it were a pin.
to see. Among the SPKI hashes is the distinguishing string
in step (2).
3. example.com can use SNI and subdomains to distinguish UAs. 3. The certificate chain served by bad.example.com does not pass
Pin Validation given the pin set the Host asserted in (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).
4. o example.com can use SNI and subdomains to distinguish UAs.
1. example.com sets a Valid Pinning Header in its response to 1. example.com sets a Valid Pinning Header in its response to
requests. The header asserts the includeSubDomains requests. The header asserts the includeSubDomains directive.
directive.
2. On a subsequent page view, the Host responds with a page 2. On a subsequent page view, the Host responds with a page
including the subresource https://0.fingerprint.example.com/ including the subresource https://0.fingerprint.example.com/
foo.png, and the server responds using a certificate chain foo.png, and the server responds using a certificate chain
that does not pass Pin Validation for the pin-set defined in that does not pass Pin Validation for the pin-set defined in
the Valid Pinning Header in step (1). The HPKP-conforming UA the Valid Pinning Header in step (1). The HPKP-conforming UA
will close the connection, never completing the request to will close the connection, never completing the request to
0.fingerprint.example.com. The Host may thus note that this 0.fingerprint.example.com. The Host may thus note that this
particular UA had noted the (good) pins for that subdomain. particular UA had noted the (good) Pins for that subdomain.
3. example.com can distinguish 2^N UAs by serving Valid Pinning 3. example.com can distinguish 2^N UAs by serving Valid Pinning
Headers from an arbitrary number N distinct subdomains, Headers from an arbitrary number N distinct subdomains, giving
giving some UAs Valid Pinning Headers for some, but not all some UAs Valid Pinning Headers for some, but not all
subdomains (causing subsequent requests for subdomains (causing subsequent requests for
n.fingerprint.example.com to fail), and giving some UAs no n.fingerprint.example.com to fail), and giving some UAs no
Valid Pinning Header for other subdomains (causing subsequent Valid Pinning Header for other subdomains (causing subsequent
requests for m.fingerprint.example.com to succeed). requests for m.fingerprint.example.com to succeed).
6. IANA Considerations 6. IANA Considerations
IANA is requested to register the header described in this document IANA is requested to register the header described in this document
in the "Message Headers" registry, with the following parameters: in the "Message Headers" registry, with the following parameters:
o Header Field Name should be "Public-Key-Pins" o Header Field Names should be "Public-Key-Pins" and "Public-Key-
Pins-Report-Only".
o Protocol should be "http" o Protocol should be "http"
o Status should be "standard" o Status should be "standard"
o Reference should be this document o Reference should be this document
7. Usability Considerations 7. Usability Considerations
When pinning works to detect impostor Pinned Hosts, users will When pinning works to detect impostor Pinned Hosts, users will
experience denial of service. UAs MUST explain the reason why, i.e. experience denial of service. UAs MUST explain the reason why, i.e.
that it was impossible to verify the confirmed cryptographic identity that it was impossible to verify the confirmed cryptographic identity
of the host. of the host.
UAs MUST have a way for users to clear current pins for Pinned Hosts. UAs MUST have a way for users to clear current Pins for Pinned Hosts.
UAs SHOULD have a way for users to query the current state of Pinned UAs SHOULD have a way for users to query the current state of Pinned
Hosts. Hosts.
8. Acknowledgements 8. Acknowledgements
Thanks to Tobias Gondrom, Jeff Hodges, Ivan Krstic, Adam Langley, Thanks to Tobias Gondrom, Jeff Hodges, Paul Hoffman, Ivan Krstic,
Nicolas Lidzborski, SM, James Manger, Eric Rescorla, Paul Hoffman, Adam Langley, Nicolas Lidzborski, SM, James Manger, Yoav Nir, Eric
and Yoav Nir for suggestions and edits that clarified the text. Rescorla, and Tom Ritter for suggestions and edits that clarified the
Thanks to Trevor Perrin for suggesting a mechanism to affirmatively text. Thanks to Trevor Perrin for suggesting a mechanism to
break pins ([pin-break-codes]). affirmatively break Pins ([pin-break-codes]).
9. What's Changed 9. What's Changed
[RFC EDITOR: PLEASE REMOVE THIS SECTION] [RFC EDITOR: PLEASE REMOVE THIS SECTION]
Removed the strict directive. Removed the strict directive.
Removed the requirement that the server set the Valid Pinning Header Removed the requirement that the server set the Valid Pinning Header
on every response. on every response.
skipping to change at page 21, line 49 skipping to change at page 23, line 34
Appendix A. Fingerprint Generation Appendix A. Fingerprint Generation
This POSIX shell program generates SPKI Fingerprints, suitable for This POSIX shell program generates SPKI Fingerprints, suitable for
use in pinning, from PEM-encoded certificates. It is non-normative. use in pinning, from PEM-encoded certificates. It is non-normative.
openssl x509 -noout -in certificate.pem -pubkey | \ openssl x509 -noout -in certificate.pem -pubkey | \
openssl asn1parse -noout -inform pem -out public.key openssl asn1parse -noout -inform pem -out public.key
openssl dgst -sha256 -binary public.key | base64 openssl dgst -sha256 -binary public.key | base64
Figure 9: Example SPKI Fingerprint Generation Code Figure 10: Example SPKI Fingerprint Generation Code
Appendix B. Deployment Guidance Appendix B. Deployment Guidance
This section is non-normative guidance which may smooth the adoption This section is non-normative guidance which may smooth the adoption
of public key pinning. of public key pinning.
o Operators SHOULD get the backup public key signed by a different o Operators SHOULD get the backup public key signed by a different
(root and/or intermediary) CA than their primary certificate, and (root and/or intermediary) CA than their primary certificate, and
store the backup key pair safely offline. The semantics of an store the backup key pair safely offline. The semantics of an
SPKI Fingerprint do not require the issuance of a certificate to SPKI Fingerprint do not require the issuance of a certificate to
 End of changes. 42 change blocks. 
101 lines changed or deleted 159 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/