draft-ietf-websec-key-pinning-08.txt   draft-ietf-websec-key-pinning-09.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: January 13, 2014 Google, Inc. Expires: May 31, 2014 Google, Inc.
July 12, 2013 November 27, 2013
Public Key Pinning Extension for HTTP Public Key Pinning Extension for HTTP
draft-ietf-websec-key-pinning-08 draft-ietf-websec-key-pinning-09
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 January 13, 2014. This Internet-Draft will expire on May 31, 2014.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2013 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 32 skipping to change at page 2, line 32
2.2. Server Processing Model . . . . . . . . . . . . . . . . . 7 2.2. Server Processing Model . . . . . . . . . . . . . . . . . 7
2.2.1. HTTP-over-Secure-Transport Request Type . . . . . . . 7 2.2.1. HTTP-over-Secure-Transport Request Type . . . . . . . 7
2.2.2. HTTP Request Type . . . . . . . . . . . . . . . . . . 8 2.2.2. HTTP Request Type . . . . . . . . . . . . . . . . . . 8
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 . . . . . . . . . . 13
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 . . . . . . . . . . . . . . 14
4. Security Considerations . . . . . . . . . . . . . . . . . . . 14 4. Security Considerations . . . . . . . . . . . . . . . . . . . 15
4.1. Maximum max-age . . . . . . . . . . . . . . . . . . . . . 15 4.1. Maximum max-age . . . . . . . . . . . . . . . . . . . . . 15
4.2. Using includeSubDomains Safely . . . . . . . . . . . . . 16 4.2. Using includeSubDomains Safely . . . . . . . . . . . . . 16
4.3. Backup Pins . . . . . . . . . . . . . . . . . . . . . . . 17 4.3. Backup Pins . . . . . . . . . . . . . . . . . . . . . . . 17
5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 17 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 17
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18
7. Usability Considerations . . . . . . . . . . . . . . . . . . 19 7. Usability Considerations . . . . . . . . . . . . . . . . . . 19
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 19 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 19
9. What's Changed . . . . . . . . . . . . . . . . . . . . . . . 19 9. What's Changed . . . . . . . . . . . . . . . . . . . . . . . 19
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 20
10.1. Normative References . . . . . . . . . . . . . . . . . . 20 10.1. Normative References . . . . . . . . . . . . . . . . . . 20
10.2. Informative References . . . . . . . . . . . . . . . . . 21 10.2. Informative References . . . . . . . . . . . . . . . . . 21
Appendix A. Fingerprint Generation . . . . . . . . . . . . . . . 21 Appendix A. Fingerprint Generation . . . . . . . . . . . . . . . 21
Appendix B. Deployment Guidance . . . . . . . . . . . . . . . . 21 Appendix B. Deployment Guidance . . . . . . . . . . . . . . . . 22
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22
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.
skipping to change at page 7, line 45 skipping to change at page 7, line 45
implement. The model comprises two facets: the processing rules for implement. The model comprises two facets: the processing rules for
HTTP request messages received over a secure transport (e.g. TLS HTTP request messages received over a secure transport (e.g. TLS
[RFC5246]); and the processing rules for HTTP request messages [RFC5246]); and the processing rules for HTTP request messages
received over non-secure transports, such as TCP. received over non-secure transports, such as TCP.
2.2.1. HTTP-over-Secure-Transport Request Type 2.2.1. HTTP-over-Secure-Transport Request Type
When replying to an HTTP request that was conveyed over a secure When replying to an HTTP request that was conveyed over a secure
transport, a Pinned Host SHOULD include in its response exactly one transport, a Pinned Host SHOULD include in its response exactly one
PKP header field that MUST satisfy the grammar specified above in PKP header field that MUST satisfy the grammar specified above in
Section 2.1. If the Pinned Host does not include the PKP header Section 2.1.
field, and if the connection passed Pin Validation, UAs MUST treat
the host as if it had set its max-age to 0 (see Section 2.3.1).
Establishing a given host as a Known Pinned Host, in the context of a Establishing a given host as a Known Pinned Host, in the context of a
given UA, MAY be accomplished over the HTTP protocol, which is in given UA, MAY be accomplished over the HTTP protocol, which is in
turn running over secure transport, by correctly returning (per this turn running over secure transport, by correctly returning (per this
specification) at least one valid PKP header field to the UA. Other specification) at least one valid PKP header field to the UA. Other
mechanisms, such as a client-side pre-loaded Known Pinned Host list mechanisms, such as a client-side pre-loaded Known Pinned Host list
MAY also be used. MAY also be used.
2.2.2. HTTP Request Type 2.2.2. HTTP Request Type
skipping to change at page 8, line 31 skipping to change at page 8, line 35
internationalized domain names SHALL be canonicalized according to internationalized domain names SHALL be canonicalized according to
the scheme in Section 10 of [RFC6797]. the scheme in Section 10 of [RFC6797].
2.3.1. Public-Key-Pins Response Header Field Processing 2.3.1. Public-Key-Pins Response Header Field Processing
If the UA receives, over a secure transport, an HTTP response that If the UA receives, over a secure transport, an HTTP response that
includes a PKP header field conforming to the grammar specified in includes a PKP header field conforming to the grammar specified in
Section 2.1, and there are no underlying secure transport errors or Section 2.1, and there are no underlying secure transport errors or
warnings (see Section 2.5), the UA MUST either: warnings (see Section 2.5), the UA MUST either:
o Note the host as a Known HSTS Host if it is not already so noted o Note the host as a Known Pinned Host if it is not already so noted
(see Section 2.3.2), (see Section 2.3.2),
or, or,
o Update the UA's cached information for the Known Pinned Host if o Update the UA's cached information for the Known Pinned Host if
any of of the max-age, includeSubDomains, strict, or report-uri any of of the max-age, includeSubDomains, strict, or report-uri
header field value directives convey information different than header field value directives convey information different than
that already maintained by the UA. that already maintained by the UA.
o The max-age value is essentially a "time to live" value relative o The max-age value is essentially a "time to live" value relative
skipping to change at page 18, line 42 skipping to change at page 19, line 4
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 some UAs Valid Pinning Headers for some, but not all giving 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
in the "Message Headers" registry, with the following parameters:
This document has no actions for IANA. However, in the future there o Header Field Name should be "Public-Key-Pins"
may arise a need for a registry of extension directives (see
Section 2.1). o Protocol should be "http"
o Status should be "standard"
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
skipping to change at page 19, line 28 skipping to change at page 19, line 38
Thanks to Tobias Gondrom, Jeff Hodges, Ivan Krstic, Adam Langley, Thanks to Tobias Gondrom, Jeff Hodges, Ivan Krstic, Adam Langley,
Nicolas Lidzborski, SM, James Manger, Eric Rescorla, Paul Hoffman, Nicolas Lidzborski, SM, James Manger, Eric Rescorla, Paul Hoffman,
and Yoav Nir for suggestions and edits that clarified the text. and Yoav Nir for suggestions and edits that clarified the text.
Thanks to Trevor Perrin for suggesting a mechanism to affirmatively Thanks to Trevor Perrin for suggesting a mechanism to affirmatively
break pins ([pin-break-codes]). 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 requirement that the server set the Valid Pinning Header
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
script using openssl. script using openssl.
Changed max-max-age from SHOULD to MAY, and used the example of 60 Changed max-max-age from SHOULD to MAY, and used the example of 60
days instead of 30. days instead of 30.
skipping to change at page 20, line 19 skipping to change at page 20, line 34
Separated normative from non-normative material. Removed tangential Separated normative from non-normative material. Removed tangential
and out-of-scope non-normative discussion. and out-of-scope non-normative discussion.
10. References 10. References
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-01 (work in CMS Structures", draft-josefsson-pkix-textual-02 (work in
progress), July 2012. progress), October 2013.
[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., [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 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.
 End of changes. 12 change blocks. 
17 lines changed or deleted 24 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/