idnits 2.17.1 draft-ietf-websec-key-pinning-01.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 issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (December 9, 2011) is 4521 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 395 looks like a reference -- Missing reference section? '1' on line 382 looks like a reference Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 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 Intended status: Standards Track Google, Inc. 5 Expires: June 11, 2012 December 9, 2011 7 Public Key Pinning Extension for HTTP 8 draft-ietf-websec-key-pinning-01 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 11, 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. Requirements Language 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 [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 pin-sha1="4n972HfV354KP560yw4uqe/baXc="; 120 pin-sha1="IvGeLsbqzPxdI0b0wuj2xVTdXgc=" 122 Public-Key-Pins: max-age=31536000; 123 pin-sha1="4n972HfV354KP560yw4uqe/baXc="; 124 pin-sha256="LPJNul+wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ=" 126 Public-Key-Pins: pin-sha1="4n972HfV354KP560yw4uqe/baXc="; 127 pin-sha1="qvTGHdzF6KLavt4PO0gs2a6pQ00="; 128 pin-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. 173 The UAs MUST ignore Public-Key-Pins response header fields 174 received on HTTP (non-HTTPS) connections. 176 o The UA MUST note the pins if and only if the TLS connection was 177 authenticated with a certificate chain containing at least one of 178 the SPKI structures indicated by at least one of the given 179 fingerprints. (See Section 2.4.) 181 o The UA MUST note the pins if and only if the given set of pins 182 contains at least one pin that does NOT refer to an SPKI in the 183 certificate chain. (That is, the host must set a Backup Pin; see 184 Section 3.1.) 186 If the Public-Key-Pins response header field does not meet all four 187 of these criteria, the UA MUST NOT note the host as a Pinned Host, 188 and MUST discard any previously set Pinning Metadata for that host in 189 its non-volatile store. Public-Key-Pins response header fields that 190 meet all these critera are known as Valid Pinning Headers. 192 Whenever a UA receives a Valid Pinning Header, it MUST set its 193 Pinning Metadata to the exact pins and max-age given in the most 194 recently received Valid Pinning Header. 196 2.3.1. max-age 198 max-age specifies the number of seconds, after the reception of the 199 Public-Key-Pins HTTP Response Header, during which the UA regards the 200 host as a Pinned Host. The delta-seconds production is specified in 201 [rfc-2616]. 203 Note that by setting a low or 0 value for max-age, hosts effectively 204 instruct UAs to cease regarding them as Pinned Hosts. 206 2.4. Validating Pinned Connections 208 When a UA connects to a Pinned Host, if the TLS connection has 209 errors, the UA MUST terminate the connection without allowing the 210 user to proceed anyway. (This behavior is the same as that required 211 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 validated certificate chain. (The UA 217 ignores superfluous certificates in the chain that do not form part 218 of the validating chain.) The UA will then check that the set of 219 these fingerprints intersects the set of fingerprints in that host's 220 Pinning Metadata. If there is set intersection, the UA continues 221 with the connection as normal. Otherwise, the UA MUST treat this Pin 222 Failure as a non-recoverable error. 224 Note that, although the UA has previously received public key pins at 225 the HTTP layer, it can and MUST perform Pin Validation at the TLS 226 layer, before beginning an HTTP conversation over the TLS channel. 227 The TLS layer thus evaluates TLS connections with pinning information 228 the UA received previously, regardless of mechanism: statically 229 preloaded, via HTTP header, or some other means (possibly in the TLS 230 layer itself). 232 2.5. Interactions With Preloaded Pin Lists 234 UAs MAY choose to implement built-in public key pins, alongside any 235 built-in HSTS opt-in list. UAs MUST allow users to override a 236 built-in pin list, including turning it off. 238 UAs MUST use the newest information -- built-in or set via Valid 239 Pinning Header -- when performing Pin Validation for the host. 241 2.6. Pinning Self-Signed End Entities 243 If UAs accept hosts that authenticate themselves with self-signed end 244 entity certificates, they MAY also allow hosts to pin the public keys 245 in such certificates. The usability and security implications of 246 this practice are outside the scope of this specification. 248 3. Security Considerations 250 Pinning public keys helps hosts assert their cryptographic identity, 251 but there is some risk that a host operator could lose or lose 252 control of their host's private key. In this case, the operator 253 would not be able to serve their web site or application in a way 254 that UAs would trust for the duration of their pin's max-age. 255 (Recall that UAs MUST close the connection to a host upon Pin 256 Failure.) 258 3.1. Backup Pins 260 The primary way to cope with the risk of inadvertant Pin Failure is 261 to keep a Backup Pin. A Backup Pin is a fingerprint for the public 262 key of a secondary, not-yet-deployed key pair. The operator keeps 263 the backup key pair offline, and sets a pin for it in the Public-Key- 264 Pins header. Then, in case the operator loses control of their 265 primary private key, they can deploy the backup key pair. UAs, who 266 have had the backup key pair pinned (when it was set in previous 267 Valid Pinning Headers), can connect to the host without error. 269 Because having a backup key pair is so important to recovery, UAs 270 MUST require that hosts set a Backup Pin. (See Section 2.3.) 272 4. IANA Considerations 274 This document has no actions for IANA. 276 5. Usability Considerations 278 When pinning works to detect impostor Pinned Hosts, users will 279 experience denial of service. UAs MUST explain the reason why, i.e. 280 that it was impossible to verify the confirmed cryptographic identity 281 of the host. 283 UAs MUST have a way for users to clear current pins for Pinned Hosts. 284 UAs SHOULD have a way for users to query the current state of Pinned 285 Hosts. 287 6. Acknowledgements 289 Thanks to Tobias Gondrom, Jeff Hodges, Adam Langley, Nicolas 290 Lidzborski, SM, James Manger, and Yoav Nir for suggestions and edits 291 that clarified the text. Thanks to Trevor Perrin for suggesting a 292 mechanism to affirmatively break pins ([pin-break-codes]). Adam 293 Langley provided the SPKI fingerprint generation code. 295 7. What's Changed 297 Removed the section on pin break codes and verifiers, in favor the of 298 most-recently-received policy (Section 2.3). 300 Now using a new header field, Public-Key-Pins, separate from HSTS. 301 This allows hosts to use pinning separately from Strict Transport 302 Security. 304 Explicitly requiring that UAs perform Pin Validation before the HTTP 305 conversation begins. 307 Backup Pins are now required. 309 Separated normative from non-normative material. Removed tangential 310 and out-of-scope non-normative discussion. 312 8. References 314 8.1. Normative References 316 [hsts-draft] 317 Hodges, J., Jackson, C., and A. Barth, "HTTP Strict 318 Transport Security (HSTS)", October 2011, . 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 8.2. Informative References 352 [why-pin-key] 353 Langley, A., "Public Key Pinning", May 2011, 354 . 356 [pin-break-codes] 357 Perrin, T., "Self-Asserted Key Pinning", September 2011, 358 . 360 Appendix A. Fingerprint Generation 362 This Go program generates public key fingerprints, suitable for use 363 in pinning, from PEM-encoded certificates. It is non-normative. 365 package main 367 import ( 368 "io/ioutil" 369 "os" 370 "crypto/sha1" 371 "crypto/x509" 372 "encoding/base64" 373 "encoding/pem" 374 "fmt" 375 ) 377 func main() { 378 if len(os.Args) < 2 { 379 fmt.Printf("Usage: %s PEM-filename\n", os.Args[0]) 380 os.Exit(1) 381 } 382 pemBytes, err := ioutil.ReadFile(os.Args[1]) 383 if err != nil { 384 panic(err.String()) 385 } 386 block, _ := pem.Decode(pemBytes) 387 if block == nil { 388 panic("No PEM structure found") 389 } 390 derBytes := block.Bytes 391 certs, err := x509.ParseCertificates(derBytes) 392 if err != nil { 393 panic(err.String()) 394 } 395 cert := certs[0] 396 h := sha1.New() 397 h.Write(cert.RawSubjectPublicKeyInfo) 398 digest := h.Sum() 400 fmt.Printf("Hex: %x\nBase64: %s\n", digest, 401 base64.StdEncoding.EncodeToString(digest)) 402 } 404 Figure 4 406 Appendix B. Deployment Guidance 408 This section is non-normative guidance which may smooth the adoption 409 of public key pinning. 411 o Operators SHOULD get the backup public key signed by a different 412 (root and/or intermediary) CA than their primary certificate, and 413 store the backup key pair safely offline. 415 o It is most economical to have the backup certificate signed by a 416 completely different signature chain than the live certificate, to 417 maximize recoverability in the event of either root or 418 intermediary signer compromise. 420 o Operators SHOULD periodically exercise their Backup Pin plan -- an 421 untested backup is no backup at all. 423 o Operators SHOULD start small. Operators SHOULD first deploy 424 public key pinning by setting a max-age of minutes or a few hours, 425 and gradually increase max-age as they gain confidence in their 426 operational capability. 428 Authors' Addresses 430 Chris Evans 431 Google, Inc. 432 1600 Amphitheatre Pkwy 433 Mountain View, CA 94043 434 US 436 Email: cevans@google.com 438 Chris Palmer 439 Google, Inc. 440 1600 Amphitheatre Pkwy 441 Mountain View, CA 94043 442 US 444 Email: palmer@google.com