Your IP : 216.73.216.62
Last Updated: 6 March 2008
This directory contains Internet Drafts which, at the time of release of
this software, were not yet been published as RFCs. These documents are
expected to be released as RFCs in the near future.
This software adheres to the specification in these documents, which
are included for informational purposes. Note, however, that these
documents must be considered preliminary in nature and will be superceded
by the successor RFC.
File Name I-D Name
--------- --------
sort.txt draft-ietf-imapext-sort-20.txt
;; SORT and THREAD commands
;; Status: approved, blocked waiting for i18n
i18n.txt draft-ietf-imapext-i18n-15.txt
;; internationalization in IMAP
Network Working Group Chris Newman
Internet-Draft Sun Microsystems
Intended Status: Proposed Standard Arnt Gulbrandsen
Oryx Mail Systems GmhH
Alexey Melnikov
Isode Limited
February 1, 2008
Internet Message Access Protocol Internationalization
draft-ietf-imapext-i18n-15.txt
Status of this Memo
By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other documents
at any time. It is inappropriate to use Internet-Drafts as
reference material or to cite them other than as "work in progress".
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-
Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft expires in August 2008.
Copyright Notice
Copyright (C) The IETF Trust (2008).
Abstract
Internet Message Access Protocol (IMAP) version 4rev1 has basic
support for non-ASCII characters in mailbox names and search
substrings. It also supports non-ASCII message headers and content
encoded as specified by Multipurpose Internet Mail Extensions
(MIME). This specification defines a collection of IMAP extensions
Newman & Co Expires August 2008 FF[Page 1]
Internet-draft February 2008
which improve international support including comparator negotiation
for search, sort and thread, language negotiation for international
error text, and translations for namespace prefixes.
Table of Contents
1. Conventions Used in this Document . . . . . . . . . . . . . . 2
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
3. LANGUAGE Extension . . . . . . . . . . . . . . . . . . . . . 3
3.1 LANGUAGE Extension Requirements . . . . . . . . . . . . . . . 3
3.2 LANGUAGE Command . . . . . . . . . . . . . . . . . . . . . . 4
3.3 LANGUAGE Response . . . . . . . . . . . . . . . . . . . . . . 6
3.4 TRANSLATION Extension to the NAMESPACE Response . . . . . . . 6
3.5 Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 6
4. I18NLEVEL=1 and I18NLEVEL=2 Extensions . . . . . . . . . . . 7
4.1 Introduction and Overview . . . . . . . . . . . . . . . . . . 8
4.2 Requirements common to both I18NLEVEL=1 and I18NLEVEL=2 . . .
4.3 I18NLEVEL=1 Extension Requirements . . . . . . . . . . . . . 8
4.4 I18NLEVEL=2 Extension Requirements . . . . . . . . . . . . . 8
4.5 Compatibility Notes
4.6 Comparators and Charsets . . . . . . . . . . . . . . . . . . 9
4.7 COMPARATOR Command . . . . . . . . . . . . . . . . . . . . . 9
4.8 COMPARATOR Response . . . . . . . . . . . . . . . . . . . . . 10
4.9 BADCOMPARATOR Response Code . . . . . . . . . . . . . . . . .
4.10 Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . 10
5. Other IMAP Internationalization Issues . . . . . . . . . . . 11
5.1 UTF-8 Userids and Passwords . . . . . . . . . . . . . . . . . 11
5.2 UTF-8 Mailbox Names . . . . . . . . . . . . . . . . . . . . . 11
5.3 UTF-8 Domains, Addresses and Mail Headers . . . . . . . . . . 11
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
7. Security Considerations . . . . . . . . . . . . . . . . . . . 12
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12
9. Relevant Standards for i18n IMAP Implementations . . . . . . 13
Normative References . . . . . . . . . . . . . . . . . . . . 13
Informative References . . . . . . . . . . . . . . . . . . . 14
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 15
Intellectual Property and Copyright Statements . . . . . . . 16
Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
The formal syntax use the Augmented Backus-Naur Form (ABNF)
[RFC4234] notation including the core rules defined in Appendix A.
Newman & Co Expires August 2008 FF[Page 2]
Internet-draft February 2008
The UTF8-related productions are defined in [RFC3629].
In examples, "C:" and "S:" indicate lines sent by the client and
server respectively. If a single "C:" or "S:" label applies to
multiple lines, then the line breaks between those lines are for
editorial clarity only and are not part of the actual protocol
exchange.
2. Introduction
This specification defines two IMAP4rev1 [RFC3501] extensions to
enhance international support. These extensions can be advertised
and implemented separately.
The LANGUAGE extension allows the client to request a suitable
language for protocol error messages and in combination with the
NAMESPACE extension [RFC2342] enables namespace translations.
The I18NLEVEL=2 extension allows the client to request a suitable
collation which will modify the behavior of the base specification's
SEARCH command as well as the SORT and THREAD extensions [SORT].
This leverages the collation registry [RFC4790].
3. LANGUAGE Extension
IMAP allows server responses to include human-readable text that in
many cases needs to be presented to the user. But that text is
limited to US-ASCII by the IMAP specification [RFC3501] in order to
preserve backwards compatibility with deployed IMAP implementations.
This section specifies a way for an IMAP client to negotiate which
language the server should use when sending human-readable text.
The LANGUAGE extension only provides a mechanism for altering fixed
server strings such as response text and NAMESPACE folder names.
Assigning localized language aliases to shared mailboxes would be
done with a separate mechanism such as the proposed METADATA
extension (see [METADATA]).
3.1 LANGUAGE Extension Requirements
IMAP servers that support this extension MUST list the keyword
LANGUAGE in their CAPABILITY response as well as in the greeting
CAPABILITY data.
A server that advertises this extension MUST use the language "i-
Newman & Co Expires August 2008 FF[Page 3]
Internet-draft February 2008
default" as described in [RFC2277] as its default language until
another supported language is negotiated by the client. A server
MUST include "i-default" as one of its supported languages.
Clients and servers that support this extension MUST also support
the NAMESPACE extension [RFC2342].
The LANGUAGE command is valid in all states. Clients are urged to
issue LANGUAGE before authentication, since some servers send
valuable user information as part of authentication (e.g. "password
is correct, but expired"). If a security layer (such as SASL or
TLS) is subsequently negotiated by the client, it MUST re-issue the
LANGUAGE command in order to make sure that no previous active
attack (if any) on LANGUAGE negotiation has effect on subsequent
error messages. (See Section 7 for a more detailed explanation of
the attack.)
3.2 LANGUAGE Command
Arguments: Optional language range arguments.
Response: A possible LANGUAGE response (see section 3.3).
A possible NAMESPACE response (see section 3.4).
Result: OK - Command completed
NO - Could not complete command
BAD - arguments invalid
The LANGUAGE command requests that human-readable text emitted by
the server be localized to a language matching one of the language
range argument as described by section 2 of [RFC4647].
If the command succeeds, the server will return human-readable
responses in the first supported language specified. These
responses will be in UTF-8 [RFC3629]. The server MUST send a
LANGUAGE response specifying the language used, and the change takes
effect immediately after the LANGUAGE response.
If the command fails, the server continues to return human-readable
responses in the language it was previously using.
The special "default" language range argument indicates a request to
use a language designated as preferred by the server administrator.
The preferred language MAY vary based on the currently active user.
If a language range does not match a known language tag exactly but
Newman & Co Expires August 2008 FF[Page 4]
Internet-draft February 2008
does match a language by the rules of [RFC4647], the server MUST
send an untagged LANGUAGE response indicating the language selected.
If there aren't any arguments, the server SHOULD send an untagged
LANGUAGE response listing the languages it supports. If the server
is unable to enumerate the list of languages it supports it MAY
return a tagged NO response to the enumeration request.
< The server defaults to using English i-default responses until
the user explicitly changes the language. >
C: A001 LOGIN KAREN PASSWORD
S: A001 OK LOGIN completed
< Client requested MUL language, which no server supports. >
C: A002 LANGUAGE MUL
S: A002 NO Unsupported language MUL
< A LANGUAGE command with no arguments is a request to enumerate
the list of languages the server supports. >
C: A003 LANGUAGE
S: * LANGUAGE (EN DE IT i-default)
S: A003 OK Supported languages have been enumerated
C: B001 LANGUAGE
S: B001 NO Server is unable to enumerate supported languages
< Once the client changes the language, all responses will be in
that language starting after the LANGUAGE response. Note that
this includes the NAMESPACE response. Because RFCs are in US-
ASCII, this document uses an ASCII transcription rather than
UTF-8 text, e.g. ue in the word "ausgefuehrt" >
C: C001 LANGUAGE DE
S: * LANGUAGE (DE)
S: * NAMESPACE (("" "/")) (("Other Users/" "/" "TRANSLATION"
("Andere Ben&APw-tzer/"))) (("Public Folders/" "/"
"TRANSLATION" ("Gemeinsame Postf&AM8-cher/")))
S: C001 OK Sprachwechsel durch LANGUAGE-Befehl ausgefuehrt
< If a server does not support the requested primary language,
responses will continue to be returned in the current language
the server is using. >
C: D001 LANGUAGE FR
S: D001 NO Diese Sprache ist nicht unterstuetzt
Newman & Co Expires August 2008 FF[Page 5]
Internet-draft February 2008
C: D002 LANGUAGE DE-IT
S: * LANGUAGE (DE-IT)
S: * NAMESPACE (("" "/"))(("Other Users/" "/" "TRANSLATION"
("Andere Ben&APw-tzer/"))) (("Public Folders/" "/"
"TRANSLATION" ("Gemeinsame Postf&AM8-cher/")))
S: D002 OK Sprachwechsel durch LANGUAGE-Befehl ausgefuehrt
C: D003 LANGUAGE "default"
S: * LANGUAGE (DE)
S: D003 OK Sprachwechsel durch LANGUAGE-Befehl ausgefuehrt
< Server does not speak French, but does speak English. User
speaks Canadian French and Canadian English. >
C: E001 LANGUAGE FR-CA EN-CA
S: * LANGUAGE (EN)
S: E001 OK Now speaking English
3.3 LANGUAGE Response
Contents: A list of one or more language tags.
The LANGUAGE response occurs as a result of a LANGUAGE command. A
LANGUAGE response with a list containing a single language tag
indicates that the server is now using that language. A LANGUAGE
response with a list containing multiple language tags indicates the
server is communicating a list of available languages to the client,
and no change in the active language has been made.
3.4 TRANSLATION Extension to the NAMESPACE Response
If localized representations of the namespace prefixes are available
in the selected language, the server SHOULD include these in the
TRANSLATION extension to the NAMESPACE response.
The TRANSLATION extension to the NAMESPACE response returns a single
string, containing the modified UTF-7 [RFC3501] encoded translation
of the namespace prefix. It is the responsibility of the client to
convert between the namespace prefix and the translation of the
namespace prefix when presenting mailbox names to the user.
In this example a server supports the IMAP4 NAMESPACE command. It
uses no prefix to the user's Personal Namespace, a prefix of "Other
Users" to its Other Users' Namespace and a prefix of "Public
Folders" to its only Shared Namespace. Since a client will often
display these prefixes to the user, the server includes a
Newman & Co Expires August 2008 FF[Page 6]
Internet-draft February 2008
translation of them that can be presented to the user.
C: A001 LANGUAGE DE-IT
S: * NAMESPACE (("" "/")) (("Other Users/" "/" "TRANSLATION"
("Andere Ben&APw-tzer/"))) (("Public Folders/" "/"
"TRANSLATION" ("Gemeinsame Postf&AM8-cher/")))
S: A001 OK LANGUAGE-Befehl ausgefuehrt
3.5 Formal Syntax
The following syntax specification inherits ABNF [RFC4234] rules
from IMAP4rev1 [RFC3501], IMAP4 Namespace [RFC2342], Tags for the
Identifying Languages [RFC4646], UTF-8 [RFC3629] and Collected
Extensions to IMAP4 ABNF [RFC4466].
command-any =/ language-cmd
; LANGUAGE command is valid in all states
language-cmd = "LANGUAGE" *(SP lang-range-quoted)
response-payload =/ language-data
language-data = "LANGUAGE" SP "(" lang-tag-quoted *(SP
lang-tag-quoted) ")"
namespace-trans = SP DQUOTE "TRANSLATION" DQUOTE SP "(" string ")"
; the string is encoded in Modified UTF-7.
; this is a subset of the syntax permitted by
; the Namespace-Response-Extension rule in [RFC4466]
lang-range-quoted = astring
; Once any literal wrapper or quoting is removed, this
; follows the language-range rule in [RFC4647]
lang-tag-quoted = astring
; Once any literal wrapper or quoting is removed, this follows
; the Language-Tag rule in [RFC4646]
resp-text = ["[" resp-text-code "]" SP ] UTF8-TEXT-CHAR
*(UTF8-TEXT-CHAR / "[")
; After the server is changed to a language other than
; i-default, this resp-text rule replaces the resp-text
; rule from [RFC3501].
UTF8-TEXT-CHAR = %x20-5A / %x5C-7E / UTF8-2 / UTF8-3 / UTF8-4
; UTF-8 excluding 7-bit control characters and "["
Newman & Co Expires August 2008 FF[Page 7]
Internet-draft February 2008
4. I18NLEVEL=1 and I18NLEVEL=2 Extensions
4.1 Introduction and Overview
IMAP4rev1 [RFC3501] includes the SEARCH command which can be used to
locate messages matching criteria including human-readable text.
The SORT extension [SORT] to IMAP allows the client to ask the
server to determine the order of messages based on criteria
including human-readable text. These mechanisms require the ability
to support non-English search and sort functions.
Section 4 defines two IMAP extensions for internationalizing IMAP
SEARCH, SORT and THREAD [SORT] using the comparator framework
[RFC4790].
The I18NLEVEL=1 extension updates SEARCH/SORT/THREAD to use
i;unicode-casemap comparator, as defined in [UCM]. See Sections 4.2
and 4.3 for more details.
The I18NLEVEL=2 extension is a superset of the I18NLEVEL=1
extension. It adds to I18NLEVEL=1 extension the ability to determine
the active comparator (see definition below) and negotiate use of
comparators using the COMPARATOR command. It also adds the
COMPARATOR response that indicates the active comparator and
possibly other available comparators. See Sections 4.2 and 4.4 for
more details.
4.2 Requirements common to both I18NLEVEL=1 and I18NLEVEL=2
The term "default comparator" refers to the comparator which is used
by SEARCH and SORT absent any negotiation using the COMPARATOR (see
Section 4.7) command. The term "active comparator" refers to the
comparator which will be used within a session e.g. by SEARCH and
SORT. The COMPARATOR command is used to change the active
comparator.
The active comparator applies to the following SEARCH keys: "BCC",
"BODY", "CC", "FROM", "SUBJECT", "TEXT", "TO" and "HEADER". If the
server also advertises the "SORT" extension, then the active
comparator applies to the following SORT keys: "CC", "FROM",
"SUBJECT" and "TO". If the server advertises THREAD=ORDEREDSUBJECT,
then the active comparator applies to the ORDEREDSUBJECT threading
algorithm. If the server advertises THREAD=REFERENCES, then the
active comparator applies to the subject field comparisons done by
REFERENCES threading algorithm. Future extensions may choose to
apply the active comparator to their SEARCH keys.
Newman & Co Expires August 2008 FF[Page 8]
Internet-draft February 2008
For SORT and THREAD, the pre-processing necessary to extract the
base subject text from a Subject header occurs prior to the
application of a comparator.
A server that advertises I18NLEVEL=1 or I18NLEVEL=2 extension MUST
implement the i;unicode-casemap comparator, as defined in [UCM].
A server that advertises I18NLEVEL=1 or I18NLEVEL=2 extension MUST
support UTF-8 as a SEARCH charset.
4.3 I18NLEVEL=1 Extension Requirements
An IMAP server that satisfies all requirements specified in sections
4.2 and 4.6 (and doesn't support/advertise any other I18NLEVEL=<n>
extension, where n > 1) MUST list the keyword I18NLEVEL=1 in its
CAPABILITY data once IMAP enters the authenticated state, and MAY
list that keyword in other states.
4.4 I18NLEVEL=2 Extension Requirements
IMAP server that satisfies all requirements specified in sections
4.2, 4.4, 4.6-4.10 (and doesn't support/advertise any other
I18NLEVEL=<n> extension, where n > 2) MUST list the keyword
I18NLEVEL=2 in its CAPABILITY data once IMAP enters the
authenticated state, and MAY list that keyword in other states.
A server that advertises this extension MUST implement the
i;unicode-casemap comparator, as defined in [UCM]. It MAY implement
other comparators from the IANA registry established by [RFC4790].
See also section 4.5 of this document.
A server that advertises this extension SHOULD use i;unicode-casemap
as the default comparator. (Note that i;unicode-casemap is the
default comparator for I18NLEVEL=1, but not necessarily the default
for I18NLEVEL=2.) The selection of the default comparator MAY be
adjustable by the server administrator, and MAY be sensitive to the
current user. Once the IMAP connection enters authenticated state,
the default comparator MUST remain static for the remainder of that
connection.
Note that since SEARCH uses the substring operation, IMAP servers
can only implement collations that offer the substring operation
(see [RFC4790 section 4.2.2). Since SORT uses ordering operation
(and by implication equality), IMAP servers which advertise the SORT
extension can only implement collations that offer all three
Newman & Co Expires August 2008 FF[Page 9]
Internet-draft February 2008
operations (see [RFC4790] sections 4.2.2-4).
If the active collation does not provide the operations needed by an
IMAP command, the server MUST respond with a tagged BAD.
4.5 Compatibility Notes
Several server implementations deployed prior to the publication of
this specification comply with I18NLEVEL=1 (see section 4.3), but do
not advertise that. Other legacy servers use the i;ascii-casemap
(see [RFC4790]) comparator.
There is no good way for a client to know which comparator that a
legacy server uses. If the client has to assume the worst, it may
end up doing expensive local operations to obtain i;unicode-casemap
comparisons even though the server implements it.
Legacy server implementations which comply with I18NLEVEL=1 should
be updated to advertise I18NLEVEL=1. All server implementations
should eventually be updated to comply with the I18NLEVEL=2
extension.
4.6 Comparators and Character Encodings
RFC 3501, section 6.4.4 says:
In all search keys that use strings, a message matches
the key if the string is a substring of the field. The
matching is case-insensitive.
When performing the SEARCH operation, the active comparator is
applied instead of the case-insensitive matching specified above.
An IMAP server which performs collation operations (e.g., as part of
commands such as SEARCH, SORT, THREAD) does so according to the
following procedure:
(a) MIME encoding (for example see [RFC2047] for headers and
[RFC2045] for body parts) MUST be removed in the texts being
collated.
If MIME encoding removal fails for a message (e.g., a body part
of the message has an unsupported Content-Transfer-Encoding,
uses characters not allowed by the Content-Transfer-Encoding,
etc.), the collation of this message is undefined by this
specification, and is handled in an implementation-dependent
Newman & Co Expires August 2008 FF[Page 10]
Internet-draft February 2008
manner.
(b) The decoded text from (a) MUST be converted to the charset
expected by the active comparator.
(c) For the substring operation:
If step (b) failed (e.g., the text is in an unknown charset,
contains a sequence which is not valid according in that
charset, etc.), the original decoded text from (a) (i.e.,
before the charset conversion attempt) is collated using the
i;octet comparator (see [RFC4790]).
If step (b) was successful, the converted text from (b) is
collated according to the active comparator.
For the ordering operation:
All strings that were successfully converted by step (b) are
separated from all strings that failed step (b). Strings in
each group are collated independently. All strings successfully
converted by step (b) are then validated by the active
comparator. Strings that pass validation are collated using the
active comparator. All strings that either fail step (b) or fail
the active collation's validity operation are collated (after
applying step (a)) using the i;octet comparator (see [RFC4790]).
The resulting sorted list is produced by appending all collated
"failed" strings after all strings collated using the active
comparator.
Example: The following example demonstrates ordering of 4
different strings using i;unicode-casemap [UCM] comparator.
Strings are represented using hexadecimal notation used by
ABNF [RFC4234].
(1) %xD0 %xC0 %xD0 %xBD %xD0 %xB4 %xD1 %x80 %xD0 %xB5
%xD0 %xB9 (labeled with charset=UTF-8)
(2) %xD1 %x81 %xD0 %x95 %xD0 %xA0 %xD0 %x93 %xD0 %x95
%xD0 %x99 (labeled with charset=UTF-8)
(3) %xD0 %x92 %xD0 %xB0 %xD1 %x81 %xD0 %xB8 %xD0 %xBB
%xD0 %xB8 %xFF %xB9 (labeled with charset=UTF-8)
(4) %xE1 %xCC %xC5 %xCB %xD3 %xC5 %xCA (labeled with
charset=KOI8-R)
Step (b) will convert string # 4 to the following
sequence of octets (in UTF-8):
Newman & Co Expires August 2008 FF[Page 11]
Internet-draft February 2008
%xD0 %x90 %xD0 %xBB %xD0 %xB5 %xD0 %xBA %xD1 %x81 %xD0
%xB5 %xD0 %xB9
and will reject strings (1) and (3), as they contain
octets not allowed in charset=UTF-8.
After that, using the i;unicode-casemap collation,
string (4) will collate before string (2). Using the
i;octet collation on the original strings, string (3)
will collate before string (1). So the final ordering
is as follows: (4) (2) (3) (1).
If the substring operation (e.g., IMAP SEARCH) of the active
comparator returns the "undefined" result (see section 4.2.3 of
[RFC4790]) for either the text specified in the SEARCH command or
the message text, then the operation is repeated on the result of
step (a) using the i;octet comparator.
The ordering operation (e.g., IMAP SORT and THREAD) SHOULD collate
the following together: strings encoded using unknown or invalid
character encodings, strings in unrecognized charsets, and invalid
input (as defined by the active collation).
4.7 COMPARATOR Command
Arguments: Optional comparator order arguments.
Response: A possible COMPARATOR response (see Section 4.8).
Result: OK - Command completed
NO - No matching comparator found
BAD - arguments invalid
The COMPARATOR command is valid in authenticated and selected
states.
The COMPARATOR command is used to determine or change the active
comparator. When issued with no arguments, it results in a
COMPARATOR response indicating the currently active comparator.
When issued with one or more comparator argument, it changes the
active comparator as directed. (If more than one installed
comparator is matched by an argument, the first argument wins.) The
COMPARATOR response lists all matching comparators if more than one
matches the specified patterns.
The argument "default" refers to the server's default comparator.
Newman & Co Expires August 2008 FF[Page 12]
Internet-draft February 2008
Otherwise each argument is an collation specification as defined in
the Internet Application Protocol Comparator Registry [RFC4790].
< The client requests activating a Czech comparator if possible,
or else a generic international comparator which it considers
suitable for Czech. The server picks the first supported
comparator. >
C: A001 COMPARATOR "cz;*" i;basic
S: * COMPARATOR i;basic
S: A001 OK Will use i;basic for collation
4.8 COMPARATOR Response
Contents: The active comparator.
An optional list of available matching comparators
The COMPARATOR response occurs as a result of a COMPARATOR command.
The first argument in the comparator response is the name of the
active comparator. The second argument is a list of comparators
which matched any of the arguments to the COMPARATOR command and is
present only if more than one match is found.
4.9 BADCOMPARATOR response code
This response code SHOULD be returned as a result of server failing
an IMAP command (returning NO), when the server knows that none of
the specified comparators match the requested comparator(s).
4.10 Formal Syntax
The following syntax specification inherits ABNF [RFC4234] rules
from IMAP4rev1 [RFC3501], and Internet Application Protocol
Comparator Registry [RFC4790].
command-auth =/ comparator-cmd
resp-text-code =/ "BADCOMPARATOR"
comparator-cmd = "COMPARATOR" *(SP comp-order-quoted)
response-payload =/ comparator-data
comparator-data = "COMPARATOR" SP comp-sel-quoted [SP "("
comp-id-quoted *(SP comp-id-quoted) ")"]
Newman & Co Expires August 2008 FF[Page 13]
Internet-draft February 2008
comp-id-quoted = astring
; Once any literal wrapper or quoting is removed, this
; follows the collation-id rule from [RFC4790]
comp-order-quoted = astring
; Once any literal wrapper or quoting is removed, this
; follows the collation-order rule from [RFC4790]
comp-sel-quoted = astring
; Once any literal wrapper or quoting is removed, this
; follows the collation-selected rule from [RFC4790]
5. Other IMAP Internationalization Issues
The following sections provide an overview of various other IMAP
internationalization issues. These issues are not resolved by this
specification, but could be resolved by other standards work, such
as that being done by the EAI group (see [IMAP-EAI]).
5.1 Unicode Userids and Passwords
IMAP4rev1 currently restricts the userid and password fields of the
LOGIN command to US-ASCII. The "userid" and "password" fields of the
IMAP LOGIN command are restricted to US-ASCII only until a future
standards track RFC states otherwise. Servers are encouraged to
validate both fields to make sure they conform to the formal syntax
of UTF-8 and to reject the LOGIN command if that syntax is violated.
Servers MAY reject the use of any 8-bit in the "userid" or
"password" field.
When AUTHENTICATE is used, some servers may support userids and
passwords in Unicode [RFC3490] since SASL (see [RFC4422]) allows
that. However, such userids cannot be used as part of email
addresses.
5.2 UTF-8 Mailbox Names
The modified UTF-7 mailbox naming convention described in section
5.1.3 of RFC 3501 is best viewed as an transition from the status
quo in 1996 when modified UTF-7 was first specified. At that time,
there was widespread unofficial use of local character sets such as
ISO-8859-1 and Shift-JIS for non-ASCII mailbox names, with resultant
non-interoperability.
The requirements in section 5.1 of RFC 3501 are very important if
Newman & Co Expires August 2008 FF[Page 14]
Internet-draft February 2008
we're ever going to be able to deploy UTF-8 mailbox names. Servers
are encouraged to enforce them.
5.3 UTF-8 Domains, Addresses and Mail Headers
There is now an IETF standard for Internationalizing Domain Names in
Applications [RFC3490]. While IMAP clients are free to support this
standard, an argument can be made that it would be helpful to simple
clients if the IMAP server could perform this conversion (the same
argument would apply to MIME header encoding [RFC2047]). However,
it would be unwise to move forward with such work until the work in
progress to define the format of international email addresses is
complete.
6. IANA Considerations
The IANA is requested to add LANGUAGE, I18NLEVEL=1 and I18NLEVEL=2
to the IMAP4 Capabilities Registry. [Note to IANA:
http://www.iana.org/assignments/imap4-capabilities]
7. Security Considerations
The LANGUAGE extension makes a new command available in "Not
Authenticated" state in IMAP. Some IMAP implementations run with
root privilege when the server is in "Not Authenticated" state and
do not revoke that privilege until after authentication is complete.
Such implementations are particularly vulnerable to buffer overflow
security errors at this stage and need to implement parsing of this
command with extra care.
A LANGUAGE command issued prior to activation of a security layer is
subject to an active attack which suppresses or modifies the
negotiation and thus makes STARTTLS or authentication error messages
more difficult to interpret. This is not a new attack as the error
messages themselves are subject to active attack. Clients MUST re-
issue the LANGUAGE command once a security layer is active, so this
does not impact subsequent protocol operations.
LANGUAGE, I18NLEVEL=1 and I18NLEVEL=2 extensions use the UTF-8
charset, thus the security considerations for UTF-8 [RFC3629] are
relevent. However, neither uses UTF-8 for identifiers so the most
serious concerns do not apply.
8. Acknowledgements
Newman & Co Expires August 2008 FF[Page 15]
Internet-draft February 2008
The LANGUAGE extension is based on a previous Internet draft by Mike
Gahrns, a substantial portion of the text in that section was
written by him. Many people have participated in discussions about
an IMAP Language extension in the various fora of the IETF and
Internet working groups, so any list of contributors is bound to be
incomplete. However, the authors would like to thank Andrew McCown
for early work on the original proposal, John Myers for suggestions
regarding the namespace issue, along with Jutta Degener, Mark
Crispin, Mark Pustilnik, Larry Osterman, Cyrus Daboo, Martin Duerst,
Timo Sirainen, Ben Campbell and Magnus Nystrom for their many
suggestions that have been incorporated into this document.
Initial discussion of the I18NLEVEL=2 extension involved input from
Mark Crispin and other participants of the IMAP Extensions WG.
9. Relevant Standards for i18n IMAP Implementations
This is a non-normative list of standards to consider when
implementing i18n aware IMAP software.
o The LANGUAGE and I18NLEVEL=2 extensions to IMAP (this
specification).
o The 8-bit rules for mailbox naming in section 5.1 of RFC 3501.
o The Mailbox International Naming Convention in section 5.1.3 of
RFC 3501.
o MIME [RFC2045] for message bodies.
o MIME header encoding [RFC2047] for message headers.
o The IETF EAI working group.
o MIME Parameter Value and Encoded Word Extensions [RFC2231] for
filenames. Quality IMAP server implementations will
automatically combine multipart parameters when generating the
BODYSTRUCTURE. There is also some deployed non-standard use of
MIME header encoding inside double-quotes for filenames.
o IDNA [RFC3490] and punycode [RFC3492] for domain names
(currently only relevant to IMAP clients).
o The UTF-8 charset [RFC3629].
o The IETF policy on Character Sets and Languages [RFC2277].
Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2277] Alvestrand, "IETF Policy on Character Sets and
Languages", BCP 18, RFC 2277, January 1998.
Newman & Co Expires August 2008 FF[Page 16]
Internet-draft February 2008
[RFC2342] Gahrns, Newman, "IMAP4 Namespace", RFC 2342, May 1998.
[RFC3501] Crispin, "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
4rev1", RFC 3501, March 2003.
[RFC3629] Yergeau, "UTF-8, a transformation format of ISO 10646",
STD 63, RFC 3629, November 2003.
[RFC4234] Crocker, Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 4234, Brandenburg
Internetworking, Demon Internet Ltd, October 2005.
[RFC4422] Melnikov, Zeilenga, "Simple Authentication and Security
Layer (SASL)", RFC 4422, June 2006.
[RFC4466] Melnikov, Daboo, "Collected Extensions to IMAP4 ABNF",
RFC 4466, Isode Ltd., April 2006.
[RFC4646] Philips, Davis, "Tags for Identifying Languages", BCP 47,
RFC 4646, September 2006.
[RFC4647] Philips, Davis, "Matching of Language Tags", BCP 47, RFC
4647, September 2006.
[RFC4790] Newman, Duerst, Gulbrandsen, "Internet Application
Protocol Comparator Registry", RFC 4790, February 2007.
[SORT] Crispin, M. and K. Murchison, "INTERNET MESSAGE ACCESS
PROTOCOL - SORT AND THREAD EXTENSION", draft-ietf-
imapext-sort-19 (work in progress), November 2006.
[UCM] Crispin, "i;unicode-casemap - Simple Unicode Collation
Algorithm", RFC 5051, October 2007.
[RFC2045] Freed, Borenstein, "Multipurpose Internet Mail Extensions
(MIME) Part One: Format of Internet Message Bodies", RFC
2045, November 1996.
[RFC2047] Moore, "MIME (Multipurpose Internet Mail Extensions) Part
Three: Message Header Extensions for Non-ASCII Text", RFC
2047, November 1996.
Informative References
[RFC2231] Freed, Moore, "MIME Parameter Value and Encoded Word
Extensions: Character Sets, Languages, and
Newman & Co Expires August 2008 FF[Page 17]
Internet-draft February 2008
Continuations", RFC 2231, November 1997.
[RFC3490] Faltstrom, Hoffman, Costello, "Internationalizing Domain
Names in Applications (IDNA)", RFC 3490, March 2003.
[RFC3492] Costello, "Punycode: A Bootstring encoding of Unicode for
Internationalized Domain Names in Applications (IDNA)",
RFC 3492, March 2003.
[METADATA] Daboo, C., "IMAP METADATA Extension", draft-daboo-imap-
annotatemore-12 (work in progress), December 2007.
[IMAP-EAI] Resnick, Newman, "IMAP Support for UTF-8", draft-ietf-
eai-imap-utf8 (work in progress), May 2006.
Authors' Addresses
Chris Newman
Sun Microsystems
3401 Centrelake Dr., Suite 410
Ontario, CA 91761
US
Email: chris.newman@sun.com
Arnt Gulbrandsen
Oryx Mail Systems GmbH
Schweppermannstr. 8
D-81671 Muenchen
Germany
Email: arnt@oryx.com
Fax: +49 89 4502 9758
Alexey Melnikov
Isode Limited
5 Castle Business Village, 36 Station Road,
Hampton, Middlesex, TW12 2BX, UK
Email: Alexey.Melnikov@isode.com
Newman & Co Expires August 2008 FF[Page 18]
Internet-draft February 2008
Intellectual Property Statement
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.
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.
Acknowledgment
Funding for the RFC Editor function is currently provided by the
Internet Society.
Newman & Co Expires August 2008 FF[Page 19]
IMAP Extensions Working Group M. Crispin
Internet-Draft K. Murchison
Intended status: Proposed Standard March 10, 2008
Expires: September 10, 2008
Document: internet-drafts/draft-ietf-imapext-sort-20.txt
INTERNET MESSAGE ACCESS PROTOCOL - SORT AND THREAD EXTENSIONS
Status of this Memo
By submitting this Internet-Draft, each author represents that
any applicable patent or other IPR claims of which he or she is
aware have been or will be disclosed, and any of which he or she
becomes aware will be disclosed, in accordance with Section 6 of
BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
A revised version of this draft document will be submitted to the RFC
editor as a Proposed Standard for the Internet Community. Discussion
and suggestions for improvement are requested, and should be sent to
ietf-imapext@IMC.ORG.
Distribution of this memo is unlimited.
Abstract
This document describes the base-level server-based sorting and
threading extensions to the [IMAP] protocol. These extensions
provide substantial performance improvements for IMAP clients which
offer sorted and threaded views.
1. Introduction
The SORT and THREAD extensions to the [IMAP] protocol provide a means
of server-based sorting and threading of messages, without requiring
that the client download the necessary data to do so itself. This is
particularly useful for online clients as described in [IMAP-MODELS].
A server which supports the base-level SORT extension indicates this
with a capability name which starts with "SORT". Future,
upwards-compatible extensions to the SORT extension will all start
with "SORT", indicating support for this base level.
A server which supports the THREAD extension indicates this with one
or more capability names consisting of "THREAD=" followed by a
supported threading algorithm name as described in this document.
This provides for future upwards-compatible extensions.
A server which implements the SORT and/or THREAD extensions MUST
collate strings in accordance with the requirements of I18NLEVEL=1,
as described in [IMAP-I18N], and SHOULD implement and advertise the
I18NLEVEL=1 extension. Alternatively, a server MAY implement
I18NLEVEL=2 (or higher) and comply with the rules of that level.
Discussion: the SORT and THREAD extensions predate [IMAP-I18N] by
several years. At the time of this writing, all known server
implementations of SORT and THREAD comply with the rules of
I18NLEVEL=1, but do not necessarily advertise it. As discussed
in [IMAP-I18N] section 4.5, all server implementations should
eventually be updated to comply with the I18NLEVEL=2 extension.
Historical note: the REFERENCES threading algorithm is based on the
[THREADING] algorithm written used in "Netscape Mail and News"
versions 2.0 through 3.0.
2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described 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.
"User" is used to refer to a human user, whereas "client" refers to
the software being run by the user.
In examples, "C:" and "S:" indicate lines sent by the client and
server respectively.
2.1 Base Subject
Subject sorting and threading use the "base subject," which has
specific subject artifacts removed. Due to the complexity of these
artifacts, the formal syntax for the subject extraction rules is
ambiguous. The following procedure is followed to determine the
"base subject", using the [ABNF] formal syntax rules described in
section 5:
(1) Convert any RFC 2047 encoded-words in the subject to
UTF-8 as described in "internationalization
considerations." Convert all tabs and continuations to
space. Convert all multiple spaces to a single space.
(2) Remove all trailing text of the subject that matches
the subj-trailer ABNF, repeat until no more matches are
possible.
(3) Remove all prefix text of the subject that matches the
subj-leader ABNF.
(4) If there is prefix text of the subject that matches the
subj-blob ABNF, and removing that prefix leaves a non-empty
subj-base, then remove the prefix text.
(5) Repeat (3) and (4) until no matches remain.
Note: it is possible to defer step (2) until step (6), but this
requires checking for subj-trailer in step (4).
(6) If the resulting text begins with the subj-fwd-hdr ABNF
and ends with the subj-fwd-trl ABNF, remove the
subj-fwd-hdr and subj-fwd-trl and repeat from step (2).
(7) The resulting text is the "base subject" used in the
SORT.
All servers and disconnected (as described in [IMAP-MODELS]) clients
MUST use exactly this algorithm to determine the "base subject".
Otherwise there is potential for a user to get inconsistent results
based on whether they are running in connected or disconnected mode.
2.2 Sent Date
As used in this document, the term "sent date" refers to the date and
time from the Date: header, adjusted by time zone to normalize to
UTC. For example, "31 Dec 2000 16:01:33 -0800" is equivalent to the
UTC date and time of "1 Jan 2001 00:01:33 +0000".
If the time zone is invalid, the date and time SHOULD be treated as
UTC. If the time is also invalid, the time SHOULD be treated as
00:00:00. If there is no valid date or time, the date and time
SHOULD be treated as 00:00:00 on the earliest possible date.
This differs from the date-related criteria in the SEARCH command
(described in [IMAP] section 6.4.4), which use just the date and not
the time, and are not adjusted by time zone.
If the sent date can not be determined (a Date: header is missing or
can not be parsed), the INTERNALDATE for that message is used as the
sent date.
When comparing two sent dates that match exactly, the order in which
the two messages appear in the mailbox (that is, by sequence number)
is used as a tie-breaker to determine the order.
3. Additional Commands
These commands are extension to the [IMAP] base protocol.
The section headings are intended to correspond with where they would
be located in the main document if they were part of the base
specification.
BASE.6.4.SORT. SORT Command
Arguments: sort program
charset specification
searching criteria (one or more)
Data: untagged responses: SORT
Result: OK - sort completed
NO - sort error: can't sort that charset or
criteria
BAD - command unknown or arguments invalid
The SORT command is a variant of SEARCH with sorting semantics for
the results. Sort has two arguments before the searching criteria
argument; a parenthesized list of sort criteria, and the searching
charset.
The charset argument is mandatory (unlike SEARCH) and indicates
the [CHARSET] of the strings that appear in the searching
criteria. The US-ASCII and UTF-8 charsets MUST be implemented.
All other charsets are optional.
There is also a UID SORT command which returns unique identifiers
instead of message sequence numbers. Note that there are separate
searching criteria for message sequence numbers and UIDs; thus the
arguments to UID SORT are interpreted the same as in SORT. This
is analogous to the behavior of UID SEARCH, as opposed to UID
COPY, UID FETCH, or UID STORE.
The SORT command first searches the mailbox for messages that
match the given searching criteria using the charset argument for
the interpretation of strings in the searching criteria. It then
returns the matching messages in an untagged SORT response, sorted
according to one or more sort criteria.
Sorting is in ascending order. Earlier dates sort before later
dates; smaller sizes sort before larger sizes; and strings are
sorted according to ascending values established by their
collation algorithm (see under "Internationalization
Considerations").
If two or more messages exactly match according to the sorting
criteria, these messages are sorted according to the order in
which they appear in the mailbox. In other words, there is an
implicit sort criterion of "sequence number".
When multiple sort criteria are specified, the result is sorted in
the priority order that the criteria appear. For example,
(SUBJECT DATE) will sort messages in order by their base subject
text; and for messages with the same base subject text will sort
by their sent date.
Untagged EXPUNGE responses are not permitted while the server is
responding to a SORT command, but are permitted during a UID SORT
command.
The defined sort criteria are as follows. Refer to the Formal
Syntax section for the precise syntactic definitions of the
arguments. If the associated RFC-822 header for a particular
criterion is absent, it is treated as the empty string. The empty
string always collates before non-empty strings.
ARRIVAL
Internal date and time of the message. This differs from the
ON criteria in SEARCH, which uses just the internal date.
CC
[IMAP] addr-mailbox of the first "cc" address.
DATE
Sent date and time, as described in section 2.2.
FROM
[IMAP] addr-mailbox of the first "From" address.
REVERSE
Followed by another sort criterion, has the effect of that
criterion but in reverse (descending) order.
Note: REVERSE only reverses a single criterion, and does not
affect the implicit "sequence number" sort criterion if all
other criteria are identicial. Consequently, a sort of
REVERSE SUBJECT is not the same as a reverse ordering of a
SUBJECT sort. This can be avoided by use of additional
criteria, e.g. SUBJECT DATE vs. REVERSE SUBJECT REVERSE
DATE. In general, however, it's better (and faster, if the
client has a "reverse current ordering" command) to reverse
the results in the client instead of issuing a new SORT.
SIZE
Size of the message in octets.
SUBJECT
Base subject text.
TO
[IMAP] addr-mailbox of the first "To" address.
Example: C: A282 SORT (SUBJECT) UTF-8 SINCE 1-Feb-1994
S: * SORT 2 84 882
S: A282 OK SORT completed
C: A283 SORT (SUBJECT REVERSE DATE) UTF-8 ALL
S: * SORT 5 3 4 1 2
S: A283 OK SORT completed
C: A284 SORT (SUBJECT) US-ASCII TEXT "not in mailbox"
S: * SORT
S: A284 OK SORT completed
BASE.6.4.THREAD. THREAD Command
Arguments: threading algorithm
charset specification
searching criteria (one or more)
Data: untagged responses: THREAD
Result: OK - thread completed
NO - thread error: can't thread that charset or
criteria
BAD - command unknown or arguments invalid
The THREAD command is a variant of SEARCH with threading semantics
for the results. Thread has two arguments before the searching
criteria argument; a threading algorithm, and the searching
charset.
The charset argument is mandatory (unlike SEARCH) and indicates
the [CHARSET] of the strings that appear in the searching
criteria. The US-ASCII and UTF-8 charsets MUST be implemented.
All other charsets are optional.
There is also a UID THREAD command which returns unique
identifiers instead of message sequence numbers. Note that there
are separate searching criteria for message sequence numbers and
UIDs; thus the arguments to UID THREAD are interpreted the same as
in THREAD. This is analogous to the behavior of UID SEARCH, as
opposed to UID COPY, UID FETCH, or UID STORE.
The THREAD command first searches the mailbox for messages that
match the given searching criteria using the charset argument for
the interpretation of strings in the searching criteria. It then
returns the matching messages in an untagged THREAD response,
threaded according to the specified threading algorithm.
All collation is in ascending order. Earlier dates collate before
later dates and strings are collated according to ascending values
established by their collation algorithm (see under
"Internationalization Considerations").
Untagged EXPUNGE responses are not permitted while the server is
responding to a THREAD command, but are permitted during a UID
THREAD command.
The defined threading algorithms are as follows:
ORDEREDSUBJECT
The ORDEREDSUBJECT threading algorithm is also referred to as
"poor man's threading." The searched messages are sorted by
base subject and then by the sent date. The messages are then
split into separate threads, with each thread containing
messages with the same base subject text. Finally, the threads
are sorted by the sent date of the first message in the thread.
The first message of each thread are siblings of each other
(the "root"). The second message of a thread is the child of
the first message, and subsequent messages of the thread are
siblings of the second message and hence children of the
message at the root. Hence, there are no grandchildren in
ORDEREDSUBJECT threading.
Children in ORDEREDSUBJECT threading do not have descendents.
Client implementations SHOULD treat descendents of a child in
a server response as being siblings of that child.
REFERENCES
The REFERENCES threading algorithm threads the searched
messages by grouping them together in parent/child
relationships based on which messages are replies to others.
The parent/child relationships are built using two methods:
reconstructing a message's ancestry using the references
contained within it; and checking the original (not base)
subject of a message to see if it is a reply to (or forward of)
another message.
Note: "Message ID" in the following description refers to a
normalized form of the msg-id in [RFC-2822]. The actual
text in an RFC 2822 may use quoting, resulting in multiple
ways of expressing the same Message ID. Implementations of
the REFERENCES threading algorithm MUST normalize any msg-id
in order to avoid false non-matches due to differences in
quoting.
For example, the msg-id
<"01KF8JCEOCBS0045PS"@xxx.yyy.com>
and the msg-id
<01KF8JCEOCBS0045PS@xxx.yyy.com>
MUST be interpreted as being the same Message ID.
The references used for reconstructing a message's ancestry are
found using the following rules:
If a message contains a References header line, then use the
Message IDs in the References header line as the references.
If a message does not contain a References header line, or
the References header line does not contain any valid
Message IDs, then use the first (if any) valid Message ID
found in the In-Reply-To header line as the only reference
(parent) for this message.
Note: Although [RFC-2822] permits multiple Message IDs in
the In-Reply-To header, in actual practice this
discipline has not been followed. For example,
In-Reply-To headers have been observed with message
addresses after the Message ID, and there are no good
heuristics for software to determine the difference.
This is not a problem with the References header however.
If a message does not contain an In-Reply-To header line, or
the In-Reply-To header line does not contain a valid Message
ID, then the message does not have any references (NIL).
A message is considered to be a reply or forward if the base
subject extraction rules, applied to the original subject,
remove any of the following: a subj-refwd, a "(fwd)"
subj-trailer, or a subj-fwd-hdr and subj-fwd-trl.
The REFERENCES algorithm is significantly more complex than
ORDEREDSUBJECT and consists of six main steps. These steps are
outlined in detail below.
(1) For each searched message:
(A) Using the Message IDs in the message's references, link
the corresponding messages (those whose Message-ID header
line contains the given reference Message ID) together as
parent/child. Make the first reference the parent of the
second (and the second a child of the first), the second the
parent of the third (and the third a child of the second),
etc. The following rules govern the creation of these
links:
If a message does not contain a Message-ID header line,
or the Message-ID header line does not contain a valid
Message ID, then assign a unique Message ID to this
message.
If two or more messages have the same Message ID, then
only use that Message ID in the first (lowest sequence
number) message, and assign a unique Message ID to each
of the subsequent messages with a duplicate of that
Message ID.
If no message can be found with a given Message ID,
create a dummy message with this ID. Use this dummy
message for all subsequent references to this ID.
If a message already has a parent, don't change the
existing link. This is done because the References
header line may have been truncated by a MUA. As a
result, there is no guarantee that the messages
corresponding to adjacent Message IDs in the References
header line are parent and child.
Do not create a parent/child link if creating that link
would introduce a loop. For example, before making
message A the parent of B, make sure that A is not a
descendent of B.
Note: Message ID comparisons are case-sensitive.
(B) Create a parent/child link between the last reference
(or NIL if there are no references) and the current message.
If the current message already has a parent, it is probably
the result of a truncated References header line, so break
the current parent/child link before creating the new
correct one. As in step 1.A, do not create the parent/child
link if creating that link would introduce a loop. Note
that if this message has no references, that it will now
have no parent.
Note: The parent/child links created in steps 1.A and 1.B
MUST be kept consistent with one another at ALL times.
(2) Gather together all of the messages that have no parents
and make them all children (siblings of one another) of a dummy
parent (the "root"). These messages constitute the first
(head) message of the threads created thus far.
(3) Prune dummy messages from the thread tree. Traverse each
thread under the root, and for each message:
If it is a dummy message with NO children, delete it.
If it is a dummy message with children, delete it, but
promote its children to the current level. In other words,
splice them in with the dummy's siblings.
Do not promote the children if doing so would make them
children of the root, unless there is only one child.
(4) Sort the messages under the root (top-level siblings only)
by sent date as described in section 2.2. In the case of a
dummy message, sort its children by sent date and then use the
first child for the top-level sort.
(5) Gather together messages under the root that have the same
base subject text.
(A) Create a table for associating base subjects with
messages, called the subject table.
(B) Populate the subject table with one message per each
base subject. For each child of the root:
(i) Find the subject of this thread, by using the base
subject from either the current message or its first
child if the current message is a dummy. This is the
thread subject.
(ii) If the thread subject is empty, skip this message.
(iii) Look up the message associated with the thread
subject in the subject table.
(iv) If there is no message in the subject table with the
thread subject, add the current message and the thread
subject to the subject table.
Otherwise, if the message in the subject table is not a
dummy, AND either of the following criteria are true:
The current message is a dummy, OR
The message in the subject table is a reply or forward
and the current message is not.
then replace the message in the subject table with the
current message.
(C) Merge threads with the same thread subject. For each
child of the root:
(i) Find the message's thread subject as in step 5.B.i
above.
(ii) If the thread subject is empty, skip this message.
(iii) Lookup the message associated with this thread
subject in the subject table.
(iv) If the message in the subject table is the current
message, skip this message.
Otherwise, merge the current message with the one in the
subject table using the following rules:
If both messages are dummies, append the current
message's children to the children of the message in
the subject table (the children of both messages
become siblings), and then delete the current message.
If the message in the subject table is a dummy and the
current message is not, make the current message a
child of the message in the subject table (a sibling
of its children).
If the current message is a reply or forward and the
message in the subject table is not, make the current
message a child of the message in the subject table (a
sibling of its children).
Otherwise, create a new dummy message and make both
the current message and the message in the subject
table children of the dummy. Then replace the message
in the subject table with the dummy message.
Note: Subject comparisons are case-insensitive, as
described under "Internationalization
Considerations."
(6) Traverse the messages under the root and sort each set of
siblings by sent date as described in section 2.2. Traverse
the messages in such a way that the "youngest" set of siblings
are sorted first, and the "oldest" set of siblings are sorted
last (grandchildren are sorted before children, etc). In the
case of a dummy message (which can only occur with top-level
siblings), use its first child for sorting.
Example: C: A283 THREAD ORDEREDSUBJECT UTF-8 SINCE 5-MAR-2000
S: * THREAD (166)(167)(168)(169)(172)(170)(171)
(173)(174 (175)(176)(178)(181)(180))(179)(177
(183)(182)(188)(184)(185)(186)(187)(189))(190)
(191)(192)(193)(194 195)(196 (197)(198))(199)
(200 202)(201)(203)(204)(205)(206 207)(208)
S: A283 OK THREAD completed
C: A284 THREAD ORDEREDSUBJECT US-ASCII TEXT "gewp"
S: * THREAD
S: A284 OK THREAD completed
C: A285 THREAD REFERENCES UTF-8 SINCE 5-MAR-2000
S: * THREAD (166)(167)(168)(169)(172)((170)(179))
(171)(173)((174)(175)(176)(178)(181)(180))
((177)(183)(182)(188 (184)(189))(185 186)(187))
(190)(191)(192)(193)((194)(195 196))(197 198)
(199)(200 202)(201)(203)(204)(205 206 207)(208)
S: A285 OK THREAD completed
Note: The line breaks in the first and third server
responses are for editorial clarity and do not appear in
real THREAD responses.
4. 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 main document.
BASE.7.2.SORT. SORT Response
Data: zero or more numbers
The SORT response occurs as a result of a SORT or UID SORT
command. The number(s) refer to those messages that match the
search criteria. For SORT, these are message sequence numbers;
for UID SORT, these are unique identifiers. Each number is
delimited by a space.
Example: S: * SORT 2 3 6
BASE.7.2.THREAD. THREAD Response
Data: zero or more threads
The THREAD response occurs as a result of a THREAD or UID THREAD
command. It contains zero or more threads. A thread consists of
a parenthesized list of thread members.
Thread members consist of zero or more message numbers, delimited
by spaces, indicating successive parent and child. This continues
until the thread splits into multiple sub-threads, at which point
the thread nests into multiple sub-threads with the first member
of each subthread being siblings at this level. There is no limit
to the nesting of threads.
The messages numbers refer to those messages that match the search
criteria. For THREAD, these are message sequence numbers; for UID
THREAD, these are unique identifiers.
Example: S: * THREAD (2)(3 6 (4 23)(44 7 96))
The first thread consists only of message 2. The second thread
consists of the messages 3 (parent) and 6 (child), after which it
splits into two subthreads; the first of which contains messages 4
(child of 6, sibling of 44) and 23 (child of 4), and the second of
which contains messages 44 (child of 6, sibling of 4), 7 (child of
44), and 96 (child of 7). Since some later messages are parents
of earlier messages, the messages were probably moved from some
other mailbox at different times.
-- 2
-- 3
\-- 6
|-- 4
| \-- 23
|
\-- 44
\-- 7
\-- 96
Example: S: * THREAD ((3)(5))
In this example, 3 and 5 are siblings of a parent which does not
match the search criteria (and/or does not exist in the mailbox);
however they are members of the same thread.
5. Formal Syntax of SORT and THREAD Commands and Responses
The following syntax specification uses the Augmented Backus-Naur
Form (ABNF) notation as specified in [ABNF]. It also uses [ABNF]
rules defined in [IMAP].
sort = ["UID" SP] "SORT" SP sort-criteria SP search-criteria
sort-criteria = "(" sort-criterion *(SP sort-criterion) ")"
sort-criterion = ["REVERSE" SP] sort-key
sort-key = "ARRIVAL" / "CC" / "DATE" / "FROM" / "SIZE" /
"SUBJECT" / "TO"
thread = ["UID" SP] "THREAD" SP thread-alg SP search-criteria
thread-alg = "ORDEREDSUBJECT" / "REFERENCES" / thread-alg-ext
thread-alg-ext = atom
; New algorithms MUST be registered with IANA
search-criteria = charset 1*(SP search-key)
charset = atom / quoted
; CHARSET values MUST be registered with IANA
sort-data = "SORT" *(SP nz-number)
thread-data = "THREAD" [SP 1*thread-list]
thread-list = "(" (thread-members / thread-nested) ")"
thread-members = nz-number *(SP nz-number) [SP thread-nested]
thread-nested = 2*thread-list
The following syntax describes base subject extraction rules (2)-(6):
subject = *subj-leader [subj-middle] *subj-trailer
subj-refwd = ("re" / ("fw" ["d"])) *WSP [subj-blob] ":"
subj-blob = "[" *BLOBCHAR "]" *WSP
subj-fwd = subj-fwd-hdr subject subj-fwd-trl
subj-fwd-hdr = "[fwd:"
subj-fwd-trl = "]"
subj-leader = (*subj-blob subj-refwd) / WSP
subj-middle = *subj-blob (subj-base / subj-fwd)
; last subj-blob is subj-base if subj-base would
; otherwise be empty
subj-trailer = "(fwd)" / WSP
subj-base = NONWSP *(*WSP NONWSP)
; can be a subj-blob
BLOBCHAR = %x01-5a / %x5c / %x5e-ff
; any CHAR8 except '[' and ']'
NONWSP = %x01-08 / %x0a-1f / %x21-ff
; any CHAR8 other than WSP
6. Security Considerations
The SORT and THREAD extensions do 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 [IMAP] protocol transactions, including message
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.
Although not a security consideration, it is important to recognize
that sorting by REFERENCES can lead to misleading threading trees.
For example, a message with false References: header data will cause
a thread to be incorporated into another thread.
The process of extracting the base subject may lead to incorrect
collation if the extracted data was significant text as opposed to
a subject artifact.
7. Internationalization Considerations
As stated in the introduction, the rules of I18NLEVEL=1 as described
in [IMAP-I18N] MUST be followed; that is, the SORT and THREAD
extensions MUST collate strings according to the i;unicode-casemap
collation described in [UNICASEMAP]. Servers SHOULD also advertise
the I18NLEVEL=1 extension. Alternatively, a server MAY implement
I18NLEVEL=2 (or higher) and comply with the rules of that level.
As discussed in [IMAP-I18N] section 4.5, all server implementations
should eventually be updated to support the [IMAP-I18N] I18NLEVEL=2
extension.
Translations of the "re" or "fw"/"fwd" tokens are not specified for
removal in the base subject extraction process. An attempt to add
such translated tokens would result in a geometrically complex, and
ultimately unimplementable, task.
Instead, note that [RFC-2822] section 3.6.5 recommends that "re:"
(from the Latin "res", in the matter of) be used to identify a reply.
Although it is evident that, from the multiple forms of token to
identify a forwarded message, there is considerable variation found
in the wild, the variations are (still) manageable. Consequently, it
is suggested that "re:" and one of the variations of the tokens for
forward supported by the base subject extraction rules be adopted for
Internet mail messages, since doing so makes it a simple display time
task to localize the token language for the user.
8. IANA Considerations
[IMAP] capabilities are registered by publishing a standards track or
IESG approved experimental RFC. This document constitutes
registration of the SORT and THREAD capabilities in the [IMAP]
capabilities registry.
This document creates a new [IMAP] threading algorithms registry,
which registers threading algorithms by publishing a standards track
or IESG approved experimental RFC. This document constitutes
registration of the ORDEREDSUBJECT and REFERENCES algorithms in that
registry.
9. Normative References
The following documents are normative to this document:
[ABNF] Crocker, D. and Overell, P. "Augmented BNF
for Syntax Specifications: ABNF", RFC 5234
January 2008
[CHARSET] Freed, N. and Postel, J. "IANA Character Set
Registration Procedures", RFC 2978, October
2000.
[IMAP] Crispin, M. "Internet Message Access Protocol -
Version 4rev1", RFC 3501, March 2003.
[IMAP-I18N] Newman, C. and Gulbrandsen, A. "Internet
Message Access Protocol Internationalization",
Work in Progress.
[KEYWORDS] Bradner, S. "Key words for use in RFCs to
Indicate Requirement Levels", BCP 14, RFC 2119,
March 1997.
[RFC-2822] Resnick, P. "Internet Message Format", RFC
2822, April 2001.
[UNICASEMAP] Crispin, M. "i;unicode-casemap - Simple Unicode
Collation Algorithm", RFC 5051.
10. Informative References
The following documents are informative to this document:
[IMAP-MODELS] Crispin, M. "Distributed Electronic Mail Models
in IMAP4", RFC 1733, December 1994.
[THREADING] Zawinski, J. "Message Threading",
http://www.jwz.org/doc/threading.html,
1997-2002.
Appendices
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
Kenneth Murchison
Carnegie Mellon University
5000 Forbes Avenue
Cyert Hall 285
Pittsburgh, PA 15213
Phone: +1 (412) 268-2638
Email: murch@andrew.cmu.edu
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.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.
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]
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]
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 tra