idnits 2.17.1 draft-ietf-webpush-encryption-06.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 31, 2016) is 2727 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-03 ** 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 (~~), 3 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 31, 2016 5 Expires: May 4, 2017 7 Message Encryption for Web Push 8 draft-ietf-webpush-encryption-06 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 May 4, 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 . . . . . . . . . . . . . . . 3 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. Encryption Summary . . . . . . . . . . . . . . . . . . . 6 59 4. Restrictions on Use of "aes128gcm" Content Coding . . . . . . 6 60 5. Push Message Encryption Example . . . . . . . . . . . . . . . 7 61 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 62 7. Security Considerations . . . . . . . . . . . . . . . . . . . 8 63 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 64 8.1. Normative References . . . . . . . . . . . . . . . . . . 9 65 8.2. Informative References . . . . . . . . . . . . . . . . . 10 66 Appendix A. Intermediate Values for Encryption . . . . . . . . . 10 67 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 69 1. Introduction 71 The Web Push protocol [I-D.ietf-webpush-protocol] is an intermediated 72 protocol by necessity. Messages from an Application Server are 73 delivered to a User Agent via a Push Service. 75 +-------+ +--------------+ +-------------+ 76 | UA | | Push Service | | Application | 77 +-------+ +--------------+ +-------------+ 78 | | | 79 | Setup | | 80 |<====================>| | 81 | Provide Subscription | 82 |-------------------------------------------->| 83 | | | 84 : : : 85 | | Push Message | 86 | Push Message |<---------------------| 87 |<---------------------| | 88 | | | 90 This document describes how messages sent using this protocol can be 91 secured against inspection, modification and falsification by a Push 92 Service. 94 Web Push messages are the payload of an HTTP message [RFC7230]. 95 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 message payload. The ECDH key pair can be discarded after encrypting 134 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 A shared secret is derived using elliptic-curve Diffie-Hellman 165 [ECDH] (Section 3.1). 167 o The shared secret is then combined with the application secret to 168 produce the input keying material used in 169 [I-D.ietf-httpbis-encryption-encoding] (Section 3.3). 171 o A content encryption key and nonce are derived using the process 172 in [I-D.ietf-httpbis-encryption-encoding]. 174 o Encryption or decryption follows according to 175 [I-D.ietf-httpbis-encryption-encoding]. 177 The key derivation process is summarized in Section 3.4. 178 Restrictions on the use of the encrypted content coding are described 179 in Section 4. 181 3.1. Diffie-Hellman Key Agreement 183 For each new subscription that the User Agent generates for an 184 Application, it also generates a P-256 [FIPS186] key pair for use in 185 elliptic-curve Diffie-Hellman (ECDH) [ECDH]. 187 When sending a push message, the Application Server also generates a 188 new ECDH key pair on the same P-256 curve. 190 The ECDH public key for the Application Server is included in the 191 "dh" parameter of the Crypto-Key header field (see Section 6). The 192 uncompressed point form defined in [X9.62] (that is, a 65 octet 193 sequence that starts with a 0x04 octet) is encoded using base64url 194 [RFC7515] to produce the "dh" parameter value. 196 An Application combines its ECDH private key with the public key 197 provided by the User Agent using the process described in [ECDH]; on 198 receipt of the push message, a User Agent combines its private key 199 with the public key provided by the Application Server in the "dh" 200 parameter in the same way. These operations produce the same value 201 for the ECDH shared secret. 203 3.2. Push Message Authentication 205 To ensure that push messages are correctly authenticated, a symmetric 206 authentication secret is added to the information generated by a User 207 Agent. The authentication secret is mixed into the key derivation 208 process shown in Section 3.3. 210 A User Agent MUST generate and provide a hard to guess sequence of 16 211 octets that is used for authentication of push messages. This SHOULD 212 be generated by a cryptographically strong random number generator 213 [RFC4086]. 215 3.3. Combining Shared and Authentication Secrets 217 The shared secret produced by ECDH is combined with the 218 authentication secret using HMAC-based key derivation function (HKDF) 219 described in [RFC5869]. This produces the input keying material used 220 by [I-D.ietf-httpbis-encryption-encoding]. 222 The HKDF function uses SHA-256 hash algorithm [FIPS180-4] with the 223 following inputs: 225 salt: the authentication secret 227 IKM: the shared secret derived using ECDH 229 info: the concatenation of the ASCII-encoded string "WebPush: info", 230 a zero octet, the X9.62 encoding of the User Agent ECDH public 231 key, and X9.62 encoding of the Application Server ECDH public key; 232 that is 234 key_info = "WebPush: info" || 0x00 || ua_public || as_public 236 L: 32 octets (i.e., the output is the length of the underlying 237 SHA-256 HMAC function output) 239 3.4. Encryption Summary 241 This results in a the final content encryption key and nonce 242 generation using the following sequence, which is shown here in 243 pseudocode with HKDF expanded into separate discrete steps using HMAC 244 with SHA-256: 246 -- For a User Agent: 247 ecdh_secret = ECDH(ua_private, as_public) 248 auth_secret = random(16) 250 -- For an Application Server: 251 ecdh_secret = ECDH(as_private, ua_public) 252 auth_secret = 254 -- For both: 255 PRK_key = HMAC-SHA-256(auth_secret, ecdh_secret) 256 key_info = "WebPush: info" || 0x00 || ua_public || as_public 257 IKM = HMAC-SHA-256(PRK_cek, key_info || 0x01) 259 salt = random(16) 260 PRK = HMAC-SHA-256(salt, IKM) 261 cek_info = "Content-Encoding: aes128gcm" || 0x00 262 CEK = HMAC-SHA-256(PRK, cek_info || 0x01)[0..15] 263 nonce_info = "Content-Encoding: nonce" || 0x00 264 NONCE = HMAC-SHA-256(PRK, nonce_info || 0x01)[0..11] 266 Note that this omits the exclusive OR of the final nonce with the 267 record sequence number, since push messages contain only a single 268 record (see Section 4) and the sequence number of the first record is 269 zero. 271 4. Restrictions on Use of "aes128gcm" Content Coding 273 An Application Server MUST encrypt a push message with a single 274 record. This allows for a minimal receiver implementation that 275 handles a single record. An application server MUST set the "rs" 276 parameter in the "aes128gcm" content coding header to a size that is 277 greater than the length of the plaintext, plus any padding (which is 278 at least 2 octets). 280 A push message MUST include a zero length "keyid" parameter in the 281 content coding header. 283 A push service is not required to support more than 4096 octets of 284 payload body (see Section 7.2 of [I-D.ietf-webpush-protocol]), which 285 equates to at most 4057 octets of plaintext. 287 An Application Server MUST NOT use other content encodings for push 288 messages. In particular, content encodings that compress could 289 result in leaking of push message contents. The Content-Encoding 290 header field therefore has exactly one value, which is "aes128gcm". 291 Multiple "aes128gcm" values are not permitted. 293 An Application Server MUST include exactly one "aes128gcm" content 294 coding, and at most one entry having a "dh" parameter in the Crypto- 295 Key field. This allows the "keyid" parameter to be omitted. 297 An Application Server MUST NOT include an "aes128gcm" parameter in 298 the Crypto-Key header field. 300 A User Agent is not required to support multiple records. A User 301 Agent MAY ignore the "rs" field and assume that the "keyid" field is 302 empty. If a record size is unchecked, decryption will fail with high 303 probability for all valid cases. However, decryption will also 304 succeed if the push message contains a single record from a longer 305 truncated message. Given that an Application Server is prohibited 306 from generating such a message, this is not considered a serious 307 risk. 309 5. Push Message Encryption Example 311 The following example shows a push message being sent to a push 312 service. 314 POST /push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV HTTP/1.1 315 Host: push.example.net 316 TTL: 10 317 Content-Length: 33 318 Content-Encoding: aes128gcm 319 Crypto-Key: dh=BP4z9KsN6nGRTbVYI_c7VJSPQTBtkgcy27mlmlMoZIIg 320 Dll6e3vCYLocInmYWAmS6TlzAC8wEqKK6PBru3jl7A8 322 DGv6ra1nlYgDCS1FRnbzlwAAxowAIg1VvoJvrVBFhclGlx4G2FuProCVzJY04Lg5 323 vUP2LeswtWoBGHGoYXUzAwuxQGRGxoNbh8BROK3gmJ0 325 This example shows the ASCII encoded string, "When I grow up, I want 326 to be a watermelon". The content body is shown here with line 327 wrapping and URL-safe base64url encoding to meet presentation 328 constraints. Similarly, the "dh" parameter wrapped to meet line 329 length constraints. 331 Since there is no ambiguity about which keys are being used, the 332 "keyid" parameter is omitted from both the Encryption and Crypto-Key 333 header fields. The keys shown below use uncompressed points [X9.62] 334 encoded using base64url. 336 Authentication Secret: BTBZMqHH6r4Tts7J_aSIgg 337 Receiver: 338 private key: q1dXpw3UpT5VOmu_cf_v6ih07Aems3njxI-JWgLcM94 339 public key: BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcx 340 aOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4 341 Sender: 342 private key: yfWPiYE-n46HLnH0KqZOF1fJJU3MYrct3AELtAQ-oRw 343 public key: 345 Intermediate values for this example are included in Appendix A. 347 6. IANA Considerations 349 This document defines the "dh" parameter for the Crypto-Key header 350 field in the "Hypertext Transfer Protocol (HTTP) Crypto-Key 351 Parameters" registry defined in 352 [I-D.ietf-httpbis-encryption-encoding]. 354 o Parameter Name: dh 356 o Purpose: The "dh" parameter contains a Diffie-Hellman share which 357 is used to derive the input keying material used in "aes128gcm" 358 content coding. 360 o Reference: this document. 362 7. Security Considerations 364 The security considerations of [I-D.ietf-httpbis-encryption-encoding] 365 describe the limitations of the content encoding. In particular, any 366 HTTP header fields are not protected by the content encoding scheme. 367 A User Agent MUST consider HTTP header fields to have come from the 368 Push Service. An application on the User Agent that uses information 369 from header fields to alter their processing of a push message is 370 exposed to a risk of attack by the Push Service. 372 The timing and length of communication cannot be hidden from the Push 373 Service. While an outside observer might see individual messages 374 intermixed with each other, the Push Service will see what 375 Application Server is talking to which User Agent, and the 376 subscription that is used. Additionally, the length of messages 377 could be revealed unless the padding provided by the content encoding 378 scheme is used to obscure length. 380 8. References 382 8.1. Normative References 384 [ECDH] SECG, "Elliptic Curve Cryptography", SEC 1 , 2000, 385 . 387 [FIPS180-4] 388 Department of Commerce, National., "NIST FIPS 180-4, 389 Secure Hash Standard", March 2012, 390 . 393 [FIPS186] National Institute of Standards and Technology (NIST), 394 "Digital Signature Standard (DSS)", NIST PUB 186-4 , July 395 2013. 397 [I-D.ietf-httpbis-encryption-encoding] 398 Thomson, M., "Encrypted Content-Encoding for HTTP", draft- 399 ietf-httpbis-encryption-encoding-03 (work in progress), 400 October 2016. 402 [I-D.ietf-webpush-protocol] 403 Thomson, M., Damaggio, E., and B. Raymor, "Generic Event 404 Delivery Using HTTP Push", draft-ietf-webpush-protocol-12 405 (work in progress), October 2016. 407 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 408 Requirement Levels", BCP 14, RFC 2119, 409 DOI 10.17487/RFC2119, March 1997, 410 . 412 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 413 "Randomness Requirements for Security", BCP 106, RFC 4086, 414 DOI 10.17487/RFC4086, June 2005, 415 . 417 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 418 Key Derivation Function (HKDF)", RFC 5869, 419 DOI 10.17487/RFC5869, May 2010, 420 . 422 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 423 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 424 2015, . 426 [X9.62] ANSI, "Public Key Cryptography For The Financial Services 427 Industry: The Elliptic Curve Digital Signature Algorithm 428 (ECDSA)", ANSI X9.62 , 1998. 430 8.2. Informative References 432 [API] van Ouwerkerk, M. and M. Thomson, "Web Push API", 2015, 433 . 435 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 436 DOI 10.17487/RFC2818, May 2000, 437 . 439 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 440 Protocol (HTTP/1.1): Message Syntax and Routing", 441 RFC 7230, DOI 10.17487/RFC7230, June 2014, 442 . 444 Appendix A. Intermediate Values for Encryption 446 The intermediate values calculated for the example in Section 5 are 447 shown here. The following are inputs to the calculation: 449 Plaintext: V2hlbiBJIGdyb3cgdXAsIEkgd2FudCB0byBiZSBhIHdhdGVybWVsb24 451 Application Server public key (as_public): 452 BP4z9KsN6nGRTbVYI_c7VJSPQTBtkgcy27mlmlMoZIIg 453 Dll6e3vCYLocInmYWAmS6TlzAC8wEqKK6PBru3jl7A8 455 Application Server private key (as_private): yfWPiYE-n46HLnH0KqZOF1f 456 JJU3MYrct3AELtAQ-oRw 458 User Agent public key (ua_public): BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV- 459 JvLexhqUzORcx aOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4 461 User Agent private key (ua_private): 462 q1dXpw3UpT5VOmu_cf_v6ih07Aems3njxI-JWgLcM94 464 Salt: DGv6ra1nlYgDCS1FRnbzlw 466 Authentication secret (auth_secret): BTBZMqHH6r4Tts7J_aSIgg 468 Note that knowledge of just one of the private keys is necessary. 469 The Application Server randomly generates the salt value, whereas 470 salt is input to the receiver. 472 This produces the following intermediate values: 474 Shared ECDH secret (ecdh_secret): kyrL1jIIOHEzg3sM2ZWRHDRB62YACZhhSl 475 knJ672kSs 477 Pseudo-random key for key combining (PRK_key): 478 Snr3JMxaHVDXHWJn5wdC52WjpCtd2EIEGBykDcZW32k 480 Info for key combining (key_info): V2ViUHVzaDogaW5mbwAE_jP0qw3qcZFNt 481 Vgj9ztUlI9 BMG2SBzLbuaWaUyhkgiAOWXp7e8JguhwieZhYCZLpOX 482 MALzASooro8Gu7eOXsDwQlcbK-zf3jYFUarx7Q9M02b 483 BHOvlVfiby3sYalMzkXMWjs4uvgGFl70wR5uG48j47O 1XfKWRh-kkaZDbaCAIsO 485 Input keying material for content encryption key derivation (IKM): 486 dTQXtQpktdp6UQb29SUBcO5igFtC9WsXlhlNr2jRkkY 488 PRK for content encryption (PRK): BEhmz5JYdOXMsFJf_WDU8fJlOURaExoUoF 489 uaGU86Fuc 491 Info for content encryption key derivation (cek_info): 492 Q29udGVudC1FbmNvZGluZzogYWVzZ2NtMTI4AA 494 Content encryption key (CEK): wgJKGPLNgnI3CKy09z19Qw 496 Info for content encryption nonce derivation (nonce_info): 497 Q29udGVudC1FbmNvZGluZzogbm9uY2UA 499 Nonce (NONCE): w5SniqvyjVui9OoV 501 The salt and a record size of 4096 produce a 21 octet header of 502 DGv6ra1nlYgDCS1FRnbzlwAAxowA. 504 The push message plaintext is padded to produce 505 AABXaGVuIEkgZ3JvdyB1cCwgSSB3YW50IHRvIGJl IGEgd2F0ZXJtZWxvbg. The 506 plaintext is then encrypted with AES-GCM, which emits ciphertext of 507 Ig1VvoJvrVBFhclGlx4G2FuProCVzJY04Lg5vUP2 508 LeswtWoBGHGoYXUzAwuxQGRGxoNbh8BROK3gmJ0. 510 The header and cipher text are concatenated and produce the result 511 shown in the example. 513 Author's Address 515 Martin Thomson 516 Mozilla 518 Email: martin.thomson@gmail.com