| WEBPUSH | M. Thomson |
| Internet-Draft | Mozilla |
| Intended status: Standards Track | E. Damaggio |
| Expires: January 21, 2016 | B. Raymor, Ed. |
| Microsoft | |
| July 20, 2015 |
Generic Event Delivery Using HTTP Push
draft-ietf-webpush-protocol-00
A simple protocol for the delivery of realtime events to user agents is described. This scheme uses HTTP/2 server push.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 21, 2016.
Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
Many applications on mobile and embedded devices require continuous access to network communications so that real-time events - such as incoming calls or messages - can be delivered (or "pushed") in a timely fashion. These devices typically have limited power reserves, so finding more efficient ways to serve application requirements greatly benefits the application ecosystem.
One significant contributor to power usage is the radio. Radio communications consume a significant portion of the energy budget on a wireless device.
Uncoordinated use of persistent connections or sessions from multiple applications can contribute to unnecessary use of the device radio, since each independent session independently incurs overheads. In particular, keep alive traffic used to ensure that middleboxes do not prematurely time out sessions, can result in significant waste. Maintenance traffic tends to dominate over the long term, since events are relatively rare.
Consolidating all real-time events into a single session ensures more efficient use of network and radio resources. A single service consolidates all events, distributing those events to applications as they arrive. This requires just one session, avoiding duplicated overhead costs.
The W3C Web Push API [API] describes an API that enables the use of a consolidated push service from web applications. This expands on that work by describing a protocol that can be used to:
Requesting the delivery of events is particularly important for the Web Push API. The subscription, management and monitoring functions are currently fulfilled by proprietary protocols; these are adequate, but do not offer any of the advantages that standardization affords.
This document intentionally does not describe how a push service is discovered. Discovery of push services is left for future efforts, if it turns out to be necessary at all. User agents are expected to be configured with a URL for a push service.
In cases where normative language needs to be emphasized, this document falls back on established shorthands for expressing interoperability requirements on implementations: the capitalized words "MUST", "MUST NOT", "SHOULD" and "MAY". The meaning of these is described in [RFC2119].
This document defines the following terms:
Examples in this document use the HTTP/1.1 message format [RFC7230]. Many of the exchanges can be completed using HTTP/1.1, where HTTP/2 is necessary, the more verbose frame format from [RFC7540] is used.
A general model for push services includes three basic actors: a user agent, a push service, and an application (server).
+-------+ +--------------+ +-------------+
| UA | | Push Service | | Application |
+-------+ +--------------+ +-------------+
| | |
| Subscribe | |
|--------------------->| |
| Monitor | |
|<====================>| |
| | |
| Distribute Push Resource |
|-------------------------------------------->|
| | |
: : :
| | Push Message |
| Push Message |<---------------------|
|<---------------------| |
| | |
At the very beginning of the process, a new message subscription is created by the user agent and then distributed to its application server. This subscription is the basis of all future interactions between the actors.
To offer more control for authorization, a message subscription is modeled as two resources with different capabilities:
It is expected that a unique subscription will be distributed to each application; however, there are no inherent cardinality constraints in the protocol. Multiple subscriptions might be created for the same application, or multiple applications could use the same subscription. Note however that sharing subscriptions has security and privacy implications.
Subscriptions have a limited lifetime. They can also be terminated by either the push service or user agent at any time. User agents and application servers must be prepared to manage changes in subscription state.
This protocol uses HTTP resources [RFC7230] and link relations [RFC5988]. The following resources are defined:
A user agent sends a POST request to its configured push service resource to create a new subscription.
POST /subscribe/ HTTP/1.1 Host: push.example.net
A response with a 201 (Created) status code includes a URI for a new push message subscription resource in the Location header field.
The push server MUST provide a URI for the push resource corresponding to the push message subscription using a link relation of type "urn:ietf:params:push".
The push server MUST provide a URI for a receipt subscribe resource in a link relation of type "urn:ietf:params:push:receipt".
An application-specific method is used to distribute the push and receipt subscribe URIs to the application server. Confidentiality protection and application server authentication MUST be used to ensure that these URIs are not disclosed to unauthorized recipients (see Section 8.3).
HTTP/1.1 201 Created
Date: Thu, 11 Dec 2014 23:56:52 GMT
Link: </p/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV>;
rel="urn:ietf:params:push"
Link: </receipts/xjTG79I3VuptNWS0DsFu4ihT97aE6UQJ>;
rel="urn:ietf:params:push:receipt"
Location: https://push.example.net/s/LBhhw0OohO-Wl4Oi971UGsB7sdQGUibx
Cache-Control: max-age:864000, private
An application server requests the creation of a receipt subscription by sending a HTTP POST request to the receipt subscribe resource distributed to the application server by a user agent.
POST /receipts/xjTG79I3VuptNWS0DsFu4ihT97aE6UQJ HTTP/1.1
Host: push.example.net
A successful response with a 201 (Created) status code includes a URI for the receipt subscription resource in the Location header field.
HTTP/1.1 201 Created
Date: Thu, 11 Dec 2014 23:56:52 GMT
Location: https://push.example.net/r/3ZtI4YVNBnUUZhuoChl6omUvG4ZM9mpN
An application server that sends push messages to a large population of user agents incurs a significant load if it has to monitor a receipt subscription for each user agent. Reuse of receipt subscriptions is critical in reducing load on application servers. A receipt subscription can be used for all resources that have the same receipt subscribe URI.
A push service SHOULD provide the same receipt subscribe URI to all user agents. Application servers SHOULD reuse receipt subscription URIs if the receipt subscribe URI provided with the push resource is identical to the one used to create the receipt subscription. Checking that the receipt subscribe URI is identical allows the application server to avoid creating unnecessary receipt subscriptions.
An application server requests the delivery of a push message by sending a HTTP request to a push resource distributed to the application server by a user agent. The push message is included in the body of the request.
POST /p/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV HTTP/1.1 Host: push.example.net Push-Receipt: https://push.example.net/r/3ZtI4YVNBnUUZhuoChl6omUvG4ZM9mpN Content-Type: text/plain;charset=utf8 Content-Length: 36 iChYuI3jMzt3ir20P8r_jgRR-dSuN182x7iB
A 201 (Created) response indicates that the push message was accepted. A URI for the push message resource that was created in response to the request is included in the Location header field. This does not indicate that the message was delivered to the user agent.
HTTP/1.1 201 Created Date: Thu, 11 Dec 2014 23:56:55 GMT Location: https://push.example.net/d/qDIYHNcfAIPP_5ITvURr-d6BGtYnTRnk
A push service MAY generate a 413 (Payload Too Large) status code in response to requests that include an entity body that is too large. Push services MUST NOT generate a 413 status code in responses to an entity body that is 4k (4096 bytes) or less in size.
An application server can use the Push-Receipt header field to request a confirmation from the push service when a push message is delivered and acknowledged by the user agent. The Push-Receipt header field is a URI-Reference as defined in Section 2.7 of [RFC7230].
Push-Receipt = URI-reference
The application sets the Push-Receipt header field value to a receipt subscription URI. This receipt subscription resource MUST be created from the same receipt subscribe resource which was returned with the push message subscription response (see Section 3).
A push service can improve the reliability of push message delivery considerably by storing push messages for a period. User agents are often only intermittently connected, and so benefit from having short term message storage at the push service.
Delaying delivery might also be used to batch communication with the user agent, thereby conserving radio resources.
Some push messages are not useful once a certain period of time elapses. Delivery of messages after they have ceased to be relevant is wasteful. For example, if the push message contains a call notification, receiving a message after the caller has abandoned the call is of no value; the application at the user agent is forced to suppress the message so that it does not generate a useless alert.
An application server can use the TTL header field to limit the time that a push message is retained by a push service. The TTL header field contains a value in seconds that describes how long a push message is retained by the push service.
TTL = 1*DIGIT
Once the Time-To-Live (TTL) period elapses, the push service MUST remove the push message and cease any attempt to deliver it to the user agent. A push service might retain values for a short duration after the TTL period to account for time accounting errors in processing. For instance, distributing a push message within a server cluster might accrue errors due to clock variation, or processing and transit delays.
A push service is not obligated to account for time spent by the application server in sending a push message to the push service, or delays incurred while sending a push message to the user agent. An application server needs to account for transit delays in selecting a TTL header field value.
Absence of the TTL header field is interpreted as equivalent to a zero value. Push messages with a zero TTL indicate that storage is not needed and that the message can be dropped if the user agent isn't immediately available to receive the message. Push messages with a zero TTL can be delivered very efficiently.
A push service MAY choose to retain a push message for a shorter duration than that requested. It indicates this by including a TTL header field in the response that includes the actual TTL. This TTL value MUST be less than or equal to the value provided by the application server.
A user agent requests the delivery of new push messages by making a GET request to a push message subscription resource. The push service does not respond to this request, it instead uses HTTP/2 server push [RFC7540] to send the contents of push messages as they are sent by application servers.
Each push message is pushed in response to a synthesized GET request. The GET request is made to the push message resource that was created by the push server when the application server requested message delivery. The response body is the entity body from the most recent request sent to the push resource.
The following example request is made over HTTP/2.
HEADERS [stream 7] +END_STREAM +END_HEADERS :method = GET :path = /s/LBhhw0OohO-Wl4Oi971UGsB7sdQGUibx :authority = push.example.net
The push service permits the request to remain outstanding. When a push message is sent by an application server, a server push is associated with the initial request. The response includes the push message.
PUSH_PROMISE [stream 7; promised stream 4] +END_HEADERS :method = GET :path = /d/qDIYHNcfAIPP_5ITvURr-d6BGtYnTRnk :authority = push.example.net HEADERS [stream 4] +END_HEADERS :status = 200 date = Thu, 11 Dec 2014 23:56:56 GMT last-modified = Thu, 11 Dec 2014 23:56:55 GMT cache-control = private content-type = text/plain;charset=utf8 content-length = 36 DATA [stream 4] +END_STREAM iChYuI3jMzt3ir20P8r_jgRR-dSuN182x7iB
In response to this request, the push server MUST generate a server push for all push messages that have not yet been delivered. In addition, the push service SHOULD return link references to the push and receipt subscribe resources, plus expiration information for the subscription.
A user agent can request the contents of the push message subscription resource immediately by including a Prefer header field [RFC7240] with a "wait" parameter set to "0".
A 204 (No Content) status code with no associated server pushes indicates that no messages are presently available. This could be because push messages have expired.
To ensure that a push message is properly delivered to the user agent at least once, the user agent MUST acknowledge receipt of the message by performing a HTTP DELETE on the push message resource.
DELETE /d/qDIYHNcfAIPP_5ITvURr-d6BGtYnTRnk HTTP/1.1
Host: push.example.net
If the application has requested a delivery receipt, the push server MUST deliver a response to the application server monitoring the receipt subscription resource.
The application server requests the delivery of receipts from the push server by making a HTTP GET request to the receipt subscription resource. The push service does not respond to this request, it instead uses HTTP/2 server push [RFC7540] to send push receipts when messages are acknowledged (Section 6.1) by the user agent.
Each receipt is pushed in response to a synthesized GET request. The GET request is made to the same push message resource that was created by the push server when the application server requested message delivery. A successful response includes a 410 (GONE) status code with no data.
The following example request is made over HTTP/2.
HEADERS [stream 13] +END_STREAM +END_HEADERS
:method = GET
:path = /r/3ZtI4YVNBnUUZhuoChl6omUvG4ZM9mpN
:authority = push.example.net
The push service permits the request to remain outstanding. When the user agent acknowledges the message, the push server pushes a delivery receipt to the application server. A 410 (Gone) status code confirms that the message was delivered and acknowledged.
PUSH_PROMISE [stream 13; promised stream 82] +END_HEADERS
:method = GET
:path = /d/qDIYHNcfAIPP_5ITvURr-d6BGtYnTRnk
:authority = push.example.net
HEADERS [stream 4] +END_STREAM
+END_HEADERS
:status = 410
date = Thu, 11 Dec 2014 23:56:56 GMT
The push server MUST push a response with a status code of 5XX (TBD) if the user agent fails to acknowledge the receipt of the push message or the push server fails to deliver the message prior to its expiration.
A push service is likely to have to maintain a very large number of open TCP connections. Effective management of those connections can depend on being able to move connections between server instances.
A user agent MUST support the 307 (Temporary Redirect) status code [RFC7231], which can be used by a push service to redistribute load at the time that a new subscription is requested.
A server that wishes to redistribute load can do so using alternative services [I-D.ietf-httpbis-alt-svc]. Alternative services allows for redistribution of load whilst maintaining the same URIs for various resources. User agents can ensure a graceful transition by using the GOAWAY frame once it has established a replacement connection.
Storage of push messages based on the TTL header field comprises a potentially significant amount of storage for a push service. A push service is not obligated to store messages indefinitely. A push service is able to indicate how long it intends to retain a message to an application server using the TTL header field (see Section 5.2).
A user agent that does not actively monitor for push messages will not receive messages that expire during that interval.
Push messages that are stored and not delivered to a user agent are delivered when the user agent recommences monitoring. Stored push messages SHOULD include a Last-Modified header field (see Section 2.2 of [RFC7232]) indicating when delivery was requested by an application server.
A GET request to a push message subscription resource that has only expired messages results in response as though no push message were ever sent.
Push services might need to limit the size and number of stored push messages to avoid overloading. In addition to using the 413 (Payload Too Large) status code for too large push messages, a push service MAY expire push messages prior to any advertised expiration time. A push service can reduce the impact push message retention by reducing the time-to-live of push messages.
In some cases, it may be necessary to terminate subscriptions so that they can be refreshed. This applies to both push message subscriptions and receipt subscriptions.
A push service might choose to set a fixed expiration time. If a resource has a known expiration time, expiration information is included in responses to requests that create the resource, or in requests that retrieve a representation of the resource.
Expiration is indicated using either the Expires header field, or by setting a "max-age" parameter on a Cache-Control header field (see [RFC7234]). The Cache-Control header field MUST also include the "private" directive.
A push service can remove a subscription at any time. If a user agent or application server has an outstanding request to a subscription resource (see Section 6), this can be signaled by returning a 400-series status code, such as 410 (Gone).
A user agent or application server can request that a subscription be removed by sending a DELETE request to the push message subscription or receipt subscription URI.
A push service MUST return a 400-series status code, such as 404 (Not Found) or 410 (Gone) if an application server attempts to send a push message to a removed or expired push message subscription.
A push server that does not support reliable delivery over intermittent network connections or failing applications on devices, forces the device to acknowledge receipt directly to the application server, incurring additional power drain in order to establish (usually secure) connections to the individual application servers.
Push message reliability can be important if messages contain information critical to the state of an application. Repairing state can be costly, particularly for devices with limited communications capacity. Knowing that a push message has been correctly received avoids costly retransmissions, polling and state resynchronization.
The availability of push message delivery receipts ensures that the application developer is not tempted to create alternative mechanisms for message delivery in case the push service fails to deliver a critical message. Setting up a polling mechanism or a backup messaging channel in order to compensate for these shortcomings negates almost all of the advantages a push service provides.
However, reliability might not be necessary for messages that are transient (e.g. an incoming call) or messages that are quickly superceded (e.g. the current number of unread emails).
This protocol MUST use HTTP over TLS [RFC2818]. This includes any communications between user agent and push service, plus communications between the application and the push service. All URIs therefore use the "https" scheme. This provides confidentiality and integrity protection for subscriptions and push messages from external parties.
The protection afforded by TLS does not protect content from the push service. Without additional safeguards, a push service is able to see and modify the content of the messages.
Applications are able to provide additional confidentiality, integrity or authentication mechanisms within the push message itself. The application server sending the push message and the application on the user agent that receives it are frequently just different instances of the same application, so no standardized protocol is needed to establish a proper security context. The process of providing the application server with subscription information provides a convenient medium for key agreement.
The Web Push API codifies this practice by requiring that each push subscription created by the browser be bound to a browser generated encryption key. Pushed messages are authenticated and decrypted by the browser before delivery to applications. This scheme ensures that the push service is unable to examine the contents of push messages.
The public key for a subscription ensures that applications using that subscription can identify messages from unknown sources and discard them. This depends on the public key only being disclosed to entities that are authorized to send messages on the channel. The push server does not require access to this public key.
Push message confidentiality does not ensure that the identity of who is communicating and when they are communicating is protected. However, the amount of information that is exposed can be limited.
The URIs provided for push resources MUST NOT provide any basis to correlate communications for a given user agent. It MUST NOT be possible to correlate any two push resource URIs based solely on their contents. This allows a user agent to control correlation across different applications, or over time.
Similarly, the URIs provided by the push service to identify a push message MUST NOT provide any information that allows for correlation across subscriptions. Push message URIs for the same subscription MAY contain information that would allow correlation with the associated subscription or other push messages for that subscription.
User and device information MUST NOT be exposed through a push or push message URI.
In addition, push URIs established by the same user agent or push message URIs for the same subscription MUST NOT include any information that allows them to be correlated with the user agent.
A user agent MUST be able to create new subscriptions with new identifiers at any time.
This protocol does not define how a push service establishes whether a user agent is permitted to create a subscription, or whether push messages can be delivered to the user agent. A push service MAY choose to authorize requests based on any HTTP-compatible authorization method available, of which there are numerous options. The authorization process and any associated credentials are expected to be configured in the user agent along with the URI for the push service.
Authorization is managed using capability URLs for the push message subscription, push, and receipt subscription resources (see [CAP-URI]). A capability URL grants access to a resource based solely on knowledge of the URL.
Capability URLs are used for their "easy onward sharing" and "easy client API" properties. These make it possible to avoid relying on relationships between push services and application servers, with the protocols necessary to build and support those relationships.
Capability URLs act as bearer tokens. Knowledge of a push message subscription URI implies authorization to either receive push messages or delete the subscription. Knowledge of a push URI implies authorization to send push messages. Knowledge of a push message URI allows for reading and acknowledging that specific message. Knowledge of a receipt subscription URI implies authorization to receive push receipts. Knowledge of a receipt subscribe URI implies authorization to create subscriptions for receipts.
Note that the same receipt subscribe URI could be returned for multiple push message subscriptions. Using the same value for a large number of subscriptions allows application servers to reuse receipt subscriptions, which can provide a significant efficiency advantage. A push service that uses a common receipt subscribe URI loses control over the creation of receipt subscriptions. This can result in a potential exposure to denial of service; stateless resource creation can be used to mitigate the effects of this exposure.
Encoding a large amount of random entropy (at least 120 bits) in the path component ensures that it is difficult to successfully guess a valid capability URL.
Discarding unwanted messages at the user agent based on message authentication doesn't protect against a denial of service attack on the user agent. Even a relatively small volume of push messages can cause battery-powered devices to exhaust power reserves.
An application can limit where valid push messages can originate by limiting the distribution of push URIs to authorized entities. Ensuring that push URIs are hard to guess ensures that only application servers that have been given a push URI can use it.
A malicious application with a valid push URI could use the greater resources of a push service to mount a denial of service attack on a user agent. Push services SHOULD limit the rate at which push messages are sent to individual user agents. A push service or user agent MAY terminate subscriptions [delete] that receive too many push messages.
End-to-end confidentiality mechanisms, such as those in [API], prevent an entity with a valid push message subscription URI from learning the contents of push messages. Push messages that are not successfully authenticated will not be delivered by the API, but this can present a denial of service risk.
Conversely, a push service is also able to deny service to user agents. Intentional failure to deliver messages is difficult to distinguish from faults, which might occur due to transient network errors, interruptions in user agent availability, or genuine service outages.
Server request logs can reveal subscription-related URIs. Acquiring a push message subscription URI enables the receipt of messages or deletion of the subscription. Acquiring a push URI permits the sending of push messages. Logging could also reveal relationships between different subscription-related URIs for the same user agent. Encrypted message contents are not revealed to the push service.
Limitations on log retention and strong access control mechanisms can ensure that URIs are not learned by unauthorized entities.
This protocol defines new HTTP header fields in Section 9.1. New link relation types are identified using the URNs defined in Section 9.2.
HTTP header fields are registered within the "Message Headers" registry maintained at <https://www.iana.org/assignments/message-headers/>.
This document defines the following HTTP header fields, so their associated registry entries shall be added according to the permanent registrations below (see [RFC3864]):
| Header Field Name | Protocol | Status | Reference |
|---|---|---|---|
| TTL | http | standard | Section 5.2 |
| Push-Receipt | http | standard | Section 5.1 |
The change controller is: "IETF (iesg@ietf.org) - Internet Engineering Task Force".
This document registers URNs for use in identifying link relation types. These are added to a new "Web Push Identifiers" registry according to the procedures in Section 4 of [RFC3553]; the corresponding "push" sub-namespace is entered in the "IETF URN Sub-namespace for Registered Protocol Parameter Identifiers" registry.
The "Web Push Identifiers" registry operates under the IETF Review policy [RFC5226].
New registrations in the "Web Push Identifiers" are encouraged to include the following information:
These values are entered as the initial content of the "Web Push Identifiers" registry.
Significant technical input to this document has been provided by Costin Manolache, Robert Sparks, Mark Nottingham, Matthew Kaufman and many others.
| [API] | Sullivan, B., Fullea, E. and M. van Ouwerkerk, "Web Push API", ED push-api, February 2015. |
| [RFC6973] | Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., Morris, J., Hansen, M. and R. Smith, "Privacy Considerations for Internet Protocols", RFC 6973, July 2013. |