idnits 2.17.1 draft-ietf-webpush-protocol-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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 1 character in excess of 72. 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 (November 23, 2015) is 3070 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) == Missing Reference: 'RFCthis' is mentioned on line 1087, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'CAP-URI' == Outdated reference: A later version (-14) exists of draft-ietf-httpbis-alt-svc-09 ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7232 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) Summary: 8 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 WEBPUSH M. Thomson 3 Internet-Draft Mozilla 4 Intended status: Standards Track E. Damaggio 5 Expires: May 26, 2016 B. Raymor, Ed. 6 Microsoft 7 November 23, 2015 9 Generic Event Delivery Using HTTP Push 10 draft-ietf-webpush-protocol-02 12 Abstract 14 A simple protocol for the delivery of realtime events to user agents 15 is described. This scheme uses HTTP/2 server push. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on May 26, 2016. 34 Copyright Notice 36 Copyright (c) 2015 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 3 53 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 2.1. HTTP Resources . . . . . . . . . . . . . . . . . . . . . 6 55 3. Connecting to the Push Service . . . . . . . . . . . . . . . 6 56 4. Subscribing for Push Messages . . . . . . . . . . . . . . . . 7 57 4.1. Correlating Subscriptions . . . . . . . . . . . . . . . . 8 58 5. Subscribing for Push Message Receipts . . . . . . . . . . . . 8 59 6. Requesting Push Message Delivery . . . . . . . . . . . . . . 9 60 6.1. Requesting Push Message Receipts . . . . . . . . . . . . 10 61 6.2. Push Message Time-To-Live . . . . . . . . . . . . . . . . 10 62 7. Receiving Push Messages for a Subscription . . . . . . . . . 11 63 7.1. Receiving Push Messages for a Subscription Set . . . . . 13 64 7.2. Acknowledging Push Messages . . . . . . . . . . . . . . . 15 65 7.3. Receiving Push Message Receipts . . . . . . . . . . . . . 15 66 8. Operational Considerations . . . . . . . . . . . . . . . . . 16 67 8.1. Load Management . . . . . . . . . . . . . . . . . . . . . 16 68 8.2. Push Message Expiration . . . . . . . . . . . . . . . . . 17 69 8.3. Subscription Expiration . . . . . . . . . . . . . . . . . 17 70 8.3.1. Subscription Set Expiration . . . . . . . . . . . . . 18 71 8.4. Implications for Application Reliability . . . . . . . . 18 72 8.5. Subscription Sets and Concurrent HTTP/2 streams . . . . . 18 73 9. Security Considerations . . . . . . . . . . . . . . . . . . . 19 74 9.1. Confidentiality from Push Service Access . . . . . . . . 19 75 9.2. Privacy Considerations . . . . . . . . . . . . . . . . . 19 76 9.3. Authorization . . . . . . . . . . . . . . . . . . . . . . 20 77 9.4. Denial of Service Considerations . . . . . . . . . . . . 21 78 9.5. Logging Risks . . . . . . . . . . . . . . . . . . . . . . 22 79 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 80 10.1. Header Field Registrations . . . . . . . . . . . . . . . 22 81 10.2. Link Relation URNs . . . . . . . . . . . . . . . . . . . 23 82 10.3. Service Name and Port Number Registration . . . . . . . 24 83 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 25 84 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 85 12.1. Normative References . . . . . . . . . . . . . . . . . . 25 86 12.2. Informative References . . . . . . . . . . . . . . . . . 26 87 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 26 88 A.1. Since draft-ietf-webpush-protocol-00 . . . . . . . . . . 26 89 A.2. Since draft-ietf-webpush-protocol-01 . . . . . . . . . . 27 90 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 92 1. Introduction 94 Many applications on mobile and embedded devices require continuous 95 access to network communications so that real-time events - such as 96 incoming calls or messages - can be delivered (or "pushed") in a 97 timely fashion. These devices typically have limited power reserves, 98 so finding more efficient ways to serve application requirements 99 greatly benefits the application ecosystem. 101 One significant contributor to power usage is the radio. Radio 102 communications consume a significant portion of the energy budget on 103 a wireless device. 105 Uncoordinated use of persistent connections or sessions from multiple 106 applications can contribute to unnecessary use of the device radio, 107 since each independent session independently incurs overheads. In 108 particular, keep alive traffic used to ensure that middleboxes do not 109 prematurely time out sessions, can result in significant waste. 110 Maintenance traffic tends to dominate over the long term, since 111 events are relatively rare. 113 Consolidating all real-time events into a single session ensures more 114 efficient use of network and radio resources. A single service 115 consolidates all events, distributing those events to applications as 116 they arrive. This requires just one session, avoiding duplicated 117 overhead costs. 119 The W3C Web Push API [API] describes an API that enables the use of a 120 consolidated push service from web applications. This expands on 121 that work by describing a protocol that can be used to: 123 o request the delivery of a push message to a user agent, 125 o create new push message delivery subscriptions, and 127 o monitor for new push messages. 129 Requesting the delivery of events is particularly important for the 130 Web Push API. The subscription, management and monitoring functions 131 are currently fulfilled by proprietary protocols; these are adequate, 132 but do not offer any of the advantages that standardization affords. 134 This document intentionally does not describe how a push service is 135 discovered. Discovery of push services is left for future efforts, 136 if it turns out to be necessary at all. User agents are expected to 137 be configured with a URL for a push service. 139 1.1. Conventions and Terminology 141 In cases where normative language needs to be emphasized, this 142 document falls back on established shorthands for expressing 143 interoperability requirements on implementations: the capitalized 144 words "MUST", "MUST NOT", "SHOULD" and "MAY". The meaning of these 145 is described in [RFC2119]. 147 This document defines the following terms: 149 application: Both the sender and ultimate consumer of push messages. 150 Many applications have components that are run on a user agent and 151 other components that run on servers. 153 application server: The component of an application that runs on a 154 server and requests the delivery of a push message. 156 push message subscription: A message delivery context that is 157 established between the user agent and the push service and shared 158 with the application server. All push messages are associated 159 with a push message subscription. 161 push message subscription set: A message delivery context that is 162 established between the user agent and the push service that 163 collects multiple push message subscriptions into a set. 165 push message: A message sent from an application server to a user 166 agent via a push service. 168 push message receipt: A message delivery confirmation sent from the 169 push service to the application server. 171 push service: A service that delivers push messages to user agents. 173 user agent: A device and software that is the recipient of push 174 messages. 176 Examples in this document use the HTTP/1.1 message format [RFC7230]. 177 Many of the exchanges can be completed using HTTP/1.1, where HTTP/2 178 is necessary, the more verbose frame format from [RFC7540] is used. 180 2. Overview 182 A general model for push services includes three basic actors: a user 183 agent, a push service, and an application (server). 185 +-------+ +--------------+ +-------------+ 186 | UA | | Push Service | | Application | 187 +-------+ +--------------+ +-------------+ 188 | | | 189 | Subscribe | | 190 |--------------------->| | 191 | Monitor | | 192 |<====================>| | 193 | | | 194 | Distribute Push Resource | 195 |-------------------------------------------->| 196 | | | 197 : : : 198 | | Push Message | 199 | Push Message |<---------------------| 200 |<---------------------| | 201 | | | 203 At the very beginning of the process, a new message subscription is 204 created by the user agent and then distributed to its application 205 server. This subscription is the basis of all future interactions 206 between the actors. 208 To offer more control for authorization, a message subscription is 209 modeled as two resources with different capabilities: 211 o A subscription resource is used to receive messages from a 212 subscription and to delete a subscription. It is private to the 213 user agent. 215 o A push resource is used to send messages to a subscription. It is 216 public and shared by the user agent with its application server. 218 It is expected that a unique subscription will be distributed to each 219 application; however, there are no inherent cardinality constraints 220 in the protocol. Multiple subscriptions might be created for the 221 same application, or multiple applications could use the same 222 subscription. Note however that sharing subscriptions has security 223 and privacy implications. 225 Subscriptions have a limited lifetime. They can also be terminated 226 by either the push service or user agent at any time. User agents 227 and application servers must be prepared to manage changes in 228 subscription state. 230 2.1. HTTP Resources 232 This protocol uses HTTP resources [RFC7230] and link relations 233 [RFC5988]. The following resources are defined: 235 push service: This resource is used to create push message 236 subscriptions (see Section 4). A URL for the push service is 237 configured into user agents. 239 push message subscription: This resource provides read and delete 240 access for a message subscription. A user agent receives push 241 messages (Section 7) using a push message subscription. Every 242 push message subscription has exactly one push resource associated 243 with it. 245 push message subscription set: This resource provides read and 246 delete access for a collection of push message subscriptions. A 247 user agent receives push messages (Section 7.1) for all the push 248 message subscriptions in the set. A link relation of type 249 "urn:ietf:params:push:set" identifies a push message subscription 250 set. 252 push: A push resource is used by the application server to request 253 the delivery of a push message (see Section 6). A link relation 254 of type "urn:ietf:params:push" is used to identify a push 255 resource. 257 push message: A push message resource is created to identify push 258 messages that have been accepted by the push service. The push 259 message resource is also used to acknowledge receipt of a push 260 message. 262 receipt subscribe: A receipt subscribe resource is used by an 263 application server to create a receipt subscription (see 264 Section 5). A link relation of type 265 "urn:ietf:params:push:receipt" is used to identity a receipt 266 subscribe resource. 268 receipt subscription: An application server receives delivery 269 confirmations (Section 6.1) for push messages using a receipt 270 subscription. 272 3. Connecting to the Push Service 274 The push service shares the same default port number (443/TCP) with 275 HTTPS, but MAY also advertise the IANA allocated TCP System Port 1001 276 using HTTP alternative services [I-D.ietf-httpbis-alt-svc]: 278 While the default port (443) offers broad reachability 279 characteristics, it is most often used for web browsing scenarios 280 with a lower idle timeout than other ports configured in middleboxes. 281 For webpush scenarios, this would contribute to unnecessary radio 282 communications to maintain the connection on battery-powered devices. 284 Advertising the alternate port (1001) allows middleboxes to optimize 285 idle timeouts for connections specific to push scenarios with the 286 expectation that data exchange will be infrequent. 288 Middleboxes SHOULD comply with REQ-5 in [RFC5382] which requires that 289 "the value of the 'established connection idle-timeout' MUST NOT be 290 less than 2 hours 4 minutes". 292 4. Subscribing for Push Messages 294 A user agent sends a POST request to its configured push service 295 resource to create a new subscription. 297 POST /subscribe/ HTTP/1.1 298 Host: push.example.net 300 A response with a 201 (Created) status code includes a URI for a new 301 push message subscription resource in the Location header field. 303 The push service MUST provide a URI for the push resource 304 corresponding to the push message subscription using a link relation 305 of type "urn:ietf:params:push". 307 The push service MUST provide a URI for a receipt subscribe resource 308 in a link relation of type "urn:ietf:params:push:receipt". 310 An application-specific method is used to distribute the push and 311 receipt subscribe URIs to the application server. Confidentiality 312 protection and application server authentication MUST be used to 313 ensure that these URIs are not disclosed to unauthorized recipients 314 (see Section 9.3). 316 The push service MAY provide a URI for a subscription set resource in 317 a link relation of type "urn:ietf:params:push:set". If provided, the 318 push service supports subscription sets. If available, the user 319 agent SHOULD use the subscription set to receive push messages rather 320 than individual push message subscriptions. 322 The push service MAY return new subscription sets in response to 323 different subscription requests from the same user agent. This 324 allows the push service to control the grouping of the push message 325 subscriptions. 327 HTTP/1.1 201 Created 328 Date: Thu, 11 Dec 2014 23:56:52 GMT 329 Link:

