Skip to main content

The IMAP WEBPUSH extension
draft-gougeon-imap-webpush-01

Document Type Active Internet-Draft (mailmaint WG)
Author Simon Gougeon
Last updated 2025-02-12
RFC stream Internet Engineering Task Force (IETF)
Intended RFC status (None)
Formats
Additional resources Mailing list discussion
Stream WG state Candidate for WG Adoption
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-01
Network Working Group                                         S. Gougeon
Internet-Draft                                          10 February 2025
Intended status: Informational                                          
Expires: 14 August 2025

                       The IMAP WEBPUSH extension
                     draft-gougeon-imap-webpush-01

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 14 August 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 14 August 2025                 [Page 1]
Internet-Draft         The IMAP WEBPUSH extension          February 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
     4.4.  WEBPUSH_SILENT Command  . . . . . . . . . . . . . . . . .   6
   5.  Server Responses  . . . . . . . . . . . . . . . . . . . . . .   7
     5.1.  VAPID Response  . . . . . . . . . . . . . . . . . . . . .   7
     5.2.  WEBPUSH Response  . . . . . . . . . . . . . . . . . . . .   7
     5.3.  SYNC Response . . . . . . . . . . . . . . . . . . . . . .   7
   6.  Push notifications  . . . . . . . . . . . . . . . . . . . . .   8
     6.1.  Content . . . . . . . . . . . . . . . . . . . . . . . . .   8
     6.2.  Push message processing . . . . . . . . . . . . . . . . .   9
     6.3.  Push server response  . . . . . . . . . . . . . . . . . .  10
   7.  Security Considerations . . . . . . . . . . . . . . . . . . .  10
   8.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  10
   9.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  10
     9.1.  Normative References  . . . . . . . . . . . . . . . . . .  10
     9.2.  Informative References  . . . . . . . . . . . . . . . . .  11
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  11

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 14 August 2025                 [Page 2]
Internet-Draft         The IMAP WEBPUSH extension          February 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 14 August 2025                 [Page 3]
Internet-Draft         The IMAP WEBPUSH extension          February 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 WEBPUSH command creates, updates or delete a push registration
   for the account.  The server MAY return a single untagged WEBPUSH
   response before the tagged OK response.

   The registration ID is uniq per account and identify the push
   registration.  Sending a WEBPUSH command with an existing
   registration ID updates the current registration.  Sending a WEBPUSH
   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 14 August 2025                 [Page 4]
Internet-Draft         The IMAP WEBPUSH extension          February 2025

   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 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" 0
  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" 0
  S: a3 OK WEBPUSH completed
  C: a4 LWEBPUSH "*"
  S: * WEBPUSH "a8282bf9-6102-4e1b-bb61-d26d0e532e65" \
      "https://push.example.net/push/JzLQ3raZJfFBR0aqvOMsLrt54w4rJUsV" 0
  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 14 August 2025                 [Page 5]
Internet-Draft         The IMAP WEBPUSH extension          February 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" 0
   S: * WEBPUSH "80a3b492-bc9c-46a9-91ab-5866b27073bb" \
       "https://push.endpoint.tld/random2" 0
   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

4.4.  WEBPUSH_SILENT Command

   Arguments:  registration ID

      duration to silent, in seconds.  MUST be equal or higher than 0

   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 WEBPUSH_SILENT command allows the client to silent a push
   registration 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
   registration is active again and the server will send events for this
   registration.

Gougeon                  Expires 14 August 2025                 [Page 6]
Internet-Draft         The IMAP WEBPUSH extension          February 2025

   For example, when a client receives a push notification, it may
   silent the registration for the duration (or a little less) that it
   stays connected to the server:

   Example:

   C: a1 WEBPUSH_SILENT a8282bf9-6102-4e1b-bb61-d26d0e532e65 10
   S: * WEBPUSH "a8282bf9-6102-4e1b-bb61-d26d0e532e65" \
       "https://push.endpoint.tld/random1" 10
   S: a1 OK WEBPUSH_SILENT 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, or a WEBPUSH_SILENT command
   too.  It contains the registration ID, the push endpoint of the
   registration, and the silenced duration in seconds.

   Example:

   S: * WEBPUSH "a8282bf9-6102-4e1b-bb61-d26d0e532e65" \
       "https://push.endpoint.tld/random1" 0

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.

Gougeon                  Expires 14 August 2025                 [Page 7]
Internet-Draft         The IMAP WEBPUSH extension          February 2025

   Example, instead of sending:

   S: * FLAGS (\Answered \Flagged \Draft \Deleted \Seen [Very long \
       list of flags ...])

   The server sends:

   S: * SYNC FLAGS

   _Note: The response for the example is anotated like a usual
   response, but the * should be replaced by the general prefix ^ in the
   push message, as defined in the Push notifications content section._

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.  Every other response, for example relative to the
   server, must be preceded by ^. 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

   *  and FETCH (UID ENVELOPE BINARY)

Gougeon                  Expires 14 August 2025                 [Page 8]
Internet-Draft         The IMAP WEBPUSH extension          February 2025

   *  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 related to the server configuration,
   using the general prefix ^, to inform about a FLAGS response that is
   longer than 3993 bytes:

   ^ SYNC FLAGS

6.2.  Push message processing

   Because every responses sent by push notifications start with a
   prefix (the mailbox name or the general prefix ^) the client MAY
   parse the prefix only and choose to synchronize with the server.  For
   example, when the client receives INBOX ANYRESPONSE, it requests the
   server for new events.

   The client MAY also parse the prefix and some events.  For example, a
   client may parse FETCH 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 INBOX KNOWN_NOT_IMPORTANT, 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 consider not important.

Gougeon                  Expires 14 August 2025                 [Page 9]
Internet-Draft         The IMAP WEBPUSH extension          February 2025

6.3.  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.

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>.

Gougeon                  Expires 14 August 2025                [Page 10]
Internet-Draft         The IMAP WEBPUSH extension          February 2025

   [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>.

   [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 14 August 2025                [Page 11]