draft-ietf-webpush-protocol.xml

<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">

<?rfc strict="yes" ?>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes" ?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>

<rfc category="std" ipr="trust200902" docName="draft-ietf-webpush-protocol-latest">
  <front>
    <title abbrev="HTTP Web Push">
      Generic Event Delivery Using HTTP Push
    </title>

    <author initials="M." surname="Thomson" fullname="Martin Thomson">
      <organization>Mozilla</organization>
      <address>
        <postal>
          <street>331 E Evelyn Street</street>
          <city>Mountain View</city>
          <region>CA</region>
          <code>94041</code>
          <country>US</country>
        </postal>
        <email>martin.thomson@gmail.com</email>
      </address>
    </author>

    <author initials="E." surname="Damaggio" fullname="Elio Damaggio">
      <organization>Microsoft</organization>
      <address>
        <postal>
          <street>One Microsoft Way</street>
          <city>Redmond</city>
          <region>WA</region>
          <code>98052</code>
          <country>US</country>
        </postal>
        <email>elioda@microsoft.com</email>
      </address>
    </author>

    <author initials="B." surname="Raymor" fullname="Brian Raymor" role="editor">
      <organization>Microsoft</organization>
      <address>
        <postal>
          <street>One Microsoft Way</street>
          <city>Redmond</city>
          <region>WA</region>
          <code>98052</code>
          <country>US</country>
        </postal>
        <email>brian.raymor@microsoft.com</email>
      </address>
    </author>

    <date year="2016"/>
    <area>RAI</area>
    <workgroup>WEBPUSH</workgroup>
    <keyword>Internet-Draft</keyword>
    <keyword>HTTP</keyword>
    <keyword>HTTP2</keyword>
    <keyword>Push</keyword>
    <keyword>WebPush</keyword>

    <abstract>
      <t>
        A simple protocol for the delivery of real-time events to user agents is
        described.  This scheme uses HTTP/2 server push.
      </t>
    </abstract>
  </front>

  <middle>
    <section anchor="intro" title="Introduction">
      <t>
        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.
      </t>
      <t>
        One significant contributor to power usage is the radio.  Radio
        communications consume a significant portion of the energy budget
        on a wireless device.
      </t>
      <t>
        Uncoordinated use of persistent connections or sessions from multiple
        applications can contribute to unnecessary use of the device radio,
        since each independent session can incur its own overhead.  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.
      </t>
      <t>
        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.
      </t>
      <t>
        The <xref target="API">W3C Push API</xref> describes an API that
        enables the use of a consolidated push service from web applications.
        This document expands on that work by describing a protocol that can be used to:
        <list style="symbols">
          <t>
            request the delivery of a push message to a user agent,
          </t>
          <t>
            create new push message delivery subscriptions, and
          </t>
          <t>
            monitor for new push messages.
          </t>
        </list>
      </t>
      <t>
        A standardized method of event delivery is particularly important for
        the W3C Push API, where application servers might need to use multiple
        push services.  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.
      </t>
      <t>
        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.
      </t>

      <section anchor="terminology" title="Conventions and Terminology">
        <t>
          The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
          "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
          document are to be interpreted as described in <xref target="RFC2119"/>.
        </t>
        <t>
          This document defines the following terms:
          <list style="hanging">
            <t hangText="application:">
              Both the sender and ultimate consumer of push messages.  Many
              applications have components that are run on a user agent and
              other components that run on servers.
            </t>
            <t hangText="application server:">
              The component of an application that usually runs on a server and
              requests the delivery of a push message.
            </t>
            <t hangText="push message subscription:">
              A message delivery context that is established between the user
              agent and the push service and shared with the application server.
              All push messages are associated with a push message subscription.
            </t>
            <t hangText="push message subscription set:">
              A message delivery context that is established between the user
              agent and the push service that collects multiple push message
              subscriptions into a set.
            </t>
            <t hangText="push message:">
              A message sent from an application server to a user agent via a
              push service.
            </t>
            <t hangText="push message receipt:">
              A message delivery confirmation sent from the push service to the
              application server.
            </t>
            <t hangText="push service:">
              A service that delivers push messages to user agents.
            </t>
            <t hangText="user agent:">
              A device and software that is the recipient of push messages.
            </t>
          </list>
        </t>
        <t>
          Examples in this document use the <xref target="RFC7230">HTTP/1.1
          message format</xref>. Many of the exchanges can be completed using
          HTTP/1.1:

          <list style="symbols">
            <t>
              <xref target="message_subscription">Subscribing for Push Messages</xref>
            </t>
            <t>
              <xref target="send">Requesting Push Message Delivery</xref>
            </t>
            <t>
              <xref target="replace">Replacing Push Messages</xref>
            </t>
            <t>
              <xref target="acknowledge_message">Acknowledging Push Messages</xref>
            </t>
          </list>

          When an example depends on HTTP/2 server push, the more verbose frame format
          from <xref target="RFC7540"/> is used:

          <list style="symbols">
            <t>
              <xref target="monitor-subscription">Receiving Push Messages for a Subscription</xref>
            </t>
            <t>
              <xref target="monitor-set">Receiving Push Messages for a Subscription Set</xref>
            </t>
            <t>
              <xref target="receive_receipt">Receiving Push Message Receipts</xref>
            </t>
          </list>
        </t>
        <t>
          All examples use HTTPS over the default port (443) rather than the registered port
          (WEBPUSH-PORT). A push service deployment might prefer this configuration to maximize
          chances for user agents to reach the service. A push service might use HTTP alternative
          services to redirect a user agent to the registered port (WEBPUSH-PORT) to gain the benefits of the
          standardized HTTPS port without sacrificing reachability (see <xref target="connecting"/>).
          This would only be apparent in the examples through the inclusion of the Alt-Used header
          field <xref target="RFC7838"/> in requests from the user agent to the push service.
        </t>
        <t>
          Examples do not include specific methods for push message encryption
          or application server authentication because the protocol does not define
          a mandatory system. The examples in <xref target="I-D.ietf-webpush-vapid">Voluntary Application Server Identification</xref>
          and <xref target="I-D.ietf-webpush-encryption">Message Encryption for WebPush</xref>
          demonstrate the approach adopted by the <xref target="API">W3C Push API</xref> for
          its requirements.
        </t>
      </section>
    </section>

    <section title="Overview">
      <t>
        A general model for push services includes three basic actors: a user
        agent, a push service, and an application (server).
      </t>
      <figure anchor="fig-arch" title="Webpush Architecture">
          <artwork><![CDATA[
 +-------+           +--------------+       +-------------+
 |  UA   |           | Push Service |       | Application |
 +-------+           +--------------+       |   Server    |
     |                      |               +-------------+
     |      Subscribe       |                      |
     |--------------------->|                      |
     |       Monitor        |                      |
     |<====================>|                      |
     |                      |                      |
     |          Distribute Push Resource           |
     |-------------------------------------------->|
     |                      |                      |
     :                      :                      :
     |                      |     Push Message     |
     |    Push Message      |<---------------------|
     |<---------------------|                      |
     |                      |                      |
]]></artwork>
      </figure>
      <t>
        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. A subscription is used by the application server to send messages to
        the push service for being delivered to the user agent. It is used by
        the user agent to monitor the push service for any incoming message.
      </t>
      <t>
        To offer more control for authorization, a message subscription is
        modeled as two resources with different capabilities:
        <list style="symbols">
          <t>
            A subscription resource is used to receive messages from a
            subscription and to delete a subscription. It is private to the user
            agent.
          </t>
          <t>
            A push resource is used to send messages to a subscription. It is
            public and shared by the user agent with its application server.
          </t>
        </list>
      </t>
      <t>
        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.
      </t>
      <t>
        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.
      </t>

      <section anchor="resources" title="HTTP Resources">
        <t>
          This protocol uses <xref target="RFC7230">HTTP resources</xref> and
          <xref target="RFC5988">link relations</xref>.  The following resources
          are defined:
          <list style="hanging">
            <t hangText="push service:">
              This resource is used to create push message subscriptions
              (<xref target="message_subscription"/>).  A URL for the push
              service is configured into user agents.
            </t>
            <t hangText="push message subscription:">
              This resource provides read and delete access for a message
              subscription. A user agent <xref target="monitor-subscription">receives push
              messages</xref> using a push message subscription.  Every push
              message subscription has exactly one push resource associated with
              it.
            </t>
            <t hangText="push message subscription set:">
              This resource provides read and delete access for a collection of push
              message subscriptions. A user agent <xref target="monitor-set">receives
              push messages</xref> for all the push message subscriptions in the set. A
              link relation of type "urn:ietf:params:push:set" identifies a push message
              subscription set.
            </t>
            <t hangText="push:">
              An application server <xref target="send">requests the delivery</xref> of a
              push message using a push resource.  A link relation of type "urn:ietf:params:push"
              identifies a push resource.
            </t>
            <t hangText="push message:">
              The push service creates a push message resource to identify push messages that
              have been <xref target="send">accepted for delivery</xref>. The push message
              resource is also deleted by the user agent to
              <xref target="acknowledge_message">acknowledge receipt</xref> of a push message.
            </t>
            <t hangText="receipt subscription:">
              An application server <xref target="request-receipt">receives
              delivery confirmations</xref> for push messages using a receipt
              subscription.  A link relation of type "urn:ietf:params:push:receipt"
              identifies a receipt subscription.
            </t>
          </list>
        </t>
      </section>
    </section>
    <section anchor="connecting" title="Connecting to the Push Service">
      <t>
        The push service MUST use HTTP over TLS [RFC2818] following the recommendations in [RFC7525].
        The push service shares the same default port number (443/TCP) with HTTPS, but MAY
        also advertise the IANA allocated TCP System Port (WEBPUSH-PORT) using HTTP alternative services
        <xref target="RFC7838"/>.
      </t>
      <t>
        While the default port (443) offers broad reachability characteristics, it is most
        often used for web browsing scenarios with a lower idle timeout than other ports
        configured in middleboxes. For webpush scenarios, this would contribute to unnecessary
        radio communications to maintain the connection on battery-powered devices.
      </t>
      <t>
        Advertising the alternate port (WEBPUSH-PORT) allows middleboxes to optimize idle timeouts
        for connections specific to push scenarios with the expectation that data exchange will be
        infrequent.
      </t>
      <t>
        Middleboxes SHOULD comply with REQ-5 in <xref target="RFC5382"/> which requires that
        "the value of the 'established connection idle-timeout' MUST NOT be less than
        2 hours 4 minutes".
      </t>
    </section>
    <section anchor="message_subscription" title="Subscribing for Push Messages">
      <t>
        A user agent sends a POST request to its configured push service
        resource to create a new subscription.
      </t>
      <figure>
        <artwork type="inline"><![CDATA[
POST /subscribe HTTP/1.1
Host: push.example.net

]]></artwork>
      </figure>
      <t>
        A 201 (Created) response indicates that the push subscription was
        created. A URI for the push message subscription resource that was
        created in response to the request MUST be returned in the Location
        header field.
      </t>
      <t>
        The push service MUST provide a URI for the push resource corresponding
        to the push message subscription in a link relation of type
        "urn:ietf:params:push".
      </t>
      <t>
        An application-specific method is used to distribute the push URI to the
        application server.  Confidentiality protection and application server
        authentication MUST be used to ensure that this URI is not disclosed
        to unauthorized recipients (<xref target="authorization"/>).
      </t>
      <figure>
        <artwork type="inline">
  <![CDATA[
HTTP/1.1 201 Created
Date: Thu, 11 Dec 2014 23:56:52 GMT
Link: </push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV>;
        rel="urn:ietf:params:push"
Link: </subscription-set/4UXwi2Rd7jGS7gp5cuutF8ZldnEuvbOy>;
        rel="urn:ietf:params:push:set"
Location: https://push.example.net/subscription/LBhhw0OohO-Wl4Oi971UG

]]></artwork>
      </figure>
      <section title="Collecting Subscriptions into Sets">
        <t>
          Collecting multiple push message subscriptions into a subscription set
          can represent a significant efficiency improvement for push services
          and user agents. The push service MAY provide a URI for a subscription
          set resource in a link relation of type "urn:ietf:params:push:set".
        </t>
        <t>
          When a subscription set is returned in a push message subscription
          response, the user agent SHOULD include this subscription set in a link
          relation of type "urn:ietf:params:push:set" in subsequent requests to
          create new push message subscriptions.
        </t>
        <t>
          A user agent MAY omit the subscription set if it is unable to receive
          push messages in an aggregated way for the lifetime of the subscription.
          This might be necessary if the user agent is monitoring subscriptions on
          behalf of other push message receivers.
        </t>
      <figure>
        <artwork type="inline">
  <![CDATA[
POST /subscribe HTTP/1.1
Host: push.example.net
Link: </subscription-set/4UXwi2Rd7jGS7gp5cuutF8ZldnEuvbOy>;
        rel="urn:ietf:params:push:set"
]]></artwork>
      </figure>
        <t>
          The push service SHOULD return the same subscription set in its response, although
          it MAY return a new subscription set if it is unable to reuse the one provided
          by the user agent.
        </t>
      <figure>
        <artwork type="inline">
  <![CDATA[
HTTP/1.1 201 Created
Date: Thu, 11 Dec 2014 23:56:52 GMT
Link: </push/YBJNBIMwwA_Ag8EtD47J4A>;
        rel="urn:ietf:params:push"
Link: </subscription-set/4UXwi2Rd7jGS7gp5cuutF8ZldnEuvbOy>;
        rel="urn:ietf:params:push:set"
Location: https://push.example.net/subscription/i-nQ3A9Zm4kgSWg8_ZijV
]]></artwork>
      </figure>
      <t>
        A push service MUST return a 400 (Bad Request) status code for requests which
        contain an invalid subscription set. A push service MAY return a 429
        (Too Many Requests) status code <xref target="RFC6585"/> to reject requests
        which omit a subscription set.
      </t>
      <t>
        How a push service detects that requests originate from the same user agent
        is implementation-specific but could take ambient information into
        consideration, such as the TLS connection, source IP address and port.
        Implementers are reminded that some heuristics can produce false
        positives and cause requests to be rejected incorrectly.
      </t>
      </section>
    </section>

    <section anchor="send" title="Requesting Push Message Delivery">
      <t>
        An application server requests the delivery of a push message by sending
        a HTTP POST request to a push resource distributed to the application
        server by a user agent. The content of the push message is included
        in the body of the request.
      </t>
      <figure>
        <artwork type="inline">
  <![CDATA[
POST /push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV HTTP/1.1
Host: push.example.net
TTL: 15
Content-Type: text/plain;charset=utf8
Content-Length: 36

iChYuI3jMzt3ir20P8r_jgRR-dSuN182x7iB
]]></artwork>
      </figure>
      <figure>
        <preamble>
          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 MUST be returned in the Location header field.  This does not
          indicate that the message was delivered to the user agent.
        </preamble>
        <artwork type="inline"><![CDATA[
HTTP/1.1 201 Created
Date: Thu, 11 Dec 2014 23:56:55 GMT
Location: https://push.example.net/message/qDIYHNcfAIPP_5ITvURr-d6BGt
]]></artwork>
      </figure>

      <section anchor="request-receipt" title="Requesting Push Message Receipts">
        <t>
          An application server can include the <xref target="RFC7240">Prefer header
          field</xref> with the "respond-async" preference to request confirmation
          from the push service when a push message is delivered and then acknowledged
          by the user agent. The push service MUST support delivery confirmations.
       </t>
        <figure>
          <artwork type="inline">
            <![CDATA[
POST /push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV HTTP/1.1
Host: push.example.net
Prefer: respond-async
TTL: 15
Content-Type: text/plain;charset=utf8
Content-Length: 36

iChYuI3jMzt3ir20P8r_jgRR-dSuN182x7iB
]]>
          </artwork>
        </figure>
        <figure>
          <preamble>
            When the push service accepts the message for delivery with confirmation, it MUST
            return a 202 (Accepted) response. A URI for the push message resource that was
            created in response to the request MUST be returned in the Location header field.
            The push service MUST also provide a URI for the receipt subscription resource in
            a link relation of type "urn:ietf:params:push:receipt".
          </preamble>
          <artwork type="inline">
            <![CDATA[
HTTP/1.1 202 Accepted
Date: Thu, 11 Dec 2014 23:56:55 GMT
Link: </receipt-subscription/3ZtI4YVNBnUUZhuoChl6omUvG4ZM>;
        rel="urn:ietf:params:push:receipt"
Location: https://push.example.net/message/qDIYHNcfAIPP_5ITvURr-d6BGt
]]>
          </artwork>
        </figure>
        <t>
          For subsequent receipt requests to the same origin <xref target="RFC6454"/>,
          the application server SHOULD include the returned receipt subscription in
          a link relation of type "urn:ietf:params:push:receipt". This gives the push
          service an option to aggregate the receipts. The push service SHOULD return
          the same receipt subscription in its response, although it MAY return a new
          receipt subscription if it is unable to reuse the one provided by the application
          server.
        </t>
        <t>
          An application server MAY omit the receipt subscription if it is
          unable to receive receipts in an aggregated way for the lifetime of
          the receipt subscription. This might be necessary if the application
          server is monitoring receipt subscriptions on the behalf of other
          push message senders.
        </t>
        <t>
          A push service MUST return a 400 (Bad Request) status code for requests which contain
          an invalid receipt subscription. If a push service wishes to limit the number of
          receipt subscriptions that it maintains, it MAY return a 429 (Too Many Requests)
          status code <xref target="RFC6585"/> to reject receipt requests which omit a receipt
          subscription.
        </t>
      </section>

      <section anchor="ttl" title="Push Message Time-To-Live">
        <t>
          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.
        </t>
        <t>
          Delaying delivery might also be used to batch communication with the
          user agent, thereby conserving radio resources.
        </t>
        <t>
          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.
        </t>
        <t>
          An application server MUST include the TTL (Time-To-Live) header field in
          its request for push message delivery. The TTL header field contains a value
          in seconds that suggests how long a push message is retained by the push service.
        </t>
        <figure>
          <preamble>
            The TTL rule specifies a non-negative integer, representing time in seconds.
            A recipient parsing and converting a TTL value to binary form SHOULD use an
            arithmetic type of at least 31 bits of non-negative integer range. If a recipient
            receives a TTL value greater than the greatest integer it can represent, or if any
            of its subsequent calculations overflows, it MUST consider the value to be 2147483648 (2^31).
          </preamble>
          <artwork type="abnf"><![CDATA[
TTL = 1*DIGIT
          ]]></artwork>
        </figure>
        <t>
          A push service MUST return a 400 (Bad Request) status code in response to
          requests that omit the TTL header field.
        </t>
        <t>
          A push service MAY retain a push message for a shorter duration than requested.
          It indicates this by returning a TTL header field in its response with the actual
          TTL.  This TTL value MUST be less than or equal to the value provided by the
          application server.
        </t>
        <t>
          Once the TTL period elapses, the push service MUST NOT attempt to deliver the push
          message to the user agent. A push service might adjust the TTL value to account for
          time accounting errors in processing.  For instance, distributing a push message
          within a server cluster might accrue errors due to clock skew or propagation delays.
        </t>
        <t>
          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.
        </t>
        <t>
          A Push message with a zero TTL is immediately delivered if the user agent is
          available to receive the message. After delivery, the push service is permitted
          to immediately remove a push message with a zero TTL. This might occur before the
          user agent acknowledges receipt of the message by performing a HTTP DELETE on the
          push message resource. Consequently, an application server cannot rely on receiving
          acknowledgement receipts for zero TTL push messages.
        </t>
        <t>
          If the user agent is unavailable, a push message with a zero TTL expires and
          is never delivered.
        </t>

      </section>

      <section anchor="urgency" title="Push Message Urgency">
        <t>
          For a device that is battery-powered, it is often critical that it remains
          dormant for extended periods.  Radio communication in particular consumes
          significant power and limits the length of time that the device can operate.
        </t>
        <t>
          To avoid consuming resources to receive trivial messages, it is helpful
          if an application server can communicate the urgency of a message and if the
          user agent can request that the push server only forward messages of a specific
          urgency.
        </t>
        <t>
          An application server MAY include an Urgency header field in its
          request for push message delivery. This header field indicates the
          message urgency. The push service MUST NOT forward the Urgency header
          field to the user agent.  A push message without the Urgency header
          field defaults to a value of "normal".
        </t>
        <t>
          A user agent MAY include the Urgency header field when monitoring for
          push messages to indicate the lowest urgency of push messages that it
          is willing to receive.  A push service MUST NOT deliver push messages
          with lower urgency than the value indicated by the user agent in its
          monitoring request.  Push messages of any urgency are delivered to a
          user agent that does not include an Urgency header field when
          monitoring for messages.
        </t>
        <figure>
          <artwork type="abnf">
            <![CDATA[
Urgency = urgency-option
urgency-option = ("very-low" / "low" / "normal" / "high")
          ]]>
          </artwork>
        </figure>
        <texttable anchor="urgency_values" title="Illustrative Urgency Values">
          <preamble>
              In order of increasing urgency:
          </preamble>
          <ttcol width='15%' align='center'>Urgency</ttcol>
          <ttcol width='45%' align='left'>Device State</ttcol>
          <ttcol width='40%' align='left'>Example Application Scenario</ttcol>
          <c>very-low</c>
          <c>On power and wifi</c>
          <c>Advertisements</c>
          <c>low</c>
          <c>On either power or wifi</c>
          <c>Topic updates</c>
          <c>normal</c>
          <c>On neither power nor wifi</c>
          <c>Chat or Calendar Message</c>
          <c>high</c>
          <c>Low battery</c>
          <c>Incoming phone call or time-sensitive alert</c>
        </texttable>
        <t>
          Multiple values for the Urgency header
          field MUST NOT be included in requests; otherwise, the push service
          MUST return a 400 (Bad Request) status code.
        </t>
      </section>

      <section anchor="replace" title="Replacing Push Messages">
        <t>
          A push message that has been stored by the push service can be
          replaced with new content.  If the user agent is offline during the
          time that the push messages are sent, updating a push message avoids
          the situation where outdated or redundant messages are sent to the
          user agent.
        </t>
        <t>
          Only push messages that have been assigned a topic can be replaced.  A
          push message with a topic replaces any outstanding push message with
          an identical topic.
        </t>
        <t>
          A push message topic is a string carried in a Topic header field.
          A topic is used to correlate push messages sent to the same subscription and
          does not convey any other semantics.
        </t>
        <t>
          The grammar for the Topic header field uses the <spanx
          style="verb">token</spanx> rule defined in <xref target="RFC7230"/>.
        </t>
        <figure>
          <artwork type="abnf">
            <![CDATA[
Topic = token
          ]]>
          </artwork>
        </figure>
        <t>
          For use with this protocol, the Topic header field MUST be restricted
          to no more than 32 characters from the URL and filename safe Base 64
          alphabet <xref target="RFC4648"/>. A push service that receives a request
          with a Topic header field that does not meet these constraints MUST return
          a 400 (Bad Request) status code to the application server.
        </t>
        <t>
          A push message replacement request creates a new push message resource
          and simultaneously deletes any existing message resource that has a
          matching topic. If an attempt was made to deliver the deleted push
          message, an acknowledgment could arrive at the push service after the
          push message has been replaced.  Delivery receipts for such deleted
          messages SHOULD be suppressed.
        </t>
        <t>
          The replacement request also replaces the stored TTL, Urgency, and any
          receipt subscription associated with the previous message in the
          matching topic.
        </t>
        <t>
          A push message with a topic that is not shared by an outstanding
          message to the same subscription is stored or delivered as normal.
        </t>
        <figure>
          <preamble>
            For example, the following message could cause an existing message
            to be replaced:
          </preamble>
          <artwork type="inline"><![CDATA[
POST /push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV HTTP/1.1
Host: push.example.net
TTL: 600
Topic: upd
Content-Type: text/plain;charset=utf8
Content-Length: 36

ZuHSZPKa2b1jtOKLGpWrcrn8cNqt0iVQyroF
]]></artwork>
        </figure>
        <figure>
          <preamble>
            If the push service identifies an outstanding push message with a
            topic of "upd", then that message resource is deleted. A 201
            (Created) response indicates that the push message replacement was
            accepted. A URI for the new push message resource that was created
            in response to the request is included in the Location header field.
          </preamble>
          <artwork type="inline"><![CDATA[
HTTP/1.1 201 Created
Date: Thu, 11 Dec 2014 23:57:02 GMT
Location: https://push.example.net/message/qDIYHNcfAIPP_5ITvURr-d6BGt
]]></artwork>
        </figure>
        <t>
          The value of the Topic header field MUST NOT be forwarded to user
          agents.  Its value is neither encrypted nor authenticated.
        </t>
      </section>
    </section>

    <section anchor="monitor-subscription" title="Receiving Push Messages for a Subscription">
      <t>
        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 <xref
        target="RFC7540">HTTP/2 server push</xref> to send the
        contents of push messages as they are sent by application servers.
      </t>
      <t>
        A user agent MAY include a Urgency header field in its request. The push service MUST
        NOT deliver messages with lower urgency than the value of the header field
        as defined in the <xref target="urgency_values" format="title"/>.
      </t>
      <t>
        Each push message is pushed as the response to a synthesized GET request
        sent in a PUSH_PROMISE.  This GET request is made to the push message resource
        that was created by the push service when the application server requested
        message delivery.  The response headers SHOULD provide a URI for the push
        resource corresponding to the push message subscription in a link relation
        of type "urn:ietf:params:push". The response body is the entity body from
        the most recent request sent to the push resource by the application server.
      </t>

      <figure>
        <preamble>
          The following example request is made over HTTP/2.
        </preamble>
        <artwork><![CDATA[
HEADERS      [stream 7] +END_STREAM +END_HEADERS
  :method        = GET
  :path          = /subscription/LBhhw0OohO-Wl4Oi971UG
  :authority     = push.example.net
]]></artwork>
      </figure>

      <figure>
        <preamble>
          The push service permits the request to remain outstanding.  When a
          push message is sent by an application server, a server push is generated
          in association with the initial request.  The response for the server push includes the push
          message.
        </preamble>
        <artwork>
          <![CDATA[
PUSH_PROMISE [stream 7; promised stream 4] +END_HEADERS
  :method        = GET
  :path          = /message/qDIYHNcfAIPP_5ITvURr-d6BGt
  :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
  link           = </push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV>;
                    rel="urn:ietf:params:push"
  content-type   = text/plain;charset=utf8
  content-length = 36

DATA         [stream 4] +END_STREAM
  iChYuI3jMzt3ir20P8r_jgRR-dSuN182x7iB

HEADERS      [stream 7] +END_STREAM +END_HEADERS
  :status        = 200
]]>
        </artwork>
      </figure>
      <t>
        A user agent can also request the contents of the push message subscription
        resource immediately by including a <xref target="RFC7240">Prefer header
        field</xref> with a "wait" preference set to "0". In response to this request,
        the push service MUST generate a server push for all push messages that have not yet
        been delivered.
      </t>
      <t>
        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.
      </t>
      <section anchor="monitor-set" title="Receiving Push Messages for a Subscription Set">
        <t>
          There are minor differences between receiving push messages for a subscription and
          a subscription set. If a subscription set is available, the user agent SHOULD use the
          subscription set to monitor for push messages rather than individual push message
          subscriptions.
        </t>
        <t>
          A user agent requests the delivery of new push messages for a collection of
          push message subscriptions by making a GET request to a push message subscription
          set resource. The push service does not respond to this request, it instead uses
          <xref target="RFC7540">HTTP/2 server push</xref> to send the contents of push
          messages as they are sent by application servers.
        </t>
        <t>
          A user agent MAY include a Urgency header field in its request. The push service MUST
          NOT deliver messages with lower urgency than the value of the header field
          as defined in the <xref target="urgency_values" format="title"/>.
        </t>
        <t>
          Each push message is pushed as the response to a synthesized GET request
          sent in a PUSH_PROMISE. This GET request is made to the push message resource
          that was created by the push service when the application server requested
          message delivery. The synthetic request MUST provide a URI for the push resource
          corresponding to the push message subscription in a link relation of type
          "urn:ietf:params:push". This enables the user agent to differentiate the source
          of the message. The response body is the entity body from the most recent request
          sent to the push resource by an application server.
        </t>

        <figure>
          <preamble>
            The following example request is made over HTTP/2.
          </preamble>
          <artwork>
            <![CDATA[
HEADERS      [stream 7] +END_STREAM +END_HEADERS
  :method        = GET
  :path          = /subscription-set/4UXwi2Rd7jGS7gp5cuutF8ZldnEuvbOy
  :authority     = push.example.net
]]>
          </artwork>
        </figure>

        <figure>
          <preamble>
            The push service permits the request to remain outstanding.  When a
            push message is sent by an application server, a server push is
            generated in association with the initial request.  The server push's response includes the push
            message.
          </preamble>
          <artwork>
            <![CDATA[
PUSH_PROMISE [stream 7; promised stream 4] +END_HEADERS
  :method        = GET
  :path          = /message/qDIYHNcfAIPP_5ITvURr-d6BGt
  :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
  link           = </push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV>;
                    rel="urn:ietf:params:push"
  cache-control  = private
  content-type   = text/plain;charset=utf8
  content-length = 36

DATA         [stream 4] +END_STREAM
  iChYuI3jMzt3ir20P8r_jgRR-dSuN182x7iB

HEADERS      [stream 7] +END_STREAM +END_HEADERS
  :status        = 200
]]>
          </artwork>
        </figure>
        <t>
          A user agent can request the contents of the push message subscription
          set resource immediately by including a <xref target="RFC7240">Prefer header
          field</xref> with a "wait" preference set to "0".  In response to this request,
          the push service MUST generate a server push for all push messages that have not
          yet been delivered.
        </t>
        <t>
          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.
        </t>
      </section>

      <section anchor="acknowledge_message"
               title="Acknowledging Push Messages">
        <t>
          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.
        </t>
        <figure>
          <artwork type="inline">
            <![CDATA[
DELETE /message/qDIYHNcfAIPP_5ITvURr-d6BGt HTTP/1.1
Host: push.example.net
]]>
          </artwork>
        </figure>
        <t>
          If the push service receives the acknowledgement and the application
          has requested a delivery receipt, the push service MUST return a 204 (No Content)
          response to the application server monitoring the receipt subscription.
        </t>
        <t>
          If the push service does not receive the acknowledgement within a
          reasonable amount of time, then the message is considered to be not yet
          delivered. The push service SHOULD continue to retry delivery of the message
          until its advertised expiration.
        </t>
        <t>
          The push service MAY cease to retry delivery of the message prior to its
          advertised expiration due to scenarios such as an unresponsive user agent or
          operational constraints. If the application has requested a delivery receipt,
          then the push service MUST return a 410 (Gone) response to the application server
          monitoring the receipt subscription.
        </t>
      </section>

      <section anchor="receive_receipt" title="Receiving Push Message Receipts">
        <t>
          The application server requests the delivery of receipts from the push
          service by making a HTTP GET request to the receipt subscription
          resource. The push service does not respond to this request, it
          instead uses <xref target="RFC7540">HTTP/2 server push</xref> to send push
          receipts when messages are acknowledged (<xref target="acknowledge_message"></xref>)
          by the user agent.
        </t>
        <t>
          Each receipt is pushed as the response to a synthesized GET request sent in a
          PUSH_PROMISE.  This GET request is made to the same push message resource that
          was created by the push service when the application server requested message
          delivery. The response includes a status code indicating the result of the message delivery and carries no data.
        </t>
        <figure>
          <preamble>
            The following example request is made over HTTP/2.
          </preamble>
          <artwork>
            <![CDATA[
HEADERS      [stream 13] +END_STREAM +END_HEADERS
  :method        = GET
  :path          = /receipt-subscription/3ZtI4YVNBnUUZhuoChl6omUvG4ZM
  :authority     = push.example.net
]]>
          </artwork>
        </figure>
        <figure>
          <preamble>
            The push service permits the request to remain outstanding.  When
            the user agent acknowledges the message, the push service pushes a
            delivery receipt to the application server. A 204 (No Content) status code
            confirms that the message was delivered and acknowledged.
          </preamble>
          <artwork>
            <![CDATA[
PUSH_PROMISE [stream 13; promised stream 82] +END_HEADERS
  :method        = GET
  :path          = /message/qDIYHNcfAIPP_5ITvURr-d6BGt
  :authority     = push.example.net

HEADERS      [stream 82] +END_STREAM
                        +END_HEADERS
  :status        = 204
  date           = Thu, 11 Dec 2014 23:56:56 GMT
]]>
          </artwork>
        </figure>
        <t>
          If the user agent fails to acknowledge the receipt of the push message and
          the push service ceases to retry delivery of the message prior to its advertised
          expiration, then the push service MUST push a failure response with a status code
          of 410 (Gone).
        </t>
      </section>
    </section>

    <section anchor="operational" title="Operational Considerations">
      <section anchor="load" title="Load Management">
        <t>
          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.
        </t>
        <t>
          A user agent MUST support the 307 (Temporary Redirect) status code
          <xref target="RFC7231"/>, which can be used by a push service to
          redistribute load at the time that a new subscription is requested.
        </t>
        <t>
          A server that wishes to redistribute load can do so using HTTP alternative
          services <xref target="RFC7838"/>.  HTTP alternative
          services allows for redistribution of load while maintaining the same
          URIs for various resources.  A user agent can ensure a graceful
          transition by using the GOAWAY frame once it has established a
          replacement connection.
        </t>
      </section>

      <section anchor="storage" title="Push Message Expiration">
        <t>
          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 (<xref
          target="ttl"/>).
        </t>
        <t>
          A user agent that does not actively monitor for push messages will not
          receive messages that expire during that interval.
        </t>
        <t>
          Push messages that are stored and have not been delivered to a user agent are
          delivered when the user agent recommences monitoring.  Stored push
          messages SHOULD include a Last-Modified header field (Section 2.2
          of <xref target="RFC7232"/>) indicating when delivery was requested by
          an application server.
        </t>
        <t>
          A GET request to a push message subscription resource with only
          expired messages results in a response as though no push message was
          ever sent.
        </t>
        <t>
          Push services might need to limit the size and number of stored push
          messages to avoid overloading.  To limit the size of messages, the
          push service MAY return a 413 (Payload Too Large) status code <xref target="RFC7231"/>
          in response to requests that include an entity body that is too large.
          Push services MUST NOT return a 413 status code in responses to an entity
          body that is 4096 bytes or less in size.
        </t>
        <t>
          To limit the number of stored push messages, the push service MAY respond with a shorter
          Time-To-Live than proposed by the application server in its request for push message delivery
          (<xref target="ttl"/>). Once a message has been accepted, the push service MAY later expire
          the message prior to its advertised Time-To-Live. If the application server requested a
          delivery receipt, the push service MUST return a failure response (<xref target="acknowledge_message"/>).
        </t>
      </section>

      <section anchor="delete" title="Subscription Expiration">
        <t>
          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.
        </t>
        <t>
          A push service MAY expire a subscription at any time. If there are outstanding
          requests to an expired push message subscription resource (<xref target="monitor-subscription"/>)
          from a user agent or to an expired receipt subscription resource (<xref target="receive_receipt"/>)
          from an application server, this MUST be signaled by returning a 404 (Not Found) status code.
        </t>
        <t>
          A push service MUST return a 404 (Not Found) status code if an application server
          attempts to send a push message to an expired push message subscription.
        </t>
        <t>
          A user agent can remove its push message subscription by sending a DELETE request to
          the corresponding URI. An application server can remove its receipt subscription by
          sending a DELETE request to the corresponding URI.
        </t>
        <section title="Subscription Set Expiration">
          <t>
            A push service MAY expire a subscription set at any time and MUST also
            expire all push message subscriptions in the set. If a user agent has an
            outstanding request to a push subscription set (<xref target="monitor-set"/>)
            this MUST be signaled by returning a 404 (Not Found) status code.
          </t>
          <t>
            A user agent can request that a subscription set be removed by sending a DELETE
            request to the subscription set URI. This MUST also remove all push message
            subscriptions in the set.
          </t>
          <t>
            If a specific push message subscription that is a member of a subscription set is
            expired or removed, then it MUST also be removed from its subscription set.
          </t>
        </section>
      </section>

      <section title="Implications for Application Reliability">
        <t>
          A push service 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 and maintain
          (usually secure) connections to the individual application servers.
        </t>
        <t>
          Push message reliability can be important if messages contain
          information critical to the state of an application.  Repairing state
          can be expensive, particularly for devices with limited communications
          capacity.  Knowing that a push message has been correctly received
          avoids retransmissions, polling, and state resynchronization.
        </t>
        <t>
          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.
        </t>
        <t>
          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).
        </t>
      </section>
      <section anchor="sets-streams" title="Subscription Sets and Concurrent HTTP/2 streams">
        <t>
          If the push service requires that the user agent use push message subscription sets,
          then it MAY limit the number of concurrently active streams with the
          SETTINGS_MAX_CONCURRENT_STREAMS parameter within a HTTP/2 SETTINGS frame <xref target="RFC7540"/>.
          The user agent MAY be limited to one concurrent stream to manage push message
          subscriptions and one concurrent stream for each subscription set returned by the push service.
          This could force the user agent to serialize subscription requests to the push
          service.
        </t>
      </section>
    </section>

    <section anchor="security" title="Security Considerations">
      <t>
        This protocol MUST use <xref target="RFC2818">HTTP over TLS</xref>
        following the recommendations in <xref target="RFC7525"/>.  This
        includes any communications between user agent and push service, plus
        communications between the application server 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.
      </t>

      <section title="Confidentiality from Push Service Access">
        <t>
          The protection afforded by TLS does not protect content from the push
          service.  Without additional safeguards, a push service can inspect
          and modify the message content.
        </t>
        <t>
          Applications using this protocol MUST use mechanisms that provide
          end-to-end confidentiality, integrity and data origin authentication.
          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 distribution of
          subscription information from the user agent to its application server
          also offers a convenient medium for key agreement.
        </t>
        <t>
          For this requirement, the <xref target="API">W3C Push API</xref> has adopted
          <xref target="I-D.ietf-webpush-encryption">Message Encryption for WebPush</xref>
          to secure the content of messages from the push service. Other scenarios can
          be addressed by similar policies.
        </t>
        <t>
          The Topic header field exposes information that allows more granular
          correlation of push messages on the same subject.  This might be used
          to aid traffic analysis of push messages by the push service.
        </t>
     </section>

     <section title="Privacy Considerations">
       <t>
         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.
       </t>
       <t>
         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.  Of course, this does not prevent
         correlation using other information that a user agent might expose.
       </t>
       <t>
         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.
       </t>
       <t>
         User and device information MUST NOT be exposed through a push or push
         message URI.
       </t>
       <t>
         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.
         <list style="hanging">
           <t hangText="Note:">
             This need not be perfect as long as the resulting anonymity set
             (<xref target="RFC6973"/>, Section 6.1.1) is sufficiently
             large.  A push URI necessarily identifies a push service or a
             single server instance.  It is also possible that traffic analysis
             could be used to correlate subscriptions.
           </t>
         </list>
       </t>
       <t>
         A user agent MUST be able to create new subscriptions with new
         identifiers at any time.
       </t>
     </section>

     <section anchor="authorization" title="Authorization">
       <t>
         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 multiple options (including experimental
         options) with varying levels of security. The authorization
         process and any associated credentials are expected to be configured in the
         user agent along with the URI for the push service.
       </t>
       <t>
         Authorization is managed using capability URLs for the push message
         subscription, push, and receipt subscription resources (<xref target="CAP-URI"/>).
         A capability URL grants access to a resource based solely on knowledge of the URL.
       </t>
       <t>
         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.
       </t>
       <t>
         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.
       </t>
       <t>
         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.
       </t>
     </section>

     <section title="Denial of Service Considerations">
       <t>
         A user agent can control where valid push messages originate by
         limiting the distribution of push URIs to authorized application servers.
         Ensuring that push URIs are hard to guess ensures that only application
         servers that have received a push URI can use it.
       </t>
       <t>
         Push messages that are not successfully authenticated by the user agent
         will not be delivered, but this can present a denial of service risk. Even a
         relatively small volume of push messages can cause battery-powered devices
         to exhaust power reserves.
       </t>
       <t>
         To address this case, the <xref target="API">W3C Push API</xref> has adopted
         <xref target="I-D.ietf-webpush-vapid">Voluntary Application Server Identification</xref>,
         which allows a user agent to restrict a subscription to a specific application
         server. The push service can then identify and reject unwanted messages without
         contacting the user agent.
       </t>
       <t>
         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.
       </t>
       <t>
         A push service MAY return a 429 (Too Many Requests) status code <xref target="RFC6585"/>
         when an application server has exceeded its rate limit for push message delivery to
         a push resource. The push service SHOULD also include a Retry-After header
         <xref target="RFC7231"/> to indicate how long the application server
         is requested to wait before it makes another request to the push resource.
       </t>
       <t>
         A push service or user agent MAY also <xref target="delete">terminate subscriptions</xref>
         that receive too many push messages.
       </t>
       <t>
         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.
       </t>
     </section>

     <section title="Logging Risks">
       <t>
         Server request logs can reveal subscription-related URIs or relationships
         between subscription-related URIs for the same user agent.
         Limitations on log retention and strong access control mechanisms can
         ensure that URIs are not revealed to unauthorized entities.
       </t>
     </section>

    </section>

    <section anchor="iana" title="IANA Considerations">
      <t>
        This protocol defines new HTTP header fields in <xref
        target="iana.header.fields"/>.  New link relation types are identified
        using the URNs defined in <xref target="iana.urns"/>. Port registration is
        defined in <xref target="iana.port"/>
      </t>

      <section anchor="iana.header.fields" title="Header Field Registrations">
        <t>
          HTTP header fields are registered within the "Message Headers"
          registry maintained at <eref
          target="https://www.iana.org/assignments/message-headers/"/>.
        </t>
        <t>
          This document defines the following HTTP header fields, so their
          associated registry entries shall be added according to the permanent
          registrations below (<xref target="RFC3864"/>):
        </t>
        <texttable align="left" suppress-title="true"
                   anchor="iana.header.registration.table">
          <ttcol>Header Field Name</ttcol>
          <ttcol>Protocol</ttcol>
          <ttcol>Status</ttcol>
          <ttcol>Reference</ttcol>

          <c>TTL</c>
          <c>http</c>
          <c>standard</c>
          <c>
            <xref target="ttl"/>
          </c>
          <c>Urgency</c>
          <c>http</c>
          <c>standard</c>
          <c>
            <xref target="urgency"/>
          </c>
          <c>Topic</c>
          <c>http</c>
          <c>standard</c>
          <c>
            <xref target="replace"/>
          </c>
        </texttable>
        <t>
          The change controller is: "IETF (iesg@ietf.org) - Internet
          Engineering Task Force".
        </t>
      </section>

      <section anchor="iana.urns" title="Link Relation URNs">
        <t>
          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 <xref target="RFC3553"/>;
          the corresponding "push" sub-namespace is entered in the "IETF URN
          Sub-namespace for Registered Protocol Parameter Identifiers"
          registry.
        </t>
        <t>
          The "Web Push Identifiers" registry operates under the <xref
          target="RFC5226">IETF Review policy</xref>.
          <list style="hanging">
            <t hangText="Registry name:">Web Push Identifiers</t>
            <t hangText="URN Prefix:">urn:ietf:params:push</t>
            <t hangText="Specification:">(this document)</t>
            <t hangText="Repository:">[Editor/IANA note: please include a link
            to the final registry location.]</t>
            <t hangText="Index value:">Values in this registry are URNs or URN
            prefixes that start with the prefix <spanx
            style="verb">urn:ietf:params:push</spanx>.  Each is registered
            independently.</t>
          </list>
        </t>
        <t>
          New registrations in the "Web Push Identifiers" are encouraged to
          include the following information:
          <list style="hanging">
            <t hangText="URN:">A complete URN or URN prefix.</t>
            <t hangText="Description:">A summary description.</t>
            <t hangText="Specification:">A reference to a specification
            describing the semantics of the URN or URN prefix.</t>
            <t hangText="Contact:">Email for the person or group making the
            registration.</t>
            <t hangText="Index value:">As described in <xref target="RFC3553"/>,
            URN prefixes that are registered include a description of how the
            URN is constructed.  This is not applicable for specific URNs.</t>
          </list>
        </t>
        <t>
          These values are entered as the initial content of the "Web Push
          Identifiers" registry.
        </t>
        <t>
          <list style="hanging">
            <t hangText="URN:">urn:ietf:params:push</t>
            <t hangText="Description:">This link relation type is used to
            identify a resource for sending push messages.</t>
            <t hangText="Specification:">(this document)</t>
            <t hangText="Contact:">The Web Push WG (webpush@ietf.org)</t>
          </list>
        </t>
        <t>
          <list style="hanging">
            <t hangText="URN:">urn:ietf:params:push:set</t>
            <t hangText="Description:">
              This link relation type is used to identify a collection of push
              message subscriptions.
            </t>
            <t hangText="Specification:">(this document)</t>
            <t hangText="Contact:">The Web Push WG (webpush@ietf.org)</t>
          </list>
        </t>
        <t>
          <list style="hanging">
            <t hangText="URN:">urn:ietf:params:push:receipt</t>
            <t hangText="Description:">
              This link relation type is used to identify a resource for
              receiving delivery confirmations for push messages.
            </t>
            <t hangText="Specification:">(this document)</t>
            <t hangText="Contact:">The Web Push WG (webpush@ietf.org)</t>
          </list>
        </t>
      </section>
      <section title="Service Name and Port Number Registration" anchor="iana.port">
        <t>
          Service names and port numbers are registered within the "Service Name and
          Transport Protocol Port Number Registry" maintained at <eref
          target="https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml"/>.
        </t>
        <t>
          In accordance with <xref target="RFC6335"/>, it is requested that IANA assign
          the suggested System Port number 1001 (or another port in the System range) and
          the service name “webpush”.


          <list style="hanging">
            <t hangText="Service Name:">
              <vspace />
              webpush</t>
            <t hangText="Transport Protocol:">
              <vspace />
              tcp</t>
            <t hangText="Assignee:">
              <vspace />
              The IESG (iesg@ietf.org)
            </t>
            <t hangText="Contact:">
              <vspace />
              The IETF Chair (chair@ietf.org)
            </t>
            <t hangText="Description:">
              <vspace />
              HTTP Web Push
            </t>
            <t hangText="Reference:">
              <vspace />
              [RFCthis]
            </t>
            <t hangText="Port Number:">
              <vspace />
              1001
            </t>
          </list>
        </t>
        <t>[[The RFC Editor is requested to remove this editorial note at publication.]]</t>
        <t>
          This document uses a placeholder value for a system port pending IANA assignment which
          needs to be replaced with the finalized value at the time of publication. Please apply
          the following replacement:
          <list style="symbols">
            <t>
              "WEBPUSH-PORT" --> the assigned port value for "webpush"
            </t>
          </list>
        </t>
        </section>
    </section>

    <section title="Acknowledgements">
      <t>
        Significant technical input to this document has been provided by Ben
        Bangert, Peter Beverloo, Kit Cambridge, JR Conlin, Lucas Jenss, Matthew Kaufman,
        Costin Manolache, Mark Nottingham, Idel Pivnitskiy, Robert Sparks,
        Darshak Thakore and many others.
      </t>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      <reference anchor="RFC2119">
        <front>
          <title>
            Key words for use in RFCs to Indicate Requirement Levels
          </title>
          <author initials="S." surname="Bradner" fullname="Scott Bradner">
            <organization>Harvard University</organization>
            <address><email>sob@harvard.edu</email></address>
          </author>
          <date month="March" year="1997"/>
        </front>
        <seriesInfo name="BCP" value="14"/>
        <seriesInfo name="RFC" value="2119"/>
      </reference>

     <reference anchor="RFC2818">
        <front>
          <title>
            HTTP Over TLS
          </title>
          <author initials="E." surname="Rescorla" fullname="Eric Rescorla"/>
          <date month="May" year="2000"/>
        </front>
        <seriesInfo name="RFC" value="2818"/>
      </reference>

      <reference anchor="RFC3553">
        <front>
          <title>An IETF URN Sub-namespace for Registered Protocol Parameters</title>
          <author initials="M." surname="Mealling" fullname="M. Mealling">
          <organization /></author>
          <author initials="L." surname="Masinter" fullname="L. Masinter">
          <organization /></author>
          <author initials="T." surname="Hardie" fullname="T. Hardie">
          <organization /></author>
          <author initials="G." surname="Klyne" fullname="G. Klyne">
          <organization /></author>
          <date year="2003" month="June" />
        </front>

        <seriesInfo name="BCP" value="73" />
        <seriesInfo name="RFC" value="3553" />
        <format type="TXT" octets="14815" target="http://www.rfc-editor.org/rfc/rfc3553.txt" />
      </reference>

      <reference anchor="RFC3864">
        <front>
          <title>Registration Procedures for Message Header Fields</title>
          <author initials="G." surname="Klyne" fullname="G. Klyne">
          <organization /></author>
          <author initials="M." surname="Nottingham" fullname="M. Nottingham">
          <organization /></author>
          <author initials="J." surname="Mogul" fullname="J. Mogul">
          <organization /></author>
          <date year="2004" month="September" />
        </front>
        <seriesInfo name="BCP" value="90" />
        <seriesInfo name="RFC" value="3864" />
        <format type="TXT" octets="36231" target="http://www.rfc-editor.org/rfc/rfc3864.txt" />
      </reference>
      <reference anchor="RFC4648">
        <front>
          <title>The Base16, Base32, and Base64 Data Encodings</title>
          <author initials="S." surname="Josefsson" fullname="S. Josefsson">
            <organization />
          </author>
          <date year="2006" month="October" />
        </front>
        <seriesInfo name="RFC" value="4648" />
        <format type="TXT" target="http://www.rfc-editor.org/rfc/rfc4648.txt" />
      </reference>
      <reference anchor="RFC5226">
        <front>
          <title>Guidelines for Writing an IANA Considerations Section in RFCs</title>
          <author initials="T." surname="Narten" fullname="T. Narten">
          <organization /></author>
          <author initials="H." surname="Alvestrand" fullname="H. Alvestrand">
          <organization /></author>
          <date year="2008" month="May" />
        </front>
        <seriesInfo name="BCP" value="26" />
        <seriesInfo name="RFC" value="5226" />
        <format type="TXT" octets="66160" target="http://www.rfc-editor.org/rfc/rfc5226.txt" />
      </reference>
      <reference anchor="RFC5382">
        <front>
          <title>NAT Behavioral Requirements for TCP</title>
          <author initials="K." surname="Biswas" fullname="K. Biswas">
            <organization />
          </author>
          <author initials="B." surname="Ford" fullname="B. Ford">
            <organization />
          </author>
          <author initials="S." surname="Sivakumar" fullname="S. Sivakumar">
            <organization />
          </author>
          <author initials="P." surname="Srisuresh" fullname="P. Srisuresh">
            <organization />
          </author>
          <date year="2008" month="October"/>
        </front>
        <seriesInfo name="RFC" value="5382" />
        <format type="TXT" target="http://www.rfc-editor.org/rfc/rfc5382.txt" />
      </reference>
      <reference anchor="RFC5988">
        <front>
          <title>Web Linking</title>
          <author initials="M." surname="Nottingham" fullname="M. Nottingham">
          <organization /></author>
          <date year="2010" month="October" />
        </front>
        <seriesInfo name="RFC" value="5988" />
        <format type="TXT" octets="46834" target="http://www.rfc-editor.org/rfc/rfc5988.txt" />
      </reference>
      <reference anchor="RFC6335">
        <front>
          <title>
            Internet Assigned Numbers Authority (IANA) Procedures for the Management of the Service Name and Transport Protocol Port Number Registry
          </title>
          <author initials="M." surname="Cotton" fullname="M. Cotton">
            <organization />
          </author>
          <author initials="L." surname="Eggert" fullname="L. Eggert">
            <organization />
          </author>
          <author initials="J." surname="Touch" fullname="J. Touch">
            <organization />
          </author>
          <author initials="M." surname="Westerlund" fullname="M. Westerlund">
            <organization />
          </author>
          <author initials="S." surname="Cheshire" fullname="S. Cheshire">
            <organization />
          </author>
          <date year="2011" month="August" />
        </front>
        <seriesInfo name="RFC" value="6335" />
        <format type="TXT" target="http://www.rfc-editor.org/rfc/rfc6335.txt" />
      </reference>
      <reference anchor="RFC6454">
        <front>
          <title>The Web Origin Concept</title>
          <author initials="A." surname="Barth" fullname="A. Barth">
            <organization />
          </author>
          <date year="2011" month="December" />
        </front>
        <seriesInfo name="RFC" value="6454" />
        <format type="TXT" target="http://www.rfc-editor.org/rfc/rfc6454.txt" />
      </reference>
      <reference anchor="RFC6585">
        <front>
          <title>Additional HTTP Status Codes</title>
          <author initials="M." surname="Nottingham" fullname="M. Nottingham">
          <organization /></author>
          <author initials="R." surname="Fielding" fullname="R. Fielding">
          <organization /></author>
          <date year="2012" month="April" />
        </front>
        <seriesInfo name="RFC" value="6585" />
        <format type="TXT" target="http://www.rfc-editor.org/rfc/rfc6585.txt" />
      </reference>
      <reference anchor="RFC7230">
        <front>
          <title>Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing</title>
          <author initials="R." surname="Fielding" fullname="R. Fielding">
          <organization /></author>
          <author initials="J." surname="Reschke" fullname="J. Reschke">
          <organization /></author>
          <date year="2014" month="June" />
        </front>
        <seriesInfo name="RFC" value="7230" />
        <format type="TXT" octets="205947" target="http://www.rfc-editor.org/rfc/rfc7230.txt" />
      </reference>

      <reference anchor="RFC7231">
        <front>
          <title>Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content</title>
          <author initials="R." surname="Fielding" fullname="R. Fielding">
          <organization /></author>
          <author initials="J." surname="Reschke" fullname="J. Reschke">
          <organization /></author>
          <date year="2014" month="June" />
        </front>
        <seriesInfo name="RFC" value="7231" />
        <format type="TXT" octets="235053" target="http://www.rfc-editor.org/rfc/rfc7231.txt" />
      </reference>

      <reference anchor="RFC7232">
        <front>
          <title>Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests</title>
          <author initials="R." surname="Fielding" fullname="R. Fielding">
          <organization /></author>
          <author initials="J." surname="Reschke" fullname="J. Reschke">
          <organization /></author>
          <date year="2014" month="June" />
        </front>
        <seriesInfo name="RFC" value="7232" />
        <format type="TXT" octets="56696" target="http://www.rfc-editor.org/rfc/rfc7232.txt" />
      </reference>

      <reference anchor="RFC7240">
        <front>
          <title>Prefer Header for HTTP</title>
          <author initials="J." surname="Snell" fullname="J. Snell">
          <organization /></author>
          <date year="2014" month="June" />
        </front>
        <seriesInfo name="RFC" value="7240" />
        <format type="TXT" octets="32796" target="http://www.rfc-editor.org/rfc/rfc7240.txt" />
      </reference>

      <reference  anchor="RFC7525">
        <front>
          <title>Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)</title>
          <author initials="Y." surname="Sheffer" fullname="Y. Sheffer">
            <organization />
          </author>
          <author initials="R." surname="Holz" fullname="R. Holz">
            <organization />
          </author>
          <author initials="P." surname="Saint-Andre" fullname="P. Saint-Andre">
            <organization />
          </author>
          <date year="2015" month="May" />
        </front>
        <seriesInfo name="BCP" value="195"/>
        <seriesInfo name="RFC" value="7525"/>
        <seriesInfo name="DOI" value="10.17487/RFC7525"/>
        <format type="TXT"
                target="http://www.rfc-editor.org/rfc/rfc7525.txt" />
      </reference>

      <reference anchor="RFC7540">
        <front>
          <title>Hypertext Transfer Protocol Version 2</title>
          <author initials="M" surname="Belshe" fullname="Mike Belshe">
            <organization />
          </author>
          <author initials="R" surname="Peon" fullname="Roberto Peon">
            <organization />
          </author>
          <author initials="M" surname="Thomson" fullname="Martin Thomson">
            <organization />
          </author>
          <date year="2015" month="May" />
        </front>
        <seriesInfo name="RFC" value="7540" />
        <format type="TXT"
                target="http://www.rfc-editor.org/rfc/rfc7540.txt" />
      </reference>

      <reference anchor="RFC7838">
        <front>
          <title>HTTP Alternative Services</title>
          <author initials="M" surname="Nottingham" fullname="Mark Nottingham">
            <organization />
          </author>
          <author initials="P" surname="McManus" fullname="Patrick McManus">
            <organization />
          </author>
          <author initials="J" surname="Reschke" fullname="Julian Reschke">
            <organization />
          </author>
          <date year="2016" month="April" />
        </front>
        <seriesInfo name="RFC" value="7838" />
        <format type="TXT"
                target="http://www.rfc-editor.org/rfc/rfc7838.txt" />
      </reference>

      <reference anchor="CAP-URI" target="http://www.w3.org/TR/capability-urls/">
        <front>
          <title>Good Practices for Capability URLs</title>
          <author initials="J." surname="Tennison" fullname="Jeni Tennison"/>
          <date month="February" year="2014"/>
        </front>
        <seriesInfo name="FPWD" value="capability-urls"/>
      </reference>
    </references>

    <references title="Informative References">
      <reference anchor="I-D.ietf-webpush-encryption" target="https://tools.ietf.org/pdf/draft-ietf-webpush-encryption-04.pdf">
        <front>
          <title>Message Encryption for Web Push</title>
          <author initials="M." surname="Thomson" fullname="Martin Thomson" />
          <date month="October" year="2016" />
        </front>
        <seriesInfo name="Internet-Draft" value="draft-ietf-webpush-encryption-04"/>
      </reference>
      <reference anchor="I-D.ietf-webpush-vapid" target="https://tools.ietf.org/pdf/draft-ietf-webpush-vapid-01.pdf">
        <front>
          <title>Voluntary Application Server Identification for Web Push</title>
          <author initials="M." surname="Thomson" fullname="Martin Thomson" />
          <author initials="P." surname="Beverloo" fullname="Peter Beverloo" />
          <date month="June" year="2016" />
        </front>
        <seriesInfo name="Internet-Draft" value="draft-ietf-webpush-vapid-01"/>
      </reference>
      <reference anchor="API" target="https://w3c.github.io/push-api/">
        <front>
          <title>W3C Push API</title>
          <author initials="M." surname="van Ouwerkerk" fullname="Michael van Ouwerkerk"/>
          <author initials="M." surname="Thomson" fullname="Martin Thomson" />
          <author initials="B." surname="Sullivan" fullname="Bryan Sullivan"/>
          <author initials="E." surname="Fullea" fullname="Eduardo Fullea"/>
          <date month="August" year="2016" />
        </front>
        <seriesInfo name="ED" value="push-api" />
      </reference>

      <reference anchor="RFC6973">
        <front>
          <title>Privacy Considerations for Internet Protocols</title>
          <author initials="A." surname="Cooper" fullname="A. Cooper">
          <organization /></author>
          <author initials="H." surname="Tschofenig" fullname="H. Tschofenig">
          <organization /></author>
          <author initials="B." surname="Aboba" fullname="B. Aboba">
          <organization /></author>
          <author initials="J." surname="Peterson" fullname="J. Peterson">
          <organization /></author>
          <author initials="J." surname="Morris" fullname="J. Morris">
          <organization /></author>
          <author initials="M." surname="Hansen" fullname="M. Hansen">
          <organization /></author>
          <author initials="R." surname="Smith" fullname="R. Smith">
          <organization /></author>
          <date year="2013" month="July" />
        </front>
        <seriesInfo name="RFC" value="6973" />
        <format type="TXT" octets="89198" target="http://www.rfc-editor.org/rfc/rfc6973.txt" />
      </reference>

    </references>

    <section title="Change Log">
      <t>[[The RFC Editor is requested to remove this section at publication.]]</t>
      <section title="Since draft-ietf-webpush-protocol-00" anchor="changes.since.draft-ietf-webpush-protocol-00">
        <t>
          Editorial changes for Push Message Time-To-Live
        </t>
        <t>
          Editorial changes for Push Acknowledgements
        </t>
        <t>
          Removed subscription expiration based on HTTP cache headers
        </t>
      </section>
      <section title="Since draft-ietf-webpush-protocol-01" anchor="changes.since.draft-ietf-webpush-protocol-01">
        <t>
          Added Subscription Sets
        </t>
        <t>
          Added System Port as an alternate service with guidance for idle timeouts
        </t>
        <t>
          Finalized status codes for acknowledgements
        </t>
        <t>
          Editorial changes for Rate Limits
        </t>
      </section>
      <section title="Since draft-ietf-webpush-protocol-02" anchor="changes.since.draft-ietf-webpush-protocol-02">
        <t>
          Added explicit correlation for Subscription Sets
        </t>
        <t>
          Added Push Message Updates (message collapsing)
        </t>
        <t>
          Renamed the push:receipt link relation to push:receipts and transitioned the
          Push-Receipt header field to the push:receipt link relation type
        </t>
      </section>
      <section title="Since draft-ietf-webpush-protocol-03" anchor="changes.since.draft-ietf-webpush-protocol-03">
        <t>
          An application server MUST include the TTL (Time-To-Live) header field in
          its request for push message delivery.
        </t>
        <t>
          Added Push Message Urgency header field
        </t>
      </section>
      <section title="Since draft-ietf-webpush-protocol-04" anchor="changes.since.draft-ietf-webpush-protocol-04">
        <t>
          Simplified design for Push Receipts and eliminated the urn:ietf:params:push:receipts link
          relation
        </t>
        <t>
          Clarified Security Considerations section and added informative references to
          Message Encryption and Voluntary Application Server Identification
        </t>
      </section>
      <section title="Since draft-ietf-webpush-protocol-05" anchor="changes.since.draft-ietf-webpush-protocol-05">
        <t>
          Addressed feedback from Working Group Last Call
        </t>
      </section>
      <section title="Since draft-ietf-webpush-protocol-06" anchor="changes.since.draft-ietf-webpush-protocol-06">
        <t>
          Updated informative references to W3C Push API, Message Encryption, and Voluntary
          Application Server Identification
        </t>
      </section>
      <section title="Since draft-ietf-webpush-protocol-07" anchor="changes.since.draft-ietf-webpush-protocol-07">
        <t>
          Minor editorial changes
        </t>
      </section>
      <section title="Since draft-ietf-webpush-protocol-08" anchor="changes.since.draft-ietf-webpush-protocol-08">
        <t>
          Minor correction to Acknowledgements
        </t>
        <t>
          Updated dates for informative references
        </t>
      </section>
      <section title="Since draft-ietf-webpush-protocol-09" anchor="changes.since.draft-ietf-webpush-protocol-09">
        <t>
          Updates for Area Director (Alissa Cooper) evaluation
        </t>
      </section>
      <section title="Since draft-ietf-webpush-protocol-10" anchor="changes.since.draft-ietf-webpush-protocol-10">
        <t>
          Updates for TSV-ART review from Magnus Westerlund
        </t>
        <t>
          Updated informative reference for Message Encryption
        </t>
      </section>
      <section title="Since draft-ietf-webpush-protocol-11" anchor="changes.since.draft-ietf-webpush-protocol-11">
        <t>
          Updates from IESG Evaluation
        </t>
      </section>
    </section>
  </back>
</rfc>