; 330 rel="urn:ietf:params:push" 331 Link: ; 332 rel="urn:ietf:params:push:receipt" 333 Link: ; 334 rel="urn:ietf:params:push:set" 335 Location: https://push.example.net/s/LBhhw0OohO-Wl4Oi971UGsB7sdQGUibx 337 4.1. Correlating Subscriptions 339 PENDING: Discuss how two different subscriptions are correlated based 340 on either authentication or connection 342 5. Subscribing for Push Message Receipts 344 An application server requests the creation of a receipt subscription 345 by sending a HTTP POST request to the receipt subscribe resource 346 distributed to the application server by a user agent. 348 POST /receipts/xjTG79I3VuptNWS0DsFu4ihT97aE6UQJ HTTP/1.1 349 Host: push.example.net 351 A successful response with a 201 (Created) status code includes a URI 352 for the receipt subscription resource in the Location header field. 354 HTTP/1.1 201 Created 355 Date: Thu, 11 Dec 2014 23:56:52 GMT 356 Location: https://push.example.net/r/3ZtI4YVNBnUUZhuoChl6omUvG4ZM9mpN 358 An application server that sends push messages to a large population 359 of user agents incurs a significant load if it has to monitor a 360 receipt subscription for each user agent. Reuse of receipt 361 subscriptions is critical in reducing load on application servers. A 362 receipt subscription can be used for all resources that have the same 363 receipt subscribe URI. 365 A push service SHOULD provide the same receipt subscribe URI to all 366 user agents. Application servers SHOULD reuse receipt subscription 367 URIs if the receipt subscribe URI provided with the push resource is 368 identical to the one used to create the receipt subscription. 369 Checking that the receipt subscribe URI is identical allows the 370 application server to avoid creating unnecessary receipt 371 subscriptions. 373 6. Requesting Push Message Delivery 375 An application server requests the delivery of a push message by 376 sending a HTTP request to a push resource distributed to the 377 application server by a user agent. The push message is included in 378 the body of the request. 380 POST /p/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV HTTP/1.1 381 Host: push.example.net 382 Push-Receipt: https://push.example.net/r/3ZtI4YVNBnUUZhuoChl6omUvG4ZM9mpN 383 Content-Type: text/plain;charset=utf8 384 Content-Length: 36 386 iChYuI3jMzt3ir20P8r_jgRR-dSuN182x7iB 388 A 201 (Created) response indicates that the push message was 389 accepted. A URI for the push message resource that was created in 390 response to the request is included in the Location header field. 391 This does not indicate that the message was delivered to the user 392 agent. 394 HTTP/1.1 201 Created 395 Date: Thu, 11 Dec 2014 23:56:55 GMT 396 Location: https://push.example.net/d/qDIYHNcfAIPP_5ITvURr-d6BGtYnTRnk 398 A push service MAY return a 429 (Too Many Requests) status code 399 [RFC6585] when an application server has exceeded its rate limit for 400 push message delivery to a push resource. The push service SHOULD 401 also include a Retry-After header [RFC7231] to indicate how long the 402 application server is requested to wait before it makes another 403 request to the push resource. 405 A push service MAY return a 413 (Payload Too Large) status code 406 [RFC7231] in response to requests that include an entity body that is 407 too large. Push services MUST NOT return a 413 status code in 408 responses to an entity body that is 4k (4096 bytes) or less in size. 410 6.1. Requesting Push Message Receipts 412 An application server can use the Push-Receipt header field to 413 request a confirmation from the push service when a push message is 414 delivered and acknowledged by the user agent. The Push-Receipt 415 header field is a URI-Reference as defined in Section 2.7 of 416 [RFC7230]. 418 Push-Receipt = URI-reference 420 The application sets the Push-Receipt header field value to a receipt 421 subscription URI. This receipt subscription resource MUST be created 422 from the same receipt subscribe resource which was returned with the 423 push message subscription response (see Section 4). 425 6.2. Push Message Time-To-Live 427 A push service can improve the reliability of push message delivery 428 considerably by storing push messages for a period. User agents are 429 often only intermittently connected, and so benefit from having short 430 term message storage at the push service. 432 Delaying delivery might also be used to batch communication with the 433 user agent, thereby conserving radio resources. 435 Some push messages are not useful once a certain period of time 436 elapses. Delivery of messages after they have ceased to be relevant 437 is wasteful. For example, if the push message contains a call 438 notification, receiving a message after the caller has abandoned the 439 call is of no value; the application at the user agent is forced to 440 suppress the message so that it does not generate a useless alert. 442 An application server can use the TTL header field to limit the time 443 that a push message is retained by a push service. The TTL header 444 field contains a value in seconds that describes how long a push 445 message is retained by the push service. 447 TTL = 1*DIGIT 449 Once the Time-To-Live (TTL) period elapses, the push service MUST NOT 450 attempt to deliver the push message to the user agent. A push 451 service might adjust the TTL value to account for time accounting 452 errors in processing. For instance, distributing a push message 453 within a server cluster might accrue errors due to clock skew or 454 propagation delays. 456 A push service is not obligated to account for time spent by the 457 application server in sending a push message to the push service, or 458 delays incurred while sending a push message to the user agent. An 459 application server needs to account for transit delays in selecting a 460 TTL header field value. 462 Absence of the TTL header field is interpreted as equivalent to a 463 zero value. A Push message with a zero TTL is immediately delivered 464 if the user agent is available to receive the message. After 465 delivery, the push service is permitted to immediately remove a push 466 message with a zero TTL. This might occur before the user agent 467 acknowledges receipt of the message by performing a HTTP DELETE on 468 the push message resource. Consequently, an application server 469 cannot rely on receiving acknowledgement receipts for zero TTL push 470 messages. 472 If the user agent is unavailable, a push message with a zero TTL 473 expires and is never delivered. 475 A push service MAY choose to retain a push message for a shorter 476 duration than that requested. It indicates this by including a TTL 477 header field in the response that includes the actual TTL. This TTL 478 value MUST be less than or equal to the value provided by the 479 application server. 481 7. Receiving Push Messages for a Subscription 483 A user agent requests the delivery of new push messages by making a 484 GET request to a push message subscription resource. The push 485 service does not respond to this request, it instead uses HTTP/2 486 server push [RFC7540] to send the contents of push messages as they 487 are sent by application servers. 489 Each push message is pushed as the response to a synthesized GET 490 request in a PUSH_PROMISE. This GET request is made to the push 491 message resource that was created by the push service when the 492 application server requested message delivery. The response headers 493 SHOULD provide a URI for the push resource corresponding to the push 494 message subscription in a link relation of type 495 "urn:ietf:params:push". The response body is the entity body from 496 the most recent request sent to the push resource by the application 497 server. 499 The following example request is made over HTTP/2. 501 HEADERS [stream 7] +END_STREAM +END_HEADERS 502 :method = GET 503 :path = /s/LBhhw0OohO-Wl4Oi971UGsB7sdQGUibx 504 :authority = push.example.net 506 The push service permits the request to remain outstanding. When a 507 push message is sent by an application server, a server push is 508 associated with the initial request. The response includes the push 509 message. 511 PUSH_PROMISE [stream 7; promised stream 4] +END_HEADERS 512 :method = GET 513 :path = /d/qDIYHNcfAIPP_5ITvURr-d6BGtYnTRnk 514 :authority = push.example.net 516 HEADERS [stream 4] +END_HEADERS 517 :status = 200 518 date = Thu, 11 Dec 2014 23:56:56 GMT 519 last-modified = Thu, 11 Dec 2014 23:56:55 GMT 520 cache-control = private 521 :link =

