idnits 2.17.1 draft-ietf-websec-key-pinning-03.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 (October 16, 2012) is 4200 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 421 looks like a reference -- Missing reference section? '1' on line 408 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: April 19, 2013 October 16, 2012 7 Public Key Pinning Extension for HTTP 8 draft-ietf-websec-key-pinning-03 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 April 19, 2013. 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 If the SubjectPublicKeyInfo of a certificate is incomplete when taken 154 in isolation, such as when holding a DSA key without domain 155 parameters, a public key pin cannot be formed. 157 We pin public keys, rather than entire certificates, to enable 158 operators to generate new certificates containing old public keys 159 (see [why-pin-key]). 161 See Appendix A for an example non-normative program that generates 162 public key fingerprints from SubjectPublicKeyInfo fields in 163 certificates. 165 2.3. Noting Pins 167 Upon receipt of the Public-Key-Pins response header field, the UA 168 notes the host as a Pinned Host, storing the pins and their 169 associated max-age in non-volatile storage (for example, along with 170 the HSTS metadata). The pins and their associated max-age are 171 collectively known as Pinning Metadata. 173 The UA MUST observe these conditions when noting a host: 175 o The UA MUST note the pins if and only if it received the Public- 176 Key-Pins response header field over an error-free TLS connection. 177 The UAs MUST ignore Public-Key-Pins response header fields 178 received on HTTP (non-HTTPS) connections. 180 o The UA MUST note the pins if and only if the TLS connection was 181 authenticated with a certificate chain containing at least one of 182 the SPKI structures indicated by at least one of the given 183 fingerprints. (See Section 2.4.) 185 o The UA MUST note the pins if and only if the given set of pins 186 contains at least one pin that does NOT refer to an SPKI in the 187 certificate chain. (That is, the host must set a Backup Pin; see 188 Section 3.1.) 190 If the Public-Key-Pins response header field does not meet all three 191 of these criteria, the UA MUST NOT note the host as a Pinned Host, 192 and MUST discard any previously set Pinning Metadata for that host in 193 its non-volatile store. Public-Key-Pins response header fields that 194 meet all these critera are known as Valid Pinning Headers. 196 Whenever a UA receives a Valid Pinning Header, it MUST set its 197 Pinning Metadata to the exact pins and max-age given in the most 198 recently received Valid Pinning Header. 200 2.3.1. max-age 202 max-age specifies the number of seconds, after the reception of the 203 Public-Key-Pins HTTP Response Header, during which the UA regards the 204 host as a Pinned Host (up to a maximum of 30 days; see Section 2.5). 205 The delta-seconds production is specified in [rfc-2616]. 207 Note that by setting a low or 0 value for max-age, hosts effectively 208 instruct UAs to cease regarding them as Pinned Hosts. 210 2.4. Validating Pinned Connections 212 When a UA connects to a Pinned Host, if the TLS connection has 213 errors, the UA MUST terminate the connection without allowing the 214 user to proceed anyway. (This behavior is the same as that required 215 by [hsts-draft].) 217 If the connection has no errors, the UA will then apply a new, 218 additional correctness check: Pin Validation. To perform Pin 219 Validation, the UA will compute the fingerprints of the SPKI 220 structures in each certificate in the host's validated certificate 221 chain. (For the purposes of Pin Validation, the UA MUST ignore 222 certificates who SPKI cannot be taken in isolation and superfluous 223 certificates in the chain that do not form part of the validating 224 chain.) The UA will then check that the set of these fingerprints 225 intersects the set of fingerprints in that host's Pinning Metadata. 226 If there is set intersection, the UA continues with the connection as 227 normal. Otherwise, the UA MUST treat this Pin Failure as a non- 228 recoverable error. 230 Note that, although the UA has previously received public key pins at 231 the HTTP layer, it can and MUST perform Pin Validation at the TLS 232 layer, before beginning an HTTP conversation over the TLS channel. 233 The TLS layer thus evaluates TLS connections with pinning information 234 the UA received previously, regardless of mechanism: statically 235 preloaded, via HTTP header, or some other means (possibly in the TLS 236 layer itself, such as specified in [tack-draft]). 238 2.5. Pin Validity Times 240 In harmony with section 5.3.4 "Create and activate pins" of 241 [tack-draft], clients MUST enforce a maximum age for pins that is no 242 longer than the least of (a) 30 days (30 * 24 * 60 * 60 seconds) 243 after the most recent time that the client noted the pin; (b) the 244 amount of time the pin has been noted; or (c) the most recent time 245 the pin was noted + max-age: 247 active_period_end = MIN(current + current - initial, 248 time_pin_noted + max-age, 249 current + 30 days) 251 Figure 4 253 2.6. Interactions With Preloaded Pin Lists 255 UAs MAY choose to implement built-in public key pins, alongside any 256 built-in HSTS opt-in list. UAs MUST allow users to override a 257 built-in pin list, including turning it off. 259 UAs MUST use the newest information -- built-in or set via Valid 260 Pinning Header -- when performing Pin Validation for the host. 262 2.7. Pinning Self-Signed End Entities 264 If UAs accept hosts that authenticate themselves with self-signed end 265 entity certificates, they MAY also allow hosts to pin the public keys 266 in such certificates. The usability and security implications of 267 this practice are outside the scope of this specification. 269 3. Security Considerations 271 Pinning public keys helps hosts assert their cryptographic identity, 272 but there is some risk that a host operator could lose or lose 273 control of their host's private key. In this case, the operator 274 would not be able to serve their web site or application in a way 275 that UAs would trust for the duration of their pin's max-age. 276 (Recall that UAs MUST close the connection to a host upon Pin 277 Failure.) 279 3.1. Backup Pins 281 The primary way to cope with the risk of inadvertant Pin Failure is 282 to keep a Backup Pin. A Backup Pin is a fingerprint for the public 283 key of a secondary, not-yet-deployed key pair. The operator keeps 284 the backup key pair offline, and sets a pin for it in the Public-Key- 285 Pins header. Then, in case the operator loses control of their 286 primary private key, they can deploy the backup key pair. UAs, who 287 have had the backup key pair pinned (when it was set in previous 288 Valid Pinning Headers), can connect to the host without error. 290 Because having a backup key pair is so important to recovery, UAs 291 MUST require that hosts set a Backup Pin. (See Section 2.3.) 293 4. IANA Considerations 295 This document has no actions for IANA. 297 5. Usability Considerations 299 When pinning works to detect impostor Pinned Hosts, users will 300 experience denial of service. UAs MUST explain the reason why, i.e. 301 that it was impossible to verify the confirmed cryptographic identity 302 of the host. 304 UAs MUST have a way for users to clear current pins for Pinned Hosts. 305 UAs SHOULD have a way for users to query the current state of Pinned 306 Hosts. 308 6. Acknowledgements 310 Thanks to Tobias Gondrom, Jeff Hodges, Adam Langley, Nicolas 311 Lidzborski, SM, James Manger, and Yoav Nir for suggestions and edits 312 that clarified the text. Thanks to Trevor Perrin for suggesting a 313 mechanism to affirmatively break pins ([pin-break-codes]). Adam 314 Langley provided the SPKI fingerprint generation code. 316 7. What's Changed 318 Removed the section on pin break codes and verifiers, in favor the of 319 most-recently-received policy (Section 2.3). 321 Now using a new header field, Public-Key-Pins, separate from HSTS. 322 This allows hosts to use pinning separately from Strict Transport 323 Security. 325 Explicitly requiring that UAs perform Pin Validation before the HTTP 326 conversation begins. 328 Backup Pins are now required. 330 Separated normative from non-normative material. Removed tangential 331 and out-of-scope non-normative discussion. 333 8. References 335 8.1. Normative References 337 [hsts-draft] 338 Hodges, J., Jackson, C., and A. Barth, "HTTP Strict 339 Transport Security (HSTS)", October 2011, . 343 [rfc-2119] 344 Bradner, S., "Key words for use in RFCs to Indicate 345 Requirement Levels", March 1997, 346 . 348 [rfc-2616] 349 Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 350 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 351 Transfer Protocol -- HTTP/1.1", June 1999, 352 . 354 [rfc-4648] 355 Josefsson, S., "The Base16, Base32, and Base64 Data 356 Encodings", October 2006, 357 . 359 [rfc-5246] 360 Rescorla, E. and T. Dierks, "The Transport Layer Security 361 (TLS) Protocol Version 1.2", August 2008, 362 . 364 [rfc-5280] 365 Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 366 Housley, R., and W. Polk, "Internet X.509 Public Key 367 Infrastructure Certificate and Certificate Revocation List 368 (CRL) Profile", May 2008, 369 . 371 8.2. Informative References 373 [why-pin-key] 374 Langley, A., "Public Key Pinning", May 2011, 375 . 377 [pin-break-codes] 378 Perrin, T., "Self-Asserted Key Pinning", September 2011, 379 . 381 [tack-draft] 382 Perrin, T. and M. Marlinspike, "Trust Assertions for 383 Certificate Keys", May 2012, 384 . 386 Appendix A. Fingerprint Generation 388 This Go program generates public key fingerprints, suitable for use 389 in pinning, from PEM-encoded certificates. It is non-normative. 391 package main 393 import ( 394 "io/ioutil" 395 "os" 396 "crypto/sha1" 397 "crypto/x509" 398 "encoding/base64" 399 "encoding/pem" 400 "fmt" 401 ) 403 func main() { 404 if len(os.Args) < 2 { 405 fmt.Printf("Usage: %s PEM-filename\n", os.Args[0]) 406 os.Exit(1) 407 } 408 pemBytes, err := ioutil.ReadFile(os.Args[1]) 409 if err != nil { 410 panic(err.String()) 411 } 412 block, _ := pem.Decode(pemBytes) 413 if block == nil { 414 panic("No PEM structure found") 415 } 416 derBytes := block.Bytes 417 certs, err := x509.ParseCertificates(derBytes) 418 if err != nil { 419 panic(err.String()) 420 } 421 cert := certs[0] 422 h := sha1.New() 423 h.Write(cert.RawSubjectPublicKeyInfo) 424 digest := h.Sum() 426 fmt.Printf("Hex: %x\nBase64: %s\n", digest, 427 base64.StdEncoding.EncodeToString(digest)) 428 } 430 Figure 5 432 Appendix B. Deployment Guidance 434 This section is non-normative guidance which may smooth the adoption 435 of public key pinning. 437 o Operators SHOULD get the backup public key signed by a different 438 (root and/or intermediary) CA than their primary certificate, and 439 store the backup key pair safely offline. 441 o It is most economical to have the backup certificate signed by a 442 completely different signature chain than the live certificate, to 443 maximize recoverability in the event of either root or 444 intermediary signer compromise. 446 o Operators SHOULD periodically exercise their Backup Pin plan -- an 447 untested backup is no backup at all. 449 o Operators SHOULD start small. Operators SHOULD first deploy 450 public key pinning by setting a max-age of minutes or a few hours, 451 and gradually increase max-age as they gain confidence in their 452 operational capability. 454 Authors' Addresses 456 Chris Evans 457 Google, Inc. 458 1600 Amphitheatre Pkwy 459 Mountain View, CA 94043 460 US 462 Email: cevans@google.com 464 Chris Palmer 465 Google, Inc. 466 1600 Amphitheatre Pkwy 467 Mountain View, CA 94043 468 US 470 Email: palmer@google.com