RFC 8292

Voluntary Application Server Identification (VAPID) for Web Push

📅 published November 2017, from ietf

RFC 8292: Voluntary Application Server Identification (VAPID) for Web Push 💖

okay so this RFC is from the Internet Engineering Task Force (IETF) 🌸, and it's officially Request for Comments: 8292. The authors are M. Thomson from Mozilla and P. Beverloo from Google 🫶. It's a Standards Track document, meaning it's an actual Internet standard and not just a suggestion 👑. The ISSN is 2070-1721, and it came out in November 2017 🎀. The header doesn't list anything it obsoletes or updates, so it's standing on its own ✨.

Abstract

okay so the big idea is that an application server can use VAPID (Voluntary Application Server Identification) to voluntarily tell a push service who it is 🦋. The "vapid" authentication scheme lets a client put its identity into a signed token that rides along with its requests 💅. The push service can use that signature to group every request from the same application server under one entity, which is so useful 😭. The identity info can also let the push service operator reach out to the application server operator if something's up 📬. And the signature can lock a push message subscription to just one application server, which is giving security 🔐.

Status of This Memo

this is an Internet Standards Track document 💜.

it's a product of the IETF, so it reflects the consensus of the IETF community 🌈. it got public review and was approved for publication by the Internet Engineering Steering Group (IESG) ⭐. if you want more on Internet Standards, check Section 2 of RFC 7841 📚.

info about the current status, any errata, and how to send feedback lives at https://www.rfc-editor.org/info/rfc8292 🔗.

Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved. 🎀

this document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they stand on the date of publication 📜. please read these carefully, because they spell out your rights and restrictions for this document 🫶. code components pulled out of this document have to include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty, as described in the Simplified BSD License 💅.

Table of Contents

   1. Introduction ....................................................3
      1.1. Voluntary Identification ...................................3
      1.2. Notational Conventions .....................................4
   2. Application Server Self-Identification ..........................4
      2.1. Application Server Contact Information .....................5
      2.2. Additional Claims ..........................................5
      2.3. Cryptographic Agility ......................................5
      2.4. Example ....................................................5
   3. VAPID Authentication Scheme .....................................6
      3.1. Token Parameter ("t") ......................................7
      3.2. Public Key Parameter ("k") .................................7
   4. Subscription Restriction ........................................7
      4.1. Creating a Restricted Push Message Subscription ............8
      4.2. Using Restricted Subscriptions .............................9
   5. Security Considerations .........................................9
   6. IANA Considerations ............................................10
      6.1. VAPID Authentication Scheme Registration ..................10
      6.2. VAPID Authentication Scheme Parameters ....................10
      6.3. application/webpush-options+json Media Type Registration ..11
   7. References .....................................................12
      7.1. Normative References ......................................12
      7.2. Informative References ....................................14
   Acknowledgements ..................................................14
   Authors' Addresses ................................................14

1. Introduction ✨

okay so the Web Push protocol [RFC8030] explains how an application server can ask a push service to deliver a push message to a user agent 🦋.

here's the tea: the whole deployment setup means an application server has no basis to be known to a push service before it asks for a delivery 🙈. if the push service had to authenticate application servers, that would put an unwanted constraint on the relationship between user agents and application servers, who are the actual main characters of a push service 💖. it would also weaken the privacy properties the protocol gives people 🔒. so [RFC8030] doesn't define a mandatory system for authenticating application servers 🌸.

the downside of that design is that a push service has a higher risk of denial-of-service attacks 😭. you can kinda figure out which user agent a request came from, but that's not always efficient or even enough 💀. giving the push service more direct info about the application server helps it tell the legit requests apart from the bogus ones 🔥.

also, [RFC8030] depends on keeping push message subscription URIs secret 🤫. any application server that has a subscription URI can send messages to the user agent 📨. if a subscription could be limited to one application server, then a leaked URI would be way less of a disaster 🛡️.

1.1. Voluntary Identification

this document describes a system where an application server can volunteer info about itself to a push service 🎀. at the very least, that gives the application server a stable identity 🪪. it could also include contact info, like an email address 💌.

a consistent identity lets a push service set behavioral expectations for an application server ✨. if something deviates a lot from what's normal, the push service can kick off exception-handling procedures 🚨.

contact info that's voluntarily shared can be used to reach the application server operator when something exceptional happens 📞.

experience with push service deployments has shown that software errors or weird circumstances can cause huge spikes in push message volume 📈. reaching out to the application server operator has proven really valuable 🙌.

