<?xmlversion="1.0" encoding="UTF-8"?> <?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?> <!-- generated by https://github.com/cabo/kramdown-rfc version 1.7.21 (Ruby 3.3.6) -->version='1.0' encoding='UTF-8'?> <!DOCTYPE rfc [ <!ENTITY nbsp " "> <!ENTITY zwsp "​"> <!ENTITY nbhy "‑"> <!ENTITY wj "⁠"><!ENTITY RFC8620 SYSTEM "https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8620.xml"> <!ENTITY RFC8030 SYSTEM "https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8030.xml"> <!ENTITY RFC8292 SYSTEM "https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8292.xml"> <!ENTITY RFC2119 SYSTEM "https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"> <!ENTITY RFC8174 SYSTEM "https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"> <!ENTITY RFC7515 SYSTEM "https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7515.xml">]> <rfc xmlns:xi="http://www.w3.org/2001/XInclude" ipr="trust200902" docName="draft-ietf-jmap-webpush-vapid-10" number="9749" category="std" consensus="true"submissionType="IETF">submissionType="IETF" version="3" xml:lang="en" tocInclude="true" updates="" obsoletes="" symRefs="true"> <front><title>Use<title abbrev="Use of VAPID in JMAPWebPush</title>Web Push">Use of Voluntary Application Server Identification (VAPID) in JSON Meta Application Protocol (JMAP) Web Push</title> <seriesInfo name="RFC" value="9749"/> <author initials="D." surname="Gultsch" fullname="Daniel Gultsch"><organization></organization><address> <email>daniel@gultsch.de</email> </address> </author> <date year="2025"month="January" day="10"/> <area>Internet</area> <workgroup>JMAP</workgroup>month="March"/> <area>ART</area> <workgroup>jmap</workgroup> <abstract><?line 45?><t>This document defines a method forJMAPJSON Meta Application Protocol (JMAP) servers to advertise their capability to authenticateWebPushWeb Push notifications using the Voluntary Application Server Identification (VAPID) protocol.</t> </abstract> </front> <middle><?line 49?><sectionanchor="introduction"><name>Introduction</name>anchor="introduction"> <name>Introduction</name> <t>JMAP <xref target="RFC8620"/> specifies how clients can subscribe to events using a protocol that is compatible withWebPushWeb Push <xref target="RFC8030"/>. Some push services require that the application serverauthenticatesauthenticate all push messages using theVoluntary Application Server IdentificationVAPID protocol <xref target="RFC8292"/>. To facilitate that, the client (or user agent inWebPushWeb Push terminology) needs the VAPID public key of the application server to passitalong to the push service when retrieving a new endpoint.</t> </section> <sectionanchor="conventions-used-in-this-document"><name>Conventionsanchor="conventions-used-in-this-document"> <name>Conventions Used in This Document</name><t>The<t> The key words"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY","<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<bcp14>RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>", "<bcp14>MAY</bcp14>", and"OPTIONAL""<bcp14>OPTIONAL</bcp14>" in this document are to be interpreted as described inBCP 14BCP 14 <xref target="RFC2119"/> <xref target="RFC8174"/> when, and only when, they appear in all capitals, as shown here.These words may also appear in this document in lower case as plain English words, absent their normative meanings. <?line -8?></t></t> </section> <sectionanchor="discovering-support-for-vapid"><name>Discoveringanchor="discovering-support-for-vapid"> <name>Discovering Support for VAPID</name> <t>The JMAP capabilities object is returned as part of the standard JMAP session object (seeSection 2 of<xref section="2" sectionFormat="of" target="RFC8620"/>). Servers supporting this specificationMUST<bcp14>MUST</bcp14> add a property called"urn:ietf:params:jmap:webpush-vapid"<tt>urn:ietf:params:jmap:webpush-vapid</tt> to the capabilities object. The value of this property is an object thatMUST<bcp14>MUST</bcp14> contain the following information:</t><t><list style="symbols"> <t>applicationServerKey: "String" <vspace blankLines='1'/> The ECDSA<dl spacing="compact" newline="true"> <dt><tt>applicationServerKey</tt>: "String"</dt> <dd>The Elliptic Curve Digital Signature Algorithm (ECDSA) public key that the push service will use to authenticate the application server, in its uncompressed form (as described in Section 2.3.3 of <xreftarget="X9.62"/> Annex A)target="SEC1"/>) and encoded using base64url encoding <xref target="RFC7515"/>. Current systems use the P-256 curve <xreftarget="FIPS186"/>.</t> </list></t>target="FIPS186"/>.</dd> </dl> <aside> <t>Informative Note: The format of the application server key was chosen to ensure compatibility with the browser API(<xref target="PUSH-API"/>, Section 7.2),(Section 7.2 of <xref target="PUSH-API"/>), allowing the key to be directly copied and used without additional transformation. Additionally, as noted in <xref section="3.2" sectionFormat="of" target="RFC8292"/>,Section 3.2,the X9.62 encoding (which is compatible with SEC1 encoding) simplifies key comparisons and is more compact than alternative formats.</t> </aside> </section> <sectionanchor="issuing-push-notifications"><name>Issuinganchor="issuing-push-notifications"> <name>Issuing Push Notifications</name> <t>Every time the server sends a push message to aPushSubscription URL<tt>PushSubscription</tt> URL, itMUST<bcp14>MUST</bcp14> authenticate the POST request using the protocol outlined in <xref target="RFC8292"/>. This includes bothStateChange<tt>StateChange</tt> events andPushVerification<tt>PushVerification</tt> notifications. To authenticate the request, the serverMUST<bcp14>MUST</bcp14> use aJWTJSON Web Token (JWT) signed by the private key corresponding to the application server key. This application server keyMUST<bcp14>MUST</bcp14> be the one that was advertised in the capabilities object at the time thePushSubscription<tt>PushSubscription</tt> was created.</t> </section> <sectionanchor="key-rotation"><name>Keyanchor="key-rotation"> <name>Key Rotation</name> <t>When a server needs to replace its VAPID key, itMUST<bcp14>MUST</bcp14> update thesessionState<tt>sessionState</tt> per <xref target="RFC8620"/>. The clientMUST<bcp14>MUST</bcp14> monitor the JMAP session object for changes to the VAPID key andMUST<bcp14>MUST</bcp14> recreate its push subscription when it detects such a change.</t> <t>After key rotation, the serverMAY<bcp14>MAY</bcp14> continue to send push notifications for existing push subscriptions using the old application server key for a transitional period. This allows clients time to recreate their respective push subscriptions. At the end of the transitional period (or immediately for implementations that do not have one), the serverMUST<bcp14>MUST</bcp14> destroy push subscriptions that use the old key.</t> <t>When destroying push subscriptions that include the data type<spanx style="verb">PushSubscription</spanx>,<tt>PushSubscription</tt>, the serverMAY<bcp14>MAY</bcp14> issue one finalStateChange<tt>StateChange</tt> push notification using the old URL and application server key to notify the client of changes to thePushSubscription<tt>PushSubscription</tt> data type. This prompts the client to make a<spanx style="verb">PushSubscription/changes</spanx><tt>PushSubscription/changes</tt> method call. The response to this call will contain an updatedsessionState,<tt>sessionState</tt>, which refers to a session object that contains the new VAPID key.</t> <t>A race condition can occur when the server updates its VAPID key after the client has refreshed the session object but before calling thePushSubscription/set<tt>PushSubscription/set</tt> method. This situation causes the server to send aPushVerification<tt>PushVerification</tt> object to a push resource URL that is now associated with an outdated VAPID key. Consequently, the push service will reject thePushVerification<tt>PushVerification</tt> with a 403 (Forbidden) status code, as specified in <xref section="4.2" sectionFormat="of" target="RFC8292"/>.</t> <t>To alleviate this problem, the clientMUST<bcp14>MUST</bcp14> check if thesessionState<tt>sessionState</tt> in the response from thePushSubscription/set<tt>PushSubscription/set</tt> method points to a session object with anapplicationServerKey<tt>applicationServerKey</tt> that matches their expectations. If there is a mismatch, the clientMAY<bcp14>MAY</bcp14> retry creating thePushSubscription.<tt>PushSubscription</tt>. Additionally, the clientMAY<bcp14>MAY</bcp14> destroy thePushSubscription<tt>PushSubscription</tt> from the earlier, failed attempt.</t> </section> <sectionanchor="security-considerations"><name>Securityanchor="security-considerations"> <name>Security Considerations</name> <t>During the key rotation process, synchronization issues between the client and server may arise. Specifically, a client might restrict a push subscription with the push service to an outdated key, while the server sends thePushVerification<tt>PushVerification</tt> object authenticated with the newly rotated key. This mismatch leads to the push service rejecting thePushVerification<tt>PushVerification</tt> request withHTTPa 403 (Forbidden) statuscode 403,code, as specified in <xreftarget="RFC8292"/>, Section 4.2.</t>section="4.2" sectionFormat="of" target="RFC8292"/>.</t> <t>Per the requirements of <xref section="7.2" sectionFormat="of" target="RFC8620"/>,Section 7.2,the serverMUST NOT<bcp14>MUST NOT</bcp14> retry the rejectedPushVerification<tt>PushVerification</tt> request. Consequently, thePushVerification<tt>PushVerification</tt> object will not be delivered to the client.</t> <t>To mitigate such issues, the client is responsible for detecting and resolving any synchronization discrepancies, as outlined inthe 'Key Rotation' section<xref target="key-rotation"/> of this document.</t> <t>The inclusion of the<spanx style="verb">urn:ietf:params:jmap:webpush-vapid</spanx><tt>urn:ietf:params:jmap:webpush-vapid</tt> property in the JMAP capabilities object is limited to providing information about the server's support forVoluntary Application Server Identification (VAPID).VAPID. This property does not reveal sensitive information, nor does it introduce new security or privacy risks beyond those inherent to JMAP andWebPush.Web Push. The security considerations for JMAP(<xref target="RFC8620"/>, especially Section 8.6<xref target="RFC8620"/> (especially Sections <xref section="8.6" sectionFormat="bare" target="RFC8620"/> andSection 8.7 of that document), WebPush (<xref target="RFC8030"/>)<xref section="8.7" sectionFormat="bare" target="RFC8620"/>), Web Push <xref target="RFC8030"/>, and VAPID(<xref target="RFC8292"/>)<xref target="RFC8292"/> apply to this document.</t> </section> <sectionanchor="iana-considerations"><name>IANAanchor="iana-considerations"> <name>IANA Considerations</name> <sectionanchor="registration-of-the-jmap-capability-for-vapid"><name>Registrationanchor="registration-of-the-jmap-capability-for-vapid"> <name>Registration of the JMAP Capability for VAPID</name><t>This specification requests IANA to register a<t>IANA has registered the following new capability in theJMAP Capabilities registry with the following data:</t> <t>Capability Name: <spanx style="verb">urn:ietf:params:jmap:webpush-vapid</spanx></t> <t>Specification document: this document</t> <t>Intended use: common</t> <t>Change Controller: IETF</t> <t>Security"JMAP Capabilities" registry:</t> <dl spacing="compact" newline="false"> <dt>Capability Name:</dt><dd><tt>urn:ietf:params:jmap:webpush-vapid</tt></dd> <dt>Intended Use:</dt><dd>common</dd> <dt>Change Controller:</dt><dd>IETF</dd> <dt>Security andprivacy considerations: this document, Section 6</t>Privacy Considerations:</dt><dd>RFC 9749, <xref target="security-considerations"/></dd> <dt>Reference:</dt><dd>RFC 9749</dd> </dl> </section> </section> </middle> <back> <referencestitle='References'anchor="sec-combined-references"> <name>References</name> <referencestitle='Normative References'anchor="sec-normative-references"> <name>Normative References</name> <reference anchor="FIPS186"target="https://doi.org/10.6028/NIST.FIPS.186-4">target="https://doi.org/10.6028/NIST.FIPS.186-5"> <front> <title>Digital Signature Standard (DSS)</title><author > <organization>National Institute of Standards and Technology (NIST)</organization><author> <organization>NIST</organization> </author> <dateyear="2013" month="July"/>year="2023" month="February"/> </front> <seriesInfoname="FIPS" value="186-4"/>name="NIST FIPS" value="186-5"/> <seriesInfo name="DOI" value="10.6028/NIST.FIPS.186-5"/> </reference> <referenceanchor="X9.62" >anchor="SEC1" target="http://www.secg.org/sec1-v2.pdf"> <front><title>Public Key Cryptography for the Financial Services Industry: The<title>SEC 1: Elliptic CurveDigital Signature Algorithm (ECDSA)</title> <author > <organization>American National Standards Institute</organization>Cryptography </title> <author> <organization>Standards for Efficient Cryptography Group</organization> </author> <dateyear="2005" month="November"/>year="2009" month="May"/> </front><seriesInfo name="ANSI" value="X9.62-2005"/><refcontent>Version 2.0</refcontent> </reference>&RFC8620; &RFC8030; &RFC8292; &RFC2119; &RFC8174; &RFC7515;<xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8620.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8030.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8292.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"/> <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7515.xml"/> </references> <referencestitle='Informative References'anchor="sec-informative-references"> <name>Informative References</name> <reference anchor="PUSH-API" target="https://www.w3.org/TR/push-api/"> <front> <title>Push API</title> <authorinitials="" surname="Peter Beverloo"> <organization></organization>initials="P" surname="Beverloo" role="editor"> <organization/> </author> <authorinitials="" surname="Martin Thomson"> <organization></organization>initials="M" surname="Thomson" role="editor"> <organization/> </author> <authorinitials="" surname="Marcos Caceres"> <organization></organization>initials="M" surname="Caceres" role="editor"> <organization/> </author> <date year="2024" month="September"/> </front> <refcontent>W3C Working Draft</refcontent> </reference> </references> </references> </back><!-- ##markdown-source: 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 XrGXvavkP85ys2AIHQAA --></rfc>