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
+
+
+
+
+
+
+
+
+
+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]
+
+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 | (