idnits 2.17.1 draft-ietf-webpush-encryption-01.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 19, 2015) is 3112 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 (-02) exists of draft-thomson-http-encryption-01 -- 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 (~~), 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 19, 2015 5 Expires: April 21, 2016 7 Message Encryption for Web Push 8 draft-ietf-webpush-encryption-01 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 21, 2016. 33 Copyright Notice 35 Copyright (c) 2015 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 3. Message Encryption . . . . . . . . . . . . . . . . . . . . . 4 56 4. Message Decryption . . . . . . . . . . . . . . . . . . . . . 5 57 5. Mandatory Group and Public Key Format . . . . . . . . . . . . 5 58 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 59 7. Security Considerations . . . . . . . . . . . . . . . . . . . 5 60 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 8.1. Normative References . . . . . . . . . . . . . . . . . . 6 62 8.2. Informative References . . . . . . . . . . . . . . . . . 7 63 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 65 1. Introduction 67 The Web Push protocol [I-D.thomson-webpush-protocol] is an 68 intermediated protocol by necessity. Messages from an Application 69 Server are delivered to a User Agent via a Push Service. 71 +-------+ +--------------+ +-------------+ 72 | UA | | Push Service | | Application | 73 +-------+ +--------------+ +-------------+ 74 | | | 75 | Setup | | 76 |<====================>| | 77 | Provide Subscription | 78 |-------------------------------------------->| 79 | | | 80 : : : 81 | | Push Message | 82 | Push Message |<---------------------| 83 |<---------------------| | 84 | | | 86 This document describes how messages sent using this protocol can be 87 secured against inspection or modification by a Push Service. 89 Web Push messages are the payload of an HTTP message [RFC7230]. 90 These messages are encrypted using an encrypted content encoding 91 [I-D.thomson-http-encryption]. This document describes how this 92 content encoding is applied and describes a recommended key 93 management scheme. 95 For efficiency reasons, multiple users of Web Push often share a 96 central agent that aggregates push functionality. This agent can 97 enforce the use of this encryption scheme by applications that use 98 push messaging. An agent that only delivers messages that are 99 properly encrypted strongly encourages the end-to-end protection of 100 messages. 102 A web browser that implements the Web Push API [API] can enforce the 103 use of encryption by forwarding only those messages that were 104 properly encrypted. 106 1.1. Notational Conventions 108 The words "MUST", "MUST NOT", "SHOULD", and "MAY" are used in this 109 document. It's not shouting, when they are capitalized, they have 110 the special meaning described in [RFC2119]. 112 2. Key Generation and Agreement 114 For each new subscription that the User Agent generates for an 115 application, it also generates an asymmetric key pair for use in 116 Diffie-Hellman (DH) [DH] or elliptic-curve Diffie-Hellman (ECDH) 117 [ECDH]. The public key for this key pair can then be distributed by 118 the application to the Application Server along with the URI of the 119 subscription. The private key MUST remain secret. 121 This key pair is used with the Diffie-Hellman key exchange as 122 described in Section 4.2 of [I-D.thomson-http-encryption]. 124 A User Agent MUST generate and provide a public key for the scheme 125 described in Section 5. 127 The public key MUST be accompanied by a key identifier that can be 128 used in the "keyid" parameter to identify which key is in use. Key 129 identifiers need only be unique within the context of a subscription. 131 2.1. Diffie-Hellman Group Information 133 As described in [I-D.thomson-http-encryption], use of Diffie-Hellman 134 for key agreement requires that the receiver provide clear 135 information about it's chosen group and the format for the "dh" 136 parameter with each potential sender. 138 This document only describes a single ECDH group and point format, 139 described in Section 5. A specification that defines alternative 140 groups or formats MUST provide a means of indicating precisely which 141 group and format is in use for every public key that is provided. 143 2.2. Key Distribution 145 The application using the subscription distributes the key identifier 146 and public key along with other subscription information, such as the 147 subscription URI and expiration time. 149 The communication medium by which an application distributes the key 150 identifier and public key MUST be confidentiality protected for the 151 reasons described in [I-D.thomson-webpush-protocol]. Most 152 applications that use push messaging have a pre-existing relationship 153 with an Application Server. Any existing communication mechanism 154 that is authenticated and provides confidentiality and integrity, 155 such as HTTPS [RFC2818], is sufficient. 157 3. Message Encryption 159 An Application Server that has the key identifier, public key, group 160 and format information can encrypt a message for the User Agent. 162 The Application Server generates a new DH or ECDH key pair in the 163 same group as the value generated by the User Agent. 165 From the newly generated key pair, the Application Server performs a 166 DH or ECDH computation with the public key provided by the User Agent 167 to find the shared secret. The Application Server then generates 16 168 octets of salt that is unique to the message. A random [RFC4086] 169 salt is acceptable. These values are used to calculate the content 170 encryption key as defined in Section 3.2 of 171 [I-D.thomson-http-encryption]. 173 The Application Server then encrypts the payload. Header fields are 174 populated with URL-safe base-64 encoded [RFC4648] values: 176 o the salt is added to the "salt" parameter of the Encryption header 177 field; and 179 o the public key for its DH or ECDH key pair is placed in the "dh" 180 parameter of the Encryption-Key header field. 182 An application server MUST encrypt a push message with a single 183 record. This allows for a minimal receiver implementation that 184 handles a single record. If the message is 4096 octets long, or 185 longer, this means that the "rs" parameter MUST be set to a value 186 that is longer than the encrypted push message length. 188 Note that a push service is not required to support more than 4096 189 octets of payload body, which equates to 4080 octets of cleartext, so 190 the "rs" parameter can be omitted for messages that fit within this 191 limit. 193 An application server MUST NOT use other content encodings for push 194 messages. In particular, content encodings that compress could 195 result in leaking of push message contents. The Content-Encoding 196 header field therefore has exactly one value, which is "aesgcm128". 197 Multiple "aesgcm128" values are not permitted. 199 An application server MUST include exactly one entry in each of the 200 Encryption and Encryption-Key header fields. This allows the "keyid" 201 parameter to be omitted from both header fields. 203 An application server MUST NOT include a "key" parameter in the 204 Encryption header field. 206 4. Message Decryption 208 A User Agent decrypts messages are decrypted as described in 209 [I-D.thomson-http-encryption]. The value of the "keyid" parameter is 210 used to identify the correct key pair, if there is more than one 211 possible value for the corresponding subscription. 213 A receiver is not required to support multiple records. Such a 214 receiver MUST check that the record size is large enough to contain 215 the entire payload body in a single record. The "rs" parameter MUST 216 NOT be exactly equal to the length of the payload body minus the 217 length of the authentication tag (16 octets); that length indicates 218 that the message has been truncated. 220 5. Mandatory Group and Public Key Format 222 User Agents that enforce encryption MUST expose an elliptic curve 223 Diffie-Hellman share on the P-256 curve [FIPS186]. Public keys, such 224 as are encoded into the "dh" parameter, MUST be in the form of an 225 uncompressed point as described in [X.692]. 227 6. IANA Considerations 229 This document has no IANA actions. 231 7. Security Considerations 233 The security considerations of [I-D.thomson-http-encryption] describe 234 the limitations of the content encoding. In particular, any HTTP 235 header fields are not protected by the content encoding scheme. A 236 User Agent MUST consider HTTP header fields to have come from the 237 Push Service. An application on the User Agent that uses information 238 from header fields to alter their processing of a push message is 239 exposed to a risk of attack by the Push Service. 241 The timing and length of communication cannot be hidden from the Push 242 Service. While an outside observer might see individual messages 243 intermixed with each other, the Push Service will see what 244 Application Server is talking to which User Agent, and the 245 subscription they are talking about. Additionally, the length of 246 messages could be revealed unless the padding provided by the content 247 encoding scheme is used to obscure length. 249 8. References 251 8.1. Normative References 253 [DH] Diffie, W. and M. Hellman, "New Directions in 254 Cryptography", IEEE Transactions on Information Theory, 255 V.IT-22 n.6 , June 1977. 257 [ECDH] SECG, "Elliptic Curve Cryptography", SEC 1 , 2000, 258 . 260 [FIPS186] National Institute of Standards and Technology (NIST), 261 "Digital Signature Standard (DSS)", NIST PUB 186-4 , July 262 2013. 264 [I-D.thomson-http-encryption] 265 Thomson, M., "Encrypted Content-Encoding for HTTP", draft- 266 thomson-http-encryption-01 (work in progress), July 2015. 268 [I-D.thomson-webpush-protocol] 269 Thomson, M., Damaggio, E., and B. Raymor, "Generic Event 270 Delivery Using HTTP Push", draft-thomson-webpush- 271 protocol-00 (work in progress), April 2015. 273 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 274 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 275 RFC2119, March 1997, 276 . 278 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 279 "Randomness Requirements for Security", BCP 106, RFC 4086, 280 DOI 10.17487/RFC4086, June 2005, 281 . 283 [X.692] ANSI, "Public Key Cryptography For The Financial Services 284 Industry: The Elliptic Curve Digital Signature Algorithm 285 (ECDSA)", ANSI X9.62 , 1998. 287 8.2. Informative References 289 [API] Sullivan, B., Fullea, E., and M. van Ouwerkerk, "Web Push 290 API", 2015, . 292 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, DOI 10.17487/ 293 RFC2818, May 2000, 294 . 296 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 297 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 298 . 300 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 301 Protocol (HTTP/1.1): Message Syntax and Routing", RFC 302 7230, DOI 10.17487/RFC7230, June 2014, 303 . 305 Author's Address 307 Martin Thomson 308 Mozilla 310 Email: martin.thomson@gmail.com