idnits 2.17.1 draft-ietf-webpush-encryption-05.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 2732 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-05 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. This allows implementations to ignore the 282 first 21 octets of a push message. 284 A push service is not required to support more than 4096 octets of 285 payload body (see Section 7.2 of [I-D.ietf-webpush-protocol]), which 286 equates to at most 4059 octets of cleartext. 288 An Application Server MUST NOT use other content encodings for push 289 messages. In particular, content encodings that compress could 290 result in leaking of push message contents. The Content-Encoding 291 header field therefore has exactly one value, which is "aes128gcm". 292 Multiple "aes128gcm" values are not permitted. 294 An Application Server MUST include exactly one "aes128gcm" content 295 coding, and at most one entry in the Crypto-Key field. This allows 296 the "keyid" parameter to be omitted. 298 An Application Server MUST NOT include an "aes128gcm" parameter in 299 the Crypto-Key header field. 301 A User Agent is not required to support multiple records. A User 302 Agent MAY ignore the "rs" field and assume that the "keyid" field is 303 empty. If a record size is unchecked, decryption will fail with high 304 probability for all valid cases. However, decryption will also 305 succeed if the push message contains a single record from a longer 306 truncated message. Given that an Application Server is prohibited 307 from generating such a message, this is not considered a serious 308 risk. 310 5. Push Message Encryption Example 312 The following example shows a push message being sent to a push 313 service. 315 POST /push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV HTTP/1.1 316 Host: push.example.net 317 TTL: 10 318 Content-Length: 33 319 Content-Encoding: aes128gcm 320 Crypto-Key: dh=BP4z9KsN6nGRTbVYI_c7VJSPQTBtkgcy27mlmlMoZIIg 321 Dll6e3vCYLocInmYWAmS6TlzAC8wEqKK6PBru3jl7A8 323 DGv6ra1nlYgDCS1FRnbzlwAAxowAIg1VvoJvrVBFhclGlx4G2FuProCVzJY04Lg5 324 vUP2LeswtWoBGHGoYXUzAwuxQGRGxoNbh8BROK3gmJ0 326 This example shows the ASCII encoded string, "When I grow up, I want 327 to be a watermelon". The content body is shown here with line 328 wrapping and URL-safe base64url encoding to meet presentation 329 constraints. Similarly, the "dh" parameter wrapped to meet line 330 length constraints. 332 Since there is no ambiguity about which keys are being used, the 333 "keyid" parameter is omitted from both the Encryption and Crypto-Key 334 header fields. The keys shown below use uncompressed points [X9.62] 335 encoded using base64url. 337 Authentication Secret: BTBZMqHH6r4Tts7J_aSIgg 338 Receiver: 339 private key: q1dXpw3UpT5VOmu_cf_v6ih07Aems3njxI-JWgLcM94 340 public key: BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcx 341 aOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4 342 Sender: 343 private key: yfWPiYE-n46HLnH0KqZOF1fJJU3MYrct3AELtAQ-oRw 344 public key: 346 Intermediate values for this example are included in Appendix A. 348 6. IANA Considerations 350 This document defines the "dh" parameter for the Crypto-Key header 351 field in the "Hypertext Transfer Protocol (HTTP) Crypto-Key 352 Parameters" registry defined in 353 [I-D.ietf-httpbis-encryption-encoding]. 355 o Parameter Name: dh 357 o Purpose: The "dh" parameter contains a Diffie-Hellman share which 358 is used to derive the input keying material used in "aes128gcm" 359 content coding. 361 o Reference: this document. 363 7. Security Considerations 365 The security considerations of [I-D.ietf-httpbis-encryption-encoding] 366 describe the limitations of the content encoding. In particular, any 367 HTTP header fields are not protected by the content encoding scheme. 368 A User Agent MUST consider HTTP header fields to have come from the 369 Push Service. An application on the User Agent that uses information 370 from header fields to alter their processing of a push message is 371 exposed to a risk of attack by the Push Service. 373 The timing and length of communication cannot be hidden from the Push 374 Service. While an outside observer might see individual messages 375 intermixed with each other, the Push Service will see what 376 Application Server is talking to which User Agent, and the 377 subscription that is used. Additionally, the length of messages 378 could be revealed unless the padding provided by the content encoding 379 scheme is used to obscure length. 381 8. References 383 8.1. Normative References 385 [ECDH] SECG, "Elliptic Curve Cryptography", SEC 1 , 2000, 386 . 388 [FIPS180-4] 389 Department of Commerce, National., "NIST FIPS 180-4, 390 Secure Hash Standard", March 2012, 391 . 394 [FIPS186] National Institute of Standards and Technology (NIST), 395 "Digital Signature Standard (DSS)", NIST PUB 186-4 , July 396 2013. 398 [I-D.ietf-httpbis-encryption-encoding] 399 Thomson, M., "Encrypted Content-Encoding for HTTP", draft- 400 ietf-httpbis-encryption-encoding-03 (work in progress), 401 October 2016. 403 [I-D.ietf-webpush-protocol] 404 Thomson, M., Damaggio, E., and B. Raymor, "Generic Event 405 Delivery Using HTTP Push", draft-ietf-webpush-protocol-12 406 (work in progress), October 2016. 408 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 409 Requirement Levels", BCP 14, RFC 2119, 410 DOI 10.17487/RFC2119, March 1997, 411 . 413 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 414 "Randomness Requirements for Security", BCP 106, RFC 4086, 415 DOI 10.17487/RFC4086, June 2005, 416 . 418 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 419 Key Derivation Function (HKDF)", RFC 5869, 420 DOI 10.17487/RFC5869, May 2010, 421 . 423 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 424 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 425 2015, . 427 [X9.62] ANSI, "Public Key Cryptography For The Financial Services 428 Industry: The Elliptic Curve Digital Signature Algorithm 429 (ECDSA)", ANSI X9.62 , 1998. 431 8.2. Informative References 433 [API] van Ouwerkerk, M. and M. Thomson, "Web Push API", 2015, 434 . 436 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 437 DOI 10.17487/RFC2818, May 2000, 438 . 440 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 441 Protocol (HTTP/1.1): Message Syntax and Routing", 442 RFC 7230, DOI 10.17487/RFC7230, June 2014, 443 . 445 Appendix A. Intermediate Values for Encryption 447 The intermediate values calculated for the example in Section 5 are 448 shown here. The following are inputs to the calculation: 450 Plaintext: V2hlbiBJIGdyb3cgdXAsIEkgd2FudCB0byBiZSBhIHdhdGVybWVsb24 452 Application Server public key (as_public): 453 BP4z9KsN6nGRTbVYI_c7VJSPQTBtkgcy27mlmlMoZIIg 454 Dll6e3vCYLocInmYWAmS6TlzAC8wEqKK6PBru3jl7A8 456 Application Server private key (as_private): yfWPiYE-n46HLnH0KqZOF1f 457 JJU3MYrct3AELtAQ-oRw 459 User Agent public key (ua_public): BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV- 460 JvLexhqUzORcx aOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4 462 User Agent private key (ua_private): 463 q1dXpw3UpT5VOmu_cf_v6ih07Aems3njxI-JWgLcM94 465 Salt: DGv6ra1nlYgDCS1FRnbzlw 467 Authentication secret (auth_secret): BTBZMqHH6r4Tts7J_aSIgg 469 Note that knowledge of just one of the private keys is necessary. 470 The Application Server randomly generates the salt value, whereas 471 salt is input to the receiver. 473 This produces the following intermediate values: 475 Shared ECDH secret (ecdh_secret): kyrL1jIIOHEzg3sM2ZWRHDRB62YACZhhSl 476 knJ672kSs 478 Pseudo-random key for key combining (PRK_key): 479 Snr3JMxaHVDXHWJn5wdC52WjpCtd2EIEGBykDcZW32k 481 Info for key combining (key_info): V2ViUHVzaDogaW5mbwAE_jP0qw3qcZFNt 482 Vgj9ztUlI9 BMG2SBzLbuaWaUyhkgiAOWXp7e8JguhwieZhYCZLpOX 483 MALzASooro8Gu7eOXsDwQlcbK-zf3jYFUarx7Q9M02b 484 BHOvlVfiby3sYalMzkXMWjs4uvgGFl70wR5uG48j47O 1XfKWRh-kkaZDbaCAIsO 486 Input keying material for content encryption key derivation (IKM): 487 dTQXtQpktdp6UQb29SUBcO5igFtC9WsXlhlNr2jRkkY 489 PRK for content encryption (PRK): BEhmz5JYdOXMsFJf_WDU8fJlOURaExoUoF 490 uaGU86Fuc 492 Info for content encryption key derivation (cek_info): 493 Q29udGVudC1FbmNvZGluZzogYWVzZ2NtMTI4AA 495 Content encryption key (CEK): wgJKGPLNgnI3CKy09z19Qw 497 Info for content encryption nonce derivation (nonce_info): 498 Q29udGVudC1FbmNvZGluZzogbm9uY2UA 500 Nonce (NONCE): w5SniqvyjVui9OoV 502 The salt and a record size of 4096 produce a 21 octet header of 503 DGv6ra1nlYgDCS1FRnbzlwAAxowA. 505 The push message plaintext is padded to produce 506 AABXaGVuIEkgZ3JvdyB1cCwgSSB3YW50IHRvIGJl IGEgd2F0ZXJtZWxvbg. The 507 plaintext is then encrypted with AES-GCM, which emits ciphertext of 508 Ig1VvoJvrVBFhclGlx4G2FuProCVzJY04Lg5vUP2 509 LeswtWoBGHGoYXUzAwuxQGRGxoNbh8BROK3gmJ0. 511 The header and cipher text are concatenated and produce the result 512 shown in the example. 514 Author's Address 516 Martin Thomson 517 Mozilla 519 Email: martin.thomson@gmail.com