Network Working Group S. Gougeon
Internet-Draft 19 March 2025
Intended status: Informational
Expires: 20 September 2025
The IMAP WEBPUSH extension
draft-gougeon-imap-webpush-02
Abstract
This document defines a WEBPUSH extension of the Internet Message
Access Protocol (IMAP) that permits IMAP servers to send WebPush
notifications.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 20 September 2025.
Copyright Notice
Copyright (c) 2025 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) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document.
Gougeon Expires 20 September 2025 [Page 1]
Internet-Draft The IMAP WEBPUSH extension March 2025
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3
3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3
4. CAPABILITY Identification . . . . . . . . . . . . . . . . . . 3
5. Client Commands . . . . . . . . . . . . . . . . . . . . . . . 3
5.1. GETVAPID Command . . . . . . . . . . . . . . . . . . . . 4
5.2. WEBPUSH Command . . . . . . . . . . . . . . . . . . . . . 4
5.3. ACKWEBPUSH Command . . . . . . . . . . . . . . . . . . . 7
5.4. LWEBPUSH Command . . . . . . . . . . . . . . . . . . . . 8
5.5. SILWEBPUSH Command . . . . . . . . . . . . . . . . . . . 9
6. Server Responses . . . . . . . . . . . . . . . . . . . . . . 10
6.1. VAPID Response . . . . . . . . . . . . . . . . . . . . . 10
6.2. WEBPUSH Response . . . . . . . . . . . . . . . . . . . . 10
6.3. SELECT Response . . . . . . . . . . . . . . . . . . . . . 11
6.4. ACKWEBPUSH Response . . . . . . . . . . . . . . . . . . . 11
6.5. SYNC Response . . . . . . . . . . . . . . . . . . . . . . 11
7. Push notifications . . . . . . . . . . . . . . . . . . . . . 12
7.1. Content . . . . . . . . . . . . . . . . . . . . . . . . . 12
7.2. WebPush headers . . . . . . . . . . . . . . . . . . . . . 13
7.3. Push message processing . . . . . . . . . . . . . . . . . 14
7.4. Push server response . . . . . . . . . . . . . . . . . . 14
8. VAPID key rotation . . . . . . . . . . . . . . . . . . . . . 14
9. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 15
10. Security Considerations . . . . . . . . . . . . . . . . . . . 17
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 17
12.1. Normative References . . . . . . . . . . . . . . . . . . 17
12.2. Informative References . . . . . . . . . . . . . . . . . 18
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 19
1. Introduction
WebPush (defined by [RFC8030], [RFC8291] and [RFC8292]) defines a way
for applications to deliver real-time events in a timely fashion,
with push notifications. Push notifications allows consolidating all
real-time events into a single session which ensures more efficient
use of network and radio resources. They are particularly used in
mobile environments. Push notifications may also be used for other
use cases, for example during the migration to a new server, the new
server may subscribe to the old server to be notified when an event
is recorded.
Gougeon Expires 20 September 2025 [Page 2]
Internet-Draft The IMAP WEBPUSH extension March 2025
Many use cases have led to a need for real-time events with email.
IMAP support for real-time events has been added with the IDLE
command ([RFC2177], [RFC9051]) and the NOTIFY extension ([RFC5465]).
These commands require using a persistent connection per account and
contribute to unnecessary use of the device radio.
JMAP ([RFC8620]) has responded to this need by supporting WebPush
from the beginning.
Therefore, this extension permits IMAP servers to send WebPush
notifications.
2. Conventions and Definitions
In examples, "C:" and "S:" indicate lines sent by the client and
server, respectively. "Push:" indicates lines send by the server
with a push message, and "Push>" indicates lines that are part of the
same push message than the previous line. Lines ending in "\" are
interrupted for presentation reasons, they would actually be joined
to the next line. Note that each other line includes the terminating
CRLF.
User agent, is defined in [RFC8030] as a device and software that is
the recipient of push messages. It describes here the mail client.
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 interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
3. Overview
This extension adds 5 commands: GETVAPID, WEBPUSH, ACKWEBPUSH,
LWEBPUSH and SILWEBPUSH. GETVAPID allows to get the server VAPID
public key, WEBPUSH to subscribe a new push subscription, ACKWEBPUSH
to confirm the subscription information is correct, LWEBPUSH to list
current subscriptions and SILWEBPUSH to silence a subscription for a
given time. Every time a message is added to a mailbox, the IMAP
server sends a push message to the registered push endpoints.
4. CAPABILITY Identification
IMAP servers that support this extension MUST include "WEBPUSH" in
the CAPABILITY command response.
5. Client Commands
Gougeon Expires 20 September 2025 [Page 3]
Internet-Draft The IMAP WEBPUSH extension March 2025
5.1. GETVAPID Command
This command is only available in authenticated or selected state.
Arguments: none
Responses: REQUIRED untagged response: VAPID
Result: OK - capability completed
BAD - arguments invalid
The GETVAPID command requests the VAPID public key ([RFC8292]) of the
server. the server MUST send a single untagged VAPID response before
the tagged OK response. This is used by clients to request a push
endpoint on their push server restricted to this mail server.
Example:
C: a1 GETVAPID
S: * VAPID \
BOniQ9xHBPNY9gnQW4o-16vHqOb40pEIMifyUdFsxAgy\
zVkFMguxw0QrdbZcq8hRjN2zpeInRvKVPlkzABvuTnI
S: a1 OK GETVAPID completed
5.2. WEBPUSH Command
This command is only available in authenticated or selected state.
Arguments (create/update): subscription ID
push endpoint
ECDH public key
authentication secret
Arguments (delete): subscription ID
NIL
Responses (inactive subscription): untagged response: WEBPUSH
VAPID
Responses (active subscription): OPTIONAL untagged response: WEBPUS
H
Gougeon Expires 20 September 2025 [Page 4]
Internet-Draft The IMAP WEBPUSH extension March 2025
VAPID
Result: OK - creation or deletion completed
NO - creation failure: can't create webpush subscription with
these arguments
BAD - command unknown or arguments invalid
The WEBPUSH command creates, updates or delete a push subscription
for the account. New subscriptions and updated subscriptions (with
at least one different field) aren't active until the subscription is
confirmed with the ACKWEBPUSH command.
The subscription ID is unique per account and identifies the push
subscription. Sending a WEBPUSH command with an existing
subscription ID updates the current subscription. Sending a WEBPUSH
command with an existing subscription ID following by NIL deletes the
subscription.
If the client tries to delete a subscription with an unknown
subscription ID, the server returns a tagged OK response.
If the subscription is inactive or is deactivated by the command, the
server MUST return a single untagged WEBPUSH response before the
tagged OK response and MUST return a single untagged VAPID response
before the tagged OK response. The VAPID response can be used by the
client to check if the server has rotated its VAPID keys.
If the subscription is still active after the command, the server MAY
return a single untagged WEBPUSH response and MAY return a single
untagged VAPID response before the tagged OK response.
If the subscription was activated (i.e. created and then confirmed/
acknowledged) with a VAPID key that is not the current VAPID key (due
to a key rotation), then subscription MUST be deactivated by this
command, and a confirm/acknowledgement is required to activate the
subscription again.
If the updated or created subscription is inactive after the command
(this is a new subscription, at least one field is different or the
VAPID key has been rotated), the server MUST send an ACKWEBPUSH
response with a push notification, encrypted with the new public key,
to the new endpoint. The client will have to send a ACKWEBPUSH
command to (re-)activate the subscription. The client knows if the
subscription is deactivated thanks to the untagged WEBPUSH response.
Gougeon Expires 20 September 2025 [Page 5]
Internet-Draft The IMAP WEBPUSH extension March 2025
The push endpoint MUST be the URI that the mail server sends push
messages to. This is defined as the URI for push resource in
[RFC8030]. This URI MUST use the "https" scheme.
The ECDH public key is the user agent public key on the P-256 curve.
It MUST be encoded in the uncompressed form [SEC_1] (section 2.3.3,
replicated from X9.62), and base64url encoded as described in
[RFC7515]. This is used to encrypt push notifications following
[RFC8291].
The authentication secret is 16 random bytes. It MUST be base64url
encoded as described in [RFC7515]. This is used to encrypt push
notifications following [RFC8291].
The client SHOULD reregister their push subscription from time to
time, like every time the client starts, in order to restore
subscriptions, in case the endpoint was removed. Subscription may be
removed if the push server has been in an inconsistent state, or if
the mail server has been restored from a backup.
The capabilities that were enabled using the ENABLE command at the
time of the WEBPUSH command are associated with the subscription.
When sending push messages, the untagged messages are formatted
according to those capabilities. For example, enabling IMAP4rev2 or
UTF8=ACCEPT cause mailboxes to be in UTF-8, and enabling CONDSTORE
causes MODSEQ to be added to UIDFETCH responses.
Example:
Gougeon Expires 20 September 2025 [Page 6]
Internet-Draft The IMAP WEBPUSH extension March 2025
C: a1 LWEBPUSH *
S: a1 OK LWEBPUSH completed
C: a2 WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
https://push.example.net/push/random1 \
BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bj\
yPjs7Vd8pZGH6SRpkNtoIAiw4 \
BTBZMqHH6r4Tts7J_aSIgg
S: * VAPID BOniQ9xHBPNY9gnQW4o-16vHqOb40pEIMifyUdFsxAgy\
zVkFMguxw0QrdbZcq8hRjN2zpeInRvKVPlkzABvuTnI
S: * WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
https://push.example.net/push/random1 NIL
S: a2 OK WEBPUSH completed
C: a3 WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
https://push.example.net/push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV \
BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bj\
yPjs7Vd8pZGH6SRpkNtoIAiw4 \
BTBZMqHH6r4Tts7J_aSIgg
S: * VAPID BOniQ9xHBPNY9gnQW4o-16vHqOb40pEIMifyUdFsxAgy\
zVkFMguxw0QrdbZcq8hRjN2zpeInRvKVPlkzABvuTnI
S: * WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
https://push.example.net/push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV NIL
S: a3 OK WEBPUSH completed
C: a4 LWEBPUSH *
S: * WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
https://push.example.net/push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV NIL
S: a4 OK LWEBPUSH completed
C: a5 WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 NIL
S: a5 OK WEBPUSH completed
C: a6 LWEBPUSH *
S: a6 OK LWEBPUSH completed
5.3. ACKWEBPUSH Command
This command is only available in authenticated or selected state.
Arguments: acknowledgement token, send with a push message with a
ACKWEBPUSH response by the server
Responses: untagged response: WEBPUSH
Result: OK - The subscription is activated
NO - The token doesn't exist or is expired
BAD - arguments invalid
Example to activate a subscription with a valid token:
Gougeon Expires 20 September 2025 [Page 7]
Internet-Draft The IMAP WEBPUSH extension March 2025
C: a1 LWEBPUSH *
S: * WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
https://push.example.net/push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV NIL
S: a1 OK LWEBPUSH completed
C: a2 ACKWEBPUSH 585078c5-fb8b-4ed0-8e77-474ab08f0a30
S: * WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
https://push.example.net/push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV 0
S: a2 OK ACKWEBPUSH completed
Example with an unknown or expired token:
C: a1 ACKWEBPUSH 5aa04cf0-f156-406e-84af-3cee534b23b8
S: a1 NO ACKWEBPUSH completed
5.4. LWEBPUSH Command
This command is only available in authenticated or selected state.
Arguments: subscription ID with possible wildcards
Responses: untagged response: WEBPUSH
Result: OK - list completed
NO - list failure: can't list webpush records
BAD - arguments invalid
The LWEBPUSH command returns a subset of webpush subscriptions from
the complete set of all subscriptions available to the client. Zero
or more untagged WEBPUSH responses are returned, containing
information to identified the subscriptions. The server MUST return
the WEBPUSH response for the exact subscription ID if the account has
a subscription with this ID. It MUST return all the account's
subscriptions if the argument is a wildcard "*".
Example:
Gougeon Expires 20 September 2025 [Page 8]
Internet-Draft The IMAP WEBPUSH extension March 2025
C: a1 LWEBPUSH *
S: * WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
https://push.endpoint.tld/random1 0
S: * WEBPUSH 80a3b492-bc9c-46a9-91ab-5866b27073bb \
https://push.endpoint.tld/random2 NIL
S: * WEBPUSH 28626e4e-37d1-456c-a667-5258b5528508 \
https://push.endpoint.tld/random3 1112
S: a1 OK LWEBPUSH completed
C: a2 LWEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65
S: * WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
https://push.endpoint.tld/random1 0
S: a2 OK LWEBPUSH completed
5.5. SILWEBPUSH Command
This command is only available in authenticated or selected state.
Arguments: subscription ID
duration to silence subscription, in seconds. MUST be equal or
higher than 0
OR "session" to silence the subscription as long as the connection
is alive.
Responses: OPTIONAL untagged response: WEBPUSH
Result: OK - create completed
NO - the subscription is unknown or inactive
BAD - command unknown or arguments invalid
The SILWEBPUSH command allows the client to silence a push
subscription for a duration. It may be useful for clients
synchronizing with the server when they receive a push notification,
without parsing it. It may also be useful for clients that support a
"do not disturb" period. When the duration is 0, the push
subscription is active again and the server will send events for this
subscription.
Clients MAY announce their subscription ID with SILWEBPUSH
subscription-id session, which causes the server to not send any push
notification as long as the connection is alive. This isn't
reflected in WEBPUSH responses. A server MAY refuse to silent for
the session more than one subscription from the same connection.
Gougeon Expires 20 September 2025 [Page 9]
Internet-Draft The IMAP WEBPUSH extension March 2025
For example, when a client receives a push notification, it may
silence the subscription for the duration (or a little less) that it
stays connected to the server:
Example:
C: a1 SILWEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 10
S: * WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
https://push.endpoint.tld/random1 10
S: a1 OK SILWEBPUSH completed
C: a2 SILWEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 session
S: * WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
https://push.endpoint.tld/random1 10
S: a2 OK SILWEBPUSH completed
6. Server Responses
6.1. VAPID Response
The VAPID response occurs as a result of a GETVAPID command. It
returns the server VAPID public key ([RFC8292]). This is a public
key on the P-256 curve. It MUST be encoded in the uncompressed form
[SEC_1] (section 2.3.3, replicated from X9.62), and base64url encoded
as described in [RFC7515]. The server MAY use a different key pair
for each account.
Example:
S: * VAPID BOniQ9xHBPNY9gnQW4o-16vHqOb40pEIMifyUdFsxAgy\
zVkFMguxw0QrdbZcq8hRjN2zpeInRvKVPlkzABvuTnI
6.2. WEBPUSH Response
The WEBPUSH response occurs as a result of a LWEBPUSH command. It
MAY be returned as a result of a WEBPUSH, or a SILWEBPUSH command
too. It contains the subscription ID, the push endpoint of the
subscription, and if the subscription is active, the silenced
duration in seconds, else nil.
Example:
S: * WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
https://push.endpoint.tld/random1 0
Gougeon Expires 20 September 2025 [Page 10]
Internet-Draft The IMAP WEBPUSH extension March 2025
6.3. SELECT Response
The SELECT response is sent with a push notification by the server to
inform to which mailbox the following events refer to. It may be
used by clients to synchronize a mailbox on push, regardless what are
the new events.
Example:
Push: * SELECT INBOX
6.4. ACKWEBPUSH Response
The ACKWEBPUSH response is sent with a push notification by the
server when a webpush subscription is created or updated (when at
least one field is different) with the WEBPUSH command. It contains
a random token.
The random token SHOULD be a UUIDv4 token. The token SHOULD be valid
for 10 minutes.
The token is then send to the server with the ACKWEBPUSH command in
order to activate the new or updated subscription.
Example:
Push: * ACKWEBPUSH 585078c5-fb8b-4ed0-8e77-474ab08f0a30
6.5. SYNC Response
The SYNC response is sent with a push notification by the server when
a response that should be pushed exceed the 3993 bytes limit. It MAY
also be used as a generic push event. It is used to inform the
client that it SHOULD send a command to retrieve the response.
It optionally contains the first word of the response in question.
It can be used by the client to determine if it synchronize with the
server or not.
For example, if a server has a lot of flags, and the list exceed the
limit, the server sends a SYNC for FLAGS.
Example, instead of sending:
Push: * SELECT INBOX
Push> * FLAGS (\Answered \Flagged \Draft \Deleted \Seen [Very long \
list of flags ...])
Gougeon Expires 20 September 2025 [Page 11]
Internet-Draft The IMAP WEBPUSH extension March 2025
The server sends:
Push: * SELECT INBOX
Push> * SYNC FLAGS
7. Push notifications
Once an account has one or more push subscription (registered with
WEBPUSH command), the server sends a push message for each
subscription every time a change is recorded. This can be a change
for the account (for example when a new permanent FLAG is added) or
for the mailboxes (new mail, deletions, flag changes).
The notification is encrypted following [RFC8291] specifications,
send following [RFC8030] and authorized with [RFC8292].
The server MAY not send some events, it determines which mailboxes
and events are relevant. For example, the server may choose not to
send events for the SPAM mailbox.
7.1. Content
The server can send responses at any time. Every response relative
to a mailbox MUST be preceded by a SELECT response containing the
mailbox name. The server MAY send multiple responses in a single
push notification.
As stated in RFC8291, the cleartext content of push notifications
MUST NOT be longer than 3993 bytes. If the server wants to inform
the client about a response longer than that, it MAY send a SYNC
message.
When the server receives a new message, to send the content of the
message, it MUST send a UIDFETCH response, as defined in [RFC9586].
The UIDFETCH response SHOULD contain the the ENVELOPE, and the BINARY
if it fits in the message length limits, or SHOULD contain the the
ENVELOPE, if it fits in the limits. Instead of sending the content,
the server MAY send SYNC EXISTS or SYNC to synchronize on push.
When a message is deleted, to send a full-event, the server MUST send
a VANISHED response, as defined in [RFC7162]. It MAY send SYNC
EXPUNGE or SYNC response to synchronize on push instead.
So, when a new mail comes in, the server sends one of the following:
* UIDFETCH (ENVELOPE BINARY)
* UIDFETCH (ENVELOPE)
Gougeon Expires 20 September 2025 [Page 12]
Internet-Draft The IMAP WEBPUSH extension March 2025
* UIDFETCH (UID)
Example of a push notification containing multiple responses for the
"INBOX" mailbox, and one for "New Messages":
Push: * SELECT INBOX
Push> * 20 UIDFETCH (UID 20)
Push> * VANISHED 1,3
Push> * SELECT "New Messages"
Push> * VANISHED 4
Example of a push notification when a new mail arrives in the "New
messages" mailbox:
Push: * SELECT "New Messages"
Push> * 3 UIDFETCH (ENVELOPE \
("Mon, 7 Feb 1994 21:52:25 -0800 (PST)" \
"afternoon meeting" \
(("Fred Foobar" NIL "foobar" "Blurdybloop.example")) \
(("Fred Foobar" NIL "foobar" "Blurdybloop.example")) \
(("Fred Foobar" NIL "foobar" "Blurdybloop.example")) \
((NIL NIL "mooch" "owatagu.siam.edu.example")) \
NIL NIL NIL "<B27397-0100000@Blurdybloop.example>"))
Example of a push notification when a new mail arrives, and the
server implements synchronization on push only:
Push: * SELECT INBOX
Push> * SYNC EXISTS
7.2. WebPush headers
Push messages SHOULD have 604800 for the TTL header (a week).
Push messages with a UIDFETCH response SHOULD have high for the
Urgency header, push messages without any SELECT response SHOULD have
low for the Urgency header to low, other push messages SHOULD have
normalfor the Urgency header.
Push messages with responses other than a generic SYNC SHOULD NOT
contain a Topic header.
Gougeon Expires 20 September 2025 [Page 13]
Internet-Draft The IMAP WEBPUSH extension March 2025
7.3. Push message processing
Because all responses regarding a specific mailbox, sent by push
notifications are preceded with a SELECT response, the client MAY
parse SELECT responses only and choose to synchronize with the
server. For example, when the client receives SELECT INBOX, it
requests the server for new events.
The client MAY also parse only some other events. For example, a
client may parse UIDFETCH responses, so it can directly show
important informations on the user interface. And synchronize with
the server if it receives another response.
The client MAY parse the name only of some events too. So when it
gets a KNOWN_NOT_IMPORTANT response, the client can ignore it, or
choose to synchronize this mailbox with the server during the next
periodic synchronization.
The server MAY not send events that it considers not important.
The client MUST NOT rely exclusively on push notifications to stay
synchronized as they may arrive out of order, and delivery isn't
guarenteed. Especially if the client uses the contents of the push
messages, or if the client performs partial synchronization on push
(synchronize a single mailbox), the client MUST rely on another
mechanism to be fully synchronized. For example, a periodic
synchronization may be used.
7.4. Push server response
When the push server returns a 429 Too many requests, it should have
send a Retry-After headers [RFC9110] to indicate how long the server
has to wait before sending another request. If this header is
present, the server MUST follow the period requested. If this header
is not present, the mail server SHOULD wait 5 minutes before sending
another request to this endpoint.
When the push server returns another 4XX status code, the mail server
MUST removes the subscription.
When the push server returns a 5XX status code, the mail server
SHOULD wait 5 minutes before sending another request to the endpoint.
8. VAPID key rotation
Server VAPID key rotation may be necessary in some cases.
Gougeon Expires 20 September 2025 [Page 14]
Internet-Draft The IMAP WEBPUSH extension March 2025
When the server rotates the keys, if it still has access to the old
VAPID key, the server SHOULD send the new VAPID public key with a
VAPID response in a push notification, using the old VAPID key for
the authorization.
The server MAY keep using the old VAPID key for some time. As soon
as the old VAPID key is invalidated, old subscriptions activated with
this VAPID key MUST be deactivated.
When the server receives a WEBPUSH command for an activated
subscription that has been acknowledged with the old VAPID key, the
server MUST deactivate the subscription and MUST reply with an
untagged VAPID response and an untagged WEBPUSH response. The server
then MUST send the ACKWEBPUSH response with a new token in a push
notification.
All pending acknowledgement tokens must be invalidate when the VAPID
key is rotated.
Example of a client sending a WEBPUSH command for a subscription
activated with the old VAPID key:
C: a1 LWEBPUSH *
S: * WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
https://push.endpoint.tld/random1 0
S: a1 OK LWEBPUSH completed
C: a2 WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
https://push.example.net/push/random1 \
BCVxsr7N_eNgVRqvHtD0zTZsEc6-VV-JvLexhqUzORcxaOzi6-AYWXvTBHm4bj\
yPjs7Vd8pZGH6SRpkNtoIAiw4 \
BTBZMqHH6r4Tts7J_aSIgg
S: * VAPID BOniQ9xHBPNY9gnQW4o-16vHqOb40pEIMifyUdFsxAgy\
zVkFMguxw0QrdbZcq8hRjN2zpeInRvKVPlkzABvuTnI
S: * WEBPUSH a8282bf9-6102-4e1b-bb61-d26d0e532e65 \
https://push.example.net/push/random1 NIL
S: a2 OK WEBPUSH completed
9. Formal Syntax
The following syntax specification uses the Augmented Backus-Naur
Form (ABNF) notation as specified in [RFC5234].
Non-terminals referenced but not defined below are as defined by
[RFC9051] and [RFC4466].
capability =/ "WEBPUSH"
Gougeon Expires 20 September 2025 [Page 15]
Internet-Draft The IMAP WEBPUSH extension March 2025
command-auth =/ getvapid / webpush / ackwebpush / lwebpush /
silwebpush
getvapid = "GETVAPID"
webpush = "WEBPUSH" SP (add-webpush-opt / del-webpush-opt)
ackwebpush = "ACKWEBPUSH" SP ackwebpush-token
lwebpush = "LWEBPUSH" SP (list-wildcards / subscription-id)
silwebpush = "SILWEBPUSH" SP subscription-id SP (duration /
"session")
add-webpush-opt = subscription-id SP endpoint SP pubkey SP auth
del-webpush-opt = subscription-id SP nil
response-payload =/ vapid-resp / webpush-resp / ackwebpush-resp /
sync-resp
vapid-resp = "VAPID" SP pubkey
webpush-resp = "WEBPUSH" SP subscription-id SP endpoint SP (duration
/ nil)
select-resp = "SELECT" SP mailbox
ackwebpush-resp = "ACKWEBPUSH" SP ackwebpush-token
sync-resp = "SYNC" [SP response-first-word]
push-content = 1*(response-data)
response-first-word = <response-payload until first SP>
subscription-id = atom ; Case sensitive
endpoint = "https://" text ; Case sensitive
pubkey = 87(base64url-char)
auth = 22(base64url-char)
duration = number
ackwebpush-token = atom ; UUIDv4 is recommended
Gougeon Expires 20 September 2025 [Page 16]
Internet-Draft The IMAP WEBPUSH extension March 2025
base64url-char = ALPHA / DIGIT / "_" / "-" ; Case sensitive
10. Security Considerations
The privacy and security considerations of [RFC8030] [RFC8291] and
[RFC8292] all apply to the use of this extension.
WebPush on decentralized applications may be used as a DDOS
amplification, by registering multiple time a target as the endpoint,
on multiple servers then notifying all the accounts. Requiring the
client to acknowledge one push notification (with the ACKWEBPUSH
command and response) greatly reduces this risk.
11. IANA Considerations
WEBPUSH capability need to be registered.
12. References
12.1. Normative References
[RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
ABNF", RFC 4466, DOI 10.17487/RFC4466, April 2006,
<https://www.rfc-editor.org/info/rfc4466>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>.
[RFC7162] Melnikov, A. and D. Cridland, "IMAP Extensions: Quick Flag
Changes Resynchronization (CONDSTORE) and Quick Mailbox
Resynchronization (QRESYNC)", RFC 7162,
DOI 10.17487/RFC7162, May 2014,
<https://www.rfc-editor.org/info/rfc7162>.
[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>.
[RFC8292] Thomson, M. and P. Beverloo, "Voluntary Application Server
Identification (VAPID) for Web Push", RFC 8292,
DOI 10.17487/RFC8292, November 2017,
<https://www.rfc-editor.org/info/rfc8292>.
Gougeon Expires 20 September 2025 [Page 17]
Internet-Draft The IMAP WEBPUSH extension March 2025
[RFC8291] Thomson, M., "Message Encryption for Web Push", RFC 8291,
DOI 10.17487/RFC8291, November 2017,
<https://www.rfc-editor.org/info/rfc8291>.
[RFC9051] Melnikov, A., Ed. and B. Leiba, Ed., "Internet Message
Access Protocol (IMAP) - Version 4rev2", RFC 9051,
DOI 10.17487/RFC9051, August 2021,
<https://www.rfc-editor.org/info/rfc9051>.
[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>.
[RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", STD 97, RFC 9110,
DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/info/rfc9110>.
[RFC9586] Melnikov, A., Achuthan, A. P., Nagulakonda, V., Singh, A.,
and L. Alves, "IMAP Extension for Using and Returning
Unique Identifiers (UIDs) Only", RFC 9586,
DOI 10.17487/RFC9586, May 2024,
<https://www.rfc-editor.org/info/rfc9586>.
[SEC_1] "SEC 1: Elliptic Curve Cryptography", n.d.,
<https://www.secg.org/sec1-v2.pdf>.
[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>.
[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>.
12.2. Informative References
[RFC2177] Leiba, B., "IMAP4 IDLE command", RFC 2177,
DOI 10.17487/RFC2177, June 1997,
<https://www.rfc-editor.org/info/rfc2177>.
[RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application
Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July
2019, <https://www.rfc-editor.org/info/rfc8620>.
Gougeon Expires 20 September 2025 [Page 18]
Internet-Draft The IMAP WEBPUSH extension March 2025
[RFC5465] Gulbrandsen, A., King, C., and A. Melnikov, "The IMAP
NOTIFY Extension", RFC 5465, DOI 10.17487/RFC5465,
February 2009, <https://www.rfc-editor.org/info/rfc5465>.
Author's Address
Simon Gougeon
Email: ietf@sgougeon.fr
Gougeon Expires 20 September 2025 [Page 19]