idnits 2.17.1 draft-ietf-webpush-encryption-04.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (October 9, 2016) is 2756 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'ECDH' -- Possible downref: Non-RFC (?) normative reference: ref. 'FIPS180-4' -- Possible downref: Non-RFC (?) normative reference: ref. 'FIPS186' == Outdated reference: A later version (-09) exists of draft-ietf-httpbis-encryption-encoding-02 == Outdated reference: A later version (-12) exists of draft-ietf-webpush-protocol-10 ** Downref: Normative reference to an Informational RFC: RFC 5869 -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Thomson 3 Internet-Draft Mozilla 4 Intended status: Standards Track October 9, 2016 5 Expires: April 12, 2017 7 Message Encryption for Web Push 8 draft-ietf-webpush-encryption-04 10 Abstract 12 A message encryption scheme is described for the Web Push protocol. 13 This scheme provides confidentiality and integrity for messages sent 14 from an Application Server to a User Agent. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on April 12, 2017. 33 Copyright Notice 35 Copyright (c) 2016 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 52 2. Push Message Encryption Overview . . . . . . . . . . . . . . 3 53 2.1. Key and Secret Distribution . . . . . . . . . . . . . . . 4 54 3. Push Message Encryption . . . . . . . . . . . . . . . . . . . 4 55 3.1. Diffie-Hellman Key Agreement . . . . . . . . . . . . . . 4 56 3.2. Push Message Authentication . . . . . . . . . . . . . . . 5 57 3.3. Combining Shared and Authentication Secrets . . . . . . . 5 58 3.4. Key Derivation Context . . . . . . . . . . . . . . . . . 6 59 3.5. Encryption Summary . . . . . . . . . . . . . . . . . . . 6 60 4. Restrictions on Use of "aesgcm" Content Coding . . . . . . . 7 61 5. Push Message Encryption Example . . . . . . . . . . . . . . . 7 62 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 63 7. Security Considerations . . . . . . . . . . . . . . . . . . . 9 64 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 65 8.1. Normative References . . . . . . . . . . . . . . . . . . 9 66 8.2. Informative References . . . . . . . . . . . . . . . . . 10 67 Appendix A. Intermediate Values for Encryption . . . . . . . . . 10 68 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 70 1. Introduction 72 The Web Push protocol [I-D.ietf-webpush-protocol] is an intermediated 73 protocol by necessity. Messages from an Application Server are 74 delivered to a User Agent via a Push Service. 76 +-------+ +--------------+ +-------------+ 77 | UA | | Push Service | | Application | 78 +-------+ +--------------+ +-------------+ 79 | | | 80 | Setup | | 81 |<====================>| | 82 | Provide Subscription | 83 |-------------------------------------------->| 84 | | | 85 : : : 86 | | Push Message | 87 | Push Message |<---------------------| 88 |<---------------------| | 89 | | | 91 This document describes how messages sent using this protocol can be 92 secured against inspection, modification and falsification by a Push 93 Service. 95 Web Push messages are the payload of an HTTP message [RFC7230]. 96 These messages are encrypted using an encrypted content encoding 97 [I-D.ietf-httpbis-encryption-encoding]. This document describes how 98 this content encoding is applied and describes a recommended key 99 management scheme. 101 For efficiency reasons, multiple users of Web Push often share a 102 central agent that aggregates push functionality. This agent can 103 enforce the use of this encryption scheme by applications that use 104 push messaging. An agent that only delivers messages that are 105 properly encrypted strongly encourages the end-to-end protection of 106 messages. 108 A web browser that implements the Web Push API [API] can enforce the 109 use of encryption by forwarding only those messages that were 110 properly encrypted. 112 1.1. Notational Conventions 114 The words "MUST", "MUST NOT", "SHOULD", and "MAY" are used in this 115 document. It's not shouting, when they are capitalized, they have 116 the special meaning described in [RFC2119]. 118 2. Push Message Encryption Overview 120 Encrypting a push message uses elliptic-curve Diffie-Hellman (ECDH) 121 [ECDH] on the P-256 curve [FIPS186] to establish a shared secret (see 122 Section 3.1) and a symmetric secret for authentication (see 123 Section 3.2). 125 A User Agent generates an ECDH key pair and authentication secret 126 that it associates with each subscription it creates. The ECDH 127 public key and the authentication secret are sent to the Application 128 Server with other details of the push subscription. 130 When sending a message, an Application Server generates an ECDH key 131 pair and a random salt. The ECDH public key is encoded into the "dh" 132 parameter of the Crypto-Key header field; the salt is encoded into 133 the "salt" parameter of the Encryption header field. The ECDH key 134 pair can be discarded after encrypting the message. 136 The content of the push message is encrypted or decrypted using a 137 content encryption key and nonce that is derived using all of these 138 inputs and the process described in Section 3. 140 2.1. Key and Secret Distribution 142 The application using the subscription distributes the subscription 143 public key and authentication secret to an authorized Application 144 Server. This could be sent along with other subscription information 145 that is provided by the User Agent, such as the push subscription 146 URI. 148 An application MUST use an authenticated, confidentiality protected 149 communications medium for this purpose. In addition to the reasons 150 described in [I-D.ietf-webpush-protocol], this ensures that the 151 authentication secret is not revealed to unauthorized entities, which 152 can be used to generate push messages that will be accepted by the 153 User Agent. 155 Most applications that use push messaging have a pre-existing 156 relationship with an Application Server. Any existing communication 157 mechanism that is authenticated and provides confidentiality and 158 integrity, such as HTTPS [RFC2818], is sufficient. 160 3. Push Message Encryption 162 Push message encryption happens in four phases: 164 o The input keying material used for deriving the content encryption 165 keys used for the push message is derived using elliptic-curve 166 Diffie-Hellman [ECDH] (Section 3.1). 168 o This is then combined with the application secret to produce the 169 input keying material used in 170 [I-D.ietf-httpbis-encryption-encoding] (Section 3.3). 172 o A content encryption key and nonce are derived using the process 173 in [I-D.ietf-httpbis-encryption-encoding] with an expanded context 174 string (Section 3.4). 176 o Encryption or decryption follows according to 177 [I-D.ietf-httpbis-encryption-encoding]. 179 The key derivation process is summarized in Section 3.5. 180 Restrictions on the use of the encrypted content coding are described 181 in Section 4. 183 3.1. Diffie-Hellman Key Agreement 185 For each new subscription that the User Agent generates for an 186 Application, it also generates a P-256 [FIPS186] key pair for use in 187 elliptic-curve Diffie-Hellman (ECDH) [ECDH]. 189 When sending a push message, the Application Server also generates a 190 new ECDH key pair on the same P-256 curve. 192 The ECDH public key for the Application Server is included in the 193 "dh" parameter of the Crypto-Key header field (see Section 6). The 194 uncompressed point form defined in [X9.62] (that is, a 65 octet 195 sequence that starts with a 0x04 octet) is encoded using base64url 196 [RFC7515] to produce the "dh" parameter value. 198 An Application combines its ECDH private key with the public key 199 provided by the User Agent using the process described in [ECDH]; on 200 receipt of the push message, a User Agent combines its private key 201 with the public key provided by the Application Server in the "dh" 202 parameter in the same way. These operations produce the same value 203 for the ECDH shared secret. 205 3.2. Push Message Authentication 207 To ensure that push messages are correctly authenticated, a symmetric 208 authentication secret is added to the information generated by a User 209 Agent. The authentication secret is mixed into the key derivation 210 process described in [I-D.ietf-httpbis-encryption-encoding]. 212 A User Agent MUST generate and provide a hard to guess sequence of 16 213 octets that is used for authentication of push messages. This SHOULD 214 be generated by a cryptographically strong random number generator 215 [RFC4086]. 217 3.3. Combining Shared and Authentication Secrets 219 The shared secret produced by ECDH is combined with the 220 authentication secret using HMAC-based key derivation function (HKDF) 221 described in [RFC5869]. This produces the input keying material used 222 by [I-D.ietf-httpbis-encryption-encoding]. 224 The HKDF function uses SHA-256 hash algorithm [FIPS180-4] with the 225 following inputs: 227 salt: the authentication secret 229 IKM: the shared secret derived using ECDH 231 info: the ASCII-encoded string "Content-Encoding: auth" with a 232 terminal zero octet 234 L: 32 octets (i.e., the output is the length of the underlying 235 SHA-256 HMAC function output) 237 3.4. Key Derivation Context 239 The derivation of the content encryption key and nonce uses an 240 additional context string. 242 The context is comprised of a label of "P-256" encoded in ASCII (that 243 is, the octet sequence 0x50, 0x2d, 0x32, 0x35, 0x36), a zero-valued 244 octet, the length of the User Agent public key (65 octets) encoded as 245 a two octet unsigned integer in network byte order, the User Agent 246 public key, the length of the Application Server public key (65 247 octets), and the Application Server public key. 249 context = label || 0x00 || 250 length(ua_public) || ua_public || 251 length(as_public) || as_public 253 3.5. Encryption Summary 255 This results in a the final content encryption key and nonce 256 generation using the following sequence, which is shown here in 257 pseudocode with HKDF expanded into separate discrete steps using HMAC 258 with SHA-256: 260 -- For a User Agent: 261 ecdh_secret = ECDH(ua_private, as_public) 262 auth_secret = random(16) 264 -- For an Application Server: 265 ecdh_secret = ECDH(as_private, ua_public) 266 auth_secret = 268 -- For both: 269 auth_info = "Content-Encoding: auth" || 0x00 270 PRK_combine = HMAC-SHA-256(auth_secret, ecdh_secret) 271 IKM = HMAC-SHA-256(PRK_combine, auth_info || 0x01) 272 context = "P-256" || 0x00 || 273 0x00 || 0x41 || ua_public || 274 0x00 || 0x41 || as_public 275 salt = random(16) 276 PRK = HMAC-SHA-256(salt, IKM) 277 cek_info = "Content-Encoding: aesgcm" || 0x00 || context 278 CEK = HMAC-SHA-256(PRK, cek_info || 0x01)[0..15] 279 nonce_info = "Content-Encoding: nonce" || 0x00 || context 280 NONCE = HMAC-SHA-256(PRK, nonce_info || 0x01)[0..11] 282 Note that this omits the exclusive OR of the final nonce with the 283 record sequence number, since push messages contain only a single 284 record (see Section 4) and the sequence number of the first record is 285 zero. 287 4. Restrictions on Use of "aesgcm" Content Coding 289 An Application Server MUST encrypt a push message with a single 290 record. This allows for a minimal receiver implementation that 291 handles a single record. If the message is 4096 octets or longer, 292 the "rs" parameter MUST be set to a value that is longer than the 293 encrypted push message length. 295 A push service is not required to support more than 4096 octets of 296 payload body (see Section 7.2 of [I-D.ietf-webpush-protocol]), which 297 equates to 4077 octets of cleartext, so the "rs" parameter can be 298 omitted for messages that fit within this limit. 300 An Application Server MUST NOT use other content encodings for push 301 messages. In particular, content encodings that compress could 302 result in leaking of push message contents. The Content-Encoding 303 header field therefore has exactly one value, which is "aesgcm". 304 Multiple "aesgcm" values are not permitted. 306 An Application Server MUST include exactly one entry in the 307 Encryption field, and at most one entry having a "dh" parameter in 308 the Crypto-Key field. This allows the "keyid" parameter to be 309 omitted from both header fields. 311 An Application Server MUST NOT include an "aesgcm" parameter in the 312 Encryption header field. 314 A User Agent is not required to support multiple records. A User 315 Agent MAY ignore the "rs" parameter. If a record size is size is 316 present, but unchecked, decryption will fail with high probability 317 for all valid cases. Decryption will also succeed if the push 318 message contains a single record from a longer truncated message. 319 Given that an Application Server is prohibited from generating such a 320 message, this is not considered a serious risk. 322 5. Push Message Encryption Example 324 The following example shows a push message being sent to a push 325 service. 327 POST /push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV HTTP/1.1 328 Host: push.example.net 329 TTL: 10 330 Content-Length: 33 331 Content-Encoding: aesgcm 332 Encryption: salt="lngarbyKfMoi9Z75xYXmkg" 333 Crypto-Key: dh="BNoRDbb84JGm8g5Z5CFxurSqsXWJ11ItfXEWYVLE85Y7 334 CYkDjXsIEc4aqxYaQ1G8BqkXCJ6DPpDrWtdWj_mugHU" 336 6nqAQUME8hNqw5J3kl8cpVVJylXKYqZOeseZG8UueKpA 338 This example shows the ASCII encoded string, "I am the walrus". The 339 content body is shown here encoded in URL-safe base64url for 340 presentation reasons only. Line wrapping of the "dh" parameter is 341 added for presentation purposes. 343 Since there is no ambiguity about which keys are being used, the 344 "keyid" parameter is omitted from both the Encryption and Crypto-Key 345 header fields. The keys shown below use uncompressed points [X9.62] 346 encoded using base64url. 348 Authentication Secret: R29vIGdvbyBnJyBqb29iIQ 349 Receiver: 350 private key: 9FWl15_QUQAWDaD3k3l50ZBZQJ4au27F1V4F0uLSD_M 351 public key: BCEkBjzL8Z3C-oi2Q7oE5t2Np-p7osjGLg93qUP0wvqR 352 T21EEWyf0cQDQcakQMqz4hQKYOQ3il2nNZct4HgAUQU 353 Sender: 354 private key: nCScek-QpEjmOOlT-rQ38nZzvdPlqa00Zy0i6m2OJvY 355 public key: 357 The sender's private key used in this example is "nCScek-QpEjmOOlT- 358 rQ38nZzvdPlqa00Zy0i6m2OJvY". Intermediate values for this example 359 are included in Appendix A. 361 6. IANA Considerations 363 This document defines the "dh" parameter for the Crypto-Key header 364 field in the "Hypertext Transfer Protocol (HTTP) Crypto-Key 365 Parameters" registry defined in 366 [I-D.ietf-httpbis-encryption-encoding]. 368 o Parameter Name: dh 370 o Purpose: The "dh" parameter contains a Diffie-Hellman share which 371 is used to derive the input keying material used in "aesgcm" 372 content coding. 374 o Reference: this document. 376 7. Security Considerations 378 The security considerations of [I-D.ietf-httpbis-encryption-encoding] 379 describe the limitations of the content encoding. In particular, any 380 HTTP header fields are not protected by the content encoding scheme. 381 A User Agent MUST consider HTTP header fields to have come from the 382 Push Service. An application on the User Agent that uses information 383 from header fields to alter their processing of a push message is 384 exposed to a risk of attack by the Push Service. 386 The timing and length of communication cannot be hidden from the Push 387 Service. While an outside observer might see individual messages 388 intermixed with each other, the Push Service will see what 389 Application Server is talking to which User Agent, and the 390 subscription that is used. Additionally, the length of messages 391 could be revealed unless the padding provided by the content encoding 392 scheme is used to obscure length. 394 8. References 396 8.1. Normative References 398 [ECDH] SECG, "Elliptic Curve Cryptography", SEC 1 , 2000, 399 . 401 [FIPS180-4] 402 Department of Commerce, National., "NIST FIPS 180-4, 403 Secure Hash Standard", March 2012, 404 . 407 [FIPS186] National Institute of Standards and Technology (NIST), 408 "Digital Signature Standard (DSS)", NIST PUB 186-4 , July 409 2013. 411 [I-D.ietf-httpbis-encryption-encoding] 412 Thomson, M., "Encrypted Content-Encoding for HTTP", draft- 413 ietf-httpbis-encryption-encoding-02 (work in progress), 414 June 2016. 416 [I-D.ietf-webpush-protocol] 417 Thomson, M., Damaggio, E., and B. Raymor, "Generic Event 418 Delivery Using HTTP Push", draft-ietf-webpush-protocol-10 419 (work in progress), September 2016. 421 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 422 Requirement Levels", BCP 14, RFC 2119, 423 DOI 10.17487/RFC2119, March 1997, 424 . 426 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 427 "Randomness Requirements for Security", BCP 106, RFC 4086, 428 DOI 10.17487/RFC4086, June 2005, 429 . 431 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 432 Key Derivation Function (HKDF)", RFC 5869, 433 DOI 10.17487/RFC5869, May 2010, 434 . 436 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 437 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 438 2015, . 440 [X9.62] ANSI, "Public Key Cryptography For The Financial Services 441 Industry: The Elliptic Curve Digital Signature Algorithm 442 (ECDSA)", ANSI X9.62 , 1998. 444 8.2. Informative References 446 [API] van Ouwerkerk, M. and M. Thomson, "Web Push API", 2015, 447 . 449 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 450 DOI 10.17487/RFC2818, May 2000, 451 . 453 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 454 Protocol (HTTP/1.1): Message Syntax and Routing", 455 RFC 7230, DOI 10.17487/RFC7230, June 2014, 456 . 458 Appendix A. Intermediate Values for Encryption 460 The intermediate values calculated for the example in Section 5 are 461 shown here. The following are inputs to the calculation: 463 Plaintext: SSBhbSB0aGUgd2FscnVz 465 Application Server public key (as_public): 466 BNoRDbb84JGm8g5Z5CFxurSqsXWJ11ItfXEWYVLE85Y7 467 CYkDjXsIEc4aqxYaQ1G8BqkXCJ6DPpDrWtdWj_mugHU 469 Application Server private key (as_private): nCScek-QpEjmOOlT-rQ38nZ 470 zvdPlqa00Zy0i6m2OJvY 472 User Agent public key (ua_public): BCEkBjzL8Z3C-oi2Q7oE5t2Np- 473 p7osjGLg93qUP0wvqR T21EEWyf0cQDQcakQMqz4hQKYOQ3il2nNZct4HgAUQU 475 User Agent private key (ua_private): 476 9FWl15_QUQAWDaD3k3l50ZBZQJ4au27F1V4F0uLSD_M 478 Salt: lngarbyKfMoi9Z75xYXmkg 480 Authentication secret (auth_secret): R29vIGdvbyBnJyBqb29iIQ 482 Note that knowledge of just one of the private keys is necessary. 483 The Application Server randomly generates the salt value, whereas 484 salt is input to the receiver. 486 This produces the following intermediate values: 488 Shared secret (ecdh_secret): RNjC- 489 NVW4BGJbxWPW7G2mowsLeDa53LYKYm4-NOQ6Y 491 Input keying material (IKM): EhpZec37Ptm4IRD5-jtZ0q6r1iK5vYmY1tZwtN8 492 fbZY 494 Context for content encryption key derivation: 495 Q29udGVudC1FbmNvZGluZzogYWVzZ2NtAFAtMjU2AABB BCEkBjzL8Z3C- 496 oi2Q7oE5t2Np-p7osjGLg93qUP0wvqR 497 T21EEWyf0cQDQcakQMqz4hQKYOQ3il2nNZct4HgAUQUA 498 QQTaEQ22_OCRpvIOWeQhcbq0qrF1iddSLX1xFmFSxPOW 499 OwmJA417CBHOGqsWGkNRvAapFwiegz6Q61rXVo_5roB1 501 Content encryption key (CEK): AN2-xhvFWeYh5z0fcDu0Ww 503 Context for nonce derivation: Q29udGVudC1FbmNvZGluZzogbm9uY2UAUC0yNT 504 YAAEEE ISQGPMvxncL6iLZDugTm3Y2n6nuiyMYuD3epQ_TC-pFP 505 bUQRbJ_RxANBxqRAyrPiFApg5DeKXac1ly3geABRBQBB 506 BNoRDbb84JGm8g5Z5CFxurSqsXWJ11ItfXEWYVLE85Y7 507 CYkDjXsIEc4aqxYaQ1G8BqkXCJ6DPpDrWtdWj_mugHU 509 Base nonce: JY1Okw5rw1Drkg9J 511 When the CEK and nonce are used with AES GCM and the padded plaintext 512 of AABJIGFtIHRoZSB3YWxydXM, the final ciphertext is 513 6nqAQUME8hNqw5J3kl8cpVVJylXKYqZOeseZG8UueKpA, as shown in the 514 example. 516 Author's Address 518 Martin Thomson 519 Mozilla 521 Email: martin.thomson@gmail.com