idnits 2.17.1 draft-ietf-websec-key-pinning-02.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: ---------------------------------------------------------------------------- ** The document is more than 15 pages and seems to lack a Table of Contents. 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 (June 4, 2012) is 4344 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 416 looks like a reference -- Missing reference section? '1' on line 403 looks like a reference Summary: 1 error (**), 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: December 6, 2012 June 4, 2012 7 Public Key Pinning Extension for HTTP 8 draft-ietf-websec-key-pinning-02 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 December 6, 2012. 41 Copyright Notice 43 Copyright (c) 2012 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 embedded 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 three 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 (up to a maximum of 30 days; see Section 2.5). 201 The delta-seconds production is specified in [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 additional correctness check: Pin Validation. To perform Pin 215 Validation, the UA will compute the fingerprints of the SPKI 216 structures in each certificate in the host's validated certificate 217 chain. (For the purposes of Pin Validation, the UA MUST ignore 218 superfluous certificates in the chain that do not form part of the 219 validating chain.) The UA will then check that the set of these 220 fingerprints intersects the set of fingerprints in that host's 221 Pinning Metadata. If there is set intersection, the UA continues 222 with the connection as normal. Otherwise, the UA MUST treat this Pin 223 Failure as a non-recoverable error. 225 Note that, although the UA has previously received public key pins at 226 the HTTP layer, it can and MUST perform Pin Validation at the TLS 227 layer, before beginning an HTTP conversation over the TLS channel. 228 The TLS layer thus evaluates TLS connections with pinning information 229 the UA received previously, regardless of mechanism: statically 230 preloaded, via HTTP header, or some other means (possibly in the TLS 231 layer itself, such as specified in [tack-draft]). 233 2.5. Pin Validity Times 235 In harmony with section 5.3.4 "Create and activate pins" of 236 [tack-draft], clients MUST enforce a maximum age for pins that is no 237 longer than the least of (a) 30 days (30 * 24 * 60 * 60 seconds) 238 after the most recent time that the client noted the pin; (b) the 239 amount of time the pin has been noted; or (c) the most recent time 240 the pin was noted + max-age: 242 active_period_end = MIN(current + current - initial, 243 time_pin_noted + max-age, 244 current + 30 days) 246 Figure 4 248 2.6. Interactions With Preloaded Pin Lists 250 UAs MAY choose to implement built-in public key pins, alongside any 251 built-in HSTS opt-in list. UAs MUST allow users to override a 252 built-in pin list, including turning it off. 254 UAs MUST use the newest information -- built-in or set via Valid 255 Pinning Header -- when performing Pin Validation for the host. 257 2.7. Pinning Self-Signed End Entities 259 If UAs accept hosts that authenticate themselves with self-signed end 260 entity certificates, they MAY also allow hosts to pin the public keys 261 in such certificates. The usability and security implications of 262 this practice are outside the scope of this specification. 264 3. Security Considerations 266 Pinning public keys helps hosts assert their cryptographic identity, 267 but there is some risk that a host operator could lose or lose 268 control of their host's private key. In this case, the operator 269 would not be able to serve their web site or application in a way 270 that UAs would trust for the duration of their pin's max-age. 271 (Recall that UAs MUST close the connection to a host upon Pin 272 Failure.) 274 3.1. Backup Pins 276 The primary way to cope with the risk of inadvertant Pin Failure is 277 to keep a Backup Pin. A Backup Pin is a fingerprint for the public 278 key of a secondary, not-yet-deployed key pair. The operator keeps 279 the backup key pair offline, and sets a pin for it in the Public-Key- 280 Pins header. Then, in case the operator loses control of their 281 primary private key, they can deploy the backup key pair. UAs, who 282 have had the backup key pair pinned (when it was set in previous 283 Valid Pinning Headers), can connect to the host without error. 285 Because having a backup key pair is so important to recovery, UAs 286 MUST require that hosts set a Backup Pin. (See Section 2.3.) 288 4. IANA Considerations 290 This document has no actions for IANA. 292 5. Usability Considerations 294 When pinning works to detect impostor Pinned Hosts, users will 295 experience denial of service. UAs MUST explain the reason why, i.e. 296 that it was impossible to verify the confirmed cryptographic identity 297 of the host. 299 UAs MUST have a way for users to clear current pins for Pinned Hosts. 300 UAs SHOULD have a way for users to query the current state of Pinned 301 Hosts. 303 6. Acknowledgements 305 Thanks to Tobias Gondrom, Jeff Hodges, Adam Langley, Nicolas 306 Lidzborski, SM, James Manger, and Yoav Nir for suggestions and edits 307 that clarified the text. Thanks to Trevor Perrin for suggesting a 308 mechanism to affirmatively break pins ([pin-break-codes]). Adam 309 Langley provided the SPKI fingerprint generation code. 311 7. What's Changed 313 Removed the section on pin break codes and verifiers, in favor the of 314 most-recently-received policy (Section 2.3). 316 Now using a new header field, Public-Key-Pins, separate from HSTS. 317 This allows hosts to use pinning separately from Strict Transport 318 Security. 320 Explicitly requiring that UAs perform Pin Validation before the HTTP 321 conversation begins. 323 Backup Pins are now required. 325 Separated normative from non-normative material. Removed tangential 326 and out-of-scope non-normative discussion. 328 8. References 330 8.1. Normative References 332 [hsts-draft] 333 Hodges, J., Jackson, C., and A. Barth, "HTTP Strict 334 Transport Security (HSTS)", October 2011, . 338 [rfc-2119] 339 Bradner, S., "Key words for use in RFCs to Indicate 340 Requirement Levels", March 1997, 341 . 343 [rfc-2616] 344 Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 345 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 346 Transfer Protocol -- HTTP/1.1", June 1999, 347 . 349 [rfc-4648] 350 Josefsson, S., "The Base16, Base32, and Base64 Data 351 Encodings", October 2006, 352 . 354 [rfc-5246] 355 Rescorla, E. and T. Dierks, "The Transport Layer Security 356 (TLS) Protocol Version 1.2", August 2008, 357 . 359 [rfc-5280] 360 Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 361 Housley, R., and W. Polk, "Internet X.509 Public Key 362 Infrastructure Certificate and Certificate Revocation List 363 (CRL) Profile", May 2008, 364 . 366 8.2. Informative References 368 [why-pin-key] 369 Langley, A., "Public Key Pinning", May 2011, 370 . 372 [pin-break-codes] 373 Perrin, T., "Self-Asserted Key Pinning", September 2011, 374 . 376 [tack-draft] 377 Perrin, T. and M. Marlinspike, "Trust Assertions for 378 Certificate Keys", May 2012, 379 . 381 Appendix A. Fingerprint Generation 383 This Go program generates public key fingerprints, suitable for use 384 in pinning, from PEM-encoded certificates. It is non-normative. 386 package main 388 import ( 389 "io/ioutil" 390 "os" 391 "crypto/sha1" 392 "crypto/x509" 393 "encoding/base64" 394 "encoding/pem" 395 "fmt" 396 ) 398 func main() { 399 if len(os.Args) < 2 { 400 fmt.Printf("Usage: %s PEM-filename\n", os.Args[0]) 401 os.Exit(1) 402 } 403 pemBytes, err := ioutil.ReadFile(os.Args[1]) 404 if err != nil { 405 panic(err.String()) 406 } 407 block, _ := pem.Decode(pemBytes) 408 if block == nil { 409 panic("No PEM structure found") 410 } 411 derBytes := block.Bytes 412 certs, err := x509.ParseCertificates(derBytes) 413 if err != nil { 414 panic(err.String()) 415 } 416 cert := certs[0] 417 h := sha1.New() 418 h.Write(cert.RawSubjectPublicKeyInfo) 419 digest := h.Sum() 421 fmt.Printf("Hex: %x\nBase64: %s\n", digest, 422 base64.StdEncoding.EncodeToString(digest)) 423 } 425 Figure 5 427 Appendix B. Deployment Guidance 429 This section is non-normative guidance which may smooth the adoption 430 of public key pinning. 432 o Operators SHOULD get the backup public key signed by a different 433 (root and/or intermediary) CA than their primary certificate, and 434 store the backup key pair safely offline. 436 o It is most economical to have the backup certificate signed by a 437 completely different signature chain than the live certificate, to 438 maximize recoverability in the event of either root or 439 intermediary signer compromise. 441 o Operators SHOULD periodically exercise their Backup Pin plan -- an 442 untested backup is no backup at all. 444 o Operators SHOULD start small. Operators SHOULD first deploy 445 public key pinning by setting a max-age of minutes or a few hours, 446 and gradually increase max-age as they gain confidence in their 447 operational capability. 449 Authors' Addresses 451 Chris Evans 452 Google, Inc. 453 1600 Amphitheatre Pkwy 454 Mountain View, CA 94043 455 US 457 Email: cevans@google.com 459 Chris Palmer 460 Google, Inc. 461 1600 Amphitheatre Pkwy 462 Mountain View, CA 94043 463 US 465 Email: palmer@google.com