Draft: draft-thomson-webpush-protocol

Commentary: registration references details on the subscription split - monitor and push resources the resource section 
 I have a question of whether the draft can generically refer to the " monitor " and " push " resources as Subscription URI(s ) in many cases . There are some cases such as expiration where it may be more appropriate to be specific about the resource . 
 This is looking pretty good . A few minor points to clean up , but otherwise we are good . It might make sense to take a look at the use of terminology for URIs . A lot of the security and privacy stuff talks about " Subscription URIs " , but with the split it might make sense to avoid mention of them altogether and talk about the specific types . 
 I 've a few TODO notes , but I 'm merging this and fix them later .
Paragraph (version A):
A session that is established between the user agent and the push
service.  A registation has any number of associated
subscriptions.
Paragraph (version A):
At the very beginning of the process, the user agent creates a
registration resource at the push service.  The registration is the
basis of all future interactions between the user agent and push
service.  The registration aggregates push messages that the user
agent receives from all subscriptions.
Paragraph (version A):
The registration resource describes how the user agent is expected to
monitor for incoming push messages.  This document describes one such
mechanism, though more efficient means of monitoring could be
defined.
Paragraph (version A):
The registration resource also describes how the user agent might
create a subscription.  A new subscription is created by the user
agent and then distributed by to an application server.
Paragraph (version A):
It is expected that a different subscription will be provided 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 can have
security and privacy implications.
Paragraph (version A):
Application servers use subscriptions to deliver push messages to
user agents, via the push service.
Paragraph (version A):
Both registrations and subscriptions have a limited lifetime.  They
can also be terminated by either push service or user agent at any
time.  User agents and application servers need to be prepared to
handle changes in registrations and subscriptions; the protocol
described here supports any number of either resource concurrently
with minimal overhead.
Paragraph (version A):
This resource is used in register.  It is configured into user
agents.
Paragraph (version A):
A link relation of type "urn:ietf:params:push:reg" refers to a
registration resource.  This resource is used by a user agent in
requesting the delivery of push messages.  A process for
monitoring for messages using this resource is described in
monitor.
Paragraph (version A):
A link relation of type "urn:ietf:params:push:sub" refers to a
resource where a user agent can create new subscriptions.
Creating a subscription is described in subscribe.
Paragraph (version A):
A link relation of type "urn:ietf:params:push" refers to a
subscription resource.  Subscription resources are used to deliver
push messages.  An application server send and a user agent
monitor using this resource.
Paragraph (version A):
A user agent that wishes to establish a new or replacement
registration sends an HTTP POST request to its configured push
service resource.
Paragraph (version A):
A request to create a registration contains no entity body.  A future
specification MAY define a format and semantics for the entity body
on this request.
Paragraph (version A):
The push service creates a new registration and subscribe resource in
response to this request.  URIs for these resources are included in
Link header fields in the response.  The push server includes the
"registration" link relation in a Location header field.
Paragraph (version A):
The push server SHOULD provide a URI for the associated "subscribe"
resource and any known expiration information in response to requests
to the "registration" resource.
Paragraph (version A):
A user agent sends a POST request to the "subscribe" resource to
create a new subscription.
Paragraph (version A):
A response with a 201 (Created) status code includes a URI for the
subscription in the Location header field.
Paragraph (version A):
A push subscription is an RFC7230.
Paragraph (version A):
An application server requests the delivery of a push message by
sending an HTTP PUT request to this resource, including the push
message in the body of the request.
Paragraph (version A):
A push service MAY generate a 413 (Payload Too Large) status code in
response to PUT 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.
Paragraph (version A):
A push service that does not store messages can stream the payload of
push messages to the user agent.  Flow control SHOULD be used to
limit the state commitment for delivery of large messages.
Paragraph (version A):
A push service can improve the reliability of push message delivery
considerably by storing push messages for a period.  User agents are
often only intermittendly connected, and so benefit from having short
term message storage at the push service.
Paragraph (version B):
At the very beginning of the process, a new subscription is created
by the user agent and then distributed to its application server.
The subscription is the basis of all future interactions between the
actors.
Paragraph (version B):
A "subscription" resource grants the rights to receive messages
from a subscription and to delete a subscription.  It is private
to the user agent.
Paragraph (version B):
A "push" resource grants the right to send messages to a
subscription.  It is public and shared by the the user agent with
its application server.
Paragraph (version B):
It is expected that a unique subscription will be provided 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.
Paragraph (version B):
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.
Paragraph (version B):
This resource is used in subscribe.  It is configured into user
agents.
Paragraph (version B):
A link relation of type "urn:ietf:params:push:subscription" refers
to a resource with read and delete access to a subscription.  A
user agent monitor using this resource.
Paragraph (version B):
A link relation of type "urn:ietf:params:push" refers to a
resource with write access to a subscription.  An application
server send using this resource.
Paragraph (version B):
A user agent sends a POST request to its configured push service
resource to create a new subscription.  If successful, the push
service MUST return new "subscription" and "push" resources in
response to this request.  URIs for these resources are included in
Link header fields in the response.
Paragraph (version B):
A response with a 201 (Created) status code includes a URI for the
"subscription" resource in the Location header field.
Paragraph (version B):
An application server requests the delivery of a push message by
sending a HTTP request to the "push" resource distributed by its user
agent.  The push message is included in the body of the request.
Paragraph (version B):
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.
Paragraph (version B):
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.
Paragraph (version A):
A user agent requests the delivery of new push messages by making a
GET request to the "registration" resource.  The push service does
not respond to this request, it instead uses I-D.ietf-httpbis-http2
to send the contents of push messages as they are sent by application
servers.
Paragraph (version A):
Each push message is pushed in response to a synthesized GET request.
The GET request is made to the same "subscription" URI that is used
by the application server to send the message.  The response body is
the entity body from the most recent PUT request sent to the
subscription resource.
Paragraph (version A):
A user agent can request the contents of the "registration" resource
immediately by including a RFC7240 with a "wait" parameter set to
"0".  The push server SHOULD return a link reference to the
"registration" resource and expiration information in response to
this request.  This request also triggers the delivery of all push
messages that the push service has stored but not yet delivered.  The
server MUST generate a server push for all stored messages that have
not yet been delivered.
Paragraph (version A):
A user agent can request the last push message for a "subscription"
resource by sending GET requests to its URI.  A 200 (OK) status
response contains the last push message sent to the subscription.  A
204 (No Content) status code indicates that no messages are presently
available.
Paragraph (version A):
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 registration is requested.
Paragraph (version B):
A user agent requests the delivery of new push messages by making a
GET request to a "subscription" resource.  The push service does not
respond to this request, it instead uses I-D.ietf-httpbis-http2 to
send the contents of push messages as they are sent by application
servers.
Paragraph (version B):
Each push message is pushed in response to a synthesized GET request.
The GET request is made to the same "push" resource that is used by
the application server to send the message.  The response body is the
entity body from the most recent request sent to the "push" resource.
Paragraph (version B):
A user agent can request the contents of the "subscription" resource
immediately by including a RFC7240 with a "wait" parameter set to
"0".  The push server SHOULD return a link reference to the "push"
resource and expiration information in response to this request.
This request also triggers the delivery of all push messages that the
push service has stored but not yet delivered.  The server MUST
generate a server push for all stored messages that have not yet been
delivered.
Paragraph (version B):
A 204 (No Content) status code with no associated server pushes
indicates that no messages are presently available.
Paragraph (version B):
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.
Paragraph (version A):
In some cases, it may be necessary to terminate registrations or
subscriptions so that they can be refreshed.
Paragraph (version B):
In some cases, it may be necessary to terminate subscriptions so that
they can be refreshed.
Paragraph (version A):
A push service can invalidate a registration or subscription at any
time.  If a user agent has an outstanding request to the
"registration" resource (see monitor), this can be signaled by
returning a 400-series status code, such as 410 (Gone).  A push
service uses server push to indicate that a subscription has expired;
a pushed 400-series status code for the subscription resource signals
the termination of a subscription.
Paragraph (version A):
A user agent can request that a registration or subscription be
removed by sending a DELETE request to the corresponding URI.
Removing a registration causes all associated subscriptions to be
removed.  Requests to delete a subscription MUST be authenticated;
the URI for subscriptions will be known by multiple entities, most of
whom will not be authorized to remove the subscription.
Paragraph (version A):
A push service MUST send a 400-series status code, such as 404 (Not
Found) or 410 (Gone) if an application server atttempts to send a
push message to a removed or expired subscription.
Paragraph (version B):
A push service can invalidate a subscription at any time.  If a user
agent has an outstanding request to a "subscription" resource (see
monitor), this can be signaled by returning a 400-series status code,
such as 410 (Gone).
Paragraph (version B):
A user agent can request that a subscription be removed by sending a
DELETE request to its private "subscription" URI.
Paragraph (version B):
A push service MUST return a 400-series status code, such as 404 (Not
Found) or 410 (Gone) if an application server atttempts to send a
push message to a removed or expired subscription.
Paragraph (version A):
This protocol MUST use RFC2818; this includes any communications
between user agent and push service, plus communications between the
application and the push service.  Thus, all URIs use the "https"
scheme.  This provides confidentiality and integrity protection for
registrations and push messages from external parties.
Paragraph (version B):
This protocol MUST use RFC2818; this includes any communications
between user agent and push service, plus communications between the
application and the push service.  Thus, all URIs use the "https"
scheme.  This provides confidentiality and integrity protection for
subscriptions and push messages from external parties.
Paragraph (version A):
Subscription URIs MUST NOT provide any basis to correlate
communications for a given user agent.  It MUST NOT be possible to
correlate any two subscription URIs based solely on the content of
the subscription URIs.  This allows a user agent to control
correlation across different applications, or over time.
Paragraph (version A):
In particular, user and device information MUST NOT be exposed
through the subscription URI.
Paragraph (version A):
In addition, subscription URIs established by the same user agent
MUST NOT include any information that allows them to be correlated
with the associated registration or the user agent.  The push service
is the only entity that needs to be able to correlate subscriptions
with a registration.
Paragraph (version A):
This need not be perfect as long as the resulting anonymity set
(see RFC6973, Section 6.1.1) is sufficiently large.  A
subscription URI necessarily identifies a push service or a single
server instance.  It is also possible that traffic analysis could
be used to correlate subscriptions.
Paragraph (version A):
A user agent MUST be able to create new registrations and
subscriptions with new identifiers at any time.
Paragraph (version A):
This protocol does not define how a push service establishes whether
a user agent is permitted to create a registration or subscription,
or whether push messages can be delivered to the user agent.  A push
service MAY choose to authorize request 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".
Paragraph (version A):
Authorization for sending push messages is managed using capability
URLs (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.
Paragraph (version A):
A subscription URI therefore acts as a bearer token: knowledge of the
URI implies authorization to send push messages.  Subscription URIs
MUST be extremely difficult to guess.  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 subscription URI.
Paragraph (version A):
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.  Limiting
the number of entities with access to push channels limits the number
of entities that can generate value push requests of the push server.
Paragraph (version A):
An application can limit where push messages can originate by
limiting the distribution of subscription URIs to authorized
entities.  Ensuring that subscription URIs are hard to guess ensures
that only applications servers that have been given a subscription
URI can use it.
Paragraph (version A):
A malicious application with a valid subscription use the greater
resources of a push service to mount a denial of service attack on a
user agent.  Push service SHOULD limit the rate at which push
messages are sent to individual user agents.  A push service or user
agent MAY delete that receives too many push messages.
Paragraph (version A):
End-to-end confidentiality mechanisms, such as those in API, prevent
an entity with a registration URI from learning the contents of push
messages.  In both cases, push messages that are not successfully
authenticated will not be delivered by the API, but this can present
a denial of service risk.
Paragraph (version B):
This need not be perfect as long as the resulting anonymity set
(see 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.
Paragraph (version B):
A user agent MUST be able to create new subscriptions with new
identifiers at any time.
Paragraph (version B):
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 request 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".
Paragraph (version B):
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.
Paragraph (version B):
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.
Paragraph (version B):
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 delete that receive too many push messages.
Paragraph (version B):
End-to-end confidentiality mechanisms, such as those in API, prevent
an entity with a valid "subscription" URI from learning the contents
of push messages.  In both cases, push messages that are not
successfully authenticated will not be delivered by the API, but this
can present a denial of service risk.
Paragraph (version A):
Server request logs can reveal registration and subscription URIs.
Acquiring a registration URI permits the creation of new
subscriptions, as well as potentially enabling the receipt of
messages.  Acquiring a subscription URI permits the sending of push
messages.  Logging could also reveal relationships between different
subscription URIs for the same registration, or between different
registrations for the same user agent.
Paragraph (version A):
Three values are entered as the initial content of the "Web Push
Identifiers" registry.
Paragraph (version A):
This link relation type is used to identify a web push
subscription.
Paragraph (version A):
This link relation type is used to identify a web push
registration.
Paragraph (version A):
This link relation type is used to identify a resource that can be
used to create new web push subscriptions.
Paragraph (version B):
Two values are entered as the initial content of the "Web Push
Identifiers" registry.
Paragraph (version B):
This link relation type is used to identify a resource for sending
push messages.
Paragraph (version B):
This link relation type is used to identify a resource for
receiving push messages and deleting a subscription.