idnits 2.17.1 draft-ietf-websec-key-pinning-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 449 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? RFC 2119 keyword, line 60: '... MUST expect to be present in the ho...' RFC 2119 keyword, line 110: '... algorithm, and MUST be either "sha1"...' RFC 2119 keyword, line 146: '... ANY DEFINED BY algorithm OPTIONAL }...' RFC 2119 keyword, line 169: '... The UA MUST observe these condition...' RFC 2119 keyword, line 171: '... o The UA MUST note the pins if and...' (20 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 30, 2011) is 4524 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? '0' on line 385 looks like a reference -- Missing reference section? '1' on line 372 looks like a reference Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Web Security C. Evans 3 Internet-Draft C. Palmer 4 Expires: June 2, 2012 Google, Inc. 5 November 30, 2011 7 Public Key Pinning Extension for HTTP 8 draft-ietf-websec-key-pinning-00 10 Abstract 12 This memo describes an extension to the HTTP protocol allowing web 13 host operators to instruct user agents (UAs) to remember ("pin") the 14 hosts' cryptographic identities for a given period of time. During 15 that time, UAs will require that the host present a certificate chain 16 including at least one Subject Public Key Info structure whose 17 fingerprint matches one or more of the pinned fingerprints for that 18 host. By effectively reducing the scope of authorities who can 19 authenticate the domain during the lifetime of the pin, pinning may 20 reduce the incidence of man-in-the-middle attacks due to compromised 21 Certification Authorities and other authentication errors and 22 attacks. 24 Status of this Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on June 2, 2012. 41 Copyright Notice 43 Copyright (c) 2011 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 1. Introduction 58 We propose a new HTTP header to enable a web host to express to user 59 agents (UAs) which Subject Public Key Info (SPKI) structure(s) UAs 60 MUST expect to be present in the host's certificate chain in future 61 connections using TLS (see [rfc-5246]). We call this "public key 62 pinning". At least one user agent (Google Chrome) has experimented 63 with shipping with a user-extensible embeded set of pins. Although 64 effective, this does not scale. This proposal addresses the scale 65 problem. 67 Deploying public key pinning safely will require operational and 68 organizational maturity due to the risk that hosts may make 69 themselves unavailable by pinning to a SPKI that becomes invalid. 70 (See Section 3.) We believe that, with care, host operators can 71 greatly reduce the risk of MITM attacks and other false- 72 authentication problems for their users without incurring undue risk. 74 We intend for hosts to use public key pinning together with HSTS (as 75 defined in [hsts-draft], but is possible to pin keys without 76 requiring HSTS. 78 This draft is being discussed on the WebSec Working Group mailing 79 list, websec@ietf.org. 81 1.1. About Notation 83 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 84 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 85 document are to be interpreted as described in [rfc-2119]. 87 2. Server and Client Behavior 89 2.1. Response Header Field Syntax 91 To set a pin, hosts use a new HTTP header field, Public-Key-Pins, in 92 their HTTP responses. Figure 1 describes the syntax of the header 93 field. 95 Public-Key-Pins = "Public-Key-Pins" ":" LWS directives 97 directives = max-age LWS ";" LWS pins 98 / pins LWS ";" LWS max-age 100 max-age = "max-age" LWS "=" LWS delta-seconds 102 pins = pin 103 / pin LWS ";" LWS pins 105 pin = "pin-" token LWS "=" LWS quoted-string 107 Figure 1 109 In the pin rule, the token is the name of a cryptographic hash 110 algorithm, and MUST be either "sha1" or "sha256". (Future versions 111 of this specification may change the hash functions.) The quoted- 112 string is a sequence of base64 digits: a base64-encoded hash. See 113 Section 2.2. 115 Figure 2 shows some example response header fields using the pins 116 extension (folded for clarity). 118 Public-Key-Pins: max-age=500; 119 pins=sha1-4n972HfV354KP560yw4uqe/baXc=, 120 sha1-IvGeLsbqzPxdI0b0wuj2xVTdXgc= 122 Public-Key-Pins: max-age=31536000; 123 pins=sha1-4n972HfV354KP560yw4uqe/baXc=, 124 sha256-LPJNul+wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ= 126 Public-Key-Pins: pins=sha1-4n972HfV354KP560yw4uqe/baXc=, 127 sha1-qvTGHdzF6KLavt4PO0gs2a6pQ00=, 128 sha256-LPJNul+wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ= ; 129 max-age=2592000 131 Figure 2 133 2.2. Semantics of Pins 135 The fingerprint is the SHA-1 or SHA-256 hash of the DER-encoded ASN.1 136 representation of the SubjectPublicKeyInfo (SPKI) field of the X.509 137 certificate. Figure 3 reproduces the definition of the 138 SubjectPublicKeyInfo structure in [rfc-5280]. 140 SubjectPublicKeyInfo ::= SEQUENCE { 141 algorithm AlgorithmIdentifier, 142 subjectPublicKey BIT STRING } 144 AlgorithmIdentifier ::= SEQUENCE { 145 algorithm OBJECT IDENTIFIER, 146 parameters ANY DEFINED BY algorithm OPTIONAL } 148 Figure 3 150 The SPKI hash is then encoded in base-64 for use in an HTTP header. 151 (See [rfc-4648].) 153 We pin public keys, rather than entire certificates, to enable 154 operators to generate new certificates containing old public keys 155 (see [why-pin-key]). 157 See Appendix A for an example non-normative program that generates 158 public key fingerprints from SubjectPublicKeyInfo fields in 159 certificates. 161 2.3. Noting Pins 163 Upon receipt of the Public-Key-Pins response header field, the UA 164 notes the host as a Pinned Host, storing the pins and their 165 associated max-age in non-volatile storage (for example, along with 166 the HSTS metadata). The pins and their associated max-age are 167 collectively known as Pinning Metadata. 169 The UA MUST observe these conditions when noting a host: 171 o The UA MUST note the pins if and only if it received the Public- 172 Key-Pins response header field over an error-free TLS connection. 174 o The UA MUST note the pins if and only if the TLS connection was 175 authenticated with a certificate chain containing at least one of 176 the SPKI structures indicated by at least one of the given 177 fingerprints. (See Section 2.4.) 179 o The UA MUST note the pins if and only if the given set of pins 180 contains at least one pin that does NOT refer to an SPKI in the 181 certificate chain. (That is, the host must set a Backup Pin; see 182 Section 3.1.) 184 If the Public-Key-Pins response header field does not meet all three 185 of these criteria, the UA MUST NOT note the host as a Pinned Host, 186 and MUST discard any previously set Pinning Metadata for that host in 187 its non-volatile store. Public-Key-Pins response header fields that 188 meet all these critera are known as Valid Pinning Headers. 190 Whenever a UA receives a Valid Pinning Header, it MUST set its 191 Pinning Metadata to the exact pins and max-age given in the most 192 recently received Valid Pinning Header. 194 2.3.1. max-age 196 max-age specifies the number of seconds, after the reception of the 197 Public-Key-Pins HTTP Response Header, during which the UA regards the 198 host as a Pinned Host. The delta-seconds production is specified in 199 [rfc-2616]. 201 Note that by setting a low or 0 value for max-age, hosts effectively 202 instruct UAs to cease regarding them as Pinned Hosts. 204 2.4. Validating Pinned Connections 206 When a UA connects to a Pinned Host, if the TLS connection has 207 errors, it applies its usual policy. For example, depending on the 208 type of failure, the UA might or might now allow the user the option 209 of continuing with the connection anyway. For hosts that are Known 210 HSTS Hosts the UA MUST terminate the connection in case of TLS 211 errors, as required by [hsts-draft]. 213 If the connection has no errors, the UA will then apply a new 214 correctness check: Pin Validation. To perform Pin Validation, the UA 215 will compute the fingerprints of the SPKI structures in each 216 certificate in the host's certificate chain. The UA will then check 217 that the set of these fingerprints intersects the set of fingerprints 218 in that host's Pinning Metadata. If there is set intersection, the 219 UA continues with the connection as normal. Otherwise, the UA MUST 220 treat this Pin Failure as a non-recoverable error. 222 Note that, although the UA has previously received public key pins at 223 the HTTP layer, it can and MUST perform Pin Validation at the TLS 224 layer, before beginning an HTTP conversation over the TLS channel. 225 The TLS layer thus evaluates TLS connections with pinning information 226 the UA received previously, regardless of mechanism: statically 227 preloaded, via HTTP header, or some other means (possibly in the TLS 228 layer itself). 230 2.5. Interactions With Preloaded Pin Lists 232 UAs MAY choose to implement built-in public key pins, alongside any 233 built-in HSTS opt-in list. UAs MUST allow users to override a 234 built-in pin list, including turning it off. 236 UAs MUST use the newest information -- built-in or set via Valid 237 Pinning Header -- when performing Pin Validation for the host. 239 2.6. Pinning Self-Signed End Entities 241 If UAs accept hosts that authenticate themselves with self-signed end 242 entity certificates, they MAY also allow hosts to pin the public keys 243 in such certificates. The usability and security implications of 244 this practice are outside the scope of this specification. 246 3. Security Considerations 248 Pinning public keys helps hosts assert their cryptographic identity, 249 but there is some risk that a host operator could lose or lose 250 control of their host's private key. In this case, the operator 251 would not be able to serve their web site or application in a way 252 that UAs would trust for the duration of their pin's max-age. 253 (Recall that UAs MUST close the connection to a host upon Pin 254 Failure.) 256 3.1. Backup Pins 258 The primary way to cope with the risk of inadvertant Pin Failure is 259 to keep a Backup Pin. A Backup Pin is a fingerprint for the public 260 key of a secondary, not-yet-deployed key pair. The operator keeps 261 the backup key pair offline, and sets a pin for it in the Public-Key- 262 Pins header. Then, in case the operator loses control of their 263 primary private key, they can deploy the backup key pair. UAs, who 264 have had the backup key pair pinned (when it was set in previous 265 Valid Pinning Headers), can connect to the host without error. 267 Because having a backup key pair is so important to recovery, UAs 268 MUST require that hosts set a Backup Pin. (See Section 2.3.) 270 4. Usability Considerations 272 When pinning works to detect impostor Pinned Hosts, users will 273 experience denial of service. UAs MUST explain the reason why, i.e. 274 that it was impossible to verify the confirmed cryptographic identity 275 of the host. 277 UAs MUST have a way for users to clear current pins for Pinned Hosts. 278 UAs SHOULD have a way for users to query the current state of Pinned 279 Hosts. 281 5. Acknowledgements 283 Thanks to Jeff Hodges, Adam Langley, Nicolas Lidzborski, SM, and Yoav 284 Nir for suggestions and edits that clarified the text. Thanks to 285 Trevor Perrin for suggesting a mechanism to affirmatively break pins 286 ([pin-break-codes]). Adam Langley provided the SPKI fingerprint 287 generation code. 289 6. What's Changed 291 Removed the section on pin break codes and verifiers, in favor the of 292 most-recently-received policy (Section 2.3). 294 Now using a new header field, Public-Key-Pins, separate from HSTS. 295 This allows hosts to use pinning separately from Strict Transport 296 Security. 298 Explicitly requiring that UAs perform Pin Validation before the HTTP 299 conversation begins. 301 Backup Pins are now required. 303 Separated normative from non-normative material. Removed tangential 304 and out-of-scope non-normative discussion. 306 7. References 308 [hsts-draft] 309 Hodges, J., Jackson, C., and A. Barth, "HTTP Strict 310 Transport Security (HSTS)", October 2011, . 314 [why-pin-key] 315 Langley, A., "Public Key Pinning", May 2011, 316 . 318 [pin-break-codes] 319 Perrin, T., "Self-Asserted Key Pinning", September 2011, 320 . 322 [rfc-2119] 323 Bradner, S., "Key words for use in RFCs to Indicate 324 Requirement Levels", March 1997, 325 . 327 [rfc-2616] 328 Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 329 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 330 Transfer Protocol -- HTTP/1.1", June 1999, 331 . 333 [rfc-4648] 334 Josefsson, S., "The Base16, Base32, and Base64 Data 335 Encodings", October 2006, 336 . 338 [rfc-5246] 339 Rescorla, E. and T. Dierks, "The Transport Layer Security 340 (TLS) Protocol Version 1.2", August 2008, 341 . 343 [rfc-5280] 344 Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 345 Housley, R., and W. Polk, "Internet X.509 Public Key 346 Infrastructure Certificate and Certificate Revocation List 347 (CRL) Profile", May 2008, 348 . 350 Appendix A. Fingerprint Generation 352 This Go program generates public key fingerprints, suitable for use 353 in pinning, from PEM-encoded certificates. It is non-normative. 355 package main 357 import ( 358 "io/ioutil" 359 "os" 360 "crypto/sha1" 361 "crypto/x509" 362 "encoding/base64" 363 "encoding/pem" 364 "fmt" 365 ) 367 func main() { 368 if len(os.Args) < 2 { 369 fmt.Printf("Usage: %s PEM-filename\n", os.Args[0]) 370 os.Exit(1) 371 } 372 pemBytes, err := ioutil.ReadFile(os.Args[1]) 373 if err != nil { 374 panic(err.String()) 375 } 376 block, _ := pem.Decode(pemBytes) 377 if block == nil { 378 panic("No PEM structure found") 379 } 380 derBytes := block.Bytes 381 certs, err := x509.ParseCertificates(derBytes) 382 if err != nil { 383 panic(err.String()) 384 } 385 cert := certs[0] 386 h := sha1.New() 387 h.Write(cert.RawSubjectPublicKeyInfo) 388 digest := h.Sum() 390 fmt.Printf("Hex: %x\nBase64: %s\n", digest, 391 base64.StdEncoding.EncodeToString(digest)) 392 } 394 Figure 4 396 Appendix B. Deployment Guidance 398 This section is non-normative guidance which may smooth the adoption 399 of public key pinning. 401 o Operators SHOULD get the backup public key signed by a different 402 (root and/or intermediary) CA than their primary certificate, and 403 store the backup key pair safely offline. 405 o It is most economical to have the backup certificate signed by a 406 completely different signature chain than the live certificate, to 407 maximize recoverability in the event of either root or 408 intermediary signer compromise. 410 o Operators SHOULD periodically exercise their Backup Pin plan -- an 411 untested backup is no backup at all. 413 o Operators SHOULD start small. Operators SHOULD first deploy 414 public key pinning by setting a max-age of minutes or a few hours, 415 and gradually increase max-age as they gain confidence in their 416 operational capability. 418 Authors' Addresses 420 Chris Evans 421 Google, Inc. 422 1600 Amphitheatre Pkwy 423 Mountain View, CA 94043 424 US 426 Email: cevans@google.com 428 Chris Palmer 429 Google, Inc. 430 1600 Amphitheatre Pkwy 431 Mountain View, CA 94043 432 US 434 Email: palmer@google.com