draft-ietf-websec-key-pinning-15.txt   draft-ietf-websec-key-pinning-16.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: December 18, 2014 Google, Inc. Expires: December 27, 2014 Google, Inc.
June 16, 2014 June 25, 2014
Public Key Pinning Extension for HTTP Public Key Pinning Extension for HTTP
draft-ietf-websec-key-pinning-15 draft-ietf-websec-key-pinning-16
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 to remember ("pin") the hosts' host operators to instruct user agents to remember ("pin") the hosts'
cryptographic identities for a given period of time. During that cryptographic identities for a given period of time. During that
time, UAs will require that the host present a certificate chain 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 December 18, 2014. This Internet-Draft will expire on December 27, 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 49 skipping to change at page 2, line 49
4.3. Backup Pins . . . . . . . . . . . . . . . . . . . . . . . 19 4.3. Backup Pins . . . . . . . . . . . . . . . . . . . . . . . 19
4.4. Interactions With Cookie Scoping . . . . . . . . . . . . 20 4.4. Interactions With Cookie Scoping . . . . . . . . . . . . 20
5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 20 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 20
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21
7. Usability Considerations . . . . . . . . . . . . . . . . . . 22 7. Usability Considerations . . . . . . . . . . . . . . . . . . 22
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 22 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 22
9. What's Changed . . . . . . . . . . . . . . . . . . . . . . . 22 9. What's Changed . . . . . . . . . . . . . . . . . . . . . . . 22
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 23
10.1. Normative References . . . . . . . . . . . . . . . . . . 23 10.1. Normative References . . . . . . . . . . . . . . . . . . 23
10.2. Informative References . . . . . . . . . . . . . . . . . 24 10.2. Informative References . . . . . . . . . . . . . . . . . 24
Appendix A. Fingerprint Generation . . . . . . . . . . . . . . . 24 Appendix A. Fingerprint Generation . . . . . . . . . . . . . . . 25
Appendix B. Deployment Guidance . . . . . . . . . . . . . . . . 24 Appendix B. Deployment Guidance . . . . . . . . . . . . . . . . 25
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26
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" (PKP). At least one UA (Google Chrome) has experimented pinning" (PKP). At least one UA (Google Chrome) has experimented
with the idea by shipping with a user-extensible embedded set of with the idea by shipping with a user-extensible embedded set of
Pins. Although effective, this does not scale. This proposal Pins. Although effective, this does not scale. This proposal
skipping to change at page 3, line 39 skipping to change at page 3, line 39
1.1. Requirements Language 1.1. Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119]. document are to be interpreted as described in RFC 2119 [RFC2119].
2. Server and Client Behavior 2. Server and Client Behavior
2.1. Response Header Field Syntax 2.1. Response Header Field Syntax
The Public-Key-Pins HTTP response header field (PKP header field) and The "Public-Key-Pins" and "Public-Key-Pins-Report-Only" header
Public-Key-Pins-Report-Only response header field (PKP-RO header fields, also referred to within this specification as the PKP and
field) indicate to a UA that it should perform Pin Validation PKP-RO header fields, respectively, are are response headers used by
server to indicate that a a UA should perform Pin Validation
(Section 2.6) in regards to the host emitting the response message (Section 2.6) in regards to the host emitting the response message
containing these header fields, and provide the necessary information containing these header fields, and provide the necessary information
for the UA to do so. for the UA to do so.
Figure 1 describes the syntax (Augmented Backus-Naur Form) of the Figure 1 describes the syntax (Augmented Backus-Naur Form) of the
header field. It is based on the Generic Grammar defined in header fields, using the grammar defined in [RFC5234] and the rules
Section 2 of [RFC2616] (which includes a notion of "implied linear defined in Section 3.2 of [RFC7230]. The field values of both header
whitespace", also known as "implied *LWS"). fields conform to the same rules.
Public-Key-Pins = Public-Key-Directives = [ directive ] *( OWS ";" OWS [ directive ] )
"Public-Key-Pins" ":" [ directive ] *( ";" [ directive ] )
Public-Key-Pins-Report-Only =
"Public-Key-Pins-Report-Only" ":" [ directive ] *( ";" [ directive ] )
directive = simple-directive directive = simple-directive
/ pin-directive / pin-directive
simple-directive = directive-name [ "=" directive-value ] simple-directive = directive-name [ "=" directive-value ]
directive-name = token directive-name = token
directive-value = token directive-value = token
/ quoted-string / quoted-string
pin-directive = "pin-" token "=" quoted-string pin-directive = "pin-" token "=" quoted-string
Figure 1: HPKP Header Syntax Figure 1: HPKP Header Syntax
token and quoted-string are used as defined in [RFC2616], OWS is used as defined in Section 3.2.3 of [RFC7230]. token and
Section 2.2. quoted-string are used as defined in Section 3.2.6 of [RFC7230].
The directives defined in this specification are described below. The directives defined in this specification are described below.
The overall requirements for directives are: The overall requirements for directives are:
1. The order of appearance of directives is not significant. 1. The order of appearance of directives is not significant.
2. All simple-directives MUST appear only once in a PKP header 2. All simple-directives MUST appear only once in a given header
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 header fields containing directives, or other
other header field value data, that do not conform to the syntax 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 header field contains any directive(s) the UA does not
recognize, the UA MUST ignore those directives. recognize, the UA MUST ignore those directives.
6. If the PKP header field otherwise satisfies the above 6. If the PKP or PKP-RO 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
header field can be defined in other specifications, with a registry header fields 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 [RFC5226]) 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-
conforming UAs. conforming UAs.
In the pin-directive, the token is the name of a cryptographic hash In the pin-directive, the token is the name of a cryptographic hash
algorithm, and MUST be "sha256". (In the future, additional hash algorithm, and MUST be "sha256". (In the future, additional hash
algorithms MAY be registered and used.) The quoted-string is a algorithms MAY be registered and used.) The quoted-string is a
sequence of base 64 digits: the base 64-encoded SPKI Fingerprint sequence of base 64 digits: the base 64-encoded SPKI Fingerprint
([RFC4648]). See Section 2.4. ([RFC4648]). See Section 2.4.
The UA MUST ignore pin-directives with tokens naming hash algorithms The UA MUST ignore pin-directives with tokens naming hash algorithms
it does not recognize. If the set of remaining effective pin- it does not recognize. If the set of remaining effective pin-
directives is empty, and if the connection passed Pin Validation with directives is empty, and if the connection passed Pin Validation with
the UA's existing noted pins for the Host (i.e. the Host is a Known the UA's existing noted pins for the Host (i.e. the Host is a Known
Pinned Host), the UA MUST cease to consider the Host as a Known Pinned Host), the UA MUST cease to consider the Host as a Known
Pinned Host. (I.e. the UA should fail open.) The UA SHOULD indicate Pinned Host. (I.e. the UA should fail open.) The UA SHOULD indicate
to users that the Host is no longer a Known Pinned Host. to users that the Host is no longer a Known Pinned Host.
2.1.1. The max-age Directive 2.1.1. The max-age Directive
The REQUIRED "max-age" directive specifies the number of seconds, The "max-age" directive specifies the number of seconds, after the
after the reception of the PKP header field, during which the UA reception of the PKP header field, during which the UA SHOULD regard
SHOULD regard the host (from whom the message was received) as a the host (from whom the message was received) as a Known Pinned Host.
Known Pinned Host. The delta-seconds production is specified in The delta-seconds production is specified in [RFC7234].
[RFC2616].
The syntax of the max-age directive's REQUIRED value (after quoted- The "max-age" directive is REQUIRED to be present within a "Public-
string unescaping, if necessary) is defined as: Key-Pins" header field, and is OPTIONAL within a "Public-Key-Pins-
Report-Only" header field.
If present, the max-age directive is REQUIRED to have a directive
value, for which the the syntax (after quoted-string unescaping, if
necessary) is defined as:
max-age-value = delta-seconds max-age-value = delta-seconds
delta-seconds = 1*DIGIT delta-seconds = 1*DIGIT
Figure 2: max-age Value Syntax Figure 2: max-age Value Syntax
delta-seconds is used as defined in [RFC2616], Section 3.3.2. delta-seconds is used as defined in [RFC7234], Section 1.2.1.
2.1.2. The includeSubDomains Directive 2.1.2. The includeSubDomains Directive
The OPTIONAL includeSubDomains directive is a valueless directive The OPTIONAL includeSubDomains directive is a valueless directive
which, if present (i.e., it is "asserted"), signals to the UA that which, if present (i.e., it is "asserted"), signals to the UA that
the Pinning Policy applies to this Pinned Host as well as any the Pinning Policy applies to this Pinned Host as well as any
subdomains of the host's domain name. subdomains of the host's domain name.
2.1.3. The report-uri Directive 2.1.3. The report-uri Directive
skipping to change at page 9, line 22 skipping to change at page 9, line 22
the UA MUST ignore any present PKP header field(s). the UA MUST ignore any present PKP header field(s).
o Similarly, if the UA receives the HTTP response over insecure o Similarly, if the UA receives the HTTP response over insecure
transport, the UA MUST ignore any present PKP-RO header field(s). transport, the UA MUST ignore any present PKP-RO header field(s).
o The UA MUST ignore any PKP or PKP-RO header fields not conforming o The UA MUST ignore any PKP or PKP-RO header fields not conforming
to the grammar specified in Section 2.1. to the grammar specified in Section 2.1.
2.3.2. Interaction of Public-Key-Pins and Public-Key-Pins-Report-Only 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- A server MAY set both the "Public-Key-Pins" and "Public-Key-Pins-
Only headers simultaneously. The headers do not interact with one Report-Only" headers simultaneously. The headers do not interact
another but the UA MUST process the PKP header and SHOULD process with one another but the UA MUST process the PKP header and SHOULD
both. process both.
The headers are processed according to Section 2.3.1. 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 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, 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 PKP-RO event of Pin Validation failure when the host has set the PKP-RO
header, the UA performs Pin Validation only to check whether or not header, the UA performs Pin Validation only to check whether or not
it should POST a report, but not for causing connection failure. it should POST a report, but not for causing connection failure.
skipping to change at page 22, line 27 skipping to change at page 22, line 27
Thanks to Tobias Gondrom, Jeff Hodges, Paul Hoffman, Ivan Krstic, Thanks to Tobias Gondrom, Jeff Hodges, Paul Hoffman, Ivan Krstic,
Adam Langley, Nicolas Lidzborski, SM, James Manger, Yoav Nir, Trevor Adam Langley, Nicolas Lidzborski, SM, James Manger, Yoav Nir, Trevor
Perrin, Eric Rescorla, Tom Ritter, and Yan Zhu for suggestions and Perrin, Eric Rescorla, Tom Ritter, and Yan Zhu for suggestions and
edits that clarified the text. edits that clarified the text.
9. What's Changed 9. What's Changed
[RFC EDITOR: PLEASE REMOVE THIS SECTION] [RFC EDITOR: PLEASE REMOVE THIS SECTION]
Clarified that max-age is REQUIRED for PKP, but OPTIONAL for PKP-RO
(where it has no effect.
Updated header field syntax and description to match that in
[RFC7230].
Updated normative references to current documents.
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.
Added normative references for SHA, JSON, and base-64. Added normative references for SHA, JSON, and base-64.
Added the Privacy Considerations section. Added the Privacy Considerations section.
Changed non-normative pin generation code from Go to POSIX shell Changed non-normative pin generation code from Go to POSIX shell
skipping to change at page 23, line 29 skipping to change at page 23, line 36
10.1. Normative References 10.1. Normative References
[I-D.josefsson-pkix-textual] [I-D.josefsson-pkix-textual]
Josefsson, S. and S. Leonard, "Text Encodings of PKIX and Josefsson, S. and S. Leonard, "Text Encodings of PKIX and
CMS Structures", draft-josefsson-pkix-textual-03 (work in CMS Structures", draft-josefsson-pkix-textual-03 (work in
progress), April 2014. progress), April 2014.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
Internet: Timestamps", RFC 3339, July 2002. Internet: Timestamps", RFC 3339, July 2002.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC Resource Identifier (URI): Generic Syntax", STD 66, RFC
3986, January 2005. 3986, January 2005.
[RFC4627] Crockford, D., "The application/json Media Type for [RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006. JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC4634] Eastlake, D. and T. Hansen, "US Secure Hash Algorithms [RFC4634] Eastlake, D. and T. Hansen, "US Secure Hash Algorithms
(SHA and HMAC-SHA)", RFC 4634, July 2006. (SHA and HMAC-SHA)", RFC 4634, July 2006.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, October 2006. Encodings", RFC 4648, October 2006.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
IANA Considerations Section in RFCs", BCP 26, RFC 5226, Specifications: ABNF", STD 68, RFC 5234, January 2008.
May 2008.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008. (TLS) Protocol Version 1.2", RFC 5246, August 2008.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, "Internet X.509 Public Key Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate Revocation List Infrastructure Certificate and Certificate Revocation List
(CRL) Profile", RFC 5280, May 2008. (CRL) Profile", RFC 5280, May 2008.
[RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265,
April 2011. April 2011.
[RFC6797] Hodges, J., Jackson, C., and A. Barth, "HTTP Strict [RFC6797] Hodges, J., Jackson, C., and A. Barth, "HTTP Strict
Transport Security (HSTS)", RFC 6797, November 2012. Transport Security (HSTS)", RFC 6797, November 2012.
[RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Message Syntax and Routing", RFC 7230, June
2014.
[RFC7234] Fielding, R., Nottingham, M., and J. Reschke, "Hypertext
Transfer Protocol (HTTP/1.1): Caching", RFC 7234, June
2014.
[W3C.REC-html401-19991224] [W3C.REC-html401-19991224]
Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01
Specification", World Wide Web Consortium Recommendation Specification", World Wide Web Consortium Recommendation
REC-html401-19991224, December 1999, REC-html401-19991224, December 1999,
<http://www.w3.org/TR/1999/REC-html401-19991224>. <http://www.w3.org/TR/1999/REC-html401-19991224>.
10.2. Informative References 10.2. Informative References
[I-D.perrin-tls-tack] [I-D.perrin-tls-tack]
Marlinspike, M., "Trust Assertions for Certificate Keys", Marlinspike, M., "Trust Assertions for Certificate Keys",
draft-perrin-tls-tack-02 (work in progress), January 2013. draft-perrin-tls-tack-02 (work in progress), January 2013.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
[why-pin-key] [why-pin-key]
Langley, A., "Public Key Pinning", May 2011, Langley, A., "Public Key Pinning", May 2011,
<http://www.imperialviolet.org/2011/05/04/pinning.html>. <http://www.imperialviolet.org/2011/05/04/pinning.html>.
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 | \
 End of changes. 25 change blocks. 
53 lines changed or deleted 70 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/