Voluntary Application Server Identification for Web Push

The Web Push protocol describes how an application server is able to request that a push service deliver a push message to a user agent. As a consequence of the expected deployment architecture, there is no basis for an application server to be known to a push service prior to requesting delivery of a push message. Requiring that the push service be able to authenticate application servers places an unwanted constraint on the interactions between user agents and application servers, who are the ultimate users of a push service. That constraint would also degrade the privacy-preserving properties the protocol provides. For these reasons, does not define a mandatory system for authentication of application servers. An unfortunate consequence of this design is that a push service is exposed to a greater risk of denial of service attack. While requests from application servers can be indirectly attributed to user agents, this is not always efficient or even sufficient. Providing more information about the application server directly to a push service allows the push service to better distinguish between legitimate and bogus requests. Additionally, this design also relies on endpoint secrecy as any application server in possession of the endpoint is able to send messages, albeit without payloads. In situations where usage of a subscription can be limited to a single application server, the ability to associate a subscription with the application server could reduce the impact of a data leak.

This document describes a system whereby an application server can volunteer information about itself to a push service. At a minimum, this provides a stable identity for the application server, though this could also include contact information, such as an email address. A consistent identity can be used by a push service to establish behavioral expectations for an application server. Significant deviations from an established norm can then be used to trigger exception handling procedures. Voluntarily-provided contact information can be used to contact an application server operator in the case of exceptional situations. Experience with push service deployment has shown that software errors or unusual circumstances can cause large increases in push message volume. Contacting the operator of the application server has proven to be valuable. Even in the absence of usable contact information, an application server that has a well-established reputation might be given preference over an unidentified application server when choosing whether to discard a push message.

The words “MUST”, “MUST NOT”, “SHOULD”, and “MAY” are used in this document. It’s not shouting, when they are capitalized, they have the special meaning described in . The terms “push message”, “push service”, “push subscription”, “application server”, and “user agent” are used as defined in .

Application servers that wish to self-identity generate and maintain a signing key pair. This key pair MUST be usable with elliptic curve digital signature (ECDSA) over the P-256 curve . Use of this key when sending push messages establishes an identity for the application server that is consistent across multiple messages. When requesting delivery of a push message, the application includes a JSON Web Token (JWT) , signed using its signing key. The token includes a number of claims as follows: An “aud” (Audience) claim in the token MUST include the unicode serialization of the origin (Section 6.1 of ) of the push resource URL. This binds the token to a specific push service. This ensures that the token is reusable for all push resource URLs that share the same origin. An “exp” (Expiry) claim MUST be included with the time after which the token expires. This limits the time that a token over which a token is valid. An “exp” claim MUST NOT be more than 24 hours from the time of the request. This JWT is included in an Authorization header field, using an auth-scheme of “WebPush”. A push service MAY reject a request with a 403 (Forbidden) status code if the JWT signature or its claims are invalid. The JWT MUST use a JSON Web Signature (JWS) . The signature MUST use ECDSA on the NIST P-256 curve , that is “ES256” .

If the application server wishes to provide contact details it MAY include an “sub” (Subject) claim in the JWT. The “sub” claim SHOULD include a contact URI for the application server as either a “mailto:” (email) or an “https:” URI.

An application server requests the delivery of a push message as described in . If the application server wishes to self-identify, it includes an Authorization header field with credentials that use the “WebPush” authentication scheme and a Crypto-Key header field that includes its public key .

Note that the header fields shown in don’t include line wrapping. Extra whitespace is added to meet formatting constraints. The value of the Authorization header field is a base64url-encoded JWT with the header and body shown in . This JWT would be valid until 2016-01-21T01:53:25Z .

A new “WebPush” HTTP authentication scheme is defined. This authentication scheme carries a signed JWT, as described in . This authentication scheme is for origin-server authentication only. Therefore, this authentication scheme MUST NOT be used with the Proxy-Authenticate or Proxy-Authorization header fields. This authentication scheme does not require a challenge. Clients are able to generate the Authorization header field without any additional information from a server. Therefore, a challenge for this authentication scheme MUST NOT be sent in a WWW-Authenticate header field. All unknown or unsupported parameters to “WebPush” authentication credentials MUST be ignored. The realm parameter is ignored for this authentication scheme.