; 522 rel="urn:ietf:params:push" 523 content-type = text/plain;charset=utf8 524 content-length = 36 526 DATA [stream 4] +END_STREAM 527 iChYuI3jMzt3ir20P8r_jgRR-dSuN182x7iB 529 The push service response for the GET request to the push message 530 subscription resource SHOULD provide a URI for the receipt subscribe 531 resource in a link relation of type "urn:ietf:params:push:receipt". 533 HEADERS [stream 7] +END_STREAM +END_HEADERS 534 :status = 200 535 :link = ; 536 rel="urn:ietf:params:push:receipt" 538 A user agent can also request the contents of the push message 539 subscription resource immediately by including a Prefer header field 540 [RFC7240] with a "wait" parameter set to "0". In response to this 541 request, the push service MUST generate a server push for all push 542 messages that have not yet been delivered. 544 A 204 (No Content) status code with no associated server pushes 545 indicates that no messages are presently available. This could be 546 because push messages have expired. 548 7.1. Receiving Push Messages for a Subscription Set 550 There are minor differences between receiving push messages for a 551 subscription and a subscripion set. 553 A user agent requests the delivery of new push messages for a 554 collection of push message subscriptions by making a GET request to a 555 push message subscription set resource. The push service does not 556 respond to this request, it instead uses HTTP/2 server push [RFC7540] 557 to send the contents of push messages as they are sent by application 558 servers. 560 Each push message is pushed as the response to a synthesized GET 561 request sent in a PUSH_PROMISE. This GET request is made to the push 562 message resource that was created by the push service when the 563 application server requested message delivery. The synthetic request 564 MUST provide a URI for the push resource corresponding to the push 565 message subscription in a link relation of type 566 "urn:ietf:params:push". This enables the user agent to differentiate 567 the source of the message. The response body is the entity body from 568 the most recent request sent to the push resource by an application 569 server. 571 The following example request is made over HTTP/2. 573 HEADERS [stream 7] +END_STREAM +END_HEADERS 574 :method = GET 575 :path = /set/4UXwi2Rd7jGS7gp5cuutF8ZldnEuvbOy 576 :authority = push.example.net 578 The push service permits the request to remain outstanding. When a 579 push message is sent by an application server, a server push is 580 associated with the initial request. The response includes the push 581 message. 583 PUSH_PROMISE [stream 7; promised stream 4] +END_HEADERS 584 :method = GET 585 :path = /d/qDIYHNcfAIPP_5ITvURr-d6BGtYnTRnk 586 :authority = push.example.net 587 :link =