even without usable contact info, an application server with a well-established reputation might get preference over an unidentified one when the push service has to decide whether to discard a push message 👑.

1.2. Notational Conventions

the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be read as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they show up in all capitals, just like here 📖. (these are the official rule words, so the caps matter 🧐.)

the terms "push message", "push service", "push message subscription", "application server", and "user agent" mean what [RFC8030] says they mean 🤓.

2. Application Server Self-Identification 🪪

application servers that want to self-identify generate and maintain a signing key pair 🔑. this key pair MUST be usable with the Elliptic Curve Digital Signature Algorithm (ECDSA) over the P-256 curve [FIPS186] 💅. using this key when sending push messages gives the application server an identity that stays consistent across all its messages 🫶.

when asking for delivery of a push message, the application includes a JSON Web Token (JWT) [RFC7519], signed with its signing key ✍️. the token carries a bunch of claims, like this 🎀:

  • An "aud" (Audience) claim in the token MUST include the Unicode serialization of the origin (Section 6.1 of [RFC6454]) of the push resource URL. this binds the token to one specific push service, and it makes sure the token can be reused for every push resource URL that shares that same origin 🔗.
  • An "exp" (Expiry) claim MUST be included, with the time after which the token expires ⏰. this limits how long the token is valid. An "exp" claim MUST NOT be more than 24 hours from the time of the request. the 24-hour cap balances the need for reuse against the risk and likelihood of a valid token getting stolen 🕵️.
🚨 the JWT goes in an Authorization header field, using the authentication scheme vapid 🚨. a push service MAY reject a request with a 403 (Forbidden) status code [RFC7231] if the JWT signature or its claims are invalid. and a push service MUST NOT use info from an invalid token 🙅‍♀️.

the JWT MUST use a JSON Web Signature (JWS) [RFC7515] 💜. the signature MUST use ECDSA on the NIST P-256 curve [FIPS186], which is identified as "ES256" [RFC7518] 🌈.

2.1. Application Server Contact Information

if the application server wants to share contact details, it MAY include a "sub" (Subject) claim in the JWT 💌. the "sub" claim SHOULD include a contact URI for the application server, either as a "mailto:" (email) [RFC6068] URI or as an "https:" [RFC2818] URI 📧.

2.2. Additional Claims

an application server MAY include additional claims using public or private names (see Sections 4.2 and 4.3 of [RFC7519]) 🧩. since the JWT lives in a header field, the size of additional claims SHOULD be kept as small as possible 🪶. header fields are not the place to be extra 😭.

2.3. Cryptographic Agility

the vapid HTTP authentication scheme (Section 3) is what identifies the specific profile of JWT defined in this document 🎯. a different authentication scheme is needed to update the signature algorithm or other parameters 🔄. this way, the existing mechanisms for negotiating authentication schemes can be reused, so there's no need to invent new parameter negotiation mechanisms 🧠✨.

2.4. Example 🎀

Okay bestie, let's see this in action 💅 An application server asks for a push message to be delivered, like in [RFC8030]. If it wants to self-identify, it adds an Authorization header field with credentials that use the vapid authentication scheme 🦋

POST /p/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV HTTP/1.1
Host: push.example.net
TTL: 30
Content-Length: 136
Content-Encoding: aes128gcm
Authorization: vapid
   t=eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiJ9.eyJhdWQiOiJodHRwczovL3
     B1c2guZXhhbXBsZS5uZXQiLCJleHAiOjE0NTM1MjM3NjgsInN1YiI6Im1ha
     Wx0bzpwdXNoQGV4YW1wbGUuY29tIn0.i3CYb7t4xfxCDquptFOepC9GAu_H
     LGkMlMuCGSK2rpiUfnK9ojFwDXb1JrErtmysazNjjvW2L9OkSSHzvoD1oA,
   k=BA1Hxzyi1RUM1b5wjxsn7nGxAszw2u61m164i3MrAIxHF6YK5h4SDYic-dR
     uU_RCPCfA5aq9ojSwk5Y2EmClBPs
{ encrypted push message }

         Figure 1: Requesting Push Message Delivery with JWT

Note that the example header fields in this document include extra line wrapping to meet formatting constraints 🙈 It's wrapped so it fits on the page, not because the real header is split up like that.

The t parameter of the Authorization header field holds a JWT 🧚 The k parameter holds the base64url-encoded key that signed that token. The JWT input values and the JSON Web Key (JWK) [RFC7517] for the signing key are shown in Figure 2, with extra whitespace added so it's easier to read 👀 This JWT would be valid until 2016-01-23T04:36:08Z.

