diff --git a/docs/rfcs/README.md b/docs/rfcs/README.md index 70264ee..e011dbc 100644 --- a/docs/rfcs/README.md +++ b/docs/rfcs/README.md @@ -1,6 +1,4 @@ All RFCs related to IMAP. -TODO: -- rename the files to know what they are talking about. -- Add a brief introduction here to introduce the most important RFCs. +TODO: Add a brief introduction here to introduce the most important RFCs. diff --git a/docs/rfcs/rfc1731.txt b/docs/rfcs/rfc1731.IMAP4_auth.txt similarity index 100% rename from docs/rfcs/rfc1731.txt rename to docs/rfcs/rfc1731.IMAP4_auth.txt diff --git a/docs/rfcs/rfc1732.txt b/docs/rfcs/rfc1732.compatibiliy_IMAP2-IMAP2bis.txt similarity index 100% rename from docs/rfcs/rfc1732.txt rename to docs/rfcs/rfc1732.compatibiliy_IMAP2-IMAP2bis.txt diff --git a/docs/rfcs/rfc1733.txt b/docs/rfcs/rfc1733.models_in_IMAP4.txt similarity index 100% rename from docs/rfcs/rfc1733.txt rename to docs/rfcs/rfc1733.models_in_IMAP4.txt diff --git a/docs/rfcs/rfc1734.POP3_AUTHentication b/docs/rfcs/rfc1734.POP3_AUTHentication new file mode 100644 index 0000000..2e6c431 --- /dev/null +++ b/docs/rfcs/rfc1734.POP3_AUTHentication @@ -0,0 +1,439 @@ + + + + + + + + + + + + + + + + RFC 1734 - POP3 AUTHentication command + + + + + + + + +
+
+ +
+[Docs] [txt|pdf] [draft-myers-pop3-...] [Diff1] [Diff2]
+
+Obsoleted by: 5034 PROPOSED STANDARD
+
+
+Network Working Group                                           J. Myers
+Request for Comments: 1734                               Carnegie Mellon
+Category: Standards Track                                  December 1994
+
+
+                      POP3 AUTHentication command
+
+Status of this Memo
+
+   This document specifies an Internet standards track protocol for the
+   Internet community, and requests discussion and suggestions for
+   improvements.  Please refer to the current edition of the "Internet
+   Official Protocol Standards" (STD 1) for the standardization state
+   and status of this protocol.  Distribution of this memo is unlimited.
+
+
+1. Introduction
+
+   This document describes the optional AUTH command, for indicating an
+   authentication mechanism to the server, performing an authentication
+   protocol exchange, and optionally negotiating a protection mechanism
+   for subsequent protocol interactions.  The authentication and
+   protection mechanisms used by the POP3 AUTH command are those used by
+   IMAP4.
+
+
+2. The AUTH command
+
+   AUTH mechanism
+
+         Arguments:
+             a string identifying an IMAP4 authentication mechanism,
+             such as defined by [IMAP4-AUTH].  Any use of the string
+             "imap" used in a server authentication identity in the
+             definition of an authentication mechanism is replaced with
+             the string "pop".
+
+         Restrictions:
+             may only be given in the AUTHORIZATION state
+
+         Discussion:
+             The AUTH command indicates an authentication mechanism to
+             the server.  If the server supports the requested
+             authentication mechanism, it performs an authentication
+             protocol exchange to authenticate and identify the user.
+             Optionally, it also negotiates a protection mechanism for
+             subsequent protocol interactions.  If the requested
+             authentication mechanism is not supported, the server
+
+
+
+Myers                                                           [Page 1]
+

+RFC 1734                       POP3 AUTH                   December 1994
+
+
+             should reject the AUTH command by sending a negative
+             response.
+
+             The authentication protocol exchange consists of a series
+             of server challenges and client answers that are specific
+             to the authentication mechanism.  A server challenge,
+             otherwise known as a ready response, is a line consisting
+             of a "+" character followed by a single space and a BASE64
+             encoded string.  The client answer consists of a line
+             containing a BASE64 encoded string.  If the client wishes
+             to cancel an authentication exchange, it should issue a
+             line with a single "*".  If the server receives such an
+             answer, it must reject the AUTH command by sending a
+             negative response.
+
+             A protection mechanism provides integrity and privacy
+             protection to the protocol session.  If a protection
+             mechanism is negotiated, it is applied to all subsequent
+             data sent over the connection.  The protection mechanism
+             takes effect immediately following the CRLF that concludes
+             the authentication exchange for the client, and the CRLF of
+             the positive response for the server.  Once the protection
+             mechanism is in effect, the stream of command and response
+             octets is processed into buffers of ciphertext.  Each
+             buffer is transferred over the connection as a stream of
+             octets prepended with a four octet field in network byte
+             order that represents the length of the following data.
+             The maximum ciphertext buffer length is defined by the
+             protection mechanism.
+
+             The server is not required to support any particular
+             authentication mechanism, nor are authentication mechanisms
+             required to support any protection mechanisms.  If an AUTH
+             command fails with a negative response, the session remains
+             in the AUTHORIZATION state and client may try another
+             authentication mechanism by issuing another AUTH command,
+             or may attempt to authenticate by using the USER/PASS or
+             APOP commands.  In other words, the client may request
+             authentication types in decreasing order of preference,
+             with the USER/PASS or APOP command as a last resort.
+
+             Should the client successfully complete the authentication
+             exchange, the POP3 server issues a positive response and
+             the POP3 session enters the TRANSACTION state.
+
+         Possible Responses:
+             +OK maildrop locked and ready
+             -ERR authentication exchange failed
+
+
+
+Myers                                                           [Page 2]
+

+RFC 1734                       POP3 AUTH                   December 1994
+
+
+
+         Examples:
+             S: +OK POP3 server ready
+             C: AUTH KERBEROS_V4
+             S: + AmFYig==
+             C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT
+                +nZImJjnTNHJUtxAA+o0KPKfHEcAFs9a3CL5Oebe/ydHJUwYFd
+                WwuQ1MWiy6IesKvjL5rL9WjXUb9MwT9bpObYLGOKi1Qh
+             S: + or//EoAADZI=
+             C: DiAF5A4gA+oOIALuBkAAmw==
+             S: +OK Kerberos V4 authentication successful
+                ...
+             C: AUTH FOOBAR
+             S: -ERR Unrecognized authentication type
+
+              Note: the line breaks in the first client answer  are
+              for editorial clarity and are not in real authentica-
+              tors.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Myers                                                           [Page 3]
+

+RFC 1734                       POP3 AUTH                   December 1994
+
+
+3. Formal Syntax
+
+   The following syntax specification uses the augmented Backus-Naur
+   Form (BNF) notation as specified in RFC 822.
+
+   Except as noted otherwise, all alphabetic characters are case-
+   insensitive.  The use of upper or lower case characters to define
+   token strings is for editorial clarity only.  Implementations MUST
+   accept these strings in a case-insensitive fashion.
+
+   ATOM_CHAR       ::= <any CHAR except atom_specials>
+
+   atom_specials   ::= "(" / ")" / "{" / SPACE / CTLs / "%" / "*" /
+                       <"> / "\"
+
+   auth            ::= "AUTH" 1*(SPACE / TAB) auth_type *(CRLF base64)
+                       CRLF
+
+   auth_type       ::= 1*ATOM_CHAR
+
+   base64          ::= *(4base64_CHAR) [base64_terminal]
+
+   base64_char     ::= "A" / "B" / "C" / "D" / "E" / "F" / "G" / "H" /
+           "I" / "J" / "K" / "L" / "M" / "N" / "O" / "P" /
+                       "Q" / "R" / "S" / "T" / "U" / "V" / "W" / "X" /
+                       "Y" / "Z" /
+                       "a" / "b" / "c" / "d" / "e" / "f" / "g" / "h" /
+                       "i" / "j" / "k" / "l" / "m" / "n" / "o" / "p" /
+                       "q" / "r" / "s" / "t" / "u" / "v" / "w" / "x" /
+                       "y" / "z" /
+                       "0" / "1" / "2" / "3" / "4" / "5" / "6" / "7" /
+                       "8" / "9" / "+" / "/"
+                       ;; Case-sensitive
+
+   base64_terminal ::= (2base64_char "==") / (3base64_char "=")
+
+   CHAR            ::= <any 7-bit US-ASCII character except NUL,
+                        0x01 - 0x7f>
+
+   continue_req    ::= "+" SPACE base64 CRLF
+
+   CR              ::= <ASCII CR, carriage return, 0x0C>
+
+   CRLF            ::= CR LF
+
+   CTL             ::= <any ASCII control character and DEL,
+                        0x00 - 0x1f, 0x7f>
+
+
+
+
+Myers                                                           [Page 4]
+

+RFC 1734                       POP3 AUTH                   December 1994
+
+
+   LF              ::= <ASCII LF, line feed, 0x0A>
+
+   SPACE           ::= <ASCII SP, space, 0x20>
+
+   TAB             ::= <ASCII HT, tab, 0x09>
+
+
+
+4. References
+
+   [IMAP4-AUTH]  Myers, J., "IMAP4 Authentication Mechanisms", RFC 1731,
+   Carnegie Mellon, December 1994.
+
+
+
+5. Security Considerations
+
+   Security issues are discussed throughout this memo.
+
+
+
+6. Author's Address
+
+   John G. Myers
+   Carnegie-Mellon University
+   5000 Forbes Ave
+   Pittsburgh, PA 15213
+
+   EMail: jgm+@cmu.edu
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Myers                                                           [Page 5]
+
+

+Html markup produced by rfcmarkup 1.111, available from +https://tools.ietf.org/tools/rfcmarkup/ + + diff --git a/docs/rfcs/rfc1939.txt b/docs/rfcs/rfc1939.txt deleted file mode 100644 index b11350e..0000000 --- a/docs/rfcs/rfc1939.txt +++ /dev/null @@ -1,1291 +0,0 @@ - - - - - - -Network Working Group J. Myers -Request for Comments: 1939 Carnegie Mellon -STD: 53 M. Rose -Obsoletes: 1725 Dover Beach Consulting, Inc. -Category: Standards Track May 1996 - - - Post Office Protocol - Version 3 - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Table of Contents - - 1. Introduction ................................................ 2 - 2. A Short Digression .......................................... 2 - 3. Basic Operation ............................................. 3 - 4. The AUTHORIZATION State ..................................... 4 - QUIT Command ................................................ 5 - 5. The TRANSACTION State ....................................... 5 - STAT Command ................................................ 6 - LIST Command ................................................ 6 - RETR Command ................................................ 8 - DELE Command ................................................ 8 - NOOP Command ................................................ 9 - RSET Command ................................................ 9 - 6. The UPDATE State ............................................ 10 - QUIT Command ................................................ 10 - 7. Optional POP3 Commands ...................................... 11 - TOP Command ................................................. 11 - UIDL Command ................................................ 12 - USER Command ................................................ 13 - PASS Command ................................................ 14 - APOP Command ................................................ 15 - 8. Scaling and Operational Considerations ...................... 16 - 9. POP3 Command Summary ........................................ 18 - 10. Example POP3 Session ....................................... 19 - 11. Message Format ............................................. 19 - 12. References ................................................. 20 - 13. Security Considerations .................................... 20 - 14. Acknowledgements ........................................... 20 - 15. Authors' Addresses ......................................... 21 - Appendix A. Differences from RFC 1725 .......................... 22 - - - -Myers & Rose Standards Track [Page 1] - -RFC 1939 POP3 May 1996 - - - Appendix B. Command Index ...................................... 23 - -1. Introduction - - On certain types of smaller nodes in the Internet it is often - impractical to maintain a message transport system (MTS). For - example, a workstation may not have sufficient resources (cycles, - disk space) in order to permit a SMTP server [RFC821] and associated - local mail delivery system to be kept resident and continuously - running. Similarly, it may be expensive (or impossible) to keep a - personal computer interconnected to an IP-style network for long - amounts of time (the node is lacking the resource known as - "connectivity"). - - Despite this, it is often very useful to be able to manage mail on - these smaller nodes, and they often support a user agent (UA) to aid - the tasks of mail handling. To solve this problem, a node which can - support an MTS entity offers a maildrop service to these less endowed - nodes. The Post Office Protocol - Version 3 (POP3) is intended to - permit a workstation to dynamically access a maildrop on a server - host in a useful fashion. Usually, this means that the POP3 protocol - is used to allow a workstation to retrieve mail that the server is - holding for it. - - POP3 is not intended to provide extensive manipulation operations of - mail on the server; normally, mail is downloaded and then deleted. A - more advanced (and complex) protocol, IMAP4, is discussed in - [RFC1730]. - - For the remainder of this memo, the term "client host" refers to a - host making use of the POP3 service, while the term "server host" - refers to a host which offers the POP3 service. - -2. A Short Digression - - This memo does not specify how a client host enters mail into the - transport system, although a method consistent with the philosophy of - this memo is presented here: - - When the user agent on a client host wishes to enter a message - into the transport system, it establishes an SMTP connection to - its relay host and sends all mail to it. This relay host could - be, but need not be, the POP3 server host for the client host. Of - course, the relay host must accept mail for delivery to arbitrary - recipient addresses, that functionality is not required of all - SMTP servers. - - - - - -Myers & Rose Standards Track [Page 2] - -RFC 1939 POP3 May 1996 - - -3. Basic Operation - - Initially, the server host starts the POP3 service by listening on - TCP port 110. When a client host wishes to make use of the service, - it establishes a TCP connection with the server host. When the - connection is established, the POP3 server sends a greeting. The - client and POP3 server then exchange commands and responses - (respectively) until the connection is closed or aborted. - - Commands in the POP3 consist of a case-insensitive keyword, possibly - followed by one or more arguments. All commands are terminated by a - CRLF pair. Keywords and arguments consist of printable ASCII - characters. Keywords and arguments are each separated by a single - SPACE character. Keywords are three or four characters long. Each - argument may be up to 40 characters long. - - Responses in the POP3 consist of a status indicator and a keyword - possibly followed by additional information. All responses are - terminated by a CRLF pair. Responses may be up to 512 characters - long, including the terminating CRLF. There are currently two status - indicators: positive ("+OK") and negative ("-ERR"). Servers MUST - send the "+OK" and "-ERR" in upper case. - - Responses to certain commands are multi-line. In these cases, which - are clearly indicated below, after sending the first line of the - response and a CRLF, any additional lines are sent, each terminated - by a CRLF pair. When all lines of the response have been sent, a - final line is sent, consisting of a termination octet (decimal code - 046, ".") and a CRLF pair. If any line of the multi-line response - begins with the termination octet, the line is "byte-stuffed" by - pre-pending the termination octet to that line of the response. - Hence a multi-line response is terminated with the five octets - "CRLF.CRLF". When examining a multi-line response, the client checks - to see if the line begins with the termination octet. If so and if - octets other than CRLF follow, the first octet of the line (the - termination octet) is stripped away. If so and if CRLF immediately - follows the termination character, then the response from the POP - server is ended and the line containing ".CRLF" is not considered - part of the multi-line response. - - A POP3 session progresses through a number of states during its - lifetime. Once the TCP connection has been opened and the POP3 - server has sent the greeting, the session enters the AUTHORIZATION - state. In this state, the client must identify itself to the POP3 - server. Once the client has successfully done this, the server - acquires resources associated with the client's maildrop, and the - session enters the TRANSACTION state. In this state, the client - requests actions on the part of the POP3 server. When the client has - - - -Myers & Rose Standards Track [Page 3] - -RFC 1939 POP3 May 1996 - - - issued the QUIT command, the session enters the UPDATE state. In - this state, the POP3 server releases any resources acquired during - the TRANSACTION state and says goodbye. The TCP connection is then - closed. - - A server MUST respond to an unrecognized, unimplemented, or - syntactically invalid command by responding with a negative status - indicator. A server MUST respond to a command issued when the - session is in an incorrect state by responding with a negative status - indicator. There is no general method for a client to distinguish - between a server which does not implement an optional command and a - server which is unwilling or unable to process the command. - - A POP3 server MAY have an inactivity autologout timer. Such a timer - MUST be of at least 10 minutes' duration. The receipt of any command - from the client during that interval should suffice to reset the - autologout timer. When the timer expires, the session does NOT enter - the UPDATE state--the server should close the TCP connection without - removing any messages or sending any response to the client. - -4. The AUTHORIZATION State - - Once the TCP connection has been opened by a POP3 client, the POP3 - server issues a one line greeting. This can be any positive - response. An example might be: - - S: +OK POP3 server ready - - The POP3 session is now in the AUTHORIZATION state. The client must - now identify and authenticate itself to the POP3 server. Two - possible mechanisms for doing this are described in this document, - the USER and PASS command combination and the APOP command. Both - mechanisms are described later in this document. Additional - authentication mechanisms are described in [RFC1734]. While there is - no single authentication mechanism that is required of all POP3 - servers, a POP3 server must of course support at least one - authentication mechanism. - - Once the POP3 server has determined through the use of any - authentication command that the client should be given access to the - appropriate maildrop, the POP3 server then acquires an exclusive- - access lock on the maildrop, as necessary to prevent messages from - being modified or removed before the session enters the UPDATE state. - If the lock is successfully acquired, the POP3 server responds with a - positive status indicator. The POP3 session now enters the - TRANSACTION state, with no messages marked as deleted. If the - maildrop cannot be opened for some reason (for example, a lock can - not be acquired, the client is denied access to the appropriate - - - -Myers & Rose Standards Track [Page 4] - -RFC 1939 POP3 May 1996 - - - maildrop, or the maildrop cannot be parsed), the POP3 server responds - with a negative status indicator. (If a lock was acquired but the - POP3 server intends to respond with a negative status indicator, the - POP3 server must release the lock prior to rejecting the command.) - After returning a negative status indicator, the server may close the - connection. If the server does not close the connection, the client - may either issue a new authentication command and start again, or the - client may issue the QUIT command. - - After the POP3 server has opened the maildrop, it assigns a message- - number to each message, and notes the size of each message in octets. - The first message in the maildrop is assigned a message-number of - "1", the second is assigned "2", and so on, so that the nth message - in a maildrop is assigned a message-number of "n". In POP3 commands - and responses, all message-numbers and message sizes are expressed in - base-10 (i.e., decimal). - - Here is the summary for the QUIT command when used in the - AUTHORIZATION state: - - QUIT - - Arguments: none - - Restrictions: none - - Possible Responses: - +OK - - Examples: - C: QUIT - S: +OK dewey POP3 server signing off - -5. The TRANSACTION State - - Once the client has successfully identified itself to the POP3 server - and the POP3 server has locked and opened the appropriate maildrop, - the POP3 session is now in the TRANSACTION state. The client may now - issue any of the following POP3 commands repeatedly. After each - command, the POP3 server issues a response. Eventually, the client - issues the QUIT command and the POP3 session enters the UPDATE state. - - - - - - - - - - -Myers & Rose Standards Track [Page 5] - -RFC 1939 POP3 May 1996 - - - Here are the POP3 commands valid in the TRANSACTION state: - - STAT - - Arguments: none - - Restrictions: - may only be given in the TRANSACTION state - - Discussion: - The POP3 server issues a positive response with a line - containing information for the maildrop. This line is - called a "drop listing" for that maildrop. - - In order to simplify parsing, all POP3 servers are - required to use a certain format for drop listings. The - positive response consists of "+OK" followed by a single - space, the number of messages in the maildrop, a single - space, and the size of the maildrop in octets. This memo - makes no requirement on what follows the maildrop size. - Minimal implementations should just end that line of the - response with a CRLF pair. More advanced implementations - may include other information. - - NOTE: This memo STRONGLY discourages implementations - from supplying additional information in the drop - listing. Other, optional, facilities are discussed - later on which permit the client to parse the messages - in the maildrop. - - Note that messages marked as deleted are not counted in - either total. - - Possible Responses: - +OK nn mm - - Examples: - C: STAT - S: +OK 2 320 - - - LIST [msg] - - Arguments: - a message-number (optional), which, if present, may NOT - refer to a message marked as deleted - - - - - -Myers & Rose Standards Track [Page 6] - -RFC 1939 POP3 May 1996 - - - Restrictions: - may only be given in the TRANSACTION state - - Discussion: - If an argument was given and the POP3 server issues a - positive response with a line containing information for - that message. This line is called a "scan listing" for - that message. - - If no argument was given and the POP3 server issues a - positive response, then the response given is multi-line. - After the initial +OK, for each message in the maildrop, - the POP3 server responds with a line containing - information for that message. This line is also called a - "scan listing" for that message. If there are no - messages in the maildrop, then the POP3 server responds - with no scan listings--it issues a positive response - followed by a line containing a termination octet and a - CRLF pair. - - In order to simplify parsing, all POP3 servers are - required to use a certain format for scan listings. A - scan listing consists of the message-number of the - message, followed by a single space and the exact size of - the message in octets. Methods for calculating the exact - size of the message are described in the "Message Format" - section below. This memo makes no requirement on what - follows the message size in the scan listing. Minimal - implementations should just end that line of the response - with a CRLF pair. More advanced implementations may - include other information, as parsed from the message. - - NOTE: This memo STRONGLY discourages implementations - from supplying additional information in the scan - listing. Other, optional, facilities are discussed - later on which permit the client to parse the messages - in the maildrop. - - Note that messages marked as deleted are not listed. - - Possible Responses: - +OK scan listing follows - -ERR no such message - - Examples: - C: LIST - S: +OK 2 messages (320 octets) - S: 1 120 - - - -Myers & Rose Standards Track [Page 7] - -RFC 1939 POP3 May 1996 - - - S: 2 200 - S: . - ... - C: LIST 2 - S: +OK 2 200 - ... - C: LIST 3 - S: -ERR no such message, only 2 messages in maildrop - - - RETR msg - - Arguments: - a message-number (required) which may NOT refer to a - message marked as deleted - - Restrictions: - may only be given in the TRANSACTION state - - Discussion: - If the POP3 server issues a positive response, then the - response given is multi-line. After the initial +OK, the - POP3 server sends the message corresponding to the given - message-number, being careful to byte-stuff the termination - character (as with all multi-line responses). - - Possible Responses: - +OK message follows - -ERR no such message - - Examples: - C: RETR 1 - S: +OK 120 octets - S: - S: . - - - DELE msg - - Arguments: - a message-number (required) which may NOT refer to a - message marked as deleted - - Restrictions: - may only be given in the TRANSACTION state - - - - - - -Myers & Rose Standards Track [Page 8] - -RFC 1939 POP3 May 1996 - - - Discussion: - The POP3 server marks the message as deleted. Any future - reference to the message-number associated with the message - in a POP3 command generates an error. The POP3 server does - not actually delete the message until the POP3 session - enters the UPDATE state. - - Possible Responses: - +OK message deleted - -ERR no such message - - Examples: - C: DELE 1 - S: +OK message 1 deleted - ... - C: DELE 2 - S: -ERR message 2 already deleted - - - NOOP - - Arguments: none - - Restrictions: - may only be given in the TRANSACTION state - - Discussion: - The POP3 server does nothing, it merely replies with a - positive response. - - Possible Responses: - +OK - - Examples: - C: NOOP - S: +OK - - - RSET - - Arguments: none - - Restrictions: - may only be given in the TRANSACTION state - - Discussion: - If any messages have been marked as deleted by the POP3 - server, they are unmarked. The POP3 server then replies - - - -Myers & Rose Standards Track [Page 9] - -RFC 1939 POP3 May 1996 - - - with a positive response. - - Possible Responses: - +OK - - Examples: - C: RSET - S: +OK maildrop has 2 messages (320 octets) - -6. The UPDATE State - - When the client issues the QUIT command from the TRANSACTION state, - the POP3 session enters the UPDATE state. (Note that if the client - issues the QUIT command from the AUTHORIZATION state, the POP3 - session terminates but does NOT enter the UPDATE state.) - - If a session terminates for some reason other than a client-issued - QUIT command, the POP3 session does NOT enter the UPDATE state and - MUST not remove any messages from the maildrop. - - QUIT - - Arguments: none - - Restrictions: none - - Discussion: - The POP3 server removes all messages marked as deleted - from the maildrop and replies as to the status of this - operation. If there is an error, such as a resource - shortage, encountered while removing messages, the - maildrop may result in having some or none of the messages - marked as deleted be removed. In no case may the server - remove any messages not marked as deleted. - - Whether the removal was successful or not, the server - then releases any exclusive-access lock on the maildrop - and closes the TCP connection. - - Possible Responses: - +OK - -ERR some deleted messages not removed - - Examples: - C: QUIT - S: +OK dewey POP3 server signing off (maildrop empty) - ... - C: QUIT - - - -Myers & Rose Standards Track [Page 10] - -RFC 1939 POP3 May 1996 - - - S: +OK dewey POP3 server signing off (2 messages left) - ... - -7. Optional POP3 Commands - - The POP3 commands discussed above must be supported by all minimal - implementations of POP3 servers. - - The optional POP3 commands described below permit a POP3 client - greater freedom in message handling, while preserving a simple POP3 - server implementation. - - NOTE: This memo STRONGLY encourages implementations to support - these commands in lieu of developing augmented drop and scan - listings. In short, the philosophy of this memo is to put - intelligence in the part of the POP3 client and not the POP3 - server. - - TOP msg n - - Arguments: - a message-number (required) which may NOT refer to to a - message marked as deleted, and a non-negative number - of lines (required) - - Restrictions: - may only be given in the TRANSACTION state - - Discussion: - If the POP3 server issues a positive response, then the - response given is multi-line. After the initial +OK, the - POP3 server sends the headers of the message, the blank - line separating the headers from the body, and then the - number of lines of the indicated message's body, being - careful to byte-stuff the termination character (as with - all multi-line responses). - - Note that if the number of lines requested by the POP3 - client is greater than than the number of lines in the - body, then the POP3 server sends the entire message. - - Possible Responses: - +OK top of message follows - -ERR no such message - - Examples: - C: TOP 1 10 - S: +OK - - - -Myers & Rose Standards Track [Page 11] - -RFC 1939 POP3 May 1996 - - - S: - S: . - ... - C: TOP 100 3 - S: -ERR no such message - - - UIDL [msg] - - Arguments: - a message-number (optional), which, if present, may NOT - refer to a message marked as deleted - - Restrictions: - may only be given in the TRANSACTION state. - - Discussion: - If an argument was given and the POP3 server issues a positive - response with a line containing information for that message. - This line is called a "unique-id listing" for that message. - - If no argument was given and the POP3 server issues a positive - response, then the response given is multi-line. After the - initial +OK, for each message in the maildrop, the POP3 server - responds with a line containing information for that message. - This line is called a "unique-id listing" for that message. - - In order to simplify parsing, all POP3 servers are required to - use a certain format for unique-id listings. A unique-id - listing consists of the message-number of the message, - followed by a single space and the unique-id of the message. - No information follows the unique-id in the unique-id listing. - - The unique-id of a message is an arbitrary server-determined - string, consisting of one to 70 characters in the range 0x21 - to 0x7E, which uniquely identifies a message within a - maildrop and which persists across sessions. This - persistence is required even if a session ends without - entering the UPDATE state. The server should never reuse an - unique-id in a given maildrop, for as long as the entity - using the unique-id exists. - - Note that messages marked as deleted are not listed. - - While it is generally preferable for server implementations - to store arbitrarily assigned unique-ids in the maildrop, - - - -Myers & Rose Standards Track [Page 12] - -RFC 1939 POP3 May 1996 - - - this specification is intended to permit unique-ids to be - calculated as a hash of the message. Clients should be able - to handle a situation where two identical copies of a - message in a maildrop have the same unique-id. - - Possible Responses: - +OK unique-id listing follows - -ERR no such message - - Examples: - C: UIDL - S: +OK - S: 1 whqtswO00WBw418f9t5JxYwZ - S: 2 QhdPYR:00WBw1Ph7x7 - S: . - ... - C: UIDL 2 - S: +OK 2 QhdPYR:00WBw1Ph7x7 - ... - C: UIDL 3 - S: -ERR no such message, only 2 messages in maildrop - - - USER name - - Arguments: - a string identifying a mailbox (required), which is of - significance ONLY to the server - - Restrictions: - may only be given in the AUTHORIZATION state after the POP3 - greeting or after an unsuccessful USER or PASS command - - Discussion: - To authenticate using the USER and PASS command - combination, the client must first issue the USER - command. If the POP3 server responds with a positive - status indicator ("+OK"), then the client may issue - either the PASS command to complete the authentication, - or the QUIT command to terminate the POP3 session. If - the POP3 server responds with a negative status indicator - ("-ERR") to the USER command, then the client may either - issue a new authentication command or may issue the QUIT - command. - - The server may return a positive response even though no - such mailbox exists. The server may return a negative - response if mailbox exists, but does not permit plaintext - - - -Myers & Rose Standards Track [Page 13] - -RFC 1939 POP3 May 1996 - - - password authentication. - - Possible Responses: - +OK name is a valid mailbox - -ERR never heard of mailbox name - - Examples: - C: USER frated - S: -ERR sorry, no mailbox for frated here - ... - C: USER mrose - S: +OK mrose is a real hoopy frood - - - PASS string - - Arguments: - a server/mailbox-specific password (required) - - Restrictions: - may only be given in the AUTHORIZATION state immediately - after a successful USER command - - Discussion: - When the client issues the PASS command, the POP3 server - uses the argument pair from the USER and PASS commands to - determine if the client should be given access to the - appropriate maildrop. - - Since the PASS command has exactly one argument, a POP3 - server may treat spaces in the argument as part of the - password, instead of as argument separators. - - Possible Responses: - +OK maildrop locked and ready - -ERR invalid password - -ERR unable to lock maildrop - - Examples: - C: USER mrose - S: +OK mrose is a real hoopy frood - C: PASS secret - S: -ERR maildrop already locked - ... - C: USER mrose - S: +OK mrose is a real hoopy frood - C: PASS secret - S: +OK mrose's maildrop has 2 messages (320 octets) - - - -Myers & Rose Standards Track [Page 14] - -RFC 1939 POP3 May 1996 - - - APOP name digest - - Arguments: - a string identifying a mailbox and a MD5 digest string - (both required) - - Restrictions: - may only be given in the AUTHORIZATION state after the POP3 - greeting or after an unsuccessful USER or PASS command - - Discussion: - Normally, each POP3 session starts with a USER/PASS - exchange. This results in a server/user-id specific - password being sent in the clear on the network. For - intermittent use of POP3, this may not introduce a sizable - risk. However, many POP3 client implementations connect to - the POP3 server on a regular basis -- to check for new - mail. Further the interval of session initiation may be on - the order of five minutes. Hence, the risk of password - capture is greatly enhanced. - - An alternate method of authentication is required which - provides for both origin authentication and replay - protection, but which does not involve sending a password - in the clear over the network. The APOP command provides - this functionality. - - A POP3 server which implements the APOP command will - include a timestamp in its banner greeting. The syntax of - the timestamp corresponds to the `msg-id' in [RFC822], and - MUST be different each time the POP3 server issues a banner - greeting. For example, on a UNIX implementation in which a - separate UNIX process is used for each instance of a POP3 - server, the syntax of the timestamp might be: - - - - where `process-ID' is the decimal value of the process's - PID, clock is the decimal value of the system clock, and - hostname is the fully-qualified domain-name corresponding - to the host where the POP3 server is running. - - The POP3 client makes note of this timestamp, and then - issues the APOP command. The `name' parameter has - identical semantics to the `name' parameter of the USER - command. The `digest' parameter is calculated by applying - the MD5 algorithm [RFC1321] to a string consisting of the - timestamp (including angle-brackets) followed by a shared - - - -Myers & Rose Standards Track [Page 15] - -RFC 1939 POP3 May 1996 - - - secret. This shared secret is a string known only to the - POP3 client and server. Great care should be taken to - prevent unauthorized disclosure of the secret, as knowledge - of the secret will allow any entity to successfully - masquerade as the named user. The `digest' parameter - itself is a 16-octet value which is sent in hexadecimal - format, using lower-case ASCII characters. - - When the POP3 server receives the APOP command, it verifies - the digest provided. If the digest is correct, the POP3 - server issues a positive response, and the POP3 session - enters the TRANSACTION state. Otherwise, a negative - response is issued and the POP3 session remains in the - AUTHORIZATION state. - - Note that as the length of the shared secret increases, so - does the difficulty of deriving it. As such, shared - secrets should be long strings (considerably longer than - the 8-character example shown below). - - Possible Responses: - +OK maildrop locked and ready - -ERR permission denied - - Examples: - S: +OK POP3 server ready <1896.697170952@dbc.mtview.ca.us> - C: APOP mrose c4c9334bac560ecc979e58001b3e22fb - S: +OK maildrop has 1 message (369 octets) - - In this example, the shared secret is the string `tan- - staaf'. Hence, the MD5 algorithm is applied to the string - - <1896.697170952@dbc.mtview.ca.us>tanstaaf - - which produces a digest value of - - c4c9334bac560ecc979e58001b3e22fb - -8. Scaling and Operational Considerations - - Since some of the optional features described above were added to the - POP3 protocol, experience has accumulated in using them in large- - scale commercial post office operations where most of the users are - unrelated to each other. In these situations and others, users and - vendors of POP3 clients have discovered that the combination of using - the UIDL command and not issuing the DELE command can provide a weak - version of the "maildrop as semi-permanent repository" functionality - normally associated with IMAP. Of course the other capabilities of - - - -Myers & Rose Standards Track [Page 16] - -RFC 1939 POP3 May 1996 - - - IMAP, such as polling an existing connection for newly arrived - messages and supporting multiple folders on the server, are not - present in POP3. - - When these facilities are used in this way by casual users, there has - been a tendency for already-read messages to accumulate on the server - without bound. This is clearly an undesirable behavior pattern from - the standpoint of the server operator. This situation is aggravated - by the fact that the limited capabilities of the POP3 do not permit - efficient handling of maildrops which have hundreds or thousands of - messages. - - Consequently, it is recommended that operators of large-scale multi- - user servers, especially ones in which the user's only access to the - maildrop is via POP3, consider such options as: - - * Imposing a per-user maildrop storage quota or the like. - - A disadvantage to this option is that accumulation of messages may - result in the user's inability to receive new ones into the - maildrop. Sites which choose this option should be sure to inform - users of impending or current exhaustion of quota, perhaps by - inserting an appropriate message into the user's maildrop. - - * Enforce a site policy regarding mail retention on the server. - - Sites are free to establish local policy regarding the storage and - retention of messages on the server, both read and unread. For - example, a site might delete unread messages from the server after - 60 days and delete read messages after 7 days. Such message - deletions are outside the scope of the POP3 protocol and are not - considered a protocol violation. - - Server operators enforcing message deletion policies should take - care to make all users aware of the policies in force. - - Clients must not assume that a site policy will automate message - deletions, and should continue to explicitly delete messages using - the DELE command when appropriate. - - It should be noted that enforcing site message deletion policies - may be confusing to the user community, since their POP3 client - may contain configuration options to leave mail on the server - which will not in fact be supported by the server. - - One special case of a site policy is that messages may only be - downloaded once from the server, and are deleted after this has - been accomplished. This could be implemented in POP3 server - - - -Myers & Rose Standards Track [Page 17] - -RFC 1939 POP3 May 1996 - - - software by the following mechanism: "following a POP3 login by a - client which was ended by a QUIT, delete all messages downloaded - during the session with the RETR command". It is important not to - delete messages in the event of abnormal connection termination - (ie, if no QUIT was received from the client) because the client - may not have successfully received or stored the messages. - Servers implementing a download-and-delete policy may also wish to - disable or limit the optional TOP command, since it could be used - as an alternate mechanism to download entire messages. - -9. POP3 Command Summary - - Minimal POP3 Commands: - - USER name valid in the AUTHORIZATION state - PASS string - QUIT - - STAT valid in the TRANSACTION state - LIST [msg] - RETR msg - DELE msg - NOOP - RSET - QUIT - - Optional POP3 Commands: - - APOP name digest valid in the AUTHORIZATION state - - TOP msg n valid in the TRANSACTION state - UIDL [msg] - - POP3 Replies: - - +OK - -ERR - - Note that with the exception of the STAT, LIST, and UIDL commands, - the reply given by the POP3 server to any command is significant - only to "+OK" and "-ERR". Any text occurring after this reply - may be ignored by the client. - - - - - - - - - -Myers & Rose Standards Track [Page 18] - -RFC 1939 POP3 May 1996 - - -10. Example POP3 Session - - S: - C: - S: +OK POP3 server ready <1896.697170952@dbc.mtview.ca.us> - C: APOP mrose c4c9334bac560ecc979e58001b3e22fb - S: +OK mrose's maildrop has 2 messages (320 octets) - C: STAT - S: +OK 2 320 - C: LIST - S: +OK 2 messages (320 octets) - S: 1 120 - S: 2 200 - S: . - C: RETR 1 - S: +OK 120 octets - S: - S: . - C: DELE 1 - S: +OK message 1 deleted - C: RETR 2 - S: +OK 200 octets - S: - S: . - C: DELE 2 - S: +OK message 2 deleted - C: QUIT - S: +OK dewey POP3 server signing off (maildrop empty) - C: - S: - -11. Message Format - - All messages transmitted during a POP3 session are assumed to conform - to the standard for the format of Internet text messages [RFC822]. - - It is important to note that the octet count for a message on the - server host may differ from the octet count assigned to that message - due to local conventions for designating end-of-line. Usually, - during the AUTHORIZATION state of the POP3 session, the POP3 server - can calculate the size of each message in octets when it opens the - maildrop. For example, if the POP3 server host internally represents - end-of-line as a single character, then the POP3 server simply counts - each occurrence of this character in a message as two octets. Note - that lines in the message which start with the termination octet need - not (and must not) be counted twice, since the POP3 client will - remove all byte-stuffed termination characters when it receives a - multi-line response. - - - -Myers & Rose Standards Track [Page 19] - -RFC 1939 POP3 May 1996 - - -12. References - - [RFC821] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC - 821, USC/Information Sciences Institute, August 1982. - - [RFC822] Crocker, D., "Standard for the Format of ARPA-Internet Text - Messages", STD 11, RFC 822, University of Delaware, August 1982. - - [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, - MIT Laboratory for Computer Science, April 1992. - - [RFC1730] Crispin, M., "Internet Message Access Protocol - Version - 4", RFC 1730, University of Washington, December 1994. - - [RFC1734] Myers, J., "POP3 AUTHentication command", RFC 1734, - Carnegie Mellon, December 1994. - -13. Security Considerations - - It is conjectured that use of the APOP command provides origin - identification and replay protection for a POP3 session. - Accordingly, a POP3 server which implements both the PASS and APOP - commands should not allow both methods of access for a given user; - that is, for a given mailbox name, either the USER/PASS command - sequence or the APOP command is allowed, but not both. - - Further, note that as the length of the shared secret increases, so - does the difficulty of deriving it. - - Servers that answer -ERR to the USER command are giving potential - attackers clues about which names are valid. - - Use of the PASS command sends passwords in the clear over the - network. - - Use of the RETR and TOP commands sends mail in the clear over the - network. - - Otherwise, security issues are not discussed in this memo. - -14. Acknowledgements - - The POP family has a long and checkered history. Although primarily - a minor revision to RFC 1460, POP3 is based on the ideas presented in - RFCs 918, 937, and 1081. - - In addition, Alfred Grimstad, Keith McCloghrie, and Neil Ostroff - provided significant comments on the APOP command. - - - -Myers & Rose Standards Track [Page 20] - -RFC 1939 POP3 May 1996 - - -15. Authors' Addresses - - John G. Myers - Carnegie-Mellon University - 5000 Forbes Ave - Pittsburgh, PA 15213 - - EMail: jgm+@cmu.edu - - - Marshall T. Rose - Dover Beach Consulting, Inc. - 420 Whisman Court - Mountain View, CA 94043-2186 - - EMail: mrose@dbc.mtview.ca.us - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Myers & Rose Standards Track [Page 21] - -RFC 1939 POP3 May 1996 - - -Appendix A. Differences from RFC 1725 - - This memo is a revision to RFC 1725, a Draft Standard. It makes the - following changes from that document: - - - clarifies that command keywords are case insensitive. - - - specifies that servers must send "+OK" and "-ERR" in - upper case. - - - specifies that the initial greeting is a positive response, - instead of any string which should be a positive response. - - - clarifies behavior for unimplemented commands. - - - makes the USER and PASS commands optional. - - - clarified the set of possible responses to the USER command. - - - reverses the order of the examples in the USER and PASS - commands, to reduce confusion. - - - clarifies that the PASS command may only be given immediately - after a successful USER command. - - - clarified the persistence requirements of UIDs and added some - implementation notes. - - - specifies a UID length limitation of one to 70 octets. - - - specifies a status indicator length limitation - of 512 octets, including the CRLF. - - - clarifies that LIST with no arguments on an empty mailbox - returns success. - - - adds a reference from the LIST command to the Message Format - section - - - clarifies the behavior of QUIT upon failure - - - clarifies the security section to not imply the use of the - USER command with the APOP command. - - - adds references to RFCs 1730 and 1734 - - - clarifies the method by which a UA may enter mail into the - transport system. - - - -Myers & Rose Standards Track [Page 22] - -RFC 1939 POP3 May 1996 - - - - clarifies that the second argument to the TOP command is a - number of lines. - - - changes the suggestion in the Security Considerations section - for a server to not accept both PASS and APOP for a given user - from a "must" to a "should". - - - adds a section on scaling and operational considerations - -Appendix B. Command Index - - APOP ....................................................... 15 - DELE ....................................................... 8 - LIST ....................................................... 6 - NOOP ....................................................... 9 - PASS ....................................................... 14 - QUIT ....................................................... 5 - QUIT ....................................................... 10 - RETR ....................................................... 8 - RSET ....................................................... 9 - STAT ....................................................... 6 - TOP ........................................................ 11 - UIDL ....................................................... 12 - USER ....................................................... 13 - - - - - - - - - - - - - - - - - - - - - - - - - - - -Myers & Rose Standards Track [Page 23] - diff --git a/docs/rfcs/rfc2061.txt b/docs/rfcs/rfc2061.compatibility_IMAP4-IMAP2bis.txt similarity index 100% rename from docs/rfcs/rfc2061.txt rename to docs/rfcs/rfc2061.compatibility_IMAP4-IMAP2bis.txt diff --git a/docs/rfcs/rfc2062.txt b/docs/rfcs/rfc2062.txt deleted file mode 100644 index 865d1da..0000000 --- a/docs/rfcs/rfc2062.txt +++ /dev/null @@ -1,451 +0,0 @@ - - - - - - -Network Working Group M. Crispin -Request for Comments: 2062 University of Washington -Category: Informational December 1996 - - - Internet Message Access Protocol - Obsolete Syntax - -Status of this Memo - - This memo provides information for the Internet community. This memo - does not specify an Internet standard of any kind. Distribution of - this memo is unlimited. - -Abstract - - This document describes obsolete syntax which may be encountered by - IMAP4 implementations which deal with older versions of the Internet - Mail Access Protocol. IMAP4 implementations MAY implement this - syntax in order to maximize interoperability with older - implementations. - - This document repeats information from earlier documents, most - notably RFC 1176 and RFC 1730. - -Obsolete Commands and Fetch Data Items - - The following commands are OBSOLETE. It is NOT required to support - any of these commands or fetch data items in new server - implementations. These commands are documented here for the benefit - of implementors who may wish to support them for compatibility with - old client implementations. - - The section headings of these commands are intended to correspond - with where they would be located in the main document if they were - not obsoleted. - -6.3.OBS.1. FIND ALL.MAILBOXES Command - - Arguments: mailbox name with possible wildcards - - Data: untagged responses: MAILBOX - - Result: OK - find completed - NO - find failure: can't list that name - BAD - command unknown or arguments invalid - - - - - - -Crispin Informational [Page 1] - -RFC 2062 IMAP4 Obsolete December 1996 - - - The FIND ALL.MAILBOXES command returns a subset of names from the - complete set of all names available to the user. It returns zero - or more untagged MAILBOX replies. The mailbox argument to FIND - ALL.MAILBOXES is similar to that for LIST with an empty reference, - except that the characters "%" and "?" match a single character. - - Example: C: A002 FIND ALL.MAILBOXES * - S: * MAILBOX blurdybloop - S: * MAILBOX INBOX - S: A002 OK FIND ALL.MAILBOXES completed - -6.3.OBS.2. FIND MAILBOXES Command - - Arguments: mailbox name with possible wildcards - - Data: untagged responses: MAILBOX - - Result: OK - find completed - NO - find failure: can't list that name - BAD - command unknown or arguments invalid - - The FIND MAILBOXES command returns a subset of names from the set - of names that the user has declared as being "active" or - "subscribed". It returns zero or more untagged MAILBOX replies. - The mailbox argument to FIND MAILBOXES is similar to that for LSUB - with an empty reference, except that the characters "%" and "?" - match a single character. - - Example: C: A002 FIND MAILBOXES * - S: * MAILBOX blurdybloop - S: * MAILBOX INBOX - S: A002 OK FIND MAILBOXES completed - -6.3.OBS.3. SUBSCRIBE MAILBOX Command - - Arguments: mailbox name - - Data: no specific data for this command - - Result: OK - subscribe completed - NO - subscribe failure: can't subscribe to that name - BAD - command unknown or arguments invalid - - The SUBSCRIBE MAILBOX command is identical in effect to the - SUBSCRIBE command. A server which implements this command must be - able to distinguish between a SUBSCRIBE MAILBOX command and a - SUBSCRIBE command with a mailbox name argument of "MAILBOX". - - - - -Crispin Informational [Page 2] - -RFC 2062 IMAP4 Obsolete December 1996 - - - Example: C: A002 SUBSCRIBE MAILBOX #news.comp.mail.mime - S: A002 OK SUBSCRIBE MAILBOX to #news.comp.mail.mime - completed - C: A003 SUBSCRIBE MAILBOX - S: A003 OK SUBSCRIBE to MAILBOX completed - - -6.3.OBS.4. UNSUBSCRIBE MAILBOX Command - - Arguments: mailbox name - - Data: no specific data for this command - - Result: OK - unsubscribe completed - NO - unsubscribe failure: can't unsubscribe that name - BAD - command unknown or arguments invalid - - The UNSUBSCRIBE MAILBOX command is identical in effect to the - UNSUBSCRIBE command. A server which implements this command must - be able to distinguish between a UNSUBSCRIBE MAILBOX command and - an UNSUBSCRIBE command with a mailbox name argument of "MAILBOX". - - Example: C: A002 UNSUBSCRIBE MAILBOX #news.comp.mail.mime - S: A002 OK UNSUBSCRIBE MAILBOX from #news.comp.mail.mime - completed - C: A003 UNSUBSCRIBE MAILBOX - S: A003 OK UNSUBSCRIBE from MAILBOX completed - -6.4.OBS.1 PARTIAL Command - - Arguments: message sequence number - message data item name - position of first octet - number of octets - - Data: untagged responses: FETCH - - Result: OK - partial completed - NO - partial error: can't fetch that data - BAD - command unknown or arguments invalid - - The PARTIAL command is equivalent to the associated FETCH command, - with the added functionality that only the specified number of - octets, beginning at the specified starting octet, are returned. - Only a single message can be fetched at a time. The first octet - of a message, and hence the minimum for the starting octet, is - octet 1. - - - - -Crispin Informational [Page 3] - -RFC 2062 IMAP4 Obsolete December 1996 - - - The following FETCH items are valid data for PARTIAL: RFC822, - RFC822.HEADER, RFC822.TEXT, BODY[
], as well as any .PEEK - forms of these. - - Any partial fetch that attempts to read beyond the end of the text - is truncated as appropriate. If the starting octet is beyond the - end of the text, an empty string is returned. - - The data are returned with the FETCH response. There is no - indication of the range of the partial data in this response. It - is not possible to stream multiple PARTIAL commands of the same - data item without processing and synchronizing at each step, since - streamed commands may be executed out of order. - - There is no requirement that partial fetches follow any sequence. - For example, if a partial fetch of octets 1 through 10000 breaks - in an awkward place for BASE64 decoding, it is permitted to - continue with a partial fetch of 9987 through 19987, etc. - - The handling of the \Seen flag is the same as in the associated - FETCH command. - - Example: C: A005 PARTIAL 4 RFC822 1 1024 - S: * 1 FETCH (RFC822 {1024} - S: Return-Path: - S: ... - S: ......... FLAGS (\Seen)) - S: A005 OK PARTIAL completed - -6.4.5.OBS.1 Obsolete FETCH Data Items - - The following FETCH data items are obsolete: - - BODY[<...>0] A body part number of 0 is the [RFC-822] header of - the message. BODY[0] is functionally equivalent to - BODY[HEADER], differing in the syntax of the - resulting untagged FETCH data (BODY[0] is - returned). - - RFC822.HEADER.LINES - Functionally equivalent to BODY.PEEK[HEADER.LINES - ], differing in the syntax of the - resulting untagged FETCH data (RFC822.HEADER is - returned). - - - - - - - -Crispin Informational [Page 4] - -RFC 2062 IMAP4 Obsolete December 1996 - - - RFC822.HEADER.LINES.NOT - Functionally equivalent to - BODY.PEEK[HEADER.LINES.NOT ], - differing in the syntax of the resulting untagged - FETCH data (RFC822.HEADER is returned). - - RFC822.PEEK Functionally equivalent to BODY.PEEK[], except for - the syntax of the resulting untagged FETCH data - (RFC822 is returned). - - RFC822.TEXT.PEEK - Functionally equivalent to BODY.PEEK[TEXT], except - for the syntax of the resulting untagged FETCH data - (RFC822.TEXT is returned). - -Obsolete Responses - - The following responses are OBSOLETE. Except as noted below, these - responses MUST NOT be transmitted by new server implementations. - Client implementations SHOULD accept these responses. - - The section headings of these responses are intended to correspond - with where they would be located in the main document if they were - not obsoleted. - -7.2.OBS.1. MAILBOX Response - - Data: name - - The MAILBOX response MUST NOT be transmitted by server - implementations except in response to the obsolete FIND MAILBOXES - and FIND ALL.MAILBOXES commands. Client implementations that do - not use these commands MAY ignore this response. It is documented - here for the benefit of implementors who may wish to support it - for compatibility with old client implementations. - - This response occurs as a result of the FIND MAILBOXES and FIND - ALL.MAILBOXES commands. It returns a single name that matches the - FIND specification. There are no attributes or hierarchy - delimiter. - - Example: S: * MAILBOX blurdybloop - - - - - - - - - -Crispin Informational [Page 5] - -RFC 2062 IMAP4 Obsolete December 1996 - - -7.3.OBS.1. COPY Response - - Data: none - - The COPY response MUST NOT be transmitted by new server - implementations. Client implementations MUST ignore the COPY - response. It is documented here for the benefit of client - implementors who may encounter this response from old server - implementations. - - In some experimental versions of this protocol, this response was - returned in response to a COPY command to indicate on a - per-message basis that the message was copied successfully. - - Example: S: * 44 COPY - -7.3.OBS.2. STORE Response - - Data: message data - - The STORE response MUST NOT be transmitted by new server - implementations. Client implementations MUST treat the STORE - response as equivalent to the FETCH response. It is documented - here for the benefit of client implementors who may encounter this - response from old server implementations. - - In some experimental versions of this protocol, this response was - returned instead of FETCH in response to a STORE command to report - the new value of the flags. - - Example: S: * 69 STORE (FLAGS (\Deleted)) - -Formal Syntax of Obsolete Commands and Responses - - Each obsolete syntax rule that is suffixed with "_old" is added to - the corresponding name in the formal syntax. For example, - command_auth_old adds the FIND command to command_auth. - - command_auth_old ::= find - - command_select_old - ::= partial - - date_year_old ::= 2digit - ;; (year - 1900) - - date_time_old ::= <"> date_day_fixed "-" date_month "-" date_year - SPACE time "-" zone_name <"> - - - -Crispin Informational [Page 6] - -RFC 2062 IMAP4 Obsolete December 1996 - - - find ::= "FIND" SPACE ["ALL."] "MAILBOXES" SPACE - list_mailbox - - fetch_att_old ::= "RFC822.HEADER.LINES" [".NOT"] SPACE header_list / - fetch_text_old - - fetch_text_old ::= "BODY" [".PEEK"] section_old / - "RFC822" [".HEADER" / ".TEXT" [".PEEK"]] - - msg_data_old ::= "COPY" / ("STORE" SPACE msg_att) - - partial ::= "PARTIAL" SPACE nz_number SPACE fetch_text_old SPACE - number SPACE number - - section_old ::= "[" (number ["." number]) "]" - - subscribe_old ::= "SUBSCRIBE" SPACE "MAILBOX" SPACE mailbox - - unsubscribe_old ::= "UNSUBSCRIBE" SPACE "MAILBOX" SPACE mailbox - - zone_name ::= "UT" / "GMT" / "Z" / ;; +0000 - "AST" / "EDT" / ;; -0400 - "EST" / "CDT" / ;; -0500 - "CST" / "MDT" / ;; -0600 - "MST" / "PDT" / ;; -0700 - "PST" / "YDT" / ;; -0800 - "YST" / "HDT" / ;; -0900 - "HST" / "BDT" / ;; -1000 - "BST" / ;; -1100 - "A" / "B" / "C" / "D" / "E" / "F" / ;; +1 to +6 - "G" / "H" / "I" / "K" / "L" / "M" / ;; +7 to +12 - "N" / "O" / "P" / "Q" / "R" / "S" / ;; -1 to -6 - "T" / "U" / "V" / "W" / "X" / "Y" ;; -7 to -12 - -Security Considerations - - Security issues are not discussed in this memo. - - - - - - - - - - - - - - -Crispin Informational [Page 7] - -RFC 2062 IMAP4 Obsolete December 1996 - - -Author's Address - - Mark R. Crispin - Networks and Distributed Computing - University of Washington - 4545 15th Aveneue NE - Seattle, WA 98105-4527 - - Phone: (206) 543-5762 - EMail: MRC@CAC.Washington.EDU - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Crispin Informational [Page 8] - diff --git a/docs/rfcs/rfc2086.txt b/docs/rfcs/rfc2086.IMAP4_ACL_extension.txt similarity index 100% rename from docs/rfcs/rfc2086.txt rename to docs/rfcs/rfc2086.IMAP4_ACL_extension.txt diff --git a/docs/rfcs/rfc2087.txt b/docs/rfcs/rfc2087.IMAP4_QUOTA_extension.txt similarity index 100% rename from docs/rfcs/rfc2087.txt rename to docs/rfcs/rfc2087.IMAP4_QUOTA_extension.txt diff --git a/docs/rfcs/rfc2088.txt b/docs/rfcs/rfc2088.IMAP4_non_synchronizing_literals.txt similarity index 100% rename from docs/rfcs/rfc2088.txt rename to docs/rfcs/rfc2088.IMAP4_non_synchronizing_literals.txt diff --git a/docs/rfcs/rfc2095.txt b/docs/rfcs/rfc2095.IMAP-POP_AUTHorize_extension.txt similarity index 100% rename from docs/rfcs/rfc2095.txt rename to docs/rfcs/rfc2095.IMAP-POP_AUTHorize_extension.txt diff --git a/docs/rfcs/rfc2177.txt b/docs/rfcs/rfc2177.IMAP4_IDLE_command.txt similarity index 100% rename from docs/rfcs/rfc2177.txt rename to docs/rfcs/rfc2177.IMAP4_IDLE_command.txt diff --git a/docs/rfcs/rfc2180.txt b/docs/rfcs/rfc2180.IMAP4_multi-accessed_Mailbox_practice.txt similarity index 100% rename from docs/rfcs/rfc2180.txt rename to docs/rfcs/rfc2180.IMAP4_multi-accessed_Mailbox_practice.txt diff --git a/docs/rfcs/rfc2192.txt b/docs/rfcs/rfc2192.IMAP_URL_scheme.txt similarity index 100% rename from docs/rfcs/rfc2192.txt rename to docs/rfcs/rfc2192.IMAP_URL_scheme.txt diff --git a/docs/rfcs/rfc2193.txt b/docs/rfcs/rfc2193.IMAP4_Mailbox_referrals.txt similarity index 100% rename from docs/rfcs/rfc2193.txt rename to docs/rfcs/rfc2193.IMAP4_Mailbox_referrals.txt diff --git a/docs/rfcs/rfc2195.txt b/docs/rfcs/rfc2195.IMAP-POP_AUTHorize_extension.txt similarity index 100% rename from docs/rfcs/rfc2195.txt rename to docs/rfcs/rfc2195.IMAP-POP_AUTHorize_extension.txt diff --git a/docs/rfcs/rfc2221.txt b/docs/rfcs/rfc2221.IMAP4_Login_referrals.txt similarity index 100% rename from docs/rfcs/rfc2221.txt rename to docs/rfcs/rfc2221.IMAP4_Login_referrals.txt diff --git a/docs/rfcs/rfc2244.txt b/docs/rfcs/rfc2244.ACAP.txt similarity index 100% rename from docs/rfcs/rfc2244.txt rename to docs/rfcs/rfc2244.ACAP.txt diff --git a/docs/rfcs/rfc2342.txt b/docs/rfcs/rfc2342.IMAP4_Namespace.txt similarity index 100% rename from docs/rfcs/rfc2342.txt rename to docs/rfcs/rfc2342.IMAP4_Namespace.txt diff --git a/docs/rfcs/rfc2359.txt b/docs/rfcs/rfc2359.IMAP4_UIDPLUS_extension.txt similarity index 100% rename from docs/rfcs/rfc2359.txt rename to docs/rfcs/rfc2359.IMAP4_UIDPLUS_extension.txt diff --git a/docs/rfcs/rfc2595.txt b/docs/rfcs/rfc2595.TLS_with_IMAP-POP3_and_ACAP.txt similarity index 100% rename from docs/rfcs/rfc2595.txt rename to docs/rfcs/rfc2595.TLS_with_IMAP-POP3_and_ACAP.txt diff --git a/docs/rfcs/rfc2683.txt b/docs/rfcs/rfc2683.IMAP4_Implementation_recommendations.txt similarity index 100% rename from docs/rfcs/rfc2683.txt rename to docs/rfcs/rfc2683.IMAP4_Implementation_recommendations.txt diff --git a/docs/rfcs/rfc2821.txt b/docs/rfcs/rfc2821.txt deleted file mode 100644 index 0eac911..0000000 --- a/docs/rfcs/rfc2821.txt +++ /dev/null @@ -1,4427 +0,0 @@ - - - - - - -Network Working Group J. Klensin, Editor -Request for Comments: 2821 AT&T Laboratories -Obsoletes: 821, 974, 1869 April 2001 -Updates: 1123 -Category: Standards Track - - - Simple Mail Transfer Protocol - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2001). All Rights Reserved. - -Abstract - - This document is a self-contained specification of the basic protocol - for the Internet electronic mail transport. It consolidates, updates - and clarifies, but doesn't add new or change existing functionality - of the following: - - - the original SMTP (Simple Mail Transfer Protocol) specification of - RFC 821 [30], - - - domain name system requirements and implications for mail - transport from RFC 1035 [22] and RFC 974 [27], - - - the clarifications and applicability statements in RFC 1123 [2], - and - - - material drawn from the SMTP Extension mechanisms [19]. - - It obsoletes RFC 821, RFC 974, and updates RFC 1123 (replaces the - mail transport materials of RFC 1123). However, RFC 821 specifies - some features that were not in significant use in the Internet by the - mid-1990s and (in appendices) some additional transport models. - Those sections are omitted here in the interest of clarity and - brevity; readers needing them should refer to RFC 821. - - - - - - -Klensin Standards Track [Page 1] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - It also includes some additional material from RFC 1123 that required - amplification. This material has been identified in multiple ways, - mostly by tracking flaming on various lists and newsgroups and - problems of unusual readings or interpretations that have appeared as - the SMTP extensions have been deployed. Where this specification - moves beyond consolidation and actually differs from earlier - documents, it supersedes them technically as well as textually. - - Although SMTP was designed as a mail transport and delivery protocol, - this specification also contains information that is important to its - use as a 'mail submission' protocol, as recommended for POP [3, 26] - and IMAP [6]. Additional submission issues are discussed in RFC 2476 - [15]. - - Section 2.3 provides definitions of terms specific to this document. - Except when the historical terminology is necessary for clarity, this - document uses the current 'client' and 'server' terminology to - identify the sending and receiving SMTP processes, respectively. - - A companion document [32] discusses message headers, message bodies - and formats and structures for them, and their relationship. - -Table of Contents - - 1. Introduction .................................................. 4 - 2. The SMTP Model ................................................ 5 - 2.1 Basic Structure .............................................. 5 - 2.2 The Extension Model .......................................... 7 - 2.2.1 Background ................................................. 7 - 2.2.2 Definition and Registration of Extensions .................. 8 - 2.3 Terminology .................................................. 9 - 2.3.1 Mail Objects ............................................... 10 - 2.3.2 Senders and Receivers ...................................... 10 - 2.3.3 Mail Agents and Message Stores ............................. 10 - 2.3.4 Host ....................................................... 11 - 2.3.5 Domain ..................................................... 11 - 2.3.6 Buffer and State Table ..................................... 11 - 2.3.7 Lines ...................................................... 12 - 2.3.8 Originator, Delivery, Relay, and Gateway Systems ........... 12 - 2.3.9 Message Content and Mail Data .............................. 13 - 2.3.10 Mailbox and Address ....................................... 13 - 2.3.11 Reply ..................................................... 13 - 2.4 General Syntax Principles and Transaction Model .............. 13 - 3. The SMTP Procedures: An Overview .............................. 15 - 3.1 Session Initiation ........................................... 15 - 3.2 Client Initiation ............................................ 16 - 3.3 Mail Transactions ............................................ 16 - 3.4 Forwarding for Address Correction or Updating ................ 19 - - - -Klensin Standards Track [Page 2] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - 3.5 Commands for Debugging Addresses ............................. 20 - 3.5.1 Overview ................................................... 20 - 3.5.2 VRFY Normal Response ....................................... 22 - 3.5.3 Meaning of VRFY or EXPN Success Response ................... 22 - 3.5.4 Semantics and Applications of EXPN ......................... 23 - 3.6 Domains ...................................................... 23 - 3.7 Relaying ..................................................... 24 - 3.8 Mail Gatewaying .............................................. 25 - 3.8.1 Header Fields in Gatewaying ................................ 26 - 3.8.2 Received Lines in Gatewaying ............................... 26 - 3.8.3 Addresses in Gatewaying .................................... 26 - 3.8.4 Other Header Fields in Gatewaying .......................... 27 - 3.8.5 Envelopes in Gatewaying .................................... 27 - 3.9 Terminating Sessions and Connections ......................... 27 - 3.10 Mailing Lists and Aliases ................................... 28 - 3.10.1 Alias ..................................................... 28 - 3.10.2 List ...................................................... 28 - 4. The SMTP Specifications ....................................... 29 - 4.1 SMTP Commands ................................................ 29 - 4.1.1 Command Semantics and Syntax ............................... 29 - 4.1.1.1 Extended HELLO (EHLO) or HELLO (HELO) ................... 29 - 4.1.1.2 MAIL (MAIL) .............................................. 31 - 4.1.1.3 RECIPIENT (RCPT) ......................................... 31 - 4.1.1.4 DATA (DATA) .............................................. 33 - 4.1.1.5 RESET (RSET) ............................................. 34 - 4.1.1.6 VERIFY (VRFY) ............................................ 35 - 4.1.1.7 EXPAND (EXPN) ............................................ 35 - 4.1.1.8 HELP (HELP) .............................................. 35 - 4.1.1.9 NOOP (NOOP) .............................................. 35 - 4.1.1.10 QUIT (QUIT) ............................................. 36 - 4.1.2 Command Argument Syntax .................................... 36 - 4.1.3 Address Literals ........................................... 38 - 4.1.4 Order of Commands .......................................... 39 - 4.1.5 Private-use Commands ....................................... 40 - 4.2 SMTP Replies ................................................ 40 - 4.2.1 Reply Code Severities and Theory ........................... 42 - 4.2.2 Reply Codes by Function Groups ............................. 44 - 4.2.3 Reply Codes in Numeric Order .............................. 45 - 4.2.4 Reply Code 502 ............................................. 46 - 4.2.5 Reply Codes After DATA and the Subsequent . .... 46 - 4.3 Sequencing of Commands and Replies ........................... 47 - 4.3.1 Sequencing Overview ........................................ 47 - 4.3.2 Command-Reply Sequences .................................... 48 - 4.4 Trace Information ............................................ 49 - 4.5 Additional Implementation Issues ............................. 53 - 4.5.1 Minimum Implementation ..................................... 53 - 4.5.2 Transparency ............................................... 53 - 4.5.3 Sizes and Timeouts ......................................... 54 - - - -Klensin Standards Track [Page 3] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - 4.5.3.1 Size limits and minimums ................................. 54 - 4.5.3.2 Timeouts ................................................. 56 - 4.5.4 Retry Strategies ........................................... 57 - 4.5.4.1 Sending Strategy ......................................... 58 - 4.5.4.2 Receiving Strategy ....................................... 59 - 4.5.5 Messages with a null reverse-path .......................... 59 - 5. Address Resolution and Mail Handling .......................... 60 - 6. Problem Detection and Handling ................................ 62 - 6.1 Reliable Delivery and Replies by Email ....................... 62 - 6.2 Loop Detection ............................................... 63 - 6.3 Compensating for Irregularities .............................. 63 - 7. Security Considerations ....................................... 64 - 7.1 Mail Security and Spoofing ................................... 64 - 7.2 "Blind" Copies ............................................... 65 - 7.3 VRFY, EXPN, and Security ..................................... 65 - 7.4 Information Disclosure in Announcements ...................... 66 - 7.5 Information Disclosure in Trace Fields ....................... 66 - 7.6 Information Disclosure in Message Forwarding ................. 67 - 7.7 Scope of Operation of SMTP Servers ........................... 67 - 8. IANA Considerations ........................................... 67 - 9. References .................................................... 68 - 10. Editor's Address ............................................. 70 - 11. Acknowledgments .............................................. 70 - Appendices ....................................................... 71 - A. TCP Transport Service ......................................... 71 - B. Generating SMTP Commands from RFC 822 Headers ................. 71 - C. Source Routes ................................................. 72 - D. Scenarios ..................................................... 73 - E. Other Gateway Issues .......................................... 76 - F. Deprecated Features of RFC 821 ................................ 76 - Full Copyright Statement ......................................... 79 - -1. Introduction - - The objective of the Simple Mail Transfer Protocol (SMTP) is to - transfer mail reliably and efficiently. - - SMTP is independent of the particular transmission subsystem and - requires only a reliable ordered data stream channel. While this - document specifically discusses transport over TCP, other transports - are possible. Appendices to RFC 821 describe some of them. - - An important feature of SMTP is its capability to transport mail - across networks, usually referred to as "SMTP mail relaying" (see - section 3.8). A network consists of the mutually-TCP-accessible - hosts on the public Internet, the mutually-TCP-accessible hosts on a - firewall-isolated TCP/IP Intranet, or hosts in some other LAN or WAN - environment utilizing a non-TCP transport-level protocol. Using - - - -Klensin Standards Track [Page 4] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - SMTP, a process can transfer mail to another process on the same - network or to some other network via a relay or gateway process - accessible to both networks. - - In this way, a mail message may pass through a number of intermediate - relay or gateway hosts on its path from sender to ultimate recipient. - The Mail eXchanger mechanisms of the domain name system [22, 27] (and - section 5 of this document) are used to identify the appropriate - next-hop destination for a message being transported. - -2. The SMTP Model - -2.1 Basic Structure - - The SMTP design can be pictured as: - - +----------+ +----------+ - +------+ | | | | - | User |<-->| | SMTP | | - +------+ | Client- |Commands/Replies| Server- | - +------+ | SMTP |<-------------->| SMTP | +------+ - | File |<-->| | and Mail | |<-->| File | - |System| | | | | |System| - +------+ +----------+ +----------+ +------+ - SMTP client SMTP server - - When an SMTP client has a message to transmit, it establishes a two- - way transmission channel to an SMTP server. The responsibility of an - SMTP client is to transfer mail messages to one or more SMTP servers, - or report its failure to do so. - - The means by which a mail message is presented to an SMTP client, and - how that client determines the domain name(s) to which mail messages - are to be transferred is a local matter, and is not addressed by this - document. In some cases, the domain name(s) transferred to, or - determined by, an SMTP client will identify the final destination(s) - of the mail message. In other cases, common with SMTP clients - associated with implementations of the POP [3, 26] or IMAP [6] - protocols, or when the SMTP client is inside an isolated transport - service environment, the domain name determined will identify an - intermediate destination through which all mail messages are to be - relayed. SMTP clients that transfer all traffic, regardless of the - target domain names associated with the individual messages, or that - do not maintain queues for retrying message transmissions that - initially cannot be completed, may otherwise conform to this - specification but are not considered fully-capable. Fully-capable - SMTP implementations, including the relays used by these less capable - - - - -Klensin Standards Track [Page 5] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - ones, and their destinations, are expected to support all of the - queuing, retrying, and alternate address functions discussed in this - specification. - - The means by which an SMTP client, once it has determined a target - domain name, determines the identity of an SMTP server to which a - copy of a message is to be transferred, and then performs that - transfer, is covered by this document. To effect a mail transfer to - an SMTP server, an SMTP client establishes a two-way transmission - channel to that SMTP server. An SMTP client determines the address - of an appropriate host running an SMTP server by resolving a - destination domain name to either an intermediate Mail eXchanger host - or a final target host. - - An SMTP server may be either the ultimate destination or an - intermediate "relay" (that is, it may assume the role of an SMTP - client after receiving the message) or "gateway" (that is, it may - transport the message further using some protocol other than SMTP). - SMTP commands are generated by the SMTP client and sent to the SMTP - server. SMTP replies are sent from the SMTP server to the SMTP - client in response to the commands. - - In other words, message transfer can occur in a single connection - between the original SMTP-sender and the final SMTP-recipient, or can - occur in a series of hops through intermediary systems. In either - case, a formal handoff of responsibility for the message occurs: the - protocol requires that a server accept responsibility for either - delivering a message or properly reporting the failure to do so. - - Once the transmission channel is established and initial handshaking - completed, the SMTP client normally initiates a mail transaction. - Such a transaction consists of a series of commands to specify the - originator and destination of the mail and transmission of the - message content (including any headers or other structure) itself. - When the same message is sent to multiple recipients, this protocol - encourages the transmission of only one copy of the data for all - recipients at the same destination (or intermediate relay) host. - - The server responds to each command with a reply; replies may - indicate that the command was accepted, that additional commands are - expected, or that a temporary or permanent error condition exists. - Commands specifying the sender or recipients may include server- - permitted SMTP service extension requests as discussed in section - 2.2. The dialog is purposely lock-step, one-at-a-time, although this - can be modified by mutually-agreed extension requests such as command - pipelining [13]. - - - - - -Klensin Standards Track [Page 6] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - Once a given mail message has been transmitted, the client may either - request that the connection be shut down or may initiate other mail - transactions. In addition, an SMTP client may use a connection to an - SMTP server for ancillary services such as verification of email - addresses or retrieval of mailing list subscriber addresses. - - As suggested above, this protocol provides mechanisms for the - transmission of mail. This transmission normally occurs directly - from the sending user's host to the receiving user's host when the - two hosts are connected to the same transport service. When they are - not connected to the same transport service, transmission occurs via - one or more relay SMTP servers. An intermediate host that acts as - either an SMTP relay or as a gateway into some other transmission - environment is usually selected through the use of the domain name - service (DNS) Mail eXchanger mechanism. - - Usually, intermediate hosts are determined via the DNS MX record, not - by explicit "source" routing (see section 5 and appendices C and - F.2). - -2.2 The Extension Model - -2.2.1 Background - - In an effort that started in 1990, approximately a decade after RFC - 821 was completed, the protocol was modified with a "service - extensions" model that permits the client and server to agree to - utilize shared functionality beyond the original SMTP requirements. - The SMTP extension mechanism defines a means whereby an extended SMTP - client and server may recognize each other, and the server can inform - the client as to the service extensions that it supports. - - Contemporary SMTP implementations MUST support the basic extension - mechanisms. For instance, servers MUST support the EHLO command even - if they do not implement any specific extensions and clients SHOULD - preferentially utilize EHLO rather than HELO. (However, for - compatibility with older conforming implementations, SMTP clients and - servers MUST support the original HELO mechanisms as a fallback.) - Unless the different characteristics of HELO must be identified for - interoperability purposes, this document discusses only EHLO. - - SMTP is widely deployed and high-quality implementations have proven - to be very robust. However, the Internet community now considers - some services to be important that were not anticipated when the - protocol was first designed. If support for those services is to be - added, it must be done in a way that permits older implementations to - continue working acceptably. The extension framework consists of: - - - - -Klensin Standards Track [Page 7] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - - The SMTP command EHLO, superseding the earlier HELO, - - - a registry of SMTP service extensions, - - - additional parameters to the SMTP MAIL and RCPT commands, and - - - optional replacements for commands defined in this protocol, such - as for DATA in non-ASCII transmissions [33]. - - SMTP's strength comes primarily from its simplicity. Experience with - many protocols has shown that protocols with few options tend towards - ubiquity, whereas protocols with many options tend towards obscurity. - - Each and every extension, regardless of its benefits, must be - carefully scrutinized with respect to its implementation, deployment, - and interoperability costs. In many cases, the cost of extending the - SMTP service will likely outweigh the benefit. - -2.2.2 Definition and Registration of Extensions - - The IANA maintains a registry of SMTP service extensions. A - corresponding EHLO keyword value is associated with each extension. - Each service extension registered with the IANA must be defined in a - formal standards-track or IESG-approved experimental protocol - document. The definition must include: - - - the textual name of the SMTP service extension; - - - the EHLO keyword value associated with the extension; - - - the syntax and possible values of parameters associated with the - EHLO keyword value; - - - any additional SMTP verbs associated with the extension - (additional verbs will usually be, but are not required to be, the - same as the EHLO keyword value); - - - any new parameters the extension associates with the MAIL or RCPT - verbs; - - - a description of how support for the extension affects the - behavior of a server and client SMTP; and, - - - the increment by which the extension is increasing the maximum - length of the commands MAIL and/or RCPT, over that specified in - this standard. - - - - - -Klensin Standards Track [Page 8] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - In addition, any EHLO keyword value starting with an upper or lower - case "X" refers to a local SMTP service extension used exclusively - through bilateral agreement. Keywords beginning with "X" MUST NOT be - used in a registered service extension. Conversely, keyword values - presented in the EHLO response that do not begin with "X" MUST - correspond to a standard, standards-track, or IESG-approved - experimental SMTP service extension registered with IANA. A - conforming server MUST NOT offer non-"X"-prefixed keyword values that - are not described in a registered extension. - - Additional verbs and parameter names are bound by the same rules as - EHLO keywords; specifically, verbs beginning with "X" are local - extensions that may not be registered or standardized. Conversely, - verbs not beginning with "X" must always be registered. - -2.3 Terminology - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - document are to be interpreted as described below. - - 1. MUST This word, or the terms "REQUIRED" or "SHALL", mean that - the definition is an absolute requirement of the specification. - - 2. MUST NOT This phrase, or the phrase "SHALL NOT", mean that the - definition is an absolute prohibition of the specification. - - 3. SHOULD This word, or the adjective "RECOMMENDED", mean that - there may exist valid reasons in particular circumstances to - ignore a particular item, but the full implications must be - understood and carefully weighed before choosing a different - course. - - 4. SHOULD NOT This phrase, or the phrase "NOT RECOMMENDED" mean - that there may exist valid reasons in particular circumstances - when the particular behavior is acceptable or even useful, but the - full implications should be understood and the case carefully - weighed before implementing any behavior described with this - label. - - 5. MAY This word, or the adjective "OPTIONAL", mean that an item is - truly optional. One vendor may choose to include the item because - a particular marketplace requires it or because the vendor feels - that it enhances the product while another vendor may omit the - same item. An implementation which does not include a particular - option MUST be prepared to interoperate with another - implementation which does include the option, though perhaps with - reduced functionality. In the same vein an implementation which - - - -Klensin Standards Track [Page 9] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - does include a particular option MUST be prepared to interoperate - with another implementation which does not include the option - (except, of course, for the feature the option provides.) - -2.3.1 Mail Objects - - SMTP transports a mail object. A mail object contains an envelope - and content. - - The SMTP envelope is sent as a series of SMTP protocol units - (described in section 3). It consists of an originator address (to - which error reports should be directed); one or more recipient - addresses; and optional protocol extension material. Historically, - variations on the recipient address specification command (RCPT TO) - could be used to specify alternate delivery modes, such as immediate - display; those variations have now been deprecated (see appendix F, - section F.6). - - The SMTP content is sent in the SMTP DATA protocol unit and has two - parts: the headers and the body. If the content conforms to other - contemporary standards, the headers form a collection of field/value - pairs structured as in the message format specification [32]; the - body, if structured, is defined according to MIME [12]. The content - is textual in nature, expressed using the US-ASCII repertoire [1]. - Although SMTP extensions (such as "8BITMIME" [20]) may relax this - restriction for the content body, the content headers are always - encoded using the US-ASCII repertoire. A MIME extension [23] defines - an algorithm for representing header values outside the US-ASCII - repertoire, while still encoding them using the US-ASCII repertoire. - -2.3.2 Senders and Receivers - - In RFC 821, the two hosts participating in an SMTP transaction were - described as the "SMTP-sender" and "SMTP-receiver". This document - has been changed to reflect current industry terminology and hence - refers to them as the "SMTP client" (or sometimes just "the client") - and "SMTP server" (or just "the server"), respectively. Since a - given host may act both as server and client in a relay situation, - "receiver" and "sender" terminology is still used where needed for - clarity. - -2.3.3 Mail Agents and Message Stores - - Additional mail system terminology became common after RFC 821 was - published and, where convenient, is used in this specification. In - particular, SMTP servers and clients provide a mail transport service - and therefore act as "Mail Transfer Agents" (MTAs). "Mail User - Agents" (MUAs or UAs) are normally thought of as the sources and - - - -Klensin Standards Track [Page 10] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - targets of mail. At the source, an MUA might collect mail to be - transmitted from a user and hand it off to an MTA; the final - ("delivery") MTA would be thought of as handing the mail off to an - MUA (or at least transferring responsibility to it, e.g., by - depositing the message in a "message store"). However, while these - terms are used with at least the appearance of great precision in - other environments, the implied boundaries between MUAs and MTAs - often do not accurately match common, and conforming, practices with - Internet mail. Hence, the reader should be cautious about inferring - the strong relationships and responsibilities that might be implied - if these terms were used elsewhere. - -2.3.4 Host - - For the purposes of this specification, a host is a computer system - attached to the Internet (or, in some cases, to a private TCP/IP - network) and supporting the SMTP protocol. Hosts are known by names - (see "domain"); identifying them by numerical address is discouraged. - -2.3.5 Domain - - A domain (or domain name) consists of one or more dot-separated - components. These components ("labels" in DNS terminology [22]) are - restricted for SMTP purposes to consist of a sequence of letters, - digits, and hyphens drawn from the ASCII character set [1]. Domain - names are used as names of hosts and of other entities in the domain - name hierarchy. For example, a domain may refer to an alias (label - of a CNAME RR) or the label of Mail eXchanger records to be used to - deliver mail instead of representing a host name. See [22] and - section 5 of this specification. - - The domain name, as described in this document and in [22], is the - entire, fully-qualified name (often referred to as an "FQDN"). A - domain name that is not in FQDN form is no more than a local alias. - Local aliases MUST NOT appear in any SMTP transaction. - -2.3.6 Buffer and State Table - - SMTP sessions are stateful, with both parties carefully maintaining a - common view of the current state. In this document we model this - state by a virtual "buffer" and a "state table" on the server which - may be used by the client to, for example, "clear the buffer" or - "reset the state table," causing the information in the buffer to be - discarded and the state to be returned to some previous state. - - - - - - - -Klensin Standards Track [Page 11] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - -2.3.7 Lines - - SMTP commands and, unless altered by a service extension, message - data, are transmitted in "lines". Lines consist of zero or more data - characters terminated by the sequence ASCII character "CR" (hex value - 0D) followed immediately by ASCII character "LF" (hex value 0A). - This termination sequence is denoted as in this document. - Conforming implementations MUST NOT recognize or generate any other - character or character sequence as a line terminator. Limits MAY be - imposed on line lengths by servers (see section 4.5.3). - - In addition, the appearance of "bare" "CR" or "LF" characters in text - (i.e., either without the other) has a long history of causing - problems in mail implementations and applications that use the mail - system as a tool. SMTP client implementations MUST NOT transmit - these characters except when they are intended as line terminators - and then MUST, as indicated above, transmit them only as a - sequence. - -2.3.8 Originator, Delivery, Relay, and Gateway Systems - - This specification makes a distinction among four types of SMTP - systems, based on the role those systems play in transmitting - electronic mail. An "originating" system (sometimes called an SMTP - originator) introduces mail into the Internet or, more generally, - into a transport service environment. A "delivery" SMTP system is - one that receives mail from a transport service environment and - passes it to a mail user agent or deposits it in a message store - which a mail user agent is expected to subsequently access. A - "relay" SMTP system (usually referred to just as a "relay") receives - mail from an SMTP client and transmits it, without modification to - the message data other than adding trace information, to another SMTP - server for further relaying or for delivery. - - A "gateway" SMTP system (usually referred to just as a "gateway") - receives mail from a client system in one transport environment and - transmits it to a server system in another transport environment. - Differences in protocols or message semantics between the transport - environments on either side of a gateway may require that the gateway - system perform transformations to the message that are not permitted - to SMTP relay systems. For the purposes of this specification, - firewalls that rewrite addresses should be considered as gateways, - even if SMTP is used on both sides of them (see [11]). - - - - - - - - -Klensin Standards Track [Page 12] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - -2.3.9 Message Content and Mail Data - - The terms "message content" and "mail data" are used interchangeably - in this document to describe the material transmitted after the DATA - command is accepted and before the end of data indication is - transmitted. Message content includes message headers and the - possibly-structured message body. The MIME specification [12] - provides the standard mechanisms for structured message bodies. - -2.3.10 Mailbox and Address - - As used in this specification, an "address" is a character string - that identifies a user to whom mail will be sent or a location into - which mail will be deposited. The term "mailbox" refers to that - depository. The two terms are typically used interchangeably unless - the distinction between the location in which mail is placed (the - mailbox) and a reference to it (the address) is important. An - address normally consists of user and domain specifications. The - standard mailbox naming convention is defined to be "local- - part@domain": contemporary usage permits a much broader set of - applications than simple "user names". Consequently, and due to a - long history of problems when intermediate hosts have attempted to - optimize transport by modifying them, the local-part MUST be - interpreted and assigned semantics only by the host specified in the - domain part of the address. - -2.3.11 Reply - - An SMTP reply is an acknowledgment (positive or negative) sent from - receiver to sender via the transmission channel in response to a - command. The general form of a reply is a numeric completion code - (indicating failure or success) usually followed by a text string. - The codes are for use by programs and the text is usually intended - for human users. Recent work [34] has specified further structuring - of the reply strings, including the use of supplemental and more - specific completion codes. - -2.4 General Syntax Principles and Transaction Model - - SMTP commands and replies have a rigid syntax. All commands begin - with a command verb. All Replies begin with a three digit numeric - code. In some commands and replies, arguments MUST follow the verb - or reply code. Some commands do not accept arguments (after the - verb), and some reply codes are followed, sometimes optionally, by - free form text. In both cases, where text appears, it is separated - from the verb or reply code by a space character. Complete - definitions of commands and replies appear in section 4. - - - - -Klensin Standards Track [Page 13] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - Verbs and argument values (e.g., "TO:" or "to:" in the RCPT command - and extension name keywords) are not case sensitive, with the sole - exception in this specification of a mailbox local-part (SMTP - Extensions may explicitly specify case-sensitive elements). That is, - a command verb, an argument value other than a mailbox local-part, - and free form text MAY be encoded in upper case, lower case, or any - mixture of upper and lower case with no impact on its meaning. This - is NOT true of a mailbox local-part. The local-part of a mailbox - MUST BE treated as case sensitive. Therefore, SMTP implementations - MUST take care to preserve the case of mailbox local-parts. Mailbox - domains are not case sensitive. In particular, for some hosts the - user "smith" is different from the user "Smith". However, exploiting - the case sensitivity of mailbox local-parts impedes interoperability - and is discouraged. - - A few SMTP servers, in violation of this specification (and RFC 821) - require that command verbs be encoded by clients in upper case. - Implementations MAY wish to employ this encoding to accommodate those - servers. - - The argument field consists of a variable length character string - ending with the end of the line, i.e., with the character sequence - . The receiver will take no action until this sequence is - received. - - The syntax for each command is shown with the discussion of that - command. Common elements and parameters are shown in section 4.1.2. - - Commands and replies are composed of characters from the ASCII - character set [1]. When the transport service provides an 8-bit byte - (octet) transmission channel, each 7-bit character is transmitted - right justified in an octet with the high order bit cleared to zero. - More specifically, the unextended SMTP service provides seven bit - transport only. An originating SMTP client which has not - successfully negotiated an appropriate extension with a particular - server MUST NOT transmit messages with information in the high-order - bit of octets. If such messages are transmitted in violation of this - rule, receiving SMTP servers MAY clear the high-order bit or reject - the message as invalid. In general, a relay SMTP SHOULD assume that - the message content it has received is valid and, assuming that the - envelope permits doing so, relay it without inspecting that content. - Of course, if the content is mislabeled and the data path cannot - accept the actual content, this may result in ultimate delivery of a - severely garbled message to the recipient. Delivery SMTP systems MAY - reject ("bounce") such messages rather than deliver them. No sending - SMTP system is permitted to send envelope commands in any character - - - - - -Klensin Standards Track [Page 14] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - set other than US-ASCII; receiving systems SHOULD reject such - commands, normally using "500 syntax error - invalid character" - replies. - - Eight-bit message content transmission MAY be requested of the server - by a client using extended SMTP facilities, notably the "8BITMIME" - extension [20]. 8BITMIME SHOULD be supported by SMTP servers. - However, it MUST not be construed as authorization to transmit - unrestricted eight bit material. 8BITMIME MUST NOT be requested by - senders for material with the high bit on that is not in MIME format - with an appropriate content-transfer encoding; servers MAY reject - such messages. - - The metalinguistic notation used in this document corresponds to the - "Augmented BNF" used in other Internet mail system documents. The - reader who is not familiar with that syntax should consult the ABNF - specification [8]. Metalanguage terms used in running text are - surrounded by pointed brackets (e.g., ) for clarity. - -3. The SMTP Procedures: An Overview - - This section contains descriptions of the procedures used in SMTP: - session initiation, the mail transaction, forwarding mail, verifying - mailbox names and expanding mailing lists, and the opening and - closing exchanges. Comments on relaying, a note on mail domains, and - a discussion of changing roles are included at the end of this - section. Several complete scenarios are presented in appendix D. - -3.1 Session Initiation - - An SMTP session is initiated when a client opens a connection to a - server and the server responds with an opening message. - - SMTP server implementations MAY include identification of their - software and version information in the connection greeting reply - after the 220 code, a practice that permits more efficient isolation - and repair of any problems. Implementations MAY make provision for - SMTP servers to disable the software and version announcement where - it causes security concerns. While some systems also identify their - contact point for mail problems, this is not a substitute for - maintaining the required "postmaster" address (see section 4.5.1). - - The SMTP protocol allows a server to formally reject a transaction - while still allowing the initial connection as follows: a 554 - response MAY be given in the initial connection opening message - instead of the 220. A server taking this approach MUST still wait - for the client to send a QUIT (see section 4.1.1.10) before closing - the connection and SHOULD respond to any intervening commands with - - - -Klensin Standards Track [Page 15] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - "503 bad sequence of commands". Since an attempt to make an SMTP - connection to such a system is probably in error, a server returning - a 554 response on connection opening SHOULD provide enough - information in the reply text to facilitate debugging of the sending - system. - -3.2 Client Initiation - - Once the server has sent the welcoming message and the client has - received it, the client normally sends the EHLO command to the - server, indicating the client's identity. In addition to opening the - session, use of EHLO indicates that the client is able to process - service extensions and requests that the server provide a list of the - extensions it supports. Older SMTP systems which are unable to - support service extensions and contemporary clients which do not - require service extensions in the mail session being initiated, MAY - use HELO instead of EHLO. Servers MUST NOT return the extended - EHLO-style response to a HELO command. For a particular connection - attempt, if the server returns a "command not recognized" response to - EHLO, the client SHOULD be able to fall back and send HELO. - - In the EHLO command the host sending the command identifies itself; - the command may be interpreted as saying "Hello, I am " (and, - in the case of EHLO, "and I support service extension requests"). - -3.3 Mail Transactions - - There are three steps to SMTP mail transactions. The transaction - starts with a MAIL command which gives the sender identification. - (In general, the MAIL command may be sent only when no mail - transaction is in progress; see section 4.1.4.) A series of one or - more RCPT commands follows giving the receiver information. Then a - DATA command initiates transfer of the mail data and is terminated by - the "end of mail" data indicator, which also confirms the - transaction. - - The first step in the procedure is the MAIL command. - - MAIL FROM: [SP ] - - This command tells the SMTP-receiver that a new mail transaction is - starting and to reset all its state tables and buffers, including any - recipients or mail data. The portion of the first or - only argument contains the source mailbox (between "<" and ">" - brackets), which can be used to report errors (see section 4.2 for a - discussion of error reporting). If accepted, the SMTP server returns - a 250 OK reply. If the mailbox specification is not acceptable for - some reason, the server MUST return a reply indicating whether the - - - -Klensin Standards Track [Page 16] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - failure is permanent (i.e., will occur again if the client tries to - send the same address again) or temporary (i.e., the address might be - accepted if the client tries again later). Despite the apparent - scope of this requirement, there are circumstances in which the - acceptability of the reverse-path may not be determined until one or - more forward-paths (in RCPT commands) can be examined. In those - cases, the server MAY reasonably accept the reverse-path (with a 250 - reply) and then report problems after the forward-paths are received - and examined. Normally, failures produce 550 or 553 replies. - - Historically, the can contain more than just a - mailbox, however, contemporary systems SHOULD NOT use source routing - (see appendix C). - - The optional are associated with negotiated SMTP - service extensions (see section 2.2). - - The second step in the procedure is the RCPT command. - - RCPT TO: [ SP ] - - The first or only argument to this command includes a forward-path - (normally a mailbox and domain, always surrounded by "<" and ">" - brackets) identifying one recipient. If accepted, the SMTP server - returns a 250 OK reply and stores the forward-path. If the recipient - is known not to be a deliverable address, the SMTP server returns a - 550 reply, typically with a string such as "no such user - " and the - mailbox name (other circumstances and reply codes are possible). - This step of the procedure can be repeated any number of times. - - The can contain more than just a mailbox. - Historically, the can be a source routing list of - hosts and the destination mailbox, however, contemporary SMTP clients - SHOULD NOT utilize source routes (see appendix C). Servers MUST be - prepared to encounter a list of source routes in the forward path, - but SHOULD ignore the routes or MAY decline to support the relaying - they imply. Similarly, servers MAY decline to accept mail that is - destined for other hosts or systems. These restrictions make a - server useless as a relay for clients that do not support full SMTP - functionality. Consequently, restricted-capability clients MUST NOT - assume that any SMTP server on the Internet can be used as their mail - processing (relaying) site. If a RCPT command appears without a - previous MAIL command, the server MUST return a 503 "Bad sequence of - commands" response. The optional are associated - with negotiated SMTP service extensions (see section 2.2). - - The third step in the procedure is the DATA command (or some - alternative specified in a service extension). - - - -Klensin Standards Track [Page 17] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - DATA - - If accepted, the SMTP server returns a 354 Intermediate reply and - considers all succeeding lines up to but not including the end of - mail data indicator to be the message text. When the end of text is - successfully received and stored the SMTP-receiver sends a 250 OK - reply. - - Since the mail data is sent on the transmission channel, the end of - mail data must be indicated so that the command and reply dialog can - be resumed. SMTP indicates the end of the mail data by sending a - line containing only a "." (period or full stop). A transparency - procedure is used to prevent this from interfering with the user's - text (see section 4.5.2). - - The end of mail data indicator also confirms the mail transaction and - tells the SMTP server to now process the stored recipients and mail - data. If accepted, the SMTP server returns a 250 OK reply. The DATA - command can fail at only two points in the protocol exchange: - - - If there was no MAIL, or no RCPT, command, or all such commands - were rejected, the server MAY return a "command out of sequence" - (503) or "no valid recipients" (554) reply in response to the DATA - command. If one of those replies (or any other 5yz reply) is - received, the client MUST NOT send the message data; more - generally, message data MUST NOT be sent unless a 354 reply is - received. - - - If the verb is initially accepted and the 354 reply issued, the - DATA command should fail only if the mail transaction was - incomplete (for example, no recipients), or if resources were - unavailable (including, of course, the server unexpectedly - becoming unavailable), or if the server determines that the - message should be rejected for policy or other reasons. - - However, in practice, some servers do not perform recipient - verification until after the message text is received. These servers - SHOULD treat a failure for one or more recipients as a "subsequent - failure" and return a mail message as discussed in section 6. Using - a "550 mailbox not found" (or equivalent) reply code after the data - are accepted makes it difficult or impossible for the client to - determine which recipients failed. - - When RFC 822 format [7, 32] is being used, the mail data include the - memo header items such as Date, Subject, To, Cc, From. Server SMTP - systems SHOULD NOT reject messages based on perceived defects in the - RFC 822 or MIME [12] message header or message body. In particular, - - - - -Klensin Standards Track [Page 18] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - they MUST NOT reject messages in which the numbers of Resent-fields - do not match or Resent-to appears without Resent-from and/or Resent- - date. - - Mail transaction commands MUST be used in the order discussed above. - -3.4 Forwarding for Address Correction or Updating - - Forwarding support is most often required to consolidate and simplify - addresses within, or relative to, some enterprise and less frequently - to establish addresses to link a person's prior address with current - one. Silent forwarding of messages (without server notification to - the sender), for security or non-disclosure purposes, is common in - the contemporary Internet. - - In both the enterprise and the "new address" cases, information - hiding (and sometimes security) considerations argue against exposure - of the "final" address through the SMTP protocol as a side-effect of - the forwarding activity. This may be especially important when the - final address may not even be reachable by the sender. Consequently, - the "forwarding" mechanisms described in section 3.2 of RFC 821, and - especially the 251 (corrected destination) and 551 reply codes from - RCPT must be evaluated carefully by implementers and, when they are - available, by those configuring systems. - - In particular: - - * Servers MAY forward messages when they are aware of an address - change. When they do so, they MAY either provide address-updating - information with a 251 code, or may forward "silently" and return - a 250 code. But, if a 251 code is used, they MUST NOT assume that - the client will actually update address information or even return - that information to the user. - - Alternately, - - * Servers MAY reject or bounce messages when they are not - deliverable when addressed. When they do so, they MAY either - provide address-updating information with a 551 code, or may - reject the message as undeliverable with a 550 code and no - address-specific information. But, if a 551 code is used, they - MUST NOT assume that the client will actually update address - information or even return that information to the user. - - SMTP server implementations that support the 251 and/or 551 reply - codes are strongly encouraged to provide configuration mechanisms so - that sites which conclude that they would undesirably disclose - information can disable or restrict their use. - - - -Klensin Standards Track [Page 19] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - -3.5 Commands for Debugging Addresses - -3.5.1 Overview - - SMTP provides commands to verify a user name or obtain the content of - a mailing list. This is done with the VRFY and EXPN commands, which - have character string arguments. Implementations SHOULD support VRFY - and EXPN (however, see section 3.5.2 and 7.3). - - For the VRFY command, the string is a user name or a user name and - domain (see below). If a normal (i.e., 250) response is returned, - the response MAY include the full name of the user and MUST include - the mailbox of the user. It MUST be in either of the following - forms: - - User Name - local-part@domain - - When a name that is the argument to VRFY could identify more than one - mailbox, the server MAY either note the ambiguity or identify the - alternatives. In other words, any of the following are legitimate - response to VRFY: - - 553 User ambiguous - - or - - 553- Ambiguous; Possibilities are - 553-Joe Smith - 553-Harry Smith - 553 Melvin Smith - - or - - 553-Ambiguous; Possibilities - 553- - 553- - 553 - - Under normal circumstances, a client receiving a 553 reply would be - expected to expose the result to the user. Use of exactly the forms - given, and the "user ambiguous" or "ambiguous" keywords, possibly - supplemented by extended reply codes such as those described in [34], - will facilitate automated translation into other languages as needed. - Of course, a client that was highly automated or that was operating - in another language than English, might choose to try to translate - the response, to return some other indication to the user than the - - - - -Klensin Standards Track [Page 20] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - literal text of the reply, or to take some automated action such as - consulting a directory service for additional information before - reporting to the user. - - For the EXPN command, the string identifies a mailing list, and the - successful (i.e., 250) multiline response MAY include the full name - of the users and MUST give the mailboxes on the mailing list. - - In some hosts the distinction between a mailing list and an alias for - a single mailbox is a bit fuzzy, since a common data structure may - hold both types of entries, and it is possible to have mailing lists - containing only one mailbox. If a request is made to apply VRFY to a - mailing list, a positive response MAY be given if a message so - addressed would be delivered to everyone on the list, otherwise an - error SHOULD be reported (e.g., "550 That is a mailing list, not a - user" or "252 Unable to verify members of mailing list"). If a - request is made to expand a user name, the server MAY return a - positive response consisting of a list containing one name, or an - error MAY be reported (e.g., "550 That is a user name, not a mailing - list"). - - In the case of a successful multiline reply (normal for EXPN) exactly - one mailbox is to be specified on each line of the reply. The case - of an ambiguous request is discussed above. - - "User name" is a fuzzy term and has been used deliberately. An - implementation of the VRFY or EXPN commands MUST include at least - recognition of local mailboxes as "user names". However, since - current Internet practice often results in a single host handling - mail for multiple domains, hosts, especially hosts that provide this - functionality, SHOULD accept the "local-part@domain" form as a "user - name"; hosts MAY also choose to recognize other strings as "user - names". - - The case of expanding a mailbox list requires a multiline reply, such - as: - - C: EXPN Example-People - S: 250-Jon Postel - S: 250-Fred Fonebone - S: 250 Sam Q. Smith - - or - - C: EXPN Executive-Washroom-List - S: 550 Access Denied to You. - - - - - -Klensin Standards Track [Page 21] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - The character string arguments of the VRFY and EXPN commands cannot - be further restricted due to the variety of implementations of the - user name and mailbox list concepts. On some systems it may be - appropriate for the argument of the EXPN command to be a file name - for a file containing a mailing list, but again there are a variety - of file naming conventions in the Internet. Similarly, historical - variations in what is returned by these commands are such that the - response SHOULD be interpreted very carefully, if at all, and SHOULD - generally only be used for diagnostic purposes. - -3.5.2 VRFY Normal Response - - When normal (2yz or 551) responses are returned from a VRFY or EXPN - request, the reply normally includes the mailbox name, i.e., - "", where "domain" is a fully qualified domain - name, MUST appear in the syntax. In circumstances exceptional enough - to justify violating the intent of this specification, free-form text - MAY be returned. In order to facilitate parsing by both computers - and people, addresses SHOULD appear in pointed brackets. When - addresses, rather than free-form debugging information, are returned, - EXPN and VRFY MUST return only valid domain addresses that are usable - in SMTP RCPT commands. Consequently, if an address implies delivery - to a program or other system, the mailbox name used to reach that - target MUST be given. Paths (explicit source routes) MUST NOT be - returned by VRFY or EXPN. - - Server implementations SHOULD support both VRFY and EXPN. For - security reasons, implementations MAY provide local installations a - way to disable either or both of these commands through configuration - options or the equivalent. When these commands are supported, they - are not required to work across relays when relaying is supported. - Since they were both optional in RFC 821, they MUST be listed as - service extensions in an EHLO response, if they are supported. - -3.5.3 Meaning of VRFY or EXPN Success Response - - A server MUST NOT return a 250 code in response to a VRFY or EXPN - command unless it has actually verified the address. In particular, - a server MUST NOT return 250 if all it has done is to verify that the - syntax given is valid. In that case, 502 (Command not implemented) - or 500 (Syntax error, command unrecognized) SHOULD be returned. As - stated elsewhere, implementation (in the sense of actually validating - addresses and returning information) of VRFY and EXPN are strongly - recommended. Hence, implementations that return 500 or 502 for VRFY - are not in full compliance with this specification. - - - - - - -Klensin Standards Track [Page 22] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - There may be circumstances where an address appears to be valid but - cannot reasonably be verified in real time, particularly when a - server is acting as a mail exchanger for another server or domain. - "Apparent validity" in this case would normally involve at least - syntax checking and might involve verification that any domains - specified were ones to which the host expected to be able to relay - mail. In these situations, reply code 252 SHOULD be returned. These - cases parallel the discussion of RCPT verification discussed in - section 2.1. Similarly, the discussion in section 3.4 applies to the - use of reply codes 251 and 551 with VRFY (and EXPN) to indicate - addresses that are recognized but that would be forwarded or bounced - were mail received for them. Implementations generally SHOULD be - more aggressive about address verification in the case of VRFY than - in the case of RCPT, even if it takes a little longer to do so. - -3.5.4 Semantics and Applications of EXPN - - EXPN is often very useful in debugging and understanding problems - with mailing lists and multiple-target-address aliases. Some systems - have attempted to use source expansion of mailing lists as a means of - eliminating duplicates. The propagation of aliasing systems with - mail on the Internet, for hosts (typically with MX and CNAME DNS - records), for mailboxes (various types of local host aliases), and in - various proxying arrangements, has made it nearly impossible for - these strategies to work consistently, and mail systems SHOULD NOT - attempt them. - -3.6 Domains - - Only resolvable, fully-qualified, domain names (FQDNs) are permitted - when domain names are used in SMTP. In other words, names that can - be resolved to MX RRs or A RRs (as discussed in section 5) are - permitted, as are CNAME RRs whose targets can be resolved, in turn, - to MX or A RRs. Local nicknames or unqualified names MUST NOT be - used. There are two exceptions to the rule requiring FQDNs: - - - The domain name given in the EHLO command MUST BE either a primary - host name (a domain name that resolves to an A RR) or, if the host - has no name, an address literal as described in section 4.1.1.1. - - - The reserved mailbox name "postmaster" may be used in a RCPT - command without domain qualification (see section 4.1.1.3) and - MUST be accepted if so used. - - - - - - - - -Klensin Standards Track [Page 23] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - -3.7 Relaying - - In general, the availability of Mail eXchanger records in the domain - name system [22, 27] makes the use of explicit source routes in the - Internet mail system unnecessary. Many historical problems with - their interpretation have made their use undesirable. SMTP clients - SHOULD NOT generate explicit source routes except under unusual - circumstances. SMTP servers MAY decline to act as mail relays or to - accept addresses that specify source routes. When route information - is encountered, SMTP servers are also permitted to ignore the route - information and simply send to the final destination specified as the - last element in the route and SHOULD do so. There has been an - invalid practice of using names that do not appear in the DNS as - destination names, with the senders counting on the intermediate - hosts specified in source routing to resolve any problems. If source - routes are stripped, this practice will cause failures. This is one - of several reasons why SMTP clients MUST NOT generate invalid source - routes or depend on serial resolution of names. - - When source routes are not used, the process described in RFC 821 for - constructing a reverse-path from the forward-path is not applicable - and the reverse-path at the time of delivery will simply be the - address that appeared in the MAIL command. - - A relay SMTP server is usually the target of a DNS MX record that - designates it, rather than the final delivery system. The relay - server may accept or reject the task of relaying the mail in the same - way it accepts or rejects mail for a local user. If it accepts the - task, it then becomes an SMTP client, establishes a transmission - channel to the next SMTP server specified in the DNS (according to - the rules in section 5), and sends it the mail. If it declines to - relay mail to a particular address for policy reasons, a 550 response - SHOULD be returned. - - Many mail-sending clients exist, especially in conjunction with - facilities that receive mail via POP3 or IMAP, that have limited - capability to support some of the requirements of this specification, - such as the ability to queue messages for subsequent delivery - attempts. For these clients, it is common practice to make private - arrangements to send all messages to a single server for processing - and subsequent distribution. SMTP, as specified here, is not ideally - suited for this role, and work is underway on standardized mail - submission protocols that might eventually supercede the current - practices. In any event, because these arrangements are private and - fall outside the scope of this specification, they are not described - here. - - - - - -Klensin Standards Track [Page 24] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - It is important to note that MX records can point to SMTP servers - which act as gateways into other environments, not just SMTP relays - and final delivery systems; see sections 3.8 and 5. - - If an SMTP server has accepted the task of relaying the mail and - later finds that the destination is incorrect or that the mail cannot - be delivered for some other reason, then it MUST construct an - "undeliverable mail" notification message and send it to the - originator of the undeliverable mail (as indicated by the reverse- - path). Formats specified for non-delivery reports by other standards - (see, for example, [24, 25]) SHOULD be used if possible. - - This notification message must be from the SMTP server at the relay - host or the host that first determines that delivery cannot be - accomplished. Of course, SMTP servers MUST NOT send notification - messages about problems transporting notification messages. One way - to prevent loops in error reporting is to specify a null reverse-path - in the MAIL command of a notification message. When such a message - is transmitted the reverse-path MUST be set to null (see section - 4.5.5 for additional discussion). A MAIL command with a null - reverse-path appears as follows: - - MAIL FROM:<> - - As discussed in section 2.4.1, a relay SMTP has no need to inspect or - act upon the headers or body of the message data and MUST NOT do so - except to add its own "Received:" header (section 4.4) and, - optionally, to attempt to detect looping in the mail system (see - section 6.2). - -3.8 Mail Gatewaying - - While the relay function discussed above operates within the Internet - SMTP transport service environment, MX records or various forms of - explicit routing may require that an intermediate SMTP server perform - a translation function between one transport service and another. As - discussed in section 2.3.8, when such a system is at the boundary - between two transport service environments, we refer to it as a - "gateway" or "gateway SMTP". - - Gatewaying mail between different mail environments, such as - different mail formats and protocols, is complex and does not easily - yield to standardization. However, some general requirements may be - given for a gateway between the Internet and another mail - environment. - - - - - - -Klensin Standards Track [Page 25] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - -3.8.1 Header Fields in Gatewaying - - Header fields MAY be rewritten when necessary as messages are - gatewayed across mail environment boundaries. This may involve - inspecting the message body or interpreting the local-part of the - destination address in spite of the prohibitions in section 2.4.1. - - Other mail systems gatewayed to the Internet often use a subset of - RFC 822 headers or provide similar functionality with a different - syntax, but some of these mail systems do not have an equivalent to - the SMTP envelope. Therefore, when a message leaves the Internet - environment, it may be necessary to fold the SMTP envelope - information into the message header. A possible solution would be to - create new header fields to carry the envelope information (e.g., - "X-SMTP-MAIL:" and "X-SMTP-RCPT:"); however, this would require - changes in mail programs in foreign environments and might risk - disclosure of private information (see section 7.2). - -3.8.2 Received Lines in Gatewaying - - When forwarding a message into or out of the Internet environment, a - gateway MUST prepend a Received: line, but it MUST NOT alter in any - way a Received: line that is already in the header. - - "Received:" fields of messages originating from other environments - may not conform exactly to this specification. However, the most - important use of Received: lines is for debugging mail faults, and - this debugging can be severely hampered by well-meaning gateways that - try to "fix" a Received: line. As another consequence of trace - fields arising in non-SMTP environments, receiving systems MUST NOT - reject mail based on the format of a trace field and SHOULD be - extremely robust in the light of unexpected information or formats in - those fields. - - The gateway SHOULD indicate the environment and protocol in the "via" - clauses of Received field(s) that it supplies. - -3.8.3 Addresses in Gatewaying - - From the Internet side, the gateway SHOULD accept all valid address - formats in SMTP commands and in RFC 822 headers, and all valid RFC - 822 messages. Addresses and headers generated by gateways MUST - conform to applicable Internet standards (including this one and RFC - 822). Gateways are, of course, subject to the same rules for - handling source routes as those described for other SMTP systems in - section 3.3. - - - - - -Klensin Standards Track [Page 26] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - -3.8.4 Other Header Fields in Gatewaying - - The gateway MUST ensure that all header fields of a message that it - forwards into the Internet mail environment meet the requirements for - Internet mail. In particular, all addresses in "From:", "To:", - "Cc:", etc., fields MUST be transformed (if necessary) to satisfy RFC - 822 syntax, MUST reference only fully-qualified domain names, and - MUST be effective and useful for sending replies. The translation - algorithm used to convert mail from the Internet protocols to another - environment's protocol SHOULD ensure that error messages from the - foreign mail environment are delivered to the return path from the - SMTP envelope, not to the sender listed in the "From:" field (or - other fields) of the RFC 822 message. - -3.8.5 Envelopes in Gatewaying - - Similarly, when forwarding a message from another environment into - the Internet, the gateway SHOULD set the envelope return path in - accordance with an error message return address, if supplied by the - foreign environment. If the foreign environment has no equivalent - concept, the gateway must select and use a best approximation, with - the message originator's address as the default of last resort. - -3.9 Terminating Sessions and Connections - - An SMTP connection is terminated when the client sends a QUIT - command. The server responds with a positive reply code, after which - it closes the connection. - - An SMTP server MUST NOT intentionally close the connection except: - - - After receiving a QUIT command and responding with a 221 reply. - - - After detecting the need to shut down the SMTP service and - returning a 421 response code. This response code can be issued - after the server receives any command or, if necessary, - asynchronously from command receipt (on the assumption that the - client will receive it after the next command is issued). - - In particular, a server that closes connections in response to - commands that are not understood is in violation of this - specification. Servers are expected to be tolerant of unknown - commands, issuing a 500 reply and awaiting further instructions from - the client. - - - - - - - -Klensin Standards Track [Page 27] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - An SMTP server which is forcibly shut down via external means SHOULD - attempt to send a line containing a 421 response code to the SMTP - client before exiting. The SMTP client will normally read the 421 - response code after sending its next command. - - SMTP clients that experience a connection close, reset, or other - communications failure due to circumstances not under their control - (in violation of the intent of this specification but sometimes - unavoidable) SHOULD, to maintain the robustness of the mail system, - treat the mail transaction as if a 451 response had been received and - act accordingly. - -3.10 Mailing Lists and Aliases - - An SMTP-capable host SHOULD support both the alias and the list - models of address expansion for multiple delivery. When a message is - delivered or forwarded to each address of an expanded list form, the - return address in the envelope ("MAIL FROM:") MUST be changed to be - the address of a person or other entity who administers the list. - However, in this case, the message header [32] MUST be left - unchanged; in particular, the "From" field of the message header is - unaffected. - - An important mail facility is a mechanism for multi-destination - delivery of a single message, by transforming (or "expanding" or - "exploding") a pseudo-mailbox address into a list of destination - mailbox addresses. When a message is sent to such a pseudo-mailbox - (sometimes called an "exploder"), copies are forwarded or - redistributed to each mailbox in the expanded list. Servers SHOULD - simply utilize the addresses on the list; application of heuristics - or other matching rules to eliminate some addresses, such as that of - the originator, is strongly discouraged. We classify such a pseudo- - mailbox as an "alias" or a "list", depending upon the expansion - rules. - -3.10.1 Alias - - To expand an alias, the recipient mailer simply replaces the pseudo- - mailbox address in the envelope with each of the expanded addresses - in turn; the rest of the envelope and the message body are left - unchanged. The message is then delivered or forwarded to each - expanded address. - -3.10.2 List - - A mailing list may be said to operate by "redistribution" rather than - by "forwarding". To expand a list, the recipient mailer replaces the - pseudo-mailbox address in the envelope with all of the expanded - - - -Klensin Standards Track [Page 28] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - addresses. The return address in the envelope is changed so that all - error messages generated by the final deliveries will be returned to - a list administrator, not to the message originator, who generally - has no control over the contents of the list and will typically find - error messages annoying. - -4. The SMTP Specifications - -4.1 SMTP Commands - -4.1.1 Command Semantics and Syntax - - The SMTP commands define the mail transfer or the mail system - function requested by the user. SMTP commands are character strings - terminated by . The commands themselves are alphabetic - characters terminated by if parameters follow and - otherwise. (In the interest of improved interoperability, SMTP - receivers are encouraged to tolerate trailing white space before the - terminating .) The syntax of the local part of a mailbox must - conform to receiver site conventions and the syntax specified in - section 4.1.2. The SMTP commands are discussed below. The SMTP - replies are discussed in section 4.2. - - A mail transaction involves several data objects which are - communicated as arguments to different commands. The reverse-path is - the argument of the MAIL command, the forward-path is the argument of - the RCPT command, and the mail data is the argument of the DATA - command. These arguments or data objects must be transmitted and - held pending the confirmation communicated by the end of mail data - indication which finalizes the transaction. The model for this is - that distinct buffers are provided to hold the types of data objects, - that is, there is a reverse-path buffer, a forward-path buffer, and a - mail data buffer. Specific commands cause information to be appended - to a specific buffer, or cause one or more buffers to be cleared. - - Several commands (RSET, DATA, QUIT) are specified as not permitting - parameters. In the absence of specific extensions offered by the - server and accepted by the client, clients MUST NOT send such - parameters and servers SHOULD reject commands containing them as - having invalid syntax. - -4.1.1.1 Extended HELLO (EHLO) or HELLO (HELO) - - These commands are used to identify the SMTP client to the SMTP - server. The argument field contains the fully-qualified domain name - of the SMTP client if one is available. In situations in which the - SMTP client system does not have a meaningful domain name (e.g., when - its address is dynamically allocated and no reverse mapping record is - - - -Klensin Standards Track [Page 29] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - available), the client SHOULD send an address literal (see section - 4.1.3), optionally followed by information that will help to identify - the client system. y The SMTP server identifies itself to the SMTP - client in the connection greeting reply and in the response to this - command. - - A client SMTP SHOULD start an SMTP session by issuing the EHLO - command. If the SMTP server supports the SMTP service extensions it - will give a successful response, a failure response, or an error - response. If the SMTP server, in violation of this specification, - does not support any SMTP service extensions it will generate an - error response. Older client SMTP systems MAY, as discussed above, - use HELO (as specified in RFC 821) instead of EHLO, and servers MUST - support the HELO command and reply properly to it. In any event, a - client MUST issue HELO or EHLO before starting a mail transaction. - - These commands, and a "250 OK" reply to one of them, confirm that - both the SMTP client and the SMTP server are in the initial state, - that is, there is no transaction in progress and all state tables and - buffers are cleared. - - Syntax: - - ehlo = "EHLO" SP Domain CRLF - helo = "HELO" SP Domain CRLF - - Normally, the response to EHLO will be a multiline reply. Each line - of the response contains a keyword and, optionally, one or more - parameters. Following the normal syntax for multiline replies, these - keyworks follow the code (250) and a hyphen for all but the last - line, and the code and a space for the last line. The syntax for a - positive response, using the ABNF notation and terminal symbols of - [8], is: - - ehlo-ok-rsp = ( "250" domain [ SP ehlo-greet ] CRLF ) - / ( "250-" domain [ SP ehlo-greet ] CRLF - *( "250-" ehlo-line CRLF ) - "250" SP ehlo-line CRLF ) - - ehlo-greet = 1*(%d0-9 / %d11-12 / %d14-127) - ; string of any characters other than CR or LF - - ehlo-line = ehlo-keyword *( SP ehlo-param ) - - ehlo-keyword = (ALPHA / DIGIT) *(ALPHA / DIGIT / "-") - ; additional syntax of ehlo-params depends on - ; ehlo-keyword - - - - -Klensin Standards Track [Page 30] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - ehlo-param = 1*(%d33-127) - ; any CHAR excluding and all - ; control characters (US-ASCII 0-31 inclusive) - - Although EHLO keywords may be specified in upper, lower, or mixed - case, they MUST always be recognized and processed in a case- - insensitive manner. This is simply an extension of practices - specified in RFC 821 and section 2.4.1. - -4.1.1.2 MAIL (MAIL) - - This command is used to initiate a mail transaction in which the mail - data is delivered to an SMTP server which may, in turn, deliver it to - one or more mailboxes or pass it on to another system (possibly using - SMTP). The argument field contains a reverse-path and may contain - optional parameters. In general, the MAIL command may be sent only - when no mail transaction is in progress, see section 4.1.4. - - The reverse-path consists of the sender mailbox. Historically, that - mailbox might optionally have been preceded by a list of hosts, but - that behavior is now deprecated (see appendix C). In some types of - reporting messages for which a reply is likely to cause a mail loop - (for example, mail delivery and nondelivery notifications), the - reverse-path may be null (see section 3.7). - - This command clears the reverse-path buffer, the forward-path buffer, - and the mail data buffer; and inserts the reverse-path information - from this command into the reverse-path buffer. - - If service extensions were negotiated, the MAIL command may also - carry parameters associated with a particular service extension. - - Syntax: - - "MAIL FROM:" ("<>" / Reverse-Path) - [SP Mail-parameters] CRLF - -4.1.1.3 RECIPIENT (RCPT) - - This command is used to identify an individual recipient of the mail - data; multiple recipients are specified by multiple use of this - command. The argument field contains a forward-path and may contain - optional parameters. - - The forward-path normally consists of the required destination - mailbox. Sending systems SHOULD not generate the optional list of - hosts known as a source route. Receiving systems MUST recognize - - - - -Klensin Standards Track [Page 31] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - source route syntax but SHOULD strip off the source route - specification and utilize the domain name associated with the mailbox - as if the source route had not been provided. - - Similarly, relay hosts SHOULD strip or ignore source routes, and - names MUST NOT be copied into the reverse-path. When mail reaches - its ultimate destination (the forward-path contains only a - destination mailbox), the SMTP server inserts it into the destination - mailbox in accordance with its host mail conventions. - - For example, mail received at relay host xyz.com with envelope - commands - - MAIL FROM: - RCPT TO:<@hosta.int,@jkl.org:userc@d.bar.org> - - will normally be sent directly on to host d.bar.org with envelope - commands - - MAIL FROM: - RCPT TO: - - As provided in appendix C, xyz.com MAY also choose to relay the - message to hosta.int, using the envelope commands - - MAIL FROM: - RCPT TO:<@hosta.int,@jkl.org:userc@d.bar.org> - - or to jkl.org, using the envelope commands - - MAIL FROM: - RCPT TO:<@jkl.org:userc@d.bar.org> - - Of course, since hosts are not required to relay mail at all, xyz.com - may also reject the message entirely when the RCPT command is - received, using a 550 code (since this is a "policy reason"). - - If service extensions were negotiated, the RCPT command may also - carry parameters associated with a particular service extension - offered by the server. The client MUST NOT transmit parameters other - than those associated with a service extension offered by the server - in its EHLO response. - -Syntax: - "RCPT TO:" ("" / "" / Forward-Path) - [SP Rcpt-parameters] CRLF - - - - - -Klensin Standards Track [Page 32] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - -4.1.1.4 DATA (DATA) - - The receiver normally sends a 354 response to DATA, and then treats - the lines (strings ending in sequences, as described in - section 2.3.7) following the command as mail data from the sender. - This command causes the mail data to be appended to the mail data - buffer. The mail data may contain any of the 128 ASCII character - codes, although experience has indicated that use of control - characters other than SP, HT, CR, and LF may cause problems and - SHOULD be avoided when possible. - - The mail data is terminated by a line containing only a period, that - is, the character sequence "." (see section 4.5.2). This - is the end of mail data indication. Note that the first of - this terminating sequence is also the that ends the final line - of the data (message text) or, if there was no data, ends the DATA - command itself. An extra MUST NOT be added, as that would - cause an empty line to be added to the message. The only exception - to this rule would arise if the message body were passed to the - originating SMTP-sender with a final "line" that did not end in - ; in that case, the originating SMTP system MUST either reject - the message as invalid or add in order to have the receiving - SMTP server recognize the "end of data" condition. - - The custom of accepting lines ending only in , as a concession to - non-conforming behavior on the part of some UNIX systems, has proven - to cause more interoperability problems than it solves, and SMTP - server systems MUST NOT do this, even in the name of improved - robustness. In particular, the sequence "." (bare line - feeds, without carriage returns) MUST NOT be treated as equivalent to - . as the end of mail data indication. - - Receipt of the end of mail data indication requires the server to - process the stored mail transaction information. This processing - consumes the information in the reverse-path buffer, the forward-path - buffer, and the mail data buffer, and on the completion of this - command these buffers are cleared. If the processing is successful, - the receiver MUST send an OK reply. If the processing fails the - receiver MUST send a failure reply. The SMTP model does not allow - for partial failures at this point: either the message is accepted by - the server for delivery and a positive response is returned or it is - not accepted and a failure reply is returned. In sending a positive - completion reply to the end of data indication, the receiver takes - full responsibility for the message (see section 6.1). Errors that - are diagnosed subsequently MUST be reported in a mail message, as - discussed in section 4.4. - - - - - -Klensin Standards Track [Page 33] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - When the SMTP server accepts a message either for relaying or for - final delivery, it inserts a trace record (also referred to - interchangeably as a "time stamp line" or "Received" line) at the top - of the mail data. This trace record indicates the identity of the - host that sent the message, the identity of the host that received - the message (and is inserting this time stamp), and the date and time - the message was received. Relayed messages will have multiple time - stamp lines. Details for formation of these lines, including their - syntax, is specified in section 4.4. - - Additional discussion about the operation of the DATA command appears - in section 3.3. - - Syntax: - "DATA" CRLF - -4.1.1.5 RESET (RSET) - - This command specifies that the current mail transaction will be - aborted. Any stored sender, recipients, and mail data MUST be - discarded, and all buffers and state tables cleared. The receiver - MUST send a "250 OK" reply to a RSET command with no arguments. A - reset command may be issued by the client at any time. It is - effectively equivalent to a NOOP (i.e., if has no effect) if issued - immediately after EHLO, before EHLO is issued in the session, after - an end-of-data indicator has been sent and acknowledged, or - immediately before a QUIT. An SMTP server MUST NOT close the - connection as the result of receiving a RSET; that action is reserved - for QUIT (see section 4.1.1.10). - - Since EHLO implies some additional processing and response by the - server, RSET will normally be more efficient than reissuing that - command, even though the formal semantics are the same. - - There are circumstances, contrary to the intent of this - specification, in which an SMTP server may receive an indication that - the underlying TCP connection has been closed or reset. To preserve - the robustness of the mail system, SMTP servers SHOULD be prepared - for this condition and SHOULD treat it as if a QUIT had been received - before the connection disappeared. - - Syntax: - "RSET" CRLF - - - - - - - - -Klensin Standards Track [Page 34] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - -4.1.1.6 VERIFY (VRFY) - - This command asks the receiver to confirm that the argument - identifies a user or mailbox. If it is a user name, information is - returned as specified in section 3.5. - - This command has no effect on the reverse-path buffer, the forward- - path buffer, or the mail data buffer. - - Syntax: - "VRFY" SP String CRLF - -4.1.1.7 EXPAND (EXPN) - - This command asks the receiver to confirm that the argument - identifies a mailing list, and if so, to return the membership of - that list. If the command is successful, a reply is returned - containing information as described in section 3.5. This reply will - have multiple lines except in the trivial case of a one-member list. - - This command has no effect on the reverse-path buffer, the forward- - path buffer, or the mail data buffer and may be issued at any time. - - Syntax: - "EXPN" SP String CRLF - -4.1.1.8 HELP (HELP) - - This command causes the server to send helpful information to the - client. The command MAY take an argument (e.g., any command name) - and return more specific information as a response. - - This command has no effect on the reverse-path buffer, the forward- - path buffer, or the mail data buffer and may be issued at any time. - - SMTP servers SHOULD support HELP without arguments and MAY support it - with arguments. - - Syntax: - "HELP" [ SP String ] CRLF - -4.1.1.9 NOOP (NOOP) - - This command does not affect any parameters or previously entered - commands. It specifies no action other than that the receiver send - an OK reply. - - - - - -Klensin Standards Track [Page 35] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - This command has no effect on the reverse-path buffer, the forward- - path buffer, or the mail data buffer and may be issued at any time. - If a parameter string is specified, servers SHOULD ignore it. - - Syntax: - "NOOP" [ SP String ] CRLF - -4.1.1.10 QUIT (QUIT) - - This command specifies that the receiver MUST send an OK reply, and - then close the transmission channel. - - The receiver MUST NOT intentionally close the transmission channel - until it receives and replies to a QUIT command (even if there was an - error). The sender MUST NOT intentionally close the transmission - channel until it sends a QUIT command and SHOULD wait until it - receives the reply (even if there was an error response to a previous - command). If the connection is closed prematurely due to violations - of the above or system or network failure, the server MUST cancel any - pending transaction, but not undo any previously completed - transaction, and generally MUST act as if the command or transaction - in progress had received a temporary error (i.e., a 4yz response). - - The QUIT command may be issued at any time. - - Syntax: - "QUIT" CRLF - -4.1.2 Command Argument Syntax - - The syntax of the argument fields of the above commands (using the - syntax specified in [8] where applicable) is given below. Some of - the productions given below are used only in conjunction with source - routes as described in appendix C. Terminals not defined in this - document, such as ALPHA, DIGIT, SP, CR, LF, CRLF, are as defined in - the "core" syntax [8 (section 6)] or in the message format syntax - [32]. - - Reverse-path = Path - Forward-path = Path - Path = "<" [ A-d-l ":" ] Mailbox ">" - A-d-l = At-domain *( "," A-d-l ) - ; Note that this form, the so-called "source route", - ; MUST BE accepted, SHOULD NOT be generated, and SHOULD be - ; ignored. - At-domain = "@" domain - Mail-parameters = esmtp-param *(SP esmtp-param) - Rcpt-parameters = esmtp-param *(SP esmtp-param) - - - -Klensin Standards Track [Page 36] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - esmtp-param = esmtp-keyword ["=" esmtp-value] - esmtp-keyword = (ALPHA / DIGIT) *(ALPHA / DIGIT / "-") - esmtp-value = 1*(%d33-60 / %d62-127) - ; any CHAR excluding "=", SP, and control characters - Keyword = Ldh-str - Argument = Atom - Domain = (sub-domain 1*("." sub-domain)) / address-literal - sub-domain = Let-dig [Ldh-str] - - address-literal = "[" IPv4-address-literal / - IPv6-address-literal / - General-address-literal "]" - ; See section 4.1.3 - - Mailbox = Local-part "@" Domain - - Local-part = Dot-string / Quoted-string - ; MAY be case-sensitive - - Dot-string = Atom *("." Atom) - - Atom = 1*atext - - Quoted-string = DQUOTE *qcontent DQUOTE - - String = Atom / Quoted-string - - While the above definition for Local-part is relatively permissive, - for maximum interoperability, a host that expects to receive mail - SHOULD avoid defining mailboxes where the Local-part requires (or - uses) the Quoted-string form or where the Local-part is case- - sensitive. For any purposes that require generating or comparing - Local-parts (e.g., to specific mailbox names), all quoted forms MUST - be treated as equivalent and the sending system SHOULD transmit the - form that uses the minimum quoting possible. - - Systems MUST NOT define mailboxes in such a way as to require the use - in SMTP of non-ASCII characters (octets with the high order bit set - to one) or ASCII "control characters" (decimal value 0-31 and 127). - These characters MUST NOT be used in MAIL or RCPT commands or other - commands that require mailbox names. - - Note that the backslash, "\", is a quote character, which is used to - indicate that the next character is to be used literally (instead of - its normal interpretation). For example, "Joe\,Smith" indicates a - single nine character user field with the comma being the fourth - character of the field. - - - - -Klensin Standards Track [Page 37] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - To promote interoperability and consistent with long-standing - guidance about conservative use of the DNS in naming and applications - (e.g., see section 2.3.1 of the base DNS document, RFC1035 [22]), - characters outside the set of alphas, digits, and hyphen MUST NOT - appear in domain name labels for SMTP clients or servers. In - particular, the underscore character is not permitted. SMTP servers - that receive a command in which invalid character codes have been - employed, and for which there are no other reasons for rejection, - MUST reject that command with a 501 response. - -4.1.3 Address Literals - - Sometimes a host is not known to the domain name system and - communication (and, in particular, communication to report and repair - the error) is blocked. To bypass this barrier a special literal form - of the address is allowed as an alternative to a domain name. For - IPv4 addresses, this form uses four small decimal integers separated - by dots and enclosed by brackets such as [123.255.37.2], which - indicates an (IPv4) Internet Address in sequence-of-octets form. For - IPv6 and other forms of addressing that might eventually be - standardized, the form consists of a standardized "tag" that - identifies the address syntax, a colon, and the address itself, in a - format specified as part of the IPv6 standards [17]. - - Specifically: - - IPv4-address-literal = Snum 3("." Snum) - IPv6-address-literal = "IPv6:" IPv6-addr - General-address-literal = Standardized-tag ":" 1*dcontent - Standardized-tag = Ldh-str - ; MUST be specified in a standards-track RFC - ; and registered with IANA - - Snum = 1*3DIGIT ; representing a decimal integer - ; value in the range 0 through 255 - Let-dig = ALPHA / DIGIT - Ldh-str = *( ALPHA / DIGIT / "-" ) Let-dig - - IPv6-addr = IPv6-full / IPv6-comp / IPv6v4-full / IPv6v4-comp - IPv6-hex = 1*4HEXDIG - IPv6-full = IPv6-hex 7(":" IPv6-hex) - IPv6-comp = [IPv6-hex *5(":" IPv6-hex)] "::" [IPv6-hex *5(":" - IPv6-hex)] - ; The "::" represents at least 2 16-bit groups of zeros - ; No more than 6 groups in addition to the "::" may be - ; present - IPv6v4-full = IPv6-hex 5(":" IPv6-hex) ":" IPv4-address-literal - IPv6v4-comp = [IPv6-hex *3(":" IPv6-hex)] "::" - - - -Klensin Standards Track [Page 38] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - [IPv6-hex *3(":" IPv6-hex) ":"] IPv4-address-literal - ; The "::" represents at least 2 16-bit groups of zeros - ; No more than 4 groups in addition to the "::" and - ; IPv4-address-literal may be present - -4.1.4 Order of Commands - - There are restrictions on the order in which these commands may be - used. - - A session that will contain mail transactions MUST first be - initialized by the use of the EHLO command. An SMTP server SHOULD - accept commands for non-mail transactions (e.g., VRFY or EXPN) - without this initialization. - - An EHLO command MAY be issued by a client later in the session. If - it is issued after the session begins, the SMTP server MUST clear all - buffers and reset the state exactly as if a RSET command had been - issued. In other words, the sequence of RSET followed immediately by - EHLO is redundant, but not harmful other than in the performance cost - of executing unnecessary commands. - - If the EHLO command is not acceptable to the SMTP server, 501, 500, - or 502 failure replies MUST be returned as appropriate. The SMTP - server MUST stay in the same state after transmitting these replies - that it was in before the EHLO was received. - - The SMTP client MUST, if possible, ensure that the domain parameter - to the EHLO command is a valid principal host name (not a CNAME or MX - name) for its host. If this is not possible (e.g., when the client's - address is dynamically assigned and the client does not have an - obvious name), an address literal SHOULD be substituted for the - domain name and supplemental information provided that will assist in - identifying the client. - - An SMTP server MAY verify that the domain name parameter in the EHLO - command actually corresponds to the IP address of the client. - However, the server MUST NOT refuse to accept a message for this - reason if the verification fails: the information about verification - failure is for logging and tracing only. - - The NOOP, HELP, EXPN, VRFY, and RSET commands can be used at any time - during a session, or without previously initializing a session. SMTP - servers SHOULD process these normally (that is, not return a 503 - code) even if no EHLO command has yet been received; clients SHOULD - open a session with EHLO before sending these commands. - - - - - -Klensin Standards Track [Page 39] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - If these rules are followed, the example in RFC 821 that shows "550 - access denied to you" in response to an EXPN command is incorrect - unless an EHLO command precedes the EXPN or the denial of access is - based on the client's IP address or other authentication or - authorization-determining mechanisms. - - The MAIL command (or the obsolete SEND, SOML, or SAML commands) - begins a mail transaction. Once started, a mail transaction consists - of a transaction beginning command, one or more RCPT commands, and a - DATA command, in that order. A mail transaction may be aborted by - the RSET (or a new EHLO) command. There may be zero or more - transactions in a session. MAIL (or SEND, SOML, or SAML) MUST NOT be - sent if a mail transaction is already open, i.e., it should be sent - only if no mail transaction had been started in the session, or it - the previous one successfully concluded with a successful DATA - command, or if the previous one was aborted with a RSET. - - If the transaction beginning command argument is not acceptable, a - 501 failure reply MUST be returned and the SMTP server MUST stay in - the same state. If the commands in a transaction are out of order to - the degree that they cannot be processed by the server, a 503 failure - reply MUST be returned and the SMTP server MUST stay in the same - state. - - The last command in a session MUST be the QUIT command. The QUIT - command cannot be used at any other time in a session, but SHOULD be - used by the client SMTP to request connection closure, even when no - session opening command was sent and accepted. - -4.1.5 Private-use Commands - - As specified in section 2.2.2, commands starting in "X" may be used - by bilateral agreement between the client (sending) and server - (receiving) SMTP agents. An SMTP server that does not recognize such - a command is expected to reply with "500 Command not recognized". An - extended SMTP server MAY list the feature names associated with these - private commands in the response to the EHLO command. - - Commands sent or accepted by SMTP systems that do not start with "X" - MUST conform to the requirements of section 2.2.2. - -4.2 SMTP Replies - - Replies to SMTP commands serve to ensure the synchronization of - requests and actions in the process of mail transfer and to guarantee - that the SMTP client always knows the state of the SMTP server. - Every command MUST generate exactly one reply. - - - - -Klensin Standards Track [Page 40] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - The details of the command-reply sequence are described in section - 4.3. - - An SMTP reply consists of a three digit number (transmitted as three - numeric characters) followed by some text unless specified otherwise - in this document. The number is for use by automata to determine - what state to enter next; the text is for the human user. The three - digits contain enough encoded information that the SMTP client need - not examine the text and may either discard it or pass it on to the - user, as appropriate. Exceptions are as noted elsewhere in this - document. In particular, the 220, 221, 251, 421, and 551 reply codes - are associated with message text that must be parsed and interpreted - by machines. In the general case, the text may be receiver dependent - and context dependent, so there are likely to be varying texts for - each reply code. A discussion of the theory of reply codes is given - in section 4.2.1. Formally, a reply is defined to be the sequence: a - three-digit code, , one line of text, and , or a multiline - reply (as defined in section 4.2.1). Since, in violation of this - specification, the text is sometimes not sent, clients which do not - receive it SHOULD be prepared to process the code alone (with or - without a trailing space character). Only the EHLO, EXPN, and HELP - commands are expected to result in multiline replies in normal - circumstances, however, multiline replies are allowed for any - command. - - In ABNF, server responses are: - - Greeting = "220 " Domain [ SP text ] CRLF - Reply-line = Reply-code [ SP text ] CRLF - - where "Greeting" appears only in the 220 response that announces that - the server is opening its part of the connection. - - An SMTP server SHOULD send only the reply codes listed in this - document. An SMTP server SHOULD use the text shown in the examples - whenever appropriate. - - An SMTP client MUST determine its actions only by the reply code, not - by the text (except for the "change of address" 251 and 551 and, if - necessary, 220, 221, and 421 replies); in the general case, any text, - including no text at all (although senders SHOULD NOT send bare - codes), MUST be acceptable. The space (blank) following the reply - code is considered part of the text. Whenever possible, a receiver- - SMTP SHOULD test the first digit (severity indication) of the reply - code. - - - - - - -Klensin Standards Track [Page 41] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - The list of codes that appears below MUST NOT be construed as - permanent. While the addition of new codes should be a rare and - significant activity, with supplemental information in the textual - part of the response being preferred, new codes may be added as the - result of new Standards or Standards-track specifications. - Consequently, a sender-SMTP MUST be prepared to handle codes not - specified in this document and MUST do so by interpreting the first - digit only. - -4.2.1 Reply Code Severities and Theory - - The three digits of the reply each have a special significance. The - first digit denotes whether the response is good, bad or incomplete. - An unsophisticated SMTP client, or one that receives an unexpected - code, will be able to determine its next action (proceed as planned, - redo, retrench, etc.) by examining this first digit. An SMTP client - that wants to know approximately what kind of error occurred (e.g., - mail system error, command syntax error) may examine the second - digit. The third digit and any supplemental information that may be - present is reserved for the finest gradation of information. - - There are five values for the first digit of the reply code: - - 1yz Positive Preliminary reply - The command has been accepted, but the requested action is being - held in abeyance, pending confirmation of the information in this - reply. The SMTP client should send another command specifying - whether to continue or abort the action. Note: unextended SMTP - does not have any commands that allow this type of reply, and so - does not have continue or abort commands. - - 2yz Positive Completion reply - The requested action has been successfully completed. A new - request may be initiated. - - 3yz Positive Intermediate reply - The command has been accepted, but the requested action is being - held in abeyance, pending receipt of further information. The - SMTP client should send another command specifying this - information. This reply is used in command sequence groups (i.e., - in DATA). - - 4yz Transient Negative Completion reply - The command was not accepted, and the requested action did not - occur. However, the error condition is temporary and the action - may be requested again. The sender should return to the beginning - of the command sequence (if any). It is difficult to assign a - meaning to "transient" when two different sites (receiver- and - - - -Klensin Standards Track [Page 42] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - sender-SMTP agents) must agree on the interpretation. Each reply - in this category might have a different time value, but the SMTP - client is encouraged to try again. A rule of thumb to determine - whether a reply fits into the 4yz or the 5yz category (see below) - is that replies are 4yz if they can be successful if repeated - without any change in command form or in properties of the sender - or receiver (that is, the command is repeated identically and the - receiver does not put up a new implementation.) - - 5yz Permanent Negative Completion reply - The command was not accepted and the requested action did not - occur. The SMTP client is discouraged from repeating the exact - request (in the same sequence). Even some "permanent" error - conditions can be corrected, so the human user may want to direct - the SMTP client to reinitiate the command sequence by direct - action at some point in the future (e.g., after the spelling has - been changed, or the user has altered the account status). - - The second digit encodes responses in specific categories: - - x0z Syntax: These replies refer to syntax errors, syntactically - correct commands that do not fit any functional category, and - unimplemented or superfluous commands. - - x1z Information: These are replies to requests for information, - such as status or help. - - x2z Connections: These are replies referring to the transmission - channel. - - x3z Unspecified. - - x4z Unspecified. - - x5z Mail system: These replies indicate the status of the receiver - mail system vis-a-vis the requested transfer or other mail system - action. - - The third digit gives a finer gradation of meaning in each category - specified by the second digit. The list of replies illustrates this. - Each reply text is recommended rather than mandatory, and may even - change according to the command with which it is associated. On the - other hand, the reply codes must strictly follow the specifications - in this section. Receiver implementations should not invent new - codes for slightly different situations from the ones described here, - but rather adapt codes already defined. - - - - - -Klensin Standards Track [Page 43] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - For example, a command such as NOOP, whose successful execution does - not offer the SMTP client any new information, will return a 250 - reply. The reply is 502 when the command requests an unimplemented - non-site-specific action. A refinement of that is the 504 reply for - a command that is implemented, but that requests an unimplemented - parameter. - - The reply text may be longer than a single line; in these cases the - complete text must be marked so the SMTP client knows when it can - stop reading the reply. This requires a special format to indicate a - multiple line reply. - - The format for multiline replies requires that every line, except the - last, begin with the reply code, followed immediately by a hyphen, - "-" (also known as minus), followed by text. The last line will - begin with the reply code, followed immediately by , optionally - some text, and . As noted above, servers SHOULD send the - if subsequent text is not sent, but clients MUST be prepared for it - to be omitted. - - For example: - - 123-First line - 123-Second line - 123-234 text beginning with numbers - 123 The last line - - In many cases the SMTP client then simply needs to search for a line - beginning with the reply code followed by or and ignore - all preceding lines. In a few cases, there is important data for the - client in the reply "text". The client will be able to identify - these cases from the current context. - -4.2.2 Reply Codes by Function Groups - - 500 Syntax error, command unrecognized - (This may include errors such as command line too long) - 501 Syntax error in parameters or arguments - 502 Command not implemented (see section 4.2.4) - 503 Bad sequence of commands - 504 Command parameter not implemented - - 211 System status, or system help reply - 214 Help message - (Information on how to use the receiver or the meaning of a - particular non-standard command; this reply is useful only - to the human user) - - - - -Klensin Standards Track [Page 44] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - 220 Service ready - 221 Service closing transmission channel - 421 Service not available, closing transmission channel - (This may be a reply to any command if the service knows it - must shut down) - - 250 Requested mail action okay, completed - 251 User not local; will forward to - (See section 3.4) - 252 Cannot VRFY user, but will accept message and attempt - delivery - (See section 3.5.3) - 450 Requested mail action not taken: mailbox unavailable - (e.g., mailbox busy) - 550 Requested action not taken: mailbox unavailable - (e.g., mailbox not found, no access, or command rejected - for policy reasons) - 451 Requested action aborted: error in processing - 551 User not local; please try - (See section 3.4) - 452 Requested action not taken: insufficient system storage - 552 Requested mail action aborted: exceeded storage allocation - 553 Requested action not taken: mailbox name not allowed - (e.g., mailbox syntax incorrect) - 354 Start mail input; end with . - 554 Transaction failed (Or, in the case of a connection-opening - response, "No SMTP service here") - -4.2.3 Reply Codes in Numeric Order - - 211 System status, or system help reply - 214 Help message - (Information on how to use the receiver or the meaning of a - particular non-standard command; this reply is useful only - to the human user) - 220 Service ready - 221 Service closing transmission channel - 250 Requested mail action okay, completed - 251 User not local; will forward to - (See section 3.4) - 252 Cannot VRFY user, but will accept message and attempt - delivery - (See section 3.5.3) - - 354 Start mail input; end with . - - - - - - -Klensin Standards Track [Page 45] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - 421 Service not available, closing transmission channel - (This may be a reply to any command if the service knows it - must shut down) - 450 Requested mail action not taken: mailbox unavailable - (e.g., mailbox busy) - 451 Requested action aborted: local error in processing - 452 Requested action not taken: insufficient system storage - 500 Syntax error, command unrecognized - (This may include errors such as command line too long) - 501 Syntax error in parameters or arguments - 502 Command not implemented (see section 4.2.4) - 503 Bad sequence of commands - 504 Command parameter not implemented - 550 Requested action not taken: mailbox unavailable - (e.g., mailbox not found, no access, or command rejected - for policy reasons) - 551 User not local; please try - (See section 3.4) - 552 Requested mail action aborted: exceeded storage allocation - 553 Requested action not taken: mailbox name not allowed - (e.g., mailbox syntax incorrect) - 554 Transaction failed (Or, in the case of a connection-opening - response, "No SMTP service here") - -4.2.4 Reply Code 502 - - Questions have been raised as to when reply code 502 (Command not - implemented) SHOULD be returned in preference to other codes. 502 - SHOULD be used when the command is actually recognized by the SMTP - server, but not implemented. If the command is not recognized, code - 500 SHOULD be returned. Extended SMTP systems MUST NOT list - capabilities in response to EHLO for which they will return 502 (or - 500) replies. - -4.2.5 Reply Codes After DATA and the Subsequent . - - When an SMTP server returns a positive completion status (2yz code) - after the DATA command is completed with ., it accepts - responsibility for: - - - delivering the message (if the recipient mailbox exists), or - - - if attempts to deliver the message fail due to transient - conditions, retrying delivery some reasonable number of times at - intervals as specified in section 4.5.4. - - - - - - -Klensin Standards Track [Page 46] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - - if attempts to deliver the message fail due to permanent - conditions, or if repeated attempts to deliver the message fail - due to transient conditions, returning appropriate notification to - the sender of the original message (using the address in the SMTP - MAIL command). - - When an SMTP server returns a permanent error status (5yz) code after - the DATA command is completed with ., it MUST NOT make - any subsequent attempt to deliver that message. The SMTP client - retains responsibility for delivery of that message and may either - return it to the user or requeue it for a subsequent attempt (see - section 4.5.4.1). - - The user who originated the message SHOULD be able to interpret the - return of a transient failure status (by mail message or otherwise) - as a non-delivery indication, just as a permanent failure would be - interpreted. I.e., if the client SMTP successfully handles these - conditions, the user will not receive such a reply. - - When an SMTP server returns a permanent error status (5yz) code after - the DATA command is completely with ., it MUST NOT make - any subsequent attempt to deliver the message. As with temporary - error status codes, the SMTP client retains responsibility for the - message, but SHOULD not again attempt delivery to the same server - without user review and intervention of the message. - -4.3 Sequencing of Commands and Replies - -4.3.1 Sequencing Overview - - The communication between the sender and receiver is an alternating - dialogue, controlled by the sender. As such, the sender issues a - command and the receiver responds with a reply. Unless other - arrangements are negotiated through service extensions, the sender - MUST wait for this response before sending further commands. - - One important reply is the connection greeting. Normally, a receiver - will send a 220 "Service ready" reply when the connection is - completed. The sender SHOULD wait for this greeting message before - sending any commands. - - Note: all the greeting-type replies have the official name (the - fully-qualified primary domain name) of the server host as the first - word following the reply code. Sometimes the host will have no - meaningful name. See 4.1.3 for a discussion of alternatives in these - situations. - - - - - -Klensin Standards Track [Page 47] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - For example, - - 220 ISIF.USC.EDU Service ready - or - 220 mail.foo.com SuperSMTP v 6.1.2 Service ready - or - 220 [10.0.0.1] Clueless host service ready - - The table below lists alternative success and failure replies for - each command. These SHOULD be strictly adhered to: a receiver may - substitute text in the replies, but the meaning and action implied by - the code numbers and by the specific command reply sequence cannot be - altered. - -4.3.2 Command-Reply Sequences - - Each command is listed with its usual possible replies. The prefixes - used before the possible replies are "I" for intermediate, "S" for - success, and "E" for error. Since some servers may generate other - replies under special circumstances, and to allow for future - extension, SMTP clients SHOULD, when possible, interpret only the - first digit of the reply and MUST be prepared to deal with - unrecognized reply codes by interpreting the first digit only. - Unless extended using the mechanisms described in section 2.2, SMTP - servers MUST NOT transmit reply codes to an SMTP client that are - other than three digits or that do not start in a digit between 2 and - 5 inclusive. - - These sequencing rules and, in principle, the codes themselves, can - be extended or modified by SMTP extensions offered by the server and - accepted (requested) by the client. - - In addition to the codes listed below, any SMTP command can return - any of the following codes if the corresponding unusual circumstances - are encountered: - - 500 For the "command line too long" case or if the command name was - not recognized. Note that producing a "command not recognized" - error in response to the required subset of these commands is a - violation of this specification. - - 501 Syntax error in command or arguments. In order to provide for - future extensions, commands that are specified in this document as - not accepting arguments (DATA, RSET, QUIT) SHOULD return a 501 - message if arguments are supplied in the absence of EHLO- - advertised extensions. - - 421 Service shutting down and closing transmission channel - - - -Klensin Standards Track [Page 48] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - Specific sequences are: - - CONNECTION ESTABLISHMENT - S: 220 - E: 554 - EHLO or HELO - S: 250 - E: 504, 550 - MAIL - S: 250 - E: 552, 451, 452, 550, 553, 503 - RCPT - S: 250, 251 (but see section 3.4 for discussion of 251 and 551) - E: 550, 551, 552, 553, 450, 451, 452, 503, 550 - DATA - I: 354 -> data -> S: 250 - E: 552, 554, 451, 452 - E: 451, 554, 503 - RSET - S: 250 - VRFY - S: 250, 251, 252 - E: 550, 551, 553, 502, 504 - EXPN - S: 250, 252 - E: 550, 500, 502, 504 - HELP - S: 211, 214 - E: 502, 504 - NOOP - S: 250 - QUIT - S: 221 - -4.4 Trace Information - - When an SMTP server receives a message for delivery or further - processing, it MUST insert trace ("time stamp" or "Received") - information at the beginning of the message content, as discussed in - section 4.1.1.4. - - This line MUST be structured as follows: - - - The FROM field, which MUST be supplied in an SMTP environment, - SHOULD contain both (1) the name of the source host as presented - in the EHLO command and (2) an address literal containing the IP - address of the source, determined from the TCP connection. - - - - -Klensin Standards Track [Page 49] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - - The ID field MAY contain an "@" as suggested in RFC 822, but this - is not required. - - - The FOR field MAY contain a list of entries when multiple - RCPT commands have been given. This may raise some security - issues and is usually not desirable; see section 7.2. - - An Internet mail program MUST NOT change a Received: line that was - previously added to the message header. SMTP servers MUST prepend - Received lines to messages; they MUST NOT change the order of - existing lines or insert Received lines in any other location. - - As the Internet grows, comparability of Received fields is important - for detecting problems, especially slow relays. SMTP servers that - create Received fields SHOULD use explicit offsets in the dates - (e.g., -0800), rather than time zone names of any type. Local time - (with an offset) is preferred to UT when feasible. This formulation - allows slightly more information about local circumstances to be - specified. If UT is needed, the receiver need merely do some simple - arithmetic to convert the values. Use of UT loses information about - the time zone-location of the server. If it is desired to supply a - time zone name, it SHOULD be included in a comment. - - When the delivery SMTP server makes the "final delivery" of a - message, it inserts a return-path line at the beginning of the mail - data. This use of return-path is required; mail systems MUST support - it. The return-path line preserves the information in the from the MAIL command. Here, final delivery means the message - has left the SMTP environment. Normally, this would mean it had been - delivered to the destination user or an associated mail drop, but in - some cases it may be further processed and transmitted by another - mail system. - - It is possible for the mailbox in the return path to be different - from the actual sender's mailbox, for example, if error responses are - to be delivered to a special error handling mailbox rather than to - the message sender. When mailing lists are involved, this - arrangement is common and useful as a means of directing errors to - the list maintainer rather than the message originator. - - The text above implies that the final mail data will begin with a - return path line, followed by one or more time stamp lines. These - lines will be followed by the mail data headers and body [32]. - - It is sometimes difficult for an SMTP server to determine whether or - not it is making final delivery since forwarding or other operations - may occur after the message is accepted for delivery. Consequently, - - - - -Klensin Standards Track [Page 50] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - any further (forwarding, gateway, or relay) systems MAY remove the - return path and rebuild the MAIL command as needed to ensure that - exactly one such line appears in a delivered message. - - A message-originating SMTP system SHOULD NOT send a message that - already contains a Return-path header. SMTP servers performing a - relay function MUST NOT inspect the message data, and especially not - to the extent needed to determine if Return-path headers are present. - SMTP servers making final delivery MAY remove Return-path headers - before adding their own. - - The primary purpose of the Return-path is to designate the address to - which messages indicating non-delivery or other mail system failures - are to be sent. For this to be unambiguous, exactly one return path - SHOULD be present when the message is delivered. Systems using RFC - 822 syntax with non-SMTP transports SHOULD designate an unambiguous - address, associated with the transport envelope, to which error - reports (e.g., non-delivery messages) should be sent. - - Historical note: Text in RFC 822 that appears to contradict the use - of the Return-path header (or the envelope reverse path address from - the MAIL command) as the destination for error messages is not - applicable on the Internet. The reverse path address (as copied into - the Return-path) MUST be used as the target of any mail containing - delivery error messages. - - In particular: - - - a gateway from SMTP->elsewhere SHOULD insert a return-path header, - unless it is known that the "elsewhere" transport also uses - Internet domain addresses and maintains the envelope sender - address separately. - - - a gateway from elsewhere->SMTP SHOULD delete any return-path - header present in the message, and either copy that information to - the SMTP envelope or combine it with information present in the - envelope of the other transport system to construct the reverse - path argument to the MAIL command in the SMTP envelope. - - The server must give special treatment to cases in which the - processing following the end of mail data indication is only - partially successful. This could happen if, after accepting several - recipients and the mail data, the SMTP server finds that the mail - data could be successfully delivered to some, but not all, of the - recipients. In such cases, the response to the DATA command MUST be - an OK reply. However, the SMTP server MUST compose and send an - "undeliverable mail" notification message to the originator of the - message. - - - -Klensin Standards Track [Page 51] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - A single notification listing all of the failed recipients or - separate notification messages MUST be sent for each failed - recipient. For economy of processing by the sender, the former is - preferred when possible. All undeliverable mail notification - messages are sent using the MAIL command (even if they result from - processing the obsolete SEND, SOML, or SAML commands) and use a null - return path as discussed in section 3.7. - - The time stamp line and the return path line are formally defined as - follows: - -Return-path-line = "Return-Path:" FWS Reverse-path - -Time-stamp-line = "Received:" FWS Stamp - -Stamp = From-domain By-domain Opt-info ";" FWS date-time - - ; where "date-time" is as defined in [32] - ; but the "obs-" forms, especially two-digit - ; years, are prohibited in SMTP and MUST NOT be used. - -From-domain = "FROM" FWS Extended-Domain CFWS - -By-domain = "BY" FWS Extended-Domain CFWS - -Extended-Domain = Domain / - ( Domain FWS "(" TCP-info ")" ) / - ( Address-literal FWS "(" TCP-info ")" ) - -TCP-info = Address-literal / ( Domain FWS Address-literal ) - ; Information derived by server from TCP connection - ; not client EHLO. - -Opt-info = [Via] [With] [ID] [For] - -Via = "VIA" FWS Link CFWS - -With = "WITH" FWS Protocol CFWS - -ID = "ID" FWS String / msg-id CFWS - -For = "FOR" FWS 1*( Path / Mailbox ) CFWS - -Link = "TCP" / Addtl-Link -Addtl-Link = Atom - ; Additional standard names for links are registered with the - ; Internet Assigned Numbers Authority (IANA). "Via" is - ; primarily of value with non-Internet transports. SMTP - - - -Klensin Standards Track [Page 52] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - ; servers SHOULD NOT use unregistered names. -Protocol = "ESMTP" / "SMTP" / Attdl-Protocol -Attdl-Protocol = Atom - ; Additional standard names for protocols are registered with the - ; Internet Assigned Numbers Authority (IANA). SMTP servers - ; SHOULD NOT use unregistered names. - -4.5 Additional Implementation Issues - -4.5.1 Minimum Implementation - - In order to make SMTP workable, the following minimum implementation - is required for all receivers. The following commands MUST be - supported to conform to this specification: - - EHLO - HELO - MAIL - RCPT - DATA - RSET - NOOP - QUIT - VRFY - - Any system that includes an SMTP server supporting mail relaying or - delivery MUST support the reserved mailbox "postmaster" as a case- - insensitive local name. This postmaster address is not strictly - necessary if the server always returns 554 on connection opening (as - described in section 3.1). The requirement to accept mail for - postmaster implies that RCPT commands which specify a mailbox for - postmaster at any of the domains for which the SMTP server provides - mail service, as well as the special case of "RCPT TO:" - (with no domain specification), MUST be supported. - - SMTP systems are expected to make every reasonable effort to accept - mail directed to Postmaster from any other system on the Internet. - In extreme cases --such as to contain a denial of service attack or - other breach of security-- an SMTP server may block mail directed to - Postmaster. However, such arrangements SHOULD be narrowly tailored - so as to avoid blocking messages which are not part of such attacks. - -4.5.2 Transparency - - Without some provision for data transparency, the character sequence - "." ends the mail text and cannot be sent by the user. - In general, users are not aware of such "forbidden" sequences. To - - - - -Klensin Standards Track [Page 53] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - allow all user composed text to be transmitted transparently, the - following procedures are used: - - - Before sending a line of mail text, the SMTP client checks the - first character of the line. If it is a period, one additional - period is inserted at the beginning of the line. - - - When a line of mail text is received by the SMTP server, it checks - the line. If the line is composed of a single period, it is - treated as the end of mail indicator. If the first character is a - period and there are other characters on the line, the first - character is deleted. - - The mail data may contain any of the 128 ASCII characters. All - characters are to be delivered to the recipient's mailbox, including - spaces, vertical and horizontal tabs, and other control characters. - If the transmission channel provides an 8-bit byte (octet) data - stream, the 7-bit ASCII codes are transmitted right justified in the - octets, with the high order bits cleared to zero. See 3.7 for - special treatment of these conditions in SMTP systems serving a relay - function. - - In some systems it may be necessary to transform the data as it is - received and stored. This may be necessary for hosts that use a - different character set than ASCII as their local character set, that - store data in records rather than strings, or which use special - character sequences as delimiters inside mailboxes. If such - transformations are necessary, they MUST be reversible, especially if - they are applied to mail being relayed. - -4.5.3 Sizes and Timeouts - -4.5.3.1 Size limits and minimums - - There are several objects that have required minimum/maximum sizes. - Every implementation MUST be able to receive objects of at least - these sizes. Objects larger than these sizes SHOULD be avoided when - possible. However, some Internet mail constructs such as encoded - X.400 addresses [16] will often require larger objects: clients MAY - attempt to transmit these, but MUST be prepared for a server to - reject them if they cannot be handled by it. To the maximum extent - possible, implementation techniques which impose no limits on the - length of these objects should be used. - - local-part - The maximum total length of a user name or other local-part is 64 - characters. - - - - -Klensin Standards Track [Page 54] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - domain - The maximum total length of a domain name or number is 255 - characters. - - path - The maximum total length of a reverse-path or forward-path is 256 - characters (including the punctuation and element separators). - - command line - The maximum total length of a command line including the command - word and the is 512 characters. SMTP extensions may be - used to increase this limit. - - reply line - The maximum total length of a reply line including the reply code - and the is 512 characters. More information may be - conveyed through multiple-line replies. - - text line - The maximum total length of a text line including the is - 1000 characters (not counting the leading dot duplicated for - transparency). This number may be increased by the use of SMTP - Service Extensions. - - message content - The maximum total length of a message content (including any - message headers as well as the message body) MUST BE at least 64K - octets. Since the introduction of Internet standards for - multimedia mail [12], message lengths on the Internet have grown - dramatically, and message size restrictions should be avoided if - at all possible. SMTP server systems that must impose - restrictions SHOULD implement the "SIZE" service extension [18], - and SMTP client systems that will send large messages SHOULD - utilize it when possible. - - recipients buffer - The minimum total number of recipients that must be buffered is - 100 recipients. Rejection of messages (for excessive recipients) - with fewer than 100 RCPT commands is a violation of this - specification. The general principle that relaying SMTP servers - MUST NOT, and delivery SMTP servers SHOULD NOT, perform validation - tests on message headers suggests that rejecting a message based - on the total number of recipients shown in header fields is to be - discouraged. A server which imposes a limit on the number of - recipients MUST behave in an orderly fashion, such as to reject - additional addresses over its limit rather than silently - discarding addresses previously accepted. A client that needs to - - - - -Klensin Standards Track [Page 55] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - deliver a message containing over 100 RCPT commands SHOULD be - prepared to transmit in 100-recipient "chunks" if the server - declines to accept more than 100 recipients in a single message. - - Errors due to exceeding these limits may be reported by using the - reply codes. Some examples of reply codes are: - - 500 Line too long. - or - 501 Path too long - or - 452 Too many recipients (see below) - or - 552 Too much mail data. - - RFC 821 [30] incorrectly listed the error where an SMTP server - exhausts its implementation limit on the number of RCPT commands - ("too many recipients") as having reply code 552. The correct reply - code for this condition is 452. Clients SHOULD treat a 552 code in - this case as a temporary, rather than permanent, failure so the logic - below works. - - When a conforming SMTP server encounters this condition, it has at - least 100 successful RCPT commands in its recipients buffer. If the - server is able to accept the message, then at least these 100 - addresses will be removed from the SMTP client's queue. When the - client attempts retransmission of those addresses which received 452 - responses, at least 100 of these will be able to fit in the SMTP - server's recipients buffer. Each retransmission attempt which is - able to deliver anything will be able to dispose of at least 100 of - these recipients. - - If an SMTP server has an implementation limit on the number of RCPT - commands and this limit is exhausted, it MUST use a response code of - 452 (but the client SHOULD also be prepared for a 552, as noted - above). If the server has a configured site-policy limitation on the - number of RCPT commands, it MAY instead use a 5XX response code. - This would be most appropriate if the policy limitation was intended - to apply if the total recipient count for a particular message body - were enforced even if that message body was sent in multiple mail - transactions. - -4.5.3.2 Timeouts - - An SMTP client MUST provide a timeout mechanism. It MUST use per- - command timeouts rather than somehow trying to time the entire mail - transaction. Timeouts SHOULD be easily reconfigurable, preferably - without recompiling the SMTP code. To implement this, a timer is set - - - -Klensin Standards Track [Page 56] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - for each SMTP command and for each buffer of the data transfer. The - latter means that the overall timeout is inherently proportional to - the size of the message. - - Based on extensive experience with busy mail-relay hosts, the minimum - per-command timeout values SHOULD be as follows: - - Initial 220 Message: 5 minutes - An SMTP client process needs to distinguish between a failed TCP - connection and a delay in receiving the initial 220 greeting - message. Many SMTP servers accept a TCP connection but delay - delivery of the 220 message until their system load permits more - mail to be processed. - - MAIL Command: 5 minutes - - RCPT Command: 5 minutes - A longer timeout is required if processing of mailing lists and - aliases is not deferred until after the message was accepted. - - DATA Initiation: 2 minutes - This is while awaiting the "354 Start Input" reply to a DATA - command. - - Data Block: 3 minutes - This is while awaiting the completion of each TCP SEND call - transmitting a chunk of data. - - DATA Termination: 10 minutes. - This is while awaiting the "250 OK" reply. When the receiver gets - the final period terminating the message data, it typically - performs processing to deliver the message to a user mailbox. A - spurious timeout at this point would be very wasteful and would - typically result in delivery of multiple copies of the message, - since it has been successfully sent and the server has accepted - responsibility for delivery. See section 6.1 for additional - discussion. - - An SMTP server SHOULD have a timeout of at least 5 minutes while it - is awaiting the next command from the sender. - -4.5.4 Retry Strategies - - The common structure of a host SMTP implementation includes user - mailboxes, one or more areas for queuing messages in transit, and one - or more daemon processes for sending and receiving mail. The exact - structure will vary depending on the needs of the users on the host - - - - -Klensin Standards Track [Page 57] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - and the number and size of mailing lists supported by the host. We - describe several optimizations that have proved helpful, particularly - for mailers supporting high traffic levels. - - Any queuing strategy MUST include timeouts on all activities on a - per-command basis. A queuing strategy MUST NOT send error messages - in response to error messages under any circumstances. - -4.5.4.1 Sending Strategy - - The general model for an SMTP client is one or more processes that - periodically attempt to transmit outgoing mail. In a typical system, - the program that composes a message has some method for requesting - immediate attention for a new piece of outgoing mail, while mail that - cannot be transmitted immediately MUST be queued and periodically - retried by the sender. A mail queue entry will include not only the - message itself but also the envelope information. - - The sender MUST delay retrying a particular destination after one - attempt has failed. In general, the retry interval SHOULD be at - least 30 minutes; however, more sophisticated and variable strategies - will be beneficial when the SMTP client can determine the reason for - non-delivery. - - Retries continue until the message is transmitted or the sender gives - up; the give-up time generally needs to be at least 4-5 days. The - parameters to the retry algorithm MUST be configurable. - - A client SHOULD keep a list of hosts it cannot reach and - corresponding connection timeouts, rather than just retrying queued - mail items. - - Experience suggests that failures are typically transient (the target - system or its connection has crashed), favoring a policy of two - connection attempts in the first hour the message is in the queue, - and then backing off to one every two or three hours. - - The SMTP client can shorten the queuing delay in cooperation with the - SMTP server. For example, if mail is received from a particular - address, it is likely that mail queued for that host can now be sent. - Application of this principle may, in many cases, eliminate the - requirement for an explicit "send queues now" function such as ETRN - [9]. - - The strategy may be further modified as a result of multiple - addresses per host (see below) to optimize delivery time vs. resource - usage. - - - - -Klensin Standards Track [Page 58] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - An SMTP client may have a large queue of messages for each - unavailable destination host. If all of these messages were retried - in every retry cycle, there would be excessive Internet overhead and - the sending system would be blocked for a long period. Note that an - SMTP client can generally determine that a delivery attempt has - failed only after a timeout of several minutes and even a one-minute - timeout per connection will result in a very large delay if retries - are repeated for dozens, or even hundreds, of queued messages to the - same host. - - At the same time, SMTP clients SHOULD use great care in caching - negative responses from servers. In an extreme case, if EHLO is - issued multiple times during the same SMTP connection, different - answers may be returned by the server. More significantly, 5yz - responses to the MAIL command MUST NOT be cached. - - When a mail message is to be delivered to multiple recipients, and - the SMTP server to which a copy of the message is to be sent is the - same for multiple recipients, then only one copy of the message - SHOULD be transmitted. That is, the SMTP client SHOULD use the - command sequence: MAIL, RCPT, RCPT,... RCPT, DATA instead of the - sequence: MAIL, RCPT, DATA, ..., MAIL, RCPT, DATA. However, if there - are very many addresses, a limit on the number of RCPT commands per - MAIL command MAY be imposed. Implementation of this efficiency - feature is strongly encouraged. - - Similarly, to achieve timely delivery, the SMTP client MAY support - multiple concurrent outgoing mail transactions. However, some limit - may be appropriate to protect the host from devoting all its - resources to mail. - -4.5.4.2 Receiving Strategy - - The SMTP server SHOULD attempt to keep a pending listen on the SMTP - port at all times. This requires the support of multiple incoming - TCP connections for SMTP. Some limit MAY be imposed but servers that - cannot handle more than one SMTP transaction at a time are not in - conformance with the intent of this specification. - - As discussed above, when the SMTP server receives mail from a - particular host address, it could activate its own SMTP queuing - mechanisms to retry any mail pending for that host address. - -4.5.5 Messages with a null reverse-path - - There are several types of notification messages which are required - by existing and proposed standards to be sent with a null reverse - path, namely non-delivery notifications as discussed in section 3.7, - - - -Klensin Standards Track [Page 59] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - other kinds of Delivery Status Notifications (DSNs) [24], and also - Message Disposition Notifications (MDNs) [10]. All of these kinds of - messages are notifications about a previous message, and they are - sent to the reverse-path of the previous mail message. (If the - delivery of such a notification message fails, that usually indicates - a problem with the mail system of the host to which the notification - message is addressed. For this reason, at some hosts the MTA is set - up to forward such failed notification messages to someone who is - able to fix problems with the mail system, e.g., via the postmaster - alias.) - - All other types of messages (i.e., any message which is not required - by a standards-track RFC to have a null reverse-path) SHOULD be sent - with with a valid, non-null reverse-path. - - Implementors of automated email processors should be careful to make - sure that the various kinds of messages with null reverse-path are - handled correctly, in particular such systems SHOULD NOT reply to - messages with null reverse-path. - -5. Address Resolution and Mail Handling - - Once an SMTP client lexically identifies a domain to which mail will - be delivered for processing (as described in sections 3.6 and 3.7), a - DNS lookup MUST be performed to resolve the domain name [22]. The - names are expected to be fully-qualified domain names (FQDNs): - mechanisms for inferring FQDNs from partial names or local aliases - are outside of this specification and, due to a history of problems, - are generally discouraged. The lookup first attempts to locate an MX - record associated with the name. If a CNAME record is found instead, - the resulting name is processed as if it were the initial name. If - no MX records are found, but an A RR is found, the A RR is treated as - if it was associated with an implicit MX RR, with a preference of 0, - pointing to that host. If one or more MX RRs are found for a given - name, SMTP systems MUST NOT utilize any A RRs associated with that - name unless they are located using the MX RRs; the "implicit MX" rule - above applies only if there are no MX records present. If MX records - are present, but none of them are usable, this situation MUST be - reported as an error. - - When the lookup succeeds, the mapping can result in a list of - alternative delivery addresses rather than a single address, because - of multiple MX records, multihoming, or both. To provide reliable - mail transmission, the SMTP client MUST be able to try (and retry) - each of the relevant addresses in this list in order, until a - delivery attempt succeeds. However, there MAY also be a configurable - limit on the number of alternate addresses that can be tried. In any - case, the SMTP client SHOULD try at least two addresses. - - - -Klensin Standards Track [Page 60] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - Two types of information is used to rank the host addresses: multiple - MX records, and multihomed hosts. - - Multiple MX records contain a preference indication that MUST be used - in sorting (see below). Lower numbers are more preferred than higher - ones. If there are multiple destinations with the same preference - and there is no clear reason to favor one (e.g., by recognition of an - easily-reached address), then the sender-SMTP MUST randomize them to - spread the load across multiple mail exchangers for a specific - organization. - - The destination host (perhaps taken from the preferred MX record) may - be multihomed, in which case the domain name resolver will return a - list of alternative IP addresses. It is the responsibility of the - domain name resolver interface to have ordered this list by - decreasing preference if necessary, and SMTP MUST try them in the - order presented. - - Although the capability to try multiple alternative addresses is - required, specific installations may want to limit or disable the use - of alternative addresses. The question of whether a sender should - attempt retries using the different addresses of a multihomed host - has been controversial. The main argument for using the multiple - addresses is that it maximizes the probability of timely delivery, - and indeed sometimes the probability of any delivery; the counter- - argument is that it may result in unnecessary resource use. Note - that resource use is also strongly determined by the sending strategy - discussed in section 4.5.4.1. - - If an SMTP server receives a message with a destination for which it - is a designated Mail eXchanger, it MAY relay the message (potentially - after having rewritten the MAIL FROM and/or RCPT TO addresses), make - final delivery of the message, or hand it off using some mechanism - outside the SMTP-provided transport environment. Of course, neither - of the latter require that the list of MX records be examined - further. - - If it determines that it should relay the message without rewriting - the address, it MUST sort the MX records to determine candidates for - delivery. The records are first ordered by preference, with the - lowest-numbered records being most preferred. The relay host MUST - then inspect the list for any of the names or addresses by which it - might be known in mail transactions. If a matching record is found, - all records at that preference level and higher-numbered ones MUST be - discarded from consideration. If there are no records left at that - point, it is an error condition, and the message MUST be returned as - undeliverable. If records do remain, they SHOULD be tried, best - preference first, as described above. - - - -Klensin Standards Track [Page 61] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - -6. Problem Detection and Handling - -6.1 Reliable Delivery and Replies by Email - - When the receiver-SMTP accepts a piece of mail (by sending a "250 OK" - message in response to DATA), it is accepting responsibility for - delivering or relaying the message. It must take this responsibility - seriously. It MUST NOT lose the message for frivolous reasons, such - as because the host later crashes or because of a predictable - resource shortage. - - If there is a delivery failure after acceptance of a message, the - receiver-SMTP MUST formulate and mail a notification message. This - notification MUST be sent using a null ("<>") reverse path in the - envelope. The recipient of this notification MUST be the address - from the envelope return path (or the Return-Path: line). However, - if this address is null ("<>"), the receiver-SMTP MUST NOT send a - notification. Obviously, nothing in this section can or should - prohibit local decisions (i.e., as part of the same system - environment as the receiver-SMTP) to log or otherwise transmit - information about null address events locally if that is desired. If - the address is an explicit source route, it MUST be stripped down to - its final hop. - - For example, suppose that an error notification must be sent for a - message that arrived with: - - MAIL FROM:<@a,@b:user@d> - - The notification message MUST be sent using: - - RCPT TO: - - Some delivery failures after the message is accepted by SMTP will be - unavoidable. For example, it may be impossible for the receiving - SMTP server to validate all the delivery addresses in RCPT command(s) - due to a "soft" domain system error, because the target is a mailing - list (see earlier discussion of RCPT), or because the server is - acting as a relay and has no immediate access to the delivering - system. - - To avoid receiving duplicate messages as the result of timeouts, a - receiver-SMTP MUST seek to minimize the time required to respond to - the final . end of data indicator. See RFC 1047 [28] for - a discussion of this problem. - - - - - - -Klensin Standards Track [Page 62] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - -6.2 Loop Detection - - Simple counting of the number of "Received:" headers in a message has - proven to be an effective, although rarely optimal, method of - detecting loops in mail systems. SMTP servers using this technique - SHOULD use a large rejection threshold, normally at least 100 - Received entries. Whatever mechanisms are used, servers MUST contain - provisions for detecting and stopping trivial loops. - -6.3 Compensating for Irregularities - - Unfortunately, variations, creative interpretations, and outright - violations of Internet mail protocols do occur; some would suggest - that they occur quite frequently. The debate as to whether a well- - behaved SMTP receiver or relay should reject a malformed message, - attempt to pass it on unchanged, or attempt to repair it to increase - the odds of successful delivery (or subsequent reply) began almost - with the dawn of structured network mail and shows no signs of - abating. Advocates of rejection claim that attempted repairs are - rarely completely adequate and that rejection of bad messages is the - only way to get the offending software repaired. Advocates of - "repair" or "deliver no matter what" argue that users prefer that - mail go through it if at all possible and that there are significant - market pressures in that direction. In practice, these market - pressures may be more important to particular vendors than strict - conformance to the standards, regardless of the preference of the - actual developers. - - The problems associated with ill-formed messages were exacerbated by - the introduction of the split-UA mail reading protocols [3, 26, 5, - 21]. These protocols have encouraged the use of SMTP as a posting - protocol, and SMTP servers as relay systems for these client hosts - (which are often only intermittently connected to the Internet). - Historically, many of those client machines lacked some of the - mechanisms and information assumed by SMTP (and indeed, by the mail - format protocol [7]). Some could not keep adequate track of time; - others had no concept of time zones; still others could not identify - their own names or addresses; and, of course, none could satisfy the - assumptions that underlay RFC 822's conception of authenticated - addresses. - - In response to these weak SMTP clients, many SMTP systems now - complete messages that are delivered to them in incomplete or - incorrect form. This strategy is generally considered appropriate - when the server can identify or authenticate the client, and there - are prior agreements between them. By contrast, there is at best - great concern about fixes applied by a relay or delivery SMTP server - that has little or no knowledge of the user or client machine. - - - -Klensin Standards Track [Page 63] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - The following changes to a message being processed MAY be applied - when necessary by an originating SMTP server, or one used as the - target of SMTP as an initial posting protocol: - - - Addition of a message-id field when none appears - - - Addition of a date, time or time zone when none appears - - - Correction of addresses to proper FQDN format - - The less information the server has about the client, the less likely - these changes are to be correct and the more caution and conservatism - should be applied when considering whether or not to perform fixes - and how. These changes MUST NOT be applied by an SMTP server that - provides an intermediate relay function. - - In all cases, properly-operating clients supplying correct - information are preferred to corrections by the SMTP server. In all - cases, documentation of actions performed by the servers (in trace - fields and/or header comments) is strongly encouraged. - -7. Security Considerations - -7.1 Mail Security and Spoofing - - SMTP mail is inherently insecure in that it is feasible for even - fairly casual users to negotiate directly with receiving and relaying - SMTP servers and create messages that will trick a naive recipient - into believing that they came from somewhere else. Constructing such - a message so that the "spoofed" behavior cannot be detected by an - expert is somewhat more difficult, but not sufficiently so as to be a - deterrent to someone who is determined and knowledgeable. - Consequently, as knowledge of Internet mail increases, so does the - knowledge that SMTP mail inherently cannot be authenticated, or - integrity checks provided, at the transport level. Real mail - security lies only in end-to-end methods involving the message - bodies, such as those which use digital signatures (see [14] and, - e.g., PGP [4] or S/MIME [31]). - - Various protocol extensions and configuration options that provide - authentication at the transport level (e.g., from an SMTP client to - an SMTP server) improve somewhat on the traditional situation - described above. However, unless they are accompanied by careful - handoffs of responsibility in a carefully-designed trust environment, - they remain inherently weaker than end-to-end mechanisms which use - digitally signed messages rather than depending on the integrity of - the transport system. - - - - -Klensin Standards Track [Page 64] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - Efforts to make it more difficult for users to set envelope return - path and header "From" fields to point to valid addresses other than - their own are largely misguided: they frustrate legitimate - applications in which mail is sent by one user on behalf of another - or in which error (or normal) replies should be directed to a special - address. (Systems that provide convenient ways for users to alter - these fields on a per-message basis should attempt to establish a - primary and permanent mailbox address for the user so that Sender - fields within the message data can be generated sensibly.) - - This specification does not further address the authentication issues - associated with SMTP other than to advocate that useful functionality - not be disabled in the hope of providing some small margin of - protection against an ignorant user who is trying to fake mail. - -7.2 "Blind" Copies - - Addresses that do not appear in the message headers may appear in the - RCPT commands to an SMTP server for a number of reasons. The two - most common involve the use of a mailing address as a "list exploder" - (a single address that resolves into multiple addresses) and the - appearance of "blind copies". Especially when more than one RCPT - command is present, and in order to avoid defeating some of the - purpose of these mechanisms, SMTP clients and servers SHOULD NOT copy - the full set of RCPT command arguments into the headers, either as - part of trace headers or as informational or private-extension - headers. Since this rule is often violated in practice, and cannot - be enforced, sending SMTP systems that are aware of "bcc" use MAY - find it helpful to send each blind copy as a separate message - transaction containing only a single RCPT command. - - There is no inherent relationship between either "reverse" (from - MAIL, SAML, etc., commands) or "forward" (RCPT) addresses in the SMTP - transaction ("envelope") and the addresses in the headers. Receiving - systems SHOULD NOT attempt to deduce such relationships and use them - to alter the headers of the message for delivery. The popular - "Apparently-to" header is a violation of this principle as well as a - common source of unintended information disclosure and SHOULD NOT be - used. - -7.3 VRFY, EXPN, and Security - - As discussed in section 3.5, individual sites may want to disable - either or both of VRFY or EXPN for security reasons. As a corollary - to the above, implementations that permit this MUST NOT appear to - have verified addresses that are not, in fact, verified. If a site - - - - - -Klensin Standards Track [Page 65] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - disables these commands for security reasons, the SMTP server MUST - return a 252 response, rather than a code that could be confused with - successful or unsuccessful verification. - - Returning a 250 reply code with the address listed in the VRFY - command after having checked it only for syntax violates this rule. - Of course, an implementation that "supports" VRFY by always returning - 550 whether or not the address is valid is equally not in - conformance. - - Within the last few years, the contents of mailing lists have become - popular as an address information source for so-called "spammers." - The use of EXPN to "harvest" addresses has increased as list - administrators have installed protections against inappropriate uses - of the lists themselves. Implementations SHOULD still provide - support for EXPN, but sites SHOULD carefully evaluate the tradeoffs. - As authentication mechanisms are introduced into SMTP, some sites may - choose to make EXPN available only to authenticated requestors. - -7.4 Information Disclosure in Announcements - - There has been an ongoing debate about the tradeoffs between the - debugging advantages of announcing server type and version (and, - sometimes, even server domain name) in the greeting response or in - response to the HELP command and the disadvantages of exposing - information that might be useful in a potential hostile attack. The - utility of the debugging information is beyond doubt. Those who - argue for making it available point out that it is far better to - actually secure an SMTP server rather than hope that trying to - conceal known vulnerabilities by hiding the server's precise identity - will provide more protection. Sites are encouraged to evaluate the - tradeoff with that issue in mind; implementations are strongly - encouraged to minimally provide for making type and version - information available in some way to other network hosts. - -7.5 Information Disclosure in Trace Fields - - In some circumstances, such as when mail originates from within a LAN - whose hosts are not directly on the public Internet, trace - ("Received") fields produced in conformance with this specification - may disclose host names and similar information that would not - normally be available. This ordinarily does not pose a problem, but - sites with special concerns about name disclosure should be aware of - it. Also, the optional FOR clause should be supplied with caution or - not at all when multiple recipients are involved lest it - inadvertently disclose the identities of "blind copy" recipients to - others. - - - - -Klensin Standards Track [Page 66] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - -7.6 Information Disclosure in Message Forwarding - - As discussed in section 3.4, use of the 251 or 551 reply codes to - identify the replacement address associated with a mailbox may - inadvertently disclose sensitive information. Sites that are - concerned about those issues should ensure that they select and - configure servers appropriately. - -7.7 Scope of Operation of SMTP Servers - - It is a well-established principle that an SMTP server may refuse to - accept mail for any operational or technical reason that makes sense - to the site providing the server. However, cooperation among sites - and installations makes the Internet possible. If sites take - excessive advantage of the right to reject traffic, the ubiquity of - email availability (one of the strengths of the Internet) will be - threatened; considerable care should be taken and balance maintained - if a site decides to be selective about the traffic it will accept - and process. - - In recent years, use of the relay function through arbitrary sites - has been used as part of hostile efforts to hide the actual origins - of mail. Some sites have decided to limit the use of the relay - function to known or identifiable sources, and implementations SHOULD - provide the capability to perform this type of filtering. When mail - is rejected for these or other policy reasons, a 550 code SHOULD be - used in response to EHLO, MAIL, or RCPT as appropriate. - -8. IANA Considerations - - IANA will maintain three registries in support of this specification. - The first consists of SMTP service extensions with the associated - keywords, and, as needed, parameters and verbs. As specified in - section 2.2.2, no entry may be made in this registry that starts in - an "X". Entries may be made only for service extensions (and - associated keywords, parameters, or verbs) that are defined in - standards-track or experimental RFCs specifically approved by the - IESG for this purpose. - - The second registry consists of "tags" that identify forms of domain - literals other than those for IPv4 addresses (specified in RFC 821 - and in this document) and IPv6 addresses (specified in this - document). Additional literal types require standardization before - being used; none are anticipated at this time. - - The third, established by RFC 821 and renewed by this specification, - is a registry of link and protocol identifiers to be used with the - "via" and "with" subclauses of the time stamp ("Received: header") - - - -Klensin Standards Track [Page 67] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - described in section 4.4. Link and protocol identifiers in addition - to those specified in this document may be registered only by - standardization or by way of an RFC-documented, IESG-approved, - Experimental protocol extension. - -9. References - - [1] American National Standards Institute (formerly United States of - America Standards Institute), X3.4, 1968, "USA Code for - Information Interchange". ANSI X3.4-1968 has been replaced by - newer versions with slight modifications, but the 1968 version - remains definitive for the Internet. - - [2] Braden, R., "Requirements for Internet hosts - application and - support", STD 3, RFC 1123, October 1989. - - [3] Butler, M., Chase, D., Goldberger, J., Postel, J. and J. - Reynolds, "Post Office Protocol - version 2", RFC 937, February - 1985. - - [4] Callas, J., Donnerhacke, L., Finney, H. and R. Thayer, "OpenPGP - Message Format", RFC 2440, November 1998. - - [5] Crispin, M., "Interactive Mail Access Protocol - Version 2", RFC - 1176, August 1990. - - [6] Crispin, M., "Internet Message Access Protocol - Version 4", RFC - 2060, December 1996. - - [7] Crocker, D., "Standard for the Format of ARPA Internet Text - Messages", RFC 822, August 1982. - - [8] Crocker, D. and P. Overell, Eds., "Augmented BNF for Syntax - Specifications: ABNF", RFC 2234, November 1997. - - [9] De Winter, J., "SMTP Service Extension for Remote Message Queue - Starting", RFC 1985, August 1996. - - [10] Fajman, R., "An Extensible Message Format for Message - Disposition Notifications", RFC 2298, March 1998. - - [11] Freed, N, "Behavior of and Requirements for Internet Firewalls", - RFC 2979, October 2000. - - [12] Freed, N. and N. Borenstein, "Multipurpose Internet Mail - Extensions (MIME) Part One: Format of Internet Message Bodies", - RFC 2045, December 1996. - - - - -Klensin Standards Track [Page 68] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - [13] Freed, N., "SMTP Service Extension for Command Pipelining", RFC - 2920, September 2000. - - [14] Galvin, J., Murphy, S., Crocker, S. and N. Freed, "Security - Multiparts for MIME: Multipart/Signed and Multipart/Encrypted", - RFC 1847, October 1995. - - [15] Gellens, R. and J. Klensin, "Message Submission", RFC 2476, - December 1998. - - [16] Kille, S., "Mapping between X.400 and RFC822/MIME", RFC 2156, - January 1998. - - [17] Hinden, R and S. Deering, Eds. "IP Version 6 Addressing - Architecture", RFC 2373, July 1998. - - [18] Klensin, J., Freed, N. and K. Moore, "SMTP Service Extension for - Message Size Declaration", STD 10, RFC 1870, November 1995. - - [19] Klensin, J., Freed, N., Rose, M., Stefferud, E. and D. Crocker, - "SMTP Service Extensions", STD 10, RFC 1869, November 1995. - - [20] Klensin, J., Freed, N., Rose, M., Stefferud, E. and D. Crocker, - "SMTP Service Extension for 8bit-MIMEtransport", RFC 1652, July - 1994. - - [21] Lambert, M., "PCMAIL: A distributed mail system for personal - computers", RFC 1056, July 1988. - - [22] Mockapetris, P., "Domain names - implementation and - specification", STD 13, RFC 1035, November 1987. - - Mockapetris, P., "Domain names - concepts and facilities", STD - 13, RFC 1034, November 1987. - - [23] Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part - Three: Message Header Extensions for Non-ASCII Text", RFC 2047, - December 1996. - - [24] Moore, K., "SMTP Service Extension for Delivery Status - Notifications", RFC 1891, January 1996. - - [25] Moore, K., and G. Vaudreuil, "An Extensible Message Format for - Delivery Status Notifications", RFC 1894, January 1996. - - [26] Myers, J. and M. Rose, "Post Office Protocol - Version 3", STD - 53, RFC 1939, May 1996. - - - - -Klensin Standards Track [Page 69] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - [27] Partridge, C., "Mail routing and the domain system", RFC 974, - January 1986. - - [28] Partridge, C., "Duplicate messages and SMTP", RFC 1047, February - 1988. - - [29] Postel, J., ed., "Transmission Control Protocol - DARPA Internet - Program Protocol Specification", STD 7, RFC 793, September 1981. - - [30] Postel, J., "Simple Mail Transfer Protocol", RFC 821, August - 1982. - - [31] Ramsdell, B., Ed., "S/MIME Version 3 Message Specification", RFC - 2633, June 1999. - - [32] Resnick, P., Ed., "Internet Message Format", RFC 2822, April - 2001. - - [33] Vaudreuil, G., "SMTP Service Extensions for Transmission of - Large and Binary MIME Messages", RFC 1830, August 1995. - - [34] Vaudreuil, G., "Enhanced Mail System Status Codes", RFC 1893, - January 1996. - -10. Editor's Address - - John C. Klensin - AT&T Laboratories - 99 Bedford St - Boston, MA 02111 USA - - Phone: 617-574-3076 - EMail: klensin@research.att.com - -11. Acknowledgments - - Many people worked long and hard on the many iterations of this - document. There was wide-ranging debate in the IETF DRUMS Working - Group, both on its mailing list and in face to face discussions, - about many technical issues and the role of a revised standard for - Internet mail transport, and many contributors helped form the - wording in this specification. The hundreds of participants in the - many discussions since RFC 821 was produced are too numerous to - mention, but they all helped this document become what it is. - - - - - - - -Klensin Standards Track [Page 70] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - -APPENDICES - -A. TCP Transport Service - - The TCP connection supports the transmission of 8-bit bytes. The - SMTP data is 7-bit ASCII characters. Each character is transmitted - as an 8-bit byte with the high-order bit cleared to zero. Service - extensions may modify this rule to permit transmission of full 8-bit - data bytes as part of the message body, but not in SMTP commands or - responses. - -B. Generating SMTP Commands from RFC 822 Headers - - Some systems use RFC 822 headers (only) in a mail submission - protocol, or otherwise generate SMTP commands from RFC 822 headers - when such a message is handed to an MTA from a UA. While the MTA-UA - protocol is a private matter, not covered by any Internet Standard, - there are problems with this approach. For example, there have been - repeated problems with proper handling of "bcc" copies and - redistribution lists when information that conceptually belongs to a - mail envelopes is not separated early in processing from header - information (and kept separate). - - It is recommended that the UA provide its initial ("submission - client") MTA with an envelope separate from the message itself. - However, if the envelope is not supplied, SMTP commands SHOULD be - generated as follows: - - 1. Each recipient address from a TO, CC, or BCC header field SHOULD - be copied to a RCPT command (generating multiple message copies if - that is required for queuing or delivery). This includes any - addresses listed in a RFC 822 "group". Any BCC fields SHOULD then - be removed from the headers. Once this process is completed, the - remaining headers SHOULD be checked to verify that at least one - To:, Cc:, or Bcc: header remains. If none do, then a bcc: header - with no additional information SHOULD be inserted as specified in - [32]. - - 2. The return address in the MAIL command SHOULD, if possible, be - derived from the system's identity for the submitting (local) - user, and the "From:" header field otherwise. If there is a - system identity available, it SHOULD also be copied to the Sender - header field if it is different from the address in the From - header field. (Any Sender field that was already there SHOULD be - removed.) Systems may provide a way for submitters to override - the envelope return address, but may want to restrict its use to - privileged users. This will not prevent mail forgery, but may - lessen its incidence; see section 7.1. - - - -Klensin Standards Track [Page 71] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - When an MTA is being used in this way, it bears responsibility for - ensuring that the message being transmitted is valid. The mechanisms - for checking that validity, and for handling (or returning) messages - that are not valid at the time of arrival, are part of the MUA-MTA - interface and not covered by this specification. - - A submission protocol based on Standard RFC 822 information alone - MUST NOT be used to gateway a message from a foreign (non-SMTP) mail - system into an SMTP environment. Additional information to construct - an envelope must come from some source in the other environment, - whether supplemental headers or the foreign system's envelope. - - Attempts to gateway messages using only their header "to" and "cc" - fields have repeatedly caused mail loops and other behavior adverse - to the proper functioning of the Internet mail environment. These - problems have been especially common when the message originates from - an Internet mailing list and is distributed into the foreign - environment using envelope information. When these messages are then - processed by a header-only remailer, loops back to the Internet - environment (and the mailing list) are almost inevitable. - -C. Source Routes - - Historically, the was a reverse source routing list of - hosts and a source mailbox. The first host in the - SHOULD be the host sending the MAIL command. Similarly, the - may be a source routing lists of hosts and a - destination mailbox. However, in general, the SHOULD - contain only a mailbox and domain name, relying on the domain name - system to supply routing information if required. The use of source - routes is deprecated; while servers MUST be prepared to receive and - handle them as discussed in section 3.3 and F.2, clients SHOULD NOT - transmit them and this section was included only to provide context. - - For relay purposes, the forward-path may be a source route of the - form "@ONE,@TWO:JOE@THREE", where ONE, TWO, and THREE MUST BE fully- - qualified domain names. This form is used to emphasize the - distinction between an address and a route. The mailbox is an - absolute address, and the route is information about how to get - there. The two concepts should not be confused. - - If source routes are used, RFC 821 and the text below should be - consulted for the mechanisms for constructing and updating the - forward- and reverse-paths. - - - - - - - -Klensin Standards Track [Page 72] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - The SMTP server transforms the command arguments by moving its own - identifier (its domain name or that of any domain for which it is - acting as a mail exchanger), if it appears, from the forward-path to - the beginning of the reverse-path. - - Notice that the forward-path and reverse-path appear in the SMTP - commands and replies, but not necessarily in the message. That is, - there is no need for these paths and especially this syntax to appear - in the "To:" , "From:", "CC:", etc. fields of the message header. - Conversely, SMTP servers MUST NOT derive final message delivery - information from message header fields. - - When the list of hosts is present, it is a "reverse" source route and - indicates that the mail was relayed through each host on the list - (the first host in the list was the most recent relay). This list is - used as a source route to return non-delivery notices to the sender. - As each relay host adds itself to the beginning of the list, it MUST - use its name as known in the transport environment to which it is - relaying the mail rather than that of the transport environment from - which the mail came (if they are different). - -D. Scenarios - - This section presents complete scenarios of several types of SMTP - sessions. In the examples, "C:" indicates what is said by the SMTP - client, and "S:" indicates what is said by the SMTP server. - -D.1 A Typical SMTP Transaction Scenario - - This SMTP example shows mail sent by Smith at host bar.com, to Jones, - Green, and Brown at host foo.com. Here we assume that host bar.com - contacts host foo.com directly. The mail is accepted for Jones and - Brown. Green does not have a mailbox at host foo.com. - - S: 220 foo.com Simple Mail Transfer Service Ready - C: EHLO bar.com - S: 250-foo.com greets bar.com - S: 250-8BITMIME - S: 250-SIZE - S: 250-DSN - S: 250 HELP - C: MAIL FROM: - S: 250 OK - C: RCPT TO: - S: 250 OK - C: RCPT TO: - S: 550 No such user here - C: RCPT TO: - - - -Klensin Standards Track [Page 73] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - S: 250 OK - C: DATA - S: 354 Start mail input; end with . - C: Blah blah blah... - C: ...etc. etc. etc. - C: . - S: 250 OK - C: QUIT - S: 221 foo.com Service closing transmission channel - -D.2 Aborted SMTP Transaction Scenario - - S: 220 foo.com Simple Mail Transfer Service Ready - C: EHLO bar.com - S: 250-foo.com greets bar.com - S: 250-8BITMIME - S: 250-SIZE - S: 250-DSN - S: 250 HELP - C: MAIL FROM: - S: 250 OK - C: RCPT TO: - S: 250 OK - C: RCPT TO: - S: 550 No such user here - C: RSET - S: 250 OK - C: QUIT - S: 221 foo.com Service closing transmission channel - -D.3 Relayed Mail Scenario - - Step 1 -- Source Host to Relay Host - - S: 220 foo.com Simple Mail Transfer Service Ready - C: EHLO bar.com - S: 250-foo.com greets bar.com - S: 250-8BITMIME - S: 250-SIZE - S: 250-DSN - S: 250 HELP - C: MAIL FROM: - S: 250 OK - C: RCPT TO:<@foo.com:Jones@XYZ.COM> - S: 250 OK - C: DATA - S: 354 Start mail input; end with . - C: Date: Thu, 21 May 1998 05:33:29 -0700 - - - -Klensin Standards Track [Page 74] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - C: From: John Q. Public - C: Subject: The Next Meeting of the Board - C: To: Jones@xyz.com - C: - C: Bill: - C: The next meeting of the board of directors will be - C: on Tuesday. - C: John. - C: . - S: 250 OK - C: QUIT - S: 221 foo.com Service closing transmission channel - - Step 2 -- Relay Host to Destination Host - - S: 220 xyz.com Simple Mail Transfer Service Ready - C: EHLO foo.com - S: 250 xyz.com is on the air - C: MAIL FROM:<@foo.com:JQP@bar.com> - S: 250 OK - C: RCPT TO: - S: 250 OK - C: DATA - S: 354 Start mail input; end with . - C: Received: from bar.com by foo.com ; Thu, 21 May 1998 - C: 05:33:29 -0700 - C: Date: Thu, 21 May 1998 05:33:22 -0700 - C: From: John Q. Public - C: Subject: The Next Meeting of the Board - C: To: Jones@xyz.com - C: - C: Bill: - C: The next meeting of the board of directors will be - C: on Tuesday. - C: John. - C: . - S: 250 OK - C: QUIT - S: 221 foo.com Service closing transmission channel - -D.4 Verifying and Sending Scenario - - S: 220 foo.com Simple Mail Transfer Service Ready - C: EHLO bar.com - S: 250-foo.com greets bar.com - S: 250-8BITMIME - S: 250-SIZE - S: 250-DSN - - - -Klensin Standards Track [Page 75] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - - S: 250-VRFY - S: 250 HELP - C: VRFY Crispin - S: 250 Mark Crispin - C: SEND FROM: - S: 250 OK - C: RCPT TO: - S: 250 OK - C: DATA - S: 354 Start mail input; end with . - C: Blah blah blah... - C: ...etc. etc. etc. - C: . - S: 250 OK - C: QUIT - S: 221 foo.com Service closing transmission channel - -E. Other Gateway Issues - - In general, gateways between the Internet and other mail systems - SHOULD attempt to preserve any layering semantics across the - boundaries between the two mail systems involved. Gateway- - translation approaches that attempt to take shortcuts by mapping, - (such as envelope information from one system to the message headers - or body of another) have generally proven to be inadequate in - important ways. Systems translating between environments that do not - support both envelopes and headers and Internet mail must be written - with the understanding that some information loss is almost - inevitable. - -F. Deprecated Features of RFC 821 - - A few features of RFC 821 have proven to be problematic and SHOULD - NOT be used in Internet mail. - -F.1 TURN - - This command, described in RFC 821, raises important security issues - since, in the absence of strong authentication of the host requesting - that the client and server switch roles, it can easily be used to - divert mail from its correct destination. Its use is deprecated; - SMTP systems SHOULD NOT use it unless the server can authenticate the - client. - - - - - - - - -Klensin Standards Track [Page 76] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - -F.2 Source Routing - - RFC 821 utilized the concept of explicit source routing to get mail - from one host to another via a series of relays. The requirement to - utilize source routes in regular mail traffic was eliminated by the - introduction of the domain name system "MX" record and the last - significant justification for them was eliminated by the - introduction, in RFC 1123, of a clear requirement that addresses - following an "@" must all be fully-qualified domain names. - Consequently, the only remaining justifications for the use of source - routes are support for very old SMTP clients or MUAs and in mail - system debugging. They can, however, still be useful in the latter - circumstance and for routing mail around serious, but temporary, - problems such as problems with the relevant DNS records. - - SMTP servers MUST continue to accept source route syntax as specified - in the main body of this document and in RFC 1123. They MAY, if - necessary, ignore the routes and utilize only the target domain in - the address. If they do utilize the source route, the message MUST - be sent to the first domain shown in the address. In particular, a - server MUST NOT guess at shortcuts within the source route. - - Clients SHOULD NOT utilize explicit source routing except under - unusual circumstances, such as debugging or potentially relaying - around firewall or mail system configuration errors. - -F.3 HELO - - As discussed in sections 3.1 and 4.1.1, EHLO is strongly preferred to - HELO when the server will accept the former. Servers must continue - to accept and process HELO in order to support older clients. - -F.4 #-literals - - RFC 821 provided for specifying an Internet address as a decimal - integer host number prefixed by a pound sign, "#". In practice, that - form has been obsolete since the introduction of TCP/IP. It is - deprecated and MUST NOT be used. - -F.5 Dates and Years - - When dates are inserted into messages by SMTP clients or servers - (e.g., in trace fields), four-digit years MUST BE used. Two-digit - years are deprecated; three-digit years were never permitted in the - Internet mail system. - - - - - - -Klensin Standards Track [Page 77] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - -F.6 Sending versus Mailing - - In addition to specifying a mechanism for delivering messages to - user's mailboxes, RFC 821 provided additional, optional, commands to - deliver messages directly to the user's terminal screen. These - commands (SEND, SAML, SOML) were rarely implemented, and changes in - workstation technology and the introduction of other protocols may - have rendered them obsolete even where they are implemented. - - Clients SHOULD NOT provide SEND, SAML, or SOML as services. Servers - MAY implement them. If they are implemented by servers, the - implementation model specified in RFC 821 MUST be used and the - command names MUST be published in the response to the EHLO command. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Klensin Standards Track [Page 78] - -RFC 2821 Simple Mail Transfer Protocol April 2001 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2001). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - -Klensin Standards Track [Page 79] - diff --git a/docs/rfcs/rfc2831.Obsolete_Digest_AUTHentication_as_a_SASL_mech.txt b/docs/rfcs/rfc2831.Obsolete_Digest_AUTHentication_as_a_SASL_mech.txt new file mode 100644 index 0000000..c1a54c4 --- /dev/null +++ b/docs/rfcs/rfc2831.Obsolete_Digest_AUTHentication_as_a_SASL_mech.txt @@ -0,0 +1,1515 @@ + + + + + + +Network Working Group P. Leach +Request for Comments: 2831 Microsoft +Category: Standards Track C. Newman + Innosoft + May 2000 + + + Using Digest Authentication as a SASL Mechanism + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2000). All Rights Reserved. + +Abstract + + This specification defines how HTTP Digest Authentication [Digest] + can be used as a SASL [RFC 2222] mechanism for any protocol that has + a SASL profile. It is intended both as an improvement over CRAM-MD5 + [RFC 2195] and as a convenient way to support a single authentication + mechanism for web, mail, LDAP, and other protocols. + +Table of Contents + + 1 INTRODUCTION.....................................................2 + 1.1 CONVENTIONS AND NOTATION......................................2 + 1.2 REQUIREMENTS..................................................3 + 2 AUTHENTICATION...................................................3 + 2.1 INITIAL AUTHENTICATION........................................3 + 2.1.1 Step One...................................................3 + 2.1.2 Step Two...................................................6 + 2.1.3 Step Three................................................12 + 2.2 SUBSEQUENT AUTHENTICATION....................................12 + 2.2.1 Step one..................................................13 + 2.2.2 Step Two..................................................13 + 2.3 INTEGRITY PROTECTION.........................................13 + 2.4 CONFIDENTIALITY PROTECTION...................................14 + 3 SECURITY CONSIDERATIONS.........................................15 + 3.1 AUTHENTICATION OF CLIENTS USING DIGEST AUTHENTICATION........15 + 3.2 COMPARISON OF DIGEST WITH PLAINTEXT PASSWORDS................16 + 3.3 REPLAY ATTACKS...............................................16 + + + +Leach & Newman Standards Track [Page 1] + +RFC 2831 Digest SASL Mechanism May 2000 + + + 3.4 ONLINE DICTIONARY ATTACKS....................................16 + 3.5 OFFLINE DICTIONARY ATTACKS...................................16 + 3.6 MAN IN THE MIDDLE............................................17 + 3.7 CHOSEN PLAINTEXT ATTACKS.....................................17 + 3.8 SPOOFING BY COUNTERFEIT SERVERS..............................17 + 3.9 STORING PASSWORDS............................................17 + 3.10 MULTIPLE REALMS.............................................18 + 3.11 SUMMARY.....................................................18 + 4 EXAMPLE.........................................................18 + 5 REFERENCES......................................................20 + 6 AUTHORS' ADDRESSES..............................................21 + 7 ABNF............................................................21 + 7.1 AUGMENTED BNF................................................21 + 7.2 BASIC RULES..................................................23 + 8 SAMPLE CODE.....................................................25 + 9 FULL COPYRIGHT STATEMENT........................................27 + +1 Introduction + + This specification describes the use of HTTP Digest Access + Authentication as a SASL mechanism. The authentication type + associated with the Digest SASL mechanism is "DIGEST-MD5". + + This specification is intended to be upward compatible with the + "md5-sess" algorithm of HTTP/1.1 Digest Access Authentication + specified in [Digest]. The only difference in the "md5-sess" + algorithm is that some directives not needed in a SASL mechanism have + had their values defaulted. + + There is one new feature for use as a SASL mechanism: integrity + protection on application protocol messages after an authentication + exchange. + + Also, compared to CRAM-MD5, DIGEST-MD5 prevents chosen plaintext + attacks, and permits the use of third party authentication servers, + mutual authentication, and optimized reauthentication if a client has + recently authenticated to a server. + +1.1 Conventions and Notation + + This specification uses the same ABNF notation and lexical + conventions as HTTP/1.1 specification; see appendix A. + + Let { a, b, ... } be the concatenation of the octet strings a, b, ... + + Let H(s) be the 16 octet MD5 hash [RFC 1321] of the octet string s. + + + + + +Leach & Newman Standards Track [Page 2] + +RFC 2831 Digest SASL Mechanism May 2000 + + + Let KD(k, s) be H({k, ":", s}), i.e., the 16 octet hash of the string + k, a colon and the string s. + + Let HEX(n) be the representation of the 16 octet MD5 hash n as a + string of 32 hex digits (with alphabetic characters always in lower + case, since MD5 is case sensitive). + + Let HMAC(k, s) be the 16 octet HMAC-MD5 [RFC 2104] of the octet + string s using the octet string k as a key. + + The value of a quoted string constant as an octet string does not + include any terminating null character. + +1.2 Requirements + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [RFC 2119]. + + An implementation is not compliant if it fails to satisfy one or more + of the MUST level requirements for the protocols it implements. An + implementation that satisfies all the MUST level and all the SHOULD + level requirements for its protocols is said to be "unconditionally + compliant"; one that satisfies all the MUST level requirements but + not all the SHOULD level requirements for its protocols is said to be + "conditionally compliant." + +2 Authentication + + The following sections describe how to use Digest as a SASL + authentication mechanism. + +2.1 Initial Authentication + + If the client has not recently authenticated to the server, then it + must perform "initial authentication", as defined in this section. If + it has recently authenticated, then a more efficient form is + available, defined in the next section. + +2.1.1 Step One + + The server starts by sending a challenge. The data encoded in the + challenge contains a string formatted according to the rules for a + "digest-challenge" defined as follows: + + + + + + + +Leach & Newman Standards Track [Page 3] + +RFC 2831 Digest SASL Mechanism May 2000 + + + digest-challenge = + 1#( realm | nonce | qop-options | stale | maxbuf | charset + algorithm | cipher-opts | auth-param ) + + realm = "realm" "=" <"> realm-value <"> + realm-value = qdstr-val + nonce = "nonce" "=" <"> nonce-value <"> + nonce-value = qdstr-val + qop-options = "qop" "=" <"> qop-list <"> + qop-list = 1#qop-value + qop-value = "auth" | "auth-int" | "auth-conf" | + token + stale = "stale" "=" "true" + maxbuf = "maxbuf" "=" maxbuf-value + maxbuf-value = 1*DIGIT + charset = "charset" "=" "utf-8" + algorithm = "algorithm" "=" "md5-sess" + cipher-opts = "cipher" "=" <"> 1#cipher-value <"> + cipher-value = "3des" | "des" | "rc4-40" | "rc4" | + "rc4-56" | token + auth-param = token "=" ( token | quoted-string ) + + The meanings of the values of the directives used above are as + follows: + + realm + Mechanistically, a string which can enable users to know which + username and password to use, in case they might have different + ones for different servers. Conceptually, it is the name of a + collection of accounts that might include the user's account. This + string should contain at least the name of the host performing the + authentication and might additionally indicate the collection of + users who might have access. An example might be + "registered_users@gotham.news.example.com". This directive is + optional; if not present, the client SHOULD solicit it from the + user or be able to compute a default; a plausible default might be + the realm supplied by the user when they logged in to the client + system. Multiple realm directives are allowed, in which case the + user or client must choose one as the realm for which to supply to + username and password. + + nonce + A server-specified data string which MUST be different each time a + digest-challenge is sent as part of initial authentication. It is + recommended that this string be base64 or hexadecimal data. Note + that since the string is passed as a quoted string, the + double-quote character is not allowed unless escaped (see section + 7.2). The contents of the nonce are implementation dependent. The + + + +Leach & Newman Standards Track [Page 4] + +RFC 2831 Digest SASL Mechanism May 2000 + + + security of the implementation depends on a good choice. It is + RECOMMENDED that it contain at least 64 bits of entropy. The nonce + is opaque to the client. This directive is required and MUST + appear exactly once; if not present, or if multiple instances are + present, the client should abort the authentication exchange. + + qop-options + A quoted string of one or more tokens indicating the "quality of + protection" values supported by the server. The value "auth" + indicates authentication; the value "auth-int" indicates + authentication with integrity protection; the value "auth-conf" + indicates authentication with integrity protection and encryption. + This directive is optional; if not present it defaults to "auth". + The client MUST ignore unrecognized options; if the client + recognizes no option, it should abort the authentication exchange. + + stale + The "stale" directive is not used in initial authentication. See + the next section for its use in subsequent authentications. This + directive may appear at most once; if multiple instances are + present, the client should abort the authentication exchange. + + maxbuf + A number indicating the size of the largest buffer the server is + able to receive when using "auth-int" or "auth-conf". If this + directive is missing, the default value is 65536. This directive + may appear at most once; if multiple instances are present, the + client should abort the authentication exchange. + + charset + This directive, if present, specifies that the server supports + UTF-8 encoding for the username and password. If not present, the + username and password must be encoded in ISO 8859-1 (of which + US-ASCII is a subset). The directive is needed for backwards + compatibility with HTTP Digest, which only supports ISO 8859-1. + This directive may appear at most once; if multiple instances are + present, the client should abort the authentication exchange. + + algorithm + This directive is required for backwards compatibility with HTTP + Digest., which supports other algorithms. . This directive is + required and MUST appear exactly once; if not present, or if + multiple instances are present, the client should abort the + authentication exchange. + + + + + + + +Leach & Newman Standards Track [Page 5] + +RFC 2831 Digest SASL Mechanism May 2000 + + + cipher-opts + A list of ciphers that the server supports. This directive must be + present exactly once if "auth-conf" is offered in the + "qop-options" directive, in which case the "3des" and "des" modes + are mandatory-to-implement. The client MUST ignore unrecognized + options; if the client recognizes no option, it should abort the + authentication exchange. + + des + the Data Encryption Standard (DES) cipher [FIPS] in cipher + block chaining (CBC) mode with a 56 bit key. + + 3des + the "triple DES" cipher in CBC mode with EDE with the same key + for each E stage (aka "two keys mode") for a total key length + of 112 bits. + + rc4, rc4-40, rc4-56 + the RC4 cipher with a 128 bit, 40 bit, and 56 bit key, + respectively. + + auth-param This construct allows for future extensions; it may appear + more than once. The client MUST ignore any unrecognized + directives. + + For use as a SASL mechanism, note that the following changes are made + to "digest-challenge" from HTTP: the following Digest options (called + "directives" in HTTP terminology) are unused (i.e., MUST NOT be sent, + and MUST be ignored if received): + + opaque + domain + + The size of a digest-challenge MUST be less than 2048 bytes. + +2.1.2 Step Two + + The client makes note of the "digest-challenge" and then responds + with a string formatted and computed according to the rules for a + "digest-response" defined as follows: + + + + + + + + + + + +Leach & Newman Standards Track [Page 6] + +RFC 2831 Digest SASL Mechanism May 2000 + + + digest-response = 1#( username | realm | nonce | cnonce | + nonce-count | qop | digest-uri | response | + maxbuf | charset | cipher | authzid | + auth-param ) + + username = "username" "=" <"> username-value <"> + username-value = qdstr-val + cnonce = "cnonce" "=" <"> cnonce-value <"> + cnonce-value = qdstr-val + nonce-count = "nc" "=" nc-value + nc-value = 8LHEX + qop = "qop" "=" qop-value + digest-uri = "digest-uri" "=" <"> digest-uri-value <"> + digest-uri-value = serv-type "/" host [ "/" serv-name ] + serv-type = 1*ALPHA + host = 1*( ALPHA | DIGIT | "-" | "." ) + serv-name = host + response = "response" "=" response-value + response-value = 32LHEX + LHEX = "0" | "1" | "2" | "3" | + "4" | "5" | "6" | "7" | + "8" | "9" | "a" | "b" | + "c" | "d" | "e" | "f" + cipher = "cipher" "=" cipher-value + authzid = "authzid" "=" <"> authzid-value <"> + authzid-value = qdstr-val + + + username + The user's name in the specified realm, encoded according to the + value of the "charset" directive. This directive is required and + MUST be present exactly once; otherwise, authentication fails. + + realm + The realm containing the user's account. This directive is + required if the server provided any realms in the + "digest-challenge", in which case it may appear exactly once and + its value SHOULD be one of those realms. If the directive is + missing, "realm-value" will set to the empty string when computing + A1 (see below for details). + + nonce + The server-specified data string received in the preceding + digest-challenge. This directive is required and MUST be present + exactly once; otherwise, authentication fails. + + + + + + +Leach & Newman Standards Track [Page 7] + +RFC 2831 Digest SASL Mechanism May 2000 + + + cnonce + A client-specified data string which MUST be different each time a + digest-response is sent as part of initial authentication. The + cnonce-value is an opaque quoted string value provided by the + client and used by both client and server to avoid chosen + plaintext attacks, and to provide mutual authentication. The + security of the implementation depends on a good choice. It is + RECOMMENDED that it contain at least 64 bits of entropy. This + directive is required and MUST be present exactly once; otherwise, + authentication fails. + + nonce-count + The nc-value is the hexadecimal count of the number of requests + (including the current request) that the client has sent with the + nonce value in this request. For example, in the first request + sent in response to a given nonce value, the client sends + "nc=00000001". The purpose of this directive is to allow the + server to detect request replays by maintaining its own copy of + this count - if the same nc-value is seen twice, then the request + is a replay. See the description below of the construction of + the response value. This directive may appear at most once; if + multiple instances are present, the client should abort the + authentication exchange. + + qop + Indicates what "quality of protection" the client accepted. If + present, it may appear exactly once and its value MUST be one of + the alternatives in qop-options. If not present, it defaults to + "auth". These values affect the computation of the response. Note + that this is a single token, not a quoted list of alternatives. + + serv-type + Indicates the type of service, such as "www" for web service, + "ftp" for FTP service, "smtp" for mail delivery service, etc. The + service name as defined in the SASL profile for the protocol see + section 4 of [RFC 2222], registered in the IANA registry of + "service" elements for the GSSAPI host-based service name form + [RFC 2078]. + + host + The DNS host name or IP address for the service requested. The + DNS host name must be the fully-qualified canonical name of the + host. The DNS host name is the preferred form; see notes on server + processing of the digest-uri. + + + + + + + +Leach & Newman Standards Track [Page 8] + +RFC 2831 Digest SASL Mechanism May 2000 + + + serv-name + Indicates the name of the service if it is replicated. The service + is considered to be replicated if the client's service-location + process involves resolution using standard DNS lookup operations, + and if these operations involve DNS records (such as SRV, or MX) + which resolve one DNS name into a set of other DNS names. In this + case, the initial name used by the client is the "serv-name", and + the final name is the "host" component. For example, the incoming + mail service for "example.com" may be replicated through the use + of MX records stored in the DNS, one of which points at an SMTP + server called "mail3.example.com"; it's "serv-name" would be + "example.com", it's "host" would be "mail3.example.com". If the + service is not replicated, or the serv-name is identical to the + host, then the serv-name component MUST be omitted. + + digest-uri + Indicates the principal name of the service with which the client + wishes to connect, formed from the serv-type, host, and serv-name. + For example, the FTP service on "ftp.example.com" would have a + "digest-uri" value of "ftp/ftp.example.com"; the SMTP server from + the example above would have a "digest-uri" value of + "smtp/mail3.example.com/example.com". + + Servers SHOULD check that the supplied value is correct. This will + detect accidental connection to the incorrect server. It is also so + that clients will be trained to provide values that will work with + implementations that use a shared back-end authentication service + that can provide server authentication. + + The serv-type component should match the service being offered. The + host component should match one of the host names of the host on + which the service is running, or it's IP address. Servers SHOULD NOT + normally support the IP address form, because server authentication + by IP address is not very useful; they should only do so if the DNS + is unavailable or unreliable. The serv-name component should match + one of the service's configured service names. + + This directive may appear at most once; if multiple instances are + present, the client should abort the authentication exchange. + + Note: In the HTTP use of Digest authentication, the digest-uri is the + URI (usually a URL) of the resource requested -- hence the name of + the directive. + + response + A string of 32 hex digits computed as defined below, which proves + that the user knows a password. This directive is required and + MUST be present exactly once; otherwise, authentication fails. + + + +Leach & Newman Standards Track [Page 9] + +RFC 2831 Digest SASL Mechanism May 2000 + + + maxbuf + A number indicating the size of the largest buffer the client is + able to receive. If this directive is missing, the default value + is 65536. This directive may appear at most once; if multiple + instances are present, the server should abort the authentication + exchange. + + charset + This directive, if present, specifies that the client has used + UTF-8 encoding for the username and password. If not present, the + username and password must be encoded in ISO 8859-1 (of which + US-ASCII is a subset). The client should send this directive only + if the server has indicated it supports UTF-8. The directive is + needed for backwards compatibility with HTTP Digest, which only + supports ISO 8859-1. + + LHEX + 32 hex digits, where the alphabetic characters MUST be lower case, + because MD5 is not case insensitive. + + cipher + The cipher chosen by the client. This directive MUST appear + exactly once if "auth-conf" is negotiated; if required and not + present, authentication fails. + + authzid + The "authorization ID" as per RFC 2222, encoded in UTF-8. This + directive is optional. If present, and the authenticating user has + sufficient privilege, and the server supports it, then after + authentication the server will use this identity for making all + accesses and access checks. If the client specifies it, and the + server does not support it, then the response-value will be + incorrect, and authentication will fail. + + The size of a digest-response MUST be less than 4096 bytes. + +2.1.2.1 Response-value + + The definition of "response-value" above indicates the encoding for + its value -- 32 lower case hex characters. The following definitions + show how the value is computed. + + Although qop-value and components of digest-uri-value may be + case-insensitive, the case which the client supplies in step two is + preserved for the purpose of computing and verifying the + response-value. + + response-value = + + + +Leach & Newman Standards Track [Page 10] + +RFC 2831 Digest SASL Mechanism May 2000 + + + HEX( KD ( HEX(H(A1)), + { nonce-value, ":" nc-value, ":", + cnonce-value, ":", qop-value, ":", HEX(H(A2)) })) + + If authzid is specified, then A1 is + + + A1 = { H( { username-value, ":", realm-value, ":", passwd } ), + ":", nonce-value, ":", cnonce-value, ":", authzid-value } + + If authzid is not specified, then A1 is + + + A1 = { H( { username-value, ":", realm-value, ":", passwd } ), + ":", nonce-value, ":", cnonce-value } + + where + + passwd = *OCTET + + The "username-value", "realm-value" and "passwd" are encoded + according to the value of the "charset" directive. If "charset=UTF-8" + is present, and all the characters of either "username-value" or + "passwd" are in the ISO 8859-1 character set, then it must be + converted to ISO 8859-1 before being hashed. This is so that + authentication databases that store the hashed username, realm and + password (which is common) can be shared compatibly with HTTP, which + specifies ISO 8859-1. A sample implementation of this conversion is + in section 8. + + If the "qop" directive's value is "auth", then A2 is: + + A2 = { "AUTHENTICATE:", digest-uri-value } + + If the "qop" value is "auth-int" or "auth-conf" then A2 is: + + A2 = { "AUTHENTICATE:", digest-uri-value, + ":00000000000000000000000000000000" } + + Note that "AUTHENTICATE:" must be in upper case, and the second + string constant is a string with a colon followed by 32 zeros. + + These apparently strange values of A2 are for compatibility with + HTTP; they were arrived at by setting "Method" to "AUTHENTICATE" and + the hash of the entity body to zero in the HTTP digest calculation of + A2. + + Also, in the HTTP usage of Digest, several directives in the + + + +Leach & Newman Standards Track [Page 11] + +RFC 2831 Digest SASL Mechanism May 2000 + + + "digest-challenge" sent by the server have to be returned by the + client in the "digest-response". These are: + + opaque + algorithm + + These directives are not needed when Digest is used as a SASL + mechanism (i.e., MUST NOT be sent, and MUST be ignored if received). + +2.1.3 Step Three + + The server receives and validates the "digest-response". The server + checks that the nonce-count is "00000001". If it supports subsequent + authentication (see section 2.2), it saves the value of the nonce and + the nonce-count. It sends a message formatted as follows: + + response-auth = "rspauth" "=" response-value + + where response-value is calculated as above, using the values sent in + step two, except that if qop is "auth", then A2 is + + A2 = { ":", digest-uri-value } + + And if qop is "auth-int" or "auth-conf" then A2 is + + A2 = { ":", digest-uri-value, ":00000000000000000000000000000000" } + + Compared to its use in HTTP, the following Digest directives in the + "digest-response" are unused: + + nextnonce + qop + cnonce + nonce-count + +2.2 Subsequent Authentication + + If the client has previously authenticated to the server, and + remembers the values of username, realm, nonce, nonce-count, cnonce, + and qop that it used in that authentication, and the SASL profile for + a protocol permits an initial client response, then it MAY perform + "subsequent authentication", as defined in this section. + + + + + + + + + +Leach & Newman Standards Track [Page 12] + +RFC 2831 Digest SASL Mechanism May 2000 + + +2.2.1 Step one + + The client uses the values from the previous authentication and sends + an initial response with a string formatted and computed according to + the rules for a "digest-response", as defined above, but with a + nonce-count one greater than used in the last "digest-response". + +2.2.2 Step Two + + The server receives the "digest-response". If the server does not + support subsequent authentication, then it sends a + "digest-challenge", and authentication proceeds as in initial + authentication. If the server has no saved nonce and nonce-count from + a previous authentication, then it sends a "digest-challenge", and + authentication proceeds as in initial authentication. Otherwise, the + server validates the "digest-response", checks that the nonce-count + is one greater than that used in the previous authentication using + that nonce, and saves the new value of nonce-count. + + If the response is invalid, then the server sends a + "digest-challenge", and authentication proceeds as in initial + authentication (and should be configurable to log an authentication + failure in some sort of security audit log, since the failure may be + a symptom of an attack). The nonce-count MUST NOT be incremented in + this case: to do so would allow a denial of service attack by sending + an out-of-order nonce-count. + + If the response is valid, the server MAY choose to deem that + authentication has succeeded. However, if it has been too long since + the previous authentication, or for any other reason, the server MAY + send a new "digest-challenge" with a new value for nonce. The + challenge MAY contain a "stale" directive with value "true", which + says that the client may respond to the challenge using the password + it used in the previous response; otherwise, the client must solicit + the password anew from the user. This permits the server to make sure + that the user has presented their password recently. (The directive + name refers to the previous nonce being stale, not to the last use of + the password.) Except for the handling of "stale", after sending the + "digest-challenge" authentication proceeds as in the case of initial + authentication. + +2.3 Integrity Protection + + If the server offered "qop=auth-int" and the client responded + "qop=auth-int", then subsequent messages, up to but not including the + next subsequent authentication, between the client and the server + + + + + +Leach & Newman Standards Track [Page 13] + +RFC 2831 Digest SASL Mechanism May 2000 + + + MUST be integrity protected. Using as a base session key the value of + H(A1) as defined above the client and server calculate a pair of + message integrity keys as follows. + + The key for integrity protecting messages from client to server is: + + Kic = MD5({H(A1), + "Digest session key to client-to-server signing key magic constant"}) + + The key for integrity protecting messages from server to client is: + + Kis = MD5({H(A1), + "Digest session key to server-to-client signing key magic constant"}) + + where MD5 is as specified in [RFC 1321]. If message integrity is + negotiated, a MAC block for each message is appended to the message. + The MAC block is 16 bytes: the first 10 bytes of the HMAC-MD5 [RFC + 2104] of the message, a 2-byte message type number in network byte + order with value 1, and the 4-byte sequence number in network byte + order. The message type is to allow for future extensions such as + rekeying. + + MAC(Ki, SeqNum, msg) = (HMAC(Ki, {SeqNum, msg})[0..9], 0x0001, + SeqNum) + + where Ki is Kic for messages sent by the client and Kis for those + sent by the server. The sequence number is initialized to zero, and + incremented by one for each message sent. + + Upon receipt, MAC(Ki, SeqNum, msg) is computed and compared with the + received value; the message is discarded if they differ. + +2.4 Confidentiality Protection + + If the server sent a "cipher-opts" directive and the client responded + with a "cipher" directive, then subsequent messages between the + client and the server MUST be confidentiality protected. Using as a + base session key the value of H(A1) as defined above the client and + server calculate a pair of message integrity keys as follows. + + The key for confidentiality protecting messages from client to server + is: + + Kcc = MD5({H(A1)[0..n], + "Digest H(A1) to client-to-server sealing key magic constant"}) + + The key for confidentiality protecting messages from server to client + is: + + + +Leach & Newman Standards Track [Page 14] + +RFC 2831 Digest SASL Mechanism May 2000 + + + Kcs = MD5({H(A1)[0..n], + "Digest H(A1) to server-to-client sealing key magic constant"}) + + where MD5 is as specified in [RFC 1321]. For cipher "rc4-40" n is 5; + for "rc4-56" n is 7; for the rest n is 16. The key for the "rc-*" + ciphers is all 16 bytes of Kcc or Kcs; the key for "des" is the first + 7 bytes; the key for "3des" is the first 14 bytes. The IV for "des" + and "3des" is the last 8 bytes of Kcc or Kcs. + + If message confidentiality is negotiated, each message is encrypted + with the chosen cipher and a MAC block is appended to the message. + + The MAC block is a variable length padding prefix followed by 16 + bytes formatted as follows: the first 10 bytes of the HMAC-MD5 [RFC + 2104] of the message, a 2-byte message type number in network byte + order with value 1, and the 4-byte sequence number in network byte + order. If the blocksize of the chosen cipher is not 1 byte, the + padding prefix is one or more octets each containing the number of + padding bytes, such that total length of the encrypted part of the + message is a multiple of the blocksize. The padding and first 10 + bytes of the MAC block are encrypted along with the message. + + SEAL(Ki, Kc, SeqNum, msg) = + {CIPHER(Kc, {msg, pad, HMAC(Ki, {SeqNum, msg})[0..9])}), 0x0001, + SeqNum} + + where CIPHER is the chosen cipher, Ki and Kc are Kic and Kcc for + messages sent by the client and Kis and Kcs for those sent by the + server. The sequence number is initialized to zero, and incremented + by one for each message sent. + + Upon receipt, the message is decrypted, HMAC(Ki, {SeqNum, msg}) is + computed and compared with the received value; the message is + discarded if they differ. + +3 Security Considerations + +3.1 Authentication of Clients using Digest Authentication + + Digest Authentication does not provide a strong authentication + mechanism, when compared to public key based mechanisms, for example. + However, since it prevents chosen plaintext attacks, it is stronger + than (e.g.) CRAM-MD5, which has been proposed for use with LDAP [10], + POP and IMAP (see RFC 2195 [9]). It is intended to replace the much + weaker and even more dangerous use of plaintext passwords; however, + since it is still a password based mechanism it avoids some of the + potential deployabilty issues with public-key, OTP or similar + mechanisms. + + + +Leach & Newman Standards Track [Page 15] + +RFC 2831 Digest SASL Mechanism May 2000 + + + Digest Authentication offers no confidentiality protection beyond + protecting the actual password. All of the rest of the challenge and + response are available to an eavesdropper, including the user's name + and authentication realm. + +3.2 Comparison of Digest with Plaintext Passwords + + The greatest threat to the type of transactions for which these + protocols are used is network snooping. This kind of transaction + might involve, for example, online access to a mail service whose use + is restricted to paying subscribers. With plaintext password + authentication an eavesdropper can obtain the password of the user. + This not only permits him to access anything in the database, but, + often worse, will permit access to anything else the user protects + with the same password. + +3.3 Replay Attacks + + Replay attacks are defeated if the client or the server chooses a + fresh nonce for each authentication, as this specification requires. + +3.4 Online dictionary attacks + + If the attacker can eavesdrop, then it can test any overheard + nonce/response pairs against a (potentially very large) list of + common words. Such a list is usually much smaller than the total + number of possible passwords. The cost of computing the response for + each password on the list is paid once for each challenge. + + The server can mitigate this attack by not allowing users to select + passwords that are in a dictionary. + +3.5 Offline dictionary attacks + + If the attacker can choose the challenge, then it can precompute the + possible responses to that challenge for a list of common words. Such + a list is usually much smaller than the total number of possible + passwords. The cost of computing the response for each password on + the list is paid just once. + + Offline dictionary attacks are defeated if the client chooses a fresh + nonce for each authentication, as this specification requires. + + + + + + + + + +Leach & Newman Standards Track [Page 16] + +RFC 2831 Digest SASL Mechanism May 2000 + + +3.6 Man in the Middle + + Digest authentication is vulnerable to "man in the middle" (MITM) + attacks. Clearly, a MITM would present all the problems of + eavesdropping. But it also offers some additional opportunities to + the attacker. + + A possible man-in-the-middle attack would be to substitute a weaker + qop scheme for the one(s) sent by the server; the server will not be + able to detect this attack. For this reason, the client should always + use the strongest scheme that it understands from the choices + offered, and should never choose a scheme that does not meet its + minimum requirements. + +3.7 Chosen plaintext attacks + + A chosen plaintext attack is where a MITM or a malicious server can + arbitrarily choose the challenge that the client will use to compute + the response. The ability to choose the challenge is known to make + cryptanalysis much easier [8]. + + However, Digest does not permit the attack to choose the challenge as + long as the client chooses a fresh nonce for each authentication, as + this specification requires. + +3.8 Spoofing by Counterfeit Servers + + If a user can be led to believe that she is connecting to a host + containing information protected by a password she knows, when in + fact she is connecting to a hostile server, then the hostile server + can obtain challenge/response pairs where it was able to partly + choose the challenge. There is no known way that this can be + exploited. + +3.9 Storing passwords + + Digest authentication requires that the authenticating agent (usually + the server) store some data derived from the user's name and password + in a "password file" associated with a given realm. Normally this + might contain pairs consisting of username and H({ username-value, + ":", realm-value, ":", passwd }), which is adequate to compute H(A1) + as described above without directly exposing the user's password. + + The security implications of this are that if this password file is + compromised, then an attacker gains immediate access to documents on + the server using this realm. Unlike, say a standard UNIX password + file, this information need not be decrypted in order to access + documents in the server realm associated with this file. On the other + + + +Leach & Newman Standards Track [Page 17] + +RFC 2831 Digest SASL Mechanism May 2000 + + + hand, decryption, or more likely a brute force attack, would be + necessary to obtain the user's password. This is the reason that the + realm is part of the digested data stored in the password file. It + means that if one Digest authentication password file is compromised, + it does not automatically compromise others with the same username + and password (though it does expose them to brute force attack). + + There are two important security consequences of this. First the + password file must be protected as if it contained plaintext + passwords, because for the purpose of accessing documents in its + realm, it effectively does. + + A second consequence of this is that the realm string should be + unique among all realms that any single user is likely to use. In + particular a realm string should include the name of the host doing + the authentication. + +3.10 Multiple realms + + Use of multiple realms may mean both that compromise of a the + security database for a single realm does not compromise all + security, and that there are more things to protect in order to keep + the whole system secure. + +3.11 Summary + + By modern cryptographic standards Digest Authentication is weak, + compared to (say) public key based mechanisms. But for a large range + of purposes it is valuable as a replacement for plaintext passwords. + Its strength may vary depending on the implementation. + +4 Example + + This example shows the use of the Digest SASL mechanism with the + IMAP4 AUTHENTICATE command [RFC 2060]. + + In this example, "C:" and "S:" represent a line sent by the client or + server respectively including a CRLF at the end. Linebreaks and + indentation within a "C:" or "S:" are editorial and not part of the + protocol. The password in this example was "secret". Note that the + base64 encoding of the challenges and responses is part of the IMAP4 + AUTHENTICATE command, not part of the Digest specification itself. + + S: * OK elwood.innosoft.com PMDF IMAP4rev1 V6.0-9 + C: c CAPABILITY + S: * CAPABILITY IMAP4 IMAP4rev1 ACL LITERAL+ NAMESPACE QUOTA + UIDPLUS AUTH=CRAM-MD5 AUTH=DIGEST-MD5 AUTH=PLAIN + S: c OK Completed + + + +Leach & Newman Standards Track [Page 18] + +RFC 2831 Digest SASL Mechanism May 2000 + + + C: a AUTHENTICATE DIGEST-MD5 + S: + cmVhbG09ImVsd29vZC5pbm5vc29mdC5jb20iLG5vbmNlPSJPQTZNRzl0 + RVFHbTJoaCIscW9wPSJhdXRoIixhbGdvcml0aG09bWQ1LXNlc3MsY2hh + cnNldD11dGYtOA== + C: Y2hhcnNldD11dGYtOCx1c2VybmFtZT0iY2hyaXMiLHJlYWxtPSJlbHdvb2 + QuaW5ub3NvZnQuY29tIixub25jZT0iT0E2TUc5dEVRR20yaGgiLG5jPTAw + MDAwMDAxLGNub25jZT0iT0E2TUhYaDZWcVRyUmsiLGRpZ2VzdC11cmk9Im + ltYXAvZWx3b29kLmlubm9zb2Z0LmNvbSIscmVzcG9uc2U9ZDM4OGRhZDkw + ZDRiYmQ3NjBhMTUyMzIxZjIxNDNhZjcscW9wPWF1dGg= + S: + cnNwYXV0aD1lYTQwZjYwMzM1YzQyN2I1NTI3Yjg0ZGJhYmNkZmZmZA== + C: + S: a OK User logged in + --- + + The base64-decoded version of the SASL exchange is: + + S: realm="elwood.innosoft.com",nonce="OA6MG9tEQGm2hh",qop="auth", + algorithm=md5-sess,charset=utf-8 + C: charset=utf-8,username="chris",realm="elwood.innosoft.com", + nonce="OA6MG9tEQGm2hh",nc=00000001,cnonce="OA6MHXh6VqTrRk", + digest-uri="imap/elwood.innosoft.com", + response=d388dad90d4bbd760a152321f2143af7,qop=auth + S: rspauth=ea40f60335c427b5527b84dbabcdfffd + + The password in this example was "secret". + + This example shows the use of the Digest SASL mechanism with the + ACAP, using the same notational conventions and password as in the + previous example. Note that ACAP does not base64 encode and uses + fewer round trips that IMAP4. + + S: * ACAP (IMPLEMENTATION "Test ACAP server") (SASL "CRAM-MD5" + "DIGEST-MD5" "PLAIN") + C: a AUTHENTICATE "DIGEST-MD5" + S: + {94} + S: realm="elwood.innosoft.com",nonce="OA9BSXrbuRhWay",qop="auth", + algorithm=md5-sess,charset=utf-8 + C: {206} + C: charset=utf-8,username="chris",realm="elwood.innosoft.com", + nonce="OA9BSXrbuRhWay",nc=00000001,cnonce="OA9BSuZWMSpW8m", + digest-uri="acap/elwood.innosoft.com", + response=6084c6db3fede7352c551284490fd0fc,qop=auth + S: a OK (SASL {40} + S: rspauth=2f0b3d7c3c2e486600ef710726aa2eae) "AUTHENTICATE + Completed" + --- + + + + + +Leach & Newman Standards Track [Page 19] + +RFC 2831 Digest SASL Mechanism May 2000 + + + The server uses the values of all the directives, plus knowledge of + the users password (or the hash of the user's name, server's realm + and the user's password) to verify the computations above. If they + check, then the user has authenticated. + +5 References + + [Digest] Franks, J., et al., "HTTP Authentication: Basic and Digest + Access Authentication", RFC 2617, June 1999. + + [ISO-8859] ISO-8859. International Standard--Information Processing-- + 8-bit Single-Byte Coded Graphic Character Sets -- + Part 1: Latin alphabet No. 1, ISO-8859-1:1987. + Part 2: Latin alphabet No. 2, ISO-8859-2, 1987. + Part 3: Latin alphabet No. 3, ISO-8859-3, 1988. + Part 4: Latin alphabet No. 4, ISO-8859-4, 1988. + Part 5: Latin/Cyrillic alphabet, ISO-8859-5, 1988. + Part 6: Latin/Arabic alphabet, ISO-8859-6, 1987. + Part 7: Latin/Greek alphabet, ISO-8859-7, 1987. + Part 8: Latin/Hebrew alphabet, ISO-8859-8, 1988. + Part 9: Latin alphabet No. 5, ISO-8859-9, 1990. + + [RFC 822] Crocker, D., "Standard for The Format of ARPA Internet + Text Messages," STD 11, RFC 822, August 1982. + + [RFC 1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, + April 1992. + + [RFC 2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) + Part Three: Message Header Extensions for Non-ASCII Text", + RFC 2047, November 1996. + + [RFC 2052] Gulbrandsen, A. and P. Vixie, "A DNS RR for specifying the + location of services (DNS SRV)", RFC 2052, October 1996. + + [RFC 2060] Crispin, M., "Internet Message Access Protocol - Version + 4rev1", RFC 2060, December 1996. + + [RFC 2104] Krawczyk, H., Bellare, M. and R. Canetti, "HMAC: Keyed- + Hashing for Message Authentication", RFC 2104, February + 1997. + + [RFC 2195] Klensin, J., Catoe, R. and P. Krumviede, "IMAP/POP + AUTHorize Extension for Simple Challenge/Response", RFC + 2195, September 1997. + + + + + + +Leach & Newman Standards Track [Page 20] + +RFC 2831 Digest SASL Mechanism May 2000 + + + [RFC 2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC 2222] Myers, J., "Simple Authentication and Security Layer + (SASL)", RFC 2222, October 1997. + + [USASCII] US-ASCII. Coded Character Set - 7-Bit American Standard + Code for Information Interchange. Standard ANSI X3.4-1986, + ANSI, 1986. + +6 Authors' Addresses + + Paul Leach + Microsoft + 1 Microsoft Way + Redmond, WA 98052 + + EMail: paulle@microsoft.com + + + Chris Newman + Innosoft International, Inc. + 1050 Lakes Drive + West Covina, CA 91790 USA + + EMail: chris.newman@innosoft.com + +7 ABNF + + What follows is the definition of the notation as is used in the + HTTP/1.1 specification (RFC 2616) and the HTTP authentication + specification (RFC 2617); it is reproduced here for ease of + reference. Since it is intended that a single Digest implementation + can support both HTTP and SASL-based protocols, the same notation is + used in both to facilitate comparison and prevention of unwanted + differences. Since it is cut-and-paste from the HTTP specifications, + not all productions may be used in this specification. It is also not + quite legal ABNF; again, the errors were copied from the HTTP + specifications. + +7.1 Augmented BNF + + All of the mechanisms specified in this document are described in + both prose and an augmented Backus-Naur Form (BNF) similar to that + used by RFC 822 [RFC 822]. Implementers will need to be familiar with + the notation in order to understand this specification. + + + + + +Leach & Newman Standards Track [Page 21] + +RFC 2831 Digest SASL Mechanism May 2000 + + + The augmented BNF includes the following constructs: + + name = definition + The name of a rule is simply the name itself (without any + enclosing "<" and ">") and is separated from its definition by the + equal "=" character. White space is only significant in that + indentation of continuation lines is used to indicate a rule + definition that spans more than one line. Certain basic rules are + in uppercase, such as SP, LWS, HT, CRLF, DIGIT, ALPHA, etc. Angle + brackets are used within definitions whenever their presence will + facilitate discerning the use of rule names. + + "literal" + Quotation marks surround literal text. Unless stated otherwise, + the text is case-insensitive. + + rule1 | rule2 + Elements separated by a bar ("|") are alternatives, e.g., "yes | + no" will accept yes or no. + + (rule1 rule2) + Elements enclosed in parentheses are treated as a single element. + Thus, "(elem (foo | bar) elem)" allows the token sequences + "elem foo elem" and "elem bar elem". + + *rule + The character "*" preceding an element indicates repetition. The + full form is "*element" indicating at least and at most + occurrences of element. Default values are 0 and infinity so + that "*(element)" allows any number, including zero; "1*element" + requires at least one; and "1*2element" allows one or two. + + [rule] + Square brackets enclose optional elements; "[foo bar]" is + equivalent to "*1(foo bar)". + + N rule + Specific repetition: "(element)" is equivalent to + "*(element)"; that is, exactly occurrences of (element). + Thus 2DIGIT is a 2-digit number, and 3ALPHA is a string of three + alphabetic characters. + + #rule + A construct "#" is defined, similar to "*", for defining lists of + elements. The full form is "#element" indicating at least + and at most elements, each separated by one or more commas + (",") and OPTIONAL linear white space (LWS). This makes the usual + form of lists very easy; a rule such as + + + +Leach & Newman Standards Track [Page 22] + +RFC 2831 Digest SASL Mechanism May 2000 + + + ( *LWS element *( *LWS "," *LWS element )) + can be shown as + 1#element + Wherever this construct is used, null elements are allowed, but do + not contribute to the count of elements present. That is, + "(element), , (element) " is permitted, but counts as only two + elements. Therefore, where at least one element is required, at + least one non-null element MUST be present. Default values are 0 + and infinity so that "#element" allows any number, including zero; + "1#element" requires at least one; and "1#2element" allows one or + two. + + ; comment + A semi-colon, set off some distance to the right of rule text, + starts a comment that continues to the end of line. This is a + simple way of including useful notes in parallel with the + specifications. + + implied *LWS + The grammar described by this specification is word-based. Except + where noted otherwise, linear white space (LWS) can be included + between any two adjacent words (token or quoted-string), and + between adjacent words and separators, without changing the + interpretation of a field. At least one delimiter (LWS and/or + separators) MUST exist between any two tokens (for the definition + of "token" below), since they would otherwise be interpreted as a + single token. + +7.2 Basic Rules + + The following rules are used throughout this specification to + describe basic parsing constructs. The US-ASCII coded character set + is defined by ANSI X3.4-1986 [USASCII]. + + OCTET = + CHAR = + UPALPHA = + LOALPHA = + ALPHA = UPALPHA | LOALPHA + DIGIT = + CTL = + CR = + LF = + SP = + HT = + <"> = + CRLF = CR LF + + + +Leach & Newman Standards Track [Page 23] + +RFC 2831 Digest SASL Mechanism May 2000 + + + + All linear white space, including folding, has the same semantics as + SP. A recipient MAY replace any linear white space with a single SP + before interpreting the field value or forwarding the message + downstream. + + LWS = [CRLF] 1*( SP | HT ) + + The TEXT rule is only used for descriptive field contents and values + that are not intended to be interpreted by the message parser. Words + of *TEXT MAY contain characters from character sets other than + ISO-8859-1 [ISO 8859] only when encoded according to the rules of RFC + 2047 [RFC 2047]. + + TEXT = + + A CRLF is allowed in the definition of TEXT only as part of a header + field continuation. It is expected that the folding LWS will be + replaced with a single SP before interpretation of the TEXT value. + + Hexadecimal numeric characters are used in several protocol elements. + + HEX = "A" | "B" | "C" | "D" | "E" | "F" + | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT + + Many HTTP/1.1 header field values consist of words separated by LWS + or special characters. These special characters MUST be in a quoted + string to be used within a parameter value. + + token = 1* + separators = "(" | ")" | "<" | ">" | "@" + | "," | ";" | ":" | "\" | <"> + | "/" | "[" | "]" | "?" | "=" + | "{" | "}" | SP | HT + + A string of text is parsed as a single word if it is quoted using + double-quote marks. + + quoted-string = ( <"> qdstr-val <"> ) + qdstr-val = *( qdtext | quoted-pair ) + qdtext = > + + Note that LWS is NOT implicit between the double-quote marks (<">) + surrounding a qdstr-val and the qdstr-val; any LWS will be considered + part of the qdstr-val. This is also the case for quotation marks + surrounding any other construct. + + + + +Leach & Newman Standards Track [Page 24] + +RFC 2831 Digest SASL Mechanism May 2000 + + + The backslash character ("\") MAY be used as a single-character + quoting mechanism only within qdstr-val and comment constructs. + + quoted-pair = "\" CHAR + + The value of this construct is CHAR. Note that an effect of this rule + is that backslash must be quoted. + +8 Sample Code + + The sample implementation in [Digest] also applies to DIGEST-MD5. + + The following code implements the conversion from UTF-8 to 8859-1 if + necessary. + + /* if the string is entirely in the 8859-1 subset of UTF-8, then + * translate to 8859-1 prior to MD5 + */ + void MD5_UTF8_8859_1(MD5_CTX *ctx, const unsigned char *base, + int len) + { + const unsigned char *scan, *end; + unsigned char cbuf; + + end = base + len; + for (scan = base; scan < end; ++scan) { + if (*scan > 0xC3) break; /* abort if outside 8859-1 */ + if (*scan >= 0xC0 && *scan <= 0xC3) { + if (++scan == end || *scan < 0x80 || *scan > 0xBF) + break; + } + } + /* if we found a character outside 8859-1, don't alter string + */ + if (scan < end) { + MD5Update(ctx, base, len); + return; + } + + /* convert to 8859-1 prior to applying hash + */ + do { + for (scan = base; scan < end && *scan < 0xC0; ++scan) + ; + if (scan != base) MD5Update(ctx, base, scan - base); + if (scan + 1 >= end) break; + cbuf = ((scan[0] & 0x3) << 6) | (scan[1] & 0x3f); + MD5Update(ctx, &cbuf, 1); + + + +Leach & Newman Standards Track [Page 25] + +RFC 2831 Digest SASL Mechanism May 2000 + + + base = scan + 2; + } while (base < end); + } + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Leach & Newman Standards Track [Page 26] + +RFC 2831 Digest SASL Mechanism May 2000 + + +9 Full Copyright Statement + + Copyright (C) The Internet Society (2000). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Leach & Newman Standards Track [Page 27] + diff --git a/docs/rfcs/rfc2971.txt b/docs/rfcs/rfc2971.IMAP4_ID_extension.txt similarity index 100% rename from docs/rfcs/rfc2971.txt rename to docs/rfcs/rfc2971.IMAP4_ID_extension.txt diff --git a/docs/rfcs/rfc3028.txt b/docs/rfcs/rfc3028.Sieve_Mail_filtering_language.txt similarity index 100% rename from docs/rfcs/rfc3028.txt rename to docs/rfcs/rfc3028.Sieve_Mail_filtering_language.txt diff --git a/docs/rfcs/rfc3348.txt b/docs/rfcs/rfc3348.IMAP4_Child_Mailbox_extension.txt similarity index 100% rename from docs/rfcs/rfc3348.txt rename to docs/rfcs/rfc3348.IMAP4_Child_Mailbox_extension.txt diff --git a/docs/rfcs/rfc3501.txt b/docs/rfcs/rfc3501.IMAP4rev1.txt similarity index 100% rename from docs/rfcs/rfc3501.txt rename to docs/rfcs/rfc3501.IMAP4rev1.txt diff --git a/docs/rfcs/rfc3502.txt b/docs/rfcs/rfc3502.MULTIAPPEND_extension.txt similarity index 100% rename from docs/rfcs/rfc3502.txt rename to docs/rfcs/rfc3502.MULTIAPPEND_extension.txt diff --git a/docs/rfcs/rfc3503.txt b/docs/rfcs/rfc3503.Message_Disposition_Notification.txt similarity index 100% rename from docs/rfcs/rfc3503.txt rename to docs/rfcs/rfc3503.Message_Disposition_Notification.txt diff --git a/docs/rfcs/rfc3516.txt b/docs/rfcs/rfc3516.IMAP4_Binary_content_extension.txt similarity index 100% rename from docs/rfcs/rfc3516.txt rename to docs/rfcs/rfc3516.IMAP4_Binary_content_extension.txt diff --git a/docs/rfcs/rfc3656.txt b/docs/rfcs/rfc3656.txt deleted file mode 100644 index 6c0ab5b..0000000 --- a/docs/rfcs/rfc3656.txt +++ /dev/null @@ -1,1067 +0,0 @@ - - - - - - -Network Working Group R. Siemborski -Request for Comments: 3656 Carnegie Mellon University -Category: Experimental December 2003 - - - The Mailbox Update (MUPDATE) - Distributed Mailbox Database Protocol - -Status of this Memo - - This memo defines an Experimental Protocol for the Internet - community. It does not specify an Internet standard of any kind. - Discussion and suggestions for improvement are requested. - Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2003). All Rights Reserved. - -Abstract - - As the demand for high-performance mail delivery agents increases, it - becomes apparent that single-machine solutions are inadequate to the - task, both because of capacity limits and that the failure of the - single machine means a loss of mail delivery for all users. It is - preferable to allow many machines to share the responsibility of mail - delivery. - - The Mailbox Update (MUPDATE) protocol allows a group of Internet - Message Access Protocol (IMAP) or Post Office Protocol - Version 3 - (POP3) servers to function with a unified mailbox namespace. This - document is intended to serve as a reference guide to that protocol. - - - - - - - - - - - - - - - - - - - -Siemborski Experimental [Page 1] - -RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 3 - 2.1. Atoms . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 2.2. Strings . . . . . . . . . . . . . . . . . . . . . . . . 4 - 3. Server Responses . . . . . . . . . . . . . . . . . . . . . . 4 - 3.1. Response: OK . . . . . . . . . . . . . . . . . . . . . 5 - 3.2. Response: NO . . . . . . . . . . . . . . . . . . . . . 5 - 3.3. Response: BAD . . . . . . . . . . . . . . . . . . . . . 5 - 3.4. Response: BYE . . . . . . . . . . . . . . . . . . . . . 6 - 3.5. Response: RESERVE . . . . . . . . . . . . . . . . . . . 6 - 3.6. Response: MAILBOX . . . . . . . . . . . . . . . . . . . 6 - 3.7. Response: DELETE . . . . . . . . . . . . . . . . . . . 7 - 3.8. Server Capability Response. . . . . . . . . . . . . . . 7 - 4. Client Commands . . . . . . . . . . . . . . . . . . . . . . . 8 - 4.1. Command: ACTIVATE . . . . . . . . . . . . . . . . . . . 8 - 4.2. Command: AUTHENTICATE . . . . . . . . . . . . . . . . . 8 - 4.3. Command: DEACTIVATE . . . . . . . . . . . . . . . . . . 9 - 4.4. Command: DELETE . . . . . . . . . . . . . . . . . . . . 9 - 4.5. Command: FIND . . . . . . . . . . . . . . . . . . . . . 9 - 4.6. Command: LIST . . . . . . . . . . . . . . . . . . . . . 10 - 4.7. Command: LOGOUT . . . . . . . . . . . . . . . . . . . . 10 - 4.8. Command: NOOP . . . . . . . . . . . . . . . . . . . . . 10 - 4.9. Command: RESERVE. . . . . . . . . . . . . . . . . . . . 10 - 4.10. Command: STARTTLS . . . . . . . . . . . . . . . . . . . 11 - 4.11. Command: UPDATE . . . . . . . . . . . . . . . . . . . . 12 - 5. MUPDATE Formal Syntax . . . . . . . . . . . . . . . . . . . . 12 - 6. MUPDATE URL Scheme. . . . . . . . . . . . . . . . . . . . . . 14 - 6.1. MUPDATE URL Scheme Registration Form. . . . . . . . . . 14 - 7. Security Considerations . . . . . . . . . . . . . . . . . . . 15 - 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 - 9. Intellectual Property Rights. . . . . . . . . . . . . . . . . 16 - 10. References. . . . . . . . . . . . . . . . . . . . . . . . . . 17 - 10.1. Normative References. . . . . . . . . . . . . . . . . . 17 - 10.2. Informative References. . . . . . . . . . . . . . . . . 17 - 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18 - 12. Author's Address. . . . . . . . . . . . . . . . . . . . . . . 18 - 13. Full Copyright Statement. . . . . . . . . . . . . . . . . . . 19 - - - - - - - - - - - - -Siemborski Experimental [Page 2] - -RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 - - -1. Introduction - - In order to support an architecture where there are multiple [IMAP, - POP3] servers sharing a common mailbox database, it is necessary to - be able to provide atomic mailbox operations, as well as offer - sufficient guarantees about database consistency. - - The primary goal of the MUPDATE protocol is to be simple to implement - yet allow for database consistency between participants. - - The key words "MUST, "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", - "RECOMMENDED", and "MAY" in this document are to be interpreted as - defined in BCP 14, RFC 2119 [KEYWORDS]. - - In examples, "C:" and "S:" indicate lines sent by the client and - server respectively. - -2. Protocol Overview - - The MUPDATE protocol assumes a reliable data stream such as a TCP - network connection. IANA has registered port 3905 with a short name - of "mupdate" for this purpose. - - In the current implementation of the MUPDATE protocol there are three - types of participants: a single master server, slave (or replica) - servers, and clients. The master server maintains an authoritative - copy of the mailbox database. Slave servers connect to the MUPDATE - master server as clients, and function as replicas from the point of - view of end clients. End clients may connect to either the master or - any slave and perform searches against the database, however - operations that change the database can only be performed against the - master. For the purposes of protocol discussion we will consider a - slave's connection to the master identical to that of any other - client. - - After connection, all commands from a client to server must have an - associated unique tag which is an alphanumeric string. Commands MAY - be pipelined from the client to the server (that is, the client need - not wait for the response before sending the next command). The - server MUST execute the commands in the order they were received, - however. - - If the server supports an inactivity login timeout, it MUST be at - least 15 minutes. - - - - - - - -Siemborski Experimental [Page 3] - -RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 - - - MUPDATE uses data formats similar to those used in [ACAP]. That is, - atoms and strings. All commands and tags in the protocol are - transmitted as atoms. All other data is considered to a string, and - must be quoted or transmitted as a literal. - - Outside of a literal, both clients and servers MUST support line - lengths of at least 1024 octets (including the trailing CR and LF - characters). If a line of a longer length must be transmitted, - implementations MUST make use of literals to do so. - -2.1. Atoms - - An atom consists of one or more alphanumeric characters. Atoms MUST - be less than 15 octets in length. - -2.2. Strings - - As in [ACAP], a string may be either literal or a quoted string. A - literal is a sequence of zero or more octets (including CR and LF), - prefix-quoted with an octet count in the form of an open brace ("{"), - the number of octets, an optional plus sign to indicate that the data - follows immediately (a non-synchronized literal), a close brace - ("}"), and a CRLF sequence. If the plus sign is omitted (a - synchronized literal), then the receiving side MUST send a "+ go - ahead" response, and the sending side MUST wait for this response. - Servers MUST support literals of atleast 4096 octets. - - Strings that are sent from server to client SHOULD NOT be in the - synchronized literal format. - - A quoted string is a sequence of zero or more 7-bit characters, - excluding CR, LF, and the double quote (<">), with double quote - characters at each end. - - The empty string is represented as either "" (a quoted string with - zero characters between double quotes) or as {0} followed by CRLF (a - literal with an octet count of 0). - -3. Server Responses - - Every client command in the MUPDATE protocol may receive one or more - tagged responses from the server. Each response is preceded by the - same tag as the command that elicited the response from the server. - - - - - - - - -Siemborski Experimental [Page 4] - -RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 - - -3.1. Response: OK - - A tagged OK response indicates that the operation completed - successfully. There is a mandatory implementation-defined string - after the OK response. This response also indicates the beginning of - the streaming update mode when given in response to an UPDATE - command. - - Example: - -C: N01 NOOP -S: N01 OK "NOOP Complete" - -3.2. Response: NO - - A tagged NO response indicates that the operation was explicitly - denied by the server or otherwise failed. There is a mandatory - implementation-defined string after the NO response that SHOULD - explain the reason for denial. - - Example: - -C: A01 AUTHENTICATE "PLAIN" -S: A01 NO "PLAIN is not a supported SASL mechanism" - -3.3. Response: BAD - - A tagged BAD response indicates that the command from the client - could not be parsed or understood. There is a mandatory - implementation-defined string after the BAD response to provide - additional information about the error. Note that untagged BAD - responses are allowed if it is unclear what the tag for a given - command is (for example, if a blank line is received by the mupdate - server, it can generate an untagged BAD response). In the case of an - untagged response, the tag should be replaced with a "*". - - Example: - -C: C01 SELECT "INBOX" -S: C01 BAD "This is not an IMAP server" -C: -S: * BAD "Need Command" - - - - - - - - - -Siemborski Experimental [Page 5] - -RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 - - -3.4. Response: BYE - - A tagged BYE response indicates that the server has decided to close - the connection. There is a mandatory implementation-defined string - after the BYE response that SHOULD explain the reason for closing the - connection. The server MUST close the connection immediately after - transmitting the BYE response. - - Example: - -C: L01 LOGOUT -S: L01 BYE "User Logged Out" - -3.5. Response: RESERVE - - A tagged RESERVE response may only be given in response to a FIND, - LIST, or UPDATE command. It includes two parameters: the name of the - mailbox that is being reserved (in mUTF-7 encoding, as specified in - [IMAP]) and a location string whose contents is defined by the - clients that are using the database, though it is RECOMMENDED that - the format of this string be the hostname of the server which is - storing the mailbox. - - This response indicates that the given name is no longer available in - the namespace, though it does not indicate that the given mailbox is - available to clients at the current time. - - Example: - -S: U01 RESERVE "internet.bugtraq" "mail2.example.org" - -3.6. Response: MAILBOX - - A tagged MAILBOX response may only be given in response to a FIND, - LIST, or UPDATE command. It includes three parameters: the name of - the mailbox, a location string (as with RESERVE), and a client- - defined string that specifies the IMAP ACL [IMAP-ACL] of the mailbox. - This message indicates that the given mailbox is ready to be accessed - by clients. - - Example: - -S: U01 MAILBOX "internet.bugtraq" "mail2.example.org" "anyone rls" - - - - - - - - -Siemborski Experimental [Page 6] - -RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 - - -3.7. Response: DELETE - - A tagged DELETE response may only be given in response to an UPDATE - command, and MUST NOT be given before the OK response to the UPDATE - command is given. It contains a single parameter, that of the - mailbox that should be deleted from the slave's database. This - response indicates that the given mailbox no longer exists in the - namespace of the database, and may be given for any mailbox name, - active, reserved, or nonexistent. (Though implementations SHOULD NOT - issue DELETE responses for nonexistent mailboxes). - - Example: - -S: U01 DELETE "user.rjs3.sent-mail-jan-2002" - -3.8. Server Capability Response - - Upon connection of the client to the server, and directly following a - successful STARTTLS command, the server MUST issue a capabilities - banner, of the following format: - - The banner MUST contain a line that begins with "* AUTH" and contain - a space-separated list of SASL mechanisms that the server will accept - for authentication. The mechanism names are transmitted as atoms. - Servers MAY advertise no available mechanisms (to indicate that - STARTTLS must be completed before authentication may occur). If - STARTTLS is not supported by the server, then the line MUST contain - at least one mechanism. - - If the banner is being issued without a TLS layer, and the server - supports the STARTTLS command, the banner MUST contain the line "* - STARTTLS". If the banner is being issued under a TLS layer (or the - server does not support STARTTLS), the banner MUST NOT contain this - line. - - The last line of the banner MUST start with "* OK MUPDATE" and be - followed by four strings: the server's hostname, an implementation- - defined string giving the name of the implementation, an - implementation-defined string giving the version of the - implementation, and a string that indicates if the server is a master - or a slave. The master/slave indication MUST be either "(master)" or - an MUPDATE URL that defines where the master can be contacted. - - Any unrecognized responses before the "* OK MUPDATE" response MUST be - ignored by the client. - - - - - - -Siemborski Experimental [Page 7] - -RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 - - - Example: - -S: * AUTH KERBEROS_V4 GSSAPI -S: * STARTTLS -S: * OK MUPDATE "mupdate.example.org" "Cyrus" "v2.1.2" "(master)" - -4. Client Commands - - The following are valid commands that a client may send to the - MUPDATE server: AUTHENTICATE, ACTIVATE, DEACTIVATE, DELETE, FIND, - LIST, LOGOUT, NOOP, RESERVE, STARTTLS, and UPDATE. - - Before a successful AUTHENTICATE command has occurred, the server - MUST NOT accept any commands except for AUTHENTICATE, STARTTLS, and - LOGOUT (and SHOULD reply with a NO response for all other commands). - -4.1. Command: ACTIVATE - - The ACTIVATE command has 3 parameters: the mailbox name, its - location, and its ACL. This command MUST NOT not be issued to a - slave server. - - This command can also be used to update the ACL or location - information of a mailbox. Note that it is not a requirement for a - mailbox to be reserved (or even exist in the database) for an - ACTIVATE command to succeed, implementations MUST allow this behavior - as it facilitates synchronization of the database with the current - state of the mailboxes. - -4.2. Command: AUTHENTICATE - - The AUTHENTICATE command initiates a [SASL] negotiation session - between the client and the server. It has two parameters. The first - parameter is mandatory, and is a string indicating the desired [SASL] - mechanism. The second is a string containing an optional BASE64 - encoded (as defined in section 6.8 of [MIME]) client first send. - - All of the remaining SASL blobs that are sent MUST be sent across the - wire must be in BASE64 encoded format, and followed by a CR and LF - combination. They MUST NOT be encoded as strings. - - Clients may cancel authentication by sending a * followed by a CR and - LF. - - The [SASL] service name for the MUPDATE protocol is "mupdate". - Implementations are REQUIRED to implement the GSSAPI [SASL] - mechanism, though they SHOULD implement as many mechanisms as - possible. - - - -Siemborski Experimental [Page 8] - -RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 - - - If a security layer is negotiated, it should be used directly - following the CR and LF combination at the end of the server's OK - response (i.e., beginning with the client's next command) Only one - successful AUTHENTICATE command may be issued per session. - -4.3. Command: DEACTIVATE - - The DEACTIVATE command takes two parameters, the mailbox name and - location data. The mailbox MUST already exist and be activated on - the MUPDATE server. If the server responds OK, then the mailbox name - has been moved to the RESERVE state. If the server responds NO, then - the mailbox name has not been moved (for example, the mailbox was not - already active). Any ACL information that is known about the mailbox - MAY be lost when a DEACTIVATE succeeds. This command MUST NOT be - issued to a slave. - - Example: - -C: A01 DEACTIVATE "user.rjs3.new" "mail3.example.org!u4" -S: A01 OK "Mailbox Reserved." - -4.4. Command: DELETE - - The DELETE command takes only a single parameter, the mailbox name to - be removed from the database's namespace. The server SHOULD give a - NO response if the mailbox does not exist. This command MUST NOT be - issued to a slave server. - -4.5. Command: FIND - - The FIND command takes a single parameter, a mailbox name. The - server then responds with the current record for the given mailbox, - if any, and an OK response. - - Example (mailbox does not exist): - -C: F01 FIND "user.rjs3.xyzzy" -S: F01 OK "Search Complete" - - Example (mailbox is reserved): - -C: F01 FIND "user.rjs3" -S: F01 RESERVE "user.rjs3" "mail4.example.org" -S: F01 OK "Search Complete" - - - - - - - -Siemborski Experimental [Page 9] - -RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 - - -4.6. Command: LIST - - The LIST command is similar to running FIND across the entire - database. The LIST command takes a single optional parameter, which - is a prefix to try to match against the location field of the - records. Without the parameter, LIST returns every record in the - database. - - For each mailbox that matches, either a MAILBOX or a RESERVE response - (as applicable) is sent to the client. When all responses are - complete, an OK response is issued. - - Example: - -C: L01 LIST -S: L01 RESERVE "user.rjs3" "mail4.example.org!u2" -S: L01 MAILBOX "user.leg" "mail2.example.org!u1" "leg lrswipcda" -S: L01 OK "List Complete" -C: L02 LIST "mail4.example.org!" -S: L02 RESERVE "user.rjs3" "mail4.example.org!u2" -S: L02 OK "List Complete" - -4.7. Command: LOGOUT - - The LOGOUT command tells the server to close the connection. Its - only valid response is the BYE response. The LOGOUT command takes no - parameters. - -4.8. Command: NOOP - - The NOOP command takes no parameters. Provided the client is - authenticated, its only acceptable response is an OK. Any idle - timeouts that the server may have on the connection SHOULD be reset - upon receipt of this command. - - If this command is issued after an UPDATE command has been issued, - then the OK response also indicates that all pending database updates - have been sent to the client. That is, the slave can guarantee that - its local database is up to date as of a certain time by issuing a - NOOP and waiting for the OK. The OK MUST NOT return until all - updates that were pending at the time of the NOOP have been sent. - -4.9. Command: RESERVE - - The RESERVE command takes two parameters (just like the RESERVE - response), the mailbox name to reserve and location data. If the - server responds OK, then the mailbox name has been reserved. If the - server responds NO, then the mailbox name has not been reserved (for - - - -Siemborski Experimental [Page 10] - -RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 - - - example, another server has reserved it already). This command MUST - NOT be issued to a slave. - - The typical sequence for mailbox creation is: - -C: R01 RESERVE "user.rjs3.new" "mail3.example.org!u4" -S: R01 OK "Mailbox Reserved." - -C: A01 ACTIVATE "user.rjs3.new" "mail3.example.org!u4" "rjs3 lrswipcda" -S: A01 OK "Mailbox Activated." - -4.10. Command: STARTTLS - - The STARTTLS command requests the commencement of a [TLS] - negotiation. The negotiation begins immediately after the CRLF in - the OK response. After a client issues a STARTTLS command, it MUST - NOT issue further commands until a server response is seen and the - [TLS] negotiation is complete. - - The STARTTLS command is only valid in non-authenticated state. The - server remains in non-authenticated state, even if client credentials - are supplied during the [TLS] negotiation. The [SASL] EXTERNAL - mechanism MAY be used to authenticate once [TLS] client credentials - are successfully exchanged. Note that servers are not required to - support the EXTERNAL mechanism. - - After the [TLS] layer is established, the server MUST re-issue the - initial response banner (see Section 3.8). This is necessary to - protect against man-in-the-middle attacks which alter the - capabilities list prior to STARTTLS, as well as to advertise any new - SASL mechanisms (or other capabilities) that may be available under - the layer. The client MUST discard cached capability information and - replace it with the new information. - - After the a successful STARTTLS command, the server SHOULD return a - NO response to additional STARTTLS commands. - - Servers MAY choose to not implement STARTTLS. In this case, they - MUST NOT advertise STARTTLS in their capabilities banner, and SHOULD - return a BAD response to the STARTTLS command, if it is issued. - - Example: - -C: S01 STARTTLS -S: S01 OK "Begin TLS negotiation now" - -S: * AUTH KERBEROS_V4 GSSAPI PLAIN -S: * OK MUPDATE "mupdate.example.org" "Cyrus" "v2.1.2" "(master)" - - - -Siemborski Experimental [Page 11] - -RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 - - -4.11. Command: UPDATE - - The UPDATE command is how a slave initializes an update stream from - the master (though it is also valid to issue this command to a - slave). In response to the command, the server returns a list of all - mailboxes in its database (the same results as a parameterless LIST - command) followed by an OK response. From this point forward, - whenever an update occurs to the master database, it MUST stream the - update to the slave within 30 seconds. That is, it will send - RESERVE, MAILBOX, or DELETE responses as they are applicable. - - After a client has issued an UPDATE command, it may only issue NOOP - and LOGOUT commands for the remainder of the session. - - Example: - -C: U01 UPDATE -S: U01 MAILBOX "user.leg" "mail2.example.org!u1" "leg lrswipcda" -S: U01 MAILBOX "user.rjs3" "mail3.example.org!u4" "rjs3 lrswipcda" -S: U01 RESERVE "internet.bugtraq" "mail1.example.org!u5" "anyone lrs" -S: U01 OK "Streaming Begins" - -S: U01 RESERVE "user.leg.new" "mail2.example.org!u1" - -S: U01 MAILBOX "user.leg.new" "mail2.example.org!u1" "leg lrswipcda" - -C: N01 NOOP -S: U01 DELETE "user.leg.new" -S: N01 OK "NOOP Complete" - -5. MUPDATE Formal Syntax - - The following syntax specification uses the Augmented Backus-Naur - Form (ABNF) notation as specified in [ABNF]. This uses the ABNF core - rules as specified in Appendix A of [ABNF]. - - Except as noted otherwise, all alphabetic characters are case- - insensitive. The use of upper or lower case characters to define - token strings is for editorial clarity only. Implementations MUST - accept these strings in a case-insensitive fashion. - - Note that this specification also uses some terminals from section 8 - of [ACAP]. - - cmd-activate = "ACTIVATE" SP string SP string SP string - - cmd-authenticate = "AUTHENTICATE" SP sasl-mech [ SP string ] - - - -Siemborski Experimental [Page 12] - -RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 - - - cmd-delete = "DELETE" SP string - - cmd-find = "FIND" SP string - - cmd-list = "LIST" [ SP string ] - - cmd-logout = "LOGOUT" - - cmd-noop = "NOOP" - - cmd-reserve = "RESERVE" SP string SP string - - cmd-starttls = "STARTTLS" - - cmd-update = "UPDATE" - - command = tag SP command-type CRLF - - command-type = cmd-activate / cmd-authenticate / cmd-delete / - cmd-find / cmd-list / cmd-logout / cmd-noop / - cmd-reserve / cmd-starttls / cmd-update - - response = tag SP response-type CRLF - - response-type = rsp-ok / rsp-no / rsp-bad / rsp-bye / rsp-mailbox / - rsp-reserve / rsp-delete - - rsp-bad = "BAD" SP string - - rsp-bye = "BYE" SP string - - rsp-mailbox = "MAILBOX" SP string SP string SP string - - rsp-no = "NO" SP string - - rsp-ok = "OK" SP string - - rsp-reserve = "RESERVE" SP string SP string - - rsp-delete = "DELETE" SP string - - sasl-mech = 1*ATOM-CHAR - ; ATOM-CHAR is defined in [ACAP] - - string = quoted / literal - ; quoted and literal are defined in [ACAP] - - - - - -Siemborski Experimental [Page 13] - -RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 - - - tag = 1*ATOM-CHAR - ; ATOM-CHAR is defined in [ACAP] - -6. MUPDATE URL Scheme - - This document defines the a URL scheme for the purposes of - referencing MUPDATE resources, according to the requirements in - [RFC2717]. This includes both MUPDATE servers as a whole, along with - individual mailbox entries on a given MUPDATE server. - - There is no MIME type associated with these resources. It is - intended that a URL consumer would either retrieve the MUPDATE record - in question, or simply connect to the MUPDATE server running on the - specified host. Note that the consumer will need to have - authentication credentials for the specified host. - - The MUPDATE URL scheme is similar to the IMAP URL scheme [IMAP-URL]. - However, it only takes one of two possible forms: - - mupdate:/// - mupdate:/// - - The first form refers to a MUPDATE server as a whole, the second form - indicates both the server and a mailbox to run a FIND against once - authenticated to the server. Note that part of may include - username and authentication information along with a hostname and - port. - -6.1. MUPDATE URL Scheme Registration Form - - URL scheme name: "mupdate" - - URL scheme syntax: - - This defines the MUPDATE URL Scheme in [ABNF]. Terminals from the - BNF of IMAP URLs [IMAP-URL] are also used. - - mupdateurl = "mupdate://" iserver "/" [ enc_mailbox ] - ; iserver and enc_mailbox are as defined in [IMAP-URL] - - Character encoding considerations: - - Identical to those described in [IMAP-URL] for the appropriate - terminals. - - - - - - - -Siemborski Experimental [Page 14] - -RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 - - - Intended Usage: - - The form of the URL without an associated mailbox is intended to - designate a MUPDATE server only. If a mailbox name is included in - the URL, then the consumer is expected to execute a FIND command - for that mailbox on the specified server. - - Applications and/or protocols which use this URL scheme name: - - The protocol described in this document. - - Interoperability Considerations: - - None. - - Security Considerations: - - Users of the MUPDATE URL Scheme should review the security - considerations that are discussed in [IMAP-URL]. In particular, - the consequences of including authentication mechanism information - in a URL should be reviewed. - - Relevant Publications: - - This document and [IMAP-URL]. - - Author, Change Controller, and Contact for Further Information: - - Author of this document. - -7. Security Considerations - - While no unauthenticated users may make modifications or even perform - searches on the database, it is important to note that this - specification assumes no protections of any type for authenticated - users. - - All authenticated users have complete access to the database. For - this reason it is important to ensure that accounts that are making - use of the database are well secured. - - A more secure deployment might have all read only access go through a - slave, and only have accounts which need write access use the master. - This has the disadvantage of a marginally longer time for updates to - reach the clients. - - - - - - -Siemborski Experimental [Page 15] - -RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 - - - The protocol assumes that all authenticated users are cooperating to - maintain atomic operations. Therefore, all new mailboxes SHOULD be - RESERVEd before they are ACTIVATEd, despite the fact that the - protocol does not require this, and it is therefore possible for a - set of participants which do not obey the provided locking to create - an inconsistent database. RESERVEing the mailbox first is not - required to perform an activate because this behavior simplifies - synchronization with the actual location of the mailboxes. - -8. IANA Considerations - - The IANA has assigned TCP port number 3905 to "mupdate". - - The IANA has registered a URL scheme for the MUPDATE protocol, as - defined in section 6.1 of this document. - - IANA has registered a GSSAPI service name of "mupdate" for the - MUPDATE protocol in the registry maintained at: - - http://www.iana.org/assignments/gssapi-service-names - -9. Intellectual Property Rights - - The IETF takes no position regarding the validity or scope of any - intellectual property or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; neither does it represent that it - has made any effort to identify any such rights. Information on the - IETF's procedures with respect to rights in standards-track and - standards-related documentation can be found in BCP-11. Copies of - claims of rights made available for publication and any assurances of - licenses to be made available, or the result of an attempt made to - obtain a general license or permission for the use of such - proprietary rights by implementors or users of this specification can - be obtained from the IETF Secretariat. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights which may cover technology that may be required to practice - this standard. Please address the information to the IETF Executive - Director. - - - - - - - - - -Siemborski Experimental [Page 16] - -RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 - - -10. References - -10.1. Normative References - - [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [IMAP] Crispin, M., "Internet Message Access Protocol - Version - 4", RFC 3501, March 2003. - - [ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for - Syntax Specifications: ABNF", RFC 2234, November 1997. - - [MIME] Freed, N. and N. Bornstein, "Multipurpose Internet Mail - Extensions (MIME) Part One: Format of Internet Message - Bodies", RFC 2045, November 1996. - - [IMAP-ACL] Myers, J., "IMAP4 ACL extension", RFC 2086, January 1997. - - [SASL] Myers, J., "Simple Authentication and Security Layer - (SASL)", RFC 2222, October 1997. - - [IMAP-URL] Newman, C., "IMAP URL Scheme", RFC 2192, September 1997. - - [ACAP] Newman, C. and J. Myers, "ACAP -- Application - Configuration Access Protocol", RFC 2244, November 1997. - - [TLS] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", - RFC 2246, January 1999. - -10.2. Informative References - - [POP3] Myers, J. and M. Rose, "Post Office Protocol - Version - 3", STD 53, RFC 1939, May 1996. - - [RFC2717] Petke, R. and I. King, "Registration Procedures for URL - Scheme Names", BCP 35, RFC 2717, November 1999. - - - - - - - - - - - - - - -Siemborski Experimental [Page 17] - -RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 - - -11. Acknowledgments - - Lawrence Greenfield and Ken Murchison, for a great deal of input on - both the protocol and the text of the documents. - -12. Author's Address - - Robert Siemborski - Carnegie Mellon, Andrew Systems Group - Cyert Hall 207 - 5000 Forbes Avenue - Pittsburgh, PA 15213 - - Phone: (412) 268-7456 - EMail: rjs3+@andrew.cmu.edu - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Siemborski Experimental [Page 18] - -RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 - - -13. Full Copyright Statement - - Copyright (C) The Internet Society (2003). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assignees. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - -Siemborski Experimental [Page 19] - diff --git a/docs/rfcs/rfc3691.txt b/docs/rfcs/rfc3691.IMAP_UNSELECT_command.txt similarity index 100% rename from docs/rfcs/rfc3691.txt rename to docs/rfcs/rfc3691.IMAP_UNSELECT_command.txt diff --git a/docs/rfcs/rfc4314.txt b/docs/rfcs/rfc4314.IMAP4_ACL_extension.txt similarity index 100% rename from docs/rfcs/rfc4314.txt rename to docs/rfcs/rfc4314.IMAP4_ACL_extension.txt diff --git a/docs/rfcs/rfc4315.txt b/docs/rfcs/rfc4315.IMAP_UIDPLUS_extension.txt similarity index 100% rename from docs/rfcs/rfc4315.txt rename to docs/rfcs/rfc4315.IMAP_UIDPLUS_extension.txt diff --git a/docs/rfcs/rfc4466.txt b/docs/rfcs/rfc4466.Collected_extensions_to_IMAP4_ABNF.txt similarity index 100% rename from docs/rfcs/rfc4466.txt rename to docs/rfcs/rfc4466.Collected_extensions_to_IMAP4_ABNF.txt diff --git a/docs/rfcs/rfc4467.txt b/docs/rfcs/rfc4467.IMAP_URLAUTH_extension.txt similarity index 100% rename from docs/rfcs/rfc4467.txt rename to docs/rfcs/rfc4467.IMAP_URLAUTH_extension.txt diff --git a/docs/rfcs/rfc4469.txt b/docs/rfcs/rfc4469.IMAP_CATENATE_extension.txt similarity index 100% rename from docs/rfcs/rfc4469.txt rename to docs/rfcs/rfc4469.IMAP_CATENATE_extension.txt diff --git a/docs/rfcs/rfc4549.txt b/docs/rfcs/rfc4549.Sync_operations_for_disconnected_IMAP4_Clients.txt similarity index 100% rename from docs/rfcs/rfc4549.txt rename to docs/rfcs/rfc4549.Sync_operations_for_disconnected_IMAP4_Clients.txt diff --git a/docs/rfcs/rfc4551.txt b/docs/rfcs/rfc4551.IMAP_Conditional_STORE_or_Quick_flag_changes_resync.txt similarity index 100% rename from docs/rfcs/rfc4551.txt rename to docs/rfcs/rfc4551.IMAP_Conditional_STORE_or_Quick_flag_changes_resync.txt diff --git a/docs/rfcs/rfc4731.IMAP4_Extension_to_SEARCH_command.txt b/docs/rfcs/rfc4731.IMAP4_Extension_to_SEARCH_command.txt new file mode 100644 index 0000000..8c4869a --- /dev/null +++ b/docs/rfcs/rfc4731.IMAP4_Extension_to_SEARCH_command.txt @@ -0,0 +1,451 @@ + + + + + + +Network Working Group A. Melnikov +Request for Comments: 4731 Isode Ltd +Category: Standards Track D. Cridland + Inventure Systems Ltd + November 2006 + + + IMAP4 Extension to SEARCH Command for Controlling + What Kind of Information Is Returned + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The IETF Trust (2006). + +Abstract + + This document extends IMAP (RFC 3501) SEARCH and UID SEARCH commands + with several result options, which can control what kind of + information is returned. The following result options are defined: + minimal value, maximal value, all found messages, and number of found + messages. + +Table of Contents + + 1. Introduction ....................................................2 + 2. Conventions Used in This Document ...............................2 + 3. IMAP Protocol Changes ...........................................2 + 3.1. New SEARCH/UID SEARCH Result Options .......................2 + 3.2. Interaction with CONDSTORE extension .......................4 + 4. Formal Syntax ...................................................5 + 5. Security Considerations .........................................6 + 6. IANA Considerations .............................................6 + 7. Normative References ............................................6 + 8. Acknowledgments .................................................6 + + + + + + + + + +Melnikov & Cridland Standards Track [Page 1] + +RFC 4731 IMAP4 Extension to SEARCH November 2006 + + +1. Introduction + + [IMAPABNF] extended SEARCH and UID SEARCH commands with result + specifiers (also known as result options), which can control what + kind of information is returned. + + A server advertising the ESEARCH capability supports the following + result options: minimal value, maximal value, all found messages, + and number of found messages. These result options allow clients to + get SEARCH results in more convenient forms, while also saving + bandwidth required to transport the results, for example, by finding + the first unseen message or returning the number of unseen or deleted + messages. Also, when a single MIN or a single MAX result option is + specified, servers can optimize execution of SEARCHes. + +2. Conventions Used in This Document + + In examples, "C:" and "S:" indicate lines sent by the client and + server, respectively. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [KEYWORDS]. + +3. IMAP Protocol Changes + +3.1. New SEARCH/UID SEARCH Result Options + + The SEARCH/UID SEARCH commands are extended to allow for the + following result options: + + MIN + Return the lowest message number/UID that satisfies the SEARCH + criteria. + + If the SEARCH results in no matches, the server MUST NOT + include the MIN result option in the ESEARCH response; however, + it still MUST send the ESEARCH response. + + MAX + Return the highest message number/UID that satisfies the SEARCH + criteria. + + If the SEARCH results in no matches, the server MUST NOT + include the MAX result option in the ESEARCH response; however, + it still MUST send the ESEARCH response. + + + + + +Melnikov & Cridland Standards Track [Page 2] + +RFC 4731 IMAP4 Extension to SEARCH November 2006 + + + ALL + Return all message numbers/UIDs that satisfy the SEARCH + criteria. Unlike regular (unextended) SEARCH, the messages are + always returned using the sequence-set syntax. A sequence-set + representation may be more compact and can be used as is in a + subsequent command that accepts sequence-set. Note, the client + MUST NOT assume that messages/UIDs will be listed in any + particular order. + + If the SEARCH results in no matches, the server MUST NOT + include the ALL result option in the ESEARCH response; however, + it still MUST send the ESEARCH response. + + COUNT + Return number of the messages that satisfy the SEARCH criteria. + This result option MUST always be included in the ESEARCH + response. + + If one or more result options described above are specified, the + extended SEARCH command MUST return a single ESEARCH response + [IMAPABNF], instead of the SEARCH response. + + An extended UID SEARCH command MUST cause an ESEARCH response with + the UID indicator present. + + Note that future extensions to this document can allow servers to + return multiple ESEARCH responses for a single extended SEARCH + command. These extensions will have to describe how results from + multiple ESEARCH responses are to be amalgamated. + + If the list of result options is empty, that requests the server to + return an ESEARCH response instead of the SEARCH response. This is + equivalent to "(ALL)". + + Example: C: A282 SEARCH RETURN (MIN COUNT) FLAGGED + SINCE 1-Feb-1994 NOT FROM "Smith" + S: * ESEARCH (TAG "A282") MIN 2 COUNT 3 + S: A282 OK SEARCH completed + + Example: C: A283 SEARCH RETURN () FLAGGED + SINCE 1-Feb-1994 NOT FROM "Smith" + S: * ESEARCH (TAG "A283") ALL 2,10:11 + S: A283 OK SEARCH completed + + The following example demonstrates finding the first unseen message + as returned in the UNSEEN response code on a successful SELECT + command: + + + + +Melnikov & Cridland Standards Track [Page 3] + +RFC 4731 IMAP4 Extension to SEARCH November 2006 + + + Example: C: A284 SEARCH RETURN (MIN) UNSEEN + S: * ESEARCH (TAG "A284") MIN 4 + S: A284 OK SEARCH completed + + The following example demonstrates that if the ESEARCH UID indicator + is present, all data in the ESEARCH response is referring to UIDs; + for example, the MIN result specifier will be followed by a UID. + + Example: C: A285 UID SEARCH RETURN (MIN MAX) 1:5000 + S: * ESEARCH (TAG "A285") UID MIN 7 MAX 3800 + S: A285 OK SEARCH completed + + The following example demonstrates returning the number of deleted + messages: + + Example: C: A286 SEARCH RETURN (COUNT) DELETED + S: * ESEARCH (TAG "A286") COUNT 15 + S: A286 OK SEARCH completed + +3.2. Interaction with CONDSTORE extension + + When the server supports both the ESEARCH and the CONDSTORE + [CONDSTORE] extension, and the client requests one or more result + option described in section 3.1 together with the MODSEQ search + criterion in the same SEARCH/UID SEARCH command, then the server MUST + return the ESEARCH response containing the MODSEQ result option + (described in the following paragraph) instead of the extended SEARCH + response described in section 3.5 of [CONDSTORE]. + + If the SEARCH/UID SEARCH command contained a single MIN or MAX result + option, the MODSEQ result option contains the mod-sequence for the + found message. If the SEARCH/UID SEARCH command contained both MIN + and MAX result options and no ALL/COUNT option, the MODSEQ result + option contains the highest mod-sequence for the two returned + messages. Otherwise the MODSEQ result option contains the highest + mod-sequence for all messages being returned. + + Example: The following example demonstrates how Example 15 from + [CONDSTORE] would look in the presence of one or more result option: + + C: a1 SEARCH RETURN (MIN) MODSEQ "/flags/\\draft" + all 620162338 + S: * ESEARCH (TAG "a1") MIN 2 MODSEQ 917162488 + S: a1 OK Search complete + + C: a2 SEARCH RETURN (MAX) MODSEQ "/flags/\\draft" + all 620162338 + S: * ESEARCH (TAG "a2") MAX 23 MODSEQ 907162321 + + + +Melnikov & Cridland Standards Track [Page 4] + +RFC 4731 IMAP4 Extension to SEARCH November 2006 + + + S: a2 OK Search complete + + C: a3 SEARCH RETURN (MIN MAX) MODSEQ "/flags/\\draft" + all 620162338 + S: * ESEARCH (TAG "a3") MIN 2 MAX 23 MODSEQ 917162488 + S: a3 OK Search complete + + C: a4 SEARCH RETURN (MIN COUNT) MODSEQ "/flags/\\draft" + all 620162338 + S: * ESEARCH (TAG "a4") MIN 2 COUNT 10 MODSEQ 917162500 + S: a4 OK Search complete + +4. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [ABNF]. + + Non-terminals referenced but not defined below are as defined by + [IMAP4], [CONDSTORE], or [IMAPABNF]. + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of upper or lowercase characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. + + capability =/ "ESEARCH" + + search-return-data = "MIN" SP nz-number / + "MAX" SP nz-number / + "ALL" SP sequence-set / + "COUNT" SP number + ;; conforms to the generic + ;; search-return-data syntax defined + ;; in [IMAPABNF] + + search-return-opt = "MIN" / "MAX" / "ALL" / "COUNT" + ;; conforms to generic search-return-opt + ;; syntax defined in [IMAPABNF] + + When the CONDSTORE [CONDSTORE] IMAP extension is also supported, + the ABNF is updated as follows: + + search-return-data =/ "MODSEQ" SP mod-sequence-value + ;; mod-sequence-value is defined + ;; in [CONDSTORE] + + + + + + +Melnikov & Cridland Standards Track [Page 5] + +RFC 4731 IMAP4 Extension to SEARCH November 2006 + + +5. Security Considerations + + In the general case, the IMAP SEARCH/UID SEARCH commands can be CPU + and/or IO intensive, and are seen by some as a potential attack point + for denial of service attacks, so some sites/implementations even + disable them entirely. This is quite unfortunate, as SEARCH command + is one of the best examples demonstrating IMAP advantage over POP3. + + The ALL and COUNT return options don't change how SEARCH is working + internally; they only change how information about found messages is + returned. MIN and MAX SEARCH result options described in this + document can lighten the load on IMAP servers that choose to optimize + SEARCHes containing only one or both of them. + + It is believed that this extension doesn't raise any additional + security concerns not already discussed in [IMAP4]. + +6. IANA Considerations + + IMAP4 capabilities are registered by publishing a standards track RFC + or an IESG-approved experimental RFC. The registry is currently + located at . + + This document defines the ESEARCH IMAP capability, which IANA added + to the registry. + +7. Normative References + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [IMAP4] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [ABNF] Crocker, D. (Ed.) and P. Overell , "Augmented BNF for + Syntax Specifications: ABNF", RFC 4234, October 2005. + + [IMAPABNF] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 + ABNF", RFC 4466, April 2006.. + + [CONDSTORE] Melnikov, A. and S. Hole, "IMAP Extension for Conditional + STORE", RFC 4551, June 2006. + +8. Acknowledgments + + Thanks to Michael Wener, Arnt Gulbrandsen, Cyrus Daboo, Mark Crispin, + and Pete Maclean for comments and corrections. + + + + +Melnikov & Cridland Standards Track [Page 6] + +RFC 4731 IMAP4 Extension to SEARCH November 2006 + + +Authors' Addresses + + Alexey Melnikov + Isode Limited + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex, TW12 2BX + UK + + EMail: Alexey.Melnikov@isode.com + + + Dave A. Cridland + Inventure Systems Limited + + EMail: dave.cridland@inventuresystems.co.uk + URL: http://invsys.co.uk/dave/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Melnikov & Cridland Standards Track [Page 7] + +RFC 4731 IMAP4 Extension to SEARCH November 2006 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2006). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST, + AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT + THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY + IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR + PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + +Melnikov & Cridland Standards Track [Page 8] + diff --git a/docs/rfcs/rfc4978.IMAP_Compress_extension.txt b/docs/rfcs/rfc4978.IMAP_Compress_extension.txt new file mode 100644 index 0000000..14b56b6 --- /dev/null +++ b/docs/rfcs/rfc4978.IMAP_Compress_extension.txt @@ -0,0 +1,507 @@ + + + + + + +Network Working Group A. Gulbrandsen +Request for Comments: 4978 Oryx Mail Systems GmbH +Category: Standards Track August 2007 + + + The IMAP COMPRESS Extension + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + The COMPRESS extension allows an IMAP connection to be effectively + and efficiently compressed. + + Table of Contents + + 1. Introduction and Overview .......................................2 + 2. Conventions Used in This Document ...............................2 + 3. The COMPRESS Command ............................................3 + 4. Compression Efficiency ..........................................4 + 5. Formal Syntax ...................................................6 + 6. Security Considerations .........................................6 + 7. IANA Considerations .............................................6 + 8. Acknowledgements ................................................7 + 9. References ......................................................7 + 9.1. Normative References .......................................7 + 9.2. Informative References .....................................7 + + + + + + + + + + + + + + + + + + +Gulbrandsen Standards Track [Page 1] + +RFC 4978 The IMAP COMPRESS Extension August 2007 + + +1. Introduction and Overview + + A server which supports the COMPRESS extension indicates this with + one or more capability names consisting of "COMPRESS=" followed by a + supported compression algorithm name as described in this document. + + The goal of COMPRESS is to reduce the bandwidth usage of IMAP. + + Compared to PPP compression (see [RFC1962]) and modem-based + compression (see [MNP] and [V42BIS]), COMPRESS offers much better + compression efficiency. COMPRESS can be used together with Transport + Security Layer (TLS) [RFC4346], Simple Authentication and Security + layer (SASL) encryption, Virtual Private Networks (VPNs), etc. + Compared to TLS compression [RFC3749], COMPRESS has the following + (dis)advantages: + + - COMPRESS can be implemented easily both by IMAP servers and + clients. + + - IMAP COMPRESS benefits from an intimate knowledge of the IMAP + protocol's state machine, allowing for dynamic and aggressive + optimization of the underlying compression algorithm's parameters. + + - When the TLS layer implements compression, any protocol using that + layer can transparently benefit from that compression (e.g., SMTP + and IMAP). COMPRESS is specific to IMAP. + + In order to increase interoperation, it is desirable to have as few + different compression algorithms as possible, so this document + specifies only one. The DEFLATE algorithm (defined in [RFC1951]) is + standard, widely available and fairly efficient, so it is the only + algorithm defined by this document. + + In order to increase interoperation, IMAP servers that advertise this + extension SHOULD also advertise the TLS DEFLATE compression mechanism + as defined in [RFC3749]. IMAP clients MAY use either COMPRESS or TLS + compression, however, if the client and server support both, it is + RECOMMENDED that the client choose TLS compression. + + The extension adds one new command (COMPRESS) and no new responses. + +2. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + Formal syntax is defined by [RFC4234] as modified by [RFC3501]. + + + +Gulbrandsen Standards Track [Page 2] + +RFC 4978 The IMAP COMPRESS Extension August 2007 + + + In the examples, "C:" and "S:" indicate lines sent by the client and + server respectively. "[...]" denotes elision. + +3. The COMPRESS Command + + Arguments: Name of compression mechanism: "DEFLATE". + + Responses: None + + Result: OK The server will compress its responses and expects the + client to compress its commands. + NO Compression is already active via another layer. + BAD Command unknown, invalid or unknown argument, or COMPRESS + already active. + + The COMPRESS command instructs the server to use the named + compression mechanism ("DEFLATE" is the only one defined) for all + commands and/or responses after COMPRESS. + + The client MUST NOT send any further commands until it has seen the + result of COMPRESS. If the response was OK, the client MUST compress + starting with the first command after COMPRESS. If the server + response was BAD or NO, the client MUST NOT turn on compression. + + If the server responds NO because it knows that the same mechanism is + active already (e.g., because TLS has negotiated the same mechanism), + it MUST send COMPRESSIONACTIVE as resp-text-code (see [RFC3501], + Section 7.1), and the resp-text SHOULD say which layer compresses. + + If the server issues an OK response, the server MUST compress + starting immediately after the CRLF which ends the tagged OK + response. (Responses issued by the server before the OK response + will, of course, still be uncompressed.) If the server issues a BAD + or NO response, the server MUST NOT turn on compression. + + For DEFLATE (as for many other compression mechanisms), the + compressor can trade speed against quality. When decompressing there + isn't much of a tradeoff. Consequently, the client and server are + both free to pick the best reasonable rate of compression for the + data they send. + + When COMPRESS is combined with TLS (see [RFC4346]) or SASL (see + [RFC4422]) security layers, the sending order of the three extensions + MUST be first COMPRESS, then SASL, and finally TLS. That is, before + data is transmitted it is first compressed. Second, if a SASL + security layer has been negotiated, the compressed data is then + signed and/or encrypted accordingly. Third, if a TLS security layer + has been negotiated, the data from the previous step is signed and/or + + + +Gulbrandsen Standards Track [Page 3] + +RFC 4978 The IMAP COMPRESS Extension August 2007 + + + encrypted accordingly. When receiving data, the processing order + MUST be reversed. This ensures that before sending, data is + compressed before it is encrypted, independent of the order in which + the client issues COMPRESS, AUTHENTICATE, and STARTTLS. + + The following example illustrates how commands and responses are + compressed during a simple login sequence: + + S: * OK [CAPABILITY IMAP4REV1 STARTTLS COMPRESS=DEFLATE] + C: a starttls + S: a OK TLS active + + From this point on, everything is encrypted. + + C: b login arnt tnra + S: b OK Logged in as arnt + C: c compress deflate + S: d OK DEFLATE active + + From this point on, everything is compressed before being + encrypted. + + The following example demonstrates how a server may refuse to + compress twice: + + S: * OK [CAPABILITY IMAP4REV1 STARTTLS COMPRESS=DEFLATE] + [...] + C: c compress deflate + S: c NO [COMPRESSIONACTIVE] DEFLATE active via TLS + +4. Compression Efficiency + + This section is informative, not normative. + + IMAP poses some unusual problems for a compression layer. + + Upstream is fairly simple. Most IMAP clients send the same few + commands again and again, so any compression algorithm that can + exploit repetition works efficiently. The APPEND command is an + exception; clients that send many APPEND commands may want to + surround large literals with flushes in the same way as is + recommended for servers later in this section. + + Downstream has the unusual property that several kinds of data are + sent, confusing all dictionary-based compression algorithms. + + + + + + +Gulbrandsen Standards Track [Page 4] + +RFC 4978 The IMAP COMPRESS Extension August 2007 + + + One type is IMAP responses. These are highly compressible; zlib + using its least CPU-intensive setting compresses typical responses to + 25-40% of their original size. + + Another type is email headers. These are equally compressible, and + benefit from using the same dictionary as the IMAP responses. + + A third type is email body text. Text is usually fairly short and + includes much ASCII, so the same compression dictionary will do a + good job here, too. When multiple messages in the same thread are + read at the same time, quoted lines etc. can often be compressed + almost to zero. + + Finally, attachments (non-text email bodies) are transmitted, either + in binary form or encoded with base-64. + + When attachments are retrieved in binary form, DEFLATE may be able to + compress them, but the format of the attachment is usually not IMAP- + like, so the dictionary built while compressing IMAP does not help. + The compressor has to adapt its dictionary from IMAP to the + attachment's format, and then back. A few file formats aren't + compressible at all using deflate, e.g., .gz, .zip, and .jpg files. + + When attachments are retrieved in base-64 form, the same problems + apply, but the base-64 encoding adds another problem. 8-bit + compression algorithms such as deflate work well on 8-bit file + formats, however base-64 turns a file into something resembling 6-bit + bytes, hiding most of the 8-bit file format from the compressor. + + When using the zlib library (see [RFC1951]), the functions + deflateInit2(), deflate(), inflateInit2(), and inflate() suffice to + implement this extension. The windowBits value must be in the range + -8 to -15, or else deflateInit2() uses the wrong format. + deflateParams() can be used to improve compression rate and resource + use. The Z_FULL_FLUSH argument to deflate() can be used to clear the + dictionary (the receiving peer does not need to do anything). + + A client can improve downstream compression by implementing BINARY + (defined in [RFC3516]) and using FETCH BINARY instead of FETCH BODY. + In the author's experience, the improvement ranges from 5% to 40% + depending on the attachment being downloaded. + + A server can improve downstream compression if it hints to the + compressor that the data type is about to change strongly, e.g., by + sending a Z_FULL_FLUSH at the start and end of large non-text + literals (before and after '*CHAR8' in the definition of literal in + RFC 3501, page 86). Small literals are best left alone. A possible + boundary is 5k. + + + +Gulbrandsen Standards Track [Page 5] + +RFC 4978 The IMAP COMPRESS Extension August 2007 + + + A server can improve the CPU efficiency both of the server and the + client if it adjusts the compression level (e.g., using the + deflateParams() function in zlib) at these points, to avoid trying to + compress incompressible attachments. A very simple strategy is to + change the level to 0 at the start of a literal provided the first + two bytes are either 0x1F 0x8B (as in deflate-compressed files) or + 0xFF 0xD8 (JPEG), and to keep it at 1-5 the rest of the time. More + complex strategies are possible. + +5. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [RFC4234]. This syntax augments + the grammar specified in [RFC3501]. [RFC4234] defines SP and + [RFC3501] defines command-auth, capability, and resp-text-code. + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of upper or lower case characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. + + command-auth =/ compress + + compress = "COMPRESS" SP algorithm + + capability =/ "COMPRESS=" algorithm + ;; multiple COMPRESS capabilities allowed + + algorithm = "DEFLATE" + + resp-text-code =/ "COMPRESSIONACTIVE" + + Note that due the syntax of capability names, future algorithm names + must be atoms. + +6. Security Considerations + + As for TLS compression [RFC3749]. + +7. IANA Considerations + + The IANA has added COMPRESS=DEFLATE to the list of IMAP capabilities. + + + + + + + + + +Gulbrandsen Standards Track [Page 6] + +RFC 4978 The IMAP COMPRESS Extension August 2007 + + +8. Acknowledgements + + Eric Burger, Dave Cridland, Tony Finch, Ned Freed, Philip Guenther, + Randall Gellens, Tony Hansen, Cullen Jennings, Stephane Maes, Alexey + Melnikov, Lyndon Nerenberg, and Zoltan Ordogh have all helped with + this document. + + The author would also like to thank various people in the rooms at + meetings, whose help is real, but not reflected in the author's + mailbox. + +9. References + +9.1. Normative References + + [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification + version 1.3", RFC 1951, May 1996. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 4234, October 2005. + +9.2. Informative References + + [RFC1962] Rand, D., "The PPP Compression Control Protocol (CCP)", + RFC 1962, June 1996. + + [RFC3516] Nerenberg, L., "IMAP4 Binary Content Extension", RFC 3516, + April 2003. + + [RFC3749] Hollenbeck, S., "Transport Layer Security Protocol + Compression Methods", RFC 3749, May 2004. + + [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol Version 1.1", RFC 4346, April 2006. + + [RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication and + Security Layer (SASL)", RFC 4422, June 2006. + + [V42BIS] ITU, "V.42bis: Data compression procedures for data + circuit-terminating equipment (DCE) using error correction + procedures", http://www.itu.int/rec/T-REC-V.42bis, January + 1990. + + + +Gulbrandsen Standards Track [Page 7] + +RFC 4978 The IMAP COMPRESS Extension August 2007 + + + [MNP] Gilbert Held, "The Complete Modem Reference", Second + Edition, Wiley Professional Computing, ISBN 0-471-00852-4, + May 1994. + +Author's Address + + Arnt Gulbrandsen + Oryx Mail Systems GmbH + Schweppermannstr. 8 + D-81671 Muenchen + Germany + + Fax: +49 89 4502 9758 + EMail: arnt@oryx.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Gulbrandsen Standards Track [Page 8] + +RFC 4978 The IMAP COMPRESS Extension August 2007 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2007). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Gulbrandsen Standards Track [Page 9] + diff --git a/docs/rfcs/rfc5032.IMAP_WITHIN_Search_extension.txt b/docs/rfcs/rfc5032.IMAP_WITHIN_Search_extension.txt new file mode 100644 index 0000000..f8e4895 --- /dev/null +++ b/docs/rfcs/rfc5032.IMAP_WITHIN_Search_extension.txt @@ -0,0 +1,283 @@ + + + + + + +Network Working Group E. Burger, Ed. +Request for Comments: 5032 BEA Systems, Inc. +Updates: 3501 September 2007 +Category: Standards Track + + + WITHIN Search Extension to the IMAP Protocol + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + This document describes the WITHIN extension to IMAP SEARCH. IMAP + SEARCH returns messages whose internal date is within or outside a + specified interval. The mechanism described here, OLDER and YOUNGER, + differs from BEFORE and SINCE in that the client specifies an + interval, rather than a date. WITHIN is useful for persistent + searches where either the device does not have the capacity to + perform the search at regular intervals or the network is of limited + bandwidth and thus there is a desire to reduce network traffic from + sending repeated requests and redundant responses. + +1. Introduction + + This extension exposes two new search keys, OLDER and YOUNGER, each + of which takes a non-zero integer argument corresponding to a time + interval in seconds. The server calculates the time of interest by + subtracting the time interval the client presents from the current + date and time of the server. The server then either returns messages + older or younger than the resultant time and date, depending on the + search key used. + +1.1. Conventions Used in This Document + + In examples, "C:" and "S:" indicate lines sent by the client and + server, respectively. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [RFC2119]. + + + + + +Burger Standards Track [Page 1] + +RFC 5032 Search Within September 2007 + + + When describing the general syntax, we omit some definitions, as RFC + 3501 [RFC3501] defines them. + +2. Protocol Operation + + An IMAP4 server that supports the capability described here MUST + return "WITHIN" as one of the server supported capabilities in the + CAPABILITY command. + + For both the OLDER and YOUNGER search keys, the server calculates a + target date and time by subtracting the interval, specified in + seconds, from the current date and time of the server. The server + then compares the target time with the INTERNALDATE of the message, + as specified in IMAP [RFC3501]. For OLDER, messages match if the + INTERNALDATE is less recent than or equal to the target time. For + YOUNGER, messages match if the INTERNALDATE is more recent than or + equal to the target time. + + Both OLDER and YOUNGER searches always result in exact matching, to + the resolution of a second. However, if one is doing a dynamic + evaluation, for example, in a context [CONTEXT], one needs to be + aware that the server might perform the evaluation periodically. + Thus, the server may delay the updates. Clients MUST be aware that + dynamic search results may not reflect the current state of the + mailbox. If the client needs a search result that reflects the + current state of the mailbox, we RECOMMEND that the client issue a + new search. + +3. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation. Elements not defined here can be found in the + formal syntax of ABNF [RFC4234] and IMAP [RFC3501]. + + This document extends RFC 3501 [RFC3501] with two new search keys: + OLDER and YOUNGER . + + search-key =/ ( "OLDER" / "YOUNGER" ) SP nz-number + ; search-key defined in RFC 3501 + +4. Example + + C: a1 SEARCH UNSEEN YOUNGER 259200 + S: a1 * SEARCH 4 8 15 16 23 42 + + Search for all unseen messages within the past 3 days, or 259200 + seconds, according to the server's current time. + + + + +Burger Standards Track [Page 2] + +RFC 5032 Search Within September 2007 + + +5. Security Considerations + + The WITHIN extension does not raise any security considerations that + are not present in the base protocol. Considerations are the same as + for IMAP [RFC3501]. + +6. IANA Considerations + + Per the IMAP RFC [RFC3501], registration of a new IMAP capability in + the IMAP Capability registry requires the publication of a standards- + track RFC or an IESG approved experimental RFC. The registry is + currently located at + . This + standards-track document defines the WITHIN IMAP capability. IANA + has added this extension to the IANA IMAP Capability registry. + +7. References + +7.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", RFC 2119, BCP 14, March 1997. + + [RFC3501] Crispin, M., "Internet Message Access Protocol - Version + 4rev1", RFC 3501, March 2003. + + [RFC4234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 4234, October 2005. + +7.2. Informative References + + [CONTEXT] Melnikov, D. and C. King, "Contexts for IMAP4", Work + in Progress, May 2006. + + + + + + + + + + + + + + + + + + +Burger Standards Track [Page 3] + +RFC 5032 Search Within September 2007 + + +Appendix A. Contributors + + Stephane Maes and Ray Cromwell wrote the original version of this + document as part of P-IMAP, as well as the first versions for the + IETF. From an attribution perspective, they are clearly authors. + +Appendix B. Acknowledgements + + The authors want to thank all who have contributed key insight and + who have extensively reviewed and discussed the concepts of LPSEARCH. + They also thank the authors of its early introduction in P-IMAP. + + We also want to give a special thanks to Arnt Gilbrandsen, Ken + Murchison, Zoltan Ordogh, and most especially Dave Cridland for their + review and suggestions. A special thank you goes to Alexey Melnikov + for his choice submission of text. + +Author's Address + + Eric W. Burger (editor) + BEA Systems, Inc. + USA + + EMail: eric.burger@bea.com + URI: http://www.standardstrack.com + + + + + + + + + + + + + + + + + + + + + + + + + + +Burger Standards Track [Page 4] + +RFC 5032 Search Within September 2007 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2007). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Burger Standards Track [Page 5] + diff --git a/docs/rfcs/rfc5161.IMAP_ENABLE_extension.txt b/docs/rfcs/rfc5161.IMAP_ENABLE_extension.txt new file mode 100644 index 0000000..13bbbf7 --- /dev/null +++ b/docs/rfcs/rfc5161.IMAP_ENABLE_extension.txt @@ -0,0 +1,395 @@ + + + + + + +Network Working Group A. Gulbrandsen, Ed. +Request for Comments: 5161 Oryx Mail Systems GmbH +Category: Standards Track A. Melnikov, Ed. + Isode Limited + March 2008 + + + The IMAP ENABLE Extension + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + Most IMAP extensions are used by the client when it wants to and the + server supports it. However, a few extensions require the server to + know whether a client supports that extension. The ENABLE extension + allows an IMAP client to say which extensions it supports. + +1. Overview + + Several IMAP extensions allow the server to return unsolicited + responses specific to these extensions in certain circumstances. + However, servers cannot send those unsolicited responses until they + know that the clients support such extensions and thus won't choke on + the extension response data. + + Up until now, extensions have typically stated that a server cannot + send the unsolicited responses until after the client has used a + command with the extension data (i.e., at that point the server knows + the client is aware of the extension). CONDSTORE ([RFC4551]), + ANNOTATE ([ANNOTATE]), and some extensions under consideration at the + moment use various commands to enable server extensions. For + example, CONDSTORE uses a SELECT or FETCH parameter, and ANNOTATE + uses a side effect of FETCH. + + The ENABLE extension provides an explicit indication from the client + that it supports particular extensions. This is done using a new + ENABLE command. + + An IMAP server that supports ENABLE advertises this by including the + word ENABLE in its capability list. + + + + +Gulbrandsen & Melnikov Standards Track [Page 1] + +RFC 5161 The IMAP ENABLE Extension March 2008 + + + Most IMAP extensions do not require the client to enable the + extension in any way. + +2. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + Formal syntax is defined by [RFC5234] and [RFC3501]. + + Example lines prefaced by "C:" are sent by the client and ones + prefaced by "S:" by the server. The five characters [...] means that + something has been elided. + +3. Protocol Changes + +3.1. The ENABLE Command + + Arguments: capability names + + Result: OK: Relevant capabilities enabled + BAD: No arguments, or syntax error in an argument + + The ENABLE command takes a list of capability names, and requests the + server to enable the named extensions. Once enabled using ENABLE, + each extension remains active until the IMAP connection is closed. + For each argument, the server does the following: + + - If the argument is not an extension known to the server, the server + MUST ignore the argument. + + - If the argument is an extension known to the server, and it is not + specifically permitted to be enabled using ENABLE, the server MUST + ignore the argument. (Note that knowing about an extension doesn't + necessarily imply supporting that extension.) + + - If the argument is an extension that is supported by the server and + that needs to be enabled, the server MUST enable the extension for + the duration of the connection. At present, this applies only to + CONDSTORE ([RFC4551]). Note that once an extension is enabled, + there is no way to disable it. + + If the ENABLE command is successful, the server MUST send an untagged + ENABLED response (see Section 3.2). + + + + + + +Gulbrandsen & Melnikov Standards Track [Page 2] + +RFC 5161 The IMAP ENABLE Extension March 2008 + + + Clients SHOULD only include extensions that need to be enabled by the + server. At the time of publication, CONDSTORE is the only such + extension (i.e., ENABLE CONDSTORE is an additional "CONDSTORE + enabling command" as defined in [RFC4551]). Future RFCs may add to + this list. + + The ENABLE command is only valid in the authenticated state (see + [RFC3501]), before any mailbox is selected. Clients MUST NOT issue + ENABLE once they SELECT/EXAMINE a mailbox; however, server + implementations don't have to check that no mailbox is selected or + was previously selected during the duration of a connection. + + The ENABLE command can be issued multiple times in a session. It is + additive; i.e., "ENABLE a b", followed by "ENABLE c" is the same as a + single command "ENABLE a b c". When multiple ENABLE commands are + issued, each corresponding ENABLED response SHOULD only contain + extensions enabled by the corresponding ENABLE command. + + There are no limitations on pipelining ENABLE. For example, it is + possible to send ENABLE and then immediately SELECT, or a LOGIN + immediately followed by ENABLE. + + The server MUST NOT change the CAPABILITY list as a result of + executing ENABLE; i.e., a CAPABILITY command issued right after an + ENABLE command MUST list the same capabilities as a CAPABILITY + command issued before the ENABLE command. This is demonstrated in + the following example: + + C: t1 CAPABILITY + S: * CAPABILITY IMAP4rev1 ID LITERAL+ ENABLE X-GOOD-IDEA + S: t1 OK foo + C: t2 ENABLE CONDSTORE X-GOOD-IDEA + S: * ENABLED X-GOOD-IDEA + S: t2 OK foo + C: t3 CAPABILITY + S: * CAPABILITY IMAP4rev1 ID LITERAL+ ENABLE X-GOOD-IDEA + S: t3 OK foo again + + In the following example, the client enables CONDSTORE: + + C: a1 ENABLE CONDSTORE + S: * ENABLED CONDSTORE + S: a1 OK Conditional Store enabled + + + + + + + + +Gulbrandsen & Melnikov Standards Track [Page 3] + +RFC 5161 The IMAP ENABLE Extension March 2008 + + +3.2. The ENABLED Response + + Contents: capability listing + + The ENABLED response occurs as a result of an ENABLE command. The + capability listing contains a space-separated listing of capability + names that the server supports and that were successfully enabled. + The ENABLED response may contain no capabilities, which means that no + extensions listed by the client were successfully enabled. + +3.3. Note to Designers of Extensions That May Use the ENABLE Command + + Designers of IMAP extensions are discouraged from creating extensions + that require ENABLE unless there is no good alternative design. + Specifically, extensions that cause potentially incompatible behavior + changes to deployed server responses (and thus benefit from ENABLE) + have a higher complexity cost than extensions that do not. + +4. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [RFC5234] including the core + rules in Appendix B.1. [RFC3501] defines the non-terminals + "capability" and "command-any". + + Except as noted otherwise, all alphabetic characters are + case-insensitive. The use of upper or lower case characters to + define token strings is for editorial clarity only. Implementations + MUST accept these strings in a case-insensitive fashion. + + capability =/ "ENABLE" + + command-any =/ "ENABLE" 1*(SP capability) + + response-data =/ "*" SP enable-data CRLF + + enable-data = "ENABLED" *(SP capability) + +5. Security Considerations + + It is believed that this extension doesn't add any security + considerations that are not already present in the base IMAP protocol + [RFC3501]. + +6. IANA Considerations + + The IANA has added ENABLE to the IMAP4 Capabilities Registry. + + + + +Gulbrandsen & Melnikov Standards Track [Page 4] + +RFC 5161 The IMAP ENABLE Extension March 2008 + + +7. Acknowledgments + + The editors would like to thank Randy Gellens, Chris Newman, Peter + Coates, Dave Cridland, Mark Crispin, Ned Freed, Dan Karp, Cyrus + Daboo, Ken Murchison, and Eric Burger for comments and corrections. + However, this doesn't necessarily mean that they endorse this + extension, agree with all details, or are responsible for errors + introduced by the editors. + +8. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", STD 68, RFC 5234, January + 2008. + + [RFC4551] Melnikov, A. and S. Hole, "IMAP Extension for Conditional + STORE Operation or Quick Flag Changes Resynchronization", + RFC 4551, June 2006. + +9. Informative References + + [ANNOTATE] Daboo, C. and R. Gellens, "IMAP ANNOTATE Extension", Work + in Progress, August 2006. + + + + + + + + + + + + + + + + + + + + + + +Gulbrandsen & Melnikov Standards Track [Page 5] + +RFC 5161 The IMAP ENABLE Extension March 2008 + + +Editors' Addresses + + Arnt Gulbrandsen + Oryx Mail Systems GmbH + Schweppermannstr. 8 + D-81671 Muenchen + Germany + + Fax: +49 89 4502 9758 + EMail: arnt@oryx.com + + + Alexey Melnikov + Isode Ltd + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: Alexey.Melnikov@isode.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Gulbrandsen & Melnikov Standards Track [Page 6] + +RFC 5161 The IMAP ENABLE Extension March 2008 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2008). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Gulbrandsen & Melnikov Standards Track [Page 7] + diff --git a/docs/rfcs/rfc5162.IMAP4_Extensions_for_Quick_Mailbox_resync.txt b/docs/rfcs/rfc5162.IMAP4_Extensions_for_Quick_Mailbox_resync.txt new file mode 100644 index 0000000..305c54f --- /dev/null +++ b/docs/rfcs/rfc5162.IMAP4_Extensions_for_Quick_Mailbox_resync.txt @@ -0,0 +1,1291 @@ + + + + + + +Network Working Group A. Melnikov +Request for Comments: 5162 D. Cridland +Category: Standards Track Isode Ltd + C. Wilson + Nokia + March 2008 + + + IMAP4 Extensions for Quick Mailbox Resynchronization + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + This document defines an IMAP4 extension, which gives an IMAP client + the ability to quickly resynchronize any previously opened mailbox as + part of the SELECT command, without the need for server-side state or + additional client round-trips. This extension also introduces a new + response that allows for a more compact representation of a list of + expunged messages (and always includes the Unique Identifiers (UIDs) + expunged). + + + + + + + + + + + + + + + + + + + + + + + + +Melnikov, et al. Standards Track [Page 1] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + +Table of Contents + + 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 2 + 2. Requirements Notation . . . . . . . . . . . . . . . . . . . . 4 + 3. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . 4 + 3.1. QRESYNC Parameter to SELECT/EXAMINE . . . . . . . . . . . 4 + 3.2. VANISHED UID FETCH Modifier . . . . . . . . . . . . . . . 8 + 3.3. EXPUNGE Command . . . . . . . . . . . . . . . . . . . . . 10 + 3.4. CLOSE Command . . . . . . . . . . . . . . . . . . . . . . 11 + 3.5. UID EXPUNGE Command . . . . . . . . . . . . . . . . . . . 11 + 3.6. VANISHED Response . . . . . . . . . . . . . . . . . . . . 12 + 3.7. CLOSED Response Code . . . . . . . . . . . . . . . . . . . 15 + 4. Server Implementation Considerations . . . . . . . . . . . . . 15 + 4.1. Server Implementations That Don't Store Extra State . . . 15 + 4.2. Server Implementations Storing Minimal State . . . . . . . 16 + 4.3. Additional State Required on the Server . . . . . . . . . 16 + 5. Updated Synchronization Sequence . . . . . . . . . . . . . . . 17 + 6. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 19 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 20 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 + 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 21 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 + 10.1. Normative References . . . . . . . . . . . . . . . . . . . 21 + 10.2. Informative References . . . . . . . . . . . . . . . . . . 22 + +1. Introduction and Overview + + The [CONDSTORE] extension gives a disconnected client the ability to + quickly resynchronize IMAP flag changes for previously seen messages. + This can be done using the CHANGEDSINCE FETCH modifier once a mailbox + is opened. In order for the client to discover which messages have + been expunged, the client still has to issue a UID FETCH or a UID + SEARCH command. This document defines an extension to [CONDSTORE] + that allows a reconnecting client to perform full resynchronization, + including discovery of expunged messages, in a single round-trip. + This extension also introduces a new response, VANISHED, that allows + for a more compact representation of a list of expunged messages. + + This extension can be useful for mobile clients that can experience + frequent disconnects caused by environmental factors (battery life, + signal strength, etc.). Such clients need a way to quickly reconnect + to the IMAP server, while minimizing delay experienced by the user as + well as the amount of traffic (and hence the expense) generated by + resynchronization. + + + + + + + +Melnikov, et al. Standards Track [Page 2] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + By extending the SELECT command to perform the additional + resynchronization, this also allows clients to reduce concurrent + connections to the IMAP server held purely for the sake of avoiding + the resynchronization. + + The quick resync IMAP extension is present if an IMAP4 server returns + "QRESYNC" as one of the supported capabilities to the CAPABILITY + command. + + Servers supporting this extension MUST implement and advertise + support for the [ENABLE] IMAP extension. Also, the presence of the + "QRESYNC" capability implies support for the [CONDSTORE] IMAP + extension even if the CONDSTORE capability isn't advertised. A + server compliant with this specification is REQUIREd to support + "ENABLE QRESYNC" and "ENABLE QRESYNC CONDSTORE" (which are "CONDSTORE + enabling commands", as defined in [CONDSTORE], and have identical + results), but there is no requirement for a compliant server to + support "ENABLE CONDSTORE" by itself. The "ENABLE QRESYNC"/"ENABLE + QRESYNC CONDSTORE" command also tells the server that it SHOULD start + sending VANISHED responses (see Section 3.6) instead of EXPUNGE + responses. This change remains in effect until the connection is + closed. + + For compatibility with clients that only support the [CONDSTORE] IMAP + extension, servers SHOULD advertise CONDSTORE in the CAPABILITY + response as well. + + A client making use of this extension MUST issue "ENABLE QRESYNC" + once it is authenticated. A server MUST respond with a tagged BAD + response if the QRESYNC parameter to the SELECT/EXAMINE command or + the VANISHED UID FETCH modifier is specified and the client hasn't + issued "ENABLE QRESYNC" in the current connection. + + This document puts additional requirements on a server implementing + the [CONDSTORE] extension. Each mailbox that supports persistent + storage of mod-sequences, i.e., for which the server has sent a + HIGHESTMODSEQ untagged OK response code on a successful SELECT/ + EXAMINE, MUST increment the per-mailbox mod-sequence when one or more + messages are expunged due to EXPUNGE, UID EXPUNGE or CLOSE; the + server MUST associate the incremented mod-sequence with the UIDs of + the expunged messages. + + A client that supports CONDSTORE but not this extension might + resynchronize a mailbox and discover that its HIGHESTMODSEQ has + increased from the value cached by the client. If the increase is + only due to messages having been expunged since the client last + synchronized, the client is likely to send a FETCH ... CHANGEDSINCE + command that returns no data. Thus, a client that supports CONDSTORE + + + +Melnikov, et al. Standards Track [Page 3] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + but not this extension might incur a penalty of an unneeded round- + trip when resynchronizing some mailboxes (those that have had + messages expunged but no flag changes since the last + synchronization). + + This extra round-trip is only incurred by clients that support + CONDSTORE but not this extension, and only when a mailbox has had + messages expunged but no flag changes to non-expunged messages. + Since CONDSTORE is a relatively new extension, it is thought likely + that clients that support it will also support this extension. + +2. Requirements Notation + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + In examples, "C:" and "S:" indicate lines sent by the client and + server respectively. If a single "C:" or "S:" label applies to + multiple lines, then the line breaks between those lines are for + editorial clarity only and are not part of the actual protocol + exchange. The five characters [...] means that something has been + elided. + + Understanding of the IMAP message sequence numbers and UIDs and the + EXPUNGE response [RFC3501] is essential when reading this document. + +3. IMAP Protocol Changes + +3.1. QRESYNC Parameter to SELECT/EXAMINE + + The Quick Resynchronization parameter to SELECT/EXAMINE commands has + four arguments: + + o the last known UIDVALIDITY, + + o the last known modification sequence, + + o the optional set of known UIDs, and + + o an optional parenthesized list of known sequence ranges and their + corresponding UIDs. + + A server MUST respond with a tagged BAD response if the Quick + Resynchronization parameter to SELECT/EXAMINE command is specified + and the client hasn't issued "ENABLE QRESYNC" in the current + connection. + + + + +Melnikov, et al. Standards Track [Page 4] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + Before opening the specified mailbox, the server verifies all + arguments for syntactic validity. If any parameter is not + syntactically valid, the server returns the tagged BAD response, and + the mailbox remains unselected. Once the check is done, the server + opens the mailbox as if no SELECT/EXAMINE parameters are specified + (this is subject to processing of other parameters as defined in + other extensions). In particular this means that the server MUST + send all untagged responses as specified in Sections 6.3.1 and 6.3.2 + of [RFC3501]. + + After that, the server checks the UIDVALIDITY value provided by the + client. If the provided UIDVALIDITY doesn't match the UIDVALIDITY + for the mailbox being opened, then the server MUST ignore the + remaining parameters and behave as if no dynamic message data + changed. The client can discover this situation by comparing the + UIDVALIDITY value returned by the server. This behavior allows the + client not to synchronize the mailbox or decide on the best + synchronization strategy. + + Example: Attempting to resynchronize INBOX, but the provided + UIDVALIDITY parameter doesn't match the current UIDVALIDITY + value. + + C: A02 SELECT INBOX (QRESYNC (67890007 20050715194045000 + 41,43:211,214:541)) + S: * 464 EXISTS + S: * 3 RECENT + S: * OK [UIDVALIDITY 3857529045] UIDVALIDITY + S: * OK [UIDNEXT 550] Predicted next UID + S: * OK [HIGHESTMODSEQ 90060128194045007] + S: * OK [UNSEEN 12] Message 12 is first unseen + S: * FLAGS (\Answered \Flagged \Draft \Deleted \Seen) + S: * OK [PERMANENTFLAGS (\Answered \Flagged \Draft + \Deleted \Seen \*)] Permanent flags + S: A02 OK [READ-WRITE] Sorry, UIDVALIDITY mismatch + + Modification Sequence and UID Parameters: + + A server that doesn't support the persistent storage of mod-sequences + for the mailbox MUST send the OK untagged response including the + NOMODSEQ response code with every successful SELECT or EXAMINE + command, as described in [CONDSTORE]. Such a server doesn't need to + remember mod-sequences for expunged messages in the mailbox. It MUST + ignore the remaining parameters and behave as if no dynamic message + data changed. + + If the provided UIDVALIDITY matches that of the selected mailbox, the + server then checks the last known modification sequence. + + + +Melnikov, et al. Standards Track [Page 5] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + The server sends the client any pending flag changes (using FETCH + responses that MUST contain UIDs) and expunges those that have + occurred in this mailbox since the provided modification sequence. + + If the list of known UIDs was also provided, the server should only + report flag changes and expunges for the specified messages. If the + client did not provide the list of UIDs, the server acts as if the + client has specified "1:", where is the mailbox's + UIDNEXT value minus 1. If the mailbox is empty and never had any + messages in it, then lack of the list of UIDs is interpreted as an + empty set of UIDs. + + Thus, the client can process just these pending events and need not + perform a full resynchronization. Without the message sequence + number matching information, the result of this step is semantically + equivalent to the client issuing: + tag1 UID FETCH "known-uids" (FLAGS) (CHANGEDSINCE + "mod-sequence-value" VANISHED) + + Example: + C: A03 SELECT INBOX (QRESYNC (67890007 + 90060115194045000 41,43:211,214:541)) + S: * OK [CLOSED] + S: * 314 EXISTS + S: * 15 RECENT + S: * OK [UIDVALIDITY 67890007] UIDVALIDITY + S: * OK [UIDNEXT 567] Predicted next UID + S: * OK [HIGHESTMODSEQ 90060115205545359] + S: * OK [UNSEEN 7] There are some unseen messages in the mailbox + S: * FLAGS (\Answered \Flagged \Draft \Deleted \Seen) + S: * OK [PERMANENTFLAGS (\Answered \Flagged \Draft + \Deleted \Seen \*)] Permanent flags + S: * VANISHED (EARLIER) 41,43:116,118,120:211,214:540 + S: * 49 FETCH (UID 117 FLAGS (\Seen \Answered) MODSEQ + (90060115194045001)) + S: * 50 FETCH (UID 119 FLAGS (\Draft $MDNSent) MODSEQ + (90060115194045308)) + S: ... + S: * 100 FETCH (UID 541 FLAGS (\Seen $Forwarded) MODSEQ + (90060115194045001)) + S: A03 OK [READ-WRITE] mailbox selected + + Message sequence match data: + + A client MAY provide a parenthesized list of a message sequence set + and the corresponding UID sets. Both MUST be provided in ascending + order. The server uses this data to restrict the range for which it + provides expunged message information. + + + +Melnikov, et al. Standards Track [Page 6] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + Conceptually, the client provides a small sample of sequence numbers + for which it knows the corresponding UIDs. The server then compares + each sequence number and UID pair the client provides with the + current state of the mailbox. If a pair matches, then the client + knows of any expunges up to, and including, the message, and thus + will not include that range in the VANISHED response, even if the + "mod-sequence-value" provided by the client is too old for the server + to have data of when those messages were expunged. + + Thus, if the Nth message number in the first set in the list is 4, + and the Nth UID in the second set in the list is 8, and the mailbox's + fourth message has UID 8, then no UIDs equal to or less than 8 are + present in the VANISHED response. If the (N+1)th message number is + 12, and the (N+1)th UID is 24, and the (N+1)th message in the mailbox + has UID 25, then the lowest UID included in the VANISHED response + would be 9. + + In the following two examples, the server is unable to remember + expunges at all, and only UIDs with messages divisible by three are + present in the mailbox. In the first example, the client does not + use the fourth parameter; in the second, it provides it. This + example is somewhat extreme, but shows that judicious usage of the + sequence match data can save a substantial amount of bandwidth. + + Example: + C: A04 SELECT INBOX (QRESYNC (67890007 + 90060115194045000 1:29997)) + S: * 10003 EXISTS + S: * 5 RECENT + S: * OK [UIDVALIDITY 67890007] UIDVALIDITY + S: * OK [UIDNEXT 30013] Predicted next UID + S: * OK [HIGHESTMODSEQ 90060115205545359] + S: * OK [UNSEEN 7] There are some unseen messages in the mailbox + S: * FLAGS (\Answered \Flagged \Draft \Deleted \Seen) + S: * OK [PERMANENTFLAGS (\Answered \Flagged \Draft + \Deleted \Seen \*)] Permanent flags + S: * VANISHED (EARLIER) 1:2,4:5,7:8,10:11,13:14 [...] + 29998:29999,30001:30002,30004:30005,30007:30008 + S: * 9889 FETCH (UID 29667 FLAGS (\Seen \Answered) MODSEQ + (90060115194045027)) + S: * 9890 FETCH (UID 29670 FLAGS (\Draft $MDNSent) MODSEQ + (90060115194045028)) + S: ... + S: * 9999 FETCH (UID 29997 FLAGS (\Seen $Forwarded) MODSEQ + (90060115194045031)) + S: A04 OK [READ-WRITE] mailbox selected + + + + + +Melnikov, et al. Standards Track [Page 7] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + Example: + C: B04 SELECT INBOX (QRESYNC (67890007 + 90060115194045000 1:29997 (5000,7500,9000,9990:9999 15000, + 22500,27000,29970,29973,29976,29979,29982,29985,29988,29991, + 29994,29997))) + S: * 10003 EXISTS + S: * 5 RECENT + S: * OK [UIDVALIDITY 67890007] UIDVALIDITY + S: * OK [UIDNEXT 30013] Predicted next UID + S: * OK [HIGHESTMODSEQ 90060115205545359] + S: * OK [UNSEEN 7] There are some unseen messages in the mailbox + S: * FLAGS (\Answered \Flagged \Draft \Deleted \Seen) + S: * OK [PERMANENTFLAGS (\Answered \Flagged \Draft + \Deleted \Seen \*)] Permanent flags + S: * VANISHED (EARLIER) 29998:29999,30001:30002,30004:30005,30007: + 30008 + S: * 9889 FETCH (UID 29667 FLAGS (\Seen \Answered) MODSEQ + (90060115194045027)) + S: * 9890 FETCH (UID 29670 FLAGS (\Draft $MDNSent) MODSEQ + (90060115194045028)) + S: ... + S: * 9999 FETCH (UID 29997 FLAGS (\Seen $Forwarded) MODSEQ + (90060115194045031)) + S: B04 OK [READ-WRITE] mailbox selected + +3.2. VANISHED UID FETCH Modifier + + [IMAPABNF] has extended the syntax of the FETCH and UID FETCH + commands to include an optional FETCH modifier. This document + defines a new UID FETCH modifier: VANISHED. + + Note, that the VANISHED UID FETCH modifier is NOT allowed with a + FETCH command. The server MUST return a tagged BAD response if this + response is specified as a modifier to the FETCH command. + + A server MUST respond with a tagged BAD response if the VANISHED UID + FETCH modifier is specified and the client hasn't issued "ENABLE + QRESYNC" in the current connection. + + The VANISHED UID FETCH modifier MUST only be specified together with + the CHANGEDSINCE UID FETCH modifier. + + The VANISHED UID FETCH modifier instructs the server to report those + messages from the UID set parameter that have been expunged and whose + associated mod-sequence is larger than the specified mod-sequence. + That is, the client requests to be informed of messages from the + specified set that were expunged since the specified mod-sequence. + Note that the mod-sequence(s) associated with these messages were + + + +Melnikov, et al. Standards Track [Page 8] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + updated when the messages were expunged (as described above). The + expunged messages are reported using the VANISHED response as + described in Section 3.6, which MUST contain the EARLIER tag. Any + VANISHED (EARLIER) responses MUST be returned before any FETCH + responses, as otherwise the client might get confused about how + message numbers map to UIDs. + + Note: A server that receives a mod-sequence smaller than , + where is the value of the smallest expunged mod-sequence + it remembers minus one, MUST behave as if it was requested to report + all expunged messages from the provided UID set parameter. + + Example 1: Without the VANISHED UID FETCH modifier, a CONDSTORE-aware + client [CONDSTORE] needs to issue separate commands to learn of flag + changes and expunged messages since the last synchronization: + + C: s100 UID FETCH 300:500 (FLAGS) (CHANGEDSINCE 12345) + S: * 1 FETCH (UID 404 MODSEQ (65402) FLAGS (\Seen)) + S: * 2 FETCH (UID 406 MODSEQ (75403) FLAGS (\Deleted)) + S: * 4 FETCH (UID 408 MODSEQ (29738) FLAGS ($NoJunk + $AutoJunk $MDNSent)) + S: s100 OK FETCH completed + C: s101 UID SEARCH 300:500 + S: * SEARCH 404 406 407 408 410 412 + S: s101 OK search completed + + Where 300 and 500 are the lowest and highest UIDs from client's + cache. The second SEARCH response tells the client that the messages + with UIDs 407, 410, and 412 are still present, but their flags + haven't changed since the specified modification sequence. + + Using the VANISHED UID FETCH modifier, it is sufficient to issue only + a single command: + + C: s100 UID FETCH 300:500 (FLAGS) (CHANGEDSINCE 12345 + VANISHED) + S: * VANISHED (EARLIER) 300:310,405,411 + S: * 1 FETCH (UID 404 MODSEQ (65402) FLAGS (\Seen)) + S: * 2 FETCH (UID 406 MODSEQ (75403) FLAGS (\Deleted)) + S: * 4 FETCH (UID 408 MODSEQ (29738) FLAGS ($NoJunk + $AutoJunk $MDNSent)) + S: s100 OK FETCH completed + + + + + + + + + +Melnikov, et al. Standards Track [Page 9] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + +3.3. EXPUNGE Command + + Arguments: none + + Responses: untagged responses: EXPUNGE or VANISHED + + Result: OK - expunge completed + NO - expunge failure: can't expunge (e.g., permission denied) + BAD - command unknown or arguments invalid + + This section updates the definition of the EXPUNGE command described + in Section 6.4.3 of [RFC3501]. + + The EXPUNGE command permanently removes all messages that have the + \Deleted flag set from the currently selected mailbox. Before + returning an OK to the client, those messages that are removed are + reported using a VANISHED response or EXPUNGE responses. + + If the server is capable of storing modification sequences for the + selected mailbox, it MUST increment the per-mailbox mod-sequence if + at least one message was permanently removed due to the execution of + the EXPUNGE command. For each permanently removed message, the + server MUST remember the incremented mod-sequence and corresponding + UID. If at least one message got expunged, the server MUST send the + updated per-mailbox modification sequence using the HIGHESTMODSEQ + response code (defined in [CONDSTORE]) in the tagged OK response. + + Example: C: A202 EXPUNGE + S: * 3 EXPUNGE + S: * 3 EXPUNGE + S: * 5 EXPUNGE + S: * 8 EXPUNGE + S: A202 OK [HIGHESTMODSEQ 20010715194045319] expunged + + Note: In this example, messages 3, 4, 7, and 11 had the \Deleted flag + set. The first "* 3 EXPUNGE" reports message # 3 as expunged. The + second "* 3 EXPUNGE" reports message # 4 as expunged (the message + number got decremented due to the previous EXPUNGE response). See + the description of the EXPUNGE response in [RFC3501] for further + explanation. + + Note that if the server chooses to always send VANISHED responses + instead of EXPUNGE responses, the previous example might look like + this: + + Example: C: B202 EXPUNGE + S: * VANISHED 405,407,410,425 + S: B202 OK [HIGHESTMODSEQ 20010715194045319] expunged + + + +Melnikov, et al. Standards Track [Page 10] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + Here messages with message numbers 3, 4, 7, and 11 have respective + UIDs 405, 407, 410, and 425. + +3.4. CLOSE Command + + Arguments: none + + Responses: no specific responses for this command + + Result: OK - close completed, now in authenticated state + BAD - command unknown or arguments invalid + + This section updates the definition of the CLOSE command described in + Section 6.4.2 of [RFC3501]. + + The CLOSE command permanently removes all messages that have the + \Deleted flag set from the currently selected mailbox, and returns to + the authenticated state from the selected state. No untagged EXPUNGE + (or VANISHED) responses are sent. + + If the server is capable of storing modification sequences for the + selected mailbox, it MUST increment the per-mailbox mod-sequence if + at least one message was permanently removed due to the execution of + the CLOSE command. For each permanently removed message, the server + MUST remember the incremented mod-sequence and corresponding UID. If + at least one message got expunged, the server MUST send the updated + per-mailbox modification sequence using the HIGHESTMODSEQ response + code (defined in [CONDSTORE]) in the tagged OK response. + + Example: C: A202 CLOSE + S: A202 OK [HIGHESTMODSEQ 20010715194045319] done + +3.5. UID EXPUNGE Command + + Arguments: message set + + Responses: untagged responses: EXPUNGE or VANISHED + + Result: OK - expunge completed + NO - expunge failure: can't expunge (e.g., permission denied) + BAD - command unknown or arguments invalid + + This section updates the definition of the UID EXPUNGE command + described in Section 2.1 of [UIDPLUS]. Servers that implement both + [UIDPLUS] and QRESYNC extensions must implement UID EXPUNGE as + described in this section. + + + + + +Melnikov, et al. Standards Track [Page 11] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + The UID EXPUNGE command permanently removes from the currently + selected mailbox all messages that both have the \Deleted flag set + and have a UID that is included in the specified message set. If a + message either does not have the \Deleted flag set or has a UID that + is not included in the specified message set, it is not affected. + + This command is particularly useful for disconnected mode clients. + By using UID EXPUNGE instead of EXPUNGE when resynchronizing with the + server, the client can avoid inadvertently removing any messages that + have been marked as \Deleted by other clients between the time that + the client was last connected and the time the client resynchronizes. + + Before returning an OK to the client, those messages that are removed + are reported using a VANISHED response or EXPUNGE responses. + + If the server is capable of storing modification sequences for the + selected mailbox, it MUST increment the per-mailbox mod-sequence if + at least one message was permanently removed due to the execution of + the UID EXPUNGE command. For each permanently removed message, the + server MUST remember the incremented mod-sequence and corresponding + UID. If at least one message got expunged, the server MUST send the + updated per-mailbox modification sequence using the HIGHESTMODSEQ + response code (defined in [CONDSTORE]) in the tagged OK response. + + Example: C: . UID EXPUNGE 3000:3002 + S: * 3 EXPUNGE + S: * 3 EXPUNGE + S: * 3 EXPUNGE + S: . OK [HIGHESTMODSEQ 20010715194045319] Ok + + Note: In this example, at least messages with message numbers 3, 4, + and 5 (UIDs 3000 to 3002) had the \Deleted flag set. The first "* 3 + EXPUNGE" reports message # 3 as expunged. The second "* 3 EXPUNGE" + reports message # 4 as expunged (the message number got decremented + due to the previous EXPUNGE response). See the description of the + EXPUNGE response in [RFC3501] for further explanation. + +3.6. VANISHED Response + + Contents: an optional EARLIER tag + + list of UIDs + + The VANISHED response reports that the specified UIDs have been + permanently removed from the mailbox. This response is similar to + the EXPUNGE response [RFC3501]; however, it can return information + about multiple messages, and it returns UIDs instead of message + + + + +Melnikov, et al. Standards Track [Page 12] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + numbers. The first benefit saves bandwidth, while the second is more + convenient for clients that only use UIDs to access the IMAP server. + + The VANISHED response has the same restrictions on when it can be + sent as does the EXPUNGE response (see below). + + The VANISHED response has two forms. The first form contains the + EARLIER tag, which signifies that the response was caused by a UID + FETCH (VANISHED) or a SELECT/EXAMINE (QRESYNC) command. This + response is sent if the UID set parameter to the UID FETCH (VANISHED) + command includes UIDs of messages that are no longer in the mailbox. + When the client sees a VANISHED EARLIER response, it MUST NOT + decrement message sequence numbers for each successive message in the + mailbox. + + The second form doesn't contain the EARLIER tag and is described + below. Once a client has issued "ENABLE QRESYNC", the server SHOULD + use the VANISHED response without the EARLIER tag instead of the + EXPUNGE response. The server SHOULD continue using VANISHED in lieu + of EXPUNGE for the duration of the connection. In particular, this + affects the EXPUNGE [RFC3501] and UID EXPUNGE [UIDPLUS] commands, as + well as messages expunged in other connections. Such a VANISHED + response MUST NOT contain the EARLIER tag. + + A VANISHED response sent because of an EXPUNGE or UID EXPUNGE command + or because messages were expunged in other connections (i.e., the + VANISHED response without the EARLIER tag) also decrements the number + of messages in the mailbox; it is not necessary for the server to + send an EXISTS response with the new value. It also decrements + message sequence numbers for each successive message in the mailbox + (see the example at the end of this section). Note that a VANISHED + response caused by EXPUNGE, UID EXPUNGE, or messages expunged in + other connections SHOULD only contain UIDs for messages expunged + since the last VANISHED/EXPUNGE response sent for the currently + opened mailbox or since the mailbox was opened. That is, servers + SHOULD NOT send UIDs for previously expunged messages, unless + explicitly requested to do so by the UID FETCH (VANISHED) command. + + Note that client implementors must take care to properly decrement + the number of messages in the mailbox even if a server violates this + last SHOULD or repeats the same UID multiple times in the returned + UID set. In general, this means that a client using this extension + should either avoid using message numbers entirely, or have a + complete mapping of UIDs to message sequence numbers for the selected + mailbox. + + + + + + +Melnikov, et al. Standards Track [Page 13] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + Because clients handle the two different forms of the VANISHED + response differently, servers MUST NOT report UIDs resulting from a + UID FETCH (VANISHED) or a SELECT/EXAMINE (QRESYNC) in the same + VANISHED response as UIDs of messages expunged now (i.e., messages + expunged in other connections). Instead, the server MUST send + separate VANISHED responses: one with the EARLIER tag and one + without. + + A VANISHED response MUST NOT be sent when no command is in progress, + nor while responding to a FETCH, STORE, or SEARCH command. This rule + is necessary to prevent a loss of synchronization of message sequence + numbers between client and server. A command is not "in progress" + until the complete command has been received; in particular, a + command is not "in progress" during the negotiation of command + continuation. + + Note: UID FETCH, UID STORE, and UID SEARCH are different commands + from FETCH, STORE, and SEARCH. A VANISHED response MAY be sent + during a UID command. However, the VANISHED response MUST NOT be + sent during a UID SEARCH command that contains message numbers in the + search criteria. + + The update from the VANISHED response MUST be recorded by the client. + + Example: Let's assume that there is the following mapping between + message numbers and UIDs in the currently selected mailbox (here "X" + marks messages with the \Deleted flag set, and "x" represents UIDs + which are not relevant for the example): + + Message numbers: 1 2 3 4 5 6 7 8 9 10 11 + UIDs: x 504 505 507 508 x 510 x x x 625 + \Deleted messages: X X X X + + In the presence of the extension defined in this document: + + C: A202 EXPUNGE + S: * VANISHED 505,507,510,625 + S: A202 OK EXPUNGE completed + + Without the QRESYNC extension, the same example might look like: + + C: A202 EXPUNGE + S: * 3 EXPUNGE + S: * 3 EXPUNGE + S: * 5 EXPUNGE + S: * 8 EXPUNGE + S: A202 OK EXPUNGE completed + + + + +Melnikov, et al. Standards Track [Page 14] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + (Continuing previous example) If subsequently messages with UIDs 504 + and 508 got marked as \Deleted: + + C: A210 EXPUNGE + S: * VANISHED 504,508 + S: A210 OK EXPUNGE completed + + i.e., the last VANISHED response only contains UIDs of messages + expunged since the previous VANISHED response. + +3.7. CLOSED Response Code + + The CLOSED response code has no parameters. A server implementing + the extension defined in this document MUST return the CLOSED + response code when the currently selected mailbox is closed + implicitly using the SELECT/EXAMINE command on another mailbox. The + CLOSED response code serves as a boundary between responses for the + previously opened mailbox (which was closed) and the newly selected + mailbox: all responses before the CLOSED response code relate to the + mailbox that was closed, and all subsequent responses relate to the + newly opened mailbox. + + There is no need to return the CLOSED response code on completion of + the CLOSE or the UNSELECT [UNSELECT] command (or similar) whose + purpose is to close the currently selected mailbox without opening a + new one. + +4. Server Implementation Considerations + + This section describes a minimalist implementation, a moderate + implementation, and an example of a full implementation. + +4.1. Server Implementations That Don't Store Extra State + + Strictly speaking, a server implementation that doesn't remember mod- + sequences associated with expunged messages can be considered + compliant with this specification. Such implementations return all + expunged messages specified in the UID set of the UID FETCH + (VANISHED) command every time, without paying attention to the + specified CHANGEDSINCE mod-sequence. Such implementations are + discouraged, as they can end up returning VANISHED responses that are + bigger than the result of a UID SEARCH command for the same UID set. + + Clients that use the message sequence match data can reduce the scope + of this VANISHED response substantially in the typical case where + expunges have not happened, or happen only toward the end of the + mailbox. + + + + +Melnikov, et al. Standards Track [Page 15] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + +4.2. Server Implementations Storing Minimal State + + A server that stores the HIGHESTMODSEQ value at the time of the last + EXPUNGE can omit the VANISHED response when a client provides a + MODSEQ value that is equal to, or higher than, the current value of + this datum, that is, when there have been no EXPUNGEs. + + A client providing message sequence match data can reduce the scope + as above. In the case where there have been no expunges, the server + can ignore this data. + +4.3. Additional State Required on the Server + + When compared to the [CONDSTORE] extension, this extension requires + servers to store additional state associated with expunged messages. + Note that implementations are not required to store this state in + persistent storage; however, use of persistent storage is advisable. + + One possible way to correctly implement the extension described in + this document is to store a queue of pairs. + can be represented as a sequence of + pairs. + + When messages are expunged, one or more entries are added to the + queue tail. + + When the server receives a request to return messages expunged since + a given mod-sequence, it will search the queue from the tail (i.e., + going from the highest expunged mod-sequence to the lowest) until it + sees the first record with a mod-sequence less than or equal to the + given mod-sequence or it reaches the head of the queue. + + Note that indefinitely storing information about expunged messages + can cause storage and related problems for an implementation. In the + worst case, this could result in almost 64Gb of storage for each IMAP + mailbox. For example, consider an implementation that stores triples for each range of messages + expunged at the same time. Each triple requires 16 octets: 4 octets + for each of the two UIDs, and 8 octets for the mod-sequence. Assume + that there is a mailbox containing a single message with a UID of + 2**32-1 (the maximum possible UID value), where messages had + previously existed with UIDs starting at 1, and have been expunged + one at a time. For this mailbox alone, storage is required for the + triples <1, 1, modseq1>, <2, 2, modseq2>, ..., <2**32-2, 2**32-2, + modseq4294967294>. + + + + + + +Melnikov, et al. Standards Track [Page 16] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + Hence, implementations are encouraged to adopt strategies to protect + against such storage problems, such as limiting the size of the queue + used to store mod-sequences for expunged messages and "expiring" + older records when this limit is reached. When the selected + implementation-specific queue limit is reached, the oldest record(s) + are deleted from the queue (note that such records are located at the + queue head). For all such "expired" records, the server needs to + store a single mod-sequence, which is the highest mod-sequence for + all "expired" expunged messages. + + Note that if the client provides the message sequence match data, + this can heavily reduce the data cost of sending a complete set of + missing UIDs; thus, reducing the problems for clients if a server is + unable to persist much of this queue. If the queue contains data + back to the requested mod-sequence, this data can be ignored. + + Also, note that if the UIDVALIDITY of the mailbox changes or if the + mailbox is deleted, then any state associated with expunged messages + doesn't need to be preserved and SHOULD be deleted. + +5. Updated Synchronization Sequence + + This section updates the description of optimized synchronization in + Section 6.1 of the [IMAP-DISC]. + + An advanced disconnected mail client should use the QRESYNC and + [CONDSTORE] extensions when they are supported by the server. The + client uses the value from the HIGHESTMODSEQ OK response code + received on mailbox opening to determine if it needs to + resynchronize. Once the synchronization is complete, it MUST cache + the received value (unless the mailbox UIDVALIDITY value has changed; + see below). The client MUST update its copy of the HIGHESTMODSEQ + value whenever the server sends a subsequent HIGHESTMODSEQ OK + response code. + + After completing a full synchronization, the client MUST also take + note of any unsolicited MODSEQ FETCH data items received from the + server. Whenever the client receives a tagged response to a command, + it calculates the highest value among all MODSEQ FETCH data items + received since the last tagged response. If this value is bigger + than the client's copy of the HIGHESTMODSEQ value, then the client + MUST use this value as its new HIGHESTMODSEQ value. + + Note: It is not safe to update the client's copy of the HIGHESTMODSEQ + value with a MODSEQ FETCH data item value as soon as it is received + because servers are not required to send MODSEQ FETCH data items in + increasing modseqence order. This can lead to the client missing + some changes in case of connectivity loss. + + + +Melnikov, et al. Standards Track [Page 17] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + When opening the mailbox for synchronization, the client uses the + QRESYNC parameter to the SELECT/EXAMINE command. The QRESYNC + parameter is followed by the UIDVALIDITY and mailbox HIGHESTMODSEQ + values, as known to the client. It can be optionally followed by the + set of UIDs, for example, if the client is only interested in partial + synchronization of the mailbox. The client may also transmit a list + containing its knowledge of message numbers. + + If the SELECT/EXAMINE command is successful, the client compares + UIDVALIDITY as described in step d)1) in Section 3 of the + [IMAP-DISC]. If the cached UIDVALIDITY value matches the one + returned by the server and the server also returns the HIGHESTMODSEQ + response code, then the server reports expunged messages and returns + flag changes for all messages specified by the client in the UID set + parameter (or for all messages in the mailbox, if the client omitted + the UID set parameter). At this point, the client is synchronized, + except for maybe the new messages. + + If upon a successful SELECT/EXAMINE (QRESYNC) command the client + receives a NOMODSEQ OK untagged response (instead of the + HIGHESTMODSEQ response code), it MUST remove the last known + HIGHESTMODSEQ value from its cache and follow the more general + instructions in Section 3 of the [IMAP-DISC]. + + At this point, the client is in sync with the server regarding old + messages. This client can now fetch information about new messages + (if requested by the user). + + Step d) ("Server-to-client synchronization") in Section 4 of the + [IMAP-DISC] in the presence of the QRESYNC & CONDSTORE extensions is + amended as follows: + + d) "Server-to-client synchronization" -- for each mailbox that + requires synchronization, do the following: + + 1a) Check the mailbox UIDVALIDITY (see Section 4.1 of the [IMAP-DISC] + for more details) after issuing SELECT/EXAMINE (QRESYNC) command. + + If the UIDVALIDITY value returned by the server differs, the + client MUST + + * empty the local cache of that mailbox; + + * "forget" the cached HIGHESTMODSEQ value for the mailbox; + + + + + + + +Melnikov, et al. Standards Track [Page 18] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + * remove any pending "actions" which refer to UIDs in that + mailbox. Note, this doesn't affect actions performed on + client generated fake UIDs (see Section 5 of the + [IMAP-DISC]); + + 2) Fetch the current "descriptors"; + + I) Discover new messages. + + 3) Fetch the bodies of any "interesting" messages that the client + doesn't already have. + + Example: The UIDVALIDITY value is the same, but the HIGHESTMODSEQ + value has changed on the server while the client was + offline: + + C: A142 SELECT INBOX (QRESYNC (3857529045 20010715194032001 1:198)) + S: * 172 EXISTS + S: * 1 RECENT + S: * OK [UNSEEN 12] Message 12 is first unseen + S: * OK [UIDVALIDITY 3857529045] UIDs valid + S: * OK [UIDNEXT 201] Predicted next UID + S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) + S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited + S: * OK [HIGHESTMODSEQ 20010715194045007] + S: * VANISHED (EARLIER) 1:5,7:8,10:15 + S: * 2 FETCH (UID 6 MODSEQ (20010715205008000) + FLAGS (\Deleted)) + S: * 5 FETCH (UID 9 MODSEQ (20010715195517000) + FLAGS ($NoJunk $AutoJunk $MDNSent)) + ... + S: A142 OK [READ-WRITE] SELECT completed + +6. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [ABNF]. + + Non-terminals referenced but not defined below are as defined by + [RFC3501], [CONDSTORE], or [IMAPABNF]. + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of upper or lower case characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. + + + + + + +Melnikov, et al. Standards Track [Page 19] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + capability =/ "QRESYNC" + + select-param = "QRESYNC" SP "(" uidvalidity SP + mod-sequence-value [SP known-uids] + [SP seq-match-data] ")" + ;; conforms to the generic select-param + ;; syntax defined in [IMAPABNF] + + seq-match-data = "(" known-sequence-set SP known-uid-set ")" + + uidvalidity = nz-number + + known-uids = sequence-set + ;; sequence of UIDs, "*" is not allowed + + known-sequence-set = sequence-set + ;; set of message numbers corresponding to + ;; the UIDs in known-uid-set, in ascending order. + ;; * is not allowed. + + known-uid-set = sequence-set + ;; set of UIDs corresponding to the messages in + ;; known-sequence-set, in ascending order. + ;; * is not allowed. + + message-data =/ expunged-resp + + expunged-resp = "VANISHED" [SP "(EARLIER)"] SP known-uids + + rexpunges-fetch-mod = "VANISHED" + ;; VANISHED UID FETCH modifier conforms + ;; to the fetch-modifier syntax + ;; defined in [IMAPABNF]. It is only + ;; allowed in the UID FETCH command. + + resp-text-code =/ "CLOSED" + +7. Security Considerations + + As always, it is important to thoroughly test clients and servers + implementing this extension, as it changes how the server reports + expunged messages to the client. + + Security considerations relevant to [CONDSTORE] are relevant to this + extension. + + This document doesn't raise any new security concerns not already + raised by [CONDSTORE] or [RFC3501]. + + + +Melnikov, et al. Standards Track [Page 20] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + +8. IANA Considerations + + IMAP4 capabilities are registered by publishing a standards track or + IESG approved experimental RFC. The registry is currently located + at: + + http://www.iana.org/assignments/imap4-capabilities + + This document defines the QRESYNC IMAP capability. IANA has added + this capability to the registry. + +9. Acknowledgments + + Thanks to Steve Hole, Cyrus Daboo, and Michael Wener for encouraging + creation of this document. + + Valuable comments, both in agreement and in dissent, were received + from Timo Sirainen, Michael Wener, Randall Gellens, Arnt Gulbrandsen, + Chris Newman, Peter Coates, Mark Crispin, Elwyn Davies, Dan Karp, + Eric Rescorla, and Mike Zraly. + + This document takes substantial text from [RFC3501] by Mark Crispin. + +10. References + +10.1. Normative References + + [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + + [CONDSTORE] Melnikov, A. and S. Hole, "IMAP Extension for + Conditional STORE Operation or Quick Flag Changes + Resynchronization", RFC 4551, June 2006. + + [ENABLE] Gulbrandsen, A., Ed. and A. Melnikov, Ed., "The IMAP + ENABLE Extension", RFC 5161, March 2008. + + [IMAPABNF] Melnikov, A. and C. Daboo, "Collected Extensions to + IMAP4 ABNF", RFC 4466, April 2006. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [UIDPLUS] Crispin, M., "Internet Message Access Protocol (IMAP) - + UIDPLUS extension", RFC 4315, December 2005. + + + +Melnikov, et al. Standards Track [Page 21] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + +10.2. Informative References + + [IMAP-DISC] Melnikov, A., Ed., "Synchronization Operations For + Disconnected Imap4 Clients", RFC 4549, June 2006. + + [UNSELECT] Melnikov, A., "Internet Message Access Protocol (IMAP) + UNSELECT command", RFC 3691, February 2004. + +Authors' Addresses + + Alexey Melnikov + Isode Ltd + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: Alexey.Melnikov@isode.com + + + Dave Cridland + Isode Ltd + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: dave.cridland@isode.com + + + Corby Wilson + Nokia + 5 Wayside Rd. + Burlington, MA 01803 + USA + + EMail: corby@computer.org + + + + + + + + + + + + + + +Melnikov, et al. Standards Track [Page 22] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2008). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Melnikov, et al. Standards Track [Page 23] + diff --git a/docs/rfcs/rfc5182.IMAP_extension_last_SEARCH_result.txt b/docs/rfcs/rfc5182.IMAP_extension_last_SEARCH_result.txt new file mode 100644 index 0000000..a7f9147 --- /dev/null +++ b/docs/rfcs/rfc5182.IMAP_extension_last_SEARCH_result.txt @@ -0,0 +1,731 @@ + + + + + + +Network Working Group A. Melnikov +Request for Comments: 5182 Isode Ltd. +Updates: 3501 March 2008 +Category: Standards Track + + + IMAP Extension for Referencing the Last SEARCH Result + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + Many IMAP clients use the result of a SEARCH command as the input to + perform another operation, for example, fetching the found messages, + deleting them, or copying them to another mailbox. + + This can be achieved using standard IMAP operations described in RFC + 3501; however, this would be suboptimal. The server will send the + list of found messages to the client; after that, the client will + have to parse the list, reformat it, and send it back to the server. + The client can't pipeline the SEARCH command with the subsequent + command, and, as a result, the server might not be able to perform + some optimizations. + + This document proposes an IMAP extension that allows a client to tell + a server to use the result of a SEARCH (or Unique Identifier (UID) + SEARCH) command as an input to any subsequent command. + +1. Introduction + + Many IMAP clients use the result of a SEARCH command as the input to + perform another operation, for example, fetching the found messages, + deleting them, or copying them to another mailbox. + + This document proposes an IMAP extension that allows a client to tell + a server to use the result of a SEARCH (or UID SEARCH) command as an + input to any subsequent command. + + The SEARCH result reference extension defines a new SEARCH result + option [IMAPABNF] "SAVE" that tells the server to remember the result + of the SEARCH or UID SEARCH command (as well as any command based on + SEARCH, e.g., SORT and THREAD [SORT]) and store it in an internal + + + +Melnikov Standards Track [Page 1] + +RFC 5182 Last SEARCH Result Reference March 2008 + + + variable that we will reference as the "search result variable". The + client can use the "$" marker to reference the content of this + internal variable. The "$" marker can be used instead of message + sequence or UID sequence in order to indicate that the server should + substitute it with the list of messages from the search result + variable. Thus, the client can use the result of the latest + remembered SEARCH command as a parameter to another command. The + search result marker has several advantages: + + * it avoids wasted bandwidth and associated delay; + + * it allows the client to pipeline a SEARCH [IMAP4] command with a + subsequent FETCH/STORE/COPY/SEARCH [IMAP4] or UID EXPUNGE + [UIDPLUS] command; + + * the client doesn't need to spend time reformatting the result of + a SEARCH command into a message set used in the subsequent + command; + + * it allows the server to perform optimizations. For example, if + the server can execute several pipelined commands in parallel + (or out of order), presence of the search result marker can + allow the server to decide which commands may or may not be + executed out of order. + + In absence of any other SEARCH result option, the SAVE result option + also suppresses any SEARCH response that would have been otherwise + returned by the SEARCH command. + +1.1. 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", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [KEYWORDS]. + + Explanatory comments in examples start with // and are not part of + the protocol. + + + + + + + + + + + +Melnikov Standards Track [Page 2] + +RFC 5182 Last SEARCH Result Reference March 2008 + + +2. Overview + +2.1. Normative Description of the SEARCHRES Extension + + The SEARCH result reference extension described in this document is + present in any IMAP4 server implementation that returns "SEARCHRES" + as one of the supported capabilities in the CAPABILITY command + response. Any such server MUST also implement the [ESEARCH] + extension. + + Upon successful completion of a SELECT or an EXAMINE command (after + the tagged OK response), the current search result variable is reset + to the empty sequence. + + A successful SEARCH command with the SAVE result option sets the + value of the search result variable to the list of messages found in + the SEARCH command. For example, if no messages were found, the + search result variable will contain the empty list. + + Any of the following SEARCH commands MUST NOT change the search + result variable: + + o a SEARCH command that caused the server to return the BAD tagged + response, + + o a SEARCH command with no SAVE result option that caused the + server to return NO tagged response, + + o a successful SEARCH command with no SAVE result option. + + A SEARCH command with the SAVE result option that caused the server + to return the NO tagged response sets the value of the search result + variable to the empty sequence. + + When a message listed in the search result variable is EXPUNGEd, it + is automatically removed from the list. Implementors are reminded + that if the server stores the list as a list of message numbers, it + MUST automatically adjust them when notifying the client about + expunged messages, as described in Section 7.4.1 of [IMAP4]. + + If the server decides to send a new UIDVALIDITY value while the + mailbox is opened, this causes resetting of the search variable to + the empty list. + + + + + + + + +Melnikov Standards Track [Page 3] + +RFC 5182 Last SEARCH Result Reference March 2008 + + + Note that even if the "$" marker contains the empty list of messages, + it must be treated by all commands accepting message sets as + parameters as a valid, but non-matching list of messages. For + example, the "FETCH $" command would return a tagged OK response and + no FETCH responses. See also the Example 5 below. + + Note that even if the "$" marker contains the empty list of messages, + it must be treated as a valid but non-matching list of messages, by + all commands that accept message sets as parameters. + + Implementation note: server implementors should note that "$" can + reference IMAP message sequences or UID sequences, depending on the + context where it is used. For example, the "$" marker can be set as + a result of a SEARCH (SAVE) command and used as a parameter to a UID + FETCH command (which accepts a UID sequence, not a message sequence), + or the "$" marker can be set as a result of a UID SEARCH (SAVE) + command and used as a parameter to a FETCH command (which accepts a + message sequence, not a UID sequence). + +2.2. Examples + + 1) The following example demonstrates how the client can use the + result of a SEARCH command to FETCH headers of interesting + messages: + + Example 1: + C: A282 SEARCH RETURN (SAVE) FLAGGED SINCE 1-Feb-1994 + NOT FROM "Smith" + S: A282 OK SEARCH completed, result saved + C: A283 FETCH $ (UID INTERNALDATE FLAGS RFC822.HEADER) + S: * 2 FETCH (UID 14 ... + S: * 84 FETCH (UID 100 ... + S: * 882 FETCH (UID 1115 ... + S: A283 OK completed + + The client can also pipeline the two commands: + + Example 2: + C: A282 SEARCH RETURN (SAVE) FLAGGED SINCE 1-Feb-1994 + NOT FROM "Smith" + C: A283 FETCH $ (UID INTERNALDATE FLAGS RFC822.HEADER) + S: A282 OK SEARCH completed + S: * 2 FETCH (UID 14 ... + S: * 84 FETCH (UID 100 ... + S: * 882 FETCH (UID 1115 ... + S: A283 OK completed + + + + + +Melnikov Standards Track [Page 4] + +RFC 5182 Last SEARCH Result Reference March 2008 + + + 2) The following example demonstrates that the result of one SEARCH + command can be used as input to another SEARCH command: + + Example 3: + C: A300 SEARCH RETURN (SAVE) SINCE 1-Jan-2004 + NOT FROM "Smith" + S: A300 OK SEARCH completed + C: A301 UID SEARCH UID $ SMALLER 4096 + S: * SEARCH 17 900 901 + S: A301 OK completed + + Note that the second command in Example 3 can be replaced with: + C: A301 UID SEARCH $ SMALLER 4096 + and the result of the command would be the same. + + 3) The following example shows that the "$" + marker can be combined with other message numbers using the OR + SEARCH criterion. + + Example 4: + C: P282 SEARCH RETURN (SAVE) SINCE 1-Feb-1994 + NOT FROM "Smith" + S: P282 OK SEARCH completed + C: P283 SEARCH CHARSET UTF-8 (OR $ 1,3000:3021) TEXT {8} + C: YYYYYYYY + S: * SEARCH 882 1102 3003 3005 3006 + S: P283 OK completed + + Note: Since this document format is restricted to 7-bit ASCII text, + it is not possible to show actual UTF-8 data. The "YYYYYYYY" is a + placeholder for what would be 8 octets of 8-bit data in an actual + transaction. + + + + + + + + + + + + + + + + + + + +Melnikov Standards Track [Page 5] + +RFC 5182 Last SEARCH Result Reference March 2008 + + + 4) The following example demonstrates that a failed SEARCH sets the + search result variable to the empty list. + + Example 5: + C: B282 SEARCH RETURN (SAVE) SINCE 1-Feb-1994 + NOT FROM "Smith" + S: B282 OK SEARCH completed + C: B283 SEARCH CHARSET KOI8-R (OR $ 1,3000:3021) TEXT {4} + C: XXXX + S: B283 NO [BADCHARSET UTF-8] KOI8-R is not supported + //After this command the saved result variable contains + //no messages. A client that wants to reissue the B283 + //SEARCH command with another CHARSET would have to reissue + //the B282 command as well. One possible workaround for + //this is to include the desired CHARSET parameter + //in the earliest SEARCH RETURN (SAVE) command in a + //sequence of related SEARCH commands. + //A better approach might be to always use CHARSET UTF-8 + //instead. + + Note: Since this document format is restricted to 7-bit ASCII text, + it is not possible to show actual KOI8-R data. The "XXXX" is a + placeholder for what would be 4 octets of 8-bit data in an actual + transaction. + + 5) The following example demonstrates that it is not an error to use + the "$" marker when it contains no messages. + + Example 6: + C: E282 SEARCH RETURN (SAVE) SINCE 28-Oct-2006 + NOT FROM "Eric" + C: E283 COPY $ "Other Messages" + //The "$" contains no messages + S: E282 OK SEARCH completed + S: E283 OK COPY completed, nothing copied + +2.3. Multiple Commands in Progress + + Use of a SEARCH RETURN (SAVE) command followed by a command using the + "$" marker creates direct dependency between the two commands. As + directed by Section 5.5 of [IMAP4], a server MUST execute the two + commands in the order they were received. (A server capable of + out-of-order execution can in some cases execute the two commands in + parallel, for example, if a SEARCH RETURN (SAVE) is followed by + "SEARCH $", the search criteria from the first command can be + directly substituted into the second command.) + + + + + +Melnikov Standards Track [Page 6] + +RFC 5182 Last SEARCH Result Reference March 2008 + + + A client supporting this extension MAY pipeline a SEARCH RETURN + (SAVE) command with one or more command using the "$" marker, as long + as this doesn't create an ambiguity, as described in Section 5.5 of + [IMAP4]. + + Example 7: + C: F282 SEARCH RETURN (SAVE) KEYWORD $Junk + C: F283 COPY $ "Junk" + C: F284 STORE $ +FLAGS.Silent (\Deleted) + S: F282 OK SEARCH completed + S: F283 OK COPY completed + S: F284 OK STORE completed + + Example 8: + C: G282 SEARCH RETURN (SAVE) KEYWORD $Junk + C: G283 SEARCH RETURN (ALL) SINCE 28-Oct-2006 + FROM "Eric" + //The server can execute the two SEARCH commands + //in any order, as they don't have any dependency. + //Note that the second command is making use of + //the [ESEARCH] extension. + S: * ESEARCH (TAG "G283") ALL 3:15,27,29:103 + S: G283 OK SEARCH completed + S: G282 OK SEARCH completed + + The following example demonstrates that the result of the second + SEARCH always overrides the result of the first. + + Example 9: + C: H282 SEARCH RETURN (SAVE) KEYWORD $Junk + C: H283 SEARCH RETURN (SAVE) SINCE 28-Oct-2006 + FROM "Eric" + S: H282 OK SEARCH completed + S: H283 OK SEARCH completed + +2.4. Interaction with ESEARCH Extension + + Servers that implement the extension defined in this document MUST + implement [ESEARCH] and conform to additional requirements listed in + this section. + + The SAVE result option doesn't change whether the server would return + items corresponding to MIN, MAX, ALL, or COUNT [ESEARCH] result + options. + + + + + + + +Melnikov Standards Track [Page 7] + +RFC 5182 Last SEARCH Result Reference March 2008 + + + When the SAVE result option is combined with the MIN or MAX [ESEARCH] + result option, and none of the other ESEARCH result options are + present, the corresponding MIN/MAX is returned (if the search result + is not empty), but the "$" marker would contain a single message as + returned in the MIN/MAX return item. + + If the SAVE result option is combined with both MIN and MAX result + options, and none of the other ESEARCH result options are present, + the "$" marker would contain one or two messages as returned in the + MIN/MAX return items. + + If the SAVE result option is combined with the ALL and/or COUNT + result option(s), the "$" marker would always contain all messages + found by the SEARCH or UID SEARCH command. (Note that the last rule + might affect ESEARCH implementations that optimize how the COUNT + result is constructed.) + + The following table summarizes the additional requirement on ESEARCH + server implementations described in this section. + + +----------------+-------------------+ + | Combination of | "$" marker value | + | Result option | | + +----------------+-------------------+ + | SAVE MIN | MIN | + +----------------+-------------------+ + | SAVE MAX | MAX | + +----------------+-------------------+ + | SAVE MIN MAX | MIN & MAX | + +----------------+-------------------+ + | SAVE * [m] | all found messages| + +----------------+-------------------+ + + where '*' means "ALL" and/or "COUNT" + '[m]' means optional "MIN" and/or "MAX" + + + + + + + + + + + + + + + + +Melnikov Standards Track [Page 8] + +RFC 5182 Last SEARCH Result Reference March 2008 + + + The following example demonstrates behavioral difference for + different combinations of ESEARCH result options. Explanatory + comments start with // and are not part of the protocol: + + Example 10: + C: C282 SEARCH RETURN (ALL) SINCE 12-Feb-2006 + NOT FROM "Smith" + S: * ESEARCH (TAG "C283") ALL 2,10:15,21 + //$ value hasn't changed + S: C282 OK SEARCH completed + + C: C283 SEARCH RETURN (ALL SAVE) SINCE 12-Feb-2006 + NOT FROM "Smith" + S: * ESEARCH (TAG "C283") ALL 2,10:15,21 + //$ value is 2,10:15,21 + S: C283 OK SEARCH completed + + C: C284 SEARCH RETURN (SAVE MIN) SINCE 12-Feb-2006 + NOT FROM "Smith" + S: * ESEARCH (TAG "C284") MIN 2 + //$ value is 2 + S: C284 OK SEARCH completed + + C: C285 SEARCH RETURN (MAX SAVE MIN) SINCE + 12-Feb-2006 NOT FROM "Smith" + S: * ESEARCH (TAG "C285") MIN 2 MAX 21 + //$ value is 2,21 + S: C285 OK SEARCH completed + + C: C286 SEARCH RETURN (MAX SAVE MIN COUNT) + SINCE 12-Feb-2006 NOT FROM "Smith" + S: * ESEARCH (TAG "C286") MIN 2 MAX 21 COUNT 8 + //$ value is 2,10:15,21 + S: C286 OK SEARCH completed + + C: C286 SEARCH RETURN (ALL SAVE MIN) SINCE + 12-Feb-2006 NOT FROM "Smith" + S: * ESEARCH (TAG "C286") MIN 2 ALL 2,10:15,21 + //$ value is 2,10:15,21 + S: C286 OK SEARCH completed + + + + + + + + + + + +Melnikov Standards Track [Page 9] + +RFC 5182 Last SEARCH Result Reference March 2008 + + +2.5. Refusing to Save Search Results + + In some cases, the server MAY refuse to save a SEARCH (SAVE) result, + for example, if an internal limit on the number of saved results is + reached. + + In this case, the server MUST return a tagged NO response containing + the NOTSAVED response code and set the search result variable to the + empty sequence, as described in Section 2.1. + +3. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [ABNF]. Non-terminals + referenced but not defined below are as defined in [IMAP4] or + [IMAPABNF]. + + Except as noted otherwise, all alphabetic characters are + case-insensitive. The use of upper- or lower-case characters to + define token strings is for editorial clarity only. Implementations + MUST accept these strings in a case-insensitive fashion. + + capability =/ "SEARCHRES" + ;; capability is defined in [IMAP4] + + sequence-set =/ seq-last-command + ;; extends sequence-set to allow for + ;; "result of the last command" indicator. + + seq-last-command = "$" + + search-return-opt = "SAVE" + ;; conforms to generic search-return-opt + ;; syntax defined in [IMAPABNF] + + resp-text-code =/ "NOTSAVED" + ;; from [IMAP4] + + + + + + + + + + + + + + +Melnikov Standards Track [Page 10] + +RFC 5182 Last SEARCH Result Reference March 2008 + + +4. Security Considerations + + This extension requires the server to keep additional state, that may + be used to simplify Denial of Service attacks. In order to minimize + damage from such attacks, server implementations MAY limit the number + of saved searches they allow across all connections at any given time + and return the tagged NO response containing the NOTSAVED response + code (see Section 2.5) to a SEARCH RETURN (SAVE) command when this + limit is exceeded. + + Apart from that, it is believed that this extension doesn't raise any + additional security concerns not already discussed in [IMAP4]. + +5. IANA Considerations + + This document defines the "SEARCHRES" IMAP capability. IANA has + added it to the IMAP4 Capabilities Registry, which is currently + located at: + + http://www.iana.org/assignments/imap4-capabilities + +6. Acknowledgments + + The author would like to thank Mark Crispin, Cyrus Daboo, and Curtis + King for remembering that this document had to be written, as well as + for comments and corrections received. + + The author would also like to thank Dave Cridland, Mark Crispin, + Chris Newman, Dan Karp, and Spencer Dawkins for comments and + corrections received. + + Valuable comments, both in agreement and in dissent, were received + from Arnt Gulbrandsen. + + + + + + + + + + + + + + + + + + +Melnikov Standards Track [Page 11] + +RFC 5182 Last SEARCH Result Reference March 2008 + + +7. References + +7.1. Normative References + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [ABNF] Crocker, D., Ed., and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", STD 68, RFC 5234, January + 2008. + + [IMAP4] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [IMAPABNF] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 + ABNF", RFC 4466, April 2006. + + [ESEARCH] Melnikov, A. and D. Cridland, "IMAP4 Extension to SEARCH + Command for Controlling What Kind of Information Is + Returned", RFC 4731, November 2006. + +7.2. Informative References + + [UIDPLUS] Crispin, M., "Internet Message Access Protocol (IMAP) - + UIDPLUS extension", RFC 4315, December 2005. + + [SORT] Crispin, M. and K. Murchison, "INTERNET MESSAGE ACCESS + PROTOCOL - SORT AND THREAD EXTENSIONS", Work in Progress, + Septemeber 2007. + +Author's Address + + Alexey Melnikov + Isode Ltd. + 5 Castle Business Village, + 36 Station Road, + Hampton, Middlesex, + TW12 2BX, United Kingdom + + EMail: Alexey.Melnikov@isode.com + + + + + + + + + + + +Melnikov Standards Track [Page 12] + +RFC 5182 Last SEARCH Result Reference March 2008 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2008). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Melnikov Standards Track [Page 13] + diff --git a/docs/rfcs/rfc5182.Sieve_and_extensions.txt b/docs/rfcs/rfc5182.Sieve_and_extensions.txt new file mode 100644 index 0000000..e5a02c6 --- /dev/null +++ b/docs/rfcs/rfc5182.Sieve_and_extensions.txt @@ -0,0 +1,2355 @@ + + + + + + +Network Working Group P. Guenther, Ed. +Request for Comments: 5228 Sendmail, Inc. +Obsoletes: 3028 T. Showalter, Ed. +Category: Standards Track January 2008 + + + Sieve: An Email Filtering Language + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + This document describes a language for filtering email messages at + time of final delivery. It is designed to be implementable on either + a mail client or mail server. It is meant to be extensible, simple, + and independent of access protocol, mail architecture, and operating + system. It is suitable for running on a mail server where users may + not be allowed to execute arbitrary programs, such as on black box + Internet Message Access Protocol (IMAP) servers, as the base language + has no variables, loops, or ability to shell out to external + programs. + + + + + + + + + + + + + + + + + + + + + + + + +Guenther & Showalter Standards Track [Page 1] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + +Table of Contents + + 1. Introduction ....................................................4 + 1.1. Conventions Used in This Document ..........................4 + 1.2. Example Mail Messages ......................................5 + 2. Design ..........................................................6 + 2.1. Form of the Language .......................................6 + 2.2. Whitespace .................................................7 + 2.3. Comments ...................................................7 + 2.4. Literal Data ...............................................7 + 2.4.1. Numbers .............................................7 + 2.4.2. Strings .............................................8 + 2.4.2.1. String Lists ...............................9 + 2.4.2.2. Headers ....................................9 + 2.4.2.3. Addresses .................................10 + 2.4.2.4. Encoding Characters Using + "encoded-character" .......................10 + 2.5. Tests .....................................................11 + 2.5.1. Test Lists .........................................12 + 2.6. Arguments .................................................12 + 2.6.1. Positional Arguments ...............................12 + 2.6.2. Tagged Arguments ...................................12 + 2.6.3. Optional Arguments .................................13 + 2.6.4. Types of Arguments .................................13 + 2.7. String Comparison .........................................13 + 2.7.1. Match Type .........................................14 + 2.7.2. Comparisons across Character Sets ..................15 + 2.7.3. Comparators ........................................15 + 2.7.4. Comparisons against Addresses ......................16 + 2.8. Blocks ....................................................17 + 2.9. Commands ..................................................17 + 2.10. Evaluation ...............................................18 + 2.10.1. Action Interaction ................................18 + 2.10.2. Implicit Keep .....................................18 + 2.10.3. Message Uniqueness in a Mailbox ...................19 + 2.10.4. Limits on Numbers of Actions ......................19 + 2.10.5. Extensions and Optional Features ..................19 + 2.10.6. Errors ............................................20 + 2.10.7. Limits on Execution ...............................20 + 3. Control Commands ...............................................21 + 3.1. Control if ................................................21 + 3.2. Control require ...........................................22 + 3.3. Control stop ..............................................22 + 4. Action Commands ................................................23 + 4.1. Action fileinto ...........................................23 + 4.2. Action redirect ...........................................23 + 4.3. Action keep ...............................................24 + 4.4. Action discard ............................................25 + + + +Guenther & Showalter Standards Track [Page 2] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + 5. Test Commands ..................................................26 + 5.1. Test address ..............................................26 + 5.2. Test allof ................................................27 + 5.3. Test anyof ................................................27 + 5.4. Test envelope .............................................27 + 5.5. Test exists ...............................................28 + 5.6. Test false ................................................28 + 5.7. Test header ...............................................29 + 5.8. Test not ..................................................29 + 5.9. Test size .................................................29 + 5.10. Test true ................................................30 + 6. Extensibility ..................................................30 + 6.1. Capability String .........................................31 + 6.2. IANA Considerations .......................................31 + 6.2.1. Template for Capability Registrations ..............32 + 6.2.2. Handling of Existing Capability Registrations ......32 + 6.2.3. Initial Capability Registrations ...................32 + 6.3. Capability Transport ......................................33 + 7. Transmission ...................................................33 + 8. Parsing ........................................................34 + 8.1. Lexical Tokens ............................................34 + 8.2. Grammar ...................................................36 + 8.3. Statement Elements ........................................36 + 9. Extended Example ...............................................37 + 10. Security Considerations .......................................38 + 11. Acknowledgments ...............................................39 + 12. Normative References ..........................................39 + 13. Informative References ........................................40 + 14. Changes from RFC 3028 .........................................41 + + + + + + + + + + + + + + + + + + + + + + +Guenther & Showalter Standards Track [Page 3] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + +1. Introduction + + This memo documents a language that can be used to create filters for + electronic mail. It is not tied to any particular operating system + or mail architecture. It requires the use of [IMAIL]-compliant + messages, but should otherwise generalize to many systems. + + The language is powerful enough to be useful but limited in order to + allow for a safe server-side filtering system. The intention is to + make it impossible for users to do anything more complex (and + dangerous) than write simple mail filters, along with facilitating + the use of graphical user interfaces (GUIs) for filter creation and + manipulation. The base language was not designed to be Turing- + complete: it does not have a loop control structure or functions. + + Scripts written in Sieve are executed during final delivery, when the + message is moved to the user-accessible mailbox. In systems where + the Mail Transfer Agent (MTA) does final delivery, such as + traditional Unix mail, it is reasonable to filter when the MTA + deposits mail into the user's mailbox. + + There are a number of reasons to use a filtering system. Mail + traffic for most users has been increasing due to increased usage of + email, the emergence of unsolicited email as a form of advertising, + and increased usage of mailing lists. + + Experience at Carnegie Mellon has shown that if a filtering system is + made available to users, many will make use of it in order to file + messages from specific users or mailing lists. However, many others + did not make use of the Andrew system's FLAMES filtering language + [FLAMES] due to difficulty in setting it up. + + Because of the expectation that users will make use of filtering if + it is offered and easy to use, this language has been made simple + enough to allow many users to make use of it, but rich enough that it + can be used productively. However, it is expected that GUI-based + editors will be the preferred way of editing filters for a large + number of users. + +1.1. Conventions Used in This Document + + In the sections of this document that discuss the requirements of + various keywords and operators, the following conventions have been + adopted. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [KEYWORDS]. + + + +Guenther & Showalter Standards Track [Page 4] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + Each section on a command (test, action, or control) has a line + labeled "Usage:". This line describes the usage of the command, + including its name and its arguments. Required arguments are listed + inside angle brackets ("<" and ">"). Optional arguments are listed + inside square brackets ("[" and "]"). Each argument is followed by + its type, so "" represents an argument called "key" that + is a string. Literal strings are represented with double-quoted + strings. Alternatives are separated with slashes, and parentheses + are used for grouping, similar to [ABNF]. + + In the "Usage:" line, there are three special pieces of syntax that + are frequently repeated, MATCH-TYPE, COMPARATOR, and ADDRESS-PART. + These are discussed in sections 2.7.1, 2.7.3, and 2.7.4, + respectively. + + The formal grammar for these commands is defined in section 8 and is + the authoritative reference on how to construct commands, but the + formal grammar does not specify the order, semantics, number or types + of arguments to commands, or the legal command names. The intent is + to allow for extension without changing the grammar. + +1.2. Example Mail Messages + + The following mail messages will be used throughout this document in + examples. + + Message A + ----------------------------------------------------------- + Date: Tue, 1 Apr 1997 09:06:31 -0800 (PST) + From: coyote@desert.example.org + To: roadrunner@acme.example.com + Subject: I have a present for you + + Look, I'm sorry about the whole anvil thing, and I really + didn't mean to try and drop it on you from the top of the + cliff. I want to try to make it up to you. I've got some + great birdseed over here at my place--top of the line + stuff--and if you come by, I'll have it all wrapped up + for you. I'm really sorry for all the problems I've caused + for you over the years, but I know we can work this out. + -- + Wile E. Coyote "Super Genius" coyote@desert.example.org + ----------------------------------------------------------- + + + + + + + + +Guenther & Showalter Standards Track [Page 5] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + Message B + ----------------------------------------------------------- + From: youcouldberich!@reply-by-postal-mail.invalid + Sender: b1ff@de.res.example.com + To: rube@landru.example.com + Date: Mon, 31 Mar 1997 18:26:10 -0800 + Subject: $$$ YOU, TOO, CAN BE A MILLIONAIRE! $$$ + + YOU MAY HAVE ALREADY WON TEN MILLION DOLLARS, BUT I DOUBT + IT! SO JUST POST THIS TO SIX HUNDRED NEWSGROUPS! IT WILL + GUARANTEE THAT YOU GET AT LEAST FIVE RESPONSES WITH MONEY! + MONEY! MONEY! COLD HARD CASH! YOU WILL RECEIVE OVER + $20,000 IN LESS THAN TWO MONTHS! AND IT'S LEGAL!!!!!!!!! + !!!!!!!!!!!!!!!!!!111111111!!!!!!!11111111111!!1 JUST + SEND $5 IN SMALL, UNMARKED BILLS TO THE ADDRESSES BELOW! + ----------------------------------------------------------- + +2. Design + +2.1. Form of the Language + + The language consists of a set of commands. Each command consists of + a set of tokens delimited by whitespace. The command identifier is + the first token and it is followed by zero or more argument tokens. + Arguments may be literal data, tags, blocks of commands, or test + commands. + + With the exceptions of strings and comments, the language is limited + to US-ASCII characters. Strings and comments may contain octets + outside the US-ASCII range. Specifically, they will normally be in + UTF-8, as specified in [UTF-8]. NUL (US-ASCII 0) is never permitted + in scripts, while CR and LF can only appear as the CRLF line ending. + + Note: While this specification permits arbitrary octets to appear + in Sieve scripts inside strings and comments, this has made it + difficult to robustly handle Sieve scripts in programs that are + sensitive to the encodings used. The "encoded-character" + capability (section 2.4.2.4) provides an alternative means of + representing such octets in strings using just US-ASCII + characters. As such, the use of non-UTF-8 text in scripts should + be considered a deprecated feature that may be abandoned. + + Tokens other than strings are considered case-insensitive. + + + + + + + + +Guenther & Showalter Standards Track [Page 6] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + +2.2. Whitespace + + Whitespace is used to separate tokens. Whitespace is made up of + tabs, newlines (CRLF, never just CR or LF), and the space character. + The amount of whitespace used is not significant. + +2.3. Comments + + Two types of comments are offered. Comments are semantically + equivalent to whitespace and can be used anyplace that whitespace is + (with one exception in multi-line strings, as described in the + grammar). + + Hash comments begin with a "#" character that is not contained within + a string and continue until the next CRLF. + + Example: if size :over 100k { # this is a comment + discard; + } + + Bracketed comments begin with the token "/*" and end with "*/" + outside of a string. Bracketed comments may span multiple lines. + Bracketed comments do not nest. + + Example: if size :over 100K { /* this is a comment + this is still a comment */ discard /* this is a comment + */ ; + } + +2.4. Literal Data + + Literal data means data that is not executed, merely evaluated "as + is", to be used as arguments to commands. Literal data is limited to + numbers, strings, and string lists. + +2.4.1. Numbers + + Numbers are given as ordinary decimal numbers. As a shorthand for + expressing larger values, such as message sizes, a suffix of "K", + "M", or "G" MAY be appended to indicate a multiple of a power of two. + To be comparable with the power-of-two-based versions of SI units + that computers frequently use, "K" specifies kibi-, or 1,024 (2^10) + times the value of the number; "M" specifies mebi-, or 1,048,576 + (2^20) times the value of the number; and "G" specifies gibi-, or + 1,073,741,824 (2^30) times the value of the number [BINARY-SI]. + + + + + + +Guenther & Showalter Standards Track [Page 7] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + Implementations MUST support integer values in the inclusive range + zero to 2,147,483,647 (2^31 - 1), but MAY support larger values. + + Only non-negative integers are permitted by this specification. + +2.4.2. Strings + + Scripts involve large numbers of string values as they are used for + pattern matching, addresses, textual bodies, etc. Typically, short + quoted strings suffice for most uses, but a more convenient form is + provided for longer strings such as bodies of messages. + + A quoted string starts and ends with a single double quote (the <"> + character, US-ASCII 34). A backslash ("\", US-ASCII 92) inside of a + quoted string is followed by either another backslash or a double + quote. These two-character sequences represent a single backslash or + double quote within the value, respectively. + + Scripts SHOULD NOT escape other characters with a backslash. + + An undefined escape sequence (such as "\a" in a context where "a" has + no special meaning) is interpreted as if there were no backslash (in + this case, "\a" is just "a"), though that may be changed by + extensions. + + Non-printing characters such as tabs, CRLF, and control characters + are permitted in quoted strings. Quoted strings MAY span multiple + lines. An unencoded NUL (US-ASCII 0) is not allowed in strings; see + section 2.4.2.4 for how it can be encoded. + + As message header data is converted to [UTF-8] for comparison (see + section 2.7.2), most string values will use the UTF-8 encoding. + However, implementations MUST accept all strings that match the + grammar in section 8. The ability to use non-UTF-8 encoded strings + matches existing practice and has proven to be useful both in tests + for invalid data and in arguments containing raw MIME parts for + extension actions that generate outgoing messages. + + For entering larger amounts of text, such as an email message, a + multi-line form is allowed. It starts with the keyword "text:", + followed by a CRLF, and ends with the sequence of a CRLF, a single + period, and another CRLF. The CRLF before the final period is + considered part of the value. In order to allow the message to + contain lines with a single dot, lines are dot-stuffed. That is, + when composing a message body, an extra '.' is added before each line + that begins with a '.'. When the server interprets the script, these + extra dots are removed. Note that a line that begins with a dot + followed by a non-dot character is not interpreted as dot-stuffed; + + + +Guenther & Showalter Standards Track [Page 8] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + that is, ".foo" is interpreted as ".foo". However, because this is + potentially ambiguous, scripts SHOULD be properly dot-stuffed so such + lines do not appear. + + Note that a hashed comment or whitespace may occur in between the + "text:" and the CRLF, but not within the string itself. Bracketed + comments are not allowed here. + +2.4.2.1. String Lists + + When matching patterns, it is frequently convenient to match against + groups of strings instead of single strings. For this reason, a list + of strings is allowed in many tests, implying that if the test is + true using any one of the strings, then the test is true. + + For instance, the test 'header :contains ["To", "Cc"] + ["me@example.com", "me00@landru.example.com"]' is true if either a To + header or Cc header of the input message contains either of the email + addresses "me@example.com" or "me00@landru.example.com". + + Conversely, in any case where a list of strings is appropriate, a + single string is allowed without being a member of a list: it is + equivalent to a list with a single member. This means that the test + 'exists "To"' is equivalent to the test 'exists ["To"]'. + +2.4.2.2. Headers + + Headers are a subset of strings. In the Internet Message + Specification [IMAIL], each header line is allowed to have whitespace + nearly anywhere in the line, including after the field name and + before the subsequent colon. Extra spaces between the header name + and the ":" in a header field are ignored. + + A header name never contains a colon. The "From" header refers to a + line beginning "From:" (or "From :", etc.). No header will match + the string "From:" due to the trailing colon. + + Similarly, no header will match a syntactically invalid header name. + An implementation MUST NOT cause an error for syntactically invalid + header names in tests. + + Header lines are unfolded as described in [IMAIL] section 2.2.3. + Interpretation of header data SHOULD be done according to [MIME3] + section 6.2 (see section 2.7.2 below for details). + + + + + + + +Guenther & Showalter Standards Track [Page 9] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + +2.4.2.3. Addresses + + A number of commands call for email addresses, which are also a + subset of strings. When these addresses are used in outbound + contexts, addresses must be compliant with [IMAIL], but are further + constrained within this document. Using the symbols defined in + [IMAIL], section 3, the syntax of an address is: + + sieve-address = addr-spec ; simple address + / phrase "<" addr-spec ">" ; name & addr-spec + + That is, routes and group syntax are not permitted. If multiple + addresses are required, use a string list. Named groups are not + permitted. + + It is an error for a script to execute an action with a value for use + as an outbound address that doesn't match the "sieve-address" syntax. + +2.4.2.4. Encoding Characters Using "encoded-character" + + When the "encoded-character" extension is in effect, certain + character sequences in strings are replaced by their decoded value. + This happens after escape sequences are interpreted and dot- + unstuffing has been done. Implementations SHOULD support "encoded- + character". + + Arbitrary octets can be embedded in strings by using the syntax + encoded-arb-octets. The sequence is replaced by the octets with the + hexadecimal values given by each hex-pair. + + blank = WSP / CRLF + encoded-arb-octets = "${hex:" hex-pair-seq "}" + hex-pair-seq = *blank hex-pair *(1*blank hex-pair) *blank + hex-pair = 1*2HEXDIG + + Where WSP and HEXDIG non-terminals are defined in Appendix B.1 of + [ABNF]. + + It may be inconvenient or undesirable to enter Unicode characters + verbatim, and for these cases the syntax encoded-unicode-char can be + used. The sequence is replaced by the UTF-8 encoding of the + specified Unicode characters, which are identified by the hexadecimal + value of unicode-hex. + + encoded-unicode-char = "${unicode:" unicode-hex-seq "}" + unicode-hex-seq = *blank unicode-hex + *(1*blank unicode-hex) *blank + unicode-hex = 1*HEXDIG + + + +Guenther & Showalter Standards Track [Page 10] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + It is an error for a script to use a hexadecimal value that isn't in + either the range 0 to D7FF or the range E000 to 10FFFF. (The range + D800 to DFFF is excluded as those character numbers are only used as + part of the UTF-16 encoding form and are not applicable to the UTF-8 + encoding that the syntax here represents.) + + Note: Implementations MUST NOT raise an error for an out-of-range + Unicode value unless the sequence containing it is well-formed + according to the grammar. + + The capability string for use with the require command is "encoded- + character". + + In the following script, message B is discarded, since the specified + test string is equivalent to "$$$". + + Example: require "encoded-character"; + if header :contains "Subject" "$${hex:24 24}" { + discard; + } + The following examples demonstrate valid and invalid encodings and + how they are handled: + + "$${hex:40}" -> "$@" + "${hex: 40 }" -> "@" + "${HEX: 40}" -> "@" + "${hex:40" -> "${hex:40" + "${hex:400}" -> "${hex:400}" + "${hex:4${hex:30}}" -> "${hex:40}" + "${unicode:40}" -> "@" + "${ unicode:40}" -> "${ unicode:40}" + "${UNICODE:40}" -> "@" + "${UnICoDE:0000040}" -> "@" + "${Unicode:40}" -> "@" + "${Unicode:Cool}" -> "${Unicode:Cool}" + "${unicode:200000}" -> error + "${Unicode:DF01} -> error + +2.5. Tests + + Tests are given as arguments to commands in order to control their + actions. In this document, tests are given to if/elsif to decide + which block of code is run. + + + + + + + + +Guenther & Showalter Standards Track [Page 11] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + +2.5.1. Test Lists + + Some tests ("allof" and "anyof", which implement logical "and" and + logical "or", respectively) may require more than a single test as an + argument. The test-list syntax element provides a way of grouping + tests as a comma-separated list in parentheses. + + Example: if anyof (not exists ["From", "Date"], + header :contains "from" "fool@example.com") { + discard; + } + +2.6. Arguments + + In order to specify what to do, most commands take arguments. There + are three types of arguments: positional, tagged, and optional. + + It is an error for a script, on a single command, to use conflicting + arguments or to use a tagged or optional argument more than once. + +2.6.1. Positional Arguments + + Positional arguments are given to a command that discerns their + meaning based on their order. When a command takes positional + arguments, all positional arguments must be supplied and must be in + the order prescribed. + +2.6.2. Tagged Arguments + + This document provides for tagged arguments in the style of + CommonLISP. These are also similar to flags given to commands in + most command-line systems. + + A tagged argument is an argument for a command that begins with ":" + followed by a tag naming the argument, such as ":contains". This + argument means that zero or more of the next tokens have some + particular meaning depending on the argument. These next tokens may + be literal data, but they are never blocks. + + Tagged arguments are similar to positional arguments, except that + instead of the meaning being derived from the command, it is derived + from the tag. + + Tagged arguments must appear before positional arguments, but they + may appear in any order with other tagged arguments. For simplicity + of the specification, this is not expressed in the syntax definitions + + + + + +Guenther & Showalter Standards Track [Page 12] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + with commands, but they still may be reordered arbitrarily provided + they appear before positional arguments. Tagged arguments may be + mixed with optional arguments. + + Tagged arguments SHOULD NOT take tagged arguments as arguments. + +2.6.3. Optional Arguments + + Optional arguments are exactly like tagged arguments except that they + may be left out, in which case a default value is implied. Because + optional arguments tend to result in shorter scripts, they have been + used far more than tagged arguments. + + One particularly noteworthy case is the ":comparator" argument, which + allows the user to specify which comparator [COLLATION] will be used + to compare two strings, since different languages may impose + different orderings on UTF-8 [UTF-8] strings. + +2.6.4. Types of Arguments + + Abstractly, arguments may be literal data, tests, or blocks of + commands. In this way, an "if" control structure is merely a command + that happens to take a test and a block as arguments and may execute + the block of code. + + However, this abstraction is ambiguous from a parsing standpoint. + + The grammar in section 8.2 presents a parsable version of this: + Arguments are string lists (string-lists), numbers, and tags, which + may be followed by a test or a test list (test-list), which may be + followed by a block of commands. No more than one test or test list, + or more than one block of commands, may be used, and commands that + end with a block of commands do not end with semicolons. + +2.7. String Comparison + + When matching one string against another, there are a number of ways + of performing the match operation. These are accomplished with three + types of matches: an exact match, a substring match, and a wildcard + glob-style match. These are described below. + + In order to provide for matches between character sets and case + insensitivity, Sieve uses the comparators defined in the Internet + Application Protocol Collation Registry [COLLATION]. + + + + + + + +Guenther & Showalter Standards Track [Page 13] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + However, when a string represents the name of a header, the + comparator is never user-specified. Header comparisons are always + done with the "i;ascii-casemap" operator, i.e., case-insensitive + comparisons, because this is the way things are defined in the + message specification [IMAIL]. + +2.7.1. Match Type + + Commands that perform string comparisons may have an optional match + type argument. The three match types in this specification are + ":contains", ":is", and ":matches". + + The ":contains" match type describes a substring match. If the value + argument contains the key argument as a substring, the match is true. + For instance, the string "frobnitzm" contains "frob" and "nit", but + not "fbm". The empty key ("") is contained in all values. + + The ":is" match type describes an absolute match; if the contents of + the first string are absolutely the same as the contents of the + second string, they match. Only the string "frobnitzm" is the string + "frobnitzm". The empty key ("") only ":is" matches with the empty + value. + + The ":matches" match type specifies a wildcard match using the + characters "*" and "?"; the entire value must be matched. "*" + matches zero or more characters in the value and "?" matches a single + character in the value, where the comparator that is used (see + section 2.7.3) defines what a character is. For example, the + comparators "i;octet" and "i;ascii-casemap" define a character to be + a single octet, so "?" will always match exactly one octet when one + of those comparators is in use. In contrast, a Unicode-based + comparator would define a character to be any UTF-8 octet sequence + encoding one Unicode character and thus "?" may match more than one + octet. "?" and "*" may be escaped as "\\?" and "\\*" in strings to + match against themselves. The first backslash escapes the second + backslash; together, they escape the "*". This is awkward, but it is + commonplace in several programming languages that use globs and + regular expressions. + + In order to specify what type of match is supposed to happen, + commands that support matching take optional arguments ":matches", + ":is", and ":contains". Commands default to using ":is" matching if + no match type argument is supplied. Note that these modifiers + interact with comparators; in particular, only comparators that + support the "substring match" operation are suitable for matching + with ":contains" or ":matches". It is an error to use a comparator + with ":contains" or ":matches" that is not compatible with it. + + + + +Guenther & Showalter Standards Track [Page 14] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + It is an error to give more than one of these arguments to a given + command. + + For convenience, the "MATCH-TYPE" syntax element is defined here as + follows: + + Syntax: ":is" / ":contains" / ":matches" + +2.7.2. Comparisons across Character Sets + + Messages may involve a number of character sets. In order for + comparisons to work across character sets, implementations SHOULD + implement the following behavior: + + Comparisons are performed on octets. Implementations convert text + from header fields in all charsets [MIME3] to Unicode, encoded as + UTF-8, as input to the comparator (see section 2.7.3). + Implementations MUST be capable of converting US-ASCII, ISO-8859- + 1, the US-ASCII subset of ISO-8859-* character sets, and UTF-8. + Text that the implementation cannot convert to Unicode for any + reason MAY be treated as plain US-ASCII (including any [MIME3] + syntax) or processed according to local conventions. An encoded + NUL octet (character zero) SHOULD NOT cause early termination of + the header content being compared against. + + If implementations fail to support the above behavior, they MUST + conform to the following: + + No two strings can be considered equal if one contains octets + greater than 127. + +2.7.3. Comparators + + In order to allow for language-independent, case-independent matches, + the match type may be coupled with a comparator name. The Internet + Application Protocol Collation Registry [COLLATION] provides the + framework for describing and naming comparators. + + All implementations MUST support the "i;octet" comparator (simply + compares octets) and the "i;ascii-casemap" comparator (which treats + uppercase and lowercase characters in the US-ASCII subset of UTF-8 as + the same). If left unspecified, the default is "i;ascii-casemap". + + Some comparators may not be usable with substring matches; that is, + they may only work with ":is". It is an error to try to use a + comparator with ":matches" or ":contains" that is not compatible with + it. + + + + +Guenther & Showalter Standards Track [Page 15] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + Sieve treats a comparator result of "undefined" the same as a result + of "no-match". That is, this base specification does not provide any + means to directly detect invalid comparator input. + + A comparator is specified by the ":comparator" option with commands + that support matching. This option is followed by a string providing + the name of the comparator to be used. For convenience, the syntax + of a comparator is abbreviated to "COMPARATOR", and (repeated in + several tests) is as follows: + + Syntax: ":comparator" + + So in this example, + + Example: if header :contains :comparator "i;octet" "Subject" + "MAKE MONEY FAST" { + discard; + } + + would discard any message with subjects like "You can MAKE MONEY + FAST", but not "You can Make Money Fast", since the comparator used + is case-sensitive. + + Comparators other than "i;octet" and "i;ascii-casemap" must be + declared with require, as they are extensions. If a comparator + declared with require is not known, it is an error, and execution + fails. If the comparator is not declared with require, it is also an + error, even if the comparator is supported. (See section 2.10.5.) + + Both ":matches" and ":contains" match types are compatible with the + "i;octet" and "i;ascii-casemap" comparators and may be used with + them. + + It is an error to give more than one of these arguments to a given + command. + +2.7.4. Comparisons against Addresses + + Addresses are one of the most frequent things represented as strings. + These are structured, and being able to compare against the local- + part or the domain of an address is useful, so some tests that act + exclusively on addresses take an additional optional argument that + specifies what the test acts on. + + These optional arguments are ":localpart", ":domain", and ":all", + which act on the local-part (left side), the domain-part (right + side), and the whole address. + + + + +Guenther & Showalter Standards Track [Page 16] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + If an address is not syntactically valid, then it will not be matched + by tests specifying ":localpart" or ":domain". + + The kind of comparison done, such as whether or not the test done is + case-insensitive, is specified as a comparator argument to the test. + + If an optional address-part is omitted, the default is ":all". + + It is an error to give more than one of these arguments to a given + command. + + For convenience, the "ADDRESS-PART" syntax element is defined here as + follows: + + Syntax: ":localpart" / ":domain" / ":all" + +2.8. Blocks + + Blocks are sets of commands enclosed within curly braces and supplied + as the final argument to a command. Such a command is a control + structure: when executed it has control over the number of times the + commands in the block are executed. + + With the commands supplied in this memo, there are no loops. The + control structures supplied--if, elsif, and else--run a block either + once or not at all. + +2.9. Commands + + Sieve scripts are sequences of commands. Commands can take any of + the tokens above as arguments, and arguments may be either tagged or + positional arguments. Not all commands take all arguments. + + There are three kinds of commands: test commands, action commands, + and control commands. + + The simplest is an action command. An action command is an + identifier followed by zero or more arguments, terminated by a + semicolon. Action commands do not take tests or blocks as arguments. + The actions referenced in this document are: + + - keep, to save the message in the default location + - fileinto, to save the message in a specific mailbox + - redirect, to forward the message to another address + - discard, to silently throw away the message + + + + + + +Guenther & Showalter Standards Track [Page 17] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + A control command is a command that affects the parsing or the flow + of execution of the Sieve script in some way. A control structure is + a control command that ends with a block instead of a semicolon. + + A test command is used as part of a control command. It is used to + specify whether or not the block of code given to the control command + is executed. + +2.10. Evaluation + +2.10.1. Action Interaction + + Some actions cannot be used with other actions because the result + would be absurd. These restrictions are noted throughout this memo. + + Extension actions MUST state how they interact with actions defined + in this specification. + +2.10.2. Implicit Keep + + Previous experience with filtering systems suggests that cases tend + to be missed in scripts. To prevent errors, Sieve has an "implicit + keep". + + An implicit keep is a keep action (see section 4.3) performed in + absence of any action that cancels the implicit keep. + + An implicit keep is performed if a message is not written to a + mailbox, redirected to a new address, or explicitly thrown out. That + is, if a fileinto, a keep, a redirect, or a discard is performed, an + implicit keep is not. + + Some actions may be defined to not cancel the implicit keep. These + actions may not directly affect the delivery of a message, and are + used for their side effects. None of the actions specified in this + document meet that criteria, but extension actions may. + + For instance, with any of the short messages offered above, the + following script produces no actions. + + Example: if size :over 500K { discard; } + + As a result, the implicit keep is taken. + + + + + + + + +Guenther & Showalter Standards Track [Page 18] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + +2.10.3. Message Uniqueness in a Mailbox + + Implementations SHOULD NOT deliver a message to the same mailbox more + than once, even if a script explicitly asks for a message to be + written to a mailbox twice. + + The test for equality of two messages is implementation-defined. + + If a script asks for a message to be written to a mailbox twice, it + MUST NOT be treated as an error. + +2.10.4. Limits on Numbers of Actions + + Site policy MAY limit the number of actions taken and MAY impose + restrictions on which actions can be used together. In the event + that a script hits a policy limit on the number of actions taken for + a particular message, an error occurs. + + Implementations MUST allow at least one keep or one fileinto. If + fileinto is not implemented, implementations MUST allow at least one + keep. + +2.10.5. Extensions and Optional Features + + Because of the differing capabilities of many mail systems, several + features of this specification are optional. Before any of these + extensions can be executed, they must be declared with the "require" + action. + + If an extension is not enabled with "require", implementations MUST + treat it as if they did not support it at all. This protects scripts + from having their behavior altered by extensions that the script + author might not have even been aware of. + + Implementations MUST NOT execute any Sieve script test or command + subsequent to "require" if one of the required extensions is + unavailable. + + Note: The reason for this restriction is that prior experiences + with languages such as LISP and Tcl suggest that this is a + workable way of noting that a given script uses an extension. + + Extensions that define actions MUST state how they interact with + actions discussed in the base specification. + + + + + + + +Guenther & Showalter Standards Track [Page 19] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + +2.10.6. Errors + + In any programming language, there are compile-time and run-time + errors. + + Compile-time errors are ones in syntax that are detectable if a + syntax check is done. + + Run-time errors are not detectable until the script is run. This + includes transient failures like disk full conditions, but also + includes issues like invalid combinations of actions. + + When an error occurs in a Sieve script, all processing stops. + + Implementations MAY choose to do a full parse, then evaluate the + script, then do all actions. Implementations might even go so far as + to ensure that execution is atomic (either all actions are executed + or none are executed). + + Other implementations may choose to parse and run at the same time. + Such implementations are simpler, but have issues with partial + failure (some actions happen, others don't). + + Implementations MUST perform syntactic, semantic, and run-time checks + on code that is actually executed. Implementations MAY perform those + checks or any part of them on code that is not reached during + execution. + + When an error happens, implementations MUST notify the user that an + error occurred and which actions (if any) were taken, and do an + implicit keep. + +2.10.7. Limits on Execution + + Implementations may limit certain constructs. However, this + specification places a lower bound on some of these limits. + + Implementations MUST support fifteen levels of nested blocks. + + Implementations MUST support fifteen levels of nested test lists. + + + + + + + + + + + +Guenther & Showalter Standards Track [Page 20] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + +3. Control Commands + + Control structures are needed to allow for multiple and conditional + actions. + +3.1. Control if + + There are three pieces to if: "if", "elsif", and "else". Each is + actually a separate command in terms of the grammar. However, an + elsif or else MUST only follow an if or elsif. An error occurs if + these conditions are not met. + + Usage: if + + Usage: elsif + + Usage: else + + The semantics are similar to those of any of the many other + programming languages these control structures appear in. When the + interpreter sees an "if", it evaluates the test associated with it. + If the test is true, it executes the block associated with it. + + If the test of the "if" is false, it evaluates the test of the first + "elsif" (if any). If the test of "elsif" is true, it runs the + elsif's block. An elsif may be followed by an elsif, in which case, + the interpreter repeats this process until it runs out of elsifs. + + When the interpreter runs out of elsifs, there may be an "else" case. + If there is, and none of the if or elsif tests were true, the + interpreter runs the else's block. + + This provides a way of performing exactly one of the blocks in the + chain. + + In the following example, both messages A and B are dropped. + + Example: require "fileinto"; + if header :contains "from" "coyote" { + discard; + } elsif header :contains ["subject"] ["$$$"] { + discard; + } else { + fileinto "INBOX"; + } + + + + + + +Guenther & Showalter Standards Track [Page 21] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + When the script below is run over message A, it redirects the message + to acm@example.com; message B, to postmaster@example.com; any other + message is redirected to field@example.com. + + Example: if header :contains ["From"] ["coyote"] { + redirect "acm@example.com"; + } elsif header :contains "Subject" "$$$" { + redirect "postmaster@example.com"; + } else { + redirect "field@example.com"; + } + + Note that this definition prohibits the "... else if ..." sequence + used by C. This is intentional, because this construct produces a + shift-reduce conflict. + +3.2. Control require + + Usage: require + + The require action notes that a script makes use of a certain + extension. Such a declaration is required to use the extension, as + discussed in section 2.10.5. Multiple capabilities can be declared + with a single require. + + The require command, if present, MUST be used before anything other + than a require can be used. An error occurs if a require appears + after a command other than require. + + Example: require ["fileinto", "reject"]; + + Example: require "fileinto"; + require "vacation"; + +3.3. Control stop + + Usage: stop + + The "stop" action ends all processing. If the implicit keep has not + been cancelled, then it is taken. + + + + + + + + + + + +Guenther & Showalter Standards Track [Page 22] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + +4. Action Commands + + This document supplies four actions that may be taken on a message: + keep, fileinto, redirect, and discard. + + Implementations MUST support the "keep", "discard", and "redirect" + actions. + + Implementations SHOULD support "fileinto". + + Implementations MAY limit the number of certain actions taken (see + section 2.10.4). + +4.1. Action fileinto + + Usage: fileinto + + The "fileinto" action delivers the message into the specified + mailbox. Implementations SHOULD support fileinto, but in some + environments this may be impossible. Implementations MAY place + restrictions on mailbox names; use of an invalid mailbox name MAY be + treated as an error or result in delivery to an implementation- + defined mailbox. If the specified mailbox doesn't exist, the + implementation MAY treat it as an error, create the mailbox, or + deliver the message to an implementation-defined mailbox. If the + implementation uses a different encoding scheme than UTF-8 for + mailbox names, it SHOULD reencode the mailbox name from UTF-8 to its + encoding scheme. For example, the Internet Message Access Protocol + [IMAP] uses modified UTF-7, such that a mailbox argument of "odds & + ends" would appear in IMAP as "odds &- ends". + + The capability string for use with the require command is "fileinto". + + In the following script, message A is filed into mailbox + "INBOX.harassment". + + Example: require "fileinto"; + if header :contains ["from"] "coyote" { + fileinto "INBOX.harassment"; + } + +4.2. Action redirect + + Usage: redirect + + The "redirect" action is used to send the message to another user at + a supplied address, as a mail forwarding feature does. The + "redirect" action makes no changes to the message body or existing + + + +Guenther & Showalter Standards Track [Page 23] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + headers, but it may add new headers. In particular, existing + Received headers MUST be preserved and the count of Received headers + in the outgoing message MUST be larger than the same count on the + message as received by the implementation. (An implementation that + adds a Received header before processing the message does not need to + add another when redirecting.) + + The message is sent back out with the address from the redirect + command as an envelope recipient. Implementations MAY combine + separate redirects for a given message into a single submission with + multiple envelope recipients. (This is not a Mail User Agent (MUA)- + style forward, which creates a new message with a different sender + and message ID, wrapping the old message in a new one.) + + The envelope sender address on the outgoing message is chosen by the + sieve implementation. It MAY be copied from the message being + processed. However, if the message being processed has an empty + envelope sender address the outgoing message MUST also have an empty + envelope sender address. This last requirement is imposed to prevent + loops in the case where a message is redirected to an invalid address + when then returns a delivery status notification that also ends up + being redirected to the same invalid address. + + A simple script can be used for redirecting all mail: + + Example: redirect "bart@example.com"; + + Implementations MUST take measures to implement loop control, + possibly including adding headers to the message or counting Received + headers as specified in section 6.2 of [SMTP]. If an implementation + detects a loop, it causes an error. + + Implementations MUST provide means of limiting the number of + redirects a Sieve script can perform. See section 10 for more + details. + + Implementations MAY ignore a redirect action silently due to policy + reasons. For example, an implementation MAY choose not to redirect + to an address that is known to be undeliverable. Any ignored + redirect MUST NOT cancel the implicit keep. + +4.3. Action keep + + Usage: keep + + The "keep" action is whatever action is taken in lieu of all other + actions, if no filtering happens at all; generally, this simply means + to file the message into the user's main mailbox. This command + + + +Guenther & Showalter Standards Track [Page 24] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + provides a way to execute this action without needing to know the + name of the user's main mailbox, providing a way to call it without + needing to understand the user's setup or the underlying mail system. + + For instance, in an implementation where the IMAP server is running + scripts on behalf of the user at time of delivery, a keep command is + equivalent to a fileinto "INBOX". + + Example: if size :under 1M { keep; } else { discard; } + + Note that the above script is identical to the one below. + + Example: if not size :under 1M { discard; } + +4.4. Action discard + + Usage: discard + + Discard is used to silently throw away the message. It does so by + simply canceling the implicit keep. If discard is used with other + actions, the other actions still happen. Discard is compatible with + all other actions. (For instance, fileinto+discard is equivalent to + fileinto.) + + Discard MUST be silent; that is, it MUST NOT return a non-delivery + notification of any kind ([DSN], [MDN], or otherwise). + + In the following script, any mail from "idiot@example.com" is thrown + out. + + Example: if header :contains ["from"] ["idiot@example.com"] { + discard; + } + + While an important part of this language, "discard" has the potential + to create serious problems for users: Students who leave themselves + logged in to an unattended machine in a public computer lab may find + their script changed to just "discard". In order to protect users in + this situation (along with similar situations), implementations MAY + keep messages destroyed by a script for an indefinite period, and MAY + disallow scripts that throw out all mail. + + + + + + + + + + +Guenther & Showalter Standards Track [Page 25] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + +5. Test Commands + + Tests are used in conditionals to decide which part(s) of the + conditional to execute. + + Implementations MUST support these tests: "address", "allof", + "anyof", "exists", "false", "header", "not", "size", and "true". + + Implementations SHOULD support the "envelope" test. + +5.1. Test address + + Usage: address [COMPARATOR] [ADDRESS-PART] [MATCH-TYPE] + + + The "address" test matches Internet addresses in structured headers + that contain addresses. It returns true if any header contains any + key in the specified part of the address, as modified by the + comparator and the match keyword. Whether there are other addresses + present in the header doesn't affect this test; this test does not + provide any way to determine whether an address is the only address + in a header. + + Like envelope and header, this test returns true if any combination + of the header-list and key-list arguments match and returns false + otherwise. + + Internet email addresses [IMAIL] have the somewhat awkward + characteristic that the local-part to the left of the at-sign is + considered case sensitive, and the domain-part to the right of the + at-sign is case insensitive. The "address" command does not deal + with this itself, but provides the ADDRESS-PART argument for allowing + users to deal with it. + + The address primitive never acts on the phrase part of an email + address or on comments within that address. It also never acts on + group names, although it does act on the addresses within the group + construct. + + Implementations MUST restrict the address test to headers that + contain addresses, but MUST include at least From, To, Cc, Bcc, + Sender, Resent-From, and Resent-To, and it SHOULD include any other + header that utilizes an "address-list" structured header body. + + Example: if address :is :all "from" "tim@example.com" { + discard; + } + + + + +Guenther & Showalter Standards Track [Page 26] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + +5.2. Test allof + + Usage: allof + + The "allof" test performs a logical AND on the tests supplied to it. + + Example: allof (false, false) => false + allof (false, true) => false + allof (true, true) => true + + The allof test takes as its argument a test-list. + +5.3. Test anyof + + Usage: anyof + + The "anyof" test performs a logical OR on the tests supplied to it. + + Example: anyof (false, false) => false + anyof (false, true) => true + anyof (true, true) => true + +5.4. Test envelope + + Usage: envelope [COMPARATOR] [ADDRESS-PART] [MATCH-TYPE] + + + The "envelope" test is true if the specified part of the [SMTP] (or + equivalent) envelope matches the specified key. This specification + defines the interpretation of the (case insensitive) "from" and "to" + envelope-parts. Additional envelope-parts may be defined by other + extensions; implementations SHOULD consider unknown envelope parts an + error. + + If one of the envelope-part strings is (case insensitive) "from", + then matching occurs against the FROM address used in the SMTP MAIL + command. The null reverse-path is matched against as the empty + string, regardless of the ADDRESS-PART argument specified. + + If one of the envelope-part strings is (case insensitive) "to", then + matching occurs against the TO address used in the SMTP RCPT command + that resulted in this message getting delivered to this user. Note + that only the most recent TO is available, and only the one relevant + to this user. + + The envelope-part is a string list and may contain more than one + parameter, in which case all of the strings specified in the key-list + are matched against all parts given in the envelope-part list. + + + +Guenther & Showalter Standards Track [Page 27] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + Like address and header, this test returns true if any combination of + the envelope-part list and key-list arguments match and returns false + otherwise. + + All tests against envelopes MUST drop source routes. + + If the SMTP transaction involved several RCPT commands, only the data + from the RCPT command that caused delivery to this user is available + in the "to" part of the envelope. + + If a protocol other than SMTP is used for message transport, + implementations are expected to adapt this command appropriately. + + The envelope command is optional. Implementations SHOULD support it, + but the necessary information may not be available in all cases. The + capability string for use with the require command is "envelope". + + Example: require "envelope"; + if envelope :all :is "from" "tim@example.com" { + discard; + } + +5.5. Test exists + + Usage: exists + + The "exists" test is true if the headers listed in the header-names + argument exist within the message. All of the headers must exist or + the test is false. + + The following example throws out mail that doesn't have a From header + and a Date header. + + Example: if not exists ["From","Date"] { + discard; + } + +5.6. Test false + + Usage: false + + The "false" test always evaluates to false. + + + + + + + + + +Guenther & Showalter Standards Track [Page 28] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + +5.7. Test header + + Usage: header [COMPARATOR] [MATCH-TYPE] + + + The "header" test evaluates to true if the value of any of the named + headers, ignoring leading and trailing whitespace, matches any key. + The type of match is specified by the optional match argument, which + defaults to ":is" if not specified, as specified in section 2.6. + + Like address and envelope, this test returns true if any combination + of the header-names list and key-list arguments match and returns + false otherwise. + + If a header listed in the header-names argument exists, it contains + the empty key (""). However, if the named header is not present, it + does not match any key, including the empty key. So if a message + contained the header + + X-Caffeine: C8H10N4O2 + + these tests on that header evaluate as follows: + + header :is ["X-Caffeine"] [""] => false + header :contains ["X-Caffeine"] [""] => true + + Testing whether a given header is either absent or doesn't contain + any non-whitespace characters can be done using a negated "header" + test: + + not header :matches "Cc" "?*" + +5.8. Test not + + Usage: not + + The "not" test takes some other test as an argument, and yields the + opposite result. "not false" evaluates to "true" and "not true" + evaluates to "false". + +5.9. Test size + + Usage: size <":over" / ":under"> + + The "size" test deals with the size of a message. It takes either a + tagged argument of ":over" or ":under", followed by a number + representing the size of the message. + + + + +Guenther & Showalter Standards Track [Page 29] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + If the argument is ":over", and the size of the message is greater + than the number provided, the test is true; otherwise, it is false. + + If the argument is ":under", and the size of the message is less than + the number provided, the test is true; otherwise, it is false. + + Exactly one of ":over" or ":under" must be specified, and anything + else is an error. + + The size of a message is defined to be the number of octets in the + [IMAIL] representation of the message. + + Note that for a message that is exactly 4,000 octets, the message is + neither ":over" nor ":under" 4000 octets. + +5.10. Test true + + Usage: true + + The "true" test always evaluates to true. + +6. Extensibility + + New control commands, actions, and tests can be added to the + language. Sites must make these features known to their users; this + document does not define a way to discover the list of extensions + supported by the server. + + Any extensions to this language MUST define a capability string that + uniquely identifies that extension. Capability string are case- + sensitive; for example, "foo" and "FOO" are different capabilities. + If a new version of an extension changes the functionality of a + previously defined extension, it MUST use a different name. + Extensions may register a set of related capabilities by registering + just a unique prefix for them. The "comparator-" prefix is an + example of this. The prefix MUST end with a "-" and MUST NOT overlap + any existing registrations. + + In a situation where there is a script submission protocol and an + extension advertisement mechanism aware of the details of this + language, scripts submitted can be checked against the mail server to + prevent use of an extension that the server does not support. + + Extensions MUST state how they interact with constraints defined in + section 2.10, e.g., whether they cancel the implicit keep, and which + actions they are compatible and incompatible with. Extensions MUST + NOT change the behavior of the "require" control command or alter the + interpretation of the argument to the "require" control. + + + +Guenther & Showalter Standards Track [Page 30] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + Extensions that can submit new email messages or otherwise generate + new protocol requests MUST consider loop suppression, at least to + document any security considerations. + +6.1. Capability String + + Capability strings are typically short strings describing what + capabilities are supported by the server. + + Capability strings beginning with "vnd." represent vendor-defined + extensions. Such extensions are not defined by Internet standards or + RFCs, but are still registered with IANA in order to prevent + conflicts. Extensions starting with "vnd." SHOULD be followed by the + name of the vendor and product, such as "vnd.acme.rocket-sled". + + The following capability strings are defined by this document: + + encoded-character The string "encoded-character" indicates that the + implementation supports the interpretation of + "${hex:...}" and "${unicode:...}" in strings. + + envelope The string "envelope" indicates that the implementation + supports the "envelope" command. + + fileinto The string "fileinto" indicates that the implementation + supports the "fileinto" command. + + comparator- The string "comparator-elbonia" is provided if the + implementation supports the "elbonia" comparator. + Therefore, all implementations have at least the + "comparator-i;octet" and "comparator-i;ascii-casemap" + capabilities. However, these comparators may be used + without being declared with require. + +6.2. IANA Considerations + + In order to provide a standard set of extensions, a registry is + maintained by IANA. This registry contains both vendor-controlled + capability names (beginning with "vnd.") and IETF-controlled + capability names. Vendor-controlled capability names may be + registered on a first-come, first-served basis, by applying to IANA + with the form in the following section. Registration of capability + prefixes that do not begin with "vnd." REQUIRES a standards track or + IESG-approved experimental RFC. + + Extensions designed for interoperable use SHOULD use IETF-controlled + capability names. + + + + +Guenther & Showalter Standards Track [Page 31] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + +6.2.1. Template for Capability Registrations + + The following template is to be used for registering new Sieve + extensions with IANA. + + To: iana@iana.org + Subject: Registration of new Sieve extension + + Capability name: [the string for use in the 'require' statement] + Description: [a brief description of what the extension adds + or changes] + RFC number: [for extensions published as RFCs] + Contact address: [email and/or physical address to contact for + additional information] + +6.2.2. Handling of Existing Capability Registrations + + In order to bring the existing capability registrations in line with + the new template, IANA has modified each as follows: + + 1. The "capability name" and "capability arguments" fields have been + eliminated + 2. The "capability keyword" field have been renamed to "Capability + name" + 3. An empty "Description" field has been added + 4. The "Standards Track/IESG-approved experimental RFC number" field + has been renamed to "RFC number" + 5. The "Person and email address to contact for further information" + field should be renamed to "Contact address" + +6.2.3. Initial Capability Registrations + + This RFC updates the following entries in the IANA registry for Sieve + extensions. + + Capability name: encoded-character + Description: changes the interpretation of strings to allow + arbitrary octets and Unicode characters to be + represented using US-ASCII + RFC number: RFC 5228 (Sieve base spec) + Contact address: The Sieve discussion list + + Capability name: fileinto + Description: adds the 'fileinto' action for delivering to a + mailbox other than the default + RFC number: RFC 5228 (Sieve base spec) + Contact address: The Sieve discussion list + + + + +Guenther & Showalter Standards Track [Page 32] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + Capability name: envelope + Description: adds the 'envelope' test for testing the message + transport sender and recipient address + RFC number: RFC 5228 (Sieve base spec) + Contact address: The Sieve discussion list + + Capability name: comparator-* (anything starting with "comparator-") + Description: adds the indicated comparator for use with the + :comparator argument + RFC number: RFC 5228 (Sieve base spec) and [COLLATION] + Contact address: The Sieve discussion list + +6.3. Capability Transport + + A method of advertising which capabilities an implementation supports + is difficult due to the wide range of possible implementations. Such + a mechanism, however, should have the property that the + implementation can advertise the complete set of extensions that it + supports. + +7. Transmission + + The [MIME] type for a Sieve script is "application/sieve". + + The registration of this type for RFC 2048 requirements is updated as + follows: + + Subject: Registration of MIME media type application/sieve + + MIME media type name: application + MIME subtype name: sieve + Required parameters: none + Optional parameters: none + Encoding considerations: Most Sieve scripts will be textual, + written in UTF-8. When non-7bit characters are used, + quoted-printable is appropriate for transport systems + that require 7bit encoding. + Security considerations: Discussed in section 10 of this RFC. + Interoperability considerations: Discussed in section 2.10.5 + of this RFC. + Published specification: this RFC. + Applications that use this media type: sieve-enabled mail + servers and clients + Additional information: + Magic number(s): + File extension(s): .siv .sieve + Macintosh File Type Code(s): + + + + +Guenther & Showalter Standards Track [Page 33] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + Person & email address to contact for further information: + See the discussion list at ietf-mta-filters@imc.org. + Intended usage: + COMMON + Author/Change controller: + The SIEVE WG, delegated by the IESG. + +8. Parsing + + The Sieve grammar is separated into tokens and a separate grammar as + most programming languages are. Additional rules are supplied here + for common arguments to various language facilities. + +8.1. Lexical Tokens + + Sieve scripts are encoded in UTF-8. The following assumes a valid + UTF-8 encoding; special characters in Sieve scripts are all US-ASCII. + + The following are tokens in Sieve: + + - identifiers + - tags + - numbers + - quoted strings + - multi-line strings + - other separators + + Identifiers, tags, and numbers are case-insensitive, while quoted + strings and multi-line strings are case-sensitive. + + Blanks, horizontal tabs, CRLFs, and comments ("whitespace") are + ignored except as they separate tokens. Some whitespace is required + to separate otherwise adjacent tokens and in specific places in the + multi-line strings. CR and LF can only appear in CRLF pairs. + + The other separators are single individual characters and are + mentioned explicitly in the grammar. + + The lexical structure of sieve is defined in the following grammar + (as described in [ABNF]): + + bracket-comment = "/*" *not-star 1*STAR + *(not-star-slash *not-star 1*STAR) "/" + ; No */ allowed inside a comment. + ; (No * is allowed unless it is the last + ; character, or unless it is followed by a + ; character that isn't a slash.) + + + + +Guenther & Showalter Standards Track [Page 34] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + comment = bracket-comment / hash-comment + + hash-comment = "#" *octet-not-crlf CRLF + + identifier = (ALPHA / "_") *(ALPHA / DIGIT / "_") + + multi-line = "text:" *(SP / HTAB) (hash-comment / CRLF) + *(multiline-literal / multiline-dotstart) + "." CRLF + + multiline-literal = [ octet-not-period *octet-not-crlf ] CRLF + + multiline-dotstart = "." 1*octet-not-crlf CRLF + ; A line containing only "." ends the + ; multi-line. Remove a leading '.' if + ; followed by another '.'. + + not-star = CRLF / %x01-09 / %x0B-0C / %x0E-29 / %x2B-FF + ; either a CRLF pair, OR a single octet + ; other than NUL, CR, LF, or star + + not-star-slash = CRLF / %x01-09 / %x0B-0C / %x0E-29 / %x2B-2E / + %x30-FF + ; either a CRLF pair, OR a single octet + ; other than NUL, CR, LF, star, or slash + + number = 1*DIGIT [ QUANTIFIER ] + + octet-not-crlf = %x01-09 / %x0B-0C / %x0E-FF + ; a single octet other than NUL, CR, or LF + + octet-not-period = %x01-09 / %x0B-0C / %x0E-2D / %x2F-FF + ; a single octet other than NUL, + ; CR, LF, or period + + octet-not-qspecial = %x01-09 / %x0B-0C / %x0E-21 / %x23-5B / %x5D-FF + ; a single octet other than NUL, + ; CR, LF, double-quote, or backslash + + QUANTIFIER = "K" / "M" / "G" + + quoted-other = "\" octet-not-qspecial + ; represents just the octet-no-qspecial + ; character. SHOULD NOT be used + + quoted-safe = CRLF / octet-not-qspecial + ; either a CRLF pair, OR a single octet other + ; than NUL, CR, LF, double-quote, or backslash + + + +Guenther & Showalter Standards Track [Page 35] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + quoted-special = "\" (DQUOTE / "\") + ; represents just a double-quote or backslash + + quoted-string = DQUOTE quoted-text DQUOTE + + quoted-text = *(quoted-safe / quoted-special / quoted-other) + + STAR = "*" + + tag = ":" identifier + + white-space = 1*(SP / CRLF / HTAB) / comment + +8.2. Grammar + + The following is the grammar of Sieve after it has been lexically + interpreted. No whitespace or comments appear below. The start + symbol is "start". + + argument = string-list / number / tag + + arguments = *argument [ test / test-list ] + + block = "{" commands "}" + + command = identifier arguments (";" / block) + + commands = *command + + start = commands + + string = quoted-string / multi-line + + string-list = "[" string *("," string) "]" / string + ; if there is only a single string, the brackets + ; are optional + + test = identifier arguments + + test-list = "(" test *("," test) ")" + +8.3. Statement Elements + + These elements are collected from the "Syntax" sections elsewhere in + this document, and are provided here in [ABNF] syntax so that they + can be modified by extensions. + + ADDRESS-PART = ":localpart" / ":domain" / ":all" + + + +Guenther & Showalter Standards Track [Page 36] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + COMPARATOR = ":comparator" string + + MATCH-TYPE = ":is" / ":contains" / ":matches" + +9. Extended Example + + The following is an extended example of a Sieve script. Note that it + does not make use of the implicit keep. + + # + # Example Sieve Filter + # Declare any optional features or extension used by the script + # + require ["fileinto"]; + + # + # Handle messages from known mailing lists + # Move messages from IETF filter discussion list to filter mailbox + # + if header :is "Sender" "owner-ietf-mta-filters@imc.org" + { + fileinto "filter"; # move to "filter" mailbox + } + # + # Keep all messages to or from people in my company + # + elsif address :DOMAIN :is ["From", "To"] "example.com" + { + keep; # keep in "In" mailbox + } + + # + # Try and catch unsolicited email. If a message is not to me, + # or it contains a subject known to be spam, file it away. + # + elsif anyof (NOT address :all :contains + ["To", "Cc", "Bcc"] "me@example.com", + header :matches "subject" + ["*make*money*fast*", "*university*dipl*mas*"]) + { + fileinto "spam"; # move to "spam" mailbox + } + else + { + # Move all other (non-company) mail to "personal" + # mailbox. + fileinto "personal"; + } + + + +Guenther & Showalter Standards Track [Page 37] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + +10. Security Considerations + + Users must get their mail. It is imperative that whatever + implementations use to store the user-defined filtering scripts + protect them from unauthorized modification, to preserve the + integrity of the mail system. An attacker who can modify a script + can cause mail to be discarded, rejected, or forwarded to an + unauthorized recipient. In addition, it's possible that Sieve + scripts might expose private information, such as mailbox names, or + email addresses of favored (or disfavored) correspondents. Because + of that, scripts SHOULD also be protected from unauthorized + retrieval. + + Several commands, such as "discard", "redirect", and "fileinto", + allow for actions to be taken that are potentially very dangerous. + + Use of the "redirect" command to generate notifications may easily + overwhelm the target address, especially if it was not designed to + handle large messages. + + Allowing a single script to redirect to multiple destinations can be + used as a means of amplifying the number of messages in an attack. + Moreover, if loop detection is not properly implemented, it may be + possible to set up exponentially growing message loops. Accordingly, + Sieve implementations: + + (1) MUST implement facilities to detect and break message loops. See + section 6.2 of [SMTP] for additional information on basic loop + detection strategies. + + (2) MUST provide the means for administrators to limit the ability of + users to abuse redirect. In particular, it MUST be possible to + limit the number of redirects a script can perform. + Additionally, if no use cases exist for using redirect to + multiple destinations, this limit SHOULD be set to 1. Additional + limits, such as the ability to restrict redirect to local users, + MAY also be implemented. + + (3) MUST provide facilities to log use of redirect in order to + facilitate tracking down abuse. + + (4) MAY use script analysis to determine whether or not a given + script can be executed safely. While the Sieve language is + sufficiently complex that full analysis of all possible scripts + is computationally infeasible, the majority of real-world scripts + are amenable to analysis. For example, an implementation might + + + + + +Guenther & Showalter Standards Track [Page 38] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + allow scripts that it has determined are safe to run unhindered, + block scripts that are potentially problematic, and subject + unclassifiable scripts to additional auditing and logging. + + Allowing redirects at all may not be appropriate in situations where + email accounts are freely available and/or not trackable to a human + who can be held accountable for creating message bombs or other + abuse. + + As with any filter on a message stream, if the Sieve implementation + and the mail agents 'behind' Sieve in the message stream differ in + their interpretation of the messages, it may be possible for an + attacker to subvert the filter. Of particular note are differences + in the interpretation of malformed messages (e.g., missing or extra + syntax characters) or those that exhibit corner cases (e.g., NUL + octets encoded via [MIME3]). + +11. Acknowledgments + + This document has been revised in part based on comments and + discussions that took place on and off the SIEVE mailing list. + Thanks to Sharon Chisholm, Cyrus Daboo, Ned Freed, Arnt Gulbrandsen, + Michael Haardt, Kjetil Torgrim Homme, Barry Leiba, Mark E. Mallett, + Alexey Melnikov, Eric Rescorla, Rob Siemborski, and Nigel Swinson for + reviews and suggestions. + +12. Normative References + + [ABNF] Crocker, D., Ed., and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", RFC 4234, October 2005. + + [COLLATION] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet + Application Protocol Collation Registry", RFC 4790, March + 2007. + + [IMAIL] Resnick, P., Ed., "Internet Message Format", RFC 2822, + April 2001. + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail + Extensions (MIME) Part One: Format of Internet Message + Bodies", RFC 2045, November 1996. + + [MIME3] Moore, K., "MIME (Multipurpose Internet Mail Extensions) + Part Three: Message Header Extensions for Non-ASCII + Text", RFC 2047, November 1996. + + + +Guenther & Showalter Standards Track [Page 39] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + + [SMTP] Klensin, J., Ed., "Simple Mail Transfer Protocol", RFC + 2821, April 2001. + + [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. + +13. Informative References + + [BINARY-SI] "Standard IEC 60027-2: Letter symbols to be used in + electrical technology - Part 2: Telecommunications and + electronics", January 1999. + + [DSN] Moore, K. and G. Vaudreuil, "An Extensible Message Format + for Delivery Status Notifications", RFC 3464, January + 2003. + + [FLAMES] Borenstein, N, and C. Thyberg, "Power, Ease of Use, and + Cooperative Work in a Practical Multimedia Message + System", Int. J. of Man-Machine Studies, April, 1991. + Reprinted in Computer-Supported Cooperative Work and + Groupware, Saul Greenberg, editor, Harcourt Brace + Jovanovich, 1991. Reprinted in Readings in Groupware and + Computer-Supported Cooperative Work, Ronald Baecker, + editor, Morgan Kaufmann, 1993. + + [IMAP] Crispin, M., "Internet Message Access Protocol - version + 4rev1", RFC 3501, March 2003. + + [MDN] Hansen, T., Ed., and G. Vaudreuil, Ed., "Message + Disposition Notification", RFC 3798, May 2004. + + [RFC3028] Showalter, T., "Sieve: A Mail Filtering Language", RFC + 3028, January 2001. + + + + + + + + + + + + + + + + + + +Guenther & Showalter Standards Track [Page 40] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + +14. Changes from RFC 3028 + + This following list is a summary of the changes that have been made + in the Sieve language base specification from [RFC3028]. + + 1. Removed ban on tests having side-effects + 2. Removed reject extension (will be specified in a separate RFC) + 3. Clarified description of comparators to match [COLLATION], the + new base specification for them + 4. Require stripping of leading and trailing whitespace in "header" + test + 5. Clarified or tightened handling of many minor items, including: + - invalid [MIME3] encoding + - invalid addresses in headers + - invalid header field names in tests + - 'undefined' comparator result + - unknown envelope parts + - null return-path in "envelope" test + 6. Capability strings are case-sensitive + 7. Clarified that fileinto should reencode non-ASCII mailbox + names to match the mailstore's conventions + 8. Errors in the ABNF were corrected + 9. The references were updated and split into normative and + informative + 10. Added encoded-character capability and deprecated (but did not + remove) use of arbitrary binary octets in Sieve scripts. + 11. Updated IANA registration template, and added IANA + considerations to permit capability prefix registrations. + 12. Added .sieve as a valid extension for Sieve scripts. + +Editors' Addresses + + Philip Guenther + Sendmail, Inc. + 6425 Christie St. Ste 400 + Emeryville, CA 94608 + EMail: guenther@sendmail.com + + Tim Showalter + EMail: tjs@psaux.com + + + + + + + + + + + +Guenther & Showalter Standards Track [Page 41] + +RFC 5228 Sieve: An Email Filtering Language January 2008 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2008). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Guenther & Showalter Standards Track [Page 42] + diff --git a/docs/rfcs/rfc5255.IMAP_i18n.txt b/docs/rfcs/rfc5255.IMAP_i18n.txt new file mode 100644 index 0000000..df76402 --- /dev/null +++ b/docs/rfcs/rfc5255.IMAP_i18n.txt @@ -0,0 +1,1123 @@ + + + + + + +Network Working Group C. Newman +Request for Comments: 5255 Sun Microsystems +Category: Standards Track A. Gulbrandsen + Oryx Mail Systems GmhH + A. Melnikov + Isode Limited + June 2008 + + + Internet Message Access Protocol Internationalization + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + Internet Message Access Protocol (IMAP) version 4rev1 has basic + support for non-ASCII characters in mailbox names and search + substrings. It also supports non-ASCII message headers and content + encoded as specified by Multipurpose Internet Mail Extensions (MIME). + This specification defines a collection of IMAP extensions that + improve international support including language negotiation for + international error text, translations for namespace prefixes, and + comparator negotiation for search, sort, and thread. + + + + + + + + + + + + + + + + + + + + + + +Newman, et al. Standards Track [Page 1] + +RFC 5255 IMAP Internationalization June 2008 + + +Table of Contents + + 1. Introduction ....................................................3 + 2. Conventions Used in This Document ...............................3 + 3. LANGUAGE Extension ..............................................3 + 3.1. LANGUAGE Extension Requirements ............................4 + 3.2. LANGUAGE Command ...........................................4 + 3.3. LANGUAGE Response ..........................................6 + 3.4. TRANSLATION Extension to the NAMESPACE Response ............7 + 3.5. Formal Syntax ..............................................8 + 4. I18NLEVEL=1 and I18NLEVEL=2 Extensions ..........................9 + 4.1. Introduction and Overview ..................................9 + 4.2. Requirements Common to Both I18NLEVEL=1 and I18NLEVEL=2 ....9 + 4.3. I18NLEVEL=1 Extension Requirements ........................10 + 4.4. I18NLEVEL=2 Extension Requirements ........................10 + 4.5. Compatibility Notes .......................................11 + 4.6. Comparators and Character Encodings .......................11 + 4.7. COMPARATOR Command ........................................13 + 4.8. COMPARATOR Response .......................................14 + 4.9. BADCOMPARATOR Response Code ...............................14 + 4.10. Formal Syntax ............................................14 + 5. Other IMAP Internationalization Issues .........................15 + 5.1. Unicode Userids and Passwords .............................15 + 5.2. UTF-8 Mailbox Names .......................................15 + 5.3. UTF-8 Domains, Addresses, and Mail Headers ................15 + 6. IANA Considerations ............................................16 + 7. Security Considerations ........................................16 + 8. Acknowledgements ...............................................16 + 9. Relevant Sources of Documents for Internationalized IMAP + Implementations ................................................17 + 10. Normative References ..........................................17 + 11. Informative References ........................................18 + + + + + + + + + + + + + + + + + + + +Newman, et al. Standards Track [Page 2] + +RFC 5255 IMAP Internationalization June 2008 + + +1. Introduction + + This specification defines two IMAP4rev1 [RFC3501] extensions to + enhance international support. These extensions can be advertised + and implemented separately. + + The LANGUAGE extension allows the client to request a suitable + language for protocol error messages and in combination with the + NAMESPACE extension [RFC2342] enables namespace translations. + + The I18NLEVEL=2 extension allows the client to request a suitable + collation that will modify the behavior of the base specification's + SEARCH command as well as the SORT and THREAD extensions [SORT]. + This leverages the collation registry [RFC4790]. The I18NLEVEL=1 + extension updates SEARCH/SORT/THREAD to use i;unicode-casemap + comparator, as defined in [UCM]. I18NLEVEL=1 is a simpler version of + I18NLEVEL=2 with no ability to select a different collation. + +2. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + The formal syntax uses the Augmented Backus-Naur Form (ABNF) + [RFC5234] notation including the core rules defined in Appendix A. + + The UTF-8-related productions are defined in [RFC3629]. + + In examples, "C:" and "S:" indicate lines sent by the client and + server respectively. If a single "C:" or "S:" label applies to + multiple lines, then the line breaks between those lines are for + editorial clarity only and are not part of the actual protocol + exchange. + +3. LANGUAGE Extension + + IMAP allows server responses to include human-readable text that in + many cases needs to be presented to the user. But that text is + limited to US-ASCII by the IMAP specification [RFC3501] in order to + preserve backwards compatibility with deployed IMAP implementations. + This section specifies a way for an IMAP client to negotiate which + language the server should use when sending human-readable text. + + + + + + + + +Newman, et al. Standards Track [Page 3] + +RFC 5255 IMAP Internationalization June 2008 + + + The LANGUAGE extension only provides a mechanism for altering fixed + server strings such as response text and NAMESPACE folder names. + Assigning localized language aliases to shared mailboxes would be + done with a separate mechanism such as the proposed METADATA + extension (see [METADATA]). + +3.1. LANGUAGE Extension Requirements + + IMAP servers that support this extension MUST list the keyword + LANGUAGE in their CAPABILITY response as well as in the greeting + CAPABILITY data. + + A server that advertises this extension MUST use the language + "i-default" as described in [RFC2277] as its default language until + another supported language is negotiated by the client. A server + MUST include "i-default" as one of its supported languages. IMAP + servers SHOULD NOT advertise the LANGUAGE extension if they discover + that they only support "i-default". + + Clients and servers that support this extension MUST also support the + NAMESPACE extension [RFC2342]. + + The LANGUAGE command is valid in all states. Clients SHOULD issue + LANGUAGE before authentication, since some servers send valuable user + information as part of authentication (e.g., "password is correct, + but expired"). If a security layer (such as SASL or TLS) is + subsequently negotiated by the client, it MUST re-issue the LANGUAGE + command in order to make sure that no previous active attack (if any) + on LANGUAGE negotiation has effect on subsequent error messages. + (See Section 7 for a more detailed explanation of the attack.) + +3.2. LANGUAGE Command + + Arguments: Optional language range arguments. + + Response: A possible LANGUAGE response (see Section 3.3). + A possible NAMESPACE response (see Section 3.4). + + Result: OK - Command completed + NO - Could not complete command + BAD - Arguments invalid + + The LANGUAGE command requests that human-readable text emitted by the + server be localized to a language matching one of the language range + argument as described by Section 2 of [RFC4647]. + + + + + + +Newman, et al. Standards Track [Page 4] + +RFC 5255 IMAP Internationalization June 2008 + + + If the command succeeds, the server will return human-readable + responses in the first supported language specified. These responses + will be in UTF-8 [RFC3629]. The server MUST send a LANGUAGE response + specifying the language used, and the change takes effect immediately + after the LANGUAGE response. + + If the command fails, the server continues to return human-readable + responses in the language it was previously using. + + The special "default" language range argument indicates a request to + use a language designated as preferred by the server administrator. + The preferred language MAY vary based on the currently active user. + + If a language range does not match a known language tag exactly but + does match a language by the rules of [RFC4647], the server MUST send + an untagged LANGUAGE response indicating the language selected. + + If there aren't any arguments, the server SHOULD send an untagged + LANGUAGE response listing the languages it supports. If the server + is unable to enumerate the list of languages it supports it MAY + return a tagged NO response to the enumeration request. If, after + receiving a LANGUAGE request, the server discovers that it doesn't + support any language other than i-default, it MUST return a tagged NO + response to the enumeration request. + + < The server defaults to using English i-default responses until + the user explicitly changes the language. > + + C: A001 LOGIN KAREN PASSWORD + S: A001 OK LOGIN completed + + < Client requested MUL language, which no server supports. > + + C: A002 LANGUAGE MUL + S: A002 NO Unsupported language MUL + + < A LANGUAGE command with no arguments is a request to enumerate + the list of languages the server supports. > + + C: A003 LANGUAGE + S: * LANGUAGE (EN DE IT i-default) + S: A003 OK Supported languages have been enumerated + + C: B001 LANGUAGE + S: B001 NO Server is unable to enumerate supported languages + + + + + + +Newman, et al. Standards Track [Page 5] + +RFC 5255 IMAP Internationalization June 2008 + + + < Once the client changes the language, all responses will be in + that language starting after the LANGUAGE response. Note that + this includes the NAMESPACE response. Because RFCs are in US- + ASCII, this document uses an ASCII transcription rather than + UTF-8 text, e.g., "ue" in the word "ausgefuehrt" > + + C: C001 LANGUAGE DE + S: * LANGUAGE (DE) + S: * NAMESPACE (("" "/")) (("Other Users/" "/" "TRANSLATION" + ("Andere Ben&APw-tzer/"))) (("Public Folders/" "/" + "TRANSLATION" ("Gemeinsame Postf&AM8-cher/"))) + S: C001 OK Sprachwechsel durch LANGUAGE-Befehl ausgefuehrt + + < If a server does not support the requested primary language, + responses will continue to be returned in the current language + the server is using. > + + C: D001 LANGUAGE FR + S: D001 NO Diese Sprache ist nicht unterstuetzt + C: D002 LANGUAGE DE-IT + S: * LANGUAGE (DE-IT) + S: * NAMESPACE (("" "/"))(("Other Users/" "/" "TRANSLATION" + ("Andere Ben&APw-tzer/"))) (("Public Folders/" "/" + "TRANSLATION" ("Gemeinsame Postf&AM8-cher/"))) + S: D002 OK Sprachwechsel durch LANGUAGE-Befehl ausgefuehrt + C: D003 LANGUAGE "default" + S: * LANGUAGE (DE) + S: D003 OK Sprachwechsel durch LANGUAGE-Befehl ausgefuehrt + + < Server does not speak French, but does speak English. User + speaks Canadian French and Canadian English. > + + C: E001 LANGUAGE FR-CA EN-CA + S: * LANGUAGE (EN) + S: E001 OK Now speaking English + +3.3. LANGUAGE Response + + Contents: A list of one or more language tags. + + The LANGUAGE response occurs as a result of a LANGUAGE command. A + LANGUAGE response with a list containing a single language tag + indicates that the server is now using that language. A LANGUAGE + response with a list containing multiple language tags indicates the + server is communicating a list of available languages to the client, + and no change in the active language has been made. + + + + + +Newman, et al. Standards Track [Page 6] + +RFC 5255 IMAP Internationalization June 2008 + + +3.4. TRANSLATION Extension to the NAMESPACE Response + + If localized representations of the namespace prefixes are available + in the selected language, the server SHOULD include these in the + TRANSLATION extension to the NAMESPACE response. + + The TRANSLATION extension to the NAMESPACE response returns a single + string, containing the modified UTF-7 [RFC3501] encoded translation + of the namespace prefix. It is the responsibility of the client to + convert between the namespace prefix and the translation of the + namespace prefix when presenting mailbox names to the user. + + In this example, a server supports the IMAP4 NAMESPACE command. It + uses no prefix to the user's Personal Namespace, a prefix of "Other + Users" to its Other Users' Namespace, and a prefix of "Public + Folders" to its only Shared Namespace. Since a client will often + display these prefixes to the user, the server includes a translation + of them that can be presented to the user. + + C: A001 LANGUAGE DE-IT + S: * NAMESPACE (("" "/")) (("Other Users/" "/" "TRANSLATION" + ("Andere Ben&APw-tzer/"))) (("Public Folders/" "/" + "TRANSLATION" ("Gemeinsame Postf&AM8-cher/"))) + S: A001 OK LANGUAGE-Befehl ausgefuehrt + + + + + + + + + + + + + + + + + + + + + + + + + + + +Newman, et al. Standards Track [Page 7] + +RFC 5255 IMAP Internationalization June 2008 + + +3.5. Formal Syntax + + The following syntax specification inherits ABNF [RFC5234] rules from + IMAP4rev1 [RFC3501], IMAP4 Namespace [RFC2342], Tags for the + Identifying Languages [RFC4646], UTF-8 [RFC3629], and Collected + Extensions to IMAP4 ABNF [RFC4466]. + + command-any =/ language-cmd + ; LANGUAGE command is valid in all states + + language-cmd = "LANGUAGE" *(SP lang-range-quoted) + + response-payload =/ language-data + + language-data = "LANGUAGE" SP "(" lang-tag-quoted *(SP + lang-tag-quoted) ")" + + namespace-trans = SP DQUOTE "TRANSLATION" DQUOTE SP "(" string ")" + ; the string is encoded in Modified UTF-7. + ; this is a subset of the syntax permitted by + ; the Namespace-Response-Extension rule in [RFC4466] + + lang-range-quoted = astring + ; Once any literal wrapper or quoting is removed, this + ; follows the language-range rule in [RFC4647] + + lang-tag-quoted = astring + ; Once any literal wrapper or quoting is removed, this follows + ; the Language-Tag rule in [RFC4646] + + resp-text = ["[" resp-text-code "]" SP ] UTF8-TEXT-CHAR + *(UTF8-TEXT-CHAR / "[") + ; After the server is changed to a language other than + ; i-default, this resp-text rule replaces the resp-text + ; rule from [RFC3501]. + + UTF8-TEXT-CHAR = %x20-5A / %x5C-7E / UTF8-2 / UTF8-3 / UTF8-4 + ; UTF-8 excluding 7-bit control characters and "[" + + + + + + + + + + + + + +Newman, et al. Standards Track [Page 8] + +RFC 5255 IMAP Internationalization June 2008 + + +4. I18NLEVEL=1 and I18NLEVEL=2 Extensions + +4.1. Introduction and Overview + + IMAP4rev1 [RFC3501] includes the SEARCH command that can be used to + locate messages matching criteria including human-readable text. The + SORT extension [SORT] to IMAP allows the client to ask the server to + determine the order of messages based on criteria including human- + readable text. These mechanisms require the ability to support non- + English search and sort functions. + + Section 4 defines two IMAP extensions for internationalizing IMAP + SEARCH, SORT, and THREAD [SORT] using the comparator framework + [RFC4790]. + + The I18NLEVEL=1 extension updates SEARCH/SORT/THREAD to use + i;unicode-casemap comparator, as defined in [UCM]. See Sections 4.2 + and 4.3 for more details. + + The I18NLEVEL=2 extension is a superset of the I18NLEVEL=1 extension. + It adds to I18NLEVEL=1 extension the ability to determine the active + comparator (see definition below) and to negotiate use of comparators + using the COMPARATOR command. It also adds the COMPARATOR response + that indicates the active comparator and possibly other available + comparators. See Sections 4.2 and 4.4 for more details. + +4.2. Requirements Common to Both I18NLEVEL=1 and I18NLEVEL=2 + + The term "default comparator" refers to the comparator that is used + by SEARCH and SORT absent any negotiation using the COMPARATOR + command (see Section 4.7). The term "active comparator" refers to + the comparator which will be used within a session, e.g., by SEARCH + and SORT. The COMPARATOR command is used to change the active + comparator. + + The active comparator applies to the following SEARCH keys: "BCC", + "BODY", "CC", "FROM", "SUBJECT", "TEXT", "TO", and "HEADER". If the + server also advertises the "SORT" extension, then the active + comparator applies to the following SORT keys: "CC", "FROM", + "SUBJECT", and "TO". If the server advertises THREAD=ORDEREDSUBJECT, + then the active comparator applies to the ORDEREDSUBJECT threading + algorithm. If the server advertises THREAD=REFERENCES, then the + active comparator applies to the subject field comparisons done by + REFERENCES threading algorithm. Future extensions may choose to + apply the active comparator to their SEARCH keys. + + + + + + +Newman, et al. Standards Track [Page 9] + +RFC 5255 IMAP Internationalization June 2008 + + + For SORT and THREAD, the pre-processing necessary to extract the base + subject text from a Subject header occurs prior to the application of + a comparator. + + A server that advertises I18NLEVEL=1 or I18NLEVEL=2 extension MUST + implement the i;unicode-casemap comparator, as defined in [UCM]. + + A server that advertises I18NLEVEL=1 or I18NLEVEL=2 extension MUST + support UTF-8 as a SEARCH charset. + +4.3. I18NLEVEL=1 Extension Requirements + + An IMAP server that satisfies all requirements specified in Sections + 4.2 and 4.6 (and that doesn't support/advertise any other + I18NLEVEL= extension, where n > 1) MUST list the keyword + I18NLEVEL=1 in its CAPABILITY data once IMAP enters the authenticated + state, and MAY list that keyword in other states. + +4.4. I18NLEVEL=2 Extension Requirements + + An IMAP server that satisfies all requirements specified in Sections + 4.2, 4.4, and 4.6-4.10 (and that doesn't support/advertise any other + I18NLEVEL= extension, where n > 2) MUST list the keyword + I18NLEVEL=2 in its CAPABILITY data once IMAP enters the authenticated + state, and MAY list that keyword in other states. + + A server that advertises this extension MUST implement the + i;unicode-casemap comparator, as defined in [UCM]. It MAY implement + other comparators from the IANA registry established by [RFC4790]. + See also Section 4.5 of this document. + + A server that advertises this extension SHOULD use i;unicode-casemap + as the default comparator. (Note that i;unicode-casemap is the + default comparator for I18NLEVEL=1, but not necessarily the default + for I18NLEVEL=2.) The selection of the default comparator MAY be + adjustable by the server administrator, and MAY be sensitive to the + current user. Once the IMAP connection enters authenticated state, + the default comparator MUST remain static for the remainder of that + connection. + + Note that since SEARCH uses the substring operation, IMAP servers can + only implement collations that offer the substring operation (see + [RFC4790], Section 4.2.2). Since SORT uses the ordering operation + (which in turn uses the equality operation), IMAP servers that + advertise the SORT extension can only implement collations that offer + all three operations (see [RFC4790], Sections 4.2.2-4.2.4). + + + + + +Newman, et al. Standards Track [Page 10] + +RFC 5255 IMAP Internationalization June 2008 + + + If the active collation does not provide the operations needed by an + IMAP command, the server MUST respond with a tagged BAD. + +4.5. Compatibility Notes + + Several server implementations deployed prior to the publication of + this specification comply with I18NLEVEL=1 (see Section 4.3), but do + not advertise that. Other legacy servers use the i;ascii-casemap + comparator (see [RFC4790]). + + There is no good way for a client to know which comparator a legacy + server uses. If the client has to assume the worst, it may end up + doing expensive local operations to obtain i;unicode-casemap + comparisons even though the server implements it. + + Legacy server implementations which comply with I18NLEVEL=1 should be + updated to advertise I18NLEVEL=1. All server implementations should + eventually be updated to comply with the I18NLEVEL=2 extension. + +4.6. Comparators and Character Encodings + + RFC 3501, Section 6.4.4, says: + + In all search keys that use strings, a message matches the key + if the string is a substring of the field. The matching is + case-insensitive. + + When performing the SEARCH operation, the active comparator is + applied instead of the case-insensitive matching specified above. + + An IMAP server which performs collation operations (e.g., as part of + commands such as SEARCH, SORT, and THREAD) does so according to the + following procedure: + + (a) MIME encoding (for example, see [RFC2047] for headers and + [RFC2045] for body parts) MUST be removed in the texts being + collated. + + If MIME encoding removal fails for a message (e.g., a body part + of the message has an unsupported Content-Transfer-Encoding, uses + characters not allowed by the Content-Transfer-Encoding, etc.), + the collation of this message is undefined by this specification, + and is handled in an implementation-dependent manner. + + (b) The decoded text from (a) MUST be converted to the charset + expected by the active comparator. + + + + + +Newman, et al. Standards Track [Page 11] + +RFC 5255 IMAP Internationalization June 2008 + + + (c) For the substring operation: + + If step (b) failed (e.g., the text is in an unknown charset, + contains a sequence that is not valid according in that charset, + etc.), the original decoded text from (a) (i.e., before the + charset conversion attempt) is collated using the i;octet + comparator (see [RFC4790]). + + If step (b) was successful, the converted text from (b) is + collated according to the active comparator. + + For the ordering operation: + + All strings that were successfully converted by step (b) are + separated from all strings that failed step (b). Strings in each + group are collated independently. All strings successfully + converted by step (b) are then validated by the active + comparator. Strings that pass validation are collated using the + active comparator. All strings that either fail step (b) or fail + the active collation's validity operation are collated (after + applying step (a)) using the i;octet comparator (see [RFC4790]). + The resulting sorted list is produced by appending all collated + "failed" strings after all strings collated using the active + comparator. + + Example: The following example demonstrates ordering of 4 + different strings using the i;unicode-casemap [UCM] comparator. + Strings are represented using hexadecimal notation used by ABNF + [RFC5234]. + + (1) %xD0 %xC0 %xD0 %xBD %xD0 %xB4 %xD1 %x80 %xD0 %xB5 + %xD0 %xB9 (labeled with charset=UTF-8) + (2) %xD1 %x81 %xD0 %x95 %xD0 %xA0 %xD0 %x93 %xD0 %x95 + %xD0 %x99 (labeled with charset=UTF-8) + (3) %xD0 %x92 %xD0 %xB0 %xD1 %x81 %xD0 %xB8 %xD0 %xBB + %xD0 %xB8 %xFF %xB9 (labeled with charset=UTF-8) + (4) %xE1 %xCC %xC5 %xCB %xD3 %xC5 %xCA (labeled with + charset=KOI8-R) + + Step (b) will convert string (4) to the following sequence of + octets (in UTF-8): + + %xD0 %x90 %xD0 %xBB %xD0 %xB5 %xD0 %xBA %xD1 %x81 %xD0 + %xB5 %xD0 %xB9 + + and will reject strings (1) and (3), as they contain octets not + allowed in charset=UTF-8. + + + + +Newman, et al. Standards Track [Page 12] + +RFC 5255 IMAP Internationalization June 2008 + + + After that, using the i;unicode-casemap collation, string (4) + will collate before string (2). Using the i;octet collation on + the original strings, string (3) will collate before string (1). + So the final ordering is as follows: (4) (2) (3) (1). + + If the substring operation (e.g., IMAP SEARCH) of the active + comparator returns the "undefined" result (see Section 4.2.3 of + [RFC4790]) for either the text specified in the SEARCH command or the + message text, then the operation is repeated on the result of step + (a) using the i;octet comparator. + + The ordering operation (e.g., IMAP SORT and THREAD) SHOULD collate + the following together: strings encoded using unknown or invalid + character encodings, strings in unrecognized charsets, and invalid + input (as defined by the active collation). + +4.7. COMPARATOR Command + + Arguments: Optional comparator order arguments. + + Response: A possible COMPARATOR response (see Section 4.8). + + Result: OK - Command completed + NO - No matching comparator found + BAD - Arguments invalid + + The COMPARATOR command is valid in authenticated and selected states. + + The COMPARATOR command is used to determine or change the active + comparator. When issued with no arguments, it results in a + COMPARATOR response indicating the currently active comparator. + + When issued with one or more comparator arguments, it changes the + active comparator as directed. (If more than one installed + comparator is matched by an argument, the first argument wins.) The + COMPARATOR response lists all matching comparators if more than one + matches the specified patterns. + + The argument "default" refers to the server's default comparator. + Otherwise, each argument is a collation specification as defined in + the Internet Application Protocol Comparator Registry [RFC4790]. + + < The client requests activating a Czech comparator if possible, + or else a generic international comparator which it considers + suitable for Czech. The server picks the first supported + comparator. > + + + + + +Newman, et al. Standards Track [Page 13] + +RFC 5255 IMAP Internationalization June 2008 + + + C: A001 COMPARATOR "cz;*" i;basic + S: * COMPARATOR i;basic + S: A001 OK Will use i;basic for collation + +4.8. COMPARATOR Response + + Contents: The active comparator. An optional list of available + matching comparators + + The COMPARATOR response occurs as a result of a COMPARATOR command. + The first argument in the comparator response is the name of the + active comparator. The second argument is a list of comparators + which matched any of the arguments to the COMPARATOR command and is + present only if more than one match is found. + +4.9. BADCOMPARATOR Response Code + + This response code SHOULD be returned as a result of server failing + an IMAP command (returning NO), when the server knows that none of + the specified comparators match the requested comparator(s). + +4.10. Formal Syntax + + The following syntax specification inherits ABNF [RFC5234] rules from + IMAP4rev1 [RFC3501] and the Internet Application Protocol Comparator + Registry [RFC4790]. + + command-auth =/ comparator-cmd + + resp-text-code =/ "BADCOMPARATOR" + + comparator-cmd = "COMPARATOR" *(SP comp-order-quoted) + + response-payload =/ comparator-data + + comparator-data = "COMPARATOR" SP comp-sel-quoted [SP "(" + comp-id-quoted *(SP comp-id-quoted) ")"] + + comp-id-quoted = astring + ; Once any literal wrapper or quoting is removed, this + ; follows the collation-id rule from [RFC4790] + + comp-order-quoted = astring + ; Once any literal wrapper or quoting is removed, this + ; follows the collation-order rule from [RFC4790] + + + + + + +Newman, et al. Standards Track [Page 14] + +RFC 5255 IMAP Internationalization June 2008 + + + comp-sel-quoted = astring + ; Once any literal wrapper or quoting is removed, this + ; follows the collation-selected rule from [RFC4790] + +5. Other IMAP Internationalization Issues + + The following sections provide an overview of various other IMAP + internationalization issues. These issues are not resolved by this + specification, but could be resolved by other standards work, such as + that being done by the EAI working group (see [IMAP-EAI]). + +5.1. Unicode Userids and Passwords + + IMAP4rev1 currently restricts the userid and password fields of the + LOGIN command to US-ASCII. The "userid" and "password" fields of the + IMAP LOGIN command are restricted to US-ASCII only until a future + standards track RFC states otherwise. Servers are encouraged to + validate both fields to make sure they conform to the formal syntax + of UTF-8 and to reject the LOGIN command if that syntax is violated. + Servers MAY reject the LOGIN command if either the "userid" or + "password" field contains an octet with the highest bit set. + + When AUTHENTICATE is used, some servers may support userids and + passwords in Unicode [RFC3490] since SASL (see [RFC4422]) allows + that. However, such userids cannot be used as part of email + addresses. + +5.2. UTF-8 Mailbox Names + + The modified UTF-7 mailbox naming convention described in Section + 5.1.3 of RFC 3501 is best viewed as an transition from the status quo + in 1996 when modified UTF-7 was first specified. At that time, there + was widespread unofficial use of local character sets such as ISO- + 8859-1 and Shift-JIS for non-ASCII mailbox names, with resultant + non-interoperability. + + The requirements in Section 5.1 of RFC 3501 are very important if + we're ever going to be able to deploy UTF-8 mailbox names. Servers + are encouraged to enforce them. + +5.3. UTF-8 Domains, Addresses, and Mail Headers + + There is now an IETF standard for "Internationalizing Domain Names in + Applications (IDNA)" [RFC3490]. While IMAP clients are free to + support this standard, an argument can be made that it would be + helpful to simple clients if the IMAP server could perform this + conversion (the same argument would apply to MIME header encoding + + + + +Newman, et al. Standards Track [Page 15] + +RFC 5255 IMAP Internationalization June 2008 + + + [RFC2047]). However, it would be unwise to move forward with such + work until the work in progress to define the format of international + email addresses is complete. + +6. IANA Considerations + + IANA added LANGUAGE, I18NLEVEL=1, and I18NLEVEL=2 to the IMAP4 + Capabilities Registry. + +7. Security Considerations + + The LANGUAGE extension makes a new command available in "Not + Authenticated" state in IMAP. Some IMAP implementations run with + root privilege when the server is in "Not Authenticated" state and do + not revoke that privilege until after authentication is complete. + Such implementations are particularly vulnerable to buffer overflow + security errors at this stage and need to implement parsing of this + command with extra care. + + A LANGUAGE command issued prior to activation of a security layer is + subject to an active attack that suppresses or modifies the + negotiation, and thus makes STARTTLS or authentication error messages + more difficult to interpret. This is not a new attack as the error + messages themselves are subject to active attack. Clients MUST re- + issue the LANGUAGE command once a security layer is active, in order + to prevent this attack from impacting subsequent protocol operations. + + LANGUAGE, I18NLEVEL=1, and I18NLEVEL=2 extensions use the UTF-8 + charset; thus, the security considerations for UTF-8 [RFC3629] are + relevant. However, neither uses UTF-8 for identifiers, so the most + serious concerns do not apply. + +8. Acknowledgements + + The LANGUAGE extension is based on a previous document by Mike + Gahrns, a substantial portion of the text in that section was written + by him. Many people have participated in discussions about an IMAP + Language extension in the various fora of the IETF and Internet + working groups, so any list of contributors is bound to be + incomplete. However, the authors would like to thank Andrew McCown + for early work on the original proposal, John Myers for suggestions + regarding the namespace issue, along with Jutta Degener, Mark + Crispin, Mark Pustilnik, Larry Osterman, Cyrus Daboo, Martin Duerst, + Timo Sirainen, Ben Campbell, and Magnus Nystrom for their many + suggestions that have been incorporated into this document. + + Initial discussion of the I18NLEVEL=2 extension involved input from + Mark Crispin and other participants of the IMAP Extensions WG. + + + +Newman, et al. Standards Track [Page 16] + +RFC 5255 IMAP Internationalization June 2008 + + +9. Relevant Sources of Documents for Internationalized IMAP + Implementations + + This is a non-normative list of sources to consider when implementing + i18n-aware IMAP software. + + o The LANGUAGE and I18NLEVEL=2 extensions to IMAP (this + specification). + + o The 8-bit rules for mailbox naming in Section 5.1 of RFC 3501. + + o The Mailbox International Naming Convention in Section 5.1.3 of + RFC 3501. + + o MIME [RFC2045] for message bodies. + + o MIME header encoding [RFC2047] for message headers. + + o The IETF EAI working group. + + o MIME Parameter Value and Encoded Word Extensions [RFC2231] for + filenames. Quality IMAP server implementations will + automatically combine multipart parameters when generating the + BODYSTRUCTURE. There is also some deployed non-standard use of + MIME header encoding inside double quotes for filenames. + + o IDNA [RFC3490] and punycode [RFC3492] for domain names + (currently only relevant to IMAP clients). + + o The UTF-8 charset [RFC3629]. + + o The IETF policy on Character Sets and Languages [RFC2277]. + +10. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and + Languages", BCP 18, RFC 2277, January 1998. + + [RFC2342] Gahrns, M. and C. Newman, "IMAP4 Namespace", RFC 2342, May + 1998. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + + + + +Newman, et al. Standards Track [Page 17] + +RFC 5255 IMAP Internationalization June 2008 + + + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. + + [RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", STD 68, RFC 5234, January + 2008. + + [RFC4422] Melnikov, A., Ed., and K. Zeilenga, Ed., "Simple + Authentication and Security Layer (SASL)", RFC 4422, June + 2006. + + [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 + ABNF", RFC 4466, April 2006. + + [RFC4646] Phillips, A. and M. Davis, "Tags for Identifying + Languages", BCP 47, RFC 4646, September 2006. + + [RFC4647] Phillips, A. and M. Davis, "Matching of Language Tags", + BCP 47, RFC 4647, September 2006. + + [RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet + Application Protocol Collation Registry", RFC 4790, March + 2007. + + [SORT] Crispin, M. and K. Murchison, "Internet Message Access + Protocol - SORT and THREAD Extensions", RFC 5256, June + 2008. + + [UCM] Crispin, M., "i;unicode-casemap - Simple Unicode Collation + Algorithm", RFC 5051, October 2007. + + [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail + Extensions (MIME) Part One: Format of Internet Message + Bodies", RFC 2045, November 1996. + + [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) + Part Three: Message Header Extensions for Non-ASCII Text", + RFC 2047, November 1996. + +11. Informative References + + [RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and Encoded + Word Extensions: Character Sets, Languages, and + Continuations", RFC 2231, November 1997. + + [RFC3490] Faltstrom, P., Hoffman, P., and A. Costello, + "Internationalizing Domain Names in Applications (IDNA)", + RFC 3490, March 2003. + + + +Newman, et al. Standards Track [Page 18] + +RFC 5255 IMAP Internationalization June 2008 + + + [RFC3492] Costello, A., "Punycode: A Bootstring encoding of Unicode + for Internationalized Domain Names in Applications + (IDNA)", RFC 3492, March 2003. + + [METADATA] Daboo, C., "IMAP METADATA Extension", Work in Progress, + April 2008. + + [IMAP-EAI] Resnick, P., and C. Newman, "IMAP Support for UTF-8", Work + in Progress, November 2007. + +Authors' Addresses + + Chris Newman + Sun Microsystems + 3401 Centrelake Dr., Suite 410 + Ontario, CA 91761 + US + + EMail: chris.newman@sun.com + + + Arnt Gulbrandsen + Oryx Mail Systems GmbH + Schweppermannstr. 8 + D-81671 Muenchen + Germany + + EMail: arnt@oryx.com + Fax: +49 89 4502 9758 + + + Alexey Melnikov + Isode Limited + 5 Castle Business Village, 36 Station Road, + Hampton, Middlesex, TW12 2BX, UK + + EMail: Alexey.Melnikov@isode.com + + + + + + + + + + + + + + +Newman, et al. Standards Track [Page 19] + +RFC 5255 IMAP Internationalization June 2008 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2008). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Newman, et al. Standards Track [Page 20] + diff --git a/docs/rfcs/rfc5257.IMAP_ANNOTATE_extension.txt b/docs/rfcs/rfc5257.IMAP_ANNOTATE_extension.txt new file mode 100644 index 0000000..1d088e5 --- /dev/null +++ b/docs/rfcs/rfc5257.IMAP_ANNOTATE_extension.txt @@ -0,0 +1,1739 @@ + + + + + + +Network Working Group C. Daboo +Request for Comments: 5257 Apple Inc. +Category: Experimental R. Gellens + QUALCOMM Incorporated + June 2008 + + + Internet Message Access Protocol - ANNOTATE Extension + +Status of This Memo + + This memo defines an Experimental Protocol for the Internet + community. It does not specify an Internet standard of any kind. + Discussion and suggestions for improvement are requested. + Distribution of this memo is unlimited. + +Abstract + + The ANNOTATE extension to the Internet Message Access Protocol + permits clients and servers to maintain "meta data" for messages, or + individual message parts, stored in a mailbox on the server. For + example, this can be used to attach comments and other useful + information to a message. It is also possible to attach annotations + to specific parts of a message, so that, for example, they could be + marked as seen, or important, or a comment added. + + Note that this document was the product of a WG that had good + consensus on how to approach the problem. Nevertheless, the WG felt + it did not have enough information on implementation and deployment + hurdles to meet all of the requirements of a Proposed Standard. The + IETF solicits implementations and implementation reports in order to + make further progress. + + Implementers should be aware that this specification may change in an + incompatible manner when going to Proposed Standard status. However, + any incompatible changes will result in a new capability name being + used to prevent problems with any deployments of the experimental + extension. + + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 1] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +Table of Contents + + 1. Introduction and Overview .......................................3 + 2. Conventions Used in This Document ...............................4 + 3. Data Model ......................................................4 + 3.1. Overview ...................................................4 + 3.2. Namespace of Entries and Attributes ........................4 + 3.2.1. Entry Names .........................................5 + 3.2.2. Attribute Names .....................................7 + 3.3. Private Versus Shared ......................................7 + 3.4. Access Control .............................................8 + 3.5. Access to Standard IMAP Flags and Keywords ................11 + 4. IMAP Protocol Changes ..........................................11 + 4.1. General Considerations ....................................11 + 4.2. ANNOTATE Parameter with the SELECT/EXAMINE Commands .......12 + 4.3. ANNOTATION Message Data Item in FETCH Command .............12 + 4.4. ANNOTATION Message Data Item in FETCH Response ............14 + 4.5. ANNOTATION Message Data Item in STORE .....................16 + 4.6. ANNOTATION Interaction with COPY ..........................18 + 4.7. ANNOTATION Message Data Item in APPEND ....................18 + 4.8. ANNOTATION Criterion in SEARCH ............................19 + 4.9. ANNOTATION Key in SORT ....................................20 + 4.10. New ACL Rights ...........................................21 + 5. Formal Syntax ..................................................21 + 6. IANA Considerations ............................................23 + 6.1. Entry and Attribute Registration Template .................23 + 6.2. Entry Registrations .......................................24 + 6.2.1. /comment ...........................................24 + 6.2.2. /flags .............................................24 + 6.2.3. /altsubject ........................................25 + 6.2.4. //comment ............................25 + 6.2.5. //flags/seen .........................26 + 6.2.6. //flags/answered .....................26 + 6.2.7. //flags/flagged ......................27 + 6.2.8. //flags/forwarded ....................27 + 6.3. Attribute Registrations ...................................28 + 6.3.1. value ..............................................28 + 6.3.2. size ...............................................28 + 6.4. Capability Registration ...................................28 + 7. Internationalization Considerations ............................29 + 8. Security Considerations ........................................29 + 9. References .....................................................29 + 9.1. Normative References ......................................29 + 9.2. Informative References ....................................30 + 10. Acknowledgments ...............................................30 + + + + + + +Daboo & Gellens Experimental [Page 2] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +1. Introduction and Overview + + The ANNOTATE extension is present in any IMAP [RFC3501] + implementation that returns "ANNOTATE-EXPERIMENT-1" as one of the + supported capabilities in the CAPABILITY response. + + This extension makes the following changes to the IMAP protocol: + + a. adds a new ANNOTATION message data item for use in FETCH. + + b. adds a new ANNOTATION message data item for use in STORE. + + c. adds a new ANNOTATION search criterion for use in SEARCH. + + d. adds a new ANNOTATION sort key for use in the SORT extension. + + e. adds a new ANNOTATION data item for use in APPEND. + + f. adds a new requirement on the COPY command. + + g. adds a new ANNOTATE parameter for use with the SELECT/EXAMINE + commands. + + h. adds two new response codes to indicate store failures of + annotations. + + i. adds a new untagged response code for the SELECT or EXAMINE + commands to indicate the maximum sized annotation that can be + stored. + + j. adds a new Access Control List (ACL) "bit" for use with the ACL + extensions [RFC2086] and [RFC4314]. + + The data model used for the storage of annotations is based on the + Application Configuration Access Protocol [RFC2244]. Note that there + is no inheritance in annotations. + + If a server supports annotations, then it MUST store all annotation + data permanently, i.e., there is no concept of "session only" + annotations that would correspond to the behavior of "session" flags + as defined in the IMAP base specification. + + In order to provide optimum support for a disconnected client (one + that needs to synchronize annotations for use when offline), servers + SHOULD also support the Conditional STORE [RFC4551] extension. + + The rest of this document describes the data model and protocol + changes more rigorously. + + + +Daboo & Gellens Experimental [Page 3] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +2. Conventions Used in This Document + + The examples in this document use "C:" and "S:" to indicate lines + sent by the client and server, respectively. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + +3. Data Model + +3.1. Overview + + The data model for annotations in ANNOTATE uses a uniquely named + entry that contains a set of standard attributes. Thus, a single + coherent unit of "meta data" for a message is stored as a single + entry, made up of several attributes. + + For example, a comment annotation added to a message has an entry + name of "/comment". This entry is composed of several attributes + such as "value", "size", etc., that contain the properties and data + of the entry. + + The protocol changes to IMAP, described below, allow a client to + access or change the values of any attribute in any entry in a + message annotation, assuming it has sufficient access rights to do so + (see Section 3.4 for specifics). + +3.2. Namespace of Entries and Attributes + + A message may contain zero or more annotations, each of which is a + single uniquely named entry. Each entry has a hierarchical name, + with each component of the name separated by a slash ("/"). An entry + name MUST NOT contain two consecutive "/" characters and MUST NOT end + with a "/" character. + + Each entry is made up of a set of attributes. Each attribute has a + hierarchical name, with each component of the name separated by a + period ("."). An attribute name MUST NOT contain two consecutive "." + characters and MUST NOT end with a "." character. + + The value of an attribute is "NIL" (has no value), or is a string of + zero or more octets. + + Entry and attribute names MUST NOT contain asterisk ("*") or percent + ("%") characters, and MUST NOT contain non-ASCII characters or the + NULL octet. Invalid entry or attribute names result in a BAD + response in any IMAP commands where they are used. + + + +Daboo & Gellens Experimental [Page 4] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + Attribute names MUST NOT contain any hierarchical components with the + names "priv" or "shared", as those have special meaning (see Section + 3.3). + + Entry and attribute names are case-sensitive. + + Use of control or punctuation characters in entry and attribute names + is strongly discouraged. + + This specification defines an initial set of entry and attribute + names available for use in message annotations. In addition, an + extension mechanism is described to allow additional names to be + added as needed. + +3.2.1. Entry Names + + Entry names MUST be specified in a standards track or IESG approved + experimental RFC, or fall under the vendor namespace. See Section + 6.1 for the registration template. + + / + Defines the top-level of entries associated with an entire + message. This entry itself does not contain any attributes. All + entries that start with a numeric character ("0" - "9") refer to + an annotation on a specific body part. All other entries are for + annotations on the entire message. + + /comment + Defines a comment or note associated with an entire message. + + /flags + This entry hierarchy is reserved for future use. + + /altsubject + Contains text supplied by the message recipient to be used by the + client, instead of the original message Subject. + + /vendor/ + Defines the top-level of entries associated with an entire message + as created by a particular product of some vendor. These sub- + entries can be used by vendors to provide client-specific + annotations. The vendor-token MUST be registered with IANA, using + the [RFC2244] vendor subtree registry. + + / + Defines the top-level of entries associated with a specific body + part of a message. This entry itself does not contain any + attributes. The section-part is a numeric part specifier. Its + + + +Daboo & Gellens Experimental [Page 5] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + syntax is the same as the section-part ABNF element defined in + [RFC3501]. The server MUST return a BAD response if the client + uses an incorrect part specifier (either incorrect syntax or a + specifier referring to a non-existent part). The server MUST + return a BAD response if the client uses an empty part specifier + (which is used in IMAP to represent the entire message). + + //comment + Defines a comment or note associated with a specific body part of + a message. + + //flags + Defines the top-level of entries associated with the flag state + for a specific body part of a message. All sub-entries are + maintained entirely by the client. There is no implicit change to + any flag by the server. + + //flags/seen + This is similar to the IMAP \Seen flag, except it applies + to only the body part referenced by the entry. + + //flags/answered + This is similar to the IMAP \Answered flag, except it + applies to only the body part referenced by the entry. + + //flags/flagged + This is similar to the IMAP \Flagged flag, except it + applies to only the body part referenced by the entry. + + //flags/forwarded + This is similar to the IMAP $Forwarded keyword, except it + applies to only the body part referenced by the entry. + + Defines flags for a specific body part of a message. The "value" + attribute of each of the entries described above must be either + "1", "0", or "NIL". "1" corresponds to the flag being set. + + //vendor/ + Defines the top-level of entries associated with a specific body + part of a message as created by a particular product of some + vendor. This entry can be used by vendors to provide client + specific annotations. The vendor-token MUST be registered with + IANA. + + + + + + + + +Daboo & Gellens Experimental [Page 6] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +3.2.2. Attribute Names + + Attribute names MUST be specified in a standards track or IESG + approved experimental RFC. See Section 6.1 for the registration + template. + + All attribute names implicitly have a ".priv" and a ".shared" suffix + that maps to private and shared versions of the entry. Searching or + fetching without using either suffix will include both. The client + MUST specify either a ".priv" or ".shared" suffix when storing an + annotation or sorting on annotations. + + value + A string or binary data representing the value of the annotation. + To delete an annotation, the client can store "NIL" into the + value. If the client requests the value attribute for a non- + existent entry, then the server MUST return "NIL" for the value. + The content represented by the string is determined by the + content-type used to register the entry (see Section 6.1 for entry + registration templates). Where applicable, the registered + content-type MUST include a charset parameter. Text values SHOULD + use the utf-8 [RFC3629] character set. Note that binary data + (data which may contain the NULL octet) is allowed (e.g., for + storing images), and this extension uses the "literal8" syntax + element [RFC4466] to allow such data to be written to or read from + the server. + + size + The size of the value, in octets. Set automatically by the + server, read-only to clients. If the client requests the size + attribute for a non-existent entry, then the server MUST return + "0" (zero) for the size. + +3.3. Private Versus Shared + + Some IMAP mailboxes are private, accessible only to the owning user. + Other mailboxes are not, either because the owner has set an ACL + [RFC4314] that permits access by other users, or because it is a + shared mailbox. + + This raises the issue of shared versus private annotations. + + If all annotations are private, it is then impossible to have + annotations in a shared or otherwise non-private mailbox be visible + to other users. This eliminates what could be a useful aspect of + annotations in a shared environment. An example of such use is a + shared IMAP folder containing bug reports. Engineers may want to use + + + + +Daboo & Gellens Experimental [Page 7] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + annotations to add information to existing messages, indicate + assignments, status, etc. This use requires shared annotations. + + If all annotations are shared, it is impossible to use annotations + for private notes on messages in shared mailboxes. Also, modifying + an ACL to permit access to a mailbox by other users may + unintentionally expose private information. + + There are also situations in which both shared and private + annotations are useful. For example, an administrator may want to + set shared annotations on messages in a shared folder, which + individual users may wish to supplement with additional notes. + + If shared and private annotations are to coexist, we need a clear way + to differentiate them. Also, it should be as easy as possible for a + client to access both and not overlook either. There is also a + danger in allowing a client to store an annotation without knowing if + it is shared or private. + + This document proposes two standard suffixes for all attributes: + ".shared" and ".priv". A SEARCH or FETCH command that specifies + neither, uses both. STORE, APPEND, and SORT commands MUST explicitly + use ".priv" or ".shared" suffixes. + + If the ANNOTATE extension is present, support for shared annotations + in servers is REQUIRED, while support for private annotations in + servers is OPTIONAL. This recognizes the fact that support for + private annotations may introduce a significant increase in + complexity to a server in terms of tracking ownership of the + annotations, how quota is determined for users based on their own + annotations, etc. Clients that support the ANNOTATE extension MUST + handle both shared and private annotations. + +3.4. Access Control + + A user needs to have appropriate rights in order to read or write + ".priv" or ".shared" annotation values. How those rights are + calculated depends on whether or not the ACL [RFC2086] extension or + its update [RFC4314] is present. If a client attempts to store or + fetch an annotation to which they do not have the appropriate rights, + the server MUST respond with a NO response. + + When the ACL extension is not present, access to annotation values is + governed by the nature of the selected state, in particular whether + the mailbox was SELECTED or EXAMINED in READ-ONLY or READ-WRITE mode. + + + + + + +Daboo & Gellens Experimental [Page 8] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + When the ACL extension is present, the server MUST recognize the new + ACL "n" right, in addition to the ones defined by the ACL extension + itself. + + For ".priv" annotation values, the "r" right controls both read and + write access. When it is on, access to ".priv" annotations is + allowed; when it is off, access to ".priv" annotations is disallowed. + + For ".shared" annotation values, the "r" right controls read access. + When it is on, ".shared" annotations can be read; when it is off, + ".shared" annotations cannot be read. + + For ".shared" annotation values, the "n" right controls write access. + When it is on, ".shared" annotations can be changed or created + through either a STORE or APPEND command; when it is off, ".shared" + annotations cannot be changed or created. The "n" right constitutes + a "shared flag right" as defined in Section 6.2 of [RFC4314]. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 9] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + A summary of all the access control restrictions is tabulated below + + +---------------+---------------+-----------------------------------+ + | Server Type | Action on | Type of mailbox | + | | annotation | | + +===============+===============+===================================+ + | | | | + | | read .priv | Any mailbox that can be SELECTED | + | | values | or EXAMINED. | + | | | | + | +---------------+-----------------------------------+ + | | | | + | | write .priv | Any SELECTED [READ-WRITE] mailbox.| + | | values | SELECTED [READ-ONLY] mailboxes MAY| + | Server | | also permit writes. | + | without | | | + | ACL Extension +---------------+-----------------------------------+ + | | | | + | | read .shared | Any mailbox that can be SELECTED | + | | values | or EXAMINED. | + | | | | + | +---------------+-----------------------------------+ + | | | | + | | write .shared | Any mailbox that can be SELECTED | + | | values | or EXAMINED and is [READ-WRITE]. | + | | | | + +---------------+---------------+-----------------------------------+ + | | | | + | | read .priv | Any mailbox with the "r" | + | | values | ACL right. | + | | | | + | +---------------+-----------------------------------+ + | | | | + | | write .priv | Any mailbox with the "r" | + | Server | values | ACL right. | + | with | | | + | ACL Extension +---------------+-----------------------------------+ + | | | | + | | read .shared | Any mailbox with the "r" | + | | values | ACL right. | + | | | | + | +---------------+-----------------------------------+ + | | | | + | | write .shared | Any mailbox with the "n" | + | | values | ACL right. | + | | | | + +---------------+---------------+-----------------------------------+ + + + + +Daboo & Gellens Experimental [Page 10] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +3.5. Access to Standard IMAP Flags and Keywords + + Due to the ambiguity of how private and shared values would map to + the base IMAP flag and keyword values, the ANNOTATE extension does + not expose IMAP flags or keywords as entries. However, the /flags + annotation entry is reserved for future use and MUST NOT be used by + clients or servers supporting this extension. + + Clients that need to implement shared and private "flags" can create + their own annotation entries for those, completely bypassing the base + IMAP flag/keyword behavior. + +4. IMAP Protocol Changes + +4.1. General Considerations + + Servers may be able to offer only a limited level of support for + annotations in mailboxes, and it is useful for clients to be able to + know what level of support is available. Servers MUST return an + ANNOTATIONS response code during the SELECT or EXAMINE command for a + mailbox to indicate the level of support. Possible data items used + with the ANNOTATIONS response code are: + + "NONE" - this indicates that the mailbox being selected does not + support annotations at all. Clients MUST NOT attempt to use + annotation extensions in commands for this mailbox. + + "READ-ONLY" - this indicates that the annotations supported by the + mailbox cannot be changed by the client. Clients MUST NOT attempt + to store annotations on any messages in a mailbox with this + response code. + + "NOPRIVATE" - this indicates that the server does not support + private annotations on the mailbox. Only shared annotations are + supported. Clients SHOULD only attempt to read or store + annotations attributes with the ".shared" suffix. If a client + uses an attribute with the ".priv" suffix in a FETCH command, then + servers should return the attribute value in the FETCH response as + "NIL". If a client uses an attribute with the ".priv" suffix in a + STORE command (or an APPEND command targeted at the mailbox), then + the server MUST return a NO response. + + numeric values - if servers support writable annotations, then the + server MUST indicate the maximum size in octets for an annotation + value by providing the maximum size value in the response code. + Clients MUST NOT store annotation values of a size greater than + the amount indicated by the server. Servers MUST accept a minimum + + + + +Daboo & Gellens Experimental [Page 11] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + annotation data size of at least 1024 octets if annotations can be + written. + + In addition, the server MAY limit the total number of annotations for + a single message. However, the server MUST provide a minimum + annotation count per message of at least 10. + +4.2. ANNOTATE Parameter with the SELECT/EXAMINE Commands + + The ANNOTATE extension defines a single optional SELECT parameter + [RFC4466] "ANNOTATE", which is used to turn on unsolicited responses + for annotations as described in Section 4.4. This optional parameter + results in a per-mailbox state change, i.e., it must be used in each + SELECT/EXAMINE command in order to be effective, irrespective of + whether it was used in a previous SELECT/EXAMINE during the same + session. + + Example: + + C: a SELECT INBOX (ANNOTATE) + S: * FLAGS (\Answered \Flagged \Draft \Deleted \Seen) + S: * OK [PERMANENTFLAGS (\Answered \Flagged \Draft + \Deleted \Seen \*)] + S: * 10268 EXISTS + S: * 1 RECENT + S: * OK [UNSEEN 10268] + S: * OK [UIDVALIDITY 890061587] + S: * OK [UIDNEXT 34643] + S: * OK [ANNOTATIONS 20480 NOPRIVATE] + S: a OK [READ-WRITE] Completed + + In the above example, a SELECT command with the ANNOTATE parameter + is issued. The response from the server includes the required + ANNOTATIONS response that indicates that the server supports + annotations up to a maximum size of 20480 octets, and does not + support private annotations (only shared). + +4.3. ANNOTATION Message Data Item in FETCH Command + + This extension adds an ANNOTATION message data item to the FETCH + command. This allows clients to retrieve annotations for a range of + messages in the currently selected mailbox. + + ANNOTATION + + The ANNOTATION message data item, when used by the client in the + FETCH command, takes an entry specifier and an attribute + specifier. + + + +Daboo & Gellens Experimental [Page 12] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + Example: + + C: a FETCH 1 (ANNOTATION (/comment value)) + S: * 1 FETCH (ANNOTATION (/comment + (value.priv "My comment" + value.shared "Group note"))) + S: a OK Fetch complete + + In the above example, the content of the "value" attribute for the + "/comment" entry is requested by the client and returned by the + server. Since neither ".shared" nor ".priv" was specified, both + are returned. + + "*" and "%" wild card characters can be used in entry specifiers to + match one or more characters at that position, with the exception + that "%" does not match the "/" hierarchy delimiter. Thus, an entry + specifier of "/%" matches entries such as "/comment" and + "/altsubject", but not "/1/comment". + + Example: + + C: a UID FETCH 1123 (UID ANNOTATION + (/* (value.priv size.priv))) + S: * 12 FETCH (UID 1123 ANNOTATION + (/comment (value.priv "My comment" + size.priv "10") + /altsubject (value.priv "Rhinoceroses!" + size.priv "13") + /vendor/foobar/label.priv + (value.priv "label43" + size.priv "7") + /vendor/foobar/personality + (value.priv "Tallulah Bankhead" + size.priv "17"))) + S: a OK Fetch complete + + In the above example, the contents of the private "value" and + "size" attributes for any entries in the "/" hierarchy are + requested by the client and returned by the server. + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 13] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + Example: + + C: a FETCH 1 (ANNOTATION (/% value.shared)) + S: * 1 FETCH (ANNOTATION + (/comment (value.shared "Patch Mangler") + /altsubject (value.shared "Patches? We don't + need no steenkin patches!"))) + S: a OK Fetch complete + + In the above example, the contents of the shared "value" + attributes for entries at the top level only of the "/" hierarchy + are requested by the client and returned by the server. + + Entry and attribute specifiers can be lists of atomic specifiers, so + that multiple items of each type may be returned in a single FETCH + command. + + Example: + + C: a FETCH 1 (ANNOTATION + ((/comment /altsubject) value.priv)) + S: * 1 FETCH (ANNOTATION + (/comment (value.priv "What a chowder-head") + /altsubject (value.priv "How to crush beer cans"))) + S: a OK Fetch complete + + In the above example, the contents of the private "value" + attributes for the two entries "/comment" and "/altsubject" are + requested by the client and returned by the server. + +4.4. ANNOTATION Message Data Item in FETCH Response + + The ANNOTATION message data item in the FETCH response displays + information about annotations in a message. + + ANNOTATION parenthesized list + + The response consists of a list of entries, each of which have a + list of attribute-value pairs. + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 14] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + Example: + + C: a FETCH 1 (ANNOTATION (/comment value)) + S: * 1 FETCH (ANNOTATION (/comment + (value.priv "My comment" + value.shared NIL))) + S: a OK Fetch complete + + In the above example, a single entry with a single attribute-value + pair is returned by the server. Since the client did not specify + a ".shared" or ".priv" suffix, both are returned. Only the + private attribute has a value (the shared value is "NIL"). + + Example: + + C: a FETCH 1 (ANNOTATION + ((/comment /altsubject) value)) + S: * 1 FETCH (ANNOTATION + (/comment (value.priv "My comment" + value.shared NIL) + /altsubject (value.priv "My subject" + value.shared NIL))) + S: a OK Fetch complete + + In the above example, two entries, each with a single attribute- + value pair, are returned by the server. Since the client did not + specify a ".shared" or ".priv" suffix, both are returned. Only + the private attributes have values; the shared attributes are + "NIL". + + Example: + + C: a FETCH 1 (ANNOTATION + (/comment (value size))) + S: * 1 FETCH (ANNOTATION + (/comment + (value.priv "My comment" + value.shared NIL + size.priv "10" + size.shared "0"))) + S: a OK Fetch complete + + In the above example, a single entry with two attribute-value + pairs is returned by the server. Since the client did not specify + a ".shared" or ".priv" suffix, both are returned. Only the + private attributes have values; the shared attributes are "NIL". + + + + + +Daboo & Gellens Experimental [Page 15] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + Servers SHOULD send ANNOTATION message data items in unsolicited + FETCH responses if an annotation entry is changed by a third-party, + and the ANNOTATE select parameter was used. This allows servers to + keep clients updated with changes to annotations by other clients. + + Unsolicited ANNOTATION responses MUST NOT include ANNOTATION data + values -- only the entry name of the ANNOTATION that has changed. + This restriction avoids sending ANNOTATION data values (which may be + large) to a client unless the client explicitly asks for the value. + + Example: + + C: a STORE 1 +FLAGS (\Seen) + S: * 1 FETCH (FLAGS (\Seen)) + ANNOTATION (/comment)) + S: a OK STORE complete + + In the above example, an unsolicited ANNOTATION response is + returned during a STORE command. The unsolicited response + contains only the entry name of the annotation that changed, and + not its value. + +4.5. ANNOTATION Message Data Item in STORE + + ANNOTATION + + Sets the specified list of entries by adding or replacing the + specified attributes with the values provided. Clients can use + "NIL" for values of attributes it wants to remove from entries. + + The ANNOTATION message data item used with the STORE command has an + implicit ".SILENT" behavior. This means the server does not generate + an untagged FETCH in response to the STORE command and assumes that + the client updates its own cache if the command succeeds. Though + note, that if the Conditional STORE extension [RFC4551] is present, + then an untagged FETCH response with a MODSEQ data item will be + returned by the server as required by [RFC4551]. + + If the server is unable to store an annotation because the size of + its value is too large, the server MUST return a tagged NO response + with a "[ANNOTATE TOOBIG]" response code. + + If the server is unable to store a new annotation because the maximum + number of allowed annotations has already been reached, the server + MUST return a tagged NO response with a "[ANNOTATE TOOMANY]" response + code. + + + + + +Daboo & Gellens Experimental [Page 16] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + Example: + + C: a STORE 1 ANNOTATION (/comment + (value.priv "My new comment")) + S: a OK Store complete + + In the above example, the entry "/comment" is created (if not + already present). Its private attribute "value" is created if not + already present, or replaced if it exists. "value.priv" is set to + "My new comment". + + Example: + + C: a STORE 1 ANNOTATION (/comment + (value.shared NIL)) + S: a OK Store complete + + In the above example, the shared "value" attribute of the entry + "/comment" is removed by storing "NIL" into the attribute. + + Multiple entries can be set in a single STORE command by listing + entry-attribute-value pairs in the list. + + Example: + + C: a STORE 1 ANNOTATION (/comment + (value.priv "Get tix Tuesday") + /altsubject + (value.priv "Wots On")) + S: a OK Store complete + + In the above example, the entries "/comment" and "/altsubject" are + created (if not already present) and the private attribute "value" + is created or replaced for each entry. + + Multiple attributes can be set in a single STORE command by listing + multiple attribute-value pairs in the entry list. + + + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 17] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + Example: + + C: a STORE 1 ANNOTATION (/comment + (value.priv "My new comment" + value.shared "foo's bar")) + S: a OK Store complete + + In the above example, the entry "/comment" is created (if not + already present) and the private and shared "value" attributes are + created if not already present, or replaced if they exist. + +4.6. ANNOTATION Interaction with COPY + + The COPY command can be used to move messages from one mailbox to + another on the same server. Servers that support the ANNOTATION + extension MUST, for each message being copied, copy all ".priv" + annotation data for the current user only, and all ".shared" + annotation data along with the message to the new mailbox. The only + exceptions to this are if the destination mailbox permissions are + such that either the ".priv" or ".shared" annotations are not + allowed, or if the destination mailbox is of a type that does not + support annotations or does not support storing of annotations (a + mailbox that returns a "NONE" or "READ-ONLY" response code in its + ANNOTATIONS response), or if the destination mailbox cannot support + the size of an annotation because it exceeds the ANNOTATIONS value. + Servers MUST NOT copy ".priv" annotation data for users other than + the current user. + +4.7. ANNOTATION Message Data Item in APPEND + + ANNOTATION + + Sets the specified list of entries and attributes in the resulting + message. + + The APPEND command can include annotations for the message being + appended via the addition of a new append data item [RFC4466]. The + new data item can also be used with the multi-append [RFC3502] + extension that allows multiple messages to be appended via a single + APPEND command. + + + + + + + + + + + +Daboo & Gellens Experimental [Page 18] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + Example: + + C: a APPEND drafts ANNOTATION (/comment + (value.priv "Don't send until I say so")) {310} + S: + Ready for literal data + C: MIME-Version: 1.0 + ... + C: + S: a OK APPEND completed + + In the above example, a comment with a private value is added to a + new message appended to the mailbox. The ellipsis represents the + bulk of the message. + +4.8. ANNOTATION Criterion in SEARCH + + ANNOTATION + + The ANNOTATION criterion for the SEARCH command allows a client to + search for a specified string in the value of an annotation entry of + a message. + + Messages that have annotations with entries matching , + attributes matching , and the specified string + in their values are returned in the SEARCH results. The "*" + character can be used in the entry name field to match any content in + those items. The "%" character can be used in the entry name field + to match a single level of hierarchy only. + + Only the "value", "value.priv", and "value.shared" attributes can be + searched. Clients MUST NOT specify an attribute other than either + "value", "value.priv", or "value.shared". Servers MUST return a BAD + response if the client tries to search any other attribute. + + Example: + + C: a SEARCH ANNOTATION /comment value "IMAP4" + S: * SEARCH 2 3 5 7 11 13 17 19 23 + S: a OK Search complete + + In the above example, the message numbers of any messages + containing the string "IMAP4" in the shared or private "value" + attribute of the "/comment" entry are returned in the search + results. + + + + + + + +Daboo & Gellens Experimental [Page 19] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + Example: + + C: a SEARCH ANNOTATION * value.priv "IMAP4" + S: * SEARCH 1 2 3 5 8 13 21 34 + S: a OK Search complete + + In the above example, the message numbers of any messages + containing the string "IMAP4" in the private "value" attribute of + any entry are returned in the search results. + +4.9. ANNOTATION Key in SORT + + ANNOTATION + + The ANNOTATION criterion for the SORT command [RFC5256] instructs the + server to return the sequence numbers or Unique Identifiers (UIDs) of + messages in a mailbox, sorted using the values of the specified + annotations. The ANNOTATION criterion is available if the server + returns both ANNOTATE-EXPERIMENT-1 and SORT as supported capabilities + in the CAPABILITY command response. + + Messages are sorted using the values of the + attributes in the entries. + + Clients MUST provide either the ".priv" or ".shared" suffix to the + attribute name to ensure that the server knows which specific value + to sort on. + + Only the "value.priv" and "value.shared" attributes can be used for + sorting. Clients MUST NOT specify an attribute other than either + "value.priv" or "value.shared". Servers MUST return a BAD response + if the client tries to sort on any other attribute. + + When either "value.priv" or "value.shared" is being sorted, the + server MUST use the character set value specified in the SORT command + to determine the appropriate sort order. + + Example: + + C: a SORT (ANNOTATION /altsubject value.shared) UTF-8 ALL + S: * SORT 2 3 4 5 1 11 10 6 7 9 8 + S: a OK Sort complete + + In the above example, the message numbers of all messages are + returned, sorted according to the shared "value" attribute of the + "/altsubject" entry. + + + + + +Daboo & Gellens Experimental [Page 20] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + Note that the ANNOTATION sort key must include a fully specified + entry -- wild cards are not allowed. + +4.10. New ACL Rights + + As discussed in Section 3.4, this extension adds a new "n" right to + the list of rights provided by the ACL extensions [RFC2086] and + [RFC4314]. + +5. 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 + [RFC3501] with the new definitions in [RFC4466] superseding those in + [RFC3501]. + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of upper or lower case characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. + + ann-size = "NONE" / + (("READ-ONLY" / nz-number) + [SP "NOPRIVATE"]) + ; response codes indicating the level of + ; support for annotations in a mailbox + + append-ext =/ att-annotate + ; modifies [RFC3501] extension behaviour + + att-annotate = "ANNOTATION" SP + "(" entry-att *(SP entry-att) ")" + + att-search = "value" / "value.priv" / "value.shared" + ; the only attributes that can be searched + + att-sort = "value.priv" / "value.shared" + ; the only attributes that can be sorted + + att-value = attrib SP value + + attrib = astring + ; dot-separated attribute name + ; MUST NOT contain "*" or "%" + + + + + +Daboo & Gellens Experimental [Page 21] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + attribs = attrib / "(" attrib *(SP attrib) ")" + ; one or more attribute specifiers + + capability =/ "ANNOTATE-EXPERIMENT-1" + ; defines the capability for this extension + + entries = entry-match / + "(" entry-match *(SP entry-match) ")" + + entry = astring + ; slash-separated path to entry + ; MUST NOT contain "*" or "%" + + entry-att = entry SP "(" att-value *(SP att-value) ")" + + entry-match = list-mailbox + ; slash-separated path to entry + ; MAY contain "*" or "%" for use as wild cards + + fetch-att =/ "ANNOTATION" SP "(" entries SP attribs ")" + ; modifies original IMAP fetch-att + + msg-att-dynamic =/ "ANNOTATION" SP + ( "(" entry-att *(SP entry-att) ")" / + "(" entry *(SP entry) ")" ) + ; extends FETCH response with annotation data + + resp-text-code =/ "ANNOTATE" SP "TOOBIG" / + "ANNOTATE" SP "TOOMANY" / + "ANNOTATIONS" SP ann-size + ; new response codes + + search-key =/ "ANNOTATION" SP entry-match SP att-search + SP value + ; modifies original IMAP search-key + + select-param =/ "ANNOTATE" + ; defines the select parameter used with + ; ANNOTATE extension + + sort-key =/ "ANNOTATION" SP entry SP att-sort + ; modifies original sort-key + + store-att-flags =/ att-annotate + ; modifies original IMAP STORE command + + value = nstring / literal8 + + + + +Daboo & Gellens Experimental [Page 22] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +6. IANA Considerations + + Entry names MUST be specified in a standards track or IESG approved + experimental RFC, or fall under the vendor namespace. Vendor names + MUST be registered. + + Attribute names MUST be specified in a standards track or IESG + approved experimental RFC. + + Each entry registration MUST include a content-type that is used to + indicate the nature of the annotation value. Where applicable, a + charset parameter MUST be included with the content-type. + +6.1. Entry and Attribute Registration Template + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [] Entry [] Attribute + + Name: ______________________________ + + Description: _______________________ + + ____________________________________ + + ____________________________________ + + Content-Type:_______________________ + + Contact person: ____________________ + + email: ____________________ + + + + + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 23] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +6.2. Entry Registrations + + The following templates specify the IANA registrations of annotation + entries specified in this document. + +6.2.1. /comment + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [X] Entry [] Attribute + + Name: /comment + + Description: Defined in IMAP ANNOTATE extension document. + + Content-Type: text/plain; charset=utf-8 + + Contact person: Cyrus Daboo + + email: cyrus@daboo.name + +6.2.2. /flags + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [X] Entry [] Attribute + + Name: /flags + + Description: Reserved entry hierarchy. + + Content-Type: - + + Contact person: Cyrus Daboo + + email: cyrus@daboo.name + + + + + + + + + +Daboo & Gellens Experimental [Page 24] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +6.2.3. /altsubject + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [X] Entry [] Attribute + + Name: /altsubject + + Description: Defined in IMAP ANNOTATE extension document. + + Content-Type: text/plain; charset=utf-8 + + Contact person: Cyrus Daboo + + email: cyrus@daboo.name + +6.2.4. //comment + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [X] Entry [] Attribute + + Name: //comment + + Description: Defined in IMAP ANNOTATE extension document. + + Content-Type: text/plain; charset=utf-8 + + Contact person: Cyrus Daboo + + email: cyrus@daboo.name + + + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 25] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +6.2.5. //flags/seen + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [X] Entry [] Attribute + + Name: //flags/seen + + Description: Defined in IMAP ANNOTATE extension document. + + Content-Type: text/plain; charset=utf-8 + + Contact person: Cyrus Daboo + + email: cyrus@daboo.name + +6.2.6. //flags/answered + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [X] Entry [] Attribute + + Name: //flags/answered + + Description: Defined in IMAP ANNOTATE extension document. + + Content-Type: text/plain; charset=utf-8 + + Contact person: Cyrus Daboo + + email: cyrus@daboo.name + + + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 26] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +6.2.7. //flags/flagged + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [X] Entry [] Attribute + + Name: //flags/flagged + + Description: Defined in IMAP ANNOTATE extension document. + + Content-Type: text/plain; charset=utf-8 + + Contact person: Cyrus Daboo + + email: cyrus@daboo.name + +6.2.8. //flags/forwarded + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [X] Entry [] Attribute + + Name: //flags/forwarded + + Description: Defined in IMAP ANNOTATE extension document. + + Content-Type: text/plain; charset=utf-8 + + Contact person: Cyrus Daboo + + email: cyrus@daboo.name + + + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 27] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +6.3. Attribute Registrations + + The following templates specify the IANA registrations of annotation + attributes specified in this document. + +6.3.1. value + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [] Entry [X] Attribute + + Name: value + + Description: Defined in IMAP ANNOTATE extension document. + + Contact person: Cyrus Daboo + + email: cyrus@daboo.name + +6.3.2. size + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [] Entry [X] Attribute + + Name: size + + Description: Defined in IMAP ANNOTATE extension document. + + Contact person: Cyrus Daboo + + email: cyrus@daboo.name + +6.4. Capability Registration + + This document registers "ANNOTATE-EXPERIMENT-1" as an IMAPEXT + capability. + + + + + + + + +Daboo & Gellens Experimental [Page 28] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +7. Internationalization Considerations + + Annotations may contain values that include text strings, and both + searching and sorting are possible with annotations. Servers MUST + follow standard IMAP text normalization, character set conversion, + and collation rules when such operations are carried out, as would be + done for other textual fields being searched or sorted on. + +8. Security Considerations + + Annotations whose values are intended to remain private MUST be + stored in ".priv" values instead of ".shared" values, which may be + accessible to other users. + + Excluding the above issues, the ANNOTATE extension does not raise any + security considerations that are not present in the base IMAP + protocol; these issues are discussed in [RFC3501]. + +9. References + +9.1. Normative References + + [RFC2086] Myers, J., "IMAP4 ACL extension", RFC 2086, January 1997. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2244] Newman, C. and J. Myers, "ACAP -- Application + Configuration Access Protocol", RFC 2244, November 1997. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [RFC3502] Crispin, M., "Internet Message Access Protocol (IMAP) - + MULTIAPPEND Extension", RFC 3502, March 2003. + + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. + + [RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) Extension", + RFC 4314, December 2005. + + [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 + ABNF", RFC 4466, April 2006. + + [RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", STD 68, RFC 5234, January + 2008. + + + +Daboo & Gellens Experimental [Page 29] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + [RFC5256] Crispin, M. and K. Murchison, "Internet Message Access + Protocol - SORT and THREAD Extensions", RFC 5256, June + 2008. + +9.2. Informative References + + [RFC4551] Melnikov, A. and S. Hole, "IMAP Extension for Conditional + STORE Operation or Quick Flag Changes Resynchronization", + RFC 4551, June 2006. + +10. Acknowledgments + + Many thanks to Chris Newman for his detailed comments on the first + draft of this document, and to the participants at the ACAP working + dinner in Pittsburgh. The participants of the IMAPext working group + made significant contributions to this work. + +Authors' Addresses + + Cyrus Daboo + Apple Inc. + 1 Infinite Loop + Cupertino, CA 95014 + USA + + EMail: cyrus@daboo.name + URI: http://www.apple.com/ + + + Randall Gellens + QUALCOMM Incorporated + 5775 Morehouse Dr. + San Diego, CA 92121-2779 + USA + + EMail: randy@qualcomm.com + + + + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 30] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2008). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 31] + diff --git a/docs/rfcs/rfc5258.IMAP4_LIST_command_extension.txt b/docs/rfcs/rfc5258.IMAP4_LIST_command_extension.txt new file mode 100644 index 0000000..a80ec15 --- /dev/null +++ b/docs/rfcs/rfc5258.IMAP4_LIST_command_extension.txt @@ -0,0 +1,1739 @@ + + + + + + +Network Working Group B. Leiba +Request for Comments: 5258 IBM T.J. Watson Research Center +Obsoletes: 3348 A. Melnikov +Updates: 2193 Isode Limited +Category: Standards Track June 2008 + + + Internet Message Access Protocol version 4 - LIST Command Extensions + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + IMAP4 has two commands for listing mailboxes: LIST and LSUB. As we + have added extensions, such as Mailbox Referrals, that have required + specialized lists we have had to expand the number of list commands, + since each extension must add its function to both LIST and LSUB, and + these commands are not, as they are defined, extensible. If we've + needed the extensions to work together, we've had to add a set of + commands to mix the different options, the set increasing in size + with each new extension. This document describes an extension to the + base LIST command that will allow these additions to be done with + mutually compatible options to the LIST command, avoiding the + exponential increase in specialized list commands. + + + + + + + + + + + + + + + + + + + + + +Leiba & Melnikov Standards Track [Page 1] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + +Table of Contents + + 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 + 2. Conventions Used in This Document . . . . . . . . . . . . . . 4 + 3. Extended LIST Command . . . . . . . . . . . . . . . . . . . . 4 + 3.1. Initial List of Selection Options . . . . . . . . . . . . 7 + 3.2. Initial List of Return Options . . . . . . . . . . . . . . 8 + 3.3. General Principles for Returning LIST Responses . . . . . 9 + 3.4. Additional Requirements on LIST-EXTENDED Clients . . . . . 9 + 3.5. CHILDINFO Extended Data Item . . . . . . . . . . . . . . . 10 + 4. The CHILDREN Return Option . . . . . . . . . . . . . . . . . . 11 + 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 + 6. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 19 + 7. Internationalization Considerations . . . . . . . . . . . . . 22 + 8. Security Considerations . . . . . . . . . . . . . . . . . . . 23 + 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 + 9.1. Guidelines for IANA . . . . . . . . . . . . . . . . . . . 23 + 9.2. Registration Procedure and Change Control . . . . . . . . 23 + 9.3. Registration Template for LIST-EXTENDED Options . . . . . 25 + 9.4. Initial LIST-EXTENDED Option Registrations . . . . . . . . 25 + 9.5. Registration Template for LIST-EXTENDED Extended Data + Item . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 + 9.6. Initial LIST-EXTENDED Extended Data Item Registrations . . 28 + 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 29 + 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 + 11.1. Normative References . . . . . . . . . . . . . . . . . . . 29 + 11.2. Informative References . . . . . . . . . . . . . . . . . . 30 + + + + + + + + + + + + + + + + + + + + + + + + +Leiba & Melnikov Standards Track [Page 2] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + +1. Introduction and Overview + + The LIST command is extended by amending the syntax to allow options + and multiple patterns to be specified. The list of options replaces + the several commands that are currently used to mix and match the + information requested. The new syntax is backward compatible, with + no ambiguity: the new syntax is being used if one of the following + conditions is true: + + 1. if the first word after the command name begins with a + parenthesis ("LIST selection options") + + 2. if the second word after the command name begins with a + parenthesis ("multiple mailbox patterns") + + 3. if the LIST command has more than 2 parameters ("LIST return + options") + + Otherwise the original syntax is used. + + By adding options to the LIST command, we are announcing the intent + to phase out and eventually to deprecate the RLIST and RLSUB commands + described in [MBRef]. We are also defining the mechanism to request + extended mailbox information, such as is described in the Child + Mailbox Extension [CMbox]. The base LSUB command is not deprecated + by this extension; rather, this extension adds a way to obtain + subscription information with more options, with those server + implementations that support it. Clients that simply need a list of + subscribed mailboxes, as provided by the LSUB command, SHOULD + continue to use that command. + + This document defines an IMAP4 extension that is identified by the + capability string "LIST-EXTENDED". The LIST-EXTENDED extension makes + the following changes to the IMAP4 protocol, which are described in + more detail in Section 3 and Section 4: + + a. defines new syntax for LIST command options. + + b. extends LIST to allow for multiple mailbox patterns. + + c. adds LIST command selection options: SUBSCRIBED, REMOTE, and + RECURSIVEMATCH. + + d. adds LIST command return options: SUBSCRIBED and CHILDREN. + + e. adds new mailbox attributes: "\NonExistent", "\Subscribed", + "\Remote", "\HasChildren", and "\HasNoChildren". + + + + +Leiba & Melnikov Standards Track [Page 3] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + f. adds CHILDINFO extended data item. + +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", "SHOULD", "SHOULD NOT", and "MAY" + are used in this document as specified in RFC 2119 [Kwds]. + + The term "canonical LIST pattern" refers to the canonical pattern + constructed internally by the server from the reference and mailbox + name arguments (Section 6.3.8 of [IMAP4]). The [IMAP4] LIST command + returns only mailboxes that match the canonical LIST pattern. + + Other terms are introduced where they are referenced for the first + time. + +3. Extended LIST Command + + This extension updates the syntax of the LIST command to allow for + multiple mailbox patterns to be specified, if they are enclosed in + parentheses. A mailbox name matches a list of mailbox patterns if it + matches at least one mailbox pattern. If a mailbox name matches + multiple mailbox patterns from the list, the server SHOULD return + only a single LIST response. + + Note that the non-extended LIST command is required to treat an empty + ("" string) mailbox name argument as a special request to return the + hierarchy delimiter and the root name of the name given in the + reference parameter (as per [IMAP4]). However, ANY extended LIST + command (extended in any of 3 ways specified in Section 1, or any + combination thereof) MUST NOT treat the empty mailbox name as such a + special request, and any regular processing described in this + document applies. In particular, if an extended LIST command has + multiple mailbox names and one (or more) of them is the empty string, + the empty string MUST be ignored for the purpose of matching. + + Some servers might restrict which patterns are allowed in a LIST + command. If a server doesn't accept a particular pattern, it MUST + silently ignore it. + + The LIST command syntax is also extended in two additional ways: by + adding a parenthesized list of command options between the command + name and the reference name (LIST selection options) and an optional + + + + + + +Leiba & Melnikov Standards Track [Page 4] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + list of options at the end that control what kind of information + should be returned (LIST return options). See the formal syntax in + Section 6 for specific details. + + A LIST selection option tells the server which mailbox names should + be selected by the LIST operation. The server should return + information about all mailbox names that match any of the "canonical + LIST pattern" (as described above) and satisfy additional selection + criteria (if any) specified by the LIST selection options. Let's + call any such mailbox name a "matched mailbox name". When multiple + selection options are specified, the server MUST return information + about mailbox names that satisfy every selection option, unless a + description of a particular specified option prescribes special + rules. An example of an option prescribing special rules is the + RECURSIVEMATCH selection option described later in this section. We + will use the term "selection criteria" when referring collectively to + all selection options specified in a LIST command. + + A LIST return option controls which information is returned for each + matched mailbox name. Note that return options MUST NOT cause the + server to report information about additional mailbox names. If the + client has not specified any return option, only information about + attributes should be returned by the server. (Of course, the server + is allowed to include any other information at will.) + + Both selection and return command options will be defined in this + document and in approved extension documents; each option will be + enabled by a capability string (one capability may enable multiple + options), and a client MUST NOT send an option for which the server + has not advertised support. A server MUST respond to options it does + not recognize with a BAD response. The client SHOULD NOT specify any + option more than once; however, if the client does this, the server + MUST act as if it received the option only once. The order in which + options are specified by the client is not significant. + + In general, each selection option except RECURSIVEMATCH will have a + corresponding return option. The REMOTE selection option is an + anomaly in this regard, and does not have a corresponding return + option. That is because it expands, rather than restricts, the set + of mailboxes that are returned. Future extensions to this + specification should keep parallelism in mind and define a pair of + corresponding options. + + This extension is identified by the capability string + "LIST-EXTENDED", and support for it is a prerequisite for any future + extensions that require specialized forms of the LIST command. Such + extensions MUST refer to this document and MUST add their function + through command options as described herein. Note that extensions + + + +Leiba & Melnikov Standards Track [Page 5] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + that don't require support for an extended LIST command, but use + extended LIST responses (see below), don't need to advertise the + "LIST-EXTENDED" capability string. + + This extension also defines extensions to the LIST response, allowing + a series of extended fields at the end, a parenthesized list of + tagged data (also referred to as "extended data item"). The first + element of an extended field is a tag, which identifies the type of + data. Tags MUST be registered with IANA, as described in Section 9.5 + of this document. An example of such an extended set might be + + tablecloth (("edge" "lacy") ("color" "red"))) (X-Sample "text")) + + or + + tablecloth ("edge" "lacy")) (X-Sample "text" "more text")) + + See the formal syntax, in Section 6, for the full syntactic details. + The server MUST NOT return any extended data item unless the client + has expressed its ability to support extended LIST responses, for + example, by using an extended LIST command. The server MAY return + data in the extended fields that was not directly solicited by the + client in the corresponding LIST command. For example, the client + can enable extra extended fields by using another IMAP extension that + make use of the extended LIST responses. The client MUST ignore all + extended fields it doesn't recognize. + + The LIST-EXTENDED capability also defines several new mailbox + attributes. + + The "\NonExistent" attribute indicates that a mailbox name does not + refer to an existing mailbox. Note that this attribute is not + meaningful by itself, as mailbox names that match the canonical LIST + pattern but don't exist must not be returned unless one of the two + conditions listed below is also satisfied: + + a. The mailbox name also satisfies the selection criteria (for + example, it is subscribed and the "SUBSCRIBED" selection option + has been specified). + + b. "RECURSIVEMATCH" has been specified, and the mailbox name has at + least one descendant mailbox name that does not match the LIST + pattern and does match the selection criteria. + + In practice, this means that the "\NonExistent" attribute is usually + returned with one or more of "\Subscribed", "\Remote", + "\HasChildren", or the CHILDINFO extended data item (see their + description below). + + + +Leiba & Melnikov Standards Track [Page 6] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + The "\NonExistent" attribute implies "\NoSelect". The "\NonExistent" + attribute MUST be supported and MUST be accurately computed. + +3.1. Initial List of Selection Options + + The selection options defined in this specification are as follows: + + SUBSCRIBED - causes the LIST command to list subscribed names, + rather than the existing mailboxes. This will often be a subset + of the actual mailboxes. It's also possible for this list to + contain the names of mailboxes that don't exist. In any case, the + list MUST include exactly those mailbox names that match the + canonical list pattern and are subscribed to. This option is + intended to supplement the LSUB command. Of particular note are + the mailbox attributes as returned by this option, compared with + what is returned by LSUB. With the latter, the attributes + returned may not reflect the actual attribute status on the + mailbox name, and the \NoSelect attribute has a second special + meaning (it indicates that this mailbox is not, itself, + subscribed, but that it has descendant mailboxes that are). With + the SUBSCRIBED selection option described here, the attributes are + accurate and complete, and have no special meanings. "LSUB" and + "LIST (SUBSCRIBED)" are, thus, not the same thing, and some + servers must do significant extra work to respond to "LIST + (SUBSCRIBED)". Because of this, clients SHOULD continue to use + "LSUB" unless they specifically want the additional information + offered by "LIST (SUBSCRIBED)". + + This option defines a new mailbox attribute, "\Subscribed", that + indicates that a mailbox name is subscribed to. The "\Subscribed" + attribute MUST be supported and MUST be accurately computed when + the SUBSCRIBED selection option is specified. + + Note that the SUBSCRIBED selection option implies the SUBSCRIBED + return option (see below). + + REMOTE - causes the LIST command to show remote mailboxes as well as + local ones, as described in [MBRef]. This option is intended to + replace the RLIST command and, in conjunction with the SUBSCRIBED + selection option, the RLSUB command. + + This option defines a new mailbox attribute, "\Remote", that + indicates that a mailbox is a remote mailbox. The "\Remote" + attribute MUST be accurately computed when the REMOTE option is + specified. + + The REMOTE selection option has no interaction with other options. + Its effect is to tell the server to apply the other options, if + + + +Leiba & Melnikov Standards Track [Page 7] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + any, to remote mailboxes, in addition to local ones. In + particular, it has no interaction with RECURSIVEMATCH (see below). + A request for (REMOTE RECURSIVEMATCH) is invalid, because a + request for (RECURSIVEMATCH) is. A request for (REMOTE + RECURSIVEMATCH SUBSCRIBED) is asking for all subscribed mailboxes, + both local and remote. + + RECURSIVEMATCH - this option forces the server to return information + about parent mailboxes that don't match other selection options, + but have some submailboxes that do. Information about children is + returned in the CHILDINFO extended data item, as described in + Section 3.5. + + Note 1: In order for a parent mailbox to be returned, it still has + to match the canonical LIST pattern. + + Note 2: When returning the CHILDINFO extended data item, it + doesn't matter whether or not the submailbox matches the canonical + LIST pattern. See also example 9 in Section 5. + + The RECURSIVEMATCH option MUST NOT occur as the only selection + option (or only with REMOTE), as it only makes sense when other + selection options are also used. The server MUST return BAD + tagged response in such case. + + Note that even if the RECURSIVEMATCH option is specified, the + client MUST still be able to handle a case when a CHILDINFO + extended data item is returned and there are no submailboxes that + meet the selection criteria of the subsequent LIST command, as + they can be deleted/renamed after the LIST response was sent, but + before the client had a chance to access them. + +3.2. Initial List of Return Options + + The return options defined in this specification are as follows: + + SUBSCRIBED - causes the LIST command to return subscription state + for all matching mailbox names. The "\Subscribed" attribute MUST + be supported and MUST be accurately computed when the SUBSCRIBED + return option is specified. Further, all mailbox flags MUST be + accurately computed (this differs from the behavior of the LSUB + command). + + CHILDREN - requests mailbox child information as originally proposed + in [CMbox]. See Section 4, below, for details. This option MUST + be supported by all servers. + + + + + +Leiba & Melnikov Standards Track [Page 8] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + +3.3. General Principles for Returning LIST Responses + + This section outlines several principles that can be used by server + implementations of this document to decide whether a LIST response + should be returned, as well as how many responses and what kind of + information they may contain. + + 1. At most one LIST response should be returned for each mailbox + name that matches the canonical LIST pattern. Server + implementors must not assume that clients will be able to + assemble mailbox attributes and other information returned in + multiple LIST responses. + + 2. There are only two reasons for including a matching mailbox name + in the responses to the LIST command (note that the server is + allowed to return unsolicited responses at any time, and such + responses are not governed by this rule): + + A. The mailbox name also satisfies the selection criteria. + + B. The mailbox name doesn't satisfy the selection criteria, but + it has at least one descendant mailbox name that satisfies + the selection criteria and that doesn't match the canonical + LIST pattern. + + For more information on this case, see the CHILDINFO extended + data item described in Section 3.5. Note that the CHILDINFO + extended data item can only be returned when the + RECURSIVEMATCH selection option is specified. + + 3. Attributes returned in the same LIST response must be treated + additively. For example, the following response + + S: * LIST (\Subscribed \NonExistent) "/" "Fruit/Peach" + + means that the "Fruit/Peach" mailbox doesn't exist, but it is + subscribed. + +3.4. Additional Requirements on LIST-EXTENDED Clients + + All clients that support this extension MUST treat an attribute with + a stronger meaning as implying any attribute that can be inferred + from it. For example, the client must treat the presence of the + \NoInferiors attribute as if the \HasNoChildren attribute was also + sent by the server. + + + + + + +Leiba & Melnikov Standards Track [Page 9] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + The following table summarizes inference rules described in + Section 3. + + +--------------------+-------------------+ + | returned attribute | implied attribute | + +--------------------+-------------------+ + | \NoInferiors | \HasNoChildren | + | \NonExistent | \NoSelect | + +--------------------+-------------------+ + +3.5. CHILDINFO Extended Data Item + + The CHILDINFO extended data item MUST NOT be returned unless the + client has specified the RECURSIVEMATCH selection option. + + The CHILDINFO extended data item in a LIST response describes the + selection criteria that has caused it to be returned and indicates + that the mailbox has at least one descendant mailbox that matches the + selection criteria. + + The LSUB command indicates this condition by using the "\NoSelect" + attribute, but the LIST (SUBSCRIBED) command MUST NOT do that, since + "\NoSelect" retains its original meaning here. Further, the + CHILDINFO extended data item is more general, in that it can be used + with any extended set of selection criteria. + + Note: Some servers allow for mailboxes to exist without requiring + their parent to exist. For example, a mailbox "Customers/ABC" can + exist while the mailbox "Customers" does not. As CHILDINFO extended + data item is not allowed if the RECURSIVEMATCH selection option is + not specified, such servers SHOULD use the "\NonExistent + \HasChildren" attribute pair to signal to the client that there is a + descendant mailbox that matches the selection criteria. See example + 11 in Section 5. + + The returned selection criteria allow the client to distinguish a + solicited response from an unsolicited one, as well as to distinguish + among solicited responses caused by multiple pipelined LIST commands + that specify different criteria. + + Servers SHOULD ONLY return a non-matching mailbox name along with + CHILDINFO if at least one matching child is not also being returned. + That is, servers SHOULD suppress redundant CHILDINFO responses. + + Examples 8 and 10 in Section 5 demonstrate the difference between + present CHILDINFO extended data item and the "\HasChildren" + attribute. + + + + +Leiba & Melnikov Standards Track [Page 10] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + The following table summarizes interaction between the "\NonExistent" + attribute and CHILDINFO (the first column indicates whether the + parent mailbox exists): + + +--------+--------------+--------------------+----------------------+ + | exists | meets the | has a child that | returned | + | | selection | meets the | LIST-EXTENDED | + | | criteria | selection criteria | attributes and | + | | | | CHILDINFO | + +--------+--------------+--------------------+----------------------+ + | no | no | no | no LIST response | + | | | | returned | + | yes | no | no | no LIST response | + | | | | returned | + | no | yes | no | (\NonExistent | + | | | | ) | + | yes | yes | no | () | + | no | no | yes | (\NonExistent) + | + | | | | CHILDINFO | + | yes | no | yes | () + CHILDINFO | + | no | yes | yes | (\NonExistent | + | | | | ) + CHILDINFO | + | yes | yes | yes | () + CHILDINFO | + +--------+--------------+--------------------+----------------------+ + + where is one or more attributes that correspond to the + selection criteria; for example, for the SUBSCRIBED option the + is \Subscribed. + +4. The CHILDREN Return Option + + The CHILDREN return option implements the Child Mailbox Extension, + originally proposed by Mike Gahrns and Raymond Cheng, of Microsoft + Corporation. Most of the information in this section is taken + directly from their original specification [CMbox]. The CHILDREN + return option is simply an indication that the client wants this + information; a server MAY provide it even if the option is not + specified. + + Many IMAP4 [IMAP4] clients present to the user a hierarchical view of + the mailboxes that a user has access to. Rather than initially + presenting to the user the entire mailbox hierarchy, it is often + preferable to show to the user a collapsed outline list of the + mailbox hierarchy (particularly if there is a large number of + mailboxes). The user can then expand the collapsed outline hierarchy + as needed. It is common to include within the collapsed hierarchy a + visual clue (such as a ''+'') to indicate that there are child + mailboxes under a particular mailbox. When the visual clue is + + + +Leiba & Melnikov Standards Track [Page 11] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + clicked, the hierarchy list is expanded to show the child mailboxes. + The CHILDREN return option provides a mechanism for a client to + efficiently determine whether a particular mailbox has children, + without issuing a LIST "" * or a LIST "" % for each mailbox name. + The CHILDREN return option defines two new attributes that MUST be + returned within a LIST response: \HasChildren and \HasNoChildren. + Although these attributes MAY be returned in response to any LIST + command, the CHILDREN return option is provided to indicate that the + client particularly wants this information. If the CHILDREN return + option is present, the server MUST return these attributes even if + their computation is expensive. + + \HasChildren + + The presence of this attribute indicates that the mailbox has child + mailboxes. A server SHOULD NOT set this attribute if there are + child mailboxes and the user does not have permission to access + any of them. In this case, \HasNoChildren SHOULD be used. In + many cases, however, a server may not be able to efficiently + compute whether a user has access to any child mailbox. Note + that even though the \HasChildren attribute for a mailbox must + be correct at the time of processing of the mailbox, a client + must be prepared to deal with a situation when a mailbox is + marked with the \HasChildren attribute, but no child mailbox + appears in the response to the LIST command. This might happen, + for example, due to children mailboxes being deleted or made + inaccessible to the user (using access control) by another + client before the server is able to list them. + + \HasNoChildren + + The presence of this attribute indicates that the mailbox has NO + child mailboxes that are accessible to the currently + authenticated user. + + It is an error for the server to return both a \HasChildren and a + \HasNoChildren attribute in the same LIST response. + + Note: the \HasNoChildren attribute should not be confused with the + IMAP4 [IMAP4] defined attribute \NoInferiors, which indicates that no + child mailboxes exist now and none can be created in the future. + + + + + + + + + + +Leiba & Melnikov Standards Track [Page 12] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + +5. Examples + + 1: The first example shows the complete local hierarchy that will + be used for the other examples. + + C: A01 LIST "" "*" + S: * LIST (\Marked \NoInferiors) "/" "inbox" + S: * LIST () "/" "Fruit" + S: * LIST () "/" "Fruit/Apple" + S: * LIST () "/" "Fruit/Banana" + S: * LIST () "/" "Tofu" + S: * LIST () "/" "Vegetable" + S: * LIST () "/" "Vegetable/Broccoli" + S: * LIST () "/" "Vegetable/Corn" + S: A01 OK done + + 2: In the next example, we will see the subscribed mailboxes. This + is similar to, but not equivalent with, . Note + that the mailbox called "Fruit/Peach" is subscribed to, but does + not actually exist (perhaps it was deleted while still + subscribed). The "Fruit" mailbox is not subscribed to, but it + has two subscribed children. The "Vegetable" mailbox is + subscribed and has two children; one of them is subscribed as + well. + + C: A02 LIST (SUBSCRIBED) "" "*" + S: * LIST (\Marked \NoInferiors \Subscribed) "/" "inbox" + S: * LIST (\Subscribed) "/" "Fruit/Banana" + S: * LIST (\Subscribed \NonExistent) "/" "Fruit/Peach" + S: * LIST (\Subscribed) "/" "Vegetable" + S: * LIST (\Subscribed) "/" "Vegetable/Broccoli" + S: A02 OK done + + 3: The next example shows the use of the CHILDREN option. The + client, without having to list the second level of hierarchy, + now knows which of the top-level mailboxes have submailboxes + (children) and which do not. Note that it's not necessary for + the server to return the \HasNoChildren attribute for the inbox, + because the \NoInferiors attribute already implies that, and has + a stronger meaning. + + C: A03 LIST () "" "%" RETURN (CHILDREN) + S: * LIST (\Marked \NoInferiors) "/" "inbox" + S: * LIST (\HasChildren) "/" "Fruit" + S: * LIST (\HasNoChildren) "/" "Tofu" + S: * LIST (\HasChildren) "/" "Vegetable" + S: A03 OK done + + + + +Leiba & Melnikov Standards Track [Page 13] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + 4: In this example, we see more mailboxes that reside on another + server. This is similar to the command . + + C: A04 LIST (REMOTE) "" "%" RETURN (CHILDREN) + S: * LIST (\Marked \NoInferiors) "/" "inbox" + S: * LIST (\HasChildren) "/" "Fruit" + S: * LIST (\HasNoChildren) "/" "Tofu" + S: * LIST (\HasChildren) "/" "Vegetable" + S: * LIST (\Remote) "/" "Bread" + S: * LIST (\HasChildren \Remote) "/" "Meat" + S: A04 OK done + + 5: The following example also requests the server to include + mailboxes that reside on another server. The server returns + information about all mailboxes that are subscribed. This is + similar to the command . We also see the use of + two selection options. + + C: A05 LIST (REMOTE SUBSCRIBED) "" "*" + S: * LIST (\Marked \NoInferiors \Subscribed) "/" "inbox" + S: * LIST (\Subscribed) "/" "Fruit/Banana" + S: * LIST (\Subscribed \NonExistent) "/" "Fruit/Peach" + S: * LIST (\Subscribed) "/" "Vegetable" + S: * LIST (\Subscribed) "/" "Vegetable/Broccoli" + S: * LIST (\Remote \Subscribed) "/" "Bread" + S: A05 OK done + + 6: The following example requests the server to include mailboxes + that reside on another server. The server is asked to return + subscription information for all returned mailboxes. This is + different from the example above. + + Note that the output of this command is not a superset of the + output in the previous example, as it doesn't include LIST + response for the non-existent "Fruit/Peach". + + C: A06 LIST (REMOTE) "" "*" RETURN (SUBSCRIBED) + S: * LIST (\Marked \NoInferiors \Subscribed) "/" "inbox" + S: * LIST () "/" "Fruit" + S: * LIST () "/" "Fruit/Apple" + S: * LIST (\Subscribed) "/" "Fruit/Banana" + S: * LIST () "/" "Tofu" + S: * LIST (\Subscribed) "/" "Vegetable" + S: * LIST (\Subscribed) "/" "Vegetable/Broccoli" + S: * LIST () "/" "Vegetable/Corn" + S: * LIST (\Remote \Subscribed) "/" "Bread" + S: * LIST (\Remote) "/" "Meat" + S: A06 OK done + + + +Leiba & Melnikov Standards Track [Page 14] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + 7: In the following example, the client has specified multiple + mailbox patterns. Note that this example does not use the + mailbox hierarchy used in the previous examples. + + C: BBB LIST "" ("INBOX" "Drafts" "Sent/%") + S: * LIST () "/" "INBOX" + S: * LIST (\NoInferiors) "/" "Drafts" + S: * LIST () "/" "Sent/March2004" + S: * LIST (\Marked) "/" "Sent/December2003" + S: * LIST () "/" "Sent/August2004" + S: BBB OK done + + 8: The following example demonstrates the difference between the + \HasChildren attribute and the CHILDINFO extended data item. + + Let's assume there is the following hierarchy: + + C: C01 LIST "" "*" + S: * LIST (\Marked \NoInferiors) "/" "inbox" + S: * LIST () "/" "Foo" + S: * LIST () "/" "Foo/Bar" + S: * LIST () "/" "Foo/Baz" + S: * LIST () "/" "Moo" + S: C01 OK done + + If the client asks RETURN (CHILDREN), it will get this: + + C: CA3 LIST "" "%" RETURN (CHILDREN) + S: * LIST (\Marked \NoInferiors) "/" "inbox" + S: * LIST (\HasChildren) "/" "Foo" + S: * LIST (\HasNoChildren) "/" "Moo" + S: CA3 OK done + + A) Let's also assume that the mailbox "Foo/Baz" is the only + subscribed mailbox. Then we get this result: + + C: C02 LIST (SUBSCRIBED) "" "*" + S: * LIST (\Subscribed) "/" "Foo/Baz" + S: C02 OK done + + Now, if the client issues , the server will + return no mailboxes (as the mailboxes "Moo", "Foo", and "Inbox" are + NOT subscribed). However, if the client issues this: + + C: C04 LIST (SUBSCRIBED RECURSIVEMATCH) "" "%" + S: * LIST () "/" "Foo" ("CHILDINFO" ("SUBSCRIBED")) + S: C04 OK done + + + + +Leiba & Melnikov Standards Track [Page 15] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + (i.e., the mailbox "Foo" is not subscribed, but it has a child that + is.) + + A1) If the mailbox "Foo" had also been subscribed, the last command + would return this: + + C: C04 LIST (SUBSCRIBED RECURSIVEMATCH) "" "%" + S: * LIST (\Subscribed) "/" "Foo" ("CHILDINFO" ("SUBSCRIBED")) + S: C04 OK done + + or even this: + + C: C04 LIST (SUBSCRIBED RECURSIVEMATCH) "" "%" + S: * LIST (\Subscribed \HasChildren) "/" "Foo" ("CHILDINFO" + ("SUBSCRIBED")) + S: C04 OK done + + A2) If we assume instead that the mailbox "Foo" is not part of the + original hierarchy and is not subscribed, the last command will give + this result: + + C: C04 LIST (SUBSCRIBED RECURSIVEMATCH) "" "%" + S: * LIST (\NonExistent) "/" "Foo" ("CHILDINFO" ("SUBSCRIBED")) + S: C04 OK done + + B) Now, let's assume that no mailbox is subscribed. In this case, + the command will return no + responses, as there are no subscribed children (even though "Foo" has + children). + + C) And finally, suppose that only the mailboxes "Foo" and "Moo" are + subscribed. In that case, we see this result: + + C: C04 LIST (SUBSCRIBED RECURSIVEMATCH) "" "%" RETURN (CHILDREN) + S: * LIST (\HasChildren \Subscribed) "/" "Foo" + S: * LIST (\HasNoChildren \Subscribed) "/" "Moo" + S: C04 OK done + + (which means that the mailbox "Foo" has children, but none of them is + subscribed). + + 9: The following example demonstrates that the CHILDINFO extended + data item is returned whether or not children mailboxes match + the canonical LIST pattern. + + + + + + + +Leiba & Melnikov Standards Track [Page 16] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + Let's assume there is the following hierarchy: + + C: D01 LIST "" "*" + S: * LIST (\Marked \NoInferiors) "/" "inbox" + S: * LIST () "/" "foo2" + S: * LIST () "/" "foo2/bar1" + S: * LIST () "/" "foo2/bar2" + S: * LIST () "/" "baz2" + S: * LIST () "/" "baz2/bar2" + S: * LIST () "/" "baz2/bar22" + S: * LIST () "/" "baz2/bar222" + S: * LIST () "/" "eps2" + S: * LIST () "/" "eps2/mamba" + S: * LIST () "/" "qux2/bar2" + S: D01 OK done + + And that the following mailboxes are subscribed: + + C: D02 LIST (SUBSCRIBED) "" "*" + S: * LIST (\Subscribed) "/" "foo2/bar1" + S: * LIST (\Subscribed) "/" "foo2/bar2" + S: * LIST (\Subscribed) "/" "baz2/bar2" + S: * LIST (\Subscribed) "/" "baz2/bar22" + S: * LIST (\Subscribed) "/" "baz2/bar222" + S: * LIST (\Subscribed) "/" "eps2" + S: * LIST (\Subscribed) "/" "eps2/mamba" + S: * LIST (\Subscribed) "/" "qux2/bar2" + S: D02 OK done + + The client issues the following command first: + + C: D03 LIST (RECURSIVEMATCH SUBSCRIBED) "" "*2" + S: * LIST () "/" "foo2" ("CHILDINFO" ("SUBSCRIBED")) + S: * LIST (\Subscribed) "/" "foo2/bar2" + S: * LIST (\Subscribed) "/" "baz2/bar2" + S: * LIST (\Subscribed) "/" "baz2/bar22" + S: * LIST (\Subscribed) "/" "baz2/bar222" + S: * LIST (\Subscribed) "/" "eps2" ("CHILDINFO" ("SUBSCRIBED")) + S: * LIST (\Subscribed) "/" "qux2/bar2" + S: D03 OK done + + and the server may also include (but this would violate a SHOULD NOT + in Section 3.5, because CHILDINFO is redundant) + + S: * LIST () "/" "baz2" ("CHILDINFO" ("SUBSCRIBED")) + S: * LIST (\NonExistent) "/" "qux2" ("CHILDINFO" ("SUBSCRIBED")) + + + + + +Leiba & Melnikov Standards Track [Page 17] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + The CHILDINFO extended data item is returned for mailboxes "foo2", + "baz2", and "eps2", because all of them have subscribed children, + even though for the mailbox "foo2" only one of the two subscribed + children matches the pattern, for the mailbox "baz2" all the + subscribed children match the pattern, and for the mailbox "eps2" + none of the subscribed children matches the pattern. + + Note that if the client issues + + C: D03 LIST (RECURSIVEMATCH SUBSCRIBED) "" "*" + S: * LIST () "/" "foo2" ("CHILDINFO" ("SUBSCRIBED")) + S: * LIST (\Subscribed) "/" "foo2/bar1" + S: * LIST (\Subscribed) "/" "foo2/bar2" + S: * LIST () "/" "baz2" ("CHILDINFO" ("SUBSCRIBED")) + S: * LIST (\Subscribed) "/" "baz2/bar2" + S: * LIST (\Subscribed) "/" "baz2/bar22" + S: * LIST (\Subscribed) "/" "baz2/bar222" + S: * LIST (\Subscribed) "/" "eps2" ("CHILDINFO" ("SUBSCRIBED")) + S: * LIST (\Subscribed) "/" "eps2/mamba" + S: * LIST (\Subscribed) "/" "qux2/bar2" + S: D03 OK done + + The LIST responses for mailboxes "foo2", "baz2", and "eps2" still + have the CHILDINFO extended data item, even though this information + is redundant and the client can determine it by itself. + + 10: The following example shows usage of multiple mailbox patterns. + It also demonstrates that the presence of the CHILDINFO extended + data item doesn't necessarily imply \HasChildren. + + C: a1 LIST "" ("foo" "foo/*") + S: * LIST () "/" foo + S: a1 OK done + + C: a2 LIST (SUBSCRIBED) "" "foo/*" + S: * LIST (\Subscribed \NonExistent) "/" foo/bar + S: a2 OK done + + C: a3 LIST (SUBSCRIBED RECURSIVEMATCH) "" foo RETURN (CHILDREN) + S: * LIST (\HasNoChildren) "/" foo ("CHILDINFO" ("SUBSCRIBED")) + S: a3 OK done + + 11: The following example shows how a server that supports missing + mailbox hierarchy elements can signal to a client that didn't + specify the RECURSIVEMATCH selection option that there is a + child mailbox that matches the selection criteria. + + + + + +Leiba & Melnikov Standards Track [Page 18] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + C: a1 LIST (REMOTE) "" * + S: * LIST () "/" music/rock + S: * LIST (\Remote) "/" also/jazz + S: a1 OK done + + C: a2 LIST () "" % + S: * LIST (\NonExistent \HasChildren) "/" music + S: a2 OK done + + C: a3 LIST (REMOTE) "" % + S: * LIST (\NonExistent \HasChildren) "/" music + S: * LIST (\NonExistent \HasChildren) "/" also + S: a3 OK done + + C: a3.1 LIST "" (% music/rock) + S: * LIST () "/" music/rock + S: a3.1 OK done + + Because "music/rock" is the only mailbox under "music", there's no + need for the server to also return "music". However clients must + handle both cases. + +6. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) as described in [ABNF]. Terms not defined here are taken + from [IMAP4]. In particular, note that the version of "mailbox-list" + below, which defines the payload of the LIST response, updates the + version defined in the IMAP specification. It is pointed to by + "mailbox-data", which is defined in [IMAP4]. + + "vendor-token" is defined in [ACAP]. Note that this normative + reference to ACAP will be an issue in moving this spec forward, since + it introduces a dependency on ACAP. The definitions of + "vendor-token" and of the IANA registry must eventually go somewhere + else, in a document that can be moved forward on the standards track + independently of ACAP. + + + + + + + + + + + + + + +Leiba & Melnikov Standards Track [Page 19] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + childinfo-extended-item = "CHILDINFO" SP "(" + list-select-base-opt-quoted + *(SP list-select-base-opt-quoted) ")" + ; Extended data item (mbox-list-extended-item) + ; returned when the RECURSIVEMATCH + ; selection option is specified. + ; Note 1: the CHILDINFO tag can be returned + ; with and without surrounding quotes, as per + ; mbox-list-extended-item-tag production. + ; Note 2: The selection options are always returned + ; quoted, unlike their specification in + ; the extended LIST command. + + child-mbox-flag = "\HasChildren" / "\HasNoChildren" + ; attributes for CHILDREN return option, at most one + ; possible per LIST response + + eitem-standard-tag = atom + ; a tag for extended list data defined in a Standard + ; Track or Experimental RFC. + + eitem-vendor-tag = vendor-token "-" atom + ; a vendor-specific tag for extended list data + + list = "LIST" [SP list-select-opts] SP mailbox SP mbox-or-pat + [SP list-return-opts] + + list-return-opts = "RETURN" SP + "(" [return-option *(SP return-option)] ")" + ; list return options, e.g., CHILDREN + + list-select-base-opt = "SUBSCRIBED" / option-extension + ; options that can be used by themselves + + list-select-base-opt-quoted = DQUOTE list-select-base-opt DQUOTE + + list-select-independent-opt = "REMOTE" / option-extension + ; options that do not syntactically interact with + ; other options + + list-select-mod-opt = "RECURSIVEMATCH" / option-extension + ; options that require a list-select-base-opt + ; to also be present + + list-select-opt = list-select-base-opt / list-select-independent-opt + / list-select-mod-opt + ; An option registration template is described in + ; Section 9.3 of this document. + + + +Leiba & Melnikov Standards Track [Page 20] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + list-select-opts = "(" [ + (*(list-select-opt SP) list-select-base-opt + *(SP list-select-opt)) + / (list-select-independent-opt + *(SP list-select-independent-opt)) + ] ")" + ; Any number of options may be in any order. + ; If a list-select-mod-opt appears, then a + ; list-select-base-opt must also appear. + ; This allows these: + ; () + ; (REMOTE) + ; (SUBSCRIBED) + ; (SUBSCRIBED REMOTE) + ; (SUBSCRIBED RECURSIVEMATCH) + ; (SUBSCRIBED REMOTE RECURSIVEMATCH) + ; But does NOT allow these: + ; (RECURSIVEMATCH) + ; (REMOTE RECURSIVEMATCH) + + mailbox-list = "(" [mbx-list-flags] ")" SP + (DQUOTE QUOTED-CHAR DQUOTE / nil) SP mailbox + [SP mbox-list-extended] + ; This is the list information pointed to by the ABNF + ; item "mailbox-data", which is defined in [IMAP4] + + mbox-list-extended = "(" [mbox-list-extended-item + *(SP mbox-list-extended-item)] ")" + + mbox-list-extended-item = mbox-list-extended-item-tag SP + tagged-ext-val + + mbox-list-extended-item-tag = astring + ; The content MUST conform to either "eitem-vendor-tag" + ; or "eitem-standard-tag" ABNF productions. + ; A tag registration template is described in this + ; document in Section 9.5. + + mbx-list-oflag =/ child-mbox-flag / "\Subscribed" / "\Remote" + + mbx-list-sflag =/ "\NonExistent" + + mbox-or-pat = list-mailbox / patterns + + option-extension = (option-standard-tag / option-vendor-tag) + [SP option-value] + + + + + +Leiba & Melnikov Standards Track [Page 21] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + option-standard-tag = atom + ; an option defined in a Standards Track or + ; Experimental RFC + + option-val-comp = astring / + option-val-comp *(SP option-val-comp) / + "(" option-val-comp ")" + + option-value = "(" option-val-comp ")" + + option-vendor-tag = vendor-token "-" atom + ; a vendor-specific option, non-standard + + patterns = "(" list-mailbox *(SP list-mailbox) ")" + + return-option = "SUBSCRIBED" / "CHILDREN" / option-extension + + tagged-ext-comp = astring / + tagged-ext-comp *(SP tagged-ext-comp) / + "(" tagged-ext-comp ")" + ; Extensions that follow this general + ; syntax should use nstring instead of + ; astring when appropriate in the context + ; of the extension. + ; Note that a message set or a "number" + ; can always be represented as an "atom". + ; A URL should be represented as + ; a "quoted" string. + + tagged-ext-simple = sequence-set / number + + tagged-ext-val = tagged-ext-simple / + "(" [tagged-ext-comp] ")" + +7. Internationalization Considerations + + The LIST command selection option types defined in this specification + involve simple tests of mailbox properties. However, future + extensions to LIST-EXTENDED may define selection options that do more + sophisticated tests. In the case of a test that requires matching + text, in the presence of the COMPARATOR [I18N] extension, the active + comparator must be used to do comparisons. Such LIST-EXTENDED + extensions MUST indicate in their specification the interaction with + the COMPARATOR [I18N] extension. + + + + + + + +Leiba & Melnikov Standards Track [Page 22] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + +8. Security Considerations + + This document describes syntactic changes to the specification of the + IMAP4 commands LIST, LSUB, RLIST, and RLSUB, and the modified LIST + command has the same security considerations as those commands. They + are described in [IMAP4] and [MBRef]. + + The Child Mailbox Extension provides a client a more efficient means + of determining whether a particular mailbox has children. If a + mailbox has children, but the currently authenticated user does not + have access to any of them, the server SHOULD respond with a + \HasNoChildren attribute. In many cases, however, a server may not + be able to efficiently compute whether a user has access to any child + mailbox. If such a server responds with a \HasChildren attribute, + when in fact the currently authenticated user does not have access to + any child mailboxes, potentially more information is conveyed about + the mailbox than intended. In most situations, this will not be a + security concern, because if information regarding whether a mailbox + has children is considered sensitive, a user would not be granted + access to that mailbox in the first place. + + The CHILDINFO extended data item has the same security considerations + as the \HasChildren attribute described above. + +9. IANA Considerations + +9.1. Guidelines for IANA + + IANA has created two new registries for LIST-EXTENDED options and + LIST-EXTENDED response data. The templates and the initial + registrations are detailed below. + +9.2. Registration Procedure and Change Control + + Registration of a LIST-EXTENDED option is done by filling in the + template in Section 9.3 and sending it via electronic mail to + iana@iana.org. Registration of a LIST-EXTENDED extended data item is + done by filling in the template in Section 9.5 and sending it via + electronic mail to iana@iana.org. IANA has the right to reject + obviously bogus registrations, but will perform no review of claims + made in the registration form. + + A LIST-EXTENDED option/extended data item name that starts with "V-" + is reserved for vendor-specific options/extended data items. All + options, whether they are vendor specific or global, should be + registered with IANA. If a LIST-EXTENDED extended data item is + returned as a result of requesting a particular LIST-EXTENDED option, + + + + +Leiba & Melnikov Standards Track [Page 23] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + the name of the option SHOULD be used as the name of the + LIST-EXTENDED extended data item. + + Each vendor-specific option/extended data item MUST start with its + vendor-token ("vendor prefix"). The vendor-token MUST be registered + with IANA, using the [ACAP] vendor subtree registry. + + Standard LIST-EXTENDED option/extended data item names are case + insensitive. If the vendor prefix is omitted from a vendor-specific + LIST-EXTENDED option/extended data item name, the rest is case + insensitive. The vendor prefix itself is not case sensitive, as it + might contain non-ASCII characters. While the registration + procedures do not require it, authors of + LIST-EXTENDED options/extended data items are encouraged to seek + community review and comment whenever that is feasible. Authors may + seek community review by posting a specification of their proposed + mechanism as an + Internet-Draft. LIST-EXTENDED option/extended data items intended + for widespread use should be standardized through the normal IETF + process, when appropriate. + + Comments on registered LIST-EXTENDED options/extended response data + should first be sent to the "owner" of the mechanism and/or to the + IMAPEXT WG mailing list. Submitters of comments may, after a + reasonable attempt to contact the owner, request IANA to attach their + comment to the registration itself. If IANA approves of this, the + comment will be made accessible in conjunction with the registration + LIST-EXTENDED options/extended response data itself. + + Once a LIST-EXTENDED registration has been published by IANA, the + author may request a change to its definition. The change request + follows the same procedure as the registration request. + + The owner of a LIST-EXTENDED registration may pass responsibility for + the registered option/extended data item to another person or agency + by informing IANA; this can be done without discussion or review. + + The IESG may reassign responsibility for a LIST-EXTENDED + option/extended data item. The most common case of this will be to + enable changes to be made to mechanisms where the author of the + registration has died, has moved out of contact, or is otherwise + unable to make changes that are important to the community. + + LIST-EXTENDED registrations may not be deleted; mechanisms that are + no longer believed appropriate for use can be declared OBSOLETE by a + change to their "intended use" field. Such LIST-EXTENDED + options/extended data items will be clearly marked in the lists + published by IANA. + + + +Leiba & Melnikov Standards Track [Page 24] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + The IESG is considered to be the owner of all LIST-EXTENDED + options/extended data items that are on the IETF standards track. + +9.3. Registration Template for LIST-EXTENDED Options + + To: iana@iana.org + Subject: Registration of LIST-EXTENDED option X + + LIST-EXTENDED option name: + + LIST-EXTENDED option type: (One of SELECTION or RETURN) + + Implied return options(s), if the option type is SELECTION: (zero or + more) + + LIST-EXTENDED option description: + + Published specification (optional, recommended): + + Security considerations: + + Intended usage: + (One of COMMON, LIMITED USE, or OBSOLETE) + + Person and email address to contact for further information: + + Owner/Change controller: + + (Any other information that the author deems interesting may be added + below this line.) + +9.4. Initial LIST-EXTENDED Option Registrations + + The LIST-EXTENDED option registry has been populated with the + following entries: + + 1. To: iana@iana.org + Subject: Registration of LIST-EXTENDED option SUBSCRIBED + + LIST-EXTENDED option name: SUBSCRIBED + + LIST-EXTENDED option type: SELECTION + + Implied return options(s): SUBSCRIBED + + LIST-EXTENDED option description: Causes the LIST command to list + subscribed mailboxes, rather than the actual mailboxes. + + + + +Leiba & Melnikov Standards Track [Page 25] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + Published specification: RFC 5258, Section 3. + + Security considerations: RFC 5258, Section 8. + + Intended usage: COMMON + + Person and email address to contact for further information: + Alexey Melnikov + + Owner/Change controller: iesg@ietf.org + + 2. To: iana@iana.org + Subject: Registration of LIST-EXTENDED option REMOTE + + LIST-EXTENDED option name: REMOTE + + LIST-EXTENDED option type: SELECTION + + Implied return options(s): (none) + + LIST-EXTENDED option description: Causes the LIST command to + return remote mailboxes as well as local ones, as described in + RFC 2193. + + Published specification: RFC 5258, Section 3. + + Security considerations: RFC 5258, Section 8. + + Intended usage: COMMON + + Person and email address to contact for further information: + Alexey Melnikov + + Owner/Change controller: iesg@ietf.org + + 3. To: iana@iana.org + Subject: Registration of LIST-EXTENDED option SUBSCRIBED + + LIST-EXTENDED option name: SUBSCRIBED + + LIST-EXTENDED option type: RETURN + + LIST-EXTENDED option description: Causes the LIST command to + return subscription state. + + Published specification: RFC 5258, Section 3. + + Security considerations: RFC 5258, Section 8. + + + +Leiba & Melnikov Standards Track [Page 26] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + Intended usage: COMMON + + Person and email address to contact for further information: + Alexey Melnikov + + Owner/Change controller: iesg@ietf.org + + 4. To: iana@iana.org + Subject: Registration of LIST-EXTENDED option RECURSIVEMATCH + + LIST-EXTENDED option name: RECURSIVEMATCH + + LIST-EXTENDED option type: SELECTION + + Implied return options(s): (none) + + LIST-EXTENDED option description: Requests that CHILDINFO + extended data item (childinfo-extended-item) is to be returned. + + Published specification: RFC 5258, Section 3. + + Security considerations: RFC 5258, Section 8. + + Intended usage: COMMON + + Person and email address to contact for further information: + Alexey Melnikov + + Owner/Change controller: iesg@ietf.org + + 5. To: iana@iana.org + Subject: Registration of LIST-EXTENDED option CHILDREN + + LIST-EXTENDED option name: CHILDREN + + LIST-EXTENDED option type: RETURN + + LIST-EXTENDED option description: Requests mailbox child + information. + + Published specification: RFC 5258, Section 3 and Section 4. + + Security considerations: RFC 5258, Section 8. + + Intended usage: COMMON + + Person and email address to contact for further information: + Alexey Melnikov + + + +Leiba & Melnikov Standards Track [Page 27] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + Owner/Change controller: iesg@ietf.org + +9.5. Registration Template for LIST-EXTENDED Extended Data Item + + To: iana@iana.org + Subject: Registration of X LIST-EXTENDED extended data item + + LIST-EXTENDED extended data item tag: + + LIST-EXTENDED extended data item description: + + Which LIST-EXTENDED option(s) (and their types) causes this extended + data item to be returned (if any): + + Published specification (optional, recommended): + + Security considerations: + + Intended usage: + (One of COMMON, LIMITED USE, or OBSOLETE) + + Person and email address to contact for further information: + + Owner/Change controller: + + (Any other information that the author deems interesting may be added + below this line.) + +9.6. Initial LIST-EXTENDED Extended Data Item Registrations + + The LIST-EXTENDED extended data item registry has been populated with + the following entries: + + 1. To: iana@iana.org + Subject: Registration of CHILDINFO LIST-EXTENDED extended data + item + + LIST-EXTENDED extended data item tag: CHILDINFO + + LIST-EXTENDED extended data item description: The CHILDINFO + extended data item describes the selection criteria that has + caused it to be returned and indicates that the mailbox has one + or more child mailboxes that match the selection criteria. + + Which LIST-EXTENDED option(s) (and their types) causes this + extended data item to be returned (if any): RECURSIVEMATCH + selection option + + + + +Leiba & Melnikov Standards Track [Page 28] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + Published specification: RFC 5258, Section 3.5. + + Security considerations: RFC 5258, Section 8. + + Intended usage: COMMON + + Person and email address to contact for further information: + Alexey Melnikov + + Owner/Change controller: iesg@ietf.org + +10. Acknowledgements + + Mike Gahrns and Raymond Cheng of Microsoft Corporation originally + devised the Child Mailbox Extension and proposed it in 1997; the + idea, as well as most of the text in Section 4, is theirs. + + This document is the result of discussions on the IMAP4 and IMAPEXT + mailing lists and is meant to reflect consensus of those groups. In + particular, Mark Crispin, Philip Guenther, Cyrus Daboo, Timo + Sirainen, Ken Murchison, Rob Siemborski, Steve Hole, Arnt + Gulbrandsen, Larry Greenfield, Dave Cridland, and Pete Maclean were + active participants in those discussions or made suggestions to this + document. + +11. References + +11.1. Normative References + + [ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + + [ACAP] Newman, C. and J. Myers, "ACAP -- Application Configuration + Access Protocol", RFC 2244, November 1997. + + [I18N] Newman, C., Gulbrandsen, A., and A. Melnikov, "Internet + Message Access Protocol Internationalization", RFC 5255, + June 2008. + + [IMAP4] Crispin, M., "Internet Message Access Protocol - Version + 4rev1", RFC 3501, March 2003. + + [Kwds] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", RFC 2119, March 1997. + + [MBRef] Gahrns, M., "IMAP4 Mailbox Referrals", RFC 2193, + September 1997. + + + + +Leiba & Melnikov Standards Track [Page 29] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + +11.2. Informative References + + [CMbox] Gahrns, M. and R. Cheng, "The Internet Message Action + Protocol (IMAP4) Child Mailbox Extension", RFC 3348, + July 2002. + +Authors' Addresses + + Barry Leiba + IBM T.J. Watson Research Center + 19 Skyline Drive + Hawthorne, NY 10532 + US + + Phone: +1 914 784 7941 + EMail: leiba@watson.ibm.com + + + Alexey Melnikov + Isode Limited + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: Alexey.Melnikov@isode.com + URI: http://www.melnikov.ca/ + + + + + + + + + + + + + + + + + + + + + + + + +Leiba & Melnikov Standards Track [Page 30] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2008). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Leiba & Melnikov Standards Track [Page 31] + diff --git a/docs/rfcs/rfc5423.IM_Store_Events.txt b/docs/rfcs/rfc5423.IM_Store_Events.txt new file mode 100644 index 0000000..0326d94 --- /dev/null +++ b/docs/rfcs/rfc5423.IM_Store_Events.txt @@ -0,0 +1,955 @@ + + + + + + +Network Working Group R. Gellens +Request for Comments: 5423 QUALCOMM Inc. +Category: Standards Track C. Newman + Sun Microsystems + March 2009 + + + Internet Message Store Events + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (c) 2009 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 in effect on the date of + publication of this document (http://trustee.ietf.org/license-info). + Please review these documents carefully, as they describe your rights + and restrictions with respect to this document. + +Abstract + + One of the missing features in the existing Internet mail and + messaging standards is a facility for server-to-server and server-to- + client event notifications related to message store events. As the + scope of Internet mail expands to support more diverse media (such as + voice mail) and devices (such as cell phones) and to provide rich + interactions with other services (such as web portals and legal + compliance systems), the need for an interoperable notification + system increases. This document attempts to enumerate the types of + events that interest real-world consumers of such a system. + + This document describes events and event parameters that are useful + for several cases, including notification to administrative systems + and end users. This is not intended as a replacement for a message + access facility such as IMAP. + + + + + + + +Gellens & Newman Standards Track [Page 1] + +RFC 5423 Internet Message Store Events March 2009 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 + 1.1. Conventions Used in This Document . . . . . . . . . . . . 3 + 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 3. Event Model . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 4. Event Types . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 4.1. Message Addition and Deletion . . . . . . . . . . . . . . 5 + 4.2. Message Flags . . . . . . . . . . . . . . . . . . . . . . 7 + 4.3. Access Accounting . . . . . . . . . . . . . . . . . . . . 8 + 4.4. Mailbox Management . . . . . . . . . . . . . . . . . . . . 8 + 5. Event Parameters . . . . . . . . . . . . . . . . . . . . . . . 10 + 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 14 + 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 15 + 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 + 9.1. Normative References . . . . . . . . . . . . . . . . . . . 15 + 9.2. Informative References . . . . . . . . . . . . . . . . . . 15 + Appendix A. Future Extensions . . . . . . . . . . . . . . . . . . 17 + +1. Introduction + + A message store is used to organize Internet Messages [RFC5322] into + one or more mailboxes (possibly hierarchical), annotate them in + various ways, and provide access to these messages and associated + metadata. Three different standards-based protocols have been widely + deployed to remotely access a message store. The Post Office + Protocol (POP) [RFC1939] provides simple download-and-delete access + to a single mail drop (which is a subset of the functionality + typically associated with a message store). The Internet Message + Access Protocol (IMAP) [RFC3501] provides an extensible feature-rich + model for online, offline, and disconnected access to a message store + with minimal constraints on any associated "fat-client" user + interface. Finally, mail access applications built on top of the + Hypertext Transfer Protocol (HTTP) [RFC2616] that run in standards- + based web browsers provide a third standards-based access mechanism + for online-only access. + + While simple and/or ad-hoc mechanisms for notifications have sufficed + to some degree in the past (e.g., "Simple New Mail Notification" + [RFC4146], "IMAP4 IDLE Command" [RFC2177]), as the scope and + importance of message stores expand, the demand for a more complete + store notification system increases. Some of the driving forces + behind this demand include: + + o Mobile devices with intermittent network connectivity that have + "new mail" or "message count" indicators. + + + + +Gellens & Newman Standards Track [Page 2] + +RFC 5423 Internet Message Store Events March 2009 + + + o Unified messaging systems that include both Internet and voice + mail require support for a message-waiting indicator on phones. + + o Interaction with systems for event-based or utility-computing + billing. + + o Simplification of the process of passing message store events to + non-Internet notification systems. + + o A calendar system may wish to subscribe to MessageNew + notifications in order to support iMIP [RFC2447]. + + o Some jurisdictions have laws or regulations for information + protection and auditing that require interoperable protocols + between message stores built by messaging experts and compliance + auditing systems built by compliance experts. + + Vendors who have deployed proprietary notification systems for their + Internet message stores have seen significant demand to provide + notifications for more and more events. As a first step towards + building a notification system, this document attempts to enumerate + the core events that real-world customers demand. + + This document includes those events that can be generated by the use + of IMAP4rev1 [RFC3501] and some existing extensions. As new IMAP + extensions are defined, or additional event types or parameters need + to be added, the set specified here can be extended by means of an + IANA registry with update requirements, as specified in Section 6. + +1.1. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [RFC2119]. + When these words appear in lower-case or with initial capital + letters, they are not RFC 2119 key words. + +2. Terminology + + The following terminology is used in this document: + + mailbox + A container for Internet messages and/or child mailboxes. A + mailbox may or may not permit delivery of new messages via a mail + delivery agent. + + + + + + +Gellens & Newman Standards Track [Page 3] + +RFC 5423 Internet Message Store Events March 2009 + + + mailbox identifier + A mailbox identifier provides sufficient information to identify a + specific mailbox on a specific server instance. An IMAP URL can + be a mailbox identifier. + + message access protocols + Protocols that provide clients (e.g., a mail user agent or web + browser) with access to the message store, including but not + limited to IMAP, POP, and HTTP. + + message context + As defined in [RFC3458]. + + UIDVALIDITY + As defined in IMAP4rev1 [RFC3501]. UIDVALIDITY is critical to the + correct operation of a caching mail client. When it changes, the + client MUST flush its cache. It's particularly important to + include UIDVALIDITY with event notifications related to message + addition or removal in order to keep the message data correctly + synchronized. + +3. Event Model + + The events that are generated by a message store depend to some + degree on the model used to represent a message store. The model the + IETF has for a message store is implicit from IMAP4rev1 and + extensions, so that model is assumed by this document. + + A message store event typically has an associated mailbox name and + usually has an associated user name (or authorization identity if + using the terminology from "Simple Authentication and Security Layer" + (SASL) [RFC4422]). Events referring to a specific message can use an + IMAP URL [RFC5092] to do so. Events referring to a set of messages + can use an IMAP URL to the mailbox plus an IMAP UID (Unique + Identifier) set. + + Each notification has a type and parameters. The type determines the + type of event, while the parameters supply information about the + context of the event that may be used to adjust subscription + preferences or may simply supply data associated with the event. The + types and parameter names in this document are restricted to US-ASCII + printable characters, so these events can be easily mapped to an + arbitrary notification system. However, this document assumes that + arbitrary parameter values (including large and multi-line values) + can be encoded with the notification system. Systems which lack that + feature could only implement a subset of these events. + + + + + +Gellens & Newman Standards Track [Page 4] + +RFC 5423 Internet Message Store Events March 2009 + + + This document does not indicate which event parameters are mandatory + or optional. That is done in documents that specify specific message + formats or bindings to a notification system. + + For scalability reasons, some degree of filtering at event generation + is necessary. At the very least, the ability to turn on and off + groups of related events and to suppress inclusion of large + parameters (such as messageContent) is needed. A sophisticated + publish/subscribe notification system may be able to propagate + cumulative subscription information to the publisher. + + Some of these events might be logically collapsed into a single event + type with a required parameter to distinguish between the cases + (e.g., QuotaExceed and QuotaWithin). However, until such time that + an event subscription model is formulated, it's not practical to make + such decisions. We thus note only the fact that some of these events + may be viewed as a single event type. + +4. Event Types + + This section discusses the different types of events useful in a + message store event notification system. The intention is to + document the events sufficient to cover an overwhelming majority of + known use cases while leaving less common event types for the future. + This section mentions parameters that are important or specific to + the events described here. Event parameters likely to be included in + most or all notifications are discussed in the next section. + +4.1. Message Addition and Deletion + + This section includes events related to message addition and + deletion. + + MessageAppend + A message was appended or concatenated to a mailbox by a message + access client. For the most part, this is identical to the + MessageNew event type except that the SMTP envelope information is + not included as a parameter, but information about which protocol + triggered the event MAY be included. See the MessageNew event for + more information. + + MessageExpire + One or more messages were expired from a mailbox due to server + expiration policy and are no longer accessible by the end user. + + The parameters include a mailbox identifier that MUST include + UIDVALIDITY and a UID set that describes the messages. + + + + +Gellens & Newman Standards Track [Page 5] + +RFC 5423 Internet Message Store Events March 2009 + + + Information about which server expiration policy was applied may + be included in the future. + + MessageExpunge + One or more messages were expunged from a mailbox by an IMAP + CLOSE/EXPUNGE, POP3 DELE+QUIT, HTTP, or equivalent client action + and are no longer accessible by the end user. + + The parameters include a mailbox identifier that MUST include + UIDVALIDITY, a UID set, and MAY also indicate which access + protocol triggered the event. + + MessageNew + A new message was received into a mailbox via a message delivery + agent. + + The parameters include a message identifier that, for IMAP- + accessible message stores, MUST include UIDVALIDITY and a UID. + The parameters MAY also include an SMTP envelope and other + arbitrary message and mailbox metadata. In some cases, the entire + new message itself may be included. The set of parameters SHOULD + be adjustable to the client's preference, with limits set by + server policy. An interesting policy, for example, would be to + include messages up to 2K in size with the notification, but to + include a URLAUTH [RFC4467] reference for larger messages. + + QuotaExceed + An operation failed (typically MessageNew) because the user's + mailbox exceeded one of the quotas (e.g., disk quota, message + quota, quota by message context, etc.). The parameters SHOULD + include at least the relevant user and quota and, optionally, the + mailbox. Quota usage SHOULD be included if possible. Parameters + needed to extend this to support quota by context are not + presently described in this document but could be added in the + future. + + QuotaWithin + An operation occurred (typically MessageExpunge or MessageExpire) + that reduced the user's quota usage under the limit. + + QuotaChange + The user's quota was changed. + + + + + + + + + +Gellens & Newman Standards Track [Page 6] + +RFC 5423 Internet Message Store Events March 2009 + + +4.2. Message Flags + + This section includes events related to changes in message flags. + + MessageRead + One or more messages in the mailbox were marked as read or seen by + a user. Note that POP has no concept of read or seen messages, so + these events are only generated by IMAP or HTTP clients (or + equivalent). + + The parameters include a mailbox identifier and a set of message + UIDs. + + MessageTrash + One or more messages were marked for future deletion by the user + but are still accessible over the protocol (the user's client may + or may not make these messages accessible through its user + interface). + + The parameters include a mailbox identifier and a set of message + UIDs. + + FlagsSet + One or more messages in the mailbox had one or more IMAP flags or + keywords set. + + The parameters include a list of IMAP flag or keyword names that + were set, a mailbox identifier, and the set of UIDs of affected + messages. The flagNames MUST NOT include \Recent. For + compatibility with simpler clients, it SHOULD be configurable + whether setting the \Seen or \Deleted flags results in this event + or the simpler MessageRead/MessageTrash events. By default, the + simpler message forms SHOULD be used for MessageRead and + MessageTrash. + + FlagsClear + One or more messages in the mailbox had one or more IMAP flags or + keywords cleared. + + The parameters include a list of IMAP flag or keyword names that + were cleared, a mailbox identifier, and the set of UIDs of + affected messages. The flagNames parameter MUST NOT include + \Recent. + + + + + + + + +Gellens & Newman Standards Track [Page 7] + +RFC 5423 Internet Message Store Events March 2009 + + +4.3. Access Accounting + + This section lists events related to message store access accounting. + + Login + A user has logged into the system via IMAP, HTTP, POP, or some + other mechanism. + + The parameters include the domain name and port used to access the + server and the user's authorization identity. Additional possible + parameters include the client's IP address and port, the + authentication identity (if different from the authorization + identity), the service name, the authentication mechanism, + information about any negotiated security layers, a timestamp, and + other information. + + Logout + A user has logged out or otherwise been disconnected from the + message store via IMAP, HTTP, POP, or some other mechanism. + + The parameters include the server domain name and the user's + authorization identity. Additional parameters MAY include any of + the information from the "Login" event as well as information + about the type of disconnect (suggested values include graceful, + abort, timeout, and security layer error), the duration of the + connection or session, and other information. + +4.4. Mailbox Management + + This section lists events related to the management of mailboxes. + + MailboxCreate + A mailbox has been created, or an access control changed on an + existing mailbox so that it is now accessible by the user. If the + mailbox creation caused the creation of new mailboxes earlier in + the hierarchy, separate MailboxCreate events are not generated, as + their creation is implied. + + The parameters include the created mailbox identifier, its + UIDVALIDITY for IMAP-accessible message stores, and MAY also + indicate which access protocol triggered the event. Access and + permissions information (such as Access Control List (ACL) + [RFC4314] settings) require a standardized format to be included, + and so are left for future extension. + + + + + + + +Gellens & Newman Standards Track [Page 8] + +RFC 5423 Internet Message Store Events March 2009 + + + MailboxDelete + A mailbox has been deleted, or an access control changed on an + existing mailbox so that it is no longer accessible by the user. + Note that if the mailbox has child mailboxes, only the specified + mailbox has been deleted, not the children. The mailbox becomes + \NOSELECT, and the hierarchy remains unchanged, as per the + description of the DELETE command in IMAP4rev1 [RFC3501]. + + The parameters include the deleted mailbox identifier and MAY also + indicate which access protocol triggered the event. + + MailboxRename + A mailbox has been renamed. Note that, per the description of the + RENAME command in IMAP4rev1 [RFC3501], special semantics regarding + the mailbox hierarchy apply when INBOX is renamed (child mailboxes + are usually included in the rename, but are excluded when INBOX is + renamed). When a mailbox other than INBOX is renamed and its + child mailboxes are also renamed as a result, separate + MailboxRename events are not generated for the child mailboxes, as + their renaming is implied. If the rename caused the creation of + new mailboxes earlier in the hierarchy, separate MailboxCreate + events are not generated for those, as their creation is implied. + When INBOX is renamed, a new INBOX is created. A MailboxCreate + event is not generated for the new INBOX, since it is implied. + + The parameters include the old mailbox identifier, the new mailbox + identifier, and MAY also indicate which access protocol triggered + the event. + + MailboxSubscribe + A mailbox has been added to the server-stored subscription list, + such as the one managed by the IMAP SUBSCRIBE and UNSUBSCRIBE + commands. + + The parameters include the user whose subscription list has been + affected, the mailbox identifier, and MAY also indicate which + access protocol triggered the event. + + MailboxUnSubscribe + A mailbox has been removed from the subscription list. + + The parameters include the user whose subscription list has been + affected, the mailbox identifier, and MAY also indicate which + access protocol triggered the event. + + + + + + + +Gellens & Newman Standards Track [Page 9] + +RFC 5423 Internet Message Store Events March 2009 + + +5. Event Parameters + + This section lists parameters included with these events. + + admin + Included with all events generated by message access protocols. + + The authentication identity associated with this event, as + distinct from the authorization identity (see "user"). This is + not included when it is the same as the value of the user + parameter. + + bodyStructure + May be included with MessageAppend and MessageNew. + + The IMAP BODYSTRUCTURE of the message. + + clientIP + Included with all events generated by message access protocols. + + The IPv4 or IPv6 address of the message store access client that + performed the action that triggered the notification. + + clientPort + Included with all events generated by message access protocols. + + The port number of the message store access client that performed + an action that triggered the notification (the port from which the + connection occurred). + + diskQuota + Included with QuotaExceed, QuotaWithin, and QuotaChange + notifications relating to a user or mailbox disk quota. May be + included with other notifications. + + Disk quota limit in kilobytes (1024 octets). + + diskUsed + Included with QuotaExceed and QuotaWithin notifications relating + to a user or mailbox disk quota. May be included with other + notifications. + + Disk space used in kilobytes (1024 octets). Only disk space that + counts against the quota is included. + + + + + + + +Gellens & Newman Standards Track [Page 10] + +RFC 5423 Internet Message Store Events March 2009 + + + envelope + May be included with the MessageNew notification. + + The message transfer envelope associated with final delivery of + the message for the MessageNew notification. This includes the + MAIL FROM and relevant RCPT TO line(s) used for final delivery + with CRLF delimiters and any ESMTP parameters. + + flagNames + Included with FlagsSet and FlagsClear events. May be included + with MessageAppend and MessageNew to indicate flags that were set + initially by the APPEND command or delivery agent, respectively. + + A list (likely to be space-separated) of IMAP flag or keyword + names that were set or cleared. Flag names begin with a backslash + while keyword names do not. The \Recent flag is explicitly not + permitted in the list. + + mailboxID + Included in events that affect mailboxes. A URI describing the + mailbox. In the case of MailboxRename, this refers to the new + name. + + maxMessages + Included with QuotaExceed and QuotaWithin notifications relating + to a user or mailbox message count quota. May be included with + other notifications. + + Quota limit on the number of messages in the mailbox, for events + referring to a mailbox. + + messageContent + May be included with MessageAppend and MessageNew. + + The entire message itself. Size-based suppression of this SHOULD + be available. + + messageSize + May be included with MessageAppend and MessageNew. + + Size of the RFC 5322 message itself in octets. This value matches + the length of the IMAP literal returned in response to an IMAP + FETCH of BODY[] for the referenced message. + + + + + + + + +Gellens & Newman Standards Track [Page 11] + +RFC 5423 Internet Message Store Events March 2009 + + + messages + Included with QuotaExceed and QuotaWithin notifications relating + to a user or mailbox message count quota. May be included with + other notifications. + + Number of messages in the mailbox. This is typically included + with message addition and deletion events. + + modseq + May be included with any notification referring to one message. + + This is the 64-bit integer MODSEQ as defined in [RFC4551]. No + assumptions about MODSEQ can be made if this is omitted. + + oldMailboxID + A URI describing the old name of a renamed or moved mailbox. + + pid + May be included with any notification. + + The process ID of the process that generated the notification. + + process + May be included with any notification. + + The name of the process that generated the notification. + + serverDomain + Included in Login and optionally in Logout or other events. The + domain name or IP address (v4 or v6) used to access the server or + mailbox. + + serverPort + Included in Login and optionally in Logout or other events. The + port number used to access the server. This is often a well-known + port. + + serverFQDN + May be included with any notification. + + The fully qualified domain name of the server that generated the + event. Note that this may be different from the server name used + to access the mailbox included in the mailbox identifier. + + + + + + + + +Gellens & Newman Standards Track [Page 12] + +RFC 5423 Internet Message Store Events March 2009 + + + service + May be included with any notification. + + The name of the service that triggered the event. Suggested + values include "imap", "pop", "http", and "admincli" (for an + administrative client). + + tags + May be included with any notification. + + A list of UTF-8 tags (likely to be comma-separated). One or more + tags can be set at the time a notification criteria or + notification subscription is created. Subscribers can use tags + for additional client-side filtering or dispatch of events. + + timestamp + May be included with any notification. + + The time at which the event occurred that triggered the + notification (the underlying protocol carrying the notification + may contain a timestamp for when the notification was generated). + This MAY be an approximate time. + + Timestamps are expressed in local time and contain the offset from + UTC (this information is used in several places in Internet mail) + and are normally in [RFC3339] format. + + uidnext + May be included with any notification referring to a mailbox. + + The UID that is projected to be assigned next in the mailbox. + This is typically included with message addition and deletion + events. This is equivalent to the UIDNEXT status item in the IMAP + STATUS command. + + uidset + Included with MessageExpires, MessageExpunges, MessageRead, + MessageTrash, FlagsSet, and FlagsClear. + + This includes the set of IMAP UIDs referenced. + + uri + Included with all notifications. A reference to the IMAP server, + a mailbox, or a message. + + Typically an IMAP URL. This can include the name of the server + used to access the mailbox/message, the mailbox name, the + UIDVALIDITY of the mailbox, and the UID of a specific message. + + + +Gellens & Newman Standards Track [Page 13] + +RFC 5423 Internet Message Store Events March 2009 + + + user + Included with all events generated by message access protocols. + + This is the authorization identifier used when the client + connected to the access protocol that triggered the event. Some + protocols (for example, many SASL mechanisms) distinguish between + authorization and authentication identifiers. For events + associated with a mailbox, this may be different from the owner of + the mailbox specified in the IMAP URL. + +6. IANA Considerations + + The IANA has created a new registry for "Internet Message Store + Events" that contains two sub-registries: event names and event + parameters. For both event names and event parameters, entries that + do not start with "vnd." are added by the IETF and are intended for + interoperable use. Entries that start with "vnd." are intended for + private use by one or more parties and are allocated to avoid + collisions. + + The initial values are contained in this document. + + Using IANA Considerations [RFC5226] terminology, entries that do not + start with "vnd." are allocated by IETF Consensus, while those + starting with "vnd." are allocated First Come First Served. + +7. Security Considerations + + Notifications can produce a large amount of traffic and expose + sensitive information. When notification mechanisms are used to + maintain state between different entities, the ability to corrupt or + manipulate notification messages could enable an attacker to modulate + the state of these entities. For example, if an attacker were able + to modify notifications sent from a message store to an auditing + server, he could modify the "user" and "messageContent" parameters in + MessageNew notifications to create false audit log entries. + + A competent transfer protocol for notifications must consider + authentication, authorization, privacy, and message integrity, as + well as denial-of-service issues. While the IETF has adequate tools + and experience to address these issues for mechanisms that involve + only one TCP connection, notification or publish/subscribe protocols + that are more sophisticated than a single end-to-end TCP connection + will need to pay extra attention to these issues and carefully + balance requirements to successfully deploy a system with security + and privacy considerations. + + + + + +Gellens & Newman Standards Track [Page 14] + +RFC 5423 Internet Message Store Events March 2009 + + +8. Acknowledgments + + Alexey Melnikov, Arnt Gulbrandsen, and Zoltan Ordogh have reviewed + and offered improvements to this document. Richard Barnes did a nice + review during Last Call. + +9. References + +9.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [RFC5092] Melnikov, A. and C. Newman, "IMAP URL Scheme", RFC 5092, + November 2007. + + [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an + IANA Considerations Section in RFCs", BCP 26, RFC 5226, + May 2008. + +9.2. Informative References + + [RFC1939] Myers, J. and M. Rose, "Post Office Protocol - Version 3", + STD 53, RFC 1939, May 1996. + + [RFC2177] Leiba, B., "IMAP4 IDLE command", RFC 2177, June 1997. + + [RFC2447] Dawson, F., Mansour, S., and S. Silverberg, "iCalendar + Message-Based Interoperability Protocol (iMIP)", RFC 2447, + November 1998. + + [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., + Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext + Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. + + [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the + Internet: Timestamps", RFC 3339, July 2002. + + [RFC3458] Burger, E., Candell, E., Eliot, C., and G. Klyne, "Message + Context for Internet Mail", RFC 3458, January 2003. + + [RFC4146] Gellens, R., "Simple New Mail Notification", RFC 4146, + August 2005. + + + + + +Gellens & Newman Standards Track [Page 15] + +RFC 5423 Internet Message Store Events March 2009 + + + [RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) Extension", + RFC 4314, December 2005. + + [RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication and + Security Layer (SASL)", RFC 4422, June 2006. + + [RFC4467] Crispin, M., "Internet Message Access Protocol (IMAP) - + URLAUTH Extension", RFC 4467, May 2006. + + [RFC4551] Melnikov, A. and S. Hole, "IMAP Extension for Conditional + STORE Operation or Quick Flag Changes Resynchronization", + RFC 4551, June 2006. + + [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, + October 2008. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Gellens & Newman Standards Track [Page 16] + +RFC 5423 Internet Message Store Events March 2009 + + +Appendix A. Future Extensions + + This document specifies core functionality based on events that are + believed to be well understood, have known use cases, and are + implemented by at least one deployed real-world Internet message + store. (A few events are exceptions to the last test only: FlagsSet, + FlagsClear, MailboxCreate, MailboxDelete, MailboxRename, + MailboxSubscribe, and MailboxUnSubscribe.) + + Some events have been suggested but are postponed to future + extensions because they do not meet this criteria. These events + include messages that have been moved to archive storage and may + require extra time to access, quota by message context, + authentication failure, user mail account disabled, annotations, and + mailbox ACL or metadata change. The descriptions of several events + note additional parameters that are likely candidates for future + inclusion. See Section 6 for how the list of events and parameters + can be extended. + + In order to narrow the scope of this document to something that can + be completed, only events generated from the message store (by a + message access module, administrative module, or message delivery + agent) are considered. A complete mail system is normally linked + with an identity system that would also publish events of interest to + a message store event subscriber. Events of interest include account + created/deleted/disabled and password changed/expired. + +Authors' Addresses + + Randall Gellens + QUALCOMM Incorporated + 5775 Morehouse Drive + San Diego, CA 92651 + USA + + Phone: + EMail: rg+ietf@qualcomm.com + + + Chris Newman + Sun Microsystems + 800 Royal Oaks + Monrovia, CA 91016-6347 + USA + + Phone: + EMail: chris.newman@sun.com + + + + +Gellens & Newman Standards Track [Page 17] + diff --git a/docs/rfcs/rfc5464.IMAP_METADATA_extension.txt b/docs/rfcs/rfc5464.IMAP_METADATA_extension.txt new file mode 100644 index 0000000..645bfd9 --- /dev/null +++ b/docs/rfcs/rfc5464.IMAP_METADATA_extension.txt @@ -0,0 +1,1177 @@ + + + +Network Working Group C. Daboo +Request for Comments: 5464 Apple, Inc. +Category: Standards Track February 2009 + + + The IMAP METADATA Extension + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + The METADATA extension to the Internet Message Access Protocol + permits clients and servers to maintain "annotations" or "metadata" + on IMAP servers. It is possible to have annotations on a per-mailbox + basis or on the server as a whole. For example, this would allow + comments about the purpose of a particular mailbox to be "attached" + to that mailbox, or a "message of the day" containing server status + information to be made available to anyone logging in to the server. + + + + + + + + + + + + + + + + + + + + + + + + + + + +Daboo Standards Track [Page 1] + +RFC 5464 The IMAP METADATA Extension February 2009 + + +Table of Contents + + 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 + 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 + 3. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3.2. Namespace of Entries . . . . . . . . . . . . . . . . . . . 4 + 3.2.1. Entry Names . . . . . . . . . . . . . . . . . . . . . 5 + 3.3. Private versus Shared and Access Control . . . . . . . . . 6 + 4. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . 7 + 4.1. General Considerations . . . . . . . . . . . . . . . . . . 7 + 4.2. GETMETADATA Command . . . . . . . . . . . . . . . . . . . 8 + 4.2.1. MAXSIZE GETMETADATA Command Option . . . . . . . . . . 9 + 4.2.2. DEPTH GETMETADATA Command Option . . . . . . . . . . . 10 + 4.3. SETMETADATA Command . . . . . . . . . . . . . . . . . . . 10 + 4.4. METADATA Response . . . . . . . . . . . . . . . . . . . . 12 + 4.4.1. METADATA Response with Values . . . . . . . . . . . . 13 + 4.4.2. Unsolicited METADATA Response without Values . . . . . 13 + 5. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 14 + 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 + 6.1. Entry and Attribute Registration Template . . . . . . . . 16 + 6.2. Server Entry Registrations . . . . . . . . . . . . . . . . 16 + 6.2.1. /shared/comment . . . . . . . . . . . . . . . . . . . 17 + 6.2.2. /shared/admin . . . . . . . . . . . . . . . . . . . . 17 + 6.3. Mailbox Entry Registrations . . . . . . . . . . . . . . . 17 + 6.3.1. /shared/comment . . . . . . . . . . . . . . . . . . . 18 + 6.3.2. /private/comment . . . . . . . . . . . . . . . . . . . 18 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 18 + 8. Normative References . . . . . . . . . . . . . . . . . . . . . 19 + Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 19 + + + + + + + + + + + + + + + + + + + + + +Daboo Standards Track [Page 2] + +RFC 5464 The IMAP METADATA Extension February 2009 + + +1. Introduction and Overview + + The goal of the METADATA extension is to provide a means for clients + to set and retrieve "annotations" or "metadata" on an IMAP server. + The annotations can be associated with specific mailboxes or the + server as a whole. The server can choose to support only server + annotations or both server and mailbox annotations. + + A server that supports both server and mailbox annotations indicates + the presence of this extension by returning "METADATA" as one of the + supported capabilities in the CAPABILITY command response. + + A server that supports only server annotations indicates the presence + of this extension by returning "METADATA-SERVER" as one of the + supported capabilities in the CAPABILITY command response. + + A server that supports unsolicited annotation change responses MUST + support the "ENABLE" [RFC5161] extension to allow clients to turn + that feature on. + + The METADATA extension adds two new commands and one new untagged + response to the IMAP base protocol. + + This extension makes the following changes to the IMAP protocol: + + o adds a new SETMETADATA command + + o adds a new GETMETADATA command + + o adds a new METADATA untagged response + + o adds a new METADATA response code + + The rest of this document describes the data model and protocol + changes more rigorously. + +2. Conventions Used in This Document + + In examples, "C:" and "S:" indicate lines sent by the client and + server, respectively. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + Whitespace and line breaks have been added to the examples in this + document to promote readability. + + + + +Daboo Standards Track [Page 3] + +RFC 5464 The IMAP METADATA Extension February 2009 + + +3. Data Model + +3.1. Overview + + Mailboxes or the server as a whole may have zero or more annotations + associated with them. An annotation contains a uniquely named entry, + which has a value. Annotations can be added to mailboxes when a + mailbox name is provided as the first argument to the SETMETADATA + command, or to the server as a whole when the empty string is + provided as the first argument to the command. + + For example, a general comment being added to a mailbox may have an + entry name of "/comment" and a value of "Really useful mailbox". + + The protocol changes to IMAP described below allow a client to access + or change the values of any annotation entry, assuming it has + sufficient access rights to do so. + +3.2. Namespace of Entries + + Each annotation is an entry that has a hierarchical name, with each + component of the name separated by a slash ("/"). An entry name MUST + NOT contain two consecutive "/" characters and MUST NOT end with a + "/" character. + + The value of an entry is NIL (has no value), or a string or binary + data of zero or more octets. A string MAY contain multiple lines of + text. Clients MUST use the CRLF (0x0D 0x0A) character octet sequence + to represent line ends in a multi-line string value. + + Entry names MUST NOT contain asterisk ("*") or percent ("%") + characters and MUST NOT contain non-ASCII characters or characters + with octet values in the range 0x00 to 0x19. Invalid entry names + result in a BAD response in any IMAP command in which they are used. + + Entry names are case-insensitive. + + Use of control or punctuation characters in entry names is strongly + discouraged. + + This specification defines an initial set of entry names available + for use with mailbox and server annotations. In addition, an + extension mechanism is described to allow additional names to be + added for extensibility. + + The first component in entry names defines the scope of the + annotation. Currently, only the prefixes "/private" or "/shared" are + defined. These prefixes are used to indicate whether an annotation + + + +Daboo Standards Track [Page 4] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + is stored on a per-user basis ("/private") and not visible to other + users, or whether an annotation is shared between authorized users + ("/shared") with a single value that can be read and changed by + authorized users with appropriate access. See Section 3.3 for + details. + + Entry names can have any number of components starting at 2, unless + they fall under the vendor namespaces (i.e., have a /shared/vendor/ + or /private/vendor/ prefix as described + below), in which case they have at least 4 components. + +3.2.1. Entry Names + + Entry names MUST be specified in a Standards Track or IESG-approved + Experimental RFC, or fall under the vendor namespace. See + Section 6.1 for the registration template. + +3.2.1.1. Server Entries + + These entries are set or retrieved when the mailbox name argument to + the new SETMETADATA or GETMETADATA command is the empty string. + + /shared/comment + + Defines a comment or note that is associated with the server and + that is shared with authorized users of the server. + + /shared/admin + + Indicates a method for contacting the server administrator. The + value MUST be a URI (e.g., a mailto: or tel: URL). This entry is + always read-only -- clients cannot change it. It is visible to + authorized users of the system. + + /shared/vendor/ + + Defines the top level of shared entries associated with the + server, as created by a particular product of some vendor. This + entry can be used by vendors to provide server- or client-specific + annotations. The vendor-token MUST be registered with IANA, using + the Application Configuration Access Protocol (ACAP) [RFC2244] + vendor subtree registry. + + /private/vendor/ + + Defines the top level of private entries associated with the + server, as created by a particular product of some vendor. This + entry can be used by vendors to provide server- or client-specific + + + +Daboo Standards Track [Page 5] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + annotations. The vendor-token MUST be registered with IANA, using + the ACAP [RFC2244] vendor subtree registry. + +3.2.1.2. Mailbox Entries + + These entries are set or retrieved when the mailbox name argument to + the new SETMETADATA or GETMETADATA command is not the empty string. + + /shared/comment + + Defines a shared comment or note associated with a mailbox. + + /private/comment + + Defines a private (per-user) comment or note associated with a + mailbox. + + /shared/vendor/ + + Defines the top level of shared entries associated with a specific + mailbox, as created by a particular product of some vendor. This + entry can be used by vendors to provide client-specific + annotations. The vendor-token MUST be registered with IANA, using + the ACAP [RFC2244] vendor subtree registry. + + /private/vendor/ + + Defines the top level of private entries associated with a + specific mailbox, as created by a particular product of some + vendor. This entry can be used by vendors to provide client- + specific annotations. The vendor-token MUST be registered with + IANA, using the ACAP [RFC2244] vendor subtree registry. + +3.3. Private versus Shared and Access Control + + In the absence of the ACL (Access Control List) extension [RFC4314], + users can only set and retrieve private or shared mailbox annotations + on a mailbox that exists and is returned to them via a LIST or LSUB + command, and on which they have either read or write access to the + actual message content of the mailbox (as determined by the READ-ONLY + and READ-WRITE response codes as described in Section 5.2 of + [RFC4314]). + + When the ACL extension [RFC4314] is present, users can only set and + retrieve private or shared mailbox annotations on a mailbox on which + they have the "l" right and any one of the "r", "s", "w", "i", or "p" + rights. + + + + +Daboo Standards Track [Page 6] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + If a client attempts to set or retrieve annotations on mailboxes that + do not satisfy the conditions above, the server MUST respond with a + NO response. + + Users can always retrieve private or shared server annotations if + they exist. Servers MAY restrict the creation of private or shared + server annotations as appropriate. When restricted, the server MUST + return a NO response when the SETMETADATA command is used to try to + create a server annotation. + + If the METADATA extension is present, support for shared annotations + is REQUIRED, whilst support for private annotations is OPTIONAL. + This recognizes the fact that support for private annotations may + introduce significantly more complexity to a server in terms of + tracking ownership of the annotations, how quota is determined for + users based on their own annotations, etc. + +4. IMAP Protocol Changes + +4.1. General Considerations + + The new SETMETADATA command and the METADATA response each have a + mailbox name argument. An empty string is used for the mailbox name + to signify server annotations. A non-empty string is used to signify + mailbox annotations attached to the corresponding mailbox. + + Servers SHOULD ensure that mailbox annotations are automatically + moved when the mailbox they refer to is renamed, i.e., the + annotations follow the mailbox. This applies to a rename of the + INBOX, with the additional behavior that the annotations are copied + from the original INBOX to the renamed mailbox, i.e., mailbox + annotations are preserved on the INBOX when it is renamed. + + Servers SHOULD delete annotations for a mailbox when the mailbox is + deleted, so that a mailbox created with the same name as a previously + existing mailbox does not inherit the old mailbox annotations. + + Servers SHOULD allow annotations on all 'types' of mailboxes, + including ones reporting \Noselect for their LIST response. Servers + can implicitly remove \Noselect mailboxes when all child mailboxes + are removed, and, at that time any annotations associated with the + \Noselect mailbox SHOULD be removed. + + The server is allowed to impose limitations on the size of any one + annotation or the total number of annotations for a single mailbox or + for the server as a whole. However, the server MUST accept an + annotation data size of at least 1024 bytes, and an annotation count + per server or mailbox of at least 10. + + + +Daboo Standards Track [Page 7] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + Some annotations may be "read-only" -- i.e., they are set by the + server and cannot be changed by the client. Also, such annotations + may be "computed" -- i.e., the value changes based on underlying + properties of the mailbox or server. For example, an annotation + reporting the total size of all messages in the mailbox would change + as messages are added or removed. Or, an annotation containing an + IMAP URL for the mailbox would change if the mailbox was renamed. + + Servers MAY support sending unsolicited responses for use when + annotations are changed by some "third-party" (see Section 4.4). In + order to do so, servers MUST support the ENABLE command [RFC5161] and + MUST only send unsolicited responses if the client used the ENABLE + command [RFC5161] extension with the capability string "METADATA" or + "METADATA-SERVER" earlier in the session, depending on which of those + capabilities is supported by the server. + +4.2. GETMETADATA Command + + This extension adds the GETMETADATA command. This allows clients to + retrieve server or mailbox annotations. + + This command is only available in authenticated or selected state + [RFC3501]. + + Arguments: mailbox-name + options + entry-specifier + + Responses: required METADATA response + + Result: OK - command completed + NO - command failure: can't access annotations on + the server + BAD - command unknown or arguments invalid + + When the mailbox name is the empty string, this command retrieves + server annotations. When the mailbox name is not empty, this command + retrieves annotations on the specified mailbox. + + Options MAY be included with this command and are defined below. + + Example: + + C: a GETMETADATA "" /shared/comment + S: * METADATA "" (/shared/comment "Shared comment") + S: a OK GETMETADATA complete + + + + + +Daboo Standards Track [Page 8] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + In the above example, the contents of the value of the "/shared/ + comment" server entry is requested by the client and returned by + the server. + + Example: + + C: a GETMETADATA "INBOX" /private/comment + S: * METADATA "INBOX" (/private/comment "My own comment") + S: a OK GETMETADATA complete + + In the above example, the contents of the value of the "/private/ + comment" mailbox entry for the mailbox "INBOX" is requested by the + client and returned by the server. + + Entry specifiers can be lists of atomic specifiers, so that multiple + annotations may be returned in a single GETMETADATA command. + + Example: + + C: a GETMETADATA "INBOX" (/shared/comment /private/comment) + S: * METADATA "INBOX" (/shared/comment "Shared comment" + /private/comment "My own comment") + S: a OK GETMETADATA complete + + In the above example, the values of the two server entries + "/shared/comment" and "/private/comment" on the mailbox "INBOX" + are requested by the client and returned by the server. + +4.2.1. MAXSIZE GETMETADATA Command Option + + When the MAXSIZE option is specified with the GETMETADATA command, it + restricts which entry values are returned by the server. Only entry + values that are less than or equal in octet size to the specified + MAXSIZE limit are returned. If there are any entries with values + larger than the MAXSIZE limit, the server MUST include the METADATA + LONGENTRIES response code in the tagged OK response for the + GETMETADATA command. The METADATA LONGENTRIES response code returns + the size of the biggest entry value requested by the client that + exceeded the MAXSIZE limit. + + Example: + + C: a GETMETADATA "INBOX" (MAXSIZE 1024) + (/shared/comment /private/comment) + S: * METADATA "INBOX" (/private/comment "My own comment") + S: a OK [METADATA LONGENTRIES 2199] GETMETADATA complete + + + + + +Daboo Standards Track [Page 9] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + In the above example, the values of the two server entries + "/shared/comment" and "/private/comment" on the mailbox "INBOX" + are requested by the client, which wants to restrict the size of + returned values to 1024 octets. In this case, the "/shared/ + comment" entry value is 2199 octets and is not returned. + +4.2.2. DEPTH GETMETADATA Command Option + + When the DEPTH option is specified with the GETMETADATA command, it + extends the list of entry values returned by the server. For each + entry name specified in the GETMETADATA command, the server returns + the value of the specified entry name (if it exists), plus all + entries below the entry name up to the specified DEPTH. Three values + are allowed for DEPTH: + + "0" - no entries below the specified entry are returned + "1" - only entries immediately below the specified entry are returned + "infinity" - all entries below the specified entry are returned + + Thus, "depth 1" for an entry "/a" will match "/a" as well as its + children entries (e.g., "/a/b"), but will not match grandchildren + entries (e.g., "/a/b/c"). + + If the DEPTH option is not specified, this is the same as specifying + "DEPTH 0". + + Example: + + C: a GETMETADATA "INBOX" (DEPTH 1) + (/private/filters/values) + S: * METADATA "INBOX" (/private/filters/values/small + "SMALLER 5000" /private/filters/values/boss + "FROM \"boss@example.com\"") + S: a OK GETMETADATA complete + + In the above example, 2 entries below the /private/filters/values + entry exist on the mailbox "INBOX": "/private/filters/values/ + small" and "/private/filters/values/boss". + +4.3. SETMETADATA Command + + This extension adds the SETMETADATA command. This allows clients to + set annotations. + + This command is only available in authenticated or selected state + [RFC3501]. + + + + + +Daboo Standards Track [Page 10] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + Arguments: mailbox-name + entry + value + list of entry, values + + Responses: no specific responses for this command + + Result: OK - command completed + NO - command failure: can't set annotations, + or annotation too big or too many + BAD - command unknown or arguments invalid + + This command sets the specified list of entries by adding or + replacing the specified values provided, on the specified existing + mailboxes or on the server (if the mailbox argument is the empty + string). Clients can use NIL for the value of entries it wants to + remove. The server SHOULD NOT return a METADATA response containing + the updated annotation data. Clients MUST NOT assume that a METADATA + response will be sent, and MUST assume that if the command succeeds, + then the annotation has been changed. + + If the server is unable to set an annotation because the size of its + value is too large, the server MUST return a tagged NO response with + a "[METADATA MAXSIZE NNN]" response code when NNN is the maximum + octet count that it is willing to accept. + + If the server is unable to set a new annotation because the maximum + number of allowed annotations has already been reached, the server + MUST return a tagged NO response with a "[METADATA TOOMANY]" response + code. + + If the server is unable to set a new annotation because it does not + support private annotations on one of the specified mailboxes, the + server MUST return a tagged NO response with a "[METADATA NOPRIVATE]" + response code. + + When any one annotation fails to be set, resulting in a tagged NO + response from the server, then the server MUST NOT change the values + for other annotations specified in the SETMETADATA command. + + Example: + + C: a SETMETADATA INBOX (/private/comment {33} + S: + ready for data + My new comment across + two lines. + ) + S: a OK SETMETADATA complete + + + +Daboo Standards Track [Page 11] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + In the above example, the entry "/private/comment" for the mailbox + "INBOX" is created (if not already present) and the value set to a + multi-line string. + + Example: + + C: a SETMETADATA INBOX (/private/comment NIL) + S: a OK SETMETADATA complete + + In the above example, the entry "/private/comment" is removed from + the mailbox "INBOX". + + Multiple entries can be set in a single SETMETADATA command by + listing entry-value pairs in the list. + + Example: + + C: a SETMETADATA INBOX (/private/comment "My new comment" + /shared/comment "This one is for you!") + S: a OK SETMETADATA complete + + In the above example, the entries "/private/comment" and "/shared/ + comment" for the mailbox "INBOX" are created (if not already + present) and the values set as specified. + + Example: + + C: a SETMETADATA INBOX (/private/comment "My new comment") + S: a NO [METADATA TOOMANY] SETMETADATA failed + + In the above example, the server is unable to set the requested + (new) annotation as it has reached the limit on the number of + annotations it can support on the specified mailbox. + +4.4. METADATA Response + + The METADATA response displays results of a GETMETADATA command, or + can be returned as an unsolicited response at any time by the server + in response to a change in a server or mailbox annotation. + + When unsolicited responses are activated by the ENABLE [RFC5161] + command for this extension, servers MUST send unsolicited METADATA + responses if server or mailbox annotations are changed by a third- + party, allowing servers to keep clients updated with changes. + + Unsolicited METADATA responses MUST only contain entry names, not the + values. If the client wants to update any cached values, it must + explicitly retrieve those using a GETMETADATA command. + + + +Daboo Standards Track [Page 12] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + The METADATA response can contain multiple entries in a single + response, but the server is free to return multiple responses for + each entry or group of entries, if it desires. + + This response is only available in authenticated or selected state + [RFC3501]. + +4.4.1. METADATA Response with Values + + The response consists of a list of entry-value pairs. + + Example: + + C: a GETMETADATA "" /shared/comment + S: * METADATA "" (/shared/comment "My comment") + S: a OK GETMETADATA complete + + In the above example, a single entry with its value is returned by + the server. + + Example: + + C: a GETMETADATA "INBOX" /private/comment /shared/comment + S: * METADATA "INBOX" (/private/comment "My comment" + /shared/comment "Its sunny outside!") + S: a OK GETMETADATA complete + + In the above example, two entries and their values are returned by + the server. + + Example: + + C: a GETMETADATA "INBOX" /private/comment /shared/comment + S: * METADATA "INBOX" (/private/comment "My comment") + S: * METADATA "INBOX" (/shared/comment "Its sunny outside!") + S: a OK GETMETADATA complete + + In the above example, the server returns two separate responses + for each of the two entries requested. + +4.4.2. Unsolicited METADATA Response without Values + + The response consists of a list of entries, each of which have + changed on the server or mailbox. + + Example: + + + + + +Daboo Standards Track [Page 13] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + C: a NOOP + S: * METADATA "" /shared/comment + S: a OK NOOP complete + + In the above example, the server indicates that the "/shared/ + comment" server entry has been changed. + + Example: + + C: a NOOP + S: * METADATA "INBOX" /shared/comment /private/comment + S: a OK NOOP complete + + In the above example, the server indicates a change to two mailbox + entries. + +5. 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 + [RFC3501], with the new definitions in [RFC4466] superseding those in + [RFC3501]. + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of upper or lower case characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. + + capability =/ "METADATA" / "METADATA-SERVER" + ; defines the capabilities for this extension. + + command-auth =/ setmetadata / getmetadata + ; adds to original IMAP command + + entries = entry / + "(" entry *(SP entry) ")" + ; entry specifiers + + entry = astring + ; slash-separated path to entry + ; MUST NOT contain "*" or "%" + + entry-value = entry SP value + + entry-values = "(" entry-value *(SP entry-value) ")" + + + + +Daboo Standards Track [Page 14] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + entry-list = entry *(SP entry) + ; list of entries used in unsolicited + ; METADATA response + + getmetadata = "GETMETADATA" [SP getmetadata-options] + SP mailbox SP entries + ; empty string for mailbox implies + ; server annotation. + + getmetadata-options = "(" getmetadata-option + *(SP getmetadata-option) ")" + + getmetadata-option = tagged-ext-label [SP tagged-ext-val] + ; tagged-ext-label and tagged-ext-val + ; are defined in [RFC4466]. + + maxsize-opt = "MAXSIZE" SP number + ; Used as a getmetadata-option + + metadata-resp = "METADATA" SP mailbox SP + (entry-values / entry-list) + ; empty string for mailbox implies + ; server annotation. + + response-payload =/ metadata-resp + ; adds to original IMAP data responses + + resp-text-code =/ "METADATA" SP "LONGENTRIES" SP number + ; new response codes for GETMETADATA + + resp-text-code =/ "METADATA" SP ("MAXSIZE" SP number / + "TOOMANY" / "NOPRIVATE") + ; new response codes for SETMETADATA + ; failures + + scope-opt = "DEPTH" SP ("0" / "1" / "infinity") + ; Used as a getmetadata-option + + setmetadata = "SETMETADATA" SP mailbox + SP entry-values + ; empty string for mailbox implies + ; server annotation. + + value = nstring / literal8 + + + + + + + +Daboo Standards Track [Page 15] + +RFC 5464 The IMAP METADATA Extension February 2009 + + +6. IANA Considerations + + All entries MUST have either "/shared" or "/private" as a prefix. + Entry names MUST be specified in a Standards Track or IESG-approved + Experimental RFC, or fall under the vendor namespace (i.e., use + /shared/vendor/ or /private/vendor/ as + the prefix). + + Each entry registration MUST include a content-type that is used to + indicate the nature of the annotation value. Where applicable, a + charset parameter MUST be included with the content-type. + +6.1. Entry and Attribute Registration Template + + To: iana@iana.org + Subject: IMAP METADATA Entry Registration + + Type: [Either "Mailbox" or "Server"] + + Name: [the name of the entry] + + Description: [a description of what the entry is for] + + Content-type: [MIME Content-Type and charset for the entry value] + + RFC Number: [for entries published as RFCs] + + Contact: [email and/or physical address to contact for + additional information] + +6.2. Server Entry Registrations + + The following templates specify the IANA registrations of annotation + entries specified in this document. + + + + + + + + + + + + + + + + + +Daboo Standards Track [Page 16] + +RFC 5464 The IMAP METADATA Extension February 2009 + + +6.2.1. /shared/comment + + To: iana@iana.org + Subject: IMAP METADATA Entry Registration + + Type: Server + + Name: /shared/comment + + Description: Defines a comment or note that is associated + with the server and that is shared with + authorized users of the server. + + Content-type: text/plain; charset=utf-8 + + RFC Number: RFC 5464 + + Contact: IMAP Extensions mailto:ietf-imapext@imc.org + +6.2.2. /shared/admin + + To: iana@iana.org + Subject: IMAP METADATA Entry Registration + + Type: Server + + Name: /shared/admin + + Description: Indicates a method for contacting the server + administrator. The value MUST be a URI (e.g., a + mailto: or tel: URL). This entry is always + read-only -- clients cannot change it. It is visible + to authorized users of the system. + + Content-type: text/plain; charset=utf-8 + + RFC Number: RFC 5464 + + Contact: IMAP Extensions mailto:ietf-imapext@imc.org + +6.3. Mailbox Entry Registrations + + The following templates specify the IANA registrations of annotation + entries specified in this document. + + + + + + + +Daboo Standards Track [Page 17] + +RFC 5464 The IMAP METADATA Extension February 2009 + + +6.3.1. /shared/comment + + To: iana@iana.org + Subject: IMAP METADATA Entry Registration + + Type: Mailbox + + Name: /shared/comment + + Description: Defines a shared comment or note associated with a + mailbox. + + Content-type: text/plain; charset=utf-8 + + RFC Number: RFC 5464 + + Contact: IMAP Extensions mailto:ietf-imapext@imc.org + +6.3.2. /private/comment + + To: iana@iana.org + Subject: IMAP METADATA Entry Registration + + Type: Mailbox + + Name: /private/comment + + Description: Defines a private comment or note associated with a + mailbox. + + Content-type: text/plain; charset=utf-8 + + RFC Number: RFC 5464 + + Contact: IMAP Extensions mailto:ietf-imapext@imc.org + +7. Security Considerations + + The security considerations in Section 11 of [RFC3501] apply here + with respect to protecting annotations from snooping. Servers MAY + choose to only support the METADATA and/or METADATA-SERVER extensions + after a privacy layer has been negotiated by the client. + + Annotations can contain arbitrary data of varying size. As such, + servers MUST ensure that size limits are enforced to prevent a user + from using up all available space on a server and preventing use by + others. Clients MUST treat annotation data values as an "untrusted" + source of data as it is possible for it to contain malicious content. + + + +Daboo Standards Track [Page 18] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + Annotations whose values are intended to remain private MUST be + stored only in entries that have the "/private" prefix on the entry + name. + + Excluding the above issues, the METADATA extension does not raise any + security considerations that are not present in the base IMAP + protocol, and these issues are discussed in [RFC3501]. + +8. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2244] Newman, C. and J. Myers, "ACAP -- Application + Configuration Access Protocol", RFC 2244, November 1997. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) Extension", + RFC 4314, December 2005. + + [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 + ABNF", RFC 4466, April 2006. + + [RFC5161] Gulbrandsen, A. and A. Melnikov, "The IMAP ENABLE + Extension", RFC 5161, March 2008. + + [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + +Appendix A. Acknowledgments + + The ideas expressed in this document are based on the message + annotation document that was co-authored by Randall Gellens. The + author would like to thank the following individuals for contributing + their ideas and support for writing this specification: Dave + Cridland, Arnt Gulbrandsen, Dan Karp, Alexey Melnikov, Ken Murchison, + Chris Newman, and Michael Wener. + + + + + + + + + + + + +Daboo Standards Track [Page 19] + +RFC 5464 The IMAP METADATA Extension February 2009 + + +Author's Address + + Cyrus Daboo + Apple Inc. + 1 Infinite Loop + Cupertino, CA 95014 + USA + + EMail: cyrus@daboo.name + URI: http://www.apple.com/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Daboo Standards Track [Page 20] + +RFC 5464 The IMAP METADATA Extension February 2009 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2009). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Daboo Standards Track [Page 21] + + diff --git a/docs/rfcs/rfc5465.IMAP_NOTIFY_extension.txt b/docs/rfcs/rfc5465.IMAP_NOTIFY_extension.txt new file mode 100644 index 0000000..3fe5bcf --- /dev/null +++ b/docs/rfcs/rfc5465.IMAP_NOTIFY_extension.txt @@ -0,0 +1,1235 @@ + + + + + + +Network Working Group A. Gulbrandsen +Request for Comments: 5465 Oryx Mail Systems GmbH +Updates: 5267 C. King +Category: Standards Track A. Melnikov + Isode Ltd. + February 2009 + + + The IMAP NOTIFY Extension + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (c) 2009 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 (http://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. + +Abstract + + This document defines an IMAP extension that allows a client to + request specific kinds of unsolicited notifications for specified + mailboxes, such as messages being added to or deleted from such + mailboxes. + + + + + + + + + + + + + + + + +Gulbrandsen, et al. Standards Track [Page 1] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + +Table of Contents + + 1. Overview and Rationale ..........................................3 + 2. Conventions Used in This Document ...............................4 + 3. The NOTIFY Extension ............................................4 + 3.1. The NOTIFY Command .........................................4 + 4. Interaction with the IDLE Command ...............................8 + 5. Event Types .....................................................8 + 5.1. FlagChange and AnnotationChange ............................9 + 5.2. MessageNew .................................................9 + 5.3. MessageExpunge ............................................10 + 5.4. MailboxName ...............................................11 + 5.5. SubscriptionChange ........................................12 + 5.6. MailboxMetadataChange .....................................12 + 5.7. ServerMetadataChange ......................................13 + 5.8. Notification Overflow .....................................13 + 5.9. ACL (Access Control List) Changes .........................13 + 6. Mailbox Specification ..........................................14 + 6.1. Mailbox Specifiers Affecting the Currently + Selected Mailbox ..........................................14 + 6.2. Personal ..................................................15 + 6.3. Inboxes ...................................................15 + 6.4. Subscribed ................................................15 + 6.5. Subtree ...................................................15 + 6.6. Mailboxes .................................................16 + 7. Extension to SEARCH and SORT Commands ..........................16 + 8. Formal Syntax ..................................................16 + 9. Security Considerations ........................................19 + 10. IANA Considerations ...........................................19 + 10.1. Initial LIST-EXTENDED Extended Data Item Registrations ...19 + 11. Acknowledgements ..............................................20 + 12. Normative References ..........................................20 + 13. Informative References ........................................21 + + + + + + + + + + + + + + + + + + +Gulbrandsen, et al. Standards Track [Page 2] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + +1. Overview and Rationale + + The IDLE command (defined in [RFC2177]) provides a way for the client + to go into a mode where the IMAP server pushes it notifications about + IMAP mailstore events for the selected mailbox. However, the IDLE + extension doesn't restrict or control which server events can be + sent, or what information the server sends in response to each event. + Also, IDLE only applies to the selected mailbox, thus requiring an + additional TCP connection per mailbox. + + This document defines an IMAP extension that allows clients to + express their preferences about unsolicited events generated by the + server. The extension allows clients to only receive events that + they are interested in, while servers know that they don't need to go + to the effort of generating certain types of untagged responses. + + Without the NOTIFY command defined in this document, an IMAP server + will only send information about mailstore changes to the client in + the following cases: + + - as the result of a client command (e.g., FETCH responses to a + FETCH or STORE command), + - as unsolicited responses sent just before the end of a command + (e.g., EXISTS or EXPUNGE) as the result of changes in other + sessions, and + - during an IDLE command. + + The NOTIFY command extends what information may be returned in those + last two cases, and also permits and requires the server to send + information about updates between commands. The NOTIFY command also + allows for the client to extend what information is sent unsolicited + about the selected mailbox and to request some update information to + be sent regarding other mailboxes. + + The interaction between IDLE and NOTIFY commands is described in + Section 4. + + For the new messages delivered to or appended to the selected + mailbox, the NOTIFY command can be used to request that a set of + attributes be sent to the client in an unsolicited FETCH response. + This allows a client to be a passive recipient of events and new mail + and to be able to maintain full synchronisation without having to + issue any subsequent commands except to modify the state of the + mailbox on the server. + + + + + + + +Gulbrandsen, et al. Standards Track [Page 3] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + Some mobile clients, however, may want mail "pushed" only for mail + that matches a SEARCH pattern. To meet that need, [RFC5267] is + augmented by this document to extend the UPDATE return option to + specify a list of fetch-atts to be returned when a new message is + delivered or appended in another session. + +2. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + The acronym MSN stands for Message Sequence Numbers (see Section + 2.3.1.2 of [RFC3501]). + + Example lines prefaced by "C:" are sent by the client and ones + prefaced by "S:", by the server. "[...]" means elision. + +3. The NOTIFY Extension + + IMAP servers that support this extension advertise the NOTIFY + capability. This extension adds the NOTIFY command as defined in + Section 5.1. + + A server implementing this extension is not required to implement + LIST-EXTENDED [RFC5258], even though a NOTIFY-compliant server must + be able to return extended LIST responses, defined in [RFC5258]. + +3.1. The NOTIFY Command + + Arguments: "SET" + Optional STATUS indicator + Mailboxes to be watched + Events about which to notify the client + + Or + Arguments: "NONE" + + Responses: Possibly untagged STATUS responses (for SET) + + Result: OK - The server will notify the client as requested. + NO - Unsupported NOTIFY event, NOTIFY too complex or + expensive, etc. + BAD - Command unknown, invalid, unsupported, or has + unknown arguments. + + + + + + +Gulbrandsen, et al. Standards Track [Page 4] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + The NOTIFY command informs the server that the client listens for + event notifications all the time (even when no command is in + progress), and requests the server to notify it about the specified + set of events. The NOTIFY command has two forms. NOTIFY NONE + specifies that the client is not interested in any kind of event + happening on the server. NOTIFY SET replaces the current list of + interesting events with a new list of events. + + Until the NOTIFY command is used for the first time, the server only + sends notifications while a command is being processed, and notifies + the client about these events on the selected mailbox (see Section 5 + for definitions): MessageNew, MessageExpunge, or FlagChange. It does + not notify the client about any events on other mailboxes. + + The effect of a successful NOTIFY command lasts until the next NOTIFY + command or until the IMAP connection is closed. + + A successful NOTIFY SET command MUST cause the server to immediately + return any accumulated changes to the currently selected mailbox (if + any), such as flag changes and new or expunged messages. Thus, a + successful NOTIFY SET command implies an implicit NOOP command. + + The NOTIFY SET command can request notifications of message-related + changes to the selected mailbox, whatever that may be at the time the + message notifications are being generated. This is done by + specifying either the SELECTED or the SELECTED-DELAYED mailbox + selector (see Section 6.1) in the NOTIFY SET command. If the + SELECTED/SELECTED-DELAYED mailbox selector is not specified in the + NOTIFY SET command, this means that the client doesn't want to + receive any s for the currently selected mailbox. + This is the same as specifying SELECTED NONE. + + The client can also request notifications on other mailboxes by name + or by a limited mailbox pattern match. Message-related notifications + returned for the currently selected mailbox will be those specified + by the SELECTED/SELECTED-DELAYED mailbox specifier, even if the + selected mailbox also appears by name (or matches a pattern) in the + command. Non-message-related notifications are controlled by mailbox + specifiers other than SELECTED/SELECTED-DELAYED. + + If the NOTIFY command enables MessageNew, MessageExpunge, + AnnotationChange, or FlagChange notifications for a mailbox other + than the currently selected mailbox, and the client has specified the + STATUS indicator parameter, then the server MUST send a STATUS + response for that mailbox before NOTIFY's tagged OK. If MessageNew + is enabled, the STATUS response MUST contain MESSAGES, UIDNEXT, and + UIDVALIDITY. If MessageExpunge is enabled, the STATUS response MUST + contain MESSAGES. If either AnnotationChange or FlagChange are + + + +Gulbrandsen, et al. Standards Track [Page 5] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + included and the server also supports the CONDSTORE [RFC4551] and/or + QRESYNC [RFC5162] extensions, the STATUS response MUST contain + UIDVALIDITY and HIGHESTMODSEQ. Absence of the STATUS indicator + parameter allows the client to avoid the additional STATUS responses. + This might be useful if the client already retrieved this information + before issuing the NOTIFY command. + + Clients are advised to limit the number of mailboxes used with + NOTIFY. Particularly, if a client asks for events for all accessible + mailboxes, the server may swamp the client with updates about shared + mailboxes. This may reduce the client's battery life. Also, this + wastes both server and network resources. + + For each mailbox specified, the server verifies that the client has + access using the following test: + + - If the name does not refer to an existing mailbox, the server MUST + ignore it. + + - If the name refers to a mailbox that the client can't LIST, the + server MUST ignore it. For a server that implements [RFC4314], + this means that if the client doesn't have the 'l' (lookup) right + for the name, then the server MUST ignore the mailbox. This + behavior prevents disclosure of potentially confidential + information to clients who don't have rights to know it. + + - If the name refers to a mailbox that the client can LIST (e.g., it + has the 'l' right from [RFC4314]), but the client doesn't have + another right required for processing of the specified event(s), + then the server MUST respond with an untagged extended LIST + response containing the \NoAccess name attribute. + + The server SHOULD return the tagged OK response if the client has + access to at least one of the mailboxes specified in the current list + of interesting events. The server MAY return the tagged NO response + if the client has no access to any of the specified mailboxes and no + access can ever be granted in the future (e.g., the client specified + an event for 'Subtree Bar/Foo', 'Bar/Foo' doesn't exist, and LIST + returns \Noinferiors for the parent 'Bar'). + + If the notification would be prohibitively expensive for the server + (e.g., "notify me of all flag changes in all mailboxes"), the server + MAY refuse the command with a tagged NO [NOTIFICATIONOVERFLOW] + response. + + + + + + + +Gulbrandsen, et al. Standards Track [Page 6] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + If the client requests information for events of an unsupported type, + the server MUST refuse the command with a tagged NO response (not a + BAD). This response SHOULD contain the BADEVENT response code, which + MUST list names of all events supported by the server. + + Here's an example: + + S: * OK [CAPABILITY IMAP4REV1 NOTIFY] + C: a login bob alice + S: a OK Password matched + C: b notify set status (selected MessageNew (uid + body.peek[header.fields (from to subject)]) MessageExpunge) + (subtree Lists MessageNew) + S: * STATUS Lists/Lemonade (UIDVALIDITY 4 UIDNEXT 9999 MESSAGES + 500) + S: [...] + S: * STATUS Lists/Im2000 (UIDVALIDITY 901 UIDNEXT 1 MESSAGES 0) + S: b OK done + C: c select inbox + S: [...] (the usual 7-8 responses to SELECT) + S: c OK INBOX selected + (Time passes. A new message is delivered to mailbox + Lists/Lemonade.) + S: * STATUS Lists/Lemonade (UIDVALIDITY 4 UIDNEXT 10000 + MESSAGES 501) + (Time passes. A new message is delivered to inbox.) + S: * 127 FETCH (UID 127001 BODY[HEADER.FIELDS (From To + Subject)] {75} + S: Subject: Re: good morning + S: From: alice@example.org + S: To: bob@example.org + S: + S: ) + (Time passes. The client decides it wants to know about + one more mailbox. As the client already knows necessary + STATUS information for all mailboxes below the Lists + mailbox, and because "notify set status" would cause + STATUS responses for *all* mailboxes specified in the + NOTIFY command, including the ones for which the client + already knows STATUS information, the client issues an + explicit STATUS request for the mailbox to be added to + the watch list, followed by the NOTIFY SET without the + STATUS parameter.) + C: d STATUS misc (UIDVALIDITY UIDNEXT MESSAGES) + S: * STATUS misc (UIDVALIDITY 1 UIDNEXT 999) + S: d STATUS completed + + + + + +Gulbrandsen, et al. Standards Track [Page 7] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + C: e notify set (selected MessageNew (uid + body.peek[header.fields (from to subject)]) MessageExpunge) + (subtree Lists MessageNew) (mailboxes misc MessageNew) + S: e OK done + +4. Interaction with the IDLE Command + + If IDLE [RFC2177] (as well as this extension) is supported, then + while processing any IDLE command, the server MUST send exactly the + same events as instructed by the client using the NOTIFY command. + + NOTIFY makes IDLE unnecessary for some clients. If a client does not + use MSNs and '*' in commands, it can request MessageExpunge and + MessageNew for the selected mailbox by using the NOTIFY command + instead of entering the IDLE mode. + + A client that uses MSNs and '*' in commands can still use the NOTIFY + command if it specifies the SELECTED-DELAYED mailbox specifier in the + NOTIFY command. + +5. Event Types + + Only some of the events in [RFC5423] can be expressed in IMAP, and + for some of them there are several possible ways to express the + event. + + This section specifies the events of which an IMAP server can notify + an IMAP client, and how. + + The server SHOULD omit notifying the client if the event is caused by + this client. For example, if the client issues CREATE and has + requested a MailboxName event that would cover the newly created + mailbox, the server SHOULD NOT notify the client of the MailboxName + change. + + All event types described in this document require the 'l' and 'r' + rights (see [RFC4314]) on all observed mailboxes. Servers that don't + implement [RFC4314] should map the above rights to their access- + control model. + + If the FlagChange and/or AnnotationChange events are specified, + MessageNew and MessageExpunge MUST also be specified by the client. + Otherwise, the server MUST respond with the tagged BAD response. + + If one of MessageNew or MessageExpunge is specified, then both events + MUST be specified. Otherwise, the server MUST respond with the + tagged BAD response. + + + + +Gulbrandsen, et al. Standards Track [Page 8] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + The client can instruct the server not to send an event by omitting + the necessary event from the list of events specified in NOTIFY SET, + by using the NONE event specifier in the NOTIFY SET, or by using + NOTIFY NONE. In particular, NOTIFY SET ... NONE can be used as a + snapshot facility by clients. + +5.1. FlagChange and AnnotationChange + + If the flag and/or message annotation change happens in the selected + mailbox, the server MUST notify the client by sending an unsolicited + FETCH response, which MUST include UID and FLAGS/ANNOTATION FETCH + data items. It MAY also send new FLAGS and/or OK [PERMANENTFLAGS + ...] responses. + + If a search context is in effect as specified in [RFC5267], an + ESEARCH ADDTO or ESEARCH REMOVEFROM will also be generated, if + appropriate. In this case, the FETCH response MUST precede the + ESEARCH response. + + If the change happens in another mailbox, then the server responds + with a STATUS response. The exact content of the STATUS response + depends on various factors. If CONDSTORE [RFC4551] and/or QRESYNC + [RFC5162] are enabled by the client, then the server sends a STATUS + response that includes at least HIGHESTMODSEQ and UIDVALIDITY status + data items. If the number of messages with the \Seen flag changes, + the server MAY also include the UNSEEN data item in the STATUS + response. If CONDSTORE/QRESYNC is not enabled by the client and the + server chooses not to include the UNSEEN data item, the server does + not notify the client. When this event is requested, the server MUST + notify the client about mailbox UIDVALIDITY changes. This is done by + sending a STATUS response that includes UIDVALIDITY. + + FlagChange covers the MessageRead, MessageTrash, FlagsSet, and + FlagsClear events in [RFC5423]. + + Example in the selected mailbox: + S: * 99 FETCH (UID 9999 FLAGS ($Junk)) + + And in another mailbox, with CONDSTORE in use: + S: * STATUS Lists/Lemonade (HIGHESTMODSEQ 65666665 UIDVALIDITY + 101) + + + + + + + + + + +Gulbrandsen, et al. Standards Track [Page 9] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + +5.2. MessageNew + + This covers both MessageNew and MessageAppend in [RFC5423]. + + If the new/appended message is in the selected mailbox, the server + notifies the client by sending an unsolicited EXISTS response, + followed by an unsolicited FETCH response containing the information + requested by the client. A FETCH response SHOULD NOT be generated + for a new message created by the client on this particular + connection, for instance, as the result of an APPEND or COPY command + to the selected mailbox performed by the client itself. The server + MAY also send a RECENT response, if the server marks the message as + \Recent. + + Note that a single EXISTS response can be returned for multiple + MessageAppend/MessageNew events. + + If a search context is in effect as specified in [RFC5267], an + ESEARCH ADDTO will also be generated, if appropriate. In this case, + the EXISTS response MUST precede the ESEARCH response. Both the + NOTIFY command and the SEARCH and SORT commands (see Section 7) can + specify attributes to be returned for new messages. These attributes + SHOULD be combined into a single FETCH response. The server SHOULD + avoid sending duplicate data. The FETCH response(s) MUST follow any + ESEARCH ADDTO responses. + + If the new/appended message is in another mailbox, the server sends + an unsolicited STATUS (UIDNEXT MESSAGES) response for the relevant + mailbox. If the CONDSTORE extension [RFC4551] and/or the QRESYNC + extension [RFC5162] is enabled, the HIGHESTMODSEQ status data item + MUST be included in the STATUS response. + + The client SHOULD NOT use FETCH attributes that implicitly set the + \seen flag, or that presuppose the existence of a given bodypart. + UID, MODSEQ, FLAGS, ENVELOPE, BODY.PEEK[HEADER.FIELDS... and + BODY/BODYSTRUCTURE may be the most useful attributes. + + Note that if a client asks to be notified of MessageNew events with + the SELECTED mailbox specifier, the number of messages can increase + at any time, and therefore the client cannot refer to a specific + message using the MSN/UID '*'. + + Example in the selected mailbox: + S: * 444 EXISTS + S: * 444 FETCH (UID 9999) + + And in another mailbox, without CONDSTORE enabled: + S: * STATUS Lists/Lemonade (UIDNEXT 10002 MESSAGES 503) + + + +Gulbrandsen, et al. Standards Track [Page 10] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + +5.3. MessageExpunge + + If the expunged message or messages are in the selected mailbox, the + server notifies the client using EXPUNGE (or VANISHED, if [RFC5162] + is supported by the server and enabled by the client). + + If a search context is in effect, as specified in [RFC5267], an + ESEARCH REMOVEFROM will also be generated, if appropriate. + + If the expunged message or messages are in another mailbox, the + server sends an unsolicited STATUS (UIDNEXT MESSAGES) response for + the relevant mailbox. If the QRESYNC [RFC5162] extension is enabled, + the HIGHESTMODSEQ data item MUST be included in the STATUS response + as well. + + Note that if a client requests MessageExpunge with the SELECTED + mailbox specifier, the meaning of an MSN can change at any time, so + the client cannot use MSNs in commands anymore. For example, such a + client cannot use FETCH, but has to use UID FETCH. The meaning of + '*' can also change when messages are added or expunged. A client + wishing to keep using MSNs can either use the SELECTED-DELAYED + mailbox specifier or can avoid using the MessageExpunge event + entirely. + + The MessageExpunge notification covers both MessageExpunge and + MessageExpire events from [RFC5423]. + + Example in the selected mailbox, without QRESYNC: + S: * 444 EXPUNGE + + The same example in the selected mailbox, with QRESYNC: + S: * VANISHED 5444 + + And in another mailbox, when QRESYNC is not enabled: + S: * STATUS misc (UIDNEXT 999 MESSAGES 554) + +5.4. MailboxName + + These notifications are sent if an affected mailbox name was created + (with CREATE), deleted (with DELETE), or renamed (with RENAME). For + a server that implements [RFC4314], granting or revocation of the 'l' + right to the current user on the affected mailbox MUST be considered + mailbox creation or deletion, respectively. If a mailbox is created + or deleted, the mailbox itself and its direct parent (whether it is + an existing mailbox or not) are considered to be affected. + + + + + + +Gulbrandsen, et al. Standards Track [Page 11] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + The server notifies the client by sending an unsolicited LIST + response for each affected mailbox name. If, after the event, the + mailbox name does not refer to a mailbox accessible to the client, + the \Nonexistent flag MUST be included. + + For each LISTable mailbox renamed, the server sends an extended LIST + response [RFC5258] for the new mailbox name, containing the OLDNAME + extended data item with the old mailbox name. When a mailbox is + renamed, its children are renamed too. No additional MailboxName + events are sent for children in this case. When INBOX is renamed, a + new INBOX is assumed to be created. No MailboxName event is sent for + INBOX in this case. + + If the server automatically subscribes a mailbox when it is created + or renamed, then the unsolicited LIST response for each affected + subscribed mailbox name MUST include the \Subscribed attribute (see + [RFC5258]). The server SHOULD also include \HasChildren or + \HasNoChildren attributes [RFC5258] as appropriate. + + Example of a newly created mailbox (or granting of the 'l' right on + the mailbox): + S: * LIST () "/" "NewMailbox" + + And a deleted mailbox (or revocation of the 'l' right on the + mailbox): + S: * LIST (\NonExistent) "." "INBOX.DeletedMailbox" + + Example of a renamed mailbox: + S: * LIST () "/" "NewMailbox" ("OLDNAME" ("OldMailbox")) + +5.5. SubscriptionChange + + The server notifies the client by sending an unsolicited LIST + response for each affected mailbox name. If and only if the mailbox + is subscribed after the event, the \Subscribed attribute (see + [RFC5258]) is included. Note that in the LIST response, all mailbox + attributes MUST be accurately computed (this differs from the + behavior of the LSUB command). + + Example: + S: * LIST (\Subscribed) "/" "SubscribedMailbox" + +5.6. MailboxMetadataChange + + Support for this event type is OPTIONAL unless the METADATA extension + [RFC5464] is also supported by the server, in which case support for + this event type is REQUIRED. + + + + +Gulbrandsen, et al. Standards Track [Page 12] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + A client willing to receive unsolicited METADATA responses as a + result of using the MailboxMetadataChange event in the NOTIFY command + doesn't have to issue ENABLE METADATA. + + The server sends an unsolicited METADATA response (as per Section + 4.4.2 of [RFC5464]). If possible, only the changed metadata SHOULD + be included, but if the server can't detect a change to a single + metadata item, it MAY include all metadata items set on the mailbox. + If a metadata item is deleted (set to NIL), it MUST always be + included in the METADATA response. + + Example: + S: * METADATA "INBOX" /shared/comment + +5.7. ServerMetadataChange + + Support for this event type is OPTIONAL unless the METADATA or the + METADATA-SERVER extension [RFC5464] is also supported by the server, + in which case support for this event type is REQUIRED. + + A client willing to receive unsolicited METADATA responses as a + result of using the ServerMetadataChange event in the NOTIFY command + doesn't have to issue ENABLE METADATA or ENABLE METADATA-SERVER. + + The server sends an unsolicited METADATA response (as per Section + 4.4.2 of [RFC5464]). Only the names of changed metadata entries + SHOULD be returned in such METADATA responses. If a metadata item is + deleted (set to NIL), it MUST always be included in the METADATA + response. + + Example: + S: * METADATA "" /shared/comment + +5.8. Notification Overflow + + If the server is unable or unwilling to deliver as many notifications + as it is being asked to, it may disable notifications for some or all + clients. It MUST notify these clients by sending an untagged "OK + [NOTIFICATIONOVERFLOW]" response and behave as if a NOTIFY NONE + command had just been received. + + Example: + S: * OK [NOTIFICATIONOVERFLOW] ...A comment can go here... + + + + + + + + +Gulbrandsen, et al. Standards Track [Page 13] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + +5.9. ACL (Access Control List) Changes + + Even if NOTIFY succeeds, it is still possible to lose access to the + mailboxes being monitored at a later time. If this happens, the + server MUST stop monitoring these mailboxes. If access is later + granted, the server MUST restart event monitoring. + + The server SHOULD return the LIST response with the \NoAccess name + attribute if and when the mailbox loses the 'l' right. Similarly, + the server SHOULD return the LIST response with no \NoAccess name + attribute if the mailbox was previously reported as having \NoAccess + and the 'l' right is later granted. + +6. Mailbox Specification + + Mailboxes to be monitored can be specified in several different ways. + + Only 'SELECTED' and 'SELECTED-DELAYED' (Section 6.1) match the + currently selected mailbox. All other mailbox specifications affect + other (non-selected) mailboxes. + + Note that multiple s can apply to the same mailbox. The + following example demonstrates this. In this example, MessageNew and + MessageExpunge events are reported for INBOX, due to the first + . A SubscriptionChange event will also be reported for + INBOX, due to the second . + + C: a notify set (mailboxes INBOX (Messagenew messageExpunge)) + (personal (SubscriptionChange)) + + A typical client that supports the NOTIFY extension would ask for + events on the selected mailbox and some named mailboxes. + + In the next example, the client asks for FlagChange events for all + personal mailboxes except the currently selected mailbox. This is + different from the previous example because SELECTED overrides all + other message event definitions for the currently selected mailbox + (see Section 3.1). + + C: a notify set (selected (Messagenew (uid flags) messageExpunge)) + (personal (MessageNew FlagChange MessageExpunge)) + +6.1. Mailbox Specifiers Affecting the Currently Selected Mailbox + + Only one of the mailbox specifiers affecting the currently selected + mailbox can be specified in any NOTIFY command. The two such mailbox + specifiers (SELECTED and SELECTED-DELAYED) are described below. + + + + +Gulbrandsen, et al. Standards Track [Page 14] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + Both refer to the mailbox that was selected using either SELECT or + EXAMINE (see [RFC3501], Sections 6.3.1 and 6.3.2). When the IMAP + connection is not in the selected state, such mailbox specifiers + don't refer to any mailbox. + + The mailbox specifiers only apply to s. It is an + error to specify other types of events with either the SELECTED or + the SELECTED-DELAYED selector. + +6.1.1. Selected + + The SELECTED mailbox specifier requires the server to send immediate + notifications for the currently selected mailbox about all specified + s. + +6.1.2. Selected-Delayed + + The SELECTED-DELAYED mailbox specifier requires the server to delay a + MessageExpunge event until the client issues a command that allows + returning information about expunged messages (see Section 7.4.1 of + [RFC3501] for more details), for example, till a NOOP or an IDLE + command has been issued. When SELECTED-DELAYED is specified, the + server MAY also delay returning other s until the + client issues one of the commands specified above, or it MAY return + them immediately. + +6.2. Personal + + Personal refers to all selectable mailboxes in the user's personal + namespace(s), as defined in [RFC2342]. + +6.3. Inboxes + + Inboxes refers to all selectable mailboxes in the user's personal + namespace(s) to which messages may be delivered by a Message Delivery + Agent (MDA) (see [EMAIL-ARCH], particularly Section 4.3.3). + + If the IMAP server cannot easily compute this set, it MUST treat + "inboxes" as equivalent to "personal". + +6.4. Subscribed + + Subscribed refers to all mailboxes subscribed to by the user. + + If the subscription list changes, the server MUST reevaluate the + list. + + + + + +Gulbrandsen, et al. Standards Track [Page 15] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + +6.5. Subtree + + Subtree is followed by a mailbox name or list of mailbox names. A + subtree refers to all selectable mailboxes that are subordinate to + the specified mailbox plus the specified mailbox itself. + +6.6. Mailboxes + + Mailboxes is followed by a mailbox name or a list of mailbox names. + The server MUST NOT do a wildcard expansion. This means there is no + special treatment for the LIST wildcard characters ('*' and '%') if + they are present in mailbox names. + +7. Extension to SEARCH and SORT Commands + + If the server that supports the NOTIFY extension also supports + CONTEXT=SEARCH and/or CONTEXT=SORT as defined in [RFC5267], the + UPDATE return option is extended so that a client can request that + FETCH attributes be returned when a new message is added to the + context result set. + + For example: + + C: a00 SEARCH RETURN (COUNT UPDATE (UID BODY[HEADER.FIELDS (TO + FROM SUBJECT)])) FROM "boss" + S: * ESEARCH (TAG "a00") (COUNT 17) + S: a00 OK + [...a new message is delivered...] + S: * EXISTS 93 + S: * 93 FETCH (UID 127001 BODY[HEADER.FIELDS (FROM TO SUBJECT)] + {76} + S: Subject: Re: good morning + S: From: myboss@example.org + S: To: bob@example.org + S: + S: ) + S: * ESEARCH (TAG "a00") ADDTO (0 93) + + Note that the EXISTS response MUST precede any FETCH responses, and + together they MUST precede the ESEARCH response. + + No untagged FETCH response SHOULD be returned if a message becomes a + member of UPDATE SEARCH due to flag or annotation changes. + + + + + + + + +Gulbrandsen, et al. Standards Track [Page 16] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + +8. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [RFC5234]. [RFC3501] defines + the non-terminals "capability", "command-auth", "mailbox", "mailbox- + data", "resp-text-code", and "search-key". The "modifier-update" + non-terminal is defined in [RFC5267]. "mbx-list-oflag" is defined in + [RFC3501] and updated by [RFC5258]. + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of upper or lower case characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. For example, the + non-terminal value "SELECTED" must be + treated in the same way as "Selected" or "selected". + + capability =/ "NOTIFY" + + command-auth =/ notify + + notify = "NOTIFY" SP + (notify-set / notify-none) + + notify-set = "SET" [status-indicator] SP event-groups + ; Replace registered notification events + ; with the specified list of events + + notify-none = "NONE" + ; Cancel all registered notification + ; events. The client is not interested + ; in receiving any events. + + status-indicator = SP "STATUS" + + one-or-more-mailbox = mailbox / many-mailboxes + + many-mailboxes = "(" mailbox *(SP mailbox) ")" + + event-groups = event-group *(SP event-group) + + event-group = "(" filter-mailboxes SP events ")" + ;; Only s are allowed in + ;; when is used. + + filter-mailboxes = filter-mailboxes-selected / + filter-mailboxes-other + + + + + +Gulbrandsen, et al. Standards Track [Page 17] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + filter-mailboxes-other = "inboxes" / "personal" / "subscribed" / + ( "subtree" SP one-or-more-mailbox ) / + ( "mailboxes" SP one-or-more-mailbox ) + + filter-mailboxes-selected = "selected" / "selected-delayed" + ;; Apply to the currently selected mailbox only. + ;; Only one of them can be specified in a NOTIFY + ;; command. + + events = ( "(" event *(SP event) ")" ) / "NONE" + ;; As in [MSGEVENT]. + ;; "NONE" means that the client does not wish + ;; to receive any events for the specified + ;; mailboxes. + + event = message-event / + mailbox-event / user-event / event-ext + + message-event = ( "MessageNew" [SP + "(" fetch-att *(SP fetch-att) ")" ] ) + / "MessageExpunge" + / "FlagChange" + / "AnnotationChange" + ;; "MessageNew" includes "MessageAppend" from + ;; [MSGEVENT]. "FlagChange" is any of + ;; "MessageRead", "MessageTrash", "FlagsSet", + ;; "FlagsClear" [MSGEVENT]. "MessageExpunge" + ;; includes "MessageExpire" [MSGEVENT]. + ;; MessageNew and MessageExpunge MUST always + ;; be specified together. If FlagChange is + ;; specified, then MessageNew and MessageExpunge + ;; MUST be specified as well. + ;; The fett-att list may only be present for the + ;; SELECTED/SELECTED-DELAYED mailbox filter + ;; (). + + mailbox-event = "MailboxName" / + "SubscriptionChange" / "MailboxMetadataChange" + ; "SubscriptionChange" includes + ; MailboxSubscribe and MailboxUnSubscribe. + ; "MailboxName" includes MailboxCreate, + ; "MailboxDelete" and "MailboxRename". + + user-event = "ServerMetadataChange" + + event-ext = atom + ;; For future extensions + + + + +Gulbrandsen, et al. Standards Track [Page 18] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + oldname-extended-item = "OLDNAME" SP "(" mailbox ")" + ;; Extended data item (mbox-list-extended-item) + ;; returned in a LIST response when a mailbox is + ;; renamed. + ;; Note 1: the OLDNAME tag can be returned + ;; with or without surrounding quotes, as per + ;; mbox-list-extended-item-tag production. + + resp-text-code =/ "NOTIFICATIONOVERFLOW" / + unsupported-events-code + + message-event-name = "MessageNew" / + "MessageExpunge" / "FlagChange" / + "AnnotationChange" + + event-name = message-event-name / mailbox-event / + user-event + + unsupported-events-code = "BADEVENT" + SP "(" event-name *(SP event-name) ")" + + modifier-update = "UPDATE" + [ "(" fetch-att *(SP fetch-att) ")" ] + + mbx-list-oflag =/ "\NoAccess" + +9. Security Considerations + + It is very easy for a client to deny itself service using NOTIFY. + Asking for all events on all mailboxes may work on a small server, + but with a big server, can swamp the client's network connection or + processing capability. In the worst case, the server's processing + could also degrade the service it offers to other clients. + + Server authors should be aware that if a client issues requests and + does not listen to the resulting responses, the TCP window can easily + fill up, and a careless server might block. This problem also exists + in plain IMAP; however, this extension magnifies the problem. + + This extension makes it possible to retrieve messages immediately + when they are added to the mailbox. This makes it wholly impractical + to delete sensitive messages using programs like imapfilter. Using + SIEVE [RFC5228] or similar is much better. + + + + + + + + +Gulbrandsen, et al. Standards Track [Page 19] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + +10. IANA Considerations + + The IANA has added NOTIFY to the list of IMAP extensions. + +10.1. Initial LIST-EXTENDED Extended Data Item Registrations + + The following entry has been added to the LIST-EXTENDED response + registry [RFC5258]: + + To: iana@iana.org + Subject: Registration of OLDNAME LIST-EXTENDED extended data item + + LIST-EXTENDED extended data item tag: OLDNAME + + LIST-EXTENDED extended data item description: The OLDNAME extended + data item describes the old mailbox name for the mailbox + identified by the LIST response. + + Which LIST-EXTENDED option(s) (and their types) causes this extended + data item to be returned (if any): none + + Published specification : RFC 5465, Section 5.4. + + Security considerations: none + + Intended usage: COMMON + + Person and email address to contact for further information: Alexey + Melnikov + + Owner/Change controller: iesg@ietf.org + +11. Acknowledgments + + The authors gratefully acknowledge the help of Peter Coates, Dave + Cridland, Mark Crispin, Cyrus Daboo, Abhijit Menon-Sen, Timo + Sirainen, and Eric Burger. In particular, Peter Coates contributed + lots of text and useful suggestions to this document. + + Various examples are copied from other RFCs. + + This document builds on one published and two unpublished drafts by + the same authors. + + + + + + + + +Gulbrandsen, et al. Standards Track [Page 20] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + +12. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2177] Leiba, B., "IMAP4 IDLE command", RFC 2177, June 1997. + + [RFC2342] Gahrns, M. and C. Newman, "IMAP4 Namespace", RFC 2342, + May 1998. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) + Extension", RFC 4314, December 2005. + + [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to + IMAP4 ABNF", RFC 4466, April 2006. + + [RFC4551] Melnikov, A. and S. Hole, "IMAP Extension for + Conditional STORE Operation or Quick Flag Changes + Resynchronization", RFC 4551, June 2006. + + [RFC5162] Melnikov, A., Cridland, D., and C. Wilson, "IMAP4 + Extensions for Quick Mailbox Resynchronization", RFC + 5162, March 2008. + + [RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", STD 68, RFC 5234, January + 2008. + + [RFC5258] Leiba, B. and A. Melnikov, "Internet Message Access + Protocol version 4 - LIST Command Extensions", RFC 5258, + June 2008. + + [RFC5267] Cridland, D. and C. King, "Contexts for IMAP4", RFC + 5267, July 2008. + + [RFC5423] Newman, C. and R. Gellens, "Internet Message Store + Events", RFC 5423, Month 2009. + + [RFC5464] Daboo, C., "The IMAP METADATA Extension", RFC 5464, + February 2009. + +13. Informative References + + [RFC5228] Guenther, P., Ed., and T. Showalter, Ed., "Sieve: An + Email Filtering Language", RFC 5228, January 2008. + + + +Gulbrandsen, et al. Standards Track [Page 21] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + [EMAIL-ARCH] Crocker, D., "Internet Mail Architecture", Work in + Progress, October 2008. + +Authors' Addresses + + Arnt Gulbrandsen + Oryx Mail Systems GmbH + Schweppermannstr. 8 + D-81671 Muenchen + Germany + + EMail: arnt@oryx.com + + + Curtis King + Isode Ltd + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: Curtis.King@isode.com + + + Alexey Melnikov + Isode Ltd + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: Alexey.Melnikov@isode.com + + + + + + + + + + + + + + + + + + + +Gulbrandsen, et al. Standards Track [Page 22] + diff --git a/docs/rfcs/rfc5530.IMAP_Response_codes.txt b/docs/rfcs/rfc5530.IMAP_Response_codes.txt new file mode 100644 index 0000000..946fbb5 --- /dev/null +++ b/docs/rfcs/rfc5530.IMAP_Response_codes.txt @@ -0,0 +1,507 @@ + + + + + + +Network Working Group A. Gulbrandsen +Request for Comments: 5530 Oryx Mail Systems GmbH +Category: Standards Track May 2009 + + + IMAP Response Codes + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (c) 2009 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 in effect on the date of + publication of this document (http://trustee.ietf.org/license-info). + Please review these documents carefully, as they describe your rights + and restrictions with respect to this document. + +Abstract + + IMAP responses consist of a response type (OK, NO, BAD), an optional + machine-readable response code, and a human-readable text. + + This document collects and documents a variety of machine-readable + response codes, for better interoperation and error reporting. + + + + + + + + + + + + + + + + + + +Gulbrandsen Standards Track [Page 1] + +RFC 5530 IMAP Response Codes May 2009 + + +1. Introduction + + Section 7.1 of [RFC3501] defines a number of response codes that can + help tell an IMAP client why a command failed. However, experience + has shown that more codes are useful. For example, it is useful for + a client to know that an authentication attempt failed because of a + server problem as opposed to a password problem. + + Currently, many IMAP servers use English-language, human-readable + text to describe these errors, and a few IMAP clients attempt to + translate this text into the user's language. + + This document names a variety of errors as response codes. It is + based on errors that have been checked and reported on in some IMAP + server implementations, and on the needs of some IMAP clients. + + This document doesn't require any servers to test for these errors or + any clients to test for these names. It only names errors for better + reporting and handling. + +2. Conventions Used in This Document + + Formal syntax is defined by [RFC5234] as modified by [RFC3501]. + + Example lines prefaced by "C:" are sent by the client and ones + prefaced by "S:" by the server. "[...]" means elision. + +3. Response Codes + + This section defines all the new response codes. Each definition is + followed by one or more examples. + + UNAVAILABLE + Temporary failure because a subsystem is down. For example, an + IMAP server that uses a Lightweight Directory Access Protocol + (LDAP) or Radius server for authentication might use this + response code when the LDAP/Radius server is down. + + C: a LOGIN "fred" "foo" + S: a NO [UNAVAILABLE] User's backend down for maintenance + + AUTHENTICATIONFAILED + Authentication failed for some reason on which the server is + unwilling to elaborate. Typically, this includes "unknown + user" and "bad password". + + + + + + +Gulbrandsen Standards Track [Page 2] + +RFC 5530 IMAP Response Codes May 2009 + + + This is the same as not sending any response code, except that + when a client sees AUTHENTICATIONFAILED, it knows that the + problem wasn't, e.g., UNAVAILABLE, so there's no point in + trying the same login/password again later. + + C: b LOGIN "fred" "foo" + S: b NO [AUTHENTICATIONFAILED] Authentication failed + + AUTHORIZATIONFAILED + Authentication succeeded in using the authentication identity, + but the server cannot or will not allow the authentication + identity to act as the requested authorization identity. This + is only applicable when the authentication and authorization + identities are different. + + C: c1 AUTHENTICATE PLAIN + [...] + S: c1 NO [AUTHORIZATIONFAILED] No such authorization-ID + + C: c2 AUTHENTICATE PLAIN + [...] + S: c2 NO [AUTHORIZATIONFAILED] Authenticator is not an admin + + + EXPIRED + Either authentication succeeded or the server no longer had the + necessary data; either way, access is no longer permitted using + that passphrase. The client or user should get a new + passphrase. + + C: d login "fred" "foo" + S: d NO [EXPIRED] That password isn't valid any more + + PRIVACYREQUIRED + The operation is not permitted due to a lack of privacy. If + Transport Layer Security (TLS) is not in use, the client could + try STARTTLS (see Section 6.2.1 of [RFC3501]) and then repeat + the operation. + + C: d login "fred" "foo" + S: d NO [PRIVACYREQUIRED] Connection offers no privacy + + C: d select inbox + S: d NO [PRIVACYREQUIRED] Connection offers no privacy + + + + + + + +Gulbrandsen Standards Track [Page 3] + +RFC 5530 IMAP Response Codes May 2009 + + + CONTACTADMIN + The user should contact the system administrator or support + desk. + + C: e login "fred" "foo" + S: e OK [CONTACTADMIN] + + NOPERM + The access control system (e.g., Access Control List (ACL), see + [RFC4314]) does not permit this user to carry out an operation, + such as selecting or creating a mailbox. + + C: f select "/archive/projects/experiment-iv" + S: f NO [NOPERM] Access denied + + INUSE + An operation has not been carried out because it involves + sawing off a branch someone else is sitting on. Someone else + may be holding an exclusive lock needed for this operation, or + the operation may involve deleting a resource someone else is + using, typically a mailbox. + + The operation may succeed if the client tries again later. + + C: g delete "/archive/projects/experiment-iv" + S: g NO [INUSE] Mailbox in use + + EXPUNGEISSUED + Someone else has issued an EXPUNGE for the same mailbox. The + client may want to issue NOOP soon. [RFC2180] discusses this + subject in depth. + + C: h search from fred@example.com + S: * SEARCH 1 2 3 5 8 13 21 42 + S: h OK [EXPUNGEISSUED] Search completed + + CORRUPTION + The server discovered that some relevant data (e.g., the + mailbox) are corrupt. This response code does not include any + information about what's corrupt, but the server can write that + to its logfiles. + + C: i select "/archive/projects/experiment-iv" + S: i NO [CORRUPTION] Cannot open mailbox + + + + + + + +Gulbrandsen Standards Track [Page 4] + +RFC 5530 IMAP Response Codes May 2009 + + + SERVERBUG + The server encountered a bug in itself or violated one of its + own invariants. + + C: j select "/archive/projects/experiment-iv" + S: j NO [SERVERBUG] This should not happen + + CLIENTBUG + The server has detected a client bug. This can accompany all + of OK, NO, and BAD, depending on what the client bug is. + + C: k1 select "/archive/projects/experiment-iv" + [...] + S: k1 OK [READ-ONLY] Done + C: k2 status "/archive/projects/experiment-iv" (messages) + [...] + S: k2 OK [CLIENTBUG] Done + + CANNOT + The operation violates some invariant of the server and can + never succeed. + + C: l create "///////" + S: l NO [CANNOT] Adjacent slashes are not supported + + LIMIT + The operation ran up against an implementation limit of some + kind, such as the number of flags on a single message or the + number of flags used in a mailbox. + + C: m STORE 42 FLAGS f1 f2 f3 f4 f5 ... f250 + S: m NO [LIMIT] At most 32 flags in one mailbox supported + + OVERQUOTA + The user would be over quota after the operation. (The user + may or may not be over quota already.) + + Note that if the server sends OVERQUOTA but doesn't support the + IMAP QUOTA extension defined by [RFC2087], then there is a + quota, but the client cannot find out what the quota is. + + C: n1 uid copy 1:* oldmail + S: n1 NO [OVERQUOTA] Sorry + + C: n2 uid copy 1:* oldmail + S: n2 OK [OVERQUOTA] You are now over your soft quota + + + + + +Gulbrandsen Standards Track [Page 5] + +RFC 5530 IMAP Response Codes May 2009 + + + ALREADYEXISTS + The operation attempts to create something that already exists, + such as when the CREATE or RENAME directories attempt to create + a mailbox and there is already one of that name. + + C: o RENAME this that + S: o NO [ALREADYEXISTS] Mailbox "that" already exists + + NONEXISTENT + The operation attempts to delete something that does not exist. + Similar to ALREADYEXISTS. + + C: p RENAME this that + S: p NO [NONEXISTENT] No such mailbox + +4. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [RFC5234]. [RFC3501] defines + the non-terminal "resp-text-code". + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of upper or lowercase characters to define + token strings is for editorial clarity only. + + resp-text-code =/ "UNAVAILABLE" / "AUTHENTICATIONFAILED" / + "AUTHORIZATIONFAILED" / "EXPIRED" / + "PRIVACYREQUIRED" / "CONTACTADMIN" / "NOPERM" / + "INUSE" / "EXPUNGEISSUED" / "CORRUPTION" / + "SERVERBUG" / "CLIENTBUG" / "CANNOT" / + "LIMIT" / "OVERQUOTA" / "ALREADYEXISTS" / + "NONEXISTENT" + +5. Security Considerations + + Revealing information about a passphrase to unauthenticated IMAP + clients causes bad karma. + + Response codes are easier to parse than human-readable text. This + can amplify the consequences of an information leak. For example, + selecting a mailbox can fail because the mailbox doesn't exist, + because the user doesn't have the "l" right (right to know the + mailbox exists) or "r" right (right to read the mailbox). If the + server sent different responses in the first two cases in the past, + only malevolent clients would discover it. With response codes it's + possible, perhaps probable, that benevolent clients will forward the + + + + + +Gulbrandsen Standards Track [Page 6] + +RFC 5530 IMAP Response Codes May 2009 + + + leaked information to the user. Server authors are encouraged to be + particularly careful with the NOPERM and authentication-related + responses. + +6. IANA Considerations + + The IANA has created the IMAP Response Codes registry. The registry + has been populated with the following codes: + + NEWNAME RFC 2060 (obsolete) + REFERRAL RFC 2221 + ALERT RFC 3501 + BADCHARSET RFC 3501 + PARSE RFC 3501 + PERMANENTFLAGS RFC 3501 + READ-ONLY RFC 3501 + READ-WRITE RFC 3501 + TRYCREATE RFC 3501 + UIDNEXT RFC 3501 + UIDVALIDITY RFC 3501 + UNSEEN RFC 3501 + UNKNOWN-CTE RFC 3516 + UIDNOTSTICKY RFC 4315 + APPENDUID RFC 4315 + COPYUID RFC 4315 + URLMECH RFC 4467 + TOOBIG RFC 4469 + BADURL RFC 4469 + HIGHESTMODSEQ RFC 4551 + NOMODSEQ RFC 4551 + MODIFIED RFC 4551 + COMPRESSIONACTIVE RFC 4978 + CLOSED RFC 5162 + NOTSAVED RFC 5182 + BADCOMPARATOR RFC 5255 + ANNOTATE RFC 5257 + ANNOTATIONS RFC 5257 + TEMPFAIL RFC 5259 + MAXCONVERTMESSAGES RFC 5259 + MAXCONVERTPARTS RFC 5259 + NOUPDATE RFC 5267 + METADATA RFC 5464 + NOTIFICATIONOVERFLOW RFC 5465 + BADEVENT RFC 5465 + UNDEFINED-FILTER RFC 5466 + UNAVAILABLE RFC 5530 + AUTHENTICATIONFAILED RFC 5530 + AUTHORIZATIONFAILED RFC 5530 + + + +Gulbrandsen Standards Track [Page 7] + +RFC 5530 IMAP Response Codes May 2009 + + + EXPIRED RFC 5530 + PRIVACYREQUIRED RFC 5530 + CONTACTADMIN RFC 5530 + NOPERM RFC 5530 + INUSE RFC 5530 + EXPUNGEISSUED RFC 5530 + CORRUPTION RFC 5530 + SERVERBUG RFC 5530 + CLIENTBUG RFC 5530 + CANNOT RFC 5530 + LIMIT RFC 5530 + OVERQUOTA RFC 5530 + ALREADYEXISTS RFC 5530 + NONEXISTENT RFC 5530 + + The new registry can be extended by sending a registration request to + IANA. IANA will forward this request to a Designated Expert, + appointed by the responsible IESG Area Director, CCing it to the IMAP + Extensions mailing list at (or a successor + designated by the Area Director). After either allowing 30 days for + community input on the IMAP Extensions mailing list or a successful + IETF Last Call, the expert will determine the appropriateness of the + registration request and either approve or disapprove the request by + sending a notice of the decision to the requestor, CCing the IMAP + Extensions mailing list and IANA. A denial notice must be justified + by an explanation, and, in cases where it is possible, concrete + suggestions on how the request can be modified so as to become + acceptable should be provided. + + For each response code, the registry contains a list of relevant RFCs + that describe (or extend) the response code and an optional response + code status description, such as "obsolete" or "reserved to prevent + collision with deployed software". (Note that in the latter case, + the RFC number can be missing.) Presence of the response code status + description means that the corresponding response code is NOT + RECOMMENDED for widespread use. + + The intention is that any future allocation will be accompanied by a + published RFC (including direct submissions to the RFC Editor). But + in order to allow for the allocation of values prior to the RFC being + approved for publication, the Designated Expert can approve + allocations once it seems clear that an RFC will be published, for + example, before requesting IETF LC for the document. + + The Designated Expert can also approve registrations for response + codes used in deployed software when no RFC exists. Such + registrations must be marked as "reserved to prevent collision with + deployed software". + + + +Gulbrandsen Standards Track [Page 8] + +RFC 5530 IMAP Response Codes May 2009 + + + Response code registrations may not be deleted; response codes that + are no longer believed appropriate for use (for example, if there is + a problem with the syntax of said response code or if the + specification describing it was moved to Historic) should be marked + "obsolete" in the registry, clearly marking the lists published by + IANA. + +7. Acknowledgements + + Peter Coates, Mark Crispin, Philip Guenther, Alexey Melnikov, Ken + Murchison, Chris Newman, Timo Sirainen, Philip Van Hoof, Dale + Wiggins, and Sarah Wilkin helped with this document. + +8. References + +8.1. Normative References + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", STD 68, RFC 5234, January + 2008. + +9. Informative References + + [RFC2087] Myers, J., "IMAP4 QUOTA extension", RFC 2087, January + 1997. + + [RFC2180] Gahrns, M., "IMAP4 Multi-Accessed Mailbox Practice", RFC + 2180, July 1997. + + [RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) Extension", + RFC 4314, December 2005. + +Author's Address + + Arnt Gulbrandsen + Oryx Mail Systems GmbH + Schweppermannstr. 8 + D-81671 Muenchen + Germany + + Fax: +49 89 4502 9758 + EMail: arnt@oryx.com + + + + + + +Gulbrandsen Standards Track [Page 9] + diff --git a/docs/rfcs/rfc5738.IMAP_UTF8.txt b/docs/rfcs/rfc5738.IMAP_UTF8.txt new file mode 100644 index 0000000..2b5daaa --- /dev/null +++ b/docs/rfcs/rfc5738.IMAP_UTF8.txt @@ -0,0 +1,843 @@ + + + + + + +Network Working Group P. Resnick +Request for Comments: 5738 Qualcomm Incorporated +Updates: 3501 C. Newman +Category: Experimental Sun Microsystems + March 2010 + + + IMAP Support for UTF-8 + +Abstract + + This specification extends the Internet Message Access Protocol + version 4rev1 (IMAP4rev1) to support UTF-8 encoded international + characters in user names, mail addresses, and message headers. + +Status of This Memo + + This document is not an Internet Standards Track specification; it is + published for examination, experimental implementation, and + evaluation. + + This document defines an Experimental Protocol for the Internet + community. 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). Not + all documents approved by the IESG are a candidate for any level of + Internet Standard; see Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc5738. + +Copyright Notice + + Copyright (c) 2010 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 + (http://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 Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + + +Resnick & Newman Experimental [Page 1] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + + This document may contain material from IETF Documents or IETF + Contributions published or made publicly available before November + 10, 2008. The person(s) controlling the copyright in some of this + material may not have granted the IETF Trust the right to allow + modifications of such material outside the IETF Standards Process. + Without obtaining an adequate license from the person(s) controlling + the copyright in such materials, this document may not be modified + outside the IETF Standards Process, and derivative works of it may + not be created outside the IETF Standards Process, except to format + it for publication as an RFC or to translate it into languages other + than English. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 + 3. UTF8=ACCEPT IMAP Capability . . . . . . . . . . . . . . . . . 3 + 3.1. IMAP UTF-8 Quoted Strings . . . . . . . . . . . . . . . . 3 + 3.2. UTF8 Parameter to SELECT and EXAMINE . . . . . . . . . . . 5 + 3.3. UTF-8 LIST and LSUB Responses . . . . . . . . . . . . . . 5 + 3.4. UTF-8 Interaction with IMAP4 LIST Command Extensions . . . 6 + 3.4.1. UTF8 and UTF8ONLY LIST Selection Options . . . . . . . 6 + 3.4.2. UTF8 LIST Return Option . . . . . . . . . . . . . . . 6 + 4. UTF8=APPEND Capability . . . . . . . . . . . . . . . . . . . . 7 + 5. UTF8=USER Capability . . . . . . . . . . . . . . . . . . . . . 7 + 6. UTF8=ALL Capability . . . . . . . . . . . . . . . . . . . . . 7 + 7. UTF8=ONLY Capability . . . . . . . . . . . . . . . . . . . . . 8 + 8. Up-Conversion Server Requirements . . . . . . . . . . . . . . 8 + 9. Issues with UTF-8 Header Mailstore . . . . . . . . . . . . . . 9 + 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 + 11. Security Considerations . . . . . . . . . . . . . . . . . . . 11 + 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 12.1. Normative References . . . . . . . . . . . . . . . . . . . 11 + 12.2. Informative References . . . . . . . . . . . . . . . . . . 13 + Appendix A. Design Rationale . . . . . . . . . . . . . . . . . . 14 + Appendix B. Examples Demonstrating Relationships between + UTF8= Capabilities . . . . . . . . . . . . . . . . . 15 + Appendix C. Acknowledgments . . . . . . . . . . . . . . . . . . . 15 + + + + + + + + + + + + + +Resnick & Newman Experimental [Page 2] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + +1. Introduction + + This specification extends IMAP4rev1 [RFC3501] to permit UTF-8 + [RFC3629] in headers as described in "Internationalized Email + Headers" [RFC5335]. It also adds a mechanism to support mailbox + names, login names, and passwords using the UTF-8 charset. This + specification creates five new IMAP capabilities to allow servers to + advertise these new extensions, along with two new IMAP LIST + selection options and a new IMAP LIST return option. + +2. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" + in this document are to be interpreted as defined in "Key words for + use in RFCs to Indicate Requirement Levels" [RFC2119]. + + The formal syntax uses the Augmented Backus-Naur Form (ABNF) + [RFC5234] notation including the core rules defined in Appendix B of + [RFC5234]. In addition, rules from IMAP4rev1 [RFC3501], UTF-8 + [RFC3629], "Collected Extensions to IMAP4 ABNF" [RFC4466], and IMAP4 + LIST Command Extensions [RFC5258] are also referenced. + + In examples, "C:" and "S:" indicate lines sent by the client and + server, respectively. If a single "C:" or "S:" label applies to + multiple lines, then the line breaks between those lines are for + editorial clarity only and are not part of the actual protocol + exchange. + +3. UTF8=ACCEPT IMAP Capability + + The "UTF8=ACCEPT" capability indicates that the server supports UTF-8 + quoted strings, the "UTF8" parameter to SELECT and EXAMINE, and UTF-8 + responses from the LIST and LSUB commands. + + A client MUST use the "ENABLE UTF8=ACCEPT" command (defined in + [RFC5161]) to indicate to the server that the client accepts UTF-8 + quoted-strings. The "ENABLE UTF8=ACCEPT" command MUST only be used + in the authenticated state. (Note that the "UTF8=ONLY" capability + described in Section 7 and the "UTF8=ALL" capability described in + Section 6 imply the "UTF8=ACCEPT" capability. See additional + information in these sections.) + +3.1. IMAP UTF-8 Quoted Strings + + The IMAP4rev1 [RFC3501] base specification forbids the use of 8-bit + characters in atoms or quoted strings. Thus, a UTF-8 string can only + be sent as a literal. This can be inconvenient from a coding + standpoint, and unless the server offers IMAP4 non-synchronizing + + + +Resnick & Newman Experimental [Page 3] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + + literals [RFC2088], this requires an extra round trip for each UTF-8 + string sent by the client. When the IMAP server advertises the + "UTF8=ACCEPT" capability, it informs the client that it supports + native UTF-8 quoted-strings with the following syntax: + + string =/ utf8-quoted + + utf8-quoted = "*" DQUOTE *UQUOTED-CHAR DQUOTE + + UQUOTED-CHAR = QUOTED-CHAR / UTF8-2 / UTF8-3 / UTF8-4 + ; UTF8-2, UTF8-3, and UTF8-4 are as defined in RFC 3629 + + When this quoting mechanism is used by the client (specifically an + octet sequence beginning with *" and ending with "), then the server + MUST reject octet sequences with the high bit set that fail to comply + with the formal syntax in [RFC3629] with a BAD response. + + The IMAP server MUST NOT send utf8-quoted syntax to the client unless + the client has indicated support for that syntax by using the "ENABLE + UTF8=ACCEPT" command. + + If the server advertises the "UTF8=ACCEPT" capability, the client MAY + use utf8-quoted syntax with any IMAP argument that permits a string + (including astring and nstring). However, if characters outside the + US-ASCII repertoire are used in an inappropriate place, the results + would be the same as if other syntactically valid but semantically + invalid characters were used. For example, if the client includes + UTF-8 characters in the user or password arguments (and the server + has not advertised "UTF8=USER"), the LOGIN command will fail as it + would with any other invalid user name or password. Specific cases + where UTF-8 characters are permitted or not permitted are described + in the following paragraphs. + + All IMAP servers that advertise the "UTF8=ACCEPT" capability SHOULD + accept UTF-8 in mailbox names, and those that also support the + "Mailbox International Naming Convention" described in RFC 3501, + Section 5.1.3 MUST accept utf8-quoted mailbox names and convert them + to the appropriate internal format. Mailbox names MUST comply with + the Net-Unicode Definition (Section 2 of [RFC5198]) with the specific + exception that they MUST NOT contain control characters (0000-001F, + 0080-009F), delete (007F), line separator (2028), or paragraph + separator (2029). + + An IMAP client MUST NOT issue a SEARCH command that uses a mixture of + utf8-quoted syntax and a SEARCH CHARSET other than UTF-8. If an IMAP + server receives such a SEARCH command, it SHOULD reject the command + with a BAD response (due to the conflicting charset labels). + + + + +Resnick & Newman Experimental [Page 4] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + +3.2. UTF8 Parameter to SELECT and EXAMINE + + The "UTF8=ACCEPT" capability also indicates that the server supports + the "UTF8" parameter to SELECT and EXAMINE. When a mailbox is + selected with the "UTF8" parameter, it alters the behavior of all + IMAP commands related to message sizes, message headers, and MIME + body headers so they refer to the message with UTF-8 headers. If the + mailstore is not UTF-8 header native and the SELECT or EXAMINE + command with UTF-8 header modifier succeeds, then the server MUST + return results as if the mailstore were UTF-8 header native with + upconversion requirements as described in Section 8. The server MAY + reject the SELECT or EXAMINE command with the [NOT-UTF-8] response + code, unless the "UTF8=ALL" or "UTF8=ONLY" capability is advertised. + + Servers MAY include mailboxes that can only be selected or examined + if the "UTF8" parameter is provided. However, such mailboxes MUST + NOT be included in the output of an unextended LIST, LSUB, or + equivalent command. If a client attempts to SELECT or EXAMINE such + mailboxes without the "UTF8" parameter, the server MUST reject the + command with a [UTF-8-ONLY] response code. As a result, such + mailboxes will not be accessible by IMAP clients written prior to + this specification and are discouraged unless the server advertises + "UTF8=ONLY" or the server implements IMAP4 LIST Command Extensions + [RFC5258]. + + utf8-select-param = "UTF8" + ;; Conforms to from RFC 4466 + + C: a SELECT newmailbox (UTF8) + S: ... + S: a OK SELECT completed + C: b FETCH 1 (SIZE ENVELOPE BODY) + S: ... < UTF-8 header native results > + S: b OK FETCH completed + + C: c EXAMINE legacymailbox (UTF8) + S: c NO [NOT-UTF-8] Mailbox does not support UTF-8 access + + C: d SELECT funky-new-mailbox + S: d NO [UTF-8-ONLY] Mailbox requires UTF-8 client + +3.3. UTF-8 LIST and LSUB Responses + + After an IMAP client successfully issues an "ENABLE UTF8=ACCEPT" + command, the server MUST NOT return in LIST results any mailbox names + to the client following the IMAP4 Mailbox International Naming + Convention. Instead, the server MUST return any mailbox names with + characters outside the US-ASCII repertoire using utf8-quoted syntax. + + + +Resnick & Newman Experimental [Page 5] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + + (The IMAP4 Mailbox International Naming Convention has proved + problematic in the past, so the desire is to make this syntax + obsolete as quickly as possible.) + +3.4. UTF-8 Interaction with IMAP4 LIST Command Extensions + + When an IMAP server advertises both the "UTF8=ACCEPT" capability and + the "LIST-EXTENDED" [RFC5258] capability, the server MUST support the + LIST extensions described in this section. + +3.4.1. UTF8 and UTF8ONLY LIST Selection Options + + The "UTF8" LIST selection option tells the server to include + mailboxes that only support UTF-8 headers in the output of the list + command. The "UTF8ONLY" LIST selection option tells the server to + include all mailboxes that support UTF-8 headers and to exclude + mailboxes that don't support UTF-8 headers. Note that "UTF8ONLY" + implies "UTF8", so it is not necessary for the client to request + both. Use of either selection option will also result in UTF-8 + mailbox names in the result as described in Section 3.3 and implies + the "UTF8" List return option described in Section 3.4.2. + +3.4.2. UTF8 LIST Return Option + + If the client supplies the "UTF8" LIST return option, then the server + MUST include either the "\NoUTF8" or the "\UTF8Only" mailbox + attribute as appropriate. The "\NoUTF8" mailbox attribute indicates + that an attempt to SELECT or EXAMINE that mailbox with the "UTF8" + parameter will fail with a [NOT-UTF-8] response code. The + "\UTF8Only" mailbox attribute indicates that an attempt to SELECT or + EXAMINE that mailbox without the "UTF8" parameter will fail with a + [UTF-8-ONLY] response code. Note that computing this information may + be expensive on some server implementations, so this return option + should not be used unless necessary. + + The ABNF [RFC5234] for these LIST extensions follows: + + list-select-independent-opt =/ "UTF8" + + list-select-base-opt =/ "UTF8ONLY" + + mbx-list-oflag =/ "\NoUTF8" / "\UTF8Only" + + return-option =/ "UTF8" + + resp-text-code =/ "NOT-UTF-8" / "UTF-8-ONLY" + + + + + +Resnick & Newman Experimental [Page 6] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + +4. UTF8=APPEND Capability + + If the "UTF8=APPEND" capability is advertised, then the server + accepts UTF-8 headers in the APPEND command message argument. A + client that sends a message with UTF-8 headers to the server MUST + send them using the "UTF8" APPEND data extension. If the server also + advertises the CATENATE capability (as specified in [RFC4469]), the + client can use the same data extension to include such a message in a + CATENATE message part. The ABNF for the APPEND data extension and + CATENATE extension follows: + + utf8-literal = "UTF8" SP "(" literal8 ")" + + append-data =/ utf8-literal + + cat-part =/ utf8-literal + + A server that advertises "UTF8=APPEND" has to comply with the + requirements of the IMAP base specification and [RFC5322] for message + fetching. Mechanisms for 7-bit downgrading to help comply with the + standards are discussed in Downgrading mechanism for + Internationalized eMail Address (IMA) [RFC5504]. + + IMAP servers that do not advertise the "UTF8=APPEND" or "UTF8=ONLY" + capability SHOULD reject an APPEND command that includes any 8-bit in + the message headers with a "NO" response. + + Note that the "UTF8=ONLY" capability described in Section 7 implies + the "UTF8=APPEND" capability. See additional information in that + section. + +5. UTF8=USER Capability + + If the "UTF8=USER" capability is advertised, that indicates the + server accepts UTF-8 user names and passwords and applies SASLprep + [RFC4013] to both arguments of the LOGIN command. The server MUST + reject UTF-8 that fails to comply with the formal syntax in RFC 3629 + [RFC3629] or if it encounters Unicode characters listed in Section + 2.3 of SASLprep RFC 4013 [RFC4013]. + +6. UTF8=ALL Capability + + The "UTF8=ALL" capability indicates all server mailboxes support + UTF-8 headers. Specifically, SELECT and EXAMINE with the "UTF8" + parameter will never fail with a [NOT-UTF-8] response code. + + + + + + +Resnick & Newman Experimental [Page 7] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + + Note that the "UTF8=ONLY" capability described in Section 7 implies + the "UTF8=ALL" capability. See additional information in that + section. + + Note that the "UTF8=ALL" capability implies the "UTF8=ACCEPT" + capability. + +7. UTF8=ONLY Capability + + The "UTF8=ONLY" capability permits an IMAP server to advertise that + it does not support the international mailbox name convention + (modified UTF-7), and does not permit selection or examination of any + mailbox unless the "UTF8" parameter is provided. As this is an + incompatible change to IMAP, a clear warning is necessary. IMAP + clients that find implementation of the "UTF8=ONLY" capability + problematic are encouraged to at least detect the "UTF8=ONLY" + capability and provide an informative error message to the end-user. + + When an IMAP mailbox internally uses UTF-8 header native storage, the + down-conversion step is necessary to permit selection or examination + of the mailbox in a backwards compatible fashion will become more + difficult to support. Although it is hoped that deployed IMAP + servers will not advertise "UTF8=ONLY" for some years, this + capability is intended to minimize the disruption when legacy support + finally goes away. + + The "UTF8=ONLY" capability implies the "UTF8=ACCEPT" capability, the + "UTF8=ALL" capability, and the "UTF8=APPEND" capability. A server + that advertises "UTF8=ONLY" need not advertise the three implicit + capabilities. + +8. Up-Conversion Server Requirements + + When an IMAP4 server uses a traditional mailbox format that includes + 7-bit headers and it chooses to permit access to that mailbox with + the "UTF8" parameter, it MUST support minimal up-conversion as + described in this section. + + The server MUST support up-conversion of the following address + header-fields in the message header: From, Sender, To, CC, Bcc, + Resent-From, Resent-Sender, Resent-To, Resent-CC, Resent-Bcc, and + Reply-To. This up-conversion MUST include address local-parts in + fields downgraded according to [RFC5504], address domains encoded + according to Internationalizing Domain Names in Applications (IDNA) + [RFC3490], and MIME header encoding [RFC2047] of display-names and + any [RFC5322] comments. + + + + + +Resnick & Newman Experimental [Page 8] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + + The following charsets MUST be supported for up-conversion of MIME + header encoding [RFC2047]: UTF-8, US-ASCII, ISO-8859-1, ISO-8859-2, + ISO-8859-3, ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, + ISO-8859-8, ISO-8859-9, ISO-8859-10, ISO-8859-14, and ISO-8859-15. + If the server supports other charsets in IMAP SEARCH or IMAP CONVERT + [RFC5259], it SHOULD also support those charsets in this conversion. + + Up-conversion of MIME header encoding of the following headers MUST + also be implemented: Subject, Date ([RFC5322] comments only), + Comments, Keywords, and Content-Description. + + Server implementations also SHOULD up-convert all MIME body headers + [RFC2045], SHOULD up-convert or remove the deprecated (and misused) + "name" parameter [RFC1341] on Content-Type, and MUST up-convert the + Content-Disposition [RFC2183] "filename" parameter, except when any + of these are contained within a multipart/signed MIME body part (see + below). These parameters can be encoded using the standard MIME + parameter encoding [RFC2231] mechanism, or via non-standard use of + MIME header encoding [RFC2047] in quoted strings. + + The IMAP server MUST NOT perform up-conversion of headers and content + of multipart/signed, as well as Original-Recipient and Return-Path. + +9. Issues with UTF-8 Header Mailstore + + When an IMAP server uses a mailbox format that supports UTF-8 headers + and it permits selection or examination of that mailbox without the + "UTF8" parameter, it is the responsibility of the server to comply + with the IMAP4rev1 base specification [RFC3501] and [RFC5322] with + respect to all header information transmitted over the wire. + Mechanisms for 7-bit downgrading to help comply with the standards + are discussed in "Downgrading Mechanism for Email Address + Internationalization" [RFC5504]. + + An IMAP server with a mailbox that supports UTF-8 headers MUST comply + with the protocol requirements implicit from Section 8. However, the + code necessary for such compliance need not be part of the IMAP + server itself in this case. For example, the minimal required up- + conversion could be performed when a message is inserted into the + IMAP-accessible mailbox. + +10. IANA Considerations + + This adds five new capabilities ("UTF8=ACCEPT", "UTF8=USER", + "UTF8=APPEND", "UTF8=ALL", and "UTF8=ONLY") to the IMAP4rev1 + Capabilities registry [RFC3501]. + + + + + +Resnick & Newman Experimental [Page 9] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + + This adds two new IMAP4 list selection options and one new IMAP4 list + return option. + + 1. LIST-EXTENDED option name: UTF8 + + LIST-EXTENDED option type: SELECTION + + Implied return options(s): UTF8 + + LIST-EXTENDED option description: Causes the LIST response to + include mailboxes that mandate the UTF8 SELECT/EXAMINE parameter. + + Published specification: RFC 5738, Section 3.4.1 + + Security considerations: RFC 5738, Section 11 + + Intended usage: COMMON + + Person and email address to contact for further information: see + the Authors' Addresses at the end of this specification + + Owner/Change controller: iesg@ietf.org + + 2. LIST-EXTENDED option name: UTF8ONLY + + LIST-EXTENDED option type: SELECTION + + Implied return options(s): UTF8 + + LIST-EXTENDED option description: Causes the LIST response to + include mailboxes that mandate the UTF8 SELECT/EXAMINE parameter + and exclude mailboxes that do not support the UTF8 SELECT/EXAMINE + parameter. + + Published specification: RFC 5738, Section 3.4.1 + + Security considerations: RFC 5738, Section 11 + + Intended usage: COMMON + + Person and email address to contact for further information: see + the Authors' Addresses at the end of this specification + + Owner/Change controller: iesg@ietf.org + + + + + + + +Resnick & Newman Experimental [Page 10] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + + 3. LIST-EXTENDED option name: UTF8 + + LIST-EXTENDED option type: RETURN + + Implied return options(s): none + + LIST-EXTENDED option description: Causes the LIST response to + include \NoUTF8 and \UTF8Only mailbox attributes. + + Published specification: RFC 5738, Section 3.4.1 + + Security considerations: RFC 5738, Section 11 + + Intended usage: COMMON + + Person and email address to contact for further information: see + the Authors' Addresses at the end of this specification + + Owner/Change controller: iesg@ietf.org + +11. Security Considerations + + The security considerations of UTF-8 [RFC3629] and SASLprep [RFC4013] + apply to this specification, particularly with respect to use of + UTF-8 in user names and passwords. Otherwise, this is not believed + to alter the security considerations of IMAP4rev1. + +12. References + +12.1. Normative References + + [RFC1341] Borenstein, N. and N. Freed, "MIME (Multipurpose Internet + Mail Extensions): Mechanisms for Specifying and Describing + the Format of Internet Message Bodies", RFC 1341, + June 1992. + + [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail + Extensions (MIME) Part One: Format of Internet Message + Bodies", RFC 2045, November 1996. + + [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) + Part Three: Message Header Extensions for Non-ASCII Text", + RFC 2047, November 1996. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + + + + +Resnick & Newman Experimental [Page 11] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + + [RFC2183] Troost, R., Dorner, S., and K. Moore, "Communicating + Presentation Information in Internet Messages: The + Content-Disposition Header Field", RFC 2183, August 1997. + + [RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and Encoded + Word Extensions: + Character Sets, Languages, and Continuations", RFC 2231, + November 1997. + + [RFC3490] Faltstrom, P., Hoffman, P., and A. Costello, + "Internationalizing Domain Names in Applications (IDNA)", + RFC 3490, March 2003. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. + + [RFC4013] Zeilenga, K., "SASLprep: Stringprep Profile for User Names + and Passwords", RFC 4013, February 2005. + + [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 + ABNF", RFC 4466, April 2006. + + [RFC4469] Resnick, P., "Internet Message Access Protocol (IMAP) + CATENATE Extension", RFC 4469, April 2006. + + [RFC5161] Gulbrandsen, A. and A. Melnikov, "The IMAP ENABLE + Extension", RFC 5161, March 2008. + + [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network + Interchange", RFC 5198, March 2008. + + [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + + [RFC5258] Leiba, B. and A. Melnikov, "Internet Message Access + Protocol version 4 - LIST Command Extensions", RFC 5258, + June 2008. + + [RFC5259] Melnikov, A. and P. Coates, "Internet Message Access + Protocol - CONVERT Extension", RFC 5259, July 2008. + + [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, + October 2008. + + + + + +Resnick & Newman Experimental [Page 12] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + + [RFC5335] Abel, Y., "Internationalized Email Headers", RFC 5335, + September 2008. + + [RFC5504] Fujiwara, K. and Y. Yoneya, "Downgrading Mechanism for + Email Address Internationalization", RFC 5504, March 2009. + +12.2. Informative References + + [RFC2049] Freed, N. and N. Borenstein, "Multipurpose Internet Mail + Extensions (MIME) Part Five: Conformance Criteria and + Examples", RFC 2049, November 1996. + + [RFC2088] Myers, J., "IMAP4 non-synchronizing literals", RFC 2088, + January 1997. + + [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and + Languages", BCP 18, RFC 2277, January 1998. + + [RFC5721] Gellens, R. and C. Newman, "POP3 Support for UTF-8", + RFC 5721, February 2010. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Resnick & Newman Experimental [Page 13] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + +Appendix A. Design Rationale + + This non-normative section discusses the reasons behind some of the + design choices in the above specification. + + The basic approach of advertising the ability to access a mailbox in + UTF-8 mode is intended to permit graceful upgrade, including servers + that support multiple mailbox formats. In particular, it would be + undesirable to force conversion of an entire server mailstore to + UTF-8 headers, so being able to phase-in support for new mailboxes + and gradually migrate old mailboxes is permitted by this design. + + "UTF8=USER" is optional because many identity systems are US-ASCII + only, so it's helpful to inform the client up front that UTF-8 won't + work. + + "UTF8=APPEND" is optional because it effectively requires IMAP server + support for down-conversion, which is a much more complex operation + than up-conversion. + + The "UTF8=ONLY" mechanism simplifies diagnosis of interoperability + problems when legacy support goes away. In the situation where + backwards compatibility is broken anyway, just-send-UTF-8 IMAP has + the advantage that it might work with some legacy clients. However, + the difficulty of diagnosing interoperability problems caused by a + just-send-UTF-8 IMAP mechanism is the reason the "UTF8=ONLY" + capability mechanism was chosen. + + The up-conversion requirements are designed to balance the desire to + deprecate and eventually eliminate complicated encodings (like MIME + header encodings) without creating a significant deployment burden + for servers. As IMAP4 servers already require a MIME parser, this + includes additional server up-conversion requirements not present in + POP3 Support for UTF-8 [RFC5721]. + + The set of mandatory charsets comes from two sources: MIME + requirements [RFC2049] and IETF Policy on Character Sets [RFC2277]. + Including a requirement to up-convert widely deployed encoded + ideographic charsets to UTF-8 would be reasonable for most scenarios, + but may require unacceptable table sizes for some embedded devices. + The open-ended recommendation to support widely deployed charsets + avoids the political ramifications of attempting to list such + charsets. The authors believe market forces, existing open-source + software, and public conversion tables are sufficient to deploy the + appropriate charsets. + + + + + + +Resnick & Newman Experimental [Page 14] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + +Appendix B. Examples Demonstrating Relationships between UTF8= + Capabilities + + + UTF8=ACCEPT UTF8=USER UTF8=APPEND + UTF8=ACCEPT UTF8=ALL + UTF8=ALL ; Note, same as above + UTF8=ACCEPT UTF8=USER UTF8=APPEND UTF8=ALL UTF8=ONLY + UTF8=USER UTF8=ONLY ; Note, same as above + +Appendix C. Acknowledgments + + The authors wish to thank the participants of the EAI working group + for their contributions to this document with particular thanks to + Harald Alvestrand, David Black, Randall Gellens, Arnt Gulbrandsen, + Kari Hurtta, John Klensin, Xiaodong Lee, Charles Lindsey, Alexey + Melnikov, Subramanian Moonesamy, Shawn Steele, Daniel Taharlev, and + Joseph Yee for their specific contributions to the discussion. + +Authors' Addresses + + Pete Resnick + Qualcomm Incorporated + 5775 Morehouse Drive + San Diego, CA 92121-1714 + US + + Phone: +1 858 651 4478 + EMail: presnick@qualcomm.com + URI: http://www.qualcomm.com/~presnick/ + + Chris Newman + Sun Microsystems + 800 Royal Oaks + Monrovia, CA 91016 + US + + EMail: chris.newman@sun.com + + + + + + + + + + + + + +Resnick & Newman Experimental [Page 15] + diff --git a/docs/rfcs/rfc5788.IMAP4_Keyword_registry.txt b/docs/rfcs/rfc5788.IMAP4_Keyword_registry.txt new file mode 100644 index 0000000..fe0de70 --- /dev/null +++ b/docs/rfcs/rfc5788.IMAP4_Keyword_registry.txt @@ -0,0 +1,619 @@ + + + + + + +Internet Engineering Task Force (IETF) A. Melnikov +Request for Comments: 5788 D. Cridland +Category: Standards Track Isode Limited +ISSN: 2070-1721 March 2010 + + + IMAP4 Keyword Registry + +Abstract + + The aim of this document is to establish a new IANA registry for IMAP + keywords and to define a procedure for keyword registration, in order + to improve interoperability between different IMAP clients. + +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 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc5788. + +Copyright Notice + + Copyright (c) 2010 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 + (http://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 Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + + + + + + + +Melnikov & Cridland Standards Track [Page 1] + +RFC 5788 IMAP4 Keyword Registry March 2010 + + +Table of Contents + + 1. Introduction ....................................................2 + 2. Conventions Used in This Document ...............................2 + 3. IANA Considerations .............................................3 + 3.1. Review Guidelines for the Designated Expert Reviewer .......4 + 3.2. Comments on IMAP Keywords' Registrations ...................5 + 3.3. Change Control .............................................5 + 3.4. Initial Registrations ......................................6 + 3.4.1. $MDNSent IMAP Keyword Registration ..................6 + 3.4.2. $Forwarded IMAP Keyword Registration ................7 + 3.4.3. $SubmitPending IMAP Keyword Registration ............8 + 3.4.4. $Submitted IMAP Keyword Registration ................9 + 4. Security Considerations ........................................10 + 5. Acknowledgements ...............................................10 + 6. References .....................................................10 + 6.1. Normative References ......................................10 + 6.2. Informative References ....................................11 + +1. Introduction + + IMAP keywords [RFC3501] are boolean named flags that can be used by + clients to annotate messages in an IMAP mailbox. Although IMAP + keywords are an optional feature of IMAP, the majority of IMAP + servers can store arbitrary keywords. Many mainstream IMAP clients + use a limited set of specific keywords, and some can manage (create, + edit, display) arbitrary IMAP keywords. + + Over the years, some IMAP keywords have become de-facto standards, + with some specific semantics associated with them. In some cases, + different client implementors decided to define and use keywords with + different names, but the same semantics. Some server implementors + decided to map such keywords automatically in order to improve cross- + client interoperability. + + In other cases, the same keywords have been used with different + semantics, thus causing interoperability problems. + + This document attempts to prevent further incompatible uses of IMAP + keywords by establishing an "IMAP Keywords" registry and allocating a + special prefix for standardized keywords. + +2. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [Kwds]. + + + + +Melnikov & Cridland Standards Track [Page 2] + +RFC 5788 IMAP4 Keyword Registry March 2010 + + +3. IANA Considerations + + IANA has established a new registry for IMAP keywords. + + Registration of an IMAP keyword is requested by filling in the + following template and following the instructions on the IANA pages + for the registry to submit it to IANA: + + Subject: Registration of IMAP keyword X + + IMAP keyword name: + + Purpose (description): + + Private or Shared on a server: (One of PRIVATE, SHARED, or BOTH. + PRIVATE means that each different + user has a distinct copy of the + keyword. SHARED means that all + different users see the same value of + the keyword. BOTH means that an IMAP + server can have the keyword as either + private or shared.) + + Is it an advisory keyword or may it cause an automatic action: + + When/by whom the keyword is set/cleared: + + Related keywords: (for example, "mutually exclusive with keywords Y + and Z") + + Related IMAP capabilities: + + Security considerations: + + Published specification (recommended): + + Person & email address to contact for further information: + + Intended usage: (One of COMMON, LIMITED USE, or DEPRECATED (i.e., + not recommended for use)) + + Owner/Change controller: (MUST be "IESG" for any "common use" + keyword registration specified in an IETF + Review document. See definition of "common + use" below in this section. When the + Owner/Change controller is not a + Standardization Organization, the + registration request MUST make it clear if + + + +Melnikov & Cridland Standards Track [Page 3] + +RFC 5788 IMAP4 Keyword Registry March 2010 + + + the registration is controlled by a + company, or the individual performing the + registration.) + + Note: (Any other information that the author deems interesting + may be added here, for example, if the keyword(s) is + supported by existing clients.) + + Registration of an IMAP keyword requires Expert Review [RFC5226]. + Registration of any IMAP keyword is initiated by posting a + registration request to the Message Organization WG mailing list + (or its replacement as chosen by the responsible + Application Area Director) and CCing IANA (). After + allowing for at least two weeks for community input on the designated + mailing list, the expert will determine the appropriateness of the + registration request and either approve or disapprove the request + with notice to the requestor, the mailing list, and IANA. Any + refusal must come with a clear explanation. + + The IESG appoints one or more Expert Reviewers for the IMAP keyword + registry established by this document. + + The Expert Reviewer should strive for timely reviews. The Expert + Reviewer should take no longer than six weeks to make and announce + the decision, or notify the mailing list that more time is required. + + Decisions (or lack of) made by an Expert Reviewer can be first + appealed to Application Area Directors and, if the appellant is not + satisfied with the response, to the full IESG. + + There are two types of IMAP keywords in the "IMAP Keywords" registry: + intended for "common use" and vendor-/organization-specific use (also + known as "limited use"). An IMAP keyword is said to be for "common + use" if it is reasonably expected to be implemented in at least two + independent client implementations. The two types of IMAP keywords + have different levels of requirements for registration (see below). + +3.1. Review Guidelines for the Designated Expert Reviewer + + Expert Reviewers should focus on the following requirements. + + Registration of a vendor-/organization-specific ("limited use") IMAP + keyword is easier. The Expert Reviewer only needs to check that the + requested name doesn't conflict with an already registered name, and + that the name is not too generic, misleading, etc. The Expert + Reviewer MAY request the IMAP keyword name change before approving + + + + + +Melnikov & Cridland Standards Track [Page 4] + +RFC 5788 IMAP4 Keyword Registry March 2010 + + + the registration. The Expert Reviewer SHOULD refuse a registration + if there is an already registered IMAP keyword that serves the same + purpose, but has a different name. + + When registering an IMAP keyword for "common use", the Expert + Reviewer performs the checks described for vendor-/ + organization-specific IMAP keywords, plus additional checks as + detailed below. + + Keywords intended for "common use" SHOULD start with the "$" prefix. + (Note that this is a SHOULD because some of the commonly used IMAP + keywords in widespread use don't follow this convention.) + + IMAP keywords intended for "common use" SHOULD be standardized in + IETF Review [RFC5226] documents. (Note that IETF Review documents + still require Expert Review.) + + Values in the "IMAP Keywords" IANA registry intended for "common use" + must be clearly documented and likely to ensure interoperability. + They must be useful, not harmful to the Internet. In cases when an + IMAP keyword being registered is already deployed, Expert Reviewers + should favor registering it over requiring perfect documentation + and/or requesting a change to the name of the IMAP keyword. + + The Expert Reviewer MAY automatically "upgrade" registration requests + for a "limited use" IMAP keyword to "common use" level. The Expert + Reviewer MAY also request that a registration targeted for "common + use" be registered as "limited use" instead. + +3.2. Comments on IMAP Keywords' Registrations + + Comments on registered IMAP keywords should be sent to both the + "owner" of the mechanism and to the mailing list designated to IMAP + keyword review (see Section 3). This improves the chances of getting + a timely response. + + Submitters of comments may, after a reasonable attempt to contact the + owner and after soliciting comments on the IMAP mailing list, request + the designated Expert Reviewer to attach their comment to the IMAP + keyword registration itself. The procedure is similar to requesting + an Expert Review for the affected keyword. + +3.3. Change Control + + Once an IMAP keyword registration has been published by IANA, the + owner may request a change to its definition. The change request + (including a change to the "intended usage" field) follows the same + procedure as the initial registration request, with the exception of + + + +Melnikov & Cridland Standards Track [Page 5] + +RFC 5788 IMAP4 Keyword Registry March 2010 + + + changes to the "Person & email address to contact for further + information" and "Owner/Change controller" fields. The latter can be + changed by the owner by informing IANA; this can be done without + discussion or review. + + The IESG may reassign responsibility for an IMAP keyword. The most + common case of this will be to enable clarifications to be made to + keywords where the owner of the registration has died, moved out of + contact, or is otherwise unable to make changes that are important to + the community. + + IMAP keyword registrations MUST NOT be deleted; keywords that are no + longer believed appropriate for use can be declared DEPRECATED by a + change to their "intended usage" field. + + The IESG is considered the owner of all "common use" IMAP keywords + that are published in an IETF Review document. + +3.4. Initial Registrations + + IANA has registered the IMAP keywords specified in following + subsections in the registry established by this document. + +3.4.1. $MDNSent IMAP Keyword Registration + + Subject: Registration of IMAP keyword $MDNSent + + + IMAP keyword name: $MDNSent + + Purpose (description): Specifies that a Message Disposition + Notification (MDN) must not be sent for any + message annotated with the $MDNSent IMAP + keyword. + + Private or Shared on a server: SHARED + + Is it an advisory keyword or may it cause an automatic action: + This keyword can cause automatic action by + the client. See [RFC3503] for more details. + + When/by whom the keyword is set/cleared: + This keyword is set by an IMAP client when it + decides to act on an MDN request, or when + uploading a sent or draft message. It can + also be set by a delivery agent. Once set, + the flag SHOULD NOT be cleared. + + + + +Melnikov & Cridland Standards Track [Page 6] + +RFC 5788 IMAP4 Keyword Registry March 2010 + + + Related keywords: None + + Related IMAP capabilities: None + + Security considerations: See Section 6 of [RFC3503] + + Published specification (recommended): [RFC3503] + + Person & email address to contact for further information: + Alexey Melnikov + + Intended usage: COMMON + + Owner/Change controller: IESG + + Note: + +3.4.2. $Forwarded IMAP Keyword Registration + + Subject: Registration of the IMAP keyword $Forwarded + + IMAP keyword name: $Forwarded + + Purpose (description): $Forwarded is used by several IMAP clients to + specify that the message was resent to + another email address, embedded within or + attached to a new message. This keyword is + set by the mail client when it successfully + forwards the message to another email + address. Typical usage of this keyword is to + show a different (or additional) icon for a + message that has been forwarded. + + Private or Shared on a server: BOTH + + Is it an advisory keyword or may it cause an automatic action: + advisory + + When/by whom the keyword is set/cleared: + This keyword can be set by either a delivery + agent or a mail client. Once set, the flag + SHOULD NOT be cleared. Notes: There is no + way to tell if a message with $Forwarded + keyword set was forwarded more than once. + + Related keywords: None + + Related IMAP capabilities: None + + + +Melnikov & Cridland Standards Track [Page 7] + +RFC 5788 IMAP4 Keyword Registry March 2010 + + + Security considerations: A server implementing this keyword as a + shared keyword may disclose that a + confidential message was forwarded. + + Published specification (recommended): [RFC5550] + + Person & email address to contact for further information: + Alexey Melnikov + + Intended usage: COMMON + + Owner/Change controller: IESG + + Note: + +3.4.3. $SubmitPending IMAP Keyword Registration + + Subject: Registration of IMAP keyword $SubmitPending + + IMAP keyword name: $SubmitPending + + Purpose (description): The $SubmitPending IMAP keyword designates + the message as awaiting to be submitted. + This keyword allows storing messages waiting + to be submitted in the same mailbox where + messages that were already submitted and/or + are being edited are stored. + + A message that has both $Submitted and + $SubmitPending IMAP keywords set is a message + being actively submitted. + + Private or Shared on a server: SHARED + + Is it an advisory keyword or may it cause an automatic action: + This keyword can cause automatic action by + the client. See Section 5.10 of [RFC5550] + for more details. + + When/by whom the keyword is set/cleared: + This keyword is set by a mail client when it + decides that the message needs to be sent + out. + + Related keywords: $Submitted + + Related IMAP capabilities: None + + + + +Melnikov & Cridland Standards Track [Page 8] + +RFC 5788 IMAP4 Keyword Registry March 2010 + + + Security considerations: A server implementing this keyword as a + shared keyword may disclose that a + confidential message is scheduled to be + sent out or is being actively sent out. + + Published specification (recommended): [RFC5550] + + Person & email address to contact for further information: + Alexey Melnikov + + Intended usage: COMMON + + Owner/Change controller: IESG + + Note: + +3.4.4. $Submitted IMAP Keyword Registration + + Subject: Registration of IMAP keyword $Submitted + + IMAP keyword name: $Submitted + + Purpose (description): The $Submitted IMAP keyword designates the + message as being sent out. + + A message that has both $Submitted and + $SubmitPending IMAP keywords set is a message + being actively submitted. + + Private or Shared on a server: SHARED + + Is it an advisory keyword or may it cause an automatic action: + This keyword can cause automatic action by + the client. See Section 5.10 of [RFC5550] + for more details. + + When/by whom the keyword is set/cleared: + This keyword is set by a mail client when it + decides to start sending it. + + Related keywords: $SubmitPending + + Related IMAP capabilities: None + + Security considerations: A server implementing this keyword as a + shared keyword may disclose that a + confidential message was sent or is being + actively sent out. + + + +Melnikov & Cridland Standards Track [Page 9] + +RFC 5788 IMAP4 Keyword Registry March 2010 + + + Published specification (recommended): [RFC5550] + + Person & email address to contact for further information: + Alexey Melnikov + + Intended usage: COMMON + + Owner/Change controller: IESG + + Note: + +4. Security Considerations + + IMAP keywords are one of the base IMAP features [RFC3501]. This + document doesn't change their behavior, so it does not add new + security issues. + + A particular IMAP keyword might have specific security + considerations, which are documented in the IMAP keyword + registration template standardized by this document. + +5. Acknowledgements + + The creation of this document was prompted by one of many discussions + on the IMAP mailing list. + + John Neystadt co-authored the first version of this document. + + Special thanks to Chris Newman, David Harris, Lyndon Nerenberg, Mark + Crispin, Samuel Weiler, Alfred Hoenes, Lars Eggert, and Cullen + Jennings for reviewing different versions of this document. However, + all errors or omissions must be attributed to the authors of this + document. + + The authors would also like to thank the developers of Mozilla mail + clients for providing food for thought. + +6. References + +6.1. Normative References + + [Kwds] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + + + + +Melnikov & Cridland Standards Track [Page 10] + +RFC 5788 IMAP4 Keyword Registry March 2010 + + + [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an + IANA Considerations Section in RFCs", BCP 26, RFC 5226, + May 2008. + +6.2. Informative References + + [RFC3503] Melnikov, A., "Message Disposition Notification (MDN) + profile for Internet Message Access Protocol (IMAP)", + RFC 3503, March 2003. + + [RFC5550] Cridland, D., Melnikov, A., and S. Maes, "The Internet + Email to Support Diverse Service Environments (Lemonade) + Profile", RFC 5550, August 2009. + +Authors' Addresses + + Alexey Melnikov + Isode Limited + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: Alexey.Melnikov@isode.com + URI: http://www.melnikov.ca/ + + + Dave Cridland + Isode Limited + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: dave.cridland@isode.com + + + + + + + + + + + + + + + + +Melnikov & Cridland Standards Track [Page 11] + diff --git a/docs/rfcs/rfc5819.IMAP4_extension_Returning_STATUS_info_in_LIST.txt b/docs/rfcs/rfc5819.IMAP4_extension_Returning_STATUS_info_in_LIST.txt new file mode 100644 index 0000000..e45b855 --- /dev/null +++ b/docs/rfcs/rfc5819.IMAP4_extension_Returning_STATUS_info_in_LIST.txt @@ -0,0 +1,339 @@ + + + + + + +Internet Engineering Task Force (IETF) A. Melnikov +Request for Comments: 5819 Isode Limited +Category: Standards Track T. Sirainen +ISSN: 2070-1721 Unaffiliated + March 2010 + + + IMAP4 Extension for Returning STATUS Information in Extended LIST + +Abstract + + Many IMAP clients display information about total number of + messages / total number of unseen messages in IMAP mailboxes. In + order to do that, they are forced to issue a LIST or LSUB command and + to list all available mailboxes, followed by a STATUS command for + each mailbox found. This document provides an extension to LIST + command that allows the client to request STATUS information for + mailboxes together 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 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc5819. + +Copyright Notice + + Copyright (c) 2010 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 + (http://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 Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + +Melnikov & Sirainen Standards Track [Page 1] + +RFC 5819 TITLE* March 2010 + + +Table of Contents + + 1. Introduction ....................................................2 + 1.1. Conventions Used in This Document ..........................2 + 2. STATUS Return Option to LIST Command ............................2 + 3. Examples ........................................................3 + 4. Formal Syntax ...................................................4 + 5. Security Considerations .........................................4 + 6. IANA Considerations .............................................4 + 7. Acknowledgements ................................................5 + 8. Normative References ............................................5 + +1. Introduction + + Many IMAP clients display information about the total number of + messages / total number of unseen messages in IMAP mailboxes. In + order to do that, they are forced to issue a LIST or LSUB command and + to list all available mailboxes, followed by a STATUS command for + each mailbox found. This document provides an extension to LIST + command that allows the client to request STATUS information for + mailboxes together with other information typically returned by the + LIST command. + +1.1. 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", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [Kwds]. + +2. STATUS Return Option to LIST Command + + [RFC3501] explicitly disallows mailbox patterns in the STATUS + command. The main reason was to discourage frequent use of the + STATUS command by clients, as it might be quite expensive for an IMAP + server to perform. However, this prohibition had resulted in an + opposite effect: a new generation of IMAP clients appeared, that + issues a STATUS command for each mailbox returned by the LIST + command. This behavior is suboptimal to say at least. It wastes + extra bandwidth and, in the case of a client that doesn't support + IMAP pipelining, also degrades performance by using too many round + trips. This document tries to remedy the situation by specifying a + single command that can be used by the client to request all the + necessary information. In order to achieve this goal, this document + is extending the LIST command with a new return option, STATUS. This + option takes STATUS data items as parameters. For each selectable + + + +Melnikov & Sirainen Standards Track [Page 2] + +RFC 5819 TITLE* March 2010 + + + mailbox matching the list pattern and selection options, the server + MUST return an untagged LIST response followed by an untagged STATUS + response containing the information requested in the STATUS return + option. + + If an attempted STATUS for a listed mailbox fails because the mailbox + can't be selected (e.g., if the "l" ACL right [ACL] is granted to the + mailbox and the "r" right is not granted, or due to a race condition + between LIST and STATUS changing the mailbox to \NoSelect), the + STATUS response MUST NOT be returned and the LIST response MUST + include the \NoSelect attribute. This means the server may have to + buffer the LIST reply until it has successfully looked up the + necessary STATUS information. + + If the server runs into unexpected problems while trying to look up + the STATUS information, it MAY drop the corresponding STATUS reply. + In such a situation, the LIST command would still return a tagged OK + reply. + +3. Examples + + C: A01 LIST "" % RETURN (STATUS (MESSAGES UNSEEN)) + S: * LIST () "." "INBOX" + S: * STATUS "INBOX" (MESSAGES 17 UNSEEN 16) + S: * LIST () "." "foo" + S: * STATUS "foo" (MESSAGES 30 UNSEEN 29) + S: * LIST (\NoSelect) "." "bar" + S: A01 OK List completed. + + The "bar" mailbox isn't selectable, so it has no STATUS reply. + + C: A02 LIST (SUBSCRIBED RECURSIVEMATCH)"" % RETURN (STATUS + (MESSAGES)) + S: * LIST (\Subscribed) "." "INBOX" + S: * STATUS "INBOX" (MESSAGES 17) + S: * LIST () "." "foo" (CHILDINFO ("SUBSCRIBED")) + S: A02 OK List completed. + + The LIST reply for "foo" is returned because it has matching + children, but no STATUS reply is returned because "foo" itself + doesn't match the selection criteria. + + + + + + + + + + +Melnikov & Sirainen Standards Track [Page 3] + +RFC 5819 TITLE* March 2010 + + +4. Formal Syntax + + The following syntax specification uses the augmented Backus-Naur + Form (BNF) as described in [ABNF]. Terms not defined here are taken + from [RFC3501] and [LISTEXT]. + + return-option =/ status-option + + status-option = "STATUS" SP "(" status-att *(SP status-att) ")" + ;; This ABNF production complies with + ;; syntax. + +5. Security Considerations + + This extension makes it a bit easier for clients to overload the + server by requesting STATUS information for a large number of + mailboxes. However, as already noted in the introduction, existing + clients already try to do that by generating a large number of STATUS + commands for each mailbox in which they are interested. While + performing STATUS information retrieval for big lists of mailboxes, a + server implementation needs to make sure that it can still serve + other IMAP connections and yield execution to other connections, when + necessary. + +6. IANA Considerations + + IMAP4 capabilities are registered by publishing a Standards Track or + IESG-approved Experimental RFC. The "IMAP 4 Capabilities" registry + is available from the IANA webiste: + + http://www.iana.org + + This document defines the LIST-STATUS IMAP capability. IANA has + added it to the registry. + + IANA has also added the following new LIST-EXTENDED option to the + IANA registry established by [LISTEXT]: + + To: iana@iana.org + Subject: Registration of LIST-EXTENDED option STATUS + + LIST-EXTENDED option name: STATUS + + LIST-EXTENDED option type: RETURN + + LIST-EXTENDED option description: Causes the LIST command to return + STATUS responses in addition to LIST responses. + + + + +Melnikov & Sirainen Standards Track [Page 4] + +RFC 5819 TITLE* March 2010 + + + Published specification: RFC 5819 + + Security considerations: RFC 5819 + + Intended usage: COMMON + + Person and email address to contact for further information: + Alexey Melnikov + + Owner/Change controller: iesg@ietf.org + +7. Acknowledgements + + Thanks to Philip Van Hoof who pointed out that STATUS and LIST + commands should be combined in order to optimize traffic and number + of round trips. + +8. Normative References + + [ABNF] Crocker, D., Ed., and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", STD 68, RFC 5234, January + 2008. + + [ACL] Melnikov, A., "IMAP4 Access Control List (ACL) Extension", + RFC 4314, December 2005. + + [Kwds] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [LISTEXT] Leiba, B. and A. Melnikov, "Internet Message Access + Protocol version 4 - LIST Command Extensions", RFC 5258, + June 2008. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + + + + + + + + + + + + + + + +Melnikov & Sirainen Standards Track [Page 5] + +RFC 5819 TITLE* March 2010 + + +Authors' Addresses + + Alexey Melnikov + Isode Limited + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: Alexey.Melnikov@isode.com + URI: http://www.melnikov.ca/ + + + Timo Sirainen + + EMail: tss@iki.fi + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Melnikov & Sirainen Standards Track [Page 6] + diff --git a/docs/rfcs/rfc5957.IMAP4_SORT_extension.txt b/docs/rfcs/rfc5957.IMAP4_SORT_extension.txt new file mode 100644 index 0000000..32adb49 --- /dev/null +++ b/docs/rfcs/rfc5957.IMAP4_SORT_extension.txt @@ -0,0 +1,283 @@ + + + + + + +Internet Engineering Task Force (IETF) D. Karp +Request for Comments: 5957 Zimbra +Updates: 5256 July 2010 +Category: Standards Track +ISSN: 2070-1721 + + + Display-Based Address Sorting for the IMAP4 SORT Extension + +Abstract + + This document describes an IMAP protocol extension enabling server- + side message sorting on the commonly displayed portion of the From + and To header fields. + +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 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc5957. + +Copyright Notice + + Copyright (c) 2010 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 + (http://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 Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + + + + + + +Karp IMAP4 Display-Based Address Sorting [Page 1] + +RFC 5957 July 2010 + + +Table of Contents + + 1. Introduction ....................................................2 + 2. Conventions Used in This Document ...............................2 + 3. DISPLAY Sort Value for an Address ...............................2 + 4. The DISPLAYFROM and DISPLAYTO Sort Criteria .....................3 + 5. Formal Syntax ...................................................3 + 6. Security Considerations .........................................3 + 7. Internationalization Considerations .............................4 + 8. IANA Considerations .............................................4 + 9. Normative References ............................................4 + +1. Introduction + + The [SORT] extension to the [IMAP] protocol provides a means for the + server-based sorting of messages. It defines a set of sort criteria + and the mechanism for determining the sort value of a message for + each such ordering. + + The [SORT] FROM and TO orderings sort messages lexically on the + [IMAP] addr-mailbox of the first address in the message's From and To + headers, respectively. This document provides two alternative + orderings, DISPLAYFROM and DISPLAYTO, which sort messages based on + the first From or To address's [IMAP] addr-name (generally the same + as its [RFC5322] display-name), when present. + + A server that supports the full [SORT] extension as well as both the + DISPLAYFROM and DISPLAYTO sort criteria indicates this by returning + "SORT=DISPLAY" in its CAPABILITY response. + +2. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + +3. DISPLAY Sort Value for an Address + + For the purposes of the sort criteria defined in this document, the + sort value for an [IMAP] address structure is defined as follows: + + o If the address structure's [IMAP] addr-name is non-NIL, apply the + procedure from [RFC5255], Section 4.6. (That is, decode any + [RFC2047] encoded-words and convert the resulting character string + into a charset valid for the currently active [RFC4790] collation, + with a default of UTF-8.) If the resulting octet string is not + the empty string, use it as the sort value for the address. + + + + +Karp IMAP4 Display-Based Address Sorting [Page 2] + +RFC 5957 July 2010 + + + o Otherwise, if the address structure's [IMAP] addr-mailbox and + [IMAP] addr-host are both non-NIL, the sort value for the address + is addr-mailbox@addr-host. + + o Otherwise, if the address structure's [IMAP] addr-mailbox is non- + NIL, the sort value for the address is its addr-mailbox. + + o If none of the above conditions are met, the sort value for the + address is the empty string. + +4. The DISPLAYFROM and DISPLAYTO Sort Criteria + + This document introduces two new [SORT] sort criteria, DISPLAYFROM + and DISPLAYTO. A message's sort value under these orderings MUST be + derived as follows: + + A "derived-addr" value is created from the [IMAP] envelope structure + resulting from a FETCH ENVELOPE on the message. For DISPLAYFROM, the + derived-addr value is the [IMAP] env-from value. For DISPLAYTO, the + derived-addr value is the [IMAP] env-to value. + + o If the derived-addr value is NIL, the message's sort value is the + empty string. + + o Otherwise, the message's sort value is the DISPLAY sort value of + the first [IMAP] address in the derived-addr value. + +5. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [RFC5234]. [IMAP] defines the + non-terminal "capability", and [SORT] defines "sort-key". + + capability =/ "SORT=DISPLAY" + + sort-key =/ "DISPLAYFROM" / "DISPLAYTO" + +6. Security Considerations + + This document defines an additional IMAP4 capability. As such, it + does not change the underlying security considerations of [IMAP]. + The author believes that no new security issues are introduced with + this additional IMAP4 capability. + + + + + + + + +Karp IMAP4 Display-Based Address Sorting [Page 3] + +RFC 5957 July 2010 + + +7. Internationalization Considerations + + DISPLAYFROM and DISPLAYTO are string-based sort criteria. As stated + in [SORT], the active [RFC4790] collation as per [RFC5255] MUST be + used when sorting such strings. + + The DISPLAYFROM and DISPLAYTO orderings sort on the full decoded + [IMAP] addr-name, when present. They do not attempt to parse this + string in a locale- or language-dependent manner in order to + determine and sort on some semantically meaningful substring such as + the surname. + +8. IANA Considerations + + [IMAP] capabilities are registered by publishing a Standards Track or + IESG-approved Experimental RFC. This document constitutes + registration of the SORT=DISPLAY capability in the [IMAP] + capabilities registry. + +9. Normative References + + [IMAP] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) + Part Three: Message Header Extensions for Non-ASCII Text", + RFC 2047, November 1996. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet + Application Protocol Collation Registry", RFC 4790, March + 2007. + + [RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", STD 68, RFC 5234, January + 2008. + + [RFC5255] Newman, C., Gulbrandsen, A., and A. Melnikov, "Internet + Message Access Protocol Internationalization", RFC 5255, + June 2008. + + [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, + October 2008. + + + + + + +Karp IMAP4 Display-Based Address Sorting [Page 4] + +RFC 5957 July 2010 + + + [SORT] Crispin, M. and K. Murchison, "Internet Message Access + Protocol - SORT and THREAD Extensions", RFC 5256, June + 2008. + +Author's Address + + Dan Karp + Zimbra + 3401 Hillview Avenue + Palo Alto, CA 94304 + USA + + EMail: dkarp@zimbra.com + URI: http://www.zimbra.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Karp IMAP4 Display-Based Address Sorting [Page 5] + diff --git a/docs/rfcs/rfc6154.IMAP_LIST_Special-use_Mailboxes.txt b/docs/rfcs/rfc6154.IMAP_LIST_Special-use_Mailboxes.txt new file mode 100644 index 0000000..14d3e76 --- /dev/null +++ b/docs/rfcs/rfc6154.IMAP_LIST_Special-use_Mailboxes.txt @@ -0,0 +1,675 @@ + + + + + + +Internet Engineering Task Force (IETF) B. Leiba +Request for Comments: 6154 Huawei Technologies +Category: Standards Track J. Nicolson +ISSN: 2070-1721 Google + March 2011 + + + IMAP LIST Extension for Special-Use Mailboxes + +Abstract + + Some IMAP message stores include special-use mailboxes, such as those + used to hold draft messages or sent messages. Many mail clients + allow users to specify where draft or sent messages should be put, + but configuring them requires that the user know which mailboxes the + server has set aside for these purposes. This extension adds new + optional mailbox attributes that a server may include in IMAP LIST + command responses to identify special-use mailboxes to the client, + easing configuration. + +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 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc6154. + +Copyright Notice + + Copyright (c) 2011 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 + (http://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 Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + +Leiba & Nicolson Standards Track [Page 1] + +RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 1.1. Conventions Used in This Document . . . . . . . . . . . . 3 + 2. New Mailbox Attributes Identifying Special-Use Mailboxes . . . 3 + 3. Extension to IMAP CREATE Command to Set Special-Use + Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 4. IMAP METADATA Entry for Special-Use Attributes . . . . . . . . 6 + 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 + 5.1. Example of an IMAP LIST Command . . . . . . . . . . . . . 7 + 5.2. Example of an Extended IMAP LIST Command . . . . . . . . . 7 + 5.3. Example of an IMAP CREATE Command . . . . . . . . . . . . 8 + 5.4. Example of Using IMAP METADATA to Manipulate + Special-Use Attributes . . . . . . . . . . . . . . . . . . 8 + 6. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 9 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 9 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 + 8.1. Registration of USEATTR IMAP Response Code . . . . . . . . 10 + 8.2. Registration of CREATE-SPECIAL-USE IMAP Capability . . . . 10 + 8.3. Registration of SPECIAL-USE IMAP Capability . . . . . . . 10 + 8.4. Registration of SPECIAL-USE Selection Option . . . . . . . 10 + 8.5. Registration of SPECIAL-USE Return Option . . . . . . . . 11 + 8.6. Registration of SPECIAL-USE Metadata . . . . . . . . . . . 11 + 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 + 9.1. Normative References . . . . . . . . . . . . . . . . . . . 12 + 9.2. Informative References . . . . . . . . . . . . . . . . . . 12 + + + + + + + + + + + + + + + + + + + + + + + + + +Leiba & Nicolson Standards Track [Page 2] + +RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011 + + +1. Introduction + + Some IMAP message stores include special-use mailboxes, such as those + used to hold draft messages or sent messages. Many mail clients + allow users to specify where draft or sent messages should be put, + but configuring them requires that the user know which mailboxes the + server has set aside for these purposes. This extension adds new + optional mailbox attributes that a server may include in IMAP LIST + command responses to identify special-use mailboxes to the client, + easing configuration. + + In addition, this extension adds an optional parameter on the IMAP + CREATE command, allowing a client to assign a special use to a + mailbox when it is created. Servers may choose to support this part + of the extension, but are not required to. + +1.1. 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", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [RFC2119]. + +2. New Mailbox Attributes Identifying Special-Use Mailboxes + + An IMAP server that supports this extension MAY include any or all of + the following attributes in responses to the non-extended IMAP LIST + command. The new attributes are included along with existing + attributes, such as "\Marked" and "\Noselect". A given mailbox may + have none, one, or more than one of these attributes. In some cases, + a special use is advice to a client about what to put in that + mailbox. In other cases, it's advice to a client about what to + expect to find there. There is no capability string related to the + support of special-use attributes on the non-extended LIST command. + + For the extended list command [RFC5258], this extension adds a new + capability string, a new selection option, and a new return option, + all called "SPECIAL-USE". Supporting implementations MUST include + the "SPECIAL-USE" capability string in response to an IMAP CAPABILITY + command. If the client specifies the "SPECIAL-USE" selection option, + the LIST command MUST return only those mailboxes that have a + special-use attribute set. If the client specifies the "SPECIAL-USE" + return option, the LIST command MUST return the new special-use + attributes on those mailboxes that have them set. The "SPECIAL-USE" + + + + + +Leiba & Nicolson Standards Track [Page 3] + +RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011 + + + return option is implied by the "SPECIAL-USE" selection option. The + extended LIST command MAY return SPECIAL-USE attributes even if the + client does not specify the return option. + + The new attributes defined here are as follows: + + \All + This mailbox presents all messages in the user's message store. + Implementations MAY omit some messages, such as, perhaps, those + in \Trash and \Junk. When this special use is supported, it is + almost certain to represent a virtual mailbox. + + \Archive + This mailbox is used to archive messages. The meaning of an + "archival" mailbox is server-dependent; typically, it will be + used to get messages out of the inbox, or otherwise keep them + out of the user's way, while still making them accessible. + + \Drafts + This mailbox is used to hold draft messages -- typically, + messages that are being composed but have not yet been sent. In + some server implementations, this might be a virtual mailbox, + containing messages from other mailboxes that are marked with + the "\Draft" message flag. Alternatively, this might just be + advice that a client put drafts here. + + \Flagged + This mailbox presents all messages marked in some way as + "important". When this special use is supported, it is likely + to represent a virtual mailbox collecting messages (from other + mailboxes) that are marked with the "\Flagged" message flag. + + \Junk + This mailbox is where messages deemed to be junk mail are held. + Some server implementations might put messages here + automatically. Alternatively, this might just be advice to a + client-side spam filter. + + \Sent + This mailbox is used to hold copies of messages that have been + sent. Some server implementations might put messages here + automatically. Alternatively, this might just be advice that a + client save sent messages here. + + \Trash + This mailbox is used to hold messages that have been deleted or + marked for deletion. In some server implementations, this might + be a virtual mailbox, containing messages from other mailboxes + + + +Leiba & Nicolson Standards Track [Page 4] + +RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011 + + + that are marked with the "\Deleted" message flag. + Alternatively, this might just be advice that a client that + chooses not to use the IMAP "\Deleted" model should use this as + its trash location. In server implementations that strictly + expect the IMAP "\Deleted" model, this special use is likely not + to be supported. + + All of the above attributes are OPTIONAL, and any given server or + message store may support any combination of the attributes, or none + at all. In most cases, there will likely be at most one mailbox with + a given attribute for a given user, but in some server or message + store implementations it might be possible for multiple mailboxes to + have the same special-use attribute. + + Special-use attributes are likely to be user-specific. User Adam + might share his \Sent mailbox with user Barb, but that mailbox is + unlikely to also serve as Barb's \Sent mailbox. It's certainly + possible for Adam and Barb to each set the \Sent use on the same + mailbox, but that would be done by specific action (see the sections + below). + +3. Extension to IMAP CREATE Command to Set Special-Use Attributes + + As an OPTIONAL feature, a server MAY allow clients to designate a + mailbox, at creation, as having one or more special uses. This + extension defines the "USE" parameter to the IMAP CREATE command for + that purpose (using the syntax defined in RFC 4466 section 2.2 + [RFC4466]). The new OPTIONAL "USE" parameter is followed by a + parenthesized list of zero or more special-use attributes, as defined + above. + + In some server implementations, some special uses may imply automatic + action by the server. For example, creation of a "\Junk" mailbox + might cause the server to start placing messages that have been + evaluated as spam into the mailbox. + + In some server implementations, some special uses may result in a + mailbox with unusual characteristics or side effects. For example, + creation of an "\All" mailbox might cause the server to create a + virtual mailbox, rather than a standard one, and that mailbox might + behave in unexpected ways (COPY into it might fail, for example). + + Servers MAY allow the creation of a special-use mailbox even if one + so designated already exists. This might have the effect of moving + the special use from the old mailbox to the new one, or might create + multiple mailboxes with the same special use. Alternatively, servers + MAY refuse the creation, considering the designation to be a + conflict. + + + +Leiba & Nicolson Standards Track [Page 5] + +RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011 + + + If the server cannot create a mailbox with the designated special use + defined, for whatever reason, it MUST NOT create the mailbox, and + MUST respond to the CREATE command with a tagged NO response. If the + reason for the failure is related to the special-use attribute (the + specified special use is not supported or cannot be assigned to the + specified mailbox), the server SHOULD include the new "USEATTR" + response code in the tagged response (see Section 5.3 for an + example). + + An IMAP server that supports this OPTIONAL feature will advertise the + "CREATE-SPECIAL-USE" capability string. Clients MUST NOT use the + "USE" parameter unless the server advertises the capability. Note + that this capability string is different from the "SPECIAL-USE" + string defined above, and a server that supports both functions MUST + advertise both capability strings. + +4. IMAP METADATA Entry for Special-Use Attributes + + If a server supports this extension and the METADATA extension + [RFC5464], it SHOULD tie the special-use attributes for a mailbox to + its metadata entry "/private/specialuse". The value of /private/ + specialuse is either NIL (if there are no special-use attributes for + that mailbox) or a space-separated list of special-use attributes, + presented the same way they would be presented in the LIST command + response. + + Such a server MAY allow the setting of special-use attributes through + the METADATA mechanisms, thereby allowing clients to change the + special uses of existing mailboxes. These changes might have side + effects, as the server automatically adjusts the special uses + accordingly, just as it might do with CREATE USE, above. See + Section 5.4 for an example. + + A server that supports this MUST check the validity of changes to the + special-use attributes that are done through the metadata in the same + way that it checks validity for the CREATE command and for any + internal mechanisms for setting special uses on mailboxes. It MUST + NOT just blindly accept setting of these metadata by clients, which + might result in the setting of special uses that the implementation + does not support, multiple mailboxes with the same special use, or + other situations that the implementation considers invalid. + + + + + + + + + + +Leiba & Nicolson Standards Track [Page 6] + +RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011 + + +5. Examples + +5.1. Example of an IMAP LIST Command + + This example shows an IMAP LIST response from a server that supports + this extension. Note that not all of the attributes are used. This + server also supports the Child Mailbox extension [RFC3348]. + + C: t1 LIST "" "%" + S: * LIST (\Marked \HasNoChildren) "/" Inbox + S: * LIST (\HasNoChildren) "/" ToDo + S: * LIST (\HasChildren) "/" Projects + S: * LIST (\Sent \HasNoChildren) "/" SentMail + S: * LIST (\Marked \Drafts \HasNoChildren) "/" MyDrafts + S: * LIST (\Trash \HasNoChildren) "/" Trash + S: t1 OK done + +5.2. Example of an Extended IMAP LIST Command + + This example shows an IMAP LIST response from a server that supports + this extension. The client uses the extended IMAP LIST command. + + C: t1 CAPABILITY + S: * CAPABILITY IMAP4rev1 SPECIAL-USE + S: t1 OK done + + C: t2 LIST "" "%" RETURN (SPECIAL-USE) + S: * LIST (\Marked) "/" Inbox + S: * LIST () "/" ToDo + S: * LIST () "/" Projects + S: * LIST (\Sent) "/" SentMail + S: * LIST (\Marked \Drafts) "/" MyDrafts + S: * LIST (\Trash) "/" Trash + S: t2 OK done + + Here, the client also includes the "SPECIAL-USE" selection option for + the same list. The "SPECIAL-USE" return option could also have been + specified, but it is unnecessary, as it is implied by the selection + option. Note that in this case, mailboxes that do not have a + special-use attribute are not listed. Also note that we've used the + wildcard "*", rather than "%", to make sure we see all special-use + mailboxes, even ones that might not be at the namespace's root. + + C: t3 LIST (SPECIAL-USE) "" "*" + S: * LIST (\Sent) "/" SentMail + S: * LIST (\Marked \Drafts) "/" MyDrafts + S: * LIST (\Trash) "/" Trash + S: t3 OK done + + + +Leiba & Nicolson Standards Track [Page 7] + +RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011 + + +5.3. Example of an IMAP CREATE Command + + This example shows an IMAP CREATE command that might be used to + create a mailbox designated to hold draft and sent messages. It also + attempts to create a mailbox that will contain all the user's + messages, but the server does not support that special use for this + user's message store. + + C: t1 CAPABILITY + S: * CAPABILITY IMAP4rev1 CREATE-SPECIAL-USE + S: t1 OK done + + C: t2 CREATE MySpecial (USE (\Drafts \Sent)) + S: t2 OK MySpecial created + + C: t3 CREATE Everything (USE (\All)) + S: t3 NO [USEATTR] \All not supported + +5.4. Example of Using IMAP METADATA to Manipulate Special-Use + Attributes + + This example shows how IMAP METADATA can be used to manipulate + special-use attributes, if the operation is supported on the server. + + ==> Starting point: + C: t1 LIST "" "%" RETURN (SPECIAL-USE) + S: * LIST (\Sent) "/" SentMail + S: * LIST (\Drafts) "/" MyDrafts + S: * LIST () "/" SavedDrafts + S: * LIST (\Trash) "/" Trash + S: t1 OK done + + ==> Demonstrate the connection: + C: t2 GETMETADATA "MyDrafts" /private/specialuse + S: * METADATA "MyDrafts" (/private/specialuse "\\Drafts") + S: t2 OK done + + ==> Set new use for SavedDrafts; MyDrafts changes automatically: + C: t3 SETMETADATA "SavedDrafts" (/private/specialuse "\\Drafts") + S: * METADATA "MyDrafts" (/private/specialuse NIL) + S: t3 OK SETMETADATA complete + + ==> Remove special use for SentMail: + C: t4 SETMETADATA "SentMail" (/private/specialuse NIL) + S: t4 OK SETMETADATA complete + + + + + + +Leiba & Nicolson Standards Track [Page 8] + +RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011 + + + ==> Check the results: + C: t5 LIST "" "%" RETURN (SPECIAL-USE) + S: * LIST () "/" SentMail + S: * LIST () "/" MyDrafts + S: * LIST (\Drafts) "/" SavedDrafts + S: * LIST (\Trash) "/" Trash + S: t5 OK done + +6. Formal Syntax + + The following syntax specification uses the augmented Backus-Naur + Form (BNF) as described in [RFC5234]. + + create-param =/ "USE" SP "(" [use-attr *(SP use-attr)] ")" + ; Extends "create-param" from RFC 4466 [RFC4466] + + mbx-list-oflag =/ use-attr + ; Extends "mbx-list-oflag" from IMAP base [RFC3501] + + list-select-independent-opt =/ "SPECIAL-USE" + ; Extends "list-select-independent-opt" from + ; LIST-extended [RFC5258] + + return-option =/ "SPECIAL-USE" + ; Extends "return-option" from + ; LIST-extended [RFC5258] + + resp-text-code =/ "USEATTR" + ; Extends "resp-text-code" from + ; IMAP [RFC3501] + + use-attr = "\All" / "\Archive" / "\Drafts" / "\Flagged" / + "\Junk" / "\Sent" / "\Trash" / use-attr-ext + + use-attr-ext = "\" atom + ; Reserved for future extensions. Clients + ; MUST ignore list attributes they do not understand + ; Server implementations MUST NOT generate + ; extension attributes except as defined by + ; future Standards-Track revisions of or + ; extensions to this specification. + +7. Security Considerations + + LIST response: + Conveying special-use information to a client exposes a small bit of + extra information that could be of value to an attacker. Knowing, + for example, that a particular mailbox (\All) contains pointers to + + + +Leiba & Nicolson Standards Track [Page 9] + +RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011 + + + every message the user has might be of particular value. If the IMAP + channel is not protected from passive eavesdropping, this could be an + issue. + + CREATE command "USE" parameter and metadata extension: In some server + implementations, some special uses may imply automatic action by the + server. For example, creation of a "\Junk" mailbox might cause the + server to start placing messages that have been evaluated as spam + into the mailbox. Implementors SHOULD consider the consequences of + allowing a user (or client program) to designate the target of such + automatic action. + + Example: If a user is allowed to give the "\Junk" attribute to a + shared mailbox, legitimate mail that's misclassified as junk (false + positives) will be put into that shared mailbox, exposing the user's + private mail to others. The server might warn a user of that + possibility, or might refuse to allow the specification to be made on + a shared mailbox. (Note that this problem exists independent of this + specification, if the server allows a user to share a mailbox that's + already in use for such a function.) + +8. IANA Considerations + +8.1. Registration of USEATTR IMAP Response Code + + This document defines a new IMAP response code, "USEATTR", which IANA + added to the IMAP Response Codes registry. + +8.2. Registration of CREATE-SPECIAL-USE IMAP Capability + + This document defines a new IMAP capability, "CREATE-SPECIAL-USE", + which IANA added to the IMAP 4 Capabilities registry. + +8.3. Registration of SPECIAL-USE IMAP Capability + + This document defines a new IMAP capability, "SPECIAL-USE", which + IANA added to the IMAP 4 Capabilities registry. + +8.4. Registration of SPECIAL-USE Selection Option + + This document defines a new IMAP4 List Extended selection option, + "SPECIAL-USE", which IANA added to the IMAP4 List Extended registry, + as follows: + + To: iana@iana.org + Subject: Registration of LIST-EXTENDED selection option SPECIAL-USE + LIST-EXTENDED option name: SPECIAL-USE + LIST-EXTENDED option type: SELECTION + + + +Leiba & Nicolson Standards Track [Page 10] + +RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011 + + + Implied return option(s): SPECIAL-USE + LIST-EXTENDED option description: Limit the list to special-use + mailboxes only + Published specification: RFC 6154 + Security considerations: none + Intended usage: COMMON + Person and email address to contact for further information: Authors' + Addresses at the end of RFC 6154 + Owner/Change controller: iesg@ietf.org + +8.5. Registration of SPECIAL-USE Return Option + + This document defines a new IMAP4 List Extended return option, + "SPECIAL-USE", which IANA added to the IMAP4 List Extended registry, + as follows: + + To: iana@iana.org + Subject: Registration of LIST-EXTENDED return option SPECIAL-USE + LIST-EXTENDED option name: SPECIAL-USE + LIST-EXTENDED option type: RETURN + LIST-EXTENDED option description: Request special-use mailbox + information + Published specification: RFC 6154 + Security considerations: none + Intended usage: COMMON + Person and email address to contact for further information: Authors' + Addresses at the end of RFC 6154 + Owner/Change controller: iesg@ietf.org + +8.6. Registration of SPECIAL-USE Metadata + + This document defines a new IMAP METADATA entry. IANA added the + following to the IMAP METADATA Mailbox Entry registry: + + To: iana@iana.org + Subject: IMAP METADATA Entry Registration + Type: Mailbox + Name: /private/specialuse + Description: Defines any special-use features of a mailbox. See the + reference specification for details of its use. + Content-type: text/plain; charset=us-ascii + RFC Number: RFC 6154 + Contact: MORG mailing list mailto:morg@ietf.org + + + + + + + + +Leiba & Nicolson Standards Track [Page 11] + +RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011 + + +9. References + +9.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 + ABNF", RFC 4466, April 2006. + + [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + + [RFC5258] Leiba, B. and A. Melnikov, "Internet Message Access + Protocol version 4 - LIST Command Extensions", RFC 5258, + June 2008. + + [RFC5464] Daboo, C., "The IMAP METADATA Extension", RFC 5464, + February 2009. + +9.2. Informative References + + [RFC3348] Gahrns, M. and R. Cheng, "The Internet Message Action + Protocol (IMAP4) Child Mailbox Extension", RFC 3348, + July 2002. + +Authors' Addresses + + Barry Leiba + Huawei Technologies + + Phone: +1 646 827 0648 + EMail: barryleiba@computer.org + URI: http://internetmessagingtechnology.org/ + + + Jamie Nicolson + Google + + EMail: nicolson@google.com + + + + + + + + +Leiba & Nicolson Standards Track [Page 12] + diff --git a/docs/rfcs/rfc6203.IMAP4_Fuzzy_SEARCH_extension.txt b/docs/rfcs/rfc6203.IMAP4_Fuzzy_SEARCH_extension.txt new file mode 100644 index 0000000..e4ed001 --- /dev/null +++ b/docs/rfcs/rfc6203.IMAP4_Fuzzy_SEARCH_extension.txt @@ -0,0 +1,395 @@ + + + + + + +Internet Engineering Task Force (IETF) T. Sirainen +Request for Comments: 6203 March 2011 +Category: Standards Track +ISSN: 2070-1721 + + + IMAP4 Extension for Fuzzy Search + +Abstract + + This document describes an IMAP protocol extension enabling a server + to perform searches with inexact matching and assigning relevancy + scores for matched messages. + +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 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc6203. + +Copyright Notice + + Copyright (c) 2011 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 + (http://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 Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + + + + + + + +Sirainen Standards Track [Page 1] + +RFC 6203 IMAP4 FUZZY Search March 2011 + + +1. Introduction + + When humans perform searches in IMAP clients, they typically want to + see the most relevant search results first. IMAP servers are able to + do this in the most efficient way when they're free to internally + decide how searches should match messages. This document describes a + new SEARCH=FUZZY extension that provides such functionality. + +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", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [KEYWORDS]. + +3. The FUZZY Search Key + + The FUZZY search key takes another search key as its argument. The + server is allowed to perform all matching in an implementation- + defined manner for this search key, including ignoring the active + comparator as defined by [RFC5255]. Typically, this would be used to + search for strings. For example: + + C: A1 SEARCH FUZZY (SUBJECT "IMAP break") + S: * SEARCH 1 5 10 + S: A1 OK Search completed. + + Besides matching messages with a subject of "IMAP break", the above + search may also match messages with subjects "broken IMAP", "IMAP is + broken", or anything else the server decides that might be a good + match. + + This example does a fuzzy SUBJECT search, but a non-fuzzy FROM + search: + + C: A2 SEARCH FUZZY SUBJECT work FROM user@example.com + S: * SEARCH 1 4 + S: A2 OK Search completed. + + How the server handles multiple separate FUZZY search keys is + implementation-defined. + + Fuzzy search algorithms might change, or the results of the + algorithms might be different from search to search, so that fuzzy + searches with the same parameters might give different results for + 1) the same user at different times, 2) different users (searches + + + +Sirainen Standards Track [Page 2] + +RFC 6203 IMAP4 FUZZY Search March 2011 + + + executed simultaneously), or 3) different users (searches executed at + different times). For example, a fuzzy search might adapt to a + user's search habits in an attempt to give more relevant results (in + a "learning" manner). Such differences can also occur because of + operational decisions, such as load balancing. Clients asking for + "fuzzy" really are requesting search results in a not-necessarily- + deterministic way and need to give the user appropriate warning about + that. + +4. Relevancy Scores for Search Results + + Servers SHOULD assign a search relevancy score for each matched + message when the FUZZY search key is given. Relevancy scores are + given in the range 1-100, where 100 is the highest relevancy. The + relevancy scores SHOULD use the full 1-100 range, so that clients can + show them to users in a meaningful way, e.g., as a percentage value. + + As the name already indicates, relevancy scores specify how relevant + to the search the matched message is. It's not necessarily the same + as how precisely the message matched. For example, a message whose + subject fuzzily matches the search string might get a higher + relevancy score than a message whose body had the exact string in the + middle of a sentence. When multiple search keys are matched fuzzily, + how the relevancy score is calculated is server-dependent. + + If the server also advertises the ESEARCH capability as defined by + [ESEARCH], the relevancy scores can be retrieved using the new + RELEVANCY return option for SEARCH: + + C: B1 SEARCH RETURN (RELEVANCY ALL) FUZZY TEXT "Helo" + S: * ESEARCH (TAG "B1") ALL 1,5,10 RELEVANCY (4 99 42) + S: B1 OK Search completed. + + In the example above, the server would treat "hello", "help", and + other similar strings as fuzzily matching the misspelled "Helo". + + The RELEVANCY return option MUST NOT be used unless a FUZZY search + key is also given. Note that SEARCH results aren't sorted by + relevancy; SORT is needed for that. + +5. Fuzzy Matching with Non-String Search Keys + + Fuzzy matching is not limited to just string matching. All search + keys SHOULD be matched fuzzily, although exactly what that means for + different search keys is left for server implementations to decide -- + including deciding that fuzzy matching is meaningless for a + particular key, and falling back to exact matching. Some suggestions + are given below. + + + +Sirainen Standards Track [Page 3] + +RFC 6203 IMAP4 FUZZY Search March 2011 + + + Dates: + A typical example could be when a user wants to find a message + "from Dave about a week ago". A client could perform this search + using SEARCH FUZZY (FROM "Dave" SINCE 21-Jan-2009 BEFORE + 24-Jan-2009). The server could return messages outside the + specified date range, but the further away the message is, the + lower the relevancy score. + + Sizes: + These should be handled similarly to dates. If a user wants to + search for "about 1 MB attachments", the client could do this by + sending SEARCH FUZZY (LARGER 900000 SMALLER 1100000). Again, the + further away the message size is from the specified range, the + lower the relevancy score. + + Flags: + If other search criteria match, the server could return messages + that don't have the specified flags set, but with lower relevancy + scores. SEARCH SUBJECT "xyz" FUZZY ANSWERED, for example, might + be useful if the user thinks the message he is looking for has the + ANSWERED flag set, but he isn't sure. + + Unique Identifiers (UIDs), sequences, modification sequences: These + are examples of keys for which exact matching probably makes sense. + Alternatively, a server might choose, for instance, to expand a UID + range by 5% on each side. + +6. Extensions to SORT and SEARCH + + If the server also advertises the SORT capability as defined by + [SORT], the results can be sorted by the new RELEVANCY sort criteria: + + C: C1 SORT (RELEVANCY) UTF-8 FUZZY SUBJECT "Helo" + S: * SORT 5 10 1 + S: C1 OK Sort completed. + + The message with the highest score is returned first. As with the + RELEVANCY return option, RELEVANCY sort criteria MUST NOT be used + unless a FUZZY search key is also given. + + If the server also advertises the ESORT capability as defined by + [CONTEXT], the relevancy scores can be retrieved using the new + RELEVANCY return option for SORT: + + C: C2 SORT RETURN (RELEVANCY ALL) (RELEVANCY) UTF-8 FUZZY TEXT + "Helo" + S: * ESEARCH (TAG "C2") ALL 5,10,1 RELEVANCY (99 42 4) + S: C2 OK Sort completed. + + + +Sirainen Standards Track [Page 4] + +RFC 6203 IMAP4 FUZZY Search March 2011 + + + Furthermore, if the server advertises the CONTEXT=SORT (or + CONTEXT=SEARCH) capability, then the client can limit the number of + returned messages to a SORT (or a SEARCH) by using the PARTIAL return + option. For example, this returns the 10 most relevant messages: + + C: C3 SORT RETURN (PARTIAL 1:10) (RELEVANCY) UTF-8 FUZZY TEXT + "World" + S: * ESEARCH (TAG "C3") PARTIAL (1:10 42,9,34,13,15,4,2,7,23,82) + S: C3 OK Sort completed. + +7. Formal Syntax + + The following syntax specification uses the augmented Backus-Naur + Form (BNF) as described in [ABNF]. It includes definitions from + [RFC3501], [IMAP-ABNF], and [SORT]. + + capability =/ "SEARCH=FUZZY" + + score = 1*3DIGIT + ;; (1 <= n <= 100) + + score-list = "(" [score *(SP score)] ")" + + search-key =/ "FUZZY" SP search-key + + search-return-data =/ "RELEVANCY" SP score-list + ;; Conforms to , from [IMAP-ABNF] + + search-return-opt =/ "RELEVANCY" + ;; Conforms to , from [IMAP-ABNF] + + sort-key =/ "RELEVANCY" + +8. Security Considerations + + Implementation of this extension might enable denial-of-service + attacks against server resources. Servers MAY limit the resources + that a single search (or a single user) may use. Additionally, + implementors should be aware of the following: Fuzzy search engines + are often complex with non-obvious disk space, memory, and/or CPU + usage patterns. Server implementors should at least test the fuzzy- + search behavior with large messages that contain very long words + and/or unique random strings. Also, very long search keys might + cause excessive memory or CPU usage. + + Invalid input may also be problematic. For example, if the search + engine takes a UTF-8 stream as input, it might fail more or less + badly when illegal UTF-8 sequences are fed to it from a message whose + + + +Sirainen Standards Track [Page 5] + +RFC 6203 IMAP4 FUZZY Search March 2011 + + + character set was claimed to be UTF-8. This could be avoided by + validating all the input and, for example, replacing illegal UTF-8 + sequences with the Unicode replacement character (U+FFFD). + + Search relevancy rankings might be susceptible to "poisoning" by + smart attackers using certain keywords or hidden markup (e.g., HTML) + in their messages to boost the rankings. This can't be fully + prevented by servers, so clients should prepare for it by at least + allowing users to see all the search results, rather than hiding + results below a certain score. + +9. IANA Considerations + + IMAP4 capabilities are registered by publishing a standards track or + IESG-approved experimental RFC. The "Internet Message Access + Protocol (IMAP) 4 Capabilities Registry" is available from + http://www.iana.org/. + + This document defines the SEARCH=FUZZY IMAP capability. IANA has + added it to the registry. + +10. Acknowledgements + + Alexey Melnikov, Zoltan Ordogh, Barry Leiba, Cyrus Daboo, and Dave + Cridland have helped with this document. + +11. Normative References + + [ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", STD 68, RFC 5234, + January 2008. + + [CONTEXT] Cridland, D. and C. King, "Contexts for IMAP4", + RFC 5267, July 2008. + + [ESEARCH] Melnikov, A. and D. Cridland, "IMAP4 Extension to SEARCH + Command for Controlling What Kind of Information Is + Returned", RFC 4731, November 2006. + + [IMAP-ABNF] Melnikov, A. and C. Daboo, "Collected Extensions to + IMAP4 ABNF", RFC 4466, April 2006. + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + + + +Sirainen Standards Track [Page 6] + +RFC 6203 IMAP4 FUZZY Search March 2011 + + + [RFC5255] Newman, C., Gulbrandsen, A., and A. Melnikov, "Internet + Message Access Protocol Internationalization", RFC 5255, + June 2008. + + [SORT] Crispin, M. and K. Murchison, "Internet Message Access + Protocol - SORT and THREAD Extensions", RFC 5256, + June 2008. + +Author's Address + + Timo Sirainen + + EMail: tss@iki.fi + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Sirainen Standards Track [Page 7] + diff --git a/docs/rfcs/rfc6237.IMAP4_Multimailbox_SEARCH_extension.txt b/docs/rfcs/rfc6237.IMAP4_Multimailbox_SEARCH_extension.txt new file mode 100644 index 0000000..b5a3a61 --- /dev/null +++ b/docs/rfcs/rfc6237.IMAP4_Multimailbox_SEARCH_extension.txt @@ -0,0 +1,563 @@ + + + + + + +Internet Engineering Task Force (IETF) B. Leiba +Request for Comments: 6237 Huawei Technologies +Updates: 4466 A. Melnikov +Category: Experimental Isode Limited +ISSN: 2070-1721 May 2011 + + + IMAP4 Multimailbox SEARCH Extension + +Abstract + + The IMAP4 specification allows the searching of only the selected + mailbox. A user often wants to search multiple mailboxes, and a + client that wishes to support this must issue a series of SELECT and + SEARCH commands, waiting for each to complete before moving on to the + next. This extension allows a client to search multiple mailboxes + with one command, limiting the round trips and waiting for various + searches to complete, and not requiring disruption of the currently + selected mailbox. This extension also uses MAILBOX and TAG fields in + ESEARCH responses, allowing a client to pipeline the searches if it + chooses. This document updates RFC 4466. + +Status of This Memo + + This document is not an Internet Standards Track specification; it is + published for examination, experimental implementation, and + evaluation. + + This document defines an Experimental Protocol for the Internet + community. 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). Not + all documents approved by the IESG are a candidate for any level of + Internet Standard; see Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc6237. + + + + + + + + + + + + +Leiba & Melnikov Experimental [Page 1] + +RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011 + + +Copyright Notice + + Copyright (c) 2011 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 + (http://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 Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + +Table of Contents + + 1. Introduction ....................................................2 + 1.1. Conventions Used in This Document ..........................3 + 2. New ESEARCH Command .............................................3 + 2.1. The ESEARCH Response .......................................4 + 2.2. Source Options: Specifying Mailboxes to Search .............5 + 3. Examples ........................................................6 + 4. Formal Syntax ...................................................7 + 5. Security Considerations .........................................8 + 6. IANA Considerations .............................................9 + 7. Acknowledgements ................................................9 + 8. Normative References ............................................9 + +1. Introduction + + The IMAP4 specification allows the searching of only the selected + mailbox. A user often wants to search multiple mailboxes, and a + client that wishes to support this must issue a series of SELECT and + SEARCH commands, waiting for each to complete before moving on to the + next. The commands can't be pipelined, because the server might run + them in parallel, and the untagged SEARCH responses could not then be + distinguished from each other. + + This extension allows a client to search multiple mailboxes with one + command, and includes MAILBOX and TAG fields in the ESEARCH response, + yielding the following advantages: + + o A single command limits the number of round trips needed to search + a set of mailboxes. + + o A single command eliminates the need to wait for one search to + complete before starting the next. + + + +Leiba & Melnikov Experimental [Page 2] + +RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011 + + + o A single command allows the server to optimize the search, if it + can. + + o A command that is not dependent upon the selected mailbox + eliminates the need to disrupt the selection state or to open + another IMAP connection. + + o The MAILBOX, UIDVALIDITY, and TAG fields in the responses allow a + client to distinguish which responses go with which search (and + which mailbox). A client can safely pipeline these search + commands without danger of confusion. The addition of the MAILBOX + and UIDVALIDITY fields updates the search-correlator item defined + in [RFC4466]. + +1.1. 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", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [RFC2119]. + +2. New ESEARCH Command + + Arguments: OPTIONAL source options + OPTIONAL result options + OPTIONAL charset specification (see [RFC2978]) + searching criteria (one or more) + + Responses: REQUIRED untagged response: ESEARCH + + Result: OK -- search completed + NO -- error: cannot search that charset or criteria + BAD -- command unknown or arguments invalid + + This section defines a new ESEARCH command, which works similarly to + the UID SEARCH command described in Section 2.6.1 of [RFC4466] + (initially described in Section 6.4.4 of [RFC3501] and extended by + [RFC4731]). + + The ESEARCH command further extends searching by allowing for + optional source and result options. This document does not define + any new result options (see Section 3.1 of [RFC4731]). A server that + supports this extension includes "MULTISEARCH" in its IMAP capability + string. + + + + + +Leiba & Melnikov Experimental [Page 3] + +RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011 + + + Because there has been confusion about this, it is worth pointing out + that with ESEARCH, as with *any* SEARCH or UID SEARCH command, it + MUST NOT be considered an error if the search terms include a range + of message numbers that extends (or, in fact, starts) beyond the end + of the mailbox. For example, a client might want to establish a + rolling window through the search results this way: + + C: tag1 UID ESEARCH FROM "frobozz" 1:100 + + ...followed later by this: + + C: tag1 UID ESEARCH FROM "frobozz" 101:200 + + ...and so on. This tells the server to match only the first hundred + messages in the mailbox the first time, the second hundred the second + time, etc. In fact, it might likely allow the server to optimize the + search significantly. In the above example, whether the mailbox + contains 50 or 150 or 250 messages, neither of the search commands + shown will result in an error. It is up to the client to know when + to stop moving its search window. + +2.1. The ESEARCH Response + + In response to an ESEARCH command, the server MUST return ESEARCH + responses [RFC4731] (that is, not SEARCH responses). Because message + numbers are not useful for mailboxes that are not selected, the + responses MUST contain information about UIDs, not message numbers. + This is true even if the source options specify that only the + selected mailbox be searched. + + Presence of a source option in the absence of a result option implies + the "ALL" result option (see Section 3.1 of [RFC4731]). Note that + this is not the same as the result from the SEARCH command described + in the IMAP base protocol [RFC3501]. + + Source options describe which mailboxes must be searched for + messages. An ESEARCH command with source options does not affect + which mailbox, if any, is currently selected, regardless of which + mailboxes are searched. + + For each mailbox satisfying the source options, a single ESEARCH + response MUST be returned if any messages in that mailbox match the + search criteria. An ESEARCH response MUST NOT be returned for + mailboxes that contain no matching messages. This is true even when + result options such as MIN, MAX, and COUNT are specified (see + Section 3.1 of [RFC4731]), and the values returned (lowest UID + matched, highest UID matched, and number of messages matched, + respectively) apply to the mailbox reported in that ESEARCH response. + + + +Leiba & Melnikov Experimental [Page 4] + +RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011 + + + Note that it is possible for an ESEARCH command to return *no* + untagged responses (no ESEARCH responses at all), in the case that + there are no matches to the search in any of the mailboxes that + satisfy the source options. Clients can detect this situation by + finding the tagged OK response without having received any matching + untagged ESEARCH responses. + + Each ESEARCH response MUST contain the MAILBOX, TAG, and UIDVALIDITY + correlators. Correlators allow clients to issue several ESEARCH + commands at once (pipelined). If the SEARCHRES [RFC5182] extension + is used in an ESEARCH command, that ESEARCH command MUST be executed + by the server after all previous SEARCH/ESEARCH commands have + completed and before any subsequent SEARCH/ESEARCH commands are + executed. The server MAY perform consecutive ESEARCH commands in + parallel as long as none of them use the SEARCHRES extension. + +2.2. Source Options: Specifying Mailboxes to Search + + The source options, if present, MUST contain a mailbox specifier as + defined in the IMAP NOTIFY extension [RFC5465], Section 6 (using the + "filter-mailboxes" ABNF item), with the following differences: + + 1. The "selected-delayed" specifier is not valid here. + + 2. A "subtree-one" specifier is added. The "subtree" specifier + results in a search of the specified mailbox and all selectable + mailboxes that are subordinate to it, through an indefinitely + deep hierarchy. The "subtree-one" specifier results in a search + of the specified mailbox and all selectable child mailboxes, one + hierarchy level down. + + If "subtree" is specified, the server MUST defend against loops in + the hierarchy (for example, those caused by recursive file-system + links within the message store). The server SHOULD do this by + keeping track of the mailboxes that have been searched, and + terminating the hierarchy traversal when a repeat is found. If it + cannot do that, it MAY do it by limiting the hierarchy depth. + + If the source options are not present, the value "selected" is + assumed -- that is, only the currently selected mailbox is searched. + + The "personal" source option is a particularly convenient way to + search all of the current user's mailboxes. Note that there is no + way to use wildcard characters to search all mailboxes; the + "mailboxes" source option does not do wildcard expansion. + + + + + + +Leiba & Melnikov Experimental [Page 5] + +RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011 + + + If the source options include (or default to) "selected", the IMAP + session MUST be in "selected" state. If the source options specify + other mailboxes and NOT "selected", then the IMAP session MUST be in + either "selected" or "authenticated" state. If the session is not in + a correct state, the ESEARCH command MUST return a "BAD" result. + + If the server supports the SEARCHRES [RFC5182] extension, then the + "SAVE" result option is valid *only* if "selected" is specified or + defaulted as the sole mailbox to be searched. If any source option + other than "selected" is specified, the ESEARCH command MUST return a + "BAD" result. + + If the server supports the CONTEXT=SEARCH and/or CONTEXT=SORT + extension [RFC5267], then the following additional rules apply: + + o The CONTEXT return option (Section 4.2 of [RFC5267]) can be used + with an ESEARCH command. + + o If the UPDATE return option is used (Section 4.3 of [RFC5267]), it + MUST apply ONLY to the currently selected mailbox. If UPDATE is + used and there is no mailbox currently selected, the ESEARCH + command MUST return a "BAD" result. + + o The PARTIAL search return option (Section 4.4 of [RFC5267]) can be + used and applies to each mailbox searched by the ESEARCH command. + + If the server supports the Access Control List (ACL) [RFC4314] + extension, then the logged-in user is required to have the "r" right + for each mailbox she wants to search. In addition, any mailboxes + that are not explicitly named (accessed through "personal" or + "subtree", for example) are required to have the "l" right. + Mailboxes matching the source options for which the logged-in user + lacks sufficient rights MUST be ignored by the ESEARCH command + processing. In particular, ESEARCH responses MUST NOT be returned + for those mailboxes. + +3. Examples + + In the following example, note that two ESEARCH commands are + pipelined, and that the server is running them in parallel, + interleaving a response to the second search amid the responses to + the first (watch the tags). + + C: tag1 ESEARCH IN (mailboxes "folder1" subtree "folder2") unseen + C: tag2 ESEARCH IN (mailboxes "folder1" subtree-one "folder2") + subject "chad" + S: * ESEARCH (TAG "tag1" MAILBOX "folder1" UIDVALIDITY 1) UID ALL + 4001,4003,4005,4007,4009 + + + +Leiba & Melnikov Experimental [Page 6] + +RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011 + + + S: * ESEARCH (TAG "tag2" MAILBOX "folder1" UIDVALIDITY 1) UID ALL + 3001:3004,3788 + S: * ESEARCH (TAG "tag1" MAILBOX "folder2/banana" UIDVALIDITY 503) + UID ALL 3002,4004 + S: * ESEARCH (TAG "tag1" MAILBOX "folder2/peach" UIDVALIDITY 3) UID + ALL 921691 + S: tag1 OK done + S: * ESEARCH (TAG "tag2" MAILBOX "folder2/salmon" UIDVALIDITY + 1111111) UID ALL 50003,50006,50009,50012 + S: tag2 OK done + +4. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) as described in [RFC5234]. Terms not defined here are + taken from [RFC3501], [RFC5465], or [RFC4466]. + + command-auth =/ esearch + ; Update definition from IMAP base [RFC3501]. + ; Add new "esearch" command. + + command-select =/ esearch + ; Update definition from IMAP base [RFC3501]. + ; Add new "esearch" command. + + filter-mailboxes-other =/ ("subtree-one" SP one-or-more-mailbox) + ; Update definition from IMAP Notify [RFC5465]. + ; Add new "subtree-one" selector. + + filter-mailboxes-selected = "selected" + ; Update definition from IMAP Notify [RFC5465]. + ; We forbid the use of "selected-delayed". + + one-correlator = ("TAG" SP tag-string) / ("MAILBOX" SP astring) / + ("UIDVALIDITY" SP nz-number) + ; Each correlator MUST appear exactly once. + + scope-option = scope-option-name [SP scope-option-value] + ; No options defined here. Syntax for future extensions. + + scope-option-name = tagged-ext-label + ; No options defined here. Syntax for future extensions. + + scope-option-value = tagged-ext-val + ; No options defined here. Syntax for future extensions. + + + + + + +Leiba & Melnikov Experimental [Page 7] + +RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011 + + + scope-options = scope-option *(SP scope-option) + ; A given option may only appear once. + ; No options defined here. Syntax for future extensions. + + esearch = "ESEARCH" [SP esearch-source-opts] + [SP search-return-opts] SP search-program + + search-correlator = SP "(" one-correlator *(SP one-correlator) ")" + ; Updates definition in IMAP4 ABNF [RFC4466]. + + esearch-source-opts = "IN" SP "(" source-mbox [SP + "(" scope-options ")"] ")" + + source-mbox = filter-mailboxes *(SP filter-mailboxes) + ; "filter-mailboxes" is defined in IMAP Notify [RFC5465]. + ; See updated definition of filter-mailboxes-other, above. + ; See updated definition of filter-mailboxes-selected, above. + +5. Security Considerations + + This new IMAP ESEARCH command allows a single command to search many + mailboxes at once. On the one hand, a client could do that by + sending many IMAP SEARCH commands. On the other hand, this makes it + easier for a client to overwork a server, by sending a single command + that results in an expensive search of tens of thousands of + mailboxes. Server implementations need to be aware of that, and + provide mechanisms that prevent a client from adversely affecting + other users. Limitations on the number of mailboxes that may be + searched in one command, and/or on the server resources that will be + devoted to responding to a single client, are reasonable limitations + for an implementation to impose. + + Implementations MUST, of course, apply access controls appropriately, + limiting a user's access to ESEARCH in the same way its access is + limited for any other IMAP commands. This extension has no data- + access risks beyond what may be there in the unextended IMAP + implementation. + + Mailboxes matching the source options for which the logged-in user + lacks sufficient rights MUST be ignored by the ESEARCH command + processing (see the paragraph about this in Section 2.2). In + particular, any attempt to distinguish insufficient access from + non-existent mailboxes may expose information about the mailbox + hierarchy that isn't otherwise available to the client. + + If "subtree" is specified, the server MUST defend against loops in + the hierarchy (see the paragraph about this in Section 2.2). + + + + +Leiba & Melnikov Experimental [Page 8] + +RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011 + + +6. IANA Considerations + + IMAP4 capabilities are registered by publishing a Standards Track or + IESG-approved Experimental RFC. The "IMAP 4 Capabilities" registry + is currently located here: + + http://www.iana.org/ + + This document defines the IMAP capability "MULTISEARCH", and IANA has + added it to the registry. + +7. Acknowledgements + + The authors gratefully acknowledge feedback provided by Timo + Sirainen, Peter Coates, and Arnt Gulbrandsen. + +8. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2978] Freed, N. and J. Postel, "IANA Charset Registration + Procedures", BCP 19, RFC 2978, October 2000. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) Extension", + RFC 4314, December 2005. + + [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 + ABNF", RFC 4466, April 2006. + + [RFC4731] Melnikov, A. and D. Cridland, "IMAP4 Extension to SEARCH + Command for Controlling What Kind of Information Is + Returned", RFC 4731, November 2006. + + [RFC5182] Melnikov, A., "IMAP Extension for Referencing the Last + SEARCH Result", RFC 5182, March 2008. + + [RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", STD 68, RFC 5234, + January 2008. + + [RFC5267] Cridland, D. and C. King, "Contexts for IMAP4", RFC 5267, + July 2008. + + + + + +Leiba & Melnikov Experimental [Page 9] + +RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011 + + + [RFC5465] Gulbrandsen, A., King, C., and A. Melnikov, "The IMAP + NOTIFY Extension", RFC 5465, February 2009. + +Authors' Addresses + + Barry Leiba + Huawei Technologies + + Phone: +1 646 827 0648 + EMail: barryleiba@computer.org + URI: http://internetmessagingtechnology.org/ + + + Alexey Melnikov + Isode Limited + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: Alexey.Melnikov@isode.com + URI: http://www.melnikov.ca/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Leiba & Melnikov Experimental [Page 10] + diff --git a/docs/rfcs/rfc6331.Moving_Digest-MD5_to_Historic b/docs/rfcs/rfc6331.Moving_Digest-MD5_to_Historic new file mode 100644 index 0000000..3d4172f --- /dev/null +++ b/docs/rfcs/rfc6331.Moving_Digest-MD5_to_Historic @@ -0,0 +1,339 @@ + + + + + + +Internet Engineering Task Force (IETF) A. Melnikov +Request for Comments: 6331 Isode Limited +Obsoletes: 2831 July 2011 +Category: Informational +ISSN: 2070-1721 + + + Moving DIGEST-MD5 to Historic + +Abstract + + This memo describes problems with the DIGEST-MD5 Simple + Authentication and Security Layer (SASL) mechanism as specified in + RFC 2831. It marks DIGEST-MD5 as OBSOLETE in the IANA Registry of + SASL mechanisms and moves RFC 2831 to Historic status. + +Status of This Memo + + This document is not an Internet Standards Track specification; it is + published for informational purposes. + + 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). Not all documents + approved by the IESG are a candidate for any level of Internet + Standard; see Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc6331. + +Copyright Notice + + Copyright (c) 2011 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 + (http://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 Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + + + +Melnikov Informational [Page 1] + +RFC 6331 Moving DIGEST-MD5 to Historic July 2011 + + + This document may contain material from IETF Documents or IETF + Contributions published or made publicly available before November + 10, 2008. The person(s) controlling the copyright in some of this + material may not have granted the IETF Trust the right to allow + modifications of such material outside the IETF Standards Process. + Without obtaining an adequate license from the person(s) controlling + the copyright in such materials, this document may not be modified + outside the IETF Standards Process, and derivative works of it may + not be created outside the IETF Standards Process, except to format + it for publication as an RFC or to translate it into languages other + than English. + +Table of Contents + + 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 2 + 2. Security Considerations . . . . . . . . . . . . . . . . . . . 5 + 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 + 4. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 5 + 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 5.1. Normative References . . . . . . . . . . . . . . . . . . . . 5 + 5.2. Informative References . . . . . . . . . . . . . . . . . . . 5 + +1. Introduction and Overview + + [RFC2831] defines how HTTP Digest Authentication [RFC2617] can be + used as a Simple Authentication and Security Layer (SASL) [RFC4422] + mechanism for any protocol that has a SASL profile. It was intended + both as an improvement over CRAM-MD5 [RFC2195] and as a convenient + way to support a single authentication mechanism for web, email, the + Lightweight Directory Access Protocol (LDAP), and other protocols. + While it can be argued that it is an improvement over CRAM-MD5, many + implementors commented that the additional complexity of DIGEST-MD5 + makes it difficult to implement fully and securely. + + Below is an incomplete list of problems with the DIGEST-MD5 mechanism + as specified in [RFC2831]: + + 1. The mechanism has too many options and modes. Some of them are + not well described and are not widely implemented. For example, + DIGEST-MD5 allows the "qop" directive to contain multiple values, + but it also allows for multiple qop directives to be specified. + The handling of multiple options is not specified, which results + in minor interoperability problems. Some implementations + amalgamate multiple qop values into one, while others treat + multiple qops as an error. Another example is the use of an + empty authorization identity. In SASL, an empty authorization + identity means that the client is willing to authorize as the + authentication identity. The document is not clear on whether + + + +Melnikov Informational [Page 2] + +RFC 6331 Moving DIGEST-MD5 to Historic July 2011 + + + the authzid must be omitted or if it can be specified with an + empty value to convey this. The requirement for backward + compatibility with HTTP Digest means that the situation is even + worse. For example, DIGEST-MD5 requires all usernames/passwords + that can be entirely represented in the ISO-8859-1 charset to be + down converted from UTF-8 [RFC3629] to ISO-8859-1 [ISO-8859-1]. + Another example is the use of quoted strings. Handling of + characters that need escaping is not properly described, and the + DIGEST-MD5 document has no examples to demonstrate correct + behavior. + + 2. The DIGEST-MD5 document uses ABNF from RFC 822 [RFC0822], which + allows an extra construct and allows for "implied folding + whitespace" to be inserted in many places. The difference from a + more common ABNF defined in [RFC5234] is confusing for some + implementors. As a result, many implementations do not accept + folding whitespace in many places where it is allowed. + + 3. The DIGEST-MD5 document uses the concept of a "realm" to define a + collection of accounts. A DIGEST-MD5 server can support one or + more realms. The DIGEST-MD5 document does not provide any + guidance on how realms should be named and, more importantly, how + they can be entered in User Interfaces (UIs). As a result, many + DIGEST-MD5 clients have confusing UIs, do not allow users to + enter a realm, and/or do not allow users to pick one of the + server-supported realms. + + 4. Use of username in the inner hash is problematic. The inner hash + of DIGEST-MD5 is an MD5 hash of colon-separated username, realm, + and password. Implementations may choose to store inner hashes + instead of clear text passwords. This has some useful + properties, such as protection from compromise of authentication + databases containing the same username and password on other + servers if a server with the username and password is + compromised; however, this is rarely done in practice. First, + the inner hash is not compatible with widely deployed Unix + password databases, and second, changing the username would + invalidate the inner hash. + + 5. Description of DES/3DES [DES] and RC4 security layers are + inadequate to produce independently developed interoperable + implementations. In the DES/3DES case, this is partly a problem + with existing DES APIs. + + 6. DIGEST-MD5 outer hash (the value of the "response" directive) + does not protect the whole authentication exchange, which makes + the mechanism vulnerable to "man-in-the-middle" (MITM) attacks, + such as modification of the list of supported qops or ciphers. + + + +Melnikov Informational [Page 3] + +RFC 6331 Moving DIGEST-MD5 to Historic July 2011 + + + 7. The following features are missing from DIGEST-MD5, making it + insecure or unsuitable for use in protocols: + + A. Channel bindings [RFC5056]. + + B. Hash agility (i.e., no easy way to replace the MD5 hash + function with another one). + + C. Support for SASLPrep [RFC4013] or any other type of Unicode + character normalization of usernames and passwords. The + original DIGEST-MD5 document predates SASLPrep and does not + recommend any Unicode character normalization. + + 8. The cryptographic primitives in DIGEST-MD5 are not up to today's + standards, in particular: + + A. The MD5 hash is sufficiently weak to make a brute force + attack on DIGEST-MD5 easy with common hardware [RFC6151]. + + B. The RC4 algorithm is prone to attack when used as the + security layer without discarding the initial key stream + output [RFC6229]. + + C. The DES cipher for the security layer is considered insecure + due to its small key space [RFC3766]. + + Note that most of the problems listed above are already present in + the HTTP Digest authentication mechanism. + + Because DIGEST-MD5 is defined as an extensible mechanism, it is + possible to fix most of the problems listed above. However, this + would increase implementation complexity of an already complex + mechanism even further, so the effort is not worth the cost. In + addition, an implementation of a "fixed" DIGEST-MD5 specification + would likely either not interoperate with any existing implementation + of [RFC2831] or would be vulnerable to various downgrade attacks. + + Note that despite DIGEST-MD5 seeing some deployment on the Internet, + this specification recommends obsoleting DIGEST-MD5 because DIGEST- + MD5, as implemented, is not a reasonable candidate for further + standardization and should be deprecated in favor of one or more new + password-based mechanisms currently being designed. + + The Salted Challenge Response Authentication Mechanism (SCRAM) family + of SASL mechanisms [RFC5802] has been developed to provide similar + features as DIGEST-MD5 but with a better design. + + + + + +Melnikov Informational [Page 4] + +RFC 6331 Moving DIGEST-MD5 to Historic July 2011 + + +2. Security Considerations + + Security issues are discussed throughout this document. + +3. IANA Considerations + + IANA has changed the "Intended usage" of the DIGEST-MD5 mechanism + registration in the SASL mechanism registry to OBSOLETE. The SASL + mechanism registry is specified in [RFC4422] and is currently + available at: + + http://www.iana.org/assignments/sasl-mechanisms + +4. Acknowledgements + + The author gratefully acknowledges the feedback provided by Chris + Newman, Simon Josefsson, Kurt Zeilenga, Sean Turner, and Abhijit + Menon-Sen. Various text was copied from other RFCs, in particular, + from [RFC2831]. + +5. References + +5.1. Normative References + + [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, + S., Leach, P., Luotonen, A., and L. Stewart, "HTTP + Authentication: Basic and Digest Access + Authentication", RFC 2617, June 1999. + + [RFC2831] Leach, P. and C. Newman, "Using Digest Authentication + as a SASL Mechanism", RFC 2831, May 2000. + +5.2. Informative References + + [DES] National Institute of Standards and Technology, "Data + Encryption Standard (DES)", FIPS PUB 46-3, + October 1999. + + [ISO-8859-1] International Organization for Standardization, + "Information technology - 8-bit single-byte coded + graphic character sets - Part 1: Latin alphabet No. 1", + ISO/IEC 8859-1, 1998. + + [RFC0822] Crocker, D., "Standard for the format of ARPA Internet + text messages", STD 11, RFC 822, August 1982. + + + + + + +Melnikov Informational [Page 5] + +RFC 6331 Moving DIGEST-MD5 to Historic July 2011 + + + [RFC2195] Klensin, J., Catoe, R., and P. Krumviede, "IMAP/POP + AUTHorize Extension for Simple Challenge/Response", + RFC 2195, September 1997. + + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. + + [RFC3766] Orman, H. and P. Hoffman, "Determining Strengths For + Public Keys Used For Exchanging Symmetric Keys", + BCP 86, RFC 3766, April 2004. + + [RFC4013] Zeilenga, K., "SASLprep: Stringprep Profile for User + Names and Passwords", RFC 4013, February 2005. + + [RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication + and Security Layer (SASL)", RFC 4422, June 2006. + + [RFC5056] Williams, N., "On the Use of Channel Bindings to Secure + Channels", RFC 5056, November 2007. + + [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + + [RFC5802] Newman, C., Menon-Sen, A., Melnikov, A., and N. + Williams, "Salted Challenge Response Authentication + Mechanism (SCRAM) SASL and GSS-API Mechanisms", + RFC 5802, July 2010. + + [RFC6151] Turner, S. and L. Chen, "Updated Security + Considerations for the MD5 Message-Digest and the HMAC- + MD5 Algorithms", RFC 6151, March 2011. + + [RFC6229] Strombergson, J. and S. Josefsson, "Test Vectors for + the Stream Cipher RC4", RFC 6229, May 2011. + +Author's Address + + Alexey Melnikov + Isode Limited + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: Alexey.Melnikov@isode.com + URI: http://www.melnikov.ca/ + + + + + +Melnikov Informational [Page 6] +