diff options
| author | Eduardo Chappa <chappa@washington.edu> | 2013-11-02 02:51:18 -0600 |
|---|---|---|
| committer | Eduardo Chappa <chappa@washington.edu> | 2013-11-02 02:51:18 -0600 |
| commit | 7fe712882b909931088a318c08041b0e7974a000 (patch) | |
| tree | 2770f9b084e2efc7fc55e96e9bf4352cf2ff33a3 /imap/docs | |
| parent | bdfc834badee92ceeb2befe02f1d065ced5b9ddf (diff) | |
| download | alpine-7fe712882b909931088a318c08041b0e7974a000.tar.xz | |
* Update to version 2.19.1
* Upgrade UW-IMAP to Panda IMAP from https://github.com/jonabbey/panda-imap.
* Replace tabs by spaces in From and Subject fields to control for size in
screen of these fields. Change only in index screen display.
Diffstat (limited to 'imap/docs')
65 files changed, 50657 insertions, 2481 deletions
diff --git a/imap/docs/BUILD b/imap/docs/BUILD index e094e065..e9492c81 100644 --- a/imap/docs/BUILD +++ b/imap/docs/BUILD @@ -1,5 +1,6 @@ /* ======================================================================== * Copyright 1988-2007 University of Washington + * Copyright 2008-2011 Mark Crispin * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -12,15 +13,14 @@ */ BUILD AND INSTALLATION NOTES - Last Updated: 15 November 2007 + Last Updated: 15 April 2013 Table of Contents: 1. UNIX Build Notes 2. UNIX Installation Notes 3. Win32 Build Notes 4. Win32 Installation Notes -5. Inactive Ports (TOPS-20, VMS) -6. Other ports (Macintosh, DOS/Win16, Windows CE, Amiga, OS/2) +5. Other ports (TOPS-20, VMS, Macintosh, DOS/Win16, Windows CE, Amiga, OS/2) UNIX BUILD NOTES @@ -38,12 +38,12 @@ the SSLBUILD file for more information. Note that doing so will produce an IMAP server which is NON-COMPLIANT with RFC 3501. - You must build through the top-level imap-2007/Makefile, which will run -a "process" step the first time and create the imap-2007/c-client, -imap-2007/ipopd, and imap-2007/imapd directories in which building actually + You must build through the top-level panda-imap/Makefile, which will run +a "process" step the first time and create the panda-imap/c-client, +panda-imap/ipopd, and panda-imap/imapd directories in which building actually takes place. - Before doing a make on UNIX, you should read imap-2007/Makefile and see + Before doing a make on UNIX, you should read panda-imap/Makefile and see if your system type is known. The various system types are three-letter codes. If your system type is known, then use this as the make option. After the first time you do a make, this option is remembered in a file called OSTYPE, @@ -55,7 +55,7 @@ RedHat). For more generic builds, try slx (shadow passwords only) or lnp (PAM). To build for RedHat, do: make lrh - There are other make options, described in imap-2007/src/osdep/Makefile. + There are other make options, described in panda-imap/src/osdep/Makefile. It's probably best to see if an existing port will work on your system before inventing a new port. Try: @@ -65,7 +65,7 @@ before inventing a new port. Try: bsf modern BSD If you must invent a new port, you need to create an entry in -imap-2007/Makefile and imap-2007/src/osdep/Makefile for your new port, as +panda-imap/Makefile and panda-imap/src/osdep/Makefile for your new port, as well as osdep/os_???.h and osdep/os_???.c files with the appropriate OS-dependent support for that system. You also need to determine which setup process to use. You should use the ua process unless you are sure that your @@ -91,10 +91,10 @@ tenex, and unix drivers. UNIX INSTALLATION NOTES Binaries from the build are: - imap-2007/mtest/mtest c-client testbed program - imap-2007/ipopd/ipop2d POP2 daemon - imap-2007/ipopd/ipop3d POP3 daemon - imap-2007/imapd/imapd IMAP4rev1 daemon + panda-imap/mtest/mtest c-client testbed program + panda-imap/ipopd/ipop2d POP2 daemon + panda-imap/ipopd/ipop3d POP3 daemon + panda-imap/imapd/imapd IMAP4rev1 daemon mtest is normally not used except by c-client developers. @@ -272,11 +272,11 @@ the Microsoft Platform SDK from Microsoft's web site. There is also considerable debate about how new mail is to be snarfed. I am currently using something that seems to work with WinSMTP. Look at -the definition of MAILFILE in imap-2007/src/osdep/nt/mailfile.h and at the -sysinbox() function in imap-2007/src/osdep/nt/env_nt.c to see what's there +the definition of MAILFILE in panda-imap/src/osdep/nt/mailfile.h and at the +sysinbox() function in panda-imap/src/osdep/nt/env_nt.c to see what's there now, so you have a clue about how to hack it. - To build under Windows 95/98/NT, connect to the imap-2007 directory + To build under Windows 95/98/NT, connect to the panda-imap directory and do: nmake -f makefile.nt The resulting binaries will support SSL if either schannel.dll or @@ -284,7 +284,7 @@ security.dll is installed in Windows, using the old, undocumented, SSL interfaces. You can also use this to build under Me/2000/XP, but it is not the preferred build on this platform. - To build with MIT Kerberos support, connect to the imap-2007 directory + To build with MIT Kerberos support, connect to the panda-imap directory and do: nmake -f makefile.ntk The resulting binaries will support SSL if either schannel.dll or @@ -293,7 +293,7 @@ interfaces. They will also support MIT Kerberos. Note, however, that these binaries will only run on systems which have the MIT Kerberos DLLs installed, and will not run otherwise. - To build under Windows Me/2000/XP, connect to the imap-2007 directory + To build under Windows Me/2000/XP, connect to the panda-imap directory and do: nmake -f makefile.w2k The resulting binaries will support SSL and Microsoft Kerberos, using the @@ -303,10 +303,10 @@ binaries will not run under Windows 95, Windows 98, or Windows NT4. WIN32 INSTALLATION NOTES The resulting binaries will be: - imap-2007\mtest\mtest.exe (testbed client) - imap-2007\ipopd\ipop2d.exe POP2 server - imap-2007\ipopd\ipop3d.exe POP3 server - imap-2007\imapd\imapd.exe IMAP4rev1 server + panda-imap\mtest\mtest.exe (testbed client) + panda-imap\ipopd\ipop2d.exe POP2 server + panda-imap\ipopd\ipop3d.exe POP3 server + panda-imap\imapd\imapd.exe IMAP4rev1 server These servers are stdio servers. I wrote a simple network listener for NT called inetlisn; currently it is available as: @@ -331,14 +331,21 @@ It is based on inetlisn, and essentially is a "completed" version of inetlisn. are unwilling to invest the time to do some programming, you probably want to buy a commercial server product. - INACTIVE PORTS + OTHER PORTS - The TOPS-20 and VMS ports were developed at one time or another, but are -no longer actively developed. However, from time to time I test build both -of these to make sure that they compile without errors and that mtest runs, -and will continue doing so as long as I have access to systems running these -operating systems. + The following ports were developed at one time or another, but are no +longer actively developed or tested. It is not known if they still work or +not. + Port Status + ---- ------ +TOPS-20 Unsupported since Mark's passing +VMS Unsupported since Mark's passing +Macintosh Obsolete; Mac OS X uses UNIX port +DOS/Win16 Obsolete; modern PCs use Win32 port +Windows CE Never completed +Amiga Unknown +OS/2 Unknown TOPS-20 BUILD NOTES @@ -347,10 +354,10 @@ own in terms of a nice TOPS-20 like main program. Maybe someday some nice person will try porting Pine to TOPS-20. This assumes the use of KCC 6, and probably will not build with other compilers or older versions of KCC. - You do not use imap-2007/Makefile under TOPS-20, nor do you build any + You do not use panda-imap/Makefile under TOPS-20, nor do you build any components other than c-client and mtest. Merge the contents of -imap-2007/src/c-client, imap-2007/src/charset, imap-2007/src/mtest, and -imap-2007/src/osdep/tops-20 onto a single directory on TOPS-20 and build from +panda-imap/src/c-client, panda-imap/src/charset, panda-imap/src/mtest, and +panda-imap/src/osdep/tops-20 onto a single directory on TOPS-20 and build from that. The command: DO BUILD.CTL will build the sources. If you don't have MIC, then SUBMIT BUILD.CTL and let @@ -359,14 +366,14 @@ BATCON execute it. VMS BUILD NOTES - The VMS port has been tested with imap-2007, but as I am soon going + The VMS port has been tested with panda-imap, but as I am soon going to lose access to a VMS system I will no longer be able able to test and this port will be moved to the "other ports" category". - You do not use imap-2007/Makefile under VMS, nor do you build any + You do not use panda-imap/Makefile under VMS, nor do you build any components other than c-client and mtest. Merge the contents of -imap-2007/src/c-client, imap-2007/src/charset, imap-2007/src/mtest, and -imap-2007/src/osdep/vms onto a single directory on VMS and build from that. +panda-imap/src/c-client, panda-imap/src/charset, panda-imap/src/mtest, and +panda-imap/src/osdep/vms onto a single directory on VMS and build from that. The command to build it is: @BUILD MULTINET or @BUILD NETLIB @@ -379,20 +386,7 @@ wonderful VMS system that DEC loves so much doesn't maintain any concept of time zone; the VMS C compiler returns a null pointer from gmtime()! Otherwise you're pretty much on your own here. - - OTHER PORTS - - The following ports were developed at one time or another, but are no -longer actively developed or tested. It is not known if they still work or -not. - Port Status - ---- ------ -Macintosh Obsolete; Mac OS X uses UNIX port -DOS/Win16 Obsolete; modern PCs use Win32 port -Windows CE Never completed -Amiga Unknown -OS/2 Unknown MACINTOSH BUILD NOTES @@ -401,10 +395,10 @@ OS/2 Unknown If you are building a Macintosh client, you will need MacTCP installed on your system as well as the MacTCP C includes and libraries. - You do not use imap-2007/Makefile on the Mac, nor do you build any + You do not use panda-imap/Makefile on the Mac, nor do you build any components other than c-client and mtest. Merge the contents of -imap-2007/src/c-client, imap-2007/src/charset, imap-2007/src/mtest, and -imap-2007/src/osdep/mac onto a single directory on the Mac and build from +panda-imap/src/c-client, panda-imap/src/charset, panda-imap/src/mtest, and +panda-imap/src/osdep/mac onto a single directory on the Mac and build from that. mtext.sit.hqx is a THINK C project file and cute icon for building mtest, encoded with Binhex and StuffIt. @@ -451,10 +445,10 @@ on your DOS system along with its development environment. The currently supported stacks are Beame & Whiteside, PC-NFS, Novell, PC/IP, Waterloo, and Winsock. mtest and a version of Pine called PC Pine run under DOS. - You do not use imap-2007/Makefile under DOS, nor do you build any + You do not use panda-imap/Makefile under DOS, nor do you build any components other than c-client and mtest. Merge the contents of -imap-2007/src/c-client, imap-2007/src/charset, imap-2007/src/mtest, and -imap-2007/src/osdep/dos onto a single directory on DOS and build from that. +panda-imap/src/c-client, panda-imap/src/charset, panda-imap/src/mtest, and +panda-imap/src/osdep/dos onto a single directory on DOS and build from that. The MAKE command on DOS takes an argument identifying the TCP/IP stack in use. For example, do: MAKE MAKEFILE OS=WSK (or MAKE -F MAKEFILE OS=WSK) @@ -474,7 +468,7 @@ least install Win32s. I build using Visual C++ 6.0 with the WCE extensions. The current code has SH3 wired in for the compiler building. - To build under NT, connect to the imap-2007 directory and do: + To build under NT, connect to the panda-imap directory and do: nmake -f makefile.wce The only binary produced is a cclient.lib file. I haven't gotten as far diff --git a/imap/docs/FAQ.html b/imap/docs/FAQ.html index 12a9feac..27d42aa4 100644 --- a/imap/docs/FAQ.html +++ b/imap/docs/FAQ.html @@ -1,5 +1,11 @@ +<html> <!-- * ======================================================================== + * Copyright 2008-2010 Mark Crispin + * ======================================================================== + * + * Previous versions of this file were: + * * Copyright 1988-2007 University of Washington * * Licensed under the Apache License, Version 2.0 (the "License"); @@ -12,14 +18,25 @@ * ======================================================================== * --> - -<!--chtml set title="IMAP Toolkit Frequently Asked Questions"--> -<!--chtml include "//imap/incs/top.inc"--> +<head> +<meta name="description" content="Panda IMAP Frequently Asked Questions"> +<meta name="keywords" content="IMAP, Panda IMAP, Panda imapd, imap-2010, imap-2009, imap-2008, imap-2007b, imap-2007e, UW imapd, UW IMAP"> +<title>Panda Programming IMAP Home Page</TITLE> +<meta HTTP-EQUIV="Content-Type" CONTENT="text/html"; charset="ISO-8859-1"> +</head> +<body> +<h1 ALIGN="center"> +<img SRC="http://panda.com/blue.gif"> +<i>Panda IMAP Frequently Asked Questions</I> +</H1> <h2>Table of Contents</h2> <ul> <li> + <a href="#panda">What is Panda IMAP?</a> + </li> + <li> <a href="#general">1. General/Software Feature Questions</a> <ul> @@ -567,7 +584,7 @@ connected to the IMAP or POP server, no matter what client I use?</a></li> - <li><a href="#7.25">7.25 Why is there a long delay in Pine or any + <li><a href="#7.25">7.25 Why is there a long delay in Alpine or any other c-client based application call before I get connected to the IMAP server? The hang seems to be in the c-client mail_open() call. I don't have this problem with any other IMAP client. There is no delay @@ -639,7 +656,7 @@ </li> <li><a href="#7.34">7.34 Why does reading certain messages hang when - using Netscape? It works fine with Pine!</a></li> + using Netscape? It works fine with Alpine!</a></li> <li><a href="#7.35">7.35 Why does Netscape say that there's a problem with the IMAP server and that I should "Contact your mail server @@ -667,7 +684,7 @@ clients out there?</a></li> <li> - <a href="#7.43">7.43 But wait! PC Pine (or other PC program build + <a href="#7.43">7.43 But wait! PC Alpine (or other PC program build with c-client) crashes with the message <ul> @@ -676,7 +693,7 @@ </li> <li><a href="#7.44">7.44 My qpopper users keep on getting the DON'T - DELETE THIS MESSAGE -- FOLDER INTERNAL DATA if they also use Pine or + DELETE THIS MESSAGE -- FOLDER INTERNAL DATA if they also use Alpine or IMAP. How can I fix this?</a></li> <li><a href="#7.45">7.45 Help! I installed the servers but I can't @@ -736,6 +753,21 @@ </ul><!--=======START BODY--> <hr> + <h2><a name="panda">What is Panda IMAP?</a></h2> + <dl> + <dd> + Panda IMAP is a fork of the final University of Washington version + (imap-2007b). The current UW version is imap-2007e which has only + minor changes from imap-2007b. All of these changes (or something + better) are in Panda IMAP. + + <p>Panda IMAP is available by donation. + +</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> <h2><a name="general">1. General/Software Feature Questions</a></h2> <hr> @@ -773,7 +805,7 @@ to do this, you'll know. There also seems to be a way to make qpopper work better with imapd; see the answer to the <a href="#7.44">My qpopper users keep on getting the DON'T DELETE THIS MESSAGE -- FOLDER - INTERNAL DATA if they also use Pine or IMAP. How can I fix this?</a> + INTERNAL DATA if they also use Alpine or IMAP. How can I fix this?</a> question.</p> </dd> </dl> @@ -825,7 +857,7 @@ <p>If IMAP2 (RFC 1176) is good enough for you, you can use MAPSER which is about the ultimate gonzo pure TOPS-20 extended addressing assembly - language program. Unfortunately, IMAP2 is barely good enough for Pine + language program. Unfortunately, IMAP2 is barely good enough for Alpine these days, and most other IMAP clients won't work with IMAP2 at all. Maybe someone will hack MAPSER to do IMAP4rev1 some day.</p> @@ -863,7 +895,7 @@ directory and each message is a file within that directory; these formats support sub-mailboxes within such mailboxes. However, for technical reasons, the "flat file" formats are generally preferred - since they perform better. Read imap-2007/docs/formats.txt for more + since they perform better. Read imap-2010/docs/formats.txt for more information on this topic.</p> <p>It is always permissible to create a directory that is not a @@ -1101,15 +1133,7 @@ <dl> <dd> - Kerberos V4 is not supported. Kerberos V4 client-only contributed code - is available in - <pre> -<a href= -"ftp://ftp.cac.washington.edu/mail/kerberos4-patches.tar.Z">ftp://ftp.cac.washington.edu/mail/kerberos4-patches.tar.Z -</a> -</pre>This is a patchkit which must be applied to the IMAP toolkit according -to the instructions in the patchkit's README. We can not promise that this -code works. + Kerberos V4 is not supported. </dd> </dl> @@ -1377,12 +1401,12 @@ code works. <dl> <dd> - imap-2007 supports SSL and TLS client functionality on UNIX and 32-bit + imap-2010 supports SSL and TLS client functionality on UNIX and 32-bit Windows for IMAP, POP3, SMTP, and NNTP; and SSL and TLS server functionality on UNIX for IMAP and POP3. <p>UNIX SSL build requires that a third-party software package, - OpenSSL, be installed on the system first. Read imap-2007/docs/SSLBUILD + OpenSSL, be installed on the system first. Read imap-2010/docs/SSLBUILD for more information.</p> <p>SSL is supported via undocumented Microsoft interfaces in Windows 9x @@ -1427,7 +1451,7 @@ code works. <dl> <dd> - imap-2007 supports client and server functionality on UNIX and 32-bit + imap-2010 supports client and server functionality on UNIX and 32-bit Windows. <p>Kerberos V5 is supported by default in Windows 2000 builds:</p> @@ -1749,7 +1773,7 @@ mtest.c:515: the `gets' function is dangerous and should not be used. <p>By the way, if you need a more advanced example of c-client programming than mtest (and you probably will), I recommend that you - look at the source code for imapd and Pine.</p> + look at the source code for imapd and Alpine.</p> </dd> </dl> @@ -1875,13 +1899,13 @@ mtest.c:515: the `gets' function is dangerous and should not be used. <hr> <p><a name="4.5"><strong>4.5 How do I use one of the alternative formats - described in the formats.txt document? In particular, I hear that mbx + described in the formats.txt document? In particular, I hear that mix format will give me better performance and allow shared access.</strong></a></p> <dl> <dd> - The rumors about mbx format being preferred are true. It is faster than + The rumors about mix format being preferred are true. It is faster than the traditional UNIX mailbox format and permits shared access. <p>However, and this is <em>very important</em>, note that using an @@ -1891,12 +1915,12 @@ mtest.c:515: the `gets' function is dangerous and should not be used. off not going this route until you are more comfortable with your understanding.</p> - <p>Some of the formats, including mbx, are only supported by the + <p>Some of the formats, including mix, are only supported by the software based on the c-client library, and are not recognized by other - mailbox programs. The "vi" editor will corrupt any mbx format mailbox - that it encounters.</p> + mailbox programs. The "vi" editor may corrupt mailboxes written in these + formats.</p> - <p>Another problem is that the certain formats, including mbx, use + <p>Another problem is that the certain formats, including mix and mbx, use advanced file access and locking techniques that do <em>not</em> work reliably with NFS. NFS is not a real filesystem. Use IMAP instead of NFS for distributed access.</p> @@ -1906,36 +1930,36 @@ mtest.c:515: the `gets' function is dangerous and should not be used. become:</p> <ul> - <li>The simplest way to create a mbx-format mailbox is to prefix the - name with "#driver.mbx/" when creating a mailbox through c-client. - For example, if you create "#driver.mbx/foo", the mailbox "foo" will - be created in mbx format. Only use "#driver.mbx/" when creating the + <li>The simplest way to create a mix-format mailbox is to prefix the + name with "#driver.mix/" when creating a mailbox through c-client. + For example, if you create "#driver.mix/foo", the mailbox "foo" will + be created in mix format. Only use "#driver.mix/" when creating the mailbox. At all other times, just use the name ("foo" in this - example); the software will automatically select the driver for mbx + example); the software will automatically select the driver for mix whenever that mailbox is accessed without you doing anything else.</li> <li>You can use the "mailutil copy" command to copy an existing - mailbox to a new mailbox in mbx format. Read the man page provided + mailbox to a new mailbox in mix format. Read the man page provided with the mailutil program for details.</li> - <li>If you create an mbx-format INBOX, by creating - "#driver.mbx/INBOX" (note that "INBOX" must be all uppercase), then + <li>If you create an mix-format INBOX, by creating + "#driver.mix/INBOX" (note that "INBOX" must be all uppercase), then subsequent access to INBOX by any c-client based application will use - the mbx-format INBOX. Any mail delivered to the traditional format + the mix-format INBOX. Any mail delivered to the traditional format mailbox in the spool directory (e.g. /var/spool/mail/$USER) will - automatically be copied into the mbx-format INBOX and the spool + automatically be copied into the mix-format INBOX and the spool directory copy removed.</li> - <li>You can cause any newly-created mailboxes to be in mbx-format by + <li>You can cause any newly-created mailboxes to be in mix-format by default by changing the definition of CREATEPROTO=unixproto to be - CREATEPROTO=mbxproto in src/osdep/unix/Makefile, then rebuilding the + CREATEPROTO=mixproto in src/osdep/unix/Makefile, then rebuilding the IMAP toolkit (do a "make clean" first). Do not change EMPTYPROTO, - since mbx format mailboxes are never a zero-byte file. If you use - Pine or the imap-utils, you should probably also rebuild them with - the new IMAP toolkit too.</li> + since mix format mailboxes are directories and thus are never a + zero-byte file. If you use Alpine or the imap-utils, you should + probably also rebuild them with the new IMAP toolkit too.</li> - <li>You can deliver directly to the mbx-format INBOX by use of the + <li>You can deliver directly to the mix-format INBOX by use of the tmail or dmail programs. tmail is for direct invocation from sendmail (or whatever MTA program you use); dmail is for calls from procmail. Both of these programs have man pages which must be read carefully @@ -1957,8 +1981,7 @@ mtest.c:515: the `gets' function is dangerous and should not be used. <p>A number of sites have done full-fledged format conversions, and are reportedly quite happy with the results. Feel free to ask in the - comp.mail.imap newsgroup or the imap-uw mailing list for advice or - help.</p> + comp.mail.imap newsgroup for help.</p> </dd> </dl> @@ -1978,7 +2001,7 @@ mtest.c:515: the `gets' function is dangerous and should not be used. </pre> <p>You may want to consider the use of a mailbox format which permits - multiple simultaneous read/write sessions, such as the mbx format. The + multiple simultaneous read/write sessions, such as the mix format. The traditional UNIX format only allows one read/write session to a mailbox at a time.</p> @@ -2122,9 +2145,12 @@ mtest.c:515: the `gets' function is dangerous and should not be used. your software hasn't been updated in a while, it would "rot" -- tend to acquire problems that it didn't have when it was new.</p> - <p>The latest release version of the IMAP toolkit is always available - at <a href= - "ftp://ftp.cac.washington.edu/mail/imap.tar.Z">ftp://ftp.cac.washington.edu/mail/imap.tar.Z</a></p> + <p>Unfortunately, UW IMAP is rapidly succumbing to "software rot", as + it is no longer being developed or maintained. If you have not yet + switched to Panda IMAP, you should seriously consider doing so. + + <p>Panda IMAP is available by donation. Donors are given a URL which + they can use to download Panda IMAP, including future versions. </dd> </dl> @@ -2412,7 +2438,7 @@ for better performance. <p>Microsoft has developed a hotfix for this bug. Look up MSKB article number 300562. Contrary to the article text which implies that this is - a Pine issue, this bug also affects Microsoft Exchange server with + a Alpine issue, this bug also affects Microsoft Exchange server with <em>any</em> client that transmits full-sized SSL payloads.</p> </dd> </dl> @@ -2993,7 +3019,7 @@ most traditional format and nobody will flame you for using it. the directory by itself, it will try to call mlock to do it. I do not recommend doing this for performance reasons.</p> - <p>A sample mlock program is included as part of imap-2007. We have + <p>A sample mlock program is included as part of imap-2010. We have tried to make this sample program secure, but it has not been thoroughly audited.</p> </dd> @@ -3193,7 +3219,7 @@ header, and delete everything from the error point to that internal header. <p>Now, remove the erroneous data:</p> <ul> - <li>Verify that you can open INBOX.new in IMAP or Pine.</li> + <li>Verify that you can open INBOX.new in IMAP or Alpine.</li> <li>The last message of INBOX.new is probably corrupted. Copy it to another file, such as badmsg.1, then delete and expunge that last @@ -3215,7 +3241,7 @@ header, and delete everything from the error point to that internal header. <li>You no longer need INBOX.tail. Delete it.</li> - <li>Verify that you can open INBOX.new in IMAP or Pine.</li> + <li>Verify that you can open INBOX.new in IMAP or Alpine.</li> </ul> <p>Reinstall INBOX.new as INBOX:</p> @@ -3402,7 +3428,7 @@ header, and delete everything from the error point to that internal header. mail.</p> <p>The solution to both situations is to replace the client with a good - online IMAP client such as Pine. Life is too short to waste on POP + online IMAP client such as Alpine. Life is too short to waste on POP clients and poorly-designed IMAP clients.</p> </dd> </dl> @@ -3425,9 +3451,9 @@ header, and delete everything from the error point to that internal header. <p>This behavior has also been observed in some third-party c-client drivers, including maildir drivers. Consequently, this problem has even - been observed in Pine. It is important to understand that this is not a - problem in Pine or c-client; it is a problem in the third-party driver. - A Pine built without that third-party driver will not have this + been observed in Alpine. It is important to understand that this is not a + problem in Alpine or c-client; it is a problem in the third-party driver. + A Alpine built without that third-party driver will not have this problem.</p> <p>See also the answer to <a href="#7.73">Why does my IMAP client show @@ -3468,7 +3494,7 @@ header, and delete everything from the error point to that internal header. to "some other file"; in fact, you can use IMAP to access any file. <p>Most clients have an option to configure your connected directory on - the IMAP server. For example, in Pine you can specify this as the + the IMAP server. For example, in Alpine you can specify this as the "Path" in your folder-collection, e.g.</p> <pre> Nickname : Secondary Folders @@ -3549,7 +3575,7 @@ which they occur. Don't be shy about it. <p><a href="#top">Back to top</a></p> <hr> - <p><a name="7.25"><strong>7.25 Why is there a long delay in Pine or any other + <p><a name="7.25"><strong>7.25 Why is there a long delay in Alpine or any other c-client based application call before I get connected to the IMAP server? The hang seems to be in the c-client mail_open() call. I don't have this problem with any other IMAP client. There is no delay @@ -3765,7 +3791,7 @@ interpreted by mail reading software as an internal header line. <hr> <p><a name="7.34"><strong>7.34 Why does reading certain messages hang when using - Netscape? It works fine with Pine!</strong></a></p> + Netscape? It works fine with Alpine!</strong></a></p> <dl> <dd> @@ -3805,7 +3831,7 @@ interpreted by mail reading software as an internal header line. <p>You can work around this by rebuilding imapd with the <strong>NETSCAPE_BRAIN_DAMAGE</strong> option set (see src/imapd/Makefile) to a URL that points either to an alternative IMAP - client (e.g. Pine) or perhaps to a homebrew mail account management + client (e.g. Alpine) or perhaps to a homebrew mail account management page.</p> </dd> </dl> @@ -3952,9 +3978,9 @@ interpreted by mail reading software as an internal header line. <dd> Yes! - <p>Pine is a <em>wonderful</em> client. It's fast, it uses IMAP well, + <p>Alpine is a <em>wonderful</em> client. It's fast, it uses IMAP well, and it generates text mail (life is too short to waste on HTML mail). - Also, there are some really wonderful things in progress in the Pine + Also, there are some really wonderful things in progress in the Alpine world.</p> <p>There are some good GUI clients out there, mostly from smaller @@ -3971,7 +3997,7 @@ interpreted by mail reading software as an internal header line. <p><a href="#top">Back to top</a></p> <hr> - <p><a name="7.43"><strong>7.43 But wait! PC Pine (or other PC program build with + <p><a name="7.43"><strong>7.43 But wait! PC Alpine (or other PC program build with c-client) crashes with the message</strong> <tt>incomplete SecBuffer exceeds maximum buffer size</tt> <strong>when I use SSL connections. This is a bug in c-client, right?</strong></a></p> @@ -3983,7 +4009,7 @@ interpreted by mail reading software as an internal header line. compliant"). The problem is that SChannel indicates that the maximum SSL packet data size is 5 bytes smaller than the actual maximum. Thus, any IMAP server which transmits a maximum sized SSL packet will not - work with PC Pine or any other program which uses SChannel. + work with PC Alpine or any other program which uses SChannel. <p>It can take a while for the problem to show up. The client has to do something that causes at least 16K of contiguous data. Many clients do @@ -3999,14 +4025,14 @@ interpreted by mail reading software as an internal header line. data to less than 16K, in order to work around the problem.</p> <p>This problem has also shown up with the Exchange IMAP server with - UNIX clients (including Pine built with an older version of c-client) + UNIX clients (including Alpine built with an older version of c-client) which sends full-sized 16K SSL packets. Modern c-client works around the problem by trimming down its maximum outgoing SSL packet size to 8K.</p> <p>Microsoft has developed a hotfix for this bug. Look up MSKB article number 300562. Contrary to the article text which implies that this is - a Pine issue, this bug also affect Microsoft Exchange server with *any* + a Alpine issue, this bug also affect Microsoft Exchange server with *any* UNIX based client that transmits full-sized SSL payloads.</p> </dd> </dl> @@ -4015,13 +4041,13 @@ interpreted by mail reading software as an internal header line. <hr> <p><a name="7.44"><strong>7.44 My qpopper users keep on getting the DON'T DELETE - THIS MESSAGE -- FOLDER INTERNAL DATA if they also use Pine or IMAP. How + THIS MESSAGE -- FOLDER INTERNAL DATA if they also use Alpine or IMAP. How can I fix this?</strong></a></p> <dl> <dd> This is an incompatibility between qpopper and the c-client library - used by Pine, imapd, and ipop[23]d. + used by Alpine, imapd, and ipop[23]d. <p>Assuming that you want to continue using qpopper, look into qpopper's <strong>--enable-uw-kludge-flag</strong> configuration flag, @@ -4174,18 +4200,7 @@ words, it is a protocol syntax error. subscribe to this list via <a href= "mailto:imap-protocol-request@u.washington.edu"><tt>imap-protocol-request@u.washington.edu</tt></a> - <p>If you have questions about this software, you can send me email - directly or use the imap-uw@u.washington.edu mailing list. You can - subscribe to this list via <a href= - "mailto:imap-uw-request@u.washington.edu"><tt>imap-uw-request@u.washington.edu</tt></a></p> - - <p>If you have general questions about the use of IMAP software - (not specific to the UW IMAP toolkit) use the - imap-use@u.washington.edu mailing list. You can subscribe to - this list via <a href= - "mailto:imap-use-request@u.washington.edu"><tt>imap-use-request@u.washington.edu</tt></a></p> - - <p>You must be a subscriber to post to these lists. As an + <p>You must be a subscriber to post to this list. As an alternative, you can use the <strong>comp.mail.imap</strong> newsgroup.</p> </dd> @@ -4212,15 +4227,12 @@ words, it is a protocol syntax error. <dd> We recommend <em>Managing IMAP</em>, by Dianna Mullet & Kevin Mullet, published by O'Reilly, ISBN 0-596-00012-X. - - <p>This book also has an excellent comparison of the UW and Cyrus IMAP - servers.<br></p> </dd> </dl> <p><a href="#top">Back to top</a></p> - <p>Last Updated: 15 November 2007</p> + <p>Last Updated: 5 May 2010</p> <!--chtml include "//imap/incs/bottom.inc"--> diff --git a/imap/docs/FAQ.txt b/imap/docs/FAQ.txt index 797bed09..a952f1e3 100644 --- a/imap/docs/FAQ.txt +++ b/imap/docs/FAQ.txt @@ -1,26 +1,15 @@ -/* ======================================================================== - * Copyright 1988-2007 University of Washington - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * - * ======================================================================== - */ - - IMAP Toolkit Frequently Asked Questions + + Panda IMAP Frequently Asked Questions Table of Contents + * What is Panda IMAP? * 1. General/Software Feature Questions + 1.1 Can I set up a POP or IMAP server on UNIX/Linux/OSF/etc.? - + 1.2 I am currently using qpopper as my POP3 server on UNIX. - Do I need to replace it with ipop3d in order to run imapd? - + 1.3 Can I set up a POP or IMAP server on Windows XP, 2000, - NT, Me, 98, or 95? + + 1.2 I am currently using qpopper as my POP3 server on UNIX. Do + I need to replace it with ipop3d in order to run imapd? + + 1.3 Can I set up a POP or IMAP server on Windows XP, 2000, NT, + Me, 98, or 95? + 1.4 Can I set up a POP or IMAP server on Windows 3.1 or DOS? + 1.5 Can I set up a POP or IMAP server on Macintosh? + 1.6 Can I set up a POP or IMAP server on VAX/VMS? @@ -57,8 +46,8 @@ Table of Contents + 2.1 What do I need to build this software with SSL on UNIX? + 2.2 What do I need to build this software with Kerberos V on UNIX? - + 2.3 What do I need to use a C++ compiler with this software - to build my own application? + + 2.3 What do I need to use a C++ compiler with this software to + build my own application? + 2.4 What do I need to build this software on Windows? + 2.5 What do I need to build this software on DOS? + 2.6 Can't I use Borland C to build this software on the PC? @@ -97,14 +86,13 @@ Table of Contents sessions, but allow them in SSL or TLS sessions? + 3.19 How do I configure virtual hosts? + 3.20 Why do I get compiler warning messages such as: - o passing arg 3 of `scandir' from incompatible pointer - type + o passing arg 3 of `scandir' from incompatible pointer type o Pointers are not assignment-compatible. o Argument #4 is not the correct type. during the build? + 3.21 Why do I get compiler warning messages such as - o Operation between types "void(*)(int)" and "void*" is - not allowed. + o Operation between types "void(*)(int)" and "void*" is not + allowed. o Function argument assignment between types "void*" and "void(*)(int)" is not allowed. o Pointers are not assignment-compatible. @@ -130,9 +118,9 @@ Table of Contents server? I noticed that it can connect on port 143, port 993, via rsh, and via ssh. + 4.4 I am using a TLS-capable IMAP server, so I don't need to - use /ssl to get encryption. However, I want to be certain - that my session is TLS encrypted before I send my password. - How to I do this? + use /ssl to get encryption. However, I want to be certain that + my session is TLS encrypted before I send my password. How to + I do this? + 4.5 How do I use one of the alternative formats described in the formats.txt document? In particular, I hear that mbx format will give me better performance and allow shared @@ -141,9 +129,8 @@ Table of Contents + 4.7 How can I make the server syslogs go to someplace other than the mail syslog? * 5. Security Questions - + 5.1 I see that the IMAP server allows access to arbitary - files on the system, including /etc/passwd! How do I disable - this? + + 5.1 I see that the IMAP server allows access to arbitary files + on the system, including /etc/passwd! How do I disable this? + 5.2 I've heard that IMAP servers are insecure. Is this true? + 5.3 How do I know that I have the most secure version of the server? @@ -177,8 +164,8 @@ Table of Contents "From " to be the start of the message. + 6.13 Why is traditional UNIX format the default format? + 6.14 Why do you write this "DON'T DELETE THIS MESSAGE -- - FOLDER INTERNAL DATA" message at the start of traditional - UNIX and MMDF format mailboxes? + FOLDER INTERNAL DATA" message at the start of traditional UNIX + and MMDF format mailboxes? + 6.15 Why don't you stash the mailbox metadata in the first real message of the mailbox instead of writing this fake FOLDER INTERNAL DATA message? @@ -201,8 +188,8 @@ Table of Contents and how do I fix it? + 7.4 Why can't I log in to the server? The user name and password are right! - + 7.5 Help! My load average is soaring and I see hundreds of - POP and IMAP servers, many logged in as the same user! + + 7.5 Help! My load average is soaring and I see hundreds of POP + and IMAP servers, many logged in as the same user! + 7.6 Why does mail disappear even though I set "keep mail on server"? + 7.7 Why do I get the message @@ -224,8 +211,8 @@ Table of Contents + 7.12 What does the message: o Can't get write access to mailbox, access is readonly mean? - + 7.13 I set my POP3 client to "delete messages from server" - but they never get deleted. What is wrong? + + 7.13 I set my POP3 client to "delete messages from server" but + they never get deleted. What is wrong? + 7.14 What do messages such as: o Message ... UID ... already has UID ... o Message ... UID ... less than ... @@ -248,8 +235,8 @@ Table of Contents mean? When it happens, the listed service shuts down. How can I fix this? + 7.17 What does the syslog message: - o Mailbox lock file /tmp/.600.1df3 open failure: - Permission denied + o Mailbox lock file /tmp/.600.1df3 open failure: Permission + denied mean? + 7.18 What do the syslog messages: o Command stream end of file, while reading line user=... @@ -262,22 +249,21 @@ Table of Contents + 7.19 Why did my POP or IMAP session suddenly disconnect? The syslog has the message: o Killed (lost mailbox lock) user=... host=... - + 7.20 Why does my IMAP client show all the files on the - system, recursively from the UNIX root directory? - + 7.21 Why does my IMAP client show all of my files, - recursively from my UNIX home directory? + + 7.20 Why does my IMAP client show all the files on the system, + recursively from the UNIX root directory? + + 7.21 Why does my IMAP client show all of my files, recursively + from my UNIX home directory? + 7.22 Why does my IMAP client show that I have mailboxes named "#mhinbox", "#mh", "#shared", "#ftp", "#news", and "#public"? + 7.23 Why does my IMAP client show all my files in my home directory? + 7.24 Why is there a long delay before I get connected to the IMAP or POP server, no matter what client I use? - + 7.25 Why is there a long delay in Pine or any other c-client + + 7.25 Why is there a long delay in Alpine or any other c-client based application call before I get connected to the IMAP - server? The hang seems to be in the c-client mail_open() - call. I don't have this problem with any other IMAP client. - There is no delay connecting to a POP3 or NNTP server with - mail_open(). + server? The hang seems to be in the c-client mail_open() call. + I don't have this problem with any other IMAP client. There is + no delay connecting to a POP3 or NNTP server with mail_open(). + 7.26 Why does a message sometimes get split into two or more messages on my SUN system? + 7.27 Why did my POP or IMAP session suddenly disconnect? The @@ -307,7 +293,7 @@ Table of Contents certificate mean? + 7.34 Why does reading certain messages hang when using - Netscape? It works fine with Pine! + Netscape? It works fine with Alpine! + 7.35 Why does Netscape say that there's a problem with the IMAP server and that I should "Contact your mail server administrator."? @@ -323,15 +309,15 @@ Table of Contents connection has been broken, and in the server syslogs I see "Command stream end of file". + 7.42 Sheesh. Aren't there any good IMAP clients out there? - + 7.43 But wait! PC Pine (or other PC program build with + + 7.43 But wait! PC Alpine (or other PC program build with c-client) crashes with the message o incomplete SecBuffer exceeds maximum buffer size when I use SSL connections. This is a bug in c-client, right? + 7.44 My qpopper users keep on getting the DON'T DELETE THIS - MESSAGE -- FOLDER INTERNAL DATA if they also use Pine or + MESSAGE -- FOLDER INTERNAL DATA if they also use Alpine or IMAP. How can I fix this? - + 7.45 Help! I installed the servers but I can't connect to - them from my client! + + 7.45 Help! I installed the servers but I can't connect to them + from my client! + 7.46 Why do I get the message o Can not authenticate to SMTP server: 421 SMTP connection went away! @@ -346,22 +332,35 @@ Table of Contents when I try to authenticate to a Cyrus server? * 8. Where to Go For Additional Information + 8.1 Where can I go to ask questions? - + 8.2 I have some ideas for enhancements to IMAP. Where should - I go? + + 8.2 I have some ideas for enhancements to IMAP. Where should I + go? + 8.3 Where can I read more about IMAP and other email protocols? + 8.4 Where can I find out more about setting up and administering an IMAP server? - _________________________________________________________________ + __________________________________________________________________ + +What is Panda IMAP? + + Panda IMAP is a fork of the final University of Washington + version (imap-2007b). The current UW version is imap-2007e which + has only minor changes from imap-2007b. All of these changes (or + something better) are in Panda IMAP. + + Panda IMAP is available by donation. + + Back to top + __________________________________________________________________ 1. General/Software Feature Questions - _________________________________________________________________ + __________________________________________________________________ 1.1 Can I set up a POP or IMAP server on UNIX/Linux/OSF/etc.? - Yes. Refer to the UNIX specific notes in files CONFIG and - BUILD. - _________________________________________________________________ + Yes. Refer to the UNIX specific notes in files CONFIG and BUILD. + + Back to top + __________________________________________________________________ 1.2 I am currently using qpopper as my POP3 server on UNIX. Do I need to replace it with ipop3d in order to run imapd? @@ -371,8 +370,8 @@ Table of Contents Although ipop3d interoperates with imapd better than qpopper, imapd and qpopper will work together. The few qpopper/imapd interoperability issues mostly affect users who use both IMAP - and POP3 clients; those users would probably be better served - if their POP3 server is ipop3d. + and POP3 clients; those users would probably be better served if + their POP3 server is ipop3d. If you are happy with qpopper and just want to add imapd, you should do that, and defer a decision on changing qpopper to @@ -380,20 +379,22 @@ Table of Contents performance, without changing anything for your qpopper users. Many sites have subsequently decided to change from qpopper to - ipop3d in order to get better POP3/IMAP interoperability. If - you need to do this, you'll know. There also seems to be a way - to make qpopper work better with imapd; see the answer to the - My qpopper users keep on getting the DON'T DELETE THIS MESSAGE - -- FOLDER INTERNAL DATA if they also use Pine or IMAP. How can - I fix this? question. - _________________________________________________________________ + ipop3d in order to get better POP3/IMAP interoperability. If you + need to do this, you'll know. There also seems to be a way to + make qpopper work better with imapd; see the answer to the My + qpopper users keep on getting the DON'T DELETE THIS MESSAGE -- + FOLDER INTERNAL DATA if they also use Alpine or IMAP. How can I + fix this? question. + + Back to top + __________________________________________________________________ 1.3 Can I set up a POP or IMAP server on Windows XP, 2000, NT, Me, 98, or 95? Yes. Refer to the NT specific notes in files CONFIG and BUILD. - Also, for DOS-based versions of Windows (Windows Me, 98, and - 95) you *must* set up CRAM-MD5 authentication, as described in + Also, for DOS-based versions of Windows (Windows Me, 98, and 95) + you *must* set up CRAM-MD5 authentication, as described in md5.txt. There is no file access control on Windows 9x or Me, so you @@ -402,14 +403,18 @@ Table of Contents Note, however, that the server is not plug and play the way it is for UNIX. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.4 Can I set up a POP or IMAP server on Windows 3.1 or DOS? 1.5 Can I set up a POP or IMAP server on Macintosh? 1.6 Can I set up a POP or IMAP server on VAX/VMS? Yes, it's just a small matter of programming. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.7 Can I set up a POP or IMAP server on TOPS-20? @@ -418,7 +423,7 @@ Table of Contents If IMAP2 (RFC 1176) is good enough for you, you can use MAPSER which is about the ultimate gonzo pure TOPS-20 extended addressing assembly language program. Unfortunately, IMAP2 is - barely good enough for Pine these days, and most other IMAP + barely good enough for Alpine these days, and most other IMAP clients won't work with IMAP2 at all. Maybe someone will hack MAPSER to do IMAP4rev1 some day. @@ -428,7 +433,9 @@ Table of Contents Or you can port the POP and IMAP server from this IMAP toolkit to it. All that you need for a first stab is to port the MTX driver. That'll probably be just a couple of hours of hacking. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.8 Are hierarchical mailboxes supported? 1.9 Are "dual-use" mailboxes supported? @@ -449,22 +456,24 @@ Table of Contents directory; these formats support sub-mailboxes within such mailboxes. However, for technical reasons, the "flat file" formats are generally preferred since they perform better. Read - imap-2007/docs/formats.txt for more information on this topic. + imap-2010/docs/formats.txt for more information on this topic. It is always permissible to create a directory that is not a mailbox, and have sub-mailboxes under it. The easiest way to - create a directory is to create a new mailbox inside a - directory that doesn't already exist. For example, if you - create "Mail/testbox" on UNIX, the directory "Mail/" will - automatically be created and then the mailbox "testbox" will be - created as a sub-mailbox of "Mail/". + create a directory is to create a new mailbox inside a directory + that doesn't already exist. For example, if you create + "Mail/testbox" on UNIX, the directory "Mail/" will automatically + be created and then the mailbox "testbox" will be created as a + sub-mailbox of "Mail/". It is also possible to create the name "Mail/" directly. Check - the documentation for your client software to see how to do - this with that software. + the documentation for your client software to see how to do this + with that software. Of course, on Windows systems you would use "\" instead of "/". - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.11 What is the difference between "mailbox" and "folder"? @@ -479,10 +488,12 @@ Table of Contents although some mailbox formats will permit this. In IMAP-speak, a mailbox which can not contain other mailboxes - is called a "no-inferiors mailbox". Similarly, a directory - which can not contain messages is not a mailbox and is called a + is called a "no-inferiors mailbox". Similarly, a directory which + can not contain messages is not a mailbox and is called a "no-select name". - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.12 What is the status of internationalization? @@ -492,15 +503,14 @@ Table of Contents Searching is supported in the following charsets: US-ASCII, UTF-8, ISO-8859-1, ISO-8859-2, ISO-8859-3, ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8, ISO-8859-9, - ISO-8859-10, ISO-8859-11, ISO-8859-13, ISO-8859-14, - ISO-8859-15, ISO-8859-16, KOI8-R, KOI8-U (alias KOI8-RU), - TIS-620, VISCII, ISO-2022-JP, ISO-2022-KR, ISO-2022-CN, - ISO-2022-JP-1, ISO-2022-JP-2, GB2312 (alias CN-GB), - CN-GB-12345, BIG5 (alias CN-BIG5), EUC-JP, EUC-KR, Shift_JIS, - Shift-JIS, KS_C_5601-1987, KS_C_5601-1992, WINDOWS_874, - WINDOWS-1250, WINDOWS-1251, WINDOWS-1252, WINDOWS-1253, - WINDOWS-1254, WINDOWS-1255, WINDOWS-1256, WINDOWS-1257, - WINDOWS-1258. + ISO-8859-10, ISO-8859-11, ISO-8859-13, ISO-8859-14, ISO-8859-15, + ISO-8859-16, KOI8-R, KOI8-U (alias KOI8-RU), TIS-620, VISCII, + ISO-2022-JP, ISO-2022-KR, ISO-2022-CN, ISO-2022-JP-1, + ISO-2022-JP-2, GB2312 (alias CN-GB), CN-GB-12345, BIG5 (alias + CN-BIG5), EUC-JP, EUC-KR, Shift_JIS, Shift-JIS, KS_C_5601-1987, + KS_C_5601-1992, WINDOWS_874, WINDOWS-1250, WINDOWS-1251, + WINDOWS-1252, WINDOWS-1253, WINDOWS-1254, WINDOWS-1255, + WINDOWS-1256, WINDOWS-1257, WINDOWS-1258. All ISO-2022-?? charsets are treated identically, and support ASCII, JIS Roman, hankaku katakana, ISO-8859-[1 - 10], TIS, GB @@ -515,73 +525,97 @@ Table of Contents There is no support for localization (e.g. non-English error messages) at the present time, but such support is planned. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.13 Can I use SSL? Yes. See the answer to the How do I configure SSL? question. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.14 Can I use TLS and the STARTTLS facility? Yes. See the answer to the How do I configure TLS and the STARTTLS facility? question. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.15 Can I use CRAM-MD5 authentication? Yes. See the answer to the How do I configure CRAM-MD5 authentication? question. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.16 Can I use APOP authentication? Yes. See the How do I configure APOP authentication? question. Note that there is no client support for APOP authentication. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.17 Can I use Kerberos V5? Yes. See the answer to the How do I configure Kerberos V5? question. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.18 Can I use PAM for plaintext passwords? Yes. See the answer to the How do I configure PAM for plaintext passwords? question. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.19 Can I use Kerberos 5 for plaintext passwords? Yes. See the answer to the How do I configure Kerberos 5 for plaintext passwords? question. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.20 Can I use AFS for plaintext passwords? Yes. See the answer to the How do I configure AFS for plaintext passwords? question. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.21 Can I use DCE for plaintext passwords? Yes. See the answer to the How do I configure DCE for plaintext passwords? question. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.22 Can I use the CRAM-MD5 database for plaintext passwords? Yes. See the answer to the How do I configure the CRAM-MD5 database for plaintext passwords? question. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.23 Can I disable plaintext passwords? - Yes. See the answer to the How do I disable plaintext - passwords? question. - _________________________________________________________________ + Yes. See the answer to the How do I disable plaintext passwords? + question. + + Back to top + __________________________________________________________________ 1.24 Can I disable plaintext passwords on unencrypted sessions, but allow them on encrypted sessions? @@ -589,47 +623,52 @@ Table of Contents Yes. See the answer to the How do I disable plaintext passwords on unencrypted sessions, but allow them in SSL or TLS sessions? question. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.25 Can I use virtual hosts? Yes. See the answer to the How do I configure virtual hosts? question. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.26 Can I use RPOP authentication? There is no support for RPOP authentication. - _________________________________________________________________ - 1.27 Can I use Kerberos V4? + Back to top + __________________________________________________________________ - Kerberos V4 is not supported. Kerberos V4 client-only - contributed code is available in + 1.27 Can I use Kerberos V4? -ftp://ftp.cac.washington.edu/mail/kerberos4-patches.tar.Z + Kerberos V4 is not supported. - This is a patchkit which must be applied to the IMAP toolkit - according to the instructions in the patchkit's README. We can - not promise that this code works. - _________________________________________________________________ + Back to top + __________________________________________________________________ 1.28 Is there support for S/Key or OTP? There is currently no support for S/Key or OTP. There may be an OTP SASL authenticator available from third parties. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.29 Is there support for NTLM or SPA? - There is currently no support for NTLM or SPA, nor are there - any plans to add such support. In general, I avoid - vendor-specific mechanisms. I also believe that these - mechanisms are being deprecated by their vendor. + There is currently no support for NTLM or SPA, nor are there any + plans to add such support. In general, I avoid vendor-specific + mechanisms. I also believe that these mechanisms are being + deprecated by their vendor. There may be an NTLM SASL authenticator available from third parties. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.30 Is there support for mh? @@ -643,102 +682,131 @@ ftp://ftp.cac.washington.edu/mail/kerberos4-patches.tar.Z Non-legacy use of mh format is not encouraged. There is no support for permanent flags or unique identifiers; furthermore there are known severe performance problems with the mh format. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.31 Is there support for qmail and the maildir format? There is no support for qmail or the maildir format in our distribution, nor are there any plans to add such support. Maildir support may be available from third parties. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.32 Is there support for the Cyrus mailbox format? No. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 1.33 Is this software Y2K compliant? Please read the files Y2K and calendar.txt. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 2. What Do I Need to Build This Software? - _________________________________________________________________ + __________________________________________________________________ 2.1 What do I need to build this software with SSL on UNIX? You need to build and install OpenSSL first. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 2.2 What do I need to build this software with Kerberos V on UNIX? You need to build and install MIT Kerberos first. - _________________________________________________________________ - 2.3 What do I need to use a C++ compiler with this software to build - my own application? + Back to top + __________________________________________________________________ + + 2.3 What do I need to use a C++ compiler with this software to build my + own application? If you are building an application using the c-client library, use the new c-client.h file instead of including the other include files. It seems that c-client.h should define away all the troublesome names that conflict with C++. - If you use gcc, you may need to use -fno-operator-names as - well. - _________________________________________________________________ + If you use gcc, you may need to use -fno-operator-names as well. + + Back to top + __________________________________________________________________ 2.4 What do I need to build this software on Windows? - You need Microsoft Visual C++ 6.0, Visual C++ .NET, or Visual - C# .NET (which you can buy from any computer store), along with - the Microsoft Platform SDK (which you can download from - Microsoft's web site). + You need Microsoft Visual C++ 6.0, Visual C++ .NET, or Visual C# + .NET (which you can buy from any computer store), along with the + Microsoft Platform SDK (which you can download from Microsoft's + web site). You do not need to install the entire Platform SDK; it suffices to install just the Core SDK and the Internet Development SDK. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 2.5 What do I need to build this software on DOS? It's been several years since we last attempted to do this. At the time, we used Microsoft C. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 2.6 Can't I use Borland C to build this software on the PC? Probably not. If you know otherwise, please let us know. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 2.7 What do I need to build this software on the Mac? - It has been several years since we last attempted to do this. - At the time, we used Symantec THINK C; but today you'll need a - C compiler which allows segments to be more than 32K. - _________________________________________________________________ + It has been several years since we last attempted to do this. At + the time, we used Symantec THINK C; but today you'll need a C + compiler which allows segments to be more than 32K. + + Back to top + __________________________________________________________________ 2.8 What do I need to build this software on VMS? You need the VMS C compiler, and either the Multinet or Netlib TCP. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 2.9 What do I need to build this software on TOPS-20? You need the TOPS-20 KCC compiler. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 2.10 What do I need to build this software on Amiga or OS/2? We don't know. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 2.11 What do I need to build this software on Windows CE? This port is incomplete. Someone needs to finish it. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 3. Build and Configuration Questions - _________________________________________________________________ + __________________________________________________________________ 3.1 How do I configure the IMAP and POP servers on UNIX? 3.2 I built and installed the servers according to the BUILD @@ -754,32 +822,38 @@ ftp://ftp.cac.washington.edu/mail/kerberos4-patches.tar.Z Yes, it's that easy. There are some additional options, such as SSL or Kerberos, which require additional steps to build. See the relevant questions below. - _________________________________________________________________ - 3.3 How do I make the IMAP and POP servers look for INBOX at some - place other than the mail spool directory? + Back to top + __________________________________________________________________ + + 3.3 How do I make the IMAP and POP servers look for INBOX at some place + other than the mail spool directory? 3.4 How do I make the IMAP server look for secondary folders at some place other than the user's home directory? Please read the file CONFIG for discussion of this and other issues. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 3.5 How do I configure SSL? 3.6 How do I configure TLS and the STARTTLS facility? - imap-2007 supports SSL and TLS client functionality on UNIX and + imap-2010 supports SSL and TLS client functionality on UNIX and 32-bit Windows for IMAP, POP3, SMTP, and NNTP; and SSL and TLS server functionality on UNIX for IMAP and POP3. UNIX SSL build requires that a third-party software package, OpenSSL, be installed on the system first. Read - imap-2007/docs/SSLBUILD for more information. + imap-2010/docs/SSLBUILD for more information. SSL is supported via undocumented Microsoft interfaces in - Windows 9x and NT4; and via standard interfaces in Windows - 2000, Windows Millenium, and Windows XP. - _________________________________________________________________ + Windows 9x and NT4; and via standard interfaces in Windows 2000, + Windows Millenium, and Windows XP. + + Back to top + __________________________________________________________________ 3.7 How do I build/install OpenSSL and obtain/create certificates for use with SSL? @@ -787,7 +861,9 @@ ftp://ftp.cac.washington.edu/mail/kerberos4-patches.tar.Z If you need help in doing this, try the contacts mentioned in the OpenSSL README. We do not offer support for OpenSSL or certificates. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 3.8 How do I configure CRAM-MD5 authentication? 3.9 How do I configure APOP authentication? @@ -797,11 +873,13 @@ ftp://ftp.cac.washington.edu/mail/kerberos4-patches.tar.Z CRAM-MD5 and APOP authentication on UNIX and NT servers. There is no support for APOP client authentication. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 3.10 How do I configure Kerberos V5? - imap-2007 supports client and server functionality on UNIX and + imap-2010 supports client and server functionality on UNIX and 32-bit Windows. Kerberos V5 is supported by default in Windows 2000 builds: @@ -821,7 +899,9 @@ ftp://ftp.cac.washington.edu/mail/kerberos4-patches.tar.Z nmake -f makefile.ntk - _________________________________________________________________ + + Back to top + __________________________________________________________________ 3.11 How do I configure PAM for plaintext passwords? @@ -839,13 +919,14 @@ ftp://ftp.cac.washington.edu/mail/kerberos4-patches.tar.Z make foo PASSWDTYPE=pam If you build with PASSWDTYPE=pam and authentication does not - work, try rebuilding (after a "make clean") with - PASSWDTYPE=pmb. - _________________________________________________________________ + work, try rebuilding (after a "make clean") with PASSWDTYPE=pmb. + + Back to top + __________________________________________________________________ 3.12 It looks like all I have to do to make the server use Kerberos is - to build with PAM on my Linux system, and set it up in PAM for - Kerberos passwords. Right? + to build with PAM on my Linux system, and set it up in PAM for Kerberos + passwords. Right? Yes and no. @@ -855,7 +936,9 @@ ftp://ftp.cac.washington.edu/mail/kerberos4-patches.tar.Z However, this will NOT give you Kerberos-secure authentication. See the answer to the How do I configure Kerberos V5? question for how to build with Kerberos-secure authentication. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 3.13 How do I configure Kerberos 5 for plaintext passwords? @@ -866,21 +949,27 @@ ftp://ftp.cac.washington.edu/mail/kerberos4-patches.tar.Z However, this will NOT give you Kerberos-secure authentication. See the answer to the How do I configure Kerberos V5? question for how to build with Kerberos-secure authentication. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 3.14 How do I configure AFS for plaintext passwords? Build with PASSWDTYPE=afs, e.g make sol PASSWDTYPE=afs - _________________________________________________________________ + + Back to top + __________________________________________________________________ 3.15 How do I configure DCE for plaintext passwords? Build with PASSWDTYPE=dce, e.g make sol PASSWDTYPE=dce - _________________________________________________________________ + + Back to top + __________________________________________________________________ 3.16 How do I configure the CRAM-MD5 database for plaintext passwords? @@ -890,7 +979,9 @@ ftp://ftp.cac.washington.edu/mail/kerberos4-patches.tar.Z Note that this is NOT CRAM-MD5-secure authentication. You probably want to consider disabling plaintext passwords for non-SSL/TLS sessions. See the next two questions. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 3.17 How do I disable plaintext passwords? @@ -899,14 +990,16 @@ ftp://ftp.cac.washington.edu/mail/kerberos4-patches.tar.Z make lnx EXTRAAUTHENTICATORS=gss PASSWDTYPE=nul - Note that you must have a CRAM-MD5 database installed or - specify at least one EXTRAAUTHENTICATOR, otherwise it will not - be possible to log in to the server. + Note that you must have a CRAM-MD5 database installed or specify + at least one EXTRAAUTHENTICATOR, otherwise it will not be + possible to log in to the server. When plaintext passwords are disabled, the IMAP server will advertise the LOGINDISABLED capability and the POP3 server will not advertise the USER capability. + Back to top + 3.18 How do I disable plaintext passwords on unencrypted sessions, but allow them in SSL or TLS sessions? @@ -927,15 +1020,17 @@ ftp://ftp.cac.washington.edu/mail/kerberos4-patches.tar.Z plaintext passwords will be enabled, and a new CAPABILITY or CAPA command (which is required after start-TLS) will show the effect as in SSL sessions. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 3.19 How do I configure virtual hosts? This is automatic, but with certain restrictions. The most important one is that each virtual host must have its - own IP address; otherwise the server has no way of knowing - which virtual host is desired. + own IP address; otherwise the server has no way of knowing which + virtual host is desired. As distributed, the software uses a global password file; hence user "fred" on one virtual host is "fred" on all virtual hosts. @@ -949,7 +1044,9 @@ ftp://ftp.cac.washington.edu/mail/kerberos4-patches.tar.Z More advanced virtual host support may be available as patches from third parties. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 3.20 Why do I get compiler warning messages such as: passing arg 3 of `scandir' from incompatible pointer type @@ -962,21 +1059,23 @@ ftp://ftp.cac.washington.edu/mail/kerberos4-patches.tar.Z Over the years, the prototype for scandir() has changed, and thus is variant across different UNIX platforms. In particular, - the definitions of the third argument (type select_t) and - fourth argument (type compar_t) have changed over the years, - the issue being whether or not the arguments to the functions - pointed to by these function pointers are of type const or not. + the definitions of the third argument (type select_t) and fourth + argument (type compar_t) have changed over the years, the issue + being whether or not the arguments to the functions pointed to + by these function pointers are of type const or not. The way that c-client calls scandir() will tend to generate - these compiler warnings on newer systems such as Linux; - however, it will still build. The problem with fixing the call - is that then it won't build on older systems. - _________________________________________________________________ + these compiler warnings on newer systems such as Linux; however, + it will still build. The problem with fixing the call is that + then it won't build on older systems. + + Back to top + __________________________________________________________________ 3.21 Why do I get compiler warning messages such as Operation between types "void(*)(int)" and "void*" is not allowed. - Function argument assignment between types "void*" and "void(*)(int)" is not a -llowed. + Function argument assignment between types "void*" and "void(*)(int)" is not al +lowed. Pointers are not assignment-compatible. Argument #5 is not the correct type. @@ -986,8 +1085,8 @@ llowed. All known systems have no problem with casting a function pointer to/from a void* pointer, certain C compilers issue a - compiler diagnostic because this facility is listed as a - "Common extension" by the C standard: + compiler diagnostic because this facility is listed as a "Common + extension" by the C standard: K.5.7 Function pointer casts [#1] A pointer to an object or to void may be cast to a pointer @@ -996,9 +1095,11 @@ llowed. object or to void, allowing a function to be inspected or modified (for example, by a debugger) (6.3.4). - It may be just a "common extension", but this facility is - relied upon heavily by c-client. - _________________________________________________________________ + It may be just a "common extension", but this facility is relied + upon heavily by c-client. + + Back to top + __________________________________________________________________ 3.22 Why do I get linker warning messages such as: mtest.c:515: the `gets' function is dangerous and should not be used. @@ -1025,15 +1126,17 @@ mtest.c:515: the `gets' function is dangerous and should not be used. script to automate some email task using c-client, you'd be better off using imapd instead of mtest. - mtest only has two legitimate uses. It's a useful testbed for - me when debugging new versions of c-client, and it's useful as - a model for someone writing a simple c-client application to - see how the various calls work. + mtest only has two legitimate uses. It's a useful testbed for me + when debugging new versions of c-client, and it's useful as a + model for someone writing a simple c-client application to see + how the various calls work. By the way, if you need a more advanced example of c-client - programming than mtest (and you probably will), I recommend - that you look at the source code for imapd and Pine. - _________________________________________________________________ + programming than mtest (and you probably will), I recommend that + you look at the source code for imapd and Alpine. + + Back to top + __________________________________________________________________ 3.23 Why do I get linker warning messages such as: auth_ssl.c:92: the `tmpnam' function is dangerous and should not be used. @@ -1053,35 +1156,43 @@ mtest.c:515: the `gets' function is dangerous and should not be used. Neither of these issues applies in the particular use that is made of tmpnam(). More importantly, the tmpnam() call is never executed on Linux systems. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 3.24 OK, suppose I see a warning message about a function being - "dangerous and should not be used" for something other than this - gets() or tmpnam() call? + "dangerous and should not be used" for something other than this gets() + or tmpnam() call? Please forward the details for investigation. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 4. Operational Questions - _________________________________________________________________ + __________________________________________________________________ 4.1 How can I enable anonymous IMAP logins? Create the file /etc/anonymous.newsgroups. At the present time, this file should be empty. This will permit IMAP logins as - anonymous as well as the ANONYMOUS SASL authenticator. - Anonymous users have access to mailboxes in the #news., #ftp/, - and #public/ namespaces only. - _________________________________________________________________ + anonymous as well as the ANONYMOUS SASL authenticator. Anonymous + users have access to mailboxes in the #news., #ftp/, and + #public/ namespaces only. + + Back to top + __________________________________________________________________ 4.2 How do I set up an alert message that each IMAP user will see? Create the file /etc/imapd.alert with the text of the message. - This text should be kept to one line if possible. Note that - this will cause an alert to every IMAP user every time they - initiate an IMAP session, so it should only be used for - critical messages. - _________________________________________________________________ + This text should be kept to one line if possible. Note that this + will cause an alert to every IMAP user every time they initiate + an IMAP session, so it should only be used for critical + messages. + + Back to top + __________________________________________________________________ 4.3 How does the c-client library choose which of its several mechanisms to use to establish an IMAP connection to the server? I @@ -1099,78 +1210,81 @@ mtest.c:515: the `gets' function is dangerous and should not be used. + Else if client is a UNIX system and "rsh server exec /etc/rimapd" works, use that. + Else use a non-SSL connection. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 4.4 I am using a TLS-capable IMAP server, so I don't need to use /ssl - to get encryption. However, I want to be certain that my session is - TLS encrypted before I send my password. How to I do this? + to get encryption. However, I want to be certain that my session is TLS + encrypted before I send my password. How to I do this? Use the /tls option in the mailbox name. This will cause an error message and the connection to fail if the server does not negotiate STARTTLS. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 4.5 How do I use one of the alternative formats described in the - formats.txt document? In particular, I hear that mbx format will give + formats.txt document? In particular, I hear that mix format will give me better performance and allow shared access. - The rumors about mbx format being preferred are true. It is + The rumors about mix format being preferred are true. It is faster than the traditional UNIX mailbox format and permits shared access. However, and this is very important, note that using an alternative mailbox format is an advanced facility, and only - expert users should undertake it. If you don't understand any - of the following notes, you may not be enough of an expert yet, - and are probably better off not going this route until you are - more comfortable with your understanding. + expert users should undertake it. If you don't understand any of + the following notes, you may not be enough of an expert yet, and + are probably better off not going this route until you are more + comfortable with your understanding. - Some of the formats, including mbx, are only supported by the + Some of the formats, including mix, are only supported by the software based on the c-client library, and are not recognized - by other mailbox programs. The "vi" editor will corrupt any mbx - format mailbox that it encounters. + by other mailbox programs. The "vi" editor may corrupt mailboxes + written in these formats. - Another problem is that the certain formats, including mbx, use - advanced file access and locking techniques that do not work - reliably with NFS. NFS is not a real filesystem. Use IMAP + Another problem is that the certain formats, including mix and + mbx, use advanced file access and locking techniques that do not + work reliably with NFS. NFS is not a real filesystem. Use IMAP instead of NFS for distributed access. Each of the following steps are in escalating order of involvement. The further you go down this list, the more deeply committed you become: - + The simplest way to create a mbx-format mailbox is to prefix - the name with "#driver.mbx/" when creating a mailbox through - c-client. For example, if you create "#driver.mbx/foo", the - mailbox "foo" will be created in mbx format. Only use - "#driver.mbx/" when creating the mailbox. At all other times, + + The simplest way to create a mix-format mailbox is to prefix + the name with "#driver.mix/" when creating a mailbox through + c-client. For example, if you create "#driver.mix/foo", the + mailbox "foo" will be created in mix format. Only use + "#driver.mix/" when creating the mailbox. At all other times, just use the name ("foo" in this example); the software will - automatically select the driver for mbx whenever that mailbox + automatically select the driver for mix whenever that mailbox is accessed without you doing anything else. + You can use the "mailutil copy" command to copy an existing - mailbox to a new mailbox in mbx format. Read the man page + mailbox to a new mailbox in mix format. Read the man page provided with the mailutil program for details. - + If you create an mbx-format INBOX, by creating - "#driver.mbx/INBOX" (note that "INBOX" must be all - uppercase), then subsequent access to INBOX by any c-client - based application will use the mbx-format INBOX. Any mail - delivered to the traditional format mailbox in the spool - directory (e.g. /var/spool/mail/$USER) will automatically be - copied into the mbx-format INBOX and the spool directory copy - removed. - + You can cause any newly-created mailboxes to be in mbx-format - by default by changing the definition of - CREATEPROTO=unixproto to be CREATEPROTO=mbxproto in - src/osdep/unix/Makefile, then rebuilding the IMAP toolkit (do - a "make clean" first). Do not change EMPTYPROTO, since mbx - format mailboxes are never a zero-byte file. If you use Pine - or the imap-utils, you should probably also rebuild them with - the new IMAP toolkit too. - + You can deliver directly to the mbx-format INBOX by use of - the tmail or dmail programs. tmail is for direct invocation - from sendmail (or whatever MTA program you use); dmail is for - calls from procmail. Both of these programs have man pages - which must be read carefully before making this change. + + If you create an mix-format INBOX, by creating + "#driver.mix/INBOX" (note that "INBOX" must be all uppercase), + then subsequent access to INBOX by any c-client based + application will use the mix-format INBOX. Any mail delivered + to the traditional format mailbox in the spool directory (e.g. + /var/spool/mail/$USER) will automatically be copied into the + mix-format INBOX and the spool directory copy removed. + + You can cause any newly-created mailboxes to be in mix-format + by default by changing the definition of CREATEPROTO=unixproto + to be CREATEPROTO=mixproto in src/osdep/unix/Makefile, then + rebuilding the IMAP toolkit (do a "make clean" first). Do not + change EMPTYPROTO, since mix format mailboxes are directories + and thus are never a zero-byte file. If you use Alpine or the + imap-utils, you should probably also rebuild them with the new + IMAP toolkit too. + + You can deliver directly to the mix-format INBOX by use of the + tmail or dmail programs. tmail is for direct invocation from + sendmail (or whatever MTA program you use); dmail is for calls + from procmail. Both of these programs have man pages which + must be read carefully before making this change. Most other servers (e.g. Cyrus) require use of a non-standard format. A full-fledged format conversion is not significantly @@ -1186,11 +1300,12 @@ mtest.c:515: the `gets' function is dangerous and should not be used. result. On the other hand, there's no "One True Way" which can be boiled down to a simple set of pedagogical instructions. - A number of sites have done full-fledged format conversions, - and are reportedly quite happy with the results. Feel free to - ask in the comp.mail.imap newsgroup or the imap-uw mailing - list for advice or help. - _________________________________________________________________ + A number of sites have done full-fledged format conversions, and + are reportedly quite happy with the results. Feel free to ask in + the comp.mail.imap newsgroup for help. + + Back to top + __________________________________________________________________ 4.6 How do I set up shared mailboxes? @@ -1204,21 +1319,20 @@ mtest.c:515: the `gets' function is dangerous and should not be used. You may want to consider the use of a mailbox format which permits multiple simultaneous read/write sessions, such as the - mbx format. The traditional UNIX format only allows one + mix format. The traditional UNIX format only allows one read/write session to a mailbox at a time. An additional convenience item are three system directories, which can be set up for shared namespaces. These are: #ftp, - #shared, and #public, and are defined by creating the - associated UNIX users and home directories as described below. + #shared, and #public, and are defined by creating the associated + UNIX users and home directories as described below. - #ftp/ refers to the anonymous ftp filesystem exported by the - ftp server, and is equivalent to the home directory for UNIX - user "ftp". For example, #ftp/foo/bar refers to the file - /foo/bar in the anonymous FTP filesystem, or ~ftp/foo/bar for - normal users. Anonymous FTP files are available to anonymous - IMAP logins. By default, newly-created files in #ftp/ are - protected 644. + #ftp/ refers to the anonymous ftp filesystem exported by the ftp + server, and is equivalent to the home directory for UNIX user + "ftp". For example, #ftp/foo/bar refers to the file /foo/bar in + the anonymous FTP filesystem, or ~ftp/foo/bar for normal users. + Anonymous FTP files are available to anonymous IMAP logins. By + default, newly-created files in #ftp/ are protected 644. #public/ refers to an IMAP toolkit convention called "public" files, and is equivalent to the home directory for UNIX user @@ -1230,10 +1344,12 @@ mtest.c:515: the `gets' function is dangerous and should not be used. #shared/ refers to an IMAP toolkit convention called "shared" files, and is equivalent to the home directory for UNIX user "imapshared". For example, #shared/foo/bar refers to the file - ~imapshared/foo/bar. Shared files are not available to - anonymous IMAP logins. By default, newly-created files in - #shared are created with protection 0660. - _________________________________________________________________ + ~imapshared/foo/bar. Shared files are not available to anonymous + IMAP logins. By default, newly-created files in #shared are + created with protection 0660. + + Back to top + __________________________________________________________________ 4.7 How can I make the server syslogs go to someplace other than the mail syslog? @@ -1248,10 +1364,12 @@ mtest.c:515: the `gets' function is dangerous and should not be used. information on what the available syslog facilities are and how to configure syslogs. If you still don't understand what to do, find a UNIX system expert. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 5. Security Questions - _________________________________________________________________ + __________________________________________________________________ 5.1 I see that the IMAP server allows access to arbitary files on the system, including /etc/passwd! How do I disable this? @@ -1268,40 +1386,42 @@ mtest.c:515: the `gets' function is dangerous and should not be used. The first (and recommended) choice is to set restrictBox as described in file CONFIG. This will disable access to the - filesystem root, to other users' home directory, and to - superior directory. + filesystem root, to other users' home directory, and to superior + directory. The second (and strongly NOT recommended) choice is to set closedBox as described in file CONFIG. This puts each IMAP session into a so-called "chroot jail", and thus setting this - option is extremely dangerous; it can make your system much - less secure and open to root compromise attacks. So do not use - this option unless you are absolutely certain that you - understand all the issues of a "chroot jail." + option is extremely dangerous; it can make your system much less + secure and open to root compromise attacks. So do not use this + option unless you are absolutely certain that you understand all + the issues of a "chroot jail." The third choice is to rewrite routine mailboxfile() to implement whatever mapping from mailbox name to filesystem name (and restrictions) that you wish. This is the most general choice. As a guide, you can see at the start of routine mailboxfile() what the restrictBox choice does. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 5.2 I've heard that IMAP servers are insecure. Is this true? - There are no known security problems in this version of the - IMAP toolkit, including the IMAP and POP servers. The IMAP and - POP servers limit what can be done while not logged in, and as - part of the login process discard all privileges except those - of the user. + There are no known security problems in this version of the IMAP + toolkit, including the IMAP and POP servers. The IMAP and POP + servers limit what can be done while not logged in, and as part + of the login process discard all privileges except those of the + user. - As with other software packages, there have been buffer - overflow vulnerabilities in past versions. All known problems - of this nature are fixed in this version. + As with other software packages, there have been buffer overflow + vulnerabilities in past versions. All known problems of this + nature are fixed in this version. There is every reason to believe that the bad guys are engaged in an ongoing effort to find vulnerabilities in the IMAP - toolkit. We look for such problems, and when one is found we - fix it. + toolkit. We look for such problems, and when one is found we fix + it. It's unfortunate that any vulnerabilities existed in past versions, and we're doing my best to keep the IMAP toolkit free @@ -1310,21 +1430,31 @@ mtest.c:515: the `gets' function is dangerous and should not be used. Beware of vendors who claim that their implementations can not have vulnerabilities. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 5.3 How do I know that I have the most secure version of the server? - The best way is to keep your server software up to date. The - bad guys are always looking for ways to crack software, and - when they find one, let all their friends know. + The best way is to keep your server software up to date. The bad + guys are always looking for ways to crack software, and when + they find one, let all their friends know. Oldtimers used to refer to a concept of software rot: if your software hasn't been updated in a while, it would "rot" -- tend to acquire problems that it didn't have when it was new. - The latest release version of the IMAP toolkit is always - available at ftp://ftp.cac.washington.edu/mail/imap.tar.Z - _________________________________________________________________ + Unfortunately, UW IMAP is rapidly succumbing to "software rot", + as it is no longer being developed or maintained. If you have + not yet switched to Panda IMAP, you should seriously consider + doing so. + + Panda IMAP is available by donation. Donors are given a URL + which they can use to download Panda IMAP, including future + versions. + + Back to top + __________________________________________________________________ 5.4 I see all these strcpy() and sprintf() calls, those are unsafe, aren't they? @@ -1335,8 +1465,8 @@ mtest.c:515: the `gets' function is dangerous and should not be used. string being written will fit in the buffer. However, they are perfectly safe if you do know that. - Beware of programmers who advocate doing a brute-force change - of all instances of + Beware of programmers who advocate doing a brute-force change of + all instances of strcpy (s,t); @@ -1350,13 +1480,13 @@ mtest.c:515: the `gets' function is dangerous and should not be used. There are examples in which a security bug was introduced because of this type of "fix", due to the programmer using the wrong value for n. In one case, the programmer thought that n - was larger than it actually was, causing a NUL to be written - out of the buffer; in another, n was too small, and a security + was larger than it actually was, causing a NUL to be written out + of the buffer; in another, n was too small, and a security credential was truncated. - What is particularly ironic was that in both cases, the - original strcpy() was safe, because the size of the source - string was known to be safe. + What is particularly ironic was that in both cases, the original + strcpy() was safe, because the size of the source string was + known to be safe. With all this in mind, the software has been inspected, and it is believed that all places where buffer overflows can happen @@ -1367,16 +1497,17 @@ mtest.c:515: the `gets' function is dangerous and should not be used. *s++ = c; - is just as vulnerable to buffer overflows. You can't cure - buffer overflows by outlawing certain functions, nor is it - desirable to do so; sometimes operations like strcpy() - translate into fast machine instructions for better - performance. + is just as vulnerable to buffer overflows. You can't cure buffer + overflows by outlawing certain functions, nor is it desirable to + do so; sometimes operations like strcpy() translate into fast + machine instructions for better performance. Nothing replaces careful study of code. That's how the bad guys find bugs. Security is not accomplished by means of brute-force shortcuts. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 5.5 Those /tmp lock files are protected 666, is that really right? @@ -1392,16 +1523,18 @@ mtest.c:515: the `gets' function is dangerous and should not be used. Before worrying about deliberate mischief, worry first about things happening by accident! - _________________________________________________________________ + + Back to top + __________________________________________________________________ 6. Why Did You Do This Strange Thing? Questions - _________________________________________________________________ + __________________________________________________________________ 6.1 Why don't you use GNU autoconfig / automake / autoblurdybloop? Autoconfig et al are not available on all the platforms where - the IMAP toolkit is supported; and do not work correctly on - some of the platforms where they do exist. Furthermore, these + the IMAP toolkit is supported; and do not work correctly on some + of the platforms where they do exist. Furthermore, these programs add another layer of complexity to an already complex process. @@ -1409,26 +1542,27 @@ mtest.c:515: the `gets' function is dangerous and should not be used. platforms which were not specifically considered by that software wastes an inordinate amount of time. When (not if) autoconfig fails to do the right thing, the result is an - inpenetrable morass to untangle in order to find the problem - and fix it. + inpenetrable morass to untangle in order to find the problem and + fix it. The concept behind autoconfig is good, but the execution is - flawed. It rarely does the right thing on a platform that - wasn't specifically considered. Human life is too short to - debug autoconfig problems, especially since the current - mechanism is so much easier. - _________________________________________________________________ + flawed. It rarely does the right thing on a platform that wasn't + specifically considered. Human life is too short to debug + autoconfig problems, especially since the current mechanism is + so much easier. + + Back to top + __________________________________________________________________ 6.2 Why do you insist upon a build with -g? Doesn't it waste disk and memory space? - From time to time a submitted port has snuck in without -g. - This has always ended up causing problems. There are only two - valid excuses for not using -g in a port: + From time to time a submitted port has snuck in without -g. This + has always ended up causing problems. There are only two valid + excuses for not using -g in a port: + The compiler does not support -g - + An alternate form of -g is needed with optimization, e.g. - -g3. + + An alternate form of -g is needed with optimization, e.g. -g3. There will be no new ports added without -g (or a suitable alternative) being set. @@ -1439,70 +1573,74 @@ mtest.c:515: the `gets' function is dangerous and should not be used. will lead to the correct -g setting being determined and permanently added. - Processors are fast enough (and disk space is cheap enough) - that -g should be automatic in all compilers with no way of - turning it off, and /bin/strip should be a symlink to - /bin/true. Human life is too short to deal with binaries built - without -g. Such binaries should be a bad memory of the days of - KIPS processors and disks that costs several dollars per - kilobyte. - _________________________________________________________________ + Processors are fast enough (and disk space is cheap enough) that + -g should be automatic in all compilers with no way of turning + it off, and /bin/strip should be a symlink to /bin/true. Human + life is too short to deal with binaries built without -g. Such + binaries should be a bad memory of the days of KIPS processors + and disks that costs several dollars per kilobyte. + + Back to top + __________________________________________________________________ 6.3 Why don't you make c-client a shared library? All too often, shared libraries create far more problems than they solve. - Remember that you only gain the benefit of a shared library - when there are multiple applications which use that shared - library. Even without shared libraries, on most modern - operating systems (and many ancient ones too!) applications - will share their text segments between across multiple - processes running the same application. This means that if your - system only runs one application (e.g. imapd) that uses the - c-client library, then you gain no benefit from making c-client - a shared library even if it has 100 imapd processes. You will, - however suffer added complexity. + Remember that you only gain the benefit of a shared library when + there are multiple applications which use that shared library. + Even without shared libraries, on most modern operating systems + (and many ancient ones too!) applications will share their text + segments between across multiple processes running the same + application. This means that if your system only runs one + application (e.g. imapd) that uses the c-client library, then + you gain no benefit from making c-client a shared library even + if it has 100 imapd processes. You will, however suffer added + complexity. If you have a server system that just runs imapd and ipop3d, - then making c-client a shared library will save just one copy - of c-client no matter how many IMAP/POP3 processes are running. + then making c-client a shared library will save just one copy of + c-client no matter how many IMAP/POP3 processes are running. The problem with shared libraries is that you have to keep - around a copy of the library every time something changes in - the library that would affect the interface the library - presents to the application. So, you end up having many copies - of the same shared library. + around a copy of the library every time something changes in the + library that would affect the interface the library presents to + the application. So, you end up having many copies of the same + shared library. If you don't keep multiple copies of the shared library, then one of two things happens. If there was proper versioning, then - you'll get a message such as "cannot open shared object file" - or "minor versions don't match" and the application won't run. - Otherwise, the application will run, but will fail in - mysterious ways. + you'll get a message such as "cannot open shared object file" or + "minor versions don't match" and the application won't run. + Otherwise, the application will run, but will fail in mysterious + ways. Several sites and third-party distributors have modified the - c-client makefile in order to make c-client be a shared - library. When (not if) a c-client based application fails in - mysterious ways because of a library compatibility problem, the - result is a bug report. A lot of time and effort ends up - getting wasted investigating such bug reports. + c-client makefile in order to make c-client be a shared library. + When (not if) a c-client based application fails in mysterious + ways because of a library compatibility problem, the result is a + bug report. A lot of time and effort ends up getting wasted + investigating such bug reports. - Memory is so cheap these days that it's not worth it. Human - life is too short to deal with shared library compatibility - problems. - _________________________________________________________________ + Memory is so cheap these days that it's not worth it. Human life + is too short to deal with shared library compatibility problems. + + Back to top + __________________________________________________________________ 6.4 Why don't you use iconv() for internationalization support? iconv() is not ubiquitous enough. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 6.5 Why is the IMAP server connected to the home directory by default? - The IMAP server has no way of knowing what you might call - "mail" as opposed to "some other file"; in fact, you can use - IMAP to access any file. + The IMAP server has no way of knowing what you might call "mail" + as opposed to "some other file"; in fact, you can use IMAP to + access any file. The IMAP server also doesn't know whether your preferred subdirectory for mailbox files is "mail/", ".mail/", "Mail/", @@ -1513,27 +1651,29 @@ mtest.c:515: the `gets' function is dangerous and should not be used. It is possible to modify the software so that the default connected directory is someplace else. Please read the file CONFIG for discussion of this and other issues. - _________________________________________________________________ - 6.6 I have a Windows system. Why isn't the server plug and play for - me? + Back to top + __________________________________________________________________ + + 6.6 I have a Windows system. Why isn't the server plug and play for me? There is no standard for how mail is stored on Windows; nor a single standard SMTP server. The closest to either would be the SMTP server in Microsoft's IIS. So there's no default by which to make assumptions. As the - software is set up, it assumes that the each user has an - Windows login account and private home directory, and that mail - is stored on that home directory as files in one of the popular - UNIX formats. It also assumes that there is some tool - equivalent to inetd on UNIX that does the TCP/IP listening and - server startup. + software is set up, it assumes that the each user has an Windows + login account and private home directory, and that mail is + stored on that home directory as files in one of the popular + UNIX formats. It also assumes that there is some tool equivalent + to inetd on UNIX that does the TCP/IP listening and server + startup. Basically, unless you're an email software hacker, you probably - want to look elsewhere if you want IMAP/POP servers for - Windows. - _________________________________________________________________ + want to look elsewhere if you want IMAP/POP servers for Windows. + + Back to top + __________________________________________________________________ 6.7 I looked at the UNIX SSL code and saw that you have the SSL data payload size set to 8192 bytes. SSL allows 16K; why aren't you using @@ -1545,14 +1685,13 @@ mtest.c:515: the `gets' function is dangerous and should not be used. SSL support + Microsoft Exchange server (which also uses SChannel). - SChannel has a bug that makes it think that the maximum SSL - data payload size is 16379 bytes -- 5 bytes too small. Thus, - c-client has to make sure that it never transmits full sized - SSL packets. + SChannel has a bug that makes it think that the maximum SSL data + payload size is 16379 bytes -- 5 bytes too small. Thus, c-client + has to make sure that it never transmits full sized SSL packets. The reason for using 8K (as opposed to, say, 16379 bytes, or - 15K, or...) is that it corresponds with the TCP buffer size - that the software uses elsewhere for input; there's a slight + 15K, or...) is that it corresponds with the TCP buffer size that + the software uses elsewhere for input; there's a slight performance benefit to having the two sizes correspond or at least be a multiple of each other. Also, it keeps the size as a power of two, which might be significant on some platforms. @@ -1562,10 +1701,12 @@ mtest.c:515: the `gets' function is dangerous and should not be used. Microsoft has developed a hotfix for this bug. Look up MSKB article number 300562. Contrary to the article text which - implies that this is a Pine issue, this bug also affects + implies that this is a Alpine issue, this bug also affects Microsoft Exchange server with any client that transmits full-sized SSL payloads. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 6.8 Why is an mh format INBOX called #mhinbox instead of just INBOX? @@ -1578,7 +1719,9 @@ mtest.c:515: the `gets' function is dangerous and should not be used. When the mh driver used INBOX, it would see the mh profile, and proceed to move the user's INBOX into the mh format INBOX. This caused considerable confusion as some things stopped working. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 6.9 Why don't you support the maildir format? @@ -1589,38 +1732,42 @@ mtest.c:515: the `gets' function is dangerous and should not be used. No one has succeeded in accomplishing all four together. The various maildir drivers offered as patches all have these - problems. The problem is exacerbated because this - implementation supports multiple formats; consequently this - implementation can't make any performance shortcuts by assuming - that all the world is maildir. + problems. The problem is exacerbated because this implementation + supports multiple formats; consequently this implementation + can't make any performance shortcuts by assuming that all the + world is maildir. - We can't do a better job than the maildir fan community has - done with their maildir drivers. Similarly, if the maildir fan + We can't do a better job than the maildir fan community has done + with their maildir drivers. Similarly, if the maildir fan community provides the maildir driver, they take on the - responsibility for answering maildir-specific support - questions. This is as it should be, and that is why maildir - support is left to the maildir fan community. - _________________________________________________________________ + responsibility for answering maildir-specific support questions. + This is as it should be, and that is why maildir support is left + to the maildir fan community. + + Back to top + __________________________________________________________________ 6.10 Why don't you support the Cyrus format? There's no point to doing so. An implementation which supports - multiple formats will never do as well as one which is - optimized to support one single format. + multiple formats will never do as well as one which is optimized + to support one single format. If you want to use Cyrus mailbox format, you should use the Cyrus server, which is the native implementation of that format and is specifically optimized for that format. That's also why Cyrus doesn't implement any other format. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 6.11 Why is it creating extra forks on my SVR4 system? This is because your system only has fcntl() style locking and not flock() style locking. fcntl() locking has a design flaw that causes a close() to release any locks made by that process - on the file opened on that file descriptor, even if the lock - was made on a different file descriptor. + on the file opened on that file descriptor, even if the lock was + made on a different file descriptor. This design flaw causes unexpected loss of lock, and consequent mailbox corruption. The workaround is to do certain "dangerous @@ -1634,10 +1781,12 @@ mtest.c:515: the `gets' function is dangerous and should not be used. SVR4, but also have flock() locking. Beware of certain SVR4 systems, such as AIX, which have an - "flock()" function in their C library that is just a jacket - that does an fcntl() lock. This is not a true flock(), and has - the same design flaw as fcntl(). - _________________________________________________________________ + "flock()" function in their C library that is just a jacket that + does an fcntl() lock. This is not a true flock(), and has the + same design flaw as fcntl(). + + Back to top + __________________________________________________________________ 6.12 Why are you so fussy about the date/time format in the internal "From " line in traditional UNIX mailbox files? My other mail program @@ -1654,20 +1803,20 @@ mtest.c:515: the `gets' function is dangerous and should not be used. "From " line if it follows the actual specification for a "From " line. This means, among other things, that the day of week is fixed-format: "May 14", but "May 7" (note the extra - space) as opposed to "May 7". ctime() format for the date is - the most common, although POSIX also allows a numeric timezone - after the year. For compatibility with ancient software, the - seconds are optional, the timezone may appear before the year, - the old 3-letter timezones are also permitted, and "remote from - xxx" may appear after the whole thing. + space) as opposed to "May 7". ctime() format for the date is the + most common, although POSIX also allows a numeric timezone after + the year. For compatibility with ancient software, the seconds + are optional, the timezone may appear before the year, the old + 3-letter timezones are also permitted, and "remote from xxx" may + appear after the whole thing. Unfortunately, some software written by novices use other formats. The most common error is to have a variable-width day of month, perhaps in the erroneous belief that RFC 2822 (or RFC - 822) defines the format of the date/time in the "From " line - (it doesn't; no RFC describes internal formats). I've seen a - few other goofs, such as a single-digit second, but these are - less common. + 822) defines the format of the date/time in the "From " line (it + doesn't; no RFC describes internal formats). I've seen a few + other goofs, such as a single-digit second, but these are less + common. If you are writing your own software that writes mailbox files, and you really aren't all that savvy with all the ins and outs @@ -1678,21 +1827,25 @@ mtest.c:515: the `gets' function is dangerous and should not be used. fprintf (mbx,"From %s@%h %s",user,host,ctime (time (0))); - rather than try to figure out a good format yourself. ctime() - is the most traditional format and nobody will flame you for - using it. - _________________________________________________________________ + rather than try to figure out a good format yourself. ctime() is + the most traditional format and nobody will flame you for using + it. + + Back to top + __________________________________________________________________ 6.13 Why is traditional UNIX format the default format? - Compatibility with the past 30 or so years of UNIX history. - This server is the only one that completely interoperates with - legacy UNIX mail tools. - _________________________________________________________________ + Compatibility with the past 30 or so years of UNIX history. This + server is the only one that completely interoperates with legacy + UNIX mail tools. + + Back to top + __________________________________________________________________ 6.14 Why do you write this "DON'T DELETE THIS MESSAGE -- FOLDER - INTERNAL DATA" message at the start of traditional UNIX and MMDF - format mailboxes? + INTERNAL DATA" message at the start of traditional UNIX and MMDF format + mailboxes? This pseudo-message serves two purposes. @@ -1702,34 +1855,40 @@ mtest.c:515: the `gets' function is dangerous and should not be used. Second, it holds mailbox metadata used by IMAP: the UID validity, the last assigned UID, and mailbox keywords. Without - this metadata, which must be preserved even when the mailbox - has no messages, the traditional UNIX format wouldn't be able - to support the full capabilities of IMAP. - _________________________________________________________________ + this metadata, which must be preserved even when the mailbox has + no messages, the traditional UNIX format wouldn't be able to + support the full capabilities of IMAP. - 6.15 Why don't you stash the mailbox metadata in the first real - message of the mailbox instead of writing this fake FOLDER INTERNAL - DATA message? + Back to top + __________________________________________________________________ + + 6.15 Why don't you stash the mailbox metadata in the first real message + of the mailbox instead of writing this fake FOLDER INTERNAL DATA + message? In fact, that is what is done if the mailbox is non-empty and does not already have a FOLDER INTERNAL DATA message. One problem with doing that is that if some external program removes the first message, the metadata is lost and must be - recreated, thus losing any prior UID or keyword list status - that IMAP clients may depend upon. + recreated, thus losing any prior UID or keyword list status that + IMAP clients may depend upon. + + Another problem is that this doesn't help if the last message is + deleted. This will result in an empty mailbox, and the necessity + to create a FOLDER INTERNAL DATA message. - Another problem is that this doesn't help if the last message - is deleted. This will result in an empty mailbox, and the - necessity to create a FOLDER INTERNAL DATA message. - _________________________________________________________________ + Back to top + __________________________________________________________________ 6.16 Why aren't "dual-use" mailboxes the default? Compatibility with the past 30 or so years of UNIX history, not - to mention compatibility with user expectations when using - shell tools. - _________________________________________________________________ + to mention compatibility with user expectations when using shell + tools. + + Back to top + __________________________________________________________________ 6.17 Why do you use ucbcc to build on Solaris? @@ -1738,23 +1897,23 @@ mtest.c:515: the `gets' function is dangerous and should not be used. libraries and not the BSD libraries, otherwise readdir() will return the wrong information. - Of all the names in the most common path, ucbcc is the only - name to be found (on /usr/ccs/bin) that points to a suitable - compiler. cc is likely to be /usr/ucb/cc which is absolutely - not the compiler that you want. The real SVR4 cc is probably + Of all the names in the most common path, ucbcc is the only name + to be found (on /usr/ccs/bin) that points to a suitable + compiler. cc is likely to be /usr/ucb/cc which is absolutely not + the compiler that you want. The real SVR4 cc is probably something like /opt/SUNWspro/bin/cc which is rarely in anyone's path by default. ucbcc is probably a link to acc, e.g. - /opt/SUNWspro/SC4.0/bin/acc, and is the UCB C compiler using - the SVR4 libraries. + /opt/SUNWspro/SC4.0/bin/acc, and is the UCB C compiler using the + SVR4 libraries. If ucbcc isn't on your system, then punt on the SUN C compiler and use gcc instead (the gso port instead of the sol port). If, in spite of all the above warnings, you choose to change - "ucbcc" to "cc", you will probably find that the -O2 needs to - be changed to -O. If you don't get any error messages with -O2, + "ucbcc" to "cc", you will probably find that the -O2 needs to be + changed to -O. If you don't get any error messages with -O2, that's a pretty good indicator that you goofed and are running the compiler that will link with the BSD libraries. @@ -1764,37 +1923,42 @@ mtest.c:515: the `gets' function is dangerous and should not be used. using the SVR4 libraries. This compiler is "ucbcc", which is lunk to acc. You use -O2 as one of the CFLAGS. + If you build the sol port with the UCB compiler using the BSD - libraries, you will get no error messages but you will get - bad binaries (the most obvious symptom is dropping the first - two characters return filenames from the imapd LIST command. - This compiler also uses -O2, and is very often what the user - gets from "cc". BEWARE + libraries, you will get no error messages but you will get bad + binaries (the most obvious symptom is dropping the first two + characters return filenames from the imapd LIST command. This + compiler also uses -O2, and is very often what the user gets + from "cc". BEWARE + If you build the sol port with the real SVR4 compiler, which is often hidden away or unavailable on many systems, then you will get errors from -O2 and you need to change that to -O. But you will get a good binary. However, you should try it with -O2 first, to make sure that you got this compiler and not the UCB compiler using BSD libraries. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 6.18 Why should I care about some old system with BSD libraries? cc is the right thing on my Solaris system! Because there still are sites that use such systems. On those - systems, the assumption that "cc" does the right thing will - lead to corrupt binaries with no error message or other warning - that anything is amiss. + systems, the assumption that "cc" does the right thing will lead + to corrupt binaries with no error message or other warning that + anything is amiss. Too many sites have fallen victim to this problem. - _________________________________________________________________ - 6.19 Why do you insist upon writing .lock files in the spool - directory? + Back to top + __________________________________________________________________ + + 6.19 Why do you insist upon writing .lock files in the spool directory? Compatibility with the past 30 years of UNIX software which deals with the spool directory, especially software which delivers mail. Otherwise, it is possible to lose mail. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 6.20 Why should I care about compatibility with the past? @@ -1802,42 +1966,49 @@ mtest.c:515: the `gets' function is dangerous and should not be used. convinces those who ask it. Somehow, everybody who ever asks this question ends up answering it for themselves as they get older, with the very answer that they rejected years earlier. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7. Problems and Annoyances - _________________________________________________________________ + __________________________________________________________________ 7.1 Help! My INBOX is empty! What happened to my messages? If you are seeing "0 messages" when you open INBOX and you know you have messages there (and perhaps have looked at your mail - spool file and see that messages are there), then probably - there is something wrong with the very first line of your mail - spool file. Make sure that the first five bytes of the file are - "From ", followed by an email address and a date/time in - ctime() format, e.g.: + spool file and see that messages are there), then probably there + is something wrong with the very first line of your mail spool + file. Make sure that the first five bytes of the file are "From + ", followed by an email address and a date/time in ctime() + format, e.g.: From fred@foo.bar Mon May 7 20:54:30 2001 - _________________________________________________________________ - 7.2 Help! All my messages in a non-INBOX mailbox have been - concatenated into one message which claims to be from me and has a - subject of the file name of the mailbox! What's going on? + Back to top + __________________________________________________________________ + + 7.2 Help! All my messages in a non-INBOX mailbox have been concatenated + into one message which claims to be from me and has a subject of the + file name of the mailbox! What's going on? Something wrong with the very first line of the mailbox. Make - sure that the first five bytes of the file are "From ", - followed by an email address and a date/time in ctime() format, - e.g.: + sure that the first five bytes of the file are "From ", followed + by an email address and a date/time in ctime() format, e.g.: From fred@foo.bar Mon May 7 20:54:30 2001 - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.3 Why do I get the message: CREATE failed: Can't create mailbox node xxxxxxxxx: File exists and how do I fix it? See the answer to the Are hierarchical mailboxes supported? question. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.4 Why can't I log in to the server? The user name and password are right! @@ -1847,9 +2018,9 @@ mtest.c:515: the `gets' function is dangerous and should not be used. under a debugger such as gdb while root (yes, you must be root) with a breakpoint at routines checkpw() and loginpw(), then single-step until you see which test rejected you. The server - isn't going to give any error messages other than "login - failed" in the name of not giving out any unnecessary - information to unauthorized individuals. + isn't going to give any error messages other than "login failed" + in the name of not giving out any unnecessary information to + unauthorized individuals. Here are some of the more common reasons why login may fail: @@ -1864,47 +2035,51 @@ mtest.c:515: the `gets' function is dangerous and should not be used. + If you are using PAM, have you created a service file for the server in /etc/pam.d? + If you are using shadow passwords, have you used an - appropriate port when building? In particular, note that - "lnx" is for Linux systems without shadow passwords; you - probably want "slx" or "lnp" instead. + appropriate port when building? In particular, note that "lnx" + is for Linux systems without shadow passwords; you probably + want "slx" or "lnp" instead. + If your system has account or password expirations, check to see that the expiration date hasn't passed. + You can't log in as root or any other UID 0 user. This is for your own safety, not to mention the fact that the servers use UID 0 as meaning "not logged in". - _________________________________________________________________ - 7.5 Help! My load average is soaring and I see hundreds of POP and - IMAP servers, many logged in as the same user! + Back to top + __________________________________________________________________ + + 7.5 Help! My load average is soaring and I see hundreds of POP and IMAP + servers, many logged in as the same user! Certain inferior losing GUI mail reading programs have a "synchronize all mailboxes at startup" (IMAP) or "check for new mail every second" (POP) feature which causes a rapid and unchecked spawning of servers. - This is not a problem in the server; the client is really - asking for all those server sessions. Unfortunately, there - isn't much that the POP and IMAP servers can do about it; they - don't spawned themselves. + This is not a problem in the server; the client is really asking + for all those server sessions. Unfortunately, there isn't much + that the POP and IMAP servers can do about it; they don't + spawned themselves. Some sites have added code to record the number of server - sessions spawned per user per hour, and disable login for a - user who has exceeded a predetermined rate. This doesn't stop - the servers from being spawned; it just means that a server - session will commit suicide a bit faster. + sessions spawned per user per hour, and disable login for a user + who has exceeded a predetermined rate. This doesn't stop the + servers from being spawned; it just means that a server session + will commit suicide a bit faster. Another possibility is to detect excessive server spawning activity at the level where the server is spawned, which would be inetd or possibly tcpd. The problem here is that this is a - hard time to quantify. 50 sessions in a minute from a - multi-user timesharing system may be perfectly alright, whereas - 10 sessions a minute from a PC may be too much. + hard time to quantify. 50 sessions in a minute from a multi-user + timesharing system may be perfectly alright, whereas 10 sessions + a minute from a PC may be too much. The real solution is to fix the client configuration, by disabling those evil features. Also tell the vendors of those - clients how you feel about distributing denial-of-service - attack tools in the guise of mail reading programs. - _________________________________________________________________ + clients how you feel about distributing denial-of-service attack + tools in the guise of mail reading programs. + + Back to top + __________________________________________________________________ 7.6 Why does mail disappear even though I set "keep mail on server"? 7.7 Why do I get the message Moved ##### bytes of new mail to @@ -1914,24 +2089,25 @@ mtest.c:515: the `gets' function is dangerous and should not be used. exists on the user's home directory and is in UNIX mailbox format, then when INBOX is opened this file will be selected as INBOX instead of the mail spool file. Messages will be - automatically transferred from the mail spool file into the - mbox file. + automatically transferred from the mail spool file into the mbox + file. To disable this behavior, delete "mbox" from the EXTRADRIVERS list in the top-level Makefile and rebuild. Note that if you do this, users won't be able to access the messages that have already been moved to mbox unless they open mbox instead of INBOX. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.8 Why isn't it showing the local host name as a fully-qualified domain name? - 7.9 Why is the local host name in the From/Sender/Message-ID headers - of outgoing mail not coming out as a fully-qualified domain name? + 7.9 Why is the local host name in the From/Sender/Message-ID headers of + outgoing mail not coming out as a fully-qualified domain name? Your UNIX system is misconfigured. The entry for your system in - /etc/hosts must have the fully-qualified domain name first, - e.g. + /etc/hosts must have the fully-qualified domain name first, e.g. 105.69.1.234 myserver.example.com myserver @@ -1950,15 +2126,15 @@ mtest.c:515: the `gets' function is dangerous and should not be used. On some systems, a configuration file (typically named /etc/svc.conf, /etc/netsvc.conf, or /etc/nsswitch.conf) can be - used to configure the system to use the domain name system - (DNS) instead of /etc/hosts, so it doesn't matter if /etc/hosts - is misconfigured. + used to configure the system to use the domain name system (DNS) + instead of /etc/hosts, so it doesn't matter if /etc/hosts is + misconfigured. - Check the man pages for gethostbyname, hosts, svc, and/or - netsvc for more information. + Check the man pages for gethostbyname, hosts, svc, and/or netsvc + for more information. - Unfortunately, certain vendors, most notably SUN, have failed - to make this clear in their documentation. Most of SUN's + Unfortunately, certain vendors, most notably SUN, have failed to + make this clear in their documentation. Most of SUN's documentation assumes a corporate network that is not connected to the Internet. @@ -1977,25 +2153,27 @@ mtest.c:515: the `gets' function is dangerous and should not be used. This practice has been thoroughly discredited for many years, but folklore dies hard. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.10 What does the message: Mailbox vulnerable - directory /var/spool/mail must have 1777 protection mean? How can I fix this? In order to update a mailbox in the default UNIX format, it is necessary to create a lock file to prevent the mailer from - delivering mail while an update is in progress. Some systems - use a directory protection of 775, requiring that all mail - handling programs be setgid mail; or of 755, requiring that all - mail handling programs be setuid root. - - The IMAP toolkit does not run with any special privileges, and - I plan to keep it that way. It is antithetical to the concept - of a toolkit if users can't write their own programs to use it. - Also, I've had enough bad experiences with security bugs while - running privileged; the IMAP and POP servers have to be root - when not logged in, in order to be able to log themselves in. I - don't want to go any deeper down that slippery slope. + delivering mail while an update is in progress. Some systems use + a directory protection of 775, requiring that all mail handling + programs be setgid mail; or of 755, requiring that all mail + handling programs be setuid root. + + The IMAP toolkit does not run with any special privileges, and I + plan to keep it that way. It is antithetical to the concept of a + toolkit if users can't write their own programs to use it. Also, + I've had enough bad experiences with security bugs while running + privileged; the IMAP and POP servers have to be root when not + logged in, in order to be able to log themselves in. I don't + want to go any deeper down that slippery slope. Directory protection 1777 is secure enough on most well-managed systems. If you can't trust your users with a 1777 mail spool @@ -2010,30 +2188,36 @@ mtest.c:515: the `gets' function is dangerous and should not be used. try to call mlock to do it. I do not recommend doing this for performance reasons. - A sample mlock program is included as part of imap-2007. We - have tried to make this sample program secure, but it has not - been thoroughly audited. - _________________________________________________________________ + A sample mlock program is included as part of imap-2010. We have + tried to make this sample program secure, but it has not been + thoroughly audited. + + Back to top + __________________________________________________________________ 7.11 What does the message: Mailbox is open by another process, access is readonly mean? How do I fix this? A problem occurred in applying a lock to a /tmp lock file. Either some other program has the mailbox open and won't - relenquish it, or something is wrong with the protection of - /tmp or the lock. + relenquish it, or something is wrong with the protection of /tmp + or the lock. Make sure that the /tmp directory is protected 1777. Some security scripts incorrectly set the protection of the /tmp directory to 775, which disables /tmp for all non-privileged programs. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.12 What does the message: Can't get write access to mailbox, access is readonly mean? The mailbox file is write-protected against you. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.13 I set my POP3 client to "delete messages from server" but they never get deleted. What is wrong? @@ -2053,15 +2237,16 @@ mtest.c:515: the `gets' function is dangerous and should not be used. finishes. The POP3 protocol specifies that deletions are discarded unless a proper QUIT is done. - Make sure that you are not opening multiple POP3 sessions to - the same mailbox. It is a requirement of the POP3 protocol than - only one POP3 session be in effect to a mailbox at a time, - however some, poorly-written POP3 clients violate this. Also, - some background "check for new mail" tasks also cause a - violation. See the answer to the What does the syslog message: - Killed (lost mailbox lock) user=... host=... mean? question for - more details. - _________________________________________________________________ + Make sure that you are not opening multiple POP3 sessions to the + same mailbox. It is a requirement of the POP3 protocol than only + one POP3 session be in effect to a mailbox at a time, however + some, poorly-written POP3 clients violate this. Also, some + background "check for new mail" tasks also cause a violation. + See the answer to the What does the syslog message: Killed (lost + mailbox lock) user=... host=... mean? question for more details. + + Back to top + __________________________________________________________________ 7.14 What do messages such as: Message ... UID ... already has UID ... @@ -2073,8 +2258,7 @@ mtest.c:515: the `gets' function is dangerous and should not be used. Something happened to corrupt the unique identifier regime in the mailbox. In traditional UNIX-format mailboxes, this can - happen if the user deleted the "DO NOT DELETE" internal - message. + happen if the user deleted the "DO NOT DELETE" internal message. This problem is relatively harmless; a new valid unique identifier regime will be created. The main effect is that any @@ -2082,7 +2266,9 @@ mtest.c:515: the `gets' function is dangerous and should not be used. So, unless it is a chronic problem or you feel like debugging, you can safely ignore these messages. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.15 What do the error messages: Unable to read internal header at ... @@ -2110,11 +2296,11 @@ mtest.c:515: the `gets' function is dangerous and should not be used. editor can handle binary!!! If you are not comfortable with emacs, or if the file is too - large to read with emacs, see the "step-by-step" technique - later on for another way of doing it. + large to read with emacs, see the "step-by-step" technique later + on for another way of doing it. - After the word "at" in the error message is the byte position - it got to when it got unhappy with the file, e.g. if you see: + After the word "at" in the error message is the byte position it + got to when it got unhappy with the file, e.g. if you see: Unable to parse internal header at 43921: ne bombastic blurdybloop @@ -2136,10 +2322,10 @@ mtest.c:515: the `gets' function is dangerous and should not be used. Here's what to do if you want to be smarter and do a little bit more work. Generally, you're in the middle of a message, and - there's nothing wrong with that message. The problem happened - in the *previous* message. So, search back to the previous - internal header. Now, remember that "ssss" field? That's the - size of that message. + there's nothing wrong with that message. The problem happened in + the *previous* message. So, search back to the previous internal + header. Now, remember that "ssss" field? That's the size of that + message. Mark where you are in the file, move the cursor to the line after the internal header, and skip that many bytes ("ssss") @@ -2154,14 +2340,14 @@ mtest.c:515: the `gets' function is dangerous and should not be used. header. Usually, once you know what you're looking at, it's pretty easy - to work out the corruption, and the best remedial action. - Repair scripts will make the problem go away but may not always - do the smartest/best salvage of the user's data. Manual repair - is more flexible and usually preferable. + to work out the corruption, and the best remedial action. Repair + scripts will make the problem go away but may not always do the + smartest/best salvage of the user's data. Manual repair is more + flexible and usually preferable. Here is a step-by-step technique for fixing corrupt mbx files - that's a bit cruder than the procedure outlined above, but - works for any size file. + that's a bit cruder than the procedure outlined above, but works + for any size file. In this example, suppose that the corrupt file is INBOX, the error message is @@ -2174,35 +2360,34 @@ mtest.c:515: the `gets' function is dangerous and should not be used. error: + Rename the INBOX file to some other name, such as INBOX.bad. - + Copy the first 132,551,754 bytes of INBOX.bad to another - file, such as INBOX.new. + + Copy the first 132,551,754 bytes of INBOX.bad to another file, + such as INBOX.new. + Extract the trailing 316,116 bytes (132867870-132551754) of INBOX.bad into another file, such as INBOX.tail. + You no longer need INBOX.bad. Delete it. - In other words, use the number from the "Unable to find CRLF - at" as the point to split INBOX into two new files, INBOX.new - and INBOX.tail. + In other words, use the number from the "Unable to find CRLF at" + as the point to split INBOX into two new files, INBOX.new and + INBOX.tail. Now, remove the erroneous data: - + Verify that you can open INBOX.new in IMAP or Pine. + + Verify that you can open INBOX.new in IMAP or Alpine. + The last message of INBOX.new is probably corrupted. Copy it to another file, such as badmsg.1, then delete and expunge that last message from INBOX.new + Locate the first occurance of text in INBOX.tail which looks like an internal header, as described above. + Remove all the text which occurs prior to that point, and - place it into another file, such as badmsg.2. Note that in - the case of a single digit date, there is a leading space - which must not be removed (e.g. " 6-Nov-2001" not - "6-Nov-2001"). + place it into another file, such as badmsg.2. Note that in the + case of a single digit date, there is a leading space which + must not be removed (e.g. " 6-Nov-2001" not "6-Nov-2001"). Reassemble the mailbox: + Append INBOX.tail to INBOX.new. + You no longer need INBOX.tail. Delete it. - + Verify that you can open INBOX.new in IMAP or Pine. + + Verify that you can open INBOX.new in IMAP or Alpine. Reinstall INBOX.new as INBOX: @@ -2214,10 +2399,12 @@ mtest.c:515: the `gets' function is dangerous and should not be used. messages from INBOX to INBOX.new before doing the rename. You now have a working INBOX, as well as two files with - corrupted data (badmsg.1 and badmsg.2). There may be some - useful data in the two badmsg files that you might want to try + corrupted data (badmsg.1 and badmsg.2). There may be some useful + data in the two badmsg files that you might want to try salvaging; otherwise you can delete the two badmsg files. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.16 What do the syslog messages: @@ -2227,11 +2414,10 @@ mtest.c:515: the `gets' function is dangerous and should not be used. mean? When it happens, the listed service shuts down. How can I fix this? - The error message "server failing (looping), service - terminated" is not from either the IMAP or POP servers. - Instead, it comes from inetd, the daemon which listens for TCP - connections to a number of servers, including the IMAP and POP - servers. + The error message "server failing (looping), service terminated" + is not from either the IMAP or POP servers. Instead, it comes + from inetd, the daemon which listens for TCP connections to a + number of servers, including the IMAP and POP servers. inetd has a limit of 40 new server sessions per minute for any particular service. If more than 40 sessions are initiated in a @@ -2240,19 +2426,18 @@ mtest.c:515: the `gets' function is dangerous and should not be used. inetd does this to prevent system resource consumption by a client which is spawning infinite numbers of servers. It should be noted that this is a denial of service; however for some - systems the alternative is a crash which would be a worse - denial of service! + systems the alternative is a crash which would be a worse denial + of service! For larger server systems, the limit of 40 is much too low. The limit was established many years ago when a system typically only ran a few dozen servers. - On some versions of inetd, such as the one distributed with - most versions of Linux, you can modify the /etc/inetd.conf file - to have a larger number of servers by appending a period - followed by a number after the nowait word for the server - entry. For example, if your existing /etc/inetd.conf line - reads: + On some versions of inetd, such as the one distributed with most + versions of Linux, you can modify the /etc/inetd.conf file to + have a larger number of servers by appending a period followed + by a number after the nowait word for the server entry. For + example, if your existing /etc/inetd.conf line reads: imap stream tcp nowait root /usr/etc/imapd imapd @@ -2276,22 +2461,24 @@ mtest.c:515: the `gets' function is dangerous and should not be used. that you will disable IMAP service entirely. Another way to fix this problem is to edit the inetd.c source - code (provided by your UNIX system vendor) to set higher - limits, rebuild inetd, install the new binary, and reboot your - system. This should only be done by a UNIX system expert. In - the inetd.c source code, the limits TOOMANY (normally 40) is - the maximum number of new server sessions permitted per minute, - and RETRYTIME (normally 600) is the number of seconds inetd - will shut down the server after it exceeds TOOMANY. - _________________________________________________________________ + code (provided by your UNIX system vendor) to set higher limits, + rebuild inetd, install the new binary, and reboot your system. + This should only be done by a UNIX system expert. In the inetd.c + source code, the limits TOOMANY (normally 40) is the maximum + number of new server sessions permitted per minute, and + RETRYTIME (normally 600) is the number of seconds inetd will + shut down the server after it exceeds TOOMANY. + + Back to top + __________________________________________________________________ 7.17 What does the syslog message: Mailbox lock file /tmp/.600.1df3 open failure: Permission denied mean? This usually means that some "helpful" security script person - has protected /tmp so that it is no longer world-writeable. - /tmp must be world-writeable because lots of applications use - it for scratch space. To fix this, do + has protected /tmp so that it is no longer world-writeable. /tmp + must be world-writeable because lots of applications use it for + scratch space. To fix this, do chmod 1777 /tmp @@ -2301,7 +2488,9 @@ mtest.c:515: the `gets' function is dangerous and should not be used. file. If it is something other than 666, then either someone is hacking or some "helpful" person modified the code to have a different default lock file protection. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.18 What do the syslog messages: Command stream end of file, while reading line user=... host=... @@ -2311,12 +2500,12 @@ mtest.c:515: the `gets' function is dangerous and should not be used. mean? This message occurs when the session is disconnected without a - proper LOGOUT (IMAP) or QUIT (POP) command being received by - the server first. + proper LOGOUT (IMAP) or QUIT (POP) command being received by the + server first. In many cases, this is perfectly normal; many client - implementations are impolite and do this. Some programmers - think this sort of rudeness is "more efficient". + implementations are impolite and do this. Some programmers think + this sort of rudeness is "more efficient". The condition could, however, indicate a client or network connectivity problem. The server has no way of knowing whether @@ -2327,36 +2516,37 @@ mtest.c:515: the `gets' function is dangerous and should not be used. failed login, and instead of saying that the login failed, just say that they can't access the mailbox. They then complain to the system manager, who looks in the syslog and finds this - message. Not very helpful, eh? See the answer to the Why can't - I log in to the server? The user name and password are right! + message. Not very helpful, eh? See the answer to the Why can't I + log in to the server? The user name and password are right! question. If the user isn't reporting a problem, you can probably ignore this message. - _________________________________________________________________ - 7.19 Why did my POP or IMAP session suddenly disconnect? The syslog - has the message: Killed (lost mailbox lock) user=... host=... + Back to top + __________________________________________________________________ + + 7.19 Why did my POP or IMAP session suddenly disconnect? The syslog has + the message: Killed (lost mailbox lock) user=... host=... This message only happens when either the traditional UNIX - mailbox format or MMDF format is in use. This format only - allows one session to have the mailbox open read/write at a - time. - - The servers assume that if a second session attempts to open - the mailbox, that means that the first session is probably - owned by an abandoned client. The common scenario here is a - user who leaves his client running at the office, and then - tries to read his mail from home. Through an internal mechanism - called kiss of death, the second session requests the first - session to kill itself. When the first session receives the - "kiss of death", it issues the "Killed (lost mailbox lock)" - syslog message and terminates. The second session then seizes - read/write access, and becomes the new "first" session. - - Certain poorly-designed clients routinely open multiple - sessions to the same mailbox; the users of those clients tend - to get this message a lot. + mailbox format or MMDF format is in use. This format only allows + one session to have the mailbox open read/write at a time. + + The servers assume that if a second session attempts to open the + mailbox, that means that the first session is probably owned by + an abandoned client. The common scenario here is a user who + leaves his client running at the office, and then tries to read + his mail from home. Through an internal mechanism called kiss of + death, the second session requests the first session to kill + itself. When the first session receives the "kiss of death", it + issues the "Killed (lost mailbox lock)" syslog message and + terminates. The second session then seizes read/write access, + and becomes the new "first" session. + + Certain poorly-designed clients routinely open multiple sessions + to the same mailbox; the users of those clients tend to get this + message a lot. Another cause of this message is a background "check for new mail" task which does its work by opening a POP session to @@ -2364,9 +2554,11 @@ mtest.c:515: the `gets' function is dangerous and should not be used. a way to announce new mail. The solution to both situations is to replace the client with a - good online IMAP client such as Pine. Life is too short to + good online IMAP client such as Alpine. Life is too short to waste on POP clients and poorly-designed IMAP clients. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.20 Why does my IMAP client show all the files on the system, recursively from the UNIX root directory? @@ -2374,36 +2566,40 @@ mtest.c:515: the `gets' function is dangerous and should not be used. UNIX home directory? A well-written client should only show one level of hierarchy - and then stop, awaiting explicit user action before going - lower. However, some poorly-designed clients will recursively - list all files, which may be a very long list (especially if - you have symbolic links to directories that create a loop in - the filesystem graph!). + and then stop, awaiting explicit user action before going lower. + However, some poorly-designed clients will recursively list all + files, which may be a very long list (especially if you have + symbolic links to directories that create a loop in the + filesystem graph!). This behavior has also been observed in some third-party c-client drivers, including maildir drivers. Consequently, this - problem has even been observed in Pine. It is important to - understand that this is not a problem in Pine or c-client; it - is a problem in the third-party driver. A Pine built without + problem has even been observed in Alpine. It is important to + understand that this is not a problem in Alpine or c-client; it + is a problem in the third-party driver. A Alpine built without that third-party driver will not have this problem. - See also the answer to Why does my IMAP client show all my - files in my home directory? - _________________________________________________________________ + See also the answer to Why does my IMAP client show all my files + in my home directory? + + Back to top + __________________________________________________________________ 7.22 Why does my IMAP client show that I have mailboxes named "#mhinbox", "#mh", "#shared", "#ftp", "#news", and "#public"? - These are IMAP namespace names. They represent other - hierarchies in which messages may exist. These hierarchies may - not necessarily exist on a server, but the namespace name is - still in the namespace list in order to mark it as reserved. + These are IMAP namespace names. They represent other hierarchies + in which messages may exist. These hierarchies may not + necessarily exist on a server, but the namespace name is still + in the namespace list in order to mark it as reserved. A few poorly-designed clients display all namespace names as if they were top-level mailboxes in a user's list of mailboxes, whether or not they actually exist. This is a flaw in those clients. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.23 Why does my IMAP client show all my files in my home directory? @@ -2413,7 +2609,7 @@ mtest.c:515: the `gets' function is dangerous and should not be used. use IMAP to access any file. Most clients have an option to configure your connected - directory on the IMAP server. For example, in Pine you can + directory on the IMAP server. For example, in Alpine you can specify this as the "Path" in your folder-collection, e.g. Nickname : Secondary Folders @@ -2430,7 +2626,9 @@ mtest.c:515: the `gets' function is dangerous and should not be used. automatically connected to some other directory, e.g. a subdirectory of the user's home directory. Read the file CONFIG for more details. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.24 Why is there a long delay before I get connected to the IMAP or POP server, no matter what client I use? @@ -2445,10 +2643,10 @@ mtest.c:515: the `gets' function is dangerous and should not be used. The IDENT protocol is a well-known bad idea that does not deliver any real security but causes incredible problems. The idea is that this will give the server a record of the user - name, or at least what some program listening on port 113 - says is the user name. So, if somebody coming from port nnnnn - on a system does something bad, IDENT may give you the userid - of the bad guy. + name, or at least what some program listening on port 113 says + is the user name. So, if somebody coming from port nnnnn on a + system does something bad, IDENT may give you the userid of + the bad guy. The problem is, IDENT is only meaningful on a timesharing system which has an administrator who is privileged and users who are not. It is of no value on a personal system which has @@ -2466,74 +2664,76 @@ mtest.c:515: the `gets' function is dangerous and should not be used. log_on_success += USERID Hunt down such lines, and delete them ruthlessly from all files in which they occur. Don't be shy about it. - + The DNS is taking a long time to do a reverse DNS (PTR - record) lookup of the IP address of your client. This is a - problem in your DNS, which either you or you ISP need to - resolve. Ideally, the DNS should return the client's name; - but if it can't it should at least return an error quickly. - - As you may have noticed, neither of these are actual problems - in the IMAP or POP servers; they are configuration issues with + + The DNS is taking a long time to do a reverse DNS (PTR record) + lookup of the IP address of your client. This is a problem in + your DNS, which either you or you ISP need to resolve. + Ideally, the DNS should return the client's name; but if it + can't it should at least return an error quickly. + + As you may have noticed, neither of these are actual problems in + the IMAP or POP servers; they are configuration issues with either your system or your network infrastructure. If this is all new to you, run (don't walk) to the nearest technical bookstore and get yourself a good pedagogical text on system administration for the type of system you are running. - _________________________________________________________________ - 7.25 Why is there a long delay in Pine or any other c-client based + Back to top + __________________________________________________________________ + + 7.25 Why is there a long delay in Alpine or any other c-client based application call before I get connected to the IMAP server? The hang - seems to be in the c-client mail_open() call. I don't have this - problem with any other IMAP client. There is no delay connecting to a - POP3 or NNTP server with mail_open(). + seems to be in the c-client mail_open() call. I don't have this problem + with any other IMAP client. There is no delay connecting to a POP3 or + NNTP server with mail_open(). By default, the c-client library attempts to make a connection through rsh (and ssh, if you enable that). If the command: rsh imapserver exec /etc/rimapd - (or ssh if that is enabled) returns with a "* PREAUTH" - response, it will use the resulting rsh session as the IMAP - session and not require an authentication step on the server. + (or ssh if that is enabled) returns with a "* PREAUTH" response, + it will use the resulting rsh session as the IMAP session and + not require an authentication step on the server. Unfortunately, rsh has a design error that treats "TCP connection refused" as "temporary failure, try again"; it expects the "rsh not allowed" case to be implemented as a - successful connection followed by an error message and close - the connection. + successful connection followed by an error message and close the + connection. - It must be emphasized that this is a bug in rsh. It is not a - bug in the IMAP toolkit. + It must be emphasized that this is a bug in rsh. It is not a bug + in the IMAP toolkit. The use of rsh can be disabled in any the following ways: + You can disable it for this particular session by either: - o setting an explicit port number in the mailbox name, - e.g. + o setting an explicit port number in the mailbox name, e.g. {imapserver.foo.com:143}INBOX o using SSL (the /ssl switch) + You can disable rsh globally by setting the rsh timeout value to 0 with the call: mail_parameters (NIL,SET_RSHTIMEOUT,0); - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.26 Why does a message sometimes get split into two or more messages on my SUN system? This is caused by an interaction of two independent design problems in SUN mail software. The first problem is that the - "forward message" option in SUN's mail tool program includes - the internal "From " header line in the text that it forwarded. - This internal header line is specific to traditional UNIX - mailbox files and is not suitable for use in forwarded - messages. + "forward message" option in SUN's mail tool program includes the + internal "From " header line in the text that it forwarded. This + internal header line is specific to traditional UNIX mailbox + files and is not suitable for use in forwarded messages. The second problem is that the mail delivery agent assumes that mail reading programs will not use the traditional UNIX mailbox format but instead an incompatible variant that depends upon a Content-Length: message header. Content-Length is widely recognized to have been a terrible mistake, and is no longer - recommended for use in mail (it is used in other facilities - that use MIME). + recommended for use in mail (it is used in other facilities that + use MIME). One symptom of the problem is that under certain circumstances, a message may get broken up into several messages. I'm also @@ -2541,20 +2741,22 @@ mtest.c:515: the `gets' function is dangerous and should not be used. "Content-Length:" headers with evil values. To fix the mailer on your system, edit your sendmail.cf to - change the Mlocal line to have the -E flag. A typical entry - will lool like: + change the Mlocal line to have the -E flag. A typical entry will + lool like: Mlocal, P=/usr/lib/mail.local, F=flsSDFMmnPE, S=10, R=20, A=mail.local -d $u This fix will also work around the problem with mail tool, because it will insert a ">" before the internal header line to - prevent it from being interpreted by mail reading software as - an internal header line. - _________________________________________________________________ + prevent it from being interpreted by mail reading software as an + internal header line. - 7.27 Why did my POP or IMAP session suddenly disconnect? The syslog - has the message: + Back to top + __________________________________________________________________ + + 7.27 Why did my POP or IMAP session suddenly disconnect? The syslog has + the message: Autologout user=<...my user name...> host=<...my client system...> This is a problem in your client. @@ -2562,7 +2764,9 @@ mtest.c:515: the `gets' function is dangerous and should not be used. In the case of IMAP, it failed to communicate with the IMAP server for over 30 minutes; in the case of POP, it failed to communicate with the POP server for over 10 minutes. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.28 What does the UNIX error message: TLS/SSL failure: myserver: SSL negotiation failed mean? @@ -2576,7 +2780,9 @@ mtest.c:515: the `gets' function is dangerous and should not be used. Use the /notls option in the mailbox name to disable TLS negotiation. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.30 What does the error message: TLS/SSL failure: myserver: Server name does not match certificate mean? @@ -2591,7 +2797,9 @@ mtest.c:515: the `gets' function is dangerous and should not be used. Use the /novalidate-cert option in the mailbox name to disable validation of the certificate. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.31 What does the UNIX error message: TLS/SSL failure: myserver: self-signed certificate mean? @@ -2601,22 +2809,24 @@ mtest.c:515: the `gets' function is dangerous and should not be used. An SSL or TLS session encryption failed because your server's certificate is "self-signed"; that is, it is not signed by any Certificate Authority (CA) and thus can not be validated. A - CA-signed certificate costs money, and some smaller sites - either don't want to pay for it or haven't gotten one yet. The - bad part about this is that this means there is no guarantee - that the server is really the system you think that it is. + CA-signed certificate costs money, and some smaller sites either + don't want to pay for it or haven't gotten one yet. The bad part + about this is that this means there is no guarantee that the + server is really the system you think that it is. Use the /novalidate-cert option in the mailbox name to disable validation of the certificate. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.33 What does the UNIX error message: TLS/SSL failure: myserver: unable to get local issuer certificate mean? - An SSL or TLS session encryption failed because your system - does not have the Certificate Authority (CA) certificates - installed on OpenSSL's certificates directory. On most systems, - this directory is /usr/local/ssl/certs). As a result, it is not + An SSL or TLS session encryption failed because your system does + not have the Certificate Authority (CA) certificates installed + on OpenSSL's certificates directory. On most systems, this + directory is /usr/local/ssl/certs). As a result, it is not possible to validate the server's certificate. If CA certificates are properly installed, you should see @@ -2625,20 +2835,22 @@ mtest.c:515: the `gets' function is dangerous and should not be used. As a workaround, you can use the /novalidate-cert option in the mailbox name to disable validation of the certificate; however, - note that you are then vulnerable to various security attacks - by bad guys. + note that you are then vulnerable to various security attacks by + bad guys. The correct fix is to copy all the files from the certs/ directory in the OpenSSL distribution to the - /usr/local/ssl/certs (or whatever) directory. Note that you - need to do this after building OpenSSL, because the OpenSSL - build creates a number of needed symbolic links. For some - bizarre reason, the OpenSSL "make install" doesn't do this for - you, so you must do it manually. - _________________________________________________________________ + /usr/local/ssl/certs (or whatever) directory. Note that you need + to do this after building OpenSSL, because the OpenSSL build + creates a number of needed symbolic links. For some bizarre + reason, the OpenSSL "make install" doesn't do this for you, so + you must do it manually. + + Back to top + __________________________________________________________________ 7.34 Why does reading certain messages hang when using Netscape? It - works fine with Pine! + works fine with Alpine! There are two possible causes. @@ -2647,18 +2859,19 @@ mtest.c:515: the `gets' function is dangerous and should not be used. regarding that message. Check the affected mailbox to see if there are embedded NUL - characters in the message. NULs in message texts are a - technical violation of both the message format and IMAP - specifications. Most clients don't care, but apparently - Netscape does. + characters in the message. NULs in message texts are a technical + violation of both the message format and IMAP specifications. + Most clients don't care, but apparently Netscape does. You can work around this by rebuilding imapd with the NETSCAPE_BRAIN_DAMAGE option set (see src/imapd/Makefile); this will cause imapd to convert all NULs to 0x80 characters. A better solution is to enable the feature in your MTA to - MIME-convert messages with binary content. See the - documentation for your MTA for how to do this. - _________________________________________________________________ + MIME-convert messages with binary content. See the documentation + for your MTA for how to do this. + + Back to top + __________________________________________________________________ 7.35 Why does Netscape say that there's a problem with the IMAP server and that I should "Contact your mail server administrator."? @@ -2670,20 +2883,24 @@ mtest.c:515: the `gets' function is dangerous and should not be used. You can work around this by rebuilding imapd with the NETSCAPE_BRAIN_DAMAGE option set (see src/imapd/Makefile) to a URL that points either to an alternative IMAP client (e.g. - Pine) or perhaps to a homebrew mail account management page. - _________________________________________________________________ + Alpine) or perhaps to a homebrew mail account management page. + + Back to top + __________________________________________________________________ 7.36 Why is one user creating huge numbers of IMAP or POP server sessions? - The user is probably using Outlook Express, Eudora, or a - similar program. See the answer to the Help! My load average is - soaring and I see hundreds of POP and IMAP servers, many logged - in as the same user! question. - _________________________________________________________________ + The user is probably using Outlook Express, Eudora, or a similar + program. See the answer to the Help! My load average is soaring + and I see hundreds of POP and IMAP servers, many logged in as + the same user! question. + + Back to top + __________________________________________________________________ - 7.37 Why don't I get any new mail notifications from Outlook Express - or Outlook after a while? + 7.37 Why don't I get any new mail notifications from Outlook Express or + Outlook after a while? This is a known bug in Outlook Express. Microsoft is aware of the problem and its cause. They have informed us that they do @@ -2692,20 +2909,19 @@ mtest.c:515: the `gets' function is dangerous and should not be used. The problem is also reported in Outlook 2000, but not verified. Outlook Express uses the IMAP IDLE command to avoid having to - "ping" the server every few minutes for new mail. - Unfortunately, Outlook Express overlooks the part in the IDLE - specification which requires that a client terminate and - restart the IDLE before the IMAP 30 minute inactivity - autologout timer triggers. + "ping" the server every few minutes for new mail. Unfortunately, + Outlook Express overlooks the part in the IDLE specification + which requires that a client terminate and restart the IDLE + before the IMAP 30 minute inactivity autologout timer triggers. When this happens, Outlook Express displays "Not connected" at the bottom of the window. Since it's no longer connected to the IMAP server, it isn't going to notice any new mail. As soon as the user does anything that would cause an IMAP - operation, Outlook Express will reconnect and new mail will - flow again. If the user does something that causes an IMAP - operation at least every 29 minutes, the problem won't happen. + operation, Outlook Express will reconnect and new mail will flow + again. If the user does something that causes an IMAP operation + at least every 29 minutes, the problem won't happen. Modern versions of imapd attempt to work around the problem by automatically reporting fake new mail after 29 minutes. This @@ -2713,7 +2929,9 @@ mtest.c:515: the `gets' function is dangerous and should not be used. happens imapd revokes the fake new mail. As long as this behavior isn't known to cause problems with other clients, this workaround will remain in imapd. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.38 Why don't I get any new mail notifications from Entourage? @@ -2727,7 +2945,9 @@ mtest.c:515: the `gets' function is dangerous and should not be used. Note: the MICROSOFT_BRAIN_DAMAGE option no longer exists in modern versions, as the Outlook Express problem which it attempted to solve has been worked around in another way. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.39 Why doesn't Entourage work at all? @@ -2737,14 +2957,16 @@ mtest.c:515: the `gets' function is dangerous and should not be used. like STATUS (MESSAGES) on the currently selected mailbox and re-fetching the same static data over and over again. - It seems that every time we understand what it is doing wrong - in Entourage and come up with a workaround, we learn about + It seems that every time we understand what it is doing wrong in + Entourage and come up with a workaround, we learn about something else that's broken. Try building imapd with the ENTOURAGE_BRAIN_DAMAGE option set, - in order to disable the diagnostic that occurs when doing - STATUS on the currently selected mailbox. - _________________________________________________________________ + in order to disable the diagnostic that occurs when doing STATUS + on the currently selected mailbox. + + Back to top + __________________________________________________________________ 7.40 Why doesn't Netscape Notify (NSNOTIFY.EXE) work at all? @@ -2753,15 +2975,17 @@ mtest.c:515: the `gets' function is dangerous and should not be used. Fortunately, there is no reason to use this program with IMAP; NSNOTIFY is a polling program to let you know when new mail has - appeared in your maildrop. This is necessary with POP; but - since IMAP dynamically announces new mail in the session you're - better off (and will actually cause less load on the server!) - keeping your mail reading program's IMAP session open and let - IMAP do the notifying for you. + appeared in your maildrop. This is necessary with POP; but since + IMAP dynamically announces new mail in the session you're better + off (and will actually cause less load on the server!) keeping + your mail reading program's IMAP session open and let IMAP do + the notifying for you. + + Consequently, the recommended fix for the NSNOTIFY problem is to + delete the NSNOTIFY binary. - Consequently, the recommended fix for the NSNOTIFY problem is - to delete the NSNOTIFY binary. - _________________________________________________________________ + Back to top + __________________________________________________________________ 7.41 Why can't I connect via SSL to Eudora? It says the connection has been broken, and in the server syslogs I see "Command stream end of @@ -2770,16 +2994,18 @@ mtest.c:515: the `gets' function is dangerous and should not be used. There is a report that you can fix the problem by going into Eudora's advanced network configuration menu and increasing the network buffer size to 8192. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.42 Sheesh. Aren't there any good IMAP clients out there? Yes! - Pine is a wonderful client. It's fast, it uses IMAP well, and + Alpine is a wonderful client. It's fast, it uses IMAP well, and it generates text mail (life is too short to waste on HTML mail). Also, there are some really wonderful things in progress - in the Pine world. + in the Alpine world. There are some good GUI clients out there, mostly from smaller vendors. Without naming names, look for the vendors who are @@ -2787,22 +3013,24 @@ mtest.c:515: the `gets' function is dangerous and should not be used. products. Netscape, Eudora, and Outlook can be configured with enough - effort to be good citizens and work well for users, but they - can also be badly misconfigured, and often the misconfiguration - is the default. - _________________________________________________________________ + effort to be good citizens and work well for users, but they can + also be badly misconfigured, and often the misconfiguration is + the default. - 7.43 But wait! PC Pine (or other PC program build with c-client) + Back to top + __________________________________________________________________ + + 7.43 But wait! PC Alpine (or other PC program build with c-client) crashes with the message incomplete SecBuffer exceeds maximum buffer size when I use SSL connections. This is a bug in c-client, right? It's a bug in the Microsoft SChannel.DLL, which implements SSL. - Microsoft admits it (albeit with an unstatement: "it's not - fully RFC compliant"). The problem is that SChannel indicates - that the maximum SSL packet data size is 5 bytes smaller than - the actual maximum. Thus, any IMAP server which transmits a - maximum sized SSL packet will not work with PC Pine or any - other program which uses SChannel. + Microsoft admits it (albeit with an unstatement: "it's not fully + RFC compliant"). The problem is that SChannel indicates that the + maximum SSL packet data size is 5 bytes smaller than the actual + maximum. Thus, any IMAP server which transmits a maximum sized + SSL packet will not work with PC Alpine or any other program + which uses SChannel. It can take a while for the problem to show up. The client has to do something that causes at least 16K of contiguous data. @@ -2810,8 +3038,8 @@ mtest.c:515: the `gets' function is dangerous and should not be used. number of cases where this can happen. However, all software which uses SChannel to support SSL is affected by this bug. - This problem does not affect UNIX code, since OpenSSL is used - on UNIX. + This problem does not affect UNIX code, since OpenSSL is used on + UNIX. This problem most recently showed up with the CommunigatePro IMAP server. They have an update which trims down their maximum @@ -2819,24 +3047,26 @@ mtest.c:515: the `gets' function is dangerous and should not be used. problem. This problem has also shown up with the Exchange IMAP server - with UNIX clients (including Pine built with an older version + with UNIX clients (including Alpine built with an older version of c-client) which sends full-sized 16K SSL packets. Modern c-client works around the problem by trimming down its maximum outgoing SSL packet size to 8K. Microsoft has developed a hotfix for this bug. Look up MSKB article number 300562. Contrary to the article text which - implies that this is a Pine issue, this bug also affect + implies that this is a Alpine issue, this bug also affect Microsoft Exchange server with *any* UNIX based client that transmits full-sized SSL payloads. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.44 My qpopper users keep on getting the DON'T DELETE THIS MESSAGE -- - FOLDER INTERNAL DATA if they also use Pine or IMAP. How can I fix + FOLDER INTERNAL DATA if they also use Alpine or IMAP. How can I fix this? This is an incompatibility between qpopper and the c-client - library used by Pine, imapd, and ipop[23]d. + library used by Alpine, imapd, and ipop[23]d. Assuming that you want to continue using qpopper, look into qpopper's --enable-uw-kludge-flag configuration flag, which is @@ -2844,21 +3074,22 @@ mtest.c:515: the `gets' function is dangerous and should not be used. messages". The other alternative is to switch from qpopper to ipop3d. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.45 Help! I installed the servers but I can't connect to them from my client! Review the installation instructions carefully. Make sure that you have not skipped any of the steps. Make sure that you have - made the correct entries in the configuration files; pay - careful attention to the exact spelling of the service names - and the path names. Make sure as well that you have properly - restarted inetd. + made the correct entries in the configuration files; pay careful + attention to the exact spelling of the service names and the + path names. Make sure as well that you have properly restarted + inetd. - If you have a system with Yellow Pages/NIS such as Solaris, - have you updated the service names there as well as in - /etc/services? + If you have a system with Yellow Pages/NIS such as Solaris, have + you updated the service names there as well as in /etc/services? If you have a system with TCP wrappers, have you properly updated the TCP wrapper files (e.g. /etc/hosts.allow and @@ -2869,25 +3100,26 @@ mtest.c:515: the `gets' function is dangerous and should not be used. xinetd changes for those services? Try telneting to the server port (143 for IMAP, 110 for POP3). - If you get a "refused" error, that probably means that you - don't have the service set up in inetd.conf. If the connection - opens and then closes with no message, the service is set up, - but either the path name of the server binary in inetd.conf is - wrong or your TCP wrappers are configured to deny access. + If you get a "refused" error, that probably means that you don't + have the service set up in inetd.conf. If the connection opens + and then closes with no message, the service is set up, but + either the path name of the server binary in inetd.conf is wrong + or your TCP wrappers are configured to deny access. + + If you don't know how to make the corresponding changes to these + files, seek the help of a local expert for your system. - If you don't know how to make the corresponding changes to - these files, seek the help of a local expert for your system. - _________________________________________________________________ + Back to top + __________________________________________________________________ 7.46 Why do I get the message Can not authenticate to SMTP server: 421 SMTP connection went away! and why did this happen? There was also - something about SECURITY PROBLEM: insecure server advertised - AUTH=PLAIN + something about SECURITY PROBLEM: insecure server advertised AUTH=PLAIN Some versions of qmail, including that running on mail.smtp.yahoo.com, disconnect the SMTP session if you fail to - authenticate prior to attempting to transmit mail. An attempt - to authenticate was made, but it failed because the server had + authenticate prior to attempting to transmit mail. An attempt to + authenticate was made, but it failed because the server had already disconnected. To work around this, you need to specify /user=... in the host @@ -2895,14 +3127,16 @@ mtest.c:515: the `gets' function is dangerous and should not be used. The SECURITY PROBLEM came about because the server advertised the AUTH=PLAIN SASL authentication mechanism outside of a - TLS-encrypted session, in violation of RFC 4616. This message - is just a warning, and in fact occurred after the server had + TLS-encrypted session, in violation of RFC 4616. This message is + just a warning, and in fact occurred after the server had disconnected. - _________________________________________________________________ - 7.47 Why do I get the message SMTP Authentication cancelled and why - did this happen? There was also something about SECURITY PROBLEM: - insecure server advertised AUTH=PLAIN + Back to top + __________________________________________________________________ + + 7.47 Why do I get the message SMTP Authentication cancelled and why did + this happen? There was also something about SECURITY PROBLEM: insecure + server advertised AUTH=PLAIN This is a bug in the SMTP server. @@ -2923,15 +3157,17 @@ mtest.c:515: the `gets' function is dangerous and should not be used. In the case of AUTH=PLAIN, RFC 4422 (page 7) requires that the encoded string have no data. In other words, the appropropiate - standards-compliant server response is "334" followed by a - SPACE and a CRLF. + standards-compliant server response is "334" followed by a SPACE + and a CRLF. The SECURITY PROBLEM came about because the server advertised the AUTH=PLAIN SASL authentication mechanism outside of a - TLS-encrypted session, in violation of RFC 4616. This message - is just a warning, and is not related the "Authentication + TLS-encrypted session, in violation of RFC 4616. This message is + just a warning, and is not related the "Authentication cancelled" problem. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 7.48 Why do I get the message Invalid base64 string when I try to authenticate to a Cyrus server? @@ -2947,10 +3183,12 @@ mtest.c:515: the `gets' function is dangerous and should not be used. via Kerberos, fail to get the Kerberos credentials, cancel the authentication attempt, and try the next available authentication technology. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 8. Where to Go For Additional Information - _________________________________________________________________ + __________________________________________________________________ 8.1 Where can I go to ask questions? 8.2 I have some ideas for enhancements to IMAP. Where should I go? @@ -2958,28 +3196,22 @@ mtest.c:515: the `gets' function is dangerous and should not be used. If you have questions about the IMAP protocol, or want to participate in discussions of future directions of the IMAP protocol, the appropriate mailing list is - imap-protocol@u.washington.edu. You can subscribe to this - list via imap-protocol-request@u.washington.edu + imap-protocol@u.washington.edu. You can subscribe to this list + via imap-protocol-request@u.washington.edu - If you have questions about this software, you can send me - email directly or use the imap-uw@u.washington.edu mailing - list. You can subscribe to this list via - imap-uw-request@u.washington.edu - - If you have general questions about the use of IMAP software - (not specific to the UW IMAP toolkit) use the - imap-use@u.washington.edu mailing list. You can subscribe to - this list via imap-use-request@u.washington.edu - - You must be a subscriber to post to these lists. As an + You must be a subscriber to post to this list. As an alternative, you can use the comp.mail.imap newsgroup. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 8.3 Where can I read more about IMAP and other email protocols? We recommend Internet Email Protocols: A Developer's Guide, by Kevin Johnson, published by Addison Wesley, ISBN 0-201-43288-9. - _________________________________________________________________ + + Back to top + __________________________________________________________________ 8.4 Where can I find out more about setting up and administering an IMAP server? @@ -2987,7 +3219,6 @@ mtest.c:515: the `gets' function is dangerous and should not be used. We recommend Managing IMAP, by Dianna Mullet & Kevin Mullet, published by O'Reilly, ISBN 0-596-00012-X. - This book also has an excellent comparison of the UW and Cyrus - IMAP servers. + Back to top - Last Updated: 15 November 2007 + Last Updated: 5 May 2010 diff --git a/imap/docs/RELNOTES b/imap/docs/RELNOTES index 5cfd9132..80e17967 100644 --- a/imap/docs/RELNOTES +++ b/imap/docs/RELNOTES @@ -1,29 +1,154 @@ /* ======================================================================== - * Copyright 1988-2008 University of Washington - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * + * Copyright 2012 Mark Crispin * ======================================================================== */ -Updated: 16 December 2008 -imap-2007e is a maintenance release, consisting primarily of bugfixes to -problems discovered in the release that affected a small number of users -plus a security fix for users of the RFC822BUFFER routines. +Updated: 21 February 2012 + +imap-2010 is Panda IMAP, forked from the University of Washington's +final imap-2007b. + +Update version and copyright information. + +New compare_string() routine which implements i;octet collation. + +compare_cstring() now collates "[", "\", "]", and "_" after alphabetics to +be consistent with how i;unicode-casemap is defined. + +i;unicode-casemap collation now uses compare_string() instead of +compare_cstring(). The case-mapping of compare_cstring() is unnecessary +because the strings have already been titlecased and decomposed via +U8T_CANONICAL conversion. The previous version of compare_cstring() +casemapped via conversion to lowercase, which violates of RFC 5051 for +characters "[", "\", "]", and "_". + +Fix tag parsing to avoid HTML/IMAP cross script vulnerability problem. Tags +are now syntax checked and the connection is closed after a bad command when +not logged in. + +Fix address sorting when the address list started with a group and the +message had not yet been parsed. Also, cc sorting did not handle +additional cc lines (as opposed to continuation lines) correctly. + +Fix server terminations when a status request signal is received while in +command input wait. + +Fix crash if SMTP server closes the session right before a QUIT is sent. + +Fix crash on some systems if IMAP server sends negative value for literal +size count. + +Mailbox compression ("burping") can now occur during IMAP IDLE. + +Fix root-compromise security bug in tmail, and user-compromise security bug +in dmail. + +Extend mailutil's -u flag to parse arguments in the context of the -u user +and disregard any restrictBox settings. + +Restrict SSL/TLS encryption algorithms to be PCI auditing compliant. + +Fix possible memory corruption problem in imapd. + +Fix longstanding problem in parsing lowercase FETCH attributes in IMAP after +a literal. + +Fix memory leak problem burping mix format mailboxes. + +Fix crash with -I switch in tmail caused by reference to uninitialized +variable. + +Fix reference to freed memory space in mix burping that led to attempts to +delete arbitrary file names. + +Fix crash when string output in RFC822 routines exactly matches the buffer +size. + +Fix crash in IMAP client on Windows in certain circumstances when IMAP +server disconnects while reading a response. + +Fix incorrect legacy INBOX file name creation on black box systems. + +Fix exploitable buffer overrun problem. + +Support QNX 6 + +Fix a problem that could cause mix mailbox corruption. +Rewrite imapd's signal handling (again) to fix corrupt in traditional UNIX +mailbox files. -Updated: 29 October 2008 +Recognize when the client is BlackBerry Internet Service, and allow mailbox +burping even when readonly. -imap-2007d is a maintenance release, consisting primarily of bugfixes to -problems discovered in the release that affected a small number of users -plus a security fix for users of tmail or dmail. +Fix a crash in the IMAP client code caused by non-compliant servers. +Fix problem in scandir code triggered by ZFS on Solaris. + +Fix quoted-printable handling in error case. + +OpenSSL 1.0.0 compatibility (OpenSSL has a STRING type) + +Fix Shift-JIS decoding. + +New oxs port for building under Mac OS X Snow Leopard. + +Fixes to build cleanly in new 64-bit gcc. + +Prevent crash if session closed unexpectedly during SSL I/O. + +Fix IMAP namespace handling. + +Detect corruption when message added with out of order UID. + +The c-client library is now thread-safe in the IPv6 version of the UNIX and +Windows builds. IPv4 and legacy (e.g., DOS, VMS) builds are NOT thread-safe. + +Fixed a memory leak that occurs each time a TCP connection is open. + +Fixed UTF-8 input validation; some valid UTF-8 sequences were rejected and +some invalid ones where accepted. + +Fix incorrect message message deletion in UID EXPUNGE. + +Fix crash in internal rfc822 parsing routines if external consumer calls +with a null defaulthost. + +Workaround to support iPhone/iPod Touch running iOS4. + +Fix buffer overflow in IMAP client code. + +Fix thread safety issues in MD5 authentication and subscription manager. + +Fix additional buffer overflows in IMAP client code. + +Fix memory name in IPv6 DNS lookup. + +Up to three bad commands permitted when not logged in to avoid problems with +clients that don't check capabilities. + +Fix off-by-one error in SASL-IR authentication. + +Fix memory leak when server sends invalid BODYSTRUCTURE data. + +Fix threading problem creating TCP socket. + +Fix loop caused by syntax errors from GMail IMAP server. + +Fix over-quota problem. + +/* + * Previous versions of this file were + * + * Copyright 1988-2008 University of Washington + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + */ Updated: 25 March 2008 diff --git a/imap/docs/draft/README b/imap/docs/draft/README deleted file mode 100644 index 9aec4719..00000000 --- a/imap/docs/draft/README +++ /dev/null @@ -1,19 +0,0 @@ -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 diff --git a/imap/docs/draft/i18n.txt b/imap/docs/draft/i18n.txt deleted file mode 100644 index f47c6cc7..00000000 --- a/imap/docs/draft/i18n.txt +++ /dev/null @@ -1,1140 +0,0 @@ -
-
-
-
-
-
-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]
-
-
diff --git a/imap/docs/README.rfc b/imap/docs/rfc/README index d320a3bb..b808150e 100644 --- a/imap/docs/README.rfc +++ b/imap/docs/rfc/README @@ -1,7 +1,3 @@ -This distribution used to contain a copy of RFCs that are relevant to the -implementation of IMAP support in the c-client library. These have been -removed, but the list of relevant RFCs is listed below. - The following documents are necessary to understand the syntax rules most of the remaining documents. Note that some documents refer to RFC 2234 which has been replaced by RFC 5234: @@ -19,31 +15,47 @@ in understanding the IMAP protocol: rfc2180.txt IMAP4 Multi-Accessed Mailbox Practice rfc2683.txt IMAP4 Implementation Recommendations rfc4549.txt Synchronization Operations for Disconnected IMAP4 Clients - + rfc5530.txt IMAP Response Codes + rfc5788.txt IMAP4 Keyword Registry The following documents describe extensions to the IMAP protocol. Items marked with "*" are supported in this distribution: rfc4314.txt ACL + rfc5257.txt ANNOTATE-EXPERIMENT-1 * rfc3516.txt BINARY rfc4469.txt CATENATE * rfc3348.txt CHILDREN rfc4978.txt COMPRESS rfc4551.txt CONDSTORE + rfc5259.txt CONVERT + rfc5267.txt CONTEXT rfc5161.txt ENABLE * rfc4731.txt ESEARCH + rfc5267.txt ESORT + rfc5466.txt FILTERS + * rfc5255.txt I18NLEVEL=1 rfc2971.txt ID * rfc2177.txt IDLE + rfc5255.txt LANGUAGE + rfc5258.txt LIST-EXTENDED + rfc5819.txt LIST-STATUS * rfc2088.txt LITERAL+ * rfc2221.txt LOGIN-REFERRALS * rfc2193.txt MAILBOX-REFERRALS + rfc5464.txt METADATA * rfc3502.txt MULTIAPPEND * rfc2342.txt NAMESPACE + rfc5465.txt NOTIFY rfc5162.txt QRESYNC rfc2087.txt QUOTA * rfc4959.txt SASL-IR + * rfc5256.txt SORT + * rfc5256.txt THREAD * rfc4315.txt UIDPLUS * rfc3691.txt UNSELECT rfc4467.txt URLAUTH + rfc5524.txt URLAUTH=BINARY + rfc5738.txt UTF8 (EXPERIMENTAL) * rfc5032.txt WITHIN @@ -59,7 +71,7 @@ and the SASL mechanisms supported in this distribution: The following documents relate to internationalization issues: rfc4790.txt Internet Application Protocol Collation Registry rfc5051.txt i;unicode-casemap - Simple Unicode Collation Algorithm - + rfc5738.txt IMAP Support for UTF-8 (EXPERIMENTAL) The following documents are primarily of historic interest: rfc1732.txt IMAP4 Compatibility with IMAP2 and IMAP2bis @@ -72,3 +84,4 @@ The following documents discuss matters which are related to IMAP: rfc3656.txt MUPDATE Distributed Mailbox Database Protocol rfc4468.txt Message Submission BURL Extension rfc5092.txt IMAP URL Scheme + rfc5593.txt IMAP URL Access Identifier Extension diff --git a/imap/docs/rfc/rfc1732.txt b/imap/docs/rfc/rfc1732.txt new file mode 100644 index 00000000..cfae89c0 --- /dev/null +++ b/imap/docs/rfc/rfc1732.txt @@ -0,0 +1,283 @@ + + + + + + +Network Working Group M. Crispin +Request for Comments: 1732 University of Washington +Category: Informational December 1994 + + + IMAP4 COMPATIBILITY WITH IMAP2 AND IMAP2BIS + + +Status of this Memo + + This memo provides information for the Internet community. This memo + does not specify an Internet standard of any kind. Distribution of + this memo is unlimited. + +Introduction + + This is a summary of hints and recommendations to enable an IMAP4 + implementation to interoperate with implementations that conform to + earlier specifications. None of these hints and recommendations are + required by the IMAP4 specification; implementors must decide for + themselves whether they want their implementation to fail if it + encounters old software. + + IMAP4 has been designed to be upwards compatible with earlier + specifications. For the most part, IMAP4 facilities that were not in + earlier specifications should be invisible to clients unless the + client asks for the facility. + + In some cases, older servers may support some of the capabilities + listed as being "new in IMAP4" as experimental extensions to the + IMAP2 protocol described in RFC 1176. + + This information may not be complete; it reflects current knowledge + of server and client implementations as well as "folklore" acquired + in the evolution of the protocol. + + + + + + + + + + + + + + + + +Crispin [Page 1] + +RFC 1732 IMAP4 - Compatibility December 1994 + + +IMAP4 client interoperability with old servers + + In general, a client should be able to discover whether an IMAP2 + server supports a facility by trial-and-error; if an attempt to use a + facility generates a BAD response, the client can assume that the + server does not support the facility. + + A quick way to check whether a server implementation supports the + IMAP4 specification is to try the CAPABILITY command. An OK response + that includes the IMAP4 capability value indicates a server that + supports IMAP4; a BAD response or one without the IMAP4 capability + value indicates an older server. + + The following is a list of facilities that are only in IMAP4, and + suggestions for how new clients might interoperate with old servers: + + CAPABILITY command + A BAD response to this command indicates that the server + implements IMAP2 (or IMAP2bis) and not IMAP4. + + AUTHENTICATE command. + Use the LOGIN command. + + LSUB and LIST commands + Try the RFC 1176 FIND command. + + * in a sequence + Use the number of messages in the mailbox from the EXISTS + unsolicited response. + + SEARCH extensions (character set, additional criteria) + Reformulate the search request using only the searching + options listed in search_old in the IMAP4 grammar. This may + entail doing multiple searches to achieve the desired + results. + + BODYSTRUCTURE fetch data item + Try to fetch the non-extensible BODY data item. + + body section number 0 + Fetch the entire message and extract the header. + + RFC822.HEADER.LINES and RFC822.HEADER.LINES.NOT fetch data items + Use RFC822.HEADER and remove the unwanted information. + + BODY.PEEK[section], RFC822.PEEK, and RFC822.TEXT.PEEK fetch data + items Use the corresponding non-PEEK versions and manually + clear the \Seen flag as necessary. + + + +Crispin [Page 2] + +RFC 1732 IMAP4 - Compatibility December 1994 + + + UID fetch data item and the UID commands + No equivalent capabilitity exists in older servers. + + FLAGS.SILENT, +FLAGS.SILENT, and -FLAGS.SILENT store data items + Use the corresponding non-SILENT versions and ignore the + untagged FETCH responses which com eback. + + + The following IMAP4 facilities were introduced in the experimental + IMAP2bis revisions to RFC-1176, and may be present in a server that + does not support the CAPABILITY command: + + CREATE, DELETE, and RENAME commands + To test whether these commands are present, try a CREATE + INBOX command. If the response is NO, these commands are + supported by the server. If the response is BAD, they are + not. Older servers without the CREATE capability may sup- + port implicit creation of a mailbox by a COPY command with a + non-existant name as the destination. + + APPEND command + To test whether this command is present, try to append a + zero-length stream to a mailbox name that is known not to + exist (or at least, highly unlikely to exist) on the remote + system. + + SUBSCRIBE and UNSUBSCRIBE commands + Try the form of these commands with the optional MAILBOX + keyword. + + EXAMINE command + Use the SELECT command instead. + + flags and internal date argument to APPEND command + Try the APPEND without any flag list and internal date argu- + ments. + + BODY, BODY[section], and FULL fetch data items + Use RFC822.TEXT and ALL instead. Server does not support + MIME. + + PARTIAL command + Use the appropriate FETCH command and ignore the unwanted + data. + + + IMAP4 client implementations must accept all responses and data for- + mats documented in the IMAP4 specification, including those labeled + + + +Crispin [Page 3] + +RFC 1732 IMAP4 - Compatibility December 1994 + + + as obsolete. This includes the COPY and STORE unsolicited responses + and the old format of dates and times. In particular, client imple- + mentations must not treat a date/time as a fixed format string; nor + may they assume that the time begins at a particular octet. + + IMAP4 client implementations must not depend upon the presence of any + server extensions that are not in the base IMAP4 specification. + + The experimental IMAP2bis version specified that the TRYCREATE spe- + cial information token is sent as a separate unsolicited OK response + instead of inside the NO response. + + The FIND BBOARDS, FIND ALL.BBOARDS, and BBOARD commands of RFC 1176 + are removed from IMAP4. There is no equivalent to the bboard com- + mands, which provided a separate namespace with implicit restrictions + on what may be done in that namespace. + + Older server implementations may automatically create the destination + mailbox on COPY if that mailbox does not already exist. This was how + a new mailbox was created in older specifications. If the server + does not support the CREATE command (see above for how to test for + this), it will probably create a mailbox on COPY. + + Older server implementations may not preserve flags or internal dates + on COPY. Some server implementations may not permit the preservation + of certain flags on COPY or their setting with APPEND as site policy. + + + + + + + + + + + + + + + + + + + + + + + + + +Crispin [Page 4] + +RFC 1732 IMAP4 - Compatibility December 1994 + + +IMAP4 server interoperability with old clients + + In general, there should be no interoperation problem between a + server conforming to the IMAP4 specification and a well-written + client that conforms to an earlier specification. Known problems are + noted below: + + Poor wording in the description of the CHECK command in earlier + specifications implied that a CHECK command is the way to get the + current number of messages in the mailbox. This is incorrect. A + CHECK command does not necessarily result in an EXISTS response. + Clients must remember the most recent EXISTS value sent from the + server, and should not generate unnecessary CHECK commands. + + An incompatibility exists with COPY in IMAP4. COPY in IMAP4 + servers does not automatically create the destination mailbox if + that mailbox does not already exist. This may cause problems with + old clients that expect automatic mailbox creation in COPY. + + The PREAUTH unsolicited response is new in IMAP4. It is highly + unlikely that an old client would ever see this response. + + The format of dates and times has changed due to the impending end + of the century. Clients that fail to accept a four-digit year or + a signed four-digit timezone value will not work properly with + IMAP4. + + An incompatibility exists with the use of "\" in quoted strings. + This is best avoided by using literals instead of quoted strings + if "\" or <"> is embedded in the string. + +Security Considerations + + Security issues are not discussed in this memo. + +Author's Address: + + Mark R. Crispin + Networks and Distributed Computing, JE-30 + University of Washington + Seattle, WA 98195 + + Phone: (206) 543-5762 + + EMail: MRC@CAC.Washington.EDU + + + + + + +Crispin [Page 5] + diff --git a/imap/docs/rfc/rfc1733.txt b/imap/docs/rfc/rfc1733.txt new file mode 100644 index 00000000..2ec385f0 --- /dev/null +++ b/imap/docs/rfc/rfc1733.txt @@ -0,0 +1,171 @@ + + + + + + +Network Working Group M. Crispin +Request for Comments: 1733 University of Washington +Category: Informational December 1994 + + + DISTRIBUTED ELECTRONIC MAIL MODELS IN IMAP4 + + +Status of this Memo + + This memo provides information for the Internet community. This memo + does not specify an Internet standard of any kind. Distribution of + this memo is unlimited. + + +Distributed Electronic Mail Models + + There are three fundamental models of client/server email: offline, + online, and disconnected use. IMAP4 can be used in any one of these + three models. + + The offline model is the most familiar form of client/server email + today, and is used by protocols such as POP-3 (RFC 1225) and UUCP. + In this model, a client application periodically connects to a + server. It downloads all the pending messages to the client machine + and deletes these from the server. Thereafter, all mail processing + is local to the client. This model is store-and-forward; it moves + mail on demand from an intermediate server (maildrop) to a single + destination machine. + + The online model is most commonly used with remote filesystem + protocols such as NFS. In this model, a client application + manipulates mailbox data on a server machine. A connection to the + server is maintained throughout the session. No mailbox data are + kept on the client; the client retrieves data from the server as is + needed. IMAP4 introduces a form of the online model that requires + considerably less network bandwidth than a remote filesystem + protocol, and provides the opportunity for using the server for CPU + or I/O intensive functions such as parsing and searching. + + The disconnected use model is a hybrid of the offline and online + models, and is used by protocols such as PCMAIL (RFC 1056). In this + model, a client user downloads some set of messages from the server, + manipulates them offline, then at some later time uploads the + changes. The server remains the authoritative repository of the + messages. The problems of synchronization (particularly when + multiple clients are involved) are handled through the means of + unique identifiers for each message. + + + +Crispin [Page 1] + +RFC 1733 IMAP4 - Model December 1994 + + + Each of these models have their own strengths and weaknesses: + + Feature Offline Online Disc + ------- ------- ------ ---- + Can use multiple clients NO YES YES + Minimum use of server connect time YES NO YES + Minimum use of server resources YES NO NO + Minimum use of client disk resources NO YES NO + Multiple remote mailboxes NO YES YES + Fast startup NO YES NO + Mail processing when not online YES NO YES + + Although IMAP4 has its origins as a protocol designed to accommodate + the online model, it can support the other two models as well. This + makes possible the creation of clients that can be used in any of the + three models. For example, a user may wish to switch between the + online and disconnected models on a regular basis (e.g. owing to + travel). + + IMAP4 is designed to transmit message data on demand, and to provide + the facilities necessary for a client to decide what data it needs at + any particular time. There is generally no need to do a wholesale + transfer of an entire mailbox or even of the complete text of a + message. This makes a difference in situations where the mailbox is + large, or when the link to the server is slow. + + More specifically, IMAP4 supports server-based RFC 822 and MIME + processing. With this information, it is possible for a client to + determine in advance whether it wishes to retrieve a particular + message or part of a message. For example, a user connected to an + IMAP4 server via a dialup link can determine that a message has a + 2000 byte text segment and a 40 megabyte video segment, and elect to + fetch only the text segment. + + In IMAP4, the client/server relationship lasts only for the duration + of the TCP connection. There is no registration of clients. Except + for any unique identifiers used in disconnected use operation, the + client initially has no knowledge of mailbox state and learns it from + the IMAP4 server when a mailbox is selected. This initial transfer + is minimal; the client requests additional state data as it needs. + + As noted above, the choice for the location of mailbox data depends + upon the model chosen. The location of message state (e.g. whether + or not a message has been read or answered) is also determined by the + model, and is not necessarily the same as the location of the mailbox + data. For example, in the online model message state can be co- + located with mailbox data; it can also be located elsewhere (on the + client or on a third agent) using unique identifiers to achieve + + + +Crispin [Page 2] + +RFC 1733 IMAP4 - Model December 1994 + + + common reference across sessions. The latter is particularly useful + with a server that exports public data such as netnews and does not + maintain per-user state. + + The IMAP4 protocol provides the generality to implement these + different models. This is done by means of server and (especially) + client configuration, and not by requiring changes to the protocol or + the implementation of the protocol. + + +Security Considerations + + Security issues are not discussed in this memo. + + +Author's Address: + + Mark R. Crispin + Networks and Distributed Computing, JE-30 + University of Washington + Seattle, WA 98195 + + Phone: (206) 543-5762 + + EMail: MRC@CAC.Washington.EDU + + + + + + + + + + + + + + + + + + + + + + + + + + +Crispin [Page 3] + diff --git a/imap/docs/rfc/rfc2061.txt b/imap/docs/rfc/rfc2061.txt new file mode 100644 index 00000000..7cb02bb2 --- /dev/null +++ b/imap/docs/rfc/rfc2061.txt @@ -0,0 +1,171 @@ + + + + + + +Network Working Group M. Crispin +Request for Comments: 2061 University of Washington +Category: Informational December 1996 + + + IMAP4 COMPATIBILITY WITH IMAP2BIS + +Status of this Memo + + This memo provides information for the Internet community. This memo + does not specify an Internet standard of any kind. Distribution of + this memo is unlimited. + +Introduction + + The Internet Message Access Protocol (IMAP) has been through several + revisions and variants in its 10-year history. Many of these are + either extinct or extremely rare; in particular, several undocumented + variants and the variants described in RFC 1064, RFC 1176, and RFC + 1203 fall into this category. + + One variant, IMAP2bis, is at the time of this writing very common and + has been widely distributed with the Pine mailer. Unfortunately, + there is no definite document describing IMAP2bis. This document is + intended to be read along with RFC 1176 and the most recent IMAP4 + specification (RFC 2060) to assist implementors in creating an IMAP4 + implementation to interoperate with implementations that conform to + earlier specifications. Nothing in this document is required by the + IMAP4 specification; implementors must decide for themselves whether + they want their implementation to fail if it encounters old software. + + At the time of this writing, IMAP4 has been updated from the version + described in RFC 1730. An implementor who wishes to interoperate + with both RFC 1730 and RFC 2060 should refer to both documents. + + This information is not complete; it reflects current knowledge of + server and client implementations as well as "folklore" acquired in + the evolution of the protocol. It is NOT a description of how to + interoperate with all variants of IMAP, but rather with the old + variant that is most likely to be encountered. For detailed + information on interoperating with other old variants, refer to RFC + 1732. + +IMAP4 client interoperability with IMAP2bis servers + + A quick way to check whether a server implementation supports the + IMAP4 specification is to try the CAPABILITY command. An OK response + will indicate which variant(s) of IMAP4 are supported by the server. + + + +Crispin Informational [Page 1] + +RFC 2061 IMAP4 Compatibility December 1996 + + + If the client does not find any of its known variant in the response, + it should treat the server as IMAP2bis. A BAD response indicates an + IMAP2bis or older server. + + Most IMAP4 facilities are in IMAP2bis. The following exceptions + exist: + + CAPABILITY command + The absense of this command indicates IMAP2bis (or older). + + AUTHENTICATE command. + Use the LOGIN command. + + LSUB, SUBSCRIBE, and UNSUBSCRIBE commands + No direct functional equivalent. IMAP2bis had a concept + called "bboards" which is not in IMAP4. RFC 1176 supported + these with the BBOARD and FIND BBOARDS commands. IMAP2bis + augmented these with the FIND ALL.BBOARDS, SUBSCRIBE BBOARD, + and UNSUBSCRIBE BBOARD commands. It is recommended that + none of these commands be implemented in new software, + including servers that support old clients. + + LIST command + Use the command FIND ALL.MAILBOXES, which has a similar syn- + tax and response to the FIND MAILBOXES command described in + RFC 1176. The FIND MAILBOXES command is unlikely to produce + useful information. + + * in a sequence + Use the number of messages in the mailbox from the EXISTS + unsolicited response. + + SEARCH extensions (character set, additional criteria) + Reformulate the search request using only the RFC 1176 syn- + tax. This may entail doing multiple searches to achieve the + desired results. + + BODYSTRUCTURE fetch data item + Use the non-extensible BODY data item. + + body sections HEADER, TEXT, MIME, HEADER.FIELDS, HEADER.FIELDS.NOT + Use body section numbers only. + + BODY.PEEK[section] + Use BODY[section] and manually clear the \Seen flag as + necessary. + + + + + +Crispin Informational [Page 2] + +RFC 2061 IMAP4 Compatibility December 1996 + + + FLAGS.SILENT, +FLAGS.SILENT, and -FLAGS.SILENT store data items + Use the corresponding non-SILENT versions and ignore the + untagged FETCH responses which come back. + + UID fetch data item and the UID commands + No functional equivalent. + + CLOSE command + No functional equivalent. + + + In IMAP2bis, the TRYCREATE special information token is sent as a + separate unsolicited OK response instead of inside the NO response. + + IMAP2bis is ambiguous about whether or not flags or internal dates + are preserved on COPY. It is impossible to know what behavior is + supported by the server. + +IMAP4 server interoperability with IMAP2bis clients + + The only interoperability problem between an IMAP4 server and a + well-written IMAP2bis client is an incompatibility with the use of + "\" in quoted strings. This is best avoided by using literals + instead of quoted strings if "\" or <"> is embedded in the string. + +Security Considerations + + Security issues are not discussed in this memo. + +Author's Address + + Mark R. Crispin + Networks and Distributed Computing + University of Washington + 4545 15th Aveneue NE + Seattle, WA 98105-4527 + + Phone: (206) 543-5762 + EMail: MRC@CAC.Washington.EDU + + + + + + + + + + + + +Crispin Informational [Page 3] + diff --git a/imap/docs/rfc/rfc2062.txt b/imap/docs/rfc/rfc2062.txt new file mode 100644 index 00000000..865d1dad --- /dev/null +++ b/imap/docs/rfc/rfc2062.txt @@ -0,0 +1,451 @@ + + + + + + +Network Working Group M. Crispin +Request for Comments: 2062 University of Washington +Category: Informational December 1996 + + + Internet Message Access Protocol - Obsolete Syntax + +Status of this Memo + + This memo provides information for the Internet community. This memo + does not specify an Internet standard of any kind. Distribution of + this memo is unlimited. + +Abstract + + This document describes obsolete syntax which may be encountered by + IMAP4 implementations which deal with older versions of the Internet + Mail Access Protocol. IMAP4 implementations MAY implement this + syntax in order to maximize interoperability with older + implementations. + + This document repeats information from earlier documents, most + notably RFC 1176 and RFC 1730. + +Obsolete Commands and Fetch Data Items + + The following commands are OBSOLETE. It is NOT required to support + any of these commands or fetch data items in new server + implementations. These commands are documented here for the benefit + of implementors who may wish to support them for compatibility with + old client implementations. + + The section headings of these commands are intended to correspond + with where they would be located in the main document if they were + not obsoleted. + +6.3.OBS.1. FIND ALL.MAILBOXES Command + + Arguments: mailbox name with possible wildcards + + Data: untagged responses: MAILBOX + + Result: OK - find completed + NO - find failure: can't list that name + BAD - command unknown or arguments invalid + + + + + + +Crispin Informational [Page 1] + +RFC 2062 IMAP4 Obsolete December 1996 + + + The FIND ALL.MAILBOXES command returns a subset of names from the + complete set of all names available to the user. It returns zero + or more untagged MAILBOX replies. The mailbox argument to FIND + ALL.MAILBOXES is similar to that for LIST with an empty reference, + except that the characters "%" and "?" match a single character. + + Example: C: A002 FIND ALL.MAILBOXES * + S: * MAILBOX blurdybloop + S: * MAILBOX INBOX + S: A002 OK FIND ALL.MAILBOXES completed + +6.3.OBS.2. FIND MAILBOXES Command + + Arguments: mailbox name with possible wildcards + + Data: untagged responses: MAILBOX + + Result: OK - find completed + NO - find failure: can't list that name + BAD - command unknown or arguments invalid + + The FIND MAILBOXES command returns a subset of names from the set + of names that the user has declared as being "active" or + "subscribed". It returns zero or more untagged MAILBOX replies. + The mailbox argument to FIND MAILBOXES is similar to that for LSUB + with an empty reference, except that the characters "%" and "?" + match a single character. + + Example: C: A002 FIND MAILBOXES * + S: * MAILBOX blurdybloop + S: * MAILBOX INBOX + S: A002 OK FIND MAILBOXES completed + +6.3.OBS.3. SUBSCRIBE MAILBOX Command + + Arguments: mailbox name + + Data: no specific data for this command + + Result: OK - subscribe completed + NO - subscribe failure: can't subscribe to that name + BAD - command unknown or arguments invalid + + The SUBSCRIBE MAILBOX command is identical in effect to the + SUBSCRIBE command. A server which implements this command must be + able to distinguish between a SUBSCRIBE MAILBOX command and a + SUBSCRIBE command with a mailbox name argument of "MAILBOX". + + + + +Crispin Informational [Page 2] + +RFC 2062 IMAP4 Obsolete December 1996 + + + Example: C: A002 SUBSCRIBE MAILBOX #news.comp.mail.mime + S: A002 OK SUBSCRIBE MAILBOX to #news.comp.mail.mime + completed + C: A003 SUBSCRIBE MAILBOX + S: A003 OK SUBSCRIBE to MAILBOX completed + + +6.3.OBS.4. UNSUBSCRIBE MAILBOX Command + + Arguments: mailbox name + + Data: no specific data for this command + + Result: OK - unsubscribe completed + NO - unsubscribe failure: can't unsubscribe that name + BAD - command unknown or arguments invalid + + The UNSUBSCRIBE MAILBOX command is identical in effect to the + UNSUBSCRIBE command. A server which implements this command must + be able to distinguish between a UNSUBSCRIBE MAILBOX command and + an UNSUBSCRIBE command with a mailbox name argument of "MAILBOX". + + Example: C: A002 UNSUBSCRIBE MAILBOX #news.comp.mail.mime + S: A002 OK UNSUBSCRIBE MAILBOX from #news.comp.mail.mime + completed + C: A003 UNSUBSCRIBE MAILBOX + S: A003 OK UNSUBSCRIBE from MAILBOX completed + +6.4.OBS.1 PARTIAL Command + + Arguments: message sequence number + message data item name + position of first octet + number of octets + + Data: untagged responses: FETCH + + Result: OK - partial completed + NO - partial error: can't fetch that data + BAD - command unknown or arguments invalid + + The PARTIAL command is equivalent to the associated FETCH command, + with the added functionality that only the specified number of + octets, beginning at the specified starting octet, are returned. + Only a single message can be fetched at a time. The first octet + of a message, and hence the minimum for the starting octet, is + octet 1. + + + + +Crispin Informational [Page 3] + +RFC 2062 IMAP4 Obsolete December 1996 + + + The following FETCH items are valid data for PARTIAL: RFC822, + RFC822.HEADER, RFC822.TEXT, BODY[<section>], as well as any .PEEK + forms of these. + + Any partial fetch that attempts to read beyond the end of the text + is truncated as appropriate. If the starting octet is beyond the + end of the text, an empty string is returned. + + The data are returned with the FETCH response. There is no + indication of the range of the partial data in this response. It + is not possible to stream multiple PARTIAL commands of the same + data item without processing and synchronizing at each step, since + streamed commands may be executed out of order. + + There is no requirement that partial fetches follow any sequence. + For example, if a partial fetch of octets 1 through 10000 breaks + in an awkward place for BASE64 decoding, it is permitted to + continue with a partial fetch of 9987 through 19987, etc. + + The handling of the \Seen flag is the same as in the associated + FETCH command. + + Example: C: A005 PARTIAL 4 RFC822 1 1024 + S: * 1 FETCH (RFC822 {1024} + S: Return-Path: <gray@cac.washington.edu> + S: ... + S: ......... FLAGS (\Seen)) + S: A005 OK PARTIAL completed + +6.4.5.OBS.1 Obsolete FETCH Data Items + + The following FETCH data items are obsolete: + + BODY[<...>0] A body part number of 0 is the [RFC-822] header of + the message. BODY[0] is functionally equivalent to + BODY[HEADER], differing in the syntax of the + resulting untagged FETCH data (BODY[0] is + returned). + + RFC822.HEADER.LINES <header_list> + Functionally equivalent to BODY.PEEK[HEADER.LINES + <header_list>], differing in the syntax of the + resulting untagged FETCH data (RFC822.HEADER is + returned). + + + + + + + +Crispin Informational [Page 4] + +RFC 2062 IMAP4 Obsolete December 1996 + + + RFC822.HEADER.LINES.NOT <header_list> + Functionally equivalent to + BODY.PEEK[HEADER.LINES.NOT <header_list>], + differing in the syntax of the resulting untagged + FETCH data (RFC822.HEADER is returned). + + RFC822.PEEK Functionally equivalent to BODY.PEEK[], except for + the syntax of the resulting untagged FETCH data + (RFC822 is returned). + + RFC822.TEXT.PEEK + Functionally equivalent to BODY.PEEK[TEXT], except + for the syntax of the resulting untagged FETCH data + (RFC822.TEXT is returned). + +Obsolete Responses + + The following responses are OBSOLETE. Except as noted below, these + responses MUST NOT be transmitted by new server implementations. + Client implementations SHOULD accept these responses. + + The section headings of these responses are intended to correspond + with where they would be located in the main document if they were + not obsoleted. + +7.2.OBS.1. MAILBOX Response + + Data: name + + The MAILBOX response MUST NOT be transmitted by server + implementations except in response to the obsolete FIND MAILBOXES + and FIND ALL.MAILBOXES commands. Client implementations that do + not use these commands MAY ignore this response. It is documented + here for the benefit of implementors who may wish to support it + for compatibility with old client implementations. + + This response occurs as a result of the FIND MAILBOXES and FIND + ALL.MAILBOXES commands. It returns a single name that matches the + FIND specification. There are no attributes or hierarchy + delimiter. + + Example: S: * MAILBOX blurdybloop + + + + + + + + + +Crispin Informational [Page 5] + +RFC 2062 IMAP4 Obsolete December 1996 + + +7.3.OBS.1. COPY Response + + Data: none + + The COPY response MUST NOT be transmitted by new server + implementations. Client implementations MUST ignore the COPY + response. It is documented here for the benefit of client + implementors who may encounter this response from old server + implementations. + + In some experimental versions of this protocol, this response was + returned in response to a COPY command to indicate on a + per-message basis that the message was copied successfully. + + Example: S: * 44 COPY + +7.3.OBS.2. STORE Response + + Data: message data + + The STORE response MUST NOT be transmitted by new server + implementations. Client implementations MUST treat the STORE + response as equivalent to the FETCH response. It is documented + here for the benefit of client implementors who may encounter this + response from old server implementations. + + In some experimental versions of this protocol, this response was + returned instead of FETCH in response to a STORE command to report + the new value of the flags. + + Example: S: * 69 STORE (FLAGS (\Deleted)) + +Formal Syntax of Obsolete Commands and Responses + + Each obsolete syntax rule that is suffixed with "_old" is added to + the corresponding name in the formal syntax. For example, + command_auth_old adds the FIND command to command_auth. + + command_auth_old ::= find + + command_select_old + ::= partial + + date_year_old ::= 2digit + ;; (year - 1900) + + date_time_old ::= <"> date_day_fixed "-" date_month "-" date_year + SPACE time "-" zone_name <"> + + + +Crispin Informational [Page 6] + +RFC 2062 IMAP4 Obsolete December 1996 + + + find ::= "FIND" SPACE ["ALL."] "MAILBOXES" SPACE + list_mailbox + + fetch_att_old ::= "RFC822.HEADER.LINES" [".NOT"] SPACE header_list / + fetch_text_old + + fetch_text_old ::= "BODY" [".PEEK"] section_old / + "RFC822" [".HEADER" / ".TEXT" [".PEEK"]] + + msg_data_old ::= "COPY" / ("STORE" SPACE msg_att) + + partial ::= "PARTIAL" SPACE nz_number SPACE fetch_text_old SPACE + number SPACE number + + section_old ::= "[" (number ["." number]) "]" + + subscribe_old ::= "SUBSCRIBE" SPACE "MAILBOX" SPACE mailbox + + unsubscribe_old ::= "UNSUBSCRIBE" SPACE "MAILBOX" SPACE mailbox + + zone_name ::= "UT" / "GMT" / "Z" / ;; +0000 + "AST" / "EDT" / ;; -0400 + "EST" / "CDT" / ;; -0500 + "CST" / "MDT" / ;; -0600 + "MST" / "PDT" / ;; -0700 + "PST" / "YDT" / ;; -0800 + "YST" / "HDT" / ;; -0900 + "HST" / "BDT" / ;; -1000 + "BST" / ;; -1100 + "A" / "B" / "C" / "D" / "E" / "F" / ;; +1 to +6 + "G" / "H" / "I" / "K" / "L" / "M" / ;; +7 to +12 + "N" / "O" / "P" / "Q" / "R" / "S" / ;; -1 to -6 + "T" / "U" / "V" / "W" / "X" / "Y" ;; -7 to -12 + +Security Considerations + + Security issues are not discussed in this memo. + + + + + + + + + + + + + + +Crispin Informational [Page 7] + +RFC 2062 IMAP4 Obsolete December 1996 + + +Author's Address + + Mark R. Crispin + Networks and Distributed Computing + University of Washington + 4545 15th Aveneue NE + Seattle, WA 98105-4527 + + Phone: (206) 543-5762 + EMail: MRC@CAC.Washington.EDU + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Crispin Informational [Page 8] + diff --git a/imap/docs/rfc/rfc2087.txt b/imap/docs/rfc/rfc2087.txt new file mode 100644 index 00000000..1db5b57b --- /dev/null +++ b/imap/docs/rfc/rfc2087.txt @@ -0,0 +1,283 @@ + + + + + + +Network Working Group J. Myers +Request for Comments: 2087 Carnegie Mellon +Category: Standards Track January 1997 + + + IMAP4 QUOTA extension + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +1. Abstract + + The QUOTA extension of the Internet Message Access Protocol [IMAP4] + permits administrative limits on resource usage (quotas) to be + manipulated through the IMAP protocol. + +Table of Contents + + 1. Abstract........................................... 1 + 2. Conventions Used in this Document.................. 1 + 3. Introduction and Overview.......................... 2 + 4. Commands........................................... 2 + 4.1. SETQUOTA Command................................... 2 + 4.2. GETQUOTA Command................................... 2 + 4.3. GETQUOTAROOT Command............................... 3 + 5. Responses.......................................... 3 + 5.1. QUOTA Response..................................... 3 + 5.2. QUOTAROOT Response................................. 4 + 6. Formal syntax...................................... 4 + 7. References......................................... 5 + 8. Security Considerations............................ 5 + 9. Author's Address................................... 5 + + +2. Conventions Used in this Document + + In examples, "C:" and "S:" indicate lines sent by the client and + server respectively. + + + + + + + + +Myers Standards Track [Page 1] + +RFC 2087 QUOTA January 1997 + + +3. Introduction and Overview + + The QUOTA extension is present in any IMAP4 implementation which + returns "QUOTA" as one of the supported capabilities to the + CAPABILITY command. + + An IMAP4 server which supports the QUOTA capability may support + limits on any number of resources. Each resource has an atom name + and an implementation-defined interpretation which evaluates to an + integer. Examples of such resources are: + + Name Interpretation + + STORAGE Sum of messages' RFC822.SIZE, in units of 1024 octets + MESSAGE Number of messages + + + Each mailbox has zero or more implementation-defined named "quota + roots". Each quota root has zero or more resource limits. All + mailboxes that share the same named quota root share the resource + limits of the quota root. + + Quota root names do not necessarily have to match the names of + existing mailboxes. + +4. Commands + +4.1. SETQUOTA Command + + Arguments: quota root + list of resource limits + + Data: untagged responses: QUOTA + + Result: OK - setquota completed + NO - setquota error: can't set that data + BAD - command unknown or arguments invalid + + The SETQUOTA command takes the name of a mailbox quota root and a + list of resource limits. The resource limits for the named quota root + are changed to be the specified limits. Any previous resource limits + for the named quota root are discarded. + + If the named quota root did not previously exist, an implementation + may optionally create it and change the quota roots for any number of + existing mailboxes in an implementation-defined manner. + + + + + +Myers Standards Track [Page 2] + +RFC 2087 QUOTA January 1997 + + + Example: C: A001 SETQUOTA "" (STORAGE 512) + S: * QUOTA "" (STORAGE 10 512) + S: A001 OK Setquota completed + +4.2. GETQUOTA Command + + Arguments: quota root + + Data: untagged responses: QUOTA + + Result: OK - getquota completed + NO - getquota error: no such quota root, permission + denied + BAD - command unknown or arguments invalid + + The GETQUOTA command takes the name of a quota root and returns the + quota root's resource usage and limits in an untagged QUOTA response. + + Example: C: A003 GETQUOTA "" + S: * QUOTA "" (STORAGE 10 512) + S: A003 OK Getquota completed + +4.3. GETQUOTAROOT Command + + Arguments: mailbox name + + Data: untagged responses: QUOTAROOT, QUOTA + + Result: OK - getquota completed + NO - getquota error: no such mailbox, permission denied + BAD - command unknown or arguments invalid + + The GETQUOTAROOT command takes the name of a mailbox and returns the + list of quota roots for the mailbox in an untagged QUOTAROOT + response. For each listed quota root, it also returns the quota + root's resource usage and limits in an untagged QUOTA response. + + Example: C: A003 GETQUOTAROOT INBOX + S: * QUOTAROOT INBOX "" + S: * QUOTA "" (STORAGE 10 512) + S: A003 OK Getquota completed + + + + + + + + + + +Myers Standards Track [Page 3] + +RFC 2087 QUOTA January 1997 + + +5. Responses + +5.1. QUOTA Response + + Data: quota root name + list of resource names, usages, and limits + + This response occurs as a result of a GETQUOTA or GETQUOTAROOT + command. The first string is the name of the quota root for which + this quota applies. + + The name is followed by a S-expression format list of the resource + usage and limits of the quota root. The list contains zero or + more triplets. Each triplet conatins a resource name, the current + usage of the resource, and the resource limit. + + Resources not named in the list are not limited in the quota root. + Thus, an empty list means there are no administrative resource + limits in the quota root. + + Example: S: * QUOTA "" (STORAGE 10 512) + +5.2. QUOTAROOT Response + + Data: mailbox name + zero or more quota root names + + This response occurs as a result of a GETQUOTAROOT command. The + first string is the mailbox and the remaining strings are the + names of the quota roots for the mailbox. + + Example: S: * QUOTAROOT INBOX "" + S: * QUOTAROOT comp.mail.mime + +6. Formal syntax + + The following syntax specification uses the augmented Backus-Naur + Form (BNF) notation as specified in RFC 822 with one exception; the + delimiter used with the "#" construct is a single space (SP) and not + one or more commas. + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of upper or lower case characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. + + + + + + +Myers Standards Track [Page 4] + +RFC 2087 QUOTA January 1997 + + + getquota ::= "GETQUOTA" SP astring + + getquotaroot ::= "GETQUOTAROOT" SP astring + + quota_list ::= "(" #quota_resource ")" + + quota_resource ::= atom SP number SP number + + quota_response ::= "QUOTA" SP astring SP quota_list + + quotaroot_response + ::= "QUOTAROOT" SP astring *(SP astring) + + setquota ::= "SETQUOTA" SP astring SP setquota_list + + setquota_list ::= "(" 0#setquota_resource ")" + + setquota_resource ::= atom SP number + +7. References + + [IMAP4] Crispin, M., "Internet Message Access Protocol - Version 4", + RFC 1730, University of Washington, December 1994. + + [RFC-822] Crocker, D., "Standard for the Format of ARPA Internet + Text Messages", STD 11, RFC 822. + +8. Security Considerations + + Implementors should be careful to make sure the implementation of + these commands does not violate the site's security policy. The + resource usage of other users is likely to be considered confidential + information and should not be divulged to unauthorized persons. + +9. Author's Address + + John G. Myers + Carnegie-Mellon University + 5000 Forbes Ave. + Pittsburgh PA, 15213-3890 + + EMail: jgm+@cmu.edu + + + + + + + + + +Myers Standards Track [Page 5] + diff --git a/imap/docs/rfc/rfc2088.txt b/imap/docs/rfc/rfc2088.txt new file mode 100644 index 00000000..f36cc764 --- /dev/null +++ b/imap/docs/rfc/rfc2088.txt @@ -0,0 +1,115 @@ + + + + + + +Network Working Group J. Myers +Request for Comments: 2088 Carnegie Mellon +Cateogry: Standards Track January 1997 + + + IMAP4 non-synchronizing literals + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +1. Abstract + + The Internet Message Access Protocol [IMAP4] contains the "literal" + syntactic construct for communicating strings. When sending a + literal from client to server, IMAP4 requires the client to wait for + the server to send a command continuation request between sending the + octet count and the string data. This document specifies an + alternate form of literal which does not require this network round + trip. + +2. Conventions Used in this Document + + In examples, "C:" and "S:" indicate lines sent by the client and + server respectively. + +3. Specification + + The non-synchronizing literal is added an alternate form of literal, + and may appear in communication from client to server instead of the + IMAP4 form of literal. The IMAP4 form of literal, used in + communication from client to server, is referred to as a + synchronizing literal. + + Non-synchronizing literals may be used with any IMAP4 server + implementation which returns "LITERAL+" as one of the supported + capabilities to the CAPABILITY command. If the server does not + advertise the LITERAL+ capability, the client must use synchronizing + literals instead. + + The non-synchronizing literal is distinguished from the original + synchronizing literal by having a plus ('+') between the octet count + and the closing brace ('}'). The server does not generate a command + continuation request in response to a non-synchronizing literal, and + + + +Myers Standards Track [Page 1] + +RFC 2088 LITERAL January 1997 + + + clients are not required to wait before sending the octets of a non- + synchronizing literal. + + The protocol receiver of an IMAP4 server must check the end of every + received line for an open brace ('{') followed by an octet count, a + plus ('+'), and a close brace ('}') immediately preceeding the CRLF. + If it finds this sequence, it is the octet count of a non- + synchronizing literal and the server MUST treat the specified number + of following octets and the following line as part of the same + command. A server MAY still process commands and reject errors on a + line-by-line basis, as long as it checks for non-synchronizing + literals at the end of each line. + + Example: C: A001 LOGIN {11+} + C: FRED FOOBAR {7+} + C: fat man + S: A001 OK LOGIN completed + +4. Formal Syntax + + The following syntax specification uses the augmented Backus-Naur + Form (BNF) notation as specified in [RFC-822] as modified by [IMAP4]. + Non-terminals referenced but not defined below are as defined by + [IMAP4]. + + literal ::= "{" number ["+"] "}" CRLF *CHAR8 + ;; Number represents the number of CHAR8 octets + +6. References + + [IMAP4] Crispin, M., "Internet Message Access Protocol - Version 4", + draft-crispin-imap-base-XX.txt, University of Washington, April 1996. + + [RFC-822] Crocker, D., "Standard for the Format of ARPA Internet Text + Messages", STD 11, RFC 822. + +7. Security Considerations + + There are no known security issues with this extension. + +8. Author's Address + + John G. Myers + Carnegie-Mellon University + 5000 Forbes Ave. + Pittsburgh PA, 15213-3890 + + Email: jgm+@cmu.edu + + + +Myers Standards Track [Page 2] + diff --git a/imap/docs/rfc/rfc2177.txt b/imap/docs/rfc/rfc2177.txt new file mode 100644 index 00000000..c11c7654 --- /dev/null +++ b/imap/docs/rfc/rfc2177.txt @@ -0,0 +1,227 @@ + + + + + + +Network Working Group B. Leiba +Request for Comments: 2177 IBM T.J. Watson Research Center +Category: Standards Track June 1997 + + + IMAP4 IDLE command + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +1. Abstract + + The Internet Message Access Protocol [IMAP4] requires a client to + poll the server for changes to the selected mailbox (new mail, + deletions). It's often more desirable to have the server transmit + updates to the client in real time. This allows a user to see new + mail immediately. It also helps some real-time applications based on + IMAP, which might otherwise need to poll extremely often (such as + every few seconds). (While the spec actually does allow a server to + push EXISTS responses aysynchronously, a client can't expect this + behaviour and must poll.) + + This document specifies the syntax of an IDLE command, which will + allow a client to tell the server that it's ready to accept such + real-time updates. + +2. Conventions Used in this Document + + In examples, "C:" and "S:" indicate lines sent by the client and + server respectively. + + The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" + in this document are to be interpreted as described in RFC 2060 + [IMAP4]. + +3. Specification + + IDLE Command + + Arguments: none + + Responses: continuation data will be requested; the client sends + the continuation data "DONE" to end the command + + + +Leiba Standards Track [Page 1] + +RFC 2177 IMAP4 IDLE command June 1997 + + + + Result: OK - IDLE completed after client sent "DONE" + NO - failure: the server will not allow the IDLE + command at this time + BAD - command unknown or arguments invalid + + The IDLE command may be used with any IMAP4 server implementation + that returns "IDLE" as one of the supported capabilities to the + CAPABILITY command. If the server does not advertise the IDLE + capability, the client MUST NOT use the IDLE command and must poll + for mailbox updates. In particular, the client MUST continue to be + able to accept unsolicited untagged responses to ANY command, as + specified in the base IMAP specification. + + The IDLE command is sent from the client to the server when the + client is ready to accept unsolicited mailbox update messages. The + server requests a response to the IDLE command using the continuation + ("+") response. The IDLE command remains active until the client + responds to the continuation, and as long as an IDLE command is + active, the server is now free to send untagged EXISTS, EXPUNGE, and + other messages at any time. + + The IDLE command is terminated by the receipt of a "DONE" + continuation from the client; such response satisfies the server's + continuation request. At that point, the server MAY send any + remaining queued untagged responses and then MUST immediately send + the tagged response to the IDLE command and prepare to process other + commands. As in the base specification, the processing of any new + command may cause the sending of unsolicited untagged responses, + subject to the ambiguity limitations. The client MUST NOT send a + command while the server is waiting for the DONE, since the server + will not be able to distinguish a command from a continuation. + + The server MAY consider a client inactive if it has an IDLE command + running, and if such a server has an inactivity timeout it MAY log + the client off implicitly at the end of its timeout period. Because + of that, clients using IDLE are advised to terminate the IDLE and + re-issue it at least every 29 minutes to avoid being logged off. + This still allows a client to receive immediate mailbox updates even + though it need only "poll" at half hour intervals. + + + + + + + + + + + +Leiba Standards Track [Page 2] + +RFC 2177 IMAP4 IDLE command June 1997 + + + Example: C: A001 SELECT INBOX + S: * FLAGS (Deleted Seen) + S: * 3 EXISTS + S: * 0 RECENT + S: * OK [UIDVALIDITY 1] + S: A001 OK SELECT completed + C: A002 IDLE + S: + idling + ...time passes; new mail arrives... + S: * 4 EXISTS + C: DONE + S: A002 OK IDLE terminated + ...another client expunges message 2 now... + C: A003 FETCH 4 ALL + S: * 4 FETCH (...) + S: A003 OK FETCH completed + C: A004 IDLE + S: * 2 EXPUNGE + S: * 3 EXISTS + S: + idling + ...time passes; another client expunges message 3... + S: * 3 EXPUNGE + S: * 2 EXISTS + ...time passes; new mail arrives... + S: * 3 EXISTS + C: DONE + S: A004 OK IDLE terminated + C: A005 FETCH 3 ALL + S: * 3 FETCH (...) + S: A005 OK FETCH completed + C: A006 IDLE + +4. Formal Syntax + + The following syntax specification uses the augmented Backus-Naur + Form (BNF) notation as specified in [RFC-822] as modified by [IMAP4]. + Non-terminals referenced but not defined below are as defined by + [IMAP4]. + + command_auth ::= append / create / delete / examine / list / lsub / + rename / select / status / subscribe / unsubscribe + / idle + ;; Valid only in Authenticated or Selected state + + idle ::= "IDLE" CRLF "DONE" + + + + + + +Leiba Standards Track [Page 3] + +RFC 2177 IMAP4 IDLE command June 1997 + + +5. References + + [IMAP4] Crispin, M., "Internet Message Access Protocol - Version + 4rev1", RFC 2060, December 1996. + +6. Security Considerations + + There are no known security issues with this extension. + +7. Author's Address + + Barry Leiba + IBM T.J. Watson Research Center + 30 Saw Mill River Road + Hawthorne, NY 10532 + + Email: leiba@watson.ibm.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Leiba Standards Track [Page 4] + diff --git a/imap/docs/rfc/rfc2180.txt b/imap/docs/rfc/rfc2180.txt new file mode 100644 index 00000000..57607002 --- /dev/null +++ b/imap/docs/rfc/rfc2180.txt @@ -0,0 +1,787 @@ + + + + + + +Network Working Group M. Gahrns +Request for Comments: 2180 Microsoft +Category: Informational July 1997 + + + IMAP4 Multi-Accessed Mailbox Practice + +Status of this Memo + + This memo provides information for the Internet community. This memo + does not specify an Internet standard of any kind. Distribution of + this memo is unlimited. + +1. Abstract + + IMAP4[RFC-2060] is rich client/server protocol that allows a client + to access and manipulate electronic mail messages on a server. + Within the protocol framework, it is possible to have differing + results for particular client/server interactions. If a protocol does + not allow for this, it is often unduly restrictive. + + For example, when multiple clients are accessing a mailbox and one + attempts to delete the mailbox, an IMAP4 server may choose to + implement a solution based upon server architectural constraints or + individual preference. + + With this flexibility comes greater client responsibility. It is not + sufficient for a client to be written based upon the behavior of a + particular IMAP server. Rather the client must be based upon the + behavior allowed by the protocol. + + By documenting common IMAP4 server practice for the case of + simultaneous client access to a mailbox, we hope to ensure the widest + amount of inter-operation between IMAP4 clients and servers. + + The behavior described in this document reflects the practice of some + existing servers or behavior that the consensus of the IMAP mailing + list has deemed to be reasonable. The behavior described within this + document is believed to be [RFC-2060] compliant. However, this + document is not meant to define IMAP4 compliance, nor is it an + exhaustive list of valid IMAP4 behavior. [RFC-2060] must always be + consulted to determine IMAP4 compliance, especially for server + behavior not described within this document. + + + + + + + + +Gahrns Informational [Page 1] + +RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 + + +2. Conventions used in this document + + In examples,"C1:", "C2:" and "C3:" indicate lines sent by 3 different + clients (client #1, client #2 and client #3) that are connected to a + server. "S1:", "S2:" and "S3:" indicated lines sent by the server to + client #1, client #2 and client #3 respectively. + + A shared mailbox, is a mailbox that can be used by multiple users. + + A multi-accessed mailbox, is a mailbox that has multiple clients + simultaneously accessing it. + + A client is said to have accessed a mailbox after a successful SELECT + or EXAMINE command. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC-2119]. + + +3. Deletion/Renaming of a multi-accessed mailbox + + If an external agent or multiple clients are accessing a mailbox, + care must be taken when handling the deletion or renaming of the + mailbox. Following are some strategies an IMAP server may choose to + use when dealing with this situation. + + +3.1. The server MAY fail the DELETE/RENAME command of a multi-accessed + mailbox + + In some cases, this behavior may not be practical. For example, if a + large number of clients are accessing a shared mailbox, the window in + which no clients have the mailbox accessed may be small or non- + existent, effectively rendering the mailbox undeletable or + unrenamable. + + Example: + + <Client #1 and Client #2 have mailbox FOO accessed. Client #1 tries + to DELETE the mailbox and is refused> + + C1: A001 DELETE FOO + S1: A001 NO Mailbox FOO is in use by another user. + + + + + + + +Gahrns Informational [Page 2] + +RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 + + +3.2. The server MAY allow the DELETE command of a multi-accessed + mailbox, but keep the information in the mailbox available for + those clients that currently have access to the mailbox. + + When all clients have finished accessing the mailbox, it is + permanently removed. For clients that do not already have access to + the mailbox, the 'ghosted' mailbox would not be available. For + example, it would not be returned to these clients in a subsequent + LIST or LSUB command and would not be a valid mailbox argument to any + other IMAP command until the reference count of clients accessing the + mailbox reached 0. + + In some cases, this behavior may not be desirable. For example if + someone created a mailbox with offensive or sensitive information, + one might prefer to have the mailbox deleted and all access to the + information contained within removed immediately, rather than + continuing to allow access until the client closes the mailbox. + + Furthermore, this behavior, may prevent 'recycling' of the same + mailbox name until all clients have finished accessing the original + mailbox. + + Example: + + <Client #1 and Client #2 have mailbox FOO selected. Client #1 DELETEs + mailbox FOO> + + C1: A001 DELETE FOO + S1: A001 OK Mailbox FOO is deleted. + + <Client #2 is still able to operate on the deleted mailbox> + + C2: B001 STORE 1 +FLAGS (\Seen) + S2: * 1 FETCH FLAGS (\Seen) + S2: B001 OK STORE completed + + <Client #3 which did not have access to the mailbox prior to the + deletion by client #1 does not have access to the mailbox> + + C3: C001 STATUS FOO (MESSAGES) + S3: C001 NO Mailbox does not exist + + <Nor is client #3 able to create a mailbox with the name FOO, while + the reference count is non zero> + + C3: C002 CREATE FOO + S3: C002 NO Mailbox FOO is still in use. Try again later. + + + + +Gahrns Informational [Page 3] + +RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 + + + <Client #2 closes its access to the mailbox, no other clients have + access to the mailbox FOO and reference count becomes 0> + + C2: B002 CLOSE + S2: B002 OK CLOSE Completed + + <Now that the reference count on FOO has reached 0, the mailbox name + can be recycled> + + C3: C003 CREATE FOO + S3: C003 OK CREATE Completed + + +3.3. The server MAY allow the DELETE/RENAME of a multi-accessed + mailbox, but disconnect all other clients who have the mailbox + accessed by sending a untagged BYE response. + + A server may often choose to disconnect clients in the DELETE case, + but may choose to implement a "friendlier" method for the RENAME + case. + + Example: + + <Client #1 and Client #2 have mailbox FOO accessed. Client #1 DELETEs + the mailbox FOO> + + C1: A002 DELETE FOO + S1: A002 OK DELETE completed. + + <Server disconnects all other users of the mailbox> + S2: * BYE Mailbox FOO has been deleted. + + +3.4. The server MAY allow the RENAME of a multi-accessed mailbox by + simply changing the name attribute on the mailbox. + + Other clients that have access to the mailbox can continue issuing + commands such as FETCH that do not reference the mailbox name. + Clients would discover the renaming the next time they referred to + the old mailbox name. Some servers MAY choose to include the + [NEWNAME] response code in their tagged NO response to a command that + contained the old mailbox name, as a hint to the client that the + operation can succeed if the command is issued with the new mailbox + name. + + + + + + + +Gahrns Informational [Page 4] + +RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 + + + Example: + + <Client #1 and Client #2 have mailbox FOO accessed. Client #1 RENAMEs + the mailbox.> + + C1: A001 RENAME FOO BAR + S1: A001 OK RENAME completed. + + <Client #2 is still able to do operations that do not reference the + mailbox name> + + C2: B001 FETCH 2:4 (FLAGS) + S2: * 2 FETCH . . . + S2: * 3 FETCH . . . + S2: * 4 FETCH . . . + S2: B001 OK FETCH completed + + <Client #2 is not able to do operations that reference the mailbox + name> + + C2: B002 APPEND FOO {300} C2: Date: Mon, 7 Feb 1994 + 21:52:25 0800 (PST) C2: . . . S2: B002 NO [NEWNAME FOO + BAR] Mailbox has been renamed + + +4. Expunging of messages on a multi-accessed mailbox + + If an external agent or multiple clients are accessing a mailbox, + care must be taken when handling the EXPUNGE of messages. Other + clients accessing the mailbox may be in the midst of issuing a + command that depends upon message sequence numbers. Because an + EXPUNGE response can not be sent while responding to a FETCH, STORE + or SEARCH command, it is not possible to immediately notify the + client of the EXPUNGE. This can result in ambiguity if the client + issues a FETCH, STORE or SEARCH operation on a message that has been + EXPUNGED. + + +4.1. Fetching of expunged messages + + Following are some strategies an IMAP server may choose to use when + dealing with a FETCH command on expunged messages. + + + + + + + + + +Gahrns Informational [Page 5] + +RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 + + + Consider the following scenario: + + - Client #1 and Client #2 have mailbox FOO selected. + - There are 7 messages in the mailbox. + - Messages 4:7 are marked for deletion. + - Client #1 issues an EXPUNGE, to expunge messages 4:7 + + +4.1.1. The server MAY allow the EXPUNGE of a multi-accessed mailbox but + keep the messages available to satisfy subsequent FETCH commands + until it is able to send an EXPUNGE response to each client. + + In some cases, the behavior of keeping "ghosted" messages may not be + desirable. For example if a message contained offensive or sensitive + information, one might prefer to instantaneously remove all access to + the information, regardless of whether another client is in the midst + of accessing it. + + Example: (Building upon the scenario outlined in 4.1.) + + <Client #2 is still able to access the expunged messages because the + server has kept a 'ghosted' copy of the messages until it is able to + notify client #2 of the EXPUNGE> + + C2: B001 FETCH 4:7 RFC822 + S2: * 4 FETCH RFC822 . . . (RFC822 info returned) + S2: * 5 FETCH RFC822 . . . (RFC822 info returned) + S2: * 6 FETCH RFC822 . . . (RFC822 info returned) + S2: * 7 FETCH RFC822 . . . (RFC822 info returned) + S2: B001 OK FETCH Completed + + <Client #2 issues a command where it can get notified of the EXPUNGE> + + C2: B002 NOOP + S2: * 4 EXPUNGE + S2: * 4 EXPUNGE + S2: * 4 EXPUNGE + S2: * 4 EXPUNGE + S2: * 3 EXISTS + S2: B002 OK NOOP Complete + + <Client #2 no longer has access to the expunged messages> + + C2: B003 FETCH 4:7 RFC822 + S2: B003 NO Messages 4:7 are no longer available. + + + + + + +Gahrns Informational [Page 6] + +RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 + + +4.1.2 The server MAY allow the EXPUNGE of a multi-accessed mailbox, + and on subsequent FETCH commands return FETCH responses only for + non-expunged messages and a tagged NO. + + After receiving a tagged NO FETCH response, the client SHOULD issue a + NOOP command so that it will be informed of any pending EXPUNGE + responses. The client may then either reissue the failed FETCH + command, or by examining the EXPUNGE response from the NOOP and the + FETCH response from the FETCH, determine that the FETCH failed + because of pending expunges. + + Example: (Building upon the scenario outlined in 4.1.) + + <Client #2 attempts to FETCH a mix of expunged and non-expunged + messages. A FETCH response is returned only for then non-expunged + messages along with a tagged NO> + + C2: B001 FETCH 3:5 ENVELOPE + S2: * 3 FETCH ENVELOPE . . . (ENVELOPE info returned) + S2: B001 NO Some of the requested messages no longer exist + + <Upon receiving a tagged NO FETCH response, Client #2 issues a NOOP + to be informed of any pending EXPUNGE responses> + + C2: B002 NOOP + S2: * 4 EXPUNGE + S2: * 4 EXPUNGE + S2: * 4 EXPUNGE + S2: * 4 EXPUNGE + S2: * 3 EXISTS + S2: B002 OK NOOP Completed. + + <By receiving a FETCH response for message 3, and an EXPUNGE response + that indicates messages 4:7 have been expunged, the client does not + need to re-issue the FETCH> + + + + + + + + + + + + + + + + +Gahrns Informational [Page 7] + +RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 + + +4.1.3 The server MAY allow the EXPUNGE of a multi-accessed mailbox, and + on subsequent FETCH commands return the usual FETCH responses for + non-expunged messages, "NIL FETCH Responses" for expunged + messages, and a tagged OK response. + + If all of the messages in the subsequent FETCH command have been + expunged, the server SHOULD return only a tagged NO. In this case, + the client SHOULD issue a NOOP command so that it will be informed of + any pending EXPUNGE responses. The client may then either reissue + the failed FETCH command, or by examining the EXPUNGE response from + the NOOP, determine that the FETCH failed because of pending + expunges. + + "NIL FETCH responses" are a representation of empty data as + appropriate for the FETCH argument specified. + + Example: + + * 1 FETCH (ENVELOPE (NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL)) + * 1 FETCH (FLAGS ()) + * 1 FETCH (INTERNALDATE "00-Jan-0000 00:00:00 +0000") + * 1 FETCH (RFC822 "") + * 1 FETCH (RFC822.HEADER "") + * 1 FETCH (RFC822.TEXT "") + * 1 FETCH (RFC822.SIZE 0) + * 1 FETCH (BODY ("TEXT" "PLAIN" NIL NIL NIL "7BIT" 0 0) + * 1 FETCH (BODYSTRUCTURE ("TEXT" "PLAIN" NIL NIL NIL "7BIT" 0 0) + * 1 FETCH (BODY[<section>] "") + * 1 FETCH (BODY[<section>]<partial> "") + + In some cases, a client may not be able to distinguish between "NIL + FETCH responses" received because a message was expunged and those + received because the data actually was NIL. For example, a * 5 + FETCH (FLAGS ()) response could be received if no flags were set on + message 5, or because message 5 was expunged. In a case of potential + ambiguity, the client SHOULD issue a command such as NOOP to force + the sending of the EXPUNGE responses to resolve any ambiguity. + + Example: (Building upon the scenario outlined in 4.1.) + + <Client #2 attempts to access a mix of expunged and non-expunged + messages. Normal data is returned for non-expunged message, "NIL + FETCH responses" are returned for expunged messages> + + + + + + + + +Gahrns Informational [Page 8] + +RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 + + + C2: B002 FETCH 3:5 ENVELOPE + S2: * 3 FETCH ENVELOPE . . . (ENVELOPE info returned) + S2: * 4 FETCH ENVELOPE (NIL NIL NIL NIL NIL NIL NIL NIL + NIL NIL) + S2: * 5 FETCH ENVELOPE (NIL NIL NIL NIL NIL NIL NIL NIL + NIL NIL) + S2: B002 OK FETCH Completed + + <Client #2 attempts to FETCH only expunged messages and receives a + tagged NO response> + + C2: B002 FETCH 4:7 ENVELOPE + S2: B002 NO Messages 4:7 have been expunged. + + +4.1.4 To avoid the situation altogether, the server MAY fail the + EXPUNGE of a multi-accessed mailbox + + In some cases, this behavior may not be practical. For example, if a + large number of clients are accessing a shared mailbox, the window in + which no clients have the mailbox accessed may be small or non- + existent, effectively rendering the message unexpungeable. + + +4.2. Storing of expunged messages + + Following are some strategies an IMAP server may choose to use when + dealing with a STORE command on expunged messages. + + +4.2.1 If the ".SILENT" suffix is used, and the STORE completed + successfully for all the non-expunged messages, the server SHOULD + return a tagged OK. + + Example: (Building upon the scenario outlined in 4.1.) + + <Client #2 tries to silently STORE flags on expunged and non- + expunged messages. The server sets the flags on the non-expunged + messages and returns OK> + + C2: B001 STORE 1:7 +FLAGS.SILENT (\SEEN) + S2: B001 OK + + + + + + + + + +Gahrns Informational [Page 9] + +RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 + + +4.2.2. If the ".SILENT" suffix is not used, and only expunged messages + are referenced, the server SHOULD return only a tagged NO. + + Example: (Building upon the scenario outlined in 4.1.) + + <Client #2 tries to STORE flags only on expunged messages> + + C2: B001 STORE 5:7 +FLAGS (\SEEN) + S2: B001 NO Messages have been expunged + + +4.2.3. If the ".SILENT" suffix is not used, and a mixture of expunged + and non-expunged messages are referenced, the server MAY set the + flags and return a FETCH response for the non-expunged messages + along with a tagged NO. + + After receiving a tagged NO STORE response, the client SHOULD issue a + NOOP command so that it will be informed of any pending EXPUNGE + responses. The client may then either reissue the failed STORE + command, or by examining the EXPUNGE responses from the NOOP and + FETCH responses from the STORE, determine that the STORE failed + because of pending expunges. + + Example: (Building upon the scenario outlined in 4.1.) + + <Client #2 tries to STORE flags on a mixture of expunged and non- + expunged messages> + + C2: B001 STORE 1:7 +FLAGS (\SEEN) + S2: * FETCH 1 FLAGS (\SEEN) + S2: * FETCH 2 FLAGS (\SEEN) + S2: * FETCH 3 FLAGS (\SEEN) + S2: B001 NO Some of the messages no longer exist. + + C2: B002 NOOP + S2: * 4 EXPUNGE + S2: * 4 EXPUNGE + S2: * 4 EXPUNGE + S2: * 4 EXPUNGE + S2: * 3 EXISTS + S2: B002 OK NOOP Completed. + + <By receiving FETCH responses for messages 1:3, and an EXPUNGE + response that indicates messages 4:7 have been expunged, the client + does not need to re-issue the STORE> + + + + + + +Gahrns Informational [Page 10] + +RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 + + +4.2.4. If the ".SILENT" suffix is not used, and a mixture of expunged + and non-expunged messages are referenced, the server MAY return + an untagged NO and not set any flags. + + After receiving a tagged NO STORE response, the client SHOULD issue a + NOOP command so that it will be informed of any pending EXPUNGE + responses. The client would then re-issue the STORE command after + updating its message list per any EXPUNGE response. + + If a large number of clients are accessing a shared mailbox, the + window in which there are no pending expunges may be small or non- + existent, effectively disallowing a client from setting the flags on + all messages at once. + + Example: (Building upon the scenario outlined in 4.1.) + + <Client #2 tries to STORE flags on a mixture of expunged and non- + expunged messages> + + C2: B001 STORE 1:7 +FLAGS (\SEEN) + S2: B001 NO Some of the messages no longer exist. + + <Client #2 issues a NOOP to be informed of the EXPUNGED messages> + + C2: B002 NOOP + S2: * 4 EXPUNGE + S2: * 4 EXPUNGE + S2: * 4 EXPUNGE + S2: * 4 EXPUNGE + S2: * 3 EXISTS + S2: B002 OK NOOP Completed. + + <Client #2 updates its message list and re-issues the STORE on only + those messages that have not been expunged> + + C2: B003 STORE 1:3 +FLAGS (\SEEN) S2: * FETCH 1 FLAGS + (\SEEN) S2: * FETCH 2 FLAGS (\SEEN) S2: * FETCH 3 FLAGS + (\SEEN) S2: B003 OK STORE Completed + + +4.3. Searching of expunged messages + + A server MAY simply not return a search response for messages that + have been expunged and it has not been able to inform the client + about. If a client was expecting a particular message to be returned + in a search result, and it was not, the client SHOULD issue a NOOP + command to see if the message was expunged by another client. + + + + +Gahrns Informational [Page 11] + +RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 + + +4.4 Copying of expunged messages + + COPY is the only IMAP4 sequence number command that is safe to allow + an EXPUNGE response on. This is because a client is not permitted to + cascade several COPY commands together. A client is required to wait + and confirm that the copy worked before issuing another one. + +4.4.1 The server MAY disallow the COPY of messages in a multi-access + mailbox that contains expunged messages. + + Pending EXPUNGE response(s) MUST be returned to the COPY command. + + Example: + + C: A001 COPY 2,4,6,8 FRED + S: * 4 EXPUNGE + S: A001 NO COPY rejected, because some of the requested + messages were expunged + + Note: Non of the above messages are copied because if a COPY command + is unsuccessful, the server MUST restore the destination mailbox to + its state before the COPY attempt. + + +4.4.2 The server MAY allow the COPY of messages in a multi-access + mailbox that contains expunged messages. + + Pending EXPUNGE response(s) MUST be returned to the COPY command. + Messages that are copied are messages corresponding to sequence + numbers before any EXPUNGE response. + + Example: + + C: A001 COPY 2,4,6,8 FRED + S: * 3 EXPUNGE + S: A001 OK COPY completed + + In the above example, the messages that are copied to FRED are + messages 2,4,6,8 at the start of the COPY command. These are + equivalent to messages 2,3,5,7 at the end of the COPY command. The + EXPUNGE response can't take place until after the messages from the + COPY command are identified (because of the "no expunge while no + commands in progress" rule). + + + + + + + + +Gahrns Informational [Page 12] + +RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 + + + Example: + + C: A001 COPY 2,4,6,8 FRED + S: * 4 EXPUNGE + S: A001 OK COPY completed + + In the above example, message 4 was copied before it was expunged, + and MUST appear in the destination mailbox FRED. + + +5. Security Considerations + + This document describes behavior of servers that use the IMAP4 + protocol, and as such, has the same security considerations as + described in [RFC-2060]. + + In particular, some described server behavior does not allow for the + immediate deletion of information when a mailbox is accessed by + multiple clients. This may be a consideration when dealing with + sensitive information where immediate deletion would be preferred. + + +6. References + + [RFC-2060], Crispin, M., "Internet Message Access Protocol - Version + 4rev1", RFC 2060, University of Washington, December 1996. + + [RFC-2119], Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", RFC 2119, Harvard University, March 1997. + + +7. Acknowledgments + + This document is the result of discussions on the IMAP4 mailing list + and is meant to reflect consensus of this group. In particular, + Raymond Cheng, Mark Crispin, Jim Evans, Erik Forsberg, Steve Hole, + Mark Keasling, Barry Leiba, Syd Logan, John Mani, Pat Moran, Larry + Osterman, Chris Newman, Bart Schaefer, Vladimir Vulovic, and Jack De + Winter were active participants in this discussion or made + suggestions to this document. + + + + + + + + + + + +Gahrns Informational [Page 13] + +RFC 2180 IMAP4 Multi-Accessed Mailbox Practice July 1997 + + +8. Author's Address + + Mike Gahrns + Microsoft + One Microsoft Way + Redmond, WA, 98072 + + Phone: (206) 936-9833 + EMail: mikega@microsoft.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Gahrns Informational [Page 14] + diff --git a/imap/docs/rfc/rfc2193.txt b/imap/docs/rfc/rfc2193.txt new file mode 100644 index 00000000..2fec58d7 --- /dev/null +++ b/imap/docs/rfc/rfc2193.txt @@ -0,0 +1,507 @@ + + + + + + +Network Working Group M. Gahrns +Request for Comments: 2193 Microsoft +Category: Standards Track September 1997 + + + IMAP4 Mailbox Referrals + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +1. Abstract + + When dealing with large amounts of users, messages and geographically + dispersed IMAP4 [RFC-2060] servers, it is often desirable to + distribute messages amongst different servers within an organization. + For example an administrator may choose to store user's personal + mailboxes on a local IMAP4 server, while storing shared mailboxes + remotely on another server. This type of configuration is common + when it is uneconomical to store all data centrally due to limited + bandwidth or disk resources. + + Mailbox referrals allow clients to seamlessly access mailboxes that + are distributed across several IMAP4 servers. + + A referral mechanism can provide efficiencies over the alternative + "proxy method", in which the local IMAP4 server contacts the remote + server on behalf of the client, and then transfers the data from the + remote server to itself, and then on to the client. The referral + mechanism's direct client connection to the remote server is often a + more efficient use of bandwidth, and does not require the local + server to impersonate the client when authenticating to the remote + server. + +2. Conventions used in this document + + In examples, "C:" and "S:" indicate lines sent by the client and + server respectively. + + A home server, is an IMAP4 server that contains the user's inbox. + + A remote mailbox is a mailbox that is not hosted on the user's home + server. + + + + +Gahrns Standards Track [Page 1] + +RFC 2193 IMAP4 Mailbox Referrals September 1997 + + + A remote server is a server that contains remote mailboxes. + + A shared mailbox, is a mailbox that multiple users have access to. + + An IMAP mailbox referral is when the server directs the client to + another IMAP mailbox. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC-2119]. + +3. Introduction and Overview + + IMAP4 servers that support this extension MUST list the keyword + MAILBOX-REFERRALS in their CAPABILITY response. No client action is + needed to invoke the MAILBOX-REFERRALS capability in a server. + + A MAILBOX-REFERRALS capable IMAP4 server MUST NOT return referrals + that result in a referrals loop. + + A referral response consists of a tagged NO response and a REFERRAL + response code. The REFERRAL response code MUST contain as an + argument a one or more valid URLs separated by a space as defined in + [RFC-1738]. If a server replies with multiple URLs for a particular + object, they MUST all be of the same type. In this case, the URL MUST + be an IMAP URL as defined in [RFC-2192]. A client that supports the + REFERRALS extension MUST be prepared for a URL of any type, but it + need only be able to process IMAP URLs. + + A server MAY respond with multiple IMAP mailbox referrals if there is + more than one replica of the mailbox. This allows the implementation + of a load balancing or failover scheme. How a server keeps multiple + replicas of a mailbox in sync is not addressed by this document. + + If the server has a preferred order in which the client should + attempt to access the URLs, the preferred URL SHOULD be listed in the + first, with the remaining URLs presented in descending order of + preference. If multiple referrals are given for a mailbox, a server + should be aware that there are synchronization issues for a client if + the UIDVALIDITY of the referred mailboxes are different. + + An IMAP mailbox referral may be given in response to an IMAP command + that specifies a mailbox as an argument. + + + + + + + + +Gahrns Standards Track [Page 2] + +RFC 2193 IMAP4 Mailbox Referrals September 1997 + + + Example: + + A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/REMOTE]Remote Mailbox + + NOTE: user;AUTH=* is specified as required by [RFC-2192] to avoid a + client falling back to anonymous login. + + Remote mailboxes and their inferiors, that are accessible only via + referrals SHOULD NOT appear in LIST and LSUB responses issued against + the user's home server. They MUST appear in RLIST and RLSUB + responses issued against the user's home server. Hierarchy referrals, + in which a client would be required to connect to the remote server + to issue a LIST to discover the inferiors of a mailbox are not + addressed in this document. + + For example, if shared mailboxes were only accessible via referrals + on a remote server, a RLIST "" "#SHARED/%" command would return the + same response if issued against the user's home server or the remote + server. + + Note: Mailboxes that are available on the user's home server do not + need to be available on the remote server. In addition, there may be + additional mailboxes available on the remote server, but they will + not accessible to the client via referrals unless they appear in the + LIST response to the RLIST command against the user's home server. + + A MAILBOX-REFERRALS capable client will issue the RLIST and RLSUB + commands in lieu of LIST and LSUB. The RLIST and RLSUB commands + behave identically to their LIST and LSUB counterparts, except remote + mailboxes are returned in addition to local mailboxes in the LIST and + LSUB responses. This avoids displaying to a non MAILBOX-REFERRALS + enabled client inaccessible remote mailboxes. + +4.1. SELECT, EXAMINE, DELETE, SUBSCRIBE, UNSUBSCRIBE, STATUS and APPEND + Referrals + + An IMAP4 server MAY respond to the SELECT, EXAMINE, DELETE, + SUBSCRIBE, UNSUBSCRIBE, STATUS or APPEND command with one or more + IMAP mailbox referrals to indicate to the client that the mailbox is + hosted on a remote server. + + When a client processes an IMAP mailbox referral, it will open a new + connection or use an existing connection to the remote server so that + it is able to issue the commands necessary to process the remote + mailbox. + + + + + + +Gahrns Standards Track [Page 3] + +RFC 2193 IMAP4 Mailbox Referrals September 1997 + + + Example: <IMAP4 connection to home server> + + C: A001 DELETE "SHARED/FOO" + S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/FOO] + Remote mailbox. Try SERVER2. + + <Client established a second connection to SERVER2 and + issues the DELETE command on the referred mailbox> + + S: * OK IMAP4rev1 server ready + C: B001 AUTHENTICATE KERBEROS_V4 + <authentication exchange> + S: B001 OK user is authenticated + + C: B002 DELETE "SHARED/FOO" + S: B002 OK DELETE completed + + Example: <IMAP4 connection to home server> + + C: A001 SELECT REMOTE + S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/REMOTE + IMAP://user;AUTH=*@SERVER3/REMOTE] Remote mailbox. + Try SERVER2 or SERVER3. + + <Client opens second connection to remote server, and + issues the commands needed to process the items in the + remote mailbox> + + S: * OK IMAP4rev1 server ready + C: B001 AUTHENTICATE KERBEROS_V4 + <authentication exchange> + S: B001 OK user is authenticated + + C: B002 SELECT REMOTE + S: * 12 EXISTS + S: * 1 RECENT + S: * OK [UNSEEN 10] Message 10 is first unseen + S: * OK [UIDVALIDITY 123456789] + S: * FLAGS (Answered Flagged Deleted Seen Draft) + S: * OK [PERMANENTFLAGS (Answered Deleted Seen ] + S: B002 OK [READ-WRITE] Selected completed + + C: B003 FETCH 10:12 RFC822 + S: * 10 FETCH . . . + S: * 11 FETCH . . . + S: * 12 FETCH . . . + S: B003 OK FETCH Completed + + + + +Gahrns Standards Track [Page 4] + +RFC 2193 IMAP4 Mailbox Referrals September 1997 + + + <Client is finished processing the REMOTE mailbox and + wants to process a mailbox on its home server> + + C: B004 LOGOUT + S: * BYE IMAP4rev1 server logging out + S: B004 OK LOGOUT Completed + + <Client continues with first connection> + + C: A002 SELECT INBOX + S: * 16 EXISTS + S: * 2 RECENT + S: * OK [UNSEEN 10] Message 10 is first unseen + S: * OK [UIDVALIDITY 123456789] + S: * FLAGS (Answered Flagged Deleted Seen Draft) + S: * OK [PERMANENTFLAGS (Answered Deleted Seen ] + S: A002 OK [READ-WRITE] Selected completed + +4.2. CREATE Referrals + + An IMAP4 server MAY respond to the CREATE command with one or more + IMAP mailbox referrals, if it wishes to direct the client to issue + the CREATE against another server. The server can employ any means, + such as examining the hierarchy of the specified mailbox name, in + determining which server the mailbox should be created on. + + Example: + + C: A001 CREATE "SHARED/FOO" + S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/FOO] + Mailbox should be created on remote server + + Alternatively, because a home server is required to maintain a + listing of referred remote mailboxes, a server MAY allow the creation + of a mailbox that will ultimately reside on a remote server against + the home server, and provide referrals on subsequent commands that + manipulate the mailbox. + + Example: + + C: A001 CREATE "SHARED/FOO" + S: A001 OK CREATE succeeded + + C: A002 SELECT "SHARED/FOO" + S: A002 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/FOO] + Remote mailbox. Try SERVER2 + + + + + +Gahrns Standards Track [Page 5] + +RFC 2193 IMAP4 Mailbox Referrals September 1997 + + +4.3. RENAME Referrals + + An IMAP4 server MAY respond to the RENAME command with one or more + pairs of IMAP mailbox referrals. In each pair of IMAP mailbox + referrals, the first one is an URL to the existing mailbox name and + the second is an URL to the requested new mailbox name. + + If within an IMAP mailbox referral pair, the existing and new mailbox + URLs are on different servers, the remote servers are unable to + perform the RENAME operation. To achieve the same behavior of + server RENAME, the client MAY issue the constituent CREATE, FETCH, + APPEND, and DELETE commands against both servers. + + If within an IMAP mailbox referral pair, the existing and new mailbox + URLs are on the same server it is an indication that the currently + connected server is unable to perform the operation. The client can + simply re-issue the RENAME command on the remote server. + + Example: + + C: A001 RENAME FOO BAR + S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER1/FOO + IMAP://user;AUTH=*@SERVER2/BAR] Unable to rename mailbox + across servers + + Since the existing and new mailbox names are on different servers, + the client would be required to make a connection to both servers and + issue the constituent commands require to achieve the RENAME. + + Example: + + C: A001 RENAME FOO BAR + S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/FOO + IMAP://user;AUTH=*@SERVER2/BAR] Unable to rename mailbox + located on SERVER2 + + Since both the existing and new mailbox are on the same remote + server, the client can simply make a connection to the remote server + and re-issue the RENAME command. + +4.4. COPY Referrals + + An IMAP4 server MAY respond to the COPY command with one or more IMAP + mailbox referrals. This indicates that the destination mailbox is on + a remote server. To achieve the same behavior of a server COPY, the + client MAY issue the constituent FETCH and APPEND commands against + both servers. + + + + +Gahrns Standards Track [Page 6] + +RFC 2193 IMAP4 Mailbox Referrals September 1997 + + + Example: + + C: A001 COPY 1 "SHARED/STUFF" + S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/STUFF] + Unable to copy message(s) to SERVER2. + +5.1 RLIST command + + Arguments: reference name + mailbox name with possible wildcards + + Responses: untagged responses: LIST + + Result: OK - RLIST Completed + NO - RLIST Failure + BAD - command unknown or arguments invalid + + The RLIST command behaves identically to its LIST counterpart, except + remote mailboxes are returned in addition to local mailboxes in the + LIST responses. + +5.2 RLSUB Command + + Arguments: reference name + mailbox name with possible wildcards + + Responses: untagged responses: LSUB + + Result: OK - RLSUB Completed + NO - RLSUB Failure + BAD - command unknown or arguments invalid + + The RLSUB command behaves identically to its LSUB counterpart, except + remote mailboxes are returned in addition to local mailboxes in the + LSUB responses. + +6. Formal Syntax + + The following syntax specification uses the augmented Backus-Naur + Form (BNF) as described in [ABNF]. + + list_mailbox = <list_mailbox> as defined in [RFC-2060] + + mailbox = <mailbox> as defined in [RFC-2060] + + mailbox_referral = <tag> SPACE "NO" SPACE + <referral_response_code> (text / text_mime2) + ; See [RFC-2060] for <tag>, text and text_mime2 definition + + + +Gahrns Standards Track [Page 7] + +RFC 2193 IMAP4 Mailbox Referrals September 1997 + + + referral_response_code = "[" "REFERRAL" 1*(SPACE <url>) "]" + ; See [RFC-1738] for <url> definition + + rlist = "RLIST" SPACE mailbox SPACE list_mailbox + + rlsub = "RLSUB" SPACE mailbox SPACE list_mailbox + +6. Security Considerations + + The IMAP4 referral mechanism makes use of IMAP URLs, and as such, + have the same security considerations as general internet URLs [RFC- + 1738], and in particular IMAP URLs [RFC-2192]. + + With the MAILBOX-REFERRALS capability, it is potentially easier to + write a rogue server that injects a bogus referral response that + directs a user to an incorrect mailbox. Although referrals reduce + the effort to write such a server, the referral response makes + detection of the intrusion easier. + +7. References + + [RFC-2060], Crispin, M., "Internet Message Access Protocol - Version + 4rev1", RFC 2060, University of Washington, December 1996. + + [RFC-2192], Newman, C., "IMAP URL Scheme", RFC 2192, Innosoft, + September 1997. + + [RFC-1738], Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform + Resource Locators (URL)", RFC 1738, CERN, Xerox Corporation, + University of Minnesota, December 1994. + + [RFC-2119], Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", RFC 2119, Harvard University, March 1997. + + [ABNF], DRUMS working group, Dave Crocker Editor, "Augmented BNF for + Syntax Specifications: ABNF", Work in Progress, Internet Mail + Consortium, April 1997. + +8. Acknowledgments + + Many valuable suggestions were received from private discussions and + the IMAP4 mailing list. In particular, Raymond Cheng, Mark Crispin, + Mark Keasling, Chris Newman and Larry Osterman made significant + contributions to this document. + + + + + + + +Gahrns Standards Track [Page 8] + +RFC 2193 IMAP4 Mailbox Referrals September 1997 + + +9. Author's Address + + Mike Gahrns + Microsoft + One Microsoft Way + Redmond, WA, 98072 + + Phone: (206) 936-9833 + EMail: mikega@microsoft.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Gahrns Standards Track [Page 9] + diff --git a/imap/docs/rfc/rfc2195.txt b/imap/docs/rfc/rfc2195.txt new file mode 100644 index 00000000..4a2725bf --- /dev/null +++ b/imap/docs/rfc/rfc2195.txt @@ -0,0 +1,283 @@ + + + + + + +Network Working Group J. Klensin +Request for Comments: 2195 R. Catoe +Category: Standards Track P. Krumviede +Obsoletes: 2095 MCI + September 1997 + + + IMAP/POP AUTHorize Extension for Simple Challenge/Response + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + While IMAP4 supports a number of strong authentication mechanisms as + described in RFC 1731, it lacks any mechanism that neither passes + cleartext, reusable passwords across the network nor requires either + a significant security infrastructure or that the mail server update + a mail-system-wide user authentication file on each mail access. + This specification provides a simple challenge-response + authentication protocol that is suitable for use with IMAP4. Since + it utilizes Keyed-MD5 digests and does not require that the secret be + stored in the clear on the server, it may also constitute an + improvement on APOP for POP3 use as specified in RFC 1734. + +1. Introduction + + Existing Proposed Standards specify an AUTHENTICATE mechanism for the + IMAP4 protocol [IMAP, IMAP-AUTH] and a parallel AUTH mechanism for + the POP3 protocol [POP3-AUTH]. The AUTHENTICATE mechanism is + intended to be extensible; the four methods specified in [IMAP-AUTH] + are all fairly powerful and require some security infrastructure to + support. The base POP3 specification [POP3] also contains a + lightweight challenge-response mechanism called APOP. APOP is + associated with most of the risks associated with such protocols: in + particular, it requires that both the client and server machines have + access to the shared secret in cleartext form. CRAM offers a method + for avoiding such cleartext storage while retaining the algorithmic + simplicity of APOP in using only MD5, though in a "keyed" method. + + + + + + + +Klensin, Catoe & Krumviede Standards Track [Page 1] + +RFC 2195 IMAP/POP AUTHorize Extension September 1997 + + + At present, IMAP [IMAP] lacks any facility corresponding to APOP. + The only alternative to the strong mechanisms identified in [IMAP- + AUTH] is a presumably cleartext username and password, supported + through the LOGIN command in [IMAP]. This document describes a + simple challenge-response mechanism, similar to APOP and PPP CHAP + [PPP], that can be used with IMAP (and, in principle, with POP3). + + This mechanism also has the advantage over some possible alternatives + of not requiring that the server maintain information about email + "logins" on a per-login basis. While mechanisms that do require such + per-login history records may offer enhanced security, protocols such + as IMAP, which may have several connections between a given client + and server open more or less simultaneous, may make their + implementation particularly challenging. + +2. Challenge-Response Authentication Mechanism (CRAM) + + The authentication type associated with CRAM is "CRAM-MD5". + + The data encoded in the first ready response contains an + presumptively arbitrary string of random digits, a timestamp, and the + fully-qualified primary host name of the server. The syntax of the + unencoded form must correspond to that of an RFC 822 'msg-id' + [RFC822] as described in [POP3]. + + The client makes note of the data and then responds with a string + consisting of the user name, a space, and a 'digest'. The latter is + computed by applying the keyed MD5 algorithm from [KEYED-MD5] where + the key is a shared secret and the digested text is the timestamp + (including angle-brackets). + + This shared secret is a string known only to the client and server. + The `digest' parameter itself is a 16-octet value which is sent in + hexadecimal format, using lower-case ASCII characters. + + When the server receives this client response, it verifies the digest + provided. If the digest is correct, the server should consider the + client authenticated and respond appropriately. + + Keyed MD5 is chosen for this application because of the greater + security imparted to authentication of short messages. In addition, + the use of the techniques described in [KEYED-MD5] for precomputation + of intermediate results make it possible to avoid explicit cleartext + storage of the shared secret on the server system by instead storing + the intermediate results which are known as "contexts". + + + + + + +Klensin, Catoe & Krumviede Standards Track [Page 2] + +RFC 2195 IMAP/POP AUTHorize Extension September 1997 + + + CRAM does not support a protection mechanism. + + Example: + + The examples in this document show the use of the CRAM mechanism with + the IMAP4 AUTHENTICATE command [IMAP-AUTH]. The base64 encoding of + the challenges and responses is part of the IMAP4 AUTHENTICATE + command, not part of the CRAM specification itself. + + S: * OK IMAP4 Server + C: A0001 AUTHENTICATE CRAM-MD5 + S: + PDE4OTYuNjk3MTcwOTUyQHBvc3RvZmZpY2UucmVzdG9uLm1jaS5uZXQ+ + C: dGltIGI5MTNhNjAyYzdlZGE3YTQ5NWI0ZTZlNzMzNGQzODkw + S: A0001 OK CRAM authentication successful + + In this example, the shared secret is the string + 'tanstaaftanstaaf'. Hence, the Keyed MD5 digest is produced by + calculating + + MD5((tanstaaftanstaaf XOR opad), + MD5((tanstaaftanstaaf XOR ipad), + <1896.697170952@postoffice.reston.mci.net>)) + + where ipad and opad are as defined in the keyed-MD5 Work in + Progress [KEYED-MD5] and the string shown in the challenge is the + base64 encoding of <1896.697170952@postoffice.reston.mci.net>. The + shared secret is null-padded to a length of 64 bytes. If the + shared secret is longer than 64 bytes, the MD5 digest of the + shared secret is used as a 16 byte input to the keyed MD5 + calculation. + + This produces a digest value (in hexadecimal) of + + b913a602c7eda7a495b4e6e7334d3890 + + The user name is then prepended to it, forming + + tim b913a602c7eda7a495b4e6e7334d3890 + + Which is then base64 encoded to meet the requirements of the IMAP4 + AUTHENTICATE command (or the similar POP3 AUTH command), yielding + + dGltIGI5MTNhNjAyYzdlZGE3YTQ5NWI0ZTZlNzMzNGQzODkw + + + + + + + + +Klensin, Catoe & Krumviede Standards Track [Page 3] + +RFC 2195 IMAP/POP AUTHorize Extension September 1997 + + +3. References + + [CHAP] Lloyd, B., and W. Simpson, "PPP Authentication Protocols", + RFC 1334, October 1992. + + [IMAP] Crispin, M., "Internet Message Access Protocol - Version + 4rev1", RFC 2060, University of Washington, December 1996. + + [IMAP-AUTH] Myers, J., "IMAP4 Authentication Mechanisms", + RFC 1731, Carnegie Mellon, December 1994. + + [KEYED-MD5] Krawczyk, Bellare, Canetti, "HMAC: Keyed-Hashing for + Message Authentication", RFC 2104, February 1997. + + [MD5] Rivest, R., "The MD5 Message Digest Algorithm", + RFC 1321, MIT Laboratory for Computer Science, April 1992. + + [POP3] Myers, J., and M. Rose, "Post Office Protocol - Version 3", + STD 53, RFC 1939, Carnegie Mellon, May 1996. + + [POP3-AUTH] Myers, J., "POP3 AUTHentication command", RFC 1734, + Carnegie Mellon, December, 1994. + +4. Security Considerations + + It is conjectured that use of the CRAM authentication mechanism + provides origin identification and replay protection for a session. + Accordingly, a server that implements both a cleartext password + command and this authentication type should not allow both methods of + access for a given user. + + While the saving, on the server, of "contexts" (see section 2) is + marginally better than saving the shared secrets in cleartext as is + required by CHAP [CHAP] and APOP [POP3], it is not sufficient to + protect the secrets if the server itself is compromised. + Consequently, servers that store the secrets or contexts must both be + protected to a level appropriate to the potential information value + in user mailboxes and identities. + + As the length of the shared secret increases, so does the difficulty + of deriving it. + + While there are now suggestions in the literature that the use of MD5 + and keyed MD5 in authentication procedures probably has a limited + effective lifetime, the technique is now widely deployed and widely + understood. It is believed that this general understanding may + assist with the rapid replacement, by CRAM-MD5, of the current uses + of permanent cleartext passwords in IMAP. This document has been + + + +Klensin, Catoe & Krumviede Standards Track [Page 4] + +RFC 2195 IMAP/POP AUTHorize Extension September 1997 + + + deliberately written to permit easy upgrading to use SHA (or whatever + alternatives emerge) when they are considered to be widely available + and adequately safe. + + Even with the use of CRAM, users are still vulnerable to active + attacks. An example of an increasingly common active attack is 'TCP + Session Hijacking' as described in CERT Advisory CA-95:01 [CERT95]. + + See section 1 above for additional discussion. + +5. Acknowledgements + + This memo borrows ideas and some text liberally from [POP3] and + [RFC-1731] and thanks are due the authors of those documents. Ran + Atkinson made a number of valuable technical and editorial + contributions to the document. + +6. Authors' Addresses + + John C. Klensin + MCI Telecommunications + 800 Boylston St, 7th floor + Boston, MA 02199 + USA + + EMail: klensin@mci.net + Phone: +1 617 960 1011 + + Randy Catoe + MCI Telecommunications + 2100 Reston Parkway + Reston, VA 22091 + USA + + EMail: randy@mci.net + Phone: +1 703 715 7366 + + Paul Krumviede + MCI Telecommunications + 2100 Reston Parkway + Reston, VA 22091 + USA + + EMail: paul@mci.net + Phone: +1 703 715 7251 + + + + + + +Klensin, Catoe & Krumviede Standards Track [Page 5] + diff --git a/imap/docs/rfc/rfc2221.txt b/imap/docs/rfc/rfc2221.txt new file mode 100644 index 00000000..81d00620 --- /dev/null +++ b/imap/docs/rfc/rfc2221.txt @@ -0,0 +1,283 @@ + + + + + + +Network Working Group M. Gahrns +Request for Comments: 2221 Microsoft +Category: Standards Track October 1997 + + + IMAP4 Login Referrals + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1997). All Rights Reserved. + +1. Abstract + + When dealing with large amounts of users and many IMAP4 [RFC-2060] + servers, it is often necessary to move users from one IMAP4 server to + another. For example, hardware failures or organizational changes + may dictate such a move. + + Login referrals allow clients to transparently connect to an + alternate IMAP4 server, if their home IMAP4 server has changed. + + A referral mechanism can provide efficiencies over the alternative + 'proxy method', in which the local IMAP4 server contacts the remote + server on behalf of the client, and then transfers the data from the + remote server to itself, and then on to the client. The referral + mechanism's direct client connection to the remote server is often a + more efficient use of bandwidth, and does not require the local + server to impersonate the client when authenticating to the remote + server. + +2. Conventions used in this document + + In examples, "C:" and "S:" indicate lines sent by the client and + server respectively. + + A home server, is an IMAP4 server that contains the user's inbox. + + A remote server is a server that contains remote mailboxes. + + + + + +Gahrns Standards Track [Page 1] + +RFC 2221 IMAP4 Login Referrals October 1997 + + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC-2119]. + +3. Introduction and Overview + + IMAP4 servers that support this extension MUST list the keyword + LOGIN-REFERRALS in their CAPABILITY response. No client action is + needed to invoke the LOGIN-REFERRALS capability in a server. + + A LOGIN-REFERRALS capable IMAP4 server SHOULD NOT return a referral + to a server that will return a referral. A client MUST NOT follow + more than 10 levels of referral without consulting the user. + + A LOGIN-REFERRALS response code MUST contain as an argument a valid + IMAP server URL as defined in [IMAP-URL]. + + A home server referral consists of either a tagged NO or OK, or an + untagged BYE response that contains a LOGIN-REFERRALS response code. + + Example: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/] Remote Server + + NOTE: user;AUTH=* is specified as required by [IMAP-URL] to avoid a + client falling back to anonymous login. + +4. Home Server Referrals + + A home server referral may be returned in response to an AUTHENTICATE + or LOGIN command, or it may appear in the connection startup banner. + If a server returns a home server referral in a tagged NO response, + that server does not contain any mailboxes that are accessible to the + user. If a server returns a home server referral in a tagged OK + response, it indicates that the user's personal mailboxes are + elsewhere, but the server contains public mailboxes which are + readable by the user. After receiving a home server referral, the + client can not make any assumptions as to whether this was a + permanent or temporary move of the user. + +4.1. LOGIN and AUTHENTICATE Referrals + + An IMAP4 server MAY respond to a LOGIN or AUTHENTICATE command with a + home server referral if it wishes to direct the user to another IMAP4 + server. + + Example: C: A001 LOGIN MIKE PASSWORD + S: A001 NO [REFERRAL IMAP://MIKE@SERVER2/] Specified user + is invalid on this server. Try SERVER2. + + + + +Gahrns Standards Track [Page 2] + +RFC 2221 IMAP4 Login Referrals October 1997 + + + Example: C: A001 LOGIN MATTHEW PASSWORD + S: A001 OK [REFERRAL IMAP://MATTHEW@SERVER2/] Specified + user's personal mailboxes located on Server2, but + public mailboxes are available. + + Example: C: A001 AUTHENTICATE GSSAPI + <authentication exchange> + S: A001 NO [REFERRAL IMAP://user;AUTH=GSSAPI@SERVER2/] + Specified user is invalid on this server. Try + SERVER2. + +4.2. BYE at connection startup referral + + An IMAP4 server MAY respond with an untagged BYE and a REFERRAL + response code that contains an IMAP URL to a home server if it is not + willing to accept connections and wishes to direct the client to + another IMAP4 server. + + Example: S: * BYE [REFERRAL IMAP://user;AUTH=*@SERVER2/] Server not + accepting connections. Try SERVER2 + +5. Formal Syntax + + The following syntax specification uses the augmented Backus-Naur + Form (BNF) as described in [ABNF]. + + This amends the "resp_text_code" element of the IMAP4 grammar + described in [RFC-2060] + + resp_text_code =/ "REFERRAL" SPACE <imapurl> + ; See [IMAP-URL] for definition of <imapurl> + ; See [RFC-2060] for base definition of resp_text_code + +6. Security Considerations + + The IMAP4 login referral mechanism makes use of IMAP URLs, and as + such, have the same security considerations as general internet URLs + [RFC-1738], and in particular IMAP URLs [IMAP-URL]. + + A server MUST NOT give a login referral if authentication for that + user fails. This is to avoid revealing information about the user's + account to an unauthorized user. + + With the LOGIN-REFERRALS capability, it is potentially easier to + write a rogue 'password catching' server that collects login data and + then refers the client to their actual IMAP4 server. Although + referrals reduce the effort to write such a server, the referral + response makes detection of the intrusion easier. + + + +Gahrns Standards Track [Page 3] + +RFC 2221 IMAP4 Login Referrals October 1997 + + +7. References + + [RFC-2060], Crispin, M., "Internet Message Access Protocol - Version + 4rev1", RFC 2060, December 1996. + + [IMAP-URL], Newman, C., "IMAP URL Scheme", RFC 2192, Innosoft, + September 1997. + + [RFC-1738], Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform + Resource Locators (URL)", RFC 1738, December 1994. + + [RFC-2119], Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", RFC 2119, March 1997. + + [ABNF], DRUMS working group, Dave Crocker Editor, "Augmented BNF for + Syntax Specifications: ABNF", Work in Progress. + +8. Acknowledgments + + Many valuable suggestions were received from private discussions and + the IMAP4 mailing list. In particular, Raymond Cheng, Mark Crispin, + Mark Keasling Chris Newman and Larry Osterman made significant + contributions to this document. + +9. Author's Address + + Mike Gahrns + Microsoft + One Microsoft Way + Redmond, WA, 98072 + + Phone: (206) 936-9833 + EMail: mikega@microsoft.com + + + + + + + + + + + + + + + + + + +Gahrns Standards Track [Page 4] + +RFC 2221 IMAP4 Login Referrals October 1997 + + +10. Full Copyright Statement + + Copyright (C) The Internet Society (1997). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implmentation may be prepared, copied, published + andand distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE." + + + + + + + + + + + + + + + + + + + + + + + + +Gahrns Standards Track [Page 5] + diff --git a/imap/docs/rfc/rfc2342.txt b/imap/docs/rfc/rfc2342.txt new file mode 100644 index 00000000..0926646d --- /dev/null +++ b/imap/docs/rfc/rfc2342.txt @@ -0,0 +1,563 @@ + + + + + + +Network Working Group M. Gahrns +Request for Comments: 2342 Microsoft +Category: Standards Track C. Newman + Innosoft + May 1998 + + + IMAP4 Namespace + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1998). All Rights Reserved. + +1. Abstract + + IMAP4 [RFC-2060] does not define a default server namespace. As a + result, two common namespace models have evolved: + + The "Personal Mailbox" model, in which the default namespace that is + presented consists of only the user's personal mailboxes. To access + shared mailboxes, the user must use an escape mechanism to reach + another namespace. + + The "Complete Hierarchy" model, in which the default namespace that + is presented includes the user's personal mailboxes along with any + other mailboxes they have access to. + + These two models, create difficulties for certain client operations. + This document defines a NAMESPACE command that allows a client to + discover the prefixes of namespaces used by a server for personal + mailboxes, other users' mailboxes, and shared mailboxes. This allows + a client to avoid much of the manual user configuration that is now + necessary when mixing and matching IMAP4 clients and servers. + +2. Conventions used in this document + + In examples, "C:" and "S:" indicate lines sent by the client and + server respectively. If such lines are wrapped without a new "C:" or + "S:" label, then the wrapping is for editorial clarity and is not + part of the command. + + + +Gahrns & Newman Standards Track [Page 1] + +RFC 2342 IMAP4 Namespace May 1998 + + + Personal Namespace: A namespace that the server considers within the + personal scope of the authenticated user on a particular connection. + Typically, only the authenticated user has access to mailboxes in + their Personal Namespace. It is the part of the namespace that + belongs to the user that is allocated for mailboxes. If an INBOX + exists for a user, it MUST appear within the user's personal + namespace. In the typical case, there SHOULD be only one Personal + Namespace on a server. + + Other Users' Namespace: A namespace that consists of mailboxes from + the Personal Namespaces of other users. To access mailboxes in the + Other Users' Namespace, the currently authenticated user MUST be + explicitly granted access rights. For example, it is common for a + manager to grant to their secretary access rights to their mailbox. + In the typical case, there SHOULD be only one Other Users' Namespace + on a server. + + Shared Namespace: A namespace that consists of mailboxes that are + intended to be shared amongst users and do not exist within a user's + Personal Namespace. + + The namespaces a server uses MAY differ on a per-user basis. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC-2119]. + +3. Introduction and Overview + + Clients often attempt to create mailboxes for such purposes as + maintaining a record of sent messages (e.g. "Sent Mail") or + temporarily saving messages being composed (e.g. "Drafts"). For + these clients to inter-operate correctly with the variety of IMAP4 + servers available, the user must enter the prefix of the Personal + Namespace used by the server. Using the NAMESPACE command, a client + is able to automatically discover this prefix without manual user + configuration. + + In addition, users are often required to manually enter the prefixes + of various namespaces in order to view the mailboxes located there. + For example, they might be required to enter the prefix of #shared to + view the shared mailboxes namespace. The NAMESPACE command allows a + client to automatically discover the namespaces that are available on + a server. This allows a client to present the available namespaces to + the user in what ever manner it deems appropriate. For example, a + + + + + + +Gahrns & Newman Standards Track [Page 2] + +RFC 2342 IMAP4 Namespace May 1998 + + + client could choose to initially display only personal mailboxes, or + it may choose to display the complete list of mailboxes available, + and initially position the user at the root of their Personal + Namespace. + + A server MAY choose to make available to the NAMESPACE command only a + subset of the complete set of namespaces the server supports. To + provide the ability to access these namespaces, a client SHOULD allow + the user the ability to manually enter a namespace prefix. + +4. Requirements + + IMAP4 servers that support this extension MUST list the keyword + NAMESPACE in their CAPABILITY response. + + The NAMESPACE command is valid in the Authenticated and Selected + state. + +5. NAMESPACE Command + + Arguments: none + + Response: an untagged NAMESPACE response that contains the prefix + and hierarchy delimiter to the server's Personal + Namespace(s), Other Users' Namespace(s), and Shared + Namespace(s) that the server wishes to expose. The + response will contain a NIL for any namespace class + that is not available. Namespace_Response_Extensions + MAY be included in the response. + Namespace_Response_Extensions which are not on the IETF + standards track, MUST be prefixed with an "X-". + + Result: OK - Command completed + NO - Error: Can't complete command + BAD - argument invalid + + Example 5.1: + =========== + + < A server that supports a single personal namespace. No leading + prefix is used on personal mailboxes and "/" is the hierarchy + delimiter.> + + C: A001 NAMESPACE + S: * NAMESPACE (("" "/")) NIL NIL + S: A001 OK NAMESPACE command completed + + + + + +Gahrns & Newman Standards Track [Page 3] + +RFC 2342 IMAP4 Namespace May 1998 + + + Example 5.2: + =========== + + < A user logged on anonymously to a server. No personal mailboxes + are associated with the anonymous user and the user does not have + access to the Other Users' Namespace. No prefix is required to + access shared mailboxes and the hierarchy delimiter is "." > + + C: A001 NAMESPACE + S: * NAMESPACE NIL NIL (("" ".")) + S: A001 OK NAMESPACE command completed + + Example 5.3: + =========== + + < A server that contains a Personal Namespace and a single Shared + Namespace. > + + C: A001 NAMESPACE + S: * NAMESPACE (("" "/")) NIL (("Public Folders/" "/")) + S: A001 OK NAMESPACE command completed + + Example 5.4: + =========== + + < A server that contains a Personal Namespace, Other Users' + Namespace and multiple Shared Namespaces. Note that the hierarchy + delimiter used within each namespace can be different. > + + C: A001 NAMESPACE + S: * NAMESPACE (("" "/")) (("~" "/")) (("#shared/" "/") + ("#public/" "/")("#ftp/" "/")("#news." ".")) + S: A001 OK NAMESPACE command completed + + The prefix string allows a client to do things such as automatically + creating personal mailboxes or LISTing all available mailboxes within + a namespace. + + Example 5.5: + =========== + + < A server that supports only the Personal Namespace, with a + leading prefix of INBOX to personal mailboxes and a hierarchy + delimiter of "."> + + C: A001 NAMESPACE + S: * NAMESPACE (("INBOX." ".")) NIL NIL + S: A001 OK NAMESPACE command completed + + + +Gahrns & Newman Standards Track [Page 4] + +RFC 2342 IMAP4 Namespace May 1998 + + + < Automatically create a mailbox to store sent items.> + + C: A002 CREATE "INBOX.Sent Mail" + S: A002 OK CREATE command completed + + Although typically a server will support only a single Personal + Namespace, and a single Other User's Namespace, circumstances exist + where there MAY be multiples of these, and a client MUST be prepared + for them. If a client is configured such that it is required to + create a certain mailbox, there can be circumstances where it is + unclear which Personal Namespaces it should create the mailbox in. + In these situations a client SHOULD let the user select which + namespaces to create the mailbox in. + + Example 5.6: + =========== + + < In this example, a server supports 2 Personal Namespaces. In + addition to the regular Personal Namespace, the user has an + additional personal namespace to allow access to mailboxes in an + MH format mailstore. > + + < The client is configured to save a copy of all mail sent by the + user into a mailbox called 'Sent Mail'. Furthermore, after a + message is deleted from a mailbox, the client is configured to + move that message to a mailbox called 'Deleted Items'.> + + < Note that this example demonstrates how some extension flags can + be passed to further describe the #mh namespace. > + + C: A001 NAMESPACE + S: * NAMESPACE (("" "/")("#mh/" "/" "X-PARAM" ("FLAG1" "FLAG2"))) + NIL NIL + S: A001 OK NAMESPACE command completed + + < It is desired to keep only one copy of sent mail. It is unclear + which Personal Namespace the client should use to create the 'Sent + Mail' mailbox. The user is prompted to select a namespace and + only one 'Sent Mail' mailbox is created. > + + C: A002 CREATE "Sent Mail" + S: A002 OK CREATE command completed + + < The client is designed so that it keeps two 'Deleted Items' + mailboxes, one for each namespace. > + + C: A003 CREATE "Delete Items" + S: A003 OK CREATE command completed + + + +Gahrns & Newman Standards Track [Page 5] + +RFC 2342 IMAP4 Namespace May 1998 + + + C: A004 CREATE "#mh/Deleted Items" + S: A004 OK CREATE command completed + + The next level of hierarchy following the Other Users' Namespace + prefix SHOULD consist of <username>, where <username> is a user name + as per the IMAP4 LOGIN or AUTHENTICATE command. + + A client can construct a LIST command by appending a "%" to the Other + Users' Namespace prefix to discover the Personal Namespaces of other + users that are available to the currently authenticated user. + + In response to such a LIST command, a server SHOULD NOT return user + names that have not granted access to their personal mailboxes to the + user in question. + + A server MAY return a LIST response containing only the names of + users that have explicitly granted access to the user in question. + + Alternatively, a server MAY return NO to such a LIST command, + requiring that a user name be included with the Other Users' + Namespace prefix before listing any other user's mailboxes. + + Example 5.7: + =========== + + < A server that supports providing a list of other user's + mailboxes that are accessible to the currently logged on user. > + + C: A001 NAMESPACE + S: * NAMESPACE (("" "/")) (("Other Users/" "/")) NIL + S: A001 OK NAMESPACE command completed + + C: A002 LIST "" "Other Users/%" + S: * LIST () "/" "Other Users/Mike" + S: * LIST () "/" "Other Users/Karen" + S: * LIST () "/" "Other Users/Matthew" + S: * LIST () "/" "Other Users/Tesa" + S: A002 OK LIST command completed + + Example 5.8: + =========== + + < A server that does not support providing a list of other user's + mailboxes that are accessible to the currently logged on user. + The mailboxes are listable if the client includes the name of the + other user with the Other Users' Namespace prefix. > + + + + + +Gahrns & Newman Standards Track [Page 6] + +RFC 2342 IMAP4 Namespace May 1998 + + + C: A001 NAMESPACE + S: * NAMESPACE (("" "/")) (("#Users/" "/")) NIL + S: A001 OK NAMESPACE command completed + + < In this example, the currently logged on user has access to the + Personal Namespace of user Mike, but the server chose to suppress + this information in the LIST response. However, by appending the + user name Mike (received through user input) to the Other Users' + Namespace prefix, the client is able to get a listing of the + personal mailboxes of user Mike. > + + C: A002 LIST "" "#Users/%" + S: A002 NO The requested item could not be found. + + C: A003 LIST "" "#Users/Mike/%" + S: * LIST () "/" "#Users/Mike/INBOX" + S: * LIST () "/" "#Users/Mike/Foo" + S: A003 OK LIST command completed. + + A prefix string might not contain a hierarchy delimiter, because + in some cases it is not needed as part of the prefix. + + Example 5.9: + =========== + + < A server that allows access to the Other Users' Namespace by + prefixing the others' mailboxes with a '~' followed by <username>, + where <username> is a user name as per the IMAP4 LOGIN or + AUTHENTICATE command.> + + C: A001 NAMESPACE + S: * NAMESPACE (("" "/")) (("~" "/")) NIL + S: A001 OK NAMESPACE command completed + + < List the mailboxes for user mark > + + C: A002 LIST "" "~mark/%" + S: * LIST () "/" "~mark/INBOX" + S: * LIST () "/" "~mark/foo" + S: A002 OK LIST command completed + + Historical convention has been to start all namespaces with the "#" + character. Namespaces that include the "#" character are not IMAP + URL [IMAP-URL] friendly requiring the "#" character to be represented + as %23 when within URLs. As such, server implementers MAY instead + consider using namespace prefixes that do not contain the "#" + character. + + + + +Gahrns & Newman Standards Track [Page 7] + +RFC 2342 IMAP4 Namespace May 1998 + + +6. Formal Syntax + + The following syntax specification uses the augmented Backus-Naur + Form (BNF) as described in [ABNF]. + + atom = <atom> + ; <atom> as defined in [RFC-2060] + + Namespace = nil / "(" 1*( "(" string SP (<"> QUOTED_CHAR <"> / + nil) *(Namespace_Response_Extension) ")" ) ")" + + Namespace_Command = "NAMESPACE" + + Namespace_Response_Extension = SP string SP "(" string *(SP string) + ")" + + Namespace_Response = "*" SP "NAMESPACE" SP Namespace SP Namespace SP + Namespace + + ; The first Namespace is the Personal Namespace(s) + ; The second Namespace is the Other Users' Namespace(s) + ; The third Namespace is the Shared Namespace(s) + + nil = <nil> + ; <nil> as defined in [RFC-2060] + + QUOTED_CHAR = <QUOTED_CHAR> + ; <QUOTED_CHAR> as defined in [RFC-2060] + + string = <string> + ; <string> as defined in [RFC-2060] + ; Note that the namespace prefix is to a mailbox and following + ; IMAP4 convention, any international string in the NAMESPACE + ; response MUST be of modified UTF-7 format as described in + ; [RFC-2060]. + +7. Security Considerations + + In response to a LIST command containing an argument of the Other + Users' Namespace prefix, a server SHOULD NOT list users that have not + granted list access to their personal mailboxes to the currently + authenticated user. Providing such a list, could compromise security + by potentially disclosing confidential information of who is located + on the server, or providing a starting point of a list of user + accounts to attack. + + + + + + +Gahrns & Newman Standards Track [Page 8] + +RFC 2342 IMAP4 Namespace May 1998 + + +8. References + + [RFC-2060], Crispin, M., "Internet Message Access Protocol Version + 4rev1", RFC 2060, December 1996. + + [RFC-2119], Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [ABNF] Crocker, D., Editor, and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997. + + [IMAP-URL], Newman, C., "IMAP URL Scheme", RFC 2192, September 1997. + +9. Acknowledgments + + Many people have participated in the discussion of IMAP namespaces on + the IMAP mailing list. In particular, the authors would like to + thank Mark Crispin for many of the concepts relating to the Personal + Namespace and accessing the Personal Namespace of other users, Steve + Hole for summarizing the two namespace models, John Myers and Jack De + Winter for their work in a preceding effort trying to define a + standardized personal namespace, and Larry Osterman for his review + and collaboration on this document. + +11. Authors' Addresses + + Mike Gahrns + Microsoft + One Microsoft Way + Redmond, WA, 98072, USA + + Phone: (425) 936-9833 + EMail: mikega@microsoft.com + + + Chris Newman + Innosoft International, Inc. + 1050 East Garvey Ave. South + West Covina, CA, 91790, USA + + EMail: chris.newman@innosoft.com + + + + + + + + + + +Gahrns & Newman Standards Track [Page 9] + +RFC 2342 IMAP4 Namespace May 1998 + + +12. Full Copyright Statement + + Copyright (C) The Internet Society (1998). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + + + + + + + + + + + + + + + + + + + + + + + + +Gahrns & Newman Standards Track [Page 10] + diff --git a/imap/docs/rfc/rfc2683.txt b/imap/docs/rfc/rfc2683.txt new file mode 100644 index 00000000..d92e3405 --- /dev/null +++ b/imap/docs/rfc/rfc2683.txt @@ -0,0 +1,1291 @@ + + + + + + +Network Working Group B. Leiba +Request for Comments: 2683 IBM T.J. Watson Research Center +Category: Informational September 1999 + + + IMAP4 Implementation Recommendations + +Status of this Memo + + This memo provides information for the Internet community. It does + not specify an Internet standard of any kind. Distribution of this + memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1999). All Rights Reserved. + +1. Abstract + + The IMAP4 specification [RFC-2060] describes a rich protocol for use + in building clients and servers for storage, retrieval, and + manipulation of electronic mail. Because the protocol is so rich and + has so many implementation choices, there are often trade-offs that + must be made and issues that must be considered when designing such + clients and servers. This document attempts to outline these issues + and to make recommendations in order to make the end products as + interoperable as possible. + +2. Conventions used in this document + + In examples, "C:" indicates lines sent by a client that is connected + to a server. "S:" indicates lines sent by the server to the client. + + The words "must", "must not", "should", "should not", and "may" are + used with specific meaning in this document; since their meaning is + somewhat different from that specified in RFC 2119, we do not put + them in all caps here. Their meaning is as follows: + + must -- This word means that the action described is necessary + to ensure interoperability. The recommendation should + not be ignored. + must not -- This phrase means that the action described will be + almost certain to hurt interoperability. The + recommendation should not be ignored. + + + + + + + +Leiba Informational [Page 1] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + + should -- This word means that the action described is strongly + recommended and will enhance interoperability or + usability. The recommendation should not be ignored + without careful consideration. + should not -- This phrase means that the action described is strongly + recommended against, and might hurt interoperability or + usability. The recommendation should not be ignored + without careful consideration. + may -- This word means that the action described is an + acceptable implementation choice. No specific + recommendation is implied; this word is used to point + out a choice that might not be obvious, or to let + implementors know what choices have been made by + existing implementations. + +3. Interoperability Issues and Recommendations + +3.1. Accessibility + + This section describes the issues related to access to servers and + server resources. Concerns here include data sharing and maintenance + of client/server connections. + +3.1.1. Multiple Accesses of the Same Mailbox + + One strong point of IMAP4 is that, unlike POP3, it allows for + multiple simultaneous access to a single mailbox. A user can, thus, + read mail from a client at home while the client in the office is + still connected; or the help desk staff can all work out of the same + inbox, all seeing the same pool of questions. An important point + about this capability, though is that NO SERVER IS GUARANTEED TO + SUPPORT THIS. If you are selecting an IMAP server and this facility + is important to you, be sure that the server you choose to install, + in the configuration you choose to use, supports it. + + If you are designing a client, you must not assume that you can + access the same mailbox more than once at a time. That means + + 1. you must handle gracefully the failure of a SELECT command if the + server refuses the second SELECT, + 2. you must handle reasonably the severing of your connection (see + "Severed Connections", below) if the server chooses to allow the + second SELECT by forcing the first off, + 3. you must avoid making multiple connections to the same mailbox in + your own client (for load balancing or other such reasons), and + 4. you must avoid using the STATUS command on a mailbox that you have + selected (with some server implementations the STATUS command has + the same problems with multiple access as do the SELECT and + + + +Leiba Informational [Page 2] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + + EXAMINE commands). + + A further note about STATUS: The STATUS command is sometimes used to + check a non-selected mailbox for new mail. This mechanism must not + be used to check for new mail in the selected mailbox; section 5.2 of + [RFC-2060] specifically forbids this in its last paragraph. Further, + since STATUS takes a mailbox name it is an independent operation, not + operating on the selected mailbox. Because of this, the information + it returns is not necessarily in synchronization with the selected + mailbox state. + +3.1.2. Severed Connections + + The client/server connection may be severed for one of three reasons: + the client severs the connection, the server severs the connection, + or the connection is severed by outside forces beyond the control of + the client and the server (a telephone line drops, for example). + Clients and servers must both deal with these situations. + + When the client wants to sever a connection, it's usually because it + has finished the work it needed to do on that connection. The client + should send a LOGOUT command, wait for the tagged response, and then + close the socket. But note that, while this is what's intended in + the protocol design, there isn't universal agreement here. Some + contend that sending the LOGOUT and waiting for the two responses + (untagged BYE and tagged OK) is wasteful and unnecessary, and that + the client can simply close the socket. The server should interpret + the closed socket as a log out by the client. The counterargument is + that it's useful from the standpoint of cleanup, problem + determination, and the like, to have an explicit client log out, + because otherwise there is no way for the server to tell the + difference between "closed socket because of log out" and "closed + socket because communication was disrupted". If there is a + client/server interaction problem, a client which routinely + terminates a session by breaking the connection without a LOGOUT will + make it much more difficult to determine the problem. + + Because of this disagreement, server designers must be aware that + some clients might close the socket without sending a LOGOUT. In any + case, whether or not a LOGOUT was sent, the server should not + implicitly expunge any messages from the selected mailbox. If a + client wants the server to do so, it must send a CLOSE or EXPUNGE + command explicitly. + + When the server wants to sever a connection it's usually due to an + inactivity timeout or is because a situation has arisen that has + changed the state of the mail store in a way that the server can not + communicate to the client. The server should send an untagged BYE + + + +Leiba Informational [Page 3] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + + response to the client and then close the socket. Sending an + untagged BYE response before severing allows the server to send a + human-readable explanation of the problem to the client, which the + client may then log, display to the user, or both (see section 7.1.5 + of [RFC-2060]). + + Regarding inactivity timeouts, there is some controversy. Unlike + POP, for which the design is for a client to connect, retrieve mail, + and log out, IMAP's design encourages long-lived (and mostly + inactive) client/server sessions. As the number of users grows, this + can use up a lot of server resources, especially with clients that + are designed to maintain sessions for mailboxes that the user has + finished accessing. To alleviate this, a server may implement an + inactivity timeout, unilaterally closing a session (after first + sending an untagged BYE, as noted above). Some server operators have + reported dramatic improvements in server performance after doing + this. As specified in [RFC-2060], if such a timeout is done it must + not be until at least 30 minutes of inactivity. The reason for this + specification is to prevent clients from sending commands (such as + NOOP) to the server at frequent intervals simply to avert a too-early + timeout. If the client knows that the server may not time out the + session for at least 30 minutes, then the client need not poll at + intervals more frequent than, say, 25 minutes. + +3.2. Scaling + + IMAP4 has many features that allow for scalability, as mail stores + become larger and more numerous. Large numbers of users, mailboxes, + and messages, and very large messages require thought to handle + efficiently. This document will not address the administrative + issues involved in large numbers of users, but we will look at the + other items. + +3.2.1. Flood Control + + There are three situations when a client can make a request that will + result in a very large response - too large for the client reasonably + to deal with: there are a great many mailboxes available, there are a + great many messages in the selected mailbox, or there is a very large + message part. The danger here is that the end user will be stuck + waiting while the server sends (and the client processes) an enormous + response. In all of these cases there are things a client can do to + reduce that danger. + + There is also the case where a client can flood a server, by sending + an arbitratily long command. We'll discuss that issue, too, in this + section. + + + + +Leiba Informational [Page 4] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + +3.2.1.1. Listing Mailboxes + + Some servers present Usenet newsgroups to IMAP users. Newsgroups, + and other such hierarchical mailbox structures, can be very numerous + but may have only a few entries at the top level of hierarchy. Also, + some servers are built against mail stores that can, unbeknownst to + the server, have circular hierarchies - that is, it's possible for + "a/b/c/d" to resolve to the same file structure as "a", which would + then mean that "a/b/c/d/b" is the same as "a/b", and the hierarchy + will never end. The LIST response in this case will be unlimited. + + Clients that will have trouble with this are those that use + + C: 001 LIST "" * + + to determine the mailbox list. Because of this, clients should not + use an unqualified "*" that way in the LIST command. A safer + approach is to list each level of hierarchy individually, allowing + the user to traverse the tree one limb at a time, thus: + + C: 001 LIST "" % + S: * LIST () "/" Banana + S: * LIST ...etc... + S: 001 OK done + + and then + + C: 002 LIST "" Banana/% + S: * LIST () "/" Banana/Apple + S: * LIST ...etc... + S: 002 OK done + + Using this technique the client's user interface can give the user + full flexibility without choking on the voluminous reply to "LIST *". + + Of course, it is still possible that the reply to + + C: 005 LIST "" alt.fan.celebrity.% + + may be thousands of entries long, and there is, unfortunately, + nothing the client can do to protect itself from that. This has not + yet been a notable problem. + + Servers that may export circular hierarchies (any server that + directly presents a UNIX file system, for instance) should limit the + hierarchy depth to prevent unlimited LIST responses. A suggested + depth limit is 20 hierarchy levels. + + + + +Leiba Informational [Page 5] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + +3.2.1.2. Fetching the List of Messages + + When a client selects a mailbox, it is given a count, in the untagged + EXISTS response, of the messages in the mailbox. This number can be + very large. In such a case it might be unwise to use + + C: 004 FETCH 1:* ALL + + to populate the user's view of the mailbox. One good method to avoid + problems with this is to batch the requests, thus: + + C: 004 FETCH 1:50 ALL + S: * 1 FETCH ...etc... + S: 004 OK done + C: 005 FETCH 51:100 ALL + S: * 51 FETCH ...etc... + S: 005 OK done + C: 006 FETCH 101:150 ALL + ...etc... + + Using this method, another command, such as "FETCH 6 BODY[1]" can be + inserted as necessary, and the client will not have its access to the + server blocked by a storm of FETCH replies. (Such a method could be + reversed to fetch the LAST 50 messages first, then the 50 prior to + that, and so on.) + + As a smart extension of this, a well designed client, prepared for + very large mailboxes, will not automatically fetch data for all + messages AT ALL. Rather, the client will populate the user's view + only as the user sees it, possibly pre-fetching selected information, + and only fetching other information as the user scrolls to it. For + example, to select only those messages beginning with the first + unseen one: + + C: 003 SELECT INBOX + S: * 10000 EXISTS + S: * 80 RECENT + S: * FLAGS (\Answered \Flagged \Deleted \Draft \Seen) + S: * OK [UIDVALIDITY 824708485] UID validity status + S: * OK [UNSEEN 9921] First unseen message + S: 003 OK [READ-WRITE] SELECT completed + C: 004 FETCH 9921:* ALL + ... etc... + + If the server does not return an OK [UNSEEN] response, the client may + use SEARCH UNSEEN to obtain that value. + + + + + +Leiba Informational [Page 6] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + + This mechanism is good as a default presentation method, but only + works well if the default message order is acceptable. A client may + want to present various sort orders to the user (by subject, by date + sent, by sender, and so on) and in that case (lacking a SORT + extension on the server side) the client WILL have to retrieve all + message descriptors. A client that provides this service should not + do it by default and should inform the user of the costs of choosing + this option for large mailboxes. + +3.2.1.3. Fetching a Large Body Part + + The issue here is similar to the one for a list of messages. In the + BODYSTRUCTURE response the client knows the size, in bytes, of the + body part it plans to fetch. Suppose this is a 70 MB video clip. The + client can use partial fetches to retrieve the body part in pieces, + avoiding the problem of an uninterruptible 70 MB literal coming back + from the server: + + C: 022 FETCH 3 BODY[1]<0.20000> + S: * 3 FETCH (FLAGS(\Seen) BODY[1]<0> {20000} + S: ...data...) + S: 022 OK done + C: 023 FETCH 3 BODY[1]<20001.20000> + S: * 3 FETCH (BODY[1]<20001> {20000} + S: ...data...) + S: 023 OK done + C: 024 FETCH 3 BODY[1]<40001.20000> + ...etc... + +3.2.1.4. BODYSTRUCTURE vs. Entire Messages + + Because FETCH BODYSTRUCTURE is necessary in order to determine the + number of body parts, and, thus, whether a message has "attachments", + clients often use FETCH FULL as their normal method of populating the + user's view of a mailbox. The benefit is that the client can display + a paperclip icon or some such indication along with the normal + message summary. However, this comes at a significant cost with some + server configurations. The parsing needed to generate the FETCH + BODYSTRUCTURE response may be time-consuming compared with that + needed for FETCH ENVELOPE. The client developer should consider this + issue when deciding whether the ability to add a paperclip icon is + worth the tradeoff in performance, especially with large mailboxes. + + Some clients, rather than using FETCH BODYSTRUCTURE, use FETCH BODY[] + (or the equivalent FETCH RFC822) to retrieve the entire message. + They then do the MIME parsing in the client. This may give the + client slightly more flexibility in some areas (access, for instance, + to header fields that aren't returned in the BODYSTRUCTURE and + + + +Leiba Informational [Page 7] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + + ENVELOPE responses), but it can cause severe performance problems by + forcing the transfer of all body parts when the user might only want + to see some of them - a user logged on by modem and reading a small + text message with a large ZIP file attached may prefer to read the + text only and save the ZIP file for later. Therefore, a client + should not normally retrieve entire messages and should retrieve + message body parts selectively. + +3.2.1.5. Long Command Lines + + A client can wind up building a very long command line in an effort to + try to be efficient about requesting information from a server. This + can typically happen when a client builds a message set from selected + messages and doesn't recognise that contiguous blocks of messages may + be group in a range. Suppose a user selects all 10,000 messages in a + large mailbox and then unselects message 287. The client could build + that message set as "1:286,288:10000", but a client that doesn't + handle that might try to enumerate each message individually and build + "1,2,3,4, [and so on] ,9999,10000". Adding that to the fetch command + results in a command line that's almost 49,000 octets long, and, + clearly, one can construct a command line that's even longer. + + A client should limit the length of the command lines it generates to + approximately 1000 octets (including all quoted strings but not + including literals). If the client is unable to group things into + ranges so that the command line is within that length, it should + split the request into multiple commands. The client should use + literals instead of long quoted strings, in order to keep the command + length down. + + For its part, a server should allow for a command line of at least + 8000 octets. This provides plenty of leeway for accepting reasonable + length commands from clients. The server should send a BAD response + to a command that does not end within the server's maximum accepted + command length. + +3.2.2. Subscriptions + + The client isn't the only entity that can get flooded: the end user, + too, may need some flood control. The IMAP4 protocol provides such + control in the form of subscriptions. Most servers support the + SUBSCRIBE, UNSUBSCRIBE, and LSUB commands, and many users choose to + narrow down a large list of available mailboxes by subscribing to the + ones that they usually want to see. Clients, with this in mind, + should give the user a way to see only subscribed mailboxes. A + client that never uses the LSUB command takes a significant usability + feature away from the user. Of course, the client would not want to + hide the LIST command completely; the user needs to have a way to + + + +Leiba Informational [Page 8] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + + choose between LIST and LSUB. The usual way to do this is to provide + a setting like "show which mailboxes?: [] all [] subscribed only". + +3.2.3. Searching + + IMAP SEARCH commands can become particularly troublesome (that is, + slow) on mailboxes containing a large number of messages. So let's + put a few things in perspective in that regard. + + The flag searches should be fast. The flag searches (ALL, [UN]SEEN, + [UN]ANSWERED, [UN]DELETED, [UN]DRAFT, [UN]FLAGGED, NEW, OLD, RECENT) + are known to be used by clients for the client's own use (for + instance, some clients use "SEARCH UNSEEN" to find unseen mail and + "SEARCH DELETED" to warn the user before expunging messages). + + Other searches, particularly the text searches (HEADER, TEXT, BODY) + are initiated by the user, rather than by the client itself, and + somewhat slower performance can be tolerated, since the user is aware + that the search is being done (and is probably aware that it might be + time-consuming). A smart server might use dynamic indexing to speed + commonly used text searches. + + The client may allow other commands to be sent to the server while a + SEARCH is in progress, but at the time of this writing there is + little or no server support for parallel processing of multiple + commands in the same session (and see "Multiple Accesses of the Same + Mailbox" above for a description of the dangers of trying to work + around this by doing your SEARCH in another session). + + Another word about text searches: some servers, built on database + back-ends with indexed search capabilities, may return search results + that do not match the IMAP spec's "case-insensitive substring" + requirements. While these servers are in violation of the protocol, + there is little harm in the violation as long as the search results + are used only in response to a user's request. Still, developers of + such servers should be aware that they ARE violating the protocol, + should think carefully about that behaviour, and must be certain that + their servers respond accurately to the flag searches for the reasons + outlined above. + + In addition, servers should support CHARSET UTF-8 [UTF-8] in + searches. + + + + + + + + + +Leiba Informational [Page 9] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + +3.3 Avoiding Invalid Requests + + IMAP4 provides ways for a server to tell a client in advance what is + and isn't permitted in some circumstances. Clients should use these + features to avoid sending requests that a well designed client would + know to be invalid. This section explains this in more detail. + +3.3.1. The CAPABILITY Command + + All IMAP4 clients should use the CAPABILITY command to determine what + version of IMAP and what optional features a server supports. The + client should not send IMAP4rev1 commands and arguments to a server + that does not advertize IMAP4rev1 in its CAPABILITY response. + Similarly, the client should not send IMAP4 commands that no longer + exist in IMAP4rev1 to a server that does not advertize IMAP4 in its + CAPABILITY response. An IMAP4rev1 server is NOT required to support + obsolete IMAP4 or IMAP2bis commands (though some do; do not let this + fact lull you into thinking that it's valid to send such commands to + an IMAP4rev1 server). + + A client should not send commands to probe for the existance of + certain extensions. All standard and standards-track extensions + include CAPABILITY tokens indicating their presense. All private and + experimental extensions should do the same, and clients that take + advantage of them should use the CAPABILITY response to determine + whether they may be used or not. + +3.3.2. Don't Do What the Server Says You Can't + + In many cases, the server, in response to a command, will tell the + client something about what can and can't be done with a particular + mailbox. The client should pay attention to this information and + should not try to do things that it's been told it can't do. + + Examples: + + * Do not try to SELECT a mailbox that has the \Noselect flag set. + * Do not try to CREATE a sub-mailbox in a mailbox that has the + \Noinferiors flag set. + * Do not respond to a failing COPY or APPEND command by trying to + CREATE the target mailbox if the server does not respond with a + [TRYCREATE] response code. + * Do not try to expunge a mailbox that has been selected with the + [READ-ONLY] response code. + + + + + + + +Leiba Informational [Page 10] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + +3.4. Miscellaneous Protocol Considerations + + We describe here a number of important protocol-related issues, the + misunderstanding of which has caused significant interoperability + problems in IMAP4 implementations. One general item is that every + implementer should be certain to take note of and to understand + section 2.2.2 and the preamble to section 7 of the IMAP4rev1 spec + [RFC-2060]. + +3.4.1. Well Formed Protocol + + We cannot stress enough the importance of adhering strictly to the + protocol grammar. The specification of the protocol is quite rigid; + do not assume that you can insert blank space for "readability" if + none is called for. Keep in mind that there are parsers out there + that will crash if there are protocol errors. There are clients that + will report every parser burp to the user. And in any case, + information that cannot be parsed is information that is lost. Be + careful in your protocol generation. And see "A Word About Testing", + below. + + In particular, note that the string in the INTERNALDATE response is + NOT an RFC-822 date string - that is, it is not in the same format as + the first string in the ENVELOPE response. Since most clients will, + in fact, accept an RFC-822 date string in the INTERNALDATE response, + it's easy to miss this in your interoperability testing. But it will + cause a problem with some client, so be sure to generate the correct + string for this field. + +3.4.2. Special Characters + + Certain characters, currently the double-quote and the backslash, may + not be sent as-is inside a quoted string. These characters must be + preceded by the escape character if they are in a quoted string, or + else the string must be sent as a literal. Both clients and servers + must handle this, both on output (they must send these characters + properly) and on input (they must be able to receive escaped + characters in quoted strings). Example: + + C: 001 LIST "" % + S: * LIST () "" INBOX + S: * LIST () "\\" TEST + S: * LIST () "\\" {12} + S: "My" mailbox + S: 001 OK done + C: 002 LIST "" "\"My\" mailbox\\%" + S: * LIST () "\\" {17} + S: "My" mailbox\Junk + + + +Leiba Informational [Page 11] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + + S: 002 OK done + + Note that in the example the server sent the hierarchy delimiter as + an escaped character in the quoted string and sent the mailbox name + containing imbedded double-quotes as a literal. The client used only + quoted strings, escaping both the backslash and the double-quote + characters. + + The CR and LF characters may be sent ONLY in literals; they are not + allowed, even if escaped, inside quoted strings. + + And while we're talking about special characters: the IMAP spec, in + the section titled "Mailbox International Naming Convention", + describes how to encode mailbox names in modified UTF-7 [UTF-7 and + RFC-2060]. Implementations must adhere to this in order to be + interoperable in the international market, and servers should + validate mailbox names sent by client and reject names that do not + conform. + + As to special characters in userids and passwords: clients must not + restrict what a user may type in for a userid or a password. The + formal grammar specifies that these are "astrings", and an astring + can be a literal. A literal, in turn can contain any 8-bit + character, and clients must allow users to enter all 8-bit characters + here, and must pass them, unchanged, to the server (being careful to + send them as literals when necessary). In particular, some server + configurations use "@" in user names, and some clients do not allow + that character to be entered; this creates a severe interoperability + problem. + +3.4.3. UIDs and UIDVALIDITY + + Servers that support existing back-end mail stores often have no good + place to save UIDs for messages. Often the existing mail store will + not have the concept of UIDs in the sense that IMAP has: strictly + increasing, never re-issued, 32-bit integers. Some servers solve + this by storing the UIDs in a place that's accessible to end users, + allowing for the possibility that the users will delete them. Others + solve it by re-assigning UIDs every time a mailbox is selected. + + The server should maintain UIDs permanently for all messages if it + can. If that's not possible, the server must change the UIDVALIDITY + value for the mailbox whenever any of the UIDs may have become + invalid. Clients must recognize that the UIDVALIDITY has changed and + must respond to that condition by throwing away any information that + they have saved about UIDs in that mailbox. There have been many + problems in this area when clients have failed to do this; in the + worst case it will result in loss of mail when a client deletes the + + + +Leiba Informational [Page 12] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + + wrong piece of mail by using a stale UID. + + It seems to be a common misunderstanding that "the UIDVALIDITY and + the UID, taken together, form a 64-bit identifier that uniquely + identifies a message on a server". This is absolutely NOT TRUE. + There is no assurance that the UIDVALIDITY values of two mailboxes be + different, so the UIDVALIDITY in no way identifies a mailbox. The + ONLY purpose of UIDVALIDITY is, as its name indicates, to give the + client a way to check the validity of the UIDs it has cached. While + it is a valid implementation choice to put these values together to + make a 64-bit identifier for the message, the important concept here + is that UIDs are not unique between mailboxes; they are only unique + WITHIN a given mailbox. + + Some server implementations have attempted to make UIDs unique across + the entire server. This is inadvisable, in that it limits the life + of UIDs unnecessarily. The UID is a 32-bit number and will run out + in reasonably finite time if it's global across the server. If you + assign UIDs sequentially in one mailbox, you will not have to start + re-using them until you have had, at one time or another, 2**32 + different messages in that mailbox. In the global case, you will + have to reuse them once you have had, at one time or another, 2**32 + different messages in the entire mail store. Suppose your server has + around 8000 users registered (2**13). That gives an average of 2**19 + UIDs per user. Suppose each user gets 32 messages (2**5) per day. + That gives you 2**14 days (16000+ days = about 45 years) before you + run out. That may seem like enough, but multiply the usage just a + little (a lot of spam, a lot of mailing list subscriptions, more + users) and you limit yourself too much. + + What's worse is that if you have to wrap the UIDs, and, thus, you + have to change UIDVALIDITY and invalidate the UIDs in the mailbox, + you have to do it for EVERY mailbox in the system, since they all + share the same UID pool. If you assign UIDs per mailbox and you have + a problem, you only have to kill the UIDs for that one mailbox. + + Under extreme circumstances (and this is extreme, indeed), the server + may have to invalidate UIDs while a mailbox is in use by a client - + that is, the UIDs that the client knows about in its active mailbox + are no longer valid. In that case, the server must immediately + change the UIDVALIDITY and must communicate this to the client. The + server may do this by sending an unsolicited UIDVALIDITY message, in + the same form as in response to the SELECT command. Clients must be + prepared to handle such a message and the possibly coincident failure + of the command in process. For example: + + + + + + +Leiba Informational [Page 13] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + + C: 032 UID STORE 382 +Flags.silent \Deleted + S: * OK [UIDVALIDITY 12345] New UIDVALIDITY value! + S: 032 NO UID command rejected because UIDVALIDITY changed! + C: ...invalidates local information and re-fetches... + C: 033 FETCH 1:* UID + ...etc... + + At the time of the writing of this document, the only server known to + do this does so only under the following condition: the client + selects INBOX, but there is not yet a physical INBOX file created. + Nonetheless, the SELECT succeeds, exporting an empty INBOX with a + temporary UIDVALIDITY of 1. While the INBOX remains selected, mail + is delivered to the user, which creates the real INBOX file and + assigns a permanent UIDVALIDITY (that is likely not to be 1). The + server reports the change of UIDVALIDITY, but as there were no + messages before, so no UIDs have actually changed, all the client + must do is accept the change in UIDVALIDITY. + + Alternatively, a server may force the client to re-select the + mailbox, at which time it will obtain a new UIDVALIDITY value. To do + this, the server closes this client session (see "Severed + Connections" above) and the client then reconnects and gets back in + synch. Clients must be prepared for either of these behaviours. + + We do not know of, nor do we anticipate the future existance of, a + server that changes UIDVALIDITY while there are existing messages, + but clients must be prepared to handle this eventuality. + +3.4.4. FETCH Responses + + When a client asks for certain information in a FETCH command, the + server may return the requested information in any order, not + necessarily in the order that it was requested. Further, the server + may return the information in separate FETCH responses and may also + return information that was not explicitly requested (to reflect to + the client changes in the state of the subject message). Some + examples: + + C: 001 FETCH 1 UID FLAGS INTERNALDATE + S: * 5 FETCH (FLAGS (\Deleted)) + S: * 1 FETCH (FLAGS (\Seen) INTERNALDATE "..." UID 345) + S: 001 OK done + + (In this case, the responses are in a different order. Also, the + server returned a flag update for message 5, which wasn't part of the + client's request.) + + + + + +Leiba Informational [Page 14] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + + C: 002 FETCH 2 UID FLAGS INTERNALDATE + S: * 2 FETCH (INTERNALDATE "...") + S: * 2 FETCH (UID 399) + S: * 2 FETCH (FLAGS ()) + S: 002 OK done + + (In this case, the responses are in a different order and were + returned in separate responses.) + + C: 003 FETCH 2 BODY[1] + S: * 2 FETCH (FLAGS (\Seen) BODY[1] {14} + S: Hello world! + S: ) + S: 003 OK done + + (In this case, the FLAGS response was added by the server, since + fetching the body part caused the server to set the \Seen flag.) + + Because of this characteristic a client must be ready to receive any + FETCH response at any time and should use that information to update + its local information about the message to which the FETCH response + refers. A client must not assume that any FETCH responses will come + in any particular order, or even that any will come at all. If after + receiving the tagged response for a FETCH command the client finds + that it did not get all of the information requested, the client + should send a NOOP command to the server to ensure that the server + has an opportunity to send any pending EXPUNGE responses to the + client (see [RFC-2180]). + +3.4.5. RFC822.SIZE + + Some back-end mail stores keep the mail in a canonical form, rather + than retaining the original MIME format of the messages. This means + that the server must reassemble the message to produce a MIME stream + when a client does a fetch such as RFC822 or BODY[], requesting the + entire message. It also may mean that the server has no convenient + way to know the RFC822.SIZE of the message. Often, such a server + will actually have to build the MIME stream to compute the size, only + to throw the stream away and report the size to the client. + + When this is the case, some servers have chosen to estimate the size, + rather than to compute it precisely. Such an estimate allows the + client to display an approximate size to the user and to use the + estimate in flood control considerations (q.v.), but requires that + the client not use the size for things such as allocation of buffers, + because those buffers might then be too small to hold the actual MIME + stream. Instead, a client should use the size that's returned in the + literal when you fetch the data. + + + +Leiba Informational [Page 15] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + + The protocol requires that the RFC822.SIZE value returned by the + server be EXACT. Estimating the size is a protocol violation, and + server designers must be aware that, despite the performance savings + they might realize in using an estimate, this practice will cause + some clients to fail in various ways. If possible, the server should + compute the RFC822.SIZE for a particular message once, and then save + it for later retrieval. If that's not possible, the server must + compute the value exactly every time. Incorrect estimates do cause + severe interoperability problems with some clients. + +3.4.6. Expunged Messages + + If the server allows multiple connections to the same mailbox, it is + often possible for messages to be expunged in one client unbeknownst + to another client. Since the server is not allowed to tell the + client about these expunged messages in response to a FETCH command, + the server may have to deal with the issue of how to return + information about an expunged message. There was extensive + discussion about this issue, and the results of that discussion are + summarized in [RFC-2180]. See that reference for a detailed + explanation and for recommendations. + +3.4.7. The Namespace Issue + + Namespaces are a very muddy area in IMAP4 implementation right now + (see [NAMESPACE] for a proposal to clear the water a bit). Until the + issue is resolved, the important thing for client developers to + understand is that some servers provide access through IMAP to more + than just the user's personal mailboxes, and, in fact, the user's + personal mailboxes may be "hidden" somewhere in the user's default + hierarchy. The client, therefore, should provide a setting wherein + the user can specify a prefix to be used when accessing mailboxes. If + the user's mailboxes are all in "~/mail/", for instance, then the + user can put that string in the prefix. The client would then put + the prefix in front of any name pattern in the LIST and LSUB + commands: + + C: 001 LIST "" ~/mail/% + + (See also "Reference Names in the LIST Command" below.) + +3.4.8. Creating Special-Use Mailboxes + + It may seem at first that this is part of the namespace issue; it is + not, and is only indirectly related to it. A number of clients like + to create special-use mailboxes with particular names. Most + commonly, clients with a "trash folder" model of message deletion + want to create a mailbox with the name "Trash" or "Deleted". Some + + + +Leiba Informational [Page 16] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + + clients want to create a "Drafts" mailbox, an "Outbox" mailbox, or a + "Sent Mail" mailbox. And so on. There are two major + interoperability problems with this practice: + + 1. different clients may use different names for mailboxes with + similar functions (such as "Trash" and "Deleted"), or may manage + the same mailboxes in different ways, causing problems if a user + switches between clients and + 2. there is no guarantee that the server will allow the creation of + the desired mailbox. + + The client developer is, therefore, well advised to consider + carefully the creation of any special-use mailboxes on the server, + and, further, the client must not require such mailbox creation - + that is, if you do decide to do this, you must handle gracefully the + failure of the CREATE command and behave reasonably when your + special-use mailboxes do not exist and can not be created. + + In addition, the client developer should provide a convenient way for + the user to select the names for any special-use mailboxes, allowing + the user to make these names the same in all clients used and to put + them where the user wants them. + +3.4.9. Reference Names in the LIST Command + + Many implementers of both clients and servers are confused by the + "reference name" on the LIST command. The reference name is intended + to be used in much the way a "cd" (change directory) command is used + on Unix, PC DOS, Windows, and OS/2 systems. That is, the mailbox + name is interpreted in much the same way as a file of that name would + be found if one had done a "cd" command into the directory specified + by the reference name. For example, in Unix we have the following: + + > cd /u/jones/junk + > vi banana [file is "/u/jones/junk/banana"] + > vi stuff/banana [file is "/u/jones/junk/stuff/banana"] + > vi /etc/hosts [file is "/etc/hosts"] + + In the past, there have been several interoperability problems with + this. First, while some IMAP servers are built on Unix or PC file + systems, many others are not, and the file system semantics do not + make sense in those configurations. Second, while some IMAP servers + expose the underlying file system to the clients, others allow access + only to the user's personal mailboxes, or to some other limited set + of files, making such file-system-like semantics less meaningful. + Third, because the IMAP spec leaves the interpretation of the + reference name as "implementation-dependent", in the past the various + server implementations handled it in vastly differing ways. + + + +Leiba Informational [Page 17] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + + The following recommendations are the result of significant + operational experience, and are intended to maximize + interoperability. + + Server implementations must implement the reference argument in a way + that matches the intended "change directory" operation as closely as + possible. As a minimum implementation, the reference argument may be + prepended to the mailbox name (while suppressing double delimiters; + see the next paragraph). Even servers that do not provide a way to + break out of the current hierarchy (see "breakout facility" below) + must provide a reasonable implementation of the reference argument, + as described here, so that they will interoperate with clients that + use it. + + Server implementations that prepend the reference argument to the + mailbox name should insert a hierarchy delimiter between them, and + must not insert a second if one is already present: + + C: A001 LIST ABC DEF + S: * LIST () "/" ABC/DEF <=== should do this + S: A001 OK done + + C: A002 LIST ABC/ /DEF + S: * LIST () "/" ABC//DEF <=== must not do this + S: A002 OK done + + On clients, the reference argument is chiefly used to implement a + "breakout facility", wherein the user may directly access a mailbox + outside the "current directory" hierarchy. Client implementations + should have an operational mode that does not use the reference + argument. This is to interoperate with older servers that did not + implement the reference argument properly. While it's a good idea to + give the user access to a breakout facility, clients that do not + intend to do so should not use the reference argument at all. + + Client implementations should always place a trailing hierarchy + delimiter on the reference argument. This is because some servers + prepend the reference argument to the mailbox name without inserting + a hierarchy delimiter, while others do insert a hierarchy delimiter + if one is not already present. A client that puts the delimiter in + will work with both varieties of server. + + Client implementations that implement a breakout facility should + allow the user to choose whether or not to use a leading hierarchy + delimiter on the mailbox argument. This is because the handling of a + leading mailbox hierarchy delimiter also varies from server to + server, and even between different mailstores on the same server. In + some cases, a leading hierarchy delimiter means "discard the + + + +Leiba Informational [Page 18] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + + reference argument" (implementing the intended breakout facility), + thus: + + C: A001 LIST ABC/ /DEF + S: * LIST () "/" /DEF + S: A001 OK done + + In other cases, however, the two are catenated and the extra + hierarchy delimiter is discarded, thus: + + C: A001 LIST ABC/ /DEF + S: * LIST () "/" ABC/DEF + S: A001 OK done + + Client implementations must not assume that the server supports a + breakout facility, but may provide a way for the user to use one if + it is available. Any breakout facility should be exported to the + user interface. Note that there may be other "breakout" characters + besides the hierarchy delimiter (for instance, UNIX filesystem + servers are likely to use a leading "~" as well), and that their + interpretation is server-dependent. + +3.4.10. Mailbox Hierarchy Delimiters + + The server's selection of what to use as a mailbox hierarchy + delimiter is a difficult one, involving several issues: What + characters do users expect to see? What characters can they enter + for a hierarchy delimiter if it is desired (or required) that the + user enter it? What character can be used for the hierarchy + delimiter, noting that the chosen character can not otherwise be used + in the mailbox name? + + Because some interfaces show users the hierarchy delimiters or allow + users to enter qualified mailbox names containing them, server + implementations should use delimiter characters that users generally + expect to see as name separators. The most common characters used + for this are "/" (as in Unix file names), "\" (as in OS/2 and Windows + file names), and "." (as in news groups). There is little to choose + among these apart from what users may expect or what is dictated by + the underlying file system, if any. One consideration about using + "\" is that it's also a special character in the IMAP protocol. While + the use of other hierarchy delimiter characters is permissible, A + DESIGNER IS WELL ADVISED TO STAY WITH ONE FROM THIS SET unless the + server is intended for special purposes only. Implementers might be + thinking about using characters such as "-", "_", ";", "&", "#", "@", + and "!", but they should be aware of the surprise to the user as well + as of the effect on URLs and other external specifications (since + some of these characters have special meanings there). Also, a + + + +Leiba Informational [Page 19] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + + server that uses "\" (and clients of such a server) must remember to + escape that character in quoted strings or to send literals instead. + Literals are recommended over escaped characters in quoted strings in + order to maintain compatibility with older IMAP versions that did not + allow escaped characters in quoted strings (but check the grammar to + see where literals are allowed): + + C: 001 LIST "" {13} + S: + send literal + C: this\%\%\%\h* + S: * LIST () "\\" {27} + S: this\is\a\mailbox\hierarchy + S: 001 OK LIST complete + + In any case, a server should not use normal alpha-numeric characters + (such as "X" or "0") as delimiters; a user would be very surprised to + find that "EXPENDITURES" actually represented a two-level hierarchy. + And a server should not use characters that are non-printable or + difficult or impossible to enter on a standard US keyboard. Control + characters, box-drawing characters, and characters from non-US + alphabets fit into this category. Their use presents + interoperability problems that are best avoided. + + The UTF-7 encoding of mailbox names also raises questions about what + to do with the hierarchy delimiters in encoded names: do we encode + each hierarchy level and separate them with delimiters, or do we + encode the fully qualified name, delimiters and all? The answer for + IMAP is the former: encode each hierarchy level separately, and + insert delimiters between. This makes it particularly important not + to use as a hierarchy delimiter a character that might cause + confusion with IMAP's modified UTF-7 [UTF-7 and RFC-2060] encoding. + + To repeat: a server should use "/", "\", or "." as its hierarchy + delimiter. The use of any other character is likely to cause + problems and is STRONGLY DISCOURAGED. + +3.4.11. ALERT Response Codes + + The protocol spec is very clear on the matter of what to do with + ALERT response codes, and yet there are many clients that violate it + so it needs to be said anyway: "The human-readable text contains a + special alert that must be presented to the user in a fashion that + calls the user's attention to the message." That should be clear + enough, but I'll repeat it here: Clients must present ALERT text + clearly to the user. + + + + + + +Leiba Informational [Page 20] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + +3.4.12. Deleting Mailboxes + + The protocol does not guarantee that a client may delete a mailbox + that is not empty, though on some servers it is permissible and is, + in fact, much faster than the alternative or deleting all the + messages from the client. If the client chooses to try to take + advantage of this possibility it must be prepared to use the other + method in the even that the more convenient one fails. Further, a + client should not try to delete the mailbox that it has selected, but + should first close that mailbox; some servers do not permit the + deletion of the selected mailbox. + + That said, a server should permit the deletion of a non-empty + mailbox; there's little reason to pass this work on to the client. + Moreover, forbidding this prevents the deletion of a mailbox that for + some reason can not be opened or expunged, leading to possible + denial-of-service problems. + + Example: + + [User tells the client to delete mailbox BANANA, which is + currently selected...] + C: 008 CLOSE + S: 008 OK done + C: 009 DELETE BANANA + S: 009 NO Delete failed; mailbox is not empty. + C: 010 SELECT BANANA + S: * ... untagged SELECT responses + S: 010 OK done + C: 011 STORE 1:* +FLAGS.SILENT \DELETED + S: 011 OK done + C: 012 CLOSE + S: 012 OK done + C: 013 DELETE BANANA + S: 013 OK done + +3.5. A Word About Testing + + Since the whole point of IMAP is interoperability, and since + interoperability can not be tested in a vacuum, the final + recommendation of this treatise is, "Test against EVERYTHING." Test + your client against every server you can get an account on. Test + your server with every client you can get your hands on. Many + clients make limited test versions available on the Web for the + downloading. Many server owners will give serious client developers + guest accounts for testing. Contact them and ask. NEVER assume that + because your client works with one or two servers, or because your + server does fine with one or two clients, you will interoperate well + + + +Leiba Informational [Page 21] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + + in general. + + In particular, in addition to everything else, be sure to test + against the reference implementations: the PINE client, the + University of Washington server, and the Cyrus server. + + See the following URLs on the web for more information here: + + IMAP Products and Sources: http://www.imap.org/products.html + IMC MailConnect: http://www.imc.org/imc-mailconnect + +4. Security Considerations + + This document describes behaviour of clients and servers that use the + IMAP4 protocol, and as such, has the same security considerations as + described in [RFC-2060]. + +5. References + + [RFC-2060] Crispin, M., "Internet Message Access Protocol - Version + 4rev1", RFC 2060, December 1996. + + [RFC-2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC-2180] Gahrns, M., "IMAP4 Multi-Accessed Mailbox Practice", RFC + 2180, July 1997. + + [UTF-8] Yergeau, F., " UTF-8, a transformation format of Unicode + and ISO 10646", RFC 2044, October 1996. + + [UTF-7] Goldsmith, D. and M. Davis, "UTF-7, a Mail-Safe + Transformation Format of Unicode", RFC 2152, May 1997. + + [NAMESPACE] Gahrns, M. and C. Newman, "IMAP4 Namespace", Work in + Progress. + +6. Author's Address + + Barry Leiba + IBM T.J. Watson Research Center + 30 Saw Mill River Road + Hawthorne, NY 10532 + + Phone: 1-914-784-7941 + EMail: leiba@watson.ibm.com + + + + + +Leiba Informational [Page 22] + +RFC 2683 IMAP4 Implementation Recommendations September 1999 + + +7. Full Copyright Statement + + Copyright (C) The Internet Society (1999). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Leiba Informational [Page 23] + diff --git a/imap/docs/rfc/rfc2971.txt b/imap/docs/rfc/rfc2971.txt new file mode 100644 index 00000000..9e7264dc --- /dev/null +++ b/imap/docs/rfc/rfc2971.txt @@ -0,0 +1,451 @@ + + + + + + +Network Working Group T. Showalter +Request for Comments: 2971 Mirapoint, Inc. +Category: Standards Track October 2000 + + + IMAP4 ID extension + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2000). All Rights Reserved. + +Abstract + + The ID extension to the Internet Message Access Protocol - Version + 4rev1 (IMAP4rev1) protocol allows the server and client to exchange + identification information on their implementation in order to make + bug reports and usage statistics more complete. + +1. Introduction + + The IMAP4rev1 protocol described in [IMAP4rev1] provides a method for + accessing remote mail stores, but it provides no facility to + advertise what program a client or server uses to provide service. + This makes it difficult for implementors to get complete bug reports + from users, as it is frequently difficult to know what client or + server is in use. + + Additionally, some sites may wish to assemble usage statistics based + on what clients are used, but in an an environment where users are + permitted to obtain and maintain their own clients this is difficult + to accomplish. + + The ID command provides a facility to advertise information on what + programs are being used along with contact information (should bugs + ever occur). + + + + + + + + +Showalter Standards Track [Page 1] + +RFC 2971 IMAP4 ID extension October 2000 + + +2. Conventions Used in this Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [KEYWORDS]. + + The conventions used in this document are the same as specified in + [IMAP4rev1]. In examples, "C:" and "S:" indicate lines sent by the + client and server respectively. Line breaks have been inserted for + readability. + +3. Specification + + The sole purpose of the ID extension is to enable clients and servers + to exchange information on their implementations for the purposes of + statistical analysis and problem determination. + + This information is be submitted to a server by any client wishing to + provide information for statistical purposes, provided the server + advertises its willingness to take the information with the atom "ID" + included in the list of capabilities returned by the CAPABILITY + command. + + Implementations MUST NOT make operational changes based on the data + sent as part of the ID command or response. The ID command is for + human consumption only, and is not to be used in improving the + performance of clients or servers. + + This includes, but is not limited to, the following: + + Servers MUST NOT attempt to work around client bugs by using + information from the ID command. Clients MUST NOT attempt to work + around server bugs based on the ID response. + + Servers MUST NOT provide features to a client or otherwise + optimize for a particular client by using information from the ID + command. Clients MUST NOT provide features to a server or + otherwise optimize for a particular server based on the ID + response. + + Servers MUST NOT deny access to or refuse service for a client + based on information from the ID command. Clients MUST NOT refuse + to operate or limit their operation with a server based on the ID + response. + + + + + + + +Showalter Standards Track [Page 2] + +RFC 2971 IMAP4 ID extension October 2000 + + + Rationale: It is imperative that this extension not supplant IMAP's + CAPABILITY mechanism with a ad-hoc approach where implementations + guess each other's features based on who they claim to be. + + Implementations MUST NOT send false information in an ID command. + + Implementations MAY send less information than they have available or + no information at all. Such behavior may be useful to preserve user + privacy. See Security Considerations, section 7. + +3.1. ID Command + + Arguments: client parameter list or NIL + + Responses: OPTIONAL untagged response: ID + + Result: OK identification information accepted + BAD command unknown or arguments invalid + + Implementation identification information is sent by the client with + the ID command. + + This command is valid in any state. + + The information sent is in the form of a list of field/value pairs. + Fields are permitted to be any IMAP4 string, and values are permitted + to be any IMAP4 string or NIL. A value of NIL indicates that the + client can not or will not specify this information. The client may + also send NIL instead of the list, indicating that it wants to send + no information, but would still accept a server response. + + The available fields are defined in section 3.3. + + Example: C: a023 ID ("name" "sodr" "version" "19.34" "vendor" + "Pink Floyd Music Limited") + S: * ID NIL + S: a023 OK ID completed + +3.2. ID Response + + Contents: server parameter list + + In response to an ID command issued by the client, the server replies + with a tagged response containing information on its implementation. + The format is the same as the client list. + + + + + + +Showalter Standards Track [Page 3] + +RFC 2971 IMAP4 ID extension October 2000 + + + Example: C: a042 ID NIL + S: * ID ("name" "Cyrus" "version" "1.5" "os" "sunos" + "os-version" "5.5" "support-url" + "mailto:cyrus-bugs+@andrew.cmu.edu") + S: a042 OK ID command completed + + A server MUST send a tagged ID response to an ID command. However, a + server MAY send NIL in place of the list. + +3.3. Defined Field Values + + Any string may be sent as a field, but the following are defined to + describe certain values that might be sent. Implementations are free + to send none, any, or all of these. Strings are not case-sensitive. + Field strings MUST NOT be longer than 30 octets. Value strings MUST + NOT be longer than 1024 octets. Implementations MUST NOT send more + than 30 field-value pairs. + + name Name of the program + version Version number of the program + os Name of the operating system + os-version Version of the operating system + vendor Vendor of the client/server + support-url URL to contact for support + address Postal address of contact/vendor + date Date program was released, specified as a date-time + in IMAP4rev1 + command Command used to start the program + arguments Arguments supplied on the command line, if any + if any + environment Description of environment, i.e., UNIX environment + variables or Windows registry settings + + Implementations MUST NOT use contact information to submit automatic + bug reports. Implementations may include information from an ID + response in a report automatically prepared, but are prohibited from + sending the report without user authorization. + + It is preferable to find the name and version of the underlying + operating system at runtime in cases where this is possible. + + Information sent via an ID response may violate user privacy. See + Security Considerations, section 7. + + Implementations MUST NOT send the same field name more than once. + + + + + + +Showalter Standards Track [Page 4] + +RFC 2971 IMAP4 ID extension October 2000 + + +4. Formal Syntax + + This syntax is intended to augment the grammar specified in + [IMAP4rev1] in order to provide for the ID command. This + specification uses the augmented Backus-Naur Form (BNF) notation as + used in [IMAP4rev1]. + + command_any ::= "CAPABILITY" / "LOGOUT" / "NOOP" / x_command / id + ;; adds id command to command_any in [IMAP4rev1] + + id ::= "ID" SPACE id_params_list + + id_response ::= "ID" SPACE id_params_list + + id_params_list ::= "(" #(string SPACE nstring) ")" / nil + ;; list of field value pairs + + response_data ::= "*" SPACE (resp_cond_state / resp_cond_bye / + mailbox_data / message_data / capability_data / id_response) + +5. Use of the ID extension with Firewalls and Other Intermediaries + + There exist proxies, firewalls, and other intermediary systems that + can intercept an IMAP session and make changes to the data exchanged + in the session. Such intermediaries are not anticipated by the IMAP4 + protocol design and are not within the scope of the IMAP4 standard. + However, in order for the ID command to be useful in the presence of + such intermediaries, those intermediaries need to take special note + of the ID command and response. In particular, if an intermediary + changes any part of the IMAP session it must also change the ID + command to advertise its presence. + + A firewall MAY act to block transmission of specific information + fields in the ID command and response that it believes reveal + information that could expose a security vulnerability. However, a + firewall SHOULD NOT disable the extension, when present, entirely, + and SHOULD NOT unconditionally remove either the client or server + list. + + Finally, it should be noted that a firewall, when handling a + CAPABILITY response, MUST NOT allow the names of extensions to be + returned to the client that the firewall has no knowledge of. + + + + + + + + + +Showalter Standards Track [Page 5] + +RFC 2971 IMAP4 ID extension October 2000 + + +6. References + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", RFC 2119, March 1997. + + [IMAP4rev1] Crispin, M., "Internet Message Access Protocol - Version + 4rev1", RFC 2060, October 1996. + + [RFC-822] Crocker, D., "Standard for the Format of ARPA Internet + Text Messages", STD 11, RFC 822, August 1982. + +7. Security Considerations + + This extension has the danger of violating the privacy of users if + misused. Clients and servers should notify users that they implement + and enable the ID command. + + It is highly desirable that implementations provide a method of + disabling ID support, perhaps by not sending ID at all, or by sending + NIL as the argument to the ID command or response. + + Implementors must exercise extreme care in adding fields sent as part + of an ID command or response. Some fields, including a processor ID + number, Ethernet address, or other unique (or mostly unique) + identifier allow tracking of users in ways that violate user privacy + expectations. + + Having implementation information of a given client or server may + make it easier for an attacker to gain unauthorized access due to + security holes. + + Since this command includes arbitrary data and does not require the + user to authenticate, server implementations are cautioned to guard + against an attacker sending arbitrary garbage data in order to fill + up the ID log. In particular, if a server naively logs each ID + command to disk without inspecting it, an attacker can simply fire up + thousands of connections and send a few kilobytes of random data. + Servers have to guard against this. Methods include truncating + abnormally large responses; collating responses by storing only a + single copy, then keeping a counter of the number of times that + response has been seen; keeping only particularly interesting parts + of responses; and only logging responses of users who actually log + in. + + Security is affected by firewalls which modify the IMAP protocol + stream; see section 5, Use of the ID Extension with Firewalls and + Other Intermediaries, for more information. + + + + +Showalter Standards Track [Page 6] + +RFC 2971 IMAP4 ID extension October 2000 + + +8. Author's Address + + Tim Showalter + Mirapoint, Inc. + 909 Hermosa Ct. + Sunnyvale, CA 94095 + + EMail: tjs@mirapoint.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Showalter Standards Track [Page 7] + +RFC 2971 IMAP4 ID extension October 2000 + + +9. Full Copyright Statement + + Copyright (C) The Internet Society (2000). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Showalter Standards Track [Page 8] + diff --git a/imap/docs/rfc/rfc3348.txt b/imap/docs/rfc/rfc3348.txt new file mode 100644 index 00000000..500871cc --- /dev/null +++ b/imap/docs/rfc/rfc3348.txt @@ -0,0 +1,339 @@ + + + + + + +Network Working Group M. Gahrns +Request for Comments: 3348 R. Cheng +Category: Informational Microsoft + July 2002 + + + The Internet Message Action Protocol (IMAP4) + Child Mailbox Extension + +Status of this Memo + + This memo provides information for the Internet community. It does + not specify an Internet standard of any kind. Distribution of this + memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2002). All Rights Reserved. + +Abstract + + The Internet Message Action Protocol (IMAP4) CHILDREN extension + provides a mechanism for a client to efficiently determine if a + particular mailbox has children, without issuing a LIST "" * or a + LIST "" % for each mailbox. + +1. Conventions used in this document + + In examples, "C:" and "S:" indicate lines sent by the client and + server respectively. If such lines are wrapped without a new "C:" or + "S:" label, then the wrapping is for editorial clarity and is not + part of the command. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC-2119]. + +2. Introduction and Overview + + Many IMAP4 [RFC-2060] clients present to the user a hierarchical view + of the mailboxes that a user has access to. Rather than initially + presenting to the user the entire mailbox hierarchy, it is often + preferable to show to the user a collapsed outline list of the + mailbox hierarchy (particularly if there is a large number of + mailboxes). The user can then expand the collapsed outline hierarchy + as needed. It is common to include within the collapsed hierarchy a + + + + + +Gahrns, et al. Informational [Page 1] + +RFC 3348 IMAP4 Child Mailbox Extension July 2002 + + + visual clue (such as a "+") to indicate that there are child + mailboxes under a particular mailbox. When the visual clue is + clicked the hierarchy list is expanded to show the child mailboxes. + + Several IMAP vendors implemented this proposal, and it is proposed to + document this behavior and functionality as an Informational RFC. + + There is interest in addressing the general extensibility of the IMAP + LIST command through an IMAP LIST Extension draft. Similar + functionality to the \HasChildren and \HasNoChildren flags could be + incorporated into this new LIST Extension. It is proposed that the + more general LIST Extension draft proceed on the standards track with + this proposal being relegated to informational status only. + + If the functionality of the \HasChildren and \HasNoChildren flags + were incorporated into a more general LIST extension, this would have + the advantage that a client could then have the opportunity to + request whether or not the server should return this information. + This would be an advantage over the current draft for servers where + this information is expensive to compute, since the server would only + need to compute the information when it knew that the client + requesting the information was able to consume it. + +3. Requirements + + IMAP4 servers that support this extension MUST list the keyword + CHILDREN in their CAPABILITY response. + + The CHILDREN extension defines two new attributes that MAY be + returned within a LIST response. + + \HasChildren - The presence of this attribute indicates that the + mailbox has child mailboxes. + + Servers SHOULD NOT return \HasChildren if child mailboxes exist, but + none will be displayed to the current user in a LIST response (as + should be the case where child mailboxes exist, but a client does not + have permissions to access them.) In this case, \HasNoChildren + SHOULD be used. + + In many cases, however, a server may not be able to efficiently + compute whether a user has access to all child mailboxes, or multiple + users may be accessing the same account and simultaneously changing + the mailbox hierarchy. As such a client MUST be prepared to accept + the \HasChildren attribute as a hint. That is, a mailbox MAY be + flagged with the \HasChildren attribute, but no child mailboxes will + appear in a subsequent LIST response. + + + + +Gahrns, et al. Informational [Page 2] + +RFC 3348 IMAP4 Child Mailbox Extension July 2002 + + + Example 3.1: + ============ + + /*** Consider a server that has the following mailbox hierarchy: + + INBOX + ITEM_1 + ITEM_1A + ITEM_2 + TOP_SECRET + + Where INBOX, ITEM_1 and ITEM_2 are top level mailboxes. ITEM_1A is a + child mailbox of ITEM_1 and TOP_SECRET is a child mailbox of ITEM_2 + that the currently logged on user does NOT have access to. + + Note that in this case, the server is not able to efficiently compute + access rights to child mailboxes and responds with a \HasChildren + attribute for mailbox ITEM_2, even though ITEM_2/TOP_SECRET does not + appear in the list response. ***/ + + C: A001 LIST "" * + S: * LIST (\HasNoChildren) "/" INBOX + S: * LIST (\HasChildren) "/" ITEM_1 + S: * LIST (\HasNoChildren) "/" ITEM_1/ITEM_1A + S: * LIST (\HasChildren) "/" ITEM_2 + S: A001 OK LIST Completed + + \HasNoChildren - The presence of this attribute indicates that the + mailbox has NO child mailboxes that are accessible to the currently + authenticated user. If a mailbox has the \Noinferiors attribute, the + \HasNoChildren attribute is redundant and SHOULD be omitted in the + LIST response. + + In some instances a server that supports the CHILDREN extension MAY + NOT be able to determine whether a mailbox has children. For example + it may have difficulty determining whether there are child mailboxes + when LISTing mailboxes while operating in a particular namespace. + + In these cases, a server MAY exclude both the \HasChildren and + \HasNoChildren attributes in the LIST response. As such, a client + can not make any assumptions about whether a mailbox has children + based upon the absence of a single attribute. + + It is an error for the server to return both a \HasChildren and a + \HasNoChildren attribute in a LIST response. + + + + + + +Gahrns, et al. Informational [Page 3] + +RFC 3348 IMAP4 Child Mailbox Extension July 2002 + + + It is an error for the server to return both a \HasChildren and a + \NoInferiors attribute in a LIST response. + + Note: the \HasNoChildren attribute should not be confused with the + IMAP4 [RFC-2060] defined attribute \Noinferiors which indicates that + no child mailboxes exist now and none can be created in the future. + + The \HasChildren and \HasNoChildren attributes might not be returned + in response to a LSUB response. Many servers maintain a simple + mailbox subscription list that is not updated when the underlying + mailbox structure is changed. A client MUST NOT assume that + hierarchy information will be maintained in the subscription list. + + RLIST is a command defined in [RFC-2193] that includes in a LIST + response mailboxes that are accessible only via referral. That is, a + client must explicitly issue an RLIST command to see a list of these + mailboxes. Thus in the case where a mailbox has child mailboxes that + are available only via referral, the mailboxes would appear as + \HasNoChildren in response to the LIST command, and \HasChildren in + response to the RLIST command. + +5. Formal Syntax + + The following syntax specification uses the augmented Backus-Naur + Form (BNF) as described in [ABNF]. + + Two new mailbox attributes are defined as flag_extensions to the + IMAP4 mailbox_list response: + + HasChildren = "\HasChildren" + + HasNoChildren = "\HasNoChildren" + +6. Security Considerations + + This extension provides a client a more efficient means of + determining whether a particular mailbox has children. If a mailbox + has children, but the currently authenticated user does not have + access to any of them, the server SHOULD respond with a + \HasNoChildren attribute. In many cases, however, a server may not + be able to efficiently compute whether a user has access to all child + mailboxes. If such a server responds with a \HasChildren attribute, + when in fact the currently authenticated user does not have access to + any child mailboxes, potentially more information is conveyed about + the mailbox than intended. A server designed with such levels of + security in mind SHOULD NOT attach the \HasChildren attribute to a + mailbox unless the server is certain that the user has access to at + least one of the child mailboxes. + + + +Gahrns, et al. Informational [Page 4] + +RFC 3348 IMAP4 Child Mailbox Extension July 2002 + + +7. References + + [RFC-2060] Crispin, M., "Internet Message Access Protocol - Version + 4rev1", RFC 2060, December 1996. + + [RFC-2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC-2234] Crocker, D. and P. Overell, Editors, "Augmented BNF for + Syntax Specifications: ABNF", RFC 2234, November 1997. + + [RFC-2193] Gahrns, M., "IMAP4 Mailbox Referrals", RFC 2193, September + 1997. + +8. Acknowledgments + + The authors would like to thank the participants of several IMC Mail + Connect events for their input when this idea was originally + presented and refined. + +9. Author's Address + + Mike Gahrns + Microsoft + One Microsoft Way + Redmond, WA, 98052 + Phone: (425) 936-9833 + EMail: mikega@microsoft.com + + Raymond Cheng + Microsoft + One Microsoft Way + Redmond, WA, 98052 + Phone: (425) 703-4913 + EMail: raych@microsoft.com + + + + + + + + + + + + + + + + +Gahrns, et al. Informational [Page 5] + +RFC 3348 IMAP4 Child Mailbox Extension July 2002 + + +10. Full Copyright Statement + + Copyright (C) The Internet Society (2002). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Gahrns, et al. Informational [Page 6] + diff --git a/imap/docs/rfc/rfc3501.txt b/imap/docs/rfc/rfc3501.txt new file mode 100644 index 00000000..6f470dd1 --- /dev/null +++ b/imap/docs/rfc/rfc3501.txt @@ -0,0 +1,6052 @@ + + + + + + +Network Working Group M. Crispin +Request for Comments: 3501 University of Washington +Obsoletes: 2060 March 2003 +Category: Standards Track + + + INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1 + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2003). All Rights Reserved. + +Abstract + + The Internet Message Access Protocol, Version 4rev1 (IMAP4rev1) + allows a client to access and manipulate electronic mail messages on + a server. IMAP4rev1 permits manipulation of mailboxes (remote + message folders) in a way that is functionally equivalent to local + folders. IMAP4rev1 also provides the capability for an offline + client to resynchronize with the server. + + IMAP4rev1 includes operations for creating, deleting, and renaming + mailboxes, checking for new messages, permanently removing messages, + setting and clearing flags, RFC 2822 and RFC 2045 parsing, searching, + and selective fetching of message attributes, texts, and portions + thereof. Messages in IMAP4rev1 are accessed by the use of numbers. + These numbers are either message sequence numbers or unique + identifiers. + + IMAP4rev1 supports a single server. A mechanism for accessing + configuration information to support multiple IMAP4rev1 servers is + discussed in RFC 2244. + + IMAP4rev1 does not specify a means of posting mail; this function is + handled by a mail transfer protocol such as RFC 2821. + + + + + + + + +Crispin Standards Track [Page 1] + +RFC 3501 IMAPv4 March 2003 + + +Table of Contents + + IMAP4rev1 Protocol Specification ................................ 4 + 1. How to Read This Document ............................... 4 + 1.1. Organization of This Document ........................... 4 + 1.2. Conventions Used in This Document ....................... 4 + 1.3. Special Notes to Implementors ........................... 5 + 2. Protocol Overview ....................................... 6 + 2.1. Link Level .............................................. 6 + 2.2. Commands and Responses .................................. 6 + 2.2.1. Client Protocol Sender and Server Protocol Receiver ..... 6 + 2.2.2. Server Protocol Sender and Client Protocol Receiver ..... 7 + 2.3. Message Attributes ...................................... 8 + 2.3.1. Message Numbers ......................................... 8 + 2.3.1.1. Unique Identifier (UID) Message Attribute ....... 8 + 2.3.1.2. Message Sequence Number Message Attribute ....... 10 + 2.3.2. Flags Message Attribute ................................. 11 + 2.3.3. Internal Date Message Attribute ......................... 12 + 2.3.4. [RFC-2822] Size Message Attribute ....................... 12 + 2.3.5. Envelope Structure Message Attribute .................... 12 + 2.3.6. Body Structure Message Attribute ........................ 12 + 2.4. Message Texts ........................................... 13 + 3. State and Flow Diagram .................................. 13 + 3.1. Not Authenticated State ................................. 13 + 3.2. Authenticated State ..................................... 13 + 3.3. Selected State .......................................... 13 + 3.4. Logout State ............................................ 14 + 4. Data Formats ............................................ 16 + 4.1. Atom .................................................... 16 + 4.2. Number .................................................. 16 + 4.3. String .................................................. 16 + 4.3.1. 8-bit and Binary Strings ................................ 17 + 4.4. Parenthesized List ...................................... 17 + 4.5. NIL ..................................................... 17 + 5. Operational Considerations .............................. 18 + 5.1. Mailbox Naming .......................................... 18 + 5.1.1. Mailbox Hierarchy Naming ................................ 19 + 5.1.2. Mailbox Namespace Naming Convention ..................... 19 + 5.1.3. Mailbox International Naming Convention ................. 19 + 5.2. Mailbox Size and Message Status Updates ................. 21 + 5.3. Response when no Command in Progress .................... 21 + 5.4. Autologout Timer ........................................ 22 + 5.5. Multiple Commands in Progress ........................... 22 + 6. Client Commands ........................................ 23 + 6.1. Client Commands - Any State ............................ 24 + 6.1.1. CAPABILITY Command ..................................... 24 + 6.1.2. NOOP Command ........................................... 25 + 6.1.3. LOGOUT Command ......................................... 26 + + + +Crispin Standards Track [Page 2] + +RFC 3501 IMAPv4 March 2003 + + + 6.2. Client Commands - Not Authenticated State .............. 26 + 6.2.1. STARTTLS Command ....................................... 27 + 6.2.2. AUTHENTICATE Command ................................... 28 + 6.2.3. LOGIN Command .......................................... 30 + 6.3. Client Commands - Authenticated State .................. 31 + 6.3.1. SELECT Command ......................................... 32 + 6.3.2. EXAMINE Command ........................................ 34 + 6.3.3. CREATE Command ......................................... 34 + 6.3.4. DELETE Command ......................................... 35 + 6.3.5. RENAME Command ......................................... 37 + 6.3.6. SUBSCRIBE Command ...................................... 39 + 6.3.7. UNSUBSCRIBE Command .................................... 39 + 6.3.8. LIST Command ........................................... 40 + 6.3.9. LSUB Command ........................................... 43 + 6.3.10. STATUS Command ......................................... 44 + 6.3.11. APPEND Command ......................................... 46 + 6.4. Client Commands - Selected State ....................... 47 + 6.4.1. CHECK Command .......................................... 47 + 6.4.2. CLOSE Command .......................................... 48 + 6.4.3. EXPUNGE Command ........................................ 49 + 6.4.4. SEARCH Command ......................................... 49 + 6.4.5. FETCH Command .......................................... 54 + 6.4.6. STORE Command .......................................... 58 + 6.4.7. COPY Command ........................................... 59 + 6.4.8. UID Command ............................................ 60 + 6.5. Client Commands - Experimental/Expansion ............... 62 + 6.5.1. X<atom> Command ........................................ 62 + 7. Server Responses ....................................... 62 + 7.1. Server Responses - Status Responses .................... 63 + 7.1.1. OK Response ............................................ 65 + 7.1.2. NO Response ............................................ 66 + 7.1.3. BAD Response ........................................... 66 + 7.1.4. PREAUTH Response ....................................... 67 + 7.1.5. BYE Response ........................................... 67 + 7.2. Server Responses - Server and Mailbox Status ........... 68 + 7.2.1. CAPABILITY Response .................................... 68 + 7.2.2. LIST Response .......................................... 69 + 7.2.3. LSUB Response .......................................... 70 + 7.2.4 STATUS Response ........................................ 70 + 7.2.5. SEARCH Response ........................................ 71 + 7.2.6. FLAGS Response ......................................... 71 + 7.3. Server Responses - Mailbox Size ........................ 71 + 7.3.1. EXISTS Response ........................................ 71 + 7.3.2. RECENT Response ........................................ 72 + 7.4. Server Responses - Message Status ...................... 72 + 7.4.1. EXPUNGE Response ....................................... 72 + 7.4.2. FETCH Response ......................................... 73 + 7.5. Server Responses - Command Continuation Request ........ 79 + + + +Crispin Standards Track [Page 3] + +RFC 3501 IMAPv4 March 2003 + + + 8. Sample IMAP4rev1 connection ............................ 80 + 9. Formal Syntax .......................................... 81 + 10. Author's Note .......................................... 92 + 11. Security Considerations ................................ 92 + 11.1. STARTTLS Security Considerations ....................... 92 + 11.2. Other Security Considerations .......................... 93 + 12. IANA Considerations .................................... 94 + Appendices ..................................................... 95 + A. References ............................................. 95 + B. Changes from RFC 2060 .................................. 97 + C. Key Word Index ......................................... 103 + Author's Address ............................................... 107 + Full Copyright Statement ....................................... 108 + +IMAP4rev1 Protocol Specification + +1. How to Read This Document + +1.1. Organization of This Document + + This document is written from the point of view of the implementor of + an IMAP4rev1 client or server. Beyond the protocol overview in + section 2, it is not optimized for someone trying to understand the + operation of the protocol. The material in sections 3 through 5 + provides the general context and definitions with which IMAP4rev1 + operates. + + Sections 6, 7, and 9 describe the IMAP commands, responses, and + syntax, respectively. The relationships among these are such that it + is almost impossible to understand any of them separately. In + particular, do not attempt to deduce command syntax from the command + section alone; instead refer to the Formal Syntax section. + +1.2. Conventions Used in This Document + + "Conventions" are basic principles or procedures. Document + conventions are noted in this section. + + In examples, "C:" and "S:" indicate lines sent by the client and + server respectively. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "MAY", and "OPTIONAL" in this document are to + be interpreted as described in [KEYWORDS]. + + The word "can" (not "may") is used to refer to a possible + circumstance or situation, as opposed to an optional facility of the + protocol. + + + +Crispin Standards Track [Page 4] + +RFC 3501 IMAPv4 March 2003 + + + "User" is used to refer to a human user, whereas "client" refers to + the software being run by the user. + + "Connection" refers to the entire sequence of client/server + interaction from the initial establishment of the network connection + until its termination. + + "Session" refers to the sequence of client/server interaction from + the time that a mailbox is selected (SELECT or EXAMINE command) until + the time that selection ends (SELECT or EXAMINE of another mailbox, + CLOSE command, or connection termination). + + Characters are 7-bit US-ASCII unless otherwise specified. Other + character sets are indicated using a "CHARSET", as described in + [MIME-IMT] and defined in [CHARSET]. CHARSETs have important + additional semantics in addition to defining character set; refer to + these documents for more detail. + + There are several protocol conventions in IMAP. These refer to + aspects of the specification which are not strictly part of the IMAP + protocol, but reflect generally-accepted practice. Implementations + need to be aware of these conventions, and avoid conflicts whether or + not they implement the convention. For example, "&" may not be used + as a hierarchy delimiter since it conflicts with the Mailbox + International Naming Convention, and other uses of "&" in mailbox + names are impacted as well. + +1.3. Special Notes to Implementors + + Implementors of the IMAP protocol are strongly encouraged to read the + IMAP implementation recommendations document [IMAP-IMPLEMENTATION] in + conjunction with this document, to help understand the intricacies of + this protocol and how best to build an interoperable product. + + IMAP4rev1 is designed to be upwards compatible from the [IMAP2] and + unpublished IMAP2bis protocols. IMAP4rev1 is largely compatible with + the IMAP4 protocol described in RFC 1730; the exception being in + certain facilities added in RFC 1730 that proved problematic and were + subsequently removed. In the course of the evolution of IMAP4rev1, + some aspects in the earlier protocols have become obsolete. Obsolete + commands, responses, and data formats which an IMAP4rev1 + implementation can encounter when used with an earlier implementation + are described in [IMAP-OBSOLETE]. + + Other compatibility issues with IMAP2bis, the most common variant of + the earlier protocol, are discussed in [IMAP-COMPAT]. A full + discussion of compatibility issues with rare (and presumed extinct) + + + + +Crispin Standards Track [Page 5] + +RFC 3501 IMAPv4 March 2003 + + + variants of [IMAP2] is in [IMAP-HISTORICAL]; this document is + primarily of historical interest. + + IMAP was originally developed for the older [RFC-822] standard, and + as a consequence several fetch items in IMAP incorporate "RFC822" in + their name. With the exception of RFC822.SIZE, there are more modern + replacements; for example, the modern version of RFC822.HEADER is + BODY.PEEK[HEADER]. In all cases, "RFC822" should be interpreted as a + reference to the updated [RFC-2822] standard. + +2. Protocol Overview + +2.1. Link Level + + The IMAP4rev1 protocol assumes a reliable data stream such as that + provided by TCP. When TCP is used, an IMAP4rev1 server listens on + port 143. + +2.2. Commands and Responses + + An IMAP4rev1 connection consists of the establishment of a + client/server network connection, an initial greeting from the + server, and client/server interactions. These client/server + interactions consist of a client command, server data, and a server + completion result response. + + All interactions transmitted by client and server are in the form of + lines, that is, strings that end with a CRLF. The protocol receiver + of an IMAP4rev1 client or server is either reading a line, or is + reading a sequence of octets with a known count followed by a line. + +2.2.1. Client Protocol Sender and Server Protocol Receiver + + The client command begins an operation. Each client command is + prefixed with an identifier (typically a short alphanumeric string, + e.g., A0001, A0002, etc.) called a "tag". A different tag is + generated by the client for each command. + + Clients MUST follow the syntax outlined in this specification + strictly. It is a syntax error to send a command with missing or + extraneous spaces or arguments. + + There are two cases in which a line from the client does not + represent a complete command. In one case, a command argument is + quoted with an octet count (see the description of literal in String + under Data Formats); in the other case, the command arguments require + server feedback (see the AUTHENTICATE command). In either case, the + + + + +Crispin Standards Track [Page 6] + +RFC 3501 IMAPv4 March 2003 + + + server sends a command continuation request response if it is ready + for the octets (if appropriate) and the remainder of the command. + This response is prefixed with the token "+". + + Note: If instead, the server detected an error in the + command, it sends a BAD completion response with a tag + matching the command (as described below) to reject the + command and prevent the client from sending any more of the + command. + + It is also possible for the server to send a completion + response for some other command (if multiple commands are + in progress), or untagged data. In either case, the + command continuation request is still pending; the client + takes the appropriate action for the response, and reads + another response from the server. In all cases, the client + MUST send a complete command (including receiving all + command continuation request responses and command + continuations for the command) before initiating a new + command. + + The protocol receiver of an IMAP4rev1 server reads a command line + from the client, parses the command and its arguments, and transmits + server data and a server command completion result response. + +2.2.2. Server Protocol Sender and Client Protocol Receiver + + Data transmitted by the server to the client and status responses + that do not indicate command completion are prefixed with the token + "*", and are called untagged responses. + + Server data MAY be sent as a result of a client command, or MAY be + sent unilaterally by the server. There is no syntactic difference + between server data that resulted from a specific command and server + data that were sent unilaterally. + + The server completion result response indicates the success or + failure of the operation. It is tagged with the same tag as the + client command which began the operation. Thus, if more than one + command is in progress, the tag in a server completion response + identifies the command to which the response applies. There are + three possible server completion responses: OK (indicating success), + NO (indicating failure), or BAD (indicating a protocol error such as + unrecognized command or command syntax error). + + Servers SHOULD enforce the syntax outlined in this specification + strictly. Any client command with a protocol syntax error, including + (but not limited to) missing or extraneous spaces or arguments, + + + +Crispin Standards Track [Page 7] + +RFC 3501 IMAPv4 March 2003 + + + SHOULD be rejected, and the client given a BAD server completion + response. + + The protocol receiver of an IMAP4rev1 client reads a response line + from the server. It then takes action on the response based upon the + first token of the response, which can be a tag, a "*", or a "+". + + A client MUST be prepared to accept any server response at all times. + This includes server data that was not requested. Server data SHOULD + be recorded, so that the client can reference its recorded copy + rather than sending a command to the server to request the data. In + the case of certain server data, the data MUST be recorded. + + This topic is discussed in greater detail in the Server Responses + section. + +2.3. Message Attributes + + In addition to message text, each message has several attributes + associated with it. These attributes can be retrieved individually + or in conjunction with other attributes or message texts. + +2.3.1. Message Numbers + + Messages in IMAP4rev1 are accessed by one of two numbers; the unique + identifier or the message sequence number. + + +2.3.1.1. Unique Identifier (UID) Message Attribute + + A 32-bit value assigned to each message, which when used with the + unique identifier validity value (see below) forms a 64-bit value + that MUST NOT refer to any other message in the mailbox or any + subsequent mailbox with the same name forever. Unique identifiers + are assigned in a strictly ascending fashion in the mailbox; as each + message is added to the mailbox it is assigned a higher UID than the + message(s) which were added previously. Unlike message sequence + numbers, unique identifiers are not necessarily contiguous. + + The unique identifier of a message MUST NOT change during the + session, and SHOULD NOT change between sessions. Any change of + unique identifiers between sessions MUST be detectable using the + UIDVALIDITY mechanism discussed below. Persistent unique identifiers + are required for a client to resynchronize its state from a previous + session with the server (e.g., disconnected or offline access + clients); this is discussed further in [IMAP-DISC]. + + + + + +Crispin Standards Track [Page 8] + +RFC 3501 IMAPv4 March 2003 + + + Associated with every mailbox are two values which aid in unique + identifier handling: the next unique identifier value and the unique + identifier validity value. + + The next unique identifier value is the predicted value that will be + assigned to a new message in the mailbox. Unless the unique + identifier validity also changes (see below), the next unique + identifier value MUST have the following two characteristics. First, + the next unique identifier value MUST NOT change unless new messages + are added to the mailbox; and second, the next unique identifier + value MUST change whenever new messages are added to the mailbox, + even if those new messages are subsequently expunged. + + Note: The next unique identifier value is intended to + provide a means for a client to determine whether any + messages have been delivered to the mailbox since the + previous time it checked this value. It is not intended to + provide any guarantee that any message will have this + unique identifier. A client can only assume, at the time + that it obtains the next unique identifier value, that + messages arriving after that time will have a UID greater + than or equal to that value. + + The unique identifier validity value is sent in a UIDVALIDITY + response code in an OK untagged response at mailbox selection time. + If unique identifiers from an earlier session fail to persist in this + session, the unique identifier validity value MUST be greater than + the one used in the earlier session. + + Note: Ideally, unique identifiers SHOULD persist at all + times. Although this specification recognizes that failure + to persist can be unavoidable in certain server + environments, it STRONGLY ENCOURAGES message store + implementation techniques that avoid this problem. For + example: + + 1) Unique identifiers MUST be strictly ascending in the + mailbox at all times. If the physical message store is + re-ordered by a non-IMAP agent, this requires that the + unique identifiers in the mailbox be regenerated, since + the former unique identifiers are no longer strictly + ascending as a result of the re-ordering. + + 2) If the message store has no mechanism to store unique + identifiers, it must regenerate unique identifiers at + each session, and each session must have a unique + UIDVALIDITY value. + + + + +Crispin Standards Track [Page 9] + +RFC 3501 IMAPv4 March 2003 + + + 3) If the mailbox is deleted and a new mailbox with the + same name is created at a later date, the server must + either keep track of unique identifiers from the + previous instance of the mailbox, or it must assign a + new UIDVALIDITY value to the new instance of the + mailbox. A good UIDVALIDITY value to use in this case + is a 32-bit representation of the creation date/time of + the mailbox. It is alright to use a constant such as + 1, but only if it guaranteed that unique identifiers + will never be reused, even in the case of a mailbox + being deleted (or renamed) and a new mailbox by the + same name created at some future time. + + 4) The combination of mailbox name, UIDVALIDITY, and UID + must refer to a single immutable message on that server + forever. In particular, the internal date, [RFC-2822] + size, envelope, body structure, and message texts + (RFC822, RFC822.HEADER, RFC822.TEXT, and all BODY[...] + fetch data items) must never change. This does not + include message numbers, nor does it include attributes + that can be set by a STORE command (e.g., FLAGS). + + +2.3.1.2. Message Sequence Number Message Attribute + + A relative position from 1 to the number of messages in the mailbox. + This position MUST be ordered by ascending unique identifier. As + each new message is added, it is assigned a message sequence number + that is 1 higher than the number of messages in the mailbox before + that new message was added. + + Message sequence numbers can be reassigned during the session. For + example, when a message is permanently removed (expunged) from the + mailbox, the message sequence number for all subsequent messages is + decremented. The number of messages in the mailbox is also + decremented. Similarly, a new message can be assigned a message + sequence number that was once held by some other message prior to an + expunge. + + In addition to accessing messages by relative position in the + mailbox, message sequence numbers can be used in mathematical + calculations. For example, if an untagged "11 EXISTS" is received, + and previously an untagged "8 EXISTS" was received, three new + messages have arrived with message sequence numbers of 9, 10, and 11. + Another example, if message 287 in a 523 message mailbox has UID + 12345, there are exactly 286 messages which have lesser UIDs and 236 + messages which have greater UIDs. + + + + +Crispin Standards Track [Page 10] + +RFC 3501 IMAPv4 March 2003 + + +2.3.2. Flags Message Attribute + + A list of zero or more named tokens associated with the message. A + flag is set by its addition to this list, and is cleared by its + removal. There are two types of flags in IMAP4rev1. A flag of + either type can be permanent or session-only. + + A system flag is a flag name that is pre-defined in this + specification. All system flags begin with "\". Certain system + flags (\Deleted and \Seen) have special semantics described + elsewhere. The currently-defined system flags are: + + \Seen + Message has been read + + \Answered + Message has been answered + + \Flagged + Message is "flagged" for urgent/special attention + + \Deleted + Message is "deleted" for removal by later EXPUNGE + + \Draft + Message has not completed composition (marked as a draft). + + \Recent + Message is "recently" arrived in this mailbox. This session + is the first session to have been notified about this + message; if the session is read-write, subsequent sessions + will not see \Recent set for this message. This flag can not + be altered by the client. + + If it is not possible to determine whether or not this + session is the first session to be notified about a message, + then that message SHOULD be considered recent. + + If multiple connections have the same mailbox selected + simultaneously, it is undefined which of these connections + will see newly-arrived messages with \Recent set and which + will see it without \Recent set. + + A keyword is defined by the server implementation. Keywords do not + begin with "\". Servers MAY permit the client to define new keywords + in the mailbox (see the description of the PERMANENTFLAGS response + code for more information). + + + + +Crispin Standards Track [Page 11] + +RFC 3501 IMAPv4 March 2003 + + + A flag can be permanent or session-only on a per-flag basis. + Permanent flags are those which the client can add or remove from the + message flags permanently; that is, concurrent and subsequent + sessions will see any change in permanent flags. Changes to session + flags are valid only in that session. + + Note: The \Recent system flag is a special case of a + session flag. \Recent can not be used as an argument in a + STORE or APPEND command, and thus can not be changed at + all. + +2.3.3. Internal Date Message Attribute + + The internal date and time of the message on the server. This + is not the date and time in the [RFC-2822] header, but rather a + date and time which reflects when the message was received. In + the case of messages delivered via [SMTP], this SHOULD be the + date and time of final delivery of the message as defined by + [SMTP]. In the case of messages delivered by the IMAP4rev1 COPY + command, this SHOULD be the internal date and time of the source + message. In the case of messages delivered by the IMAP4rev1 + APPEND command, this SHOULD be the date and time as specified in + the APPEND command description. All other cases are + implementation defined. + +2.3.4. [RFC-2822] Size Message Attribute + + The number of octets in the message, as expressed in [RFC-2822] + format. + +2.3.5. Envelope Structure Message Attribute + + A parsed representation of the [RFC-2822] header of the message. + Note that the IMAP Envelope structure is not the same as an + [SMTP] envelope. + +2.3.6. Body Structure Message Attribute + + A parsed representation of the [MIME-IMB] body structure + information of the message. + + + + + + + + + + + +Crispin Standards Track [Page 12] + +RFC 3501 IMAPv4 March 2003 + + +2.4. Message Texts + + In addition to being able to fetch the full [RFC-2822] text of a + message, IMAP4rev1 permits the fetching of portions of the full + message text. Specifically, it is possible to fetch the + [RFC-2822] message header, [RFC-2822] message body, a [MIME-IMB] + body part, or a [MIME-IMB] header. + +3. State and Flow Diagram + + Once the connection between client and server is established, an + IMAP4rev1 connection is in one of four states. The initial + state is identified in the server greeting. Most commands are + only valid in certain states. It is a protocol error for the + client to attempt a command while the connection is in an + inappropriate state, and the server will respond with a BAD or + NO (depending upon server implementation) command completion + result. + +3.1. Not Authenticated State + + In the not authenticated state, the client MUST supply + authentication credentials before most commands will be + permitted. This state is entered when a connection starts + unless the connection has been pre-authenticated. + +3.2. Authenticated State + + In the authenticated state, the client is authenticated and MUST + select a mailbox to access before commands that affect messages + will be permitted. This state is entered when a + pre-authenticated connection starts, when acceptable + authentication credentials have been provided, after an error in + selecting a mailbox, or after a successful CLOSE command. + +3.3. Selected State + + In a selected state, a mailbox has been selected to access. + This state is entered when a mailbox has been successfully + selected. + + + + + + + + + + + +Crispin Standards Track [Page 13] + +RFC 3501 IMAPv4 March 2003 + + +3.4. Logout State + + In the logout state, the connection is being terminated. This + state can be entered as a result of a client request (via the + LOGOUT command) or by unilateral action on the part of either + the client or server. + + If the client requests the logout state, the server MUST send an + untagged BYE response and a tagged OK response to the LOGOUT + command before the server closes the connection; and the client + MUST read the tagged OK response to the LOGOUT command before + the client closes the connection. + + A server MUST NOT unilaterally close the connection without + sending an untagged BYE response that contains the reason for + having done so. A client SHOULD NOT unilaterally close the + connection, and instead SHOULD issue a LOGOUT command. If the + server detects that the client has unilaterally closed the + connection, the server MAY omit the untagged BYE response and + simply close its connection. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Crispin Standards Track [Page 14] + +RFC 3501 IMAPv4 March 2003 + + + +----------------------+ + |connection established| + +----------------------+ + || + \/ + +--------------------------------------+ + | server greeting | + +--------------------------------------+ + || (1) || (2) || (3) + \/ || || + +-----------------+ || || + |Not Authenticated| || || + +-----------------+ || || + || (7) || (4) || || + || \/ \/ || + || +----------------+ || + || | Authenticated |<=++ || + || +----------------+ || || + || || (7) || (5) || (6) || + || || \/ || || + || || +--------+ || || + || || |Selected|==++ || + || || +--------+ || + || || || (7) || + \/ \/ \/ \/ + +--------------------------------------+ + | Logout | + +--------------------------------------+ + || + \/ + +-------------------------------+ + |both sides close the connection| + +-------------------------------+ + + (1) connection without pre-authentication (OK greeting) + (2) pre-authenticated connection (PREAUTH greeting) + (3) rejected connection (BYE greeting) + (4) successful LOGIN or AUTHENTICATE command + (5) successful SELECT or EXAMINE command + (6) CLOSE command, or failed SELECT or EXAMINE command + (7) LOGOUT command, server shutdown, or connection closed + + + + + + + + + + +Crispin Standards Track [Page 15] + +RFC 3501 IMAPv4 March 2003 + + +4. Data Formats + + IMAP4rev1 uses textual commands and responses. Data in + IMAP4rev1 can be in one of several forms: atom, number, string, + parenthesized list, or NIL. Note that a particular data item + may take more than one form; for example, a data item defined as + using "astring" syntax may be either an atom or a string. + +4.1. Atom + + An atom consists of one or more non-special characters. + +4.2. Number + + A number consists of one or more digit characters, and + represents a numeric value. + +4.3. String + + A string is in one of two forms: either literal or quoted + string. The literal form is the general form of string. The + quoted string form is an alternative that avoids the overhead of + processing a literal at the cost of limitations of characters + which may be used. + + A literal is a sequence of zero or more octets (including CR and + LF), prefix-quoted with an octet count in the form of an open + brace ("{"), the number of octets, close brace ("}"), and CRLF. + In the case of literals transmitted from server to client, the + CRLF is immediately followed by the octet data. In the case of + literals transmitted from client to server, the client MUST wait + to receive a command continuation request (described later in + this document) before sending the octet data (and the remainder + of the command). + + A quoted string is a sequence of zero or more 7-bit characters, + excluding CR and LF, with double quote (<">) characters at each + end. + + The empty string is represented as either "" (a quoted string + with zero characters between double quotes) or as {0} followed + by CRLF (a literal with an octet count of 0). + + Note: Even if the octet count is 0, a client transmitting a + literal MUST wait to receive a command continuation request. + + + + + + +Crispin Standards Track [Page 16] + +RFC 3501 IMAPv4 March 2003 + + +4.3.1. 8-bit and Binary Strings + + 8-bit textual and binary mail is supported through the use of a + [MIME-IMB] content transfer encoding. IMAP4rev1 implementations MAY + transmit 8-bit or multi-octet characters in literals, but SHOULD do + so only when the [CHARSET] is identified. + + Although a BINARY body encoding is defined, unencoded binary strings + are not permitted. A "binary string" is any string with NUL + characters. Implementations MUST encode binary data into a textual + form, such as BASE64, before transmitting the data. A string with an + excessive amount of CTL characters MAY also be considered to be + binary. + +4.4. Parenthesized List + + Data structures are represented as a "parenthesized list"; a sequence + of data items, delimited by space, and bounded at each end by + parentheses. A parenthesized list can contain other parenthesized + lists, using multiple levels of parentheses to indicate nesting. + + The empty list is represented as () -- a parenthesized list with no + members. + +4.5. NIL + + The special form "NIL" represents the non-existence of a particular + data item that is represented as a string or parenthesized list, as + distinct from the empty string "" or the empty parenthesized list (). + + Note: NIL is never used for any data item which takes the + form of an atom. For example, a mailbox name of "NIL" is a + mailbox named NIL as opposed to a non-existent mailbox + name. This is because mailbox uses "astring" syntax which + is an atom or a string. Conversely, an addr-name of NIL is + a non-existent personal name, because addr-name uses + "nstring" syntax which is NIL or a string, but never an + atom. + + + + + + + + + + + + + +Crispin Standards Track [Page 17] + +RFC 3501 IMAPv4 March 2003 + + +5. Operational Considerations + + The following rules are listed here to ensure that all IMAP4rev1 + implementations interoperate properly. + +5.1. Mailbox Naming + + Mailbox names are 7-bit. Client implementations MUST NOT attempt to + create 8-bit mailbox names, and SHOULD interpret any 8-bit mailbox + names returned by LIST or LSUB as UTF-8. Server implementations + SHOULD prohibit the creation of 8-bit mailbox names, and SHOULD NOT + return 8-bit mailbox names in LIST or LSUB. See section 5.1.3 for + more information on how to represent non-ASCII mailbox names. + + Note: 8-bit mailbox names were undefined in earlier + versions of this protocol. Some sites used a local 8-bit + character set to represent non-ASCII mailbox names. Such + usage is not interoperable, and is now formally deprecated. + + The case-insensitive mailbox name INBOX is a special name reserved to + mean "the primary mailbox for this user on this server". The + interpretation of all other names is implementation-dependent. + + In particular, this specification takes no position on case + sensitivity in non-INBOX mailbox names. Some server implementations + are fully case-sensitive; others preserve case of a newly-created + name but otherwise are case-insensitive; and yet others coerce names + to a particular case. Client implementations MUST interact with any + of these. If a server implementation interprets non-INBOX mailbox + names as case-insensitive, it MUST treat names using the + international naming convention specially as described in section + 5.1.3. + + There are certain client considerations when creating a new mailbox + name: + + 1) Any character which is one of the atom-specials (see the Formal + Syntax) will require that the mailbox name be represented as a + quoted string or literal. + + 2) CTL and other non-graphic characters are difficult to represent + in a user interface and are best avoided. + + 3) Although the list-wildcard characters ("%" and "*") are valid + in a mailbox name, it is difficult to use such mailbox names + with the LIST and LSUB commands due to the conflict with + wildcard interpretation. + + + + +Crispin Standards Track [Page 18] + +RFC 3501 IMAPv4 March 2003 + + + 4) Usually, a character (determined by the server implementation) + is reserved to delimit levels of hierarchy. + + 5) Two characters, "#" and "&", have meanings by convention, and + should be avoided except when used in that convention. + +5.1.1. Mailbox Hierarchy Naming + + If it is desired to export hierarchical mailbox names, mailbox names + MUST be left-to-right hierarchical using a single character to + separate levels of hierarchy. The same hierarchy separator character + is used for all levels of hierarchy within a single name. + +5.1.2. Mailbox Namespace Naming Convention + + By convention, the first hierarchical element of any mailbox name + which begins with "#" identifies the "namespace" of the remainder of + the name. This makes it possible to disambiguate between different + types of mailbox stores, each of which have their own namespaces. + + For example, implementations which offer access to USENET + newsgroups MAY use the "#news" namespace to partition the + USENET newsgroup namespace from that of other mailboxes. + Thus, the comp.mail.misc newsgroup would have a mailbox + name of "#news.comp.mail.misc", and the name + "comp.mail.misc" can refer to a different object (e.g., a + user's private mailbox). + +5.1.3. Mailbox International Naming Convention + + By convention, international mailbox names in IMAP4rev1 are specified + using a modified version of the UTF-7 encoding described in [UTF-7]. + Modified UTF-7 may also be usable in servers that implement an + earlier version of this protocol. + + In modified UTF-7, printable US-ASCII characters, except for "&", + represent themselves; that is, characters with octet values 0x20-0x25 + and 0x27-0x7e. The character "&" (0x26) is represented by the + two-octet sequence "&-". + + All other characters (octet values 0x00-0x1f and 0x7f-0xff) are + represented in modified BASE64, with a further modification from + [UTF-7] that "," is used instead of "/". Modified BASE64 MUST NOT be + used to represent any printing US-ASCII character which can represent + itself. + + + + + + +Crispin Standards Track [Page 19] + +RFC 3501 IMAPv4 March 2003 + + + "&" is used to shift to modified BASE64 and "-" to shift back to + US-ASCII. There is no implicit shift from BASE64 to US-ASCII, and + null shifts ("-&" while in BASE64; note that "&-" while in US-ASCII + means "&") are not permitted. However, all names start in US-ASCII, + and MUST end in US-ASCII; that is, a name that ends with a non-ASCII + ISO-10646 character MUST end with a "-"). + + The purpose of these modifications is to correct the following + problems with UTF-7: + + 1) UTF-7 uses the "+" character for shifting; this conflicts with + the common use of "+" in mailbox names, in particular USENET + newsgroup names. + + 2) UTF-7's encoding is BASE64 which uses the "/" character; this + conflicts with the use of "/" as a popular hierarchy delimiter. + + 3) UTF-7 prohibits the unencoded usage of "\"; this conflicts with + the use of "\" as a popular hierarchy delimiter. + + 4) UTF-7 prohibits the unencoded usage of "~"; this conflicts with + the use of "~" in some servers as a home directory indicator. + + 5) UTF-7 permits multiple alternate forms to represent the same + string; in particular, printable US-ASCII characters can be + represented in encoded form. + + Although modified UTF-7 is a convention, it establishes certain + requirements on server handling of any mailbox name with an + embedded "&" character. In particular, server implementations + MUST preserve the exact form of the modified BASE64 portion of a + modified UTF-7 name and treat that text as case-sensitive, even if + names are otherwise case-insensitive or case-folded. + + Server implementations SHOULD verify that any mailbox name with an + embedded "&" character, used as an argument to CREATE, is: in the + correctly modified UTF-7 syntax, has no superfluous shifts, and + has no encoding in modified BASE64 of any printing US-ASCII + character which can represent itself. However, client + implementations MUST NOT depend upon the server doing this, and + SHOULD NOT attempt to create a mailbox name with an embedded "&" + character unless it complies with the modified UTF-7 syntax. + + Server implementations which export a mail store that does not + follow the modified UTF-7 convention MUST convert to modified + UTF-7 any mailbox name that contains either non-ASCII characters + or the "&" character. + + + + +Crispin Standards Track [Page 20] + +RFC 3501 IMAPv4 March 2003 + + + For example, here is a mailbox name which mixes English, + Chinese, and Japanese text: + ~peter/mail/&U,BTFw-/&ZeVnLIqe- + + For example, the string "&Jjo!" is not a valid mailbox + name because it does not contain a shift to US-ASCII + before the "!". The correct form is "&Jjo-!". The + string "&U,BTFw-&ZeVnLIqe-" is not permitted because it + contains a superfluous shift. The correct form is + "&U,BTF2XlZyyKng-". + +5.2. Mailbox Size and Message Status Updates + + At any time, a server can send data that the client did not request. + Sometimes, such behavior is REQUIRED. For example, agents other than + the server MAY add messages to the mailbox (e.g., new message + delivery), change the flags of the messages in the mailbox (e.g., + simultaneous access to the same mailbox by multiple agents), or even + remove messages from the mailbox. A server MUST send mailbox size + updates automatically if a mailbox size change is observed during the + processing of a command. A server SHOULD send message flag updates + automatically, without requiring the client to request such updates + explicitly. + + Special rules exist for server notification of a client about the + removal of messages to prevent synchronization errors; see the + description of the EXPUNGE response for more detail. In particular, + it is NOT permitted to send an EXISTS response that would reduce the + number of messages in the mailbox; only the EXPUNGE response can do + this. + + Regardless of what implementation decisions a client makes on + remembering data from the server, a client implementation MUST record + mailbox size updates. It MUST NOT assume that any command after the + initial mailbox selection will return the size of the mailbox. + +5.3. Response when no Command in Progress + + Server implementations are permitted to send an untagged response + (except for EXPUNGE) while there is no command in progress. Server + implementations that send such responses MUST deal with flow control + considerations. Specifically, they MUST either (1) verify that the + size of the data does not exceed the underlying transport's available + window size, or (2) use non-blocking writes. + + + + + + + +Crispin Standards Track [Page 21] + +RFC 3501 IMAPv4 March 2003 + + +5.4. Autologout Timer + + If a server has an inactivity autologout timer, the duration of that + timer MUST be at least 30 minutes. The receipt of ANY command from + the client during that interval SHOULD suffice to reset the + autologout timer. + +5.5. Multiple Commands in Progress + + The client MAY send another command without waiting for the + completion result response of a command, subject to ambiguity rules + (see below) and flow control constraints on the underlying data + stream. Similarly, a server MAY begin processing another command + before processing the current command to completion, subject to + ambiguity rules. However, any command continuation request responses + and command continuations MUST be negotiated before any subsequent + command is initiated. + + The exception is if an ambiguity would result because of a command + that would affect the results of other commands. Clients MUST NOT + send multiple commands without waiting if an ambiguity would result. + If the server detects a possible ambiguity, it MUST execute commands + to completion in the order given by the client. + + The most obvious example of ambiguity is when a command would affect + the results of another command, e.g., a FETCH of a message's flags + and a STORE of that same message's flags. + + A non-obvious ambiguity occurs with commands that permit an untagged + EXPUNGE response (commands other than FETCH, STORE, and SEARCH), + since an untagged EXPUNGE response can invalidate sequence numbers in + a subsequent command. This is not a problem for FETCH, STORE, or + SEARCH commands because servers are prohibited from sending EXPUNGE + responses while any of those commands are in progress. Therefore, if + the client sends any command other than FETCH, STORE, or SEARCH, it + MUST wait for the completion result response before sending a command + with message sequence numbers. + + Note: UID FETCH, UID STORE, and UID SEARCH are different + commands from FETCH, STORE, and SEARCH. If the client + sends a UID command, it must wait for a completion result + response before sending a command with message sequence + numbers. + + + + + + + + +Crispin Standards Track [Page 22] + +RFC 3501 IMAPv4 March 2003 + + + For example, the following non-waiting command sequences are invalid: + + FETCH + NOOP + STORE + STORE + COPY + FETCH + COPY + COPY + CHECK + FETCH + + The following are examples of valid non-waiting command sequences: + + FETCH + STORE + SEARCH + CHECK + STORE + COPY + EXPUNGE + + UID SEARCH + UID SEARCH may be valid or invalid as a non-waiting + command sequence, depending upon whether or not the second UID + SEARCH contains message sequence numbers. + +6. Client Commands + + IMAP4rev1 commands are described in this section. Commands are + organized by the state in which the command is permitted. Commands + which are permitted in multiple states are listed in the minimum + permitted state (for example, commands valid in authenticated and + selected state are listed in the authenticated state commands). + + Command arguments, identified by "Arguments:" in the command + descriptions below, are described by function, not by syntax. The + precise syntax of command arguments is described in the Formal Syntax + section. + + Some commands cause specific server responses to be returned; these + are identified by "Responses:" in the command descriptions below. + See the response descriptions in the Responses section for + information on these responses, and the Formal Syntax section for the + precise syntax of these responses. It is possible for server data to + be transmitted as a result of any command. Thus, commands that do + not specifically require server data specify "no specific responses + for this command" instead of "none". + + The "Result:" in the command description refers to the possible + tagged status responses to a command, and any special interpretation + of these status responses. + + The state of a connection is only changed by successful commands + which are documented as changing state. A rejected command (BAD + response) never changes the state of the connection or of the + selected mailbox. A failed command (NO response) generally does not + change the state of the connection or of the selected mailbox; the + exception being the SELECT and EXAMINE commands. + + + +Crispin Standards Track [Page 23] + +RFC 3501 IMAPv4 March 2003 + + +6.1. Client Commands - Any State + + The following commands are valid in any state: CAPABILITY, NOOP, and + LOGOUT. + +6.1.1. CAPABILITY Command + + Arguments: none + + Responses: REQUIRED untagged response: CAPABILITY + + Result: OK - capability completed + BAD - command unknown or arguments invalid + + The CAPABILITY command requests a listing of capabilities that the + server supports. The server MUST send a single untagged + CAPABILITY response with "IMAP4rev1" as one of the listed + capabilities before the (tagged) OK response. + + A capability name which begins with "AUTH=" indicates that the + server supports that particular authentication mechanism. All + such names are, by definition, part of this specification. For + example, the authorization capability for an experimental + "blurdybloop" authenticator would be "AUTH=XBLURDYBLOOP" and not + "XAUTH=BLURDYBLOOP" or "XAUTH=XBLURDYBLOOP". + + Other capability names refer to extensions, revisions, or + amendments to this specification. See the documentation of the + CAPABILITY response for additional information. No capabilities, + beyond the base IMAP4rev1 set defined in this specification, are + enabled without explicit client action to invoke the capability. + + Client and server implementations MUST implement the STARTTLS, + LOGINDISABLED, and AUTH=PLAIN (described in [IMAP-TLS]) + capabilities. See the Security Considerations section for + important information. + + See the section entitled "Client Commands - + Experimental/Expansion" for information about the form of site or + implementation-specific capabilities. + + + + + + + + + + + +Crispin Standards Track [Page 24] + +RFC 3501 IMAPv4 March 2003 + + + Example: C: abcd CAPABILITY + S: * CAPABILITY IMAP4rev1 STARTTLS AUTH=GSSAPI + LOGINDISABLED + S: abcd OK CAPABILITY completed + C: efgh STARTTLS + S: efgh OK STARTLS completed + <TLS negotiation, further commands are under [TLS] layer> + C: ijkl CAPABILITY + S: * CAPABILITY IMAP4rev1 AUTH=GSSAPI AUTH=PLAIN + S: ijkl OK CAPABILITY completed + + +6.1.2. NOOP Command + + Arguments: none + + Responses: no specific responses for this command (but see below) + + Result: OK - noop completed + BAD - command unknown or arguments invalid + + The NOOP command always succeeds. It does nothing. + + Since any command can return a status update as untagged data, the + NOOP command can be used as a periodic poll for new messages or + message status updates during a period of inactivity (this is the + preferred method to do this). The NOOP command can also be used + to reset any inactivity autologout timer on the server. + + Example: C: a002 NOOP + S: a002 OK NOOP completed + . . . + C: a047 NOOP + S: * 22 EXPUNGE + S: * 23 EXISTS + S: * 3 RECENT + S: * 14 FETCH (FLAGS (\Seen \Deleted)) + S: a047 OK NOOP completed + + + + + + + + + + + + + +Crispin Standards Track [Page 25] + +RFC 3501 IMAPv4 March 2003 + + +6.1.3. LOGOUT Command + + Arguments: none + + Responses: REQUIRED untagged response: BYE + + Result: OK - logout completed + BAD - command unknown or arguments invalid + + The LOGOUT command informs the server that the client is done with + the connection. The server MUST send a BYE untagged response + before the (tagged) OK response, and then close the network + connection. + + Example: C: A023 LOGOUT + S: * BYE IMAP4rev1 Server logging out + S: A023 OK LOGOUT completed + (Server and client then close the connection) + +6.2. Client Commands - Not Authenticated State + + In the not authenticated state, the AUTHENTICATE or LOGIN command + establishes authentication and enters the authenticated state. The + AUTHENTICATE command provides a general mechanism for a variety of + authentication techniques, privacy protection, and integrity + checking; whereas the LOGIN command uses a traditional user name and + plaintext password pair and has no means of establishing privacy + protection or integrity checking. + + The STARTTLS command is an alternate form of establishing session + privacy protection and integrity checking, but does not establish + authentication or enter the authenticated state. + + Server implementations MAY allow access to certain mailboxes without + establishing authentication. This can be done by means of the + ANONYMOUS [SASL] authenticator described in [ANONYMOUS]. An older + convention is a LOGIN command using the userid "anonymous"; in this + case, a password is required although the server may choose to accept + any password. The restrictions placed on anonymous users are + implementation-dependent. + + Once authenticated (including as anonymous), it is not possible to + re-enter not authenticated state. + + + + + + + + +Crispin Standards Track [Page 26] + +RFC 3501 IMAPv4 March 2003 + + + In addition to the universal commands (CAPABILITY, NOOP, and LOGOUT), + the following commands are valid in the not authenticated state: + STARTTLS, AUTHENTICATE and LOGIN. See the Security Considerations + section for important information about these commands. + +6.2.1. STARTTLS Command + + Arguments: none + + Responses: no specific response for this command + + Result: OK - starttls completed, begin TLS negotiation + BAD - command unknown or arguments invalid + + A [TLS] negotiation begins immediately after the CRLF at the end + of the tagged OK response from the server. Once a client issues a + STARTTLS command, it MUST NOT issue further commands until a + server response is seen and the [TLS] negotiation is complete. + + The server remains in the non-authenticated state, even if client + credentials are supplied during the [TLS] negotiation. This does + not preclude an authentication mechanism such as EXTERNAL (defined + in [SASL]) from using client identity determined by the [TLS] + negotiation. + + Once [TLS] has been started, the client MUST discard cached + information about server capabilities and SHOULD re-issue the + CAPABILITY command. This is necessary to protect against man-in- + the-middle attacks which alter the capabilities list prior to + STARTTLS. The server MAY advertise different capabilities after + STARTTLS. + + Example: C: a001 CAPABILITY + S: * CAPABILITY IMAP4rev1 STARTTLS LOGINDISABLED + S: a001 OK CAPABILITY completed + C: a002 STARTTLS + S: a002 OK Begin TLS negotiation now + <TLS negotiation, further commands are under [TLS] layer> + C: a003 CAPABILITY + S: * CAPABILITY IMAP4rev1 AUTH=PLAIN + S: a003 OK CAPABILITY completed + C: a004 LOGIN joe password + S: a004 OK LOGIN completed + + + + + + + + +Crispin Standards Track [Page 27] + +RFC 3501 IMAPv4 March 2003 + + +6.2.2. AUTHENTICATE Command + + Arguments: authentication mechanism name + + Responses: continuation data can be requested + + Result: OK - authenticate completed, now in authenticated state + NO - authenticate failure: unsupported authentication + mechanism, credentials rejected + BAD - command unknown or arguments invalid, + authentication exchange cancelled + + The AUTHENTICATE command indicates a [SASL] authentication + mechanism to the server. If the server supports the requested + authentication mechanism, it performs an authentication protocol + exchange to authenticate and identify the client. It MAY also + negotiate an OPTIONAL security layer for subsequent protocol + interactions. If the requested authentication mechanism is not + supported, the server SHOULD reject the AUTHENTICATE command by + sending a tagged NO response. + + The AUTHENTICATE command does not support the optional "initial + response" feature of [SASL]. Section 5.1 of [SASL] specifies how + to handle an authentication mechanism which uses an initial + response. + + The service name specified by this protocol's profile of [SASL] is + "imap". + + The authentication protocol exchange consists of a series of + server challenges and client responses that are specific to the + authentication mechanism. A server challenge consists of a + command continuation request response with the "+" token followed + by a BASE64 encoded string. The client response consists of a + single line consisting of a BASE64 encoded string. If the client + wishes to cancel an authentication exchange, it issues a line + consisting of a single "*". If the server receives such a + response, it MUST reject the AUTHENTICATE command by sending a + tagged BAD response. + + If a security layer is negotiated through the [SASL] + authentication exchange, it takes effect immediately following the + CRLF that concludes the authentication exchange for the client, + and the CRLF of the tagged OK response for the server. + + While client and server implementations MUST implement the + AUTHENTICATE command itself, it is not required to implement any + authentication mechanisms other than the PLAIN mechanism described + + + +Crispin Standards Track [Page 28] + +RFC 3501 IMAPv4 March 2003 + + + in [IMAP-TLS]. Also, an authentication mechanism is not required + to support any security layers. + + Note: a server implementation MUST implement a + configuration in which it does NOT permit any plaintext + password mechanisms, unless either the STARTTLS command + has been negotiated or some other mechanism that + protects the session from password snooping has been + provided. Server sites SHOULD NOT use any configuration + which permits a plaintext password mechanism without + such a protection mechanism against password snooping. + Client and server implementations SHOULD implement + additional [SASL] mechanisms that do not use plaintext + passwords, such the GSSAPI mechanism described in [SASL] + and/or the [DIGEST-MD5] mechanism. + + Servers and clients can support multiple authentication + mechanisms. The server SHOULD list its supported authentication + mechanisms in the response to the CAPABILITY command so that the + client knows which authentication mechanisms to use. + + A server MAY include a CAPABILITY response code in the tagged OK + response of a successful AUTHENTICATE command in order to send + capabilities automatically. It is unnecessary for a client to + send a separate CAPABILITY command if it recognizes these + automatic capabilities. This should only be done if a security + layer was not negotiated by the AUTHENTICATE command, because the + tagged OK response as part of an AUTHENTICATE command is not + protected by encryption/integrity checking. [SASL] requires the + client to re-issue a CAPABILITY command in this case. + + If an AUTHENTICATE command fails with a NO response, the client + MAY try another authentication mechanism by issuing another + AUTHENTICATE command. It MAY also attempt to authenticate by + using the LOGIN command (see section 6.2.3 for more detail). In + other words, the client MAY request authentication types in + decreasing order of preference, with the LOGIN command as a last + resort. + + The authorization identity passed from the client to the server + during the authentication exchange is interpreted by the server as + the user name whose privileges the client is requesting. + + + + + + + + + +Crispin Standards Track [Page 29] + +RFC 3501 IMAPv4 March 2003 + + + Example: S: * OK IMAP4rev1 Server + C: A001 AUTHENTICATE GSSAPI + S: + + C: YIIB+wYJKoZIhvcSAQICAQBuggHqMIIB5qADAgEFoQMCAQ6iBw + MFACAAAACjggEmYYIBIjCCAR6gAwIBBaESGxB1Lndhc2hpbmd0 + b24uZWR1oi0wK6ADAgEDoSQwIhsEaW1hcBsac2hpdmFtcy5jYW + Mud2FzaGluZ3Rvbi5lZHWjgdMwgdCgAwIBAaEDAgEDooHDBIHA + cS1GSa5b+fXnPZNmXB9SjL8Ollj2SKyb+3S0iXMljen/jNkpJX + AleKTz6BQPzj8duz8EtoOuNfKgweViyn/9B9bccy1uuAE2HI0y + C/PHXNNU9ZrBziJ8Lm0tTNc98kUpjXnHZhsMcz5Mx2GR6dGknb + I0iaGcRerMUsWOuBmKKKRmVMMdR9T3EZdpqsBd7jZCNMWotjhi + vd5zovQlFqQ2Wjc2+y46vKP/iXxWIuQJuDiisyXF0Y8+5GTpAL + pHDc1/pIGmMIGjoAMCAQGigZsEgZg2on5mSuxoDHEA1w9bcW9n + FdFxDKpdrQhVGVRDIzcCMCTzvUboqb5KjY1NJKJsfjRQiBYBdE + NKfzK+g5DlV8nrw81uOcP8NOQCLR5XkoMHC0Dr/80ziQzbNqhx + O6652Npft0LQwJvenwDI13YxpwOdMXzkWZN/XrEqOWp6GCgXTB + vCyLWLlWnbaUkZdEYbKHBPjd8t/1x5Yg== + S: + YGgGCSqGSIb3EgECAgIAb1kwV6ADAgEFoQMCAQ+iSzBJoAMC + AQGiQgRAtHTEuOP2BXb9sBYFR4SJlDZxmg39IxmRBOhXRKdDA0 + uHTCOT9Bq3OsUTXUlk0CsFLoa8j+gvGDlgHuqzWHPSQg== + C: + S: + YDMGCSqGSIb3EgECAgIBAAD/////6jcyG4GE3KkTzBeBiVHe + ceP2CWY0SR0fAQAgAAQEBAQ= + C: YDMGCSqGSIb3EgECAgIBAAD/////3LQBHXTpFfZgrejpLlLImP + wkhbfa2QteAQAgAG1yYwE= + S: A001 OK GSSAPI authentication successful + + Note: The line breaks within server challenges and client + responses are for editorial clarity and are not in real + authenticators. + + +6.2.3. LOGIN Command + + Arguments: user name + password + + Responses: no specific responses for this command + + Result: OK - login completed, now in authenticated state + NO - login failure: user name or password rejected + BAD - command unknown or arguments invalid + + The LOGIN command identifies the client to the server and carries + the plaintext password authenticating this user. + + + + + + +Crispin Standards Track [Page 30] + +RFC 3501 IMAPv4 March 2003 + + + A server MAY include a CAPABILITY response code in the tagged OK + response to a successful LOGIN command in order to send + capabilities automatically. It is unnecessary for a client to + send a separate CAPABILITY command if it recognizes these + automatic capabilities. + + Example: C: a001 LOGIN SMITH SESAME + S: a001 OK LOGIN completed + + Note: Use of the LOGIN command over an insecure network + (such as the Internet) is a security risk, because anyone + monitoring network traffic can obtain plaintext passwords. + The LOGIN command SHOULD NOT be used except as a last + resort, and it is recommended that client implementations + have a means to disable any automatic use of the LOGIN + command. + + Unless either the STARTTLS command has been negotiated or + some other mechanism that protects the session from + password snooping has been provided, a server + implementation MUST implement a configuration in which it + advertises the LOGINDISABLED capability and does NOT permit + the LOGIN command. Server sites SHOULD NOT use any + configuration which permits the LOGIN command without such + a protection mechanism against password snooping. A client + implementation MUST NOT send a LOGIN command if the + LOGINDISABLED capability is advertised. + +6.3. Client Commands - Authenticated State + + In the authenticated state, commands that manipulate mailboxes as + atomic entities are permitted. Of these commands, the SELECT and + EXAMINE commands will select a mailbox for access and enter the + selected state. + + In addition to the universal commands (CAPABILITY, NOOP, and LOGOUT), + the following commands are valid in the authenticated state: SELECT, + EXAMINE, CREATE, DELETE, RENAME, SUBSCRIBE, UNSUBSCRIBE, LIST, LSUB, + STATUS, and APPEND. + + + + + + + + + + + + +Crispin Standards Track [Page 31] + +RFC 3501 IMAPv4 March 2003 + + +6.3.1. SELECT Command + + Arguments: mailbox name + + Responses: REQUIRED untagged responses: FLAGS, EXISTS, RECENT + REQUIRED OK untagged responses: UNSEEN, PERMANENTFLAGS, + UIDNEXT, UIDVALIDITY + + Result: OK - select completed, now in selected state + NO - select failure, now in authenticated state: no + such mailbox, can't access mailbox + BAD - command unknown or arguments invalid + + The SELECT command selects a mailbox so that messages in the + mailbox can be accessed. Before returning an OK to the client, + the server MUST send the following untagged data to the client. + Note that earlier versions of this protocol only required the + FLAGS, EXISTS, and RECENT untagged data; consequently, client + implementations SHOULD implement default behavior for missing data + as discussed with the individual item. + + FLAGS Defined flags in the mailbox. See the description + of the FLAGS response for more detail. + + <n> EXISTS The number of messages in the mailbox. See the + description of the EXISTS response for more detail. + + <n> RECENT The number of messages with the \Recent flag set. + See the description of the RECENT response for more + detail. + + OK [UNSEEN <n>] + The message sequence number of the first unseen + message in the mailbox. If this is missing, the + client can not make any assumptions about the first + unseen message in the mailbox, and needs to issue a + SEARCH command if it wants to find it. + + OK [PERMANENTFLAGS (<list of flags>)] + A list of message flags that the client can change + permanently. If this is missing, the client should + assume that all flags can be changed permanently. + + OK [UIDNEXT <n>] + The next unique identifier value. Refer to section + 2.3.1.1 for more information. If this is missing, + the client can not make any assumptions about the + next unique identifier value. + + + +Crispin Standards Track [Page 32] + +RFC 3501 IMAPv4 March 2003 + + + OK [UIDVALIDITY <n>] + The unique identifier validity value. Refer to + section 2.3.1.1 for more information. If this is + missing, the server does not support unique + identifiers. + + Only one mailbox can be selected at a time in a connection; + simultaneous access to multiple mailboxes requires multiple + connections. The SELECT command automatically deselects any + currently selected mailbox before attempting the new selection. + Consequently, if a mailbox is selected and a SELECT command that + fails is attempted, no mailbox is selected. + + If the client is permitted to modify the mailbox, the server + SHOULD prefix the text of the tagged OK response with the + "[READ-WRITE]" response code. + + If the client is not permitted to modify the mailbox but is + permitted read access, the mailbox is selected as read-only, and + the server MUST prefix the text of the tagged OK response to + SELECT with the "[READ-ONLY]" response code. Read-only access + through SELECT differs from the EXAMINE command in that certain + read-only mailboxes MAY permit the change of permanent state on a + per-user (as opposed to global) basis. Netnews messages marked in + a server-based .newsrc file are an example of such per-user + permanent state that can be modified with read-only mailboxes. + + Example: C: A142 SELECT INBOX + S: * 172 EXISTS + S: * 1 RECENT + S: * OK [UNSEEN 12] Message 12 is first unseen + S: * OK [UIDVALIDITY 3857529045] UIDs valid + S: * OK [UIDNEXT 4392] Predicted next UID + S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) + S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited + S: A142 OK [READ-WRITE] SELECT completed + + + + + + + + + + + + + + + +Crispin Standards Track [Page 33] + +RFC 3501 IMAPv4 March 2003 + + +6.3.2. EXAMINE Command + + Arguments: mailbox name + + Responses: REQUIRED untagged responses: FLAGS, EXISTS, RECENT + REQUIRED OK untagged responses: UNSEEN, PERMANENTFLAGS, + UIDNEXT, UIDVALIDITY + + Result: OK - examine completed, now in selected state + NO - examine failure, now in authenticated state: no + such mailbox, can't access mailbox + BAD - command unknown or arguments invalid + + The EXAMINE command is identical to SELECT and returns the same + output; however, the selected mailbox is identified as read-only. + No changes to the permanent state of the mailbox, including + per-user state, are permitted; in particular, EXAMINE MUST NOT + cause messages to lose the \Recent flag. + + The text of the tagged OK response to the EXAMINE command MUST + begin with the "[READ-ONLY]" response code. + + Example: C: A932 EXAMINE blurdybloop + S: * 17 EXISTS + S: * 2 RECENT + S: * OK [UNSEEN 8] Message 8 is first unseen + S: * OK [UIDVALIDITY 3857529045] UIDs valid + S: * OK [UIDNEXT 4392] Predicted next UID + S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) + S: * OK [PERMANENTFLAGS ()] No permanent flags permitted + S: A932 OK [READ-ONLY] EXAMINE completed + + +6.3.3. CREATE Command + + Arguments: mailbox name + + Responses: no specific responses for this command + + Result: OK - create completed + NO - create failure: can't create mailbox with that name + BAD - command unknown or arguments invalid + + The CREATE command creates a mailbox with the given name. An OK + response is returned only if a new mailbox with that name has been + created. It is an error to attempt to create INBOX or a mailbox + with a name that refers to an extant mailbox. Any error in + creation will return a tagged NO response. + + + +Crispin Standards Track [Page 34] + +RFC 3501 IMAPv4 March 2003 + + + If the mailbox name is suffixed with the server's hierarchy + separator character (as returned from the server by a LIST + command), this is a declaration that the client intends to create + mailbox names under this name in the hierarchy. Server + implementations that do not require this declaration MUST ignore + the declaration. In any case, the name created is without the + trailing hierarchy delimiter. + + If the server's hierarchy separator character appears elsewhere in + the name, the server SHOULD create any superior hierarchical names + that are needed for the CREATE command to be successfully + completed. In other words, an attempt to create "foo/bar/zap" on + a server in which "/" is the hierarchy separator character SHOULD + create foo/ and foo/bar/ if they do not already exist. + + If a new mailbox is created with the same name as a mailbox which + was deleted, its unique identifiers MUST be greater than any + unique identifiers used in the previous incarnation of the mailbox + UNLESS the new incarnation has a different unique identifier + validity value. See the description of the UID command for more + detail. + + Example: C: A003 CREATE owatagusiam/ + S: A003 OK CREATE completed + C: A004 CREATE owatagusiam/blurdybloop + S: A004 OK CREATE completed + + Note: The interpretation of this example depends on whether + "/" was returned as the hierarchy separator from LIST. If + "/" is the hierarchy separator, a new level of hierarchy + named "owatagusiam" with a member called "blurdybloop" is + created. Otherwise, two mailboxes at the same hierarchy + level are created. + + +6.3.4. DELETE Command + + Arguments: mailbox name + + Responses: no specific responses for this command + + Result: OK - delete completed + NO - delete failure: can't delete mailbox with that name + BAD - command unknown or arguments invalid + + + + + + + +Crispin Standards Track [Page 35] + +RFC 3501 IMAPv4 March 2003 + + + The DELETE command permanently removes the mailbox with the given + name. A tagged OK response is returned only if the mailbox has + been deleted. It is an error to attempt to delete INBOX or a + mailbox name that does not exist. + + The DELETE command MUST NOT remove inferior hierarchical names. + For example, if a mailbox "foo" has an inferior "foo.bar" + (assuming "." is the hierarchy delimiter character), removing + "foo" MUST NOT remove "foo.bar". It is an error to attempt to + delete a name that has inferior hierarchical names and also has + the \Noselect mailbox name attribute (see the description of the + LIST response for more details). + + It is permitted to delete a name that has inferior hierarchical + names and does not have the \Noselect mailbox name attribute. In + this case, all messages in that mailbox are removed, and the name + will acquire the \Noselect mailbox name attribute. + + The value of the highest-used unique identifier of the deleted + mailbox MUST be preserved so that a new mailbox created with the + same name will not reuse the identifiers of the former + incarnation, UNLESS the new incarnation has a different unique + identifier validity value. See the description of the UID command + for more detail. + + Examples: C: A682 LIST "" * + S: * LIST () "/" blurdybloop + S: * LIST (\Noselect) "/" foo + S: * LIST () "/" foo/bar + S: A682 OK LIST completed + C: A683 DELETE blurdybloop + S: A683 OK DELETE completed + C: A684 DELETE foo + S: A684 NO Name "foo" has inferior hierarchical names + C: A685 DELETE foo/bar + S: A685 OK DELETE Completed + C: A686 LIST "" * + S: * LIST (\Noselect) "/" foo + S: A686 OK LIST completed + C: A687 DELETE foo + S: A687 OK DELETE Completed + + + + + + + + + + +Crispin Standards Track [Page 36] + +RFC 3501 IMAPv4 March 2003 + + + C: A82 LIST "" * + S: * LIST () "." blurdybloop + S: * LIST () "." foo + S: * LIST () "." foo.bar + S: A82 OK LIST completed + C: A83 DELETE blurdybloop + S: A83 OK DELETE completed + C: A84 DELETE foo + S: A84 OK DELETE Completed + C: A85 LIST "" * + S: * LIST () "." foo.bar + S: A85 OK LIST completed + C: A86 LIST "" % + S: * LIST (\Noselect) "." foo + S: A86 OK LIST completed + + +6.3.5. RENAME Command + + Arguments: existing mailbox name + new mailbox name + + Responses: no specific responses for this command + + Result: OK - rename completed + NO - rename failure: can't rename mailbox with that name, + can't rename to mailbox with that name + BAD - command unknown or arguments invalid + + The RENAME command changes the name of a mailbox. A tagged OK + response is returned only if the mailbox has been renamed. It is + an error to attempt to rename from a mailbox name that does not + exist or to a mailbox name that already exists. Any error in + renaming will return a tagged NO response. + + If the name has inferior hierarchical names, then the inferior + hierarchical names MUST also be renamed. For example, a rename of + "foo" to "zap" will rename "foo/bar" (assuming "/" is the + hierarchy delimiter character) to "zap/bar". + + If the server's hierarchy separator character appears in the name, + the server SHOULD create any superior hierarchical names that are + needed for the RENAME command to complete successfully. In other + words, an attempt to rename "foo/bar/zap" to baz/rag/zowie on a + server in which "/" is the hierarchy separator character SHOULD + create baz/ and baz/rag/ if they do not already exist. + + + + + +Crispin Standards Track [Page 37] + +RFC 3501 IMAPv4 March 2003 + + + The value of the highest-used unique identifier of the old mailbox + name MUST be preserved so that a new mailbox created with the same + name will not reuse the identifiers of the former incarnation, + UNLESS the new incarnation has a different unique identifier + validity value. See the description of the UID command for more + detail. + + Renaming INBOX is permitted, and has special behavior. It moves + all messages in INBOX to a new mailbox with the given name, + leaving INBOX empty. If the server implementation supports + inferior hierarchical names of INBOX, these are unaffected by a + rename of INBOX. + + Examples: C: A682 LIST "" * + S: * LIST () "/" blurdybloop + S: * LIST (\Noselect) "/" foo + S: * LIST () "/" foo/bar + S: A682 OK LIST completed + C: A683 RENAME blurdybloop sarasoop + S: A683 OK RENAME completed + C: A684 RENAME foo zowie + S: A684 OK RENAME Completed + C: A685 LIST "" * + S: * LIST () "/" sarasoop + S: * LIST (\Noselect) "/" zowie + S: * LIST () "/" zowie/bar + S: A685 OK LIST completed + + C: Z432 LIST "" * + S: * LIST () "." INBOX + S: * LIST () "." INBOX.bar + S: Z432 OK LIST completed + C: Z433 RENAME INBOX old-mail + S: Z433 OK RENAME completed + C: Z434 LIST "" * + S: * LIST () "." INBOX + S: * LIST () "." INBOX.bar + S: * LIST () "." old-mail + S: Z434 OK LIST completed + + + + + + + + + + + + +Crispin Standards Track [Page 38] + +RFC 3501 IMAPv4 March 2003 + + +6.3.6. SUBSCRIBE Command + + Arguments: mailbox + + Responses: no specific responses for this command + + Result: OK - subscribe completed + NO - subscribe failure: can't subscribe to that name + BAD - command unknown or arguments invalid + + The SUBSCRIBE command adds the specified mailbox name to the + server's set of "active" or "subscribed" mailboxes as returned by + the LSUB command. This command returns a tagged OK response only + if the subscription is successful. + + A server MAY validate the mailbox argument to SUBSCRIBE to verify + that it exists. However, it MUST NOT unilaterally remove an + existing mailbox name from the subscription list even if a mailbox + by that name no longer exists. + + Note: This requirement is because a server site can + choose to routinely remove a mailbox with a well-known + name (e.g., "system-alerts") after its contents expire, + with the intention of recreating it when new contents + are appropriate. + + + Example: C: A002 SUBSCRIBE #news.comp.mail.mime + S: A002 OK SUBSCRIBE completed + + +6.3.7. UNSUBSCRIBE Command + + Arguments: mailbox name + + Responses: no specific responses for this command + + Result: OK - unsubscribe completed + NO - unsubscribe failure: can't unsubscribe that name + BAD - command unknown or arguments invalid + + The UNSUBSCRIBE command removes the specified mailbox name from + the server's set of "active" or "subscribed" mailboxes as returned + by the LSUB command. This command returns a tagged OK response + only if the unsubscription is successful. + + Example: C: A002 UNSUBSCRIBE #news.comp.mail.mime + S: A002 OK UNSUBSCRIBE completed + + + +Crispin Standards Track [Page 39] + +RFC 3501 IMAPv4 March 2003 + + +6.3.8. LIST Command + + Arguments: reference name + mailbox name with possible wildcards + + Responses: untagged responses: LIST + + Result: OK - list completed + NO - list failure: can't list that reference or name + BAD - command unknown or arguments invalid + + The LIST command returns a subset of names from the complete set + of all names available to the client. Zero or more untagged LIST + replies are returned, containing the name attributes, hierarchy + delimiter, and name; see the description of the LIST reply for + more detail. + + The LIST command SHOULD return its data quickly, without undue + delay. For example, it SHOULD NOT go to excess trouble to + calculate the \Marked or \Unmarked status or perform other + processing; if each name requires 1 second of processing, then a + list of 1200 names would take 20 minutes! + + An empty ("" string) reference name argument indicates that the + mailbox name is interpreted as by SELECT. The returned mailbox + names MUST match the supplied mailbox name pattern. A non-empty + reference name argument is the name of a mailbox or a level of + mailbox hierarchy, and indicates the context in which the mailbox + name is interpreted. + + An empty ("" string) mailbox name argument is a special request to + return the hierarchy delimiter and the root name of the name given + in the reference. The value returned as the root MAY be the empty + string if the reference is non-rooted or is an empty string. In + all cases, a hierarchy delimiter (or NIL if there is no hierarchy) + is returned. This permits a client to get the hierarchy delimiter + (or find out that the mailbox names are flat) even when no + mailboxes by that name currently exist. + + The reference and mailbox name arguments are interpreted into a + canonical form that represents an unambiguous left-to-right + hierarchy. The returned mailbox names will be in the interpreted + form. + + + + + + + + +Crispin Standards Track [Page 40] + +RFC 3501 IMAPv4 March 2003 + + + Note: The interpretation of the reference argument is + implementation-defined. It depends upon whether the + server implementation has a concept of the "current + working directory" and leading "break out characters", + which override the current working directory. + + For example, on a server which exports a UNIX or NT + filesystem, the reference argument contains the current + working directory, and the mailbox name argument would + contain the name as interpreted in the current working + directory. + + If a server implementation has no concept of break out + characters, the canonical form is normally the reference + name appended with the mailbox name. Note that if the + server implements the namespace convention (section + 5.1.2), "#" is a break out character and must be treated + as such. + + If the reference argument is not a level of mailbox + hierarchy (that is, it is a \NoInferiors name), and/or + the reference argument does not end with the hierarchy + delimiter, it is implementation-dependent how this is + interpreted. For example, a reference of "foo/bar" and + mailbox name of "rag/baz" could be interpreted as + "foo/bar/rag/baz", "foo/barrag/baz", or "foo/rag/baz". + A client SHOULD NOT use such a reference argument except + at the explicit request of the user. A hierarchical + browser MUST NOT make any assumptions about server + interpretation of the reference unless the reference is + a level of mailbox hierarchy AND ends with the hierarchy + delimiter. + + Any part of the reference argument that is included in the + interpreted form SHOULD prefix the interpreted form. It SHOULD + also be in the same form as the reference name argument. This + rule permits the client to determine if the returned mailbox name + is in the context of the reference argument, or if something about + the mailbox argument overrode the reference argument. Without + this rule, the client would have to have knowledge of the server's + naming semantics including what characters are "breakouts" that + override a naming context. + + + + + + + + + +Crispin Standards Track [Page 41] + +RFC 3501 IMAPv4 March 2003 + + + For example, here are some examples of how references + and mailbox names might be interpreted on a UNIX-based + server: + + Reference Mailbox Name Interpretation + ------------ ------------ -------------- + ~smith/Mail/ foo.* ~smith/Mail/foo.* + archive/ % archive/% + #news. comp.mail.* #news.comp.mail.* + ~smith/Mail/ /usr/doc/foo /usr/doc/foo + archive/ ~fred/Mail/* ~fred/Mail/* + + The first three examples demonstrate interpretations in + the context of the reference argument. Note that + "~smith/Mail" SHOULD NOT be transformed into something + like "/u2/users/smith/Mail", or it would be impossible + for the client to determine that the interpretation was + in the context of the reference. + + The character "*" is a wildcard, and matches zero or more + characters at this position. The character "%" is similar to "*", + but it does not match a hierarchy delimiter. If the "%" wildcard + is the last character of a mailbox name argument, matching levels + of hierarchy are also returned. If these levels of hierarchy are + not also selectable mailboxes, they are returned with the + \Noselect mailbox name attribute (see the description of the LIST + response for more details). + + Server implementations are permitted to "hide" otherwise + accessible mailboxes from the wildcard characters, by preventing + certain characters or names from matching a wildcard in certain + situations. For example, a UNIX-based server might restrict the + interpretation of "*" so that an initial "/" character does not + match. + + The special name INBOX is included in the output from LIST, if + INBOX is supported by this server for this user and if the + uppercase string "INBOX" matches the interpreted reference and + mailbox name arguments with wildcards as described above. The + criteria for omitting INBOX is whether SELECT INBOX will return + failure; it is not relevant whether the user's real INBOX resides + on this or some other server. + + + + + + + + + +Crispin Standards Track [Page 42] + +RFC 3501 IMAPv4 March 2003 + + + Example: C: A101 LIST "" "" + S: * LIST (\Noselect) "/" "" + S: A101 OK LIST Completed + C: A102 LIST #news.comp.mail.misc "" + S: * LIST (\Noselect) "." #news. + S: A102 OK LIST Completed + C: A103 LIST /usr/staff/jones "" + S: * LIST (\Noselect) "/" / + S: A103 OK LIST Completed + C: A202 LIST ~/Mail/ % + S: * LIST (\Noselect) "/" ~/Mail/foo + S: * LIST () "/" ~/Mail/meetings + S: A202 OK LIST completed + + +6.3.9. LSUB Command + + Arguments: reference name + mailbox name with possible wildcards + + Responses: untagged responses: LSUB + + Result: OK - lsub completed + NO - lsub failure: can't list that reference or name + BAD - command unknown or arguments invalid + + The LSUB command returns a subset of names from the set of names + that the user has declared as being "active" or "subscribed". + Zero or more untagged LSUB replies are returned. The arguments to + LSUB are in the same form as those for LIST. + + The returned untagged LSUB response MAY contain different mailbox + flags from a LIST untagged response. If this should happen, the + flags in the untagged LIST are considered more authoritative. + + A special situation occurs when using LSUB with the % wildcard. + Consider what happens if "foo/bar" (with a hierarchy delimiter of + "/") is subscribed but "foo" is not. A "%" wildcard to LSUB must + return foo, not foo/bar, in the LSUB response, and it MUST be + flagged with the \Noselect attribute. + + The server MUST NOT unilaterally remove an existing mailbox name + from the subscription list even if a mailbox by that name no + longer exists. + + + + + + + +Crispin Standards Track [Page 43] + +RFC 3501 IMAPv4 March 2003 + + + Example: C: A002 LSUB "#news." "comp.mail.*" + S: * LSUB () "." #news.comp.mail.mime + S: * LSUB () "." #news.comp.mail.misc + S: A002 OK LSUB completed + C: A003 LSUB "#news." "comp.%" + S: * LSUB (\NoSelect) "." #news.comp.mail + S: A003 OK LSUB completed + + +6.3.10. STATUS Command + + Arguments: mailbox name + status data item names + + Responses: untagged responses: STATUS + + Result: OK - status completed + NO - status failure: no status for that name + BAD - command unknown or arguments invalid + + The STATUS command requests the status of the indicated mailbox. + It does not change the currently selected mailbox, nor does it + affect the state of any messages in the queried mailbox (in + particular, STATUS MUST NOT cause messages to lose the \Recent + flag). + + The STATUS command provides an alternative to opening a second + IMAP4rev1 connection and doing an EXAMINE command on a mailbox to + query that mailbox's status without deselecting the current + mailbox in the first IMAP4rev1 connection. + + Unlike the LIST command, the STATUS command is not guaranteed to + be fast in its response. Under certain circumstances, it can be + quite slow. In some implementations, the server is obliged to + open the mailbox read-only internally to obtain certain status + information. Also unlike the LIST command, the STATUS command + does not accept wildcards. + + Note: The STATUS command is intended to access the + status of mailboxes other than the currently selected + mailbox. Because the STATUS command can cause the + mailbox to be opened internally, and because this + information is available by other means on the selected + mailbox, the STATUS command SHOULD NOT be used on the + currently selected mailbox. + + + + + + +Crispin Standards Track [Page 44] + +RFC 3501 IMAPv4 March 2003 + + + The STATUS command MUST NOT be used as a "check for new + messages in the selected mailbox" operation (refer to + sections 7, 7.3.1, and 7.3.2 for more information about + the proper method for new message checking). + + Because the STATUS command is not guaranteed to be fast + in its results, clients SHOULD NOT expect to be able to + issue many consecutive STATUS commands and obtain + reasonable performance. + + The currently defined status data items that can be requested are: + + MESSAGES + The number of messages in the mailbox. + + RECENT + The number of messages with the \Recent flag set. + + UIDNEXT + The next unique identifier value of the mailbox. Refer to + section 2.3.1.1 for more information. + + UIDVALIDITY + The unique identifier validity value of the mailbox. Refer to + section 2.3.1.1 for more information. + + UNSEEN + The number of messages which do not have the \Seen flag set. + + + Example: C: A042 STATUS blurdybloop (UIDNEXT MESSAGES) + S: * STATUS blurdybloop (MESSAGES 231 UIDNEXT 44292) + S: A042 OK STATUS completed + + + + + + + + + + + + + + + + + + +Crispin Standards Track [Page 45] + +RFC 3501 IMAPv4 March 2003 + + +6.3.11. APPEND Command + + Arguments: mailbox name + OPTIONAL flag parenthesized list + OPTIONAL date/time string + message literal + + Responses: no specific responses for this command + + Result: OK - append completed + NO - append error: can't append to that mailbox, error + in flags or date/time or message text + BAD - command unknown or arguments invalid + + The APPEND command appends the literal argument as a new message + to the end of the specified destination mailbox. This argument + SHOULD be in the format of an [RFC-2822] message. 8-bit + characters are permitted in the message. A server implementation + that is unable to preserve 8-bit data properly MUST be able to + reversibly convert 8-bit APPEND data to 7-bit using a [MIME-IMB] + content transfer encoding. + + Note: There MAY be exceptions, e.g., draft messages, in + which required [RFC-2822] header lines are omitted in + the message literal argument to APPEND. The full + implications of doing so MUST be understood and + carefully weighed. + + If a flag parenthesized list is specified, the flags SHOULD be set + in the resulting message; otherwise, the flag list of the + resulting message is set to empty by default. In either case, the + Recent flag is also set. + + If a date-time is specified, the internal date SHOULD be set in + the resulting message; otherwise, the internal date of the + resulting message is set to the current date and time by default. + + If the append is unsuccessful for any reason, the mailbox MUST be + restored to its state before the APPEND attempt; no partial + appending is permitted. + + If the destination mailbox does not exist, a server MUST return an + error, and MUST NOT automatically create the mailbox. Unless it + is certain that the destination mailbox can not be created, the + server MUST send the response code "[TRYCREATE]" as the prefix of + the text of the tagged NO response. This gives a hint to the + client that it can attempt a CREATE command and retry the APPEND + if the CREATE is successful. + + + +Crispin Standards Track [Page 46] + +RFC 3501 IMAPv4 March 2003 + + + If the mailbox is currently selected, the normal new message + actions SHOULD occur. Specifically, the server SHOULD notify the + client immediately via an untagged EXISTS response. If the server + does not do so, the client MAY issue a NOOP command (or failing + that, a CHECK command) after one or more APPEND commands. + + Example: C: A003 APPEND saved-messages (\Seen) {310} + S: + Ready for literal data + C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) + C: From: Fred Foobar <foobar@Blurdybloop.COM> + C: Subject: afternoon meeting + C: To: mooch@owatagu.siam.edu + C: Message-Id: <B27397-0100000@Blurdybloop.COM> + C: MIME-Version: 1.0 + C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII + C: + C: Hello Joe, do you think we can meet at 3:30 tomorrow? + C: + S: A003 OK APPEND completed + + Note: The APPEND command is not used for message delivery, + because it does not provide a mechanism to transfer [SMTP] + envelope information. + +6.4. Client Commands - Selected State + + In the selected state, commands that manipulate messages in a mailbox + are permitted. + + In addition to the universal commands (CAPABILITY, NOOP, and LOGOUT), + and the authenticated state commands (SELECT, EXAMINE, CREATE, + DELETE, RENAME, SUBSCRIBE, UNSUBSCRIBE, LIST, LSUB, STATUS, and + APPEND), the following commands are valid in the selected state: + CHECK, CLOSE, EXPUNGE, SEARCH, FETCH, STORE, COPY, and UID. + +6.4.1. CHECK Command + + Arguments: none + + Responses: no specific responses for this command + + Result: OK - check completed + BAD - command unknown or arguments invalid + + The CHECK command requests a checkpoint of the currently selected + mailbox. A checkpoint refers to any implementation-dependent + housekeeping associated with the mailbox (e.g., resolving the + server's in-memory state of the mailbox with the state on its + + + +Crispin Standards Track [Page 47] + +RFC 3501 IMAPv4 March 2003 + + + disk) that is not normally executed as part of each command. A + checkpoint MAY take a non-instantaneous amount of real time to + complete. If a server implementation has no such housekeeping + considerations, CHECK is equivalent to NOOP. + + There is no guarantee that an EXISTS untagged response will happen + as a result of CHECK. NOOP, not CHECK, SHOULD be used for new + message polling. + + Example: C: FXXZ CHECK + S: FXXZ OK CHECK Completed + + +6.4.2. CLOSE Command + + Arguments: none + + Responses: no specific responses for this command + + Result: OK - close completed, now in authenticated state + BAD - command unknown or arguments invalid + + The CLOSE command permanently removes all messages that have the + \Deleted flag set from the currently selected mailbox, and returns + to the authenticated state from the selected state. No untagged + EXPUNGE responses are sent. + + No messages are removed, and no error is given, if the mailbox is + selected by an EXAMINE command or is otherwise selected read-only. + + Even if a mailbox is selected, a SELECT, EXAMINE, or LOGOUT + command MAY be issued without previously issuing a CLOSE command. + The SELECT, EXAMINE, and LOGOUT commands implicitly close the + currently selected mailbox without doing an expunge. However, + when many messages are deleted, a CLOSE-LOGOUT or CLOSE-SELECT + sequence is considerably faster than an EXPUNGE-LOGOUT or + EXPUNGE-SELECT because no untagged EXPUNGE responses (which the + client would probably ignore) are sent. + + Example: C: A341 CLOSE + S: A341 OK CLOSE completed + + + + + + + + + + +Crispin Standards Track [Page 48] + +RFC 3501 IMAPv4 March 2003 + + +6.4.3. EXPUNGE Command + + Arguments: none + + Responses: untagged responses: EXPUNGE + + Result: OK - expunge completed + NO - expunge failure: can't expunge (e.g., permission + denied) + BAD - command unknown or arguments invalid + + The EXPUNGE command permanently removes all messages that have the + \Deleted flag set from the currently selected mailbox. Before + returning an OK to the client, an untagged EXPUNGE response is + sent for each message that is removed. + + Example: C: A202 EXPUNGE + S: * 3 EXPUNGE + S: * 3 EXPUNGE + S: * 5 EXPUNGE + S: * 8 EXPUNGE + S: A202 OK EXPUNGE completed + + Note: In this example, messages 3, 4, 7, and 11 had the + \Deleted flag set. See the description of the EXPUNGE + response for further explanation. + + +6.4.4. SEARCH Command + + Arguments: OPTIONAL [CHARSET] specification + searching criteria (one or more) + + Responses: REQUIRED untagged response: SEARCH + + Result: OK - search completed + NO - search error: can't search that [CHARSET] or + criteria + BAD - command unknown or arguments invalid + + The SEARCH command searches the mailbox for messages that match + the given searching criteria. Searching criteria consist of one + or more search keys. The untagged SEARCH response from the server + contains a listing of message sequence numbers corresponding to + those messages that match the searching criteria. + + + + + + +Crispin Standards Track [Page 49] + +RFC 3501 IMAPv4 March 2003 + + + When multiple keys are specified, the result is the intersection + (AND function) of all the messages that match those keys. For + example, the criteria DELETED FROM "SMITH" SINCE 1-Feb-1994 refers + to all deleted messages from Smith that were placed in the mailbox + since February 1, 1994. A search key can also be a parenthesized + list of one or more search keys (e.g., for use with the OR and NOT + keys). + + Server implementations MAY exclude [MIME-IMB] body parts with + terminal content media types other than TEXT and MESSAGE from + consideration in SEARCH matching. + + The OPTIONAL [CHARSET] specification consists of the word + "CHARSET" followed by a registered [CHARSET]. It indicates the + [CHARSET] of the strings that appear in the search criteria. + [MIME-IMB] content transfer encodings, and [MIME-HDRS] strings in + [RFC-2822]/[MIME-IMB] headers, MUST be decoded before comparing + text in a [CHARSET] other than US-ASCII. US-ASCII MUST be + supported; other [CHARSET]s MAY be supported. + + If the server does not support the specified [CHARSET], it MUST + return a tagged NO response (not a BAD). This response SHOULD + contain the BADCHARSET response code, which MAY list the + [CHARSET]s supported by the server. + + In all search keys that use strings, a message matches the key if + the string is a substring of the field. The matching is + case-insensitive. + + The defined search keys are as follows. Refer to the Formal + Syntax section for the precise syntactic definitions of the + arguments. + + <sequence set> + Messages with message sequence numbers corresponding to the + specified message sequence number set. + + ALL + All messages in the mailbox; the default initial key for + ANDing. + + ANSWERED + Messages with the \Answered flag set. + + + + + + + + +Crispin Standards Track [Page 50] + +RFC 3501 IMAPv4 March 2003 + + + BCC <string> + Messages that contain the specified string in the envelope + structure's BCC field. + + BEFORE <date> + Messages whose internal date (disregarding time and timezone) + is earlier than the specified date. + + BODY <string> + Messages that contain the specified string in the body of the + message. + + CC <string> + Messages that contain the specified string in the envelope + structure's CC field. + + DELETED + Messages with the \Deleted flag set. + + DRAFT + Messages with the \Draft flag set. + + FLAGGED + Messages with the \Flagged flag set. + + FROM <string> + Messages that contain the specified string in the envelope + structure's FROM field. + + HEADER <field-name> <string> + Messages that have a header with the specified field-name (as + defined in [RFC-2822]) and that contains the specified string + in the text of the header (what comes after the colon). If the + string to search is zero-length, this matches all messages that + have a header line with the specified field-name regardless of + the contents. + + KEYWORD <flag> + Messages with the specified keyword flag set. + + LARGER <n> + Messages with an [RFC-2822] size larger than the specified + number of octets. + + NEW + Messages that have the \Recent flag set but not the \Seen flag. + This is functionally equivalent to "(RECENT UNSEEN)". + + + + +Crispin Standards Track [Page 51] + +RFC 3501 IMAPv4 March 2003 + + + NOT <search-key> + Messages that do not match the specified search key. + + OLD + Messages that do not have the \Recent flag set. This is + functionally equivalent to "NOT RECENT" (as opposed to "NOT + NEW"). + + ON <date> + Messages whose internal date (disregarding time and timezone) + is within the specified date. + + OR <search-key1> <search-key2> + Messages that match either search key. + + RECENT + Messages that have the \Recent flag set. + + SEEN + Messages that have the \Seen flag set. + + SENTBEFORE <date> + Messages whose [RFC-2822] Date: header (disregarding time and + timezone) is earlier than the specified date. + + SENTON <date> + Messages whose [RFC-2822] Date: header (disregarding time and + timezone) is within the specified date. + + SENTSINCE <date> + Messages whose [RFC-2822] Date: header (disregarding time and + timezone) is within or later than the specified date. + + SINCE <date> + Messages whose internal date (disregarding time and timezone) + is within or later than the specified date. + + SMALLER <n> + Messages with an [RFC-2822] size smaller than the specified + number of octets. + + + + + + + + + + + +Crispin Standards Track [Page 52] + +RFC 3501 IMAPv4 March 2003 + + + SUBJECT <string> + Messages that contain the specified string in the envelope + structure's SUBJECT field. + + TEXT <string> + Messages that contain the specified string in the header or + body of the message. + + TO <string> + Messages that contain the specified string in the envelope + structure's TO field. + + UID <sequence set> + Messages with unique identifiers corresponding to the specified + unique identifier set. Sequence set ranges are permitted. + + UNANSWERED + Messages that do not have the \Answered flag set. + + UNDELETED + Messages that do not have the \Deleted flag set. + + UNDRAFT + Messages that do not have the \Draft flag set. + + UNFLAGGED + Messages that do not have the \Flagged flag set. + + UNKEYWORD <flag> + Messages that do not have the specified keyword flag set. + + UNSEEN + Messages that do not have the \Seen flag set. + + + + + + + + + + + + + + + + + + +Crispin Standards Track [Page 53] + +RFC 3501 IMAPv4 March 2003 + + + Example: C: A282 SEARCH FLAGGED SINCE 1-Feb-1994 NOT FROM "Smith" + S: * SEARCH 2 84 882 + S: A282 OK SEARCH completed + C: A283 SEARCH TEXT "string not in mailbox" + S: * SEARCH + S: A283 OK SEARCH completed + C: A284 SEARCH CHARSET UTF-8 TEXT {6} + C: XXXXXX + S: * SEARCH 43 + S: A284 OK SEARCH completed + + Note: Since this document is restricted to 7-bit ASCII + text, it is not possible to show actual UTF-8 data. The + "XXXXXX" is a placeholder for what would be 6 octets of + 8-bit data in an actual transaction. + + +6.4.5. FETCH Command + + Arguments: sequence set + message data item names or macro + + Responses: untagged responses: FETCH + + Result: OK - fetch completed + NO - fetch error: can't fetch that data + BAD - command unknown or arguments invalid + + The FETCH command retrieves data associated with a message in the + mailbox. The data items to be fetched can be either a single atom + or a parenthesized list. + + Most data items, identified in the formal syntax under the + msg-att-static rule, are static and MUST NOT change for any + particular message. Other data items, identified in the formal + syntax under the msg-att-dynamic rule, MAY change, either as a + result of a STORE command or due to external events. + + For example, if a client receives an ENVELOPE for a + message when it already knows the envelope, it can + safely ignore the newly transmitted envelope. + + There are three macros which specify commonly-used sets of data + items, and can be used instead of data items. A macro must be + used by itself, and not in conjunction with other macros or data + items. + + + + + +Crispin Standards Track [Page 54] + +RFC 3501 IMAPv4 March 2003 + + + ALL + Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE) + + FAST + Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE) + + FULL + Macro equivalent to: (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE + BODY) + + The currently defined data items that can be fetched are: + + BODY + Non-extensible form of BODYSTRUCTURE. + + BODY[<section>]<<partial>> + The text of a particular body section. The section + specification is a set of zero or more part specifiers + delimited by periods. A part specifier is either a part number + or one of the following: HEADER, HEADER.FIELDS, + HEADER.FIELDS.NOT, MIME, and TEXT. An empty section + specification refers to the entire message, including the + header. + + Every message has at least one part number. Non-[MIME-IMB] + messages, and non-multipart [MIME-IMB] messages with no + encapsulated message, only have a part 1. + + Multipart messages are assigned consecutive part numbers, as + they occur in the message. If a particular part is of type + message or multipart, its parts MUST be indicated by a period + followed by the part number within that nested multipart part. + + A part of type MESSAGE/RFC822 also has nested part numbers, + referring to parts of the MESSAGE part's body. + + The HEADER, HEADER.FIELDS, HEADER.FIELDS.NOT, and TEXT part + specifiers can be the sole part specifier or can be prefixed by + one or more numeric part specifiers, provided that the numeric + part specifier refers to a part of type MESSAGE/RFC822. The + MIME part specifier MUST be prefixed by one or more numeric + part specifiers. + + The HEADER, HEADER.FIELDS, and HEADER.FIELDS.NOT part + specifiers refer to the [RFC-2822] header of the message or of + an encapsulated [MIME-IMT] MESSAGE/RFC822 message. + HEADER.FIELDS and HEADER.FIELDS.NOT are followed by a list of + field-name (as defined in [RFC-2822]) names, and return a + + + +Crispin Standards Track [Page 55] + +RFC 3501 IMAPv4 March 2003 + + + subset of the header. The subset returned by HEADER.FIELDS + contains only those header fields with a field-name that + matches one of the names in the list; similarly, the subset + returned by HEADER.FIELDS.NOT contains only the header fields + with a non-matching field-name. The field-matching is + case-insensitive but otherwise exact. Subsetting does not + exclude the [RFC-2822] delimiting blank line between the header + and the body; the blank line is included in all header fetches, + except in the case of a message which has no body and no blank + line. + + The MIME part specifier refers to the [MIME-IMB] header for + this part. + + The TEXT part specifier refers to the text body of the message, + omitting the [RFC-2822] header. + + Here is an example of a complex message with some of its + part specifiers: + + HEADER ([RFC-2822] header of the message) + TEXT ([RFC-2822] text body of the message) MULTIPART/MIXED + 1 TEXT/PLAIN + 2 APPLICATION/OCTET-STREAM + 3 MESSAGE/RFC822 + 3.HEADER ([RFC-2822] header of the message) + 3.TEXT ([RFC-2822] text body of the message) MULTIPART/MIXED + 3.1 TEXT/PLAIN + 3.2 APPLICATION/OCTET-STREAM + 4 MULTIPART/MIXED + 4.1 IMAGE/GIF + 4.1.MIME ([MIME-IMB] header for the IMAGE/GIF) + 4.2 MESSAGE/RFC822 + 4.2.HEADER ([RFC-2822] header of the message) + 4.2.TEXT ([RFC-2822] text body of the message) MULTIPART/MIXED + 4.2.1 TEXT/PLAIN + 4.2.2 MULTIPART/ALTERNATIVE + 4.2.2.1 TEXT/PLAIN + 4.2.2.2 TEXT/RICHTEXT + + + It is possible to fetch a substring of the designated text. + This is done by appending an open angle bracket ("<"), the + octet position of the first desired octet, a period, the + maximum number of octets desired, and a close angle bracket + (">") to the part specifier. If the starting octet is beyond + the end of the text, an empty string is returned. + + + + +Crispin Standards Track [Page 56] + +RFC 3501 IMAPv4 March 2003 + + + Any partial fetch that attempts to read beyond the end of the + text is truncated as appropriate. A partial fetch that starts + at octet 0 is returned as a partial fetch, even if this + truncation happened. + + Note: This means that BODY[]<0.2048> of a 1500-octet message + will return BODY[]<0> with a literal of size 1500, not + BODY[]. + + Note: A substring fetch of a HEADER.FIELDS or + HEADER.FIELDS.NOT part specifier is calculated after + subsetting the header. + + The \Seen flag is implicitly set; if this causes the flags to + change, they SHOULD be included as part of the FETCH responses. + + BODY.PEEK[<section>]<<partial>> + An alternate form of BODY[<section>] that does not implicitly + set the \Seen flag. + + BODYSTRUCTURE + The [MIME-IMB] body structure of the message. This is computed + by the server by parsing the [MIME-IMB] header fields in the + [RFC-2822] header and [MIME-IMB] headers. + + ENVELOPE + The envelope structure of the message. This is computed by the + server by parsing the [RFC-2822] header into the component + parts, defaulting various fields as necessary. + + FLAGS + The flags that are set for this message. + + INTERNALDATE + The internal date of the message. + + RFC822 + Functionally equivalent to BODY[], differing in the syntax of + the resulting untagged FETCH data (RFC822 is returned). + + RFC822.HEADER + Functionally equivalent to BODY.PEEK[HEADER], differing in the + syntax of the resulting untagged FETCH data (RFC822.HEADER is + returned). + + RFC822.SIZE + The [RFC-2822] size of the message. + + + + +Crispin Standards Track [Page 57] + +RFC 3501 IMAPv4 March 2003 + + + RFC822.TEXT + Functionally equivalent to BODY[TEXT], differing in the syntax + of the resulting untagged FETCH data (RFC822.TEXT is returned). + + UID + The unique identifier for the message. + + + Example: C: A654 FETCH 2:4 (FLAGS BODY[HEADER.FIELDS (DATE FROM)]) + S: * 2 FETCH .... + S: * 3 FETCH .... + S: * 4 FETCH .... + S: A654 OK FETCH completed + + +6.4.6. STORE Command + + Arguments: sequence set + message data item name + value for message data item + + Responses: untagged responses: FETCH + + Result: OK - store completed + NO - store error: can't store that data + BAD - command unknown or arguments invalid + + The STORE command alters data associated with a message in the + mailbox. Normally, STORE will return the updated value of the + data with an untagged FETCH response. A suffix of ".SILENT" in + the data item name prevents the untagged FETCH, and the server + SHOULD assume that the client has determined the updated value + itself or does not care about the updated value. + + Note: Regardless of whether or not the ".SILENT" suffix + was used, the server SHOULD send an untagged FETCH + response if a change to a message's flags from an + external source is observed. The intent is that the + status of the flags is determinate without a race + condition. + + + + + + + + + + + +Crispin Standards Track [Page 58] + +RFC 3501 IMAPv4 March 2003 + + + The currently defined data items that can be stored are: + + FLAGS <flag list> + Replace the flags for the message (other than \Recent) with the + argument. The new value of the flags is returned as if a FETCH + of those flags was done. + + FLAGS.SILENT <flag list> + Equivalent to FLAGS, but without returning a new value. + + +FLAGS <flag list> + Add the argument to the flags for the message. The new value + of the flags is returned as if a FETCH of those flags was done. + + +FLAGS.SILENT <flag list> + Equivalent to +FLAGS, but without returning a new value. + + -FLAGS <flag list> + Remove the argument from the flags for the message. The new + value of the flags is returned as if a FETCH of those flags was + done. + + -FLAGS.SILENT <flag list> + Equivalent to -FLAGS, but without returning a new value. + + + Example: C: A003 STORE 2:4 +FLAGS (\Deleted) + S: * 2 FETCH (FLAGS (\Deleted \Seen)) + S: * 3 FETCH (FLAGS (\Deleted)) + S: * 4 FETCH (FLAGS (\Deleted \Flagged \Seen)) + S: A003 OK STORE completed + + +6.4.7. COPY Command + + Arguments: sequence set + mailbox name + + Responses: no specific responses for this command + + Result: OK - copy completed + NO - copy error: can't copy those messages or to that + name + BAD - command unknown or arguments invalid + + + + + + + +Crispin Standards Track [Page 59] + +RFC 3501 IMAPv4 March 2003 + + + The COPY command copies the specified message(s) to the end of the + specified destination mailbox. The flags and internal date of the + message(s) SHOULD be preserved, and the Recent flag SHOULD be set, + in the copy. + + If the destination mailbox does not exist, a server SHOULD return + an error. It SHOULD NOT automatically create the mailbox. Unless + it is certain that the destination mailbox can not be created, the + server MUST send the response code "[TRYCREATE]" as the prefix of + the text of the tagged NO response. This gives a hint to the + client that it can attempt a CREATE command and retry the COPY if + the CREATE is successful. + + If the COPY command is unsuccessful for any reason, server + implementations MUST restore the destination mailbox to its state + before the COPY attempt. + + Example: C: A003 COPY 2:4 MEETING + S: A003 OK COPY completed + + +6.4.8. UID Command + + Arguments: command name + command arguments + + Responses: untagged responses: FETCH, SEARCH + + Result: OK - UID command completed + NO - UID command error + BAD - command unknown or arguments invalid + + The UID command has two forms. In the first form, it takes as its + arguments a COPY, FETCH, or STORE command with arguments + appropriate for the associated command. However, the numbers in + the sequence set argument are unique identifiers instead of + message sequence numbers. Sequence set ranges are permitted, but + there is no guarantee that unique identifiers will be contiguous. + + A non-existent unique identifier is ignored without any error + message generated. Thus, it is possible for a UID FETCH command + to return an OK without any data or a UID COPY or UID STORE to + return an OK without performing any operations. + + In the second form, the UID command takes a SEARCH command with + SEARCH command arguments. The interpretation of the arguments is + the same as with SEARCH; however, the numbers returned in a SEARCH + response for a UID SEARCH command are unique identifiers instead + + + +Crispin Standards Track [Page 60] + +RFC 3501 IMAPv4 March 2003 + + + of message sequence numbers. For example, the command UID SEARCH + 1:100 UID 443:557 returns the unique identifiers corresponding to + the intersection of two sequence sets, the message sequence number + range 1:100 and the UID range 443:557. + + Note: in the above example, the UID range 443:557 + appears. The same comment about a non-existent unique + identifier being ignored without any error message also + applies here. Hence, even if neither UID 443 or 557 + exist, this range is valid and would include an existing + UID 495. + + Also note that a UID range of 559:* always includes the + UID of the last message in the mailbox, even if 559 is + higher than any assigned UID value. This is because the + contents of a range are independent of the order of the + range endpoints. Thus, any UID range with * as one of + the endpoints indicates at least one message (the + message with the highest numbered UID), unless the + mailbox is empty. + + The number after the "*" in an untagged FETCH response is always a + message sequence number, not a unique identifier, even for a UID + command response. However, server implementations MUST implicitly + include the UID message data item as part of any FETCH response + caused by a UID command, regardless of whether a UID was specified + as a message data item to the FETCH. + + + Note: The rule about including the UID message data item as part + of a FETCH response primarily applies to the UID FETCH and UID + STORE commands, including a UID FETCH command that does not + include UID as a message data item. Although it is unlikely that + the other UID commands will cause an untagged FETCH, this rule + applies to these commands as well. + + Example: C: A999 UID FETCH 4827313:4828442 FLAGS + S: * 23 FETCH (FLAGS (\Seen) UID 4827313) + S: * 24 FETCH (FLAGS (\Seen) UID 4827943) + S: * 25 FETCH (FLAGS (\Seen) UID 4828442) + S: A999 OK UID FETCH completed + + + + + + + + + + +Crispin Standards Track [Page 61] + +RFC 3501 IMAPv4 March 2003 + + +6.5. Client Commands - Experimental/Expansion + + +6.5.1. X<atom> Command + + Arguments: implementation defined + + Responses: implementation defined + + Result: OK - command completed + NO - failure + BAD - command unknown or arguments invalid + + Any command prefixed with an X is an experimental command. + Commands which are not part of this specification, a standard or + standards-track revision of this specification, or an + IESG-approved experimental protocol, MUST use the X prefix. + + Any added untagged responses issued by an experimental command + MUST also be prefixed with an X. Server implementations MUST NOT + send any such untagged responses, unless the client requested it + by issuing the associated experimental command. + + Example: C: a441 CAPABILITY + S: * CAPABILITY IMAP4rev1 XPIG-LATIN + S: a441 OK CAPABILITY completed + C: A442 XPIG-LATIN + S: * XPIG-LATIN ow-nay eaking-spay ig-pay atin-lay + S: A442 OK XPIG-LATIN ompleted-cay + +7. Server Responses + + Server responses are in three forms: status responses, server data, + and command continuation request. The information contained in a + server response, identified by "Contents:" in the response + descriptions below, is described by function, not by syntax. The + precise syntax of server responses is described in the Formal Syntax + section. + + The client MUST be prepared to accept any response at all times. + + Status responses can be tagged or untagged. Tagged status responses + indicate the completion result (OK, NO, or BAD status) of a client + command, and have a tag matching the command. + + Some status responses, and all server data, are untagged. An + untagged response is indicated by the token "*" instead of a tag. + Untagged status responses indicate server greeting, or server status + + + +Crispin Standards Track [Page 62] + +RFC 3501 IMAPv4 March 2003 + + + that does not indicate the completion of a command (for example, an + impending system shutdown alert). For historical reasons, untagged + server data responses are also called "unsolicited data", although + strictly speaking, only unilateral server data is truly + "unsolicited". + + Certain server data MUST be recorded by the client when it is + received; this is noted in the description of that data. Such data + conveys critical information which affects the interpretation of all + subsequent commands and responses (e.g., updates reflecting the + creation or destruction of messages). + + Other server data SHOULD be recorded for later reference; if the + client does not need to record the data, or if recording the data has + no obvious purpose (e.g., a SEARCH response when no SEARCH command is + in progress), the data SHOULD be ignored. + + An example of unilateral untagged server data occurs when the IMAP + connection is in the selected state. In the selected state, the + server checks the mailbox for new messages as part of command + execution. Normally, this is part of the execution of every command; + hence, a NOOP command suffices to check for new messages. If new + messages are found, the server sends untagged EXISTS and RECENT + responses reflecting the new size of the mailbox. Server + implementations that offer multiple simultaneous access to the same + mailbox SHOULD also send appropriate unilateral untagged FETCH and + EXPUNGE responses if another agent changes the state of any message + flags or expunges any messages. + + Command continuation request responses use the token "+" instead of a + tag. These responses are sent by the server to indicate acceptance + of an incomplete client command and readiness for the remainder of + the command. + +7.1. Server Responses - Status Responses + + Status responses are OK, NO, BAD, PREAUTH and BYE. OK, NO, and BAD + can be tagged or untagged. PREAUTH and BYE are always untagged. + + Status responses MAY include an OPTIONAL "response code". A response + code consists of data inside square brackets in the form of an atom, + possibly followed by a space and arguments. The response code + contains additional information or status codes for client software + beyond the OK/NO/BAD condition, and are defined when there is a + specific action that a client can take based upon the additional + information. + + + + + +Crispin Standards Track [Page 63] + +RFC 3501 IMAPv4 March 2003 + + + The currently defined response codes are: + + ALERT + + The human-readable text contains a special alert that MUST be + presented to the user in a fashion that calls the user's + attention to the message. + + BADCHARSET + + Optionally followed by a parenthesized list of charsets. A + SEARCH failed because the given charset is not supported by + this implementation. If the optional list of charsets is + given, this lists the charsets that are supported by this + implementation. + + CAPABILITY + + Followed by a list of capabilities. This can appear in the + initial OK or PREAUTH response to transmit an initial + capabilities list. This makes it unnecessary for a client to + send a separate CAPABILITY command if it recognizes this + response. + + PARSE + + The human-readable text represents an error in parsing the + [RFC-2822] header or [MIME-IMB] headers of a message in the + mailbox. + + PERMANENTFLAGS + + Followed by a parenthesized list of flags, indicates which of + the known flags the client can change permanently. Any flags + that are in the FLAGS untagged response, but not the + PERMANENTFLAGS list, can not be set permanently. If the client + attempts to STORE a flag that is not in the PERMANENTFLAGS + list, the server will either ignore the change or store the + state change for the remainder of the current session only. + The PERMANENTFLAGS list can also include the special flag \*, + which indicates that it is possible to create new keywords by + attempting to store those flags in the mailbox. + + + + + + + + + +Crispin Standards Track [Page 64] + +RFC 3501 IMAPv4 March 2003 + + + READ-ONLY + + The mailbox is selected read-only, or its access while selected + has changed from read-write to read-only. + + READ-WRITE + + The mailbox is selected read-write, or its access while + selected has changed from read-only to read-write. + + TRYCREATE + + An APPEND or COPY attempt is failing because the target mailbox + does not exist (as opposed to some other reason). This is a + hint to the client that the operation can succeed if the + mailbox is first created by the CREATE command. + + UIDNEXT + + Followed by a decimal number, indicates the next unique + identifier value. Refer to section 2.3.1.1 for more + information. + + UIDVALIDITY + + Followed by a decimal number, indicates the unique identifier + validity value. Refer to section 2.3.1.1 for more information. + + UNSEEN + + Followed by a decimal number, indicates the number of the first + message without the \Seen flag set. + + Additional response codes defined by particular client or server + implementations SHOULD be prefixed with an "X" until they are + added to a revision of this protocol. Client implementations + SHOULD ignore response codes that they do not recognize. + +7.1.1. OK Response + + Contents: OPTIONAL response code + human-readable text + + The OK response indicates an information message from the server. + When tagged, it indicates successful completion of the associated + command. The human-readable text MAY be presented to the user as + an information message. The untagged form indicates an + + + + +Crispin Standards Track [Page 65] + +RFC 3501 IMAPv4 March 2003 + + + information-only message; the nature of the information MAY be + indicated by a response code. + + The untagged form is also used as one of three possible greetings + at connection startup. It indicates that the connection is not + yet authenticated and that a LOGIN command is needed. + + Example: S: * OK IMAP4rev1 server ready + C: A001 LOGIN fred blurdybloop + S: * OK [ALERT] System shutdown in 10 minutes + S: A001 OK LOGIN Completed + + +7.1.2. NO Response + + Contents: OPTIONAL response code + human-readable text + + The NO response indicates an operational error message from the + server. When tagged, it indicates unsuccessful completion of the + associated command. The untagged form indicates a warning; the + command can still complete successfully. The human-readable text + describes the condition. + + Example: C: A222 COPY 1:2 owatagusiam + S: * NO Disk is 98% full, please delete unnecessary data + S: A222 OK COPY completed + C: A223 COPY 3:200 blurdybloop + S: * NO Disk is 98% full, please delete unnecessary data + S: * NO Disk is 99% full, please delete unnecessary data + S: A223 NO COPY failed: disk is full + + +7.1.3. BAD Response + + Contents: OPTIONAL response code + human-readable text + + The BAD response indicates an error message from the server. When + tagged, it reports a protocol-level error in the client's command; + the tag indicates the command that caused the error. The untagged + form indicates a protocol-level error for which the associated + command can not be determined; it can also indicate an internal + server failure. The human-readable text describes the condition. + + + + + + + +Crispin Standards Track [Page 66] + +RFC 3501 IMAPv4 March 2003 + + + Example: C: ...very long command line... + S: * BAD Command line too long + C: ...empty line... + S: * BAD Empty command line + C: A443 EXPUNGE + S: * BAD Disk crash, attempting salvage to a new disk! + S: * OK Salvage successful, no data lost + S: A443 OK Expunge completed + + +7.1.4. PREAUTH Response + + Contents: OPTIONAL response code + human-readable text + + The PREAUTH response is always untagged, and is one of three + possible greetings at connection startup. It indicates that the + connection has already been authenticated by external means; thus + no LOGIN command is needed. + + Example: S: * PREAUTH IMAP4rev1 server logged in as Smith + + +7.1.5. BYE Response + + Contents: OPTIONAL response code + human-readable text + + The BYE response is always untagged, and indicates that the server + is about to close the connection. The human-readable text MAY be + displayed to the user in a status report by the client. The BYE + response is sent under one of four conditions: + + 1) as part of a normal logout sequence. The server will close + the connection after sending the tagged OK response to the + LOGOUT command. + + 2) as a panic shutdown announcement. The server closes the + connection immediately. + + 3) as an announcement of an inactivity autologout. The server + closes the connection immediately. + + 4) as one of three possible greetings at connection startup, + indicating that the server is not willing to accept a + connection from this client. The server closes the + connection immediately. + + + + +Crispin Standards Track [Page 67] + +RFC 3501 IMAPv4 March 2003 + + + The difference between a BYE that occurs as part of a normal + LOGOUT sequence (the first case) and a BYE that occurs because of + a failure (the other three cases) is that the connection closes + immediately in the failure case. In all cases the client SHOULD + continue to read response data from the server until the + connection is closed; this will ensure that any pending untagged + or completion responses are read and processed. + + Example: S: * BYE Autologout; idle for too long + +7.2. Server Responses - Server and Mailbox Status + + These responses are always untagged. This is how server and mailbox + status data are transmitted from the server to the client. Many of + these responses typically result from a command with the same name. + +7.2.1. CAPABILITY Response + + Contents: capability listing + + The CAPABILITY response occurs as a result of a CAPABILITY + command. The capability listing contains a space-separated + listing of capability names that the server supports. The + capability listing MUST include the atom "IMAP4rev1". + + In addition, client and server implementations MUST implement the + STARTTLS, LOGINDISABLED, and AUTH=PLAIN (described in [IMAP-TLS]) + capabilities. See the Security Considerations section for + important information. + + A capability name which begins with "AUTH=" indicates that the + server supports that particular authentication mechanism. + + The LOGINDISABLED capability indicates that the LOGIN command is + disabled, and that the server will respond with a tagged NO + response to any attempt to use the LOGIN command even if the user + name and password are valid. An IMAP client MUST NOT issue the + LOGIN command if the server advertises the LOGINDISABLED + capability. + + Other capability names indicate that the server supports an + extension, revision, or amendment to the IMAP4rev1 protocol. + Server responses MUST conform to this document until the client + issues a command that uses the associated capability. + + Capability names MUST either begin with "X" or be standard or + standards-track IMAP4rev1 extensions, revisions, or amendments + registered with IANA. A server MUST NOT offer unregistered or + + + +Crispin Standards Track [Page 68] + +RFC 3501 IMAPv4 March 2003 + + + non-standard capability names, unless such names are prefixed with + an "X". + + Client implementations SHOULD NOT require any capability name + other than "IMAP4rev1", and MUST ignore any unknown capability + names. + + A server MAY send capabilities automatically, by using the + CAPABILITY response code in the initial PREAUTH or OK responses, + and by sending an updated CAPABILITY response code in the tagged + OK response as part of a successful authentication. It is + unnecessary for a client to send a separate CAPABILITY command if + it recognizes these automatic capabilities. + + Example: S: * CAPABILITY IMAP4rev1 STARTTLS AUTH=GSSAPI XPIG-LATIN + + +7.2.2. LIST Response + + Contents: name attributes + hierarchy delimiter + name + + The LIST response occurs as a result of a LIST command. It + returns a single name that matches the LIST specification. There + can be multiple LIST responses for a single LIST command. + + Four name attributes are defined: + + \Noinferiors + It is not possible for any child levels of hierarchy to exist + under this name; no child levels exist now and none can be + created in the future. + + \Noselect + It is not possible to use this name as a selectable mailbox. + + \Marked + The mailbox has been marked "interesting" by the server; the + mailbox probably contains messages that have been added since + the last time the mailbox was selected. + + \Unmarked + The mailbox does not contain any additional messages since the + last time the mailbox was selected. + + + + + + +Crispin Standards Track [Page 69] + +RFC 3501 IMAPv4 March 2003 + + + If it is not feasible for the server to determine whether or not + the mailbox is "interesting", or if the name is a \Noselect name, + the server SHOULD NOT send either \Marked or \Unmarked. + + The hierarchy delimiter is a character used to delimit levels of + hierarchy in a mailbox name. A client can use it to create child + mailboxes, and to search higher or lower levels of naming + hierarchy. All children of a top-level hierarchy node MUST use + the same separator character. A NIL hierarchy delimiter means + that no hierarchy exists; the name is a "flat" name. + + The name represents an unambiguous left-to-right hierarchy, and + MUST be valid for use as a reference in LIST and LSUB commands. + Unless \Noselect is indicated, the name MUST also be valid as an + argument for commands, such as SELECT, that accept mailbox names. + + Example: S: * LIST (\Noselect) "/" ~/Mail/foo + + +7.2.3. LSUB Response + + Contents: name attributes + hierarchy delimiter + name + + The LSUB response occurs as a result of an LSUB command. It + returns a single name that matches the LSUB specification. There + can be multiple LSUB responses for a single LSUB command. The + data is identical in format to the LIST response. + + Example: S: * LSUB () "." #news.comp.mail.misc + + +7.2.4 STATUS Response + + Contents: name + status parenthesized list + + The STATUS response occurs as a result of an STATUS command. It + returns the mailbox name that matches the STATUS specification and + the requested mailbox status information. + + Example: S: * STATUS blurdybloop (MESSAGES 231 UIDNEXT 44292) + + + + + + + + +Crispin Standards Track [Page 70] + +RFC 3501 IMAPv4 March 2003 + + +7.2.5. SEARCH Response + + Contents: zero or more numbers + + The SEARCH response occurs as a result of a SEARCH or UID SEARCH + command. The number(s) refer to those messages that match the + search criteria. For SEARCH, these are message sequence numbers; + for UID SEARCH, these are unique identifiers. Each number is + delimited by a space. + + Example: S: * SEARCH 2 3 6 + + +7.2.6. FLAGS Response + + Contents: flag parenthesized list + + The FLAGS response occurs as a result of a SELECT or EXAMINE + command. The flag parenthesized list identifies the flags (at a + minimum, the system-defined flags) that are applicable for this + mailbox. Flags other than the system flags can also exist, + depending on server implementation. + + The update from the FLAGS response MUST be recorded by the client. + + Example: S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) + + +7.3. Server Responses - Mailbox Size + + These responses are always untagged. This is how changes in the size + of the mailbox are transmitted from the server to the client. + Immediately following the "*" token is a number that represents a + message count. + +7.3.1. EXISTS Response + + Contents: none + + The EXISTS response reports the number of messages in the mailbox. + This response occurs as a result of a SELECT or EXAMINE command, + and if the size of the mailbox changes (e.g., new messages). + + The update from the EXISTS response MUST be recorded by the + client. + + Example: S: * 23 EXISTS + + + + +Crispin Standards Track [Page 71] + +RFC 3501 IMAPv4 March 2003 + + +7.3.2. RECENT Response + + Contents: none + + The RECENT response reports the number of messages with the + \Recent flag set. This response occurs as a result of a SELECT or + EXAMINE command, and if the size of the mailbox changes (e.g., new + messages). + + Note: It is not guaranteed that the message sequence + numbers of recent messages will be a contiguous range of + the highest n messages in the mailbox (where n is the + value reported by the RECENT response). Examples of + situations in which this is not the case are: multiple + clients having the same mailbox open (the first session + to be notified will see it as recent, others will + probably see it as non-recent), and when the mailbox is + re-ordered by a non-IMAP agent. + + The only reliable way to identify recent messages is to + look at message flags to see which have the \Recent flag + set, or to do a SEARCH RECENT. + + The update from the RECENT response MUST be recorded by the + client. + + Example: S: * 5 RECENT + + +7.4. Server Responses - Message Status + + These responses are always untagged. This is how message data are + transmitted from the server to the client, often as a result of a + command with the same name. Immediately following the "*" token is a + number that represents a message sequence number. + +7.4.1. EXPUNGE Response + + Contents: none + + The EXPUNGE response reports that the specified message sequence + number has been permanently removed from the mailbox. The message + sequence number for each successive message in the mailbox is + immediately decremented by 1, and this decrement is reflected in + message sequence numbers in subsequent responses (including other + untagged EXPUNGE responses). + + + + + +Crispin Standards Track [Page 72] + +RFC 3501 IMAPv4 March 2003 + + + The EXPUNGE response also decrements the number of messages in the + mailbox; it is not necessary to send an EXISTS response with the + new value. + + As a result of the immediate decrement rule, message sequence + numbers that appear in a set of successive EXPUNGE responses + depend upon whether the messages are removed starting from lower + numbers to higher numbers, or from higher numbers to lower + numbers. For example, if the last 5 messages in a 9-message + mailbox are expunged, a "lower to higher" server will send five + untagged EXPUNGE responses for message sequence number 5, whereas + a "higher to lower server" will send successive untagged EXPUNGE + responses for message sequence numbers 9, 8, 7, 6, and 5. + + An EXPUNGE response MUST NOT be sent when no command is in + progress, nor while responding to a FETCH, STORE, or SEARCH + command. This rule is necessary to prevent a loss of + synchronization of message sequence numbers between client and + server. A command is not "in progress" until the complete command + has been received; in particular, a command is not "in progress" + during the negotiation of command continuation. + + Note: UID FETCH, UID STORE, and UID SEARCH are different + commands from FETCH, STORE, and SEARCH. An EXPUNGE + response MAY be sent during a UID command. + + The update from the EXPUNGE response MUST be recorded by the + client. + + Example: S: * 44 EXPUNGE + + +7.4.2. FETCH Response + + Contents: message data + + The FETCH response returns data about a message to the client. + The data are pairs of data item names and their values in + parentheses. This response occurs as the result of a FETCH or + STORE command, as well as by unilateral server decision (e.g., + flag updates). + + The current data items are: + + BODY + A form of BODYSTRUCTURE without extension data. + + + + + +Crispin Standards Track [Page 73] + +RFC 3501 IMAPv4 March 2003 + + + BODY[<section>]<<origin octet>> + A string expressing the body contents of the specified section. + The string SHOULD be interpreted by the client according to the + content transfer encoding, body type, and subtype. + + If the origin octet is specified, this string is a substring of + the entire body contents, starting at that origin octet. This + means that BODY[]<0> MAY be truncated, but BODY[] is NEVER + truncated. + + Note: The origin octet facility MUST NOT be used by a server + in a FETCH response unless the client specifically requested + it by means of a FETCH of a BODY[<section>]<<partial>> data + item. + + 8-bit textual data is permitted if a [CHARSET] identifier is + part of the body parameter parenthesized list for this section. + Note that headers (part specifiers HEADER or MIME, or the + header portion of a MESSAGE/RFC822 part), MUST be 7-bit; 8-bit + characters are not permitted in headers. Note also that the + [RFC-2822] delimiting blank line between the header and the + body is not affected by header line subsetting; the blank line + is always included as part of header data, except in the case + of a message which has no body and no blank line. + + Non-textual data such as binary data MUST be transfer encoded + into a textual form, such as BASE64, prior to being sent to the + client. To derive the original binary data, the client MUST + decode the transfer encoded string. + + BODYSTRUCTURE + A parenthesized list that describes the [MIME-IMB] body + structure of a message. This is computed by the server by + parsing the [MIME-IMB] header fields, defaulting various fields + as necessary. + + For example, a simple text message of 48 lines and 2279 octets + can have a body structure of: ("TEXT" "PLAIN" ("CHARSET" + "US-ASCII") NIL NIL "7BIT" 2279 48) + + Multiple parts are indicated by parenthesis nesting. Instead + of a body type as the first element of the parenthesized list, + there is a sequence of one or more nested body structures. The + second element of the parenthesized list is the multipart + subtype (mixed, digest, parallel, alternative, etc.). + + + + + + +Crispin Standards Track [Page 74] + +RFC 3501 IMAPv4 March 2003 + + + For example, a two part message consisting of a text and a + BASE64-encoded text attachment can have a body structure of: + (("TEXT" "PLAIN" ("CHARSET" "US-ASCII") NIL NIL "7BIT" 1152 + 23)("TEXT" "PLAIN" ("CHARSET" "US-ASCII" "NAME" "cc.diff") + "<960723163407.20117h@cac.washington.edu>" "Compiler diff" + "BASE64" 4554 73) "MIXED") + + Extension data follows the multipart subtype. Extension data + is never returned with the BODY fetch, but can be returned with + a BODYSTRUCTURE fetch. Extension data, if present, MUST be in + the defined order. The extension data of a multipart body part + are in the following order: + + body parameter parenthesized list + A parenthesized list of attribute/value pairs [e.g., ("foo" + "bar" "baz" "rag") where "bar" is the value of "foo", and + "rag" is the value of "baz"] as defined in [MIME-IMB]. + + body disposition + A parenthesized list, consisting of a disposition type + string, followed by a parenthesized list of disposition + attribute/value pairs as defined in [DISPOSITION]. + + body language + A string or parenthesized list giving the body language + value as defined in [LANGUAGE-TAGS]. + + body location + A string list giving the body content URI as defined in + [LOCATION]. + + Any following extension data are not yet defined in this + version of the protocol. Such extension data can consist of + zero or more NILs, strings, numbers, or potentially nested + parenthesized lists of such data. Client implementations that + do a BODYSTRUCTURE fetch MUST be prepared to accept such + extension data. Server implementations MUST NOT send such + extension data until it has been defined by a revision of this + protocol. + + The basic fields of a non-multipart body part are in the + following order: + + body type + A string giving the content media type name as defined in + [MIME-IMB]. + + + + + +Crispin Standards Track [Page 75] + +RFC 3501 IMAPv4 March 2003 + + + body subtype + A string giving the content subtype name as defined in + [MIME-IMB]. + + body parameter parenthesized list + A parenthesized list of attribute/value pairs [e.g., ("foo" + "bar" "baz" "rag") where "bar" is the value of "foo" and + "rag" is the value of "baz"] as defined in [MIME-IMB]. + + body id + A string giving the content id as defined in [MIME-IMB]. + + body description + A string giving the content description as defined in + [MIME-IMB]. + + body encoding + A string giving the content transfer encoding as defined in + [MIME-IMB]. + + body size + A number giving the size of the body in octets. Note that + this size is the size in its transfer encoding and not the + resulting size after any decoding. + + A body type of type MESSAGE and subtype RFC822 contains, + immediately after the basic fields, the envelope structure, + body structure, and size in text lines of the encapsulated + message. + + A body type of type TEXT contains, immediately after the basic + fields, the size of the body in text lines. Note that this + size is the size in its content transfer encoding and not the + resulting size after any decoding. + + Extension data follows the basic fields and the type-specific + fields listed above. Extension data is never returned with the + BODY fetch, but can be returned with a BODYSTRUCTURE fetch. + Extension data, if present, MUST be in the defined order. + + The extension data of a non-multipart body part are in the + following order: + + body MD5 + A string giving the body MD5 value as defined in [MD5]. + + + + + + +Crispin Standards Track [Page 76] + +RFC 3501 IMAPv4 March 2003 + + + body disposition + A parenthesized list with the same content and function as + the body disposition for a multipart body part. + + body language + A string or parenthesized list giving the body language + value as defined in [LANGUAGE-TAGS]. + + body location + A string list giving the body content URI as defined in + [LOCATION]. + + Any following extension data are not yet defined in this + version of the protocol, and would be as described above under + multipart extension data. + + ENVELOPE + A parenthesized list that describes the envelope structure of a + message. This is computed by the server by parsing the + [RFC-2822] header into the component parts, defaulting various + fields as necessary. + + The fields of the envelope structure are in the following + order: date, subject, from, sender, reply-to, to, cc, bcc, + in-reply-to, and message-id. The date, subject, in-reply-to, + and message-id fields are strings. The from, sender, reply-to, + to, cc, and bcc fields are parenthesized lists of address + structures. + + An address structure is a parenthesized list that describes an + electronic mail address. The fields of an address structure + are in the following order: personal name, [SMTP] + at-domain-list (source route), mailbox name, and host name. + + [RFC-2822] group syntax is indicated by a special form of + address structure in which the host name field is NIL. If the + mailbox name field is also NIL, this is an end of group marker + (semi-colon in RFC 822 syntax). If the mailbox name field is + non-NIL, this is a start of group marker, and the mailbox name + field holds the group name phrase. + + If the Date, Subject, In-Reply-To, and Message-ID header lines + are absent in the [RFC-2822] header, the corresponding member + of the envelope is NIL; if these header lines are present but + empty the corresponding member of the envelope is the empty + string. + + + + + +Crispin Standards Track [Page 77] + +RFC 3501 IMAPv4 March 2003 + + + Note: some servers may return a NIL envelope member in the + "present but empty" case. Clients SHOULD treat NIL and + empty string as identical. + + Note: [RFC-2822] requires that all messages have a valid + Date header. Therefore, the date member in the envelope can + not be NIL or the empty string. + + Note: [RFC-2822] requires that the In-Reply-To and + Message-ID headers, if present, have non-empty content. + Therefore, the in-reply-to and message-id members in the + envelope can not be the empty string. + + If the From, To, cc, and bcc header lines are absent in the + [RFC-2822] header, or are present but empty, the corresponding + member of the envelope is NIL. + + If the Sender or Reply-To lines are absent in the [RFC-2822] + header, or are present but empty, the server sets the + corresponding member of the envelope to be the same value as + the from member (the client is not expected to know to do + this). + + Note: [RFC-2822] requires that all messages have a valid + From header. Therefore, the from, sender, and reply-to + members in the envelope can not be NIL. + + FLAGS + A parenthesized list of flags that are set for this message. + + INTERNALDATE + A string representing the internal date of the message. + + RFC822 + Equivalent to BODY[]. + + RFC822.HEADER + Equivalent to BODY[HEADER]. Note that this did not result in + \Seen being set, because RFC822.HEADER response data occurs as + a result of a FETCH of RFC822.HEADER. BODY[HEADER] response + data occurs as a result of a FETCH of BODY[HEADER] (which sets + \Seen) or BODY.PEEK[HEADER] (which does not set \Seen). + + RFC822.SIZE + A number expressing the [RFC-2822] size of the message. + + + + + + +Crispin Standards Track [Page 78] + +RFC 3501 IMAPv4 March 2003 + + + RFC822.TEXT + Equivalent to BODY[TEXT]. + + UID + A number expressing the unique identifier of the message. + + + Example: S: * 23 FETCH (FLAGS (\Seen) RFC822.SIZE 44827) + + +7.5. Server Responses - Command Continuation Request + + The command continuation request response is indicated by a "+" token + instead of a tag. This form of response indicates that the server is + ready to accept the continuation of a command from the client. The + remainder of this response is a line of text. + + This response is used in the AUTHENTICATE command to transmit server + data to the client, and request additional client data. This + response is also used if an argument to any command is a literal. + + The client is not permitted to send the octets of the literal unless + the server indicates that it is expected. This permits the server to + process commands and reject errors on a line-by-line basis. The + remainder of the command, including the CRLF that terminates a + command, follows the octets of the literal. If there are any + additional command arguments, the literal octets are followed by a + space and those arguments. + + Example: C: A001 LOGIN {11} + S: + Ready for additional command text + C: FRED FOOBAR {7} + S: + Ready for additional command text + C: fat man + S: A001 OK LOGIN completed + C: A044 BLURDYBLOOP {102856} + S: A044 BAD No such command as "BLURDYBLOOP" + + + + + + + + + + + + + + +Crispin Standards Track [Page 79] + +RFC 3501 IMAPv4 March 2003 + + +8. Sample IMAP4rev1 connection + + The following is a transcript of an IMAP4rev1 connection. A long + line in this sample is broken for editorial clarity. + +S: * OK IMAP4rev1 Service Ready +C: a001 login mrc secret +S: a001 OK LOGIN completed +C: a002 select inbox +S: * 18 EXISTS +S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) +S: * 2 RECENT +S: * OK [UNSEEN 17] Message 17 is the first unseen message +S: * OK [UIDVALIDITY 3857529045] UIDs valid +S: a002 OK [READ-WRITE] SELECT completed +C: a003 fetch 12 full +S: * 12 FETCH (FLAGS (\Seen) INTERNALDATE "17-Jul-1996 02:44:25 -0700" + RFC822.SIZE 4286 ENVELOPE ("Wed, 17 Jul 1996 02:23:25 -0700 (PDT)" + "IMAP4rev1 WG mtg summary and minutes" + (("Terry Gray" NIL "gray" "cac.washington.edu")) + (("Terry Gray" NIL "gray" "cac.washington.edu")) + (("Terry Gray" NIL "gray" "cac.washington.edu")) + ((NIL NIL "imap" "cac.washington.edu")) + ((NIL NIL "minutes" "CNRI.Reston.VA.US") + ("John Klensin" NIL "KLENSIN" "MIT.EDU")) NIL NIL + "<B27397-0100000@cac.washington.edu>") + BODY ("TEXT" "PLAIN" ("CHARSET" "US-ASCII") NIL NIL "7BIT" 3028 + 92)) +S: a003 OK FETCH completed +C: a004 fetch 12 body[header] +S: * 12 FETCH (BODY[HEADER] {342} +S: Date: Wed, 17 Jul 1996 02:23:25 -0700 (PDT) +S: From: Terry Gray <gray@cac.washington.edu> +S: Subject: IMAP4rev1 WG mtg summary and minutes +S: To: imap@cac.washington.edu +S: cc: minutes@CNRI.Reston.VA.US, John Klensin <KLENSIN@MIT.EDU> +S: Message-Id: <B27397-0100000@cac.washington.edu> +S: MIME-Version: 1.0 +S: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII +S: +S: ) +S: a004 OK FETCH completed +C: a005 store 12 +flags \deleted +S: * 12 FETCH (FLAGS (\Seen \Deleted)) +S: a005 OK +FLAGS completed +C: a006 logout +S: * BYE IMAP4rev1 server terminating connection +S: a006 OK LOGOUT completed + + + +Crispin Standards Track [Page 80] + +RFC 3501 IMAPv4 March 2003 + + +9. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [ABNF]. + + In the case of alternative or optional rules in which a later rule + overlaps an earlier rule, the rule which is listed earlier MUST take + priority. For example, "\Seen" when parsed as a flag is the \Seen + flag name and not a flag-extension, even though "\Seen" can be parsed + as a flag-extension. Some, but not all, instances of this rule are + noted below. + + Note: [ABNF] rules MUST be followed strictly; in + particular: + + (1) Except as noted otherwise, all alphabetic characters + are case-insensitive. The use of upper or lower case + characters to define token strings is for editorial clarity + only. Implementations MUST accept these strings in a + case-insensitive fashion. + + (2) In all cases, SP refers to exactly one space. It is + NOT permitted to substitute TAB, insert additional spaces, + or otherwise treat SP as being equivalent to LWSP. + + (3) The ASCII NUL character, %x00, MUST NOT be used at any + time. + +address = "(" addr-name SP addr-adl SP addr-mailbox SP + addr-host ")" + +addr-adl = nstring + ; Holds route from [RFC-2822] route-addr if + ; non-NIL + +addr-host = nstring + ; NIL indicates [RFC-2822] group syntax. + ; Otherwise, holds [RFC-2822] domain name + +addr-mailbox = nstring + ; NIL indicates end of [RFC-2822] group; if + ; non-NIL and addr-host is NIL, holds + ; [RFC-2822] group name. + ; Otherwise, holds [RFC-2822] local-part + ; after removing [RFC-2822] quoting + + + + + + +Crispin Standards Track [Page 81] + +RFC 3501 IMAPv4 March 2003 + + +addr-name = nstring + ; If non-NIL, holds phrase from [RFC-2822] + ; mailbox after removing [RFC-2822] quoting + +append = "APPEND" SP mailbox [SP flag-list] [SP date-time] SP + literal + +astring = 1*ASTRING-CHAR / string + +ASTRING-CHAR = ATOM-CHAR / resp-specials + +atom = 1*ATOM-CHAR + +ATOM-CHAR = <any CHAR except atom-specials> + +atom-specials = "(" / ")" / "{" / SP / CTL / list-wildcards / + quoted-specials / resp-specials + +authenticate = "AUTHENTICATE" SP auth-type *(CRLF base64) + +auth-type = atom + ; Defined by [SASL] + +base64 = *(4base64-char) [base64-terminal] + +base64-char = ALPHA / DIGIT / "+" / "/" + ; Case-sensitive + +base64-terminal = (2base64-char "==") / (3base64-char "=") + +body = "(" (body-type-1part / body-type-mpart) ")" + +body-extension = nstring / number / + "(" body-extension *(SP body-extension) ")" + ; Future expansion. Client implementations + ; MUST accept body-extension fields. Server + ; implementations MUST NOT generate + ; body-extension fields except as defined by + ; future standard or standards-track + ; revisions of this specification. + +body-ext-1part = body-fld-md5 [SP body-fld-dsp [SP body-fld-lang + [SP body-fld-loc *(SP body-extension)]]] + ; MUST NOT be returned on non-extensible + ; "BODY" fetch + + + + + + +Crispin Standards Track [Page 82] + +RFC 3501 IMAPv4 March 2003 + + +body-ext-mpart = body-fld-param [SP body-fld-dsp [SP body-fld-lang + [SP body-fld-loc *(SP body-extension)]]] + ; MUST NOT be returned on non-extensible + ; "BODY" fetch + +body-fields = body-fld-param SP body-fld-id SP body-fld-desc SP + body-fld-enc SP body-fld-octets + +body-fld-desc = nstring + +body-fld-dsp = "(" string SP body-fld-param ")" / nil + +body-fld-enc = (DQUOTE ("7BIT" / "8BIT" / "BINARY" / "BASE64"/ + "QUOTED-PRINTABLE") DQUOTE) / string + +body-fld-id = nstring + +body-fld-lang = nstring / "(" string *(SP string) ")" + +body-fld-loc = nstring + +body-fld-lines = number + +body-fld-md5 = nstring + +body-fld-octets = number + +body-fld-param = "(" string SP string *(SP string SP string) ")" / nil + +body-type-1part = (body-type-basic / body-type-msg / body-type-text) + [SP body-ext-1part] + +body-type-basic = media-basic SP body-fields + ; MESSAGE subtype MUST NOT be "RFC822" + +body-type-mpart = 1*body SP media-subtype + [SP body-ext-mpart] + +body-type-msg = media-message SP body-fields SP envelope + SP body SP body-fld-lines + +body-type-text = media-text SP body-fields SP body-fld-lines + +capability = ("AUTH=" auth-type) / atom + ; New capabilities MUST begin with "X" or be + ; registered with IANA as standard or + ; standards-track + + + + +Crispin Standards Track [Page 83] + +RFC 3501 IMAPv4 March 2003 + + +capability-data = "CAPABILITY" *(SP capability) SP "IMAP4rev1" + *(SP capability) + ; Servers MUST implement the STARTTLS, AUTH=PLAIN, + ; and LOGINDISABLED capabilities + ; Servers which offer RFC 1730 compatibility MUST + ; list "IMAP4" as the first capability. + +CHAR8 = %x01-ff + ; any OCTET except NUL, %x00 + +command = tag SP (command-any / command-auth / command-nonauth / + command-select) CRLF + ; Modal based on state + +command-any = "CAPABILITY" / "LOGOUT" / "NOOP" / x-command + ; Valid in all states + +command-auth = append / create / delete / examine / list / lsub / + rename / select / status / subscribe / unsubscribe + ; Valid only in Authenticated or Selected state + +command-nonauth = login / authenticate / "STARTTLS" + ; Valid only when in Not Authenticated state + +command-select = "CHECK" / "CLOSE" / "EXPUNGE" / copy / fetch / store / + uid / search + ; Valid only when in Selected state + +continue-req = "+" SP (resp-text / base64) CRLF + +copy = "COPY" SP sequence-set SP mailbox + +create = "CREATE" SP mailbox + ; Use of INBOX gives a NO error + +date = date-text / DQUOTE date-text DQUOTE + +date-day = 1*2DIGIT + ; Day of month + +date-day-fixed = (SP DIGIT) / 2DIGIT + ; Fixed-format version of date-day + +date-month = "Jan" / "Feb" / "Mar" / "Apr" / "May" / "Jun" / + "Jul" / "Aug" / "Sep" / "Oct" / "Nov" / "Dec" + +date-text = date-day "-" date-month "-" date-year + + + + +Crispin Standards Track [Page 84] + +RFC 3501 IMAPv4 March 2003 + + +date-year = 4DIGIT + +date-time = DQUOTE date-day-fixed "-" date-month "-" date-year + SP time SP zone DQUOTE + +delete = "DELETE" SP mailbox + ; Use of INBOX gives a NO error + +digit-nz = %x31-39 + ; 1-9 + +envelope = "(" env-date SP env-subject SP env-from SP + env-sender SP env-reply-to SP env-to SP env-cc SP + env-bcc SP env-in-reply-to SP env-message-id ")" + +env-bcc = "(" 1*address ")" / nil + +env-cc = "(" 1*address ")" / nil + +env-date = nstring + +env-from = "(" 1*address ")" / nil + +env-in-reply-to = nstring + +env-message-id = nstring + +env-reply-to = "(" 1*address ")" / nil + +env-sender = "(" 1*address ")" / nil + +env-subject = nstring + +env-to = "(" 1*address ")" / nil + +examine = "EXAMINE" SP mailbox + +fetch = "FETCH" SP sequence-set SP ("ALL" / "FULL" / "FAST" / + fetch-att / "(" fetch-att *(SP fetch-att) ")") + +fetch-att = "ENVELOPE" / "FLAGS" / "INTERNALDATE" / + "RFC822" [".HEADER" / ".SIZE" / ".TEXT"] / + "BODY" ["STRUCTURE"] / "UID" / + "BODY" section ["<" number "." nz-number ">"] / + "BODY.PEEK" section ["<" number "." nz-number ">"] + + + + + + +Crispin Standards Track [Page 85] + +RFC 3501 IMAPv4 March 2003 + + +flag = "\Answered" / "\Flagged" / "\Deleted" / + "\Seen" / "\Draft" / flag-keyword / flag-extension + ; Does not include "\Recent" + +flag-extension = "\" atom + ; Future expansion. Client implementations + ; MUST accept flag-extension flags. Server + ; implementations MUST NOT generate + ; flag-extension flags except as defined by + ; future standard or standards-track + ; revisions of this specification. + +flag-fetch = flag / "\Recent" + +flag-keyword = atom + +flag-list = "(" [flag *(SP flag)] ")" + +flag-perm = flag / "\*" + +greeting = "*" SP (resp-cond-auth / resp-cond-bye) CRLF + +header-fld-name = astring + +header-list = "(" header-fld-name *(SP header-fld-name) ")" + +list = "LIST" SP mailbox SP list-mailbox + +list-mailbox = 1*list-char / string + +list-char = ATOM-CHAR / list-wildcards / resp-specials + +list-wildcards = "%" / "*" + +literal = "{" number "}" CRLF *CHAR8 + ; Number represents the number of CHAR8s + +login = "LOGIN" SP userid SP password + +lsub = "LSUB" SP mailbox SP list-mailbox + + + + + + + + + + + +Crispin Standards Track [Page 86] + +RFC 3501 IMAPv4 March 2003 + + +mailbox = "INBOX" / astring + ; INBOX is case-insensitive. All case variants of + ; INBOX (e.g., "iNbOx") MUST be interpreted as INBOX + ; not as an astring. An astring which consists of + ; the case-insensitive sequence "I" "N" "B" "O" "X" + ; is considered to be INBOX and not an astring. + ; Refer to section 5.1 for further + ; semantic details of mailbox names. + +mailbox-data = "FLAGS" SP flag-list / "LIST" SP mailbox-list / + "LSUB" SP mailbox-list / "SEARCH" *(SP nz-number) / + "STATUS" SP mailbox SP "(" [status-att-list] ")" / + number SP "EXISTS" / number SP "RECENT" + +mailbox-list = "(" [mbx-list-flags] ")" SP + (DQUOTE QUOTED-CHAR DQUOTE / nil) SP mailbox + +mbx-list-flags = *(mbx-list-oflag SP) mbx-list-sflag + *(SP mbx-list-oflag) / + mbx-list-oflag *(SP mbx-list-oflag) + +mbx-list-oflag = "\Noinferiors" / flag-extension + ; Other flags; multiple possible per LIST response + +mbx-list-sflag = "\Noselect" / "\Marked" / "\Unmarked" + ; Selectability flags; only one per LIST response + +media-basic = ((DQUOTE ("APPLICATION" / "AUDIO" / "IMAGE" / + "MESSAGE" / "VIDEO") DQUOTE) / string) SP + media-subtype + ; Defined in [MIME-IMT] + +media-message = DQUOTE "MESSAGE" DQUOTE SP DQUOTE "RFC822" DQUOTE + ; Defined in [MIME-IMT] + +media-subtype = string + ; Defined in [MIME-IMT] + +media-text = DQUOTE "TEXT" DQUOTE SP media-subtype + ; Defined in [MIME-IMT] + +message-data = nz-number SP ("EXPUNGE" / ("FETCH" SP msg-att)) + +msg-att = "(" (msg-att-dynamic / msg-att-static) + *(SP (msg-att-dynamic / msg-att-static)) ")" + +msg-att-dynamic = "FLAGS" SP "(" [flag-fetch *(SP flag-fetch)] ")" + ; MAY change for a message + + + +Crispin Standards Track [Page 87] + +RFC 3501 IMAPv4 March 2003 + + +msg-att-static = "ENVELOPE" SP envelope / "INTERNALDATE" SP date-time / + "RFC822" [".HEADER" / ".TEXT"] SP nstring / + "RFC822.SIZE" SP number / + "BODY" ["STRUCTURE"] SP body / + "BODY" section ["<" number ">"] SP nstring / + "UID" SP uniqueid + ; MUST NOT change for a message + +nil = "NIL" + +nstring = string / nil + +number = 1*DIGIT + ; Unsigned 32-bit integer + ; (0 <= n < 4,294,967,296) + +nz-number = digit-nz *DIGIT + ; Non-zero unsigned 32-bit integer + ; (0 < n < 4,294,967,296) + +password = astring + +quoted = DQUOTE *QUOTED-CHAR DQUOTE + +QUOTED-CHAR = <any TEXT-CHAR except quoted-specials> / + "\" quoted-specials + +quoted-specials = DQUOTE / "\" + +rename = "RENAME" SP mailbox SP mailbox + ; Use of INBOX as a destination gives a NO error + +response = *(continue-req / response-data) response-done + +response-data = "*" SP (resp-cond-state / resp-cond-bye / + mailbox-data / message-data / capability-data) CRLF + +response-done = response-tagged / response-fatal + +response-fatal = "*" SP resp-cond-bye CRLF + ; Server closes connection immediately + +response-tagged = tag SP resp-cond-state CRLF + +resp-cond-auth = ("OK" / "PREAUTH") SP resp-text + ; Authentication condition + + + + + +Crispin Standards Track [Page 88] + +RFC 3501 IMAPv4 March 2003 + + +resp-cond-bye = "BYE" SP resp-text + +resp-cond-state = ("OK" / "NO" / "BAD") SP resp-text + ; Status condition + +resp-specials = "]" + +resp-text = ["[" resp-text-code "]" SP] text + +resp-text-code = "ALERT" / + "BADCHARSET" [SP "(" astring *(SP astring) ")" ] / + capability-data / "PARSE" / + "PERMANENTFLAGS" SP "(" + [flag-perm *(SP flag-perm)] ")" / + "READ-ONLY" / "READ-WRITE" / "TRYCREATE" / + "UIDNEXT" SP nz-number / "UIDVALIDITY" SP nz-number / + "UNSEEN" SP nz-number / + atom [SP 1*<any TEXT-CHAR except "]">] + +search = "SEARCH" [SP "CHARSET" SP astring] 1*(SP search-key) + ; CHARSET argument to MUST be registered with IANA + +search-key = "ALL" / "ANSWERED" / "BCC" SP astring / + "BEFORE" SP date / "BODY" SP astring / + "CC" SP astring / "DELETED" / "FLAGGED" / + "FROM" SP astring / "KEYWORD" SP flag-keyword / + "NEW" / "OLD" / "ON" SP date / "RECENT" / "SEEN" / + "SINCE" SP date / "SUBJECT" SP astring / + "TEXT" SP astring / "TO" SP astring / + "UNANSWERED" / "UNDELETED" / "UNFLAGGED" / + "UNKEYWORD" SP flag-keyword / "UNSEEN" / + ; Above this line were in [IMAP2] + "DRAFT" / "HEADER" SP header-fld-name SP astring / + "LARGER" SP number / "NOT" SP search-key / + "OR" SP search-key SP search-key / + "SENTBEFORE" SP date / "SENTON" SP date / + "SENTSINCE" SP date / "SMALLER" SP number / + "UID" SP sequence-set / "UNDRAFT" / sequence-set / + "(" search-key *(SP search-key) ")" + +section = "[" [section-spec] "]" + +section-msgtext = "HEADER" / "HEADER.FIELDS" [".NOT"] SP header-list / + "TEXT" + ; top-level or MESSAGE/RFC822 part + +section-part = nz-number *("." nz-number) + ; body part nesting + + + +Crispin Standards Track [Page 89] + +RFC 3501 IMAPv4 March 2003 + + +section-spec = section-msgtext / (section-part ["." section-text]) + +section-text = section-msgtext / "MIME" + ; text other than actual body part (headers, etc.) + +select = "SELECT" SP mailbox + +seq-number = nz-number / "*" + ; message sequence number (COPY, FETCH, STORE + ; commands) or unique identifier (UID COPY, + ; UID FETCH, UID STORE commands). + ; * represents the largest number in use. In + ; the case of message sequence numbers, it is + ; the number of messages in a non-empty mailbox. + ; In the case of unique identifiers, it is the + ; unique identifier of the last message in the + ; mailbox or, if the mailbox is empty, the + ; mailbox's current UIDNEXT value. + ; The server should respond with a tagged BAD + ; response to a command that uses a message + ; sequence number greater than the number of + ; messages in the selected mailbox. This + ; includes "*" if the selected mailbox is empty. + +seq-range = seq-number ":" seq-number + ; two seq-number values and all values between + ; these two regardless of order. + ; Example: 2:4 and 4:2 are equivalent and indicate + ; values 2, 3, and 4. + ; Example: a unique identifer sequence range of + ; 3291:* includes the UID of the last message in + ; the mailbox, even if that value is less than 3291. + +sequence-set = (seq-number / seq-range) *("," sequence-set) + ; set of seq-number values, regardless of order. + ; Servers MAY coalesce overlaps and/or execute the + ; sequence in any order. + ; Example: a message sequence number set of + ; 2,4:7,9,12:* for a mailbox with 15 messages is + ; equivalent to 2,4,5,6,7,9,12,13,14,15 + ; Example: a message sequence number set of *:4,5:7 + ; for a mailbox with 10 messages is equivalent to + ; 10,9,8,7,6,5,4,5,6,7 and MAY be reordered and + ; overlap coalesced to be 4,5,6,7,8,9,10. + +status = "STATUS" SP mailbox SP + "(" status-att *(SP status-att) ")" + + + + +Crispin Standards Track [Page 90] + +RFC 3501 IMAPv4 March 2003 + + +status-att = "MESSAGES" / "RECENT" / "UIDNEXT" / "UIDVALIDITY" / + "UNSEEN" + +status-att-list = status-att SP number *(SP status-att SP number) + +store = "STORE" SP sequence-set SP store-att-flags + +store-att-flags = (["+" / "-"] "FLAGS" [".SILENT"]) SP + (flag-list / (flag *(SP flag))) + +string = quoted / literal + +subscribe = "SUBSCRIBE" SP mailbox + +tag = 1*<any ASTRING-CHAR except "+"> + +text = 1*TEXT-CHAR + +TEXT-CHAR = <any CHAR except CR and LF> + +time = 2DIGIT ":" 2DIGIT ":" 2DIGIT + ; Hours minutes seconds + +uid = "UID" SP (copy / fetch / search / store) + ; Unique identifiers used instead of message + ; sequence numbers + +uniqueid = nz-number + ; Strictly ascending + +unsubscribe = "UNSUBSCRIBE" SP mailbox + +userid = astring + +x-command = "X" atom <experimental command arguments> + +zone = ("+" / "-") 4DIGIT + ; Signed four-digit value of hhmm representing + ; hours and minutes east of Greenwich (that is, + ; the amount that the given time differs from + ; Universal Time). Subtracting the timezone + ; from the given time will give the UT form. + ; The Universal Time zone is "+0000". + + + + + + + + +Crispin Standards Track [Page 91] + +RFC 3501 IMAPv4 March 2003 + + +10. Author's Note + + This document is a revision or rewrite of earlier documents, and + supercedes the protocol specification in those documents: RFC 2060, + RFC 1730, unpublished IMAP2bis.TXT document, RFC 1176, and RFC 1064. + +11. Security Considerations + + IMAP4rev1 protocol transactions, including electronic mail data, are + sent in the clear over the network unless protection from snooping is + negotiated. This can be accomplished either by the use of STARTTLS, + negotiated privacy protection in the AUTHENTICATE command, or some + other protection mechanism. + +11.1. STARTTLS Security Considerations + + The specification of the STARTTLS command and LOGINDISABLED + capability in this document replaces that in [IMAP-TLS]. [IMAP-TLS] + remains normative for the PLAIN [SASL] authenticator. + + IMAP client and server implementations MUST implement the + TLS_RSA_WITH_RC4_128_MD5 [TLS] cipher suite, and SHOULD implement the + TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA [TLS] cipher suite. This is + important as it assures that any two compliant implementations can be + configured to interoperate. All other cipher suites are OPTIONAL. + Note that this is a change from section 2.1 of [IMAP-TLS]. + + During the [TLS] negotiation, the client MUST check its understanding + of the server hostname against the server's identity as presented in + the server Certificate message, in order to prevent man-in-the-middle + attacks. If the match fails, the client SHOULD either ask for + explicit user confirmation, or terminate the connection and indicate + that the server's identity is suspect. Matching is performed + according to these rules: + + The client MUST use the server hostname it used to open the + connection as the value to compare against the server name + as expressed in the server certificate. The client MUST + NOT use any form of the server hostname derived from an + insecure remote source (e.g., insecure DNS lookup). CNAME + canonicalization is not done. + + If a subjectAltName extension of type dNSName is present in + the certificate, it SHOULD be used as the source of the + server's identity. + + Matching is case-insensitive. + + + + +Crispin Standards Track [Page 92] + +RFC 3501 IMAPv4 March 2003 + + + A "*" wildcard character MAY be used as the left-most name + component in the certificate. For example, *.example.com + would match a.example.com, foo.example.com, etc. but would + not match example.com. + + If the certificate contains multiple names (e.g., more than + one dNSName field), then a match with any one of the fields + is considered acceptable. + + Both the client and server MUST check the result of the STARTTLS + command and subsequent [TLS] negotiation to see whether acceptable + authentication or privacy was achieved. + +11.2. Other Security Considerations + + A server error message for an AUTHENTICATE command which fails due to + invalid credentials SHOULD NOT detail why the credentials are + invalid. + + Use of the LOGIN command sends passwords in the clear. This can be + avoided by using the AUTHENTICATE command with a [SASL] mechanism + that does not use plaintext passwords, by first negotiating + encryption via STARTTLS or some other protection mechanism. + + A server implementation MUST implement a configuration that, at the + time of authentication, requires: + (1) The STARTTLS command has been negotiated. + OR + (2) Some other mechanism that protects the session from password + snooping has been provided. + OR + (3) The following measures are in place: + (a) The LOGINDISABLED capability is advertised, and [SASL] + mechanisms (such as PLAIN) using plaintext passwords are NOT + advertised in the CAPABILITY list. + AND + (b) The LOGIN command returns an error even if the password is + correct. + AND + (c) The AUTHENTICATE command returns an error with all [SASL] + mechanisms that use plaintext passwords, even if the password + is correct. + + A server error message for a failing LOGIN command SHOULD NOT specify + that the user name, as opposed to the password, is invalid. + + A server SHOULD have mechanisms in place to limit or delay failed + AUTHENTICATE/LOGIN attempts. + + + +Crispin Standards Track [Page 93] + +RFC 3501 IMAPv4 March 2003 + + + Additional security considerations are discussed in the section + discussing the AUTHENTICATE and LOGIN commands. + +12. IANA Considerations + + IMAP4 capabilities are registered by publishing a standards track or + IESG approved experimental RFC. The registry is currently located + at: + + http://www.iana.org/assignments/imap4-capabilities + + As this specification revises the STARTTLS and LOGINDISABLED + extensions previously defined in [IMAP-TLS], the registry will be + updated accordingly. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Crispin Standards Track [Page 94] + +RFC 3501 IMAPv4 March 2003 + + +Appendices + +A. Normative References + + The following documents contain definitions or specifications that + are necessary to understand this document properly: + [ABNF] Crocker, D. and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", RFC 2234, + November 1997. + + [ANONYMOUS] Newman, C., "Anonymous SASL Mechanism", RFC + 2245, November 1997. + + [CHARSET] Freed, N. and J. Postel, "IANA Character Set + Registration Procedures", RFC 2978, October + 2000. + + [DIGEST-MD5] Leach, P. and C. Newman, "Using Digest + Authentication as a SASL Mechanism", RFC 2831, + May 2000. + + [DISPOSITION] Troost, R., Dorner, S. and K. Moore, + "Communicating Presentation Information in + Internet Messages: The Content-Disposition + Header", RFC 2183, August 1997. + + [IMAP-TLS] Newman, C., "Using TLS with IMAP, POP3 and + ACAP", RFC 2595, June 1999. + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to + Indicate Requirement Levels", BCP 14, RFC 2119, + March 1997. + + [LANGUAGE-TAGS] Alvestrand, H., "Tags for the Identification of + Languages", BCP 47, RFC 3066, January 2001. + + [LOCATION] Palme, J., Hopmann, A. and N. Shelness, "MIME + Encapsulation of Aggregate Documents, such as + HTML (MHTML)", RFC 2557, March 1999. + + [MD5] Myers, J. and M. Rose, "The Content-MD5 Header + Field", RFC 1864, October 1995. + + + + + + + + + +Crispin Standards Track [Page 95] + +RFC 3501 IMAPv4 March 2003 + + + [MIME-HDRS] Moore, K., "MIME (Multipurpose Internet Mail + Extensions) Part Three: Message Header + Extensions for Non-ASCII Text", RFC 2047, + November 1996. + + [MIME-IMB] Freed, N. and N. Borenstein, "MIME + (Multipurpose Internet Mail Extensions) Part + One: Format of Internet Message Bodies", RFC + 2045, November 1996. + + [MIME-IMT] Freed, N. and N. Borenstein, "MIME + (Multipurpose Internet Mail Extensions) Part + Two: Media Types", RFC 2046, November 1996. + + [RFC-2822] Resnick, P., "Internet Message Format", RFC + 2822, April 2001. + + [SASL] Myers, J., "Simple Authentication and Security + Layer (SASL)", RFC 2222, October 1997. + + [TLS] Dierks, T. and C. Allen, "The TLS Protocol + Version 1.0", RFC 2246, January 1999. + + [UTF-7] Goldsmith, D. and M. Davis, "UTF-7: A Mail-Safe + Transformation Format of Unicode", RFC 2152, + May 1997. + + The following documents describe quality-of-implementation issues + that should be carefully considered when implementing this protocol: + + [IMAP-IMPLEMENTATION] Leiba, B., "IMAP Implementation + Recommendations", RFC 2683, September 1999. + + [IMAP-MULTIACCESS] Gahrns, M., "IMAP4 Multi-Accessed Mailbox + Practice", RFC 2180, July 1997. + +A.1 Informative References + + The following documents describe related protocols: + + [IMAP-DISC] Austein, R., "Synchronization Operations for + Disconnected IMAP4 Clients", Work in Progress. + + [IMAP-MODEL] Crispin, M., "Distributed Electronic Mail + Models in IMAP4", RFC 1733, December 1994. + + + + + + +Crispin Standards Track [Page 96] + +RFC 3501 IMAPv4 March 2003 + + + [ACAP] Newman, C. and J. Myers, "ACAP -- Application + Configuration Access Protocol", RFC 2244, + November 1997. + + [SMTP] Klensin, J., "Simple Mail Transfer Protocol", + STD 10, RFC 2821, April 2001. + + The following documents are historical or describe historical aspects + of this protocol: + + [IMAP-COMPAT] Crispin, M., "IMAP4 Compatibility with + IMAP2bis", RFC 2061, December 1996. + + [IMAP-HISTORICAL] Crispin, M., "IMAP4 Compatibility with IMAP2 + and IMAP2bis", RFC 1732, December 1994. + + [IMAP-OBSOLETE] Crispin, M., "Internet Message Access Protocol + - Obsolete Syntax", RFC 2062, December 1996. + + [IMAP2] Crispin, M., "Interactive Mail Access Protocol + - Version 2", RFC 1176, August 1990. + + [RFC-822] Crocker, D., "Standard for the Format of ARPA + Internet Text Messages", STD 11, RFC 822, + August 1982. + + [RFC-821] Postel, J., "Simple Mail Transfer Protocol", + STD 10, RFC 821, August 1982. + +B. Changes from RFC 2060 + + 1) Clarify description of unique identifiers and their semantics. + + 2) Fix the SELECT description to clarify that UIDVALIDITY is required + in the SELECT and EXAMINE responses. + + 3) Added an example of a failing search. + + 4) Correct store-att-flags: "#flag" should be "1#flag". + + 5) Made search and section rules clearer. + + 6) Correct the STORE example. + + 7) Correct "BASE645" misspelling. + + 8) Remove extraneous close parenthesis in example of two-part message + with text and BASE64 attachment. + + + +Crispin Standards Track [Page 97] + +RFC 3501 IMAPv4 March 2003 + + + 9) Remove obsolete "MAILBOX" response from mailbox-data. + + 10) A spurious "<" in the rule for mailbox-data was removed. + + 11) Add CRLF to continue-req. + + 12) Specifically exclude "]" from the atom in resp-text-code. + + 13) Clarify that clients and servers should adhere strictly to the + protocol syntax. + + 14) Emphasize in 5.2 that EXISTS can not be used to shrink a mailbox. + + 15) Add NEWNAME to resp-text-code. + + 16) Clarify that the empty string, not NIL, is used as arguments to + LIST. + + 17) Clarify that NIL can be returned as a hierarchy delimiter for the + empty string mailbox name argument if the mailbox namespace is flat. + + 18) Clarify that addr-mailbox and addr-name have RFC-2822 quoting + removed. + + 19) Update UTF-7 reference. + + 20) Fix example in 6.3.11. + + 21) Clarify that non-existent UIDs are ignored. + + 22) Update DISPOSITION reference. + + 23) Expand state diagram. + + 24) Clarify that partial fetch responses are only returned in + response to a partial fetch command. + + 25) Add UIDNEXT response code. Correct UIDVALIDITY definition + reference. + + 26) Further clarification of "can" vs. "MAY". + + 27) Reference RFC-2119. + + 28) Clarify that superfluous shifts are not permitted in modified + UTF-7. + + 29) Clarify that there are no implicit shifts in modified UTF-7. + + + +Crispin Standards Track [Page 98] + +RFC 3501 IMAPv4 March 2003 + + + 30) Clarify that "INBOX" in a mailbox name is always INBOX, even if + it is given as a string. + + 31) Add missing open parenthesis in media-basic grammar rule. + + 32) Correct attribute syntax in mailbox-data. + + 33) Add UIDNEXT to EXAMINE responses. + + 34) Clarify UNSEEN, PERMANENTFLAGS, UIDVALIDITY, and UIDNEXT + responses in SELECT and EXAMINE. They are required now, but weren't + in older versions. + + 35) Update references with RFC numbers. + + 36) Flush text-mime2. + + 37) Clarify that modified UTF-7 names must be case-sensitive and that + violating the convention should be avoided. + + 38) Correct UID FETCH example. + + 39) Clarify UID FETCH, UID STORE, and UID SEARCH vs. untagged EXPUNGE + responses. + + 40) Clarify the use of the word "convention". + + 41) Clarify that a command is not "in progress" until it has been + fully received (specifically, that a command is not "in progress" + during command continuation negotiation). + + 42) Clarify envelope defaulting. + + 43) Clarify that SP means one and only one space character. + + 44) Forbid silly states in LIST response. + + 45) Clarify that the ENVELOPE, INTERNALDATE, RFC822*, BODY*, and UID + for a message is static. + + 46) Add BADCHARSET response code. + + 47) Update formal syntax to [ABNF] conventions. + + 48) Clarify trailing hierarchy delimiter in CREATE semantics. + + 49) Clarify that the "blank line" is the [RFC-2822] delimiting blank + line. + + + +Crispin Standards Track [Page 99] + +RFC 3501 IMAPv4 March 2003 + + + 50) Clarify that RENAME should also create hierarchy as needed for + the command to complete. + + 51) Fix body-ext-mpart to not require language if disposition + present. + + 52) Clarify the RFC822.HEADER response. + + 53) Correct missing space after charset astring in search. + + 54) Correct missing quote for BADCHARSET in resp-text-code. + + 55) Clarify that ALL, FAST, and FULL preclude any other data items + appearing. + + 56) Clarify semantics of reference argument in LIST. + + 57) Clarify that a null string for SEARCH HEADER X-FOO means any + message with a header line with a field-name of X-FOO regardless of + the text of the header. + + 58) Specifically reserve 8-bit mailbox names for future use as UTF-8. + + 59) It is not an error for the client to store a flag that is not in + the PERMANENTFLAGS list; however, the server will either ignore the + change or make the change in the session only. + + 60) Correct/clarify the text regarding superfluous shifts. + + 61) Correct typographic errors in the "Changes" section. + + 62) Clarify that STATUS must not be used to check for new messages in + the selected mailbox + + 63) Clarify LSUB behavior with "%" wildcard. + + 64) Change AUTHORIZATION to AUTHENTICATE in section 7.5. + + 65) Clarify description of multipart body type. + + 66) Clarify that STORE FLAGS does not affect \Recent. + + 67) Change "west" to "east" in description of timezone. + + 68) Clarify that commands which break command pipelining must wait + for a completion result response. + + 69) Clarify that EXAMINE does not affect \Recent. + + + +Crispin Standards Track [Page 100] + +RFC 3501 IMAPv4 March 2003 + + + 70) Make description of MIME structure consistent. + + 71) Clarify that date searches disregard the time and timezone of the + INTERNALDATE or Date: header. In other words, "ON 13-APR-2000" means + messages with an INTERNALDATE text which starts with "13-APR-2000", + even if timezone differential from the local timezone is sufficient + to move that INTERNALDATE into the previous or next day. + + 72) Clarify that the header fetches don't add a blank line if one + isn't in the [RFC-2822] message. + + 73) Clarify (in discussion of UIDs) that messages are immutable. + + 74) Add an example of CHARSET searching. + + 75) Clarify in SEARCH that keywords are a type of flag. + + 76) Clarify the mandatory nature of the SELECT data responses. + + 77) Add optional CAPABILITY response code in the initial OK or + PREAUTH. + + 78) Add note that server can send an untagged CAPABILITY command as + part of the responses to AUTHENTICATE and LOGIN. + + 79) Remove statement about it being unnecessary to issue a CAPABILITY + command more than once in a connection. That statement is no longer + true. + + 80) Clarify that untagged EXPUNGE decrements the number of messages + in the mailbox. + + 81) Fix definition of "body" (concatenation has tighter binding than + alternation). + + 82) Add a new "Special Notes to Implementors" section with reference + to [IMAP-IMPLEMENTATION]. + + 83) Clarify that an untagged CAPABILITY response to an AUTHENTICATE + command should only be done if a security layer was not negotiated. + + 84) Change the definition of atom to exclude "]". Update astring to + include "]" for compatiblity with the past. Remove resp-text-atom. + + 85) Remove NEWNAME. It can't work because mailbox names can be + literals and can include "]". Functionality can be addressed via + referrals. + + + + +Crispin Standards Track [Page 101] + +RFC 3501 IMAPv4 March 2003 + + + 86) Move modified UTF-7 rationale in order to have more logical + paragraph flow. + + 87) Clarify UID uniqueness guarantees with the use of MUST. + + 88) Note that clients should read response data until the connection + is closed instead of immediately closing on a BYE. + + 89) Change RFC-822 references to RFC-2822. + + 90) Clarify that RFC-2822 should be followed instead of RFC-822. + + 91) Change recommendation of optional automatic capabilities in LOGIN + and AUTHENTICATE to use the CAPABILITY response code in the tagged + OK. This is more interoperable than an unsolicited untagged + CAPABILITY response. + + 92) STARTTLS and AUTH=PLAIN are mandatory to implement; add + recommendations for other [SASL] mechanisms. + + 93) Clarify that a "connection" (as opposed to "server" or "command") + is in one of the four states. + + 94) Clarify that a failed or rejected command does not change state. + + 95) Split references between normative and informative. + + 96) Discuss authentication failure issues in security section. + + 97) Clarify that a data item is not necessarily of only one data + type. + + 98) Clarify that sequence ranges are independent of order. + + 99) Change an example to clarify that superfluous shifts in + Modified-UTF7 can not be fixed just by omitting the shift. The + entire string must be recalculated. + + 100) Change Envelope Structure definition since [RFC-2822] uses + "envelope" to refer to the [SMTP] envelope and not the envelope data + that appears in the [RFC-2822] header. + + 101) Expand on RFC822.HEADER response data vs. BODY[HEADER]. + + 102) Clarify Logout state semantics, change ASCII art. + + 103) Security changes to comply with IESG requirements. + + + + +Crispin Standards Track [Page 102] + +RFC 3501 IMAPv4 March 2003 + + + 104) Add definition for body URI. + + 105) Break sequence range definition into three rules, with rewritten + descriptions for each. + + 106) Move STARTTLS and LOGINDISABLED here from [IMAP-TLS]. + + 107) Add IANA Considerations section. + + 108) Clarify valid client assumptions for new message UIDs vs. + UIDNEXT. + + 109) Clarify that changes to permanentflags affect concurrent + sessions as well as subsequent sessions. + + 110) Clarify that authenticated state can be entered by the CLOSE + command. + + 111) Emphasize that SELECT and EXAMINE are the exceptions to the rule + that a failing command does not change state. + + 112) Clarify that newly-appended messages have the Recent flag set. + + 113) Clarify that newly-copied messages SHOULD have the Recent flag + set. + + 114) Clarify that UID commands always return the UID in FETCH + responses. + +C. Key Word Index + + +FLAGS <flag list> (store command data item) ............... 59 + +FLAGS.SILENT <flag list> (store command data item) ........ 59 + -FLAGS <flag list> (store command data item) ............... 59 + -FLAGS.SILENT <flag list> (store command data item) ........ 59 + ALERT (response code) ...................................... 64 + ALL (fetch item) ........................................... 55 + ALL (search key) ........................................... 50 + ANSWERED (search key) ...................................... 50 + APPEND (command) ........................................... 45 + AUTHENTICATE (command) ..................................... 27 + BAD (response) ............................................. 66 + BADCHARSET (response code) ................................. 64 + BCC <string> (search key) .................................. 51 + BEFORE <date> (search key) ................................. 51 + BODY (fetch item) .......................................... 55 + BODY (fetch result) ........................................ 73 + BODY <string> (search key) ................................. 51 + + + +Crispin Standards Track [Page 103] + +RFC 3501 IMAPv4 March 2003 + + + BODY.PEEK[<section>]<<partial>> (fetch item) ............... 57 + BODYSTRUCTURE (fetch item) ................................. 57 + BODYSTRUCTURE (fetch result) ............................... 74 + BODY[<section>]<<origin octet>> (fetch result) ............. 74 + BODY[<section>]<<partial>> (fetch item) .................... 55 + BYE (response) ............................................. 67 + Body Structure (message attribute) ......................... 12 + CAPABILITY (command) ....................................... 24 + CAPABILITY (response code) ................................. 64 + CAPABILITY (response) ...................................... 68 + CC <string> (search key) ................................... 51 + CHECK (command) ............................................ 47 + CLOSE (command) ............................................ 48 + COPY (command) ............................................. 59 + CREATE (command) ........................................... 34 + DELETE (command) ........................................... 35 + DELETED (search key) ....................................... 51 + DRAFT (search key) ......................................... 51 + ENVELOPE (fetch item) ...................................... 57 + ENVELOPE (fetch result) .................................... 77 + EXAMINE (command) .......................................... 33 + EXISTS (response) .......................................... 71 + EXPUNGE (command) .......................................... 48 + EXPUNGE (response) ......................................... 72 + Envelope Structure (message attribute) ..................... 12 + FAST (fetch item) .......................................... 55 + FETCH (command) ............................................ 54 + FETCH (response) ........................................... 73 + FLAGGED (search key) ....................................... 51 + FLAGS (fetch item) ......................................... 57 + FLAGS (fetch result) ....................................... 78 + FLAGS (response) ........................................... 71 + FLAGS <flag list> (store command data item) ................ 59 + FLAGS.SILENT <flag list> (store command data item) ......... 59 + FROM <string> (search key) ................................. 51 + FULL (fetch item) .......................................... 55 + Flags (message attribute) .................................. 11 + HEADER (part specifier) .................................... 55 + HEADER <field-name> <string> (search key) .................. 51 + HEADER.FIELDS <header-list> (part specifier) ............... 55 + HEADER.FIELDS.NOT <header-list> (part specifier) ........... 55 + INTERNALDATE (fetch item) .................................. 57 + INTERNALDATE (fetch result) ................................ 78 + Internal Date (message attribute) .......................... 12 + KEYWORD <flag> (search key) ................................ 51 + Keyword (type of flag) ..................................... 11 + LARGER <n> (search key) .................................... 51 + LIST (command) ............................................. 40 + + + +Crispin Standards Track [Page 104] + +RFC 3501 IMAPv4 March 2003 + + + LIST (response) ............................................ 69 + LOGIN (command) ............................................ 30 + LOGOUT (command) ........................................... 25 + LSUB (command) ............................................. 43 + LSUB (response) ............................................ 70 + MAY (specification requirement term) ....................... 4 + MESSAGES (status item) ..................................... 45 + MIME (part specifier) ...................................... 56 + MUST (specification requirement term) ...................... 4 + MUST NOT (specification requirement term) .................. 4 + Message Sequence Number (message attribute) ................ 10 + NEW (search key) ........................................... 51 + NO (response) .............................................. 66 + NOOP (command) ............................................. 25 + NOT <search-key> (search key) .............................. 52 + OK (response) .............................................. 65 + OLD (search key) ........................................... 52 + ON <date> (search key) ..................................... 52 + OPTIONAL (specification requirement term) .................. 4 + OR <search-key1> <search-key2> (search key) ................ 52 + PARSE (response code) ...................................... 64 + PERMANENTFLAGS (response code) ............................. 64 + PREAUTH (response) ......................................... 67 + Permanent Flag (class of flag) ............................. 12 + READ-ONLY (response code) .................................. 65 + READ-WRITE (response code) ................................. 65 + RECENT (response) .......................................... 72 + RECENT (search key) ........................................ 52 + RECENT (status item) ....................................... 45 + RENAME (command) ........................................... 37 + REQUIRED (specification requirement term) .................. 4 + RFC822 (fetch item) ........................................ 57 + RFC822 (fetch result) ...................................... 78 + RFC822.HEADER (fetch item) ................................. 57 + RFC822.HEADER (fetch result) ............................... 78 + RFC822.SIZE (fetch item) ................................... 57 + RFC822.SIZE (fetch result) ................................. 78 + RFC822.TEXT (fetch item) ................................... 58 + RFC822.TEXT (fetch result) ................................. 79 + SEARCH (command) ........................................... 49 + SEARCH (response) .......................................... 71 + SEEN (search key) .......................................... 52 + SELECT (command) ........................................... 31 + SENTBEFORE <date> (search key) ............................. 52 + SENTON <date> (search key) ................................. 52 + SENTSINCE <date> (search key) .............................. 52 + SHOULD (specification requirement term) .................... 4 + SHOULD NOT (specification requirement term) ................ 4 + + + +Crispin Standards Track [Page 105] + +RFC 3501 IMAPv4 March 2003 + + + SINCE <date> (search key) .................................. 52 + SMALLER <n> (search key) ................................... 52 + STARTTLS (command) ......................................... 27 + STATUS (command) ........................................... 44 + STATUS (response) .......................................... 70 + STORE (command) ............................................ 58 + SUBJECT <string> (search key) .............................. 53 + SUBSCRIBE (command) ........................................ 38 + Session Flag (class of flag) ............................... 12 + System Flag (type of flag) ................................. 11 + TEXT (part specifier) ...................................... 56 + TEXT <string> (search key) ................................. 53 + TO <string> (search key) ................................... 53 + TRYCREATE (response code) .................................. 65 + UID (command) .............................................. 60 + UID (fetch item) ........................................... 58 + UID (fetch result) ......................................... 79 + UID <sequence set> (search key) ............................ 53 + UIDNEXT (response code) .................................... 65 + UIDNEXT (status item) ...................................... 45 + UIDVALIDITY (response code) ................................ 65 + UIDVALIDITY (status item) .................................. 45 + UNANSWERED (search key) .................................... 53 + UNDELETED (search key) ..................................... 53 + UNDRAFT (search key) ....................................... 53 + UNFLAGGED (search key) ..................................... 53 + UNKEYWORD <flag> (search key) .............................. 53 + UNSEEN (response code) ..................................... 65 + UNSEEN (search key) ........................................ 53 + UNSEEN (status item) ....................................... 45 + UNSUBSCRIBE (command) ...................................... 39 + Unique Identifier (UID) (message attribute) ................ 8 + X<atom> (command) .......................................... 62 + [RFC-2822] Size (message attribute) ........................ 12 + \Answered (system flag) .................................... 11 + \Deleted (system flag) ..................................... 11 + \Draft (system flag) ....................................... 11 + \Flagged (system flag) ..................................... 11 + \Marked (mailbox name attribute) ........................... 69 + \Noinferiors (mailbox name attribute) ...................... 69 + \Noselect (mailbox name attribute) ......................... 69 + \Recent (system flag) ...................................... 11 + \Seen (system flag) ........................................ 11 + \Unmarked (mailbox name attribute) ......................... 69 + + + + + + + +Crispin Standards Track [Page 106] + +RFC 3501 IMAPv4 March 2003 + + +Author's Address + + Mark R. Crispin + Networks and Distributed Computing + University of Washington + 4545 15th Avenue NE + Seattle, WA 98105-4527 + + Phone: (206) 543-5762 + + EMail: MRC@CAC.Washington.EDU + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Crispin Standards Track [Page 107] + +RFC 3501 IMAPv4 March 2003 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2003). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. v This + document and the information contained herein is provided on an "AS + IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK + FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT + LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL + NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY + OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + + +Crispin Standards Track [Page 108] + + diff --git a/imap/docs/rfc/rfc3502.txt b/imap/docs/rfc/rfc3502.txt new file mode 100644 index 00000000..f6b61a44 --- /dev/null +++ b/imap/docs/rfc/rfc3502.txt @@ -0,0 +1,395 @@ + + + + + + +Network Working Group M. Crispin +Request for Comments: 3502 University of Washington +Category: Standards Track March 2003 + + + Internet Message Access Protocol (IMAP) - MULTIAPPEND Extension + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2003). All Rights Reserved. + +Abstract + + This document describes the multiappending extension to the Internet + Message Access Protocol (IMAP) (RFC 3501). This extension provides + substantial performance improvements for IMAP clients which upload + multiple messages at a time to a mailbox on the server. + + A server which supports this extension indicates this with a + capability name of "MULTIAPPEND". + +Terminology + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "MAY", and "OPTIONAL" in this document are to + be interpreted as described in [KEYWORDS]. + +Introduction + + The MULTIAPPEND extension permits uploading of multiple messages with + a single command. When used in conjunction with the [LITERAL+] + extension, the entire upload is accomplished in a single + command/response round trip. + + A MULTIAPPEND APPEND operation is atomic; either all messages are + successfully appended, or no messages are appended. + + In the base IMAP specification, each message must be appended in a + separate command, and there is no mechanism to "unappend" messages if + an error occurs while appending. Also, some mail stores may require + + + +Crispin Standards Track [Page 1] + +RFC 3502 IMAP MULTIAPPEND March 2003 + + + an expensive "open/lock + sync/unlock/close" operation as part of + appending; this can be quite expensive if it must be done on a + per-message basis. + + If the server supports both LITERAL+ and pipelining but not + MULTIAPPEND, it may be possible to get some of the performance + advantages of MULTIAPPEND by doing a pipelined "batch" append. + However, it will not work as well as MULTIAPPEND for the following + reasons: + + 1) Multiple APPEND commands, even as part of a pipelined batch, + are non-atomic by definition. There is no way to revert the + mailbox to the state before the batch append in the event of an + error. + + 2) It may not be feasible for the server to coalesce pipelined + APPEND operations so as to avoid the "open/lock + + sync/unlock/close" overhead described above. In any case, such + coalescing would be timing dependent and thus potentially + unreliable. In particular, with traditional UNIX mailbox files, + it is assumed that a lock is held only for a single atomic + operation, and many applications disregard any lock that is + older than 5 minutes. + + 3) If an error occurs, depending upon the nature of the error, + it is possible for additional messages to be appended after the + error. For example, the user wants to append 5 messages, but a + disk quota error occurs with the third message because of its + size. However, the fourth and fifth messages have already been + sent in the pipeline, so the mailbox ends up with the first, + second, fourth, and fifth messages of the batch appended. + +6.3.11. APPEND Command + + Arguments: mailbox name + one or more messages to upload, specified as: + OPTIONAL flag parenthesized list + OPTIONAL date/time string + message literal + + Data: no specific responses for this command + + Result: OK - append completed + NO - append error: can't append to that mailbox, error + in flags or date/time or message text, + append cancelled + BAD - command unknown or arguments invalid + + + + +Crispin Standards Track [Page 2] + +RFC 3502 IMAP MULTIAPPEND March 2003 + + + The APPEND command appends the literal arguments as new messages + to the end of the specified destination mailbox. This argument + SHOULD be in the format of an [RFC-2822] message. 8-bit + characters are permitted in the message. A server implementation + that is unable to preserve 8-bit data properly MUST be able to + reversibly convert 8-bit APPEND data to 7-bit using a [MIME-IMB] + content transfer encoding. + + Note: There MAY be exceptions, e.g., draft messages, in + which required [RFC-2822] header lines are omitted in the + message literal argument to APPEND. The full implications + of doing so MUST be understood and carefully weighed. + + If a flag parenthesized list is specified, the flags SHOULD be set + in the resulting message; otherwise, the flag list of the + resulting message is set empty by default. + + If a date-time is specified, the internal date SHOULD be set in + the resulting message; otherwise, the internal date of the + resulting message is set to the current date and time by default. + + A zero-length message literal argument is an error, and MUST + return a NO. This can be used to cancel the append. + + If the append is unsuccessful for any reason (including being + cancelled), the mailbox MUST be restored to its state before the + APPEND attempt; no partial appending is permitted. The server MAY + return an error before processing all the message arguments. + + If the destination mailbox does not exist, a server MUST return an + error, and MUST NOT automatically create the mailbox. Unless it + is certain that the destination mailbox can not be created, the + server MUST send the response code "[TRYCREATE]" as the prefix of + the text of the tagged NO response. This gives a hint to the + client that it can attempt a CREATE command and retry the APPEND + if the CREATE is successful. + + If the mailbox is currently selected, the normal new message + actions SHOULD occur. Specifically, the server SHOULD notify the + client immediately via an untagged EXISTS response. If the server + does not do so, the client MAY issue a NOOP command (or failing + that, a CHECK command) after one or more APPEND commands. + + + + + + + + + +Crispin Standards Track [Page 3] + +RFC 3502 IMAP MULTIAPPEND March 2003 + + + Example: C: A003 APPEND saved-messages (\Seen) {329} + S: + Ready for literal data + C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) + C: From: Fred Foobar <foobar@Blurdybloop.example.COM> + C: Subject: afternoon meeting + C: To: mooch@owatagu.example.net + C: Message-Id: <B27397-0100000@Blurdybloop.example.COM> + C: MIME-Version: 1.0 + C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII + C: + C: Hello Joe, do you think we can meet at 3:30 tomorrow? + C: (\Seen) " 7-Feb-1994 22:43:04 -0800" {295} + S: + Ready for literal data + C: Date: Mon, 7 Feb 1994 22:43:04 -0800 (PST) + C: From: Joe Mooch <mooch@OWaTaGu.example.net> + C: Subject: Re: afternoon meeting + C: To: foobar@blurdybloop.example.com + C: Message-Id: <a0434793874930@OWaTaGu.example.net> + C: MIME-Version: 1.0 + C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII + C: + C: 3:30 is fine with me. + C: + S: A003 OK APPEND completed + C: A004 APPEND bogusname (\Flagged) {1023} + S: A004 NO [TRYCREATE] No such mailbox as bogusname + C: A005 APPEND test (\Flagged) {99} + S: + Ready for literal data + C: Date: Mon, 7 Feb 2000 22:43:04 -0800 (PST) + C: From: Fred Foobar <fred@example.com> + C: Subject: hmm... + C: {35403} + S: A005 NO APPEND failed: Disk quota exceeded + + Note: The APPEND command is not used for message delivery, + because it does not provide a mechanism to transfer [SMTP] + envelope information. + +Modification to IMAP4rev1 Base Protocol Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [ABNF]. + + append = "APPEND" SP mailbox 1*append-message + + append-message = [SP flag-list] [SP date-time] SP literal + + + + + +Crispin Standards Track [Page 4] + +RFC 3502 IMAP MULTIAPPEND March 2003 + + +MULTIAPPEND Interaction with UIDPLUS Extension + + Servers which support both MULTIAPPEND and [UIDPLUS] will have the + "resp-code-apnd" rule modified as follows: + + resp-code-apnd = "APPENDUID" SP nz-number SP set + + That is, the APPENDUID response code returns as many UIDs as there + were messages appended in the multiple append. The UIDs returned + should be in the order the articles where appended. The message set + may not contain extraneous UIDs or the symbol "*". + +Security Considerations + + The MULTIAPPEND extension does not raise any security considerations + that are not present in the base [IMAP] protocol, and these issues + are discussed in [IMAP]. Nevertheless, it is important to remember + that IMAP4rev1 protocol transactions, including electronic mail data, + are sent in the clear over the network unless protection from + snooping is negotiated, either by the use of STARTTLS, privacy + protection is negotiated in the AUTHENTICATE command, or some other + protection mechanism is in effect. + +Normative References + + [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997. + + [IMAP] Crispin, M., "Internet Message Access Protocol - Version + 4rev1", RFC 3501, March 2003. + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [MIME-IMB] Freed, N. and N. Borenstein, "MIME (Multipurpose Internet + Mail Extensions) Part One: Format of Internet Message + Bodies", RFC 2045, November 1996. + + [RFC-2822] Resnick, P., "Internet Message Format", RFC 2822, April + 2001. + + + + + + + + + + + +Crispin Standards Track [Page 5] + +RFC 3502 IMAP MULTIAPPEND March 2003 + + +Informative References + + [LITERAL+] Myers, J., "IMAP4 non-synchronizing literals", RFC 2088, + January 1997. + + [UIDPLUS] Myers, J., "IMAP4 UIDPLUS extension", RFC 2359, June 1988. + + [SMTP] Klensin, J., Editor, "Simple Mail Transfer Protocol", RFC + 2821, April 2001. + +Author's Address + + Mark R. Crispin + Networks and Distributed Computing + University of Washington + 4545 15th Avenue NE + Seattle, WA 98105-4527 + + Phone: (206) 543-5762 + EMail: MRC@CAC.Washington.EDU + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Crispin Standards Track [Page 6] + +RFC 3502 IMAP MULTIAPPEND March 2003 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2003). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Crispin Standards Track [Page 7] + diff --git a/imap/docs/rfc/rfc3503.txt b/imap/docs/rfc/rfc3503.txt new file mode 100644 index 00000000..5b82fb08 --- /dev/null +++ b/imap/docs/rfc/rfc3503.txt @@ -0,0 +1,507 @@ + + + + + + +Network Working Group A. Melnikov +Request for Comments: 3503 ACI Worldwide/MessagingDirect +Category: Standards Track March 2003 + + + Message Disposition Notification (MDN) profile for + Internet Message Access Protocol (IMAP) + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2003). All Rights Reserved. + +Abstract + + The Message Disposition Notification (MDN) facility defined in RFC + 2298 provides a means by which a message can request that message + processing by the recipient be acknowledged as well as a format to be + used for such acknowledgements. However, it doesn't describe how + multiple Mail User Agents (MUAs) should handle the generation of MDNs + in an Internet Message Access Protocol (IMAP4) environment. + + This document describes how to handle MDNs in such an environment and + provides guidelines for implementers of IMAP4 that want to add MDN + support to their products. + + + + + + + + + + + + + + + + + + + +Melnikov Standards Track [Page 1] + +RFC 3503 MDN profile for IMAP March 2003 + + +Table of Contents + + 1. Conventions Used in this Document............................. 2 + 2. Introduction and Overview..................................... 2 + 3. Client behavior............................................... 3 + 3.1. Client behavior when receiving a message................. 5 + 3.2. Client behavior when copying a message................... 5 + 3.3. Client behavior when sending a message................... 5 + 3.4. Client behavior when saving a temporary message.......... 5 + 4. Server behavior............................................... 5 + 4.1. Server that supports arbitrary keywords.................. 5 + 4.2. Server that supports only $MDNSent keyword............... 5 + 4.3. Interaction with IMAP ACL extension...................... 6 + 5. Examples...................................................... 6 + 6. Security Considerations....................................... 7 + 7. Formal Syntax................................................. 7 + 8. Acknowledgments............................................... 7 + 9. Normative References.......................................... 8 + 10. Author's Address.............................................. 8 + 11. Full Copyright Statement...................................... 9 + +1. Conventions Used in this Document + + "C:" and "S:" in examples show lines sent by the client and server + respectively. + + The keywords "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" in + this document when typed in uppercase are to be interpreted as + defined in "Key words for use in RFCs to Indicate Requirement Levels" + [KEYWORDS]. + +2. Introduction and Overview + + This memo defines an additional [IMAP4] mailbox keyword that allows + multiple Mail User Agents (MUAs) to know if a requested receipt + notification was sent. + + Message Disposition Notification [MDN] does not require any special + support of IMAP in the case where a user has access to the mailstore + from only one computer and is using a single MUA. In this case, the + MUA behaves as described in [MDN], i.e., the MUA performs automatic + processing and generates corresponding MDNs, it performs requested + action and, with the user's permission, sends appropriate MDNs. The + MUA will not send MDN twice because the MUA keeps track of sent + notifications in a local configuration. However, that does not work + when IMAP is used to access the same mailstore from different + locations or is using different MUAs. + + + + +Melnikov Standards Track [Page 2] + +RFC 3503 MDN profile for IMAP March 2003 + + + This document defines a new special purpose mailbox keyword $MDNSent + that must be used by MUAs. It does not define any new command or + response for IMAP, but describes a technique that MUAs should use to + achieve interoperability. + + When a client opens a mailbox for the first time, it verifies that + the server is capable of storing the $MDNSent keyword by examining + the PERMANENTFLAGS response code. In order to support MDN in IMAP, a + server MUST support either the $MDNSent keyword, or arbitrary message + keywords. + +3. Client behavior + + The use of IMAP requires few additional steps in mail processing on + the client side. The following timeline modifies the timeline found + in Section 4 of [MDN]. + + -- User composes message. + + -- User tells MUA to send message. + + -- MUA passes message to MSA (original recipient information passed + along). MUA [optionally] saves message to a folder for sent mail + with $MDNSent flag set. + + -- MSA sends message to MTA. + + -- Final MTA receives message. + + -- Final MTA delivers message to MUA (possibly generating DSN). + + -- MUA logs into IMAP server, opens mailbox, verifies if mailbox can + store $MDNSent keyword by examining PERMANENTFLAGS response. + + -- MUA performs automatic processing and generates corresponding MDNs + ("dispatched", "processed", "deleted", "denied" or "failed" + disposition type with "automatic-action" and "MDN-sent- + automatically" disposition modes) for messages that do not have + $MDNSent keyword, or \Draft flag set. (*) + + -- MUA sets the $MDNSent keyword for every message that required an + automatic MDN to be sent, whether or not the MDN was sent. + + -- MUA displays a list of messages to user. + + -- User selects a message and requests that some action be performed + on it. + + + + +Melnikov Standards Track [Page 3] + +RFC 3503 MDN profile for IMAP March 2003 + + + -- MUA performs requested action and, with user's permission, sends + appropriate MDN ("displayed", "dispatched", "processed", + "deleted", "denied" or "failed" disposition type with "manual- + action" and "MDN-sent-manually" or "MDN-sent-automatically" + disposition mode). If the generated MDN is saved to a mailbox + with the APPEND command, the client MUST specify the $MDNSent + keyword in the APPEND. + + -- MUA sets the $MDNSent keyword for all messages for which the user + confirmed the dispatching of disposition (or was explicitly + prohibited to do so). + + -- User possibly performs other actions on message, but no further + MDNs are generated. + + (*) Note: MUA MUST NOT use \Recent flag as an indicator that it + should send MDN, because according to [IMAP4], "If multiple + connections have the same mailbox selected simultaneously, it is + undefined which of these connections will see newly-arrived + messages with \Recent set and which will see it without \Recent + set". Thus, using \Recent as an indicator will cause + unpredictable client behavior with different IMAP4 servers. + However, the client MAY use \Seen flag as one of the indicators + that MDN must not be sent. The client MUST NOT use any other + standard flags, like \Draft or \Answered, to indicate that MDN + was previously sent, because they have different well known + meaning. In any case, in the presence of the $MDNSent keyword, + the client MUST ignore all other flags or keywords for the + purpose of generating an MDN and MUST NOT send the MDN. + + When the client opens a mailbox for the first time, it must verify + that the server supports the $MDNSent keyword, or arbitrary message + keywords by examining PERMANENTFLAGS response code. + + The client MUST NOT try to set the $MDNSent keyword if the server is + incapable of storing it permanently. + + The client MUST be prepared to receive NO from the server as the + result of STORE $MDNSent when the server advertises the support of + storing arbitrary keywords, because the server may limit the number + of message keywords it can store in a particular mailbox. A client + SHOULD NOT send MDN if it fails to store the $MDNSent keyword. + + Once the $MDNSent keyword is set, it MUST NOT be unset by a client. + The client MAY set the $MDNSent keyword when a user denies sending + the notification. This prohibits all other MUAs from sending MDN for + this message. + + + + +Melnikov Standards Track [Page 4] + +RFC 3503 MDN profile for IMAP March 2003 + + +3.1. Client behavior when receiving a message + + The client MUST NOT send MDN if a message has the $MDNSent keyword + set. It also MUST NOT send MDN if a message has \Draft flag, because + some clients use this flag to mark a message as incomplete. + + See the timeline in section 3 for details on client behavior when + receiving a message. + +3.2. Client behavior when copying a message + + The client SHOULD verify that $MDNSent is preserved on a COPY + operation. Furthermore, when a message is copied between servers + with the APPEND command, the client MUST set the $MDNSent keyword + correctly. + +3.3. Client behavior when sending a message + + When saving a sent message to any folder, the client MUST set the + $MDNSent keyword to prevent another client from sending MDN for the + message. + +3.4. Client behavior when saving a temporary message + + When saving an unfinished message to any folder client MUST set + $MDNSent keyword to prevent another client from sending MDN for the + message. + +4. Server behavior + + Server implementors that want to follow this specification must + insure that their server complies with either section 4.1 or section + 4.2. If the server also supports the IMAP [ACL] extension, it MUST + also comply with the section 4.3. + +4.1. Server that supports arbitrary keywords + + No changes are required from the server to make it compatible with + the extension described in this document if it supports arbitrary + keywords. + +4.2. Server that supports only $MDNSent keyword + + Servers that support only the $MDNSent keyword MUST preserve it on + the COPY operation. It is also expected that a server that supports + SEARCH <flag> will also support the SEARCH KEYWORD $MDNSent. + + + + + +Melnikov Standards Track [Page 5] + +RFC 3503 MDN profile for IMAP March 2003 + + +4.3. Interaction with IMAP ACL extension + + Any server that conforms to either 4.1 or 4.2 and also supports the + IMAP [ACL] extension, SHOULD preserve the $MDNSent keyword on COPY + even if the client does not have 'w' right. This will prevent the + generation of a duplicated MDN for the same message. Note that the + server MUST still check if the client has rights to perform the COPY + operation on a message according to [ACL]. + +5. Examples + + 1) MUA opens mailbox for the first time. + + a) The server supports storing of arbitrary keywords + + C: a100 select INBOX + S: * FLAGS (\Flagged \Draft \Deleted \Seen) + S: * OK [PERMANENTFLAGS (\Flagged \Draft \Deleted \Seen \*)] + S: * 5 EXISTS + S: * 3 RECENT + S: * OK [UIDVALIDITY 894294713] + S: a100 OK [READ-WRITE] Completed + + b) The server supports storing of the $MDNSent keyword + + C: a100 select INBOX + S: * FLAGS (\Flagged \Draft \Deleted \Seen $MDNSent) + S: * OK [PERMANENTFLAGS (\Flagged \Draft \Deleted \Seen $MDNSent)] + S: * 5 EXISTS + S: * 3 RECENT + S: * OK [UIDVALIDITY 894294713] + S: a100 OK [READ-WRITE] Completed + + 2) The MUA successfully sets the $MDNSent keyword + + C: a200 STORE 4 +FLAGS ($MDNSent) + S: * 4 FETCH (FLAGS (\Flagged \Seen $MDNSent)) + S: * FLAGS ($MDNSent \Flagged \Deleted \Draft \Seen) + S: * OK [PERMANENTFLAGS ($MDNSent \Flagged \Deleted \Draft \Seen \*)] + S: a200 OK STORE completed + + 3) The server refuses to store the $MDNSent keyword + + C: a200 STORE 4 +FLAGS ($MDNSent) + S: a200 NO STORE failed : no space left to store $MDNSent keyword + + + + + + +Melnikov Standards Track [Page 6] + +RFC 3503 MDN profile for IMAP March 2003 + + + 4) All clients and servers MUST treat the $MDNSent keyword as case + insensitive in all operations, as stated in [IMAP]. + + C: a300 FETCH 1:* FLAGS + S: * 1 FETCH (FLAGS (\Seen)) + S: * 2 FETCH (FLAGS (\Answered \Seen $MdnSENt)) + S: * 3 FETCH (FLAGS ()) + S: * 4 FETCH (FLAGS (\Flagged \Seen $MdnSENT)) + S: * 5 FETCH (FLAGS ($MDNSent)) + S: * 6 FETCH (FLAGS (\Recent)) + S: a300 OK FETCH completed + C: a400 SEARCH KEYWORDS $mdnsent + S: * SEARCH 2 4 5 + S: a400 OK SEARCH completed + +6. Security Considerations + + There are no known security issues with this extension, not found in + [MDN] and/or [IMAP4]. + + Section 4.3 changes ACL checking requirements on an IMAP server that + implements IMAP [ACL] extension. + +7. Formal Syntax + + The following syntax specification uses the augmented Backus-Naur + Form (BNF) notation as specified in [RFC-822], as modified by + [IMAP4]. Non-terminals referenced, but not defined below, are as + defined by [IMAP4]. + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of upper or lower case characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. + + flag_keyword ::= "$MDNSent" / other_keywords + + other_keywords ::= atom + +8. Acknowledgments + + This document is the product of discussions that took place on the + IMAP mailing list. Special gratitude to Cyrus Daboo and Randall + Gellens for reviewing the document. + + Thank you to my father who as he has helped to make me what I am. I + miss you terribly. + + + + +Melnikov Standards Track [Page 7] + +RFC 3503 MDN profile for IMAP March 2003 + + +9. Normative References + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [MDN] Fajman, R., "An Extensible Message Format for Message + Disposition Notifications", RFC 2298, March 1998. + + [IMAP4] Crispin, M., "Internet Message Access Protocol - Version + 4rev1", RFC 3501, March 2003. + + [ACL] Myers, J., "IMAP4 ACL extension", RFC 2086, January 1997. + +10. Author's Address + + Alexey Melnikov + ACI Worldwide/MessagingDirect + 59 Clarendon Road + Watford, Hertfordshire + United Kingdom, WD17 1FQ + + Phone: +44 1923 81 2877 + EMail: mel@messagingdirect.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Melnikov Standards Track [Page 8] + +RFC 3503 MDN profile for IMAP March 2003 + + +11. Full Copyright Statement + + Copyright (C) The Internet Society (2003). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Melnikov Standards Track [Page 9] + diff --git a/imap/docs/rfc/rfc3516.txt b/imap/docs/rfc/rfc3516.txt new file mode 100644 index 00000000..4d021975 --- /dev/null +++ b/imap/docs/rfc/rfc3516.txt @@ -0,0 +1,451 @@ + + + + + + +Network Working Group L. Nerenberg +Request for Comments: 3516 Orthanc Systems +Category: Standards Track April 2003 + + + IMAP4 Binary Content Extension + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2003). All Rights Reserved. + +Abstract + + This memo defines the Binary extension to the Internet Message Access + Protocol (IMAP4). It provides a mechanism for IMAP4 clients and + servers to exchange message body data without using a MIME content- + transfer-encoding. + +1. Conventions Used in this Document + + The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" + in this document are to be interpreted as described in [KEYWORD]. + + The abbreviation "CTE" means content-transfer-encoding. + +2. Introduction + + The MIME extensions to Internet messaging allow for the transmission + of non-textual (binary) message content [MIME-IMB]. Since the + traditional transports for messaging are not always capable of + passing binary data transparently, MIME provides encoding schemes + that allow binary content to be transmitted over transports that are + not otherwise able to do so. + + The overhead of MIME-encoding this content can be considerable in + some contexts (e.g., slow radio links, streaming multimedia). + Reducing the overhead associated with CTE schemes such as base64 + + + + + + +Nerenberg Standards Track [Page 1] + +RFC 3516 IMAP4 Binary Content Extension April 2003 + + + can give a noticeable reduction in resource consumption. The Binary + extension lets the server perform CTE decoding prior to transmitting + message data to the client. + +3. Content-Transfer-Encoding Considerations + + Every IMAP4 body section has a MIME content-transfer-encoding. + (Those without an explicit Content-Transfer-Encoding header are + implicitly labeled as "7bit" content.) In the terminology of [MIME- + IMB], the CTE specifies both a decoding algorithm and the domain of + the decoded data. In this memo, "decoding" refers to the CTE + decoding step described in [MIME-IMB]. + + Certain CTEs use an identity encoding transformation. For these CTEs + there is no decoding required, however the domain of the underlying + data may not be expressible in the IMAP4 protocol (e.g., MIME + "binary" content containing NUL octets). To accommodate these cases + the Binary extension introduces a new type of literal protocol + element that is fully eight bit transparent. + + Thus, server processing of the FETCH BINARY command involves two + logical steps: + + 1) perform any CTE-related decoding + + 2) determine the domain of the decoded data + + Step 2 is necessary to determine which protocol element should be + used to transmit the decoded data. (See FETCH Response Extensions + for further details.) + +4. Framework for the IMAP4 Binary Extension + + This memo defines the following extensions to [IMAP4rev1]. + +4.1. CAPABILITY Identification + + IMAP4 servers that support this extension MUST include "BINARY" in + the response list to the CAPABILITY command. + +4.2. FETCH Command Extensions + + This extension defines three new FETCH command data items. + + BINARY<section-binary>[<partial>] + + Requests that the specified section be transmitted after + performing CTE-related decoding. + + + +Nerenberg Standards Track [Page 2] + +RFC 3516 IMAP4 Binary Content Extension April 2003 + + + The <partial> argument, if present, requests that a subset of + the data be returned. The semantics of a partial FETCH BINARY + command are the same as for a partial FETCH BODY command, with + the exception that the <partial> arguments refer to the DECODED + section data. + + BINARY.PEEK<section-binary>[<partial>] + + An alternate form of FETCH BINARY that does not implicitly set + the \Seen flag. + + BINARY.SIZE<section-binary> + + Requests the decoded size of the section (i.e., the size to + expect in response to the corresponding FETCH BINARY request). + + Note: client authors are cautioned that this might be an + expensive operation for some server implementations. + Needlessly issuing this request could result in degraded + performance due to servers having to calculate the value every + time the request is issued. + +4.3. FETCH Response Extensions + + This extension defines two new FETCH response data items. + + BINARY<section-binary>[<<number>>] + + An <nstring> or <literal8> expressing the content of the + specified section after removing any CTE-related encoding. If + <number> is present it refers to the offset within the DECODED + section data. + + If the domain of the decoded data is "8bit" and the data does + not contain the NUL octet, the server SHOULD return the data in + a <string> instead of a <literal8>; this allows the client to + determine if the "8bit" data contains the NUL octet without + having to explicitly scan the data stream for for NULs. + + If the server does not know how to decode the section's CTE, it + MUST fail the request and issue a "NO" response that contains + the "UNKNOWN-CTE" extended response code. + + + + + + + + + +Nerenberg Standards Track [Page 3] + +RFC 3516 IMAP4 Binary Content Extension April 2003 + + + BINARY.SIZE<section-binary> + + The size of the section after removing any CTE-related + encoding. The value returned MUST match the size of the + <nstring> or <literal8> that will be returned by the + corresponding FETCH BINARY request. + + If the server does not know how to decode the section's CTE, it + MUST fail the request and issue a "NO" response that contains + the "UNKNOWN-CTE" extended response code. + +4.4. APPEND Command Extensions + + The APPEND command is extended to allow the client to append data + containing NULs by using the <literal8> syntax. The server MAY + modify the CTE of the appended data, however any such transformation + MUST NOT result in a loss of data. + + If the destination mailbox does not support the storage of binary + content, the server MUST fail the request and issue a "NO" response + that contains the "UNKNOWN-CTE" extended response code. + +5. MIME Encoded Headers + + [MIME-MHE] defines an encoding that allows for non-US-ASCII text in + message headers. This encoding is not the same as the content- + transfer-encoding applied to message bodies, and the decoding + transformations described in this memo do not apply to [MIME-MHE] + encoded header text. A server MUST NOT perform any conversion of + [MIME-MHE] encoded header text in response to any binary FETCH or + APPEND request. + +6. Implementation Considerations + + Messaging clients and servers have been notoriously lax in their + adherence to the Internet CRLF convention for terminating lines of + textual data in Internet protocols. When sending data using the + Binary extension, servers MUST ensure that textual line-oriented + sections are always transmitted using the IMAP4 CRLF line termination + syntax, regardless of the underlying storage representation of the + data on the server. + + A server may choose to store message body binary content in a non- + encoded format. Regardless of the internal storage representation + used, the server MUST issue BODYSTRUCTURE responses that describe the + message as though the binary-encoded sections are encoded in a CTE + + + + + +Nerenberg Standards Track [Page 4] + +RFC 3516 IMAP4 Binary Content Extension April 2003 + + + acceptable to the IMAP4 base specification. Furthermore, the results + of a FETCH BODY MUST return the message body content in the format + described by the corresponding FETCH BODYSTRUCTURE response. + + While the server is allowed to modify the CTE of APPENDed <literal8> + data, this should only be done when it is absolutely necessary. + Gratuitous encoding changes will render useless most cryptographic + operations that have been performed on the message. + + This extension provides an optimization that is useful in certain + specific situations. It does not absolve clients from providing + basic functionality (content transfer decoding) that should be + available in all messaging clients. Clients supporting this + extension SHOULD be prepared to perform their own CTE decoding + operations. + +7. Formal Protocol Syntax + + The following syntax specification uses the augmented Backus-Naur + Form (ABNF) notation as used in [ABNF], and incorporates by reference + the Core Rules defined in that document. + + This syntax augments the grammar specified in [IMAP4rev1]. + + append =/ "APPEND" SP mailbox [SP flag-list] + [SP date-time] SP literal8 + + fetch-att =/ "BINARY" [".PEEK"] section-binary [partial] + / "BINARY.SIZE" section-binary + + literal8 = "~{" number "}" CRLF *OCTET + ; <number> represents the number of OCTETs + ; in the response string. + + msg-att-static =/ "BINARY" section-binary SP (nstring / literal8) + / "BINARY.SIZE" section-binary SP number + + partial = "<" number "." nz-number ">" + + resp-text-code =/ "UNKNOWN-CTE" + + section-binary = "[" [section-part] "]" + + + + + + + + + +Nerenberg Standards Track [Page 5] + +RFC 3516 IMAP4 Binary Content Extension April 2003 + + +8. Normative References + + [ABNF] Crocker, D., Editor, and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", RFC 2234, November 1997. + + [IMAP4rev1] Crispin, M., "Internet Message Access Protocol Version + 4rev1", RFC 3501, March 2003. + + [KEYWORD] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [MIME-IMB] Freed, N. and N. Borenstein, "Multipurpose Internet Mail + Extensions (MIME) Part One: Format of Internet Message + Bodies", RFC 2045, November 1996. + + [MIME-MHE] Moore, K., "MIME (Multipurpose Internet Mail Extensions) + Part Three: Message Header Extensions for Non-ASCII + Text", RFC 2047, November 1996. + +9. Security Considerations + + There are no known additional security issues with this extension + beyond those described in the base protocol described in [IMAP4rev1]. + +10. Intellectual Property + + The IETF takes no position regarding the validity or scope of any + intellectual property or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; neither does it represent that it + has made any effort to identify any such rights. Information on the + IETF's procedures with respect to rights in standards-track and + standards-related documentation can be found in BCP-11. Copies of + claims of rights made available for publication and any assurances of + licenses to be made available, or the result of an attempt made to + obtain a general license or permission for the use of such + proprietary rights by implementors or users of this specification can + be obtained from the IETF Secretariat. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights which may cover technology that may be required to practice + this standard. Please address the information to the IETF Executive + Director. + + + + + + +Nerenberg Standards Track [Page 6] + +RFC 3516 IMAP4 Binary Content Extension April 2003 + + +11. Author's Address + + Lyndon Nerenberg + Orthanc Systems + 1606 - 10770 Winterburn Road + Edmonton, Alberta + Canada T5S 1T6 + + EMail: lyndon@orthanc.ab.ca + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Nerenberg Standards Track [Page 7] + +RFC 3516 IMAP4 Binary Content Extension April 2003 + + +12. Full Copyright Statement + + Copyright (C) The Internet Society (2003). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Nerenberg Standards Track [Page 8] + diff --git a/imap/docs/rfc/rfc3656.txt b/imap/docs/rfc/rfc3656.txt new file mode 100644 index 00000000..6c0ab5b1 --- /dev/null +++ b/imap/docs/rfc/rfc3656.txt @@ -0,0 +1,1067 @@ + + + + + + +Network Working Group R. Siemborski +Request for Comments: 3656 Carnegie Mellon University +Category: Experimental December 2003 + + + The Mailbox Update (MUPDATE) + Distributed Mailbox Database Protocol + +Status of this Memo + + This memo defines an Experimental Protocol for the Internet + community. It does not specify an Internet standard of any kind. + Discussion and suggestions for improvement are requested. + Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2003). All Rights Reserved. + +Abstract + + As the demand for high-performance mail delivery agents increases, it + becomes apparent that single-machine solutions are inadequate to the + task, both because of capacity limits and that the failure of the + single machine means a loss of mail delivery for all users. It is + preferable to allow many machines to share the responsibility of mail + delivery. + + The Mailbox Update (MUPDATE) protocol allows a group of Internet + Message Access Protocol (IMAP) or Post Office Protocol - Version 3 + (POP3) servers to function with a unified mailbox namespace. This + document is intended to serve as a reference guide to that protocol. + + + + + + + + + + + + + + + + + + + +Siemborski Experimental [Page 1] + +RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 3 + 2.1. Atoms . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 2.2. Strings . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3. Server Responses . . . . . . . . . . . . . . . . . . . . . . 4 + 3.1. Response: OK . . . . . . . . . . . . . . . . . . . . . 5 + 3.2. Response: NO . . . . . . . . . . . . . . . . . . . . . 5 + 3.3. Response: BAD . . . . . . . . . . . . . . . . . . . . . 5 + 3.4. Response: BYE . . . . . . . . . . . . . . . . . . . . . 6 + 3.5. Response: RESERVE . . . . . . . . . . . . . . . . . . . 6 + 3.6. Response: MAILBOX . . . . . . . . . . . . . . . . . . . 6 + 3.7. Response: DELETE . . . . . . . . . . . . . . . . . . . 7 + 3.8. Server Capability Response. . . . . . . . . . . . . . . 7 + 4. Client Commands . . . . . . . . . . . . . . . . . . . . . . . 8 + 4.1. Command: ACTIVATE . . . . . . . . . . . . . . . . . . . 8 + 4.2. Command: AUTHENTICATE . . . . . . . . . . . . . . . . . 8 + 4.3. Command: DEACTIVATE . . . . . . . . . . . . . . . . . . 9 + 4.4. Command: DELETE . . . . . . . . . . . . . . . . . . . . 9 + 4.5. Command: FIND . . . . . . . . . . . . . . . . . . . . . 9 + 4.6. Command: LIST . . . . . . . . . . . . . . . . . . . . . 10 + 4.7. Command: LOGOUT . . . . . . . . . . . . . . . . . . . . 10 + 4.8. Command: NOOP . . . . . . . . . . . . . . . . . . . . . 10 + 4.9. Command: RESERVE. . . . . . . . . . . . . . . . . . . . 10 + 4.10. Command: STARTTLS . . . . . . . . . . . . . . . . . . . 11 + 4.11. Command: UPDATE . . . . . . . . . . . . . . . . . . . . 12 + 5. MUPDATE Formal Syntax . . . . . . . . . . . . . . . . . . . . 12 + 6. MUPDATE URL Scheme. . . . . . . . . . . . . . . . . . . . . . 14 + 6.1. MUPDATE URL Scheme Registration Form. . . . . . . . . . 14 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 15 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 + 9. Intellectual Property Rights. . . . . . . . . . . . . . . . . 16 + 10. References. . . . . . . . . . . . . . . . . . . . . . . . . . 17 + 10.1. Normative References. . . . . . . . . . . . . . . . . . 17 + 10.2. Informative References. . . . . . . . . . . . . . . . . 17 + 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18 + 12. Author's Address. . . . . . . . . . . . . . . . . . . . . . . 18 + 13. Full Copyright Statement. . . . . . . . . . . . . . . . . . . 19 + + + + + + + + + + + + +Siemborski Experimental [Page 2] + +RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 + + +1. Introduction + + In order to support an architecture where there are multiple [IMAP, + POP3] servers sharing a common mailbox database, it is necessary to + be able to provide atomic mailbox operations, as well as offer + sufficient guarantees about database consistency. + + The primary goal of the MUPDATE protocol is to be simple to implement + yet allow for database consistency between participants. + + The key words "MUST, "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", + "RECOMMENDED", and "MAY" in this document are to be interpreted as + defined in BCP 14, RFC 2119 [KEYWORDS]. + + In examples, "C:" and "S:" indicate lines sent by the client and + server respectively. + +2. Protocol Overview + + The MUPDATE protocol assumes a reliable data stream such as a TCP + network connection. IANA has registered port 3905 with a short name + of "mupdate" for this purpose. + + In the current implementation of the MUPDATE protocol there are three + types of participants: a single master server, slave (or replica) + servers, and clients. The master server maintains an authoritative + copy of the mailbox database. Slave servers connect to the MUPDATE + master server as clients, and function as replicas from the point of + view of end clients. End clients may connect to either the master or + any slave and perform searches against the database, however + operations that change the database can only be performed against the + master. For the purposes of protocol discussion we will consider a + slave's connection to the master identical to that of any other + client. + + After connection, all commands from a client to server must have an + associated unique tag which is an alphanumeric string. Commands MAY + be pipelined from the client to the server (that is, the client need + not wait for the response before sending the next command). The + server MUST execute the commands in the order they were received, + however. + + If the server supports an inactivity login timeout, it MUST be at + least 15 minutes. + + + + + + + +Siemborski Experimental [Page 3] + +RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 + + + MUPDATE uses data formats similar to those used in [ACAP]. That is, + atoms and strings. All commands and tags in the protocol are + transmitted as atoms. All other data is considered to a string, and + must be quoted or transmitted as a literal. + + Outside of a literal, both clients and servers MUST support line + lengths of at least 1024 octets (including the trailing CR and LF + characters). If a line of a longer length must be transmitted, + implementations MUST make use of literals to do so. + +2.1. Atoms + + An atom consists of one or more alphanumeric characters. Atoms MUST + be less than 15 octets in length. + +2.2. Strings + + As in [ACAP], a string may be either literal or a quoted string. A + literal is a sequence of zero or more octets (including CR and LF), + prefix-quoted with an octet count in the form of an open brace ("{"), + the number of octets, an optional plus sign to indicate that the data + follows immediately (a non-synchronized literal), a close brace + ("}"), and a CRLF sequence. If the plus sign is omitted (a + synchronized literal), then the receiving side MUST send a "+ go + ahead" response, and the sending side MUST wait for this response. + Servers MUST support literals of atleast 4096 octets. + + Strings that are sent from server to client SHOULD NOT be in the + synchronized literal format. + + A quoted string is a sequence of zero or more 7-bit characters, + excluding CR, LF, and the double quote (<">), with double quote + characters at each end. + + The empty string is represented as either "" (a quoted string with + zero characters between double quotes) or as {0} followed by CRLF (a + literal with an octet count of 0). + +3. Server Responses + + Every client command in the MUPDATE protocol may receive one or more + tagged responses from the server. Each response is preceded by the + same tag as the command that elicited the response from the server. + + + + + + + + +Siemborski Experimental [Page 4] + +RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 + + +3.1. Response: OK + + A tagged OK response indicates that the operation completed + successfully. There is a mandatory implementation-defined string + after the OK response. This response also indicates the beginning of + the streaming update mode when given in response to an UPDATE + command. + + Example: + +C: N01 NOOP +S: N01 OK "NOOP Complete" + +3.2. Response: NO + + A tagged NO response indicates that the operation was explicitly + denied by the server or otherwise failed. There is a mandatory + implementation-defined string after the NO response that SHOULD + explain the reason for denial. + + Example: + +C: A01 AUTHENTICATE "PLAIN" +S: A01 NO "PLAIN is not a supported SASL mechanism" + +3.3. Response: BAD + + A tagged BAD response indicates that the command from the client + could not be parsed or understood. There is a mandatory + implementation-defined string after the BAD response to provide + additional information about the error. Note that untagged BAD + responses are allowed if it is unclear what the tag for a given + command is (for example, if a blank line is received by the mupdate + server, it can generate an untagged BAD response). In the case of an + untagged response, the tag should be replaced with a "*". + + Example: + +C: C01 SELECT "INBOX" +S: C01 BAD "This is not an IMAP server" +C: +S: * BAD "Need Command" + + + + + + + + + +Siemborski Experimental [Page 5] + +RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 + + +3.4. Response: BYE + + A tagged BYE response indicates that the server has decided to close + the connection. There is a mandatory implementation-defined string + after the BYE response that SHOULD explain the reason for closing the + connection. The server MUST close the connection immediately after + transmitting the BYE response. + + Example: + +C: L01 LOGOUT +S: L01 BYE "User Logged Out" + +3.5. Response: RESERVE + + A tagged RESERVE response may only be given in response to a FIND, + LIST, or UPDATE command. It includes two parameters: the name of the + mailbox that is being reserved (in mUTF-7 encoding, as specified in + [IMAP]) and a location string whose contents is defined by the + clients that are using the database, though it is RECOMMENDED that + the format of this string be the hostname of the server which is + storing the mailbox. + + This response indicates that the given name is no longer available in + the namespace, though it does not indicate that the given mailbox is + available to clients at the current time. + + Example: + +S: U01 RESERVE "internet.bugtraq" "mail2.example.org" + +3.6. Response: MAILBOX + + A tagged MAILBOX response may only be given in response to a FIND, + LIST, or UPDATE command. It includes three parameters: the name of + the mailbox, a location string (as with RESERVE), and a client- + defined string that specifies the IMAP ACL [IMAP-ACL] of the mailbox. + This message indicates that the given mailbox is ready to be accessed + by clients. + + Example: + +S: U01 MAILBOX "internet.bugtraq" "mail2.example.org" "anyone rls" + + + + + + + + +Siemborski Experimental [Page 6] + +RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 + + +3.7. Response: DELETE + + A tagged DELETE response may only be given in response to an UPDATE + command, and MUST NOT be given before the OK response to the UPDATE + command is given. It contains a single parameter, that of the + mailbox that should be deleted from the slave's database. This + response indicates that the given mailbox no longer exists in the + namespace of the database, and may be given for any mailbox name, + active, reserved, or nonexistent. (Though implementations SHOULD NOT + issue DELETE responses for nonexistent mailboxes). + + Example: + +S: U01 DELETE "user.rjs3.sent-mail-jan-2002" + +3.8. Server Capability Response + + Upon connection of the client to the server, and directly following a + successful STARTTLS command, the server MUST issue a capabilities + banner, of the following format: + + The banner MUST contain a line that begins with "* AUTH" and contain + a space-separated list of SASL mechanisms that the server will accept + for authentication. The mechanism names are transmitted as atoms. + Servers MAY advertise no available mechanisms (to indicate that + STARTTLS must be completed before authentication may occur). If + STARTTLS is not supported by the server, then the line MUST contain + at least one mechanism. + + If the banner is being issued without a TLS layer, and the server + supports the STARTTLS command, the banner MUST contain the line "* + STARTTLS". If the banner is being issued under a TLS layer (or the + server does not support STARTTLS), the banner MUST NOT contain this + line. + + The last line of the banner MUST start with "* OK MUPDATE" and be + followed by four strings: the server's hostname, an implementation- + defined string giving the name of the implementation, an + implementation-defined string giving the version of the + implementation, and a string that indicates if the server is a master + or a slave. The master/slave indication MUST be either "(master)" or + an MUPDATE URL that defines where the master can be contacted. + + Any unrecognized responses before the "* OK MUPDATE" response MUST be + ignored by the client. + + + + + + +Siemborski Experimental [Page 7] + +RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 + + + Example: + +S: * AUTH KERBEROS_V4 GSSAPI +S: * STARTTLS +S: * OK MUPDATE "mupdate.example.org" "Cyrus" "v2.1.2" "(master)" + +4. Client Commands + + The following are valid commands that a client may send to the + MUPDATE server: AUTHENTICATE, ACTIVATE, DEACTIVATE, DELETE, FIND, + LIST, LOGOUT, NOOP, RESERVE, STARTTLS, and UPDATE. + + Before a successful AUTHENTICATE command has occurred, the server + MUST NOT accept any commands except for AUTHENTICATE, STARTTLS, and + LOGOUT (and SHOULD reply with a NO response for all other commands). + +4.1. Command: ACTIVATE + + The ACTIVATE command has 3 parameters: the mailbox name, its + location, and its ACL. This command MUST NOT not be issued to a + slave server. + + This command can also be used to update the ACL or location + information of a mailbox. Note that it is not a requirement for a + mailbox to be reserved (or even exist in the database) for an + ACTIVATE command to succeed, implementations MUST allow this behavior + as it facilitates synchronization of the database with the current + state of the mailboxes. + +4.2. Command: AUTHENTICATE + + The AUTHENTICATE command initiates a [SASL] negotiation session + between the client and the server. It has two parameters. The first + parameter is mandatory, and is a string indicating the desired [SASL] + mechanism. The second is a string containing an optional BASE64 + encoded (as defined in section 6.8 of [MIME]) client first send. + + All of the remaining SASL blobs that are sent MUST be sent across the + wire must be in BASE64 encoded format, and followed by a CR and LF + combination. They MUST NOT be encoded as strings. + + Clients may cancel authentication by sending a * followed by a CR and + LF. + + The [SASL] service name for the MUPDATE protocol is "mupdate". + Implementations are REQUIRED to implement the GSSAPI [SASL] + mechanism, though they SHOULD implement as many mechanisms as + possible. + + + +Siemborski Experimental [Page 8] + +RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 + + + If a security layer is negotiated, it should be used directly + following the CR and LF combination at the end of the server's OK + response (i.e., beginning with the client's next command) Only one + successful AUTHENTICATE command may be issued per session. + +4.3. Command: DEACTIVATE + + The DEACTIVATE command takes two parameters, the mailbox name and + location data. The mailbox MUST already exist and be activated on + the MUPDATE server. If the server responds OK, then the mailbox name + has been moved to the RESERVE state. If the server responds NO, then + the mailbox name has not been moved (for example, the mailbox was not + already active). Any ACL information that is known about the mailbox + MAY be lost when a DEACTIVATE succeeds. This command MUST NOT be + issued to a slave. + + Example: + +C: A01 DEACTIVATE "user.rjs3.new" "mail3.example.org!u4" +S: A01 OK "Mailbox Reserved." + +4.4. Command: DELETE + + The DELETE command takes only a single parameter, the mailbox name to + be removed from the database's namespace. The server SHOULD give a + NO response if the mailbox does not exist. This command MUST NOT be + issued to a slave server. + +4.5. Command: FIND + + The FIND command takes a single parameter, a mailbox name. The + server then responds with the current record for the given mailbox, + if any, and an OK response. + + Example (mailbox does not exist): + +C: F01 FIND "user.rjs3.xyzzy" +S: F01 OK "Search Complete" + + Example (mailbox is reserved): + +C: F01 FIND "user.rjs3" +S: F01 RESERVE "user.rjs3" "mail4.example.org" +S: F01 OK "Search Complete" + + + + + + + +Siemborski Experimental [Page 9] + +RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 + + +4.6. Command: LIST + + The LIST command is similar to running FIND across the entire + database. The LIST command takes a single optional parameter, which + is a prefix to try to match against the location field of the + records. Without the parameter, LIST returns every record in the + database. + + For each mailbox that matches, either a MAILBOX or a RESERVE response + (as applicable) is sent to the client. When all responses are + complete, an OK response is issued. + + Example: + +C: L01 LIST +S: L01 RESERVE "user.rjs3" "mail4.example.org!u2" +S: L01 MAILBOX "user.leg" "mail2.example.org!u1" "leg lrswipcda" +S: L01 OK "List Complete" +C: L02 LIST "mail4.example.org!" +S: L02 RESERVE "user.rjs3" "mail4.example.org!u2" +S: L02 OK "List Complete" + +4.7. Command: LOGOUT + + The LOGOUT command tells the server to close the connection. Its + only valid response is the BYE response. The LOGOUT command takes no + parameters. + +4.8. Command: NOOP + + The NOOP command takes no parameters. Provided the client is + authenticated, its only acceptable response is an OK. Any idle + timeouts that the server may have on the connection SHOULD be reset + upon receipt of this command. + + If this command is issued after an UPDATE command has been issued, + then the OK response also indicates that all pending database updates + have been sent to the client. That is, the slave can guarantee that + its local database is up to date as of a certain time by issuing a + NOOP and waiting for the OK. The OK MUST NOT return until all + updates that were pending at the time of the NOOP have been sent. + +4.9. Command: RESERVE + + The RESERVE command takes two parameters (just like the RESERVE + response), the mailbox name to reserve and location data. If the + server responds OK, then the mailbox name has been reserved. If the + server responds NO, then the mailbox name has not been reserved (for + + + +Siemborski Experimental [Page 10] + +RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 + + + example, another server has reserved it already). This command MUST + NOT be issued to a slave. + + The typical sequence for mailbox creation is: + +C: R01 RESERVE "user.rjs3.new" "mail3.example.org!u4" +S: R01 OK "Mailbox Reserved." +<client does local mailbox create operations> +C: A01 ACTIVATE "user.rjs3.new" "mail3.example.org!u4" "rjs3 lrswipcda" +S: A01 OK "Mailbox Activated." + +4.10. Command: STARTTLS + + The STARTTLS command requests the commencement of a [TLS] + negotiation. The negotiation begins immediately after the CRLF in + the OK response. After a client issues a STARTTLS command, it MUST + NOT issue further commands until a server response is seen and the + [TLS] negotiation is complete. + + The STARTTLS command is only valid in non-authenticated state. The + server remains in non-authenticated state, even if client credentials + are supplied during the [TLS] negotiation. The [SASL] EXTERNAL + mechanism MAY be used to authenticate once [TLS] client credentials + are successfully exchanged. Note that servers are not required to + support the EXTERNAL mechanism. + + After the [TLS] layer is established, the server MUST re-issue the + initial response banner (see Section 3.8). This is necessary to + protect against man-in-the-middle attacks which alter the + capabilities list prior to STARTTLS, as well as to advertise any new + SASL mechanisms (or other capabilities) that may be available under + the layer. The client MUST discard cached capability information and + replace it with the new information. + + After the a successful STARTTLS command, the server SHOULD return a + NO response to additional STARTTLS commands. + + Servers MAY choose to not implement STARTTLS. In this case, they + MUST NOT advertise STARTTLS in their capabilities banner, and SHOULD + return a BAD response to the STARTTLS command, if it is issued. + + Example: + +C: S01 STARTTLS +S: S01 OK "Begin TLS negotiation now" +<TLS negotiation, further commands are under TLS layer> +S: * AUTH KERBEROS_V4 GSSAPI PLAIN +S: * OK MUPDATE "mupdate.example.org" "Cyrus" "v2.1.2" "(master)" + + + +Siemborski Experimental [Page 11] + +RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 + + +4.11. Command: UPDATE + + The UPDATE command is how a slave initializes an update stream from + the master (though it is also valid to issue this command to a + slave). In response to the command, the server returns a list of all + mailboxes in its database (the same results as a parameterless LIST + command) followed by an OK response. From this point forward, + whenever an update occurs to the master database, it MUST stream the + update to the slave within 30 seconds. That is, it will send + RESERVE, MAILBOX, or DELETE responses as they are applicable. + + After a client has issued an UPDATE command, it may only issue NOOP + and LOGOUT commands for the remainder of the session. + + Example: + +C: U01 UPDATE +S: U01 MAILBOX "user.leg" "mail2.example.org!u1" "leg lrswipcda" +S: U01 MAILBOX "user.rjs3" "mail3.example.org!u4" "rjs3 lrswipcda" +S: U01 RESERVE "internet.bugtraq" "mail1.example.org!u5" "anyone lrs" +S: U01 OK "Streaming Begins" +<some time goes by, and another client creates a new mailbox> +S: U01 RESERVE "user.leg.new" "mail2.example.org!u1" +<some more time passes, and the create succeeds> +S: U01 MAILBOX "user.leg.new" "mail2.example.org!u1" "leg lrswipcda" +<much more time passes, and the slave decides to send a NOOP to reset +its inactivity timer> +C: N01 NOOP +S: U01 DELETE "user.leg.new" +S: N01 OK "NOOP Complete" + +5. MUPDATE Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [ABNF]. This uses the ABNF core + rules as specified in Appendix A of [ABNF]. + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of upper or lower case characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. + + Note that this specification also uses some terminals from section 8 + of [ACAP]. + + cmd-activate = "ACTIVATE" SP string SP string SP string + + cmd-authenticate = "AUTHENTICATE" SP sasl-mech [ SP string ] + + + +Siemborski Experimental [Page 12] + +RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 + + + cmd-delete = "DELETE" SP string + + cmd-find = "FIND" SP string + + cmd-list = "LIST" [ SP string ] + + cmd-logout = "LOGOUT" + + cmd-noop = "NOOP" + + cmd-reserve = "RESERVE" SP string SP string + + cmd-starttls = "STARTTLS" + + cmd-update = "UPDATE" + + command = tag SP command-type CRLF + + command-type = cmd-activate / cmd-authenticate / cmd-delete / + cmd-find / cmd-list / cmd-logout / cmd-noop / + cmd-reserve / cmd-starttls / cmd-update + + response = tag SP response-type CRLF + + response-type = rsp-ok / rsp-no / rsp-bad / rsp-bye / rsp-mailbox / + rsp-reserve / rsp-delete + + rsp-bad = "BAD" SP string + + rsp-bye = "BYE" SP string + + rsp-mailbox = "MAILBOX" SP string SP string SP string + + rsp-no = "NO" SP string + + rsp-ok = "OK" SP string + + rsp-reserve = "RESERVE" SP string SP string + + rsp-delete = "DELETE" SP string + + sasl-mech = 1*ATOM-CHAR + ; ATOM-CHAR is defined in [ACAP] + + string = quoted / literal + ; quoted and literal are defined in [ACAP] + + + + + +Siemborski Experimental [Page 13] + +RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 + + + tag = 1*ATOM-CHAR + ; ATOM-CHAR is defined in [ACAP] + +6. MUPDATE URL Scheme + + This document defines the a URL scheme for the purposes of + referencing MUPDATE resources, according to the requirements in + [RFC2717]. This includes both MUPDATE servers as a whole, along with + individual mailbox entries on a given MUPDATE server. + + There is no MIME type associated with these resources. It is + intended that a URL consumer would either retrieve the MUPDATE record + in question, or simply connect to the MUPDATE server running on the + specified host. Note that the consumer will need to have + authentication credentials for the specified host. + + The MUPDATE URL scheme is similar to the IMAP URL scheme [IMAP-URL]. + However, it only takes one of two possible forms: + + mupdate://<iserver>/ + mupdate://<iserver>/<mailbox> + + The first form refers to a MUPDATE server as a whole, the second form + indicates both the server and a mailbox to run a FIND against once + authenticated to the server. Note that part of <iserver> may include + username and authentication information along with a hostname and + port. + +6.1. MUPDATE URL Scheme Registration Form + + URL scheme name: "mupdate" + + URL scheme syntax: + + This defines the MUPDATE URL Scheme in [ABNF]. Terminals from the + BNF of IMAP URLs [IMAP-URL] are also used. + + mupdateurl = "mupdate://" iserver "/" [ enc_mailbox ] + ; iserver and enc_mailbox are as defined in [IMAP-URL] + + Character encoding considerations: + + Identical to those described in [IMAP-URL] for the appropriate + terminals. + + + + + + + +Siemborski Experimental [Page 14] + +RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 + + + Intended Usage: + + The form of the URL without an associated mailbox is intended to + designate a MUPDATE server only. If a mailbox name is included in + the URL, then the consumer is expected to execute a FIND command + for that mailbox on the specified server. + + Applications and/or protocols which use this URL scheme name: + + The protocol described in this document. + + Interoperability Considerations: + + None. + + Security Considerations: + + Users of the MUPDATE URL Scheme should review the security + considerations that are discussed in [IMAP-URL]. In particular, + the consequences of including authentication mechanism information + in a URL should be reviewed. + + Relevant Publications: + + This document and [IMAP-URL]. + + Author, Change Controller, and Contact for Further Information: + + Author of this document. + +7. Security Considerations + + While no unauthenticated users may make modifications or even perform + searches on the database, it is important to note that this + specification assumes no protections of any type for authenticated + users. + + All authenticated users have complete access to the database. For + this reason it is important to ensure that accounts that are making + use of the database are well secured. + + A more secure deployment might have all read only access go through a + slave, and only have accounts which need write access use the master. + This has the disadvantage of a marginally longer time for updates to + reach the clients. + + + + + + +Siemborski Experimental [Page 15] + +RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 + + + The protocol assumes that all authenticated users are cooperating to + maintain atomic operations. Therefore, all new mailboxes SHOULD be + RESERVEd before they are ACTIVATEd, despite the fact that the + protocol does not require this, and it is therefore possible for a + set of participants which do not obey the provided locking to create + an inconsistent database. RESERVEing the mailbox first is not + required to perform an activate because this behavior simplifies + synchronization with the actual location of the mailboxes. + +8. IANA Considerations + + The IANA has assigned TCP port number 3905 to "mupdate". + + The IANA has registered a URL scheme for the MUPDATE protocol, as + defined in section 6.1 of this document. + + IANA has registered a GSSAPI service name of "mupdate" for the + MUPDATE protocol in the registry maintained at: + + http://www.iana.org/assignments/gssapi-service-names + +9. Intellectual Property Rights + + The IETF takes no position regarding the validity or scope of any + intellectual property or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; neither does it represent that it + has made any effort to identify any such rights. Information on the + IETF's procedures with respect to rights in standards-track and + standards-related documentation can be found in BCP-11. Copies of + claims of rights made available for publication and any assurances of + licenses to be made available, or the result of an attempt made to + obtain a general license or permission for the use of such + proprietary rights by implementors or users of this specification can + be obtained from the IETF Secretariat. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights which may cover technology that may be required to practice + this standard. Please address the information to the IETF Executive + Director. + + + + + + + + + +Siemborski Experimental [Page 16] + +RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 + + +10. References + +10.1. Normative References + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [IMAP] Crispin, M., "Internet Message Access Protocol - Version + 4", RFC 3501, March 2003. + + [ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", RFC 2234, November 1997. + + [MIME] Freed, N. and N. Bornstein, "Multipurpose Internet Mail + Extensions (MIME) Part One: Format of Internet Message + Bodies", RFC 2045, November 1996. + + [IMAP-ACL] Myers, J., "IMAP4 ACL extension", RFC 2086, January 1997. + + [SASL] Myers, J., "Simple Authentication and Security Layer + (SASL)", RFC 2222, October 1997. + + [IMAP-URL] Newman, C., "IMAP URL Scheme", RFC 2192, September 1997. + + [ACAP] Newman, C. and J. Myers, "ACAP -- Application + Configuration Access Protocol", RFC 2244, November 1997. + + [TLS] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", + RFC 2246, January 1999. + +10.2. Informative References + + [POP3] Myers, J. and M. Rose, "Post Office Protocol - Version + 3", STD 53, RFC 1939, May 1996. + + [RFC2717] Petke, R. and I. King, "Registration Procedures for URL + Scheme Names", BCP 35, RFC 2717, November 1999. + + + + + + + + + + + + + + +Siemborski Experimental [Page 17] + +RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 + + +11. Acknowledgments + + Lawrence Greenfield and Ken Murchison, for a great deal of input on + both the protocol and the text of the documents. + +12. Author's Address + + Robert Siemborski + Carnegie Mellon, Andrew Systems Group + Cyert Hall 207 + 5000 Forbes Avenue + Pittsburgh, PA 15213 + + Phone: (412) 268-7456 + EMail: rjs3+@andrew.cmu.edu + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Siemborski Experimental [Page 18] + +RFC 3656 MUPDATE Distributed Mailbox Database Protocol December 2003 + + +13. Full Copyright Statement + + Copyright (C) The Internet Society (2003). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assignees. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Siemborski Experimental [Page 19] + diff --git a/imap/docs/rfc/rfc3691.txt b/imap/docs/rfc/rfc3691.txt new file mode 100644 index 00000000..2f4e9b44 --- /dev/null +++ b/imap/docs/rfc/rfc3691.txt @@ -0,0 +1,283 @@ + + + + + + +Network Working Group A. Melnikov +Request for Comments: 3691 Isode Ltd. +Category: Standards Track February 2004 + + + Internet Message Access Protocol (IMAP) UNSELECT command + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2004). All Rights Reserved. + +Abstract + + This document defines an UNSELECT command that can be used to close + the current mailbox in an Internet Message Access Protocol - version + 4 (IMAP4) session without expunging it. Certain types of IMAP + clients need to release resources associated with the selected + mailbox without selecting a different mailbox. While IMAP4 provides + this functionality (via a SELECT command with a nonexistent mailbox + name or reselecting the same mailbox with EXAMINE command), a more + clean solution is desirable. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 + 2. UNSELECT command . . . . . . . . . . . . . . . . . . . . . . . 2 + 3. Security Considerations. . . . . . . . . . . . . . . . . . . . 3 + 4. Formal Syntax. . . . . . . . . . . . . . . . . . . . . . . . . 3 + 5. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 3 + 6. Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . . 3 + 7. Normative References . . . . . . . . . . . . . . . . . . . . . 4 + 8. Author's Address . . . . . . . . . . . . . . . . . . . . . . . 4 + 9. Full Copyright Statement . . . . . . . . . . . . . . . . . . . 5 + + + + + + + + + + +Melnikov Standards Track [Page 1] + +RFC 3691 IMAP UNSELECT command February 2004 + + +1. Introduction + + Certain types of IMAP clients need to release resources associated + with the selected mailbox without selecting a different mailbox. + While [IMAP4] provides this functionality (via a SELECT command with + a nonexistent mailbox name or reselecting the same mailbox with + EXAMINE command), a more clean solution is desirable. + + [IMAP4] defines the CLOSE command that closes the selected mailbox as + well as permanently removes all messages with the \Deleted flag set. + + However [IMAP4] lacks a command that simply closes the mailbox + without expunging it. This document defines the UNSELECT command for + this purpose. + + A server which supports this extension indicates this with a + capability name of "UNSELECT". + + "C:" and "S:" in examples show lines sent by the client and server + respectively. + + The keywords "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" in + this document when typed in uppercase are to be interpreted as + defined in "Key words for use in RFCs to Indicate Requirement Levels" + [KEYWORDS]. + +2. UNSELECT Command + + Arguments: none + + Responses: no specific responses for this command + + Result: OK - unselect completed, now in authenticated state + BAD - no mailbox selected, or argument supplied but + none permitted + + The UNSELECT command frees server's resources associated with the + selected mailbox and returns the server to the authenticated + state. This command performs the same actions as CLOSE, except + that no messages are permanently removed from the currently + selected mailbox. + + Example: C: A341 UNSELECT + S: A341 OK Unselect completed + + + + + + + +Melnikov Standards Track [Page 2] + +RFC 3691 IMAP UNSELECT command February 2004 + + +3. Security Considerations + + It is believed that this extension doesn't raise any additional + security concerns not already discussed in [IMAP4]. + +4. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [ABNF]. Non-terminals + referenced but not defined below are as defined by [IMAP4]. + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of upper or lower case characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. + + command-select /= "UNSELECT" + +5. IANA Considerations + + IMAP4 capabilities are registered by publishing a standards track or + IESG approved experimental RFC. The registry is currently located + at: + + http://www.iana.org/assignments/imap4-capabilities + + This document defines the UNSELECT IMAP capabilities. IANA has added + this capability to the registry. + +6. Acknowledgments + + UNSELECT command was originally implemented by Tim Showalter in Cyrus + IMAP server. + + Also, the author of the document would like to thank Vladimir Butenko + and Mark Crispin for reminding that UNSELECT has to be documented. + Also thanks to Simon Josefsson for pointing out that there are + multiple ways to implement UNSELECT. + + + + + + + + + + + + + +Melnikov Standards Track [Page 3] + +RFC 3691 IMAP UNSELECT command February 2004 + + +7. Normative References + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [IMAP4] Crispin, M., "Internet Message Access Protocol - Version + 4rev1", RFC 3501, March 2003. + + [ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 2234, November 1997. + +8. Author's Address + + Alexey Melnikov + Isode Limited + 5 Castle Business Village + Hampton, Middlesex TW12 2BX + + EMail: Alexey.Melnikov@isode.com + URI: http://www.melnikov.ca/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Melnikov Standards Track [Page 4] + +RFC 3691 IMAP UNSELECT command February 2004 + + +9. Full Copyright Statement + + Copyright (C) The Internet Society (2004). This document is subject + to the rights, licenses and restrictions contained in BCP 78 and + except as set forth therein, the authors retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE + REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE + INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed + to pertain to the implementation or use of the technology + described in this document or the extent to which any license + under such rights might or might not be available; nor does it + represent that it has made any independent effort to identify any + such rights. Information on the procedures with respect to + rights in RFC documents can be found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use + of such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository + at http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention + any copyrights, patents or patent applications, or other + proprietary rights that may cover technology that may be required + to implement this standard. Please address the information to the + IETF at ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + +Melnikov Standards Track [Page 5] + diff --git a/imap/docs/rfc/rfc4314.txt b/imap/docs/rfc/rfc4314.txt new file mode 100644 index 00000000..e73a56f2 --- /dev/null +++ b/imap/docs/rfc/rfc4314.txt @@ -0,0 +1,1515 @@ + + + + + + +Network Working Group A. Melnikov +Request for Comments: 4314 Isode Ltd. +Obsoletes: 2086 December 2005 +Category: Standards Track + + + IMAP4 Access Control List (ACL) Extension + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2005). + +Abstract + + The Access Control List (ACL) extension (RFC 2086) of the Internet + Message Access Protocol (IMAP) permits mailbox access control lists + to be retrieved and manipulated through the IMAP protocol. + + This document is a revision of RFC 2086. It defines several new + access control rights and clarifies which rights are required for + different IMAP commands. + + + + + + + + + + + + + + + + + + + + + + +Melnikov Standards Track [Page 1] + +RFC 4314 IMAP ACL December 2005 + + +Table of Contents + + 1. Introduction and Overview .......................................3 + 1.1. Conventions Used in This Document ..........................3 + 2. Access Control ..................................................3 + 2.1. Standard Rights ............................................5 + 2.1.1. Obsolete Rights .....................................5 + 2.2. Rights Defined in RFC 2086 .................................8 + 3. Access control management commands and responses ................8 + 3.1. SETACL Command .............................................8 + 3.2. DELETEACL Command ..........................................9 + 3.3. GETACL Command ............................................10 + 3.4. LISTRIGHTS Command ........................................10 + 3.5. MYRIGHTS Command ..........................................11 + 3.6. ACL Response ..............................................11 + 3.7. LISTRIGHTS Response .......................................12 + 3.8. MYRIGHTS Response .........................................12 + 4. Rights Required to Perform Different IMAP4rev1 Commands ........12 + 5. Other Considerations ...........................................17 + 5.1. Additional Requirements and Implementation Notes ..........17 + 5.1.1. Servers ............................................17 + 5.1.2. Clients ............................................18 + 5.2. Mapping of ACL Rights to READ-WRITE and READ-ONLY + Response Codes ............................................19 + 6. Security Considerations ........................................20 + 7. Formal Syntax ..................................................21 + 8. IANA Considerations ............................................22 + 9. Internationalization Considerations ............................22 + Appendix A. Changes since RFC 2086 ................................23 + Appendix B. Compatibility with RFC 2086 ...........................24 + Appendix C. Known Deficiencies ....................................24 + Appendix D. Acknowledgements ......................................25 + Normative References ..............................................25 + Informative References ............................................25 + + + + + + + + + + + + + + + + + +Melnikov Standards Track [Page 2] + +RFC 4314 IMAP ACL December 2005 + + +1. Introduction and Overview + + The ACL (Access Control List) extension of the Internet Message + Access Protocol [IMAP4] permits mailbox access control lists to be + retrieved and manipulated through the IMAP protocol. + + This document is a revision of RFC 2086 [RFC2086]. It tries to + clarify different ambiguities in RFC 2086, in particular, the use of + UTF-8 [UTF-8] in access identifiers, which rights are required for + different IMAP4 commands, and how READ-WRITE/READ-ONLY response codes + are related to ACL. + +1.1. Conventions Used in This Document + + In examples, "C:" and "S:" indicate lines sent by the client and + server respectively. + + In all examples "/" character is used as hierarchy separator. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [KEYWORDS]. + + The phrase "ACL server" is just a shortcut for saying "IMAP server + that supports ACL extension as defined in this document". + +2. Access Control + + The ACL extension is present in any IMAP4 implementation that returns + "ACL" as one of the supported capabilities to the CAPABILITY command. + + A server implementation conformant to this document MUST also return + rights (see below) not defined in Section 2.2 in the "RIGHTS=" + capability. + + An access control list is a set of <access identifier,rights> pairs. + An ACL applies to a mailbox name. + + Access identifier (or just "identifier") is a UTF-8 [UTF-8] string. + The identifier "anyone" is reserved to refer to the universal + identity (all authentications, including anonymous). All user name + strings accepted by the LOGIN or AUTHENTICATE commands to + authenticate to the IMAP server are reserved as identifiers for the + corresponding users. Identifiers starting with a dash ("-") are + reserved for "negative rights", described below. All other + identifier strings are interpreted in an implementation-defined + manner. + + + + +Melnikov Standards Track [Page 3] + +RFC 4314 IMAP ACL December 2005 + + + Rights is a string listing a (possibly empty) set of alphanumeric + characters, each character listing a set of operations that is being + controlled. Lowercase letters are reserved for "standard" rights, + listed in Section 2.1. (Note that for compatibility with deployed + clients and servers uppercase rights are not allowed.) The set of + standard rights can only be extended by a standards-track document. + Digits are reserved for implementation- or site-defined rights. + + An implementation MAY tie rights together or MAY force rights to + always or never be granted to particular identifiers. For example, + in an implementation that uses UNIX mode bits, the rights "swite" are + tied, the "a" right is always granted to the owner of a mailbox and + is never granted to another user. If rights are tied in an + implementation, the implementation must be conservative in granting + rights in response to SETACL commands--unless all rights in a tied + set are specified, none of that set should be included in the ACL + entry for that identifier. A client can discover the set of rights + that may be granted to a given identifier in the ACL for a given + mailbox name by using the LISTRIGHTS command. + + It is possible for multiple identifiers in an access control list to + apply to a given user. For example, an ACL may include rights to be + granted to the identifier matching the user, one or more + implementation-defined identifiers matching groups that include the + user, and/or the identifier "anyone". How these rights are combined + to determine the user's access is implementation defined. An + implementation may choose, for example, to use the union of the + rights granted to the applicable identifiers. An implementation may + instead choose, for example, to use only those rights granted to the + most specific identifier present in the ACL. A client can determine + the set of rights granted to the logged-in user for a given mailbox + name by using the MYRIGHTS command. + + When an identifier in an ACL starts with a dash ("-"), that indicates + that associated rights are to be removed from the identifier prefixed + by the dash. This is referred to as a "negative right". This + differs from DELETEACL in that a negative right is added to the ACL + and is a part of the calculation of the rights. + + Let's assume that an identifier "fred" refers to a user with login + "fred". If the identifier "-fred" is granted the "w" right, that + indicates that the "w" right is to be removed from users matching the + identifier "fred", even though the user "fred" might have the "w" + right as a consequence of some other identifier in the ACL. A + DELETEACL of "fred" simply deletes the identifier "fred" from the + ACL; it does not affect any rights that the user "fred" may get from + another entry in the ACL, in particular it doesn't affect rights + granted to the identifier "-fred". + + + +Melnikov Standards Track [Page 4] + +RFC 4314 IMAP ACL December 2005 + + + Server implementations are not required to support "negative right" + identifiers. + +2.1. Standard Rights + + The currently defined standard rights are (note that the list below + doesn't list all commands that use a particular right): + + l - lookup (mailbox is visible to LIST/LSUB commands, SUBSCRIBE + mailbox) + r - read (SELECT the mailbox, perform STATUS) + s - keep seen/unseen information across sessions (set or clear + \SEEN flag via STORE, also set \SEEN during APPEND/COPY/ + FETCH BODY[...]) + w - write (set or clear flags other than \SEEN and \DELETED via + STORE, also set them during APPEND/COPY) + i - insert (perform APPEND, COPY into mailbox) + p - post (send mail to submission address for mailbox, + not enforced by IMAP4 itself) + k - create mailboxes (CREATE new sub-mailboxes in any + implementation-defined hierarchy, parent mailbox for the new + mailbox name in RENAME) + x - delete mailbox (DELETE mailbox, old mailbox name in RENAME) + t - delete messages (set or clear \DELETED flag via STORE, set + \DELETED flag during APPEND/COPY) + e - perform EXPUNGE and expunge as a part of CLOSE + a - administer (perform SETACL/DELETEACL/GETACL/LISTRIGHTS) + +2.1.1. Obsolete Rights + + Due to ambiguity in RFC 2086, some existing RFC 2086 server + implementations use the "c" right to control the DELETE command. + Others chose to use the "d" right to control the DELETE command. For + the former group, let's define the "create" right as union of the "k" + and "x" rights, and the "delete" right as union of the "e" and "t" + rights. For the latter group, let's define the "create" rights as a + synonym to the "k" right, and the "delete" right as union of the "e", + "t", and "x" rights. + + For compatibility with RFC 2086, this section defines two virtual + rights "d" and "c". + + If a client includes the "d" right in a rights list, then it MUST be + treated as if the client had included every member of the "delete" + right. (It is not an error for a client to specify both the "d" + right and one or more members of the "delete" right, but the effect + is no different than if just the "d" right or all members of the + "delete" right had been specified.) + + + +Melnikov Standards Track [Page 5] + +RFC 4314 IMAP ACL December 2005 + + + When any of the "delete" member rights is set in a list of rights, + the server MUST also include the "d" right when returning the list in + a MYRIGHTS or ACL response. This is to enable older clients + conforming to RFC 2086 to work with newer servers. (*) + + Example: C: A001 SeTacl INBOX/Drafts David lrswida + S: A001 OK Setacl complete + + The client has specified the "d" right in the SETACL command above + and it expands to "et" on the server: + + C: A002 getacl INBOX/Drafts + S: * ACL INBOX Fred rwipslxcetda David lrswideta + S: A002 OK Getacl complete + + If the identifier specified in the LISTRIGHTS command can be granted + any of the "delete" member rights on a mailbox, then the server MUST + include the "d" right in the corresponding LISTRIGHTS response. (*) + If the member rights aren't tied to non-member rights, then the "d" + right is returned by itself in the LISTRIGHTS response. If any of + the member rights needs to be tied to one (or more) non-member right, + then the "d" right and all of the member rights need to be tied to + the same non-member right(s) (**). + + If a client includes the "c" right in a rights list, then it MUST be + treated as if the client had included every member of the "create" + right. (It is not an error for a client to specify both the "c" + right and one or more members of the "create" right, but the effect + is no different than if just the "c" right or all members of the + "create" right had been specified.) + + When any of the "create" member rights is set in a list of rights, + the server MUST also include the "c" right when returning the list in + a MYRIGHTS or ACL response. This is to enable older clients + conforming to RFC 2086 to work with newer servers. (*) + + Example: C: A003 Setacl INBOX/Drafts Byron lrswikda + S: A001 OK Setacl complete + C: A002 getAcl INBOX/Drafts + S: * ACL INBOX Fred rwipslxcetda Byron lrswikcdeta + S: A002 OK Getacl complete + + The client has specified the "d" right in the SETACL command above + and it expands to "et" on the server: As the client has specified the + "k" right (which is a member of the "c" right), the server also + returns the "c" right. + + + + + +Melnikov Standards Track [Page 6] + +RFC 4314 IMAP ACL December 2005 + + + If the identifier specified in the LISTRIGHTS command can be granted + any of the "create" member rights on a mailbox, then the server MUST + include the "c" right in the corresponding LISTRIGHTS response. (*) + If the member rights aren't tied to non-member rights, then the "c" + right is returned by itself in the LISTRIGHTS response. If any of + the member rights needs to be tied to one (or more) non-member right, + then the "c" right and all of the member rights need to be tied to + the same non-member right(s) (**). + + Example: The server that ties the rights as follows: + + lr s w i p k x t + + and c=k + + will return: + + S: * LISTRIGHTS archive/imap anyone "" + lr s w i p k x t c d + + Example: The server that ties the rights as follows: + + lr s w i p k xte + + and c=k + + will return: + + S: * LISTRIGHTS archive/imap anyone "" + lr s w i p k xte c d + + Example: The server that ties the rights as follows: + + lr s w i p k x te + + and c=k + + will return: + + S: * LISTRIGHTS archive/imap anyone "" + lr s w i p k c x te d + + Example: The server that ties the rights as follows: + + lr swte i p k x + + and c=kx + + + + +Melnikov Standards Track [Page 7] + +RFC 4314 IMAP ACL December 2005 + + + will return: + + S: * LISTRIGHTS archive/imap anyone "" + lr swted i p k x c + + (*) Clients conforming to this document MUST ignore the virtual "d" + and "c" rights in MYRIGHTS, ACL, and LISTRIGHTS responses. + + (**) The IMAPEXT Working Group has debated this issue in great length + and after reviewing existing ACL implementations concluded that + this is a reasonable restriction. + +2.2. Rights Defined in RFC 2086 + + The "RIGHTS=" capability MUST NOT include any of the rights defined + in RFC 2086: "l", "r", "s", "w", "i", "p", "a", "c", "d", and the + digits ("0" .. "9"). + +3. Access control management commands and responses + + Servers, when processing a command that has an identifier as a + parameter (i.e., any of SETACL, DELETEACL, and LISTRIGHTS commands), + SHOULD first prepare the received identifier using "SASLprep" profile + [SASLprep] of the "stringprep" algorithm [Stringprep]. If the + preparation of the identifier fails or results in an empty string, + the server MUST refuse to perform the command with a BAD response. + Note that Section 6 recommends additional identifier's verification + steps. + +3.1. SETACL Command + + Arguments: mailbox name + identifier + access right modification + + Data: no specific data for this command + + Result: OK - setacl completed + NO - setacl failure: can't set acl + BAD - arguments invalid + + The SETACL command changes the access control list on the specified + mailbox so that the specified identifier is granted permissions as + specified in the third argument. + + The third argument is a string containing an optional plus ("+") or + minus ("-") prefix, followed by zero or more rights characters. If + the string starts with a plus, the following rights are added to any + + + +Melnikov Standards Track [Page 8] + +RFC 4314 IMAP ACL December 2005 + + + existing rights for the identifier. If the string starts with a + minus, the following rights are removed from any existing rights for + the identifier. If the string does not start with a plus or minus, + the rights replace any existing rights for the identifier. + + Note that an unrecognized right MUST cause the command to return the + BAD response. In particular, the server MUST NOT silently ignore + unrecognized rights. + + Example: C: A001 GETACL INBOX/Drafts + S: * ACL INBOX/Drafts Fred rwipslxetad Chris lrswi + S: A001 OK Getacl complete + C: A002 SETACL INBOX/Drafts Chris +cda + S: A002 OK Setacl complete + C: A003 GETACL INBOX/Drafts + S: * ACL INBOX/Drafts Fred rwipslxetad Chris lrswicdakxet + S: A003 OK Getacl complete + + + C: A035 SETACL INBOX/Drafts John lrQswicda + S: A035 BAD Uppercase rights are not allowed + + + C: A036 SETACL INBOX/Drafts John lrqswicda + S: A036 BAD The q right is not supported + +3.2. DELETEACL Command + + Arguments: mailbox name + identifier + + Data: no specific data for this command + + Result: OK - deleteacl completed + NO - deleteacl failure: can't delete acl + BAD - arguments invalid + + The DELETEACL command removes any <identifier,rights> pair for the + specified identifier from the access control list for the specified + mailbox. + + Example: C: B001 getacl INBOX + S: * ACL INBOX Fred rwipslxetad -Fred wetd $team w + S: B001 OK Getacl complete + C: B002 DeleteAcl INBOX Fred + S: B002 OK Deleteacl complete + + + + + +Melnikov Standards Track [Page 9] + +RFC 4314 IMAP ACL December 2005 + + + C: B003 GETACL INBOX + S: * ACL INBOX -Fred wetd $team w + S: B003 OK Getacl complete + +3.3. GETACL Command + + Arguments: mailbox name + + Data: untagged responses: ACL + + Result: OK - getacl completed + NO - getacl failure: can't get acl + BAD - arguments invalid + + The GETACL command returns the access control list for mailbox in an + untagged ACL response. + + Some implementations MAY permit multiple forms of an identifier to + reference the same IMAP account. Usually, such implementations will + have a canonical form that is stored internally. An ACL response + caused by a GETACL command MAY include a canonicalized form of the + identifier that might be different from the one used in the + corresponding SETACL command. + + Example: C: A002 GETACL INBOX + S: * ACL INBOX Fred rwipsldexta + S: A002 OK Getacl complete + +3.4. LISTRIGHTS Command + + Arguments: mailbox name + identifier + + Data: untagged responses: LISTRIGHTS + + Result: OK - listrights completed + NO - listrights failure: can't get rights list + BAD - arguments invalid + + The LISTRIGHTS command takes a mailbox name and an identifier and + returns information about what rights can be granted to the + identifier in the ACL for the mailbox. + + Some implementations MAY permit multiple forms of an identifier to + reference the same IMAP account. Usually, such implementations will + have a canonical form that is stored internally. A LISTRIGHTS + + + + + +Melnikov Standards Track [Page 10] + +RFC 4314 IMAP ACL December 2005 + + + response caused by a LISTRIGHTS command MUST always return the same + form of an identifier as specified by the client. This is to allow + the client to correlate the response with the command. + + Example: C: a001 LISTRIGHTS ~/Mail/saved smith + S: * LISTRIGHTS ~/Mail/saved smith la r swicdkxte + S: a001 OK Listrights completed + + Example: C: a005 listrights archive/imap anyone + S: * LISTRIGHTS archive.imap anyone "" + l r s w i p k x t e c d a 0 1 2 3 4 5 6 7 8 9 + S: a005 Listrights successful + +3.5. MYRIGHTS Command + + Arguments: mailbox name + + Data: untagged responses: MYRIGHTS + + Result: OK - myrights completed + NO - myrights failure: can't get rights + BAD - arguments invalid + + The MYRIGHTS command returns the set of rights that the user has to + mailbox in an untagged MYRIGHTS reply. + + Example: C: A003 MYRIGHTS INBOX + S: * MYRIGHTS INBOX rwiptsldaex + S: A003 OK Myrights complete + +3.6. ACL Response + + Data: mailbox name + zero or more identifier rights pairs + + The ACL response occurs as a result of a GETACL command. The first + string is the mailbox name for which this ACL applies. This is + followed by zero or more pairs of strings; each pair contains the + identifier for which the entry applies followed by the set of rights + that the identifier has. + + Section 2.1.1 details additional server requirements related to + handling of the virtual "d" and "c" rights. + + + + + + + + +Melnikov Standards Track [Page 11] + +RFC 4314 IMAP ACL December 2005 + + +3.7. LISTRIGHTS Response + + Data: mailbox name + identifier + required rights + list of optional rights + + The LISTRIGHTS response occurs as a result of a LISTRIGHTS command. + The first two strings are the mailbox name and identifier for which + this rights list applies. Following the identifier is a string + containing the (possibly empty) set of rights the identifier will + always be granted in the mailbox. + + Following this are zero or more strings each containing a set of + rights the identifier can be granted in the mailbox. Rights + mentioned in the same string are tied together. The server MUST + either grant all tied rights to the identifier in the mailbox or + grant none. Section 2.1.1 details additional server requirements + related to handling of the virtual "d" and "c" rights. + + The same right MUST NOT be listed more than once in the LISTRIGHTS + command. + +3.8. MYRIGHTS Response + + Data: mailbox name + rights + + The MYRIGHTS response occurs as a result of a MYRIGHTS command. The + first string is the mailbox name for which these rights apply. The + second string is the set of rights that the client has. + + Section 2.1.1 details additional server requirements related to + handling of the virtual "d" and "c" rights. + +4. Rights Required to Perform Different IMAP4rev1 Commands + + Before executing a command, an ACL-compliant server MUST check which + rights are required to perform it. This section groups command by + functions they perform and list the rights required. It also gives + the detailed description of any special processing required. + + For the purpose of this section the UID counterpart of a command is + considered to be the same command, e.g., both UID COPY and COPY + commands require the same set of rights. + + + + + + +Melnikov Standards Track [Page 12] + +RFC 4314 IMAP ACL December 2005 + + + The table below summarizes different rights or their combinations + that are required in order to perform different IMAP operations. As + it is not always possible to express complex right checking and + interactions, the description after the table should be used as the + primary reference. + + +-------------------+---+---+---+---+---+---+---+---+---+---+---+---+ + |Operations\Rights | l | r | s | w | i | k | x | t | e | a |Any|Non| + +-------------------+---+---+---+---+---+---+---+---+---+---+---+---+ + | commands in authenticated state | + +-------------------------------------------------------------------+ + | LIST | + | | | | | | | | | | | | + | SUBSCRIBE | * | | | | | | | | | | | * | + | UNSUBSCRIBE | | | | | | | | | | | | + | + | LSUB | * | | | | | | | | | | | * | + |CREATE (for parent)| | | | | | + | | | | | | | + | DELETE | | ? | | | | | + | ? | ? | | | | + | RENAME | | | | | | + | + | | | | | | + | SELECT/EXAMINE | | + | | | | | | | | | | | + | STATUS | | + | | | | | | | | | | | + | SETACL/DELETEACL | | | | | | | | | | + | | | + | GETACL/LISTRIGHTS | | | | | | | | | | + | | | + | MYRIGHTS | | | | | | | | | | | + | | + | APPEND | | | ? | ? | + | | | ? | | | | | + +-------------------------------------------------------------------+ + | commands in selected state | + +-------------------------------------------------------------------+ + | COPY | | | ? | ? | + | | | ? | | | | | + | EXPUNGE | | | | | | | | | + | | | | + | CLOSE | | | | | | | | | ? | | | | + | FETCH | | | ? | | | | | | | | | | + | STORE flags | | | ? | ? | | | | ? | | | | | + +-------------------+---+---+---+---+---+---+---+---+---+---+---+---+ + + Note: for all commands in the selected state, the "r" is implied, + because it is required to SELECT/EXAMINE a mailbox. Servers are not + required to check presence of the "r" right once a mailbox is + successfully selected. + + Legend: + + - The right is required + * - Only one of the rights marked with * is required + (see description below) + ? - The right is OPTIONAL (see description below) + "Any" - at least one of the "l", "r", "i", "k", "x", "a" rights is + required + "Non" - No rights required to perform the command + + + + +Melnikov Standards Track [Page 13] + +RFC 4314 IMAP ACL December 2005 + + + Listing and subscribing/unsubscribing mailboxes: + LIST - "l" right is required. However, unlike other commands + (e.g., SELECT) the server MUST NOT return a NO response if it + can't list a mailbox. + Note that if the user has "l" right to a mailbox "A/B", but not to + its parent mailbox "A", the LIST command should behave as if the + mailbox "A" doesn't exist, for example: + + C: A777 LIST "" * + S: * LIST (\NoInferiors) "/" "A/B" + S: * LIST () "/" "C" + S: * LIST (\NoInferiors) "/" "C/D" + S: A777 OK LIST completed + + + SUBSCRIBE - "l" right is required only if the server checks for + mailbox existence when performing SUBSCRIBE. + + UNSUBSCRIBE - no rights required to perform this operation. + + LSUB - "l" right is required only if the server checks for mailbox + existence when performing SUBSCRIBE. However, unlike other + commands (e.g., SELECT) the server MUST NOT return a NO response + if it can't list a subscribed mailbox. + + Mailbox management: + CREATE - "k" right on a nearest existing parent mailbox. When a + new mailbox is created, it SHOULD inherit the ACL from the parent + mailbox (if one exists) in the defined hierarchy. + + DELETE - "x" right on the mailbox. Note that some servers don't + allow to delete a non-empty mailbox. If this is the case, the + user would also need "r", "e", and "t" rights, in order to open + the mailbox and empty it. + + The DELETE command MUST delete the ACL associated with the deleted + mailbox. + + RENAME - Moving a mailbox from one parent to another requires the + "x" right on the mailbox itself and the "k" right for the new + parent. For example, if the user wants to rename the mailbox + named "A/B/C" to "D/E", the user must have the "x" right for the + mailbox "A/B/C" and the "k" right for the mailbox "D". + The RENAME command SHOULD NOT change the ACLs on the renamed + mailbox and submailboxes. + + + + + + +Melnikov Standards Track [Page 14] + +RFC 4314 IMAP ACL December 2005 + + + Copying or appending messages: + Before performing a COPY/APPEND command, the server MUST check if + the user has "i" right for the target mailbox. If the user + doesn't have "i" right, the operation fails. Otherwise for each + copied/appended message the server MUST check if the user has + "t" right - when the message has \Deleted flag set + "s" right - when the message has \Seen flag set + "w" right - for all other message flags. + Only when the user has a particular right are the corresponding + flags stored for the newly created message. The server MUST NOT + fail a COPY/APPEND if the user has no rights to set a particular + flag. + + Example: C: A003 MYRIGHTS TargetMailbox + S: * MYRIGHTS TargetMailbox rwis + S: A003 OK Myrights complete + + C: A004 FETCH 1:3 (FLAGS) + S: * 1 FETCH (FLAGS (\Draft \Deleted) + S: * 2 FETCH (FLAGS (\Answered) + S: * 3 FETCH (FLAGS ($Forwarded \Seen) + S: A004 OK Fetch Completed + + C: A005 COPY 1:3 TargetMailbox + S: A005 OK Copy completed + + C: A006 SELECT TargetMailbox + ... + S: A006 Select Completed + + Let's assume that the copied messages received message numbers + 77:79. + + C: A007 FETCH 77:79 (FLAGS) + S: * 77 FETCH (FLAGS (\Draft)) + S: * 78 FETCH (FLAGS (\Answered)) + S: * 79 FETCH (FLAGS ($Forwarded \Seen)) + S: A007 OK Fetch Completed + + \Deleted flag was lost on COPY, as the user has no "t" right in + the target mailbox. + If the MYRIGHTS command with the tag A003 would have returned: + + S: * MYRIGHTS TargetMailbox rsti + + the response from the FETCH with the tag A007 would have been: + + C: A007 FETCH 77:79 (FLAGS) + + + +Melnikov Standards Track [Page 15] + +RFC 4314 IMAP ACL December 2005 + + + S: * 77 FETCH (FLAGS (\Deleted)) + S: * 78 FETCH (FLAGS ()) + S: * 79 FETCH (FLAGS (\Seen)) + S: A007 OK Fetch Completed + + In the latter case, \Answered, $Forwarded, and \Draft flags were + lost on COPY, as the user has no "w" right in the target mailbox. + + Expunging the selected mailbox: + EXPUNGE - "e" right on the selected mailbox. + + CLOSE - "e" right on the selected mailbox. If the server is + unable to expunge the mailbox because the user doesn't have the + "e" right, the server MUST ignore the expunge request, close the + mailbox, and return the tagged OK response. + + Fetch information about a mailbox and its messages: + SELECT/EXAMINE/STATUS - "r" right on the mailbox. + + FETCH - A FETCH request that implies setting \Seen flag MUST NOT + set it, if the current user doesn't have "s" right. + + Changing flags: + STORE - the server MUST check if the user has + "t" right - when the user modifies \Deleted flag + "s" right - when the user modifies \Seen flag + "w" right - for all other message flags. + STORE operation SHOULD NOT fail if the user has rights to modify + at least one flag specified in the STORE, as the tagged NO + response to a STORE command is not handled very well by deployed + clients. + + Changing ACLs: + SETACL/DELETEACL - "a" right on the mailbox. + + Reading ACLs: + GETACL - "a" right on the mailbox. + + MYRIGHTS - any of the following rights is required to perform the + operation: "l", "r", "i", "k", "x", "a". + + LISTRIGHTS - "a" right on the mailbox. + + + + + + + + + +Melnikov Standards Track [Page 16] + +RFC 4314 IMAP ACL December 2005 + + +5. Other Considerations + +5.1. Additional Requirements and Implementation Notes + +5.1.1. Servers + + This document defines an additional capability that is used to + announce the list of extra rights (excluding the ones defined in RFC + 2086) supported by the server. The set of rights MUST include "t", + "e", "x", and "k". Note that the extra rights can appear in any + order. + + Example: C: 1 capability + S: * CAPABILITY IMAP4REV1 STARTTLS LITERAL+ + ACL RIGHTS=texk + S: 1 OK completed + + Any server implementing an ACL extension MUST accurately reflect the + current user's rights in FLAGS and PERMANENTFLAGS responses. + + Example: C: A142 SELECT INBOX + S: * 172 EXISTS + S: * 1 RECENT + S: * OK [UNSEEN 12] Message 12 is first unseen + S: * OK [UIDVALIDITY 3857529045] UIDs valid + S: * OK [UIDNEXT 4392] Predicted next UID + S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) + S: * OK [PERMANENTFLAGS (\Seen \Answered \Flagged \*)] L + S: A142 OK [READ-WRITE] SELECT completed + C: A143 MYRIGHTS INBOX + S: * MYRIGHTS INBOX lrwis + S: A143 OK completed + + Note that in order to get better performance the client MAY pipeline + SELECT and MYRIGHTS commands: + + C: A142 SELECT INBOX + C: A143 MYRIGHTS INBOX + S: * 172 EXISTS + S: * 1 RECENT + S: * OK [UNSEEN 12] Message 12 is first unseen + S: * OK [UIDVALIDITY 3857529045] UIDs valid + S: * OK [UIDNEXT 4392] Predicted next UID + S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) + S: * OK [PERMANENTFLAGS (\Seen \Answered \Flagged \*)] L + S: A142 OK [READ-WRITE] SELECT completed + S: * MYRIGHTS INBOX lrwis + S: A143 OK completed + + + +Melnikov Standards Track [Page 17] + +RFC 4314 IMAP ACL December 2005 + + + Servers MAY cache the rights a user has on a mailbox when the mailbox + is selected, so that if a client's rights on a mailbox are changed + with SETACL or DELETEACL, commands specific to the selected state + (e.g., STORE, EXPUNGE) might not reflect the changed rights until the + mailbox is re-selected. If the server checks the rights on each + command, then it SHOULD send FLAGS and PERMANENTFLAGS responses if + they have changed. If such server detects that the user no longer + has read access to the mailbox, it MAY send an untagged BYE response + and close connection. It MAY also refuse to execute all commands + specific to the selected state until the mailbox is closed; however, + server implementors should note that most clients don't handle NO + responses very well. + + An ACL server MAY modify one or more ACLs for one or more identifiers + as a side effect of modifying the ACL specified in a + SETACL/DELETEACL. If the server does that, it MUST send untagged ACL + response(s) to notify the client about the changes made. + + An ACL server implementation MUST treat received ACL modification + commands as a possible ambiguity with respect to subsequent commands + affected by the ACL, as described in Section 5.5 of [IMAP4]. Hence a + pipeline SETACL + MYRIGHTS is an ambiguity with respect to the + server, meaning that the server must execute the SETACL command to + completion before the MYRIGHTS. However, clients are permitted to + send such a pipeline. + +5.1.2. Clients + + The following requirement is put on clients in order to allow for + future extensibility. A client implementation that allows a user to + read and update ACLs MUST preserve unrecognized rights that it + doesn't allow the user to change. That is, if the client + + 1) can read ACLs + and + 2) can update ACLs + but + 3) doesn't allow the user to change the rights the client doesn't + recognize, then it MUST preserve unrecognized rights. + + Otherwise the client could risk unintentionally removing permissions + it doesn't understand. + + + + + + + + + +Melnikov Standards Track [Page 18] + +RFC 4314 IMAP ACL December 2005 + + +5.2. Mapping of ACL Rights to READ-WRITE and READ-ONLY Response Codes + + A particular ACL server implementation MAY allow "shared multiuser + access" to some mailboxes. "Shared multiuser access" to a mailbox + means that multiple different users are able to access the same + mailbox, if they have proper access rights. "Shared multiuser + access" to the mailbox doesn't mean that the ACL for the mailbox is + currently set to allow access by multiple users. Let's denote a + "shared multiuser write access" as a "shared multiuser access" when a + user can be granted flag modification rights (any of "w", "s", or + "t"). + + Section 4 describes which rights are required for modifying different + flags. + + If the ACL server implements some flags as shared for a mailbox + (i.e., the ACL for the mailbox MAY be set up so that changes to those + flags are visible to another user), let's call the set of rights + associated with these flags (as described in Section 4) for that + mailbox collectively as "shared flag rights". Note that the "shared + flag rights" set MAY be different for different mailboxes. + + If the server doesn't support "shared multiuser write access" to a + mailbox or doesn't implement shared flags on the mailbox, "shared + flag rights" for the mailbox is defined to be the empty set. + + Example 1: Mailbox "banan" allows "shared multiuser write access" and + implements flags \Deleted, \Answered, and $MDNSent as + shared flags. "Shared flag rights" for the mailbox "banan" + is a set containing flags "t" (because system flag + \Deleted requires "t" right) and "w" (because both + \Answered and $MDNSent require "w" right). + + Example 2: Mailbox "apple" allows "shared multiuser write access" and + implements \Seen system flag as shared flag. "Shared flag + rights" for the mailbox "apple" contains "s" right + because system flag \Seen requires "s" right. + + Example 3: Mailbox "pear" allows "shared multiuser write access" and + implements flags \Seen, \Draft as shared flags. "Shared + flag rights" for the mailbox "apple" is a set containing + flags "s" (because system flag \Seen requires "s" right) + and "w" (because system flag \Draft requires "w" right). + + The server MUST include a READ-ONLY response code in the tagged OK + response to a SELECT command if none of the following rights is + granted to the current user: + + + + +Melnikov Standards Track [Page 19] + +RFC 4314 IMAP ACL December 2005 + + + "i", "e", and "shared flag rights"(***). + + The server SHOULD include a READ-WRITE response code in the tagged OK + response if at least one of the "i", "e", or "shared flag + rights"(***) is granted to the current user. + + (***) Note that a future extension to this document can extend the + list of rights that causes the server to return the READ-WRITE + response code. + + Example 1 (continued): The user that has "lrs" rights for the mailbox + "banan". The server returns READ-ONLY + response code on SELECT, as none of "iewt" + rights is granted to the user. + + Example 2 (continued): The user that has "rit" rights for the mailbox + "apple". The server returns READ-WRITE + response code on SELECT, as the user has "i" + right. + + Example 3 (continued): The user that has "rset" rights for the + mailbox "pear". The server returns READ-WRITE + response code on SELECT, as the user has "e" + and "s" rights. + +6. Security Considerations + + An implementation MUST make sure the ACL commands themselves do not + give information about mailboxes with appropriately restricted ACLs. + For example, when a user agent executes a GETACL command on a mailbox + that the user has no permission to LIST, the server would respond to + that request with the same error that would be used if the mailbox + did not exist, thus revealing no existence information, much less the + mailbox's ACL. + + IMAP clients implementing ACL that are able to modify ACLs SHOULD + warn a user that wants to give full access (or even just the "a" + right) to the special identifier "anyone". + + This document relies on [SASLprep] to describe steps required to + perform identifier canonicalization (preparation). The preparation + algorithm in SASLprep was specifically designed such that its output + is canonical, and it is well-formed. However, due to an anomaly + [PR29] in the specification of Unicode normalization, canonical + equivalence is not guaranteed for a select few character sequences. + Identifiers prepared with SASLprep can be stored and returned by an + ACL server. The anomaly affects ACL manipulation and evaluation of + identifiers containing the selected character sequences. These + + + +Melnikov Standards Track [Page 20] + +RFC 4314 IMAP ACL December 2005 + + + sequences, however, do not appear in well-formed text. In order to + address this problem, an ACL server MAY reject identifiers containing + sequences described in [PR29] by sending the tagged BAD response. + This is in addition to the requirement to reject identifiers that + fail SASLprep preparation as described in Section 3. + + Other security considerations described in [IMAP4] are relevant to + this document. In particular, ACL information is sent in the clear + over the network unless confidentiality protection is negotiated. + + This can be accomplished either by the use of STARTTLS, negotiated + privacy protection in the AUTHENTICATE command, or some other + protection mechanism. + +7. Formal Syntax + + Formal syntax is defined using ABNF [ABNF], extending the ABNF rules + in Section 9 of [IMAP4]. Elements not defined here can be found in + [ABNF] and [IMAP4]. + + Except as noted otherwise, all alphabetic characters are case + insensitive. The use of uppercase or lowercase characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. + + LOWER-ALPHA = %x61-7A ;; a-z + + acl-data = "ACL" SP mailbox *(SP identifier SP + rights) + + capability =/ rights-capa + ;;capability is defined in [IMAP4] + + command-auth =/ setacl / deleteacl / getacl / + listrights / myrights + ;;command-auth is defined in [IMAP4] + + deleteacl = "DELETEACL" SP mailbox SP identifier + + getacl = "GETACL" SP mailbox + + identifier = astring + + listrights = "LISTRIGHTS" SP mailbox SP identifier + + listrights-data = "LISTRIGHTS" SP mailbox SP identifier + SP rights *(SP rights) + + + + +Melnikov Standards Track [Page 21] + +RFC 4314 IMAP ACL December 2005 + + + mailbox-data =/ acl-data / listrights-data / myrights-data + ;;mailbox-data is defined in [IMAP4] + + mod-rights = astring + ;; +rights to add, -rights to remove + ;; rights to replace + + myrights = "MYRIGHTS" SP mailbox + + myrights-data = "MYRIGHTS" SP mailbox SP rights + + new-rights = 1*LOWER-ALPHA + ;; MUST include "t", "e", "x", and "k". + ;; MUST NOT include standard rights listed + ;; in section 2.2 + + rights = astring + ;; only lowercase ASCII letters and digits + ;; are allowed. + + rights-capa = "RIGHTS=" new-rights + ;; RIGHTS=... capability + + setacl = "SETACL" SP mailbox SP identifier + SP mod-rights + +8. IANA Considerations + + IMAP4 capabilities are registered by publishing a standards-track or + IESG-approved experimental RFC. The registry is currently located + at: + + http://www.iana.org/assignments/imap4-capabilities + + This document defines the RIGHTS= IMAP capability. IANA has added + this capability to the registry. + +9. Internationalization Considerations + + Section 3 states requirements on servers regarding + internationalization of identifiers. + + + + + + + + + + +Melnikov Standards Track [Page 22] + +RFC 4314 IMAP ACL December 2005 + + +Appendix A. Changes since RFC 2086 + + 1. Changed the charset of "identifier" from US-ASCII to UTF-8. + 2. Specified that mailbox deletion is controlled by the "x" right + and EXPUNGE is controlled by the "e" right. + 3. Added the "t" right that controls STORE \Deleted. Redefined the + "d" right to be a macro for "e", "t", and possibly "x". + 4. Added the "k" right that controls CREATE. Redefined the "c" + right to be a macro for "k" and possibly "x". + 5. Specified that the "a" right also controls DELETEACL. + 6. Specified that the "r" right also controls STATUS. + 7. Removed the requirement to check the "r" right for CHECK, SEARCH + and FETCH, as this is required for SELECT/EXAMINE to be + successful. + 8. LISTRIGHTS requires the "a" right on the mailbox (same as + SETACL). + 9. Deleted "PARTIAL", this is a deprecated feature of RFC 1730. + 10. Specified that the "w" right controls setting flags other than + \Seen and \Deleted on APPEND. Also specified that the "s" right + controls the \Seen flag and that the "t" right controls the + \Deleted flag. + 11. Specified that SUBSCRIBE is NOT allowed with the "r" right. + 12. Specified that the "l" right controls SUBSCRIBE. + 13. GETACL is NOT allowed with the "r" right, even though there are + several implementations that allows that. If a user only has + "r" right, GETACL can disclose information about identifiers + existing on the mail system. + 14. Clarified that RENAME requires the "k" right for the new parent + and the "x" right for the old name. + 15. Added new section that describes which rights are required + and/or checked when performing various IMAP commands. + 16. Added mail client security considerations when dealing with + special identifier "anyone". + 17. Clarified that negative rights are not the same as DELETEACL. + 18. Added "Compatibility with RFC 2086" section. + 19. Added section about mapping of ACL rights to READ-WRITE and + READ-ONLY response codes. + 20. Changed BNF to ABNF. + 21. Added "Implementation Notes" section. + 22. Updated "References" section. + 23. Added more examples. + 24. Clarified when the virtual "c" and "d" rights are returned in + ACL, MYRIGHTS, and LISTRIGHTS responses. + + + + + + + + +Melnikov Standards Track [Page 23] + +RFC 4314 IMAP ACL December 2005 + + +Appendix B. Compatibility with RFC 2086 + + This non-normative section gives guidelines as to how an existing RFC + 2086 server implementation may be updated to comply with this + document. + + This document splits the "d" right into several new different rights: + "t", "e", and possibly "x" (see Section 2.1.1 for more details). The + "d" right remains for backward-compatibility, but it is a virtual + right. There are two approaches for RFC 2086 server implementors to + handle the "d" right and the new rights that have replaced it: + + a. Tie "t", "e" (and possibly "x) together - almost no changes. + b. Implement separate "x", "t" and "e". Return the "d" right in a + MYRIGHTS response or an ACL response containing ACL information + when any of the "t", "e" (and "x") is granted. + + In a similar manner this document splits the "c" right into several + new different rights: "k" and possibly "x" (see Section 2.1.1 for + more details). The "c" right remains for backwards-compatibility but + it is a virtual right. Again, RFC 2086 server implementors can + choose to tie rights or to implement separate rights, as described + above. + + Also check Sections 5.1.1 and 5.1.2, as well as Appendix A, to see + other changes required. Server implementors should check which + rights are required to invoke different IMAP4 commands as described + in Section 4. + +Appendix C. Known Deficiencies + + This specification has some known deficiencies including: + + 1. This is inadequate to provide complete read-write access to + mailboxes protected by Unix-style rights bits because there is no + equivalent to "chown" and "chgrp" commands nor is there a good + way to discover such limitations are present. + 2. Because this extension leaves the specific semantics of how + rights are combined by the server as implementation defined, the + ability to build a user-friendly interface is limited. + 3. Users, groups, and special identifiers (e.g., anyone) exist in + the same namespace. + + The work-in-progress "ACL2" extension is intended to redesign this + extension to address these deficiencies without the constraint of + backward-compatibility and may eventually supercede this facility. + + + + + +Melnikov Standards Track [Page 24] + +RFC 4314 IMAP ACL December 2005 + + + However, RFC 2086 is deployed in multiple implementations so this + intermediate step, which fixes the straightforward deficiencies in a + backward-compatible fashion, is considered worthwhile. + +Appendix D. Acknowledgements + + This document is a revision of RFC 2086 written by John G. Myers. + + Editor appreciates comments received from Mark Crispin, Chris Newman, + Cyrus Daboo, John G. Myers, Dave Cridland, Ken Murchison, Steve Hole, + Vladimir Butenko, Larry Greenfield, Robert Siemborski, Harrie + Hazewinkel, Philip Guenther, Brian Candler, Curtis King, Lyndon + Nerenberg, Lisa Dusseault, Arnt Gulbrandsen, and other participants + of the IMAPEXT working group. + +Normative References + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 4234, October 2005. + + [IMAP4] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. + + [Stringprep] Hoffman, P. and M. Blanchet, "Preparation of + Internationalized Strings ("stringprep")", RFC 3454, + December 2002. + + [SASLprep] Zeilenga, K., "SASLprep: Stringprep Profile for User + Names and Passwords", RFC 4013, February 2005. + +Informative References + + [RFC2086] Myers, J., "IMAP4 ACL extension", RFC 2086, + January 1997. + + [PR29] "Public Review Issue #29: Normalization Issue", + February 2004, + <http://www.unicode.org/review/pr-29.html>. + + + + + + + +Melnikov Standards Track [Page 25] + +RFC 4314 IMAP ACL December 2005 + + +Author's Address + + Alexey Melnikov + Isode Ltd. + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + GB + + EMail: alexey.melnikov@isode.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Melnikov Standards Track [Page 26] + +RFC 4314 IMAP ACL December 2005 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2005). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at ietf- + ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + +Melnikov Standards Track [Page 27] + diff --git a/imap/docs/rfc/rfc4315.txt b/imap/docs/rfc/rfc4315.txt new file mode 100644 index 00000000..c026f422 --- /dev/null +++ b/imap/docs/rfc/rfc4315.txt @@ -0,0 +1,451 @@ + + + + + + +Network Working Group M. Crispin +Request for Comments: 4315 December 2005 +Obsoletes: 2359 +Category: Standards Track + + + Internet Message Access Protocol (IMAP) - UIDPLUS extension + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2005). + +Abstract + + The UIDPLUS extension of the Internet Message Access Protocol (IMAP) + provides a set of features intended to reduce the amount of time and + resources used by some client operations. The features in UIDPLUS + are primarily intended for disconnected-use clients. + +1. Introduction and Overview + + The UIDPLUS extension is present in any IMAP server implementation + that returns "UIDPLUS" as one of the supported capabilities to the + CAPABILITY command. + + The UIDPLUS extension defines an additional command. In addition, + this document recommends new status response codes in IMAP that + SHOULD be returned by all server implementations, regardless of + whether or not the UIDPLUS extension is implemented. + + The added facilities of the features in UIDPLUS are optimizations; + clients can provide equivalent functionality, albeit less + efficiently, by using facilities in the base protocol. + +1.1. Conventions Used in This Document + + In examples, "C:" and "S:" indicate lines sent by the client and + server, respectively. + + + + + +Crispin Standards Track [Page 1] + +RFC 4315 IMAP - UIDPLUS Extension December 2005 + + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "MAY", and "OPTIONAL" in this document are to + be interpreted as described in [KEYWORDS]. + + A "UID set" is similar to the [IMAP] sequence set; however, the "*" + value for a sequence number is not permitted. + +2. Additional Commands + + The following command definition is an extension to [IMAP] section + 6.4. + +2.1. UID EXPUNGE Command + + Arguments: sequence set + + Data: untagged responses: EXPUNGE + + Result: OK - expunge completed + NO - expunge failure (e.g., permission denied) + BAD - command unknown or arguments invalid + + The UID EXPUNGE command permanently removes all messages that both + have the \Deleted flag set and have a UID that is included in the + specified sequence set from the currently selected mailbox. If a + message either does not have the \Deleted flag set or has a UID + that is not included in the specified sequence set, it is not + affected. + + This command is particularly useful for disconnected use clients. + By using UID EXPUNGE instead of EXPUNGE when resynchronizing with + the server, the client can ensure that it does not inadvertantly + remove any messages that have been marked as \Deleted by other + clients between the time that the client was last connected and + the time the client resynchronizes. + + If the server does not support the UIDPLUS capability, the client + should fall back to using the STORE command to temporarily remove + the \Deleted flag from messages it does not want to remove, then + issuing the EXPUNGE command. Finally, the client should use the + STORE command to restore the \Deleted flag on the messages in + which it was temporarily removed. + + Alternatively, the client may fall back to using just the EXPUNGE + command, risking the unintended removal of some messages. + + + + + + +Crispin Standards Track [Page 2] + +RFC 4315 IMAP - UIDPLUS Extension December 2005 + + + Example: C: A003 UID EXPUNGE 3000:3002 + S: * 3 EXPUNGE + S: * 3 EXPUNGE + S: * 3 EXPUNGE + S: A003 OK UID EXPUNGE completed + +3. Additional Response Codes + + The following response codes are extensions to the response codes + defined in [IMAP] section 7.1. With limited exceptions, discussed + below, server implementations that advertise the UIDPLUS extension + SHOULD return these response codes. + + In the case of a mailbox that has permissions set so that the client + can COPY or APPEND to the mailbox, but not SELECT or EXAMINE it, the + server SHOULD NOT send an APPENDUID or COPYUID response code as it + would disclose information about the mailbox. + + In the case of a mailbox that has UIDNOTSTICKY status (as defined + below), the server MAY omit the APPENDUID or COPYUID response code as + it is not meaningful. + + If the server does not return the APPENDUID or COPYUID response + codes, the client can discover this information by selecting the + destination mailbox. The location of messages placed in the + destination mailbox by COPY or APPEND can be determined by using + FETCH and/or SEARCH commands (e.g., for Message-ID or some unique + marker placed in the message in an APPEND). + + APPENDUID + + Followed by the UIDVALIDITY of the destination mailbox and the UID + assigned to the appended message in the destination mailbox, + indicates that the message has been appended to the destination + mailbox with that UID. + + If the server also supports the [MULTIAPPEND] extension, and if + multiple messages were appended in the APPEND command, then the + second value is a UID set containing the UIDs assigned to the + appended messages, in the order they were transmitted in the + APPEND command. This UID set may not contain extraneous UIDs or + the symbol "*". + + Note: the UID set form of the APPENDUID response code MUST NOT + be used if only a single message was appended. In particular, + a server MUST NOT send a range such as 123:123. This is + because a client that does not support [MULTIAPPEND] expects + only a single UID and not a UID set. + + + +Crispin Standards Track [Page 3] + +RFC 4315 IMAP - UIDPLUS Extension December 2005 + + + UIDs are assigned in strictly ascending order in the mailbox + (refer to [IMAP], section 2.3.1.1) and UID ranges are as in + [IMAP]; in particular, note that a range of 12:10 is exactly + equivalent to 10:12 and refers to the sequence 10,11,12. + + This response code is returned in a tagged OK response to the + APPEND command. + + COPYUID + + Followed by the UIDVALIDITY of the destination mailbox, a UID set + containing the UIDs of the message(s) in the source mailbox that + were copied to the destination mailbox and containing the UIDs + assigned to the copied message(s) in the destination mailbox, + indicates that the message(s) have been copied to the destination + mailbox with the stated UID(s). + + The source UID set is in the order the message(s) were copied; the + destination UID set corresponds to the source UID set and is in + the same order. Neither of the UID sets may contain extraneous + UIDs or the symbol "*". + + UIDs are assigned in strictly ascending order in the mailbox + (refer to [IMAP], section 2.3.1.1) and UID ranges are as in + [IMAP]; in particular, note that a range of 12:10 is exactly + equivalent to 10:12 and refers to the sequence 10,11,12. + + This response code is returned in a tagged OK response to the COPY + command. + + UIDNOTSTICKY + + The selected mailbox is supported by a mail store that does not + support persistent UIDs; that is, UIDVALIDITY will be different + each time the mailbox is selected. Consequently, APPEND or COPY + to this mailbox will not return an APPENDUID or COPYUID response + code. + + This response code is returned in an untagged NO response to the + SELECT command. + + Note: servers SHOULD NOT have any UIDNOTSTICKY mail stores. + This facility exists to support legacy mail stores in which it + is technically infeasible to support persistent UIDs. This + should be avoided when designing new mail stores. + + + + + + +Crispin Standards Track [Page 4] + +RFC 4315 IMAP - UIDPLUS Extension December 2005 + + + Example: C: A003 APPEND saved-messages (\Seen) {297} + C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) + C: From: Fred Foobar <foobar@example.com> + C: Subject: afternoon meeting + C: To: mooch@example.com + C: Message-Id: <B27397-0100000@example.com> + C: MIME-Version: 1.0 + C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII + C: + C: Hello Joe, do you think we can meet at 3:30 tomorrow? + C: + S: A003 OK [APPENDUID 38505 3955] APPEND completed + C: A004 COPY 2:4 meeting + S: A004 OK [COPYUID 38505 304,319:320 3956:3958] Done + C: A005 UID COPY 305:310 meeting + S: A005 OK No matching messages, so nothing copied + C: A006 COPY 2 funny + S: A006 OK Done + C: A007 SELECT funny + S: * 1 EXISTS + S: * 1 RECENT + S: * OK [UNSEEN 1] Message 1 is first unseen + S: * OK [UIDVALIDITY 3857529045] Validity session-only + S: * OK [UIDNEXT 2] Predicted next UID + S: * NO [UIDNOTSTICKY] Non-persistent UIDs + S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) + S: * OK [PERMANENTFLAGS (\Deleted \Seen)] Limited + S: A007 OK [READ-WRITE] SELECT completed + + In this example, A003 and A004 demonstrate successful appending and + copying to a mailbox that returns the UIDs assigned to the messages. + A005 is an example in which no messages were copied; this is because + in A003, we see that message 2 had UID 304, and message 3 had UID + 319; therefore, UIDs 305 through 310 do not exist (refer to section + 2.3.1.1 of [IMAP] for further explanation). A006 is an example of a + message being copied that did not return a COPYUID; and, as expected, + A007 shows that the mail store containing that mailbox does not + support persistent UIDs. + +4. Formal Syntax + + Formal syntax is defined using ABNF [ABNF], which extends the ABNF + rules defined in [IMAP]. The IMAP4 ABNF should be imported before + attempting to validate these rules. + + append-uid = uniqueid + + capability =/ "UIDPLUS" + + + +Crispin Standards Track [Page 5] + +RFC 4315 IMAP - UIDPLUS Extension December 2005 + + + command-select =/ uid-expunge + + resp-code-apnd = "APPENDUID" SP nz-number SP append-uid + + resp-code-copy = "COPYUID" SP nz-number SP uid-set SP uid-set + + resp-text-code =/ resp-code-apnd / resp-code-copy / "UIDNOTSTICKY" + ; incorporated before the expansion rule of + ; atom [SP 1*<any TEXT-CHAR except "]">] + ; that appears in [IMAP] + + uid-expunge = "UID" SP "EXPUNGE" SP sequence-set + + uid-set = (uniqueid / uid-range) *("," uid-set) + + uid-range = (uniqueid ":" uniqueid) + ; two uniqueid values and all values + ; between these two regards of order. + ; Example: 2:4 and 4:2 are equivalent. + + Servers that support [MULTIAPPEND] will have the following extension + to the above rules: + + append-uid =/ uid-set + ; only permitted if client uses [MULTIAPPEND] + ; to append multiple messages. + +5. Security Considerations + + The COPYUID and APPENDUID response codes return information about the + mailbox, which may be considered sensitive if the mailbox has + permissions set that permit the client to COPY or APPEND to the + mailbox, but not SELECT or EXAMINE it. + + Consequently, these response codes SHOULD NOT be issued if the client + does not have access to SELECT or EXAMINE the mailbox. + +6. IANA Considerations + + This document constitutes registration of the UIDPLUS capability in + the imap4-capabilities registry, replacing [RFC2359]. + +7. Normative References + + [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 4234, October 2005. + + + + + +Crispin Standards Track [Page 6] + +RFC 4315 IMAP - UIDPLUS Extension December 2005 + + + [IMAP] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - + VERSION 4rev1", RFC 3501, March 2003. + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [MULTIAPPEND] Crispin, M., "Internet Message Access Protocol (IMAP) - + MULTIAPPEND Extension", RFC 3502, March 2003. + +8. Informative References + + [RFC2359] Myers, J., "IMAP4 UIDPLUS extension", RFC 2359, June + 1998. + +9. Changes from RFC 2359 + + This document obsoletes [RFC2359]. However, it is based upon that + document, and takes substantial text from it (albeit with numerous + clarifications in wording). + + [RFC2359] implied that a server must always return COPYUID/APPENDUID + data; thus suggesting that in such cases the server should return + arbitrary data if the destination mailbox did not support persistent + UIDs. This document adds the UIDNOTSTICKY response code to indicate + that a mailbox does not support persistent UIDs, and stipulates that + a UIDPLUS server does not return COPYUID/APPENDUID data when the COPY + (or APPEND) destination mailbox has UIDNOTSTICKY status. + +Author's Address + + Mark R. Crispin + Networks and Distributed Computing + University of Washington + 4545 15th Avenue NE + Seattle, WA 98105-4527 + + Phone: (206) 543-5762 + EMail: MRC@CAC.Washington.EDU + + + + + + + + + + + + + +Crispin Standards Track [Page 7] + +RFC 4315 IMAP - UIDPLUS Extension December 2005 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2005). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at ietf- + ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + +Crispin Standards Track [Page 8] + diff --git a/imap/docs/rfc/rfc4422.txt b/imap/docs/rfc/rfc4422.txt new file mode 100644 index 00000000..049fa8c5 --- /dev/null +++ b/imap/docs/rfc/rfc4422.txt @@ -0,0 +1,1851 @@ + + + + + + +Network Working Group A. Melnikov, Ed. +Request for Comments: 4422 Isode Limited +Obsoletes: 2222 K. Zeilenga, Ed. +Category: Standards Track OpenLDAP Foundation + June 2006 + + + Simple Authentication and Security Layer (SASL) + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2006). + +Abstract + + The Simple Authentication and Security Layer (SASL) is a framework + for providing authentication and data security services in + connection-oriented protocols via replaceable mechanisms. It + provides a structured interface between protocols and mechanisms. + The resulting framework allows new protocols to reuse existing + mechanisms and allows old protocols to make use of new mechanisms. + The framework also provides a protocol for securing subsequent + protocol exchanges within a data security layer. + + This document describes how a SASL mechanism is structured, describes + how protocols include support for SASL, and defines the protocol for + carrying a data security layer over a connection. In addition, this + document defines one SASL mechanism, the EXTERNAL mechanism. + + This document obsoletes RFC 2222. + + + + + + + + + + + + + +Melnikov & Zeilenga Standards Track [Page 1] + +RFC 4422 SASL June 2006 + + +Table of Contents + + 1. Introduction ....................................................3 + 1.1. Document Audiences .........................................4 + 1.2. Relationship to Other Documents ............................4 + 1.3. Conventions ................................................5 + 2. Identity Concepts ...............................................5 + 3. The Authentication Exchange .....................................6 + 3.1. Mechanism Naming ...........................................8 + 3.2. Mechanism Negotiation ......................................9 + 3.3. Request Authentication Exchange ............................9 + 3.4. Challenges and Responses ...................................9 + 3.4.1. Authorization Identity String ......................10 + 3.5. Aborting Authentication Exchanges .........................10 + 3.6. Authentication Outcome ....................................11 + 3.7. Security Layers ...........................................12 + 3.8. Multiple Authentications ..................................12 + 4. Protocol Requirements ..........................................13 + 5. Mechanism Requirements .........................................16 + 6. Security Considerations ........................................18 + 6.1. Active Attacks ............................................19 + 6.1.1. Hijack Attacks .....................................19 + 6.1.2. Downgrade Attacks ..................................19 + 6.1.3. Replay Attacks .....................................20 + 6.1.4. Truncation Attacks .................................20 + 6.1.5. Other Active Attacks ...............................20 + 6.2. Passive Attacks ...........................................20 + 6.3. Re-keying .................................................21 + 6.4. Other Considerations ......................................21 + 7. IANA Considerations ............................................22 + 7.1. SASL Mechanism Registry ...................................22 + 7.2. Registration Changes ......................................26 + 8. References .....................................................26 + 8.1. Normative References ......................................26 + 8.2. Informative References ....................................27 + 9. Acknowledgements ...............................................28 + Appendix A. The SASL EXTERNAL Mechanism ..........................29 + A.1. EXTERNAL Technical Specification ..........................29 + A.2. SASL EXTERNAL Examples ....................................30 + A.3. Security Considerations ...................................31 + Appendix B. Changes since RFC 2222 ...............................31 + + + + + + + + + + +Melnikov & Zeilenga Standards Track [Page 2] + +RFC 4422 SASL June 2006 + + +1. Introduction + + The Simple Authentication and Security Layer (SASL) is a framework + for providing authentication and data security services in + connection-oriented protocols via replaceable mechanisms. SASL + provides a structured interface between protocols and mechanisms. + SASL also provides a protocol for securing subsequent protocol + exchanges within a data security layer. The data security layer can + provide data integrity, data confidentiality, and other services. + + SASL's design is intended to allow new protocols to reuse existing + mechanisms without requiring redesign of the mechanisms and allows + existing protocols to make use of new mechanisms without redesign of + protocols. + + SASL is conceptually a framework that provides an abstraction layer + between protocols and mechanisms as illustrated in the following + diagram. + + SMTP LDAP XMPP Other protocols ... + \ | | / + \ | | / + SASL abstraction layer + / | | \ + / | | \ + EXTERNAL GSSAPI PLAIN Other mechanisms ... + + It is through the interfaces of this abstraction layer that the + framework allows any protocol to utilize any mechanism. While this + layer does generally hide the particulars of protocols from + mechanisms and the particulars of mechanisms from protocols, this + layer does not generally hide the particulars of mechanisms from + protocol implementations. For example, different mechanisms require + different information to operate, some of them use password-based + authentication, some of then require realm information, others make + use of Kerberos tickets, certificates, etc. Also, in order to + perform authorization, server implementations generally have to + implement identity mapping between authentication identities, whose + form is mechanism specific, and authorization identities, whose form + is application protocol specific. Section 2 discusses identity + concepts. + + It is possible to design and implement this framework in ways that do + abstract away particulars of similar mechanisms. Such a framework + implementation, as well as mechanisms implementations, could be + designed not only to be shared by multiple implementations of a + particular protocol but to be shared by implementations of multiple + protocols. + + + +Melnikov & Zeilenga Standards Track [Page 3] + +RFC 4422 SASL June 2006 + + + The framework incorporates interfaces with both protocols and + mechanisms in which authentication exchanges are carried out. + Section 3 discusses SASL authentication exchanges. + + To use SASL, each protocol (amongst other items) provides a method + for identifying which mechanism is to be used, a method for exchange + of mechanism-specific server-challenges and client-responses, and a + method for communicating the outcome of the authentication exchange. + Section 4 discusses SASL protocol requirements. + + Each SASL mechanism defines (amongst other items) a series of + server-challenges and client-responses that provide authentication + services and negotiate data security services. Section 5 discusses + SASL mechanism requirements. + + Section 6 discusses security considerations. Section 7 discusses + IANA considerations. Appendix A defines the SASL EXTERNAL mechanism. + +1.1. Document Audiences + + This document is written to serve several different audiences: + + - protocol designers using this specification to support + authentication in their protocol, + + - mechanism designers that define new SASL mechanisms, and + + - implementors of clients or servers for those protocols that + support SASL. + + While the document organization is intended to allow readers to focus + on details relevant to their engineering, readers are encouraged to + read and understand all aspects of this document. + +1.2. Relationship to Other Documents + + This document obsoletes RFC 2222. It replaces all portions of RFC + 2222 excepting sections 7.1 (the KERBEROS_IV mechanism), 7.2 (the + GSSAPI mechanism), 7.3 (the SKEY mechanism). The KERBEROS_IV and + SKEY mechanisms are now viewed as obsolete and their specifications + provided in RFC 2222 are Historic. The GSSAPI mechanism is now + separately specified [SASL-GSSAPI]. + + Appendix B provides a summary of changes since RFC 2222. + + + + + + + +Melnikov & Zeilenga Standards Track [Page 4] + +RFC 4422 SASL June 2006 + + +1.3. Conventions + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in BCP 14 [RFC2119]. + + Character names in this document use the notation for code points and + names from the Unicode Standard [Unicode]. For example, the letter + "a" may be represented as either <U+0061> or <LATIN SMALL LETTER A>. + + Note: a glossary of terms used in Unicode can be found in [Glossary]. + Information on the Unicode character encoding model can be found in + [CharModel]. + + In examples, "C:" and "S:" indicate lines of data to be sent by the + client and server, respectively. Lines have been wrapped for + improved readability. + +2. Identity Concepts + + In practice, authentication and authorization may involve multiple + identities, possibly in different forms (simple username, Kerberos + principal, X.500 Distinguished Name, etc.), possibly with different + representations (e.g., ABNF-described UTF-8 encoded Unicode character + string, BER-encoded Distinguished Name). While technical + specifications often prescribe both the identity form and + representation used on the network, different identity forms and/or + representations may be (and often are) used within implementations. + How identities of different forms relate to each other is, generally, + a local matter. In addition, the forms and representations used + within an implementation are a local matter. + + However, conceptually, the SASL framework involves two identities: + + 1) an identity associated with the authentication credentials + (termed the authentication identity), and + + 2) an identity to act as (termed the authorization identity). + + SASL mechanism specifications describe the credential form(s) (e.g., + X.509 certificates, Kerberos tickets, simple username/password) used + to authenticate the client, including (where appropriate) the syntax + and semantics of authentication identities carried in the + credentials. SASL protocol specifications describe the identity + form(s) used in authorization and, in particular, prescribe the + syntax and semantics of the authorization identity character string + to be transferred by mechanisms. + + + + +Melnikov & Zeilenga Standards Track [Page 5] + +RFC 4422 SASL June 2006 + + + The client provides its credentials (which include or imply an + authentication identity) and, optionally, a character string + representing the requested authorization identity as part of the SASL + exchange. When this character string is omitted or empty, the client + is requesting to act as the identity associated with the credentials + (e.g., the user is requesting to act as the authentication identity). + + The server is responsible for verifying the client's credentials and + verifying that the identity it associates with the client's + credentials (e.g., the authentication identity) is allowed to act as + the authorization identity. A SASL exchange fails if either (or + both) of these verifications fails. (The SASL exchange may fail for + other reasons, such as service authorization failure.) + + However, the precise form(s) of the authentication identities (used + within the server in its verifications, or otherwise) and the precise + form(s) of the authorization identities (used in making authorization + decisions, or otherwise) are beyond the scope of SASL and this + specification. In some circumstances, the precise identity forms + used in some context outside of the SASL exchange may be dictated by + other specifications. For instance, an identity assumption + authorization (proxy authorization) policy specification may dictate + how authentication and authorization identities are represented in + policy statements. + +3. The Authentication Exchange + + Each authentication exchange consists of a message from the client to + the server requesting authentication via a particular mechanism, + followed by one or more pairs of challenges from the server and + responses from the client, followed by a message from the server + indicating the outcome of the authentication exchange. (Note: + exchanges may also be aborted as discussed in Section 3.5.) + + The following illustration provides a high-level overview of an + authentication exchange. + + C: Request authentication exchange + S: Initial challenge + C: Initial response + <additional challenge/response messages> + S: Outcome of authentication exchange + + If the outcome is successful and a security layer was negotiated, + this layer is then installed (see Section 3.7). This also applies to + the following illustrations. + + + + + +Melnikov & Zeilenga Standards Track [Page 6] + +RFC 4422 SASL June 2006 + + + Some mechanisms specify that the first data sent in the + authentication exchange is from the client to the server. Protocols + may provide an optional initial response field in the request message + to carry this data. Where the mechanism specifies that the first + data sent in the exchange is from the client to the server, the + protocol provides an optional initial response field, and the client + uses this field, the exchange is shortened by one round-trip: + + C: Request authentication exchange + Initial response + <additional challenge/response messages> + S: Outcome of authentication exchange + + Where the mechanism specifies that the first data sent in the + exchange is from the client to the server and this field is + unavailable or unused, the client request is followed by an empty + challenge. + + C: Request authentication exchange + S: Empty Challenge + C: Initial Response + <additional challenge/response messages> + S: Outcome of authentication exchange + + Should a client include an initial response in its request where the + mechanism does not allow the client to send data first, the + authentication exchange fails. + + Some mechanisms specify that the server is to send additional data to + the client when indicating a successful outcome. Protocols may + provide an optional additional data field in the outcome message to + carry this data. Where the mechanism specifies that the server is to + return additional data with the successful outcome, the protocol + provides an optional additional data field in the outcome message, + and the server uses this field, the exchange is shortened by one + round-trip: + + C: Request authentication exchange + S: Initial challenge + C: Initial response + <additional challenge/response messages> + S: Outcome of authentication exchange with + additional data with success + + Where the mechanism specifies that the server is to return additional + data to the client with a successful outcome and this field is + unavailable or unused, the additional data is sent as a challenge + whose response is empty. After receiving this response, the server + then indicates the successful outcome. + + + +Melnikov & Zeilenga Standards Track [Page 7] + +RFC 4422 SASL June 2006 + + + C: Request authentication exchange + S: Initial challenge + C: Initial response + <additional challenge/response messages> + S: Additional data challenge + C: Empty Response + S: Outcome of authentication exchange + + Where mechanisms specify that the first data sent in the exchange is + from the client to the server and additional data is sent to the + client along with indicating a successful outcome, and the protocol + provides fields supporting both, then the exchange takes two fewer + round-trips: + + C: Request authentication exchange + Initial response + <additional challenge/response messages> + S: Outcome of authentication exchange + with additional data with success + + instead of: + + C: Request authentication exchange + S: Empty Challenge + C: Initial Response + <additional challenge/response messages> + S: Additional data challenge + C: Empty Response + S: Outcome of authentication exchange + +3.1. Mechanism Naming + + SASL mechanisms are named by character strings, from 1 to 20 + characters in length, consisting of ASCII [ASCII] uppercase letters, + digits, hyphens, and/or underscores. In the following Augmented + Backus-Naur Form (ABNF) [RFC4234] grammar, the <sasl-mech> production + defines the syntax of a SASL mechanism name. + + sasl-mech = 1*20mech-char + mech-char = UPPER-ALPHA / DIGIT / HYPHEN / UNDERSCORE + ; mech-char is restricted to A-Z (uppercase only), 0-9, -, and _ + ; from ASCII character set. + + UPPER-ALPHA = %x41-5A ; A-Z (uppercase only) + DIGIT = %x30-39 ; 0-9 + HYPHEN = %x2D ; hyphen (-) + UNDERSCORE = %x5F ; underscore (_) + + SASL mechanism names are registered as discussed in Section 7.1. + + + +Melnikov & Zeilenga Standards Track [Page 8] + +RFC 4422 SASL June 2006 + + +3.2. Mechanism Negotiation + + Mechanism negotiation is protocol specific. + + Commonly, a protocol will specify that the server advertises + supported and available mechanisms to the client via some facility + provided by the protocol, and the client will then select the "best" + mechanism from this list that it supports and finds suitable. + + Note that the mechanism negotiation is not protected by the + subsequent authentication exchange and hence is subject to downgrade + attacks if not protected by other means. + + To detect downgrade attacks, a protocol can allow the client to + discover available mechanisms subsequent to the authentication + exchange and installation of data security layers with at least data + integrity protection. This allows the client to detect changes to + the list of mechanisms supported by the server. + +3.3. Request Authentication Exchange + + The authentication exchange is initiated by the client by requesting + authentication via a mechanism it specifies. The client sends a + message that contains the name of the mechanism to the server. The + particulars of the message are protocol specific. + + Note that the name of the mechanism is not protected by the + mechanism, and hence is subject to alteration by an attacker if not + integrity protected by other means. + + Where the mechanism is defined to allow the client to send data + first, and the protocol's request message includes an optional + initial response field, the client may include the response to the + initial challenge in the authentication request message. + +3.4. Challenges and Responses + + The authentication exchange involves one or more pairs of server- + challenges and client-responses, the particulars of which are + mechanism specific. These challenges and responses are enclosed in + protocol messages, the particulars of which are protocol specific. + + Through these challenges and responses, the mechanism may: + + - authenticate the client to the server, + + - authenticate the server to the client, + + + + +Melnikov & Zeilenga Standards Track [Page 9] + +RFC 4422 SASL June 2006 + + + - transfer an authorization identity string, + + - negotiate a security layer, and + + - provide other services. + + The negotiation of the security layer may involve negotiation of the + security services to be provided in the layer, how these services + will be provided, and negotiation of a maximum cipher-text buffer + size each side is able to receive in the layer (see Section 3.6). + + After receiving an authentication request or any client response, the + server may issue a challenge, abort the exchange, or indicate the + outcome of an exchange. After receiving a challenge, a client + mechanism may issue a response or abort the exchange. + +3.4.1. Authorization Identity String + + The authorization identity string is a sequence of zero or more + Unicode [Unicode] characters, excluding the NUL (U+0000) character, + representing the identity to act as. + + If the authorization identity string is absent, the client is + requesting to act as the identity the server associates with the + client's credentials. An empty string is equivalent to an absent + authorization identity. + + A non-empty authorization identity string indicates that the client + wishes to act as the identity represented by the string. In this + case, the form of identity represented by the string, as well as the + precise syntax and semantics of the string, is protocol specific. + + While the character encoding schema used to transfer the + authorization identity string in the authentication exchange is + mechanism specific, mechanisms are expected to be capable of carrying + the entire Unicode repertoire (with the exception of the NUL + character). + +3.5. Aborting Authentication Exchanges + + A client or server may desire to abort an authentication exchange if + it is unwilling or unable to continue (or enter into). + + A client may abort the authentication exchange by sending a message, + the particulars of which are protocol specific, to the server, + indicating that the exchange is aborted. The server may be required + by the protocol to return a message in response to the client's abort + message. + + + +Melnikov & Zeilenga Standards Track [Page 10] + +RFC 4422 SASL June 2006 + + + Likewise, a server may abort the authentication exchange by sending a + message, the particulars of which are protocol specific, to the + client, indicating that the exchange is aborted. + +3.6. Authentication Outcome + + At the conclusion of the authentication exchange, the server sends a + message, the particulars of which are protocol specific, to the + client indicating the outcome of the exchange. + + The outcome is not successful if + + - the authentication exchange failed for any reason, + + - the client's credentials could not be verified, + + - the server cannot associate an identity with the client's + credentials, + + - the client-provided authorization identity string is malformed, + + - the identity associated with the client's credentials is not + authorized to act as the requested authorization identity, + + - the negotiated security layer (or lack thereof) is not + suitable, or + + - the server is not willing to provide service to the client for + any reason. + + The protocol may include an optional additional data field in this + outcome message. This field can only include additional data when + the outcome is successful. + + If the outcome is successful and a security layer was negotiated, + this layer is then installed. If the outcome is unsuccessful, or a + security layer was not negotiated, any existing security is left in + place. + + The outcome message provided by the server can provide a way for the + client to distinguish between errors that are best dealt with by re- + prompting the user for her credentials, errors that are best dealt + with by telling the user to try again later, and errors where the + user must contact a system administrator for resolution (see the SYS + and AUTH POP Response Codes [RFC3206] specification for an example). + This distinction is particularly useful during scheduled server + maintenance periods as it reduces support costs. It is also + important that the server can be configured such that the outcome + + + +Melnikov & Zeilenga Standards Track [Page 11] + +RFC 4422 SASL June 2006 + + + message will not distinguish between a valid user with invalid + credentials and an invalid user. + +3.7. Security Layers + + SASL mechanisms may offer a wide range of services in security + layers. Typical services include data integrity and data + confidentiality. SASL mechanisms that do not provide a security + layer are treated as negotiating no security layer. + + If use of a security layer is negotiated in the authentication + protocol exchange, the layer is installed by the server after + indicating the outcome of the authentication exchange and installed + by the client upon receipt of the outcome indication. In both cases, + the layer is installed before transfer of further protocol data. The + precise position upon which the layer takes effect in the protocol + data stream is protocol specific. + + Once the security layer is in effect in the protocol data stream, it + remains in effect until either a subsequently negotiated security + layer is installed or the underlying transport connection is closed. + + When in effect, the security layer processes protocol data into + buffers of protected data. If at any time the security layer is + unable or unwilling to continue producing buffers protecting protocol + data, the underlying transport connection MUST be closed. If the + security layer is not able to decode a received buffer, the + underlying connection MUST be closed. In both cases, the underlying + transport connection SHOULD be closed gracefully. + + Each buffer of protected data is transferred over the underlying + transport connection as a sequence of octets prepended with a four- + octet field in network byte order that represents the length of the + buffer. The length of the protected data buffer MUST be no larger + than the maximum size that the other side expects. Upon the receipt + of a length field whose value is greater than the maximum size, the + receiver SHOULD close the connection, as this might be a sign of an + attack. + + The maximum size that each side expects is fixed by the mechanism, + either through negotiation or by its specification. + +3.8. Multiple Authentications + + Unless explicitly permitted in the protocol (as stated in the + protocol's technical specification), only one successful SASL + authentication exchange may occur in a protocol session. In this + + + + +Melnikov & Zeilenga Standards Track [Page 12] + +RFC 4422 SASL June 2006 + + + case, once an authentication exchange has successfully completed, + further attempts to initiate an authentication exchange fail. + + Where multiple successful SASL authentication exchanges are permitted + in the protocol, then in no case may multiple SASL security layers be + simultaneously in effect. If a security layer is in effect and a + subsequent SASL negotiation selects a second security layer, then the + second security layer replaces the first. If a security layer is in + effect and a subsequent SASL negotiation selects no security layer, + the original security layer remains in effect. + + Where multiple successful SASL negotiations are permitted in the + protocol, the effect of a failed SASL authentication exchange upon + the previously established authentication and authorization state is + protocol specific. The protocol's technical specification should be + consulted to determine whether the previous authentication and + authorization state remains in force, or changed to an anonymous + state, or otherwise was affected. Regardless of the protocol- + specific effect upon previously established authentication and + authorization state, the previously negotiated security layer remains + in effect. + +4. Protocol Requirements + + In order for a protocol to offer SASL services, its specification + MUST supply the following information: + + 1) A service name, to be selected from registry of "service" elements + for the Generic Security Service Application Program Interface + (GSSAPI) host-based service name form, as described in Section 4.1 + of [RFC2743]. Note that this registry is shared by all GSSAPI and + SASL mechanisms. + + 2) Detail any mechanism negotiation facility that the protocol + provides (see Section 3.2). + + A protocol SHOULD specify a facility through which the client may + discover, both before initiation of the SASL exchange and after + installing security layers negotiated by the exchange, the names + of the SASL mechanisms that the server makes available to the + client. The latter is important to allow the client to detect + downgrade attacks. This facility is typically provided through + the protocol's extensions or capabilities discovery facility. + + 3) Definition of the messages necessary for authentication exchange, + including the following: + + + + + +Melnikov & Zeilenga Standards Track [Page 13] + +RFC 4422 SASL June 2006 + + + a) A message to initiate the authentication exchange (see Section + 3.3). + + This message MUST contain a field for carrying the name of the + mechanism selected by the client. + + This message SHOULD contain an optional field for carrying an + initial response. If the message is defined with this field, + the specification MUST describe how messages with an empty + initial response are distinguished from messages with no + initial response. This field MUST be capable of carrying + arbitrary sequences of octets (including zero-length sequences + and sequences containing zero-valued octets). + + b) Messages to transfer server challenges and client responses + (see Section 3.4). + + Each of these messages MUST be capable of carrying arbitrary + sequences of octets (including zero-length sequences and + sequences containing zero-valued octets). + + c) A message to indicate the outcome of the authentication + exchange (see Section 3.6). + + This message SHOULD contain an optional field for carrying + additional data with a successful outcome. If the message is + defined with this field, the specification MUST describe how + messages with an empty additional data are distinguished from + messages with no additional data. This field MUST be capable + of carrying arbitrary sequences of octets (including zero- + length sequences and sequences containing zero-valued octets). + + 4) Prescribe the syntax and semantics of non-empty authorization + identity strings (see Section 3.4.1). + + In order to avoid interoperability problems due to differing + normalizations, the protocol specification MUST detail precisely + how and where (client or server) non-empty authorization identity + strings are prepared, including all normalizations, for comparison + and other applicable functions to ensure proper function. + + Specifications are encouraged to prescribe use of existing + authorization identity forms as well as existing string + representations, such as simple user names [RFC4013]. + + Where the specification does not precisely prescribe how + identities in SASL relate to identities used elsewhere in the + protocol, for instance, in access control policy statements, it + + + +Melnikov & Zeilenga Standards Track [Page 14] + +RFC 4422 SASL June 2006 + + + may be appropriate for the protocol to provide a facility by which + the client can discover information (such as the representation of + the identity used in making access control decisions) about + established identities for these uses. + + 5) Detail any facility the protocol provides that allows the client + and/or server to abort authentication exchange (see Section 3.5). + + Protocols that support multiple authentications typically allow a + client to abort an ongoing authentication exchange by initiating a + new authentication exchange. Protocols that do not support + multiple authentications may require the client to close the + connection and start over to abort an ongoing authentication + exchange. + + Protocols typically allow the server to abort ongoing + authentication exchanges by returning a non-successful outcome + message. + + 6) Identify precisely where newly negotiated security layers start to + take effect, in both directions (see Section 3.7). + + Typically, specifications require security layers to start taking + effect on the first octet following the outcome message in data + being sent by the server and on the first octet sent after receipt + of the outcome message in data being sent by the client. + + 7) If the protocol supports other layered security services, such as + Transport Layer Security (TLS) [RFC4346], the specification MUST + prescribe the order in which security layers are applied to + protocol data. + + For instance, where a protocol supports both TLS and SASL security + layers, the specification could prescribe any of the following: + + a) SASL security layer is always applied first to data being sent + and, hence, applied last to received data, + + b) SASL security layer is always applied last to data being sent + and, hence, applied first to received data, + + c) Layers are applied in the order in which they were installed, + + d) Layers are applied in the reverse order in which they were + installed, or + + e) Both TLS and SASL security layers cannot be installed. + + + + +Melnikov & Zeilenga Standards Track [Page 15] + +RFC 4422 SASL June 2006 + + + 8) Indicate whether the protocol supports multiple authentications + (see Section 3.8). If so, the protocol MUST detail the effect a + failed SASL authentication exchange will have upon a previously + established authentication and authorization state. + + Protocol specifications SHOULD avoid stating implementation + requirements that would hinder replacement of applicable mechanisms. + In general, protocol specifications SHOULD be mechanism neutral. + There are a number of reasonable exceptions to this recommendation, + including + + - detailing how credentials (which are mechanism specific) are + managed in the protocol, + + - detailing how authentication identities (which are mechanism + specific) and authorization identities (which are protocol + specific) relate to each other, and + + - detailing which mechanisms are applicable to the protocol. + +5. Mechanism Requirements + + SASL mechanism specifications MUST supply the following information: + + 1) The name of the mechanism (see Section 3.1). This name MUST be + registered as discussed in Section 7.1. + + 2) A definition of the server-challenges and client-responses of the + authentication exchange, as well as the following: + + a) An indication of whether the mechanism is client-first, + variable, or server-first. If a SASL mechanism is defined as + client-first and the client does not send an initial response + in the authentication request, then the first server challenge + MUST be empty (the EXTERNAL mechanism is an example of this + case). If a SASL mechanism is defined as variable, then the + specification needs to state how the server behaves when the + initial client response in the authentication request is + omitted (the DIGEST-MD5 mechanism [DIGEST-MD5] is an example of + this case). If a SASL mechanism is defined as server-first, + then the client MUST NOT send an initial client response in the + authentication request (the CRAM-MD5 mechanism [CRAM-MD5] is an + example of this case). + + b) An indication of whether the server is expected to provide + additional data when indicating a successful outcome. If so, + if the server sends the additional data as a challenge, the + + + + +Melnikov & Zeilenga Standards Track [Page 16] + +RFC 4422 SASL June 2006 + + + specification MUST indicate that the response to this challenge + is an empty response. + + SASL mechanisms SHOULD be designed to minimize the number of + challenges and responses necessary to complete the exchange. + + 3) An indication of whether the mechanism is capable of transferring + authorization identity strings (see Section 3.4.1). While some + legacy mechanisms are incapable of transmitting an authorization + identity (which means that for these mechanisms, the authorization + identity is always the empty string), newly defined mechanisms + SHOULD be capable of transferring authorization identity strings. + The mechanism SHOULD NOT be capable of transferring both no + authorization identity string and an empty authorization identity. + + Mechanisms that are capable of transferring an authorization + identity string MUST be capable of transferring arbitrary non- + empty sequences of Unicode characters, excluding those that + contain the NUL (U+0000) character. Mechanisms SHOULD use the + UTF-8 [RFC3629] transformation format. The specification MUST + detail how any Unicode code points special to the mechanism that + might appear in the authorization identity string are escaped to + avoid ambiguity during decoding of the authorization identity + string. Typically, mechanisms that have special characters + require these special characters to be escaped or encoded in the + character string (after encoding it in a particular Unicode + transformation format) using a data encoding scheme such as Base64 + [RFC3548]. + + 4) The specification MUST detail whether the mechanism offers a + security layer. If the mechanism does, the specification MUST + detail the security and other services offered in the layer as + well as how these services are to be implemented. + + 5) If the underlying cryptographic technology used by a mechanism + supports data integrity, then the mechanism specification MUST + integrity protect the transmission of an authorization identity + and the negotiation of the security layer. + + SASL mechanisms SHOULD be protocol neutral. + + SASL mechanisms SHOULD reuse existing credential and identity forms, + as well as associated syntaxes and semantics. + + SASL mechanisms SHOULD use the UTF-8 transformation format [RFC3629] + for encoding Unicode [Unicode] code points for transfer. + + + + + +Melnikov & Zeilenga Standards Track [Page 17] + +RFC 4422 SASL June 2006 + + + In order to avoid interoperability problems due to differing + normalizations, when a mechanism calls for character data (other than + the authorization identity string) to be used as input to a + cryptographic and/or comparison function, the specification MUST + detail precisely how and where (client or server) the character data + is to be prepared, including all normalizations, for input into the + function to ensure proper operation. + + For simple user names and/or passwords in authentication credentials, + SASLprep [RFC4013] (a profile of the StringPrep [RFC3454] preparation + algorithm), SHOULD be specified as the preparation algorithm. + + The mechanism SHOULD NOT use the authorization identity string in + generation of any long-term cryptographic keys or hashes as there is + no requirement that the authorization identity string be canonical. + Long-term, here, means a term longer than the duration of the + authentication exchange in which they were generated. That is, as + different clients (of the same or different protocol) may provide + different authorization identity strings that are semantically + equivalent, use of authorization identity strings in generation of + cryptographic keys and hashes will likely lead to interoperability + and other problems. + +6. Security Considerations + + Security issues are discussed throughout this memo. + + Many existing SASL mechanisms do not provide adequate protection + against passive attacks, let alone active attacks, in the + authentication exchange. Many existing SASL mechanisms do not offer + security layers. It is hoped that future SASL mechanisms will + provide strong protection against passive and active attacks in the + authentication exchange, as well as security layers with strong basic + data security features (e.g., data integrity and data + confidentiality) services. It is also hoped that future mechanisms + will provide more advanced data security services like re-keying (see + Section 6.3). + + Regardless, the SASL framework is susceptible to downgrade attacks. + Section 6.1.2 offers a variety of approaches for preventing or + detecting these attacks. In some cases, it is appropriate to use + data integrity protective services external to SASL (e.g., TLS) to + protect against downgrade attacks in SASL. Use of external + protective security services is also important when the mechanisms + available do not themselves offer adequate integrity and/or + confidentiality protection of the authentication exchange and/or + protocol data. + + + + +Melnikov & Zeilenga Standards Track [Page 18] + +RFC 4422 SASL June 2006 + + +6.1. Active Attacks + +6.1.1. Hijack Attacks + + When the client selects a SASL security layer with at least integrity + protection, this protection serves as a counter-measure against an + active attacker hijacking the connection and modifying protocol data + sent after establishment of the security layer. Implementations + SHOULD close the connection when the security services in a SASL + security layer report protocol data report lack of data integrity. + +6.1.2. Downgrade Attacks + + It is important that any security-sensitive protocol negotiations be + performed after installation of a security layer with data integrity + protection. Protocols should be designed such that negotiations + performed prior to this installation should be revalidated after + installation is complete. Negotiation of the SASL mechanism is + security sensitive. + + When a client negotiates the authentication mechanism with the server + and/or other security features, it is possible for an active attacker + to cause a party to use the least secure security services available. + For instance, an attacker can modify the server-advertised mechanism + list or can modify the client-advertised security feature list within + a mechanism response. To protect against this sort of attack, + implementations SHOULD NOT advertise mechanisms and/or features that + cannot meet their minimum security requirements, SHOULD NOT enter + into or continue authentication exchanges that cannot meet their + minimum security requirements, and SHOULD verify that completed + authentication exchanges result in security services that meet their + minimum security requirements. Note that each endpoint needs to + independently verify that its security requirements are met. + + In order to detect downgrade attacks to the least (or less) secure + mechanism supported, the client can discover the SASL mechanisms that + the server makes available both before the SASL authentication + exchange and after the negotiated SASL security layer (with at least + data integrity protection) has been installed through the protocol's + mechanism discovery facility. If the client finds that the + integrity-protected list (the list obtained after the security layer + was installed) contains a stronger mechanism than those in the + previously obtained list, the client should assume that the + previously obtained list was modified by an attacker and SHOULD close + the underlying transport connection. + + The client's initiation of the SASL exchange, including the selection + of a SASL mechanism, is done in the clear and may be modified by an + + + +Melnikov & Zeilenga Standards Track [Page 19] + +RFC 4422 SASL June 2006 + + + active attacker. It is important for any new SASL mechanisms to be + designed such that an active attacker cannot obtain an authentication + with weaker security properties by modifying the SASL mechanism name + and/or the challenges and responses. + + Multi-level negotiation of security features is prone to downgrade + attack. Protocol designers should avoid offering higher-level + negotiation of security features in protocols (e.g., above SASL + mechanism negotiation) and mechanism designers should avoid lower- + level negotiation of security features in mechanisms (e.g., below + SASL mechanism negotiation). + +6.1.3. Replay Attacks + + Some mechanisms may be subject to replay attacks unless protected by + external data security services (e.g., TLS). + +6.1.4. Truncation Attacks + + Most existing SASL security layers do not themselves offer protection + against truncation attack. In a truncation attack, the active + attacker causes the protocol session to be closed, causing a + truncation of the possibly integrity-protected data stream that leads + to behavior of one or both the protocol peers that inappropriately + benefits the attacker. Truncation attacks are fairly easy to defend + against in connection-oriented application-level protocols. A + protocol can defend against these attacks by ensuring that each + information exchange has a clear final result and that each protocol + session has a graceful closure mechanism, and that these are + integrity protected. + +6.1.5. Other Active Attacks + + When use of a security layer is negotiated by the authentication + protocol exchange, the receiver SHOULD handle gracefully any + protected data buffer larger than the defined/negotiated maximal + size. In particular, it MUST NOT blindly allocate the amount of + memory specified in the buffer size field, as this might cause the + "out of memory" condition. If the receiver detects a large block, it + SHOULD close the connection. + +6.2. Passive Attacks + + Many mechanisms are subject to various passive attacks, including + simple eavesdropping of unprotected credential information as well as + online and offline dictionary attacks of protected credential + information. + + + + +Melnikov & Zeilenga Standards Track [Page 20] + +RFC 4422 SASL June 2006 + + +6.3. Re-keying + + The secure or administratively permitted lifetimes of SASL + mechanisms' security layers are finite. Cryptographic keys weaken as + they are used and as time passes; the more time and/or cipher-text + that a cryptanalyst has after the first use of the a key, the easier + it is for the cryptanalyst to mount attacks on the key. + + Administrative limits on a security layer's lifetime may take the + form of time limits expressed in X.509 certificates, in Kerberos V + tickets, or in directories, and are often desired. In practice, one + likely effect of administrative lifetime limits is that applications + may find that security layers stop working in the middle of + application protocol operation, such as, perhaps, during large data + transfers. As the result of this, the connection will be closed (see + Section 3.7), which will result in an unpleasant user experience. + + Re-keying (key renegotiation process) is a way of addressing the + weakening of cryptographic keys. The SASL framework does not itself + provide for re-keying; SASL mechanisms may. Designers of future SASL + mechanisms should consider providing re-keying services. + + Implementations that wish to re-key SASL security layers where the + mechanism does not provide for re-keying SHOULD reauthenticate the + same IDs and replace the expired or soon-to-expire security layers. + This approach requires support for reauthentication in the + application protocols (see Section 3.8). + +6.4. Other Considerations + + Protocol designers and implementors should understand the security + considerations of mechanisms so they may select mechanisms that are + applicable to their needs. + + Distributed server implementations need to be careful in how they + trust other parties. In particular, authentication secrets should + only be disclosed to other parties that are trusted to manage and use + those secrets in a manner acceptable to the disclosing party. + Applications using SASL assume that SASL security layers providing + data confidentiality are secure even when an attacker chooses the + text to be protected by the security layer. Similarly, applications + assume that the SASL security layer is secure even if the attacker + can manipulate the cipher-text output of the security layer. New + SASL mechanisms are expected to meet these assumptions. + + + + + + + +Melnikov & Zeilenga Standards Track [Page 21] + +RFC 4422 SASL June 2006 + + + Unicode security considerations [UTR36] apply to authorization + identity strings, as well as UTF-8 [RFC3629] security considerations + where UTF-8 is used. SASLprep [RFC4013] and StringPrep [RFC3454] + security considerations also apply where used. + +7. IANA Considerations + +7.1. SASL Mechanism Registry + + The SASL mechanism registry is maintained by IANA. The registry is + currently available at <http://www.iana.org/assignments/sasl- + mechanisms>. + + The purpose of this registry is not only to ensure uniqueness of + values used to name SASL mechanisms, but also to provide a definitive + reference to technical specifications detailing each SASL mechanism + available for use on the Internet. + + There is no naming convention for SASL mechanisms; any name that + conforms to the syntax of a SASL mechanism name can be registered. + + The procedure detailed in Section 7.1.1 is to be used for + registration of a value naming a specific individual mechanism. + + The procedure detailed in Section 7.1.2 is to be used for + registration of a value naming a family of related mechanisms. + + Comments may be included in the registry as discussed in Section + 7.1.3 and may be changed as discussed in Section 7.1.4. + + The SASL mechanism registry has been updated to reflect that this + document provides the definitive technical specification for SASL and + that this section provides the registration procedures for this + registry. + + + + + + + + + + + + + + + + + +Melnikov & Zeilenga Standards Track [Page 22] + +RFC 4422 SASL June 2006 + + +7.1.1. Mechanism Name Registration Procedure + + IANA will register new SASL mechanism names on a First Come First + Served basis, as defined in BCP 26 [RFC2434]. IANA has the right to + reject obviously bogus registration requests, but will perform no + review of claims made in the registration form. + + Registration of a SASL mechanism is requested by filling in the + following template: + + Subject: Registration of SASL mechanism X + + SASL mechanism name (or prefix for the family): + + Security considerations: + + Published specification (recommended): + + Person & email address to contact for further information: + + Intended usage: (One of COMMON, LIMITED USE, or OBSOLETE) + + Owner/Change controller: + + Note: (Any other information that the author deems relevant may be + added here.) + + and sending it via electronic mail to IANA at <iana@iana.org>. + + While this registration procedure does not require expert review, + authors of SASL mechanisms are encouraged to seek community review + and comment whenever that is feasible. Authors may seek community + review by posting a specification of their proposed mechanism as an + Internet-Draft. SASL mechanisms intended for widespread use should + be standardized through the normal IETF process, when appropriate. + + + + + + + + + + + + + + + + +Melnikov & Zeilenga Standards Track [Page 23] + +RFC 4422 SASL June 2006 + + +7.1.2. Family Name Registration Procedure + + As noted above, there is no general naming convention for SASL + mechanisms. However, specifications may reserve a portion of the + SASL mechanism namespace for a set of related SASL mechanisms, a + "family" of SASL mechanisms. Each family of SASL mechanisms is + identified by a unique prefix, such as X-. Registration of new SASL + mechanism family names requires expert review as defined in BCP 26 + [RFC2434]. + + Registration of a SASL family name is requested by filling in the + following template: + + Subject: Registration of SASL mechanism family X + + SASL family name (or prefix for the family): + + Security considerations: + + Published specification (recommended): + + Person & email address to contact for further information: + + Intended usage: (One of COMMON, LIMITED USE, or OBSOLETE) + + Owner/Change controller: + + Note: (Any other information that the author deems relevant may be + added here.) + + and sending it via electronic mail to the IETF SASL mailing list at + <ietf-sasl@imc.org> and carbon copying IANA at <iana@iana.org>. + After allowing two weeks for community input on the IETF SASL mailing + list, the expert will determine the appropriateness of the + registration request and either approve or disapprove the request + with notice to the requestor, the mailing list, and IANA. + + The review should focus on the appropriateness of the requested + family name for the proposed use and the appropriateness of the + proposed naming and registration plan for existing and future + mechanism names in the family. The scope of this request review may + entail consideration of relevant aspects of any provided technical + specification, such as their IANA Considerations section. However, + this review is narrowly focused on the appropriateness of the + requested registration and not on the overall soundness of any + provided technical specification. + + + + + +Melnikov & Zeilenga Standards Track [Page 24] + +RFC 4422 SASL June 2006 + + + Authors are encouraged to pursue community review by posting the + technical specification as an Internet-Draft and soliciting comment + by posting to appropriate IETF mailing lists. + +7.1.3. Comments on SASL Mechanism Registrations + + Comments on a registered SASL mechanism/family should first be sent + to the "owner" of the mechanism/family and/or to the <ietf- + sasl@imc.org> mailing list. + + Submitters of comments may, after a reasonable attempt to contact the + owner, request IANA to attach their comment to the SASL mechanism + registration itself by sending mail to <iana@iana.org>. At IANA's + sole discretion, IANA may attach the comment to the SASL mechanism's + registration. + +7.1.4. Change Control + + Once a SASL mechanism registration has been published by IANA, the + author may request a change to its definition. The change request + follows the same procedure as the registration request. + + The owner of a SASL mechanism may pass responsibility for the SASL + mechanism to another person or agency by informing IANA; this can be + done without discussion or review. + + The IESG may reassign responsibility for a SASL mechanism. The most + common case of this will be to enable changes to be made to + mechanisms where the author of the registration has died, has moved + out of contact, or is otherwise unable to make changes that are + important to the community. + + SASL mechanism registrations may not be deleted; mechanisms that are + no longer believed appropriate for use can be declared OBSOLETE by a + change to their "intended usage" field; such SASL mechanisms will be + clearly marked in the lists published by IANA. + + The IESG is considered to be the owner of all SASL mechanisms that + are on the IETF standards track. + + + + + + + + + + + + +Melnikov & Zeilenga Standards Track [Page 25] + +RFC 4422 SASL June 2006 + + +7.2. Registration Changes + + The IANA has updated the SASL mechanisms registry as follows: + + 1) Changed the "Intended usage" of the KERBEROS_V4 and SKEY mechanism + registrations to OBSOLETE. + + 2) Changed the "Published specification" of the EXTERNAL mechanism to + this document as indicated below: + + Subject: Updated Registration of SASL mechanism EXTERNAL + Family of SASL mechanisms: NO + SASL mechanism name: EXTERNAL + Security considerations: See A.3 of RFC 4422 + Published specification (optional, recommended): RFC 4422 + Person & email address to contact for further information: + Alexey Melnikov <Alexey.Melnikov@isode.com> + Intended usage: COMMON + Owner/Change controller: IESG <iesg@ietf.org> + Note: Updates existing entry for EXTERNAL + +8. References + +8.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2244] Newman, C. and J. G. Myers, "ACAP -- Application + Configuration Access Protocol", RFC 2244, November + 1997. + + [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing + an IANA Considerations Section in RFCs", BCP 26, RFC + 2434, October 1998. + + [RFC2743] Linn, J., "Generic Security Service Application Program + Interface Version 2, Update 1", RFC 2743, January 2000. + + [RFC3454] Hoffman, P. and M. Blanchet, "Preparation of + Internationalized Strings ("stringprep")", RFC 3454, + December 2002. + + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. + + [RFC4013] Zeilenga, K., "SASLprep: Stringprep Profile for User + Names and Passwords", RFC 4013, February 2005. + + + +Melnikov & Zeilenga Standards Track [Page 26] + +RFC 4422 SASL June 2006 + + + [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 4234, October 2005. + + [ASCII] Coded Character Set--7-bit American Standard Code for + Information Interchange, ANSI X3.4-1986. + + [Unicode] The Unicode Consortium, "The Unicode Standard, Version + 3.2.0" is defined by "The Unicode Standard, Version + 3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201- + 61633-5), as amended by the "Unicode Standard Annex + #27: Unicode 3.1" + (http://www.unicode.org/reports/tr27/) and by the + "Unicode Standard Annex #28: Unicode 3.2" + (http://www.unicode.org/reports/tr28/). + + [CharModel] Whistler, K. and M. Davis, "Unicode Technical Report + #17, Character Encoding Model", UTR17, + <http://www.unicode.org/unicode/reports/tr17/>, August + 2000. + + [Glossary] The Unicode Consortium, "Unicode Glossary", + <http://www.unicode.org/glossary/>. + +8.2. Informative References + + [RFC3206] Gellens, R., "The SYS and AUTH POP Response Codes", RFC + 3206, February 2002. + + [RFC3548] Josefsson, S., "The Base16, Base32, and Base64 Data + Encodings", RFC 3548, July 2003. + + [RFC4301] Kent, S. and K. Seo, "Security Architecture for the + Internet Protocol", RFC 4301, December 2005. + + [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer + Security (TLS) Protocol Version 1.1", RFC 4346, April + 2006. + + [SASL-GSSAPI] Melnikov, A. (Editor), "The Kerberos V5 ("GSSAPI") SASL + Mechanism", Work in Progress, May 2006. + + [UTR36] Davis, M., "(Draft) Unicode Technical Report #36, + Character Encoding Model", UTR17, + <http://www.unicode.org/unicode/reports/tr36/>, + February 2005. + + [CRAM-MD5] Nerenberg, L., "The CRAM-MD5 SASL Mechanism", Work in + Progress. + + + +Melnikov & Zeilenga Standards Track [Page 27] + +RFC 4422 SASL June 2006 + + + [DIGEST-MD5] Leach, P., C. Newman, and A. Melnikov, "Using Digest + Authentication as a SASL Mechanism", Work in Progress, + March 2006. + +9. Acknowledgements + + This document is a revision of RFC 2222 written by John Myers. + + This revision is a product of the IETF Simple Authentication and + Security Layer (SASL) Working Group. + + The following individuals contributed significantly to this revision: + Abhijit Menon-Sen, Hallvard Furuseth, Jeffrey Hutzelman, John Myers, + Luke Howard, Magnus Nystrom, Nicolas Williams, Peter Saint-Andre, RL + 'Bob' Morgan, Rob Siemborski, Sam Hartman, Simon Josefsson, Tim + Alsop, and Tony Hansen. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Melnikov & Zeilenga Standards Track [Page 28] + +RFC 4422 SASL June 2006 + + +Appendix A. The SASL EXTERNAL Mechanism + + This appendix is normative. + + The EXTERNAL mechanism allows a client to request the server to use + credentials established by means external to the mechanism to + authenticate the client. The external means may be, for instance, IP + Security [RFC4301] or TLS [RFC4346] services. In absence of some a + priori agreement between the client and the server, the client cannot + make any assumption as to what external means the server has used to + obtain the client's credentials, nor make an assumption as to the + form of credentials. For example, the client cannot assume that the + server will use the credentials the client has established via TLS. + +A.1. EXTERNAL Technical Specification + + The name of this mechanism is "EXTERNAL". + + The mechanism does not provide a security layer. + + The mechanism is capable of transferring an authorization identity + string. If empty, the client is requesting to act as the identity + the server has associated with the client's credentials. If non- + empty, the client is requesting to act as the identity represented by + the string. + + The client is expected to send data first in the authentication + exchange. Where the client does not provide an initial response data + in its request to initiate the authentication exchange, the server is + to respond to the request with an empty initial challenge and then + the client is to provide its initial response. + + The client sends the initial response containing the UTF-8 [RFC3629] + encoding of the requested authorization identity string. This + response is non-empty when the client is requesting to act as the + identity represented by the (non-empty) string. This response is + empty when the client is requesting to act as the identity the server + associated with its authentication credentials. + + The syntax of the initial response is specified as a value of the + <extern-initial-resp> production detailed below using the Augmented + Backus-Naur Form (ABNF) [RFC4234] notation. + + external-initial-resp = authz-id-string + authz-id-string = *( UTF8-char-no-nul ) + UTF8-char-no-nul = UTF8-1-no-nul / UTF8-2 / UTF8-3 / UTF8-4 + UTF8-1-no-nul = %x01-7F + + + + +Melnikov & Zeilenga Standards Track [Page 29] + +RFC 4422 SASL June 2006 + + + where the <UTF8-2>, <UTF8-3>, and <UTF8-4> productions are as defined + in [RFC3629]. + + There are no additional challenges and responses. + + Hence, the server is to return the outcome of the authentication + exchange. + + The exchange fails if + + - the client has not established its credentials via external means, + + - the client's credentials are inadequate, + + - the client provided an empty authorization identity string and the + server is unwilling or unable to associate an authorization + identity with the client's credentials, + + - the client provided a non-empty authorization identity string that + is invalid per the syntax requirements of the applicable + application protocol specification, + + - the client provided a non-empty authorization identity string + representing an identity that the client is not allowed to act as, + or + + - the server is unwilling or unable to provide service to the client + for any other reason. + + Otherwise the exchange is successful. When indicating a successful + outcome, additional data is not provided. + +A.2. SASL EXTERNAL Examples + + This section provides examples of EXTERNAL authentication exchanges. + The examples are intended to help the readers understand the above + text. The examples are not definitive. The Application + Configuration Access Protocol (ACAP) [RFC2244] is used in the + examples. + + The first example shows use of EXTERNAL with an empty authorization + identity. In this example, the initial response is not sent in the + client's request to initiate the authentication exchange. + + S: * ACAP (SASL "DIGEST-MD5") + C: a001 STARTTLS + S: a001 OK "Begin TLS negotiation now" + <TLS negotiation, further commands are under TLS layer> + + + +Melnikov & Zeilenga Standards Track [Page 30] + +RFC 4422 SASL June 2006 + + + S: * ACAP (SASL "DIGEST-MD5" "EXTERNAL") + C: a002 AUTHENTICATE "EXTERNAL" + S: + "" + C: + "" + S: a002 OK "Authenticated" + + The second example shows use of EXTERNAL with an authorization + identity of "fred@example.com". In this example, the initial + response is sent with the client's request to initiate the + authentication exchange. This saves a round-trip. + + S: * ACAP (SASL "DIGEST-MD5") + C: a001 STARTTLS + S: a001 OK "Begin TLS negotiation now" + <TLS negotiation, further commands are under TLS layer> + S: * ACAP (SASL "DIGEST-MD5" "EXTERNAL") + C: a002 AUTHENTICATE "EXTERNAL" {16+} + C: fred@example.com + S: a002 NO "Cannot assume requested authorization identity" + +A.3. Security Considerations + + The EXTERNAL mechanism provides no security protection; it is + vulnerable to spoofing by either client or server, active attack, and + eavesdropping. It should only be used when adequate security + services have been established. + +Appendix B. Changes since RFC 2222 + + This appendix is non-normative. + + The material in RFC 2222 was significantly rewritten in the + production of this document. + + RFC 2222, by not stating that the authorization identity string was a + string of Unicode characters, let alone character data, implied that + the authorization identity string was a string of octets. + + - The authorization identity string is now defined as a string of + Unicode characters. The NUL (U+0000) character is prohibited. + While protocol specifications are responsible for defining the + authorization identity form, as well as the Unicode string syntax + and related semantics, mechanism specifications are responsible + for defining how the Unicode string is carried in the + authentication exchange. + + - Deleted "If so, when the client does not send data first, the + initial challenge MUST be specified as being an empty challenge." + + + +Melnikov & Zeilenga Standards Track [Page 31] + +RFC 4422 SASL June 2006 + + + The following technical change was made to the EXTERNAL mechanism: + + - The authorization identity string is to be UTF-8 encoded. + + Note that protocol and mechanism specification requirements have + been significantly tightened. Existing protocol and mechanism + specifications will need to be updated to meet these requirements. + +Editors' Addresses + + Alexey Melnikov + Isode Limited + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex, + TW12 2BX, United Kingdom + + EMail: Alexey.Melnikov@isode.com + URI: http://www.melnikov.ca/ + + + Kurt D. Zeilenga + OpenLDAP Foundation + + EMail: Kurt@OpenLDAP.org + + + + + + + + + + + + + + + + + + + + + + + + + + +Melnikov & Zeilenga Standards Track [Page 32] + +RFC 4422 SASL June 2006 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2006). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is provided by the IETF + Administrative Support Activity (IASA). + + + + + + + +Melnikov & Zeilenga Standards Track [Page 33] + diff --git a/imap/docs/rfc/rfc4466.txt b/imap/docs/rfc/rfc4466.txt new file mode 100644 index 00000000..dfde1685 --- /dev/null +++ b/imap/docs/rfc/rfc4466.txt @@ -0,0 +1,955 @@ + + + + + + +Network Working Group A. Melnikov +Request for Comments: 4466 Isode Ltd. +Updates: 2088, 2342, 3501, 3502, 3516 C. Daboo +Category: Standards Track April 2006 + + + Collected Extensions to IMAP4 ABNF + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2006). + +Abstract + + Over the years, many documents from IMAPEXT and LEMONADE working + groups, as well as many individual documents, have added syntactic + extensions to many base IMAP commands described in RFC 3501. For + ease of reference, this document collects most of such ABNF changes + in one place. + + This document also suggests a set of standard patterns for adding + options and extensions to several existing IMAP commands defined in + RFC 3501. The patterns provide for compatibility between existing + and future extensions. + + This document updates ABNF in RFCs 2088, 2342, 3501, 3502, and 3516. + It also includes part of the errata to RFC 3501. This document + doesn't specify any semantic changes to the listed RFCs. + + + + + + + + + + + + + + + +Melnikov & Daboo Standards Track [Page 1] + +RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 + + +Table of Contents + + 1. Introduction ....................................................2 + 1.1. Purpose of This Document ...................................2 + 1.2. Conventions Used in This Document ..........................3 + 2. IMAP ABNF Extensions ............................................3 + 2.1. Optional Parameters with the SELECT/EXAMINE Commands .......3 + 2.2. Extended CREATE Command ....................................4 + 2.3. Extended RENAME Command ....................................5 + 2.4. Extensions to FETCH and UID FETCH Commands .................6 + 2.5. Extensions to STORE and UID STORE Commands .................6 + 2.6. Extensions to SEARCH Command ...............................7 + 2.6.1. Extended SEARCH Command .............................7 + 2.6.2. ESEARCH untagged response ...........................8 + 2.7. Extensions to APPEND Command ...............................8 + 3. Formal Syntax ...................................................9 + 4. Security Considerations ........................................14 + 5. Normative References ...........................................15 + 6. Acknowledgements ...............................................15 + +1. Introduction + +1.1. Purpose of This Document + + This document serves several purposes: + + 1. rationalize and generalize ABNF for some existing IMAP + extensions; + 2. collect the ABNF in one place in order to minimize cross + references between documents; + 3. define building blocks for future extensions so that they can + be used together in a compatible way. + + It is expected that a future revision of this document will be + incorporated into a revision of RFC 3501. + + This document updates ABNF in RFCs 2088, 2342, 3501, 3502, and 3516. + It also includes part of the errata to RFC 3501. This document + doesn't specify any semantic changes to the listed RFCs. + + The ABNF in section 6 of RFC 2342 got rewritten to conform to the + ABNF syntax as defined in RFC 4234 and to reference new non-terminals + from RFC 3501. It was also restructured to allow for better + readability. There were no changes "on the wire". + + Section 2 extends ABNF for SELECT, EXAMINE, CREATE, RENAME, FETCH/UID + FETCH, STORE/UID STORE, SEARCH, and APPEND commands in a consistent + manner. Extensions to all the commands but APPEND have the same + + + +Melnikov & Daboo Standards Track [Page 2] + +RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 + + + structure. Extensibility for the APPEND command was done slightly + differently in order to preserve backward compatibility with existing + extensions. + + Section 2 also defines a new ESEARCH response, whose purpose is to + define a better version of the SEARCH response defined in RFC 3501. + + Section 3 defines the collected ABNF that replaces pieces of ABNF in + the aforementioned RFCs. The collected ABNF got generalized to allow + for easier future extensibility. + +1.2. Conventions Used in This Document + + In examples, "C:" and "S:" indicate lines sent by the client and + server, respectively. + + The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" + in this document are to be interpreted as defined in "Key words for + use in RFCs to Indicate Requirement Levels" [KEYWORDS]. + +2. IMAP ABNF Extensions + + This section is not normative. It provides some background on the + intended use of different extensions and it gives some guidance about + how future extensions should extend the described commands. + +2.1. Optional Parameters with the SELECT/EXAMINE Commands + + This document adds the ability to include one or more parameters with + the IMAP SELECT (section 6.3.1 of [IMAP4]) or EXAMINE (section 6.3.2 + of [IMAP4]) commands, to turn on or off certain standard behaviors, + or to add new optional behaviors required for a particular extension. + + There are two possible modes of operation: + + o A global state change where a single use of the optional parameter + will affect the session state from that time on, irrespective of + subsequent SELECT/EXAMINE commands. + + o A per-mailbox state change that will affect the session only for + the duration of the new selected state. A subsequent + SELECT/EXAMINE without the optional parameter will cancel its + effect for the newly selected mailbox. + + Optional parameters to the SELECT or EXAMINE commands are added as a + parenthesized list of attribute/value pairs, and appear after the + mailbox name in the standard SELECT or EXAMINE command. The order of + individual parameters is arbitrary. A parameter value is optional + + + +Melnikov & Daboo Standards Track [Page 3] + +RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 + + + and may consist of atoms, strings, or lists in a specific order. If + the parameter value is present, it always appears in parentheses (*). + Any parameter not defined by extensions that the server supports must + be rejected with a BAD response. + + Example: + + C: a SELECT INBOX (ANNOTATE) + S: ... + S: a OK SELECT complete + + In the above example, a single parameter is used with the SELECT + command. + + Example: + + C: a EXAMINE INBOX (ANNOTATE RESPONSES ("UID Responses") + CONDSTORE) + S: ... + S: a OK EXAMINE complete + + In the above example, three parameters are used with the EXAMINE + command. The second parameter consists of two items: an atom + "RESPONSES" followed by a quoted string. + + Example: + + C: a SELECT INBOX (BLURDYBLOOP) + S: a BAD Unknown parameter in SELECT command + + In the above example, a parameter not supported by the server is + used. This results in the BAD response from the server. + + (*) - if a parameter has a mandatory value, which can always be + represented as a number or a sequence-set, the parameter value does + not need the enclosing (). See ABNF for more details. + +2.2. Extended CREATE Command + + Arguments: mailbox name + OPTIONAL list of CREATE parameters + + Responses: no specific responses for this command + + Result: OK - create completed + NO - create failure: cannot create mailbox with + that name + BAD - argument(s) invalid + + + +Melnikov & Daboo Standards Track [Page 4] + +RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 + + + This document adds the ability to include one or more parameters with + the IMAP CREATE command (see section 6.3.3 of [IMAP4]), to turn on or + off certain standard behaviors, or to add new optional behaviors + required for a particular extension. No CREATE parameters are + defined in this document. + + Optional parameters to the CREATE command are added as a + parenthesized list of attribute/value pairs after the mailbox name. + The order of individual parameters is arbitrary. A parameter value + is optional and may consist of atoms, strings, or lists in a specific + order. If the parameter value is present, it always appears in + parentheses (*). Any parameter not defined by extensions that the + server supports must be rejected with a BAD response. + + (*) - if a parameter has a mandatory value, which can always be + represented as a number or a sequence-set, the parameter value does + not need the enclosing (). See ABNF for more details. + +2.3. Extended RENAME Command + + Arguments: existing mailbox name + new mailbox name + OPTIONAL list of RENAME parameters + + Responses: no specific responses for this command + + Result: OK - rename completed + NO - rename failure: cannot rename mailbox with + that name, cannot rename to mailbox with + that name, etc. + BAD - argument(s) invalid + + This document adds the ability to include one or more parameters with + the IMAP RENAME command (see section 6.3.5 of [IMAP4]), to turn on or + off certain standard behaviors, or to add new optional behaviors + required for a particular extension. No RENAME parameters are + defined in this document. + + Optional parameters to the RENAME command are added as a + parenthesized list of attribute/value pairs after the new mailbox + name. The order of individual parameters is arbitrary. A parameter + value is optional and may consist of atoms, strings, or lists in a + specific order. If the parameter value is present, it always appears + in parentheses (*). Any parameter not defined by extensions that the + server supports must be rejected with a BAD response. + + + + + + +Melnikov & Daboo Standards Track [Page 5] + +RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 + + + (*) - if a parameter has a mandatory value, which can always be + represented as a number or a sequence-set, the parameter value does + not need the enclosing (). See ABNF for more details. + +2.4. Extensions to FETCH and UID FETCH Commands + + Arguments: sequence set + message data item names or macro + OPTIONAL fetch modifiers + + Responses: untagged responses: FETCH + + Result: OK - fetch completed + NO - fetch error: cannot fetch that data + BAD - command unknown or arguments invalid + + This document extends the syntax of the FETCH and UID FETCH commands + (see section 6.4.5 of [IMAP4]) to include optional FETCH modifiers. + No fetch modifiers are defined in this document. + + The order of individual modifiers is arbitrary. Each modifier is an + attribute/value pair. A modifier value is optional and may consist + of atoms and/or strings and/or lists in a specific order. If the + modifier value is present, it always appears in parentheses (*). Any + modifiers not defined by extensions that the server supports must be + rejected with a BAD response. + + (*) - if a modifier has a mandatory value, which can always be + represented as a number or a sequence-set, the modifier value does + not need the enclosing (). See ABNF for more details. + +2.5. Extensions to STORE and UID STORE Commands + + Arguments: message set + OPTIONAL store modifiers + message data item name + value for message data item + + Responses: untagged responses: FETCH + + Result: OK - store completed + NO - store error: cannot store that data + BAD - command unknown or arguments invalid + + This document extends the syntax of the STORE and UID STORE commands + (see section 6.4.6 of [IMAP4]) to include optional STORE modifiers. + No store modifiers are defined in this document. + + + + +Melnikov & Daboo Standards Track [Page 6] + +RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 + + + The order of individual modifiers is arbitrary. Each modifier is an + attribute/value pair. A modifier value is optional and may consist + of atoms and/or strings and/or lists in a specific order. If the + modifier value is present, it always appears in parentheses (*). Any + modifiers not defined by extensions that the server supports must be + rejected with a BAD response. + + (*) - if a modifier has a mandatory value, which can always be + represented as a number or a sequence-set, the modifier value does + not need the enclosing (). See ABNF for more details. + +2.6. Extensions to SEARCH Command + +2.6.1. Extended SEARCH Command + + Arguments: OPTIONAL result specifier + OPTIONAL [CHARSET] specification + searching criteria (one or more) + + Responses: REQUIRED untagged response: SEARCH (*) + + Result: OK - search completed + NO - search error: cannot search that [CHARSET] or + criteria + BAD - command unknown or arguments invalid + + This section updates definition of the SEARCH command described in + section 6.4.4 of [IMAP4]. + + The SEARCH command is extended to allow for result options. This + document does not define any result options. + + The order of individual options is arbitrary. Individual options may + contain parameters enclosed in parentheses (**). If an option has + parameters, they consist of atoms and/or strings and/or lists in a + specific order. Any options not defined by extensions that the + server supports must be rejected with a BAD response. + + (*) - An extension to the SEARCH command may require another untagged + response, or no untagged response to be returned. Section 2.6.2 + defines a new ESEARCH untagged response that replaces the SEARCH + untagged response. Note that for a given extended SEARCH command the + SEARCH and ESEARCH responses SHOULD be mutually exclusive, i.e., only + one of them should be returned. + + (**) - if an option has a mandatory parameter, which can always be + represented as a number or a sequence-set, the option parameter does + not need the enclosing (). See ABNF for more details. + + + +Melnikov & Daboo Standards Track [Page 7] + +RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 + + +2.6.2. ESEARCH untagged response + + Contents: one or more search-return-data pairs + + The ESEARCH response SHOULD be sent as a result of an extended SEARCH + or UID SEARCH command specified in section 2.6.1. + + The ESEARCH response starts with an optional search correlator. If + it is missing, then the response was not caused by a particular IMAP + command, whereas if it is present, it contains the tag of the command + that caused the response to be returned. + + The search correlator is followed by an optional UID indicator. If + this indicator is present, all data in the ESEARCH response refers to + UIDs, otherwise all returned data refers to message numbers. + + The rest of the ESEARCH response contains one or more search data + pairs. Each pair starts with unique return item name, followed by a + space and the corresponding data. Search data pairs may be returned + in any order. Unless specified otherwise by an extension, any return + item name SHOULD appear only once in an ESEARCH response. + + Example: S: * ESEARCH UID COUNT 5 ALL 4:19,21,28 + + Example: S: * ESEARCH (TAG "a567") UID COUNT 5 ALL 4:19,21,28 + + Example: S: * ESEARCH COUNT 5 ALL 1:17,21 + +2.7. Extensions to APPEND Command + + The IMAP BINARY extension [BINARY] extends the APPEND command to + allow a client to append data containing NULs by using the <literal8> + syntax. The ABNF was rewritten to allow for easier extensibility by + IMAP extensions. This document hasn't specified any semantical + changes to the [BINARY] extension. + + In addition, the non-terminal "literal8" defined in [BINARY] got + extended to allow for non-synchronizing literals if both [BINARY] and + [LITERAL+] extensions are supported by the server. + + The IMAP MULTIAPPEND extension [MULTIAPPEND] extends the APPEND + command to allow a client to append multiple messages atomically. + This document defines a common syntax for the APPEND command that + takes into consideration syntactic extensions defined by both + [BINARY] and [MULTIAPPEND] extensions. + + + + + + +Melnikov & Daboo Standards Track [Page 8] + +RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 + + +3. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [ABNF]. + + Non-terminals referenced but not defined below are as defined by + [IMAP4]. + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of uppercase or lowercase characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. + + append = "APPEND" SP mailbox 1*append-message + ;; only a single append-message may appear + ;; if MULTIAPPEND [MULTIAPPEND] capability + ;; is not present + + append-message = append-opts SP append-data + + append-ext = append-ext-name SP append-ext-value + ;; This non-terminal define extensions to + ;; to message metadata. + + append-ext-name = tagged-ext-label + + append-ext-value= tagged-ext-val + ;; This non-terminal shows recommended syntax + ;; for future extensions. + + + append-data = literal / literal8 / append-data-ext + + append-data-ext = tagged-ext + ;; This non-terminal shows recommended syntax + ;; for future extensions, + ;; i.e., a mandatory label followed + ;; by parameters. + + append-opts = [SP flag-list] [SP date-time] *(SP append-ext) + ;; message metadata + + charset = atom / quoted + ;; Exact syntax is defined in [CHARSET]. + + create = "CREATE" SP mailbox + [create-params] + ;; Use of INBOX gives a NO error. + + + +Melnikov & Daboo Standards Track [Page 9] + +RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 + + + create-params = SP "(" create-param *( SP create-param) ")" + + create-param-name = tagged-ext-label + + create-param = create-param-name [SP create-param-value] + + create-param-value= tagged-ext-val + ;; This non-terminal shows recommended syntax + ;; for future extensions. + + + esearch-response = "ESEARCH" [search-correlator] [SP "UID"] + *(SP search-return-data) + ;; Note that SEARCH and ESEARCH responses + ;; SHOULD be mutually exclusive, + ;; i.e., only one of the response types + ;; should be + ;; returned as a result of a command. + + + examine = "EXAMINE" SP mailbox [select-params] + ;; modifies the original IMAP EXAMINE command + ;; to accept optional parameters + + fetch = "FETCH" SP sequence-set SP ("ALL" / "FULL" / + "FAST" / fetch-att / + "(" fetch-att *(SP fetch-att) ")") + [fetch-modifiers] + ;; modifies the original IMAP4 FETCH command to + ;; accept optional modifiers + + fetch-modifiers = SP "(" fetch-modifier *(SP fetch-modifier) ")" + + fetch-modifier = fetch-modifier-name [ SP fetch-modif-params ] + + fetch-modif-params = tagged-ext-val + ;; This non-terminal shows recommended syntax + ;; for future extensions. + + fetch-modifier-name = tagged-ext-label + + literal8 = "~{" number ["+"] "}" CRLF *OCTET + ;; A string that might contain NULs. + ;; <number> represents the number of OCTETs + ;; in the response string. + ;; The "+" is only allowed when both LITERAL+ and + ;; BINARY extensions are supported by the server. + + + + +Melnikov & Daboo Standards Track [Page 10] + +RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 + + + mailbox-data =/ Namespace-Response / + esearch-response + + Namespace = nil / "(" 1*Namespace-Descr ")" + + Namespace-Command = "NAMESPACE" + + Namespace-Descr = "(" string SP + (DQUOTE QUOTED-CHAR DQUOTE / nil) + *(Namespace-Response-Extension) ")" + + Namespace-Response-Extension = SP string SP + "(" string *(SP string) ")" + + Namespace-Response = "NAMESPACE" SP Namespace + SP Namespace SP Namespace + ;; This response is currently only allowed + ;; if the IMAP server supports [NAMESPACE]. + ;; The first Namespace is the Personal Namespace(s) + ;; The second Namespace is the Other Users' Namespace(s) + ;; The third Namespace is the Shared Namespace(s) + + rename = "RENAME" SP mailbox SP mailbox + [rename-params] + ;; Use of INBOX as a destination gives + ;; a NO error, unless rename-params + ;; is not empty. + + rename-params = SP "(" rename-param *( SP rename-param) ")" + + rename-param = rename-param-name [SP rename-param-value] + + rename-param-name = tagged-ext-label + + rename-param-value= tagged-ext-val + ;; This non-terminal shows recommended syntax + ;; for future extensions. + + + response-data = "*" SP response-payload CRLF + + response-payload= resp-cond-state / resp-cond-bye / + mailbox-data / message-data / capability-data + + search = "SEARCH" [search-return-opts] + SP search-program + + search-correlator = SP "(" "TAG" SP tag-string ")" + + + +Melnikov & Daboo Standards Track [Page 11] + +RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 + + + search-program = ["CHARSET" SP charset SP] + search-key *(SP search-key) + ;; CHARSET argument to SEARCH MUST be + ;; registered with IANA. + + search-return-data = search-modifier-name SP search-return-value + ;; Note that not every SEARCH return option + ;; is required to have the corresponding + ;; ESEARCH return data. + + search-return-opts = SP "RETURN" SP "(" [search-return-opt + *(SP search-return-opt)] ")" + + search-return-opt = search-modifier-name [SP search-mod-params] + + search-return-value = tagged-ext-val + ;; Data for the returned search option. + ;; A single "nz-number"/"number" value + ;; can be returned as an atom (i.e., without + ;; quoting). A sequence-set can be returned + ;; as an atom as well. + + search-modifier-name = tagged-ext-label + + search-mod-params = tagged-ext-val + ;; This non-terminal shows recommended syntax + ;; for future extensions. + + + select = "SELECT" SP mailbox [select-params] + ;; modifies the original IMAP SELECT command to + ;; accept optional parameters + + select-params = SP "(" select-param *(SP select-param) ")" + + select-param = select-param-name [SP select-param-value] + ;; a parameter to SELECT may contain one or + ;; more atoms and/or strings and/or lists. + + select-param-name= tagged-ext-label + + select-param-value= tagged-ext-val + ;; This non-terminal shows recommended syntax + ;; for future extensions. + + + status-att-list = status-att-val *(SP status-att-val) + ;; Redefines status-att-list from RFC 3501. + + + +Melnikov & Daboo Standards Track [Page 12] + +RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 + + + ;; status-att-val is defined in RFC 3501 errata + + status-att-val = ("MESSAGES" SP number) / + ("RECENT" SP number) / + ("UIDNEXT" SP nz-number) / + ("UIDVALIDITY" SP nz-number) / + ("UNSEEN" SP number) + ;; Extensions to the STATUS responses + ;; should extend this production. + ;; Extensions should use the generic + ;; syntax defined by tagged-ext. + + store = "STORE" SP sequence-set [store-modifiers] + SP store-att-flags + ;; extend [IMAP4] STORE command syntax + ;; to allow for optional store-modifiers + + store-modifiers = SP "(" store-modifier *(SP store-modifier) + ")" + + store-modifier = store-modifier-name [SP store-modif-params] + + store-modif-params = tagged-ext-val + ;; This non-terminal shows recommended syntax + ;; for future extensions. + + store-modifier-name = tagged-ext-label + + tag-string = string + ;; tag of the command that caused + ;; the ESEARCH response, sent as + ;; a string. + + tagged-ext = tagged-ext-label SP tagged-ext-val + ;; recommended overarching syntax for + ;; extensions + + tagged-ext-label = tagged-label-fchar *tagged-label-char + ;; Is a valid RFC 3501 "atom". + + tagged-label-fchar = ALPHA / "-" / "_" / "." + + tagged-label-char = tagged-label-fchar / DIGIT / ":" + + + + + + + + +Melnikov & Daboo Standards Track [Page 13] + +RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 + + + tagged-ext-comp = astring / + tagged-ext-comp *(SP tagged-ext-comp) / + "(" tagged-ext-comp ")" + ;; Extensions that follow this general + ;; syntax should use nstring instead of + ;; astring when appropriate in the context + ;; of the extension. + ;; Note that a message set or a "number" + ;; can always be represented as an "atom". + ;; An URL should be represented as + ;; a "quoted" string. + + tagged-ext-simple = sequence-set / number + + tagged-ext-val = tagged-ext-simple / + "(" [tagged-ext-comp] ")" + +4. Security Considerations + + This document updates ABNF in RFCs 2088, 2342, 3501, 3502, and 3516. + The updated documents must be consulted for security considerations + for the extensions that they define. + + As a protocol gets more complex, parser bugs become more common + including buffer overflow, denial of service, and other common + security coding errors. To the extent that this document makes the + parser more complex, it makes this situation worse. To the extent + that this document makes the parser more consistent and thus simpler, + the situation is improved. The impact will depend on how many + deployed IMAP extensions are consistent with this document. + Implementers are encouraged to take care of these issues when + extending existing implementations. Future IMAP extensions should + strive for consistency and simplicity to the greatest extent + possible. + + Extensions to IMAP commands that are permitted in NOT AUTHENTICATED + state are more sensitive to these security issues due to the larger + possible attacker community prior to authentication, and the fact + that some IMAP servers run with elevated privileges in that state. + This document does not extend any commands permitted in NOT + AUTHENTICATED state. Future IMAP extensions to commands permitted in + NOT AUTHENTICATED state should favor simplicity over consistency or + extensibility. + + + + + + + + +Melnikov & Daboo Standards Track [Page 14] + +RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 + + +5. Normative References + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [IMAP4] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - + VERSION 4rev1", RFC 3501, March 2003. + + [ABNF] Crocker, D., Ed., and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", RFC 4234, October 2005. + + [CHARSET] Freed, N. and J. Postel, "IANA Charset Registration + Procedures", BCP 19, RFC 2978, October 2000. + + [MULTIAPPEND] Crispin, M., "Internet Message Access Protocol (IMAP) - + MULTIAPPEND Extension", RFC 3502, March 2003. + + [NAMESPACE] Gahrns, M. and C. Newman, "IMAP4 Namespace", RFC 2342, + May 1998. + + [LITERAL+] Myers, J., "IMAP4 non-synchronizing literals", RFC + 2088, January 1997. + + [BINARY] Nerenberg, L., "IMAP4 Binary Content Extension", RFC + 3516, April 2003. + +6. Acknowledgements + + This documents is based on ideas proposed by Pete Resnick, Mark + Crispin, Ken Murchison, Philip Guenther, Randall Gellens, and Lyndon + Nerenberg. + + However, all errors and omissions must be attributed to the authors + of the document. + + Thanks to Philip Guenther, Dave Cridland, Mark Crispin, Chris Newman, + Elwyn Davies, and Barry Leiba for comments and corrections. + + literal8 syntax was taken from RFC 3516. + + + + + + + + + + + + +Melnikov & Daboo Standards Track [Page 15] + +RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 + + +Authors' Addresses + + Alexey Melnikov + Isode Limited + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex, TW12 2BX + UK + + EMail: Alexey.Melnikov@isode.com + + + Cyrus Daboo + + EMail: cyrus@daboo.name + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Melnikov & Daboo Standards Track [Page 16] + +RFC 4466 Collected Extensions to IMAP4 ABNF April 2006 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2006). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is provided by the IETF + Administrative Support Activity (IASA). + + + + + + + +Melnikov & Daboo Standards Track [Page 17] + diff --git a/imap/docs/rfc/rfc4467.txt b/imap/docs/rfc/rfc4467.txt new file mode 100644 index 00000000..83b6516a --- /dev/null +++ b/imap/docs/rfc/rfc4467.txt @@ -0,0 +1,1011 @@ + + + + + + +Network Working Group M. Crispin +Request for Comments: 4467 University of Washington +Updates: 3501 May 2006 +Category: Standards Track + + + Internet Message Access Protocol (IMAP) - URLAUTH Extension + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2006). + +Abstract + + This document describes the URLAUTH extension to the Internet Message + Access Protocol (IMAP) (RFC 3501) and the IMAP URL Scheme (IMAPURL) + (RFC 2192). This extension provides a means by which an IMAP client + can use URLs carrying authorization to access limited message data on + the IMAP server. + + An IMAP server that supports this extension indicates this with a + capability name of "URLAUTH". + +1. Introduction + + In [IMAPURL], a URL of the form imap://fred@example.com/INBOX/;uid=20 + requires authorization as userid "fred". However, [IMAPURL] implies + that it only supports authentication and confuses the concepts of + authentication and authorization. + + The URLAUTH extension defines an authorization mechanism for IMAP + URLs to replace [IMAPURL]'s authentication-only mechanism. URLAUTH + conveys authorization in the URL string itself and reuses a portion + of the syntax of the [IMAPURL] authentication mechanism to convey the + authorization identity (which also defines the default namespace in + [IMAP]). + + The URLAUTH extension provides a means by which an authorized user of + an IMAP server can create URLAUTH-authorized IMAP URLs. A URLAUTH- + authorized URL conveys authorization (not authentication) to the data + + + +Crispin Standards Track [Page 1] + +RFC 4467 IMAP - URLAUTH Extension May 2006 + + + addressed by that URL. This URL can be used in another IMAP session + to access specific content on the IMAP server, without otherwise + providing authorization to any other data (such as other data in the + mailbox specified in the URL) owned by the authorizing user. + + Conceptually, a URLAUTH-authorized URL can be thought of as a "pawn + ticket" that carries no authentication information and can be + redeemed by whomever presents it. However, unlike a pawn ticket, + URLAUTH has optional mechanisms to restrict the usage of a URLAUTH- + authorized URL. Using these mechanisms, URLAUTH-authorized URLs can + be usable by: + + . anonymous (the "pawn ticket" model) + . authenticated users only + . a specific authenticated user only + . message submission acting on behalf of a specific user only + + There is also a mechanism for expiration. + + A URLAUTH-authorized URL can be used in the argument to the BURL + command in message composition, as described in [BURL], for such + purposes as allowing a client (with limited memory or other + resources) to submit a message forward or to resend from an IMAP + mailbox without requiring the client to fetch that message data. + + The URLAUTH is generated using an authorization mechanism name and an + authorization token, which is generated using a secret mailbox access + key. An IMAP client can request that the server generate and assign + a new mailbox access key (thus effectively revoking all current URLs + using URLAUTH with the old mailbox access key) but cannot set the + mailbox access key to a key of its own choosing. + +1.1. Conventions Used in this Document + + The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" + in this document are to be interpreted as defined in [KEYWORDS]. + + The formal syntax uses the Augmented Backus-Naur Form (ABNF) notation + including the core rules defined in Appendix A of [ABNF]. + + In examples, "C:" and "S:" indicate lines sent by the client and + server, respectively. If a single "C:" or "S:" label applies to + multiple lines, then the line breaks between those lines are for + editorial clarity only and are not part of the actual protocol + exchange. + + + + + + +Crispin Standards Track [Page 2] + +RFC 4467 IMAP - URLAUTH Extension May 2006 + + +2. Concepts + +2.1. URLAUTH + + The URLAUTH is a component, appended at the end of a URL, that + conveys authorization to access the data addressed by that URL. It + contains an authorized access identifier, an authorization mechanism + name, and an authorization token. The authorization token is + generated from the URL, the authorized access identifier, the + authorization mechanism name, and a mailbox access key. + +2.2. Mailbox Access Key + + The mailbox access key is a random string with at least 128 bits of + entropy. It is generated by software (not by the human user) and + MUST be unpredictable. + + Each user has a table of mailboxes and an associated mailbox access + key for each mailbox. Consequently, the mailbox access key is per- + user and per-mailbox. In other words, two users sharing the same + mailbox each have a different mailbox access key for that mailbox, + and each mailbox accessed by a single user also has a different + mailbox access key. + +2.3. Authorized Access Identifier + + The authorized access identifier restricts use of the URLAUTH + authorized URL to certain users authorized on the server, as + described in section 3. + +2.4. Authorization Mechanism + + The authorization mechanism is the algorithm by which the URLAUTH is + generated and subsequently verified, using the mailbox access key. + +2.4.1. INTERNAL Authorization Mechanism + + This specification defines the INTERNAL mechanism, which uses a token + generation algorithm of the server's choosing and does not involve + disclosure of the mailbox access key to the client. + + Note: The token generation algorithm chosen by the server + implementation should be modern and reasonably secure. At the + time of the writing of this document, an [HMAC] such as HMAC-SHA1 + is recommended. + + + + + + +Crispin Standards Track [Page 3] + +RFC 4467 IMAP - URLAUTH Extension May 2006 + + + If it becomes necessary to change the token generation algorithm + of the INTERNAL mechanism (e.g., because an attack against the + current algorithm has been discovered), all currently existing + URLAUTH-authorized URLs are invalidated by the change in + algorithm. Since this would be an unpleasant surprise to + applications that depend upon the validity of a URLAUTH-authorized + URL, and there is no good way to do a bulk update of existing + deployed URLs, it is best to avoid this situation by using a + secure algorithm as opposed to one that is "good enough". + + Server implementations SHOULD consider the possibility of changing + the algorithm. In some cases, it may be desirable to implement + the change of algorithm in a way that newly-generated tokens use + the new algorithm, but that for a limited period of time tokens + using either the new or old algorithm can be validated. + Consequently, the server SHOULD incorporate some means of + identifying the token generation algorithm within the token. + + Although this specification is extensible for other mechanisms, none + are defined in this document. In addition to the mechanism name + itself, other mechanisms may have mechanism-specific data, which is + to be interpreted according to the definition of that mechanism. + +2.5. Authorization Token + + The authorization token is a deterministic string of at least 128 + bits that an entity with knowledge of the secret mailbox access key + and URL authorization mechanism can use to verify the URL. + +3. IMAP URL Extensions + + [IMAPURL] is extended by allowing the addition of + ";EXPIRE=<datetime>" and ";URLAUTH=<access>:<mech>:<token>" to IMAP + URLs that refer to a specific message or message parts. + + The URLAUTH is comprised of ";URLAUTH=<access>:<mech>:<token>" and + MUST be at the end of the URL. + + URLAUTH does not apply to, and MUST NOT be used with, any IMAP URL + that refers to an entire IMAP server, a list of mailboxes, an entire + IMAP mailbox, or IMAP search results. + + When ";EXPIRE=<datetime>" is used, this indicates the latest date and + time that the URL is valid. After that date and time, the URL has + expired, and server implementations MUST reject the URL. If + ";EXPIRE=<datetime>" is not used, the URL has no expiration, but + still can be revoked as discussed below. + + + + +Crispin Standards Track [Page 4] + +RFC 4467 IMAP - URLAUTH Extension May 2006 + + + The URLAUTH takes the form ";URLAUTH=<access>:<mech>:<token>". It is + composed of three parts. The <access> portion provides the + authorized access identifiers, which may constrain the operations and + users that are permitted to use this URL. The <mech> portion + provides the authorization mechanism used by the IMAP server to + generate the authorization token that follows. The <token> portion + provides the authorization token. + + The "submit+" access identifier prefix, followed by a userid, + indicates that only a userid authorized as a message submission + entity on behalf of the specified userid is permitted to use this + URL. The IMAP server does not validate the specified userid but does + validate that the IMAP session has an authorization identity that is + authorized as a message submission entity. The authorized message + submission entity MUST validate the userid prior to contacting the + IMAP server. + + The "user+" access identifier prefix, followed by a userid, indicates + that use of this URL is limited to IMAP sessions that are logged in + as the specified userid (that is, have authorization identity as that + userid). + + Note: If a SASL mechanism that provides both authorization and + authentication identifiers is used to authenticate to the IMAP + server, the "user+" access identifier MUST match the authorization + identifier. + + The "authuser" access identifier indicates that use of this URL is + limited to IMAP sessions that are logged in as an authorized user + (that is, have authorization identity as an authorized user) of that + IMAP server. Use of this URL is prohibited to anonymous IMAP + sessions. + + The "anonymous" access identifier indicates that use of this URL is + not restricted by session authorization identity; that is, any IMAP + session in authenticated or selected state (as defined in [IMAP]), + including anonymous sessions, may issue a URLFETCH using this URL. + + The authorization token is represented as an ASCII-encoded + hexadecimal string, which is used to authorize the URL. The length + and the calculation of the authorization token depends upon the + mechanism used; but, in all cases, the authorization token is at + least 128 bits (and therefore at least 32 hexadecimal digits). + + + + + + + + +Crispin Standards Track [Page 5] + +RFC 4467 IMAP - URLAUTH Extension May 2006 + + +4. Discussion of URLAUTH Authorization Issues + + In [IMAPURL], the userid before the "@" in the URL has two purposes: + + 1) It provides context for user-specific mailbox paths such as + "INBOX". + + 2) It specifies that resolution of the URL requires logging in as + that user and limits use of that URL to only that user. + + An obvious limitation of using the same field for both purposes is + that the URL can only be resolved by the mailbox owner. + + URLAUTH overrides the second purpose of the userid in the IMAP URL + and by default permits the URL to be resolved by any user permitted + by the access identifier. + + The "user+<userid>" access identifier limits resolution of that URL + to a particular userid, whereas the "submit+<userid>" access + identifier is more general and simply requires that the session be + authorized by a user that has been granted a "submit" role within the + authentication system. Use of either of these access identifiers + makes it impossible for an attacker, spying on the session, to use + the same URL, either directly or by submission to a message + submission entity. + + The "authuser" and "anonymous" access identifiers do not have this + level of protection and should be used with caution. These access + identifiers are primarily useful for public export of data from an + IMAP server, without requiring that it be copied to a web or + anonymous FTP server. Refer to the Security Considerations for more + details. + +5. Generation of URLAUTH-Authorized URLs + + A URLAUTH-authorized URL is generated from an initial URL as follows: + + An initial URL is built, ending with ";URLAUTH=<access>" but without + the ":<mech>:<token>" components. An authorization mechanism is + selected and used to calculate the authorization token, with the + initial URL as the data and a secret known to the IMAP server as the + key. The URLAUTH-authorized URL is generated by taking the initial + URL and appending ":", the URL authorization mechanism name, ":", and + the ASCII-encoded hexadecimal representation of the authorization + token. + + + + + + +Crispin Standards Track [Page 6] + +RFC 4467 IMAP - URLAUTH Extension May 2006 + + + Note: ASCII-encoded hexadecimal is used instead of BASE64 because + a BASE64 representation may have "=" padding characters, which + would be problematic in a URL. + + In the INTERNAL mechanism, the mailbox access key for that mailbox is + the secret known to the IMAP server, and a server-selected algorithm + is used as described in section 2.4.1. + +6. Validation of URLAUTH-authorized URLs + + A URLAUTH-authorized URL is validated as follows: + + The URL is split at the ":" that separates "<access>" from + "<mech>:<token>" in the ";URLAUTH=<access>:<mech>:<token>" portion of + the URL. The "<mech>:<token>" portion is first parsed and saved as + the authorization mechanism and the authorization token. The URL is + truncated, discarding the ":" described above, to create a "rump URL" + (the URL minus the ":" and the "<mech>:<token>" portion). The rump + URL is then analyzed to identify the mailbox. + + If the mailbox cannot be identified, an authorization token is + calculated on the rump URL, using random "plausible" keys (selected + by the server) as needed, before returning a validation failure. + This prevents timing attacks aimed at identifying mailbox names. + + If the mailbox can be identified, the authorization token is + calculated on the rump URL and a secret known to the IMAP server + using the given URL authorization mechanism. Validation is + successful if, and only if, the calculated authorization token for + that mechanism matches the authorization token supplied in + ";URLAUTH=<access>:<mech>:<token>". + + Removal of the ":<mech>:<token>" portion of the URL MUST be the only + operation applied to the URLAUTH-authorized URL to get the rump URL. + In particular, URL percent escape decoding and case-folding + (including to the domain part of the URL) MUST NOT occur. + + In the INTERNAL mechanism, the mailbox access key for that mailbox is + used as the secret known to the IMAP server, and the same server- + selected algorithm used for generating URLs is used to calculate the + authorization token for verification. + + + + + + + + + + +Crispin Standards Track [Page 7] + +RFC 4467 IMAP - URLAUTH Extension May 2006 + + +7. Additional Commands + + These commands are extensions to the [IMAP] base protocol. + + The section headings of these commands are intended to correspond + with where they would be located in the base protocol document if + they were part of that document. + +BASE.6.3.RESETKEY. RESETKEY Command + + Arguments: optional mailbox name + optional mechanism name(s) + + Responses: none other than in result + + Result: OK - RESETKEY completed, URLMECH containing new data + NO - RESETKEY error: can't change key of that mailbox + BAD - command unknown or arguments invalid + + The RESETKEY command has two forms. + + The first form accepts a mailbox name as an argument and generates a + new mailbox access key for the given mailbox in the user's mailbox + access key table, replacing any previous mailbox access key (and + revoking any URLs that were authorized with a URLAUTH using that key) + in that table. By default, the mailbox access key is generated for + the INTERNAL mechanism; other mechanisms can be specified with the + optional mechanism argument. + + The second form, with no arguments, removes all mailbox access keys + in the user's mailbox access key table, revoking all URLs currently + authorized using URLAUTH by the user. + + Any current IMAP session logged in as the user that has the mailbox + selected will receive an untagged OK response with the URLMECH status + response code (see section BASE.7.1.URLMECH for more details about + the URLMECH status response code). + + Example: + + C: a31 RESETKEY + S: a31 OK All keys removed + C: a32 RESETKEY INBOX + S: a32 OK [URLMECH INTERNAL] mechs + C: a33 RESETKEY INBOX XSAMPLE + S: a33 OK [URLMECH INTERNAL XSAMPLE=P34OKhO7VEkCbsiYY8rGEg==] done + + + + + +Crispin Standards Track [Page 8] + +RFC 4467 IMAP - URLAUTH Extension May 2006 + + +BASE.6.3.GENURLAUTH. GENURLAUTH Command + + Argument: one or more URL/mechanism pairs + + Response: untagged response: GENURLAUTH + + Result: OK - GENURLAUTH completed + NO - GENURLAUTH error: can't generate a URLAUTH + BAD - command unknown or arguments invalid + + The GENURLAUTH command requests that the server generate a URLAUTH- + authorized URL for each of the given URLs using the given URL + authorization mechanism. + + The server MUST validate each supplied URL as follows: + + (1) The mailbox component of the URL MUST refer to an existing + mailbox. + + (2) The server component of the URL MUST contain a valid userid + that identifies the owner of the mailbox access key table that + will be used to generate the URLAUTH-authorized URL. As a + consequence, the iserver rule of [IMAPURL] is modified so that + iuserauth is mandatory. + + Note: the server component of the URL is generally the + logged in userid and server. If not, then the logged in + userid and server MUST have owner-type access to the + mailbox access key table owned by the userid and server + indicated by the server component of the URL. + + (3) There is a valid access identifier that, in the case of + "submit+" and "user+", will contain a valid userid. This + userid is not necessarily the same as the owner userid + described in (2). + + (4) The server MAY also verify that the iuid and/or isection + components (if present) are valid. + + If any of the above checks fail, the server MUST return a tagged BAD + response with the following exception. If an invalid userid is + supplied as the mailbox access key owner and/or as part of the access + identifier, the server MAY issue a tagged OK response with a + generated mailbox key that always fails validation when used with a + URLFETCH command. This exception prevents an attacker from + validating userids. + + + + + +Crispin Standards Track [Page 9] + +RFC 4467 IMAP - URLAUTH Extension May 2006 + + + If there is currently no mailbox access key for the given mailbox in + the owner's mailbox access key table, one is automatically generated. + That is, it is not necessary to use RESETKEY prior to first-time use + of GENURLAUTH. + + If the command is successful, a GENURLAUTH response code is returned + listing the requested URLs as URLAUTH-authorized URLs. + + Examples: + + C: a775 GENURLAUTH "imap://joe@example.com/INBOX/;uid=20/ + ;section=1.2" INTERNAL + S: a775 BAD missing access identifier in supplied URL + C: a776 GENURLAUTH "imap://example.com/Shared/;uid=20/ + ;section=1.2;urlauth=submit+fred" INTERNAL + S: a776 BAD missing owner username in supplied URL + C: a777 GENURLAUTH "imap://joe@example.com/INBOX/;uid=20/ + ;section=1.2;urlauth=submit+fred" INTERNAL + S: * GENURLAUTH "imap://joe@example.com/INBOX/;uid=20/;section=1.2 + ;urlauth=submit+fred:internal:91354a473744909de610943775f92038" + S: a777 OK GENURLAUTH completed + +BASE.6.3.URLFETCH. URLFETCH Command + + Argument: one or more URLs + + Response: untagged response: URLFETCH + + Result: OK - urlfetch completed + NO - urlfetch failed due to server internal error + BAD - command unknown or arguments invalid + + The URLFETCH command requests that the server return the text data + associated with the specified IMAP URLs, as described in [IMAPURL] + and extended by this document. The data is returned for all + validated URLs, regardless of whether or not the session would + otherwise be able to access the mailbox containing that data via + SELECT or EXAMINE. + + Note: This command does not require that the URL refer to the + selected mailbox; nor does it require that any mailbox be + selected. It also does not in any way interfere with any selected + mailbox. + + + + + + + + +Crispin Standards Track [Page 10] + +RFC 4467 IMAP - URLAUTH Extension May 2006 + + + The URLFETCH command effectively executes with the access of the + userid in the server component of the URL (which is generally the + userid that issued the GENURLAUTH). By itself, the URLAUTH does NOT + grant access to the data; once validated, it grants whatever access + to the data is held by the userid in the server component of the URL. + That access may have changed since the GENURLAUTH was done. + + The URLFETCH command MUST return an untagged URLFETCH response and a + tagged OK response to any URLFETCH command that is syntactically + valid. A NO response indicates a server internal failure that may be + resolved on later retry. + + Note: The possibility of a NO response is to accommodate + implementations that would otherwise have to issue an untagged BYE + with a fatal error due to an inability to respond to a valid + request. In an ideal world, a server SHOULD NOT issue a NO + response. + + The server MUST return NIL for any IMAP URL that references an entire + IMAP server, a list of mailboxes, an entire IMAP mailbox, or IMAP + search results. + + Example: + + Note: For clarity, this example uses the LOGIN command, which + SHOULD NOT be used over a non-encrypted communication path. + + This example is of a submit server, obtaining a message segment + for a message that it has already validated was submitted by + "fred". + + S: * OK [CAPABILITY IMAP4REV1 URLAUTH] example.com IMAP server + C: a001 LOGIN submitserver secret + S: a001 OK submitserver logged in + C: a002 URLFETCH "imap://joe@example.com/INBOX/;uid=20/ + ;section=1.2;urlauth=submit+fred:internal + :91354a473744909de610943775f92038" + S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/;section=1.2 + ;urlauth=submit+fred:internal + :91354a473744909de610943775f92038" {28} + S: Si vis pacem, para bellum. + S: + S: a002 OK URLFETCH completed + + + + + + + + +Crispin Standards Track [Page 11] + +RFC 4467 IMAP - URLAUTH Extension May 2006 + + +8. Additional Responses + + These responses are extensions to the [IMAP] base protocol. + + The section headings of these responses are intended to correspond + with where they would be located in the base protocol document if + they were part of that document. + +BASE.7.1.URLMECH. URLMECH Status Response Code + + The URLMECH status response code is followed by a list of URL + authorization mechanism names. Mechanism names other than INTERNAL + may be appended with an "=" and BASE64-encoded form of mechanism- + specific data. + + This status response code is returned in an untagged OK response in + response to a RESETKEY, SELECT, or EXAMINE command. In the case of + the RESETKEY command, this status response code can be sent in the + tagged OK response instead of requiring a separate untagged OK + response. + + Example: + + C: a33 RESETKEY INBOX XSAMPLE + S: a33 OK [URLMECH INTERNAL XSAMPLE=P34OKhO7VEkCbsiYY8rGEg==] done + + In this example, the server supports the INTERNAL mechanism and an + experimental mechanism called XSAMPLE, which also holds some + mechanism-specific data (the name "XSAMPLE" is for illustrative + purposes only). + +BASE.7.4.GENURLAUTH. GENURLAUTH Response + + Contents: One or more URLs + + The GENURLAUTH response returns the URLAUTH-authorized URL(s) + requested by a GENURLAUTH command. + + Example: + + C: a777 GENURLAUTH "imap://joe@example.com/INBOX/;uid=20/ + ;section=1.2;urlauth=submit+fred" INTERNAL + S: * GENURLAUTH "imap://joe@example.com/INBOX/;uid=20/;section=1.2 + ;urlauth=submit+fred:internal:91354a473744909de610943775f92038" + S: a777 OK GENURLAUTH completed + + + + + + +Crispin Standards Track [Page 12] + +RFC 4467 IMAP - URLAUTH Extension May 2006 + + +BASE.7.4.URLFETCH. URLFETCH Response + + Contents: One or more URL/nstring pairs + + The URLFETCH response returns the message text data associated with + one or more IMAP URLs, as described in [IMAPURL] and extended by this + document. This response occurs as the result of a URLFETCH command. + + The returned data string is NIL if the URL is invalid for any reason + (including validation failure). If the URL is valid, but the IMAP + fetch of the body part returned NIL (this should not happen), the + returned data string should be the empty string ("") and not NIL. + + Note: This command does not require that the URL refer to the + selected mailbox; nor does it require that any mailbox be + selected. It also does not in any way interfere with any selected + mailbox. + + Example: + + C: a002 URLFETCH "imap://joe@example.com/INBOX/;uid=20/ + ;section=1.2;urlauth=submit+fred:internal + :91354a473744909de610943775f92038" + S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/;section=1.2 + ;urlauth=submit+fred:internal + :91354a473744909de610943775f92038" {28} + S: Si vis pacem, para bellum. + S: + S: a002 OK URLFETCH completed + +9. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [ABNF]. + + The following modifications are made to the Formal Syntax in [IMAP]: + +resetkey = "RESETKEY" [SP mailbox *(SP mechanism)] + +capability =/ "URLAUTH" + +command-auth =/ resetkey / genurlauth / urlfetch + +resp-text-code =/ "URLMECH" SP "INTERNAL" *(SP mechanism ["=" base64]) + +genurlauth = "GENURLAUTH" 1*(SP url-rump SP mechanism) + +genurlauth-data = "*" SP "GENURLAUTH" 1*(SP url-full) + + + +Crispin Standards Track [Page 13] + +RFC 4467 IMAP - URLAUTH Extension May 2006 + + +url-full = astring + ; contains authimapurlfull as defined below + +url-rump = astring + ; contains authimapurlrump as defined below + +urlfetch = "URLFETCH" 1*(SP url-full) + +urlfetch-data = "*" SP "URLFETCH" 1*(SP url-full SP nstring) + + The following extensions are made to the Formal Syntax in [IMAPURL]: + +authimapurl = "imap://" enc-user [iauth] "@" hostport "/" + imessagepart + ; replaces "imapurl" and "iserver" rules for + ; URLAUTH authorized URLs + +authimapurlfull = authimapurl iurlauth + +authimapurlrump = authimapurl iurlauth-rump + +enc-urlauth = 32*HEXDIG + +enc-user = 1*achar + ; same as "enc_user" in RFC 2192 + +iurlauth = iurlauth-rump ":" mechanism ":" enc-urlauth + +iurlauth-rump = [expire] ";URLAUTH=" access + +access = ("submit+" enc-user) / ("user+" enc-user) / + "authuser" / "anonymous" + +expire = ";EXPIRE=" date-time + ; date-time defined in [DATETIME] + +mechanism = "INTERNAL" / 1*(ALPHA / DIGIT / "-" / ".") + ; case-insensitive + ; new mechanisms MUST be registered with IANA + + + + + + + + + + + + +Crispin Standards Track [Page 14] + +RFC 4467 IMAP - URLAUTH Extension May 2006 + + +10. Security Considerations + + Security considerations are discussed throughout this memo. + + The mailbox access key SHOULD have at least 128 bits of entropy + (refer to [RANDOM] for more details) and MUST be unpredictable. + + The server implementation of the INTERNAL mechanism SHOULD consider + the possibility of needing to change the token generation algorithm, + and SHOULD incorporate some means of identifying the token generation + algorithm within the token. + + The URLMECH status response code may expose sensitive data in the + mechanism-specific data for mechanisms other than INTERNAL. A server + implementation MUST implement a configuration that will not return a + URLMECH status response code unless some mechanism is provided that + protects the session from snooping, such as a TLS or SASL security + layer that provides confidentiality protection. + + The calculation of an authorization token with a "plausible" key if + the mailbox can not be identified is necessary to avoid attacks in + which the server is probed to see if a particular mailbox exists on + the server by measuring the amount of time taken to reject a known + bad name versus some other name. + + To protect against a computational denial-of-service attack, a server + MAY impose progressively longer delays on multiple URL requests that + fail validation. + + The decision to use the "authuser" access identifier should be made + with caution. An "authuser" access identifier can be used by any + authorized user of the IMAP server; therefore, use of this access + identifier should be limited to content that may be disclosed to any + authorized user of the IMAP server. + + The decision to use the "anonymous" access identifier should be made + with extreme caution. An "anonymous" access identifier can be used + by anyone; therefore, use of this access identifier should be limited + to content that may be disclosed to anyone. Many IMAP servers do not + permit anonymous access; in this case, the "anonymous" access + identifier is equivalent to "authuser", but this MUST NOT be relied + upon. + + Although this specification does not prohibit the theoretical + capability to generate a URL with a server component other than the + logged in userid and server, this capability should only be provided + + + + + +Crispin Standards Track [Page 15] + +RFC 4467 IMAP - URLAUTH Extension May 2006 + + + when the logged in userid/server has been authorized as equivalent to + the server component userid/server, or otherwise has access to that + userid/server mailbox access key table. + +11. IANA Considerations + + This document constitutes registration of the URLAUTH capability in + the imap4-capabilities registry. + + URLAUTH authorization mechanisms are registered by publishing a + standards track or IESG-approved experimental RFC. The registry is + currently located at: + +http://www.iana.org/assignments/urlauth-authorization-mechanism-registry + + This registry is case-insensitive. + + This document constitutes registration of the INTERNAL URLAUTH + authorization mechanism. + + IMAP URLAUTH Authorization Mechanism Registry + + Mechanism Name Reference + -------------- --------- + INTERNAL [RFC4467] + + + + + + + + + + + + + + + + + + + + + + + + + + +Crispin Standards Track [Page 16] + +RFC 4467 IMAP - URLAUTH Extension May 2006 + + +12. Normative References + + [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 4234, October 2005. + + [BURL] Newman, C., "Message Submission BURL Extension", RFC 4468, + May 2006. + + [DATETIME] Klyne, G. and C. Newman, "Date and Time on the Internet: + Timestamps", RFC 3339, July 2002. + + [IMAP] Crispin, M., "Internet Message Access Protocol - Version + 4rev1", RFC 3501, March 2003. + + [IMAPURL] Newman, C., "IMAP URL Scheme", RFC 2192, September 1997. + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + +13. Informative References + + [HMAC] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- + Hashing for Message Authentication", RFC 2104, February + 1997. + + [RANDOM] Eastlake, D., 3rd, Schiller, J., and S. Crocker, + "Randomness Requirements for Security", BCP 106, RFC 4086, + June 2005. + +Author's Address + + Mark R. Crispin + Networks and Distributed Computing + University of Washington + 4545 15th Avenue NE + Seattle, WA 98105-4527 + + Phone: (206) 543-5762 + EMail: MRC@CAC.Washington.EDU + + + + + + + + + + + + +Crispin Standards Track [Page 17] + +RFC 4467 IMAP - URLAUTH Extension May 2006 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2006). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is provided by the IETF + Administrative Support Activity (IASA). + + + + + + + +Crispin Standards Track [Page 18] + diff --git a/imap/docs/rfc/rfc4468.txt b/imap/docs/rfc/rfc4468.txt new file mode 100644 index 00000000..b16dcb4e --- /dev/null +++ b/imap/docs/rfc/rfc4468.txt @@ -0,0 +1,787 @@ + + + + + + +Network Working Group C. Newman +Request for Comments: 4468 Sun Microsystems +Updates: 3463 May 2006 +Category: Standards Track + + + Message Submission BURL Extension + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2006). + +Abstract + + The submission profile of Simple Mail Transfer Protocol (SMTP) + provides a standard way for an email client to submit a complete + message for delivery. This specification extends the submission + profile by adding a new BURL command that can be used to fetch + submission data from an Internet Message Access Protocol (IMAP) + server. This permits a mail client to inject content from an IMAP + server into the SMTP infrastructure without downloading it to the + client and uploading it back to the server. + + + + + + + + + + + + + + + + + + + + + +Newman Standards Track [Page 1] + +RFC 4468 Message Submission BURL Extension May 2006 + + +Table of Contents + + 1. Introduction ....................................................2 + 2. Conventions Used in This Document ...............................2 + 3. BURL Submission Extension .......................................3 + 3.1. SMTP Submission Extension Registration .....................3 + 3.2. BURL Transaction ...........................................3 + 3.3. The BURL IMAP Options ......................................4 + 3.4. Examples ...................................................5 + 3.5. Formal Syntax ..............................................6 + 4. 8-Bit and Binary ................................................7 + 5. Updates to RFC 3463 .............................................7 + 6. Response Codes ..................................................7 + 7. IANA Considerations .............................................9 + 8. Security Considerations .........................................9 + 9. References .....................................................11 + 9.1. Normative References ......................................11 + 9.2. Informative References ....................................12 + Appendix A. Acknowledgements .....................................13 + +1. Introduction + + This specification defines an extension to the standard Message + Submission [RFC4409] protocol to permit data to be fetched from an + IMAP server at message submission time. This MAY be used in + conjunction with the CHUNKING [RFC3030] mechanism so that chunks of + the message can come from an external IMAP server. This provides the + ability to forward an email message without first downloading it to + the client. + +2. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" + in this document are to be interpreted as defined in "Key words for + use in RFCs to Indicate Requirement Levels" [RFC2119]. + + The formal syntax uses the Augmented Backus-Naur Form (ABNF) + [RFC4234] notation including the core rules defined in Appendix B of + RFC 4234. + + + + + + + + + + + + +Newman Standards Track [Page 2] + +RFC 4468 Message Submission BURL Extension May 2006 + + +3. BURL Submission Extension + + This section defines the BURL submission extension. + +3.1. SMTP Submission Extension Registration + + 1. The name of this submission extension is "BURL". This extends + the Message Submission protocol on port 587 and MUST NOT be + advertised by a regular SMTP [RFC2821] server on port 25 that + acts as a relay for incoming mail from other SMTP relays. + + 2. The EHLO keyword value associated with the extension is "BURL". + + 3. The BURL EHLO keyword will have zero or more arguments. The only + argument defined at this time is the "imap" argument, which MUST + be present in order to use IMAP URLs with BURL. Clients MUST + ignore other arguments after the BURL EHLO keyword unless they + are defined by a subsequent IETF standards track specification. + The arguments that appear after the BURL EHLO keyword may change + subsequent to the use of SMTP AUTH [RFC2554], so a server that + advertises BURL with no arguments prior to authentication + indicates that BURL is supported but authentication is required + to use it. + + 4. This extension adds the BURL SMTP verb. This verb is used as a + replacement for the DATA command and is only permitted during a + mail transaction after at least one successful RCPT TO. + +3.2. BURL Transaction + + A simple BURL transaction will consist of MAIL FROM, one or more RCPT + TO headers, and a BURL command with the "LAST" tag. The BURL command + will include an IMAP URL pointing to a fully formed message ready for + injection into the SMTP infrastructure. If PIPELINING [RFC2920] is + advertised, the client MAY send the entire transaction in one round + trip. If no valid RCPT TO address is supplied, the BURL command will + simply fail, and no resolution of the BURL URL argument will be + performed. If at least one valid RCPT TO address is supplied, then + the BURL URL argument will be resolved before the server responds to + the command. + + A more sophisticated BURL transaction MAY occur when the server also + advertises CHUNKING [RFC3030]. In this case, the BURL and BDAT + commands may be interleaved until one of them terminates the + transaction with the "LAST" argument. If PIPELINING [RFC2920] is + also advertised, then the client may pipeline the entire transaction + in one round-trip. However, it MUST wait for the results of the + "LAST" BDAT or BURL command prior to initiating a new transaction. + + + +Newman Standards Track [Page 3] + +RFC 4468 Message Submission BURL Extension May 2006 + + + The BURL command directs the server to fetch the data object to which + the URL refers and include it in the message. If the URL fetch + fails, the server will fail the entire transaction. + +3.3. The BURL IMAP Options + + When "imap" is present in the space-separated list of arguments + following the BURL EHLO keyword, it indicates that the BURL command + supports the URLAUTH [RFC4467] extended form of IMAP URLs [RFC2192] + and that the submit server is configured with the necessary + credentials to resolve "urlauth=submit+" IMAP URLs for the submit + server's domain. + + Subsequent to a successful SMTP AUTH command, the submission server + MAY indicate a prearranged trust relationship with a specific IMAP + server by including a BURL EHLO keyword argument of the form + "imap://imap.example.com". In this case, the submission server will + permit a regular IMAP URL referring to messages or parts of messages + on imap.example.com that the user who authenticated to the submit + server can access. Note that this form does not imply that the + submit server supports URLAUTH URLs; the submit server must advertise + both "imap" and "imap://imap.example.com" to indicate support for + both extended and non-extended URL forms. + + When the submit server connects to the IMAP server, it acts as an + IMAP client and thus is subject to both the mandatory-to-implement + IMAP capabilities in Section 6.1.1 of RFC 3501, and the security + considerations in Section 11 of RFC 3501. Specifically, this + requires that the submit server implement a configuration that uses + STARTTLS followed by SASL PLAIN [SASL-PLAIN] to authenticate to the + IMAP server. + + When the submit server resolves a URLAUTH IMAP URL, it uses submit + server credentials when authenticating to the IMAP server. The + authentication identity and password used for submit credentials MUST + be configurable. The string "submit" is suggested as a default value + for the authentication identity, with no default for the password. + Typically, the authorization identity is empty in this case; thus the + IMAP server will derive the authorization identity from the + authentication identity. If the IMAP URL uses the "submit+" access + identifier prefix, the submit server MUST refuse the BURL command + unless the userid in the URL's <access> token matches the submit + client's authorization identity. + + When the submit server resolves a regular IMAP URL, it uses the + submit client's authorization identity when authenticating to the + IMAP server. If both the submit client and the submit server's + embedded IMAP client use SASL PLAIN (or the equivalent), the submit + + + +Newman Standards Track [Page 4] + +RFC 4468 Message Submission BURL Extension May 2006 + + + server SHOULD forward the client's credentials if and only if the + submit server knows that the IMAP server is in the same + administrative domain. If the submit server supports SASL mechanisms + other than PLAIN, it MUST implement a configuration in which the + submit server's embedded IMAP client uses STARTTLS and SASL PLAIN + with the submit server's authentication identity and password (for + the respective IMAP server) and the submit client's authorization + identity. + +3.4. Examples + + In examples, "C:" and "S:" indicate lines sent by the client and + server, respectively. If a single "C:" or "S:" label applies to + multiple lines, then the line breaks between those lines are for + editorial clarity only and are not part of the actual protocol + exchange. + + Two successful submissions (without and with pipelining) follow: + + <SSL/TLS encryption layer negotiated> + C: EHLO potter.example.com + S: 250-owlry.example.com + S: 250-8BITMIME + S: 250-BURL imap + S: 250-AUTH PLAIN + S: 250-DSN + S: 250 ENHANCEDSTATUSCODES + C: AUTH PLAIN aGFycnkAaGFycnkAYWNjaW8= + S: 235 2.7.0 PLAIN authentication successful. + C: MAIL FROM:<harry@gryffindor.example.com> + S: 250 2.5.0 Address Ok. + C: RCPT TO:<ron@gryffindor.example.com> + S: 250 2.1.5 ron@gryffindor.example.com OK. + C: BURL imap://harry@gryffindor.example.com/outbox + ;uidvalidity=1078863300/;uid=25;urlauth=submit+harry + :internal:91354a473744909de610943775f92038 LAST + S: 250 2.5.0 Ok. + + <SSL/TLS encryption layer negotiated> + C: EHLO potter.example.com + S: 250-owlry.example.com + S: 250-8BITMIME + S: 250-PIPELINING + S: 250-BURL imap + S: 250-AUTH PLAIN + S: 250-DSN + S: 250 ENHANCEDSTATUSCODES + C: AUTH PLAIN aGFycnkAaGFycnkAYWNjaW8= + + + +Newman Standards Track [Page 5] + +RFC 4468 Message Submission BURL Extension May 2006 + + + C: MAIL FROM:<harry@gryffindor.example.com> + C: RCPT TO:<ron@gryffindor.example.com> + C: BURL imap://harry@gryffindor.example.com/outbox + ;uidvalidity=1078863300/;uid=25;urlauth=submit+harry + :internal:91354a473744909de610943775f92038 LAST + S: 235 2.7.0 PLAIN authentication successful. + S: 250 2.5.0 Address Ok. + S: 250 2.1.5 ron@gryffindor.example.com OK. + S: 250 2.5.0 Ok. + + Note that PIPELINING of the AUTH command is only permitted if the + selected mechanism can be completed in one round trip, a client + initial response is provided, and no SASL security layer is + negotiated. This is possible for PLAIN and EXTERNAL, but not for + most other SASL mechanisms. + + Some examples of failure cases: + + C: MAIL FROM:<harry@gryffindor.example.com> + C: RCPT TO:<malfoy@slitherin.example.com> + C: BURL imap://harry@gryffindor.example.com/outbox + ;uidvalidity=1078863300/;uid=25;urlauth=submit+harry + :internal:91354a473744909de610943775f92038 LAST + S: 250 2.5.0 Address Ok. + S: 550 5.7.1 Relaying not allowed: malfoy@slitherin.example.com + S: 554 5.5.0 No recipients have been specified. + + C: MAIL FROM:<harry@gryffindor.example.com> + C: RCPT TO:<ron@gryffindor.example.com> + C: BURL imap://harry@gryffindor.example.com/outbox + ;uidvalidity=1078863300/;uid=25;urlauth=submit+harry + :internal:71354a473744909de610943775f92038 LAST + S: 250 2.5.0 Address Ok. + S: 250 2.1.5 ron@gryffindor.example.com OK. + S: 554 5.7.0 IMAP URL authorization failed + +3.5. Formal Syntax + + The following syntax specification inherits ABNF [RFC4234] and + Uniform Resource Identifiers [RFC3986]. + + burl-param = "imap" / ("imap://" authority) + ; parameter to BURL EHLO keyword + + burl-cmd = "BURL" SP absolute-URI [SP end-marker] CRLF + + end-marker = "LAST" + + + + +Newman Standards Track [Page 6] + +RFC 4468 Message Submission BURL Extension May 2006 + + +4. 8-Bit and Binary + + A submit server that advertises BURL MUST also advertise 8BITMIME + [RFC1652] and perform the down conversion described in that + specification on the resulting complete message if 8-bit data is + received with the BURL command and passed to a 7-bit server. If the + URL argument to BURL refers to binary data, then the submit server + MAY refuse the command or down convert as described in Binary SMTP + [RFC3030]. + + The Submit server MAY refuse to accept a BURL command or combination + of BURL and BDAT commands that result in un-encoded 8-bit data in + mail or MIME [RFC2045] headers. Alternatively, the server MAY accept + such data and down convert to MIME header encoding [RFC2047]. + +5. Updates to RFC 3463 + + SMTP or Submit servers that advertise ENHANCEDSTATUSCODES [RFC2034] + use enhanced status codes defined in RFC 3463 [RFC3463]. The BURL + extension introduces new error cases that that RFC did not consider. + The following additional enhanced status codes are defined by this + specification: + + X.6.6 Message content not available + + The message content could not be fetched from a remote system. + This may be useful as a permanent or persistent temporary + notification. + + X.7.8 Trust relationship required + + The submission server requires a configured trust relationship + with a third-party server in order to access the message content. + +6. Response Codes + + This section includes example response codes to the BURL command. + Other text may be used with the same response codes. This list is + not exhaustive, and BURL clients MUST tolerate any valid SMTP + response code. Most of these examples include the appropriate + enhanced status code [RFC3463]. + + 554 5.5.0 No recipients have been specified + + This response code occurs when BURL is used (for example, with + PIPELINING) and all RCPT TOs failed. + + + + + +Newman Standards Track [Page 7] + +RFC 4468 Message Submission BURL Extension May 2006 + + + 503 5.5.0 Valid RCPT TO required before BURL + + This response code is an alternative to the previous one when BURL + is used (for example, with PIPELINING) and all RCPT TOs failed. + + 554 5.6.3 Conversion required but not supported + + This response code occurs when the URL points to binary data and + the implementation does not support down conversion to base64. + This can also be used if the URL points to message data with 8-bit + content in headers and the server does not down convert such + content. + + 554 5.3.4 Message too big for system + + The message (subsequent to URL resolution) is larger than the + per-message size limit for this server. + + 554 5.7.8 URL resolution requires trust relationship + + The submit server does not have a trust relationship with the IMAP + server specified in the URL argument to BURL. + + 552 5.2.2 Mailbox full + + The recipient is local, the submit server supports direct + delivery, and the recipient has exceeded his quota and any grace + period for delivery attempts. + + 554 5.6.6 IMAP URL resolution failed + + The IMAP URLFETCH command returned an error or no data. + + 250 2.5.0 Waiting for additional BURL or BDAT commands + + A BURL command without the "LAST" modifier was sent. The URL for + this BURL command was successfully resolved, but the content will + not necessarily be committed to persistent storage until the rest + of the message content is collected. For example, a Unix server + may have written the content to a queue file buffer, but may not + yet have performed an fsync() operation. If the server loses + power, the content can still be lost. + + 451 4.4.1 IMAP server unavailable + + The connection to the IMAP server to resolve the URL failed. + + + + + +Newman Standards Track [Page 8] + +RFC 4468 Message Submission BURL Extension May 2006 + + + 250 2.5.0 Ok. + + The URL was successfully resolved, and the complete message data + has been committed to persistent storage. + + 250 2.6.4 MIME header conversion with loss performed + + The URL pointed to message data that included mail or MIME headers + with 8-bit data. This data was converted to MIME header encoding + [RFC2047], but the submit server may not have correctly guessed + the unlabeled character set. + +7. IANA Considerations + + The "BURL" SMTP extension as described in Section 3 has been + registered. This registration has been marked for use by message + submission [RFC4409] only in the registry. + +8. Security Considerations + + Modern SMTP submission servers often include content-based security + and denial-of-service defense mechanisms such as virus filtering, + size limits, server-generated signatures, spam filtering, etc. + Implementations of BURL should fetch the URL content prior to + application of such content-based mechanisms in order to preserve + their function. + + Clients that generate unsolicited bulk email or email with viruses + could use this mechanism to compensate for a slow link between the + client and submit server. In particular, this mechanism would make + it feasible for a programmable cell phone or other device on a slow + link to become a significant source of unsolicited bulk email and/or + viruses. This makes it more important for submit server vendors + implementing BURL to have auditing and/or defenses against such + denial-of-service attacks including mandatory authentication, logging + that associates unique client identifiers with mail transactions, + limits on reuse of the same IMAP URL, rate limits, recipient count + limits, and content filters. + + Transfer of the URLAUTH [RFC4467] form of IMAP URLs in the clear can + expose the authorization token to network eavesdroppers. + Implementations that support such URLs can address this issue by + using a strong confidentiality protection mechanism. For example, + the SMTP STARTTLS [RFC3207] and the IMAP STARTTLS [RFC3501] + extensions, in combination with a configuration setting that requires + their use with such IMAP URLs, would address this concern. + + + + + +Newman Standards Track [Page 9] + +RFC 4468 Message Submission BURL Extension May 2006 + + + Use of a prearranged trust relationship between a submit server and a + specific IMAP server introduces security considerations. A + compromise of the submit server should not automatically compromise + all accounts on the IMAP server, so trust relationships involving + super-user proxy credentials are strongly discouraged. A system that + requires the submit server to authenticate to the IMAP server with + submit credentials and subsequently requires a URLAUTH URL to fetch + any content addresses this concern. A trusted third party model for + proxy credentials (such as that provided by Kerberos 5 [RFC4120]) + would also suffice. + + When a client uses SMTP STARTTLS to send a BURL command that + references non-public information, there is a user expectation that + the entire message content will be treated confidentially. To + address this expectation, the message submission server SHOULD use + STARTTLS or a mechanism providing equivalent data confidentiality + when fetching the content referenced by that URL. + + A legitimate user of a submit server may try to compromise other + accounts on the server by providing an IMAP URLAUTH URL that points + to a server under that user's control that is designed to undermine + the security of the submit server. For this reason, the IMAP client + code that the submit server uses must be robust with respect to + arbitrary input sizes (including large IMAP literals) and arbitrary + delays from the IMAP server. Requiring a prearranged trust + relationship between a submit server and the IMAP server also + addresses this concern. + + An authorized user of the submit server could set up a fraudulent + IMAP server and pass a URL for that server to the submit server. The + submit server might then contact the fraudulent IMAP server to + authenticate with submit credentials and fetch content. There are + several ways to mitigate this potential attack. A submit server that + only uses submit credentials with a fixed set of trusted IMAP servers + will not be vulnerable to exposure of those credentials. A submit + server can treat the IMAP server as untrusted and include defenses + for buffer overflows, denial-of-service slowdowns, and other + potential attacks. Finally, because authentication is required to + use BURL, it is possible to keep a secure audit trail and use that to + detect and punish the offending party. + + + + + + + + + + + +Newman Standards Track [Page 10] + +RFC 4468 Message Submission BURL Extension May 2006 + + +9. References + +9.1. Normative References + + [RFC1652] Klensin, J., Freed, N., Rose, M., Stefferud, E., and D. + Crocker, "SMTP Service Extension for + 8bit-MIMEtransport", RFC 1652, July 1994. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2192] Newman, C., "IMAP URL Scheme", RFC 2192, + September 1997. + + [RFC2554] Myers, J., "SMTP Service Extension for Authentication", + RFC 2554, March 1999. + + [RFC2821] Klensin, J., "Simple Mail Transfer Protocol", RFC 2821, + April 2001. + + [RFC3207] Hoffman, P., "SMTP Service Extension for Secure SMTP + over Transport Layer Security", RFC 3207, + February 2002. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - + VERSION 4rev1", RFC 3501, March 2003. + + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, + "Uniform Resource Identifier (URI): Generic Syntax", + STD 66, RFC 3986, January 2005. + + [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 4234, October 2005. + + [RFC4409] Gellens, R. and J. Klensin, "Message Submission for + Mail", RFC 4409, April 2006. + + [RFC4467] Crispin, M., "Internet Message Access Protocol (IMAP) - + URLAUTH Extension", RFC 4467, May 2006. + + + + + + + + + + + + +Newman Standards Track [Page 11] + +RFC 4468 Message Submission BURL Extension May 2006 + + +9.2. Informative References + + [RFC2034] Freed, N., "SMTP Service Extension for Returning + Enhanced Error Codes", RFC 2034, October 1996. + + [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet + Mail Extensions (MIME) Part One: Format of Internet + Message Bodies", RFC 2045, November 1996. + + [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail + Extensions) Part Three: Message Header Extensions for + Non-ASCII Text", RFC 2047, November 1996. + + [RFC2920] Freed, N., "SMTP Service Extension for Command + Pipelining", STD 60, RFC 2920, September 2000. + + [RFC3030] Vaudreuil, G., "SMTP Service Extensions for + Transmission of Large and Binary MIME Messages", + RFC 3030, December 2000. + + [RFC3463] Vaudreuil, G., "Enhanced Mail System Status Codes", + RFC 3463, January 2003. + + [RFC4120] Neuman, C., Yu, T., Hartman, S., and K. Raeburn, "The + Kerberos Network Authentication Service (V5)", RFC + 4120, July 2005. + + [SASL-PLAIN] Zeilenga, K., "The Plain SASL Mechanism", Work in + Progress, March 2005. + + + + + + + + + + + + + + + + + + + + + + +Newman Standards Track [Page 12] + +RFC 4468 Message Submission BURL Extension May 2006 + + +Appendix A. Acknowledgements + + This document is a product of the lemonade WG. Many thanks are due + to all the participants of that working group for their input. Mark + Crispin was instrumental in the conception of this mechanism. Thanks + to Randall Gellens, Alexey Melnikov, Sam Hartman, Ned Freed, Dave + Cridland, Peter Coates, and Mark Crispin for review comments on the + document. Thanks to the RFC Editor for correcting the author's + grammar mistakes. Thanks to Ted Hardie, Randall Gellens, Mark + Crispin, Pete Resnick, and Greg Vaudreuil for extremely interesting + debates comparing this proposal and alternatives. Thanks to the + lemonade WG chairs Eric Burger and Glenn Parsons for concluding the + debate at the correct time and making sure this document got + completed. + +Author's Address + + Chris Newman + Sun Microsystems + 3401 Centrelake Dr., Suite 410 + Ontario, CA 91761 + US + + EMail: chris.newman@sun.com + + + + + + + + + + + + + + + + + + + + + + + + + + + +Newman Standards Track [Page 13] + +RFC 4468 Message Submission BURL Extension May 2006 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2006). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is provided by the IETF + Administrative Support Activity (IASA). + + + + + + + +Newman Standards Track [Page 14] + diff --git a/imap/docs/rfc/rfc4469.txt b/imap/docs/rfc/rfc4469.txt new file mode 100644 index 00000000..da365514 --- /dev/null +++ b/imap/docs/rfc/rfc4469.txt @@ -0,0 +1,731 @@ + + + + + + +Network Working Group P. Resnick +Request for Comments: 4469 QUALCOMM Incorporated +Updates: 3501, 3502 April 2006 +Category: Standards Track + + + Internet Message Access Protocol (IMAP) CATENATE Extension + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2006). + +Abstract + + The CATENATE extension to the Internet Message Access Protocol (IMAP) + extends the APPEND command to allow clients to create messages on the + IMAP server that may contain a combination of new data along with + parts of (or entire) messages already on the server. Using this + extension, the client can catenate parts of an already existing + message onto a new message without having to first download the data + and then upload it back to the server. + + + + + + + + + + + + + + + + + + + + + + +Resnick Standards Track [Page 1] + +RFC 4469 IMAP CATENATE Extension April 2006 + + +1. Introduction + + The CATENATE extension to the Internet Message Access Protocol (IMAP) + [1] allows the client to create a message on the server that can + include the text of messages (or parts of messages) that already + exist on the server without having to FETCH them and APPEND them back + to the server. The CATENATE extension extends the APPEND command so + that, instead of a single message literal, the command can take as + arguments any combination of message literals (as described in IMAP + [1]) and message URLs (as described in the IMAP URL Scheme [2] + specification). The server takes all the pieces and catenates them + into the output message. The CATENATE extension can also coexist + with the MULTIAPPEND extension [3] to APPEND multiple messages in a + single command. + + There are some obvious uses for the CATENATE extension. The + motivating use case was to provide a way for a resource-constrained + client to compose a message for subsequent submission that contains + data that already exists in that client's IMAP store. Because the + client does not have to download and re-upload potentially large + message parts, bandwidth and processing limitations do not have as + much impact. In addition, since the client can create a message in + its own IMAP store, the command also addresses the desire of the + client to archive a copy of a sent message without having to upload + the message twice. (Mechanisms for sending the message are outside + the scope of this document.) + + The extended APPEND command can also be used to copy parts of a + message to another mailbox for archival purposes while getting rid of + undesired parts. In environments where server storage is limited, a + client could get rid of large message parts by copying over only the + necessary parts and then deleting the original message. The + mechanism could also be used to add data to a message (such as + prepending message header fields) or to include other data by making + a copy of the original and catenating the new data. + +2. The CATENATE Capability + + A server that supports this extension returns "CATENATE" as one of + the responses to the CAPABILITY command. + + + + + + + + + + + +Resnick Standards Track [Page 2] + +RFC 4469 IMAP CATENATE Extension April 2006 + + +3. The APPEND Command + + Arguments: mailbox name + (The following can be repeated in the presence of the + MULTIAPPEND extension [3]) + OPTIONAL flag parenthesized list + OPTIONAL date/time string + a single message literal or one or more message parts to + catenate, specified as: + message literal + or + message (or message part) URL + + Responses: OPTIONAL NO responses: BADURL, TOOBIG + + Result: OK - append completed + NO - append error: can't append to that mailbox, error + in flags or date/time or message text, or can't + fetch that data + BAD - command unknown or arguments invalid + + The APPEND command concatenates all the message parts and appends + them as a new message to the end of the specified mailbox. The + parenthesized flag list and date/time string set the flags and the + internal date, respectively, as described in IMAP [1]. The + subsequent command parameters specify the message parts that are + appended sequentially to the output message. + + If the original form of APPEND is used, a message literal follows the + optional flag list and date/time string, which is appended as + described in IMAP [1]. If the extended form is used, "CATENATE" and + a parenthesized list of message literals and message URLs follows, + each of which is appended to the new message. If a message literal + is specified (indicated by "TEXT"), the octets following the count + are appended. If a message URL is specified (indicated by "URL"), + the octets of the body part pointed to by that URL are appended, as + if the literal returned in a FETCH BODY response were put in place of + the message part specifier. The APPEND command does not cause the + \Seen flag to be set for any catenated body part. The APPEND command + does not change the selected mailbox. + + In the extended APPEND command, the string following "URL" is an IMAP + URL [2] and is interpreted according to the rules of [2]. The + present document only describes the behavior of the command using + IMAP URLs that refer to specific messages or message parts on the + current IMAP server from the current authenticated IMAP session. + Because of that, only relative IMAP message or message part URLs + (i.e., those having no scheme or <iserver>) are used. The base URL + + + +Resnick Standards Track [Page 3] + +RFC 4469 IMAP CATENATE Extension April 2006 + + + for evaluating the relative URL is considered "imap://user@server/", + where "user" is the user name of the currently authenticated user and + "server" is the domain name of the current server. When in the + selected state, the base URL is considered + "imap://user@server/mailbox", where "mailbox" is the encoded name of + the currently selected mailbox. Additionally, since the APPEND + command is valid in the authenticated state of an IMAP session, no + further LOGIN or AUTHENTICATE command is performed for URLs specified + in the extended APPEND command. + + Note: Use of an absolute IMAP URL or any URL that refers to + anything other than a message or message part from the current + authenticated IMAP session is outside the scope of this document + and would require an extension to this specification, and a server + implementing only this specification would return NO to such a + request. + + The client is responsible for making sure that the catenated message + is in the format of an Internet Message Format (RFC 2822) [4] or + Multipurpose Internet Mail Extension (MIME) [5] message. In + particular, when a URL is catenated, the server copies octets, + unchanged, from the indicated message or message part to the + catenated message. It does no data conversion (e.g., MIME transfer + encodings) nor any verification that the data is appropriate for the + MIME part of the message into which it is inserted. The client is + also responsible for inserting appropriate MIME boundaries between + body parts, and writing MIME Content-Type and Content-Transfer- + Encoding lines as needed in the appropriate places. + + Responses behave just as the original APPEND command described in + IMAP [1]. If the server implements the IMAP UIDPLUS extension [6], + it will also return an APPENDUID response code in the tagged OK + response. Two response codes are provided in Section 4 that can be + used in the tagged NO response if the APPEND command fails. + +4. Response Codes + + When a APPEND command fails, it may return a response code that + describes a reason for the failure. + +4.1. BADURL Response + + The BADURL response code is returned if the APPEND fails to process + one of the specified URLs. Possible reasons for this are bad URL + syntax, unrecognized URL schema, invalid message UID, or invalid body + part. The BADURL response code contains the first URL specified as a + parameter to the APPEND command that has caused the operation to + fail. + + + +Resnick Standards Track [Page 4] + +RFC 4469 IMAP CATENATE Extension April 2006 + + +4.2. TOOBIG Response + + The TOOBIG response code is returned if the resulting message will + exceed the 4-GB IMAP message limit. This might happen, for example, + if the client specifies 3 URLs for 2-GB messages. Note that even if + the server doesn't return TOOBIG, it still has to be defensive + against misbehaving or malicious clients that try to construct a + message over the 4-GB limit. The server may also wish to return the + TOOBIG response code if the resulting message exceeds a server- + specific message size limit. + +5. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) [7] notation. Elements not defined here can be found in + the formal syntax of the ABNF [7], IMAP [1], and IMAP ABNF extensions + [8] specifications. Note that capability and resp-text-code are + extended from the IMAP [1] specification and append-data is extended + from the IMAP ABNF extensions [8] specification. + + append-data =/ "CATENATE" SP "(" cat-part *(SP cat-part) ")" + + cat-part = text-literal / url + + text-literal = "TEXT" SP literal + + url = "URL" SP astring + + resp-text-code =/ toobig-response-code / badurl-response-code + + toobig-response-code = "TOOBIG" + + badurl-response-code = "BADURL" SP url-resp-text + + url-resp-text = 1*(%x01-09 / + %x0B-0C / + %x0E-5B / + %x5D-FE) ; Any TEXT-CHAR except "]" + + capability =/ "CATENATE" + + The astring in the definition of url and the url-resp-text in the + definition of badurl-response-code each contain an imapurl as defined + by [2]. + + + + + + + +Resnick Standards Track [Page 5] + +RFC 4469 IMAP CATENATE Extension April 2006 + + +6. Acknowledgements + + Thanks to the members of the LEMONADE working group for their input. + Special thanks to Alexey Melnikov for the examples. + +7. Security Considerations + + The CATENATE extension does not raise any security considerations + that are not present for the base protocol or in the use of IMAP + URLs, and these issues are discussed in the IMAP [1] and IMAP URL [2] + documents. + +8. IANA Considerations + + IMAP4 capabilities are registered by publishing a standards track or + IESG approved experimental RFC. The registry is currently located at + <http://www.iana.org/assignments/imap4-capabilities>. This document + defines the CATENATE IMAP capability. The IANA has added this + capability to the registry. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Resnick Standards Track [Page 6] + +RFC 4469 IMAP CATENATE Extension April 2006 + + +Appendix A. Examples + + Lines not starting with "C: " or "S: " are continuations of the + previous lines. + + The original message in examples 1 and 2 below (UID = 20) has the + following structure: + + + multipart/mixed MIME message with two body parts: + + 1. text/plain + + 2. application/x-zip-compressed + + Example 1: The following example demonstrates how a CATENATE client + can replace an attachment in a draft message, without the need to + download it to the client and upload it back. + + C: A003 APPEND Drafts (\Seen \Draft $MDNSent) CATENATE + (URL "/Drafts;UIDVALIDITY=385759045/;UID=20/;section=HEADER" + TEXT {42} + S: + Ready for literal data + C: + C: --------------030308070208000400050907 + C: URL "/Drafts;UIDVALIDITY=385759045/;UID=20/;section=1.MIME" + URL "/Drafts;UIDVALIDITY=385759045/;UID=20/;section=1" TEXT {42} + S: + Ready for literal data + C: + C: --------------030308070208000400050907 + C: URL "/Drafts;UIDVALIDITY=385759045/;UID=30" TEXT {44} + S: + Ready for literal data + C: + C: --------------030308070208000400050907-- + C: ) + S: A003 OK catenate append completed + + + + + + + + + + + + + + + +Resnick Standards Track [Page 7] + +RFC 4469 IMAP CATENATE Extension April 2006 + + + Example 2: The following example demonstrates how the CATENATE + extension can be used to replace edited text in a draft message, as + well as header fields for the top level message part (e.g., Subject + has changed). The previous version of the draft is marked as + \Deleted. Note that the server also supports the UIDPLUS extension, + so the APPENDUID response code is returned in the successful OK + response to the APPEND command. + + C: A003 APPEND Drafts (\Seen \Draft $MDNSent) CATENATE (TEXT {738} + S: + Ready for literal data + C: Return-Path: <bar@example.org> + C: Received: from [127.0.0.2] + C: by rufus.example.org via TCP (internal) with ESMTPA; + C: Thu, 11 Nov 2004 16:57:07 +0000 + C: Message-ID: <419399E1.6000505@example.org> + C: Date: Thu, 12 Nov 2004 16:57:05 +0000 + C: From: Bob Ar <bar@example.org> + C: X-Accept-Language: en-us, en + C: MIME-Version: 1.0 + C: To: foo@example.net + C: Subject: About our holiday trip + C: Content-Type: multipart/mixed; + C: boundary="------------030308070208000400050907" + C: + C: --------------030308070208000400050907 + C: Content-Type: text/plain; charset=us-ascii; format=flowed + C: Content-Transfer-Encoding: 7bit + C: + C: Our travel agent has sent the updated schedule. + C: + C: Cheers, + C: Bob + C: --------------030308070208000400050907 + C: URL "/Drafts;UIDVALIDITY=385759045/;UID=20/;Section=2.MIME" + URL "/Drafts;UIDVALIDITY=385759045/;UID=20/;Section=2" TEXT {44} + S: + Ready for literal data + C: + C: --------------030308070208000400050907-- + C: ) + S: A003 OK [APPENDUID 385759045 45] append Completed + C: A004 UID STORE 20 +FLAGS.SILENT (\Deleted) + S: A004 OK STORE completed + + + + + + + + + +Resnick Standards Track [Page 8] + +RFC 4469 IMAP CATENATE Extension April 2006 + + + Example 3: The following example demonstrates how the CATENATE + extension can be used to strip attachments. Below, a PowerPoint + attachment was replaced by a small text part explaining that the + attachment was stripped. + + C: A003 APPEND Drafts (\Seen \Draft $MDNSent) CATENATE + (URL "/Drafts;UIDVALIDITY=385759045/;UID=21/;section=HEADER" + TEXT {42} + S: + Ready for literal data + C: + C: --------------030308070208000400050903 + C: URL "/Drafts;UIDVALIDITY=385759045/;UID=21/;section=1.MIME" + URL "/Drafts;UIDVALIDITY=385759045/;UID=21/;section=1" TEXT {255} + S: + Ready for literal data + C: + C: --------------030308070208000400050903 + C: Content-type: text/plain; charset="us-ascii" + C: Content-transfer-encoding: 7bit + C: + C: This body part contained a Power Point presentation that was + C: deleted upon your request. + C: --------------030308070208000400050903-- + C: ) + S: A003 OK append Completed + + + + + + + + + + + + + + + + + + + + + + + + + + + +Resnick Standards Track [Page 9] + +RFC 4469 IMAP CATENATE Extension April 2006 + + + Example 4: The following example demonstrates a failed APPEND + command. The server returns the BADURL response code to indicate + that one of the provided URLs is invalid. This example also + demonstrates how the CATENATE extension can be used to construct a + digest of several messages. + + C: A003 APPEND Sent (\Seen $MDNSent) CATENATE (TEXT {541} + S: + Ready for literal data + C: Return-Path: <foo@example.org> + C: Received: from [127.0.0.2] + C: by rufus.example.org via TCP (internal) with ESMTPA; + C: Thu, 11 Nov 2004 16:57:07 +0000 + C: Message-ID: <419399E1.6000505@example.org> + C: Date: Thu, 21 Nov 2004 16:57:05 +0000 + C: From: Farren Oo <foo@example.org> + C: X-Accept-Language: en-us, en + C: MIME-Version: 1.0 + C: To: bar@example.org + C: Subject: Digest of the mailing list for today + C: Content-Type: multipart/digest; + C: boundary="------------030308070208000400050904" + C: + C: --------------030308070208000400050904 + C: URL "/INBOX;UIDVALIDITY=785799047/;UID=11467" TEXT {42} + S: + Ready for literal data + C: + C: --------------030308070208000400050904 + C: URL "/INBOX;UIDVALIDITY=785799047/;UID=113330/;section=1.5.9" + TEXT {42} + S: + Ready for literal data + C: + C: --------------030308070208000400050904 + C: URL "/INBOX;UIDVALIDITY=785799047/;UID=11916" TEXT {44} + S: + Ready for literal data + C: + C: --------------030308070208000400050904-- + C: ) + S: A003 NO [BADURL "/INBOX;UIDVALIDITY=785799047/;UID=113330; + section=1.5.9"] CATENATE append has failed, one message expunged + + Note that the server could have validated the URLs as they were + received and therefore could have returned the tagged NO response + with BADURL response-code in place of any continuation request after + the URL was received. + + + + + + + +Resnick Standards Track [Page 10] + +RFC 4469 IMAP CATENATE Extension April 2006 + + +9. Normative References + + [1] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1", + RFC 3501, March 2003. + + [2] Newman, C., "IMAP URL Scheme", RFC 2192, September 1997. + + [3] Crispin, M., "Internet Message Access Protocol (IMAP) - + MULTIAPPEND Extension", RFC 3502, March 2003. + + [4] Resnick, P., "Internet Message Format", RFC 2822, April 2001. + + [5] Freed, N. and N. Borenstein, "Multipurpose Internet Mail + Extensions (MIME) Part One: Format of Internet Message Bodies", + RFC 2045, November 1996. + + [6] Crispin, M., "Internet Message Access Protocol (IMAP) - UIDPLUS + extension", RFC 4315, December 2005. + + [7] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 4234, October 2005. + + [8] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 ABNF", + RFC 4466, April 2006. + + + + + + + + + + + + + + + + + + + + + + + + + + + +Resnick Standards Track [Page 11] + +RFC 4469 IMAP CATENATE Extension April 2006 + + +Author's Address + + Peter W. Resnick + QUALCOMM Incorporated + 5775 Morehouse Drive + San Diego, CA 92121-1714 + US + + Phone: +1 858 651 4478 + EMail: presnick@qualcomm.com + URI: http://www.qualcomm.com/~presnick/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Resnick Standards Track [Page 12] + +RFC 4469 IMAP CATENATE Extension April 2006 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2006). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is provided by the IETF + Administrative Support Activity (IASA). + + + + + + + +Resnick Standards Track [Page 13] + diff --git a/imap/docs/rfc/rfc4505.txt b/imap/docs/rfc/rfc4505.txt new file mode 100644 index 00000000..6b8a4a11 --- /dev/null +++ b/imap/docs/rfc/rfc4505.txt @@ -0,0 +1,507 @@ + + + + + + +Network Working Group K. Zeilenga, Ed. +Request for Comments: 4505 OpenLDAP Foundation +Obsoletes: 2245 June 2006 +Category: Standards Track + + + Anonymous Simple Authentication and Security Layer (SASL) Mechanism + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2006). + +Abstract + + On the Internet, it is common practice to permit anonymous access to + various services. Traditionally, this has been done with a plain- + text password mechanism using "anonymous" as the user name and using + optional trace information, such as an email address, as the + password. As plain-text login commands are not permitted in new IETF + protocols, a new way to provide anonymous login is needed within the + context of the Simple Authentication and Security Layer (SASL) + framework. + +1. Introduction + + This document defines an anonymous mechanism for the Simple + Authentication and Security Layer ([SASL]) framework. The name + associated with this mechanism is "ANONYMOUS". + + Unlike many other SASL mechanisms, whose purpose is to authenticate + and identify the user to a server, the purpose of this SASL mechanism + is to allow the user to gain access to services or resources without + requiring the user to establish or otherwise disclose their identity + to the server. That is, this mechanism provides an anonymous login + method. + + This mechanism does not provide a security layer. + + This document replaces RFC 2245. Changes since RFC 2245 are detailed + in Appendix A. + + + +Zeilenga Standards Track [Page 1] + +RFC 4505 Anonymous SASL Mechanism June 2006 + + +2. The Anonymous Mechanism + + The mechanism consists of a single message from the client to the + server. The client may include in this message trace information in + the form of a string of [UTF-8]-encoded [Unicode] characters prepared + in accordance with [StringPrep] and the "trace" stringprep profile + defined in Section 3 of this document. The trace information, which + has no semantical value, should take one of two forms: an Internet + email address, or an opaque string that does not contain the '@' + (U+0040) character and that can be interpreted by the system + administrator of the client's domain. For privacy reasons, an + Internet email address or other information identifying the user + should only be used with permission from the user. + + A server that permits anonymous access will announce support for the + ANONYMOUS mechanism and allow anyone to log in using that mechanism, + usually with restricted access. + + A formal grammar for the client message using Augmented BNF [ABNF] is + provided below as a tool for understanding this technical + specification. + + message = [ email / token ] + ;; to be prepared in accordance with Section 3 + + UTF1 = %x00-3F / %x41-7F ;; less '@' (U+0040) + UTF2 = %xC2-DF UTF0 + UTF3 = %xE0 %xA0-BF UTF0 / %xE1-EC 2(UTF0) / + %xED %x80-9F UTF0 / %xEE-EF 2(UTF0) + UTF4 = %xF0 %x90-BF 2(UTF0) / %xF1-F3 3(UTF0) / + %xF4 %x80-8F 2(UTF0) + UTF0 = %x80-BF + + TCHAR = UTF1 / UTF2 / UTF3 / UTF4 + ;; any UTF-8 encoded Unicode character + ;; except '@' (U+0040) + + email = addr-spec + ;; as defined in [IMAIL] + + token = 1*255TCHAR + + Note to implementors: + The <token> production is restricted to 255 UTF-8-encoded Unicode + characters. As the encoding of a characters uses a sequence of 1 + to 4 octets, a token may be as long as 1020 octets. + + + + + +Zeilenga Standards Track [Page 2] + +RFC 4505 Anonymous SASL Mechanism June 2006 + + +3. The "trace" Profile of "Stringprep" + + This section defines the "trace" profile of [StringPrep]. This + profile is designed for use with the SASL ANONYMOUS Mechanism. + Specifically, the client is to prepare the <message> production in + accordance with this profile. + + The character repertoire of this profile is Unicode 3.2 [Unicode]. + + No mapping is required by this profile. + + No Unicode normalization is required by this profile. + + The list of unassigned code points for this profile is that provided + in Appendix A of [StringPrep]. Unassigned code points are not + prohibited. + + Characters from the following tables of [StringPrep] are prohibited: + + - C.2.1 (ASCII control characters) + - C.2.2 (Non-ASCII control characters) + - C.3 (Private use characters) + - C.4 (Non-character code points) + - C.5 (Surrogate codes) + - C.6 (Inappropriate for plain text) + - C.8 (Change display properties are deprecated) + - C.9 (Tagging characters) + + No additional characters are prohibited. + + This profile requires bidirectional character checking per Section 6 + of [StringPrep]. + +4. Example + + Here is a sample ANONYMOUS login between an IMAP client and server. + In this example, "C:" and "S:" indicate lines sent by the client and + server, respectively. If such lines are wrapped without a new "C:" + or "S:" label, then the wrapping is for editorial clarity and is not + part of the command. + + Note that this example uses the IMAP profile [IMAP4] of SASL. The + base64 encoding of challenges and responses as well as the "+ " + preceding the responses are part of the IMAP4 profile, not part of + SASL itself. Additionally, protocols with SASL profiles permitting + an initial client response will be able to avoid the extra round trip + below (the server response with an empty "+ "). + + + + +Zeilenga Standards Track [Page 3] + +RFC 4505 Anonymous SASL Mechanism June 2006 + + + In this example, the trace information is "sirhc". + + S: * OK IMAP4 server ready + C: A001 CAPABILITY + S: * CAPABILITY IMAP4 IMAP4rev1 AUTH=DIGEST-MD5 AUTH=ANONYMOUS + S: A001 OK done + C: A002 AUTHENTICATE ANONYMOUS + S: + + C: c2lyaGM= + S: A003 OK Welcome, trace information has been logged. + +5. Security Considerations + + The ANONYMOUS mechanism grants access to services and/or resources by + anyone. For this reason, it should be disabled by default so that + the administrator can make an explicit decision to enable it. + + If the anonymous user has any write privileges, a denial-of-service + attack is possible by filling up all available space. This can be + prevented by disabling all write access by anonymous users. + + If anonymous users have read and write access to the same area, the + server can be used as a communication mechanism to exchange + information anonymously. Servers that accept anonymous submissions + should implement the common "drop box" model, which forbids anonymous + read access to the area where anonymous submissions are accepted. + + If the anonymous user can run many expensive operations (e.g., an + IMAP SEARCH BODY command), this could enable a denial-of-service + attack. Servers are encouraged to reduce the priority of anonymous + users or limit their resource usage. + + While servers may impose a limit on the number of anonymous users, + note that such limits enable denial-of-service attacks and should be + used with caution. + + The trace information is not authenticated, so it can be falsified. + This can be used as an attempt to get someone else in trouble for + access to questionable information. Administrators investigating + abuse need to realize that this trace information may be falsified. + + A client that uses the user's correct email address as trace + information without explicit permission may violate that user's + privacy. Anyone who accesses an anonymous archive on a sensitive + subject (e.g., sexual abuse) likely has strong privacy needs. + Clients should not send the email address without the explicit + permission of the user and should offer the option of supplying no + trace information, thus only exposing the source IP address and time. + + + +Zeilenga Standards Track [Page 4] + +RFC 4505 Anonymous SASL Mechanism June 2006 + + + Anonymous proxy servers could enhance this privacy but would have to + consider the resulting potential denial-of-service attacks. + + Anonymous connections are susceptible to man-in-the-middle attacks + that view or alter the data transferred. Clients and servers are + encouraged to support external data security services. + + Protocols that fail to require an explicit anonymous login are more + susceptible to break-ins given certain common implementation + techniques. Specifically, Unix servers that offer user login may + initially start up as root and switch to the appropriate user id + after an explicit login command. Normally, such servers refuse all + data access commands prior to explicit login and may enter a + restricted security environment (e.g., the Unix chroot(2) function) + for anonymous users. If anonymous access is not explicitly + requested, the entire data access machinery is exposed to external + security attacks without the chance for explicit protective measures. + Protocols that offer restricted data access should not allow + anonymous data access without an explicit login step. + + General [SASL] security considerations apply to this mechanism. + + [StringPrep] security considerations and [Unicode] security + considerations discussed in [StringPrep] apply to this mechanism. + [UTF-8] security considerations also apply. + +6. IANA Considerations + + The SASL Mechanism registry [IANA-SASL] entry for the ANONYMOUS + mechanism has been updated by the IANA to reflect that this document + now provides its technical specification. + + To: iana@iana.org + Subject: Updated Registration of SASL mechanism ANONYMOUS + + SASL mechanism name: ANONYMOUS + Security considerations: See RFC 4505. + Published specification (optional, recommended): RFC 4505 + Person & email address to contact for further information: + Kurt Zeilenga <Kurt@OpenLDAP.org> + Chris Newman <Chris.Newman@sun.com> + Intended usage: COMMON + Author/Change controller: IESG <iesg@ietf.org> + Note: Updates existing entry for ANONYMOUS + + + + + + + +Zeilenga Standards Track [Page 5] + +RFC 4505 Anonymous SASL Mechanism June 2006 + + + The [StringPrep] profile "trace", first defined in this RFC, has been + registered: + + To: iana@iana.org + Subject: Initial Registration of Stringprep "trace" profile + + Stringprep profile: trace + Published specification: RFC 4505 + Person & email address to contact for further information: + Kurt Zeilenga <kurt@openldap.org> + +7. Acknowledgement + + This document is a revision of RFC 2245 by Chris Newman. Portions of + the grammar defined in Section 1 were borrowed from RFC 3629 by + Francois Yergeau. + + This document is a product of the IETF SASL WG. + +8. Normative References + + [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 4234, October 2005. + + [IMAIL] Resnick, P., "Internet Message Format", RFC 2822, April + 2001. + + [SASL] Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple + Authentication and Security Layer (SASL)", RFC 4422, + June 2006. + + [StringPrep] Hoffman, P. and M. Blanchet, "Preparation of + Internationalized Strings ('stringprep')", RFC 3454, + December 2002. + + [Unicode] The Unicode Consortium, "The Unicode Standard, Version + 3.2.0" is defined by "The Unicode Standard, Version 3.0" + (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5), + as amended by the "Unicode Standard Annex #27: Unicode + 3.1" (http://www.unicode.org/reports/tr27/) and by the + "Unicode Standard Annex #28: Unicode 3.2" + (http://www.unicode.org/reports/tr28/). + + [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", RFC 3629 (also STD 63), November 2003. + + + + + + +Zeilenga Standards Track [Page 6] + +RFC 4505 Anonymous SASL Mechanism June 2006 + + +9. Informative References + + [IMAP4] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [IANA-SASL] IANA, "SIMPLE AUTHENTICATION AND SECURITY LAYER (SASL) + MECHANISMS", <http://www.iana.org/assignments/sasl- + mechanisms>. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Zeilenga Standards Track [Page 7] + +RFC 4505 Anonymous SASL Mechanism June 2006 + + +Appendix A. Changes since RFC 2245 + + This appendix is non-normative. + + RFC 2245 allows the client to include optional trace information in + the form of a human readable string. RFC 2245 restricted this string + to US-ASCII. As the Internet is international, this document uses a + string restricted to UTF-8 encoded Unicode characters. A + "stringprep" profile is defined to precisely define which Unicode + characters are allowed in this string. While the string remains + restricted to 255 characters, the encoded length of each character + may now range from 1 to 4 octets. + + Additionally, a number of editorial changes were made. + +Editor's Address + + Kurt D. Zeilenga + OpenLDAP Foundation + + EMail: Kurt@OpenLDAP.org + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Zeilenga Standards Track [Page 8] + +RFC 4505 Anonymous SASL Mechanism June 2006 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2006). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is provided by the IETF + Administrative Support Activity (IASA). + + + + + + + +Zeilenga Standards Track [Page 9] + diff --git a/imap/docs/rfc/rfc4549.txt b/imap/docs/rfc/rfc4549.txt new file mode 100644 index 00000000..8430ee10 --- /dev/null +++ b/imap/docs/rfc/rfc4549.txt @@ -0,0 +1,1963 @@ + + + + + + +Network Working Group A. Melnikov, Ed. +Request for Comments: 4549 Isode Ltd. +Category: Informational June 2006 + + + Synchronization Operations for Disconnected IMAP4 Clients + +Status of This Memo + + This memo provides information for the Internet community. It does + not specify an Internet standard of any kind. Distribution of this + memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2006). + +Abstract + + This document attempts to address some of the issues involved in + building a disconnected IMAP4 client. In particular, it deals with + the issues of what might be called the "driver" portion of the + synchronization tool: the portion of the code responsible for issuing + the correct set of IMAP4 commands to synchronize the disconnected + client in the way that is most likely to make the human who uses the + disconnected client happy. + + This note describes different strategies that can be used by + disconnected clients and shows how to use IMAP protocol in order to + minimize the time of the synchronization process. + + This note also lists IMAP extensions that a server should implement + in order to provide better synchronization facilities to disconnected + clients. + + + + + + + + + + + + + + + + + +Melnikov Informational [Page 1] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + +Table of Contents + + 1. Introduction ....................................................3 + 1.1. Conventions Used in This Document ..........................3 + 2. Design Principles ...............................................3 + 3. Overall Picture of Synchronization ..............................4 + 4. Mailbox Synchronization Steps and Strategies ....................7 + 4.1. Checking UID Validity ......................................7 + 4.2. Synchronizing Local Changes with the Server ................8 + 4.2.1. Uploading Messages to the Mailbox ...................8 + 4.2.2. Optimizing "move" and "copy" Operations .............9 + 4.2.3. Replaying Local Flag Changes .......................14 + 4.2.4. Processing Mailbox Compression (EXPUNGE) Requests ..15 + 4.2.5. Closing a Mailbox ..................................17 + 4.3. Details of "Normal" Synchronization of a Single Mailbox ...18 + 4.3.1. Discovering New Messages and Changes to Old + Messages ...........................................18 + 4.3.2. Searching for "Interesting" Messages. ..............20 + 4.3.3. Populating Cache with "Interesting" Messages. ......21 + 4.3.4. User-Initiated Synchronization .....................22 + 4.4. Special Case: Descriptor-Only Synchronization .............22 + 4.5. Special Case: Fast New-Only Synchronization ...............23 + 4.6. Special Case: Blind FETCH .................................23 + 5. Implementation Considerations ..................................24 + 5.1. Error Recovery during Playback ............................26 + 5.2. Quality of Implementation Issues ..........................28 + 5.3. Optimizations .............................................28 + 6. IMAP Extensions That May Help ..................................30 + 6.1. CONDSTORE Extension .......................................30 + 7. Security Considerations ........................................33 + 8. References .....................................................33 + 8.1. Normative References ......................................33 + 8.2. Informative References ....................................34 + 9. Acknowledgements ...............................................34 + + + + + + + + + + + + + + + + + +Melnikov Informational [Page 2] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + +1. Introduction + + Several recommendations presented in this document are generally + applicable to all types of IMAP clients. However, this document + tries to concentrate on disconnected mail clients [IMAP-MODEL]. It + also suggests some IMAP extensions* that should be implemented by + IMAP servers in order to make the life of disconnected clients + easier. In particular, the [UIDPLUS] extension was specifically + designed to streamline certain disconnected operations, like + expunging, uploading, and copying messages (see Sections 4.2.1, + 4.2.2.1, and 4.2.4). + + Readers of this document are also strongly advised to read RFC 2683 + [RFC2683]. + + * Note that the functionality provided by the base IMAP protocol + [IMAP4] is sufficient to perform basic synchronization. + +1.1. Conventions Used in This Document + + In examples, "C:" and "S:" indicate lines sent by the client and + server, respectively. Long lines in examples are broken for + editorial clarity. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [KEYWORDS]. + + Let's call an IMAP command idempotent if the result of executing the + command twice sequentially is the same as the result of executing the + command just once. + +2. Design Principles + + All mailbox state or content information stored on the disconnected + client should be viewed strictly as a cache of the state of the + server. The "master" state remains on the server, just as it would + with an interactive IMAP4 client. The one exception to this rule is + that information about the state of the disconnected client's cache + (the state includes flag changes while offline and during scheduled + message uploads) remains on the disconnected client: that is, the + IMAP4 server is not responsible for remembering the state of the + disconnected IMAP4 client. + + We assume that a disconnected client is a client that, for whatever + reason, wants to minimize the length of time that it is "on the + phone" to the IMAP4 server. Often this will be because the client is + using a dialup connection, possibly with very low bandwidth, but + + + +Melnikov Informational [Page 3] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + sometimes it might just be that the human is in a hurry to catch an + airplane, or some other event beyond our control. Whatever the + reason, we assume that we must make efficient use of the network + connection, both in the usual sense (not generating spurious traffic) + and in the sense that we would prefer not to have the connection + sitting idle while the client and/or the server is performing + strictly local computation or I/O. Another, perhaps simpler way of + stating this is that we assume that network connections are + "expensive". + + Practical experience with disconnected mail systems has shown that + there is no single synchronization strategy that is appropriate for + all cases. Different humans have different preferences, and the same + human's preference will vary depending both on external circumstance + (how much of a hurry the human is in today) and on the value that the + human places on the messages being transferred. The point here is + that there is no way that the synchronization program can guess + exactly what the human wants to do, so the human will have to provide + some guidance. + + Taken together, the preceding two principles lead to the conclusion + that the synchronization program must make its decisions based on + some kind of guidance provided by the human, by selecting the + appropriate options in the user interface or through some sort of + configuration file. Almost certainly, it should not pause for I/O + with the human in the middle of the synchronization process. The + human will almost certainly have several different configurations for + the synchronization program, for different circumstances. + + Since a disconnected client has no way of knowing what changes might + have occurred to the mailbox while it was disconnected, message + numbers are not useful to a disconnected client. All disconnected + client operations should be performed using UIDs, so that the client + can be sure that it and the server are talking about the same + messages during the synchronization process. + +3. Overall Picture of Synchronization + + The basic strategy for synchronization is outlined below. Note that + the real strategy may vary from one application to another or may + depend on a synchronization mode. + + a) Process any "actions" that were pending on the client that were + not associated with any mailbox. (In particular sending messages + composed offline with SMTP. This is not part of IMAP + synchronization, but it is mentioned here for completeness.) + + + + + +Melnikov Informational [Page 4] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + b) Fetch the current list of "interesting" mailboxes. (The + disconnected client should allow the user to skip this step + completely.) + + c) "Client-to-server synchronization": for each IMAP "action" that + was pending on the client, do the following: + + 1) If the action implies opening a new mailbox (any operation that + operates on messages), open the mailbox. Check its UID + validity value (see Section 4.1 for more details) returned in + the UIDVALIDITY response code. If the UIDVALIDITY value + returned by the server differs, the client MUST empty the local + cache of the mailbox and remove any pending "actions" that + refer to UIDs in that mailbox (and consider them failed). Note + that this doesn't affect actions performed on client-generated + fake UIDs (see Section 5). + + 2) Perform the action. If the action is to delete a mailbox + (DELETE), make sure that the mailbox is closed first (see also + Section 3.4.12 of [RFC2683]). + + d) "Server-to-client synchronization": for each mailbox that requires + synchronization, do the following: + + 1) Check the mailbox UIDVALIDITY (see Section 4.1 for more + details) with SELECT/EXAMINE/STATUS. + + If UIDVALIDITY value returned by the server differs, the client + MUST + + * empty the local cache of that mailbox; + * remove any pending "actions" that refer to UIDs in that + mailbox and consider them failed; and + * skip step 2-II. + + 2) Fetch the current "descriptors"; + + I) Discover new messages. + + II) Discover changes to old messages. + + 3) Fetch the bodies of any "interesting" messages that the client + doesn't already have. + + e) Close all open mailboxes not required for further operations (if + staying online) or disconnect all open connections (if going + offline). + + + + +Melnikov Informational [Page 5] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + Terms used: + + "Actions" are queued requests that were made by the human to the + client's Mail User Agent (MUA) software while the client was + disconnected. + + We define "descriptors" as a set of IMAP4 FETCH data items. + Conceptually, a message's descriptor is that set of information that + allows the synchronization program to decide what protocol actions + are necessary to bring the local cache to the desired state for this + message; since this decision is really up to the human, this + information probably includes at least a few header fields intended + for human consumption. Exactly what will constitute a descriptor + depends on the client implementation. At a minimum, the descriptor + contains the message's UID and FLAGS. Other likely candidates are + the RFC822.SIZE, RFC822.HEADER, BODYSTRUCTURE, or ENVELOPE data + items. + + Comments: + + 1) The list of actions should be ordered. For example, if the human + deletes message A1 in mailbox A, then expunges mailbox A, and then + deletes message A2 in mailbox A, the human will expect that + message A1 is gone and that message A2 is still present but is now + deleted. + + By processing all the actions before proceeding with + synchronization, we avoid having to compensate for the local MUA's + changes to the server's state. That is, once we have processed + all the pending actions, the steps that the client must take to + synchronize itself will be the same no matter where the changes to + the server's state originated. + + 2) Steps a and b can be performed in parallel. Alternatively, step a + can be performed after d. + + 3) On step b, the set of "interesting" mailboxes pretty much has to + be determined by the human. What mailboxes belong to this set may + vary between different IMAP4 sessions with the same server, + client, and human. An interesting mailbox can be a mailbox + returned by LSUB command (see Section 6.3.9 of [IMAP4]). The + special mailbox "INBOX" SHOULD be in the default set of mailboxes + that the client considers interesting. However, providing the + ability to ignore INBOX for a particular session or client may be + valuable for some mail filtering strategies. + + + + + + +Melnikov Informational [Page 6] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + 4) On step d-2-II, the client also finds out about changes to the + flags of messages that the client already has in its local cache, + and about messages in the local cache that no longer exist on the + server (i.e., messages that have been expunged). + + 5) "Interesting" messages are those messages that the synchronization + program thinks the human wants to have cached locally, based on + the configuration and the data retrieved in step b. + + 6) A disconnected IMAP client is a special case of an IMAP client, so + it MUST be able to handle any "unexpected" unsolicited responses, + like EXISTS and EXPUNGE, at any time. The disconnected client MAY + ignore EXPUNGE response during "client-to-server" synchronization + phase (step c). + + The rest of this discussion will focus primarily on the + synchronization issues for a single mailbox. + +4. Mailbox Synchronization Steps and Strategies + +4.1. Checking UID Validity + + The "UID validity" of a mailbox is a number returned in an + UIDVALIDITY response code in an OK untagged response at mailbox + selection time. The UID validity value changes between sessions when + UIDs fail to persist between sessions. + + Whenever the client selects a mailbox, the client must compare the + returned UID validity value with the value stored in the local cache. + If the UID validity values differ, the UIDs in the client's cache are + no longer valid. The client MUST then empty the local cache of that + mailbox and remove any pending "actions" that refer to UIDs in that + mailbox. The client MAY also issue a warning to the human. The + client MUST NOT cancel any scheduled uploads (i.e., APPENDs) for the + mailbox. + + Note that UIDVALIDITY is not only returned on a mailbox selection. + The COPYUID and APPENDUID response codes defined in the [UIDPLUS] + extension (see also 4.2.2) and the UIDVALIDITY STATUS response data + item also contain a UIDVALIDITY value for some other mailbox. The + client SHOULD behave as described in the previous paragraph (but it + should act on the other mailbox's cache), no matter how it obtained + the UIDVALIDITY value. + + + + + + + + +Melnikov Informational [Page 7] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + +4.2. Synchronizing Local Changes with the Server + +4.2.1. Uploading Messages to the Mailbox + + Two of the most common examples of operations resulting in message + uploads are: + + 1) Saving a draft message + + 2) Copying a message between remote mailboxes on two different IMAP + servers or a local mailbox and a remote mailbox. + + Message upload is performed with the APPEND command. A message + scheduled to be uploaded has no UID associated with it, as all UIDs + are assigned by the server. The APPEND command will effectively + associate a UID with the uploaded message that can be stored in the + local cache for future reference. However, [IMAP4] doesn't describe + a simple mechanism to discover the message UID by just performing the + APPEND command. In order to discover the UID, the client can do one + of the following: + + 1) Remove the uploaded message from cache. Then, use the mechanism + described in 4.3 to fetch the information about the uploaded + message as if it had been uploaded by some other client. + + 2) Try to fetch header information as described in 4.2.2 in order to + find a message that corresponds to the uploaded message. One + strategy for doing this is described in 4.2.2. + + Case 1 describes a not particularly smart client. + + C: A003 APPEND Drafts (\Seen $MDNSent) {310} + S: + Ready for literal data + C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) + C: From: Fred Foobar <foobar@blt.example.COM> + C: Subject: afternoon meeting + C: To: mooch@owatagu.siam.edu + C: Message-Id: <B27397-0100000@blt.example.COM> + C: MIME-Version: 1.0 + C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII + C: + C: Hello Joe, do you think we can meet at 3:30 tomorrow? + C: + S: A003 OK APPEND Completed + + Fortunately, there is a simpler way to discover the message UID in + the presence of the [UIDPLUS] extension: + + + + +Melnikov Informational [Page 8] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + C: A003 APPEND Drafts (\Seen $MDNSent) {310} + S: + Ready for literal data + C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) + C: From: Fred Foobar <foobar@blt.example.COM> + C: Subject: afternoon meeting + C: To: mooch@owatagu.siam.edu + C: Message-Id: <B27397-0100000@blt.example.COM> + C: MIME-Version: 1.0 + C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII + C: + C: Hello Joe, do you think we can meet at 3:30 tomorrow? + C: + S: A003 OK [APPENDUID 1022843275 77712] APPEND completed + + The UID of the appended message is the second parameter of APPENDUID + response code. + +4.2.2. Optimizing "move" and "copy" Operations + + Practical experience with IMAP and other mailbox access protocols + that support multiple mailboxes suggests that moving a message from + one mailbox to another is an extremely common operation. + +4.2.2.1. Moving a Message between Two Mailboxes on the Same Server + + In IMAP4, a "move" operation between two mailboxes on the same server + is really a combination of a COPY operation and a STORE +FLAGS + (\Deleted) operation. This makes good protocol sense for IMAP, but + it leaves a simple-minded disconnected client in the silly position + of deleting and possibly expunging its cached copy of a message, then + fetching an identical copy via the network. + + However, the presence of the UIDPLUS extension in the server can + help: + + C: A001 UID COPY 567,414 "Interesting Messages" + S: A001 OK [COPYUID 1022843275 414,567 5:6] Completed + + This tells the client that the message with UID 414 in the current + mailbox was successfully copied to the mailbox "Interesting Messages" + and was given the UID 5, and that the message with UID 567 was given + the UID 6. + + In the absence of UIDPLUS extension support in the server, the + following trick can be used. By including the Message-ID: header and + the INTERNALDATE data item as part of the descriptor, the client can + check the descriptor of a "new" message against messages that are + already in its cache and avoid fetching the extra copy. Of course, + + + +Melnikov Informational [Page 9] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + it's possible that the cost of checking to see if the message is + already in the local cache may exceed the cost of just fetching it, + so this technique should not be used blindly. If the MUA implements + a "move" command, it makes special provisions to use this technique + when it knows that a copy/delete sequence is the result of a "move" + command. + + Note that servers are not required (although they are strongly + encouraged with "SHOULD language") to preserve INTERNALDATE when + copying messages. + + Also note that since it's theoretically possible for this algorithm + to find the wrong message (given sufficiently malignant Message-ID + headers), implementers should provide a way to disable this + optimization, both permanently and on a message-by-message basis. + + Example 1: Copying a message in the absence of UIDPLUS extension. + + At some point in time the client has fetched the source message and + some information was cached: + + C: C021 UID FETCH <uids> (BODY.PEEK[] INTERNALDATE FLAGS) + ... + S: * 27 FETCH (UID 123 INTERNALDATE "31-May-2002 05:26:59 -0600" + FLAGS (\Draft $MDNSent) BODY[] {1036} + S: ... + S: Message-Id: <20040903110856.22a127cd@chardonnay> + S: ... + S: ...message body... + S: ) + ... + S: C021 OK fetch completed + + Later on, the client decides to copy the message: + + C: C035 UID COPY 123 "Interesting Messages" + S: C035 OK Completed + + As the server hasn't provided the COPYUID response code, the client + tries the optimization described above: + + C: C036 SELECT "Interesting Messages" + ... + C: C037 UID SEARCH ON 31-May-2002 HEADER + "Message-Id" "20040903110856.22a127cd@chardonnay" + S: SEARCH 12368 + S: C037 OK completed + + + + +Melnikov Informational [Page 10] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + Note that if the server has returned multiple UIDs in the SEARCH + response, the client MUST NOT use any of the returned UID. + +4.2.2.2. Moving a Message from a Remote Mailbox to a Local + + Moving a message from a remote mailbox to a local is done with FETCH + (that includes FLAGS and INTERNALDATE) followed by UID STORE <uid> + +FLAGS.SILENT (\Deleted): + + C: A003 UID FETCH 123 (BODY.PEEK[] INTERNALDATE FLAGS) + S: * 27 FETCH (UID 123 INTERNALDATE "31-May-2002 05:26:59 -0600" + FLAGS (\Seen $MDNSent) BODY[] + S: ...message body... + S: ) + S: A003 OK UID FETCH completed + C: A004 UID STORE <uid> +FLAGS.SILENT (\Deleted) + S: A004 STORE completed + + Note that there is no reason to fetch the message during + synchronization if it's already in the client's cache. Also, the + client SHOULD preserve delivery date in the local cache. + +4.2.2.3. Moving a Message from a Local Mailbox to a Remote + + Moving a message from a local mailbox to a remote is done with + APPEND: + + C: A003 APPEND Drafts (\Seen $MDNSent) "31-May-2002 05:26:59 -0600" + {310} + S: + Ready for literal data + C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) + C: From: Fred Foobar <foobar@blt.example.COM> + C: Subject: afternoon meeting + C: To: mooch@owatagu.siam.edu + C: Message-Id: <B27397-0100000@blt.example.COM> + C: MIME-Version: 1.0 + C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII + C: + C: Hello Joe, do you think we can meet at 3:30 tomorrow? + C: + S: A003 OK [APPENDUID 1022843275 77712] completed + + The client SHOULD specify the delivery date from the local cache in + the APPEND. + + If the [LITERAL+] extension is available, the client can save a + round-trip*: + + + + +Melnikov Informational [Page 11] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + C: A003 APPEND Drafts (\Seen $MDNSent) "31-May-2002 05:26:59 -0600" + {310+} + C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) + C: From: Fred Foobar <foobar@blt.example.COM> + C: Subject: afternoon meeting + C: To: mooch@owatagu.siam.edu + C: Message-Id: <B27397-0100000@blt.example.COM> + C: MIME-Version: 1.0 + C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII + C: + C: Hello Joe, do you think we can meet at 3:30 tomorrow? + C: + S: A003 OK [APPENDUID 1022843275 77712] completed + + * Note that there is a risk that the server will reject the message + due to its size. If this happens, the client will waste bandwidth + transferring the whole message. If the client wouldn't have used + the LITERAL+, this could have been avoided: + + C: A003 APPEND Drafts (\Seen $MDNSent) "31-May-2004 05:26:59 -0600" + {16777215} + S: A003 NO Sorry, message is too big + +4.2.2.4. Moving a Message between Two Mailboxes on Different Servers + + Moving a message between two mailbox on two different servers is a + combination of the operations described in 4.2.2.2 followed by the + operations described in 4.2.2.3. + +4.2.2.5. Uploading Multiple Messages to a Remote Mailbox with + MULTIAPPEND + + When there is a need to upload multiple messages to a remote mailbox + (e.g., as per 4.2.2.3), the presence of certain IMAP extensions may + significantly improve performance. One of them is [MULTIAPPEND]. + + For some mail stores, opening a mailbox for appending might be + expensive. [MULTIAPPEND] tells the server to open the mailbox once + (instead of opening and closing it "n" times per "n" messages to be + uploaded) and to keep it open while a group of messages is being + uploaded to the server. + + Also, if the server supports both [MULTIAPPEND] and [LITERAL+] + extensions, the entire upload is accomplished in a single + command/response round-trip. + + + + + + +Melnikov Informational [Page 12] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + Note: Client implementers should be aware that [MULTIAPPEND] performs + append of multiple messages atomically. This means, for example, if + there is not enough space to save "n"-th message (or the message has + invalid structure and is rejected by the server) after successful + upload of "n-1" messages, the whole upload operation fails, and no + message will be saved in the mailbox. Although this behavior might + be desirable in certain situations, it might not be what you want. + Otherwise, the client should use the regular APPEND command (Section + 4.2.2.3), possibly utilizing the [LITERAL+] extension. See also + Section 5.1 for discussions about error recovery. + + Note: MULTIAPPEND can be used together with the UIDPLUS extension in + a way similar to what was described in Section 4.2.1. [MULTIAPPEND] + extends the syntax of the APPENDUID response code to allow for + multiple message UIDs in the second parameter. + + Example 2: + + This example demonstrates the use of MULTIAPPEND together with + UIDPLUS (synchronization points where the client waits for + confirmations from the server are marked with "<--->"): + + C: A003 APPEND Jan-2002 (\Seen $MDNSent) "31-May-2002 05:26:59 -0600" + {310} + <---> + S: + Ready for literal data + C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) + C: From: Fred Foobar <foobar@blt.example.COM> + C: Subject: afternoon meeting + C: To: mooch@owatagu.siam.edu + C: Message-Id: <B27397-0100000@blt.example.COM> + C: MIME-Version: 1.0 + C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII + C: + C: Hello Joe, do you think we can meet at 3:30 tomorrow? + C: (\Seen) " 1-Jun-2002 22:43:04 -0800" {286} + <---> + S: + Ready for literal data + C: Date: Mon, 7 Feb 1994 22:43:04 -0800 (PST) + C: From: Joe Mooch <mooch@OWaTaGu.siam.EDU> + C: Subject: Re: afternoon meeting + C: To: foobar@blt.example.com + C: Message-Id: <a0434793874930@OWaTaGu.siam.EDU> + C: MIME-Version: 1.0 + C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII + C: + C: 3:30 is fine with me. + C: + + + +Melnikov Informational [Page 13] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + S: A003 OK [APPENDUID 1022843275 77712,77713] completed + + The upload takes 3 round-trips. + + Example 3: + + In this example, Example 2 was modified for the case when the server + supports MULTIAPPEND, LITERAL+, and UIDPLUS. The upload takes only 1 + round-trip. + + C: A003 APPEND Jan-2002 (\Seen $MDNSent) "31-May-2002 05:26:59 -0600" + {310+} + C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST) + C: From: Fred Foobar <foobar@blt.example.COM> + C: Subject: afternoon meeting + C: To: mooch@owatagu.siam.edu + C: Message-Id: <B27397-0100000@blt.example.COM> + C: MIME-Version: 1.0 + C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII + C: + C: Hello Joe, do you think we can meet at 3:30 tomorrow? + C: (\Seen) " 1-Jun-2002 22:43:04 -0800" {286+} + C: Date: Mon, 7 Feb 1994 22:43:04 -0800 (PST) + C: From: Joe Mooch <mooch@OWaTaGu.siam.EDU> + C: Subject: Re: afternoon meeting + C: To: foobar@blt.example.com + C: Message-Id: <a0434793874930@OWaTaGu.siam.EDU> + C: MIME-Version: 1.0 + C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII + C: + C: 3:30 is fine with me. + C: + S: A003 OK [APPENDUID 1022843275 77712,77713] completed + +4.2.3. Replaying Local Flag Changes + + The disconnected client uses the STORE command to synchronize local + flag state with the server. The disconnected client SHOULD use + +FLAGS.SILENT or -FLAGS.SILENT in order to set or unset flags + modified by the user while offline. The FLAGS form MUST NOT be used, + as there is a risk that this will overwrite flags on the server that + have been changed by some other client. + + Example 4: + + For the message with UID 15, the disconnected client stores the + following flags \Seen and $Highest. The flags were modified on the + server by some other client: \Seen, \Answered, and $Highest. While + + + +Melnikov Informational [Page 14] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + offline, the user requested that the $Highest flags be removed and + that the \Deleted flag be added. The flag synchronization sequence + for the message should look like: + + C: A001 UID STORE 15 +FLAGS.SILENT (\Deleted) + S: A001 STORE completed + C: A002 UID STORE 15 -FLAGS.SILENT ($Highest) + S: A002 STORE completed + + If the disconnected client is able to store an additional binary + state information (or a piece of information that can take a value + from a predefined set of values) in the local cache of an IMAP + mailbox or in a local mailbox (e.g., message priority), and if the + server supports storing of arbitrary keywords, the client MUST use + keywords to store this state on the server. + + Example 5: + + Imagine a speculative mail client that can mark a message as one of + work-related ($Work), personal ($Personal), or spam ($Spam). In + order to mark a message as personal, the client issues: + + C: A001 UID STORE 15 +FLAGS.SILENT ($Personal) + S: A001 STORE completed + C: A002 UID STORE 15 -FLAGS.SILENT ($Work $Spam) + S: A002 STORE completed + + In order to mark the message as not work, not personal and not spam, + the client issues: + + C: A003 UID STORE 15 -FLAGS.SILENT ($Personal $Work $Spam) + S: A003 STORE completed + +4.2.4. Processing Mailbox Compression (EXPUNGE) Requests + + A naive disconnected client implementation that supports compressing + a mailbox while offline may decide to issue an EXPUNGE command to the + server in order to expunge messages marked \Deleted. The problem + with this command during synchronization is that it permanently + erases all messages with the \Deleted flag set, i.e., even those + messages that were marked as \Deleted on the server while the user + was offline. Doing this might result in an unpleasant surprise for + the user. + + Fortunately the [UIDPLUS] extension can help in this case as well. + The extension introduces UID EXPUNGE command, that, unlike EXPUNGE, + takes a UID set parameter, that lists UIDs of all messages that can + be expunged. When processing this command the server erases only + + + +Melnikov Informational [Page 15] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + messages with \Deleted flag listed in the UID list. Thus, messages + not listed in the UID set will not be expunged even if they have the + \Deleted flag set. + + Example 6: + + While the user was offline, 3 messages with UIDs 7, 27, and 65 were + marked \Deleted when the user requested to compress the open mailbox. + Another client marked a message \Deleted on the server (UID 34). + During synchronization, the disconnected client issues: + + C: A001 UID EXPUNGE 7,27,65 + S: * ... EXPUNGE + S: * ... EXPUNGE + S: * ... EXPUNGE + S: A001 UID EXPUNGE completed + + If another client issues UID SEARCH DELETED command (to find all + messages with the \Deleted flag) before and after the UID EXPUNGE, it + will get: + + Before: + + C: B001 UID SEARCH DELETED + S: * SEARCH 65 34 27 7 + S: B001 UID SEARCH completed + + After: + + C: B002 UID SEARCH DELETED + S: * SEARCH 34 + S: B002 UID SEARCH completed + + In the absence of the [UIDPLUS] extension, the following sequence of + commands can be used as an approximation. Note: It's possible for + another client to mark additional messages as deleted while this + sequence is being performed. In this case, these additional messages + will be expunged as well. + + 1) Find all messages marked \Deleted on the server. + + C: A001 UID SEARCH DELETED + S: * SEARCH 65 34 27 7 + S: A001 UID SEARCH completed + + 2) Find all messages that must not be erased (for the previous + example the list will consist of the message with UID 34). + + + + +Melnikov Informational [Page 16] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + 3) Temporarily remove \Deleted flag on all messages found in step 2. + + C: A002 UID STORE 34 -FLAGS.SILENT (\Deleted) + S: A002 UID STORE completed + + 4) Expunge the mailbox. + + C: A003 EXPUNGE + S: * 20 EXPUNGE + S: * 7 EXPUNGE + S: * 1 EXPUNGE + S: A003 EXPUNGE completed + + Here, the message with UID 7 has message number 1, with UID 27 has + message number 7, and with UID 65 has message number 20. + + 5) Restore \Deleted flag on all messages found when performing step + 2. + + C: A004 UID STORE 34 +FLAGS.SILENT (\Deleted) + S: A004 UID STORE completed + +4.2.5. Closing a Mailbox + + When the disconnected client has to close a mailbox, it should not + use the CLOSE command, because CLOSE does a silent EXPUNGE. (Section + 4.2.4 explains why EXPUNGE should not be used by a disconnected + client.) It is safe to use CLOSE only if the mailbox was opened with + EXAMINE. + + If the mailbox was opened with SELECT, the client can use one of the + following commands to implicitly close the mailbox and prevent the + silent expunge: + + 1) UNSELECT - This is a command described in [UNSELECT] that works as + CLOSE, but doesn't cause the silent EXPUNGE. This command is + supported by the server if it reports UNSELECT in its CAPABILITY + list. + + 2) SELECT <another_mailbox> - SELECT causes implicit CLOSE without + EXPUNGE. + + 3) If the client intends to issue LOGOUT after closing the mailbox, + it may just issue LOGOUT, because LOGOUT causes implicit CLOSE + without EXPUNGE as well. + + 4) SELECT <non_existing_mailbox> - If the client knows a mailbox that + doesn't exist or can't be selected, it MAY SELECT it. + + + +Melnikov Informational [Page 17] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + If the client opened the mailbox with SELECT and just wants to avoid + implicit EXPUNGE without closing the mailbox, it may also use the + following: + + 5) EXAMINE <mailbox> - Reselect the same mailbox in read-only mode. + +4.3. Details of "Normal" Synchronization of a Single Mailbox + + The most common form of synchronization is where the human trusts the + integrity of the client's copy of the state of a particular mailbox + and simply wants to bring the client's cache up to date so that it + accurately reflects the mailbox's current state on the server. + +4.3.1. Discovering New Messages and Changes to Old Messages + + Let <lastseenuid> represent the highest UID that the client knows + about in this mailbox. Since UIDs are allocated in strictly + ascending order, this is simply the UID of the last message in the + mailbox that the client knows about. Let <lastseenuid+1> represent + <lastseenuid>'s UID plus one. Let <descriptors> represent a list + consisting of all the FETCH data item items that the implementation + considers part of the descriptor; at a minimum this is just the FLAGS + data item, but it usually also includes BODYSTRUCTURE and + RFC822.SIZE. At this step, <descriptors> SHOULD NOT include RFC822. + + With no further information, the client can issue the following two + commands: + + tag1 UID FETCH <lastseenuid+1>:* <descriptors> + tag2 UID FETCH 1:<lastseenuid> FLAGS + + The first command will request some information about "new" messages + (i.e., messages received by the server since the last + synchronization). It will also allow the client to build a message + number to UID map (only for new messages). The second command allows + the client to + + 1) update cached flags for old messages; + + 2) find out which old messages got expunged; and + + 3) build a mapping between message numbers and UIDs (for old + messages). + + The order here is significant. We want the server to start returning + the list of new message descriptors as fast as it can, so that the + client can start issuing more FETCH commands, so we start out by + asking for the descriptors of all the messages we know the client + + + +Melnikov Informational [Page 18] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + cannot possibly have cached yet. The second command fetches the + information we need to determine what changes may have occurred to + messages that the client already has cached. Note that the former + command should only be issued if the UIDNEXT value cached by the + client differs from the one returned by the server. Once the client + has issued these two commands, there's nothing more the client can do + with this mailbox until the responses to the first command start + arriving. A clever synchronization program might use this time to + fetch its local cache state from disk or to start the process of + synchronizing another mailbox. + + The following is an example of the first FETCH: + + C: A011 UID fetch 131:* (FLAGS BODYSTRUCTURE INTERNALDATE + RFC822.SIZE) + + Note 1: The first FETCH may result in the server's sending a huge + volume of data. A smart disconnected client should use message + ranges (see also Section 3.2.1.2 of [RFC2683]), so that the user is + able to execute a different operation between fetching information + for a group of new messages. + + Example 7: + + Knowing the new UIDNEXT returned by the server on SELECT or EXAMINE + (<uidnext>), the client can split the UID range + <lastseenuid+1>:<uidnext> into groups, e.g., 100 messages. After + that, the client can issue: + + C: A011 UID fetch <lastseenuid+1>:<lastseenuid+100> + (FLAGS BODYSTRUCTURE INTERNALDATE RFC822.SIZE) + ... + C: A012 UID fetch <lastseenuid+101>:<lastseenuid+200> + (FLAGS BODYSTRUCTURE INTERNALDATE RFC822.SIZE) + ... + ... + C: A0FF UID fetch <lastseenuid+901>:<uidnext> + (FLAGS BODYSTRUCTURE INTERNALDATE RFC822.SIZE) + + Note that unless a SEARCH command is issued, it is impossible to + determine how many messages will fall into a subrange, as UIDs are + not necessarily contiguous. + + Note 2: The client SHOULD ignore any unsolicited EXPUNGE responses + received during the first FETCH command. EXPUNGE responses contain + message numbers that are useless to a client that doesn't have the + message-number-to-UID translation table. + + + + +Melnikov Informational [Page 19] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + The second FETCH command will result in zero or more untagged fetch + responses. Each response will have a corresponding UID FETCH data + item. All messages that didn't have a matching untagged FETCH + response MUST be removed from the local cache. + + For example, if the <lastseenuid> had a value 15000 and the local + cache contained 3 messages with the UIDs 12, 777, and 14999, + respectively, then after receiving the following responses from the + server, the client must remove the message with UID 14999 from its + local cache. + + S: * 1 FETCH (UID 12 FLAGS (\Seen)) + S: * 2 FETCH (UID 777 FLAGS (\Answered \Deleted)) + + Note 3: If the client is not interested in flag changes (i.e., the + client only wants to know which old messages are still on the + server), the second FETCH command can be substituted with: + + tag2 UID SEARCH UID 1:<lastseenuid> + + This command will generate less traffic. However, an implementor + should be aware that in order to build the mapping table from message + numbers to UIDs, the output of the SEARCH command MUST be sorted + first, because there is no requirement for a server to return UIDs in + SEARCH response in any particular order. + +4.3.2. Searching for "Interesting" Messages. + + This step is performed entirely on the client (from the information + received in the step described in 4.3.1), entirely on the server, or + on some combination of both. The decision on what is an + "interesting" message is up to the client software and the human. + One easy criterion that should probably be implemented in any client + is whether the message is "too big" for automatic retrieval, where + "too big" is a parameter defined in the client's configuration. + + Another commonly used criterion is the age of a message. For + example, the client may choose to download only messages received in + the last week (in this case, <date> would be today's date minus 7 + days): + + tag3 UID SEARCH UID <uidset> SINCE <date> + + Keep in mind that a date search disregards time and time zone. The + client can avoid doing this search if it specified INTERNALDATE in + <descriptors> on the step described in 4.3.1. If the client did, it + can perform the local search on its message cache. + + + + +Melnikov Informational [Page 20] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + At this step, the client also decides what kind of information about + a particular message to fetch from the server. In particular, even + for a message that is considered "too big", the client MAY choose to + fetch some part(s) of it. For example, if the message is a + multipart/mixed containing a text part and a MPEG attachment, there + is no reason for the client not to fetch the text part. The decision + of which part should or should not be fetched can be based on the + information received in the BODYSTRUCTURE FETCH response data item + (i.e., if BODYSTRUCTURE was included in <descriptors> on the step + described in 4.3.1). + +4.3.3. Populating Cache with "Interesting" Messages. + + Once the client has found out which messages are "interesting", it + can start issuing appropriate FETCH commands for "interesting" + messages or parts thereof. + + Note that fetching a message into the disconnected client's local + cache does NOT imply that the human has (or even will) read the + message. Thus, the synchronization program for a disconnected client + should always be careful to use the .PEEK variants of the FETCH data + items that implicitly set the \Seen flag. + + Once the last descriptor has arrived and the last FETCH command has + been issued, the client simply needs to process the incoming fetch + items and use them to update the local message cache. + + In order to avoid deadlock problems, the client must give processing + of received messages priority over issuing new FETCH commands during + this synchronization process. This may necessitate temporary local + queuing of FETCH requests that cannot be issued without causing a + deadlock. In order to achieve the best use of the "expensive" + network connection, the client will almost certainly need to pay + careful attention to any flow-control information that it can obtain + from the underlying transport connection (usually a TCP connection). + + Note: The requirement stated in the previous paragraph might result + in an unpleasant user experience, if followed blindly. For example, + the user might be unwilling to wait for the client to finish + synchronization before starting to process the user's requests. A + smart disconnected client should allow the user to perform requested + operations in between IMAP commands that are part of the + synchronization process. See also Note 1 in Section 4.3.1. + + + + + + + + +Melnikov Informational [Page 21] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + Example 8: + + After fetching a message BODYSTRUCTURE, the client discovers a + complex MIME message. Then, it decides to fetch MIME headers of the + nested MIME messages and some body parts. + + C: A011 UID fetch 11 (BODYSTRUCTURE) + S: ... + C: A012 UID fetch 11 (BODY[HEADER] BODY[1.MIME] BODY[1.1.MIME] + BODY[1.2.MIME] BODY[2.MIME] BODY[3.MIME] BODY[4.MIME] + BODY[5.MIME] BODY[6.MIME] BODY[7.MIME] BODY[8.MIME] BODY[9.MIME] + BODY[10.MIME] BODY[11.MIME] BODY[12.MIME] BODY[13.MIME] + BODY[14.MIME] BODY[15.MIME] BODY[16.MIME] BODY[17.MIME] + BODY[18.MIME] BODY[19.MIME] BODY[20.MIME] BODY[21.MIME]) + S: ... + C: A013 UID fetch 11 (BODY[1.1] BODY[1.2]) + S: ... + C: A014 UID fetch 11 (BODY[3] BODY[4] BODY[5] BODY[6] BODY[7] BODY[8] + BODY[9] BODY[10] BODY[11] BODY[13] BODY[14] BODY[15] BODY[16] + BODY[21]) + S: ... + +4.3.4. User-Initiated Synchronization + + After the client has finished the main synchronization process as + described in Sections 4.3.1-4.3.3, the user may optionally request + additional synchronization steps while the client is still online. + This is not any different from the process described in Sections + 4.3.2 and 4.3.3. + + Typical examples are: + + 1) fetch all messages selected in UI. + 2) fetch all messages marked as \Flagged on the server. + +4.4. Special Case: Descriptor-Only Synchronization + + For some mailboxes, fetching the descriptors might be the entire + synchronization step. Practical experience with IMAP has shown that + a certain class of mailboxes (e.g., "archival" mailboxes) are used + primarily for long-term storage of important messages that the human + wants to have instantly available on demand but does not want + cluttering up the disconnected client's cache at any other time. + Messages in this kind of mailbox would be fetched exclusively by + explicit actions queued by the local MUA. Thus, the only + synchronization desirable on this kind of mailbox is fetching enough + descriptor information for the user to be able to identify messages + for subsequent download. + + + +Melnikov Informational [Page 22] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + Special mailboxes that receive messages from a high volume, low + priority mailing list might also be in this category, at least when + the human is in a hurry. + +4.5. Special Case: Fast New-Only Synchronization + + In some cases, the human might be in such a hurry that he or she + doesn't care about changes to old messages, just about new messages. + In this case, the client can skip the UID FETCH command that obtains + the flags and UIDs for old messages (1:<lastseenuid>). + +4.6. Special Case: Blind FETCH + + In some cases, the human may know (for whatever reason) that he or + she always wants to fetch any new messages in a particular mailbox, + unconditionally. In this case, the client can just fetch the + messages themselves, rather than just the descriptors, by using a + command like: + + tag1 UID FETCH <lastseenuid+1>:* (FLAGS BODY.PEEK[]) + + Note that this example ignores the fact that the messages can be + arbitrary long. The disconnected client MUST always check for + message size before downloading, unless explicitly told otherwise. A + well-behaved client should instead use something like the following: + + 1) Issue "tag1 UID FETCH <lastseenuid+1>:* (FLAGS RFC822.SIZE)". + + 2) From the message sizes returned in step 1, construct UID set + <required_messages>. + + 3) Issue "tag2 UID FETCH <required_messages> (BODY.PEEK[])". + + or + + 1) Issue "tag1 UID FETCH <lastseenuid+1>:* (FLAGS)". + + 2) Construct UID set <old_uids> from the responses of step 1. + + 3) Issue "tag2 SEARCH UID <old_uids> SMALLER <message_limit>". + Construct UID set <required_messages> from the result of the + SEARCH command. + + 4) Issue "tag3 UID FETCH <required_messages> (BODY.PEEK[])". + + + + + + + +Melnikov Informational [Page 23] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + or + + 1) Issue "tag1 UID FETCH <lastseenuid+1>:* (FLAGS + BODY.PEEK[]<0.<length>>)", where <length> should be replaced with + the maximal message size the client is willing to download. + + Note: In response to such a command, the server will only return + partial data if the message is longer than <length>. It will + return the full message data for any message whose size is smaller + than or equal to <length>. In the former case, the client will + not be able to extract the full MIME structure of the message from + the truncated data, so the client should include BODYSTRUCTURE in + the UID FETCH command as well. + +5. Implementation Considerations + + Below are listed some common implementation pitfalls that should be + considered when implementing a disconnected client. + + 1) Implementing fake UIDs on the client. + + A message scheduled to be uploaded has no UID, as UIDs are + selected by the server. The client may implement fake UIDs + internally in order to reference not-yet-uploaded messages in + further operations. (For example, a message could be scheduled to + be uploaded, but subsequently marked as deleted or copied to + another mailbox). Here, the client MUST NOT under any + circumstances send these fake UIDs to the server. Also, client + implementers should be reminded that according to [IMAP4] a UID is + a 32-bit unsigned integer excluding 0. So, both 4294967295 and + 2147483648 are valid UIDs, and 0 and -1 are both invalid. Some + disconnected mail clients have been known to send negative numbers + (e.g., "-1") as message UIDs to servers during synchronization. + + Situation 1: The user starts composing a new message, edits it, + saves it, continues to edit it, and saves it again. + + A disconnected client may record in its replay log (log of + operations to be replayed on the server during synchronization) + the sequence of operations as shown below. For the purpose of + this situation, we assume that all draft messages are stored in + the mailbox called Drafts on an IMAP server. We will also use the + following conventions: <old_uid> is the UID of the intermediate + version of the draft when it was saved for the first time. This + is a fake UID generated on the client. <new_uid> is the UID of + the final version of the draft. This is another fake UID + generated on the client. + + + + +Melnikov Informational [Page 24] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + 1) APPEND Drafts (\Seen $MDNSent \Drafts) {<nnn>} + ...first version of the message follows... + + 2) APPEND Drafts (\Seen $MDNSent \Drafts) {<mmm>} + ...final version of the message follows... + + 3) STORE <old_uid> +FLAGS (\Deleted) + + Step 1 corresponds to the first attempt to save the draft message, + step 2 corresponds to the second attempt to save the draft + message, and step 3 deletes the first version of the draft message + saved in step 1. + + A naive disconnected client may send the command in step 3 without + replacing the fake client generated <old_uid> with the value + returned by the server in step 1. A server will probably reject + this command, which will make the client believe that the + synchronization sequence has failed. + + 2) Section 5.1 discusses common implementation errors related to + error recovery during playback. + + 3) Don't assume that the disconnected client is the only client used + by the user. + + Situation 2: Some clients may use the \Deleted flag as an + indicator that the message should not appear in the user's view. + Usage of the \Deleted flag for this purpose is not safe, as other + clients (e.g., online clients) might EXPUNGE the mailbox at any + time. + + 4) Beware of data dependencies between synchronization operations. + + It might be very tempting for a client writer to perform some + optimizations on the playback log. Such optimizations might + include removing redundant operations (for example, see + optimization 2 in Section 5.3), or their reordering. + + It is not always safe to reorder or remove redundant operations + during synchronization because some operations may have + dependencies (as Situation 3 demonstrates). So, if in doubt, + don't do this. + + Situation 3: The user copies a message out of a mailbox and then + deletes the mailbox. + + + + + + +Melnikov Informational [Page 25] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + C: A001 SELECT Old-Mail + S: ... + C: A002 UID COPY 111 ToDo + S: A002 OK [COPYUID 1022843345 111 94] Copy completed + ... + C: A015 CLOSE + S: A015 OK Completed + C: A016 DELETE Old-Mail + S: A016 OK Mailbox deletion completed successfully + + If the client performs DELETE (tag A016) first and COPY (tag A002) + second, then the COPY fails. Also, the message that the user so + carefully copied into another mailbox has been lost. + +5.1. Error Recovery during Playback + + Error recovery during synchronization is one of the trickiest parts + to get right. Below, we will discuss certain error conditions and + suggest possible choices for handling them. + + 1) Lost connection to the server. + + The client MUST remember the current position in the playback + (replay) log and replay it starting from the interrupted operation + (the last command issued by the client, but not acknowledged by + the server) the next time it successfully connects to the same + server. If the connection was lost while executing a non- + idempotent IMAP command (see the definition in Section 1), then + when the client is reconnected, it MUST make sure that the + interrupted command was indeed not executed. If it wasn't + executed, the client must restart playback from the interrupted + command, otherwise from the following command. + + Upon reconnect, care must be taken in order to properly reapply + logical operations that are represented by multiple IMAP commands, + e.g., UID EXPUNGE emulation when UID EXPUNGE is not supported by + the server (see Section 4.2.4). + + Once the client detects that the connection to the server was + lost, it MUST stop replaying its log. There are existing + disconnected clients that, to the great annoyance of users, pop up + an error dialog for each and every playback operation that fails. + + 2) Copying/appending messages to a mailbox that doesn't exist. (The + server advertises this condition by sending the TRYCREATE response + code in the tagged NO response to the APPEND or COPY command.) + + + + + +Melnikov Informational [Page 26] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + The user should be advised about the situation and be given one of + the following choices: + + a) Try to recreate a mailbox. + b) Copy/upload messages to another mailbox. + c) Skip copy/upload. + d) Abort replay. + + 3) Copying messages from a mailbox that doesn't exist, or renaming or + getting/changing ACLs [ACL] on a mailbox that doesn't exist: + + a) Skip operation. + b) Abort replay. + + 4) Deleting mailboxes or deleting/expunging messages that no longer + exist. + + This is actually is not an error and should be ignored by the + client. + + 5) Performing operations on messages that no longer exist. + + a) Skip operation. + b) Abort replay. + + In the case of changing flags on an expunged message, the client + should silently ignore the error. + + Note 1: Several synchronization operations map to multiple IMAP + commands (for example, "move" described in 4.2.2). The client must + guarantee atomicity of each such multistep operation. For example, + when performing a "move" between two mailboxes on the same server, if + the server is unable to copy messages, the client MUST NOT attempt to + set the \Deleted flag on the messages being copied, let alone expunge + them. However, the client MAY consider that move operation to have + succeeded even if the server was unable to set the \Deleted flag on + copied messages. + + Note 2: Many synchronization operations have data dependencies. A + failed operation must cause all dependent operations to fail as well. + The client should check this and MUST NOT try to perform all + dependent operations blindly (unless the user corrected the original + problem). For example, a message may be scheduled to be appended to + a mailbox on the server and later on the appended message may be + copied to another mailbox. If the APPEND operation fails, the client + must not attempt to COPY the failed message later on. (See also + Section 5, Situation 3). + + + + +Melnikov Informational [Page 27] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + +5.2. Quality of Implementation Issues + + Below, some quality of implementation issues are listed for + disconnected clients. They will help to write a disconnected client + that works correctly, performs synchronization as quickly as possible + (and thus can make the user happier as well as save her some money), + and minimizes the server load: + + 1) Don't lose information. + + No matter how smart your client is in other areas, if it loses + information, users will get very upset. + + 2) Don't do work unless explicitly asked. Be flexible. Ask all + questions BEFORE starting synchronization, if possible. + + 3) Minimize traffic. + + The client MUST NOT issue a command if the client already received + the required information from the server. + + The client MUST make use of UIDPLUS extension if it is supported + by the server. + + See also optimization 1 in Section 5.3. + + 4) Minimize the number of round-trips. + + Round-trips kill performance, especially on links with high + latency. Sections 4.2.2.5 and 5.2 give some advice on how to + minimize the number of round-trips. + + See also optimization 1 in Section 5.3. + +5.3. Optimizations + + Some useful optimizations are described in this section. A + disconnected client that supports the recommendations listed below + will give the user a more pleasant experience. + + 1) The initial OK or PREAUTH responses may contain the CAPABILITY + response code as described in Section 7.1 of [IMAP4]. This + response code gives the same information as returned by the + CAPABILITY command*. A disconnected client that pays attention to + this response code can avoid sending CAPABILITY command and will + save a round-trip. + + + + + +Melnikov Informational [Page 28] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + * Note: Some servers report in the CAPABILITY response code + extensions that are only relevant in unauthenticated state or in + all states. Such servers usually send another CAPABILITY + response code upon successful authentication using LOGIN or + AUTHENTICATE command (that negotiates no security layer; see + Section 6.2.2 of [IMAP4]). The CAPABILITY response code sent + upon successful LOGIN/AUTHENTICATE might be different from the + CAPABILITY response code in the initial OK response, as + extensions only relevant for unauthenticated state will not be + advertised, and some additional extensions available only in + authenticated and/or selected state will be. + + Example 9: + + S: * OK [CAPABILITY IMAP4REV1 LOGIN-REFERRALS STARTTLS + AUTH=DIGEST-MD5 AUTH=SRP] imap.example.com ready + C: 2 authenticate DIGEST-MD5 + S: 2 OK [CAPABILITY IMAP4REV1 IDLE NAMESPACE MAILBOX-REFERRALS SCAN + SORT THREAD=REFERENCES THREAD=ORDEREDSUBJECT MULTIAPPEND] + User authenticated (no layer) + + 2) An advanced disconnected client may choose to optimize its replay + log. For example, there might be some operations that are + redundant (the list is not complete): + + a) an EXPUNGE followed by another EXPUNGE or CLOSE; + b) changing flags (other than the \Deleted flag) on a message that + gets immediately expunged; + c) opening and closing the same mailbox. + + When optimizing, be careful about data dependencies between commands. + For example, if the client is wishing to optimize (see case b, above) + + tag1 UID STORE <uid1> +FLAGS (\Deleted) + ... + tag2 UID STORE <uid1> +FLAGS (\Flagged) + ... + tag3 UID COPY <uid1> "Backup" + ... + tag4 UID EXPUNGE <uid1> + + it can't remove the second UID STORE command because the message is + being copied before it gets expunged. + + In general, it might be a good idea to keep mailboxes open during + synchronization (see case c above), if possible. This can be more + easily achieved in conjunction with optimization 3 described below. + + + + +Melnikov Informational [Page 29] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + 3) Perform some synchronization steps in parallel, if possible. + + Several synchronization steps don't depend on each other and thus + can be performed in parallel. Because the server machine is + usually more powerful than the client machine and can perform some + operations in parallel, this may speed up the total time of + synchronization. + + In order to achieve such parallelization, the client will have to + open more than one connection to the same server. Client writers + should not forget about non-trivial cost associated with + establishing a TCP connection and performing an authentication. + The disconnected client MUST NOT use one connection per mailbox. + In most cases, it is sufficient to have two connections. The + disconnected client SHOULD avoid selecting the same mailbox in + more than one connection; see Section 3.1.1 of [RFC2683] for more + details. + + Any mailbox synchronization MUST start with checking the + UIDVALIDITY as described in Section 4.1 of this document. The + client MAY use STATUS command to check UID Validity of a non- + selected mailbox. This is preferable to opening many connections + to the same server to perform synchronization of multiple + mailboxes simultaneously. As described in Section 5.3.10 of + [IMAP4], this SHOULD NOT be used on the selected mailbox. + +6. IMAP Extensions That May Help + + The following extensions can save traffic and/or the number of + round-trips: + + 1) The use of [UIDPLUS] is discussed in Sections 4.1, 4.2.1, 4.2.2.1 + and 4.2.4. + + 2) The use of the MULTIAPPEND and LITERAL+ extensions for uploading + messages is discussed in Section 4.2.2.5. + + 3) Use the CONDSTORE extension (see Section 6.1) for quick flag + resynchronization. + +6.1. CONDSTORE Extension + + An advanced disconnected mail client should use the [CONDSTORE] + extension when it is supported by the server. The client must cache + the value from HIGHESTMODSEQ OK response code received on mailbox + opening and update it whenever the server sends MODSEQ FETCH data + items. + + + + +Melnikov Informational [Page 30] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + If the client receives NOMODSEQ OK untagged response instead of + HIGHESTMODSEQ, it MUST remove the last known HIGHESTMODSEQ value from + its cache and follow the more general instructions in Section 3. + + When the client opens the mailbox for synchronization, it first + compares UIDVALIDITY as described in step d-1 in Section 3. If the + cached UIDVALIDITY value matches the one returned by the server, the + client MUST compare the cached value of HIGHESTMODSEQ with the one + returned by the server. If the cached HIGHESTMODSEQ value also + matches the one returned by the server, then the client MUST NOT + fetch flags for cached messages, as they hasn't changed. If the + value on the server is higher than the cached one, the client MAY use + "SEARCH MODSEQ <cached-value>" to find all messages with flags + changed since the last time the client was online and had the mailbox + opened. Alternatively, the client MAY use "FETCH 1:* (FLAGS) + (CHANGEDSINCE <cached-value>)". The latter operation combines + searching for changed messages and fetching new information. + + In all cases, the client still needs to fetch information about new + messages (if requested by the user) as well as discover which + messages have been expunged. + + Step d ("Server-to-client synchronization") in Section 4 in the + presence of the CONDSTORE extension is amended as follows: + + d) "Server-to-client synchronization" - For each mailbox that + requires synchronization, do the following: + + 1a) Check the mailbox UIDVALIDITY (see section 4.1 for more + details) with SELECT/EXAMINE/STATUS. + + If the UIDVALIDITY value returned by the server differs, the + client MUST + + * empty the local cache of that mailbox; + * "forget" the cached HIGHESTMODSEQ value for the mailbox; + * remove any pending "actions" that refer to UIDs in that + mailbox (note that this doesn't affect actions performed on + client-generated fake UIDs; see Section 5); and + * skip steps 1b and 2-II; + + 1b) Check the mailbox HIGHESTMODSEQ. If the cached value is the + same as the one returned by the server, skip fetching message + flags on step 2-II, i.e., the client only has to find out + which messages got expunged. + + + + + + +Melnikov Informational [Page 31] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + 2) Fetch the current "descriptors". + + I) Discover new messages. + + II) Discover changes to old messages and flags for new messages + using + "FETCH 1:* (FLAGS) (CHANGEDSINCE <cached-value>)" or + "SEARCH MODSEQ <cached-value>". + + Discover expunged messages; for example, using + "UID SEARCH 1:<lastseenuid>". (All messages not returned + in this command are expunged.) + + 3) Fetch the bodies of any "interesting" messages that the client + doesn't already have. + + Example 10: + + The UIDVALIDITY value is the same, but the HIGHESTMODSEQ value + has changed on the server while the client was offline. + + C: A142 SELECT INBOX + S: * 172 EXISTS + S: * 1 RECENT + S: * OK [UNSEEN 12] Message 12 is first unseen + S: * OK [UIDVALIDITY 3857529045] UIDs valid + S: * OK [UIDNEXT 201] Predicted next UID + S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) + S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited + S: * OK [HIGHESTMODSEQ 20010715194045007] + S: A142 OK [READ-WRITE] SELECT completed + + After that, either: + + C: A143 UID FETCH 1:* (FLAGS) (CHANGEDSINCE 20010715194032001) + S: * 2 FETCH (UID 6 MODSEQ (20010715205008000) FLAGS (\Deleted)) + S: * 5 FETCH (UID 9 MODSEQ (20010715195517000) FLAGS ($NoJunk + $AutoJunk $MDNSent)) + ... + S: A143 OK FETCH completed + + or: + + + + + + + + + +Melnikov Informational [Page 32] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + + C: A143 UID SEARCH MODSEQ 20010715194032001 UID 1:20 + S: * SEARCH 6 9 11 12 18 19 20 23 (MODSEQ 20010917162500) + S: A143 OK Search complete + C: A144 UID SEARCH 1:20 + S: * SEARCH 6 9 ... + S: A144 OK FETCH completed + +7. Security Considerations + + It is believed that this document does not raise any new security + concerns that are not already present in the base [IMAP4] protocol, + and these issues are discussed in [IMAP4]. Additional security + considerations may be found in different extensions mentioned in this + document; in particular, in [UIDPLUS], [LITERAL+], [CONDSTORE], + [MULTIAPPEND], and [UNSELECT]. + + Implementers are also reminded about the importance of thorough + testing. + +8. References + +8.1. Normative References + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [IMAP4] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - + VERSION 4rev1", RFC 3501, March 2003. + + [UIDPLUS] Crispin, M., "Internet Message Access Protocol (IMAP) - + UIDPLUS extension", RFC 4315, December 2005. + + [LITERAL+] Myers, J., "IMAP4 non-synchronizing literals", RFC + 2088, January 1997. + + [CONDSTORE] Melnikov, A. and S. Hole, "IMAP Extension for + Conditional STORE Operation or Quick Flag Changes + Resynchronization", RFC 4551, June 2006. + + [MULTIAPPEND] Crispin, M., "Internet Message Access Protocol (IMAP) - + MULTIAPPEND Extension", RFC 3502, March 2003. + + [UNSELECT] Melnikov, A., "Internet Message Access Protocol (IMAP) + UNSELECT command", RFC 3691, February 2004. + + [RFC2683] Leiba, B., "IMAP4 Implementation Recommendations", RFC + 2683, September 1999. + + + + +Melnikov Informational [Page 33] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + +8.2. Informative References + + [ACL] Melnikov, A., "IMAP4 Access Control List (ACL) + Extension", RFC 4314, December 2005. + + [IMAP-MODEL] Crispin, M., "Distributed Electronic Mail Models in + IMAP4", RFC 1733, December 1994. + +9. Acknowledgements + + This document is based on version 01 of the text written by Rob + Austein in November 1994. + + The editor appreciates comments posted by Mark Crispin to the IMAP + mailing list and the comments/corrections/ideas received from Grant + Baillie, Cyrus Daboo, John G. Myers, Chris Newman, and Timo Sirainen. + + The editor would also like to thank the developers of Netscape + Messenger and Mozilla mail clients for providing examples of + disconnected mail clients that served as a base for many + recommendations in this document. + +Editor's Address + + Alexey Melnikov + Isode Limited + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex + TW12 2BX + United Kingdom + + Phone: +44 77 53759732 + EMail: alexey.melnikov@isode.com + + + + + + + + + + + + + + + + + +Melnikov Informational [Page 34] + +RFC 4549 Synch Ops for Disconnected IMAP4 Clients June 2006 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2006). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is provided by the IETF + Administrative Support Activity (IASA). + + + + + + + +Melnikov Informational [Page 35] + diff --git a/imap/docs/rfc/rfc4551.txt b/imap/docs/rfc/rfc4551.txt new file mode 100644 index 00000000..894b5109 --- /dev/null +++ b/imap/docs/rfc/rfc4551.txt @@ -0,0 +1,1403 @@ + + + + + + +Network Working Group A. Melnikov +Request for Comments: 4551 Isode Ltd. +Updates: 3501 S. Hole +Category: Standards Track ACI WorldWide/MessagingDirect + June 2006 + + + IMAP Extension for Conditional STORE Operation + or Quick Flag Changes Resynchronization + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2006). + +Abstract + + Often, multiple IMAP (RFC 3501) clients need to coordinate changes to + a common IMAP mailbox. Examples include different clients working on + behalf of the same user, and multiple users accessing shared + mailboxes. These clients need a mechanism to synchronize state + changes for messages within the mailbox. They must be able to + guarantee that only one client can change message state (e.g., + message flags) at any time. An example of such an application is use + of an IMAP mailbox as a message queue with multiple dequeueing + clients. + + The Conditional Store facility provides a protected update mechanism + for message state information that can detect and resolve conflicts + between multiple writing mail clients. + + The Conditional Store facility also allows a client to quickly + resynchronize mailbox flag changes. + + This document defines an extension to IMAP (RFC 3501). + + + + + + + + + +Melnikov & Hole Standards Track [Page 1] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + +Table of Contents + + 1. Introduction and Overview ................................. 3 + 2. Conventions Used in This Document ......................... 5 + 3. IMAP Protocol Changes ..................................... 6 + 3.1. New OK untagged responses for SELECT and EXAMINE ......... 6 + 3.1.1. HIGHESTMODSEQ response code ............................ 6 + 3.1.2. NOMODSEQ response code ................................. 7 + 3.2. STORE and UID STORE Commands ............................. 7 + 3.3 FETCH and UID FETCH Commands ..............................13 + 3.3.1. CHANGEDSINCE FETCH modifier ............................13 + 3.3.2. MODSEQ message data item in FETCH Command ..............14 + 3.4. MODSEQ search criterion in SEARCH ........................16 + 3.5. Modified SEARCH untagged response ........................17 + 3.6. HIGHESTMODSEQ status data items ..........................17 + 3.7. CONDSTORE parameter to SELECT and EXAMINE ................18 + 3.8. Additional quality of implementation issues ..............18 + 4. Formal Syntax .............................................19 + 5. Server implementation considerations ......................21 + 6. Security Considerations ...................................22 + 7. IANA Considerations .......................................22 + 8. References ................................................23 + 8.1. Normative References .....................................23 + 8.2. Informative References ...................................23 + 9. Acknowledgements ..........................................23 + + + + + + + + + + + + + + + + + + + + + + + + + + +Melnikov & Hole Standards Track [Page 2] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + +1. Introduction and Overview + + The Conditional STORE extension is present in any IMAP4 + implementation that returns "CONDSTORE" as one of the supported + capabilities in the CAPABILITY command response. + + An IMAP server that supports this extension MUST associate a positive + unsigned 64-bit value called a modification sequence (mod-sequence) + with every IMAP message. This is an opaque value updated by the + server whenever a metadata item is modified. The server MUST + guarantee that each STORE command performed on the same mailbox + (including simultaneous stores to different metadata items from + different connections) will get a different mod-sequence value. + Also, for any two successful STORE operations performed in the same + session on the same mailbox, the mod-sequence of the second completed + operation MUST be greater than the mod-sequence of the first + completed. Note that the latter rule disallows the use of the system + clock as a mod-sequence, because if system time changes (e.g., an NTP + [NTP] client adjusting the time), the next generated value might be + less than the previous one. + + Mod-sequences allow a client that supports the CONDSTORE extension to + determine if a message metadata has changed since some known moment. + Whenever the state of a flag changes (i.e., the flag is added where + previously it wasn't set, or the flag is removed and before it was + set) the value of the modification sequence for the message MUST be + updated. Adding the flag when it is already present or removing when + it is not present SHOULD NOT change the mod-sequence. + + When a message is appended to a mailbox (via the IMAP APPEND command, + COPY to the mailbox, or using an external mechanism) the server + generates a new modification sequence that is higher than the highest + modification sequence of all messages in the mailbox and assigns it + to the appended message. + + The server MAY store separate (per-message) modification sequence + values for different metadata items. If the server does so, per- + message mod-sequence is the highest mod-sequence of all metadata + items for the specified message. + + The server that supports this extension is not required to be able to + store mod-sequences for every available mailbox. Section 3.1.2 + describes how the server may act if a particular mailbox doesn't + support the persistent storage of mod-sequences. + + + + + + + +Melnikov & Hole Standards Track [Page 3] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + + This extension makes the following changes to the IMAP4 protocol: + + a) adds UNCHANGEDSINCE STORE modifier. + + b) adds the MODIFIED response code which should be used with an OK + response to the STORE command. (It can also be used in a NO + response.) + + c) adds a new MODSEQ message data item for use with the FETCH + command. + + d) adds CHANGEDSINCE FETCH modifier. + + e) adds a new MODSEQ search criterion. + + f) extends the syntax of untagged SEARCH responses to include + mod-sequence. + + g) adds new OK untagged responses for the SELECT and EXAMINE + commands. + + h) defines an additional parameter to SELECT/EXAMINE commands. + + i) adds the HIGHESTMODSEQ status data item to the STATUS command. + + A client supporting CONDSTORE extension indicates its willingness to + receive mod-sequence updates in all untagged FETCH responses by + issuing: + + - a SELECT or EXAMINE command with the CONDSTORE parameter, + - a STATUS (HIGHESTMODSEQ) command, + - a FETCH or SEARCH command that includes the MODSEQ message data + item, + - a FETCH command with the CHANGEDSINCE modifier, or + - a STORE command with the UNCHANGEDSINCE modifier. + + The server MUST include mod-sequence data in all subsequent untagged + FETCH responses (until the connection is closed), whether they were + caused by a regular STORE, a STORE with UNCHANGEDSINCE modifier, or + an external agent. + + This document uses the term "CONDSTORE-aware client" to refer to a + client that announces its willingness to receive mod-sequence updates + as described above. The term "CONDSTORE enabling command" will refer + any of the commands listed above. A future extension to this + document may extend the list of CONDSTORE enabling commands. A first + CONDSTORE enabling command executed in the session MUST cause the + + + + +Melnikov & Hole Standards Track [Page 4] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + + server to return HIGHESTMODSEQ (Section 3.1.1) unless the server has + sent NOMODSEQ (Section 3.1.2) response code when the currently + selected mailbox was selected. + + The rest of this document describes the protocol changes more + rigorously. + +2. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [KEYWORDS]. + + In examples, lines beginning with "S:" are sent by the IMAP server, + and lines beginning with "C:" are sent by the client. Line breaks + may appear in example commands solely for editorial clarity; when + present in the actual message, they are represented by "CRLF". + + Formal syntax is defined using ABNF [ABNF]. + + The term "metadata" or "metadata item" is used throughout this + document. It refers to any system or user-defined keyword. Future + documents may extend "metadata" to include other dynamic message + data. + + Some IMAP mailboxes are private, accessible only to the owning user. + Other mailboxes are not, either because the owner has set an Access + Control List [ACL] that permits access by other users, or because it + is a shared mailbox. Let's call a metadata item "shared" for the + mailbox if any changes to the metadata items are persistent and + visible to all other users accessing the mailbox. Otherwise, the + metadata item is called "private". Note that private metadata items + are still visible to all sessions accessing the mailbox as the same + user. Also note that different mailboxes may have different metadata + items as shared. + + See Section 1 for the definition of a "CONDSTORE-aware client" and a + "CONDSTORE enabling command". + + + + + + + + + + + + + +Melnikov & Hole Standards Track [Page 5] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + +3. IMAP Protocol Changes + +3.1. New OK Untagged Responses for SELECT and EXAMINE + + This document adds two new response codes, HIGHESTMODSEQ and + NOMODSEQ. One of those response codes MUST be returned in the OK + untagged response for a successful SELECT/EXAMINE command. + + When opening a mailbox, the server must check if the mailbox supports + the persistent storage of mod-sequences. If the mailbox supports the + persistent storage of mod-sequences and the mailbox open operation + succeeds, the server MUST send the OK untagged response including + HIGHESTMODSEQ response code. If the persistent storage for the + mailbox is not supported, the server MUST send the OK untagged + response including NOMODSEQ response code instead. + +3.1.1. HIGHESTMODSEQ Response Code + + This document adds a new response code that is returned in the OK + untagged response for the SELECT and EXAMINE commands. A server + supporting the persistent storage of mod-sequences for the mailbox + MUST send the OK untagged response including HIGHESTMODSEQ response + code with every successful SELECT or EXAMINE command: + + OK [HIGHESTMODSEQ <mod-sequence-value>] + + where <mod-sequence-value> is the highest mod-sequence value of + all messages in the mailbox. When the server changes UIDVALIDITY + for a mailbox, it doesn't have to keep the same HIGHESTMODSEQ for + the mailbox. + + A disconnected client can use the value of HIGHESTMODSEQ to check if + it has to refetch metadata from the server. If the UIDVALIDITY value + has changed for the selected mailbox, the client MUST delete the + cached value of HIGHESTMODSEQ. If UIDVALIDITY for the mailbox is the + same, and if the HIGHESTMODSEQ value stored in the client's cache is + less than the value returned by the server, then some metadata items + on the server have changed since the last synchronization, and the + client needs to update its cache. The client MAY use SEARCH MODSEQ + (Section 3.4) to find out exactly which metadata items have changed. + Alternatively, the client MAY issue FETCH with the CHANGEDSINCE + modifier (Section 3.3.1) in order to fetch data for all messages that + have metadata items changed since some known modification sequence. + + Example 1: + + C: A142 SELECT INBOX + S: * 172 EXISTS + + + +Melnikov & Hole Standards Track [Page 6] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + + S: * 1 RECENT + S: * OK [UNSEEN 12] Message 12 is first unseen + S: * OK [UIDVALIDITY 3857529045] UIDs valid + S: * OK [UIDNEXT 4392] Predicted next UID + S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) + S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited + S: * OK [HIGHESTMODSEQ 715194045007] + S: A142 OK [READ-WRITE] SELECT completed + +3.1.2. NOMODSEQ Response Code + + A server that doesn't support the persistent storage of mod-sequences + for the mailbox MUST send the OK untagged response including NOMODSEQ + response code with every successful SELECT or EXAMINE command. A + server that returned NOMODSEQ response code for a mailbox, which + subsequently receives one of the following commands while the mailbox + is selected: + + - a FETCH command with the CHANGEDSINCE modifier, + - a FETCH or SEARCH command that includes the MODSEQ message data + item, or + - a STORE command with the UNCHANGEDSINCE modifier + + MUST reject any such command with the tagged BAD response. + + Example 2: + + C: A142 SELECT INBOX + S: * 172 EXISTS + S: * 1 RECENT + S: * OK [UNSEEN 12] Message 12 is first unseen + S: * OK [UIDVALIDITY 3857529045] UIDs valid + S: * OK [UIDNEXT 4392] Predicted next UID + S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) + S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited + S: * OK [NOMODSEQ] Sorry, this mailbox format doesn't support + modsequences + S: A142 OK [READ-WRITE] SELECT completed + +3.2. STORE and UID STORE Commands + + This document defines the following STORE modifier (see Section 2.5 + of [IMAPABNF]): + + UNCHANGEDSINCE <mod-sequence> + + For each message specified in the message set, the server performs + the following. If the mod-sequence of any metadata item of the + + + +Melnikov & Hole Standards Track [Page 7] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + + message is equal or less than the specified UNCHANGEDSINCE value, + then the requested operation (as described by the message data + item) is performed. If the operation is successful, the server + MUST update the mod-sequence attribute of the message. An + untagged FETCH response MUST be sent, even if the .SILENT suffix + is specified, and the response MUST include the MODSEQ message + data item. This is required to update the client's cache with the + correct mod-sequence values. See Section 3.3.2 for more details. + + However, if the mod-sequence of any metadata item of the message + is greater than the specified UNCHANGEDSINCE value, then the + requested operation MUST NOT be performed. In this case, the + mod-sequence attribute of the message is not updated, and the + message number (or unique identifier in the case of the UID STORE + command) is added to the list of messages that failed the + UNCHANGESINCE test. + + When the server finished performing the operation on all the + messages in the message set, it checks for a non-empty list of + messages that failed the UNCHANGESINCE test. If this list is + non-empty, the server MUST return in the tagged response a + MODIFIED response code. The MODIFIED response code includes the + message set (for STORE) or set of UIDs (for UID STORE) of all + messages that failed the UNCHANGESINCE test. + + Example 3: + + All messages pass the UNCHANGESINCE test. + + C: a103 UID STORE 6,4,8 (UNCHANGEDSINCE 12121230045) + +FLAGS.SILENT (\Deleted) + S: * 1 FETCH (UID 4 MODSEQ (12121231000)) + S: * 2 FETCH (UID 6 MODSEQ (12121230852)) + S: * 4 FETCH (UID 8 MODSEQ (12121130956)) + S: a103 OK Conditional Store completed + + Example 4: + + C: a104 STORE * (UNCHANGEDSINCE 12121230045) +FLAGS.SILENT + (\Deleted $Processed) + S: * 50 FETCH (MODSEQ (12111230047)) + S: a104 OK Store (conditional) completed + + Example 5: + + C: c101 STORE 1 (UNCHANGEDSINCE 12121230045) -FLAGS.SILENT + (\Deleted) + S: * OK [HIGHESTMODSEQ 12111230047] + + + +Melnikov & Hole Standards Track [Page 8] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + + S: * 50 FETCH (MODSEQ (12111230048)) + S: c101 OK Store (conditional) completed + + HIGHESTMODSEQ response code was sent by the server presumably + because this was the first CONDSTORE enabling command. + + Example 6: + + In spite of the failure of the conditional STORE operation for + message 7, the server continues to process the conditional STORE + in order to find all messages that fail the test. + + C: d105 STORE 7,5,9 (UNCHANGEDSINCE 320162338) + +FLAGS.SILENT (\Deleted) + S: * 5 FETCH (MODSEQ (320162350)) + S: d105 OK [MODIFIED 7,9] Conditional STORE failed + + Example 7: + + Same as above, but the server follows the SHOULD recommendation in + Section 6.4.6 of [IMAP4]. + + C: d105 STORE 7,5,9 (UNCHANGEDSINCE 320162338) + +FLAGS.SILENT (\Deleted) + S: * 7 FETCH (MODSEQ (320162342) FLAGS (\Seen \Deleted)) + S: * 5 FETCH (MODSEQ (320162350)) + S: * 9 FETCH (MODSEQ (320162349) FLAGS (\Answered)) + S: d105 OK [MODIFIED 7,9] Conditional STORE failed + + Use of UNCHANGEDSINCE with a modification sequence of 0 always + fails if the metadata item exists. A system flag MUST always be + considered existent, whether it was set or not. + + Example 8: + + C: a102 STORE 12 (UNCHANGEDSINCE 0) + +FLAGS.SILENT ($MDNSent) + S: a102 OK [MODIFIED 12] Conditional STORE failed + + The client has tested the presence of the $MDNSent user-defined + keyword. + + Note: A client trying to make an atomic change to the state of a + particular metadata item (or a set of metadata items) should be + prepared to deal with the case when the server returns the MODIFIED + response code if the state of the metadata item being watched hasn't + changed (but the state of some other metadata item has). This is + necessary, because some servers don't store separate mod-sequences + + + +Melnikov & Hole Standards Track [Page 9] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + + for different metadata items. However, a server implementation + SHOULD avoid generating spurious MODIFIED responses for +FLAGS/-FLAGS + STORE operations, even when the server stores a single mod-sequence + per message. Section 5 describes how this can be achieved. + + Unless the server has included an unsolicited FETCH to update + client's knowledge about messages that have failed the UNCHANGEDSINCE + test, upon receipt of the MODIFIED response code, the client SHOULD + try to figure out if the required metadata items have indeed changed + by issuing FETCH or NOOP command. It is RECOMMENDED that the server + avoids the need for the client to do that by sending an unsolicited + FETCH response (Examples 9 and 10). + + If the required metadata items haven't changed, the client SHOULD + retry the command with the new mod-sequence. The client SHOULD allow + for a configurable but reasonable number of retries (at least 2). + + Example 9: + + In the example below, the server returns the MODIFIED response + code without sending information describing why the STORE + UNCHANGEDSINCE operation has failed. + + C: a106 STORE 100:150 (UNCHANGEDSINCE 212030000000) + +FLAGS.SILENT ($Processed) + S: * 100 FETCH (MODSEQ (303181230852)) + S: * 102 FETCH (MODSEQ (303181230852)) + ... + S: * 150 FETCH (MODSEQ (303181230852)) + S: a106 OK [MODIFIED 101] Conditional STORE failed + + The flag $Processed was set on the message 101... + + C: a107 NOOP + S: * 101 FETCH (MODSEQ (303011130956) FLAGS ($Processed)) + S: a107 OK + + Or the flag hasn't changed, but another has (note that this server + behaviour is discouraged. Server implementers should also see + Section 5)... + + C: b107 NOOP + S: * 101 FETCH (MODSEQ (303011130956) FLAGS (\Deleted \Answered)) + S: b107 OK + + ...and the client retries the operation for the message 101 with + the updated UNCHANGEDSINCE value + + + + +Melnikov & Hole Standards Track [Page 10] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + + C: b108 STORE 101 (UNCHANGEDSINCE 303011130956) + +FLAGS.SILENT ($Processed) + S: * 101 FETCH (MODSEQ (303181230852)) + S: b108 OK Conditional Store completed + + Example 10: + + Same as above, but the server avoids the need for the client to + poll for changes. + + The flag $Processed was set on the message 101 by another + client... + + C: a106 STORE 100:150 (UNCHANGEDSINCE 212030000000) + +FLAGS.SILENT ($Processed) + S: * 100 FETCH (MODSEQ (303181230852)) + S: * 101 FETCH (MODSEQ (303011130956) FLAGS ($Processed)) + S: * 102 FETCH (MODSEQ (303181230852)) + ... + S: * 150 FETCH (MODSEQ (303181230852)) + S: a106 OK [MODIFIED 101] Conditional STORE failed + + Or the flag hasn't changed, but another has (note that this server + behaviour is discouraged. Server implementers should also see + Section 5)... + + C: a106 STORE 100:150 (UNCHANGEDSINCE 212030000000) + +FLAGS.SILENT ($Processed) + S: * 100 FETCH (MODSEQ (303181230852)) + S: * 101 FETCH (MODSEQ (303011130956) FLAGS (\Deleted \Answered)) + S: * 102 FETCH (MODSEQ (303181230852)) + ... + S: * 150 FETCH (MODSEQ (303181230852)) + S: a106 OK [MODIFIED 101] Conditional STORE failed + + ...and the client retries the operation for the message 101 with + the updated UNCHANGEDSINCE value + + C: b108 STORE 101 (UNCHANGEDSINCE 303011130956) + +FLAGS.SILENT ($Processed) + S: * 101 FETCH (MODSEQ (303181230852)) + S: b108 OK Conditional Store completed + + Or the flag hasn't changed, but another has (nice server + behaviour. Server implementers should also see Section 5)... + + C: a106 STORE 100:150 (UNCHANGEDSINCE 212030000000) + +FLAGS.SILENT ($Processed) + + + +Melnikov & Hole Standards Track [Page 11] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + + S: * 100 FETCH (MODSEQ (303181230852)) + S: * 101 FETCH (MODSEQ (303011130956) FLAGS ($Processed \Deleted + \Answered)) + S: * 102 FETCH (MODSEQ (303181230852)) + ... + S: * 150 FETCH (MODSEQ (303181230852)) + S: a106 OK Conditional STORE completed + + Example 11: + + The following example is based on the example from the Section + 4.2.3 of [RFC-2180] and demonstrates that the MODIFIED response + code may be also returned in the tagged NO response. + + Client tries to conditionally STORE flags on a mixture of expunged + and non-expunged messages; one message fails the UNCHANGEDSINCE + test. + + C: B001 STORE 1:7 (UNCHANGEDSINCE 320172338) +FLAGS (\SEEN) + S: * 1 FETCH (MODSEQ (320172342) FLAGS (\SEEN)) + S: * 3 FETCH (MODSEQ (320172342) FLAGS (\SEEN)) + S: B001 NO [MODIFIED 2] Some of the messages no longer exist. + + C: B002 NOOP + S: * 4 EXPUNGE + S: * 4 EXPUNGE + S: * 4 EXPUNGE + S: * 4 EXPUNGE + S: * 2 FETCH (MODSEQ (320172340) FLAGS (\Deleted \Answered)) + S: B002 OK NOOP Completed. + + By receiving FETCH responses for messages 1 and 3, and EXPUNGE + responses that indicate that messages 4 through 7 have been + expunged, the client retries the operation only for the message 2. + The updated UNCHANGEDSINCE value is used. + + C: b003 STORE 2 (UNCHANGEDSINCE 320172340) +FLAGS (\Seen) + S: * 2 FETCH (MODSEQ (320180050)) + S: b003 OK Conditional Store completed + + Note: If a message is specified multiple times in the message set, + and the server doesn't internally eliminate duplicates from the + message set, it MUST NOT fail the conditional STORE operation for the + second (or subsequent) occurrence of the message if the operation + completed successfully for the first occurrence. For example, if the + client specifies: + + + + + +Melnikov & Hole Standards Track [Page 12] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + + e105 STORE 7,3:9 (UNCHANGEDSINCE 12121230045) + +FLAGS.SILENT (\Deleted) + + the server must not fail the operation for message 7 as part of + processing "3:9" if it succeeded when message 7 was processed the + first time. + + Once the client specified the UNCHANGEDSINCE modifier in a STORE + command, the server MUST include the MODSEQ fetch response data items + in all subsequent unsolicited FETCH responses. + + This document also changes the behaviour of the server when it has + performed a STORE or UID STORE command and the UNCHANGEDSINCE + modifier is not specified. If the operation is successful for a + message, the server MUST update the mod-sequence attribute of the + message. The server is REQUIRED to include the mod-sequence value + whenever it decides to send the unsolicited FETCH response to all + CONDSTORE-aware clients that have opened the mailbox containing the + message. + + Server implementers should also see Section 3.8 for additional + quality of implementation issues related to the STORE command. + +3.3. FETCH and UID FETCH Commands + +3.3.1. CHANGEDSINCE FETCH Modifier + + This document defines the following FETCH modifier (see Section 2.4 + of [IMAPABNF]): + + CHANGEDSINCE <mod-sequence> + + CHANGEDSINCE FETCH modifier allows to create a further subset of + the list of messages described by sequence set. The information + described by message data items is only returned for messages that + have mod-sequence bigger than <mod-sequence>. + + When CHANGEDSINCE FETCH modifier is specified, it implicitly adds + MODSEQ FETCH message data item (Section 3.3.2). + + Example 12: + + C: s100 UID FETCH 1:* (FLAGS) (CHANGEDSINCE 12345) + S: * 1 FETCH (UID 4 MODSEQ (65402) FLAGS (\Seen)) + S: * 2 FETCH (UID 6 MODSEQ (75403) FLAGS (\Deleted)) + S: * 4 FETCH (UID 8 MODSEQ (29738) FLAGS ($NoJunk $AutoJunk + $MDNSent)) + S: s100 OK FETCH completed + + + +Melnikov & Hole Standards Track [Page 13] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + +3.3.2. MODSEQ Message Data Item in FETCH Command + + This extension adds a MODSEQ message data item to the FETCH command. + The MODSEQ message data item allows clients to retrieve mod-sequence + values for a range of messages in the currently selected mailbox. + + Once the client specified the MODSEQ message data item in a FETCH + request, the server MUST include the MODSEQ fetch response data items + in all subsequent unsolicited FETCH responses. + + Syntax: MODSEQ + + The MODSEQ message data item causes the server to return MODSEQ + fetch response data items. + + Syntax: MODSEQ ( <permsg-modsequence> ) + + MODSEQ response data items contain per-message mod-sequences. + + The MODSEQ response data item is returned if the client issued + FETCH with MODSEQ message data item. It also allows the server to + notify the client about mod-sequence changes caused by conditional + STOREs (Section 3.2) and/or changes caused by external sources. + + Example 13: + + C: a FETCH 1:3 (MODSEQ) + S: * 1 FETCH (MODSEQ (624140003)) + S: * 2 FETCH (MODSEQ (624140007)) + S: * 3 FETCH (MODSEQ (624140005)) + S: a OK Fetch complete + + In this example, the client requests per-message mod-sequences for + a set of messages. + + When a flag for a message is modified in a different session, the + server sends an unsolicited FETCH response containing the mod- + sequence for the message. + + Example 14: + + (Session 1, authenticated as a user "alex"). The user adds a + shared flag \Deleted: + + C: A142 SELECT INBOX + ... + S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) + S: * OK [PERMANENTFLAGS (\Answered \Deleted \Seen \*)] Limited + + + +Melnikov & Hole Standards Track [Page 14] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + + ... + + C: A160 STORE 7 +FLAGS.SILENT (\Deleted) + S: * 7 FETCH (MODSEQ (2121231000)) + S: A160 OK Store completed + + (Session 2, also authenticated as the user "alex"). Any changes + to flags are always reported to all sessions authenticated as the + same user as in the session 1. + + C: C180 NOOP + S: * 7 FETCH (FLAGS (\Deleted \Answered) MODSEQ (12121231000)) + S: C180 OK Noop completed + + (Session 3, authenticated as a user "andrew"). As \Deleted is a + shared flag, changes in session 1 are also reported in session 3: + + C: D210 NOOP + S: * 7 FETCH (FLAGS (\Deleted \Answered) MODSEQ (12121231000)) + S: D210 OK Noop completed + + The user modifies a private flag \Seen in session 1... + + C: A240 STORE 7 +FLAGS.SILENT (\Seen) + S: * 7 FETCH (MODSEQ (12121231777)) + S: A240 OK Store completed + + ...which is only reported in session 2... + + C: C270 NOOP + S: * 7 FETCH (FLAGS (\Deleted \Answered \Seen) MODSEQ + (12121231777)) + S: C270 OK Noop completed + + ...but not in session 3. + + C: D300 NOOP + S: D300 OK Noop completed + + And finally, the user removes flags \Answered (shared) and \Seen + (private) in session 1. + + C: A330 STORE 7 -FLAGS.SILENT (\Answered \Seen) + S: * 7 FETCH (MODSEQ (12121245160)) + S: A330 OK Store completed + + + + + + +Melnikov & Hole Standards Track [Page 15] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + + Both changes are reported in the session 2... + + C: C360 NOOP + S: * 7 FETCH (FLAGS (\Deleted) MODSEQ (12121245160)) + S: C360 OK Noop completed + + ...and only changes to shared flags are reported in session 3. + + C: D390 NOOP + S: * 7 FETCH (FLAGS (\Deleted) MODSEQ (12121245160)) + S: D390 OK Noop completed + + Server implementers should also see Section 3.8 for additional + quality of implementation issues related to the FETCH command. + +3.4. MODSEQ Search Criterion in SEARCH + + The MODSEQ criterion for the SEARCH command allows a client to search + for the metadata items that were modified since a specified moment. + + Syntax: MODSEQ [<entry-name> <entry-type-req>] <mod-sequence-valzer> + + Messages that have modification values that are equal to or + greater than <mod-sequence-valzer>. This allows a client, for + example, to find out which messages contain metadata items that + have changed since the last time it updated its disconnected + cache. The client may also specify <entry-name> (name of metadata + item) and <entry-type-req> (type of metadata item) before + <mod-sequence-valzer>. <entry-type-req> can be one of "shared", + "priv" (private), or "all". The latter means that the server + should use the biggest value among "priv" and "shared" mod- + sequences for the metadata item. If the server doesn't store + internally separate mod-sequences for different metadata items, it + MUST ignore <entry-name> and <entry-type-req>. Otherwise, the + server should use them to narrow down the search. + + For a flag <flagname>, the corresponding <entry-name> has a form + "/flags/<flagname>" as defined in [IMAPABNF]. Note that the + leading "\" character that denotes a system flag has to be escaped + as per Section 4.3 of [IMAP4], as the <entry-name> uses syntax for + quoted strings. + + If client specifies a MODSEQ criterion in a SEARCH command and the + server returns a non-empty SEARCH result, the server MUST also append + (to the end of the untagged SEARCH response) the highest mod-sequence + for all messages being returned. See also Section 3.5. + + + + + +Melnikov & Hole Standards Track [Page 16] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + + Example 15: + + C: a SEARCH MODSEQ "/flags/\\draft" all 620162338 + S: * SEARCH 2 5 6 7 11 12 18 19 20 23 (MODSEQ 917162500) + S: a OK Search complete + + In the above example, the message numbers of any messages + containing the string "IMAP4" in the "value" attribute of the + "/comment" entry and having a mod-sequence equal to or greater + than 620162338 for the "\Draft" flag are returned in the search + results. + + Example 16: + + C: t SEARCH OR NOT MODSEQ 720162338 LARGER 50000 + S: * SEARCH + S: t OK Search complete, nothing found + +3.5. Modified SEARCH Untagged Response + + Data: zero or more numbers + mod-sequence value (omitted if no match) + + This document extends syntax of the untagged SEARCH response to + include the highest mod-sequence for all messages being returned. + + If a client specifies a MODSEQ criterion in a SEARCH (or UID SEARCH) + command and the server returns a non-empty SEARCH result, the server + MUST also append (to the end of the untagged SEARCH response) the + highest mod-sequence for all messages being returned. See Section + 3.4 for examples. + +3.6. HIGHESTMODSEQ Status Data Items + + This document defines a new status data item: + + HIGHESTMODSEQ + + The highest mod-sequence value of all messages in the mailbox. + This is the same value that is returned by the server in the + HIGHESTMODSEQ response code in an OK untagged response (see + Section 3.1.1). If the server doesn't support the persistent + storage of mod-sequences for the mailbox (see Section 3.1.2), the + server MUST return 0 as the value of HIGHESTMODSEQ status data + item. + + + + + + +Melnikov & Hole Standards Track [Page 17] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + + Example 17: + + C: A042 STATUS blurdybloop (UIDNEXT MESSAGES HIGHESTMODSEQ) + S: * STATUS blurdybloop (MESSAGES 231 UIDNEXT 44292 + HIGHESTMODSEQ 7011231777) + S: A042 OK STATUS completed + +3.7. CONDSTORE Parameter to SELECT and EXAMINE + + The CONDSTORE extension defines a single optional select parameter, + "CONDSTORE", which tells the server that it MUST include the MODSEQ + fetch response data items in all subsequent unsolicited FETCH + responses. + + The CONDSTORE parameter to SELECT/EXAMINE helps avoid a race + condition that might arise when one or more metadata items are + modified in another session after the server has sent the + HIGHESTMODSEQ response code and before the client was able to issue a + CONDSTORE enabling command. + + Example 18: + + C: A142 SELECT INBOX (CONDSTORE) + S: * 172 EXISTS + S: * 1 RECENT + S: * OK [UNSEEN 12] Message 12 is first unseen + S: * OK [UIDVALIDITY 3857529045] UIDs valid + S: * OK [UIDNEXT 4392] Predicted next UID + S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) + S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited + S: * OK [HIGHESTMODSEQ 715194045007] + S: A142 OK [READ-WRITE] SELECT completed, CONDSTORE is now enabled + +3.8. Additional Quality-of-Implementation Issues + + Server implementations should follow the following rule, which + applies to any successfully completed STORE/UID STORE (with and + without UNCHANGEDSINCE modifier), as well as to a FETCH command that + implicitly sets \Seen flag: + + Adding the flag when it is already present or removing when it is + not present SHOULD NOT change the mod-sequence. + + This will prevent spurious client synchronization requests. + + + + + + + +Melnikov & Hole Standards Track [Page 18] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + + However, note that client implementers MUST NOT rely on this server + behavior. A client can't distinguish between the case when a server + has violated the SHOULD mentioned above, and that when one or more + clients set and unset (or unset and set) the flag in another session. + +4. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) [ABNF] notation. Elements not defined here can be found + in the formal syntax of the ABNF [ABNF], IMAP [IMAP4], and IMAP ABNF + extensions [IMAPABNF] specifications. + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of upper- or lowercase characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. + + capability =/ "CONDSTORE" + + status-att =/ "HIGHESTMODSEQ" + ;; extends non-terminal defined in RFC 3501. + + status-att-val =/ "HIGHESTMODSEQ" SP mod-sequence-valzer + ;; extends non-terminal defined in [IMAPABNF]. + ;; Value 0 denotes that the mailbox doesn't + ;; support persistent mod-sequences + ;; as described in Section 3.1.2 + + store-modifier =/ "UNCHANGEDSINCE" SP mod-sequence-valzer + ;; Only a single "UNCHANGEDSINCE" may be + ;; specified in a STORE operation + + fetch-modifier =/ chgsince-fetch-mod + ;; conforms to the generic "fetch-modifier" + ;; syntax defined in [IMAPABNF]. + + chgsince-fetch-mod = "CHANGEDSINCE" SP mod-sequence-value + ;; CHANGEDSINCE FETCH modifier conforms to + ;; the fetch-modifier syntax + + fetch-att =/ fetch-mod-sequence + ;; modifies original IMAP4 fetch-att + + fetch-mod-sequence = "MODSEQ" + + fetch-mod-resp = "MODSEQ" SP "(" permsg-modsequence ")" + + msg-att-dynamic =/ fetch-mod-resp + + + +Melnikov & Hole Standards Track [Page 19] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + + search-key =/ search-modsequence + ;; modifies original IMAP4 search-key + ;; + ;; This change applies to all commands + ;; referencing this non-terminal, in + ;; particular SEARCH. + + search-modsequence = "MODSEQ" [search-modseq-ext] SP + mod-sequence-valzer + + search-modseq-ext = SP entry-name SP entry-type-req + + resp-text-code =/ "HIGHESTMODSEQ" SP mod-sequence-value / + "NOMODSEQ" / + "MODIFIED" SP set + + entry-name = entry-flag-name + + entry-flag-name = DQUOTE "/flags/" attr-flag DQUOTE + ;; each system or user defined flag <flag> + ;; is mapped to "/flags/<flag>". + ;; + ;; <entry-flag-name> follows the escape rules + ;; used by "quoted" string as described in + ;; Section 4.3 of [IMAP4], e.g., for the flag + ;; \Seen the corresponding <entry-name> is + ;; "/flags/\\seen", and for the flag + ;; $MDNSent, the corresponding <entry-name> + ;; is "/flags/$mdnsent". + + entry-type-resp = "priv" / "shared" + ;; metadata item type + + entry-type-req = entry-type-resp / "all" + ;; perform SEARCH operation on private + ;; metadata item, shared metadata item or both + + permsg-modsequence = mod-sequence-value + ;; per message mod-sequence + + mod-sequence-value = 1*DIGIT + ;; Positive unsigned 64-bit integer + ;; (mod-sequence) + ;; (1 <= n < 18,446,744,073,709,551,615) + + mod-sequence-valzer = "0" / mod-sequence-value + + search-sort-mod-seq = "(" "MODSEQ" SP mod-sequence-value ")" + + + +Melnikov & Hole Standards Track [Page 20] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + + select-param =/ condstore-param + ;; conforms to the generic "select-param" + ;; non-terminal syntax defined in [IMAPABNF]. + + condstore-param = "CONDSTORE" + + mailbox-data =/ "SEARCH" [1*(SP nz-number) SP + search-sort-mod-seq] + + attr-flag = "\\Answered" / "\\Flagged" / "\\Deleted" / + "\\Seen" / "\\Draft" / attr-flag-keyword / + attr-flag-extension + ;; Does not include "\\Recent" + + attr-flag-extension = "\\" atom + ;; Future expansion. Client implementations + ;; MUST accept flag-extension flags. Server + ;; implementations MUST NOT generate + ;; flag-extension flags except as defined by + ;; future standard or standards-track + ;; revisions of [IMAP4]. + + attr-flag-keyword = atom + +5. Server Implementation Considerations + + This section describes how a server implementation that doesn't store + separate per-metadata mod-sequences for different metadata items can + avoid sending the MODIFIED response to any of the following + conditional STORE operations: + + +FLAGS + -FLAGS + +FLAGS.SILENT + -FLAGS.SILENT + + Note that the optimization described in this section can't be + performed in case of a conditional STORE FLAGS operation. + + Let's use the following example. The client has issued + + C: a106 STORE 100:150 (UNCHANGEDSINCE 212030000000) + +FLAGS.SILENT ($Processed) + + When the server receives the command and parses it successfully, it + iterates through the message set and tries to execute the conditional + STORE command for each message. + + + + +Melnikov & Hole Standards Track [Page 21] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + + Each server internally works as a client, i.e., it has to cache the + current state of all IMAP flags as it is known to the client. In + order to report flag changes to the client, the server compares the + cached values with the values in its database for IMAP flags. + + Imagine that another client has changed the state of a flag \Deleted + on the message 101 and that the change updated the mod-sequence for + the message. The server knows that the mod-sequence for the mailbox + has changed; however, it also knows that: + + a) the client is not interested in \Deleted flag, as it hasn't + included it in +FLAGS.SILENT operation; and + + b) the state of the flag $Processed hasn't changed (the server can + determine this by comparing cached flag state with the state of + the flag in the database). + + Therefore, the server doesn't have to report MODIFIED to the client. + Instead, the server may set $Processed flag, update the mod-sequence + for the message 101 once again and send an untagged FETCH response + with new mod-sequence and flags: + + S: * 101 FETCH (MODSEQ (303011130956) + FLAGS ($Processed \Deleted \Answered)) + + See also Section 3.8 for additional quality-of-implementation issues. + +6. Security Considerations + + It is believed that the Conditional STORE extension doesn't raise any + new security concerns that are not already discussed in [IMAP4]. + However, the availability of this extension may make it possible for + IMAP4 to be used in critical applications it could not be used for + previously, making correct IMAP server implementation and operation + even more important. + +7. IANA Considerations + + IMAP4 capabilities are registered by publishing a standards track or + IESG approved experimental RFC. The registry is currently located + at: + + http://www.iana.org/assignments/imap4-capabilities + + This document defines the CONDSTORE IMAP capability. IANA has added + it to the registry accordingly. + + + + + +Melnikov & Hole Standards Track [Page 22] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + +8. References + +8.1. Normative References + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 4234, October 2005. + + [IMAP4] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [IMAPABNF] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 + ABNF", RFC 4466, April 2006. + +8.2. Informative References + + [ACAP] Newman, C. and J. Myers, "ACAP -- Application + Configuration Access Protocol", RFC 2244, November 1997. + + [ACL] Melnikov, A., "IMAP4 Access Control List (ACL) Extension", + RFC 4314, December 2005. + + [ANN] Daboo, C. and R. Gellens, "IMAP ANNOTATE Extension", Work + in Progress, March 2006. + + [NTP] Mills, D., "Network Time Protocol (Version 3) + Specification, Implementation and Analysis", RFC 1305, + March 1992. + + [RFC-2180] Gahrns, M., "IMAP4 Multi-Accessed Mailbox Practice", RFC + 2180, July 1997. + +9. Acknowledgements + + Some text was borrowed from "IMAP ANNOTATE Extension" [ANN] by + Randall Gellens and Cyrus Daboo and from "ACAP -- Application + Configuration Access Protocol" [ACAP] by Chris Newman and John Myers. + + Many thanks to Randall Gellens for his thorough review of the + document. + + The authors also acknowledge the feedback provided by Cyrus Daboo, + Larry Greenfield, Chris Newman, Harrie Hazewinkel, Arnt Gulbrandsen, + Timo Sirainen, Mark Crispin, Ned Freed, Ken Murchison, and Dave + Cridland. + + + + +Melnikov & Hole Standards Track [Page 23] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + +Authors' Addresses + + Alexey Melnikov + Isode Limited + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex + TW12 2BX, + United Kingdom + + EMail: Alexey.Melnikov@isode.com + + + Steve Hole + ACI WorldWide/MessagingDirect + #1807, 10088 102 Ave + Edmonton, AB + T5J 2Z1 + Canada + + EMail: Steve.Hole@messagingdirect.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Melnikov & Hole Standards Track [Page 24] + +RFC 4551 IMAP Extension for Conditional STORE June 2006 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2006). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is provided by the IETF + Administrative Support Activity (IASA). + + + + + + + +Melnikov & Hole Standards Track [Page 25] + diff --git a/imap/docs/rfc/rfc4616.txt b/imap/docs/rfc/rfc4616.txt new file mode 100644 index 00000000..991189d5 --- /dev/null +++ b/imap/docs/rfc/rfc4616.txt @@ -0,0 +1,619 @@ + + + + + + +Network Working Group K. Zeilenga, Ed. +Request for Comments: 4616 OpenLDAP Foundation +Updates: 2595 August 2006 +Category: Standards Track + + + The PLAIN Simple Authentication and Security Layer (SASL) Mechanism + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (2006). + +Abstract + + This document defines a simple clear-text user/password Simple + Authentication and Security Layer (SASL) mechanism called the PLAIN + mechanism. The PLAIN mechanism is intended to be used, in + combination with data confidentiality services provided by a lower + layer, in protocols that lack a simple password authentication + command. + + + + + + + + + + + + + + + + + + + + + + + +Zeilenga Standards Track [Page 1] + +RFC 4616 The PLAIN SASL Mechanism August 2006 + + +1. Introduction + + Clear-text, multiple-use passwords are simple, interoperate with + almost all existing operating system authentication databases, and + are useful for a smooth transition to a more secure password-based + authentication mechanism. The drawback is that they are unacceptable + for use over network connections where data confidentiality is not + ensured. + + This document defines the PLAIN Simple Authentication and Security + Layer ([SASL]) mechanism for use in protocols with no clear-text + login command (e.g., [ACAP] or [SMTP-AUTH]). This document updates + RFC 2595, replacing Section 6. Changes since RFC 2595 are detailed + in Appendix A. + + The name associated with this mechanism is "PLAIN". + + The PLAIN SASL mechanism does not provide a security layer. + + The PLAIN mechanism should not be used without adequate data security + protection as this mechanism affords no integrity or confidentiality + protections itself. The mechanism is intended to be used with data + security protections provided by application-layer protocol, + generally through its use of Transport Layer Security ([TLS]) + services. + + By default, implementations SHOULD advertise and make use of the + PLAIN mechanism only when adequate data security services are in + place. Specifications for IETF protocols that indicate that this + mechanism is an applicable authentication mechanism MUST mandate that + implementations support an strong data security service, such as TLS. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [Keywords]. + +2. PLAIN SASL Mechanism + + The mechanism consists of a single message, a string of [UTF-8] + encoded [Unicode] characters, from the client to the server. The + client presents the authorization identity (identity to act as), + followed by a NUL (U+0000) character, followed by the authentication + identity (identity whose password will be used), followed by a NUL + (U+0000) character, followed by the clear-text password. As with + other SASL mechanisms, the client does not provide an authorization + identity when it wishes the server to derive an identity from the + credentials and use that as the authorization identity. + + + + +Zeilenga Standards Track [Page 2] + +RFC 4616 The PLAIN SASL Mechanism August 2006 + + + The formal grammar for the client message using Augmented BNF [ABNF] + follows. + + message = [authzid] UTF8NUL authcid UTF8NUL passwd + authcid = 1*SAFE ; MUST accept up to 255 octets + authzid = 1*SAFE ; MUST accept up to 255 octets + passwd = 1*SAFE ; MUST accept up to 255 octets + UTF8NUL = %x00 ; UTF-8 encoded NUL character + + SAFE = UTF1 / UTF2 / UTF3 / UTF4 + ;; any UTF-8 encoded Unicode character except NUL + + UTF1 = %x01-7F ;; except NUL + UTF2 = %xC2-DF UTF0 + UTF3 = %xE0 %xA0-BF UTF0 / %xE1-EC 2(UTF0) / + %xED %x80-9F UTF0 / %xEE-EF 2(UTF0) + UTF4 = %xF0 %x90-BF 2(UTF0) / %xF1-F3 3(UTF0) / + %xF4 %x80-8F 2(UTF0) + UTF0 = %x80-BF + + The authorization identity (authzid), authentication identity + (authcid), password (passwd), and NUL character deliminators SHALL be + transferred as [UTF-8] encoded strings of [Unicode] characters. As + the NUL (U+0000) character is used as a deliminator, the NUL (U+0000) + character MUST NOT appear in authzid, authcid, or passwd productions. + + The form of the authzid production is specific to the application- + level protocol's SASL profile [SASL]. The authcid and passwd + productions are form-free. Use of non-visible characters or + characters that a user may be unable to enter on some keyboards is + discouraged. + + Servers MUST be capable of accepting authzid, authcid, and passwd + productions up to and including 255 octets. It is noted that the + UTF-8 encoding of a Unicode character may be as long as 4 octets. + + Upon receipt of the message, the server will verify the presented (in + the message) authentication identity (authcid) and password (passwd) + with the system authentication database, and it will verify that the + authentication credentials permit the client to act as the (presented + or derived) authorization identity (authzid). If both steps succeed, + the user is authenticated. + + The presented authentication identity and password strings, as well + as the database authentication identity and password strings, are to + be prepared before being used in the verification process. The + [SASLPrep] profile of the [StringPrep] algorithm is the RECOMMENDED + preparation algorithm. The SASLprep preparation algorithm is + + + +Zeilenga Standards Track [Page 3] + +RFC 4616 The PLAIN SASL Mechanism August 2006 + + + recommended to improve the likelihood that comparisons behave in an + expected manner. The SASLprep preparation algorithm is not mandatory + so as to allow the server to employ other preparation algorithms + (including none) when appropriate. For instance, use of a different + preparation algorithm may be necessary for the server to interoperate + with an external system. + + When preparing the presented strings using [SASLPrep], the presented + strings are to be treated as "query" strings (Section 7 of + [StringPrep]) and hence unassigned code points are allowed to appear + in their prepared output. When preparing the database strings using + [SASLPrep], the database strings are to be treated as "stored" + strings (Section 7 of [StringPrep]) and hence unassigned code points + are prohibited from appearing in their prepared output. + + Regardless of the preparation algorithm used, if the output of a + non-invertible function (e.g., hash) of the expected string is + stored, the string MUST be prepared before input to that function. + + Regardless of the preparation algorithm used, if preparation fails or + results in an empty string, verification SHALL fail. + + When no authorization identity is provided, the server derives an + authorization identity from the prepared representation of the + provided authentication identity string. This ensures that the + derivation of different representations of the authentication + identity produces the same authorization identity. + + The server MAY use the credentials to initialize any new + authentication database, such as one suitable for [CRAM-MD5] or + [DIGEST-MD5]. + +3. Pseudo-Code + + This section provides pseudo-code illustrating the verification + process (using hashed passwords and the SASLprep preparation + function) discussed above. This section is not definitive. + + boolean Verify(string authzid, string authcid, string passwd) { + string pAuthcid = SASLprep(authcid, true); # prepare authcid + string pPasswd = SASLprep(passwd, true); # prepare passwd + if (pAuthcid == NULL || pPasswd == NULL) { + return false; # preparation failed + } + if (pAuthcid == "" || pPasswd == "") { + return false; # empty prepared string + } + + + + +Zeilenga Standards Track [Page 4] + +RFC 4616 The PLAIN SASL Mechanism August 2006 + + + storedHash = FetchPasswordHash(pAuthcid); + if (storedHash == NULL || storedHash == "") { + return false; # error or unknown authcid + } + + if (!Compare(storedHash, Hash(pPasswd))) { + return false; # incorrect password + } + + if (authzid == NULL ) { + authzid = DeriveAuthzid(pAuthcid); + if (authzid == NULL || authzid == "") { + return false; # could not derive authzid + } + } + + if (!Authorize(pAuthcid, authzid)) { + return false; # not authorized + } + + return true; + } + + The second parameter of the SASLprep function, when true, indicates + that unassigned code points are allowed in the input. When the + SASLprep function is called to prepare the password prior to + computing the stored hash, the second parameter would be false. + + The second parameter provided to the Authorize function is not + prepared by this code. The application-level SASL profile should be + consulted to determine what, if any, preparation is necessary. + + Note that the DeriveAuthzid and Authorize functions (whether + implemented as one function or two, whether designed in a manner in + which these functions or whether the mechanism implementation can be + reused elsewhere) require knowledge and understanding of mechanism + and the application-level protocol specification and/or + implementation details to implement. + + Note that the Authorize function outcome is clearly dependent on + details of the local authorization model and policy. Both functions + may be dependent on other factors as well. + + + + + + + + + +Zeilenga Standards Track [Page 5] + +RFC 4616 The PLAIN SASL Mechanism August 2006 + + +4. Examples + + This section provides examples of PLAIN authentication exchanges. + The examples are intended to help the readers understand the above + text. The examples are not definitive. + + "C:" and "S:" indicate lines sent by the client and server, + respectively. "<NUL>" represents a single NUL (U+0000) character. + The Application Configuration Access Protocol ([ACAP]) is used in the + examples. + + The first example shows how the PLAIN mechanism might be used for + user authentication. + + S: * ACAP (SASL "CRAM-MD5") (STARTTLS) + C: a001 STARTTLS + S: a001 OK "Begin TLS negotiation now" + <TLS negotiation, further commands are under TLS layer> + S: * ACAP (SASL "CRAM-MD5" "PLAIN") + C: a002 AUTHENTICATE "PLAIN" + S: + "" + C: {21} + C: <NUL>tim<NUL>tanstaaftanstaaf + S: a002 OK "Authenticated" + + The second example shows how the PLAIN mechanism might be used to + attempt to assume the identity of another user. In this example, the + server rejects the request. Also, this example makes use of the + protocol optional initial response capability to eliminate a round- + trip. + + S: * ACAP (SASL "CRAM-MD5") (STARTTLS) + C: a001 STARTTLS + S: a001 OK "Begin TLS negotiation now" + <TLS negotiation, further commands are under TLS layer> + S: * ACAP (SASL "CRAM-MD5" "PLAIN") + C: a002 AUTHENTICATE "PLAIN" {20+} + C: Ursel<NUL>Kurt<NUL>xipj3plmq + S: a002 NO "Not authorized to requested authorization identity" + +5. Security Considerations + + As the PLAIN mechanism itself provided no integrity or + confidentiality protections, it should not be used without adequate + external data security protection, such as TLS services provided by + many application-layer protocols. By default, implementations SHOULD + NOT advertise and SHOULD NOT make use of the PLAIN mechanism unless + adequate data security services are in place. + + + +Zeilenga Standards Track [Page 6] + +RFC 4616 The PLAIN SASL Mechanism August 2006 + + + When the PLAIN mechanism is used, the server gains the ability to + impersonate the user to all services with the same password + regardless of any encryption provided by TLS or other confidentiality + protection mechanisms. Whereas many other authentication mechanisms + have similar weaknesses, stronger SASL mechanisms address this issue. + Clients are encouraged to have an operational mode where all + mechanisms that are likely to reveal the user's password to the + server are disabled. + + General [SASL] security considerations apply to this mechanism. + + Unicode, [UTF-8], and [StringPrep] security considerations also + apply. + +6. IANA Considerations + + The SASL Mechanism registry [IANA-SASL] entry for the PLAIN mechanism + has been updated by the IANA to reflect that this document now + provides its technical specification. + + To: iana@iana.org + Subject: Updated Registration of SASL mechanism PLAIN + + SASL mechanism name: PLAIN + Security considerations: See RFC 4616. + Published specification (optional, recommended): RFC 4616 + Person & email address to contact for further information: + Kurt Zeilenga <kurt@openldap.org> + IETF SASL WG <ietf-sasl@imc.org> + Intended usage: COMMON + Author/Change controller: IESG <iesg@ietf.org> + Note: Updates existing entry for PLAIN + +7. Acknowledgements + + This document is a revision of RFC 2595 by Chris Newman. Portions of + the grammar defined in Section 2 were borrowed from [UTF-8] by + Francois Yergeau. + + This document is a product of the IETF Simple Authentication and + Security Layer (SASL) Working Group. + + + + + + + + + + +Zeilenga Standards Track [Page 7] + +RFC 4616 The PLAIN SASL Mechanism August 2006 + + +8. Normative References + + [ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", RFC 4234, October 2005. + + [Keywords] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [SASL] Melnikov, A., Ed., and K. Zeilenga, Ed., "Simple + Authentication and Security Layer (SASL)", RFC 4422, + June 2006. + + [SASLPrep] Zeilenga, K., "SASLprep: Stringprep Profile for User + Names and Passwords", RFC 4013, February 2005. + + [StringPrep] Hoffman, P. and M. Blanchet, "Preparation of + Internationalized Strings ("stringprep")", RFC 3454, + December 2002. + + [Unicode] The Unicode Consortium, "The Unicode Standard, Version + 3.2.0" is defined by "The Unicode Standard, Version + 3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201- + 61633-5), as amended by the "Unicode Standard Annex + #27: Unicode 3.1" + (http://www.unicode.org/reports/tr27/) and by the + "Unicode Standard Annex #28: Unicode 3.2" + (http://www.unicode.org/reports/tr28/). + + [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. + + [TLS] Dierks, T. and E. Rescorla, "The Transport Layer + Security (TLS) Protocol Version 1.1", RFC 4346, April + 2006. + +9. Informative References + + [ACAP] Newman, C. and J. Myers, "ACAP -- Application + Configuration Access Protocol", RFC 2244, November + 1997. + + [CRAM-MD5] Nerenberg, L., Ed., "The CRAM-MD5 SASL Mechanism", Work + in Progress, June 2006. + + [DIGEST-MD5] Melnikov, A., Ed., "Using Digest Authentication as a + SASL Mechanism", Work in Progress, June 2006. + + + + + +Zeilenga Standards Track [Page 8] + +RFC 4616 The PLAIN SASL Mechanism August 2006 + + + [IANA-SASL] IANA, "SIMPLE AUTHENTICATION AND SECURITY LAYER (SASL) + MECHANISMS", + <http://www.iana.org/assignments/sasl-mechanisms>. + + [SMTP-AUTH] Myers, J., "SMTP Service Extension for Authentication", + RFC 2554, March 1999. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Zeilenga Standards Track [Page 9] + +RFC 4616 The PLAIN SASL Mechanism August 2006 + + +Appendix A. Changes since RFC 2595 + + This appendix is non-normative. + + This document replaces Section 6 of RFC 2595. + + The specification details how the server is to compare client- + provided character strings with stored character strings. + + The ABNF grammar was updated. In particular, the grammar now allows + LINE FEED (U+000A) and CARRIAGE RETURN (U+000D) characters in the + authzid, authcid, passwd productions. However, whether these control + characters may be used depends on the string preparation rules + applicable to the production. For passwd and authcid productions, + control characters are prohibited. For authzid, one must consult the + application-level SASL profile. This change allows PLAIN to carry + all possible authorization identity strings allowed in SASL. + + Pseudo-code was added. + + The example section was expanded to illustrate more features of the + PLAIN mechanism. + +Editor's Address + + Kurt D. Zeilenga + OpenLDAP Foundation + + EMail: Kurt@OpenLDAP.org + + + + + + + + + + + + + + + + + + + + + + +Zeilenga Standards Track [Page 10] + +RFC 4616 The PLAIN SASL Mechanism August 2006 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2006). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is provided by the IETF + Administrative Support Activity (IASA). + + + + + + + +Zeilenga Standards Track [Page 11] + diff --git a/imap/docs/rfc/rfc4731.txt b/imap/docs/rfc/rfc4731.txt new file mode 100644 index 00000000..8c4869aa --- /dev/null +++ b/imap/docs/rfc/rfc4731.txt @@ -0,0 +1,451 @@ + + + + + + +Network Working Group A. Melnikov +Request for Comments: 4731 Isode Ltd +Category: Standards Track D. Cridland + Inventure Systems Ltd + November 2006 + + + IMAP4 Extension to SEARCH Command for Controlling + What Kind of Information Is Returned + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The IETF Trust (2006). + +Abstract + + This document extends IMAP (RFC 3501) SEARCH and UID SEARCH commands + with several result options, which can control what kind of + information is returned. The following result options are defined: + minimal value, maximal value, all found messages, and number of found + messages. + +Table of Contents + + 1. Introduction ....................................................2 + 2. Conventions Used in This Document ...............................2 + 3. IMAP Protocol Changes ...........................................2 + 3.1. New SEARCH/UID SEARCH Result Options .......................2 + 3.2. Interaction with CONDSTORE extension .......................4 + 4. Formal Syntax ...................................................5 + 5. Security Considerations .........................................6 + 6. IANA Considerations .............................................6 + 7. Normative References ............................................6 + 8. Acknowledgments .................................................6 + + + + + + + + + +Melnikov & Cridland Standards Track [Page 1] + +RFC 4731 IMAP4 Extension to SEARCH November 2006 + + +1. Introduction + + [IMAPABNF] extended SEARCH and UID SEARCH commands with result + specifiers (also known as result options), which can control what + kind of information is returned. + + A server advertising the ESEARCH capability supports the following + result options: minimal value, maximal value, all found messages, + and number of found messages. These result options allow clients to + get SEARCH results in more convenient forms, while also saving + bandwidth required to transport the results, for example, by finding + the first unseen message or returning the number of unseen or deleted + messages. Also, when a single MIN or a single MAX result option is + specified, servers can optimize execution of SEARCHes. + +2. Conventions Used in This Document + + In examples, "C:" and "S:" indicate lines sent by the client and + server, respectively. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [KEYWORDS]. + +3. IMAP Protocol Changes + +3.1. New SEARCH/UID SEARCH Result Options + + The SEARCH/UID SEARCH commands are extended to allow for the + following result options: + + MIN + Return the lowest message number/UID that satisfies the SEARCH + criteria. + + If the SEARCH results in no matches, the server MUST NOT + include the MIN result option in the ESEARCH response; however, + it still MUST send the ESEARCH response. + + MAX + Return the highest message number/UID that satisfies the SEARCH + criteria. + + If the SEARCH results in no matches, the server MUST NOT + include the MAX result option in the ESEARCH response; however, + it still MUST send the ESEARCH response. + + + + + +Melnikov & Cridland Standards Track [Page 2] + +RFC 4731 IMAP4 Extension to SEARCH November 2006 + + + ALL + Return all message numbers/UIDs that satisfy the SEARCH + criteria. Unlike regular (unextended) SEARCH, the messages are + always returned using the sequence-set syntax. A sequence-set + representation may be more compact and can be used as is in a + subsequent command that accepts sequence-set. Note, the client + MUST NOT assume that messages/UIDs will be listed in any + particular order. + + If the SEARCH results in no matches, the server MUST NOT + include the ALL result option in the ESEARCH response; however, + it still MUST send the ESEARCH response. + + COUNT + Return number of the messages that satisfy the SEARCH criteria. + This result option MUST always be included in the ESEARCH + response. + + If one or more result options described above are specified, the + extended SEARCH command MUST return a single ESEARCH response + [IMAPABNF], instead of the SEARCH response. + + An extended UID SEARCH command MUST cause an ESEARCH response with + the UID indicator present. + + Note that future extensions to this document can allow servers to + return multiple ESEARCH responses for a single extended SEARCH + command. These extensions will have to describe how results from + multiple ESEARCH responses are to be amalgamated. + + If the list of result options is empty, that requests the server to + return an ESEARCH response instead of the SEARCH response. This is + equivalent to "(ALL)". + + Example: C: A282 SEARCH RETURN (MIN COUNT) FLAGGED + SINCE 1-Feb-1994 NOT FROM "Smith" + S: * ESEARCH (TAG "A282") MIN 2 COUNT 3 + S: A282 OK SEARCH completed + + Example: C: A283 SEARCH RETURN () FLAGGED + SINCE 1-Feb-1994 NOT FROM "Smith" + S: * ESEARCH (TAG "A283") ALL 2,10:11 + S: A283 OK SEARCH completed + + The following example demonstrates finding the first unseen message + as returned in the UNSEEN response code on a successful SELECT + command: + + + + +Melnikov & Cridland Standards Track [Page 3] + +RFC 4731 IMAP4 Extension to SEARCH November 2006 + + + Example: C: A284 SEARCH RETURN (MIN) UNSEEN + S: * ESEARCH (TAG "A284") MIN 4 + S: A284 OK SEARCH completed + + The following example demonstrates that if the ESEARCH UID indicator + is present, all data in the ESEARCH response is referring to UIDs; + for example, the MIN result specifier will be followed by a UID. + + Example: C: A285 UID SEARCH RETURN (MIN MAX) 1:5000 + S: * ESEARCH (TAG "A285") UID MIN 7 MAX 3800 + S: A285 OK SEARCH completed + + The following example demonstrates returning the number of deleted + messages: + + Example: C: A286 SEARCH RETURN (COUNT) DELETED + S: * ESEARCH (TAG "A286") COUNT 15 + S: A286 OK SEARCH completed + +3.2. Interaction with CONDSTORE extension + + When the server supports both the ESEARCH and the CONDSTORE + [CONDSTORE] extension, and the client requests one or more result + option described in section 3.1 together with the MODSEQ search + criterion in the same SEARCH/UID SEARCH command, then the server MUST + return the ESEARCH response containing the MODSEQ result option + (described in the following paragraph) instead of the extended SEARCH + response described in section 3.5 of [CONDSTORE]. + + If the SEARCH/UID SEARCH command contained a single MIN or MAX result + option, the MODSEQ result option contains the mod-sequence for the + found message. If the SEARCH/UID SEARCH command contained both MIN + and MAX result options and no ALL/COUNT option, the MODSEQ result + option contains the highest mod-sequence for the two returned + messages. Otherwise the MODSEQ result option contains the highest + mod-sequence for all messages being returned. + + Example: The following example demonstrates how Example 15 from + [CONDSTORE] would look in the presence of one or more result option: + + C: a1 SEARCH RETURN (MIN) MODSEQ "/flags/\\draft" + all 620162338 + S: * ESEARCH (TAG "a1") MIN 2 MODSEQ 917162488 + S: a1 OK Search complete + + C: a2 SEARCH RETURN (MAX) MODSEQ "/flags/\\draft" + all 620162338 + S: * ESEARCH (TAG "a2") MAX 23 MODSEQ 907162321 + + + +Melnikov & Cridland Standards Track [Page 4] + +RFC 4731 IMAP4 Extension to SEARCH November 2006 + + + S: a2 OK Search complete + + C: a3 SEARCH RETURN (MIN MAX) MODSEQ "/flags/\\draft" + all 620162338 + S: * ESEARCH (TAG "a3") MIN 2 MAX 23 MODSEQ 917162488 + S: a3 OK Search complete + + C: a4 SEARCH RETURN (MIN COUNT) MODSEQ "/flags/\\draft" + all 620162338 + S: * ESEARCH (TAG "a4") MIN 2 COUNT 10 MODSEQ 917162500 + S: a4 OK Search complete + +4. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [ABNF]. + + Non-terminals referenced but not defined below are as defined by + [IMAP4], [CONDSTORE], or [IMAPABNF]. + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of upper or lowercase characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. + + capability =/ "ESEARCH" + + search-return-data = "MIN" SP nz-number / + "MAX" SP nz-number / + "ALL" SP sequence-set / + "COUNT" SP number + ;; conforms to the generic + ;; search-return-data syntax defined + ;; in [IMAPABNF] + + search-return-opt = "MIN" / "MAX" / "ALL" / "COUNT" + ;; conforms to generic search-return-opt + ;; syntax defined in [IMAPABNF] + + When the CONDSTORE [CONDSTORE] IMAP extension is also supported, + the ABNF is updated as follows: + + search-return-data =/ "MODSEQ" SP mod-sequence-value + ;; mod-sequence-value is defined + ;; in [CONDSTORE] + + + + + + +Melnikov & Cridland Standards Track [Page 5] + +RFC 4731 IMAP4 Extension to SEARCH November 2006 + + +5. Security Considerations + + In the general case, the IMAP SEARCH/UID SEARCH commands can be CPU + and/or IO intensive, and are seen by some as a potential attack point + for denial of service attacks, so some sites/implementations even + disable them entirely. This is quite unfortunate, as SEARCH command + is one of the best examples demonstrating IMAP advantage over POP3. + + The ALL and COUNT return options don't change how SEARCH is working + internally; they only change how information about found messages is + returned. MIN and MAX SEARCH result options described in this + document can lighten the load on IMAP servers that choose to optimize + SEARCHes containing only one or both of them. + + It is believed that this extension doesn't raise any additional + security concerns not already discussed in [IMAP4]. + +6. IANA Considerations + + IMAP4 capabilities are registered by publishing a standards track RFC + or an IESG-approved experimental RFC. The registry is currently + located at <http://www.iana.org/assignments/imap4-capabilities>. + + This document defines the ESEARCH IMAP capability, which IANA added + to the registry. + +7. Normative References + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [IMAP4] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [ABNF] Crocker, D. (Ed.) and P. Overell , "Augmented BNF for + Syntax Specifications: ABNF", RFC 4234, October 2005. + + [IMAPABNF] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 + ABNF", RFC 4466, April 2006.. + + [CONDSTORE] Melnikov, A. and S. Hole, "IMAP Extension for Conditional + STORE", RFC 4551, June 2006. + +8. Acknowledgments + + Thanks to Michael Wener, Arnt Gulbrandsen, Cyrus Daboo, Mark Crispin, + and Pete Maclean for comments and corrections. + + + + +Melnikov & Cridland Standards Track [Page 6] + +RFC 4731 IMAP4 Extension to SEARCH November 2006 + + +Authors' Addresses + + Alexey Melnikov + Isode Limited + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex, TW12 2BX + UK + + EMail: Alexey.Melnikov@isode.com + + + Dave A. Cridland + Inventure Systems Limited + + EMail: dave.cridland@inventuresystems.co.uk + URL: http://invsys.co.uk/dave/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Melnikov & Cridland Standards Track [Page 7] + +RFC 4731 IMAP4 Extension to SEARCH November 2006 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2006). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST, + AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT + THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY + IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR + PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + +Melnikov & Cridland Standards Track [Page 8] + diff --git a/imap/docs/rfc/rfc4752.txt b/imap/docs/rfc/rfc4752.txt new file mode 100644 index 00000000..bfd8e30b --- /dev/null +++ b/imap/docs/rfc/rfc4752.txt @@ -0,0 +1,563 @@ + + + + + + +Network Working Group A. Melnikov, Ed. +Request for Comments: 4752 Isode +Obsoletes: 2222 November 2006 +Category: Standards Track + + + The Kerberos V5 ("GSSAPI") + Simple Authentication and Security Layer (SASL) Mechanism + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The IETF Trust (2006). + +Abstract + + The Simple Authentication and Security Layer (SASL) is a framework + for adding authentication support to connection-based protocols. + This document describes the method for using the Generic Security + Service Application Program Interface (GSS-API) Kerberos V5 in the + SASL. + + This document replaces Section 7.2 of RFC 2222, the definition of the + "GSSAPI" SASL mechanism. This document, together with RFC 4422, + obsoletes RFC 2222. + + + + + + + + + + + + + + + + + + + +Melnikov Standards Track [Page 1] + +RFC 4752 SASL GSSAPI Mechanism November 2006 + + +Table of Contents + + 1. Introduction ....................................................2 + 1.1. Relationship to Other Documents ............................2 + 2. Conventions Used in This Document ...............................2 + 3. Kerberos V5 GSS-API Mechanism ...................................2 + 3.1. Client Side of Authentication Protocol Exchange ............3 + 3.2. Server Side of Authentication Protocol Exchange ............4 + 3.3. Security Layer .............................................6 + 4. IANA Considerations .............................................7 + 5. Security Considerations .........................................7 + 6. Acknowledgements ................................................8 + 7. Changes since RFC 2222 ..........................................8 + 8. References ......................................................8 + 8.1. Normative References .......................................8 + 8.2. Informative References .....................................9 + +1. Introduction + + This specification documents currently deployed Simple Authentication + and Security Layer (SASL [SASL]) mechanism supporting the Kerberos V5 + [KERBEROS] Generic Security Service Application Program Interface + ([GSS-API]) mechanism [RFC4121]. The authentication sequence is + described in Section 3. Note that the described authentication + sequence has known limitations, in particular, it lacks channel + bindings and the number of round-trips required to complete + authentication exchange is not minimal. SASL WG is working on a + separate document that should address these limitations. + +1.1. Relationship to Other Documents + + This document, together with RFC 4422, obsoletes RFC 2222 in its + entirety. This document replaces Section 7.2 of RFC 2222. The + remainder is obsoleted as detailed in Section 1.2 of RFC 4422. + +2. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" + in this document are to be interpreted as defined in "Key words for + use in RFCs to Indicate Requirement Levels" [KEYWORDS]. + +3. Kerberos V5 GSS-API Mechanism + + The SASL mechanism name for the Kerberos V5 GSS-API mechanism + [RFC4121] is "GSSAPI". Though known as the SASL GSSAPI mechanism, + the mechanism is specifically tied to Kerberos V5 and GSS-API's + Kerberos V5 mechanism. + + + + +Melnikov Standards Track [Page 2] + +RFC 4752 SASL GSSAPI Mechanism November 2006 + + + The GSSAPI SASL mechanism is a "client goes first" SASL mechanism; + i.e., it starts with the client sending a "response" created as + described in the following section. + + The implementation MAY set any GSS-API flags or arguments not + mentioned in this specification as is necessary for the + implementation to enforce its security policy. + + Note that major status codes returned by GSS_Init_sec_context() or + GSS_Accept_sec_context() other than GSS_S_COMPLETE or + GSS_S_CONTINUE_NEEDED cause authentication failure. Major status + codes returned by GSS_Unwrap() other than GSS_S_COMPLETE (without any + additional supplementary status codes) cause authentication and/or + security layer failure. + +3.1. Client Side of Authentication Protocol Exchange + + The client calls GSS_Init_sec_context, passing in + input_context_handle of 0 (initially), mech_type of the Kerberos V5 + GSS-API mechanism [KRB5GSS], chan_binding of NULL, and targ_name + equal to output_name from GSS_Import_Name called with input_name_type + of GSS_C_NT_HOSTBASED_SERVICE (*) and input_name_string of + "service@hostname" where "service" is the service name specified in + the protocol's profile, and "hostname" is the fully qualified host + name of the server. When calling the GSS_Init_sec_context, the + client MUST pass the integ_req_flag of TRUE (**). If the client will + be requesting a security layer, it MUST also supply to the + GSS_Init_sec_context a mutual_req_flag of TRUE, and a + sequence_req_flag of TRUE. If the client will be requesting a + security layer providing confidentiality protection, it MUST also + supply to the GSS_Init_sec_context a conf_req_flag of TRUE. The + client then responds with the resulting output_token. If + GSS_Init_sec_context returns GSS_S_CONTINUE_NEEDED, then the client + should expect the server to issue a token in a subsequent challenge. + The client must pass the token to another call to + GSS_Init_sec_context, repeating the actions in this paragraph. + + (*) Clients MAY use name types other than GSS_C_NT_HOSTBASED_SERVICE + to import servers' acceptor names, but only when they have a priori + knowledge that the servers support alternate name types. Otherwise + clients MUST use GSS_C_NT_HOSTBASED_SERVICE for importing acceptor + names. + + (**) Note that RFC 2222 [RFC2222] implementations will not work with + GSS-API implementations that require integ_req_flag to be true. No + implementations of RFC 1964 [KRB5GSS] or RFC 4121 [RFC4121] that + require integ_req_flag to be true are believed to exist and it is + expected that any future update to [RFC4121] will require that + + + +Melnikov Standards Track [Page 3] + +RFC 4752 SASL GSSAPI Mechanism November 2006 + + + integrity be available even in not explicitly requested by the + application. + + When GSS_Init_sec_context returns GSS_S_COMPLETE, the client examines + the context to ensure that it provides a level of protection + permitted by the client's security policy. In particular, if the + integ_avail flag is not set in the context, then no security layer + can be offered or accepted. + + If the conf_avail flag is not set in the context, then no security + layer with confidentiality can be offered or accepted. If the + context is acceptable, the client takes the following actions: If the + last call to GSS_Init_sec_context returned an output_token, then the + client responds with the output_token, otherwise the client responds + with no data. The client should then expect the server to issue a + token in a subsequent challenge. The client passes this token to + GSS_Unwrap and interprets the first octet of resulting cleartext as a + bit-mask specifying the security layers supported by the server and + the second through fourth octets as the maximum size output_message + the server is able to receive (in network byte order). If the + resulting cleartext is not 4 octets long, the client fails the + negotiation. The client verifies that the server maximum buffer is 0 + if the server does not advertise support for any security layer. + + The client then constructs data, with the first octet containing the + bit-mask specifying the selected security layer, the second through + fourth octets containing in network byte order the maximum size + output_message the client is able to receive (which MUST be 0 if the + client does not support any security layer), and the remaining octets + containing the UTF-8 [UTF8] encoded authorization identity. + (Implementation note: The authorization identity is not terminated + with the zero-valued (%x00) octet (e.g., the UTF-8 encoding of the + NUL (U+0000) character)). The client passes the data to GSS_Wrap + with conf_flag set to FALSE and responds with the generated + output_message. The client can then consider the server + authenticated. + +3.2. Server Side of Authentication Protocol Exchange + + A server MUST NOT advertise support for the "GSSAPI" SASL mechanism + described in this document unless it has acceptor credential for the + Kerberos V GSS-API mechanism [KRB5GSS]. + + The server passes the initial client response to + GSS_Accept_sec_context as input_token, setting input_context_handle + to 0 (initially), chan_binding of NULL, and a suitable + acceptor_cred_handle (see below). If GSS_Accept_sec_context returns + GSS_S_CONTINUE_NEEDED, the server returns the generated output_token + + + +Melnikov Standards Track [Page 4] + +RFC 4752 SASL GSSAPI Mechanism November 2006 + + + to the client in challenge and passes the resulting response to + another call to GSS_Accept_sec_context, repeating the actions in this + paragraph. + + Servers SHOULD use a credential obtained by calling GSS_Acquire_cred + or GSS_Add_cred for the GSS_C_NO_NAME desired_name and the Object + Identifier (OID) of the Kerberos V5 GSS-API mechanism [KRB5GSS](*). + Servers MAY use GSS_C_NO_CREDENTIAL as an acceptor credential handle. + Servers MAY use a credential obtained by calling GSS_Acquire_cred or + GSS_Add_cred for the server's principal name(s) (**) and the Kerberos + V5 GSS-API mechanism [KRB5GSS]. + + (*) Unlike GSS_Add_cred the GSS_Acquire_cred uses an OID set of GSS- + API mechanism as an input parameter. The OID set can be created by + using GSS_Create_empty_OID_set and GSS_Add_OID_set_member. It can be + freed by calling the GSS_Release_oid_set. + + + (**) Use of server's principal names having + GSS_C_NT_HOSTBASED_SERVICE name type and "service@hostname" format, + where "service" is the service name specified in the protocol's + profile, and "hostname" is the fully qualified host name of the + server, is RECOMMENDED. The server name is generated by calling + GSS_Import_name with input_name_type of GSS_C_NT_HOSTBASED_SERVICE + and input_name_string of "service@hostname". + + Upon successful establishment of the security context (i.e., + GSS_Accept_sec_context returns GSS_S_COMPLETE), the server SHOULD + verify that the negotiated GSS-API mechanism is indeed Kerberos V5 + [KRB5GSS]. This is done by examining the value of the mech_type + parameter returned from the GSS_Accept_sec_context call. If the + value differs, SASL authentication MUST be aborted. + + Upon successful establishment of the security context and if the + server used GSS_C_NO_NAME/GSS_C_NO_CREDENTIAL to create acceptor + credential handle, the server SHOULD also check using the + GSS_Inquire_context that the target_name used by the client matches + either + + - the GSS_C_NT_HOSTBASED_SERVICE "service@hostname" name syntax, + where "service" is the service name specified in the application + protocol's profile, + + or + + - the GSS_KRB5_NT_PRINCIPAL_NAME [KRB5GSS] name syntax for a two- + component principal where the first component matches the service + name specified in the application protocol's profile. + + + +Melnikov Standards Track [Page 5] + +RFC 4752 SASL GSSAPI Mechanism November 2006 + + + When GSS_Accept_sec_context returns GSS_S_COMPLETE, the server + examines the context to ensure that it provides a level of protection + permitted by the server's security policy. In particular, if the + integ_avail flag is not set in the context, then no security layer + can be offered or accepted. If the conf_avail flag is not set in the + context, then no security layer with confidentiality can be offered + or accepted. + + If the context is acceptable, the server takes the following actions: + If the last call to GSS_Accept_sec_context returned an output_token, + the server returns it to the client in a challenge and expects a + reply from the client with no data. Whether or not an output_token + was returned (and after receipt of any response from the client to + such an output_token), the server then constructs 4 octets of data, + with the first octet containing a bit-mask specifying the security + layers supported by the server and the second through fourth octets + containing in network byte order the maximum size output_token the + server is able to receive (which MUST be 0 if the server does not + support any security layer). The server must then pass the plaintext + to GSS_Wrap with conf_flag set to FALSE and issue the generated + output_message to the client in a challenge. + + The server must then pass the resulting response to GSS_Unwrap and + interpret the first octet of resulting cleartext as the bit-mask for + the selected security layer, the second through fourth octets as the + maximum size output_message the client is able to receive (in network + byte order), and the remaining octets as the authorization identity. + The server verifies that the client has selected a security layer + that was offered and that the client maximum buffer is 0 if no + security layer was chosen. The server must verify that the src_name + is authorized to act as the authorization identity. After these + verifications, the authentication process is complete. The server is + not expected to return any additional data with the success + indicator. + +3.3. Security Layer + + The security layers and their corresponding bit-masks are as follows: + + 1 No security layer + 2 Integrity protection. + Sender calls GSS_Wrap with conf_flag set to FALSE + 4 Confidentiality protection. + Sender calls GSS_Wrap with conf_flag set to TRUE + + Other bit-masks may be defined in the future; bits that are not + understood must be negotiated off. + + + + +Melnikov Standards Track [Page 6] + +RFC 4752 SASL GSSAPI Mechanism November 2006 + + + When decoding any received data with GSS_Unwrap, the major_status + other than the GSS_S_COMPLETE MUST be treated as a fatal error. + + Note that SASL negotiates the maximum size of the output_message to + send. Implementations can use the GSS_Wrap_size_limit call to + determine the corresponding maximum size input_message. + +4. IANA Considerations + + IANA modified the existing registration for "GSSAPI" as follows: + + Family of SASL mechanisms: NO + + SASL mechanism name: GSSAPI + + Security considerations: See Section 5 of RFC 4752 + + Published specification: RFC 4752 + + Person & email address to contact for further information: + Alexey Melnikov <Alexey.Melnikov@isode.com> + + Intended usage: COMMON + + Owner/Change controller: iesg@ietf.org + + Additional information: This mechanism is for the Kerberos V5 + mechanism of GSS-API. + +5. Security Considerations + + Security issues are discussed throughout this memo. + + When constructing the input_name_string, the client SHOULD NOT + canonicalize the server's fully qualified domain name using an + insecure or untrusted directory service. + + For compatibility with deployed software, this document requires that + the chan_binding (channel bindings) parameter to GSS_Init_sec_context + and GSS_Accept_sec_context be NULL, hence disallowing use of GSS-API + support for channel bindings. GSS-API channel bindings in SASL is + expected to be supported via a new GSS-API family of SASL mechanisms + (to be introduced in a future document). + + Additional security considerations are in the [SASL] and [GSS-API] + specifications. Additional security considerations for the GSS-API + mechanism can be found in [KRB5GSS] and [KERBEROS]. + + + + +Melnikov Standards Track [Page 7] + +RFC 4752 SASL GSSAPI Mechanism November 2006 + + +6. Acknowledgements + + This document replaces Section 7.2 of RFC 2222 [RFC2222] by John G. + Myers. He also contributed significantly to this revision. + + Lawrence Greenfield converted text of this document to the XML + format. + + Contributions of many members of the SASL mailing list are gratefully + acknowledged, in particular comments from Chris Newman, Nicolas + Williams, Jeffrey Hutzelman, Sam Hartman, Mark Crispin, and Martin + Rex. + +7. Changes since RFC 2222 + + RFC 2078 [RFC2078] specifies the version of GSS-API used by RFC 2222 + [RFC2222], which provided the original version of this specification. + That version of GSS-API did not provide the integ_integ_avail flag as + an input to GSS_Init_sec_context. Instead, integrity was always + requested. RFC 4422 [SASL] requires that when possible, the security + layer negotiation be integrity protected. To meet this requirement + and as part of moving from RFC 2078 [RFC2078] to RFC 2743 [GSS-API], + this specification requires that clients request integrity from + GSS_Init_sec_context so they can use GSS_Wrap to protect the security + layer negotiation. This specification does not require that the + mechanism offer the integrity security layer, simply that the + security layer negotiation be wrapped. + +8. References + +8.1. Normative References + + [GSS-API] Linn, J., "Generic Security Service Application Program + Interface Version 2, Update 1", RFC 2743, January 2000. + + [KERBEROS] Neuman, C., Yu, T., Hartman, S., and K. Raeburn, "The + Kerberos Network Authentication Service (V5)", RFC 4120, + July 2005. + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [KRB5GSS] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC + 1964, June 1996. + + + + + + + +Melnikov Standards Track [Page 8] + +RFC 4752 SASL GSSAPI Mechanism November 2006 + + + [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos + Version 5 Generic Security Service Application Program + Interface (GSS-API) Mechanism: Version 2", RFC 4121, July + 2005. + + [SASL] Melnikov, A. and K. Zeilenga, "Simple Authentication and + Security Layer (SASL)", RFC 4422, June 2006. + + [UTF8] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. + +8.2. Informative References + + [RFC2078] Linn, J., "Generic Security Service Application Program + Interface, Version 2", RFC 2078, January 1997. + + [RFC2222] Myers, J., "Simple Authentication and Security Layer + (SASL)", RFC 2222, October 1997. + +Editor's Address + + Alexey Melnikov + Isode Limited + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: Alexey.Melnikov@isode.com + URI: http://www.melnikov.ca/ + + + + + + + + + + + + + + + + + + + + + +Melnikov Standards Track [Page 9] + +RFC 4752 SASL GSSAPI Mechanism November 2006 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2006). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST, + AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT + THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY + IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR + PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + +Melnikov Standards Track [Page 10] + diff --git a/imap/docs/rfc/rfc4790.txt b/imap/docs/rfc/rfc4790.txt new file mode 100644 index 00000000..d58191c0 --- /dev/null +++ b/imap/docs/rfc/rfc4790.txt @@ -0,0 +1,1459 @@ + + + + + + +Network Working Group C. Newman +Request for Comments: 4790 Sun Microsystems +Category: Standards Track M. Duerst + Aoyama Gakuin University + A. Gulbrandsen + Oryx + March 2007 + + + Internet Application Protocol Collation Registry + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The IETF Trust (2007). + +Abstract + + Many Internet application protocols include string-based lookup, + searching, or sorting operations. However, the problem space for + searching and sorting international strings is large, not fully + explored, and is outside the area of expertise for the Internet + Engineering Task Force (IETF). Rather than attempt to solve such a + large problem, this specification creates an abstraction framework so + that application protocols can precisely identify a comparison + function, and the repertoire of comparison functions can be extended + in the future. + + + + + + + + + + + + + + + + + +Newman, et al. Standards Track [Page 1] + +RFC 4790 Collation Registry March 2007 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 1.1. Conventions Used in This Document . . . . . . . . . . . . 4 + 2. Collation Definition and Purpose . . . . . . . . . . . . . . . 4 + 2.1. Definition . . . . . . . . . . . . . . . . . . . . . . . . 4 + 2.2. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 2.3. Some Other Terms Used in this Document . . . . . . . . . . 5 + 2.4. Sort Keys . . . . . . . . . . . . . . . . . . . . . . . . 5 + 3. Collation Identifier Syntax . . . . . . . . . . . . . . . . . 6 + 3.1. Basic Syntax . . . . . . . . . . . . . . . . . . . . . . . 6 + 3.2. Wildcards . . . . . . . . . . . . . . . . . . . . . . . . 6 + 3.3. Ordering Direction . . . . . . . . . . . . . . . . . . . . 7 + 3.4. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 + 3.5. Naming Guidelines . . . . . . . . . . . . . . . . . . . . 7 + 4. Collation Specification Requirements . . . . . . . . . . . . . 8 + 4.1. Collation/Server Interface . . . . . . . . . . . . . . . . 8 + 4.2. Operations Supported . . . . . . . . . . . . . . . . . . . 8 + 4.2.1. Validity . . . . . . . . . . . . . . . . . . . . . . . 9 + 4.2.2. Equality . . . . . . . . . . . . . . . . . . . . . . . 9 + 4.2.3. Substring . . . . . . . . . . . . . . . . . . . . . . 9 + 4.2.4. Ordering . . . . . . . . . . . . . . . . . . . . . . . 10 + 4.3. Sort Keys . . . . . . . . . . . . . . . . . . . . . . . . 10 + 4.4. Use of Lookup Tables . . . . . . . . . . . . . . . . . . . 11 + 5. Application Protocol Requirements . . . . . . . . . . . . . . 11 + 5.1. Character Encoding . . . . . . . . . . . . . . . . . . . . 11 + 5.2. Operations . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.3. Wildcards . . . . . . . . . . . . . . . . . . . . . . . . 12 + 5.4. String Comparison . . . . . . . . . . . . . . . . . . . . 12 + 5.5. Disconnected Clients . . . . . . . . . . . . . . . . . . . 12 + 5.6. Error Codes . . . . . . . . . . . . . . . . . . . . . . . 13 + 5.7. Octet Collation . . . . . . . . . . . . . . . . . . . . . 13 + 6. Use by Existing Protocols . . . . . . . . . . . . . . . . . . 13 + 7. Collation Registration . . . . . . . . . . . . . . . . . . . . 14 + 7.1. Collation Registration Procedure . . . . . . . . . . . . . 14 + 7.2. Collation Registration Format . . . . . . . . . . . . . . 15 + 7.2.1. Registration Template . . . . . . . . . . . . . . . . 15 + 7.2.2. The Collation Element . . . . . . . . . . . . . . . . 15 + 7.2.3. The Identifier Element . . . . . . . . . . . . . . . . 16 + 7.2.4. The Title Element . . . . . . . . . . . . . . . . . . 16 + 7.2.5. The Operations Element . . . . . . . . . . . . . . . . 16 + 7.2.6. The Specification Element . . . . . . . . . . . . . . 16 + 7.2.7. The Submitter Element . . . . . . . . . . . . . . . . 16 + 7.2.8. The Owner Element . . . . . . . . . . . . . . . . . . 16 + 7.2.9. The Version Element . . . . . . . . . . . . . . . . . 17 + 7.2.10. The Variable Element . . . . . . . . . . . . . . . . . 17 + 7.3. Structure of Collation Registry . . . . . . . . . . . . . 17 + 7.4. Example Initial Registry Summary . . . . . . . . . . . . . 18 + + + +Newman, et al. Standards Track [Page 2] + +RFC 4790 Collation Registry March 2007 + + + 8. Guidelines for Expert Reviewer . . . . . . . . . . . . . . . . 18 + 9. Initial Collations . . . . . . . . . . . . . . . . . . . . . . 19 + 9.1. ASCII Numeric Collation . . . . . . . . . . . . . . . . . 20 + 9.1.1. ASCII Numeric Collation Description . . . . . . . . . 20 + 9.1.2. ASCII Numeric Collation Registration . . . . . . . . . 20 + 9.2. ASCII Casemap Collation . . . . . . . . . . . . . . . . . 21 + 9.2.1. ASCII Casemap Collation Description . . . . . . . . . 21 + 9.2.2. ASCII Casemap Collation Registration . . . . . . . . . 22 + 9.3. Octet Collation . . . . . . . . . . . . . . . . . . . . . 22 + 9.3.1. Octet Collation Description . . . . . . . . . . . . . 22 + 9.3.2. Octet Collation Registration . . . . . . . . . . . . . 23 + 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 + 11. Security Considerations . . . . . . . . . . . . . . . . . . . 23 + 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 23 + 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 24 + 13.1. Normative References . . . . . . . . . . . . . . . . . . . 24 + 13.2. Informative References . . . . . . . . . . . . . . . . . . 24 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Newman, et al. Standards Track [Page 3] + +RFC 4790 Collation Registry March 2007 + + +1. Introduction + + The Application Configuration Access Protocol ACAP [11] specification + introduced the concept of a comparator (which we call collation in + this document), but failed to create an IANA registry. With the + introduction of stringprep [6] and the Unicode Collation Algorithm + [7], it is now time to create that registry and populate it with some + initial values appropriate for an international community. This + specification replaces and generalizes the definition of a comparator + in ACAP, and creates a collation registry. + +1.1. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" + in this document are to be interpreted as defined in "Key words for + use in RFCs to Indicate Requirement Levels" [1]. + + The attribute syntax specifications use the Augmented Backus-Naur + Form (ABNF) [2] notation, including the core rules defined in + Appendix A. The ABNF production "Language-tag" is imported from + Language Tags [5] and "reg-name" from URI: Generic Syntax [4]. + +2. Collation Definition and Purpose + +2.1. Definition + + A collation is a named function which takes two arbitrary length + strings as input and can be used to perform one or more of three + basic comparison operations: equality test, substring match, and + ordering test. + +2.2. Purpose + + Collations are an abstraction for comparison functions so that these + comparison functions can be used in multiple protocols. The details + of a particular comparison operation can be specified by someone with + appropriate expertise, independent of the application protocols that + use that collation. This is similar to the way a charset [13] + separates the details of octet to character mapping from a protocol + specification, such as MIME [9], or the way SASL [10] separates the + details of an authentication mechanism from a protocol specification, + such as ACAP [11]. + + + + + + + + + +Newman, et al. Standards Track [Page 4] + +RFC 4790 Collation Registry March 2007 + + + Here is a small diagram to help illustrate the value of this + abstraction: + + +-------------------+ +-----------------+ + | IMAP i18n SEARCH |--+ | Basic | + +-------------------+ | +--| Collation Spec | + | | +-----------------+ + +-------------------+ | +-------------+ | +-----------------+ + | ACAP i18n SEARCH |--+--| Collation |--+--| A stringprep | + +-------------------+ | | Registry | | | Collation Spec | + | +-------------+ | +-----------------+ + +-------------------+ | | +-----------------+ + | ...other protocol |--+ | | locale-specific | + +-------------------+ +--| Collation Spec | + +-----------------+ + + Thus IMAP, ACAP, and future application protocols with international + search capability simply specify how to interface to the collation + registry instead of each protocol specification having to specify all + the collations it supports. + +2.3. Some Other Terms Used in this Document + + The terms client, server, and protocol are used in somewhat unusual + senses. + + Client means a user, or a program acting directly on behalf of a + user. This may be a mail reader acting as an IMAP client, or it may + be an interactive shell, where the user can type protocol commands/ + requests directly, or it may be a script or program written by the + user. + + Server means a program that performs services requested by the + client. This may be a traditional server such as an HTTP server, or + it may be a Sieve [14] interpreter running a Sieve script written by + a user. A server needs to use the operations provided by collations + in order to fulfill the client's requests. + + The protocol describes how the client tells the server what it wants + done, and (if applicable) how the server tells the client about the + results. IMAP is a protocol by this definition, and so is the Sieve + language. + +2.4. Sort Keys + + One component of a collation is a transformation, which turns a + string into a sort key, which is then used while sorting. + + + + +Newman, et al. Standards Track [Page 5] + +RFC 4790 Collation Registry March 2007 + + + The transformation can range from an identity mapping (e.g., the + i;octet collation Section 9.3) to a mapping that makes the string + unreadable to a human. + + This is an implementation detail of collations or servers. A + protocol SHOULD NOT expose it to clients, since some collations leave + the sort key's format up to the implementation, and current + conformant implementations are known to use different formats. + +3. Collation Identifier Syntax + +3.1. Basic Syntax + + The collation identifier itself is a single US-ASCII string. The + identifier MUST NOT be longer than 254 characters, and obeys the + following grammar: + + collation-char = ALPHA / DIGIT / "-" / ";" / "=" / "." + + collation-id = collation-prefix ";" collation-core-name + *collation-arg + + collation-scope = Language-tag / "vnd-" reg-name + + collation-core-name = ALPHA *( ALPHA / DIGIT / "-" ) + + collation-arg = ";" ALPHA *( ALPHA / DIGIT ) "=" + 1*( ALPHA / DIGIT / "." ) + + + Note: the ABNF production "Language-tag" is imported from Language + Tags [5] and "reg-name" from URI: Generic Syntax [4]. + + There is a special identifier called "default". For protocols that + have a default collation, "default" refers to that collation. For + other protocols, the identifier "default" MUST match no collations, + and servers SHOULD treat it in the same way as they treat nonexistent + collations. + +3.2. Wildcards + + The string a client uses to select a collation MAY contain one or + more wildcard ("*") characters that match zero or more collation- + chars. Wildcard characters MUST NOT be adjacent. If the wildcard + string matches multiple collations, the server SHOULD attempt to + select a widely useful collation in preference to a narrowly useful + one. + + + + +Newman, et al. Standards Track [Page 6] + +RFC 4790 Collation Registry March 2007 + + + collation-wild = ("*" / (ALPHA ["*"])) *(collation-char ["*"]) + ; MUST NOT exceed 254 characters total + +3.3. Ordering Direction + + When used as a protocol element for ordering, the collation + identifier MAY be prefixed by either "+" or "-" to explicitly specify + an ordering direction. "+" has no effect on the ordering operation, + while "-" inverts the result of the ordering operation. In general, + collation-order is used when a client requests a collation, and + collation-selected is used when the server informs the client of the + selected collation. + + collation-selected = ["+" / "-"] collation-id + + collation-order = ["+" / "-"] collation-wild + +3.4. URIs + + Some protocols are designed to use URIs [4] to refer to collations + rather than simple tokens. A special section of the IANA URL space + is reserved for such usage. The "collation-uri" form is used to + refer to a specific named collation (the collation registration may + not actually be present). The "collation-auri" form is an abstract + name for an ordering, a collation pattern or a vendor private + collator. + + collation-uri = "http://www.iana.org/assignments/collation/" + collation-id ".xml" + + collation-auri = ( "http://www.iana.org/assignments/collation/" + collation-order ".xml" ) / other-uri + + other-uri = <absoluteURI> + ; excluding the IANA collation namespace. + +3.5. Naming Guidelines + + While this specification makes no absolute requirements on the + structure of collation identifiers, naming consistency is important, + so the following initial guidelines are provided. + + Collation identifiers with an international audience typically begin + with "i;". Collation identifiers intended for a particular language + or locale typically begin with a language tag [5] followed by a ";". + After the first ";" is normally the name of the general collation + algorithm, followed by a series of algorithm modifications separated + by the ";" delimiter. Parameterized modifications will use "=" to + + + +Newman, et al. Standards Track [Page 7] + +RFC 4790 Collation Registry March 2007 + + + delimit the parameter from the value. The version numbers of any + lookup tables used by the algorithm SHOULD be present as + parameterized modifications. + + Collation identifiers of the form *;vnd-hostname;* are reserved for + vendor-specific collations created by the owner of the hostname + following the "vnd-" prefix (e.g., vnd-example.com for the vendor + example.com). Registration of such collations (or the name space as + a whole), with intended use of the "Vendor", is encouraged when a + public specification or open-source implementation is available, but + is not required. + +4. Collation Specification Requirements + +4.1. Collation/Server Interface + + The collation itself defines what it operates on. Most collations + are expected to operate on character strings. The i;octet + (Section 9.3) collation operates on octet strings. The i;ascii- + numeric (Section 9.1) operation operates on numbers. + + This specification defines the collation interface in terms of octet + strings. However, implementations may choose to use character + strings instead. Such implementations may not be able to implement + e.g., i;octet. Since i;octet is not currently mandatory to implement + for any protocol, this should not be a problem. + +4.2. Operations Supported + + A collation specification MUST state which of the three basic + operations are supported (equality, substring, ordering) and how to + perform each of the supported operations on any two input character + strings, including empty strings. Collations must be deterministic, + i.e., given a collation with a specific identifier, and any two fixed + input strings, the result MUST be the same for the same operation. + + In general, collation operations should behave as their names + suggest. While a collation may be new, the operations are not, so + the new collation's operations should be similar to those of older + collations. For example, a date/time collation should not provide a + "substring" operation that would morph IMAP substring SEARCH into + e.g., a date-range search. + + A non-obvious consequence of the rules for each collation operation + is that, for any single collation, either none or all of the + operations can return "undefined". For example, it is not possible + to have an equality operation that never returns "undefined", and a + substring operation that occasionally does. + + + +Newman, et al. Standards Track [Page 8] + +RFC 4790 Collation Registry March 2007 + + +4.2.1. Validity + + The validity test takes one string as argument. It returns valid if + its input string is a valid input to the collation's other + operations, and invalid if not. (In other words, a string is valid + if it is equal to itself according to the collation's equality + operation.) + + The validity test is provided by all collations. It MUST NOT be + listed separately in the collation registration. + +4.2.2. Equality + + The equality test always returns "match" or "no-match" when it is + supplied valid input, and MAY return "undefined" if one or both input + strings are not valid. + + The equality test MUST be reflexive and symmetric. For valid input, + it MUST be transitive. + + If a collation provides either a substring or an ordering test, it + MUST also provide an equality test. The substring and/or ordering + tests MUST be consistent with the equality test. + + The return values of the equality test are called "match", "no-match" + and "undefined" in this document. + +4.2.3. Substring + + The substring matching operation determines if the first string is a + substring of the second string, i.e., if one or more substrings of + the second string is equal to the first, as defined by the + collation's equality operation. + + A collation that supports substring matching will automatically + support two special cases of substring matching: prefix and suffix + matching, if those special cases are supported by the application + protocol. It returns "match" or "no-match" when it is supplied valid + input and returns "undefined" when supplied invalid input. + + Application protocols MAY return position information for substring + matches. If this is done, the position information SHOULD include + both the starting offset and the ending offset for each match. This + is important because more sophisticated collations can match strings + of unequal length (for example, a pre-composed accented character can + match a decomposed accented character). In general, overlapping + matches SHOULD be reported (as when "ana" occurs twice within + "banana"), although there are cases where a collation may decide not + + + +Newman, et al. Standards Track [Page 9] + +RFC 4790 Collation Registry March 2007 + + + to. For example, in a collation which treats all whitespace + sequences as identical, the substring operation could be defined such + that " 1 " (SP "1" SP) is reported just once within " 1 " (SP SP + "1" SP SP), not four times (SP SP "1" SP, SP "1" SP, SP "1" SP SP and + SP SP "1" SP SP), since the four matches are, in a sense, the same + match. + + A string is a substring of itself. The empty string is a substring + of all strings. + + Note that the substring operation of some collations can match + strings of unequal length. For example, a pre-composed accented + character can match a decomposed accented character. The Unicode + Collation Algorithm [7] discusses this in more detail. + + The return values of the substring operation are called "match", "no- + match", and "undefined" in this document. + +4.2.4. Ordering + + The ordering operation determines how two strings are ordered. It + MUST be reflexive. For valid input, it MUST be transitive and + trichotomous. + + Ordering returns "less" if the first string is listed before the + second string, according to the collation; "greater", if the second + string is listed before the first string; and "equal", if the two + strings are equal, as defined by the collation's equality operation. + If one or both strings are invalid, the result of ordering is + "undefined". + + When the collation is used with a "+" prefix, the behavior is the + same as when used with no prefix. When the collation is used with a + "-" prefix, the result of the ordering operation of the collation + MUST be reversed. + + The return values of the ordering operation are called "less", + "equal", "greater", and "undefined" in this document. + +4.3. Sort Keys + + A collation specification SHOULD describe the internal transformation + algorithm to generate sort keys. This algorithm can be applied to + individual strings, and the result can be stored to potentially + optimize future comparison operations. A collation MAY specify that + the sort key is generated by the identity function. The sort key may + have no meaning to a human. The sort key may not be valid input to + the collation. + + + +Newman, et al. Standards Track [Page 10] + +RFC 4790 Collation Registry March 2007 + + +4.4. Use of Lookup Tables + + Some collations use customizable lookup tables, e.g., because the + tables depend on locale, and may be modified after shipping the + software. Collations that use more than one customizable lookup + table in a documented format MUST assign numbers to the tables they + use. This permits an application protocol command to access the + tables used by a server collation, so that clients and servers use + the same tables. + +5. Application Protocol Requirements + + This section describes the requirements and issues that an + application protocol needs to consider if it offers searching, + substring matching and/or sorting, and permits the use of characters + outside the US-ASCII charset. + +5.1. Character Encoding + + The protocol specification has to make sure that it is clear on which + characters (rather than just octets) the collations are used. This + can be done by specifying the protocol itself in terms of characters + (e.g., in the case of a query language), by specifying a single + character encoding for the protocol (e.g., UTF-8 [3]), or by + carefully describing the relevant issues of character encoding + labeling and conversion. In the later case, details to consider + include how to handle unknown charsets, any charsets that are + mandatory-to-implement, any issues with byte-order that might apply, + and any transfer encodings that need to be supported. + +5.2. Operations + + The protocol must specify which of the operations defined in this + specification (equality matching, substring matching, and ordering) + can be invoked in the protocol, and how they are invoked. There may + be more than one way to invoke an operation. + + The protocol MUST provide a mechanism for the client to select the + collation to use with equality matching, substring matching, and + ordering. + + If a protocol needs a total ordering and the collation chosen does + not provide it because the ordering operation returns "undefined" at + least once, the recommended fallback is to sort all invalid strings + after the valid ones, and use i;octet to order the invalid strings. + + Although the collation's substring function provides a list of + matches, a protocol need not provide all that to the client. It may + + + +Newman, et al. Standards Track [Page 11] + +RFC 4790 Collation Registry March 2007 + + + provide only the first matching substring, or even just the + information that the substring search matched. In this way, + collations can be used with protocols that are defined such that "x + is a substring of y" returns true-false. + + If the protocol provides positional information for the results of a + substring match, that positional information SHOULD fully specify the + substring(s) in the result that matches, independent of the length of + the search string. For example, returning both the starting and + ending offset of the match would suffice, as would the starting + offset and a length. Returning just the starting offset is not + acceptable. This rule is necessary because advanced collations can + treat strings of different lengths as equal (for example, pre- + composed and decomposed accented characters). + +5.3. Wildcards + + The protocol MUST specify whether it allows the use of wildcards in + collation identifiers. If the protocol allows wildcards, then: + The protocol MUST specify how comparisons behave in the absence of + explicit collation negotiation, or when a collation of "default" + is requested. The protocol MAY specify that the default collation + used in such circumstances is sensitive to server configuration. + + The protocol SHOULD provide a way to list available collations + matching a given wildcard pattern, or patterns. + +5.4. String Comparison + + If a protocol compares strings in any nontrivial way, using a + collation may be appropriate. As an example, many protocols use + case-independent strings. In many cases, a simple ASCII mapping to + upper/lower case works well. In other cases, it may be better to use + a specifiable collation; for example, so that a server can treat "i" + and "I" as equivalent in Italy, and different in Turkey (Turkish also + has a dotted upper-case" I" and a dotless lower-case "i"). + + Protocol designers should consider, in each case, whether to use a + specifiable collation. Keywords often have other needs than user + variables, and search arguments may be different again. + +5.5. Disconnected Clients + + If the protocol supports disconnected clients, and a collation is + used that can use configurable tables (e.g., to support + locale-specific extensions), then the client may not be able to + reproduce the server's collation operations while offline. + + + + +Newman, et al. Standards Track [Page 12] + +RFC 4790 Collation Registry March 2007 + + + A mechanism to download such tables has been discussed. Such a + mechanism is not included in the present specification, since the + problem is not yet well understood. + +5.6. Error Codes + + The protocol specification should consider assigning protocol error + codes for the following circumstances: + + o The client requests the use of a collation by identifier or + pattern, but no implemented collation matches that pattern. + + o The client attempts to use a collation for an operation that is + not supported by that collation -- for example, attempting to use + the "i;ascii-numeric" collation for substring matching. + + o The client uses an equality or substring matching collation, and + the result is an error. It may be appropriate to distinguish + between the two input strings, particularly when one is supplied + by the client and the other is stored by the server. It might + also be appropriate to distinguish the specific case of an invalid + UTF-8 string. + +5.7. Octet Collation + + The i;octet (Section 9.3) collation is only usable with protocols + based on octet-strings. Clients and servers MUST NOT use i;octet + with other protocols. + + If the protocol permits the use of collations with data structures + other than strings, the protocol MUST describe the default behavior + for a collation with those data structures. + +6. Use by Existing Protocols + + This section is informative. + + Both ACAP [11] and Sieve [14] are standards track specifications that + used collations prior to the creation of this specification and + registry. Those standards do not meet all the application protocol + requirements described in Section 5. + + These protocols allow the use of the i;octet (Section 9.3) collation + working directly on UTF-8 data, as used in these protocols. + + + + + + + +Newman, et al. Standards Track [Page 13] + +RFC 4790 Collation Registry March 2007 + + + In Sieve, all matches are either true or false. Accordingly, Sieve + servers must treat "undefined" and "no-match" results of the equality + and substring operations as false, and only "match" as true. + + In ACAP and Sieve, there are no invalid strings. In this document's + terms, invalid strings sort after valid strings. + + IMAP [15] also collates, although that is explicit only when the + COMPARATOR [17] extension is used. The built-in IMAP substring + operation and the ordering provided by the SORT [16] extension may + not meet the requirements made in this document. + + Other protocols may be in a similar position. + + In IMAP, the default collation is i;ascii-casemap, because its + operations are understood to match IMAP's built-in operations. + +7. Collation Registration + +7.1. Collation Registration Procedure + + The IETF will create a mailing list, collation@ietf.org, which can be + used for public discussion of collation proposals prior to + registration. Use of the mailing list is strongly encouraged. The + IESG will appoint a designated expert who will monitor the + collation@ietf.org mailing list and review registrations. + + The registration procedure begins when a completed registration + template is sent to iana@iana.org and collation@ietf.org. The + designated expert is expected to tell IANA and the submitter of the + registration within two weeks whether the registration is approved, + approved with minor changes, or rejected with cause. When a + registration is rejected with cause, it can be re-submitted if the + concerns listed in the cause are addressed. Decisions made by the + designated expert can be appealed to the IESG Applications Area + Director, then to the IESG. They follow the normal appeals procedure + for IESG decisions. + + Collation registrations in a standards track, BCP, or IESG-approved + experimental RFC are owned by the IETF, and changes to the + registration follow normal procedures for updating such documents. + Collation registrations in other RFCs are owned by the RFC author(s). + Other collation registrations are owned by the individual(s) listed + in the contact field of the registration, and IANA will preserve this + information. + + If the registration is a change of an existing collation, it MUST be + approved by the owner. In the event the owner cannot be contacted + + + +Newman, et al. Standards Track [Page 14] + +RFC 4790 Collation Registry March 2007 + + + for a period of one month, and the designated expert deems the change + necessary, the IESG MAY re-assign ownership to an appropriate party. + +7.2. Collation Registration Format + + Registration of a collation is done by sending a well-formed XML + document to collation@ietf.org and iana@iana.org. + +7.2.1. Registration Template + + Here is a template for the registration: + + <?xml version='1.0'?> + <!DOCTYPE collation SYSTEM 'collationreg.dtd'> + <collation rfc="YYYY" scope="global" intendedUse="common"> + <identifier>collation identifier</identifier> + <title>technical title for collation</title> + <operations>equality order substring</operations> + <specification>specification reference</specification> + <owner>email address of owner or IETF</owner> + <submitter>email address of submitter</submitter> + <version>1</version> + </collation> + +7.2.2. The Collation Element + + The root of the registration document MUST be a <collation> element. + The collation element contains the other elements in the + registration, which are described in the following sub-subsections, + in the order given here. + + The <collation> element MAY include an "rfc=" attribute if the + specification is in an RFC. The "rfc=" attribute gives only the + number of the RFC, without any prefix, such as "RFC", or suffix, such + as ".txt". + + The <collation> element MUST include a "scope=" attribute, which MUST + have one of the values "global", "local", or "other". + + The <collation> element MUST include an "intendedUse=" attribute, + which must have one of the values "common", "limited", "vendor", or + "deprecated". Collation specifications intended for "common" use are + expected to reference standards from standards bodies with + significant experience dealing with the details of international + character sets. + + Be aware that future revisions of this specification may add + additional function types, as well as additional XML attributes, + + + +Newman, et al. Standards Track [Page 15] + +RFC 4790 Collation Registry March 2007 + + + values, and elements. Any system that automatically parses these XML + documents MUST take this into account to preserve future + compatibility. + +7.2.3. The Identifier Element + + The <identifier> element gives the precise identifier of the + collation, e.g., i;ascii-casemap. The <identifier> element is + mandatory. + +7.2.4. The Title Element + + The <title> element gives the title of the collation. The <title> + element is mandatory. + +7.2.5. The Operations Element + + The <operations> element lists which of the three operations + ("equality", "order" or "substring") the collation provides, + separated by single spaces. The <operations> element is mandatory. + +7.2.6. The Specification Element + + The <specification> element describes where to find the + specification. The <specification> element is mandatory. It MAY + have a URI attribute. There may be more than one <specification> + element, in which case, they together form the specification. + + If it is discovered that parts of a collation specification conflict, + a new revision of the collation is necessary, and the + collation@ietf.org mailing list should be notified. + +7.2.7. The Submitter Element + + The <submitter> element provides an RFC 2822 [12] email address for + the person who submitted the registration. It is optional if the + <owner> element contains an email address. + + There may be more than one <submitter> element. + +7.2.8. The Owner Element + + The <owner> element contains either the four letters "IETF" or an + email address of the owner of the registration. The <owner> element + is mandatory. There may be more than one <owner> element. If so, + all owners are equal. Each owner can speak for all. + + + + + +Newman, et al. Standards Track [Page 16] + +RFC 4790 Collation Registry March 2007 + + +7.2.9. The Version Element + + The <version> element MUST be included when the registration is + likely to be revised, or has been revised in such a way that the + results change for one or more input strings. The <version> element + is optional. + +7.2.10. The Variable Element + + The <variable> element specifies an optional variable to control the + collation's behaviour, for example whether it is case sensitive. The + <variable> element is optional. When <variable> is used, it must + contain <name> and <default> elements, and it may contain one or more + <value> elements. + +7.2.10.1. The Name Element + + The <name> element specifies the name value of a variable. The + <name> element is mandatory. + +7.2.10.2. The Default Element + + The <default> element specifies the default value of a variable. The + <default> element is mandatory. + +7.2.10.3. The Value Element + + The <value> element specifies a legal value of a variable. The + <value> element is optional. If one or more <value> elements are + present, only those values are legal. If none are, then the + variable's legal values do not form an enumerated set, and the rules + MUST be specified in an RFC accompanying the registration. + +7.3. Structure of Collation Registry + + Once the registration is approved, IANA will store each XML + registration document in a URL of the form + http://www.iana.org/assignments/collation/collation-id.xml, where + collation-id is the content of the identifier element in the + registration. Both the submitter and the designated expert are + responsible for verifying that the XML is well-formed. The + registration document should avoid using new elements. If any are + necessary, it is important to be consistent with other registrations. + + IANA will also maintain a text summary of the registry under the name + http://www.iana.org/assignments/collation/collation-index.html. This + summary is divided into four sections. The first section is for + collations intended for common use. This section is intended for + + + +Newman, et al. Standards Track [Page 17] + +RFC 4790 Collation Registry March 2007 + + + collation registrations published in IESG-approved RFCs, or for + locally scoped collations from the primary standards body for that + locale. The designated expert is encouraged to reject collation + registrations with an intended use of "common" if the expert believes + it should be "limited", as it is desirable to keep the number of + "common" registrations small and of high quality. The second section + is reserved for limited-use collations. The third section is + reserved for registered vendor-specific collations. The final + section is reserved for deprecated collations. + +7.4. Example Initial Registry Summary + + The following is an example of how IANA might structure the initial + registry summary.html file: + + Collation Functions Scope Reference + --------- --------- ----- --------- + Common Use Collations: + i;ascii-casemap e, o, s Local [RFC 4790] + + Limited Use Collations: + i;octet e, o, s Other [RFC 4790] + i;ascii-numeric e, o Other [RFC 4790] + + Vendor Collations: + + Deprecated Collations: + + + References + ---------- + [RFC 4790] Newman, C., Duerst, M., Gulbrandsen, A., "Internet + Application Protocol Collation Registry", RFC 4790, + Sun Microsystems, March 2007. + +8. Guidelines for Expert Reviewer + + The expert reviewer appointed by the IESG has fairly broad latitude + for this registry. While a number of collations are expected + (particularly customizations of the UCA for localized use), an + explosion of collations (particularly common-use collations) is not + desirable for widespread interoperability. However, it is important + for the expert reviewer to provide cause when rejecting a + registration, and, when possible, to describe corrective action to + + + + + + + +Newman, et al. Standards Track [Page 18] + +RFC 4790 Collation Registry March 2007 + + + permit the registration to proceed. The following table includes + some example reasons to reject a registration with cause: + + o The registration is not a well-formed XML document. + + o The registration has an intended use of "common", but there is no + evidence the collation will be widely deployed, so it should be + listed as "limited". + + o The registration has an intended use of "common", but it is + redundant with the functionality of a previously registered + "common" collation. + + o The registration has an intended use of "common", but the + specification is not detailed enough to allow interoperable + implementations by others. + + o The collation identifier fails to precisely identify the version + numbers of relevant tables to use. + + o The registration fails to meet one of the "MUST" requirements in + Section 4. + + o The collation identifier fails to meet the syntax in Section 3. + + o The collation specification referenced in the registration is + vague or has optional features without a clear behavior specified. + + o The referenced specification does not adequately address security + considerations specific to that collation. + + o The registration's operations are needlessly different from those + of traditional operations. + + o The registration's XML is needlessly different from that of + already registered collations. + +9. Initial Collations + + This section registers the three collations that were originally + defined in [11], and are implemented in most [14] engines. Some of + the behavior of these collations is perhaps not ideal, such as + i;ascii-casemap accepting non-ASCII input. Compatibility with widely + deployed code was judged more important than fixing the collations. + Some of the aspects of these collations are necessary to maintain + compatibility with widely deployed code. + + + + + +Newman, et al. Standards Track [Page 19] + +RFC 4790 Collation Registry March 2007 + + +9.1. ASCII Numeric Collation + +9.1.1. ASCII Numeric Collation Description + + The "i;ascii-numeric" collation is a simple collation intended for + use with arbitrarily-sized, unsigned decimal integer numbers stored + as octet strings. US-ASCII digits (0x30 to 0x39) represent digits of + the numbers. Before converting from string to integer, the input + string is truncated at the first non-digit character. All input is + valid; strings that do not start with a digit represent positive + infinity. + + The collation supports equality and ordering, but does not support + the substring operation. + + The equality operation returns "match" if the two strings represent + the same number (i.e., leading zeroes and trailing non-digits are + disregarded), and "no-match" if the two strings represent different + numbers. + + The ordering operation returns "less" if the first string represents + a smaller number than the second, "equal" if they represent the same + number, and "greater" if the first string represents a larger number + than the second. + + Some examples: "0" is less than "1", and "1" is less than + "4294967298". "4294967298", "04294967298", and "4294967298b" are all + equal. "04294967298" is less than "". "", "x", and "y" are equal. + +9.1.2. ASCII Numeric Collation Registration + + <?xml version='1.0'?> + <!DOCTYPE collation SYSTEM 'collationreg.dtd'> + <collation rfc="4790" scope="other" intendedUse="limited"> + <identifier>i;ascii-numeric</identifier> + <title>ASCII Numeric</title> + <operations>equality order</operations> + <specification>RFC 4790</specification> + <owner>IETF</owner> + <submitter>chris.newman@sun.com</submitter> + </collation> + + + + + + + + + + +Newman, et al. Standards Track [Page 20] + +RFC 4790 Collation Registry March 2007 + + +9.2. ASCII Casemap Collation + +9.2.1. ASCII Casemap Collation Description + + The "i;ascii-casemap" collation is a simple collation that operates + on octet strings and treats US-ASCII letters case-insensitively. It + provides equality, substring, and ordering operations. All input is + valid. Note that letters outside ASCII are not treated case- + insensitively. + + Its equality, ordering, and substring operations are as for i;octet, + except that at first, the lower-case letters (octet values 97-122) in + each input string are changed to upper case (octet values 65-90). + + Care should be taken when using OS-supplied functions to implement + this collation, as it is not locale sensitive. Functions, such as + strcasecmp and toupper, are sometimes locale sensitive, and may + inappropriately map lower-case letters other than a-z to upper case. + + The i;ascii-casemap collation is well-suited for use with many + Internet protocols and computer languages. Use with natural language + is often inappropriate; even though the collation apparently supports + languages such as Swahili and English, in real-world use, it tends to + mis-sort a number of types of string: + + o people and place names containing non-ASCII, + + o words such as "naive" (if spelled with an accent, the accented + character could push the word to the wrong spot in a sorted list), + + o names such as "Lloyd" (which, in Welsh, sorts after "Lyon", unlike + in English), + + o strings containing euro and pound sterling symbols, quotation + marks other than '"', dashes/hyphens, etc. + + + + + + + + + + + + + + + + +Newman, et al. Standards Track [Page 21] + +RFC 4790 Collation Registry March 2007 + + +9.2.2. ASCII Casemap Collation Registration + + <?xml version='1.0'?> + <!DOCTYPE collation SYSTEM 'collationreg.dtd'> + <collation rfc="4790" scope="local" intendedUse="common"> + <identifier>i;ascii-casemap</identifier> + <title>ASCII Casemap</title> + <operations>equality order substring</operations> + <specification>RFC 4790</specification> + <owner>IETF</owner> + <submitter>chris.newman@sun.com</submitter> + </collation> + +9.3. Octet Collation + +9.3.1. Octet Collation Description + + The "i;octet" collation is a simple and fast collation intended for + use on binary octet strings rather than on character data. Protocols + that want to make this collation available have to do so by + explicitly allowing it. If not explicitly allowed, it MUST NOT be + used. It never returns an "undefined" result. It provides equality, + substring, and ordering operations. + + The ordering algorithm is as follows: + + 1. If both strings are the empty string, return the result "equal". + + 2. If the first string is empty and the second is not, return the + result "less". + + 3. If the second string is empty and the first is not, return the + result "greater". + + 4. If both strings begin with the same octet value, remove the first + octet from both strings and repeat this algorithm from step 1. + + 5. If the unsigned value (0 to 255) of the first octet of the first + string is less than the unsigned value of the first octet of the + second string, then return "less". + + 6. If this step is reached, return "greater". + + This algorithm is roughly equivalent to the C library function + memcmp, with appropriate length checks added. + + + + + + +Newman, et al. Standards Track [Page 22] + +RFC 4790 Collation Registry March 2007 + + + The matching operation returns "match" if the sorting algorithm would + return "equal". Otherwise, the matching operation returns "no- + match". + + The substring operation returns "match" if the first string is the + empty string, or if there exists a substring of the second string of + length equal to the length of the first string, which would result in + a "match" result from the equality function. Otherwise, the + substring operation returns "no-match". + +9.3.2. Octet Collation Registration + + This collation is defined with intendedUse="limited" because it can + only be used by protocols that explicitly allow it. + + <?xml version='1.0'?> + <!DOCTYPE collation SYSTEM 'collationreg.dtd'> + <collation rfc="4790" scope="global" intendedUse="limited"> + <identifier>i;octet</identifier> + <title>Octet</title> + <operations>equality order substring</operations> + <specification>RFC 4790</specification> + <owner>IETF</owner> + <submitter>chris.newman@sun.com</submitter> + </collation> + +10. IANA Considerations + + Section 7 defines how to register collations with IANA. Section 9 + defines a list of predefined collations that have been registered + with IANA. + +11. Security Considerations + + Collations will normally be used with UTF-8 strings. Thus, the + security considerations for UTF-8 [3], stringprep [6], and Unicode + TR-36 [8] also apply, and are normative to this specification. + +12. Acknowledgements + + The authors want to thank all who have contributed to this document, + including Brian Carpenter, John Cowan, Dave Cridland, Mark Davis, + Spencer Dawkins, Lisa Dusseault, Lars Eggert, Frank Ellermann, Philip + Guenther, Tony Hansen, Ted Hardie, Sam Hartman, Kjetil Torgrim Homme, + Michael Kay, John Klensin, Alexey Melnikov, Jim Melton, and Abhijit + Menon-Sen. + + + + + +Newman, et al. Standards Track [Page 23] + +RFC 4790 Collation Registry March 2007 + + +13. References + +13.1. Normative References + + [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement + Levels", BCP 14, RFC 2119, March 1997. + + [2] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 4234, October 2005. + + [3] Yergeau, F., "UTF-8, a transformation format of ISO 10646", + STD 63, RFC 3629, November 2003. + + [4] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", RFC 3986, + January 2005. + + [5] Phillips, A. and M. Davis, "Tags for Identifying Languages", + BCP 47, RFC 4646, September 2006. + + [6] Hoffman, P. and M. Blanchet, "Preparation of Internationalized + Strings ("stringprep")", RFC 3454, December 2002. + + [7] Davis, M. and K. Whistler, "Unicode Collation Algorithm version + 14", May 2005, + <http://www.unicode.org/reports/tr10/tr10-14.html>. + + [8] Davis, M. and M. Suignard, "Unicode Security Considerations", + February 2006, <http://www.unicode.org/reports/tr36/>. + +13.2. Informative References + + [9] Freed, N. and N. Borenstein, "Multipurpose Internet Mail + Extensions (MIME) Part One: Format of Internet Message Bodies", + RFC 2045, November 1996. + + [10] Melnikov, A., "Simple Authentication and Security Layer + (SASL)", RFC 4422, June 2006. + + [11] Newman, C. and J. Myers, "ACAP -- Application Configuration + Access Protocol", RFC 2244, November 1997. + + [12] Resnick, P., "Internet Message Format", RFC 2822, April 2001. + + [13] Freed, N. and J. Postel, "IANA Charset Registration + Procedures", BCP 19, RFC 2978, October 2000. + + + + + +Newman, et al. Standards Track [Page 24] + +RFC 4790 Collation Registry March 2007 + + + [14] Showalter, T., "Sieve: A Mail Filtering Language", RFC 3028, + January 2001. + + [15] Crispin, M., "Internet Message Access Protocol - Version + 4rev1", RFC 3501, March 2003. + + [16] Crispin, M. and K. Murchison, "Internet Message Access Protocol + - Sort and Thread Extensions", Work in Progress, May 2004. + + [17] Newman, C. and A. Gulbrandsen, "Internet Message Access + Protocol Internationalization", Work in Progress, January 2006. + +Authors' Addresses + + Chris Newman + Sun Microsystems + 1050 Lakes Drive + West Covina, CA 91790 + USA + + EMail: chris.newman@sun.com + + + Martin Duerst + Aoyama Gakuin University + 5-10-1 Fuchinobe + Sagamihara, Kanagawa 229-8558 + Japan + + Phone: +81 42 759 6329 + Fax: +81 42 759 6495 + EMail: duerst@it.aoyama.ac.jp + URI: http://www.sw.it.aoyama.ac.jp/D%C3%BCrst/ + + Note: Please write "Duerst" with u-umlaut wherever possible, for + example as "Dürst" in XML and HTML. + + + Arnt Gulbrandsen + Oryx Mail Systems GmbH + Schweppermannstr. 8 + 81671 Munich + Germany + + Fax: +49 89 4502 9758 + EMail: arnt@oryx.com + URI: http://www.oryx.com/arnt/ + + + + +Newman, et al. Standards Track [Page 25] + +RFC 4790 Collation Registry March 2007 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2007). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + +Newman, et al. Standards Track [Page 26] + diff --git a/imap/docs/rfc/rfc4959.txt b/imap/docs/rfc/rfc4959.txt new file mode 100644 index 00000000..3df18354 --- /dev/null +++ b/imap/docs/rfc/rfc4959.txt @@ -0,0 +1,395 @@ + + + + + + +Network Working Group R. Siemborski +Request for Comments: 4959 Google, Inc. +Category: Standards Track A. Gulbrandsen + Oryx Mail Systems GmbH + September 2007 + + + IMAP Extension for Simple Authentication and Security Layer (SASL) + Initial Client Response + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + To date, the Internet Message Access Protocol (IMAP) has used a + Simple Authentication and Security Layer (SASL) profile which always + required at least one complete round trip for an authentication, as + it did not support an initial client response argument. This + additional round trip at the beginning of the session is undesirable, + especially when round-trip costs are high. + + This document defines an extension to IMAP which allows clients and + servers to avoid this round trip by allowing an initial client + response argument to the IMAP AUTHENTICATE command. + + + + + + + + + + + + + + + + + + + + + +Siemborski & Gulbrandsen Standards Track [Page 1] + +RFC 4959 IMAP Ext for SASL Initial Client Response September 2007 + + +1. Introduction + + The SASL initial client response extension is present in any IMAP + [RFC3501] server implementation which returns "SASL-IR" as one of the + supported capabilities in its CAPABILITY response. + + Servers which support this extension will accept an optional initial + client response with the AUTHENTICATE command for any SASL [RFC4422] + mechanisms which support it. + +2. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + In examples, "C:" and "S:" indicate lines sent by the client and + server, respectively. + + Formal syntax is defined by [RFC4234] as extended by [RFC3501]. + +3. IMAP Changes to the IMAP AUTHENTICATE Command + + This extension adds an optional second argument to the AUTHENTICATE + command that is defined in Section 6.2.2 of [RFC3501]. If this + second argument is present, it represents the contents of the + "initial client response" defined in Section 5.1 of [RFC4422]. + + As with any other client response, this initial client response MUST + be encoded as defined in Section 4 of [RFC4648]. It also MUST be + transmitted outside of a quoted string or literal. To send a zero- + length initial response, the client MUST send a single pad character + ("="). This indicates that the response is present, but is a zero- + length string. + + When decoding the BASE64 [RFC4648] data in the initial client + response, decoding errors MUST be treated as IMAP [RFC3501] would + handle them in any normal SASL client response. In particular, the + server should check for any characters not explicitly allowed by the + BASE64 alphabet, as well as any sequence of BASE64 characters that + contains the pad character ('=') anywhere other than the end of the + string (e.g., "=AAA" and "AAA=BBB" are not allowed). + + If the client uses an initial response with a SASL mechanism that + does not support an initial response, the server MUST reject the + command with a tagged BAD response. + + + + + +Siemborski & Gulbrandsen Standards Track [Page 2] + +RFC 4959 IMAP Ext for SASL Initial Client Response September 2007 + + + Note: support and use of the initial client response is optional for + both clients and servers. Servers that implement this extension MUST + support clients that omit the initial client response, and clients + that implement this extension MUST NOT send an initial client + response to servers that do not advertise the SASL-IR capability. In + such a situation, clients MUST fall back to an IMAP [RFC3501] + compatible mode. + + If either the client or the server do not support the SASL-IR + capability, a mechanism which uses an initial client response is + negotiated using the challenge/response exchange described in + [RFC3501], with an initial zero-length server challenge. + +4. Examples + + The following is an example authentication using the PLAIN (see + [RFC4616]) SASL mechanism (under a TLS protection layer, see + [RFC4346]) and an initial client response: + + ... client connects to server and negotiates a TLS + protection layer ... + C: C01 CAPABILITY + S: * CAPABILITY IMAP4rev1 SASL-IR AUTH=PLAIN + S: C01 OK Completed + C: A01 AUTHENTICATE PLAIN dGVzdAB0ZXN0AHRlc3Q= + S: A01 OK Success (tls protection) + + Note that even when a server supports this extension, the following + negotiation (which does not use the initial response) is still valid + and MUST be supported by the server: + + ... client connects to server and negotiates a TLS + protection layer ... + C: C01 CAPABILITY + S: * CAPABILITY IMAP4rev1 SASL-IR AUTH=PLAIN + S: C01 OK Completed + C: A01 AUTHENTICATE PLAIN + (note that there is a space following the "+" in the + following line) + S: + + C: dGVzdAB0ZXN0AHRlc3Q= + S: A01 OK Success (tls protection) + + The following is an example authentication using the SASL EXTERNAL + mechanism (defined in [RFC4422]) under a TLS protection layer (see + [RFC4346]) and an empty initial client response: + + + + + +Siemborski & Gulbrandsen Standards Track [Page 3] + +RFC 4959 IMAP Ext for SASL Initial Client Response September 2007 + + + ... client connects to server and negotiates a TLS + protection layer ... + C: C01 CAPABILITY + S: * CAPABILITY IMAP4rev1 SASL-IR AUTH=PLAIN AUTH=EXTERNAL + S: C01 OK Completed + C: A01 AUTHENTICATE EXTERNAL = + S: A01 OK Success (tls protection) + + This is in contrast with the handling of such a situation when an + initial response is omitted: + + ... client connects to server and negotiates a TLS protection + layer ... + C: C01 CAPABILITY + S: * CAPABILITY IMAP4rev1 SASL-IR AUTH=PLAIN AUTH=EXTERNAL + S: C01 OK Completed + C: A01 AUTHENTICATE EXTERNAL + (note that there is a space following the "+" in the + following line) + S: + + C: + S: A01 OK Success (tls protection) + +5. IANA Considerations + + The IANA has added SASL-IR to the IMAP4 Capabilities Registry. + +6. Security Considerations + + The extension defined in this document is subject to many of the + Security Considerations defined in [RFC3501] and [RFC4422]. + + Server implementations MUST treat the omission of an initial client + response from the AUTHENTICATE command as defined by [RFC3501] (as if + this extension did not exist). + + Although [RFC3501] has no express line length limitations, some + implementations choose to enforce them anyway. Such implementations + MUST be aware that the addition of the initial response parameter to + AUTHENTICATE may increase the maximum line length that IMAP parsers + may expect to support. Server implementations MUST be able to + receive the largest possible initial client response that their + supported mechanisms might receive. + + + + + + + + +Siemborski & Gulbrandsen Standards Track [Page 4] + +RFC 4959 IMAP Ext for SASL Initial Client Response September 2007 + + +7. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form [RFC4234] notation. [RFC3501] defines the non-terminals + capability, auth-type, and base64. + + capability =/ "SASL-IR" + + authenticate = "AUTHENTICATE" SP auth-type [SP (base64 / "=")] + *(CRLF base64) + ;;redefine AUTHENTICATE from [RFC3501] + +8. Acknowledgments + + The authors would like to acknowledge the contributions of Ken + Murchison and Mark Crispin, along with the rest of the IMAPEXT + Working Group for their assistance in reviewing this document. + + Alexey Melnikov and Cyrus Daboo also had some early discussions about + this extension. + +9. References + +9.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 4234, October 2005. + + [RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication and + Security Layer (SASL)", RFC 4422, June 2006. + + [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data + Encodings", RFC 4648, October 2006. + +9.2. Informative References + + [RFC4616] Zeilenga, K., "The PLAIN Simple Authentication and + Security Layer (SASL) Mechanism", RFC 4616, August 2006. + + [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol Version 1.1", RFC 4346, April 2006. + + + + +Siemborski & Gulbrandsen Standards Track [Page 5] + +RFC 4959 IMAP Ext for SASL Initial Client Response September 2007 + + +Authors' Addresses + + Robert Siemborski + Google, Inc. + 1600 Ampitheatre Parkway + Mountain View, CA 94043 + + Phone: +1 650 623 6925 + EMail: robsiemb@google.com + + + Arnt Gulbrandsen + Oryx Mail Systems GmbH + Schweppermannstr. 8 + D-81671 Muenchen + Germany + + EMail: arnt@oryx.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Siemborski & Gulbrandsen Standards Track [Page 6] + +RFC 4959 IMAP Ext for SASL Initial Client Response September 2007 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2007). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Siemborski & Gulbrandsen Standards Track [Page 7] + diff --git a/imap/docs/rfc/rfc4978.txt b/imap/docs/rfc/rfc4978.txt new file mode 100644 index 00000000..14b56b6e --- /dev/null +++ b/imap/docs/rfc/rfc4978.txt @@ -0,0 +1,507 @@ + + + + + + +Network Working Group A. Gulbrandsen +Request for Comments: 4978 Oryx Mail Systems GmbH +Category: Standards Track August 2007 + + + The IMAP COMPRESS Extension + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + The COMPRESS extension allows an IMAP connection to be effectively + and efficiently compressed. + + Table of Contents + + 1. Introduction and Overview .......................................2 + 2. Conventions Used in This Document ...............................2 + 3. The COMPRESS Command ............................................3 + 4. Compression Efficiency ..........................................4 + 5. Formal Syntax ...................................................6 + 6. Security Considerations .........................................6 + 7. IANA Considerations .............................................6 + 8. Acknowledgements ................................................7 + 9. References ......................................................7 + 9.1. Normative References .......................................7 + 9.2. Informative References .....................................7 + + + + + + + + + + + + + + + + + + +Gulbrandsen Standards Track [Page 1] + +RFC 4978 The IMAP COMPRESS Extension August 2007 + + +1. Introduction and Overview + + A server which supports the COMPRESS extension indicates this with + one or more capability names consisting of "COMPRESS=" followed by a + supported compression algorithm name as described in this document. + + The goal of COMPRESS is to reduce the bandwidth usage of IMAP. + + Compared to PPP compression (see [RFC1962]) and modem-based + compression (see [MNP] and [V42BIS]), COMPRESS offers much better + compression efficiency. COMPRESS can be used together with Transport + Security Layer (TLS) [RFC4346], Simple Authentication and Security + layer (SASL) encryption, Virtual Private Networks (VPNs), etc. + Compared to TLS compression [RFC3749], COMPRESS has the following + (dis)advantages: + + - COMPRESS can be implemented easily both by IMAP servers and + clients. + + - IMAP COMPRESS benefits from an intimate knowledge of the IMAP + protocol's state machine, allowing for dynamic and aggressive + optimization of the underlying compression algorithm's parameters. + + - When the TLS layer implements compression, any protocol using that + layer can transparently benefit from that compression (e.g., SMTP + and IMAP). COMPRESS is specific to IMAP. + + In order to increase interoperation, it is desirable to have as few + different compression algorithms as possible, so this document + specifies only one. The DEFLATE algorithm (defined in [RFC1951]) is + standard, widely available and fairly efficient, so it is the only + algorithm defined by this document. + + In order to increase interoperation, IMAP servers that advertise this + extension SHOULD also advertise the TLS DEFLATE compression mechanism + as defined in [RFC3749]. IMAP clients MAY use either COMPRESS or TLS + compression, however, if the client and server support both, it is + RECOMMENDED that the client choose TLS compression. + + The extension adds one new command (COMPRESS) and no new responses. + +2. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + Formal syntax is defined by [RFC4234] as modified by [RFC3501]. + + + +Gulbrandsen Standards Track [Page 2] + +RFC 4978 The IMAP COMPRESS Extension August 2007 + + + In the examples, "C:" and "S:" indicate lines sent by the client and + server respectively. "[...]" denotes elision. + +3. The COMPRESS Command + + Arguments: Name of compression mechanism: "DEFLATE". + + Responses: None + + Result: OK The server will compress its responses and expects the + client to compress its commands. + NO Compression is already active via another layer. + BAD Command unknown, invalid or unknown argument, or COMPRESS + already active. + + The COMPRESS command instructs the server to use the named + compression mechanism ("DEFLATE" is the only one defined) for all + commands and/or responses after COMPRESS. + + The client MUST NOT send any further commands until it has seen the + result of COMPRESS. If the response was OK, the client MUST compress + starting with the first command after COMPRESS. If the server + response was BAD or NO, the client MUST NOT turn on compression. + + If the server responds NO because it knows that the same mechanism is + active already (e.g., because TLS has negotiated the same mechanism), + it MUST send COMPRESSIONACTIVE as resp-text-code (see [RFC3501], + Section 7.1), and the resp-text SHOULD say which layer compresses. + + If the server issues an OK response, the server MUST compress + starting immediately after the CRLF which ends the tagged OK + response. (Responses issued by the server before the OK response + will, of course, still be uncompressed.) If the server issues a BAD + or NO response, the server MUST NOT turn on compression. + + For DEFLATE (as for many other compression mechanisms), the + compressor can trade speed against quality. When decompressing there + isn't much of a tradeoff. Consequently, the client and server are + both free to pick the best reasonable rate of compression for the + data they send. + + When COMPRESS is combined with TLS (see [RFC4346]) or SASL (see + [RFC4422]) security layers, the sending order of the three extensions + MUST be first COMPRESS, then SASL, and finally TLS. That is, before + data is transmitted it is first compressed. Second, if a SASL + security layer has been negotiated, the compressed data is then + signed and/or encrypted accordingly. Third, if a TLS security layer + has been negotiated, the data from the previous step is signed and/or + + + +Gulbrandsen Standards Track [Page 3] + +RFC 4978 The IMAP COMPRESS Extension August 2007 + + + encrypted accordingly. When receiving data, the processing order + MUST be reversed. This ensures that before sending, data is + compressed before it is encrypted, independent of the order in which + the client issues COMPRESS, AUTHENTICATE, and STARTTLS. + + The following example illustrates how commands and responses are + compressed during a simple login sequence: + + S: * OK [CAPABILITY IMAP4REV1 STARTTLS COMPRESS=DEFLATE] + C: a starttls + S: a OK TLS active + + From this point on, everything is encrypted. + + C: b login arnt tnra + S: b OK Logged in as arnt + C: c compress deflate + S: d OK DEFLATE active + + From this point on, everything is compressed before being + encrypted. + + The following example demonstrates how a server may refuse to + compress twice: + + S: * OK [CAPABILITY IMAP4REV1 STARTTLS COMPRESS=DEFLATE] + [...] + C: c compress deflate + S: c NO [COMPRESSIONACTIVE] DEFLATE active via TLS + +4. Compression Efficiency + + This section is informative, not normative. + + IMAP poses some unusual problems for a compression layer. + + Upstream is fairly simple. Most IMAP clients send the same few + commands again and again, so any compression algorithm that can + exploit repetition works efficiently. The APPEND command is an + exception; clients that send many APPEND commands may want to + surround large literals with flushes in the same way as is + recommended for servers later in this section. + + Downstream has the unusual property that several kinds of data are + sent, confusing all dictionary-based compression algorithms. + + + + + + +Gulbrandsen Standards Track [Page 4] + +RFC 4978 The IMAP COMPRESS Extension August 2007 + + + One type is IMAP responses. These are highly compressible; zlib + using its least CPU-intensive setting compresses typical responses to + 25-40% of their original size. + + Another type is email headers. These are equally compressible, and + benefit from using the same dictionary as the IMAP responses. + + A third type is email body text. Text is usually fairly short and + includes much ASCII, so the same compression dictionary will do a + good job here, too. When multiple messages in the same thread are + read at the same time, quoted lines etc. can often be compressed + almost to zero. + + Finally, attachments (non-text email bodies) are transmitted, either + in binary form or encoded with base-64. + + When attachments are retrieved in binary form, DEFLATE may be able to + compress them, but the format of the attachment is usually not IMAP- + like, so the dictionary built while compressing IMAP does not help. + The compressor has to adapt its dictionary from IMAP to the + attachment's format, and then back. A few file formats aren't + compressible at all using deflate, e.g., .gz, .zip, and .jpg files. + + When attachments are retrieved in base-64 form, the same problems + apply, but the base-64 encoding adds another problem. 8-bit + compression algorithms such as deflate work well on 8-bit file + formats, however base-64 turns a file into something resembling 6-bit + bytes, hiding most of the 8-bit file format from the compressor. + + When using the zlib library (see [RFC1951]), the functions + deflateInit2(), deflate(), inflateInit2(), and inflate() suffice to + implement this extension. The windowBits value must be in the range + -8 to -15, or else deflateInit2() uses the wrong format. + deflateParams() can be used to improve compression rate and resource + use. The Z_FULL_FLUSH argument to deflate() can be used to clear the + dictionary (the receiving peer does not need to do anything). + + A client can improve downstream compression by implementing BINARY + (defined in [RFC3516]) and using FETCH BINARY instead of FETCH BODY. + In the author's experience, the improvement ranges from 5% to 40% + depending on the attachment being downloaded. + + A server can improve downstream compression if it hints to the + compressor that the data type is about to change strongly, e.g., by + sending a Z_FULL_FLUSH at the start and end of large non-text + literals (before and after '*CHAR8' in the definition of literal in + RFC 3501, page 86). Small literals are best left alone. A possible + boundary is 5k. + + + +Gulbrandsen Standards Track [Page 5] + +RFC 4978 The IMAP COMPRESS Extension August 2007 + + + A server can improve the CPU efficiency both of the server and the + client if it adjusts the compression level (e.g., using the + deflateParams() function in zlib) at these points, to avoid trying to + compress incompressible attachments. A very simple strategy is to + change the level to 0 at the start of a literal provided the first + two bytes are either 0x1F 0x8B (as in deflate-compressed files) or + 0xFF 0xD8 (JPEG), and to keep it at 1-5 the rest of the time. More + complex strategies are possible. + +5. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [RFC4234]. This syntax augments + the grammar specified in [RFC3501]. [RFC4234] defines SP and + [RFC3501] defines command-auth, capability, and resp-text-code. + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of upper or lower case characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. + + command-auth =/ compress + + compress = "COMPRESS" SP algorithm + + capability =/ "COMPRESS=" algorithm + ;; multiple COMPRESS capabilities allowed + + algorithm = "DEFLATE" + + resp-text-code =/ "COMPRESSIONACTIVE" + + Note that due the syntax of capability names, future algorithm names + must be atoms. + +6. Security Considerations + + As for TLS compression [RFC3749]. + +7. IANA Considerations + + The IANA has added COMPRESS=DEFLATE to the list of IMAP capabilities. + + + + + + + + + +Gulbrandsen Standards Track [Page 6] + +RFC 4978 The IMAP COMPRESS Extension August 2007 + + +8. Acknowledgements + + Eric Burger, Dave Cridland, Tony Finch, Ned Freed, Philip Guenther, + Randall Gellens, Tony Hansen, Cullen Jennings, Stephane Maes, Alexey + Melnikov, Lyndon Nerenberg, and Zoltan Ordogh have all helped with + this document. + + The author would also like to thank various people in the rooms at + meetings, whose help is real, but not reflected in the author's + mailbox. + +9. References + +9.1. Normative References + + [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification + version 1.3", RFC 1951, May 1996. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 4234, October 2005. + +9.2. Informative References + + [RFC1962] Rand, D., "The PPP Compression Control Protocol (CCP)", + RFC 1962, June 1996. + + [RFC3516] Nerenberg, L., "IMAP4 Binary Content Extension", RFC 3516, + April 2003. + + [RFC3749] Hollenbeck, S., "Transport Layer Security Protocol + Compression Methods", RFC 3749, May 2004. + + [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol Version 1.1", RFC 4346, April 2006. + + [RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication and + Security Layer (SASL)", RFC 4422, June 2006. + + [V42BIS] ITU, "V.42bis: Data compression procedures for data + circuit-terminating equipment (DCE) using error correction + procedures", http://www.itu.int/rec/T-REC-V.42bis, January + 1990. + + + +Gulbrandsen Standards Track [Page 7] + +RFC 4978 The IMAP COMPRESS Extension August 2007 + + + [MNP] Gilbert Held, "The Complete Modem Reference", Second + Edition, Wiley Professional Computing, ISBN 0-471-00852-4, + May 1994. + +Author's Address + + Arnt Gulbrandsen + Oryx Mail Systems GmbH + Schweppermannstr. 8 + D-81671 Muenchen + Germany + + Fax: +49 89 4502 9758 + EMail: arnt@oryx.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Gulbrandsen Standards Track [Page 8] + +RFC 4978 The IMAP COMPRESS Extension August 2007 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2007). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Gulbrandsen Standards Track [Page 9] + diff --git a/imap/docs/rfc/rfc5032.txt b/imap/docs/rfc/rfc5032.txt new file mode 100644 index 00000000..f8e48953 --- /dev/null +++ b/imap/docs/rfc/rfc5032.txt @@ -0,0 +1,283 @@ + + + + + + +Network Working Group E. Burger, Ed. +Request for Comments: 5032 BEA Systems, Inc. +Updates: 3501 September 2007 +Category: Standards Track + + + WITHIN Search Extension to the IMAP Protocol + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + This document describes the WITHIN extension to IMAP SEARCH. IMAP + SEARCH returns messages whose internal date is within or outside a + specified interval. The mechanism described here, OLDER and YOUNGER, + differs from BEFORE and SINCE in that the client specifies an + interval, rather than a date. WITHIN is useful for persistent + searches where either the device does not have the capacity to + perform the search at regular intervals or the network is of limited + bandwidth and thus there is a desire to reduce network traffic from + sending repeated requests and redundant responses. + +1. Introduction + + This extension exposes two new search keys, OLDER and YOUNGER, each + of which takes a non-zero integer argument corresponding to a time + interval in seconds. The server calculates the time of interest by + subtracting the time interval the client presents from the current + date and time of the server. The server then either returns messages + older or younger than the resultant time and date, depending on the + search key used. + +1.1. Conventions Used in This Document + + In examples, "C:" and "S:" indicate lines sent by the client and + server, respectively. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [RFC2119]. + + + + + +Burger Standards Track [Page 1] + +RFC 5032 Search Within September 2007 + + + When describing the general syntax, we omit some definitions, as RFC + 3501 [RFC3501] defines them. + +2. Protocol Operation + + An IMAP4 server that supports the capability described here MUST + return "WITHIN" as one of the server supported capabilities in the + CAPABILITY command. + + For both the OLDER and YOUNGER search keys, the server calculates a + target date and time by subtracting the interval, specified in + seconds, from the current date and time of the server. The server + then compares the target time with the INTERNALDATE of the message, + as specified in IMAP [RFC3501]. For OLDER, messages match if the + INTERNALDATE is less recent than or equal to the target time. For + YOUNGER, messages match if the INTERNALDATE is more recent than or + equal to the target time. + + Both OLDER and YOUNGER searches always result in exact matching, to + the resolution of a second. However, if one is doing a dynamic + evaluation, for example, in a context [CONTEXT], one needs to be + aware that the server might perform the evaluation periodically. + Thus, the server may delay the updates. Clients MUST be aware that + dynamic search results may not reflect the current state of the + mailbox. If the client needs a search result that reflects the + current state of the mailbox, we RECOMMEND that the client issue a + new search. + +3. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation. Elements not defined here can be found in the + formal syntax of ABNF [RFC4234] and IMAP [RFC3501]. + + This document extends RFC 3501 [RFC3501] with two new search keys: + OLDER <interval> and YOUNGER <interval>. + + search-key =/ ( "OLDER" / "YOUNGER" ) SP nz-number + ; search-key defined in RFC 3501 + +4. Example + + C: a1 SEARCH UNSEEN YOUNGER 259200 + S: a1 * SEARCH 4 8 15 16 23 42 + + Search for all unseen messages within the past 3 days, or 259200 + seconds, according to the server's current time. + + + + +Burger Standards Track [Page 2] + +RFC 5032 Search Within September 2007 + + +5. Security Considerations + + The WITHIN extension does not raise any security considerations that + are not present in the base protocol. Considerations are the same as + for IMAP [RFC3501]. + +6. IANA Considerations + + Per the IMAP RFC [RFC3501], registration of a new IMAP capability in + the IMAP Capability registry requires the publication of a standards- + track RFC or an IESG approved experimental RFC. The registry is + currently located at + <http://www.iana.org/assignments/imap4-capabilities>. This + standards-track document defines the WITHIN IMAP capability. IANA + has added this extension to the IANA IMAP Capability registry. + +7. References + +7.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", RFC 2119, BCP 14, March 1997. + + [RFC3501] Crispin, M., "Internet Message Access Protocol - Version + 4rev1", RFC 3501, March 2003. + + [RFC4234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", RFC 4234, October 2005. + +7.2. Informative References + + [CONTEXT] Melnikov, D. and C. King, "Contexts for IMAP4", Work + in Progress, May 2006. + + + + + + + + + + + + + + + + + + +Burger Standards Track [Page 3] + +RFC 5032 Search Within September 2007 + + +Appendix A. Contributors + + Stephane Maes and Ray Cromwell wrote the original version of this + document as part of P-IMAP, as well as the first versions for the + IETF. From an attribution perspective, they are clearly authors. + +Appendix B. Acknowledgements + + The authors want to thank all who have contributed key insight and + who have extensively reviewed and discussed the concepts of LPSEARCH. + They also thank the authors of its early introduction in P-IMAP. + + We also want to give a special thanks to Arnt Gilbrandsen, Ken + Murchison, Zoltan Ordogh, and most especially Dave Cridland for their + review and suggestions. A special thank you goes to Alexey Melnikov + for his choice submission of text. + +Author's Address + + Eric W. Burger (editor) + BEA Systems, Inc. + USA + + EMail: eric.burger@bea.com + URI: http://www.standardstrack.com + + + + + + + + + + + + + + + + + + + + + + + + + + +Burger Standards Track [Page 4] + +RFC 5032 Search Within September 2007 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2007). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Burger Standards Track [Page 5] + diff --git a/imap/docs/rfc/rfc5051.txt b/imap/docs/rfc/rfc5051.txt new file mode 100644 index 00000000..0a4479ca --- /dev/null +++ b/imap/docs/rfc/rfc5051.txt @@ -0,0 +1,395 @@ + + + + + + +Network Working Group M. Crispin +Request for Comments: 5051 University of Washington +Category: Standards Track October 2007 + + + i;unicode-casemap - Simple Unicode Collation Algorithm + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + This document describes "i;unicode-casemap", a simple case- + insensitive collation for Unicode strings. It provides equality, + substring, and ordering operations. + +1. Introduction + + The "i;ascii-casemap" collation described in [COMPARATOR] is quite + simple to implement and provides case-independent comparisons for the + 26 Latin alphabetics. It is specified as the default and/or baseline + comparator in some application protocols, e.g., [IMAP-SORT]. + + However, the "i;ascii-casemap" collation does not produce + satisfactory results with non-ASCII characters. It is possible, with + a modest extension, to provide a more sophisticated collation with + greater multilingual applicability than "i;ascii-casemap". This + extension provides case-independent comparisons for a much greater + number of characters. It also collates characters with diacriticals + with the non-diacritical character forms. + + This collation, "i;unicode-casemap", is intended to be an alternative + to, and preferred over, "i;ascii-casemap". It does not replace the + "i;basic" collation described in [BASIC]. + +2. Unicode Casemap Collation Description + + The "i;unicode-casemap" collation is a simple collation which is + case-insensitive in its treatment of characters. It provides + equality, substring, and ordering operations. The validity test + operation returns "valid" for any input. + + + + + +Crispin Standards Track [Page 1] + +RFC 5051 i;unicode-casemap October 2007 + + + This collation allows strings in arbitrary (and mixed) character + sets, as long as the character set for each string is identified and + it is possible to convert the string to Unicode. Strings which have + an unidentified character set and/or cannot be converted to Unicode + are not rejected, but are treated as binary. + + Each input string is prepared by converting it to a "titlecased + canonicalized UTF-8" string according to the following steps, using + UnicodeData.txt ([UNICODE-DATA]): + + (1) A Unicode codepoint is obtained from the input string. + + (a) If the input string is in a known charset that can be + converted to Unicode, a sequence in the string's charset + is read and checked for validity according to the rules of + that charset. If the sequence is valid, it is converted + to a Unicode codepoint. Note that for input strings in + UTF-8, the UTF-8 sequence must be valid according to the + rules of [UTF-8]; e.g., overlong UTF-8 sequences are + invalid. + + (b) If the input string is in an unknown charset, or an + invalid sequence occurs in step (1)(a), conversion ceases. + No further preparation is performed, and any partial + preparation results are discarded. The original string is + used unchanged with the i;octet comparator. + + (2) The following steps, using UnicodeData.txt ([UNICODE-DATA]), + are performed on the resulting codepoint from step (1)(a). + + (a) If the codepoint has a titlecase property in + UnicodeData.txt (this is normally the same as the + uppercase property), the codepoint is converted to the + codepoints in the titlecase property. + + (b) If the resulting codepoint from (2)(a) has a decomposition + property of any type in UnicodeData.txt, the codepoint is + converted to the codepoints in the decomposition property. + This step is recursively applied to each of the resulting + codepoints until no more decomposition is possible + (effectively Normalization Form KD). + + Example: codepoint U+01C4 (LATIN CAPITAL LETTER DZ WITH CARON) + has a titlecase property of U+01C5 (LATIN CAPITAL LETTER D + WITH SMALL LETTER Z WITH CARON). Codepoint U+01C5 has a + decomposition property of U+0044 (LATIN CAPITAL LETTER D) + U+017E (LATIN SMALL LETTER Z WITH CARON). U+017E has a + decomposition property of U+007A (LATIN SMALL LETTER Z) U+030c + + + +Crispin Standards Track [Page 2] + +RFC 5051 i;unicode-casemap October 2007 + + + (COMBINING CARON). Neither U+0044, U+007A, nor U+030C have + any decomposition properties. Therefore, U+01C4 is converted + to U+0044 U+007A U+030C by this step. + + (3) The resulting codepoint(s) from step (2) is/are appended, in + UTF-8 format, to the "titlecased canonicalized UTF-8" string. + + (4) Repeat from step (1) until there is no more data in the input + string. + + Following the above preparation process on each string, the equality, + ordering, and substring operations are as for i;octet. + + It is permitted to use an alternative implementation of the above + preparation process if it produces the same results. For example, it + may be more convenient for an implementation to convert all input + strings to a sequence of UTF-16 or UTF-32 values prior to performing + any of the step (2) actions. Similarly, if all input strings are (or + are convertible to) Unicode, it may be possible to use UTF-32 as an + alternative to UTF-8 in step (3). + + Note: UTF-16 is unsuitable as an alternative to UTF-8 in step (3), + because UTF-16 surrogates will cause i;octet to collate codepoints + U+E0000 through U+FFFF after non-BMP codepoints. + + This collation is not locale sensitive. Consequently, care should be + taken when using OS-supplied functions to implement this collation. + Functions such as strcasecmp and toupper are sometimes locale + sensitive and may inconsistently casemap letters. + + The i;unicode-casemap collation is well suited to use with many + Internet protocols and computer languages. Use with natural language + is often inappropriate; even though the collation apparently supports + languages such as Swahili and English, in real-world use it tends to + mis-sort a number of types of string: + + o people and place names containing scripts that are not collated + according to "alphabetical order". + o words with characters that have diacriticals. However, + i;unicode-casemap generally does a better job than i;ascii-casemap + for most (but not all) languages. For example, German umlaut + letters will sort correctly, but some Scandinavian letters will + not. + o names such as "Lloyd" (which in Welsh sorts after "Lyon", unlike + in English), + o strings containing other non-letter symbols; e.g., euro and pound + sterling symbols, quotation marks other than '"', dashes/hyphens, + etc. + + + +Crispin Standards Track [Page 3] + +RFC 5051 i;unicode-casemap October 2007 + + +3. Unicode Casemap Collation Registration + + <?xml version='1.0'?> + <!DOCTYPE collation SYSTEM 'collationreg.dtd'> + <collation rfc="5051" scope="global" intendedUse="common"> + <identifier>i;unicode-casemap</identifier> + <title>Unicode Casemap</title> + <operations>equality order substring</operations> + <specification>RFC 5051</specification> + <owner>IETF</owner> + <submitter>mrc@cac.washington.edu</submitter> + </collation> + +4. Security Considerations + + The security considerations for [UTF-8], [STRINGPREP], and [UNICODE- + SECURITY] apply and are normative to this specification. + + The results from this comparator will vary depending upon the + implementation for several reasons. Implementations MUST consider + whether these possibilities are a problem for their use case: + + 1) New characters added in Unicode may have decomposition or + titlecase properties that will not be known to an implementation + based upon an older revision of Unicode. This impacts step (2). + + 2) Step (2)(b) defines a subset of Normalization Form KD (NFKD) that + does not require normalization of out-of-order diacriticals. + However, an implementation MAY use an NFKD library routine that + does such normalization. This impacts step (2)(b) and possibly + also step (1)(a), and is an issue only with ill-formed UTF-8 + input. + + 3) The set of charsets handled in step (1)(a) is open-ended. UTF-8 + (and, by extension, US-ASCII) are the only mandatory-to-implement + charsets. This impacts step (1)(a). + + Implementations SHOULD, as far as feasible, support all the + charsets they are likely to encounter in the input data, in order + to avoid poor collation caused by the fall through to the (1)(b) + rule. + + 4) Other charsets may have revisions which add new characters that + are not known to an implementation based upon an older revision. + This impacts step (1)(a) and possibly also step (1)(b). + + + + + + +Crispin Standards Track [Page 4] + +RFC 5051 i;unicode-casemap October 2007 + + + An attacker may create input that is ill-formed or in an unknown + charset, with the intention of impacting the results of this + comparator or exploiting other parts of the system which process this + input in different ways. Note, however, that even well-formed data + in a known charset can impact the result of this comparator in + unexpected ways. For example, an attacker can substitute U+0041 + (LATIN CAPITAL LETTER A) with U+0391 (GREEK CAPITAL LETTER ALPHA) or + U+0410 (CYRILLIC CAPITAL LETTER A) in the intention of causing a + non-match of strings which visually appear the same and/or causing + the string to appear elsewhere in a sort. + +5. IANA Considerations + + The i;unicode-casemap collation defined in section 2 has been added + to the registry of collations defined in [COMPARATOR]. + +6. Normative References + + [COMPARATOR] Newman, C., Duerst, M., and A. Gulbrandsen, + "Internet Application Protocol Collation + Registry", RFC 4790, February 2007. + + [STRINGPREP] Hoffman, P. and M. Blanchet, "Preparation of + Internationalized Strings ("stringprep")", RFC + 3454, December 2002. + + [UTF-8] Yergeau, F., "UTF-8, a transformation format of + ISO 10646", STD 63, RFC 3629, November 2003. + + [UNICODE-DATA] <http://www.unicode.org/Public/UNIDATA/ + UnicodeData.txt> + + Although the UnicodeData.txt file referenced + here is part of the Unicode standard, it is + subject to change as new characters are added + to Unicode and errors are corrected in Unicode + revisions. As a result, it may be less stable + than might otherwise be implied by the + standards status of this specification. + + [UNICODE-SECURITY] Davis, M. and M. Suignard, "Unicode Security + Considerations", February 2006, + <http://www.unicode.org/reports/tr36/>. + + + + + + + + +Crispin Standards Track [Page 5] + +RFC 5051 i;unicode-casemap October 2007 + + +7. Informative References + + [BASIC] Newman, C., Duerst, M., and A. Gulbrandsen, + "i;basic - the Unicode Collation Algorithm", + Work in Progress, March 2007. + + [IMAP-SORT] Crispin, M. and K. Murchison, "Internet Message + Access Protocol - SORT and THREAD Extensions", + Work in Progress, September 2007. + +Author's Address + + Mark R. Crispin + Networks and Distributed Computing + University of Washington + 4545 15th Avenue NE + Seattle, WA 98105-4527 + + Phone: +1 (206) 543-5762 + EMail: MRC@CAC.Washington.EDU + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Crispin Standards Track [Page 6] + +RFC 5051 i;unicode-casemap October 2007 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2007). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Crispin Standards Track [Page 7] + diff --git a/imap/docs/rfc/rfc5092.txt b/imap/docs/rfc/rfc5092.txt new file mode 100644 index 00000000..ab87f350 --- /dev/null +++ b/imap/docs/rfc/rfc5092.txt @@ -0,0 +1,1795 @@ + + + + + + +Network Working Group A. Melnikov, Ed. +Request for Comments: 5092 Isode Ltd. +Obsoletes: 2192 C. Newman +Updates: 4467 Sun Microsystems +Category: Standards Track November 2007 + + + IMAP URL Scheme + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + IMAP (RFC 3501) is a rich protocol for accessing remote message + stores. It provides an ideal mechanism for accessing public mailing + list archives as well as private and shared message stores. This + document defines a URL scheme for referencing objects on an IMAP + server. + + This document obsoletes RFC 2192. It also updates RFC 4467. + + + + + + + + + + + + + + + + + + + + + + + + + +Melnikov & Newman Standards Track [Page 1] + +RFC 5092 IMAP URL Scheme November 2007 + + +Table of Contents + + 1. Introduction ....................................................2 + 2. Conventions Used in This Document ...............................3 + 3. IMAP userinfo Component (iuserinfo) .............................4 + 3.1. IMAP Mailbox Naming Scope ..................................4 + 3.2. IMAP User Name and Authentication Mechanism ................4 + 3.3. Limitations of enc-user ....................................6 + 4. IMAP Server .....................................................7 + 5. Lists of Messages ...............................................7 + 6. A Specific Message or Message Part ..............................8 + 6.1. URLAUTH Authorized URL .....................................9 + 6.1.1. Concepts ............................................9 + 6.1.1.1. URLAUTH ....................................9 + 6.1.1.2. Mailbox Access Key .........................9 + 6.1.1.3. Authorized Access Identifier ...............9 + 6.1.1.4. Authorization Mechanism ...................10 + 6.1.1.5. Authorization Token .......................10 + 6.1.2. URLAUTH Extensions to IMAP URL .....................10 + 7. Relative IMAP URLs .............................................11 + 7.1. absolute-path References ..................................12 + 7.2. relative-path References ..................................12 + 8. Internationalization Considerations ............................13 + 9. Examples .......................................................13 + 9.1. Examples of Relative URLs .................................16 + 10. Security Considerations .......................................16 + 10.1. Security Considerations Specific to URLAUTH Authorized + URL ......................................................17 + 11. ABNF for IMAP URL Scheme ......................................17 + 12. IANA Considerations ...........................................21 + 12.1. IANA Registration of imap: URI Scheme ....................21 + 13. References ....................................................22 + 13.1. Normative References .....................................22 + 13.2. Informative References ...................................23 + Appendix A. Sample Code............................................24 + Appendix B. List of Changes since RFC 2192.........................30 + Appendix C. List of Changes since RFC 4467.........................31 + Appendix D. Acknowledgments........................................31 + +1. Introduction + + The IMAP URL scheme is used to designate IMAP servers, mailboxes, + messages, MIME bodies [MIME], and search programs on Internet hosts + accessible using the IMAP protocol over TCP. + + The IMAP URL follows the common Internet scheme syntax as defined in + [URI-GEN]. If :<port> is omitted, the port defaults to 143 (as + defined in Section 2.1 of [IMAP4]). + + + +Melnikov & Newman Standards Track [Page 2] + +RFC 5092 IMAP URL Scheme November 2007 + + + An absolute IMAP URL takes one of the following forms: + + imap://<iserver>[/] + + imap://<iserver>/<enc-mailbox>[<uidvalidity>][?<enc-search>] + + imap://<iserver>/<enc-mailbox>[<uidvalidity>]<iuid> + [<isection>][<ipartial>][<iurlauth>] + + The first form is used to refer to an IMAP server (see Section 4), + the second form refers to the contents of a mailbox or a set of + messages resulting from a search (see Section 5), and the final form + refers to a specific message or message part, and possibly a byte + range in that part (see Section 6). If [URLAUTH] extension is + supported, then the final form can have the <iurlauth> component (see + Section 6.1 for more details). + + The <iserver> component common to all types of absolute IMAP URLs has + the following syntax expressed in ABNF [ABNF]: + + [iuserinfo "@"] host [ ":" port ] + + The <iserver> component is the same as "authority" defined in + [URI-GEN]. The syntax and uses of the <iuserinfo> ("IMAP userinfo + component") are described in detail in Section 3. The syntax of + <host> and <port> is described in [URI-GEN]. + +2. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [KEYWORDS]. + + This document references many productions from [URI-GEN]. When the + document needs to emphasize IMAP URI-specific differences from [URI- + GEN] (i.e., for parts of IMAP URIs that have more restricted syntax + than generic URIs), it uses a non-terminal i<foo> to define an IMAP- + specific version of the non-terminal <foo> from [URI-GEN]. + + Note that the ABNF syntax shown in Section 11 is normative. Sections + 2-6 may use a less formal syntax that does not necessarily match the + normative ABNF shown in Section 11. If there are any differences + between the syntax shown in Sections 2-6 and Section 11, then the + syntax shown in Section 11 must be treated as authoritative. Non- + syntax requirements included in Sections 2-6 are, of course, + normative. + + + + + +Melnikov & Newman Standards Track [Page 3] + +RFC 5092 IMAP URL Scheme November 2007 + + +3. IMAP userinfo Component (iuserinfo) + + The <iuserinfo> component conforms to the generic syntax of + <userinfo> defined in [URI-GEN]. It has the following syntax + expressed in ABNF [ABNF]: + + enc-user [iauth] / [enc-user] iauth + + The meaning of the different parts is described in subsections of + this section. + +3.1. IMAP Mailbox Naming Scope + + The "enc-user" part of the "iuserinfo" component, if present, denotes + mailbox naming scope. If it is absent, the IMAP URL can only + reference mailboxes with globally unique names, i.e., mailboxes with + names that don't change depending on the user the client + authenticated as to the IMAP server. Note that not all IMAP + implementations support globally unique names. + + For example, a personal mailbox described by the following URL + <imap://michael@example.org/INBOX> is most likely different from a + personal mailbox described by <imap://bester@example.org/INBOX>, even + though both URLs use the same mailbox name. + +3.2. IMAP User Name and Authentication Mechanism + + The userinfo component (see [URI-GEN]) of an IMAP URI may contain an + IMAP user name (a.k.a. authorization identity [SASL], "enc-user") + and/or an authentication mechanism. (Note that the "enc-user" also + defines a mailbox naming scope as described in Section 3.1). The + IMAP user name and the authentication mechanism are used in the + "LOGIN" or "AUTHENTICATE" commands after making the connection to the + IMAP server. + + If no user name and no authentication mechanism are supplied, the + client MUST authenticate as anonymous to the server. If the server + advertises AUTH=ANONYMOUS IMAP capability, the client MUST use the + AUTHENTICATE command with ANONYMOUS [ANONYMOUS] SASL mechanism. If + SASL ANONYMOUS is not available, the (case-insensitive) user name + "anonymous" is used with the "LOGIN" command and the Internet email + address of the end user accessing the resource is supplied as the + password. The latter option is given in order to provide for + interoperability with deployed servers. + + Note that, as described in RFC 3501, the "LOGIN" command MUST NOT be + used when the IMAP server advertises the LOGINDISABLED capability. + + + + +Melnikov & Newman Standards Track [Page 4] + +RFC 5092 IMAP URL Scheme November 2007 + + + An authentication mechanism (as used by the IMAP AUTHENTICATE + command) can be expressed by adding ";AUTH=<enc-auth-type>" to the + end of the user name in an IMAP URL. When such an <enc-auth-type> is + indicated, the client SHOULD request appropriate credentials from + that mechanism and use the "AUTHENTICATE" command instead of the + "LOGIN" command. If no user name is specified, one MUST be obtained + from the mechanism or requested from the user/configuration as + appropriate. + + The string ";AUTH=*" indicates that the client SHOULD select an + appropriate authentication mechanism. (Though the '*' character in + this usage is not strictly a delimiter, it is being treated like a + sub-delim [URI-GEN] in this instance. It MUST NOT be percent-encoded + in this usage, as ";AUTH=%2A" will not match this production.) It + MAY use any mechanism listed in the response to the CAPABILITY + command (or CAPABILITY response code) or use an out-of-band security + service resulting in a PREAUTH connection. If no user name is + specified and no appropriate authentication mechanisms are available, + the client SHOULD fall back to anonymous login as described above. + The behavior prescribed in this section allows a URL that grants + read-write access to authorized users and read-only anonymous access + to other users. + + If a user name is included with no authentication mechanism, then + ";AUTH=*" is assumed. + + Clients must take care when resolving a URL that requires or requests + any sort of authentication, since URLs can easily come from untrusted + sources. Supplying authentication credentials to the wrong server + may compromise the security of the user's account; therefore, the + program resolving the URL should meet at least one of the following + criteria in this case: + + 1) The URL comes from a trusted source, such as a referral server + that the client has validated and trusts according to site policy. + Note that user entry of the URL may or may not count as a trusted + source, depending on the experience level of the user and site + policy. + + 2) Explicit local site policy permits the client to connect to the + server in the URL. For example, a company example.com may have a + site policy to trust all IMAP server names ending in example.com, + whereas such a policy would be unwise for example.edu where random + students can set up IMAP servers. + + 3) The user confirms that connecting to that domain name with the + specified credentials and/or mechanism is permitted. For example, + when using "LOGIN" or SASL PLAIN with Transport Layer Security + + + +Melnikov & Newman Standards Track [Page 5] + +RFC 5092 IMAP URL Scheme November 2007 + + + (TLS), the IMAP URL client presents a dialog box "Is it OK to send + your password to server "example.com"? Please be aware the owners + of example.com will be able to reuse your password to connect to + other servers on your behalf". + + 4) A mechanism is used that validates the server before passing + potentially compromising client credentials. For example, a site + has a designated TLS certificate used to certify site-trusted IMAP + server certificates, and this has been configured explicitly into + the IMAP URL client. Another example is use of a Simple + Authentication and Security Layer (SASL) mechanism such as + DIGEST-MD5 [DIGEST-MD5], which supports mutual authentication. + + 5) An authentication mechanism is used that will not reveal any + information to the server that could be used to compromise future + connections. Examples are SASL ANONYMOUS [ANONYMOUS] or GSSAPI + [GSSAPI]. + + URLs that do not include a user name but include an authentication + mechanism (";AUTH=<mech>") must be treated with extra care, since for + some <mech>s they are more likely to compromise the user's primary + account. A URL containing ";AUTH=*" must also be treated with extra + care since it might fall back on a weaker security mechanism. + Finally, clients are discouraged from using a plaintext password as a + fallback with ";AUTH=*" unless the connection has strong encryption. + + A program interpreting IMAP URLs MAY cache open connections to an + IMAP server for later reuse. If a URL contains a user name, only + connections authenticated as that user may be reused. If a URL does + not contain a user name or authentication mechanism, then only an + anonymous connection may be reused. + + Note that if unsafe or reserved characters such as " " (space) or ";" + are present in the user name or authentication mechanism, they MUST + be percent-encoded as described in [URI-GEN]. + +3.3. Limitations of enc-user + + As per Sections 3.1 and 3.2 of this document, the IMAP URI enc-user + has two purposes: + + 1) It provides context for user-specific mailbox paths such as + "INBOX" (Section 3.1). + + 2) It specifies that resolution of the URL requires logging in as + that user and limits use of that URL to only that user (Section + 3.2). + + + + +Melnikov & Newman Standards Track [Page 6] + +RFC 5092 IMAP URL Scheme November 2007 + + + An obvious limitation of using the same field for both purposes is + that the URL can be resolved only by the mailbox owner. In order to + avoid this restriction, implementations should use globally unique + mailbox names (see Section 3.1) whenever possible. + + Note: There is currently no general way in IMAP of learning a + globally unique name for a mailbox. However, by looking at the + NAMESPACE [NAMESPACE] command result, it is possible to determine + whether or not a mailbox name is globally unique. + + The URLAUTH component overrides the second purpose of the enc-user in + the IMAP URI and by default permits the URI to be resolved by any + user permitted by the <access> identifier. URLAUTH and <access> + identifier are described in Section 6.1. + +4. IMAP Server + + An IMAP URL referring to an IMAP server has the following form: + + imap://<iserver>[/] + + This URL type is frequently used to describe a location of an IMAP + server, both in referrals and in configuration. It may optionally + contain the <iuserinfo> component (see Sections 3 and 11). A program + interpreting this URL would issue the standard set of commands it + uses to present a view of the content of the IMAP server, as visible + to the user described by the "enc-user" part of the <iuserinfo> + component, if the "enc-user" part is specified. + +5. Lists of Messages + + An IMAP URL referring to a list of messages has the following form: + + imap://<iserver>/<enc-mailbox>[<uidvalidity>][?<enc-search>] + + The <enc-mailbox> field is used as the argument to the IMAP4 "SELECT" + or "EXAMINE" command. Note that if unsafe or reserved characters + such as " " (space), ";", or "?" are present in <enc-mailbox>, they + MUST be percent-encoded as described in [URI-GEN]. + + The <uidvalidity> field is optional. If it is present, it MUST be + the same as the value of IMAP4 UIDVALIDITY response code at the time + the URL was created. This MUST be used by the program interpreting + the IMAP URL to determine if the URL is stale. If the IMAP URL is + stale, then the program should behave as if the corresponding mailbox + doesn't exist. + + + + + +Melnikov & Newman Standards Track [Page 7] + +RFC 5092 IMAP URL Scheme November 2007 + + + Note that the <uidvalidity> field is a modifier to the <enc-mailbox>, + i.e., it is considered a part of the last "component" (as used in + [URI-GEN]) of the <enc-mailbox>. This is significant during relative + URI resolution. + + The "?<enc-search>" field is optional. If it is not present, the + program interpreting the URL will present the entire content of the + mailbox. + + If the "?<enc-search>" field is present, the program interpreting the + URL should use the contents of this field as arguments following an + IMAP4 SEARCH command. These arguments are likely to contain unsafe + characters such as " " (space) (which are likely to be present in the + <enc-search>). If unsafe characters are present, they MUST be + percent-encoded as described in [URI-GEN]. + + Note that quoted strings and non-synchronizing literals [LITERAL+] + are allowed in the <enc-search> content; however, synchronizing + literals are not allowed, as their presence would effectively mean + that the agent interpreting IMAP URLs needs to parse an <enc-search> + content, find all synchronizing literals, and perform proper command + continuation request handling (see Sections 4.3 and 7 of [IMAP4]). + +6. A Specific Message or Message Part + + An IMAP URL referring to a specific message or message part has the + following form: + + imap://<iserver>/<enc-mailbox>[<uidvalidity>]<iuid> + [<isection>][<ipartial>][<iurlauth>] + + The <enc-mailbox> and [uidvalidity] are as defined in Section 5 + above. + + If <uidvalidity> is present in this form, it SHOULD be used by the + program interpreting the URL to determine if the URL is stale. + + The <iuid> refers to an IMAP4 message Unique Identifier (UID), and it + SHOULD be used as the <set> argument to the IMAP4 "UID FETCH" + command. + + The <isection> field is optional. If not present, the URL refers to + the entire Internet message as returned by the IMAP command "UID + FETCH <uid> BODY.PEEK[]". If present, the URL refers to the object + returned by a "UID FETCH <uid> BODY.PEEK[<section>]" command. The + type of the object may be determined by using a "UID FETCH <uid> + BODYSTRUCTURE" command and locating the appropriate part in the + + + + +Melnikov & Newman Standards Track [Page 8] + +RFC 5092 IMAP URL Scheme November 2007 + + + resulting BODYSTRUCTURE. Note that unsafe characters in [isection] + MUST be percent-encoded as described in [URI-GEN]. + + The <ipartial> field is optional. If present, it effectively appends + "<<partial-range>>" to the end of the UID FETCH BODY.PEEK[<section>] + command constructed as described in the previous paragraph. In other + words, it allows the client to request a byte range of the + message/message part. + + The <iurlauth> field is described in detail in Section 6.1. + +6.1. URLAUTH Authorized URL + + URLAUTH authorized URLs are only supported by an IMAP server + advertising the URLAUTH IMAP capability [URLAUTH]. + +6.1.1. Concepts + +6.1.1.1. URLAUTH + + URLAUTH is a component, appended at the end of a URL, that conveys + authorization to access the data addressed by that URL. It contains + an authorized access identifier, an authorization mechanism name, and + an authorization token. The authorization token is generated from + the URL, the authorized access identifier, authorization mechanism + name, and a mailbox access key. + + Note: This specification only allows for the URLAUTH component in + IMAP URLs describing a message or its part. + +6.1.1.2. Mailbox Access Key + + The mailbox access key is an unpredictable, random string. To ensure + unpredictability, the random string with at least 128 bits of entropy + is generated by software or hardware (not by the human user). + + Each user has a table of mailboxes and an associated mailbox access + key for each mailbox. Consequently, the mailbox access key is per- + user and per-mailbox. In other words, two users sharing the same + mailbox each have a different mailbox access key for that mailbox, + and each mailbox accessed by a single user also has a different + mailbox access key. + +6.1.1.3. Authorized Access Identifier + + The authorized <access> identifier restricts use of the URLAUTH + authorized URL to certain users authorized on the server, as + described in Section 6.1.2. + + + +Melnikov & Newman Standards Track [Page 9] + +RFC 5092 IMAP URL Scheme November 2007 + + +6.1.1.4. Authorization Mechanism + + The authorization mechanism is the algorithm by which the URLAUTH is + generated and subsequently verified, using the mailbox access key. + +6.1.1.5. Authorization Token + + The authorization token is a deterministic string of at least 128 + bits that an entity with knowledge of the secret mailbox access key + and URL authorization mechanism can use to verify the URL. + +6.1.2. URLAUTH Extensions to IMAP URL + + A specific message or message part IMAP URL can optionally contain + ";EXPIRE=<datetime>" and/or ";URLAUTH=<access>:<mech>:<token>". + + When ";EXPIRE=<datetime>" is used, this indicates the latest date and + time that the URL is valid. After that date and time, the URL has + expired and server implementations MUST reject the URL. If + ";EXPIRE=<datetime>" is not used, the URL has no expiration, but can + still be revoked using the RESETKEY command [URLAUTH]. + + The URLAUTH takes the form ";URLAUTH=<access>:<mech>:<token>", and it + MUST be at the end of the URL. It is composed of three parts. The + <access> portion provides the authorized access identifiers that may + constrain the operations and users that are permitted to use this + URL. The <mech> portion provides the authorization mechanism used by + the IMAP server to generate the authorization token that follows. + The <token> portion provides the authorization token, which can be + generated using the GENURLAUTH command [URLAUTH]. + + The "submit+" <access> identifier prefix, followed by a userid, + indicates that only a userid authorized as a message submission + entity on behalf of the specified userid is permitted to use this + URL. The IMAP server does not validate the specified userid but does + validate that the IMAP session has an authorization identity that is + authorized as a message submission entity. The authorized message + submission entity MUST validate the userid prior to contacting the + IMAP server. + + The "user+" <access> identifier prefix, followed by a userid, + indicates that use of this URL is limited to IMAP sessions that are + logged in as the specified userid (that is, have authorization + identity as that userid). + + Note: If a SASL mechanism that provides both authorization and + authentication identifiers is used to authenticate to the IMAP + server, the "user+" <access> identifier MUST match the + + + +Melnikov & Newman Standards Track [Page 10] + +RFC 5092 IMAP URL Scheme November 2007 + + + authorization identifier. If the SASL mechanism can't transport + the authorization identifier, the "user+" <access> identifier MUST + match the authorization identifier derived from the authentication + identifier (see [SASL]). + + The "authuser" <access> identifier indicates that use of this URL is + limited to authenticated IMAP sessions that are logged in as any + non-anonymous user (that is, have authorization identity as a non- + anonymous user) of that IMAP server. To restate this: use of this + type of URL is prohibited to anonymous IMAP sessions, i.e., any + URLFETCH command containing this type of URL issued in an anonymous + session MUST return NIL in the URLFETCH response. + + The "anonymous" <access> identifier indicates that use of this URL is + not restricted by session authorization identity; that is, any IMAP + session in authenticated or selected state (as defined in [IMAP4]), + including anonymous sessions, may issue a URLFETCH [URLAUTH] using + this URL. + + The authorization token is represented as an ASCII-encoded + hexadecimal string, which is used to authorize the URL. The length + and the calculation of the authorization token depend upon the + mechanism used, but in all cases, the authorization token is at least + 128 bits (and therefore at least 32 hexadecimal digits). + + Example: + + <imap://joe@example.com/INBOX/;uid=20/;section=1.2;urlauth= + submit+fred:internal:91354a473744909de610943775f92038> + +7. Relative IMAP URLs + + Relative IMAP URLs are permitted and are resolved according to the + rules defined in [URI-GEN]. In particular, in IMAP URLs parameters + (such as ";uid=" or ";section=") are treated as part of the normal + path with respect to relative URL resolution. + + [URI-GEN] defines four forms of relative URLs: <inetwork-path>, + <iabsolute-path>, <irelative-path>, and <ipath-empty>. Their syntax + is defined in Section 11. + + A relative reference that begins with two slash characters is termed + a network-path reference (<inetwork-path>); such references are + rarely used, because in most cases they can be replaced with an + equivalent absolute URL. A relative reference that begins with a + single slash character is termed an absolute-path reference + (<iabsolute-path>; see also Section 7.1). A relative reference that + does not begin with a slash character is termed a relative-path + + + +Melnikov & Newman Standards Track [Page 11] + +RFC 5092 IMAP URL Scheme November 2007 + + + reference (<irelative-path>; see also Section 7.2). The final form + is <ipath-empty>, which is "same-document reference" (see Section 4.4 + of [URI-GEN]). + + The following observations about relative URLs are important: + + The <iauth> grammar element (which is a part of <iuserinfo>, which + is, in turn, a part of <iserver>; see Section 3) is considered part + of the user name for purposes of resolving relative IMAP URLs. This + means that unless a new user name/server specification is included in + the relative URL, the authentication mechanism is inherited from the + base IMAP URL. + + URLs always use "/" as the hierarchy delimiter for the purpose of + resolving paths in relative URLs. IMAP4 permits the use of any + hierarchy delimiter in mailbox names. For this reason, relative + mailbox paths will only work if the mailbox uses "/" as the hierarchy + delimiter. Relative URLs may be used on mailboxes that use other + delimiters, but in that case, the entire mailbox name MUST be + specified in the relative URL or inherited as a whole from the base + URL. + + If an IMAP server allows for mailbox names starting with "./" or + "../", ending with "/." or "/..", or containing sequences "/../" or + "/./", then such mailbox names MUST be percent-encoded as described + in [URI-GEN]. Otherwise, they would be misinterpreted as dot- + segments (see Section 3.3 of [URI-GEN]), which are processed + specially during the relative path resolution process. + +7.1. absolute-path References + + A relative reference that begins with a single slash character is + termed an absolute-path reference (see Section 4.2 of [URI-GEN]). If + an IMAP server permits mailbox names with a leading "/", then the + leading "/" MUST be percent-encoded as described in [URI-GEN]. + Otherwise, the produced absolute-path reference URI will be + misinterpreted as a network-path reference [URI-GEN] described by the + <inetwork-path> non-terminal. + +7.2. relative-path References + + A relative reference that does not begin with a slash character is + termed a relative-path reference [URI-GEN]. Implementations MUST NOT + generate or accept relative-path IMAP references. + + See also Section 4.2 of [URI-GEN] for restrictions on relative-path + references. + + + + +Melnikov & Newman Standards Track [Page 12] + +RFC 5092 IMAP URL Scheme November 2007 + + +8. Internationalization Considerations + + IMAP4, Section 5.1.3 [IMAP4] includes a convention for encoding non- + US-ASCII characters in IMAP mailbox names. Because this convention + is private to IMAP, it is necessary to convert IMAP's encoding to one + that can be more easily interpreted by a URL display program. For + this reason, IMAP's modified UTF-7 encoding for mailboxes MUST be + converted to UTF-8 [UTF-8]. Since 8-bit octets are not permitted in + URLs, the UTF-8 octets are percent-encoded as required by the URL + specification [URI-GEN], Section 2.1. Sample code is included in + Appendix A to demonstrate this conversion. + + IMAP user names are UTF-8 strings and MUST be percent-encoded as + required by the URL specification [URI-GEN], Section 2.1. + + Also note that IMAP SEARCH criteria can contain non-US-ASCII + characters. 8-bit octets in those strings MUST be percent-encoded as + required by the URL specification [URI-GEN], Section 2.1. + +9. Examples + + The following examples demonstrate how an IMAP4 client program might + translate various IMAP4 URLs into a series of IMAP4 commands. + Commands sent from the client to the server are prefixed with "C:", + and responses sent from the server to the client are prefixed with + "S:". + + The URL: + + <imap://minbari.example.org/gray-council;UIDVALIDITY=385759045/; + UID=20/;PARTIAL=0.1024> + + may result in the following client commands and server responses: + + <connect to minbari.example.org, port 143> + S: * OK [CAPABILITY IMAP4rev1 STARTTLS AUTH=ANONYMOUS] Welcome + C: A001 AUTHENTICATE ANONYMOUS + S: + + C: c2hlcmlkYW5AYmFieWxvbjUuZXhhbXBsZS5vcmc= + S: A001 OK Welcome sheridan@babylon5.example.org + C: A002 SELECT gray-council + <client verifies the UIDVALIDITY matches> + C: A003 UID FETCH 20 BODY.PEEK[]<0.1024> + + The URL: + + <imap://psicorp.example.org/~peter/%E6%97%A5%E6%9C%AC%E8%AA%9E/ + %E5%8F%B0%E5%8C%97> + + + +Melnikov & Newman Standards Track [Page 13] + +RFC 5092 IMAP URL Scheme November 2007 + + + may result in the following client commands: + + <connect to psicorp.example.org, port 143> + S: * OK [CAPABILITY IMAP4rev1 STARTTLS AUTH=CRAM-MD5] Welcome + C: A001 LOGIN ANONYMOUS bester@psycop.psicorp.example.org + C: A002 SELECT ~peter/&ZeVnLIqe-/&U,BTFw- + <commands the client uses for viewing the contents of + the mailbox> + + The URL: + + <imap://;AUTH=GSSAPI@minbari.example.org/gray-council/;uid=20/ + ;section=1.2> + + may result in the following client commands: + + <connect to minbari.example.org, port 143> + S: * OK Greetings + C: A000 CAPABILITY + S: * CAPABILITY IMAP4rev1 STARTTLS AUTH=GSSAPI + S: A000 OK + C: A001 AUTHENTICATE GSSAPI + <authentication exchange> + C: A002 SELECT gray-council + C: A003 UID FETCH 20 BODY.PEEK[1.2] + + If the following relative URL is located in that body part: + + <;section=1.4> + + this could result in the following client commands: + + C: A004 UID FETCH 20 (BODY.PEEK[1.2.MIME] + BODY.PEEK[1.MIME] + BODY.PEEK[HEADER.FIELDS (Content-Location)]) + <Client looks for Content-Location headers in + result. If no such headers, then it does the following> + C: A005 UID FETCH 20 BODY.PEEK[1.4] + + The URL: + + <imap://;AUTH=*@minbari.example.org/gray%20council? + SUBJECT%20shadows> + + + + + + + + +Melnikov & Newman Standards Track [Page 14] + +RFC 5092 IMAP URL Scheme November 2007 + + + could result in the following: + + <connect to minbari.example.org, port 143> + S: * OK Welcome + C: A001 CAPABILITY + S: * CAPABILITY IMAP4rev1 AUTH=DIGEST-MD5 + S: A001 OK + C: A002 AUTHENTICATE DIGEST-MD5 + <authentication exchange> + S: A002 OK user lennier authenticated + C: A003 SELECT "gray council" + ... + C: A004 SEARCH SUBJECT shadows + S: * SEARCH 8 10 13 14 15 16 + S: A004 OK SEARCH completed + C: A005 FETCH 8,10,13:16 ALL + ... + + In the example above, the client has implementation-dependent + choices. The authentication mechanism could be anything, including + PREAUTH. The final FETCH command could fetch more or less + information about the messages, depending on what it wishes to + display to the user. + + The URL: + + <imap://john;AUTH=*@minbari.example.org/babylon5/personel? + charset%20UTF-8%20SUBJECT%20%7B14+%7D%0D%0A%D0%98%D0%B2% + D0%B0%D0%BD%D0%BE%D0%B2%D0%B0> + + shows that 8-bit data can be sent using non-synchronizing literals + [LITERAL+]. This could result in the following: + + <connect to minbari.example.org, port 143> + S: * OK Hi there + C: A001 CAPABILITY + S: * CAPABILITY IMAP4rev1 LITERAL+ AUTH=DIGEST-MD5 + S: A001 OK + C: A002 AUTHENTICATE DIGEST-MD5 + <authentication exchange> + S: A002 OK user john authenticated + C: A003 SELECT babylon5/personel + ... + C: A004 SEARCH CHARSET UTF-8 SUBJECT {14+} + C: XXXXXXXXXXXXXX + S: * SEARCH 7 10 12 + S: A004 OK SEARCH completed + C: A005 FETCH 7,10,12 ALL + + + +Melnikov & Newman Standards Track [Page 15] + +RFC 5092 IMAP URL Scheme November 2007 + + + ... + + where XXXXXXXXXXXXXX is 14 bytes of UTF-8 encoded data as specified + in the URL above. + +9.1. Examples of Relative URLs + + The following absolute-path reference + + </foo/;UID=20/..> + + is the same as + + </foo> + + That is, both of them reference the mailbox "foo" located on the IMAP + server described by the corresponding Base URI. + + The following relative-path reference + + <;UID=20> + + references a message with UID in the mailbox specified by the Base + URI. + + The following edge case example demonstrates that the ;UIDVALIDITY= + modifier is a part of the mailbox name as far as relative URI + resolution is concerned: + + <..;UIDVALIDITY=385759045/;UID=20> + + In this example, ".." is not a dot-segment [URI-GEN]. + +10. Security Considerations + + Security considerations discussed in the IMAP specification [IMAP4] + and the URI specification [URI-GEN] are relevant. Security + considerations related to authenticated URLs are discussed in Section + 3.2 of this document. + + Many email clients store the plaintext password for later use after + logging into an IMAP server. Such clients MUST NOT use a stored + password in response to an IMAP URL without explicit permission from + the user to supply that password to the specified host name. + + Clients resolving IMAP URLs that wish to achieve data confidentiality + and/or integrity SHOULD use the STARTTLS command (if supported by the + + + + +Melnikov & Newman Standards Track [Page 16] + +RFC 5092 IMAP URL Scheme November 2007 + + + server) before starting authentication, or use a SASL mechanism, such + as GSSAPI, that provides a confidentiality security layer. + +10.1. Security Consideration Specific to URLAUTH Authorized URL + + The "user+<userid>" <access> identifier limits resolution of that URL + to a particular userid, whereas the "submit+<userid>" <access> + identifier is more general and simply requires that the session be + authorized by a user that has been granted a "submit" role within the + authentication system. Use of either of these mechanisms limits the + scope of the URL. An attacker who cannot authenticate using the + appropriate credentials cannot make use of the URL. + + The "authuser" and "anonymous" <access> identifiers do not have this + level of protection. These access identifiers are primarily useful + for public export of data from an IMAP server, without requiring that + it be copied to a web or anonymous FTP server. + + The decision to use the "authuser" <access> identifier should be made + with caution. An "authuser" <access> identifier can be used by any + authorized user of the IMAP server; therefore, use of this access + identifier should be limited to content that may be disclosed to any + authorized user of the IMAP server. + + The decision to use the "anonymous" <access> identifier should be + made with extreme caution. An "anonymous" <access> identifier can be + used by anyone; therefore, use of this access identifier should be + limited to content that may be disclosed to anyone. + +11. ABNF for IMAP URL Scheme + + Formal syntax is defined using ABNF [ABNF], extending the ABNF rules + in Section 9 of [IMAP4]. Elements not defined here can be found in + [ABNF], [IMAP4], [IMAPABNF], or [URI-GEN]. Strings are not case + sensitive, and free insertion of linear white space is not permitted. + + sub-delims-sh = "!" / "$" / "'" / "(" / ")" / + "*" / "+" / "," + ;; Same as [URI-GEN] sub-delims, + ;; but without ";", "&" and "=". + + uchar = unreserved / sub-delims-sh / pct-encoded + + achar = uchar / "&" / "=" + ;; Same as [URI-GEN] 'unreserved / sub-delims / + ;; pct-encoded', but ";" is disallowed. + + bchar = achar / ":" / "@" / "/" + + + +Melnikov & Newman Standards Track [Page 17] + +RFC 5092 IMAP URL Scheme November 2007 + + + enc-auth-type = 1*achar + ; %-encoded version of [IMAP4] "auth-type" + + enc-mailbox = 1*bchar + ; %-encoded version of [IMAP4] "mailbox" + + enc-search = 1*bchar + ; %-encoded version of [IMAPABNF] + ; "search-program". Note that IMAP4 + ; literals may not be used in + ; a "search-program", i.e., only + ; quoted or non-synchronizing + ; literals (if the server supports + ; LITERAL+ [LITERAL+]) are allowed. + + enc-section = 1*bchar + ; %-encoded version of [IMAP4] "section-spec" + + enc-user = 1*achar + ; %-encoded version of [IMAP4] authorization + ; identity or "userid". + + imapurl = "imap://" iserver ipath-query + ; Defines an absolute IMAP URL + + ipath-query = ["/" [ icommand ]] + ; Corresponds to "path-abempty [ "?" query ]" + ; in [URI-GEN] + + Generic syntax for relative URLs is defined in Section 4.2 of + [URI-GEN]. For ease of implementation, the relative IMAP URL syntax + is defined below: + + imapurl-rel = inetwork-path + + / iabsolute-path + / irelative-path + / ipath-empty + + inetwork-path = "//" iserver ipath-query + ; Corresponds to '"//" authority path-abempty + ; [ "?" query ]' in [URI-GEN] + + iabsolute-path = "/" [ icommand ] + ; icommand, if present, MUST NOT start with '/'. + ; + ; Corresponds to 'path-absolute [ "?" query ]' + ; in [URI-GEN] + + + +Melnikov & Newman Standards Track [Page 18] + +RFC 5092 IMAP URL Scheme November 2007 + + + irelative-path = imessagelist / + imsg-or-part + ; Corresponds to 'path-noscheme [ "?" query ]' + ; in [URI-GEN] + + imsg-or-part = ( imailbox-ref "/" iuid-only ["/" isection-only] + ["/" ipartial-only] ) / + ( iuid-only ["/" isection-only] + ["/" ipartial-only] ) / + ( isection-only ["/" ipartial-only] ) / + ipartial-only + + ipath-empty = 0<pchar> + ; Zero characters. + ; The same-document reference. + + The following three rules are only used in the presence of the IMAP + [URLAUTH] extension: + + authimapurl = "imap://" iserver "/" imessagepart + ; Same as "imapurl" when "[icommand]" is + ; "imessagepart" + + authimapurlfull = authimapurl iurlauth + ; Same as "imapurl" when "[icommand]" is + ; "imessagepart iurlauth" + + authimapurlrump = authimapurl iurlauth-rump + + + enc-urlauth = 32*HEXDIG + + iurlauth = iurlauth-rump iua-verifier + + iua-verifier = ":" uauth-mechanism ":" enc-urlauth + + iurlauth-rump = [expire] ";URLAUTH=" access + + access = ("submit+" enc-user) / ("user+" enc-user) / + "authuser" / "anonymous" + + expire = ";EXPIRE=" date-time + ; date-time is defined in [DATETIME] + + uauth-mechanism = "INTERNAL" / 1*(ALPHA / DIGIT / "-" / ".") + ; Case-insensitive. + ; New mechanisms MUST be registered with IANA. + + + + +Melnikov & Newman Standards Track [Page 19] + +RFC 5092 IMAP URL Scheme November 2007 + + + iauth = ";AUTH=" ( "*" / enc-auth-type ) + + icommand = imessagelist / + imessagepart [iurlauth] + + imailbox-ref = enc-mailbox [uidvalidity] + + imessagelist = imailbox-ref [ "?" enc-search ] + ; "enc-search" is [URI-GEN] "query". + + imessagepart = imailbox-ref iuid [isection] [ipartial] + + ipartial = "/" ipartial-only + + ipartial-only = ";PARTIAL=" partial-range + + isection = "/" isection-only + + isection-only = ";SECTION=" enc-section + + iserver = [iuserinfo "@"] host [ ":" port ] + ; This is the same as "authority" defined + ; in [URI-GEN]. See [URI-GEN] for "host" + ; and "port" definitions. + + iuid = "/" iuid-only + + iuid-only = ";UID=" nz-number + ; See [IMAP4] for "nz-number" definition + + iuserinfo = enc-user [iauth] / [enc-user] iauth + ; conforms to the generic syntax of + ; "userinfo" as defined in [URI-GEN]. + + partial-range = number ["." nz-number] + ; partial FETCH. The first number is + ; the offset of the first byte, + ; the second number is the length of + ; the fragment. + + uidvalidity = ";UIDVALIDITY=" nz-number + ; See [IMAP4] for "nz-number" definition + + + + + + + + + +Melnikov & Newman Standards Track [Page 20] + +RFC 5092 IMAP URL Scheme November 2007 + + +12. IANA Considerations + + IANA has updated the "imap" definition in the "Uniform Resource + Identifier scheme registry" to point to this document. + + The registration template (as per [URI-REG]) is specified in Section + 12.1 of this document. + +12.1. IANA Registration of imap: URI Scheme + + This section provides the information required to register the imap: + URI scheme. + + URI scheme name: imap + + Status: permanent + + URI scheme syntax: + + See Section 11 of [RFC5092]. + + URI scheme semantics: + + The imap: URI scheme is used to designate IMAP servers, mailboxes, + messages, MIME bodies [MIME] and their parts, and search programs + on Internet hosts accessible using the IMAP protocol. + + There is no MIME type associated with this URI. + + Encoding considerations: + + See Section 8 of [RFC5092]. + + Applications/protocols that use this URI scheme name: + + The imap: URI is intended to be used by applications that might + need access to an IMAP mailstore. Such applications may include + (but are not limited to) IMAP-capable web browsers; IMAP clients + that wish to access a mailbox, message, or edit a message on the + server using [CATENATE]; [SUBMIT] clients and servers that are + requested to assemble a complete message on submission using + [BURL]. + + Interoperability considerations: + + A widely deployed IMAP client Netscape Mail (and possibly + Mozilla/Thunderbird/Seamonkey) uses a different imap: scheme + internally. + + + +Melnikov & Newman Standards Track [Page 21] + +RFC 5092 IMAP URL Scheme November 2007 + + + Security considerations: + + See Security Considerations (Section 10) of [RFC5092]. + + Contact: + + Alexey Melnikov <alexey.melnikov@isode.com> + + Author/Change controller: + + IESG + + References: + + [RFC5092] and [IMAP4]. + +13. References + +13.1. Normative References + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [IMAP4] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [IMAPABNF] Melnikov, A. and C. Daboo, "Collected Extensions to + IMAP4 ABNF", RFC 4466, April 2006. + + [ABNF] Crocker, D., Ed., and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", RFC 4234, October 2005. + + [MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail + Extensions (MIME) Part One: Format of Internet Message + Bodies", RFC 2045, November 1996. + + [URI-GEN] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, RFC + 3986, January 2005. + + [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. + + [NAMESPACE] Gahrns, M. and C. Newman, "IMAP4 Namespace", RFC 2342, + May 1998. + + [LITERAL+] Myers, J., "IMAP4 non-synchronizing literals", RFC 2088, + January 1997. + + + +Melnikov & Newman Standards Track [Page 22] + +RFC 5092 IMAP URL Scheme November 2007 + + + [ANONYMOUS] Zeilenga, K., "Anonymous Simple Authentication and + Security Layer (SASL) Mechanism", RFC 4505, June 2006. + + [DATETIME] Klyne, G. and C. Newman, "Date and Time on the Internet: + Timestamps", RFC 3339, July 2002. + + [URLAUTH] Crispin, M., "Internet Message Access Protocol (IMAP) - + URLAUTH Extension", RFC 4467, May 2006. + +13.2. Informative References + + [SUBMIT] Gellens, R. and J. Klensin, "Message Submission for + Mail", RFC 4409, April 2006. + + [BURL] Newman, C., "Message Submission BURL Extension", RFC + 4468, May 2006. + + [CATENATE] Resnick, P., "Internet Message Access Protocol (IMAP) + CATENATE Extension", RFC 4469, April 2006. + + [SASL] Melnikov, A., Ed., and K. Zeilenga, Ed., "Simple + Authentication and Security Layer (SASL)", RFC 4422, + June 2006. + + [GSSAPI] Melnikov, A., Ed., "The Kerberos V5 ("GSSAPI") Simple + Authentication and Security Layer (SASL) Mechanism", RFC + 4752, November 2006. + + [DIGEST-MD5] Leach, P. and C. Newman, "Using Digest Authentication as + a SASL Mechanism", RFC 2831, May 2000. + + [URI-REG] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and + Registration Procedures for New URI Schemes", BCP 115, + RFC 4395, February 2006. + + + + + + + + + + + + + + + + + +Melnikov & Newman Standards Track [Page 23] + +RFC 5092 IMAP URL Scheme November 2007 + + +Appendix A. Sample Code + + Here is sample C source code to convert between URL paths and IMAP + mailbox names, taking into account mapping between IMAP's modified + UTF-7 [IMAP4] and hex-encoded UTF-8, which is more appropriate for + URLs. This code has not been rigorously tested nor does it + necessarily behave reasonably with invalid input, but it should serve + as a useful example. This code just converts the mailbox portion of + the URL and does not deal with parameters, query, or server + components of the URL. + +/* Copyright (C) The IETF Trust (2007). This version of + sample C code is part of RFC XXXX; see the RFC itself + for full legal notices. + + Regarding this sample C code (or any portion of it), the authors + make no guarantees and are not responsible for any damage + resulting from its use. The authors grant irrevocable permission + to anyone to use, modify, and distribute it in any way that does + not diminish the rights of anyone else to use, modify, and + distribute it, provided that redistributed derivative works do + not contain misleading author or version information. + + Derivative works need not be licensed under similar terms. + */ + +#include <stdio.h> +#include <string.h> + +/* hexadecimal lookup table */ +static const char hex[] = "0123456789ABCDEF"; + +#define XX 127 +/* + * Table for decoding hexadecimal in %encoding + */ +static const char index_hex[256] = { + XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, + XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, + XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9,XX,XX, XX,XX,XX,XX, + XX,10,11,12, 13,14,15,XX, XX,XX,XX,XX, XX,XX,XX,XX, + XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, + XX,10,11,12, 13,14,15,XX, XX,XX,XX,XX, XX,XX,XX,XX, + XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, + XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, + XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, + XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, + + + +Melnikov & Newman Standards Track [Page 24] + +RFC 5092 IMAP URL Scheme November 2007 + + + XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, + XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, + XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, + XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, + XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, +}; +#define HEXCHAR(c) (index_hex[(unsigned char)(c)]) + +/* "gen-delims" excluding "/" but including "%" */ +#define GENERAL_DELIMS_NO_SLASH ":?#[]@" "%" + +/* "gen-delims" (excluding "/", but including "%") + plus subset of "sub-delims" */ +#define GENERAL_UNSAFE_NO_SLASH GENERAL_DELIMS_NO_SLASH ";&=+" +#define OTHER_UNSAFE " \"<>\\^`{|}" + +/* URL unsafe printable characters */ +static const char mailbox_url_unsafe[] = GENERAL_UNSAFE_NO_SLASH + OTHER_UNSAFE; + +/* UTF7 modified base64 alphabet */ +static const char base64chars[] = + "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+,"; + +#define UNDEFINED 64 + +/* UTF16 definitions */ +#define UTF16MASK 0x03FFUL +#define UTF16SHIFT 10 +#define UTF16BASE 0x10000UL +#define UTF16HIGHSTART 0xD800UL +#define UTF16HIGHEND 0xDBFFUL +#define UTF16LOSTART 0xDC00UL +#define UTF16LOEND 0xDFFFUL + +/* Convert an IMAP mailbox to a URL path + * dst needs to have roughly 4 times the storage space of src + * Hex encoding can triple the size of the input + * UTF-7 can be slightly denser than UTF-8 + * (worst case: 8 octets UTF-7 becomes 9 octets UTF-8) + */ +void MailboxToURL(char *dst, char *src) +{ + unsigned char c, i, bitcount; + unsigned long ucs4, utf16, bitbuf; + unsigned char base64[256], utf8[6]; + + /* initialize modified base64 decoding table */ + + + +Melnikov & Newman Standards Track [Page 25] + +RFC 5092 IMAP URL Scheme November 2007 + + + memset(base64, UNDEFINED, sizeof (base64)); + for (i = 0; i < sizeof (base64chars); ++i) { + base64[(int) base64chars[i]] = i; + } + + /* loop until end of string */ + while (*src != '\0') { + c = *src++; + /* deal with literal characters and &- */ + if (c != '&' || *src == '-') { + /* NB: There are no "URL safe" characters after the '~' */ + if (c < ' ' || c > '~' || + strchr(mailbox_url_unsafe, c) != NULL) { + /* hex encode if necessary */ + dst[0] = '%'; + dst[1] = hex[c >> 4]; + dst[2] = hex[c & 0x0f]; + dst += 3; + } else { + /* encode literally */ + *dst++ = c; + } + /* skip over the '-' if this is an &- sequence */ + if (c == '&') ++src; + + } else { + /* convert modified UTF-7 -> UTF-16 -> UCS-4 -> UTF-8 -> HEX */ + bitbuf = 0; + bitcount = 0; + ucs4 = 0; + while ((c = base64[(unsigned char) *src]) != UNDEFINED) { + ++src; + bitbuf = (bitbuf << 6) | c; + bitcount += 6; + /* enough bits for a UTF-16 character? */ + if (bitcount >= 16) { + bitcount -= 16; + utf16 = (bitcount ? bitbuf >> bitcount + : bitbuf) & 0xffff; + /* convert UTF16 to UCS4 */ + if + (utf16 >= UTF16HIGHSTART && utf16 <= UTF16HIGHEND) { + ucs4 = (utf16 - UTF16HIGHSTART) << UTF16SHIFT; + continue; + } else if + (utf16 >= UTF16LOSTART && utf16 <= UTF16LOEND) { + ucs4 += utf16 - UTF16LOSTART + UTF16BASE; + } else { + + + +Melnikov & Newman Standards Track [Page 26] + +RFC 5092 IMAP URL Scheme November 2007 + + + ucs4 = utf16; + } + /* convert UTF-16 range of UCS4 to UTF-8 */ + if (ucs4 <= 0x7fUL) { + utf8[0] = (unsigned char) ucs4; + i = 1; + } else if (ucs4 <= 0x7ffUL) { + utf8[0] = 0xc0 | (unsigned char) (ucs4 >> 6); + utf8[1] = 0x80 | (unsigned char) (ucs4 & 0x3f); + i = 2; + } else if (ucs4 <= 0xffffUL) { + utf8[0] = 0xe0 | (unsigned char) (ucs4 >> 12); + utf8[1] = 0x80 | (unsigned char) ((ucs4 >> 6) & 0x3f); + utf8[2] = 0x80 | (unsigned char) (ucs4 & 0x3f); + i = 3; + } else { + utf8[0] = 0xf0 | (unsigned char) (ucs4 >> 18); + utf8[1] = 0x80 | (unsigned char) ((ucs4 >> 12) & 0x3f); + utf8[2] = 0x80 | (unsigned char) ((ucs4 >> 6) & 0x3f); + utf8[3] = 0x80 | (unsigned char) (ucs4 & 0x3f); + i = 4; + } + /* convert utf8 to hex */ + for (c = 0; c < i; ++c) { + dst[0] = '%'; + dst[1] = hex[utf8[c] >> 4]; + dst[2] = hex[utf8[c] & 0x0f]; + dst += 3; + } + } + } + /* skip over trailing '-' in modified UTF-7 encoding */ + if (*src == '-') ++src; + } + } + /* terminate destination string */ + *dst = '\0'; +} + +/* Convert hex coded UTF-8 URL path to modified UTF-7 IMAP mailbox + * dst should be about twice the length of src to deal with non-hex + * coded URLs + */ +int URLtoMailbox(char *dst, char *src) +{ + unsigned int utf8pos = 0; + unsigned int utf8total, i, c, utf7mode, bitstogo, utf16flag; + unsigned long ucs4 = 0, bitbuf = 0; + + + +Melnikov & Newman Standards Track [Page 27] + +RFC 5092 IMAP URL Scheme November 2007 + + + utf7mode = 0; /* is the output UTF7 currently in base64 mode? */ + utf8total = 0; /* how many octets is the current input UTF-8 char; + 0 == between characters */ + bitstogo = 0; /* bits that need to be encoded into base64; if + bitstogo != 0 then utf7mode == 1 */ + while ((c = (unsigned char)*src) != '\0') { + ++src; + /* undo hex-encoding */ + if (c == '%' && src[0] != '\0' && src[1] != '\0') { + c = HEXCHAR(src[0]); + i = HEXCHAR(src[1]); + if (c == XX || i == XX) { + return 0; + } else { + c = (char)((c << 4) | i); + } + src += 2; + } + /* normal character? */ + if (c >= ' ' && c <= '~') { + /* switch out of UTF-7 mode */ + if (utf7mode) { + if (bitstogo) { + *dst++ = base64chars[(bitbuf << (6 - bitstogo)) & 0x3F]; + } + *dst++ = '-'; + utf7mode = 0; + bitstogo = bitbuf = 0; + } + *dst++ = c; + /* encode '&' as '&-' */ + if (c == '&') { + *dst++ = '-'; + } + continue; + } + /* switch to UTF-7 mode */ + if (!utf7mode) { + *dst++ = '&'; + utf7mode = 1; + } + /* Encode US-ASCII characters as themselves */ + if (c < 0x80) { + ucs4 = c; + utf8total = 1; + } else if (utf8total) { + /* this is a subsequent octet of a multi-octet character */ + /* save UTF8 bits into UCS4 */ + + + +Melnikov & Newman Standards Track [Page 28] + +RFC 5092 IMAP URL Scheme November 2007 + + + ucs4 = (ucs4 << 6) | (c & 0x3FUL); + if (++utf8pos < utf8total) { + continue; + } + } else { + /* this is the first octet of a multi-octet character */ + utf8pos = 1; + if (c < 0xE0) { + utf8total = 2; + ucs4 = c & 0x1F; + } else if (c < 0xF0) { + utf8total = 3; + ucs4 = c & 0x0F; + } else { + /* NOTE: can't convert UTF8 sequences longer than 4 */ + utf8total = 4; + ucs4 = c & 0x03; + } + continue; + } + /* Finished with UTF-8 character. Make sure it isn't an + overlong sequence. If it is, return failure. */ + if ((ucs4 < 0x80 && utf8total > 1) || + (ucs4 < 0x0800 && utf8total > 2) || + (ucs4 < 0x00010000 && utf8total > 3) || + (ucs4 < 0x00200000 && utf8total > 4) || + (ucs4 < 0x04000000 && utf8total > 5) || + (ucs4 < 0x80000000 && utf8total > 6)) { + return 0; + } + /* loop to split ucs4 into two utf16 chars if necessary */ + utf8total = 0; + do { + if (ucs4 >= UTF16BASE) { + ucs4 -= UTF16BASE; + bitbuf = (bitbuf << 16) | ((ucs4 >> UTF16SHIFT) + + UTF16HIGHSTART); + ucs4 = (ucs4 & UTF16MASK) + UTF16LOSTART; + utf16flag = 1; + } else { + bitbuf = (bitbuf << 16) | ucs4; + utf16flag = 0; + } + bitstogo += 16; + /* spew out base64 */ + while (bitstogo >= 6) { + bitstogo -= 6; + *dst++ = base64chars[(bitstogo ? (bitbuf >> bitstogo) + + + +Melnikov & Newman Standards Track [Page 29] + +RFC 5092 IMAP URL Scheme November 2007 + + + : bitbuf) + & 0x3F]; + } + } while (utf16flag); + } + /* if in UTF-7 mode, finish in ASCII */ + if (utf7mode) { + if (bitstogo) { + *dst++ = base64chars[(bitbuf << (6 - bitstogo)) & 0x3F]; + } + *dst++ = '-'; + } + /* tie off string */ + *dst = '\0'; + return 1; +} + +Appendix B. List of Changes since RFC 2192 + + Updated boilerplate, list of editor's, etc. + Updated references. + Updated ABNF not to use _, to use SP instead of SPACE, etc. + Updated example domains to use example.org. + Fixed ABNF error in "imessagelist" non-terminal. + Updated ABNF, due to changes in RFC 3501, RFC 4466, and RFC 3986. + Renamed "iuserauth" non-terminal to <iuserinfo>. + Clarified that the userinfo component describes both authorization + identity and mailbox naming scope. + Allow for non-synchronizing literals in "enc-search". + Added "ipartial" specifier that denotes a partial FETCH. + Moved URLAUTH text from RFC 4467 to this document. + Updated ABNF for the whole server to allow missing trailing "/" + (e.g., "imap://imap.example.com" is now valid and is the same as + "imap://imap.example.com/"). + Clarified how relative-path references are constructed. + Added more examples demonstrating relative-path references. + Added rules for relative URLs and restructured ABNF as the result. + Removed text on use of relative URLs in MHTML. + Added examples demonstrating security considerations when resolving + URLs. + Recommend usage of STARTTLS/SASL security layer to protect + confidential data. + Removed some advices about connection reuse that were incorrect. + Removed URLs referencing a list of mailboxes, as this feature + hasn't seen any deployments. + Clarified that user name "anonymous" is case-insensitive. + + + + + +Melnikov & Newman Standards Track [Page 30] + +RFC 5092 IMAP URL Scheme November 2007 + + +Appendix C. List of Changes since RFC 4467 + + Renamed <mechanism> to <uauth-mechanism>. Restructured ABNF. + +Appendix D. Acknowledgments + + Text describing URLAUTH was lifted from [URLAUTH] by Mark Crispin. + + Stephane H. Maes contributed some ideas to this document; he also + co-edited early versions of this document. + + The editors would like to thank Mark Crispin, Ken Murchison, Ted + Hardie, Zoltan Ordogh, Dave Cridland, Kjetil Torgrim Homme, Lisa + Dusseault, Spencer Dawkins, Filip Navara, Shawn M. Emery, Sam + Hartman, Russ Housley, and Lars Eggert for the time they devoted to + reviewing this document and/or for the comments received. + +Authors' Addresses + + Chris Newman (Author/Editor) + Sun Microsystems + 3401 Centrelake Dr., Suite 410 + Ontario, CA 91761 + EMail: chris.newman@sun.com + + Alexey Melnikov (Editor) + Isode Limited + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex + TW12 2BX, UK + EMail: Alexey.Melnikov@isode.com + URI: http://www.melnikov.ca/ + + + + + + + + + + + + + + + + + + +Melnikov & Newman Standards Track [Page 31] + +RFC 5092 IMAP URL Scheme November 2007 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2007). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Melnikov & Newman Standards Track [Page 32] + diff --git a/imap/docs/rfc/rfc5161.txt b/imap/docs/rfc/rfc5161.txt new file mode 100644 index 00000000..13bbbf74 --- /dev/null +++ b/imap/docs/rfc/rfc5161.txt @@ -0,0 +1,395 @@ + + + + + + +Network Working Group A. Gulbrandsen, Ed. +Request for Comments: 5161 Oryx Mail Systems GmbH +Category: Standards Track A. Melnikov, Ed. + Isode Limited + March 2008 + + + The IMAP ENABLE Extension + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + Most IMAP extensions are used by the client when it wants to and the + server supports it. However, a few extensions require the server to + know whether a client supports that extension. The ENABLE extension + allows an IMAP client to say which extensions it supports. + +1. Overview + + Several IMAP extensions allow the server to return unsolicited + responses specific to these extensions in certain circumstances. + However, servers cannot send those unsolicited responses until they + know that the clients support such extensions and thus won't choke on + the extension response data. + + Up until now, extensions have typically stated that a server cannot + send the unsolicited responses until after the client has used a + command with the extension data (i.e., at that point the server knows + the client is aware of the extension). CONDSTORE ([RFC4551]), + ANNOTATE ([ANNOTATE]), and some extensions under consideration at the + moment use various commands to enable server extensions. For + example, CONDSTORE uses a SELECT or FETCH parameter, and ANNOTATE + uses a side effect of FETCH. + + The ENABLE extension provides an explicit indication from the client + that it supports particular extensions. This is done using a new + ENABLE command. + + An IMAP server that supports ENABLE advertises this by including the + word ENABLE in its capability list. + + + + +Gulbrandsen & Melnikov Standards Track [Page 1] + +RFC 5161 The IMAP ENABLE Extension March 2008 + + + Most IMAP extensions do not require the client to enable the + extension in any way. + +2. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + Formal syntax is defined by [RFC5234] and [RFC3501]. + + Example lines prefaced by "C:" are sent by the client and ones + prefaced by "S:" by the server. The five characters [...] means that + something has been elided. + +3. Protocol Changes + +3.1. The ENABLE Command + + Arguments: capability names + + Result: OK: Relevant capabilities enabled + BAD: No arguments, or syntax error in an argument + + The ENABLE command takes a list of capability names, and requests the + server to enable the named extensions. Once enabled using ENABLE, + each extension remains active until the IMAP connection is closed. + For each argument, the server does the following: + + - If the argument is not an extension known to the server, the server + MUST ignore the argument. + + - If the argument is an extension known to the server, and it is not + specifically permitted to be enabled using ENABLE, the server MUST + ignore the argument. (Note that knowing about an extension doesn't + necessarily imply supporting that extension.) + + - If the argument is an extension that is supported by the server and + that needs to be enabled, the server MUST enable the extension for + the duration of the connection. At present, this applies only to + CONDSTORE ([RFC4551]). Note that once an extension is enabled, + there is no way to disable it. + + If the ENABLE command is successful, the server MUST send an untagged + ENABLED response (see Section 3.2). + + + + + + +Gulbrandsen & Melnikov Standards Track [Page 2] + +RFC 5161 The IMAP ENABLE Extension March 2008 + + + Clients SHOULD only include extensions that need to be enabled by the + server. At the time of publication, CONDSTORE is the only such + extension (i.e., ENABLE CONDSTORE is an additional "CONDSTORE + enabling command" as defined in [RFC4551]). Future RFCs may add to + this list. + + The ENABLE command is only valid in the authenticated state (see + [RFC3501]), before any mailbox is selected. Clients MUST NOT issue + ENABLE once they SELECT/EXAMINE a mailbox; however, server + implementations don't have to check that no mailbox is selected or + was previously selected during the duration of a connection. + + The ENABLE command can be issued multiple times in a session. It is + additive; i.e., "ENABLE a b", followed by "ENABLE c" is the same as a + single command "ENABLE a b c". When multiple ENABLE commands are + issued, each corresponding ENABLED response SHOULD only contain + extensions enabled by the corresponding ENABLE command. + + There are no limitations on pipelining ENABLE. For example, it is + possible to send ENABLE and then immediately SELECT, or a LOGIN + immediately followed by ENABLE. + + The server MUST NOT change the CAPABILITY list as a result of + executing ENABLE; i.e., a CAPABILITY command issued right after an + ENABLE command MUST list the same capabilities as a CAPABILITY + command issued before the ENABLE command. This is demonstrated in + the following example: + + C: t1 CAPABILITY + S: * CAPABILITY IMAP4rev1 ID LITERAL+ ENABLE X-GOOD-IDEA + S: t1 OK foo + C: t2 ENABLE CONDSTORE X-GOOD-IDEA + S: * ENABLED X-GOOD-IDEA + S: t2 OK foo + C: t3 CAPABILITY + S: * CAPABILITY IMAP4rev1 ID LITERAL+ ENABLE X-GOOD-IDEA + S: t3 OK foo again + + In the following example, the client enables CONDSTORE: + + C: a1 ENABLE CONDSTORE + S: * ENABLED CONDSTORE + S: a1 OK Conditional Store enabled + + + + + + + + +Gulbrandsen & Melnikov Standards Track [Page 3] + +RFC 5161 The IMAP ENABLE Extension March 2008 + + +3.2. The ENABLED Response + + Contents: capability listing + + The ENABLED response occurs as a result of an ENABLE command. The + capability listing contains a space-separated listing of capability + names that the server supports and that were successfully enabled. + The ENABLED response may contain no capabilities, which means that no + extensions listed by the client were successfully enabled. + +3.3. Note to Designers of Extensions That May Use the ENABLE Command + + Designers of IMAP extensions are discouraged from creating extensions + that require ENABLE unless there is no good alternative design. + Specifically, extensions that cause potentially incompatible behavior + changes to deployed server responses (and thus benefit from ENABLE) + have a higher complexity cost than extensions that do not. + +4. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [RFC5234] including the core + rules in Appendix B.1. [RFC3501] defines the non-terminals + "capability" and "command-any". + + Except as noted otherwise, all alphabetic characters are + case-insensitive. The use of upper or lower case characters to + define token strings is for editorial clarity only. Implementations + MUST accept these strings in a case-insensitive fashion. + + capability =/ "ENABLE" + + command-any =/ "ENABLE" 1*(SP capability) + + response-data =/ "*" SP enable-data CRLF + + enable-data = "ENABLED" *(SP capability) + +5. Security Considerations + + It is believed that this extension doesn't add any security + considerations that are not already present in the base IMAP protocol + [RFC3501]. + +6. IANA Considerations + + The IANA has added ENABLE to the IMAP4 Capabilities Registry. + + + + +Gulbrandsen & Melnikov Standards Track [Page 4] + +RFC 5161 The IMAP ENABLE Extension March 2008 + + +7. Acknowledgments + + The editors would like to thank Randy Gellens, Chris Newman, Peter + Coates, Dave Cridland, Mark Crispin, Ned Freed, Dan Karp, Cyrus + Daboo, Ken Murchison, and Eric Burger for comments and corrections. + However, this doesn't necessarily mean that they endorse this + extension, agree with all details, or are responsible for errors + introduced by the editors. + +8. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", STD 68, RFC 5234, January + 2008. + + [RFC4551] Melnikov, A. and S. Hole, "IMAP Extension for Conditional + STORE Operation or Quick Flag Changes Resynchronization", + RFC 4551, June 2006. + +9. Informative References + + [ANNOTATE] Daboo, C. and R. Gellens, "IMAP ANNOTATE Extension", Work + in Progress, August 2006. + + + + + + + + + + + + + + + + + + + + + + +Gulbrandsen & Melnikov Standards Track [Page 5] + +RFC 5161 The IMAP ENABLE Extension March 2008 + + +Editors' Addresses + + Arnt Gulbrandsen + Oryx Mail Systems GmbH + Schweppermannstr. 8 + D-81671 Muenchen + Germany + + Fax: +49 89 4502 9758 + EMail: arnt@oryx.com + + + Alexey Melnikov + Isode Ltd + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: Alexey.Melnikov@isode.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Gulbrandsen & Melnikov Standards Track [Page 6] + +RFC 5161 The IMAP ENABLE Extension March 2008 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2008). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Gulbrandsen & Melnikov Standards Track [Page 7] + diff --git a/imap/docs/rfc/rfc5162.txt b/imap/docs/rfc/rfc5162.txt new file mode 100644 index 00000000..305c54fb --- /dev/null +++ b/imap/docs/rfc/rfc5162.txt @@ -0,0 +1,1291 @@ + + + + + + +Network Working Group A. Melnikov +Request for Comments: 5162 D. Cridland +Category: Standards Track Isode Ltd + C. Wilson + Nokia + March 2008 + + + IMAP4 Extensions for Quick Mailbox Resynchronization + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + This document defines an IMAP4 extension, which gives an IMAP client + the ability to quickly resynchronize any previously opened mailbox as + part of the SELECT command, without the need for server-side state or + additional client round-trips. This extension also introduces a new + response that allows for a more compact representation of a list of + expunged messages (and always includes the Unique Identifiers (UIDs) + expunged). + + + + + + + + + + + + + + + + + + + + + + + + +Melnikov, et al. Standards Track [Page 1] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + +Table of Contents + + 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 2 + 2. Requirements Notation . . . . . . . . . . . . . . . . . . . . 4 + 3. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . 4 + 3.1. QRESYNC Parameter to SELECT/EXAMINE . . . . . . . . . . . 4 + 3.2. VANISHED UID FETCH Modifier . . . . . . . . . . . . . . . 8 + 3.3. EXPUNGE Command . . . . . . . . . . . . . . . . . . . . . 10 + 3.4. CLOSE Command . . . . . . . . . . . . . . . . . . . . . . 11 + 3.5. UID EXPUNGE Command . . . . . . . . . . . . . . . . . . . 11 + 3.6. VANISHED Response . . . . . . . . . . . . . . . . . . . . 12 + 3.7. CLOSED Response Code . . . . . . . . . . . . . . . . . . . 15 + 4. Server Implementation Considerations . . . . . . . . . . . . . 15 + 4.1. Server Implementations That Don't Store Extra State . . . 15 + 4.2. Server Implementations Storing Minimal State . . . . . . . 16 + 4.3. Additional State Required on the Server . . . . . . . . . 16 + 5. Updated Synchronization Sequence . . . . . . . . . . . . . . . 17 + 6. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 19 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 20 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 + 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 21 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 + 10.1. Normative References . . . . . . . . . . . . . . . . . . . 21 + 10.2. Informative References . . . . . . . . . . . . . . . . . . 22 + +1. Introduction and Overview + + The [CONDSTORE] extension gives a disconnected client the ability to + quickly resynchronize IMAP flag changes for previously seen messages. + This can be done using the CHANGEDSINCE FETCH modifier once a mailbox + is opened. In order for the client to discover which messages have + been expunged, the client still has to issue a UID FETCH or a UID + SEARCH command. This document defines an extension to [CONDSTORE] + that allows a reconnecting client to perform full resynchronization, + including discovery of expunged messages, in a single round-trip. + This extension also introduces a new response, VANISHED, that allows + for a more compact representation of a list of expunged messages. + + This extension can be useful for mobile clients that can experience + frequent disconnects caused by environmental factors (battery life, + signal strength, etc.). Such clients need a way to quickly reconnect + to the IMAP server, while minimizing delay experienced by the user as + well as the amount of traffic (and hence the expense) generated by + resynchronization. + + + + + + + +Melnikov, et al. Standards Track [Page 2] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + By extending the SELECT command to perform the additional + resynchronization, this also allows clients to reduce concurrent + connections to the IMAP server held purely for the sake of avoiding + the resynchronization. + + The quick resync IMAP extension is present if an IMAP4 server returns + "QRESYNC" as one of the supported capabilities to the CAPABILITY + command. + + Servers supporting this extension MUST implement and advertise + support for the [ENABLE] IMAP extension. Also, the presence of the + "QRESYNC" capability implies support for the [CONDSTORE] IMAP + extension even if the CONDSTORE capability isn't advertised. A + server compliant with this specification is REQUIREd to support + "ENABLE QRESYNC" and "ENABLE QRESYNC CONDSTORE" (which are "CONDSTORE + enabling commands", as defined in [CONDSTORE], and have identical + results), but there is no requirement for a compliant server to + support "ENABLE CONDSTORE" by itself. The "ENABLE QRESYNC"/"ENABLE + QRESYNC CONDSTORE" command also tells the server that it SHOULD start + sending VANISHED responses (see Section 3.6) instead of EXPUNGE + responses. This change remains in effect until the connection is + closed. + + For compatibility with clients that only support the [CONDSTORE] IMAP + extension, servers SHOULD advertise CONDSTORE in the CAPABILITY + response as well. + + A client making use of this extension MUST issue "ENABLE QRESYNC" + once it is authenticated. A server MUST respond with a tagged BAD + response if the QRESYNC parameter to the SELECT/EXAMINE command or + the VANISHED UID FETCH modifier is specified and the client hasn't + issued "ENABLE QRESYNC" in the current connection. + + This document puts additional requirements on a server implementing + the [CONDSTORE] extension. Each mailbox that supports persistent + storage of mod-sequences, i.e., for which the server has sent a + HIGHESTMODSEQ untagged OK response code on a successful SELECT/ + EXAMINE, MUST increment the per-mailbox mod-sequence when one or more + messages are expunged due to EXPUNGE, UID EXPUNGE or CLOSE; the + server MUST associate the incremented mod-sequence with the UIDs of + the expunged messages. + + A client that supports CONDSTORE but not this extension might + resynchronize a mailbox and discover that its HIGHESTMODSEQ has + increased from the value cached by the client. If the increase is + only due to messages having been expunged since the client last + synchronized, the client is likely to send a FETCH ... CHANGEDSINCE + command that returns no data. Thus, a client that supports CONDSTORE + + + +Melnikov, et al. Standards Track [Page 3] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + but not this extension might incur a penalty of an unneeded round- + trip when resynchronizing some mailboxes (those that have had + messages expunged but no flag changes since the last + synchronization). + + This extra round-trip is only incurred by clients that support + CONDSTORE but not this extension, and only when a mailbox has had + messages expunged but no flag changes to non-expunged messages. + Since CONDSTORE is a relatively new extension, it is thought likely + that clients that support it will also support this extension. + +2. Requirements Notation + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + In examples, "C:" and "S:" indicate lines sent by the client and + server respectively. If a single "C:" or "S:" label applies to + multiple lines, then the line breaks between those lines are for + editorial clarity only and are not part of the actual protocol + exchange. The five characters [...] means that something has been + elided. + + Understanding of the IMAP message sequence numbers and UIDs and the + EXPUNGE response [RFC3501] is essential when reading this document. + +3. IMAP Protocol Changes + +3.1. QRESYNC Parameter to SELECT/EXAMINE + + The Quick Resynchronization parameter to SELECT/EXAMINE commands has + four arguments: + + o the last known UIDVALIDITY, + + o the last known modification sequence, + + o the optional set of known UIDs, and + + o an optional parenthesized list of known sequence ranges and their + corresponding UIDs. + + A server MUST respond with a tagged BAD response if the Quick + Resynchronization parameter to SELECT/EXAMINE command is specified + and the client hasn't issued "ENABLE QRESYNC" in the current + connection. + + + + +Melnikov, et al. Standards Track [Page 4] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + Before opening the specified mailbox, the server verifies all + arguments for syntactic validity. If any parameter is not + syntactically valid, the server returns the tagged BAD response, and + the mailbox remains unselected. Once the check is done, the server + opens the mailbox as if no SELECT/EXAMINE parameters are specified + (this is subject to processing of other parameters as defined in + other extensions). In particular this means that the server MUST + send all untagged responses as specified in Sections 6.3.1 and 6.3.2 + of [RFC3501]. + + After that, the server checks the UIDVALIDITY value provided by the + client. If the provided UIDVALIDITY doesn't match the UIDVALIDITY + for the mailbox being opened, then the server MUST ignore the + remaining parameters and behave as if no dynamic message data + changed. The client can discover this situation by comparing the + UIDVALIDITY value returned by the server. This behavior allows the + client not to synchronize the mailbox or decide on the best + synchronization strategy. + + Example: Attempting to resynchronize INBOX, but the provided + UIDVALIDITY parameter doesn't match the current UIDVALIDITY + value. + + C: A02 SELECT INBOX (QRESYNC (67890007 20050715194045000 + 41,43:211,214:541)) + S: * 464 EXISTS + S: * 3 RECENT + S: * OK [UIDVALIDITY 3857529045] UIDVALIDITY + S: * OK [UIDNEXT 550] Predicted next UID + S: * OK [HIGHESTMODSEQ 90060128194045007] + S: * OK [UNSEEN 12] Message 12 is first unseen + S: * FLAGS (\Answered \Flagged \Draft \Deleted \Seen) + S: * OK [PERMANENTFLAGS (\Answered \Flagged \Draft + \Deleted \Seen \*)] Permanent flags + S: A02 OK [READ-WRITE] Sorry, UIDVALIDITY mismatch + + Modification Sequence and UID Parameters: + + A server that doesn't support the persistent storage of mod-sequences + for the mailbox MUST send the OK untagged response including the + NOMODSEQ response code with every successful SELECT or EXAMINE + command, as described in [CONDSTORE]. Such a server doesn't need to + remember mod-sequences for expunged messages in the mailbox. It MUST + ignore the remaining parameters and behave as if no dynamic message + data changed. + + If the provided UIDVALIDITY matches that of the selected mailbox, the + server then checks the last known modification sequence. + + + +Melnikov, et al. Standards Track [Page 5] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + The server sends the client any pending flag changes (using FETCH + responses that MUST contain UIDs) and expunges those that have + occurred in this mailbox since the provided modification sequence. + + If the list of known UIDs was also provided, the server should only + report flag changes and expunges for the specified messages. If the + client did not provide the list of UIDs, the server acts as if the + client has specified "1:<maxuid>", where <maxuid> is the mailbox's + UIDNEXT value minus 1. If the mailbox is empty and never had any + messages in it, then lack of the list of UIDs is interpreted as an + empty set of UIDs. + + Thus, the client can process just these pending events and need not + perform a full resynchronization. Without the message sequence + number matching information, the result of this step is semantically + equivalent to the client issuing: + tag1 UID FETCH "known-uids" (FLAGS) (CHANGEDSINCE + "mod-sequence-value" VANISHED) + + Example: + C: A03 SELECT INBOX (QRESYNC (67890007 + 90060115194045000 41,43:211,214:541)) + S: * OK [CLOSED] + S: * 314 EXISTS + S: * 15 RECENT + S: * OK [UIDVALIDITY 67890007] UIDVALIDITY + S: * OK [UIDNEXT 567] Predicted next UID + S: * OK [HIGHESTMODSEQ 90060115205545359] + S: * OK [UNSEEN 7] There are some unseen messages in the mailbox + S: * FLAGS (\Answered \Flagged \Draft \Deleted \Seen) + S: * OK [PERMANENTFLAGS (\Answered \Flagged \Draft + \Deleted \Seen \*)] Permanent flags + S: * VANISHED (EARLIER) 41,43:116,118,120:211,214:540 + S: * 49 FETCH (UID 117 FLAGS (\Seen \Answered) MODSEQ + (90060115194045001)) + S: * 50 FETCH (UID 119 FLAGS (\Draft $MDNSent) MODSEQ + (90060115194045308)) + S: ... + S: * 100 FETCH (UID 541 FLAGS (\Seen $Forwarded) MODSEQ + (90060115194045001)) + S: A03 OK [READ-WRITE] mailbox selected + + Message sequence match data: + + A client MAY provide a parenthesized list of a message sequence set + and the corresponding UID sets. Both MUST be provided in ascending + order. The server uses this data to restrict the range for which it + provides expunged message information. + + + +Melnikov, et al. Standards Track [Page 6] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + Conceptually, the client provides a small sample of sequence numbers + for which it knows the corresponding UIDs. The server then compares + each sequence number and UID pair the client provides with the + current state of the mailbox. If a pair matches, then the client + knows of any expunges up to, and including, the message, and thus + will not include that range in the VANISHED response, even if the + "mod-sequence-value" provided by the client is too old for the server + to have data of when those messages were expunged. + + Thus, if the Nth message number in the first set in the list is 4, + and the Nth UID in the second set in the list is 8, and the mailbox's + fourth message has UID 8, then no UIDs equal to or less than 8 are + present in the VANISHED response. If the (N+1)th message number is + 12, and the (N+1)th UID is 24, and the (N+1)th message in the mailbox + has UID 25, then the lowest UID included in the VANISHED response + would be 9. + + In the following two examples, the server is unable to remember + expunges at all, and only UIDs with messages divisible by three are + present in the mailbox. In the first example, the client does not + use the fourth parameter; in the second, it provides it. This + example is somewhat extreme, but shows that judicious usage of the + sequence match data can save a substantial amount of bandwidth. + + Example: + C: A04 SELECT INBOX (QRESYNC (67890007 + 90060115194045000 1:29997)) + S: * 10003 EXISTS + S: * 5 RECENT + S: * OK [UIDVALIDITY 67890007] UIDVALIDITY + S: * OK [UIDNEXT 30013] Predicted next UID + S: * OK [HIGHESTMODSEQ 90060115205545359] + S: * OK [UNSEEN 7] There are some unseen messages in the mailbox + S: * FLAGS (\Answered \Flagged \Draft \Deleted \Seen) + S: * OK [PERMANENTFLAGS (\Answered \Flagged \Draft + \Deleted \Seen \*)] Permanent flags + S: * VANISHED (EARLIER) 1:2,4:5,7:8,10:11,13:14 [...] + 29998:29999,30001:30002,30004:30005,30007:30008 + S: * 9889 FETCH (UID 29667 FLAGS (\Seen \Answered) MODSEQ + (90060115194045027)) + S: * 9890 FETCH (UID 29670 FLAGS (\Draft $MDNSent) MODSEQ + (90060115194045028)) + S: ... + S: * 9999 FETCH (UID 29997 FLAGS (\Seen $Forwarded) MODSEQ + (90060115194045031)) + S: A04 OK [READ-WRITE] mailbox selected + + + + + +Melnikov, et al. Standards Track [Page 7] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + Example: + C: B04 SELECT INBOX (QRESYNC (67890007 + 90060115194045000 1:29997 (5000,7500,9000,9990:9999 15000, + 22500,27000,29970,29973,29976,29979,29982,29985,29988,29991, + 29994,29997))) + S: * 10003 EXISTS + S: * 5 RECENT + S: * OK [UIDVALIDITY 67890007] UIDVALIDITY + S: * OK [UIDNEXT 30013] Predicted next UID + S: * OK [HIGHESTMODSEQ 90060115205545359] + S: * OK [UNSEEN 7] There are some unseen messages in the mailbox + S: * FLAGS (\Answered \Flagged \Draft \Deleted \Seen) + S: * OK [PERMANENTFLAGS (\Answered \Flagged \Draft + \Deleted \Seen \*)] Permanent flags + S: * VANISHED (EARLIER) 29998:29999,30001:30002,30004:30005,30007: + 30008 + S: * 9889 FETCH (UID 29667 FLAGS (\Seen \Answered) MODSEQ + (90060115194045027)) + S: * 9890 FETCH (UID 29670 FLAGS (\Draft $MDNSent) MODSEQ + (90060115194045028)) + S: ... + S: * 9999 FETCH (UID 29997 FLAGS (\Seen $Forwarded) MODSEQ + (90060115194045031)) + S: B04 OK [READ-WRITE] mailbox selected + +3.2. VANISHED UID FETCH Modifier + + [IMAPABNF] has extended the syntax of the FETCH and UID FETCH + commands to include an optional FETCH modifier. This document + defines a new UID FETCH modifier: VANISHED. + + Note, that the VANISHED UID FETCH modifier is NOT allowed with a + FETCH command. The server MUST return a tagged BAD response if this + response is specified as a modifier to the FETCH command. + + A server MUST respond with a tagged BAD response if the VANISHED UID + FETCH modifier is specified and the client hasn't issued "ENABLE + QRESYNC" in the current connection. + + The VANISHED UID FETCH modifier MUST only be specified together with + the CHANGEDSINCE UID FETCH modifier. + + The VANISHED UID FETCH modifier instructs the server to report those + messages from the UID set parameter that have been expunged and whose + associated mod-sequence is larger than the specified mod-sequence. + That is, the client requests to be informed of messages from the + specified set that were expunged since the specified mod-sequence. + Note that the mod-sequence(s) associated with these messages were + + + +Melnikov, et al. Standards Track [Page 8] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + updated when the messages were expunged (as described above). The + expunged messages are reported using the VANISHED response as + described in Section 3.6, which MUST contain the EARLIER tag. Any + VANISHED (EARLIER) responses MUST be returned before any FETCH + responses, as otherwise the client might get confused about how + message numbers map to UIDs. + + Note: A server that receives a mod-sequence smaller than <minmodseq>, + where <minmodseq> is the value of the smallest expunged mod-sequence + it remembers minus one, MUST behave as if it was requested to report + all expunged messages from the provided UID set parameter. + + Example 1: Without the VANISHED UID FETCH modifier, a CONDSTORE-aware + client [CONDSTORE] needs to issue separate commands to learn of flag + changes and expunged messages since the last synchronization: + + C: s100 UID FETCH 300:500 (FLAGS) (CHANGEDSINCE 12345) + S: * 1 FETCH (UID 404 MODSEQ (65402) FLAGS (\Seen)) + S: * 2 FETCH (UID 406 MODSEQ (75403) FLAGS (\Deleted)) + S: * 4 FETCH (UID 408 MODSEQ (29738) FLAGS ($NoJunk + $AutoJunk $MDNSent)) + S: s100 OK FETCH completed + C: s101 UID SEARCH 300:500 + S: * SEARCH 404 406 407 408 410 412 + S: s101 OK search completed + + Where 300 and 500 are the lowest and highest UIDs from client's + cache. The second SEARCH response tells the client that the messages + with UIDs 407, 410, and 412 are still present, but their flags + haven't changed since the specified modification sequence. + + Using the VANISHED UID FETCH modifier, it is sufficient to issue only + a single command: + + C: s100 UID FETCH 300:500 (FLAGS) (CHANGEDSINCE 12345 + VANISHED) + S: * VANISHED (EARLIER) 300:310,405,411 + S: * 1 FETCH (UID 404 MODSEQ (65402) FLAGS (\Seen)) + S: * 2 FETCH (UID 406 MODSEQ (75403) FLAGS (\Deleted)) + S: * 4 FETCH (UID 408 MODSEQ (29738) FLAGS ($NoJunk + $AutoJunk $MDNSent)) + S: s100 OK FETCH completed + + + + + + + + + +Melnikov, et al. Standards Track [Page 9] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + +3.3. EXPUNGE Command + + Arguments: none + + Responses: untagged responses: EXPUNGE or VANISHED + + Result: OK - expunge completed + NO - expunge failure: can't expunge (e.g., permission denied) + BAD - command unknown or arguments invalid + + This section updates the definition of the EXPUNGE command described + in Section 6.4.3 of [RFC3501]. + + The EXPUNGE command permanently removes all messages that have the + \Deleted flag set from the currently selected mailbox. Before + returning an OK to the client, those messages that are removed are + reported using a VANISHED response or EXPUNGE responses. + + If the server is capable of storing modification sequences for the + selected mailbox, it MUST increment the per-mailbox mod-sequence if + at least one message was permanently removed due to the execution of + the EXPUNGE command. For each permanently removed message, the + server MUST remember the incremented mod-sequence and corresponding + UID. If at least one message got expunged, the server MUST send the + updated per-mailbox modification sequence using the HIGHESTMODSEQ + response code (defined in [CONDSTORE]) in the tagged OK response. + + Example: C: A202 EXPUNGE + S: * 3 EXPUNGE + S: * 3 EXPUNGE + S: * 5 EXPUNGE + S: * 8 EXPUNGE + S: A202 OK [HIGHESTMODSEQ 20010715194045319] expunged + + Note: In this example, messages 3, 4, 7, and 11 had the \Deleted flag + set. The first "* 3 EXPUNGE" reports message # 3 as expunged. The + second "* 3 EXPUNGE" reports message # 4 as expunged (the message + number got decremented due to the previous EXPUNGE response). See + the description of the EXPUNGE response in [RFC3501] for further + explanation. + + Note that if the server chooses to always send VANISHED responses + instead of EXPUNGE responses, the previous example might look like + this: + + Example: C: B202 EXPUNGE + S: * VANISHED 405,407,410,425 + S: B202 OK [HIGHESTMODSEQ 20010715194045319] expunged + + + +Melnikov, et al. Standards Track [Page 10] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + Here messages with message numbers 3, 4, 7, and 11 have respective + UIDs 405, 407, 410, and 425. + +3.4. CLOSE Command + + Arguments: none + + Responses: no specific responses for this command + + Result: OK - close completed, now in authenticated state + BAD - command unknown or arguments invalid + + This section updates the definition of the CLOSE command described in + Section 6.4.2 of [RFC3501]. + + The CLOSE command permanently removes all messages that have the + \Deleted flag set from the currently selected mailbox, and returns to + the authenticated state from the selected state. No untagged EXPUNGE + (or VANISHED) responses are sent. + + If the server is capable of storing modification sequences for the + selected mailbox, it MUST increment the per-mailbox mod-sequence if + at least one message was permanently removed due to the execution of + the CLOSE command. For each permanently removed message, the server + MUST remember the incremented mod-sequence and corresponding UID. If + at least one message got expunged, the server MUST send the updated + per-mailbox modification sequence using the HIGHESTMODSEQ response + code (defined in [CONDSTORE]) in the tagged OK response. + + Example: C: A202 CLOSE + S: A202 OK [HIGHESTMODSEQ 20010715194045319] done + +3.5. UID EXPUNGE Command + + Arguments: message set + + Responses: untagged responses: EXPUNGE or VANISHED + + Result: OK - expunge completed + NO - expunge failure: can't expunge (e.g., permission denied) + BAD - command unknown or arguments invalid + + This section updates the definition of the UID EXPUNGE command + described in Section 2.1 of [UIDPLUS]. Servers that implement both + [UIDPLUS] and QRESYNC extensions must implement UID EXPUNGE as + described in this section. + + + + + +Melnikov, et al. Standards Track [Page 11] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + The UID EXPUNGE command permanently removes from the currently + selected mailbox all messages that both have the \Deleted flag set + and have a UID that is included in the specified message set. If a + message either does not have the \Deleted flag set or has a UID that + is not included in the specified message set, it is not affected. + + This command is particularly useful for disconnected mode clients. + By using UID EXPUNGE instead of EXPUNGE when resynchronizing with the + server, the client can avoid inadvertently removing any messages that + have been marked as \Deleted by other clients between the time that + the client was last connected and the time the client resynchronizes. + + Before returning an OK to the client, those messages that are removed + are reported using a VANISHED response or EXPUNGE responses. + + If the server is capable of storing modification sequences for the + selected mailbox, it MUST increment the per-mailbox mod-sequence if + at least one message was permanently removed due to the execution of + the UID EXPUNGE command. For each permanently removed message, the + server MUST remember the incremented mod-sequence and corresponding + UID. If at least one message got expunged, the server MUST send the + updated per-mailbox modification sequence using the HIGHESTMODSEQ + response code (defined in [CONDSTORE]) in the tagged OK response. + + Example: C: . UID EXPUNGE 3000:3002 + S: * 3 EXPUNGE + S: * 3 EXPUNGE + S: * 3 EXPUNGE + S: . OK [HIGHESTMODSEQ 20010715194045319] Ok + + Note: In this example, at least messages with message numbers 3, 4, + and 5 (UIDs 3000 to 3002) had the \Deleted flag set. The first "* 3 + EXPUNGE" reports message # 3 as expunged. The second "* 3 EXPUNGE" + reports message # 4 as expunged (the message number got decremented + due to the previous EXPUNGE response). See the description of the + EXPUNGE response in [RFC3501] for further explanation. + +3.6. VANISHED Response + + Contents: an optional EARLIER tag + + list of UIDs + + The VANISHED response reports that the specified UIDs have been + permanently removed from the mailbox. This response is similar to + the EXPUNGE response [RFC3501]; however, it can return information + about multiple messages, and it returns UIDs instead of message + + + + +Melnikov, et al. Standards Track [Page 12] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + numbers. The first benefit saves bandwidth, while the second is more + convenient for clients that only use UIDs to access the IMAP server. + + The VANISHED response has the same restrictions on when it can be + sent as does the EXPUNGE response (see below). + + The VANISHED response has two forms. The first form contains the + EARLIER tag, which signifies that the response was caused by a UID + FETCH (VANISHED) or a SELECT/EXAMINE (QRESYNC) command. This + response is sent if the UID set parameter to the UID FETCH (VANISHED) + command includes UIDs of messages that are no longer in the mailbox. + When the client sees a VANISHED EARLIER response, it MUST NOT + decrement message sequence numbers for each successive message in the + mailbox. + + The second form doesn't contain the EARLIER tag and is described + below. Once a client has issued "ENABLE QRESYNC", the server SHOULD + use the VANISHED response without the EARLIER tag instead of the + EXPUNGE response. The server SHOULD continue using VANISHED in lieu + of EXPUNGE for the duration of the connection. In particular, this + affects the EXPUNGE [RFC3501] and UID EXPUNGE [UIDPLUS] commands, as + well as messages expunged in other connections. Such a VANISHED + response MUST NOT contain the EARLIER tag. + + A VANISHED response sent because of an EXPUNGE or UID EXPUNGE command + or because messages were expunged in other connections (i.e., the + VANISHED response without the EARLIER tag) also decrements the number + of messages in the mailbox; it is not necessary for the server to + send an EXISTS response with the new value. It also decrements + message sequence numbers for each successive message in the mailbox + (see the example at the end of this section). Note that a VANISHED + response caused by EXPUNGE, UID EXPUNGE, or messages expunged in + other connections SHOULD only contain UIDs for messages expunged + since the last VANISHED/EXPUNGE response sent for the currently + opened mailbox or since the mailbox was opened. That is, servers + SHOULD NOT send UIDs for previously expunged messages, unless + explicitly requested to do so by the UID FETCH (VANISHED) command. + + Note that client implementors must take care to properly decrement + the number of messages in the mailbox even if a server violates this + last SHOULD or repeats the same UID multiple times in the returned + UID set. In general, this means that a client using this extension + should either avoid using message numbers entirely, or have a + complete mapping of UIDs to message sequence numbers for the selected + mailbox. + + + + + + +Melnikov, et al. Standards Track [Page 13] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + Because clients handle the two different forms of the VANISHED + response differently, servers MUST NOT report UIDs resulting from a + UID FETCH (VANISHED) or a SELECT/EXAMINE (QRESYNC) in the same + VANISHED response as UIDs of messages expunged now (i.e., messages + expunged in other connections). Instead, the server MUST send + separate VANISHED responses: one with the EARLIER tag and one + without. + + A VANISHED response MUST NOT be sent when no command is in progress, + nor while responding to a FETCH, STORE, or SEARCH command. This rule + is necessary to prevent a loss of synchronization of message sequence + numbers between client and server. A command is not "in progress" + until the complete command has been received; in particular, a + command is not "in progress" during the negotiation of command + continuation. + + Note: UID FETCH, UID STORE, and UID SEARCH are different commands + from FETCH, STORE, and SEARCH. A VANISHED response MAY be sent + during a UID command. However, the VANISHED response MUST NOT be + sent during a UID SEARCH command that contains message numbers in the + search criteria. + + The update from the VANISHED response MUST be recorded by the client. + + Example: Let's assume that there is the following mapping between + message numbers and UIDs in the currently selected mailbox (here "X" + marks messages with the \Deleted flag set, and "x" represents UIDs + which are not relevant for the example): + + Message numbers: 1 2 3 4 5 6 7 8 9 10 11 + UIDs: x 504 505 507 508 x 510 x x x 625 + \Deleted messages: X X X X + + In the presence of the extension defined in this document: + + C: A202 EXPUNGE + S: * VANISHED 505,507,510,625 + S: A202 OK EXPUNGE completed + + Without the QRESYNC extension, the same example might look like: + + C: A202 EXPUNGE + S: * 3 EXPUNGE + S: * 3 EXPUNGE + S: * 5 EXPUNGE + S: * 8 EXPUNGE + S: A202 OK EXPUNGE completed + + + + +Melnikov, et al. Standards Track [Page 14] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + (Continuing previous example) If subsequently messages with UIDs 504 + and 508 got marked as \Deleted: + + C: A210 EXPUNGE + S: * VANISHED 504,508 + S: A210 OK EXPUNGE completed + + i.e., the last VANISHED response only contains UIDs of messages + expunged since the previous VANISHED response. + +3.7. CLOSED Response Code + + The CLOSED response code has no parameters. A server implementing + the extension defined in this document MUST return the CLOSED + response code when the currently selected mailbox is closed + implicitly using the SELECT/EXAMINE command on another mailbox. The + CLOSED response code serves as a boundary between responses for the + previously opened mailbox (which was closed) and the newly selected + mailbox: all responses before the CLOSED response code relate to the + mailbox that was closed, and all subsequent responses relate to the + newly opened mailbox. + + There is no need to return the CLOSED response code on completion of + the CLOSE or the UNSELECT [UNSELECT] command (or similar) whose + purpose is to close the currently selected mailbox without opening a + new one. + +4. Server Implementation Considerations + + This section describes a minimalist implementation, a moderate + implementation, and an example of a full implementation. + +4.1. Server Implementations That Don't Store Extra State + + Strictly speaking, a server implementation that doesn't remember mod- + sequences associated with expunged messages can be considered + compliant with this specification. Such implementations return all + expunged messages specified in the UID set of the UID FETCH + (VANISHED) command every time, without paying attention to the + specified CHANGEDSINCE mod-sequence. Such implementations are + discouraged, as they can end up returning VANISHED responses that are + bigger than the result of a UID SEARCH command for the same UID set. + + Clients that use the message sequence match data can reduce the scope + of this VANISHED response substantially in the typical case where + expunges have not happened, or happen only toward the end of the + mailbox. + + + + +Melnikov, et al. Standards Track [Page 15] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + +4.2. Server Implementations Storing Minimal State + + A server that stores the HIGHESTMODSEQ value at the time of the last + EXPUNGE can omit the VANISHED response when a client provides a + MODSEQ value that is equal to, or higher than, the current value of + this datum, that is, when there have been no EXPUNGEs. + + A client providing message sequence match data can reduce the scope + as above. In the case where there have been no expunges, the server + can ignore this data. + +4.3. Additional State Required on the Server + + When compared to the [CONDSTORE] extension, this extension requires + servers to store additional state associated with expunged messages. + Note that implementations are not required to store this state in + persistent storage; however, use of persistent storage is advisable. + + One possible way to correctly implement the extension described in + this document is to store a queue of <UID set, mod-sequence> pairs. + <UID set> can be represented as a sequence of <min UID, max UID> + pairs. + + When messages are expunged, one or more entries are added to the + queue tail. + + When the server receives a request to return messages expunged since + a given mod-sequence, it will search the queue from the tail (i.e., + going from the highest expunged mod-sequence to the lowest) until it + sees the first record with a mod-sequence less than or equal to the + given mod-sequence or it reaches the head of the queue. + + Note that indefinitely storing information about expunged messages + can cause storage and related problems for an implementation. In the + worst case, this could result in almost 64Gb of storage for each IMAP + mailbox. For example, consider an implementation that stores <min + UID, max UID, mod-sequence> triples for each range of messages + expunged at the same time. Each triple requires 16 octets: 4 octets + for each of the two UIDs, and 8 octets for the mod-sequence. Assume + that there is a mailbox containing a single message with a UID of + 2**32-1 (the maximum possible UID value), where messages had + previously existed with UIDs starting at 1, and have been expunged + one at a time. For this mailbox alone, storage is required for the + triples <1, 1, modseq1>, <2, 2, modseq2>, ..., <2**32-2, 2**32-2, + modseq4294967294>. + + + + + + +Melnikov, et al. Standards Track [Page 16] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + Hence, implementations are encouraged to adopt strategies to protect + against such storage problems, such as limiting the size of the queue + used to store mod-sequences for expunged messages and "expiring" + older records when this limit is reached. When the selected + implementation-specific queue limit is reached, the oldest record(s) + are deleted from the queue (note that such records are located at the + queue head). For all such "expired" records, the server needs to + store a single mod-sequence, which is the highest mod-sequence for + all "expired" expunged messages. + + Note that if the client provides the message sequence match data, + this can heavily reduce the data cost of sending a complete set of + missing UIDs; thus, reducing the problems for clients if a server is + unable to persist much of this queue. If the queue contains data + back to the requested mod-sequence, this data can be ignored. + + Also, note that if the UIDVALIDITY of the mailbox changes or if the + mailbox is deleted, then any state associated with expunged messages + doesn't need to be preserved and SHOULD be deleted. + +5. Updated Synchronization Sequence + + This section updates the description of optimized synchronization in + Section 6.1 of the [IMAP-DISC]. + + An advanced disconnected mail client should use the QRESYNC and + [CONDSTORE] extensions when they are supported by the server. The + client uses the value from the HIGHESTMODSEQ OK response code + received on mailbox opening to determine if it needs to + resynchronize. Once the synchronization is complete, it MUST cache + the received value (unless the mailbox UIDVALIDITY value has changed; + see below). The client MUST update its copy of the HIGHESTMODSEQ + value whenever the server sends a subsequent HIGHESTMODSEQ OK + response code. + + After completing a full synchronization, the client MUST also take + note of any unsolicited MODSEQ FETCH data items received from the + server. Whenever the client receives a tagged response to a command, + it calculates the highest value among all MODSEQ FETCH data items + received since the last tagged response. If this value is bigger + than the client's copy of the HIGHESTMODSEQ value, then the client + MUST use this value as its new HIGHESTMODSEQ value. + + Note: It is not safe to update the client's copy of the HIGHESTMODSEQ + value with a MODSEQ FETCH data item value as soon as it is received + because servers are not required to send MODSEQ FETCH data items in + increasing modseqence order. This can lead to the client missing + some changes in case of connectivity loss. + + + +Melnikov, et al. Standards Track [Page 17] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + When opening the mailbox for synchronization, the client uses the + QRESYNC parameter to the SELECT/EXAMINE command. The QRESYNC + parameter is followed by the UIDVALIDITY and mailbox HIGHESTMODSEQ + values, as known to the client. It can be optionally followed by the + set of UIDs, for example, if the client is only interested in partial + synchronization of the mailbox. The client may also transmit a list + containing its knowledge of message numbers. + + If the SELECT/EXAMINE command is successful, the client compares + UIDVALIDITY as described in step d)1) in Section 3 of the + [IMAP-DISC]. If the cached UIDVALIDITY value matches the one + returned by the server and the server also returns the HIGHESTMODSEQ + response code, then the server reports expunged messages and returns + flag changes for all messages specified by the client in the UID set + parameter (or for all messages in the mailbox, if the client omitted + the UID set parameter). At this point, the client is synchronized, + except for maybe the new messages. + + If upon a successful SELECT/EXAMINE (QRESYNC) command the client + receives a NOMODSEQ OK untagged response (instead of the + HIGHESTMODSEQ response code), it MUST remove the last known + HIGHESTMODSEQ value from its cache and follow the more general + instructions in Section 3 of the [IMAP-DISC]. + + At this point, the client is in sync with the server regarding old + messages. This client can now fetch information about new messages + (if requested by the user). + + Step d) ("Server-to-client synchronization") in Section 4 of the + [IMAP-DISC] in the presence of the QRESYNC & CONDSTORE extensions is + amended as follows: + + d) "Server-to-client synchronization" -- for each mailbox that + requires synchronization, do the following: + + 1a) Check the mailbox UIDVALIDITY (see Section 4.1 of the [IMAP-DISC] + for more details) after issuing SELECT/EXAMINE (QRESYNC) command. + + If the UIDVALIDITY value returned by the server differs, the + client MUST + + * empty the local cache of that mailbox; + + * "forget" the cached HIGHESTMODSEQ value for the mailbox; + + + + + + + +Melnikov, et al. Standards Track [Page 18] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + * remove any pending "actions" which refer to UIDs in that + mailbox. Note, this doesn't affect actions performed on + client generated fake UIDs (see Section 5 of the + [IMAP-DISC]); + + 2) Fetch the current "descriptors"; + + I) Discover new messages. + + 3) Fetch the bodies of any "interesting" messages that the client + doesn't already have. + + Example: The UIDVALIDITY value is the same, but the HIGHESTMODSEQ + value has changed on the server while the client was + offline: + + C: A142 SELECT INBOX (QRESYNC (3857529045 20010715194032001 1:198)) + S: * 172 EXISTS + S: * 1 RECENT + S: * OK [UNSEEN 12] Message 12 is first unseen + S: * OK [UIDVALIDITY 3857529045] UIDs valid + S: * OK [UIDNEXT 201] Predicted next UID + S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) + S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited + S: * OK [HIGHESTMODSEQ 20010715194045007] + S: * VANISHED (EARLIER) 1:5,7:8,10:15 + S: * 2 FETCH (UID 6 MODSEQ (20010715205008000) + FLAGS (\Deleted)) + S: * 5 FETCH (UID 9 MODSEQ (20010715195517000) + FLAGS ($NoJunk $AutoJunk $MDNSent)) + ... + S: A142 OK [READ-WRITE] SELECT completed + +6. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [ABNF]. + + Non-terminals referenced but not defined below are as defined by + [RFC3501], [CONDSTORE], or [IMAPABNF]. + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of upper or lower case characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. + + + + + + +Melnikov, et al. Standards Track [Page 19] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + + capability =/ "QRESYNC" + + select-param = "QRESYNC" SP "(" uidvalidity SP + mod-sequence-value [SP known-uids] + [SP seq-match-data] ")" + ;; conforms to the generic select-param + ;; syntax defined in [IMAPABNF] + + seq-match-data = "(" known-sequence-set SP known-uid-set ")" + + uidvalidity = nz-number + + known-uids = sequence-set + ;; sequence of UIDs, "*" is not allowed + + known-sequence-set = sequence-set + ;; set of message numbers corresponding to + ;; the UIDs in known-uid-set, in ascending order. + ;; * is not allowed. + + known-uid-set = sequence-set + ;; set of UIDs corresponding to the messages in + ;; known-sequence-set, in ascending order. + ;; * is not allowed. + + message-data =/ expunged-resp + + expunged-resp = "VANISHED" [SP "(EARLIER)"] SP known-uids + + rexpunges-fetch-mod = "VANISHED" + ;; VANISHED UID FETCH modifier conforms + ;; to the fetch-modifier syntax + ;; defined in [IMAPABNF]. It is only + ;; allowed in the UID FETCH command. + + resp-text-code =/ "CLOSED" + +7. Security Considerations + + As always, it is important to thoroughly test clients and servers + implementing this extension, as it changes how the server reports + expunged messages to the client. + + Security considerations relevant to [CONDSTORE] are relevant to this + extension. + + This document doesn't raise any new security concerns not already + raised by [CONDSTORE] or [RFC3501]. + + + +Melnikov, et al. Standards Track [Page 20] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + +8. IANA Considerations + + IMAP4 capabilities are registered by publishing a standards track or + IESG approved experimental RFC. The registry is currently located + at: + + http://www.iana.org/assignments/imap4-capabilities + + This document defines the QRESYNC IMAP capability. IANA has added + this capability to the registry. + +9. Acknowledgments + + Thanks to Steve Hole, Cyrus Daboo, and Michael Wener for encouraging + creation of this document. + + Valuable comments, both in agreement and in dissent, were received + from Timo Sirainen, Michael Wener, Randall Gellens, Arnt Gulbrandsen, + Chris Newman, Peter Coates, Mark Crispin, Elwyn Davies, Dan Karp, + Eric Rescorla, and Mike Zraly. + + This document takes substantial text from [RFC3501] by Mark Crispin. + +10. References + +10.1. Normative References + + [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + + [CONDSTORE] Melnikov, A. and S. Hole, "IMAP Extension for + Conditional STORE Operation or Quick Flag Changes + Resynchronization", RFC 4551, June 2006. + + [ENABLE] Gulbrandsen, A., Ed. and A. Melnikov, Ed., "The IMAP + ENABLE Extension", RFC 5161, March 2008. + + [IMAPABNF] Melnikov, A. and C. Daboo, "Collected Extensions to + IMAP4 ABNF", RFC 4466, April 2006. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [UIDPLUS] Crispin, M., "Internet Message Access Protocol (IMAP) - + UIDPLUS extension", RFC 4315, December 2005. + + + +Melnikov, et al. Standards Track [Page 21] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + +10.2. Informative References + + [IMAP-DISC] Melnikov, A., Ed., "Synchronization Operations For + Disconnected Imap4 Clients", RFC 4549, June 2006. + + [UNSELECT] Melnikov, A., "Internet Message Access Protocol (IMAP) + UNSELECT command", RFC 3691, February 2004. + +Authors' Addresses + + Alexey Melnikov + Isode Ltd + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: Alexey.Melnikov@isode.com + + + Dave Cridland + Isode Ltd + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: dave.cridland@isode.com + + + Corby Wilson + Nokia + 5 Wayside Rd. + Burlington, MA 01803 + USA + + EMail: corby@computer.org + + + + + + + + + + + + + + +Melnikov, et al. Standards Track [Page 22] + +RFC 5162 IMAP Quick Mailbox Resync March 2008 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2008). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Melnikov, et al. Standards Track [Page 23] + diff --git a/imap/docs/rfc/rfc5234.txt b/imap/docs/rfc/rfc5234.txt new file mode 100644 index 00000000..42bb44ca --- /dev/null +++ b/imap/docs/rfc/rfc5234.txt @@ -0,0 +1,899 @@ + + + + + + +Network Working Group D. Crocker, Ed. +Request for Comments: 5234 Brandenburg InternetWorking +STD: 68 P. Overell +Obsoletes: 4234 THUS plc. +Category: Standards Track January 2008 + + + Augmented BNF for Syntax Specifications: ABNF + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + Internet technical specifications often need to define a formal + syntax. Over the years, a modified version of Backus-Naur Form + (BNF), called Augmented BNF (ABNF), has been popular among many + Internet specifications. The current specification documents ABNF. + It balances compactness and simplicity with reasonable + representational power. The differences between standard BNF and + ABNF involve naming rules, repetition, alternatives, order- + independence, and value ranges. This specification also supplies + additional rule definitions and encoding for a core lexical analyzer + of the type common to several Internet specifications. + + + + + + + + + + + + + + + + + + + + + + +Crocker & Overell Standards Track [Page 1] + +RFC 5234 ABNF January 2008 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Rule Definition . . . . . . . . . . . . . . . . . . . . . . . 3 + 2.1. Rule Naming . . . . . . . . . . . . . . . . . . . . . . . 3 + 2.2. Rule Form . . . . . . . . . . . . . . . . . . . . . . . . 4 + 2.3. Terminal Values . . . . . . . . . . . . . . . . . . . . . 4 + 2.4. External Encodings . . . . . . . . . . . . . . . . . . . . 6 + 3. Operators . . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 3.1. Concatenation: Rule1 Rule2 . . . . . . . . . . . . . . . 6 + 3.2. Alternatives: Rule1 / Rule2 . . . . . . . . . . . . . . . 7 + 3.3. Incremental Alternatives: Rule1 =/ Rule2 . . . . . . . . . 7 + 3.4. Value Range Alternatives: %c##-## . . . . . . . . . . . . 8 + 3.5. Sequence Group: (Rule1 Rule2) . . . . . . . . . . . . . . 8 + 3.6. Variable Repetition: *Rule . . . . . . . . . . . . . . . 9 + 3.7. Specific Repetition: nRule . . . . . . . . . . . . . . . 9 + 3.8. Optional Sequence: [RULE] . . . . . . . . . . . . . . . . 9 + 3.9. Comment: ; Comment . . . . . . . . . . . . . . . . . . . 9 + 3.10. Operator Precedence . . . . . . . . . . . . . . . . . . . 10 + 4. ABNF Definition of ABNF . . . . . . . . . . . . . . . . . . . 10 + 5. Security Considerations . . . . . . . . . . . . . . . . . . . 12 + 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 + 6.1. Normative References . . . . . . . . . . . . . . . . . . . 12 + 6.2. Informative References . . . . . . . . . . . . . . . . . . 12 + Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 13 + Appendix B. Core ABNF of ABNF . . . . . . . . . . . . . . . . . . 13 + B.1. Core Rules . . . . . . . . . . . . . . . . . . . . . . . . 13 + B.2. Common Encoding . . . . . . . . . . . . . . . . . . . . . 15 + + + + + + + + + + + + + + + + + + + + + + + +Crocker & Overell Standards Track [Page 2] + +RFC 5234 ABNF January 2008 + + +1. Introduction + + Internet technical specifications often need to define a formal + syntax and are free to employ whatever notation their authors deem + useful. Over the years, a modified version of Backus-Naur Form + (BNF), called Augmented BNF (ABNF), has been popular among many + Internet specifications. It balances compactness and simplicity with + reasonable representational power. In the early days of the Arpanet, + each specification contained its own definition of ABNF. This + included the email specifications, [RFC733] and then [RFC822], which + came to be the common citations for defining ABNF. The current + document separates those definitions to permit selective reference. + Predictably, it also provides some modifications and enhancements. + + The differences between standard BNF and ABNF involve naming rules, + repetition, alternatives, order-independence, and value ranges. + Appendix B supplies rule definitions and encoding for a core lexical + analyzer of the type common to several Internet specifications. It + is provided as a convenience and is otherwise separate from the meta + language defined in the body of this document, and separate from its + formal status. + +2. Rule Definition + +2.1. Rule Naming + + The name of a rule is simply the name itself, that is, a sequence of + characters, beginning with an alphabetic character, and followed by a + combination of alphabetics, digits, and hyphens (dashes). + + NOTE: + + Rule names are case insensitive. + + The names <rulename>, <Rulename>, <RULENAME>, and <rUlENamE> all + refer to the same rule. + + Unlike original BNF, angle brackets ("<", ">") are not required. + However, angle brackets may be used around a rule name whenever their + presence facilitates in discerning the use of a rule name. This is + typically restricted to rule name references in free-form prose, or + to distinguish partial rules that combine into a string not separated + by white space, such as shown in the discussion about repetition, + below. + + + + + + + +Crocker & Overell Standards Track [Page 3] + +RFC 5234 ABNF January 2008 + + +2.2. Rule Form + + A rule is defined by the following sequence: + + name = elements crlf + + where <name> is the name of the rule, <elements> is one or more rule + names or terminal specifications, and <crlf> is the end-of-line + indicator (carriage return followed by line feed). The equal sign + separates the name from the definition of the rule. The elements + form a sequence of one or more rule names and/or value definitions, + combined according to the various operators defined in this document, + such as alternative and repetition. + + For visual ease, rule definitions are left aligned. When a rule + requires multiple lines, the continuation lines are indented. The + left alignment and indentation are relative to the first lines of the + ABNF rules and need not match the left margin of the document. + +2.3. Terminal Values + + Rules resolve into a string of terminal values, sometimes called + characters. In ABNF, a character is merely a non-negative integer. + In certain contexts, a specific mapping (encoding) of values into a + character set (such as ASCII) will be specified. + + Terminals are specified by one or more numeric characters, with the + base interpretation of those characters indicated explicitly. The + following bases are currently defined: + + b = binary + + d = decimal + + x = hexadecimal + + Hence: + + CR = %d13 + + CR = %x0D + + respectively specify the decimal and hexadecimal representation of + [US-ASCII] for carriage return. + + + + + + + +Crocker & Overell Standards Track [Page 4] + +RFC 5234 ABNF January 2008 + + + A concatenated string of such values is specified compactly, using a + period (".") to indicate a separation of characters within that + value. Hence: + + CRLF = %d13.10 + + ABNF permits the specification of literal text strings directly, + enclosed in quotation marks. Hence: + + command = "command string" + + Literal text strings are interpreted as a concatenated set of + printable characters. + + NOTE: + + ABNF strings are case insensitive and the character set for these + strings is US-ASCII. + + Hence: + + rulename = "abc" + + and: + + rulename = "aBc" + + will match "abc", "Abc", "aBc", "abC", "ABc", "aBC", "AbC", and + "ABC". + + To specify a rule that is case sensitive, specify the characters + individually. + + For example: + + rulename = %d97 %d98 %d99 + + or + + rulename = %d97.98.99 + + will match only the string that comprises only the lowercase + characters, abc. + + + + + + + + +Crocker & Overell Standards Track [Page 5] + +RFC 5234 ABNF January 2008 + + +2.4. External Encodings + + External representations of terminal value characters will vary + according to constraints in the storage or transmission environment. + Hence, the same ABNF-based grammar may have multiple external + encodings, such as one for a 7-bit US-ASCII environment, another for + a binary octet environment, and still a different one when 16-bit + Unicode is used. Encoding details are beyond the scope of ABNF, + although Appendix B provides definitions for a 7-bit US-ASCII + environment as has been common to much of the Internet. + + By separating external encoding from the syntax, it is intended that + alternate encoding environments can be used for the same syntax. + +3. Operators + +3.1. Concatenation: Rule1 Rule2 + + A rule can define a simple, ordered string of values (i.e., a + concatenation of contiguous characters) by listing a sequence of rule + names. For example: + + foo = %x61 ; a + + bar = %x62 ; b + + mumble = foo bar foo + + So that the rule <mumble> matches the lowercase string "aba". + + Linear white space: Concatenation is at the core of the ABNF parsing + model. A string of contiguous characters (values) is parsed + according to the rules defined in ABNF. For Internet specifications, + there is some history of permitting linear white space (space and + horizontal tab) to be freely and implicitly interspersed around major + constructs, such as delimiting special characters or atomic strings. + + NOTE: + + This specification for ABNF does not provide for implicit + specification of linear white space. + + Any grammar that wishes to permit linear white space around + delimiters or string segments must specify it explicitly. It is + often useful to provide for such white space in "core" rules that are + then used variously among higher-level rules. The "core" rules might + be formed into a lexical analyzer or simply be part of the main + ruleset. + + + +Crocker & Overell Standards Track [Page 6] + +RFC 5234 ABNF January 2008 + + +3.2. Alternatives: Rule1 / Rule2 + + Elements separated by a forward slash ("/") are alternatives. + Therefore, + + foo / bar + + will accept <foo> or <bar>. + + NOTE: + + A quoted string containing alphabetic characters is a special form + for specifying alternative characters and is interpreted as a non- + terminal representing the set of combinatorial strings with the + contained characters, in the specified order but with any mixture + of upper- and lowercase. + +3.3. Incremental Alternatives: Rule1 =/ Rule2 + + It is sometimes convenient to specify a list of alternatives in + fragments. That is, an initial rule may match one or more + alternatives, with later rule definitions adding to the set of + alternatives. This is particularly useful for otherwise independent + specifications that derive from the same parent ruleset, such as + often occurs with parameter lists. ABNF permits this incremental + definition through the construct: + + oldrule =/ additional-alternatives + + So that the ruleset + + ruleset = alt1 / alt2 + + ruleset =/ alt3 + + ruleset =/ alt4 / alt5 + + is the same as specifying + + ruleset = alt1 / alt2 / alt3 / alt4 / alt5 + + + + + + + + + + + +Crocker & Overell Standards Track [Page 7] + +RFC 5234 ABNF January 2008 + + +3.4. Value Range Alternatives: %c##-## + + A range of alternative numeric values can be specified compactly, + using a dash ("-") to indicate the range of alternative values. + Hence: + + DIGIT = %x30-39 + + is equivalent to: + + DIGIT = "0" / "1" / "2" / "3" / "4" / "5" / "6" / + + "7" / "8" / "9" + + Concatenated numeric values and numeric value ranges cannot be + specified in the same string. A numeric value may use the dotted + notation for concatenation or it may use the dash notation to specify + one value range. Hence, to specify one printable character between + end-of-line sequences, the specification could be: + + char-line = %x0D.0A %x20-7E %x0D.0A + +3.5. Sequence Group: (Rule1 Rule2) + + Elements enclosed in parentheses are treated as a single element, + whose contents are strictly ordered. Thus, + + elem (foo / bar) blat + + matches (elem foo blat) or (elem bar blat), and + + elem foo / bar blat + + matches (elem foo) or (bar blat). + + NOTE: + + It is strongly advised that grouping notation be used, rather than + relying on the proper reading of "bare" alternations, when + alternatives consist of multiple rule names or literals. + + Hence, it is recommended that the following form be used: + + (elem foo) / (bar blat) + + It will avoid misinterpretation by casual readers. + + + + + +Crocker & Overell Standards Track [Page 8] + +RFC 5234 ABNF January 2008 + + + The sequence group notation is also used within free text to set off + an element sequence from the prose. + +3.6. Variable Repetition: *Rule + + The operator "*" preceding an element indicates repetition. The full + form is: + + <a>*<b>element + + where <a> and <b> are optional decimal values, indicating at least + <a> and at most <b> occurrences of the element. + + Default values are 0 and infinity so that *<element> allows any + number, including zero; 1*<element> requires at least one; + 3*3<element> allows exactly 3; and 1*2<element> allows one or two. + +3.7. Specific Repetition: nRule + + A rule of the form: + + <n>element + + is equivalent to + + <n>*<n>element + + That is, exactly <n> occurrences of <element>. Thus, 2DIGIT is a + 2-digit number, and 3ALPHA is a string of three alphabetic + characters. + +3.8. Optional Sequence: [RULE] + + Square brackets enclose an optional element sequence: + + [foo bar] + + is equivalent to + + *1(foo bar). + +3.9. Comment: ; Comment + + A semicolon starts a comment that continues to the end of line. This + is a simple way of including useful notes in parallel with the + specifications. + + + + + +Crocker & Overell Standards Track [Page 9] + +RFC 5234 ABNF January 2008 + + +3.10. Operator Precedence + + The various mechanisms described above have the following precedence, + from highest (binding tightest) at the top, to lowest (loosest) at + the bottom: + + Rule name, prose-val, Terminal value + + Comment + + Value range + + Repetition + + Grouping, Optional + + Concatenation + + Alternative + + Use of the alternative operator, freely mixed with concatenations, + can be confusing. + + Again, it is recommended that the grouping operator be used to + make explicit concatenation groups. + +4. ABNF Definition of ABNF + + NOTES: + + 1. This syntax requires a formatting of rules that is relatively + strict. Hence, the version of a ruleset included in a + specification might need preprocessing to ensure that it can + be interpreted by an ABNF parser. + + 2. This syntax uses the rules provided in Appendix B. + + + rulelist = 1*( rule / (*c-wsp c-nl) ) + + rule = rulename defined-as elements c-nl + ; continues if next line starts + ; with white space + + rulename = ALPHA *(ALPHA / DIGIT / "-") + + + + + + +Crocker & Overell Standards Track [Page 10] + +RFC 5234 ABNF January 2008 + + + defined-as = *c-wsp ("=" / "=/") *c-wsp + ; basic rules definition and + ; incremental alternatives + + elements = alternation *c-wsp + + c-wsp = WSP / (c-nl WSP) + + c-nl = comment / CRLF + ; comment or newline + + comment = ";" *(WSP / VCHAR) CRLF + + alternation = concatenation + *(*c-wsp "/" *c-wsp concatenation) + + concatenation = repetition *(1*c-wsp repetition) + + repetition = [repeat] element + + repeat = 1*DIGIT / (*DIGIT "*" *DIGIT) + + element = rulename / group / option / + char-val / num-val / prose-val + + group = "(" *c-wsp alternation *c-wsp ")" + + option = "[" *c-wsp alternation *c-wsp "]" + + char-val = DQUOTE *(%x20-21 / %x23-7E) DQUOTE + ; quoted string of SP and VCHAR + ; without DQUOTE + + num-val = "%" (bin-val / dec-val / hex-val) + + bin-val = "b" 1*BIT + [ 1*("." 1*BIT) / ("-" 1*BIT) ] + ; series of concatenated bit values + ; or single ONEOF range + + dec-val = "d" 1*DIGIT + [ 1*("." 1*DIGIT) / ("-" 1*DIGIT) ] + + hex-val = "x" 1*HEXDIG + [ 1*("." 1*HEXDIG) / ("-" 1*HEXDIG) ] + + + + + + +Crocker & Overell Standards Track [Page 11] + +RFC 5234 ABNF January 2008 + + + prose-val = "<" *(%x20-3D / %x3F-7E) ">" + ; bracketed string of SP and VCHAR + ; without angles + ; prose description, to be used as + ; last resort + +5. Security Considerations + + Security is truly believed to be irrelevant to this document. + +6. References + +6.1. Normative References + + [US-ASCII] American National Standards Institute, "Coded Character + Set -- 7-bit American Standard Code for Information + Interchange", ANSI X3.4, 1986. + +6.2. Informative References + + [RFC733] Crocker, D., Vittal, J., Pogran, K., and D. Henderson, + "Standard for the format of ARPA network text messages", + RFC 733, November 1977. + + [RFC822] Crocker, D., "Standard for the format of ARPA Internet + text messages", STD 11, RFC 822, August 1982. + + + + + + + + + + + + + + + + + + + + + + + + + +Crocker & Overell Standards Track [Page 12] + +RFC 5234 ABNF January 2008 + + +Appendix A. Acknowledgements + + The syntax for ABNF was originally specified in RFC 733. Ken L. + Harrenstien, of SRI International, was responsible for re-coding the + BNF into an Augmented BNF that makes the representation smaller and + easier to understand. + + This recent project began as a simple effort to cull out the portion + of RFC 822 that has been repeatedly cited by non-email specification + writers, namely the description of Augmented BNF. Rather than simply + and blindly converting the existing text into a separate document, + the working group chose to give careful consideration to the + deficiencies, as well as benefits, of the existing specification and + related specifications made available over the last 15 years, and + therefore to pursue enhancement. This turned the project into + something rather more ambitious than was first intended. + Interestingly, the result is not massively different from that + original, although decisions, such as removing the list notation, + came as a surprise. + + This "separated" version of the specification was part of the DRUMS + working group, with significant contributions from Jerome Abela, + Harald Alvestrand, Robert Elz, Roger Fajman, Aviva Garrett, Tom + Harsch, Dan Kohn, Bill McQuillan, Keith Moore, Chris Newman, Pete + Resnick, and Henning Schulzrinne. + + Julian Reschke warrants a special thanks for converting the Draft + Standard version to XML source form. + +Appendix B. Core ABNF of ABNF + + This appendix contains some basic rules that are in common use. + Basic rules are in uppercase. Note that these rules are only valid + for ABNF encoded in 7-bit ASCII or in characters sets that are a + superset of 7-bit ASCII. + +B.1. Core Rules + + Certain basic rules are in uppercase, such as SP, HTAB, CRLF, DIGIT, + ALPHA, etc. + + ALPHA = %x41-5A / %x61-7A ; A-Z / a-z + + BIT = "0" / "1" + + CHAR = %x01-7F + ; any 7-bit US-ASCII character, + ; excluding NUL + + + +Crocker & Overell Standards Track [Page 13] + +RFC 5234 ABNF January 2008 + + + CR = %x0D + ; carriage return + + CRLF = CR LF + ; Internet standard newline + + CTL = %x00-1F / %x7F + ; controls + + DIGIT = %x30-39 + ; 0-9 + + DQUOTE = %x22 + ; " (Double Quote) + + HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" + + HTAB = %x09 + ; horizontal tab + + LF = %x0A + ; linefeed + + LWSP = *(WSP / CRLF WSP) + ; Use of this linear-white-space rule + ; permits lines containing only white + ; space that are no longer legal in + ; mail headers and have caused + ; interoperability problems in other + ; contexts. + ; Do not use when defining mail + ; headers and use with caution in + ; other contexts. + + OCTET = %x00-FF + ; 8 bits of data + + SP = %x20 + + VCHAR = %x21-7E + ; visible (printing) characters + + WSP = SP / HTAB + ; white space + + + + + + + +Crocker & Overell Standards Track [Page 14] + +RFC 5234 ABNF January 2008 + + +B.2. Common Encoding + + Externally, data are represented as "network virtual ASCII" (namely, + 7-bit US-ASCII in an 8-bit field), with the high (8th) bit set to + zero. A string of values is in "network byte order", in which the + higher-valued bytes are represented on the left-hand side and are + sent over the network first. + +Authors' Addresses + + Dave Crocker (editor) + Brandenburg InternetWorking + 675 Spruce Dr. + Sunnyvale, CA 94086 + US + + Phone: +1.408.246.8253 + EMail: dcrocker@bbiw.net + + + Paul Overell + THUS plc. + 1/2 Berkeley Square, + 99 Berkeley Street + Glasgow G3 7HR + UK + + EMail: paul.overell@thus.net + + + + + + + + + + + + + + + + + + + + + + + +Crocker & Overell Standards Track [Page 15] + +RFC 5234 ABNF January 2008 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2008). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Crocker & Overell Standards Track [Page 16] + diff --git a/imap/docs/rfc/rfc5255.txt b/imap/docs/rfc/rfc5255.txt new file mode 100644 index 00000000..df76402c --- /dev/null +++ b/imap/docs/rfc/rfc5255.txt @@ -0,0 +1,1123 @@ + + + + + + +Network Working Group C. Newman +Request for Comments: 5255 Sun Microsystems +Category: Standards Track A. Gulbrandsen + Oryx Mail Systems GmhH + A. Melnikov + Isode Limited + June 2008 + + + Internet Message Access Protocol Internationalization + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + Internet Message Access Protocol (IMAP) version 4rev1 has basic + support for non-ASCII characters in mailbox names and search + substrings. It also supports non-ASCII message headers and content + encoded as specified by Multipurpose Internet Mail Extensions (MIME). + This specification defines a collection of IMAP extensions that + improve international support including language negotiation for + international error text, translations for namespace prefixes, and + comparator negotiation for search, sort, and thread. + + + + + + + + + + + + + + + + + + + + + + +Newman, et al. Standards Track [Page 1] + +RFC 5255 IMAP Internationalization June 2008 + + +Table of Contents + + 1. Introduction ....................................................3 + 2. Conventions Used in This Document ...............................3 + 3. LANGUAGE Extension ..............................................3 + 3.1. LANGUAGE Extension Requirements ............................4 + 3.2. LANGUAGE Command ...........................................4 + 3.3. LANGUAGE Response ..........................................6 + 3.4. TRANSLATION Extension to the NAMESPACE Response ............7 + 3.5. Formal Syntax ..............................................8 + 4. I18NLEVEL=1 and I18NLEVEL=2 Extensions ..........................9 + 4.1. Introduction and Overview ..................................9 + 4.2. Requirements Common to Both I18NLEVEL=1 and I18NLEVEL=2 ....9 + 4.3. I18NLEVEL=1 Extension Requirements ........................10 + 4.4. I18NLEVEL=2 Extension Requirements ........................10 + 4.5. Compatibility Notes .......................................11 + 4.6. Comparators and Character Encodings .......................11 + 4.7. COMPARATOR Command ........................................13 + 4.8. COMPARATOR Response .......................................14 + 4.9. BADCOMPARATOR Response Code ...............................14 + 4.10. Formal Syntax ............................................14 + 5. Other IMAP Internationalization Issues .........................15 + 5.1. Unicode Userids and Passwords .............................15 + 5.2. UTF-8 Mailbox Names .......................................15 + 5.3. UTF-8 Domains, Addresses, and Mail Headers ................15 + 6. IANA Considerations ............................................16 + 7. Security Considerations ........................................16 + 8. Acknowledgements ...............................................16 + 9. Relevant Sources of Documents for Internationalized IMAP + Implementations ................................................17 + 10. Normative References ..........................................17 + 11. Informative References ........................................18 + + + + + + + + + + + + + + + + + + + +Newman, et al. Standards Track [Page 2] + +RFC 5255 IMAP Internationalization June 2008 + + +1. Introduction + + This specification defines two IMAP4rev1 [RFC3501] extensions to + enhance international support. These extensions can be advertised + and implemented separately. + + The LANGUAGE extension allows the client to request a suitable + language for protocol error messages and in combination with the + NAMESPACE extension [RFC2342] enables namespace translations. + + The I18NLEVEL=2 extension allows the client to request a suitable + collation that will modify the behavior of the base specification's + SEARCH command as well as the SORT and THREAD extensions [SORT]. + This leverages the collation registry [RFC4790]. The I18NLEVEL=1 + extension updates SEARCH/SORT/THREAD to use i;unicode-casemap + comparator, as defined in [UCM]. I18NLEVEL=1 is a simpler version of + I18NLEVEL=2 with no ability to select a different collation. + +2. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + The formal syntax uses the Augmented Backus-Naur Form (ABNF) + [RFC5234] notation including the core rules defined in Appendix A. + + The UTF-8-related productions are defined in [RFC3629]. + + In examples, "C:" and "S:" indicate lines sent by the client and + server respectively. If a single "C:" or "S:" label applies to + multiple lines, then the line breaks between those lines are for + editorial clarity only and are not part of the actual protocol + exchange. + +3. LANGUAGE Extension + + IMAP allows server responses to include human-readable text that in + many cases needs to be presented to the user. But that text is + limited to US-ASCII by the IMAP specification [RFC3501] in order to + preserve backwards compatibility with deployed IMAP implementations. + This section specifies a way for an IMAP client to negotiate which + language the server should use when sending human-readable text. + + + + + + + + +Newman, et al. Standards Track [Page 3] + +RFC 5255 IMAP Internationalization June 2008 + + + The LANGUAGE extension only provides a mechanism for altering fixed + server strings such as response text and NAMESPACE folder names. + Assigning localized language aliases to shared mailboxes would be + done with a separate mechanism such as the proposed METADATA + extension (see [METADATA]). + +3.1. LANGUAGE Extension Requirements + + IMAP servers that support this extension MUST list the keyword + LANGUAGE in their CAPABILITY response as well as in the greeting + CAPABILITY data. + + A server that advertises this extension MUST use the language + "i-default" as described in [RFC2277] as its default language until + another supported language is negotiated by the client. A server + MUST include "i-default" as one of its supported languages. IMAP + servers SHOULD NOT advertise the LANGUAGE extension if they discover + that they only support "i-default". + + Clients and servers that support this extension MUST also support the + NAMESPACE extension [RFC2342]. + + The LANGUAGE command is valid in all states. Clients SHOULD issue + LANGUAGE before authentication, since some servers send valuable user + information as part of authentication (e.g., "password is correct, + but expired"). If a security layer (such as SASL or TLS) is + subsequently negotiated by the client, it MUST re-issue the LANGUAGE + command in order to make sure that no previous active attack (if any) + on LANGUAGE negotiation has effect on subsequent error messages. + (See Section 7 for a more detailed explanation of the attack.) + +3.2. LANGUAGE Command + + Arguments: Optional language range arguments. + + Response: A possible LANGUAGE response (see Section 3.3). + A possible NAMESPACE response (see Section 3.4). + + Result: OK - Command completed + NO - Could not complete command + BAD - Arguments invalid + + The LANGUAGE command requests that human-readable text emitted by the + server be localized to a language matching one of the language range + argument as described by Section 2 of [RFC4647]. + + + + + + +Newman, et al. Standards Track [Page 4] + +RFC 5255 IMAP Internationalization June 2008 + + + If the command succeeds, the server will return human-readable + responses in the first supported language specified. These responses + will be in UTF-8 [RFC3629]. The server MUST send a LANGUAGE response + specifying the language used, and the change takes effect immediately + after the LANGUAGE response. + + If the command fails, the server continues to return human-readable + responses in the language it was previously using. + + The special "default" language range argument indicates a request to + use a language designated as preferred by the server administrator. + The preferred language MAY vary based on the currently active user. + + If a language range does not match a known language tag exactly but + does match a language by the rules of [RFC4647], the server MUST send + an untagged LANGUAGE response indicating the language selected. + + If there aren't any arguments, the server SHOULD send an untagged + LANGUAGE response listing the languages it supports. If the server + is unable to enumerate the list of languages it supports it MAY + return a tagged NO response to the enumeration request. If, after + receiving a LANGUAGE request, the server discovers that it doesn't + support any language other than i-default, it MUST return a tagged NO + response to the enumeration request. + + < The server defaults to using English i-default responses until + the user explicitly changes the language. > + + C: A001 LOGIN KAREN PASSWORD + S: A001 OK LOGIN completed + + < Client requested MUL language, which no server supports. > + + C: A002 LANGUAGE MUL + S: A002 NO Unsupported language MUL + + < A LANGUAGE command with no arguments is a request to enumerate + the list of languages the server supports. > + + C: A003 LANGUAGE + S: * LANGUAGE (EN DE IT i-default) + S: A003 OK Supported languages have been enumerated + + C: B001 LANGUAGE + S: B001 NO Server is unable to enumerate supported languages + + + + + + +Newman, et al. Standards Track [Page 5] + +RFC 5255 IMAP Internationalization June 2008 + + + < Once the client changes the language, all responses will be in + that language starting after the LANGUAGE response. Note that + this includes the NAMESPACE response. Because RFCs are in US- + ASCII, this document uses an ASCII transcription rather than + UTF-8 text, e.g., "ue" in the word "ausgefuehrt" > + + C: C001 LANGUAGE DE + S: * LANGUAGE (DE) + S: * NAMESPACE (("" "/")) (("Other Users/" "/" "TRANSLATION" + ("Andere Ben&APw-tzer/"))) (("Public Folders/" "/" + "TRANSLATION" ("Gemeinsame Postf&AM8-cher/"))) + S: C001 OK Sprachwechsel durch LANGUAGE-Befehl ausgefuehrt + + < If a server does not support the requested primary language, + responses will continue to be returned in the current language + the server is using. > + + C: D001 LANGUAGE FR + S: D001 NO Diese Sprache ist nicht unterstuetzt + C: D002 LANGUAGE DE-IT + S: * LANGUAGE (DE-IT) + S: * NAMESPACE (("" "/"))(("Other Users/" "/" "TRANSLATION" + ("Andere Ben&APw-tzer/"))) (("Public Folders/" "/" + "TRANSLATION" ("Gemeinsame Postf&AM8-cher/"))) + S: D002 OK Sprachwechsel durch LANGUAGE-Befehl ausgefuehrt + C: D003 LANGUAGE "default" + S: * LANGUAGE (DE) + S: D003 OK Sprachwechsel durch LANGUAGE-Befehl ausgefuehrt + + < Server does not speak French, but does speak English. User + speaks Canadian French and Canadian English. > + + C: E001 LANGUAGE FR-CA EN-CA + S: * LANGUAGE (EN) + S: E001 OK Now speaking English + +3.3. LANGUAGE Response + + Contents: A list of one or more language tags. + + The LANGUAGE response occurs as a result of a LANGUAGE command. A + LANGUAGE response with a list containing a single language tag + indicates that the server is now using that language. A LANGUAGE + response with a list containing multiple language tags indicates the + server is communicating a list of available languages to the client, + and no change in the active language has been made. + + + + + +Newman, et al. Standards Track [Page 6] + +RFC 5255 IMAP Internationalization June 2008 + + +3.4. TRANSLATION Extension to the NAMESPACE Response + + If localized representations of the namespace prefixes are available + in the selected language, the server SHOULD include these in the + TRANSLATION extension to the NAMESPACE response. + + The TRANSLATION extension to the NAMESPACE response returns a single + string, containing the modified UTF-7 [RFC3501] encoded translation + of the namespace prefix. It is the responsibility of the client to + convert between the namespace prefix and the translation of the + namespace prefix when presenting mailbox names to the user. + + In this example, a server supports the IMAP4 NAMESPACE command. It + uses no prefix to the user's Personal Namespace, a prefix of "Other + Users" to its Other Users' Namespace, and a prefix of "Public + Folders" to its only Shared Namespace. Since a client will often + display these prefixes to the user, the server includes a translation + of them that can be presented to the user. + + C: A001 LANGUAGE DE-IT + S: * NAMESPACE (("" "/")) (("Other Users/" "/" "TRANSLATION" + ("Andere Ben&APw-tzer/"))) (("Public Folders/" "/" + "TRANSLATION" ("Gemeinsame Postf&AM8-cher/"))) + S: A001 OK LANGUAGE-Befehl ausgefuehrt + + + + + + + + + + + + + + + + + + + + + + + + + + + +Newman, et al. Standards Track [Page 7] + +RFC 5255 IMAP Internationalization June 2008 + + +3.5. Formal Syntax + + The following syntax specification inherits ABNF [RFC5234] rules from + IMAP4rev1 [RFC3501], IMAP4 Namespace [RFC2342], Tags for the + Identifying Languages [RFC4646], UTF-8 [RFC3629], and Collected + Extensions to IMAP4 ABNF [RFC4466]. + + command-any =/ language-cmd + ; LANGUAGE command is valid in all states + + language-cmd = "LANGUAGE" *(SP lang-range-quoted) + + response-payload =/ language-data + + language-data = "LANGUAGE" SP "(" lang-tag-quoted *(SP + lang-tag-quoted) ")" + + namespace-trans = SP DQUOTE "TRANSLATION" DQUOTE SP "(" string ")" + ; the string is encoded in Modified UTF-7. + ; this is a subset of the syntax permitted by + ; the Namespace-Response-Extension rule in [RFC4466] + + lang-range-quoted = astring + ; Once any literal wrapper or quoting is removed, this + ; follows the language-range rule in [RFC4647] + + lang-tag-quoted = astring + ; Once any literal wrapper or quoting is removed, this follows + ; the Language-Tag rule in [RFC4646] + + resp-text = ["[" resp-text-code "]" SP ] UTF8-TEXT-CHAR + *(UTF8-TEXT-CHAR / "[") + ; After the server is changed to a language other than + ; i-default, this resp-text rule replaces the resp-text + ; rule from [RFC3501]. + + UTF8-TEXT-CHAR = %x20-5A / %x5C-7E / UTF8-2 / UTF8-3 / UTF8-4 + ; UTF-8 excluding 7-bit control characters and "[" + + + + + + + + + + + + + +Newman, et al. Standards Track [Page 8] + +RFC 5255 IMAP Internationalization June 2008 + + +4. I18NLEVEL=1 and I18NLEVEL=2 Extensions + +4.1. Introduction and Overview + + IMAP4rev1 [RFC3501] includes the SEARCH command that can be used to + locate messages matching criteria including human-readable text. The + SORT extension [SORT] to IMAP allows the client to ask the server to + determine the order of messages based on criteria including human- + readable text. These mechanisms require the ability to support non- + English search and sort functions. + + Section 4 defines two IMAP extensions for internationalizing IMAP + SEARCH, SORT, and THREAD [SORT] using the comparator framework + [RFC4790]. + + The I18NLEVEL=1 extension updates SEARCH/SORT/THREAD to use + i;unicode-casemap comparator, as defined in [UCM]. See Sections 4.2 + and 4.3 for more details. + + The I18NLEVEL=2 extension is a superset of the I18NLEVEL=1 extension. + It adds to I18NLEVEL=1 extension the ability to determine the active + comparator (see definition below) and to negotiate use of comparators + using the COMPARATOR command. It also adds the COMPARATOR response + that indicates the active comparator and possibly other available + comparators. See Sections 4.2 and 4.4 for more details. + +4.2. Requirements Common to Both I18NLEVEL=1 and I18NLEVEL=2 + + The term "default comparator" refers to the comparator that is used + by SEARCH and SORT absent any negotiation using the COMPARATOR + command (see Section 4.7). The term "active comparator" refers to + the comparator which will be used within a session, e.g., by SEARCH + and SORT. The COMPARATOR command is used to change the active + comparator. + + The active comparator applies to the following SEARCH keys: "BCC", + "BODY", "CC", "FROM", "SUBJECT", "TEXT", "TO", and "HEADER". If the + server also advertises the "SORT" extension, then the active + comparator applies to the following SORT keys: "CC", "FROM", + "SUBJECT", and "TO". If the server advertises THREAD=ORDEREDSUBJECT, + then the active comparator applies to the ORDEREDSUBJECT threading + algorithm. If the server advertises THREAD=REFERENCES, then the + active comparator applies to the subject field comparisons done by + REFERENCES threading algorithm. Future extensions may choose to + apply the active comparator to their SEARCH keys. + + + + + + +Newman, et al. Standards Track [Page 9] + +RFC 5255 IMAP Internationalization June 2008 + + + For SORT and THREAD, the pre-processing necessary to extract the base + subject text from a Subject header occurs prior to the application of + a comparator. + + A server that advertises I18NLEVEL=1 or I18NLEVEL=2 extension MUST + implement the i;unicode-casemap comparator, as defined in [UCM]. + + A server that advertises I18NLEVEL=1 or I18NLEVEL=2 extension MUST + support UTF-8 as a SEARCH charset. + +4.3. I18NLEVEL=1 Extension Requirements + + An IMAP server that satisfies all requirements specified in Sections + 4.2 and 4.6 (and that doesn't support/advertise any other + I18NLEVEL=<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 + + An IMAP server that satisfies all requirements specified in Sections + 4.2, 4.4, and 4.6-4.10 (and that doesn't support/advertise any other + I18NLEVEL=<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 the ordering operation + (which in turn uses the equality operation), IMAP servers that + advertise the SORT extension can only implement collations that offer + all three operations (see [RFC4790], Sections 4.2.2-4.2.4). + + + + + +Newman, et al. Standards Track [Page 10] + +RFC 5255 IMAP Internationalization June 2008 + + + If the active collation does not provide the operations needed by an + IMAP command, the server MUST respond with a tagged BAD. + +4.5. Compatibility Notes + + Several server implementations deployed prior to the publication of + this specification comply with I18NLEVEL=1 (see Section 4.3), but do + not advertise that. Other legacy servers use the i;ascii-casemap + comparator (see [RFC4790]). + + There is no good way for a client to know which comparator a legacy + server uses. If the client has to assume the worst, it may end up + doing expensive local operations to obtain i;unicode-casemap + comparisons even though the server implements it. + + Legacy server implementations which comply with I18NLEVEL=1 should be + updated to advertise I18NLEVEL=1. All server implementations should + eventually be updated to comply with the I18NLEVEL=2 extension. + +4.6. Comparators and Character Encodings + + RFC 3501, Section 6.4.4, says: + + In all search keys that use strings, a message matches the key + if the string is a substring of the field. The matching is + case-insensitive. + + When performing the SEARCH operation, the active comparator is + applied instead of the case-insensitive matching specified above. + + An IMAP server which performs collation operations (e.g., as part of + commands such as SEARCH, SORT, and THREAD) does so according to the + following procedure: + + (a) MIME encoding (for example, see [RFC2047] for headers and + [RFC2045] for body parts) MUST be removed in the texts being + collated. + + If MIME encoding removal fails for a message (e.g., a body part + of the message has an unsupported Content-Transfer-Encoding, uses + characters not allowed by the Content-Transfer-Encoding, etc.), + the collation of this message is undefined by this specification, + and is handled in an implementation-dependent manner. + + (b) The decoded text from (a) MUST be converted to the charset + expected by the active comparator. + + + + + +Newman, et al. Standards Track [Page 11] + +RFC 5255 IMAP Internationalization June 2008 + + + (c) For the substring operation: + + If step (b) failed (e.g., the text is in an unknown charset, + contains a sequence that is not valid according in that charset, + etc.), the original decoded text from (a) (i.e., before the + charset conversion attempt) is collated using the i;octet + comparator (see [RFC4790]). + + If step (b) was successful, the converted text from (b) is + collated according to the active comparator. + + For the ordering operation: + + All strings that were successfully converted by step (b) are + separated from all strings that failed step (b). Strings in each + group are collated independently. All strings successfully + converted by step (b) are then validated by the active + comparator. Strings that pass validation are collated using the + active comparator. All strings that either fail step (b) or fail + the active collation's validity operation are collated (after + applying step (a)) using the i;octet comparator (see [RFC4790]). + The resulting sorted list is produced by appending all collated + "failed" strings after all strings collated using the active + comparator. + + Example: The following example demonstrates ordering of 4 + different strings using the i;unicode-casemap [UCM] comparator. + Strings are represented using hexadecimal notation used by ABNF + [RFC5234]. + + (1) %xD0 %xC0 %xD0 %xBD %xD0 %xB4 %xD1 %x80 %xD0 %xB5 + %xD0 %xB9 (labeled with charset=UTF-8) + (2) %xD1 %x81 %xD0 %x95 %xD0 %xA0 %xD0 %x93 %xD0 %x95 + %xD0 %x99 (labeled with charset=UTF-8) + (3) %xD0 %x92 %xD0 %xB0 %xD1 %x81 %xD0 %xB8 %xD0 %xBB + %xD0 %xB8 %xFF %xB9 (labeled with charset=UTF-8) + (4) %xE1 %xCC %xC5 %xCB %xD3 %xC5 %xCA (labeled with + charset=KOI8-R) + + Step (b) will convert string (4) to the following sequence of + octets (in UTF-8): + + %xD0 %x90 %xD0 %xBB %xD0 %xB5 %xD0 %xBA %xD1 %x81 %xD0 + %xB5 %xD0 %xB9 + + and will reject strings (1) and (3), as they contain octets not + allowed in charset=UTF-8. + + + + +Newman, et al. Standards Track [Page 12] + +RFC 5255 IMAP Internationalization June 2008 + + + After that, using the i;unicode-casemap collation, string (4) + will collate before string (2). Using the i;octet collation on + the original strings, string (3) will collate before string (1). + So the final ordering is as follows: (4) (2) (3) (1). + + If the substring operation (e.g., IMAP SEARCH) of the active + comparator returns the "undefined" result (see Section 4.2.3 of + [RFC4790]) for either the text specified in the SEARCH command or the + message text, then the operation is repeated on the result of step + (a) using the i;octet comparator. + + The ordering operation (e.g., IMAP SORT and THREAD) SHOULD collate + the following together: strings encoded using unknown or invalid + character encodings, strings in unrecognized charsets, and invalid + input (as defined by the active collation). + +4.7. COMPARATOR Command + + Arguments: Optional comparator order arguments. + + Response: A possible COMPARATOR response (see Section 4.8). + + Result: OK - Command completed + NO - No matching comparator found + BAD - Arguments invalid + + The COMPARATOR command is valid in authenticated and selected states. + + The COMPARATOR command is used to determine or change the active + comparator. When issued with no arguments, it results in a + COMPARATOR response indicating the currently active comparator. + + When issued with one or more comparator arguments, it changes the + active comparator as directed. (If more than one installed + comparator is matched by an argument, the first argument wins.) The + COMPARATOR response lists all matching comparators if more than one + matches the specified patterns. + + The argument "default" refers to the server's default comparator. + Otherwise, each argument is a collation specification as defined in + the Internet Application Protocol Comparator Registry [RFC4790]. + + < The client requests activating a Czech comparator if possible, + or else a generic international comparator which it considers + suitable for Czech. The server picks the first supported + comparator. > + + + + + +Newman, et al. Standards Track [Page 13] + +RFC 5255 IMAP Internationalization June 2008 + + + C: A001 COMPARATOR "cz;*" i;basic + S: * COMPARATOR i;basic + S: A001 OK Will use i;basic for collation + +4.8. COMPARATOR Response + + Contents: The active comparator. An optional list of available + matching comparators + + The COMPARATOR response occurs as a result of a COMPARATOR command. + The first argument in the comparator response is the name of the + active comparator. The second argument is a list of comparators + which matched any of the arguments to the COMPARATOR command and is + present only if more than one match is found. + +4.9. BADCOMPARATOR Response Code + + This response code SHOULD be returned as a result of server failing + an IMAP command (returning NO), when the server knows that none of + the specified comparators match the requested comparator(s). + +4.10. Formal Syntax + + The following syntax specification inherits ABNF [RFC5234] rules from + IMAP4rev1 [RFC3501] and the Internet Application Protocol Comparator + Registry [RFC4790]. + + command-auth =/ comparator-cmd + + resp-text-code =/ "BADCOMPARATOR" + + comparator-cmd = "COMPARATOR" *(SP comp-order-quoted) + + response-payload =/ comparator-data + + comparator-data = "COMPARATOR" SP comp-sel-quoted [SP "(" + comp-id-quoted *(SP comp-id-quoted) ")"] + + comp-id-quoted = astring + ; Once any literal wrapper or quoting is removed, this + ; follows the collation-id rule from [RFC4790] + + comp-order-quoted = astring + ; Once any literal wrapper or quoting is removed, this + ; follows the collation-order rule from [RFC4790] + + + + + + +Newman, et al. Standards Track [Page 14] + +RFC 5255 IMAP Internationalization June 2008 + + + comp-sel-quoted = astring + ; Once any literal wrapper or quoting is removed, this + ; follows the collation-selected rule from [RFC4790] + +5. Other IMAP Internationalization Issues + + The following sections provide an overview of various other IMAP + internationalization issues. These issues are not resolved by this + specification, but could be resolved by other standards work, such as + that being done by the EAI working group (see [IMAP-EAI]). + +5.1. Unicode Userids and Passwords + + IMAP4rev1 currently restricts the userid and password fields of the + LOGIN command to US-ASCII. The "userid" and "password" fields of the + IMAP LOGIN command are restricted to US-ASCII only until a future + standards track RFC states otherwise. Servers are encouraged to + validate both fields to make sure they conform to the formal syntax + of UTF-8 and to reject the LOGIN command if that syntax is violated. + Servers MAY reject the LOGIN command if either the "userid" or + "password" field contains an octet with the highest bit set. + + When AUTHENTICATE is used, some servers may support userids and + passwords in Unicode [RFC3490] since SASL (see [RFC4422]) allows + that. However, such userids cannot be used as part of email + addresses. + +5.2. UTF-8 Mailbox Names + + The modified UTF-7 mailbox naming convention described in Section + 5.1.3 of RFC 3501 is best viewed as an transition from the status quo + in 1996 when modified UTF-7 was first specified. At that time, there + was widespread unofficial use of local character sets such as ISO- + 8859-1 and Shift-JIS for non-ASCII mailbox names, with resultant + non-interoperability. + + The requirements in Section 5.1 of RFC 3501 are very important if + we're ever going to be able to deploy UTF-8 mailbox names. Servers + are encouraged to enforce them. + +5.3. UTF-8 Domains, Addresses, and Mail Headers + + There is now an IETF standard for "Internationalizing Domain Names in + Applications (IDNA)" [RFC3490]. While IMAP clients are free to + support this standard, an argument can be made that it would be + helpful to simple clients if the IMAP server could perform this + conversion (the same argument would apply to MIME header encoding + + + + +Newman, et al. Standards Track [Page 15] + +RFC 5255 IMAP Internationalization June 2008 + + + [RFC2047]). However, it would be unwise to move forward with such + work until the work in progress to define the format of international + email addresses is complete. + +6. IANA Considerations + + IANA added LANGUAGE, I18NLEVEL=1, and I18NLEVEL=2 to the IMAP4 + Capabilities Registry. + +7. Security Considerations + + The LANGUAGE extension makes a new command available in "Not + Authenticated" state in IMAP. Some IMAP implementations run with + root privilege when the server is in "Not Authenticated" state and do + not revoke that privilege until after authentication is complete. + Such implementations are particularly vulnerable to buffer overflow + security errors at this stage and need to implement parsing of this + command with extra care. + + A LANGUAGE command issued prior to activation of a security layer is + subject to an active attack that suppresses or modifies the + negotiation, and thus makes STARTTLS or authentication error messages + more difficult to interpret. This is not a new attack as the error + messages themselves are subject to active attack. Clients MUST re- + issue the LANGUAGE command once a security layer is active, in order + to prevent this attack from impacting subsequent protocol operations. + + LANGUAGE, I18NLEVEL=1, and I18NLEVEL=2 extensions use the UTF-8 + charset; thus, the security considerations for UTF-8 [RFC3629] are + relevant. However, neither uses UTF-8 for identifiers, so the most + serious concerns do not apply. + +8. Acknowledgements + + The LANGUAGE extension is based on a previous document by Mike + Gahrns, a substantial portion of the text in that section was written + by him. Many people have participated in discussions about an IMAP + Language extension in the various fora of the IETF and Internet + working groups, so any list of contributors is bound to be + incomplete. However, the authors would like to thank Andrew McCown + for early work on the original proposal, John Myers for suggestions + regarding the namespace issue, along with Jutta Degener, Mark + Crispin, Mark Pustilnik, Larry Osterman, Cyrus Daboo, Martin Duerst, + Timo Sirainen, Ben Campbell, and Magnus Nystrom for their many + suggestions that have been incorporated into this document. + + Initial discussion of the I18NLEVEL=2 extension involved input from + Mark Crispin and other participants of the IMAP Extensions WG. + + + +Newman, et al. Standards Track [Page 16] + +RFC 5255 IMAP Internationalization June 2008 + + +9. Relevant Sources of Documents for Internationalized IMAP + Implementations + + This is a non-normative list of sources to consider when implementing + i18n-aware IMAP software. + + o The LANGUAGE and I18NLEVEL=2 extensions to IMAP (this + specification). + + o The 8-bit rules for mailbox naming in Section 5.1 of RFC 3501. + + o The Mailbox International Naming Convention in Section 5.1.3 of + RFC 3501. + + o MIME [RFC2045] for message bodies. + + o MIME header encoding [RFC2047] for message headers. + + o The IETF EAI working group. + + o MIME Parameter Value and Encoded Word Extensions [RFC2231] for + filenames. Quality IMAP server implementations will + automatically combine multipart parameters when generating the + BODYSTRUCTURE. There is also some deployed non-standard use of + MIME header encoding inside double quotes for filenames. + + o IDNA [RFC3490] and punycode [RFC3492] for domain names + (currently only relevant to IMAP clients). + + o The UTF-8 charset [RFC3629]. + + o The IETF policy on Character Sets and Languages [RFC2277]. + +10. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and + Languages", BCP 18, RFC 2277, January 1998. + + [RFC2342] Gahrns, M. and C. Newman, "IMAP4 Namespace", RFC 2342, May + 1998. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + + + + +Newman, et al. Standards Track [Page 17] + +RFC 5255 IMAP Internationalization June 2008 + + + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. + + [RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", STD 68, RFC 5234, January + 2008. + + [RFC4422] Melnikov, A., Ed., and K. Zeilenga, Ed., "Simple + Authentication and Security Layer (SASL)", RFC 4422, June + 2006. + + [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 + ABNF", RFC 4466, April 2006. + + [RFC4646] Phillips, A. and M. Davis, "Tags for Identifying + Languages", BCP 47, RFC 4646, September 2006. + + [RFC4647] Phillips, A. and M. Davis, "Matching of Language Tags", + BCP 47, RFC 4647, September 2006. + + [RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet + Application Protocol Collation Registry", RFC 4790, March + 2007. + + [SORT] Crispin, M. and K. Murchison, "Internet Message Access + Protocol - SORT and THREAD Extensions", RFC 5256, June + 2008. + + [UCM] Crispin, M., "i;unicode-casemap - Simple Unicode Collation + Algorithm", RFC 5051, October 2007. + + [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail + Extensions (MIME) Part One: Format of Internet Message + Bodies", RFC 2045, November 1996. + + [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) + Part Three: Message Header Extensions for Non-ASCII Text", + RFC 2047, November 1996. + +11. Informative References + + [RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and Encoded + Word Extensions: Character Sets, Languages, and + Continuations", RFC 2231, November 1997. + + [RFC3490] Faltstrom, P., Hoffman, P., and A. Costello, + "Internationalizing Domain Names in Applications (IDNA)", + RFC 3490, March 2003. + + + +Newman, et al. Standards Track [Page 18] + +RFC 5255 IMAP Internationalization June 2008 + + + [RFC3492] Costello, A., "Punycode: A Bootstring encoding of Unicode + for Internationalized Domain Names in Applications + (IDNA)", RFC 3492, March 2003. + + [METADATA] Daboo, C., "IMAP METADATA Extension", Work in Progress, + April 2008. + + [IMAP-EAI] Resnick, P., and C. Newman, "IMAP Support for UTF-8", Work + in Progress, November 2007. + +Authors' Addresses + + Chris Newman + Sun Microsystems + 3401 Centrelake Dr., Suite 410 + Ontario, CA 91761 + US + + EMail: chris.newman@sun.com + + + Arnt Gulbrandsen + Oryx Mail Systems GmbH + Schweppermannstr. 8 + D-81671 Muenchen + Germany + + EMail: arnt@oryx.com + Fax: +49 89 4502 9758 + + + Alexey Melnikov + Isode Limited + 5 Castle Business Village, 36 Station Road, + Hampton, Middlesex, TW12 2BX, UK + + EMail: Alexey.Melnikov@isode.com + + + + + + + + + + + + + + +Newman, et al. Standards Track [Page 19] + +RFC 5255 IMAP Internationalization June 2008 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2008). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Newman, et al. Standards Track [Page 20] + diff --git a/imap/docs/draft/sort.txt b/imap/docs/rfc/rfc5256.txt index 4453bb4d..fff0591a 100644 --- a/imap/docs/draft/sort.txt +++ b/imap/docs/rfc/rfc5256.txt @@ -1,84 +1,77 @@ -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 +Network Working Group M. Crispin +Request for Comments: 5256 Panda Programming +Category: Standards Track K. Murchison + Carnegie Mellon University + June 2008 - 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. + Internet Message Access Protocol - SORT and THREAD Extensions - Distribution of this memo is unlimited. +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. Abstract This document describes the 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. + threading extensions to the IMAP protocol. These extensions provide + substantial performance improvements for IMAP clients that offer + sorted and threaded views. -1. Introduction +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 that 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 + A server that 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 + A server that 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 + + + + +Crispin & Murchison Standards Track [Page 1] + +RFC 5256 IMAP Sort June 2008 + + + 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 + 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. + Historical note: The REFERENCES threading algorithm is based on the + [THREADING] algorithm written and used in "Netscape Mail and News" + versions 2.0 through 3.0. -2. Terminology +2. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this @@ -92,51 +85,58 @@ Abstract the software being run by the user. In examples, "C:" and "S:" indicate lines sent by the client and - server respectively. + server, respectively. -2.1 Base Subject +2.1. Base Subject - Subject sorting and threading use the "base subject," which has + 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. + (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. + - (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. +Crispin & Murchison Standards Track [Page 2] + +RFC 5256 IMAP Sort June 2008 - Note: it is possible to defer step (2) until step (6), but this + + (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). + (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. + (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 + 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 +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 @@ -152,17 +152,29 @@ Abstract (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 + If the sent date cannot be determined (a Date: header is missing or + cannot 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. + + + + + + +Crispin & Murchison Standards Track [Page 3] + +RFC 5256 IMAP Sort June 2008 + + +3. Additional Commands + + These commands are extensions 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 @@ -182,20 +194,20 @@ BASE.6.4.SORT. SORT Command 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 results. There are 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. + 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 + There is also a UID SORT command that 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 + 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 @@ -207,8 +219,14 @@ BASE.6.4.SORT. SORT Command 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"). + collation algorithm (see "Internationalization Considerations"). + + + +Crispin & Murchison Standards Track [Page 4] + +RFC 5256 IMAP Sort June 2008 + If two or more messages exactly match according to the sorting criteria, these messages are sorted according to the order in @@ -218,8 +236,8 @@ BASE.6.4.SORT. SORT Command 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. + text; and for messages with the same base subject text, it 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 @@ -249,14 +267,23 @@ BASE.6.4.SORT. SORT Command 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 + other criteria are identical. 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 + 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. + + + + +Crispin & Murchison Standards Track [Page 5] + +RFC 5256 IMAP Sort June 2008 + + SIZE Size of the message in octets. @@ -291,20 +318,27 @@ Result: OK - thread completed 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 + 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. + 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. + There is also a UID THREAD command that 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. + + + +Crispin & Murchison Standards Track [Page 6] + +RFC 5256 IMAP Sort June 2008 + The THREAD command first searches the mailbox for messages that match the given searching criteria using the charset argument for @@ -314,7 +348,7 @@ Result: OK - thread completed 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 + established by their collation algorithm (see "Internationalization Considerations"). Untagged EXPUNGE responses are not permitted while the server is @@ -326,22 +360,23 @@ Result: OK - thread completed ORDEREDSUBJECT The ORDEREDSUBJECT threading algorithm is also referred to as - "poor man's threading." The searched messages are sorted by + "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 + The top level or "root" in ORDEREDSUBJECT threading contains + the first message of every thread. All messages in the root + are siblings of each other. 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. + Client implementations SHOULD treat descendents of a child in a + server response as being siblings of that child. REFERENCES @@ -354,12 +389,19 @@ Result: OK - thread completed subject of a message to see if it is a reply to (or forward of) another message. + + +Crispin & Murchison Standards Track [Page 7] + +RFC 5256 IMAP Sort June 2008 + + 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 + normalized form of the msg-id in [RFC2822]. The actual text + in 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 @@ -380,13 +422,14 @@ Result: OK - thread completed 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 + Note: Although [RFC2822] 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. + 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 @@ -394,170 +437,212 @@ Result: OK - thread completed 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. + 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. + + + +Crispin & Murchison Standards Track [Page 8] + +RFC 5256 IMAP Sort June 2008 + + (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. + (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 Mail User + Agent (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, + + + +Crispin & Murchison Standards Track [Page 9] + +RFC 5256 IMAP Sort June 2008 + + + do not create the parent/child link if creating that + link would introduce a loop. Note that if this message + has no references, 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. + 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: + 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 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. + 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. + 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. + 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. + 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. + + - (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. +Crispin & Murchison Standards Track [Page 10] + +RFC 5256 IMAP Sort June 2008 - (ii) If the thread subject is empty, skip this message. - (iii) Look up the message associated with the thread - subject in the subject table. + (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. + (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: + 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 current message is a dummy, OR - The message in the subject table is a reply or forward - and the current message is not. + 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. + 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: + (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. + (i) Find the message's thread subject as in step + 5.B.i above. - (ii) If the thread subject is empty, skip this message. + (ii) If the thread subject is empty, skip this + message. - (iii) Lookup the message associated with this thread - subject in the subject table. + (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. + (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: + 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 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 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." + +Crispin & Murchison Standards Track [Page 11] + +RFC 5256 IMAP Sort June 2008 + + + 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. + 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) @@ -577,11 +662,21 @@ Result: OK - thread completed (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. + 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 + +Crispin & Murchison Standards Track [Page 12] + +RFC 5256 IMAP Sort June 2008 + + +4. Additional Responses These responses are extensions to the [IMAP] base protocol. @@ -610,10 +705,10 @@ BASE.7.2.THREAD. THREAD Response 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 + 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. + of each sub-thread 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 @@ -623,31 +718,38 @@ BASE.7.2.THREAD. THREAD Response 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 + splits into two sub-threads; 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. + + + +Crispin & Murchison Standards Track [Page 13] + +RFC 5256 IMAP Sort June 2008 + + + -- 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 + In this example, 3 and 5 are siblings of a parent that 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 +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] @@ -678,6 +780,14 @@ sort-data = "SORT" *(SP nz-number) thread-data = "THREAD" [SP 1*thread-list] + + + +Crispin & Murchison Standards Track [Page 14] + +RFC 5256 IMAP Sort June 2008 + + thread-list = "(" (thread-members / thread-nested) ")" thread-members = nz-number *(SP nz-number) [SP thread-nested] @@ -710,12 +820,14 @@ subj-base = NONWSP *(*WSP NONWSP) ; can be a subj-blob BLOBCHAR = %x01-5a / %x5c / %x5e-ff - ; any CHAR8 except '[' and ']' + ; any CHAR8 except '[' and ']'. + ; SHOULD comply with [UTF-8] NONWSP = %x01-08 / %x0a-1f / %x21-ff - ; any CHAR8 other than WSP + ; any CHAR8 other than WSP. + ; SHOULD comply with [UTF-8] -6. Security Considerations +6. Security Considerations The SORT and THREAD extensions do not raise any security considerations that are not present in the base [IMAP] protocol, and @@ -723,8 +835,14 @@ NONWSP = %x01-08 / %x0a-1f / %x21-ff 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. + protection in AUTHENTICATE, or some other protection mechanism. + + + +Crispin & Murchison Standards Track [Page 15] + +RFC 5256 IMAP Sort June 2008 + Although not a security consideration, it is important to recognize that sorting by REFERENCES can lead to misleading threading trees. @@ -732,10 +850,10 @@ NONWSP = %x01-08 / %x0a-1f / %x21-ff 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. + collation if the extracted data was significant text as opposed to a + subject artifact. -7. Internationalization Considerations +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 @@ -753,82 +871,101 @@ NONWSP = %x01-08 / %x0a-1f / %x21-ff 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. + Instead, note that [RFC2822] section 3.6.5 recommends that "re:" + (from the Latin "res", meaning "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 a 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 +8. IANA Considerations [IMAP] capabilities are registered by publishing a standards track or - IESG approved experimental RFC. This document constitutes + IESG-approved experimental RFC. This document constitutes registration of the SORT and THREAD capabilities in the [IMAP] capabilities registry. + + + + + + +Crispin & Murchison Standards Track [Page 16] + +RFC 5256 IMAP Sort June 2008 + + 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 + or IESG-approved experimental RFC. This document constitutes registration of the ORDEREDSUBJECT and REFERENCES algorithms in that registry. -9. Normative References +9. Normative References + + [ABNF] Crocker, D., Ed., and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", STD 68, RFC 5234, January + 2008. + + [CHARSET] Freed, N. and J. Postel, "IANA Charset Registration + Procedures", BCP 19, RFC 2978, October 2000. + + [IMAP] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - + VERSION 4rev1", RFC 3501, March 2003. + + [IMAP-I18N] Newman, C., Gulbrandsen, A., and A. Melnikov, "Internet + Message Access Protocol Internationalization", RFC + 5255, June 2008. - The following documents are normative to this document: + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. - [ABNF] Crocker, D. and Overell, P. "Augmented BNF - for Syntax Specifications: ABNF", RFC 5234 - January 2008 + [RFC2822] Resnick, P., Ed., "Internet Message Format", RFC 2822, + April 2001. - [CHARSET] Freed, N. and Postel, J. "IANA Character Set - Registration Procedures", RFC 2978, October - 2000. + [UNICASEMAP] Crispin, M., "i;unicode-casemap - Simple Unicode + Collation Algorithm", RFC 5051, October 2007. - [IMAP] Crispin, M. "Internet Message Access Protocol - - Version 4rev1", RFC 3501, March 2003. + [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. - [IMAP-I18N] Newman, C. and Gulbrandsen, A. "Internet - Message Access Protocol Internationalization", - Work in Progress. +10. Informative References - [KEYWORDS] Bradner, S. "Key words for use in RFCs to - Indicate Requirement Levels", BCP 14, RFC 2119, - March 1997. + [IMAP-MODELS] Crispin, M., "Distributed Electronic Mail Models in + IMAP4", RFC 1733, December 1994. - [RFC-2822] Resnick, P. "Internet Message Format", RFC - 2822, April 2001. + [THREADING] Zawinski, J. "Message Threading", + http://www.jwz.org/doc/threading.html, 1997-2002. - [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 + + + +Crispin & Murchison Standards Track [Page 17] + +RFC 5256 IMAP Sort June 2008 + + +Authors' Addresses Mark R. Crispin - Networks and Distributed Computing - University of Washington - 4545 15th Avenue NE - Seattle, WA 98105-4527 + Panda Programming + 6158 NE Lariat Loop + Bainbridge Island, WA 98110-2098 - Phone: +1 (206) 543-5762 + Phone: +1 (206) 842-2385 + EMail: IMAP+SORT+THREAD@Lingling.Panda.COM - EMail: MRC@CAC.Washington.EDU Kenneth Murchison Carnegie Mellon University @@ -837,7 +974,43 @@ Author's Address Pittsburgh, PA 15213 Phone: +1 (412) 268-2638 - Email: murch@andrew.cmu.edu + EMail: murch@andrew.cmu.edu + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Crispin & Murchison Standards Track [Page 18] + +RFC 5256 IMAP Sort June 2008 + Full Copyright Statement @@ -876,10 +1049,19 @@ Intellectual Property 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. + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + -Acknowledgement - Funding for the RFC Editor function is currently provided by the - Internet Society. +Crispin & Murchison Standards Track [Page 19] + diff --git a/imap/docs/rfc/rfc5257.txt b/imap/docs/rfc/rfc5257.txt new file mode 100644 index 00000000..1d088e59 --- /dev/null +++ b/imap/docs/rfc/rfc5257.txt @@ -0,0 +1,1739 @@ + + + + + + +Network Working Group C. Daboo +Request for Comments: 5257 Apple Inc. +Category: Experimental R. Gellens + QUALCOMM Incorporated + June 2008 + + + Internet Message Access Protocol - ANNOTATE Extension + +Status of This Memo + + This memo defines an Experimental Protocol for the Internet + community. It does not specify an Internet standard of any kind. + Discussion and suggestions for improvement are requested. + Distribution of this memo is unlimited. + +Abstract + + The ANNOTATE extension to the Internet Message Access Protocol + permits clients and servers to maintain "meta data" for messages, or + individual message parts, stored in a mailbox on the server. For + example, this can be used to attach comments and other useful + information to a message. It is also possible to attach annotations + to specific parts of a message, so that, for example, they could be + marked as seen, or important, or a comment added. + + Note that this document was the product of a WG that had good + consensus on how to approach the problem. Nevertheless, the WG felt + it did not have enough information on implementation and deployment + hurdles to meet all of the requirements of a Proposed Standard. The + IETF solicits implementations and implementation reports in order to + make further progress. + + Implementers should be aware that this specification may change in an + incompatible manner when going to Proposed Standard status. However, + any incompatible changes will result in a new capability name being + used to prevent problems with any deployments of the experimental + extension. + + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 1] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +Table of Contents + + 1. Introduction and Overview .......................................3 + 2. Conventions Used in This Document ...............................4 + 3. Data Model ......................................................4 + 3.1. Overview ...................................................4 + 3.2. Namespace of Entries and Attributes ........................4 + 3.2.1. Entry Names .........................................5 + 3.2.2. Attribute Names .....................................7 + 3.3. Private Versus Shared ......................................7 + 3.4. Access Control .............................................8 + 3.5. Access to Standard IMAP Flags and Keywords ................11 + 4. IMAP Protocol Changes ..........................................11 + 4.1. General Considerations ....................................11 + 4.2. ANNOTATE Parameter with the SELECT/EXAMINE Commands .......12 + 4.3. ANNOTATION Message Data Item in FETCH Command .............12 + 4.4. ANNOTATION Message Data Item in FETCH Response ............14 + 4.5. ANNOTATION Message Data Item in STORE .....................16 + 4.6. ANNOTATION Interaction with COPY ..........................18 + 4.7. ANNOTATION Message Data Item in APPEND ....................18 + 4.8. ANNOTATION Criterion in SEARCH ............................19 + 4.9. ANNOTATION Key in SORT ....................................20 + 4.10. New ACL Rights ...........................................21 + 5. Formal Syntax ..................................................21 + 6. IANA Considerations ............................................23 + 6.1. Entry and Attribute Registration Template .................23 + 6.2. Entry Registrations .......................................24 + 6.2.1. /comment ...........................................24 + 6.2.2. /flags .............................................24 + 6.2.3. /altsubject ........................................25 + 6.2.4. /<section-part>/comment ............................25 + 6.2.5. /<section-part>/flags/seen .........................26 + 6.2.6. /<section-part>/flags/answered .....................26 + 6.2.7. /<section-part>/flags/flagged ......................27 + 6.2.8. /<section-part>/flags/forwarded ....................27 + 6.3. Attribute Registrations ...................................28 + 6.3.1. value ..............................................28 + 6.3.2. size ...............................................28 + 6.4. Capability Registration ...................................28 + 7. Internationalization Considerations ............................29 + 8. Security Considerations ........................................29 + 9. References .....................................................29 + 9.1. Normative References ......................................29 + 9.2. Informative References ....................................30 + 10. Acknowledgments ...............................................30 + + + + + + +Daboo & Gellens Experimental [Page 2] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +1. Introduction and Overview + + The ANNOTATE extension is present in any IMAP [RFC3501] + implementation that returns "ANNOTATE-EXPERIMENT-1" as one of the + supported capabilities in the CAPABILITY response. + + This extension makes the following changes to the IMAP protocol: + + a. adds a new ANNOTATION message data item for use in FETCH. + + b. adds a new ANNOTATION message data item for use in STORE. + + c. adds a new ANNOTATION search criterion for use in SEARCH. + + d. adds a new ANNOTATION sort key for use in the SORT extension. + + e. adds a new ANNOTATION data item for use in APPEND. + + f. adds a new requirement on the COPY command. + + g. adds a new ANNOTATE parameter for use with the SELECT/EXAMINE + commands. + + h. adds two new response codes to indicate store failures of + annotations. + + i. adds a new untagged response code for the SELECT or EXAMINE + commands to indicate the maximum sized annotation that can be + stored. + + j. adds a new Access Control List (ACL) "bit" for use with the ACL + extensions [RFC2086] and [RFC4314]. + + The data model used for the storage of annotations is based on the + Application Configuration Access Protocol [RFC2244]. Note that there + is no inheritance in annotations. + + If a server supports annotations, then it MUST store all annotation + data permanently, i.e., there is no concept of "session only" + annotations that would correspond to the behavior of "session" flags + as defined in the IMAP base specification. + + In order to provide optimum support for a disconnected client (one + that needs to synchronize annotations for use when offline), servers + SHOULD also support the Conditional STORE [RFC4551] extension. + + The rest of this document describes the data model and protocol + changes more rigorously. + + + +Daboo & Gellens Experimental [Page 3] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +2. Conventions Used in This Document + + The examples in this document use "C:" and "S:" to indicate lines + sent by the client and server, respectively. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + +3. Data Model + +3.1. Overview + + The data model for annotations in ANNOTATE uses a uniquely named + entry that contains a set of standard attributes. Thus, a single + coherent unit of "meta data" for a message is stored as a single + entry, made up of several attributes. + + For example, a comment annotation added to a message has an entry + name of "/comment". This entry is composed of several attributes + such as "value", "size", etc., that contain the properties and data + of the entry. + + The protocol changes to IMAP, described below, allow a client to + access or change the values of any attribute in any entry in a + message annotation, assuming it has sufficient access rights to do so + (see Section 3.4 for specifics). + +3.2. Namespace of Entries and Attributes + + A message may contain zero or more annotations, each of which is a + single uniquely named entry. Each entry has a hierarchical name, + with each component of the name separated by a slash ("/"). An entry + name MUST NOT contain two consecutive "/" characters and MUST NOT end + with a "/" character. + + Each entry is made up of a set of attributes. Each attribute has a + hierarchical name, with each component of the name separated by a + period ("."). An attribute name MUST NOT contain two consecutive "." + characters and MUST NOT end with a "." character. + + The value of an attribute is "NIL" (has no value), or is a string of + zero or more octets. + + Entry and attribute names MUST NOT contain asterisk ("*") or percent + ("%") characters, and MUST NOT contain non-ASCII characters or the + NULL octet. Invalid entry or attribute names result in a BAD + response in any IMAP commands where they are used. + + + +Daboo & Gellens Experimental [Page 4] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + Attribute names MUST NOT contain any hierarchical components with the + names "priv" or "shared", as those have special meaning (see Section + 3.3). + + Entry and attribute names are case-sensitive. + + Use of control or punctuation characters in entry and attribute names + is strongly discouraged. + + This specification defines an initial set of entry and attribute + names available for use in message annotations. In addition, an + extension mechanism is described to allow additional names to be + added as needed. + +3.2.1. Entry Names + + Entry names MUST be specified in a standards track or IESG approved + experimental RFC, or fall under the vendor namespace. See Section + 6.1 for the registration template. + + / + Defines the top-level of entries associated with an entire + message. This entry itself does not contain any attributes. All + entries that start with a numeric character ("0" - "9") refer to + an annotation on a specific body part. All other entries are for + annotations on the entire message. + + /comment + Defines a comment or note associated with an entire message. + + /flags + This entry hierarchy is reserved for future use. + + /altsubject + Contains text supplied by the message recipient to be used by the + client, instead of the original message Subject. + + /vendor/<vendor-token> + Defines the top-level of entries associated with an entire message + as created by a particular product of some vendor. These sub- + entries can be used by vendors to provide client-specific + annotations. The vendor-token MUST be registered with IANA, using + the [RFC2244] vendor subtree registry. + + /<section-part> + Defines the top-level of entries associated with a specific body + part of a message. This entry itself does not contain any + attributes. The section-part is a numeric part specifier. Its + + + +Daboo & Gellens Experimental [Page 5] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + syntax is the same as the section-part ABNF element defined in + [RFC3501]. The server MUST return a BAD response if the client + uses an incorrect part specifier (either incorrect syntax or a + specifier referring to a non-existent part). The server MUST + return a BAD response if the client uses an empty part specifier + (which is used in IMAP to represent the entire message). + + /<section-part>/comment + Defines a comment or note associated with a specific body part of + a message. + + /<section-part>/flags + Defines the top-level of entries associated with the flag state + for a specific body part of a message. All sub-entries are + maintained entirely by the client. There is no implicit change to + any flag by the server. + + /<section-part>/flags/seen + This is similar to the IMAP \Seen flag, except it applies + to only the body part referenced by the entry. + + /<section-part>/flags/answered + This is similar to the IMAP \Answered flag, except it + applies to only the body part referenced by the entry. + + /<section-part>/flags/flagged + This is similar to the IMAP \Flagged flag, except it + applies to only the body part referenced by the entry. + + /<section-part>/flags/forwarded + This is similar to the IMAP $Forwarded keyword, except it + applies to only the body part referenced by the entry. + + Defines flags for a specific body part of a message. The "value" + attribute of each of the entries described above must be either + "1", "0", or "NIL". "1" corresponds to the flag being set. + + /<section-part>/vendor/<vendor-token> + Defines the top-level of entries associated with a specific body + part of a message as created by a particular product of some + vendor. This entry can be used by vendors to provide client + specific annotations. The vendor-token MUST be registered with + IANA. + + + + + + + + +Daboo & Gellens Experimental [Page 6] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +3.2.2. Attribute Names + + Attribute names MUST be specified in a standards track or IESG + approved experimental RFC. See Section 6.1 for the registration + template. + + All attribute names implicitly have a ".priv" and a ".shared" suffix + that maps to private and shared versions of the entry. Searching or + fetching without using either suffix will include both. The client + MUST specify either a ".priv" or ".shared" suffix when storing an + annotation or sorting on annotations. + + value + A string or binary data representing the value of the annotation. + To delete an annotation, the client can store "NIL" into the + value. If the client requests the value attribute for a non- + existent entry, then the server MUST return "NIL" for the value. + The content represented by the string is determined by the + content-type used to register the entry (see Section 6.1 for entry + registration templates). Where applicable, the registered + content-type MUST include a charset parameter. Text values SHOULD + use the utf-8 [RFC3629] character set. Note that binary data + (data which may contain the NULL octet) is allowed (e.g., for + storing images), and this extension uses the "literal8" syntax + element [RFC4466] to allow such data to be written to or read from + the server. + + size + The size of the value, in octets. Set automatically by the + server, read-only to clients. If the client requests the size + attribute for a non-existent entry, then the server MUST return + "0" (zero) for the size. + +3.3. Private Versus Shared + + Some IMAP mailboxes are private, accessible only to the owning user. + Other mailboxes are not, either because the owner has set an ACL + [RFC4314] that permits access by other users, or because it is a + shared mailbox. + + This raises the issue of shared versus private annotations. + + If all annotations are private, it is then impossible to have + annotations in a shared or otherwise non-private mailbox be visible + to other users. This eliminates what could be a useful aspect of + annotations in a shared environment. An example of such use is a + shared IMAP folder containing bug reports. Engineers may want to use + + + + +Daboo & Gellens Experimental [Page 7] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + annotations to add information to existing messages, indicate + assignments, status, etc. This use requires shared annotations. + + If all annotations are shared, it is impossible to use annotations + for private notes on messages in shared mailboxes. Also, modifying + an ACL to permit access to a mailbox by other users may + unintentionally expose private information. + + There are also situations in which both shared and private + annotations are useful. For example, an administrator may want to + set shared annotations on messages in a shared folder, which + individual users may wish to supplement with additional notes. + + If shared and private annotations are to coexist, we need a clear way + to differentiate them. Also, it should be as easy as possible for a + client to access both and not overlook either. There is also a + danger in allowing a client to store an annotation without knowing if + it is shared or private. + + This document proposes two standard suffixes for all attributes: + ".shared" and ".priv". A SEARCH or FETCH command that specifies + neither, uses both. STORE, APPEND, and SORT commands MUST explicitly + use ".priv" or ".shared" suffixes. + + If the ANNOTATE extension is present, support for shared annotations + in servers is REQUIRED, while support for private annotations in + servers is OPTIONAL. This recognizes the fact that support for + private annotations may introduce a significant increase in + complexity to a server in terms of tracking ownership of the + annotations, how quota is determined for users based on their own + annotations, etc. Clients that support the ANNOTATE extension MUST + handle both shared and private annotations. + +3.4. Access Control + + A user needs to have appropriate rights in order to read or write + ".priv" or ".shared" annotation values. How those rights are + calculated depends on whether or not the ACL [RFC2086] extension or + its update [RFC4314] is present. If a client attempts to store or + fetch an annotation to which they do not have the appropriate rights, + the server MUST respond with a NO response. + + When the ACL extension is not present, access to annotation values is + governed by the nature of the selected state, in particular whether + the mailbox was SELECTED or EXAMINED in READ-ONLY or READ-WRITE mode. + + + + + + +Daboo & Gellens Experimental [Page 8] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + When the ACL extension is present, the server MUST recognize the new + ACL "n" right, in addition to the ones defined by the ACL extension + itself. + + For ".priv" annotation values, the "r" right controls both read and + write access. When it is on, access to ".priv" annotations is + allowed; when it is off, access to ".priv" annotations is disallowed. + + For ".shared" annotation values, the "r" right controls read access. + When it is on, ".shared" annotations can be read; when it is off, + ".shared" annotations cannot be read. + + For ".shared" annotation values, the "n" right controls write access. + When it is on, ".shared" annotations can be changed or created + through either a STORE or APPEND command; when it is off, ".shared" + annotations cannot be changed or created. The "n" right constitutes + a "shared flag right" as defined in Section 6.2 of [RFC4314]. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 9] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + A summary of all the access control restrictions is tabulated below + + +---------------+---------------+-----------------------------------+ + | Server Type | Action on | Type of mailbox | + | | annotation | | + +===============+===============+===================================+ + | | | | + | | read .priv | Any mailbox that can be SELECTED | + | | values | or EXAMINED. | + | | | | + | +---------------+-----------------------------------+ + | | | | + | | write .priv | Any SELECTED [READ-WRITE] mailbox.| + | | values | SELECTED [READ-ONLY] mailboxes MAY| + | Server | | also permit writes. | + | without | | | + | ACL Extension +---------------+-----------------------------------+ + | | | | + | | read .shared | Any mailbox that can be SELECTED | + | | values | or EXAMINED. | + | | | | + | +---------------+-----------------------------------+ + | | | | + | | write .shared | Any mailbox that can be SELECTED | + | | values | or EXAMINED and is [READ-WRITE]. | + | | | | + +---------------+---------------+-----------------------------------+ + | | | | + | | read .priv | Any mailbox with the "r" | + | | values | ACL right. | + | | | | + | +---------------+-----------------------------------+ + | | | | + | | write .priv | Any mailbox with the "r" | + | Server | values | ACL right. | + | with | | | + | ACL Extension +---------------+-----------------------------------+ + | | | | + | | read .shared | Any mailbox with the "r" | + | | values | ACL right. | + | | | | + | +---------------+-----------------------------------+ + | | | | + | | write .shared | Any mailbox with the "n" | + | | values | ACL right. | + | | | | + +---------------+---------------+-----------------------------------+ + + + + +Daboo & Gellens Experimental [Page 10] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +3.5. Access to Standard IMAP Flags and Keywords + + Due to the ambiguity of how private and shared values would map to + the base IMAP flag and keyword values, the ANNOTATE extension does + not expose IMAP flags or keywords as entries. However, the /flags + annotation entry is reserved for future use and MUST NOT be used by + clients or servers supporting this extension. + + Clients that need to implement shared and private "flags" can create + their own annotation entries for those, completely bypassing the base + IMAP flag/keyword behavior. + +4. IMAP Protocol Changes + +4.1. General Considerations + + Servers may be able to offer only a limited level of support for + annotations in mailboxes, and it is useful for clients to be able to + know what level of support is available. Servers MUST return an + ANNOTATIONS response code during the SELECT or EXAMINE command for a + mailbox to indicate the level of support. Possible data items used + with the ANNOTATIONS response code are: + + "NONE" - this indicates that the mailbox being selected does not + support annotations at all. Clients MUST NOT attempt to use + annotation extensions in commands for this mailbox. + + "READ-ONLY" - this indicates that the annotations supported by the + mailbox cannot be changed by the client. Clients MUST NOT attempt + to store annotations on any messages in a mailbox with this + response code. + + "NOPRIVATE" - this indicates that the server does not support + private annotations on the mailbox. Only shared annotations are + supported. Clients SHOULD only attempt to read or store + annotations attributes with the ".shared" suffix. If a client + uses an attribute with the ".priv" suffix in a FETCH command, then + servers should return the attribute value in the FETCH response as + "NIL". If a client uses an attribute with the ".priv" suffix in a + STORE command (or an APPEND command targeted at the mailbox), then + the server MUST return a NO response. + + numeric values - if servers support writable annotations, then the + server MUST indicate the maximum size in octets for an annotation + value by providing the maximum size value in the response code. + Clients MUST NOT store annotation values of a size greater than + the amount indicated by the server. Servers MUST accept a minimum + + + + +Daboo & Gellens Experimental [Page 11] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + annotation data size of at least 1024 octets if annotations can be + written. + + In addition, the server MAY limit the total number of annotations for + a single message. However, the server MUST provide a minimum + annotation count per message of at least 10. + +4.2. ANNOTATE Parameter with the SELECT/EXAMINE Commands + + The ANNOTATE extension defines a single optional SELECT parameter + [RFC4466] "ANNOTATE", which is used to turn on unsolicited responses + for annotations as described in Section 4.4. This optional parameter + results in a per-mailbox state change, i.e., it must be used in each + SELECT/EXAMINE command in order to be effective, irrespective of + whether it was used in a previous SELECT/EXAMINE during the same + session. + + Example: + + C: a SELECT INBOX (ANNOTATE) + S: * FLAGS (\Answered \Flagged \Draft \Deleted \Seen) + S: * OK [PERMANENTFLAGS (\Answered \Flagged \Draft + \Deleted \Seen \*)] + S: * 10268 EXISTS + S: * 1 RECENT + S: * OK [UNSEEN 10268] + S: * OK [UIDVALIDITY 890061587] + S: * OK [UIDNEXT 34643] + S: * OK [ANNOTATIONS 20480 NOPRIVATE] + S: a OK [READ-WRITE] Completed + + In the above example, a SELECT command with the ANNOTATE parameter + is issued. The response from the server includes the required + ANNOTATIONS response that indicates that the server supports + annotations up to a maximum size of 20480 octets, and does not + support private annotations (only shared). + +4.3. ANNOTATION Message Data Item in FETCH Command + + This extension adds an ANNOTATION message data item to the FETCH + command. This allows clients to retrieve annotations for a range of + messages in the currently selected mailbox. + + ANNOTATION <entry-specifier> <attribute-specifier> + + The ANNOTATION message data item, when used by the client in the + FETCH command, takes an entry specifier and an attribute + specifier. + + + +Daboo & Gellens Experimental [Page 12] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + Example: + + C: a FETCH 1 (ANNOTATION (/comment value)) + S: * 1 FETCH (ANNOTATION (/comment + (value.priv "My comment" + value.shared "Group note"))) + S: a OK Fetch complete + + In the above example, the content of the "value" attribute for the + "/comment" entry is requested by the client and returned by the + server. Since neither ".shared" nor ".priv" was specified, both + are returned. + + "*" and "%" wild card characters can be used in entry specifiers to + match one or more characters at that position, with the exception + that "%" does not match the "/" hierarchy delimiter. Thus, an entry + specifier of "/%" matches entries such as "/comment" and + "/altsubject", but not "/1/comment". + + Example: + + C: a UID FETCH 1123 (UID ANNOTATION + (/* (value.priv size.priv))) + S: * 12 FETCH (UID 1123 ANNOTATION + (/comment (value.priv "My comment" + size.priv "10") + /altsubject (value.priv "Rhinoceroses!" + size.priv "13") + /vendor/foobar/label.priv + (value.priv "label43" + size.priv "7") + /vendor/foobar/personality + (value.priv "Tallulah Bankhead" + size.priv "17"))) + S: a OK Fetch complete + + In the above example, the contents of the private "value" and + "size" attributes for any entries in the "/" hierarchy are + requested by the client and returned by the server. + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 13] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + Example: + + C: a FETCH 1 (ANNOTATION (/% value.shared)) + S: * 1 FETCH (ANNOTATION + (/comment (value.shared "Patch Mangler") + /altsubject (value.shared "Patches? We don't + need no steenkin patches!"))) + S: a OK Fetch complete + + In the above example, the contents of the shared "value" + attributes for entries at the top level only of the "/" hierarchy + are requested by the client and returned by the server. + + Entry and attribute specifiers can be lists of atomic specifiers, so + that multiple items of each type may be returned in a single FETCH + command. + + Example: + + C: a FETCH 1 (ANNOTATION + ((/comment /altsubject) value.priv)) + S: * 1 FETCH (ANNOTATION + (/comment (value.priv "What a chowder-head") + /altsubject (value.priv "How to crush beer cans"))) + S: a OK Fetch complete + + In the above example, the contents of the private "value" + attributes for the two entries "/comment" and "/altsubject" are + requested by the client and returned by the server. + +4.4. ANNOTATION Message Data Item in FETCH Response + + The ANNOTATION message data item in the FETCH response displays + information about annotations in a message. + + ANNOTATION parenthesized list + + The response consists of a list of entries, each of which have a + list of attribute-value pairs. + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 14] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + Example: + + C: a FETCH 1 (ANNOTATION (/comment value)) + S: * 1 FETCH (ANNOTATION (/comment + (value.priv "My comment" + value.shared NIL))) + S: a OK Fetch complete + + In the above example, a single entry with a single attribute-value + pair is returned by the server. Since the client did not specify + a ".shared" or ".priv" suffix, both are returned. Only the + private attribute has a value (the shared value is "NIL"). + + Example: + + C: a FETCH 1 (ANNOTATION + ((/comment /altsubject) value)) + S: * 1 FETCH (ANNOTATION + (/comment (value.priv "My comment" + value.shared NIL) + /altsubject (value.priv "My subject" + value.shared NIL))) + S: a OK Fetch complete + + In the above example, two entries, each with a single attribute- + value pair, are returned by the server. Since the client did not + specify a ".shared" or ".priv" suffix, both are returned. Only + the private attributes have values; the shared attributes are + "NIL". + + Example: + + C: a FETCH 1 (ANNOTATION + (/comment (value size))) + S: * 1 FETCH (ANNOTATION + (/comment + (value.priv "My comment" + value.shared NIL + size.priv "10" + size.shared "0"))) + S: a OK Fetch complete + + In the above example, a single entry with two attribute-value + pairs is returned by the server. Since the client did not specify + a ".shared" or ".priv" suffix, both are returned. Only the + private attributes have values; the shared attributes are "NIL". + + + + + +Daboo & Gellens Experimental [Page 15] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + Servers SHOULD send ANNOTATION message data items in unsolicited + FETCH responses if an annotation entry is changed by a third-party, + and the ANNOTATE select parameter was used. This allows servers to + keep clients updated with changes to annotations by other clients. + + Unsolicited ANNOTATION responses MUST NOT include ANNOTATION data + values -- only the entry name of the ANNOTATION that has changed. + This restriction avoids sending ANNOTATION data values (which may be + large) to a client unless the client explicitly asks for the value. + + Example: + + C: a STORE 1 +FLAGS (\Seen) + S: * 1 FETCH (FLAGS (\Seen)) + ANNOTATION (/comment)) + S: a OK STORE complete + + In the above example, an unsolicited ANNOTATION response is + returned during a STORE command. The unsolicited response + contains only the entry name of the annotation that changed, and + not its value. + +4.5. ANNOTATION Message Data Item in STORE + + ANNOTATION <parenthesized entry-attribute-value list> + + Sets the specified list of entries by adding or replacing the + specified attributes with the values provided. Clients can use + "NIL" for values of attributes it wants to remove from entries. + + The ANNOTATION message data item used with the STORE command has an + implicit ".SILENT" behavior. This means the server does not generate + an untagged FETCH in response to the STORE command and assumes that + the client updates its own cache if the command succeeds. Though + note, that if the Conditional STORE extension [RFC4551] is present, + then an untagged FETCH response with a MODSEQ data item will be + returned by the server as required by [RFC4551]. + + If the server is unable to store an annotation because the size of + its value is too large, the server MUST return a tagged NO response + with a "[ANNOTATE TOOBIG]" response code. + + If the server is unable to store a new annotation because the maximum + number of allowed annotations has already been reached, the server + MUST return a tagged NO response with a "[ANNOTATE TOOMANY]" response + code. + + + + + +Daboo & Gellens Experimental [Page 16] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + Example: + + C: a STORE 1 ANNOTATION (/comment + (value.priv "My new comment")) + S: a OK Store complete + + In the above example, the entry "/comment" is created (if not + already present). Its private attribute "value" is created if not + already present, or replaced if it exists. "value.priv" is set to + "My new comment". + + Example: + + C: a STORE 1 ANNOTATION (/comment + (value.shared NIL)) + S: a OK Store complete + + In the above example, the shared "value" attribute of the entry + "/comment" is removed by storing "NIL" into the attribute. + + Multiple entries can be set in a single STORE command by listing + entry-attribute-value pairs in the list. + + Example: + + C: a STORE 1 ANNOTATION (/comment + (value.priv "Get tix Tuesday") + /altsubject + (value.priv "Wots On")) + S: a OK Store complete + + In the above example, the entries "/comment" and "/altsubject" are + created (if not already present) and the private attribute "value" + is created or replaced for each entry. + + Multiple attributes can be set in a single STORE command by listing + multiple attribute-value pairs in the entry list. + + + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 17] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + Example: + + C: a STORE 1 ANNOTATION (/comment + (value.priv "My new comment" + value.shared "foo's bar")) + S: a OK Store complete + + In the above example, the entry "/comment" is created (if not + already present) and the private and shared "value" attributes are + created if not already present, or replaced if they exist. + +4.6. ANNOTATION Interaction with COPY + + The COPY command can be used to move messages from one mailbox to + another on the same server. Servers that support the ANNOTATION + extension MUST, for each message being copied, copy all ".priv" + annotation data for the current user only, and all ".shared" + annotation data along with the message to the new mailbox. The only + exceptions to this are if the destination mailbox permissions are + such that either the ".priv" or ".shared" annotations are not + allowed, or if the destination mailbox is of a type that does not + support annotations or does not support storing of annotations (a + mailbox that returns a "NONE" or "READ-ONLY" response code in its + ANNOTATIONS response), or if the destination mailbox cannot support + the size of an annotation because it exceeds the ANNOTATIONS value. + Servers MUST NOT copy ".priv" annotation data for users other than + the current user. + +4.7. ANNOTATION Message Data Item in APPEND + + ANNOTATION <parenthesized entry-attribute-value list> + + Sets the specified list of entries and attributes in the resulting + message. + + The APPEND command can include annotations for the message being + appended via the addition of a new append data item [RFC4466]. The + new data item can also be used with the multi-append [RFC3502] + extension that allows multiple messages to be appended via a single + APPEND command. + + + + + + + + + + + +Daboo & Gellens Experimental [Page 18] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + Example: + + C: a APPEND drafts ANNOTATION (/comment + (value.priv "Don't send until I say so")) {310} + S: + Ready for literal data + C: MIME-Version: 1.0 + ... + C: + S: a OK APPEND completed + + In the above example, a comment with a private value is added to a + new message appended to the mailbox. The ellipsis represents the + bulk of the message. + +4.8. ANNOTATION Criterion in SEARCH + + ANNOTATION <entry-name> <attribute-name> <value> + + The ANNOTATION criterion for the SEARCH command allows a client to + search for a specified string in the value of an annotation entry of + a message. + + Messages that have annotations with entries matching <entry-name>, + attributes matching <attribute-name>, and the specified string + <value> in their values are returned in the SEARCH results. The "*" + character can be used in the entry name field to match any content in + those items. The "%" character can be used in the entry name field + to match a single level of hierarchy only. + + Only the "value", "value.priv", and "value.shared" attributes can be + searched. Clients MUST NOT specify an attribute other than either + "value", "value.priv", or "value.shared". Servers MUST return a BAD + response if the client tries to search any other attribute. + + Example: + + C: a SEARCH ANNOTATION /comment value "IMAP4" + S: * SEARCH 2 3 5 7 11 13 17 19 23 + S: a OK Search complete + + In the above example, the message numbers of any messages + containing the string "IMAP4" in the shared or private "value" + attribute of the "/comment" entry are returned in the search + results. + + + + + + + +Daboo & Gellens Experimental [Page 19] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + Example: + + C: a SEARCH ANNOTATION * value.priv "IMAP4" + S: * SEARCH 1 2 3 5 8 13 21 34 + S: a OK Search complete + + In the above example, the message numbers of any messages + containing the string "IMAP4" in the private "value" attribute of + any entry are returned in the search results. + +4.9. ANNOTATION Key in SORT + + ANNOTATION <entry-name> <attribute-name> + + The ANNOTATION criterion for the SORT command [RFC5256] instructs the + server to return the sequence numbers or Unique Identifiers (UIDs) of + messages in a mailbox, sorted using the values of the specified + annotations. The ANNOTATION criterion is available if the server + returns both ANNOTATE-EXPERIMENT-1 and SORT as supported capabilities + in the CAPABILITY command response. + + Messages are sorted using the values of the <attribute-name> + attributes in the <entry-name> entries. + + Clients MUST provide either the ".priv" or ".shared" suffix to the + attribute name to ensure that the server knows which specific value + to sort on. + + Only the "value.priv" and "value.shared" attributes can be used for + sorting. Clients MUST NOT specify an attribute other than either + "value.priv" or "value.shared". Servers MUST return a BAD response + if the client tries to sort on any other attribute. + + When either "value.priv" or "value.shared" is being sorted, the + server MUST use the character set value specified in the SORT command + to determine the appropriate sort order. + + Example: + + C: a SORT (ANNOTATION /altsubject value.shared) UTF-8 ALL + S: * SORT 2 3 4 5 1 11 10 6 7 9 8 + S: a OK Sort complete + + In the above example, the message numbers of all messages are + returned, sorted according to the shared "value" attribute of the + "/altsubject" entry. + + + + + +Daboo & Gellens Experimental [Page 20] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + Note that the ANNOTATION sort key must include a fully specified + entry -- wild cards are not allowed. + +4.10. New ACL Rights + + As discussed in Section 3.4, this extension adds a new "n" right to + the list of rights provided by the ACL extensions [RFC2086] and + [RFC4314]. + +5. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [RFC5234]. + + Non-terminals referenced but not defined below are as defined by + [RFC3501] with the new definitions in [RFC4466] superseding those in + [RFC3501]. + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of upper or lower case characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. + + ann-size = "NONE" / + (("READ-ONLY" / nz-number) + [SP "NOPRIVATE"]) + ; response codes indicating the level of + ; support for annotations in a mailbox + + append-ext =/ att-annotate + ; modifies [RFC3501] extension behaviour + + att-annotate = "ANNOTATION" SP + "(" entry-att *(SP entry-att) ")" + + att-search = "value" / "value.priv" / "value.shared" + ; the only attributes that can be searched + + att-sort = "value.priv" / "value.shared" + ; the only attributes that can be sorted + + att-value = attrib SP value + + attrib = astring + ; dot-separated attribute name + ; MUST NOT contain "*" or "%" + + + + + +Daboo & Gellens Experimental [Page 21] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + attribs = attrib / "(" attrib *(SP attrib) ")" + ; one or more attribute specifiers + + capability =/ "ANNOTATE-EXPERIMENT-1" + ; defines the capability for this extension + + entries = entry-match / + "(" entry-match *(SP entry-match) ")" + + entry = astring + ; slash-separated path to entry + ; MUST NOT contain "*" or "%" + + entry-att = entry SP "(" att-value *(SP att-value) ")" + + entry-match = list-mailbox + ; slash-separated path to entry + ; MAY contain "*" or "%" for use as wild cards + + fetch-att =/ "ANNOTATION" SP "(" entries SP attribs ")" + ; modifies original IMAP fetch-att + + msg-att-dynamic =/ "ANNOTATION" SP + ( "(" entry-att *(SP entry-att) ")" / + "(" entry *(SP entry) ")" ) + ; extends FETCH response with annotation data + + resp-text-code =/ "ANNOTATE" SP "TOOBIG" / + "ANNOTATE" SP "TOOMANY" / + "ANNOTATIONS" SP ann-size + ; new response codes + + search-key =/ "ANNOTATION" SP entry-match SP att-search + SP value + ; modifies original IMAP search-key + + select-param =/ "ANNOTATE" + ; defines the select parameter used with + ; ANNOTATE extension + + sort-key =/ "ANNOTATION" SP entry SP att-sort + ; modifies original sort-key + + store-att-flags =/ att-annotate + ; modifies original IMAP STORE command + + value = nstring / literal8 + + + + +Daboo & Gellens Experimental [Page 22] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +6. IANA Considerations + + Entry names MUST be specified in a standards track or IESG approved + experimental RFC, or fall under the vendor namespace. Vendor names + MUST be registered. + + Attribute names MUST be specified in a standards track or IESG + approved experimental RFC. + + Each entry registration MUST include a content-type that is used to + indicate the nature of the annotation value. Where applicable, a + charset parameter MUST be included with the content-type. + +6.1. Entry and Attribute Registration Template + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [] Entry [] Attribute + + Name: ______________________________ + + Description: _______________________ + + ____________________________________ + + ____________________________________ + + Content-Type:_______________________ + + Contact person: ____________________ + + email: ____________________ + + + + + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 23] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +6.2. Entry Registrations + + The following templates specify the IANA registrations of annotation + entries specified in this document. + +6.2.1. /comment + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [X] Entry [] Attribute + + Name: /comment + + Description: Defined in IMAP ANNOTATE extension document. + + Content-Type: text/plain; charset=utf-8 + + Contact person: Cyrus Daboo + + email: cyrus@daboo.name + +6.2.2. /flags + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [X] Entry [] Attribute + + Name: /flags + + Description: Reserved entry hierarchy. + + Content-Type: - + + Contact person: Cyrus Daboo + + email: cyrus@daboo.name + + + + + + + + + +Daboo & Gellens Experimental [Page 24] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +6.2.3. /altsubject + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [X] Entry [] Attribute + + Name: /altsubject + + Description: Defined in IMAP ANNOTATE extension document. + + Content-Type: text/plain; charset=utf-8 + + Contact person: Cyrus Daboo + + email: cyrus@daboo.name + +6.2.4. /<section-part>/comment + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [X] Entry [] Attribute + + Name: /<section-part>/comment + + Description: Defined in IMAP ANNOTATE extension document. + + Content-Type: text/plain; charset=utf-8 + + Contact person: Cyrus Daboo + + email: cyrus@daboo.name + + + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 25] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +6.2.5. /<section-part>/flags/seen + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [X] Entry [] Attribute + + Name: /<section-part>/flags/seen + + Description: Defined in IMAP ANNOTATE extension document. + + Content-Type: text/plain; charset=utf-8 + + Contact person: Cyrus Daboo + + email: cyrus@daboo.name + +6.2.6. /<section-part>/flags/answered + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [X] Entry [] Attribute + + Name: /<section-part>/flags/answered + + Description: Defined in IMAP ANNOTATE extension document. + + Content-Type: text/plain; charset=utf-8 + + Contact person: Cyrus Daboo + + email: cyrus@daboo.name + + + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 26] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +6.2.7. /<section-part>/flags/flagged + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [X] Entry [] Attribute + + Name: /<section-part>/flags/flagged + + Description: Defined in IMAP ANNOTATE extension document. + + Content-Type: text/plain; charset=utf-8 + + Contact person: Cyrus Daboo + + email: cyrus@daboo.name + +6.2.8. /<section-part>/flags/forwarded + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [X] Entry [] Attribute + + Name: /<section-part>/flags/forwarded + + Description: Defined in IMAP ANNOTATE extension document. + + Content-Type: text/plain; charset=utf-8 + + Contact person: Cyrus Daboo + + email: cyrus@daboo.name + + + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 27] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +6.3. Attribute Registrations + + The following templates specify the IANA registrations of annotation + attributes specified in this document. + +6.3.1. value + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [] Entry [X] Attribute + + Name: value + + Description: Defined in IMAP ANNOTATE extension document. + + Contact person: Cyrus Daboo + + email: cyrus@daboo.name + +6.3.2. size + + To: iana@iana.org + Subject: IMAP Annotate Registration + + Please register the following IMAP Annotate item: + + [] Entry [X] Attribute + + Name: size + + Description: Defined in IMAP ANNOTATE extension document. + + Contact person: Cyrus Daboo + + email: cyrus@daboo.name + +6.4. Capability Registration + + This document registers "ANNOTATE-EXPERIMENT-1" as an IMAPEXT + capability. + + + + + + + + +Daboo & Gellens Experimental [Page 28] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +7. Internationalization Considerations + + Annotations may contain values that include text strings, and both + searching and sorting are possible with annotations. Servers MUST + follow standard IMAP text normalization, character set conversion, + and collation rules when such operations are carried out, as would be + done for other textual fields being searched or sorted on. + +8. Security Considerations + + Annotations whose values are intended to remain private MUST be + stored in ".priv" values instead of ".shared" values, which may be + accessible to other users. + + Excluding the above issues, the ANNOTATE extension does not raise any + security considerations that are not present in the base IMAP + protocol; these issues are discussed in [RFC3501]. + +9. References + +9.1. Normative References + + [RFC2086] Myers, J., "IMAP4 ACL extension", RFC 2086, January 1997. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2244] Newman, C. and J. Myers, "ACAP -- Application + Configuration Access Protocol", RFC 2244, November 1997. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [RFC3502] Crispin, M., "Internet Message Access Protocol (IMAP) - + MULTIAPPEND Extension", RFC 3502, March 2003. + + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. + + [RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) Extension", + RFC 4314, December 2005. + + [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 + ABNF", RFC 4466, April 2006. + + [RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", STD 68, RFC 5234, January + 2008. + + + +Daboo & Gellens Experimental [Page 29] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + + [RFC5256] Crispin, M. and K. Murchison, "Internet Message Access + Protocol - SORT and THREAD Extensions", RFC 5256, June + 2008. + +9.2. Informative References + + [RFC4551] Melnikov, A. and S. Hole, "IMAP Extension for Conditional + STORE Operation or Quick Flag Changes Resynchronization", + RFC 4551, June 2006. + +10. Acknowledgments + + Many thanks to Chris Newman for his detailed comments on the first + draft of this document, and to the participants at the ACAP working + dinner in Pittsburgh. The participants of the IMAPext working group + made significant contributions to this work. + +Authors' Addresses + + Cyrus Daboo + Apple Inc. + 1 Infinite Loop + Cupertino, CA 95014 + USA + + EMail: cyrus@daboo.name + URI: http://www.apple.com/ + + + Randall Gellens + QUALCOMM Incorporated + 5775 Morehouse Dr. + San Diego, CA 92121-2779 + USA + + EMail: randy@qualcomm.com + + + + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 30] + +RFC 5257 IMAP ANNOTATE Extension June 2008 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2008). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Daboo & Gellens Experimental [Page 31] + diff --git a/imap/docs/rfc/rfc5258.txt b/imap/docs/rfc/rfc5258.txt new file mode 100644 index 00000000..a80ec156 --- /dev/null +++ b/imap/docs/rfc/rfc5258.txt @@ -0,0 +1,1739 @@ + + + + + + +Network Working Group B. Leiba +Request for Comments: 5258 IBM T.J. Watson Research Center +Obsoletes: 3348 A. Melnikov +Updates: 2193 Isode Limited +Category: Standards Track June 2008 + + + Internet Message Access Protocol version 4 - LIST Command Extensions + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + IMAP4 has two commands for listing mailboxes: LIST and LSUB. As we + have added extensions, such as Mailbox Referrals, that have required + specialized lists we have had to expand the number of list commands, + since each extension must add its function to both LIST and LSUB, and + these commands are not, as they are defined, extensible. If we've + needed the extensions to work together, we've had to add a set of + commands to mix the different options, the set increasing in size + with each new extension. This document describes an extension to the + base LIST command that will allow these additions to be done with + mutually compatible options to the LIST command, avoiding the + exponential increase in specialized list commands. + + + + + + + + + + + + + + + + + + + + + +Leiba & Melnikov Standards Track [Page 1] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + +Table of Contents + + 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 + 2. Conventions Used in This Document . . . . . . . . . . . . . . 4 + 3. Extended LIST Command . . . . . . . . . . . . . . . . . . . . 4 + 3.1. Initial List of Selection Options . . . . . . . . . . . . 7 + 3.2. Initial List of Return Options . . . . . . . . . . . . . . 8 + 3.3. General Principles for Returning LIST Responses . . . . . 9 + 3.4. Additional Requirements on LIST-EXTENDED Clients . . . . . 9 + 3.5. CHILDINFO Extended Data Item . . . . . . . . . . . . . . . 10 + 4. The CHILDREN Return Option . . . . . . . . . . . . . . . . . . 11 + 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 + 6. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 19 + 7. Internationalization Considerations . . . . . . . . . . . . . 22 + 8. Security Considerations . . . . . . . . . . . . . . . . . . . 23 + 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 + 9.1. Guidelines for IANA . . . . . . . . . . . . . . . . . . . 23 + 9.2. Registration Procedure and Change Control . . . . . . . . 23 + 9.3. Registration Template for LIST-EXTENDED Options . . . . . 25 + 9.4. Initial LIST-EXTENDED Option Registrations . . . . . . . . 25 + 9.5. Registration Template for LIST-EXTENDED Extended Data + Item . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 + 9.6. Initial LIST-EXTENDED Extended Data Item Registrations . . 28 + 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 29 + 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 + 11.1. Normative References . . . . . . . . . . . . . . . . . . . 29 + 11.2. Informative References . . . . . . . . . . . . . . . . . . 30 + + + + + + + + + + + + + + + + + + + + + + + + +Leiba & Melnikov Standards Track [Page 2] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + +1. Introduction and Overview + + The LIST command is extended by amending the syntax to allow options + and multiple patterns to be specified. The list of options replaces + the several commands that are currently used to mix and match the + information requested. The new syntax is backward compatible, with + no ambiguity: the new syntax is being used if one of the following + conditions is true: + + 1. if the first word after the command name begins with a + parenthesis ("LIST selection options") + + 2. if the second word after the command name begins with a + parenthesis ("multiple mailbox patterns") + + 3. if the LIST command has more than 2 parameters ("LIST return + options") + + Otherwise the original syntax is used. + + By adding options to the LIST command, we are announcing the intent + to phase out and eventually to deprecate the RLIST and RLSUB commands + described in [MBRef]. We are also defining the mechanism to request + extended mailbox information, such as is described in the Child + Mailbox Extension [CMbox]. The base LSUB command is not deprecated + by this extension; rather, this extension adds a way to obtain + subscription information with more options, with those server + implementations that support it. Clients that simply need a list of + subscribed mailboxes, as provided by the LSUB command, SHOULD + continue to use that command. + + This document defines an IMAP4 extension that is identified by the + capability string "LIST-EXTENDED". The LIST-EXTENDED extension makes + the following changes to the IMAP4 protocol, which are described in + more detail in Section 3 and Section 4: + + a. defines new syntax for LIST command options. + + b. extends LIST to allow for multiple mailbox patterns. + + c. adds LIST command selection options: SUBSCRIBED, REMOTE, and + RECURSIVEMATCH. + + d. adds LIST command return options: SUBSCRIBED and CHILDREN. + + e. adds new mailbox attributes: "\NonExistent", "\Subscribed", + "\Remote", "\HasChildren", and "\HasNoChildren". + + + + +Leiba & Melnikov Standards Track [Page 3] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + f. adds CHILDINFO extended data item. + +2. Conventions Used in This Document + + In examples, "C:" indicates lines sent by a client that is connected + to a server. "S:" indicates lines sent by the server to the client. + + The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" + are used in this document as specified in RFC 2119 [Kwds]. + + The term "canonical LIST pattern" refers to the canonical pattern + constructed internally by the server from the reference and mailbox + name arguments (Section 6.3.8 of [IMAP4]). The [IMAP4] LIST command + returns only mailboxes that match the canonical LIST pattern. + + Other terms are introduced where they are referenced for the first + time. + +3. Extended LIST Command + + This extension updates the syntax of the LIST command to allow for + multiple mailbox patterns to be specified, if they are enclosed in + parentheses. A mailbox name matches a list of mailbox patterns if it + matches at least one mailbox pattern. If a mailbox name matches + multiple mailbox patterns from the list, the server SHOULD return + only a single LIST response. + + Note that the non-extended LIST command is required to treat an empty + ("" string) mailbox name argument as a special request to return the + hierarchy delimiter and the root name of the name given in the + reference parameter (as per [IMAP4]). However, ANY extended LIST + command (extended in any of 3 ways specified in Section 1, or any + combination thereof) MUST NOT treat the empty mailbox name as such a + special request, and any regular processing described in this + document applies. In particular, if an extended LIST command has + multiple mailbox names and one (or more) of them is the empty string, + the empty string MUST be ignored for the purpose of matching. + + Some servers might restrict which patterns are allowed in a LIST + command. If a server doesn't accept a particular pattern, it MUST + silently ignore it. + + The LIST command syntax is also extended in two additional ways: by + adding a parenthesized list of command options between the command + name and the reference name (LIST selection options) and an optional + + + + + + +Leiba & Melnikov Standards Track [Page 4] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + list of options at the end that control what kind of information + should be returned (LIST return options). See the formal syntax in + Section 6 for specific details. + + A LIST selection option tells the server which mailbox names should + be selected by the LIST operation. The server should return + information about all mailbox names that match any of the "canonical + LIST pattern" (as described above) and satisfy additional selection + criteria (if any) specified by the LIST selection options. Let's + call any such mailbox name a "matched mailbox name". When multiple + selection options are specified, the server MUST return information + about mailbox names that satisfy every selection option, unless a + description of a particular specified option prescribes special + rules. An example of an option prescribing special rules is the + RECURSIVEMATCH selection option described later in this section. We + will use the term "selection criteria" when referring collectively to + all selection options specified in a LIST command. + + A LIST return option controls which information is returned for each + matched mailbox name. Note that return options MUST NOT cause the + server to report information about additional mailbox names. If the + client has not specified any return option, only information about + attributes should be returned by the server. (Of course, the server + is allowed to include any other information at will.) + + Both selection and return command options will be defined in this + document and in approved extension documents; each option will be + enabled by a capability string (one capability may enable multiple + options), and a client MUST NOT send an option for which the server + has not advertised support. A server MUST respond to options it does + not recognize with a BAD response. The client SHOULD NOT specify any + option more than once; however, if the client does this, the server + MUST act as if it received the option only once. The order in which + options are specified by the client is not significant. + + In general, each selection option except RECURSIVEMATCH will have a + corresponding return option. The REMOTE selection option is an + anomaly in this regard, and does not have a corresponding return + option. That is because it expands, rather than restricts, the set + of mailboxes that are returned. Future extensions to this + specification should keep parallelism in mind and define a pair of + corresponding options. + + This extension is identified by the capability string + "LIST-EXTENDED", and support for it is a prerequisite for any future + extensions that require specialized forms of the LIST command. Such + extensions MUST refer to this document and MUST add their function + through command options as described herein. Note that extensions + + + +Leiba & Melnikov Standards Track [Page 5] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + that don't require support for an extended LIST command, but use + extended LIST responses (see below), don't need to advertise the + "LIST-EXTENDED" capability string. + + This extension also defines extensions to the LIST response, allowing + a series of extended fields at the end, a parenthesized list of + tagged data (also referred to as "extended data item"). The first + element of an extended field is a tag, which identifies the type of + data. Tags MUST be registered with IANA, as described in Section 9.5 + of this document. An example of such an extended set might be + + tablecloth (("edge" "lacy") ("color" "red"))) (X-Sample "text")) + + or + + tablecloth ("edge" "lacy")) (X-Sample "text" "more text")) + + See the formal syntax, in Section 6, for the full syntactic details. + The server MUST NOT return any extended data item unless the client + has expressed its ability to support extended LIST responses, for + example, by using an extended LIST command. The server MAY return + data in the extended fields that was not directly solicited by the + client in the corresponding LIST command. For example, the client + can enable extra extended fields by using another IMAP extension that + make use of the extended LIST responses. The client MUST ignore all + extended fields it doesn't recognize. + + The LIST-EXTENDED capability also defines several new mailbox + attributes. + + The "\NonExistent" attribute indicates that a mailbox name does not + refer to an existing mailbox. Note that this attribute is not + meaningful by itself, as mailbox names that match the canonical LIST + pattern but don't exist must not be returned unless one of the two + conditions listed below is also satisfied: + + a. The mailbox name also satisfies the selection criteria (for + example, it is subscribed and the "SUBSCRIBED" selection option + has been specified). + + b. "RECURSIVEMATCH" has been specified, and the mailbox name has at + least one descendant mailbox name that does not match the LIST + pattern and does match the selection criteria. + + In practice, this means that the "\NonExistent" attribute is usually + returned with one or more of "\Subscribed", "\Remote", + "\HasChildren", or the CHILDINFO extended data item (see their + description below). + + + +Leiba & Melnikov Standards Track [Page 6] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + The "\NonExistent" attribute implies "\NoSelect". The "\NonExistent" + attribute MUST be supported and MUST be accurately computed. + +3.1. Initial List of Selection Options + + The selection options defined in this specification are as follows: + + SUBSCRIBED - causes the LIST command to list subscribed names, + rather than the existing mailboxes. This will often be a subset + of the actual mailboxes. It's also possible for this list to + contain the names of mailboxes that don't exist. In any case, the + list MUST include exactly those mailbox names that match the + canonical list pattern and are subscribed to. This option is + intended to supplement the LSUB command. Of particular note are + the mailbox attributes as returned by this option, compared with + what is returned by LSUB. With the latter, the attributes + returned may not reflect the actual attribute status on the + mailbox name, and the \NoSelect attribute has a second special + meaning (it indicates that this mailbox is not, itself, + subscribed, but that it has descendant mailboxes that are). With + the SUBSCRIBED selection option described here, the attributes are + accurate and complete, and have no special meanings. "LSUB" and + "LIST (SUBSCRIBED)" are, thus, not the same thing, and some + servers must do significant extra work to respond to "LIST + (SUBSCRIBED)". Because of this, clients SHOULD continue to use + "LSUB" unless they specifically want the additional information + offered by "LIST (SUBSCRIBED)". + + This option defines a new mailbox attribute, "\Subscribed", that + indicates that a mailbox name is subscribed to. The "\Subscribed" + attribute MUST be supported and MUST be accurately computed when + the SUBSCRIBED selection option is specified. + + Note that the SUBSCRIBED selection option implies the SUBSCRIBED + return option (see below). + + REMOTE - causes the LIST command to show remote mailboxes as well as + local ones, as described in [MBRef]. This option is intended to + replace the RLIST command and, in conjunction with the SUBSCRIBED + selection option, the RLSUB command. + + This option defines a new mailbox attribute, "\Remote", that + indicates that a mailbox is a remote mailbox. The "\Remote" + attribute MUST be accurately computed when the REMOTE option is + specified. + + The REMOTE selection option has no interaction with other options. + Its effect is to tell the server to apply the other options, if + + + +Leiba & Melnikov Standards Track [Page 7] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + any, to remote mailboxes, in addition to local ones. In + particular, it has no interaction with RECURSIVEMATCH (see below). + A request for (REMOTE RECURSIVEMATCH) is invalid, because a + request for (RECURSIVEMATCH) is. A request for (REMOTE + RECURSIVEMATCH SUBSCRIBED) is asking for all subscribed mailboxes, + both local and remote. + + RECURSIVEMATCH - this option forces the server to return information + about parent mailboxes that don't match other selection options, + but have some submailboxes that do. Information about children is + returned in the CHILDINFO extended data item, as described in + Section 3.5. + + Note 1: In order for a parent mailbox to be returned, it still has + to match the canonical LIST pattern. + + Note 2: When returning the CHILDINFO extended data item, it + doesn't matter whether or not the submailbox matches the canonical + LIST pattern. See also example 9 in Section 5. + + The RECURSIVEMATCH option MUST NOT occur as the only selection + option (or only with REMOTE), as it only makes sense when other + selection options are also used. The server MUST return BAD + tagged response in such case. + + Note that even if the RECURSIVEMATCH option is specified, the + client MUST still be able to handle a case when a CHILDINFO + extended data item is returned and there are no submailboxes that + meet the selection criteria of the subsequent LIST command, as + they can be deleted/renamed after the LIST response was sent, but + before the client had a chance to access them. + +3.2. Initial List of Return Options + + The return options defined in this specification are as follows: + + SUBSCRIBED - causes the LIST command to return subscription state + for all matching mailbox names. The "\Subscribed" attribute MUST + be supported and MUST be accurately computed when the SUBSCRIBED + return option is specified. Further, all mailbox flags MUST be + accurately computed (this differs from the behavior of the LSUB + command). + + CHILDREN - requests mailbox child information as originally proposed + in [CMbox]. See Section 4, below, for details. This option MUST + be supported by all servers. + + + + + +Leiba & Melnikov Standards Track [Page 8] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + +3.3. General Principles for Returning LIST Responses + + This section outlines several principles that can be used by server + implementations of this document to decide whether a LIST response + should be returned, as well as how many responses and what kind of + information they may contain. + + 1. At most one LIST response should be returned for each mailbox + name that matches the canonical LIST pattern. Server + implementors must not assume that clients will be able to + assemble mailbox attributes and other information returned in + multiple LIST responses. + + 2. There are only two reasons for including a matching mailbox name + in the responses to the LIST command (note that the server is + allowed to return unsolicited responses at any time, and such + responses are not governed by this rule): + + A. The mailbox name also satisfies the selection criteria. + + B. The mailbox name doesn't satisfy the selection criteria, but + it has at least one descendant mailbox name that satisfies + the selection criteria and that doesn't match the canonical + LIST pattern. + + For more information on this case, see the CHILDINFO extended + data item described in Section 3.5. Note that the CHILDINFO + extended data item can only be returned when the + RECURSIVEMATCH selection option is specified. + + 3. Attributes returned in the same LIST response must be treated + additively. For example, the following response + + S: * LIST (\Subscribed \NonExistent) "/" "Fruit/Peach" + + means that the "Fruit/Peach" mailbox doesn't exist, but it is + subscribed. + +3.4. Additional Requirements on LIST-EXTENDED Clients + + All clients that support this extension MUST treat an attribute with + a stronger meaning as implying any attribute that can be inferred + from it. For example, the client must treat the presence of the + \NoInferiors attribute as if the \HasNoChildren attribute was also + sent by the server. + + + + + + +Leiba & Melnikov Standards Track [Page 9] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + The following table summarizes inference rules described in + Section 3. + + +--------------------+-------------------+ + | returned attribute | implied attribute | + +--------------------+-------------------+ + | \NoInferiors | \HasNoChildren | + | \NonExistent | \NoSelect | + +--------------------+-------------------+ + +3.5. CHILDINFO Extended Data Item + + The CHILDINFO extended data item MUST NOT be returned unless the + client has specified the RECURSIVEMATCH selection option. + + The CHILDINFO extended data item in a LIST response describes the + selection criteria that has caused it to be returned and indicates + that the mailbox has at least one descendant mailbox that matches the + selection criteria. + + The LSUB command indicates this condition by using the "\NoSelect" + attribute, but the LIST (SUBSCRIBED) command MUST NOT do that, since + "\NoSelect" retains its original meaning here. Further, the + CHILDINFO extended data item is more general, in that it can be used + with any extended set of selection criteria. + + Note: Some servers allow for mailboxes to exist without requiring + their parent to exist. For example, a mailbox "Customers/ABC" can + exist while the mailbox "Customers" does not. As CHILDINFO extended + data item is not allowed if the RECURSIVEMATCH selection option is + not specified, such servers SHOULD use the "\NonExistent + \HasChildren" attribute pair to signal to the client that there is a + descendant mailbox that matches the selection criteria. See example + 11 in Section 5. + + The returned selection criteria allow the client to distinguish a + solicited response from an unsolicited one, as well as to distinguish + among solicited responses caused by multiple pipelined LIST commands + that specify different criteria. + + Servers SHOULD ONLY return a non-matching mailbox name along with + CHILDINFO if at least one matching child is not also being returned. + That is, servers SHOULD suppress redundant CHILDINFO responses. + + Examples 8 and 10 in Section 5 demonstrate the difference between + present CHILDINFO extended data item and the "\HasChildren" + attribute. + + + + +Leiba & Melnikov Standards Track [Page 10] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + The following table summarizes interaction between the "\NonExistent" + attribute and CHILDINFO (the first column indicates whether the + parent mailbox exists): + + +--------+--------------+--------------------+----------------------+ + | exists | meets the | has a child that | returned | + | | selection | meets the | LIST-EXTENDED | + | | criteria | selection criteria | attributes and | + | | | | CHILDINFO | + +--------+--------------+--------------------+----------------------+ + | no | no | no | no LIST response | + | | | | returned | + | yes | no | no | no LIST response | + | | | | returned | + | no | yes | no | (\NonExistent | + | | | | <attr>) | + | yes | yes | no | (<attr>) | + | no | no | yes | (\NonExistent) + | + | | | | CHILDINFO | + | yes | no | yes | () + CHILDINFO | + | no | yes | yes | (\NonExistent | + | | | | <attr>) + CHILDINFO | + | yes | yes | yes | (<attr>) + CHILDINFO | + +--------+--------------+--------------------+----------------------+ + + where <attr> is one or more attributes that correspond to the + selection criteria; for example, for the SUBSCRIBED option the <attr> + is \Subscribed. + +4. The CHILDREN Return Option + + The CHILDREN return option implements the Child Mailbox Extension, + originally proposed by Mike Gahrns and Raymond Cheng, of Microsoft + Corporation. Most of the information in this section is taken + directly from their original specification [CMbox]. The CHILDREN + return option is simply an indication that the client wants this + information; a server MAY provide it even if the option is not + specified. + + Many IMAP4 [IMAP4] clients present to the user a hierarchical view of + the mailboxes that a user has access to. Rather than initially + presenting to the user the entire mailbox hierarchy, it is often + preferable to show to the user a collapsed outline list of the + mailbox hierarchy (particularly if there is a large number of + mailboxes). The user can then expand the collapsed outline hierarchy + as needed. It is common to include within the collapsed hierarchy a + visual clue (such as a ''+'') to indicate that there are child + mailboxes under a particular mailbox. When the visual clue is + + + +Leiba & Melnikov Standards Track [Page 11] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + clicked, the hierarchy list is expanded to show the child mailboxes. + The CHILDREN return option provides a mechanism for a client to + efficiently determine whether a particular mailbox has children, + without issuing a LIST "" * or a LIST "" % for each mailbox name. + The CHILDREN return option defines two new attributes that MUST be + returned within a LIST response: \HasChildren and \HasNoChildren. + Although these attributes MAY be returned in response to any LIST + command, the CHILDREN return option is provided to indicate that the + client particularly wants this information. If the CHILDREN return + option is present, the server MUST return these attributes even if + their computation is expensive. + + \HasChildren + + The presence of this attribute indicates that the mailbox has child + mailboxes. A server SHOULD NOT set this attribute if there are + child mailboxes and the user does not have permission to access + any of them. In this case, \HasNoChildren SHOULD be used. In + many cases, however, a server may not be able to efficiently + compute whether a user has access to any child mailbox. Note + that even though the \HasChildren attribute for a mailbox must + be correct at the time of processing of the mailbox, a client + must be prepared to deal with a situation when a mailbox is + marked with the \HasChildren attribute, but no child mailbox + appears in the response to the LIST command. This might happen, + for example, due to children mailboxes being deleted or made + inaccessible to the user (using access control) by another + client before the server is able to list them. + + \HasNoChildren + + The presence of this attribute indicates that the mailbox has NO + child mailboxes that are accessible to the currently + authenticated user. + + It is an error for the server to return both a \HasChildren and a + \HasNoChildren attribute in the same LIST response. + + Note: the \HasNoChildren attribute should not be confused with the + IMAP4 [IMAP4] defined attribute \NoInferiors, which indicates that no + child mailboxes exist now and none can be created in the future. + + + + + + + + + + +Leiba & Melnikov Standards Track [Page 12] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + +5. Examples + + 1: The first example shows the complete local hierarchy that will + be used for the other examples. + + C: A01 LIST "" "*" + S: * LIST (\Marked \NoInferiors) "/" "inbox" + S: * LIST () "/" "Fruit" + S: * LIST () "/" "Fruit/Apple" + S: * LIST () "/" "Fruit/Banana" + S: * LIST () "/" "Tofu" + S: * LIST () "/" "Vegetable" + S: * LIST () "/" "Vegetable/Broccoli" + S: * LIST () "/" "Vegetable/Corn" + S: A01 OK done + + 2: In the next example, we will see the subscribed mailboxes. This + is similar to, but not equivalent with, <LSUB "" "*">. Note + that the mailbox called "Fruit/Peach" is subscribed to, but does + not actually exist (perhaps it was deleted while still + subscribed). The "Fruit" mailbox is not subscribed to, but it + has two subscribed children. The "Vegetable" mailbox is + subscribed and has two children; one of them is subscribed as + well. + + C: A02 LIST (SUBSCRIBED) "" "*" + S: * LIST (\Marked \NoInferiors \Subscribed) "/" "inbox" + S: * LIST (\Subscribed) "/" "Fruit/Banana" + S: * LIST (\Subscribed \NonExistent) "/" "Fruit/Peach" + S: * LIST (\Subscribed) "/" "Vegetable" + S: * LIST (\Subscribed) "/" "Vegetable/Broccoli" + S: A02 OK done + + 3: The next example shows the use of the CHILDREN option. The + client, without having to list the second level of hierarchy, + now knows which of the top-level mailboxes have submailboxes + (children) and which do not. Note that it's not necessary for + the server to return the \HasNoChildren attribute for the inbox, + because the \NoInferiors attribute already implies that, and has + a stronger meaning. + + C: A03 LIST () "" "%" RETURN (CHILDREN) + S: * LIST (\Marked \NoInferiors) "/" "inbox" + S: * LIST (\HasChildren) "/" "Fruit" + S: * LIST (\HasNoChildren) "/" "Tofu" + S: * LIST (\HasChildren) "/" "Vegetable" + S: A03 OK done + + + + +Leiba & Melnikov Standards Track [Page 13] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + 4: In this example, we see more mailboxes that reside on another + server. This is similar to the command <RLIST "" "%">. + + C: A04 LIST (REMOTE) "" "%" RETURN (CHILDREN) + S: * LIST (\Marked \NoInferiors) "/" "inbox" + S: * LIST (\HasChildren) "/" "Fruit" + S: * LIST (\HasNoChildren) "/" "Tofu" + S: * LIST (\HasChildren) "/" "Vegetable" + S: * LIST (\Remote) "/" "Bread" + S: * LIST (\HasChildren \Remote) "/" "Meat" + S: A04 OK done + + 5: The following example also requests the server to include + mailboxes that reside on another server. The server returns + information about all mailboxes that are subscribed. This is + similar to the command <RLSUB "" "*">. We also see the use of + two selection options. + + C: A05 LIST (REMOTE SUBSCRIBED) "" "*" + S: * LIST (\Marked \NoInferiors \Subscribed) "/" "inbox" + S: * LIST (\Subscribed) "/" "Fruit/Banana" + S: * LIST (\Subscribed \NonExistent) "/" "Fruit/Peach" + S: * LIST (\Subscribed) "/" "Vegetable" + S: * LIST (\Subscribed) "/" "Vegetable/Broccoli" + S: * LIST (\Remote \Subscribed) "/" "Bread" + S: A05 OK done + + 6: The following example requests the server to include mailboxes + that reside on another server. The server is asked to return + subscription information for all returned mailboxes. This is + different from the example above. + + Note that the output of this command is not a superset of the + output in the previous example, as it doesn't include LIST + response for the non-existent "Fruit/Peach". + + C: A06 LIST (REMOTE) "" "*" RETURN (SUBSCRIBED) + S: * LIST (\Marked \NoInferiors \Subscribed) "/" "inbox" + S: * LIST () "/" "Fruit" + S: * LIST () "/" "Fruit/Apple" + S: * LIST (\Subscribed) "/" "Fruit/Banana" + S: * LIST () "/" "Tofu" + S: * LIST (\Subscribed) "/" "Vegetable" + S: * LIST (\Subscribed) "/" "Vegetable/Broccoli" + S: * LIST () "/" "Vegetable/Corn" + S: * LIST (\Remote \Subscribed) "/" "Bread" + S: * LIST (\Remote) "/" "Meat" + S: A06 OK done + + + +Leiba & Melnikov Standards Track [Page 14] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + 7: In the following example, the client has specified multiple + mailbox patterns. Note that this example does not use the + mailbox hierarchy used in the previous examples. + + C: BBB LIST "" ("INBOX" "Drafts" "Sent/%") + S: * LIST () "/" "INBOX" + S: * LIST (\NoInferiors) "/" "Drafts" + S: * LIST () "/" "Sent/March2004" + S: * LIST (\Marked) "/" "Sent/December2003" + S: * LIST () "/" "Sent/August2004" + S: BBB OK done + + 8: The following example demonstrates the difference between the + \HasChildren attribute and the CHILDINFO extended data item. + + Let's assume there is the following hierarchy: + + C: C01 LIST "" "*" + S: * LIST (\Marked \NoInferiors) "/" "inbox" + S: * LIST () "/" "Foo" + S: * LIST () "/" "Foo/Bar" + S: * LIST () "/" "Foo/Baz" + S: * LIST () "/" "Moo" + S: C01 OK done + + If the client asks RETURN (CHILDREN), it will get this: + + C: CA3 LIST "" "%" RETURN (CHILDREN) + S: * LIST (\Marked \NoInferiors) "/" "inbox" + S: * LIST (\HasChildren) "/" "Foo" + S: * LIST (\HasNoChildren) "/" "Moo" + S: CA3 OK done + + A) Let's also assume that the mailbox "Foo/Baz" is the only + subscribed mailbox. Then we get this result: + + C: C02 LIST (SUBSCRIBED) "" "*" + S: * LIST (\Subscribed) "/" "Foo/Baz" + S: C02 OK done + + Now, if the client issues <LIST (SUBSCRIBED) "" "%">, the server will + return no mailboxes (as the mailboxes "Moo", "Foo", and "Inbox" are + NOT subscribed). However, if the client issues this: + + C: C04 LIST (SUBSCRIBED RECURSIVEMATCH) "" "%" + S: * LIST () "/" "Foo" ("CHILDINFO" ("SUBSCRIBED")) + S: C04 OK done + + + + +Leiba & Melnikov Standards Track [Page 15] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + (i.e., the mailbox "Foo" is not subscribed, but it has a child that + is.) + + A1) If the mailbox "Foo" had also been subscribed, the last command + would return this: + + C: C04 LIST (SUBSCRIBED RECURSIVEMATCH) "" "%" + S: * LIST (\Subscribed) "/" "Foo" ("CHILDINFO" ("SUBSCRIBED")) + S: C04 OK done + + or even this: + + C: C04 LIST (SUBSCRIBED RECURSIVEMATCH) "" "%" + S: * LIST (\Subscribed \HasChildren) "/" "Foo" ("CHILDINFO" + ("SUBSCRIBED")) + S: C04 OK done + + A2) If we assume instead that the mailbox "Foo" is not part of the + original hierarchy and is not subscribed, the last command will give + this result: + + C: C04 LIST (SUBSCRIBED RECURSIVEMATCH) "" "%" + S: * LIST (\NonExistent) "/" "Foo" ("CHILDINFO" ("SUBSCRIBED")) + S: C04 OK done + + B) Now, let's assume that no mailbox is subscribed. In this case, + the command <LIST (SUBSCRIBED RECURSIVEMATCH) "" "%"> will return no + responses, as there are no subscribed children (even though "Foo" has + children). + + C) And finally, suppose that only the mailboxes "Foo" and "Moo" are + subscribed. In that case, we see this result: + + C: C04 LIST (SUBSCRIBED RECURSIVEMATCH) "" "%" RETURN (CHILDREN) + S: * LIST (\HasChildren \Subscribed) "/" "Foo" + S: * LIST (\HasNoChildren \Subscribed) "/" "Moo" + S: C04 OK done + + (which means that the mailbox "Foo" has children, but none of them is + subscribed). + + 9: The following example demonstrates that the CHILDINFO extended + data item is returned whether or not children mailboxes match + the canonical LIST pattern. + + + + + + + +Leiba & Melnikov Standards Track [Page 16] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + Let's assume there is the following hierarchy: + + C: D01 LIST "" "*" + S: * LIST (\Marked \NoInferiors) "/" "inbox" + S: * LIST () "/" "foo2" + S: * LIST () "/" "foo2/bar1" + S: * LIST () "/" "foo2/bar2" + S: * LIST () "/" "baz2" + S: * LIST () "/" "baz2/bar2" + S: * LIST () "/" "baz2/bar22" + S: * LIST () "/" "baz2/bar222" + S: * LIST () "/" "eps2" + S: * LIST () "/" "eps2/mamba" + S: * LIST () "/" "qux2/bar2" + S: D01 OK done + + And that the following mailboxes are subscribed: + + C: D02 LIST (SUBSCRIBED) "" "*" + S: * LIST (\Subscribed) "/" "foo2/bar1" + S: * LIST (\Subscribed) "/" "foo2/bar2" + S: * LIST (\Subscribed) "/" "baz2/bar2" + S: * LIST (\Subscribed) "/" "baz2/bar22" + S: * LIST (\Subscribed) "/" "baz2/bar222" + S: * LIST (\Subscribed) "/" "eps2" + S: * LIST (\Subscribed) "/" "eps2/mamba" + S: * LIST (\Subscribed) "/" "qux2/bar2" + S: D02 OK done + + The client issues the following command first: + + C: D03 LIST (RECURSIVEMATCH SUBSCRIBED) "" "*2" + S: * LIST () "/" "foo2" ("CHILDINFO" ("SUBSCRIBED")) + S: * LIST (\Subscribed) "/" "foo2/bar2" + S: * LIST (\Subscribed) "/" "baz2/bar2" + S: * LIST (\Subscribed) "/" "baz2/bar22" + S: * LIST (\Subscribed) "/" "baz2/bar222" + S: * LIST (\Subscribed) "/" "eps2" ("CHILDINFO" ("SUBSCRIBED")) + S: * LIST (\Subscribed) "/" "qux2/bar2" + S: D03 OK done + + and the server may also include (but this would violate a SHOULD NOT + in Section 3.5, because CHILDINFO is redundant) + + S: * LIST () "/" "baz2" ("CHILDINFO" ("SUBSCRIBED")) + S: * LIST (\NonExistent) "/" "qux2" ("CHILDINFO" ("SUBSCRIBED")) + + + + + +Leiba & Melnikov Standards Track [Page 17] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + The CHILDINFO extended data item is returned for mailboxes "foo2", + "baz2", and "eps2", because all of them have subscribed children, + even though for the mailbox "foo2" only one of the two subscribed + children matches the pattern, for the mailbox "baz2" all the + subscribed children match the pattern, and for the mailbox "eps2" + none of the subscribed children matches the pattern. + + Note that if the client issues + + C: D03 LIST (RECURSIVEMATCH SUBSCRIBED) "" "*" + S: * LIST () "/" "foo2" ("CHILDINFO" ("SUBSCRIBED")) + S: * LIST (\Subscribed) "/" "foo2/bar1" + S: * LIST (\Subscribed) "/" "foo2/bar2" + S: * LIST () "/" "baz2" ("CHILDINFO" ("SUBSCRIBED")) + S: * LIST (\Subscribed) "/" "baz2/bar2" + S: * LIST (\Subscribed) "/" "baz2/bar22" + S: * LIST (\Subscribed) "/" "baz2/bar222" + S: * LIST (\Subscribed) "/" "eps2" ("CHILDINFO" ("SUBSCRIBED")) + S: * LIST (\Subscribed) "/" "eps2/mamba" + S: * LIST (\Subscribed) "/" "qux2/bar2" + S: D03 OK done + + The LIST responses for mailboxes "foo2", "baz2", and "eps2" still + have the CHILDINFO extended data item, even though this information + is redundant and the client can determine it by itself. + + 10: The following example shows usage of multiple mailbox patterns. + It also demonstrates that the presence of the CHILDINFO extended + data item doesn't necessarily imply \HasChildren. + + C: a1 LIST "" ("foo" "foo/*") + S: * LIST () "/" foo + S: a1 OK done + + C: a2 LIST (SUBSCRIBED) "" "foo/*" + S: * LIST (\Subscribed \NonExistent) "/" foo/bar + S: a2 OK done + + C: a3 LIST (SUBSCRIBED RECURSIVEMATCH) "" foo RETURN (CHILDREN) + S: * LIST (\HasNoChildren) "/" foo ("CHILDINFO" ("SUBSCRIBED")) + S: a3 OK done + + 11: The following example shows how a server that supports missing + mailbox hierarchy elements can signal to a client that didn't + specify the RECURSIVEMATCH selection option that there is a + child mailbox that matches the selection criteria. + + + + + +Leiba & Melnikov Standards Track [Page 18] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + C: a1 LIST (REMOTE) "" * + S: * LIST () "/" music/rock + S: * LIST (\Remote) "/" also/jazz + S: a1 OK done + + C: a2 LIST () "" % + S: * LIST (\NonExistent \HasChildren) "/" music + S: a2 OK done + + C: a3 LIST (REMOTE) "" % + S: * LIST (\NonExistent \HasChildren) "/" music + S: * LIST (\NonExistent \HasChildren) "/" also + S: a3 OK done + + C: a3.1 LIST "" (% music/rock) + S: * LIST () "/" music/rock + S: a3.1 OK done + + Because "music/rock" is the only mailbox under "music", there's no + need for the server to also return "music". However clients must + handle both cases. + +6. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) as described in [ABNF]. Terms not defined here are taken + from [IMAP4]. In particular, note that the version of "mailbox-list" + below, which defines the payload of the LIST response, updates the + version defined in the IMAP specification. It is pointed to by + "mailbox-data", which is defined in [IMAP4]. + + "vendor-token" is defined in [ACAP]. Note that this normative + reference to ACAP will be an issue in moving this spec forward, since + it introduces a dependency on ACAP. The definitions of + "vendor-token" and of the IANA registry must eventually go somewhere + else, in a document that can be moved forward on the standards track + independently of ACAP. + + + + + + + + + + + + + + +Leiba & Melnikov Standards Track [Page 19] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + childinfo-extended-item = "CHILDINFO" SP "(" + list-select-base-opt-quoted + *(SP list-select-base-opt-quoted) ")" + ; Extended data item (mbox-list-extended-item) + ; returned when the RECURSIVEMATCH + ; selection option is specified. + ; Note 1: the CHILDINFO tag can be returned + ; with and without surrounding quotes, as per + ; mbox-list-extended-item-tag production. + ; Note 2: The selection options are always returned + ; quoted, unlike their specification in + ; the extended LIST command. + + child-mbox-flag = "\HasChildren" / "\HasNoChildren" + ; attributes for CHILDREN return option, at most one + ; possible per LIST response + + eitem-standard-tag = atom + ; a tag for extended list data defined in a Standard + ; Track or Experimental RFC. + + eitem-vendor-tag = vendor-token "-" atom + ; a vendor-specific tag for extended list data + + list = "LIST" [SP list-select-opts] SP mailbox SP mbox-or-pat + [SP list-return-opts] + + list-return-opts = "RETURN" SP + "(" [return-option *(SP return-option)] ")" + ; list return options, e.g., CHILDREN + + list-select-base-opt = "SUBSCRIBED" / option-extension + ; options that can be used by themselves + + list-select-base-opt-quoted = DQUOTE list-select-base-opt DQUOTE + + list-select-independent-opt = "REMOTE" / option-extension + ; options that do not syntactically interact with + ; other options + + list-select-mod-opt = "RECURSIVEMATCH" / option-extension + ; options that require a list-select-base-opt + ; to also be present + + list-select-opt = list-select-base-opt / list-select-independent-opt + / list-select-mod-opt + ; An option registration template is described in + ; Section 9.3 of this document. + + + +Leiba & Melnikov Standards Track [Page 20] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + list-select-opts = "(" [ + (*(list-select-opt SP) list-select-base-opt + *(SP list-select-opt)) + / (list-select-independent-opt + *(SP list-select-independent-opt)) + ] ")" + ; Any number of options may be in any order. + ; If a list-select-mod-opt appears, then a + ; list-select-base-opt must also appear. + ; This allows these: + ; () + ; (REMOTE) + ; (SUBSCRIBED) + ; (SUBSCRIBED REMOTE) + ; (SUBSCRIBED RECURSIVEMATCH) + ; (SUBSCRIBED REMOTE RECURSIVEMATCH) + ; But does NOT allow these: + ; (RECURSIVEMATCH) + ; (REMOTE RECURSIVEMATCH) + + mailbox-list = "(" [mbx-list-flags] ")" SP + (DQUOTE QUOTED-CHAR DQUOTE / nil) SP mailbox + [SP mbox-list-extended] + ; This is the list information pointed to by the ABNF + ; item "mailbox-data", which is defined in [IMAP4] + + mbox-list-extended = "(" [mbox-list-extended-item + *(SP mbox-list-extended-item)] ")" + + mbox-list-extended-item = mbox-list-extended-item-tag SP + tagged-ext-val + + mbox-list-extended-item-tag = astring + ; The content MUST conform to either "eitem-vendor-tag" + ; or "eitem-standard-tag" ABNF productions. + ; A tag registration template is described in this + ; document in Section 9.5. + + mbx-list-oflag =/ child-mbox-flag / "\Subscribed" / "\Remote" + + mbx-list-sflag =/ "\NonExistent" + + mbox-or-pat = list-mailbox / patterns + + option-extension = (option-standard-tag / option-vendor-tag) + [SP option-value] + + + + + +Leiba & Melnikov Standards Track [Page 21] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + option-standard-tag = atom + ; an option defined in a Standards Track or + ; Experimental RFC + + option-val-comp = astring / + option-val-comp *(SP option-val-comp) / + "(" option-val-comp ")" + + option-value = "(" option-val-comp ")" + + option-vendor-tag = vendor-token "-" atom + ; a vendor-specific option, non-standard + + patterns = "(" list-mailbox *(SP list-mailbox) ")" + + return-option = "SUBSCRIBED" / "CHILDREN" / option-extension + + tagged-ext-comp = astring / + tagged-ext-comp *(SP tagged-ext-comp) / + "(" tagged-ext-comp ")" + ; Extensions that follow this general + ; syntax should use nstring instead of + ; astring when appropriate in the context + ; of the extension. + ; Note that a message set or a "number" + ; can always be represented as an "atom". + ; A URL should be represented as + ; a "quoted" string. + + tagged-ext-simple = sequence-set / number + + tagged-ext-val = tagged-ext-simple / + "(" [tagged-ext-comp] ")" + +7. Internationalization Considerations + + The LIST command selection option types defined in this specification + involve simple tests of mailbox properties. However, future + extensions to LIST-EXTENDED may define selection options that do more + sophisticated tests. In the case of a test that requires matching + text, in the presence of the COMPARATOR [I18N] extension, the active + comparator must be used to do comparisons. Such LIST-EXTENDED + extensions MUST indicate in their specification the interaction with + the COMPARATOR [I18N] extension. + + + + + + + +Leiba & Melnikov Standards Track [Page 22] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + +8. Security Considerations + + This document describes syntactic changes to the specification of the + IMAP4 commands LIST, LSUB, RLIST, and RLSUB, and the modified LIST + command has the same security considerations as those commands. They + are described in [IMAP4] and [MBRef]. + + The Child Mailbox Extension provides a client a more efficient means + of determining whether a particular mailbox has children. If a + mailbox has children, but the currently authenticated user does not + have access to any of them, the server SHOULD respond with a + \HasNoChildren attribute. In many cases, however, a server may not + be able to efficiently compute whether a user has access to any child + mailbox. If such a server responds with a \HasChildren attribute, + when in fact the currently authenticated user does not have access to + any child mailboxes, potentially more information is conveyed about + the mailbox than intended. In most situations, this will not be a + security concern, because if information regarding whether a mailbox + has children is considered sensitive, a user would not be granted + access to that mailbox in the first place. + + The CHILDINFO extended data item has the same security considerations + as the \HasChildren attribute described above. + +9. IANA Considerations + +9.1. Guidelines for IANA + + IANA has created two new registries for LIST-EXTENDED options and + LIST-EXTENDED response data. The templates and the initial + registrations are detailed below. + +9.2. Registration Procedure and Change Control + + Registration of a LIST-EXTENDED option is done by filling in the + template in Section 9.3 and sending it via electronic mail to + iana@iana.org. Registration of a LIST-EXTENDED extended data item is + done by filling in the template in Section 9.5 and sending it via + electronic mail to iana@iana.org. IANA has the right to reject + obviously bogus registrations, but will perform no review of claims + made in the registration form. + + A LIST-EXTENDED option/extended data item name that starts with "V-" + is reserved for vendor-specific options/extended data items. All + options, whether they are vendor specific or global, should be + registered with IANA. If a LIST-EXTENDED extended data item is + returned as a result of requesting a particular LIST-EXTENDED option, + + + + +Leiba & Melnikov Standards Track [Page 23] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + the name of the option SHOULD be used as the name of the + LIST-EXTENDED extended data item. + + Each vendor-specific option/extended data item MUST start with its + vendor-token ("vendor prefix"). The vendor-token MUST be registered + with IANA, using the [ACAP] vendor subtree registry. + + Standard LIST-EXTENDED option/extended data item names are case + insensitive. If the vendor prefix is omitted from a vendor-specific + LIST-EXTENDED option/extended data item name, the rest is case + insensitive. The vendor prefix itself is not case sensitive, as it + might contain non-ASCII characters. While the registration + procedures do not require it, authors of + LIST-EXTENDED options/extended data items are encouraged to seek + community review and comment whenever that is feasible. Authors may + seek community review by posting a specification of their proposed + mechanism as an + Internet-Draft. LIST-EXTENDED option/extended data items intended + for widespread use should be standardized through the normal IETF + process, when appropriate. + + Comments on registered LIST-EXTENDED options/extended response data + should first be sent to the "owner" of the mechanism and/or to the + IMAPEXT WG mailing list. Submitters of comments may, after a + reasonable attempt to contact the owner, request IANA to attach their + comment to the registration itself. If IANA approves of this, the + comment will be made accessible in conjunction with the registration + LIST-EXTENDED options/extended response data itself. + + Once a LIST-EXTENDED registration has been published by IANA, the + author may request a change to its definition. The change request + follows the same procedure as the registration request. + + The owner of a LIST-EXTENDED registration may pass responsibility for + the registered option/extended data item to another person or agency + by informing IANA; this can be done without discussion or review. + + The IESG may reassign responsibility for a LIST-EXTENDED + option/extended data item. The most common case of this will be to + enable changes to be made to mechanisms where the author of the + registration has died, has moved out of contact, or is otherwise + unable to make changes that are important to the community. + + LIST-EXTENDED registrations may not be deleted; mechanisms that are + no longer believed appropriate for use can be declared OBSOLETE by a + change to their "intended use" field. Such LIST-EXTENDED + options/extended data items will be clearly marked in the lists + published by IANA. + + + +Leiba & Melnikov Standards Track [Page 24] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + The IESG is considered to be the owner of all LIST-EXTENDED + options/extended data items that are on the IETF standards track. + +9.3. Registration Template for LIST-EXTENDED Options + + To: iana@iana.org + Subject: Registration of LIST-EXTENDED option X + + LIST-EXTENDED option name: + + LIST-EXTENDED option type: (One of SELECTION or RETURN) + + Implied return options(s), if the option type is SELECTION: (zero or + more) + + LIST-EXTENDED option description: + + Published specification (optional, recommended): + + Security considerations: + + Intended usage: + (One of COMMON, LIMITED USE, or OBSOLETE) + + Person and email address to contact for further information: + + Owner/Change controller: + + (Any other information that the author deems interesting may be added + below this line.) + +9.4. Initial LIST-EXTENDED Option Registrations + + The LIST-EXTENDED option registry has been populated with the + following entries: + + 1. To: iana@iana.org + Subject: Registration of LIST-EXTENDED option SUBSCRIBED + + LIST-EXTENDED option name: SUBSCRIBED + + LIST-EXTENDED option type: SELECTION + + Implied return options(s): SUBSCRIBED + + LIST-EXTENDED option description: Causes the LIST command to list + subscribed mailboxes, rather than the actual mailboxes. + + + + +Leiba & Melnikov Standards Track [Page 25] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + Published specification: RFC 5258, Section 3. + + Security considerations: RFC 5258, Section 8. + + Intended usage: COMMON + + Person and email address to contact for further information: + Alexey Melnikov <Alexey.Melnikov@isode.com> + + Owner/Change controller: iesg@ietf.org + + 2. To: iana@iana.org + Subject: Registration of LIST-EXTENDED option REMOTE + + LIST-EXTENDED option name: REMOTE + + LIST-EXTENDED option type: SELECTION + + Implied return options(s): (none) + + LIST-EXTENDED option description: Causes the LIST command to + return remote mailboxes as well as local ones, as described in + RFC 2193. + + Published specification: RFC 5258, Section 3. + + Security considerations: RFC 5258, Section 8. + + Intended usage: COMMON + + Person and email address to contact for further information: + Alexey Melnikov <Alexey.Melnikov@isode.com> + + Owner/Change controller: iesg@ietf.org + + 3. To: iana@iana.org + Subject: Registration of LIST-EXTENDED option SUBSCRIBED + + LIST-EXTENDED option name: SUBSCRIBED + + LIST-EXTENDED option type: RETURN + + LIST-EXTENDED option description: Causes the LIST command to + return subscription state. + + Published specification: RFC 5258, Section 3. + + Security considerations: RFC 5258, Section 8. + + + +Leiba & Melnikov Standards Track [Page 26] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + Intended usage: COMMON + + Person and email address to contact for further information: + Alexey Melnikov <Alexey.Melnikov@isode.com> + + Owner/Change controller: iesg@ietf.org + + 4. To: iana@iana.org + Subject: Registration of LIST-EXTENDED option RECURSIVEMATCH + + LIST-EXTENDED option name: RECURSIVEMATCH + + LIST-EXTENDED option type: SELECTION + + Implied return options(s): (none) + + LIST-EXTENDED option description: Requests that CHILDINFO + extended data item (childinfo-extended-item) is to be returned. + + Published specification: RFC 5258, Section 3. + + Security considerations: RFC 5258, Section 8. + + Intended usage: COMMON + + Person and email address to contact for further information: + Alexey Melnikov <Alexey.Melnikov@isode.com> + + Owner/Change controller: iesg@ietf.org + + 5. To: iana@iana.org + Subject: Registration of LIST-EXTENDED option CHILDREN + + LIST-EXTENDED option name: CHILDREN + + LIST-EXTENDED option type: RETURN + + LIST-EXTENDED option description: Requests mailbox child + information. + + Published specification: RFC 5258, Section 3 and Section 4. + + Security considerations: RFC 5258, Section 8. + + Intended usage: COMMON + + Person and email address to contact for further information: + Alexey Melnikov <Alexey.Melnikov@isode.com> + + + +Leiba & Melnikov Standards Track [Page 27] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + Owner/Change controller: iesg@ietf.org + +9.5. Registration Template for LIST-EXTENDED Extended Data Item + + To: iana@iana.org + Subject: Registration of X LIST-EXTENDED extended data item + + LIST-EXTENDED extended data item tag: + + LIST-EXTENDED extended data item description: + + Which LIST-EXTENDED option(s) (and their types) causes this extended + data item to be returned (if any): + + Published specification (optional, recommended): + + Security considerations: + + Intended usage: + (One of COMMON, LIMITED USE, or OBSOLETE) + + Person and email address to contact for further information: + + Owner/Change controller: + + (Any other information that the author deems interesting may be added + below this line.) + +9.6. Initial LIST-EXTENDED Extended Data Item Registrations + + The LIST-EXTENDED extended data item registry has been populated with + the following entries: + + 1. To: iana@iana.org + Subject: Registration of CHILDINFO LIST-EXTENDED extended data + item + + LIST-EXTENDED extended data item tag: CHILDINFO + + LIST-EXTENDED extended data item description: The CHILDINFO + extended data item describes the selection criteria that has + caused it to be returned and indicates that the mailbox has one + or more child mailboxes that match the selection criteria. + + Which LIST-EXTENDED option(s) (and their types) causes this + extended data item to be returned (if any): RECURSIVEMATCH + selection option + + + + +Leiba & Melnikov Standards Track [Page 28] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + + Published specification: RFC 5258, Section 3.5. + + Security considerations: RFC 5258, Section 8. + + Intended usage: COMMON + + Person and email address to contact for further information: + Alexey Melnikov <Alexey.Melnikov@isode.com> + + Owner/Change controller: iesg@ietf.org + +10. Acknowledgements + + Mike Gahrns and Raymond Cheng of Microsoft Corporation originally + devised the Child Mailbox Extension and proposed it in 1997; the + idea, as well as most of the text in Section 4, is theirs. + + This document is the result of discussions on the IMAP4 and IMAPEXT + mailing lists and is meant to reflect consensus of those groups. In + particular, Mark Crispin, Philip Guenther, Cyrus Daboo, Timo + Sirainen, Ken Murchison, Rob Siemborski, Steve Hole, Arnt + Gulbrandsen, Larry Greenfield, Dave Cridland, and Pete Maclean were + active participants in those discussions or made suggestions to this + document. + +11. References + +11.1. Normative References + + [ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + + [ACAP] Newman, C. and J. Myers, "ACAP -- Application Configuration + Access Protocol", RFC 2244, November 1997. + + [I18N] Newman, C., Gulbrandsen, A., and A. Melnikov, "Internet + Message Access Protocol Internationalization", RFC 5255, + June 2008. + + [IMAP4] Crispin, M., "Internet Message Access Protocol - Version + 4rev1", RFC 3501, March 2003. + + [Kwds] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", RFC 2119, March 1997. + + [MBRef] Gahrns, M., "IMAP4 Mailbox Referrals", RFC 2193, + September 1997. + + + + +Leiba & Melnikov Standards Track [Page 29] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + +11.2. Informative References + + [CMbox] Gahrns, M. and R. Cheng, "The Internet Message Action + Protocol (IMAP4) Child Mailbox Extension", RFC 3348, + July 2002. + +Authors' Addresses + + Barry Leiba + IBM T.J. Watson Research Center + 19 Skyline Drive + Hawthorne, NY 10532 + US + + Phone: +1 914 784 7941 + EMail: leiba@watson.ibm.com + + + Alexey Melnikov + Isode Limited + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: Alexey.Melnikov@isode.com + URI: http://www.melnikov.ca/ + + + + + + + + + + + + + + + + + + + + + + + + +Leiba & Melnikov Standards Track [Page 30] + +RFC 5258 IMAP4 LIST Command Extensions June 2008 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2008). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Leiba & Melnikov Standards Track [Page 31] + diff --git a/imap/docs/rfc/rfc5259.txt b/imap/docs/rfc/rfc5259.txt new file mode 100644 index 00000000..9d6ab8ad --- /dev/null +++ b/imap/docs/rfc/rfc5259.txt @@ -0,0 +1,1683 @@ + + + + + + +Network Working Group A. Melnikov, Ed. +Request for Comments: 5259 Isode Ltd +Category: Standards Track P. Coates, Ed. + Sun Microsystems + July 2008 + + + Internet Message Access Protocol - CONVERT 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 + + CONVERT defines extensions to IMAP allowing clients to request + adaptation and/or transcoding of attachments. Clients can specify + the conversion details or allow servers to decide based on knowledge + of client capabilities, on user or administrator preferences, or on + server settings. + + + + + + + + + + + + + + + + + + + + + + + + + + + +Melnikov & Coates Standards Track [Page 1] + +RFC 5259 IMAP CONVERT extension July 2008 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 + 3. Relation with Other IMAP Specifications . . . . . . . . . . . 4 + 3.1. CAPABILITY Response . . . . . . . . . . . . . . . . . . . 4 + 4. Scope of Conversions . . . . . . . . . . . . . . . . . . . . . 4 + 5. Discovery of Available Conversions . . . . . . . . . . . . . . 4 + 5.1. CONVERSIONS Command . . . . . . . . . . . . . . . . . . . 4 + 5.2. CONVERSION Response . . . . . . . . . . . . . . . . . . . 6 + 6. CONVERT and UID CONVERT Commands . . . . . . . . . . . . . . . 6 + 7. CONVERT Conversion Parameters . . . . . . . . . . . . . . . . 12 + 7.1. Mandatory-to-Implement Conversions and Conversion + Parameters . . . . . . . . . . . . . . . . . . . . . . . . 12 + 7.2. Additional Features for Mobile Usage . . . . . . . . . . . 13 + 8. Request/Response Data Items to CONVERT/UID CONVERT Commands . 14 + 8.1. CONVERTED Untagged Response . . . . . . . . . . . . . . . 14 + 8.2. BODYPARTSTRUCTURE CONVERT Request and Response Item . . . 14 + 8.3. BINARY.SIZE CONVERT Request and Response Item . . . . . . 15 + 8.4. AVAILABLECONVERSIONS CONVERT Request and Response Item . . 16 + 8.5. Implementation Considerations . . . . . . . . . . . . . . 17 + 9. Status Responses and Response Code Extensions . . . . . . . . 17 + 10. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 20 + 11. Manageability Considerations . . . . . . . . . . . . . . . . . 24 + 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 + 12.1. Registration of unknown-character-replacement Media + Type Parameter . . . . . . . . . . . . . . . . . . . . . . 25 + 13. Security Considerations . . . . . . . . . . . . . . . . . . . 26 + 14. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 27 + 15. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28 + 15.1. Normative References . . . . . . . . . . . . . . . . . . . 28 + 15.2. Informative References . . . . . . . . . . . . . . . . . . 29 + + + + + + + + + + + + + + + + + + + +Melnikov & Coates Standards Track [Page 2] + +RFC 5259 IMAP CONVERT extension July 2008 + + +1. Introduction + + This document defines the CONVERT extension to IMAP4 [RFC3501]. + CONVERT provides adaptation and transcoding of body parts as needed + by the client. Conversion (adaptation, transcoding) may be requested + by the client and performed by the server on a best effort basis or, + when requested by the client, decided by the server based on the + server's knowledge of the client capabilities, user or administrator + preferences, or server settings. + + This extension is primarily intended to be useful to mobile clients. + It satisfies requirements specified in [OMA-ME-RD]. + + A server that supports CONVERT can convert body parts to other + formats to be viewed (for example) on a mobile device. The client + can explicitly request a particular conversion or ask the server to + select the best available conversion. When allowed by the client, + the server determines how to convert based on its own strategy (e.g., + based on knowledge of the client as discussed hereafter). If the + server knows the characteristics of the device (out of scope for + CONVERT) or can determine them (for example, using a conversion + parameter containing device type), converted body parts can also be + optimized for capabilities of the device (e.g., form factor of + pictures). The client is able to control conversions using optional + conversion (also referred to as "transcoding" in this document) + parameters. + + This document relies on the registry of conversion parameters + established by [MEDIAFEAT-REG]. The registry can be used to discover + the underlying legal values that these parameters can take. + Additional conversion parameters, such as those defined by [OMA-STI], + are expected to be registered in the future. + +2. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + In examples, "C:" and "S:" indicate lines sent by the client and + server, respectively. 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 [...] mean that something has been + elided. + + + + + + +Melnikov & Coates Standards Track [Page 3] + +RFC 5259 IMAP CONVERT extension July 2008 + + + When describing the general syntax, some definitions are omitted as + they are defined in [RFC3501]. In particular, the term "session" is + used in this document as defined in Section 1.2 of [RFC3501]. + +3. Relation with Other IMAP Specifications + + Conversion of attachments during streaming is out of scope for the + CONVERT extension and is described in a separate Lemonade WG document + [LEM-STREAMING]. + + A server claiming compliance with this specification MUST support the + IMAP Binary specification [RFC3516]. + +3.1. CAPABILITY Response + + A server that supports the CONVERT extension MUST return "CONVERT" + and "BINARY" in the CAPABILITY response or response code. (Client + and server authors are reminded that the order of tokens returned in + the CAPABILITY response or response code is arbitrary.) + + Example: A server that implements CONVERT. + + C: a000 CAPABILITY + S: * CAPABILITY IMAP4rev1 CONVERT BINARY [...] + S: a000 OK CAPABILITY completed + +4. Scope of Conversions + + Conversions only affect what is sent to the client; the original data + in the message store MUST NOT be altered. This document does not + specify how the server performs conversions. + + Note: The requirement that original data be unaltered allows such + data to remain accessible by other clients, permits replies or + forwards of the original documents, permits signature verification + (the converted body parts are not likely to contain any signatures), + and preserves BODYSTRUCTURE and related information. + +5. Discovery of Available Conversions + +5.1. CONVERSIONS Command + + Arguments: source MIME type + target MIME type + + Responses: untagged responses: CONVERSION + + + + + +Melnikov & Coates Standards Track [Page 4] + +RFC 5259 IMAP CONVERT extension July 2008 + + + Result: OK - CONVERSIONS command completed + BAD - unrecognized syntax of an argument, unexpected extra + argument, missing argument, etc. + + The CONVERSIONS command is allowed in Authenticated and Selected IMAP + states. + + The first parameter to the CONVERSIONS command is a source MIME type, + the second parameter is the target MIME type. Both parameters are + partially (e.g., "text/*") or completely ("*") wildcardable. + + Conversions matching the source/target pair and their associated + conversion parameters are returned in untagged CONVERSION responses. + If source/target doesn't match any conversion supported by the + server, no CONVERSION response is returned. + + Examples: + + For conversion information from GIF to JPEG image format (no untagged + CONVERSION response would be returned if no conversion is possible): + + C: a CONVERSIONS "image/gif" "image/jpeg" + S: * CONVERSION "image/gif" "image/jpeg" ("pix-y" "pix-x" + "image-interleave") + S: a OK CONVERSIONS completed + + For conversion information from GIF image format to anything: + + C: b CONVERSIONS "image/gif" "*" + S: * CONVERSION "image/gif" "image/jpeg" ("pix-y" "pix-x" + "image-interleave") + S: * CONVERSION "image/gif" "image/png" ([...]) + [...] + S: b OK CONVERSIONS completed + + For conversion of anything to JPEG: + + C: c CONVERSIONS "*" "image/jpeg" + S: * CONVERSION "image/gif" "image/jpeg" ("pix-y" "pix-x" + "image-interleave") + S: * CONVERSION "image/png" "image/jpeg" (...) + [...] + S: c OK CONVERSIONS completed + + For conversions from all image formats to all text formats, the + client can issue the following command: + + C: d CONVERSIONS "image/*" "text/*" + + + +Melnikov & Coates Standards Track [Page 5] + +RFC 5259 IMAP CONVERT extension July 2008 + + +5.2. CONVERSION Response + + Contents: source MIME type + target MIME type + optional list of supported conversion parameters + + As a result of executing a CONVERSIONS command, the server can return + one or more CONVERSION responses. Each CONVERSION response specifies + which source MIME type can be converted to the target MIME type, and + also lists supported conversion parameters. + +6. CONVERT and UID CONVERT Commands + + Arguments: sequence set + conversion parameters + CONVERT data item names + + Responses: untagged responses: CONVERTED + + Result: OK - convert completed + NO - convert error: can't fetch and/or convert that data + BAD - unrecognized syntax of an argument, unexpected extra + argument, missing argument, etc. + + The CONVERT extension defines CONVERT and UID CONVERT commands that + are used to transcode the media type of a MIME part into another + media type, and/or the same media type with different encoding + parameters. These commands are structured and behave similarly to + FETCH/UID FETCH commands as extended by [RFC3516]: + + o A successful CONVERT/UID CONVERT command results in one or more + untagged CONVERTED responses (one per message). They are similar + to the untagged FETCH responses. Note that a single CONVERT/ UID + CONVERT command can only perform a single type of conversion as + defined by the conversion parameters. A client that needs to + perform multiple different conversions needs to issue multiple + CONVERT/UID CONVERT commands. Such a client MAY pipeline them. + + o BINARY[...] data item requests conversion of a body part or of the + whole message according to conversion parameters and requests that + the converted message/body part be returned as binary. + + o BINARY.SIZE data item is similar to RFC822.SIZE, but it requests + size of a converted body part/message. + + o BODYPARTSTRUCTURE data item is similar to BODYSTRUCTURE FETCH data + item, but it returns the MIME structure of the converted body + part. + + + +Melnikov & Coates Standards Track [Page 6] + +RFC 5259 IMAP CONVERT extension July 2008 + + + o BODY[...HEADER] encoded words in the requested headers are + converted to the specified charset. The CHARSET parameter is + REQUIRED for this conversion. + + o BODY[...MIME] encoded words in the requested headers are converted + to the specified charset. The CHARSET parameter is REQUIRED for + this conversion. + + o AVAILABLECONVERSIONS data item requests the list of target MIME + types the specified body part (or the whole message) can be + converted to. + + The CONVERT extension also adds one new response code. See Section 9 + for more details. + + Typically clients will request conversion of leaf body parts. In + addition to support of leaf body part conversion, servers MAY offer + conversion of non-leaf body parts (e.g., conversion from multipart/ + related). + + Instead of specifying the exact target MIME media type the client + wants to convert to, the client MAY use a special marker NIL (also + known as "default conversion") to request the server to pick a + suitable target media type. This document doesn't describe how + exactly the server makes such a choice; however, some basic + guidelines are described in this paragraph. If the server knows + characteristics of the device using an in-band (such as device type + specified in a conversion parameter) or an out-of-band mechanism, + then it should convert the request body part to a media type the + device is likely to support and display/play successfully. Unless + specifically overridden by a conversion parameter, the server MAY + also remove any unnecessary detail that exceeds the capabilities of + the device (e.g., scaling images to just fit on the device's screen). + In the absence of any in-band or out-of-band mechanism for + determining device characteristics, the server should convert the + request body part to the most standard or widely deployed media type + available in that media category, for example, to convert to text/ + plain, image/jpeg. In such case, the server should minimize quality + loss. Servers are REQUIRED to support "default conversion" requests. + Server implementations that support conversions to multiple target + MIME types SHOULD make the default conversion configurable. Clients + SHOULD avoid using the default conversion unless they provided a way + (in-band or out-band) to signal their capabilities to the server, as + there is no guaranty that the server would guess their capability + correctly. Client implementors should consider using + AVAILABLECONVERSIONS CONVERT data item or CONVERSIONS command instead + of the default conversion. + + + + +Melnikov & Coates Standards Track [Page 7] + +RFC 5259 IMAP CONVERT extension July 2008 + + + CONVERT's command syntax is modeled after the FETCH command syntax in + [RFC3501], as extended by [RFC3516]. CONVERT data items are + generally structured as: + + BINARY[section-part]<partial> + + BINARY.SIZE[section-part] + + BODYPARTSTRUCTURE[section-part] + + BODY[HEADER] + + BODY[section-part.HEADER] + + BODY[section-part.MIME] + + AVAILABLECONVERSIONS[section-part] + + The semantics of a partial CONVERT BINARY[...] command is the same as + for a partial FETCH BODY[...] command, with the exception that the + <partial> arguments refer to the TRANSCODED and DECODED section data. + + Note that unlike the FETCH command, the CONVERT command never sets + the \Seen flag on converted messages. A client wishing to mark a + message with the \Seen flag would need to issue a STORE command + (possibly pipelined with the CONVERT request) to do that. + + The UID CONVERT command is different from the CONVERT command in the + same way as the UID FETCH command is different from the FETCH + command: + + o UID CONVERT takes as a parameter a sequence of UIDs instead of a + sequence of message numbers. + + o UID CONVERT command MUST result in the UID data item in a + corresponding CONVERTED response. + + o An EXPUNGE response MUST NOT be sent while responding to a CONVERT + command. This rule is necessary to prevent a loss of + synchronization of message sequence numbers between client and + server. Note that an EXPUNGE response MAY be sent during a UID + CONVERT command. + + + + + + + + + +Melnikov & Coates Standards Track [Page 8] + +RFC 5259 IMAP CONVERT extension July 2008 + + + Example: The client fetches body part section 3 in the message with + the message sequence number of 2 and asks to have that attachment + converted to pdf format. + + C: a001 CONVERT 2 ("APPLICATION/PDF") BINARY[3] + S: * 2 CONVERTED (TAG "a001") (BINARY[3] {2135} + <the document in .pdf format> + ) + S: a001 OK CONVERT COMPLETED + + Example: The client requests for conversion of a text/html body part + to text/plain and asks for a charset of us-ascii. The server cannot + respect the charset conversion request because there are non-us-ascii + characters in the text/html body part, so it fails the request by + returning an ERROR phrase in place of the converted data (see + Section 9). + + C: b001 CONVERT 2 ("text/plain" ("charset" "us-ascii")) BINARY[3] + S: * 2 CONVERTED (tag "b001") (BINARY[3] + (ERROR "Source text has non us-ascii" BADPARAMETERS + "text/html" "text/plain" ("charset" "us-ascii"))) + S: b001 NO All conversions failed + + If the client also specified the "unknown-character-replacement" + conversion parameter (see Section 12.1), the same example can look + like this: + + C: b001 CONVERT 2 ("text/plain" ("charset" "us-ascii" + "unknown-character-replacement" "?")) BINARY[3] + S: * 2 CONVERTED (TAG "b001") (BINARY[3] {2135} + <the document in text/plain format with us-ascii + charset> + ) + S: b001 OK CONVERT COMPLETED + + The server replaced non-us-ascii characters with a us-ascii character + such as "?". + + Example: The client first requests the converted size of a text/html + body part converted to text/plain: + + C: c000 CONVERT 2 ("TEXT/PLAIN" ("CHARSET" "us-ascii")) + BINARY.SIZE[4] + S: * 2 CONVERTED (TAG "c000") (BINARY.SIZE[4] 3135) + S: c000 OK CONVERT COMPLETED + + + + + + +Melnikov & Coates Standards Track [Page 9] + +RFC 5259 IMAP CONVERT extension July 2008 + + + Later on, the client requests 1000 bytes from the converted body + part, starting from byte 2001: + + C: c001 CONVERT 2 ("TEXT/PLAIN" ("CHARSET" "us-ascii")) + BINARY[4]<2001.1000> + S: * 2 CONVERTED (TAG "c001") (BINARY[4]<2001> {135} + <bytes 2001 - 2135 of the document in text/plain format> + ) + S: c001 OK CONVERT COMPLETED + + The server MUST respect the target MIME type and conversion + parameters specified by the client in the transcoding request. Note + that some conversion parameters can restrict what kind of conversion + is possible, while others can remove some restrictions. + + It is legal for a client to request conversion of a non-leaf body + part, for example, to request conversion of a multipart/* into a PDF + document. However, servers implementing this extension are not + required to support such conversions. Servers that support such + conversions MUST return one or more CONVERSION responses in response + to a 'CONVERSIONS "multipart/*" "*"' command. See Section 5.1 for + more details. + + The client can request header conversions using the BODY[...HEADER] + CONVERT request, for example + + C: D001 FETCH 2 BODY[HEADER] + S: * 2 FETCH (BODY[HEADER] {158} + S: Date: Mon, 20 Apr 2007 20:05:43 +0200 + S: From: Peter <peter@siroe.example.com> + S: To: Alexey <alexey@siroe.example.com> + S: Subject: =?KOI8-R?Q?why encode this?= + S: + S: ) + S: D001 OK + C: D002 CONVERT 2 (NIL ("CHARSET" "utf-8")) BODY[HEADER] + S: * 2 CONVERTED (TAG "d002") (BODY[HEADER] {157} + S: Date: Mon, 20 Apr 2007 20:05:43 +0200 + S: From: Peter <peter@siroe.example.com> + S: To: Alexey <alexey@siroe.example.com> + S: Subject: =?UTF-8?Q?why encode this?= + S: + S: ) + S: D002 OK + + Any such request MUST include the CHARSET parameter. Upon receipt of + the request, the server MUST decode any encoded words (as described + in [RFC2047]) in headers and return them re-encoded in the specified + + + +Melnikov & Coates Standards Track [Page 10] + +RFC 5259 IMAP CONVERT extension July 2008 + + + charset. (Note that encoded-words might not be needed if the result + can be represented entirely in US-ASCII, so the server MAY replace + the resulting encoded-words with their pure US-ASCII representation.) + If the server can't decode any particular encoded word, for example, + if the charset or encoding is not recognized, it MUST leave them as + is. Servers SHOULD also support decoding of any parameters as + described in [RFC2231]. Support for RFC 2231 parameters might + require reformatting of header fields during conversion. Consider + the following + + C: D011 FETCH 3 BODY[1.MIME] + S: * 3 FETCH (BODY[1.MIME] {118} + S: Content-Type: text/plain; charset=utf-8; + S: foo*0*=utf-8'fr'tr%c0; + S: foo*1*(very)=%03s_m%c0; + S: foo*2*=(nasty)%09chant + S: + S: D011 OK + + The server should preserve the headers during the conversion as much + as possible. In case the characters are split (legally!) between + fragments of an encoded parameter, the server MUST consolidate the + parameter fragments, and convert, emit, and re-fragment them as + necessary in order to keep the line length less than 78. Comments + embedded like this SHOULD be preserved during conversion, but clients + MUST gracefully handle the situation where comments are removed + entirely. If the comments are preserved, they MAY be moved after the + parameter. For example (continuing the previous example): + + C: D012 CONVERT 3 (NIL) BODY[1.MIME] + S: * 3 CONVERTED (TAG "D012") (BODY[1.MIME] {109} + S: Content-Type: text/plain; charset=utf-8; + S: foo*0*=utf-8'fr'tr%c0%03s_; + S: foo*1*=%m%c0%09chant (very)(nasty) + S: + S: D012 OK + + No destination MIME type MUST be specified with BODY[HEADER], + BODY[section.HEADER], or BODY[section.MIME]. That is, BODY[HEADER], + BODY[section.HEADER], or BODY[section.MIME] can only be used with the + "default conversion". When performing these conversions, the server + SHOULD leave encoded words as encoded words. A failure to do so may + alter the semantics of structured headers. + + + + + + + + +Melnikov & Coates Standards Track [Page 11] + +RFC 5259 IMAP CONVERT extension July 2008 + + +7. CONVERT Conversion Parameters + + The registry established by [MEDIAFEAT-REG] defines names of + conversion parameters that can be used in the CONVERT command. + Support for some conversion parameters is mandatory, as described in + Section 7.1. + + According to [MEDIAFEAT-REG], conversion parameter names are case- + insensitive. + + The following example illustrates how target picture dimensions can + be specified in a CONVERT request using the PIX-X and PIX-Y + parameters defined in [DISP-FEATURES]. + + C: e001 UID CONVERT 100 ("IMAGE/JPEG" ("PIX-X" "128" + "PIX-Y" "96")) BINARY[2] + S: * 2 CONVERTED (TAG "e001") (UID 100 BINARY[2] ~{4182} + <this part of a document is a rescaled image in + JPEG format with width=128, height=96.> + ) + S: e001 OK UID CONVERT COMPLETED + +7.1. Mandatory-to-Implement Conversions and Conversion Parameters + + A server implementing CONVERT MUST support charset conversions for + the text/plain MIME type, and MUST support charset conversions from + iso-8859-1, iso-8859-2, iso-8859-3, iso-8859-4, iso-8859-5, + iso-8859-6, iso-8859-7, iso-8859-8, and iso-8859-15 to utf-8. + + The server MUST list "text/plain" as an allowed destination + conversion from "text/plain" MIME type (see Section 5.1). A command + 'CONVERSIONS "text/plain" "text/plain"' MUST also return "charset" + and "unknown-character-replacement" (see Section 12.1) as supported + conversion parameters in the corresponding CONVERSION response. + + IMAP servers implementing the CONVERT extension MUST support + recognition of the "charset" [CHARSET-REG] parameter for text/plain, + text/html, text/css, text/csv, text/enriched, and text/xml MIME + types. Note, a server implementation is not required to support any + conversion from the text MIME subtypes specified above, except for + the mandatory-to-implement conversion described above. That is, a + server implementation MUST support the "charset" parameter for text/ + csv, only if it supports any conversion from text/csv. + + The server MUST support decoding of [RFC2047] headers and their + conversion to UTF-8 as long as the encoded words are in one of the + supported charsets. + + + + +Melnikov & Coates Standards Track [Page 12] + +RFC 5259 IMAP CONVERT extension July 2008 + + + Servers SHOULD offer additional character encoding conversions where + they make sense, as character conversion libraries are generally + available on many platforms. + + If the server cannot carry out the charset conversion while + preserving all the characters (i.e., a source character can't be + represented in the target charset), and the "unknown-character- + replacement" conversion parameter is not specified, then the server + MUST fail the conversion and MUST return the untagged ERROR + BADPARAMETERS response (see Section 9). If the value specified in + the "unknown-character-replacement" conversion itself can't be + represented in the target charset, then the server MUST also fail the + conversion and MUST return the untagged ERROR BADPARAMETERS response + (see Section 9). + +7.2. Additional Features for Mobile Usage + + This section is informative. + + Based on the expected usage of CONVERT in mobile environments, server + implementors should consider support for the following conversions: + + o Conversion of HTML and XHTML documents to text/plain in ways that + preserve at the minimum the document structure and tables. + + o Image conversions among the types image/gif, image/jpeg, and + image/png for at least the following parameters: + + * size limit (i.e., reduce quality) + + * width ("pix-x" parameter) + + * height ("pix-y" parameter) + + * resize directive (crop, stretch, aspect ratio) + + The support for "depth" may also be of interest. + + Audio conversion is also of interest but the relevant formats depend + significantly on the usage context. + + + + + + + + + + + +Melnikov & Coates Standards Track [Page 13] + +RFC 5259 IMAP CONVERT extension July 2008 + + +8. Request/Response Data Items to CONVERT/UID CONVERT Commands + +8.1. CONVERTED Untagged Response + + Contents: convert correlator + CONVERTED return data items + + The CONVERTED response may be sent as a result of a successful, + partially successful, or unsuccessful CONVERT or UID CONVERT command + specified in Section 6. + + The CONVERTED response starts with a message number, followed by the + "CONVERTED" label. The label is followed by a convert correlator, + which contains the tag of the command that caused the response to be + returned. This can be used by a client to match a CONVERTED response + against a corresponding CONVERT/UID CONVERT command. + + The convert correlator is followed by a list of one or more CONVERT + return data items. If the UID data item is returned, it MUST be + returned as the first data item in the CONVERTED response. This + requirement is to simplify client implementations. See Section 10 + and the remainder of Section 8 for more details. + +8.2. BODYPARTSTRUCTURE CONVERT Request and Response Item + + BODYPARTSTRUCTURE[section-part] + + The CONVERT extension defines the BODYPARTSTRUCTURE CONVERT data + item. Data contained in the BODYPARTSTRUCTURE return data item + follows the exact syntax specified in the [RFC3501] BODYSTRUCTURE + data item, but only contains information for the converted part. All + information contained in BODYPARTSTRUCTURE pertains to the state of + the part after it is converted, such as the converted MIME type, sub- + type, size, or charset. Note that the client can expect the returned + MIME type to match the one it requested (as the server is required to + obey the requested MIME type) and can treat mismatch as an error. + + The returned BODYPARTSTRUCTURE data MUST match the BINARY data + returned for exactly the same conversion in the same IMAP "session". + This requirement allows a client to request BODYPARTSTRUCTURE and + BINARY data in separate commands in the same IMAP session. + + If the client lists a BODYPARTSTRUCTURE data item for a section-part + before a BINARY data item for the same section-part, then, in the + CONVERTED response, the server MUST return the BODYPARTSTRUCTURE data + prior to the corresponding BINARY data. Also, any BODYSTRUCTURE data + + + + + +Melnikov & Coates Standards Track [Page 14] + +RFC 5259 IMAP CONVERT extension July 2008 + + + items MUST be after the UID data item if the UID data item is + present. Both requirements are to simplify handling of converted + data in clients. + + Example: + C: e002 CONVERT 2 (NIL ("PIX-X" "128" "PIX-Y" "96")) (BINARY[2] + BODYPARTSTRUCTURE[2]) + S: * 2 CONVERTED (TAG "e002") (BODYPARTSTRUCTURE[2] ("IMAGE" + "JPEG" () NIL NIL "8bit" 4182 NIL NIL NIL) BINARY[2] + ~{4182} + <this part of a document is a rescaled image in + JPEG format with width=128, height=96.> + ) + S: e002 OK CONVERT COMPLETED + +8.3. BINARY.SIZE CONVERT Request and Response Item + + BINARY.SIZE[section-part] + + This item requests the converted size of the section (i.e., the size + to expect in a response to the corresponding CONVERT BINARY request). + The returned value MUST be exact and MUST NOT change during a + duration of an IMAP "session", unless the message is expunged in + another session (see below). This allows a client to download a + converted part in chunks (using "<partial>"). This requirement means + that in most cases the server needs to perform conversion of the + requested body part before returning its size. + + If the message is expunged in another session, then the server MAY + return the value 0 in response to the BINARY.SIZE request item later + in the same session. + + In order to allow for upgrade of server transcoding components, + clients MUST NOT assume that repeating a particular body part + conversion in another IMAP "session" would yield the same result as a + previous conversion of the very same body part -- any characteristics + of the converted body part might be different (format, size, etc.). + In particular, clients MUST NOT cache sizes of converted messages/ + body parts beyond duration of any IMAP "session", or use sizes + obtained in one connection in another IMAP connection to the same + server. + + Historical note: Previous experience with IMAP servers that returned + estimated RFC822.SIZE value shows that this caused interoperability + problems. If the server returns a value that is smaller than the + actual size, this will result in data truncation if <partial> + + + + + +Melnikov & Coates Standards Track [Page 15] + +RFC 5259 IMAP CONVERT extension July 2008 + + + download is used. If the server returns a value that is bigger than + the actual size, this might mislead a client to believe that it + doesn't have enough storage to download a body part. + + Note for client implementors: client authors are cautioned that this + might be an expensive operation for some server implementations. + Requesting BINARY.SIZE for a large number of converted body parts or + for multiple conversions of the same body part can result in slow + performance and/or excessive server load and is discouraged. Client + implementors should consider implementation approaches that limit + this request to only the most necessary cases and are encouraged to + test the performance impact of BINARY.SIZE with multiple server + implementations. + +8.4. AVAILABLECONVERSIONS CONVERT Request and Response Item + + AVAILABLECONVERSIONS[section-part] allows the client to request the + list of target MIME types the specified body part of a message or the + whole message can be converted to. This data item is only useful + when the default conversion (see Section 6) is requested. + + This data item MUST return a list of target MIME types that is a + subset of the list returned by the CONVERSIONS command for the same + source and target MIME type pairs. If specific conversion is + requested, it MUST return the target MIME type as requested in the + CONVERT command, or the ERROR phrase. + + For both specific or default conversion requests, if conversion + parameters are specified, then the server must take them into + consideration when generating the list of target MIME types. For + example, if one or more of the conversion parameters doesn't apply to + a potential target MIME type, then such MIME type MUST be omitted + from the resulting list. If the server only had a single target MIME + type candidate and it was discarded due to the list of conversion + parameters, then the server SHOULD return the ERROR phrase instead of + the empty list of the target MIME types. + + The AVAILABLECONVERSIONS request SHOULD be processed quickly if + specified by itself. Note that if a MIME type is returned in + response to the AVAILABLECONVERSIONS, there is no guaranty that the + corresponding BINARY/BINARY.SIZE/BODYPARTSTRUCTURE CONVERT request + will not fail. + + Example: + C: f001 CONVERT 2 (NIL) (AVAILABLECONVERSIONS[2]) + S: * 2 CONVERTED (TAG "f001") (AVAILABLECONVERSIONS[2] + (("IMAGE/JPEG" "application/PostScript")) + S: f001 OK CONVERT COMPLETED + + + +Melnikov & Coates Standards Track [Page 16] + +RFC 5259 IMAP CONVERT extension July 2008 + + +8.5. Implementation Considerations + + Note that this section is normative. + + Servers MAY refuse to execute conversion requests that convert + multiple messages and/or body parts at once, e.g., a conversion + request that specifies multiple message numbers/UIDs. If the server + refuses a conversion because the request lists too many messages, the + server MUST return the MAXCONVERTMESSAGES response code (see + Section 9). For example: + + C: g001 CONVERT 1:* ("text/plain" ("charset" "us-ascii")) + BINARY[3] + S: g001 NO [MAXCONVERTMESSAGES 1] + + If the server refuses a conversion because the request lists too many + body parts, the server MUST return the MAXCONVERTPARTS response code + (see Section 9). For example: + + C: h001 CONVERT 1 ("text/plain" ("charset" "us-ascii")) + (BINARY[1] BINARY[2]) + + S: g001 NO [MAXCONVERTPARTS 1] You can only request 1 body part at + any given time + + Note for server implementors: In order to improve performance, + implementations SHOULD cache converted body parts. For example, the + server may perform a body part conversion when it receives the first + BINARY.SIZE[...], BODYPARTSTRUCTURE[...], or BINARY[...] request and + cache it until the client requests conversion/download of another + body part, a different conversion of the same body part, or until the + mailbox is closed. In order to mitigate denial-of-service attacks + from misbehaving or badly-written clients, a server SHOULD limit the + number of converted body parts it can cache. Servers SHOULD be able + to cache at least 2 conversions at any given time. + +9. Status Responses and Response Code Extensions + + A syntactically invalid MIME media type SHOULD generate a BAD tagged + response from the server. An unrecognized MIME media type generates + a NO tagged response. + + Some transcodings may require parameters. If a transcoding request + with no parameters is sent for a format which requires parameters, + the server will return an ERROR MISSINGPARAMETERS phrase in place of + the data associated with the data items requested. This is analogous + to the NIL response in FETCH, but with structured data associated + with the failure. + + + +Melnikov & Coates Standards Track [Page 17] + +RFC 5259 IMAP CONVERT extension July 2008 + + + If the server is unable to perform the requested conversion because a + resource is temporary unavailable (e.g., lack of disk space, + temporary internal error, transcoding service down), then the server + MUST return a tagged NO response that SHOULD contain the TEMPFAIL + response code (see below), or an ERROR TEMPFAIL phrase. + + If the requested conversion cannot be performed because of a + permanent error, for example, if a proprietary document format has no + existing transcoding implementation, the server MUST return a + CONVERTED response containing a ERROR BADPARAMETERS or ERROR + MISSINGPARAMETERS phrase. + + The server MAY choose to return one ERROR phrase for a single + conversion if several related data items are requested. For + instance: + + C: b002 CONVERT 2 ("text/plain" ("charset" "us-ascii")) + (BINARY[3] BODYPARTSTRUCTURE[3]) + S: * 2 CONVERTED (tag "b002") (BODYPARTSTRUCTURE[3] + (ERROR "Source text has non us-ascii" BADPARAMETERS + "text/html" "text/plain" ("charset" "us-ascii"))) + S: b002 NO All conversions failed + + If at least one conversion succeeds, the server MUST return an OK + response. If all conversions fail, the server MAY return OK or NO. + For instance: + + C: b002 CONVERT 2 ("text/plain" ("charset" "us-ascii")) + (BINARY[3] BODYPARTSTRUCTURE[3] BINARY[4] + BODYPARTSTRUCTURE[4]) + S: * 2 CONVERTED (tag "b002") (BODYPARTSTRUCTURE[3] + (ERROR "Source text has non us-ascii" BADPARAMETERS + "text/html" "text/plain" ("charset" "us-ascii")) + BODYSTRUCTURE[4] ("TEXT" "PLAIN" (CHARSET US-ASCII) + NIL NIL "8bit" 4182 NIL NIL NIL) BINARY[4] {4182} + <body in text plain> + ) + S: b002 OK Some conversions failed + + In general, the client can tell from the BODYPARTSTRUCTURE response + whether or not its request was honored exactly, but may not know the + reasons why. + + This document defines the following response codes that can be + returned in the tagged NO response code. + + TEMPFAIL - The transcoding request failed temporarily. It might + succeed later, so the client MAY retry. + + + +Melnikov & Coates Standards Track [Page 18] + +RFC 5259 IMAP CONVERT extension July 2008 + + + MAXCONVERTMESSAGES <number> - The server is unable or unwilling to + convert more than <number> messages in any given CONVERT/UID + CONVERT request. + + MAXCONVERTPARTS <number> - The server is unable or unwilling to + convert more than <number> body parts of a message at once in + any given CONVERT/UID CONVERT request. + + The word ERROR is always followed by an informal human-readable + descriptive text, which is followed by the convert-error-code. The + convert-error-code MUST be one of the following: + + TEMPFAIL mm - The transcoding request failed temporarily. It might + succeed later, so the client MAY retry. The client SHOULD wait + for at least mm minutes before retrying. + + BADPARAMETERS from-concrete-mime-type to-mime-type + "(" transcoding-params ")" - + The listed parameters were not understood, not valid for the + source/destination MIME type pair, had invalid values or could + not be honored for another reason noted in the human-readable + text that was specified after the ERROR label. The + transcoding-params can be omitted, in which case, it means that + the conversion from the from-concrete-mime-type to the to-mime- + type is not possible. If the from-concrete-mime-type is NIL, + this means that the specified body part doesn't exist. All + unrecognized or irrelevant parameters MUST be listed in the + transcoding-params. It is not legal behavior to ignore + irrelevant parameters. + + Note that if the client requested the "default conversion" (see + Section 6), the to-mime-type contains the destination MIME type + chosen by the server. + + MISSINGPARAMETERS from-concrete-mime-type to-mime-type + "(" transcoding-params ")" - + The listed parameters are required for conversion of the + specified source MIME type to the destination MIME type, but + were not seen in the request. Note that if the client + requested the "default conversion" (see Section 6), the to- + mime-type contains the destination MIME type chosen by the + server. + + + + + + + + + +Melnikov & Coates Standards Track [Page 19] + +RFC 5259 IMAP CONVERT extension July 2008 + + + Examples: + + C: b002 CONVERT 2 ("APPLICATION/PDF") BINARY[3] + S: b002 NO [TEMPFAIL] All conversions failed + + C: b003 CONVERT 2 ("TEXT/PLAIN") BINARY[3] + S: * 2 CONVERTED (tag "b003") (BINARY[3] + (ERROR "CHARSET must be specified for text conversions" + MISSINGPARAMETERS (CHARSET))) + S: b003 NO All conversions failed + + C: b005 CONVERT 2 ("TEXT/PLAIN" (CHARSET "US-ASCII" + UNKNOWN-CHARACTER-REPLACEMENT "<badchar>")) BINARY[3] + S: * 2 CONVERTED (tag "b005") (BINARY[3] + (ERROR "UNKNOWN-CHARACTER-REPLACEMENT limited to 4 + bytes" BADPARAMETERS (UNKNOWN-CHARACTER-REPLACEMENT + "<badchar>"))) + S: b005 NO All conversions failed + +10. Formal Syntax + + The following syntax specification uses the augmented Backus-Naur + Form (ABNF) notation as used in [ABNF], and incorporates by reference + the core rules defined in that document. + + This syntax augments the grammar specified in [RFC3501] and + [RFC3516]. Non-terminals not defined in this document can be found + in [RFC3501], [RFC3516], [IMAPABNF], [MIME-MTSRP], and + [MEDIAFEAT-REG]. + + command-select =/ convert + + uid =/ "UID" SP convert + ; Unique identifiers used instead of message + ; sequence numbers + + convert = "CONVERT" SP sequence-set SP convert-params SP + ( convert-att / + "(" convert-att *(SP convert-att) ")" ) + + convert-att = "UID" / + "BODYPARTSTRUCTURE" section-convert / + "BINARY" section-convert [partial] / + "BINARY.SIZE" section-convert / + "BODY[HEADER]" / + "BODY[" section-part ".HEADER]" / + "BODY[" section-part ".MIME]" / + "AVAILABLECONVERSIONS" section-convert + + + +Melnikov & Coates Standards Track [Page 20] + +RFC 5259 IMAP CONVERT extension July 2008 + + + ; <partial> is defined in [RFC3516]. + ; <section-part> is defined in [RFC3501]. + + convert-params = "(" (quoted-to-mime-type / default-conversion) + [SP "(" transcoding-params ")"] ")" + + quoted-to-mime-type = DQUOTE to-mime-type DQUOTE + + transcoding-params = transcoding-param + *(SP transcoding-param) + + transcoding-param-names = transcoding-param-name + *(SP transcoding-param-name) + + transcoding-param = transcoding-param-name SP + transcoding-param-value + + transcoding-param-name = astring + ; <transcod-param-name-nq> represented as a quoted, + ; literal or atom. Note that + ; <transcod-param-name-nq> allows for "%", which is + ; not allowed in atoms. Such values must be + ; represented as quoted or literal. + + transcod-param-name-nq = Feature-tag + ; <Feature-tag> is defined in [MEDIAFEAT-REG]. + + transcoding-param-value = astring + + default-conversion = "NIL" + + message-data =/ nz-number SP "CONVERTED" SP convert-correlator + SP convert-msg-attrs + + convert-correlator = "(" "TAG" SP tag-string ")" + + tag-string = string + ; tag of the command that caused + ; the CONVERTED response, sent as + ; a string. + + convert-msg-attrs = "(" convert-msg-att *(SP convert-msg-att) ")" + ; "UID" MUST be the first data item, if present. + + convert-msg-att = msg-att-semistat / msg-att-conv-static + + msg-att-conv-static = "UID" SP uniqueid + ; MUST NOT change for a message + + + +Melnikov & Coates Standards Track [Page 21] + +RFC 5259 IMAP CONVERT extension July 2008 + + + msg-att-semistat = + ( "BINARY" section-convert ["<" number ">"] SP + (nstring / literal8 / converterror-phrase) ) / + ( "BINARY.SIZE" section-convert SP + (number / converterror-phrase) ) / + ( "BODYPARTSTRUCTURE" section-convert SP + (body / converterror-phrase) ) / + ( "AVAILABLECONVERSIONS" section-convert SP + (mimetype-list / converterror-phrase) ) + ; MUST NOT change during an IMAP "session", + ; but not necessarily static in the long term. + + section-convert = section-binary + ; <section-binary> is defined in [RFC3516]. + ; + ; Note that unlike [RFC3516], conversion + ; of a top level multipart/* is allowed. + + resp-text-code =/ "TEMPFAIL" / + "MAXCONVERTMESSAGES" SP nz-number / + "MAXCONVERTPARTS" SP nz-number + ; <resp-text-code> is defined in [RFC3501]. + + mimetype-and-params = quoted-to-mime-type + [SP "(" transcoding-params ")"] + ; always includes a specific MIME type + + mimetype-list = "(" "(" [quoted-to-mime-type + *(SP quoted-to-mime-type)] ")" ")" + ; Unordered list of MIME types. It can be empty. + ; + ; Two levels of parenthesis is needed to distinguish this + ; data from <converterror-phrase>. + + converterror-phrase = "(" "ERROR" SP + convert-err-descript SP convert-error-code ")" + + convert-error-code = "TEMPFAIL" [SP nz-number] + / bad-params + / missing-params + + convert-err-descript = string + ; Human-readable text explaining the conversion error. + ; The default charset is US-ASCII, unless + ; the LANGUAGE command [IMAP-I18N] is called, when + ; the charset changes to UTF-8. + + quoted-from-mime-type = DQUOTE from-concrete-mime-type DQUOTE + + + +Melnikov & Coates Standards Track [Page 22] + +RFC 5259 IMAP CONVERT extension July 2008 + + + bad-params = "BADPARAMETERS" + 1*(SP (quoted-from-mime-type / nil) + SP mimetype-and-params) + ; nil is only returned when the body part doesn't exist. + + missing-params = "MISSINGPARAMETERS" + 1*(SP quoted-from-mime-type SP + mimetype-and-missing-params) + + mimetype-and-missing-params = quoted-to-mime-type + "(" transcoding-param-names ")" + ; always includes a specific MIME type + + concrete-mime-type = type-name "/" subtype-name + ; i.e., "type/subtype". + ; type-name and subtype-name + ; are defined in [MIME-MTSRP]. + + from-concrete-mime-type = concrete-mime-type + + to-mime-type = concrete-mime-type + + command-auth =/ conversions-cmd + + conversions-cmd = "CONVERSIONS" SP from-mime-type-req SP + to-mime-type-req + + from-mime-type-req = astring + ; "mime-type-req" represented as IMAP <atom>, + ; <quoted> or <literal> + + to-mime-type-req = astring + ; <mime-type-req> represented as IMAP <atom>, + ; <quoted> or <literal>. + ; Note that <mime-type-req> allows for "*", + ; which is not allowed in <atom>. Such values must + ; be represented as <quoted> or <literal>. + + any-mime-type = "*" + + mime-type-req = any-mime-type / + (type-name "/" any-mime-type) / + concrete-mime-type + ; '*', 'type/*' or 'type/subtype'. + ; type-name is defined in [MIME-MTSRP]. + + response-payload =/ conversion-data + + + + +Melnikov & Coates Standards Track [Page 23] + +RFC 5259 IMAP CONVERT extension July 2008 + + + conversion-data = "CONVERSION" SP quoted-from-mime-type SP + quoted-to-mime-type + [SP "(" transcoding-param-name + *(SP transcoding-param-name) ")"] + +11. Manageability Considerations + + The monitoring of CONVERT operation is similar to monitoring of the + IMAP FETCH operation. + + At the time of writing this document, there is no standard IMAP MIB + defined. Similarly, a standard MIB for monitoring CONVERT operations + and their failures does not exist. However, the authors believe that + in the absence of such a MIB, server implementations SHOULD provide + operators with tools to report the following information: + + o which conversions (source and target MIME types and possibly + conversion parameters used) are invoked more frequently and how + long they take, + + o information about conversion errors and which error condition + caused them (see Section 9), and + + o information about users which invoke conversion operation. + + This information can help operators to detect client abuse of this + extension and scalability issues that might arise from its use. + + Standardizing these tools may be the subject of future work. + +12. IANA Considerations + + IMAP4 capabilities are registered by publishing a Standards Track or + IESG-approved Experimental RFC. This document defines the CONVERT + IMAP capability. IANA has added this extension to the IANA IMAP + Capability registry. + + IANA has performed registrations as defined in the following + subsections. + + + + + + + + + + + + +Melnikov & Coates Standards Track [Page 24] + +RFC 5259 IMAP CONVERT extension July 2008 + + +12.1. Registration of unknown-character-replacement Media Type + Parameter + + IANA has added the following registration to the registry established + by RFC 2506. + + To: "Media feature tags mailing list" + <media-feature-tags@apps.ietf.org> + + Subject: Registration of media feature tag + unknown-character-replacement + + Media feature tag name: + unknown-character-replacement + + ASN.1 identifier associated with feature tag: + 1.3.6.1.8.1.33 + + Summary of the media feature indicated by this feature tag: + Allows servers that can perform charset conversion for text/plain + text/html, text/css, text/csv, text/enriched, and text/xml MIME + types to replace characters not supported by the target charset + with a fixed string, such as "?". + This feature tag is also applicable to other conversions + to text, e.g., conversion of images using OCR (optical + character recognition). + + Values appropriate for use with this feature tag: + The feature tag contains a UTF-8 string used to replace any + characters from the source media type that can't be + represented in the target media type. + + The feature tag is intended primarily for use in the following + applications, protocols, services, or negotiation mechanisms: + IMAP CONVERT extension [RFC5259] + + Examples of typical use: + C: b001 CONVERT 2 BINARY[3 ("text/plain" ("charset" + "us-ascii" "unknown-character-replacement" "?"))] + + Related standards or documents: + [RFC5259] + [CHARSET-REG] + + Considerations particular to use in individual applications, + protocols, services, or negotiation mechanisms: + None + + + + +Melnikov & Coates Standards Track [Page 25] + +RFC 5259 IMAP CONVERT extension July 2008 + + + Interoperability considerations: None + + Security considerations: None + + Additional information: + This media feature only make sense for MIME types that + also support the "charset" media type parameter + [CHARSET-REG]. + + Name(s) & email address(es) of person(s) to contact for further + information: + Alexey Melnikov <alexey.melnikov@isode.com> + + Intended usage: + COMMON + + Author/Change controller: + IETF + + Requested IANA publication delay: + None + + Other information: + None + +13. Security Considerations + + It is to be noted that some conversions may present security threats + (e.g., converting a document to a damaging executable, exploiting a + buffer overflow in a media codec/parser, or a denial-of-service + attack against a client or a server such as requesting an image be + scaled to extremely large dimensions). Server SHOULD refuse to + execute CPU-expensive conversions. Servers should avoid dangerous + conversions if possible. Whenever possible, servers should perform + verification of the converted attachments before returning them to + the client. Clients should be careful when requesting conversions or + processing transformed attachments. Clients SHOULD use mutual Simple + Authentication and Security Layer (SASL) authentication and the SASL/ + TLS integrity layer, to make sure they are talking to trusted + servers. + + When the client requests a server-side conversion of a signed body + part (e.g., a part inside multipart/signed), there is no way for the + client to verify that the converted content is authentic. A client + not trusting the server to perform conversion of a signed body part + can download the signed object, verify the signature, and perform the + conversion itself. + + + + +Melnikov & Coates Standards Track [Page 26] + +RFC 5259 IMAP CONVERT extension July 2008 + + + A client can create a carefully crafted bad message with the APPEND + command followed by the CONVERT command to attack the server. If the + server's conversion function or library has a security problem (such + as vulnerability to a buffer overflow), this could result in + privilege escalation or denial of service. In order to mitigate such + attacks, servers SHOULD log the client authentication identity on + APPEND and/or CONVERT operations in order to facilitate tracking of + abusive clients. Also server implementors SHOULD isolate the + conversion function or library from the privileged mailstore, perhaps + by running it within a distinct process. + + Deployments in which the actual transcoding is done outside the IMAP + server in a separate server are recommended to keep the servers in + the same trusted domain (e.g., subnet). + +14. Acknowledgments + + Stephane H. Maes and Ray Cromwell from Oracle edited several earlier + versions of this document. Their contribution is gratefully + acknowledged. + + The authors want to specifically acknowledge the excellent criticism + and comments received from Randall Gellens (Qualcomm), Arnt + Gulbrandsen (Oryx), Zoltan Ordogh (Nokia), Ben Last (Emccsoft), Dan + Karp (Zimbra), Pete Resnick (Qualcomm), Chris Newman (Sun), Ted + Hardie (Qualcomm), Larry Masinter (Adobe), Philip Guenther + (Sendmail), Greg Vaudreuil (Alcatel-Lucent), David Harrington + (Comcast), Dave Cridland (Isode), Pasi Eronen (Nokia), Magnus + Westerlund (Ericsson), and Jari Arkko (Ericsson), which improved the + quality of this specification considerably. + + The authors would also like to specially thank Dave Cridland for the + MEDIACAPS command proposal and Dan Karp for the CONVERSIONS command + proposal. + + The authors also want to thank all who have contributed key insight + and extensively reviewed and discussed the concepts of CONVERT and + its predecessor P-IMAP. In particular, this includes the authors of + the LCONVERT document: Rafiul Ahad (Oracle Corporation), Eugene Chiu + (Oracle Corporation), Ray Cromwell (Oracle Corporation), Jia-der Day + (Oracle Corporation), Vi Ha (Oracle Corporation), Wook-Hyun Jeong + (Samsung Electronics Co. LTF), Chang Kuang (Oracle Corporation), + Rodrigo Lima (Oracle Corporation), Stephane H. Maes (Oracle + Corporation), Gustaf Rosell (Sony Ericsson), Jean Sini (Symbol + Technologies), Sung-Mu Son (LG Electronics), Fan Xiaohui (China + Mobile Communications Corporation (CMCC)), and Zhao Lijun (China + Mobile Communications Corporation (CMCC)). + + + + +Melnikov & Coates Standards Track [Page 27] + +RFC 5259 IMAP CONVERT extension July 2008 + + +15. References + +15.1. Normative References + + [ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", STD 68, RFC 5234, + January 2008. + + [CHARSET-REG] Hoffman, P., "Registration of Charset and Languages + Media Features Tags", RFC 2987, November 2000. + + [IMAPABNF] Melnikov, A. and C. Daboo, "Collected Extensions to + IMAP4 ABNF", RFC 4466, April 2006. + + [MEDIAFEAT-REG] Holtman, K., Mutz, A., and T. Hardie, "Media Feature + Tag Registration Procedure", BCP 31, RFC 2506, + March 1999. + + [MIME-MTSRP] Freed, N. and J. Klensin, "Media Type Specifications + and Registration Procedures", BCP 13, RFC 4288, + December 2005. + + [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail + Extensions) Part Three: Message Header Extensions + for Non-ASCII Text", RFC 2047, November 1996. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and + Encoded Word Extensions: + Character Sets, Languages, and Continuations", + RFC 2231, November 1997. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - + VERSION 4rev1", RFC 3501, March 2003. + + [RFC3516] Nerenberg, L., "IMAP4 Binary Content Extension", + RFC 3516, April 2003. + + + + + + + + + + + + +Melnikov & Coates Standards Track [Page 28] + +RFC 5259 IMAP CONVERT extension July 2008 + + +15.2. Informative References + + [DISP-FEATURES] Masinter, L., Wing, D., Mutz, A., and K. Holtman, + "Media Features for Display, Print, and Fax", + RFC 2534, March 1999. + + [IMAP-I18N] Newman, C., Gulbrandsen, A., and A. Melnikov, + "Internet Message Access Protocol + Internationalization", RFC 5255, June 2008. + + [LEM-STREAMING] Cook, N., "Streaming Internet Messaging + Attachments", Work in Progress, June 2008. + + [OMA-ME-RD] OMA, "Open Mobile Alliance Mobile Email Requirement + Document", OMA 55.919 3.0.0, December 2007. + + [OMA-STI] OMA, "Open Mobile Alliance, Standard Transcoding + Interface Specification", OMA OMA-STI-V1_0, + December 2005. + +Authors' Addresses + + Alexey Melnikov (editor) + Isode Ltd + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: Alexey.Melnikov@isode.com + + + Peter Coates (editor) + Sun Microsystems + 185 Falcon Drive + Whitehorse, YT Y1A 6T2 + Canada + + EMail: peter.coates@Sun.COM + + + + + + + + + + + + +Melnikov & Coates Standards Track [Page 29] + +RFC 5259 IMAP CONVERT extension July 2008 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2008). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Melnikov & Coates Standards Track [Page 30] + diff --git a/imap/docs/rfc/rfc5267.txt b/imap/docs/rfc/rfc5267.txt new file mode 100644 index 00000000..91bfa223 --- /dev/null +++ b/imap/docs/rfc/rfc5267.txt @@ -0,0 +1,1011 @@ + + + + + + +Network Working Group D. Cridland +Request for Comments: 5267 C. King +Category: Standards Track Isode Limited + July 2008 + + + Contexts for IMAP4 + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + The IMAP4rev1 protocol has powerful search facilities as part of the + core protocol, but lacks the ability to create live, updated results + that can be easily handled. This memo provides such an extension, + and shows how it can be used to provide a facility similar to virtual + mailboxes. + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Cridland & King Standards Track [Page 1] + +RFC 5267 IMAP CONTEXT July 2008 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 + 3. Extended Sort Syntax . . . . . . . . . . . . . . . . . . . . . 3 + 3.1. ESORT Extension . . . . . . . . . . . . . . . . . . . . . 4 + 3.2. Ranges in Extended Sort Results . . . . . . . . . . . . . 4 + 3.3. Extended SORT Example . . . . . . . . . . . . . . . . . . 4 + 4. Contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 4.2. Context Hint . . . . . . . . . . . . . . . . . . . . . . . 5 + 4.3. Notifications of Changes . . . . . . . . . . . . . . . . . 6 + 4.3.1. Refusing to Update Contexts . . . . . . . . . . . . . 7 + 4.3.2. Common Features of ADDTO and REMOVEFROM . . . . . . . 8 + 4.3.3. ADDTO Return Data Item . . . . . . . . . . . . . . . . 8 + 4.3.4. REMOVEFROM Return Data Item . . . . . . . . . . . . . 9 + 4.3.5. The CANCELUPDATE Command . . . . . . . . . . . . . . . 10 + 4.4. Partial Results . . . . . . . . . . . . . . . . . . . . . 10 + 4.5. Caching Results . . . . . . . . . . . . . . . . . . . . . 11 + 5. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 12 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 + 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 + 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 13 + 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 + 9.1. Normative References . . . . . . . . . . . . . . . . . . . 14 + 9.2. Informative References . . . . . . . . . . . . . . . . . . 14 + Appendix A. Cookbook . . . . . . . . . . . . . . . . . . . . . . 15 + A.1. Virtual Mailboxes . . . . . . . . . . . . . . . . . . . . 15 + A.2. Trash Mailboxes . . . . . . . . . . . . . . . . . . . . . 15 + A.3. Immediate EXPUNGE Notifications . . . . . . . . . . . . . 15 + A.4. Monitoring Counts . . . . . . . . . . . . . . . . . . . . 15 + A.5. Resynchronizing Contexts . . . . . . . . . . . . . . . . . 16 + Appendix B. Server Implementation Notes . . . . . . . . . . . . . 16 + + + + + + + + + + + + + + + + + + +Cridland & King Standards Track [Page 2] + +RFC 5267 IMAP CONTEXT July 2008 + + +1. Introduction + + Although the basic SEARCH command defined in [IMAP], and as enhanced + by [ESEARCH], is relatively compact in its representation, this + reduction saves only a certain amount of data, and huge mailboxes + might overwhelm the storage available for results on even relatively + high-end desktop machines. + + The SORT command defined in [SORT] provides useful features, but is + hard to use effectively on changing mailboxes over low-bandwidth + connections. + + This memo borrows concepts from [ACAP], such as providing a windowed + view onto search or sort results, and making updates that are + bandwidth and round-trip efficient. These are provided by two + extensions: "ESORT" and "CONTEXT". + +2. Conventions Used in This Document + + In examples, "C:" and "S:" indicate lines sent by the client + messaging user agent and IMAP4rev1 ([IMAP]) server, respectively. + "//" indicates inline comments not part of the protocol exchange. + Line breaks are liberally inserted for clarity. Examples are + intended to be read in order, such that the state remains from one + example to the next. + + Although the examples show a server that supports [ESEARCH], this is + not a strict requirement of this specification. + + 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]. + + Other capitalized words are typically names of IMAP extensions or + commands -- these are uppercased for clarity only, and are case- + insensitive. + +3. Extended Sort Syntax + + Servers implementing the extended SORT provide a suite of extensions + to the SORT and UID SORT commands defined in [SORT]. This allows for + return options, as used with SEARCH and specified in [IMAP-ABNF], to + be used with SORT in a similar manner. + + The SORT and UID SORT commands are extended by the addition of an + optional list of return options that follow a RETURN atom immediately + after the command. If this is missing, the server will return + results as specified in [SORT]. + + + +Cridland & King Standards Track [Page 3] + +RFC 5267 IMAP CONTEXT July 2008 + + + The extended SORT command always returns results in the requested + sort order, but is otherwise identical in its behaviour to the + extended SEARCH command defined in [IMAP-ABNF], as extended by + [ESEARCH]. In particular, the extended SORT command returns results + in an ESEARCH response. + +3.1. ESORT Extension + + Servers advertising the capability "ESORT" support the return options + specified in [ESEARCH] in the SORT command. These return options are + adapted as follows: + + MIN + Return the message number/UID of the lowest sorted message + satisfying the search criteria. + + MAX + Return the message number/UID of the highest sorted message + satisfying the search criteria. + + ALL + Return all message numbers/UIDs which match the search criteria, + in the requested sort order, using a sequence-set. Note the use + of ranges described below in Section 3.2. + + COUNT + As in [ESEARCH]. + +3.2. Ranges in Extended Sort Results + + Any ranges given by the server, including those given as part of the + sequence-set, in an ESEARCH response resulting from an extended SORT + or UID SORT command, MUST be ordered in increasing numerical order + after expansion, as per usual [IMAP] rules. + + In particular this means that 10:12 is equivalent to 12:10, and + 10,11,12. To avoid confusion, servers SHOULD present ranges only + when the first seq-number is lower than the second; that is, either + of the forms 10:12 or 10,11,12 is acceptable, but 12:10 SHOULD be + avoided. + +3.3. Extended SORT Example + + If the list of return options is present but empty, then the server + provides the ALL return data item in an ESEARCH response. This is + functionally equivalent to an unextended UID SORT command, but can + use a smaller representation: + + + + +Cridland & King Standards Track [Page 4] + +RFC 5267 IMAP CONTEXT July 2008 + + + C: E01 UID SORT RETURN () (REVERSE DATE) UTF-8 UNDELETED + UNKEYWORD $Junk + S: * ESEARCH (TAG "E01") UID ALL 23765,23764,23763,23761,[...] + S: E01 OK Sort completed + + Note that the initial three results are not represented as the range + 23765:23763 as mandated in Section 3.2. + +4. Contexts + +4.1. Overview + + The Contexts extension is present in any IMAP4rev1 server that + includes the string "CONTEXT=SEARCH", and/or "CONTEXT=SORT", within + its advertised capabilities. + + In the case of CONTEXT=SEARCH, the server supports the extended + SEARCH command syntax described in [IMAP-ABNF], and accepts three + additional return options. + + Servers advertising CONTEXT=SORT also advertise the SORT capability, + as described in [SORT], support the extended SORT command syntax + described in Section 3, and accept three additional return options + for this extended SORT. + + These additional return options allow for notifications of changes to + the results of SEARCH or SORT commands, and also allow for access to + partial results. + + A server advertising the CONTEXT=SEARCH extension will order all + SEARCH results, whether from a UID SEARCH or SEARCH command, in + mailbox order -- that is, by message number and UID. Therefore, the + UID SEARCH, SEARCH, UID SORT, or SORT command used -- collectively + known as the searching command -- will always have an order, the + requested order, which will be the mailbox order for UID SEARCH and + SEARCH commands. + + All of the return specifiers have no interaction with either each + other or any return specifiers defined in [ESEARCH] or Section 3.1; + however, it is believed that implementations supporting CONTEXT will + also support ESEARCH and ESORT. + +4.2. Context Hint + + The return option CONTEXT SHOULD be used by a client to indicate that + subsequent use of the search criteria are likely. Servers MAY ignore + this return option or use it as a hint to maintain a full result + cache, or index. + + + +Cridland & King Standards Track [Page 5] + +RFC 5267 IMAP CONTEXT July 2008 + + + A client might choose to obtain a count of matching messages prior to + obtaining actual results. Here, the client signals its intention to + fetch the results themselves: + + C: A01 SEARCH RETURN (CONTEXT COUNT) UNDELETED + UNKEYWORD $Junk + S: * ESEARCH (TAG "A01") COUNT 23765 + S: A01 OK Search completed. + +4.3. Notifications of Changes + + The search return option UPDATE, if used by a client, causes the + server to issue unsolicited notifications containing updates to the + results that would be returned by an unmodified searching command. + These update sets are carried in ADDTO and REMOVEFROM data items in + ESEARCH responses. + + These ESEARCH responses carry a search correlator of the searching + command, hence clients MUST NOT reuse tags, as already specified in + Section 2.2.1 of [IMAP]. An attempt to use UPDATE where a tag is + already in use with a previous searching command that itself used + UPDATE SHALL result in the server rejecting the searching command + with a BAD response. + + Both ADDTO and REMOVEFROM data items SHOULD be delivered to clients + in a timely manner, as and when results change, whether by new + messages arriving in the mailbox, metadata such as flags being + changed, or messages being expunged. + + Typically, this would occur at the same time as the FETCH, EXISTS, or + EXPUNGE responses carrying the source of the change. + + Updates will cease when the mailbox is no longer selected, or when + the CANCELUPDATE command, defined in Section 4.3.5, is issued by the + client, whichever is sooner. + + Unlike [ACAP], there is no requirement that a context need be created + with CONTEXT to use UPDATE, and in addition, the lack of UPDATE with + a CONTEXT does not affect the results caused by later searching + commands -- there is no snapshot facility. + + There is no interaction between UPDATE and any other return options; + therefore, use of RETURN (UPDATE MIN), for example, does not notify + about the minimum UID or sequence number, but notifies instead about + all changes to the set of matching messages. In particular, this + means that a client using UPDATE and PARTIAL on the same search + program could receive notifications about messages that do not + currently interest it. + + + +Cridland & King Standards Track [Page 6] + +RFC 5267 IMAP CONTEXT July 2008 + + + Finally, as specified in the errata to [IMAP], any message sequence + numbers used in the search program are evaluated at the time the + command is received; therefore, if the messages referred to by such + message sequence numbers change, no notifications will be emitted. + + This time, the client will require notifications of updates and + chooses to obtain a count: + + C: B01 UID SEARCH RETURN (UPDATE COUNT) DELETED + KEYWORD $Junk + S: * ESEARCH (TAG "B01") COUNT 74 + S: B01 OK Search completed, will notify. + // Note that the following is rejected, and has no effect: + C: B01 SORT RETURN (UPDATE) FLAGGED + S: B01 BAD Tag reuse + +4.3.1. Refusing to Update Contexts + + In some cases, the server MAY refuse to provide updates, such as if + an internal limit on the number of update contexts is reached. In + such a case, an untagged NO is generated during processing of the + command with a response-code of NOUPDATE. The response-code + contains, as argument, the tag of the search command for which the + server is refusing to honour the UPDATE request. + + Other return options specified SHALL still be honoured. + + Servers MUST provide at least one updating context per client, and + SHOULD provide more -- see Appendix B for strategies on reducing the + impact of additional updating contexts. Since sorted contexts + require a higher implementation cost than unsorted contexts, refusal + to provide updates for a SORT command does not imply that SEARCH + contexts will also be refused. + + This time, the client will require notifications of updates, and + chooses to obtain a count: + + C: B02 UID SORT RETURN (UPDATE COUNT) UTF-8 + KEYWORD $Junk + S: * ESEARCH (TAG "B02") COUNT 74 + S: * NO [NOUPDATE "B02"] Too many contexts + S: B02 OK Search completed, will not notify. + + Client handling might be to retry with a UID SEARCH command, or else + cancel an existing context; see Section 4.3.5. + + + + + + +Cridland & King Standards Track [Page 7] + +RFC 5267 IMAP CONTEXT July 2008 + + +4.3.2. Common Features of ADDTO and REMOVEFROM + + The result update set included in the return data item is specified + as UIDs or message numbers, depending on how the UPDATE was + specified. If the UPDATE was present in a SEARCH or SORT command, + the results will be message numbers; in a UID SEARCH or UID SORT + command, they will be UIDs. + + The client MUST process ADDTO and REMOVEFROM return data items in the + order they appear, including those within a single ESEARCH response. + Correspondingly, servers MUST generate ADDTO and REMOVEFROM responses + such that the results are maintained in the requested order. + + As with any response aside from EXPUNGE, ESEARCH responses carrying + ADDTO and/or REMOVEFROM return data items MAY be sent at any time. + In particular, servers MAY send such responses when no command is in + progress, during the processing of any command, or when the client is + using the IDLE facility described in [IDLE]. Implementors are + recommended to read [NOTIFY] as a mechanism for clients to signal + servers that they are willing to process responses at any time, and + are also recommended to pay close attention to Section 5.3 of [IMAP]. + + It is anticipated that typical server implementations will emit ADDTO + when they normally emit the causal FETCH or EXISTS, and similarly + emit REMOVEFROM when they normally emit the causal FETCH or EXPUNGE. + +4.3.3. ADDTO Return Data Item + + The ADDTO return data item contains, as payload, a list containing + pairs of a context position and a set of result updates in the + requested order to be inserted at the context position. Where the + searching command is a SEARCH or UID SEARCH command, the context + position MAY be zero. Each pair is processed in the order that it + appears. + + Note that an ADDTO containing message sequence numbers added as a + result of those messages being delivered or appended MUST be sent + after the EXISTS notification itself, in order that those sequence + numbers are valid. + + If the context position is non-zero, the result update is inserted at + the given context position, meaning that the first result in the set + will occupy the new context position after insertion, and any prior + existing result at that context position will be shifted to a later + context position. + + + + + + +Cridland & King Standards Track [Page 8] + +RFC 5267 IMAP CONTEXT July 2008 + + + Where the context position is zero, the client MAY insert the message + numbers or UIDs in the result list such that the result list is + maintained in mailbox order. In this case, servers are RECOMMENDED + to order the result update into mailbox order to produce the shortest + representation in set-syntax. + + [...] + S: * 23762 FETCH (FLAGS (\Deleted \Seen)) + S: * 23763 FETCH (FLAGS ($Junk \Seen)) + S: * ESEARCH (TAG "B01") UID ADDTO (0 32768:32769) + + Note that this example assumes messages 23762 and 23763 with UIDs + 32768 and 32769 (respectively) previously had neither \Deleted nor + $Junk set. Also note that only the ADDTO is included, and not the + (now changed) COUNT. + + If the searching command "C01" initially generated a result list of + 2734:2735, then the following three responses are equivalent, and + yield a result list of 2731:2735: + + [...] + S: * ESEARCH (TAG "C01") UID ADDTO (1 2733 1 2732 1 2731) + S: * ESEARCH (TAG "C01") UID ADDTO (1 2733) ADDTO (1 2731:2732) + S: * ESEARCH (TAG "C01") UID ADDTO (1 2731:2733) + + The last is the preferred representation. + +4.3.4. REMOVEFROM Return Data Item + + The REMOVEFROM return data item contains, as payload, a list + containing pairs of a context position and a set of result updates in + the requested order to be removed starting from the context position. + Where the searching command is a SEARCH or UID SEARCH command, the + context position MAY be zero. Each pair is processed in the order + that it appears. + + If the context position is non-zero, the results are removed at the + given context position, meaning that the first result in the set will + occupy the given context position before removal, and any prior + existing result at that context position will be shifted to an + earlier context position. + + Where the context position is zero, the client removes the message + numbers or UIDs in the result list wherever they occur, and servers + are RECOMMENDED to order the result list in mailbox order to obtain + the best benefit from the set-syntax. + + + + + +Cridland & King Standards Track [Page 9] + +RFC 5267 IMAP CONTEXT July 2008 + + + Note that a REMOVEFROM containing message sequence numbers removed as + a result of those messages being expunged MUST be sent prior to the + expunge notification itself, in order that those sequence numbers + remain valid. + + Here, a message in the result list is expunged. The REMOVEFROM is + shown to happen without any command in progress; see Section 4.3.2. + Note that EXPUNGE responses do not have this property. + + [...] + S: * ESEARCH (TAG "B01") UID REMOVEFROM (0 32768) + C: B03 NOOP + S: * 23762 EXPUNGE + S: B03 OK Nothing done. + +4.3.5. The CANCELUPDATE Command + + When a client no longer wishes to receive updates, it may issue the + CANCELUPDATE command, which will prevent all updates to the contexts + named in the arguments from being transmitted by the server. The + command takes, as arguments, one or more tags of the commands used to + request updates. + + The server MAY free any resource associated with a context so + disabled -- however, the client is free to issue further searching + commands with the same criteria and requested order, including + PARTIAL requests. + + C: B04 CANCELUPDATE "B01" + S: B04 OK No further updates. + +4.4. Partial Results + + The PARTIAL search return option causes the server to provide in an + ESEARCH response a subset of the results denoted by the sequence + range given as the mandatory argument. The first result is 1; thus, + the first 500 results would be obtained by a return option of + "PARTIAL 1:500", and the second 500 by "PARTIAL 501:1000". This + intentionally mirrors message sequence numbers. + + A single command MUST NOT contain more than one PARTIAL or ALL search + return option -- that is, either one PARTIAL, one ALL, or neither + PARTIAL nor ALL is allowed. + + For SEARCH results, the entire result list MUST be ordered in mailbox + order, that is, in UID or message sequence number order. + + + + + +Cridland & King Standards Track [Page 10] + +RFC 5267 IMAP CONTEXT July 2008 + + + Where a PARTIAL search return option references results that do not + exist, by using a range which starts or ends higher than the current + number of results, then the server returns the results that are in + the set. This yields a PARTIAL return data item that has, as + payload, the original range and a potentially missing set of results + that may be shorter than the extent of the range. + + Clients need not request PARTIAL results in any particular order. + Because mailboxes may change, clients will often wish to use PARTIAL + in combination with UPDATE, especially if the intent is to walk a + large set of results; however, these return options do not interact + -- the UPDATE will provide notifications for all matching results. + + // Recall from A01 that there are 23764 results. + C: A02 UID SEARCH RETURN (PARTIAL 23500:24000) UNDELETED + UNKEYWORD $Junk + C: A03 UID SEARCH RETURN (PARTIAL 1:500) UNDELETED + UNKEYWORD $Junk + C: A04 UID SEARCH RETURN (PARTIAL 24000:24500) UNDELETED + UNKEYWORD $Junk + S: * ESEARCH (TAG "A02") UID PARTIAL (23500:24000 ...) + // 264 results in set syntax elided, + // this spans the end of the results. + S: A02 OK Completed. + S: * ESEARCH (TAG "A03") UID PARTIAL (1:500 ...) + // 500 results in set syntax elided. + S: A03 OK Completed. + S: * ESEARCH (TAG "A04") UID PARTIAL (24000:24500 NIL) + // No results are present, this is beyond the end of the results. + S: A04 OK Completed. + +4.5. Caching Results + + Server implementations MAY cache results from a SEARCH or SORT, + whether or not hinted to by CONTEXT, in order to make subsequent + searches more efficient, perhaps by recommencing a subsequent PARTIAL + search where a previous search left off. However, servers MUST + behave identically whether or not internal caching is taking place; + therefore, any such cache is required to be updated as changes to the + mailbox occur. An alternate strategy would be to discard results + when any change occurs to the mailbox. + + + + + + + + + + +Cridland & King Standards Track [Page 11] + +RFC 5267 IMAP CONTEXT July 2008 + + +5. Formal Syntax + + The collected formal syntax. This uses ABNF as defined in [ABNF]. + It includes definitions from [IMAP], [IMAP-ABNF], and [SORT]. + + capability =/ "CONTEXT=SEARCH" / "CONTEXT=SORT" / "ESORT" + ;; <capability> from [IMAP] + + command-select =/ "CANCELUPDATE" 1*(SP quoted) + ;; <command-select> from [IMAP] + + context-position = number + ;; Context position may be 0 for SEARCH result additions. + ;; <number> from [IMAP] + + modifier-context = "CONTEXT" + + modifier-partial = "PARTIAL" SP partial-range + + partial-range = nz-number ":" nz-number + ;; A range 500:400 is the same as 400:500. + ;; This is similar to <seq-range> from [IMAP], + ;; but cannot contain "*". + + modifier-update = "UPDATE" + + search-return-opt =/ modifier-context / modifier-partial / + modifier-update + ;; All conform to <search-return-opt>, from [IMAP-ABNF] + + resp-text-code =/ "NOUPDATE" SP quoted + ;; <resp-text-code> from [IMAP] + + ret-data-addto = "ADDTO" + SP "(" context-position SP sequence-set + *(SP context-position SP sequence-set) + ")" + ;; <sequence-set> from [IMAP] + + ret-data-partial = "PARTIAL" + SP "(" partial-range SP partial-results ")" + ;; <partial-range> is the requested range. + + partial-results = sequence-set / "NIL" + ;; <sequence-set> from [IMAP] + ;; NIL indicates no results correspond to the requested range. + + + + + +Cridland & King Standards Track [Page 12] + +RFC 5267 IMAP CONTEXT July 2008 + + + ret-data-removefrom = "REMOVEFROM" + SP "(" context-position SP sequence-set + *(SP context-position SP sequence-set) + ")" + ;; <sequence-set> from [IMAP] + + search-return-data =/ ret-data-partial / ret-data-addto / + ret-data-removefrom + ;; All conform to <search-return-data>, from [IMAP-ABNF] + + sort =/ extended-sort + ;; <sort> from [SORT] + + extended-sort = ["UID" SP] "SORT" search-return-opts + SP sort-criteria SP search-criteria + ;; <search-return-opts> from [IMAP-ABNF] + ;; <sort-criteria> and <search-criteria> from [SORT] + +6. Security Considerations + + This document defines additional IMAP4 capabilities. As such, it + does not change the underlying security considerations of [IMAP]. + The authors and reviewers believe that no new security issues are + introduced with these additional IMAP4 capabilities. + + Creation of a large number of contexts may provide an avenue for + denial-of-service attacks by authorized users. Implementors may + reduce this by limiting the number of contexts possible to create, + via the protocol features described in Section 4.3.1; by reducing the + impact of contexts by the implementation strategies described in + Appendix B; and by logging context creation and usage so that + administrative remedies may be applied. + +7. IANA Considerations + + IMAP4 capabilities are registered by publishing a Standards Track or + IESG-approved Experimental RFC. + + This document defines the ESORT, CONTEXT=SEARCH, and CONTEXT=SORT + IMAP capabilities. IANA has added them to the registry accordingly. + +8. Acknowledgements + + Much of the design of this extension can be found in ACAP. Valuable + comments, both in agreement and in dissent, were received from Alexey + Melnikov, Arnt Gulbrandsen, Cyrus Daboo, Filip Navara, Mark Crispin, + Peter Coates, Philip Van Hoof, Randall Gellens, Timo Sirainen, Zoltan + + + + +Cridland & King Standards Track [Page 13] + +RFC 5267 IMAP CONTEXT July 2008 + + + Ordogh, and others, and many of these comments have had significant + influence on the design or the text. The authors are grateful to all + those involved, including those not mentioned here. + +9. References + +9.1. Normative References + + [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + + [ESEARCH] Melnikov, A. and D. Cridland, "IMAP4 Extension to SEARCH + Command for Controlling What Kind of Information Is + Returned", RFC 4731, November 2006. + + [IMAP] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [IMAP-ABNF] Melnikov, A. and C. Daboo, "Collected Extensions to + IMAP4 ABNF", RFC 4466, April 2006. + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [SORT] Crispin, M. and K. Murchison, "Internet Message Access + Protocol - SORT and THREAD Extensions", RFC 5256, + June 2008. + +9.2. Informative References + + [ACAP] Newman, C. and J. Myers, "ACAP -- Application + Configuration Access Protocol", RFC 2244, November 1997. + + [IDLE] Leiba, B., "IMAP4 IDLE command", RFC 2177, June 1997. + + [NOTIFY] Melnikov, A., Gulbrandsen, A., and C. King, "The IMAP + NOTIFY Extension", Work in Progress, March 2008. + + + + + + + + + + + + + + +Cridland & King Standards Track [Page 14] + +RFC 5267 IMAP CONTEXT July 2008 + + +Appendix A. Cookbook + +A.1. Virtual Mailboxes + + It is possible to use the facilities described within this memo to + create a facility largely similar to a virtual mailbox, but handled + on the client side. + + Initially, the client SELECTs the real "backing" mailbox. Next, it + can switch to a filtered view at any time by issuing a RETURN (COUNT + UPDATE CONTEXT), and using RETURN (PARTIAL x:y) as the user scrolls, + feeding the results into a FETCH as required to populate summary + views. + + A typically useful view is "UID SORT (DATE) RETURN (...) UTF-8 + UNSEEN UNDELETED", which can be used to show the mailbox sorted into + INTERNALDATE order, filtered to only show messages which are unread + and not yet deleted. + +A.2. Trash Mailboxes + + Certain contexts are particularly useful for client developers + wishing to present something similar to the common trash mailbox + metaphor in limited bandwidth. The simple criteria of UNDELETED only + matches undeleted messages, and the corresponding DELETED search key + can be used to display a per-mailbox trash-like virtual mailbox. + +A.3. Immediate EXPUNGE Notifications + + The command "SEARCH RETURN (UPDATE) ALL" can be used to create a + context that notifies immediately about expunged messages, yet will + not affect message sequence numbers until the normal EXPUNGE message + can be sent. This may be useful for clients wishing to show this + behavior without losing the benefit of sequence numbering. + +A.4. Monitoring Counts + + A client need not maintain any result cache at all, but instead it + can maintain a simple count of messages matching the search criteria. + Typically, this would use the SEARCH command, as opposed to UID + SEARCH, due to its smaller representation. Such usage might prove + useful in monitoring the number of flagged, but unanswered, messages, + for example, with "SEARCH RETURN (UPDATE COUNT) FLAGGED UNANSWERED". + + + + + + + + +Cridland & King Standards Track [Page 15] + +RFC 5267 IMAP CONTEXT July 2008 + + +A.5. Resynchronizing Contexts + + The creation of a context, and immediate access to it, can all be + accomplished in a single round-trip. Therefore, whilst it is + possible to elide resynchronization if no changes have occurred, it + is simpler in most cases to resynchronize by simply recreating the + context. + +Appendix B. Server Implementation Notes + + Although a server may cache the results, this is neither mandated nor + required, especially when the client uses SEARCH or UID SEARCH + commands. UPDATE processing, for example, can be achieved + efficiently by comparison of the old flag state (if any) and the new, + and PARTIAL can be achieved by re-running the search until the + suitable window is required. This is a result of there being no + snapshot facility. + + For example, on a new message, the server can simply test for matches + against all current UPDATE context search programs, and for any that + match, send the ADDTO return data. + + Similarly, for a flag change on an existing message, the server can + check whether the message matched with its old flags, whether it + matches with new flags, and provide ADDTO or REMOVEFROM return data + accordingly if these results differ. + + For PARTIAL requests, the server can perform a full search, + discarding results until the lower bound is hit, and stopping the + search when sufficient results have been obtained. + + With some additional state, it is possible to restart PARTIAL + searches, thus avoiding performing the initial discard phase. + + For the best performance, however, caching the full search results is + needed, which can allow for faster responses at the expense of + memory. One reasonable strategy would be to balance this trade-off + at run-time, discarding search results after a suitable timeout, and + regenerating them as required. + + This yields state requirements of storing the search program for any + UPDATE contexts, and optionally storing both search program and + (updated) results for further contexts as required. + + + + + + + + +Cridland & King Standards Track [Page 16] + +RFC 5267 IMAP CONTEXT July 2008 + + + Note that in the absence of a server-side results cache, it may be + impossible to know if an expunged message previously matched unless + the original message is still available. Therefore, some + implementations may be forced into using a results cache in many + circumstances. + + UPDATE contexts created with SORT or UID SORT will almost certainly + require some form of results caching, however. + +Authors' Addresses + + Dave Cridland + Isode Limited + 5 Castle Business Village + 36, Station Road + Hampton, Middlesex TW12 2BX + GB + + EMail: dave.cridland@isode.com + + + Curtis King + Isode Limited + 5 Castle Business Village + 36, Station Road + Hampton, Middlesex TW12 2BX + GB + + EMail: cking@mumbo.ca + + + + + + + + + + + + + + + + + + + + + + +Cridland & King Standards Track [Page 17] + +RFC 5267 IMAP CONTEXT July 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. + + + + + + + + + + + + +Cridland & King Standards Track [Page 18] + diff --git a/imap/docs/rfc/rfc5464.txt b/imap/docs/rfc/rfc5464.txt new file mode 100644 index 00000000..645bfd9a --- /dev/null +++ b/imap/docs/rfc/rfc5464.txt @@ -0,0 +1,1177 @@ + + + +Network Working Group C. Daboo +Request for Comments: 5464 Apple, Inc. +Category: Standards Track February 2009 + + + The IMAP METADATA Extension + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Abstract + + The METADATA extension to the Internet Message Access Protocol + permits clients and servers to maintain "annotations" or "metadata" + on IMAP servers. It is possible to have annotations on a per-mailbox + basis or on the server as a whole. For example, this would allow + comments about the purpose of a particular mailbox to be "attached" + to that mailbox, or a "message of the day" containing server status + information to be made available to anyone logging in to the server. + + + + + + + + + + + + + + + + + + + + + + + + + + + +Daboo Standards Track [Page 1] + +RFC 5464 The IMAP METADATA Extension February 2009 + + +Table of Contents + + 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 + 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 + 3. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3.2. Namespace of Entries . . . . . . . . . . . . . . . . . . . 4 + 3.2.1. Entry Names . . . . . . . . . . . . . . . . . . . . . 5 + 3.3. Private versus Shared and Access Control . . . . . . . . . 6 + 4. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . 7 + 4.1. General Considerations . . . . . . . . . . . . . . . . . . 7 + 4.2. GETMETADATA Command . . . . . . . . . . . . . . . . . . . 8 + 4.2.1. MAXSIZE GETMETADATA Command Option . . . . . . . . . . 9 + 4.2.2. DEPTH GETMETADATA Command Option . . . . . . . . . . . 10 + 4.3. SETMETADATA Command . . . . . . . . . . . . . . . . . . . 10 + 4.4. METADATA Response . . . . . . . . . . . . . . . . . . . . 12 + 4.4.1. METADATA Response with Values . . . . . . . . . . . . 13 + 4.4.2. Unsolicited METADATA Response without Values . . . . . 13 + 5. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 14 + 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 + 6.1. Entry and Attribute Registration Template . . . . . . . . 16 + 6.2. Server Entry Registrations . . . . . . . . . . . . . . . . 16 + 6.2.1. /shared/comment . . . . . . . . . . . . . . . . . . . 17 + 6.2.2. /shared/admin . . . . . . . . . . . . . . . . . . . . 17 + 6.3. Mailbox Entry Registrations . . . . . . . . . . . . . . . 17 + 6.3.1. /shared/comment . . . . . . . . . . . . . . . . . . . 18 + 6.3.2. /private/comment . . . . . . . . . . . . . . . . . . . 18 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 18 + 8. Normative References . . . . . . . . . . . . . . . . . . . . . 19 + Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 19 + + + + + + + + + + + + + + + + + + + + + +Daboo Standards Track [Page 2] + +RFC 5464 The IMAP METADATA Extension February 2009 + + +1. Introduction and Overview + + The goal of the METADATA extension is to provide a means for clients + to set and retrieve "annotations" or "metadata" on an IMAP server. + The annotations can be associated with specific mailboxes or the + server as a whole. The server can choose to support only server + annotations or both server and mailbox annotations. + + A server that supports both server and mailbox annotations indicates + the presence of this extension by returning "METADATA" as one of the + supported capabilities in the CAPABILITY command response. + + A server that supports only server annotations indicates the presence + of this extension by returning "METADATA-SERVER" as one of the + supported capabilities in the CAPABILITY command response. + + A server that supports unsolicited annotation change responses MUST + support the "ENABLE" [RFC5161] extension to allow clients to turn + that feature on. + + The METADATA extension adds two new commands and one new untagged + response to the IMAP base protocol. + + This extension makes the following changes to the IMAP protocol: + + o adds a new SETMETADATA command + + o adds a new GETMETADATA command + + o adds a new METADATA untagged response + + o adds a new METADATA response code + + The rest of this document describes the data model and protocol + changes more rigorously. + +2. Conventions Used in This Document + + In examples, "C:" and "S:" indicate lines sent by the client and + server, respectively. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + Whitespace and line breaks have been added to the examples in this + document to promote readability. + + + + +Daboo Standards Track [Page 3] + +RFC 5464 The IMAP METADATA Extension February 2009 + + +3. Data Model + +3.1. Overview + + Mailboxes or the server as a whole may have zero or more annotations + associated with them. An annotation contains a uniquely named entry, + which has a value. Annotations can be added to mailboxes when a + mailbox name is provided as the first argument to the SETMETADATA + command, or to the server as a whole when the empty string is + provided as the first argument to the command. + + For example, a general comment being added to a mailbox may have an + entry name of "/comment" and a value of "Really useful mailbox". + + The protocol changes to IMAP described below allow a client to access + or change the values of any annotation entry, assuming it has + sufficient access rights to do so. + +3.2. Namespace of Entries + + Each annotation is an entry that has a hierarchical name, with each + component of the name separated by a slash ("/"). An entry name MUST + NOT contain two consecutive "/" characters and MUST NOT end with a + "/" character. + + The value of an entry is NIL (has no value), or a string or binary + data of zero or more octets. A string MAY contain multiple lines of + text. Clients MUST use the CRLF (0x0D 0x0A) character octet sequence + to represent line ends in a multi-line string value. + + Entry names MUST NOT contain asterisk ("*") or percent ("%") + characters and MUST NOT contain non-ASCII characters or characters + with octet values in the range 0x00 to 0x19. Invalid entry names + result in a BAD response in any IMAP command in which they are used. + + Entry names are case-insensitive. + + Use of control or punctuation characters in entry names is strongly + discouraged. + + This specification defines an initial set of entry names available + for use with mailbox and server annotations. In addition, an + extension mechanism is described to allow additional names to be + added for extensibility. + + The first component in entry names defines the scope of the + annotation. Currently, only the prefixes "/private" or "/shared" are + defined. These prefixes are used to indicate whether an annotation + + + +Daboo Standards Track [Page 4] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + is stored on a per-user basis ("/private") and not visible to other + users, or whether an annotation is shared between authorized users + ("/shared") with a single value that can be read and changed by + authorized users with appropriate access. See Section 3.3 for + details. + + Entry names can have any number of components starting at 2, unless + they fall under the vendor namespaces (i.e., have a /shared/vendor/ + <vendor-token> or /private/vendor/<vendor-token> prefix as described + below), in which case they have at least 4 components. + +3.2.1. Entry Names + + Entry names MUST be specified in a Standards Track or IESG-approved + Experimental RFC, or fall under the vendor namespace. See + Section 6.1 for the registration template. + +3.2.1.1. Server Entries + + These entries are set or retrieved when the mailbox name argument to + the new SETMETADATA or GETMETADATA command is the empty string. + + /shared/comment + + Defines a comment or note that is associated with the server and + that is shared with authorized users of the server. + + /shared/admin + + Indicates a method for contacting the server administrator. The + value MUST be a URI (e.g., a mailto: or tel: URL). This entry is + always read-only -- clients cannot change it. It is visible to + authorized users of the system. + + /shared/vendor/<vendor-token> + + Defines the top level of shared entries associated with the + server, as created by a particular product of some vendor. This + entry can be used by vendors to provide server- or client-specific + annotations. The vendor-token MUST be registered with IANA, using + the Application Configuration Access Protocol (ACAP) [RFC2244] + vendor subtree registry. + + /private/vendor/<vendor-token> + + Defines the top level of private entries associated with the + server, as created by a particular product of some vendor. This + entry can be used by vendors to provide server- or client-specific + + + +Daboo Standards Track [Page 5] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + annotations. The vendor-token MUST be registered with IANA, using + the ACAP [RFC2244] vendor subtree registry. + +3.2.1.2. Mailbox Entries + + These entries are set or retrieved when the mailbox name argument to + the new SETMETADATA or GETMETADATA command is not the empty string. + + /shared/comment + + Defines a shared comment or note associated with a mailbox. + + /private/comment + + Defines a private (per-user) comment or note associated with a + mailbox. + + /shared/vendor/<vendor-token> + + Defines the top level of shared entries associated with a specific + mailbox, as created by a particular product of some vendor. This + entry can be used by vendors to provide client-specific + annotations. The vendor-token MUST be registered with IANA, using + the ACAP [RFC2244] vendor subtree registry. + + /private/vendor/<vendor-token> + + Defines the top level of private entries associated with a + specific mailbox, as created by a particular product of some + vendor. This entry can be used by vendors to provide client- + specific annotations. The vendor-token MUST be registered with + IANA, using the ACAP [RFC2244] vendor subtree registry. + +3.3. Private versus Shared and Access Control + + In the absence of the ACL (Access Control List) extension [RFC4314], + users can only set and retrieve private or shared mailbox annotations + on a mailbox that exists and is returned to them via a LIST or LSUB + command, and on which they have either read or write access to the + actual message content of the mailbox (as determined by the READ-ONLY + and READ-WRITE response codes as described in Section 5.2 of + [RFC4314]). + + When the ACL extension [RFC4314] is present, users can only set and + retrieve private or shared mailbox annotations on a mailbox on which + they have the "l" right and any one of the "r", "s", "w", "i", or "p" + rights. + + + + +Daboo Standards Track [Page 6] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + If a client attempts to set or retrieve annotations on mailboxes that + do not satisfy the conditions above, the server MUST respond with a + NO response. + + Users can always retrieve private or shared server annotations if + they exist. Servers MAY restrict the creation of private or shared + server annotations as appropriate. When restricted, the server MUST + return a NO response when the SETMETADATA command is used to try to + create a server annotation. + + If the METADATA extension is present, support for shared annotations + is REQUIRED, whilst support for private annotations is OPTIONAL. + This recognizes the fact that support for private annotations may + introduce significantly more complexity to a server in terms of + tracking ownership of the annotations, how quota is determined for + users based on their own annotations, etc. + +4. IMAP Protocol Changes + +4.1. General Considerations + + The new SETMETADATA command and the METADATA response each have a + mailbox name argument. An empty string is used for the mailbox name + to signify server annotations. A non-empty string is used to signify + mailbox annotations attached to the corresponding mailbox. + + Servers SHOULD ensure that mailbox annotations are automatically + moved when the mailbox they refer to is renamed, i.e., the + annotations follow the mailbox. This applies to a rename of the + INBOX, with the additional behavior that the annotations are copied + from the original INBOX to the renamed mailbox, i.e., mailbox + annotations are preserved on the INBOX when it is renamed. + + Servers SHOULD delete annotations for a mailbox when the mailbox is + deleted, so that a mailbox created with the same name as a previously + existing mailbox does not inherit the old mailbox annotations. + + Servers SHOULD allow annotations on all 'types' of mailboxes, + including ones reporting \Noselect for their LIST response. Servers + can implicitly remove \Noselect mailboxes when all child mailboxes + are removed, and, at that time any annotations associated with the + \Noselect mailbox SHOULD be removed. + + The server is allowed to impose limitations on the size of any one + annotation or the total number of annotations for a single mailbox or + for the server as a whole. However, the server MUST accept an + annotation data size of at least 1024 bytes, and an annotation count + per server or mailbox of at least 10. + + + +Daboo Standards Track [Page 7] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + Some annotations may be "read-only" -- i.e., they are set by the + server and cannot be changed by the client. Also, such annotations + may be "computed" -- i.e., the value changes based on underlying + properties of the mailbox or server. For example, an annotation + reporting the total size of all messages in the mailbox would change + as messages are added or removed. Or, an annotation containing an + IMAP URL for the mailbox would change if the mailbox was renamed. + + Servers MAY support sending unsolicited responses for use when + annotations are changed by some "third-party" (see Section 4.4). In + order to do so, servers MUST support the ENABLE command [RFC5161] and + MUST only send unsolicited responses if the client used the ENABLE + command [RFC5161] extension with the capability string "METADATA" or + "METADATA-SERVER" earlier in the session, depending on which of those + capabilities is supported by the server. + +4.2. GETMETADATA Command + + This extension adds the GETMETADATA command. This allows clients to + retrieve server or mailbox annotations. + + This command is only available in authenticated or selected state + [RFC3501]. + + Arguments: mailbox-name + options + entry-specifier + + Responses: required METADATA response + + Result: OK - command completed + NO - command failure: can't access annotations on + the server + BAD - command unknown or arguments invalid + + When the mailbox name is the empty string, this command retrieves + server annotations. When the mailbox name is not empty, this command + retrieves annotations on the specified mailbox. + + Options MAY be included with this command and are defined below. + + Example: + + C: a GETMETADATA "" /shared/comment + S: * METADATA "" (/shared/comment "Shared comment") + S: a OK GETMETADATA complete + + + + + +Daboo Standards Track [Page 8] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + In the above example, the contents of the value of the "/shared/ + comment" server entry is requested by the client and returned by + the server. + + Example: + + C: a GETMETADATA "INBOX" /private/comment + S: * METADATA "INBOX" (/private/comment "My own comment") + S: a OK GETMETADATA complete + + In the above example, the contents of the value of the "/private/ + comment" mailbox entry for the mailbox "INBOX" is requested by the + client and returned by the server. + + Entry specifiers can be lists of atomic specifiers, so that multiple + annotations may be returned in a single GETMETADATA command. + + Example: + + C: a GETMETADATA "INBOX" (/shared/comment /private/comment) + S: * METADATA "INBOX" (/shared/comment "Shared comment" + /private/comment "My own comment") + S: a OK GETMETADATA complete + + In the above example, the values of the two server entries + "/shared/comment" and "/private/comment" on the mailbox "INBOX" + are requested by the client and returned by the server. + +4.2.1. MAXSIZE GETMETADATA Command Option + + When the MAXSIZE option is specified with the GETMETADATA command, it + restricts which entry values are returned by the server. Only entry + values that are less than or equal in octet size to the specified + MAXSIZE limit are returned. If there are any entries with values + larger than the MAXSIZE limit, the server MUST include the METADATA + LONGENTRIES response code in the tagged OK response for the + GETMETADATA command. The METADATA LONGENTRIES response code returns + the size of the biggest entry value requested by the client that + exceeded the MAXSIZE limit. + + Example: + + C: a GETMETADATA "INBOX" (MAXSIZE 1024) + (/shared/comment /private/comment) + S: * METADATA "INBOX" (/private/comment "My own comment") + S: a OK [METADATA LONGENTRIES 2199] GETMETADATA complete + + + + + +Daboo Standards Track [Page 9] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + In the above example, the values of the two server entries + "/shared/comment" and "/private/comment" on the mailbox "INBOX" + are requested by the client, which wants to restrict the size of + returned values to 1024 octets. In this case, the "/shared/ + comment" entry value is 2199 octets and is not returned. + +4.2.2. DEPTH GETMETADATA Command Option + + When the DEPTH option is specified with the GETMETADATA command, it + extends the list of entry values returned by the server. For each + entry name specified in the GETMETADATA command, the server returns + the value of the specified entry name (if it exists), plus all + entries below the entry name up to the specified DEPTH. Three values + are allowed for DEPTH: + + "0" - no entries below the specified entry are returned + "1" - only entries immediately below the specified entry are returned + "infinity" - all entries below the specified entry are returned + + Thus, "depth 1" for an entry "/a" will match "/a" as well as its + children entries (e.g., "/a/b"), but will not match grandchildren + entries (e.g., "/a/b/c"). + + If the DEPTH option is not specified, this is the same as specifying + "DEPTH 0". + + Example: + + C: a GETMETADATA "INBOX" (DEPTH 1) + (/private/filters/values) + S: * METADATA "INBOX" (/private/filters/values/small + "SMALLER 5000" /private/filters/values/boss + "FROM \"boss@example.com\"") + S: a OK GETMETADATA complete + + In the above example, 2 entries below the /private/filters/values + entry exist on the mailbox "INBOX": "/private/filters/values/ + small" and "/private/filters/values/boss". + +4.3. SETMETADATA Command + + This extension adds the SETMETADATA command. This allows clients to + set annotations. + + This command is only available in authenticated or selected state + [RFC3501]. + + + + + +Daboo Standards Track [Page 10] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + Arguments: mailbox-name + entry + value + list of entry, values + + Responses: no specific responses for this command + + Result: OK - command completed + NO - command failure: can't set annotations, + or annotation too big or too many + BAD - command unknown or arguments invalid + + This command sets the specified list of entries by adding or + replacing the specified values provided, on the specified existing + mailboxes or on the server (if the mailbox argument is the empty + string). Clients can use NIL for the value of entries it wants to + remove. The server SHOULD NOT return a METADATA response containing + the updated annotation data. Clients MUST NOT assume that a METADATA + response will be sent, and MUST assume that if the command succeeds, + then the annotation has been changed. + + If the server is unable to set an annotation because the size of its + value is too large, the server MUST return a tagged NO response with + a "[METADATA MAXSIZE NNN]" response code when NNN is the maximum + octet count that it is willing to accept. + + If the server is unable to set a new annotation because the maximum + number of allowed annotations has already been reached, the server + MUST return a tagged NO response with a "[METADATA TOOMANY]" response + code. + + If the server is unable to set a new annotation because it does not + support private annotations on one of the specified mailboxes, the + server MUST return a tagged NO response with a "[METADATA NOPRIVATE]" + response code. + + When any one annotation fails to be set, resulting in a tagged NO + response from the server, then the server MUST NOT change the values + for other annotations specified in the SETMETADATA command. + + Example: + + C: a SETMETADATA INBOX (/private/comment {33} + S: + ready for data + My new comment across + two lines. + ) + S: a OK SETMETADATA complete + + + +Daboo Standards Track [Page 11] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + In the above example, the entry "/private/comment" for the mailbox + "INBOX" is created (if not already present) and the value set to a + multi-line string. + + Example: + + C: a SETMETADATA INBOX (/private/comment NIL) + S: a OK SETMETADATA complete + + In the above example, the entry "/private/comment" is removed from + the mailbox "INBOX". + + Multiple entries can be set in a single SETMETADATA command by + listing entry-value pairs in the list. + + Example: + + C: a SETMETADATA INBOX (/private/comment "My new comment" + /shared/comment "This one is for you!") + S: a OK SETMETADATA complete + + In the above example, the entries "/private/comment" and "/shared/ + comment" for the mailbox "INBOX" are created (if not already + present) and the values set as specified. + + Example: + + C: a SETMETADATA INBOX (/private/comment "My new comment") + S: a NO [METADATA TOOMANY] SETMETADATA failed + + In the above example, the server is unable to set the requested + (new) annotation as it has reached the limit on the number of + annotations it can support on the specified mailbox. + +4.4. METADATA Response + + The METADATA response displays results of a GETMETADATA command, or + can be returned as an unsolicited response at any time by the server + in response to a change in a server or mailbox annotation. + + When unsolicited responses are activated by the ENABLE [RFC5161] + command for this extension, servers MUST send unsolicited METADATA + responses if server or mailbox annotations are changed by a third- + party, allowing servers to keep clients updated with changes. + + Unsolicited METADATA responses MUST only contain entry names, not the + values. If the client wants to update any cached values, it must + explicitly retrieve those using a GETMETADATA command. + + + +Daboo Standards Track [Page 12] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + The METADATA response can contain multiple entries in a single + response, but the server is free to return multiple responses for + each entry or group of entries, if it desires. + + This response is only available in authenticated or selected state + [RFC3501]. + +4.4.1. METADATA Response with Values + + The response consists of a list of entry-value pairs. + + Example: + + C: a GETMETADATA "" /shared/comment + S: * METADATA "" (/shared/comment "My comment") + S: a OK GETMETADATA complete + + In the above example, a single entry with its value is returned by + the server. + + Example: + + C: a GETMETADATA "INBOX" /private/comment /shared/comment + S: * METADATA "INBOX" (/private/comment "My comment" + /shared/comment "Its sunny outside!") + S: a OK GETMETADATA complete + + In the above example, two entries and their values are returned by + the server. + + Example: + + C: a GETMETADATA "INBOX" /private/comment /shared/comment + S: * METADATA "INBOX" (/private/comment "My comment") + S: * METADATA "INBOX" (/shared/comment "Its sunny outside!") + S: a OK GETMETADATA complete + + In the above example, the server returns two separate responses + for each of the two entries requested. + +4.4.2. Unsolicited METADATA Response without Values + + The response consists of a list of entries, each of which have + changed on the server or mailbox. + + Example: + + + + + +Daboo Standards Track [Page 13] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + C: a NOOP + S: * METADATA "" /shared/comment + S: a OK NOOP complete + + In the above example, the server indicates that the "/shared/ + comment" server entry has been changed. + + Example: + + C: a NOOP + S: * METADATA "INBOX" /shared/comment /private/comment + S: a OK NOOP complete + + In the above example, the server indicates a change to two mailbox + entries. + +5. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [RFC5234]. + + Non-terminals referenced but not defined below are as defined by + [RFC3501], with the new definitions in [RFC4466] superseding those in + [RFC3501]. + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of upper or lower case characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. + + capability =/ "METADATA" / "METADATA-SERVER" + ; defines the capabilities for this extension. + + command-auth =/ setmetadata / getmetadata + ; adds to original IMAP command + + entries = entry / + "(" entry *(SP entry) ")" + ; entry specifiers + + entry = astring + ; slash-separated path to entry + ; MUST NOT contain "*" or "%" + + entry-value = entry SP value + + entry-values = "(" entry-value *(SP entry-value) ")" + + + + +Daboo Standards Track [Page 14] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + entry-list = entry *(SP entry) + ; list of entries used in unsolicited + ; METADATA response + + getmetadata = "GETMETADATA" [SP getmetadata-options] + SP mailbox SP entries + ; empty string for mailbox implies + ; server annotation. + + getmetadata-options = "(" getmetadata-option + *(SP getmetadata-option) ")" + + getmetadata-option = tagged-ext-label [SP tagged-ext-val] + ; tagged-ext-label and tagged-ext-val + ; are defined in [RFC4466]. + + maxsize-opt = "MAXSIZE" SP number + ; Used as a getmetadata-option + + metadata-resp = "METADATA" SP mailbox SP + (entry-values / entry-list) + ; empty string for mailbox implies + ; server annotation. + + response-payload =/ metadata-resp + ; adds to original IMAP data responses + + resp-text-code =/ "METADATA" SP "LONGENTRIES" SP number + ; new response codes for GETMETADATA + + resp-text-code =/ "METADATA" SP ("MAXSIZE" SP number / + "TOOMANY" / "NOPRIVATE") + ; new response codes for SETMETADATA + ; failures + + scope-opt = "DEPTH" SP ("0" / "1" / "infinity") + ; Used as a getmetadata-option + + setmetadata = "SETMETADATA" SP mailbox + SP entry-values + ; empty string for mailbox implies + ; server annotation. + + value = nstring / literal8 + + + + + + + +Daboo Standards Track [Page 15] + +RFC 5464 The IMAP METADATA Extension February 2009 + + +6. IANA Considerations + + All entries MUST have either "/shared" or "/private" as a prefix. + Entry names MUST be specified in a Standards Track or IESG-approved + Experimental RFC, or fall under the vendor namespace (i.e., use + /shared/vendor/<vendor-token> or /private/vendor/<vendor-token> as + the prefix). + + Each entry registration MUST include a content-type that is used to + indicate the nature of the annotation value. Where applicable, a + charset parameter MUST be included with the content-type. + +6.1. Entry and Attribute Registration Template + + To: iana@iana.org + Subject: IMAP METADATA Entry Registration + + Type: [Either "Mailbox" or "Server"] + + Name: [the name of the entry] + + Description: [a description of what the entry is for] + + Content-type: [MIME Content-Type and charset for the entry value] + + RFC Number: [for entries published as RFCs] + + Contact: [email and/or physical address to contact for + additional information] + +6.2. Server Entry Registrations + + The following templates specify the IANA registrations of annotation + entries specified in this document. + + + + + + + + + + + + + + + + + +Daboo Standards Track [Page 16] + +RFC 5464 The IMAP METADATA Extension February 2009 + + +6.2.1. /shared/comment + + To: iana@iana.org + Subject: IMAP METADATA Entry Registration + + Type: Server + + Name: /shared/comment + + Description: Defines a comment or note that is associated + with the server and that is shared with + authorized users of the server. + + Content-type: text/plain; charset=utf-8 + + RFC Number: RFC 5464 + + Contact: IMAP Extensions mailto:ietf-imapext@imc.org + +6.2.2. /shared/admin + + To: iana@iana.org + Subject: IMAP METADATA Entry Registration + + Type: Server + + Name: /shared/admin + + Description: Indicates a method for contacting the server + administrator. The value MUST be a URI (e.g., a + mailto: or tel: URL). This entry is always + read-only -- clients cannot change it. It is visible + to authorized users of the system. + + Content-type: text/plain; charset=utf-8 + + RFC Number: RFC 5464 + + Contact: IMAP Extensions mailto:ietf-imapext@imc.org + +6.3. Mailbox Entry Registrations + + The following templates specify the IANA registrations of annotation + entries specified in this document. + + + + + + + +Daboo Standards Track [Page 17] + +RFC 5464 The IMAP METADATA Extension February 2009 + + +6.3.1. /shared/comment + + To: iana@iana.org + Subject: IMAP METADATA Entry Registration + + Type: Mailbox + + Name: /shared/comment + + Description: Defines a shared comment or note associated with a + mailbox. + + Content-type: text/plain; charset=utf-8 + + RFC Number: RFC 5464 + + Contact: IMAP Extensions mailto:ietf-imapext@imc.org + +6.3.2. /private/comment + + To: iana@iana.org + Subject: IMAP METADATA Entry Registration + + Type: Mailbox + + Name: /private/comment + + Description: Defines a private comment or note associated with a + mailbox. + + Content-type: text/plain; charset=utf-8 + + RFC Number: RFC 5464 + + Contact: IMAP Extensions mailto:ietf-imapext@imc.org + +7. Security Considerations + + The security considerations in Section 11 of [RFC3501] apply here + with respect to protecting annotations from snooping. Servers MAY + choose to only support the METADATA and/or METADATA-SERVER extensions + after a privacy layer has been negotiated by the client. + + Annotations can contain arbitrary data of varying size. As such, + servers MUST ensure that size limits are enforced to prevent a user + from using up all available space on a server and preventing use by + others. Clients MUST treat annotation data values as an "untrusted" + source of data as it is possible for it to contain malicious content. + + + +Daboo Standards Track [Page 18] + +RFC 5464 The IMAP METADATA Extension February 2009 + + + Annotations whose values are intended to remain private MUST be + stored only in entries that have the "/private" prefix on the entry + name. + + Excluding the above issues, the METADATA extension does not raise any + security considerations that are not present in the base IMAP + protocol, and these issues are discussed in [RFC3501]. + +8. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2244] Newman, C. and J. Myers, "ACAP -- Application + Configuration Access Protocol", RFC 2244, November 1997. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) Extension", + RFC 4314, December 2005. + + [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 + ABNF", RFC 4466, April 2006. + + [RFC5161] Gulbrandsen, A. and A. Melnikov, "The IMAP ENABLE + Extension", RFC 5161, March 2008. + + [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + +Appendix A. Acknowledgments + + The ideas expressed in this document are based on the message + annotation document that was co-authored by Randall Gellens. The + author would like to thank the following individuals for contributing + their ideas and support for writing this specification: Dave + Cridland, Arnt Gulbrandsen, Dan Karp, Alexey Melnikov, Ken Murchison, + Chris Newman, and Michael Wener. + + + + + + + + + + + + +Daboo Standards Track [Page 19] + +RFC 5464 The IMAP METADATA Extension February 2009 + + +Author's Address + + Cyrus Daboo + Apple Inc. + 1 Infinite Loop + Cupertino, CA 95014 + USA + + EMail: cyrus@daboo.name + URI: http://www.apple.com/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Daboo Standards Track [Page 20] + +RFC 5464 The IMAP METADATA Extension February 2009 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2009). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + + + + + + + + + + + +Daboo Standards Track [Page 21] + + diff --git a/imap/docs/rfc/rfc5465.txt b/imap/docs/rfc/rfc5465.txt new file mode 100644 index 00000000..3fe5bcfb --- /dev/null +++ b/imap/docs/rfc/rfc5465.txt @@ -0,0 +1,1235 @@ + + + + + + +Network Working Group A. Gulbrandsen +Request for Comments: 5465 Oryx Mail Systems GmbH +Updates: 5267 C. King +Category: Standards Track A. Melnikov + Isode Ltd. + February 2009 + + + The IMAP NOTIFY Extension + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (c) 2009 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents (http://trustee.ietf.org/ + license-info) in effect on the date of publication of this document. + Please review these documents carefully, as they describe your rights + and restrictions with respect to this document. + +Abstract + + This document defines an IMAP extension that allows a client to + request specific kinds of unsolicited notifications for specified + mailboxes, such as messages being added to or deleted from such + mailboxes. + + + + + + + + + + + + + + + + +Gulbrandsen, et al. Standards Track [Page 1] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + +Table of Contents + + 1. Overview and Rationale ..........................................3 + 2. Conventions Used in This Document ...............................4 + 3. The NOTIFY Extension ............................................4 + 3.1. The NOTIFY Command .........................................4 + 4. Interaction with the IDLE Command ...............................8 + 5. Event Types .....................................................8 + 5.1. FlagChange and AnnotationChange ............................9 + 5.2. MessageNew .................................................9 + 5.3. MessageExpunge ............................................10 + 5.4. MailboxName ...............................................11 + 5.5. SubscriptionChange ........................................12 + 5.6. MailboxMetadataChange .....................................12 + 5.7. ServerMetadataChange ......................................13 + 5.8. Notification Overflow .....................................13 + 5.9. ACL (Access Control List) Changes .........................13 + 6. Mailbox Specification ..........................................14 + 6.1. Mailbox Specifiers Affecting the Currently + Selected Mailbox ..........................................14 + 6.2. Personal ..................................................15 + 6.3. Inboxes ...................................................15 + 6.4. Subscribed ................................................15 + 6.5. Subtree ...................................................15 + 6.6. Mailboxes .................................................16 + 7. Extension to SEARCH and SORT Commands ..........................16 + 8. Formal Syntax ..................................................16 + 9. Security Considerations ........................................19 + 10. IANA Considerations ...........................................19 + 10.1. Initial LIST-EXTENDED Extended Data Item Registrations ...19 + 11. Acknowledgements ..............................................20 + 12. Normative References ..........................................20 + 13. Informative References ........................................21 + + + + + + + + + + + + + + + + + + +Gulbrandsen, et al. Standards Track [Page 2] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + +1. Overview and Rationale + + The IDLE command (defined in [RFC2177]) provides a way for the client + to go into a mode where the IMAP server pushes it notifications about + IMAP mailstore events for the selected mailbox. However, the IDLE + extension doesn't restrict or control which server events can be + sent, or what information the server sends in response to each event. + Also, IDLE only applies to the selected mailbox, thus requiring an + additional TCP connection per mailbox. + + This document defines an IMAP extension that allows clients to + express their preferences about unsolicited events generated by the + server. The extension allows clients to only receive events that + they are interested in, while servers know that they don't need to go + to the effort of generating certain types of untagged responses. + + Without the NOTIFY command defined in this document, an IMAP server + will only send information about mailstore changes to the client in + the following cases: + + - as the result of a client command (e.g., FETCH responses to a + FETCH or STORE command), + - as unsolicited responses sent just before the end of a command + (e.g., EXISTS or EXPUNGE) as the result of changes in other + sessions, and + - during an IDLE command. + + The NOTIFY command extends what information may be returned in those + last two cases, and also permits and requires the server to send + information about updates between commands. The NOTIFY command also + allows for the client to extend what information is sent unsolicited + about the selected mailbox and to request some update information to + be sent regarding other mailboxes. + + The interaction between IDLE and NOTIFY commands is described in + Section 4. + + For the new messages delivered to or appended to the selected + mailbox, the NOTIFY command can be used to request that a set of + attributes be sent to the client in an unsolicited FETCH response. + This allows a client to be a passive recipient of events and new mail + and to be able to maintain full synchronisation without having to + issue any subsequent commands except to modify the state of the + mailbox on the server. + + + + + + + +Gulbrandsen, et al. Standards Track [Page 3] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + Some mobile clients, however, may want mail "pushed" only for mail + that matches a SEARCH pattern. To meet that need, [RFC5267] is + augmented by this document to extend the UPDATE return option to + specify a list of fetch-atts to be returned when a new message is + delivered or appended in another session. + +2. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + The acronym MSN stands for Message Sequence Numbers (see Section + 2.3.1.2 of [RFC3501]). + + Example lines prefaced by "C:" are sent by the client and ones + prefaced by "S:", by the server. "[...]" means elision. + +3. The NOTIFY Extension + + IMAP servers that support this extension advertise the NOTIFY + capability. This extension adds the NOTIFY command as defined in + Section 5.1. + + A server implementing this extension is not required to implement + LIST-EXTENDED [RFC5258], even though a NOTIFY-compliant server must + be able to return extended LIST responses, defined in [RFC5258]. + +3.1. The NOTIFY Command + + Arguments: "SET" + Optional STATUS indicator + Mailboxes to be watched + Events about which to notify the client + + Or + Arguments: "NONE" + + Responses: Possibly untagged STATUS responses (for SET) + + Result: OK - The server will notify the client as requested. + NO - Unsupported NOTIFY event, NOTIFY too complex or + expensive, etc. + BAD - Command unknown, invalid, unsupported, or has + unknown arguments. + + + + + + +Gulbrandsen, et al. Standards Track [Page 4] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + The NOTIFY command informs the server that the client listens for + event notifications all the time (even when no command is in + progress), and requests the server to notify it about the specified + set of events. The NOTIFY command has two forms. NOTIFY NONE + specifies that the client is not interested in any kind of event + happening on the server. NOTIFY SET replaces the current list of + interesting events with a new list of events. + + Until the NOTIFY command is used for the first time, the server only + sends notifications while a command is being processed, and notifies + the client about these events on the selected mailbox (see Section 5 + for definitions): MessageNew, MessageExpunge, or FlagChange. It does + not notify the client about any events on other mailboxes. + + The effect of a successful NOTIFY command lasts until the next NOTIFY + command or until the IMAP connection is closed. + + A successful NOTIFY SET command MUST cause the server to immediately + return any accumulated changes to the currently selected mailbox (if + any), such as flag changes and new or expunged messages. Thus, a + successful NOTIFY SET command implies an implicit NOOP command. + + The NOTIFY SET command can request notifications of message-related + changes to the selected mailbox, whatever that may be at the time the + message notifications are being generated. This is done by + specifying either the SELECTED or the SELECTED-DELAYED mailbox + selector (see Section 6.1) in the NOTIFY SET command. If the + SELECTED/SELECTED-DELAYED mailbox selector is not specified in the + NOTIFY SET command, this means that the client doesn't want to + receive any <message-event>s for the currently selected mailbox. + This is the same as specifying SELECTED NONE. + + The client can also request notifications on other mailboxes by name + or by a limited mailbox pattern match. Message-related notifications + returned for the currently selected mailbox will be those specified + by the SELECTED/SELECTED-DELAYED mailbox specifier, even if the + selected mailbox also appears by name (or matches a pattern) in the + command. Non-message-related notifications are controlled by mailbox + specifiers other than SELECTED/SELECTED-DELAYED. + + If the NOTIFY command enables MessageNew, MessageExpunge, + AnnotationChange, or FlagChange notifications for a mailbox other + than the currently selected mailbox, and the client has specified the + STATUS indicator parameter, then the server MUST send a STATUS + response for that mailbox before NOTIFY's tagged OK. If MessageNew + is enabled, the STATUS response MUST contain MESSAGES, UIDNEXT, and + UIDVALIDITY. If MessageExpunge is enabled, the STATUS response MUST + contain MESSAGES. If either AnnotationChange or FlagChange are + + + +Gulbrandsen, et al. Standards Track [Page 5] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + included and the server also supports the CONDSTORE [RFC4551] and/or + QRESYNC [RFC5162] extensions, the STATUS response MUST contain + UIDVALIDITY and HIGHESTMODSEQ. Absence of the STATUS indicator + parameter allows the client to avoid the additional STATUS responses. + This might be useful if the client already retrieved this information + before issuing the NOTIFY command. + + Clients are advised to limit the number of mailboxes used with + NOTIFY. Particularly, if a client asks for events for all accessible + mailboxes, the server may swamp the client with updates about shared + mailboxes. This may reduce the client's battery life. Also, this + wastes both server and network resources. + + For each mailbox specified, the server verifies that the client has + access using the following test: + + - If the name does not refer to an existing mailbox, the server MUST + ignore it. + + - If the name refers to a mailbox that the client can't LIST, the + server MUST ignore it. For a server that implements [RFC4314], + this means that if the client doesn't have the 'l' (lookup) right + for the name, then the server MUST ignore the mailbox. This + behavior prevents disclosure of potentially confidential + information to clients who don't have rights to know it. + + - If the name refers to a mailbox that the client can LIST (e.g., it + has the 'l' right from [RFC4314]), but the client doesn't have + another right required for processing of the specified event(s), + then the server MUST respond with an untagged extended LIST + response containing the \NoAccess name attribute. + + The server SHOULD return the tagged OK response if the client has + access to at least one of the mailboxes specified in the current list + of interesting events. The server MAY return the tagged NO response + if the client has no access to any of the specified mailboxes and no + access can ever be granted in the future (e.g., the client specified + an event for 'Subtree Bar/Foo', 'Bar/Foo' doesn't exist, and LIST + returns \Noinferiors for the parent 'Bar'). + + If the notification would be prohibitively expensive for the server + (e.g., "notify me of all flag changes in all mailboxes"), the server + MAY refuse the command with a tagged NO [NOTIFICATIONOVERFLOW] + response. + + + + + + + +Gulbrandsen, et al. Standards Track [Page 6] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + If the client requests information for events of an unsupported type, + the server MUST refuse the command with a tagged NO response (not a + BAD). This response SHOULD contain the BADEVENT response code, which + MUST list names of all events supported by the server. + + Here's an example: + + S: * OK [CAPABILITY IMAP4REV1 NOTIFY] + C: a login bob alice + S: a OK Password matched + C: b notify set status (selected MessageNew (uid + body.peek[header.fields (from to subject)]) MessageExpunge) + (subtree Lists MessageNew) + S: * STATUS Lists/Lemonade (UIDVALIDITY 4 UIDNEXT 9999 MESSAGES + 500) + S: [...] + S: * STATUS Lists/Im2000 (UIDVALIDITY 901 UIDNEXT 1 MESSAGES 0) + S: b OK done + C: c select inbox + S: [...] (the usual 7-8 responses to SELECT) + S: c OK INBOX selected + (Time passes. A new message is delivered to mailbox + Lists/Lemonade.) + S: * STATUS Lists/Lemonade (UIDVALIDITY 4 UIDNEXT 10000 + MESSAGES 501) + (Time passes. A new message is delivered to inbox.) + S: * 127 FETCH (UID 127001 BODY[HEADER.FIELDS (From To + Subject)] {75} + S: Subject: Re: good morning + S: From: alice@example.org + S: To: bob@example.org + S: + S: ) + (Time passes. The client decides it wants to know about + one more mailbox. As the client already knows necessary + STATUS information for all mailboxes below the Lists + mailbox, and because "notify set status" would cause + STATUS responses for *all* mailboxes specified in the + NOTIFY command, including the ones for which the client + already knows STATUS information, the client issues an + explicit STATUS request for the mailbox to be added to + the watch list, followed by the NOTIFY SET without the + STATUS parameter.) + C: d STATUS misc (UIDVALIDITY UIDNEXT MESSAGES) + S: * STATUS misc (UIDVALIDITY 1 UIDNEXT 999) + S: d STATUS completed + + + + + +Gulbrandsen, et al. Standards Track [Page 7] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + C: e notify set (selected MessageNew (uid + body.peek[header.fields (from to subject)]) MessageExpunge) + (subtree Lists MessageNew) (mailboxes misc MessageNew) + S: e OK done + +4. Interaction with the IDLE Command + + If IDLE [RFC2177] (as well as this extension) is supported, then + while processing any IDLE command, the server MUST send exactly the + same events as instructed by the client using the NOTIFY command. + + NOTIFY makes IDLE unnecessary for some clients. If a client does not + use MSNs and '*' in commands, it can request MessageExpunge and + MessageNew for the selected mailbox by using the NOTIFY command + instead of entering the IDLE mode. + + A client that uses MSNs and '*' in commands can still use the NOTIFY + command if it specifies the SELECTED-DELAYED mailbox specifier in the + NOTIFY command. + +5. Event Types + + Only some of the events in [RFC5423] can be expressed in IMAP, and + for some of them there are several possible ways to express the + event. + + This section specifies the events of which an IMAP server can notify + an IMAP client, and how. + + The server SHOULD omit notifying the client if the event is caused by + this client. For example, if the client issues CREATE and has + requested a MailboxName event that would cover the newly created + mailbox, the server SHOULD NOT notify the client of the MailboxName + change. + + All event types described in this document require the 'l' and 'r' + rights (see [RFC4314]) on all observed mailboxes. Servers that don't + implement [RFC4314] should map the above rights to their access- + control model. + + If the FlagChange and/or AnnotationChange events are specified, + MessageNew and MessageExpunge MUST also be specified by the client. + Otherwise, the server MUST respond with the tagged BAD response. + + If one of MessageNew or MessageExpunge is specified, then both events + MUST be specified. Otherwise, the server MUST respond with the + tagged BAD response. + + + + +Gulbrandsen, et al. Standards Track [Page 8] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + The client can instruct the server not to send an event by omitting + the necessary event from the list of events specified in NOTIFY SET, + by using the NONE event specifier in the NOTIFY SET, or by using + NOTIFY NONE. In particular, NOTIFY SET ... NONE can be used as a + snapshot facility by clients. + +5.1. FlagChange and AnnotationChange + + If the flag and/or message annotation change happens in the selected + mailbox, the server MUST notify the client by sending an unsolicited + FETCH response, which MUST include UID and FLAGS/ANNOTATION FETCH + data items. It MAY also send new FLAGS and/or OK [PERMANENTFLAGS + ...] responses. + + If a search context is in effect as specified in [RFC5267], an + ESEARCH ADDTO or ESEARCH REMOVEFROM will also be generated, if + appropriate. In this case, the FETCH response MUST precede the + ESEARCH response. + + If the change happens in another mailbox, then the server responds + with a STATUS response. The exact content of the STATUS response + depends on various factors. If CONDSTORE [RFC4551] and/or QRESYNC + [RFC5162] are enabled by the client, then the server sends a STATUS + response that includes at least HIGHESTMODSEQ and UIDVALIDITY status + data items. If the number of messages with the \Seen flag changes, + the server MAY also include the UNSEEN data item in the STATUS + response. If CONDSTORE/QRESYNC is not enabled by the client and the + server chooses not to include the UNSEEN data item, the server does + not notify the client. When this event is requested, the server MUST + notify the client about mailbox UIDVALIDITY changes. This is done by + sending a STATUS response that includes UIDVALIDITY. + + FlagChange covers the MessageRead, MessageTrash, FlagsSet, and + FlagsClear events in [RFC5423]. + + Example in the selected mailbox: + S: * 99 FETCH (UID 9999 FLAGS ($Junk)) + + And in another mailbox, with CONDSTORE in use: + S: * STATUS Lists/Lemonade (HIGHESTMODSEQ 65666665 UIDVALIDITY + 101) + + + + + + + + + + +Gulbrandsen, et al. Standards Track [Page 9] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + +5.2. MessageNew + + This covers both MessageNew and MessageAppend in [RFC5423]. + + If the new/appended message is in the selected mailbox, the server + notifies the client by sending an unsolicited EXISTS response, + followed by an unsolicited FETCH response containing the information + requested by the client. A FETCH response SHOULD NOT be generated + for a new message created by the client on this particular + connection, for instance, as the result of an APPEND or COPY command + to the selected mailbox performed by the client itself. The server + MAY also send a RECENT response, if the server marks the message as + \Recent. + + Note that a single EXISTS response can be returned for multiple + MessageAppend/MessageNew events. + + If a search context is in effect as specified in [RFC5267], an + ESEARCH ADDTO will also be generated, if appropriate. In this case, + the EXISTS response MUST precede the ESEARCH response. Both the + NOTIFY command and the SEARCH and SORT commands (see Section 7) can + specify attributes to be returned for new messages. These attributes + SHOULD be combined into a single FETCH response. The server SHOULD + avoid sending duplicate data. The FETCH response(s) MUST follow any + ESEARCH ADDTO responses. + + If the new/appended message is in another mailbox, the server sends + an unsolicited STATUS (UIDNEXT MESSAGES) response for the relevant + mailbox. If the CONDSTORE extension [RFC4551] and/or the QRESYNC + extension [RFC5162] is enabled, the HIGHESTMODSEQ status data item + MUST be included in the STATUS response. + + The client SHOULD NOT use FETCH attributes that implicitly set the + \seen flag, or that presuppose the existence of a given bodypart. + UID, MODSEQ, FLAGS, ENVELOPE, BODY.PEEK[HEADER.FIELDS... and + BODY/BODYSTRUCTURE may be the most useful attributes. + + Note that if a client asks to be notified of MessageNew events with + the SELECTED mailbox specifier, the number of messages can increase + at any time, and therefore the client cannot refer to a specific + message using the MSN/UID '*'. + + Example in the selected mailbox: + S: * 444 EXISTS + S: * 444 FETCH (UID 9999) + + And in another mailbox, without CONDSTORE enabled: + S: * STATUS Lists/Lemonade (UIDNEXT 10002 MESSAGES 503) + + + +Gulbrandsen, et al. Standards Track [Page 10] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + +5.3. MessageExpunge + + If the expunged message or messages are in the selected mailbox, the + server notifies the client using EXPUNGE (or VANISHED, if [RFC5162] + is supported by the server and enabled by the client). + + If a search context is in effect, as specified in [RFC5267], an + ESEARCH REMOVEFROM will also be generated, if appropriate. + + If the expunged message or messages are in another mailbox, the + server sends an unsolicited STATUS (UIDNEXT MESSAGES) response for + the relevant mailbox. If the QRESYNC [RFC5162] extension is enabled, + the HIGHESTMODSEQ data item MUST be included in the STATUS response + as well. + + Note that if a client requests MessageExpunge with the SELECTED + mailbox specifier, the meaning of an MSN can change at any time, so + the client cannot use MSNs in commands anymore. For example, such a + client cannot use FETCH, but has to use UID FETCH. The meaning of + '*' can also change when messages are added or expunged. A client + wishing to keep using MSNs can either use the SELECTED-DELAYED + mailbox specifier or can avoid using the MessageExpunge event + entirely. + + The MessageExpunge notification covers both MessageExpunge and + MessageExpire events from [RFC5423]. + + Example in the selected mailbox, without QRESYNC: + S: * 444 EXPUNGE + + The same example in the selected mailbox, with QRESYNC: + S: * VANISHED 5444 + + And in another mailbox, when QRESYNC is not enabled: + S: * STATUS misc (UIDNEXT 999 MESSAGES 554) + +5.4. MailboxName + + These notifications are sent if an affected mailbox name was created + (with CREATE), deleted (with DELETE), or renamed (with RENAME). For + a server that implements [RFC4314], granting or revocation of the 'l' + right to the current user on the affected mailbox MUST be considered + mailbox creation or deletion, respectively. If a mailbox is created + or deleted, the mailbox itself and its direct parent (whether it is + an existing mailbox or not) are considered to be affected. + + + + + + +Gulbrandsen, et al. Standards Track [Page 11] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + The server notifies the client by sending an unsolicited LIST + response for each affected mailbox name. If, after the event, the + mailbox name does not refer to a mailbox accessible to the client, + the \Nonexistent flag MUST be included. + + For each LISTable mailbox renamed, the server sends an extended LIST + response [RFC5258] for the new mailbox name, containing the OLDNAME + extended data item with the old mailbox name. When a mailbox is + renamed, its children are renamed too. No additional MailboxName + events are sent for children in this case. When INBOX is renamed, a + new INBOX is assumed to be created. No MailboxName event is sent for + INBOX in this case. + + If the server automatically subscribes a mailbox when it is created + or renamed, then the unsolicited LIST response for each affected + subscribed mailbox name MUST include the \Subscribed attribute (see + [RFC5258]). The server SHOULD also include \HasChildren or + \HasNoChildren attributes [RFC5258] as appropriate. + + Example of a newly created mailbox (or granting of the 'l' right on + the mailbox): + S: * LIST () "/" "NewMailbox" + + And a deleted mailbox (or revocation of the 'l' right on the + mailbox): + S: * LIST (\NonExistent) "." "INBOX.DeletedMailbox" + + Example of a renamed mailbox: + S: * LIST () "/" "NewMailbox" ("OLDNAME" ("OldMailbox")) + +5.5. SubscriptionChange + + The server notifies the client by sending an unsolicited LIST + response for each affected mailbox name. If and only if the mailbox + is subscribed after the event, the \Subscribed attribute (see + [RFC5258]) is included. Note that in the LIST response, all mailbox + attributes MUST be accurately computed (this differs from the + behavior of the LSUB command). + + Example: + S: * LIST (\Subscribed) "/" "SubscribedMailbox" + +5.6. MailboxMetadataChange + + Support for this event type is OPTIONAL unless the METADATA extension + [RFC5464] is also supported by the server, in which case support for + this event type is REQUIRED. + + + + +Gulbrandsen, et al. Standards Track [Page 12] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + A client willing to receive unsolicited METADATA responses as a + result of using the MailboxMetadataChange event in the NOTIFY command + doesn't have to issue ENABLE METADATA. + + The server sends an unsolicited METADATA response (as per Section + 4.4.2 of [RFC5464]). If possible, only the changed metadata SHOULD + be included, but if the server can't detect a change to a single + metadata item, it MAY include all metadata items set on the mailbox. + If a metadata item is deleted (set to NIL), it MUST always be + included in the METADATA response. + + Example: + S: * METADATA "INBOX" /shared/comment + +5.7. ServerMetadataChange + + Support for this event type is OPTIONAL unless the METADATA or the + METADATA-SERVER extension [RFC5464] is also supported by the server, + in which case support for this event type is REQUIRED. + + A client willing to receive unsolicited METADATA responses as a + result of using the ServerMetadataChange event in the NOTIFY command + doesn't have to issue ENABLE METADATA or ENABLE METADATA-SERVER. + + The server sends an unsolicited METADATA response (as per Section + 4.4.2 of [RFC5464]). Only the names of changed metadata entries + SHOULD be returned in such METADATA responses. If a metadata item is + deleted (set to NIL), it MUST always be included in the METADATA + response. + + Example: + S: * METADATA "" /shared/comment + +5.8. Notification Overflow + + If the server is unable or unwilling to deliver as many notifications + as it is being asked to, it may disable notifications for some or all + clients. It MUST notify these clients by sending an untagged "OK + [NOTIFICATIONOVERFLOW]" response and behave as if a NOTIFY NONE + command had just been received. + + Example: + S: * OK [NOTIFICATIONOVERFLOW] ...A comment can go here... + + + + + + + + +Gulbrandsen, et al. Standards Track [Page 13] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + +5.9. ACL (Access Control List) Changes + + Even if NOTIFY succeeds, it is still possible to lose access to the + mailboxes being monitored at a later time. If this happens, the + server MUST stop monitoring these mailboxes. If access is later + granted, the server MUST restart event monitoring. + + The server SHOULD return the LIST response with the \NoAccess name + attribute if and when the mailbox loses the 'l' right. Similarly, + the server SHOULD return the LIST response with no \NoAccess name + attribute if the mailbox was previously reported as having \NoAccess + and the 'l' right is later granted. + +6. Mailbox Specification + + Mailboxes to be monitored can be specified in several different ways. + + Only 'SELECTED' and 'SELECTED-DELAYED' (Section 6.1) match the + currently selected mailbox. All other mailbox specifications affect + other (non-selected) mailboxes. + + Note that multiple <event-group>s can apply to the same mailbox. The + following example demonstrates this. In this example, MessageNew and + MessageExpunge events are reported for INBOX, due to the first + <event-group>. A SubscriptionChange event will also be reported for + INBOX, due to the second <event-group>. + + C: a notify set (mailboxes INBOX (Messagenew messageExpunge)) + (personal (SubscriptionChange)) + + A typical client that supports the NOTIFY extension would ask for + events on the selected mailbox and some named mailboxes. + + In the next example, the client asks for FlagChange events for all + personal mailboxes except the currently selected mailbox. This is + different from the previous example because SELECTED overrides all + other message event definitions for the currently selected mailbox + (see Section 3.1). + + C: a notify set (selected (Messagenew (uid flags) messageExpunge)) + (personal (MessageNew FlagChange MessageExpunge)) + +6.1. Mailbox Specifiers Affecting the Currently Selected Mailbox + + Only one of the mailbox specifiers affecting the currently selected + mailbox can be specified in any NOTIFY command. The two such mailbox + specifiers (SELECTED and SELECTED-DELAYED) are described below. + + + + +Gulbrandsen, et al. Standards Track [Page 14] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + Both refer to the mailbox that was selected using either SELECT or + EXAMINE (see [RFC3501], Sections 6.3.1 and 6.3.2). When the IMAP + connection is not in the selected state, such mailbox specifiers + don't refer to any mailbox. + + The mailbox specifiers only apply to <message-event>s. It is an + error to specify other types of events with either the SELECTED or + the SELECTED-DELAYED selector. + +6.1.1. Selected + + The SELECTED mailbox specifier requires the server to send immediate + notifications for the currently selected mailbox about all specified + <message-event>s. + +6.1.2. Selected-Delayed + + The SELECTED-DELAYED mailbox specifier requires the server to delay a + MessageExpunge event until the client issues a command that allows + returning information about expunged messages (see Section 7.4.1 of + [RFC3501] for more details), for example, till a NOOP or an IDLE + command has been issued. When SELECTED-DELAYED is specified, the + server MAY also delay returning other <message-event>s until the + client issues one of the commands specified above, or it MAY return + them immediately. + +6.2. Personal + + Personal refers to all selectable mailboxes in the user's personal + namespace(s), as defined in [RFC2342]. + +6.3. Inboxes + + Inboxes refers to all selectable mailboxes in the user's personal + namespace(s) to which messages may be delivered by a Message Delivery + Agent (MDA) (see [EMAIL-ARCH], particularly Section 4.3.3). + + If the IMAP server cannot easily compute this set, it MUST treat + "inboxes" as equivalent to "personal". + +6.4. Subscribed + + Subscribed refers to all mailboxes subscribed to by the user. + + If the subscription list changes, the server MUST reevaluate the + list. + + + + + +Gulbrandsen, et al. Standards Track [Page 15] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + +6.5. Subtree + + Subtree is followed by a mailbox name or list of mailbox names. A + subtree refers to all selectable mailboxes that are subordinate to + the specified mailbox plus the specified mailbox itself. + +6.6. Mailboxes + + Mailboxes is followed by a mailbox name or a list of mailbox names. + The server MUST NOT do a wildcard expansion. This means there is no + special treatment for the LIST wildcard characters ('*' and '%') if + they are present in mailbox names. + +7. Extension to SEARCH and SORT Commands + + If the server that supports the NOTIFY extension also supports + CONTEXT=SEARCH and/or CONTEXT=SORT as defined in [RFC5267], the + UPDATE return option is extended so that a client can request that + FETCH attributes be returned when a new message is added to the + context result set. + + For example: + + C: a00 SEARCH RETURN (COUNT UPDATE (UID BODY[HEADER.FIELDS (TO + FROM SUBJECT)])) FROM "boss" + S: * ESEARCH (TAG "a00") (COUNT 17) + S: a00 OK + [...a new message is delivered...] + S: * EXISTS 93 + S: * 93 FETCH (UID 127001 BODY[HEADER.FIELDS (FROM TO SUBJECT)] + {76} + S: Subject: Re: good morning + S: From: myboss@example.org + S: To: bob@example.org + S: + S: ) + S: * ESEARCH (TAG "a00") ADDTO (0 93) + + Note that the EXISTS response MUST precede any FETCH responses, and + together they MUST precede the ESEARCH response. + + No untagged FETCH response SHOULD be returned if a message becomes a + member of UPDATE SEARCH due to flag or annotation changes. + + + + + + + + +Gulbrandsen, et al. Standards Track [Page 16] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + +8. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [RFC5234]. [RFC3501] defines + the non-terminals "capability", "command-auth", "mailbox", "mailbox- + data", "resp-text-code", and "search-key". The "modifier-update" + non-terminal is defined in [RFC5267]. "mbx-list-oflag" is defined in + [RFC3501] and updated by [RFC5258]. + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of upper or lower case characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. For example, the + <filter-mailboxes-selected> non-terminal value "SELECTED" must be + treated in the same way as "Selected" or "selected". + + capability =/ "NOTIFY" + + command-auth =/ notify + + notify = "NOTIFY" SP + (notify-set / notify-none) + + notify-set = "SET" [status-indicator] SP event-groups + ; Replace registered notification events + ; with the specified list of events + + notify-none = "NONE" + ; Cancel all registered notification + ; events. The client is not interested + ; in receiving any events. + + status-indicator = SP "STATUS" + + one-or-more-mailbox = mailbox / many-mailboxes + + many-mailboxes = "(" mailbox *(SP mailbox) ")" + + event-groups = event-group *(SP event-group) + + event-group = "(" filter-mailboxes SP events ")" + ;; Only <message-event>s are allowed in <events> + ;; when <filter-mailboxes-selected> is used. + + filter-mailboxes = filter-mailboxes-selected / + filter-mailboxes-other + + + + + +Gulbrandsen, et al. Standards Track [Page 17] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + filter-mailboxes-other = "inboxes" / "personal" / "subscribed" / + ( "subtree" SP one-or-more-mailbox ) / + ( "mailboxes" SP one-or-more-mailbox ) + + filter-mailboxes-selected = "selected" / "selected-delayed" + ;; Apply to the currently selected mailbox only. + ;; Only one of them can be specified in a NOTIFY + ;; command. + + events = ( "(" event *(SP event) ")" ) / "NONE" + ;; As in [MSGEVENT]. + ;; "NONE" means that the client does not wish + ;; to receive any events for the specified + ;; mailboxes. + + event = message-event / + mailbox-event / user-event / event-ext + + message-event = ( "MessageNew" [SP + "(" fetch-att *(SP fetch-att) ")" ] ) + / "MessageExpunge" + / "FlagChange" + / "AnnotationChange" + ;; "MessageNew" includes "MessageAppend" from + ;; [MSGEVENT]. "FlagChange" is any of + ;; "MessageRead", "MessageTrash", "FlagsSet", + ;; "FlagsClear" [MSGEVENT]. "MessageExpunge" + ;; includes "MessageExpire" [MSGEVENT]. + ;; MessageNew and MessageExpunge MUST always + ;; be specified together. If FlagChange is + ;; specified, then MessageNew and MessageExpunge + ;; MUST be specified as well. + ;; The fett-att list may only be present for the + ;; SELECTED/SELECTED-DELAYED mailbox filter + ;; (<filter-mailboxes>). + + mailbox-event = "MailboxName" / + "SubscriptionChange" / "MailboxMetadataChange" + ; "SubscriptionChange" includes + ; MailboxSubscribe and MailboxUnSubscribe. + ; "MailboxName" includes MailboxCreate, + ; "MailboxDelete" and "MailboxRename". + + user-event = "ServerMetadataChange" + + event-ext = atom + ;; For future extensions + + + + +Gulbrandsen, et al. Standards Track [Page 18] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + oldname-extended-item = "OLDNAME" SP "(" mailbox ")" + ;; Extended data item (mbox-list-extended-item) + ;; returned in a LIST response when a mailbox is + ;; renamed. + ;; Note 1: the OLDNAME tag can be returned + ;; with or without surrounding quotes, as per + ;; mbox-list-extended-item-tag production. + + resp-text-code =/ "NOTIFICATIONOVERFLOW" / + unsupported-events-code + + message-event-name = "MessageNew" / + "MessageExpunge" / "FlagChange" / + "AnnotationChange" + + event-name = message-event-name / mailbox-event / + user-event + + unsupported-events-code = "BADEVENT" + SP "(" event-name *(SP event-name) ")" + + modifier-update = "UPDATE" + [ "(" fetch-att *(SP fetch-att) ")" ] + + mbx-list-oflag =/ "\NoAccess" + +9. Security Considerations + + It is very easy for a client to deny itself service using NOTIFY. + Asking for all events on all mailboxes may work on a small server, + but with a big server, can swamp the client's network connection or + processing capability. In the worst case, the server's processing + could also degrade the service it offers to other clients. + + Server authors should be aware that if a client issues requests and + does not listen to the resulting responses, the TCP window can easily + fill up, and a careless server might block. This problem also exists + in plain IMAP; however, this extension magnifies the problem. + + This extension makes it possible to retrieve messages immediately + when they are added to the mailbox. This makes it wholly impractical + to delete sensitive messages using programs like imapfilter. Using + SIEVE [RFC5228] or similar is much better. + + + + + + + + +Gulbrandsen, et al. Standards Track [Page 19] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + +10. IANA Considerations + + The IANA has added NOTIFY to the list of IMAP extensions. + +10.1. Initial LIST-EXTENDED Extended Data Item Registrations + + The following entry has been added to the LIST-EXTENDED response + registry [RFC5258]: + + To: iana@iana.org + Subject: Registration of OLDNAME LIST-EXTENDED extended data item + + LIST-EXTENDED extended data item tag: OLDNAME + + LIST-EXTENDED extended data item description: The OLDNAME extended + data item describes the old mailbox name for the mailbox + identified by the LIST response. + + Which LIST-EXTENDED option(s) (and their types) causes this extended + data item to be returned (if any): none + + Published specification : RFC 5465, Section 5.4. + + Security considerations: none + + Intended usage: COMMON + + Person and email address to contact for further information: Alexey + Melnikov <Alexey.Melnikov@isode.com> + + Owner/Change controller: iesg@ietf.org + +11. Acknowledgments + + The authors gratefully acknowledge the help of Peter Coates, Dave + Cridland, Mark Crispin, Cyrus Daboo, Abhijit Menon-Sen, Timo + Sirainen, and Eric Burger. In particular, Peter Coates contributed + lots of text and useful suggestions to this document. + + Various examples are copied from other RFCs. + + This document builds on one published and two unpublished drafts by + the same authors. + + + + + + + + +Gulbrandsen, et al. Standards Track [Page 20] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + +12. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2177] Leiba, B., "IMAP4 IDLE command", RFC 2177, June 1997. + + [RFC2342] Gahrns, M. and C. Newman, "IMAP4 Namespace", RFC 2342, + May 1998. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) + Extension", RFC 4314, December 2005. + + [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to + IMAP4 ABNF", RFC 4466, April 2006. + + [RFC4551] Melnikov, A. and S. Hole, "IMAP Extension for + Conditional STORE Operation or Quick Flag Changes + Resynchronization", RFC 4551, June 2006. + + [RFC5162] Melnikov, A., Cridland, D., and C. Wilson, "IMAP4 + Extensions for Quick Mailbox Resynchronization", RFC + 5162, March 2008. + + [RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", STD 68, RFC 5234, January + 2008. + + [RFC5258] Leiba, B. and A. Melnikov, "Internet Message Access + Protocol version 4 - LIST Command Extensions", RFC 5258, + June 2008. + + [RFC5267] Cridland, D. and C. King, "Contexts for IMAP4", RFC + 5267, July 2008. + + [RFC5423] Newman, C. and R. Gellens, "Internet Message Store + Events", RFC 5423, Month 2009. + + [RFC5464] Daboo, C., "The IMAP METADATA Extension", RFC 5464, + February 2009. + +13. Informative References + + [RFC5228] Guenther, P., Ed., and T. Showalter, Ed., "Sieve: An + Email Filtering Language", RFC 5228, January 2008. + + + +Gulbrandsen, et al. Standards Track [Page 21] + +RFC 5465 IMAP NOTIFY Extension February 2009 + + + [EMAIL-ARCH] Crocker, D., "Internet Mail Architecture", Work in + Progress, October 2008. + +Authors' Addresses + + Arnt Gulbrandsen + Oryx Mail Systems GmbH + Schweppermannstr. 8 + D-81671 Muenchen + Germany + + EMail: arnt@oryx.com + + + Curtis King + Isode Ltd + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: Curtis.King@isode.com + + + Alexey Melnikov + Isode Ltd + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: Alexey.Melnikov@isode.com + + + + + + + + + + + + + + + + + + + +Gulbrandsen, et al. Standards Track [Page 22] + diff --git a/imap/docs/rfc/rfc5466.txt b/imap/docs/rfc/rfc5466.txt new file mode 100644 index 00000000..d566a5f5 --- /dev/null +++ b/imap/docs/rfc/rfc5466.txt @@ -0,0 +1,507 @@ + + + + + + +Network Working Group A. Melnikov +Request for Comments: 5466 C. King +Category: Standards Track Isode Ltd + February 2009 + + + IMAP4 Extension for Named Searches (Filters) + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (c) 2009 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents (http://trustee.ietf.org/ + license-info) in effect on the date of publication of this document. + Please review these documents carefully, as they describe your rights + and restrictions with respect to this document. + +Abstract + + The document defines a way to persistently store named IMAP (RFC + 3501) searches on the server. Such named searches can be + subsequently referenced in a SEARCH or any other command that accepts + a search criterion as a parameter. + +Table of Contents + + 1. Introduction and Overview . . . . . . . . . . . . . . . . . . . 2 + 2. Conventions Used in This Document . . . . . . . . . . . . . . . 2 + 3. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . . 2 + 3.1. FILTER SEARCH Criterion . . . . . . . . . . . . . . . . . . 3 + 3.2. Managing Filters Using SETMETADATA/GETMETADATA Commands . . 4 + 4. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 5. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 + 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7 + 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . 8 + 8. Normative References . . . . . . . . . . . . . . . . . . . . . 8 + + + + + +Melnikov & King Standards Track [Page 1] + +RFC 5466 IMAP Filters February 2009 + + +1. Introduction and Overview + + Persistent named searches described in this document allow clients to + save favorite searches on the server. Such saved searches can save + bandwidth for clients that need to regularly repeat them. + + The FILTERS IMAP extension adds a new FILTER search criterion for + referencing persistent named searches (a.k.a. "filters"), as well as + reuses GETMETADATA/SETMETADATA commands [METADATA] for listing/ + creating/updating/deleting such filters. + + A filter can be private (only accessible to the logged-in user) or + public (accessible to all logged-in users). Both a private and a + public filter with the same name can exist at the same time. If both + filter types with the same name exist, the FILTER SEARCH criterion + (see Section 3.1) MUST use the value of the private filter; + otherwise, it MUST use the value of the filter that exists. + + Let us call a pair of filter name and filter type a "typed filter". + Each typed filter can have a value (which is a valid IMAP SEARCH + criteria conforming to ABNF for the "search-criteria" non-terminal) + and an optional human-readable description. The SETMETADATA command + creates or updates the value and/or the description of a typed + filter. + + Values of all search keys stored in a filter MUST be encoded in + UTF-8. + +2. Conventions Used in This Document + + 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 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]. + + Basic familiarity with the METADATA-SERVER extension [METADATA] and + terms defined therein is required to understand this document. + +3. IMAP Protocol Changes + + The IMAP extension for persistent named searches is present in any + IMAP4 implementation that advertises "FILTERS" as one of the + supported capabilities in the CAPABILITY response or response code. + + + +Melnikov & King Standards Track [Page 2] + +RFC 5466 IMAP Filters February 2009 + + +3.1. FILTER SEARCH Criterion + + The FILTER criterion for the SEARCH command allows a client to + reference by name a filter stored on the server. Such filter was + created by setting the server annotation named "/private/filters/ + values/<filter_name>" (or the server annotation "/shared/filters/ + values/<filter_name>", if "/private/filters/values/<filter_name>" + doesn't exist) using the SETMETADATA command as described in + Section 3.2. + + Syntax: FILTER <filter_name> + + When the named filter exists, its search criterion (i.e., the + associated entry value) is inserted verbatim instead of the FILTER + search-key. For example, the following SEARCH command + + C: a SEARCH UID 300:900 FILTER on-the-road SINCE "3-Dec-2002" + + would be equivalent to the following + + C: a SEARCH UID 300:900 OR SMALLER 5000 FROM "boss@example.com" + SINCE "3-Dec-2002" + + assuming the filter "on-the-road" exists and contains the value 'OR + SMALLER 5000 FROM "boss@example.com"'. + + A reference to a nonexistent or unaccessible (e.g., due to access + control restrictions) filter MUST cause failure of the SEARCH command + with the tagged NO response that includes the UNDEFINED-FILTER + response code followed by the name of the nonexistent/unaccessible + filter. + + Note the server SHOULD verify that each search criterion referenced + by the FILTER search key is a full and correct search criterion. For + example, the server should fail the SEARCH command if its SEARCH + criterion references a filter containing "OR SMALLER" search + criterion, because this value is lacking one parameter and thus is + not a fully specified search criterion. + + Note that a named filter itself can reference another filter using + the FILTER search-key. Implementations MUST be able to perform at + least 3 substitution passes on the SEARCH command criterion. If an + implementation allows for more passes, it MUST implement some kind of + loop detection. If an implementation detects a loop or still sees a + FILTER search-key after performing at least 3 substitutions, it MUST + behave as if the specified filter doesn't exist (as described above). + + + + + +Melnikov & King Standards Track [Page 3] + +RFC 5466 IMAP Filters February 2009 + + + Note that use of the FILTER search key implies the CHARSET "UTF-8" + parameter to the SEARCH/UID SEARCH command. If the SEARCH/UID SEARCH + command includes the explicit CHARSET parameter with the value other + than "UTF-8" or "US-ASCII", then such command MUST result in the + tagged BAD response from the server. Such tagged response MUST + contain the BADCHARSET response code (see [RFC3501]). + +3.2. Managing Filters Using SETMETADATA/GETMETADATA Commands + + Any server compliant with this document MUST either implement the + METADATA-SERVER (or METADATA) [METADATA] extension, or implement + SETMETADATA/GETMETADATA commands described in [METADATA] so that they + work for the case of empty mailbox name (i.e., for managing server + annotations) and for the entries specified in this section. + + This document reserves two hierarchies of per-server entries under + the "/private/filters/values" and "/shared/filters/values" roots (see + [METADATA]) for storing filter values. The value of a "/private/ + filters/values/<filter_name>" or a "/shared/filters/values/ + <filter_name>" server annotation is an IMAP SEARCH criteria, + conforming to ABNF for the "search-criteria" non-terminal. A name of + a filter is governed by the ABNF for the "filter-name" non-terminal. + + Note that values of all search keys stored in these entries MUST be + encoded in UTF-8. + + A new filter named "<filter_name>" can be created (or an existing + filter can be modified) by storing a non-NIL value in the "/private/ + filters/values/<filter_name>" server entry (or in the "/shared/ + filters/values/<filter_name>") using the SETMETADATA [METADATA] + command. The server SHOULD verify that each search criterion stored + in such a server entry is a full and correct search criterion. + + A filter can be deleted by storing the NIL value in both the + "/private/filters/values/<filter_name>" and the "/shared/filters/ + values/<filter_name>" entries. + + A filter can be renamed by first creating a filter with the new name + (that has the same value as the old one) and then deleting the filter + with the old one. + + If both "/private/filters/values/<filter_name>" and "/shared/filters/ + values/<filter_name>" server annotations exist, then the value of the + "/private/filters/values/<filter_name>" is used when evaluating the + corresponding FILTER SEARCH key (see Section 3.1). Otherwise the + non-NIL (existent) value is used. + + + + + +Melnikov & King Standards Track [Page 4] + +RFC 5466 IMAP Filters February 2009 + + + If the server is unable to create a new typed filter because the + maximum number of allowed filters has already been reached, the + server MUST return a tagged NO response with a "[METADATA TOOMANY]" + response code, as defined in [METADATA]. + + C: a007 SETMETADATA "" ("/private/filters/values/on-the-road" + "OR SMALLER 5000 FROM \"boss@example.com\"") + S: a007 OK SETMETADATA complete + + Client implementation note: As multiple clients might read and write + filter values, it is possible that one client will use a SEARCH key + that might not be recognized by another client that tries to present + a user interface for editing a filter value. In order to help other + clients to (partially) parse filter values for editing purposes, a + client storing a filter value SHOULD use () around any SEARCH key not + defined in [RFC3501]. For example, if there is an IMAP extension + that defines a new x-dsfa SEARCH key that takes 2 parameters, then + the following SEARCH criterion 'from "@example.com>" x-dsfa from 5' + should be stored as 'from "@example.com>" (x-dsfa from 5)'. + + Note that filter names are restricted to a subset of US-ASCII, as + described in Section 4. So they might not always be meaningful to + users and thus not necessarily suitable for display purposes. In + order to help with storing human-readable descriptions of filters, + this document also reserves two hierarchies of server entries under + the "/private/filters/descriptions" and "/shared/filters/ + descriptions" roots. The value of a "/private/filters/descriptions/ + <filter_name>" or a "/shared/filters/descriptions/<filter_name>" + server annotation is a human-readable description for the + <filter_name> filter, encoded in UTF-8 [UTF-8]. If the "/private/ + filters/descriptions/<filter_name>" server annotation exists, its + value is used by the client as the filter description. Otherwise, + the value of the "/shared/filters/descriptions/<filter_name>" server + annotation is used as the filter description. In the absence of both + the "/private/filters/descriptions/<filter_name>" and the "/shared/ + filters/descriptions/<filter_name>" entries, the client MAY display + the name of the filter as its description. + + The description string SHOULD be annotated with one or more language + tags [RFC4646] as specified in Chapter 16.9 of [Unicode]. In the + absence of any language tag, the "i-default" [RFC2277] language + SHOULD be assumed. Description in multiple languages MAY be present + in a single description string. This is done by concatenating + descriptions in multiple languages into a single string, each + description prefixed with its language tag, for example + "<ru><...description in Russian...><fr-ca><...description in + French...>". Note that here <ru> is a language tag consisting of 3 + Unicode characters: <U+E0001>, <U+E0072>, <U+E0075>; and <fr-ca> is a + + + +Melnikov & King Standards Track [Page 5] + +RFC 5466 IMAP Filters February 2009 + + + language tag consisting of 6 Unicode characters: <U+E0001>, + <U+E0066>, <U+E0072>, <U+E002D>, <U+E0063>, <U+E0061>. + +4. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [ABNF]. + + Non-terminals referenced but not defined below are as defined by + [RFC3501] or [IMAPABNF]. + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of upper or lower case characters to define + token strings is for editorial clarity only. Implementations MUST + accept these strings in a case-insensitive fashion. + + capability =/ "FILTERS" + + search-criteria = search-key *(SP search-key) + + search-key =/ "FILTER" SP filter-name + ;; New SEARCH criterion for referencing filters + + filter-name = 1*<any ATOM-CHAR except "/"> + ;; Note that filter-name disallows UTF-8 or + ;; the following characters: "(", ")", "{", + ;; " ", "%", "*", "]". See definition of + ;; ATOM-CHAR [RFC3501]. + + resp-text-code =/ "UNDEFINED-FILTER" SP filter-name + +5. Security Considerations + + General issues relevant to [RFC3501] (in particular to the SEARCH + command) and METADATA-SERVER extension [METADATA] are also relevant + to this document. + + Note that excessive use of filters can potentially simplify denial- + of-service attacks, especially if combined with poor implementations + and lack of loop detection (i.e., detection of filters referencing + each other to create a loop). Servers that allow for anonymous + access SHOULD NOT allow anonymous users to create/edit/delete + filters. + + Also note that stored filters can potentially disclose personal + information about users. When confidentiality of such information is + important, clients MUST use TLS and/or SASL security layer (or + similar) as recommended in [RFC3501]. Also, clients should use + + + +Melnikov & King Standards Track [Page 6] + +RFC 5466 IMAP Filters February 2009 + + + private filters instead of public, unless they desire to share such + information with other users. + + As always, it is important to thoroughly test clients and servers + when implementing this extension. + +6. IANA Considerations + + IMAP4 capabilities are registered by publishing a Standards Track or + IESG-approved Experimental RFC. The IMAP4 capabilities registry is + available from http://www.iana.org. + + This document defines the FILTERS IMAP capability. IANA has added it + to the registry. + + IANA has added the following 4 entries to the [METADATA] registry: + + To: iana@iana.org + Subject: IMAP METADATA Entry Registration + Type: Server + Name: /private/filters/values/<filter_name> + Description: Contains an IMAP SEARCH criteria. Defined in RFC 5466. + Content-type: text/plain; charset=utf-8 + Contact person: Alexey Melnikov + Email: alexey.melnikov@isode.com + + To: iana@iana.org + Subject: IMAP METADATA Entry Registration + Type: Server + Name: /shared/filters/values/<filter_name> + Description: Contains an IMAP SEARCH criterion. Defined in RFC + 5466. + Content-type: text/plain; charset=utf-8 + Contact person: Alexey Melnikov + Email: alexey.melnikov@isode.com + + To: iana@iana.org + Subject: IMAP METADATA Entry Registration + Type: Server + Name: /private/filters/descriptions/<filter_name> + Description: Contains a user-specific human-readable description of + a named SEARCH criterion stored in the /private/filters/values/ + <filter_name> or /shared/filters/values/<filter_name> annotation. + The value is in UTF-8. Defined in RFC 5466. + Content-type: text/plain; charset=utf-8 + Contact person: Alexey Melnikov + Email: alexey.melnikov@isode.com + + + + +Melnikov & King Standards Track [Page 7] + +RFC 5466 IMAP Filters February 2009 + + + To: iana@iana.org + Subject: IMAP METADATA Entry Registration + Type: Server + Name: /shared/filters/descriptions/<filter_name> + Description: Contains a global (shared among all users) human- + readable description of a named SEARCH criterion stored in the + /private/filters/values/<filter_name> or /shared/filters/values/ + <filter_name> annotation. The value is in UTF-8. Defined in RFC + 5466. + Content-type: text/plain; charset=utf-8 + Contact person: Alexey Melnikov + Email: alexey.melnikov@isode.com + +7. Acknowledgments + + Thanks to David Cridland, Arnt Gulbrandsen, Chris Newman, and Timo + Sirainen for comments and suggestions on this document. Special + thank you to Brian E. Carpenter for the GenArt review. + +8. Normative References + + [ABNF] Crocker, D., Ed. and P. Overell, Ed., "Augmented BNF for + Syntax Specifications: ABNF", STD 68, RFC 5234, + January 2008. + + [IMAPABNF] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 + ABNF", RFC 4466, April 2006. + + [METADATA] Daboo, C., "The IMAP METADATA Extension", RFC 5464, + February 2009. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and + Languages", BCP 18, RFC 2277, January 1998. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [RFC4646] Phillips, A. and M. Davis, "Tags for Identifying + Languages", BCP 47, RFC 4646, September 2006. + + [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. + + [Unicode] "The Unicode Standard 5.0", Unicode 5.0, 2007, + <http://www.unicode.org/versions/Unicode5.0.0/>. + + + +Melnikov & King Standards Track [Page 8] + +RFC 5466 IMAP Filters February 2009 + + +Authors' Addresses + + Alexey Melnikov + Isode Ltd + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: Alexey.Melnikov@isode.com + + + Curtis King + Isode Ltd + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: Curtis.King@isode.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Melnikov & King Standards Track [Page 9] + diff --git a/imap/docs/rfc/rfc5524.txt b/imap/docs/rfc/rfc5524.txt new file mode 100644 index 00000000..3808d1ff --- /dev/null +++ b/imap/docs/rfc/rfc5524.txt @@ -0,0 +1,507 @@ + + + + + + +Network Working Group D. Cridland +Request for Comments: 5524 Isode Limited +Category: Standards Track May 2009 + + + Extended URLFETCH for Binary and Converted Parts + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (c) 2009 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents in effect on the date of + publication of this document (http://trustee.ietf.org/license-info). + Please review these documents carefully, as they describe your rights + and restrictions with respect to this document. + +Abstract + + The URLFETCH command defined as part of URLAUTH provides a mechanism + for third parties to gain access to data held within messages in a + user's private store; however, this data is sent verbatim, which is + not suitable for a number of applications. This memo specifies a + method for obtaining data in forms suitable for non-mail + applications. + + + + + + + + + + + + + + + + + +Cridland Standards Track [Page 1] + +RFC 5524 URLFETCH Binary May 2009 + + +Table of Contents + + 1. Introduction ....................................................2 + 2. Conventions Used in This Document ...............................2 + 3. Extended URLFETCH ...............................................2 + 3.1. Command Parameters .........................................3 + 3.2. Response Metadata ..........................................3 + 4. Example Exchanges ...............................................4 + 5. Formal Syntax ...................................................6 + 6. IANA Considerations .............................................7 + 7. Security Considerations .........................................7 + 8. Acknowledgements ................................................7 + 9. References ......................................................8 + 9.1. Normative References .......................................8 + 9.2. Informative References .....................................8 + +1. Introduction + + Although [URLAUTH] provides a URLFETCH command that can be used to + dereference a URL and return the body-part data, it does so by + returning the encoded form, without sufficient metadata to decode. + This is suitable for use in mail applications such as [BURL], where + the encoded form is suitable, but not where access to the actual + content is required, such as in [STREAMING]. + + This memo specifies a mechanism that returns additional metadata + about the part, such as its [MEDIATYPE] type, as well as removes any + content transfer encoding that was used on the body part. + +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]. + + Protocol examples are line-wrapped for clarity. Protocol strings are + prefixed with C: and S: for client and server respectively, and + elided data is represented by [...]. Implementors should note these + notations are for editorial clarity only. + +3. Extended URLFETCH + + This extension is available in any IMAP server implementation that + includes URLAUTH=BINARY within its capability string. + + Such servers accept additional, per-URL parameters to the URLFETCH + command and will provide, upon request, specific data for each URL + dereferenced. + + + +Cridland Standards Track [Page 2] + +RFC 5524 URLFETCH Binary May 2009 + + +3.1. Command Parameters + + The URLFETCH command is extended by the provision of optional + parameters. The extended URLFETCH command is distinct by enclosing + each URL and associated parameters in a parenthesized list. Cases + where there is an absence of any parameters or where the URL is sent + unenclosed cause the command to behave precisely as specified in + [URLAUTH]. + + Similarly, if the URL is invalid, the command will behave precisely + as specified in [URLAUTH] and return a simple NIL. + + Available parameters are: + + BODYPARTSTRUCTURE + Provide a BODYPARTSTRUCTURE. + + BODYPARTSTRUCTURE is defined in [CONVERT] and provides metadata + useful for processing applications, such as the type of data. + + BINARY + Provide the data without any Content-Transfer-Encoding. + + In particular, this means that the data MAY contain NUL octets and + not be formed from textual lines. Data containing NUL octets MUST + be transferred using the literal8 syntax defined in [BINARY]. + + BODY + Provide the data as-is. + + This will provide the same data as the unextended [URLAUTH] as a + metadata item. + + Metadata items MUST NOT appear more than once per URL requested, and + clients MUST NOT request both BINARY and BODY. + +3.2. Response Metadata + + In order to carry any requested metadata and provide additional + information to the consumer, the URLFETCH response is similarly + extended. + + Following the URL itself, servers will include a series of + parenthesized metadata elements. Defined metadata elements are as + follows: + + + + + + +Cridland Standards Track [Page 3] + +RFC 5524 URLFETCH Binary May 2009 + + + BODYPARTSTRUCTURE + The BODYPARTSTRUCTURE provides information about the data + contained in the response, as it has been returned. It will + reflect any conversions or decoding that have taken place. In + particular, this will show an identity encoding if BINARY is also + requested. + + BINARY + The BINARY item provides the content, without any content transfer + encoding applied. If this is not possible (for example, the + content transfer encoding is unknown to the server), then this MAY + contain NIL. Servers MUST understand all identity content + transfer encodings defined in [MIME], as well as the + transformation encodings "Base64" [BASE64] and "Quoted-Printable" + [MIME]. + + BODY + The BODY item provides the content as found in the message, with + any content transfer encoding still applied. Requesting only the + BODY will provide equivalent functionality to the unextended + [URLAUTH], however, using the extended syntax described herein. + + Note that unlike [CONVERT], BODYPARTSTRUCTURE is not appended with + the part specifier, as this is implicit in the URL. + +4. Example Exchanges + + A client requests the data with no content transfer encoding. + + C: A001 URLFETCH ("imap://joe@example.com/INBOX/;uid=20/; + section=1.2;urlauth=anonymous:internal: + 91354a473744909de610943775f92038" BINARY) + S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/; + section=1.2;urlauth=anonymous:internal: + 91354a473744909de610943775f92038" (BINARY {28} + S: Si vis pacem, para bellum. + S: + S: ) + S: A001 OK URLFETCH completed + + Note that the data here does not contain a NUL octet; therefore, a + literal -- not literal8 -- syntax has been used. + + A client again requests data with no content transfer encoding, but + this time requests the body structure. + + + + + + +Cridland Standards Track [Page 4] + +RFC 5524 URLFETCH Binary May 2009 + + + C: A001 URLFETCH ("imap://joe@example.com/INBOX/;uid=20/; + section=1.3;urlauth=anonymous:internal: + ae354a473744909de610943775f92038" BINARY BODYPARTSTRUCTURE) + S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/; + section=1.3;urlauth=anonymous:internal: + ae354a473744909de610943775f92038" (BODYPARTSTRUCTURE + ("IMAGE" "PNG" () NIL NIL "BINARY" 123)) (BINARY ~{123} + S: [123 octets of data, some of which is NUL]) + S: A001 OK URLFETCH completed + + A client requests only the body structure. + + C: A001 URLFETCH ("imap://joe@example.com/INBOX/;uid=20/; + section=1.3;urlauth=anonymous:internal: + ae354a473744909de610943775f92038" BODYPARTSTRUCTURE) + S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/; + section=1.3;urlauth=anonymous:internal: + ae354a473744909de610943775f92038" (BODYPARTSTRUCTURE + ("IMAGE" "PNG" () NIL NIL "BASE64" 164)) + S: A001 OK URLFETCH completed + + A client requests the body structure and the original content. + + C: A001 URLFETCH ("imap://joe@example.com/INBOX/;uid=20/; + section=1.3;urlauth=anonymous:internal: + ae354a473744909de610943775f92038" BODYPARTSTRUCTURE BODY) + S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/; + section=1.3;urlauth=anonymous:internal: + ae354a473744909de610943775f92038" (BODYPARTSTRUCTURE + ("IMAGE" "PNG" () NIL NIL "BASE64" 164)) (BODY {164} + S: [164 octets of base64 encoded data]) + S: A001 OK URLFETCH completed + + Some parts cannot be decoded, so the server will provide the + BODYPARTSTRUCTURE of the part as is and provide NIL for the binary + content: + + C: A001 URLFETCH ("imap://joe@example.com/INBOX/;uid=20/; + section=1.4;urlauth=anonymous:internal: + 87ecbd02095b815e699503fc20d869c8" BODYPARTSTRUCTURE BINARY) + S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/; + section=1.4;urlauth=anonymous:internal: + 87ecbd02095b815e699503fc20d869c8" (BODYPARTSTRUCTURE + ("IMAGE" "PNG" () NIL NIL "X-BLURDYBLOOP" 123)) + (BINARY NIL) + S: A001 OK URLFETCH completed + + + + + +Cridland Standards Track [Page 5] + +RFC 5524 URLFETCH Binary May 2009 + + + If a part simply doesn't exist, however, or the URI is invalid for + some other reason, then NIL is returned instead of metadata: + + C: A001 URLFETCH ("imap://joe@example.com/INBOX/;uid=20/; + section=200;urlauth=anonymous:internal: + 88066d37e2e5410e1a6486350a8836ee" BODYPARTSTRUCTURE BODY) + S: * URLFETCH "imap://joe@example.com/INBOX/;uid=20/; + section=200;urlauth=anonymous:internal: + 88066d37e2e5410e1a6486350a8836ee" NIL + S: A001 OK URLFETCH completed + +5. Formal Syntax + + This formal syntax uses ABNF as specified in [ABNF], and includes + productions defined in [URLAUTH], [BINARY], and [IMAP]. + + capability =/ "URLAUTH=BINARY" + + ; Command parameters; see Section 3.1 + + urlfetch = "URLFETCH" 1*(SP url-fetch-arg) + + url-fetch-arg = url-fetch-simple / url-fetch-ext + + url-fetch-simple = url-full + ; Unextended URLFETCH. + + url-fetch-ext = "(" url-full *(SP url-fetch-param) ")" + ; If no url-fetch-param present, as unextended. + + url-fetch-param = "BODY" / "BINARY" / "BODYPARTSTRUCTURE" / atom + + ; Response; see Section 3.2 + + urlfetch-data = "*" SP "URLFETCH" + 1*(SP (urldata-simple / urldata-ext / + urldata-error)) + + urldata-error = SP url-full SP nil + + urldata-simple = SP url-full SP nstring + ; If client issues url-fetch-simple, server MUST respond with + ; urldata-simple. + + urldata-ext = SP url-full url-metadata + + url-metadata = 1*(SP "(" url-metadata-el ")") + + + + +Cridland Standards Track [Page 6] + +RFC 5524 URLFETCH Binary May 2009 + + + url-metadata-el = url-meta-bodystruct / url-meta-body / + url-meta-binary + + url-meta-bodystruct = "BODYPARTSTRUCTURE" SP body + + url-meta-binary = "BINARY" SP ( nstring / literal8 ) + ; If content contains a NUL octet, literal8 MUST be used. + ; Otherwise, content SHOULD use nstring. + ; On decoding error, NIL should be used. + + url-meta-body = "BODY" SP nstring + +6. IANA Considerations + + IMAP4 capabilities are registered by publishing a Standards Track or + IESG-approved Experimental RFC. + + This document defines the URLFETCH=BINARY IMAP capability. IANA has + added it to the registry accordingly. + +7. Security Considerations + + Implementors are directed to the security considerations within + [IMAP], [URLAUTH], and [BINARY]. + + The ability of the holder of a URL to be able to fetch metadata about + the content pointed to by the URL as well as the content itself + allows a potential attacker to discover more about the content than + was previously possible, including its original filename and user- + supplied description. + + The additional value of this information to an attacker is marginal, + and applies only to those URLs for which the attacker does not have + direct access, such as those produced by [URLAUTH]. Implementors are + therefore directed to the security considerations present in + [URLAUTH]. + +8. Acknowledgements + + Comments were received on this idea and/or document from Neil Cook, + Philip Guenther, Alexey Melnikov, Ken Murchison, and others. Whether + in agreement or dissent, the comments have refined and otherwise + influenced this document. + + + + + + + + +Cridland Standards Track [Page 7] + +RFC 5524 URLFETCH Binary May 2009 + + +9. References + +9.1. Normative References + + [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + + [BASE64] Josefsson, S., "The Base16, Base32, and Base64 Data + Encodings", RFC 4648, October 2006. + + [BINARY] Nerenberg, L., "IMAP4 Binary Content Extension", + RFC 3516, April 2003. + + [CONVERT] Melnikov, A. and P. Coates, "Internet Message Access + Protocol - CONVERT Extension", RFC 5259, July 2008. + + [IMAP] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail + Extensions (MIME) Part One: Format of Internet Message + Bodies", RFC 2045, November 1996. + + [URLAUTH] Crispin, M., "Internet Message Access Protocol (IMAP) - + URLAUTH Extension", RFC 4467, May 2006. + +9.2. Informative References + + [BURL] Newman, C., "Message Submission BURL Extension", + RFC 4468, May 2006. + + [MEDIATYPE] Freed, N. and N. Borenstein, "Multipurpose Internet Mail + Extensions (MIME) Part Two: Media Types", RFC 2046, + November 1996. + + [STREAMING] Cook, N., "Streaming Internet Messaging Attachments", + Work in Progress, March 2009. + + + + + + + + + + + +Cridland Standards Track [Page 8] + +RFC 5524 URLFETCH Binary May 2009 + + +Author's Address + + Dave Cridland + Isode Limited + 5 Castle Business Village + 36, Station Road + Hampton, Middlesex TW12 2BX + GB + + EMail: dave.cridland@isode.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Cridland Standards Track [Page 9] + diff --git a/imap/docs/rfc/rfc5530.txt b/imap/docs/rfc/rfc5530.txt new file mode 100644 index 00000000..946fbb5f --- /dev/null +++ b/imap/docs/rfc/rfc5530.txt @@ -0,0 +1,507 @@ + + + + + + +Network Working Group A. Gulbrandsen +Request for Comments: 5530 Oryx Mail Systems GmbH +Category: Standards Track May 2009 + + + IMAP Response Codes + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (c) 2009 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents in effect on the date of + publication of this document (http://trustee.ietf.org/license-info). + Please review these documents carefully, as they describe your rights + and restrictions with respect to this document. + +Abstract + + IMAP responses consist of a response type (OK, NO, BAD), an optional + machine-readable response code, and a human-readable text. + + This document collects and documents a variety of machine-readable + response codes, for better interoperation and error reporting. + + + + + + + + + + + + + + + + + + +Gulbrandsen Standards Track [Page 1] + +RFC 5530 IMAP Response Codes May 2009 + + +1. Introduction + + Section 7.1 of [RFC3501] defines a number of response codes that can + help tell an IMAP client why a command failed. However, experience + has shown that more codes are useful. For example, it is useful for + a client to know that an authentication attempt failed because of a + server problem as opposed to a password problem. + + Currently, many IMAP servers use English-language, human-readable + text to describe these errors, and a few IMAP clients attempt to + translate this text into the user's language. + + This document names a variety of errors as response codes. It is + based on errors that have been checked and reported on in some IMAP + server implementations, and on the needs of some IMAP clients. + + This document doesn't require any servers to test for these errors or + any clients to test for these names. It only names errors for better + reporting and handling. + +2. Conventions Used in This Document + + Formal syntax is defined by [RFC5234] as modified by [RFC3501]. + + Example lines prefaced by "C:" are sent by the client and ones + prefaced by "S:" by the server. "[...]" means elision. + +3. Response Codes + + This section defines all the new response codes. Each definition is + followed by one or more examples. + + UNAVAILABLE + Temporary failure because a subsystem is down. For example, an + IMAP server that uses a Lightweight Directory Access Protocol + (LDAP) or Radius server for authentication might use this + response code when the LDAP/Radius server is down. + + C: a LOGIN "fred" "foo" + S: a NO [UNAVAILABLE] User's backend down for maintenance + + AUTHENTICATIONFAILED + Authentication failed for some reason on which the server is + unwilling to elaborate. Typically, this includes "unknown + user" and "bad password". + + + + + + +Gulbrandsen Standards Track [Page 2] + +RFC 5530 IMAP Response Codes May 2009 + + + This is the same as not sending any response code, except that + when a client sees AUTHENTICATIONFAILED, it knows that the + problem wasn't, e.g., UNAVAILABLE, so there's no point in + trying the same login/password again later. + + C: b LOGIN "fred" "foo" + S: b NO [AUTHENTICATIONFAILED] Authentication failed + + AUTHORIZATIONFAILED + Authentication succeeded in using the authentication identity, + but the server cannot or will not allow the authentication + identity to act as the requested authorization identity. This + is only applicable when the authentication and authorization + identities are different. + + C: c1 AUTHENTICATE PLAIN + [...] + S: c1 NO [AUTHORIZATIONFAILED] No such authorization-ID + + C: c2 AUTHENTICATE PLAIN + [...] + S: c2 NO [AUTHORIZATIONFAILED] Authenticator is not an admin + + + EXPIRED + Either authentication succeeded or the server no longer had the + necessary data; either way, access is no longer permitted using + that passphrase. The client or user should get a new + passphrase. + + C: d login "fred" "foo" + S: d NO [EXPIRED] That password isn't valid any more + + PRIVACYREQUIRED + The operation is not permitted due to a lack of privacy. If + Transport Layer Security (TLS) is not in use, the client could + try STARTTLS (see Section 6.2.1 of [RFC3501]) and then repeat + the operation. + + C: d login "fred" "foo" + S: d NO [PRIVACYREQUIRED] Connection offers no privacy + + C: d select inbox + S: d NO [PRIVACYREQUIRED] Connection offers no privacy + + + + + + + +Gulbrandsen Standards Track [Page 3] + +RFC 5530 IMAP Response Codes May 2009 + + + CONTACTADMIN + The user should contact the system administrator or support + desk. + + C: e login "fred" "foo" + S: e OK [CONTACTADMIN] + + NOPERM + The access control system (e.g., Access Control List (ACL), see + [RFC4314]) does not permit this user to carry out an operation, + such as selecting or creating a mailbox. + + C: f select "/archive/projects/experiment-iv" + S: f NO [NOPERM] Access denied + + INUSE + An operation has not been carried out because it involves + sawing off a branch someone else is sitting on. Someone else + may be holding an exclusive lock needed for this operation, or + the operation may involve deleting a resource someone else is + using, typically a mailbox. + + The operation may succeed if the client tries again later. + + C: g delete "/archive/projects/experiment-iv" + S: g NO [INUSE] Mailbox in use + + EXPUNGEISSUED + Someone else has issued an EXPUNGE for the same mailbox. The + client may want to issue NOOP soon. [RFC2180] discusses this + subject in depth. + + C: h search from fred@example.com + S: * SEARCH 1 2 3 5 8 13 21 42 + S: h OK [EXPUNGEISSUED] Search completed + + CORRUPTION + The server discovered that some relevant data (e.g., the + mailbox) are corrupt. This response code does not include any + information about what's corrupt, but the server can write that + to its logfiles. + + C: i select "/archive/projects/experiment-iv" + S: i NO [CORRUPTION] Cannot open mailbox + + + + + + + +Gulbrandsen Standards Track [Page 4] + +RFC 5530 IMAP Response Codes May 2009 + + + SERVERBUG + The server encountered a bug in itself or violated one of its + own invariants. + + C: j select "/archive/projects/experiment-iv" + S: j NO [SERVERBUG] This should not happen + + CLIENTBUG + The server has detected a client bug. This can accompany all + of OK, NO, and BAD, depending on what the client bug is. + + C: k1 select "/archive/projects/experiment-iv" + [...] + S: k1 OK [READ-ONLY] Done + C: k2 status "/archive/projects/experiment-iv" (messages) + [...] + S: k2 OK [CLIENTBUG] Done + + CANNOT + The operation violates some invariant of the server and can + never succeed. + + C: l create "///////" + S: l NO [CANNOT] Adjacent slashes are not supported + + LIMIT + The operation ran up against an implementation limit of some + kind, such as the number of flags on a single message or the + number of flags used in a mailbox. + + C: m STORE 42 FLAGS f1 f2 f3 f4 f5 ... f250 + S: m NO [LIMIT] At most 32 flags in one mailbox supported + + OVERQUOTA + The user would be over quota after the operation. (The user + may or may not be over quota already.) + + Note that if the server sends OVERQUOTA but doesn't support the + IMAP QUOTA extension defined by [RFC2087], then there is a + quota, but the client cannot find out what the quota is. + + C: n1 uid copy 1:* oldmail + S: n1 NO [OVERQUOTA] Sorry + + C: n2 uid copy 1:* oldmail + S: n2 OK [OVERQUOTA] You are now over your soft quota + + + + + +Gulbrandsen Standards Track [Page 5] + +RFC 5530 IMAP Response Codes May 2009 + + + ALREADYEXISTS + The operation attempts to create something that already exists, + such as when the CREATE or RENAME directories attempt to create + a mailbox and there is already one of that name. + + C: o RENAME this that + S: o NO [ALREADYEXISTS] Mailbox "that" already exists + + NONEXISTENT + The operation attempts to delete something that does not exist. + Similar to ALREADYEXISTS. + + C: p RENAME this that + S: p NO [NONEXISTENT] No such mailbox + +4. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [RFC5234]. [RFC3501] defines + the non-terminal "resp-text-code". + + Except as noted otherwise, all alphabetic characters are case- + insensitive. The use of upper or lowercase characters to define + token strings is for editorial clarity only. + + resp-text-code =/ "UNAVAILABLE" / "AUTHENTICATIONFAILED" / + "AUTHORIZATIONFAILED" / "EXPIRED" / + "PRIVACYREQUIRED" / "CONTACTADMIN" / "NOPERM" / + "INUSE" / "EXPUNGEISSUED" / "CORRUPTION" / + "SERVERBUG" / "CLIENTBUG" / "CANNOT" / + "LIMIT" / "OVERQUOTA" / "ALREADYEXISTS" / + "NONEXISTENT" + +5. Security Considerations + + Revealing information about a passphrase to unauthenticated IMAP + clients causes bad karma. + + Response codes are easier to parse than human-readable text. This + can amplify the consequences of an information leak. For example, + selecting a mailbox can fail because the mailbox doesn't exist, + because the user doesn't have the "l" right (right to know the + mailbox exists) or "r" right (right to read the mailbox). If the + server sent different responses in the first two cases in the past, + only malevolent clients would discover it. With response codes it's + possible, perhaps probable, that benevolent clients will forward the + + + + + +Gulbrandsen Standards Track [Page 6] + +RFC 5530 IMAP Response Codes May 2009 + + + leaked information to the user. Server authors are encouraged to be + particularly careful with the NOPERM and authentication-related + responses. + +6. IANA Considerations + + The IANA has created the IMAP Response Codes registry. The registry + has been populated with the following codes: + + NEWNAME RFC 2060 (obsolete) + REFERRAL RFC 2221 + ALERT RFC 3501 + BADCHARSET RFC 3501 + PARSE RFC 3501 + PERMANENTFLAGS RFC 3501 + READ-ONLY RFC 3501 + READ-WRITE RFC 3501 + TRYCREATE RFC 3501 + UIDNEXT RFC 3501 + UIDVALIDITY RFC 3501 + UNSEEN RFC 3501 + UNKNOWN-CTE RFC 3516 + UIDNOTSTICKY RFC 4315 + APPENDUID RFC 4315 + COPYUID RFC 4315 + URLMECH RFC 4467 + TOOBIG RFC 4469 + BADURL RFC 4469 + HIGHESTMODSEQ RFC 4551 + NOMODSEQ RFC 4551 + MODIFIED RFC 4551 + COMPRESSIONACTIVE RFC 4978 + CLOSED RFC 5162 + NOTSAVED RFC 5182 + BADCOMPARATOR RFC 5255 + ANNOTATE RFC 5257 + ANNOTATIONS RFC 5257 + TEMPFAIL RFC 5259 + MAXCONVERTMESSAGES RFC 5259 + MAXCONVERTPARTS RFC 5259 + NOUPDATE RFC 5267 + METADATA RFC 5464 + NOTIFICATIONOVERFLOW RFC 5465 + BADEVENT RFC 5465 + UNDEFINED-FILTER RFC 5466 + UNAVAILABLE RFC 5530 + AUTHENTICATIONFAILED RFC 5530 + AUTHORIZATIONFAILED RFC 5530 + + + +Gulbrandsen Standards Track [Page 7] + +RFC 5530 IMAP Response Codes May 2009 + + + EXPIRED RFC 5530 + PRIVACYREQUIRED RFC 5530 + CONTACTADMIN RFC 5530 + NOPERM RFC 5530 + INUSE RFC 5530 + EXPUNGEISSUED RFC 5530 + CORRUPTION RFC 5530 + SERVERBUG RFC 5530 + CLIENTBUG RFC 5530 + CANNOT RFC 5530 + LIMIT RFC 5530 + OVERQUOTA RFC 5530 + ALREADYEXISTS RFC 5530 + NONEXISTENT RFC 5530 + + The new registry can be extended by sending a registration request to + IANA. IANA will forward this request to a Designated Expert, + appointed by the responsible IESG Area Director, CCing it to the IMAP + Extensions mailing list at <ietf-imapext@imc.org> (or a successor + designated by the Area Director). After either allowing 30 days for + community input on the IMAP Extensions mailing list or a successful + IETF Last Call, the expert will determine the appropriateness of the + registration request and either approve or disapprove the request by + sending a notice of the decision to the requestor, CCing the IMAP + Extensions mailing list and IANA. A denial notice must be justified + by an explanation, and, in cases where it is possible, concrete + suggestions on how the request can be modified so as to become + acceptable should be provided. + + For each response code, the registry contains a list of relevant RFCs + that describe (or extend) the response code and an optional response + code status description, such as "obsolete" or "reserved to prevent + collision with deployed software". (Note that in the latter case, + the RFC number can be missing.) Presence of the response code status + description means that the corresponding response code is NOT + RECOMMENDED for widespread use. + + The intention is that any future allocation will be accompanied by a + published RFC (including direct submissions to the RFC Editor). But + in order to allow for the allocation of values prior to the RFC being + approved for publication, the Designated Expert can approve + allocations once it seems clear that an RFC will be published, for + example, before requesting IETF LC for the document. + + The Designated Expert can also approve registrations for response + codes used in deployed software when no RFC exists. Such + registrations must be marked as "reserved to prevent collision with + deployed software". + + + +Gulbrandsen Standards Track [Page 8] + +RFC 5530 IMAP Response Codes May 2009 + + + Response code registrations may not be deleted; response codes that + are no longer believed appropriate for use (for example, if there is + a problem with the syntax of said response code or if the + specification describing it was moved to Historic) should be marked + "obsolete" in the registry, clearly marking the lists published by + IANA. + +7. Acknowledgements + + Peter Coates, Mark Crispin, Philip Guenther, Alexey Melnikov, Ken + Murchison, Chris Newman, Timo Sirainen, Philip Van Hoof, Dale + Wiggins, and Sarah Wilkin helped with this document. + +8. References + +8.1. Normative References + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", STD 68, RFC 5234, January + 2008. + +9. Informative References + + [RFC2087] Myers, J., "IMAP4 QUOTA extension", RFC 2087, January + 1997. + + [RFC2180] Gahrns, M., "IMAP4 Multi-Accessed Mailbox Practice", RFC + 2180, July 1997. + + [RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) Extension", + RFC 4314, December 2005. + +Author's Address + + Arnt Gulbrandsen + Oryx Mail Systems GmbH + Schweppermannstr. 8 + D-81671 Muenchen + Germany + + Fax: +49 89 4502 9758 + EMail: arnt@oryx.com + + + + + + +Gulbrandsen Standards Track [Page 9] + diff --git a/imap/docs/rfc/rfc5593.txt b/imap/docs/rfc/rfc5593.txt new file mode 100644 index 00000000..20158d4e --- /dev/null +++ b/imap/docs/rfc/rfc5593.txt @@ -0,0 +1,563 @@ + + + + + + +Network Working Group N. Cook +Request for Comments: 5593 Cloudmark +Updates: 5092 June 2009 +Category: Standards Track + + + Internet Message Access Protocol (IMAP) - + URL Access Identifier Extension + +Status of This Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (c) 2009 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents in effect on the date of + publication of this document (http://trustee.ietf.org/license-info). + Please review these documents carefully, as they describe your rights + and restrictions with respect to this document. + +Abstract + + The existing IMAP URL specification (RFC 5092) lists several <access> + identifiers and <access> identifier prefixes that can be used to + restrict access to URLAUTH-generated URLs. However, these + identifiers do not provide facilities for new services such as + streaming. This document proposes a set of new <access> identifiers + as well as an IANA mechanism to register new <access> identifiers for + future applications. + + This document updates RFC 5092. + + + + + + + + + + + + +Cook Standards Track [Page 1] + +RFC 5593 IMAP URL Access Identifier June 2009 + + +Table of Contents + + 1. Introduction ....................................................2 + 2. Conventions Used in This Document ...............................2 + 3. Additional Authorized Access Identifiers ........................3 + 3.1. Existing Access Identifiers ................................3 + 3.2. Requirement for Additional Access Identifiers ..............3 + 3.3. Additional Access Identifier Specification .................4 + 3.4. Defining an Access Identifier for Streaming ................5 + 4. Formal Syntax ...................................................5 + 5. Acknowledgements ................................................6 + 6. IANA Considerations .............................................6 + 6.1. Access Identifier Registration Template ....................7 + 6.2. Stream Application Registration ............................7 + 6.3. Submit Application Registration ............................8 + 6.4. User Application Registration ..............................8 + 6.5. Authuser Application Registration ..........................9 + 6.6. Anonymous Application Registration .........................9 + 7. Security Considerations .........................................9 + 8. References .....................................................10 + 8.1. Normative References ......................................10 + 8.2. Informative References ....................................10 + +1. Introduction + + The IMAP URL specification [RFC5092] provides a way to carry + authorization information in IMAP URLs. Several authorization + <access> identifiers are specified in the document that allow + URLAUTH-authorized URLs to be used only by anonymous users, + authenticated users, or message submission entities. However, there + is no mechanism defined to create new <access> identifiers, and + overloading the existing mechanisms has security as well as + administrative implications. + + This document describes a new <access> identifier, "stream", to be + used by message streaming entities (as described in [STREAMING]), and + defines an IANA registration template, which can be used to register + new <access> identifiers for future applications. IANA definitions + for the existing access identifiers and prefixes from RFC 5092 are + also defined in this document -- this document updates RFC 5092 and + should be taken as the master in the event of any differences or + discrepancies. + +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 [RFC2119]. + + + +Cook Standards Track [Page 2] + +RFC 5593 IMAP URL Access Identifier June 2009 + + + 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 some of the line breaks between those lines are + for editorial clarity only and may not be part of the actual protocol + exchange. + +3. Additional Authorized Access Identifiers + +3.1. Existing Access Identifiers + + The IMAP URL specification [RFC5092] specifies the following + authorized <access> identifiers: + + o "authuser" - Indicates that use of this URL is limited to + authenticated IMAP sessions that are logged in as any non- + anonymous user. + + o "anonymous" - Indicates that use of this URL is not restricted by + session authorization identity. + + Additionally, the following <access> identifier prefixes are defined + in [RFC5092]: + + o "submit+" - 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. + + o "user+" - Followed by a userid, indicates that use of this URL is + limited to IMAP sessions that are logged in as the specified + userid. + +3.2. Requirement for Additional Access Identifiers + + The existing <access> identifiers are suitable for user-based + authorization, but only the "submit+" <access> identifier prefix is + suitable for entities acting on behalf of a user. Generic support + for external entities acting on behalf of users is required for new + services such as streaming [STREAMING]. + + The "submit+" <access> identifier prefix is not suitable for use as a + general mechanism to grant access to entities acting on behalf of + users, for reasons that include: + + o Security - The IMAP server maintains a list of submission server + entities that are entitled to retrieve IMAP URLs specifying the + "submit+" <access> identifier prefix. If this list is extended to + include the set of all external entities that could act on behalf + of users, then the attack surface would be increased. + + + +Cook Standards Track [Page 3] + +RFC 5593 IMAP URL Access Identifier June 2009 + + + o Administration - When URLAUTH-style IMAP URLs are presented to an + IMAP server by entities acting on behalf of users, the server + administrator has no way of determining the intended use of that + URL from the server logs. + + o Resourcing - Without a mechanism to distinguish between the + application for which an IMAP URL is to be used, the IMAP server + has no way to prioritize resources for particular applications. + For example, the server could prioritize "submit+" URL fetch + requests over other access identifiers. + +3.3. Additional Access Identifier Specification + + The previous section establishes that additional access identifiers + are required to support applications, such as streaming [STREAMING], + that require entities to retrieve URLAUTH URLs on behalf of users. + This section describes the scope and meaning of any additional + <access> identifiers that are created. + + Additional <access> identifiers MUST take one of two forms (Section 4 + gives the formal ABNF syntax): + + o <access> identifier - The name of the application, e.g., + "exampleapp". + + o <access> identifier prefix - The name of the application, e.g., + "exampleapp3", followed by a "+" and then a userid. For example, + consider "exampleapp3+testuser". + + Note that an <access> identifier name can also be registered as an + <access> identifier prefix. However, this would require 2 separate + IANA registrations. + + In both cases, the semantics are the same as those for "submit+", + i.e., the <access> identifier or <access> identifier prefix (which + MUST be followed by a userid) indicates that only a userid authorized + as an application entity for the specified application is permitted + to use this URL. In the case of <access> identifier prefixes, the + IMAP server SHALL NOT validate the specified userid but MUST validate + that the IMAP session has an authorization identity that is + authorized as an application entity for the specified application. + + + + + + + + + + +Cook Standards Track [Page 4] + +RFC 5593 IMAP URL Access Identifier June 2009 + + + The application entity itself MAY choose to perform validation on any + specified userid before attempting to retrieve the URL. + + The authorization granted by any <access> identifiers used as + described above is self-describing, and so requires that the IMAP + server provide an extensible mechanism for associating userids with + new applications. For example, imagine a new application, "foo", is + created that requires application entities to retrieve URLs on behalf + of users. In this case, the IMAP server would need to provide a way + to register the new application "foo" and to associate the set of + userids to be used by those entities with the application "foo". Any + attempt to retrieve URLs containing the <access> identifier "foo" + would be checked for authorization against the list of userids + associated with the application "foo". + + Section 6 provides the template required to register new <access> + identifiers or prefixes with IANA. + +3.4. Defining an Access Identifier for Streaming + + One application that makes use of URLAUTH-authorized URLs is that of + streaming multimedia files that are received as internet-messaging + attachments. This application is described in [STREAMING]. + + See Section 6.2 for the IANA registration template for the "stream" + <access> identifier. + +4. Formal Syntax + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [RFC5234]. + + 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. + + The ABNF specified below updates the formal syntax of <access> + identifiers as defined in IMAP URL [RFC5092]. + + Copyright (c) 2009 IETF Trust and the persons identified as + authors of the code. All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + + + + +Cook Standards Track [Page 5] + +RFC 5593 IMAP URL Access Identifier June 2009 + + + - Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + - Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. + + - Neither the name of Internet Society, IETF or IETF Trust, nor the + names of specific contributors, may be used to endorse or promote + products derived from this software without specific prior + written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + application = 1*(ALPHA/DIGIT) + + access =/ application / (application "+" enc-user) + +5. Acknowledgements + + This document was inspired by discussions in the Lemonade Working + Group. + +6. IANA Considerations + + IANA created a new registry for IMAP URLAUTH access identifiers and + prefixes. + + Access identifiers and prefixes MUST be registered using the "IETF + Review" policy [RFC5226]. This section gives the IANA registration + entries for the existing access identifiers and prefixes from RFC + 5092 as well as the entry for the "stream" application. + + + + + + + + + +Cook Standards Track [Page 6] + +RFC 5593 IMAP URL Access Identifier June 2009 + + +6.1. Access Identifier Registration Template + + To: iana@iana.org + Subject: IMAP URL Access Identifier Registration + + Type: [Either "<access> identifier" or + "<access> identifier prefix"] + + Application: [Name of the application, e.g., "stream"] + + Description: [A description of the application and its use + of IMAP URLs] + + RFC Number: [Number of the RFC in which the application is + defined] + + Contact: [Email and/or physical address to contact for + additional information] + +6.2. Stream Application Registration + + To: iana@iana.org + Subject: IMAP URL Access Identifier Registration + + Type: <access> identifier + + Application: stream + + Description: Used by SIP Media Servers to retrieve + attachments for streaming to email + clients + + RFC Number: RFC 5593 + + Contact: Neil Cook <neil.cook@noware.co.uk> + + + + + + + + + + + + + + + + +Cook Standards Track [Page 7] + +RFC 5593 IMAP URL Access Identifier June 2009 + + +6.3. Submit Application Registration + + To: iana@iana.org + Subject: IMAP URL Access Identifier Registration + + Type: <access> identifier prefix + + Application: submit + + Description: Used by message submission entities to + retrieve attachments to be included in + submitted messages + + RFC Number: RFC 5593 and RFC 5092 + + Contact: Lemonade WG <lemonade@ietf.org> + +6.4. User Application Registration + + To: iana@iana.org + Subject: IMAP URL Access Identifier Registration + + Type: <access> identifier prefix + + Application: user + + Description: Used to restrict access to IMAP sessions + that are logged in as the specified userid + + RFC Number: RFC 5593 and RFC 5092 + + Contact: Lemonade WG <lemonade@ietf.org> + + + + + + + + + + + + + + + + + + + +Cook Standards Track [Page 8] + +RFC 5593 IMAP URL Access Identifier June 2009 + + +6.5. Authuser Application Registration + + To: iana@iana.org + Subject: IMAP URL Access Identifier Registration + + Type: <access> identifier + + Application: authuser + + Description: Used to restrict access to IMAP sessions + that are logged in as any non-anonymous + user of that IMAP server + + RFC Number: RFC 5593 and RFC 5092 + + Contact: Lemonade WG <lemonade@ietf.org> + +6.6. Anonymous Application Registration + + To: iana@iana.org + Subject: IMAP URL Access Identifier Registration + + Type: <access> identifier + + Application: anonymous + + Description: Indicates that use of this URL is + not restricted by session authorization + identity + + RFC Number: RFC 5593 and RFC 5092 + + Contact: Lemonade WG <lemonade@ietf.org> + +7. Security Considerations + + The extension to <access> identifiers specified in this document + provides a mechanism for extending the semantics of the "submit+" + <access> prefix to arbitrary applications. The use of such + additional <access> identifiers and prefixes is primarily for + security purposes, i.e., to prevent the overloading of "submit+" as a + generic mechanism to allow entities to retrieve IMAP URLs on behalf + of userids. Other than this, the security implications are identical + to those discussed in Section 10.1 of IMAPURL [RFC5092]. + + + + + + + +Cook Standards Track [Page 9] + +RFC 5593 IMAP URL Access Identifier June 2009 + + +8. References + +8.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC5092] Melnikov, A., Ed., and C. Newman, "IMAP URL Scheme", RFC + 5092, November 2007. + + [RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", STD 68, RFC 5234, January + 2008. + +8.2. Informative References + + [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an + IANA Considerations Section in RFCs", BCP 26, RFC 5226, + May 2008. + + [STREAMING] Cook, N., "Streaming Internet Messaging Attachments", + Work in Progress, May 2009. + +Author's Address + + Neil L Cook + Cloudmark + + EMail: neil.cook@noware.co.uk + + + + + + + + + + + + + + + + + + + + + + +Cook Standards Track [Page 10] + diff --git a/imap/docs/rfc/rfc5738.txt b/imap/docs/rfc/rfc5738.txt new file mode 100644 index 00000000..2b5daaa2 --- /dev/null +++ b/imap/docs/rfc/rfc5738.txt @@ -0,0 +1,843 @@ + + + + + + +Network Working Group P. Resnick +Request for Comments: 5738 Qualcomm Incorporated +Updates: 3501 C. Newman +Category: Experimental Sun Microsystems + March 2010 + + + IMAP Support for UTF-8 + +Abstract + + This specification extends the Internet Message Access Protocol + version 4rev1 (IMAP4rev1) to support UTF-8 encoded international + characters in user names, mail addresses, and message headers. + +Status of This Memo + + This document is not an Internet Standards Track specification; it is + published for examination, experimental implementation, and + evaluation. + + This document defines an Experimental Protocol for the Internet + community. This document is a product of the Internet Engineering + Task Force (IETF). It represents the consensus of the IETF + community. It has received public review and has been approved for + publication by the Internet Engineering Steering Group (IESG). Not + all documents approved by the IESG are a candidate for any level of + Internet Standard; see Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc5738. + +Copyright Notice + + Copyright (c) 2010 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + + +Resnick & Newman Experimental [Page 1] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + + This document may contain material from IETF Documents or IETF + Contributions published or made publicly available before November + 10, 2008. The person(s) controlling the copyright in some of this + material may not have granted the IETF Trust the right to allow + modifications of such material outside the IETF Standards Process. + Without obtaining an adequate license from the person(s) controlling + the copyright in such materials, this document may not be modified + outside the IETF Standards Process, and derivative works of it may + not be created outside the IETF Standards Process, except to format + it for publication as an RFC or to translate it into languages other + than English. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 + 3. UTF8=ACCEPT IMAP Capability . . . . . . . . . . . . . . . . . 3 + 3.1. IMAP UTF-8 Quoted Strings . . . . . . . . . . . . . . . . 3 + 3.2. UTF8 Parameter to SELECT and EXAMINE . . . . . . . . . . . 5 + 3.3. UTF-8 LIST and LSUB Responses . . . . . . . . . . . . . . 5 + 3.4. UTF-8 Interaction with IMAP4 LIST Command Extensions . . . 6 + 3.4.1. UTF8 and UTF8ONLY LIST Selection Options . . . . . . . 6 + 3.4.2. UTF8 LIST Return Option . . . . . . . . . . . . . . . 6 + 4. UTF8=APPEND Capability . . . . . . . . . . . . . . . . . . . . 7 + 5. UTF8=USER Capability . . . . . . . . . . . . . . . . . . . . . 7 + 6. UTF8=ALL Capability . . . . . . . . . . . . . . . . . . . . . 7 + 7. UTF8=ONLY Capability . . . . . . . . . . . . . . . . . . . . . 8 + 8. Up-Conversion Server Requirements . . . . . . . . . . . . . . 8 + 9. Issues with UTF-8 Header Mailstore . . . . . . . . . . . . . . 9 + 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 + 11. Security Considerations . . . . . . . . . . . . . . . . . . . 11 + 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 12.1. Normative References . . . . . . . . . . . . . . . . . . . 11 + 12.2. Informative References . . . . . . . . . . . . . . . . . . 13 + Appendix A. Design Rationale . . . . . . . . . . . . . . . . . . 14 + Appendix B. Examples Demonstrating Relationships between + UTF8= Capabilities . . . . . . . . . . . . . . . . . 15 + Appendix C. Acknowledgments . . . . . . . . . . . . . . . . . . . 15 + + + + + + + + + + + + + +Resnick & Newman Experimental [Page 2] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + +1. Introduction + + This specification extends IMAP4rev1 [RFC3501] to permit UTF-8 + [RFC3629] in headers as described in "Internationalized Email + Headers" [RFC5335]. It also adds a mechanism to support mailbox + names, login names, and passwords using the UTF-8 charset. This + specification creates five new IMAP capabilities to allow servers to + advertise these new extensions, along with two new IMAP LIST + selection options and a new IMAP LIST return option. + +2. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" + in this document are to be interpreted as defined in "Key words for + use in RFCs to Indicate Requirement Levels" [RFC2119]. + + The formal syntax uses the Augmented Backus-Naur Form (ABNF) + [RFC5234] notation including the core rules defined in Appendix B of + [RFC5234]. In addition, rules from IMAP4rev1 [RFC3501], UTF-8 + [RFC3629], "Collected Extensions to IMAP4 ABNF" [RFC4466], and IMAP4 + LIST Command Extensions [RFC5258] are also referenced. + + In examples, "C:" and "S:" indicate lines sent by the client and + server, respectively. If a single "C:" or "S:" label applies to + multiple lines, then the line breaks between those lines are for + editorial clarity only and are not part of the actual protocol + exchange. + +3. UTF8=ACCEPT IMAP Capability + + The "UTF8=ACCEPT" capability indicates that the server supports UTF-8 + quoted strings, the "UTF8" parameter to SELECT and EXAMINE, and UTF-8 + responses from the LIST and LSUB commands. + + A client MUST use the "ENABLE UTF8=ACCEPT" command (defined in + [RFC5161]) to indicate to the server that the client accepts UTF-8 + quoted-strings. The "ENABLE UTF8=ACCEPT" command MUST only be used + in the authenticated state. (Note that the "UTF8=ONLY" capability + described in Section 7 and the "UTF8=ALL" capability described in + Section 6 imply the "UTF8=ACCEPT" capability. See additional + information in these sections.) + +3.1. IMAP UTF-8 Quoted Strings + + The IMAP4rev1 [RFC3501] base specification forbids the use of 8-bit + characters in atoms or quoted strings. Thus, a UTF-8 string can only + be sent as a literal. This can be inconvenient from a coding + standpoint, and unless the server offers IMAP4 non-synchronizing + + + +Resnick & Newman Experimental [Page 3] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + + literals [RFC2088], this requires an extra round trip for each UTF-8 + string sent by the client. When the IMAP server advertises the + "UTF8=ACCEPT" capability, it informs the client that it supports + native UTF-8 quoted-strings with the following syntax: + + string =/ utf8-quoted + + utf8-quoted = "*" DQUOTE *UQUOTED-CHAR DQUOTE + + UQUOTED-CHAR = QUOTED-CHAR / UTF8-2 / UTF8-3 / UTF8-4 + ; UTF8-2, UTF8-3, and UTF8-4 are as defined in RFC 3629 + + When this quoting mechanism is used by the client (specifically an + octet sequence beginning with *" and ending with "), then the server + MUST reject octet sequences with the high bit set that fail to comply + with the formal syntax in [RFC3629] with a BAD response. + + The IMAP server MUST NOT send utf8-quoted syntax to the client unless + the client has indicated support for that syntax by using the "ENABLE + UTF8=ACCEPT" command. + + If the server advertises the "UTF8=ACCEPT" capability, the client MAY + use utf8-quoted syntax with any IMAP argument that permits a string + (including astring and nstring). However, if characters outside the + US-ASCII repertoire are used in an inappropriate place, the results + would be the same as if other syntactically valid but semantically + invalid characters were used. For example, if the client includes + UTF-8 characters in the user or password arguments (and the server + has not advertised "UTF8=USER"), the LOGIN command will fail as it + would with any other invalid user name or password. Specific cases + where UTF-8 characters are permitted or not permitted are described + in the following paragraphs. + + All IMAP servers that advertise the "UTF8=ACCEPT" capability SHOULD + accept UTF-8 in mailbox names, and those that also support the + "Mailbox International Naming Convention" described in RFC 3501, + Section 5.1.3 MUST accept utf8-quoted mailbox names and convert them + to the appropriate internal format. Mailbox names MUST comply with + the Net-Unicode Definition (Section 2 of [RFC5198]) with the specific + exception that they MUST NOT contain control characters (0000-001F, + 0080-009F), delete (007F), line separator (2028), or paragraph + separator (2029). + + An IMAP client MUST NOT issue a SEARCH command that uses a mixture of + utf8-quoted syntax and a SEARCH CHARSET other than UTF-8. If an IMAP + server receives such a SEARCH command, it SHOULD reject the command + with a BAD response (due to the conflicting charset labels). + + + + +Resnick & Newman Experimental [Page 4] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + +3.2. UTF8 Parameter to SELECT and EXAMINE + + The "UTF8=ACCEPT" capability also indicates that the server supports + the "UTF8" parameter to SELECT and EXAMINE. When a mailbox is + selected with the "UTF8" parameter, it alters the behavior of all + IMAP commands related to message sizes, message headers, and MIME + body headers so they refer to the message with UTF-8 headers. If the + mailstore is not UTF-8 header native and the SELECT or EXAMINE + command with UTF-8 header modifier succeeds, then the server MUST + return results as if the mailstore were UTF-8 header native with + upconversion requirements as described in Section 8. The server MAY + reject the SELECT or EXAMINE command with the [NOT-UTF-8] response + code, unless the "UTF8=ALL" or "UTF8=ONLY" capability is advertised. + + Servers MAY include mailboxes that can only be selected or examined + if the "UTF8" parameter is provided. However, such mailboxes MUST + NOT be included in the output of an unextended LIST, LSUB, or + equivalent command. If a client attempts to SELECT or EXAMINE such + mailboxes without the "UTF8" parameter, the server MUST reject the + command with a [UTF-8-ONLY] response code. As a result, such + mailboxes will not be accessible by IMAP clients written prior to + this specification and are discouraged unless the server advertises + "UTF8=ONLY" or the server implements IMAP4 LIST Command Extensions + [RFC5258]. + + utf8-select-param = "UTF8" + ;; Conforms to <select-param> from RFC 4466 + + C: a SELECT newmailbox (UTF8) + S: ... + S: a OK SELECT completed + C: b FETCH 1 (SIZE ENVELOPE BODY) + S: ... < UTF-8 header native results > + S: b OK FETCH completed + + C: c EXAMINE legacymailbox (UTF8) + S: c NO [NOT-UTF-8] Mailbox does not support UTF-8 access + + C: d SELECT funky-new-mailbox + S: d NO [UTF-8-ONLY] Mailbox requires UTF-8 client + +3.3. UTF-8 LIST and LSUB Responses + + After an IMAP client successfully issues an "ENABLE UTF8=ACCEPT" + command, the server MUST NOT return in LIST results any mailbox names + to the client following the IMAP4 Mailbox International Naming + Convention. Instead, the server MUST return any mailbox names with + characters outside the US-ASCII repertoire using utf8-quoted syntax. + + + +Resnick & Newman Experimental [Page 5] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + + (The IMAP4 Mailbox International Naming Convention has proved + problematic in the past, so the desire is to make this syntax + obsolete as quickly as possible.) + +3.4. UTF-8 Interaction with IMAP4 LIST Command Extensions + + When an IMAP server advertises both the "UTF8=ACCEPT" capability and + the "LIST-EXTENDED" [RFC5258] capability, the server MUST support the + LIST extensions described in this section. + +3.4.1. UTF8 and UTF8ONLY LIST Selection Options + + The "UTF8" LIST selection option tells the server to include + mailboxes that only support UTF-8 headers in the output of the list + command. The "UTF8ONLY" LIST selection option tells the server to + include all mailboxes that support UTF-8 headers and to exclude + mailboxes that don't support UTF-8 headers. Note that "UTF8ONLY" + implies "UTF8", so it is not necessary for the client to request + both. Use of either selection option will also result in UTF-8 + mailbox names in the result as described in Section 3.3 and implies + the "UTF8" List return option described in Section 3.4.2. + +3.4.2. UTF8 LIST Return Option + + If the client supplies the "UTF8" LIST return option, then the server + MUST include either the "\NoUTF8" or the "\UTF8Only" mailbox + attribute as appropriate. The "\NoUTF8" mailbox attribute indicates + that an attempt to SELECT or EXAMINE that mailbox with the "UTF8" + parameter will fail with a [NOT-UTF-8] response code. The + "\UTF8Only" mailbox attribute indicates that an attempt to SELECT or + EXAMINE that mailbox without the "UTF8" parameter will fail with a + [UTF-8-ONLY] response code. Note that computing this information may + be expensive on some server implementations, so this return option + should not be used unless necessary. + + The ABNF [RFC5234] for these LIST extensions follows: + + list-select-independent-opt =/ "UTF8" + + list-select-base-opt =/ "UTF8ONLY" + + mbx-list-oflag =/ "\NoUTF8" / "\UTF8Only" + + return-option =/ "UTF8" + + resp-text-code =/ "NOT-UTF-8" / "UTF-8-ONLY" + + + + + +Resnick & Newman Experimental [Page 6] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + +4. UTF8=APPEND Capability + + If the "UTF8=APPEND" capability is advertised, then the server + accepts UTF-8 headers in the APPEND command message argument. A + client that sends a message with UTF-8 headers to the server MUST + send them using the "UTF8" APPEND data extension. If the server also + advertises the CATENATE capability (as specified in [RFC4469]), the + client can use the same data extension to include such a message in a + CATENATE message part. The ABNF for the APPEND data extension and + CATENATE extension follows: + + utf8-literal = "UTF8" SP "(" literal8 ")" + + append-data =/ utf8-literal + + cat-part =/ utf8-literal + + A server that advertises "UTF8=APPEND" has to comply with the + requirements of the IMAP base specification and [RFC5322] for message + fetching. Mechanisms for 7-bit downgrading to help comply with the + standards are discussed in Downgrading mechanism for + Internationalized eMail Address (IMA) [RFC5504]. + + IMAP servers that do not advertise the "UTF8=APPEND" or "UTF8=ONLY" + capability SHOULD reject an APPEND command that includes any 8-bit in + the message headers with a "NO" response. + + Note that the "UTF8=ONLY" capability described in Section 7 implies + the "UTF8=APPEND" capability. See additional information in that + section. + +5. UTF8=USER Capability + + If the "UTF8=USER" capability is advertised, that indicates the + server accepts UTF-8 user names and passwords and applies SASLprep + [RFC4013] to both arguments of the LOGIN command. The server MUST + reject UTF-8 that fails to comply with the formal syntax in RFC 3629 + [RFC3629] or if it encounters Unicode characters listed in Section + 2.3 of SASLprep RFC 4013 [RFC4013]. + +6. UTF8=ALL Capability + + The "UTF8=ALL" capability indicates all server mailboxes support + UTF-8 headers. Specifically, SELECT and EXAMINE with the "UTF8" + parameter will never fail with a [NOT-UTF-8] response code. + + + + + + +Resnick & Newman Experimental [Page 7] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + + Note that the "UTF8=ONLY" capability described in Section 7 implies + the "UTF8=ALL" capability. See additional information in that + section. + + Note that the "UTF8=ALL" capability implies the "UTF8=ACCEPT" + capability. + +7. UTF8=ONLY Capability + + The "UTF8=ONLY" capability permits an IMAP server to advertise that + it does not support the international mailbox name convention + (modified UTF-7), and does not permit selection or examination of any + mailbox unless the "UTF8" parameter is provided. As this is an + incompatible change to IMAP, a clear warning is necessary. IMAP + clients that find implementation of the "UTF8=ONLY" capability + problematic are encouraged to at least detect the "UTF8=ONLY" + capability and provide an informative error message to the end-user. + + When an IMAP mailbox internally uses UTF-8 header native storage, the + down-conversion step is necessary to permit selection or examination + of the mailbox in a backwards compatible fashion will become more + difficult to support. Although it is hoped that deployed IMAP + servers will not advertise "UTF8=ONLY" for some years, this + capability is intended to minimize the disruption when legacy support + finally goes away. + + The "UTF8=ONLY" capability implies the "UTF8=ACCEPT" capability, the + "UTF8=ALL" capability, and the "UTF8=APPEND" capability. A server + that advertises "UTF8=ONLY" need not advertise the three implicit + capabilities. + +8. Up-Conversion Server Requirements + + When an IMAP4 server uses a traditional mailbox format that includes + 7-bit headers and it chooses to permit access to that mailbox with + the "UTF8" parameter, it MUST support minimal up-conversion as + described in this section. + + The server MUST support up-conversion of the following address + header-fields in the message header: From, Sender, To, CC, Bcc, + Resent-From, Resent-Sender, Resent-To, Resent-CC, Resent-Bcc, and + Reply-To. This up-conversion MUST include address local-parts in + fields downgraded according to [RFC5504], address domains encoded + according to Internationalizing Domain Names in Applications (IDNA) + [RFC3490], and MIME header encoding [RFC2047] of display-names and + any [RFC5322] comments. + + + + + +Resnick & Newman Experimental [Page 8] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + + The following charsets MUST be supported for up-conversion of MIME + header encoding [RFC2047]: UTF-8, US-ASCII, ISO-8859-1, ISO-8859-2, + ISO-8859-3, ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, + ISO-8859-8, ISO-8859-9, ISO-8859-10, ISO-8859-14, and ISO-8859-15. + If the server supports other charsets in IMAP SEARCH or IMAP CONVERT + [RFC5259], it SHOULD also support those charsets in this conversion. + + Up-conversion of MIME header encoding of the following headers MUST + also be implemented: Subject, Date ([RFC5322] comments only), + Comments, Keywords, and Content-Description. + + Server implementations also SHOULD up-convert all MIME body headers + [RFC2045], SHOULD up-convert or remove the deprecated (and misused) + "name" parameter [RFC1341] on Content-Type, and MUST up-convert the + Content-Disposition [RFC2183] "filename" parameter, except when any + of these are contained within a multipart/signed MIME body part (see + below). These parameters can be encoded using the standard MIME + parameter encoding [RFC2231] mechanism, or via non-standard use of + MIME header encoding [RFC2047] in quoted strings. + + The IMAP server MUST NOT perform up-conversion of headers and content + of multipart/signed, as well as Original-Recipient and Return-Path. + +9. Issues with UTF-8 Header Mailstore + + When an IMAP server uses a mailbox format that supports UTF-8 headers + and it permits selection or examination of that mailbox without the + "UTF8" parameter, it is the responsibility of the server to comply + with the IMAP4rev1 base specification [RFC3501] and [RFC5322] with + respect to all header information transmitted over the wire. + Mechanisms for 7-bit downgrading to help comply with the standards + are discussed in "Downgrading Mechanism for Email Address + Internationalization" [RFC5504]. + + An IMAP server with a mailbox that supports UTF-8 headers MUST comply + with the protocol requirements implicit from Section 8. However, the + code necessary for such compliance need not be part of the IMAP + server itself in this case. For example, the minimal required up- + conversion could be performed when a message is inserted into the + IMAP-accessible mailbox. + +10. IANA Considerations + + This adds five new capabilities ("UTF8=ACCEPT", "UTF8=USER", + "UTF8=APPEND", "UTF8=ALL", and "UTF8=ONLY") to the IMAP4rev1 + Capabilities registry [RFC3501]. + + + + + +Resnick & Newman Experimental [Page 9] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + + This adds two new IMAP4 list selection options and one new IMAP4 list + return option. + + 1. LIST-EXTENDED option name: UTF8 + + LIST-EXTENDED option type: SELECTION + + Implied return options(s): UTF8 + + LIST-EXTENDED option description: Causes the LIST response to + include mailboxes that mandate the UTF8 SELECT/EXAMINE parameter. + + Published specification: RFC 5738, Section 3.4.1 + + Security considerations: RFC 5738, Section 11 + + Intended usage: COMMON + + Person and email address to contact for further information: see + the Authors' Addresses at the end of this specification + + Owner/Change controller: iesg@ietf.org + + 2. LIST-EXTENDED option name: UTF8ONLY + + LIST-EXTENDED option type: SELECTION + + Implied return options(s): UTF8 + + LIST-EXTENDED option description: Causes the LIST response to + include mailboxes that mandate the UTF8 SELECT/EXAMINE parameter + and exclude mailboxes that do not support the UTF8 SELECT/EXAMINE + parameter. + + Published specification: RFC 5738, Section 3.4.1 + + Security considerations: RFC 5738, Section 11 + + Intended usage: COMMON + + Person and email address to contact for further information: see + the Authors' Addresses at the end of this specification + + Owner/Change controller: iesg@ietf.org + + + + + + + +Resnick & Newman Experimental [Page 10] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + + 3. LIST-EXTENDED option name: UTF8 + + LIST-EXTENDED option type: RETURN + + Implied return options(s): none + + LIST-EXTENDED option description: Causes the LIST response to + include \NoUTF8 and \UTF8Only mailbox attributes. + + Published specification: RFC 5738, Section 3.4.1 + + Security considerations: RFC 5738, Section 11 + + Intended usage: COMMON + + Person and email address to contact for further information: see + the Authors' Addresses at the end of this specification + + Owner/Change controller: iesg@ietf.org + +11. Security Considerations + + The security considerations of UTF-8 [RFC3629] and SASLprep [RFC4013] + apply to this specification, particularly with respect to use of + UTF-8 in user names and passwords. Otherwise, this is not believed + to alter the security considerations of IMAP4rev1. + +12. References + +12.1. Normative References + + [RFC1341] Borenstein, N. and N. Freed, "MIME (Multipurpose Internet + Mail Extensions): Mechanisms for Specifying and Describing + the Format of Internet Message Bodies", RFC 1341, + June 1992. + + [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail + Extensions (MIME) Part One: Format of Internet Message + Bodies", RFC 2045, November 1996. + + [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) + Part Three: Message Header Extensions for Non-ASCII Text", + RFC 2047, November 1996. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + + + + +Resnick & Newman Experimental [Page 11] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + + [RFC2183] Troost, R., Dorner, S., and K. Moore, "Communicating + Presentation Information in Internet Messages: The + Content-Disposition Header Field", RFC 2183, August 1997. + + [RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and Encoded + Word Extensions: + Character Sets, Languages, and Continuations", RFC 2231, + November 1997. + + [RFC3490] Faltstrom, P., Hoffman, P., and A. Costello, + "Internationalizing Domain Names in Applications (IDNA)", + RFC 3490, March 2003. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, November 2003. + + [RFC4013] Zeilenga, K., "SASLprep: Stringprep Profile for User Names + and Passwords", RFC 4013, February 2005. + + [RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 + ABNF", RFC 4466, April 2006. + + [RFC4469] Resnick, P., "Internet Message Access Protocol (IMAP) + CATENATE Extension", RFC 4469, April 2006. + + [RFC5161] Gulbrandsen, A. and A. Melnikov, "The IMAP ENABLE + Extension", RFC 5161, March 2008. + + [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network + Interchange", RFC 5198, March 2008. + + [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + + [RFC5258] Leiba, B. and A. Melnikov, "Internet Message Access + Protocol version 4 - LIST Command Extensions", RFC 5258, + June 2008. + + [RFC5259] Melnikov, A. and P. Coates, "Internet Message Access + Protocol - CONVERT Extension", RFC 5259, July 2008. + + [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, + October 2008. + + + + + +Resnick & Newman Experimental [Page 12] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + + [RFC5335] Abel, Y., "Internationalized Email Headers", RFC 5335, + September 2008. + + [RFC5504] Fujiwara, K. and Y. Yoneya, "Downgrading Mechanism for + Email Address Internationalization", RFC 5504, March 2009. + +12.2. Informative References + + [RFC2049] Freed, N. and N. Borenstein, "Multipurpose Internet Mail + Extensions (MIME) Part Five: Conformance Criteria and + Examples", RFC 2049, November 1996. + + [RFC2088] Myers, J., "IMAP4 non-synchronizing literals", RFC 2088, + January 1997. + + [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and + Languages", BCP 18, RFC 2277, January 1998. + + [RFC5721] Gellens, R. and C. Newman, "POP3 Support for UTF-8", + RFC 5721, February 2010. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Resnick & Newman Experimental [Page 13] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + +Appendix A. Design Rationale + + This non-normative section discusses the reasons behind some of the + design choices in the above specification. + + The basic approach of advertising the ability to access a mailbox in + UTF-8 mode is intended to permit graceful upgrade, including servers + that support multiple mailbox formats. In particular, it would be + undesirable to force conversion of an entire server mailstore to + UTF-8 headers, so being able to phase-in support for new mailboxes + and gradually migrate old mailboxes is permitted by this design. + + "UTF8=USER" is optional because many identity systems are US-ASCII + only, so it's helpful to inform the client up front that UTF-8 won't + work. + + "UTF8=APPEND" is optional because it effectively requires IMAP server + support for down-conversion, which is a much more complex operation + than up-conversion. + + The "UTF8=ONLY" mechanism simplifies diagnosis of interoperability + problems when legacy support goes away. In the situation where + backwards compatibility is broken anyway, just-send-UTF-8 IMAP has + the advantage that it might work with some legacy clients. However, + the difficulty of diagnosing interoperability problems caused by a + just-send-UTF-8 IMAP mechanism is the reason the "UTF8=ONLY" + capability mechanism was chosen. + + The up-conversion requirements are designed to balance the desire to + deprecate and eventually eliminate complicated encodings (like MIME + header encodings) without creating a significant deployment burden + for servers. As IMAP4 servers already require a MIME parser, this + includes additional server up-conversion requirements not present in + POP3 Support for UTF-8 [RFC5721]. + + The set of mandatory charsets comes from two sources: MIME + requirements [RFC2049] and IETF Policy on Character Sets [RFC2277]. + Including a requirement to up-convert widely deployed encoded + ideographic charsets to UTF-8 would be reasonable for most scenarios, + but may require unacceptable table sizes for some embedded devices. + The open-ended recommendation to support widely deployed charsets + avoids the political ramifications of attempting to list such + charsets. The authors believe market forces, existing open-source + software, and public conversion tables are sufficient to deploy the + appropriate charsets. + + + + + + +Resnick & Newman Experimental [Page 14] + +RFC 5738 IMAP Support for UTF-8 March 2010 + + +Appendix B. Examples Demonstrating Relationships between UTF8= + Capabilities + + + UTF8=ACCEPT UTF8=USER UTF8=APPEND + UTF8=ACCEPT UTF8=ALL + UTF8=ALL ; Note, same as above + UTF8=ACCEPT UTF8=USER UTF8=APPEND UTF8=ALL UTF8=ONLY + UTF8=USER UTF8=ONLY ; Note, same as above + +Appendix C. Acknowledgments + + The authors wish to thank the participants of the EAI working group + for their contributions to this document with particular thanks to + Harald Alvestrand, David Black, Randall Gellens, Arnt Gulbrandsen, + Kari Hurtta, John Klensin, Xiaodong Lee, Charles Lindsey, Alexey + Melnikov, Subramanian Moonesamy, Shawn Steele, Daniel Taharlev, and + Joseph Yee for their specific contributions to the discussion. + +Authors' Addresses + + Pete Resnick + Qualcomm Incorporated + 5775 Morehouse Drive + San Diego, CA 92121-1714 + US + + Phone: +1 858 651 4478 + EMail: presnick@qualcomm.com + URI: http://www.qualcomm.com/~presnick/ + + Chris Newman + Sun Microsystems + 800 Royal Oaks + Monrovia, CA 91016 + US + + EMail: chris.newman@sun.com + + + + + + + + + + + + + +Resnick & Newman Experimental [Page 15] + diff --git a/imap/docs/rfc/rfc5788.txt b/imap/docs/rfc/rfc5788.txt new file mode 100644 index 00000000..fe0de709 --- /dev/null +++ b/imap/docs/rfc/rfc5788.txt @@ -0,0 +1,619 @@ + + + + + + +Internet Engineering Task Force (IETF) A. Melnikov +Request for Comments: 5788 D. Cridland +Category: Standards Track Isode Limited +ISSN: 2070-1721 March 2010 + + + IMAP4 Keyword Registry + +Abstract + + The aim of this document is to establish a new IANA registry for IMAP + keywords and to define a procedure for keyword registration, in order + to improve interoperability between different IMAP clients. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc5788. + +Copyright Notice + + Copyright (c) 2010 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + + + + + + + +Melnikov & Cridland Standards Track [Page 1] + +RFC 5788 IMAP4 Keyword Registry March 2010 + + +Table of Contents + + 1. Introduction ....................................................2 + 2. Conventions Used in This Document ...............................2 + 3. IANA Considerations .............................................3 + 3.1. Review Guidelines for the Designated Expert Reviewer .......4 + 3.2. Comments on IMAP Keywords' Registrations ...................5 + 3.3. Change Control .............................................5 + 3.4. Initial Registrations ......................................6 + 3.4.1. $MDNSent IMAP Keyword Registration ..................6 + 3.4.2. $Forwarded IMAP Keyword Registration ................7 + 3.4.3. $SubmitPending IMAP Keyword Registration ............8 + 3.4.4. $Submitted IMAP Keyword Registration ................9 + 4. Security Considerations ........................................10 + 5. Acknowledgements ...............................................10 + 6. References .....................................................10 + 6.1. Normative References ......................................10 + 6.2. Informative References ....................................11 + +1. Introduction + + IMAP keywords [RFC3501] are boolean named flags that can be used by + clients to annotate messages in an IMAP mailbox. Although IMAP + keywords are an optional feature of IMAP, the majority of IMAP + servers can store arbitrary keywords. Many mainstream IMAP clients + use a limited set of specific keywords, and some can manage (create, + edit, display) arbitrary IMAP keywords. + + Over the years, some IMAP keywords have become de-facto standards, + with some specific semantics associated with them. In some cases, + different client implementors decided to define and use keywords with + different names, but the same semantics. Some server implementors + decided to map such keywords automatically in order to improve cross- + client interoperability. + + In other cases, the same keywords have been used with different + semantics, thus causing interoperability problems. + + This document attempts to prevent further incompatible uses of IMAP + keywords by establishing an "IMAP Keywords" registry and allocating a + special prefix for standardized keywords. + +2. Conventions Used in This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [Kwds]. + + + + +Melnikov & Cridland Standards Track [Page 2] + +RFC 5788 IMAP4 Keyword Registry March 2010 + + +3. IANA Considerations + + IANA has established a new registry for IMAP keywords. + + Registration of an IMAP keyword is requested by filling in the + following template and following the instructions on the IANA pages + for the registry to submit it to IANA: + + Subject: Registration of IMAP keyword X + + IMAP keyword name: + + Purpose (description): + + Private or Shared on a server: (One of PRIVATE, SHARED, or BOTH. + PRIVATE means that each different + user has a distinct copy of the + keyword. SHARED means that all + different users see the same value of + the keyword. BOTH means that an IMAP + server can have the keyword as either + private or shared.) + + Is it an advisory keyword or may it cause an automatic action: + + When/by whom the keyword is set/cleared: + + Related keywords: (for example, "mutually exclusive with keywords Y + and Z") + + Related IMAP capabilities: + + Security considerations: + + Published specification (recommended): + + Person & email address to contact for further information: + + Intended usage: (One of COMMON, LIMITED USE, or DEPRECATED (i.e., + not recommended for use)) + + Owner/Change controller: (MUST be "IESG" for any "common use" + keyword registration specified in an IETF + Review document. See definition of "common + use" below in this section. When the + Owner/Change controller is not a + Standardization Organization, the + registration request MUST make it clear if + + + +Melnikov & Cridland Standards Track [Page 3] + +RFC 5788 IMAP4 Keyword Registry March 2010 + + + the registration is controlled by a + company, or the individual performing the + registration.) + + Note: (Any other information that the author deems interesting + may be added here, for example, if the keyword(s) is + supported by existing clients.) + + Registration of an IMAP keyword requires Expert Review [RFC5226]. + Registration of any IMAP keyword is initiated by posting a + registration request to the Message Organization WG mailing list + <morg@ietf.org> (or its replacement as chosen by the responsible + Application Area Director) and CCing IANA (<iana@iana.org>). After + allowing for at least two weeks for community input on the designated + mailing list, the expert will determine the appropriateness of the + registration request and either approve or disapprove the request + with notice to the requestor, the mailing list, and IANA. Any + refusal must come with a clear explanation. + + The IESG appoints one or more Expert Reviewers for the IMAP keyword + registry established by this document. + + The Expert Reviewer should strive for timely reviews. The Expert + Reviewer should take no longer than six weeks to make and announce + the decision, or notify the mailing list that more time is required. + + Decisions (or lack of) made by an Expert Reviewer can be first + appealed to Application Area Directors and, if the appellant is not + satisfied with the response, to the full IESG. + + There are two types of IMAP keywords in the "IMAP Keywords" registry: + intended for "common use" and vendor-/organization-specific use (also + known as "limited use"). An IMAP keyword is said to be for "common + use" if it is reasonably expected to be implemented in at least two + independent client implementations. The two types of IMAP keywords + have different levels of requirements for registration (see below). + +3.1. Review Guidelines for the Designated Expert Reviewer + + Expert Reviewers should focus on the following requirements. + + Registration of a vendor-/organization-specific ("limited use") IMAP + keyword is easier. The Expert Reviewer only needs to check that the + requested name doesn't conflict with an already registered name, and + that the name is not too generic, misleading, etc. The Expert + Reviewer MAY request the IMAP keyword name change before approving + + + + + +Melnikov & Cridland Standards Track [Page 4] + +RFC 5788 IMAP4 Keyword Registry March 2010 + + + the registration. The Expert Reviewer SHOULD refuse a registration + if there is an already registered IMAP keyword that serves the same + purpose, but has a different name. + + When registering an IMAP keyword for "common use", the Expert + Reviewer performs the checks described for vendor-/ + organization-specific IMAP keywords, plus additional checks as + detailed below. + + Keywords intended for "common use" SHOULD start with the "$" prefix. + (Note that this is a SHOULD because some of the commonly used IMAP + keywords in widespread use don't follow this convention.) + + IMAP keywords intended for "common use" SHOULD be standardized in + IETF Review [RFC5226] documents. (Note that IETF Review documents + still require Expert Review.) + + Values in the "IMAP Keywords" IANA registry intended for "common use" + must be clearly documented and likely to ensure interoperability. + They must be useful, not harmful to the Internet. In cases when an + IMAP keyword being registered is already deployed, Expert Reviewers + should favor registering it over requiring perfect documentation + and/or requesting a change to the name of the IMAP keyword. + + The Expert Reviewer MAY automatically "upgrade" registration requests + for a "limited use" IMAP keyword to "common use" level. The Expert + Reviewer MAY also request that a registration targeted for "common + use" be registered as "limited use" instead. + +3.2. Comments on IMAP Keywords' Registrations + + Comments on registered IMAP keywords should be sent to both the + "owner" of the mechanism and to the mailing list designated to IMAP + keyword review (see Section 3). This improves the chances of getting + a timely response. + + Submitters of comments may, after a reasonable attempt to contact the + owner and after soliciting comments on the IMAP mailing list, request + the designated Expert Reviewer to attach their comment to the IMAP + keyword registration itself. The procedure is similar to requesting + an Expert Review for the affected keyword. + +3.3. Change Control + + Once an IMAP keyword registration has been published by IANA, the + owner may request a change to its definition. The change request + (including a change to the "intended usage" field) follows the same + procedure as the initial registration request, with the exception of + + + +Melnikov & Cridland Standards Track [Page 5] + +RFC 5788 IMAP4 Keyword Registry March 2010 + + + changes to the "Person & email address to contact for further + information" and "Owner/Change controller" fields. The latter can be + changed by the owner by informing IANA; this can be done without + discussion or review. + + The IESG may reassign responsibility for an IMAP keyword. The most + common case of this will be to enable clarifications to be made to + keywords where the owner of the registration has died, moved out of + contact, or is otherwise unable to make changes that are important to + the community. + + IMAP keyword registrations MUST NOT be deleted; keywords that are no + longer believed appropriate for use can be declared DEPRECATED by a + change to their "intended usage" field. + + The IESG is considered the owner of all "common use" IMAP keywords + that are published in an IETF Review document. + +3.4. Initial Registrations + + IANA has registered the IMAP keywords specified in following + subsections in the registry established by this document. + +3.4.1. $MDNSent IMAP Keyword Registration + + Subject: Registration of IMAP keyword $MDNSent + + + IMAP keyword name: $MDNSent + + Purpose (description): Specifies that a Message Disposition + Notification (MDN) must not be sent for any + message annotated with the $MDNSent IMAP + keyword. + + Private or Shared on a server: SHARED + + Is it an advisory keyword or may it cause an automatic action: + This keyword can cause automatic action by + the client. See [RFC3503] for more details. + + When/by whom the keyword is set/cleared: + This keyword is set by an IMAP client when it + decides to act on an MDN request, or when + uploading a sent or draft message. It can + also be set by a delivery agent. Once set, + the flag SHOULD NOT be cleared. + + + + +Melnikov & Cridland Standards Track [Page 6] + +RFC 5788 IMAP4 Keyword Registry March 2010 + + + Related keywords: None + + Related IMAP capabilities: None + + Security considerations: See Section 6 of [RFC3503] + + Published specification (recommended): [RFC3503] + + Person & email address to contact for further information: + Alexey Melnikov <alexey.melnikov@isode.com> + + Intended usage: COMMON + + Owner/Change controller: IESG + + Note: + +3.4.2. $Forwarded IMAP Keyword Registration + + Subject: Registration of the IMAP keyword $Forwarded + + IMAP keyword name: $Forwarded + + Purpose (description): $Forwarded is used by several IMAP clients to + specify that the message was resent to + another email address, embedded within or + attached to a new message. This keyword is + set by the mail client when it successfully + forwards the message to another email + address. Typical usage of this keyword is to + show a different (or additional) icon for a + message that has been forwarded. + + Private or Shared on a server: BOTH + + Is it an advisory keyword or may it cause an automatic action: + advisory + + When/by whom the keyword is set/cleared: + This keyword can be set by either a delivery + agent or a mail client. Once set, the flag + SHOULD NOT be cleared. Notes: There is no + way to tell if a message with $Forwarded + keyword set was forwarded more than once. + + Related keywords: None + + Related IMAP capabilities: None + + + +Melnikov & Cridland Standards Track [Page 7] + +RFC 5788 IMAP4 Keyword Registry March 2010 + + + Security considerations: A server implementing this keyword as a + shared keyword may disclose that a + confidential message was forwarded. + + Published specification (recommended): [RFC5550] + + Person & email address to contact for further information: + Alexey Melnikov <alexey.melnikov@isode.com> + + Intended usage: COMMON + + Owner/Change controller: IESG + + Note: + +3.4.3. $SubmitPending IMAP Keyword Registration + + Subject: Registration of IMAP keyword $SubmitPending + + IMAP keyword name: $SubmitPending + + Purpose (description): The $SubmitPending IMAP keyword designates + the message as awaiting to be submitted. + This keyword allows storing messages waiting + to be submitted in the same mailbox where + messages that were already submitted and/or + are being edited are stored. + + A message that has both $Submitted and + $SubmitPending IMAP keywords set is a message + being actively submitted. + + Private or Shared on a server: SHARED + + Is it an advisory keyword or may it cause an automatic action: + This keyword can cause automatic action by + the client. See Section 5.10 of [RFC5550] + for more details. + + When/by whom the keyword is set/cleared: + This keyword is set by a mail client when it + decides that the message needs to be sent + out. + + Related keywords: $Submitted + + Related IMAP capabilities: None + + + + +Melnikov & Cridland Standards Track [Page 8] + +RFC 5788 IMAP4 Keyword Registry March 2010 + + + Security considerations: A server implementing this keyword as a + shared keyword may disclose that a + confidential message is scheduled to be + sent out or is being actively sent out. + + Published specification (recommended): [RFC5550] + + Person & email address to contact for further information: + Alexey Melnikov <alexey.melnikov@isode.com> + + Intended usage: COMMON + + Owner/Change controller: IESG + + Note: + +3.4.4. $Submitted IMAP Keyword Registration + + Subject: Registration of IMAP keyword $Submitted + + IMAP keyword name: $Submitted + + Purpose (description): The $Submitted IMAP keyword designates the + message as being sent out. + + A message that has both $Submitted and + $SubmitPending IMAP keywords set is a message + being actively submitted. + + Private or Shared on a server: SHARED + + Is it an advisory keyword or may it cause an automatic action: + This keyword can cause automatic action by + the client. See Section 5.10 of [RFC5550] + for more details. + + When/by whom the keyword is set/cleared: + This keyword is set by a mail client when it + decides to start sending it. + + Related keywords: $SubmitPending + + Related IMAP capabilities: None + + Security considerations: A server implementing this keyword as a + shared keyword may disclose that a + confidential message was sent or is being + actively sent out. + + + +Melnikov & Cridland Standards Track [Page 9] + +RFC 5788 IMAP4 Keyword Registry March 2010 + + + Published specification (recommended): [RFC5550] + + Person & email address to contact for further information: + Alexey Melnikov <alexey.melnikov@isode.com> + + Intended usage: COMMON + + Owner/Change controller: IESG + + Note: + +4. Security Considerations + + IMAP keywords are one of the base IMAP features [RFC3501]. This + document doesn't change their behavior, so it does not add new + security issues. + + A particular IMAP keyword might have specific security + considerations, which are documented in the IMAP keyword + registration template standardized by this document. + +5. Acknowledgements + + The creation of this document was prompted by one of many discussions + on the IMAP mailing list. + + John Neystadt co-authored the first version of this document. + + Special thanks to Chris Newman, David Harris, Lyndon Nerenberg, Mark + Crispin, Samuel Weiler, Alfred Hoenes, Lars Eggert, and Cullen + Jennings for reviewing different versions of this document. However, + all errors or omissions must be attributed to the authors of this + document. + + The authors would also like to thank the developers of Mozilla mail + clients for providing food for thought. + +6. References + +6.1. Normative References + + [Kwds] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + + + + +Melnikov & Cridland Standards Track [Page 10] + +RFC 5788 IMAP4 Keyword Registry March 2010 + + + [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an + IANA Considerations Section in RFCs", BCP 26, RFC 5226, + May 2008. + +6.2. Informative References + + [RFC3503] Melnikov, A., "Message Disposition Notification (MDN) + profile for Internet Message Access Protocol (IMAP)", + RFC 3503, March 2003. + + [RFC5550] Cridland, D., Melnikov, A., and S. Maes, "The Internet + Email to Support Diverse Service Environments (Lemonade) + Profile", RFC 5550, August 2009. + +Authors' Addresses + + Alexey Melnikov + Isode Limited + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: Alexey.Melnikov@isode.com + URI: http://www.melnikov.ca/ + + + Dave Cridland + Isode Limited + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: dave.cridland@isode.com + + + + + + + + + + + + + + + + +Melnikov & Cridland Standards Track [Page 11] + diff --git a/imap/docs/rfc/rfc5819.txt b/imap/docs/rfc/rfc5819.txt new file mode 100644 index 00000000..e45b8558 --- /dev/null +++ b/imap/docs/rfc/rfc5819.txt @@ -0,0 +1,339 @@ + + + + + + +Internet Engineering Task Force (IETF) A. Melnikov +Request for Comments: 5819 Isode Limited +Category: Standards Track T. Sirainen +ISSN: 2070-1721 Unaffiliated + March 2010 + + + IMAP4 Extension for Returning STATUS Information in Extended LIST + +Abstract + + Many IMAP clients display information about total number of + messages / total number of unseen messages in IMAP mailboxes. In + order to do that, they are forced to issue a LIST or LSUB command and + to list all available mailboxes, followed by a STATUS command for + each mailbox found. This document provides an extension to LIST + command that allows the client to request STATUS information for + mailboxes together with other information typically returned by the + LIST command. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc5819. + +Copyright Notice + + Copyright (c) 2010 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + +Melnikov & Sirainen Standards Track [Page 1] + +RFC 5819 TITLE* March 2010 + + +Table of Contents + + 1. Introduction ....................................................2 + 1.1. Conventions Used in This Document ..........................2 + 2. STATUS Return Option to LIST Command ............................2 + 3. Examples ........................................................3 + 4. Formal Syntax ...................................................4 + 5. Security Considerations .........................................4 + 6. IANA Considerations .............................................4 + 7. Acknowledgements ................................................5 + 8. Normative References ............................................5 + +1. Introduction + + Many IMAP clients display information about the total number of + messages / total number of unseen messages in IMAP mailboxes. In + order to do that, they are forced to issue a LIST or LSUB command and + to list all available mailboxes, followed by a STATUS command for + each mailbox found. This document provides an extension to LIST + command that allows the client to request STATUS information for + mailboxes together with other information typically returned by the + LIST command. + +1.1. Conventions Used in This Document + + In examples, "C:" indicates lines sent by a client that is connected + to a server. "S:" indicates lines sent by the server to the client. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [Kwds]. + +2. STATUS Return Option to LIST Command + + [RFC3501] explicitly disallows mailbox patterns in the STATUS + command. The main reason was to discourage frequent use of the + STATUS command by clients, as it might be quite expensive for an IMAP + server to perform. However, this prohibition had resulted in an + opposite effect: a new generation of IMAP clients appeared, that + issues a STATUS command for each mailbox returned by the LIST + command. This behavior is suboptimal to say at least. It wastes + extra bandwidth and, in the case of a client that doesn't support + IMAP pipelining, also degrades performance by using too many round + trips. This document tries to remedy the situation by specifying a + single command that can be used by the client to request all the + necessary information. In order to achieve this goal, this document + is extending the LIST command with a new return option, STATUS. This + option takes STATUS data items as parameters. For each selectable + + + +Melnikov & Sirainen Standards Track [Page 2] + +RFC 5819 TITLE* March 2010 + + + mailbox matching the list pattern and selection options, the server + MUST return an untagged LIST response followed by an untagged STATUS + response containing the information requested in the STATUS return + option. + + If an attempted STATUS for a listed mailbox fails because the mailbox + can't be selected (e.g., if the "l" ACL right [ACL] is granted to the + mailbox and the "r" right is not granted, or due to a race condition + between LIST and STATUS changing the mailbox to \NoSelect), the + STATUS response MUST NOT be returned and the LIST response MUST + include the \NoSelect attribute. This means the server may have to + buffer the LIST reply until it has successfully looked up the + necessary STATUS information. + + If the server runs into unexpected problems while trying to look up + the STATUS information, it MAY drop the corresponding STATUS reply. + In such a situation, the LIST command would still return a tagged OK + reply. + +3. Examples + + C: A01 LIST "" % RETURN (STATUS (MESSAGES UNSEEN)) + S: * LIST () "." "INBOX" + S: * STATUS "INBOX" (MESSAGES 17 UNSEEN 16) + S: * LIST () "." "foo" + S: * STATUS "foo" (MESSAGES 30 UNSEEN 29) + S: * LIST (\NoSelect) "." "bar" + S: A01 OK List completed. + + The "bar" mailbox isn't selectable, so it has no STATUS reply. + + C: A02 LIST (SUBSCRIBED RECURSIVEMATCH)"" % RETURN (STATUS + (MESSAGES)) + S: * LIST (\Subscribed) "." "INBOX" + S: * STATUS "INBOX" (MESSAGES 17) + S: * LIST () "." "foo" (CHILDINFO ("SUBSCRIBED")) + S: A02 OK List completed. + + The LIST reply for "foo" is returned because it has matching + children, but no STATUS reply is returned because "foo" itself + doesn't match the selection criteria. + + + + + + + + + + +Melnikov & Sirainen Standards Track [Page 3] + +RFC 5819 TITLE* March 2010 + + +4. Formal Syntax + + The following syntax specification uses the augmented Backus-Naur + Form (BNF) as described in [ABNF]. Terms not defined here are taken + from [RFC3501] and [LISTEXT]. + + return-option =/ status-option + + status-option = "STATUS" SP "(" status-att *(SP status-att) ")" + ;; This ABNF production complies with + ;; <option-extension> syntax. + +5. Security Considerations + + This extension makes it a bit easier for clients to overload the + server by requesting STATUS information for a large number of + mailboxes. However, as already noted in the introduction, existing + clients already try to do that by generating a large number of STATUS + commands for each mailbox in which they are interested. While + performing STATUS information retrieval for big lists of mailboxes, a + server implementation needs to make sure that it can still serve + other IMAP connections and yield execution to other connections, when + necessary. + +6. IANA Considerations + + IMAP4 capabilities are registered by publishing a Standards Track or + IESG-approved Experimental RFC. The "IMAP 4 Capabilities" registry + is available from the IANA webiste: + + http://www.iana.org + + This document defines the LIST-STATUS IMAP capability. IANA has + added it to the registry. + + IANA has also added the following new LIST-EXTENDED option to the + IANA registry established by [LISTEXT]: + + To: iana@iana.org + Subject: Registration of LIST-EXTENDED option STATUS + + LIST-EXTENDED option name: STATUS + + LIST-EXTENDED option type: RETURN + + LIST-EXTENDED option description: Causes the LIST command to return + STATUS responses in addition to LIST responses. + + + + +Melnikov & Sirainen Standards Track [Page 4] + +RFC 5819 TITLE* March 2010 + + + Published specification: RFC 5819 + + Security considerations: RFC 5819 + + Intended usage: COMMON + + Person and email address to contact for further information: + Alexey Melnikov <Alexey.Melnikov@isode.com> + + Owner/Change controller: iesg@ietf.org + +7. Acknowledgements + + Thanks to Philip Van Hoof who pointed out that STATUS and LIST + commands should be combined in order to optimize traffic and number + of round trips. + +8. Normative References + + [ABNF] Crocker, D., Ed., and P. Overell, "Augmented BNF for + Syntax Specifications: ABNF", STD 68, RFC 5234, January + 2008. + + [ACL] Melnikov, A., "IMAP4 Access Control List (ACL) Extension", + RFC 4314, December 2005. + + [Kwds] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [LISTEXT] Leiba, B. and A. Melnikov, "Internet Message Access + Protocol version 4 - LIST Command Extensions", RFC 5258, + June 2008. + + [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION + 4rev1", RFC 3501, March 2003. + + + + + + + + + + + + + + + + +Melnikov & Sirainen Standards Track [Page 5] + +RFC 5819 TITLE* March 2010 + + +Authors' Addresses + + Alexey Melnikov + Isode Limited + 5 Castle Business Village + 36 Station Road + Hampton, Middlesex TW12 2BX + UK + + EMail: Alexey.Melnikov@isode.com + URI: http://www.melnikov.ca/ + + + Timo Sirainen + + EMail: tss@iki.fi + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Melnikov & Sirainen Standards Track [Page 6] + |