idnits 2.17.1 draft-ietf-webpush-encryption-08.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 (February 14, 2017) is 2625 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-08 ** 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 February 14, 2017 5 Expires: August 18, 2017 7 Message Encryption for Web Push 8 draft-ietf-webpush-encryption-08 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 August 18, 2017. 33 Copyright Notice 35 Copyright (c) 2017 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 . . . . . . . . . . . . . . . . . . . 5 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 . . . . . . . . . . . . . . . . . . . . . . . . . 8 64 8.1. Normative References . . . . . . . . . . . . . . . . . . 8 65 8.2. Informative References . . . . . . . . . . . . . . . . . 9 66 Appendix A. Intermediate Values for Encryption . . . . . . . . . 9 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 as the 191 "keyid" parameter in the encrypted content coding header (see 192 Section 2.1 of [I-D.ietf-httpbis-encryption-encoding]. 194 An Application combines its ECDH private key with the public key 195 provided by the User Agent using the process described in [ECDH]; on 196 receipt of the push message, a User Agent combines its private key 197 with the public key provided by the Application Server in the "dh" 198 parameter in the same way. These operations produce the same value 199 for the ECDH shared secret. 201 3.2. Push Message Authentication 203 To ensure that push messages are correctly authenticated, a symmetric 204 authentication secret is added to the information generated by a User 205 Agent. The authentication secret is mixed into the key derivation 206 process shown in Section 3.3. 208 A User Agent MUST generate and provide a hard to guess sequence of 16 209 octets that is used for authentication of push messages. This SHOULD 210 be generated by a cryptographically strong random number generator 211 [RFC4086]. 213 3.3. Combining Shared and Authentication Secrets 215 The shared secret produced by ECDH is combined with the 216 authentication secret using HMAC-based key derivation function (HKDF) 217 described in [RFC5869]. This produces the input keying material used 218 by [I-D.ietf-httpbis-encryption-encoding]. 220 The HKDF function uses SHA-256 hash algorithm [FIPS180-4] with the 221 following inputs: 223 salt: the authentication secret 225 IKM: the shared secret derived using ECDH 227 info: the concatenation of the ASCII-encoded string "WebPush: info", 228 a zero octet, the X9.62 encoding of the User Agent ECDH public 229 key, and X9.62 encoding of the Application Server ECDH public key; 230 that is 232 key_info = "WebPush: info" || 0x00 || ua_public || as_public 234 L: 32 octets (i.e., the output is the length of the underlying 235 SHA-256 HMAC function output) 237 3.4. Encryption Summary 239 This results in a the final content encryption key and nonce 240 generation using the following sequence, which is shown here in 241 pseudocode with HKDF expanded into separate discrete steps using HMAC 242 with SHA-256: 244 -- For a User Agent: 245 ecdh_secret = ECDH(ua_private, as_public) 246 auth_secret = random(16) 248 -- For an Application Server: 249 ecdh_secret = ECDH(as_private, ua_public) 250 auth_secret = 252 -- For both: 253 PRK_key = HMAC-SHA-256(auth_secret, ecdh_secret) 254 key_info = "WebPush: info" || 0x00 || ua_public || as_public 255 IKM = HMAC-SHA-256(PRK_cek, key_info || 0x01) 257 salt = random(16) 258 PRK = HMAC-SHA-256(salt, IKM) 259 cek_info = "Content-Encoding: aes128gcm" || 0x00 260 CEK = HMAC-SHA-256(PRK, cek_info || 0x01)[0..15] 261 nonce_info = "Content-Encoding: nonce" || 0x00 262 NONCE = HMAC-SHA-256(PRK, nonce_info || 0x01)[0..11] 264 Note that this omits the exclusive OR of the final nonce with the 265 record sequence number, since push messages contain only a single 266 record (see Section 4) and the sequence number of the first record is 267 zero. 269 4. Restrictions on Use of "aes128gcm" Content Coding 271 An Application Server MUST encrypt a push message with a single 272 record. This allows for a minimal receiver implementation that 273 handles a single record. An application server MUST set the "rs" 274 parameter in the "aes128gcm" content coding header to a size that is 275 greater than the some of the length of the plaintext, the padding 276 delimiter (1 octet), any padding, and the authentication tag (16 277 octets). 279 A push message MUST include the application server ECDH public key in 280 the "keyid" parameter of the encrypted content coding header. The 281 uncompressed point form defined in [X9.62] (that is, a 65 octet 282 sequence that starts with a 0x04 octet) forms the entirety of the 283 "keyid". 285 A push service is not required to support more than 4096 octets of 286 payload body (see Section 7.2 of [I-D.ietf-webpush-protocol]). 287 Absent header (86 octets), padding (minimum 2 octets), and expansion 288 for AEAD_AES_128_GCM (16 octets), this equates to at most 3992 octets 289 of plaintext. 291 An Application Server MUST NOT use other content encodings for push 292 messages. In particular, content encodings that compress could 293 result in leaking of push message contents. The Content-Encoding 294 header field therefore has exactly one value, which is "aes128gcm". 295 Multiple "aes128gcm" values are not permitted. 297 A User Agent is not required to support multiple records. A User 298 Agent MAY ignore the "rs" field. If a record size is unchecked, 299 decryption will fail with high probability for all valid cases. The 300 padding delimiter octet MUST be checked, values other than 0x02 MUST 301 cause the message to be discarded. 303 5. Push Message Encryption Example 305 The following example shows a push message being sent to a push 306 service. 308 POST /push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV HTTP/1.1 309 Host: push.example.net 310 TTL: 10 311 Content-Length: 145 312 Content-Encoding: aes128gcm 314 DGv6ra1nlYgDCS1FRnbzlwAAEABBBP4z9KsN6nGRTbVYI_c7VJSPQTBtkgcy27ml 315 mlMoZIIgDll6e3vCYLocInmYWAmS6TlzAC8wEqKK6PBru3jl7A_yl95bQpu6cVPT 316 pK4Mqgkf1CXztLVBSt2Ks3oZwbuwXPXLWyouBWLVWGNWQexSgSxsj_Qulcy4a-fN 318 This example shows the ASCII encoded string, "When I grow up, I want 319 to be a watermelon". The content body is shown here with line 320 wrapping and URL-safe base64url encoding to meet presentation 321 constraints. 323 The keys used are shown below using the uncompressed form [X9.62] 324 encoded using base64url. 326 Authentication Secret: BTBZMqHH6r4Tts7J_aSIgg 327 Receiver: 328 private key: q1dXpw3UpT5VOmu_cf_v6ih07Aems3njxI-JWgLcM94 329 public key: BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcx 330 aOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4 331 Sender: 332 private key: yfWPiYE-n46HLnH0KqZOF1fJJU3MYrct3AELtAQ-oRw 333 public key: 335 Intermediate values for this example are included in Appendix A. 337 6. IANA Considerations 339 [[RFC EDITOR: please remote this section before publication.]] This 340 document makes no request of IANA. 342 7. Security Considerations 344 The security considerations of [I-D.ietf-httpbis-encryption-encoding] 345 describe the limitations of the content encoding. In particular, any 346 HTTP header fields are not protected by the content encoding scheme. 347 A User Agent MUST consider HTTP header fields to have come from the 348 Push Service. An application on the User Agent that uses information 349 from header fields to alter their processing of a push message is 350 exposed to a risk of attack by the Push Service. 352 The timing and length of communication cannot be hidden from the Push 353 Service. While an outside observer might see individual messages 354 intermixed with each other, the Push Service will see what 355 Application Server is talking to which User Agent, and the 356 subscription that is used. Additionally, the length of messages 357 could be revealed unless the padding provided by the content encoding 358 scheme is used to obscure length. 360 8. References 362 8.1. Normative References 364 [ECDH] SECG, "Elliptic Curve Cryptography", SEC 1 , 2000, 365 . 367 [FIPS180-4] 368 Department of Commerce, National., "NIST FIPS 180-4, 369 Secure Hash Standard", March 2012, 370 . 373 [FIPS186] National Institute of Standards and Technology (NIST), 374 "Digital Signature Standard (DSS)", NIST PUB 186-4 , July 375 2013. 377 [I-D.ietf-httpbis-encryption-encoding] 378 Thomson, M., "Encrypted Content-Encoding for HTTP", draft- 379 ietf-httpbis-encryption-encoding-02 (work in progress), 380 June 2016. 382 [I-D.ietf-webpush-protocol] 383 Thomson, M., Damaggio, E., and B. Raymor, "Generic Event 384 Delivery Using HTTP Push", draft-ietf-webpush-protocol-08 385 (work in progress), July 2016. 387 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 388 Requirement Levels", BCP 14, RFC 2119, 389 DOI 10.17487/RFC2119, March 1997, 390 . 392 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 393 "Randomness Requirements for Security", BCP 106, RFC 4086, 394 DOI 10.17487/RFC4086, June 2005, 395 . 397 [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand 398 Key Derivation Function (HKDF)", RFC 5869, 399 DOI 10.17487/RFC5869, May 2010, 400 . 402 [X9.62] ANSI, "Public Key Cryptography For The Financial Services 403 Industry: The Elliptic Curve Digital Signature Algorithm 404 (ECDSA)", ANSI X9.62 , 1998. 406 8.2. Informative References 408 [API] van Ouwerkerk, M. and M. Thomson, "Web Push API", 2015, 409 . 411 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 412 DOI 10.17487/RFC2818, May 2000, 413 . 415 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 416 Protocol (HTTP/1.1): Message Syntax and Routing", 417 RFC 7230, DOI 10.17487/RFC7230, June 2014, 418 . 420 Appendix A. Intermediate Values for Encryption 422 The intermediate values calculated for the example in Section 5 are 423 shown here. The following are inputs to the calculation: 425 Plaintext: V2hlbiBJIGdyb3cgdXAsIEkgd2FudCB0byBiZSBhIHdhdGVybWVsb24 427 Application Server public key (as_public): 428 BP4z9KsN6nGRTbVYI_c7VJSPQTBtkgcy27mlmlMoZIIg 429 Dll6e3vCYLocInmYWAmS6TlzAC8wEqKK6PBru3jl7A8 431 Application Server private key (as_private): yfWPiYE-n46HLnH0KqZOF1f 432 JJU3MYrct3AELtAQ-oRw 434 User Agent public key (ua_public): BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV- 435 JvLexhqUzORcx aOzi6-AYWXvTBHm4bjyPjs7Vd8pZGH6SRpkNtoIAiw4 437 User Agent private key (ua_private): 438 q1dXpw3UpT5VOmu_cf_v6ih07Aems3njxI-JWgLcM94 440 Salt: DGv6ra1nlYgDCS1FRnbzlw 442 Authentication secret (auth_secret): BTBZMqHH6r4Tts7J_aSIgg 444 Note that knowledge of just one of the private keys is necessary. 445 The Application Server randomly generates the salt value, whereas 446 salt is input to the receiver. 448 This produces the following intermediate values: 450 Shared ECDH secret (ecdh_secret): kyrL1jIIOHEzg3sM2ZWRHDRB62YACZhhSl 451 knJ672kSs 453 Pseudo-random key for key combining (PRK_key): 454 Snr3JMxaHVDXHWJn5wdC52WjpCtd2EIEGBykDcZW32k 456 Info for key combining (key_info): V2ViUHVzaDogaW5mbwAEJXGyvs3942BVG 457 q8e0PTNNmwR zr5VX4m8t7GGpTM5FzFo7OLr4BhZe9MEebhuPI-OztV3 458 ylkYfpJGmQ22ggCLDgT-M_SrDepxkU21WCP3O1SUj0Ew 459 bZIHMtu5pZpTKGSCIA5Zent7wmC6HCJ5mFgJkuk5cwAv MBKiiujwa7t45ewP 461 Input keying material for content encryption key derivation (IKM): 462 S4lYMb_L0FxCeq0WhDx813KgSYqU26kOyzWUdsXYyrg 464 PRK for content encryption (PRK): 09_eUZGrsvxChDCGRCdkLiDXrReGOEVeSC 465 dCcPBSJSc 467 Info for content encryption key derivation (cek_info): 468 Q29udGVudC1FbmNvZGluZzogYWVzMTI4Z2NtAA 470 Content encryption key (CEK): oIhVW04MRdy2XN9CiKLxTg 472 Info for content encryption nonce derivation (nonce_info): 473 Q29udGVudC1FbmNvZGluZzogbm9uY2UA 475 Nonce (NONCE): 4h_95klXJ5E_qnoN 477 The salt, record size of 4096, and application server public key 478 produce an 86 octet header of DGv6ra1nlYgDCS1FRnbzlwAAEABBBP4z 479 9KsN6nGRTbVYI_c7VJSPQTBtkgcy27ml mlMoZIIgDll6e3vCYLocInmYWAmS6Tlz 480 AC8wEqKK6PBru3jl7A8. 482 The push message plaintext has the padding delimiter octet (0x02) 483 appended to produce V2hlbiBJIGdyb3cgdXAsIEkgd2FudCB0 484 byBiZSBhIHdhdGVybWVsb24C. The plaintext is then encrypted with AES- 485 GCM, which emits ciphertext of 8pfeW0KbunFT06SuDKoJH9Ql87S1QUrd 486 irN6GcG7sFz1y1sqLgVi1VhjVkHsUoEs bI_0LpXMuGvnzQ. 488 The header and cipher text are concatenated and produce the result 489 shown in Section 5. 491 Author's Address 493 Martin Thomson 494 Mozilla 496 Email: martin.thomson@gmail.com