JWT header = { "typ": "JWT", "alg": "ES256" }
JWT body = { "aud": "https://push.example.net",
             "exp": 1453523768,
             "sub": "mailto:push@example.com" }
JWK = { "crv":"P-256",
        "kty":"EC",
        "x":"DUfHPKLVFQzVvnCPGyfucbECzPDa7rWbXriLcysAjEc",
        "y":"F6YK5h4SDYic-dRuU_RCPCfA5aq9ojSwk5Y2EmClBPs" }

                  Figure 2: Decoded Example Values

3. VAPID Authentication Scheme 🦋

This document defines a brand new HTTP authentication scheme [RFC7235] called vapid. This scheme carries a signed JWT, as described in Section 2, plus the key that signed that JWT ✨

This authentication scheme is for origin-server authentication only 💅 So this authentication scheme MUST NOT be used with the Proxy-Authenticate or Proxy-Authorization header fields. Not for proxies, periodt!

The challenge for the vapid authentication scheme contains only the "auth-scheme" production. No parameters are defined right now.

Two parameters are defined for this scheme: t and k 🌸 All unknown or unsupported parameters to vapid authentication credentials MUST be ignored. The realm parameter is ignored for this scheme too.

This authentication scheme is meant for an application server using the Web Push protocol [RFC8030] 🫶

3.1. Token Parameter ("t") 💖

The t parameter of the vapid authentication scheme carries a JWT, as described in Section 2.

3.2. Public Key Parameter ("k") 🔑

For the push service to validate the JWT, it needs to learn the public key of the application server. That's why a k parameter is defined for the vapid authentication scheme, to carry this info ✨

The k parameter includes an ECDSA public key [FIPS186] in uncompressed form [X9.62], encoded using base64url encoding [RFC7515].

Note: X9.62 encoding is used over JWK [RFC7517] for two reasons. A JWK does not have a canonical form, so X9.62 encoding makes it easier for the push service to compare keys from different sources. Secondarily, the X9.62 encoding is also considerably smaller.

Some elliptic curve implementations let the same P-256 key be used for both signing and key exchange 😭 An application server MUST select a different private key for the key exchange [RFC8291] and for signing the authentication token. A push service isn't obligated to check either parameter for every push message, but a push service SHOULD reject push messages that have identical values for these parameters with a 400 (Bad Request) status code 💀

4. Subscription Restriction 🔒

The public key of the application server works as a stable identifier for the server 🆔 This key can be used to restrict a push message subscription to one specific application server.

Subscription restriction reduces the reliance on endpoint secrecy, because it requires an application server to provide a signed token when it requests delivery of a push message. That gives an extra layer of protection against leaking the details of the push message subscription 🛡️

4.1. Creating a Restricted Push Message Subscription 🍓

A user agent that wants a restricted subscription includes the public key of the application server when it requests the creation of a push message subscription. This restricts use of the resulting subscription to application servers that can provide a valid JWT signed by the matching private key.

The user agent then adds the public key to the request to create a push message subscription. The push message subscription request is extended to include a body. The body is a JSON object as described in [RFC7159]. The user agent adds a vapid member to this JSON object that contains a public key on the P-256 curve, encoded in uncompressed form [X9.62] and base64url encoded [RFC7515]. The media type of the body is set to application/webpush-options+json (see Section 6.3 for registration of this media type) 📦

A push service MUST ignore the body of a request that uses a different media type. For the application/webpush-options+json media type, a push service MUST ignore any members on this object that it does not understand.

The example in Figure 3 shows a restriction to the key used in Figure 1. Extra whitespace is added to meet formatting constraints.

POST /subscribe/ HTTP/1.1
Host: push.example.net
Content-Type: application/webpush-options+json
Content-Length: 104

