idnits 2.17.1 draft-ietf-webpush-encryption-02.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 (March 20, 2016) is 2958 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. 'DH' -- Possible downref: Non-RFC (?) normative reference: ref. 'ECDH' -- Possible downref: Non-RFC (?) normative reference: ref. 'FIPS186' == Outdated reference: A later version (-09) exists of draft-ietf-httpbis-encryption-encoding-01 == Outdated reference: A later version (-12) exists of draft-ietf-webpush-protocol-03 -- 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: 0 errors (**), 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 March 20, 2016 5 Expires: September 21, 2016 7 Message Encryption for Web Push 8 draft-ietf-webpush-encryption-02 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 September 21, 2016. 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. Key Generation and Agreement . . . . . . . . . . . . . . . . 3 53 2.1. Diffie-Hellman Group Information . . . . . . . . . . . . 3 54 2.2. Key Distribution . . . . . . . . . . . . . . . . . . . . 4 55 2.3. Push Message Authentication . . . . . . . . . . . . . . . 4 56 3. Message Encryption . . . . . . . . . . . . . . . . . . . . . 4 57 3.1. Key Derivation . . . . . . . . . . . . . . . . . . . . . 4 58 3.2. Push Message Content Encryption . . . . . . . . . . . . . 5 59 4. Message Decryption . . . . . . . . . . . . . . . . . . . . . 5 60 5. Mandatory Group and Public Key Format . . . . . . . . . . . . 6 61 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 62 7. Security Considerations . . . . . . . . . . . . . . . . . . . 6 63 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 64 8.1. Normative References . . . . . . . . . . . . . . . . . . 7 65 8.2. Informative References . . . . . . . . . . . . . . . . . 7 66 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8 68 1. Introduction 70 The Web Push protocol [I-D.ietf-webpush-protocol] is an intermediated 71 protocol by necessity. Messages from an Application Server are 72 delivered to a User Agent via a Push Service. 74 +-------+ +--------------+ +-------------+ 75 | UA | | Push Service | | Application | 76 +-------+ +--------------+ +-------------+ 77 | | | 78 | Setup | | 79 |<====================>| | 80 | Provide Subscription | 81 |-------------------------------------------->| 82 | | | 83 : : : 84 | | Push Message | 85 | Push Message |<---------------------| 86 |<---------------------| | 87 | | | 89 This document describes how messages sent using this protocol can be 90 secured against inspection, modification and falsification by a Push 91 Service. 93 Web Push messages are the payload of an HTTP message [RFC7230]. 94 These messages are encrypted using an encrypted content encoding 95 [I-D.ietf-httpbis-encryption-encoding]. This document describes how 96 this content encoding is applied and describes a recommended key 97 management scheme. 99 For efficiency reasons, multiple users of Web Push often share a 100 central agent that aggregates push functionality. This agent can 101 enforce the use of this encryption scheme by applications that use 102 push messaging. An agent that only delivers messages that are 103 properly encrypted strongly encourages the end-to-end protection of 104 messages. 106 A web browser that implements the Web Push API [API] can enforce the 107 use of encryption by forwarding only those messages that were 108 properly encrypted. 110 1.1. Notational Conventions 112 The words "MUST", "MUST NOT", "SHOULD", and "MAY" are used in this 113 document. It's not shouting, when they are capitalized, they have 114 the special meaning described in [RFC2119]. 116 2. Key Generation and Agreement 118 For each new subscription that the User Agent generates for an 119 application, it also generates an asymmetric key pair for use in 120 Diffie-Hellman (DH) [DH] or elliptic-curve Diffie-Hellman (ECDH) 121 [ECDH]. The public key for this key pair can then be distributed by 122 the application to the Application Server along with the URI of the 123 subscription. The private key MUST remain secret. 125 This key pair is used with the Diffie-Hellman key exchange as 126 described in Section 4.2 of [I-D.ietf-httpbis-encryption-encoding]. 128 A User Agent MUST generate and provide a public key for the scheme 129 described in Section 5. 131 The public key MUST be accompanied by a key identifier that can be 132 used in the "keyid" parameter to identify which key is in use. Key 133 identifiers need only be unique within the context of a subscription. 135 2.1. Diffie-Hellman Group Information 137 As described in [I-D.ietf-httpbis-encryption-encoding], use of 138 Diffie-Hellman for key agreement requires that the receiver provide 139 clear information about its chosen group and the format for the "dh" 140 parameter with each potential sender. 142 This document only describes a single ECDH group and point format, 143 described in Section 5. A specification that defines alternative 144 groups or formats MUST provide a means of indicating precisely which 145 group and format is in use for every public key that is provided. 147 2.2. Key Distribution 149 The application using the subscription distributes the key identifier 150 and public key along with other subscription information, such as the 151 subscription URI and expiration time. 153 The communication medium by which an application distributes the key 154 identifier and public key MUST be confidentiality protected for the 155 reasons described in [I-D.ietf-webpush-protocol]. Most applications 156 that use push messaging have a pre-existing relationship with an 157 Application Server. Any existing communication mechanism that is 158 authenticated and provides confidentiality and integrity, such as 159 HTTPS [RFC2818], is sufficient. 161 2.3. Push Message Authentication 163 To ensure that push messages are correctly authenticated, a symmetric 164 authentication secret is added to the information generated by a User 165 Agent. The authentication secret is mixed into the key derivation 166 process described in [I-D.ietf-httpbis-encryption-encoding]. 168 The authentication secret ensures that exposure or leakage of the DH 169 public key - which, as a public key, is not necessarily treated as a 170 secret - does not enable an adversary to generate valid push 171 messages. 173 A User Agent MUST generate and provide a hard to guess sequence of 174 octets that is used for authentication of push messages. This SHOULD 175 be generated by a cryptographically strong random number generator 176 [RFC4086] and be at least 16 octets long. 178 3. Message Encryption 180 An Application Server that has the public key, group and format 181 information plus the authentication secret can encrypt a message for 182 the User Agent. 184 3.1. Key Derivation 186 The Application Server generates a new DH or ECDH key pair in the 187 same group as the value generated by the User Agent. 189 From the newly generated key pair, the Application Server performs a 190 DH or ECDH computation with the public key provided by the User Agent 191 to find the input keying material for key derivation. The 192 Application Server then generates 16 octets of salt that is unique to 193 the message. A random [RFC4086] salt is acceptable. 195 Web push uses the authentication secret defined in Section 4.3 of 196 [I-D.ietf-httpbis-encryption-encoding]. This authentication secret 197 (see Section 2.3) is generated by the user agent and shared with the 198 application server. 200 3.2. Push Message Content Encryption 202 The Application Server then encrypts the payload. Header fields are 203 populated with base64url encoded [RFC7515] values: 205 o the salt is added to the "salt" parameter of the Encryption header 206 field; and 208 o the public key for its DH or ECDH key pair is placed in the "dh" 209 parameter of the Crypto-Key header field. 211 An application server MUST encrypt a push message with a single 212 record. This allows for a minimal receiver implementation that 213 handles a single record. If the message is 4096 octets or longer, 214 the "rs" parameter MUST be set to a value that is longer than the 215 encrypted push message length. 217 Note that a push service is not required to support more than 4096 218 octets of payload body, which equates to 4080 octets of cleartext, so 219 the "rs" parameter can be omitted for messages that fit within this 220 limit. 222 An application server MUST NOT use other content encodings for push 223 messages. In particular, content encodings that compress could 224 result in leaking of push message contents. The Content-Encoding 225 header field therefore has exactly one value, which is "aesgcm128". 226 Multiple "aesgcm128" values are not permitted. 228 An application server MUST include exactly one entry in each of the 229 Encryption and Crypto-Key header fields. This allows the "keyid" 230 parameter to be omitted from both header fields. 232 An application server MUST NOT include an "aesgcm128" parameter in 233 the Encryption header field. 235 4. Message Decryption 237 A User Agent decrypts messages are decrypted as described in 238 [I-D.ietf-httpbis-encryption-encoding]. The authentication secret 239 described in Section 3.1 is used in key derivation. 241 Note that the value of the "keyid" parameter is used to identify the 242 correct share, if there are multiple values for the Crypto-Key header 243 field. 245 A receiver is not required to support multiple records. Such a 246 receiver MUST check that the record size is large enough to contain 247 the entire payload body in a single record. The "rs" parameter MUST 248 NOT be exactly equal to the length of the payload body minus the 249 length of the authentication tag (16 octets); that length indicates 250 that the message has been truncated. 252 5. Mandatory Group and Public Key Format 254 User Agents MUST expose an elliptic curve Diffie-Hellman share on the 255 P-256 curve [FIPS186]. 257 Public keys, such as are encoded into the "dh" parameter, MUST be in 258 the form of an uncompressed point as described in [X.692] (that is, a 259 65 octet sequence that starts with a 0x04 octet). 261 The label for this curve is the string "P-256" encoded in ASCII (that 262 is, the octet sequence 0x50, 0x2d, 0x32, 0x35, 0x36). 264 6. IANA Considerations 266 This document has no IANA actions. 268 7. Security Considerations 270 The security considerations of [I-D.ietf-httpbis-encryption-encoding] 271 describe the limitations of the content encoding. In particular, any 272 HTTP header fields are not protected by the content encoding scheme. 273 A User Agent MUST consider HTTP header fields to have come from the 274 Push Service. An application on the User Agent that uses information 275 from header fields to alter their processing of a push message is 276 exposed to a risk of attack by the Push Service. 278 The timing and length of communication cannot be hidden from the Push 279 Service. While an outside observer might see individual messages 280 intermixed with each other, the Push Service will see what 281 Application Server is talking to which User Agent, and the 282 subscription that is used. Additionally, the length of messages 283 could be revealed unless the padding provided by the content encoding 284 scheme is used to obscure length. 286 8. References 288 8.1. Normative References 290 [DH] Diffie, W. and M. Hellman, "New Directions in 291 Cryptography", IEEE Transactions on Information Theory, 292 V.IT-22 n.6 , June 1977. 294 [ECDH] SECG, "Elliptic Curve Cryptography", SEC 1 , 2000, 295 . 297 [FIPS186] National Institute of Standards and Technology (NIST), 298 "Digital Signature Standard (DSS)", NIST PUB 186-4 , July 299 2013. 301 [I-D.ietf-httpbis-encryption-encoding] 302 Thomson, M., "Encrypted Content-Encoding for HTTP", draft- 303 ietf-httpbis-encryption-encoding-01 (work in progress), 304 March 2016. 306 [I-D.ietf-webpush-protocol] 307 Thomson, M., Damaggio, E., and B. Raymor, "Generic Event 308 Delivery Using HTTP Push", draft-ietf-webpush-protocol-03 309 (work in progress), February 2016. 311 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 312 Requirement Levels", BCP 14, RFC 2119, 313 DOI 10.17487/RFC2119, March 1997, 314 . 316 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 317 "Randomness Requirements for Security", BCP 106, RFC 4086, 318 DOI 10.17487/RFC4086, June 2005, 319 . 321 [X.692] ANSI, "Public Key Cryptography For The Financial Services 322 Industry: The Elliptic Curve Digital Signature Algorithm 323 (ECDSA)", ANSI X9.62 , 1998. 325 8.2. Informative References 327 [API] van Ouwerkerk, M. and M. Thomson, "Web Push API", 2015, 328 . 330 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, 331 DOI 10.17487/RFC2818, May 2000, 332 . 334 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 335 Protocol (HTTP/1.1): Message Syntax and Routing", 336 RFC 7230, DOI 10.17487/RFC7230, June 2014, 337 . 339 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 340 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 341 2015, . 343 Author's Address 345 Martin Thomson 346 Mozilla 348 Email: martin.thomson@gmail.com