diff options
Diffstat (limited to 'doc/rfc/rfc9590.txt')
| -rw-r--r-- | doc/rfc/rfc9590.txt | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/doc/rfc/rfc9590.txt b/doc/rfc/rfc9590.txt new file mode 100644 index 0000000..9db6c5f --- /dev/null +++ b/doc/rfc/rfc9590.txt @@ -0,0 +1,274 @@ + + + + +Internet Engineering Task Force (IETF) K. Murchison +Request for Comments: 9590 B. Gondwana +Category: Standards Track Fastmail +ISSN: 2070-1721 May 2024 + + + IMAP Extension for Returning Mailbox METADATA in Extended LIST + +Abstract + + This document defines an extension to the Internet Message Access + Protocol (IMAP) LIST command that allows the client to request + mailbox annotations (metadata), along with other information + typically returned by the LIST command. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc9590. + +Copyright Notice + + Copyright (c) 2024 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. Code Components extracted from this document must + include Revised BSD License text as described in Section 4.e of the + Trust Legal Provisions and are provided without warranty as described + in the Revised BSD License. + +Table of Contents + + 1. Introduction + 2. Conventions Used in This Document + 3. METADATA Return Option to LIST Command + 4. Examples + 5. Formal Syntax + 6. Security Considerations + 7. Privacy Considerations + 8. IANA Considerations + 8.1. Registration of IMAP Capability LIST-METADATA + 8.2. Registration of LIST-EXTENDED Option METADATA + 9. References + 9.1. Normative References + 9.2. Informative References + Authors' Addresses + +1. Introduction + + IMAP clients sometimes fetch mailbox metadata (e.g., color) to + augment the display of mailboxes for the logged-in user. In order to + do that, the client is forced to issue a LIST or LSUB command to list + all available mailboxes, followed by a GETMETADATA command for each + mailbox found. This document defines an extension to the IMAP LIST + command that is identified by the capability string "LIST-METADATA". + The LIST-METADATA extension allows the client to request annotations + on available mailboxes, along with other information typically + returned by the LIST command. + +2. Conventions Used in This Document + + In examples, "C:" indicates lines sent by a client that is connected + to a server. "S:" indicates lines sent by the server to the 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. + + Long lines in examples are wrapped using "The Single Backslash + Strategy" described in [RFC8792]. + +3. METADATA Return Option to LIST Command + + [RFC5464] defines the GETMETADATA command that is used by an IMAP + client to retrieve mailbox annotations. Sometimes, a client will + have to look up the metadata for some or all of the mailboxes + returned by the LIST command. Doing so in multiple GETMETADATA + commands wastes bandwidth and can degrade performance if the client + does not pipeline the requests. + + This document extends the LIST command with a new return option, + "METADATA", which allows the client to request all of the desired + information in a single command. For each listable mailbox matching + the list pattern and selection options, the server MUST return an + untagged LIST response, followed by one or more untagged METADATA + responses containing the mailbox annotations requested by the client. + The untagged METADATA responses to an extended LIST command have the + same syntax and semantics as those that would be returned by + GETMETADATA commands on the same set of listable mailboxes (see + Section 4.4.1 of [RFC5464]). As per Section 4.4 of [RFC5464], the + server may return all requested annotations in a single METADATA + response for each mailbox, or it may split the requested annotations + into multiple METADATA responses for each mailbox. + + If the server is unable to look up the annotations for given mailbox, + it MAY drop the corresponding METADATA response. In such a + situation, the LIST command would still return a tagged OK reply. + +4. Examples + + The following are examples of fetching metadata from only the top- + level hierarchies of the mailbox using different sets of selection + criteria (see Section 6.3.9 of [RFC9051]). + + In this example: + + * The "color" annotation for the "foo" mailbox has not been set, so + the METADATA response has a value of "NIL" (i.e., has no value). + + * "bar" has children, but isn't an actual mailbox itself, so it has + no METADATA response. + + ========== NOTE: '\' line wrapping per RFC 8792 =========== + + C: A00 CAPABILITY + S: * CAPABILITY IMAP4rev1 IMAP4rev2 \ + LIST-EXTENDED LIST-METADATA METADATA + S: A00 OK Completed. + C: A01 LIST "" % \ + RETURN (METADATA ("/shared/vendor/cmu/cyrus-imapd/color")) + S: * LIST () "." "INBOX" + S: * METADATA INBOX ("/shared/vendor/cmu/cyrus-imapd/color" "#b71c1c") + S: * LIST () "." "foo" + S: * METADATA "foo" ("/shared/vendor/cmu/cyrus-imapd/color" NIL) + S: * LIST (\NonExistent) "." "bar" + S: A01 OK List completed. + + In this example, the LIST response for the "foo" mailbox is returned + because it has matching children, but no METADATA response is + returned because "foo" itself doesn't match the selection criteria. + + ========== NOTE: '\' line wrapping per RFC 8792 =========== + + C: A02 LIST (SUBSCRIBED RECURSIVEMATCH) "" % \ + RETURN (METADATA ("/shared/vendor/cmu/cyrus-imapd/color")) + S: * LIST (\Subscribed) "." "INBOX" + S: * METADATA INBOX ("/shared/vendor/cmu/cyrus-imapd/color" "#b71c1c") + S: * LIST () "." "foo" (CHILDINFO ("SUBSCRIBED")) + S: A02 OK List completed. + +5. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) as described in [RFC5234]. Note that "return-option" is + defined in [RFC5258] and "entry" is defined in [RFC5464]. + + return-option =/ "METADATA" SP "(" entry *(SP entry) ")" + +6. Security Considerations + + This specification does not introduce any additional security + concerns beyond those described in [RFC5258] and [RFC5464]. + +7. Privacy Considerations + + This specification does not introduce any additional privacy concerns + beyond those described in [RFC5464]. + +8. IANA Considerations + +8.1. Registration of IMAP Capability LIST-METADATA + + Per this document, IANA has added the "LIST-METADATA" IMAP capability + to the "IMAP Capabilities" registry located at + <https://www.iana.org/assignments/imap4-capabilities/>. + +8.2. Registration of LIST-EXTENDED Option METADATA + + Per this document, IANA has registered the "METADATA" LIST-EXTENDED + option in the "LIST-EXTENDED options" registry located at + <https://www.iana.org/assignments/imap-list-extended/>. + + LIST-EXTENDED option name: + METADATA + + LIST-EXTENDED option type: + RETURN + + LIST-EXTENDED option description: + Causes the LIST command to return METADATA responses in addition + to LIST responses. + + Published specification: + RFC 9590, Section 3 + + Security considerations: + RFC 9590, Section 6 + + Intended usage: + COMMON + + Person and email address to contact for further information: + Kenneth Murchison <murch@fastmailteam.com> and + Bron Gondwana <brong@fastmailteam.com> + + Owner/Change controller: + IESG <iesg@ietf.org> + +9. References + +9.1. Normative References + + [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>. + + [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>. + + [RFC5258] Leiba, B. and A. Melnikov, "Internet Message Access + Protocol version 4 - LIST Command Extensions", RFC 5258, + DOI 10.17487/RFC5258, June 2008, + <https://www.rfc-editor.org/info/rfc5258>. + + [RFC5464] Daboo, C., "The IMAP METADATA Extension", RFC 5464, + DOI 10.17487/RFC5464, February 2009, + <https://www.rfc-editor.org/info/rfc5464>. + + [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>. + + [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>. + +9.2. Informative References + + [RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, + "Handling Long Lines in Content of Internet-Drafts and + RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020, + <https://www.rfc-editor.org/info/rfc8792>. + +Authors' Addresses + + Kenneth Murchison + Fastmail US LLC + 1429 Walnut Street + Suite 1201 + Philadelphia, PA 19102 + United States of America + Email: murch@fastmailteam.com + + + Bron Gondwana + Fastmail Pty Ltd + Level 2, 114 William Street + Melbourne VIC 3000 + Australia + Email: brong@fastmailteam.com |