The IMAP WEBPUSH extension
draft-gougeon-imap-webpush-00
This document is an Internet-Draft (I-D).
Anyone may submit an I-D to the IETF.
This I-D is not endorsed by the IETF and has no formal standing in the
IETF standards process.
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Expired".
|
|
|---|---|---|---|
| Author | Simon Gougeon | ||
| Last updated | 2025-02-06 (Latest revision 2025-01-24) | ||
| RFC stream | Internet Engineering Task Force (IETF) | ||
| Formats | |||
| Additional resources | Mailing list discussion | ||
| Stream | WG state | Candidate for WG Adoption | |
| Associated WG milestone |
|
||
| Document shepherd | (None) | ||
| IESG | IESG state | I-D Exists | |
| Consensus boilerplate | Unknown | ||
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-gougeon-imap-webpush-00
Network Working Group S. Gougeon
Internet-Draft 24 January 2025
Intended status: Informational
Expires: 28 July 2025
The IMAP WEBPUSH extension
draft-gougeon-imap-webpush-00
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 28 July 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 28 July 2025 [Page 1]
Internet-Draft The IMAP WEBPUSH extension January 2025
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3
3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3
4. Client Commands . . . . . . . . . . . . . . . . . . . . . . . 3
4.1. GETVAPID Command . . . . . . . . . . . . . . . . . . . . 3
4.2. WEBPUSH Command . . . . . . . . . . . . . . . . . . . . . 4
4.3. LWEBPUSH Command . . . . . . . . . . . . . . . . . . . . 5
5. Server Responses . . . . . . . . . . . . . . . . . . . . . . 6
5.1. VAPID Response . . . . . . . . . . . . . . . . . . . . . 6
5.2. WEBPUSH Response . . . . . . . . . . . . . . . . . . . . 6
5.3. SYNC Response . . . . . . . . . . . . . . . . . . . . . . 7
6. Push notifications . . . . . . . . . . . . . . . . . . . . . 7
6.1. Content . . . . . . . . . . . . . . . . . . . . . . . . . 7
6.2. Push server response . . . . . . . . . . . . . . . . . . 8
7. Security Considerations . . . . . . . . . . . . . . . . . . . 9
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
9.1. Normative References . . . . . . . . . . . . . . . . . . 9
9.2. Informative References . . . . . . . . . . . . . . . . . 10
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10
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.
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.
Gougeon Expires 28 July 2025 [Page 2]
Internet-Draft The IMAP WEBPUSH extension January 2025
2. Conventions and Definitions
In examples, "C:" and "S:" indicate lines sent by the client and
server, respectively. 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 3 commands: GETVAPID, WEBPUSH and LWEBPUSH.
GETVAPID allows to get the server VAPID public key, WEBPUSH to
subscribe a new push registration and LWEBPUSH to list current
registrations. Every time a message is added to one of the
subscribed mailbox (with the SUBSCRIBE command), the IMAP server
sends a push message to the registered push endpoints.
4. Client Commands
4.1. GETVAPID Command
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:
Gougeon Expires 28 July 2025 [Page 3]
Internet-Draft The IMAP WEBPUSH extension January 2025
C: a1 GETVAPID
S: * VAPID \
"BOniQ9xHBPNY9gnQW4o-16vHqOb40pEIMifyUdFsxAgy\
zVkFMguxw0QrdbZcq8hRjN2zpeInRvKVPlkzABvuTnI"
S: a1 OK GETVAPID completed
4.2. WEBPUSH Command
Arguments (create/update): registration ID
push endpoint
ECDH public key
authentication secret
Arguments (delete): registration ID
NIL
Responses: OPTIONAL untagged response: WEBPUSH
Result: OK - create completed
NO - create failure: can't create webpush registration with these
arguments
BAD - command unknown or arguments invalid
The VAPID command creates, updates or delete a push registration for
the account. The server MAY return a single untagged VAPID response
before the tagged OK response.
The registration ID is uniq per account and identify the push
registration. Sending a VAPID command with an existing registration
ID updates the current registration. Sending a VAPID command with an
existing registration ID following by NIL deletes the registration.
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].
Gougeon Expires 28 July 2025 [Page 4]
Internet-Draft The IMAP WEBPUSH extension January 2025
The authentication secret is 16 random bytes. It MUST be base64url
encoded as described in [RFC7515]. This is the salt used to encrypt
push notifications following [RFC8291].
The client SHOULD register their push subscription from time to time,
like when the client starts in order to restore registrations, in
case the endpoint was removed.
Example:
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: * WEBPUSH "a8282bf9-6102-4e1b-bb61-d26d0e532e65" \
"https://push.example.net/push/random1"
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: * WEBPUSH "a8282bf9-6102-4e1b-bb61-d26d0e532e65" \
"https://push.example.net/push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV"
S: a3 OK WEBPUSH completed
C: a4 LWEBPUSH "*"
S: * WEBPUSH "a8282bf9-6102-4e1b-bb61-d26d0e532e65" \
"https://push.example.net/push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV"
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
4.3. LWEBPUSH Command
Arguments: registration ID with possible wildcards
Responses: untagged response: WEBPUSH
Result: OK - list completed
NO - list failure: can't list webpush records
BAD - arguments invalid
Gougeon Expires 28 July 2025 [Page 5]
Internet-Draft The IMAP WEBPUSH extension January 2025
The LWEBPUSH command returns a subset of webpush registrations from
the complete set of all registrations available to the client. Zero
or more untagged WEBPUSH responses are returned, containing
information to identified the registrations. The server MUST return
the WEBPUSH response for the exact registration ID if the account has
a registration with this ID. It MUST return all the account's
registrations if the argument is a wildcard "*".
Example:
C: a1 LWEBPUSH "*"
S: * WEBPUSH "a8282bf9-6102-4e1b-bb61-d26d0e532e65" \
"https://push.endpoint.tld/random1"
S: * WEBPUSH "80a3b492-bc9c-46a9-91ab-5866b27073bb" \
"https://push.endpoint.tld/random2"
S: * WEBPUSH "28626e4e-37d1-456c-a667-5258b5528508" \
"https://push.endpoint.tld/random3"
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"
S: a2 OK LWEBPUSH completed
5. Server Responses
5.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"
5.2. WEBPUSH Response
The WEBPUSH response occurs as a result of a LWEBPUSH command. It
MAY be returned as a result of a WEBPUSH command too. It contains
the registration ID and the push endpoint of the registration.
Example:
Gougeon Expires 28 July 2025 [Page 6]
Internet-Draft The IMAP WEBPUSH extension January 2025
S: * WEBPUSH "a8282bf9-6102-4e1b-bb61-d26d0e532e65" \
"https://push.endpoint.tld/random1"
5.3. 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 is
used to inform the client that it SHOULD send a command to retrieve
the response. It contains the response name in question. For
example, if a server has a lot of flags, and the list exceed the
limit, the server sends a SYNC for FLAGS.
Example:
S: * SYNC FLAGS
6. Push notifications
Once an account has one or more push registration (registered with
WEBPUSH command), the server sends a push message for each
registration 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 subscribed mailboxes (new mail, deletions, flag changes).
The notification is encrypted following [RFC8291] specifications,
send following [RFC8030] and authorized with [RFC8292].
6.1. Content
The server can send EXISTS, EXPUNGE, FETCH, and other responses at
any time. Every response relative to a mailbox MUST be preceded by
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.
If the server sends a FETCH response, it MUST include a UID FETCH
item. Every EXISTS response MUST be followed by a FETCH response.
The FETCH response SHOULD contain the UID, the ENVELOPE, and the
BINARY if it fits in the message length limits, or SHOULD contain the
UID and the ENVELOPE, if it fits in the limits.
So, when a new mail comes in, the server sends:
* EXISTS
Gougeon Expires 28 July 2025 [Page 7]
Internet-Draft The IMAP WEBPUSH extension January 2025
* and FETCH (UID ENVELOPE BINARY)
* or FETCH (UID ENVELOPE)
* or FETCH (UID)
Example of a push notification containing multiple responses for the
"INBOX" mailbox::
INBOX 2 FETCH (UID 2 FLAGS (\Deleted \Seen))
INBOX 2 EXPUNGE
Example of a push notification when a new mail arrives in the "New
messages" mailbox:
"New Messages" 2 EXISTS
"New Messages" 2 FETCH (UID 3 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 to inform about a response longer than
3993 bytes:
SYNC FLAGS
6.2. 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 registration.
When the push server returns a 5XX status code, the mail server
SHOULD wait 5 minutes before sending another request to the endpoint.
Gougeon Expires 28 July 2025 [Page 8]
Internet-Draft The IMAP WEBPUSH extension January 2025
7. Security Considerations
The privacy and security considerations of [RFC8030] [RFC8291] and
[RFC8292] all apply to the use of this extension.
8. IANA Considerations
This document has no IANA actions.
9. References
9.1. Normative References
[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>.
[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>.
[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>.
Gougeon Expires 28 July 2025 [Page 9]
Internet-Draft The IMAP WEBPUSH extension January 2025
[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>.
9.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>.
[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 28 July 2025 [Page 10]