idnits 2.17.1
draft-ietf-webpush-encryption-03.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 (June 29, 2016) is 2858 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-02
== Outdated reference: A later version (-12) exists of
draft-ietf-webpush-protocol-06
-- 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 June 29, 2016
5 Expires: December 31, 2016
7 Message Encryption for Web Push
8 draft-ietf-webpush-encryption-03
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 December 31, 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 . . . . . . . . . . . . . . . . . . . . . 6
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 4077 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 the
229 Encryption field, and at most one entry having a "dh" parameter in
230 the Crypto-Key field. This allows the "keyid" parameter to be
231 omitted from both header fields.
233 An application server MUST NOT include an "aesgcm128" parameter in
234 the Encryption header field.
236 4. Message Decryption
238 A User Agent decrypts messages are decrypted as described in
239 [I-D.ietf-httpbis-encryption-encoding]. The authentication secret
240 described in Section 3.1 is used in key derivation.
242 Note that the value of the "keyid" parameter is used to identify the
243 correct share, if there are multiple values for the Crypto-Key header
244 field.
246 A receiver is not required to support multiple records. Such a
247 receiver MUST check that the record size is large enough to contain
248 the entire payload body in a single record. The "rs" parameter MUST
249 NOT be exactly equal to the length of the payload body minus the
250 length of the authentication tag (16 octets); that length indicates
251 that the message has been truncated.
253 5. Mandatory Group and Public Key Format
255 User Agents MUST expose an elliptic curve Diffie-Hellman share on the
256 P-256 curve [FIPS186].
258 Public keys, such as are encoded into the "dh" parameter, MUST be in
259 the form of an uncompressed point as described in [X.692] (that is, a
260 65 octet sequence that starts with a 0x04 octet).
262 The label for this curve is the string "P-256" encoded in ASCII (that
263 is, the octet sequence 0x50, 0x2d, 0x32, 0x35, 0x36).
265 6. IANA Considerations
267 This document has no IANA actions.
269 7. Security Considerations
271 The security considerations of [I-D.ietf-httpbis-encryption-encoding]
272 describe the limitations of the content encoding. In particular, any
273 HTTP header fields are not protected by the content encoding scheme.
274 A User Agent MUST consider HTTP header fields to have come from the
275 Push Service. An application on the User Agent that uses information
276 from header fields to alter their processing of a push message is
277 exposed to a risk of attack by the Push Service.
279 The timing and length of communication cannot be hidden from the Push
280 Service. While an outside observer might see individual messages
281 intermixed with each other, the Push Service will see what
282 Application Server is talking to which User Agent, and the
283 subscription that is used. Additionally, the length of messages
284 could be revealed unless the padding provided by the content encoding
285 scheme is used to obscure length.
287 8. References
289 8.1. Normative References
291 [DH] Diffie, W. and M. Hellman, "New Directions in
292 Cryptography", IEEE Transactions on Information Theory,
293 V.IT-22 n.6 , June 1977.
295 [ECDH] SECG, "Elliptic Curve Cryptography", SEC 1 , 2000,
296 .
298 [FIPS186] National Institute of Standards and Technology (NIST),
299 "Digital Signature Standard (DSS)", NIST PUB 186-4 , July
300 2013.
302 [I-D.ietf-httpbis-encryption-encoding]
303 Thomson, M., "Encrypted Content-Encoding for HTTP", draft-
304 ietf-httpbis-encryption-encoding-02 (work in progress),
305 June 2016.
307 [I-D.ietf-webpush-protocol]
308 Thomson, M., Damaggio, E., and B. Raymor, "Generic Event
309 Delivery Using HTTP Push", draft-ietf-webpush-protocol-06
310 (work in progress), June 2016.
312 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
313 Requirement Levels", BCP 14, RFC 2119,
314 DOI 10.17487/RFC2119, March 1997,
315 .
317 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker,
318 "Randomness Requirements for Security", BCP 106, RFC 4086,
319 DOI 10.17487/RFC4086, June 2005,
320 .
322 [X.692] ANSI, "Public Key Cryptography For The Financial Services
323 Industry: The Elliptic Curve Digital Signature Algorithm
324 (ECDSA)", ANSI X9.62 , 1998.
326 8.2. Informative References
328 [API] van Ouwerkerk, M. and M. Thomson, "Web Push API", 2015,
329 .
331 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818,
332 DOI 10.17487/RFC2818, May 2000,
333 .
335 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
336 Protocol (HTTP/1.1): Message Syntax and Routing",
337 RFC 7230, DOI 10.17487/RFC7230, June 2014,
338 .
340 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
341 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
342 2015, .
344 Author's Address
346 Martin Thomson
347 Mozilla
349 Email: martin.thomson@gmail.com