├── .gitignore ├── .travis.yml ├── CONTRIBUTING.md ├── Makefile ├── README.md ├── circle.yml └── draft-ietf-webpush-protocol.xml /.gitignore: -------------------------------------------------------------------------------- 1 | *.redxml 2 | *.txt 3 | *.html 4 | *.pdf 5 | *~ 6 | *.swp 7 | /*-[0-9][0-9].xml 8 | .refcache 9 | venv/ 10 | issues.json 11 | draft-ietf-webpush-protocol.xml 12 | /lib 13 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: python 2 | sudo: false 3 | addons: 4 | apt: 5 | packages: 6 | - python-pip 7 | 8 | install: 9 | - gem install kramdown-rfc2629 10 | - pip install xml2rfc 11 | 12 | script: make ghpages 13 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | Before submitting feedback, please familiarize yourself with our current issues 4 | list and review the [working group 5 | documents](https://datatracker.ietf.org/wg/{WG_NAME}/documents/) and [mailing 6 | list discussion](https://mailarchive.ietf.org/arch/browse/{WG_NAME}/). If you're 7 | new to this, you may also want to read the [Tao of the 8 | IETF](https://www.ietf.org/tao.html). 9 | 10 | Be aware that all contributions to the specification fall under the "NOTE WELL" 11 | terms outlined below. 12 | 13 | 1. The best way to provide feedback (editorial or design) and ask questions is 14 | sending an e-mail to our mailing list 15 | ([info](https://www.ietf.org/mailman/listinfo/{WG_NAME})). This will ensure that 16 | the entire Working Group sees your input in a timely fashion. 17 | 18 | 2. If you have **editorial** suggestions (i.e., those that do not change the 19 | meaning of the specification), you can either: 20 | 21 | a) Fork this repository and submit a pull request; this is the lowest 22 | friction way to get editorial changes in. 23 | 24 | b) Submit a new issue to Github, and mention that you believe it is editorial 25 | in the issue body. It is not necessary to notify the mailing list for 26 | editorial issues. 27 | 28 | c) Make comments on individual commits in Github. Note that this feedback is 29 | processed only with best effort by the editors, so it should only be used for 30 | quick editorial suggestions or questions. 31 | 32 | 3. For non-editorial (i.e., **design**) issues, you can also create an issue on 33 | Github. However, you **must notify the mailing list** when creating such issues, 34 | providing a link to the issue in the message body. 35 | 36 | Note that **github issues are not for substantial discussions**; the only 37 | appropriate place to discuss design issues is on the mailing list itself. 38 | 39 | 40 | ## NOTE WELL 41 | 42 | Any submission to the [IETF](https://www.ietf.org/) intended by the Contributor 43 | for publication as all or part of an IETF Internet-Draft or RFC and any 44 | statement made within the context of an IETF activity is considered an "IETF 45 | Contribution". Such statements include oral statements in IETF sessions, as 46 | well as written and electronic communications made at any time or place, which 47 | are addressed to: 48 | 49 | * The IETF plenary session 50 | * The IESG, or any member thereof on behalf of the IESG 51 | * Any IETF mailing list, including the IETF list itself, any working group 52 | or design team list, or any other list functioning under IETF auspices 53 | * Any IETF working group or portion thereof 54 | * Any Birds of a Feather (BOF) session 55 | * The IAB or any member thereof on behalf of the IAB 56 | * The RFC Editor or the Internet-Drafts function 57 | * All IETF Contributions are subject to the rules of 58 | [RFC 5378](https://tools.ietf.org/html/rfc5378) and 59 | [RFC 3979](https://tools.ietf.org/html/rfc3979) 60 | (updated by [RFC 4879](https://tools.ietf.org/html/rfc4879)). 61 | 62 | Statements made outside of an IETF session, mailing list or other function, 63 | that are clearly not intended to be input to an IETF activity, group or 64 | function, are not IETF Contributions in the context of this notice. 65 | 66 | Please consult [RFC 5378](https://tools.ietf.org/html/rfc5378) and [RFC 67 | 3979](https://tools.ietf.org/html/rfc3979) for details. 68 | 69 | A participant in any IETF activity is deemed to accept all IETF rules of 70 | process, as documented in Best Current Practices RFCs and IESG Statements. 71 | 72 | A participant in any IETF activity acknowledges that written, audio and video 73 | records of meetings may be made and may be available to the public. 74 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | include lib/main.mk 2 | 3 | lib/main.mk: 4 | ifneq (,$(shell git submodule status lib 2>/dev/null)) 5 | git submodule sync 6 | git submodule update --init 7 | else 8 | git clone -q --depth 10 -b master https://github.com/martinthomson/i-d-template.git lib 9 | endif 10 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Web Push Protocol 2 | 3 | This is the Web Push Protocol. This is a product of the [IETF Web Push Working 4 | Group](https://tools.ietf.org/wg/webpush). 5 | 6 | * [Editor's copy](https://webpush-wg.github.io/webpush-protocol/) 7 | * [Working group draft](https://tools.ietf.org/html/draft-ietf-webpush-protocol) ([Datatracker](https://datatracker.ietf.org/doc/draft-ietf-webpush-protocol)) 8 | 9 | ## Contributing 10 | 11 | Before submitting feedback, please familiarize yourself with our current issues 12 | list and review the [working group home 13 | page](https://tools.ietf.org/wg/webpush). If you're new to this, you may also 14 | want to read the [Tao of the IETF](https://www.ietf.org/tao.html). 15 | 16 | Be aware that all contributions to the specification fall under the "NOTE WELL" 17 | terms outlined below. 18 | 19 | 1. The best way to provide feedback (editorial or design) and ask questions is 20 | sending an e-mail to [our mailing 21 | list](https://www.ietf.org/mailman/listinfo/webpush). This will ensure that the 22 | entire Working Group sees your input in a timely fashion. 23 | 24 | 2. If you have **editorial** suggestions (i.e., those that do not change the 25 | meaning of the specification), you can either: 26 | 27 | a) Fork this repository and submit a pull request; this is the lowest 28 | friction way to get editorial changes in. 29 | 30 | b) Submit a new issue to Github, and mention that you believe it is editorial 31 | in the issue body. It is not necessary to notify the mailing list for 32 | editorial issues. 33 | 34 | c) Make comments on individual commits in Github. Note that this feedback is 35 | processed only with best effort by the editors, so it should only be used for 36 | quick editorial suggestions or questions. 37 | 38 | 3. For non-editorial (i.e., **design**) issues, you can also create an issue on 39 | Github. However, you **must notify the mailing list** when creating such issues, 40 | providing a link to the issue in the message body. 41 | 42 | Note that **github issues are not for substantial discussions**; the only 43 | appropriate place to discuss design issues is on the mailing list itself. 44 | 45 | 46 | ## Building the Draft 47 | 48 | Formatted text and HTML versions of the draft can be built using `make`. 49 | 50 | ```sh 51 | $ make 52 | ``` 53 | 54 | This requires that you have the necessary software installed. There are several 55 | other tools that are enabled by make, check the Makefile for details, including 56 | links to the software those tools might require. 57 | 58 | 59 | ## Installation and Setup 60 | 61 | Mac users will need to install 62 | [XCode](https://itunes.apple.com/us/app/xcode/id497799835) to get `make`, see 63 | [this answer](http://stackoverflow.com/a/11494872/1375574) for instructions. 64 | Some of the makefile targets need GNU make 4.0, which Apple doesn't ship yet; 65 | sorry, but if you want those, you can 66 | [download](https://www.gnu.org/software/make/) and build a copy for yourself. 67 | 68 | Windows users will need to use [Cygwin](http://cygwin.org/) to get `make`. 69 | 70 | All systems require [xml2rfc](http://xml2rfc.ietf.org/). This requires [Python 71 | 2.7](https://www.python.org/). The easiest way to get `xml2rfc` is with `pip`. 72 | 73 | Using a `virtualenv`: 74 | 75 | ```sh 76 | $ virtualenv --no-site-packages venv 77 | # remember also to activate the virtualenv before any 'make' run 78 | $ source venv/bin/activate 79 | $ pip install xml2rfc 80 | ``` 81 | 82 | To your local user account: 83 | 84 | ```sh 85 | $ pip install --user xml2rfc 86 | ``` 87 | 88 | Or globally: 89 | 90 | ```sh 91 | $ sudo pip install xml2rfc 92 | ``` 93 | 94 | xml2rfc depends on development versions of [libxml2](http://xmlsoft.org/) and 95 | [libxslt1](http://xmlsoft.org/XSLT). These packages are named `libxml2-dev` and 96 | `libxslt1-dev` (Debian, Ubuntu) or `libxml2-devel` and `libxslt1-devel` (RedHat, 97 | Fedora). 98 | 99 | If you use markdown, you will also need to install `kramdown-xml2rfc`, which 100 | requires Ruby and can be installed using the roby package manager, `gem`: 101 | 102 | ```sh 103 | $ gem install kramdown-xml2rfc 104 | ``` 105 | 106 | 107 | ## NOTE WELL 108 | 109 | Any submission to the [IETF](https://www.ietf.org/) intended by the Contributor 110 | for publication as all or part of an IETF Internet-Draft or RFC and any 111 | statement made within the context of an IETF activity is considered an "IETF 112 | Contribution". Such statements include oral statements in IETF sessions, as 113 | well as written and electronic communications made at any time or place, which 114 | are addressed to: 115 | 116 | * The IETF plenary session 117 | * The IESG, or any member thereof on behalf of the IESG 118 | * Any IETF mailing list, including the IETF list itself, any working group 119 | or design team list, or any other list functioning under IETF auspices 120 | * Any IETF working group or portion thereof 121 | * Any Birds of a Feather (BOF) session 122 | * The IAB or any member thereof on behalf of the IAB 123 | * The RFC Editor or the Internet-Drafts function 124 | * All IETF Contributions are subject to the rules of 125 | [RFC 5378](https://tools.ietf.org/html/rfc5378) and 126 | [RFC 3979](https://tools.ietf.org/html/rfc3979) 127 | (updated by [RFC 4879](https://tools.ietf.org/html/rfc4879)). 128 | 129 | Statements made outside of an IETF session, mailing list or other function, 130 | that are clearly not intended to be input to an IETF activity, group or 131 | function, are not IETF Contributions in the context of this notice. 132 | 133 | Please consult [RFC 5378](https://tools.ietf.org/html/rfc5378) and [RFC 134 | 3979](https://tools.ietf.org/html/rfc3979) for details. 135 | 136 | A participant in any IETF activity is deemed to accept all IETF rules of 137 | process, as documented in Best Current Practices RFCs and IESG Statements. 138 | 139 | A participant in any IETF activity acknowledges that written, audio and video 140 | records of meetings may be made and may be available to the public. 141 | -------------------------------------------------------------------------------- /circle.yml: -------------------------------------------------------------------------------- 1 | machine: 2 | python: 3 | version: 2.7.11 4 | ruby: 5 | version: 2.3.1 6 | 7 | checkout: 8 | post: 9 | - git fetch origin gh-pages --depth 10 10 | 11 | dependencies: 12 | pre: 13 | - pip install xml2rfc 14 | - gem install kramdown-rfc2629 15 | 16 | test: 17 | override: 18 | - make 19 | 20 | deployment: 21 | production: 22 | branch: /.*/ 23 | commands: 24 | - make ghpages 25 | -------------------------------------------------------------------------------- /draft-ietf-webpush-protocol.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | Generic Event Delivery Using HTTP Push 17 | 18 | 19 | 20 | Mozilla 21 |
22 | 23 | 331 E Evelyn Street 24 | Mountain View 25 | CA 26 | 94041 27 | US 28 | 29 | martin.thomson@gmail.com 30 |
31 | 32 | 33 | 34 | Microsoft 35 |
36 | 37 | One Microsoft Way 38 | Redmond 39 | WA 40 | 98052 41 | US 42 | 43 | elioda@microsoft.com 44 |
45 | 46 | 47 | 48 | Microsoft 49 |
50 | 51 | One Microsoft Way 52 | Redmond 53 | WA 54 | 98052 55 | US 56 | 57 | brian.raymor@microsoft.com 58 |
59 | 60 | 61 | 62 | RAI 63 | WEBPUSH 64 | Internet-Draft 65 | HTTP 66 | HTTP2 67 | Push 68 | WebPush 69 | 70 | 71 | 72 | A simple protocol for the delivery of real-time events to user agents is 73 | described. This scheme uses HTTP/2 server push. 74 | 75 | 76 | 77 | 78 | 79 |
80 | 81 | Many applications on mobile and embedded devices require continuous 82 | access to network communications so that real-time events - such as 83 | incoming calls or messages - can be delivered (or "pushed") in a timely 84 | fashion. These devices typically have limited power reserves, so finding 85 | more efficient ways to serve application requirements greatly benefits 86 | the application ecosystem. 87 | 88 | 89 | One significant contributor to power usage is the radio. Radio 90 | communications consume a significant portion of the energy budget 91 | on a wireless device. 92 | 93 | 94 | Uncoordinated use of persistent connections or sessions from multiple 95 | applications can contribute to unnecessary use of the device radio, 96 | since each independent session can incur its own overhead. In 97 | particular, keep alive traffic used to ensure that middleboxes do not 98 | prematurely time out sessions, can result in significant waste. 99 | Maintenance traffic tends to dominate over the long term, since events 100 | are relatively rare. 101 | 102 | 103 | Consolidating all real-time events into a single session ensures more 104 | efficient use of network and radio resources. A single service 105 | consolidates all events, distributing those events to applications as 106 | they arrive. This requires just one session, avoiding duplicated 107 | overhead costs. 108 | 109 | 110 | The W3C Push API describes an API that 111 | enables the use of a consolidated push service from web applications. 112 | This document expands on that work by describing a protocol that can be used to: 113 | 114 | 115 | request the delivery of a push message to a user agent, 116 | 117 | 118 | create new push message delivery subscriptions, and 119 | 120 | 121 | monitor for new push messages. 122 | 123 | 124 | 125 | 126 | A standardized method of event delivery is particularly important for 127 | the W3C Push API, where application servers might need to use multiple 128 | push services. The subscription, management and monitoring functions 129 | are currently fulfilled by proprietary protocols; these are adequate, 130 | but do not offer any of the advantages that standardization affords. 131 | 132 | 133 | This document intentionally does not describe how a push service is 134 | discovered. Discovery of push services is left for future efforts, if 135 | it turns out to be necessary at all. User agents are expected to be 136 | configured with a URL for a push service. 137 | 138 | 139 |
140 | 141 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 142 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 143 | document are to be interpreted as described in . 144 | 145 | 146 | This document defines the following terms: 147 | 148 | 149 | Both the sender and ultimate consumer of push messages. Many 150 | applications have components that are run on a user agent and 151 | other components that run on servers. 152 | 153 | 154 | The component of an application that usually runs on a server and 155 | requests the delivery of a push message. 156 | 157 | 158 | A message delivery context that is established between the user 159 | agent and the push service and shared with the application server. 160 | All push messages are associated with a push message subscription. 161 | 162 | 163 | A message delivery context that is established between the user 164 | agent and the push service that collects multiple push message 165 | subscriptions into a set. 166 | 167 | 168 | A message sent from an application server to a user agent via a 169 | push service. 170 | 171 | 172 | A message delivery confirmation sent from the push service to the 173 | application server. 174 | 175 | 176 | A service that delivers push messages to user agents. 177 | 178 | 179 | A device and software that is the recipient of push messages. 180 | 181 | 182 | 183 | 184 | Examples in this document use the HTTP/1.1 185 | message format. Many of the exchanges can be completed using 186 | HTTP/1.1: 187 | 188 | 189 | 190 | Subscribing for Push Messages 191 | 192 | 193 | Requesting Push Message Delivery 194 | 195 | 196 | Replacing Push Messages 197 | 198 | 199 | Acknowledging Push Messages 200 | 201 | 202 | 203 | When an example depends on HTTP/2 server push, the more verbose frame format 204 | from is used: 205 | 206 | 207 | 208 | Receiving Push Messages for a Subscription 209 | 210 | 211 | Receiving Push Messages for a Subscription Set 212 | 213 | 214 | Receiving Push Message Receipts 215 | 216 | 217 | 218 | 219 | All examples use HTTPS over the default port (443) rather than the registered port 220 | (WEBPUSH-PORT). A push service deployment might prefer this configuration to maximize 221 | chances for user agents to reach the service. A push service might use HTTP alternative 222 | services to redirect a user agent to the registered port (WEBPUSH-PORT) to gain the benefits of the 223 | standardized HTTPS port without sacrificing reachability (see ). 224 | This would only be apparent in the examples through the inclusion of the Alt-Used header 225 | field in requests from the user agent to the push service. 226 | 227 | 228 | Examples do not include specific methods for push message encryption 229 | or application server authentication because the protocol does not define 230 | a mandatory system. The examples in Voluntary Application Server Identification 231 | and Message Encryption for WebPush 232 | demonstrate the approach adopted by the W3C Push API for 233 | its requirements. 234 | 235 |
236 |
237 | 238 |
239 | 240 | A general model for push services includes three basic actors: a user 241 | agent, a push service, and an application (server). 242 | 243 |
244 | | | 251 | | Monitor | | 252 | |<====================>| | 253 | | | | 254 | | Distribute Push Resource | 255 | |-------------------------------------------->| 256 | | | | 257 | : : : 258 | | | Push Message | 259 | | Push Message |<---------------------| 260 | |<---------------------| | 261 | | | | 262 | ]]> 263 |
264 | 265 | At the very beginning of the process, a new message subscription is 266 | created by the user agent and then distributed to its application 267 | server. This subscription is the basis of all future interactions between 268 | the actors. A subscription is used by the application server to send messages to 269 | the push service for being delivered to the user agent. It is used by 270 | the user agent to monitor the push service for any incoming message. 271 | 272 | 273 | To offer more control for authorization, a message subscription is 274 | modeled as two resources with different capabilities: 275 | 276 | 277 | A subscription resource is used to receive messages from a 278 | subscription and to delete a subscription. It is private to the user 279 | agent. 280 | 281 | 282 | A push resource is used to send messages to a subscription. It is 283 | public and shared by the user agent with its application server. 284 | 285 | 286 | 287 | 288 | It is expected that a unique subscription will be distributed to each 289 | application; however, there are no inherent cardinality constraints in 290 | the protocol. Multiple subscriptions might be created for the same 291 | application, or multiple applications could use the same subscription. 292 | Note however that sharing subscriptions has security and privacy 293 | implications. 294 | 295 | 296 | Subscriptions have a limited lifetime. They can also be terminated by 297 | either the push service or user agent at any time. User agents and 298 | application servers must be prepared to manage changes in subscription 299 | state. 300 | 301 | 302 |
303 | 304 | This protocol uses HTTP resources and 305 | link relations. The following resources 306 | are defined: 307 | 308 | 309 | This resource is used to create push message subscriptions 310 | (). A URL for the push 311 | service is configured into user agents. 312 | 313 | 314 | This resource provides read and delete access for a message 315 | subscription. A user agent receives push 316 | messages using a push message subscription. Every push 317 | message subscription has exactly one push resource associated with 318 | it. 319 | 320 | 321 | This resource provides read and delete access for a collection of push 322 | message subscriptions. A user agent receives 323 | push messages for all the push message subscriptions in the set. A 324 | link relation of type "urn:ietf:params:push:set" identifies a push message 325 | subscription set. 326 | 327 | 328 | An application server requests the delivery of a 329 | push message using a push resource. A link relation of type "urn:ietf:params:push" 330 | identifies a push resource. 331 | 332 | 333 | The push service creates a push message resource to identify push messages that 334 | have been accepted for delivery. The push message 335 | resource is also deleted by the user agent to 336 | acknowledge receipt of a push message. 337 | 338 | 339 | An application server receives 340 | delivery confirmations for push messages using a receipt 341 | subscription. A link relation of type "urn:ietf:params:push:receipt" 342 | identifies a receipt subscription. 343 | 344 | 345 | 346 |
347 |
348 |
349 | 350 | The push service MUST use HTTP over TLS [RFC2818] following the recommendations in [RFC7525]. 351 | The push service shares the same default port number (443/TCP) with HTTPS, but MAY 352 | also advertise the IANA allocated TCP System Port (WEBPUSH-PORT) using HTTP alternative services 353 | . 354 | 355 | 356 | While the default port (443) offers broad reachability characteristics, it is most 357 | often used for web browsing scenarios with a lower idle timeout than other ports 358 | configured in middleboxes. For webpush scenarios, this would contribute to unnecessary 359 | radio communications to maintain the connection on battery-powered devices. 360 | 361 | 362 | Advertising the alternate port (WEBPUSH-PORT) allows middleboxes to optimize idle timeouts 363 | for connections specific to push scenarios with the expectation that data exchange will be 364 | infrequent. 365 | 366 | 367 | Middleboxes SHOULD comply with REQ-5 in which requires that 368 | "the value of the 'established connection idle-timeout' MUST NOT be less than 369 | 2 hours 4 minutes". 370 | 371 |
372 |
373 | 374 | A user agent sends a POST request to its configured push service 375 | resource to create a new subscription. 376 | 377 |
378 | 383 |
384 | 385 | A 201 (Created) response indicates that the push subscription was 386 | created. A URI for the push message subscription resource that was 387 | created in response to the request MUST be returned in the Location 388 | header field. 389 | 390 | 391 | The push service MUST provide a URI for the push resource corresponding 392 | to the push message subscription in a link relation of type 393 | "urn:ietf:params:push". 394 | 395 | 396 | An application-specific method is used to distribute the push URI to the 397 | application server. Confidentiality protection and application server 398 | authentication MUST be used to ensure that this URI is not disclosed 399 | to unauthorized recipients (). 400 | 401 |
402 | 403 | ; 407 | rel="urn:ietf:params:push" 408 | Link: ; 409 | rel="urn:ietf:params:push:set" 410 | Location: https://push.example.net/subscription/LBhhw0OohO-Wl4Oi971UG 411 | 412 | ]]> 413 |
414 |
415 | 416 | Collecting multiple push message subscriptions into a subscription set 417 | can represent a significant efficiency improvement for push services 418 | and user agents. The push service MAY provide a URI for a subscription 419 | set resource in a link relation of type "urn:ietf:params:push:set". 420 | 421 | 422 | When a subscription set is returned in a push message subscription 423 | response, the user agent SHOULD include this subscription set in a link 424 | relation of type "urn:ietf:params:push:set" in subsequent requests to 425 | create new push message subscriptions. 426 | 427 | 428 | A user agent MAY omit the subscription set if it is unable to receive 429 | push messages in an aggregated way for the lifetime of the subscription. 430 | This might be necessary if the user agent is monitoring subscriptions on 431 | behalf of other push message receivers. 432 | 433 |
434 | 435 | ; 439 | rel="urn:ietf:params:push:set" 440 | ]]> 441 |
442 | 443 | The push service SHOULD return the same subscription set in its response, although 444 | it MAY return a new subscription set if it is unable to reuse the one provided 445 | by the user agent. 446 | 447 |
448 | 449 | ; 453 | rel="urn:ietf:params:push" 454 | Link: ; 455 | rel="urn:ietf:params:push:set" 456 | Location: https://push.example.net/subscription/i-nQ3A9Zm4kgSWg8_ZijV 457 | ]]> 458 |
459 | 460 | A push service MUST return a 400 (Bad Request) status code for requests which 461 | contain an invalid subscription set. A push service MAY return a 429 462 | (Too Many Requests) status code to reject requests 463 | which omit a subscription set. 464 | 465 | 466 | How a push service detects that requests originate from the same user agent 467 | is implementation-specific but could take ambient information into 468 | consideration, such as the TLS connection, source IP address and port. 469 | Implementers are reminded that some heuristics can produce false 470 | positives and cause requests to be rejected incorrectly. 471 | 472 |
473 |
474 | 475 |
476 | 477 | An application server requests the delivery of a push message by sending 478 | a HTTP POST request to a push resource distributed to the application 479 | server by a user agent. The content of the push message is included 480 | in the body of the request. 481 | 482 |
483 | 484 | 493 |
494 |
495 | 496 | A 201 (Created) response indicates that the push message was accepted. 497 | A URI for the push message resource that was created in response to 498 | the request MUST be returned in the Location header field. This does not 499 | indicate that the message was delivered to the user agent. 500 | 501 | 506 |
507 | 508 |
509 | 510 | An application server can include the Prefer header 511 | field with the "respond-async" preference to request confirmation 512 | from the push service when a push message is delivered and then acknowledged 513 | by the user agent. The push service MUST support delivery confirmations. 514 | 515 |
516 | 517 | 527 | 528 |
529 |
530 | 531 | When the push service accepts the message for delivery with confirmation, it MUST 532 | return a 202 (Accepted) response. A URI for the push message resource that was 533 | created in response to the request MUST be returned in the Location header field. 534 | The push service MUST also provide a URI for the receipt subscription resource in 535 | a link relation of type "urn:ietf:params:push:receipt". 536 | 537 | 538 | ; 542 | rel="urn:ietf:params:push:receipt" 543 | Location: https://push.example.net/message/qDIYHNcfAIPP_5ITvURr-d6BGt 544 | ]]> 545 | 546 |
547 | 548 | For subsequent receipt requests to the same origin , 549 | the application server SHOULD include the returned receipt subscription in 550 | a link relation of type "urn:ietf:params:push:receipt". This gives the push 551 | service an option to aggregate the receipts. The push service SHOULD return 552 | the same receipt subscription in its response, although it MAY return a new 553 | receipt subscription if it is unable to reuse the one provided by the application 554 | server. 555 | 556 | 557 | An application server MAY omit the receipt subscription if it is 558 | unable to receive receipts in an aggregated way for the lifetime of 559 | the receipt subscription. This might be necessary if the application 560 | server is monitoring receipt subscriptions on the behalf of other 561 | push message senders. 562 | 563 | 564 | A push service MUST return a 400 (Bad Request) status code for requests which contain 565 | an invalid receipt subscription. If a push service wishes to limit the number of 566 | receipt subscriptions that it maintains, it MAY return a 429 (Too Many Requests) 567 | status code to reject receipt requests which omit a receipt 568 | subscription. 569 | 570 |
571 | 572 |
573 | 574 | A push service can improve the reliability of push message delivery 575 | considerably by storing push messages for a period. User agents are 576 | often only intermittently connected, and so benefit from having short 577 | term message storage at the push service. 578 | 579 | 580 | Delaying delivery might also be used to batch communication with the 581 | user agent, thereby conserving radio resources. 582 | 583 | 584 | Some push messages are not useful once a certain period of time 585 | elapses. Delivery of messages after they have ceased to be relevant 586 | is wasteful. For example, if the push message contains a call 587 | notification, receiving a message after the caller has abandoned the 588 | call is of no value; the application at the user agent is forced to 589 | suppress the message so that it does not generate a useless alert. 590 | 591 | 592 | An application server MUST include the TTL (Time-To-Live) header field in 593 | its request for push message delivery. The TTL header field contains a value 594 | in seconds that suggests how long a push message is retained by the push service. 595 | 596 |
597 | 598 | The TTL rule specifies a non-negative integer, representing time in seconds. 599 | A recipient parsing and converting a TTL value to binary form SHOULD use an 600 | arithmetic type of at least 31 bits of non-negative integer range. If a recipient 601 | receives a TTL value greater than the greatest integer it can represent, or if any 602 | of its subsequent calculations overflows, it MUST consider the value to be 2147483648 (2^31). 603 | 604 | 607 |
608 | 609 | A push service MUST return a 400 (Bad Request) status code in response to 610 | requests that omit the TTL header field. 611 | 612 | 613 | A push service MAY retain a push message for a shorter duration than requested. 614 | It indicates this by returning a TTL header field in its response with the actual 615 | TTL. This TTL value MUST be less than or equal to the value provided by the 616 | application server. 617 | 618 | 619 | Once the TTL period elapses, the push service MUST NOT attempt to deliver the push 620 | message to the user agent. A push service might adjust the TTL value to account for 621 | time accounting errors in processing. For instance, distributing a push message 622 | within a server cluster might accrue errors due to clock skew or propagation delays. 623 | 624 | 625 | A push service is not obligated to account for time spent by the 626 | application server in sending a push message to the push service, or 627 | delays incurred while sending a push message to the user agent. An 628 | application server needs to account for transit delays in selecting a 629 | TTL header field value. 630 | 631 | 632 | A Push message with a zero TTL is immediately delivered if the user agent is 633 | available to receive the message. After delivery, the push service is permitted 634 | to immediately remove a push message with a zero TTL. This might occur before the 635 | user agent acknowledges receipt of the message by performing a HTTP DELETE on the 636 | push message resource. Consequently, an application server cannot rely on receiving 637 | acknowledgement receipts for zero TTL push messages. 638 | 639 | 640 | If the user agent is unavailable, a push message with a zero TTL expires and 641 | is never delivered. 642 | 643 | 644 |
645 | 646 |
647 | 648 | For a device that is battery-powered, it is often critical that it remains 649 | dormant for extended periods. Radio communication in particular consumes 650 | significant power and limits the length of time that the device can operate. 651 | 652 | 653 | To avoid consuming resources to receive trivial messages, it is helpful 654 | if an application server can communicate the urgency of a message and if the 655 | user agent can request that the push server only forward messages of a specific 656 | urgency. 657 | 658 | 659 | An application server MAY include an Urgency header field in its 660 | request for push message delivery. This header field indicates the 661 | message urgency. The push service MUST NOT forward the Urgency header 662 | field to the user agent. A push message without the Urgency header 663 | field defaults to a value of "normal". 664 | 665 | 666 | A user agent MAY include the Urgency header field when monitoring for 667 | push messages to indicate the lowest urgency of push messages that it 668 | is willing to receive. A push service MUST NOT deliver push messages 669 | with lower urgency than the value indicated by the user agent in its 670 | monitoring request. Push messages of any urgency are delivered to a 671 | user agent that does not include an Urgency header field when 672 | monitoring for messages. 673 | 674 |
675 | 676 | 680 | 681 |
682 | 683 | 684 | In order of increasing urgency: 685 | 686 | Urgency 687 | Device State 688 | Example Application Scenario 689 | very-low 690 | On power and wifi 691 | Advertisements 692 | low 693 | On either power or wifi 694 | Topic updates 695 | normal 696 | On neither power nor wifi 697 | Chat or Calendar Message 698 | high 699 | Low battery 700 | Incoming phone call or time-sensitive alert 701 | 702 | 703 | Multiple values for the Urgency header 704 | field MUST NOT be included in requests; otherwise, the push service 705 | MUST return a 400 (Bad Request) status code. 706 | 707 |
708 | 709 |
710 | 711 | A push message that has been stored by the push service can be 712 | replaced with new content. If the user agent is offline during the 713 | time that the push messages are sent, updating a push message avoids 714 | the situation where outdated or redundant messages are sent to the 715 | user agent. 716 | 717 | 718 | Only push messages that have been assigned a topic can be replaced. A 719 | push message with a topic replaces any outstanding push message with 720 | an identical topic. 721 | 722 | 723 | A push message topic is a string carried in a Topic header field. 724 | A topic is used to correlate push messages sent to the same subscription and 725 | does not convey any other semantics. 726 | 727 | 728 | The grammar for the Topic header field uses the token rule defined in . 730 | 731 |
732 | 733 | 736 | 737 |
738 | 739 | For use with this protocol, the Topic header field MUST be restricted 740 | to no more than 32 characters from the URL and filename safe Base 64 741 | alphabet . A push service that receives a request 742 | with a Topic header field that does not meet these constraints MUST return 743 | a 400 (Bad Request) status code to the application server. 744 | 745 | 746 | A push message replacement request creates a new push message resource 747 | and simultaneously deletes any existing message resource that has a 748 | matching topic. If an attempt was made to deliver the deleted push 749 | message, an acknowledgment could arrive at the push service after the 750 | push message has been replaced. Delivery receipts for such deleted 751 | messages SHOULD be suppressed. 752 | 753 | 754 | The replacement request also replaces the stored TTL, Urgency, and any 755 | receipt subscription associated with the previous message in the 756 | matching topic. 757 | 758 | 759 | A push message with a topic that is not shared by an outstanding 760 | message to the same subscription is stored or delivered as normal. 761 | 762 |
763 | 764 | For example, the following message could cause an existing message 765 | to be replaced: 766 | 767 | 777 |
778 |
779 | 780 | If the push service identifies an outstanding push message with a 781 | topic of "upd", then that message resource is deleted. A 201 782 | (Created) response indicates that the push message replacement was 783 | accepted. A URI for the new push message resource that was created 784 | in response to the request is included in the Location header field. 785 | 786 | 791 |
792 | 793 | The value of the Topic header field MUST NOT be forwarded to user 794 | agents. Its value is neither encrypted nor authenticated. 795 | 796 |
797 |
798 | 799 |
800 | 801 | A user agent requests the delivery of new push messages by making a GET 802 | request to a push message subscription resource. The push service does 803 | not respond to this request, it instead uses HTTP/2 server push to send the 805 | contents of push messages as they are sent by application servers. 806 | 807 | 808 | A user agent MAY include a Urgency header field in its request. The push service MUST 809 | NOT deliver messages with lower urgency than the value of the header field 810 | as defined in the . 811 | 812 | 813 | Each push message is pushed as the response to a synthesized GET request 814 | sent in a PUSH_PROMISE. This GET request is made to the push message resource 815 | that was created by the push service when the application server requested 816 | message delivery. The response headers SHOULD provide a URI for the push 817 | resource corresponding to the push message subscription in a link relation 818 | of type "urn:ietf:params:push". The response body is the entity body from 819 | the most recent request sent to the push resource by the application server. 820 | 821 | 822 |
823 | 824 | The following example request is made over HTTP/2. 825 | 826 | 832 |
833 | 834 |
835 | 836 | The push service permits the request to remain outstanding. When a 837 | push message is sent by an application server, a server push is generated 838 | in association with the initial request. The response for the server push includes the push 839 | message. 840 | 841 | 842 | ; 854 | rel="urn:ietf:params:push" 855 | content-type = text/plain;charset=utf8 856 | content-length = 36 857 | 858 | DATA [stream 4] +END_STREAM 859 | iChYuI3jMzt3ir20P8r_jgRR-dSuN182x7iB 860 | 861 | HEADERS [stream 7] +END_STREAM +END_HEADERS 862 | :status = 200 863 | ]]> 864 | 865 |
866 | 867 | A user agent can also request the contents of the push message subscription 868 | resource immediately by including a Prefer header 869 | field with a "wait" preference set to "0". In response to this request, 870 | the push service MUST generate a server push for all push messages that have not yet 871 | been delivered. 872 | 873 | 874 | A 204 (No Content) status code with no associated server pushes 875 | indicates that no messages are presently available. This could be 876 | because push messages have expired. 877 | 878 |
879 | 880 | There are minor differences between receiving push messages for a subscription and 881 | a subscription set. If a subscription set is available, the user agent SHOULD use the 882 | subscription set to monitor for push messages rather than individual push message 883 | subscriptions. 884 | 885 | 886 | A user agent requests the delivery of new push messages for a collection of 887 | push message subscriptions by making a GET request to a push message subscription 888 | set resource. The push service does not respond to this request, it instead uses 889 | HTTP/2 server push to send the contents of push 890 | messages as they are sent by application servers. 891 | 892 | 893 | A user agent MAY include a Urgency header field in its request. The push service MUST 894 | NOT deliver messages with lower urgency than the value of the header field 895 | as defined in the . 896 | 897 | 898 | Each push message is pushed as the response to a synthesized GET request 899 | sent in a PUSH_PROMISE. This GET request is made to the push message resource 900 | that was created by the push service when the application server requested 901 | message delivery. The synthetic request MUST provide a URI for the push resource 902 | corresponding to the push message subscription in a link relation of type 903 | "urn:ietf:params:push". This enables the user agent to differentiate the source 904 | of the message. The response body is the entity body from the most recent request 905 | sent to the push resource by an application server. 906 | 907 | 908 |
909 | 910 | The following example request is made over HTTP/2. 911 | 912 | 913 | 919 | 920 |
921 | 922 |
923 | 924 | The push service permits the request to remain outstanding. When a 925 | push message is sent by an application server, a server push is 926 | generated in association with the initial request. The server push's response includes the push 927 | message. 928 | 929 | 930 | ; 941 | rel="urn:ietf:params:push" 942 | cache-control = private 943 | content-type = text/plain;charset=utf8 944 | content-length = 36 945 | 946 | DATA [stream 4] +END_STREAM 947 | iChYuI3jMzt3ir20P8r_jgRR-dSuN182x7iB 948 | 949 | HEADERS [stream 7] +END_STREAM +END_HEADERS 950 | :status = 200 951 | ]]> 952 | 953 |
954 | 955 | A user agent can request the contents of the push message subscription 956 | set resource immediately by including a Prefer header 957 | field with a "wait" preference set to "0". In response to this request, 958 | the push service MUST generate a server push for all push messages that have not 959 | yet been delivered. 960 | 961 | 962 | A 204 (No Content) status code with no associated server pushes 963 | indicates that no messages are presently available. This could be 964 | because push messages have expired. 965 | 966 |
967 | 968 |
970 | 971 | To ensure that a push message is properly delivered to the user agent 972 | at least once, the user agent MUST acknowledge receipt of the message 973 | by performing a HTTP DELETE on the push message resource. 974 | 975 |
976 | 977 | 981 | 982 |
983 | 984 | If the push service receives the acknowledgement and the application 985 | has requested a delivery receipt, the push service MUST return a 204 (No Content) 986 | response to the application server monitoring the receipt subscription. 987 | 988 | 989 | If the push service does not receive the acknowledgement within a 990 | reasonable amount of time, then the message is considered to be not yet 991 | delivered. The push service SHOULD continue to retry delivery of the message 992 | until its advertised expiration. 993 | 994 | 995 | The push service MAY cease to retry delivery of the message prior to its 996 | advertised expiration due to scenarios such as an unresponsive user agent or 997 | operational constraints. If the application has requested a delivery receipt, 998 | then the push service MUST return a 410 (Gone) response to the application server 999 | monitoring the receipt subscription. 1000 | 1001 |
1002 | 1003 |
1004 | 1005 | The application server requests the delivery of receipts from the push 1006 | service by making a HTTP GET request to the receipt subscription 1007 | resource. The push service does not respond to this request, it 1008 | instead uses HTTP/2 server push to send push 1009 | receipts when messages are acknowledged () 1010 | by the user agent. 1011 | 1012 | 1013 | Each receipt is pushed as the response to a synthesized GET request sent in a 1014 | PUSH_PROMISE. This GET request is made to the same push message resource that 1015 | was created by the push service when the application server requested message 1016 | delivery. The response includes a status code indicating the result of the message delivery and carries no data. 1017 | 1018 |
1019 | 1020 | The following example request is made over HTTP/2. 1021 | 1022 | 1023 | 1029 | 1030 |
1031 |
1032 | 1033 | The push service permits the request to remain outstanding. When 1034 | the user agent acknowledges the message, the push service pushes a 1035 | delivery receipt to the application server. A 204 (No Content) status code 1036 | confirms that the message was delivered and acknowledged. 1037 | 1038 | 1039 | 1050 | 1051 |
1052 | 1053 | If the user agent fails to acknowledge the receipt of the push message and 1054 | the push service ceases to retry delivery of the message prior to its advertised 1055 | expiration, then the push service MUST push a failure response with a status code 1056 | of 410 (Gone). 1057 | 1058 |
1059 |
1060 | 1061 |
1062 |
1063 | 1064 | A push service is likely to have to maintain a very large number of open 1065 | TCP connections. Effective management of those connections can depend 1066 | on being able to move connections between server instances. 1067 | 1068 | 1069 | A user agent MUST support the 307 (Temporary Redirect) status code 1070 | , which can be used by a push service to 1071 | redistribute load at the time that a new subscription is requested. 1072 | 1073 | 1074 | A server that wishes to redistribute load can do so using HTTP alternative 1075 | services . HTTP alternative 1076 | services allows for redistribution of load while maintaining the same 1077 | URIs for various resources. A user agent can ensure a graceful 1078 | transition by using the GOAWAY frame once it has established a 1079 | replacement connection. 1080 | 1081 |
1082 | 1083 |
1084 | 1085 | Storage of push messages based on the TTL header field comprises a 1086 | potentially significant amount of storage for a push service. A push 1087 | service is not obligated to store messages indefinitely. A push 1088 | service is able to indicate how long it intends to retain a message to 1089 | an application server using the TTL header field (). 1091 | 1092 | 1093 | A user agent that does not actively monitor for push messages will not 1094 | receive messages that expire during that interval. 1095 | 1096 | 1097 | Push messages that are stored and have not been delivered to a user agent are 1098 | delivered when the user agent recommences monitoring. Stored push 1099 | messages SHOULD include a Last-Modified header field (Section 2.2 1100 | of ) indicating when delivery was requested by 1101 | an application server. 1102 | 1103 | 1104 | A GET request to a push message subscription resource with only 1105 | expired messages results in a response as though no push message was 1106 | ever sent. 1107 | 1108 | 1109 | Push services might need to limit the size and number of stored push 1110 | messages to avoid overloading. To limit the size of messages, the 1111 | push service MAY return a 413 (Payload Too Large) status code 1112 | in response to requests that include an entity body that is too large. 1113 | Push services MUST NOT return a 413 status code in responses to an entity 1114 | body that is 4096 bytes or less in size. 1115 | 1116 | 1117 | To limit the number of stored push messages, the push service MAY respond with a shorter 1118 | Time-To-Live than proposed by the application server in its request for push message delivery 1119 | (). Once a message has been accepted, the push service MAY later expire 1120 | the message prior to its advertised Time-To-Live. If the application server requested a 1121 | delivery receipt, the push service MUST return a failure response (). 1122 | 1123 |
1124 | 1125 |
1126 | 1127 | In some cases, it may be necessary to terminate subscriptions so that 1128 | they can be refreshed. This applies to both push message 1129 | subscriptions and receipt subscriptions. 1130 | 1131 | 1132 | A push service MAY expire a subscription at any time. If there are outstanding 1133 | requests to an expired push message subscription resource () 1134 | from a user agent or to an expired receipt subscription resource () 1135 | from an application server, this MUST be signaled by returning a 404 (Not Found) status code. 1136 | 1137 | 1138 | A push service MUST return a 404 (Not Found) status code if an application server 1139 | attempts to send a push message to an expired push message subscription. 1140 | 1141 | 1142 | A user agent can remove its push message subscription by sending a DELETE request to 1143 | the corresponding URI. An application server can remove its receipt subscription by 1144 | sending a DELETE request to the corresponding URI. 1145 | 1146 |
1147 | 1148 | A push service MAY expire a subscription set at any time and MUST also 1149 | expire all push message subscriptions in the set. If a user agent has an 1150 | outstanding request to a push subscription set () 1151 | this MUST be signaled by returning a 404 (Not Found) status code. 1152 | 1153 | 1154 | A user agent can request that a subscription set be removed by sending a DELETE 1155 | request to the subscription set URI. This MUST also remove all push message 1156 | subscriptions in the set. 1157 | 1158 | 1159 | If a specific push message subscription that is a member of a subscription set is 1160 | expired or removed, then it MUST also be removed from its subscription set. 1161 | 1162 |
1163 |
1164 | 1165 |
1166 | 1167 | A push service that does not support reliable delivery over 1168 | intermittent network connections or failing applications on devices, 1169 | forces the device to acknowledge receipt directly to the application 1170 | server, incurring additional power drain in order to establish and maintain 1171 | (usually secure) connections to the individual application servers. 1172 | 1173 | 1174 | Push message reliability can be important if messages contain 1175 | information critical to the state of an application. Repairing state 1176 | can be expensive, particularly for devices with limited communications 1177 | capacity. Knowing that a push message has been correctly received 1178 | avoids retransmissions, polling, and state resynchronization. 1179 | 1180 | 1181 | The availability of push message delivery receipts ensures that the 1182 | application developer is not tempted to create alternative mechanisms 1183 | for message delivery in case the push service fails to deliver a 1184 | critical message. Setting up a polling mechanism or a backup messaging 1185 | channel in order to compensate for these shortcomings negates almost 1186 | all of the advantages a push service provides. 1187 | 1188 | 1189 | However, reliability might not be necessary for messages that are 1190 | transient (e.g. an incoming call) or messages that are quickly 1191 | superceded (e.g. the current number of unread emails). 1192 | 1193 |
1194 |
1195 | 1196 | If the push service requires that the user agent use push message subscription sets, 1197 | then it MAY limit the number of concurrently active streams with the 1198 | SETTINGS_MAX_CONCURRENT_STREAMS parameter within a HTTP/2 SETTINGS frame . 1199 | The user agent MAY be limited to one concurrent stream to manage push message 1200 | subscriptions and one concurrent stream for each subscription set returned by the push service. 1201 | This could force the user agent to serialize subscription requests to the push 1202 | service. 1203 | 1204 |
1205 |
1206 | 1207 |
1208 | 1209 | This protocol MUST use HTTP over TLS 1210 | following the recommendations in . This 1211 | includes any communications between user agent and push service, plus 1212 | communications between the application server and the push service. All URIs 1213 | therefore use the "https" scheme. This provides confidentiality and 1214 | integrity protection for subscriptions and push messages from external 1215 | parties. 1216 | 1217 | 1218 |
1219 | 1220 | The protection afforded by TLS does not protect content from the push 1221 | service. Without additional safeguards, a push service can inspect 1222 | and modify the message content. 1223 | 1224 | 1225 | Applications using this protocol MUST use mechanisms that provide 1226 | end-to-end confidentiality, integrity and data origin authentication. 1227 | The application server sending the push message and the application on 1228 | the user agent that receives it are frequently just different 1229 | instances of the same application, so no standardized protocol is 1230 | needed to establish a proper security context. The distribution of 1231 | subscription information from the user agent to its application server 1232 | also offers a convenient medium for key agreement. 1233 | 1234 | 1235 | For this requirement, the W3C Push API has adopted 1236 | Message Encryption for WebPush 1237 | to secure the content of messages from the push service. Other scenarios can 1238 | be addressed by similar policies. 1239 | 1240 | 1241 | The Topic header field exposes information that allows more granular 1242 | correlation of push messages on the same subject. This might be used 1243 | to aid traffic analysis of push messages by the push service. 1244 | 1245 |
1246 | 1247 |
1248 | 1249 | Push message confidentiality does not ensure that the identity of who 1250 | is communicating and when they are communicating is protected. 1251 | However, the amount of information that is exposed can be limited. 1252 | 1253 | 1254 | The URIs provided for push resources MUST NOT provide any basis to 1255 | correlate communications for a given user agent. It MUST NOT be 1256 | possible to correlate any two push resource URIs based solely on their 1257 | contents. This allows a user agent to control correlation across 1258 | different applications, or over time. Of course, this does not prevent 1259 | correlation using other information that a user agent might expose. 1260 | 1261 | 1262 | Similarly, the URIs provided by the push service to identify a push 1263 | message MUST NOT provide any information that allows for correlation 1264 | across subscriptions. Push message URIs for the same subscription MAY 1265 | contain information that would allow correlation with the associated 1266 | subscription or other push messages for that subscription. 1267 | 1268 | 1269 | User and device information MUST NOT be exposed through a push or push 1270 | message URI. 1271 | 1272 | 1273 | In addition, push URIs established by the same user agent or push 1274 | message URIs for the same subscription MUST NOT include any information 1275 | that allows them to be correlated with the user agent. 1276 | 1277 | 1278 | This need not be perfect as long as the resulting anonymity set 1279 | (, Section 6.1.1) is sufficiently 1280 | large. A push URI necessarily identifies a push service or a 1281 | single server instance. It is also possible that traffic analysis 1282 | could be used to correlate subscriptions. 1283 | 1284 | 1285 | 1286 | 1287 | A user agent MUST be able to create new subscriptions with new 1288 | identifiers at any time. 1289 | 1290 |
1291 | 1292 |
1293 | 1294 | This protocol does not define how a push service establishes whether a 1295 | user agent is permitted to create a subscription, or whether push 1296 | messages can be delivered to the user agent. A push service MAY choose 1297 | to authorize requests based on any HTTP-compatible authorization method 1298 | available, of which there are multiple options (including experimental 1299 | options) with varying levels of security. The authorization 1300 | process and any associated credentials are expected to be configured in the 1301 | user agent along with the URI for the push service. 1302 | 1303 | 1304 | Authorization is managed using capability URLs for the push message 1305 | subscription, push, and receipt subscription resources (). 1306 | A capability URL grants access to a resource based solely on knowledge of the URL. 1307 | 1308 | 1309 | Capability URLs are used for their "easy onward sharing" and "easy 1310 | client API" properties. These make it possible to avoid relying on 1311 | relationships between push services and application servers, with the 1312 | protocols necessary to build and support those relationships. 1313 | 1314 | 1315 | Capability URLs act as bearer tokens. Knowledge of a push message 1316 | subscription URI implies authorization to either receive push messages 1317 | or delete the subscription. Knowledge of a push URI implies 1318 | authorization to send push messages. Knowledge of a push message URI 1319 | allows for reading and acknowledging that specific message. Knowledge 1320 | of a receipt subscription URI implies authorization to receive push receipts. 1321 | 1322 | 1323 | Encoding a large amount of random entropy (at least 120 bits) in the 1324 | path component ensures that it is difficult to successfully guess a 1325 | valid capability URL. 1326 | 1327 |
1328 | 1329 |
1330 | 1331 | A user agent can control where valid push messages originate by 1332 | limiting the distribution of push URIs to authorized application servers. 1333 | Ensuring that push URIs are hard to guess ensures that only application 1334 | servers that have received a push URI can use it. 1335 | 1336 | 1337 | Push messages that are not successfully authenticated by the user agent 1338 | will not be delivered, but this can present a denial of service risk. Even a 1339 | relatively small volume of push messages can cause battery-powered devices 1340 | to exhaust power reserves. 1341 | 1342 | 1343 | To address this case, the W3C Push API has adopted 1344 | Voluntary Application Server Identification, 1345 | which allows a user agent to restrict a subscription to a specific application 1346 | server. The push service can then identify and reject unwanted messages without 1347 | contacting the user agent. 1348 | 1349 | 1350 | A malicious application with a valid push URI could use the greater 1351 | resources of a push service to mount a denial of service attack on a 1352 | user agent. Push services SHOULD limit the rate at which push messages 1353 | are sent to individual user agents. 1354 | 1355 | 1356 | A push service MAY return a 429 (Too Many Requests) status code 1357 | when an application server has exceeded its rate limit for push message delivery to 1358 | a push resource. The push service SHOULD also include a Retry-After header 1359 | to indicate how long the application server 1360 | is requested to wait before it makes another request to the push resource. 1361 | 1362 | 1363 | A push service or user agent MAY also terminate subscriptions 1364 | that receive too many push messages. 1365 | 1366 | 1367 | A push service is also able to deny service to user agents. 1368 | Intentional failure to deliver messages is difficult to distinguish 1369 | from faults, which might occur due to transient network errors, 1370 | interruptions in user agent availability, or genuine service outages. 1371 | 1372 |
1373 | 1374 |
1375 | 1376 | Server request logs can reveal subscription-related URIs or relationships 1377 | between subscription-related URIs for the same user agent. 1378 | Limitations on log retention and strong access control mechanisms can 1379 | ensure that URIs are not revealed to unauthorized entities. 1380 | 1381 |
1382 | 1383 |
1384 | 1385 |
1386 | 1387 | This protocol defines new HTTP header fields in . New link relation types are identified 1389 | using the URNs defined in . Port registration is 1390 | defined in 1391 | 1392 | 1393 |
1394 | 1395 | HTTP header fields are registered within the "Message Headers" 1396 | registry maintained at . 1398 | 1399 | 1400 | This document defines the following HTTP header fields, so their 1401 | associated registry entries shall be added according to the permanent 1402 | registrations below (): 1403 | 1404 | 1406 | Header Field Name 1407 | Protocol 1408 | Status 1409 | Reference 1410 | 1411 | TTL 1412 | http 1413 | standard 1414 | 1415 | 1416 | 1417 | Urgency 1418 | http 1419 | standard 1420 | 1421 | 1422 | 1423 | Topic 1424 | http 1425 | standard 1426 | 1427 | 1428 | 1429 | 1430 | 1431 | The change controller is: "IETF (iesg@ietf.org) - Internet 1432 | Engineering Task Force". 1433 | 1434 |
1435 | 1436 |
1437 | 1438 | This document registers URNs for use in identifying link relation 1439 | types. These are added to a new "Web Push Identifiers" registry 1440 | according to the procedures in Section 4 of ; 1441 | the corresponding "push" sub-namespace is entered in the "IETF URN 1442 | Sub-namespace for Registered Protocol Parameter Identifiers" 1443 | registry. 1444 | 1445 | 1446 | The "Web Push Identifiers" registry operates under the IETF Review policy. 1448 | 1449 | Web Push Identifiers 1450 | urn:ietf:params:push 1451 | (this document) 1452 | [Editor/IANA note: please include a link 1453 | to the final registry location.] 1454 | Values in this registry are URNs or URN 1455 | prefixes that start with the prefix urn:ietf:params:push. Each is registered 1457 | independently. 1458 | 1459 | 1460 | 1461 | New registrations in the "Web Push Identifiers" are encouraged to 1462 | include the following information: 1463 | 1464 | A complete URN or URN prefix. 1465 | A summary description. 1466 | A reference to a specification 1467 | describing the semantics of the URN or URN prefix. 1468 | Email for the person or group making the 1469 | registration. 1470 | As described in , 1471 | URN prefixes that are registered include a description of how the 1472 | URN is constructed. This is not applicable for specific URNs. 1473 | 1474 | 1475 | 1476 | These values are entered as the initial content of the "Web Push 1477 | Identifiers" registry. 1478 | 1479 | 1480 | 1481 | urn:ietf:params:push 1482 | This link relation type is used to 1483 | identify a resource for sending push messages. 1484 | (this document) 1485 | The Web Push WG (webpush@ietf.org) 1486 | 1487 | 1488 | 1489 | 1490 | urn:ietf:params:push:set 1491 | 1492 | This link relation type is used to identify a collection of push 1493 | message subscriptions. 1494 | 1495 | (this document) 1496 | The Web Push WG (webpush@ietf.org) 1497 | 1498 | 1499 | 1500 | 1501 | urn:ietf:params:push:receipt 1502 | 1503 | This link relation type is used to identify a resource for 1504 | receiving delivery confirmations for push messages. 1505 | 1506 | (this document) 1507 | The Web Push WG (webpush@ietf.org) 1508 | 1509 | 1510 |
1511 |
1512 | 1513 | Service names and port numbers are registered within the "Service Name and 1514 | Transport Protocol Port Number Registry" maintained at . 1516 | 1517 | 1518 | In accordance with , it is requested that IANA assign 1519 | the suggested System Port number 1001 (or another port in the System range) and 1520 | the service name “webpush”. 1521 | 1522 | 1523 | 1524 | 1525 | 1526 | webpush 1527 | 1528 | 1529 | tcp 1530 | 1531 | 1532 | The IESG (iesg@ietf.org) 1533 | 1534 | 1535 | 1536 | The IETF Chair (chair@ietf.org) 1537 | 1538 | 1539 | 1540 | HTTP Web Push 1541 | 1542 | 1543 | 1544 | [RFCthis] 1545 | 1546 | 1547 | 1548 | 1001 1549 | 1550 | 1551 | 1552 | [[The RFC Editor is requested to remove this editorial note at publication.]] 1553 | 1554 | This document uses a placeholder value for a system port pending IANA assignment which 1555 | needs to be replaced with the finalized value at the time of publication. Please apply 1556 | the following replacement: 1557 | 1558 | 1559 | "WEBPUSH-PORT" --> the assigned port value for "webpush" 1560 | 1561 | 1562 | 1563 |
1564 |
1565 | 1566 |
1567 | 1568 | Significant technical input to this document has been provided by Ben 1569 | Bangert, Peter Beverloo, Kit Cambridge, JR Conlin, Lucas Jenss, Matthew Kaufman, 1570 | Costin Manolache, Mark Nottingham, Idel Pivnitskiy, Robert Sparks, 1571 | Darshak Thakore and many others. 1572 | 1573 |
1574 | 1575 | 1576 | 1577 | 1578 | 1579 | 1580 | 1581 | Key words for use in RFCs to Indicate Requirement Levels 1582 | 1583 | 1584 | Harvard University 1585 |
sob@harvard.edu
1586 | 1587 | 1588 | 1589 | 1590 | 1591 | 1592 | 1593 | 1594 | 1595 | 1596 | HTTP Over TLS 1597 | 1598 | 1599 | 1600 | 1601 | 1602 | 1603 | 1604 | 1605 | 1606 | An IETF URN Sub-namespace for Registered Protocol Parameters 1607 | 1608 | 1609 | 1610 | 1611 | 1612 | 1613 | 1614 | 1615 | 1616 | 1617 | 1618 | 1619 | 1620 | 1621 | 1622 | 1623 | 1624 | 1625 | Registration Procedures for Message Header Fields 1626 | 1627 | 1628 | 1629 | 1630 | 1631 | 1632 | 1633 | 1634 | 1635 | 1636 | 1637 | 1638 | 1639 | 1640 | The Base16, Base32, and Base64 Data Encodings 1641 | 1642 | 1643 | 1644 | 1645 | 1646 | 1647 | 1648 | 1649 | 1650 | 1651 | Guidelines for Writing an IANA Considerations Section in RFCs 1652 | 1653 | 1654 | 1655 | 1656 | 1657 | 1658 | 1659 | 1660 | 1661 | 1662 | 1663 | 1664 | NAT Behavioral Requirements for TCP 1665 | 1666 | 1667 | 1668 | 1669 | 1670 | 1671 | 1672 | 1673 | 1674 | 1675 | 1676 | 1677 | 1678 | 1679 | 1680 | 1681 | 1682 | 1683 | 1684 | Web Linking 1685 | 1686 | 1687 | 1688 | 1689 | 1690 | 1691 | 1692 | 1693 | 1694 | 1695 | Internet Assigned Numbers Authority (IANA) Procedures for the Management of the Service Name and Transport Protocol Port Number Registry 1696 | 1697 | 1698 | 1699 | 1700 | 1701 | 1702 | 1703 | 1704 | 1705 | 1706 | 1707 | 1708 | 1709 | 1710 | 1711 | 1712 | 1713 | 1714 | 1715 | 1716 | 1717 | 1718 | 1719 | The Web Origin Concept 1720 | 1721 | 1722 | 1723 | 1724 | 1725 | 1726 | 1727 | 1728 | 1729 | 1730 | Additional HTTP Status Codes 1731 | 1732 | 1733 | 1734 | 1735 | 1736 | 1737 | 1738 | 1739 | 1740 | 1741 | 1742 | Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing 1743 | 1744 | 1745 | 1746 | 1747 | 1748 | 1749 | 1750 | 1751 | 1752 | 1753 | 1754 | 1755 | Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content 1756 | 1757 | 1758 | 1759 | 1760 | 1761 | 1762 | 1763 | 1764 | 1765 | 1766 | 1767 | 1768 | Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests 1769 | 1770 | 1771 | 1772 | 1773 | 1774 | 1775 | 1776 | 1777 | 1778 | 1779 | 1780 | 1781 | Prefer Header for HTTP 1782 | 1783 | 1784 | 1785 | 1786 | 1787 | 1788 | 1789 | 1790 | 1791 | 1792 | Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) 1793 | 1794 | 1795 | 1796 | 1797 | 1798 | 1799 | 1800 | 1801 | 1802 | 1803 | 1804 | 1805 | 1806 | 1807 | 1809 | 1810 | 1811 | 1812 | 1813 | Hypertext Transfer Protocol Version 2 1814 | 1815 | 1816 | 1817 | 1818 | 1819 | 1820 | 1821 | 1822 | 1823 | 1824 | 1825 | 1826 | 1828 | 1829 | 1830 | 1831 | 1832 | HTTP Alternative Services 1833 | 1834 | 1835 | 1836 | 1837 | 1838 | 1839 | 1840 | 1841 | 1842 | 1843 | 1844 | 1845 | 1847 | 1848 | 1849 | 1850 | 1851 | Good Practices for Capability URLs 1852 | 1853 | 1854 | 1855 | 1856 | 1857 | 1858 | 1859 | 1860 | 1861 | 1862 | Message Encryption for Web Push 1863 | 1864 | 1865 | 1866 | 1867 | 1868 | 1869 | 1870 | Voluntary Application Server Identification for Web Push 1871 | 1872 | 1873 | 1874 | 1875 | 1876 | 1877 | 1878 | 1879 | W3C Push API 1880 | 1881 | 1882 | 1883 | 1884 | 1885 | 1886 | 1887 | 1888 | 1889 | 1890 | 1891 | Privacy Considerations for Internet Protocols 1892 | 1893 | 1894 | 1895 | 1896 | 1897 | 1898 | 1899 | 1900 | 1901 | 1902 | 1903 | 1904 | 1905 | 1906 | 1907 | 1908 | 1909 | 1910 | 1911 | 1912 | 1913 | 1914 |
1915 | [[The RFC Editor is requested to remove this section at publication.]] 1916 |
1917 | 1918 | Editorial changes for Push Message Time-To-Live 1919 | 1920 | 1921 | Editorial changes for Push Acknowledgements 1922 | 1923 | 1924 | Removed subscription expiration based on HTTP cache headers 1925 | 1926 |
1927 |
1928 | 1929 | Added Subscription Sets 1930 | 1931 | 1932 | Added System Port as an alternate service with guidance for idle timeouts 1933 | 1934 | 1935 | Finalized status codes for acknowledgements 1936 | 1937 | 1938 | Editorial changes for Rate Limits 1939 | 1940 |
1941 |
1942 | 1943 | Added explicit correlation for Subscription Sets 1944 | 1945 | 1946 | Added Push Message Updates (message collapsing) 1947 | 1948 | 1949 | Renamed the push:receipt link relation to push:receipts and transitioned the 1950 | Push-Receipt header field to the push:receipt link relation type 1951 | 1952 |
1953 |
1954 | 1955 | An application server MUST include the TTL (Time-To-Live) header field in 1956 | its request for push message delivery. 1957 | 1958 | 1959 | Added Push Message Urgency header field 1960 | 1961 |
1962 |
1963 | 1964 | Simplified design for Push Receipts and eliminated the urn:ietf:params:push:receipts link 1965 | relation 1966 | 1967 | 1968 | Clarified Security Considerations section and added informative references to 1969 | Message Encryption and Voluntary Application Server Identification 1970 | 1971 |
1972 |
1973 | 1974 | Addressed feedback from Working Group Last Call 1975 | 1976 |
1977 |
1978 | 1979 | Updated informative references to W3C Push API, Message Encryption, and Voluntary 1980 | Application Server Identification 1981 | 1982 |
1983 |
1984 | 1985 | Minor editorial changes 1986 | 1987 |
1988 |
1989 | 1990 | Minor correction to Acknowledgements 1991 | 1992 | 1993 | Updated dates for informative references 1994 | 1995 |
1996 |
1997 | 1998 | Updates for Area Director (Alissa Cooper) evaluation 1999 | 2000 |
2001 |
2002 | 2003 | Updates for TSV-ART review from Magnus Westerlund 2004 | 2005 | 2006 | Updated informative reference for Message Encryption 2007 | 2008 |
2009 |
2010 | 2011 | Updates from IESG Evaluation 2012 | 2013 |
2014 |
2015 | 2016 | 2017 | --------------------------------------------------------------------------------