diff options
| author | Eduardo Chappa <chappa@washington.edu> | 2013-06-03 10:30:56 -0600 |
|---|---|---|
| committer | Eduardo Chappa <chappa@washington.edu> | 2013-06-03 10:30:56 -0600 |
| commit | e4b35478c8b3ce7352a74b2fea0e067f068daf18 (patch) | |
| tree | 0b8a97debddc8210c6696c252c26f03703b606fa /imap/docs/rfc | |
| parent | a46157ba61f2c65f88b42abb31db60c4a714f87b (diff) | |
| download | alpine-e4b35478c8b3ce7352a74b2fea0e067f068daf18.tar.xz | |
* Changes to configure.ac to add -lkrb5 to the link
* Changes to avoud errors in compilation when -Wformat-security is used
* Remove RFC files from source code
Diffstat (limited to 'imap/docs/rfc')
44 files changed, 0 insertions, 35256 deletions
diff --git a/imap/docs/rfc/README b/imap/docs/rfc/README deleted file mode 100644 index 550d8d20..00000000 --- a/imap/docs/rfc/README +++ /dev/null @@ -1,70 +0,0 @@ -The following documents are necessary to understand the syntax rules -most of the remaining documents. Note that some documents refer to -RFC 2234 which has been replaced by RFC 5234: - rfc5234.txt Augmented BNF for Syntax Specifications - ABNF - rfc4466.txt Collected Extensions to IMAP4 ABNF - - -The following documents specify the IMAP protocol: - rfc3501.txt Internet Message Access Protocol - Version 4rev1 - - -The following documents provide additional information which is useful -in understanding the IMAP protocol: - rfc1733.txt Distributed Electronic Mail Models in IMAP4 - rfc2180.txt IMAP4 Multi-Accessed Mailbox Practice - rfc2683.txt IMAP4 Implementation Recommendations - rfc4549.txt Synchronization Operations for Disconnected IMAP4 Clients - - -The following documents describe extensions to the IMAP protocol. -Items marked with "*" are supported in this distribution: - rfc4314.txt ACL - * rfc3516.txt BINARY - rfc4469.txt CATENATE - * rfc3348.txt CHILDREN - rfc4978.txt COMPRESS - rfc4551.txt CONDSTORE - rfc5161.txt ENABLE - * rfc4731.txt ESEARCH - rfc2971.txt ID - * rfc2177.txt IDLE - * rfc2088.txt LITERAL+ - * rfc2221.txt LOGIN-REFERRALS - * rfc2193.txt MAILBOX-REFERRALS - * rfc3502.txt MULTIAPPEND - * rfc2342.txt NAMESPACE - rfc5162.txt QRESYNC - rfc2087.txt QUOTA - * rfc4959.txt SASL-IR - * rfc4315.txt UIDPLUS - * rfc3691.txt UNSELECT - rfc4467.txt URLAUTH - * rfc5032.txt WITHIN - - -The following documents describe SASL: - rfc4422.txt Simple Authentication and Security Layer (SASL) -and the SASL mechanisms supported in this distribution: - rfc4505.txt ANONYMOUS - rfc2195.txt CRAM-MD5 - rfc4752.txt GSSAPI - rfc4616.txt PLAIN - - -The following documents relate to internationalization issues: - rfc4790.txt Internet Application Protocol Collation Registry - rfc5051.txt i;unicode-casemap - Simple Unicode Collation Algorithm - - -The following documents are primarily of historic interest: - rfc1732.txt IMAP4 Compatibility with IMAP2 and IMAP2bis - rfc2061.txt IMAP4 Compatibility with IMAP2bis - rfc2062.txt Internet Message Access Protocol - Obsolete Syntax - - -The following documents discuss matters which are related to IMAP: - rfc3503.txt MDN Profile for IMAP - rfc3656.txt MUPDATE Distributed Mailbox Database Protocol - rfc4468.txt Message Submission BURL Extension - rfc5092.txt IMAP URL Scheme diff --git a/imap/docs/rfc/rfc1732.txt b/imap/docs/rfc/rfc1732.txt deleted file mode 100644 index cfae89c0..00000000 --- a/imap/docs/rfc/rfc1732.txt +++ /dev/null @@ -1,283 +0,0 @@ - - - - - - -Network Working Group M. Crispin -Request for Comments: 1732 University of Washington -Category: Informational December 1994 - - - IMAP4 COMPATIBILITY WITH IMAP2 AND IMAP2BIS - - -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. - -Introduction - - This is a summary of hints and recommendations to enable an IMAP4 - implementation to interoperate with implementations that conform to - earlier specifications. None of these hints and recommendations are - required by the IMAP4 specification; implementors must decide for - themselves whether they want their implementation to fail if it - encounters old software. - - IMAP4 has been designed to be upwards compatible with earlier - specifications. For the most part, IMAP4 facilities that were not in - earlier specifications should be invisible to clients unless the - client asks for the facility. - - In some cases, older servers may support some of the capabilities - listed as being "new in IMAP4" as experimental extensions to the - IMAP2 protocol described in RFC 1176. - - This information may not be complete; it reflects current knowledge - of server and client implementations as well as "folklore" acquired - in the evolution of the protocol. - - - - - - - - - - - - - - - - -Crispin [Page 1] - -RFC 1732 IMAP4 - Compatibility December 1994 - - -IMAP4 client interoperability with old servers - - In general, a client should be able to discover whether an IMAP2 - server supports a facility by trial-and-error; if an attempt to use a - facility generates a BAD response, the client can assume that the - server does not support the facility. - - A quick way to check whether a server implementation supports the - IMAP4 specification is to try the CAPABILITY command. An OK response - that includes the IMAP4 capability value indicates a server that - supports IMAP4; a BAD response or one without the IMAP4 capability - value indicates an older server. - - The following is a list of facilities that are only in IMAP4, and - suggestions for how new clients might interoperate with old servers: - - CAPABILITY command - A BAD response to this command indicates that the server - implements IMAP2 (or IMAP2bis) and not IMAP4. - - AUTHENTICATE command. - Use the LOGIN command. - - LSUB and LIST commands - Try the RFC 1176 FIND command. - - * in a sequence - Use the number of messages in the mailbox from the EXISTS - unsolicited response. - - SEARCH extensions (character set, additional criteria) - Reformulate the search request using only the searching - options listed in search_old in the IMAP4 grammar. This may - entail doing multiple searches to achieve the desired - results. - - BODYSTRUCTURE fetch data item - Try to fetch the non-extensible BODY data item. - - body section number 0 - Fetch the entire message and extract the header. - - RFC822.HEADER.LINES and RFC822.HEADER.LINES.NOT fetch data items - Use RFC822.HEADER and remove the unwanted information. - - BODY.PEEK[section], RFC822.PEEK, and RFC822.TEXT.PEEK fetch data - items Use the corresponding non-PEEK versions and manually - clear the \Seen flag as necessary. - - - -Crispin [Page 2] - -RFC 1732 IMAP4 - Compatibility December 1994 - - - UID fetch data item and the UID commands - No equivalent capabilitity exists in older servers. - - FLAGS.SILENT, +FLAGS.SILENT, and -FLAGS.SILENT store data items - Use the corresponding non-SILENT versions and ignore the - untagged FETCH responses which com eback. - - - The following IMAP4 facilities were introduced in the experimental - IMAP2bis revisions to RFC-1176, and may be present in a server that - does not support the CAPABILITY command: - - CREATE, DELETE, and RENAME commands - To test whether these commands are present, try a CREATE - INBOX command. If the response is NO, these commands are - supported by the server. If the response is BAD, they are - not. Older servers without the CREATE capability may sup- - port implicit creation of a mailbox by a COPY command with a - non-existant name as the destination. - - APPEND command - To test whether this command is present, try to append a - zero-length stream to a mailbox name that is known not to - exist (or at least, highly unlikely to exist) on the remote - system. - - SUBSCRIBE and UNSUBSCRIBE commands - Try the form of these commands with the optional MAILBOX - keyword. - - EXAMINE command - Use the SELECT command instead. - - flags and internal date argument to APPEND command - Try the APPEND without any flag list and internal date argu- - ments. - - BODY, BODY[section], and FULL fetch data items - Use RFC822.TEXT and ALL instead. Server does not support - MIME. - - PARTIAL command - Use the appropriate FETCH command and ignore the unwanted - data. - - - IMAP4 client implementations must accept all responses and data for- - mats documented in the IMAP4 specification, including those labeled - - - -Crispin [Page 3] - -RFC 1732 IMAP4 - Compatibility December 1994 - - - as obsolete. This includes the COPY and STORE unsolicited responses - and the old format of dates and times. In particular, client imple- - mentations must not treat a date/time as a fixed format string; nor - may they assume that the time begins at a particular octet. - - IMAP4 client implementations must not depend upon the presence of any - server extensions that are not in the base IMAP4 specification. - - The experimental IMAP2bis version specified that the TRYCREATE spe- - cial information token is sent as a separate unsolicited OK response - instead of inside the NO response. - - The FIND BBOARDS, FIND ALL.BBOARDS, and BBOARD commands of RFC 1176 - are removed from IMAP4. There is no equivalent to the bboard com- - mands, which provided a separate namespace with implicit restrictions - on what may be done in that namespace. - - Older server implementations may automatically create the destination - mailbox on COPY if that mailbox does not already exist. This was how - a new mailbox was created in older specifications. If the server - does not support the CREATE command (see above for how to test for - this), it will probably create a mailbox on COPY. - - Older server implementations may not preserve flags or internal dates - on COPY. Some server implementations may not permit the preservation - of certain flags on COPY or their setting with APPEND as site policy. - - - - - - - - - - - - - - - - - - - - - - - - - -Crispin [Page 4] - -RFC 1732 IMAP4 - Compatibility December 1994 - - -IMAP4 server interoperability with old clients - - In general, there should be no interoperation problem between a - server conforming to the IMAP4 specification and a well-written - client that conforms to an earlier specification. Known problems are - noted below: - - Poor wording in the description of the CHECK command in earlier - specifications implied that a CHECK command is the way to get the - current number of messages in the mailbox. This is incorrect. A - CHECK command does not necessarily result in an EXISTS response. - Clients must remember the most recent EXISTS value sent from the - server, and should not generate unnecessary CHECK commands. - - An incompatibility exists with COPY in IMAP4. COPY in IMAP4 - servers does not automatically create the destination mailbox if - that mailbox does not already exist. This may cause problems with - old clients that expect automatic mailbox creation in COPY. - - The PREAUTH unsolicited response is new in IMAP4. It is highly - unlikely that an old client would ever see this response. - - The format of dates and times has changed due to the impending end - of the century. Clients that fail to accept a four-digit year or - a signed four-digit timezone value will not work properly with - IMAP4. - - An incompatibility exists with the use of "\" in quoted strings. - This is best avoided by using literals instead of quoted strings - if "\" or <"> is embedded in the string. - -Security Considerations - - Security issues are not discussed in this memo. - -Author's Address: - - Mark R. Crispin - Networks and Distributed Computing, JE-30 - University of Washington - Seattle, WA 98195 - - Phone: (206) 543-5762 - - EMail: MRC@CAC.Washington.EDU - - - - - - -Crispin [Page 5] - diff --git a/imap/docs/rfc/rfc1733.txt b/imap/docs/rfc/rfc1733.txt deleted file mode 100644 index 2ec385f0..00000000 --- a/imap/docs/rfc/rfc1733.txt +++ /dev/null @@ -1,171 +0,0 @@ - - - - - - -Network Working Group M. Crispin -Request for Comments: 1733 University of Washington -Category: Informational December 1994 - - - DISTRIBUTED ELECTRONIC MAIL MODELS IN IMAP4 - - -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. - - -Distributed Electronic Mail Models - - There are three fundamental models of client/server email: offline, - online, and disconnected use. IMAP4 can be used in any one of these - three models. - - The offline model is the most familiar form of client/server email - today, and is used by protocols such as POP-3 (RFC 1225) and UUCP. - In this model, a client application periodically connects to a - server. It downloads all the pending messages to the client machine - and deletes these from the server. Thereafter, all mail processing - is local to the client. This model is store-and-forward; it moves - mail on demand from an intermediate server (maildrop) to a single - destination machine. - - The online model is most commonly used with remote filesystem - protocols such as NFS. In this model, a client application - manipulates mailbox data on a server machine. A connection to the - server is maintained throughout the session. No mailbox data are - kept on the client; the client retrieves data from the server as is - needed. IMAP4 introduces a form of the online model that requires - considerably less network bandwidth than a remote filesystem - protocol, and provides the opportunity for using the server for CPU - or I/O intensive functions such as parsing and searching. - - The disconnected use model is a hybrid of the offline and online - models, and is used by protocols such as PCMAIL (RFC 1056). In this - model, a client user downloads some set of messages from the server, - manipulates them offline, then at some later time uploads the - changes. The server remains the authoritative repository of the - messages. The problems of synchronization (particularly when - multiple clients are involved) are handled through the means of - unique identifiers for each message. - - - -Crispin [Page 1] - -RFC 1733 IMAP4 - Model December 1994 - - - Each of these models have their own strengths and weaknesses: - - Feature Offline Online Disc - ------- ------- ------ ---- - Can use multiple clients NO YES YES - Minimum use of server connect time YES NO YES - Minimum use of server resources YES NO NO - Minimum use of client disk resources NO YES NO - Multiple remote mailboxes NO YES YES - Fast startup NO YES NO - Mail processing when not online YES NO YES - - Although IMAP4 has its origins as a protocol designed to accommodate - the online model, it can support the other two models as well. This - makes possible the creation of clients that can be used in any of the - three models. For example, a user may wish to switch between the - online and disconnected models on a regular basis (e.g. owing to - travel). - - IMAP4 is designed to transmit message data on demand, and to provide - the facilities necessary for a client to decide what data it needs at - any particular time. There is generally no need to do a wholesale - transfer of an entire mailbox or even of the complete text of a - message. This makes a difference in situations where the mailbox is - large, or when the link to the server is slow. - - More specifically, IMAP4 supports server-based RFC 822 and MIME - processing. With this information, it is possible for a client to - determine in advance whether it wishes to retrieve a particular - message or part of a message. For example, a user connected to an - IMAP4 server via a dialup link can determine that a message has a - 2000 byte text segment and a 40 megabyte video segment, and elect to - fetch only the text segment. - - In IMAP4, the client/server relationship lasts only for the duration - of the TCP connection. There is no registration of clients. Except - for any unique identifiers used in disconnected use operation, the - client initially has no knowledge of mailbox state and learns it from - the IMAP4 server when a mailbox is selected. This initial transfer - is minimal; the client requests additional state data as it needs. - - As noted above, the choice for the location of mailbox data depends - upon the model chosen. The location of message state (e.g. whether - or not a message has been read or answered) is also determined by the - model, and is not necessarily the same as the location of the mailbox - data. For example, in the online model message state can be co- - located with mailbox data; it can also be located elsewhere (on the - client or on a third agent) using unique identifiers to achieve - - - -Crispin [Page 2] - -RFC 1733 IMAP4 - Model December 1994 - - - common reference across sessions. The latter is particularly useful - with a server that exports public data such as netnews and does not - maintain per-user state. - - The IMAP4 protocol provides the generality to implement these - different models. This is done by means of server and (especially) - client configuration, and not by requiring changes to the protocol or - the implementation of the protocol. - - -Security Considerations - - Security issues are not discussed in this memo. - - -Author's Address: - - Mark R. Crispin - Networks and Distributed Computing, JE-30 - University of Washington - Seattle, WA 98195 - - Phone: (206) 543-5762 - - EMail: MRC@CAC.Washington.EDU - - - - - - - - - - - - - - - - - - - - - - - - - - -Crispin [Page 3] - diff --git a/imap/docs/rfc/rfc2061.txt b/imap/docs/rfc/rfc2061.txt deleted file mode 100644 index 7cb02bb2..00000000 --- a/imap/docs/rfc/rfc2061.txt +++ /dev/null @@ -1,171 +0,0 @@ - - - - - - -Network Working Group M. Crispin -Request for Comments: 2061 University of Washington -Category: Informational December 1996 - - - IMAP4 COMPATIBILITY WITH IMAP2BIS - -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. - -Introduction - - The Internet Message Access Protocol (IMAP) has been through several - revisions and variants in its 10-year history. Many of these are - either extinct or extremely rare; in particular, several undocumented - variants and the variants described in RFC 1064, RFC 1176, and RFC - 1203 fall into this category. - - One variant, IMAP2bis, is at the time of this writing very common and - has been widely distributed with the Pine mailer. Unfortunately, - there is no definite document describing IMAP2bis. This document is - intended to be read along with RFC 1176 and the most recent IMAP4 - specification (RFC 2060) to assist implementors in creating an IMAP4 - implementation to interoperate with implementations that conform to - earlier specifications. Nothing in this document is required by the - IMAP4 specification; implementors must decide for themselves whether - they want their implementation to fail if it encounters old software. - - At the time of this writing, IMAP4 has been updated from the version - described in RFC 1730. An implementor who wishes to interoperate - with both RFC 1730 and RFC 2060 should refer to both documents. - - This information is not complete; it reflects current knowledge of - server and client implementations as well as "folklore" acquired in - the evolution of the protocol. It is NOT a description of how to - interoperate with all variants of IMAP, but rather with the old - variant that is most likely to be encountered. For detailed - information on interoperating with other old variants, refer to RFC - 1732. - -IMAP4 client interoperability with IMAP2bis servers - - A quick way to check whether a server implementation supports the - IMAP4 specification is to try the CAPABILITY command. An OK response - will indicate which variant(s) of IMAP4 are supported by the server. - - - -Crispin Informational [Page 1] - -RFC 2061 IMAP4 Compatibility December 1996 - - - If the client does not find any of its known variant in the response, - it should treat the server as IMAP2bis. A BAD response indicates an - IMAP2bis or older server. - - Most IMAP4 facilities are in IMAP2bis. The following exceptions - exist: - - CAPABILITY command - The absense of this command indicates IMAP2bis (or older). - - AUTHENTICATE command. - Use the LOGIN command. - - LSUB, SUBSCRIBE, and UNSUBSCRIBE commands - No direct functional equivalent. IMAP2bis had a concept - called "bboards" which is not in IMAP4. RFC 1176 supported - these with the BBOARD and FIND BBOARDS commands. IMAP2bis - augmented these with the FIND ALL.BBOARDS, SUBSCRIBE BBOARD, - and UNSUBSCRIBE BBOARD commands. It is recommended that - none of these commands be implemented in new software, - including servers that support old clients. - - LIST command - Use the command FIND ALL.MAILBOXES, which has a similar syn- - tax and response to the FIND MAILBOXES command described in - RFC 1176. The FIND MAILBOXES command is unlikely to produce - useful information. - - * in a sequence - Use the number of messages in the mailbox from the EXISTS - unsolicited response. - - SEARCH extensions (character set, additional criteria) - Reformulate the search request using only the RFC 1176 syn- - tax. This may entail doing multiple searches to achieve the - desired results. - - BODYSTRUCTURE fetch data item - Use the non-extensible BODY data item. - - body sections HEADER, TEXT, MIME, HEADER.FIELDS, HEADER.FIELDS.NOT - Use body section numbers only. - - BODY.PEEK[section] - Use BODY[section] and manually clear the \Seen flag as - necessary. - - - - - -Crispin Informational [Page 2] - -RFC 2061 IMAP4 Compatibility December 1996 - - - FLAGS.SILENT, +FLAGS.SILENT, and -FLAGS.SILENT store data items - Use the corresponding non-SILENT versions and ignore the - untagged FETCH responses which come back. - - UID fetch data item and the UID commands - No functional equivalent. - - CLOSE command - No functional equivalent. - - - In IMAP2bis, the TRYCREATE special information token is sent as a - separate unsolicited OK response instead of inside the NO response. - - IMAP2bis is ambiguous about whether or not flags or internal dates - are preserved on COPY. It is impossible to know what behavior is - supported by the server. - -IMAP4 server interoperability with IMAP2bis clients - - The only interoperability problem between an IMAP4 server and a - well-written IMAP2bis client is an incompatibility with the use of - "\" in quoted strings. This is best avoided by using literals - instead of quoted strings if "\" or <"> is embedded in the string. - -Security Considerations - - Security issues are not discussed in this memo. - -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 3] - diff --git a/imap/docs/rfc/rfc2062.txt b/imap/docs/rfc/rfc2062.txt deleted file mode 100644 index 865d1dad..00000000 --- a/imap/docs/rfc/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[<section>], 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: <gray@cac.washington.edu> - 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 <header_list> - Functionally equivalent to BODY.PEEK[HEADER.LINES - <header_list>], 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 <header_list> - Functionally equivalent to - BODY.PEEK[HEADER.LINES.NOT <header_list>], - 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/imap/docs/rfc/rfc2087.txt b/imap/docs/rfc/rfc2087.txt deleted file mode 100644 index 1db5b57b..00000000 --- a/imap/docs/rfc/rfc2087.txt +++ /dev/null @@ -1,283 +0,0 @@ - - - - - - -Network Working Group J. Myers -Request for Comments: 2087 Carnegie Mellon -Category: Standards Track January 1997 - - - IMAP4 QUOTA 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. - -1. Abstract - - The QUOTA extension of the Internet Message Access Protocol [IMAP4] - permits administrative limits on resource usage (quotas) to be - manipulated through the IMAP protocol. - -Table of Contents - - 1. Abstract........................................... 1 - 2. Conventions Used in this Document.................. 1 - 3. Introduction and Overview.......................... 2 - 4. Commands........................................... 2 - 4.1. SETQUOTA Command................................... 2 - 4.2. GETQUOTA Command................................... 2 - 4.3. GETQUOTAROOT Command............................... 3 - 5. Responses.......................................... 3 - 5.1. QUOTA Response..................................... 3 - 5.2. QUOTAROOT Response................................. 4 - 6. Formal syntax...................................... 4 - 7. References......................................... 5 - 8. Security Considerations............................ 5 - 9. Author's Address................................... 5 - - -2. Conventions Used in this Document - - In examples, "C:" and "S:" indicate lines sent by the client and - server respectively. - - - - - - - - -Myers Standards Track [Page 1] - -RFC 2087 QUOTA January 1997 - - -3. Introduction and Overview - - The QUOTA extension is present in any IMAP4 implementation which - returns "QUOTA" as one of the supported capabilities to the - CAPABILITY command. - - An IMAP4 server which supports the QUOTA capability may support - limits on any number of resources. Each resource has an atom name - and an implementation-defined interpretation which evaluates to an - integer. Examples of such resources are: - - Name Interpretation - - STORAGE Sum of messages' RFC822.SIZE, in units of 1024 octets - MESSAGE Number of messages - - - Each mailbox has zero or more implementation-defined named "quota - roots". Each quota root has zero or more resource limits. All - mailboxes that share the same named quota root share the resource - limits of the quota root. - - Quota root names do not necessarily have to match the names of - existing mailboxes. - -4. Commands - -4.1. SETQUOTA Command - - Arguments: quota root - list of resource limits - - Data: untagged responses: QUOTA - - Result: OK - setquota completed - NO - setquota error: can't set that data - BAD - command unknown or arguments invalid - - The SETQUOTA command takes the name of a mailbox quota root and a - list of resource limits. The resource limits for the named quota root - are changed to be the specified limits. Any previous resource limits - for the named quota root are discarded. - - If the named quota root did not previously exist, an implementation - may optionally create it and change the quota roots for any number of - existing mailboxes in an implementation-defined manner. - - - - - -Myers Standards Track [Page 2] - -RFC 2087 QUOTA January 1997 - - - Example: C: A001 SETQUOTA "" (STORAGE 512) - S: * QUOTA "" (STORAGE 10 512) - S: A001 OK Setquota completed - -4.2. GETQUOTA Command - - Arguments: quota root - - Data: untagged responses: QUOTA - - Result: OK - getquota completed - NO - getquota error: no such quota root, permission - denied - BAD - command unknown or arguments invalid - - The GETQUOTA command takes the name of a quota root and returns the - quota root's resource usage and limits in an untagged QUOTA response. - - Example: C: A003 GETQUOTA "" - S: * QUOTA "" (STORAGE 10 512) - S: A003 OK Getquota completed - -4.3. GETQUOTAROOT Command - - Arguments: mailbox name - - Data: untagged responses: QUOTAROOT, QUOTA - - Result: OK - getquota completed - NO - getquota error: no such mailbox, permission denied - BAD - command unknown or arguments invalid - - The GETQUOTAROOT command takes the name of a mailbox and returns the - list of quota roots for the mailbox in an untagged QUOTAROOT - response. For each listed quota root, it also returns the quota - root's resource usage and limits in an untagged QUOTA response. - - Example: C: A003 GETQUOTAROOT INBOX - S: * QUOTAROOT INBOX "" - S: * QUOTA "" (STORAGE 10 512) - S: A003 OK Getquota completed - - - - - - - - - - -Myers Standards Track [Page 3] - -RFC 2087 QUOTA January 1997 - - -5. Responses - -5.1. QUOTA Response - - Data: quota root name - list of resource names, usages, and limits - - This response occurs as a result of a GETQUOTA or GETQUOTAROOT - command. The first string is the name of the quota root for which - this quota applies. - - The name is followed by a S-expression format list of the resource - usage and limits of the quota root. The list contains zero or - more triplets. Each triplet conatins a resource name, the current - usage of the resource, and the resource limit. - - Resources not named in the list are not limited in the quota root. - Thus, an empty list means there are no administrative resource - limits in the quota root. - - Example: S: * QUOTA "" (STORAGE 10 512) - -5.2. QUOTAROOT Response - - Data: mailbox name - zero or more quota root names - - This response occurs as a result of a GETQUOTAROOT command. The - first string is the mailbox and the remaining strings are the - names of the quota roots for the mailbox. - - Example: S: * QUOTAROOT INBOX "" - S: * QUOTAROOT comp.mail.mime - -6. Formal syntax - - The following syntax specification uses the augmented Backus-Naur - Form (BNF) notation as specified in RFC 822 with one exception; the - delimiter used with the "#" construct is a single space (SP) and not - one or more commas. - - 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. - - - - - - -Myers Standards Track [Page 4] - -RFC 2087 QUOTA January 1997 - - - getquota ::= "GETQUOTA" SP astring - - getquotaroot ::= "GETQUOTAROOT" SP astring - - quota_list ::= "(" #quota_resource ")" - - quota_resource ::= atom SP number SP number - - quota_response ::= "QUOTA" SP astring SP quota_list - - quotaroot_response - ::= "QUOTAROOT" SP astring *(SP astring) - - setquota ::= "SETQUOTA" SP astring SP setquota_list - - setquota_list ::= "(" 0#setquota_resource ")" - - setquota_resource ::= atom SP number - -7. References - - [IMAP4] Crispin, M., "Internet Message Access Protocol - Version 4", - RFC 1730, University of Washington, December 1994. - - [RFC-822] Crocker, D., "Standard for the Format of ARPA Internet - Text Messages", STD 11, RFC 822. - -8. Security Considerations - - Implementors should be careful to make sure the implementation of - these commands does not violate the site's security policy. The - resource usage of other users is likely to be considered confidential - information and should not be divulged to unauthorized persons. - -9. Author's Address - - John G. Myers - Carnegie-Mellon University - 5000 Forbes Ave. - Pittsburgh PA, 15213-3890 - - EMail: jgm+@cmu.edu - - - - - - - - - -Myers Standards Track [Page 5] - diff --git a/imap/docs/rfc/rfc2088.txt b/imap/docs/rfc/rfc2088.txt deleted file mode 100644 index f36cc764..00000000 --- a/imap/docs/rfc/rfc2088.txt +++ /dev/null @@ -1,115 +0,0 @@ - - - - - - -Network Working Group J. Myers -Request for Comments: 2088 Carnegie Mellon -Cateogry: Standards Track January 1997 - - - IMAP4 non-synchronizing literals - -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. Abstract - - The Internet Message Access Protocol [IMAP4] contains the "literal" - syntactic construct for communicating strings. When sending a - literal from client to server, IMAP4 requires the client to wait for - the server to send a command continuation request between sending the - octet count and the string data. This document specifies an - alternate form of literal which does not require this network round - trip. - -2. Conventions Used in this Document - - In examples, "C:" and "S:" indicate lines sent by the client and - server respectively. - -3. Specification - - The non-synchronizing literal is added an alternate form of literal, - and may appear in communication from client to server instead of the - IMAP4 form of literal. The IMAP4 form of literal, used in - communication from client to server, is referred to as a - synchronizing literal. - - Non-synchronizing literals may be used with any IMAP4 server - implementation which returns "LITERAL+" as one of the supported - capabilities to the CAPABILITY command. If the server does not - advertise the LITERAL+ capability, the client must use synchronizing - literals instead. - - The non-synchronizing literal is distinguished from the original - synchronizing literal by having a plus ('+') between the octet count - and the closing brace ('}'). The server does not generate a command - continuation request in response to a non-synchronizing literal, and - - - -Myers Standards Track [Page 1] - -RFC 2088 LITERAL January 1997 - - - clients are not required to wait before sending the octets of a non- - synchronizing literal. - - The protocol receiver of an IMAP4 server must check the end of every - received line for an open brace ('{') followed by an octet count, a - plus ('+'), and a close brace ('}') immediately preceeding the CRLF. - If it finds this sequence, it is the octet count of a non- - synchronizing literal and the server MUST treat the specified number - of following octets and the following line as part of the same - command. A server MAY still process commands and reject errors on a - line-by-line basis, as long as it checks for non-synchronizing - literals at the end of each line. - - Example: C: A001 LOGIN {11+} - C: FRED FOOBAR {7+} - C: fat man - S: A001 OK LOGIN completed - -4. Formal Syntax - - The following syntax specification uses the augmented Backus-Naur - Form (BNF) notation as specified in [RFC-822] as modified by [IMAP4]. - Non-terminals referenced but not defined below are as defined by - [IMAP4]. - - literal ::= "{" number ["+"] "}" CRLF *CHAR8 - ;; Number represents the number of CHAR8 octets - -6. References - - [IMAP4] Crispin, M., "Internet Message Access Protocol - Version 4", - draft-crispin-imap-base-XX.txt, University of Washington, April 1996. - - [RFC-822] Crocker, D., "Standard for the Format of ARPA Internet Text - Messages", STD 11, RFC 822. - -7. Security Considerations - - There are no known security issues with this extension. - -8. Author's Address - - John G. Myers - Carnegie-Mellon University - 5000 Forbes Ave. - Pittsburgh PA, 15213-3890 - - Email: jgm+@cmu.edu - - - -Myers Standards Track [Page 2] - diff --git a/imap/docs/rfc/rfc2177.txt b/imap/docs/rfc/rfc2177.txt deleted file mode 100644 index c11c7654..00000000 --- a/imap/docs/rfc/rfc2177.txt +++ /dev/null @@ -1,227 +0,0 @@ - - - - - - -Network Working Group B. Leiba -Request for Comments: 2177 IBM T.J. Watson Research Center -Category: Standards Track June 1997 - - - IMAP4 IDLE 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. Abstract - - The Internet Message Access Protocol [IMAP4] requires a client to - poll the server for changes to the selected mailbox (new mail, - deletions). It's often more desirable to have the server transmit - updates to the client in real time. This allows a user to see new - mail immediately. It also helps some real-time applications based on - IMAP, which might otherwise need to poll extremely often (such as - every few seconds). (While the spec actually does allow a server to - push EXISTS responses aysynchronously, a client can't expect this - behaviour and must poll.) - - This document specifies the syntax of an IDLE command, which will - allow a client to tell the server that it's ready to accept such - real-time updates. - -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", "SHOULD", "SHOULD NOT", and "MAY" - in this document are to be interpreted as described in RFC 2060 - [IMAP4]. - -3. Specification - - IDLE Command - - Arguments: none - - Responses: continuation data will be requested; the client sends - the continuation data "DONE" to end the command - - - -Leiba Standards Track [Page 1] - -RFC 2177 IMAP4 IDLE command June 1997 - - - - Result: OK - IDLE completed after client sent "DONE" - NO - failure: the server will not allow the IDLE - command at this time - BAD - command unknown or arguments invalid - - The IDLE command may be used with any IMAP4 server implementation - that returns "IDLE" as one of the supported capabilities to the - CAPABILITY command. If the server does not advertise the IDLE - capability, the client MUST NOT use the IDLE command and must poll - for mailbox updates. In particular, the client MUST continue to be - able to accept unsolicited untagged responses to ANY command, as - specified in the base IMAP specification. - - The IDLE command is sent from the client to the server when the - client is ready to accept unsolicited mailbox update messages. The - server requests a response to the IDLE command using the continuation - ("+") response. The IDLE command remains active until the client - responds to the continuation, and as long as an IDLE command is - active, the server is now free to send untagged EXISTS, EXPUNGE, and - other messages at any time. - - The IDLE command is terminated by the receipt of a "DONE" - continuation from the client; such response satisfies the server's - continuation request. At that point, the server MAY send any - remaining queued untagged responses and then MUST immediately send - the tagged response to the IDLE command and prepare to process other - commands. As in the base specification, the processing of any new - command may cause the sending of unsolicited untagged responses, - subject to the ambiguity limitations. The client MUST NOT send a - command while the server is waiting for the DONE, since the server - will not be able to distinguish a command from a continuation. - - The server MAY consider a client inactive if it has an IDLE command - running, and if such a server has an inactivity timeout it MAY log - the client off implicitly at the end of its timeout period. Because - of that, clients using IDLE are advised to terminate the IDLE and - re-issue it at least every 29 minutes to avoid being logged off. - This still allows a client to receive immediate mailbox updates even - though it need only "poll" at half hour intervals. - - - - - - - - - - - -Leiba Standards Track [Page 2] - -RFC 2177 IMAP4 IDLE command June 1997 - - - Example: C: A001 SELECT INBOX - S: * FLAGS (Deleted Seen) - S: * 3 EXISTS - S: * 0 RECENT - S: * OK [UIDVALIDITY 1] - S: A001 OK SELECT completed - C: A002 IDLE - S: + idling - ...time passes; new mail arrives... - S: * 4 EXISTS - C: DONE - S: A002 OK IDLE terminated - ...another client expunges message 2 now... - C: A003 FETCH 4 ALL - S: * 4 FETCH (...) - S: A003 OK FETCH completed - C: A004 IDLE - S: * 2 EXPUNGE - S: * 3 EXISTS - S: + idling - ...time passes; another client expunges message 3... - S: * 3 EXPUNGE - S: * 2 EXISTS - ...time passes; new mail arrives... - S: * 3 EXISTS - C: DONE - S: A004 OK IDLE terminated - C: A005 FETCH 3 ALL - S: * 3 FETCH (...) - S: A005 OK FETCH completed - C: A006 IDLE - -4. Formal Syntax - - The following syntax specification uses the augmented Backus-Naur - Form (BNF) notation as specified in [RFC-822] as modified by [IMAP4]. - Non-terminals referenced but not defined below are as defined by - [IMAP4]. - - command_auth ::= append / create / delete / examine / list / lsub / - rename / select / status / subscribe / unsubscribe - / idle - ;; Valid only in Authenticated or Selected state - - idle ::= "IDLE" CRLF "DONE" - - - - - - -Leiba Standards Track [Page 3] - -RFC 2177 IMAP4 IDLE command June 1997 - - -5. References - - [IMAP4] Crispin, M., "Internet Message Access Protocol - Version - 4rev1", RFC 2060, December 1996. - -6. Security Considerations - - There are no known security issues with this extension. - -7. Author's Address - - Barry Leiba - IBM T.J. Watson Research Center - 30 Saw Mill River Road - Hawthorne, NY 10532 - - Email: leiba@watson.ibm.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Leiba Standards Track [Page 4] - diff --git a/imap/docs/rfc/rfc2180.txt b/imap/docs/rfc/rfc2180.txt deleted file mode 100644 index 57607002..00000000 --- a/imap/docs/rfc/rfc2180.txt +++ /dev/null @@ -1,787 +0,0 @@ - - - - - - -Network Working Group M. Gahrns -Request for Comments: 2180 Microsoft -Category: Informational July 1997 - - - IMAP4 Multi-Accessed Mailbox Practice - -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. - -1. Abstract - - IMAP4[RFC-2060] is rich client/server protocol that allows a client - to access and manipulate electronic mail messages on a server. - Within the protocol framework, it is possible to have differing - results for particular client/server interactions. If a protocol does - not allow for this, it is often unduly restrictive. - - For example, when multiple clients are accessing a mailbox and one - attempts to delete the mailbox, an IMAP4 server may choose to - implement a solution based upon server architectural constraints or - individual preference. - - With this flexibility comes greater client responsibility. It is not - sufficient for a client to be written based upon the behavior of a - particular IMAP server. Rather the client must be based upon the - behavior allowed by the protocol. - - By documenting common IMAP4 server practice for the case of - simultaneous client access to a mailbox, we hope to ensure the widest - amount of inter-operation between IMAP4 clients and servers. - - The behavior described in this document reflects the practice of some - existing servers or behavior that the consensus of the IMAP mailing - list has deemed to be reasonable. The behavior described within this - document is believed to be [RFC-2060] compliant. However, this - document is not meant to define IMAP4 compliance, nor is it an - exhaustive list of valid IMAP4 behavior. [RFC-2060] must always be - consulted to determine IMAP4 compliance, especially for server - behavior not described within this document. - - - - - - - - -Gahrns Informational [Page 1] - -RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 - - -2. Conventions used in this document - - In examples,"C1:", "C2:" and "C3:" indicate lines sent by 3 different - clients (client #1, client #2 and client #3) that are connected to a - server. "S1:", "S2:" and "S3:" indicated lines sent by the server to - client #1, client #2 and client #3 respectively. - - A shared mailbox, is a mailbox that can be used by multiple users. - - A multi-accessed mailbox, is a mailbox that has multiple clients - simultaneously accessing it. - - A client is said to have accessed a mailbox after a successful SELECT - or EXAMINE command. - - 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]. - - -3. Deletion/Renaming of a multi-accessed mailbox - - If an external agent or multiple clients are accessing a mailbox, - care must be taken when handling the deletion or renaming of the - mailbox. Following are some strategies an IMAP server may choose to - use when dealing with this situation. - - -3.1. The server MAY fail the DELETE/RENAME command of a multi-accessed - mailbox - - In some cases, this behavior may not be practical. For example, if a - large number of clients are accessing a shared mailbox, the window in - which no clients have the mailbox accessed may be small or non- - existent, effectively rendering the mailbox undeletable or - unrenamable. - - Example: - - <Client #1 and Client #2 have mailbox FOO accessed. Client #1 tries - to DELETE the mailbox and is refused> - - C1: A001 DELETE FOO - S1: A001 NO Mailbox FOO is in use by another user. - - - - - - - -Gahrns Informational [Page 2] - -RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 - - -3.2. The server MAY allow the DELETE command of a multi-accessed - mailbox, but keep the information in the mailbox available for - those clients that currently have access to the mailbox. - - When all clients have finished accessing the mailbox, it is - permanently removed. For clients that do not already have access to - the mailbox, the 'ghosted' mailbox would not be available. For - example, it would not be returned to these clients in a subsequent - LIST or LSUB command and would not be a valid mailbox argument to any - other IMAP command until the reference count of clients accessing the - mailbox reached 0. - - In some cases, this behavior may not be desirable. For example if - someone created a mailbox with offensive or sensitive information, - one might prefer to have the mailbox deleted and all access to the - information contained within removed immediately, rather than - continuing to allow access until the client closes the mailbox. - - Furthermore, this behavior, may prevent 'recycling' of the same - mailbox name until all clients have finished accessing the original - mailbox. - - Example: - - <Client #1 and Client #2 have mailbox FOO selected. Client #1 DELETEs - mailbox FOO> - - C1: A001 DELETE FOO - S1: A001 OK Mailbox FOO is deleted. - - <Client #2 is still able to operate on the deleted mailbox> - - C2: B001 STORE 1 +FLAGS (\Seen) - S2: * 1 FETCH FLAGS (\Seen) - S2: B001 OK STORE completed - - <Client #3 which did not have access to the mailbox prior to the - deletion by client #1 does not have access to the mailbox> - - C3: C001 STATUS FOO (MESSAGES) - S3: C001 NO Mailbox does not exist - - <Nor is client #3 able to create a mailbox with the name FOO, while - the reference count is non zero> - - C3: C002 CREATE FOO - S3: C002 NO Mailbox FOO is still in use. Try again later. - - - - -Gahrns Informational [Page 3] - -RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 - - - <Client #2 closes its access to the mailbox, no other clients have - access to the mailbox FOO and reference count becomes 0> - - C2: B002 CLOSE - S2: B002 OK CLOSE Completed - - <Now that the reference count on FOO has reached 0, the mailbox name - can be recycled> - - C3: C003 CREATE FOO - S3: C003 OK CREATE Completed - - -3.3. The server MAY allow the DELETE/RENAME of a multi-accessed - mailbox, but disconnect all other clients who have the mailbox - accessed by sending a untagged BYE response. - - A server may often choose to disconnect clients in the DELETE case, - but may choose to implement a "friendlier" method for the RENAME - case. - - Example: - - <Client #1 and Client #2 have mailbox FOO accessed. Client #1 DELETEs - the mailbox FOO> - - C1: A002 DELETE FOO - S1: A002 OK DELETE completed. - - <Server disconnects all other users of the mailbox> - S2: * BYE Mailbox FOO has been deleted. - - -3.4. The server MAY allow the RENAME of a multi-accessed mailbox by - simply changing the name attribute on the mailbox. - - Other clients that have access to the mailbox can continue issuing - commands such as FETCH that do not reference the mailbox name. - Clients would discover the renaming the next time they referred to - the old mailbox name. Some servers MAY choose to include the - [NEWNAME] response code in their tagged NO response to a command that - contained the old mailbox name, as a hint to the client that the - operation can succeed if the command is issued with the new mailbox - name. - - - - - - - -Gahrns Informational [Page 4] - -RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 - - - Example: - - <Client #1 and Client #2 have mailbox FOO accessed. Client #1 RENAMEs - the mailbox.> - - C1: A001 RENAME FOO BAR - S1: A001 OK RENAME completed. - - <Client #2 is still able to do operations that do not reference the - mailbox name> - - C2: B001 FETCH 2:4 (FLAGS) - S2: * 2 FETCH . . . - S2: * 3 FETCH . . . - S2: * 4 FETCH . . . - S2: B001 OK FETCH completed - - <Client #2 is not able to do operations that reference the mailbox - name> - - C2: B002 APPEND FOO {300} C2: Date: Mon, 7 Feb 1994 - 21:52:25 0800 (PST) C2: . . . S2: B002 NO [NEWNAME FOO - BAR] Mailbox has been renamed - - -4. Expunging of messages on a multi-accessed mailbox - - If an external agent or multiple clients are accessing a mailbox, - care must be taken when handling the EXPUNGE of messages. Other - clients accessing the mailbox may be in the midst of issuing a - command that depends upon message sequence numbers. Because an - EXPUNGE response can not be sent while responding to a FETCH, STORE - or SEARCH command, it is not possible to immediately notify the - client of the EXPUNGE. This can result in ambiguity if the client - issues a FETCH, STORE or SEARCH operation on a message that has been - EXPUNGED. - - -4.1. Fetching of expunged messages - - Following are some strategies an IMAP server may choose to use when - dealing with a FETCH command on expunged messages. - - - - - - - - - -Gahrns Informational [Page 5] - -RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 - - - Consider the following scenario: - - - Client #1 and Client #2 have mailbox FOO selected. - - There are 7 messages in the mailbox. - - Messages 4:7 are marked for deletion. - - Client #1 issues an EXPUNGE, to expunge messages 4:7 - - -4.1.1. The server MAY allow the EXPUNGE of a multi-accessed mailbox but - keep the messages available to satisfy subsequent FETCH commands - until it is able to send an EXPUNGE response to each client. - - In some cases, the behavior of keeping "ghosted" messages may not be - desirable. For example if a message contained offensive or sensitive - information, one might prefer to instantaneously remove all access to - the information, regardless of whether another client is in the midst - of accessing it. - - Example: (Building upon the scenario outlined in 4.1.) - - <Client #2 is still able to access the expunged messages because the - server has kept a 'ghosted' copy of the messages until it is able to - notify client #2 of the EXPUNGE> - - C2: B001 FETCH 4:7 RFC822 - S2: * 4 FETCH RFC822 . . . (RFC822 info returned) - S2: * 5 FETCH RFC822 . . . (RFC822 info returned) - S2: * 6 FETCH RFC822 . . . (RFC822 info returned) - S2: * 7 FETCH RFC822 . . . (RFC822 info returned) - S2: B001 OK FETCH Completed - - <Client #2 issues a command where it can get notified of the EXPUNGE> - - C2: B002 NOOP - S2: * 4 EXPUNGE - S2: * 4 EXPUNGE - S2: * 4 EXPUNGE - S2: * 4 EXPUNGE - S2: * 3 EXISTS - S2: B002 OK NOOP Complete - - <Client #2 no longer has access to the expunged messages> - - C2: B003 FETCH 4:7 RFC822 - S2: B003 NO Messages 4:7 are no longer available. - - - - - - -Gahrns Informational [Page 6] - -RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 - - -4.1.2 The server MAY allow the EXPUNGE of a multi-accessed mailbox, - and on subsequent FETCH commands return FETCH responses only for - non-expunged messages and a tagged NO. - - After receiving a tagged NO FETCH response, the client SHOULD issue a - NOOP command so that it will be informed of any pending EXPUNGE - responses. The client may then either reissue the failed FETCH - command, or by examining the EXPUNGE response from the NOOP and the - FETCH response from the FETCH, determine that the FETCH failed - because of pending expunges. - - Example: (Building upon the scenario outlined in 4.1.) - - <Client #2 attempts to FETCH a mix of expunged and non-expunged - messages. A FETCH response is returned only for then non-expunged - messages along with a tagged NO> - - C2: B001 FETCH 3:5 ENVELOPE - S2: * 3 FETCH ENVELOPE . . . (ENVELOPE info returned) - S2: B001 NO Some of the requested messages no longer exist - - <Upon receiving a tagged NO FETCH response, Client #2 issues a NOOP - to be informed of any pending EXPUNGE responses> - - C2: B002 NOOP - S2: * 4 EXPUNGE - S2: * 4 EXPUNGE - S2: * 4 EXPUNGE - S2: * 4 EXPUNGE - S2: * 3 EXISTS - S2: B002 OK NOOP Completed. - - <By receiving a FETCH response for message 3, and an EXPUNGE response - that indicates messages 4:7 have been expunged, the client does not - need to re-issue the FETCH> - - - - - - - - - - - - - - - - -Gahrns Informational [Page 7] - -RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 - - -4.1.3 The server MAY allow the EXPUNGE of a multi-accessed mailbox, and - on subsequent FETCH commands return the usual FETCH responses for - non-expunged messages, "NIL FETCH Responses" for expunged - messages, and a tagged OK response. - - If all of the messages in the subsequent FETCH command have been - expunged, the server SHOULD return only a tagged NO. In this case, - the client SHOULD issue a NOOP command so that it will be informed of - any pending EXPUNGE responses. The client may then either reissue - the failed FETCH command, or by examining the EXPUNGE response from - the NOOP, determine that the FETCH failed because of pending - expunges. - - "NIL FETCH responses" are a representation of empty data as - appropriate for the FETCH argument specified. - - Example: - - * 1 FETCH (ENVELOPE (NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL)) - * 1 FETCH (FLAGS ()) - * 1 FETCH (INTERNALDATE "00-Jan-0000 00:00:00 +0000") - * 1 FETCH (RFC822 "") - * 1 FETCH (RFC822.HEADER "") - * 1 FETCH (RFC822.TEXT "") - * 1 FETCH (RFC822.SIZE 0) - * 1 FETCH (BODY ("TEXT" "PLAIN" NIL NIL NIL "7BIT" 0 0) - * 1 FETCH (BODYSTRUCTURE ("TEXT" "PLAIN" NIL NIL NIL "7BIT" 0 0) - * 1 FETCH (BODY[<section>] "") - * 1 FETCH (BODY[<section>]<partial> "") - - In some cases, a client may not be able to distinguish between "NIL - FETCH responses" received because a message was expunged and those - received because the data actually was NIL. For example, a * 5 - FETCH (FLAGS ()) response could be received if no flags were set on - message 5, or because message 5 was expunged. In a case of potential - ambiguity, the client SHOULD issue a command such as NOOP to force - the sending of the EXPUNGE responses to resolve any ambiguity. - - Example: (Building upon the scenario outlined in 4.1.) - - <Client #2 attempts to access a mix of expunged and non-expunged - messages. Normal data is returned for non-expunged message, "NIL - FETCH responses" are returned for expunged messages> - - - - - - - - -Gahrns Informational [Page 8] - -RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 - - - C2: B002 FETCH 3:5 ENVELOPE - S2: * 3 FETCH ENVELOPE . . . (ENVELOPE info returned) - S2: * 4 FETCH ENVELOPE (NIL NIL NIL NIL NIL NIL NIL NIL - NIL NIL) - S2: * 5 FETCH ENVELOPE (NIL NIL NIL NIL NIL NIL NIL NIL - NIL NIL) - S2: B002 OK FETCH Completed - - <Client #2 attempts to FETCH only expunged messages and receives a - tagged NO response> - - C2: B002 FETCH 4:7 ENVELOPE - S2: B002 NO Messages 4:7 have been expunged. - - -4.1.4 To avoid the situation altogether, the server MAY fail the - EXPUNGE of a multi-accessed mailbox - - In some cases, this behavior may not be practical. For example, if a - large number of clients are accessing a shared mailbox, the window in - which no clients have the mailbox accessed may be small or non- - existent, effectively rendering the message unexpungeable. - - -4.2. Storing of expunged messages - - Following are some strategies an IMAP server may choose to use when - dealing with a STORE command on expunged messages. - - -4.2.1 If the ".SILENT" suffix is used, and the STORE completed - successfully for all the non-expunged messages, the server SHOULD - return a tagged OK. - - Example: (Building upon the scenario outlined in 4.1.) - - <Client #2 tries to silently STORE flags on expunged and non- - expunged messages. The server sets the flags on the non-expunged - messages and returns OK> - - C2: B001 STORE 1:7 +FLAGS.SILENT (\SEEN) - S2: B001 OK - - - - - - - - - -Gahrns Informational [Page 9] - -RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 - - -4.2.2. If the ".SILENT" suffix is not used, and only expunged messages - are referenced, the server SHOULD return only a tagged NO. - - Example: (Building upon the scenario outlined in 4.1.) - - <Client #2 tries to STORE flags only on expunged messages> - - C2: B001 STORE 5:7 +FLAGS (\SEEN) - S2: B001 NO Messages have been expunged - - -4.2.3. If the ".SILENT" suffix is not used, and a mixture of expunged - and non-expunged messages are referenced, the server MAY set the - flags and return a FETCH response for the non-expunged messages - along with a tagged NO. - - After receiving a tagged NO STORE response, the client SHOULD issue a - NOOP command so that it will be informed of any pending EXPUNGE - responses. The client may then either reissue the failed STORE - command, or by examining the EXPUNGE responses from the NOOP and - FETCH responses from the STORE, determine that the STORE failed - because of pending expunges. - - Example: (Building upon the scenario outlined in 4.1.) - - <Client #2 tries to STORE flags on a mixture of expunged and non- - expunged messages> - - C2: B001 STORE 1:7 +FLAGS (\SEEN) - S2: * FETCH 1 FLAGS (\SEEN) - S2: * FETCH 2 FLAGS (\SEEN) - S2: * FETCH 3 FLAGS (\SEEN) - S2: B001 NO Some of the messages no longer exist. - - C2: B002 NOOP - S2: * 4 EXPUNGE - S2: * 4 EXPUNGE - S2: * 4 EXPUNGE - S2: * 4 EXPUNGE - S2: * 3 EXISTS - S2: B002 OK NOOP Completed. - - <By receiving FETCH responses for messages 1:3, and an EXPUNGE - response that indicates messages 4:7 have been expunged, the client - does not need to re-issue the STORE> - - - - - - -Gahrns Informational [Page 10] - -RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 - - -4.2.4. If the ".SILENT" suffix is not used, and a mixture of expunged - and non-expunged messages are referenced, the server MAY return - an untagged NO and not set any flags. - - After receiving a tagged NO STORE response, the client SHOULD issue a - NOOP command so that it will be informed of any pending EXPUNGE - responses. The client would then re-issue the STORE command after - updating its message list per any EXPUNGE response. - - If a large number of clients are accessing a shared mailbox, the - window in which there are no pending expunges may be small or non- - existent, effectively disallowing a client from setting the flags on - all messages at once. - - Example: (Building upon the scenario outlined in 4.1.) - - <Client #2 tries to STORE flags on a mixture of expunged and non- - expunged messages> - - C2: B001 STORE 1:7 +FLAGS (\SEEN) - S2: B001 NO Some of the messages no longer exist. - - <Client #2 issues a NOOP to be informed of the EXPUNGED messages> - - C2: B002 NOOP - S2: * 4 EXPUNGE - S2: * 4 EXPUNGE - S2: * 4 EXPUNGE - S2: * 4 EXPUNGE - S2: * 3 EXISTS - S2: B002 OK NOOP Completed. - - <Client #2 updates its message list and re-issues the STORE on only - those messages that have not been expunged> - - C2: B003 STORE 1:3 +FLAGS (\SEEN) S2: * FETCH 1 FLAGS - (\SEEN) S2: * FETCH 2 FLAGS (\SEEN) S2: * FETCH 3 FLAGS - (\SEEN) S2: B003 OK STORE Completed - - -4.3. Searching of expunged messages - - A server MAY simply not return a search response for messages that - have been expunged and it has not been able to inform the client - about. If a client was expecting a particular message to be returned - in a search result, and it was not, the client SHOULD issue a NOOP - command to see if the message was expunged by another client. - - - - -Gahrns Informational [Page 11] - -RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 - - -4.4 Copying of expunged messages - - COPY is the only IMAP4 sequence number command that is safe to allow - an EXPUNGE response on. This is because a client is not permitted to - cascade several COPY commands together. A client is required to wait - and confirm that the copy worked before issuing another one. - -4.4.1 The server MAY disallow the COPY of messages in a multi-access - mailbox that contains expunged messages. - - Pending EXPUNGE response(s) MUST be returned to the COPY command. - - Example: - - C: A001 COPY 2,4,6,8 FRED - S: * 4 EXPUNGE - S: A001 NO COPY rejected, because some of the requested - messages were expunged - - Note: Non of the above messages are copied because if a COPY command - is unsuccessful, the server MUST restore the destination mailbox to - its state before the COPY attempt. - - -4.4.2 The server MAY allow the COPY of messages in a multi-access - mailbox that contains expunged messages. - - Pending EXPUNGE response(s) MUST be returned to the COPY command. - Messages that are copied are messages corresponding to sequence - numbers before any EXPUNGE response. - - Example: - - C: A001 COPY 2,4,6,8 FRED - S: * 3 EXPUNGE - S: A001 OK COPY completed - - In the above example, the messages that are copied to FRED are - messages 2,4,6,8 at the start of the COPY command. These are - equivalent to messages 2,3,5,7 at the end of the COPY command. The - EXPUNGE response can't take place until after the messages from the - COPY command are identified (because of the "no expunge while no - commands in progress" rule). - - - - - - - - -Gahrns Informational [Page 12] - -RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 - - - Example: - - C: A001 COPY 2,4,6,8 FRED - S: * 4 EXPUNGE - S: A001 OK COPY completed - - In the above example, message 4 was copied before it was expunged, - and MUST appear in the destination mailbox FRED. - - -5. Security Considerations - - This document describes behavior of servers that use the IMAP4 - protocol, and as such, has the same security considerations as - described in [RFC-2060]. - - In particular, some described server behavior does not allow for the - immediate deletion of information when a mailbox is accessed by - multiple clients. This may be a consideration when dealing with - sensitive information where immediate deletion would be preferred. - - -6. References - - [RFC-2060], Crispin, M., "Internet Message Access Protocol - Version - 4rev1", RFC 2060, University of Washington, December 1996. - - [RFC-2119], Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", RFC 2119, Harvard University, March 1997. - - -7. Acknowledgments - - This document is the result of discussions on the IMAP4 mailing list - and is meant to reflect consensus of this group. In particular, - Raymond Cheng, Mark Crispin, Jim Evans, Erik Forsberg, Steve Hole, - Mark Keasling, Barry Leiba, Syd Logan, John Mani, Pat Moran, Larry - Osterman, Chris Newman, Bart Schaefer, Vladimir Vulovic, and Jack De - Winter were active participants in this discussion or made - suggestions to this document. - - - - - - - - - - - -Gahrns Informational [Page 13] - -RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 - - -8. Author's Address - - Mike Gahrns - Microsoft - One Microsoft Way - Redmond, WA, 98072 - - Phone: (206) 936-9833 - EMail: mikega@microsoft.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Gahrns Informational [Page 14] - diff --git a/imap/docs/rfc/rfc2193.txt b/imap/docs/rfc/rfc2193.txt deleted file mode 100644 index 2fec58d7..00000000 --- a/imap/docs/rfc/rfc2193.txt +++ /dev/null @@ -1,507 +0,0 @@ - - - - - - -Network Working Group M. Gahrns -Request for Comments: 2193 Microsoft -Category: Standards Track September 1997 - - - IMAP4 Mailbox Referrals - -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. Abstract - - When dealing with large amounts of users, messages and geographically - dispersed IMAP4 [RFC-2060] servers, it is often desirable to - distribute messages amongst different servers within an organization. - For example an administrator may choose to store user's personal - mailboxes on a local IMAP4 server, while storing shared mailboxes - remotely on another server. This type of configuration is common - when it is uneconomical to store all data centrally due to limited - bandwidth or disk resources. - - Mailbox referrals allow clients to seamlessly access mailboxes that - are distributed across several IMAP4 servers. - - A referral mechanism can provide efficiencies over the alternative - "proxy method", in which the local IMAP4 server contacts the remote - server on behalf of the client, and then transfers the data from the - remote server to itself, and then on to the client. The referral - mechanism's direct client connection to the remote server is often a - more efficient use of bandwidth, and does not require the local - server to impersonate the client when authenticating to the remote - server. - -2. Conventions used in this document - - In examples, "C:" and "S:" indicate lines sent by the client and - server respectively. - - A home server, is an IMAP4 server that contains the user's inbox. - - A remote mailbox is a mailbox that is not hosted on the user's home - server. - - - - -Gahrns Standards Track [Page 1] - -RFC 2193 IMAP4 Mailbox Referrals September 1997 - - - A remote server is a server that contains remote mailboxes. - - A shared mailbox, is a mailbox that multiple users have access to. - - An IMAP mailbox referral is when the server directs the client to - another IMAP mailbox. - - 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]. - -3. Introduction and Overview - - IMAP4 servers that support this extension MUST list the keyword - MAILBOX-REFERRALS in their CAPABILITY response. No client action is - needed to invoke the MAILBOX-REFERRALS capability in a server. - - A MAILBOX-REFERRALS capable IMAP4 server MUST NOT return referrals - that result in a referrals loop. - - A referral response consists of a tagged NO response and a REFERRAL - response code. The REFERRAL response code MUST contain as an - argument a one or more valid URLs separated by a space as defined in - [RFC-1738]. If a server replies with multiple URLs for a particular - object, they MUST all be of the same type. In this case, the URL MUST - be an IMAP URL as defined in [RFC-2192]. A client that supports the - REFERRALS extension MUST be prepared for a URL of any type, but it - need only be able to process IMAP URLs. - - A server MAY respond with multiple IMAP mailbox referrals if there is - more than one replica of the mailbox. This allows the implementation - of a load balancing or failover scheme. How a server keeps multiple - replicas of a mailbox in sync is not addressed by this document. - - If the server has a preferred order in which the client should - attempt to access the URLs, the preferred URL SHOULD be listed in the - first, with the remaining URLs presented in descending order of - preference. If multiple referrals are given for a mailbox, a server - should be aware that there are synchronization issues for a client if - the UIDVALIDITY of the referred mailboxes are different. - - An IMAP mailbox referral may be given in response to an IMAP command - that specifies a mailbox as an argument. - - - - - - - - -Gahrns Standards Track [Page 2] - -RFC 2193 IMAP4 Mailbox Referrals September 1997 - - - Example: - - A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/REMOTE]Remote Mailbox - - NOTE: user;AUTH=* is specified as required by [RFC-2192] to avoid a - client falling back to anonymous login. - - Remote mailboxes and their inferiors, that are accessible only via - referrals SHOULD NOT appear in LIST and LSUB responses issued against - the user's home server. They MUST appear in RLIST and RLSUB - responses issued against the user's home server. Hierarchy referrals, - in which a client would be required to connect to the remote server - to issue a LIST to discover the inferiors of a mailbox are not - addressed in this document. - - For example, if shared mailboxes were only accessible via referrals - on a remote server, a RLIST "" "#SHARED/%" command would return the - same response if issued against the user's home server or the remote - server. - - Note: Mailboxes that are available on the user's home server do not - need to be available on the remote server. In addition, there may be - additional mailboxes available on the remote server, but they will - not accessible to the client via referrals unless they appear in the - LIST response to the RLIST command against the user's home server. - - A MAILBOX-REFERRALS capable client will issue the RLIST and RLSUB - commands in lieu of LIST and LSUB. The RLIST and RLSUB commands - behave identically to their LIST and LSUB counterparts, except remote - mailboxes are returned in addition to local mailboxes in the LIST and - LSUB responses. This avoids displaying to a non MAILBOX-REFERRALS - enabled client inaccessible remote mailboxes. - -4.1. SELECT, EXAMINE, DELETE, SUBSCRIBE, UNSUBSCRIBE, STATUS and APPEND - Referrals - - An IMAP4 server MAY respond to the SELECT, EXAMINE, DELETE, - SUBSCRIBE, UNSUBSCRIBE, STATUS or APPEND command with one or more - IMAP mailbox referrals to indicate to the client that the mailbox is - hosted on a remote server. - - When a client processes an IMAP mailbox referral, it will open a new - connection or use an existing connection to the remote server so that - it is able to issue the commands necessary to process the remote - mailbox. - - - - - - -Gahrns Standards Track [Page 3] - -RFC 2193 IMAP4 Mailbox Referrals September 1997 - - - Example: <IMAP4 connection to home server> - - C: A001 DELETE "SHARED/FOO" - S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/FOO] - Remote mailbox. Try SERVER2. - - <Client established a second connection to SERVER2 and - issues the DELETE command on the referred mailbox> - - S: * OK IMAP4rev1 server ready - C: B001 AUTHENTICATE KERBEROS_V4 - <authentication exchange> - S: B001 OK user is authenticated - - C: B002 DELETE "SHARED/FOO" - S: B002 OK DELETE completed - - Example: <IMAP4 connection to home server> - - C: A001 SELECT REMOTE - S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/REMOTE - IMAP://user;AUTH=*@SERVER3/REMOTE] Remote mailbox. - Try SERVER2 or SERVER3. - - <Client opens second connection to remote server, and - issues the commands needed to process the items in the - remote mailbox> - - S: * OK IMAP4rev1 server ready - C: B001 AUTHENTICATE KERBEROS_V4 - <authentication exchange> - S: B001 OK user is authenticated - - C: B002 SELECT REMOTE - S: * 12 EXISTS - S: * 1 RECENT - S: * OK [UNSEEN 10] Message 10 is first unseen - S: * OK [UIDVALIDITY 123456789] - S: * FLAGS (Answered Flagged Deleted Seen Draft) - S: * OK [PERMANENTFLAGS (Answered Deleted Seen ] - S: B002 OK [READ-WRITE] Selected completed - - C: B003 FETCH 10:12 RFC822 - S: * 10 FETCH . . . - S: * 11 FETCH . . . - S: * 12 FETCH . . . - S: B003 OK FETCH Completed - - - - -Gahrns Standards Track [Page 4] - -RFC 2193 IMAP4 Mailbox Referrals September 1997 - - - <Client is finished processing the REMOTE mailbox and - wants to process a mailbox on its home server> - - C: B004 LOGOUT - S: * BYE IMAP4rev1 server logging out - S: B004 OK LOGOUT Completed - - <Client continues with first connection> - - C: A002 SELECT INBOX - S: * 16 EXISTS - S: * 2 RECENT - S: * OK [UNSEEN 10] Message 10 is first unseen - S: * OK [UIDVALIDITY 123456789] - S: * FLAGS (Answered Flagged Deleted Seen Draft) - S: * OK [PERMANENTFLAGS (Answered Deleted Seen ] - S: A002 OK [READ-WRITE] Selected completed - -4.2. CREATE Referrals - - An IMAP4 server MAY respond to the CREATE command with one or more - IMAP mailbox referrals, if it wishes to direct the client to issue - the CREATE against another server. The server can employ any means, - such as examining the hierarchy of the specified mailbox name, in - determining which server the mailbox should be created on. - - Example: - - C: A001 CREATE "SHARED/FOO" - S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/FOO] - Mailbox should be created on remote server - - Alternatively, because a home server is required to maintain a - listing of referred remote mailboxes, a server MAY allow the creation - of a mailbox that will ultimately reside on a remote server against - the home server, and provide referrals on subsequent commands that - manipulate the mailbox. - - Example: - - C: A001 CREATE "SHARED/FOO" - S: A001 OK CREATE succeeded - - C: A002 SELECT "SHARED/FOO" - S: A002 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/FOO] - Remote mailbox. Try SERVER2 - - - - - -Gahrns Standards Track [Page 5] - -RFC 2193 IMAP4 Mailbox Referrals September 1997 - - -4.3. RENAME Referrals - - An IMAP4 server MAY respond to the RENAME command with one or more - pairs of IMAP mailbox referrals. In each pair of IMAP mailbox - referrals, the first one is an URL to the existing mailbox name and - the second is an URL to the requested new mailbox name. - - If within an IMAP mailbox referral pair, the existing and new mailbox - URLs are on different servers, the remote servers are unable to - perform the RENAME operation. To achieve the same behavior of - server RENAME, the client MAY issue the constituent CREATE, FETCH, - APPEND, and DELETE commands against both servers. - - If within an IMAP mailbox referral pair, the existing and new mailbox - URLs are on the same server it is an indication that the currently - connected server is unable to perform the operation. The client can - simply re-issue the RENAME command on the remote server. - - Example: - - C: A001 RENAME FOO BAR - S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER1/FOO - IMAP://user;AUTH=*@SERVER2/BAR] Unable to rename mailbox - across servers - - Since the existing and new mailbox names are on different servers, - the client would be required to make a connection to both servers and - issue the constituent commands require to achieve the RENAME. - - Example: - - C: A001 RENAME FOO BAR - S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/FOO - IMAP://user;AUTH=*@SERVER2/BAR] Unable to rename mailbox - located on SERVER2 - - Since both the existing and new mailbox are on the same remote - server, the client can simply make a connection to the remote server - and re-issue the RENAME command. - -4.4. COPY Referrals - - An IMAP4 server MAY respond to the COPY command with one or more IMAP - mailbox referrals. This indicates that the destination mailbox is on - a remote server. To achieve the same behavior of a server COPY, the - client MAY issue the constituent FETCH and APPEND commands against - both servers. - - - - -Gahrns Standards Track [Page 6] - -RFC 2193 IMAP4 Mailbox Referrals September 1997 - - - Example: - - C: A001 COPY 1 "SHARED/STUFF" - S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/STUFF] - Unable to copy message(s) to SERVER2. - -5.1 RLIST command - - Arguments: reference name - mailbox name with possible wildcards - - Responses: untagged responses: LIST - - Result: OK - RLIST Completed - NO - RLIST Failure - BAD - command unknown or arguments invalid - - The RLIST command behaves identically to its LIST counterpart, except - remote mailboxes are returned in addition to local mailboxes in the - LIST responses. - -5.2 RLSUB Command - - Arguments: reference name - mailbox name with possible wildcards - - Responses: untagged responses: LSUB - - Result: OK - RLSUB Completed - NO - RLSUB Failure - BAD - command unknown or arguments invalid - - The RLSUB command behaves identically to its LSUB counterpart, except - remote mailboxes are returned in addition to local mailboxes in the - LSUB responses. - -6. Formal Syntax - - The following syntax specification uses the augmented Backus-Naur - Form (BNF) as described in [ABNF]. - - list_mailbox = <list_mailbox> as defined in [RFC-2060] - - mailbox = <mailbox> as defined in [RFC-2060] - - mailbox_referral = <tag> SPACE "NO" SPACE - <referral_response_code> (text / text_mime2) - ; See [RFC-2060] for <tag>, text and text_mime2 definition - - - -Gahrns Standards Track [Page 7] - -RFC 2193 IMAP4 Mailbox Referrals September 1997 - - - referral_response_code = "[" "REFERRAL" 1*(SPACE <url>) "]" - ; See [RFC-1738] for <url> definition - - rlist = "RLIST" SPACE mailbox SPACE list_mailbox - - rlsub = "RLSUB" SPACE mailbox SPACE list_mailbox - -6. Security Considerations - - The IMAP4 referral mechanism makes use of IMAP URLs, and as such, - have the same security considerations as general internet URLs [RFC- - 1738], and in particular IMAP URLs [RFC-2192]. - - With the MAILBOX-REFERRALS capability, it is potentially easier to - write a rogue server that injects a bogus referral response that - directs a user to an incorrect mailbox. Although referrals reduce - the effort to write such a server, the referral response makes - detection of the intrusion easier. - -7. References - - [RFC-2060], Crispin, M., "Internet Message Access Protocol - Version - 4rev1", RFC 2060, University of Washington, December 1996. - - [RFC-2192], Newman, C., "IMAP URL Scheme", RFC 2192, Innosoft, - September 1997. - - [RFC-1738], Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform - Resource Locators (URL)", RFC 1738, CERN, Xerox Corporation, - University of Minnesota, December 1994. - - [RFC-2119], Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", RFC 2119, Harvard University, March 1997. - - [ABNF], DRUMS working group, Dave Crocker Editor, "Augmented BNF for - Syntax Specifications: ABNF", Work in Progress, Internet Mail - Consortium, April 1997. - -8. Acknowledgments - - Many valuable suggestions were received from private discussions and - the IMAP4 mailing list. In particular, Raymond Cheng, Mark Crispin, - Mark Keasling, Chris Newman and Larry Osterman made significant - contributions to this document. - - - - - - - -Gahrns Standards Track [Page 8] - -RFC 2193 IMAP4 Mailbox Referrals September 1997 - - -9. Author's Address - - Mike Gahrns - Microsoft - One Microsoft Way - Redmond, WA, 98072 - - Phone: (206) 936-9833 - EMail: mikega@microsoft.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Gahrns Standards Track [Page 9] - diff --git a/imap/docs/rfc/rfc2195.txt b/imap/docs/rfc/rfc2195.txt deleted file mode 100644 index 4a2725bf..00000000 --- a/imap/docs/rfc/rfc2195.txt +++ /dev/null @@ -1,283 +0,0 @@ - - - - - - -Network Working Group J. Klensin -Request for Comments: 2195 R. Catoe -Category: Standards Track P. Krumviede -Obsoletes: 2095 MCI - September 1997 - - - IMAP/POP AUTHorize Extension for Simple Challenge/Response - -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 - - While IMAP4 supports a number of strong authentication mechanisms as - described in RFC 1731, it lacks any mechanism that neither passes - cleartext, reusable passwords across the network nor requires either - a significant security infrastructure or that the mail server update - a mail-system-wide user authentication file on each mail access. - This specification provides a simple challenge-response - authentication protocol that is suitable for use with IMAP4. Since - it utilizes Keyed-MD5 digests and does not require that the secret be - stored in the clear on the server, it may also constitute an - improvement on APOP for POP3 use as specified in RFC 1734. - -1. Introduction - - Existing Proposed Standards specify an AUTHENTICATE mechanism for the - IMAP4 protocol [IMAP, IMAP-AUTH] and a parallel AUTH mechanism for - the POP3 protocol [POP3-AUTH]. The AUTHENTICATE mechanism is - intended to be extensible; the four methods specified in [IMAP-AUTH] - are all fairly powerful and require some security infrastructure to - support. The base POP3 specification [POP3] also contains a - lightweight challenge-response mechanism called APOP. APOP is - associated with most of the risks associated with such protocols: in - particular, it requires that both the client and server machines have - access to the shared secret in cleartext form. CRAM offers a method - for avoiding such cleartext storage while retaining the algorithmic - simplicity of APOP in using only MD5, though in a "keyed" method. - - - - - - - -Klensin, Catoe & Krumviede Standards Track [Page 1] - -RFC 2195 IMAP/POP AUTHorize Extension September 1997 - - - At present, IMAP [IMAP] lacks any facility corresponding to APOP. - The only alternative to the strong mechanisms identified in [IMAP- - AUTH] is a presumably cleartext username and password, supported - through the LOGIN command in [IMAP]. This document describes a - simple challenge-response mechanism, similar to APOP and PPP CHAP - [PPP], that can be used with IMAP (and, in principle, with POP3). - - This mechanism also has the advantage over some possible alternatives - of not requiring that the server maintain information about email - "logins" on a per-login basis. While mechanisms that do require such - per-login history records may offer enhanced security, protocols such - as IMAP, which may have several connections between a given client - and server open more or less simultaneous, may make their - implementation particularly challenging. - -2. Challenge-Response Authentication Mechanism (CRAM) - - The authentication type associated with CRAM is "CRAM-MD5". - - The data encoded in the first ready response contains an - presumptively arbitrary string of random digits, a timestamp, and the - fully-qualified primary host name of the server. The syntax of the - unencoded form must correspond to that of an RFC 822 'msg-id' - [RFC822] as described in [POP3]. - - The client makes note of the data and then responds with a string - consisting of the user name, a space, and a 'digest'. The latter is - computed by applying the keyed MD5 algorithm from [KEYED-MD5] where - the key is a shared secret and the digested text is the timestamp - (including angle-brackets). - - This shared secret is a string known only to the client and server. - The `digest' parameter itself is a 16-octet value which is sent in - hexadecimal format, using lower-case ASCII characters. - - When the server receives this client response, it verifies the digest - provided. If the digest is correct, the server should consider the - client authenticated and respond appropriately. - - Keyed MD5 is chosen for this application because of the greater - security imparted to authentication of short messages. In addition, - the use of the techniques described in [KEYED-MD5] for precomputation - of intermediate results make it possible to avoid explicit cleartext - storage of the shared secret on the server system by instead storing - the intermediate results which are known as "contexts". - - - - - - -Klensin, Catoe & Krumviede Standards Track [Page 2] - -RFC 2195 IMAP/POP AUTHorize Extension September 1997 - - - CRAM does not support a protection mechanism. - - Example: - - The examples in this document show the use of the CRAM mechanism with - the IMAP4 AUTHENTICATE command [IMAP-AUTH]. The base64 encoding of - the challenges and responses is part of the IMAP4 AUTHENTICATE - command, not part of the CRAM specification itself. - - S: * OK IMAP4 Server - C: A0001 AUTHENTICATE CRAM-MD5 - S: + PDE4OTYuNjk3MTcwOTUyQHBvc3RvZmZpY2UucmVzdG9uLm1jaS5uZXQ+ - C: dGltIGI5MTNhNjAyYzdlZGE3YTQ5NWI0ZTZlNzMzNGQzODkw - S: A0001 OK CRAM authentication successful - - In this example, the shared secret is the string - 'tanstaaftanstaaf'. Hence, the Keyed MD5 digest is produced by - calculating - - MD5((tanstaaftanstaaf XOR opad), - MD5((tanstaaftanstaaf XOR ipad), - <1896.697170952@postoffice.reston.mci.net>)) - - where ipad and opad are as defined in the keyed-MD5 Work in - Progress [KEYED-MD5] and the string shown in the challenge is the - base64 encoding of <1896.697170952@postoffice.reston.mci.net>. The - shared secret is null-padded to a length of 64 bytes. If the - shared secret is longer than 64 bytes, the MD5 digest of the - shared secret is used as a 16 byte input to the keyed MD5 - calculation. - - This produces a digest value (in hexadecimal) of - - b913a602c7eda7a495b4e6e7334d3890 - - The user name is then prepended to it, forming - - tim b913a602c7eda7a495b4e6e7334d3890 - - Which is then base64 encoded to meet the requirements of the IMAP4 - AUTHENTICATE command (or the similar POP3 AUTH command), yielding - - dGltIGI5MTNhNjAyYzdlZGE3YTQ5NWI0ZTZlNzMzNGQzODkw - - - - - - - - -Klensin, Catoe & Krumviede Standards Track [Page 3] - -RFC 2195 IMAP/POP AUTHorize Extension September 1997 - - -3. References - - [CHAP] Lloyd, B., and W. Simpson, "PPP Authentication Protocols", - RFC 1334, October 1992. - - [IMAP] Crispin, M., "Internet Message Access Protocol - Version - 4rev1", RFC 2060, University of Washington, December 1996. - - [IMAP-AUTH] Myers, J., "IMAP4 Authentication Mechanisms", - RFC 1731, Carnegie Mellon, December 1994. - - [KEYED-MD5] Krawczyk, Bellare, Canetti, "HMAC: Keyed-Hashing for - Message Authentication", RFC 2104, February 1997. - - [MD5] Rivest, R., "The MD5 Message Digest Algorithm", - RFC 1321, MIT Laboratory for Computer Science, April 1992. - - [POP3] Myers, J., and M. Rose, "Post Office Protocol - Version 3", - STD 53, RFC 1939, Carnegie Mellon, May 1996. - - [POP3-AUTH] Myers, J., "POP3 AUTHentication command", RFC 1734, - Carnegie Mellon, December, 1994. - -4. Security Considerations - - It is conjectured that use of the CRAM authentication mechanism - provides origin identification and replay protection for a session. - Accordingly, a server that implements both a cleartext password - command and this authentication type should not allow both methods of - access for a given user. - - While the saving, on the server, of "contexts" (see section 2) is - marginally better than saving the shared secrets in cleartext as is - required by CHAP [CHAP] and APOP [POP3], it is not sufficient to - protect the secrets if the server itself is compromised. - Consequently, servers that store the secrets or contexts must both be - protected to a level appropriate to the potential information value - in user mailboxes and identities. - - As the length of the shared secret increases, so does the difficulty - of deriving it. - - While there are now suggestions in the literature that the use of MD5 - and keyed MD5 in authentication procedures probably has a limited - effective lifetime, the technique is now widely deployed and widely - understood. It is believed that this general understanding may - assist with the rapid replacement, by CRAM-MD5, of the current uses - of permanent cleartext passwords in IMAP. This document has been - - - -Klensin, Catoe & Krumviede Standards Track [Page 4] - -RFC 2195 IMAP/POP AUTHorize Extension September 1997 - - - deliberately written to permit easy upgrading to use SHA (or whatever - alternatives emerge) when they are considered to be widely available - and adequately safe. - - Even with the use of CRAM, users are still vulnerable to active - attacks. An example of an increasingly common active attack is 'TCP - Session Hijacking' as described in CERT Advisory CA-95:01 [CERT95]. - - See section 1 above for additional discussion. - -5. Acknowledgements - - This memo borrows ideas and some text liberally from [POP3] and - [RFC-1731] and thanks are due the authors of those documents. Ran - Atkinson made a number of valuable technical and editorial - contributions to the document. - -6. Authors' Addresses - - John C. Klensin - MCI Telecommunications - 800 Boylston St, 7th floor - Boston, MA 02199 - USA - - EMail: klensin@mci.net - Phone: +1 617 960 1011 - - Randy Catoe - MCI Telecommunications - 2100 Reston Parkway - Reston, VA 22091 - USA - - EMail: randy@mci.net - Phone: +1 703 715 7366 - - Paul Krumviede - MCI Telecommunications - 2100 Reston Parkway - Reston, VA 22091 - USA - - EMail: paul@mci.net - Phone: +1 703 715 7251 - - - - - - -Klensin, Catoe & Krumviede Standards Track [Page 5] - diff --git a/imap/docs/rfc/rfc2221.txt b/imap/docs/rfc/rfc2221.txt deleted file mode 100644 index 81d00620..00000000 --- a/imap/docs/rfc/rfc2221.txt +++ /dev/null @@ -1,283 +0,0 @@ - - - - - - -Network Working Group M. Gahrns -Request for Comments: 2221 Microsoft -Category: Standards Track October 1997 - - - IMAP4 Login Referrals - -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 (1997). All Rights Reserved. - -1. Abstract - - When dealing with large amounts of users and many IMAP4 [RFC-2060] - servers, it is often necessary to move users from one IMAP4 server to - another. For example, hardware failures or organizational changes - may dictate such a move. - - Login referrals allow clients to transparently connect to an - alternate IMAP4 server, if their home IMAP4 server has changed. - - A referral mechanism can provide efficiencies over the alternative - 'proxy method', in which the local IMAP4 server contacts the remote - server on behalf of the client, and then transfers the data from the - remote server to itself, and then on to the client. The referral - mechanism's direct client connection to the remote server is often a - more efficient use of bandwidth, and does not require the local - server to impersonate the client when authenticating to the remote - server. - -2. Conventions used in this document - - In examples, "C:" and "S:" indicate lines sent by the client and - server respectively. - - A home server, is an IMAP4 server that contains the user's inbox. - - A remote server is a server that contains remote mailboxes. - - - - - -Gahrns Standards Track [Page 1] - -RFC 2221 IMAP4 Login Referrals October 1997 - - - 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]. - -3. Introduction and Overview - - IMAP4 servers that support this extension MUST list the keyword - LOGIN-REFERRALS in their CAPABILITY response. No client action is - needed to invoke the LOGIN-REFERRALS capability in a server. - - A LOGIN-REFERRALS capable IMAP4 server SHOULD NOT return a referral - to a server that will return a referral. A client MUST NOT follow - more than 10 levels of referral without consulting the user. - - A LOGIN-REFERRALS response code MUST contain as an argument a valid - IMAP server URL as defined in [IMAP-URL]. - - A home server referral consists of either a tagged NO or OK, or an - untagged BYE response that contains a LOGIN-REFERRALS response code. - - Example: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/] Remote Server - - NOTE: user;AUTH=* is specified as required by [IMAP-URL] to avoid a - client falling back to anonymous login. - -4. Home Server Referrals - - A home server referral may be returned in response to an AUTHENTICATE - or LOGIN command, or it may appear in the connection startup banner. - If a server returns a home server referral in a tagged NO response, - that server does not contain any mailboxes that are accessible to the - user. If a server returns a home server referral in a tagged OK - response, it indicates that the user's personal mailboxes are - elsewhere, but the server contains public mailboxes which are - readable by the user. After receiving a home server referral, the - client can not make any assumptions as to whether this was a - permanent or temporary move of the user. - -4.1. LOGIN and AUTHENTICATE Referrals - - An IMAP4 server MAY respond to a LOGIN or AUTHENTICATE command with a - home server referral if it wishes to direct the user to another IMAP4 - server. - - Example: C: A001 LOGIN MIKE PASSWORD - S: A001 NO [REFERRAL IMAP://MIKE@SERVER2/] Specified user - is invalid on this server. Try SERVER2. - - - - -Gahrns Standards Track [Page 2] - -RFC 2221 IMAP4 Login Referrals October 1997 - - - Example: C: A001 LOGIN MATTHEW PASSWORD - S: A001 OK [REFERRAL IMAP://MATTHEW@SERVER2/] Specified - user's personal mailboxes located on Server2, but - public mailboxes are available. - - Example: C: A001 AUTHENTICATE GSSAPI - <authentication exchange> - S: A001 NO [REFERRAL IMAP://user;AUTH=GSSAPI@SERVER2/] - Specified user is invalid on this server. Try - SERVER2. - -4.2. BYE at connection startup referral - - An IMAP4 server MAY respond with an untagged BYE and a REFERRAL - response code that contains an IMAP URL to a home server if it is not - willing to accept connections and wishes to direct the client to - another IMAP4 server. - - Example: S: * BYE [REFERRAL IMAP://user;AUTH=*@SERVER2/] Server not - accepting connections. Try SERVER2 - -5. Formal Syntax - - The following syntax specification uses the augmented Backus-Naur - Form (BNF) as described in [ABNF]. - - This amends the "resp_text_code" element of the IMAP4 grammar - described in [RFC-2060] - - resp_text_code =/ "REFERRAL" SPACE <imapurl> - ; See [IMAP-URL] for definition of <imapurl> - ; See [RFC-2060] for base definition of resp_text_code - -6. Security Considerations - - The IMAP4 login referral mechanism makes use of IMAP URLs, and as - such, have the same security considerations as general internet URLs - [RFC-1738], and in particular IMAP URLs [IMAP-URL]. - - A server MUST NOT give a login referral if authentication for that - user fails. This is to avoid revealing information about the user's - account to an unauthorized user. - - With the LOGIN-REFERRALS capability, it is potentially easier to - write a rogue 'password catching' server that collects login data and - then refers the client to their actual IMAP4 server. Although - referrals reduce the effort to write such a server, the referral - response makes detection of the intrusion easier. - - - -Gahrns Standards Track [Page 3] - -RFC 2221 IMAP4 Login Referrals October 1997 - - -7. References - - [RFC-2060], Crispin, M., "Internet Message Access Protocol - Version - 4rev1", RFC 2060, December 1996. - - [IMAP-URL], Newman, C., "IMAP URL Scheme", RFC 2192, Innosoft, - September 1997. - - [RFC-1738], Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform - Resource Locators (URL)", RFC 1738, December 1994. - - [RFC-2119], Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", RFC 2119, March 1997. - - [ABNF], DRUMS working group, Dave Crocker Editor, "Augmented BNF for - Syntax Specifications: ABNF", Work in Progress. - -8. Acknowledgments - - Many valuable suggestions were received from private discussions and - the IMAP4 mailing list. In particular, Raymond Cheng, Mark Crispin, - Mark Keasling Chris Newman and Larry Osterman made significant - contributions to this document. - -9. Author's Address - - Mike Gahrns - Microsoft - One Microsoft Way - Redmond, WA, 98072 - - Phone: (206) 936-9833 - EMail: mikega@microsoft.com - - - - - - - - - - - - - - - - - - -Gahrns Standards Track [Page 4] - -RFC 2221 IMAP4 Login Referrals October 1997 - - -10. Full Copyright Statement - - Copyright (C) The Internet Society (1997). 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 implmentation may be prepared, copied, published - andand 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." - - - - - - - - - - - - - - - - - - - - - - - - -Gahrns Standards Track [Page 5] - diff --git a/imap/docs/rfc/rfc2342.txt b/imap/docs/rfc/rfc2342.txt deleted file mode 100644 index 0926646d..00000000 --- a/imap/docs/rfc/rfc2342.txt +++ /dev/null @@ -1,563 +0,0 @@ - - - - - - -Network Working Group M. Gahrns -Request for Comments: 2342 Microsoft -Category: Standards Track C. Newman - Innosoft - May 1998 - - - IMAP4 Namespace - -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 (1998). All Rights Reserved. - -1. Abstract - - IMAP4 [RFC-2060] does not define a default server namespace. As a - result, two common namespace models have evolved: - - The "Personal Mailbox" model, in which the default namespace that is - presented consists of only the user's personal mailboxes. To access - shared mailboxes, the user must use an escape mechanism to reach - another namespace. - - The "Complete Hierarchy" model, in which the default namespace that - is presented includes the user's personal mailboxes along with any - other mailboxes they have access to. - - These two models, create difficulties for certain client operations. - This document defines a NAMESPACE command that allows a client to - discover the prefixes of namespaces used by a server for personal - mailboxes, other users' mailboxes, and shared mailboxes. This allows - a client to avoid much of the manual user configuration that is now - necessary when mixing and matching IMAP4 clients and servers. - -2. Conventions used in this document - - In examples, "C:" and "S:" indicate lines sent by the client and - server respectively. If such lines are wrapped without a new "C:" or - "S:" label, then the wrapping is for editorial clarity and is not - part of the command. - - - -Gahrns & Newman Standards Track [Page 1] - -RFC 2342 IMAP4 Namespace May 1998 - - - Personal Namespace: A namespace that the server considers within the - personal scope of the authenticated user on a particular connection. - Typically, only the authenticated user has access to mailboxes in - their Personal Namespace. It is the part of the namespace that - belongs to the user that is allocated for mailboxes. If an INBOX - exists for a user, it MUST appear within the user's personal - namespace. In the typical case, there SHOULD be only one Personal - Namespace on a server. - - Other Users' Namespace: A namespace that consists of mailboxes from - the Personal Namespaces of other users. To access mailboxes in the - Other Users' Namespace, the currently authenticated user MUST be - explicitly granted access rights. For example, it is common for a - manager to grant to their secretary access rights to their mailbox. - In the typical case, there SHOULD be only one Other Users' Namespace - on a server. - - Shared Namespace: A namespace that consists of mailboxes that are - intended to be shared amongst users and do not exist within a user's - Personal Namespace. - - The namespaces a server uses MAY differ on a per-user basis. - - 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]. - -3. Introduction and Overview - - Clients often attempt to create mailboxes for such purposes as - maintaining a record of sent messages (e.g. "Sent Mail") or - temporarily saving messages being composed (e.g. "Drafts"). For - these clients to inter-operate correctly with the variety of IMAP4 - servers available, the user must enter the prefix of the Personal - Namespace used by the server. Using the NAMESPACE command, a client - is able to automatically discover this prefix without manual user - configuration. - - In addition, users are often required to manually enter the prefixes - of various namespaces in order to view the mailboxes located there. - For example, they might be required to enter the prefix of #shared to - view the shared mailboxes namespace. The NAMESPACE command allows a - client to automatically discover the namespaces that are available on - a server. This allows a client to present the available namespaces to - the user in what ever manner it deems appropriate. For example, a - - - - - - -Gahrns & Newman Standards Track [Page 2] - -RFC 2342 IMAP4 Namespace May 1998 - - - client could choose to initially display only personal mailboxes, or - it may choose to display the complete list of mailboxes available, - and initially position the user at the root of their Personal - Namespace. - - A server MAY choose to make available to the NAMESPACE command only a - subset of the complete set of namespaces the server supports. To - provide the ability to access these namespaces, a client SHOULD allow - the user the ability to manually enter a namespace prefix. - -4. Requirements - - IMAP4 servers that support this extension MUST list the keyword - NAMESPACE in their CAPABILITY response. - - The NAMESPACE command is valid in the Authenticated and Selected - state. - -5. NAMESPACE Command - - Arguments: none - - Response: an untagged NAMESPACE response that contains the prefix - and hierarchy delimiter to the server's Personal - Namespace(s), Other Users' Namespace(s), and Shared - Namespace(s) that the server wishes to expose. The - response will contain a NIL for any namespace class - that is not available. Namespace_Response_Extensions - MAY be included in the response. - Namespace_Response_Extensions which are not on the IETF - standards track, MUST be prefixed with an "X-". - - Result: OK - Command completed - NO - Error: Can't complete command - BAD - argument invalid - - Example 5.1: - =========== - - < A server that supports a single personal namespace. No leading - prefix is used on personal mailboxes and "/" is the hierarchy - delimiter.> - - C: A001 NAMESPACE - S: * NAMESPACE (("" "/")) NIL NIL - S: A001 OK NAMESPACE command completed - - - - - -Gahrns & Newman Standards Track [Page 3] - -RFC 2342 IMAP4 Namespace May 1998 - - - Example 5.2: - =========== - - < A user logged on anonymously to a server. No personal mailboxes - are associated with the anonymous user and the user does not have - access to the Other Users' Namespace. No prefix is required to - access shared mailboxes and the hierarchy delimiter is "." > - - C: A001 NAMESPACE - S: * NAMESPACE NIL NIL (("" ".")) - S: A001 OK NAMESPACE command completed - - Example 5.3: - =========== - - < A server that contains a Personal Namespace and a single Shared - Namespace. > - - C: A001 NAMESPACE - S: * NAMESPACE (("" "/")) NIL (("Public Folders/" "/")) - S: A001 OK NAMESPACE command completed - - Example 5.4: - =========== - - < A server that contains a Personal Namespace, Other Users' - Namespace and multiple Shared Namespaces. Note that the hierarchy - delimiter used within each namespace can be different. > - - C: A001 NAMESPACE - S: * NAMESPACE (("" "/")) (("~" "/")) (("#shared/" "/") - ("#public/" "/")("#ftp/" "/")("#news." ".")) - S: A001 OK NAMESPACE command completed - - The prefix string allows a client to do things such as automatically - creating personal mailboxes or LISTing all available mailboxes within - a namespace. - - Example 5.5: - =========== - - < A server that supports only the Personal Namespace, with a - leading prefix of INBOX to personal mailboxes and a hierarchy - delimiter of "."> - - C: A001 NAMESPACE - S: * NAMESPACE (("INBOX." ".")) NIL NIL - S: A001 OK NAMESPACE command completed - - - -Gahrns & Newman Standards Track [Page 4] - -RFC 2342 IMAP4 Namespace May 1998 - - - < Automatically create a mailbox to store sent items.> - - C: A002 CREATE "INBOX.Sent Mail" - S: A002 OK CREATE command completed - - Although typically a server will support only a single Personal - Namespace, and a single Other User's Namespace, circumstances exist - where there MAY be multiples of these, and a client MUST be prepared - for them. If a client is configured such that it is required to - create a certain mailbox, there can be circumstances where it is - unclear which Personal Namespaces it should create the mailbox in. - In these situations a client SHOULD let the user select which - namespaces to create the mailbox in. - - Example 5.6: - =========== - - < In this example, a server supports 2 Personal Namespaces. In - addition to the regular Personal Namespace, the user has an - additional personal namespace to allow access to mailboxes in an - MH format mailstore. > - - < The client is configured to save a copy of all mail sent by the - user into a mailbox called 'Sent Mail'. Furthermore, after a - message is deleted from a mailbox, the client is configured to - move that message to a mailbox called 'Deleted Items'.> - - < Note that this example demonstrates how some extension flags can - be passed to further describe the #mh namespace. > - - C: A001 NAMESPACE - S: * NAMESPACE (("" "/")("#mh/" "/" "X-PARAM" ("FLAG1" "FLAG2"))) - NIL NIL - S: A001 OK NAMESPACE command completed - - < It is desired to keep only one copy of sent mail. It is unclear - which Personal Namespace the client should use to create the 'Sent - Mail' mailbox. The user is prompted to select a namespace and - only one 'Sent Mail' mailbox is created. > - - C: A002 CREATE "Sent Mail" - S: A002 OK CREATE command completed - - < The client is designed so that it keeps two 'Deleted Items' - mailboxes, one for each namespace. > - - C: A003 CREATE "Delete Items" - S: A003 OK CREATE command completed - - - -Gahrns & Newman Standards Track [Page 5] - -RFC 2342 IMAP4 Namespace May 1998 - - - C: A004 CREATE "#mh/Deleted Items" - S: A004 OK CREATE command completed - - The next level of hierarchy following the Other Users' Namespace - prefix SHOULD consist of <username>, where <username> is a user name - as per the IMAP4 LOGIN or AUTHENTICATE command. - - A client can construct a LIST command by appending a "%" to the Other - Users' Namespace prefix to discover the Personal Namespaces of other - users that are available to the currently authenticated user. - - In response to such a LIST command, a server SHOULD NOT return user - names that have not granted access to their personal mailboxes to the - user in question. - - A server MAY return a LIST response containing only the names of - users that have explicitly granted access to the user in question. - - Alternatively, a server MAY return NO to such a LIST command, - requiring that a user name be included with the Other Users' - Namespace prefix before listing any other user's mailboxes. - - Example 5.7: - =========== - - < A server that supports providing a list of other user's - mailboxes that are accessible to the currently logged on user. > - - C: A001 NAMESPACE - S: * NAMESPACE (("" "/")) (("Other Users/" "/")) NIL - S: A001 OK NAMESPACE command completed - - C: A002 LIST "" "Other Users/%" - S: * LIST () "/" "Other Users/Mike" - S: * LIST () "/" "Other Users/Karen" - S: * LIST () "/" "Other Users/Matthew" - S: * LIST () "/" "Other Users/Tesa" - S: A002 OK LIST command completed - - Example 5.8: - =========== - - < A server that does not support providing a list of other user's - mailboxes that are accessible to the currently logged on user. - The mailboxes are listable if the client includes the name of the - other user with the Other Users' Namespace prefix. > - - - - - -Gahrns & Newman Standards Track [Page 6] - -RFC 2342 IMAP4 Namespace May 1998 - - - C: A001 NAMESPACE - S: * NAMESPACE (("" "/")) (("#Users/" "/")) NIL - S: A001 OK NAMESPACE command completed - - < In this example, the currently logged on user has access to the - Personal Namespace of user Mike, but the server chose to suppress - this information in the LIST response. However, by appending the - user name Mike (received through user input) to the Other Users' - Namespace prefix, the client is able to get a listing of the - personal mailboxes of user Mike. > - - C: A002 LIST "" "#Users/%" - S: A002 NO The requested item could not be found. - - C: A003 LIST "" "#Users/Mike/%" - S: * LIST () "/" "#Users/Mike/INBOX" - S: * LIST () "/" "#Users/Mike/Foo" - S: A003 OK LIST command completed. - - A prefix string might not contain a hierarchy delimiter, because - in some cases it is not needed as part of the prefix. - - Example 5.9: - =========== - - < A server that allows access to the Other Users' Namespace by - prefixing the others' mailboxes with a '~' followed by <username>, - where <username> is a user name as per the IMAP4 LOGIN or - AUTHENTICATE command.> - - C: A001 NAMESPACE - S: * NAMESPACE (("" "/")) (("~" "/")) NIL - S: A001 OK NAMESPACE command completed - - < List the mailboxes for user mark > - - C: A002 LIST "" "~mark/%" - S: * LIST () "/" "~mark/INBOX" - S: * LIST () "/" "~mark/foo" - S: A002 OK LIST command completed - - Historical convention has been to start all namespaces with the "#" - character. Namespaces that include the "#" character are not IMAP - URL [IMAP-URL] friendly requiring the "#" character to be represented - as %23 when within URLs. As such, server implementers MAY instead - consider using namespace prefixes that do not contain the "#" - character. - - - - -Gahrns & Newman Standards Track [Page 7] - -RFC 2342 IMAP4 Namespace May 1998 - - -6. Formal Syntax - - The following syntax specification uses the augmented Backus-Naur - Form (BNF) as described in [ABNF]. - - atom = <atom> - ; <atom> as defined in [RFC-2060] - - Namespace = nil / "(" 1*( "(" string SP (<"> QUOTED_CHAR <"> / - nil) *(Namespace_Response_Extension) ")" ) ")" - - Namespace_Command = "NAMESPACE" - - Namespace_Response_Extension = SP string SP "(" string *(SP string) - ")" - - Namespace_Response = "*" SP "NAMESPACE" SP Namespace SP Namespace SP - Namespace - - ; The first Namespace is the Personal Namespace(s) - ; The second Namespace is the Other Users' Namespace(s) - ; The third Namespace is the Shared Namespace(s) - - nil = <nil> - ; <nil> as defined in [RFC-2060] - - QUOTED_CHAR = <QUOTED_CHAR> - ; <QUOTED_CHAR> as defined in [RFC-2060] - - string = <string> - ; <string> as defined in [RFC-2060] - ; Note that the namespace prefix is to a mailbox and following - ; IMAP4 convention, any international string in the NAMESPACE - ; response MUST be of modified UTF-7 format as described in - ; [RFC-2060]. - -7. Security Considerations - - In response to a LIST command containing an argument of the Other - Users' Namespace prefix, a server SHOULD NOT list users that have not - granted list access to their personal mailboxes to the currently - authenticated user. Providing such a list, could compromise security - by potentially disclosing confidential information of who is located - on the server, or providing a starting point of a list of user - accounts to attack. - - - - - - -Gahrns & Newman Standards Track [Page 8] - -RFC 2342 IMAP4 Namespace May 1998 - - -8. References - - [RFC-2060], Crispin, M., "Internet Message Access Protocol Version - 4rev1", RFC 2060, December 1996. - - [RFC-2119], Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [ABNF] Crocker, D., Editor, and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", RFC 2234, November 1997. - - [IMAP-URL], Newman, C., "IMAP URL Scheme", RFC 2192, September 1997. - -9. Acknowledgments - - Many people have participated in the discussion of IMAP namespaces on - the IMAP mailing list. In particular, the authors would like to - thank Mark Crispin for many of the concepts relating to the Personal - Namespace and accessing the Personal Namespace of other users, Steve - Hole for summarizing the two namespace models, John Myers and Jack De - Winter for their work in a preceding effort trying to define a - standardized personal namespace, and Larry Osterman for his review - and collaboration on this document. - -11. Authors' Addresses - - Mike Gahrns - Microsoft - One Microsoft Way - Redmond, WA, 98072, USA - - Phone: (425) 936-9833 - EMail: mikega@microsoft.com - - - Chris Newman - Innosoft International, Inc. - 1050 East Garvey Ave. South - West Covina, CA, 91790, USA - - EMail: chris.newman@innosoft.com - - - - - - - - - - -Gahrns & Newman Standards Track [Page 9] - -RFC 2342 IMAP4 Namespace May 1998 - - -12. Full Copyright Statement - - Copyright (C) The Internet Society (1998). 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. - - - - - - - - - - - - - - - - - - - - - - - - -Gahrns & Newman Standards Track [Page 10] - diff --git a/imap/docs/rfc/rfc2683.txt b/imap/docs/rfc/rfc2683.txt deleted file mode 100644 index d92e3405..00000000 --- a/imap/docs/rfc/rfc2683.txt +++ /dev/null @@ -1,1291 +0,0 @@ - - - - - - -Network Working Group B. Leiba -Request for Comments: 2683 IBM T.J. Watson Research Center -Category: Informational September 1999 - - - IMAP4 Implementation Recommendations - -Status of this Memo - - This memo provides information for the Internet community. It does - not specify an Internet standard of any kind. Distribution of this - memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (1999). All Rights Reserved. - -1. Abstract - - The IMAP4 specification [RFC-2060] describes a rich protocol for use - in building clients and servers for storage, retrieval, and - manipulation of electronic mail. Because the protocol is so rich and - has so many implementation choices, there are often trade-offs that - must be made and issues that must be considered when designing such - clients and servers. This document attempts to outline these issues - and to make recommendations in order to make the end products as - interoperable as possible. - -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 words "must", "must not", "should", "should not", and "may" are - used with specific meaning in this document; since their meaning is - somewhat different from that specified in RFC 2119, we do not put - them in all caps here. Their meaning is as follows: - - must -- This word means that the action described is necessary - to ensure interoperability. The recommendation should - not be ignored. - must not -- This phrase means that the action described will be - almost certain to hurt interoperability. The - recommendation should not be ignored. - - - - - - - -Leiba Informational [Page 1] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - - should -- This word means that the action described is strongly - recommended and will enhance interoperability or - usability. The recommendation should not be ignored - without careful consideration. - should not -- This phrase means that the action described is strongly - recommended against, and might hurt interoperability or - usability. The recommendation should not be ignored - without careful consideration. - may -- This word means that the action described is an - acceptable implementation choice. No specific - recommendation is implied; this word is used to point - out a choice that might not be obvious, or to let - implementors know what choices have been made by - existing implementations. - -3. Interoperability Issues and Recommendations - -3.1. Accessibility - - This section describes the issues related to access to servers and - server resources. Concerns here include data sharing and maintenance - of client/server connections. - -3.1.1. Multiple Accesses of the Same Mailbox - - One strong point of IMAP4 is that, unlike POP3, it allows for - multiple simultaneous access to a single mailbox. A user can, thus, - read mail from a client at home while the client in the office is - still connected; or the help desk staff can all work out of the same - inbox, all seeing the same pool of questions. An important point - about this capability, though is that NO SERVER IS GUARANTEED TO - SUPPORT THIS. If you are selecting an IMAP server and this facility - is important to you, be sure that the server you choose to install, - in the configuration you choose to use, supports it. - - If you are designing a client, you must not assume that you can - access the same mailbox more than once at a time. That means - - 1. you must handle gracefully the failure of a SELECT command if the - server refuses the second SELECT, - 2. you must handle reasonably the severing of your connection (see - "Severed Connections", below) if the server chooses to allow the - second SELECT by forcing the first off, - 3. you must avoid making multiple connections to the same mailbox in - your own client (for load balancing or other such reasons), and - 4. you must avoid using the STATUS command on a mailbox that you have - selected (with some server implementations the STATUS command has - the same problems with multiple access as do the SELECT and - - - -Leiba Informational [Page 2] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - - EXAMINE commands). - - A further note about STATUS: The STATUS command is sometimes used to - check a non-selected mailbox for new mail. This mechanism must not - be used to check for new mail in the selected mailbox; section 5.2 of - [RFC-2060] specifically forbids this in its last paragraph. Further, - since STATUS takes a mailbox name it is an independent operation, not - operating on the selected mailbox. Because of this, the information - it returns is not necessarily in synchronization with the selected - mailbox state. - -3.1.2. Severed Connections - - The client/server connection may be severed for one of three reasons: - the client severs the connection, the server severs the connection, - or the connection is severed by outside forces beyond the control of - the client and the server (a telephone line drops, for example). - Clients and servers must both deal with these situations. - - When the client wants to sever a connection, it's usually because it - has finished the work it needed to do on that connection. The client - should send a LOGOUT command, wait for the tagged response, and then - close the socket. But note that, while this is what's intended in - the protocol design, there isn't universal agreement here. Some - contend that sending the LOGOUT and waiting for the two responses - (untagged BYE and tagged OK) is wasteful and unnecessary, and that - the client can simply close the socket. The server should interpret - the closed socket as a log out by the client. The counterargument is - that it's useful from the standpoint of cleanup, problem - determination, and the like, to have an explicit client log out, - because otherwise there is no way for the server to tell the - difference between "closed socket because of log out" and "closed - socket because communication was disrupted". If there is a - client/server interaction problem, a client which routinely - terminates a session by breaking the connection without a LOGOUT will - make it much more difficult to determine the problem. - - Because of this disagreement, server designers must be aware that - some clients might close the socket without sending a LOGOUT. In any - case, whether or not a LOGOUT was sent, the server should not - implicitly expunge any messages from the selected mailbox. If a - client wants the server to do so, it must send a CLOSE or EXPUNGE - command explicitly. - - When the server wants to sever a connection it's usually due to an - inactivity timeout or is because a situation has arisen that has - changed the state of the mail store in a way that the server can not - communicate to the client. The server should send an untagged BYE - - - -Leiba Informational [Page 3] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - - response to the client and then close the socket. Sending an - untagged BYE response before severing allows the server to send a - human-readable explanation of the problem to the client, which the - client may then log, display to the user, or both (see section 7.1.5 - of [RFC-2060]). - - Regarding inactivity timeouts, there is some controversy. Unlike - POP, for which the design is for a client to connect, retrieve mail, - and log out, IMAP's design encourages long-lived (and mostly - inactive) client/server sessions. As the number of users grows, this - can use up a lot of server resources, especially with clients that - are designed to maintain sessions for mailboxes that the user has - finished accessing. To alleviate this, a server may implement an - inactivity timeout, unilaterally closing a session (after first - sending an untagged BYE, as noted above). Some server operators have - reported dramatic improvements in server performance after doing - this. As specified in [RFC-2060], if such a timeout is done it must - not be until at least 30 minutes of inactivity. The reason for this - specification is to prevent clients from sending commands (such as - NOOP) to the server at frequent intervals simply to avert a too-early - timeout. If the client knows that the server may not time out the - session for at least 30 minutes, then the client need not poll at - intervals more frequent than, say, 25 minutes. - -3.2. Scaling - - IMAP4 has many features that allow for scalability, as mail stores - become larger and more numerous. Large numbers of users, mailboxes, - and messages, and very large messages require thought to handle - efficiently. This document will not address the administrative - issues involved in large numbers of users, but we will look at the - other items. - -3.2.1. Flood Control - - There are three situations when a client can make a request that will - result in a very large response - too large for the client reasonably - to deal with: there are a great many mailboxes available, there are a - great many messages in the selected mailbox, or there is a very large - message part. The danger here is that the end user will be stuck - waiting while the server sends (and the client processes) an enormous - response. In all of these cases there are things a client can do to - reduce that danger. - - There is also the case where a client can flood a server, by sending - an arbitratily long command. We'll discuss that issue, too, in this - section. - - - - -Leiba Informational [Page 4] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - -3.2.1.1. Listing Mailboxes - - Some servers present Usenet newsgroups to IMAP users. Newsgroups, - and other such hierarchical mailbox structures, can be very numerous - but may have only a few entries at the top level of hierarchy. Also, - some servers are built against mail stores that can, unbeknownst to - the server, have circular hierarchies - that is, it's possible for - "a/b/c/d" to resolve to the same file structure as "a", which would - then mean that "a/b/c/d/b" is the same as "a/b", and the hierarchy - will never end. The LIST response in this case will be unlimited. - - Clients that will have trouble with this are those that use - - C: 001 LIST "" * - - to determine the mailbox list. Because of this, clients should not - use an unqualified "*" that way in the LIST command. A safer - approach is to list each level of hierarchy individually, allowing - the user to traverse the tree one limb at a time, thus: - - C: 001 LIST "" % - S: * LIST () "/" Banana - S: * LIST ...etc... - S: 001 OK done - - and then - - C: 002 LIST "" Banana/% - S: * LIST () "/" Banana/Apple - S: * LIST ...etc... - S: 002 OK done - - Using this technique the client's user interface can give the user - full flexibility without choking on the voluminous reply to "LIST *". - - Of course, it is still possible that the reply to - - C: 005 LIST "" alt.fan.celebrity.% - - may be thousands of entries long, and there is, unfortunately, - nothing the client can do to protect itself from that. This has not - yet been a notable problem. - - Servers that may export circular hierarchies (any server that - directly presents a UNIX file system, for instance) should limit the - hierarchy depth to prevent unlimited LIST responses. A suggested - depth limit is 20 hierarchy levels. - - - - -Leiba Informational [Page 5] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - -3.2.1.2. Fetching the List of Messages - - When a client selects a mailbox, it is given a count, in the untagged - EXISTS response, of the messages in the mailbox. This number can be - very large. In such a case it might be unwise to use - - C: 004 FETCH 1:* ALL - - to populate the user's view of the mailbox. One good method to avoid - problems with this is to batch the requests, thus: - - C: 004 FETCH 1:50 ALL - S: * 1 FETCH ...etc... - S: 004 OK done - C: 005 FETCH 51:100 ALL - S: * 51 FETCH ...etc... - S: 005 OK done - C: 006 FETCH 101:150 ALL - ...etc... - - Using this method, another command, such as "FETCH 6 BODY[1]" can be - inserted as necessary, and the client will not have its access to the - server blocked by a storm of FETCH replies. (Such a method could be - reversed to fetch the LAST 50 messages first, then the 50 prior to - that, and so on.) - - As a smart extension of this, a well designed client, prepared for - very large mailboxes, will not automatically fetch data for all - messages AT ALL. Rather, the client will populate the user's view - only as the user sees it, possibly pre-fetching selected information, - and only fetching other information as the user scrolls to it. For - example, to select only those messages beginning with the first - unseen one: - - C: 003 SELECT INBOX - S: * 10000 EXISTS - S: * 80 RECENT - S: * FLAGS (\Answered \Flagged \Deleted \Draft \Seen) - S: * OK [UIDVALIDITY 824708485] UID validity status - S: * OK [UNSEEN 9921] First unseen message - S: 003 OK [READ-WRITE] SELECT completed - C: 004 FETCH 9921:* ALL - ... etc... - - If the server does not return an OK [UNSEEN] response, the client may - use SEARCH UNSEEN to obtain that value. - - - - - -Leiba Informational [Page 6] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - - This mechanism is good as a default presentation method, but only - works well if the default message order is acceptable. A client may - want to present various sort orders to the user (by subject, by date - sent, by sender, and so on) and in that case (lacking a SORT - extension on the server side) the client WILL have to retrieve all - message descriptors. A client that provides this service should not - do it by default and should inform the user of the costs of choosing - this option for large mailboxes. - -3.2.1.3. Fetching a Large Body Part - - The issue here is similar to the one for a list of messages. In the - BODYSTRUCTURE response the client knows the size, in bytes, of the - body part it plans to fetch. Suppose this is a 70 MB video clip. The - client can use partial fetches to retrieve the body part in pieces, - avoiding the problem of an uninterruptible 70 MB literal coming back - from the server: - - C: 022 FETCH 3 BODY[1]<0.20000> - S: * 3 FETCH (FLAGS(\Seen) BODY[1]<0> {20000} - S: ...data...) - S: 022 OK done - C: 023 FETCH 3 BODY[1]<20001.20000> - S: * 3 FETCH (BODY[1]<20001> {20000} - S: ...data...) - S: 023 OK done - C: 024 FETCH 3 BODY[1]<40001.20000> - ...etc... - -3.2.1.4. BODYSTRUCTURE vs. Entire Messages - - Because FETCH BODYSTRUCTURE is necessary in order to determine the - number of body parts, and, thus, whether a message has "attachments", - clients often use FETCH FULL as their normal method of populating the - user's view of a mailbox. The benefit is that the client can display - a paperclip icon or some such indication along with the normal - message summary. However, this comes at a significant cost with some - server configurations. The parsing needed to generate the FETCH - BODYSTRUCTURE response may be time-consuming compared with that - needed for FETCH ENVELOPE. The client developer should consider this - issue when deciding whether the ability to add a paperclip icon is - worth the tradeoff in performance, especially with large mailboxes. - - Some clients, rather than using FETCH BODYSTRUCTURE, use FETCH BODY[] - (or the equivalent FETCH RFC822) to retrieve the entire message. - They then do the MIME parsing in the client. This may give the - client slightly more flexibility in some areas (access, for instance, - to header fields that aren't returned in the BODYSTRUCTURE and - - - -Leiba Informational [Page 7] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - - ENVELOPE responses), but it can cause severe performance problems by - forcing the transfer of all body parts when the user might only want - to see some of them - a user logged on by modem and reading a small - text message with a large ZIP file attached may prefer to read the - text only and save the ZIP file for later. Therefore, a client - should not normally retrieve entire messages and should retrieve - message body parts selectively. - -3.2.1.5. Long Command Lines - - A client can wind up building a very long command line in an effort to - try to be efficient about requesting information from a server. This - can typically happen when a client builds a message set from selected - messages and doesn't recognise that contiguous blocks of messages may - be group in a range. Suppose a user selects all 10,000 messages in a - large mailbox and then unselects message 287. The client could build - that message set as "1:286,288:10000", but a client that doesn't - handle that might try to enumerate each message individually and build - "1,2,3,4, [and so on] ,9999,10000". Adding that to the fetch command - results in a command line that's almost 49,000 octets long, and, - clearly, one can construct a command line that's even longer. - - A client should limit the length of the command lines it generates to - approximately 1000 octets (including all quoted strings but not - including literals). If the client is unable to group things into - ranges so that the command line is within that length, it should - split the request into multiple commands. The client should use - literals instead of long quoted strings, in order to keep the command - length down. - - For its part, a server should allow for a command line of at least - 8000 octets. This provides plenty of leeway for accepting reasonable - length commands from clients. The server should send a BAD response - to a command that does not end within the server's maximum accepted - command length. - -3.2.2. Subscriptions - - The client isn't the only entity that can get flooded: the end user, - too, may need some flood control. The IMAP4 protocol provides such - control in the form of subscriptions. Most servers support the - SUBSCRIBE, UNSUBSCRIBE, and LSUB commands, and many users choose to - narrow down a large list of available mailboxes by subscribing to the - ones that they usually want to see. Clients, with this in mind, - should give the user a way to see only subscribed mailboxes. A - client that never uses the LSUB command takes a significant usability - feature away from the user. Of course, the client would not want to - hide the LIST command completely; the user needs to have a way to - - - -Leiba Informational [Page 8] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - - choose between LIST and LSUB. The usual way to do this is to provide - a setting like "show which mailboxes?: [] all [] subscribed only". - -3.2.3. Searching - - IMAP SEARCH commands can become particularly troublesome (that is, - slow) on mailboxes containing a large number of messages. So let's - put a few things in perspective in that regard. - - The flag searches should be fast. The flag searches (ALL, [UN]SEEN, - [UN]ANSWERED, [UN]DELETED, [UN]DRAFT, [UN]FLAGGED, NEW, OLD, RECENT) - are known to be used by clients for the client's own use (for - instance, some clients use "SEARCH UNSEEN" to find unseen mail and - "SEARCH DELETED" to warn the user before expunging messages). - - Other searches, particularly the text searches (HEADER, TEXT, BODY) - are initiated by the user, rather than by the client itself, and - somewhat slower performance can be tolerated, since the user is aware - that the search is being done (and is probably aware that it might be - time-consuming). A smart server might use dynamic indexing to speed - commonly used text searches. - - The client may allow other commands to be sent to the server while a - SEARCH is in progress, but at the time of this writing there is - little or no server support for parallel processing of multiple - commands in the same session (and see "Multiple Accesses of the Same - Mailbox" above for a description of the dangers of trying to work - around this by doing your SEARCH in another session). - - Another word about text searches: some servers, built on database - back-ends with indexed search capabilities, may return search results - that do not match the IMAP spec's "case-insensitive substring" - requirements. While these servers are in violation of the protocol, - there is little harm in the violation as long as the search results - are used only in response to a user's request. Still, developers of - such servers should be aware that they ARE violating the protocol, - should think carefully about that behaviour, and must be certain that - their servers respond accurately to the flag searches for the reasons - outlined above. - - In addition, servers should support CHARSET UTF-8 [UTF-8] in - searches. - - - - - - - - - -Leiba Informational [Page 9] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - -3.3 Avoiding Invalid Requests - - IMAP4 provides ways for a server to tell a client in advance what is - and isn't permitted in some circumstances. Clients should use these - features to avoid sending requests that a well designed client would - know to be invalid. This section explains this in more detail. - -3.3.1. The CAPABILITY Command - - All IMAP4 clients should use the CAPABILITY command to determine what - version of IMAP and what optional features a server supports. The - client should not send IMAP4rev1 commands and arguments to a server - that does not advertize IMAP4rev1 in its CAPABILITY response. - Similarly, the client should not send IMAP4 commands that no longer - exist in IMAP4rev1 to a server that does not advertize IMAP4 in its - CAPABILITY response. An IMAP4rev1 server is NOT required to support - obsolete IMAP4 or IMAP2bis commands (though some do; do not let this - fact lull you into thinking that it's valid to send such commands to - an IMAP4rev1 server). - - A client should not send commands to probe for the existance of - certain extensions. All standard and standards-track extensions - include CAPABILITY tokens indicating their presense. All private and - experimental extensions should do the same, and clients that take - advantage of them should use the CAPABILITY response to determine - whether they may be used or not. - -3.3.2. Don't Do What the Server Says You Can't - - In many cases, the server, in response to a command, will tell the - client something about what can and can't be done with a particular - mailbox. The client should pay attention to this information and - should not try to do things that it's been told it can't do. - - Examples: - - * Do not try to SELECT a mailbox that has the \Noselect flag set. - * Do not try to CREATE a sub-mailbox in a mailbox that has the - \Noinferiors flag set. - * Do not respond to a failing COPY or APPEND command by trying to - CREATE the target mailbox if the server does not respond with a - [TRYCREATE] response code. - * Do not try to expunge a mailbox that has been selected with the - [READ-ONLY] response code. - - - - - - - -Leiba Informational [Page 10] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - -3.4. Miscellaneous Protocol Considerations - - We describe here a number of important protocol-related issues, the - misunderstanding of which has caused significant interoperability - problems in IMAP4 implementations. One general item is that every - implementer should be certain to take note of and to understand - section 2.2.2 and the preamble to section 7 of the IMAP4rev1 spec - [RFC-2060]. - -3.4.1. Well Formed Protocol - - We cannot stress enough the importance of adhering strictly to the - protocol grammar. The specification of the protocol is quite rigid; - do not assume that you can insert blank space for "readability" if - none is called for. Keep in mind that there are parsers out there - that will crash if there are protocol errors. There are clients that - will report every parser burp to the user. And in any case, - information that cannot be parsed is information that is lost. Be - careful in your protocol generation. And see "A Word About Testing", - below. - - In particular, note that the string in the INTERNALDATE response is - NOT an RFC-822 date string - that is, it is not in the same format as - the first string in the ENVELOPE response. Since most clients will, - in fact, accept an RFC-822 date string in the INTERNALDATE response, - it's easy to miss this in your interoperability testing. But it will - cause a problem with some client, so be sure to generate the correct - string for this field. - -3.4.2. Special Characters - - Certain characters, currently the double-quote and the backslash, may - not be sent as-is inside a quoted string. These characters must be - preceded by the escape character if they are in a quoted string, or - else the string must be sent as a literal. Both clients and servers - must handle this, both on output (they must send these characters - properly) and on input (they must be able to receive escaped - characters in quoted strings). Example: - - C: 001 LIST "" % - S: * LIST () "" INBOX - S: * LIST () "\\" TEST - S: * LIST () "\\" {12} - S: "My" mailbox - S: 001 OK done - C: 002 LIST "" "\"My\" mailbox\\%" - S: * LIST () "\\" {17} - S: "My" mailbox\Junk - - - -Leiba Informational [Page 11] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - - S: 002 OK done - - Note that in the example the server sent the hierarchy delimiter as - an escaped character in the quoted string and sent the mailbox name - containing imbedded double-quotes as a literal. The client used only - quoted strings, escaping both the backslash and the double-quote - characters. - - The CR and LF characters may be sent ONLY in literals; they are not - allowed, even if escaped, inside quoted strings. - - And while we're talking about special characters: the IMAP spec, in - the section titled "Mailbox International Naming Convention", - describes how to encode mailbox names in modified UTF-7 [UTF-7 and - RFC-2060]. Implementations must adhere to this in order to be - interoperable in the international market, and servers should - validate mailbox names sent by client and reject names that do not - conform. - - As to special characters in userids and passwords: clients must not - restrict what a user may type in for a userid or a password. The - formal grammar specifies that these are "astrings", and an astring - can be a literal. A literal, in turn can contain any 8-bit - character, and clients must allow users to enter all 8-bit characters - here, and must pass them, unchanged, to the server (being careful to - send them as literals when necessary). In particular, some server - configurations use "@" in user names, and some clients do not allow - that character to be entered; this creates a severe interoperability - problem. - -3.4.3. UIDs and UIDVALIDITY - - Servers that support existing back-end mail stores often have no good - place to save UIDs for messages. Often the existing mail store will - not have the concept of UIDs in the sense that IMAP has: strictly - increasing, never re-issued, 32-bit integers. Some servers solve - this by storing the UIDs in a place that's accessible to end users, - allowing for the possibility that the users will delete them. Others - solve it by re-assigning UIDs every time a mailbox is selected. - - The server should maintain UIDs permanently for all messages if it - can. If that's not possible, the server must change the UIDVALIDITY - value for the mailbox whenever any of the UIDs may have become - invalid. Clients must recognize that the UIDVALIDITY has changed and - must respond to that condition by throwing away any information that - they have saved about UIDs in that mailbox. There have been many - problems in this area when clients have failed to do this; in the - worst case it will result in loss of mail when a client deletes the - - - -Leiba Informational [Page 12] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - - wrong piece of mail by using a stale UID. - - It seems to be a common misunderstanding that "the UIDVALIDITY and - the UID, taken together, form a 64-bit identifier that uniquely - identifies a message on a server". This is absolutely NOT TRUE. - There is no assurance that the UIDVALIDITY values of two mailboxes be - different, so the UIDVALIDITY in no way identifies a mailbox. The - ONLY purpose of UIDVALIDITY is, as its name indicates, to give the - client a way to check the validity of the UIDs it has cached. While - it is a valid implementation choice to put these values together to - make a 64-bit identifier for the message, the important concept here - is that UIDs are not unique between mailboxes; they are only unique - WITHIN a given mailbox. - - Some server implementations have attempted to make UIDs unique across - the entire server. This is inadvisable, in that it limits the life - of UIDs unnecessarily. The UID is a 32-bit number and will run out - in reasonably finite time if it's global across the server. If you - assign UIDs sequentially in one mailbox, you will not have to start - re-using them until you have had, at one time or another, 2**32 - different messages in that mailbox. In the global case, you will - have to reuse them once you have had, at one time or another, 2**32 - different messages in the entire mail store. Suppose your server has - around 8000 users registered (2**13). That gives an average of 2**19 - UIDs per user. Suppose each user gets 32 messages (2**5) per day. - That gives you 2**14 days (16000+ days = about 45 years) before you - run out. That may seem like enough, but multiply the usage just a - little (a lot of spam, a lot of mailing list subscriptions, more - users) and you limit yourself too much. - - What's worse is that if you have to wrap the UIDs, and, thus, you - have to change UIDVALIDITY and invalidate the UIDs in the mailbox, - you have to do it for EVERY mailbox in the system, since they all - share the same UID pool. If you assign UIDs per mailbox and you have - a problem, you only have to kill the UIDs for that one mailbox. - - Under extreme circumstances (and this is extreme, indeed), the server - may have to invalidate UIDs while a mailbox is in use by a client - - that is, the UIDs that the client knows about in its active mailbox - are no longer valid. In that case, the server must immediately - change the UIDVALIDITY and must communicate this to the client. The - server may do this by sending an unsolicited UIDVALIDITY message, in - the same form as in response to the SELECT command. Clients must be - prepared to handle such a message and the possibly coincident failure - of the command in process. For example: - - - - - - -Leiba Informational [Page 13] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - - C: 032 UID STORE 382 +Flags.silent \Deleted - S: * OK [UIDVALIDITY 12345] New UIDVALIDITY value! - S: 032 NO UID command rejected because UIDVALIDITY changed! - C: ...invalidates local information and re-fetches... - C: 033 FETCH 1:* UID - ...etc... - - At the time of the writing of this document, the only server known to - do this does so only under the following condition: the client - selects INBOX, but there is not yet a physical INBOX file created. - Nonetheless, the SELECT succeeds, exporting an empty INBOX with a - temporary UIDVALIDITY of 1. While the INBOX remains selected, mail - is delivered to the user, which creates the real INBOX file and - assigns a permanent UIDVALIDITY (that is likely not to be 1). The - server reports the change of UIDVALIDITY, but as there were no - messages before, so no UIDs have actually changed, all the client - must do is accept the change in UIDVALIDITY. - - Alternatively, a server may force the client to re-select the - mailbox, at which time it will obtain a new UIDVALIDITY value. To do - this, the server closes this client session (see "Severed - Connections" above) and the client then reconnects and gets back in - synch. Clients must be prepared for either of these behaviours. - - We do not know of, nor do we anticipate the future existance of, a - server that changes UIDVALIDITY while there are existing messages, - but clients must be prepared to handle this eventuality. - -3.4.4. FETCH Responses - - When a client asks for certain information in a FETCH command, the - server may return the requested information in any order, not - necessarily in the order that it was requested. Further, the server - may return the information in separate FETCH responses and may also - return information that was not explicitly requested (to reflect to - the client changes in the state of the subject message). Some - examples: - - C: 001 FETCH 1 UID FLAGS INTERNALDATE - S: * 5 FETCH (FLAGS (\Deleted)) - S: * 1 FETCH (FLAGS (\Seen) INTERNALDATE "..." UID 345) - S: 001 OK done - - (In this case, the responses are in a different order. Also, the - server returned a flag update for message 5, which wasn't part of the - client's request.) - - - - - -Leiba Informational [Page 14] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - - C: 002 FETCH 2 UID FLAGS INTERNALDATE - S: * 2 FETCH (INTERNALDATE "...") - S: * 2 FETCH (UID 399) - S: * 2 FETCH (FLAGS ()) - S: 002 OK done - - (In this case, the responses are in a different order and were - returned in separate responses.) - - C: 003 FETCH 2 BODY[1] - S: * 2 FETCH (FLAGS (\Seen) BODY[1] {14} - S: Hello world! - S: ) - S: 003 OK done - - (In this case, the FLAGS response was added by the server, since - fetching the body part caused the server to set the \Seen flag.) - - Because of this characteristic a client must be ready to receive any - FETCH response at any time and should use that information to update - its local information about the message to which the FETCH response - refers. A client must not assume that any FETCH responses will come - in any particular order, or even that any will come at all. If after - receiving the tagged response for a FETCH command the client finds - that it did not get all of the information requested, the client - should send a NOOP command to the server to ensure that the server - has an opportunity to send any pending EXPUNGE responses to the - client (see [RFC-2180]). - -3.4.5. RFC822.SIZE - - Some back-end mail stores keep the mail in a canonical form, rather - than retaining the original MIME format of the messages. This means - that the server must reassemble the message to produce a MIME stream - when a client does a fetch such as RFC822 or BODY[], requesting the - entire message. It also may mean that the server has no convenient - way to know the RFC822.SIZE of the message. Often, such a server - will actually have to build the MIME stream to compute the size, only - to throw the stream away and report the size to the client. - - When this is the case, some servers have chosen to estimate the size, - rather than to compute it precisely. Such an estimate allows the - client to display an approximate size to the user and to use the - estimate in flood control considerations (q.v.), but requires that - the client not use the size for things such as allocation of buffers, - because those buffers might then be too small to hold the actual MIME - stream. Instead, a client should use the size that's returned in the - literal when you fetch the data. - - - -Leiba Informational [Page 15] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - - The protocol requires that the RFC822.SIZE value returned by the - server be EXACT. Estimating the size is a protocol violation, and - server designers must be aware that, despite the performance savings - they might realize in using an estimate, this practice will cause - some clients to fail in various ways. If possible, the server should - compute the RFC822.SIZE for a particular message once, and then save - it for later retrieval. If that's not possible, the server must - compute the value exactly every time. Incorrect estimates do cause - severe interoperability problems with some clients. - -3.4.6. Expunged Messages - - If the server allows multiple connections to the same mailbox, it is - often possible for messages to be expunged in one client unbeknownst - to another client. Since the server is not allowed to tell the - client about these expunged messages in response to a FETCH command, - the server may have to deal with the issue of how to return - information about an expunged message. There was extensive - discussion about this issue, and the results of that discussion are - summarized in [RFC-2180]. See that reference for a detailed - explanation and for recommendations. - -3.4.7. The Namespace Issue - - Namespaces are a very muddy area in IMAP4 implementation right now - (see [NAMESPACE] for a proposal to clear the water a bit). Until the - issue is resolved, the important thing for client developers to - understand is that some servers provide access through IMAP to more - than just the user's personal mailboxes, and, in fact, the user's - personal mailboxes may be "hidden" somewhere in the user's default - hierarchy. The client, therefore, should provide a setting wherein - the user can specify a prefix to be used when accessing mailboxes. If - the user's mailboxes are all in "~/mail/", for instance, then the - user can put that string in the prefix. The client would then put - the prefix in front of any name pattern in the LIST and LSUB - commands: - - C: 001 LIST "" ~/mail/% - - (See also "Reference Names in the LIST Command" below.) - -3.4.8. Creating Special-Use Mailboxes - - It may seem at first that this is part of the namespace issue; it is - not, and is only indirectly related to it. A number of clients like - to create special-use mailboxes with particular names. Most - commonly, clients with a "trash folder" model of message deletion - want to create a mailbox with the name "Trash" or "Deleted". Some - - - -Leiba Informational [Page 16] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - - clients want to create a "Drafts" mailbox, an "Outbox" mailbox, or a - "Sent Mail" mailbox. And so on. There are two major - interoperability problems with this practice: - - 1. different clients may use different names for mailboxes with - similar functions (such as "Trash" and "Deleted"), or may manage - the same mailboxes in different ways, causing problems if a user - switches between clients and - 2. there is no guarantee that the server will allow the creation of - the desired mailbox. - - The client developer is, therefore, well advised to consider - carefully the creation of any special-use mailboxes on the server, - and, further, the client must not require such mailbox creation - - that is, if you do decide to do this, you must handle gracefully the - failure of the CREATE command and behave reasonably when your - special-use mailboxes do not exist and can not be created. - - In addition, the client developer should provide a convenient way for - the user to select the names for any special-use mailboxes, allowing - the user to make these names the same in all clients used and to put - them where the user wants them. - -3.4.9. Reference Names in the LIST Command - - Many implementers of both clients and servers are confused by the - "reference name" on the LIST command. The reference name is intended - to be used in much the way a "cd" (change directory) command is used - on Unix, PC DOS, Windows, and OS/2 systems. That is, the mailbox - name is interpreted in much the same way as a file of that name would - be found if one had done a "cd" command into the directory specified - by the reference name. For example, in Unix we have the following: - - > cd /u/jones/junk - > vi banana [file is "/u/jones/junk/banana"] - > vi stuff/banana [file is "/u/jones/junk/stuff/banana"] - > vi /etc/hosts [file is "/etc/hosts"] - - In the past, there have been several interoperability problems with - this. First, while some IMAP servers are built on Unix or PC file - systems, many others are not, and the file system semantics do not - make sense in those configurations. Second, while some IMAP servers - expose the underlying file system to the clients, others allow access - only to the user's personal mailboxes, or to some other limited set - of files, making such file-system-like semantics less meaningful. - Third, because the IMAP spec leaves the interpretation of the - reference name as "implementation-dependent", in the past the various - server implementations handled it in vastly differing ways. - - - -Leiba Informational [Page 17] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - - The following recommendations are the result of significant - operational experience, and are intended to maximize - interoperability. - - Server implementations must implement the reference argument in a way - that matches the intended "change directory" operation as closely as - possible. As a minimum implementation, the reference argument may be - prepended to the mailbox name (while suppressing double delimiters; - see the next paragraph). Even servers that do not provide a way to - break out of the current hierarchy (see "breakout facility" below) - must provide a reasonable implementation of the reference argument, - as described here, so that they will interoperate with clients that - use it. - - Server implementations that prepend the reference argument to the - mailbox name should insert a hierarchy delimiter between them, and - must not insert a second if one is already present: - - C: A001 LIST ABC DEF - S: * LIST () "/" ABC/DEF <=== should do this - S: A001 OK done - - C: A002 LIST ABC/ /DEF - S: * LIST () "/" ABC//DEF <=== must not do this - S: A002 OK done - - On clients, the reference argument is chiefly used to implement a - "breakout facility", wherein the user may directly access a mailbox - outside the "current directory" hierarchy. Client implementations - should have an operational mode that does not use the reference - argument. This is to interoperate with older servers that did not - implement the reference argument properly. While it's a good idea to - give the user access to a breakout facility, clients that do not - intend to do so should not use the reference argument at all. - - Client implementations should always place a trailing hierarchy - delimiter on the reference argument. This is because some servers - prepend the reference argument to the mailbox name without inserting - a hierarchy delimiter, while others do insert a hierarchy delimiter - if one is not already present. A client that puts the delimiter in - will work with both varieties of server. - - Client implementations that implement a breakout facility should - allow the user to choose whether or not to use a leading hierarchy - delimiter on the mailbox argument. This is because the handling of a - leading mailbox hierarchy delimiter also varies from server to - server, and even between different mailstores on the same server. In - some cases, a leading hierarchy delimiter means "discard the - - - -Leiba Informational [Page 18] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - - reference argument" (implementing the intended breakout facility), - thus: - - C: A001 LIST ABC/ /DEF - S: * LIST () "/" /DEF - S: A001 OK done - - In other cases, however, the two are catenated and the extra - hierarchy delimiter is discarded, thus: - - C: A001 LIST ABC/ /DEF - S: * LIST () "/" ABC/DEF - S: A001 OK done - - Client implementations must not assume that the server supports a - breakout facility, but may provide a way for the user to use one if - it is available. Any breakout facility should be exported to the - user interface. Note that there may be other "breakout" characters - besides the hierarchy delimiter (for instance, UNIX filesystem - servers are likely to use a leading "~" as well), and that their - interpretation is server-dependent. - -3.4.10. Mailbox Hierarchy Delimiters - - The server's selection of what to use as a mailbox hierarchy - delimiter is a difficult one, involving several issues: What - characters do users expect to see? What characters can they enter - for a hierarchy delimiter if it is desired (or required) that the - user enter it? What character can be used for the hierarchy - delimiter, noting that the chosen character can not otherwise be used - in the mailbox name? - - Because some interfaces show users the hierarchy delimiters or allow - users to enter qualified mailbox names containing them, server - implementations should use delimiter characters that users generally - expect to see as name separators. The most common characters used - for this are "/" (as in Unix file names), "\" (as in OS/2 and Windows - file names), and "." (as in news groups). There is little to choose - among these apart from what users may expect or what is dictated by - the underlying file system, if any. One consideration about using - "\" is that it's also a special character in the IMAP protocol. While - the use of other hierarchy delimiter characters is permissible, A - DESIGNER IS WELL ADVISED TO STAY WITH ONE FROM THIS SET unless the - server is intended for special purposes only. Implementers might be - thinking about using characters such as "-", "_", ";", "&", "#", "@", - and "!", but they should be aware of the surprise to the user as well - as of the effect on URLs and other external specifications (since - some of these characters have special meanings there). Also, a - - - -Leiba Informational [Page 19] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - - server that uses "\" (and clients of such a server) must remember to - escape that character in quoted strings or to send literals instead. - Literals are recommended over escaped characters in quoted strings in - order to maintain compatibility with older IMAP versions that did not - allow escaped characters in quoted strings (but check the grammar to - see where literals are allowed): - - C: 001 LIST "" {13} - S: + send literal - C: this\%\%\%\h* - S: * LIST () "\\" {27} - S: this\is\a\mailbox\hierarchy - S: 001 OK LIST complete - - In any case, a server should not use normal alpha-numeric characters - (such as "X" or "0") as delimiters; a user would be very surprised to - find that "EXPENDITURES" actually represented a two-level hierarchy. - And a server should not use characters that are non-printable or - difficult or impossible to enter on a standard US keyboard. Control - characters, box-drawing characters, and characters from non-US - alphabets fit into this category. Their use presents - interoperability problems that are best avoided. - - The UTF-7 encoding of mailbox names also raises questions about what - to do with the hierarchy delimiters in encoded names: do we encode - each hierarchy level and separate them with delimiters, or do we - encode the fully qualified name, delimiters and all? The answer for - IMAP is the former: encode each hierarchy level separately, and - insert delimiters between. This makes it particularly important not - to use as a hierarchy delimiter a character that might cause - confusion with IMAP's modified UTF-7 [UTF-7 and RFC-2060] encoding. - - To repeat: a server should use "/", "\", or "." as its hierarchy - delimiter. The use of any other character is likely to cause - problems and is STRONGLY DISCOURAGED. - -3.4.11. ALERT Response Codes - - The protocol spec is very clear on the matter of what to do with - ALERT response codes, and yet there are many clients that violate it - so it needs to be said anyway: "The human-readable text contains a - special alert that must be presented to the user in a fashion that - calls the user's attention to the message." That should be clear - enough, but I'll repeat it here: Clients must present ALERT text - clearly to the user. - - - - - - -Leiba Informational [Page 20] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - -3.4.12. Deleting Mailboxes - - The protocol does not guarantee that a client may delete a mailbox - that is not empty, though on some servers it is permissible and is, - in fact, much faster than the alternative or deleting all the - messages from the client. If the client chooses to try to take - advantage of this possibility it must be prepared to use the other - method in the even that the more convenient one fails. Further, a - client should not try to delete the mailbox that it has selected, but - should first close that mailbox; some servers do not permit the - deletion of the selected mailbox. - - That said, a server should permit the deletion of a non-empty - mailbox; there's little reason to pass this work on to the client. - Moreover, forbidding this prevents the deletion of a mailbox that for - some reason can not be opened or expunged, leading to possible - denial-of-service problems. - - Example: - - [User tells the client to delete mailbox BANANA, which is - currently selected...] - C: 008 CLOSE - S: 008 OK done - C: 009 DELETE BANANA - S: 009 NO Delete failed; mailbox is not empty. - C: 010 SELECT BANANA - S: * ... untagged SELECT responses - S: 010 OK done - C: 011 STORE 1:* +FLAGS.SILENT \DELETED - S: 011 OK done - C: 012 CLOSE - S: 012 OK done - C: 013 DELETE BANANA - S: 013 OK done - -3.5. A Word About Testing - - Since the whole point of IMAP is interoperability, and since - interoperability can not be tested in a vacuum, the final - recommendation of this treatise is, "Test against EVERYTHING." Test - your client against every server you can get an account on. Test - your server with every client you can get your hands on. Many - clients make limited test versions available on the Web for the - downloading. Many server owners will give serious client developers - guest accounts for testing. Contact them and ask. NEVER assume that - because your client works with one or two servers, or because your - server does fine with one or two clients, you will interoperate well - - - -Leiba Informational [Page 21] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - - in general. - - In particular, in addition to everything else, be sure to test - against the reference implementations: the PINE client, the - University of Washington server, and the Cyrus server. - - See the following URLs on the web for more information here: - - IMAP Products and Sources: http://www.imap.org/products.html - IMC MailConnect: http://www.imc.org/imc-mailconnect - -4. Security Considerations - - This document describes behaviour of clients and servers that use the - IMAP4 protocol, and as such, has the same security considerations as - described in [RFC-2060]. - -5. References - - [RFC-2060] Crispin, M., "Internet Message Access Protocol - Version - 4rev1", RFC 2060, December 1996. - - [RFC-2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [RFC-2180] Gahrns, M., "IMAP4 Multi-Accessed Mailbox Practice", RFC - 2180, July 1997. - - [UTF-8] Yergeau, F., " UTF-8, a transformation format of Unicode - and ISO 10646", RFC 2044, October 1996. - - [UTF-7] Goldsmith, D. and M. Davis, "UTF-7, a Mail-Safe - Transformation Format of Unicode", RFC 2152, May 1997. - - [NAMESPACE] Gahrns, M. and C. Newman, "IMAP4 Namespace", Work in - Progress. - -6. Author's Address - - Barry Leiba - IBM T.J. Watson Research Center - 30 Saw Mill River Road - Hawthorne, NY 10532 - - Phone: 1-914-784-7941 - EMail: leiba@watson.ibm.com - - - - - -Leiba Informational [Page 22] - -RFC 2683 IMAP4 Implementation Recommendations September 1999 - - -7. Full Copyright Statement - - Copyright (C) The Internet Society (1999). 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. - - - - - - - - - - - - - - - - - - - -Leiba Informational [Page 23] - diff --git a/imap/docs/rfc/rfc2971.txt b/imap/docs/rfc/rfc2971.txt deleted file mode 100644 index 9e7264dc..00000000 --- a/imap/docs/rfc/rfc2971.txt +++ /dev/null @@ -1,451 +0,0 @@ - - - - - - -Network Working Group T. Showalter -Request for Comments: 2971 Mirapoint, Inc. -Category: Standards Track October 2000 - - - IMAP4 ID extension - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2000). All Rights Reserved. - -Abstract - - The ID extension to the Internet Message Access Protocol - Version - 4rev1 (IMAP4rev1) protocol allows the server and client to exchange - identification information on their implementation in order to make - bug reports and usage statistics more complete. - -1. Introduction - - The IMAP4rev1 protocol described in [IMAP4rev1] provides a method for - accessing remote mail stores, but it provides no facility to - advertise what program a client or server uses to provide service. - This makes it difficult for implementors to get complete bug reports - from users, as it is frequently difficult to know what client or - server is in use. - - Additionally, some sites may wish to assemble usage statistics based - on what clients are used, but in an an environment where users are - permitted to obtain and maintain their own clients this is difficult - to accomplish. - - The ID command provides a facility to advertise information on what - programs are being used along with contact information (should bugs - ever occur). - - - - - - - - -Showalter Standards Track [Page 1] - -RFC 2971 IMAP4 ID extension October 2000 - - -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 [KEYWORDS]. - - The conventions used in this document are the same as specified in - [IMAP4rev1]. In examples, "C:" and "S:" indicate lines sent by the - client and server respectively. Line breaks have been inserted for - readability. - -3. Specification - - The sole purpose of the ID extension is to enable clients and servers - to exchange information on their implementations for the purposes of - statistical analysis and problem determination. - - This information is be submitted to a server by any client wishing to - provide information for statistical purposes, provided the server - advertises its willingness to take the information with the atom "ID" - included in the list of capabilities returned by the CAPABILITY - command. - - Implementations MUST NOT make operational changes based on the data - sent as part of the ID command or response. The ID command is for - human consumption only, and is not to be used in improving the - performance of clients or servers. - - This includes, but is not limited to, the following: - - Servers MUST NOT attempt to work around client bugs by using - information from the ID command. Clients MUST NOT attempt to work - around server bugs based on the ID response. - - Servers MUST NOT provide features to a client or otherwise - optimize for a particular client by using information from the ID - command. Clients MUST NOT provide features to a server or - otherwise optimize for a particular server based on the ID - response. - - Servers MUST NOT deny access to or refuse service for a client - based on information from the ID command. Clients MUST NOT refuse - to operate or limit their operation with a server based on the ID - response. - - - - - - - -Showalter Standards Track [Page 2] - -RFC 2971 IMAP4 ID extension October 2000 - - - Rationale: It is imperative that this extension not supplant IMAP's - CAPABILITY mechanism with a ad-hoc approach where implementations - guess each other's features based on who they claim to be. - - Implementations MUST NOT send false information in an ID command. - - Implementations MAY send less information than they have available or - no information at all. Such behavior may be useful to preserve user - privacy. See Security Considerations, section 7. - -3.1. ID Command - - Arguments: client parameter list or NIL - - Responses: OPTIONAL untagged response: ID - - Result: OK identification information accepted - BAD command unknown or arguments invalid - - Implementation identification information is sent by the client with - the ID command. - - This command is valid in any state. - - The information sent is in the form of a list of field/value pairs. - Fields are permitted to be any IMAP4 string, and values are permitted - to be any IMAP4 string or NIL. A value of NIL indicates that the - client can not or will not specify this information. The client may - also send NIL instead of the list, indicating that it wants to send - no information, but would still accept a server response. - - The available fields are defined in section 3.3. - - Example: C: a023 ID ("name" "sodr" "version" "19.34" "vendor" - "Pink Floyd Music Limited") - S: * ID NIL - S: a023 OK ID completed - -3.2. ID Response - - Contents: server parameter list - - In response to an ID command issued by the client, the server replies - with a tagged response containing information on its implementation. - The format is the same as the client list. - - - - - - -Showalter Standards Track [Page 3] - -RFC 2971 IMAP4 ID extension October 2000 - - - Example: C: a042 ID NIL - S: * ID ("name" "Cyrus" "version" "1.5" "os" "sunos" - "os-version" "5.5" "support-url" - "mailto:cyrus-bugs+@andrew.cmu.edu") - S: a042 OK ID command completed - - A server MUST send a tagged ID response to an ID command. However, a - server MAY send NIL in place of the list. - -3.3. Defined Field Values - - Any string may be sent as a field, but the following are defined to - describe certain values that might be sent. Implementations are free - to send none, any, or all of these. Strings are not case-sensitive. - Field strings MUST NOT be longer than 30 octets. Value strings MUST - NOT be longer than 1024 octets. Implementations MUST NOT send more - than 30 field-value pairs. - - name Name of the program - version Version number of the program - os Name of the operating system - os-version Version of the operating system - vendor Vendor of the client/server - support-url URL to contact for support - address Postal address of contact/vendor - date Date program was released, specified as a date-time - in IMAP4rev1 - command Command used to start the program - arguments Arguments supplied on the command line, if any - if any - environment Description of environment, i.e., UNIX environment - variables or Windows registry settings - - Implementations MUST NOT use contact information to submit automatic - bug reports. Implementations may include information from an ID - response in a report automatically prepared, but are prohibited from - sending the report without user authorization. - - It is preferable to find the name and version of the underlying - operating system at runtime in cases where this is possible. - - Information sent via an ID response may violate user privacy. See - Security Considerations, section 7. - - Implementations MUST NOT send the same field name more than once. - - - - - - -Showalter Standards Track [Page 4] - -RFC 2971 IMAP4 ID extension October 2000 - - -4. Formal Syntax - - This syntax is intended to augment the grammar specified in - [IMAP4rev1] in order to provide for the ID command. This - specification uses the augmented Backus-Naur Form (BNF) notation as - used in [IMAP4rev1]. - - command_any ::= "CAPABILITY" / "LOGOUT" / "NOOP" / x_command / id - ;; adds id command to command_any in [IMAP4rev1] - - id ::= "ID" SPACE id_params_list - - id_response ::= "ID" SPACE id_params_list - - id_params_list ::= "(" #(string SPACE nstring) ")" / nil - ;; list of field value pairs - - response_data ::= "*" SPACE (resp_cond_state / resp_cond_bye / - mailbox_data / message_data / capability_data / id_response) - -5. Use of the ID extension with Firewalls and Other Intermediaries - - There exist proxies, firewalls, and other intermediary systems that - can intercept an IMAP session and make changes to the data exchanged - in the session. Such intermediaries are not anticipated by the IMAP4 - protocol design and are not within the scope of the IMAP4 standard. - However, in order for the ID command to be useful in the presence of - such intermediaries, those intermediaries need to take special note - of the ID command and response. In particular, if an intermediary - changes any part of the IMAP session it must also change the ID - command to advertise its presence. - - A firewall MAY act to block transmission of specific information - fields in the ID command and response that it believes reveal - information that could expose a security vulnerability. However, a - firewall SHOULD NOT disable the extension, when present, entirely, - and SHOULD NOT unconditionally remove either the client or server - list. - - Finally, it should be noted that a firewall, when handling a - CAPABILITY response, MUST NOT allow the names of extensions to be - returned to the client that the firewall has no knowledge of. - - - - - - - - - -Showalter Standards Track [Page 5] - -RFC 2971 IMAP4 ID extension October 2000 - - -6. References - - [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", RFC 2119, March 1997. - - [IMAP4rev1] Crispin, M., "Internet Message Access Protocol - Version - 4rev1", RFC 2060, October 1996. - - [RFC-822] Crocker, D., "Standard for the Format of ARPA Internet - Text Messages", STD 11, RFC 822, August 1982. - -7. Security Considerations - - This extension has the danger of violating the privacy of users if - misused. Clients and servers should notify users that they implement - and enable the ID command. - - It is highly desirable that implementations provide a method of - disabling ID support, perhaps by not sending ID at all, or by sending - NIL as the argument to the ID command or response. - - Implementors must exercise extreme care in adding fields sent as part - of an ID command or response. Some fields, including a processor ID - number, Ethernet address, or other unique (or mostly unique) - identifier allow tracking of users in ways that violate user privacy - expectations. - - Having implementation information of a given client or server may - make it easier for an attacker to gain unauthorized access due to - security holes. - - Since this command includes arbitrary data and does not require the - user to authenticate, server implementations are cautioned to guard - against an attacker sending arbitrary garbage data in order to fill - up the ID log. In particular, if a server naively logs each ID - command to disk without inspecting it, an attacker can simply fire up - thousands of connections and send a few kilobytes of random data. - Servers have to guard against this. Methods include truncating - abnormally large responses; collating responses by storing only a - single copy, then keeping a counter of the number of times that - response has been seen; keeping only particularly interesting parts - of responses; and only logging responses of users who actually log - in. - - Security is affected by firewalls which modify the IMAP protocol - stream; see section 5, Use of the ID Extension with Firewalls and - Other Intermediaries, for more information. - - - - -Showalter Standards Track [Page 6] - -RFC 2971 IMAP4 ID extension October 2000 - - -8. Author's Address - - Tim Showalter - Mirapoint, Inc. - 909 Hermosa Ct. - Sunnyvale, CA 94095 - - EMail: tjs@mirapoint.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Showalter Standards Track [Page 7] - -RFC 2971 IMAP4 ID extension October 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. - - - - - - - - - - - - - - - - - - - -Showalter Standards Track [Page 8] - diff --git a/imap/docs/rfc/rfc3348.txt b/imap/docs/rfc/rfc3348.txt deleted file mode 100644 index 500871cc..00000000 --- a/imap/docs/rfc/rfc3348.txt +++ /dev/null @@ -1,339 +0,0 @@ - - - - - - -Network Working Group M. Gahrns -Request for Comments: 3348 R. Cheng -Category: Informational Microsoft - July 2002 - - - The Internet Message Action Protocol (IMAP4) - Child Mailbox Extension - -Status of this Memo - - This memo provides information for the Internet community. It does - not specify an Internet standard of any kind. Distribution of this - memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2002). All Rights Reserved. - -Abstract - - The Internet Message Action Protocol (IMAP4) CHILDREN extension - provides a mechanism for a client to efficiently determine if a - particular mailbox has children, without issuing a LIST "" * or a - LIST "" % for each mailbox. - -1. Conventions used in this document - - In examples, "C:" and "S:" indicate lines sent by the client and - server respectively. If such lines are wrapped without a new "C:" or - "S:" label, then the wrapping is for editorial clarity and is not - part of the command. - - 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]. - -2. Introduction and Overview - - Many IMAP4 [RFC-2060] clients present to the user a hierarchical view - of the mailboxes that a user has access to. Rather than initially - presenting to the user the entire mailbox hierarchy, it is often - preferable to show to the user a collapsed outline list of the - mailbox hierarchy (particularly if there is a large number of - mailboxes). The user can then expand the collapsed outline hierarchy - as needed. It is common to include within the collapsed hierarchy a - - - - - -Gahrns, et al. Informational [Page 1] - -RFC 3348 IMAP4 Child Mailbox Extension July 2002 - - - visual clue (such as a "+") to indicate that there are child - mailboxes under a particular mailbox. When the visual clue is - clicked the hierarchy list is expanded to show the child mailboxes. - - Several IMAP vendors implemented this proposal, and it is proposed to - document this behavior and functionality as an Informational RFC. - - There is interest in addressing the general extensibility of the IMAP - LIST command through an IMAP LIST Extension draft. Similar - functionality to the \HasChildren and \HasNoChildren flags could be - incorporated into this new LIST Extension. It is proposed that the - more general LIST Extension draft proceed on the standards track with - this proposal being relegated to informational status only. - - If the functionality of the \HasChildren and \HasNoChildren flags - were incorporated into a more general LIST extension, this would have - the advantage that a client could then have the opportunity to - request whether or not the server should return this information. - This would be an advantage over the current draft for servers where - this information is expensive to compute, since the server would only - need to compute the information when it knew that the client - requesting the information was able to consume it. - -3. Requirements - - IMAP4 servers that support this extension MUST list the keyword - CHILDREN in their CAPABILITY response. - - The CHILDREN extension defines two new attributes that MAY be - returned within a LIST response. - - \HasChildren - The presence of this attribute indicates that the - mailbox has child mailboxes. - - Servers SHOULD NOT return \HasChildren if child mailboxes exist, but - none will be displayed to the current user in a LIST response (as - should be the case where child mailboxes exist, but a client does not - have permissions to access them.) In this case, \HasNoChildren - SHOULD be used. - - In many cases, however, a server may not be able to efficiently - compute whether a user has access to all child mailboxes, or multiple - users may be accessing the same account and simultaneously changing - the mailbox hierarchy. As such a client MUST be prepared to accept - the \HasChildren attribute as a hint. That is, a mailbox MAY be - flagged with the \HasChildren attribute, but no child mailboxes will - appear in a subsequent LIST response. - - - - -Gahrns, et al. Informational [Page 2] - -RFC 3348 IMAP4 Child Mailbox Extension July 2002 - - - Example 3.1: - ============ - - /*** Consider a server that has the following mailbox hierarchy: - - INBOX - ITEM_1 - ITEM_1A - ITEM_2 - TOP_SECRET - - Where INBOX, ITEM_1 and ITEM_2 are top level mailboxes. ITEM_1A is a - child mailbox of ITEM_1 and TOP_SECRET is a child mailbox of ITEM_2 - that the currently logged on user does NOT have access to. - - Note that in this case, the server is not able to efficiently compute - access rights to child mailboxes and responds with a \HasChildren - attribute for mailbox ITEM_2, even though ITEM_2/TOP_SECRET does not - appear in the list response. ***/ - - C: A001 LIST "" * - S: * LIST (\HasNoChildren) "/" INBOX - S: * LIST (\HasChildren) "/" ITEM_1 - S: * LIST (\HasNoChildren) "/" ITEM_1/ITEM_1A - S: * LIST (\HasChildren) "/" ITEM_2 - S: A001 OK LIST Completed - - \HasNoChildren - The presence of this attribute indicates that the - mailbox has NO child mailboxes that are accessible to the currently - authenticated user. If a mailbox has the \Noinferiors attribute, the - \HasNoChildren attribute is redundant and SHOULD be omitted in the - LIST response. - - In some instances a server that supports the CHILDREN extension MAY - NOT be able to determine whether a mailbox has children. For example - it may have difficulty determining whether there are child mailboxes - when LISTing mailboxes while operating in a particular namespace. - - In these cases, a server MAY exclude both the \HasChildren and - \HasNoChildren attributes in the LIST response. As such, a client - can not make any assumptions about whether a mailbox has children - based upon the absence of a single attribute. - - It is an error for the server to return both a \HasChildren and a - \HasNoChildren attribute in a LIST response. - - - - - - -Gahrns, et al. Informational [Page 3] - -RFC 3348 IMAP4 Child Mailbox Extension July 2002 - - - It is an error for the server to return both a \HasChildren and a - \NoInferiors attribute in a LIST response. - - Note: the \HasNoChildren attribute should not be confused with the - IMAP4 [RFC-2060] defined attribute \Noinferiors which indicates that - no child mailboxes exist now and none can be created in the future. - - The \HasChildren and \HasNoChildren attributes might not be returned - in response to a LSUB response. Many servers maintain a simple - mailbox subscription list that is not updated when the underlying - mailbox structure is changed. A client MUST NOT assume that - hierarchy information will be maintained in the subscription list. - - RLIST is a command defined in [RFC-2193] that includes in a LIST - response mailboxes that are accessible only via referral. That is, a - client must explicitly issue an RLIST command to see a list of these - mailboxes. Thus in the case where a mailbox has child mailboxes that - are available only via referral, the mailboxes would appear as - \HasNoChildren in response to the LIST command, and \HasChildren in - response to the RLIST command. - -5. Formal Syntax - - The following syntax specification uses the augmented Backus-Naur - Form (BNF) as described in [ABNF]. - - Two new mailbox attributes are defined as flag_extensions to the - IMAP4 mailbox_list response: - - HasChildren = "\HasChildren" - - HasNoChildren = "\HasNoChildren" - -6. Security Considerations - - This extension provides a client a more efficient means of - determining whether a particular mailbox has children. If a mailbox - has children, but the currently authenticated user does not have - access to any of them, the server SHOULD respond with a - \HasNoChildren attribute. In many cases, however, a server may not - be able to efficiently compute whether a user has access to all child - mailboxes. If such a server responds with a \HasChildren attribute, - when in fact the currently authenticated user does not have access to - any child mailboxes, potentially more information is conveyed about - the mailbox than intended. A server designed with such levels of - security in mind SHOULD NOT attach the \HasChildren attribute to a - mailbox unless the server is certain that the user has access to at - least one of the child mailboxes. - - - -Gahrns, et al. Informational [Page 4] - -RFC 3348 IMAP4 Child Mailbox Extension July 2002 - - -7. References - - [RFC-2060] Crispin, M., "Internet Message Access Protocol - Version - 4rev1", RFC 2060, December 1996. - - [RFC-2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [RFC-2234] Crocker, D. and P. Overell, Editors, "Augmented BNF for - Syntax Specifications: ABNF", RFC 2234, November 1997. - - [RFC-2193] Gahrns, M., "IMAP4 Mailbox Referrals", RFC 2193, September - 1997. - -8. Acknowledgments - - The authors would like to thank the participants of several IMC Mail - Connect events for their input when this idea was originally - presented and refined. - -9. Author's Address - - Mike Gahrns - Microsoft - One Microsoft Way - Redmond, WA, 98052 - Phone: (425) 936-9833 - EMail: mikega@microsoft.com - - Raymond Cheng - Microsoft - One Microsoft Way - Redmond, WA, 98052 - Phone: (425) 703-4913 - EMail: raych@microsoft.com - - - - - - - - - - - - - - - - -Gahrns, et al. Informational [Page 5] - -RFC 3348 IMAP4 Child Mailbox Extension July 2002 - - -10. Full Copyright Statement - - Copyright (C) The Internet Society (2002). 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. - - - - - - - - - - - - - - - - - - - -Gahrns, et al. Informational [Page 6] - diff --git a/imap/docs/rfc/rfc3501.txt b/imap/docs/rfc/rfc3501.txt deleted file mode 100644 index 6f470dd1..00000000 --- a/imap/docs/rfc/rfc3501.txt +++ /dev/null @@ -1,6052 +0,0 @@ - - - - - - -Network Working Group M. Crispin -Request for Comments: 3501 University of Washington -Obsoletes: 2060 March 2003 -Category: Standards Track - - - INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1 - -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 (2003). All Rights Reserved. - -Abstract - - The Internet Message Access Protocol, Version 4rev1 (IMAP4rev1) - allows a client to access and manipulate electronic mail messages on - a server. IMAP4rev1 permits manipulation of mailboxes (remote - message folders) in a way that is functionally equivalent to local - folders. IMAP4rev1 also provides the capability for an offline - client to resynchronize with the server. - - IMAP4rev1 includes operations for creating, deleting, and renaming - mailboxes, checking for new messages, permanently removing messages, - setting and clearing flags, RFC 2822 and RFC 2045 parsing, searching, - and selective fetching of message attributes, texts, and portions - thereof. Messages in IMAP4rev1 are accessed by the use of numbers. - These numbers are either message sequence numbers or unique - identifiers. - - IMAP4rev1 supports a single server. A mechanism for accessing - configuration information to support multiple IMAP4rev1 servers is - discussed in RFC 2244. - - IMAP4rev1 does not specify a means of posting mail; this function is - handled by a mail transfer protocol such as RFC 2821. - - - - - - - - -Crispin Standards Track [Page 1] - -RFC 3501 IMAPv4 March 2003 - - -Table of Contents - - IMAP4rev1 Protocol Specification ................................ 4 - 1. How to Read This Document ............................... 4 - 1.1. Organization of This Document ........................... 4 - 1.2. Conventions Used in This Document ....................... 4 - 1.3. Special Notes to Implementors ........................... 5 - 2. Protocol Overview ....................................... 6 - 2.1. Link Level .............................................. 6 - 2.2. Commands and Responses .................................. 6 - 2.2.1. Client Protocol Sender and Server Protocol Receiver ..... 6 - 2.2.2. Server Protocol Sender and Client Protocol Receiver ..... 7 - 2.3. Message Attributes ...................................... 8 - 2.3.1. Message Numbers ......................................... 8 - 2.3.1.1. Unique Identifier (UID) Message Attribute ....... 8 - 2.3.1.2. Message Sequence Number Message Attribute ....... 10 - 2.3.2. Flags Message Attribute ................................. 11 - 2.3.3. Internal Date Message Attribute ......................... 12 - 2.3.4. [RFC-2822] Size Message Attribute ....................... 12 - 2.3.5. Envelope Structure Message Attribute .................... 12 - 2.3.6. Body Structure Message Attribute ........................ 12 - 2.4. Message Texts ........................................... 13 - 3. State and Flow Diagram .................................. 13 - 3.1. Not Authenticated State ................................. 13 - 3.2. Authenticated State ..................................... 13 - 3.3. Selected State .......................................... 13 - 3.4. Logout State ............................................ 14 - 4. Data Formats ............................................ 16 - 4.1. Atom .................................................... 16 - 4.2. Number .................................................. 16 - 4.3. String .................................................. 16 - 4.3.1. 8-bit and Binary Strings ................................ 17 - 4.4. Parenthesized List ...................................... 17 - 4.5. NIL ..................................................... 17 - 5. Operational Considerations .............................. 18 - 5.1. Mailbox Naming .......................................... 18 - 5.1.1. Mailbox Hierarchy Naming ................................ 19 - 5.1.2. Mailbox Namespace Naming Convention ..................... 19 - 5.1.3. Mailbox International Naming Convention ................. 19 - 5.2. Mailbox Size and Message Status Updates ................. 21 - 5.3. Response when no Command in Progress .................... 21 - 5.4. Autologout Timer ........................................ 22 - 5.5. Multiple Commands in Progress ........................... 22 - 6. Client Commands ........................................ 23 - 6.1. Client Commands - Any State ............................ 24 - 6.1.1. CAPABILITY Command ..................................... 24 - 6.1.2. NOOP Command ........................................... 25 - 6.1.3. LOGOUT Command ......................................... 26 - - - -Crispin Standards Track [Page 2] - -RFC 3501 IMAPv4 March 2003 - - - 6.2. Client Commands - Not Authenticated State .............. 26 - 6.2.1. STARTTLS Command ....................................... 27 - 6.2.2. AUTHENTICATE Command ................................... 28 - 6.2.3. LOGIN Command .......................................... 30 - 6.3. Client Commands - Authenticated State .................. 31 - 6.3.1. SELECT Command ......................................... 32 - 6.3.2. EXAMINE Command ........................................ 34 - 6.3.3. CREATE Command ......................................... 34 - 6.3.4. DELETE Command ......................................... 35 - 6.3.5. RENAME Command ......................................... 37 - 6.3.6. SUBSCRIBE Command ...................................... 39 - 6.3.7. UNSUBSCRIBE Command .................................... 39 - 6.3.8. LIST Command ........................................... 40 - 6.3.9. LSUB Command ........................................... 43 - 6.3.10. STATUS Command ......................................... 44 - 6.3.11. APPEND Command ......................................... 46 - 6.4. Client Commands - Selected State ....................... 47 - 6.4.1. CHECK Command .......................................... 47 - 6.4.2. CLOSE Command .......................................... 48 - 6.4.3. EXPUNGE Command ........................................ 49 - 6.4.4. SEARCH Command ......................................... 49 - 6.4.5. FETCH Command .......................................... 54 - 6.4.6. STORE Command .......................................... 58 - 6.4.7. COPY Command ........................................... 59 - 6.4.8. UID Command ............................................ 60 - 6.5. Client Commands - Experimental/Expansion ............... 62 - 6.5.1. X<atom> Command ........................................ 62 - 7. Server Responses ....................................... 62 - 7.1. Server Responses - Status Responses .................... 63 - 7.1.1. OK Response ............................................ 65 - 7.1.2. NO Response ............................................ 66 - 7.1.3. BAD Response ........................................... 66 - 7.1.4. PREAUTH Response ....................................... 67 - 7.1.5. BYE Response ........................................... 67 - 7.2. Server Responses - Server and Mailbox Status ........... 68 - 7.2.1. CAPABILITY Response .................................... 68 - 7.2.2. LIST Response .......................................... 69 - 7.2.3. LSUB Response .......................................... 70 - 7.2.4 STATUS Response ........................................ 70 - 7.2.5. SEARCH Response ........................................ 71 - 7.2.6. FLAGS Response ......................................... 71 - 7.3. Server Responses - Mailbox Size ........................ 71 - 7.3.1. EXISTS Response ........................................ 71 - 7.3.2. RECENT Response ........................................ 72 - 7.4. Server Responses - Message Status ...................... 72 - 7.4.1. EXPUNGE Response ....................................... 72 - 7.4.2. FETCH Response ......................................... 73 - 7.5. Server Responses - Command Continuation Request ........ 79 - - - -Crispin Standards Track [Page 3] - -RFC 3501 IMAPv4 March 2003 - - - 8. Sample IMAP4rev1 connection ............................ 80 - 9. Formal Syntax .......................................... 81 - 10. Author's Note .......................................... 92 - 11. Security Considerations ................................ 92 - 11.1. STARTTLS Security Considerations ....................... 92 - 11.2. Other Security Considerations .......................... 93 - 12. IANA Considerations .................................... 94 - Appendices ..................................................... 95 - A. References ............................................. 95 - B. Changes from RFC 2060 .................................. 97 - C. Key Word Index ......................................... 103 - Author's Address ............................................... 107 - Full Copyright Statement ....................................... 108 - -IMAP4rev1 Protocol Specification - -1. How to Read This Document - -1.1. Organization of This Document - - This document is written from the point of view of the implementor of - an IMAP4rev1 client or server. Beyond the protocol overview in - section 2, it is not optimized for someone trying to understand the - operation of the protocol. The material in sections 3 through 5 - provides the general context and definitions with which IMAP4rev1 - operates. - - Sections 6, 7, and 9 describe the IMAP commands, responses, and - syntax, respectively. The relationships among these are such that it - is almost impossible to understand any of them separately. In - particular, do not attempt to deduce command syntax from the command - section alone; instead refer to the Formal Syntax section. - -1.2. Conventions Used in This Document - - "Conventions" are basic principles or procedures. Document - conventions are noted in this section. - - 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", "MAY", and "OPTIONAL" in this document are to - be interpreted as described in [KEYWORDS]. - - The word "can" (not "may") is used to refer to a possible - circumstance or situation, as opposed to an optional facility of the - protocol. - - - -Crispin Standards Track [Page 4] - -RFC 3501 IMAPv4 March 2003 - - - "User" is used to refer to a human user, whereas "client" refers to - the software being run by the user. - - "Connection" refers to the entire sequence of client/server - interaction from the initial establishment of the network connection - until its termination. - - "Session" refers to the sequence of client/server interaction from - the time that a mailbox is selected (SELECT or EXAMINE command) until - the time that selection ends (SELECT or EXAMINE of another mailbox, - CLOSE command, or connection termination). - - Characters are 7-bit US-ASCII unless otherwise specified. Other - character sets are indicated using a "CHARSET", as described in - [MIME-IMT] and defined in [CHARSET]. CHARSETs have important - additional semantics in addition to defining character set; refer to - these documents for more detail. - - There are several protocol conventions in IMAP. These refer to - aspects of the specification which are not strictly part of the IMAP - protocol, but reflect generally-accepted practice. Implementations - need to be aware of these conventions, and avoid conflicts whether or - not they implement the convention. For example, "&" may not be used - as a hierarchy delimiter since it conflicts with the Mailbox - International Naming Convention, and other uses of "&" in mailbox - names are impacted as well. - -1.3. Special Notes to Implementors - - Implementors of the IMAP protocol are strongly encouraged to read the - IMAP implementation recommendations document [IMAP-IMPLEMENTATION] in - conjunction with this document, to help understand the intricacies of - this protocol and how best to build an interoperable product. - - IMAP4rev1 is designed to be upwards compatible from the [IMAP2] and - unpublished IMAP2bis protocols. IMAP4rev1 is largely compatible with - the IMAP4 protocol described in RFC 1730; the exception being in - certain facilities added in RFC 1730 that proved problematic and were - subsequently removed. In the course of the evolution of IMAP4rev1, - some aspects in the earlier protocols have become obsolete. Obsolete - commands, responses, and data formats which an IMAP4rev1 - implementation can encounter when used with an earlier implementation - are described in [IMAP-OBSOLETE]. - - Other compatibility issues with IMAP2bis, the most common variant of - the earlier protocol, are discussed in [IMAP-COMPAT]. A full - discussion of compatibility issues with rare (and presumed extinct) - - - - -Crispin Standards Track [Page 5] - -RFC 3501 IMAPv4 March 2003 - - - variants of [IMAP2] is in [IMAP-HISTORICAL]; this document is - primarily of historical interest. - - IMAP was originally developed for the older [RFC-822] standard, and - as a consequence several fetch items in IMAP incorporate "RFC822" in - their name. With the exception of RFC822.SIZE, there are more modern - replacements; for example, the modern version of RFC822.HEADER is - BODY.PEEK[HEADER]. In all cases, "RFC822" should be interpreted as a - reference to the updated [RFC-2822] standard. - -2. Protocol Overview - -2.1. Link Level - - The IMAP4rev1 protocol assumes a reliable data stream such as that - provided by TCP. When TCP is used, an IMAP4rev1 server listens on - port 143. - -2.2. Commands and Responses - - An IMAP4rev1 connection consists of the establishment of a - client/server network connection, an initial greeting from the - server, and client/server interactions. These client/server - interactions consist of a client command, server data, and a server - completion result response. - - All interactions transmitted by client and server are in the form of - lines, that is, strings that end with a CRLF. The protocol receiver - of an IMAP4rev1 client or server is either reading a line, or is - reading a sequence of octets with a known count followed by a line. - -2.2.1. Client Protocol Sender and Server Protocol Receiver - - The client command begins an operation. Each client command is - prefixed with an identifier (typically a short alphanumeric string, - e.g., A0001, A0002, etc.) called a "tag". A different tag is - generated by the client for each command. - - Clients MUST follow the syntax outlined in this specification - strictly. It is a syntax error to send a command with missing or - extraneous spaces or arguments. - - There are two cases in which a line from the client does not - represent a complete command. In one case, a command argument is - quoted with an octet count (see the description of literal in String - under Data Formats); in the other case, the command arguments require - server feedback (see the AUTHENTICATE command). In either case, the - - - - -Crispin Standards Track [Page 6] - -RFC 3501 IMAPv4 March 2003 - - - server sends a command continuation request response if it is ready - for the octets (if appropriate) and the remainder of the command. - This response is prefixed with the token "+". - - Note: If instead, the server detected an error in the - command, it sends a BAD completion response with a tag - matching the command (as described below) to reject the - command and prevent the client from sending any more of the - command. - - It is also possible for the server to send a completion - response for some other command (if multiple commands are - in progress), or untagged data. In either case, the - command continuation request is still pending; the client - takes the appropriate action for the response, and reads - another response from the server. In all cases, the client - MUST send a complete command (including receiving all - command continuation request responses and command - continuations for the command) before initiating a new - command. - - The protocol receiver of an IMAP4rev1 server reads a command line - from the client, parses the command and its arguments, and transmits - server data and a server command completion result response. - -2.2.2. Server Protocol Sender and Client Protocol Receiver - - Data transmitted by the server to the client and status responses - that do not indicate command completion are prefixed with the token - "*", and are called untagged responses. - - Server data MAY be sent as a result of a client command, or MAY be - sent unilaterally by the server. There is no syntactic difference - between server data that resulted from a specific command and server - data that were sent unilaterally. - - The server completion result response indicates the success or - failure of the operation. It is tagged with the same tag as the - client command which began the operation. Thus, if more than one - command is in progress, the tag in a server completion response - identifies the command to which the response applies. There are - three possible server completion responses: OK (indicating success), - NO (indicating failure), or BAD (indicating a protocol error such as - unrecognized command or command syntax error). - - Servers SHOULD enforce the syntax outlined in this specification - strictly. Any client command with a protocol syntax error, including - (but not limited to) missing or extraneous spaces or arguments, - - - -Crispin Standards Track [Page 7] - -RFC 3501 IMAPv4 March 2003 - - - SHOULD be rejected, and the client given a BAD server completion - response. - - The protocol receiver of an IMAP4rev1 client reads a response line - from the server. It then takes action on the response based upon the - first token of the response, which can be a tag, a "*", or a "+". - - A client MUST be prepared to accept any server response at all times. - This includes server data that was not requested. Server data SHOULD - be recorded, so that the client can reference its recorded copy - rather than sending a command to the server to request the data. In - the case of certain server data, the data MUST be recorded. - - This topic is discussed in greater detail in the Server Responses - section. - -2.3. Message Attributes - - In addition to message text, each message has several attributes - associated with it. These attributes can be retrieved individually - or in conjunction with other attributes or message texts. - -2.3.1. Message Numbers - - Messages in IMAP4rev1 are accessed by one of two numbers; the unique - identifier or the message sequence number. - - -2.3.1.1. Unique Identifier (UID) Message Attribute - - A 32-bit value assigned to each message, which when used with the - unique identifier validity value (see below) forms a 64-bit value - that MUST NOT refer to any other message in the mailbox or any - subsequent mailbox with the same name forever. Unique identifiers - are assigned in a strictly ascending fashion in the mailbox; as each - message is added to the mailbox it is assigned a higher UID than the - message(s) which were added previously. Unlike message sequence - numbers, unique identifiers are not necessarily contiguous. - - The unique identifier of a message MUST NOT change during the - session, and SHOULD NOT change between sessions. Any change of - unique identifiers between sessions MUST be detectable using the - UIDVALIDITY mechanism discussed below. Persistent unique identifiers - are required for a client to resynchronize its state from a previous - session with the server (e.g., disconnected or offline access - clients); this is discussed further in [IMAP-DISC]. - - - - - -Crispin Standards Track [Page 8] - -RFC 3501 IMAPv4 March 2003 - - - Associated with every mailbox are two values which aid in unique - identifier handling: the next unique identifier value and the unique - identifier validity value. - - The next unique identifier value is the predicted value that will be - assigned to a new message in the mailbox. Unless the unique - identifier validity also changes (see below), the next unique - identifier value MUST have the following two characteristics. First, - the next unique identifier value MUST NOT change unless new messages - are added to the mailbox; and second, the next unique identifier - value MUST change whenever new messages are added to the mailbox, - even if those new messages are subsequently expunged. - - Note: The next unique identifier value is intended to - provide a means for a client to determine whether any - messages have been delivered to the mailbox since the - previous time it checked this value. It is not intended to - provide any guarantee that any message will have this - unique identifier. A client can only assume, at the time - that it obtains the next unique identifier value, that - messages arriving after that time will have a UID greater - than or equal to that value. - - The unique identifier validity value is sent in a UIDVALIDITY - response code in an OK untagged response at mailbox selection time. - If unique identifiers from an earlier session fail to persist in this - session, the unique identifier validity value MUST be greater than - the one used in the earlier session. - - Note: Ideally, unique identifiers SHOULD persist at all - times. Although this specification recognizes that failure - to persist can be unavoidable in certain server - environments, it STRONGLY ENCOURAGES message store - implementation techniques that avoid this problem. For - example: - - 1) Unique identifiers MUST be strictly ascending in the - mailbox at all times. If the physical message store is - re-ordered by a non-IMAP agent, this requires that the - unique identifiers in the mailbox be regenerated, since - the former unique identifiers are no longer strictly - ascending as a result of the re-ordering. - - 2) If the message store has no mechanism to store unique - identifiers, it must regenerate unique identifiers at - each session, and each session must have a unique - UIDVALIDITY value. - - - - -Crispin Standards Track [Page 9] - -RFC 3501 IMAPv4 March 2003 - - - 3) If the mailbox is deleted and a new mailbox with the - same name is created at a later date, the server must - either keep track of unique identifiers from the - previous instance of the mailbox, or it must assign a - new UIDVALIDITY value to the new instance of the - mailbox. A good UIDVALIDITY value to use in this case - is a 32-bit representation of the creation date/time of - the mailbox. It is alright to use a constant such as - 1, but only if it guaranteed that unique identifiers - will never be reused, even in the case of a mailbox - being deleted (or renamed) and a new mailbox by the - same name created at some future time. - - 4) The combination of mailbox name, UIDVALIDITY, and UID - must refer to a single immutable message on that server - forever. In particular, the internal date, [RFC-2822] - size, envelope, body structure, and message texts - (RFC822, RFC822.HEADER, RFC822.TEXT, and all BODY[...] - fetch data items) must never change. This does not - include message numbers, nor does it include attributes - that can be set by a STORE command (e.g., FLAGS). - - -2.3.1.2. Message Sequence Number Message Attribute - - A relative position from 1 to the number of messages in the mailbox. - This position MUST be ordered by ascending unique identifier. As - each new message is added, it is assigned a message sequence number - that is 1 higher than the number of messages in the mailbox before - that new message was added. - - Message sequence numbers can be reassigned during the session. For - example, when a message is permanently removed (expunged) from the - mailbox, the message sequence number for all subsequent messages is - decremented. The number of messages in the mailbox is also - decremented. Similarly, a new message can be assigned a message - sequence number that was once held by some other message prior to an - expunge. - - In addition to accessing messages by relative position in the - mailbox, message sequence numbers can be used in mathematical - calculations. For example, if an untagged "11 EXISTS" is received, - and previously an untagged "8 EXISTS" was received, three new - messages have arrived with message sequence numbers of 9, 10, and 11. - Another example, if message 287 in a 523 message mailbox has UID - 12345, there are exactly 286 messages which have lesser UIDs and 236 - messages which have greater UIDs. - - - - -Crispin Standards Track [Page 10] - -RFC 3501 IMAPv4 March 2003 - - -2.3.2. Flags Message Attribute - - A list of zero or more named tokens associated with the message. A - flag is set by its addition to this list, and is cleared by its - removal. There are two types of flags in IMAP4rev1. A flag of - either type can be permanent or session-only. - - A system flag is a flag name that is pre-defined in this - specification. All system flags begin with "\". Certain system - flags (\Deleted and \Seen) have special semantics described - elsewhere. The currently-defined system flags are: - - \Seen - Message has been read - - \Answered - Message has been answered - - \Flagged - Message is "flagged" for urgent/special attention - - \Deleted - Message is "deleted" for removal by later EXPUNGE - - \Draft - Message has not completed composition (marked as a draft). - - \Recent - Message is "recently" arrived in this mailbox. This session - is the first session to have been notified about this - message; if the session is read-write, subsequent sessions - will not see \Recent set for this message. This flag can not - be altered by the client. - - If it is not possible to determine whether or not this - session is the first session to be notified about a message, - then that message SHOULD be considered recent. - - If multiple connections have the same mailbox selected - simultaneously, it is undefined which of these connections - will see newly-arrived messages with \Recent set and which - will see it without \Recent set. - - A keyword is defined by the server implementation. Keywords do not - begin with "\". Servers MAY permit the client to define new keywords - in the mailbox (see the description of the PERMANENTFLAGS response - code for more information). - - - - -Crispin Standards Track [Page 11] - -RFC 3501 IMAPv4 March 2003 - - - A flag can be permanent or session-only on a per-flag basis. - Permanent flags are those which the client can add or remove from the - message flags permanently; that is, concurrent and subsequent - sessions will see any change in permanent flags. Changes to session - flags are valid only in that session. - - Note: The \Recent system flag is a special case of a - session flag. \Recent can not be used as an argument in a - STORE or APPEND command, and thus can not be changed at - all. - -2.3.3. Internal Date Message Attribute - - The internal date and time of the message on the server. This - is not the date and time in the [RFC-2822] header, but rather a - date and time which reflects when the message was received. In - the case of messages delivered via [SMTP], this SHOULD be the - date and time of final delivery of the message as defined by - [SMTP]. In the case of messages delivered by the IMAP4rev1 COPY - command, this SHOULD be the internal date and time of the source - message. In the case of messages delivered by the IMAP4rev1 - APPEND command, this SHOULD be the date and time as specified in - the APPEND command description. All other cases are - implementation defined. - -2.3.4. [RFC-2822] Size Message Attribute - - The number of octets in the message, as expressed in [RFC-2822] - format. - -2.3.5. Envelope Structure Message Attribute - - A parsed representation of the [RFC-2822] header of the message. - Note that the IMAP Envelope structure is not the same as an - [SMTP] envelope. - -2.3.6. Body Structure Message Attribute - - A parsed representation of the [MIME-IMB] body structure - information of the message. - - - - - - - - - - - -Crispin Standards Track [Page 12] - -RFC 3501 IMAPv4 March 2003 - - -2.4. Message Texts - - In addition to being able to fetch the full [RFC-2822] text of a - message, IMAP4rev1 permits the fetching of portions of the full - message text. Specifically, it is possible to fetch the - [RFC-2822] message header, [RFC-2822] message body, a [MIME-IMB] - body part, or a [MIME-IMB] header. - -3. State and Flow Diagram - - Once the connection between client and server is established, an - IMAP4rev1 connection is in one of four states. The initial - state is identified in the server greeting. Most commands are - only valid in certain states. It is a protocol error for the - client to attempt a command while the connection is in an - inappropriate state, and the server will respond with a BAD or - NO (depending upon server implementation) command completion - result. - -3.1. Not Authenticated State - - In the not authenticated state, the client MUST supply - authentication credentials before most commands will be - permitted. This state is entered when a connection starts - unless the connection has been pre-authenticated. - -3.2. Authenticated State - - In the authenticated state, the client is authenticated and MUST - select a mailbox to access before commands that affect messages - will be permitted. This state is entered when a - pre-authenticated connection starts, when acceptable - authentication credentials have been provided, after an error in - selecting a mailbox, or after a successful CLOSE command. - -3.3. Selected State - - In a selected state, a mailbox has been selected to access. - This state is entered when a mailbox has been successfully - selected. - - - - - - - - - - - -Crispin Standards Track [Page 13] - -RFC 3501 IMAPv4 March 2003 - - -3.4. Logout State - - In the logout state, the connection is being terminated. This - state can be entered as a result of a client request (via the - LOGOUT command) or by unilateral action on the part of either - the client or server. - - If the client requests the logout state, the server MUST send an - untagged BYE response and a tagged OK response to the LOGOUT - command before the server closes the connection; and the client - MUST read the tagged OK response to the LOGOUT command before - the client closes the connection. - - A server MUST NOT unilaterally close the connection without - sending an untagged BYE response that contains the reason for - having done so. A client SHOULD NOT unilaterally close the - connection, and instead SHOULD issue a LOGOUT command. If the - server detects that the client has unilaterally closed the - connection, the server MAY omit the untagged BYE response and - simply close its connection. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Crispin Standards Track [Page 14] - -RFC 3501 IMAPv4 March 2003 - - - +----------------------+ - |connection established| - +----------------------+ - || - \/ - +--------------------------------------+ - | server greeting | - +--------------------------------------+ - || (1) || (2) || (3) - \/ || || - +-----------------+ || || - |Not Authenticated| || || - +-----------------+ || || - || (7) || (4) || || - || \/ \/ || - || +----------------+ || - || | Authenticated |<=++ || - || +----------------+ || || - || || (7) || (5) || (6) || - || || \/ || || - || || +--------+ || || - || || |Selected|==++ || - || || +--------+ || - || || || (7) || - \/ \/ \/ \/ - +--------------------------------------+ - | Logout | - +--------------------------------------+ - || - \/ - +-------------------------------+ - |both sides close the connection| - +-------------------------------+ - - (1) connection without pre-authentication (OK greeting) - (2) pre-authenticated connection (PREAUTH greeting) - (3) rejected connection (BYE greeting) - (4) successful LOGIN or AUTHENTICATE command - (5) successful SELECT or EXAMINE command - (6) CLOSE command, or failed SELECT or EXAMINE command - (7) LOGOUT command, server shutdown, or connection closed - - - - - - - - - - -Crispin Standards Track [Page 15] - -RFC 3501 IMAPv4 March 2003 - - -4. Data Formats - - IMAP4rev1 uses textual commands and responses. Data in - IMAP4rev1 can be in one of several forms: atom, number, string, - parenthesized list, or NIL. Note that a particular data item - may take more than one form; for example, a data item defined as - using "astring" syntax may be either an atom or a string. - -4.1. Atom - - An atom consists of one or more non-special characters. - -4.2. Number - - A number consists of one or more digit characters, and - represents a numeric value. - -4.3. String - - A string is in one of two forms: either literal or quoted - string. The literal form is the general form of string. The - quoted string form is an alternative that avoids the overhead of - processing a literal at the cost of limitations of characters - which may be used. - - 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, close brace ("}"), and CRLF. - In the case of literals transmitted from server to client, the - CRLF is immediately followed by the octet data. In the case of - literals transmitted from client to server, the client MUST wait - to receive a command continuation request (described later in - this document) before sending the octet data (and the remainder - of the command). - - A quoted string is a sequence of zero or more 7-bit characters, - excluding CR and LF, 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). - - Note: Even if the octet count is 0, a client transmitting a - literal MUST wait to receive a command continuation request. - - - - - - -Crispin Standards Track [Page 16] - -RFC 3501 IMAPv4 March 2003 - - -4.3.1. 8-bit and Binary Strings - - 8-bit textual and binary mail is supported through the use of a - [MIME-IMB] content transfer encoding. IMAP4rev1 implementations MAY - transmit 8-bit or multi-octet characters in literals, but SHOULD do - so only when the [CHARSET] is identified. - - Although a BINARY body encoding is defined, unencoded binary strings - are not permitted. A "binary string" is any string with NUL - characters. Implementations MUST encode binary data into a textual - form, such as BASE64, before transmitting the data. A string with an - excessive amount of CTL characters MAY also be considered to be - binary. - -4.4. Parenthesized List - - Data structures are represented as a "parenthesized list"; a sequence - of data items, delimited by space, and bounded at each end by - parentheses. A parenthesized list can contain other parenthesized - lists, using multiple levels of parentheses to indicate nesting. - - The empty list is represented as () -- a parenthesized list with no - members. - -4.5. NIL - - The special form "NIL" represents the non-existence of a particular - data item that is represented as a string or parenthesized list, as - distinct from the empty string "" or the empty parenthesized list (). - - Note: NIL is never used for any data item which takes the - form of an atom. For example, a mailbox name of "NIL" is a - mailbox named NIL as opposed to a non-existent mailbox - name. This is because mailbox uses "astring" syntax which - is an atom or a string. Conversely, an addr-name of NIL is - a non-existent personal name, because addr-name uses - "nstring" syntax which is NIL or a string, but never an - atom. - - - - - - - - - - - - - -Crispin Standards Track [Page 17] - -RFC 3501 IMAPv4 March 2003 - - -5. Operational Considerations - - The following rules are listed here to ensure that all IMAP4rev1 - implementations interoperate properly. - -5.1. Mailbox Naming - - Mailbox names are 7-bit. Client implementations MUST NOT attempt to - create 8-bit mailbox names, and SHOULD interpret any 8-bit mailbox - names returned by LIST or LSUB as UTF-8. Server implementations - SHOULD prohibit the creation of 8-bit mailbox names, and SHOULD NOT - return 8-bit mailbox names in LIST or LSUB. See section 5.1.3 for - more information on how to represent non-ASCII mailbox names. - - Note: 8-bit mailbox names were undefined in earlier - versions of this protocol. Some sites used a local 8-bit - character set to represent non-ASCII mailbox names. Such - usage is not interoperable, and is now formally deprecated. - - The case-insensitive mailbox name INBOX is a special name reserved to - mean "the primary mailbox for this user on this server". The - interpretation of all other names is implementation-dependent. - - In particular, this specification takes no position on case - sensitivity in non-INBOX mailbox names. Some server implementations - are fully case-sensitive; others preserve case of a newly-created - name but otherwise are case-insensitive; and yet others coerce names - to a particular case. Client implementations MUST interact with any - of these. If a server implementation interprets non-INBOX mailbox - names as case-insensitive, it MUST treat names using the - international naming convention specially as described in section - 5.1.3. - - There are certain client considerations when creating a new mailbox - name: - - 1) Any character which is one of the atom-specials (see the Formal - Syntax) will require that the mailbox name be represented as a - quoted string or literal. - - 2) CTL and other non-graphic characters are difficult to represent - in a user interface and are best avoided. - - 3) Although the list-wildcard characters ("%" and "*") are valid - in a mailbox name, it is difficult to use such mailbox names - with the LIST and LSUB commands due to the conflict with - wildcard interpretation. - - - - -Crispin Standards Track [Page 18] - -RFC 3501 IMAPv4 March 2003 - - - 4) Usually, a character (determined by the server implementation) - is reserved to delimit levels of hierarchy. - - 5) Two characters, "#" and "&", have meanings by convention, and - should be avoided except when used in that convention. - -5.1.1. Mailbox Hierarchy Naming - - If it is desired to export hierarchical mailbox names, mailbox names - MUST be left-to-right hierarchical using a single character to - separate levels of hierarchy. The same hierarchy separator character - is used for all levels of hierarchy within a single name. - -5.1.2. Mailbox Namespace Naming Convention - - By convention, the first hierarchical element of any mailbox name - which begins with "#" identifies the "namespace" of the remainder of - the name. This makes it possible to disambiguate between different - types of mailbox stores, each of which have their own namespaces. - - For example, implementations which offer access to USENET - newsgroups MAY use the "#news" namespace to partition the - USENET newsgroup namespace from that of other mailboxes. - Thus, the comp.mail.misc newsgroup would have a mailbox - name of "#news.comp.mail.misc", and the name - "comp.mail.misc" can refer to a different object (e.g., a - user's private mailbox). - -5.1.3. Mailbox International Naming Convention - - By convention, international mailbox names in IMAP4rev1 are specified - using a modified version of the UTF-7 encoding described in [UTF-7]. - Modified UTF-7 may also be usable in servers that implement an - earlier version of this protocol. - - In modified UTF-7, printable US-ASCII characters, except for "&", - represent themselves; that is, characters with octet values 0x20-0x25 - and 0x27-0x7e. The character "&" (0x26) is represented by the - two-octet sequence "&-". - - All other characters (octet values 0x00-0x1f and 0x7f-0xff) are - represented in modified BASE64, with a further modification from - [UTF-7] that "," is used instead of "/". Modified BASE64 MUST NOT be - used to represent any printing US-ASCII character which can represent - itself. - - - - - - -Crispin Standards Track [Page 19] - -RFC 3501 IMAPv4 March 2003 - - - "&" is used to shift to modified BASE64 and "-" to shift back to - US-ASCII. There is no implicit shift from BASE64 to US-ASCII, and - null shifts ("-&" while in BASE64; note that "&-" while in US-ASCII - means "&") are not permitted. However, all names start in US-ASCII, - and MUST end in US-ASCII; that is, a name that ends with a non-ASCII - ISO-10646 character MUST end with a "-"). - - The purpose of these modifications is to correct the following - problems with UTF-7: - - 1) UTF-7 uses the "+" character for shifting; this conflicts with - the common use of "+" in mailbox names, in particular USENET - newsgroup names. - - 2) UTF-7's encoding is BASE64 which uses the "/" character; this - conflicts with the use of "/" as a popular hierarchy delimiter. - - 3) UTF-7 prohibits the unencoded usage of "\"; this conflicts with - the use of "\" as a popular hierarchy delimiter. - - 4) UTF-7 prohibits the unencoded usage of "~"; this conflicts with - the use of "~" in some servers as a home directory indicator. - - 5) UTF-7 permits multiple alternate forms to represent the same - string; in particular, printable US-ASCII characters can be - represented in encoded form. - - Although modified UTF-7 is a convention, it establishes certain - requirements on server handling of any mailbox name with an - embedded "&" character. In particular, server implementations - MUST preserve the exact form of the modified BASE64 portion of a - modified UTF-7 name and treat that text as case-sensitive, even if - names are otherwise case-insensitive or case-folded. - - Server implementations SHOULD verify that any mailbox name with an - embedded "&" character, used as an argument to CREATE, is: in the - correctly modified UTF-7 syntax, has no superfluous shifts, and - has no encoding in modified BASE64 of any printing US-ASCII - character which can represent itself. However, client - implementations MUST NOT depend upon the server doing this, and - SHOULD NOT attempt to create a mailbox name with an embedded "&" - character unless it complies with the modified UTF-7 syntax. - - Server implementations which export a mail store that does not - follow the modified UTF-7 convention MUST convert to modified - UTF-7 any mailbox name that contains either non-ASCII characters - or the "&" character. - - - - -Crispin Standards Track [Page 20] - -RFC 3501 IMAPv4 March 2003 - - - For example, here is a mailbox name which mixes English, - Chinese, and Japanese text: - ~peter/mail/&U,BTFw-/&ZeVnLIqe- - - For example, the string "&Jjo!" is not a valid mailbox - name because it does not contain a shift to US-ASCII - before the "!". The correct form is "&Jjo-!". The - string "&U,BTFw-&ZeVnLIqe-" is not permitted because it - contains a superfluous shift. The correct form is - "&U,BTF2XlZyyKng-". - -5.2. Mailbox Size and Message Status Updates - - At any time, a server can send data that the client did not request. - Sometimes, such behavior is REQUIRED. For example, agents other than - the server MAY add messages to the mailbox (e.g., new message - delivery), change the flags of the messages in the mailbox (e.g., - simultaneous access to the same mailbox by multiple agents), or even - remove messages from the mailbox. A server MUST send mailbox size - updates automatically if a mailbox size change is observed during the - processing of a command. A server SHOULD send message flag updates - automatically, without requiring the client to request such updates - explicitly. - - Special rules exist for server notification of a client about the - removal of messages to prevent synchronization errors; see the - description of the EXPUNGE response for more detail. In particular, - it is NOT permitted to send an EXISTS response that would reduce the - number of messages in the mailbox; only the EXPUNGE response can do - this. - - Regardless of what implementation decisions a client makes on - remembering data from the server, a client implementation MUST record - mailbox size updates. It MUST NOT assume that any command after the - initial mailbox selection will return the size of the mailbox. - -5.3. Response when no Command in Progress - - Server implementations are permitted to send an untagged response - (except for EXPUNGE) while there is no command in progress. Server - implementations that send such responses MUST deal with flow control - considerations. Specifically, they MUST either (1) verify that the - size of the data does not exceed the underlying transport's available - window size, or (2) use non-blocking writes. - - - - - - - -Crispin Standards Track [Page 21] - -RFC 3501 IMAPv4 March 2003 - - -5.4. Autologout Timer - - If a server has an inactivity autologout timer, the duration of that - timer MUST be at least 30 minutes. The receipt of ANY command from - the client during that interval SHOULD suffice to reset the - autologout timer. - -5.5. Multiple Commands in Progress - - The client MAY send another command without waiting for the - completion result response of a command, subject to ambiguity rules - (see below) and flow control constraints on the underlying data - stream. Similarly, a server MAY begin processing another command - before processing the current command to completion, subject to - ambiguity rules. However, any command continuation request responses - and command continuations MUST be negotiated before any subsequent - command is initiated. - - The exception is if an ambiguity would result because of a command - that would affect the results of other commands. Clients MUST NOT - send multiple commands without waiting if an ambiguity would result. - If the server detects a possible ambiguity, it MUST execute commands - to completion in the order given by the client. - - The most obvious example of ambiguity is when a command would affect - the results of another command, e.g., a FETCH of a message's flags - and a STORE of that same message's flags. - - A non-obvious ambiguity occurs with commands that permit an untagged - EXPUNGE response (commands other than FETCH, STORE, and SEARCH), - since an untagged EXPUNGE response can invalidate sequence numbers in - a subsequent command. This is not a problem for FETCH, STORE, or - SEARCH commands because servers are prohibited from sending EXPUNGE - responses while any of those commands are in progress. Therefore, if - the client sends any command other than FETCH, STORE, or SEARCH, it - MUST wait for the completion result response before sending a command - with message sequence numbers. - - Note: UID FETCH, UID STORE, and UID SEARCH are different - commands from FETCH, STORE, and SEARCH. If the client - sends a UID command, it must wait for a completion result - response before sending a command with message sequence - numbers. - - - - - - - - -Crispin Standards Track [Page 22] - -RFC 3501 IMAPv4 March 2003 - - - For example, the following non-waiting command sequences are invalid: - - FETCH + NOOP + STORE - STORE + COPY + FETCH - COPY + COPY - CHECK + FETCH - - The following are examples of valid non-waiting command sequences: - - FETCH + STORE + SEARCH + CHECK - STORE + COPY + EXPUNGE - - UID SEARCH + UID SEARCH may be valid or invalid as a non-waiting - command sequence, depending upon whether or not the second UID - SEARCH contains message sequence numbers. - -6. Client Commands - - IMAP4rev1 commands are described in this section. Commands are - organized by the state in which the command is permitted. Commands - which are permitted in multiple states are listed in the minimum - permitted state (for example, commands valid in authenticated and - selected state are listed in the authenticated state commands). - - Command arguments, identified by "Arguments:" in the command - descriptions below, are described by function, not by syntax. The - precise syntax of command arguments is described in the Formal Syntax - section. - - Some commands cause specific server responses to be returned; these - are identified by "Responses:" in the command descriptions below. - See the response descriptions in the Responses section for - information on these responses, and the Formal Syntax section for the - precise syntax of these responses. It is possible for server data to - be transmitted as a result of any command. Thus, commands that do - not specifically require server data specify "no specific responses - for this command" instead of "none". - - The "Result:" in the command description refers to the possible - tagged status responses to a command, and any special interpretation - of these status responses. - - The state of a connection is only changed by successful commands - which are documented as changing state. A rejected command (BAD - response) never changes the state of the connection or of the - selected mailbox. A failed command (NO response) generally does not - change the state of the connection or of the selected mailbox; the - exception being the SELECT and EXAMINE commands. - - - -Crispin Standards Track [Page 23] - -RFC 3501 IMAPv4 March 2003 - - -6.1. Client Commands - Any State - - The following commands are valid in any state: CAPABILITY, NOOP, and - LOGOUT. - -6.1.1. CAPABILITY Command - - Arguments: none - - Responses: REQUIRED untagged response: CAPABILITY - - Result: OK - capability completed - BAD - command unknown or arguments invalid - - The CAPABILITY command requests a listing of capabilities that the - server supports. The server MUST send a single untagged - CAPABILITY response with "IMAP4rev1" as one of the listed - capabilities before the (tagged) OK response. - - A capability name which begins with "AUTH=" indicates that the - server supports that particular authentication mechanism. All - such names are, by definition, part of this specification. For - example, the authorization capability for an experimental - "blurdybloop" authenticator would be "AUTH=XBLURDYBLOOP" and not - "XAUTH=BLURDYBLOOP" or "XAUTH=XBLURDYBLOOP". - - Other capability names refer to extensions, revisions, or - amendments to this specification. See the documentation of the - CAPABILITY response for additional information. No capabilities, - beyond the base IMAP4rev1 set defined in this specification, are - enabled without explicit client action to invoke the capability. - - Client and server implementations MUST implement the STARTTLS, - LOGINDISABLED, and AUTH=PLAIN (described in [IMAP-TLS]) - capabilities. See the Security Considerations section for - important information. - - See the section entitled "Client Commands - - Experimental/Expansion" for information about the form of site or - implementation-specific capabilities. - - - - - - - - - - - -Crispin Standards Track [Page 24] - -RFC 3501 IMAPv4 March 2003 - - - Example: C: abcd CAPABILITY - S: * CAPABILITY IMAP4rev1 STARTTLS AUTH=GSSAPI - LOGINDISABLED - S: abcd OK CAPABILITY completed - C: efgh STARTTLS - S: efgh OK STARTLS completed - <TLS negotiation, further commands are under [TLS] layer> - C: ijkl CAPABILITY - S: * CAPABILITY IMAP4rev1 AUTH=GSSAPI AUTH=PLAIN - S: ijkl OK CAPABILITY completed - - -6.1.2. NOOP Command - - Arguments: none - - Responses: no specific responses for this command (but see below) - - Result: OK - noop completed - BAD - command unknown or arguments invalid - - The NOOP command always succeeds. It does nothing. - - Since any command can return a status update as untagged data, the - NOOP command can be used as a periodic poll for new messages or - message status updates during a period of inactivity (this is the - preferred method to do this). The NOOP command can also be used - to reset any inactivity autologout timer on the server. - - Example: C: a002 NOOP - S: a002 OK NOOP completed - . . . - C: a047 NOOP - S: * 22 EXPUNGE - S: * 23 EXISTS - S: * 3 RECENT - S: * 14 FETCH (FLAGS (\Seen \Deleted)) - S: a047 OK NOOP completed - - - - - - - - - - - - - -Crispin Standards Track [Page 25] - -RFC 3501 IMAPv4 March 2003 - - -6.1.3. LOGOUT Command - - Arguments: none - - Responses: REQUIRED untagged response: BYE - - Result: OK - logout completed - BAD - command unknown or arguments invalid - - The LOGOUT command informs the server that the client is done with - the connection. The server MUST send a BYE untagged response - before the (tagged) OK response, and then close the network - connection. - - Example: C: A023 LOGOUT - S: * BYE IMAP4rev1 Server logging out - S: A023 OK LOGOUT completed - (Server and client then close the connection) - -6.2. Client Commands - Not Authenticated State - - In the not authenticated state, the AUTHENTICATE or LOGIN command - establishes authentication and enters the authenticated state. The - AUTHENTICATE command provides a general mechanism for a variety of - authentication techniques, privacy protection, and integrity - checking; whereas the LOGIN command uses a traditional user name and - plaintext password pair and has no means of establishing privacy - protection or integrity checking. - - The STARTTLS command is an alternate form of establishing session - privacy protection and integrity checking, but does not establish - authentication or enter the authenticated state. - - Server implementations MAY allow access to certain mailboxes without - establishing authentication. This can be done by means of the - ANONYMOUS [SASL] authenticator described in [ANONYMOUS]. An older - convention is a LOGIN command using the userid "anonymous"; in this - case, a password is required although the server may choose to accept - any password. The restrictions placed on anonymous users are - implementation-dependent. - - Once authenticated (including as anonymous), it is not possible to - re-enter not authenticated state. - - - - - - - - -Crispin Standards Track [Page 26] - -RFC 3501 IMAPv4 March 2003 - - - In addition to the universal commands (CAPABILITY, NOOP, and LOGOUT), - the following commands are valid in the not authenticated state: - STARTTLS, AUTHENTICATE and LOGIN. See the Security Considerations - section for important information about these commands. - -6.2.1. STARTTLS Command - - Arguments: none - - Responses: no specific response for this command - - Result: OK - starttls completed, begin TLS negotiation - BAD - command unknown or arguments invalid - - A [TLS] negotiation begins immediately after the CRLF at the end - of the tagged OK response from the server. Once 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 server remains in the non-authenticated state, even if client - credentials are supplied during the [TLS] negotiation. This does - not preclude an authentication mechanism such as EXTERNAL (defined - in [SASL]) from using client identity determined by the [TLS] - negotiation. - - Once [TLS] has been started, the client MUST discard cached - information about server capabilities and SHOULD re-issue the - CAPABILITY command. This is necessary to protect against man-in- - the-middle attacks which alter the capabilities list prior to - STARTTLS. The server MAY advertise different capabilities after - STARTTLS. - - Example: C: a001 CAPABILITY - S: * CAPABILITY IMAP4rev1 STARTTLS LOGINDISABLED - S: a001 OK CAPABILITY completed - C: a002 STARTTLS - S: a002 OK Begin TLS negotiation now - <TLS negotiation, further commands are under [TLS] layer> - C: a003 CAPABILITY - S: * CAPABILITY IMAP4rev1 AUTH=PLAIN - S: a003 OK CAPABILITY completed - C: a004 LOGIN joe password - S: a004 OK LOGIN completed - - - - - - - - -Crispin Standards Track [Page 27] - -RFC 3501 IMAPv4 March 2003 - - -6.2.2. AUTHENTICATE Command - - Arguments: authentication mechanism name - - Responses: continuation data can be requested - - Result: OK - authenticate completed, now in authenticated state - NO - authenticate failure: unsupported authentication - mechanism, credentials rejected - BAD - command unknown or arguments invalid, - authentication exchange cancelled - - The AUTHENTICATE command indicates a [SASL] authentication - mechanism to the server. If the server supports the requested - authentication mechanism, it performs an authentication protocol - exchange to authenticate and identify the client. It MAY also - negotiate an OPTIONAL security layer for subsequent protocol - interactions. If the requested authentication mechanism is not - supported, the server SHOULD reject the AUTHENTICATE command by - sending a tagged NO response. - - The AUTHENTICATE command does not support the optional "initial - response" feature of [SASL]. Section 5.1 of [SASL] specifies how - to handle an authentication mechanism which uses an initial - response. - - The service name specified by this protocol's profile of [SASL] is - "imap". - - The authentication protocol exchange consists of a series of - server challenges and client responses that are specific to the - authentication mechanism. A server challenge consists of a - command continuation request response with the "+" token followed - by a BASE64 encoded string. The client response consists of a - single line consisting of a BASE64 encoded string. If the client - wishes to cancel an authentication exchange, it issues a line - consisting of a single "*". If the server receives such a - response, it MUST reject the AUTHENTICATE command by sending a - tagged BAD response. - - If a security layer is negotiated through the [SASL] - authentication exchange, it takes effect immediately following the - CRLF that concludes the authentication exchange for the client, - and the CRLF of the tagged OK response for the server. - - While client and server implementations MUST implement the - AUTHENTICATE command itself, it is not required to implement any - authentication mechanisms other than the PLAIN mechanism described - - - -Crispin Standards Track [Page 28] - -RFC 3501 IMAPv4 March 2003 - - - in [IMAP-TLS]. Also, an authentication mechanism is not required - to support any security layers. - - Note: a server implementation MUST implement a - configuration in which it does NOT permit any plaintext - password mechanisms, unless either the STARTTLS command - has been negotiated or some other mechanism that - protects the session from password snooping has been - provided. Server sites SHOULD NOT use any configuration - which permits a plaintext password mechanism without - such a protection mechanism against password snooping. - Client and server implementations SHOULD implement - additional [SASL] mechanisms that do not use plaintext - passwords, such the GSSAPI mechanism described in [SASL] - and/or the [DIGEST-MD5] mechanism. - - Servers and clients can support multiple authentication - mechanisms. The server SHOULD list its supported authentication - mechanisms in the response to the CAPABILITY command so that the - client knows which authentication mechanisms to use. - - A server MAY include a CAPABILITY response code in the tagged OK - response of a successful AUTHENTICATE command in order to send - capabilities automatically. It is unnecessary for a client to - send a separate CAPABILITY command if it recognizes these - automatic capabilities. This should only be done if a security - layer was not negotiated by the AUTHENTICATE command, because the - tagged OK response as part of an AUTHENTICATE command is not - protected by encryption/integrity checking. [SASL] requires the - client to re-issue a CAPABILITY command in this case. - - If an AUTHENTICATE command fails with a NO response, the client - MAY try another authentication mechanism by issuing another - AUTHENTICATE command. It MAY also attempt to authenticate by - using the LOGIN command (see section 6.2.3 for more detail). In - other words, the client MAY request authentication types in - decreasing order of preference, with the LOGIN command as a last - resort. - - The authorization identity passed from the client to the server - during the authentication exchange is interpreted by the server as - the user name whose privileges the client is requesting. - - - - - - - - - -Crispin Standards Track [Page 29] - -RFC 3501 IMAPv4 March 2003 - - - Example: S: * OK IMAP4rev1 Server - C: A001 AUTHENTICATE GSSAPI - S: + - C: YIIB+wYJKoZIhvcSAQICAQBuggHqMIIB5qADAgEFoQMCAQ6iBw - MFACAAAACjggEmYYIBIjCCAR6gAwIBBaESGxB1Lndhc2hpbmd0 - b24uZWR1oi0wK6ADAgEDoSQwIhsEaW1hcBsac2hpdmFtcy5jYW - Mud2FzaGluZ3Rvbi5lZHWjgdMwgdCgAwIBAaEDAgEDooHDBIHA - cS1GSa5b+fXnPZNmXB9SjL8Ollj2SKyb+3S0iXMljen/jNkpJX - AleKTz6BQPzj8duz8EtoOuNfKgweViyn/9B9bccy1uuAE2HI0y - C/PHXNNU9ZrBziJ8Lm0tTNc98kUpjXnHZhsMcz5Mx2GR6dGknb - I0iaGcRerMUsWOuBmKKKRmVMMdR9T3EZdpqsBd7jZCNMWotjhi - vd5zovQlFqQ2Wjc2+y46vKP/iXxWIuQJuDiisyXF0Y8+5GTpAL - pHDc1/pIGmMIGjoAMCAQGigZsEgZg2on5mSuxoDHEA1w9bcW9n - FdFxDKpdrQhVGVRDIzcCMCTzvUboqb5KjY1NJKJsfjRQiBYBdE - NKfzK+g5DlV8nrw81uOcP8NOQCLR5XkoMHC0Dr/80ziQzbNqhx - O6652Npft0LQwJvenwDI13YxpwOdMXzkWZN/XrEqOWp6GCgXTB - vCyLWLlWnbaUkZdEYbKHBPjd8t/1x5Yg== - S: + YGgGCSqGSIb3EgECAgIAb1kwV6ADAgEFoQMCAQ+iSzBJoAMC - AQGiQgRAtHTEuOP2BXb9sBYFR4SJlDZxmg39IxmRBOhXRKdDA0 - uHTCOT9Bq3OsUTXUlk0CsFLoa8j+gvGDlgHuqzWHPSQg== - C: - S: + YDMGCSqGSIb3EgECAgIBAAD/////6jcyG4GE3KkTzBeBiVHe - ceP2CWY0SR0fAQAgAAQEBAQ= - C: YDMGCSqGSIb3EgECAgIBAAD/////3LQBHXTpFfZgrejpLlLImP - wkhbfa2QteAQAgAG1yYwE= - S: A001 OK GSSAPI authentication successful - - Note: The line breaks within server challenges and client - responses are for editorial clarity and are not in real - authenticators. - - -6.2.3. LOGIN Command - - Arguments: user name - password - - Responses: no specific responses for this command - - Result: OK - login completed, now in authenticated state - NO - login failure: user name or password rejected - BAD - command unknown or arguments invalid - - The LOGIN command identifies the client to the server and carries - the plaintext password authenticating this user. - - - - - - -Crispin Standards Track [Page 30] - -RFC 3501 IMAPv4 March 2003 - - - A server MAY include a CAPABILITY response code in the tagged OK - response to a successful LOGIN command in order to send - capabilities automatically. It is unnecessary for a client to - send a separate CAPABILITY command if it recognizes these - automatic capabilities. - - Example: C: a001 LOGIN SMITH SESAME - S: a001 OK LOGIN completed - - Note: Use of the LOGIN command over an insecure network - (such as the Internet) is a security risk, because anyone - monitoring network traffic can obtain plaintext passwords. - The LOGIN command SHOULD NOT be used except as a last - resort, and it is recommended that client implementations - have a means to disable any automatic use of the LOGIN - command. - - Unless either the STARTTLS command has been negotiated or - some other mechanism that protects the session from - password snooping has been provided, a server - implementation MUST implement a configuration in which it - advertises the LOGINDISABLED capability and does NOT permit - the LOGIN command. Server sites SHOULD NOT use any - configuration which permits the LOGIN command without such - a protection mechanism against password snooping. A client - implementation MUST NOT send a LOGIN command if the - LOGINDISABLED capability is advertised. - -6.3. Client Commands - Authenticated State - - In the authenticated state, commands that manipulate mailboxes as - atomic entities are permitted. Of these commands, the SELECT and - EXAMINE commands will select a mailbox for access and enter the - selected state. - - In addition to the universal commands (CAPABILITY, NOOP, and LOGOUT), - the following commands are valid in the authenticated state: SELECT, - EXAMINE, CREATE, DELETE, RENAME, SUBSCRIBE, UNSUBSCRIBE, LIST, LSUB, - STATUS, and APPEND. - - - - - - - - - - - - -Crispin Standards Track [Page 31] - -RFC 3501 IMAPv4 March 2003 - - -6.3.1. SELECT Command - - Arguments: mailbox name - - Responses: REQUIRED untagged responses: FLAGS, EXISTS, RECENT - REQUIRED OK untagged responses: UNSEEN, PERMANENTFLAGS, - UIDNEXT, UIDVALIDITY - - Result: OK - select completed, now in selected state - NO - select failure, now in authenticated state: no - such mailbox, can't access mailbox - BAD - command unknown or arguments invalid - - The SELECT command selects a mailbox so that messages in the - mailbox can be accessed. Before returning an OK to the client, - the server MUST send the following untagged data to the client. - Note that earlier versions of this protocol only required the - FLAGS, EXISTS, and RECENT untagged data; consequently, client - implementations SHOULD implement default behavior for missing data - as discussed with the individual item. - - FLAGS Defined flags in the mailbox. See the description - of the FLAGS response for more detail. - - <n> EXISTS The number of messages in the mailbox. See the - description of the EXISTS response for more detail. - - <n> RECENT The number of messages with the \Recent flag set. - See the description of the RECENT response for more - detail. - - OK [UNSEEN <n>] - The message sequence number of the first unseen - message in the mailbox. If this is missing, the - client can not make any assumptions about the first - unseen message in the mailbox, and needs to issue a - SEARCH command if it wants to find it. - - OK [PERMANENTFLAGS (<list of flags>)] - A list of message flags that the client can change - permanently. If this is missing, the client should - assume that all flags can be changed permanently. - - OK [UIDNEXT <n>] - The next unique identifier value. Refer to section - 2.3.1.1 for more information. If this is missing, - the client can not make any assumptions about the - next unique identifier value. - - - -Crispin Standards Track [Page 32] - -RFC 3501 IMAPv4 March 2003 - - - OK [UIDVALIDITY <n>] - The unique identifier validity value. Refer to - section 2.3.1.1 for more information. If this is - missing, the server does not support unique - identifiers. - - Only one mailbox can be selected at a time in a connection; - simultaneous access to multiple mailboxes requires multiple - connections. The SELECT command automatically deselects any - currently selected mailbox before attempting the new selection. - Consequently, if a mailbox is selected and a SELECT command that - fails is attempted, no mailbox is selected. - - If the client is permitted to modify the mailbox, the server - SHOULD prefix the text of the tagged OK response with the - "[READ-WRITE]" response code. - - If the client is not permitted to modify the mailbox but is - permitted read access, the mailbox is selected as read-only, and - the server MUST prefix the text of the tagged OK response to - SELECT with the "[READ-ONLY]" response code. Read-only access - through SELECT differs from the EXAMINE command in that certain - read-only mailboxes MAY permit the change of permanent state on a - per-user (as opposed to global) basis. Netnews messages marked in - a server-based .newsrc file are an example of such per-user - permanent state that can be modified with read-only mailboxes. - - Example: C: A142 SELECT INBOX - S: * 172 EXISTS - S: * 1 RECENT - S: * OK [UNSEEN 12] Message 12 is first unseen - S: * OK [UIDVALIDITY 3857529045] UIDs valid - S: * OK [UIDNEXT 4392] Predicted next UID - S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) - S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited - S: A142 OK [READ-WRITE] SELECT completed - - - - - - - - - - - - - - - -Crispin Standards Track [Page 33] - -RFC 3501 IMAPv4 March 2003 - - -6.3.2. EXAMINE Command - - Arguments: mailbox name - - Responses: REQUIRED untagged responses: FLAGS, EXISTS, RECENT - REQUIRED OK untagged responses: UNSEEN, PERMANENTFLAGS, - UIDNEXT, UIDVALIDITY - - Result: OK - examine completed, now in selected state - NO - examine failure, now in authenticated state: no - such mailbox, can't access mailbox - BAD - command unknown or arguments invalid - - The EXAMINE command is identical to SELECT and returns the same - output; however, the selected mailbox is identified as read-only. - No changes to the permanent state of the mailbox, including - per-user state, are permitted; in particular, EXAMINE MUST NOT - cause messages to lose the \Recent flag. - - The text of the tagged OK response to the EXAMINE command MUST - begin with the "[READ-ONLY]" response code. - - Example: C: A932 EXAMINE blurdybloop - S: * 17 EXISTS - S: * 2 RECENT - S: * OK [UNSEEN 8] Message 8 is first unseen - S: * OK [UIDVALIDITY 3857529045] UIDs valid - S: * OK [UIDNEXT 4392] Predicted next UID - S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) - S: * OK [PERMANENTFLAGS ()] No permanent flags permitted - S: A932 OK [READ-ONLY] EXAMINE completed - - -6.3.3. CREATE Command - - Arguments: mailbox name - - Responses: no specific responses for this command - - Result: OK - create completed - NO - create failure: can't create mailbox with that name - BAD - command unknown or arguments invalid - - The CREATE command creates a mailbox with the given name. An OK - response is returned only if a new mailbox with that name has been - created. It is an error to attempt to create INBOX or a mailbox - with a name that refers to an extant mailbox. Any error in - creation will return a tagged NO response. - - - -Crispin Standards Track [Page 34] - -RFC 3501 IMAPv4 March 2003 - - - If the mailbox name is suffixed with the server's hierarchy - separator character (as returned from the server by a LIST - command), this is a declaration that the client intends to create - mailbox names under this name in the hierarchy. Server - implementations that do not require this declaration MUST ignore - the declaration. In any case, the name created is without the - trailing hierarchy delimiter. - - If the server's hierarchy separator character appears elsewhere in - the name, the server SHOULD create any superior hierarchical names - that are needed for the CREATE command to be successfully - completed. In other words, an attempt to create "foo/bar/zap" on - a server in which "/" is the hierarchy separator character SHOULD - create foo/ and foo/bar/ if they do not already exist. - - If a new mailbox is created with the same name as a mailbox which - was deleted, its unique identifiers MUST be greater than any - unique identifiers used in the previous incarnation of the mailbox - UNLESS the new incarnation has a different unique identifier - validity value. See the description of the UID command for more - detail. - - Example: C: A003 CREATE owatagusiam/ - S: A003 OK CREATE completed - C: A004 CREATE owatagusiam/blurdybloop - S: A004 OK CREATE completed - - Note: The interpretation of this example depends on whether - "/" was returned as the hierarchy separator from LIST. If - "/" is the hierarchy separator, a new level of hierarchy - named "owatagusiam" with a member called "blurdybloop" is - created. Otherwise, two mailboxes at the same hierarchy - level are created. - - -6.3.4. DELETE Command - - Arguments: mailbox name - - Responses: no specific responses for this command - - Result: OK - delete completed - NO - delete failure: can't delete mailbox with that name - BAD - command unknown or arguments invalid - - - - - - - -Crispin Standards Track [Page 35] - -RFC 3501 IMAPv4 March 2003 - - - The DELETE command permanently removes the mailbox with the given - name. A tagged OK response is returned only if the mailbox has - been deleted. It is an error to attempt to delete INBOX or a - mailbox name that does not exist. - - The DELETE command MUST NOT remove inferior hierarchical names. - For example, if a mailbox "foo" has an inferior "foo.bar" - (assuming "." is the hierarchy delimiter character), removing - "foo" MUST NOT remove "foo.bar". It is an error to attempt to - delete a name that has inferior hierarchical names and also has - the \Noselect mailbox name attribute (see the description of the - LIST response for more details). - - It is permitted to delete a name that has inferior hierarchical - names and does not have the \Noselect mailbox name attribute. In - this case, all messages in that mailbox are removed, and the name - will acquire the \Noselect mailbox name attribute. - - The value of the highest-used unique identifier of the deleted - mailbox MUST be preserved so that a new mailbox created with the - same name will not reuse the identifiers of the former - incarnation, UNLESS the new incarnation has a different unique - identifier validity value. See the description of the UID command - for more detail. - - Examples: C: A682 LIST "" * - S: * LIST () "/" blurdybloop - S: * LIST (\Noselect) "/" foo - S: * LIST () "/" foo/bar - S: A682 OK LIST completed - C: A683 DELETE blurdybloop - S: A683 OK DELETE completed - C: A684 DELETE foo - S: A684 NO Name "foo" has inferior hierarchical names - C: A685 DELETE foo/bar - S: A685 OK DELETE Completed - C: A686 LIST "" * - S: * LIST (\Noselect) "/" foo - S: A686 OK LIST completed - C: A687 DELETE foo - S: A687 OK DELETE Completed - - - - - - - - - - -Crispin Standards Track [Page 36] - -RFC 3501 IMAPv4 March 2003 - - - C: A82 LIST "" * - S: * LIST () "." blurdybloop - S: * LIST () "." foo - S: * LIST () "." foo.bar - S: A82 OK LIST completed - C: A83 DELETE blurdybloop - S: A83 OK DELETE completed - C: A84 DELETE foo - S: A84 OK DELETE Completed - C: A85 LIST "" * - S: * LIST () "." foo.bar - S: A85 OK LIST completed - C: A86 LIST "" % - S: * LIST (\Noselect) "." foo - S: A86 OK LIST completed - - -6.3.5. RENAME Command - - Arguments: existing mailbox name - new mailbox name - - Responses: no specific responses for this command - - Result: OK - rename completed - NO - rename failure: can't rename mailbox with that name, - can't rename to mailbox with that name - BAD - command unknown or arguments invalid - - The RENAME command changes the name of a mailbox. A tagged OK - response is returned only if the mailbox has been renamed. It is - an error to attempt to rename from a mailbox name that does not - exist or to a mailbox name that already exists. Any error in - renaming will return a tagged NO response. - - If the name has inferior hierarchical names, then the inferior - hierarchical names MUST also be renamed. For example, a rename of - "foo" to "zap" will rename "foo/bar" (assuming "/" is the - hierarchy delimiter character) to "zap/bar". - - If the server's hierarchy separator character appears in the name, - the server SHOULD create any superior hierarchical names that are - needed for the RENAME command to complete successfully. In other - words, an attempt to rename "foo/bar/zap" to baz/rag/zowie on a - server in which "/" is the hierarchy separator character SHOULD - create baz/ and baz/rag/ if they do not already exist. - - - - - -Crispin Standards Track [Page 37] - -RFC 3501 IMAPv4 March 2003 - - - The value of the highest-used unique identifier of the old mailbox - name MUST be preserved so that a new mailbox created with the same - name will not reuse the identifiers of the former incarnation, - UNLESS the new incarnation has a different unique identifier - validity value. See the description of the UID command for more - detail. - - Renaming INBOX is permitted, and has special behavior. It moves - all messages in INBOX to a new mailbox with the given name, - leaving INBOX empty. If the server implementation supports - inferior hierarchical names of INBOX, these are unaffected by a - rename of INBOX. - - Examples: C: A682 LIST "" * - S: * LIST () "/" blurdybloop - S: * LIST (\Noselect) "/" foo - S: * LIST () "/" foo/bar - S: A682 OK LIST completed - C: A683 RENAME blurdybloop sarasoop - S: A683 OK RENAME completed - C: A684 RENAME foo zowie - S: A684 OK RENAME Completed - C: A685 LIST "" * - S: * LIST () "/" sarasoop - S: * LIST (\Noselect) "/" zowie - S: * LIST () "/" zowie/bar - S: A685 OK LIST completed - - C: Z432 LIST "" * - S: * LIST () "." INBOX - S: * LIST () "." INBOX.bar - S: Z432 OK LIST completed - C: Z433 RENAME INBOX old-mail - S: Z433 OK RENAME completed - C: Z434 LIST "" * - S: * LIST () "." INBOX - S: * LIST () "." INBOX.bar - S: * LIST () "." old-mail - S: Z434 OK LIST completed - - - - - - - - - - - - -Crispin Standards Track [Page 38] - -RFC 3501 IMAPv4 March 2003 - - -6.3.6. SUBSCRIBE Command - - Arguments: mailbox - - Responses: no specific responses for this command - - Result: OK - subscribe completed - NO - subscribe failure: can't subscribe to that name - BAD - command unknown or arguments invalid - - The SUBSCRIBE command adds the specified mailbox name to the - server's set of "active" or "subscribed" mailboxes as returned by - the LSUB command. This command returns a tagged OK response only - if the subscription is successful. - - A server MAY validate the mailbox argument to SUBSCRIBE to verify - that it exists. However, it MUST NOT unilaterally remove an - existing mailbox name from the subscription list even if a mailbox - by that name no longer exists. - - Note: This requirement is because a server site can - choose to routinely remove a mailbox with a well-known - name (e.g., "system-alerts") after its contents expire, - with the intention of recreating it when new contents - are appropriate. - - - Example: C: A002 SUBSCRIBE #news.comp.mail.mime - S: A002 OK SUBSCRIBE completed - - -6.3.7. UNSUBSCRIBE Command - - Arguments: mailbox name - - Responses: no specific responses for this command - - Result: OK - unsubscribe completed - NO - unsubscribe failure: can't unsubscribe that name - BAD - command unknown or arguments invalid - - The UNSUBSCRIBE command removes the specified mailbox name from - the server's set of "active" or "subscribed" mailboxes as returned - by the LSUB command. This command returns a tagged OK response - only if the unsubscription is successful. - - Example: C: A002 UNSUBSCRIBE #news.comp.mail.mime - S: A002 OK UNSUBSCRIBE completed - - - -Crispin Standards Track [Page 39] - -RFC 3501 IMAPv4 March 2003 - - -6.3.8. LIST Command - - Arguments: reference name - mailbox name with possible wildcards - - Responses: untagged responses: LIST - - Result: OK - list completed - NO - list failure: can't list that reference or name - BAD - command unknown or arguments invalid - - The LIST command returns a subset of names from the complete set - of all names available to the client. Zero or more untagged LIST - replies are returned, containing the name attributes, hierarchy - delimiter, and name; see the description of the LIST reply for - more detail. - - The LIST command SHOULD return its data quickly, without undue - delay. For example, it SHOULD NOT go to excess trouble to - calculate the \Marked or \Unmarked status or perform other - processing; if each name requires 1 second of processing, then a - list of 1200 names would take 20 minutes! - - An empty ("" string) reference name argument indicates that the - mailbox name is interpreted as by SELECT. The returned mailbox - names MUST match the supplied mailbox name pattern. A non-empty - reference name argument is the name of a mailbox or a level of - mailbox hierarchy, and indicates the context in which the mailbox - name is interpreted. - - An empty ("" string) mailbox name argument is a special request to - return the hierarchy delimiter and the root name of the name given - in the reference. The value returned as the root MAY be the empty - string if the reference is non-rooted or is an empty string. In - all cases, a hierarchy delimiter (or NIL if there is no hierarchy) - is returned. This permits a client to get the hierarchy delimiter - (or find out that the mailbox names are flat) even when no - mailboxes by that name currently exist. - - The reference and mailbox name arguments are interpreted into a - canonical form that represents an unambiguous left-to-right - hierarchy. The returned mailbox names will be in the interpreted - form. - - - - - - - - -Crispin Standards Track [Page 40] - -RFC 3501 IMAPv4 March 2003 - - - Note: The interpretation of the reference argument is - implementation-defined. It depends upon whether the - server implementation has a concept of the "current - working directory" and leading "break out characters", - which override the current working directory. - - For example, on a server which exports a UNIX or NT - filesystem, the reference argument contains the current - working directory, and the mailbox name argument would - contain the name as interpreted in the current working - directory. - - If a server implementation has no concept of break out - characters, the canonical form is normally the reference - name appended with the mailbox name. Note that if the - server implements the namespace convention (section - 5.1.2), "#" is a break out character and must be treated - as such. - - If the reference argument is not a level of mailbox - hierarchy (that is, it is a \NoInferiors name), and/or - the reference argument does not end with the hierarchy - delimiter, it is implementation-dependent how this is - interpreted. For example, a reference of "foo/bar" and - mailbox name of "rag/baz" could be interpreted as - "foo/bar/rag/baz", "foo/barrag/baz", or "foo/rag/baz". - A client SHOULD NOT use such a reference argument except - at the explicit request of the user. A hierarchical - browser MUST NOT make any assumptions about server - interpretation of the reference unless the reference is - a level of mailbox hierarchy AND ends with the hierarchy - delimiter. - - Any part of the reference argument that is included in the - interpreted form SHOULD prefix the interpreted form. It SHOULD - also be in the same form as the reference name argument. This - rule permits the client to determine if the returned mailbox name - is in the context of the reference argument, or if something about - the mailbox argument overrode the reference argument. Without - this rule, the client would have to have knowledge of the server's - naming semantics including what characters are "breakouts" that - override a naming context. - - - - - - - - - -Crispin Standards Track [Page 41] - -RFC 3501 IMAPv4 March 2003 - - - For example, here are some examples of how references - and mailbox names might be interpreted on a UNIX-based - server: - - Reference Mailbox Name Interpretation - ------------ ------------ -------------- - ~smith/Mail/ foo.* ~smith/Mail/foo.* - archive/ % archive/% - #news. comp.mail.* #news.comp.mail.* - ~smith/Mail/ /usr/doc/foo /usr/doc/foo - archive/ ~fred/Mail/* ~fred/Mail/* - - The first three examples demonstrate interpretations in - the context of the reference argument. Note that - "~smith/Mail" SHOULD NOT be transformed into something - like "/u2/users/smith/Mail", or it would be impossible - for the client to determine that the interpretation was - in the context of the reference. - - The character "*" is a wildcard, and matches zero or more - characters at this position. The character "%" is similar to "*", - but it does not match a hierarchy delimiter. If the "%" wildcard - is the last character of a mailbox name argument, matching levels - of hierarchy are also returned. If these levels of hierarchy are - not also selectable mailboxes, they are returned with the - \Noselect mailbox name attribute (see the description of the LIST - response for more details). - - Server implementations are permitted to "hide" otherwise - accessible mailboxes from the wildcard characters, by preventing - certain characters or names from matching a wildcard in certain - situations. For example, a UNIX-based server might restrict the - interpretation of "*" so that an initial "/" character does not - match. - - The special name INBOX is included in the output from LIST, if - INBOX is supported by this server for this user and if the - uppercase string "INBOX" matches the interpreted reference and - mailbox name arguments with wildcards as described above. The - criteria for omitting INBOX is whether SELECT INBOX will return - failure; it is not relevant whether the user's real INBOX resides - on this or some other server. - - - - - - - - - -Crispin Standards Track [Page 42] - -RFC 3501 IMAPv4 March 2003 - - - Example: C: A101 LIST "" "" - S: * LIST (\Noselect) "/" "" - S: A101 OK LIST Completed - C: A102 LIST #news.comp.mail.misc "" - S: * LIST (\Noselect) "." #news. - S: A102 OK LIST Completed - C: A103 LIST /usr/staff/jones "" - S: * LIST (\Noselect) "/" / - S: A103 OK LIST Completed - C: A202 LIST ~/Mail/ % - S: * LIST (\Noselect) "/" ~/Mail/foo - S: * LIST () "/" ~/Mail/meetings - S: A202 OK LIST completed - - -6.3.9. LSUB Command - - Arguments: reference name - mailbox name with possible wildcards - - Responses: untagged responses: LSUB - - Result: OK - lsub completed - NO - lsub failure: can't list that reference or name - BAD - command unknown or arguments invalid - - The LSUB command returns a subset of names from the set of names - that the user has declared as being "active" or "subscribed". - Zero or more untagged LSUB replies are returned. The arguments to - LSUB are in the same form as those for LIST. - - The returned untagged LSUB response MAY contain different mailbox - flags from a LIST untagged response. If this should happen, the - flags in the untagged LIST are considered more authoritative. - - A special situation occurs when using LSUB with the % wildcard. - Consider what happens if "foo/bar" (with a hierarchy delimiter of - "/") is subscribed but "foo" is not. A "%" wildcard to LSUB must - return foo, not foo/bar, in the LSUB response, and it MUST be - flagged with the \Noselect attribute. - - The server MUST NOT unilaterally remove an existing mailbox name - from the subscription list even if a mailbox by that name no - longer exists. - - - - - - - -Crispin Standards Track [Page 43] - -RFC 3501 IMAPv4 March 2003 - - - Example: C: A002 LSUB "#news." "comp.mail.*" - S: * LSUB () "." #news.comp.mail.mime - S: * LSUB () "." #news.comp.mail.misc - S: A002 OK LSUB completed - C: A003 LSUB "#news." "comp.%" - S: * LSUB (\NoSelect) "." #news.comp.mail - S: A003 OK LSUB completed - - -6.3.10. STATUS Command - - Arguments: mailbox name - status data item names - - Responses: untagged responses: STATUS - - Result: OK - status completed - NO - status failure: no status for that name - BAD - command unknown or arguments invalid - - The STATUS command requests the status of the indicated mailbox. - It does not change the currently selected mailbox, nor does it - affect the state of any messages in the queried mailbox (in - particular, STATUS MUST NOT cause messages to lose the \Recent - flag). - - The STATUS command provides an alternative to opening a second - IMAP4rev1 connection and doing an EXAMINE command on a mailbox to - query that mailbox's status without deselecting the current - mailbox in the first IMAP4rev1 connection. - - Unlike the LIST command, the STATUS command is not guaranteed to - be fast in its response. Under certain circumstances, it can be - quite slow. In some implementations, the server is obliged to - open the mailbox read-only internally to obtain certain status - information. Also unlike the LIST command, the STATUS command - does not accept wildcards. - - Note: The STATUS command is intended to access the - status of mailboxes other than the currently selected - mailbox. Because the STATUS command can cause the - mailbox to be opened internally, and because this - information is available by other means on the selected - mailbox, the STATUS command SHOULD NOT be used on the - currently selected mailbox. - - - - - - -Crispin Standards Track [Page 44] - -RFC 3501 IMAPv4 March 2003 - - - The STATUS command MUST NOT be used as a "check for new - messages in the selected mailbox" operation (refer to - sections 7, 7.3.1, and 7.3.2 for more information about - the proper method for new message checking). - - Because the STATUS command is not guaranteed to be fast - in its results, clients SHOULD NOT expect to be able to - issue many consecutive STATUS commands and obtain - reasonable performance. - - The currently defined status data items that can be requested are: - - MESSAGES - The number of messages in the mailbox. - - RECENT - The number of messages with the \Recent flag set. - - UIDNEXT - The next unique identifier value of the mailbox. Refer to - section 2.3.1.1 for more information. - - UIDVALIDITY - The unique identifier validity value of the mailbox. Refer to - section 2.3.1.1 for more information. - - UNSEEN - The number of messages which do not have the \Seen flag set. - - - Example: C: A042 STATUS blurdybloop (UIDNEXT MESSAGES) - S: * STATUS blurdybloop (MESSAGES 231 UIDNEXT 44292) - S: A042 OK STATUS completed - - - - - - - - - - - - - - - - - - -Crispin Standards Track [Page 45] - -RFC 3501 IMAPv4 March 2003 - - -6.3.11. APPEND Command - - Arguments: mailbox name - OPTIONAL flag parenthesized list - OPTIONAL date/time string - message literal - - Responses: no specific responses for this command - - Result: OK - append completed - NO - append error: can't append to that mailbox, error - in flags or date/time or message text - BAD - command unknown or arguments invalid - - The APPEND command appends the literal argument as a new message - to the end of the specified destination mailbox. This argument - SHOULD be in the format of an [RFC-2822] message. 8-bit - characters are permitted in the message. A server implementation - that is unable to preserve 8-bit data properly MUST be able to - reversibly convert 8-bit APPEND data to 7-bit using a [MIME-IMB] - content transfer encoding. - - Note: There MAY be exceptions, e.g., draft messages, in - which required [RFC-2822] header lines are omitted in - the message literal argument to APPEND. The full - implications of doing so MUST be understood and - carefully weighed. - - If a flag parenthesized list is specified, the flags SHOULD be set - in the resulting message; otherwise, the flag list of the - resulting message is set to empty by default. In either case, the - Recent flag is also set. - - If a date-time is specified, the internal date SHOULD be set in - the resulting message; otherwise, the internal date of the - resulting message is set to the current date and time by default. - - If the append is unsuccessful for any reason, the mailbox MUST be - restored to its state before the APPEND attempt; no partial - appending is permitted. - - If the destination mailbox does not exist, a server MUST return an - error, and MUST NOT automatically create the mailbox. Unless it - is certain that the destination mailbox can not be created, the - server MUST send the response code "[TRYCREATE]" as the prefix of - the text of the tagged NO response. This gives a hint to the - client that it can attempt a CREATE command and retry the APPEND - if the CREATE is successful. - - - -Crispin Standards Track [Page 46] - -RFC 3501 IMAPv4 March 2003 - - - If the mailbox is currently selected, the normal new message - actions SHOULD occur. Specifically, the server SHOULD notify the - client immediately via an untagged EXISTS response. If the server - does not do so, the client MAY issue a NOOP command (or failing - that, a CHECK command) after one or more APPEND commands. - - Example: C: A003 APPEND saved-messages (\Seen) {310} - S: + Ready for literal data - C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) - C: From: Fred Foobar <foobar@Blurdybloop.COM> - C: Subject: afternoon meeting - C: To: mooch@owatagu.siam.edu - C: Message-Id: <B27397-0100000@Blurdybloop.COM> - C: MIME-Version: 1.0 - C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII - C: - C: Hello Joe, do you think we can meet at 3:30 tomorrow? - C: - S: A003 OK APPEND completed - - Note: The APPEND command is not used for message delivery, - because it does not provide a mechanism to transfer [SMTP] - envelope information. - -6.4. Client Commands - Selected State - - In the selected state, commands that manipulate messages in a mailbox - are permitted. - - In addition to the universal commands (CAPABILITY, NOOP, and LOGOUT), - and the authenticated state commands (SELECT, EXAMINE, CREATE, - DELETE, RENAME, SUBSCRIBE, UNSUBSCRIBE, LIST, LSUB, STATUS, and - APPEND), the following commands are valid in the selected state: - CHECK, CLOSE, EXPUNGE, SEARCH, FETCH, STORE, COPY, and UID. - -6.4.1. CHECK Command - - Arguments: none - - Responses: no specific responses for this command - - Result: OK - check completed - BAD - command unknown or arguments invalid - - The CHECK command requests a checkpoint of the currently selected - mailbox. A checkpoint refers to any implementation-dependent - housekeeping associated with the mailbox (e.g., resolving the - server's in-memory state of the mailbox with the state on its - - - -Crispin Standards Track [Page 47] - -RFC 3501 IMAPv4 March 2003 - - - disk) that is not normally executed as part of each command. A - checkpoint MAY take a non-instantaneous amount of real time to - complete. If a server implementation has no such housekeeping - considerations, CHECK is equivalent to NOOP. - - There is no guarantee that an EXISTS untagged response will happen - as a result of CHECK. NOOP, not CHECK, SHOULD be used for new - message polling. - - Example: C: FXXZ CHECK - S: FXXZ OK CHECK Completed - - -6.4.2. 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 - - 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 responses are sent. - - No messages are removed, and no error is given, if the mailbox is - selected by an EXAMINE command or is otherwise selected read-only. - - Even if a mailbox is selected, a SELECT, EXAMINE, or LOGOUT - command MAY be issued without previously issuing a CLOSE command. - The SELECT, EXAMINE, and LOGOUT commands implicitly close the - currently selected mailbox without doing an expunge. However, - when many messages are deleted, a CLOSE-LOGOUT or CLOSE-SELECT - sequence is considerably faster than an EXPUNGE-LOGOUT or - EXPUNGE-SELECT because no untagged EXPUNGE responses (which the - client would probably ignore) are sent. - - Example: C: A341 CLOSE - S: A341 OK CLOSE completed - - - - - - - - - - -Crispin Standards Track [Page 48] - -RFC 3501 IMAPv4 March 2003 - - -6.4.3. EXPUNGE Command - - Arguments: none - - Responses: untagged responses: EXPUNGE - - Result: OK - expunge completed - NO - expunge failure: can't expunge (e.g., permission - denied) - BAD - command unknown or arguments invalid - - 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, an untagged EXPUNGE response is - sent for each message that is removed. - - Example: C: A202 EXPUNGE - S: * 3 EXPUNGE - S: * 3 EXPUNGE - S: * 5 EXPUNGE - S: * 8 EXPUNGE - S: A202 OK EXPUNGE completed - - Note: In this example, messages 3, 4, 7, and 11 had the - \Deleted flag set. See the description of the EXPUNGE - response for further explanation. - - -6.4.4. SEARCH Command - - Arguments: OPTIONAL [CHARSET] specification - searching criteria (one or more) - - Responses: REQUIRED untagged response: SEARCH - - Result: OK - search completed - NO - search error: can't search that [CHARSET] or - criteria - BAD - command unknown or arguments invalid - - The SEARCH command searches the mailbox for messages that match - the given searching criteria. Searching criteria consist of one - or more search keys. The untagged SEARCH response from the server - contains a listing of message sequence numbers corresponding to - those messages that match the searching criteria. - - - - - - -Crispin Standards Track [Page 49] - -RFC 3501 IMAPv4 March 2003 - - - When multiple keys are specified, the result is the intersection - (AND function) of all the messages that match those keys. For - example, the criteria DELETED FROM "SMITH" SINCE 1-Feb-1994 refers - to all deleted messages from Smith that were placed in the mailbox - since February 1, 1994. A search key can also be a parenthesized - list of one or more search keys (e.g., for use with the OR and NOT - keys). - - Server implementations MAY exclude [MIME-IMB] body parts with - terminal content media types other than TEXT and MESSAGE from - consideration in SEARCH matching. - - The OPTIONAL [CHARSET] specification consists of the word - "CHARSET" followed by a registered [CHARSET]. It indicates the - [CHARSET] of the strings that appear in the search criteria. - [MIME-IMB] content transfer encodings, and [MIME-HDRS] strings in - [RFC-2822]/[MIME-IMB] headers, MUST be decoded before comparing - text in a [CHARSET] other than US-ASCII. US-ASCII MUST be - supported; other [CHARSET]s MAY be supported. - - If the server does not support the specified [CHARSET], it MUST - return a tagged NO response (not a BAD). This response SHOULD - contain the BADCHARSET response code, which MAY list the - [CHARSET]s supported by the server. - - 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. - - The defined search keys are as follows. Refer to the Formal - Syntax section for the precise syntactic definitions of the - arguments. - - <sequence set> - Messages with message sequence numbers corresponding to the - specified message sequence number set. - - ALL - All messages in the mailbox; the default initial key for - ANDing. - - ANSWERED - Messages with the \Answered flag set. - - - - - - - - -Crispin Standards Track [Page 50] - -RFC 3501 IMAPv4 March 2003 - - - BCC <string> - Messages that contain the specified string in the envelope - structure's BCC field. - - BEFORE <date> - Messages whose internal date (disregarding time and timezone) - is earlier than the specified date. - - BODY <string> - Messages that contain the specified string in the body of the - message. - - CC <string> - Messages that contain the specified string in the envelope - structure's CC field. - - DELETED - Messages with the \Deleted flag set. - - DRAFT - Messages with the \Draft flag set. - - FLAGGED - Messages with the \Flagged flag set. - - FROM <string> - Messages that contain the specified string in the envelope - structure's FROM field. - - HEADER <field-name> <string> - Messages that have a header with the specified field-name (as - defined in [RFC-2822]) and that contains the specified string - in the text of the header (what comes after the colon). If the - string to search is zero-length, this matches all messages that - have a header line with the specified field-name regardless of - the contents. - - KEYWORD <flag> - Messages with the specified keyword flag set. - - LARGER <n> - Messages with an [RFC-2822] size larger than the specified - number of octets. - - NEW - Messages that have the \Recent flag set but not the \Seen flag. - This is functionally equivalent to "(RECENT UNSEEN)". - - - - -Crispin Standards Track [Page 51] - -RFC 3501 IMAPv4 March 2003 - - - NOT <search-key> - Messages that do not match the specified search key. - - OLD - Messages that do not have the \Recent flag set. This is - functionally equivalent to "NOT RECENT" (as opposed to "NOT - NEW"). - - ON <date> - Messages whose internal date (disregarding time and timezone) - is within the specified date. - - OR <search-key1> <search-key2> - Messages that match either search key. - - RECENT - Messages that have the \Recent flag set. - - SEEN - Messages that have the \Seen flag set. - - SENTBEFORE <date> - Messages whose [RFC-2822] Date: header (disregarding time and - timezone) is earlier than the specified date. - - SENTON <date> - Messages whose [RFC-2822] Date: header (disregarding time and - timezone) is within the specified date. - - SENTSINCE <date> - Messages whose [RFC-2822] Date: header (disregarding time and - timezone) is within or later than the specified date. - - SINCE <date> - Messages whose internal date (disregarding time and timezone) - is within or later than the specified date. - - SMALLER <n> - Messages with an [RFC-2822] size smaller than the specified - number of octets. - - - - - - - - - - - -Crispin Standards Track [Page 52] - -RFC 3501 IMAPv4 March 2003 - - - SUBJECT <string> - Messages that contain the specified string in the envelope - structure's SUBJECT field. - - TEXT <string> - Messages that contain the specified string in the header or - body of the message. - - TO <string> - Messages that contain the specified string in the envelope - structure's TO field. - - UID <sequence set> - Messages with unique identifiers corresponding to the specified - unique identifier set. Sequence set ranges are permitted. - - UNANSWERED - Messages that do not have the \Answered flag set. - - UNDELETED - Messages that do not have the \Deleted flag set. - - UNDRAFT - Messages that do not have the \Draft flag set. - - UNFLAGGED - Messages that do not have the \Flagged flag set. - - UNKEYWORD <flag> - Messages that do not have the specified keyword flag set. - - UNSEEN - Messages that do not have the \Seen flag set. - - - - - - - - - - - - - - - - - - -Crispin Standards Track [Page 53] - -RFC 3501 IMAPv4 March 2003 - - - Example: C: A282 SEARCH FLAGGED SINCE 1-Feb-1994 NOT FROM "Smith" - S: * SEARCH 2 84 882 - S: A282 OK SEARCH completed - C: A283 SEARCH TEXT "string not in mailbox" - S: * SEARCH - S: A283 OK SEARCH completed - C: A284 SEARCH CHARSET UTF-8 TEXT {6} - C: XXXXXX - S: * SEARCH 43 - S: A284 OK SEARCH completed - - Note: Since this document is restricted to 7-bit ASCII - text, it is not possible to show actual UTF-8 data. The - "XXXXXX" is a placeholder for what would be 6 octets of - 8-bit data in an actual transaction. - - -6.4.5. FETCH Command - - Arguments: sequence set - message data item names or macro - - Responses: untagged responses: FETCH - - Result: OK - fetch completed - NO - fetch error: can't fetch that data - BAD - command unknown or arguments invalid - - The FETCH command retrieves data associated with a message in the - mailbox. The data items to be fetched can be either a single atom - or a parenthesized list. - - Most data items, identified in the formal syntax under the - msg-att-static rule, are static and MUST NOT change for any - particular message. Other data items, identified in the formal - syntax under the msg-att-dynamic rule, MAY change, either as a - result of a STORE command or due to external events. - - For example, if a client receives an ENVELOPE for a - message when it already knows the envelope, it can - safely ignore the newly transmitted envelope. - - There are three macros which specify commonly-used sets of data - items, and can be used instead of data items. A macro must be - used by itself, and not in conjunction with other macros or data - items. - - - - - -Crispin Standards Track [Page 54] - -RFC 3501 IMAPv4 March 2003 - - - ALL - Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE) - - FAST - Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE) - - FULL - Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE - BODY) - - The currently defined data items that can be fetched are: - - BODY - Non-extensible form of BODYSTRUCTURE. - - BODY[<section>]<<partial>> - The text of a particular body section. The section - specification is a set of zero or more part specifiers - delimited by periods. A part specifier is either a part number - or one of the following: HEADER, HEADER.FIELDS, - HEADER.FIELDS.NOT, MIME, and TEXT. An empty section - specification refers to the entire message, including the - header. - - Every message has at least one part number. Non-[MIME-IMB] - messages, and non-multipart [MIME-IMB] messages with no - encapsulated message, only have a part 1. - - Multipart messages are assigned consecutive part numbers, as - they occur in the message. If a particular part is of type - message or multipart, its parts MUST be indicated by a period - followed by the part number within that nested multipart part. - - A part of type MESSAGE/RFC822 also has nested part numbers, - referring to parts of the MESSAGE part's body. - - The HEADER, HEADER.FIELDS, HEADER.FIELDS.NOT, and TEXT part - specifiers can be the sole part specifier or can be prefixed by - one or more numeric part specifiers, provided that the numeric - part specifier refers to a part of type MESSAGE/RFC822. The - MIME part specifier MUST be prefixed by one or more numeric - part specifiers. - - The HEADER, HEADER.FIELDS, and HEADER.FIELDS.NOT part - specifiers refer to the [RFC-2822] header of the message or of - an encapsulated [MIME-IMT] MESSAGE/RFC822 message. - HEADER.FIELDS and HEADER.FIELDS.NOT are followed by a list of - field-name (as defined in [RFC-2822]) names, and return a - - - -Crispin Standards Track [Page 55] - -RFC 3501 IMAPv4 March 2003 - - - subset of the header. The subset returned by HEADER.FIELDS - contains only those header fields with a field-name that - matches one of the names in the list; similarly, the subset - returned by HEADER.FIELDS.NOT contains only the header fields - with a non-matching field-name. The field-matching is - case-insensitive but otherwise exact. Subsetting does not - exclude the [RFC-2822] delimiting blank line between the header - and the body; the blank line is included in all header fetches, - except in the case of a message which has no body and no blank - line. - - The MIME part specifier refers to the [MIME-IMB] header for - this part. - - The TEXT part specifier refers to the text body of the message, - omitting the [RFC-2822] header. - - Here is an example of a complex message with some of its - part specifiers: - - HEADER ([RFC-2822] header of the message) - TEXT ([RFC-2822] text body of the message) MULTIPART/MIXED - 1 TEXT/PLAIN - 2 APPLICATION/OCTET-STREAM - 3 MESSAGE/RFC822 - 3.HEADER ([RFC-2822] header of the message) - 3.TEXT ([RFC-2822] text body of the message) MULTIPART/MIXED - 3.1 TEXT/PLAIN - 3.2 APPLICATION/OCTET-STREAM - 4 MULTIPART/MIXED - 4.1 IMAGE/GIF - 4.1.MIME ([MIME-IMB] header for the IMAGE/GIF) - 4.2 MESSAGE/RFC822 - 4.2.HEADER ([RFC-2822] header of the message) - 4.2.TEXT ([RFC-2822] text body of the message) MULTIPART/MIXED - 4.2.1 TEXT/PLAIN - 4.2.2 MULTIPART/ALTERNATIVE - 4.2.2.1 TEXT/PLAIN - 4.2.2.2 TEXT/RICHTEXT - - - It is possible to fetch a substring of the designated text. - This is done by appending an open angle bracket ("<"), the - octet position of the first desired octet, a period, the - maximum number of octets desired, and a close angle bracket - (">") to the part specifier. If the starting octet is beyond - the end of the text, an empty string is returned. - - - - -Crispin Standards Track [Page 56] - -RFC 3501 IMAPv4 March 2003 - - - Any partial fetch that attempts to read beyond the end of the - text is truncated as appropriate. A partial fetch that starts - at octet 0 is returned as a partial fetch, even if this - truncation happened. - - Note: This means that BODY[]<0.2048> of a 1500-octet message - will return BODY[]<0> with a literal of size 1500, not - BODY[]. - - Note: A substring fetch of a HEADER.FIELDS or - HEADER.FIELDS.NOT part specifier is calculated after - subsetting the header. - - The \Seen flag is implicitly set; if this causes the flags to - change, they SHOULD be included as part of the FETCH responses. - - BODY.PEEK[<section>]<<partial>> - An alternate form of BODY[<section>] that does not implicitly - set the \Seen flag. - - BODYSTRUCTURE - The [MIME-IMB] body structure of the message. This is computed - by the server by parsing the [MIME-IMB] header fields in the - [RFC-2822] header and [MIME-IMB] headers. - - ENVELOPE - The envelope structure of the message. This is computed by the - server by parsing the [RFC-2822] header into the component - parts, defaulting various fields as necessary. - - FLAGS - The flags that are set for this message. - - INTERNALDATE - The internal date of the message. - - RFC822 - Functionally equivalent to BODY[], differing in the syntax of - the resulting untagged FETCH data (RFC822 is returned). - - RFC822.HEADER - Functionally equivalent to BODY.PEEK[HEADER], differing in the - syntax of the resulting untagged FETCH data (RFC822.HEADER is - returned). - - RFC822.SIZE - The [RFC-2822] size of the message. - - - - -Crispin Standards Track [Page 57] - -RFC 3501 IMAPv4 March 2003 - - - RFC822.TEXT - Functionally equivalent to BODY[TEXT], differing in the syntax - of the resulting untagged FETCH data (RFC822.TEXT is returned). - - UID - The unique identifier for the message. - - - Example: C: A654 FETCH 2:4 (FLAGS BODY[HEADER.FIELDS (DATE FROM)]) - S: * 2 FETCH .... - S: * 3 FETCH .... - S: * 4 FETCH .... - S: A654 OK FETCH completed - - -6.4.6. STORE Command - - Arguments: sequence set - message data item name - value for message data item - - Responses: untagged responses: FETCH - - Result: OK - store completed - NO - store error: can't store that data - BAD - command unknown or arguments invalid - - The STORE command alters data associated with a message in the - mailbox. Normally, STORE will return the updated value of the - data with an untagged FETCH response. A suffix of ".SILENT" in - the data item name prevents the untagged FETCH, and the server - SHOULD assume that the client has determined the updated value - itself or does not care about the updated value. - - Note: Regardless of whether or not the ".SILENT" suffix - was used, the server SHOULD send an untagged FETCH - response if a change to a message's flags from an - external source is observed. The intent is that the - status of the flags is determinate without a race - condition. - - - - - - - - - - - -Crispin Standards Track [Page 58] - -RFC 3501 IMAPv4 March 2003 - - - The currently defined data items that can be stored are: - - FLAGS <flag list> - Replace the flags for the message (other than \Recent) with the - argument. The new value of the flags is returned as if a FETCH - of those flags was done. - - FLAGS.SILENT <flag list> - Equivalent to FLAGS, but without returning a new value. - - +FLAGS <flag list> - Add the argument to the flags for the message. The new value - of the flags is returned as if a FETCH of those flags was done. - - +FLAGS.SILENT <flag list> - Equivalent to +FLAGS, but without returning a new value. - - -FLAGS <flag list> - Remove the argument from the flags for the message. The new - value of the flags is returned as if a FETCH of those flags was - done. - - -FLAGS.SILENT <flag list> - Equivalent to -FLAGS, but without returning a new value. - - - Example: C: A003 STORE 2:4 +FLAGS (\Deleted) - S: * 2 FETCH (FLAGS (\Deleted \Seen)) - S: * 3 FETCH (FLAGS (\Deleted)) - S: * 4 FETCH (FLAGS (\Deleted \Flagged \Seen)) - S: A003 OK STORE completed - - -6.4.7. COPY Command - - Arguments: sequence set - mailbox name - - Responses: no specific responses for this command - - Result: OK - copy completed - NO - copy error: can't copy those messages or to that - name - BAD - command unknown or arguments invalid - - - - - - - -Crispin Standards Track [Page 59] - -RFC 3501 IMAPv4 March 2003 - - - The COPY command copies the specified message(s) to the end of the - specified destination mailbox. The flags and internal date of the - message(s) SHOULD be preserved, and the Recent flag SHOULD be set, - in the copy. - - If the destination mailbox does not exist, a server SHOULD return - an error. It SHOULD NOT automatically create the mailbox. Unless - it is certain that the destination mailbox can not be created, the - server MUST send the response code "[TRYCREATE]" as the prefix of - the text of the tagged NO response. This gives a hint to the - client that it can attempt a CREATE command and retry the COPY if - the CREATE is successful. - - If the COPY command is unsuccessful for any reason, server - implementations MUST restore the destination mailbox to its state - before the COPY attempt. - - Example: C: A003 COPY 2:4 MEETING - S: A003 OK COPY completed - - -6.4.8. UID Command - - Arguments: command name - command arguments - - Responses: untagged responses: FETCH, SEARCH - - Result: OK - UID command completed - NO - UID command error - BAD - command unknown or arguments invalid - - The UID command has two forms. In the first form, it takes as its - arguments a COPY, FETCH, or STORE command with arguments - appropriate for the associated command. However, the numbers in - the sequence set argument are unique identifiers instead of - message sequence numbers. Sequence set ranges are permitted, but - there is no guarantee that unique identifiers will be contiguous. - - A non-existent unique identifier is ignored without any error - message generated. Thus, it is possible for a UID FETCH command - to return an OK without any data or a UID COPY or UID STORE to - return an OK without performing any operations. - - In the second form, the UID command takes a SEARCH command with - SEARCH command arguments. The interpretation of the arguments is - the same as with SEARCH; however, the numbers returned in a SEARCH - response for a UID SEARCH command are unique identifiers instead - - - -Crispin Standards Track [Page 60] - -RFC 3501 IMAPv4 March 2003 - - - of message sequence numbers. For example, the command UID SEARCH - 1:100 UID 443:557 returns the unique identifiers corresponding to - the intersection of two sequence sets, the message sequence number - range 1:100 and the UID range 443:557. - - Note: in the above example, the UID range 443:557 - appears. The same comment about a non-existent unique - identifier being ignored without any error message also - applies here. Hence, even if neither UID 443 or 557 - exist, this range is valid and would include an existing - UID 495. - - Also note that a UID range of 559:* always includes the - UID of the last message in the mailbox, even if 559 is - higher than any assigned UID value. This is because the - contents of a range are independent of the order of the - range endpoints. Thus, any UID range with * as one of - the endpoints indicates at least one message (the - message with the highest numbered UID), unless the - mailbox is empty. - - The number after the "*" in an untagged FETCH response is always a - message sequence number, not a unique identifier, even for a UID - command response. However, server implementations MUST implicitly - include the UID message data item as part of any FETCH response - caused by a UID command, regardless of whether a UID was specified - as a message data item to the FETCH. - - - Note: The rule about including the UID message data item as part - of a FETCH response primarily applies to the UID FETCH and UID - STORE commands, including a UID FETCH command that does not - include UID as a message data item. Although it is unlikely that - the other UID commands will cause an untagged FETCH, this rule - applies to these commands as well. - - Example: C: A999 UID FETCH 4827313:4828442 FLAGS - S: * 23 FETCH (FLAGS (\Seen) UID 4827313) - S: * 24 FETCH (FLAGS (\Seen) UID 4827943) - S: * 25 FETCH (FLAGS (\Seen) UID 4828442) - S: A999 OK UID FETCH completed - - - - - - - - - - -Crispin Standards Track [Page 61] - -RFC 3501 IMAPv4 March 2003 - - -6.5. Client Commands - Experimental/Expansion - - -6.5.1. X<atom> Command - - Arguments: implementation defined - - Responses: implementation defined - - Result: OK - command completed - NO - failure - BAD - command unknown or arguments invalid - - Any command prefixed with an X is an experimental command. - Commands which are not part of this specification, a standard or - standards-track revision of this specification, or an - IESG-approved experimental protocol, MUST use the X prefix. - - Any added untagged responses issued by an experimental command - MUST also be prefixed with an X. Server implementations MUST NOT - send any such untagged responses, unless the client requested it - by issuing the associated experimental command. - - Example: C: a441 CAPABILITY - S: * CAPABILITY IMAP4rev1 XPIG-LATIN - S: a441 OK CAPABILITY completed - C: A442 XPIG-LATIN - S: * XPIG-LATIN ow-nay eaking-spay ig-pay atin-lay - S: A442 OK XPIG-LATIN ompleted-cay - -7. Server Responses - - Server responses are in three forms: status responses, server data, - and command continuation request. The information contained in a - server response, identified by "Contents:" in the response - descriptions below, is described by function, not by syntax. The - precise syntax of server responses is described in the Formal Syntax - section. - - The client MUST be prepared to accept any response at all times. - - Status responses can be tagged or untagged. Tagged status responses - indicate the completion result (OK, NO, or BAD status) of a client - command, and have a tag matching the command. - - Some status responses, and all server data, are untagged. An - untagged response is indicated by the token "*" instead of a tag. - Untagged status responses indicate server greeting, or server status - - - -Crispin Standards Track [Page 62] - -RFC 3501 IMAPv4 March 2003 - - - that does not indicate the completion of a command (for example, an - impending system shutdown alert). For historical reasons, untagged - server data responses are also called "unsolicited data", although - strictly speaking, only unilateral server data is truly - "unsolicited". - - Certain server data MUST be recorded by the client when it is - received; this is noted in the description of that data. Such data - conveys critical information which affects the interpretation of all - subsequent commands and responses (e.g., updates reflecting the - creation or destruction of messages). - - Other server data SHOULD be recorded for later reference; if the - client does not need to record the data, or if recording the data has - no obvious purpose (e.g., a SEARCH response when no SEARCH command is - in progress), the data SHOULD be ignored. - - An example of unilateral untagged server data occurs when the IMAP - connection is in the selected state. In the selected state, the - server checks the mailbox for new messages as part of command - execution. Normally, this is part of the execution of every command; - hence, a NOOP command suffices to check for new messages. If new - messages are found, the server sends untagged EXISTS and RECENT - responses reflecting the new size of the mailbox. Server - implementations that offer multiple simultaneous access to the same - mailbox SHOULD also send appropriate unilateral untagged FETCH and - EXPUNGE responses if another agent changes the state of any message - flags or expunges any messages. - - Command continuation request responses use the token "+" instead of a - tag. These responses are sent by the server to indicate acceptance - of an incomplete client command and readiness for the remainder of - the command. - -7.1. Server Responses - Status Responses - - Status responses are OK, NO, BAD, PREAUTH and BYE. OK, NO, and BAD - can be tagged or untagged. PREAUTH and BYE are always untagged. - - Status responses MAY include an OPTIONAL "response code". A response - code consists of data inside square brackets in the form of an atom, - possibly followed by a space and arguments. The response code - contains additional information or status codes for client software - beyond the OK/NO/BAD condition, and are defined when there is a - specific action that a client can take based upon the additional - information. - - - - - -Crispin Standards Track [Page 63] - -RFC 3501 IMAPv4 March 2003 - - - The currently defined response codes are: - - ALERT - - The human-readable text contains a special alert that MUST be - presented to the user in a fashion that calls the user's - attention to the message. - - BADCHARSET - - Optionally followed by a parenthesized list of charsets. A - SEARCH failed because the given charset is not supported by - this implementation. If the optional list of charsets is - given, this lists the charsets that are supported by this - implementation. - - CAPABILITY - - Followed by a list of capabilities. This can appear in the - initial OK or PREAUTH response to transmit an initial - capabilities list. This makes it unnecessary for a client to - send a separate CAPABILITY command if it recognizes this - response. - - PARSE - - The human-readable text represents an error in parsing the - [RFC-2822] header or [MIME-IMB] headers of a message in the - mailbox. - - PERMANENTFLAGS - - Followed by a parenthesized list of flags, indicates which of - the known flags the client can change permanently. Any flags - that are in the FLAGS untagged response, but not the - PERMANENTFLAGS list, can not be set permanently. If the client - attempts to STORE a flag that is not in the PERMANENTFLAGS - list, the server will either ignore the change or store the - state change for the remainder of the current session only. - The PERMANENTFLAGS list can also include the special flag \*, - which indicates that it is possible to create new keywords by - attempting to store those flags in the mailbox. - - - - - - - - - -Crispin Standards Track [Page 64] - -RFC 3501 IMAPv4 March 2003 - - - READ-ONLY - - The mailbox is selected read-only, or its access while selected - has changed from read-write to read-only. - - READ-WRITE - - The mailbox is selected read-write, or its access while - selected has changed from read-only to read-write. - - TRYCREATE - - An APPEND or COPY attempt is failing because the target mailbox - does not exist (as opposed to some other reason). This is a - hint to the client that the operation can succeed if the - mailbox is first created by the CREATE command. - - UIDNEXT - - Followed by a decimal number, indicates the next unique - identifier value. Refer to section 2.3.1.1 for more - information. - - UIDVALIDITY - - Followed by a decimal number, indicates the unique identifier - validity value. Refer to section 2.3.1.1 for more information. - - UNSEEN - - Followed by a decimal number, indicates the number of the first - message without the \Seen flag set. - - Additional response codes defined by particular client or server - implementations SHOULD be prefixed with an "X" until they are - added to a revision of this protocol. Client implementations - SHOULD ignore response codes that they do not recognize. - -7.1.1. OK Response - - Contents: OPTIONAL response code - human-readable text - - The OK response indicates an information message from the server. - When tagged, it indicates successful completion of the associated - command. The human-readable text MAY be presented to the user as - an information message. The untagged form indicates an - - - - -Crispin Standards Track [Page 65] - -RFC 3501 IMAPv4 March 2003 - - - information-only message; the nature of the information MAY be - indicated by a response code. - - The untagged form is also used as one of three possible greetings - at connection startup. It indicates that the connection is not - yet authenticated and that a LOGIN command is needed. - - Example: S: * OK IMAP4rev1 server ready - C: A001 LOGIN fred blurdybloop - S: * OK [ALERT] System shutdown in 10 minutes - S: A001 OK LOGIN Completed - - -7.1.2. NO Response - - Contents: OPTIONAL response code - human-readable text - - The NO response indicates an operational error message from the - server. When tagged, it indicates unsuccessful completion of the - associated command. The untagged form indicates a warning; the - command can still complete successfully. The human-readable text - describes the condition. - - Example: C: A222 COPY 1:2 owatagusiam - S: * NO Disk is 98% full, please delete unnecessary data - S: A222 OK COPY completed - C: A223 COPY 3:200 blurdybloop - S: * NO Disk is 98% full, please delete unnecessary data - S: * NO Disk is 99% full, please delete unnecessary data - S: A223 NO COPY failed: disk is full - - -7.1.3. BAD Response - - Contents: OPTIONAL response code - human-readable text - - The BAD response indicates an error message from the server. When - tagged, it reports a protocol-level error in the client's command; - the tag indicates the command that caused the error. The untagged - form indicates a protocol-level error for which the associated - command can not be determined; it can also indicate an internal - server failure. The human-readable text describes the condition. - - - - - - - -Crispin Standards Track [Page 66] - -RFC 3501 IMAPv4 March 2003 - - - Example: C: ...very long command line... - S: * BAD Command line too long - C: ...empty line... - S: * BAD Empty command line - C: A443 EXPUNGE - S: * BAD Disk crash, attempting salvage to a new disk! - S: * OK Salvage successful, no data lost - S: A443 OK Expunge completed - - -7.1.4. PREAUTH Response - - Contents: OPTIONAL response code - human-readable text - - The PREAUTH response is always untagged, and is one of three - possible greetings at connection startup. It indicates that the - connection has already been authenticated by external means; thus - no LOGIN command is needed. - - Example: S: * PREAUTH IMAP4rev1 server logged in as Smith - - -7.1.5. BYE Response - - Contents: OPTIONAL response code - human-readable text - - The BYE response is always untagged, and indicates that the server - is about to close the connection. The human-readable text MAY be - displayed to the user in a status report by the client. The BYE - response is sent under one of four conditions: - - 1) as part of a normal logout sequence. The server will close - the connection after sending the tagged OK response to the - LOGOUT command. - - 2) as a panic shutdown announcement. The server closes the - connection immediately. - - 3) as an announcement of an inactivity autologout. The server - closes the connection immediately. - - 4) as one of three possible greetings at connection startup, - indicating that the server is not willing to accept a - connection from this client. The server closes the - connection immediately. - - - - -Crispin Standards Track [Page 67] - -RFC 3501 IMAPv4 March 2003 - - - The difference between a BYE that occurs as part of a normal - LOGOUT sequence (the first case) and a BYE that occurs because of - a failure (the other three cases) is that the connection closes - immediately in the failure case. In all cases the client SHOULD - continue to read response data from the server until the - connection is closed; this will ensure that any pending untagged - or completion responses are read and processed. - - Example: S: * BYE Autologout; idle for too long - -7.2. Server Responses - Server and Mailbox Status - - These responses are always untagged. This is how server and mailbox - status data are transmitted from the server to the client. Many of - these responses typically result from a command with the same name. - -7.2.1. CAPABILITY Response - - Contents: capability listing - - The CAPABILITY response occurs as a result of a CAPABILITY - command. The capability listing contains a space-separated - listing of capability names that the server supports. The - capability listing MUST include the atom "IMAP4rev1". - - In addition, client and server implementations MUST implement the - STARTTLS, LOGINDISABLED, and AUTH=PLAIN (described in [IMAP-TLS]) - capabilities. See the Security Considerations section for - important information. - - A capability name which begins with "AUTH=" indicates that the - server supports that particular authentication mechanism. - - The LOGINDISABLED capability indicates that the LOGIN command is - disabled, and that the server will respond with a tagged NO - response to any attempt to use the LOGIN command even if the user - name and password are valid. An IMAP client MUST NOT issue the - LOGIN command if the server advertises the LOGINDISABLED - capability. - - Other capability names indicate that the server supports an - extension, revision, or amendment to the IMAP4rev1 protocol. - Server responses MUST conform to this document until the client - issues a command that uses the associated capability. - - Capability names MUST either begin with "X" or be standard or - standards-track IMAP4rev1 extensions, revisions, or amendments - registered with IANA. A server MUST NOT offer unregistered or - - - -Crispin Standards Track [Page 68] - -RFC 3501 IMAPv4 March 2003 - - - non-standard capability names, unless such names are prefixed with - an "X". - - Client implementations SHOULD NOT require any capability name - other than "IMAP4rev1", and MUST ignore any unknown capability - names. - - A server MAY send capabilities automatically, by using the - CAPABILITY response code in the initial PREAUTH or OK responses, - and by sending an updated CAPABILITY response code in the tagged - OK response as part of a successful authentication. It is - unnecessary for a client to send a separate CAPABILITY command if - it recognizes these automatic capabilities. - - Example: S: * CAPABILITY IMAP4rev1 STARTTLS AUTH=GSSAPI XPIG-LATIN - - -7.2.2. LIST Response - - Contents: name attributes - hierarchy delimiter - name - - The LIST response occurs as a result of a LIST command. It - returns a single name that matches the LIST specification. There - can be multiple LIST responses for a single LIST command. - - Four name attributes are defined: - - \Noinferiors - It is not possible for any child levels of hierarchy to exist - under this name; no child levels exist now and none can be - created in the future. - - \Noselect - It is not possible to use this name as a selectable mailbox. - - \Marked - The mailbox has been marked "interesting" by the server; the - mailbox probably contains messages that have been added since - the last time the mailbox was selected. - - \Unmarked - The mailbox does not contain any additional messages since the - last time the mailbox was selected. - - - - - - -Crispin Standards Track [Page 69] - -RFC 3501 IMAPv4 March 2003 - - - If it is not feasible for the server to determine whether or not - the mailbox is "interesting", or if the name is a \Noselect name, - the server SHOULD NOT send either \Marked or \Unmarked. - - The hierarchy delimiter is a character used to delimit levels of - hierarchy in a mailbox name. A client can use it to create child - mailboxes, and to search higher or lower levels of naming - hierarchy. All children of a top-level hierarchy node MUST use - the same separator character. A NIL hierarchy delimiter means - that no hierarchy exists; the name is a "flat" name. - - The name represents an unambiguous left-to-right hierarchy, and - MUST be valid for use as a reference in LIST and LSUB commands. - Unless \Noselect is indicated, the name MUST also be valid as an - argument for commands, such as SELECT, that accept mailbox names. - - Example: S: * LIST (\Noselect) "/" ~/Mail/foo - - -7.2.3. LSUB Response - - Contents: name attributes - hierarchy delimiter - name - - The LSUB response occurs as a result of an LSUB command. It - returns a single name that matches the LSUB specification. There - can be multiple LSUB responses for a single LSUB command. The - data is identical in format to the LIST response. - - Example: S: * LSUB () "." #news.comp.mail.misc - - -7.2.4 STATUS Response - - Contents: name - status parenthesized list - - The STATUS response occurs as a result of an STATUS command. It - returns the mailbox name that matches the STATUS specification and - the requested mailbox status information. - - Example: S: * STATUS blurdybloop (MESSAGES 231 UIDNEXT 44292) - - - - - - - - -Crispin Standards Track [Page 70] - -RFC 3501 IMAPv4 March 2003 - - -7.2.5. SEARCH Response - - Contents: zero or more numbers - - The SEARCH response occurs as a result of a SEARCH or UID SEARCH - command. The number(s) refer to those messages that match the - search criteria. For SEARCH, these are message sequence numbers; - for UID SEARCH, these are unique identifiers. Each number is - delimited by a space. - - Example: S: * SEARCH 2 3 6 - - -7.2.6. FLAGS Response - - Contents: flag parenthesized list - - The FLAGS response occurs as a result of a SELECT or EXAMINE - command. The flag parenthesized list identifies the flags (at a - minimum, the system-defined flags) that are applicable for this - mailbox. Flags other than the system flags can also exist, - depending on server implementation. - - The update from the FLAGS response MUST be recorded by the client. - - Example: S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) - - -7.3. Server Responses - Mailbox Size - - These responses are always untagged. This is how changes in the size - of the mailbox are transmitted from the server to the client. - Immediately following the "*" token is a number that represents a - message count. - -7.3.1. EXISTS Response - - Contents: none - - The EXISTS response reports the number of messages in the mailbox. - This response occurs as a result of a SELECT or EXAMINE command, - and if the size of the mailbox changes (e.g., new messages). - - The update from the EXISTS response MUST be recorded by the - client. - - Example: S: * 23 EXISTS - - - - -Crispin Standards Track [Page 71] - -RFC 3501 IMAPv4 March 2003 - - -7.3.2. RECENT Response - - Contents: none - - The RECENT response reports the number of messages with the - \Recent flag set. This response occurs as a result of a SELECT or - EXAMINE command, and if the size of the mailbox changes (e.g., new - messages). - - Note: It is not guaranteed that the message sequence - numbers of recent messages will be a contiguous range of - the highest n messages in the mailbox (where n is the - value reported by the RECENT response). Examples of - situations in which this is not the case are: multiple - clients having the same mailbox open (the first session - to be notified will see it as recent, others will - probably see it as non-recent), and when the mailbox is - re-ordered by a non-IMAP agent. - - The only reliable way to identify recent messages is to - look at message flags to see which have the \Recent flag - set, or to do a SEARCH RECENT. - - The update from the RECENT response MUST be recorded by the - client. - - Example: S: * 5 RECENT - - -7.4. Server Responses - Message Status - - These responses are always untagged. This is how message data are - transmitted from the server to the client, often as a result of a - command with the same name. Immediately following the "*" token is a - number that represents a message sequence number. - -7.4.1. EXPUNGE Response - - Contents: none - - The EXPUNGE response reports that the specified message sequence - number has been permanently removed from the mailbox. The message - sequence number for each successive message in the mailbox is - immediately decremented by 1, and this decrement is reflected in - message sequence numbers in subsequent responses (including other - untagged EXPUNGE responses). - - - - - -Crispin Standards Track [Page 72] - -RFC 3501 IMAPv4 March 2003 - - - The EXPUNGE response also decrements the number of messages in the - mailbox; it is not necessary to send an EXISTS response with the - new value. - - As a result of the immediate decrement rule, message sequence - numbers that appear in a set of successive EXPUNGE responses - depend upon whether the messages are removed starting from lower - numbers to higher numbers, or from higher numbers to lower - numbers. For example, if the last 5 messages in a 9-message - mailbox are expunged, a "lower to higher" server will send five - untagged EXPUNGE responses for message sequence number 5, whereas - a "higher to lower server" will send successive untagged EXPUNGE - responses for message sequence numbers 9, 8, 7, 6, and 5. - - An EXPUNGE 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. An EXPUNGE - response MAY be sent during a UID command. - - The update from the EXPUNGE response MUST be recorded by the - client. - - Example: S: * 44 EXPUNGE - - -7.4.2. FETCH Response - - Contents: message data - - The FETCH response returns data about a message to the client. - The data are pairs of data item names and their values in - parentheses. This response occurs as the result of a FETCH or - STORE command, as well as by unilateral server decision (e.g., - flag updates). - - The current data items are: - - BODY - A form of BODYSTRUCTURE without extension data. - - - - - -Crispin Standards Track [Page 73] - -RFC 3501 IMAPv4 March 2003 - - - BODY[<section>]<<origin octet>> - A string expressing the body contents of the specified section. - The string SHOULD be interpreted by the client according to the - content transfer encoding, body type, and subtype. - - If the origin octet is specified, this string is a substring of - the entire body contents, starting at that origin octet. This - means that BODY[]<0> MAY be truncated, but BODY[] is NEVER - truncated. - - Note: The origin octet facility MUST NOT be used by a server - in a FETCH response unless the client specifically requested - it by means of a FETCH of a BODY[<section>]<<partial>> data - item. - - 8-bit textual data is permitted if a [CHARSET] identifier is - part of the body parameter parenthesized list for this section. - Note that headers (part specifiers HEADER or MIME, or the - header portion of a MESSAGE/RFC822 part), MUST be 7-bit; 8-bit - characters are not permitted in headers. Note also that the - [RFC-2822] delimiting blank line between the header and the - body is not affected by header line subsetting; the blank line - is always included as part of header data, except in the case - of a message which has no body and no blank line. - - Non-textual data such as binary data MUST be transfer encoded - into a textual form, such as BASE64, prior to being sent to the - client. To derive the original binary data, the client MUST - decode the transfer encoded string. - - BODYSTRUCTURE - A parenthesized list that describes the [MIME-IMB] body - structure of a message. This is computed by the server by - parsing the [MIME-IMB] header fields, defaulting various fields - as necessary. - - For example, a simple text message of 48 lines and 2279 octets - can have a body structure of: ("TEXT" "PLAIN" ("CHARSET" - "US-ASCII") NIL NIL "7BIT" 2279 48) - - Multiple parts are indicated by parenthesis nesting. Instead - of a body type as the first element of the parenthesized list, - there is a sequence of one or more nested body structures. The - second element of the parenthesized list is the multipart - subtype (mixed, digest, parallel, alternative, etc.). - - - - - - -Crispin Standards Track [Page 74] - -RFC 3501 IMAPv4 March 2003 - - - For example, a two part message consisting of a text and a - BASE64-encoded text attachment can have a body structure of: - (("TEXT" "PLAIN" ("CHARSET" "US-ASCII") NIL NIL "7BIT" 1152 - 23)("TEXT" "PLAIN" ("CHARSET" "US-ASCII" "NAME" "cc.diff") - "<960723163407.20117h@cac.washington.edu>" "Compiler diff" - "BASE64" 4554 73) "MIXED") - - Extension data follows the multipart subtype. Extension data - is never returned with the BODY fetch, but can be returned with - a BODYSTRUCTURE fetch. Extension data, if present, MUST be in - the defined order. The extension data of a multipart body part - are in the following order: - - body parameter parenthesized list - A parenthesized list of attribute/value pairs [e.g., ("foo" - "bar" "baz" "rag") where "bar" is the value of "foo", and - "rag" is the value of "baz"] as defined in [MIME-IMB]. - - body disposition - A parenthesized list, consisting of a disposition type - string, followed by a parenthesized list of disposition - attribute/value pairs as defined in [DISPOSITION]. - - body language - A string or parenthesized list giving the body language - value as defined in [LANGUAGE-TAGS]. - - body location - A string list giving the body content URI as defined in - [LOCATION]. - - Any following extension data are not yet defined in this - version of the protocol. Such extension data can consist of - zero or more NILs, strings, numbers, or potentially nested - parenthesized lists of such data. Client implementations that - do a BODYSTRUCTURE fetch MUST be prepared to accept such - extension data. Server implementations MUST NOT send such - extension data until it has been defined by a revision of this - protocol. - - The basic fields of a non-multipart body part are in the - following order: - - body type - A string giving the content media type name as defined in - [MIME-IMB]. - - - - - -Crispin Standards Track [Page 75] - -RFC 3501 IMAPv4 March 2003 - - - body subtype - A string giving the content subtype name as defined in - [MIME-IMB]. - - body parameter parenthesized list - A parenthesized list of attribute/value pairs [e.g., ("foo" - "bar" "baz" "rag") where "bar" is the value of "foo" and - "rag" is the value of "baz"] as defined in [MIME-IMB]. - - body id - A string giving the content id as defined in [MIME-IMB]. - - body description - A string giving the content description as defined in - [MIME-IMB]. - - body encoding - A string giving the content transfer encoding as defined in - [MIME-IMB]. - - body size - A number giving the size of the body in octets. Note that - this size is the size in its transfer encoding and not the - resulting size after any decoding. - - A body type of type MESSAGE and subtype RFC822 contains, - immediately after the basic fields, the envelope structure, - body structure, and size in text lines of the encapsulated - message. - - A body type of type TEXT contains, immediately after the basic - fields, the size of the body in text lines. Note that this - size is the size in its content transfer encoding and not the - resulting size after any decoding. - - Extension data follows the basic fields and the type-specific - fields listed above. Extension data is never returned with the - BODY fetch, but can be returned with a BODYSTRUCTURE fetch. - Extension data, if present, MUST be in the defined order. - - The extension data of a non-multipart body part are in the - following order: - - body MD5 - A string giving the body MD5 value as defined in [MD5]. - - - - - - -Crispin Standards Track [Page 76] - -RFC 3501 IMAPv4 March 2003 - - - body disposition - A parenthesized list with the same content and function as - the body disposition for a multipart body part. - - body language - A string or parenthesized list giving the body language - value as defined in [LANGUAGE-TAGS]. - - body location - A string list giving the body content URI as defined in - [LOCATION]. - - Any following extension data are not yet defined in this - version of the protocol, and would be as described above under - multipart extension data. - - ENVELOPE - A parenthesized list that describes the envelope structure of a - message. This is computed by the server by parsing the - [RFC-2822] header into the component parts, defaulting various - fields as necessary. - - The fields of the envelope structure are in the following - order: date, subject, from, sender, reply-to, to, cc, bcc, - in-reply-to, and message-id. The date, subject, in-reply-to, - and message-id fields are strings. The from, sender, reply-to, - to, cc, and bcc fields are parenthesized lists of address - structures. - - An address structure is a parenthesized list that describes an - electronic mail address. The fields of an address structure - are in the following order: personal name, [SMTP] - at-domain-list (source route), mailbox name, and host name. - - [RFC-2822] group syntax is indicated by a special form of - address structure in which the host name field is NIL. If the - mailbox name field is also NIL, this is an end of group marker - (semi-colon in RFC 822 syntax). If the mailbox name field is - non-NIL, this is a start of group marker, and the mailbox name - field holds the group name phrase. - - If the Date, Subject, In-Reply-To, and Message-ID header lines - are absent in the [RFC-2822] header, the corresponding member - of the envelope is NIL; if these header lines are present but - empty the corresponding member of the envelope is the empty - string. - - - - - -Crispin Standards Track [Page 77] - -RFC 3501 IMAPv4 March 2003 - - - Note: some servers may return a NIL envelope member in the - "present but empty" case. Clients SHOULD treat NIL and - empty string as identical. - - Note: [RFC-2822] requires that all messages have a valid - Date header. Therefore, the date member in the envelope can - not be NIL or the empty string. - - Note: [RFC-2822] requires that the In-Reply-To and - Message-ID headers, if present, have non-empty content. - Therefore, the in-reply-to and message-id members in the - envelope can not be the empty string. - - If the From, To, cc, and bcc header lines are absent in the - [RFC-2822] header, or are present but empty, the corresponding - member of the envelope is NIL. - - If the Sender or Reply-To lines are absent in the [RFC-2822] - header, or are present but empty, the server sets the - corresponding member of the envelope to be the same value as - the from member (the client is not expected to know to do - this). - - Note: [RFC-2822] requires that all messages have a valid - From header. Therefore, the from, sender, and reply-to - members in the envelope can not be NIL. - - FLAGS - A parenthesized list of flags that are set for this message. - - INTERNALDATE - A string representing the internal date of the message. - - RFC822 - Equivalent to BODY[]. - - RFC822.HEADER - Equivalent to BODY[HEADER]. Note that this did not result in - \Seen being set, because RFC822.HEADER response data occurs as - a result of a FETCH of RFC822.HEADER. BODY[HEADER] response - data occurs as a result of a FETCH of BODY[HEADER] (which sets - \Seen) or BODY.PEEK[HEADER] (which does not set \Seen). - - RFC822.SIZE - A number expressing the [RFC-2822] size of the message. - - - - - - -Crispin Standards Track [Page 78] - -RFC 3501 IMAPv4 March 2003 - - - RFC822.TEXT - Equivalent to BODY[TEXT]. - - UID - A number expressing the unique identifier of the message. - - - Example: S: * 23 FETCH (FLAGS (\Seen) RFC822.SIZE 44827) - - -7.5. Server Responses - Command Continuation Request - - The command continuation request response is indicated by a "+" token - instead of a tag. This form of response indicates that the server is - ready to accept the continuation of a command from the client. The - remainder of this response is a line of text. - - This response is used in the AUTHENTICATE command to transmit server - data to the client, and request additional client data. This - response is also used if an argument to any command is a literal. - - The client is not permitted to send the octets of the literal unless - the server indicates that it is expected. This permits the server to - process commands and reject errors on a line-by-line basis. The - remainder of the command, including the CRLF that terminates a - command, follows the octets of the literal. If there are any - additional command arguments, the literal octets are followed by a - space and those arguments. - - Example: C: A001 LOGIN {11} - S: + Ready for additional command text - C: FRED FOOBAR {7} - S: + Ready for additional command text - C: fat man - S: A001 OK LOGIN completed - C: A044 BLURDYBLOOP {102856} - S: A044 BAD No such command as "BLURDYBLOOP" - - - - - - - - - - - - - - -Crispin Standards Track [Page 79] - -RFC 3501 IMAPv4 March 2003 - - -8. Sample IMAP4rev1 connection - - The following is a transcript of an IMAP4rev1 connection. A long - line in this sample is broken for editorial clarity. - -S: * OK IMAP4rev1 Service Ready -C: a001 login mrc secret -S: a001 OK LOGIN completed -C: a002 select inbox -S: * 18 EXISTS -S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) -S: * 2 RECENT -S: * OK [UNSEEN 17] Message 17 is the first unseen message -S: * OK [UIDVALIDITY 3857529045] UIDs valid -S: a002 OK [READ-WRITE] SELECT completed -C: a003 fetch 12 full -S: * 12 FETCH (FLAGS (\Seen) INTERNALDATE "17-Jul-1996 02:44:25 -0700" - RFC822.SIZE 4286 ENVELOPE ("Wed, 17 Jul 1996 02:23:25 -0700 (PDT)" - "IMAP4rev1 WG mtg summary and minutes" - (("Terry Gray" NIL "gray" "cac.washington.edu")) - (("Terry Gray" NIL "gray" "cac.washington.edu")) - (("Terry Gray" NIL "gray" "cac.washington.edu")) - ((NIL NIL "imap" "cac.washington.edu")) - ((NIL NIL "minutes" "CNRI.Reston.VA.US") - ("John Klensin" NIL "KLENSIN" "MIT.EDU")) NIL NIL - "<B27397-0100000@cac.washington.edu>") - BODY ("TEXT" "PLAIN" ("CHARSET" "US-ASCII") NIL NIL "7BIT" 3028 - 92)) -S: a003 OK FETCH completed -C: a004 fetch 12 body[header] -S: * 12 FETCH (BODY[HEADER] {342} -S: Date: Wed, 17 Jul 1996 02:23:25 -0700 (PDT) -S: From: Terry Gray <gray@cac.washington.edu> -S: Subject: IMAP4rev1 WG mtg summary and minutes -S: To: imap@cac.washington.edu -S: cc: minutes@CNRI.Reston.VA.US, John Klensin <KLENSIN@MIT.EDU> -S: Message-Id: <B27397-0100000@cac.washington.edu> -S: MIME-Version: 1.0 -S: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII -S: -S: ) -S: a004 OK FETCH completed -C: a005 store 12 +flags \deleted -S: * 12 FETCH (FLAGS (\Seen \Deleted)) -S: a005 OK +FLAGS completed -C: a006 logout -S: * BYE IMAP4rev1 server terminating connection -S: a006 OK LOGOUT completed - - - -Crispin Standards Track [Page 80] - -RFC 3501 IMAPv4 March 2003 - - -9. Formal Syntax - - The following syntax specification uses the Augmented Backus-Naur - Form (ABNF) notation as specified in [ABNF]. - - In the case of alternative or optional rules in which a later rule - overlaps an earlier rule, the rule which is listed earlier MUST take - priority. For example, "\Seen" when parsed as a flag is the \Seen - flag name and not a flag-extension, even though "\Seen" can be parsed - as a flag-extension. Some, but not all, instances of this rule are - noted below. - - Note: [ABNF] rules MUST be followed strictly; in - particular: - - (1) 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. - - (2) In all cases, SP refers to exactly one space. It is - NOT permitted to substitute TAB, insert additional spaces, - or otherwise treat SP as being equivalent to LWSP. - - (3) The ASCII NUL character, %x00, MUST NOT be used at any - time. - -address = "(" addr-name SP addr-adl SP addr-mailbox SP - addr-host ")" - -addr-adl = nstring - ; Holds route from [RFC-2822] route-addr if - ; non-NIL - -addr-host = nstring - ; NIL indicates [RFC-2822] group syntax. - ; Otherwise, holds [RFC-2822] domain name - -addr-mailbox = nstring - ; NIL indicates end of [RFC-2822] group; if - ; non-NIL and addr-host is NIL, holds - ; [RFC-2822] group name. - ; Otherwise, holds [RFC-2822] local-part - ; after removing [RFC-2822] quoting - - - - - - -Crispin Standards Track [Page 81] - -RFC 3501 IMAPv4 March 2003 - - -addr-name = nstring - ; If non-NIL, holds phrase from [RFC-2822] - ; mailbox after removing [RFC-2822] quoting - -append = "APPEND" SP mailbox [SP flag-list] [SP date-time] SP - literal - -astring = 1*ASTRING-CHAR / string - -ASTRING-CHAR = ATOM-CHAR / resp-specials - -atom = 1*ATOM-CHAR - -ATOM-CHAR = <any CHAR except atom-specials> - -atom-specials = "(" / ")" / "{" / SP / CTL / list-wildcards / - quoted-specials / resp-specials - -authenticate = "AUTHENTICATE" SP auth-type *(CRLF base64) - -auth-type = atom - ; Defined by [SASL] - -base64 = *(4base64-char) [base64-terminal] - -base64-char = ALPHA / DIGIT / "+" / "/" - ; Case-sensitive - -base64-terminal = (2base64-char "==") / (3base64-char "=") - -body = "(" (body-type-1part / body-type-mpart) ")" - -body-extension = nstring / number / - "(" body-extension *(SP body-extension) ")" - ; Future expansion. Client implementations - ; MUST accept body-extension fields. Server - ; implementations MUST NOT generate - ; body-extension fields except as defined by - ; future standard or standards-track - ; revisions of this specification. - -body-ext-1part = body-fld-md5 [SP body-fld-dsp [SP body-fld-lang - [SP body-fld-loc *(SP body-extension)]]] - ; MUST NOT be returned on non-extensible - ; "BODY" fetch - - - - - - -Crispin Standards Track [Page 82] - -RFC 3501 IMAPv4 March 2003 - - -body-ext-mpart = body-fld-param [SP body-fld-dsp [SP body-fld-lang - [SP body-fld-loc *(SP body-extension)]]] - ; MUST NOT be returned on non-extensible - ; "BODY" fetch - -body-fields = body-fld-param SP body-fld-id SP body-fld-desc SP - body-fld-enc SP body-fld-octets - -body-fld-desc = nstring - -body-fld-dsp = "(" string SP body-fld-param ")" / nil - -body-fld-enc = (DQUOTE ("7BIT" / "8BIT" / "BINARY" / "BASE64"/ - "QUOTED-PRINTABLE") DQUOTE) / string - -body-fld-id = nstring - -body-fld-lang = nstring / "(" string *(SP string) ")" - -body-fld-loc = nstring - -body-fld-lines = number - -body-fld-md5 = nstring - -body-fld-octets = number - -body-fld-param = "(" string SP string *(SP string SP string) ")" / nil - -body-type-1part = (body-type-basic / body-type-msg / body-type-text) - [SP body-ext-1part] - -body-type-basic = media-basic SP body-fields - ; MESSAGE subtype MUST NOT be "RFC822" - -body-type-mpart = 1*body SP media-subtype - [SP body-ext-mpart] - -body-type-msg = media-message SP body-fields SP envelope - SP body SP body-fld-lines - -body-type-text = media-text SP body-fields SP body-fld-lines - -capability = ("AUTH=" auth-type) / atom - ; New capabilities MUST begin with "X" or be - ; registered with IANA as standard or - ; standards-track - - - - -Crispin Standards Track [Page 83] - -RFC 3501 IMAPv4 March 2003 - - -capability-data = "CAPABILITY" *(SP capability) SP "IMAP4rev1" - *(SP capability) - ; Servers MUST implement the STARTTLS, AUTH=PLAIN, - ; and LOGINDISABLED capabilities - ; Servers which offer RFC 1730 compatibility MUST - ; list "IMAP4" as the first capability. - -CHAR8 = %x01-ff - ; any OCTET except NUL, %x00 - -command = tag SP (command-any / command-auth / command-nonauth / - command-select) CRLF - ; Modal based on state - -command-any = "CAPABILITY" / "LOGOUT" / "NOOP" / x-command - ; Valid in all states - -command-auth = append / create / delete / examine / list / lsub / - rename / select / status / subscribe / unsubscribe - ; Valid only in Authenticated or Selected state - -command-nonauth = login / authenticate / "STARTTLS" - ; Valid only when in Not Authenticated state - -command-select = "CHECK" / "CLOSE" / "EXPUNGE" / copy / fetch / store / - uid / search - ; Valid only when in Selected state - -continue-req = "+" SP (resp-text / base64) CRLF - -copy = "COPY" SP sequence-set SP mailbox - -create = "CREATE" SP mailbox - ; Use of INBOX gives a NO error - -date = date-text / DQUOTE date-text DQUOTE - -date-day = 1*2DIGIT - ; Day of month - -date-day-fixed = (SP DIGIT) / 2DIGIT - ; Fixed-format version of date-day - -date-month = "Jan" / "Feb" / "Mar" / "Apr" / "May" / "Jun" / - "Jul" / "Aug" / "Sep" / "Oct" / "Nov" / "Dec" - -date-text = date-day "-" date-month "-" date-year - - - - -Crispin Standards Track [Page 84] - -RFC 3501 IMAPv4 March 2003 - - -date-year = 4DIGIT - -date-time = DQUOTE date-day-fixed "-" date-month "-" date-year - SP time SP zone DQUOTE - -delete = "DELETE" SP mailbox - ; Use of INBOX gives a NO error - -digit-nz = %x31-39 - ; 1-9 - -envelope = "(" env-date SP env-subject SP env-from SP - env-sender SP env-reply-to SP env-to SP env-cc SP - env-bcc SP env-in-reply-to SP env-message-id ")" - -env-bcc = "(" 1*address ")" / nil - -env-cc = "(" 1*address ")" / nil - -env-date = nstring - -env-from = "(" 1*address ")" / nil - -env-in-reply-to = nstring - -env-message-id = nstring - -env-reply-to = "(" 1*address ")" / nil - -env-sender = "(" 1*address ")" / nil - -env-subject = nstring - -env-to = "(" 1*address ")" / nil - -examine = "EXAMINE" SP mailbox - -fetch = "FETCH" SP sequence-set SP ("ALL" / "FULL" / "FAST" / - fetch-att / "(" fetch-att *(SP fetch-att) ")") - -fetch-att = "ENVELOPE" / "FLAGS" / "INTERNALDATE" / - "RFC822" [".HEADER" / ".SIZE" / ".TEXT"] / - "BODY" ["STRUCTURE"] / "UID" / - "BODY" section ["<" number "." nz-number ">"] / - "BODY.PEEK" section ["<" number "." nz-number ">"] - - - - - - -Crispin Standards Track [Page 85] - -RFC 3501 IMAPv4 March 2003 - - -flag = "\Answered" / "\Flagged" / "\Deleted" / - "\Seen" / "\Draft" / flag-keyword / flag-extension - ; Does not include "\Recent" - -flag-extension = "\" atom - ; Future expansion. Client implementations - ; MUST accept flag-extension flags. Server - ; implementations MUST NOT generate - ; flag-extension flags except as defined by - ; future standard or standards-track - ; revisions of this specification. - -flag-fetch = flag / "\Recent" - -flag-keyword = atom - -flag-list = "(" [flag *(SP flag)] ")" - -flag-perm = flag / "\*" - -greeting = "*" SP (resp-cond-auth / resp-cond-bye) CRLF - -header-fld-name = astring - -header-list = "(" header-fld-name *(SP header-fld-name) ")" - -list = "LIST" SP mailbox SP list-mailbox - -list-mailbox = 1*list-char / string - -list-char = ATOM-CHAR / list-wildcards / resp-specials - -list-wildcards = "%" / "*" - -literal = "{" number "}" CRLF *CHAR8 - ; Number represents the number of CHAR8s - -login = "LOGIN" SP userid SP password - -lsub = "LSUB" SP mailbox SP list-mailbox - - - - - - - - - - - -Crispin Standards Track [Page 86] - -RFC 3501 IMAPv4 March 2003 - - -mailbox = "INBOX" / astring - ; INBOX is case-insensitive. All case variants of - ; INBOX (e.g., "iNbOx") MUST be interpreted as INBOX - ; not as an astring. An astring which consists of - ; the case-insensitive sequence "I" "N" "B" "O" "X" - ; is considered to be INBOX and not an astring. - ; Refer to section 5.1 for further - ; semantic details of mailbox names. - -mailbox-data = "FLAGS" SP flag-list / "LIST" SP mailbox-list / - "LSUB" SP mailbox-list / "SEARCH" *(SP nz-number) / - "STATUS" SP mailbox SP "(" [status-att-list] ")" / - number SP "EXISTS" / number SP "RECENT" - -mailbox-list = "(" [mbx-list-flags] ")" SP - (DQUOTE QUOTED-CHAR DQUOTE / nil) SP mailbox - -mbx-list-flags = *(mbx-list-oflag SP) mbx-list-sflag - *(SP mbx-list-oflag) / - mbx-list-oflag *(SP mbx-list-oflag) - -mbx-list-oflag = "\Noinferiors" / flag-extension - ; Other flags; multiple possible per LIST response - -mbx-list-sflag = "\Noselect" / "\Marked" / "\Unmarked" - ; Selectability flags; only one per LIST response - -media-basic = ((DQUOTE ("APPLICATION" / "AUDIO" / "IMAGE" / - "MESSAGE" / "VIDEO") DQUOTE) / string) SP - media-subtype - ; Defined in [MIME-IMT] - -media-message = DQUOTE "MESSAGE" DQUOTE SP DQUOTE "RFC822" DQUOTE - ; Defined in [MIME-IMT] - -media-subtype = string - ; Defined in [MIME-IMT] - -media-text = DQUOTE "TEXT" DQUOTE SP media-subtype - ; Defined in [MIME-IMT] - -message-data = nz-number SP ("EXPUNGE" / ("FETCH" SP msg-att)) - -msg-att = "(" (msg-att-dynamic / msg-att-static) - *(SP (msg-att-dynamic / msg-att-static)) ")" - -msg-att-dynamic = "FLAGS" SP "(" [flag-fetch *(SP flag-fetch)] ")" - ; MAY change for a message - - - -Crispin Standards Track [Page 87] - -RFC 3501 IMAPv4 March 2003 - - -msg-att-static = "ENVELOPE" SP envelope / "INTERNALDATE" SP date-time / - "RFC822" [".HEADER" / ".TEXT"] SP nstring / - "RFC822.SIZE" SP number / - "BODY" ["STRUCTURE"] SP body / - "BODY" section ["<" number ">"] SP nstring / - "UID" SP uniqueid - ; MUST NOT change for a message - -nil = "NIL" - -nstring = string / nil - -number = 1*DIGIT - ; Unsigned 32-bit integer - ; (0 <= n < 4,294,967,296) - -nz-number = digit-nz *DIGIT - ; Non-zero unsigned 32-bit integer - ; (0 < n < 4,294,967,296) - -password = astring - -quoted = DQUOTE *QUOTED-CHAR DQUOTE - -QUOTED-CHAR = <any TEXT-CHAR except quoted-specials> / - "\" quoted-specials - -quoted-specials = DQUOTE / "\" - -rename = "RENAME" SP mailbox SP mailbox - ; Use of INBOX as a destination gives a NO error - -response = *(continue-req / response-data) response-done - -response-data = "*" SP (resp-cond-state / resp-cond-bye / - mailbox-data / message-data / capability-data) CRLF - -response-done = response-tagged / response-fatal - -response-fatal = "*" SP resp-cond-bye CRLF - ; Server closes connection immediately - -response-tagged = tag SP resp-cond-state CRLF - -resp-cond-auth = ("OK" / "PREAUTH") SP resp-text - ; Authentication condition - - - - - -Crispin Standards Track [Page 88] - -RFC 3501 IMAPv4 March 2003 - - -resp-cond-bye = "BYE" SP resp-text - -resp-cond-state = ("OK" / "NO" / "BAD") SP resp-text - ; Status condition - -resp-specials = "]" - -resp-text = ["[" resp-text-code "]" SP] text - -resp-text-code = "ALERT" / - "BADCHARSET" [SP "(" astring *(SP astring) ")" ] / - capability-data / "PARSE" / - "PERMANENTFLAGS" SP "(" - [flag-perm *(SP flag-perm)] ")" / - "READ-ONLY" / "READ-WRITE" / "TRYCREATE" / - "UIDNEXT" SP nz-number / "UIDVALIDITY" SP nz-number / - "UNSEEN" SP nz-number / - atom [SP 1*<any TEXT-CHAR except "]">] - -search = "SEARCH" [SP "CHARSET" SP astring] 1*(SP search-key) - ; CHARSET argument to MUST be registered with IANA - -search-key = "ALL" / "ANSWERED" / "BCC" SP astring / - "BEFORE" SP date / "BODY" SP astring / - "CC" SP astring / "DELETED" / "FLAGGED" / - "FROM" SP astring / "KEYWORD" SP flag-keyword / - "NEW" / "OLD" / "ON" SP date / "RECENT" / "SEEN" / - "SINCE" SP date / "SUBJECT" SP astring / - "TEXT" SP astring / "TO" SP astring / - "UNANSWERED" / "UNDELETED" / "UNFLAGGED" / - "UNKEYWORD" SP flag-keyword / "UNSEEN" / - ; Above this line were in [IMAP2] - "DRAFT" / "HEADER" SP header-fld-name SP astring / - "LARGER" SP number / "NOT" SP search-key / - "OR" SP search-key SP search-key / - "SENTBEFORE" SP date / "SENTON" SP date / - "SENTSINCE" SP date / "SMALLER" SP number / - "UID" SP sequence-set / "UNDRAFT" / sequence-set / - "(" search-key *(SP search-key) ")" - -section = "[" [section-spec] "]" - -section-msgtext = "HEADER" / "HEADER.FIELDS" [".NOT"] SP header-list / - "TEXT" - ; top-level or MESSAGE/RFC822 part - -section-part = nz-number *("." nz-number) - ; body part nesting - - - -Crispin Standards Track [Page 89] - -RFC 3501 IMAPv4 March 2003 - - -section-spec = section-msgtext / (section-part ["." section-text]) - -section-text = section-msgtext / "MIME" - ; text other than actual body part (headers, etc.) - -select = "SELECT" SP mailbox - -seq-number = nz-number / "*" - ; message sequence number (COPY, FETCH, STORE - ; commands) or unique identifier (UID COPY, - ; UID FETCH, UID STORE commands). - ; * represents the largest number in use. In - ; the case of message sequence numbers, it is - ; the number of messages in a non-empty mailbox. - ; In the case of unique identifiers, it is the - ; unique identifier of the last message in the - ; mailbox or, if the mailbox is empty, the - ; mailbox's current UIDNEXT value. - ; The server should respond with a tagged BAD - ; response to a command that uses a message - ; sequence number greater than the number of - ; messages in the selected mailbox. This - ; includes "*" if the selected mailbox is empty. - -seq-range = seq-number ":" seq-number - ; two seq-number values and all values between - ; these two regardless of order. - ; Example: 2:4 and 4:2 are equivalent and indicate - ; values 2, 3, and 4. - ; Example: a unique identifer sequence range of - ; 3291:* includes the UID of the last message in - ; the mailbox, even if that value is less than 3291. - -sequence-set = (seq-number / seq-range) *("," sequence-set) - ; set of seq-number values, regardless of order. - ; Servers MAY coalesce overlaps and/or execute the - ; sequence in any order. - ; Example: a message sequence number set of - ; 2,4:7,9,12:* for a mailbox with 15 messages is - ; equivalent to 2,4,5,6,7,9,12,13,14,15 - ; Example: a message sequence number set of *:4,5:7 - ; for a mailbox with 10 messages is equivalent to - ; 10,9,8,7,6,5,4,5,6,7 and MAY be reordered and - ; overlap coalesced to be 4,5,6,7,8,9,10. - -status = "STATUS" SP mailbox SP - "(" status-att *(SP status-att) ")" - - - - -Crispin Standards Track [Page 90] - -RFC 3501 IMAPv4 March 2003 - - -status-att = "MESSAGES" / "RECENT" / "UIDNEXT" / "UIDVALIDITY" / - "UNSEEN" - -status-att-list = status-att SP number *(SP status-att SP number) - -store = "STORE" SP sequence-set SP store-att-flags - -store-att-flags = (["+" / "-"] "FLAGS" [".SILENT"]) SP - (flag-list / (flag *(SP flag))) - -string = quoted / literal - -subscribe = "SUBSCRIBE" SP mailbox - -tag = 1*<any ASTRING-CHAR except "+"> - -text = 1*TEXT-CHAR - -TEXT-CHAR = <any CHAR except CR and LF> - -time = 2DIGIT ":" 2DIGIT ":" 2DIGIT - ; Hours minutes seconds - -uid = "UID" SP (copy / fetch / search / store) - ; Unique identifiers used instead of message - ; sequence numbers - -uniqueid = nz-number - ; Strictly ascending - -unsubscribe = "UNSUBSCRIBE" SP mailbox - -userid = astring - -x-command = "X" atom <experimental command arguments> - -zone = ("+" / "-") 4DIGIT - ; Signed four-digit value of hhmm representing - ; hours and minutes east of Greenwich (that is, - ; the amount that the given time differs from - ; Universal Time). Subtracting the timezone - ; from the given time will give the UT form. - ; The Universal Time zone is "+0000". - - - - - - - - -Crispin Standards Track [Page 91] - -RFC 3501 IMAPv4 March 2003 - - -10. Author's Note - - This document is a revision or rewrite of earlier documents, and - supercedes the protocol specification in those documents: RFC 2060, - RFC 1730, unpublished IMAP2bis.TXT document, RFC 1176, and RFC 1064. - -11. Security Considerations - - IMAP4rev1 protocol transactions, including electronic mail data, are - sent in the clear over the network unless protection from snooping is - negotiated. This can be accomplished either by the use of STARTTLS, - negotiated privacy protection in the AUTHENTICATE command, or some - other protection mechanism. - -11.1. STARTTLS Security Considerations - - The specification of the STARTTLS command and LOGINDISABLED - capability in this document replaces that in [IMAP-TLS]. [IMAP-TLS] - remains normative for the PLAIN [SASL] authenticator. - - IMAP client and server implementations MUST implement the - TLS_RSA_WITH_RC4_128_MD5 [TLS] cipher suite, and SHOULD implement the - TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA [TLS] cipher suite. This is - important as it assures that any two compliant implementations can be - configured to interoperate. All other cipher suites are OPTIONAL. - Note that this is a change from section 2.1 of [IMAP-TLS]. - - During the [TLS] negotiation, the client MUST check its understanding - of the server hostname against the server's identity as presented in - the server Certificate message, in order to prevent man-in-the-middle - attacks. If the match fails, the client SHOULD either ask for - explicit user confirmation, or terminate the connection and indicate - that the server's identity is suspect. Matching is performed - according to these rules: - - The client MUST use the server hostname it used to open the - connection as the value to compare against the server name - as expressed in the server certificate. The client MUST - NOT use any form of the server hostname derived from an - insecure remote source (e.g., insecure DNS lookup). CNAME - canonicalization is not done. - - If a subjectAltName extension of type dNSName is present in - the certificate, it SHOULD be used as the source of the - server's identity. - - Matching is case-insensitive. - - - - -Crispin Standards Track [Page 92] - -RFC 3501 IMAPv4 March 2003 - - - A "*" wildcard character MAY be used as the left-most name - component in the certificate. For example, *.example.com - would match a.example.com, foo.example.com, etc. but would - not match example.com. - - If the certificate contains multiple names (e.g., more than - one dNSName field), then a match with any one of the fields - is considered acceptable. - - Both the client and server MUST check the result of the STARTTLS - command and subsequent [TLS] negotiation to see whether acceptable - authentication or privacy was achieved. - -11.2. Other Security Considerations - - A server error message for an AUTHENTICATE command which fails due to - invalid credentials SHOULD NOT detail why the credentials are - invalid. - - Use of the LOGIN command sends passwords in the clear. This can be - avoided by using the AUTHENTICATE command with a [SASL] mechanism - that does not use plaintext passwords, by first negotiating - encryption via STARTTLS or some other protection mechanism. - - A server implementation MUST implement a configuration that, at the - time of authentication, requires: - (1) The STARTTLS command has been negotiated. - OR - (2) Some other mechanism that protects the session from password - snooping has been provided. - OR - (3) The following measures are in place: - (a) The LOGINDISABLED capability is advertised, and [SASL] - mechanisms (such as PLAIN) using plaintext passwords are NOT - advertised in the CAPABILITY list. - AND - (b) The LOGIN command returns an error even if the password is - correct. - AND - (c) The AUTHENTICATE command returns an error with all [SASL] - mechanisms that use plaintext passwords, even if the password - is correct. - - A server error message for a failing LOGIN command SHOULD NOT specify - that the user name, as opposed to the password, is invalid. - - A server SHOULD have mechanisms in place to limit or delay failed - AUTHENTICATE/LOGIN attempts. - - - -Crispin Standards Track [Page 93] - -RFC 3501 IMAPv4 March 2003 - - - Additional security considerations are discussed in the section - discussing the AUTHENTICATE and LOGIN commands. - -12. 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 - - As this specification revises the STARTTLS and LOGINDISABLED - extensions previously defined in [IMAP-TLS], the registry will be - updated accordingly. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Crispin Standards Track [Page 94] - -RFC 3501 IMAPv4 March 2003 - - -Appendices - -A. Normative References - - The following documents contain definitions or specifications that - are necessary to understand this document properly: - [ABNF] Crocker, D. and P. Overell, "Augmented BNF for - Syntax Specifications: ABNF", RFC 2234, - November 1997. - - [ANONYMOUS] Newman, C., "Anonymous SASL Mechanism", RFC - 2245, November 1997. - - [CHARSET] Freed, N. and J. Postel, "IANA Character Set - Registration Procedures", RFC 2978, October - 2000. - - [DIGEST-MD5] Leach, P. and C. Newman, "Using Digest - Authentication as a SASL Mechanism", RFC 2831, - May 2000. - - [DISPOSITION] Troost, R., Dorner, S. and K. Moore, - "Communicating Presentation Information in - Internet Messages: The Content-Disposition - Header", RFC 2183, August 1997. - - [IMAP-TLS] Newman, C., "Using TLS with IMAP, POP3 and - ACAP", RFC 2595, June 1999. - - [KEYWORDS] Bradner, S., "Key words for use in RFCs to - Indicate Requirement Levels", BCP 14, RFC 2119, - March 1997. - - [LANGUAGE-TAGS] Alvestrand, H., "Tags for the Identification of - Languages", BCP 47, RFC 3066, January 2001. - - [LOCATION] Palme, J., Hopmann, A. and N. Shelness, "MIME - Encapsulation of Aggregate Documents, such as - HTML (MHTML)", RFC 2557, March 1999. - - [MD5] Myers, J. and M. Rose, "The Content-MD5 Header - Field", RFC 1864, October 1995. - - - - - - - - - -Crispin Standards Track [Page 95] - -RFC 3501 IMAPv4 March 2003 - - - [MIME-HDRS] Moore, K., "MIME (Multipurpose Internet Mail - Extensions) Part Three: Message Header - Extensions for Non-ASCII Text", RFC 2047, - November 1996. - - [MIME-IMB] Freed, N. and N. Borenstein, "MIME - (Multipurpose Internet Mail Extensions) Part - One: Format of Internet Message Bodies", RFC - 2045, November 1996. - - [MIME-IMT] Freed, N. and N. Borenstein, "MIME - (Multipurpose Internet Mail Extensions) Part - Two: Media Types", RFC 2046, November 1996. - - [RFC-2822] Resnick, P., "Internet Message Format", RFC - 2822, April 2001. - - [SASL] Myers, J., "Simple Authentication and Security - Layer (SASL)", RFC 2222, October 1997. - - [TLS] Dierks, T. and C. Allen, "The TLS Protocol - Version 1.0", RFC 2246, January 1999. - - [UTF-7] Goldsmith, D. and M. Davis, "UTF-7: A Mail-Safe - Transformation Format of Unicode", RFC 2152, - May 1997. - - The following documents describe quality-of-implementation issues - that should be carefully considered when implementing this protocol: - - [IMAP-IMPLEMENTATION] Leiba, B., "IMAP Implementation - Recommendations", RFC 2683, September 1999. - - [IMAP-MULTIACCESS] Gahrns, M., "IMAP4 Multi-Accessed Mailbox - Practice", RFC 2180, July 1997. - -A.1 Informative References - - The following documents describe related protocols: - - [IMAP-DISC] Austein, R., "Synchronization Operations for - Disconnected IMAP4 Clients", Work in Progress. - - [IMAP-MODEL] Crispin, M., "Distributed Electronic Mail - Models in IMAP4", RFC 1733, December 1994. - - - - - - -Crispin Standards Track [Page 96] - -RFC 3501 IMAPv4 March 2003 - - - [ACAP] Newman, C. and J. Myers, "ACAP -- Application - Configuration Access Protocol", RFC 2244, - November 1997. - - [SMTP] Klensin, J., "Simple Mail Transfer Protocol", - STD 10, RFC 2821, April 2001. - - The following documents are historical or describe historical aspects - of this protocol: - - [IMAP-COMPAT] Crispin, M., "IMAP4 Compatibility with - IMAP2bis", RFC 2061, December 1996. - - [IMAP-HISTORICAL] Crispin, M., "IMAP4 Compatibility with IMAP2 - and IMAP2bis", RFC 1732, December 1994. - - [IMAP-OBSOLETE] Crispin, M., "Internet Message Access Protocol - - Obsolete Syntax", RFC 2062, December 1996. - - [IMAP2] Crispin, M., "Interactive Mail Access Protocol - - Version 2", RFC 1176, August 1990. - - [RFC-822] Crocker, D., "Standard for the Format of ARPA - Internet Text Messages", STD 11, RFC 822, - August 1982. - - [RFC-821] Postel, J., "Simple Mail Transfer Protocol", - STD 10, RFC 821, August 1982. - -B. Changes from RFC 2060 - - 1) Clarify description of unique identifiers and their semantics. - - 2) Fix the SELECT description to clarify that UIDVALIDITY is required - in the SELECT and EXAMINE responses. - - 3) Added an example of a failing search. - - 4) Correct store-att-flags: "#flag" should be "1#flag". - - 5) Made search and section rules clearer. - - 6) Correct the STORE example. - - 7) Correct "BASE645" misspelling. - - 8) Remove extraneous close parenthesis in example of two-part message - with text and BASE64 attachment. - - - -Crispin Standards Track [Page 97] - -RFC 3501 IMAPv4 March 2003 - - - 9) Remove obsolete "MAILBOX" response from mailbox-data. - - 10) A spurious "<" in the rule for mailbox-data was removed. - - 11) Add CRLF to continue-req. - - 12) Specifically exclude "]" from the atom in resp-text-code. - - 13) Clarify that clients and servers should adhere strictly to the - protocol syntax. - - 14) Emphasize in 5.2 that EXISTS can not be used to shrink a mailbox. - - 15) Add NEWNAME to resp-text-code. - - 16) Clarify that the empty string, not NIL, is used as arguments to - LIST. - - 17) Clarify that NIL can be returned as a hierarchy delimiter for the - empty string mailbox name argument if the mailbox namespace is flat. - - 18) Clarify that addr-mailbox and addr-name have RFC-2822 quoting - removed. - - 19) Update UTF-7 reference. - - 20) Fix example in 6.3.11. - - 21) Clarify that non-existent UIDs are ignored. - - 22) Update DISPOSITION reference. - - 23) Expand state diagram. - - 24) Clarify that partial fetch responses are only returned in - response to a partial fetch command. - - 25) Add UIDNEXT response code. Correct UIDVALIDITY definition - reference. - - 26) Further clarification of "can" vs. "MAY". - - 27) Reference RFC-2119. - - 28) Clarify that superfluous shifts are not permitted in modified - UTF-7. - - 29) Clarify that there are no implicit shifts in modified UTF-7. - - - -Crispin Standards Track [Page 98] - -RFC 3501 IMAPv4 March 2003 - - - 30) Clarify that "INBOX" in a mailbox name is always INBOX, even if - it is given as a string. - - 31) Add missing open parenthesis in media-basic grammar rule. - - 32) Correct attribute syntax in mailbox-data. - - 33) Add UIDNEXT to EXAMINE responses. - - 34) Clarify UNSEEN, PERMANENTFLAGS, UIDVALIDITY, and UIDNEXT - responses in SELECT and EXAMINE. They are required now, but weren't - in older versions. - - 35) Update references with RFC numbers. - - 36) Flush text-mime2. - - 37) Clarify that modified UTF-7 names must be case-sensitive and that - violating the convention should be avoided. - - 38) Correct UID FETCH example. - - 39) Clarify UID FETCH, UID STORE, and UID SEARCH vs. untagged EXPUNGE - responses. - - 40) Clarify the use of the word "convention". - - 41) Clarify that a command is not "in progress" until it has been - fully received (specifically, that a command is not "in progress" - during command continuation negotiation). - - 42) Clarify envelope defaulting. - - 43) Clarify that SP means one and only one space character. - - 44) Forbid silly states in LIST response. - - 45) Clarify that the ENVELOPE, INTERNALDATE, RFC822*, BODY*, and UID - for a message is static. - - 46) Add BADCHARSET response code. - - 47) Update formal syntax to [ABNF] conventions. - - 48) Clarify trailing hierarchy delimiter in CREATE semantics. - - 49) Clarify that the "blank line" is the [RFC-2822] delimiting blank - line. - - - -Crispin Standards Track [Page 99] - -RFC 3501 IMAPv4 March 2003 - - - 50) Clarify that RENAME should also create hierarchy as needed for - the command to complete. - - 51) Fix body-ext-mpart to not require language if disposition - present. - - 52) Clarify the RFC822.HEADER response. - - 53) Correct missing space after charset astring in search. - - 54) Correct missing quote for BADCHARSET in resp-text-code. - - 55) Clarify that ALL, FAST, and FULL preclude any other data items - appearing. - - 56) Clarify semantics of reference argument in LIST. - - 57) Clarify that a null string for SEARCH HEADER X-FOO means any - message with a header line with a field-name of X-FOO regardless of - the text of the header. - - 58) Specifically reserve 8-bit mailbox names for future use as UTF-8. - - 59) It is not an error for the client to store a flag that is not in - the PERMANENTFLAGS list; however, the server will either ignore the - change or make the change in the session only. - - 60) Correct/clarify the text regarding superfluous shifts. - - 61) Correct typographic errors in the "Changes" section. - - 62) Clarify that STATUS must not be used to check for new messages in - the selected mailbox - - 63) Clarify LSUB behavior with "%" wildcard. - - 64) Change AUTHORIZATION to AUTHENTICATE in section 7.5. - - 65) Clarify description of multipart body type. - - 66) Clarify that STORE FLAGS does not affect \Recent. - - 67) Change "west" to "east" in description of timezone. - - 68) Clarify that commands which break command pipelining must wait - for a completion result response. - - 69) Clarify that EXAMINE does not affect \Recent. - - - -Crispin Standards Track [Page 100] - -RFC 3501 IMAPv4 March 2003 - - - 70) Make description of MIME structure consistent. - - 71) Clarify that date searches disregard the time and timezone of the - INTERNALDATE or Date: header. In other words, "ON 13-APR-2000" means - messages with an INTERNALDATE text which starts with "13-APR-2000", - even if timezone differential from the local timezone is sufficient - to move that INTERNALDATE into the previous or next day. - - 72) Clarify that the header fetches don't add a blank line if one - isn't in the [RFC-2822] message. - - 73) Clarify (in discussion of UIDs) that messages are immutable. - - 74) Add an example of CHARSET searching. - - 75) Clarify in SEARCH that keywords are a type of flag. - - 76) Clarify the mandatory nature of the SELECT data responses. - - 77) Add optional CAPABILITY response code in the initial OK or - PREAUTH. - - 78) Add note that server can send an untagged CAPABILITY command as - part of the responses to AUTHENTICATE and LOGIN. - - 79) Remove statement about it being unnecessary to issue a CAPABILITY - command more than once in a connection. That statement is no longer - true. - - 80) Clarify that untagged EXPUNGE decrements the number of messages - in the mailbox. - - 81) Fix definition of "body" (concatenation has tighter binding than - alternation). - - 82) Add a new "Special Notes to Implementors" section with reference - to [IMAP-IMPLEMENTATION]. - - 83) Clarify that an untagged CAPABILITY response to an AUTHENTICATE - command should only be done if a security layer was not negotiated. - - 84) Change the definition of atom to exclude "]". Update astring to - include "]" for compatiblity with the past. Remove resp-text-atom. - - 85) Remove NEWNAME. It can't work because mailbox names can be - literals and can include "]". Functionality can be addressed via - referrals. - - - - -Crispin Standards Track [Page 101] - -RFC 3501 IMAPv4 March 2003 - - - 86) Move modified UTF-7 rationale in order to have more logical - paragraph flow. - - 87) Clarify UID uniqueness guarantees with the use of MUST. - - 88) Note that clients should read response data until the connection - is closed instead of immediately closing on a BYE. - - 89) Change RFC-822 references to RFC-2822. - - 90) Clarify that RFC-2822 should be followed instead of RFC-822. - - 91) Change recommendation of optional automatic capabilities in LOGIN - and AUTHENTICATE to use the CAPABILITY response code in the tagged - OK. This is more interoperable than an unsolicited untagged - CAPABILITY response. - - 92) STARTTLS and AUTH=PLAIN are mandatory to implement; add - recommendations for other [SASL] mechanisms. - - 93) Clarify that a "connection" (as opposed to "server" or "command") - is in one of the four states. - - 94) Clarify that a failed or rejected command does not change state. - - 95) Split references between normative and informative. - - 96) Discuss authentication failure issues in security section. - - 97) Clarify that a data item is not necessarily of only one data - type. - - 98) Clarify that sequence ranges are independent of order. - - 99) Change an example to clarify that superfluous shifts in - Modified-UTF7 can not be fixed just by omitting the shift. The - entire string must be recalculated. - - 100) Change Envelope Structure definition since [RFC-2822] uses - "envelope" to refer to the [SMTP] envelope and not the envelope data - that appears in the [RFC-2822] header. - - 101) Expand on RFC822.HEADER response data vs. BODY[HEADER]. - - 102) Clarify Logout state semantics, change ASCII art. - - 103) Security changes to comply with IESG requirements. - - - - -Crispin Standards Track [Page 102] - -RFC 3501 IMAPv4 March 2003 - - - 104) Add definition for body URI. - - 105) Break sequence range definition into three rules, with rewritten - descriptions for each. - - 106) Move STARTTLS and LOGINDISABLED here from [IMAP-TLS]. - - 107) Add IANA Considerations section. - - 108) Clarify valid client assumptions for new message UIDs vs. - UIDNEXT. - - 109) Clarify that changes to permanentflags affect concurrent - sessions as well as subsequent sessions. - - 110) Clarify that authenticated state can be entered by the CLOSE - command. - - 111) Emphasize that SELECT and EXAMINE are the exceptions to the rule - that a failing command does not change state. - - 112) Clarify that newly-appended messages have the Recent flag set. - - 113) Clarify that newly-copied messages SHOULD have the Recent flag - set. - - 114) Clarify that UID commands always return the UID in FETCH - responses. - -C. Key Word Index - - +FLAGS <flag list> (store command data item) ............... 59 - +FLAGS.SILENT <flag list> (store command data item) ........ 59 - -FLAGS <flag list> (store command data item) ............... 59 - -FLAGS.SILENT <flag list> (store command data item) ........ 59 - ALERT (response code) ...................................... 64 - ALL (fetch item) ........................................... 55 - ALL (search key) ........................................... 50 - ANSWERED (search key) ...................................... 50 - APPEND (command) ........................................... 45 - AUTHENTICATE (command) ..................................... 27 - BAD (response) ............................................. 66 - BADCHARSET (response code) ................................. 64 - BCC <string> (search key) .................................. 51 - BEFORE <date> (search key) ................................. 51 - BODY (fetch item) .......................................... 55 - BODY (fetch result) ........................................ 73 - BODY <string> (search key) ................................. 51 - - - -Crispin Standards Track [Page 103] - -RFC 3501 IMAPv4 March 2003 - - - BODY.PEEK[<section>]<<partial>> (fetch item) ............... 57 - BODYSTRUCTURE (fetch item) ................................. 57 - BODYSTRUCTURE (fetch result) ............................... 74 - BODY[<section>]<<origin octet>> (fetch result) ............. 74 - BODY[<section>]<<partial>> (fetch item) .................... 55 - BYE (response) ............................................. 67 - Body Structure (message attribute) ......................... 12 - CAPABILITY (command) ....................................... 24 - CAPABILITY (response code) ................................. 64 - CAPABILITY (response) ...................................... 68 - CC <string> (search key) ................................... 51 - CHECK (command) ............................................ 47 - CLOSE (command) ............................................ 48 - COPY (command) ............................................. 59 - CREATE (command) ........................................... 34 - DELETE (command) ........................................... 35 - DELETED (search key) ....................................... 51 - DRAFT (search key) ......................................... 51 - ENVELOPE (fetch item) ...................................... 57 - ENVELOPE (fetch result) .................................... 77 - EXAMINE (command) .......................................... 33 - EXISTS (response) .......................................... 71 - EXPUNGE (command) .......................................... 48 - EXPUNGE (response) ......................................... 72 - Envelope Structure (message attribute) ..................... 12 - FAST (fetch item) .......................................... 55 - FETCH (command) ............................................ 54 - FETCH (response) ........................................... 73 - FLAGGED (search key) ....................................... 51 - FLAGS (fetch item) ......................................... 57 - FLAGS (fetch result) ....................................... 78 - FLAGS (response) ........................................... 71 - FLAGS <flag list> (store command data item) ................ 59 - FLAGS.SILENT <flag list> (store command data item) ......... 59 - FROM <string> (search key) ................................. 51 - FULL (fetch item) .......................................... 55 - Flags (message attribute) .................................. 11 - HEADER (part specifier) .................................... 55 - HEADER <field-name> <string> (search key) .................. 51 - HEADER.FIELDS <header-list> (part specifier) ............... 55 - HEADER.FIELDS.NOT <header-list> (part specifier) ........... 55 - INTERNALDATE (fetch item) .................................. 57 - INTERNALDATE (fetch result) ................................ 78 - Internal Date (message attribute) .......................... 12 - KEYWORD <flag> (search key) ................................ 51 - Keyword (type of flag) ..................................... 11 - LARGER <n> (search key) .................................... 51 - LIST (command) ............................................. 40 - - - -Crispin Standards Track [Page 104] - -RFC 3501 IMAPv4 March 2003 - - - LIST (response) ............................................ 69 - LOGIN (command) ............................................ 30 - LOGOUT (command) ........................................... 25 - LSUB (command) ............................................. 43 - LSUB (response) ............................................ 70 - MAY (specification requirement term) ....................... 4 - MESSAGES (status item) ..................................... 45 - MIME (part specifier) ...................................... 56 - MUST (specification requirement term) ...................... 4 - MUST NOT (specification requirement term) .................. 4 - Message Sequence Number (message attribute) ................ 10 - NEW (search key) ........................................... 51 - NO (response) .............................................. 66 - NOOP (command) ............................................. 25 - NOT <search-key> (search key) .............................. 52 - OK (response) .............................................. 65 - OLD (search key) ........................................... 52 - ON <date> (search key) ..................................... 52 - OPTIONAL (specification requirement term) .................. 4 - OR <search-key1> <search-key2> (search key) ................ 52 - PARSE (response code) ...................................... 64 - PERMANENTFLAGS (response code) ............................. 64 - PREAUTH (response) ......................................... 67 - Permanent Flag (class of flag) ............................. 12 - READ-ONLY (response code) .................................. 65 - READ-WRITE (response code) ................................. 65 - RECENT (response) .......................................... 72 - RECENT (search key) ........................................ 52 - RECENT (status item) ....................................... 45 - RENAME (command) ........................................... 37 - REQUIRED (specification requirement term) .................. 4 - RFC822 (fetch item) ........................................ 57 - RFC822 (fetch result) ...................................... 78 - RFC822.HEADER (fetch item) ................................. 57 - RFC822.HEADER (fetch result) ............................... 78 - RFC822.SIZE (fetch item) ................................... 57 - RFC822.SIZE (fetch result) ................................. 78 - RFC822.TEXT (fetch item) ................................... 58 - RFC822.TEXT (fetch result) ................................. 79 - SEARCH (command) ........................................... 49 - SEARCH (response) .......................................... 71 - SEEN (search key) .......................................... 52 - SELECT (command) ........................................... 31 - SENTBEFORE <date> (search key) ............................. 52 - SENTON <date> (search key) ................................. 52 - SENTSINCE <date> (search key) .............................. 52 - SHOULD (specification requirement term) .................... 4 - SHOULD NOT (specification requirement term) ................ 4 - - - -Crispin Standards Track [Page 105] - -RFC 3501 IMAPv4 March 2003 - - - SINCE <date> (search key) .................................. 52 - SMALLER <n> (search key) ................................... 52 - STARTTLS (command) ......................................... 27 - STATUS (command) ........................................... 44 - STATUS (response) .......................................... 70 - STORE (command) ............................................ 58 - SUBJECT <string> (search key) .............................. 53 - SUBSCRIBE (command) ........................................ 38 - Session Flag (class of flag) ............................... 12 - System Flag (type of flag) ................................. 11 - TEXT (part specifier) ...................................... 56 - TEXT <string> (search key) ................................. 53 - TO <string> (search key) ................................... 53 - TRYCREATE (response code) .................................. 65 - UID (command) .............................................. 60 - UID (fetch item) ........................................... 58 - UID (fetch result) ......................................... 79 - UID <sequence set> (search key) ............................ 53 - UIDNEXT (response code) .................................... 65 - UIDNEXT (status item) ...................................... 45 - UIDVALIDITY (response code) ................................ 65 - UIDVALIDITY (status item) .................................. 45 - UNANSWERED (search key) .................................... 53 - UNDELETED (search key) ..................................... 53 - UNDRAFT (search key) ....................................... 53 - UNFLAGGED (search key) ..................................... 53 - UNKEYWORD <flag> (search key) .............................. 53 - UNSEEN (response code) ..................................... 65 - UNSEEN (search key) ........................................ 53 - UNSEEN (status item) ....................................... 45 - UNSUBSCRIBE (command) ...................................... 39 - Unique Identifier (UID) (message attribute) ................ 8 - X<atom> (command) .......................................... 62 - [RFC-2822] Size (message attribute) ........................ 12 - \Answered (system flag) .................................... 11 - \Deleted (system flag) ..................................... 11 - \Draft (system flag) ....................................... 11 - \Flagged (system flag) ..................................... 11 - \Marked (mailbox name attribute) ........................... 69 - \Noinferiors (mailbox name attribute) ...................... 69 - \Noselect (mailbox name attribute) ......................... 69 - \Recent (system flag) ...................................... 11 - \Seen (system flag) ........................................ 11 - \Unmarked (mailbox name attribute) ......................... 69 - - - - - - - -Crispin Standards Track [Page 106] - -RFC 3501 IMAPv4 March 2003 - - -Author's Address - - Mark R. Crispin - Networks and Distributed Computing - University of Washington - 4545 15th Avenue NE - Seattle, WA 98105-4527 - - Phone: (206) 543-5762 - - EMail: MRC@CAC.Washington.EDU - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Crispin Standards Track [Page 107] - -RFC 3501 IMAPv4 March 2003 - - -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 assigns. v 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. - - - - - - - - - - - - - - - - - - - - -Crispin Standards Track [Page 108] - - diff --git a/imap/docs/rfc/rfc3502.txt b/imap/docs/rfc/rfc3502.txt deleted file mode 100644 index f6b61a44..00000000 --- a/imap/docs/rfc/rfc3502.txt +++ /dev/null @@ -1,395 +0,0 @@ - - - - - - -Network Working Group M. Crispin -Request for Comments: 3502 University of Washington -Category: Standards Track March 2003 - - - Internet Message Access Protocol (IMAP) - MULTIAPPEND Extension - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2003). All Rights Reserved. - -Abstract - - This document describes the multiappending extension to the Internet - Message Access Protocol (IMAP) (RFC 3501). This extension provides - substantial performance improvements for IMAP clients which upload - multiple messages at a time to a mailbox on the server. - - A server which supports this extension indicates this with a - capability name of "MULTIAPPEND". - -Terminology - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "MAY", and "OPTIONAL" in this document are to - be interpreted as described in [KEYWORDS]. - -Introduction - - The MULTIAPPEND extension permits uploading of multiple messages with - a single command. When used in conjunction with the [LITERAL+] - extension, the entire upload is accomplished in a single - command/response round trip. - - A MULTIAPPEND APPEND operation is atomic; either all messages are - successfully appended, or no messages are appended. - - In the base IMAP specification, each message must be appended in a - separate command, and there is no mechanism to "unappend" messages if - an error occurs while appending. Also, some mail stores may require - - - -Crispin Standards Track [Page 1] - -RFC 3502 IMAP MULTIAPPEND March 2003 - - - an expensive "open/lock + sync/unlock/close" operation as part of - appending; this can be quite expensive if it must be done on a - per-message basis. - - If the server supports both LITERAL+ and pipelining but not - MULTIAPPEND, it may be possible to get some of the performance - advantages of MULTIAPPEND by doing a pipelined "batch" append. - However, it will not work as well as MULTIAPPEND for the following - reasons: - - 1) Multiple APPEND commands, even as part of a pipelined batch, - are non-atomic by definition. There is no way to revert the - mailbox to the state before the batch append in the event of an - error. - - 2) It may not be feasible for the server to coalesce pipelined - APPEND operations so as to avoid the "open/lock + - sync/unlock/close" overhead described above. In any case, such - coalescing would be timing dependent and thus potentially - unreliable. In particular, with traditional UNIX mailbox files, - it is assumed that a lock is held only for a single atomic - operation, and many applications disregard any lock that is - older than 5 minutes. - - 3) If an error occurs, depending upon the nature of the error, - it is possible for additional messages to be appended after the - error. For example, the user wants to append 5 messages, but a - disk quota error occurs with the third message because of its - size. However, the fourth and fifth messages have already been - sent in the pipeline, so the mailbox ends up with the first, - second, fourth, and fifth messages of the batch appended. - -6.3.11. APPEND Command - - Arguments: mailbox name - one or more messages to upload, specified as: - OPTIONAL flag parenthesized list - OPTIONAL date/time string - message literal - - Data: no specific responses for this command - - Result: OK - append completed - NO - append error: can't append to that mailbox, error - in flags or date/time or message text, - append cancelled - BAD - command unknown or arguments invalid - - - - -Crispin Standards Track [Page 2] - -RFC 3502 IMAP MULTIAPPEND March 2003 - - - The APPEND command appends the literal arguments as new messages - to the end of the specified destination mailbox. This argument - SHOULD be in the format of an [RFC-2822] message. 8-bit - characters are permitted in the message. A server implementation - that is unable to preserve 8-bit data properly MUST be able to - reversibly convert 8-bit APPEND data to 7-bit using a [MIME-IMB] - content transfer encoding. - - Note: There MAY be exceptions, e.g., draft messages, in - which required [RFC-2822] header lines are omitted in the - message literal argument to APPEND. The full implications - of doing so MUST be understood and carefully weighed. - - If a flag parenthesized list is specified, the flags SHOULD be set - in the resulting message; otherwise, the flag list of the - resulting message is set empty by default. - - If a date-time is specified, the internal date SHOULD be set in - the resulting message; otherwise, the internal date of the - resulting message is set to the current date and time by default. - - A zero-length message literal argument is an error, and MUST - return a NO. This can be used to cancel the append. - - If the append is unsuccessful for any reason (including being - cancelled), the mailbox MUST be restored to its state before the - APPEND attempt; no partial appending is permitted. The server MAY - return an error before processing all the message arguments. - - If the destination mailbox does not exist, a server MUST return an - error, and MUST NOT automatically create the mailbox. Unless it - is certain that the destination mailbox can not be created, the - server MUST send the response code "[TRYCREATE]" as the prefix of - the text of the tagged NO response. This gives a hint to the - client that it can attempt a CREATE command and retry the APPEND - if the CREATE is successful. - - If the mailbox is currently selected, the normal new message - actions SHOULD occur. Specifically, the server SHOULD notify the - client immediately via an untagged EXISTS response. If the server - does not do so, the client MAY issue a NOOP command (or failing - that, a CHECK command) after one or more APPEND commands. - - - - - - - - - -Crispin Standards Track [Page 3] - -RFC 3502 IMAP MULTIAPPEND March 2003 - - - Example: C: A003 APPEND saved-messages (\Seen) {329} - S: + Ready for literal data - C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) - C: From: Fred Foobar <foobar@Blurdybloop.example.COM> - C: Subject: afternoon meeting - C: To: mooch@owatagu.example.net - C: Message-Id: <B27397-0100000@Blurdybloop.example.COM> - C: MIME-Version: 1.0 - C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII - C: - C: Hello Joe, do you think we can meet at 3:30 tomorrow? - C: (\Seen) " 7-Feb-1994 22:43:04 -0800" {295} - S: + Ready for literal data - C: Date: Mon, 7 Feb 1994 22:43:04 -0800 (PST) - C: From: Joe Mooch <mooch@OWaTaGu.example.net> - C: Subject: Re: afternoon meeting - C: To: foobar@blurdybloop.example.com - C: Message-Id: <a0434793874930@OWaTaGu.example.net> - C: MIME-Version: 1.0 - C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII - C: - C: 3:30 is fine with me. - C: - S: A003 OK APPEND completed - C: A004 APPEND bogusname (\Flagged) {1023} - S: A004 NO [TRYCREATE] No such mailbox as bogusname - C: A005 APPEND test (\Flagged) {99} - S: + Ready for literal data - C: Date: Mon, 7 Feb 2000 22:43:04 -0800 (PST) - C: From: Fred Foobar <fred@example.com> - C: Subject: hmm... - C: {35403} - S: A005 NO APPEND failed: Disk quota exceeded - - Note: The APPEND command is not used for message delivery, - because it does not provide a mechanism to transfer [SMTP] - envelope information. - -Modification to IMAP4rev1 Base Protocol Formal Syntax - - The following syntax specification uses the Augmented Backus-Naur - Form (ABNF) notation as specified in [ABNF]. - - append = "APPEND" SP mailbox 1*append-message - - append-message = [SP flag-list] [SP date-time] SP literal - - - - - -Crispin Standards Track [Page 4] - -RFC 3502 IMAP MULTIAPPEND March 2003 - - -MULTIAPPEND Interaction with UIDPLUS Extension - - Servers which support both MULTIAPPEND and [UIDPLUS] will have the - "resp-code-apnd" rule modified as follows: - - resp-code-apnd = "APPENDUID" SP nz-number SP set - - That is, the APPENDUID response code returns as many UIDs as there - were messages appended in the multiple append. The UIDs returned - should be in the order the articles where appended. The message set - may not contain extraneous UIDs or the symbol "*". - -Security Considerations - - The MULTIAPPEND extension does not raise any security considerations - that are not present in the base [IMAP] protocol, and these issues - are discussed in [IMAP]. Nevertheless, it is important to remember - that IMAP4rev1 protocol transactions, including electronic mail data, - are sent in the clear over the network unless protection from - snooping is negotiated, either by the use of STARTTLS, privacy - protection is negotiated in the AUTHENTICATE command, or some other - protection mechanism is in effect. - -Normative References - - [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", RFC 2234, November 1997. - - [IMAP] Crispin, M., "Internet Message Access Protocol - Version - 4rev1", RFC 3501, March 2003. - - [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [MIME-IMB] Freed, N. and N. Borenstein, "MIME (Multipurpose Internet - Mail Extensions) Part One: Format of Internet Message - Bodies", RFC 2045, November 1996. - - [RFC-2822] Resnick, P., "Internet Message Format", RFC 2822, April - 2001. - - - - - - - - - - - -Crispin Standards Track [Page 5] - -RFC 3502 IMAP MULTIAPPEND March 2003 - - -Informative References - - [LITERAL+] Myers, J., "IMAP4 non-synchronizing literals", RFC 2088, - January 1997. - - [UIDPLUS] Myers, J., "IMAP4 UIDPLUS extension", RFC 2359, June 1988. - - [SMTP] Klensin, J., Editor, "Simple Mail Transfer Protocol", RFC - 2821, April 2001. - -Author's Address - - Mark R. Crispin - Networks and Distributed Computing - University of Washington - 4545 15th Avenue NE - Seattle, WA 98105-4527 - - Phone: (206) 543-5762 - EMail: MRC@CAC.Washington.EDU - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Crispin Standards Track [Page 6] - -RFC 3502 IMAP MULTIAPPEND March 2003 - - -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 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. - - - - - - - - - - - - - - - - - - - -Crispin Standards Track [Page 7] - diff --git a/imap/docs/rfc/rfc3503.txt b/imap/docs/rfc/rfc3503.txt deleted file mode 100644 index 5b82fb08..00000000 --- a/imap/docs/rfc/rfc3503.txt +++ /dev/null @@ -1,507 +0,0 @@ - - - - - - -Network Working Group A. Melnikov -Request for Comments: 3503 ACI Worldwide/MessagingDirect -Category: Standards Track March 2003 - - - Message Disposition Notification (MDN) profile for - Internet Message Access Protocol (IMAP) - -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 (2003). All Rights Reserved. - -Abstract - - The Message Disposition Notification (MDN) facility defined in RFC - 2298 provides a means by which a message can request that message - processing by the recipient be acknowledged as well as a format to be - used for such acknowledgements. However, it doesn't describe how - multiple Mail User Agents (MUAs) should handle the generation of MDNs - in an Internet Message Access Protocol (IMAP4) environment. - - This document describes how to handle MDNs in such an environment and - provides guidelines for implementers of IMAP4 that want to add MDN - support to their products. - - - - - - - - - - - - - - - - - - - -Melnikov Standards Track [Page 1] - -RFC 3503 MDN profile for IMAP March 2003 - - -Table of Contents - - 1. Conventions Used in this Document............................. 2 - 2. Introduction and Overview..................................... 2 - 3. Client behavior............................................... 3 - 3.1. Client behavior when receiving a message................. 5 - 3.2. Client behavior when copying a message................... 5 - 3.3. Client behavior when sending a message................... 5 - 3.4. Client behavior when saving a temporary message.......... 5 - 4. Server behavior............................................... 5 - 4.1. Server that supports arbitrary keywords.................. 5 - 4.2. Server that supports only $MDNSent keyword............... 5 - 4.3. Interaction with IMAP ACL extension...................... 6 - 5. Examples...................................................... 6 - 6. Security Considerations....................................... 7 - 7. Formal Syntax................................................. 7 - 8. Acknowledgments............................................... 7 - 9. Normative References.......................................... 8 - 10. Author's Address.............................................. 8 - 11. Full Copyright Statement...................................... 9 - -1. Conventions Used in this Document - - "C:" and "S:" in examples show lines sent by the client and server - respectively. - - The keywords "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" in - this document when typed in uppercase are to be interpreted as - defined in "Key words for use in RFCs to Indicate Requirement Levels" - [KEYWORDS]. - -2. Introduction and Overview - - This memo defines an additional [IMAP4] mailbox keyword that allows - multiple Mail User Agents (MUAs) to know if a requested receipt - notification was sent. - - Message Disposition Notification [MDN] does not require any special - support of IMAP in the case where a user has access to the mailstore - from only one computer and is using a single MUA. In this case, the - MUA behaves as described in [MDN], i.e., the MUA performs automatic - processing and generates corresponding MDNs, it performs requested - action and, with the user's permission, sends appropriate MDNs. The - MUA will not send MDN twice because the MUA keeps track of sent - notifications in a local configuration. However, that does not work - when IMAP is used to access the same mailstore from different - locations or is using different MUAs. - - - - -Melnikov Standards Track [Page 2] - -RFC 3503 MDN profile for IMAP March 2003 - - - This document defines a new special purpose mailbox keyword $MDNSent - that must be used by MUAs. It does not define any new command or - response for IMAP, but describes a technique that MUAs should use to - achieve interoperability. - - When a client opens a mailbox for the first time, it verifies that - the server is capable of storing the $MDNSent keyword by examining - the PERMANENTFLAGS response code. In order to support MDN in IMAP, a - server MUST support either the $MDNSent keyword, or arbitrary message - keywords. - -3. Client behavior - - The use of IMAP requires few additional steps in mail processing on - the client side. The following timeline modifies the timeline found - in Section 4 of [MDN]. - - -- User composes message. - - -- User tells MUA to send message. - - -- MUA passes message to MSA (original recipient information passed - along). MUA [optionally] saves message to a folder for sent mail - with $MDNSent flag set. - - -- MSA sends message to MTA. - - -- Final MTA receives message. - - -- Final MTA delivers message to MUA (possibly generating DSN). - - -- MUA logs into IMAP server, opens mailbox, verifies if mailbox can - store $MDNSent keyword by examining PERMANENTFLAGS response. - - -- MUA performs automatic processing and generates corresponding MDNs - ("dispatched", "processed", "deleted", "denied" or "failed" - disposition type with "automatic-action" and "MDN-sent- - automatically" disposition modes) for messages that do not have - $MDNSent keyword, or \Draft flag set. (*) - - -- MUA sets the $MDNSent keyword for every message that required an - automatic MDN to be sent, whether or not the MDN was sent. - - -- MUA displays a list of messages to user. - - -- User selects a message and requests that some action be performed - on it. - - - - -Melnikov Standards Track [Page 3] - -RFC 3503 MDN profile for IMAP March 2003 - - - -- MUA performs requested action and, with user's permission, sends - appropriate MDN ("displayed", "dispatched", "processed", - "deleted", "denied" or "failed" disposition type with "manual- - action" and "MDN-sent-manually" or "MDN-sent-automatically" - disposition mode). If the generated MDN is saved to a mailbox - with the APPEND command, the client MUST specify the $MDNSent - keyword in the APPEND. - - -- MUA sets the $MDNSent keyword for all messages for which the user - confirmed the dispatching of disposition (or was explicitly - prohibited to do so). - - -- User possibly performs other actions on message, but no further - MDNs are generated. - - (*) Note: MUA MUST NOT use \Recent flag as an indicator that it - should send MDN, because according to [IMAP4], "If multiple - connections have the same mailbox selected simultaneously, it is - undefined which of these connections will see newly-arrived - messages with \Recent set and which will see it without \Recent - set". Thus, using \Recent as an indicator will cause - unpredictable client behavior with different IMAP4 servers. - However, the client MAY use \Seen flag as one of the indicators - that MDN must not be sent. The client MUST NOT use any other - standard flags, like \Draft or \Answered, to indicate that MDN - was previously sent, because they have different well known - meaning. In any case, in the presence of the $MDNSent keyword, - the client MUST ignore all other flags or keywords for the - purpose of generating an MDN and MUST NOT send the MDN. - - When the client opens a mailbox for the first time, it must verify - that the server supports the $MDNSent keyword, or arbitrary message - keywords by examining PERMANENTFLAGS response code. - - The client MUST NOT try to set the $MDNSent keyword if the server is - incapable of storing it permanently. - - The client MUST be prepared to receive NO from the server as the - result of STORE $MDNSent when the server advertises the support of - storing arbitrary keywords, because the server may limit the number - of message keywords it can store in a particular mailbox. A client - SHOULD NOT send MDN if it fails to store the $MDNSent keyword. - - Once the $MDNSent keyword is set, it MUST NOT be unset by a client. - The client MAY set the $MDNSent keyword when a user denies sending - the notification. This prohibits all other MUAs from sending MDN for - this message. - - - - -Melnikov Standards Track [Page 4] - -RFC 3503 MDN profile for IMAP March 2003 - - -3.1. Client behavior when receiving a message - - The client MUST NOT send MDN if a message has the $MDNSent keyword - set. It also MUST NOT send MDN if a message has \Draft flag, because - some clients use this flag to mark a message as incomplete. - - See the timeline in section 3 for details on client behavior when - receiving a message. - -3.2. Client behavior when copying a message - - The client SHOULD verify that $MDNSent is preserved on a COPY - operation. Furthermore, when a message is copied between servers - with the APPEND command, the client MUST set the $MDNSent keyword - correctly. - -3.3. Client behavior when sending a message - - When saving a sent message to any folder, the client MUST set the - $MDNSent keyword to prevent another client from sending MDN for the - message. - -3.4. Client behavior when saving a temporary message - - When saving an unfinished message to any folder client MUST set - $MDNSent keyword to prevent another client from sending MDN for the - message. - -4. Server behavior - - Server implementors that want to follow this specification must - insure that their server complies with either section 4.1 or section - 4.2. If the server also supports the IMAP [ACL] extension, it MUST - also comply with the section 4.3. - -4.1. Server that supports arbitrary keywords - - No changes are required from the server to make it compatible with - the extension described in this document if it supports arbitrary - keywords. - -4.2. Server that supports only $MDNSent keyword - - Servers that support only the $MDNSent keyword MUST preserve it on - the COPY operation. It is also expected that a server that supports - SEARCH <flag> will also support the SEARCH KEYWORD $MDNSent. - - - - - -Melnikov Standards Track [Page 5] - -RFC 3503 MDN profile for IMAP March 2003 - - -4.3. Interaction with IMAP ACL extension - - Any server that conforms to either 4.1 or 4.2 and also supports the - IMAP [ACL] extension, SHOULD preserve the $MDNSent keyword on COPY - even if the client does not have 'w' right. This will prevent the - generation of a duplicated MDN for the same message. Note that the - server MUST still check if the client has rights to perform the COPY - operation on a message according to [ACL]. - -5. Examples - - 1) MUA opens mailbox for the first time. - - a) The server supports storing of arbitrary keywords - - C: a100 select INBOX - S: * FLAGS (\Flagged \Draft \Deleted \Seen) - S: * OK [PERMANENTFLAGS (\Flagged \Draft \Deleted \Seen \*)] - S: * 5 EXISTS - S: * 3 RECENT - S: * OK [UIDVALIDITY 894294713] - S: a100 OK [READ-WRITE] Completed - - b) The server supports storing of the $MDNSent keyword - - C: a100 select INBOX - S: * FLAGS (\Flagged \Draft \Deleted \Seen $MDNSent) - S: * OK [PERMANENTFLAGS (\Flagged \Draft \Deleted \Seen $MDNSent)] - S: * 5 EXISTS - S: * 3 RECENT - S: * OK [UIDVALIDITY 894294713] - S: a100 OK [READ-WRITE] Completed - - 2) The MUA successfully sets the $MDNSent keyword - - C: a200 STORE 4 +FLAGS ($MDNSent) - S: * 4 FETCH (FLAGS (\Flagged \Seen $MDNSent)) - S: * FLAGS ($MDNSent \Flagged \Deleted \Draft \Seen) - S: * OK [PERMANENTFLAGS ($MDNSent \Flagged \Deleted \Draft \Seen \*)] - S: a200 OK STORE completed - - 3) The server refuses to store the $MDNSent keyword - - C: a200 STORE 4 +FLAGS ($MDNSent) - S: a200 NO STORE failed : no space left to store $MDNSent keyword - - - - - - -Melnikov Standards Track [Page 6] - -RFC 3503 MDN profile for IMAP March 2003 - - - 4) All clients and servers MUST treat the $MDNSent keyword as case - insensitive in all operations, as stated in [IMAP]. - - C: a300 FETCH 1:* FLAGS - S: * 1 FETCH (FLAGS (\Seen)) - S: * 2 FETCH (FLAGS (\Answered \Seen $MdnSENt)) - S: * 3 FETCH (FLAGS ()) - S: * 4 FETCH (FLAGS (\Flagged \Seen $MdnSENT)) - S: * 5 FETCH (FLAGS ($MDNSent)) - S: * 6 FETCH (FLAGS (\Recent)) - S: a300 OK FETCH completed - C: a400 SEARCH KEYWORDS $mdnsent - S: * SEARCH 2 4 5 - S: a400 OK SEARCH completed - -6. Security Considerations - - There are no known security issues with this extension, not found in - [MDN] and/or [IMAP4]. - - Section 4.3 changes ACL checking requirements on an IMAP server that - implements IMAP [ACL] extension. - -7. Formal Syntax - - The following syntax specification uses the augmented Backus-Naur - Form (BNF) notation as specified in [RFC-822], as modified by - [IMAP4]. Non-terminals referenced, but not defined below, are as - defined by [IMAP4]. - - 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. - - flag_keyword ::= "$MDNSent" / other_keywords - - other_keywords ::= atom - -8. Acknowledgments - - This document is the product of discussions that took place on the - IMAP mailing list. Special gratitude to Cyrus Daboo and Randall - Gellens for reviewing the document. - - Thank you to my father who as he has helped to make me what I am. I - miss you terribly. - - - - -Melnikov Standards Track [Page 7] - -RFC 3503 MDN profile for IMAP March 2003 - - -9. Normative References - - [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [MDN] Fajman, R., "An Extensible Message Format for Message - Disposition Notifications", RFC 2298, March 1998. - - [IMAP4] Crispin, M., "Internet Message Access Protocol - Version - 4rev1", RFC 3501, March 2003. - - [ACL] Myers, J., "IMAP4 ACL extension", RFC 2086, January 1997. - -10. Author's Address - - Alexey Melnikov - ACI Worldwide/MessagingDirect - 59 Clarendon Road - Watford, Hertfordshire - United Kingdom, WD17 1FQ - - Phone: +44 1923 81 2877 - EMail: mel@messagingdirect.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Melnikov Standards Track [Page 8] - -RFC 3503 MDN profile for IMAP March 2003 - - -11. 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 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. - - - - - - - - - - - - - - - - - - - -Melnikov Standards Track [Page 9] - diff --git a/imap/docs/rfc/rfc3516.txt b/imap/docs/rfc/rfc3516.txt deleted file mode 100644 index 4d021975..00000000 --- a/imap/docs/rfc/rfc3516.txt +++ /dev/null @@ -1,451 +0,0 @@ - - - - - - -Network Working Group L. Nerenberg -Request for Comments: 3516 Orthanc Systems -Category: Standards Track April 2003 - - - IMAP4 Binary Content Extension - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2003). All Rights Reserved. - -Abstract - - This memo defines the Binary extension to the Internet Message Access - Protocol (IMAP4). It provides a mechanism for IMAP4 clients and - servers to exchange message body data without using a MIME content- - transfer-encoding. - -1. Conventions Used in this Document - - The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" - in this document are to be interpreted as described in [KEYWORD]. - - The abbreviation "CTE" means content-transfer-encoding. - -2. Introduction - - The MIME extensions to Internet messaging allow for the transmission - of non-textual (binary) message content [MIME-IMB]. Since the - traditional transports for messaging are not always capable of - passing binary data transparently, MIME provides encoding schemes - that allow binary content to be transmitted over transports that are - not otherwise able to do so. - - The overhead of MIME-encoding this content can be considerable in - some contexts (e.g., slow radio links, streaming multimedia). - Reducing the overhead associated with CTE schemes such as base64 - - - - - - -Nerenberg Standards Track [Page 1] - -RFC 3516 IMAP4 Binary Content Extension April 2003 - - - can give a noticeable reduction in resource consumption. The Binary - extension lets the server perform CTE decoding prior to transmitting - message data to the client. - -3. Content-Transfer-Encoding Considerations - - Every IMAP4 body section has a MIME content-transfer-encoding. - (Those without an explicit Content-Transfer-Encoding header are - implicitly labeled as "7bit" content.) In the terminology of [MIME- - IMB], the CTE specifies both a decoding algorithm and the domain of - the decoded data. In this memo, "decoding" refers to the CTE - decoding step described in [MIME-IMB]. - - Certain CTEs use an identity encoding transformation. For these CTEs - there is no decoding required, however the domain of the underlying - data may not be expressible in the IMAP4 protocol (e.g., MIME - "binary" content containing NUL octets). To accommodate these cases - the Binary extension introduces a new type of literal protocol - element that is fully eight bit transparent. - - Thus, server processing of the FETCH BINARY command involves two - logical steps: - - 1) perform any CTE-related decoding - - 2) determine the domain of the decoded data - - Step 2 is necessary to determine which protocol element should be - used to transmit the decoded data. (See FETCH Response Extensions - for further details.) - -4. Framework for the IMAP4 Binary Extension - - This memo defines the following extensions to [IMAP4rev1]. - -4.1. CAPABILITY Identification - - IMAP4 servers that support this extension MUST include "BINARY" in - the response list to the CAPABILITY command. - -4.2. FETCH Command Extensions - - This extension defines three new FETCH command data items. - - BINARY<section-binary>[<partial>] - - Requests that the specified section be transmitted after - performing CTE-related decoding. - - - -Nerenberg Standards Track [Page 2] - -RFC 3516 IMAP4 Binary Content Extension April 2003 - - - The <partial> argument, if present, requests that a subset of - the data be returned. The semantics of a partial FETCH BINARY - command are the same as for a partial FETCH BODY command, with - the exception that the <partial> arguments refer to the DECODED - section data. - - BINARY.PEEK<section-binary>[<partial>] - - An alternate form of FETCH BINARY that does not implicitly set - the \Seen flag. - - BINARY.SIZE<section-binary> - - Requests the decoded size of the section (i.e., the size to - expect in response to the corresponding FETCH BINARY request). - - Note: client authors are cautioned that this might be an - expensive operation for some server implementations. - Needlessly issuing this request could result in degraded - performance due to servers having to calculate the value every - time the request is issued. - -4.3. FETCH Response Extensions - - This extension defines two new FETCH response data items. - - BINARY<section-binary>[<<number>>] - - An <nstring> or <literal8> expressing the content of the - specified section after removing any CTE-related encoding. If - <number> is present it refers to the offset within the DECODED - section data. - - If the domain of the decoded data is "8bit" and the data does - not contain the NUL octet, the server SHOULD return the data in - a <string> instead of a <literal8>; this allows the client to - determine if the "8bit" data contains the NUL octet without - having to explicitly scan the data stream for for NULs. - - If the server does not know how to decode the section's CTE, it - MUST fail the request and issue a "NO" response that contains - the "UNKNOWN-CTE" extended response code. - - - - - - - - - -Nerenberg Standards Track [Page 3] - -RFC 3516 IMAP4 Binary Content Extension April 2003 - - - BINARY.SIZE<section-binary> - - The size of the section after removing any CTE-related - encoding. The value returned MUST match the size of the - <nstring> or <literal8> that will be returned by the - corresponding FETCH BINARY request. - - If the server does not know how to decode the section's CTE, it - MUST fail the request and issue a "NO" response that contains - the "UNKNOWN-CTE" extended response code. - -4.4. APPEND Command Extensions - - The APPEND command is extended to allow the client to append data - containing NULs by using the <literal8> syntax. The server MAY - modify the CTE of the appended data, however any such transformation - MUST NOT result in a loss of data. - - If the destination mailbox does not support the storage of binary - content, the server MUST fail the request and issue a "NO" response - that contains the "UNKNOWN-CTE" extended response code. - -5. MIME Encoded Headers - - [MIME-MHE] defines an encoding that allows for non-US-ASCII text in - message headers. This encoding is not the same as the content- - transfer-encoding applied to message bodies, and the decoding - transformations described in this memo do not apply to [MIME-MHE] - encoded header text. A server MUST NOT perform any conversion of - [MIME-MHE] encoded header text in response to any binary FETCH or - APPEND request. - -6. Implementation Considerations - - Messaging clients and servers have been notoriously lax in their - adherence to the Internet CRLF convention for terminating lines of - textual data in Internet protocols. When sending data using the - Binary extension, servers MUST ensure that textual line-oriented - sections are always transmitted using the IMAP4 CRLF line termination - syntax, regardless of the underlying storage representation of the - data on the server. - - A server may choose to store message body binary content in a non- - encoded format. Regardless of the internal storage representation - used, the server MUST issue BODYSTRUCTURE responses that describe the - message as though the binary-encoded sections are encoded in a CTE - - - - - -Nerenberg Standards Track [Page 4] - -RFC 3516 IMAP4 Binary Content Extension April 2003 - - - acceptable to the IMAP4 base specification. Furthermore, the results - of a FETCH BODY MUST return the message body content in the format - described by the corresponding FETCH BODYSTRUCTURE response. - - While the server is allowed to modify the CTE of APPENDed <literal8> - data, this should only be done when it is absolutely necessary. - Gratuitous encoding changes will render useless most cryptographic - operations that have been performed on the message. - - This extension provides an optimization that is useful in certain - specific situations. It does not absolve clients from providing - basic functionality (content transfer decoding) that should be - available in all messaging clients. Clients supporting this - extension SHOULD be prepared to perform their own CTE decoding - operations. - -7. Formal Protocol Syntax - - The following syntax specification uses the augmented Backus-Naur - Form (ABNF) notation as used in [ABNF], and incorporates by reference - the Core Rules defined in that document. - - This syntax augments the grammar specified in [IMAP4rev1]. - - append =/ "APPEND" SP mailbox [SP flag-list] - [SP date-time] SP literal8 - - fetch-att =/ "BINARY" [".PEEK"] section-binary [partial] - / "BINARY.SIZE" section-binary - - literal8 = "~{" number "}" CRLF *OCTET - ; <number> represents the number of OCTETs - ; in the response string. - - msg-att-static =/ "BINARY" section-binary SP (nstring / literal8) - / "BINARY.SIZE" section-binary SP number - - partial = "<" number "." nz-number ">" - - resp-text-code =/ "UNKNOWN-CTE" - - section-binary = "[" [section-part] "]" - - - - - - - - - -Nerenberg Standards Track [Page 5] - -RFC 3516 IMAP4 Binary Content Extension April 2003 - - -8. Normative References - - [ABNF] Crocker, D., Editor, and P. Overell, "Augmented BNF for - Syntax Specifications: ABNF", RFC 2234, November 1997. - - [IMAP4rev1] Crispin, M., "Internet Message Access Protocol Version - 4rev1", RFC 3501, March 2003. - - [KEYWORD] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [MIME-IMB] Freed, N. and N. Borenstein, "Multipurpose Internet Mail - Extensions (MIME) Part One: Format of Internet Message - Bodies", RFC 2045, November 1996. - - [MIME-MHE] Moore, K., "MIME (Multipurpose Internet Mail Extensions) - Part Three: Message Header Extensions for Non-ASCII - Text", RFC 2047, November 1996. - -9. Security Considerations - - There are no known additional security issues with this extension - beyond those described in the base protocol described in [IMAP4rev1]. - -10. Intellectual Property - - 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. - - - - - - -Nerenberg Standards Track [Page 6] - -RFC 3516 IMAP4 Binary Content Extension April 2003 - - -11. Author's Address - - Lyndon Nerenberg - Orthanc Systems - 1606 - 10770 Winterburn Road - Edmonton, Alberta - Canada T5S 1T6 - - EMail: lyndon@orthanc.ab.ca - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Nerenberg Standards Track [Page 7] - -RFC 3516 IMAP4 Binary Content Extension April 2003 - - -12. 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 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. - - - - - - - - - - - - - - - - - - - -Nerenberg Standards Track [Page 8] - diff --git a/imap/docs/rfc/rfc3656.txt b/imap/docs/rfc/rfc3656.txt deleted file mode 100644 index 6c0ab5b1..00000000 --- a/imap/docs/rfc/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." -<client does local mailbox create operations> -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" -<TLS negotiation, further commands are under TLS layer> -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" -<some time goes by, and another client creates a new mailbox> -S: U01 RESERVE "user.leg.new" "mail2.example.org!u1" -<some more time passes, and the create succeeds> -S: U01 MAILBOX "user.leg.new" "mail2.example.org!u1" "leg lrswipcda" -<much more time passes, and the slave decides to send a NOOP to reset -its inactivity timer> -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://<iserver>/ - mupdate://<iserver>/<mailbox> - - 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 <iserver> 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/imap/docs/rfc/rfc3691.txt b/imap/docs/rfc/rfc3691.txt deleted file mode 100644 index 2f4e9b44..00000000 --- a/imap/docs/rfc/rfc3691.txt +++ /dev/null @@ -1,283 +0,0 @@ - - - - - - -Network Working Group A. Melnikov -Request for Comments: 3691 Isode Ltd. -Category: Standards Track February 2004 - - - Internet Message Access Protocol (IMAP) UNSELECT 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. - -Copyright Notice - - Copyright (C) The Internet Society (2004). All Rights Reserved. - -Abstract - - This document defines an UNSELECT command that can be used to close - the current mailbox in an Internet Message Access Protocol - version - 4 (IMAP4) session without expunging it. Certain types of IMAP - clients need to release resources associated with the selected - mailbox without selecting a different mailbox. While IMAP4 provides - this functionality (via a SELECT command with a nonexistent mailbox - name or reselecting the same mailbox with EXAMINE command), a more - clean solution is desirable. - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 - 2. UNSELECT command . . . . . . . . . . . . . . . . . . . . . . . 2 - 3. Security Considerations. . . . . . . . . . . . . . . . . . . . 3 - 4. Formal Syntax. . . . . . . . . . . . . . . . . . . . . . . . . 3 - 5. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 3 - 6. Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . . 3 - 7. Normative References . . . . . . . . . . . . . . . . . . . . . 4 - 8. Author's Address . . . . . . . . . . . . . . . . . . . . . . . 4 - 9. Full Copyright Statement . . . . . . . . . . . . . . . . . . . 5 - - - - - - - - - - -Melnikov Standards Track [Page 1] - -RFC 3691 IMAP UNSELECT command February 2004 - - -1. Introduction - - Certain types of IMAP clients need to release resources associated - with the selected mailbox without selecting a different mailbox. - While [IMAP4] provides this functionality (via a SELECT command with - a nonexistent mailbox name or reselecting the same mailbox with - EXAMINE command), a more clean solution is desirable. - - [IMAP4] defines the CLOSE command that closes the selected mailbox as - well as permanently removes all messages with the \Deleted flag set. - - However [IMAP4] lacks a command that simply closes the mailbox - without expunging it. This document defines the UNSELECT command for - this purpose. - - A server which supports this extension indicates this with a - capability name of "UNSELECT". - - "C:" and "S:" in examples show lines sent by the client and server - respectively. - - The keywords "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" in - this document when typed in uppercase are to be interpreted as - defined in "Key words for use in RFCs to Indicate Requirement Levels" - [KEYWORDS]. - -2. UNSELECT Command - - Arguments: none - - Responses: no specific responses for this command - - Result: OK - unselect completed, now in authenticated state - BAD - no mailbox selected, or argument supplied but - none permitted - - The UNSELECT command frees server's resources associated with the - selected mailbox and returns the server to the authenticated - state. This command performs the same actions as CLOSE, except - that no messages are permanently removed from the currently - selected mailbox. - - Example: C: A341 UNSELECT - S: A341 OK Unselect completed - - - - - - - -Melnikov Standards Track [Page 2] - -RFC 3691 IMAP UNSELECT command February 2004 - - -3. Security Considerations - - It is believed that this extension doesn't raise any additional - security concerns not already discussed in [IMAP4]. - -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]. - - 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-select /= "UNSELECT" - -5. 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 UNSELECT IMAP capabilities. IANA has added - this capability to the registry. - -6. Acknowledgments - - UNSELECT command was originally implemented by Tim Showalter in Cyrus - IMAP server. - - Also, the author of the document would like to thank Vladimir Butenko - and Mark Crispin for reminding that UNSELECT has to be documented. - Also thanks to Simon Josefsson for pointing out that there are - multiple ways to implement UNSELECT. - - - - - - - - - - - - - -Melnikov Standards Track [Page 3] - -RFC 3691 IMAP UNSELECT command February 2004 - - -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 2234, November 1997. - -8. Author's Address - - Alexey Melnikov - Isode Limited - 5 Castle Business Village - Hampton, Middlesex TW12 2BX - - EMail: Alexey.Melnikov@isode.com - URI: http://www.melnikov.ca/ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Melnikov Standards Track [Page 4] - -RFC 3691 IMAP UNSELECT command February 2004 - - -9. Full Copyright Statement - - Copyright (C) The Internet Society (2004). 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 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 Standards Track [Page 5] - diff --git a/imap/docs/rfc/rfc4314.txt b/imap/docs/rfc/rfc4314.txt deleted file mode 100644 index e73a56f2..00000000 --- a/imap/docs/rfc/rfc4314.txt +++ /dev/null @@ -1,1515 +0,0 @@ - - - - - - -Network Working Group A. Melnikov -Request for Comments: 4314 Isode Ltd. -Obsoletes: 2086 December 2005 -Category: Standards Track - - - IMAP4 Access Control List (ACL) Extension - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2005). - -Abstract - - The Access Control List (ACL) extension (RFC 2086) of the Internet - Message Access Protocol (IMAP) permits mailbox access control lists - to be retrieved and manipulated through the IMAP protocol. - - This document is a revision of RFC 2086. It defines several new - access control rights and clarifies which rights are required for - different IMAP commands. - - - - - - - - - - - - - - - - - - - - - - -Melnikov Standards Track [Page 1] - -RFC 4314 IMAP ACL December 2005 - - -Table of Contents - - 1. Introduction and Overview .......................................3 - 1.1. Conventions Used in This Document ..........................3 - 2. Access Control ..................................................3 - 2.1. Standard Rights ............................................5 - 2.1.1. Obsolete Rights .....................................5 - 2.2. Rights Defined in RFC 2086 .................................8 - 3. Access control management commands and responses ................8 - 3.1. SETACL Command .............................................8 - 3.2. DELETEACL Command ..........................................9 - 3.3. GETACL Command ............................................10 - 3.4. LISTRIGHTS Command ........................................10 - 3.5. MYRIGHTS Command ..........................................11 - 3.6. ACL Response ..............................................11 - 3.7. LISTRIGHTS Response .......................................12 - 3.8. MYRIGHTS Response .........................................12 - 4. Rights Required to Perform Different IMAP4rev1 Commands ........12 - 5. Other Considerations ...........................................17 - 5.1. Additional Requirements and Implementation Notes ..........17 - 5.1.1. Servers ............................................17 - 5.1.2. Clients ............................................18 - 5.2. Mapping of ACL Rights to READ-WRITE and READ-ONLY - Response Codes ............................................19 - 6. Security Considerations ........................................20 - 7. Formal Syntax ..................................................21 - 8. IANA Considerations ............................................22 - 9. Internationalization Considerations ............................22 - Appendix A. Changes since RFC 2086 ................................23 - Appendix B. Compatibility with RFC 2086 ...........................24 - Appendix C. Known Deficiencies ....................................24 - Appendix D. Acknowledgements ......................................25 - Normative References ..............................................25 - Informative References ............................................25 - - - - - - - - - - - - - - - - - -Melnikov Standards Track [Page 2] - -RFC 4314 IMAP ACL December 2005 - - -1. Introduction and Overview - - The ACL (Access Control List) extension of the Internet Message - Access Protocol [IMAP4] permits mailbox access control lists to be - retrieved and manipulated through the IMAP protocol. - - This document is a revision of RFC 2086 [RFC2086]. It tries to - clarify different ambiguities in RFC 2086, in particular, the use of - UTF-8 [UTF-8] in access identifiers, which rights are required for - different IMAP4 commands, and how READ-WRITE/READ-ONLY response codes - are related to ACL. - -1.1. Conventions Used in This Document - - In examples, "C:" and "S:" indicate lines sent by the client and - server respectively. - - In all examples "/" character is used as hierarchy separator. - - 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]. - - The phrase "ACL server" is just a shortcut for saying "IMAP server - that supports ACL extension as defined in this document". - -2. Access Control - - The ACL extension is present in any IMAP4 implementation that returns - "ACL" as one of the supported capabilities to the CAPABILITY command. - - A server implementation conformant to this document MUST also return - rights (see below) not defined in Section 2.2 in the "RIGHTS=" - capability. - - An access control list is a set of <access identifier,rights> pairs. - An ACL applies to a mailbox name. - - Access identifier (or just "identifier") is a UTF-8 [UTF-8] string. - The identifier "anyone" is reserved to refer to the universal - identity (all authentications, including anonymous). All user name - strings accepted by the LOGIN or AUTHENTICATE commands to - authenticate to the IMAP server are reserved as identifiers for the - corresponding users. Identifiers starting with a dash ("-") are - reserved for "negative rights", described below. All other - identifier strings are interpreted in an implementation-defined - manner. - - - - -Melnikov Standards Track [Page 3] - -RFC 4314 IMAP ACL December 2005 - - - Rights is a string listing a (possibly empty) set of alphanumeric - characters, each character listing a set of operations that is being - controlled. Lowercase letters are reserved for "standard" rights, - listed in Section 2.1. (Note that for compatibility with deployed - clients and servers uppercase rights are not allowed.) The set of - standard rights can only be extended by a standards-track document. - Digits are reserved for implementation- or site-defined rights. - - An implementation MAY tie rights together or MAY force rights to - always or never be granted to particular identifiers. For example, - in an implementation that uses UNIX mode bits, the rights "swite" are - tied, the "a" right is always granted to the owner of a mailbox and - is never granted to another user. If rights are tied in an - implementation, the implementation must be conservative in granting - rights in response to SETACL commands--unless all rights in a tied - set are specified, none of that set should be included in the ACL - entry for that identifier. A client can discover the set of rights - that may be granted to a given identifier in the ACL for a given - mailbox name by using the LISTRIGHTS command. - - It is possible for multiple identifiers in an access control list to - apply to a given user. For example, an ACL may include rights to be - granted to the identifier matching the user, one or more - implementation-defined identifiers matching groups that include the - user, and/or the identifier "anyone". How these rights are combined - to determine the user's access is implementation defined. An - implementation may choose, for example, to use the union of the - rights granted to the applicable identifiers. An implementation may - instead choose, for example, to use only those rights granted to the - most specific identifier present in the ACL. A client can determine - the set of rights granted to the logged-in user for a given mailbox - name by using the MYRIGHTS command. - - When an identifier in an ACL starts with a dash ("-"), that indicates - that associated rights are to be removed from the identifier prefixed - by the dash. This is referred to as a "negative right". This - differs from DELETEACL in that a negative right is added to the ACL - and is a part of the calculation of the rights. - - Let's assume that an identifier "fred" refers to a user with login - "fred". If the identifier "-fred" is granted the "w" right, that - indicates that the "w" right is to be removed from users matching the - identifier "fred", even though the user "fred" might have the "w" - right as a consequence of some other identifier in the ACL. A - DELETEACL of "fred" simply deletes the identifier "fred" from the - ACL; it does not affect any rights that the user "fred" may get from - another entry in the ACL, in particular it doesn't affect rights - granted to the identifier "-fred". - - - -Melnikov Standards Track [Page 4] - -RFC 4314 IMAP ACL December 2005 - - - Server implementations are not required to support "negative right" - identifiers. - -2.1. Standard Rights - - The currently defined standard rights are (note that the list below - doesn't list all commands that use a particular right): - - l - lookup (mailbox is visible to LIST/LSUB commands, SUBSCRIBE - mailbox) - r - read (SELECT the mailbox, perform STATUS) - s - keep seen/unseen information across sessions (set or clear - \SEEN flag via STORE, also set \SEEN during APPEND/COPY/ - FETCH BODY[...]) - w - write (set or clear flags other than \SEEN and \DELETED via - STORE, also set them during APPEND/COPY) - i - insert (perform APPEND, COPY into mailbox) - p - post (send mail to submission address for mailbox, - not enforced by IMAP4 itself) - k - create mailboxes (CREATE new sub-mailboxes in any - implementation-defined hierarchy, parent mailbox for the new - mailbox name in RENAME) - x - delete mailbox (DELETE mailbox, old mailbox name in RENAME) - t - delete messages (set or clear \DELETED flag via STORE, set - \DELETED flag during APPEND/COPY) - e - perform EXPUNGE and expunge as a part of CLOSE - a - administer (perform SETACL/DELETEACL/GETACL/LISTRIGHTS) - -2.1.1. Obsolete Rights - - Due to ambiguity in RFC 2086, some existing RFC 2086 server - implementations use the "c" right to control the DELETE command. - Others chose to use the "d" right to control the DELETE command. For - the former group, let's define the "create" right as union of the "k" - and "x" rights, and the "delete" right as union of the "e" and "t" - rights. For the latter group, let's define the "create" rights as a - synonym to the "k" right, and the "delete" right as union of the "e", - "t", and "x" rights. - - For compatibility with RFC 2086, this section defines two virtual - rights "d" and "c". - - If a client includes the "d" right in a rights list, then it MUST be - treated as if the client had included every member of the "delete" - right. (It is not an error for a client to specify both the "d" - right and one or more members of the "delete" right, but the effect - is no different than if just the "d" right or all members of the - "delete" right had been specified.) - - - -Melnikov Standards Track [Page 5] - -RFC 4314 IMAP ACL December 2005 - - - When any of the "delete" member rights is set in a list of rights, - the server MUST also include the "d" right when returning the list in - a MYRIGHTS or ACL response. This is to enable older clients - conforming to RFC 2086 to work with newer servers. (*) - - Example: C: A001 SeTacl INBOX/Drafts David lrswida - S: A001 OK Setacl complete - - The client has specified the "d" right in the SETACL command above - and it expands to "et" on the server: - - C: A002 getacl INBOX/Drafts - S: * ACL INBOX Fred rwipslxcetda David lrswideta - S: A002 OK Getacl complete - - If the identifier specified in the LISTRIGHTS command can be granted - any of the "delete" member rights on a mailbox, then the server MUST - include the "d" right in the corresponding LISTRIGHTS response. (*) - If the member rights aren't tied to non-member rights, then the "d" - right is returned by itself in the LISTRIGHTS response. If any of - the member rights needs to be tied to one (or more) non-member right, - then the "d" right and all of the member rights need to be tied to - the same non-member right(s) (**). - - If a client includes the "c" right in a rights list, then it MUST be - treated as if the client had included every member of the "create" - right. (It is not an error for a client to specify both the "c" - right and one or more members of the "create" right, but the effect - is no different than if just the "c" right or all members of the - "create" right had been specified.) - - When any of the "create" member rights is set in a list of rights, - the server MUST also include the "c" right when returning the list in - a MYRIGHTS or ACL response. This is to enable older clients - conforming to RFC 2086 to work with newer servers. (*) - - Example: C: A003 Setacl INBOX/Drafts Byron lrswikda - S: A001 OK Setacl complete - C: A002 getAcl INBOX/Drafts - S: * ACL INBOX Fred rwipslxcetda Byron lrswikcdeta - S: A002 OK Getacl complete - - The client has specified the "d" right in the SETACL command above - and it expands to "et" on the server: As the client has specified the - "k" right (which is a member of the "c" right), the server also - returns the "c" right. - - - - - -Melnikov Standards Track [Page 6] - -RFC 4314 IMAP ACL December 2005 - - - If the identifier specified in the LISTRIGHTS command can be granted - any of the "create" member rights on a mailbox, then the server MUST - include the "c" right in the corresponding LISTRIGHTS response. (*) - If the member rights aren't tied to non-member rights, then the "c" - right is returned by itself in the LISTRIGHTS response. If any of - the member rights needs to be tied to one (or more) non-member right, - then the "c" right and all of the member rights need to be tied to - the same non-member right(s) (**). - - Example: The server that ties the rights as follows: - - lr s w i p k x t - - and c=k - - will return: - - S: * LISTRIGHTS archive/imap anyone "" - lr s w i p k x t c d - - Example: The server that ties the rights as follows: - - lr s w i p k xte - - and c=k - - will return: - - S: * LISTRIGHTS archive/imap anyone "" - lr s w i p k xte c d - - Example: The server that ties the rights as follows: - - lr s w i p k x te - - and c=k - - will return: - - S: * LISTRIGHTS archive/imap anyone "" - lr s w i p k c x te d - - Example: The server that ties the rights as follows: - - lr swte i p k x - - and c=kx - - - - -Melnikov Standards Track [Page 7] - -RFC 4314 IMAP ACL December 2005 - - - will return: - - S: * LISTRIGHTS archive/imap anyone "" - lr swted i p k x c - - (*) Clients conforming to this document MUST ignore the virtual "d" - and "c" rights in MYRIGHTS, ACL, and LISTRIGHTS responses. - - (**) The IMAPEXT Working Group has debated this issue in great length - and after reviewing existing ACL implementations concluded that - this is a reasonable restriction. - -2.2. Rights Defined in RFC 2086 - - The "RIGHTS=" capability MUST NOT include any of the rights defined - in RFC 2086: "l", "r", "s", "w", "i", "p", "a", "c", "d", and the - digits ("0" .. "9"). - -3. Access control management commands and responses - - Servers, when processing a command that has an identifier as a - parameter (i.e., any of SETACL, DELETEACL, and LISTRIGHTS commands), - SHOULD first prepare the received identifier using "SASLprep" profile - [SASLprep] of the "stringprep" algorithm [Stringprep]. If the - preparation of the identifier fails or results in an empty string, - the server MUST refuse to perform the command with a BAD response. - Note that Section 6 recommends additional identifier's verification - steps. - -3.1. SETACL Command - - Arguments: mailbox name - identifier - access right modification - - Data: no specific data for this command - - Result: OK - setacl completed - NO - setacl failure: can't set acl - BAD - arguments invalid - - The SETACL command changes the access control list on the specified - mailbox so that the specified identifier is granted permissions as - specified in the third argument. - - The third argument is a string containing an optional plus ("+") or - minus ("-") prefix, followed by zero or more rights characters. If - the string starts with a plus, the following rights are added to any - - - -Melnikov Standards Track [Page 8] - -RFC 4314 IMAP ACL December 2005 - - - existing rights for the identifier. If the string starts with a - minus, the following rights are removed from any existing rights for - the identifier. If the string does not start with a plus or minus, - the rights replace any existing rights for the identifier. - - Note that an unrecognized right MUST cause the command to return the - BAD response. In particular, the server MUST NOT silently ignore - unrecognized rights. - - Example: C: A001 GETACL INBOX/Drafts - S: * ACL INBOX/Drafts Fred rwipslxetad Chris lrswi - S: A001 OK Getacl complete - C: A002 SETACL INBOX/Drafts Chris +cda - S: A002 OK Setacl complete - C: A003 GETACL INBOX/Drafts - S: * ACL INBOX/Drafts Fred rwipslxetad Chris lrswicdakxet - S: A003 OK Getacl complete - - - C: A035 SETACL INBOX/Drafts John lrQswicda - S: A035 BAD Uppercase rights are not allowed - - - C: A036 SETACL INBOX/Drafts John lrqswicda - S: A036 BAD The q right is not supported - -3.2. DELETEACL Command - - Arguments: mailbox name - identifier - - Data: no specific data for this command - - Result: OK - deleteacl completed - NO - deleteacl failure: can't delete acl - BAD - arguments invalid - - The DELETEACL command removes any <identifier,rights> pair for the - specified identifier from the access control list for the specified - mailbox. - - Example: C: B001 getacl INBOX - S: * ACL INBOX Fred rwipslxetad -Fred wetd $team w - S: B001 OK Getacl complete - C: B002 DeleteAcl INBOX Fred - S: B002 OK Deleteacl complete - - - - - -Melnikov Standards Track [Page 9] - -RFC 4314 IMAP ACL December 2005 - - - C: B003 GETACL INBOX - S: * ACL INBOX -Fred wetd $team w - S: B003 OK Getacl complete - -3.3. GETACL Command - - Arguments: mailbox name - - Data: untagged responses: ACL - - Result: OK - getacl completed - NO - getacl failure: can't get acl - BAD - arguments invalid - - The GETACL command returns the access control list for mailbox in an - untagged ACL response. - - Some implementations MAY permit multiple forms of an identifier to - reference the same IMAP account. Usually, such implementations will - have a canonical form that is stored internally. An ACL response - caused by a GETACL command MAY include a canonicalized form of the - identifier that might be different from the one used in the - corresponding SETACL command. - - Example: C: A002 GETACL INBOX - S: * ACL INBOX Fred rwipsldexta - S: A002 OK Getacl complete - -3.4. LISTRIGHTS Command - - Arguments: mailbox name - identifier - - Data: untagged responses: LISTRIGHTS - - Result: OK - listrights completed - NO - listrights failure: can't get rights list - BAD - arguments invalid - - The LISTRIGHTS command takes a mailbox name and an identifier and - returns information about what rights can be granted to the - identifier in the ACL for the mailbox. - - Some implementations MAY permit multiple forms of an identifier to - reference the same IMAP account. Usually, such implementations will - have a canonical form that is stored internally. A LISTRIGHTS - - - - - -Melnikov Standards Track [Page 10] - -RFC 4314 IMAP ACL December 2005 - - - response caused by a LISTRIGHTS command MUST always return the same - form of an identifier as specified by the client. This is to allow - the client to correlate the response with the command. - - Example: C: a001 LISTRIGHTS ~/Mail/saved smith - S: * LISTRIGHTS ~/Mail/saved smith la r swicdkxte - S: a001 OK Listrights completed - - Example: C: a005 listrights archive/imap anyone - S: * LISTRIGHTS archive.imap anyone "" - l r s w i p k x t e c d a 0 1 2 3 4 5 6 7 8 9 - S: a005 Listrights successful - -3.5. MYRIGHTS Command - - Arguments: mailbox name - - Data: untagged responses: MYRIGHTS - - Result: OK - myrights completed - NO - myrights failure: can't get rights - BAD - arguments invalid - - The MYRIGHTS command returns the set of rights that the user has to - mailbox in an untagged MYRIGHTS reply. - - Example: C: A003 MYRIGHTS INBOX - S: * MYRIGHTS INBOX rwiptsldaex - S: A003 OK Myrights complete - -3.6. ACL Response - - Data: mailbox name - zero or more identifier rights pairs - - The ACL response occurs as a result of a GETACL command. The first - string is the mailbox name for which this ACL applies. This is - followed by zero or more pairs of strings; each pair contains the - identifier for which the entry applies followed by the set of rights - that the identifier has. - - Section 2.1.1 details additional server requirements related to - handling of the virtual "d" and "c" rights. - - - - - - - - -Melnikov Standards Track [Page 11] - -RFC 4314 IMAP ACL December 2005 - - -3.7. LISTRIGHTS Response - - Data: mailbox name - identifier - required rights - list of optional rights - - The LISTRIGHTS response occurs as a result of a LISTRIGHTS command. - The first two strings are the mailbox name and identifier for which - this rights list applies. Following the identifier is a string - containing the (possibly empty) set of rights the identifier will - always be granted in the mailbox. - - Following this are zero or more strings each containing a set of - rights the identifier can be granted in the mailbox. Rights - mentioned in the same string are tied together. The server MUST - either grant all tied rights to the identifier in the mailbox or - grant none. Section 2.1.1 details additional server requirements - related to handling of the virtual "d" and "c" rights. - - The same right MUST NOT be listed more than once in the LISTRIGHTS - command. - -3.8. MYRIGHTS Response - - Data: mailbox name - rights - - The MYRIGHTS response occurs as a result of a MYRIGHTS command. The - first string is the mailbox name for which these rights apply. The - second string is the set of rights that the client has. - - Section 2.1.1 details additional server requirements related to - handling of the virtual "d" and "c" rights. - -4. Rights Required to Perform Different IMAP4rev1 Commands - - Before executing a command, an ACL-compliant server MUST check which - rights are required to perform it. This section groups command by - functions they perform and list the rights required. It also gives - the detailed description of any special processing required. - - For the purpose of this section the UID counterpart of a command is - considered to be the same command, e.g., both UID COPY and COPY - commands require the same set of rights. - - - - - - -Melnikov Standards Track [Page 12] - -RFC 4314 IMAP ACL December 2005 - - - The table below summarizes different rights or their combinations - that are required in order to perform different IMAP operations. As - it is not always possible to express complex right checking and - interactions, the description after the table should be used as the - primary reference. - - +-------------------+---+---+---+---+---+---+---+---+---+---+---+---+ - |Operations\Rights | l | r | s | w | i | k | x | t | e | a |Any|Non| - +-------------------+---+---+---+---+---+---+---+---+---+---+---+---+ - | commands in authenticated state | - +-------------------------------------------------------------------+ - | LIST | + | | | | | | | | | | | | - | SUBSCRIBE | * | | | | | | | | | | | * | - | UNSUBSCRIBE | | | | | | | | | | | | + | - | LSUB | * | | | | | | | | | | | * | - |CREATE (for parent)| | | | | | + | | | | | | | - | DELETE | | ? | | | | | + | ? | ? | | | | - | RENAME | | | | | | + | + | | | | | | - | SELECT/EXAMINE | | + | | | | | | | | | | | - | STATUS | | + | | | | | | | | | | | - | SETACL/DELETEACL | | | | | | | | | | + | | | - | GETACL/LISTRIGHTS | | | | | | | | | | + | | | - | MYRIGHTS | | | | | | | | | | | + | | - | APPEND | | | ? | ? | + | | | ? | | | | | - +-------------------------------------------------------------------+ - | commands in selected state | - +-------------------------------------------------------------------+ - | COPY | | | ? | ? | + | | | ? | | | | | - | EXPUNGE | | | | | | | | | + | | | | - | CLOSE | | | | | | | | | ? | | | | - | FETCH | | | ? | | | | | | | | | | - | STORE flags | | | ? | ? | | | | ? | | | | | - +-------------------+---+---+---+---+---+---+---+---+---+---+---+---+ - - Note: for all commands in the selected state, the "r" is implied, - because it is required to SELECT/EXAMINE a mailbox. Servers are not - required to check presence of the "r" right once a mailbox is - successfully selected. - - Legend: - + - The right is required - * - Only one of the rights marked with * is required - (see description below) - ? - The right is OPTIONAL (see description below) - "Any" - at least one of the "l", "r", "i", "k", "x", "a" rights is - required - "Non" - No rights required to perform the command - - - - -Melnikov Standards Track [Page 13] - -RFC 4314 IMAP ACL December 2005 - - - Listing and subscribing/unsubscribing mailboxes: - LIST - "l" right is required. However, unlike other commands - (e.g., SELECT) the server MUST NOT return a NO response if it - can't list a mailbox. - Note that if the user has "l" right to a mailbox "A/B", but not to - its parent mailbox "A", the LIST command should behave as if the - mailbox "A" doesn't exist, for example: - - C: A777 LIST "" * - S: * LIST (\NoInferiors) "/" "A/B" - S: * LIST () "/" "C" - S: * LIST (\NoInferiors) "/" "C/D" - S: A777 OK LIST completed - - - SUBSCRIBE - "l" right is required only if the server checks for - mailbox existence when performing SUBSCRIBE. - - UNSUBSCRIBE - no rights required to perform this operation. - - LSUB - "l" right is required only if the server checks for mailbox - existence when performing SUBSCRIBE. However, unlike other - commands (e.g., SELECT) the server MUST NOT return a NO response - if it can't list a subscribed mailbox. - - Mailbox management: - CREATE - "k" right on a nearest existing parent mailbox. When a - new mailbox is created, it SHOULD inherit the ACL from the parent - mailbox (if one exists) in the defined hierarchy. - - DELETE - "x" right on the mailbox. Note that some servers don't - allow to delete a non-empty mailbox. If this is the case, the - user would also need "r", "e", and "t" rights, in order to open - the mailbox and empty it. - - The DELETE command MUST delete the ACL associated with the deleted - mailbox. - - RENAME - Moving a mailbox from one parent to another requires the - "x" right on the mailbox itself and the "k" right for the new - parent. For example, if the user wants to rename the mailbox - named "A/B/C" to "D/E", the user must have the "x" right for the - mailbox "A/B/C" and the "k" right for the mailbox "D". - The RENAME command SHOULD NOT change the ACLs on the renamed - mailbox and submailboxes. - - - - - - -Melnikov Standards Track [Page 14] - -RFC 4314 IMAP ACL December 2005 - - - Copying or appending messages: - Before performing a COPY/APPEND command, the server MUST check if - the user has "i" right for the target mailbox. If the user - doesn't have "i" right, the operation fails. Otherwise for each - copied/appended message the server MUST check if the user has - "t" right - when the message has \Deleted flag set - "s" right - when the message has \Seen flag set - "w" right - for all other message flags. - Only when the user has a particular right are the corresponding - flags stored for the newly created message. The server MUST NOT - fail a COPY/APPEND if the user has no rights to set a particular - flag. - - Example: C: A003 MYRIGHTS TargetMailbox - S: * MYRIGHTS TargetMailbox rwis - S: A003 OK Myrights complete - - C: A004 FETCH 1:3 (FLAGS) - S: * 1 FETCH (FLAGS (\Draft \Deleted) - S: * 2 FETCH (FLAGS (\Answered) - S: * 3 FETCH (FLAGS ($Forwarded \Seen) - S: A004 OK Fetch Completed - - C: A005 COPY 1:3 TargetMailbox - S: A005 OK Copy completed - - C: A006 SELECT TargetMailbox - ... - S: A006 Select Completed - - Let's assume that the copied messages received message numbers - 77:79. - - C: A007 FETCH 77:79 (FLAGS) - S: * 77 FETCH (FLAGS (\Draft)) - S: * 78 FETCH (FLAGS (\Answered)) - S: * 79 FETCH (FLAGS ($Forwarded \Seen)) - S: A007 OK Fetch Completed - - \Deleted flag was lost on COPY, as the user has no "t" right in - the target mailbox. - If the MYRIGHTS command with the tag A003 would have returned: - - S: * MYRIGHTS TargetMailbox rsti - - the response from the FETCH with the tag A007 would have been: - - C: A007 FETCH 77:79 (FLAGS) - - - -Melnikov Standards Track [Page 15] - -RFC 4314 IMAP ACL December 2005 - - - S: * 77 FETCH (FLAGS (\Deleted)) - S: * 78 FETCH (FLAGS ()) - S: * 79 FETCH (FLAGS (\Seen)) - S: A007 OK Fetch Completed - - In the latter case, \Answered, $Forwarded, and \Draft flags were - lost on COPY, as the user has no "w" right in the target mailbox. - - Expunging the selected mailbox: - EXPUNGE - "e" right on the selected mailbox. - - CLOSE - "e" right on the selected mailbox. If the server is - unable to expunge the mailbox because the user doesn't have the - "e" right, the server MUST ignore the expunge request, close the - mailbox, and return the tagged OK response. - - Fetch information about a mailbox and its messages: - SELECT/EXAMINE/STATUS - "r" right on the mailbox. - - FETCH - A FETCH request that implies setting \Seen flag MUST NOT - set it, if the current user doesn't have "s" right. - - Changing flags: - STORE - the server MUST check if the user has - "t" right - when the user modifies \Deleted flag - "s" right - when the user modifies \Seen flag - "w" right - for all other message flags. - STORE operation SHOULD NOT fail if the user has rights to modify - at least one flag specified in the STORE, as the tagged NO - response to a STORE command is not handled very well by deployed - clients. - - Changing ACLs: - SETACL/DELETEACL - "a" right on the mailbox. - - Reading ACLs: - GETACL - "a" right on the mailbox. - - MYRIGHTS - any of the following rights is required to perform the - operation: "l", "r", "i", "k", "x", "a". - - LISTRIGHTS - "a" right on the mailbox. - - - - - - - - - -Melnikov Standards Track [Page 16] - -RFC 4314 IMAP ACL December 2005 - - -5. Other Considerations - -5.1. Additional Requirements and Implementation Notes - -5.1.1. Servers - - This document defines an additional capability that is used to - announce the list of extra rights (excluding the ones defined in RFC - 2086) supported by the server. The set of rights MUST include "t", - "e", "x", and "k". Note that the extra rights can appear in any - order. - - Example: C: 1 capability - S: * CAPABILITY IMAP4REV1 STARTTLS LITERAL+ - ACL RIGHTS=texk - S: 1 OK completed - - Any server implementing an ACL extension MUST accurately reflect the - current user's rights in FLAGS and PERMANENTFLAGS responses. - - Example: C: A142 SELECT INBOX - S: * 172 EXISTS - S: * 1 RECENT - S: * OK [UNSEEN 12] Message 12 is first unseen - S: * OK [UIDVALIDITY 3857529045] UIDs valid - S: * OK [UIDNEXT 4392] Predicted next UID - S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) - S: * OK [PERMANENTFLAGS (\Seen \Answered \Flagged \*)] L - S: A142 OK [READ-WRITE] SELECT completed - C: A143 MYRIGHTS INBOX - S: * MYRIGHTS INBOX lrwis - S: A143 OK completed - - Note that in order to get better performance the client MAY pipeline - SELECT and MYRIGHTS commands: - - C: A142 SELECT INBOX - C: A143 MYRIGHTS INBOX - S: * 172 EXISTS - S: * 1 RECENT - S: * OK [UNSEEN 12] Message 12 is first unseen - S: * OK [UIDVALIDITY 3857529045] UIDs valid - S: * OK [UIDNEXT 4392] Predicted next UID - S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) - S: * OK [PERMANENTFLAGS (\Seen \Answered \Flagged \*)] L - S: A142 OK [READ-WRITE] SELECT completed - S: * MYRIGHTS INBOX lrwis - S: A143 OK completed - - - -Melnikov Standards Track [Page 17] - -RFC 4314 IMAP ACL December 2005 - - - Servers MAY cache the rights a user has on a mailbox when the mailbox - is selected, so that if a client's rights on a mailbox are changed - with SETACL or DELETEACL, commands specific to the selected state - (e.g., STORE, EXPUNGE) might not reflect the changed rights until the - mailbox is re-selected. If the server checks the rights on each - command, then it SHOULD send FLAGS and PERMANENTFLAGS responses if - they have changed. If such server detects that the user no longer - has read access to the mailbox, it MAY send an untagged BYE response - and close connection. It MAY also refuse to execute all commands - specific to the selected state until the mailbox is closed; however, - server implementors should note that most clients don't handle NO - responses very well. - - An ACL server MAY modify one or more ACLs for one or more identifiers - as a side effect of modifying the ACL specified in a - SETACL/DELETEACL. If the server does that, it MUST send untagged ACL - response(s) to notify the client about the changes made. - - An ACL server implementation MUST treat received ACL modification - commands as a possible ambiguity with respect to subsequent commands - affected by the ACL, as described in Section 5.5 of [IMAP4]. Hence a - pipeline SETACL + MYRIGHTS is an ambiguity with respect to the - server, meaning that the server must execute the SETACL command to - completion before the MYRIGHTS. However, clients are permitted to - send such a pipeline. - -5.1.2. Clients - - The following requirement is put on clients in order to allow for - future extensibility. A client implementation that allows a user to - read and update ACLs MUST preserve unrecognized rights that it - doesn't allow the user to change. That is, if the client - - 1) can read ACLs - and - 2) can update ACLs - but - 3) doesn't allow the user to change the rights the client doesn't - recognize, then it MUST preserve unrecognized rights. - - Otherwise the client could risk unintentionally removing permissions - it doesn't understand. - - - - - - - - - -Melnikov Standards Track [Page 18] - -RFC 4314 IMAP ACL December 2005 - - -5.2. Mapping of ACL Rights to READ-WRITE and READ-ONLY Response Codes - - A particular ACL server implementation MAY allow "shared multiuser - access" to some mailboxes. "Shared multiuser access" to a mailbox - means that multiple different users are able to access the same - mailbox, if they have proper access rights. "Shared multiuser - access" to the mailbox doesn't mean that the ACL for the mailbox is - currently set to allow access by multiple users. Let's denote a - "shared multiuser write access" as a "shared multiuser access" when a - user can be granted flag modification rights (any of "w", "s", or - "t"). - - Section 4 describes which rights are required for modifying different - flags. - - If the ACL server implements some flags as shared for a mailbox - (i.e., the ACL for the mailbox MAY be set up so that changes to those - flags are visible to another user), let's call the set of rights - associated with these flags (as described in Section 4) for that - mailbox collectively as "shared flag rights". Note that the "shared - flag rights" set MAY be different for different mailboxes. - - If the server doesn't support "shared multiuser write access" to a - mailbox or doesn't implement shared flags on the mailbox, "shared - flag rights" for the mailbox is defined to be the empty set. - - Example 1: Mailbox "banan" allows "shared multiuser write access" and - implements flags \Deleted, \Answered, and $MDNSent as - shared flags. "Shared flag rights" for the mailbox "banan" - is a set containing flags "t" (because system flag - \Deleted requires "t" right) and "w" (because both - \Answered and $MDNSent require "w" right). - - Example 2: Mailbox "apple" allows "shared multiuser write access" and - implements \Seen system flag as shared flag. "Shared flag - rights" for the mailbox "apple" contains "s" right - because system flag \Seen requires "s" right. - - Example 3: Mailbox "pear" allows "shared multiuser write access" and - implements flags \Seen, \Draft as shared flags. "Shared - flag rights" for the mailbox "apple" is a set containing - flags "s" (because system flag \Seen requires "s" right) - and "w" (because system flag \Draft requires "w" right). - - The server MUST include a READ-ONLY response code in the tagged OK - response to a SELECT command if none of the following rights is - granted to the current user: - - - - -Melnikov Standards Track [Page 19] - -RFC 4314 IMAP ACL December 2005 - - - "i", "e", and "shared flag rights"(***). - - The server SHOULD include a READ-WRITE response code in the tagged OK - response if at least one of the "i", "e", or "shared flag - rights"(***) is granted to the current user. - - (***) Note that a future extension to this document can extend the - list of rights that causes the server to return the READ-WRITE - response code. - - Example 1 (continued): The user that has "lrs" rights for the mailbox - "banan". The server returns READ-ONLY - response code on SELECT, as none of "iewt" - rights is granted to the user. - - Example 2 (continued): The user that has "rit" rights for the mailbox - "apple". The server returns READ-WRITE - response code on SELECT, as the user has "i" - right. - - Example 3 (continued): The user that has "rset" rights for the - mailbox "pear". The server returns READ-WRITE - response code on SELECT, as the user has "e" - and "s" rights. - -6. Security Considerations - - An implementation MUST make sure the ACL commands themselves do not - give information about mailboxes with appropriately restricted ACLs. - For example, when a user agent executes a GETACL command on a mailbox - that the user has no permission to LIST, the server would respond to - that request with the same error that would be used if the mailbox - did not exist, thus revealing no existence information, much less the - mailbox's ACL. - - IMAP clients implementing ACL that are able to modify ACLs SHOULD - warn a user that wants to give full access (or even just the "a" - right) to the special identifier "anyone". - - This document relies on [SASLprep] to describe steps required to - perform identifier canonicalization (preparation). The preparation - algorithm in SASLprep was specifically designed such that its output - is canonical, and it is well-formed. However, due to an anomaly - [PR29] in the specification of Unicode normalization, canonical - equivalence is not guaranteed for a select few character sequences. - Identifiers prepared with SASLprep can be stored and returned by an - ACL server. The anomaly affects ACL manipulation and evaluation of - identifiers containing the selected character sequences. These - - - -Melnikov Standards Track [Page 20] - -RFC 4314 IMAP ACL December 2005 - - - sequences, however, do not appear in well-formed text. In order to - address this problem, an ACL server MAY reject identifiers containing - sequences described in [PR29] by sending the tagged BAD response. - This is in addition to the requirement to reject identifiers that - fail SASLprep preparation as described in Section 3. - - Other security considerations described in [IMAP4] are relevant to - this document. In particular, ACL information is sent in the clear - over the network unless confidentiality protection is negotiated. - - This can be accomplished either by the use of STARTTLS, negotiated - privacy protection in the AUTHENTICATE command, or some other - protection mechanism. - -7. Formal Syntax - - Formal syntax is defined using ABNF [ABNF], extending the ABNF rules - in Section 9 of [IMAP4]. Elements not defined here can be found in - [ABNF] and [IMAP4]. - - Except as noted otherwise, all alphabetic characters are case - insensitive. The use of uppercase or lowercase characters to define - token strings is for editorial clarity only. Implementations MUST - accept these strings in a case-insensitive fashion. - - LOWER-ALPHA = %x61-7A ;; a-z - - acl-data = "ACL" SP mailbox *(SP identifier SP - rights) - - capability =/ rights-capa - ;;capability is defined in [IMAP4] - - command-auth =/ setacl / deleteacl / getacl / - listrights / myrights - ;;command-auth is defined in [IMAP4] - - deleteacl = "DELETEACL" SP mailbox SP identifier - - getacl = "GETACL" SP mailbox - - identifier = astring - - listrights = "LISTRIGHTS" SP mailbox SP identifier - - listrights-data = "LISTRIGHTS" SP mailbox SP identifier - SP rights *(SP rights) - - - - -Melnikov Standards Track [Page 21] - -RFC 4314 IMAP ACL December 2005 - - - mailbox-data =/ acl-data / listrights-data / myrights-data - ;;mailbox-data is defined in [IMAP4] - - mod-rights = astring - ;; +rights to add, -rights to remove - ;; rights to replace - - myrights = "MYRIGHTS" SP mailbox - - myrights-data = "MYRIGHTS" SP mailbox SP rights - - new-rights = 1*LOWER-ALPHA - ;; MUST include "t", "e", "x", and "k". - ;; MUST NOT include standard rights listed - ;; in section 2.2 - - rights = astring - ;; only lowercase ASCII letters and digits - ;; are allowed. - - rights-capa = "RIGHTS=" new-rights - ;; RIGHTS=... capability - - setacl = "SETACL" SP mailbox SP identifier - SP mod-rights - -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 RIGHTS= IMAP capability. IANA has added - this capability to the registry. - -9. Internationalization Considerations - - Section 3 states requirements on servers regarding - internationalization of identifiers. - - - - - - - - - - -Melnikov Standards Track [Page 22] - -RFC 4314 IMAP ACL December 2005 - - -Appendix A. Changes since RFC 2086 - - 1. Changed the charset of "identifier" from US-ASCII to UTF-8. - 2. Specified that mailbox deletion is controlled by the "x" right - and EXPUNGE is controlled by the "e" right. - 3. Added the "t" right that controls STORE \Deleted. Redefined the - "d" right to be a macro for "e", "t", and possibly "x". - 4. Added the "k" right that controls CREATE. Redefined the "c" - right to be a macro for "k" and possibly "x". - 5. Specified that the "a" right also controls DELETEACL. - 6. Specified that the "r" right also controls STATUS. - 7. Removed the requirement to check the "r" right for CHECK, SEARCH - and FETCH, as this is required for SELECT/EXAMINE to be - successful. - 8. LISTRIGHTS requires the "a" right on the mailbox (same as - SETACL). - 9. Deleted "PARTIAL", this is a deprecated feature of RFC 1730. - 10. Specified that the "w" right controls setting flags other than - \Seen and \Deleted on APPEND. Also specified that the "s" right - controls the \Seen flag and that the "t" right controls the - \Deleted flag. - 11. Specified that SUBSCRIBE is NOT allowed with the "r" right. - 12. Specified that the "l" right controls SUBSCRIBE. - 13. GETACL is NOT allowed with the "r" right, even though there are - several implementations that allows that. If a user only has - "r" right, GETACL can disclose information about identifiers - existing on the mail system. - 14. Clarified that RENAME requires the "k" right for the new parent - and the "x" right for the old name. - 15. Added new section that describes which rights are required - and/or checked when performing various IMAP commands. - 16. Added mail client security considerations when dealing with - special identifier "anyone". - 17. Clarified that negative rights are not the same as DELETEACL. - 18. Added "Compatibility with RFC 2086" section. - 19. Added section about mapping of ACL rights to READ-WRITE and - READ-ONLY response codes. - 20. Changed BNF to ABNF. - 21. Added "Implementation Notes" section. - 22. Updated "References" section. - 23. Added more examples. - 24. Clarified when the virtual "c" and "d" rights are returned in - ACL, MYRIGHTS, and LISTRIGHTS responses. - - - - - - - - -Melnikov Standards Track [Page 23] - -RFC 4314 IMAP ACL December 2005 - - -Appendix B. Compatibility with RFC 2086 - - This non-normative section gives guidelines as to how an existing RFC - 2086 server implementation may be updated to comply with this - document. - - This document splits the "d" right into several new different rights: - "t", "e", and possibly "x" (see Section 2.1.1 for more details). The - "d" right remains for backward-compatibility, but it is a virtual - right. There are two approaches for RFC 2086 server implementors to - handle the "d" right and the new rights that have replaced it: - - a. Tie "t", "e" (and possibly "x) together - almost no changes. - b. Implement separate "x", "t" and "e". Return the "d" right in a - MYRIGHTS response or an ACL response containing ACL information - when any of the "t", "e" (and "x") is granted. - - In a similar manner this document splits the "c" right into several - new different rights: "k" and possibly "x" (see Section 2.1.1 for - more details). The "c" right remains for backwards-compatibility but - it is a virtual right. Again, RFC 2086 server implementors can - choose to tie rights or to implement separate rights, as described - above. - - Also check Sections 5.1.1 and 5.1.2, as well as Appendix A, to see - other changes required. Server implementors should check which - rights are required to invoke different IMAP4 commands as described - in Section 4. - -Appendix C. Known Deficiencies - - This specification has some known deficiencies including: - - 1. This is inadequate to provide complete read-write access to - mailboxes protected by Unix-style rights bits because there is no - equivalent to "chown" and "chgrp" commands nor is there a good - way to discover such limitations are present. - 2. Because this extension leaves the specific semantics of how - rights are combined by the server as implementation defined, the - ability to build a user-friendly interface is limited. - 3. Users, groups, and special identifiers (e.g., anyone) exist in - the same namespace. - - The work-in-progress "ACL2" extension is intended to redesign this - extension to address these deficiencies without the constraint of - backward-compatibility and may eventually supercede this facility. - - - - - -Melnikov Standards Track [Page 24] - -RFC 4314 IMAP ACL December 2005 - - - However, RFC 2086 is deployed in multiple implementations so this - intermediate step, which fixes the straightforward deficiencies in a - backward-compatible fashion, is considered worthwhile. - -Appendix D. Acknowledgements - - This document is a revision of RFC 2086 written by John G. Myers. - - Editor appreciates comments received from Mark Crispin, Chris Newman, - Cyrus Daboo, John G. Myers, Dave Cridland, Ken Murchison, Steve Hole, - Vladimir Butenko, Larry Greenfield, Robert Siemborski, Harrie - Hazewinkel, Philip Guenther, Brian Candler, Curtis King, Lyndon - Nerenberg, Lisa Dusseault, Arnt Gulbrandsen, and other participants - of the IMAPEXT working group. - -Normative References - - [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", RFC 4234, October 2005. - - [IMAP4] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION - 4rev1", RFC 3501, March 2003. - - [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO - 10646", STD 63, RFC 3629, November 2003. - - [Stringprep] Hoffman, P. and M. Blanchet, "Preparation of - Internationalized Strings ("stringprep")", RFC 3454, - December 2002. - - [SASLprep] Zeilenga, K., "SASLprep: Stringprep Profile for User - Names and Passwords", RFC 4013, February 2005. - -Informative References - - [RFC2086] Myers, J., "IMAP4 ACL extension", RFC 2086, - January 1997. - - [PR29] "Public Review Issue #29: Normalization Issue", - February 2004, - <http://www.unicode.org/review/pr-29.html>. - - - - - - - -Melnikov Standards Track [Page 25] - -RFC 4314 IMAP ACL December 2005 - - -Author's Address - - Alexey Melnikov - Isode Ltd. - 5 Castle Business Village - 36 Station Road - Hampton, Middlesex TW12 2BX - GB - - EMail: alexey.melnikov@isode.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Melnikov Standards Track [Page 26] - -RFC 4314 IMAP ACL December 2005 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2005). - - 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 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 Standards Track [Page 27] - diff --git a/imap/docs/rfc/rfc4315.txt b/imap/docs/rfc/rfc4315.txt deleted file mode 100644 index c026f422..00000000 --- a/imap/docs/rfc/rfc4315.txt +++ /dev/null @@ -1,451 +0,0 @@ - - - - - - -Network Working Group M. Crispin -Request for Comments: 4315 December 2005 -Obsoletes: 2359 -Category: Standards Track - - - Internet Message Access Protocol (IMAP) - UIDPLUS extension - -Status of This Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2005). - -Abstract - - The UIDPLUS extension of the Internet Message Access Protocol (IMAP) - provides a set of features intended to reduce the amount of time and - resources used by some client operations. The features in UIDPLUS - are primarily intended for disconnected-use clients. - -1. Introduction and Overview - - The UIDPLUS extension is present in any IMAP server implementation - that returns "UIDPLUS" as one of the supported capabilities to the - CAPABILITY command. - - The UIDPLUS extension defines an additional command. In addition, - this document recommends new status response codes in IMAP that - SHOULD be returned by all server implementations, regardless of - whether or not the UIDPLUS extension is implemented. - - The added facilities of the features in UIDPLUS are optimizations; - clients can provide equivalent functionality, albeit less - efficiently, by using facilities in the base protocol. - -1.1. Conventions Used in This Document - - In examples, "C:" and "S:" indicate lines sent by the client and - server, respectively. - - - - - -Crispin Standards Track [Page 1] - -RFC 4315 IMAP - UIDPLUS Extension December 2005 - - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "MAY", and "OPTIONAL" in this document are to - be interpreted as described in [KEYWORDS]. - - A "UID set" is similar to the [IMAP] sequence set; however, the "*" - value for a sequence number is not permitted. - -2. Additional Commands - - The following command definition is an extension to [IMAP] section - 6.4. - -2.1. UID EXPUNGE Command - - Arguments: sequence set - - Data: untagged responses: EXPUNGE - - Result: OK - expunge completed - NO - expunge failure (e.g., permission denied) - BAD - command unknown or arguments invalid - - The UID EXPUNGE command permanently removes all messages that both - have the \Deleted flag set and have a UID that is included in the - specified sequence set from the currently selected mailbox. If a - message either does not have the \Deleted flag set or has a UID - that is not included in the specified sequence set, it is not - affected. - - This command is particularly useful for disconnected use clients. - By using UID EXPUNGE instead of EXPUNGE when resynchronizing with - the server, the client can ensure that it does not inadvertantly - remove 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. - - If the server does not support the UIDPLUS capability, the client - should fall back to using the STORE command to temporarily remove - the \Deleted flag from messages it does not want to remove, then - issuing the EXPUNGE command. Finally, the client should use the - STORE command to restore the \Deleted flag on the messages in - which it was temporarily removed. - - Alternatively, the client may fall back to using just the EXPUNGE - command, risking the unintended removal of some messages. - - - - - - -Crispin Standards Track [Page 2] - -RFC 4315 IMAP - UIDPLUS Extension December 2005 - - - Example: C: A003 UID EXPUNGE 3000:3002 - S: * 3 EXPUNGE - S: * 3 EXPUNGE - S: * 3 EXPUNGE - S: A003 OK UID EXPUNGE completed - -3. Additional Response Codes - - The following response codes are extensions to the response codes - defined in [IMAP] section 7.1. With limited exceptions, discussed - below, server implementations that advertise the UIDPLUS extension - SHOULD return these response codes. - - In the case of a mailbox that has permissions set so that the client - can COPY or APPEND to the mailbox, but not SELECT or EXAMINE it, the - server SHOULD NOT send an APPENDUID or COPYUID response code as it - would disclose information about the mailbox. - - In the case of a mailbox that has UIDNOTSTICKY status (as defined - below), the server MAY omit the APPENDUID or COPYUID response code as - it is not meaningful. - - If the server does not return the APPENDUID or COPYUID response - codes, the client can discover this information by selecting the - destination mailbox. The location of messages placed in the - destination mailbox by COPY or APPEND can be determined by using - FETCH and/or SEARCH commands (e.g., for Message-ID or some unique - marker placed in the message in an APPEND). - - APPENDUID - - Followed by the UIDVALIDITY of the destination mailbox and the UID - assigned to the appended message in the destination mailbox, - indicates that the message has been appended to the destination - mailbox with that UID. - - If the server also supports the [MULTIAPPEND] extension, and if - multiple messages were appended in the APPEND command, then the - second value is a UID set containing the UIDs assigned to the - appended messages, in the order they were transmitted in the - APPEND command. This UID set may not contain extraneous UIDs or - the symbol "*". - - Note: the UID set form of the APPENDUID response code MUST NOT - be used if only a single message was appended. In particular, - a server MUST NOT send a range such as 123:123. This is - because a client that does not support [MULTIAPPEND] expects - only a single UID and not a UID set. - - - -Crispin Standards Track [Page 3] - -RFC 4315 IMAP - UIDPLUS Extension December 2005 - - - UIDs are assigned in strictly ascending order in the mailbox - (refer to [IMAP], section 2.3.1.1) and UID ranges are as in - [IMAP]; in particular, note that a range of 12:10 is exactly - equivalent to 10:12 and refers to the sequence 10,11,12. - - This response code is returned in a tagged OK response to the - APPEND command. - - COPYUID - - Followed by the UIDVALIDITY of the destination mailbox, a UID set - containing the UIDs of the message(s) in the source mailbox that - were copied to the destination mailbox and containing the UIDs - assigned to the copied message(s) in the destination mailbox, - indicates that the message(s) have been copied to the destination - mailbox with the stated UID(s). - - The source UID set is in the order the message(s) were copied; the - destination UID set corresponds to the source UID set and is in - the same order. Neither of the UID sets may contain extraneous - UIDs or the symbol "*". - - UIDs are assigned in strictly ascending order in the mailbox - (refer to [IMAP], section 2.3.1.1) and UID ranges are as in - [IMAP]; in particular, note that a range of 12:10 is exactly - equivalent to 10:12 and refers to the sequence 10,11,12. - - This response code is returned in a tagged OK response to the COPY - command. - - UIDNOTSTICKY - - The selected mailbox is supported by a mail store that does not - support persistent UIDs; that is, UIDVALIDITY will be different - each time the mailbox is selected. Consequently, APPEND or COPY - to this mailbox will not return an APPENDUID or COPYUID response - code. - - This response code is returned in an untagged NO response to the - SELECT command. - - Note: servers SHOULD NOT have any UIDNOTSTICKY mail stores. - This facility exists to support legacy mail stores in which it - is technically infeasible to support persistent UIDs. This - should be avoided when designing new mail stores. - - - - - - -Crispin Standards Track [Page 4] - -RFC 4315 IMAP - UIDPLUS Extension December 2005 - - - Example: C: A003 APPEND saved-messages (\Seen) {297} - C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) - C: From: Fred Foobar <foobar@example.com> - C: Subject: afternoon meeting - C: To: mooch@example.com - C: Message-Id: <B27397-0100000@example.com> - C: MIME-Version: 1.0 - C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII - C: - C: Hello Joe, do you think we can meet at 3:30 tomorrow? - C: - S: A003 OK [APPENDUID 38505 3955] APPEND completed - C: A004 COPY 2:4 meeting - S: A004 OK [COPYUID 38505 304,319:320 3956:3958] Done - C: A005 UID COPY 305:310 meeting - S: A005 OK No matching messages, so nothing copied - C: A006 COPY 2 funny - S: A006 OK Done - C: A007 SELECT funny - S: * 1 EXISTS - S: * 1 RECENT - S: * OK [UNSEEN 1] Message 1 is first unseen - S: * OK [UIDVALIDITY 3857529045] Validity session-only - S: * OK [UIDNEXT 2] Predicted next UID - S: * NO [UIDNOTSTICKY] Non-persistent UIDs - S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) - S: * OK [PERMANENTFLAGS (\Deleted \Seen)] Limited - S: A007 OK [READ-WRITE] SELECT completed - - In this example, A003 and A004 demonstrate successful appending and - copying to a mailbox that returns the UIDs assigned to the messages. - A005 is an example in which no messages were copied; this is because - in A003, we see that message 2 had UID 304, and message 3 had UID - 319; therefore, UIDs 305 through 310 do not exist (refer to section - 2.3.1.1 of [IMAP] for further explanation). A006 is an example of a - message being copied that did not return a COPYUID; and, as expected, - A007 shows that the mail store containing that mailbox does not - support persistent UIDs. - -4. Formal Syntax - - Formal syntax is defined using ABNF [ABNF], which extends the ABNF - rules defined in [IMAP]. The IMAP4 ABNF should be imported before - attempting to validate these rules. - - append-uid = uniqueid - - capability =/ "UIDPLUS" - - - -Crispin Standards Track [Page 5] - -RFC 4315 IMAP - UIDPLUS Extension December 2005 - - - command-select =/ uid-expunge - - resp-code-apnd = "APPENDUID" SP nz-number SP append-uid - - resp-code-copy = "COPYUID" SP nz-number SP uid-set SP uid-set - - resp-text-code =/ resp-code-apnd / resp-code-copy / "UIDNOTSTICKY" - ; incorporated before the expansion rule of - ; atom [SP 1*<any TEXT-CHAR except "]">] - ; that appears in [IMAP] - - uid-expunge = "UID" SP "EXPUNGE" SP sequence-set - - uid-set = (uniqueid / uid-range) *("," uid-set) - - uid-range = (uniqueid ":" uniqueid) - ; two uniqueid values and all values - ; between these two regards of order. - ; Example: 2:4 and 4:2 are equivalent. - - Servers that support [MULTIAPPEND] will have the following extension - to the above rules: - - append-uid =/ uid-set - ; only permitted if client uses [MULTIAPPEND] - ; to append multiple messages. - -5. Security Considerations - - The COPYUID and APPENDUID response codes return information about the - mailbox, which may be considered sensitive if the mailbox has - permissions set that permit the client to COPY or APPEND to the - mailbox, but not SELECT or EXAMINE it. - - Consequently, these response codes SHOULD NOT be issued if the client - does not have access to SELECT or EXAMINE the mailbox. - -6. IANA Considerations - - This document constitutes registration of the UIDPLUS capability in - the imap4-capabilities registry, replacing [RFC2359]. - -7. Normative References - - [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", RFC 4234, October 2005. - - - - - -Crispin Standards Track [Page 6] - -RFC 4315 IMAP - UIDPLUS Extension December 2005 - - - [IMAP] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - - VERSION 4rev1", RFC 3501, March 2003. - - [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [MULTIAPPEND] Crispin, M., "Internet Message Access Protocol (IMAP) - - MULTIAPPEND Extension", RFC 3502, March 2003. - -8. Informative References - - [RFC2359] Myers, J., "IMAP4 UIDPLUS extension", RFC 2359, June - 1998. - -9. Changes from RFC 2359 - - This document obsoletes [RFC2359]. However, it is based upon that - document, and takes substantial text from it (albeit with numerous - clarifications in wording). - - [RFC2359] implied that a server must always return COPYUID/APPENDUID - data; thus suggesting that in such cases the server should return - arbitrary data if the destination mailbox did not support persistent - UIDs. This document adds the UIDNOTSTICKY response code to indicate - that a mailbox does not support persistent UIDs, and stipulates that - a UIDPLUS server does not return COPYUID/APPENDUID data when the COPY - (or APPEND) destination mailbox has UIDNOTSTICKY status. - -Author's Address - - Mark R. Crispin - Networks and Distributed Computing - University of Washington - 4545 15th Avenue NE - Seattle, WA 98105-4527 - - Phone: (206) 543-5762 - EMail: MRC@CAC.Washington.EDU - - - - - - - - - - - - - -Crispin Standards Track [Page 7] - -RFC 4315 IMAP - UIDPLUS Extension December 2005 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2005). - - 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 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. - - - - - - - -Crispin Standards Track [Page 8] - diff --git a/imap/docs/rfc/rfc4422.txt b/imap/docs/rfc/rfc4422.txt deleted file mode 100644 index 049fa8c5..00000000 --- a/imap/docs/rfc/rfc4422.txt +++ /dev/null @@ -1,1851 +0,0 @@ - - - - - - -Network Working Group A. Melnikov, Ed. -Request for Comments: 4422 Isode Limited -Obsoletes: 2222 K. Zeilenga, Ed. -Category: Standards Track OpenLDAP Foundation - June 2006 - - - Simple Authentication and Security Layer (SASL) - -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 (2006). - -Abstract - - The Simple Authentication and Security Layer (SASL) is a framework - for providing authentication and data security services in - connection-oriented protocols via replaceable mechanisms. It - provides a structured interface between protocols and mechanisms. - The resulting framework allows new protocols to reuse existing - mechanisms and allows old protocols to make use of new mechanisms. - The framework also provides a protocol for securing subsequent - protocol exchanges within a data security layer. - - This document describes how a SASL mechanism is structured, describes - how protocols include support for SASL, and defines the protocol for - carrying a data security layer over a connection. In addition, this - document defines one SASL mechanism, the EXTERNAL mechanism. - - This document obsoletes RFC 2222. - - - - - - - - - - - - - -Melnikov & Zeilenga Standards Track [Page 1] - -RFC 4422 SASL June 2006 - - -Table of Contents - - 1. Introduction ....................................................3 - 1.1. Document Audiences .........................................4 - 1.2. Relationship to Other Documents ............................4 - 1.3. Conventions ................................................5 - 2. Identity Concepts ...............................................5 - 3. The Authentication Exchange .....................................6 - 3.1. Mechanism Naming ...........................................8 - 3.2. Mechanism Negotiation ......................................9 - 3.3. Request Authentication Exchange ............................9 - 3.4. Challenges and Responses ...................................9 - 3.4.1. Authorization Identity String ......................10 - 3.5. Aborting Authentication Exchanges .........................10 - 3.6. Authentication Outcome ....................................11 - 3.7. Security Layers ...........................................12 - 3.8. Multiple Authentications ..................................12 - 4. Protocol Requirements ..........................................13 - 5. Mechanism Requirements .........................................16 - 6. Security Considerations ........................................18 - 6.1. Active Attacks ............................................19 - 6.1.1. Hijack Attacks .....................................19 - 6.1.2. Downgrade Attacks ..................................19 - 6.1.3. Replay Attacks .....................................20 - 6.1.4. Truncation Attacks .................................20 - 6.1.5. Other Active Attacks ...............................20 - 6.2. Passive Attacks ...........................................20 - 6.3. Re-keying .................................................21 - 6.4. Other Considerations ......................................21 - 7. IANA Considerations ............................................22 - 7.1. SASL Mechanism Registry ...................................22 - 7.2. Registration Changes ......................................26 - 8. References .....................................................26 - 8.1. Normative References ......................................26 - 8.2. Informative References ....................................27 - 9. Acknowledgements ...............................................28 - Appendix A. The SASL EXTERNAL Mechanism ..........................29 - A.1. EXTERNAL Technical Specification ..........................29 - A.2. SASL EXTERNAL Examples ....................................30 - A.3. Security Considerations ...................................31 - Appendix B. Changes since RFC 2222 ...............................31 - - - - - - - - - - -Melnikov & Zeilenga Standards Track [Page 2] - -RFC 4422 SASL June 2006 - - -1. Introduction - - The Simple Authentication and Security Layer (SASL) is a framework - for providing authentication and data security services in - connection-oriented protocols via replaceable mechanisms. SASL - provides a structured interface between protocols and mechanisms. - SASL also provides a protocol for securing subsequent protocol - exchanges within a data security layer. The data security layer can - provide data integrity, data confidentiality, and other services. - - SASL's design is intended to allow new protocols to reuse existing - mechanisms without requiring redesign of the mechanisms and allows - existing protocols to make use of new mechanisms without redesign of - protocols. - - SASL is conceptually a framework that provides an abstraction layer - between protocols and mechanisms as illustrated in the following - diagram. - - SMTP LDAP XMPP Other protocols ... - \ | | / - \ | | / - SASL abstraction layer - / | | \ - / | | \ - EXTERNAL GSSAPI PLAIN Other mechanisms ... - - It is through the interfaces of this abstraction layer that the - framework allows any protocol to utilize any mechanism. While this - layer does generally hide the particulars of protocols from - mechanisms and the particulars of mechanisms from protocols, this - layer does not generally hide the particulars of mechanisms from - protocol implementations. For example, different mechanisms require - different information to operate, some of them use password-based - authentication, some of then require realm information, others make - use of Kerberos tickets, certificates, etc. Also, in order to - perform authorization, server implementations generally have to - implement identity mapping between authentication identities, whose - form is mechanism specific, and authorization identities, whose form - is application protocol specific. Section 2 discusses identity - concepts. - - It is possible to design and implement this framework in ways that do - abstract away particulars of similar mechanisms. Such a framework - implementation, as well as mechanisms implementations, could be - designed not only to be shared by multiple implementations of a - particular protocol but to be shared by implementations of multiple - protocols. - - - -Melnikov & Zeilenga Standards Track [Page 3] - -RFC 4422 SASL June 2006 - - - The framework incorporates interfaces with both protocols and - mechanisms in which authentication exchanges are carried out. - Section 3 discusses SASL authentication exchanges. - - To use SASL, each protocol (amongst other items) provides a method - for identifying which mechanism is to be used, a method for exchange - of mechanism-specific server-challenges and client-responses, and a - method for communicating the outcome of the authentication exchange. - Section 4 discusses SASL protocol requirements. - - Each SASL mechanism defines (amongst other items) a series of - server-challenges and client-responses that provide authentication - services and negotiate data security services. Section 5 discusses - SASL mechanism requirements. - - Section 6 discusses security considerations. Section 7 discusses - IANA considerations. Appendix A defines the SASL EXTERNAL mechanism. - -1.1. Document Audiences - - This document is written to serve several different audiences: - - - protocol designers using this specification to support - authentication in their protocol, - - - mechanism designers that define new SASL mechanisms, and - - - implementors of clients or servers for those protocols that - support SASL. - - While the document organization is intended to allow readers to focus - on details relevant to their engineering, readers are encouraged to - read and understand all aspects of this document. - -1.2. Relationship to Other Documents - - This document obsoletes RFC 2222. It replaces all portions of RFC - 2222 excepting sections 7.1 (the KERBEROS_IV mechanism), 7.2 (the - GSSAPI mechanism), 7.3 (the SKEY mechanism). The KERBEROS_IV and - SKEY mechanisms are now viewed as obsolete and their specifications - provided in RFC 2222 are Historic. The GSSAPI mechanism is now - separately specified [SASL-GSSAPI]. - - Appendix B provides a summary of changes since RFC 2222. - - - - - - - -Melnikov & Zeilenga Standards Track [Page 4] - -RFC 4422 SASL June 2006 - - -1.3. Conventions - - 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 BCP 14 [RFC2119]. - - Character names in this document use the notation for code points and - names from the Unicode Standard [Unicode]. For example, the letter - "a" may be represented as either <U+0061> or <LATIN SMALL LETTER A>. - - Note: a glossary of terms used in Unicode can be found in [Glossary]. - Information on the Unicode character encoding model can be found in - [CharModel]. - - In examples, "C:" and "S:" indicate lines of data to be sent by the - client and server, respectively. Lines have been wrapped for - improved readability. - -2. Identity Concepts - - In practice, authentication and authorization may involve multiple - identities, possibly in different forms (simple username, Kerberos - principal, X.500 Distinguished Name, etc.), possibly with different - representations (e.g., ABNF-described UTF-8 encoded Unicode character - string, BER-encoded Distinguished Name). While technical - specifications often prescribe both the identity form and - representation used on the network, different identity forms and/or - representations may be (and often are) used within implementations. - How identities of different forms relate to each other is, generally, - a local matter. In addition, the forms and representations used - within an implementation are a local matter. - - However, conceptually, the SASL framework involves two identities: - - 1) an identity associated with the authentication credentials - (termed the authentication identity), and - - 2) an identity to act as (termed the authorization identity). - - SASL mechanism specifications describe the credential form(s) (e.g., - X.509 certificates, Kerberos tickets, simple username/password) used - to authenticate the client, including (where appropriate) the syntax - and semantics of authentication identities carried in the - credentials. SASL protocol specifications describe the identity - form(s) used in authorization and, in particular, prescribe the - syntax and semantics of the authorization identity character string - to be transferred by mechanisms. - - - - -Melnikov & Zeilenga Standards Track [Page 5] - -RFC 4422 SASL June 2006 - - - The client provides its credentials (which include or imply an - authentication identity) and, optionally, a character string - representing the requested authorization identity as part of the SASL - exchange. When this character string is omitted or empty, the client - is requesting to act as the identity associated with the credentials - (e.g., the user is requesting to act as the authentication identity). - - The server is responsible for verifying the client's credentials and - verifying that the identity it associates with the client's - credentials (e.g., the authentication identity) is allowed to act as - the authorization identity. A SASL exchange fails if either (or - both) of these verifications fails. (The SASL exchange may fail for - other reasons, such as service authorization failure.) - - However, the precise form(s) of the authentication identities (used - within the server in its verifications, or otherwise) and the precise - form(s) of the authorization identities (used in making authorization - decisions, or otherwise) are beyond the scope of SASL and this - specification. In some circumstances, the precise identity forms - used in some context outside of the SASL exchange may be dictated by - other specifications. For instance, an identity assumption - authorization (proxy authorization) policy specification may dictate - how authentication and authorization identities are represented in - policy statements. - -3. The Authentication Exchange - - Each authentication exchange consists of a message from the client to - the server requesting authentication via a particular mechanism, - followed by one or more pairs of challenges from the server and - responses from the client, followed by a message from the server - indicating the outcome of the authentication exchange. (Note: - exchanges may also be aborted as discussed in Section 3.5.) - - The following illustration provides a high-level overview of an - authentication exchange. - - C: Request authentication exchange - S: Initial challenge - C: Initial response - <additional challenge/response messages> - S: Outcome of authentication exchange - - If the outcome is successful and a security layer was negotiated, - this layer is then installed (see Section 3.7). This also applies to - the following illustrations. - - - - - -Melnikov & Zeilenga Standards Track [Page 6] - -RFC 4422 SASL June 2006 - - - Some mechanisms specify that the first data sent in the - authentication exchange is from the client to the server. Protocols - may provide an optional initial response field in the request message - to carry this data. Where the mechanism specifies that the first - data sent in the exchange is from the client to the server, the - protocol provides an optional initial response field, and the client - uses this field, the exchange is shortened by one round-trip: - - C: Request authentication exchange + Initial response - <additional challenge/response messages> - S: Outcome of authentication exchange - - Where the mechanism specifies that the first data sent in the - exchange is from the client to the server and this field is - unavailable or unused, the client request is followed by an empty - challenge. - - C: Request authentication exchange - S: Empty Challenge - C: Initial Response - <additional challenge/response messages> - S: Outcome of authentication exchange - - Should a client include an initial response in its request where the - mechanism does not allow the client to send data first, the - authentication exchange fails. - - Some mechanisms specify that the server is to send additional data to - the client when indicating a successful outcome. Protocols may - provide an optional additional data field in the outcome message to - carry this data. Where the mechanism specifies that the server is to - return additional data with the successful outcome, the protocol - provides an optional additional data field in the outcome message, - and the server uses this field, the exchange is shortened by one - round-trip: - - C: Request authentication exchange - S: Initial challenge - C: Initial response - <additional challenge/response messages> - S: Outcome of authentication exchange with - additional data with success - - Where the mechanism specifies that the server is to return additional - data to the client with a successful outcome and this field is - unavailable or unused, the additional data is sent as a challenge - whose response is empty. After receiving this response, the server - then indicates the successful outcome. - - - -Melnikov & Zeilenga Standards Track [Page 7] - -RFC 4422 SASL June 2006 - - - C: Request authentication exchange - S: Initial challenge - C: Initial response - <additional challenge/response messages> - S: Additional data challenge - C: Empty Response - S: Outcome of authentication exchange - - Where mechanisms specify that the first data sent in the exchange is - from the client to the server and additional data is sent to the - client along with indicating a successful outcome, and the protocol - provides fields supporting both, then the exchange takes two fewer - round-trips: - - C: Request authentication exchange + Initial response - <additional challenge/response messages> - S: Outcome of authentication exchange - with additional data with success - - instead of: - - C: Request authentication exchange - S: Empty Challenge - C: Initial Response - <additional challenge/response messages> - S: Additional data challenge - C: Empty Response - S: Outcome of authentication exchange - -3.1. Mechanism Naming - - SASL mechanisms are named by character strings, from 1 to 20 - characters in length, consisting of ASCII [ASCII] uppercase letters, - digits, hyphens, and/or underscores. In the following Augmented - Backus-Naur Form (ABNF) [RFC4234] grammar, the <sasl-mech> production - defines the syntax of a SASL mechanism name. - - sasl-mech = 1*20mech-char - mech-char = UPPER-ALPHA / DIGIT / HYPHEN / UNDERSCORE - ; mech-char is restricted to A-Z (uppercase only), 0-9, -, and _ - ; from ASCII character set. - - UPPER-ALPHA = %x41-5A ; A-Z (uppercase only) - DIGIT = %x30-39 ; 0-9 - HYPHEN = %x2D ; hyphen (-) - UNDERSCORE = %x5F ; underscore (_) - - SASL mechanism names are registered as discussed in Section 7.1. - - - -Melnikov & Zeilenga Standards Track [Page 8] - -RFC 4422 SASL June 2006 - - -3.2. Mechanism Negotiation - - Mechanism negotiation is protocol specific. - - Commonly, a protocol will specify that the server advertises - supported and available mechanisms to the client via some facility - provided by the protocol, and the client will then select the "best" - mechanism from this list that it supports and finds suitable. - - Note that the mechanism negotiation is not protected by the - subsequent authentication exchange and hence is subject to downgrade - attacks if not protected by other means. - - To detect downgrade attacks, a protocol can allow the client to - discover available mechanisms subsequent to the authentication - exchange and installation of data security layers with at least data - integrity protection. This allows the client to detect changes to - the list of mechanisms supported by the server. - -3.3. Request Authentication Exchange - - The authentication exchange is initiated by the client by requesting - authentication via a mechanism it specifies. The client sends a - message that contains the name of the mechanism to the server. The - particulars of the message are protocol specific. - - Note that the name of the mechanism is not protected by the - mechanism, and hence is subject to alteration by an attacker if not - integrity protected by other means. - - Where the mechanism is defined to allow the client to send data - first, and the protocol's request message includes an optional - initial response field, the client may include the response to the - initial challenge in the authentication request message. - -3.4. Challenges and Responses - - The authentication exchange involves one or more pairs of server- - challenges and client-responses, the particulars of which are - mechanism specific. These challenges and responses are enclosed in - protocol messages, the particulars of which are protocol specific. - - Through these challenges and responses, the mechanism may: - - - authenticate the client to the server, - - - authenticate the server to the client, - - - - -Melnikov & Zeilenga Standards Track [Page 9] - -RFC 4422 SASL June 2006 - - - - transfer an authorization identity string, - - - negotiate a security layer, and - - - provide other services. - - The negotiation of the security layer may involve negotiation of the - security services to be provided in the layer, how these services - will be provided, and negotiation of a maximum cipher-text buffer - size each side is able to receive in the layer (see Section 3.6). - - After receiving an authentication request or any client response, the - server may issue a challenge, abort the exchange, or indicate the - outcome of an exchange. After receiving a challenge, a client - mechanism may issue a response or abort the exchange. - -3.4.1. Authorization Identity String - - The authorization identity string is a sequence of zero or more - Unicode [Unicode] characters, excluding the NUL (U+0000) character, - representing the identity to act as. - - If the authorization identity string is absent, the client is - requesting to act as the identity the server associates with the - client's credentials. An empty string is equivalent to an absent - authorization identity. - - A non-empty authorization identity string indicates that the client - wishes to act as the identity represented by the string. In this - case, the form of identity represented by the string, as well as the - precise syntax and semantics of the string, is protocol specific. - - While the character encoding schema used to transfer the - authorization identity string in the authentication exchange is - mechanism specific, mechanisms are expected to be capable of carrying - the entire Unicode repertoire (with the exception of the NUL - character). - -3.5. Aborting Authentication Exchanges - - A client or server may desire to abort an authentication exchange if - it is unwilling or unable to continue (or enter into). - - A client may abort the authentication exchange by sending a message, - the particulars of which are protocol specific, to the server, - indicating that the exchange is aborted. The server may be required - by the protocol to return a message in response to the client's abort - message. - - - -Melnikov & Zeilenga Standards Track [Page 10] - -RFC 4422 SASL June 2006 - - - Likewise, a server may abort the authentication exchange by sending a - message, the particulars of which are protocol specific, to the - client, indicating that the exchange is aborted. - -3.6. Authentication Outcome - - At the conclusion of the authentication exchange, the server sends a - message, the particulars of which are protocol specific, to the - client indicating the outcome of the exchange. - - The outcome is not successful if - - - the authentication exchange failed for any reason, - - - the client's credentials could not be verified, - - - the server cannot associate an identity with the client's - credentials, - - - the client-provided authorization identity string is malformed, - - - the identity associated with the client's credentials is not - authorized to act as the requested authorization identity, - - - the negotiated security layer (or lack thereof) is not - suitable, or - - - the server is not willing to provide service to the client for - any reason. - - The protocol may include an optional additional data field in this - outcome message. This field can only include additional data when - the outcome is successful. - - If the outcome is successful and a security layer was negotiated, - this layer is then installed. If the outcome is unsuccessful, or a - security layer was not negotiated, any existing security is left in - place. - - The outcome message provided by the server can provide a way for the - client to distinguish between errors that are best dealt with by re- - prompting the user for her credentials, errors that are best dealt - with by telling the user to try again later, and errors where the - user must contact a system administrator for resolution (see the SYS - and AUTH POP Response Codes [RFC3206] specification for an example). - This distinction is particularly useful during scheduled server - maintenance periods as it reduces support costs. It is also - important that the server can be configured such that the outcome - - - -Melnikov & Zeilenga Standards Track [Page 11] - -RFC 4422 SASL June 2006 - - - message will not distinguish between a valid user with invalid - credentials and an invalid user. - -3.7. Security Layers - - SASL mechanisms may offer a wide range of services in security - layers. Typical services include data integrity and data - confidentiality. SASL mechanisms that do not provide a security - layer are treated as negotiating no security layer. - - If use of a security layer is negotiated in the authentication - protocol exchange, the layer is installed by the server after - indicating the outcome of the authentication exchange and installed - by the client upon receipt of the outcome indication. In both cases, - the layer is installed before transfer of further protocol data. The - precise position upon which the layer takes effect in the protocol - data stream is protocol specific. - - Once the security layer is in effect in the protocol data stream, it - remains in effect until either a subsequently negotiated security - layer is installed or the underlying transport connection is closed. - - When in effect, the security layer processes protocol data into - buffers of protected data. If at any time the security layer is - unable or unwilling to continue producing buffers protecting protocol - data, the underlying transport connection MUST be closed. If the - security layer is not able to decode a received buffer, the - underlying connection MUST be closed. In both cases, the underlying - transport connection SHOULD be closed gracefully. - - Each buffer of protected data is transferred over the underlying - transport connection as a sequence of octets prepended with a four- - octet field in network byte order that represents the length of the - buffer. The length of the protected data buffer MUST be no larger - than the maximum size that the other side expects. Upon the receipt - of a length field whose value is greater than the maximum size, the - receiver SHOULD close the connection, as this might be a sign of an - attack. - - The maximum size that each side expects is fixed by the mechanism, - either through negotiation or by its specification. - -3.8. Multiple Authentications - - Unless explicitly permitted in the protocol (as stated in the - protocol's technical specification), only one successful SASL - authentication exchange may occur in a protocol session. In this - - - - -Melnikov & Zeilenga Standards Track [Page 12] - -RFC 4422 SASL June 2006 - - - case, once an authentication exchange has successfully completed, - further attempts to initiate an authentication exchange fail. - - Where multiple successful SASL authentication exchanges are permitted - in the protocol, then in no case may multiple SASL security layers be - simultaneously in effect. If a security layer is in effect and a - subsequent SASL negotiation selects a second security layer, then the - second security layer replaces the first. If a security layer is in - effect and a subsequent SASL negotiation selects no security layer, - the original security layer remains in effect. - - Where multiple successful SASL negotiations are permitted in the - protocol, the effect of a failed SASL authentication exchange upon - the previously established authentication and authorization state is - protocol specific. The protocol's technical specification should be - consulted to determine whether the previous authentication and - authorization state remains in force, or changed to an anonymous - state, or otherwise was affected. Regardless of the protocol- - specific effect upon previously established authentication and - authorization state, the previously negotiated security layer remains - in effect. - -4. Protocol Requirements - - In order for a protocol to offer SASL services, its specification - MUST supply the following information: - - 1) A service name, to be selected from registry of "service" elements - for the Generic Security Service Application Program Interface - (GSSAPI) host-based service name form, as described in Section 4.1 - of [RFC2743]. Note that this registry is shared by all GSSAPI and - SASL mechanisms. - - 2) Detail any mechanism negotiation facility that the protocol - provides (see Section 3.2). - - A protocol SHOULD specify a facility through which the client may - discover, both before initiation of the SASL exchange and after - installing security layers negotiated by the exchange, the names - of the SASL mechanisms that the server makes available to the - client. The latter is important to allow the client to detect - downgrade attacks. This facility is typically provided through - the protocol's extensions or capabilities discovery facility. - - 3) Definition of the messages necessary for authentication exchange, - including the following: - - - - - -Melnikov & Zeilenga Standards Track [Page 13] - -RFC 4422 SASL June 2006 - - - a) A message to initiate the authentication exchange (see Section - 3.3). - - This message MUST contain a field for carrying the name of the - mechanism selected by the client. - - This message SHOULD contain an optional field for carrying an - initial response. If the message is defined with this field, - the specification MUST describe how messages with an empty - initial response are distinguished from messages with no - initial response. This field MUST be capable of carrying - arbitrary sequences of octets (including zero-length sequences - and sequences containing zero-valued octets). - - b) Messages to transfer server challenges and client responses - (see Section 3.4). - - Each of these messages MUST be capable of carrying arbitrary - sequences of octets (including zero-length sequences and - sequences containing zero-valued octets). - - c) A message to indicate the outcome of the authentication - exchange (see Section 3.6). - - This message SHOULD contain an optional field for carrying - additional data with a successful outcome. If the message is - defined with this field, the specification MUST describe how - messages with an empty additional data are distinguished from - messages with no additional data. This field MUST be capable - of carrying arbitrary sequences of octets (including zero- - length sequences and sequences containing zero-valued octets). - - 4) Prescribe the syntax and semantics of non-empty authorization - identity strings (see Section 3.4.1). - - In order to avoid interoperability problems due to differing - normalizations, the protocol specification MUST detail precisely - how and where (client or server) non-empty authorization identity - strings are prepared, including all normalizations, for comparison - and other applicable functions to ensure proper function. - - Specifications are encouraged to prescribe use of existing - authorization identity forms as well as existing string - representations, such as simple user names [RFC4013]. - - Where the specification does not precisely prescribe how - identities in SASL relate to identities used elsewhere in the - protocol, for instance, in access control policy statements, it - - - -Melnikov & Zeilenga Standards Track [Page 14] - -RFC 4422 SASL June 2006 - - - may be appropriate for the protocol to provide a facility by which - the client can discover information (such as the representation of - the identity used in making access control decisions) about - established identities for these uses. - - 5) Detail any facility the protocol provides that allows the client - and/or server to abort authentication exchange (see Section 3.5). - - Protocols that support multiple authentications typically allow a - client to abort an ongoing authentication exchange by initiating a - new authentication exchange. Protocols that do not support - multiple authentications may require the client to close the - connection and start over to abort an ongoing authentication - exchange. - - Protocols typically allow the server to abort ongoing - authentication exchanges by returning a non-successful outcome - message. - - 6) Identify precisely where newly negotiated security layers start to - take effect, in both directions (see Section 3.7). - - Typically, specifications require security layers to start taking - effect on the first octet following the outcome message in data - being sent by the server and on the first octet sent after receipt - of the outcome message in data being sent by the client. - - 7) If the protocol supports other layered security services, such as - Transport Layer Security (TLS) [RFC4346], the specification MUST - prescribe the order in which security layers are applied to - protocol data. - - For instance, where a protocol supports both TLS and SASL security - layers, the specification could prescribe any of the following: - - a) SASL security layer is always applied first to data being sent - and, hence, applied last to received data, - - b) SASL security layer is always applied last to data being sent - and, hence, applied first to received data, - - c) Layers are applied in the order in which they were installed, - - d) Layers are applied in the reverse order in which they were - installed, or - - e) Both TLS and SASL security layers cannot be installed. - - - - -Melnikov & Zeilenga Standards Track [Page 15] - -RFC 4422 SASL June 2006 - - - 8) Indicate whether the protocol supports multiple authentications - (see Section 3.8). If so, the protocol MUST detail the effect a - failed SASL authentication exchange will have upon a previously - established authentication and authorization state. - - Protocol specifications SHOULD avoid stating implementation - requirements that would hinder replacement of applicable mechanisms. - In general, protocol specifications SHOULD be mechanism neutral. - There are a number of reasonable exceptions to this recommendation, - including - - - detailing how credentials (which are mechanism specific) are - managed in the protocol, - - - detailing how authentication identities (which are mechanism - specific) and authorization identities (which are protocol - specific) relate to each other, and - - - detailing which mechanisms are applicable to the protocol. - -5. Mechanism Requirements - - SASL mechanism specifications MUST supply the following information: - - 1) The name of the mechanism (see Section 3.1). This name MUST be - registered as discussed in Section 7.1. - - 2) A definition of the server-challenges and client-responses of the - authentication exchange, as well as the following: - - a) An indication of whether the mechanism is client-first, - variable, or server-first. If a SASL mechanism is defined as - client-first and the client does not send an initial response - in the authentication request, then the first server challenge - MUST be empty (the EXTERNAL mechanism is an example of this - case). If a SASL mechanism is defined as variable, then the - specification needs to state how the server behaves when the - initial client response in the authentication request is - omitted (the DIGEST-MD5 mechanism [DIGEST-MD5] is an example of - this case). If a SASL mechanism is defined as server-first, - then the client MUST NOT send an initial client response in the - authentication request (the CRAM-MD5 mechanism [CRAM-MD5] is an - example of this case). - - b) An indication of whether the server is expected to provide - additional data when indicating a successful outcome. If so, - if the server sends the additional data as a challenge, the - - - - -Melnikov & Zeilenga Standards Track [Page 16] - -RFC 4422 SASL June 2006 - - - specification MUST indicate that the response to this challenge - is an empty response. - - SASL mechanisms SHOULD be designed to minimize the number of - challenges and responses necessary to complete the exchange. - - 3) An indication of whether the mechanism is capable of transferring - authorization identity strings (see Section 3.4.1). While some - legacy mechanisms are incapable of transmitting an authorization - identity (which means that for these mechanisms, the authorization - identity is always the empty string), newly defined mechanisms - SHOULD be capable of transferring authorization identity strings. - The mechanism SHOULD NOT be capable of transferring both no - authorization identity string and an empty authorization identity. - - Mechanisms that are capable of transferring an authorization - identity string MUST be capable of transferring arbitrary non- - empty sequences of Unicode characters, excluding those that - contain the NUL (U+0000) character. Mechanisms SHOULD use the - UTF-8 [RFC3629] transformation format. The specification MUST - detail how any Unicode code points special to the mechanism that - might appear in the authorization identity string are escaped to - avoid ambiguity during decoding of the authorization identity - string. Typically, mechanisms that have special characters - require these special characters to be escaped or encoded in the - character string (after encoding it in a particular Unicode - transformation format) using a data encoding scheme such as Base64 - [RFC3548]. - - 4) The specification MUST detail whether the mechanism offers a - security layer. If the mechanism does, the specification MUST - detail the security and other services offered in the layer as - well as how these services are to be implemented. - - 5) If the underlying cryptographic technology used by a mechanism - supports data integrity, then the mechanism specification MUST - integrity protect the transmission of an authorization identity - and the negotiation of the security layer. - - SASL mechanisms SHOULD be protocol neutral. - - SASL mechanisms SHOULD reuse existing credential and identity forms, - as well as associated syntaxes and semantics. - - SASL mechanisms SHOULD use the UTF-8 transformation format [RFC3629] - for encoding Unicode [Unicode] code points for transfer. - - - - - -Melnikov & Zeilenga Standards Track [Page 17] - -RFC 4422 SASL June 2006 - - - In order to avoid interoperability problems due to differing - normalizations, when a mechanism calls for character data (other than - the authorization identity string) to be used as input to a - cryptographic and/or comparison function, the specification MUST - detail precisely how and where (client or server) the character data - is to be prepared, including all normalizations, for input into the - function to ensure proper operation. - - For simple user names and/or passwords in authentication credentials, - SASLprep [RFC4013] (a profile of the StringPrep [RFC3454] preparation - algorithm), SHOULD be specified as the preparation algorithm. - - The mechanism SHOULD NOT use the authorization identity string in - generation of any long-term cryptographic keys or hashes as there is - no requirement that the authorization identity string be canonical. - Long-term, here, means a term longer than the duration of the - authentication exchange in which they were generated. That is, as - different clients (of the same or different protocol) may provide - different authorization identity strings that are semantically - equivalent, use of authorization identity strings in generation of - cryptographic keys and hashes will likely lead to interoperability - and other problems. - -6. Security Considerations - - Security issues are discussed throughout this memo. - - Many existing SASL mechanisms do not provide adequate protection - against passive attacks, let alone active attacks, in the - authentication exchange. Many existing SASL mechanisms do not offer - security layers. It is hoped that future SASL mechanisms will - provide strong protection against passive and active attacks in the - authentication exchange, as well as security layers with strong basic - data security features (e.g., data integrity and data - confidentiality) services. It is also hoped that future mechanisms - will provide more advanced data security services like re-keying (see - Section 6.3). - - Regardless, the SASL framework is susceptible to downgrade attacks. - Section 6.1.2 offers a variety of approaches for preventing or - detecting these attacks. In some cases, it is appropriate to use - data integrity protective services external to SASL (e.g., TLS) to - protect against downgrade attacks in SASL. Use of external - protective security services is also important when the mechanisms - available do not themselves offer adequate integrity and/or - confidentiality protection of the authentication exchange and/or - protocol data. - - - - -Melnikov & Zeilenga Standards Track [Page 18] - -RFC 4422 SASL June 2006 - - -6.1. Active Attacks - -6.1.1. Hijack Attacks - - When the client selects a SASL security layer with at least integrity - protection, this protection serves as a counter-measure against an - active attacker hijacking the connection and modifying protocol data - sent after establishment of the security layer. Implementations - SHOULD close the connection when the security services in a SASL - security layer report protocol data report lack of data integrity. - -6.1.2. Downgrade Attacks - - It is important that any security-sensitive protocol negotiations be - performed after installation of a security layer with data integrity - protection. Protocols should be designed such that negotiations - performed prior to this installation should be revalidated after - installation is complete. Negotiation of the SASL mechanism is - security sensitive. - - When a client negotiates the authentication mechanism with the server - and/or other security features, it is possible for an active attacker - to cause a party to use the least secure security services available. - For instance, an attacker can modify the server-advertised mechanism - list or can modify the client-advertised security feature list within - a mechanism response. To protect against this sort of attack, - implementations SHOULD NOT advertise mechanisms and/or features that - cannot meet their minimum security requirements, SHOULD NOT enter - into or continue authentication exchanges that cannot meet their - minimum security requirements, and SHOULD verify that completed - authentication exchanges result in security services that meet their - minimum security requirements. Note that each endpoint needs to - independently verify that its security requirements are met. - - In order to detect downgrade attacks to the least (or less) secure - mechanism supported, the client can discover the SASL mechanisms that - the server makes available both before the SASL authentication - exchange and after the negotiated SASL security layer (with at least - data integrity protection) has been installed through the protocol's - mechanism discovery facility. If the client finds that the - integrity-protected list (the list obtained after the security layer - was installed) contains a stronger mechanism than those in the - previously obtained list, the client should assume that the - previously obtained list was modified by an attacker and SHOULD close - the underlying transport connection. - - The client's initiation of the SASL exchange, including the selection - of a SASL mechanism, is done in the clear and may be modified by an - - - -Melnikov & Zeilenga Standards Track [Page 19] - -RFC 4422 SASL June 2006 - - - active attacker. It is important for any new SASL mechanisms to be - designed such that an active attacker cannot obtain an authentication - with weaker security properties by modifying the SASL mechanism name - and/or the challenges and responses. - - Multi-level negotiation of security features is prone to downgrade - attack. Protocol designers should avoid offering higher-level - negotiation of security features in protocols (e.g., above SASL - mechanism negotiation) and mechanism designers should avoid lower- - level negotiation of security features in mechanisms (e.g., below - SASL mechanism negotiation). - -6.1.3. Replay Attacks - - Some mechanisms may be subject to replay attacks unless protected by - external data security services (e.g., TLS). - -6.1.4. Truncation Attacks - - Most existing SASL security layers do not themselves offer protection - against truncation attack. In a truncation attack, the active - attacker causes the protocol session to be closed, causing a - truncation of the possibly integrity-protected data stream that leads - to behavior of one or both the protocol peers that inappropriately - benefits the attacker. Truncation attacks are fairly easy to defend - against in connection-oriented application-level protocols. A - protocol can defend against these attacks by ensuring that each - information exchange has a clear final result and that each protocol - session has a graceful closure mechanism, and that these are - integrity protected. - -6.1.5. Other Active Attacks - - When use of a security layer is negotiated by the authentication - protocol exchange, the receiver SHOULD handle gracefully any - protected data buffer larger than the defined/negotiated maximal - size. In particular, it MUST NOT blindly allocate the amount of - memory specified in the buffer size field, as this might cause the - "out of memory" condition. If the receiver detects a large block, it - SHOULD close the connection. - -6.2. Passive Attacks - - Many mechanisms are subject to various passive attacks, including - simple eavesdropping of unprotected credential information as well as - online and offline dictionary attacks of protected credential - information. - - - - -Melnikov & Zeilenga Standards Track [Page 20] - -RFC 4422 SASL June 2006 - - -6.3. Re-keying - - The secure or administratively permitted lifetimes of SASL - mechanisms' security layers are finite. Cryptographic keys weaken as - they are used and as time passes; the more time and/or cipher-text - that a cryptanalyst has after the first use of the a key, the easier - it is for the cryptanalyst to mount attacks on the key. - - Administrative limits on a security layer's lifetime may take the - form of time limits expressed in X.509 certificates, in Kerberos V - tickets, or in directories, and are often desired. In practice, one - likely effect of administrative lifetime limits is that applications - may find that security layers stop working in the middle of - application protocol operation, such as, perhaps, during large data - transfers. As the result of this, the connection will be closed (see - Section 3.7), which will result in an unpleasant user experience. - - Re-keying (key renegotiation process) is a way of addressing the - weakening of cryptographic keys. The SASL framework does not itself - provide for re-keying; SASL mechanisms may. Designers of future SASL - mechanisms should consider providing re-keying services. - - Implementations that wish to re-key SASL security layers where the - mechanism does not provide for re-keying SHOULD reauthenticate the - same IDs and replace the expired or soon-to-expire security layers. - This approach requires support for reauthentication in the - application protocols (see Section 3.8). - -6.4. Other Considerations - - Protocol designers and implementors should understand the security - considerations of mechanisms so they may select mechanisms that are - applicable to their needs. - - Distributed server implementations need to be careful in how they - trust other parties. In particular, authentication secrets should - only be disclosed to other parties that are trusted to manage and use - those secrets in a manner acceptable to the disclosing party. - Applications using SASL assume that SASL security layers providing - data confidentiality are secure even when an attacker chooses the - text to be protected by the security layer. Similarly, applications - assume that the SASL security layer is secure even if the attacker - can manipulate the cipher-text output of the security layer. New - SASL mechanisms are expected to meet these assumptions. - - - - - - - -Melnikov & Zeilenga Standards Track [Page 21] - -RFC 4422 SASL June 2006 - - - Unicode security considerations [UTR36] apply to authorization - identity strings, as well as UTF-8 [RFC3629] security considerations - where UTF-8 is used. SASLprep [RFC4013] and StringPrep [RFC3454] - security considerations also apply where used. - -7. IANA Considerations - -7.1. SASL Mechanism Registry - - The SASL mechanism registry is maintained by IANA. The registry is - currently available at <http://www.iana.org/assignments/sasl- - mechanisms>. - - The purpose of this registry is not only to ensure uniqueness of - values used to name SASL mechanisms, but also to provide a definitive - reference to technical specifications detailing each SASL mechanism - available for use on the Internet. - - There is no naming convention for SASL mechanisms; any name that - conforms to the syntax of a SASL mechanism name can be registered. - - The procedure detailed in Section 7.1.1 is to be used for - registration of a value naming a specific individual mechanism. - - The procedure detailed in Section 7.1.2 is to be used for - registration of a value naming a family of related mechanisms. - - Comments may be included in the registry as discussed in Section - 7.1.3 and may be changed as discussed in Section 7.1.4. - - The SASL mechanism registry has been updated to reflect that this - document provides the definitive technical specification for SASL and - that this section provides the registration procedures for this - registry. - - - - - - - - - - - - - - - - - -Melnikov & Zeilenga Standards Track [Page 22] - -RFC 4422 SASL June 2006 - - -7.1.1. Mechanism Name Registration Procedure - - IANA will register new SASL mechanism names on a First Come First - Served basis, as defined in BCP 26 [RFC2434]. IANA has the right to - reject obviously bogus registration requests, but will perform no - review of claims made in the registration form. - - Registration of a SASL mechanism is requested by filling in the - following template: - - Subject: Registration of SASL mechanism X - - SASL mechanism name (or prefix for the family): - - Security considerations: - - Published specification (recommended): - - Person & email address to contact for further information: - - Intended usage: (One of COMMON, LIMITED USE, or OBSOLETE) - - Owner/Change controller: - - Note: (Any other information that the author deems relevant may be - added here.) - - and sending it via electronic mail to IANA at <iana@iana.org>. - - While this registration procedure does not require expert review, - authors of SASL mechanisms are encouraged to seek community review - and comment whenever that is feasible. Authors may seek community - review by posting a specification of their proposed mechanism as an - Internet-Draft. SASL mechanisms intended for widespread use should - be standardized through the normal IETF process, when appropriate. - - - - - - - - - - - - - - - - -Melnikov & Zeilenga Standards Track [Page 23] - -RFC 4422 SASL June 2006 - - -7.1.2. Family Name Registration Procedure - - As noted above, there is no general naming convention for SASL - mechanisms. However, specifications may reserve a portion of the - SASL mechanism namespace for a set of related SASL mechanisms, a - "family" of SASL mechanisms. Each family of SASL mechanisms is - identified by a unique prefix, such as X-. Registration of new SASL - mechanism family names requires expert review as defined in BCP 26 - [RFC2434]. - - Registration of a SASL family name is requested by filling in the - following template: - - Subject: Registration of SASL mechanism family X - - SASL family name (or prefix for the family): - - Security considerations: - - Published specification (recommended): - - Person & email address to contact for further information: - - Intended usage: (One of COMMON, LIMITED USE, or OBSOLETE) - - Owner/Change controller: - - Note: (Any other information that the author deems relevant may be - added here.) - - and sending it via electronic mail to the IETF SASL mailing list at - <ietf-sasl@imc.org> and carbon copying IANA at <iana@iana.org>. - After allowing two weeks for community input on the IETF SASL mailing - list, the expert will determine the appropriateness of the - registration request and either approve or disapprove the request - with notice to the requestor, the mailing list, and IANA. - - The review should focus on the appropriateness of the requested - family name for the proposed use and the appropriateness of the - proposed naming and registration plan for existing and future - mechanism names in the family. The scope of this request review may - entail consideration of relevant aspects of any provided technical - specification, such as their IANA Considerations section. However, - this review is narrowly focused on the appropriateness of the - requested registration and not on the overall soundness of any - provided technical specification. - - - - - -Melnikov & Zeilenga Standards Track [Page 24] - -RFC 4422 SASL June 2006 - - - Authors are encouraged to pursue community review by posting the - technical specification as an Internet-Draft and soliciting comment - by posting to appropriate IETF mailing lists. - -7.1.3. Comments on SASL Mechanism Registrations - - Comments on a registered SASL mechanism/family should first be sent - to the "owner" of the mechanism/family and/or to the <ietf- - sasl@imc.org> mailing list. - - Submitters of comments may, after a reasonable attempt to contact the - owner, request IANA to attach their comment to the SASL mechanism - registration itself by sending mail to <iana@iana.org>. At IANA's - sole discretion, IANA may attach the comment to the SASL mechanism's - registration. - -7.1.4. Change Control - - Once a SASL mechanism registration has been published by IANA, the - author may request a change to its definition. The change request - follows the same procedure as the registration request. - - The owner of a SASL mechanism may pass responsibility for the SASL - mechanism to another person or agency by informing IANA; this can be - done without discussion or review. - - The IESG may reassign responsibility for a SASL mechanism. The most - common case of this will be to enable changes to be made to - mechanisms where the author of the registration has died, has moved - out of contact, or is otherwise unable to make changes that are - important to the community. - - SASL mechanism registrations may not be deleted; mechanisms that are - no longer believed appropriate for use can be declared OBSOLETE by a - change to their "intended usage" field; such SASL mechanisms will be - clearly marked in the lists published by IANA. - - The IESG is considered to be the owner of all SASL mechanisms that - are on the IETF standards track. - - - - - - - - - - - - -Melnikov & Zeilenga Standards Track [Page 25] - -RFC 4422 SASL June 2006 - - -7.2. Registration Changes - - The IANA has updated the SASL mechanisms registry as follows: - - 1) Changed the "Intended usage" of the KERBEROS_V4 and SKEY mechanism - registrations to OBSOLETE. - - 2) Changed the "Published specification" of the EXTERNAL mechanism to - this document as indicated below: - - Subject: Updated Registration of SASL mechanism EXTERNAL - Family of SASL mechanisms: NO - SASL mechanism name: EXTERNAL - Security considerations: See A.3 of RFC 4422 - Published specification (optional, recommended): RFC 4422 - Person & email address to contact for further information: - Alexey Melnikov <Alexey.Melnikov@isode.com> - Intended usage: COMMON - Owner/Change controller: IESG <iesg@ietf.org> - Note: Updates existing entry for EXTERNAL - -8. References - -8.1. Normative References - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [RFC2244] Newman, C. and J. G. Myers, "ACAP -- Application - Configuration Access Protocol", RFC 2244, November - 1997. - - [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing - an IANA Considerations Section in RFCs", BCP 26, RFC - 2434, October 1998. - - [RFC2743] Linn, J., "Generic Security Service Application Program - Interface Version 2, Update 1", RFC 2743, January 2000. - - [RFC3454] Hoffman, P. and M. Blanchet, "Preparation of - Internationalized Strings ("stringprep")", RFC 3454, - December 2002. - - [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO - 10646", STD 63, RFC 3629, November 2003. - - [RFC4013] Zeilenga, K., "SASLprep: Stringprep Profile for User - Names and Passwords", RFC 4013, February 2005. - - - -Melnikov & Zeilenga Standards Track [Page 26] - -RFC 4422 SASL June 2006 - - - [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", RFC 4234, October 2005. - - [ASCII] Coded Character Set--7-bit American Standard Code for - Information Interchange, ANSI X3.4-1986. - - [Unicode] The Unicode Consortium, "The Unicode Standard, Version - 3.2.0" is defined by "The Unicode Standard, Version - 3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201- - 61633-5), as amended by the "Unicode Standard Annex - #27: Unicode 3.1" - (http://www.unicode.org/reports/tr27/) and by the - "Unicode Standard Annex #28: Unicode 3.2" - (http://www.unicode.org/reports/tr28/). - - [CharModel] Whistler, K. and M. Davis, "Unicode Technical Report - #17, Character Encoding Model", UTR17, - <http://www.unicode.org/unicode/reports/tr17/>, August - 2000. - - [Glossary] The Unicode Consortium, "Unicode Glossary", - <http://www.unicode.org/glossary/>. - -8.2. Informative References - - [RFC3206] Gellens, R., "The SYS and AUTH POP Response Codes", RFC - 3206, February 2002. - - [RFC3548] Josefsson, S., "The Base16, Base32, and Base64 Data - Encodings", RFC 3548, July 2003. - - [RFC4301] Kent, S. and K. Seo, "Security Architecture for the - Internet Protocol", RFC 4301, December 2005. - - [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer - Security (TLS) Protocol Version 1.1", RFC 4346, April - 2006. - - [SASL-GSSAPI] Melnikov, A. (Editor), "The Kerberos V5 ("GSSAPI") SASL - Mechanism", Work in Progress, May 2006. - - [UTR36] Davis, M., "(Draft) Unicode Technical Report #36, - Character Encoding Model", UTR17, - <http://www.unicode.org/unicode/reports/tr36/>, - February 2005. - - [CRAM-MD5] Nerenberg, L., "The CRAM-MD5 SASL Mechanism", Work in - Progress. - - - -Melnikov & Zeilenga Standards Track [Page 27] - -RFC 4422 SASL June 2006 - - - [DIGEST-MD5] Leach, P., C. Newman, and A. Melnikov, "Using Digest - Authentication as a SASL Mechanism", Work in Progress, - March 2006. - -9. Acknowledgements - - This document is a revision of RFC 2222 written by John Myers. - - This revision is a product of the IETF Simple Authentication and - Security Layer (SASL) Working Group. - - The following individuals contributed significantly to this revision: - Abhijit Menon-Sen, Hallvard Furuseth, Jeffrey Hutzelman, John Myers, - Luke Howard, Magnus Nystrom, Nicolas Williams, Peter Saint-Andre, RL - 'Bob' Morgan, Rob Siemborski, Sam Hartman, Simon Josefsson, Tim - Alsop, and Tony Hansen. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Melnikov & Zeilenga Standards Track [Page 28] - -RFC 4422 SASL June 2006 - - -Appendix A. The SASL EXTERNAL Mechanism - - This appendix is normative. - - The EXTERNAL mechanism allows a client to request the server to use - credentials established by means external to the mechanism to - authenticate the client. The external means may be, for instance, IP - Security [RFC4301] or TLS [RFC4346] services. In absence of some a - priori agreement between the client and the server, the client cannot - make any assumption as to what external means the server has used to - obtain the client's credentials, nor make an assumption as to the - form of credentials. For example, the client cannot assume that the - server will use the credentials the client has established via TLS. - -A.1. EXTERNAL Technical Specification - - The name of this mechanism is "EXTERNAL". - - The mechanism does not provide a security layer. - - The mechanism is capable of transferring an authorization identity - string. If empty, the client is requesting to act as the identity - the server has associated with the client's credentials. If non- - empty, the client is requesting to act as the identity represented by - the string. - - The client is expected to send data first in the authentication - exchange. Where the client does not provide an initial response data - in its request to initiate the authentication exchange, the server is - to respond to the request with an empty initial challenge and then - the client is to provide its initial response. - - The client sends the initial response containing the UTF-8 [RFC3629] - encoding of the requested authorization identity string. This - response is non-empty when the client is requesting to act as the - identity represented by the (non-empty) string. This response is - empty when the client is requesting to act as the identity the server - associated with its authentication credentials. - - The syntax of the initial response is specified as a value of the - <extern-initial-resp> production detailed below using the Augmented - Backus-Naur Form (ABNF) [RFC4234] notation. - - external-initial-resp = authz-id-string - authz-id-string = *( UTF8-char-no-nul ) - UTF8-char-no-nul = UTF8-1-no-nul / UTF8-2 / UTF8-3 / UTF8-4 - UTF8-1-no-nul = %x01-7F - - - - -Melnikov & Zeilenga Standards Track [Page 29] - -RFC 4422 SASL June 2006 - - - where the <UTF8-2>, <UTF8-3>, and <UTF8-4> productions are as defined - in [RFC3629]. - - There are no additional challenges and responses. - - Hence, the server is to return the outcome of the authentication - exchange. - - The exchange fails if - - - the client has not established its credentials via external means, - - - the client's credentials are inadequate, - - - the client provided an empty authorization identity string and the - server is unwilling or unable to associate an authorization - identity with the client's credentials, - - - the client provided a non-empty authorization identity string that - is invalid per the syntax requirements of the applicable - application protocol specification, - - - the client provided a non-empty authorization identity string - representing an identity that the client is not allowed to act as, - or - - - the server is unwilling or unable to provide service to the client - for any other reason. - - Otherwise the exchange is successful. When indicating a successful - outcome, additional data is not provided. - -A.2. SASL EXTERNAL Examples - - This section provides examples of EXTERNAL authentication exchanges. - The examples are intended to help the readers understand the above - text. The examples are not definitive. The Application - Configuration Access Protocol (ACAP) [RFC2244] is used in the - examples. - - The first example shows use of EXTERNAL with an empty authorization - identity. In this example, the initial response is not sent in the - client's request to initiate the authentication exchange. - - S: * ACAP (SASL "DIGEST-MD5") - C: a001 STARTTLS - S: a001 OK "Begin TLS negotiation now" - <TLS negotiation, further commands are under TLS layer> - - - -Melnikov & Zeilenga Standards Track [Page 30] - -RFC 4422 SASL June 2006 - - - S: * ACAP (SASL "DIGEST-MD5" "EXTERNAL") - C: a002 AUTHENTICATE "EXTERNAL" - S: + "" - C: + "" - S: a002 OK "Authenticated" - - The second example shows use of EXTERNAL with an authorization - identity of "fred@example.com". In this example, the initial - response is sent with the client's request to initiate the - authentication exchange. This saves a round-trip. - - S: * ACAP (SASL "DIGEST-MD5") - C: a001 STARTTLS - S: a001 OK "Begin TLS negotiation now" - <TLS negotiation, further commands are under TLS layer> - S: * ACAP (SASL "DIGEST-MD5" "EXTERNAL") - C: a002 AUTHENTICATE "EXTERNAL" {16+} - C: fred@example.com - S: a002 NO "Cannot assume requested authorization identity" - -A.3. Security Considerations - - The EXTERNAL mechanism provides no security protection; it is - vulnerable to spoofing by either client or server, active attack, and - eavesdropping. It should only be used when adequate security - services have been established. - -Appendix B. Changes since RFC 2222 - - This appendix is non-normative. - - The material in RFC 2222 was significantly rewritten in the - production of this document. - - RFC 2222, by not stating that the authorization identity string was a - string of Unicode characters, let alone character data, implied that - the authorization identity string was a string of octets. - - - The authorization identity string is now defined as a string of - Unicode characters. The NUL (U+0000) character is prohibited. - While protocol specifications are responsible for defining the - authorization identity form, as well as the Unicode string syntax - and related semantics, mechanism specifications are responsible - for defining how the Unicode string is carried in the - authentication exchange. - - - Deleted "If so, when the client does not send data first, the - initial challenge MUST be specified as being an empty challenge." - - - -Melnikov & Zeilenga Standards Track [Page 31] - -RFC 4422 SASL June 2006 - - - The following technical change was made to the EXTERNAL mechanism: - - - The authorization identity string is to be UTF-8 encoded. - - Note that protocol and mechanism specification requirements have - been significantly tightened. Existing protocol and mechanism - specifications will need to be updated to meet these requirements. - -Editors' Addresses - - Alexey Melnikov - Isode Limited - 5 Castle Business Village - 36 Station Road - Hampton, Middlesex, - TW12 2BX, United Kingdom - - EMail: Alexey.Melnikov@isode.com - URI: http://www.melnikov.ca/ - - - Kurt D. Zeilenga - OpenLDAP Foundation - - EMail: Kurt@OpenLDAP.org - - - - - - - - - - - - - - - - - - - - - - - - - - -Melnikov & Zeilenga Standards Track [Page 32] - -RFC 4422 SASL June 2006 - - -Full Copyright Statement - - Copyright (C) The Internet Society (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 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 provided by the IETF - Administrative Support Activity (IASA). - - - - - - - -Melnikov & Zeilenga Standards Track [Page 33] - diff --git a/imap/docs/rfc/rfc4466.txt b/imap/docs/rfc/rfc4466.txt deleted file mode 100644 index dfde1685..00000000 --- a/imap/docs/rfc/rfc4466.txt +++ /dev/null @@ -1,955 +0,0 @@ - - - - - - -Network Working Group A. Melnikov -Request for Comments: 4466 Isode Ltd. -Updates: 2088, 2342, 3501, 3502, 3516 C. Daboo -Category: Standards Track April 2006 - - - Collected Extensions to IMAP4 ABNF - -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 (2006). - -Abstract - - Over the years, many documents from IMAPEXT and LEMONADE working - groups, as well as many individual documents, have added syntactic - extensions to many base IMAP commands described in RFC 3501. For - ease of reference, this document collects most of such ABNF changes - in one place. - - This document also suggests a set of standard patterns for adding - options and extensions to several existing IMAP commands defined in - RFC 3501. The patterns provide for compatibility between existing - and future extensions. - - This document updates ABNF in RFCs 2088, 2342, 3501, 3502, and 3516. - It also includes part of the errata to RFC 3501. This document - doesn't specify any semantic changes to the listed RFCs. - - - - - - - - - - - - - - - -Melnikov & Daboo Standards Track [Page 1] - -RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 - - -Table of Contents - - 1. Introduction ....................................................2 - 1.1. Purpose of This Document ...................................2 - 1.2. Conventions Used in This Document ..........................3 - 2. IMAP ABNF Extensions ............................................3 - 2.1. Optional Parameters with the SELECT/EXAMINE Commands .......3 - 2.2. Extended CREATE Command ....................................4 - 2.3. Extended RENAME Command ....................................5 - 2.4. Extensions to FETCH and UID FETCH Commands .................6 - 2.5. Extensions to STORE and UID STORE Commands .................6 - 2.6. Extensions to SEARCH Command ...............................7 - 2.6.1. Extended SEARCH Command .............................7 - 2.6.2. ESEARCH untagged response ...........................8 - 2.7. Extensions to APPEND Command ...............................8 - 3. Formal Syntax ...................................................9 - 4. Security Considerations ........................................14 - 5. Normative References ...........................................15 - 6. Acknowledgements ...............................................15 - -1. Introduction - -1.1. Purpose of This Document - - This document serves several purposes: - - 1. rationalize and generalize ABNF for some existing IMAP - extensions; - 2. collect the ABNF in one place in order to minimize cross - references between documents; - 3. define building blocks for future extensions so that they can - be used together in a compatible way. - - It is expected that a future revision of this document will be - incorporated into a revision of RFC 3501. - - This document updates ABNF in RFCs 2088, 2342, 3501, 3502, and 3516. - It also includes part of the errata to RFC 3501. This document - doesn't specify any semantic changes to the listed RFCs. - - The ABNF in section 6 of RFC 2342 got rewritten to conform to the - ABNF syntax as defined in RFC 4234 and to reference new non-terminals - from RFC 3501. It was also restructured to allow for better - readability. There were no changes "on the wire". - - Section 2 extends ABNF for SELECT, EXAMINE, CREATE, RENAME, FETCH/UID - FETCH, STORE/UID STORE, SEARCH, and APPEND commands in a consistent - manner. Extensions to all the commands but APPEND have the same - - - -Melnikov & Daboo Standards Track [Page 2] - -RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 - - - structure. Extensibility for the APPEND command was done slightly - differently in order to preserve backward compatibility with existing - extensions. - - Section 2 also defines a new ESEARCH response, whose purpose is to - define a better version of the SEARCH response defined in RFC 3501. - - Section 3 defines the collected ABNF that replaces pieces of ABNF in - the aforementioned RFCs. The collected ABNF got generalized to allow - for easier future extensibility. - -1.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", "SHOULD", "SHOULD NOT", and "MAY" - in this document are to be interpreted as defined in "Key words for - use in RFCs to Indicate Requirement Levels" [KEYWORDS]. - -2. IMAP ABNF Extensions - - This section is not normative. It provides some background on the - intended use of different extensions and it gives some guidance about - how future extensions should extend the described commands. - -2.1. Optional Parameters with the SELECT/EXAMINE Commands - - This document adds the ability to include one or more parameters with - the IMAP SELECT (section 6.3.1 of [IMAP4]) or EXAMINE (section 6.3.2 - of [IMAP4]) commands, to turn on or off certain standard behaviors, - or to add new optional behaviors required for a particular extension. - - There are two possible modes of operation: - - o A global state change where a single use of the optional parameter - will affect the session state from that time on, irrespective of - subsequent SELECT/EXAMINE commands. - - o A per-mailbox state change that will affect the session only for - the duration of the new selected state. A subsequent - SELECT/EXAMINE without the optional parameter will cancel its - effect for the newly selected mailbox. - - Optional parameters to the SELECT or EXAMINE commands are added as a - parenthesized list of attribute/value pairs, and appear after the - mailbox name in the standard SELECT or EXAMINE command. The order of - individual parameters is arbitrary. A parameter value is optional - - - -Melnikov & Daboo Standards Track [Page 3] - -RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 - - - and may consist of atoms, strings, or lists in a specific order. If - the parameter value is present, it always appears in parentheses (*). - Any parameter not defined by extensions that the server supports must - be rejected with a BAD response. - - Example: - - C: a SELECT INBOX (ANNOTATE) - S: ... - S: a OK SELECT complete - - In the above example, a single parameter is used with the SELECT - command. - - Example: - - C: a EXAMINE INBOX (ANNOTATE RESPONSES ("UID Responses") - CONDSTORE) - S: ... - S: a OK EXAMINE complete - - In the above example, three parameters are used with the EXAMINE - command. The second parameter consists of two items: an atom - "RESPONSES" followed by a quoted string. - - Example: - - C: a SELECT INBOX (BLURDYBLOOP) - S: a BAD Unknown parameter in SELECT command - - In the above example, a parameter not supported by the server is - used. This results in the BAD response from the server. - - (*) - if a parameter has a mandatory value, which can always be - represented as a number or a sequence-set, the parameter value does - not need the enclosing (). See ABNF for more details. - -2.2. Extended CREATE Command - - Arguments: mailbox name - OPTIONAL list of CREATE parameters - - Responses: no specific responses for this command - - Result: OK - create completed - NO - create failure: cannot create mailbox with - that name - BAD - argument(s) invalid - - - -Melnikov & Daboo Standards Track [Page 4] - -RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 - - - This document adds the ability to include one or more parameters with - the IMAP CREATE command (see section 6.3.3 of [IMAP4]), to turn on or - off certain standard behaviors, or to add new optional behaviors - required for a particular extension. No CREATE parameters are - defined in this document. - - Optional parameters to the CREATE command are added as a - parenthesized list of attribute/value pairs after the mailbox name. - The order of individual parameters is arbitrary. A parameter value - is optional and may consist of atoms, strings, or lists in a specific - order. If the parameter value is present, it always appears in - parentheses (*). Any parameter not defined by extensions that the - server supports must be rejected with a BAD response. - - (*) - if a parameter has a mandatory value, which can always be - represented as a number or a sequence-set, the parameter value does - not need the enclosing (). See ABNF for more details. - -2.3. Extended RENAME Command - - Arguments: existing mailbox name - new mailbox name - OPTIONAL list of RENAME parameters - - Responses: no specific responses for this command - - Result: OK - rename completed - NO - rename failure: cannot rename mailbox with - that name, cannot rename to mailbox with - that name, etc. - BAD - argument(s) invalid - - This document adds the ability to include one or more parameters with - the IMAP RENAME command (see section 6.3.5 of [IMAP4]), to turn on or - off certain standard behaviors, or to add new optional behaviors - required for a particular extension. No RENAME parameters are - defined in this document. - - Optional parameters to the RENAME command are added as a - parenthesized list of attribute/value pairs after the new mailbox - name. The order of individual parameters is arbitrary. A parameter - value is optional and may consist of atoms, strings, or lists in a - specific order. If the parameter value is present, it always appears - in parentheses (*). Any parameter not defined by extensions that the - server supports must be rejected with a BAD response. - - - - - - -Melnikov & Daboo Standards Track [Page 5] - -RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 - - - (*) - if a parameter has a mandatory value, which can always be - represented as a number or a sequence-set, the parameter value does - not need the enclosing (). See ABNF for more details. - -2.4. Extensions to FETCH and UID FETCH Commands - - Arguments: sequence set - message data item names or macro - OPTIONAL fetch modifiers - - Responses: untagged responses: FETCH - - Result: OK - fetch completed - NO - fetch error: cannot fetch that data - BAD - command unknown or arguments invalid - - This document extends the syntax of the FETCH and UID FETCH commands - (see section 6.4.5 of [IMAP4]) to include optional FETCH modifiers. - No fetch modifiers are defined in this document. - - The order of individual modifiers is arbitrary. Each modifier is an - attribute/value pair. A modifier value is optional and may consist - of atoms and/or strings and/or lists in a specific order. If the - modifier value is present, it always appears in parentheses (*). Any - modifiers not defined by extensions that the server supports must be - rejected with a BAD response. - - (*) - if a modifier has a mandatory value, which can always be - represented as a number or a sequence-set, the modifier value does - not need the enclosing (). See ABNF for more details. - -2.5. Extensions to STORE and UID STORE Commands - - Arguments: message set - OPTIONAL store modifiers - message data item name - value for message data item - - Responses: untagged responses: FETCH - - Result: OK - store completed - NO - store error: cannot store that data - BAD - command unknown or arguments invalid - - This document extends the syntax of the STORE and UID STORE commands - (see section 6.4.6 of [IMAP4]) to include optional STORE modifiers. - No store modifiers are defined in this document. - - - - -Melnikov & Daboo Standards Track [Page 6] - -RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 - - - The order of individual modifiers is arbitrary. Each modifier is an - attribute/value pair. A modifier value is optional and may consist - of atoms and/or strings and/or lists in a specific order. If the - modifier value is present, it always appears in parentheses (*). Any - modifiers not defined by extensions that the server supports must be - rejected with a BAD response. - - (*) - if a modifier has a mandatory value, which can always be - represented as a number or a sequence-set, the modifier value does - not need the enclosing (). See ABNF for more details. - -2.6. Extensions to SEARCH Command - -2.6.1. Extended SEARCH Command - - Arguments: OPTIONAL result specifier - OPTIONAL [CHARSET] specification - searching criteria (one or more) - - Responses: REQUIRED untagged response: SEARCH (*) - - Result: OK - search completed - NO - search error: cannot search that [CHARSET] or - criteria - BAD - command unknown or arguments invalid - - This section updates definition of the SEARCH command described in - section 6.4.4 of [IMAP4]. - - The SEARCH command is extended to allow for result options. This - document does not define any result options. - - The order of individual options is arbitrary. Individual options may - contain parameters enclosed in parentheses (**). If an option has - parameters, they consist of atoms and/or strings and/or lists in a - specific order. Any options not defined by extensions that the - server supports must be rejected with a BAD response. - - (*) - An extension to the SEARCH command may require another untagged - response, or no untagged response to be returned. Section 2.6.2 - defines a new ESEARCH untagged response that replaces the SEARCH - untagged response. Note that for a given extended SEARCH command the - SEARCH and ESEARCH responses SHOULD be mutually exclusive, i.e., only - one of them should be returned. - - (**) - if an option has a mandatory parameter, which can always be - represented as a number or a sequence-set, the option parameter does - not need the enclosing (). See ABNF for more details. - - - -Melnikov & Daboo Standards Track [Page 7] - -RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 - - -2.6.2. ESEARCH untagged response - - Contents: one or more search-return-data pairs - - The ESEARCH response SHOULD be sent as a result of an extended SEARCH - or UID SEARCH command specified in section 2.6.1. - - The ESEARCH response starts with an optional search correlator. If - it is missing, then the response was not caused by a particular IMAP - command, whereas if it is present, it contains the tag of the command - that caused the response to be returned. - - The search correlator is followed by an optional UID indicator. If - this indicator is present, all data in the ESEARCH response refers to - UIDs, otherwise all returned data refers to message numbers. - - The rest of the ESEARCH response contains one or more search data - pairs. Each pair starts with unique return item name, followed by a - space and the corresponding data. Search data pairs may be returned - in any order. Unless specified otherwise by an extension, any return - item name SHOULD appear only once in an ESEARCH response. - - Example: S: * ESEARCH UID COUNT 5 ALL 4:19,21,28 - - Example: S: * ESEARCH (TAG "a567") UID COUNT 5 ALL 4:19,21,28 - - Example: S: * ESEARCH COUNT 5 ALL 1:17,21 - -2.7. Extensions to APPEND Command - - The IMAP BINARY extension [BINARY] extends the APPEND command to - allow a client to append data containing NULs by using the <literal8> - syntax. The ABNF was rewritten to allow for easier extensibility by - IMAP extensions. This document hasn't specified any semantical - changes to the [BINARY] extension. - - In addition, the non-terminal "literal8" defined in [BINARY] got - extended to allow for non-synchronizing literals if both [BINARY] and - [LITERAL+] extensions are supported by the server. - - The IMAP MULTIAPPEND extension [MULTIAPPEND] extends the APPEND - command to allow a client to append multiple messages atomically. - This document defines a common syntax for the APPEND command that - takes into consideration syntactic extensions defined by both - [BINARY] and [MULTIAPPEND] extensions. - - - - - - -Melnikov & Daboo Standards Track [Page 8] - -RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 - - -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 by - [IMAP4]. - - Except as noted otherwise, all alphabetic characters are case- - insensitive. The use of uppercase or lowercase characters to define - token strings is for editorial clarity only. Implementations MUST - accept these strings in a case-insensitive fashion. - - append = "APPEND" SP mailbox 1*append-message - ;; only a single append-message may appear - ;; if MULTIAPPEND [MULTIAPPEND] capability - ;; is not present - - append-message = append-opts SP append-data - - append-ext = append-ext-name SP append-ext-value - ;; This non-terminal define extensions to - ;; to message metadata. - - append-ext-name = tagged-ext-label - - append-ext-value= tagged-ext-val - ;; This non-terminal shows recommended syntax - ;; for future extensions. - - - append-data = literal / literal8 / append-data-ext - - append-data-ext = tagged-ext - ;; This non-terminal shows recommended syntax - ;; for future extensions, - ;; i.e., a mandatory label followed - ;; by parameters. - - append-opts = [SP flag-list] [SP date-time] *(SP append-ext) - ;; message metadata - - charset = atom / quoted - ;; Exact syntax is defined in [CHARSET]. - - create = "CREATE" SP mailbox - [create-params] - ;; Use of INBOX gives a NO error. - - - -Melnikov & Daboo Standards Track [Page 9] - -RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 - - - create-params = SP "(" create-param *( SP create-param) ")" - - create-param-name = tagged-ext-label - - create-param = create-param-name [SP create-param-value] - - create-param-value= tagged-ext-val - ;; This non-terminal shows recommended syntax - ;; for future extensions. - - - esearch-response = "ESEARCH" [search-correlator] [SP "UID"] - *(SP search-return-data) - ;; Note that SEARCH and ESEARCH responses - ;; SHOULD be mutually exclusive, - ;; i.e., only one of the response types - ;; should be - ;; returned as a result of a command. - - - examine = "EXAMINE" SP mailbox [select-params] - ;; modifies the original IMAP EXAMINE command - ;; to accept optional parameters - - fetch = "FETCH" SP sequence-set SP ("ALL" / "FULL" / - "FAST" / fetch-att / - "(" fetch-att *(SP fetch-att) ")") - [fetch-modifiers] - ;; modifies the original IMAP4 FETCH command to - ;; accept optional modifiers - - fetch-modifiers = SP "(" fetch-modifier *(SP fetch-modifier) ")" - - fetch-modifier = fetch-modifier-name [ SP fetch-modif-params ] - - fetch-modif-params = tagged-ext-val - ;; This non-terminal shows recommended syntax - ;; for future extensions. - - fetch-modifier-name = tagged-ext-label - - literal8 = "~{" number ["+"] "}" CRLF *OCTET - ;; A string that might contain NULs. - ;; <number> represents the number of OCTETs - ;; in the response string. - ;; The "+" is only allowed when both LITERAL+ and - ;; BINARY extensions are supported by the server. - - - - -Melnikov & Daboo Standards Track [Page 10] - -RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 - - - mailbox-data =/ Namespace-Response / - esearch-response - - Namespace = nil / "(" 1*Namespace-Descr ")" - - Namespace-Command = "NAMESPACE" - - Namespace-Descr = "(" string SP - (DQUOTE QUOTED-CHAR DQUOTE / nil) - *(Namespace-Response-Extension) ")" - - Namespace-Response-Extension = SP string SP - "(" string *(SP string) ")" - - Namespace-Response = "NAMESPACE" SP Namespace - SP Namespace SP Namespace - ;; This response is currently only allowed - ;; if the IMAP server supports [NAMESPACE]. - ;; The first Namespace is the Personal Namespace(s) - ;; The second Namespace is the Other Users' Namespace(s) - ;; The third Namespace is the Shared Namespace(s) - - rename = "RENAME" SP mailbox SP mailbox - [rename-params] - ;; Use of INBOX as a destination gives - ;; a NO error, unless rename-params - ;; is not empty. - - rename-params = SP "(" rename-param *( SP rename-param) ")" - - rename-param = rename-param-name [SP rename-param-value] - - rename-param-name = tagged-ext-label - - rename-param-value= tagged-ext-val - ;; This non-terminal shows recommended syntax - ;; for future extensions. - - - response-data = "*" SP response-payload CRLF - - response-payload= resp-cond-state / resp-cond-bye / - mailbox-data / message-data / capability-data - - search = "SEARCH" [search-return-opts] - SP search-program - - search-correlator = SP "(" "TAG" SP tag-string ")" - - - -Melnikov & Daboo Standards Track [Page 11] - -RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 - - - search-program = ["CHARSET" SP charset SP] - search-key *(SP search-key) - ;; CHARSET argument to SEARCH MUST be - ;; registered with IANA. - - search-return-data = search-modifier-name SP search-return-value - ;; Note that not every SEARCH return option - ;; is required to have the corresponding - ;; ESEARCH return data. - - search-return-opts = SP "RETURN" SP "(" [search-return-opt - *(SP search-return-opt)] ")" - - search-return-opt = search-modifier-name [SP search-mod-params] - - search-return-value = tagged-ext-val - ;; Data for the returned search option. - ;; A single "nz-number"/"number" value - ;; can be returned as an atom (i.e., without - ;; quoting). A sequence-set can be returned - ;; as an atom as well. - - search-modifier-name = tagged-ext-label - - search-mod-params = tagged-ext-val - ;; This non-terminal shows recommended syntax - ;; for future extensions. - - - select = "SELECT" SP mailbox [select-params] - ;; modifies the original IMAP SELECT command to - ;; accept optional parameters - - select-params = SP "(" select-param *(SP select-param) ")" - - select-param = select-param-name [SP select-param-value] - ;; a parameter to SELECT may contain one or - ;; more atoms and/or strings and/or lists. - - select-param-name= tagged-ext-label - - select-param-value= tagged-ext-val - ;; This non-terminal shows recommended syntax - ;; for future extensions. - - - status-att-list = status-att-val *(SP status-att-val) - ;; Redefines status-att-list from RFC 3501. - - - -Melnikov & Daboo Standards Track [Page 12] - -RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 - - - ;; status-att-val is defined in RFC 3501 errata - - status-att-val = ("MESSAGES" SP number) / - ("RECENT" SP number) / - ("UIDNEXT" SP nz-number) / - ("UIDVALIDITY" SP nz-number) / - ("UNSEEN" SP number) - ;; Extensions to the STATUS responses - ;; should extend this production. - ;; Extensions should use the generic - ;; syntax defined by tagged-ext. - - store = "STORE" SP sequence-set [store-modifiers] - SP store-att-flags - ;; extend [IMAP4] STORE command syntax - ;; to allow for optional store-modifiers - - store-modifiers = SP "(" store-modifier *(SP store-modifier) - ")" - - store-modifier = store-modifier-name [SP store-modif-params] - - store-modif-params = tagged-ext-val - ;; This non-terminal shows recommended syntax - ;; for future extensions. - - store-modifier-name = tagged-ext-label - - tag-string = string - ;; tag of the command that caused - ;; the ESEARCH response, sent as - ;; a string. - - tagged-ext = tagged-ext-label SP tagged-ext-val - ;; recommended overarching syntax for - ;; extensions - - tagged-ext-label = tagged-label-fchar *tagged-label-char - ;; Is a valid RFC 3501 "atom". - - tagged-label-fchar = ALPHA / "-" / "_" / "." - - tagged-label-char = tagged-label-fchar / DIGIT / ":" - - - - - - - - -Melnikov & Daboo Standards Track [Page 13] - -RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 - - - tagged-ext-comp = astring / - tagged-ext-comp *(SP tagged-ext-comp) / - "(" tagged-ext-comp ")" - ;; Extensions that follow this general - ;; syntax should use nstring instead of - ;; astring when appropriate in the context - ;; of the extension. - ;; Note that a message set or a "number" - ;; can always be represented as an "atom". - ;; An URL should be represented as - ;; a "quoted" string. - - tagged-ext-simple = sequence-set / number - - tagged-ext-val = tagged-ext-simple / - "(" [tagged-ext-comp] ")" - -4. Security Considerations - - This document updates ABNF in RFCs 2088, 2342, 3501, 3502, and 3516. - The updated documents must be consulted for security considerations - for the extensions that they define. - - As a protocol gets more complex, parser bugs become more common - including buffer overflow, denial of service, and other common - security coding errors. To the extent that this document makes the - parser more complex, it makes this situation worse. To the extent - that this document makes the parser more consistent and thus simpler, - the situation is improved. The impact will depend on how many - deployed IMAP extensions are consistent with this document. - Implementers are encouraged to take care of these issues when - extending existing implementations. Future IMAP extensions should - strive for consistency and simplicity to the greatest extent - possible. - - Extensions to IMAP commands that are permitted in NOT AUTHENTICATED - state are more sensitive to these security issues due to the larger - possible attacker community prior to authentication, and the fact - that some IMAP servers run with elevated privileges in that state. - This document does not extend any commands permitted in NOT - AUTHENTICATED state. Future IMAP extensions to commands permitted in - NOT AUTHENTICATED state should favor simplicity over consistency or - extensibility. - - - - - - - - -Melnikov & Daboo Standards Track [Page 14] - -RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 - - -5. 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. - - [CHARSET] Freed, N. and J. Postel, "IANA Charset Registration - Procedures", BCP 19, RFC 2978, October 2000. - - [MULTIAPPEND] Crispin, M., "Internet Message Access Protocol (IMAP) - - MULTIAPPEND Extension", RFC 3502, March 2003. - - [NAMESPACE] Gahrns, M. and C. Newman, "IMAP4 Namespace", RFC 2342, - May 1998. - - [LITERAL+] Myers, J., "IMAP4 non-synchronizing literals", RFC - 2088, January 1997. - - [BINARY] Nerenberg, L., "IMAP4 Binary Content Extension", RFC - 3516, April 2003. - -6. Acknowledgements - - This documents is based on ideas proposed by Pete Resnick, Mark - Crispin, Ken Murchison, Philip Guenther, Randall Gellens, and Lyndon - Nerenberg. - - However, all errors and omissions must be attributed to the authors - of the document. - - Thanks to Philip Guenther, Dave Cridland, Mark Crispin, Chris Newman, - Elwyn Davies, and Barry Leiba for comments and corrections. - - literal8 syntax was taken from RFC 3516. - - - - - - - - - - - - -Melnikov & Daboo Standards Track [Page 15] - -RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 - - -Authors' Addresses - - Alexey Melnikov - Isode Limited - 5 Castle Business Village - 36 Station Road - Hampton, Middlesex, TW12 2BX - UK - - EMail: Alexey.Melnikov@isode.com - - - Cyrus Daboo - - EMail: cyrus@daboo.name - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Melnikov & Daboo Standards Track [Page 16] - -RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 - - -Full Copyright Statement - - Copyright (C) The Internet Society (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 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 provided by the IETF - Administrative Support Activity (IASA). - - - - - - - -Melnikov & Daboo Standards Track [Page 17] - diff --git a/imap/docs/rfc/rfc4467.txt b/imap/docs/rfc/rfc4467.txt deleted file mode 100644 index 83b6516a..00000000 --- a/imap/docs/rfc/rfc4467.txt +++ /dev/null @@ -1,1011 +0,0 @@ - - - - - - -Network Working Group M. Crispin -Request for Comments: 4467 University of Washington -Updates: 3501 May 2006 -Category: Standards Track - - - Internet Message Access Protocol (IMAP) - URLAUTH Extension - -Status of This Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2006). - -Abstract - - This document describes the URLAUTH extension to the Internet Message - Access Protocol (IMAP) (RFC 3501) and the IMAP URL Scheme (IMAPURL) - (RFC 2192). This extension provides a means by which an IMAP client - can use URLs carrying authorization to access limited message data on - the IMAP server. - - An IMAP server that supports this extension indicates this with a - capability name of "URLAUTH". - -1. Introduction - - In [IMAPURL], a URL of the form imap://fred@example.com/INBOX/;uid=20 - requires authorization as userid "fred". However, [IMAPURL] implies - that it only supports authentication and confuses the concepts of - authentication and authorization. - - The URLAUTH extension defines an authorization mechanism for IMAP - URLs to replace [IMAPURL]'s authentication-only mechanism. URLAUTH - conveys authorization in the URL string itself and reuses a portion - of the syntax of the [IMAPURL] authentication mechanism to convey the - authorization identity (which also defines the default namespace in - [IMAP]). - - The URLAUTH extension provides a means by which an authorized user of - an IMAP server can create URLAUTH-authorized IMAP URLs. A URLAUTH- - authorized URL conveys authorization (not authentication) to the data - - - -Crispin Standards Track [Page 1] - -RFC 4467 IMAP - URLAUTH Extension May 2006 - - - addressed by that URL. This URL can be used in another IMAP session - to access specific content on the IMAP server, without otherwise - providing authorization to any other data (such as other data in the - mailbox specified in the URL) owned by the authorizing user. - - Conceptually, a URLAUTH-authorized URL can be thought of as a "pawn - ticket" that carries no authentication information and can be - redeemed by whomever presents it. However, unlike a pawn ticket, - URLAUTH has optional mechanisms to restrict the usage of a URLAUTH- - authorized URL. Using these mechanisms, URLAUTH-authorized URLs can - be usable by: - - . anonymous (the "pawn ticket" model) - . authenticated users only - . a specific authenticated user only - . message submission acting on behalf of a specific user only - - There is also a mechanism for expiration. - - A URLAUTH-authorized URL can be used in the argument to the BURL - command in message composition, as described in [BURL], for such - purposes as allowing a client (with limited memory or other - resources) to submit a message forward or to resend from an IMAP - mailbox without requiring the client to fetch that message data. - - The URLAUTH is generated using an authorization mechanism name and an - authorization token, which is generated using a secret mailbox access - key. An IMAP client can request that the server generate and assign - a new mailbox access key (thus effectively revoking all current URLs - using URLAUTH with the old mailbox access key) but cannot set the - mailbox access key to a key of its own choosing. - -1.1. Conventions Used in this Document - - The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" - in this document are to be interpreted as defined in [KEYWORDS]. - - The formal syntax uses the Augmented Backus-Naur Form (ABNF) notation - including the core rules defined in Appendix A of [ABNF]. - - 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. - - - - - - -Crispin Standards Track [Page 2] - -RFC 4467 IMAP - URLAUTH Extension May 2006 - - -2. Concepts - -2.1. URLAUTH - - The URLAUTH is a component, appended at the end of a URL, that - conveys authorization to access the data addressed by that URL. It - contains an authorized access identifier, an authorization mechanism - name, and an authorization token. The authorization token is - generated from the URL, the authorized access identifier, the - authorization mechanism name, and a mailbox access key. - -2.2. Mailbox Access Key - - The mailbox access key is a random string with at least 128 bits of - entropy. It is generated by software (not by the human user) and - MUST be unpredictable. - - Each user has a table of mailboxes and an associated mailbox access - key for each mailbox. Consequently, the mailbox access key is per- - user and per-mailbox. In other words, two users sharing the same - mailbox each have a different mailbox access key for that mailbox, - and each mailbox accessed by a single user also has a different - mailbox access key. - -2.3. Authorized Access Identifier - - The authorized access identifier restricts use of the URLAUTH - authorized URL to certain users authorized on the server, as - described in section 3. - -2.4. Authorization Mechanism - - The authorization mechanism is the algorithm by which the URLAUTH is - generated and subsequently verified, using the mailbox access key. - -2.4.1. INTERNAL Authorization Mechanism - - This specification defines the INTERNAL mechanism, which uses a token - generation algorithm of the server's choosing and does not involve - disclosure of the mailbox access key to the client. - - Note: The token generation algorithm chosen by the server - implementation should be modern and reasonably secure. At the - time of the writing of this document, an [HMAC] such as HMAC-SHA1 - is recommended. - - - - - - -Crispin Standards Track [Page 3] - -RFC 4467 IMAP - URLAUTH Extension May 2006 - - - If it becomes necessary to change the token generation algorithm - of the INTERNAL mechanism (e.g., because an attack against the - current algorithm has been discovered), all currently existing - URLAUTH-authorized URLs are invalidated by the change in - algorithm. Since this would be an unpleasant surprise to - applications that depend upon the validity of a URLAUTH-authorized - URL, and there is no good way to do a bulk update of existing - deployed URLs, it is best to avoid this situation by using a - secure algorithm as opposed to one that is "good enough". - - Server implementations SHOULD consider the possibility of changing - the algorithm. In some cases, it may be desirable to implement - the change of algorithm in a way that newly-generated tokens use - the new algorithm, but that for a limited period of time tokens - using either the new or old algorithm can be validated. - Consequently, the server SHOULD incorporate some means of - identifying the token generation algorithm within the token. - - Although this specification is extensible for other mechanisms, none - are defined in this document. In addition to the mechanism name - itself, other mechanisms may have mechanism-specific data, which is - to be interpreted according to the definition of that mechanism. - -2.5. Authorization Token - - The authorization token is a deterministic string of at least 128 - bits that an entity with knowledge of the secret mailbox access key - and URL authorization mechanism can use to verify the URL. - -3. IMAP URL Extensions - - [IMAPURL] is extended by allowing the addition of - ";EXPIRE=<datetime>" and ";URLAUTH=<access>:<mech>:<token>" to IMAP - URLs that refer to a specific message or message parts. - - The URLAUTH is comprised of ";URLAUTH=<access>:<mech>:<token>" and - MUST be at the end of the URL. - - URLAUTH does not apply to, and MUST NOT be used with, any IMAP URL - that refers to an entire IMAP server, a list of mailboxes, an entire - IMAP mailbox, or IMAP search results. - - When ";EXPIRE=<datetime>" is used, this indicates the latest date and - time that the URL is valid. After that date and time, the URL has - expired, and server implementations MUST reject the URL. If - ";EXPIRE=<datetime>" is not used, the URL has no expiration, but - still can be revoked as discussed below. - - - - -Crispin Standards Track [Page 4] - -RFC 4467 IMAP - URLAUTH Extension May 2006 - - - The URLAUTH takes the form ";URLAUTH=<access>:<mech>:<token>". It is - composed of three parts. The <access> portion provides the - authorized access identifiers, which may constrain the operations and - users that are permitted to use this URL. The <mech> portion - provides the authorization mechanism used by the IMAP server to - generate the authorization token that follows. The <token> portion - provides the authorization token. - - The "submit+" access identifier prefix, followed by a userid, - indicates that only a userid authorized as a message submission - entity on behalf of the specified userid is permitted to use this - URL. The IMAP server does not validate the specified userid but does - validate that the IMAP session has an authorization identity that is - authorized as a message submission entity. The authorized message - submission entity MUST validate the userid prior to contacting the - IMAP server. - - The "user+" access identifier prefix, followed by a userid, indicates - that use of this URL is limited to IMAP sessions that are logged in - as the specified userid (that is, have authorization identity as that - userid). - - Note: If a SASL mechanism that provides both authorization and - authentication identifiers is used to authenticate to the IMAP - server, the "user+" access identifier MUST match the authorization - identifier. - - The "authuser" access identifier indicates that use of this URL is - limited to IMAP sessions that are logged in as an authorized user - (that is, have authorization identity as an authorized user) of that - IMAP server. Use of this URL is prohibited to anonymous IMAP - sessions. - - The "anonymous" access identifier indicates that use of this URL is - not restricted by session authorization identity; that is, any IMAP - session in authenticated or selected state (as defined in [IMAP]), - including anonymous sessions, may issue a URLFETCH using this URL. - - The authorization token is represented as an ASCII-encoded - hexadecimal string, which is used to authorize the URL. The length - and the calculation of the authorization token depends upon the - mechanism used; but, in all cases, the authorization token is at - least 128 bits (and therefore at least 32 hexadecimal digits). - - - - - - - - -Crispin Standards Track [Page 5] - -RFC 4467 IMAP - URLAUTH Extension May 2006 - - -4. Discussion of URLAUTH Authorization Issues - - In [IMAPURL], the userid before the "@" in the URL has two purposes: - - 1) It provides context for user-specific mailbox paths such as - "INBOX". - - 2) It specifies that resolution of the URL requires logging in as - that user and limits use of that URL to only that user. - - An obvious limitation of using the same field for both purposes is - that the URL can only be resolved by the mailbox owner. - - URLAUTH overrides the second purpose of the userid in the IMAP URL - and by default permits the URL to be resolved by any user permitted - by the access identifier. - - The "user+<userid>" access identifier limits resolution of that URL - to a particular userid, whereas the "submit+<userid>" access - identifier is more general and simply requires that the session be - authorized by a user that has been granted a "submit" role within the - authentication system. Use of either of these access identifiers - makes it impossible for an attacker, spying on the session, to use - the same URL, either directly or by submission to a message - submission entity. - - The "authuser" and "anonymous" access identifiers do not have this - level of protection and should be used with caution. These access - identifiers are primarily useful for public export of data from an - IMAP server, without requiring that it be copied to a web or - anonymous FTP server. Refer to the Security Considerations for more - details. - -5. Generation of URLAUTH-Authorized URLs - - A URLAUTH-authorized URL is generated from an initial URL as follows: - - An initial URL is built, ending with ";URLAUTH=<access>" but without - the ":<mech>:<token>" components. An authorization mechanism is - selected and used to calculate the authorization token, with the - initial URL as the data and a secret known to the IMAP server as the - key. The URLAUTH-authorized URL is generated by taking the initial - URL and appending ":", the URL authorization mechanism name, ":", and - the ASCII-encoded hexadecimal representation of the authorization - token. - - - - - - -Crispin Standards Track [Page 6] - -RFC 4467 IMAP - URLAUTH Extension May 2006 - - - Note: ASCII-encoded hexadecimal is used instead of BASE64 because - a BASE64 representation may have "=" padding characters, which - would be problematic in a URL. - - In the INTERNAL mechanism, the mailbox access key for that mailbox is - the secret known to the IMAP server, and a server-selected algorithm - is used as described in section 2.4.1. - -6. Validation of URLAUTH-authorized URLs - - A URLAUTH-authorized URL is validated as follows: - - The URL is split at the ":" that separates "<access>" from - "<mech>:<token>" in the ";URLAUTH=<access>:<mech>:<token>" portion of - the URL. The "<mech>:<token>" portion is first parsed and saved as - the authorization mechanism and the authorization token. The URL is - truncated, discarding the ":" described above, to create a "rump URL" - (the URL minus the ":" and the "<mech>:<token>" portion). The rump - URL is then analyzed to identify the mailbox. - - If the mailbox cannot be identified, an authorization token is - calculated on the rump URL, using random "plausible" keys (selected - by the server) as needed, before returning a validation failure. - This prevents timing attacks aimed at identifying mailbox names. - - If the mailbox can be identified, the authorization token is - calculated on the rump URL and a secret known to the IMAP server - using the given URL authorization mechanism. Validation is - successful if, and only if, the calculated authorization token for - that mechanism matches the authorization token supplied in - ";URLAUTH=<access>:<mech>:<token>". - - Removal of the ":<mech>:<token>" portion of the URL MUST be the only - operation applied to the URLAUTH-authorized URL to get the rump URL. - In particular, URL percent escape decoding and case-folding - (including to the domain part of the URL) MUST NOT occur. - - In the INTERNAL mechanism, the mailbox access key for that mailbox is - used as the secret known to the IMAP server, and the same server- - selected algorithm used for generating URLs is used to calculate the - authorization token for verification. - - - - - - - - - - -Crispin Standards Track [Page 7] - -RFC 4467 IMAP - URLAUTH Extension May 2006 - - -7. Additional Commands - - These commands are extensions to the [IMAP] base protocol. - - The section headings of these commands are intended to correspond - with where they would be located in the base protocol document if - they were part of that document. - -BASE.6.3.RESETKEY. RESETKEY Command - - Arguments: optional mailbox name - optional mechanism name(s) - - Responses: none other than in result - - Result: OK - RESETKEY completed, URLMECH containing new data - NO - RESETKEY error: can't change key of that mailbox - BAD - command unknown or arguments invalid - - The RESETKEY command has two forms. - - The first form accepts a mailbox name as an argument and generates a - new mailbox access key for the given mailbox in the user's mailbox - access key table, replacing any previous mailbox access key (and - revoking any URLs that were authorized with a URLAUTH using that key) - in that table. By default, the mailbox access key is generated for - the INTERNAL mechanism; other mechanisms can be specified with the - optional mechanism argument. - - The second form, with no arguments, removes all mailbox access keys - in the user's mailbox access key table, revoking all URLs currently - authorized using URLAUTH by the user. - - Any current IMAP session logged in as the user that has the mailbox - selected will receive an untagged OK response with the URLMECH status - response code (see section BASE.7.1.URLMECH for more details about - the URLMECH status response code). - - Example: - - C: a31 RESETKEY - S: a31 OK All keys removed - C: a32 RESETKEY INBOX - S: a32 OK [URLMECH INTERNAL] mechs - C: a33 RESETKEY INBOX XSAMPLE - S: a33 OK [URLMECH INTERNAL XSAMPLE=P34OKhO7VEkCbsiYY8rGEg==] done - - - - - -Crispin Standards Track [Page 8] - -RFC 4467 IMAP - URLAUTH Extension May 2006 - - -BASE.6.3.GENURLAUTH. GENURLAUTH Command - - Argument: one or more URL/mechanism pairs - - Response: untagged response: GENURLAUTH - - Result: OK - GENURLAUTH completed - NO - GENURLAUTH error: can't generate a URLAUTH - BAD - command unknown or arguments invalid - - The GENURLAUTH command requests that the server generate a URLAUTH- - authorized URL for each of the given URLs using the given URL - authorization mechanism. - - The server MUST validate each supplied URL as follows: - - (1) The mailbox component of the URL MUST refer to an existing - mailbox. - - (2) The server component of the URL MUST contain a valid userid - that identifies the owner of the mailbox access key table that - will be used to generate the URLAUTH-authorized URL. As a - consequence, the iserver rule of [IMAPURL] is modified so that - iuserauth is mandatory. - - Note: the server component of the URL is generally the - logged in userid and server. If not, then the logged in - userid and server MUST have owner-type access to the - mailbox access key table owned by the userid and server - indicated by the server component of the URL. - - (3) There is a valid access identifier that, in the case of - "submit+" and "user+", will contain a valid userid. This - userid is not necessarily the same as the owner userid - described in (2). - - (4) The server MAY also verify that the iuid and/or isection - components (if present) are valid. - - If any of the above checks fail, the server MUST return a tagged BAD - response with the following exception. If an invalid userid is - supplied as the mailbox access key owner and/or as part of the access - identifier, the server MAY issue a tagged OK response with a - generated mailbox key that always fails validation when used with a - URLFETCH command. This exception prevents an attacker from - validating userids. - - - - - -Crispin Standards Track [Page 9] - -RFC 4467 IMAP - URLAUTH Extension May 2006 - - - If there is currently no mailbox access key for the given mailbox in - the owner's mailbox access key table, one is automatically generated. - That is, it is not necessary to use RESETKEY prior to first-time use - of GENURLAUTH. - - If the command is successful, a GENURLAUTH response code is returned - listing the requested URLs as URLAUTH-authorized URLs. - - Examples: - - C: a775 GENURLAUTH "imap://joe@example.com/INBOX/;uid=20/ - ;section=1.2" INTERNAL - S: a775 BAD missing access identifier in supplied URL - C: a776 GENURLAUTH "imap://example.com/Shared/;uid=20/ - ;section=1.2;urlauth=submit+fred" INTERNAL - S: a776 BAD missing owner username in supplied URL - C: a777 GENURLAUTH "imap://joe@example.com/INBOX/;uid=20/ - ;section=1.2;urlauth=submit+fred" INTERNAL - S: * GENURLAUTH "imap://joe@example.com/INBOX/;uid=20/;section=1.2 - ;urlauth=submit+fred:internal:91354a473744909de610943775f92038" - S: a777 OK GENURLAUTH completed - -BASE.6.3.URLFETCH. URLFETCH Command - - Argument: one or more URLs - - Response: untagged response: URLFETCH - - Result: OK - urlfetch completed - NO - urlfetch failed due to server internal error - BAD - command unknown or arguments invalid - - The URLFETCH command requests that the server return the text data - associated with the specified IMAP URLs, as described in [IMAPURL] - and extended by this document. The data is returned for all - validated URLs, regardless of whether or not the session would - otherwise be able to access the mailbox containing that data via - SELECT or EXAMINE. - - Note: This command does not require that the URL refer to the - selected mailbox; nor does it require that any mailbox be - selected. It also does not in any way interfere with any selected - mailbox. - - - - - - - - -Crispin Standards Track [Page 10] - -RFC 4467 IMAP - URLAUTH Extension May 2006 - - - The URLFETCH command effectively executes with the access of the - userid in the server component of the URL (which is generally the - userid that issued the GENURLAUTH). By itself, the URLAUTH does NOT - grant access to the data; once validated, it grants whatever access - to the data is held by the userid in the server component of the URL. - That access may have changed since the GENURLAUTH was done. - - The URLFETCH command MUST return an untagged URLFETCH response and a - tagged OK response to any URLFETCH command that is syntactically - valid. A NO response indicates a server internal failure that may be - resolved on later retry. - - Note: The possibility of a NO response is to accommodate - implementations that would otherwise have to issue an untagged BYE - with a fatal error due to an inability to respond to a valid - request. In an ideal world, a server SHOULD NOT issue a NO - response. - - The server MUST return NIL for any IMAP URL that references an entire - IMAP server, a list of mailboxes, an entire IMAP mailbox, or IMAP - search results. - - Example: - - Note: For clarity, this example uses the LOGIN command, which - SHOULD NOT be used over a non-encrypted communication path. - - This example is of a submit server, obtaining a message segment - for a message that it has already validated was submitted by - "fred". - - S: * OK [CAPABILITY IMAP4REV1 URLAUTH] example.com IMAP server - C: a001 LOGIN submitserver secret - S: a001 OK submitserver logged in - C: a002 URLFETCH "imap://joe@example.com/INBOX/;uid=20/ - ;section=1.2;urlauth=submit+fred:internal - :91354a473744909de610943775f92038" - S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/;section=1.2 - ;urlauth=submit+fred:internal - :91354a473744909de610943775f92038" {28} - S: Si vis pacem, para bellum. - S: - S: a002 OK URLFETCH completed - - - - - - - - -Crispin Standards Track [Page 11] - -RFC 4467 IMAP - URLAUTH Extension May 2006 - - -8. Additional Responses - - These responses are extensions to the [IMAP] base protocol. - - The section headings of these responses are intended to correspond - with where they would be located in the base protocol document if - they were part of that document. - -BASE.7.1.URLMECH. URLMECH Status Response Code - - The URLMECH status response code is followed by a list of URL - authorization mechanism names. Mechanism names other than INTERNAL - may be appended with an "=" and BASE64-encoded form of mechanism- - specific data. - - This status response code is returned in an untagged OK response in - response to a RESETKEY, SELECT, or EXAMINE command. In the case of - the RESETKEY command, this status response code can be sent in the - tagged OK response instead of requiring a separate untagged OK - response. - - Example: - - C: a33 RESETKEY INBOX XSAMPLE - S: a33 OK [URLMECH INTERNAL XSAMPLE=P34OKhO7VEkCbsiYY8rGEg==] done - - In this example, the server supports the INTERNAL mechanism and an - experimental mechanism called XSAMPLE, which also holds some - mechanism-specific data (the name "XSAMPLE" is for illustrative - purposes only). - -BASE.7.4.GENURLAUTH. GENURLAUTH Response - - Contents: One or more URLs - - The GENURLAUTH response returns the URLAUTH-authorized URL(s) - requested by a GENURLAUTH command. - - Example: - - C: a777 GENURLAUTH "imap://joe@example.com/INBOX/;uid=20/ - ;section=1.2;urlauth=submit+fred" INTERNAL - S: * GENURLAUTH "imap://joe@example.com/INBOX/;uid=20/;section=1.2 - ;urlauth=submit+fred:internal:91354a473744909de610943775f92038" - S: a777 OK GENURLAUTH completed - - - - - - -Crispin Standards Track [Page 12] - -RFC 4467 IMAP - URLAUTH Extension May 2006 - - -BASE.7.4.URLFETCH. URLFETCH Response - - Contents: One or more URL/nstring pairs - - The URLFETCH response returns the message text data associated with - one or more IMAP URLs, as described in [IMAPURL] and extended by this - document. This response occurs as the result of a URLFETCH command. - - The returned data string is NIL if the URL is invalid for any reason - (including validation failure). If the URL is valid, but the IMAP - fetch of the body part returned NIL (this should not happen), the - returned data string should be the empty string ("") and not NIL. - - Note: This command does not require that the URL refer to the - selected mailbox; nor does it require that any mailbox be - selected. It also does not in any way interfere with any selected - mailbox. - - Example: - - C: a002 URLFETCH "imap://joe@example.com/INBOX/;uid=20/ - ;section=1.2;urlauth=submit+fred:internal - :91354a473744909de610943775f92038" - S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/;section=1.2 - ;urlauth=submit+fred:internal - :91354a473744909de610943775f92038" {28} - S: Si vis pacem, para bellum. - S: - S: a002 OK URLFETCH completed - -9. Formal Syntax - - The following syntax specification uses the Augmented Backus-Naur - Form (ABNF) notation as specified in [ABNF]. - - The following modifications are made to the Formal Syntax in [IMAP]: - -resetkey = "RESETKEY" [SP mailbox *(SP mechanism)] - -capability =/ "URLAUTH" - -command-auth =/ resetkey / genurlauth / urlfetch - -resp-text-code =/ "URLMECH" SP "INTERNAL" *(SP mechanism ["=" base64]) - -genurlauth = "GENURLAUTH" 1*(SP url-rump SP mechanism) - -genurlauth-data = "*" SP "GENURLAUTH" 1*(SP url-full) - - - -Crispin Standards Track [Page 13] - -RFC 4467 IMAP - URLAUTH Extension May 2006 - - -url-full = astring - ; contains authimapurlfull as defined below - -url-rump = astring - ; contains authimapurlrump as defined below - -urlfetch = "URLFETCH" 1*(SP url-full) - -urlfetch-data = "*" SP "URLFETCH" 1*(SP url-full SP nstring) - - The following extensions are made to the Formal Syntax in [IMAPURL]: - -authimapurl = "imap://" enc-user [iauth] "@" hostport "/" - imessagepart - ; replaces "imapurl" and "iserver" rules for - ; URLAUTH authorized URLs - -authimapurlfull = authimapurl iurlauth - -authimapurlrump = authimapurl iurlauth-rump - -enc-urlauth = 32*HEXDIG - -enc-user = 1*achar - ; same as "enc_user" in RFC 2192 - -iurlauth = iurlauth-rump ":" mechanism ":" enc-urlauth - -iurlauth-rump = [expire] ";URLAUTH=" access - -access = ("submit+" enc-user) / ("user+" enc-user) / - "authuser" / "anonymous" - -expire = ";EXPIRE=" date-time - ; date-time defined in [DATETIME] - -mechanism = "INTERNAL" / 1*(ALPHA / DIGIT / "-" / ".") - ; case-insensitive - ; new mechanisms MUST be registered with IANA - - - - - - - - - - - - -Crispin Standards Track [Page 14] - -RFC 4467 IMAP - URLAUTH Extension May 2006 - - -10. Security Considerations - - Security considerations are discussed throughout this memo. - - The mailbox access key SHOULD have at least 128 bits of entropy - (refer to [RANDOM] for more details) and MUST be unpredictable. - - The server implementation of the INTERNAL mechanism SHOULD consider - the possibility of needing to change the token generation algorithm, - and SHOULD incorporate some means of identifying the token generation - algorithm within the token. - - The URLMECH status response code may expose sensitive data in the - mechanism-specific data for mechanisms other than INTERNAL. A server - implementation MUST implement a configuration that will not return a - URLMECH status response code unless some mechanism is provided that - protects the session from snooping, such as a TLS or SASL security - layer that provides confidentiality protection. - - The calculation of an authorization token with a "plausible" key if - the mailbox can not be identified is necessary to avoid attacks in - which the server is probed to see if a particular mailbox exists on - the server by measuring the amount of time taken to reject a known - bad name versus some other name. - - To protect against a computational denial-of-service attack, a server - MAY impose progressively longer delays on multiple URL requests that - fail validation. - - The decision to use the "authuser" access identifier should be made - with caution. An "authuser" access identifier can be used by any - authorized user of the IMAP server; therefore, use of this access - identifier should be limited to content that may be disclosed to any - authorized user of the IMAP server. - - The decision to use the "anonymous" access identifier should be made - with extreme caution. An "anonymous" access identifier can be used - by anyone; therefore, use of this access identifier should be limited - to content that may be disclosed to anyone. Many IMAP servers do not - permit anonymous access; in this case, the "anonymous" access - identifier is equivalent to "authuser", but this MUST NOT be relied - upon. - - Although this specification does not prohibit the theoretical - capability to generate a URL with a server component other than the - logged in userid and server, this capability should only be provided - - - - - -Crispin Standards Track [Page 15] - -RFC 4467 IMAP - URLAUTH Extension May 2006 - - - when the logged in userid/server has been authorized as equivalent to - the server component userid/server, or otherwise has access to that - userid/server mailbox access key table. - -11. IANA Considerations - - This document constitutes registration of the URLAUTH capability in - the imap4-capabilities registry. - - URLAUTH authorization mechanisms are registered by publishing a - standards track or IESG-approved experimental RFC. The registry is - currently located at: - -http://www.iana.org/assignments/urlauth-authorization-mechanism-registry - - This registry is case-insensitive. - - This document constitutes registration of the INTERNAL URLAUTH - authorization mechanism. - - IMAP URLAUTH Authorization Mechanism Registry - - Mechanism Name Reference - -------------- --------- - INTERNAL [RFC4467] - - - - - - - - - - - - - - - - - - - - - - - - - - -Crispin Standards Track [Page 16] - -RFC 4467 IMAP - URLAUTH Extension May 2006 - - -12. Normative References - - [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", RFC 4234, October 2005. - - [BURL] Newman, C., "Message Submission BURL Extension", RFC 4468, - May 2006. - - [DATETIME] Klyne, G. and C. Newman, "Date and Time on the Internet: - Timestamps", RFC 3339, July 2002. - - [IMAP] Crispin, M., "Internet Message Access Protocol - Version - 4rev1", RFC 3501, March 2003. - - [IMAPURL] Newman, C., "IMAP URL Scheme", RFC 2192, September 1997. - - [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - -13. Informative References - - [HMAC] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- - Hashing for Message Authentication", RFC 2104, February - 1997. - - [RANDOM] Eastlake, D., 3rd, Schiller, J., and S. Crocker, - "Randomness Requirements for Security", BCP 106, RFC 4086, - June 2005. - -Author's Address - - Mark R. Crispin - Networks and Distributed Computing - University of Washington - 4545 15th Avenue NE - Seattle, WA 98105-4527 - - Phone: (206) 543-5762 - EMail: MRC@CAC.Washington.EDU - - - - - - - - - - - - -Crispin Standards Track [Page 17] - -RFC 4467 IMAP - URLAUTH Extension May 2006 - - -Full Copyright Statement - - Copyright (C) The Internet Society (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 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 provided by the IETF - Administrative Support Activity (IASA). - - - - - - - -Crispin Standards Track [Page 18] - diff --git a/imap/docs/rfc/rfc4468.txt b/imap/docs/rfc/rfc4468.txt deleted file mode 100644 index b16dcb4e..00000000 --- a/imap/docs/rfc/rfc4468.txt +++ /dev/null @@ -1,787 +0,0 @@ - - - - - - -Network Working Group C. Newman -Request for Comments: 4468 Sun Microsystems -Updates: 3463 May 2006 -Category: Standards Track - - - Message Submission BURL Extension - -Status of This Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2006). - -Abstract - - The submission profile of Simple Mail Transfer Protocol (SMTP) - provides a standard way for an email client to submit a complete - message for delivery. This specification extends the submission - profile by adding a new BURL command that can be used to fetch - submission data from an Internet Message Access Protocol (IMAP) - server. This permits a mail client to inject content from an IMAP - server into the SMTP infrastructure without downloading it to the - client and uploading it back to the server. - - - - - - - - - - - - - - - - - - - - - -Newman Standards Track [Page 1] - -RFC 4468 Message Submission BURL Extension May 2006 - - -Table of Contents - - 1. Introduction ....................................................2 - 2. Conventions Used in This Document ...............................2 - 3. BURL Submission Extension .......................................3 - 3.1. SMTP Submission Extension Registration .....................3 - 3.2. BURL Transaction ...........................................3 - 3.3. The BURL IMAP Options ......................................4 - 3.4. Examples ...................................................5 - 3.5. Formal Syntax ..............................................6 - 4. 8-Bit and Binary ................................................7 - 5. Updates to RFC 3463 .............................................7 - 6. Response Codes ..................................................7 - 7. IANA Considerations .............................................9 - 8. Security Considerations .........................................9 - 9. References .....................................................11 - 9.1. Normative References ......................................11 - 9.2. Informative References ....................................12 - Appendix A. Acknowledgements .....................................13 - -1. Introduction - - This specification defines an extension to the standard Message - Submission [RFC4409] protocol to permit data to be fetched from an - IMAP server at message submission time. This MAY be used in - conjunction with the CHUNKING [RFC3030] mechanism so that chunks of - the message can come from an external IMAP server. This provides the - ability to forward an email message without first downloading it to - the client. - -2. Conventions Used in This Document - - The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" - in this document are to be interpreted as defined in "Key words for - use in RFCs to Indicate Requirement Levels" [RFC2119]. - - The formal syntax uses the Augmented Backus-Naur Form (ABNF) - [RFC4234] notation including the core rules defined in Appendix B of - RFC 4234. - - - - - - - - - - - - -Newman Standards Track [Page 2] - -RFC 4468 Message Submission BURL Extension May 2006 - - -3. BURL Submission Extension - - This section defines the BURL submission extension. - -3.1. SMTP Submission Extension Registration - - 1. The name of this submission extension is "BURL". This extends - the Message Submission protocol on port 587 and MUST NOT be - advertised by a regular SMTP [RFC2821] server on port 25 that - acts as a relay for incoming mail from other SMTP relays. - - 2. The EHLO keyword value associated with the extension is "BURL". - - 3. The BURL EHLO keyword will have zero or more arguments. The only - argument defined at this time is the "imap" argument, which MUST - be present in order to use IMAP URLs with BURL. Clients MUST - ignore other arguments after the BURL EHLO keyword unless they - are defined by a subsequent IETF standards track specification. - The arguments that appear after the BURL EHLO keyword may change - subsequent to the use of SMTP AUTH [RFC2554], so a server that - advertises BURL with no arguments prior to authentication - indicates that BURL is supported but authentication is required - to use it. - - 4. This extension adds the BURL SMTP verb. This verb is used as a - replacement for the DATA command and is only permitted during a - mail transaction after at least one successful RCPT TO. - -3.2. BURL Transaction - - A simple BURL transaction will consist of MAIL FROM, one or more RCPT - TO headers, and a BURL command with the "LAST" tag. The BURL command - will include an IMAP URL pointing to a fully formed message ready for - injection into the SMTP infrastructure. If PIPELINING [RFC2920] is - advertised, the client MAY send the entire transaction in one round - trip. If no valid RCPT TO address is supplied, the BURL command will - simply fail, and no resolution of the BURL URL argument will be - performed. If at least one valid RCPT TO address is supplied, then - the BURL URL argument will be resolved before the server responds to - the command. - - A more sophisticated BURL transaction MAY occur when the server also - advertises CHUNKING [RFC3030]. In this case, the BURL and BDAT - commands may be interleaved until one of them terminates the - transaction with the "LAST" argument. If PIPELINING [RFC2920] is - also advertised, then the client may pipeline the entire transaction - in one round-trip. However, it MUST wait for the results of the - "LAST" BDAT or BURL command prior to initiating a new transaction. - - - -Newman Standards Track [Page 3] - -RFC 4468 Message Submission BURL Extension May 2006 - - - The BURL command directs the server to fetch the data object to which - the URL refers and include it in the message. If the URL fetch - fails, the server will fail the entire transaction. - -3.3. The BURL IMAP Options - - When "imap" is present in the space-separated list of arguments - following the BURL EHLO keyword, it indicates that the BURL command - supports the URLAUTH [RFC4467] extended form of IMAP URLs [RFC2192] - and that the submit server is configured with the necessary - credentials to resolve "urlauth=submit+" IMAP URLs for the submit - server's domain. - - Subsequent to a successful SMTP AUTH command, the submission server - MAY indicate a prearranged trust relationship with a specific IMAP - server by including a BURL EHLO keyword argument of the form - "imap://imap.example.com". In this case, the submission server will - permit a regular IMAP URL referring to messages or parts of messages - on imap.example.com that the user who authenticated to the submit - server can access. Note that this form does not imply that the - submit server supports URLAUTH URLs; the submit server must advertise - both "imap" and "imap://imap.example.com" to indicate support for - both extended and non-extended URL forms. - - When the submit server connects to the IMAP server, it acts as an - IMAP client and thus is subject to both the mandatory-to-implement - IMAP capabilities in Section 6.1.1 of RFC 3501, and the security - considerations in Section 11 of RFC 3501. Specifically, this - requires that the submit server implement a configuration that uses - STARTTLS followed by SASL PLAIN [SASL-PLAIN] to authenticate to the - IMAP server. - - When the submit server resolves a URLAUTH IMAP URL, it uses submit - server credentials when authenticating to the IMAP server. The - authentication identity and password used for submit credentials MUST - be configurable. The string "submit" is suggested as a default value - for the authentication identity, with no default for the password. - Typically, the authorization identity is empty in this case; thus the - IMAP server will derive the authorization identity from the - authentication identity. If the IMAP URL uses the "submit+" access - identifier prefix, the submit server MUST refuse the BURL command - unless the userid in the URL's <access> token matches the submit - client's authorization identity. - - When the submit server resolves a regular IMAP URL, it uses the - submit client's authorization identity when authenticating to the - IMAP server. If both the submit client and the submit server's - embedded IMAP client use SASL PLAIN (or the equivalent), the submit - - - -Newman Standards Track [Page 4] - -RFC 4468 Message Submission BURL Extension May 2006 - - - server SHOULD forward the client's credentials if and only if the - submit server knows that the IMAP server is in the same - administrative domain. If the submit server supports SASL mechanisms - other than PLAIN, it MUST implement a configuration in which the - submit server's embedded IMAP client uses STARTTLS and SASL PLAIN - with the submit server's authentication identity and password (for - the respective IMAP server) and the submit client's authorization - identity. - -3.4. Examples - - 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. - - Two successful submissions (without and with pipelining) follow: - - <SSL/TLS encryption layer negotiated> - C: EHLO potter.example.com - S: 250-owlry.example.com - S: 250-8BITMIME - S: 250-BURL imap - S: 250-AUTH PLAIN - S: 250-DSN - S: 250 ENHANCEDSTATUSCODES - C: AUTH PLAIN aGFycnkAaGFycnkAYWNjaW8= - S: 235 2.7.0 PLAIN authentication successful. - C: MAIL FROM:<harry@gryffindor.example.com> - S: 250 2.5.0 Address Ok. - C: RCPT TO:<ron@gryffindor.example.com> - S: 250 2.1.5 ron@gryffindor.example.com OK. - C: BURL imap://harry@gryffindor.example.com/outbox - ;uidvalidity=1078863300/;uid=25;urlauth=submit+harry - :internal:91354a473744909de610943775f92038 LAST - S: 250 2.5.0 Ok. - - <SSL/TLS encryption layer negotiated> - C: EHLO potter.example.com - S: 250-owlry.example.com - S: 250-8BITMIME - S: 250-PIPELINING - S: 250-BURL imap - S: 250-AUTH PLAIN - S: 250-DSN - S: 250 ENHANCEDSTATUSCODES - C: AUTH PLAIN aGFycnkAaGFycnkAYWNjaW8= - - - -Newman Standards Track [Page 5] - -RFC 4468 Message Submission BURL Extension May 2006 - - - C: MAIL FROM:<harry@gryffindor.example.com> - C: RCPT TO:<ron@gryffindor.example.com> - C: BURL imap://harry@gryffindor.example.com/outbox - ;uidvalidity=1078863300/;uid=25;urlauth=submit+harry - :internal:91354a473744909de610943775f92038 LAST - S: 235 2.7.0 PLAIN authentication successful. - S: 250 2.5.0 Address Ok. - S: 250 2.1.5 ron@gryffindor.example.com OK. - S: 250 2.5.0 Ok. - - Note that PIPELINING of the AUTH command is only permitted if the - selected mechanism can be completed in one round trip, a client - initial response is provided, and no SASL security layer is - negotiated. This is possible for PLAIN and EXTERNAL, but not for - most other SASL mechanisms. - - Some examples of failure cases: - - C: MAIL FROM:<harry@gryffindor.example.com> - C: RCPT TO:<malfoy@slitherin.example.com> - C: BURL imap://harry@gryffindor.example.com/outbox - ;uidvalidity=1078863300/;uid=25;urlauth=submit+harry - :internal:91354a473744909de610943775f92038 LAST - S: 250 2.5.0 Address Ok. - S: 550 5.7.1 Relaying not allowed: malfoy@slitherin.example.com - S: 554 5.5.0 No recipients have been specified. - - C: MAIL FROM:<harry@gryffindor.example.com> - C: RCPT TO:<ron@gryffindor.example.com> - C: BURL imap://harry@gryffindor.example.com/outbox - ;uidvalidity=1078863300/;uid=25;urlauth=submit+harry - :internal:71354a473744909de610943775f92038 LAST - S: 250 2.5.0 Address Ok. - S: 250 2.1.5 ron@gryffindor.example.com OK. - S: 554 5.7.0 IMAP URL authorization failed - -3.5. Formal Syntax - - The following syntax specification inherits ABNF [RFC4234] and - Uniform Resource Identifiers [RFC3986]. - - burl-param = "imap" / ("imap://" authority) - ; parameter to BURL EHLO keyword - - burl-cmd = "BURL" SP absolute-URI [SP end-marker] CRLF - - end-marker = "LAST" - - - - -Newman Standards Track [Page 6] - -RFC 4468 Message Submission BURL Extension May 2006 - - -4. 8-Bit and Binary - - A submit server that advertises BURL MUST also advertise 8BITMIME - [RFC1652] and perform the down conversion described in that - specification on the resulting complete message if 8-bit data is - received with the BURL command and passed to a 7-bit server. If the - URL argument to BURL refers to binary data, then the submit server - MAY refuse the command or down convert as described in Binary SMTP - [RFC3030]. - - The Submit server MAY refuse to accept a BURL command or combination - of BURL and BDAT commands that result in un-encoded 8-bit data in - mail or MIME [RFC2045] headers. Alternatively, the server MAY accept - such data and down convert to MIME header encoding [RFC2047]. - -5. Updates to RFC 3463 - - SMTP or Submit servers that advertise ENHANCEDSTATUSCODES [RFC2034] - use enhanced status codes defined in RFC 3463 [RFC3463]. The BURL - extension introduces new error cases that that RFC did not consider. - The following additional enhanced status codes are defined by this - specification: - - X.6.6 Message content not available - - The message content could not be fetched from a remote system. - This may be useful as a permanent or persistent temporary - notification. - - X.7.8 Trust relationship required - - The submission server requires a configured trust relationship - with a third-party server in order to access the message content. - -6. Response Codes - - This section includes example response codes to the BURL command. - Other text may be used with the same response codes. This list is - not exhaustive, and BURL clients MUST tolerate any valid SMTP - response code. Most of these examples include the appropriate - enhanced status code [RFC3463]. - - 554 5.5.0 No recipients have been specified - - This response code occurs when BURL is used (for example, with - PIPELINING) and all RCPT TOs failed. - - - - - -Newman Standards Track [Page 7] - -RFC 4468 Message Submission BURL Extension May 2006 - - - 503 5.5.0 Valid RCPT TO required before BURL - - This response code is an alternative to the previous one when BURL - is used (for example, with PIPELINING) and all RCPT TOs failed. - - 554 5.6.3 Conversion required but not supported - - This response code occurs when the URL points to binary data and - the implementation does not support down conversion to base64. - This can also be used if the URL points to message data with 8-bit - content in headers and the server does not down convert such - content. - - 554 5.3.4 Message too big for system - - The message (subsequent to URL resolution) is larger than the - per-message size limit for this server. - - 554 5.7.8 URL resolution requires trust relationship - - The submit server does not have a trust relationship with the IMAP - server specified in the URL argument to BURL. - - 552 5.2.2 Mailbox full - - The recipient is local, the submit server supports direct - delivery, and the recipient has exceeded his quota and any grace - period for delivery attempts. - - 554 5.6.6 IMAP URL resolution failed - - The IMAP URLFETCH command returned an error or no data. - - 250 2.5.0 Waiting for additional BURL or BDAT commands - - A BURL command without the "LAST" modifier was sent. The URL for - this BURL command was successfully resolved, but the content will - not necessarily be committed to persistent storage until the rest - of the message content is collected. For example, a Unix server - may have written the content to a queue file buffer, but may not - yet have performed an fsync() operation. If the server loses - power, the content can still be lost. - - 451 4.4.1 IMAP server unavailable - - The connection to the IMAP server to resolve the URL failed. - - - - - -Newman Standards Track [Page 8] - -RFC 4468 Message Submission BURL Extension May 2006 - - - 250 2.5.0 Ok. - - The URL was successfully resolved, and the complete message data - has been committed to persistent storage. - - 250 2.6.4 MIME header conversion with loss performed - - The URL pointed to message data that included mail or MIME headers - with 8-bit data. This data was converted to MIME header encoding - [RFC2047], but the submit server may not have correctly guessed - the unlabeled character set. - -7. IANA Considerations - - The "BURL" SMTP extension as described in Section 3 has been - registered. This registration has been marked for use by message - submission [RFC4409] only in the registry. - -8. Security Considerations - - Modern SMTP submission servers often include content-based security - and denial-of-service defense mechanisms such as virus filtering, - size limits, server-generated signatures, spam filtering, etc. - Implementations of BURL should fetch the URL content prior to - application of such content-based mechanisms in order to preserve - their function. - - Clients that generate unsolicited bulk email or email with viruses - could use this mechanism to compensate for a slow link between the - client and submit server. In particular, this mechanism would make - it feasible for a programmable cell phone or other device on a slow - link to become a significant source of unsolicited bulk email and/or - viruses. This makes it more important for submit server vendors - implementing BURL to have auditing and/or defenses against such - denial-of-service attacks including mandatory authentication, logging - that associates unique client identifiers with mail transactions, - limits on reuse of the same IMAP URL, rate limits, recipient count - limits, and content filters. - - Transfer of the URLAUTH [RFC4467] form of IMAP URLs in the clear can - expose the authorization token to network eavesdroppers. - Implementations that support such URLs can address this issue by - using a strong confidentiality protection mechanism. For example, - the SMTP STARTTLS [RFC3207] and the IMAP STARTTLS [RFC3501] - extensions, in combination with a configuration setting that requires - their use with such IMAP URLs, would address this concern. - - - - - -Newman Standards Track [Page 9] - -RFC 4468 Message Submission BURL Extension May 2006 - - - Use of a prearranged trust relationship between a submit server and a - specific IMAP server introduces security considerations. A - compromise of the submit server should not automatically compromise - all accounts on the IMAP server, so trust relationships involving - super-user proxy credentials are strongly discouraged. A system that - requires the submit server to authenticate to the IMAP server with - submit credentials and subsequently requires a URLAUTH URL to fetch - any content addresses this concern. A trusted third party model for - proxy credentials (such as that provided by Kerberos 5 [RFC4120]) - would also suffice. - - When a client uses SMTP STARTTLS to send a BURL command that - references non-public information, there is a user expectation that - the entire message content will be treated confidentially. To - address this expectation, the message submission server SHOULD use - STARTTLS or a mechanism providing equivalent data confidentiality - when fetching the content referenced by that URL. - - A legitimate user of a submit server may try to compromise other - accounts on the server by providing an IMAP URLAUTH URL that points - to a server under that user's control that is designed to undermine - the security of the submit server. For this reason, the IMAP client - code that the submit server uses must be robust with respect to - arbitrary input sizes (including large IMAP literals) and arbitrary - delays from the IMAP server. Requiring a prearranged trust - relationship between a submit server and the IMAP server also - addresses this concern. - - An authorized user of the submit server could set up a fraudulent - IMAP server and pass a URL for that server to the submit server. The - submit server might then contact the fraudulent IMAP server to - authenticate with submit credentials and fetch content. There are - several ways to mitigate this potential attack. A submit server that - only uses submit credentials with a fixed set of trusted IMAP servers - will not be vulnerable to exposure of those credentials. A submit - server can treat the IMAP server as untrusted and include defenses - for buffer overflows, denial-of-service slowdowns, and other - potential attacks. Finally, because authentication is required to - use BURL, it is possible to keep a secure audit trail and use that to - detect and punish the offending party. - - - - - - - - - - - -Newman Standards Track [Page 10] - -RFC 4468 Message Submission BURL Extension May 2006 - - -9. References - -9.1. Normative References - - [RFC1652] Klensin, J., Freed, N., Rose, M., Stefferud, E., and D. - Crocker, "SMTP Service Extension for - 8bit-MIMEtransport", RFC 1652, July 1994. - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [RFC2192] Newman, C., "IMAP URL Scheme", RFC 2192, - September 1997. - - [RFC2554] Myers, J., "SMTP Service Extension for Authentication", - RFC 2554, March 1999. - - [RFC2821] Klensin, J., "Simple Mail Transfer Protocol", RFC 2821, - April 2001. - - [RFC3207] Hoffman, P., "SMTP Service Extension for Secure SMTP - over Transport Layer Security", RFC 3207, - February 2002. - - [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - - VERSION 4rev1", RFC 3501, March 2003. - - [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, - "Uniform Resource Identifier (URI): Generic Syntax", - STD 66, RFC 3986, January 2005. - - [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", RFC 4234, October 2005. - - [RFC4409] Gellens, R. and J. Klensin, "Message Submission for - Mail", RFC 4409, April 2006. - - [RFC4467] Crispin, M., "Internet Message Access Protocol (IMAP) - - URLAUTH Extension", RFC 4467, May 2006. - - - - - - - - - - - - -Newman Standards Track [Page 11] - -RFC 4468 Message Submission BURL Extension May 2006 - - -9.2. Informative References - - [RFC2034] Freed, N., "SMTP Service Extension for Returning - Enhanced Error Codes", RFC 2034, October 1996. - - [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. - - [RFC2920] Freed, N., "SMTP Service Extension for Command - Pipelining", STD 60, RFC 2920, September 2000. - - [RFC3030] Vaudreuil, G., "SMTP Service Extensions for - Transmission of Large and Binary MIME Messages", - RFC 3030, December 2000. - - [RFC3463] Vaudreuil, G., "Enhanced Mail System Status Codes", - RFC 3463, January 2003. - - [RFC4120] Neuman, C., Yu, T., Hartman, S., and K. Raeburn, "The - Kerberos Network Authentication Service (V5)", RFC - 4120, July 2005. - - [SASL-PLAIN] Zeilenga, K., "The Plain SASL Mechanism", Work in - Progress, March 2005. - - - - - - - - - - - - - - - - - - - - - - -Newman Standards Track [Page 12] - -RFC 4468 Message Submission BURL Extension May 2006 - - -Appendix A. Acknowledgements - - This document is a product of the lemonade WG. Many thanks are due - to all the participants of that working group for their input. Mark - Crispin was instrumental in the conception of this mechanism. Thanks - to Randall Gellens, Alexey Melnikov, Sam Hartman, Ned Freed, Dave - Cridland, Peter Coates, and Mark Crispin for review comments on the - document. Thanks to the RFC Editor for correcting the author's - grammar mistakes. Thanks to Ted Hardie, Randall Gellens, Mark - Crispin, Pete Resnick, and Greg Vaudreuil for extremely interesting - debates comparing this proposal and alternatives. Thanks to the - lemonade WG chairs Eric Burger and Glenn Parsons for concluding the - debate at the correct time and making sure this document got - completed. - -Author's Address - - Chris Newman - Sun Microsystems - 3401 Centrelake Dr., Suite 410 - Ontario, CA 91761 - US - - EMail: chris.newman@sun.com - - - - - - - - - - - - - - - - - - - - - - - - - - - -Newman Standards Track [Page 13] - -RFC 4468 Message Submission BURL Extension May 2006 - - -Full Copyright Statement - - Copyright (C) The Internet Society (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 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 provided by the IETF - Administrative Support Activity (IASA). - - - - - - - -Newman Standards Track [Page 14] - diff --git a/imap/docs/rfc/rfc4469.txt b/imap/docs/rfc/rfc4469.txt deleted file mode 100644 index da365514..00000000 --- a/imap/docs/rfc/rfc4469.txt +++ /dev/null @@ -1,731 +0,0 @@ - - - - - - -Network Working Group P. Resnick -Request for Comments: 4469 QUALCOMM Incorporated -Updates: 3501, 3502 April 2006 -Category: Standards Track - - - Internet Message Access Protocol (IMAP) CATENATE Extension - -Status of This Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2006). - -Abstract - - The CATENATE extension to the Internet Message Access Protocol (IMAP) - extends the APPEND command to allow clients to create messages on the - IMAP server that may contain a combination of new data along with - parts of (or entire) messages already on the server. Using this - extension, the client can catenate parts of an already existing - message onto a new message without having to first download the data - and then upload it back to the server. - - - - - - - - - - - - - - - - - - - - - - -Resnick Standards Track [Page 1] - -RFC 4469 IMAP CATENATE Extension April 2006 - - -1. Introduction - - The CATENATE extension to the Internet Message Access Protocol (IMAP) - [1] allows the client to create a message on the server that can - include the text of messages (or parts of messages) that already - exist on the server without having to FETCH them and APPEND them back - to the server. The CATENATE extension extends the APPEND command so - that, instead of a single message literal, the command can take as - arguments any combination of message literals (as described in IMAP - [1]) and message URLs (as described in the IMAP URL Scheme [2] - specification). The server takes all the pieces and catenates them - into the output message. The CATENATE extension can also coexist - with the MULTIAPPEND extension [3] to APPEND multiple messages in a - single command. - - There are some obvious uses for the CATENATE extension. The - motivating use case was to provide a way for a resource-constrained - client to compose a message for subsequent submission that contains - data that already exists in that client's IMAP store. Because the - client does not have to download and re-upload potentially large - message parts, bandwidth and processing limitations do not have as - much impact. In addition, since the client can create a message in - its own IMAP store, the command also addresses the desire of the - client to archive a copy of a sent message without having to upload - the message twice. (Mechanisms for sending the message are outside - the scope of this document.) - - The extended APPEND command can also be used to copy parts of a - message to another mailbox for archival purposes while getting rid of - undesired parts. In environments where server storage is limited, a - client could get rid of large message parts by copying over only the - necessary parts and then deleting the original message. The - mechanism could also be used to add data to a message (such as - prepending message header fields) or to include other data by making - a copy of the original and catenating the new data. - -2. The CATENATE Capability - - A server that supports this extension returns "CATENATE" as one of - the responses to the CAPABILITY command. - - - - - - - - - - - -Resnick Standards Track [Page 2] - -RFC 4469 IMAP CATENATE Extension April 2006 - - -3. The APPEND Command - - Arguments: mailbox name - (The following can be repeated in the presence of the - MULTIAPPEND extension [3]) - OPTIONAL flag parenthesized list - OPTIONAL date/time string - a single message literal or one or more message parts to - catenate, specified as: - message literal - or - message (or message part) URL - - Responses: OPTIONAL NO responses: BADURL, TOOBIG - - Result: OK - append completed - NO - append error: can't append to that mailbox, error - in flags or date/time or message text, or can't - fetch that data - BAD - command unknown or arguments invalid - - The APPEND command concatenates all the message parts and appends - them as a new message to the end of the specified mailbox. The - parenthesized flag list and date/time string set the flags and the - internal date, respectively, as described in IMAP [1]. The - subsequent command parameters specify the message parts that are - appended sequentially to the output message. - - If the original form of APPEND is used, a message literal follows the - optional flag list and date/time string, which is appended as - described in IMAP [1]. If the extended form is used, "CATENATE" and - a parenthesized list of message literals and message URLs follows, - each of which is appended to the new message. If a message literal - is specified (indicated by "TEXT"), the octets following the count - are appended. If a message URL is specified (indicated by "URL"), - the octets of the body part pointed to by that URL are appended, as - if the literal returned in a FETCH BODY response were put in place of - the message part specifier. The APPEND command does not cause the - \Seen flag to be set for any catenated body part. The APPEND command - does not change the selected mailbox. - - In the extended APPEND command, the string following "URL" is an IMAP - URL [2] and is interpreted according to the rules of [2]. The - present document only describes the behavior of the command using - IMAP URLs that refer to specific messages or message parts on the - current IMAP server from the current authenticated IMAP session. - Because of that, only relative IMAP message or message part URLs - (i.e., those having no scheme or <iserver>) are used. The base URL - - - -Resnick Standards Track [Page 3] - -RFC 4469 IMAP CATENATE Extension April 2006 - - - for evaluating the relative URL is considered "imap://user@server/", - where "user" is the user name of the currently authenticated user and - "server" is the domain name of the current server. When in the - selected state, the base URL is considered - "imap://user@server/mailbox", where "mailbox" is the encoded name of - the currently selected mailbox. Additionally, since the APPEND - command is valid in the authenticated state of an IMAP session, no - further LOGIN or AUTHENTICATE command is performed for URLs specified - in the extended APPEND command. - - Note: Use of an absolute IMAP URL or any URL that refers to - anything other than a message or message part from the current - authenticated IMAP session is outside the scope of this document - and would require an extension to this specification, and a server - implementing only this specification would return NO to such a - request. - - The client is responsible for making sure that the catenated message - is in the format of an Internet Message Format (RFC 2822) [4] or - Multipurpose Internet Mail Extension (MIME) [5] message. In - particular, when a URL is catenated, the server copies octets, - unchanged, from the indicated message or message part to the - catenated message. It does no data conversion (e.g., MIME transfer - encodings) nor any verification that the data is appropriate for the - MIME part of the message into which it is inserted. The client is - also responsible for inserting appropriate MIME boundaries between - body parts, and writing MIME Content-Type and Content-Transfer- - Encoding lines as needed in the appropriate places. - - Responses behave just as the original APPEND command described in - IMAP [1]. If the server implements the IMAP UIDPLUS extension [6], - it will also return an APPENDUID response code in the tagged OK - response. Two response codes are provided in Section 4 that can be - used in the tagged NO response if the APPEND command fails. - -4. Response Codes - - When a APPEND command fails, it may return a response code that - describes a reason for the failure. - -4.1. BADURL Response - - The BADURL response code is returned if the APPEND fails to process - one of the specified URLs. Possible reasons for this are bad URL - syntax, unrecognized URL schema, invalid message UID, or invalid body - part. The BADURL response code contains the first URL specified as a - parameter to the APPEND command that has caused the operation to - fail. - - - -Resnick Standards Track [Page 4] - -RFC 4469 IMAP CATENATE Extension April 2006 - - -4.2. TOOBIG Response - - The TOOBIG response code is returned if the resulting message will - exceed the 4-GB IMAP message limit. This might happen, for example, - if the client specifies 3 URLs for 2-GB messages. Note that even if - the server doesn't return TOOBIG, it still has to be defensive - against misbehaving or malicious clients that try to construct a - message over the 4-GB limit. The server may also wish to return the - TOOBIG response code if the resulting message exceeds a server- - specific message size limit. - -5. Formal Syntax - - The following syntax specification uses the Augmented Backus-Naur - Form (ABNF) [7] notation. Elements not defined here can be found in - the formal syntax of the ABNF [7], IMAP [1], and IMAP ABNF extensions - [8] specifications. Note that capability and resp-text-code are - extended from the IMAP [1] specification and append-data is extended - from the IMAP ABNF extensions [8] specification. - - append-data =/ "CATENATE" SP "(" cat-part *(SP cat-part) ")" - - cat-part = text-literal / url - - text-literal = "TEXT" SP literal - - url = "URL" SP astring - - resp-text-code =/ toobig-response-code / badurl-response-code - - toobig-response-code = "TOOBIG" - - badurl-response-code = "BADURL" SP url-resp-text - - url-resp-text = 1*(%x01-09 / - %x0B-0C / - %x0E-5B / - %x5D-FE) ; Any TEXT-CHAR except "]" - - capability =/ "CATENATE" - - The astring in the definition of url and the url-resp-text in the - definition of badurl-response-code each contain an imapurl as defined - by [2]. - - - - - - - -Resnick Standards Track [Page 5] - -RFC 4469 IMAP CATENATE Extension April 2006 - - -6. Acknowledgements - - Thanks to the members of the LEMONADE working group for their input. - Special thanks to Alexey Melnikov for the examples. - -7. Security Considerations - - The CATENATE extension does not raise any security considerations - that are not present for the base protocol or in the use of IMAP - URLs, and these issues are discussed in the IMAP [1] and IMAP URL [2] - documents. - -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 CATENATE IMAP capability. The IANA has added this - capability to the registry. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Resnick Standards Track [Page 6] - -RFC 4469 IMAP CATENATE Extension April 2006 - - -Appendix A. Examples - - Lines not starting with "C: " or "S: " are continuations of the - previous lines. - - The original message in examples 1 and 2 below (UID = 20) has the - following structure: - - - multipart/mixed MIME message with two body parts: - - 1. text/plain - - 2. application/x-zip-compressed - - Example 1: The following example demonstrates how a CATENATE client - can replace an attachment in a draft message, without the need to - download it to the client and upload it back. - - C: A003 APPEND Drafts (\Seen \Draft $MDNSent) CATENATE - (URL "/Drafts;UIDVALIDITY=385759045/;UID=20/;section=HEADER" - TEXT {42} - S: + Ready for literal data - C: - C: --------------030308070208000400050907 - C: URL "/Drafts;UIDVALIDITY=385759045/;UID=20/;section=1.MIME" - URL "/Drafts;UIDVALIDITY=385759045/;UID=20/;section=1" TEXT {42} - S: + Ready for literal data - C: - C: --------------030308070208000400050907 - C: URL "/Drafts;UIDVALIDITY=385759045/;UID=30" TEXT {44} - S: + Ready for literal data - C: - C: --------------030308070208000400050907-- - C: ) - S: A003 OK catenate append completed - - - - - - - - - - - - - - - -Resnick Standards Track [Page 7] - -RFC 4469 IMAP CATENATE Extension April 2006 - - - Example 2: The following example demonstrates how the CATENATE - extension can be used to replace edited text in a draft message, as - well as header fields for the top level message part (e.g., Subject - has changed). The previous version of the draft is marked as - \Deleted. Note that the server also supports the UIDPLUS extension, - so the APPENDUID response code is returned in the successful OK - response to the APPEND command. - - C: A003 APPEND Drafts (\Seen \Draft $MDNSent) CATENATE (TEXT {738} - S: + Ready for literal data - C: Return-Path: <bar@example.org> - C: Received: from [127.0.0.2] - C: by rufus.example.org via TCP (internal) with ESMTPA; - C: Thu, 11 Nov 2004 16:57:07 +0000 - C: Message-ID: <419399E1.6000505@example.org> - C: Date: Thu, 12 Nov 2004 16:57:05 +0000 - C: From: Bob Ar <bar@example.org> - C: X-Accept-Language: en-us, en - C: MIME-Version: 1.0 - C: To: foo@example.net - C: Subject: About our holiday trip - C: Content-Type: multipart/mixed; - C: boundary="------------030308070208000400050907" - C: - C: --------------030308070208000400050907 - C: Content-Type: text/plain; charset=us-ascii; format=flowed - C: Content-Transfer-Encoding: 7bit - C: - C: Our travel agent has sent the updated schedule. - C: - C: Cheers, - C: Bob - C: --------------030308070208000400050907 - C: URL "/Drafts;UIDVALIDITY=385759045/;UID=20/;Section=2.MIME" - URL "/Drafts;UIDVALIDITY=385759045/;UID=20/;Section=2" TEXT {44} - S: + Ready for literal data - C: - C: --------------030308070208000400050907-- - C: ) - S: A003 OK [APPENDUID 385759045 45] append Completed - C: A004 UID STORE 20 +FLAGS.SILENT (\Deleted) - S: A004 OK STORE completed - - - - - - - - - -Resnick Standards Track [Page 8] - -RFC 4469 IMAP CATENATE Extension April 2006 - - - Example 3: The following example demonstrates how the CATENATE - extension can be used to strip attachments. Below, a PowerPoint - attachment was replaced by a small text part explaining that the - attachment was stripped. - - C: A003 APPEND Drafts (\Seen \Draft $MDNSent) CATENATE - (URL "/Drafts;UIDVALIDITY=385759045/;UID=21/;section=HEADER" - TEXT {42} - S: + Ready for literal data - C: - C: --------------030308070208000400050903 - C: URL "/Drafts;UIDVALIDITY=385759045/;UID=21/;section=1.MIME" - URL "/Drafts;UIDVALIDITY=385759045/;UID=21/;section=1" TEXT {255} - S: + Ready for literal data - C: - C: --------------030308070208000400050903 - C: Content-type: text/plain; charset="us-ascii" - C: Content-transfer-encoding: 7bit - C: - C: This body part contained a Power Point presentation that was - C: deleted upon your request. - C: --------------030308070208000400050903-- - C: ) - S: A003 OK append Completed - - - - - - - - - - - - - - - - - - - - - - - - - - - -Resnick Standards Track [Page 9] - -RFC 4469 IMAP CATENATE Extension April 2006 - - - Example 4: The following example demonstrates a failed APPEND - command. The server returns the BADURL response code to indicate - that one of the provided URLs is invalid. This example also - demonstrates how the CATENATE extension can be used to construct a - digest of several messages. - - C: A003 APPEND Sent (\Seen $MDNSent) CATENATE (TEXT {541} - S: + Ready for literal data - C: Return-Path: <foo@example.org> - C: Received: from [127.0.0.2] - C: by rufus.example.org via TCP (internal) with ESMTPA; - C: Thu, 11 Nov 2004 16:57:07 +0000 - C: Message-ID: <419399E1.6000505@example.org> - C: Date: Thu, 21 Nov 2004 16:57:05 +0000 - C: From: Farren Oo <foo@example.org> - C: X-Accept-Language: en-us, en - C: MIME-Version: 1.0 - C: To: bar@example.org - C: Subject: Digest of the mailing list for today - C: Content-Type: multipart/digest; - C: boundary="------------030308070208000400050904" - C: - C: --------------030308070208000400050904 - C: URL "/INBOX;UIDVALIDITY=785799047/;UID=11467" TEXT {42} - S: + Ready for literal data - C: - C: --------------030308070208000400050904 - C: URL "/INBOX;UIDVALIDITY=785799047/;UID=113330/;section=1.5.9" - TEXT {42} - S: + Ready for literal data - C: - C: --------------030308070208000400050904 - C: URL "/INBOX;UIDVALIDITY=785799047/;UID=11916" TEXT {44} - S: + Ready for literal data - C: - C: --------------030308070208000400050904-- - C: ) - S: A003 NO [BADURL "/INBOX;UIDVALIDITY=785799047/;UID=113330; - section=1.5.9"] CATENATE append has failed, one message expunged - - Note that the server could have validated the URLs as they were - received and therefore could have returned the tagged NO response - with BADURL response-code in place of any continuation request after - the URL was received. - - - - - - - -Resnick Standards Track [Page 10] - -RFC 4469 IMAP CATENATE Extension April 2006 - - -9. Normative References - - [1] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1", - RFC 3501, March 2003. - - [2] Newman, C., "IMAP URL Scheme", RFC 2192, September 1997. - - [3] Crispin, M., "Internet Message Access Protocol (IMAP) - - MULTIAPPEND Extension", RFC 3502, March 2003. - - [4] Resnick, P., "Internet Message Format", RFC 2822, April 2001. - - [5] Freed, N. and N. Borenstein, "Multipurpose Internet Mail - Extensions (MIME) Part One: Format of Internet Message Bodies", - RFC 2045, November 1996. - - [6] Crispin, M., "Internet Message Access Protocol (IMAP) - UIDPLUS - extension", RFC 4315, December 2005. - - [7] Crocker, D. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", RFC 4234, October 2005. - - [8] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 ABNF", - RFC 4466, April 2006. - - - - - - - - - - - - - - - - - - - - - - - - - - - -Resnick Standards Track [Page 11] - -RFC 4469 IMAP CATENATE Extension April 2006 - - -Author's Address - - Peter W. Resnick - QUALCOMM Incorporated - 5775 Morehouse Drive - San Diego, CA 92121-1714 - US - - Phone: +1 858 651 4478 - EMail: presnick@qualcomm.com - URI: http://www.qualcomm.com/~presnick/ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Resnick Standards Track [Page 12] - -RFC 4469 IMAP CATENATE Extension April 2006 - - -Full Copyright Statement - - Copyright (C) The Internet Society (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 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 provided by the IETF - Administrative Support Activity (IASA). - - - - - - - -Resnick Standards Track [Page 13] - diff --git a/imap/docs/rfc/rfc4505.txt b/imap/docs/rfc/rfc4505.txt deleted file mode 100644 index 6b8a4a11..00000000 --- a/imap/docs/rfc/rfc4505.txt +++ /dev/null @@ -1,507 +0,0 @@ - - - - - - -Network Working Group K. Zeilenga, Ed. -Request for Comments: 4505 OpenLDAP Foundation -Obsoletes: 2245 June 2006 -Category: Standards Track - - - Anonymous Simple Authentication and Security Layer (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 (2006). - -Abstract - - On the Internet, it is common practice to permit anonymous access to - various services. Traditionally, this has been done with a plain- - text password mechanism using "anonymous" as the user name and using - optional trace information, such as an email address, as the - password. As plain-text login commands are not permitted in new IETF - protocols, a new way to provide anonymous login is needed within the - context of the Simple Authentication and Security Layer (SASL) - framework. - -1. Introduction - - This document defines an anonymous mechanism for the Simple - Authentication and Security Layer ([SASL]) framework. The name - associated with this mechanism is "ANONYMOUS". - - Unlike many other SASL mechanisms, whose purpose is to authenticate - and identify the user to a server, the purpose of this SASL mechanism - is to allow the user to gain access to services or resources without - requiring the user to establish or otherwise disclose their identity - to the server. That is, this mechanism provides an anonymous login - method. - - This mechanism does not provide a security layer. - - This document replaces RFC 2245. Changes since RFC 2245 are detailed - in Appendix A. - - - -Zeilenga Standards Track [Page 1] - -RFC 4505 Anonymous SASL Mechanism June 2006 - - -2. The Anonymous Mechanism - - The mechanism consists of a single message from the client to the - server. The client may include in this message trace information in - the form of a string of [UTF-8]-encoded [Unicode] characters prepared - in accordance with [StringPrep] and the "trace" stringprep profile - defined in Section 3 of this document. The trace information, which - has no semantical value, should take one of two forms: an Internet - email address, or an opaque string that does not contain the '@' - (U+0040) character and that can be interpreted by the system - administrator of the client's domain. For privacy reasons, an - Internet email address or other information identifying the user - should only be used with permission from the user. - - A server that permits anonymous access will announce support for the - ANONYMOUS mechanism and allow anyone to log in using that mechanism, - usually with restricted access. - - A formal grammar for the client message using Augmented BNF [ABNF] is - provided below as a tool for understanding this technical - specification. - - message = [ email / token ] - ;; to be prepared in accordance with Section 3 - - UTF1 = %x00-3F / %x41-7F ;; less '@' (U+0040) - UTF2 = %xC2-DF UTF0 - UTF3 = %xE0 %xA0-BF UTF0 / %xE1-EC 2(UTF0) / - %xED %x80-9F UTF0 / %xEE-EF 2(UTF0) - UTF4 = %xF0 %x90-BF 2(UTF0) / %xF1-F3 3(UTF0) / - %xF4 %x80-8F 2(UTF0) - UTF0 = %x80-BF - - TCHAR = UTF1 / UTF2 / UTF3 / UTF4 - ;; any UTF-8 encoded Unicode character - ;; except '@' (U+0040) - - email = addr-spec - ;; as defined in [IMAIL] - - token = 1*255TCHAR - - Note to implementors: - The <token> production is restricted to 255 UTF-8-encoded Unicode - characters. As the encoding of a characters uses a sequence of 1 - to 4 octets, a token may be as long as 1020 octets. - - - - - -Zeilenga Standards Track [Page 2] - -RFC 4505 Anonymous SASL Mechanism June 2006 - - -3. The "trace" Profile of "Stringprep" - - This section defines the "trace" profile of [StringPrep]. This - profile is designed for use with the SASL ANONYMOUS Mechanism. - Specifically, the client is to prepare the <message> production in - accordance with this profile. - - The character repertoire of this profile is Unicode 3.2 [Unicode]. - - No mapping is required by this profile. - - No Unicode normalization is required by this profile. - - The list of unassigned code points for this profile is that provided - in Appendix A of [StringPrep]. Unassigned code points are not - prohibited. - - Characters from the following tables of [StringPrep] are prohibited: - - - C.2.1 (ASCII control characters) - - C.2.2 (Non-ASCII control characters) - - C.3 (Private use characters) - - C.4 (Non-character code points) - - C.5 (Surrogate codes) - - C.6 (Inappropriate for plain text) - - C.8 (Change display properties are deprecated) - - C.9 (Tagging characters) - - No additional characters are prohibited. - - This profile requires bidirectional character checking per Section 6 - of [StringPrep]. - -4. Example - - Here is a sample ANONYMOUS login between an IMAP client and server. - In this example, "C:" and "S:" indicate lines sent by the client and - server, respectively. If such lines are wrapped without a new "C:" - or "S:" label, then the wrapping is for editorial clarity and is not - part of the command. - - Note that this example uses the IMAP profile [IMAP4] of SASL. The - base64 encoding of challenges and responses as well as the "+ " - preceding the responses are part of the IMAP4 profile, not part of - SASL itself. Additionally, protocols with SASL profiles permitting - an initial client response will be able to avoid the extra round trip - below (the server response with an empty "+ "). - - - - -Zeilenga Standards Track [Page 3] - -RFC 4505 Anonymous SASL Mechanism June 2006 - - - In this example, the trace information is "sirhc". - - S: * OK IMAP4 server ready - C: A001 CAPABILITY - S: * CAPABILITY IMAP4 IMAP4rev1 AUTH=DIGEST-MD5 AUTH=ANONYMOUS - S: A001 OK done - C: A002 AUTHENTICATE ANONYMOUS - S: + - C: c2lyaGM= - S: A003 OK Welcome, trace information has been logged. - -5. Security Considerations - - The ANONYMOUS mechanism grants access to services and/or resources by - anyone. For this reason, it should be disabled by default so that - the administrator can make an explicit decision to enable it. - - If the anonymous user has any write privileges, a denial-of-service - attack is possible by filling up all available space. This can be - prevented by disabling all write access by anonymous users. - - If anonymous users have read and write access to the same area, the - server can be used as a communication mechanism to exchange - information anonymously. Servers that accept anonymous submissions - should implement the common "drop box" model, which forbids anonymous - read access to the area where anonymous submissions are accepted. - - If the anonymous user can run many expensive operations (e.g., an - IMAP SEARCH BODY command), this could enable a denial-of-service - attack. Servers are encouraged to reduce the priority of anonymous - users or limit their resource usage. - - While servers may impose a limit on the number of anonymous users, - note that such limits enable denial-of-service attacks and should be - used with caution. - - The trace information is not authenticated, so it can be falsified. - This can be used as an attempt to get someone else in trouble for - access to questionable information. Administrators investigating - abuse need to realize that this trace information may be falsified. - - A client that uses the user's correct email address as trace - information without explicit permission may violate that user's - privacy. Anyone who accesses an anonymous archive on a sensitive - subject (e.g., sexual abuse) likely has strong privacy needs. - Clients should not send the email address without the explicit - permission of the user and should offer the option of supplying no - trace information, thus only exposing the source IP address and time. - - - -Zeilenga Standards Track [Page 4] - -RFC 4505 Anonymous SASL Mechanism June 2006 - - - Anonymous proxy servers could enhance this privacy but would have to - consider the resulting potential denial-of-service attacks. - - Anonymous connections are susceptible to man-in-the-middle attacks - that view or alter the data transferred. Clients and servers are - encouraged to support external data security services. - - Protocols that fail to require an explicit anonymous login are more - susceptible to break-ins given certain common implementation - techniques. Specifically, Unix servers that offer user login may - initially start up as root and switch to the appropriate user id - after an explicit login command. Normally, such servers refuse all - data access commands prior to explicit login and may enter a - restricted security environment (e.g., the Unix chroot(2) function) - for anonymous users. If anonymous access is not explicitly - requested, the entire data access machinery is exposed to external - security attacks without the chance for explicit protective measures. - Protocols that offer restricted data access should not allow - anonymous data access without an explicit login step. - - General [SASL] security considerations apply to this mechanism. - - [StringPrep] security considerations and [Unicode] security - considerations discussed in [StringPrep] apply to this mechanism. - [UTF-8] security considerations also apply. - -6. IANA Considerations - - The SASL Mechanism registry [IANA-SASL] entry for the ANONYMOUS - mechanism has been updated by the IANA to reflect that this document - now provides its technical specification. - - To: iana@iana.org - Subject: Updated Registration of SASL mechanism ANONYMOUS - - SASL mechanism name: ANONYMOUS - Security considerations: See RFC 4505. - Published specification (optional, recommended): RFC 4505 - Person & email address to contact for further information: - Kurt Zeilenga <Kurt@OpenLDAP.org> - Chris Newman <Chris.Newman@sun.com> - Intended usage: COMMON - Author/Change controller: IESG <iesg@ietf.org> - Note: Updates existing entry for ANONYMOUS - - - - - - - -Zeilenga Standards Track [Page 5] - -RFC 4505 Anonymous SASL Mechanism June 2006 - - - The [StringPrep] profile "trace", first defined in this RFC, has been - registered: - - To: iana@iana.org - Subject: Initial Registration of Stringprep "trace" profile - - Stringprep profile: trace - Published specification: RFC 4505 - Person & email address to contact for further information: - Kurt Zeilenga <kurt@openldap.org> - -7. Acknowledgement - - This document is a revision of RFC 2245 by Chris Newman. Portions of - the grammar defined in Section 1 were borrowed from RFC 3629 by - Francois Yergeau. - - This document is a product of the IETF SASL WG. - -8. Normative References - - [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", RFC 4234, October 2005. - - [IMAIL] Resnick, P., "Internet Message Format", RFC 2822, April - 2001. - - [SASL] Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple - Authentication and Security Layer (SASL)", RFC 4422, - June 2006. - - [StringPrep] Hoffman, P. and M. Blanchet, "Preparation of - Internationalized Strings ('stringprep')", RFC 3454, - December 2002. - - [Unicode] The Unicode Consortium, "The Unicode Standard, Version - 3.2.0" is defined by "The Unicode Standard, Version 3.0" - (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5), - as amended by the "Unicode Standard Annex #27: Unicode - 3.1" (http://www.unicode.org/reports/tr27/) and by the - "Unicode Standard Annex #28: Unicode 3.2" - (http://www.unicode.org/reports/tr28/). - - [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO - 10646", RFC 3629 (also STD 63), November 2003. - - - - - - -Zeilenga Standards Track [Page 6] - -RFC 4505 Anonymous SASL Mechanism June 2006 - - -9. Informative References - - [IMAP4] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION - 4rev1", RFC 3501, March 2003. - - [IANA-SASL] IANA, "SIMPLE AUTHENTICATION AND SECURITY LAYER (SASL) - MECHANISMS", <http://www.iana.org/assignments/sasl- - mechanisms>. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Zeilenga Standards Track [Page 7] - -RFC 4505 Anonymous SASL Mechanism June 2006 - - -Appendix A. Changes since RFC 2245 - - This appendix is non-normative. - - RFC 2245 allows the client to include optional trace information in - the form of a human readable string. RFC 2245 restricted this string - to US-ASCII. As the Internet is international, this document uses a - string restricted to UTF-8 encoded Unicode characters. A - "stringprep" profile is defined to precisely define which Unicode - characters are allowed in this string. While the string remains - restricted to 255 characters, the encoded length of each character - may now range from 1 to 4 octets. - - Additionally, a number of editorial changes were made. - -Editor's Address - - Kurt D. Zeilenga - OpenLDAP Foundation - - EMail: Kurt@OpenLDAP.org - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Zeilenga Standards Track [Page 8] - -RFC 4505 Anonymous SASL Mechanism June 2006 - - -Full Copyright Statement - - Copyright (C) The Internet Society (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 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 provided by the IETF - Administrative Support Activity (IASA). - - - - - - - -Zeilenga Standards Track [Page 9] - diff --git a/imap/docs/rfc/rfc4549.txt b/imap/docs/rfc/rfc4549.txt deleted file mode 100644 index 8430ee10..00000000 --- a/imap/docs/rfc/rfc4549.txt +++ /dev/null @@ -1,1963 +0,0 @@ - - - - - - -Network Working Group A. Melnikov, Ed. -Request for Comments: 4549 Isode Ltd. -Category: Informational June 2006 - - - Synchronization Operations for Disconnected IMAP4 Clients - -Status of This Memo - - This memo provides information for the Internet community. It does - not specify an Internet standard of any kind. Distribution of this - memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2006). - -Abstract - - This document attempts to address some of the issues involved in - building a disconnected IMAP4 client. In particular, it deals with - the issues of what might be called the "driver" portion of the - synchronization tool: the portion of the code responsible for issuing - the correct set of IMAP4 commands to synchronize the disconnected - client in the way that is most likely to make the human who uses the - disconnected client happy. - - This note describes different strategies that can be used by - disconnected clients and shows how to use IMAP protocol in order to - minimize the time of the synchronization process. - - This note also lists IMAP extensions that a server should implement - in order to provide better synchronization facilities to disconnected - clients. - - - - - - - - - - - - - - - - - -Melnikov Informational [Page 1] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - -Table of Contents - - 1. Introduction ....................................................3 - 1.1. Conventions Used in This Document ..........................3 - 2. Design Principles ...............................................3 - 3. Overall Picture of Synchronization ..............................4 - 4. Mailbox Synchronization Steps and Strategies ....................7 - 4.1. Checking UID Validity ......................................7 - 4.2. Synchronizing Local Changes with the Server ................8 - 4.2.1. Uploading Messages to the Mailbox ...................8 - 4.2.2. Optimizing "move" and "copy" Operations .............9 - 4.2.3. Replaying Local Flag Changes .......................14 - 4.2.4. Processing Mailbox Compression (EXPUNGE) Requests ..15 - 4.2.5. Closing a Mailbox ..................................17 - 4.3. Details of "Normal" Synchronization of a Single Mailbox ...18 - 4.3.1. Discovering New Messages and Changes to Old - Messages ...........................................18 - 4.3.2. Searching for "Interesting" Messages. ..............20 - 4.3.3. Populating Cache with "Interesting" Messages. ......21 - 4.3.4. User-Initiated Synchronization .....................22 - 4.4. Special Case: Descriptor-Only Synchronization .............22 - 4.5. Special Case: Fast New-Only Synchronization ...............23 - 4.6. Special Case: Blind FETCH .................................23 - 5. Implementation Considerations ..................................24 - 5.1. Error Recovery during Playback ............................26 - 5.2. Quality of Implementation Issues ..........................28 - 5.3. Optimizations .............................................28 - 6. IMAP Extensions That May Help ..................................30 - 6.1. CONDSTORE Extension .......................................30 - 7. Security Considerations ........................................33 - 8. References .....................................................33 - 8.1. Normative References ......................................33 - 8.2. Informative References ....................................34 - 9. Acknowledgements ...............................................34 - - - - - - - - - - - - - - - - - -Melnikov Informational [Page 2] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - -1. Introduction - - Several recommendations presented in this document are generally - applicable to all types of IMAP clients. However, this document - tries to concentrate on disconnected mail clients [IMAP-MODEL]. It - also suggests some IMAP extensions* that should be implemented by - IMAP servers in order to make the life of disconnected clients - easier. In particular, the [UIDPLUS] extension was specifically - designed to streamline certain disconnected operations, like - expunging, uploading, and copying messages (see Sections 4.2.1, - 4.2.2.1, and 4.2.4). - - Readers of this document are also strongly advised to read RFC 2683 - [RFC2683]. - - * Note that the functionality provided by the base IMAP protocol - [IMAP4] is sufficient to perform basic synchronization. - -1.1. Conventions Used in This Document - - In examples, "C:" and "S:" indicate lines sent by the client and - server, respectively. Long lines in examples are broken for - editorial clarity. - - 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]. - - Let's call an IMAP command idempotent if the result of executing the - command twice sequentially is the same as the result of executing the - command just once. - -2. Design Principles - - All mailbox state or content information stored on the disconnected - client should be viewed strictly as a cache of the state of the - server. The "master" state remains on the server, just as it would - with an interactive IMAP4 client. The one exception to this rule is - that information about the state of the disconnected client's cache - (the state includes flag changes while offline and during scheduled - message uploads) remains on the disconnected client: that is, the - IMAP4 server is not responsible for remembering the state of the - disconnected IMAP4 client. - - We assume that a disconnected client is a client that, for whatever - reason, wants to minimize the length of time that it is "on the - phone" to the IMAP4 server. Often this will be because the client is - using a dialup connection, possibly with very low bandwidth, but - - - -Melnikov Informational [Page 3] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - sometimes it might just be that the human is in a hurry to catch an - airplane, or some other event beyond our control. Whatever the - reason, we assume that we must make efficient use of the network - connection, both in the usual sense (not generating spurious traffic) - and in the sense that we would prefer not to have the connection - sitting idle while the client and/or the server is performing - strictly local computation or I/O. Another, perhaps simpler way of - stating this is that we assume that network connections are - "expensive". - - Practical experience with disconnected mail systems has shown that - there is no single synchronization strategy that is appropriate for - all cases. Different humans have different preferences, and the same - human's preference will vary depending both on external circumstance - (how much of a hurry the human is in today) and on the value that the - human places on the messages being transferred. The point here is - that there is no way that the synchronization program can guess - exactly what the human wants to do, so the human will have to provide - some guidance. - - Taken together, the preceding two principles lead to the conclusion - that the synchronization program must make its decisions based on - some kind of guidance provided by the human, by selecting the - appropriate options in the user interface or through some sort of - configuration file. Almost certainly, it should not pause for I/O - with the human in the middle of the synchronization process. The - human will almost certainly have several different configurations for - the synchronization program, for different circumstances. - - Since a disconnected client has no way of knowing what changes might - have occurred to the mailbox while it was disconnected, message - numbers are not useful to a disconnected client. All disconnected - client operations should be performed using UIDs, so that the client - can be sure that it and the server are talking about the same - messages during the synchronization process. - -3. Overall Picture of Synchronization - - The basic strategy for synchronization is outlined below. Note that - the real strategy may vary from one application to another or may - depend on a synchronization mode. - - a) Process any "actions" that were pending on the client that were - not associated with any mailbox. (In particular sending messages - composed offline with SMTP. This is not part of IMAP - synchronization, but it is mentioned here for completeness.) - - - - - -Melnikov Informational [Page 4] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - b) Fetch the current list of "interesting" mailboxes. (The - disconnected client should allow the user to skip this step - completely.) - - c) "Client-to-server synchronization": for each IMAP "action" that - was pending on the client, do the following: - - 1) If the action implies opening a new mailbox (any operation that - operates on messages), open the mailbox. Check its UID - validity value (see Section 4.1 for more details) returned in - the UIDVALIDITY response code. If the UIDVALIDITY value - returned by the server differs, the client MUST empty the local - cache of the mailbox and remove any pending "actions" that - refer to UIDs in that mailbox (and consider them failed). Note - that this doesn't affect actions performed on client-generated - fake UIDs (see Section 5). - - 2) Perform the action. If the action is to delete a mailbox - (DELETE), make sure that the mailbox is closed first (see also - Section 3.4.12 of [RFC2683]). - - d) "Server-to-client synchronization": for each mailbox that requires - synchronization, do the following: - - 1) Check the mailbox UIDVALIDITY (see Section 4.1 for more - details) with SELECT/EXAMINE/STATUS. - - If UIDVALIDITY value returned by the server differs, the client - MUST - - * empty the local cache of that mailbox; - * remove any pending "actions" that refer to UIDs in that - mailbox and consider them failed; and - * skip step 2-II. - - 2) Fetch the current "descriptors"; - - I) Discover new messages. - - II) Discover changes to old messages. - - 3) Fetch the bodies of any "interesting" messages that the client - doesn't already have. - - e) Close all open mailboxes not required for further operations (if - staying online) or disconnect all open connections (if going - offline). - - - - -Melnikov Informational [Page 5] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - Terms used: - - "Actions" are queued requests that were made by the human to the - client's Mail User Agent (MUA) software while the client was - disconnected. - - We define "descriptors" as a set of IMAP4 FETCH data items. - Conceptually, a message's descriptor is that set of information that - allows the synchronization program to decide what protocol actions - are necessary to bring the local cache to the desired state for this - message; since this decision is really up to the human, this - information probably includes at least a few header fields intended - for human consumption. Exactly what will constitute a descriptor - depends on the client implementation. At a minimum, the descriptor - contains the message's UID and FLAGS. Other likely candidates are - the RFC822.SIZE, RFC822.HEADER, BODYSTRUCTURE, or ENVELOPE data - items. - - Comments: - - 1) The list of actions should be ordered. For example, if the human - deletes message A1 in mailbox A, then expunges mailbox A, and then - deletes message A2 in mailbox A, the human will expect that - message A1 is gone and that message A2 is still present but is now - deleted. - - By processing all the actions before proceeding with - synchronization, we avoid having to compensate for the local MUA's - changes to the server's state. That is, once we have processed - all the pending actions, the steps that the client must take to - synchronize itself will be the same no matter where the changes to - the server's state originated. - - 2) Steps a and b can be performed in parallel. Alternatively, step a - can be performed after d. - - 3) On step b, the set of "interesting" mailboxes pretty much has to - be determined by the human. What mailboxes belong to this set may - vary between different IMAP4 sessions with the same server, - client, and human. An interesting mailbox can be a mailbox - returned by LSUB command (see Section 6.3.9 of [IMAP4]). The - special mailbox "INBOX" SHOULD be in the default set of mailboxes - that the client considers interesting. However, providing the - ability to ignore INBOX for a particular session or client may be - valuable for some mail filtering strategies. - - - - - - -Melnikov Informational [Page 6] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - 4) On step d-2-II, the client also finds out about changes to the - flags of messages that the client already has in its local cache, - and about messages in the local cache that no longer exist on the - server (i.e., messages that have been expunged). - - 5) "Interesting" messages are those messages that the synchronization - program thinks the human wants to have cached locally, based on - the configuration and the data retrieved in step b. - - 6) A disconnected IMAP client is a special case of an IMAP client, so - it MUST be able to handle any "unexpected" unsolicited responses, - like EXISTS and EXPUNGE, at any time. The disconnected client MAY - ignore EXPUNGE response during "client-to-server" synchronization - phase (step c). - - The rest of this discussion will focus primarily on the - synchronization issues for a single mailbox. - -4. Mailbox Synchronization Steps and Strategies - -4.1. Checking UID Validity - - The "UID validity" of a mailbox is a number returned in an - UIDVALIDITY response code in an OK untagged response at mailbox - selection time. The UID validity value changes between sessions when - UIDs fail to persist between sessions. - - Whenever the client selects a mailbox, the client must compare the - returned UID validity value with the value stored in the local cache. - If the UID validity values differ, the UIDs in the client's cache are - no longer valid. The client MUST then empty the local cache of that - mailbox and remove any pending "actions" that refer to UIDs in that - mailbox. The client MAY also issue a warning to the human. The - client MUST NOT cancel any scheduled uploads (i.e., APPENDs) for the - mailbox. - - Note that UIDVALIDITY is not only returned on a mailbox selection. - The COPYUID and APPENDUID response codes defined in the [UIDPLUS] - extension (see also 4.2.2) and the UIDVALIDITY STATUS response data - item also contain a UIDVALIDITY value for some other mailbox. The - client SHOULD behave as described in the previous paragraph (but it - should act on the other mailbox's cache), no matter how it obtained - the UIDVALIDITY value. - - - - - - - - -Melnikov Informational [Page 7] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - -4.2. Synchronizing Local Changes with the Server - -4.2.1. Uploading Messages to the Mailbox - - Two of the most common examples of operations resulting in message - uploads are: - - 1) Saving a draft message - - 2) Copying a message between remote mailboxes on two different IMAP - servers or a local mailbox and a remote mailbox. - - Message upload is performed with the APPEND command. A message - scheduled to be uploaded has no UID associated with it, as all UIDs - are assigned by the server. The APPEND command will effectively - associate a UID with the uploaded message that can be stored in the - local cache for future reference. However, [IMAP4] doesn't describe - a simple mechanism to discover the message UID by just performing the - APPEND command. In order to discover the UID, the client can do one - of the following: - - 1) Remove the uploaded message from cache. Then, use the mechanism - described in 4.3 to fetch the information about the uploaded - message as if it had been uploaded by some other client. - - 2) Try to fetch header information as described in 4.2.2 in order to - find a message that corresponds to the uploaded message. One - strategy for doing this is described in 4.2.2. - - Case 1 describes a not particularly smart client. - - C: A003 APPEND Drafts (\Seen $MDNSent) {310} - S: + Ready for literal data - C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) - C: From: Fred Foobar <foobar@blt.example.COM> - C: Subject: afternoon meeting - C: To: mooch@owatagu.siam.edu - C: Message-Id: <B27397-0100000@blt.example.COM> - C: MIME-Version: 1.0 - C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII - C: - C: Hello Joe, do you think we can meet at 3:30 tomorrow? - C: - S: A003 OK APPEND Completed - - Fortunately, there is a simpler way to discover the message UID in - the presence of the [UIDPLUS] extension: - - - - -Melnikov Informational [Page 8] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - C: A003 APPEND Drafts (\Seen $MDNSent) {310} - S: + Ready for literal data - C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) - C: From: Fred Foobar <foobar@blt.example.COM> - C: Subject: afternoon meeting - C: To: mooch@owatagu.siam.edu - C: Message-Id: <B27397-0100000@blt.example.COM> - C: MIME-Version: 1.0 - C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII - C: - C: Hello Joe, do you think we can meet at 3:30 tomorrow? - C: - S: A003 OK [APPENDUID 1022843275 77712] APPEND completed - - The UID of the appended message is the second parameter of APPENDUID - response code. - -4.2.2. Optimizing "move" and "copy" Operations - - Practical experience with IMAP and other mailbox access protocols - that support multiple mailboxes suggests that moving a message from - one mailbox to another is an extremely common operation. - -4.2.2.1. Moving a Message between Two Mailboxes on the Same Server - - In IMAP4, a "move" operation between two mailboxes on the same server - is really a combination of a COPY operation and a STORE +FLAGS - (\Deleted) operation. This makes good protocol sense for IMAP, but - it leaves a simple-minded disconnected client in the silly position - of deleting and possibly expunging its cached copy of a message, then - fetching an identical copy via the network. - - However, the presence of the UIDPLUS extension in the server can - help: - - C: A001 UID COPY 567,414 "Interesting Messages" - S: A001 OK [COPYUID 1022843275 414,567 5:6] Completed - - This tells the client that the message with UID 414 in the current - mailbox was successfully copied to the mailbox "Interesting Messages" - and was given the UID 5, and that the message with UID 567 was given - the UID 6. - - In the absence of UIDPLUS extension support in the server, the - following trick can be used. By including the Message-ID: header and - the INTERNALDATE data item as part of the descriptor, the client can - check the descriptor of a "new" message against messages that are - already in its cache and avoid fetching the extra copy. Of course, - - - -Melnikov Informational [Page 9] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - it's possible that the cost of checking to see if the message is - already in the local cache may exceed the cost of just fetching it, - so this technique should not be used blindly. If the MUA implements - a "move" command, it makes special provisions to use this technique - when it knows that a copy/delete sequence is the result of a "move" - command. - - Note that servers are not required (although they are strongly - encouraged with "SHOULD language") to preserve INTERNALDATE when - copying messages. - - Also note that since it's theoretically possible for this algorithm - to find the wrong message (given sufficiently malignant Message-ID - headers), implementers should provide a way to disable this - optimization, both permanently and on a message-by-message basis. - - Example 1: Copying a message in the absence of UIDPLUS extension. - - At some point in time the client has fetched the source message and - some information was cached: - - C: C021 UID FETCH <uids> (BODY.PEEK[] INTERNALDATE FLAGS) - ... - S: * 27 FETCH (UID 123 INTERNALDATE "31-May-2002 05:26:59 -0600" - FLAGS (\Draft $MDNSent) BODY[] {1036} - S: ... - S: Message-Id: <20040903110856.22a127cd@chardonnay> - S: ... - S: ...message body... - S: ) - ... - S: C021 OK fetch completed - - Later on, the client decides to copy the message: - - C: C035 UID COPY 123 "Interesting Messages" - S: C035 OK Completed - - As the server hasn't provided the COPYUID response code, the client - tries the optimization described above: - - C: C036 SELECT "Interesting Messages" - ... - C: C037 UID SEARCH ON 31-May-2002 HEADER - "Message-Id" "20040903110856.22a127cd@chardonnay" - S: SEARCH 12368 - S: C037 OK completed - - - - -Melnikov Informational [Page 10] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - Note that if the server has returned multiple UIDs in the SEARCH - response, the client MUST NOT use any of the returned UID. - -4.2.2.2. Moving a Message from a Remote Mailbox to a Local - - Moving a message from a remote mailbox to a local is done with FETCH - (that includes FLAGS and INTERNALDATE) followed by UID STORE <uid> - +FLAGS.SILENT (\Deleted): - - C: A003 UID FETCH 123 (BODY.PEEK[] INTERNALDATE FLAGS) - S: * 27 FETCH (UID 123 INTERNALDATE "31-May-2002 05:26:59 -0600" - FLAGS (\Seen $MDNSent) BODY[] - S: ...message body... - S: ) - S: A003 OK UID FETCH completed - C: A004 UID STORE <uid> +FLAGS.SILENT (\Deleted) - S: A004 STORE completed - - Note that there is no reason to fetch the message during - synchronization if it's already in the client's cache. Also, the - client SHOULD preserve delivery date in the local cache. - -4.2.2.3. Moving a Message from a Local Mailbox to a Remote - - Moving a message from a local mailbox to a remote is done with - APPEND: - - C: A003 APPEND Drafts (\Seen $MDNSent) "31-May-2002 05:26:59 -0600" - {310} - S: + Ready for literal data - C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) - C: From: Fred Foobar <foobar@blt.example.COM> - C: Subject: afternoon meeting - C: To: mooch@owatagu.siam.edu - C: Message-Id: <B27397-0100000@blt.example.COM> - C: MIME-Version: 1.0 - C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII - C: - C: Hello Joe, do you think we can meet at 3:30 tomorrow? - C: - S: A003 OK [APPENDUID 1022843275 77712] completed - - The client SHOULD specify the delivery date from the local cache in - the APPEND. - - If the [LITERAL+] extension is available, the client can save a - round-trip*: - - - - -Melnikov Informational [Page 11] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - C: A003 APPEND Drafts (\Seen $MDNSent) "31-May-2002 05:26:59 -0600" - {310+} - C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) - C: From: Fred Foobar <foobar@blt.example.COM> - C: Subject: afternoon meeting - C: To: mooch@owatagu.siam.edu - C: Message-Id: <B27397-0100000@blt.example.COM> - C: MIME-Version: 1.0 - C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII - C: - C: Hello Joe, do you think we can meet at 3:30 tomorrow? - C: - S: A003 OK [APPENDUID 1022843275 77712] completed - - * Note that there is a risk that the server will reject the message - due to its size. If this happens, the client will waste bandwidth - transferring the whole message. If the client wouldn't have used - the LITERAL+, this could have been avoided: - - C: A003 APPEND Drafts (\Seen $MDNSent) "31-May-2004 05:26:59 -0600" - {16777215} - S: A003 NO Sorry, message is too big - -4.2.2.4. Moving a Message between Two Mailboxes on Different Servers - - Moving a message between two mailbox on two different servers is a - combination of the operations described in 4.2.2.2 followed by the - operations described in 4.2.2.3. - -4.2.2.5. Uploading Multiple Messages to a Remote Mailbox with - MULTIAPPEND - - When there is a need to upload multiple messages to a remote mailbox - (e.g., as per 4.2.2.3), the presence of certain IMAP extensions may - significantly improve performance. One of them is [MULTIAPPEND]. - - For some mail stores, opening a mailbox for appending might be - expensive. [MULTIAPPEND] tells the server to open the mailbox once - (instead of opening and closing it "n" times per "n" messages to be - uploaded) and to keep it open while a group of messages is being - uploaded to the server. - - Also, if the server supports both [MULTIAPPEND] and [LITERAL+] - extensions, the entire upload is accomplished in a single - command/response round-trip. - - - - - - -Melnikov Informational [Page 12] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - Note: Client implementers should be aware that [MULTIAPPEND] performs - append of multiple messages atomically. This means, for example, if - there is not enough space to save "n"-th message (or the message has - invalid structure and is rejected by the server) after successful - upload of "n-1" messages, the whole upload operation fails, and no - message will be saved in the mailbox. Although this behavior might - be desirable in certain situations, it might not be what you want. - Otherwise, the client should use the regular APPEND command (Section - 4.2.2.3), possibly utilizing the [LITERAL+] extension. See also - Section 5.1 for discussions about error recovery. - - Note: MULTIAPPEND can be used together with the UIDPLUS extension in - a way similar to what was described in Section 4.2.1. [MULTIAPPEND] - extends the syntax of the APPENDUID response code to allow for - multiple message UIDs in the second parameter. - - Example 2: - - This example demonstrates the use of MULTIAPPEND together with - UIDPLUS (synchronization points where the client waits for - confirmations from the server are marked with "<--->"): - - C: A003 APPEND Jan-2002 (\Seen $MDNSent) "31-May-2002 05:26:59 -0600" - {310} - <---> - S: + Ready for literal data - C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) - C: From: Fred Foobar <foobar@blt.example.COM> - C: Subject: afternoon meeting - C: To: mooch@owatagu.siam.edu - C: Message-Id: <B27397-0100000@blt.example.COM> - C: MIME-Version: 1.0 - C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII - C: - C: Hello Joe, do you think we can meet at 3:30 tomorrow? - C: (\Seen) " 1-Jun-2002 22:43:04 -0800" {286} - <---> - S: + Ready for literal data - C: Date: Mon, 7 Feb 1994 22:43:04 -0800 (PST) - C: From: Joe Mooch <mooch@OWaTaGu.siam.EDU> - C: Subject: Re: afternoon meeting - C: To: foobar@blt.example.com - C: Message-Id: <a0434793874930@OWaTaGu.siam.EDU> - C: MIME-Version: 1.0 - C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII - C: - C: 3:30 is fine with me. - C: - - - -Melnikov Informational [Page 13] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - S: A003 OK [APPENDUID 1022843275 77712,77713] completed - - The upload takes 3 round-trips. - - Example 3: - - In this example, Example 2 was modified for the case when the server - supports MULTIAPPEND, LITERAL+, and UIDPLUS. The upload takes only 1 - round-trip. - - C: A003 APPEND Jan-2002 (\Seen $MDNSent) "31-May-2002 05:26:59 -0600" - {310+} - C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) - C: From: Fred Foobar <foobar@blt.example.COM> - C: Subject: afternoon meeting - C: To: mooch@owatagu.siam.edu - C: Message-Id: <B27397-0100000@blt.example.COM> - C: MIME-Version: 1.0 - C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII - C: - C: Hello Joe, do you think we can meet at 3:30 tomorrow? - C: (\Seen) " 1-Jun-2002 22:43:04 -0800" {286+} - C: Date: Mon, 7 Feb 1994 22:43:04 -0800 (PST) - C: From: Joe Mooch <mooch@OWaTaGu.siam.EDU> - C: Subject: Re: afternoon meeting - C: To: foobar@blt.example.com - C: Message-Id: <a0434793874930@OWaTaGu.siam.EDU> - C: MIME-Version: 1.0 - C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII - C: - C: 3:30 is fine with me. - C: - S: A003 OK [APPENDUID 1022843275 77712,77713] completed - -4.2.3. Replaying Local Flag Changes - - The disconnected client uses the STORE command to synchronize local - flag state with the server. The disconnected client SHOULD use - +FLAGS.SILENT or -FLAGS.SILENT in order to set or unset flags - modified by the user while offline. The FLAGS form MUST NOT be used, - as there is a risk that this will overwrite flags on the server that - have been changed by some other client. - - Example 4: - - For the message with UID 15, the disconnected client stores the - following flags \Seen and $Highest. The flags were modified on the - server by some other client: \Seen, \Answered, and $Highest. While - - - -Melnikov Informational [Page 14] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - offline, the user requested that the $Highest flags be removed and - that the \Deleted flag be added. The flag synchronization sequence - for the message should look like: - - C: A001 UID STORE 15 +FLAGS.SILENT (\Deleted) - S: A001 STORE completed - C: A002 UID STORE 15 -FLAGS.SILENT ($Highest) - S: A002 STORE completed - - If the disconnected client is able to store an additional binary - state information (or a piece of information that can take a value - from a predefined set of values) in the local cache of an IMAP - mailbox or in a local mailbox (e.g., message priority), and if the - server supports storing of arbitrary keywords, the client MUST use - keywords to store this state on the server. - - Example 5: - - Imagine a speculative mail client that can mark a message as one of - work-related ($Work), personal ($Personal), or spam ($Spam). In - order to mark a message as personal, the client issues: - - C: A001 UID STORE 15 +FLAGS.SILENT ($Personal) - S: A001 STORE completed - C: A002 UID STORE 15 -FLAGS.SILENT ($Work $Spam) - S: A002 STORE completed - - In order to mark the message as not work, not personal and not spam, - the client issues: - - C: A003 UID STORE 15 -FLAGS.SILENT ($Personal $Work $Spam) - S: A003 STORE completed - -4.2.4. Processing Mailbox Compression (EXPUNGE) Requests - - A naive disconnected client implementation that supports compressing - a mailbox while offline may decide to issue an EXPUNGE command to the - server in order to expunge messages marked \Deleted. The problem - with this command during synchronization is that it permanently - erases all messages with the \Deleted flag set, i.e., even those - messages that were marked as \Deleted on the server while the user - was offline. Doing this might result in an unpleasant surprise for - the user. - - Fortunately the [UIDPLUS] extension can help in this case as well. - The extension introduces UID EXPUNGE command, that, unlike EXPUNGE, - takes a UID set parameter, that lists UIDs of all messages that can - be expunged. When processing this command the server erases only - - - -Melnikov Informational [Page 15] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - messages with \Deleted flag listed in the UID list. Thus, messages - not listed in the UID set will not be expunged even if they have the - \Deleted flag set. - - Example 6: - - While the user was offline, 3 messages with UIDs 7, 27, and 65 were - marked \Deleted when the user requested to compress the open mailbox. - Another client marked a message \Deleted on the server (UID 34). - During synchronization, the disconnected client issues: - - C: A001 UID EXPUNGE 7,27,65 - S: * ... EXPUNGE - S: * ... EXPUNGE - S: * ... EXPUNGE - S: A001 UID EXPUNGE completed - - If another client issues UID SEARCH DELETED command (to find all - messages with the \Deleted flag) before and after the UID EXPUNGE, it - will get: - - Before: - - C: B001 UID SEARCH DELETED - S: * SEARCH 65 34 27 7 - S: B001 UID SEARCH completed - - After: - - C: B002 UID SEARCH DELETED - S: * SEARCH 34 - S: B002 UID SEARCH completed - - In the absence of the [UIDPLUS] extension, the following sequence of - commands can be used as an approximation. Note: It's possible for - another client to mark additional messages as deleted while this - sequence is being performed. In this case, these additional messages - will be expunged as well. - - 1) Find all messages marked \Deleted on the server. - - C: A001 UID SEARCH DELETED - S: * SEARCH 65 34 27 7 - S: A001 UID SEARCH completed - - 2) Find all messages that must not be erased (for the previous - example the list will consist of the message with UID 34). - - - - -Melnikov Informational [Page 16] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - 3) Temporarily remove \Deleted flag on all messages found in step 2. - - C: A002 UID STORE 34 -FLAGS.SILENT (\Deleted) - S: A002 UID STORE completed - - 4) Expunge the mailbox. - - C: A003 EXPUNGE - S: * 20 EXPUNGE - S: * 7 EXPUNGE - S: * 1 EXPUNGE - S: A003 EXPUNGE completed - - Here, the message with UID 7 has message number 1, with UID 27 has - message number 7, and with UID 65 has message number 20. - - 5) Restore \Deleted flag on all messages found when performing step - 2. - - C: A004 UID STORE 34 +FLAGS.SILENT (\Deleted) - S: A004 UID STORE completed - -4.2.5. Closing a Mailbox - - When the disconnected client has to close a mailbox, it should not - use the CLOSE command, because CLOSE does a silent EXPUNGE. (Section - 4.2.4 explains why EXPUNGE should not be used by a disconnected - client.) It is safe to use CLOSE only if the mailbox was opened with - EXAMINE. - - If the mailbox was opened with SELECT, the client can use one of the - following commands to implicitly close the mailbox and prevent the - silent expunge: - - 1) UNSELECT - This is a command described in [UNSELECT] that works as - CLOSE, but doesn't cause the silent EXPUNGE. This command is - supported by the server if it reports UNSELECT in its CAPABILITY - list. - - 2) SELECT <another_mailbox> - SELECT causes implicit CLOSE without - EXPUNGE. - - 3) If the client intends to issue LOGOUT after closing the mailbox, - it may just issue LOGOUT, because LOGOUT causes implicit CLOSE - without EXPUNGE as well. - - 4) SELECT <non_existing_mailbox> - If the client knows a mailbox that - doesn't exist or can't be selected, it MAY SELECT it. - - - -Melnikov Informational [Page 17] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - If the client opened the mailbox with SELECT and just wants to avoid - implicit EXPUNGE without closing the mailbox, it may also use the - following: - - 5) EXAMINE <mailbox> - Reselect the same mailbox in read-only mode. - -4.3. Details of "Normal" Synchronization of a Single Mailbox - - The most common form of synchronization is where the human trusts the - integrity of the client's copy of the state of a particular mailbox - and simply wants to bring the client's cache up to date so that it - accurately reflects the mailbox's current state on the server. - -4.3.1. Discovering New Messages and Changes to Old Messages - - Let <lastseenuid> represent the highest UID that the client knows - about in this mailbox. Since UIDs are allocated in strictly - ascending order, this is simply the UID of the last message in the - mailbox that the client knows about. Let <lastseenuid+1> represent - <lastseenuid>'s UID plus one. Let <descriptors> represent a list - consisting of all the FETCH data item items that the implementation - considers part of the descriptor; at a minimum this is just the FLAGS - data item, but it usually also includes BODYSTRUCTURE and - RFC822.SIZE. At this step, <descriptors> SHOULD NOT include RFC822. - - With no further information, the client can issue the following two - commands: - - tag1 UID FETCH <lastseenuid+1>:* <descriptors> - tag2 UID FETCH 1:<lastseenuid> FLAGS - - The first command will request some information about "new" messages - (i.e., messages received by the server since the last - synchronization). It will also allow the client to build a message - number to UID map (only for new messages). The second command allows - the client to - - 1) update cached flags for old messages; - - 2) find out which old messages got expunged; and - - 3) build a mapping between message numbers and UIDs (for old - messages). - - The order here is significant. We want the server to start returning - the list of new message descriptors as fast as it can, so that the - client can start issuing more FETCH commands, so we start out by - asking for the descriptors of all the messages we know the client - - - -Melnikov Informational [Page 18] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - cannot possibly have cached yet. The second command fetches the - information we need to determine what changes may have occurred to - messages that the client already has cached. Note that the former - command should only be issued if the UIDNEXT value cached by the - client differs from the one returned by the server. Once the client - has issued these two commands, there's nothing more the client can do - with this mailbox until the responses to the first command start - arriving. A clever synchronization program might use this time to - fetch its local cache state from disk or to start the process of - synchronizing another mailbox. - - The following is an example of the first FETCH: - - C: A011 UID fetch 131:* (FLAGS BODYSTRUCTURE INTERNALDATE - RFC822.SIZE) - - Note 1: The first FETCH may result in the server's sending a huge - volume of data. A smart disconnected client should use message - ranges (see also Section 3.2.1.2 of [RFC2683]), so that the user is - able to execute a different operation between fetching information - for a group of new messages. - - Example 7: - - Knowing the new UIDNEXT returned by the server on SELECT or EXAMINE - (<uidnext>), the client can split the UID range - <lastseenuid+1>:<uidnext> into groups, e.g., 100 messages. After - that, the client can issue: - - C: A011 UID fetch <lastseenuid+1>:<lastseenuid+100> - (FLAGS BODYSTRUCTURE INTERNALDATE RFC822.SIZE) - ... - C: A012 UID fetch <lastseenuid+101>:<lastseenuid+200> - (FLAGS BODYSTRUCTURE INTERNALDATE RFC822.SIZE) - ... - ... - C: A0FF UID fetch <lastseenuid+901>:<uidnext> - (FLAGS BODYSTRUCTURE INTERNALDATE RFC822.SIZE) - - Note that unless a SEARCH command is issued, it is impossible to - determine how many messages will fall into a subrange, as UIDs are - not necessarily contiguous. - - Note 2: The client SHOULD ignore any unsolicited EXPUNGE responses - received during the first FETCH command. EXPUNGE responses contain - message numbers that are useless to a client that doesn't have the - message-number-to-UID translation table. - - - - -Melnikov Informational [Page 19] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - The second FETCH command will result in zero or more untagged fetch - responses. Each response will have a corresponding UID FETCH data - item. All messages that didn't have a matching untagged FETCH - response MUST be removed from the local cache. - - For example, if the <lastseenuid> had a value 15000 and the local - cache contained 3 messages with the UIDs 12, 777, and 14999, - respectively, then after receiving the following responses from the - server, the client must remove the message with UID 14999 from its - local cache. - - S: * 1 FETCH (UID 12 FLAGS (\Seen)) - S: * 2 FETCH (UID 777 FLAGS (\Answered \Deleted)) - - Note 3: If the client is not interested in flag changes (i.e., the - client only wants to know which old messages are still on the - server), the second FETCH command can be substituted with: - - tag2 UID SEARCH UID 1:<lastseenuid> - - This command will generate less traffic. However, an implementor - should be aware that in order to build the mapping table from message - numbers to UIDs, the output of the SEARCH command MUST be sorted - first, because there is no requirement for a server to return UIDs in - SEARCH response in any particular order. - -4.3.2. Searching for "Interesting" Messages. - - This step is performed entirely on the client (from the information - received in the step described in 4.3.1), entirely on the server, or - on some combination of both. The decision on what is an - "interesting" message is up to the client software and the human. - One easy criterion that should probably be implemented in any client - is whether the message is "too big" for automatic retrieval, where - "too big" is a parameter defined in the client's configuration. - - Another commonly used criterion is the age of a message. For - example, the client may choose to download only messages received in - the last week (in this case, <date> would be today's date minus 7 - days): - - tag3 UID SEARCH UID <uidset> SINCE <date> - - Keep in mind that a date search disregards time and time zone. The - client can avoid doing this search if it specified INTERNALDATE in - <descriptors> on the step described in 4.3.1. If the client did, it - can perform the local search on its message cache. - - - - -Melnikov Informational [Page 20] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - At this step, the client also decides what kind of information about - a particular message to fetch from the server. In particular, even - for a message that is considered "too big", the client MAY choose to - fetch some part(s) of it. For example, if the message is a - multipart/mixed containing a text part and a MPEG attachment, there - is no reason for the client not to fetch the text part. The decision - of which part should or should not be fetched can be based on the - information received in the BODYSTRUCTURE FETCH response data item - (i.e., if BODYSTRUCTURE was included in <descriptors> on the step - described in 4.3.1). - -4.3.3. Populating Cache with "Interesting" Messages. - - Once the client has found out which messages are "interesting", it - can start issuing appropriate FETCH commands for "interesting" - messages or parts thereof. - - Note that fetching a message into the disconnected client's local - cache does NOT imply that the human has (or even will) read the - message. Thus, the synchronization program for a disconnected client - should always be careful to use the .PEEK variants of the FETCH data - items that implicitly set the \Seen flag. - - Once the last descriptor has arrived and the last FETCH command has - been issued, the client simply needs to process the incoming fetch - items and use them to update the local message cache. - - In order to avoid deadlock problems, the client must give processing - of received messages priority over issuing new FETCH commands during - this synchronization process. This may necessitate temporary local - queuing of FETCH requests that cannot be issued without causing a - deadlock. In order to achieve the best use of the "expensive" - network connection, the client will almost certainly need to pay - careful attention to any flow-control information that it can obtain - from the underlying transport connection (usually a TCP connection). - - Note: The requirement stated in the previous paragraph might result - in an unpleasant user experience, if followed blindly. For example, - the user might be unwilling to wait for the client to finish - synchronization before starting to process the user's requests. A - smart disconnected client should allow the user to perform requested - operations in between IMAP commands that are part of the - synchronization process. See also Note 1 in Section 4.3.1. - - - - - - - - -Melnikov Informational [Page 21] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - Example 8: - - After fetching a message BODYSTRUCTURE, the client discovers a - complex MIME message. Then, it decides to fetch MIME headers of the - nested MIME messages and some body parts. - - C: A011 UID fetch 11 (BODYSTRUCTURE) - S: ... - C: A012 UID fetch 11 (BODY[HEADER] BODY[1.MIME] BODY[1.1.MIME] - BODY[1.2.MIME] BODY[2.MIME] BODY[3.MIME] BODY[4.MIME] - BODY[5.MIME] BODY[6.MIME] BODY[7.MIME] BODY[8.MIME] BODY[9.MIME] - BODY[10.MIME] BODY[11.MIME] BODY[12.MIME] BODY[13.MIME] - BODY[14.MIME] BODY[15.MIME] BODY[16.MIME] BODY[17.MIME] - BODY[18.MIME] BODY[19.MIME] BODY[20.MIME] BODY[21.MIME]) - S: ... - C: A013 UID fetch 11 (BODY[1.1] BODY[1.2]) - S: ... - C: A014 UID fetch 11 (BODY[3] BODY[4] BODY[5] BODY[6] BODY[7] BODY[8] - BODY[9] BODY[10] BODY[11] BODY[13] BODY[14] BODY[15] BODY[16] - BODY[21]) - S: ... - -4.3.4. User-Initiated Synchronization - - After the client has finished the main synchronization process as - described in Sections 4.3.1-4.3.3, the user may optionally request - additional synchronization steps while the client is still online. - This is not any different from the process described in Sections - 4.3.2 and 4.3.3. - - Typical examples are: - - 1) fetch all messages selected in UI. - 2) fetch all messages marked as \Flagged on the server. - -4.4. Special Case: Descriptor-Only Synchronization - - For some mailboxes, fetching the descriptors might be the entire - synchronization step. Practical experience with IMAP has shown that - a certain class of mailboxes (e.g., "archival" mailboxes) are used - primarily for long-term storage of important messages that the human - wants to have instantly available on demand but does not want - cluttering up the disconnected client's cache at any other time. - Messages in this kind of mailbox would be fetched exclusively by - explicit actions queued by the local MUA. Thus, the only - synchronization desirable on this kind of mailbox is fetching enough - descriptor information for the user to be able to identify messages - for subsequent download. - - - -Melnikov Informational [Page 22] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - Special mailboxes that receive messages from a high volume, low - priority mailing list might also be in this category, at least when - the human is in a hurry. - -4.5. Special Case: Fast New-Only Synchronization - - In some cases, the human might be in such a hurry that he or she - doesn't care about changes to old messages, just about new messages. - In this case, the client can skip the UID FETCH command that obtains - the flags and UIDs for old messages (1:<lastseenuid>). - -4.6. Special Case: Blind FETCH - - In some cases, the human may know (for whatever reason) that he or - she always wants to fetch any new messages in a particular mailbox, - unconditionally. In this case, the client can just fetch the - messages themselves, rather than just the descriptors, by using a - command like: - - tag1 UID FETCH <lastseenuid+1>:* (FLAGS BODY.PEEK[]) - - Note that this example ignores the fact that the messages can be - arbitrary long. The disconnected client MUST always check for - message size before downloading, unless explicitly told otherwise. A - well-behaved client should instead use something like the following: - - 1) Issue "tag1 UID FETCH <lastseenuid+1>:* (FLAGS RFC822.SIZE)". - - 2) From the message sizes returned in step 1, construct UID set - <required_messages>. - - 3) Issue "tag2 UID FETCH <required_messages> (BODY.PEEK[])". - - or - - 1) Issue "tag1 UID FETCH <lastseenuid+1>:* (FLAGS)". - - 2) Construct UID set <old_uids> from the responses of step 1. - - 3) Issue "tag2 SEARCH UID <old_uids> SMALLER <message_limit>". - Construct UID set <required_messages> from the result of the - SEARCH command. - - 4) Issue "tag3 UID FETCH <required_messages> (BODY.PEEK[])". - - - - - - - -Melnikov Informational [Page 23] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - or - - 1) Issue "tag1 UID FETCH <lastseenuid+1>:* (FLAGS - BODY.PEEK[]<0.<length>>)", where <length> should be replaced with - the maximal message size the client is willing to download. - - Note: In response to such a command, the server will only return - partial data if the message is longer than <length>. It will - return the full message data for any message whose size is smaller - than or equal to <length>. In the former case, the client will - not be able to extract the full MIME structure of the message from - the truncated data, so the client should include BODYSTRUCTURE in - the UID FETCH command as well. - -5. Implementation Considerations - - Below are listed some common implementation pitfalls that should be - considered when implementing a disconnected client. - - 1) Implementing fake UIDs on the client. - - A message scheduled to be uploaded has no UID, as UIDs are - selected by the server. The client may implement fake UIDs - internally in order to reference not-yet-uploaded messages in - further operations. (For example, a message could be scheduled to - be uploaded, but subsequently marked as deleted or copied to - another mailbox). Here, the client MUST NOT under any - circumstances send these fake UIDs to the server. Also, client - implementers should be reminded that according to [IMAP4] a UID is - a 32-bit unsigned integer excluding 0. So, both 4294967295 and - 2147483648 are valid UIDs, and 0 and -1 are both invalid. Some - disconnected mail clients have been known to send negative numbers - (e.g., "-1") as message UIDs to servers during synchronization. - - Situation 1: The user starts composing a new message, edits it, - saves it, continues to edit it, and saves it again. - - A disconnected client may record in its replay log (log of - operations to be replayed on the server during synchronization) - the sequence of operations as shown below. For the purpose of - this situation, we assume that all draft messages are stored in - the mailbox called Drafts on an IMAP server. We will also use the - following conventions: <old_uid> is the UID of the intermediate - version of the draft when it was saved for the first time. This - is a fake UID generated on the client. <new_uid> is the UID of - the final version of the draft. This is another fake UID - generated on the client. - - - - -Melnikov Informational [Page 24] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - 1) APPEND Drafts (\Seen $MDNSent \Drafts) {<nnn>} - ...first version of the message follows... - - 2) APPEND Drafts (\Seen $MDNSent \Drafts) {<mmm>} - ...final version of the message follows... - - 3) STORE <old_uid> +FLAGS (\Deleted) - - Step 1 corresponds to the first attempt to save the draft message, - step 2 corresponds to the second attempt to save the draft - message, and step 3 deletes the first version of the draft message - saved in step 1. - - A naive disconnected client may send the command in step 3 without - replacing the fake client generated <old_uid> with the value - returned by the server in step 1. A server will probably reject - this command, which will make the client believe that the - synchronization sequence has failed. - - 2) Section 5.1 discusses common implementation errors related to - error recovery during playback. - - 3) Don't assume that the disconnected client is the only client used - by the user. - - Situation 2: Some clients may use the \Deleted flag as an - indicator that the message should not appear in the user's view. - Usage of the \Deleted flag for this purpose is not safe, as other - clients (e.g., online clients) might EXPUNGE the mailbox at any - time. - - 4) Beware of data dependencies between synchronization operations. - - It might be very tempting for a client writer to perform some - optimizations on the playback log. Such optimizations might - include removing redundant operations (for example, see - optimization 2 in Section 5.3), or their reordering. - - It is not always safe to reorder or remove redundant operations - during synchronization because some operations may have - dependencies (as Situation 3 demonstrates). So, if in doubt, - don't do this. - - Situation 3: The user copies a message out of a mailbox and then - deletes the mailbox. - - - - - - -Melnikov Informational [Page 25] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - C: A001 SELECT Old-Mail - S: ... - C: A002 UID COPY 111 ToDo - S: A002 OK [COPYUID 1022843345 111 94] Copy completed - ... - C: A015 CLOSE - S: A015 OK Completed - C: A016 DELETE Old-Mail - S: A016 OK Mailbox deletion completed successfully - - If the client performs DELETE (tag A016) first and COPY (tag A002) - second, then the COPY fails. Also, the message that the user so - carefully copied into another mailbox has been lost. - -5.1. Error Recovery during Playback - - Error recovery during synchronization is one of the trickiest parts - to get right. Below, we will discuss certain error conditions and - suggest possible choices for handling them. - - 1) Lost connection to the server. - - The client MUST remember the current position in the playback - (replay) log and replay it starting from the interrupted operation - (the last command issued by the client, but not acknowledged by - the server) the next time it successfully connects to the same - server. If the connection was lost while executing a non- - idempotent IMAP command (see the definition in Section 1), then - when the client is reconnected, it MUST make sure that the - interrupted command was indeed not executed. If it wasn't - executed, the client must restart playback from the interrupted - command, otherwise from the following command. - - Upon reconnect, care must be taken in order to properly reapply - logical operations that are represented by multiple IMAP commands, - e.g., UID EXPUNGE emulation when UID EXPUNGE is not supported by - the server (see Section 4.2.4). - - Once the client detects that the connection to the server was - lost, it MUST stop replaying its log. There are existing - disconnected clients that, to the great annoyance of users, pop up - an error dialog for each and every playback operation that fails. - - 2) Copying/appending messages to a mailbox that doesn't exist. (The - server advertises this condition by sending the TRYCREATE response - code in the tagged NO response to the APPEND or COPY command.) - - - - - -Melnikov Informational [Page 26] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - The user should be advised about the situation and be given one of - the following choices: - - a) Try to recreate a mailbox. - b) Copy/upload messages to another mailbox. - c) Skip copy/upload. - d) Abort replay. - - 3) Copying messages from a mailbox that doesn't exist, or renaming or - getting/changing ACLs [ACL] on a mailbox that doesn't exist: - - a) Skip operation. - b) Abort replay. - - 4) Deleting mailboxes or deleting/expunging messages that no longer - exist. - - This is actually is not an error and should be ignored by the - client. - - 5) Performing operations on messages that no longer exist. - - a) Skip operation. - b) Abort replay. - - In the case of changing flags on an expunged message, the client - should silently ignore the error. - - Note 1: Several synchronization operations map to multiple IMAP - commands (for example, "move" described in 4.2.2). The client must - guarantee atomicity of each such multistep operation. For example, - when performing a "move" between two mailboxes on the same server, if - the server is unable to copy messages, the client MUST NOT attempt to - set the \Deleted flag on the messages being copied, let alone expunge - them. However, the client MAY consider that move operation to have - succeeded even if the server was unable to set the \Deleted flag on - copied messages. - - Note 2: Many synchronization operations have data dependencies. A - failed operation must cause all dependent operations to fail as well. - The client should check this and MUST NOT try to perform all - dependent operations blindly (unless the user corrected the original - problem). For example, a message may be scheduled to be appended to - a mailbox on the server and later on the appended message may be - copied to another mailbox. If the APPEND operation fails, the client - must not attempt to COPY the failed message later on. (See also - Section 5, Situation 3). - - - - -Melnikov Informational [Page 27] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - -5.2. Quality of Implementation Issues - - Below, some quality of implementation issues are listed for - disconnected clients. They will help to write a disconnected client - that works correctly, performs synchronization as quickly as possible - (and thus can make the user happier as well as save her some money), - and minimizes the server load: - - 1) Don't lose information. - - No matter how smart your client is in other areas, if it loses - information, users will get very upset. - - 2) Don't do work unless explicitly asked. Be flexible. Ask all - questions BEFORE starting synchronization, if possible. - - 3) Minimize traffic. - - The client MUST NOT issue a command if the client already received - the required information from the server. - - The client MUST make use of UIDPLUS extension if it is supported - by the server. - - See also optimization 1 in Section 5.3. - - 4) Minimize the number of round-trips. - - Round-trips kill performance, especially on links with high - latency. Sections 4.2.2.5 and 5.2 give some advice on how to - minimize the number of round-trips. - - See also optimization 1 in Section 5.3. - -5.3. Optimizations - - Some useful optimizations are described in this section. A - disconnected client that supports the recommendations listed below - will give the user a more pleasant experience. - - 1) The initial OK or PREAUTH responses may contain the CAPABILITY - response code as described in Section 7.1 of [IMAP4]. This - response code gives the same information as returned by the - CAPABILITY command*. A disconnected client that pays attention to - this response code can avoid sending CAPABILITY command and will - save a round-trip. - - - - - -Melnikov Informational [Page 28] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - * Note: Some servers report in the CAPABILITY response code - extensions that are only relevant in unauthenticated state or in - all states. Such servers usually send another CAPABILITY - response code upon successful authentication using LOGIN or - AUTHENTICATE command (that negotiates no security layer; see - Section 6.2.2 of [IMAP4]). The CAPABILITY response code sent - upon successful LOGIN/AUTHENTICATE might be different from the - CAPABILITY response code in the initial OK response, as - extensions only relevant for unauthenticated state will not be - advertised, and some additional extensions available only in - authenticated and/or selected state will be. - - Example 9: - - S: * OK [CAPABILITY IMAP4REV1 LOGIN-REFERRALS STARTTLS - AUTH=DIGEST-MD5 AUTH=SRP] imap.example.com ready - C: 2 authenticate DIGEST-MD5 - S: 2 OK [CAPABILITY IMAP4REV1 IDLE NAMESPACE MAILBOX-REFERRALS SCAN - SORT THREAD=REFERENCES THREAD=ORDEREDSUBJECT MULTIAPPEND] - User authenticated (no layer) - - 2) An advanced disconnected client may choose to optimize its replay - log. For example, there might be some operations that are - redundant (the list is not complete): - - a) an EXPUNGE followed by another EXPUNGE or CLOSE; - b) changing flags (other than the \Deleted flag) on a message that - gets immediately expunged; - c) opening and closing the same mailbox. - - When optimizing, be careful about data dependencies between commands. - For example, if the client is wishing to optimize (see case b, above) - - tag1 UID STORE <uid1> +FLAGS (\Deleted) - ... - tag2 UID STORE <uid1> +FLAGS (\Flagged) - ... - tag3 UID COPY <uid1> "Backup" - ... - tag4 UID EXPUNGE <uid1> - - it can't remove the second UID STORE command because the message is - being copied before it gets expunged. - - In general, it might be a good idea to keep mailboxes open during - synchronization (see case c above), if possible. This can be more - easily achieved in conjunction with optimization 3 described below. - - - - -Melnikov Informational [Page 29] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - 3) Perform some synchronization steps in parallel, if possible. - - Several synchronization steps don't depend on each other and thus - can be performed in parallel. Because the server machine is - usually more powerful than the client machine and can perform some - operations in parallel, this may speed up the total time of - synchronization. - - In order to achieve such parallelization, the client will have to - open more than one connection to the same server. Client writers - should not forget about non-trivial cost associated with - establishing a TCP connection and performing an authentication. - The disconnected client MUST NOT use one connection per mailbox. - In most cases, it is sufficient to have two connections. The - disconnected client SHOULD avoid selecting the same mailbox in - more than one connection; see Section 3.1.1 of [RFC2683] for more - details. - - Any mailbox synchronization MUST start with checking the - UIDVALIDITY as described in Section 4.1 of this document. The - client MAY use STATUS command to check UID Validity of a non- - selected mailbox. This is preferable to opening many connections - to the same server to perform synchronization of multiple - mailboxes simultaneously. As described in Section 5.3.10 of - [IMAP4], this SHOULD NOT be used on the selected mailbox. - -6. IMAP Extensions That May Help - - The following extensions can save traffic and/or the number of - round-trips: - - 1) The use of [UIDPLUS] is discussed in Sections 4.1, 4.2.1, 4.2.2.1 - and 4.2.4. - - 2) The use of the MULTIAPPEND and LITERAL+ extensions for uploading - messages is discussed in Section 4.2.2.5. - - 3) Use the CONDSTORE extension (see Section 6.1) for quick flag - resynchronization. - -6.1. CONDSTORE Extension - - An advanced disconnected mail client should use the [CONDSTORE] - extension when it is supported by the server. The client must cache - the value from HIGHESTMODSEQ OK response code received on mailbox - opening and update it whenever the server sends MODSEQ FETCH data - items. - - - - -Melnikov Informational [Page 30] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - If the client receives NOMODSEQ OK untagged response instead of - HIGHESTMODSEQ, it MUST remove the last known HIGHESTMODSEQ value from - its cache and follow the more general instructions in Section 3. - - When the client opens the mailbox for synchronization, it first - compares UIDVALIDITY as described in step d-1 in Section 3. If the - cached UIDVALIDITY value matches the one returned by the server, the - client MUST compare the cached value of HIGHESTMODSEQ with the one - returned by the server. If the cached HIGHESTMODSEQ value also - matches the one returned by the server, then the client MUST NOT - fetch flags for cached messages, as they hasn't changed. If the - value on the server is higher than the cached one, the client MAY use - "SEARCH MODSEQ <cached-value>" to find all messages with flags - changed since the last time the client was online and had the mailbox - opened. Alternatively, the client MAY use "FETCH 1:* (FLAGS) - (CHANGEDSINCE <cached-value>)". The latter operation combines - searching for changed messages and fetching new information. - - In all cases, the client still needs to fetch information about new - messages (if requested by the user) as well as discover which - messages have been expunged. - - Step d ("Server-to-client synchronization") in Section 4 in the - presence of the CONDSTORE extension 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 for more - details) with SELECT/EXAMINE/STATUS. - - 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; - * remove any pending "actions" that refer to UIDs in that - mailbox (note that this doesn't affect actions performed on - client-generated fake UIDs; see Section 5); and - * skip steps 1b and 2-II; - - 1b) Check the mailbox HIGHESTMODSEQ. If the cached value is the - same as the one returned by the server, skip fetching message - flags on step 2-II, i.e., the client only has to find out - which messages got expunged. - - - - - - -Melnikov Informational [Page 31] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - 2) Fetch the current "descriptors". - - I) Discover new messages. - - II) Discover changes to old messages and flags for new messages - using - "FETCH 1:* (FLAGS) (CHANGEDSINCE <cached-value>)" or - "SEARCH MODSEQ <cached-value>". - - Discover expunged messages; for example, using - "UID SEARCH 1:<lastseenuid>". (All messages not returned - in this command are expunged.) - - 3) Fetch the bodies of any "interesting" messages that the client - doesn't already have. - - Example 10: - - The UIDVALIDITY value is the same, but the HIGHESTMODSEQ value - has changed on the server while the client was offline. - - C: A142 SELECT INBOX - 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: A142 OK [READ-WRITE] SELECT completed - - After that, either: - - C: A143 UID FETCH 1:* (FLAGS) (CHANGEDSINCE 20010715194032001) - S: * 2 FETCH (UID 6 MODSEQ (20010715205008000) FLAGS (\Deleted)) - S: * 5 FETCH (UID 9 MODSEQ (20010715195517000) FLAGS ($NoJunk - $AutoJunk $MDNSent)) - ... - S: A143 OK FETCH completed - - or: - - - - - - - - - -Melnikov Informational [Page 32] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - - C: A143 UID SEARCH MODSEQ 20010715194032001 UID 1:20 - S: * SEARCH 6 9 11 12 18 19 20 23 (MODSEQ 20010917162500) - S: A143 OK Search complete - C: A144 UID SEARCH 1:20 - S: * SEARCH 6 9 ... - S: A144 OK FETCH completed - -7. Security Considerations - - It is believed that this document does not raise any new security - concerns that are not already present in the base [IMAP4] protocol, - and these issues are discussed in [IMAP4]. Additional security - considerations may be found in different extensions mentioned in this - document; in particular, in [UIDPLUS], [LITERAL+], [CONDSTORE], - [MULTIAPPEND], and [UNSELECT]. - - Implementers are also reminded about the importance of thorough - testing. - -8. References - -8.1. 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. - - [UIDPLUS] Crispin, M., "Internet Message Access Protocol (IMAP) - - UIDPLUS extension", RFC 4315, December 2005. - - [LITERAL+] Myers, J., "IMAP4 non-synchronizing literals", RFC - 2088, January 1997. - - [CONDSTORE] Melnikov, A. and S. Hole, "IMAP Extension for - Conditional STORE Operation or Quick Flag Changes - Resynchronization", RFC 4551, June 2006. - - [MULTIAPPEND] Crispin, M., "Internet Message Access Protocol (IMAP) - - MULTIAPPEND Extension", RFC 3502, March 2003. - - [UNSELECT] Melnikov, A., "Internet Message Access Protocol (IMAP) - UNSELECT command", RFC 3691, February 2004. - - [RFC2683] Leiba, B., "IMAP4 Implementation Recommendations", RFC - 2683, September 1999. - - - - -Melnikov Informational [Page 33] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - -8.2. Informative References - - [ACL] Melnikov, A., "IMAP4 Access Control List (ACL) - Extension", RFC 4314, December 2005. - - [IMAP-MODEL] Crispin, M., "Distributed Electronic Mail Models in - IMAP4", RFC 1733, December 1994. - -9. Acknowledgements - - This document is based on version 01 of the text written by Rob - Austein in November 1994. - - The editor appreciates comments posted by Mark Crispin to the IMAP - mailing list and the comments/corrections/ideas received from Grant - Baillie, Cyrus Daboo, John G. Myers, Chris Newman, and Timo Sirainen. - - The editor would also like to thank the developers of Netscape - Messenger and Mozilla mail clients for providing examples of - disconnected mail clients that served as a base for many - recommendations in this document. - -Editor's Address - - Alexey Melnikov - Isode Limited - 5 Castle Business Village - 36 Station Road - Hampton, Middlesex - TW12 2BX - United Kingdom - - Phone: +44 77 53759732 - EMail: alexey.melnikov@isode.com - - - - - - - - - - - - - - - - - -Melnikov Informational [Page 34] - -RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 - - -Full Copyright Statement - - Copyright (C) The Internet Society (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 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 provided by the IETF - Administrative Support Activity (IASA). - - - - - - - -Melnikov Informational [Page 35] - diff --git a/imap/docs/rfc/rfc4551.txt b/imap/docs/rfc/rfc4551.txt deleted file mode 100644 index 894b5109..00000000 --- a/imap/docs/rfc/rfc4551.txt +++ /dev/null @@ -1,1403 +0,0 @@ - - - - - - -Network Working Group A. Melnikov -Request for Comments: 4551 Isode Ltd. -Updates: 3501 S. Hole -Category: Standards Track ACI WorldWide/MessagingDirect - June 2006 - - - IMAP Extension for Conditional STORE Operation - or Quick Flag Changes 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. - -Copyright Notice - - Copyright (C) The Internet Society (2006). - -Abstract - - Often, multiple IMAP (RFC 3501) clients need to coordinate changes to - a common IMAP mailbox. Examples include different clients working on - behalf of the same user, and multiple users accessing shared - mailboxes. These clients need a mechanism to synchronize state - changes for messages within the mailbox. They must be able to - guarantee that only one client can change message state (e.g., - message flags) at any time. An example of such an application is use - of an IMAP mailbox as a message queue with multiple dequeueing - clients. - - The Conditional Store facility provides a protected update mechanism - for message state information that can detect and resolve conflicts - between multiple writing mail clients. - - The Conditional Store facility also allows a client to quickly - resynchronize mailbox flag changes. - - This document defines an extension to IMAP (RFC 3501). - - - - - - - - - -Melnikov & Hole Standards Track [Page 1] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - -Table of Contents - - 1. Introduction and Overview ................................. 3 - 2. Conventions Used in This Document ......................... 5 - 3. IMAP Protocol Changes ..................................... 6 - 3.1. New OK untagged responses for SELECT and EXAMINE ......... 6 - 3.1.1. HIGHESTMODSEQ response code ............................ 6 - 3.1.2. NOMODSEQ response code ................................. 7 - 3.2. STORE and UID STORE Commands ............................. 7 - 3.3 FETCH and UID FETCH Commands ..............................13 - 3.3.1. CHANGEDSINCE FETCH modifier ............................13 - 3.3.2. MODSEQ message data item in FETCH Command ..............14 - 3.4. MODSEQ search criterion in SEARCH ........................16 - 3.5. Modified SEARCH untagged response ........................17 - 3.6. HIGHESTMODSEQ status data items ..........................17 - 3.7. CONDSTORE parameter to SELECT and EXAMINE ................18 - 3.8. Additional quality of implementation issues ..............18 - 4. Formal Syntax .............................................19 - 5. Server implementation considerations ......................21 - 6. Security Considerations ...................................22 - 7. IANA Considerations .......................................22 - 8. References ................................................23 - 8.1. Normative References .....................................23 - 8.2. Informative References ...................................23 - 9. Acknowledgements ..........................................23 - - - - - - - - - - - - - - - - - - - - - - - - - - -Melnikov & Hole Standards Track [Page 2] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - -1. Introduction and Overview - - The Conditional STORE extension is present in any IMAP4 - implementation that returns "CONDSTORE" as one of the supported - capabilities in the CAPABILITY command response. - - An IMAP server that supports this extension MUST associate a positive - unsigned 64-bit value called a modification sequence (mod-sequence) - with every IMAP message. This is an opaque value updated by the - server whenever a metadata item is modified. The server MUST - guarantee that each STORE command performed on the same mailbox - (including simultaneous stores to different metadata items from - different connections) will get a different mod-sequence value. - Also, for any two successful STORE operations performed in the same - session on the same mailbox, the mod-sequence of the second completed - operation MUST be greater than the mod-sequence of the first - completed. Note that the latter rule disallows the use of the system - clock as a mod-sequence, because if system time changes (e.g., an NTP - [NTP] client adjusting the time), the next generated value might be - less than the previous one. - - Mod-sequences allow a client that supports the CONDSTORE extension to - determine if a message metadata has changed since some known moment. - Whenever the state of a flag changes (i.e., the flag is added where - previously it wasn't set, or the flag is removed and before it was - set) the value of the modification sequence for the message MUST be - updated. Adding the flag when it is already present or removing when - it is not present SHOULD NOT change the mod-sequence. - - When a message is appended to a mailbox (via the IMAP APPEND command, - COPY to the mailbox, or using an external mechanism) the server - generates a new modification sequence that is higher than the highest - modification sequence of all messages in the mailbox and assigns it - to the appended message. - - The server MAY store separate (per-message) modification sequence - values for different metadata items. If the server does so, per- - message mod-sequence is the highest mod-sequence of all metadata - items for the specified message. - - The server that supports this extension is not required to be able to - store mod-sequences for every available mailbox. Section 3.1.2 - describes how the server may act if a particular mailbox doesn't - support the persistent storage of mod-sequences. - - - - - - - -Melnikov & Hole Standards Track [Page 3] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - - This extension makes the following changes to the IMAP4 protocol: - - a) adds UNCHANGEDSINCE STORE modifier. - - b) adds the MODIFIED response code which should be used with an OK - response to the STORE command. (It can also be used in a NO - response.) - - c) adds a new MODSEQ message data item for use with the FETCH - command. - - d) adds CHANGEDSINCE FETCH modifier. - - e) adds a new MODSEQ search criterion. - - f) extends the syntax of untagged SEARCH responses to include - mod-sequence. - - g) adds new OK untagged responses for the SELECT and EXAMINE - commands. - - h) defines an additional parameter to SELECT/EXAMINE commands. - - i) adds the HIGHESTMODSEQ status data item to the STATUS command. - - A client supporting CONDSTORE extension indicates its willingness to - receive mod-sequence updates in all untagged FETCH responses by - issuing: - - - a SELECT or EXAMINE command with the CONDSTORE parameter, - - a STATUS (HIGHESTMODSEQ) command, - - a FETCH or SEARCH command that includes the MODSEQ message data - item, - - a FETCH command with the CHANGEDSINCE modifier, or - - a STORE command with the UNCHANGEDSINCE modifier. - - The server MUST include mod-sequence data in all subsequent untagged - FETCH responses (until the connection is closed), whether they were - caused by a regular STORE, a STORE with UNCHANGEDSINCE modifier, or - an external agent. - - This document uses the term "CONDSTORE-aware client" to refer to a - client that announces its willingness to receive mod-sequence updates - as described above. The term "CONDSTORE enabling command" will refer - any of the commands listed above. A future extension to this - document may extend the list of CONDSTORE enabling commands. A first - CONDSTORE enabling command executed in the session MUST cause the - - - - -Melnikov & Hole Standards Track [Page 4] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - - server to return HIGHESTMODSEQ (Section 3.1.1) unless the server has - sent NOMODSEQ (Section 3.1.2) response code when the currently - selected mailbox was selected. - - The rest of this document describes the protocol changes more - rigorously. - -2. Conventions Used in This Document - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - document are to be interpreted as described in RFC 2119 [KEYWORDS]. - - In examples, lines beginning with "S:" are sent by the IMAP server, - and lines beginning with "C:" are sent by the client. Line breaks - may appear in example commands solely for editorial clarity; when - present in the actual message, they are represented by "CRLF". - - Formal syntax is defined using ABNF [ABNF]. - - The term "metadata" or "metadata item" is used throughout this - document. It refers to any system or user-defined keyword. Future - documents may extend "metadata" to include other dynamic message - data. - - Some IMAP mailboxes are private, accessible only to the owning user. - Other mailboxes are not, either because the owner has set an Access - Control List [ACL] that permits access by other users, or because it - is a shared mailbox. Let's call a metadata item "shared" for the - mailbox if any changes to the metadata items are persistent and - visible to all other users accessing the mailbox. Otherwise, the - metadata item is called "private". Note that private metadata items - are still visible to all sessions accessing the mailbox as the same - user. Also note that different mailboxes may have different metadata - items as shared. - - See Section 1 for the definition of a "CONDSTORE-aware client" and a - "CONDSTORE enabling command". - - - - - - - - - - - - - -Melnikov & Hole Standards Track [Page 5] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - -3. IMAP Protocol Changes - -3.1. New OK Untagged Responses for SELECT and EXAMINE - - This document adds two new response codes, HIGHESTMODSEQ and - NOMODSEQ. One of those response codes MUST be returned in the OK - untagged response for a successful SELECT/EXAMINE command. - - When opening a mailbox, the server must check if the mailbox supports - the persistent storage of mod-sequences. If the mailbox supports the - persistent storage of mod-sequences and the mailbox open operation - succeeds, the server MUST send the OK untagged response including - HIGHESTMODSEQ response code. If the persistent storage for the - mailbox is not supported, the server MUST send the OK untagged - response including NOMODSEQ response code instead. - -3.1.1. HIGHESTMODSEQ Response Code - - This document adds a new response code that is returned in the OK - untagged response for the SELECT and EXAMINE commands. A server - supporting the persistent storage of mod-sequences for the mailbox - MUST send the OK untagged response including HIGHESTMODSEQ response - code with every successful SELECT or EXAMINE command: - - OK [HIGHESTMODSEQ <mod-sequence-value>] - - where <mod-sequence-value> is the highest mod-sequence value of - all messages in the mailbox. When the server changes UIDVALIDITY - for a mailbox, it doesn't have to keep the same HIGHESTMODSEQ for - the mailbox. - - A disconnected client can use the value of HIGHESTMODSEQ to check if - it has to refetch metadata from the server. If the UIDVALIDITY value - has changed for the selected mailbox, the client MUST delete the - cached value of HIGHESTMODSEQ. If UIDVALIDITY for the mailbox is the - same, and if the HIGHESTMODSEQ value stored in the client's cache is - less than the value returned by the server, then some metadata items - on the server have changed since the last synchronization, and the - client needs to update its cache. The client MAY use SEARCH MODSEQ - (Section 3.4) to find out exactly which metadata items have changed. - Alternatively, the client MAY issue FETCH with the CHANGEDSINCE - modifier (Section 3.3.1) in order to fetch data for all messages that - have metadata items changed since some known modification sequence. - - Example 1: - - C: A142 SELECT INBOX - S: * 172 EXISTS - - - -Melnikov & Hole Standards Track [Page 6] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - - S: * 1 RECENT - S: * OK [UNSEEN 12] Message 12 is first unseen - S: * OK [UIDVALIDITY 3857529045] UIDs valid - S: * OK [UIDNEXT 4392] Predicted next UID - S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) - S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited - S: * OK [HIGHESTMODSEQ 715194045007] - S: A142 OK [READ-WRITE] SELECT completed - -3.1.2. NOMODSEQ Response Code - - A server that doesn't support the persistent storage of mod-sequences - for the mailbox MUST send the OK untagged response including NOMODSEQ - response code with every successful SELECT or EXAMINE command. A - server that returned NOMODSEQ response code for a mailbox, which - subsequently receives one of the following commands while the mailbox - is selected: - - - a FETCH command with the CHANGEDSINCE modifier, - - a FETCH or SEARCH command that includes the MODSEQ message data - item, or - - a STORE command with the UNCHANGEDSINCE modifier - - MUST reject any such command with the tagged BAD response. - - Example 2: - - C: A142 SELECT INBOX - S: * 172 EXISTS - S: * 1 RECENT - S: * OK [UNSEEN 12] Message 12 is first unseen - S: * OK [UIDVALIDITY 3857529045] UIDs valid - S: * OK [UIDNEXT 4392] Predicted next UID - S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) - S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited - S: * OK [NOMODSEQ] Sorry, this mailbox format doesn't support - modsequences - S: A142 OK [READ-WRITE] SELECT completed - -3.2. STORE and UID STORE Commands - - This document defines the following STORE modifier (see Section 2.5 - of [IMAPABNF]): - - UNCHANGEDSINCE <mod-sequence> - - For each message specified in the message set, the server performs - the following. If the mod-sequence of any metadata item of the - - - -Melnikov & Hole Standards Track [Page 7] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - - message is equal or less than the specified UNCHANGEDSINCE value, - then the requested operation (as described by the message data - item) is performed. If the operation is successful, the server - MUST update the mod-sequence attribute of the message. An - untagged FETCH response MUST be sent, even if the .SILENT suffix - is specified, and the response MUST include the MODSEQ message - data item. This is required to update the client's cache with the - correct mod-sequence values. See Section 3.3.2 for more details. - - However, if the mod-sequence of any metadata item of the message - is greater than the specified UNCHANGEDSINCE value, then the - requested operation MUST NOT be performed. In this case, the - mod-sequence attribute of the message is not updated, and the - message number (or unique identifier in the case of the UID STORE - command) is added to the list of messages that failed the - UNCHANGESINCE test. - - When the server finished performing the operation on all the - messages in the message set, it checks for a non-empty list of - messages that failed the UNCHANGESINCE test. If this list is - non-empty, the server MUST return in the tagged response a - MODIFIED response code. The MODIFIED response code includes the - message set (for STORE) or set of UIDs (for UID STORE) of all - messages that failed the UNCHANGESINCE test. - - Example 3: - - All messages pass the UNCHANGESINCE test. - - C: a103 UID STORE 6,4,8 (UNCHANGEDSINCE 12121230045) - +FLAGS.SILENT (\Deleted) - S: * 1 FETCH (UID 4 MODSEQ (12121231000)) - S: * 2 FETCH (UID 6 MODSEQ (12121230852)) - S: * 4 FETCH (UID 8 MODSEQ (12121130956)) - S: a103 OK Conditional Store completed - - Example 4: - - C: a104 STORE * (UNCHANGEDSINCE 12121230045) +FLAGS.SILENT - (\Deleted $Processed) - S: * 50 FETCH (MODSEQ (12111230047)) - S: a104 OK Store (conditional) completed - - Example 5: - - C: c101 STORE 1 (UNCHANGEDSINCE 12121230045) -FLAGS.SILENT - (\Deleted) - S: * OK [HIGHESTMODSEQ 12111230047] - - - -Melnikov & Hole Standards Track [Page 8] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - - S: * 50 FETCH (MODSEQ (12111230048)) - S: c101 OK Store (conditional) completed - - HIGHESTMODSEQ response code was sent by the server presumably - because this was the first CONDSTORE enabling command. - - Example 6: - - In spite of the failure of the conditional STORE operation for - message 7, the server continues to process the conditional STORE - in order to find all messages that fail the test. - - C: d105 STORE 7,5,9 (UNCHANGEDSINCE 320162338) - +FLAGS.SILENT (\Deleted) - S: * 5 FETCH (MODSEQ (320162350)) - S: d105 OK [MODIFIED 7,9] Conditional STORE failed - - Example 7: - - Same as above, but the server follows the SHOULD recommendation in - Section 6.4.6 of [IMAP4]. - - C: d105 STORE 7,5,9 (UNCHANGEDSINCE 320162338) - +FLAGS.SILENT (\Deleted) - S: * 7 FETCH (MODSEQ (320162342) FLAGS (\Seen \Deleted)) - S: * 5 FETCH (MODSEQ (320162350)) - S: * 9 FETCH (MODSEQ (320162349) FLAGS (\Answered)) - S: d105 OK [MODIFIED 7,9] Conditional STORE failed - - Use of UNCHANGEDSINCE with a modification sequence of 0 always - fails if the metadata item exists. A system flag MUST always be - considered existent, whether it was set or not. - - Example 8: - - C: a102 STORE 12 (UNCHANGEDSINCE 0) - +FLAGS.SILENT ($MDNSent) - S: a102 OK [MODIFIED 12] Conditional STORE failed - - The client has tested the presence of the $MDNSent user-defined - keyword. - - Note: A client trying to make an atomic change to the state of a - particular metadata item (or a set of metadata items) should be - prepared to deal with the case when the server returns the MODIFIED - response code if the state of the metadata item being watched hasn't - changed (but the state of some other metadata item has). This is - necessary, because some servers don't store separate mod-sequences - - - -Melnikov & Hole Standards Track [Page 9] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - - for different metadata items. However, a server implementation - SHOULD avoid generating spurious MODIFIED responses for +FLAGS/-FLAGS - STORE operations, even when the server stores a single mod-sequence - per message. Section 5 describes how this can be achieved. - - Unless the server has included an unsolicited FETCH to update - client's knowledge about messages that have failed the UNCHANGEDSINCE - test, upon receipt of the MODIFIED response code, the client SHOULD - try to figure out if the required metadata items have indeed changed - by issuing FETCH or NOOP command. It is RECOMMENDED that the server - avoids the need for the client to do that by sending an unsolicited - FETCH response (Examples 9 and 10). - - If the required metadata items haven't changed, the client SHOULD - retry the command with the new mod-sequence. The client SHOULD allow - for a configurable but reasonable number of retries (at least 2). - - Example 9: - - In the example below, the server returns the MODIFIED response - code without sending information describing why the STORE - UNCHANGEDSINCE operation has failed. - - C: a106 STORE 100:150 (UNCHANGEDSINCE 212030000000) - +FLAGS.SILENT ($Processed) - S: * 100 FETCH (MODSEQ (303181230852)) - S: * 102 FETCH (MODSEQ (303181230852)) - ... - S: * 150 FETCH (MODSEQ (303181230852)) - S: a106 OK [MODIFIED 101] Conditional STORE failed - - The flag $Processed was set on the message 101... - - C: a107 NOOP - S: * 101 FETCH (MODSEQ (303011130956) FLAGS ($Processed)) - S: a107 OK - - Or the flag hasn't changed, but another has (note that this server - behaviour is discouraged. Server implementers should also see - Section 5)... - - C: b107 NOOP - S: * 101 FETCH (MODSEQ (303011130956) FLAGS (\Deleted \Answered)) - S: b107 OK - - ...and the client retries the operation for the message 101 with - the updated UNCHANGEDSINCE value - - - - -Melnikov & Hole Standards Track [Page 10] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - - C: b108 STORE 101 (UNCHANGEDSINCE 303011130956) - +FLAGS.SILENT ($Processed) - S: * 101 FETCH (MODSEQ (303181230852)) - S: b108 OK Conditional Store completed - - Example 10: - - Same as above, but the server avoids the need for the client to - poll for changes. - - The flag $Processed was set on the message 101 by another - client... - - C: a106 STORE 100:150 (UNCHANGEDSINCE 212030000000) - +FLAGS.SILENT ($Processed) - S: * 100 FETCH (MODSEQ (303181230852)) - S: * 101 FETCH (MODSEQ (303011130956) FLAGS ($Processed)) - S: * 102 FETCH (MODSEQ (303181230852)) - ... - S: * 150 FETCH (MODSEQ (303181230852)) - S: a106 OK [MODIFIED 101] Conditional STORE failed - - Or the flag hasn't changed, but another has (note that this server - behaviour is discouraged. Server implementers should also see - Section 5)... - - C: a106 STORE 100:150 (UNCHANGEDSINCE 212030000000) - +FLAGS.SILENT ($Processed) - S: * 100 FETCH (MODSEQ (303181230852)) - S: * 101 FETCH (MODSEQ (303011130956) FLAGS (\Deleted \Answered)) - S: * 102 FETCH (MODSEQ (303181230852)) - ... - S: * 150 FETCH (MODSEQ (303181230852)) - S: a106 OK [MODIFIED 101] Conditional STORE failed - - ...and the client retries the operation for the message 101 with - the updated UNCHANGEDSINCE value - - C: b108 STORE 101 (UNCHANGEDSINCE 303011130956) - +FLAGS.SILENT ($Processed) - S: * 101 FETCH (MODSEQ (303181230852)) - S: b108 OK Conditional Store completed - - Or the flag hasn't changed, but another has (nice server - behaviour. Server implementers should also see Section 5)... - - C: a106 STORE 100:150 (UNCHANGEDSINCE 212030000000) - +FLAGS.SILENT ($Processed) - - - -Melnikov & Hole Standards Track [Page 11] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - - S: * 100 FETCH (MODSEQ (303181230852)) - S: * 101 FETCH (MODSEQ (303011130956) FLAGS ($Processed \Deleted - \Answered)) - S: * 102 FETCH (MODSEQ (303181230852)) - ... - S: * 150 FETCH (MODSEQ (303181230852)) - S: a106 OK Conditional STORE completed - - Example 11: - - The following example is based on the example from the Section - 4.2.3 of [RFC-2180] and demonstrates that the MODIFIED response - code may be also returned in the tagged NO response. - - Client tries to conditionally STORE flags on a mixture of expunged - and non-expunged messages; one message fails the UNCHANGEDSINCE - test. - - C: B001 STORE 1:7 (UNCHANGEDSINCE 320172338) +FLAGS (\SEEN) - S: * 1 FETCH (MODSEQ (320172342) FLAGS (\SEEN)) - S: * 3 FETCH (MODSEQ (320172342) FLAGS (\SEEN)) - S: B001 NO [MODIFIED 2] Some of the messages no longer exist. - - C: B002 NOOP - S: * 4 EXPUNGE - S: * 4 EXPUNGE - S: * 4 EXPUNGE - S: * 4 EXPUNGE - S: * 2 FETCH (MODSEQ (320172340) FLAGS (\Deleted \Answered)) - S: B002 OK NOOP Completed. - - By receiving FETCH responses for messages 1 and 3, and EXPUNGE - responses that indicate that messages 4 through 7 have been - expunged, the client retries the operation only for the message 2. - The updated UNCHANGEDSINCE value is used. - - C: b003 STORE 2 (UNCHANGEDSINCE 320172340) +FLAGS (\Seen) - S: * 2 FETCH (MODSEQ (320180050)) - S: b003 OK Conditional Store completed - - Note: If a message is specified multiple times in the message set, - and the server doesn't internally eliminate duplicates from the - message set, it MUST NOT fail the conditional STORE operation for the - second (or subsequent) occurrence of the message if the operation - completed successfully for the first occurrence. For example, if the - client specifies: - - - - - -Melnikov & Hole Standards Track [Page 12] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - - e105 STORE 7,3:9 (UNCHANGEDSINCE 12121230045) - +FLAGS.SILENT (\Deleted) - - the server must not fail the operation for message 7 as part of - processing "3:9" if it succeeded when message 7 was processed the - first time. - - Once the client specified the UNCHANGEDSINCE modifier in a STORE - command, the server MUST include the MODSEQ fetch response data items - in all subsequent unsolicited FETCH responses. - - This document also changes the behaviour of the server when it has - performed a STORE or UID STORE command and the UNCHANGEDSINCE - modifier is not specified. If the operation is successful for a - message, the server MUST update the mod-sequence attribute of the - message. The server is REQUIRED to include the mod-sequence value - whenever it decides to send the unsolicited FETCH response to all - CONDSTORE-aware clients that have opened the mailbox containing the - message. - - Server implementers should also see Section 3.8 for additional - quality of implementation issues related to the STORE command. - -3.3. FETCH and UID FETCH Commands - -3.3.1. CHANGEDSINCE FETCH Modifier - - This document defines the following FETCH modifier (see Section 2.4 - of [IMAPABNF]): - - CHANGEDSINCE <mod-sequence> - - CHANGEDSINCE FETCH modifier allows to create a further subset of - the list of messages described by sequence set. The information - described by message data items is only returned for messages that - have mod-sequence bigger than <mod-sequence>. - - When CHANGEDSINCE FETCH modifier is specified, it implicitly adds - MODSEQ FETCH message data item (Section 3.3.2). - - Example 12: - - C: s100 UID FETCH 1:* (FLAGS) (CHANGEDSINCE 12345) - S: * 1 FETCH (UID 4 MODSEQ (65402) FLAGS (\Seen)) - S: * 2 FETCH (UID 6 MODSEQ (75403) FLAGS (\Deleted)) - S: * 4 FETCH (UID 8 MODSEQ (29738) FLAGS ($NoJunk $AutoJunk - $MDNSent)) - S: s100 OK FETCH completed - - - -Melnikov & Hole Standards Track [Page 13] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - -3.3.2. MODSEQ Message Data Item in FETCH Command - - This extension adds a MODSEQ message data item to the FETCH command. - The MODSEQ message data item allows clients to retrieve mod-sequence - values for a range of messages in the currently selected mailbox. - - Once the client specified the MODSEQ message data item in a FETCH - request, the server MUST include the MODSEQ fetch response data items - in all subsequent unsolicited FETCH responses. - - Syntax: MODSEQ - - The MODSEQ message data item causes the server to return MODSEQ - fetch response data items. - - Syntax: MODSEQ ( <permsg-modsequence> ) - - MODSEQ response data items contain per-message mod-sequences. - - The MODSEQ response data item is returned if the client issued - FETCH with MODSEQ message data item. It also allows the server to - notify the client about mod-sequence changes caused by conditional - STOREs (Section 3.2) and/or changes caused by external sources. - - Example 13: - - C: a FETCH 1:3 (MODSEQ) - S: * 1 FETCH (MODSEQ (624140003)) - S: * 2 FETCH (MODSEQ (624140007)) - S: * 3 FETCH (MODSEQ (624140005)) - S: a OK Fetch complete - - In this example, the client requests per-message mod-sequences for - a set of messages. - - When a flag for a message is modified in a different session, the - server sends an unsolicited FETCH response containing the mod- - sequence for the message. - - Example 14: - - (Session 1, authenticated as a user "alex"). The user adds a - shared flag \Deleted: - - C: A142 SELECT INBOX - ... - S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) - S: * OK [PERMANENTFLAGS (\Answered \Deleted \Seen \*)] Limited - - - -Melnikov & Hole Standards Track [Page 14] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - - ... - - C: A160 STORE 7 +FLAGS.SILENT (\Deleted) - S: * 7 FETCH (MODSEQ (2121231000)) - S: A160 OK Store completed - - (Session 2, also authenticated as the user "alex"). Any changes - to flags are always reported to all sessions authenticated as the - same user as in the session 1. - - C: C180 NOOP - S: * 7 FETCH (FLAGS (\Deleted \Answered) MODSEQ (12121231000)) - S: C180 OK Noop completed - - (Session 3, authenticated as a user "andrew"). As \Deleted is a - shared flag, changes in session 1 are also reported in session 3: - - C: D210 NOOP - S: * 7 FETCH (FLAGS (\Deleted \Answered) MODSEQ (12121231000)) - S: D210 OK Noop completed - - The user modifies a private flag \Seen in session 1... - - C: A240 STORE 7 +FLAGS.SILENT (\Seen) - S: * 7 FETCH (MODSEQ (12121231777)) - S: A240 OK Store completed - - ...which is only reported in session 2... - - C: C270 NOOP - S: * 7 FETCH (FLAGS (\Deleted \Answered \Seen) MODSEQ - (12121231777)) - S: C270 OK Noop completed - - ...but not in session 3. - - C: D300 NOOP - S: D300 OK Noop completed - - And finally, the user removes flags \Answered (shared) and \Seen - (private) in session 1. - - C: A330 STORE 7 -FLAGS.SILENT (\Answered \Seen) - S: * 7 FETCH (MODSEQ (12121245160)) - S: A330 OK Store completed - - - - - - -Melnikov & Hole Standards Track [Page 15] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - - Both changes are reported in the session 2... - - C: C360 NOOP - S: * 7 FETCH (FLAGS (\Deleted) MODSEQ (12121245160)) - S: C360 OK Noop completed - - ...and only changes to shared flags are reported in session 3. - - C: D390 NOOP - S: * 7 FETCH (FLAGS (\Deleted) MODSEQ (12121245160)) - S: D390 OK Noop completed - - Server implementers should also see Section 3.8 for additional - quality of implementation issues related to the FETCH command. - -3.4. MODSEQ Search Criterion in SEARCH - - The MODSEQ criterion for the SEARCH command allows a client to search - for the metadata items that were modified since a specified moment. - - Syntax: MODSEQ [<entry-name> <entry-type-req>] <mod-sequence-valzer> - - Messages that have modification values that are equal to or - greater than <mod-sequence-valzer>. This allows a client, for - example, to find out which messages contain metadata items that - have changed since the last time it updated its disconnected - cache. The client may also specify <entry-name> (name of metadata - item) and <entry-type-req> (type of metadata item) before - <mod-sequence-valzer>. <entry-type-req> can be one of "shared", - "priv" (private), or "all". The latter means that the server - should use the biggest value among "priv" and "shared" mod- - sequences for the metadata item. If the server doesn't store - internally separate mod-sequences for different metadata items, it - MUST ignore <entry-name> and <entry-type-req>. Otherwise, the - server should use them to narrow down the search. - - For a flag <flagname>, the corresponding <entry-name> has a form - "/flags/<flagname>" as defined in [IMAPABNF]. Note that the - leading "\" character that denotes a system flag has to be escaped - as per Section 4.3 of [IMAP4], as the <entry-name> uses syntax for - quoted strings. - - If client specifies a MODSEQ criterion in a SEARCH command and the - server returns a non-empty SEARCH result, the server MUST also append - (to the end of the untagged SEARCH response) the highest mod-sequence - for all messages being returned. See also Section 3.5. - - - - - -Melnikov & Hole Standards Track [Page 16] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - - Example 15: - - C: a SEARCH MODSEQ "/flags/\\draft" all 620162338 - S: * SEARCH 2 5 6 7 11 12 18 19 20 23 (MODSEQ 917162500) - S: a OK Search complete - - In the above example, the message numbers of any messages - containing the string "IMAP4" in the "value" attribute of the - "/comment" entry and having a mod-sequence equal to or greater - than 620162338 for the "\Draft" flag are returned in the search - results. - - Example 16: - - C: t SEARCH OR NOT MODSEQ 720162338 LARGER 50000 - S: * SEARCH - S: t OK Search complete, nothing found - -3.5. Modified SEARCH Untagged Response - - Data: zero or more numbers - mod-sequence value (omitted if no match) - - This document extends syntax of the untagged SEARCH response to - include the highest mod-sequence for all messages being returned. - - If a client specifies a MODSEQ criterion in a SEARCH (or UID SEARCH) - command and the server returns a non-empty SEARCH result, the server - MUST also append (to the end of the untagged SEARCH response) the - highest mod-sequence for all messages being returned. See Section - 3.4 for examples. - -3.6. HIGHESTMODSEQ Status Data Items - - This document defines a new status data item: - - HIGHESTMODSEQ - - The highest mod-sequence value of all messages in the mailbox. - This is the same value that is returned by the server in the - HIGHESTMODSEQ response code in an OK untagged response (see - Section 3.1.1). If the server doesn't support the persistent - storage of mod-sequences for the mailbox (see Section 3.1.2), the - server MUST return 0 as the value of HIGHESTMODSEQ status data - item. - - - - - - -Melnikov & Hole Standards Track [Page 17] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - - Example 17: - - C: A042 STATUS blurdybloop (UIDNEXT MESSAGES HIGHESTMODSEQ) - S: * STATUS blurdybloop (MESSAGES 231 UIDNEXT 44292 - HIGHESTMODSEQ 7011231777) - S: A042 OK STATUS completed - -3.7. CONDSTORE Parameter to SELECT and EXAMINE - - The CONDSTORE extension defines a single optional select parameter, - "CONDSTORE", which tells the server that it MUST include the MODSEQ - fetch response data items in all subsequent unsolicited FETCH - responses. - - The CONDSTORE parameter to SELECT/EXAMINE helps avoid a race - condition that might arise when one or more metadata items are - modified in another session after the server has sent the - HIGHESTMODSEQ response code and before the client was able to issue a - CONDSTORE enabling command. - - Example 18: - - C: A142 SELECT INBOX (CONDSTORE) - S: * 172 EXISTS - S: * 1 RECENT - S: * OK [UNSEEN 12] Message 12 is first unseen - S: * OK [UIDVALIDITY 3857529045] UIDs valid - S: * OK [UIDNEXT 4392] Predicted next UID - S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) - S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited - S: * OK [HIGHESTMODSEQ 715194045007] - S: A142 OK [READ-WRITE] SELECT completed, CONDSTORE is now enabled - -3.8. Additional Quality-of-Implementation Issues - - Server implementations should follow the following rule, which - applies to any successfully completed STORE/UID STORE (with and - without UNCHANGEDSINCE modifier), as well as to a FETCH command that - implicitly sets \Seen flag: - - Adding the flag when it is already present or removing when it is - not present SHOULD NOT change the mod-sequence. - - This will prevent spurious client synchronization requests. - - - - - - - -Melnikov & Hole Standards Track [Page 18] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - - However, note that client implementers MUST NOT rely on this server - behavior. A client can't distinguish between the case when a server - has violated the SHOULD mentioned above, and that when one or more - clients set and unset (or unset and set) the flag in another session. - -4. Formal Syntax - - The following syntax specification uses the Augmented Backus-Naur - Form (ABNF) [ABNF] notation. Elements not defined here can be found - in the formal syntax of the ABNF [ABNF], IMAP [IMAP4], and IMAP ABNF - extensions [IMAPABNF] specifications. - - 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 =/ "CONDSTORE" - - status-att =/ "HIGHESTMODSEQ" - ;; extends non-terminal defined in RFC 3501. - - status-att-val =/ "HIGHESTMODSEQ" SP mod-sequence-valzer - ;; extends non-terminal defined in [IMAPABNF]. - ;; Value 0 denotes that the mailbox doesn't - ;; support persistent mod-sequences - ;; as described in Section 3.1.2 - - store-modifier =/ "UNCHANGEDSINCE" SP mod-sequence-valzer - ;; Only a single "UNCHANGEDSINCE" may be - ;; specified in a STORE operation - - fetch-modifier =/ chgsince-fetch-mod - ;; conforms to the generic "fetch-modifier" - ;; syntax defined in [IMAPABNF]. - - chgsince-fetch-mod = "CHANGEDSINCE" SP mod-sequence-value - ;; CHANGEDSINCE FETCH modifier conforms to - ;; the fetch-modifier syntax - - fetch-att =/ fetch-mod-sequence - ;; modifies original IMAP4 fetch-att - - fetch-mod-sequence = "MODSEQ" - - fetch-mod-resp = "MODSEQ" SP "(" permsg-modsequence ")" - - msg-att-dynamic =/ fetch-mod-resp - - - -Melnikov & Hole Standards Track [Page 19] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - - search-key =/ search-modsequence - ;; modifies original IMAP4 search-key - ;; - ;; This change applies to all commands - ;; referencing this non-terminal, in - ;; particular SEARCH. - - search-modsequence = "MODSEQ" [search-modseq-ext] SP - mod-sequence-valzer - - search-modseq-ext = SP entry-name SP entry-type-req - - resp-text-code =/ "HIGHESTMODSEQ" SP mod-sequence-value / - "NOMODSEQ" / - "MODIFIED" SP set - - entry-name = entry-flag-name - - entry-flag-name = DQUOTE "/flags/" attr-flag DQUOTE - ;; each system or user defined flag <flag> - ;; is mapped to "/flags/<flag>". - ;; - ;; <entry-flag-name> follows the escape rules - ;; used by "quoted" string as described in - ;; Section 4.3 of [IMAP4], e.g., for the flag - ;; \Seen the corresponding <entry-name> is - ;; "/flags/\\seen", and for the flag - ;; $MDNSent, the corresponding <entry-name> - ;; is "/flags/$mdnsent". - - entry-type-resp = "priv" / "shared" - ;; metadata item type - - entry-type-req = entry-type-resp / "all" - ;; perform SEARCH operation on private - ;; metadata item, shared metadata item or both - - permsg-modsequence = mod-sequence-value - ;; per message mod-sequence - - mod-sequence-value = 1*DIGIT - ;; Positive unsigned 64-bit integer - ;; (mod-sequence) - ;; (1 <= n < 18,446,744,073,709,551,615) - - mod-sequence-valzer = "0" / mod-sequence-value - - search-sort-mod-seq = "(" "MODSEQ" SP mod-sequence-value ")" - - - -Melnikov & Hole Standards Track [Page 20] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - - select-param =/ condstore-param - ;; conforms to the generic "select-param" - ;; non-terminal syntax defined in [IMAPABNF]. - - condstore-param = "CONDSTORE" - - mailbox-data =/ "SEARCH" [1*(SP nz-number) SP - search-sort-mod-seq] - - attr-flag = "\\Answered" / "\\Flagged" / "\\Deleted" / - "\\Seen" / "\\Draft" / attr-flag-keyword / - attr-flag-extension - ;; Does not include "\\Recent" - - attr-flag-extension = "\\" atom - ;; Future expansion. Client implementations - ;; MUST accept flag-extension flags. Server - ;; implementations MUST NOT generate - ;; flag-extension flags except as defined by - ;; future standard or standards-track - ;; revisions of [IMAP4]. - - attr-flag-keyword = atom - -5. Server Implementation Considerations - - This section describes how a server implementation that doesn't store - separate per-metadata mod-sequences for different metadata items can - avoid sending the MODIFIED response to any of the following - conditional STORE operations: - - +FLAGS - -FLAGS - +FLAGS.SILENT - -FLAGS.SILENT - - Note that the optimization described in this section can't be - performed in case of a conditional STORE FLAGS operation. - - Let's use the following example. The client has issued - - C: a106 STORE 100:150 (UNCHANGEDSINCE 212030000000) - +FLAGS.SILENT ($Processed) - - When the server receives the command and parses it successfully, it - iterates through the message set and tries to execute the conditional - STORE command for each message. - - - - -Melnikov & Hole Standards Track [Page 21] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - - Each server internally works as a client, i.e., it has to cache the - current state of all IMAP flags as it is known to the client. In - order to report flag changes to the client, the server compares the - cached values with the values in its database for IMAP flags. - - Imagine that another client has changed the state of a flag \Deleted - on the message 101 and that the change updated the mod-sequence for - the message. The server knows that the mod-sequence for the mailbox - has changed; however, it also knows that: - - a) the client is not interested in \Deleted flag, as it hasn't - included it in +FLAGS.SILENT operation; and - - b) the state of the flag $Processed hasn't changed (the server can - determine this by comparing cached flag state with the state of - the flag in the database). - - Therefore, the server doesn't have to report MODIFIED to the client. - Instead, the server may set $Processed flag, update the mod-sequence - for the message 101 once again and send an untagged FETCH response - with new mod-sequence and flags: - - S: * 101 FETCH (MODSEQ (303011130956) - FLAGS ($Processed \Deleted \Answered)) - - See also Section 3.8 for additional quality-of-implementation issues. - -6. Security Considerations - - It is believed that the Conditional STORE extension doesn't raise any - new security concerns that are not already discussed in [IMAP4]. - However, the availability of this extension may make it possible for - IMAP4 to be used in critical applications it could not be used for - previously, making correct IMAP server implementation and operation - even more important. - -7. 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 CONDSTORE IMAP capability. IANA has added - it to the registry accordingly. - - - - - -Melnikov & Hole Standards Track [Page 22] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - -8. References - -8.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. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", RFC 4234, October 2005. - - [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. - -8.2. Informative References - - [ACAP] Newman, C. and J. Myers, "ACAP -- Application - Configuration Access Protocol", RFC 2244, November 1997. - - [ACL] Melnikov, A., "IMAP4 Access Control List (ACL) Extension", - RFC 4314, December 2005. - - [ANN] Daboo, C. and R. Gellens, "IMAP ANNOTATE Extension", Work - in Progress, March 2006. - - [NTP] Mills, D., "Network Time Protocol (Version 3) - Specification, Implementation and Analysis", RFC 1305, - March 1992. - - [RFC-2180] Gahrns, M., "IMAP4 Multi-Accessed Mailbox Practice", RFC - 2180, July 1997. - -9. Acknowledgements - - Some text was borrowed from "IMAP ANNOTATE Extension" [ANN] by - Randall Gellens and Cyrus Daboo and from "ACAP -- Application - Configuration Access Protocol" [ACAP] by Chris Newman and John Myers. - - Many thanks to Randall Gellens for his thorough review of the - document. - - The authors also acknowledge the feedback provided by Cyrus Daboo, - Larry Greenfield, Chris Newman, Harrie Hazewinkel, Arnt Gulbrandsen, - Timo Sirainen, Mark Crispin, Ned Freed, Ken Murchison, and Dave - Cridland. - - - - -Melnikov & Hole Standards Track [Page 23] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - -Authors' Addresses - - Alexey Melnikov - Isode Limited - 5 Castle Business Village - 36 Station Road - Hampton, Middlesex - TW12 2BX, - United Kingdom - - EMail: Alexey.Melnikov@isode.com - - - Steve Hole - ACI WorldWide/MessagingDirect - #1807, 10088 102 Ave - Edmonton, AB - T5J 2Z1 - Canada - - EMail: Steve.Hole@messagingdirect.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Melnikov & Hole Standards Track [Page 24] - -RFC 4551 IMAP Extension for Conditional STORE June 2006 - - -Full Copyright Statement - - Copyright (C) The Internet Society (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 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 provided by the IETF - Administrative Support Activity (IASA). - - - - - - - -Melnikov & Hole Standards Track [Page 25] - diff --git a/imap/docs/rfc/rfc4616.txt b/imap/docs/rfc/rfc4616.txt deleted file mode 100644 index 991189d5..00000000 --- a/imap/docs/rfc/rfc4616.txt +++ /dev/null @@ -1,619 +0,0 @@ - - - - - - -Network Working Group K. Zeilenga, Ed. -Request for Comments: 4616 OpenLDAP Foundation -Updates: 2595 August 2006 -Category: Standards Track - - - The PLAIN Simple Authentication and Security Layer (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 (2006). - -Abstract - - This document defines a simple clear-text user/password Simple - Authentication and Security Layer (SASL) mechanism called the PLAIN - mechanism. The PLAIN mechanism is intended to be used, in - combination with data confidentiality services provided by a lower - layer, in protocols that lack a simple password authentication - command. - - - - - - - - - - - - - - - - - - - - - - - -Zeilenga Standards Track [Page 1] - -RFC 4616 The PLAIN SASL Mechanism August 2006 - - -1. Introduction - - Clear-text, multiple-use passwords are simple, interoperate with - almost all existing operating system authentication databases, and - are useful for a smooth transition to a more secure password-based - authentication mechanism. The drawback is that they are unacceptable - for use over network connections where data confidentiality is not - ensured. - - This document defines the PLAIN Simple Authentication and Security - Layer ([SASL]) mechanism for use in protocols with no clear-text - login command (e.g., [ACAP] or [SMTP-AUTH]). This document updates - RFC 2595, replacing Section 6. Changes since RFC 2595 are detailed - in Appendix A. - - The name associated with this mechanism is "PLAIN". - - The PLAIN SASL mechanism does not provide a security layer. - - The PLAIN mechanism should not be used without adequate data security - protection as this mechanism affords no integrity or confidentiality - protections itself. The mechanism is intended to be used with data - security protections provided by application-layer protocol, - generally through its use of Transport Layer Security ([TLS]) - services. - - By default, implementations SHOULD advertise and make use of the - PLAIN mechanism only when adequate data security services are in - place. Specifications for IETF protocols that indicate that this - mechanism is an applicable authentication mechanism MUST mandate that - implementations support an strong data security service, such as TLS. - - 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]. - -2. PLAIN SASL Mechanism - - The mechanism consists of a single message, a string of [UTF-8] - encoded [Unicode] characters, from the client to the server. The - client presents the authorization identity (identity to act as), - followed by a NUL (U+0000) character, followed by the authentication - identity (identity whose password will be used), followed by a NUL - (U+0000) character, followed by the clear-text password. As with - other SASL mechanisms, the client does not provide an authorization - identity when it wishes the server to derive an identity from the - credentials and use that as the authorization identity. - - - - -Zeilenga Standards Track [Page 2] - -RFC 4616 The PLAIN SASL Mechanism August 2006 - - - The formal grammar for the client message using Augmented BNF [ABNF] - follows. - - message = [authzid] UTF8NUL authcid UTF8NUL passwd - authcid = 1*SAFE ; MUST accept up to 255 octets - authzid = 1*SAFE ; MUST accept up to 255 octets - passwd = 1*SAFE ; MUST accept up to 255 octets - UTF8NUL = %x00 ; UTF-8 encoded NUL character - - SAFE = UTF1 / UTF2 / UTF3 / UTF4 - ;; any UTF-8 encoded Unicode character except NUL - - UTF1 = %x01-7F ;; except NUL - UTF2 = %xC2-DF UTF0 - UTF3 = %xE0 %xA0-BF UTF0 / %xE1-EC 2(UTF0) / - %xED %x80-9F UTF0 / %xEE-EF 2(UTF0) - UTF4 = %xF0 %x90-BF 2(UTF0) / %xF1-F3 3(UTF0) / - %xF4 %x80-8F 2(UTF0) - UTF0 = %x80-BF - - The authorization identity (authzid), authentication identity - (authcid), password (passwd), and NUL character deliminators SHALL be - transferred as [UTF-8] encoded strings of [Unicode] characters. As - the NUL (U+0000) character is used as a deliminator, the NUL (U+0000) - character MUST NOT appear in authzid, authcid, or passwd productions. - - The form of the authzid production is specific to the application- - level protocol's SASL profile [SASL]. The authcid and passwd - productions are form-free. Use of non-visible characters or - characters that a user may be unable to enter on some keyboards is - discouraged. - - Servers MUST be capable of accepting authzid, authcid, and passwd - productions up to and including 255 octets. It is noted that the - UTF-8 encoding of a Unicode character may be as long as 4 octets. - - Upon receipt of the message, the server will verify the presented (in - the message) authentication identity (authcid) and password (passwd) - with the system authentication database, and it will verify that the - authentication credentials permit the client to act as the (presented - or derived) authorization identity (authzid). If both steps succeed, - the user is authenticated. - - The presented authentication identity and password strings, as well - as the database authentication identity and password strings, are to - be prepared before being used in the verification process. The - [SASLPrep] profile of the [StringPrep] algorithm is the RECOMMENDED - preparation algorithm. The SASLprep preparation algorithm is - - - -Zeilenga Standards Track [Page 3] - -RFC 4616 The PLAIN SASL Mechanism August 2006 - - - recommended to improve the likelihood that comparisons behave in an - expected manner. The SASLprep preparation algorithm is not mandatory - so as to allow the server to employ other preparation algorithms - (including none) when appropriate. For instance, use of a different - preparation algorithm may be necessary for the server to interoperate - with an external system. - - When preparing the presented strings using [SASLPrep], the presented - strings are to be treated as "query" strings (Section 7 of - [StringPrep]) and hence unassigned code points are allowed to appear - in their prepared output. When preparing the database strings using - [SASLPrep], the database strings are to be treated as "stored" - strings (Section 7 of [StringPrep]) and hence unassigned code points - are prohibited from appearing in their prepared output. - - Regardless of the preparation algorithm used, if the output of a - non-invertible function (e.g., hash) of the expected string is - stored, the string MUST be prepared before input to that function. - - Regardless of the preparation algorithm used, if preparation fails or - results in an empty string, verification SHALL fail. - - When no authorization identity is provided, the server derives an - authorization identity from the prepared representation of the - provided authentication identity string. This ensures that the - derivation of different representations of the authentication - identity produces the same authorization identity. - - The server MAY use the credentials to initialize any new - authentication database, such as one suitable for [CRAM-MD5] or - [DIGEST-MD5]. - -3. Pseudo-Code - - This section provides pseudo-code illustrating the verification - process (using hashed passwords and the SASLprep preparation - function) discussed above. This section is not definitive. - - boolean Verify(string authzid, string authcid, string passwd) { - string pAuthcid = SASLprep(authcid, true); # prepare authcid - string pPasswd = SASLprep(passwd, true); # prepare passwd - if (pAuthcid == NULL || pPasswd == NULL) { - return false; # preparation failed - } - if (pAuthcid == "" || pPasswd == "") { - return false; # empty prepared string - } - - - - -Zeilenga Standards Track [Page 4] - -RFC 4616 The PLAIN SASL Mechanism August 2006 - - - storedHash = FetchPasswordHash(pAuthcid); - if (storedHash == NULL || storedHash == "") { - return false; # error or unknown authcid - } - - if (!Compare(storedHash, Hash(pPasswd))) { - return false; # incorrect password - } - - if (authzid == NULL ) { - authzid = DeriveAuthzid(pAuthcid); - if (authzid == NULL || authzid == "") { - return false; # could not derive authzid - } - } - - if (!Authorize(pAuthcid, authzid)) { - return false; # not authorized - } - - return true; - } - - The second parameter of the SASLprep function, when true, indicates - that unassigned code points are allowed in the input. When the - SASLprep function is called to prepare the password prior to - computing the stored hash, the second parameter would be false. - - The second parameter provided to the Authorize function is not - prepared by this code. The application-level SASL profile should be - consulted to determine what, if any, preparation is necessary. - - Note that the DeriveAuthzid and Authorize functions (whether - implemented as one function or two, whether designed in a manner in - which these functions or whether the mechanism implementation can be - reused elsewhere) require knowledge and understanding of mechanism - and the application-level protocol specification and/or - implementation details to implement. - - Note that the Authorize function outcome is clearly dependent on - details of the local authorization model and policy. Both functions - may be dependent on other factors as well. - - - - - - - - - -Zeilenga Standards Track [Page 5] - -RFC 4616 The PLAIN SASL Mechanism August 2006 - - -4. Examples - - This section provides examples of PLAIN authentication exchanges. - The examples are intended to help the readers understand the above - text. The examples are not definitive. - - "C:" and "S:" indicate lines sent by the client and server, - respectively. "<NUL>" represents a single NUL (U+0000) character. - The Application Configuration Access Protocol ([ACAP]) is used in the - examples. - - The first example shows how the PLAIN mechanism might be used for - user authentication. - - S: * ACAP (SASL "CRAM-MD5") (STARTTLS) - C: a001 STARTTLS - S: a001 OK "Begin TLS negotiation now" - <TLS negotiation, further commands are under TLS layer> - S: * ACAP (SASL "CRAM-MD5" "PLAIN") - C: a002 AUTHENTICATE "PLAIN" - S: + "" - C: {21} - C: <NUL>tim<NUL>tanstaaftanstaaf - S: a002 OK "Authenticated" - - The second example shows how the PLAIN mechanism might be used to - attempt to assume the identity of another user. In this example, the - server rejects the request. Also, this example makes use of the - protocol optional initial response capability to eliminate a round- - trip. - - S: * ACAP (SASL "CRAM-MD5") (STARTTLS) - C: a001 STARTTLS - S: a001 OK "Begin TLS negotiation now" - <TLS negotiation, further commands are under TLS layer> - S: * ACAP (SASL "CRAM-MD5" "PLAIN") - C: a002 AUTHENTICATE "PLAIN" {20+} - C: Ursel<NUL>Kurt<NUL>xipj3plmq - S: a002 NO "Not authorized to requested authorization identity" - -5. Security Considerations - - As the PLAIN mechanism itself provided no integrity or - confidentiality protections, it should not be used without adequate - external data security protection, such as TLS services provided by - many application-layer protocols. By default, implementations SHOULD - NOT advertise and SHOULD NOT make use of the PLAIN mechanism unless - adequate data security services are in place. - - - -Zeilenga Standards Track [Page 6] - -RFC 4616 The PLAIN SASL Mechanism August 2006 - - - When the PLAIN mechanism is used, the server gains the ability to - impersonate the user to all services with the same password - regardless of any encryption provided by TLS or other confidentiality - protection mechanisms. Whereas many other authentication mechanisms - have similar weaknesses, stronger SASL mechanisms address this issue. - Clients are encouraged to have an operational mode where all - mechanisms that are likely to reveal the user's password to the - server are disabled. - - General [SASL] security considerations apply to this mechanism. - - Unicode, [UTF-8], and [StringPrep] security considerations also - apply. - -6. IANA Considerations - - The SASL Mechanism registry [IANA-SASL] entry for the PLAIN mechanism - has been updated by the IANA to reflect that this document now - provides its technical specification. - - To: iana@iana.org - Subject: Updated Registration of SASL mechanism PLAIN - - SASL mechanism name: PLAIN - Security considerations: See RFC 4616. - Published specification (optional, recommended): RFC 4616 - Person & email address to contact for further information: - Kurt Zeilenga <kurt@openldap.org> - IETF SASL WG <ietf-sasl@imc.org> - Intended usage: COMMON - Author/Change controller: IESG <iesg@ietf.org> - Note: Updates existing entry for PLAIN - -7. Acknowledgements - - This document is a revision of RFC 2595 by Chris Newman. Portions of - the grammar defined in Section 2 were borrowed from [UTF-8] by - Francois Yergeau. - - This document is a product of the IETF Simple Authentication and - Security Layer (SASL) Working Group. - - - - - - - - - - -Zeilenga Standards Track [Page 7] - -RFC 4616 The PLAIN SASL Mechanism August 2006 - - -8. Normative References - - [ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for - Syntax Specifications: ABNF", RFC 4234, October 2005. - - [Keywords] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [SASL] Melnikov, A., Ed., and K. Zeilenga, Ed., "Simple - Authentication and Security Layer (SASL)", RFC 4422, - June 2006. - - [SASLPrep] Zeilenga, K., "SASLprep: Stringprep Profile for User - Names and Passwords", RFC 4013, February 2005. - - [StringPrep] Hoffman, P. and M. Blanchet, "Preparation of - Internationalized Strings ("stringprep")", RFC 3454, - December 2002. - - [Unicode] The Unicode Consortium, "The Unicode Standard, Version - 3.2.0" is defined by "The Unicode Standard, Version - 3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201- - 61633-5), as amended by the "Unicode Standard Annex - #27: Unicode 3.1" - (http://www.unicode.org/reports/tr27/) and by the - "Unicode Standard Annex #28: Unicode 3.2" - (http://www.unicode.org/reports/tr28/). - - [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO - 10646", STD 63, RFC 3629, November 2003. - - [TLS] Dierks, T. and E. Rescorla, "The Transport Layer - Security (TLS) Protocol Version 1.1", RFC 4346, April - 2006. - -9. Informative References - - [ACAP] Newman, C. and J. Myers, "ACAP -- Application - Configuration Access Protocol", RFC 2244, November - 1997. - - [CRAM-MD5] Nerenberg, L., Ed., "The CRAM-MD5 SASL Mechanism", Work - in Progress, June 2006. - - [DIGEST-MD5] Melnikov, A., Ed., "Using Digest Authentication as a - SASL Mechanism", Work in Progress, June 2006. - - - - - -Zeilenga Standards Track [Page 8] - -RFC 4616 The PLAIN SASL Mechanism August 2006 - - - [IANA-SASL] IANA, "SIMPLE AUTHENTICATION AND SECURITY LAYER (SASL) - MECHANISMS", - <http://www.iana.org/assignments/sasl-mechanisms>. - - [SMTP-AUTH] Myers, J., "SMTP Service Extension for Authentication", - RFC 2554, March 1999. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Zeilenga Standards Track [Page 9] - -RFC 4616 The PLAIN SASL Mechanism August 2006 - - -Appendix A. Changes since RFC 2595 - - This appendix is non-normative. - - This document replaces Section 6 of RFC 2595. - - The specification details how the server is to compare client- - provided character strings with stored character strings. - - The ABNF grammar was updated. In particular, the grammar now allows - LINE FEED (U+000A) and CARRIAGE RETURN (U+000D) characters in the - authzid, authcid, passwd productions. However, whether these control - characters may be used depends on the string preparation rules - applicable to the production. For passwd and authcid productions, - control characters are prohibited. For authzid, one must consult the - application-level SASL profile. This change allows PLAIN to carry - all possible authorization identity strings allowed in SASL. - - Pseudo-code was added. - - The example section was expanded to illustrate more features of the - PLAIN mechanism. - -Editor's Address - - Kurt D. Zeilenga - OpenLDAP Foundation - - EMail: Kurt@OpenLDAP.org - - - - - - - - - - - - - - - - - - - - - - -Zeilenga Standards Track [Page 10] - -RFC 4616 The PLAIN SASL Mechanism August 2006 - - -Full Copyright Statement - - Copyright (C) The Internet Society (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 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 provided by the IETF - Administrative Support Activity (IASA). - - - - - - - -Zeilenga Standards Track [Page 11] - diff --git a/imap/docs/rfc/rfc4731.txt b/imap/docs/rfc/rfc4731.txt deleted file mode 100644 index 8c4869aa..00000000 --- a/imap/docs/rfc/rfc4731.txt +++ /dev/null @@ -1,451 +0,0 @@ - - - - - - -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 <http://www.iana.org/assignments/imap4-capabilities>. - - 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/imap/docs/rfc/rfc4752.txt b/imap/docs/rfc/rfc4752.txt deleted file mode 100644 index bfd8e30b..00000000 --- a/imap/docs/rfc/rfc4752.txt +++ /dev/null @@ -1,563 +0,0 @@ - - - - - - -Network Working Group A. Melnikov, Ed. -Request for Comments: 4752 Isode -Obsoletes: 2222 November 2006 -Category: Standards Track - - - The Kerberos V5 ("GSSAPI") - Simple Authentication and Security Layer (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 IETF Trust (2006). - -Abstract - - The Simple Authentication and Security Layer (SASL) is a framework - for adding authentication support to connection-based protocols. - This document describes the method for using the Generic Security - Service Application Program Interface (GSS-API) Kerberos V5 in the - SASL. - - This document replaces Section 7.2 of RFC 2222, the definition of the - "GSSAPI" SASL mechanism. This document, together with RFC 4422, - obsoletes RFC 2222. - - - - - - - - - - - - - - - - - - - -Melnikov Standards Track [Page 1] - -RFC 4752 SASL GSSAPI Mechanism November 2006 - - -Table of Contents - - 1. Introduction ....................................................2 - 1.1. Relationship to Other Documents ............................2 - 2. Conventions Used in This Document ...............................2 - 3. Kerberos V5 GSS-API Mechanism ...................................2 - 3.1. Client Side of Authentication Protocol Exchange ............3 - 3.2. Server Side of Authentication Protocol Exchange ............4 - 3.3. Security Layer .............................................6 - 4. IANA Considerations .............................................7 - 5. Security Considerations .........................................7 - 6. Acknowledgements ................................................8 - 7. Changes since RFC 2222 ..........................................8 - 8. References ......................................................8 - 8.1. Normative References .......................................8 - 8.2. Informative References .....................................9 - -1. Introduction - - This specification documents currently deployed Simple Authentication - and Security Layer (SASL [SASL]) mechanism supporting the Kerberos V5 - [KERBEROS] Generic Security Service Application Program Interface - ([GSS-API]) mechanism [RFC4121]. The authentication sequence is - described in Section 3. Note that the described authentication - sequence has known limitations, in particular, it lacks channel - bindings and the number of round-trips required to complete - authentication exchange is not minimal. SASL WG is working on a - separate document that should address these limitations. - -1.1. Relationship to Other Documents - - This document, together with RFC 4422, obsoletes RFC 2222 in its - entirety. This document replaces Section 7.2 of RFC 2222. The - remainder is obsoleted as detailed in Section 1.2 of RFC 4422. - -2. Conventions Used in This Document - - The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" - in this document are to be interpreted as defined in "Key words for - use in RFCs to Indicate Requirement Levels" [KEYWORDS]. - -3. Kerberos V5 GSS-API Mechanism - - The SASL mechanism name for the Kerberos V5 GSS-API mechanism - [RFC4121] is "GSSAPI". Though known as the SASL GSSAPI mechanism, - the mechanism is specifically tied to Kerberos V5 and GSS-API's - Kerberos V5 mechanism. - - - - -Melnikov Standards Track [Page 2] - -RFC 4752 SASL GSSAPI Mechanism November 2006 - - - The GSSAPI SASL mechanism is a "client goes first" SASL mechanism; - i.e., it starts with the client sending a "response" created as - described in the following section. - - The implementation MAY set any GSS-API flags or arguments not - mentioned in this specification as is necessary for the - implementation to enforce its security policy. - - Note that major status codes returned by GSS_Init_sec_context() or - GSS_Accept_sec_context() other than GSS_S_COMPLETE or - GSS_S_CONTINUE_NEEDED cause authentication failure. Major status - codes returned by GSS_Unwrap() other than GSS_S_COMPLETE (without any - additional supplementary status codes) cause authentication and/or - security layer failure. - -3.1. Client Side of Authentication Protocol Exchange - - The client calls GSS_Init_sec_context, passing in - input_context_handle of 0 (initially), mech_type of the Kerberos V5 - GSS-API mechanism [KRB5GSS], chan_binding of NULL, and targ_name - equal to output_name from GSS_Import_Name called with input_name_type - of GSS_C_NT_HOSTBASED_SERVICE (*) and input_name_string of - "service@hostname" where "service" is the service name specified in - the protocol's profile, and "hostname" is the fully qualified host - name of the server. When calling the GSS_Init_sec_context, the - client MUST pass the integ_req_flag of TRUE (**). If the client will - be requesting a security layer, it MUST also supply to the - GSS_Init_sec_context a mutual_req_flag of TRUE, and a - sequence_req_flag of TRUE. If the client will be requesting a - security layer providing confidentiality protection, it MUST also - supply to the GSS_Init_sec_context a conf_req_flag of TRUE. The - client then responds with the resulting output_token. If - GSS_Init_sec_context returns GSS_S_CONTINUE_NEEDED, then the client - should expect the server to issue a token in a subsequent challenge. - The client must pass the token to another call to - GSS_Init_sec_context, repeating the actions in this paragraph. - - (*) Clients MAY use name types other than GSS_C_NT_HOSTBASED_SERVICE - to import servers' acceptor names, but only when they have a priori - knowledge that the servers support alternate name types. Otherwise - clients MUST use GSS_C_NT_HOSTBASED_SERVICE for importing acceptor - names. - - (**) Note that RFC 2222 [RFC2222] implementations will not work with - GSS-API implementations that require integ_req_flag to be true. No - implementations of RFC 1964 [KRB5GSS] or RFC 4121 [RFC4121] that - require integ_req_flag to be true are believed to exist and it is - expected that any future update to [RFC4121] will require that - - - -Melnikov Standards Track [Page 3] - -RFC 4752 SASL GSSAPI Mechanism November 2006 - - - integrity be available even in not explicitly requested by the - application. - - When GSS_Init_sec_context returns GSS_S_COMPLETE, the client examines - the context to ensure that it provides a level of protection - permitted by the client's security policy. In particular, if the - integ_avail flag is not set in the context, then no security layer - can be offered or accepted. - - If the conf_avail flag is not set in the context, then no security - layer with confidentiality can be offered or accepted. If the - context is acceptable, the client takes the following actions: If the - last call to GSS_Init_sec_context returned an output_token, then the - client responds with the output_token, otherwise the client responds - with no data. The client should then expect the server to issue a - token in a subsequent challenge. The client passes this token to - GSS_Unwrap and interprets the first octet of resulting cleartext as a - bit-mask specifying the security layers supported by the server and - the second through fourth octets as the maximum size output_message - the server is able to receive (in network byte order). If the - resulting cleartext is not 4 octets long, the client fails the - negotiation. The client verifies that the server maximum buffer is 0 - if the server does not advertise support for any security layer. - - The client then constructs data, with the first octet containing the - bit-mask specifying the selected security layer, the second through - fourth octets containing in network byte order the maximum size - output_message the client is able to receive (which MUST be 0 if the - client does not support any security layer), and the remaining octets - containing the UTF-8 [UTF8] encoded authorization identity. - (Implementation note: The authorization identity is not terminated - with the zero-valued (%x00) octet (e.g., the UTF-8 encoding of the - NUL (U+0000) character)). The client passes the data to GSS_Wrap - with conf_flag set to FALSE and responds with the generated - output_message. The client can then consider the server - authenticated. - -3.2. Server Side of Authentication Protocol Exchange - - A server MUST NOT advertise support for the "GSSAPI" SASL mechanism - described in this document unless it has acceptor credential for the - Kerberos V GSS-API mechanism [KRB5GSS]. - - The server passes the initial client response to - GSS_Accept_sec_context as input_token, setting input_context_handle - to 0 (initially), chan_binding of NULL, and a suitable - acceptor_cred_handle (see below). If GSS_Accept_sec_context returns - GSS_S_CONTINUE_NEEDED, the server returns the generated output_token - - - -Melnikov Standards Track [Page 4] - -RFC 4752 SASL GSSAPI Mechanism November 2006 - - - to the client in challenge and passes the resulting response to - another call to GSS_Accept_sec_context, repeating the actions in this - paragraph. - - Servers SHOULD use a credential obtained by calling GSS_Acquire_cred - or GSS_Add_cred for the GSS_C_NO_NAME desired_name and the Object - Identifier (OID) of the Kerberos V5 GSS-API mechanism [KRB5GSS](*). - Servers MAY use GSS_C_NO_CREDENTIAL as an acceptor credential handle. - Servers MAY use a credential obtained by calling GSS_Acquire_cred or - GSS_Add_cred for the server's principal name(s) (**) and the Kerberos - V5 GSS-API mechanism [KRB5GSS]. - - (*) Unlike GSS_Add_cred the GSS_Acquire_cred uses an OID set of GSS- - API mechanism as an input parameter. The OID set can be created by - using GSS_Create_empty_OID_set and GSS_Add_OID_set_member. It can be - freed by calling the GSS_Release_oid_set. - - - (**) Use of server's principal names having - GSS_C_NT_HOSTBASED_SERVICE name type and "service@hostname" format, - where "service" is the service name specified in the protocol's - profile, and "hostname" is the fully qualified host name of the - server, is RECOMMENDED. The server name is generated by calling - GSS_Import_name with input_name_type of GSS_C_NT_HOSTBASED_SERVICE - and input_name_string of "service@hostname". - - Upon successful establishment of the security context (i.e., - GSS_Accept_sec_context returns GSS_S_COMPLETE), the server SHOULD - verify that the negotiated GSS-API mechanism is indeed Kerberos V5 - [KRB5GSS]. This is done by examining the value of the mech_type - parameter returned from the GSS_Accept_sec_context call. If the - value differs, SASL authentication MUST be aborted. - - Upon successful establishment of the security context and if the - server used GSS_C_NO_NAME/GSS_C_NO_CREDENTIAL to create acceptor - credential handle, the server SHOULD also check using the - GSS_Inquire_context that the target_name used by the client matches - either - - - the GSS_C_NT_HOSTBASED_SERVICE "service@hostname" name syntax, - where "service" is the service name specified in the application - protocol's profile, - - or - - - the GSS_KRB5_NT_PRINCIPAL_NAME [KRB5GSS] name syntax for a two- - component principal where the first component matches the service - name specified in the application protocol's profile. - - - -Melnikov Standards Track [Page 5] - -RFC 4752 SASL GSSAPI Mechanism November 2006 - - - When GSS_Accept_sec_context returns GSS_S_COMPLETE, the server - examines the context to ensure that it provides a level of protection - permitted by the server's security policy. In particular, if the - integ_avail flag is not set in the context, then no security layer - can be offered or accepted. If the conf_avail flag is not set in the - context, then no security layer with confidentiality can be offered - or accepted. - - If the context is acceptable, the server takes the following actions: - If the last call to GSS_Accept_sec_context returned an output_token, - the server returns it to the client in a challenge and expects a - reply from the client with no data. Whether or not an output_token - was returned (and after receipt of any response from the client to - such an output_token), the server then constructs 4 octets of data, - with the first octet containing a bit-mask specifying the security - layers supported by the server and the second through fourth octets - containing in network byte order the maximum size output_token the - server is able to receive (which MUST be 0 if the server does not - support any security layer). The server must then pass the plaintext - to GSS_Wrap with conf_flag set to FALSE and issue the generated - output_message to the client in a challenge. - - The server must then pass the resulting response to GSS_Unwrap and - interpret the first octet of resulting cleartext as the bit-mask for - the selected security layer, the second through fourth octets as the - maximum size output_message the client is able to receive (in network - byte order), and the remaining octets as the authorization identity. - The server verifies that the client has selected a security layer - that was offered and that the client maximum buffer is 0 if no - security layer was chosen. The server must verify that the src_name - is authorized to act as the authorization identity. After these - verifications, the authentication process is complete. The server is - not expected to return any additional data with the success - indicator. - -3.3. Security Layer - - The security layers and their corresponding bit-masks are as follows: - - 1 No security layer - 2 Integrity protection. - Sender calls GSS_Wrap with conf_flag set to FALSE - 4 Confidentiality protection. - Sender calls GSS_Wrap with conf_flag set to TRUE - - Other bit-masks may be defined in the future; bits that are not - understood must be negotiated off. - - - - -Melnikov Standards Track [Page 6] - -RFC 4752 SASL GSSAPI Mechanism November 2006 - - - When decoding any received data with GSS_Unwrap, the major_status - other than the GSS_S_COMPLETE MUST be treated as a fatal error. - - Note that SASL negotiates the maximum size of the output_message to - send. Implementations can use the GSS_Wrap_size_limit call to - determine the corresponding maximum size input_message. - -4. IANA Considerations - - IANA modified the existing registration for "GSSAPI" as follows: - - Family of SASL mechanisms: NO - - SASL mechanism name: GSSAPI - - Security considerations: See Section 5 of RFC 4752 - - Published specification: RFC 4752 - - Person & email address to contact for further information: - Alexey Melnikov <Alexey.Melnikov@isode.com> - - Intended usage: COMMON - - Owner/Change controller: iesg@ietf.org - - Additional information: This mechanism is for the Kerberos V5 - mechanism of GSS-API. - -5. Security Considerations - - Security issues are discussed throughout this memo. - - When constructing the input_name_string, the client SHOULD NOT - canonicalize the server's fully qualified domain name using an - insecure or untrusted directory service. - - For compatibility with deployed software, this document requires that - the chan_binding (channel bindings) parameter to GSS_Init_sec_context - and GSS_Accept_sec_context be NULL, hence disallowing use of GSS-API - support for channel bindings. GSS-API channel bindings in SASL is - expected to be supported via a new GSS-API family of SASL mechanisms - (to be introduced in a future document). - - Additional security considerations are in the [SASL] and [GSS-API] - specifications. Additional security considerations for the GSS-API - mechanism can be found in [KRB5GSS] and [KERBEROS]. - - - - -Melnikov Standards Track [Page 7] - -RFC 4752 SASL GSSAPI Mechanism November 2006 - - -6. Acknowledgements - - This document replaces Section 7.2 of RFC 2222 [RFC2222] by John G. - Myers. He also contributed significantly to this revision. - - Lawrence Greenfield converted text of this document to the XML - format. - - Contributions of many members of the SASL mailing list are gratefully - acknowledged, in particular comments from Chris Newman, Nicolas - Williams, Jeffrey Hutzelman, Sam Hartman, Mark Crispin, and Martin - Rex. - -7. Changes since RFC 2222 - - RFC 2078 [RFC2078] specifies the version of GSS-API used by RFC 2222 - [RFC2222], which provided the original version of this specification. - That version of GSS-API did not provide the integ_integ_avail flag as - an input to GSS_Init_sec_context. Instead, integrity was always - requested. RFC 4422 [SASL] requires that when possible, the security - layer negotiation be integrity protected. To meet this requirement - and as part of moving from RFC 2078 [RFC2078] to RFC 2743 [GSS-API], - this specification requires that clients request integrity from - GSS_Init_sec_context so they can use GSS_Wrap to protect the security - layer negotiation. This specification does not require that the - mechanism offer the integrity security layer, simply that the - security layer negotiation be wrapped. - -8. References - -8.1. Normative References - - [GSS-API] Linn, J., "Generic Security Service Application Program - Interface Version 2, Update 1", RFC 2743, January 2000. - - [KERBEROS] Neuman, C., Yu, T., Hartman, S., and K. Raeburn, "The - Kerberos Network Authentication Service (V5)", RFC 4120, - July 2005. - - [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [KRB5GSS] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC - 1964, June 1996. - - - - - - - -Melnikov Standards Track [Page 8] - -RFC 4752 SASL GSSAPI Mechanism November 2006 - - - [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos - Version 5 Generic Security Service Application Program - Interface (GSS-API) Mechanism: Version 2", RFC 4121, July - 2005. - - [SASL] Melnikov, A. and K. Zeilenga, "Simple Authentication and - Security Layer (SASL)", RFC 4422, June 2006. - - [UTF8] Yergeau, F., "UTF-8, a transformation format of ISO - 10646", STD 63, RFC 3629, November 2003. - -8.2. Informative References - - [RFC2078] Linn, J., "Generic Security Service Application Program - Interface, Version 2", RFC 2078, January 1997. - - [RFC2222] Myers, J., "Simple Authentication and Security Layer - (SASL)", RFC 2222, October 1997. - -Editor's Address - - Alexey Melnikov - Isode Limited - 5 Castle Business Village - 36 Station Road - Hampton, Middlesex TW12 2BX - UK - - EMail: Alexey.Melnikov@isode.com - URI: http://www.melnikov.ca/ - - - - - - - - - - - - - - - - - - - - - -Melnikov Standards Track [Page 9] - -RFC 4752 SASL GSSAPI Mechanism 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 Standards Track [Page 10] - diff --git a/imap/docs/rfc/rfc4790.txt b/imap/docs/rfc/rfc4790.txt deleted file mode 100644 index d58191c0..00000000 --- a/imap/docs/rfc/rfc4790.txt +++ /dev/null @@ -1,1459 +0,0 @@ - - - - - - -Network Working Group C. Newman -Request for Comments: 4790 Sun Microsystems -Category: Standards Track M. Duerst - Aoyama Gakuin University - A. Gulbrandsen - Oryx - March 2007 - - - Internet Application Protocol Collation Registry - -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 (2007). - -Abstract - - Many Internet application protocols include string-based lookup, - searching, or sorting operations. However, the problem space for - searching and sorting international strings is large, not fully - explored, and is outside the area of expertise for the Internet - Engineering Task Force (IETF). Rather than attempt to solve such a - large problem, this specification creates an abstraction framework so - that application protocols can precisely identify a comparison - function, and the repertoire of comparison functions can be extended - in the future. - - - - - - - - - - - - - - - - - -Newman, et al. Standards Track [Page 1] - -RFC 4790 Collation Registry March 2007 - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 1.1. Conventions Used in This Document . . . . . . . . . . . . 4 - 2. Collation Definition and Purpose . . . . . . . . . . . . . . . 4 - 2.1. Definition . . . . . . . . . . . . . . . . . . . . . . . . 4 - 2.2. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 2.3. Some Other Terms Used in this Document . . . . . . . . . . 5 - 2.4. Sort Keys . . . . . . . . . . . . . . . . . . . . . . . . 5 - 3. Collation Identifier Syntax . . . . . . . . . . . . . . . . . 6 - 3.1. Basic Syntax . . . . . . . . . . . . . . . . . . . . . . . 6 - 3.2. Wildcards . . . . . . . . . . . . . . . . . . . . . . . . 6 - 3.3. Ordering Direction . . . . . . . . . . . . . . . . . . . . 7 - 3.4. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 - 3.5. Naming Guidelines . . . . . . . . . . . . . . . . . . . . 7 - 4. Collation Specification Requirements . . . . . . . . . . . . . 8 - 4.1. Collation/Server Interface . . . . . . . . . . . . . . . . 8 - 4.2. Operations Supported . . . . . . . . . . . . . . . . . . . 8 - 4.2.1. Validity . . . . . . . . . . . . . . . . . . . . . . . 9 - 4.2.2. Equality . . . . . . . . . . . . . . . . . . . . . . . 9 - 4.2.3. Substring . . . . . . . . . . . . . . . . . . . . . . 9 - 4.2.4. Ordering . . . . . . . . . . . . . . . . . . . . . . . 10 - 4.3. Sort Keys . . . . . . . . . . . . . . . . . . . . . . . . 10 - 4.4. Use of Lookup Tables . . . . . . . . . . . . . . . . . . . 11 - 5. Application Protocol Requirements . . . . . . . . . . . . . . 11 - 5.1. Character Encoding . . . . . . . . . . . . . . . . . . . . 11 - 5.2. Operations . . . . . . . . . . . . . . . . . . . . . . . . 11 - 5.3. Wildcards . . . . . . . . . . . . . . . . . . . . . . . . 12 - 5.4. String Comparison . . . . . . . . . . . . . . . . . . . . 12 - 5.5. Disconnected Clients . . . . . . . . . . . . . . . . . . . 12 - 5.6. Error Codes . . . . . . . . . . . . . . . . . . . . . . . 13 - 5.7. Octet Collation . . . . . . . . . . . . . . . . . . . . . 13 - 6. Use by Existing Protocols . . . . . . . . . . . . . . . . . . 13 - 7. Collation Registration . . . . . . . . . . . . . . . . . . . . 14 - 7.1. Collation Registration Procedure . . . . . . . . . . . . . 14 - 7.2. Collation Registration Format . . . . . . . . . . . . . . 15 - 7.2.1. Registration Template . . . . . . . . . . . . . . . . 15 - 7.2.2. The Collation Element . . . . . . . . . . . . . . . . 15 - 7.2.3. The Identifier Element . . . . . . . . . . . . . . . . 16 - 7.2.4. The Title Element . . . . . . . . . . . . . . . . . . 16 - 7.2.5. The Operations Element . . . . . . . . . . . . . . . . 16 - 7.2.6. The Specification Element . . . . . . . . . . . . . . 16 - 7.2.7. The Submitter Element . . . . . . . . . . . . . . . . 16 - 7.2.8. The Owner Element . . . . . . . . . . . . . . . . . . 16 - 7.2.9. The Version Element . . . . . . . . . . . . . . . . . 17 - 7.2.10. The Variable Element . . . . . . . . . . . . . . . . . 17 - 7.3. Structure of Collation Registry . . . . . . . . . . . . . 17 - 7.4. Example Initial Registry Summary . . . . . . . . . . . . . 18 - - - -Newman, et al. Standards Track [Page 2] - -RFC 4790 Collation Registry March 2007 - - - 8. Guidelines for Expert Reviewer . . . . . . . . . . . . . . . . 18 - 9. Initial Collations . . . . . . . . . . . . . . . . . . . . . . 19 - 9.1. ASCII Numeric Collation . . . . . . . . . . . . . . . . . 20 - 9.1.1. ASCII Numeric Collation Description . . . . . . . . . 20 - 9.1.2. ASCII Numeric Collation Registration . . . . . . . . . 20 - 9.2. ASCII Casemap Collation . . . . . . . . . . . . . . . . . 21 - 9.2.1. ASCII Casemap Collation Description . . . . . . . . . 21 - 9.2.2. ASCII Casemap Collation Registration . . . . . . . . . 22 - 9.3. Octet Collation . . . . . . . . . . . . . . . . . . . . . 22 - 9.3.1. Octet Collation Description . . . . . . . . . . . . . 22 - 9.3.2. Octet Collation Registration . . . . . . . . . . . . . 23 - 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 - 11. Security Considerations . . . . . . . . . . . . . . . . . . . 23 - 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 23 - 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 24 - 13.1. Normative References . . . . . . . . . . . . . . . . . . . 24 - 13.2. Informative References . . . . . . . . . . . . . . . . . . 24 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Newman, et al. Standards Track [Page 3] - -RFC 4790 Collation Registry March 2007 - - -1. Introduction - - The Application Configuration Access Protocol ACAP [11] specification - introduced the concept of a comparator (which we call collation in - this document), but failed to create an IANA registry. With the - introduction of stringprep [6] and the Unicode Collation Algorithm - [7], it is now time to create that registry and populate it with some - initial values appropriate for an international community. This - specification replaces and generalizes the definition of a comparator - in ACAP, and creates a collation registry. - -1.1. Conventions Used in This Document - - The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" - in this document are to be interpreted as defined in "Key words for - use in RFCs to Indicate Requirement Levels" [1]. - - The attribute syntax specifications use the Augmented Backus-Naur - Form (ABNF) [2] notation, including the core rules defined in - Appendix A. The ABNF production "Language-tag" is imported from - Language Tags [5] and "reg-name" from URI: Generic Syntax [4]. - -2. Collation Definition and Purpose - -2.1. Definition - - A collation is a named function which takes two arbitrary length - strings as input and can be used to perform one or more of three - basic comparison operations: equality test, substring match, and - ordering test. - -2.2. Purpose - - Collations are an abstraction for comparison functions so that these - comparison functions can be used in multiple protocols. The details - of a particular comparison operation can be specified by someone with - appropriate expertise, independent of the application protocols that - use that collation. This is similar to the way a charset [13] - separates the details of octet to character mapping from a protocol - specification, such as MIME [9], or the way SASL [10] separates the - details of an authentication mechanism from a protocol specification, - such as ACAP [11]. - - - - - - - - - -Newman, et al. Standards Track [Page 4] - -RFC 4790 Collation Registry March 2007 - - - Here is a small diagram to help illustrate the value of this - abstraction: - - +-------------------+ +-----------------+ - | IMAP i18n SEARCH |--+ | Basic | - +-------------------+ | +--| Collation Spec | - | | +-----------------+ - +-------------------+ | +-------------+ | +-----------------+ - | ACAP i18n SEARCH |--+--| Collation |--+--| A stringprep | - +-------------------+ | | Registry | | | Collation Spec | - | +-------------+ | +-----------------+ - +-------------------+ | | +-----------------+ - | ...other protocol |--+ | | locale-specific | - +-------------------+ +--| Collation Spec | - +-----------------+ - - Thus IMAP, ACAP, and future application protocols with international - search capability simply specify how to interface to the collation - registry instead of each protocol specification having to specify all - the collations it supports. - -2.3. Some Other Terms Used in this Document - - The terms client, server, and protocol are used in somewhat unusual - senses. - - Client means a user, or a program acting directly on behalf of a - user. This may be a mail reader acting as an IMAP client, or it may - be an interactive shell, where the user can type protocol commands/ - requests directly, or it may be a script or program written by the - user. - - Server means a program that performs services requested by the - client. This may be a traditional server such as an HTTP server, or - it may be a Sieve [14] interpreter running a Sieve script written by - a user. A server needs to use the operations provided by collations - in order to fulfill the client's requests. - - The protocol describes how the client tells the server what it wants - done, and (if applicable) how the server tells the client about the - results. IMAP is a protocol by this definition, and so is the Sieve - language. - -2.4. Sort Keys - - One component of a collation is a transformation, which turns a - string into a sort key, which is then used while sorting. - - - - -Newman, et al. Standards Track [Page 5] - -RFC 4790 Collation Registry March 2007 - - - The transformation can range from an identity mapping (e.g., the - i;octet collation Section 9.3) to a mapping that makes the string - unreadable to a human. - - This is an implementation detail of collations or servers. A - protocol SHOULD NOT expose it to clients, since some collations leave - the sort key's format up to the implementation, and current - conformant implementations are known to use different formats. - -3. Collation Identifier Syntax - -3.1. Basic Syntax - - The collation identifier itself is a single US-ASCII string. The - identifier MUST NOT be longer than 254 characters, and obeys the - following grammar: - - collation-char = ALPHA / DIGIT / "-" / ";" / "=" / "." - - collation-id = collation-prefix ";" collation-core-name - *collation-arg - - collation-scope = Language-tag / "vnd-" reg-name - - collation-core-name = ALPHA *( ALPHA / DIGIT / "-" ) - - collation-arg = ";" ALPHA *( ALPHA / DIGIT ) "=" - 1*( ALPHA / DIGIT / "." ) - - - Note: the ABNF production "Language-tag" is imported from Language - Tags [5] and "reg-name" from URI: Generic Syntax [4]. - - There is a special identifier called "default". For protocols that - have a default collation, "default" refers to that collation. For - other protocols, the identifier "default" MUST match no collations, - and servers SHOULD treat it in the same way as they treat nonexistent - collations. - -3.2. Wildcards - - The string a client uses to select a collation MAY contain one or - more wildcard ("*") characters that match zero or more collation- - chars. Wildcard characters MUST NOT be adjacent. If the wildcard - string matches multiple collations, the server SHOULD attempt to - select a widely useful collation in preference to a narrowly useful - one. - - - - -Newman, et al. Standards Track [Page 6] - -RFC 4790 Collation Registry March 2007 - - - collation-wild = ("*" / (ALPHA ["*"])) *(collation-char ["*"]) - ; MUST NOT exceed 254 characters total - -3.3. Ordering Direction - - When used as a protocol element for ordering, the collation - identifier MAY be prefixed by either "+" or "-" to explicitly specify - an ordering direction. "+" has no effect on the ordering operation, - while "-" inverts the result of the ordering operation. In general, - collation-order is used when a client requests a collation, and - collation-selected is used when the server informs the client of the - selected collation. - - collation-selected = ["+" / "-"] collation-id - - collation-order = ["+" / "-"] collation-wild - -3.4. URIs - - Some protocols are designed to use URIs [4] to refer to collations - rather than simple tokens. A special section of the IANA URL space - is reserved for such usage. The "collation-uri" form is used to - refer to a specific named collation (the collation registration may - not actually be present). The "collation-auri" form is an abstract - name for an ordering, a collation pattern or a vendor private - collator. - - collation-uri = "http://www.iana.org/assignments/collation/" - collation-id ".xml" - - collation-auri = ( "http://www.iana.org/assignments/collation/" - collation-order ".xml" ) / other-uri - - other-uri = <absoluteURI> - ; excluding the IANA collation namespace. - -3.5. Naming Guidelines - - While this specification makes no absolute requirements on the - structure of collation identifiers, naming consistency is important, - so the following initial guidelines are provided. - - Collation identifiers with an international audience typically begin - with "i;". Collation identifiers intended for a particular language - or locale typically begin with a language tag [5] followed by a ";". - After the first ";" is normally the name of the general collation - algorithm, followed by a series of algorithm modifications separated - by the ";" delimiter. Parameterized modifications will use "=" to - - - -Newman, et al. Standards Track [Page 7] - -RFC 4790 Collation Registry March 2007 - - - delimit the parameter from the value. The version numbers of any - lookup tables used by the algorithm SHOULD be present as - parameterized modifications. - - Collation identifiers of the form *;vnd-hostname;* are reserved for - vendor-specific collations created by the owner of the hostname - following the "vnd-" prefix (e.g., vnd-example.com for the vendor - example.com). Registration of such collations (or the name space as - a whole), with intended use of the "Vendor", is encouraged when a - public specification or open-source implementation is available, but - is not required. - -4. Collation Specification Requirements - -4.1. Collation/Server Interface - - The collation itself defines what it operates on. Most collations - are expected to operate on character strings. The i;octet - (Section 9.3) collation operates on octet strings. The i;ascii- - numeric (Section 9.1) operation operates on numbers. - - This specification defines the collation interface in terms of octet - strings. However, implementations may choose to use character - strings instead. Such implementations may not be able to implement - e.g., i;octet. Since i;octet is not currently mandatory to implement - for any protocol, this should not be a problem. - -4.2. Operations Supported - - A collation specification MUST state which of the three basic - operations are supported (equality, substring, ordering) and how to - perform each of the supported operations on any two input character - strings, including empty strings. Collations must be deterministic, - i.e., given a collation with a specific identifier, and any two fixed - input strings, the result MUST be the same for the same operation. - - In general, collation operations should behave as their names - suggest. While a collation may be new, the operations are not, so - the new collation's operations should be similar to those of older - collations. For example, a date/time collation should not provide a - "substring" operation that would morph IMAP substring SEARCH into - e.g., a date-range search. - - A non-obvious consequence of the rules for each collation operation - is that, for any single collation, either none or all of the - operations can return "undefined". For example, it is not possible - to have an equality operation that never returns "undefined", and a - substring operation that occasionally does. - - - -Newman, et al. Standards Track [Page 8] - -RFC 4790 Collation Registry March 2007 - - -4.2.1. Validity - - The validity test takes one string as argument. It returns valid if - its input string is a valid input to the collation's other - operations, and invalid if not. (In other words, a string is valid - if it is equal to itself according to the collation's equality - operation.) - - The validity test is provided by all collations. It MUST NOT be - listed separately in the collation registration. - -4.2.2. Equality - - The equality test always returns "match" or "no-match" when it is - supplied valid input, and MAY return "undefined" if one or both input - strings are not valid. - - The equality test MUST be reflexive and symmetric. For valid input, - it MUST be transitive. - - If a collation provides either a substring or an ordering test, it - MUST also provide an equality test. The substring and/or ordering - tests MUST be consistent with the equality test. - - The return values of the equality test are called "match", "no-match" - and "undefined" in this document. - -4.2.3. Substring - - The substring matching operation determines if the first string is a - substring of the second string, i.e., if one or more substrings of - the second string is equal to the first, as defined by the - collation's equality operation. - - A collation that supports substring matching will automatically - support two special cases of substring matching: prefix and suffix - matching, if those special cases are supported by the application - protocol. It returns "match" or "no-match" when it is supplied valid - input and returns "undefined" when supplied invalid input. - - Application protocols MAY return position information for substring - matches. If this is done, the position information SHOULD include - both the starting offset and the ending offset for each match. This - is important because more sophisticated collations can match strings - of unequal length (for example, a pre-composed accented character can - match a decomposed accented character). In general, overlapping - matches SHOULD be reported (as when "ana" occurs twice within - "banana"), although there are cases where a collation may decide not - - - -Newman, et al. Standards Track [Page 9] - -RFC 4790 Collation Registry March 2007 - - - to. For example, in a collation which treats all whitespace - sequences as identical, the substring operation could be defined such - that " 1 " (SP "1" SP) is reported just once within " 1 " (SP SP - "1" SP SP), not four times (SP SP "1" SP, SP "1" SP, SP "1" SP SP and - SP SP "1" SP SP), since the four matches are, in a sense, the same - match. - - A string is a substring of itself. The empty string is a substring - of all strings. - - Note that the substring operation of some collations can match - strings of unequal length. For example, a pre-composed accented - character can match a decomposed accented character. The Unicode - Collation Algorithm [7] discusses this in more detail. - - The return values of the substring operation are called "match", "no- - match", and "undefined" in this document. - -4.2.4. Ordering - - The ordering operation determines how two strings are ordered. It - MUST be reflexive. For valid input, it MUST be transitive and - trichotomous. - - Ordering returns "less" if the first string is listed before the - second string, according to the collation; "greater", if the second - string is listed before the first string; and "equal", if the two - strings are equal, as defined by the collation's equality operation. - If one or both strings are invalid, the result of ordering is - "undefined". - - When the collation is used with a "+" prefix, the behavior is the - same as when used with no prefix. When the collation is used with a - "-" prefix, the result of the ordering operation of the collation - MUST be reversed. - - The return values of the ordering operation are called "less", - "equal", "greater", and "undefined" in this document. - -4.3. Sort Keys - - A collation specification SHOULD describe the internal transformation - algorithm to generate sort keys. This algorithm can be applied to - individual strings, and the result can be stored to potentially - optimize future comparison operations. A collation MAY specify that - the sort key is generated by the identity function. The sort key may - have no meaning to a human. The sort key may not be valid input to - the collation. - - - -Newman, et al. Standards Track [Page 10] - -RFC 4790 Collation Registry March 2007 - - -4.4. Use of Lookup Tables - - Some collations use customizable lookup tables, e.g., because the - tables depend on locale, and may be modified after shipping the - software. Collations that use more than one customizable lookup - table in a documented format MUST assign numbers to the tables they - use. This permits an application protocol command to access the - tables used by a server collation, so that clients and servers use - the same tables. - -5. Application Protocol Requirements - - This section describes the requirements and issues that an - application protocol needs to consider if it offers searching, - substring matching and/or sorting, and permits the use of characters - outside the US-ASCII charset. - -5.1. Character Encoding - - The protocol specification has to make sure that it is clear on which - characters (rather than just octets) the collations are used. This - can be done by specifying the protocol itself in terms of characters - (e.g., in the case of a query language), by specifying a single - character encoding for the protocol (e.g., UTF-8 [3]), or by - carefully describing the relevant issues of character encoding - labeling and conversion. In the later case, details to consider - include how to handle unknown charsets, any charsets that are - mandatory-to-implement, any issues with byte-order that might apply, - and any transfer encodings that need to be supported. - -5.2. Operations - - The protocol must specify which of the operations defined in this - specification (equality matching, substring matching, and ordering) - can be invoked in the protocol, and how they are invoked. There may - be more than one way to invoke an operation. - - The protocol MUST provide a mechanism for the client to select the - collation to use with equality matching, substring matching, and - ordering. - - If a protocol needs a total ordering and the collation chosen does - not provide it because the ordering operation returns "undefined" at - least once, the recommended fallback is to sort all invalid strings - after the valid ones, and use i;octet to order the invalid strings. - - Although the collation's substring function provides a list of - matches, a protocol need not provide all that to the client. It may - - - -Newman, et al. Standards Track [Page 11] - -RFC 4790 Collation Registry March 2007 - - - provide only the first matching substring, or even just the - information that the substring search matched. In this way, - collations can be used with protocols that are defined such that "x - is a substring of y" returns true-false. - - If the protocol provides positional information for the results of a - substring match, that positional information SHOULD fully specify the - substring(s) in the result that matches, independent of the length of - the search string. For example, returning both the starting and - ending offset of the match would suffice, as would the starting - offset and a length. Returning just the starting offset is not - acceptable. This rule is necessary because advanced collations can - treat strings of different lengths as equal (for example, pre- - composed and decomposed accented characters). - -5.3. Wildcards - - The protocol MUST specify whether it allows the use of wildcards in - collation identifiers. If the protocol allows wildcards, then: - The protocol MUST specify how comparisons behave in the absence of - explicit collation negotiation, or when a collation of "default" - is requested. The protocol MAY specify that the default collation - used in such circumstances is sensitive to server configuration. - - The protocol SHOULD provide a way to list available collations - matching a given wildcard pattern, or patterns. - -5.4. String Comparison - - If a protocol compares strings in any nontrivial way, using a - collation may be appropriate. As an example, many protocols use - case-independent strings. In many cases, a simple ASCII mapping to - upper/lower case works well. In other cases, it may be better to use - a specifiable collation; for example, so that a server can treat "i" - and "I" as equivalent in Italy, and different in Turkey (Turkish also - has a dotted upper-case" I" and a dotless lower-case "i"). - - Protocol designers should consider, in each case, whether to use a - specifiable collation. Keywords often have other needs than user - variables, and search arguments may be different again. - -5.5. Disconnected Clients - - If the protocol supports disconnected clients, and a collation is - used that can use configurable tables (e.g., to support - locale-specific extensions), then the client may not be able to - reproduce the server's collation operations while offline. - - - - -Newman, et al. Standards Track [Page 12] - -RFC 4790 Collation Registry March 2007 - - - A mechanism to download such tables has been discussed. Such a - mechanism is not included in the present specification, since the - problem is not yet well understood. - -5.6. Error Codes - - The protocol specification should consider assigning protocol error - codes for the following circumstances: - - o The client requests the use of a collation by identifier or - pattern, but no implemented collation matches that pattern. - - o The client attempts to use a collation for an operation that is - not supported by that collation -- for example, attempting to use - the "i;ascii-numeric" collation for substring matching. - - o The client uses an equality or substring matching collation, and - the result is an error. It may be appropriate to distinguish - between the two input strings, particularly when one is supplied - by the client and the other is stored by the server. It might - also be appropriate to distinguish the specific case of an invalid - UTF-8 string. - -5.7. Octet Collation - - The i;octet (Section 9.3) collation is only usable with protocols - based on octet-strings. Clients and servers MUST NOT use i;octet - with other protocols. - - If the protocol permits the use of collations with data structures - other than strings, the protocol MUST describe the default behavior - for a collation with those data structures. - -6. Use by Existing Protocols - - This section is informative. - - Both ACAP [11] and Sieve [14] are standards track specifications that - used collations prior to the creation of this specification and - registry. Those standards do not meet all the application protocol - requirements described in Section 5. - - These protocols allow the use of the i;octet (Section 9.3) collation - working directly on UTF-8 data, as used in these protocols. - - - - - - - -Newman, et al. Standards Track [Page 13] - -RFC 4790 Collation Registry March 2007 - - - In Sieve, all matches are either true or false. Accordingly, Sieve - servers must treat "undefined" and "no-match" results of the equality - and substring operations as false, and only "match" as true. - - In ACAP and Sieve, there are no invalid strings. In this document's - terms, invalid strings sort after valid strings. - - IMAP [15] also collates, although that is explicit only when the - COMPARATOR [17] extension is used. The built-in IMAP substring - operation and the ordering provided by the SORT [16] extension may - not meet the requirements made in this document. - - Other protocols may be in a similar position. - - In IMAP, the default collation is i;ascii-casemap, because its - operations are understood to match IMAP's built-in operations. - -7. Collation Registration - -7.1. Collation Registration Procedure - - The IETF will create a mailing list, collation@ietf.org, which can be - used for public discussion of collation proposals prior to - registration. Use of the mailing list is strongly encouraged. The - IESG will appoint a designated expert who will monitor the - collation@ietf.org mailing list and review registrations. - - The registration procedure begins when a completed registration - template is sent to iana@iana.org and collation@ietf.org. The - designated expert is expected to tell IANA and the submitter of the - registration within two weeks whether the registration is approved, - approved with minor changes, or rejected with cause. When a - registration is rejected with cause, it can be re-submitted if the - concerns listed in the cause are addressed. Decisions made by the - designated expert can be appealed to the IESG Applications Area - Director, then to the IESG. They follow the normal appeals procedure - for IESG decisions. - - Collation registrations in a standards track, BCP, or IESG-approved - experimental RFC are owned by the IETF, and changes to the - registration follow normal procedures for updating such documents. - Collation registrations in other RFCs are owned by the RFC author(s). - Other collation registrations are owned by the individual(s) listed - in the contact field of the registration, and IANA will preserve this - information. - - If the registration is a change of an existing collation, it MUST be - approved by the owner. In the event the owner cannot be contacted - - - -Newman, et al. Standards Track [Page 14] - -RFC 4790 Collation Registry March 2007 - - - for a period of one month, and the designated expert deems the change - necessary, the IESG MAY re-assign ownership to an appropriate party. - -7.2. Collation Registration Format - - Registration of a collation is done by sending a well-formed XML - document to collation@ietf.org and iana@iana.org. - -7.2.1. Registration Template - - Here is a template for the registration: - - <?xml version='1.0'?> - <!DOCTYPE collation SYSTEM 'collationreg.dtd'> - <collation rfc="YYYY" scope="global" intendedUse="common"> - <identifier>collation identifier</identifier> - <title>technical title for collation</title> - <operations>equality order substring</operations> - <specification>specification reference</specification> - <owner>email address of owner or IETF</owner> - <submitter>email address of submitter</submitter> - <version>1</version> - </collation> - -7.2.2. The Collation Element - - The root of the registration document MUST be a <collation> element. - The collation element contains the other elements in the - registration, which are described in the following sub-subsections, - in the order given here. - - The <collation> element MAY include an "rfc=" attribute if the - specification is in an RFC. The "rfc=" attribute gives only the - number of the RFC, without any prefix, such as "RFC", or suffix, such - as ".txt". - - The <collation> element MUST include a "scope=" attribute, which MUST - have one of the values "global", "local", or "other". - - The <collation> element MUST include an "intendedUse=" attribute, - which must have one of the values "common", "limited", "vendor", or - "deprecated". Collation specifications intended for "common" use are - expected to reference standards from standards bodies with - significant experience dealing with the details of international - character sets. - - Be aware that future revisions of this specification may add - additional function types, as well as additional XML attributes, - - - -Newman, et al. Standards Track [Page 15] - -RFC 4790 Collation Registry March 2007 - - - values, and elements. Any system that automatically parses these XML - documents MUST take this into account to preserve future - compatibility. - -7.2.3. The Identifier Element - - The <identifier> element gives the precise identifier of the - collation, e.g., i;ascii-casemap. The <identifier> element is - mandatory. - -7.2.4. The Title Element - - The <title> element gives the title of the collation. The <title> - element is mandatory. - -7.2.5. The Operations Element - - The <operations> element lists which of the three operations - ("equality", "order" or "substring") the collation provides, - separated by single spaces. The <operations> element is mandatory. - -7.2.6. The Specification Element - - The <specification> element describes where to find the - specification. The <specification> element is mandatory. It MAY - have a URI attribute. There may be more than one <specification> - element, in which case, they together form the specification. - - If it is discovered that parts of a collation specification conflict, - a new revision of the collation is necessary, and the - collation@ietf.org mailing list should be notified. - -7.2.7. The Submitter Element - - The <submitter> element provides an RFC 2822 [12] email address for - the person who submitted the registration. It is optional if the - <owner> element contains an email address. - - There may be more than one <submitter> element. - -7.2.8. The Owner Element - - The <owner> element contains either the four letters "IETF" or an - email address of the owner of the registration. The <owner> element - is mandatory. There may be more than one <owner> element. If so, - all owners are equal. Each owner can speak for all. - - - - - -Newman, et al. Standards Track [Page 16] - -RFC 4790 Collation Registry March 2007 - - -7.2.9. The Version Element - - The <version> element MUST be included when the registration is - likely to be revised, or has been revised in such a way that the - results change for one or more input strings. The <version> element - is optional. - -7.2.10. The Variable Element - - The <variable> element specifies an optional variable to control the - collation's behaviour, for example whether it is case sensitive. The - <variable> element is optional. When <variable> is used, it must - contain <name> and <default> elements, and it may contain one or more - <value> elements. - -7.2.10.1. The Name Element - - The <name> element specifies the name value of a variable. The - <name> element is mandatory. - -7.2.10.2. The Default Element - - The <default> element specifies the default value of a variable. The - <default> element is mandatory. - -7.2.10.3. The Value Element - - The <value> element specifies a legal value of a variable. The - <value> element is optional. If one or more <value> elements are - present, only those values are legal. If none are, then the - variable's legal values do not form an enumerated set, and the rules - MUST be specified in an RFC accompanying the registration. - -7.3. Structure of Collation Registry - - Once the registration is approved, IANA will store each XML - registration document in a URL of the form - http://www.iana.org/assignments/collation/collation-id.xml, where - collation-id is the content of the identifier element in the - registration. Both the submitter and the designated expert are - responsible for verifying that the XML is well-formed. The - registration document should avoid using new elements. If any are - necessary, it is important to be consistent with other registrations. - - IANA will also maintain a text summary of the registry under the name - http://www.iana.org/assignments/collation/collation-index.html. This - summary is divided into four sections. The first section is for - collations intended for common use. This section is intended for - - - -Newman, et al. Standards Track [Page 17] - -RFC 4790 Collation Registry March 2007 - - - collation registrations published in IESG-approved RFCs, or for - locally scoped collations from the primary standards body for that - locale. The designated expert is encouraged to reject collation - registrations with an intended use of "common" if the expert believes - it should be "limited", as it is desirable to keep the number of - "common" registrations small and of high quality. The second section - is reserved for limited-use collations. The third section is - reserved for registered vendor-specific collations. The final - section is reserved for deprecated collations. - -7.4. Example Initial Registry Summary - - The following is an example of how IANA might structure the initial - registry summary.html file: - - Collation Functions Scope Reference - --------- --------- ----- --------- - Common Use Collations: - i;ascii-casemap e, o, s Local [RFC 4790] - - Limited Use Collations: - i;octet e, o, s Other [RFC 4790] - i;ascii-numeric e, o Other [RFC 4790] - - Vendor Collations: - - Deprecated Collations: - - - References - ---------- - [RFC 4790] Newman, C., Duerst, M., Gulbrandsen, A., "Internet - Application Protocol Collation Registry", RFC 4790, - Sun Microsystems, March 2007. - -8. Guidelines for Expert Reviewer - - The expert reviewer appointed by the IESG has fairly broad latitude - for this registry. While a number of collations are expected - (particularly customizations of the UCA for localized use), an - explosion of collations (particularly common-use collations) is not - desirable for widespread interoperability. However, it is important - for the expert reviewer to provide cause when rejecting a - registration, and, when possible, to describe corrective action to - - - - - - - -Newman, et al. Standards Track [Page 18] - -RFC 4790 Collation Registry March 2007 - - - permit the registration to proceed. The following table includes - some example reasons to reject a registration with cause: - - o The registration is not a well-formed XML document. - - o The registration has an intended use of "common", but there is no - evidence the collation will be widely deployed, so it should be - listed as "limited". - - o The registration has an intended use of "common", but it is - redundant with the functionality of a previously registered - "common" collation. - - o The registration has an intended use of "common", but the - specification is not detailed enough to allow interoperable - implementations by others. - - o The collation identifier fails to precisely identify the version - numbers of relevant tables to use. - - o The registration fails to meet one of the "MUST" requirements in - Section 4. - - o The collation identifier fails to meet the syntax in Section 3. - - o The collation specification referenced in the registration is - vague or has optional features without a clear behavior specified. - - o The referenced specification does not adequately address security - considerations specific to that collation. - - o The registration's operations are needlessly different from those - of traditional operations. - - o The registration's XML is needlessly different from that of - already registered collations. - -9. Initial Collations - - This section registers the three collations that were originally - defined in [11], and are implemented in most [14] engines. Some of - the behavior of these collations is perhaps not ideal, such as - i;ascii-casemap accepting non-ASCII input. Compatibility with widely - deployed code was judged more important than fixing the collations. - Some of the aspects of these collations are necessary to maintain - compatibility with widely deployed code. - - - - - -Newman, et al. Standards Track [Page 19] - -RFC 4790 Collation Registry March 2007 - - -9.1. ASCII Numeric Collation - -9.1.1. ASCII Numeric Collation Description - - The "i;ascii-numeric" collation is a simple collation intended for - use with arbitrarily-sized, unsigned decimal integer numbers stored - as octet strings. US-ASCII digits (0x30 to 0x39) represent digits of - the numbers. Before converting from string to integer, the input - string is truncated at the first non-digit character. All input is - valid; strings that do not start with a digit represent positive - infinity. - - The collation supports equality and ordering, but does not support - the substring operation. - - The equality operation returns "match" if the two strings represent - the same number (i.e., leading zeroes and trailing non-digits are - disregarded), and "no-match" if the two strings represent different - numbers. - - The ordering operation returns "less" if the first string represents - a smaller number than the second, "equal" if they represent the same - number, and "greater" if the first string represents a larger number - than the second. - - Some examples: "0" is less than "1", and "1" is less than - "4294967298". "4294967298", "04294967298", and "4294967298b" are all - equal. "04294967298" is less than "". "", "x", and "y" are equal. - -9.1.2. ASCII Numeric Collation Registration - - <?xml version='1.0'?> - <!DOCTYPE collation SYSTEM 'collationreg.dtd'> - <collation rfc="4790" scope="other" intendedUse="limited"> - <identifier>i;ascii-numeric</identifier> - <title>ASCII Numeric</title> - <operations>equality order</operations> - <specification>RFC 4790</specification> - <owner>IETF</owner> - <submitter>chris.newman@sun.com</submitter> - </collation> - - - - - - - - - - -Newman, et al. Standards Track [Page 20] - -RFC 4790 Collation Registry March 2007 - - -9.2. ASCII Casemap Collation - -9.2.1. ASCII Casemap Collation Description - - The "i;ascii-casemap" collation is a simple collation that operates - on octet strings and treats US-ASCII letters case-insensitively. It - provides equality, substring, and ordering operations. All input is - valid. Note that letters outside ASCII are not treated case- - insensitively. - - Its equality, ordering, and substring operations are as for i;octet, - except that at first, the lower-case letters (octet values 97-122) in - each input string are changed to upper case (octet values 65-90). - - Care should be taken when using OS-supplied functions to implement - this collation, as it is not locale sensitive. Functions, such as - strcasecmp and toupper, are sometimes locale sensitive, and may - inappropriately map lower-case letters other than a-z to upper case. - - The i;ascii-casemap collation is well-suited for use with many - Internet protocols and computer languages. Use with natural language - is often inappropriate; even though the collation apparently supports - languages such as Swahili and English, in real-world use, it tends to - mis-sort a number of types of string: - - o people and place names containing non-ASCII, - - o words such as "naive" (if spelled with an accent, the accented - character could push the word to the wrong spot in a sorted list), - - o names such as "Lloyd" (which, in Welsh, sorts after "Lyon", unlike - in English), - - o strings containing euro and pound sterling symbols, quotation - marks other than '"', dashes/hyphens, etc. - - - - - - - - - - - - - - - - -Newman, et al. Standards Track [Page 21] - -RFC 4790 Collation Registry March 2007 - - -9.2.2. ASCII Casemap Collation Registration - - <?xml version='1.0'?> - <!DOCTYPE collation SYSTEM 'collationreg.dtd'> - <collation rfc="4790" scope="local" intendedUse="common"> - <identifier>i;ascii-casemap</identifier> - <title>ASCII Casemap</title> - <operations>equality order substring</operations> - <specification>RFC 4790</specification> - <owner>IETF</owner> - <submitter>chris.newman@sun.com</submitter> - </collation> - -9.3. Octet Collation - -9.3.1. Octet Collation Description - - The "i;octet" collation is a simple and fast collation intended for - use on binary octet strings rather than on character data. Protocols - that want to make this collation available have to do so by - explicitly allowing it. If not explicitly allowed, it MUST NOT be - used. It never returns an "undefined" result. It provides equality, - substring, and ordering operations. - - The ordering algorithm is as follows: - - 1. If both strings are the empty string, return the result "equal". - - 2. If the first string is empty and the second is not, return the - result "less". - - 3. If the second string is empty and the first is not, return the - result "greater". - - 4. If both strings begin with the same octet value, remove the first - octet from both strings and repeat this algorithm from step 1. - - 5. If the unsigned value (0 to 255) of the first octet of the first - string is less than the unsigned value of the first octet of the - second string, then return "less". - - 6. If this step is reached, return "greater". - - This algorithm is roughly equivalent to the C library function - memcmp, with appropriate length checks added. - - - - - - -Newman, et al. Standards Track [Page 22] - -RFC 4790 Collation Registry March 2007 - - - The matching operation returns "match" if the sorting algorithm would - return "equal". Otherwise, the matching operation returns "no- - match". - - The substring operation returns "match" if the first string is the - empty string, or if there exists a substring of the second string of - length equal to the length of the first string, which would result in - a "match" result from the equality function. Otherwise, the - substring operation returns "no-match". - -9.3.2. Octet Collation Registration - - This collation is defined with intendedUse="limited" because it can - only be used by protocols that explicitly allow it. - - <?xml version='1.0'?> - <!DOCTYPE collation SYSTEM 'collationreg.dtd'> - <collation rfc="4790" scope="global" intendedUse="limited"> - <identifier>i;octet</identifier> - <title>Octet</title> - <operations>equality order substring</operations> - <specification>RFC 4790</specification> - <owner>IETF</owner> - <submitter>chris.newman@sun.com</submitter> - </collation> - -10. IANA Considerations - - Section 7 defines how to register collations with IANA. Section 9 - defines a list of predefined collations that have been registered - with IANA. - -11. Security Considerations - - Collations will normally be used with UTF-8 strings. Thus, the - security considerations for UTF-8 [3], stringprep [6], and Unicode - TR-36 [8] also apply, and are normative to this specification. - -12. Acknowledgements - - The authors want to thank all who have contributed to this document, - including Brian Carpenter, John Cowan, Dave Cridland, Mark Davis, - Spencer Dawkins, Lisa Dusseault, Lars Eggert, Frank Ellermann, Philip - Guenther, Tony Hansen, Ted Hardie, Sam Hartman, Kjetil Torgrim Homme, - Michael Kay, John Klensin, Alexey Melnikov, Jim Melton, and Abhijit - Menon-Sen. - - - - - -Newman, et al. Standards Track [Page 23] - -RFC 4790 Collation Registry March 2007 - - -13. References - -13.1. Normative References - - [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement - Levels", BCP 14, RFC 2119, March 1997. - - [2] Crocker, D. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", RFC 4234, October 2005. - - [3] Yergeau, F., "UTF-8, a transformation format of ISO 10646", - STD 63, RFC 3629, November 2003. - - [4] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform - Resource Identifier (URI): Generic Syntax", RFC 3986, - January 2005. - - [5] Phillips, A. and M. Davis, "Tags for Identifying Languages", - BCP 47, RFC 4646, September 2006. - - [6] Hoffman, P. and M. Blanchet, "Preparation of Internationalized - Strings ("stringprep")", RFC 3454, December 2002. - - [7] Davis, M. and K. Whistler, "Unicode Collation Algorithm version - 14", May 2005, - <http://www.unicode.org/reports/tr10/tr10-14.html>. - - [8] Davis, M. and M. Suignard, "Unicode Security Considerations", - February 2006, <http://www.unicode.org/reports/tr36/>. - -13.2. Informative References - - [9] Freed, N. and N. Borenstein, "Multipurpose Internet Mail - Extensions (MIME) Part One: Format of Internet Message Bodies", - RFC 2045, November 1996. - - [10] Melnikov, A., "Simple Authentication and Security Layer - (SASL)", RFC 4422, June 2006. - - [11] Newman, C. and J. Myers, "ACAP -- Application Configuration - Access Protocol", RFC 2244, November 1997. - - [12] Resnick, P., "Internet Message Format", RFC 2822, April 2001. - - [13] Freed, N. and J. Postel, "IANA Charset Registration - Procedures", BCP 19, RFC 2978, October 2000. - - - - - -Newman, et al. Standards Track [Page 24] - -RFC 4790 Collation Registry March 2007 - - - [14] Showalter, T., "Sieve: A Mail Filtering Language", RFC 3028, - January 2001. - - [15] Crispin, M., "Internet Message Access Protocol - Version - 4rev1", RFC 3501, March 2003. - - [16] Crispin, M. and K. Murchison, "Internet Message Access Protocol - - Sort and Thread Extensions", Work in Progress, May 2004. - - [17] Newman, C. and A. Gulbrandsen, "Internet Message Access - Protocol Internationalization", Work in Progress, January 2006. - -Authors' Addresses - - Chris Newman - Sun Microsystems - 1050 Lakes Drive - West Covina, CA 91790 - USA - - EMail: chris.newman@sun.com - - - Martin Duerst - Aoyama Gakuin University - 5-10-1 Fuchinobe - Sagamihara, Kanagawa 229-8558 - Japan - - Phone: +81 42 759 6329 - Fax: +81 42 759 6495 - EMail: duerst@it.aoyama.ac.jp - URI: http://www.sw.it.aoyama.ac.jp/D%C3%BCrst/ - - Note: Please write "Duerst" with u-umlaut wherever possible, for - example as "Dürst" in XML and HTML. - - - Arnt Gulbrandsen - Oryx Mail Systems GmbH - Schweppermannstr. 8 - 81671 Munich - Germany - - Fax: +49 89 4502 9758 - EMail: arnt@oryx.com - URI: http://www.oryx.com/arnt/ - - - - -Newman, et al. Standards Track [Page 25] - -RFC 4790 Collation Registry March 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. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - -Newman, et al. Standards Track [Page 26] - diff --git a/imap/docs/rfc/rfc4959.txt b/imap/docs/rfc/rfc4959.txt deleted file mode 100644 index 3df18354..00000000 --- a/imap/docs/rfc/rfc4959.txt +++ /dev/null @@ -1,395 +0,0 @@ - - - - - - -Network Working Group R. Siemborski -Request for Comments: 4959 Google, Inc. -Category: Standards Track A. Gulbrandsen - Oryx Mail Systems GmbH - September 2007 - - - IMAP Extension for Simple Authentication and Security Layer (SASL) - Initial Client Response - -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 - - To date, the Internet Message Access Protocol (IMAP) has used a - Simple Authentication and Security Layer (SASL) profile which always - required at least one complete round trip for an authentication, as - it did not support an initial client response argument. This - additional round trip at the beginning of the session is undesirable, - especially when round-trip costs are high. - - This document defines an extension to IMAP which allows clients and - servers to avoid this round trip by allowing an initial client - response argument to the IMAP AUTHENTICATE command. - - - - - - - - - - - - - - - - - - - - - -Siemborski & Gulbrandsen Standards Track [Page 1] - -RFC 4959 IMAP Ext for SASL Initial Client Response September 2007 - - -1. Introduction - - The SASL initial client response extension is present in any IMAP - [RFC3501] server implementation which returns "SASL-IR" as one of the - supported capabilities in its CAPABILITY response. - - Servers which support this extension will accept an optional initial - client response with the AUTHENTICATE command for any SASL [RFC4422] - mechanisms which support it. - -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]. - - In examples, "C:" and "S:" indicate lines sent by the client and - server, respectively. - - Formal syntax is defined by [RFC4234] as extended by [RFC3501]. - -3. IMAP Changes to the IMAP AUTHENTICATE Command - - This extension adds an optional second argument to the AUTHENTICATE - command that is defined in Section 6.2.2 of [RFC3501]. If this - second argument is present, it represents the contents of the - "initial client response" defined in Section 5.1 of [RFC4422]. - - As with any other client response, this initial client response MUST - be encoded as defined in Section 4 of [RFC4648]. It also MUST be - transmitted outside of a quoted string or literal. To send a zero- - length initial response, the client MUST send a single pad character - ("="). This indicates that the response is present, but is a zero- - length string. - - When decoding the BASE64 [RFC4648] data in the initial client - response, decoding errors MUST be treated as IMAP [RFC3501] would - handle them in any normal SASL client response. In particular, the - server should check for any characters not explicitly allowed by the - BASE64 alphabet, as well as any sequence of BASE64 characters that - contains the pad character ('=') anywhere other than the end of the - string (e.g., "=AAA" and "AAA=BBB" are not allowed). - - If the client uses an initial response with a SASL mechanism that - does not support an initial response, the server MUST reject the - command with a tagged BAD response. - - - - - -Siemborski & Gulbrandsen Standards Track [Page 2] - -RFC 4959 IMAP Ext for SASL Initial Client Response September 2007 - - - Note: support and use of the initial client response is optional for - both clients and servers. Servers that implement this extension MUST - support clients that omit the initial client response, and clients - that implement this extension MUST NOT send an initial client - response to servers that do not advertise the SASL-IR capability. In - such a situation, clients MUST fall back to an IMAP [RFC3501] - compatible mode. - - If either the client or the server do not support the SASL-IR - capability, a mechanism which uses an initial client response is - negotiated using the challenge/response exchange described in - [RFC3501], with an initial zero-length server challenge. - -4. Examples - - The following is an example authentication using the PLAIN (see - [RFC4616]) SASL mechanism (under a TLS protection layer, see - [RFC4346]) and an initial client response: - - ... client connects to server and negotiates a TLS - protection layer ... - C: C01 CAPABILITY - S: * CAPABILITY IMAP4rev1 SASL-IR AUTH=PLAIN - S: C01 OK Completed - C: A01 AUTHENTICATE PLAIN dGVzdAB0ZXN0AHRlc3Q= - S: A01 OK Success (tls protection) - - Note that even when a server supports this extension, the following - negotiation (which does not use the initial response) is still valid - and MUST be supported by the server: - - ... client connects to server and negotiates a TLS - protection layer ... - C: C01 CAPABILITY - S: * CAPABILITY IMAP4rev1 SASL-IR AUTH=PLAIN - S: C01 OK Completed - C: A01 AUTHENTICATE PLAIN - (note that there is a space following the "+" in the - following line) - S: + - C: dGVzdAB0ZXN0AHRlc3Q= - S: A01 OK Success (tls protection) - - The following is an example authentication using the SASL EXTERNAL - mechanism (defined in [RFC4422]) under a TLS protection layer (see - [RFC4346]) and an empty initial client response: - - - - - -Siemborski & Gulbrandsen Standards Track [Page 3] - -RFC 4959 IMAP Ext for SASL Initial Client Response September 2007 - - - ... client connects to server and negotiates a TLS - protection layer ... - C: C01 CAPABILITY - S: * CAPABILITY IMAP4rev1 SASL-IR AUTH=PLAIN AUTH=EXTERNAL - S: C01 OK Completed - C: A01 AUTHENTICATE EXTERNAL = - S: A01 OK Success (tls protection) - - This is in contrast with the handling of such a situation when an - initial response is omitted: - - ... client connects to server and negotiates a TLS protection - layer ... - C: C01 CAPABILITY - S: * CAPABILITY IMAP4rev1 SASL-IR AUTH=PLAIN AUTH=EXTERNAL - S: C01 OK Completed - C: A01 AUTHENTICATE EXTERNAL - (note that there is a space following the "+" in the - following line) - S: + - C: - S: A01 OK Success (tls protection) - -5. IANA Considerations - - The IANA has added SASL-IR to the IMAP4 Capabilities Registry. - -6. Security Considerations - - The extension defined in this document is subject to many of the - Security Considerations defined in [RFC3501] and [RFC4422]. - - Server implementations MUST treat the omission of an initial client - response from the AUTHENTICATE command as defined by [RFC3501] (as if - this extension did not exist). - - Although [RFC3501] has no express line length limitations, some - implementations choose to enforce them anyway. Such implementations - MUST be aware that the addition of the initial response parameter to - AUTHENTICATE may increase the maximum line length that IMAP parsers - may expect to support. Server implementations MUST be able to - receive the largest possible initial client response that their - supported mechanisms might receive. - - - - - - - - -Siemborski & Gulbrandsen Standards Track [Page 4] - -RFC 4959 IMAP Ext for SASL Initial Client Response September 2007 - - -7. Formal Syntax - - The following syntax specification uses the Augmented Backus-Naur - Form [RFC4234] notation. [RFC3501] defines the non-terminals - capability, auth-type, and base64. - - capability =/ "SASL-IR" - - authenticate = "AUTHENTICATE" SP auth-type [SP (base64 / "=")] - *(CRLF base64) - ;;redefine AUTHENTICATE from [RFC3501] - -8. Acknowledgments - - The authors would like to acknowledge the contributions of Ken - Murchison and Mark Crispin, along with the rest of the IMAPEXT - Working Group for their assistance in reviewing this document. - - Alexey Melnikov and Cyrus Daboo also had some early discussions about - this extension. - -9. References - -9.1. Normative References - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION - 4rev1", RFC 3501, March 2003. - - [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", RFC 4234, October 2005. - - [RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication and - Security Layer (SASL)", RFC 4422, June 2006. - - [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data - Encodings", RFC 4648, October 2006. - -9.2. Informative References - - [RFC4616] Zeilenga, K., "The PLAIN Simple Authentication and - Security Layer (SASL) Mechanism", RFC 4616, August 2006. - - [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security - (TLS) Protocol Version 1.1", RFC 4346, April 2006. - - - - -Siemborski & Gulbrandsen Standards Track [Page 5] - -RFC 4959 IMAP Ext for SASL Initial Client Response September 2007 - - -Authors' Addresses - - Robert Siemborski - Google, Inc. - 1600 Ampitheatre Parkway - Mountain View, CA 94043 - - Phone: +1 650 623 6925 - EMail: robsiemb@google.com - - - Arnt Gulbrandsen - Oryx Mail Systems GmbH - Schweppermannstr. 8 - D-81671 Muenchen - Germany - - EMail: arnt@oryx.com - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Siemborski & Gulbrandsen Standards Track [Page 6] - -RFC 4959 IMAP Ext for SASL Initial Client Response 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. - - - - - - - - - - - - -Siemborski & Gulbrandsen Standards Track [Page 7] - diff --git a/imap/docs/rfc/rfc4978.txt b/imap/docs/rfc/rfc4978.txt deleted file mode 100644 index 14b56b6e..00000000 --- a/imap/docs/rfc/rfc4978.txt +++ /dev/null @@ -1,507 +0,0 @@ - - - - - - -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/imap/docs/rfc/rfc5032.txt b/imap/docs/rfc/rfc5032.txt deleted file mode 100644 index f8e48953..00000000 --- a/imap/docs/rfc/rfc5032.txt +++ /dev/null @@ -1,283 +0,0 @@ - - - - - - -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 <interval> and YOUNGER <interval>. - - 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 - <http://www.iana.org/assignments/imap4-capabilities>. 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/imap/docs/rfc/rfc5051.txt b/imap/docs/rfc/rfc5051.txt deleted file mode 100644 index 0a4479ca..00000000 --- a/imap/docs/rfc/rfc5051.txt +++ /dev/null @@ -1,395 +0,0 @@ - - - - - - -Network Working Group M. Crispin -Request for Comments: 5051 University of Washington -Category: Standards Track October 2007 - - - i;unicode-casemap - Simple Unicode Collation Algorithm - -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 "i;unicode-casemap", a simple case- - insensitive collation for Unicode strings. It provides equality, - substring, and ordering operations. - -1. Introduction - - The "i;ascii-casemap" collation described in [COMPARATOR] is quite - simple to implement and provides case-independent comparisons for the - 26 Latin alphabetics. It is specified as the default and/or baseline - comparator in some application protocols, e.g., [IMAP-SORT]. - - However, the "i;ascii-casemap" collation does not produce - satisfactory results with non-ASCII characters. It is possible, with - a modest extension, to provide a more sophisticated collation with - greater multilingual applicability than "i;ascii-casemap". This - extension provides case-independent comparisons for a much greater - number of characters. It also collates characters with diacriticals - with the non-diacritical character forms. - - This collation, "i;unicode-casemap", is intended to be an alternative - to, and preferred over, "i;ascii-casemap". It does not replace the - "i;basic" collation described in [BASIC]. - -2. Unicode Casemap Collation Description - - The "i;unicode-casemap" collation is a simple collation which is - case-insensitive in its treatment of characters. It provides - equality, substring, and ordering operations. The validity test - operation returns "valid" for any input. - - - - - -Crispin Standards Track [Page 1] - -RFC 5051 i;unicode-casemap October 2007 - - - This collation allows strings in arbitrary (and mixed) character - sets, as long as the character set for each string is identified and - it is possible to convert the string to Unicode. Strings which have - an unidentified character set and/or cannot be converted to Unicode - are not rejected, but are treated as binary. - - Each input string is prepared by converting it to a "titlecased - canonicalized UTF-8" string according to the following steps, using - UnicodeData.txt ([UNICODE-DATA]): - - (1) A Unicode codepoint is obtained from the input string. - - (a) If the input string is in a known charset that can be - converted to Unicode, a sequence in the string's charset - is read and checked for validity according to the rules of - that charset. If the sequence is valid, it is converted - to a Unicode codepoint. Note that for input strings in - UTF-8, the UTF-8 sequence must be valid according to the - rules of [UTF-8]; e.g., overlong UTF-8 sequences are - invalid. - - (b) If the input string is in an unknown charset, or an - invalid sequence occurs in step (1)(a), conversion ceases. - No further preparation is performed, and any partial - preparation results are discarded. The original string is - used unchanged with the i;octet comparator. - - (2) The following steps, using UnicodeData.txt ([UNICODE-DATA]), - are performed on the resulting codepoint from step (1)(a). - - (a) If the codepoint has a titlecase property in - UnicodeData.txt (this is normally the same as the - uppercase property), the codepoint is converted to the - codepoints in the titlecase property. - - (b) If the resulting codepoint from (2)(a) has a decomposition - property of any type in UnicodeData.txt, the codepoint is - converted to the codepoints in the decomposition property. - This step is recursively applied to each of the resulting - codepoints until no more decomposition is possible - (effectively Normalization Form KD). - - Example: codepoint U+01C4 (LATIN CAPITAL LETTER DZ WITH CARON) - has a titlecase property of U+01C5 (LATIN CAPITAL LETTER D - WITH SMALL LETTER Z WITH CARON). Codepoint U+01C5 has a - decomposition property of U+0044 (LATIN CAPITAL LETTER D) - U+017E (LATIN SMALL LETTER Z WITH CARON). U+017E has a - decomposition property of U+007A (LATIN SMALL LETTER Z) U+030c - - - -Crispin Standards Track [Page 2] - -RFC 5051 i;unicode-casemap October 2007 - - - (COMBINING CARON). Neither U+0044, U+007A, nor U+030C have - any decomposition properties. Therefore, U+01C4 is converted - to U+0044 U+007A U+030C by this step. - - (3) The resulting codepoint(s) from step (2) is/are appended, in - UTF-8 format, to the "titlecased canonicalized UTF-8" string. - - (4) Repeat from step (1) until there is no more data in the input - string. - - Following the above preparation process on each string, the equality, - ordering, and substring operations are as for i;octet. - - It is permitted to use an alternative implementation of the above - preparation process if it produces the same results. For example, it - may be more convenient for an implementation to convert all input - strings to a sequence of UTF-16 or UTF-32 values prior to performing - any of the step (2) actions. Similarly, if all input strings are (or - are convertible to) Unicode, it may be possible to use UTF-32 as an - alternative to UTF-8 in step (3). - - Note: UTF-16 is unsuitable as an alternative to UTF-8 in step (3), - because UTF-16 surrogates will cause i;octet to collate codepoints - U+E0000 through U+FFFF after non-BMP codepoints. - - This collation is not locale sensitive. Consequently, care should be - taken when using OS-supplied functions to implement this collation. - Functions such as strcasecmp and toupper are sometimes locale - sensitive and may inconsistently casemap letters. - - The i;unicode-casemap collation is well suited to use with many - Internet protocols and computer languages. Use with natural language - is often inappropriate; even though the collation apparently supports - languages such as Swahili and English, in real-world use it tends to - mis-sort a number of types of string: - - o people and place names containing scripts that are not collated - according to "alphabetical order". - o words with characters that have diacriticals. However, - i;unicode-casemap generally does a better job than i;ascii-casemap - for most (but not all) languages. For example, German umlaut - letters will sort correctly, but some Scandinavian letters will - not. - o names such as "Lloyd" (which in Welsh sorts after "Lyon", unlike - in English), - o strings containing other non-letter symbols; e.g., euro and pound - sterling symbols, quotation marks other than '"', dashes/hyphens, - etc. - - - -Crispin Standards Track [Page 3] - -RFC 5051 i;unicode-casemap October 2007 - - -3. Unicode Casemap Collation Registration - - <?xml version='1.0'?> - <!DOCTYPE collation SYSTEM 'collationreg.dtd'> - <collation rfc="5051" scope="global" intendedUse="common"> - <identifier>i;unicode-casemap</identifier> - <title>Unicode Casemap</title> - <operations>equality order substring</operations> - <specification>RFC 5051</specification> - <owner>IETF</owner> - <submitter>mrc@cac.washington.edu</submitter> - </collation> - -4. Security Considerations - - The security considerations for [UTF-8], [STRINGPREP], and [UNICODE- - SECURITY] apply and are normative to this specification. - - The results from this comparator will vary depending upon the - implementation for several reasons. Implementations MUST consider - whether these possibilities are a problem for their use case: - - 1) New characters added in Unicode may have decomposition or - titlecase properties that will not be known to an implementation - based upon an older revision of Unicode. This impacts step (2). - - 2) Step (2)(b) defines a subset of Normalization Form KD (NFKD) that - does not require normalization of out-of-order diacriticals. - However, an implementation MAY use an NFKD library routine that - does such normalization. This impacts step (2)(b) and possibly - also step (1)(a), and is an issue only with ill-formed UTF-8 - input. - - 3) The set of charsets handled in step (1)(a) is open-ended. UTF-8 - (and, by extension, US-ASCII) are the only mandatory-to-implement - charsets. This impacts step (1)(a). - - Implementations SHOULD, as far as feasible, support all the - charsets they are likely to encounter in the input data, in order - to avoid poor collation caused by the fall through to the (1)(b) - rule. - - 4) Other charsets may have revisions which add new characters that - are not known to an implementation based upon an older revision. - This impacts step (1)(a) and possibly also step (1)(b). - - - - - - -Crispin Standards Track [Page 4] - -RFC 5051 i;unicode-casemap October 2007 - - - An attacker may create input that is ill-formed or in an unknown - charset, with the intention of impacting the results of this - comparator or exploiting other parts of the system which process this - input in different ways. Note, however, that even well-formed data - in a known charset can impact the result of this comparator in - unexpected ways. For example, an attacker can substitute U+0041 - (LATIN CAPITAL LETTER A) with U+0391 (GREEK CAPITAL LETTER ALPHA) or - U+0410 (CYRILLIC CAPITAL LETTER A) in the intention of causing a - non-match of strings which visually appear the same and/or causing - the string to appear elsewhere in a sort. - -5. IANA Considerations - - The i;unicode-casemap collation defined in section 2 has been added - to the registry of collations defined in [COMPARATOR]. - -6. Normative References - - [COMPARATOR] Newman, C., Duerst, M., and A. Gulbrandsen, - "Internet Application Protocol Collation - Registry", RFC 4790, February 2007. - - [STRINGPREP] Hoffman, P. and M. Blanchet, "Preparation of - Internationalized Strings ("stringprep")", RFC - 3454, December 2002. - - [UTF-8] Yergeau, F., "UTF-8, a transformation format of - ISO 10646", STD 63, RFC 3629, November 2003. - - [UNICODE-DATA] <http://www.unicode.org/Public/UNIDATA/ - UnicodeData.txt> - - Although the UnicodeData.txt file referenced - here is part of the Unicode standard, it is - subject to change as new characters are added - to Unicode and errors are corrected in Unicode - revisions. As a result, it may be less stable - than might otherwise be implied by the - standards status of this specification. - - [UNICODE-SECURITY] Davis, M. and M. Suignard, "Unicode Security - Considerations", February 2006, - <http://www.unicode.org/reports/tr36/>. - - - - - - - - -Crispin Standards Track [Page 5] - -RFC 5051 i;unicode-casemap October 2007 - - -7. Informative References - - [BASIC] Newman, C., Duerst, M., and A. Gulbrandsen, - "i;basic - the Unicode Collation Algorithm", - Work in Progress, March 2007. - - [IMAP-SORT] Crispin, M. and K. Murchison, "Internet Message - Access Protocol - SORT and THREAD Extensions", - Work in Progress, September 2007. - -Author's Address - - Mark R. Crispin - Networks and Distributed Computing - University of Washington - 4545 15th Avenue NE - Seattle, WA 98105-4527 - - Phone: +1 (206) 543-5762 - EMail: MRC@CAC.Washington.EDU - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Crispin Standards Track [Page 6] - -RFC 5051 i;unicode-casemap October 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. - - - - - - - - - - - - -Crispin Standards Track [Page 7] - diff --git a/imap/docs/rfc/rfc5092.txt b/imap/docs/rfc/rfc5092.txt deleted file mode 100644 index ab87f350..00000000 --- a/imap/docs/rfc/rfc5092.txt +++ /dev/null @@ -1,1795 +0,0 @@ - - - - - - -Network Working Group A. Melnikov, Ed. -Request for Comments: 5092 Isode Ltd. -Obsoletes: 2192 C. Newman -Updates: 4467 Sun Microsystems -Category: Standards Track November 2007 - - - IMAP URL Scheme - -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 - - IMAP (RFC 3501) is a rich protocol for accessing remote message - stores. It provides an ideal mechanism for accessing public mailing - list archives as well as private and shared message stores. This - document defines a URL scheme for referencing objects on an IMAP - server. - - This document obsoletes RFC 2192. It also updates RFC 4467. - - - - - - - - - - - - - - - - - - - - - - - - - -Melnikov & Newman Standards Track [Page 1] - -RFC 5092 IMAP URL Scheme November 2007 - - -Table of Contents - - 1. Introduction ....................................................2 - 2. Conventions Used in This Document ...............................3 - 3. IMAP userinfo Component (iuserinfo) .............................4 - 3.1. IMAP Mailbox Naming Scope ..................................4 - 3.2. IMAP User Name and Authentication Mechanism ................4 - 3.3. Limitations of enc-user ....................................6 - 4. IMAP Server .....................................................7 - 5. Lists of Messages ...............................................7 - 6. A Specific Message or Message Part ..............................8 - 6.1. URLAUTH Authorized URL .....................................9 - 6.1.1. Concepts ............................................9 - 6.1.1.1. URLAUTH ....................................9 - 6.1.1.2. Mailbox Access Key .........................9 - 6.1.1.3. Authorized Access Identifier ...............9 - 6.1.1.4. Authorization Mechanism ...................10 - 6.1.1.5. Authorization Token .......................10 - 6.1.2. URLAUTH Extensions to IMAP URL .....................10 - 7. Relative IMAP URLs .............................................11 - 7.1. absolute-path References ..................................12 - 7.2. relative-path References ..................................12 - 8. Internationalization Considerations ............................13 - 9. Examples .......................................................13 - 9.1. Examples of Relative URLs .................................16 - 10. Security Considerations .......................................16 - 10.1. Security Considerations Specific to URLAUTH Authorized - URL ......................................................17 - 11. ABNF for IMAP URL Scheme ......................................17 - 12. IANA Considerations ...........................................21 - 12.1. IANA Registration of imap: URI Scheme ....................21 - 13. References ....................................................22 - 13.1. Normative References .....................................22 - 13.2. Informative References ...................................23 - Appendix A. Sample Code............................................24 - Appendix B. List of Changes since RFC 2192.........................30 - Appendix C. List of Changes since RFC 4467.........................31 - Appendix D. Acknowledgments........................................31 - -1. Introduction - - The IMAP URL scheme is used to designate IMAP servers, mailboxes, - messages, MIME bodies [MIME], and search programs on Internet hosts - accessible using the IMAP protocol over TCP. - - The IMAP URL follows the common Internet scheme syntax as defined in - [URI-GEN]. If :<port> is omitted, the port defaults to 143 (as - defined in Section 2.1 of [IMAP4]). - - - -Melnikov & Newman Standards Track [Page 2] - -RFC 5092 IMAP URL Scheme November 2007 - - - An absolute IMAP URL takes one of the following forms: - - imap://<iserver>[/] - - imap://<iserver>/<enc-mailbox>[<uidvalidity>][?<enc-search>] - - imap://<iserver>/<enc-mailbox>[<uidvalidity>]<iuid> - [<isection>][<ipartial>][<iurlauth>] - - The first form is used to refer to an IMAP server (see Section 4), - the second form refers to the contents of a mailbox or a set of - messages resulting from a search (see Section 5), and the final form - refers to a specific message or message part, and possibly a byte - range in that part (see Section 6). If [URLAUTH] extension is - supported, then the final form can have the <iurlauth> component (see - Section 6.1 for more details). - - The <iserver> component common to all types of absolute IMAP URLs has - the following syntax expressed in ABNF [ABNF]: - - [iuserinfo "@"] host [ ":" port ] - - The <iserver> component is the same as "authority" defined in - [URI-GEN]. The syntax and uses of the <iuserinfo> ("IMAP userinfo - component") are described in detail in Section 3. The syntax of - <host> and <port> is described in [URI-GEN]. - -2. Conventions Used in This Document - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - document are to be interpreted as described in RFC 2119 [KEYWORDS]. - - This document references many productions from [URI-GEN]. When the - document needs to emphasize IMAP URI-specific differences from [URI- - GEN] (i.e., for parts of IMAP URIs that have more restricted syntax - than generic URIs), it uses a non-terminal i<foo> to define an IMAP- - specific version of the non-terminal <foo> from [URI-GEN]. - - Note that the ABNF syntax shown in Section 11 is normative. Sections - 2-6 may use a less formal syntax that does not necessarily match the - normative ABNF shown in Section 11. If there are any differences - between the syntax shown in Sections 2-6 and Section 11, then the - syntax shown in Section 11 must be treated as authoritative. Non- - syntax requirements included in Sections 2-6 are, of course, - normative. - - - - - -Melnikov & Newman Standards Track [Page 3] - -RFC 5092 IMAP URL Scheme November 2007 - - -3. IMAP userinfo Component (iuserinfo) - - The <iuserinfo> component conforms to the generic syntax of - <userinfo> defined in [URI-GEN]. It has the following syntax - expressed in ABNF [ABNF]: - - enc-user [iauth] / [enc-user] iauth - - The meaning of the different parts is described in subsections of - this section. - -3.1. IMAP Mailbox Naming Scope - - The "enc-user" part of the "iuserinfo" component, if present, denotes - mailbox naming scope. If it is absent, the IMAP URL can only - reference mailboxes with globally unique names, i.e., mailboxes with - names that don't change depending on the user the client - authenticated as to the IMAP server. Note that not all IMAP - implementations support globally unique names. - - For example, a personal mailbox described by the following URL - <imap://michael@example.org/INBOX> is most likely different from a - personal mailbox described by <imap://bester@example.org/INBOX>, even - though both URLs use the same mailbox name. - -3.2. IMAP User Name and Authentication Mechanism - - The userinfo component (see [URI-GEN]) of an IMAP URI may contain an - IMAP user name (a.k.a. authorization identity [SASL], "enc-user") - and/or an authentication mechanism. (Note that the "enc-user" also - defines a mailbox naming scope as described in Section 3.1). The - IMAP user name and the authentication mechanism are used in the - "LOGIN" or "AUTHENTICATE" commands after making the connection to the - IMAP server. - - If no user name and no authentication mechanism are supplied, the - client MUST authenticate as anonymous to the server. If the server - advertises AUTH=ANONYMOUS IMAP capability, the client MUST use the - AUTHENTICATE command with ANONYMOUS [ANONYMOUS] SASL mechanism. If - SASL ANONYMOUS is not available, the (case-insensitive) user name - "anonymous" is used with the "LOGIN" command and the Internet email - address of the end user accessing the resource is supplied as the - password. The latter option is given in order to provide for - interoperability with deployed servers. - - Note that, as described in RFC 3501, the "LOGIN" command MUST NOT be - used when the IMAP server advertises the LOGINDISABLED capability. - - - - -Melnikov & Newman Standards Track [Page 4] - -RFC 5092 IMAP URL Scheme November 2007 - - - An authentication mechanism (as used by the IMAP AUTHENTICATE - command) can be expressed by adding ";AUTH=<enc-auth-type>" to the - end of the user name in an IMAP URL. When such an <enc-auth-type> is - indicated, the client SHOULD request appropriate credentials from - that mechanism and use the "AUTHENTICATE" command instead of the - "LOGIN" command. If no user name is specified, one MUST be obtained - from the mechanism or requested from the user/configuration as - appropriate. - - The string ";AUTH=*" indicates that the client SHOULD select an - appropriate authentication mechanism. (Though the '*' character in - this usage is not strictly a delimiter, it is being treated like a - sub-delim [URI-GEN] in this instance. It MUST NOT be percent-encoded - in this usage, as ";AUTH=%2A" will not match this production.) It - MAY use any mechanism listed in the response to the CAPABILITY - command (or CAPABILITY response code) or use an out-of-band security - service resulting in a PREAUTH connection. If no user name is - specified and no appropriate authentication mechanisms are available, - the client SHOULD fall back to anonymous login as described above. - The behavior prescribed in this section allows a URL that grants - read-write access to authorized users and read-only anonymous access - to other users. - - If a user name is included with no authentication mechanism, then - ";AUTH=*" is assumed. - - Clients must take care when resolving a URL that requires or requests - any sort of authentication, since URLs can easily come from untrusted - sources. Supplying authentication credentials to the wrong server - may compromise the security of the user's account; therefore, the - program resolving the URL should meet at least one of the following - criteria in this case: - - 1) The URL comes from a trusted source, such as a referral server - that the client has validated and trusts according to site policy. - Note that user entry of the URL may or may not count as a trusted - source, depending on the experience level of the user and site - policy. - - 2) Explicit local site policy permits the client to connect to the - server in the URL. For example, a company example.com may have a - site policy to trust all IMAP server names ending in example.com, - whereas such a policy would be unwise for example.edu where random - students can set up IMAP servers. - - 3) The user confirms that connecting to that domain name with the - specified credentials and/or mechanism is permitted. For example, - when using "LOGIN" or SASL PLAIN with Transport Layer Security - - - -Melnikov & Newman Standards Track [Page 5] - -RFC 5092 IMAP URL Scheme November 2007 - - - (TLS), the IMAP URL client presents a dialog box "Is it OK to send - your password to server "example.com"? Please be aware the owners - of example.com will be able to reuse your password to connect to - other servers on your behalf". - - 4) A mechanism is used that validates the server before passing - potentially compromising client credentials. For example, a site - has a designated TLS certificate used to certify site-trusted IMAP - server certificates, and this has been configured explicitly into - the IMAP URL client. Another example is use of a Simple - Authentication and Security Layer (SASL) mechanism such as - DIGEST-MD5 [DIGEST-MD5], which supports mutual authentication. - - 5) An authentication mechanism is used that will not reveal any - information to the server that could be used to compromise future - connections. Examples are SASL ANONYMOUS [ANONYMOUS] or GSSAPI - [GSSAPI]. - - URLs that do not include a user name but include an authentication - mechanism (";AUTH=<mech>") must be treated with extra care, since for - some <mech>s they are more likely to compromise the user's primary - account. A URL containing ";AUTH=*" must also be treated with extra - care since it might fall back on a weaker security mechanism. - Finally, clients are discouraged from using a plaintext password as a - fallback with ";AUTH=*" unless the connection has strong encryption. - - A program interpreting IMAP URLs MAY cache open connections to an - IMAP server for later reuse. If a URL contains a user name, only - connections authenticated as that user may be reused. If a URL does - not contain a user name or authentication mechanism, then only an - anonymous connection may be reused. - - Note that if unsafe or reserved characters such as " " (space) or ";" - are present in the user name or authentication mechanism, they MUST - be percent-encoded as described in [URI-GEN]. - -3.3. Limitations of enc-user - - As per Sections 3.1 and 3.2 of this document, the IMAP URI enc-user - has two purposes: - - 1) It provides context for user-specific mailbox paths such as - "INBOX" (Section 3.1). - - 2) It specifies that resolution of the URL requires logging in as - that user and limits use of that URL to only that user (Section - 3.2). - - - - -Melnikov & Newman Standards Track [Page 6] - -RFC 5092 IMAP URL Scheme November 2007 - - - An obvious limitation of using the same field for both purposes is - that the URL can be resolved only by the mailbox owner. In order to - avoid this restriction, implementations should use globally unique - mailbox names (see Section 3.1) whenever possible. - - Note: There is currently no general way in IMAP of learning a - globally unique name for a mailbox. However, by looking at the - NAMESPACE [NAMESPACE] command result, it is possible to determine - whether or not a mailbox name is globally unique. - - The URLAUTH component overrides the second purpose of the enc-user in - the IMAP URI and by default permits the URI to be resolved by any - user permitted by the <access> identifier. URLAUTH and <access> - identifier are described in Section 6.1. - -4. IMAP Server - - An IMAP URL referring to an IMAP server has the following form: - - imap://<iserver>[/] - - This URL type is frequently used to describe a location of an IMAP - server, both in referrals and in configuration. It may optionally - contain the <iuserinfo> component (see Sections 3 and 11). A program - interpreting this URL would issue the standard set of commands it - uses to present a view of the content of the IMAP server, as visible - to the user described by the "enc-user" part of the <iuserinfo> - component, if the "enc-user" part is specified. - -5. Lists of Messages - - An IMAP URL referring to a list of messages has the following form: - - imap://<iserver>/<enc-mailbox>[<uidvalidity>][?<enc-search>] - - The <enc-mailbox> field is used as the argument to the IMAP4 "SELECT" - or "EXAMINE" command. Note that if unsafe or reserved characters - such as " " (space), ";", or "?" are present in <enc-mailbox>, they - MUST be percent-encoded as described in [URI-GEN]. - - The <uidvalidity> field is optional. If it is present, it MUST be - the same as the value of IMAP4 UIDVALIDITY response code at the time - the URL was created. This MUST be used by the program interpreting - the IMAP URL to determine if the URL is stale. If the IMAP URL is - stale, then the program should behave as if the corresponding mailbox - doesn't exist. - - - - - -Melnikov & Newman Standards Track [Page 7] - -RFC 5092 IMAP URL Scheme November 2007 - - - Note that the <uidvalidity> field is a modifier to the <enc-mailbox>, - i.e., it is considered a part of the last "component" (as used in - [URI-GEN]) of the <enc-mailbox>. This is significant during relative - URI resolution. - - The "?<enc-search>" field is optional. If it is not present, the - program interpreting the URL will present the entire content of the - mailbox. - - If the "?<enc-search>" field is present, the program interpreting the - URL should use the contents of this field as arguments following an - IMAP4 SEARCH command. These arguments are likely to contain unsafe - characters such as " " (space) (which are likely to be present in the - <enc-search>). If unsafe characters are present, they MUST be - percent-encoded as described in [URI-GEN]. - - Note that quoted strings and non-synchronizing literals [LITERAL+] - are allowed in the <enc-search> content; however, synchronizing - literals are not allowed, as their presence would effectively mean - that the agent interpreting IMAP URLs needs to parse an <enc-search> - content, find all synchronizing literals, and perform proper command - continuation request handling (see Sections 4.3 and 7 of [IMAP4]). - -6. A Specific Message or Message Part - - An IMAP URL referring to a specific message or message part has the - following form: - - imap://<iserver>/<enc-mailbox>[<uidvalidity>]<iuid> - [<isection>][<ipartial>][<iurlauth>] - - The <enc-mailbox> and [uidvalidity] are as defined in Section 5 - above. - - If <uidvalidity> is present in this form, it SHOULD be used by the - program interpreting the URL to determine if the URL is stale. - - The <iuid> refers to an IMAP4 message Unique Identifier (UID), and it - SHOULD be used as the <set> argument to the IMAP4 "UID FETCH" - command. - - The <isection> field is optional. If not present, the URL refers to - the entire Internet message as returned by the IMAP command "UID - FETCH <uid> BODY.PEEK[]". If present, the URL refers to the object - returned by a "UID FETCH <uid> BODY.PEEK[<section>]" command. The - type of the object may be determined by using a "UID FETCH <uid> - BODYSTRUCTURE" command and locating the appropriate part in the - - - - -Melnikov & Newman Standards Track [Page 8] - -RFC 5092 IMAP URL Scheme November 2007 - - - resulting BODYSTRUCTURE. Note that unsafe characters in [isection] - MUST be percent-encoded as described in [URI-GEN]. - - The <ipartial> field is optional. If present, it effectively appends - "<<partial-range>>" to the end of the UID FETCH BODY.PEEK[<section>] - command constructed as described in the previous paragraph. In other - words, it allows the client to request a byte range of the - message/message part. - - The <iurlauth> field is described in detail in Section 6.1. - -6.1. URLAUTH Authorized URL - - URLAUTH authorized URLs are only supported by an IMAP server - advertising the URLAUTH IMAP capability [URLAUTH]. - -6.1.1. Concepts - -6.1.1.1. URLAUTH - - URLAUTH is a component, appended at the end of a URL, that conveys - authorization to access the data addressed by that URL. It contains - an authorized access identifier, an authorization mechanism name, and - an authorization token. The authorization token is generated from - the URL, the authorized access identifier, authorization mechanism - name, and a mailbox access key. - - Note: This specification only allows for the URLAUTH component in - IMAP URLs describing a message or its part. - -6.1.1.2. Mailbox Access Key - - The mailbox access key is an unpredictable, random string. To ensure - unpredictability, the random string with at least 128 bits of entropy - is generated by software or hardware (not by the human user). - - Each user has a table of mailboxes and an associated mailbox access - key for each mailbox. Consequently, the mailbox access key is per- - user and per-mailbox. In other words, two users sharing the same - mailbox each have a different mailbox access key for that mailbox, - and each mailbox accessed by a single user also has a different - mailbox access key. - -6.1.1.3. Authorized Access Identifier - - The authorized <access> identifier restricts use of the URLAUTH - authorized URL to certain users authorized on the server, as - described in Section 6.1.2. - - - -Melnikov & Newman Standards Track [Page 9] - -RFC 5092 IMAP URL Scheme November 2007 - - -6.1.1.4. Authorization Mechanism - - The authorization mechanism is the algorithm by which the URLAUTH is - generated and subsequently verified, using the mailbox access key. - -6.1.1.5. Authorization Token - - The authorization token is a deterministic string of at least 128 - bits that an entity with knowledge of the secret mailbox access key - and URL authorization mechanism can use to verify the URL. - -6.1.2. URLAUTH Extensions to IMAP URL - - A specific message or message part IMAP URL can optionally contain - ";EXPIRE=<datetime>" and/or ";URLAUTH=<access>:<mech>:<token>". - - When ";EXPIRE=<datetime>" is used, this indicates the latest date and - time that the URL is valid. After that date and time, the URL has - expired and server implementations MUST reject the URL. If - ";EXPIRE=<datetime>" is not used, the URL has no expiration, but can - still be revoked using the RESETKEY command [URLAUTH]. - - The URLAUTH takes the form ";URLAUTH=<access>:<mech>:<token>", and it - MUST be at the end of the URL. It is composed of three parts. The - <access> portion provides the authorized access identifiers that may - constrain the operations and users that are permitted to use this - URL. The <mech> portion provides the authorization mechanism used by - the IMAP server to generate the authorization token that follows. - The <token> portion provides the authorization token, which can be - generated using the GENURLAUTH command [URLAUTH]. - - The "submit+" <access> identifier prefix, followed by a userid, - indicates that only a userid authorized as a message submission - entity on behalf of the specified userid is permitted to use this - URL. The IMAP server does not validate the specified userid but does - validate that the IMAP session has an authorization identity that is - authorized as a message submission entity. The authorized message - submission entity MUST validate the userid prior to contacting the - IMAP server. - - The "user+" <access> identifier prefix, followed by a userid, - indicates that use of this URL is limited to IMAP sessions that are - logged in as the specified userid (that is, have authorization - identity as that userid). - - Note: If a SASL mechanism that provides both authorization and - authentication identifiers is used to authenticate to the IMAP - server, the "user+" <access> identifier MUST match the - - - -Melnikov & Newman Standards Track [Page 10] - -RFC 5092 IMAP URL Scheme November 2007 - - - authorization identifier. If the SASL mechanism can't transport - the authorization identifier, the "user+" <access> identifier MUST - match the authorization identifier derived from the authentication - identifier (see [SASL]). - - The "authuser" <access> identifier indicates that use of this URL is - limited to authenticated IMAP sessions that are logged in as any - non-anonymous user (that is, have authorization identity as a non- - anonymous user) of that IMAP server. To restate this: use of this - type of URL is prohibited to anonymous IMAP sessions, i.e., any - URLFETCH command containing this type of URL issued in an anonymous - session MUST return NIL in the URLFETCH response. - - The "anonymous" <access> identifier indicates that use of this URL is - not restricted by session authorization identity; that is, any IMAP - session in authenticated or selected state (as defined in [IMAP4]), - including anonymous sessions, may issue a URLFETCH [URLAUTH] using - this URL. - - The authorization token is represented as an ASCII-encoded - hexadecimal string, which is used to authorize the URL. The length - and the calculation of the authorization token depend upon the - mechanism used, but in all cases, the authorization token is at least - 128 bits (and therefore at least 32 hexadecimal digits). - - Example: - - <imap://joe@example.com/INBOX/;uid=20/;section=1.2;urlauth= - submit+fred:internal:91354a473744909de610943775f92038> - -7. Relative IMAP URLs - - Relative IMAP URLs are permitted and are resolved according to the - rules defined in [URI-GEN]. In particular, in IMAP URLs parameters - (such as ";uid=" or ";section=") are treated as part of the normal - path with respect to relative URL resolution. - - [URI-GEN] defines four forms of relative URLs: <inetwork-path>, - <iabsolute-path>, <irelative-path>, and <ipath-empty>. Their syntax - is defined in Section 11. - - A relative reference that begins with two slash characters is termed - a network-path reference (<inetwork-path>); such references are - rarely used, because in most cases they can be replaced with an - equivalent absolute URL. A relative reference that begins with a - single slash character is termed an absolute-path reference - (<iabsolute-path>; see also Section 7.1). A relative reference that - does not begin with a slash character is termed a relative-path - - - -Melnikov & Newman Standards Track [Page 11] - -RFC 5092 IMAP URL Scheme November 2007 - - - reference (<irelative-path>; see also Section 7.2). The final form - is <ipath-empty>, which is "same-document reference" (see Section 4.4 - of [URI-GEN]). - - The following observations about relative URLs are important: - - The <iauth> grammar element (which is a part of <iuserinfo>, which - is, in turn, a part of <iserver>; see Section 3) is considered part - of the user name for purposes of resolving relative IMAP URLs. This - means that unless a new user name/server specification is included in - the relative URL, the authentication mechanism is inherited from the - base IMAP URL. - - URLs always use "/" as the hierarchy delimiter for the purpose of - resolving paths in relative URLs. IMAP4 permits the use of any - hierarchy delimiter in mailbox names. For this reason, relative - mailbox paths will only work if the mailbox uses "/" as the hierarchy - delimiter. Relative URLs may be used on mailboxes that use other - delimiters, but in that case, the entire mailbox name MUST be - specified in the relative URL or inherited as a whole from the base - URL. - - If an IMAP server allows for mailbox names starting with "./" or - "../", ending with "/." or "/..", or containing sequences "/../" or - "/./", then such mailbox names MUST be percent-encoded as described - in [URI-GEN]. Otherwise, they would be misinterpreted as dot- - segments (see Section 3.3 of [URI-GEN]), which are processed - specially during the relative path resolution process. - -7.1. absolute-path References - - A relative reference that begins with a single slash character is - termed an absolute-path reference (see Section 4.2 of [URI-GEN]). If - an IMAP server permits mailbox names with a leading "/", then the - leading "/" MUST be percent-encoded as described in [URI-GEN]. - Otherwise, the produced absolute-path reference URI will be - misinterpreted as a network-path reference [URI-GEN] described by the - <inetwork-path> non-terminal. - -7.2. relative-path References - - A relative reference that does not begin with a slash character is - termed a relative-path reference [URI-GEN]. Implementations MUST NOT - generate or accept relative-path IMAP references. - - See also Section 4.2 of [URI-GEN] for restrictions on relative-path - references. - - - - -Melnikov & Newman Standards Track [Page 12] - -RFC 5092 IMAP URL Scheme November 2007 - - -8. Internationalization Considerations - - IMAP4, Section 5.1.3 [IMAP4] includes a convention for encoding non- - US-ASCII characters in IMAP mailbox names. Because this convention - is private to IMAP, it is necessary to convert IMAP's encoding to one - that can be more easily interpreted by a URL display program. For - this reason, IMAP's modified UTF-7 encoding for mailboxes MUST be - converted to UTF-8 [UTF-8]. Since 8-bit octets are not permitted in - URLs, the UTF-8 octets are percent-encoded as required by the URL - specification [URI-GEN], Section 2.1. Sample code is included in - Appendix A to demonstrate this conversion. - - IMAP user names are UTF-8 strings and MUST be percent-encoded as - required by the URL specification [URI-GEN], Section 2.1. - - Also note that IMAP SEARCH criteria can contain non-US-ASCII - characters. 8-bit octets in those strings MUST be percent-encoded as - required by the URL specification [URI-GEN], Section 2.1. - -9. Examples - - The following examples demonstrate how an IMAP4 client program might - translate various IMAP4 URLs into a series of IMAP4 commands. - Commands sent from the client to the server are prefixed with "C:", - and responses sent from the server to the client are prefixed with - "S:". - - The URL: - - <imap://minbari.example.org/gray-council;UIDVALIDITY=385759045/; - UID=20/;PARTIAL=0.1024> - - may result in the following client commands and server responses: - - <connect to minbari.example.org, port 143> - S: * OK [CAPABILITY IMAP4rev1 STARTTLS AUTH=ANONYMOUS] Welcome - C: A001 AUTHENTICATE ANONYMOUS - S: + - C: c2hlcmlkYW5AYmFieWxvbjUuZXhhbXBsZS5vcmc= - S: A001 OK Welcome sheridan@babylon5.example.org - C: A002 SELECT gray-council - <client verifies the UIDVALIDITY matches> - C: A003 UID FETCH 20 BODY.PEEK[]<0.1024> - - The URL: - - <imap://psicorp.example.org/~peter/%E6%97%A5%E6%9C%AC%E8%AA%9E/ - %E5%8F%B0%E5%8C%97> - - - -Melnikov & Newman Standards Track [Page 13] - -RFC 5092 IMAP URL Scheme November 2007 - - - may result in the following client commands: - - <connect to psicorp.example.org, port 143> - S: * OK [CAPABILITY IMAP4rev1 STARTTLS AUTH=CRAM-MD5] Welcome - C: A001 LOGIN ANONYMOUS bester@psycop.psicorp.example.org - C: A002 SELECT ~peter/&ZeVnLIqe-/&U,BTFw- - <commands the client uses for viewing the contents of - the mailbox> - - The URL: - - <imap://;AUTH=GSSAPI@minbari.example.org/gray-council/;uid=20/ - ;section=1.2> - - may result in the following client commands: - - <connect to minbari.example.org, port 143> - S: * OK Greetings - C: A000 CAPABILITY - S: * CAPABILITY IMAP4rev1 STARTTLS AUTH=GSSAPI - S: A000 OK - C: A001 AUTHENTICATE GSSAPI - <authentication exchange> - C: A002 SELECT gray-council - C: A003 UID FETCH 20 BODY.PEEK[1.2] - - If the following relative URL is located in that body part: - - <;section=1.4> - - this could result in the following client commands: - - C: A004 UID FETCH 20 (BODY.PEEK[1.2.MIME] - BODY.PEEK[1.MIME] - BODY.PEEK[HEADER.FIELDS (Content-Location)]) - <Client looks for Content-Location headers in - result. If no such headers, then it does the following> - C: A005 UID FETCH 20 BODY.PEEK[1.4] - - The URL: - - <imap://;AUTH=*@minbari.example.org/gray%20council? - SUBJECT%20shadows> - - - - - - - - -Melnikov & Newman Standards Track [Page 14] - -RFC 5092 IMAP URL Scheme November 2007 - - - could result in the following: - - <connect to minbari.example.org, port 143> - S: * OK Welcome - C: A001 CAPABILITY - S: * CAPABILITY IMAP4rev1 AUTH=DIGEST-MD5 - S: A001 OK - C: A002 AUTHENTICATE DIGEST-MD5 - <authentication exchange> - S: A002 OK user lennier authenticated - C: A003 SELECT "gray council" - ... - C: A004 SEARCH SUBJECT shadows - S: * SEARCH 8 10 13 14 15 16 - S: A004 OK SEARCH completed - C: A005 FETCH 8,10,13:16 ALL - ... - - In the example above, the client has implementation-dependent - choices. The authentication mechanism could be anything, including - PREAUTH. The final FETCH command could fetch more or less - information about the messages, depending on what it wishes to - display to the user. - - The URL: - - <imap://john;AUTH=*@minbari.example.org/babylon5/personel? - charset%20UTF-8%20SUBJECT%20%7B14+%7D%0D%0A%D0%98%D0%B2% - D0%B0%D0%BD%D0%BE%D0%B2%D0%B0> - - shows that 8-bit data can be sent using non-synchronizing literals - [LITERAL+]. This could result in the following: - - <connect to minbari.example.org, port 143> - S: * OK Hi there - C: A001 CAPABILITY - S: * CAPABILITY IMAP4rev1 LITERAL+ AUTH=DIGEST-MD5 - S: A001 OK - C: A002 AUTHENTICATE DIGEST-MD5 - <authentication exchange> - S: A002 OK user john authenticated - C: A003 SELECT babylon5/personel - ... - C: A004 SEARCH CHARSET UTF-8 SUBJECT {14+} - C: XXXXXXXXXXXXXX - S: * SEARCH 7 10 12 - S: A004 OK SEARCH completed - C: A005 FETCH 7,10,12 ALL - - - -Melnikov & Newman Standards Track [Page 15] - -RFC 5092 IMAP URL Scheme November 2007 - - - ... - - where XXXXXXXXXXXXXX is 14 bytes of UTF-8 encoded data as specified - in the URL above. - -9.1. Examples of Relative URLs - - The following absolute-path reference - - </foo/;UID=20/..> - - is the same as - - </foo> - - That is, both of them reference the mailbox "foo" located on the IMAP - server described by the corresponding Base URI. - - The following relative-path reference - - <;UID=20> - - references a message with UID in the mailbox specified by the Base - URI. - - The following edge case example demonstrates that the ;UIDVALIDITY= - modifier is a part of the mailbox name as far as relative URI - resolution is concerned: - - <..;UIDVALIDITY=385759045/;UID=20> - - In this example, ".." is not a dot-segment [URI-GEN]. - -10. Security Considerations - - Security considerations discussed in the IMAP specification [IMAP4] - and the URI specification [URI-GEN] are relevant. Security - considerations related to authenticated URLs are discussed in Section - 3.2 of this document. - - Many email clients store the plaintext password for later use after - logging into an IMAP server. Such clients MUST NOT use a stored - password in response to an IMAP URL without explicit permission from - the user to supply that password to the specified host name. - - Clients resolving IMAP URLs that wish to achieve data confidentiality - and/or integrity SHOULD use the STARTTLS command (if supported by the - - - - -Melnikov & Newman Standards Track [Page 16] - -RFC 5092 IMAP URL Scheme November 2007 - - - server) before starting authentication, or use a SASL mechanism, such - as GSSAPI, that provides a confidentiality security layer. - -10.1. Security Consideration Specific to URLAUTH Authorized URL - - The "user+<userid>" <access> identifier limits resolution of that URL - to a particular userid, whereas the "submit+<userid>" <access> - identifier is more general and simply requires that the session be - authorized by a user that has been granted a "submit" role within the - authentication system. Use of either of these mechanisms limits the - scope of the URL. An attacker who cannot authenticate using the - appropriate credentials cannot make use of the URL. - - The "authuser" and "anonymous" <access> identifiers do not have this - level of protection. These access identifiers are primarily useful - for public export of data from an IMAP server, without requiring that - it be copied to a web or anonymous FTP server. - - The decision to use the "authuser" <access> identifier should be made - with caution. An "authuser" <access> identifier can be used by any - authorized user of the IMAP server; therefore, use of this access - identifier should be limited to content that may be disclosed to any - authorized user of the IMAP server. - - The decision to use the "anonymous" <access> identifier should be - made with extreme caution. An "anonymous" <access> identifier can be - used by anyone; therefore, use of this access identifier should be - limited to content that may be disclosed to anyone. - -11. ABNF for IMAP URL Scheme - - Formal syntax is defined using ABNF [ABNF], extending the ABNF rules - in Section 9 of [IMAP4]. Elements not defined here can be found in - [ABNF], [IMAP4], [IMAPABNF], or [URI-GEN]. Strings are not case - sensitive, and free insertion of linear white space is not permitted. - - sub-delims-sh = "!" / "$" / "'" / "(" / ")" / - "*" / "+" / "," - ;; Same as [URI-GEN] sub-delims, - ;; but without ";", "&" and "=". - - uchar = unreserved / sub-delims-sh / pct-encoded - - achar = uchar / "&" / "=" - ;; Same as [URI-GEN] 'unreserved / sub-delims / - ;; pct-encoded', but ";" is disallowed. - - bchar = achar / ":" / "@" / "/" - - - -Melnikov & Newman Standards Track [Page 17] - -RFC 5092 IMAP URL Scheme November 2007 - - - enc-auth-type = 1*achar - ; %-encoded version of [IMAP4] "auth-type" - - enc-mailbox = 1*bchar - ; %-encoded version of [IMAP4] "mailbox" - - enc-search = 1*bchar - ; %-encoded version of [IMAPABNF] - ; "search-program". Note that IMAP4 - ; literals may not be used in - ; a "search-program", i.e., only - ; quoted or non-synchronizing - ; literals (if the server supports - ; LITERAL+ [LITERAL+]) are allowed. - - enc-section = 1*bchar - ; %-encoded version of [IMAP4] "section-spec" - - enc-user = 1*achar - ; %-encoded version of [IMAP4] authorization - ; identity or "userid". - - imapurl = "imap://" iserver ipath-query - ; Defines an absolute IMAP URL - - ipath-query = ["/" [ icommand ]] - ; Corresponds to "path-abempty [ "?" query ]" - ; in [URI-GEN] - - Generic syntax for relative URLs is defined in Section 4.2 of - [URI-GEN]. For ease of implementation, the relative IMAP URL syntax - is defined below: - - imapurl-rel = inetwork-path - - / iabsolute-path - / irelative-path - / ipath-empty - - inetwork-path = "//" iserver ipath-query - ; Corresponds to '"//" authority path-abempty - ; [ "?" query ]' in [URI-GEN] - - iabsolute-path = "/" [ icommand ] - ; icommand, if present, MUST NOT start with '/'. - ; - ; Corresponds to 'path-absolute [ "?" query ]' - ; in [URI-GEN] - - - -Melnikov & Newman Standards Track [Page 18] - -RFC 5092 IMAP URL Scheme November 2007 - - - irelative-path = imessagelist / - imsg-or-part - ; Corresponds to 'path-noscheme [ "?" query ]' - ; in [URI-GEN] - - imsg-or-part = ( imailbox-ref "/" iuid-only ["/" isection-only] - ["/" ipartial-only] ) / - ( iuid-only ["/" isection-only] - ["/" ipartial-only] ) / - ( isection-only ["/" ipartial-only] ) / - ipartial-only - - ipath-empty = 0<pchar> - ; Zero characters. - ; The same-document reference. - - The following three rules are only used in the presence of the IMAP - [URLAUTH] extension: - - authimapurl = "imap://" iserver "/" imessagepart - ; Same as "imapurl" when "[icommand]" is - ; "imessagepart" - - authimapurlfull = authimapurl iurlauth - ; Same as "imapurl" when "[icommand]" is - ; "imessagepart iurlauth" - - authimapurlrump = authimapurl iurlauth-rump - - - enc-urlauth = 32*HEXDIG - - iurlauth = iurlauth-rump iua-verifier - - iua-verifier = ":" uauth-mechanism ":" enc-urlauth - - iurlauth-rump = [expire] ";URLAUTH=" access - - access = ("submit+" enc-user) / ("user+" enc-user) / - "authuser" / "anonymous" - - expire = ";EXPIRE=" date-time - ; date-time is defined in [DATETIME] - - uauth-mechanism = "INTERNAL" / 1*(ALPHA / DIGIT / "-" / ".") - ; Case-insensitive. - ; New mechanisms MUST be registered with IANA. - - - - -Melnikov & Newman Standards Track [Page 19] - -RFC 5092 IMAP URL Scheme November 2007 - - - iauth = ";AUTH=" ( "*" / enc-auth-type ) - - icommand = imessagelist / - imessagepart [iurlauth] - - imailbox-ref = enc-mailbox [uidvalidity] - - imessagelist = imailbox-ref [ "?" enc-search ] - ; "enc-search" is [URI-GEN] "query". - - imessagepart = imailbox-ref iuid [isection] [ipartial] - - ipartial = "/" ipartial-only - - ipartial-only = ";PARTIAL=" partial-range - - isection = "/" isection-only - - isection-only = ";SECTION=" enc-section - - iserver = [iuserinfo "@"] host [ ":" port ] - ; This is the same as "authority" defined - ; in [URI-GEN]. See [URI-GEN] for "host" - ; and "port" definitions. - - iuid = "/" iuid-only - - iuid-only = ";UID=" nz-number - ; See [IMAP4] for "nz-number" definition - - iuserinfo = enc-user [iauth] / [enc-user] iauth - ; conforms to the generic syntax of - ; "userinfo" as defined in [URI-GEN]. - - partial-range = number ["." nz-number] - ; partial FETCH. The first number is - ; the offset of the first byte, - ; the second number is the length of - ; the fragment. - - uidvalidity = ";UIDVALIDITY=" nz-number - ; See [IMAP4] for "nz-number" definition - - - - - - - - - -Melnikov & Newman Standards Track [Page 20] - -RFC 5092 IMAP URL Scheme November 2007 - - -12. IANA Considerations - - IANA has updated the "imap" definition in the "Uniform Resource - Identifier scheme registry" to point to this document. - - The registration template (as per [URI-REG]) is specified in Section - 12.1 of this document. - -12.1. IANA Registration of imap: URI Scheme - - This section provides the information required to register the imap: - URI scheme. - - URI scheme name: imap - - Status: permanent - - URI scheme syntax: - - See Section 11 of [RFC5092]. - - URI scheme semantics: - - The imap: URI scheme is used to designate IMAP servers, mailboxes, - messages, MIME bodies [MIME] and their parts, and search programs - on Internet hosts accessible using the IMAP protocol. - - There is no MIME type associated with this URI. - - Encoding considerations: - - See Section 8 of [RFC5092]. - - Applications/protocols that use this URI scheme name: - - The imap: URI is intended to be used by applications that might - need access to an IMAP mailstore. Such applications may include - (but are not limited to) IMAP-capable web browsers; IMAP clients - that wish to access a mailbox, message, or edit a message on the - server using [CATENATE]; [SUBMIT] clients and servers that are - requested to assemble a complete message on submission using - [BURL]. - - Interoperability considerations: - - A widely deployed IMAP client Netscape Mail (and possibly - Mozilla/Thunderbird/Seamonkey) uses a different imap: scheme - internally. - - - -Melnikov & Newman Standards Track [Page 21] - -RFC 5092 IMAP URL Scheme November 2007 - - - Security considerations: - - See Security Considerations (Section 10) of [RFC5092]. - - Contact: - - Alexey Melnikov <alexey.melnikov@isode.com> - - Author/Change controller: - - IESG - - References: - - [RFC5092] and [IMAP4]. - -13. References - -13.1. 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. - - [IMAPABNF] Melnikov, A. and C. Daboo, "Collected Extensions to - IMAP4 ABNF", RFC 4466, April 2006. - - [ABNF] Crocker, D., Ed., and P. Overell, "Augmented BNF for - Syntax Specifications: ABNF", RFC 4234, October 2005. - - [MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail - Extensions (MIME) Part One: Format of Internet Message - Bodies", RFC 2045, November 1996. - - [URI-GEN] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform - Resource Identifier (URI): Generic Syntax", STD 66, RFC - 3986, January 2005. - - [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO - 10646", STD 63, RFC 3629, November 2003. - - [NAMESPACE] Gahrns, M. and C. Newman, "IMAP4 Namespace", RFC 2342, - May 1998. - - [LITERAL+] Myers, J., "IMAP4 non-synchronizing literals", RFC 2088, - January 1997. - - - -Melnikov & Newman Standards Track [Page 22] - -RFC 5092 IMAP URL Scheme November 2007 - - - [ANONYMOUS] Zeilenga, K., "Anonymous Simple Authentication and - Security Layer (SASL) Mechanism", RFC 4505, June 2006. - - [DATETIME] Klyne, G. and C. Newman, "Date and Time on the Internet: - Timestamps", RFC 3339, July 2002. - - [URLAUTH] Crispin, M., "Internet Message Access Protocol (IMAP) - - URLAUTH Extension", RFC 4467, May 2006. - -13.2. Informative References - - [SUBMIT] Gellens, R. and J. Klensin, "Message Submission for - Mail", RFC 4409, April 2006. - - [BURL] Newman, C., "Message Submission BURL Extension", RFC - 4468, May 2006. - - [CATENATE] Resnick, P., "Internet Message Access Protocol (IMAP) - CATENATE Extension", RFC 4469, April 2006. - - [SASL] Melnikov, A., Ed., and K. Zeilenga, Ed., "Simple - Authentication and Security Layer (SASL)", RFC 4422, - June 2006. - - [GSSAPI] Melnikov, A., Ed., "The Kerberos V5 ("GSSAPI") Simple - Authentication and Security Layer (SASL) Mechanism", RFC - 4752, November 2006. - - [DIGEST-MD5] Leach, P. and C. Newman, "Using Digest Authentication as - a SASL Mechanism", RFC 2831, May 2000. - - [URI-REG] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and - Registration Procedures for New URI Schemes", BCP 115, - RFC 4395, February 2006. - - - - - - - - - - - - - - - - - -Melnikov & Newman Standards Track [Page 23] - -RFC 5092 IMAP URL Scheme November 2007 - - -Appendix A. Sample Code - - Here is sample C source code to convert between URL paths and IMAP - mailbox names, taking into account mapping between IMAP's modified - UTF-7 [IMAP4] and hex-encoded UTF-8, which is more appropriate for - URLs. This code has not been rigorously tested nor does it - necessarily behave reasonably with invalid input, but it should serve - as a useful example. This code just converts the mailbox portion of - the URL and does not deal with parameters, query, or server - components of the URL. - -/* Copyright (C) The IETF Trust (2007). This version of - sample C code is part of RFC XXXX; see the RFC itself - for full legal notices. - - Regarding this sample C code (or any portion of it), the authors - make no guarantees and are not responsible for any damage - resulting from its use. The authors grant irrevocable permission - to anyone to use, modify, and distribute it in any way that does - not diminish the rights of anyone else to use, modify, and - distribute it, provided that redistributed derivative works do - not contain misleading author or version information. - - Derivative works need not be licensed under similar terms. - */ - -#include <stdio.h> -#include <string.h> - -/* hexadecimal lookup table */ -static const char hex[] = "0123456789ABCDEF"; - -#define XX 127 -/* - * Table for decoding hexadecimal in %encoding - */ -static const char index_hex[256] = { - XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, - XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, - XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, - 0, 1, 2, 3, 4, 5, 6, 7, 8, 9,XX,XX, XX,XX,XX,XX, - XX,10,11,12, 13,14,15,XX, XX,XX,XX,XX, XX,XX,XX,XX, - XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, - XX,10,11,12, 13,14,15,XX, XX,XX,XX,XX, XX,XX,XX,XX, - XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, - XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, - XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, - XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, - - - -Melnikov & Newman Standards Track [Page 24] - -RFC 5092 IMAP URL Scheme November 2007 - - - XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, - XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, - XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, - XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, - XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, -}; -#define HEXCHAR(c) (index_hex[(unsigned char)(c)]) - -/* "gen-delims" excluding "/" but including "%" */ -#define GENERAL_DELIMS_NO_SLASH ":?#[]@" "%" - -/* "gen-delims" (excluding "/", but including "%") - plus subset of "sub-delims" */ -#define GENERAL_UNSAFE_NO_SLASH GENERAL_DELIMS_NO_SLASH ";&=+" -#define OTHER_UNSAFE " \"<>\\^`{|}" - -/* URL unsafe printable characters */ -static const char mailbox_url_unsafe[] = GENERAL_UNSAFE_NO_SLASH - OTHER_UNSAFE; - -/* UTF7 modified base64 alphabet */ -static const char base64chars[] = - "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+,"; - -#define UNDEFINED 64 - -/* UTF16 definitions */ -#define UTF16MASK 0x03FFUL -#define UTF16SHIFT 10 -#define UTF16BASE 0x10000UL -#define UTF16HIGHSTART 0xD800UL -#define UTF16HIGHEND 0xDBFFUL -#define UTF16LOSTART 0xDC00UL -#define UTF16LOEND 0xDFFFUL - -/* Convert an IMAP mailbox to a URL path - * dst needs to have roughly 4 times the storage space of src - * Hex encoding can triple the size of the input - * UTF-7 can be slightly denser than UTF-8 - * (worst case: 8 octets UTF-7 becomes 9 octets UTF-8) - */ -void MailboxToURL(char *dst, char *src) -{ - unsigned char c, i, bitcount; - unsigned long ucs4, utf16, bitbuf; - unsigned char base64[256], utf8[6]; - - /* initialize modified base64 decoding table */ - - - -Melnikov & Newman Standards Track [Page 25] - -RFC 5092 IMAP URL Scheme November 2007 - - - memset(base64, UNDEFINED, sizeof (base64)); - for (i = 0; i < sizeof (base64chars); ++i) { - base64[(int) base64chars[i]] = i; - } - - /* loop until end of string */ - while (*src != '\0') { - c = *src++; - /* deal with literal characters and &- */ - if (c != '&' || *src == '-') { - /* NB: There are no "URL safe" characters after the '~' */ - if (c < ' ' || c > '~' || - strchr(mailbox_url_unsafe, c) != NULL) { - /* hex encode if necessary */ - dst[0] = '%'; - dst[1] = hex[c >> 4]; - dst[2] = hex[c & 0x0f]; - dst += 3; - } else { - /* encode literally */ - *dst++ = c; - } - /* skip over the '-' if this is an &- sequence */ - if (c == '&') ++src; - - } else { - /* convert modified UTF-7 -> UTF-16 -> UCS-4 -> UTF-8 -> HEX */ - bitbuf = 0; - bitcount = 0; - ucs4 = 0; - while ((c = base64[(unsigned char) *src]) != UNDEFINED) { - ++src; - bitbuf = (bitbuf << 6) | c; - bitcount += 6; - /* enough bits for a UTF-16 character? */ - if (bitcount >= 16) { - bitcount -= 16; - utf16 = (bitcount ? bitbuf >> bitcount - : bitbuf) & 0xffff; - /* convert UTF16 to UCS4 */ - if - (utf16 >= UTF16HIGHSTART && utf16 <= UTF16HIGHEND) { - ucs4 = (utf16 - UTF16HIGHSTART) << UTF16SHIFT; - continue; - } else if - (utf16 >= UTF16LOSTART && utf16 <= UTF16LOEND) { - ucs4 += utf16 - UTF16LOSTART + UTF16BASE; - } else { - - - -Melnikov & Newman Standards Track [Page 26] - -RFC 5092 IMAP URL Scheme November 2007 - - - ucs4 = utf16; - } - /* convert UTF-16 range of UCS4 to UTF-8 */ - if (ucs4 <= 0x7fUL) { - utf8[0] = (unsigned char) ucs4; - i = 1; - } else if (ucs4 <= 0x7ffUL) { - utf8[0] = 0xc0 | (unsigned char) (ucs4 >> 6); - utf8[1] = 0x80 | (unsigned char) (ucs4 & 0x3f); - i = 2; - } else if (ucs4 <= 0xffffUL) { - utf8[0] = 0xe0 | (unsigned char) (ucs4 >> 12); - utf8[1] = 0x80 | (unsigned char) ((ucs4 >> 6) & 0x3f); - utf8[2] = 0x80 | (unsigned char) (ucs4 & 0x3f); - i = 3; - } else { - utf8[0] = 0xf0 | (unsigned char) (ucs4 >> 18); - utf8[1] = 0x80 | (unsigned char) ((ucs4 >> 12) & 0x3f); - utf8[2] = 0x80 | (unsigned char) ((ucs4 >> 6) & 0x3f); - utf8[3] = 0x80 | (unsigned char) (ucs4 & 0x3f); - i = 4; - } - /* convert utf8 to hex */ - for (c = 0; c < i; ++c) { - dst[0] = '%'; - dst[1] = hex[utf8[c] >> 4]; - dst[2] = hex[utf8[c] & 0x0f]; - dst += 3; - } - } - } - /* skip over trailing '-' in modified UTF-7 encoding */ - if (*src == '-') ++src; - } - } - /* terminate destination string */ - *dst = '\0'; -} - -/* Convert hex coded UTF-8 URL path to modified UTF-7 IMAP mailbox - * dst should be about twice the length of src to deal with non-hex - * coded URLs - */ -int URLtoMailbox(char *dst, char *src) -{ - unsigned int utf8pos = 0; - unsigned int utf8total, i, c, utf7mode, bitstogo, utf16flag; - unsigned long ucs4 = 0, bitbuf = 0; - - - -Melnikov & Newman Standards Track [Page 27] - -RFC 5092 IMAP URL Scheme November 2007 - - - utf7mode = 0; /* is the output UTF7 currently in base64 mode? */ - utf8total = 0; /* how many octets is the current input UTF-8 char; - 0 == between characters */ - bitstogo = 0; /* bits that need to be encoded into base64; if - bitstogo != 0 then utf7mode == 1 */ - while ((c = (unsigned char)*src) != '\0') { - ++src; - /* undo hex-encoding */ - if (c == '%' && src[0] != '\0' && src[1] != '\0') { - c = HEXCHAR(src[0]); - i = HEXCHAR(src[1]); - if (c == XX || i == XX) { - return 0; - } else { - c = (char)((c << 4) | i); - } - src += 2; - } - /* normal character? */ - if (c >= ' ' && c <= '~') { - /* switch out of UTF-7 mode */ - if (utf7mode) { - if (bitstogo) { - *dst++ = base64chars[(bitbuf << (6 - bitstogo)) & 0x3F]; - } - *dst++ = '-'; - utf7mode = 0; - bitstogo = bitbuf = 0; - } - *dst++ = c; - /* encode '&' as '&-' */ - if (c == '&') { - *dst++ = '-'; - } - continue; - } - /* switch to UTF-7 mode */ - if (!utf7mode) { - *dst++ = '&'; - utf7mode = 1; - } - /* Encode US-ASCII characters as themselves */ - if (c < 0x80) { - ucs4 = c; - utf8total = 1; - } else if (utf8total) { - /* this is a subsequent octet of a multi-octet character */ - /* save UTF8 bits into UCS4 */ - - - -Melnikov & Newman Standards Track [Page 28] - -RFC 5092 IMAP URL Scheme November 2007 - - - ucs4 = (ucs4 << 6) | (c & 0x3FUL); - if (++utf8pos < utf8total) { - continue; - } - } else { - /* this is the first octet of a multi-octet character */ - utf8pos = 1; - if (c < 0xE0) { - utf8total = 2; - ucs4 = c & 0x1F; - } else if (c < 0xF0) { - utf8total = 3; - ucs4 = c & 0x0F; - } else { - /* NOTE: can't convert UTF8 sequences longer than 4 */ - utf8total = 4; - ucs4 = c & 0x03; - } - continue; - } - /* Finished with UTF-8 character. Make sure it isn't an - overlong sequence. If it is, return failure. */ - if ((ucs4 < 0x80 && utf8total > 1) || - (ucs4 < 0x0800 && utf8total > 2) || - (ucs4 < 0x00010000 && utf8total > 3) || - (ucs4 < 0x00200000 && utf8total > 4) || - (ucs4 < 0x04000000 && utf8total > 5) || - (ucs4 < 0x80000000 && utf8total > 6)) { - return 0; - } - /* loop to split ucs4 into two utf16 chars if necessary */ - utf8total = 0; - do { - if (ucs4 >= UTF16BASE) { - ucs4 -= UTF16BASE; - bitbuf = (bitbuf << 16) | ((ucs4 >> UTF16SHIFT) - + UTF16HIGHSTART); - ucs4 = (ucs4 & UTF16MASK) + UTF16LOSTART; - utf16flag = 1; - } else { - bitbuf = (bitbuf << 16) | ucs4; - utf16flag = 0; - } - bitstogo += 16; - /* spew out base64 */ - while (bitstogo >= 6) { - bitstogo -= 6; - *dst++ = base64chars[(bitstogo ? (bitbuf >> bitstogo) - - - -Melnikov & Newman Standards Track [Page 29] - -RFC 5092 IMAP URL Scheme November 2007 - - - : bitbuf) - & 0x3F]; - } - } while (utf16flag); - } - /* if in UTF-7 mode, finish in ASCII */ - if (utf7mode) { - if (bitstogo) { - *dst++ = base64chars[(bitbuf << (6 - bitstogo)) & 0x3F]; - } - *dst++ = '-'; - } - /* tie off string */ - *dst = '\0'; - return 1; -} - -Appendix B. List of Changes since RFC 2192 - - Updated boilerplate, list of editor's, etc. - Updated references. - Updated ABNF not to use _, to use SP instead of SPACE, etc. - Updated example domains to use example.org. - Fixed ABNF error in "imessagelist" non-terminal. - Updated ABNF, due to changes in RFC 3501, RFC 4466, and RFC 3986. - Renamed "iuserauth" non-terminal to <iuserinfo>. - Clarified that the userinfo component describes both authorization - identity and mailbox naming scope. - Allow for non-synchronizing literals in "enc-search". - Added "ipartial" specifier that denotes a partial FETCH. - Moved URLAUTH text from RFC 4467 to this document. - Updated ABNF for the whole server to allow missing trailing "/" - (e.g., "imap://imap.example.com" is now valid and is the same as - "imap://imap.example.com/"). - Clarified how relative-path references are constructed. - Added more examples demonstrating relative-path references. - Added rules for relative URLs and restructured ABNF as the result. - Removed text on use of relative URLs in MHTML. - Added examples demonstrating security considerations when resolving - URLs. - Recommend usage of STARTTLS/SASL security layer to protect - confidential data. - Removed some advices about connection reuse that were incorrect. - Removed URLs referencing a list of mailboxes, as this feature - hasn't seen any deployments. - Clarified that user name "anonymous" is case-insensitive. - - - - - -Melnikov & Newman Standards Track [Page 30] - -RFC 5092 IMAP URL Scheme November 2007 - - -Appendix C. List of Changes since RFC 4467 - - Renamed <mechanism> to <uauth-mechanism>. Restructured ABNF. - -Appendix D. Acknowledgments - - Text describing URLAUTH was lifted from [URLAUTH] by Mark Crispin. - - Stephane H. Maes contributed some ideas to this document; he also - co-edited early versions of this document. - - The editors would like to thank Mark Crispin, Ken Murchison, Ted - Hardie, Zoltan Ordogh, Dave Cridland, Kjetil Torgrim Homme, Lisa - Dusseault, Spencer Dawkins, Filip Navara, Shawn M. Emery, Sam - Hartman, Russ Housley, and Lars Eggert for the time they devoted to - reviewing this document and/or for the comments received. - -Authors' Addresses - - Chris Newman (Author/Editor) - Sun Microsystems - 3401 Centrelake Dr., Suite 410 - Ontario, CA 91761 - EMail: chris.newman@sun.com - - Alexey Melnikov (Editor) - Isode Limited - 5 Castle Business Village - 36 Station Road - Hampton, Middlesex - TW12 2BX, UK - EMail: Alexey.Melnikov@isode.com - URI: http://www.melnikov.ca/ - - - - - - - - - - - - - - - - - - -Melnikov & Newman Standards Track [Page 31] - -RFC 5092 IMAP URL Scheme November 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. - - - - - - - - - - - - -Melnikov & Newman Standards Track [Page 32] - diff --git a/imap/docs/rfc/rfc5161.txt b/imap/docs/rfc/rfc5161.txt deleted file mode 100644 index 13bbbf74..00000000 --- a/imap/docs/rfc/rfc5161.txt +++ /dev/null @@ -1,395 +0,0 @@ - - - - - - -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/imap/docs/rfc/rfc5162.txt b/imap/docs/rfc/rfc5162.txt deleted file mode 100644 index 305c54fb..00000000 --- a/imap/docs/rfc/rfc5162.txt +++ /dev/null @@ -1,1291 +0,0 @@ - - - - - - -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:<maxuid>", where <maxuid> 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 <minmodseq>, - where <minmodseq> 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 <UID set, mod-sequence> pairs. - <UID set> can be represented as a sequence of <min UID, max UID> - 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 <min - UID, max UID, mod-sequence> 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/imap/docs/rfc/rfc5234.txt b/imap/docs/rfc/rfc5234.txt deleted file mode 100644 index 42bb44ca..00000000 --- a/imap/docs/rfc/rfc5234.txt +++ /dev/null @@ -1,899 +0,0 @@ - - - - - - -Network Working Group D. Crocker, Ed. -Request for Comments: 5234 Brandenburg InternetWorking -STD: 68 P. Overell -Obsoletes: 4234 THUS plc. -Category: Standards Track January 2008 - - - Augmented BNF for Syntax Specifications: ABNF - -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 technical specifications often need to define a formal - syntax. Over the years, a modified version of Backus-Naur Form - (BNF), called Augmented BNF (ABNF), has been popular among many - Internet specifications. The current specification documents ABNF. - It balances compactness and simplicity with reasonable - representational power. The differences between standard BNF and - ABNF involve naming rules, repetition, alternatives, order- - independence, and value ranges. This specification also supplies - additional rule definitions and encoding for a core lexical analyzer - of the type common to several Internet specifications. - - - - - - - - - - - - - - - - - - - - - - -Crocker & Overell Standards Track [Page 1] - -RFC 5234 ABNF January 2008 - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. Rule Definition . . . . . . . . . . . . . . . . . . . . . . . 3 - 2.1. Rule Naming . . . . . . . . . . . . . . . . . . . . . . . 3 - 2.2. Rule Form . . . . . . . . . . . . . . . . . . . . . . . . 4 - 2.3. Terminal Values . . . . . . . . . . . . . . . . . . . . . 4 - 2.4. External Encodings . . . . . . . . . . . . . . . . . . . . 6 - 3. Operators . . . . . . . . . . . . . . . . . . . . . . . . . . 6 - 3.1. Concatenation: Rule1 Rule2 . . . . . . . . . . . . . . . 6 - 3.2. Alternatives: Rule1 / Rule2 . . . . . . . . . . . . . . . 7 - 3.3. Incremental Alternatives: Rule1 =/ Rule2 . . . . . . . . . 7 - 3.4. Value Range Alternatives: %c##-## . . . . . . . . . . . . 8 - 3.5. Sequence Group: (Rule1 Rule2) . . . . . . . . . . . . . . 8 - 3.6. Variable Repetition: *Rule . . . . . . . . . . . . . . . 9 - 3.7. Specific Repetition: nRule . . . . . . . . . . . . . . . 9 - 3.8. Optional Sequence: [RULE] . . . . . . . . . . . . . . . . 9 - 3.9. Comment: ; Comment . . . . . . . . . . . . . . . . . . . 9 - 3.10. Operator Precedence . . . . . . . . . . . . . . . . . . . 10 - 4. ABNF Definition of ABNF . . . . . . . . . . . . . . . . . . . 10 - 5. Security Considerations . . . . . . . . . . . . . . . . . . . 12 - 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 - 6.1. Normative References . . . . . . . . . . . . . . . . . . . 12 - 6.2. Informative References . . . . . . . . . . . . . . . . . . 12 - Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 13 - Appendix B. Core ABNF of ABNF . . . . . . . . . . . . . . . . . . 13 - B.1. Core Rules . . . . . . . . . . . . . . . . . . . . . . . . 13 - B.2. Common Encoding . . . . . . . . . . . . . . . . . . . . . 15 - - - - - - - - - - - - - - - - - - - - - - - -Crocker & Overell Standards Track [Page 2] - -RFC 5234 ABNF January 2008 - - -1. Introduction - - Internet technical specifications often need to define a formal - syntax and are free to employ whatever notation their authors deem - useful. Over the years, a modified version of Backus-Naur Form - (BNF), called Augmented BNF (ABNF), has been popular among many - Internet specifications. It balances compactness and simplicity with - reasonable representational power. In the early days of the Arpanet, - each specification contained its own definition of ABNF. This - included the email specifications, [RFC733] and then [RFC822], which - came to be the common citations for defining ABNF. The current - document separates those definitions to permit selective reference. - Predictably, it also provides some modifications and enhancements. - - The differences between standard BNF and ABNF involve naming rules, - repetition, alternatives, order-independence, and value ranges. - Appendix B supplies rule definitions and encoding for a core lexical - analyzer of the type common to several Internet specifications. It - is provided as a convenience and is otherwise separate from the meta - language defined in the body of this document, and separate from its - formal status. - -2. Rule Definition - -2.1. Rule Naming - - The name of a rule is simply the name itself, that is, a sequence of - characters, beginning with an alphabetic character, and followed by a - combination of alphabetics, digits, and hyphens (dashes). - - NOTE: - - Rule names are case insensitive. - - The names <rulename>, <Rulename>, <RULENAME>, and <rUlENamE> all - refer to the same rule. - - Unlike original BNF, angle brackets ("<", ">") are not required. - However, angle brackets may be used around a rule name whenever their - presence facilitates in discerning the use of a rule name. This is - typically restricted to rule name references in free-form prose, or - to distinguish partial rules that combine into a string not separated - by white space, such as shown in the discussion about repetition, - below. - - - - - - - -Crocker & Overell Standards Track [Page 3] - -RFC 5234 ABNF January 2008 - - -2.2. Rule Form - - A rule is defined by the following sequence: - - name = elements crlf - - where <name> is the name of the rule, <elements> is one or more rule - names or terminal specifications, and <crlf> is the end-of-line - indicator (carriage return followed by line feed). The equal sign - separates the name from the definition of the rule. The elements - form a sequence of one or more rule names and/or value definitions, - combined according to the various operators defined in this document, - such as alternative and repetition. - - For visual ease, rule definitions are left aligned. When a rule - requires multiple lines, the continuation lines are indented. The - left alignment and indentation are relative to the first lines of the - ABNF rules and need not match the left margin of the document. - -2.3. Terminal Values - - Rules resolve into a string of terminal values, sometimes called - characters. In ABNF, a character is merely a non-negative integer. - In certain contexts, a specific mapping (encoding) of values into a - character set (such as ASCII) will be specified. - - Terminals are specified by one or more numeric characters, with the - base interpretation of those characters indicated explicitly. The - following bases are currently defined: - - b = binary - - d = decimal - - x = hexadecimal - - Hence: - - CR = %d13 - - CR = %x0D - - respectively specify the decimal and hexadecimal representation of - [US-ASCII] for carriage return. - - - - - - - -Crocker & Overell Standards Track [Page 4] - -RFC 5234 ABNF January 2008 - - - A concatenated string of such values is specified compactly, using a - period (".") to indicate a separation of characters within that - value. Hence: - - CRLF = %d13.10 - - ABNF permits the specification of literal text strings directly, - enclosed in quotation marks. Hence: - - command = "command string" - - Literal text strings are interpreted as a concatenated set of - printable characters. - - NOTE: - - ABNF strings are case insensitive and the character set for these - strings is US-ASCII. - - Hence: - - rulename = "abc" - - and: - - rulename = "aBc" - - will match "abc", "Abc", "aBc", "abC", "ABc", "aBC", "AbC", and - "ABC". - - To specify a rule that is case sensitive, specify the characters - individually. - - For example: - - rulename = %d97 %d98 %d99 - - or - - rulename = %d97.98.99 - - will match only the string that comprises only the lowercase - characters, abc. - - - - - - - - -Crocker & Overell Standards Track [Page 5] - -RFC 5234 ABNF January 2008 - - -2.4. External Encodings - - External representations of terminal value characters will vary - according to constraints in the storage or transmission environment. - Hence, the same ABNF-based grammar may have multiple external - encodings, such as one for a 7-bit US-ASCII environment, another for - a binary octet environment, and still a different one when 16-bit - Unicode is used. Encoding details are beyond the scope of ABNF, - although Appendix B provides definitions for a 7-bit US-ASCII - environment as has been common to much of the Internet. - - By separating external encoding from the syntax, it is intended that - alternate encoding environments can be used for the same syntax. - -3. Operators - -3.1. Concatenation: Rule1 Rule2 - - A rule can define a simple, ordered string of values (i.e., a - concatenation of contiguous characters) by listing a sequence of rule - names. For example: - - foo = %x61 ; a - - bar = %x62 ; b - - mumble = foo bar foo - - So that the rule <mumble> matches the lowercase string "aba". - - Linear white space: Concatenation is at the core of the ABNF parsing - model. A string of contiguous characters (values) is parsed - according to the rules defined in ABNF. For Internet specifications, - there is some history of permitting linear white space (space and - horizontal tab) to be freely and implicitly interspersed around major - constructs, such as delimiting special characters or atomic strings. - - NOTE: - - This specification for ABNF does not provide for implicit - specification of linear white space. - - Any grammar that wishes to permit linear white space around - delimiters or string segments must specify it explicitly. It is - often useful to provide for such white space in "core" rules that are - then used variously among higher-level rules. The "core" rules might - be formed into a lexical analyzer or simply be part of the main - ruleset. - - - -Crocker & Overell Standards Track [Page 6] - -RFC 5234 ABNF January 2008 - - -3.2. Alternatives: Rule1 / Rule2 - - Elements separated by a forward slash ("/") are alternatives. - Therefore, - - foo / bar - - will accept <foo> or <bar>. - - NOTE: - - A quoted string containing alphabetic characters is a special form - for specifying alternative characters and is interpreted as a non- - terminal representing the set of combinatorial strings with the - contained characters, in the specified order but with any mixture - of upper- and lowercase. - -3.3. Incremental Alternatives: Rule1 =/ Rule2 - - It is sometimes convenient to specify a list of alternatives in - fragments. That is, an initial rule may match one or more - alternatives, with later rule definitions adding to the set of - alternatives. This is particularly useful for otherwise independent - specifications that derive from the same parent ruleset, such as - often occurs with parameter lists. ABNF permits this incremental - definition through the construct: - - oldrule =/ additional-alternatives - - So that the ruleset - - ruleset = alt1 / alt2 - - ruleset =/ alt3 - - ruleset =/ alt4 / alt5 - - is the same as specifying - - ruleset = alt1 / alt2 / alt3 / alt4 / alt5 - - - - - - - - - - - -Crocker & Overell Standards Track [Page 7] - -RFC 5234 ABNF January 2008 - - -3.4. Value Range Alternatives: %c##-## - - A range of alternative numeric values can be specified compactly, - using a dash ("-") to indicate the range of alternative values. - Hence: - - DIGIT = %x30-39 - - is equivalent to: - - DIGIT = "0" / "1" / "2" / "3" / "4" / "5" / "6" / - - "7" / "8" / "9" - - Concatenated numeric values and numeric value ranges cannot be - specified in the same string. A numeric value may use the dotted - notation for concatenation or it may use the dash notation to specify - one value range. Hence, to specify one printable character between - end-of-line sequences, the specification could be: - - char-line = %x0D.0A %x20-7E %x0D.0A - -3.5. Sequence Group: (Rule1 Rule2) - - Elements enclosed in parentheses are treated as a single element, - whose contents are strictly ordered. Thus, - - elem (foo / bar) blat - - matches (elem foo blat) or (elem bar blat), and - - elem foo / bar blat - - matches (elem foo) or (bar blat). - - NOTE: - - It is strongly advised that grouping notation be used, rather than - relying on the proper reading of "bare" alternations, when - alternatives consist of multiple rule names or literals. - - Hence, it is recommended that the following form be used: - - (elem foo) / (bar blat) - - It will avoid misinterpretation by casual readers. - - - - - -Crocker & Overell Standards Track [Page 8] - -RFC 5234 ABNF January 2008 - - - The sequence group notation is also used within free text to set off - an element sequence from the prose. - -3.6. Variable Repetition: *Rule - - The operator "*" preceding an element indicates repetition. The full - form is: - - <a>*<b>element - - where <a> and <b> are optional decimal values, indicating at least - <a> and at most <b> occurrences of the element. - - Default values are 0 and infinity so that *<element> allows any - number, including zero; 1*<element> requires at least one; - 3*3<element> allows exactly 3; and 1*2<element> allows one or two. - -3.7. Specific Repetition: nRule - - A rule of the form: - - <n>element - - is equivalent to - - <n>*<n>element - - That is, exactly <n> occurrences of <element>. Thus, 2DIGIT is a - 2-digit number, and 3ALPHA is a string of three alphabetic - characters. - -3.8. Optional Sequence: [RULE] - - Square brackets enclose an optional element sequence: - - [foo bar] - - is equivalent to - - *1(foo bar). - -3.9. Comment: ; Comment - - A semicolon starts a comment that continues to the end of line. This - is a simple way of including useful notes in parallel with the - specifications. - - - - - -Crocker & Overell Standards Track [Page 9] - -RFC 5234 ABNF January 2008 - - -3.10. Operator Precedence - - The various mechanisms described above have the following precedence, - from highest (binding tightest) at the top, to lowest (loosest) at - the bottom: - - Rule name, prose-val, Terminal value - - Comment - - Value range - - Repetition - - Grouping, Optional - - Concatenation - - Alternative - - Use of the alternative operator, freely mixed with concatenations, - can be confusing. - - Again, it is recommended that the grouping operator be used to - make explicit concatenation groups. - -4. ABNF Definition of ABNF - - NOTES: - - 1. This syntax requires a formatting of rules that is relatively - strict. Hence, the version of a ruleset included in a - specification might need preprocessing to ensure that it can - be interpreted by an ABNF parser. - - 2. This syntax uses the rules provided in Appendix B. - - - rulelist = 1*( rule / (*c-wsp c-nl) ) - - rule = rulename defined-as elements c-nl - ; continues if next line starts - ; with white space - - rulename = ALPHA *(ALPHA / DIGIT / "-") - - - - - - -Crocker & Overell Standards Track [Page 10] - -RFC 5234 ABNF January 2008 - - - defined-as = *c-wsp ("=" / "=/") *c-wsp - ; basic rules definition and - ; incremental alternatives - - elements = alternation *c-wsp - - c-wsp = WSP / (c-nl WSP) - - c-nl = comment / CRLF - ; comment or newline - - comment = ";" *(WSP / VCHAR) CRLF - - alternation = concatenation - *(*c-wsp "/" *c-wsp concatenation) - - concatenation = repetition *(1*c-wsp repetition) - - repetition = [repeat] element - - repeat = 1*DIGIT / (*DIGIT "*" *DIGIT) - - element = rulename / group / option / - char-val / num-val / prose-val - - group = "(" *c-wsp alternation *c-wsp ")" - - option = "[" *c-wsp alternation *c-wsp "]" - - char-val = DQUOTE *(%x20-21 / %x23-7E) DQUOTE - ; quoted string of SP and VCHAR - ; without DQUOTE - - num-val = "%" (bin-val / dec-val / hex-val) - - bin-val = "b" 1*BIT - [ 1*("." 1*BIT) / ("-" 1*BIT) ] - ; series of concatenated bit values - ; or single ONEOF range - - dec-val = "d" 1*DIGIT - [ 1*("." 1*DIGIT) / ("-" 1*DIGIT) ] - - hex-val = "x" 1*HEXDIG - [ 1*("." 1*HEXDIG) / ("-" 1*HEXDIG) ] - - - - - - -Crocker & Overell Standards Track [Page 11] - -RFC 5234 ABNF January 2008 - - - prose-val = "<" *(%x20-3D / %x3F-7E) ">" - ; bracketed string of SP and VCHAR - ; without angles - ; prose description, to be used as - ; last resort - -5. Security Considerations - - Security is truly believed to be irrelevant to this document. - -6. References - -6.1. Normative References - - [US-ASCII] American National Standards Institute, "Coded Character - Set -- 7-bit American Standard Code for Information - Interchange", ANSI X3.4, 1986. - -6.2. Informative References - - [RFC733] Crocker, D., Vittal, J., Pogran, K., and D. Henderson, - "Standard for the format of ARPA network text messages", - RFC 733, November 1977. - - [RFC822] Crocker, D., "Standard for the format of ARPA Internet - text messages", STD 11, RFC 822, August 1982. - - - - - - - - - - - - - - - - - - - - - - - - - -Crocker & Overell Standards Track [Page 12] - -RFC 5234 ABNF January 2008 - - -Appendix A. Acknowledgements - - The syntax for ABNF was originally specified in RFC 733. Ken L. - Harrenstien, of SRI International, was responsible for re-coding the - BNF into an Augmented BNF that makes the representation smaller and - easier to understand. - - This recent project began as a simple effort to cull out the portion - of RFC 822 that has been repeatedly cited by non-email specification - writers, namely the description of Augmented BNF. Rather than simply - and blindly converting the existing text into a separate document, - the working group chose to give careful consideration to the - deficiencies, as well as benefits, of the existing specification and - related specifications made available over the last 15 years, and - therefore to pursue enhancement. This turned the project into - something rather more ambitious than was first intended. - Interestingly, the result is not massively different from that - original, although decisions, such as removing the list notation, - came as a surprise. - - This "separated" version of the specification was part of the DRUMS - working group, with significant contributions from Jerome Abela, - Harald Alvestrand, Robert Elz, Roger Fajman, Aviva Garrett, Tom - Harsch, Dan Kohn, Bill McQuillan, Keith Moore, Chris Newman, Pete - Resnick, and Henning Schulzrinne. - - Julian Reschke warrants a special thanks for converting the Draft - Standard version to XML source form. - -Appendix B. Core ABNF of ABNF - - This appendix contains some basic rules that are in common use. - Basic rules are in uppercase. Note that these rules are only valid - for ABNF encoded in 7-bit ASCII or in characters sets that are a - superset of 7-bit ASCII. - -B.1. Core Rules - - Certain basic rules are in uppercase, such as SP, HTAB, CRLF, DIGIT, - ALPHA, etc. - - ALPHA = %x41-5A / %x61-7A ; A-Z / a-z - - BIT = "0" / "1" - - CHAR = %x01-7F - ; any 7-bit US-ASCII character, - ; excluding NUL - - - -Crocker & Overell Standards Track [Page 13] - -RFC 5234 ABNF January 2008 - - - CR = %x0D - ; carriage return - - CRLF = CR LF - ; Internet standard newline - - CTL = %x00-1F / %x7F - ; controls - - DIGIT = %x30-39 - ; 0-9 - - DQUOTE = %x22 - ; " (Double Quote) - - HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" - - HTAB = %x09 - ; horizontal tab - - LF = %x0A - ; linefeed - - LWSP = *(WSP / CRLF WSP) - ; Use of this linear-white-space rule - ; permits lines containing only white - ; space that are no longer legal in - ; mail headers and have caused - ; interoperability problems in other - ; contexts. - ; Do not use when defining mail - ; headers and use with caution in - ; other contexts. - - OCTET = %x00-FF - ; 8 bits of data - - SP = %x20 - - VCHAR = %x21-7E - ; visible (printing) characters - - WSP = SP / HTAB - ; white space - - - - - - - -Crocker & Overell Standards Track [Page 14] - -RFC 5234 ABNF January 2008 - - -B.2. Common Encoding - - Externally, data are represented as "network virtual ASCII" (namely, - 7-bit US-ASCII in an 8-bit field), with the high (8th) bit set to - zero. A string of values is in "network byte order", in which the - higher-valued bytes are represented on the left-hand side and are - sent over the network first. - -Authors' Addresses - - Dave Crocker (editor) - Brandenburg InternetWorking - 675 Spruce Dr. - Sunnyvale, CA 94086 - US - - Phone: +1.408.246.8253 - EMail: dcrocker@bbiw.net - - - Paul Overell - THUS plc. - 1/2 Berkeley Square, - 99 Berkeley Street - Glasgow G3 7HR - UK - - EMail: paul.overell@thus.net - - - - - - - - - - - - - - - - - - - - - - - -Crocker & Overell Standards Track [Page 15] - -RFC 5234 ABNF 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. - - - - - - - - - - - - -Crocker & Overell Standards Track [Page 16] - |