; 588 rel="urn:ietf:params:push" 590 HEADERS [stream 4] +END_HEADERS 591 :status = 200 592 date = Thu, 11 Dec 2014 23:56:56 GMT 593 last-modified = Thu, 11 Dec 2014 23:56:55 GMT 594 cache-control = private 595 content-type = text/plain;charset=utf8 596 content-length = 36 598 DATA [stream 4] +END_STREAM 599 iChYuI3jMzt3ir20P8r_jgRR-dSuN182x7iB 601 The push service response for the GET request to the push message 602 subscription set resource SHOULD provide a URI for the receipt 603 subscribe resource in a link relation of type 604 "urn:ietf:params:push:receipt". 606 HEADERS [stream 7] +END_STREAM +END_HEADERS 607 :status = 200 608 :link = ; 609 rel="urn:ietf:params:push:receipt" 611 A user agent can request the contents of the push message 612 subscription set resource immediately by including a Prefer header 613 field [RFC7240] with a "wait" parameter set to "0". In response to 614 this request, the push service MUST generate a server push for all 615 push messages that have not yet been delivered. 617 A 204 (No Content) status code with no associated server pushes 618 indicates that no messages are presently available. This could be 619 because push messages have expired. 621 7.2. Acknowledging Push Messages 623 To ensure that a push message is properly delivered to the user agent 624 at least once, the user agent MUST acknowledge receipt of the message 625 by performing a HTTP DELETE on the push message resource. 627 DELETE /d/qDIYHNcfAIPP_5ITvURr-d6BGtYnTRnk HTTP/1.1 628 Host: push.example.net 630 If the push service receives the acknowledgement and the application 631 has requested a delivery receipt, the push service MUST deliver a 632 success response to the application server monitoring the receipt 633 subscription resource. 635 If the push service does not receive the acknowledgement within a 636 reasonable amount of time, then the message is considered to be not 637 yet delivered. The push service SHOULD continue to retry delivery of 638 the message until its advertised expiration. 640 The push service MAY cease to retry delivery of the message prior to 641 its advertised expiration due to scenarios such as an unresponsive 642 user agent or operational constraints. If the application has 643 requested a delivery receipt, then the push service MUST push a 644 failure response with a status code of 410 (Gone) to the application 645 server monitoring the receipt subscription resource. 647 7.3. Receiving Push Message Receipts 649 The application server requests the delivery of receipts from the 650 push service by making a HTTP GET request to the receipt subscription 651 resource. The push service does not respond to this request, it 652 instead uses HTTP/2 server push [RFC7540] to send push receipts when 653 messages are acknowledged (Section 7.2) by the user agent. 655 Each receipt is pushed as the response to a synthesized GET request 656 sent in a PUSH_PROMISE. This GET request is made to the same push 657 message resource that was created by the push service when the 658 application server requested message delivery. A successful response 659 includes a 204 (No Content) status code with no data. 661 The following example request is made over HTTP/2. 663 HEADERS [stream 13] +END_STREAM +END_HEADERS 664 :method = GET 665 :path = /r/3ZtI4YVNBnUUZhuoChl6omUvG4ZM9mpN 666 :authority = push.example.net 668 The push service permits the request to remain outstanding. When the 669 user agent acknowledges the message, the push service pushes a 670 delivery receipt to the application server. A 204 (No Content) 671 status code confirms that the message was delivered and acknowledged. 673 PUSH_PROMISE [stream 13; promised stream 82] +END_HEADERS 674 :method = GET 675 :path = /d/qDIYHNcfAIPP_5ITvURr-d6BGtYnTRnk 676 :authority = push.example.net 678 HEADERS [stream 82] +END_STREAM 679 +END_HEADERS 680 :status = 204 681 date = Thu, 11 Dec 2014 23:56:56 GMT 683 If the user agent fails to acknowledge the receipt of the push 684 message and the push service ceases to retry delivery of the message 685 prior to its advertised expiration, then the push service MUST push a 686 failure response with a status code of 410 (Gone). 688 8. Operational Considerations 690 8.1. Load Management 692 A push service is likely to have to maintain a very large number of 693 open TCP connections. Effective management of those connections can 694 depend on being able to move connections between server instances. 696 A user agent MUST support the 307 (Temporary Redirect) status code 697 [RFC7231], which can be used by a push service to redistribute load 698 at the time that a new subscription is requested. 700 A server that wishes to redistribute load can do so using alternative 701 services [I-D.ietf-httpbis-alt-svc]. Alternative services allows for 702 redistribution of load whilst maintaining the same URIs for various 703 resources. User agents can ensure a graceful transition by using the 704 GOAWAY frame once it has established a replacement connection. 706 8.2. Push Message Expiration 708 Storage of push messages based on the TTL header field comprises a 709 potentially significant amount of storage for a push service. A push 710 service is not obligated to store messages indefinitely. A push 711 service is able to indicate how long it intends to retain a message 712 to an application server using the TTL header field (see 713 Section 6.2). 715 A user agent that does not actively monitor for push messages will 716 not receive messages that expire during that interval. 718 Push messages that are stored and not delivered to a user agent are 719 delivered when the user agent recommences monitoring. Stored push 720 messages SHOULD include a Last-Modified header field (see Section 2.2 721 of [RFC7232]) indicating when delivery was requested by an 722 application server. 724 A GET request to a push message subscription resource that has only 725 expired messages results in response as though no push message were 726 ever sent. 728 Push services might need to limit the size and number of stored push 729 messages to avoid overloading. To limit the size of messages, the 730 push service MAY return the 413 (Payload Too Large) status code for 731 messages that are too large. To limit the number of stored push 732 messages, the push service MAY either expire messages prior to their 733 advertised Time-To-Live or reduce their advertised Time-To-Live. 735 8.3. Subscription Expiration 737 In some cases, it may be necessary to terminate subscriptions so that 738 they can be refreshed. This applies to both push message 739 subscriptions and receipt subscriptions. 741 A push service can remove a subscription at any time. If a user 742 agent or application server has an outstanding request to a 743 subscription resource (see Section 7), this can be signaled by 744 returning a 400-series status code, such as 410 (Gone). 746 A user agent or application server can request that a subscription be 747 removed by sending a DELETE request to the push message subscription 748 or receipt subscription URI. 750 A push service MUST return a 400-series status code, such as 404 (Not 751 Found) or 410 (Gone) if an application server attempts to send a push 752 message to a removed or expired push message subscription. 754 8.3.1. Subscription Set Expiration 756 A push service MAY expire a subscription set at any time which MUST 757 also expire all push message subscriptions in the set. If a user 758 agent has an outstanding request to a push subscription set (see 759 Section 7.1) this can be signaled by returning a 400-series status 760 code, such as 410 (Gone). 762 A user agent can request that a subscription set be removed by 763 sending a DELETE request to the subscription set URI. This MUST also 764 remove all push message subscriptions in the set. 766 If a specific push message subscription that is a member of a 767 subscription set is expired or removed, then it MUST also be removed 768 from its subscription set. 770 8.4. Implications for Application Reliability 772 A push service that does not support reliable delivery over 773 intermittent network connections or failing applications on devices, 774 forces the device to acknowledge receipt directly to the application 775 server, incurring additional power drain in order to establish 776 (usually secure) connections to the individual application servers. 778 Push message reliability can be important if messages contain 779 information critical to the state of an application. Repairing state 780 can be costly, particularly for devices with limited communications 781 capacity. Knowing that a push message has been correctly received 782 avoids costly retransmissions, polling and state resynchronization. 784 The availability of push message delivery receipts ensures that the 785 application developer is not tempted to create alternative mechanisms 786 for message delivery in case the push service fails to deliver a 787 critical message. Setting up a polling mechanism or a backup 788 messaging channel in order to compensate for these shortcomings 789 negates almost all of the advantages a push service provides. 791 However, reliability might not be necessary for messages that are 792 transient (e.g. an incoming call) or messages that are quickly 793 superceded (e.g. the current number of unread emails). 795 8.5. Subscription Sets and Concurrent HTTP/2 streams 797 If the push service requires that the user agent use push message 798 subscription sets, then it MAY limit the number of concurrently 799 active streams with the SETTINGS_MAX_CONCURRENT_STREAMS parameter 800 within a HTTP/2 SETTINGS frame [RFC7540]. The user agent MAY be 801 limited to one concurrent stream to manage push message subscriptions 802 and one concurrent stream for each subscription set returned by the 803 push service. This could force the user agent to serialize 804 subscription requests to the push service. 806 9. Security Considerations 808 This protocol MUST use HTTP over TLS [RFC2818]. This includes any 809 communications between user agent and push service, plus 810 communications between the application and the push service. All 811 URIs therefore use the "https" scheme. This provides confidentiality 812 and integrity protection for subscriptions and push messages from 813 external parties. 815 9.1. Confidentiality from Push Service Access 817 The protection afforded by TLS does not protect content from the push 818 service. Without additional safeguards, a push service is able to 819 see and modify the content of the messages. 821 Applications are able to provide additional confidentiality, 822 integrity or authentication mechanisms within the push message 823 itself. The application server sending the push message and the 824 application on the user agent that receives it are frequently just 825 different instances of the same application, so no standardized 826 protocol is needed to establish a proper security context. The 827 process of providing the application server with subscription 828 information provides a convenient medium for key agreement. 830 The Web Push API codifies this practice by requiring that each push 831 subscription created by the browser be bound to a browser generated 832 encryption key. Pushed messages are authenticated and decrypted by 833 the browser before delivery to applications. This scheme ensures 834 that the push service is unable to examine the contents of push 835 messages. 837 The public key for a subscription ensures that applications using 838 that subscription can identify messages from unknown sources and 839 discard them. This depends on the public key only being disclosed to 840 entities that are authorized to send messages on the channel. The 841 push service does not require access to this public key. 843 9.2. Privacy Considerations 845 Push message confidentiality does not ensure that the identity of who 846 is communicating and when they are communicating is protected. 847 However, the amount of information that is exposed can be limited. 849 The URIs provided for push resources MUST NOT provide any basis to 850 correlate communications for a given user agent. It MUST NOT be 851 possible to correlate any two push resource URIs based solely on 852 their contents. This allows a user agent to control correlation 853 across different applications, or over time. 855 Similarly, the URIs provided by the push service to identify a push 856 message MUST NOT provide any information that allows for correlation 857 across subscriptions. Push message URIs for the same subscription 858 MAY contain information that would allow correlation with the 859 associated subscription or other push messages for that subscription. 861 User and device information MUST NOT be exposed through a push or 862 push message URI. 864 In addition, push URIs established by the same user agent or push 865 message URIs for the same subscription MUST NOT include any 866 information that allows them to be correlated with the user agent. 868 Note: This need not be perfect as long as the resulting anonymity 869 set (see [RFC6973], Section 6.1.1) is sufficiently large. A push 870 URI necessarily identifies a push service or a single server 871 instance. It is also possible that traffic analysis could be used 872 to correlate subscriptions. 874 A user agent MUST be able to create new subscriptions with new 875 identifiers at any time. 877 9.3. Authorization 879 This protocol does not define how a push service establishes whether 880 a user agent is permitted to create a subscription, or whether push 881 messages can be delivered to the user agent. A push service MAY 882 choose to authorize requests based on any HTTP-compatible 883 authorization method available, of which there are numerous options. 884 The authorization process and any associated credentials are expected 885 to be configured in the user agent along with the URI for the push 886 service. 888 Authorization is managed using capability URLs for the push message 889 subscription, push, and receipt subscription resources (see 890 [CAP-URI]). A capability URL grants access to a resource based 891 solely on knowledge of the URL. 893 Capability URLs are used for their "easy onward sharing" and "easy 894 client API" properties. These make it possible to avoid relying on 895 relationships between push services and application servers, with the 896 protocols necessary to build and support those relationships. 898 Capability URLs act as bearer tokens. Knowledge of a push message 899 subscription URI implies authorization to either receive push 900 messages or delete the subscription. Knowledge of a push URI implies 901 authorization to send push messages. Knowledge of a push message URI 902 allows for reading and acknowledging that specific message. 903 Knowledge of a receipt subscription URI implies authorization to 904 receive push receipts. Knowledge of a receipt subscribe URI implies 905 authorization to create subscriptions for receipts. 907 Note that the same receipt subscribe URI could be returned for 908 multiple push message subscriptions. Using the same value for a 909 large number of subscriptions allows application servers to reuse 910 receipt subscriptions, which can provide a significant efficiency 911 advantage. A push service that uses a common receipt subscribe URI 912 loses control over the creation of receipt subscriptions. This can 913 result in a potential exposure to denial of service; stateless 914 resource creation can be used to mitigate the effects of this 915 exposure. 917 Encoding a large amount of random entropy (at least 120 bits) in the 918 path component ensures that it is difficult to successfully guess a 919 valid capability URL. 921 9.4. Denial of Service Considerations 923 Discarding unwanted messages at the user agent based on message 924 authentication doesn't protect against a denial of service attack on 925 the user agent. Even a relatively small volume of push messages can 926 cause battery-powered devices to exhaust power reserves. 928 An application can limit where valid push messages can originate by 929 limiting the distribution of push URIs to authorized entities. 930 Ensuring that push URIs are hard to guess ensures that only 931 application servers that have been given a push URI can use it. 933 A malicious application with a valid push URI could use the greater 934 resources of a push service to mount a denial of service attack on a 935 user agent. Push services SHOULD limit the rate at which push 936 messages are sent to individual user agents. A push service or user 937 agent MAY terminate subscriptions (Section 8.3) that receive too many 938 push messages. 940 End-to-end confidentiality mechanisms, such as those in [API], 941 prevent an entity with a valid push message subscription URI from 942 learning the contents of push messages. Push messages that are not 943 successfully authenticated will not be delivered by the API, but this 944 can present a denial of service risk. 946 Conversely, a push service is also able to deny service to user 947 agents. Intentional failure to deliver messages is difficult to 948 distinguish from faults, which might occur due to transient network 949 errors, interruptions in user agent availability, or genuine service 950 outages. 952 9.5. Logging Risks 954 Server request logs can reveal subscription-related URIs. Acquiring 955 a push message subscription URI enables the receipt of messages or 956 deletion of the subscription. Acquiring a push URI permits the 957 sending of push messages. Logging could also reveal relationships 958 between different subscription-related URIs for the same user agent. 959 Encrypted message contents are not revealed to the push service. 961 Limitations on log retention and strong access control mechanisms can 962 ensure that URIs are not learned by unauthorized entities. 964 10. IANA Considerations 966 This protocol defines new HTTP header fields in Section 10.1. New 967 link relation types are identified using the URNs defined in 968 Section 10.2. Port registration is defined in Section 10.3 970 10.1. Header Field Registrations 972 HTTP header fields are registered within the "Message Headers" 973 registry maintained at . 976 This document defines the following HTTP header fields, so their 977 associated registry entries shall be added according to the permanent 978 registrations below (see [RFC3864]): 980 +-------------------+----------+----------+--------------+ 981 | Header Field Name | Protocol | Status | Reference | 982 +-------------------+----------+----------+--------------+ 983 | TTL | http | standard | Section 6.2 | 984 | Push-Receipt | http | standard | Section 6.1 | 985 +-------------------+----------+----------+--------------+ 987 The change controller is: "IETF (iesg@ietf.org) - Internet 988 Engineering Task Force". 990 10.2. Link Relation URNs 992 This document registers URNs for use in identifying link relation 993 types. These are added to a new "Web Push Identifiers" registry 994 according to the procedures in Section 4 of [RFC3553]; the 995 corresponding "push" sub-namespace is entered in the "IETF URN Sub- 996 namespace for Registered Protocol Parameter Identifiers" registry. 998 The "Web Push Identifiers" registry operates under the IETF Review 999 policy [RFC5226]. 1001 Registry name: Web Push Identifiers 1003 URN Prefix: urn:ietf:params:push 1005 Specification: (this document) 1007 Repository: [Editor/IANA note: please include a link to the final 1008 registry location.] 1010 Index value: Values in this registry are URNs or URN prefixes that 1011 start with the prefix "urn:ietf:params:push". Each is registered 1012 independently. 1014 New registrations in the "Web Push Identifiers" are encouraged to 1015 include the following information: 1017 URN: A complete URN or URN prefix. 1019 Description: A summary description. 1021 Specification: A reference to a specification describing the 1022 semantics of the URN or URN prefix. 1024 Contact: Email for the person or group making the registration. 1026 Index value: As described in [RFC3553], URN prefixes that are 1027 registered include a description of how the URN is constructed. 1028 This is not applicable for specific URNs. 1030 These values are entered as the initial content of the "Web Push 1031 Identifiers" registry. 1033 URN: urn:ietf:params:push 1035 Description: This link relation type is used to identify a resource 1036 for sending push messages. 1038 Specification: (this document) 1040 Contact: The Web Push WG (webpush@ietf.org) 1042 URN: urn:ietf:params:push:set 1044 Description: This link relation type is used to identify a 1045 collection of push message subscriptions. 1047 Specification: (this document) 1049 Contact: The Web Push WG (webpush@ietf.org) 1051 URN: urn:ietf:params:push:receipts 1053 Description: This link relation type is used to identify a resource 1054 for creating new push message receipt subscriptions. 1056 Specification: (this document) 1058 Contact: The Web Push WG (webpush@ietf.org) 1060 10.3. Service Name and Port Number Registration 1062 Service names and port numbers are registered within the "Service 1063 Name and Transport Protocol Port Number Registry" maintained at 1064 . 1067 IANA is requested to assign the System Port number 1001 and the 1068 service name "webpush" in accordance with [RFC6335]. 1070 Service Name. 1071 webpush 1073 Transport Protocol. 1074 tcp 1076 Assignee. 1077 IESG (iesg@ietf.org) 1079 Contact. 1080 The Web Push WG (webpush@ietf.org) 1082 Description. 1083 HTTP Web Push 1085 Reference. 1087 [RFCthis] 1089 Port Number. 1090 1001 1092 11. Acknowledgements 1094 Significant technical input to this document has been provided by Ben 1095 Bangert, Kit Cambridge, JR Conlin, Matthew Kaufman, Costin Manolache, 1096 Mark Nottingham, Robert Sparks, Darshak Thakore and many others. 1098 12. References 1100 12.1. Normative References 1102 [CAP-URI] Tennison, J., "Good Practices for Capability URLs", FPWD 1103 capability-urls, February 2014, 1104 . 1106 [I-D.ietf-httpbis-alt-svc] 1107 Nottingham, M., McManus, P., and J. Reschke, "HTTP 1108 Alternative Services", draft-ietf-httpbis-alt-svc-09 (work 1109 in progress), May 2015. 1111 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1112 Requirement Levels", BCP 14, RFC 2119, March 1997. 1114 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1116 [RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An 1117 IETF URN Sub-namespace for Registered Protocol 1118 Parameters", BCP 73, RFC 3553, June 2003. 1120 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 1121 Procedures for Message Header Fields", BCP 90, RFC 3864, 1122 September 2004. 1124 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1125 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1126 May 2008. 1128 [RFC5382] Biswas, K., Ford, B., Sivakumar, S., and P. Srisuresh, 1129 "NAT Behavioral Requirements for TCP", RFC 5382, October 1130 2008. 1132 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 1134 [RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S. 1135 Cheshire, "Internet Assigned Numbers Authority (IANA) 1136 Procedures for the Management of the Service Name and 1137 Transport Protocol Port Number Registry", RFC 6335, August 1138 2011. 1140 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 1141 Codes", RFC 6585, April 2012. 1143 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1144 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 1145 2014. 1147 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1148 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 1150 [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 1151 (HTTP/1.1): Conditional Requests", RFC 7232, June 2014. 1153 [RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240, June 2014. 1155 [RFC7540] Belshe, M., Peon, R., and M. Thomson, "Hypertext Transfer 1156 Protocol Version 2", RFC 7540, May 2015. 1158 12.2. Informative References 1160 [API] Sullivan, B., Fullea, E., and M. van Ouwerkerk, "Web Push 1161 API", ED push-api, February 2015, . 1164 [RFC6973] Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., 1165 Morris, J., Hansen, M., and R. Smith, "Privacy 1166 Considerations for Internet Protocols", RFC 6973, July 1167 2013. 1169 Appendix A. Change Log 1171 [[The RFC Editor is requested to remove this section at 1172 publication.]] 1174 A.1. Since draft-ietf-webpush-protocol-00 1176 Editorial changes for Push Message Time-To-Live 1178 Editorial changes for Push Acknowledgements 1180 Removed subscription expiration based on HTTP cache headers 1182 A.2. Since draft-ietf-webpush-protocol-01 1184 Added Subscription Sets 1186 Added System Port as an alternate service with guidance for idle 1187 timeouts 1189 Finalized status codes for acknowledgements 1191 Editorial changes for Rate Limits 1193 Authors' Addresses 1195 Martin Thomson 1196 Mozilla 1197 331 E Evelyn Street 1198 Mountain View, CA 94041 1199 US 1201 Email: martin.thomson@gmail.com 1203 Elio Damaggio 1204 Microsoft 1205 One Microsoft Way 1206 Redmond, WA 98052 1207 US 1209 Email: elioda@microsoft.com 1211 Brian Raymor (editor) 1212 Microsoft 1213 One Microsoft Way 1214 Redmond, WA 98052 1215 US 1217 Email: brian.raymor@microsoft.com