In order for the push service to be able to validate the JWT, it needs to learn the public key of the application server. A p256ecdsa parameter is defined for the Crypto-Key header field to carry this information. The p256ecdsa parameter includes an elliptic curve digital signature algorithm (ECDSA) public key in uncompressed form that is encoded using the URL- and filename-safe variant of base-64 with padding removed. Note that with push message encryption , this results in two values in the Crypto-Key header field, one with the a dh key and another with a p256ecdsa key. Some implementations permit the same P-256 key to be used for signing and key exchange. An application server MUST select a different private key for the key exchange (i.e., dh) and signing (i.e., p256ecdsa). Though a push service is not obligated to check either parameter for every push message, a push service SHOULD reject push messages that have identical values for these parameters with a 400 (Bad Request) status code. JWK seems like the obvious choice here. However, JWK doesn’t define a compact representation for public keys, which complicates the representation of JWK in a header field.

The public key of the application server serves as a stable identifier for the server. This key can be used to restrict a push subscription to a specific application server. Subscription restriction reduces the reliance on endpoint secrecy by requiring proof of possession to be demonstrated by an application server when requesting delivery of a push message. This provides an additional level of protection against leaking of the details of the push subscription.

The user agent includes the public key of the application server when requesting the creation of a push subscription. This restricts use of the resulting subscription to application servers that are able to provide proof of possession for the corresponding private key. This public key is then added to the request to create a push subscription as described in . The Crypto-Key header field includes exactly one public key. For example:

An application might use the Web Push API to include this information. For example, the API might permit an application to provide a public key as part of a new field on the PushSubscriptionOptions dictionary. Allowing the inclusion of multiple keys when creating a subscription would allow a subscription to be associated with multiple application servers or application server instances. This might be more flexible, but it also would require more state to be maintained by the push service for each subscription.

When a push subscription has been associated with an application server, the request for push message delivery MUST include proof of possession for the associated private key that was used when creating the push subscription. A push service MUST reject a message that omits mandatory credentials with a 401 (Unauthorized) status code. A push service MAY reject a message that includes invalid credentials with a 403 (Forbidden) status code. Credentials are invalid if: either the authentication credentials or public key are not included in the request, the signature on the JWT cannot be successfully verified using the included public key, the current time is later than the time identified in the “exp” (Expiry) claim or more than 24 hours before the expiry time, the origin of the push resource is not included in the “aud” (Audience) claim, or the public key used to sign the JWT doesn’t match the one that was included in the creation of the push message. In theory, since the push service was given a public key, the push message request could omit the public key. On balance, requiring the key keeps things simple and it allows push services to compress the public key (by hashing it, for example). In any case, the relatively minor space savings aren’t particularly important on the connection between the application server and push service. A push service MUST NOT forward the JWT or public key to the user agent when delivering the push message.

This authentication scheme is vulnerable to replay attacks if an attacker can acquire a valid JWT. Applying narrow limits to the period over which a replayable token can be reused limits the potential value of a stolen token to an attacker and can increase the difficulty of stealing a token. An application server might offer falsified contact information. A push service operator therefore cannot use the presence of unvalidated contact information as input to any security-critical decision-making process. Validation of a signature on the JWT requires a non-trivial amount of computation. For something that might be used to identify legitimate requests under denial of service attack conditions, this is not ideal. Application servers are therefore encouraged to reuse a JWT, which permits the push service to cache the results of signature validation.

This registers the “WebPush” authentication scheme in the “Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry” established in . WebPush of this document This scheme is origin-server only and does not define a challenge.

This registers a p256ecdsa parameter for the Crypto-Key header field in the “Hypertext Transfer Protocol (HTTP) Crypto-Key Parameters” established in . p256ecdsa Conveys a public key for that is used to generate an ECDSA signature. of this document

This document would have been much worse than it currently is if not for the contributions of Benjamin Bangert, Chris Karlof, Costin Manolache, and others.