{ "vapid": "BA1Hxzyi1RUM1b5wjxsn7nGxAszw2u61m164i3MrAIxH
            F6YK5h4SDYic-dRuU_RCPCfA5aq9ojSwk5Y2EmClBPs" }

                 Figure 3: Example Subscribe Request

An application might use the Push API [API] to give the user agent a public key 🌈

4.2. Using Restricted Subscriptions 🧁

When a push message subscription has been restricted to an application server, the request for push message delivery MUST include a JWT signed by the private key that corresponds to the public key used when the subscription was created.

A push service MUST reject a message sent to a restricted push message subscription if that message includes no vapid authentication, or invalid vapid authentication. A 401 (Unauthorized) status code might be used if the authentication is absent. A 403 (Forbidden) status code might be used if the authentication is invalid 🙅‍♀️

vapid authentication is invalid if:

  • either the authentication token or public key is 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 when the push message subscription was created.

A push service MUST NOT forward the JWT or public key to the user agent when it delivers the push message 🤫

An application server that needs to replace its signing key has to request the creation of a new subscription by the user agent, restricted to the updated key 🔄 Application servers need to remember the key that was used when they requested the creation of a subscription 🧠

5. Security Considerations 🚨

This authentication scheme is vulnerable to replay attacks if an attacker can acquire a valid JWT 😱 Sending requests over HTTPS, as required by [RFC8030], provides confidentiality. Also, 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 make stealing a token harder.

An application server might offer falsified contact information. The application server asserts its email address or contact URI without any evidence to back the claim 🙃 A push service operator cannot use the presence of unvalidated contact information as input to any security-critical decision-making process.

Validating a signature on the JWT takes a non-trivial amount of computation. For something that might be used to identify legitimate requests during a denial-of-service attack, that's not ideal 💀 So application servers are encouraged to reuse tokens, which lets the push service cache the results of signature validation ♻️

An application server that changes its signing key breaks linkability between the push messages it sends under different keys. A push service that relies on a consistent identity for application servers might categorize requests made with new keys differently. A gradual migration to a new signing key reduces the chances that requests using the new key get categorized as abusive 🫣

6. IANA Considerations 📚

This document registers a new authentication scheme, a registry for parameters of that scheme, and a media type for push options ✨

6.1. VAPID Authentication Scheme Registration 🦋

This document registers the vapid authentication scheme in the "Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry" established by [RFC7235].

  • Authentication Scheme Name: vapid
  • Pointer to specification text: Section 3 of this document

6.2. VAPID Authentication Scheme Parameters 🎀

This document creates a "VAPID Authentication Scheme Parameters" registry for parameters to the vapid authentication scheme. These parameters are defined for use in requests (in the Authorization header field) and for challenges (in the WWW-Authenticate header field). This registry is under the "Web Push Parameters" grouping. The registry operates on the "Specification Required" policy [RFC8126].

Registrations MUST include the following information:

  • Parameter Name: A name for the parameter, which conforms to the "token" grammar [RFC7230]
  • Purpose (optional): Brief text identifying the purpose of the parameter
  • Header Field(s): The header field(s) in which the parameter can be used
  • Specification: A link to the specification that defines the format and semantics of the parameter

This registry initially contains the following entries:

+-------------+------------------+---------------+------------------+
| Parameter   | Purpose          | Header        | Specification    |
| Name        |                  | Field(s)      |                  |
+-------------+------------------+---------------+------------------+
| t           | JWT              | Authorization | [RFC8292],       |
|             | authentication   |               | Section 3.1      |
|             | token            |               |                  |
|             |                  |               |                  |
| k           | signing key      | Authorization | [RFC8292],       |
|             |                  |               | Section 3.2      |
+-------------+------------------+---------------+------------------+

6.3. application/webpush-options+json Media Type Registration

okay so this is the bit where we register a brand new media type 🎀 The application/webpush-options+json type gets added to the "Media Types" registry, following the process in [RFC6838]. Here's the registration exactly as it appears:

   Type name:  application

   Subtype name:  webpush-options+json

   Required parameters:  none

   Optional parameters:  none

   Encoding considerations:  binary (JSON is UTF-8-encoded text)

   Security considerations:  See [RFC7159] for security considerations
      specific to JSON.

   Interoperability considerations:  See [RFC7159] for interoperability
      considerations specific to JSON.

   Published specification:  [RFC8292]

   Applications that use this media type:  Web browsers, via the Web
      Push protocol [RFC8030]

   Fragment identifier considerations:  none

   Additional information:

      Deprecated alias names for this type:  n/a

      Magic number(s):  n/a

      File extension(s):  .json

      Macintosh file type code(s):  TEXT

   Person & email address to contact for further information:  Martin
      Thomson (martin.thomson@gmail.com)

   Intended usage:  LIMITED USE

   Restrictions on usage:  For use with the Web Push protocol [RFC8030]

   Author:  See "Authors' Addresses" section of [RFC8292].

   Change controller:  Internet Engineering Task Force

Basically it's a JSON type 💅 It's binary-encoded, but JSON is UTF-8 text, so that's the whole vibe. Security and interoperability both just point you to [RFC7159] for the JSON stuff. It's for Web Push ([RFC8030]) only, so it's LIMITED USE, and the IETF is the change controller. Iconic restraint 🦋

7. References

7.1. Normative References

Here are the normative refs, the ones you absolutely need to read to get this spec 🧠

   [FIPS186]  National Institute of Standards and Technology (NIST),
              "Digital Signature Standard (DSS)", FIPS PUB 186-4,
              DOI 10.6028/NIST.FIPS.186-4, July 2013.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC2818]  Rescorla, E., "HTTP Over TLS", RFC 2818,
              DOI 10.17487/RFC2818, May 2000,
              <https://www.rfc-editor.org/info/rfc2818>.

   [RFC6068]  Duerst, M., Masinter, L., and J. Zawinski, "The 'mailto'
              URI Scheme", RFC 6068, DOI 10.17487/RFC6068, October 2010,
              <https://www.rfc-editor.org/info/rfc6068>.

   [RFC6454]  Barth, A., "The Web Origin Concept", RFC 6454,
              DOI 10.17487/RFC6454, December 2011,
              <https://www.rfc-editor.org/info/rfc6454>.

   [RFC6838]  Freed, N., Klensin, J., and T. Hansen, "Media Type
              Specifications and Registration Procedures", BCP 13,
              RFC 6838, DOI 10.17487/RFC6838, January 2013,
              <https://www.rfc-editor.org/info/rfc6838>.

   [RFC7159]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
              2014, <https://www.rfc-editor.org/info/rfc7159>.

   [RFC7230]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Message Syntax and Routing",
              RFC 7230, DOI 10.17487/RFC7230, June 2014,
              <https://www.rfc-editor.org/info/rfc7230>.

   [RFC7231]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
              DOI 10.17487/RFC7231, June 2014,
              <https://www.rfc-editor.org/info/rfc7231>.

   [RFC7235]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Authentication", RFC 7235,
              DOI 10.17487/RFC7235, June 2014,
              <https://www.rfc-editor.org/info/rfc7235>.

   [RFC7515]  Jones, M., Bradley, J., and N. Sakimura, "JSON Web
              Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
              2015, <https://www.rfc-editor.org/info/rfc7515>.

   [RFC7518]  Jones, M., "JSON Web Algorithms (JWA)", RFC 7518,
              DOI 10.17487/RFC7518, May 2015,
              <https://www.rfc-editor.org/info/rfc7518>.

   [RFC7519]  Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
              (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
              <https://www.rfc-editor.org/info/rfc7519>.

   [RFC8030]  Thomson, M., Damaggio, E., and B. Raymor, Ed., "Generic
              Event Delivery Using HTTP Push", RFC 8030,
              DOI 10.17487/RFC8030, December 2016,
              <https://www.rfc-editor.org/info/rfc8030>.

   [RFC8126]  Cotton, M., Leiba, B., and T. Narten, "Guidelines for
              Writing an IANA Considerations Section in RFCs", BCP 26,
              RFC 8126, DOI 10.17487/RFC8126, June 2017,
              <https://www.rfc-editor.org/info/rfc8126>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

   [RFC8291]  Thomson, M., "Message Encryption for Web Push", RFC 8291,
              DOI 10.17487/RFC8291, November 2017,
              <http://www.rfc-editor.org/info/rfc8291>.

   [X9.62]    ANSI, "Public Key Cryptography for the Financial Services
              Industry: the Elliptic Curve Digital Signature Algorithm
              (ECDSA)", ANSI X9.62, 2005.

7.2. Informative References

These ones are the extra reading, nice to have but not required 📚

   [API]      Beverloo, P., Thomson, M., van Ouwerkerk, M., Sullivan,
              B., and E. Fullea, "Push API", October 2017,
              <https://www.w3.org/TR/push-api/>.

   [RFC7517]  Jones, M., "JSON Web Key (JWK)", RFC 7517,
              DOI 10.17487/RFC7517, May 2015,
              <https://www.rfc-editor.org/info/rfc7517>.

Acknowledgements ✨

Honestly this doc would've been SO much worse without the help of Benjamin Bangert, JR Conlin, Chris Karlof, Costin Manolache, Adam Roach, and others 🫶 Thank you, besties 💜

Authors' Addresses 🎀

   Martin Thomson
   Mozilla

   Email: martin.thomson@gmail.com


   Peter Beverloo
   Google

   Email: beverloo@google.com
📦 where this page comes from