draft-ietf-websec-key-pinning-01.txt   draft-ietf-websec-key-pinning-02.txt 
Web Security C. Evans Web Security C. Evans
Internet-Draft C. Palmer Internet-Draft C. Palmer
Intended status: Standards Track Google, Inc. Intended status: Standards Track Google, Inc.
Expires: June 11, 2012 December 9, 2011 Expires: December 6, 2012 June 4, 2012
Public Key Pinning Extension for HTTP Public Key Pinning Extension for HTTP
draft-ietf-websec-key-pinning-01 draft-ietf-websec-key-pinning-02
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 or more of the pinned fingerprints for that fingerprint matches one or more of the pinned fingerprints for that
host. By effectively reducing the scope of authorities who can host. By effectively reducing the scope of authorities who can
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 June 11, 2012. This Internet-Draft will expire on December 6, 2012.
Copyright Notice Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the Copyright (c) 2012 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
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
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
MUST expect to be present in the host's certificate chain in future MUST expect to be present in the host's certificate chain in future
connections using TLS (see [rfc-5246]). We call this "public key connections using TLS (see [rfc-5246]). We call this "public key
pinning". At least one user agent (Google Chrome) has experimented pinning". At least one user agent (Google Chrome) has experimented
with shipping with a user-extensible embeded set of pins. Although with shipping with a user-extensible embedded set of pins. Although
effective, this does not scale. This proposal addresses the scale effective, this does not scale. This proposal addresses the scale
problem. 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 3.) We believe that, with care, host operators can (See Section 3.) 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 6, line 10 skipping to change at page 6, line 10
o The UA MUST note the pins if and only if the TLS connection was o The UA MUST note the pins if and only if the TLS connection was
authenticated with a certificate chain containing at least one of authenticated with a certificate chain containing at least one of
the SPKI structures indicated by at least one of the given the SPKI structures indicated by at least one of the given
fingerprints. (See Section 2.4.) fingerprints. (See Section 2.4.)
o The UA MUST note the pins if and only if the given set of pins o The UA MUST note the pins if and only if the given set of pins
contains at least one pin that does NOT refer to an SPKI in the 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 certificate chain. (That is, the host must set a Backup Pin; see
Section 3.1.) Section 3.1.)
If the Public-Key-Pins response header field does not meet all four If the Public-Key-Pins response header field does not meet all three
of these criteria, the UA MUST NOT note the host as a Pinned Host, of these criteria, the UA MUST NOT note the host as a Pinned Host,
and MUST discard any previously set Pinning Metadata for that host in and MUST discard any previously set Pinning Metadata for that host in
its non-volatile store. Public-Key-Pins response header fields that its non-volatile store. Public-Key-Pins response header fields that
meet all these critera are known as Valid Pinning Headers. meet all these critera are known as Valid Pinning Headers.
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 and max-age given in the most Pinning Metadata to the exact pins and max-age given in the most
recently received Valid Pinning Header. recently received Valid Pinning Header.
2.3.1. max-age 2.3.1. max-age
max-age specifies the number of seconds, after the reception of the max-age specifies the number of seconds, after the reception of the
Public-Key-Pins HTTP Response Header, during which the UA regards the Public-Key-Pins HTTP Response Header, during which the UA regards the
host as a Pinned Host. The delta-seconds production is specified in host as a Pinned Host (up to a maximum of 30 days; see Section 2.5).
[rfc-2616]. The delta-seconds production is specified in [rfc-2616].
Note that by setting a low or 0 value for max-age, hosts effectively Note that by setting a low or 0 value for max-age, hosts effectively
instruct UAs to cease regarding them as Pinned Hosts. instruct UAs to cease regarding them as Pinned Hosts.
2.4. Validating Pinned Connections 2.4. 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 [hsts-draft]. by [hsts-draft].)
If the connection has no errors, the UA will then apply a new If the connection has no errors, the UA will then apply a new,
correctness check: Pin Validation. To perform Pin Validation, the UA additional correctness check: Pin Validation. To perform Pin
will compute the fingerprints of the SPKI structures in each Validation, the UA will compute the fingerprints of the SPKI
certificate in the host's validated certificate chain. (The UA structures in each certificate in the host's validated certificate
ignores superfluous certificates in the chain that do not form part chain. (For the purposes of Pin Validation, the UA MUST ignore
of the validating chain.) The UA will then check that the set of superfluous certificates in the chain that do not form part of the
these fingerprints intersects the set of fingerprints in that host's validating chain.) The UA will then check that the set of these
fingerprints intersects the set of fingerprints in that host's
Pinning Metadata. If there is set intersection, the UA continues Pinning Metadata. If there is set intersection, the UA continues
with the connection as normal. Otherwise, the UA MUST treat this Pin with the connection as normal. Otherwise, the UA MUST treat this Pin
Failure as a non-recoverable error. Failure as a non-recoverable error.
Note that, although the UA has previously received public key pins at Note that, although the UA has previously received public key pins at
the HTTP layer, it can and MUST perform Pin Validation at the TLS the HTTP layer, it can and MUST perform Pin Validation at the TLS
layer, before beginning an HTTP conversation over the TLS channel. layer, before beginning an HTTP conversation over the TLS channel.
The TLS layer thus evaluates TLS connections with pinning information The TLS layer thus evaluates TLS connections with pinning information
the UA received previously, regardless of mechanism: statically the UA received previously, regardless of mechanism: statically
preloaded, via HTTP header, or some other means (possibly in the TLS preloaded, via HTTP header, or some other means (possibly in the TLS
layer itself). layer itself, such as specified in [tack-draft]).
2.5. Interactions With Preloaded Pin Lists 2.5. Pin Validity Times
In harmony with section 5.3.4 "Create and activate pins" of
[tack-draft], clients MUST enforce a maximum age for pins that is no
longer than the least of (a) 30 days (30 * 24 * 60 * 60 seconds)
after the most recent time that the client noted the pin; (b) the
amount of time the pin has been noted; or (c) the most recent time
the pin was noted + max-age:
active_period_end = MIN(current + current - initial,
time_pin_noted + max-age,
current + 30 days)
Figure 4
2.6. Interactions With Preloaded Pin Lists
UAs MAY choose to implement built-in public key pins, alongside any UAs MAY choose to implement built-in public key pins, alongside any
built-in HSTS opt-in list. UAs MUST allow users to override a built-in HSTS opt-in list. UAs MUST allow users to override a
built-in pin list, including turning it off. built-in pin list, including turning it off.
UAs MUST use the newest information -- built-in or set via Valid UAs MUST use the newest information -- built-in or set via Valid
Pinning Header -- when performing Pin Validation for the host. Pinning Header -- when performing Pin Validation for the host.
2.6. Pinning Self-Signed End Entities 2.7. 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
entity certificates, they MAY also allow hosts to pin the public keys entity certificates, they MAY also allow hosts to pin the public keys
in such certificates. The usability and security implications of in such certificates. The usability and security implications of
this practice are outside the scope of this specification. this practice are outside the scope of this specification.
3. Security Considerations 3. Security Considerations
Pinning public keys helps hosts assert their cryptographic identity, Pinning public keys helps hosts assert their cryptographic identity,
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
skipping to change at page 14, line 5 skipping to change at page 14, line 5
8.2. Informative References 8.2. Informative References
[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>.
[pin-break-codes] [pin-break-codes]
Perrin, T., "Self-Asserted Key Pinning", September 2011, Perrin, T., "Self-Asserted Key Pinning", September 2011,
<http://trevp.net/SAKP/>. <http://trevp.net/SAKP/>.
[tack-draft]
Perrin, T. and M. Marlinspike, "Trust Assertions for
Certificate Keys", May 2012,
<http://tools.ietf.org/html/draft-perrin-tls-tack>.
Appendix A. Fingerprint Generation Appendix A. Fingerprint Generation
This Go program generates public key fingerprints, suitable for use This Go program generates public key fingerprints, suitable for use
in pinning, from PEM-encoded certificates. It is non-normative. in pinning, from PEM-encoded certificates. It is non-normative.
package main package main
import ( import (
"io/ioutil" "io/ioutil"
"os" "os"
skipping to change at page 14, line 49 skipping to change at page 15, line 49
} }
cert := certs[0] cert := certs[0]
h := sha1.New() h := sha1.New()
h.Write(cert.RawSubjectPublicKeyInfo) h.Write(cert.RawSubjectPublicKeyInfo)
digest := h.Sum() digest := h.Sum()
fmt.Printf("Hex: %x\nBase64: %s\n", digest, fmt.Printf("Hex: %x\nBase64: %s\n", digest,
base64.StdEncoding.EncodeToString(digest)) base64.StdEncoding.EncodeToString(digest))
} }
Figure 4 Figure 5
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. store the backup key pair safely offline.
 End of changes. 14 change blocks. 
20 lines changed or deleted 41 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/