diff options
| author | Eduardo Chappa <echappa@gmx.com> | 2013-02-03 00:59:38 -0700 |
|---|---|---|
| committer | Eduardo Chappa <echappa@gmx.com> | 2013-02-03 00:59:38 -0700 |
| commit | 094ca96844842928810f14844413109fc6cdd890 (patch) | |
| tree | e60efbb980f38ba9308ccb4fb2b77b87bbc115f3 /imap/docs | |
| download | alpine-094ca96844842928810f14844413109fc6cdd890.tar.xz | |
Initial Alpine Version
Diffstat (limited to 'imap/docs')
66 files changed, 52209 insertions, 0 deletions
diff --git a/imap/docs/BUILD b/imap/docs/BUILD new file mode 100644 index 00000000..e094e065 --- /dev/null +++ b/imap/docs/BUILD @@ -0,0 +1,491 @@ +/* ======================================================================== + * 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 + * + * + * ======================================================================== + */ + + BUILD AND INSTALLATION NOTES + Last Updated: 15 November 2007 + +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) + + + UNIX BUILD NOTES + + The default build on many systems with IPv4 only. To build with IPv6, +add "IP=6" to the make command line, e.g. + make lnp IP=6 + + The default build is to build with SSL and disabling plaintext passwords +unless SSL/TLS encryption is in effect (SSLTYPE=nopwd). This means that +OpenSSL MUST be installed before building the IMAP toolkit. Please refer to +the SSLBUILD file for more information. + + To build without SSL, add "SSLTYPE=none" to the make command line. +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 +takes place. + + Before doing a make on UNIX, you should read imap-2007/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, +so just typing "make" suffices. + + For example, if you are using a more or less modern Linux system, your +system type is probably one of the specific distribution types (such as lrh for +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. + + It's probably best to see if an existing port will work on your system +before inventing a new port. Try: + sv4 generic SVR4, non-ANSI compiler + a32 modern SVR4 + bsd basic 4.3 BSD, non-ANSI compiler + 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 +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 +compiler supports *ALL* aspects of ANSI C prototyping. Note that some +compilers, such as Ultrix, support some aspects of ANSI C but not others; +c-client really beats on the full prototyping capability of ANSI C so you +have to use the non-ANSI source tree for such systems. + + If you send a new port back to us, we will make it available for others +who use your particular system type. + + The mbox driver is now enabled by default. If the file "mbox" 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. To disable this behavior, delete "mbox" from the EXTRADRIVERS list +in the top-level Makefile and rebuild. + + WARNING: The SVR2 (sv2) port is *incomplete*. SVR2 does not appear to +have any way to do ftruncate(), which is needed by the mbox, mbx, mmdf, mtx, +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 + + mtest is normally not used except by c-client developers. + +STEP 1: [x]inetd setup + + The ipop2d, ipop3d, and imapd daemons should be installed in a system +daemon directory and invoked by a listener such as xinetd or inetd. In the +following examples, /usr/local/etc is used). + +STEP 1(A): xinetd-specific setup + + If your system uses xinetd, the daemons are invoked by files in your +/etc/xinetd.d directory with names corresponding to the service names (that +is: imap, pop2, pop3). You will need to consult your local xinetd +documentation to see what should go into these files. Here is a a sample +/etc/xinetd.d/imap file: + +service imap +{ + disable = no + socket_type = stream + wait = no + user = root + server = /usr/local/etc/imapd + groups = yes + flags = REUSE IPv6 +} + +STEP 1(B): inetd-specific setup + + If your system still uses inetd, the daemons are invoked by your +/etc/inetd.conf file with lines such as: + +pop stream tcp nowait root /usr/local/etc/ipop2d ipop2d +pop3 stream tcp nowait root /usr/local/etc/ipop3d ipop3d +imap stream tcp nowait root /usr/local/etc/imapd imapd + + Note that different variants of UNIX have different versions of inetd, +so you should verify the precise form of these commands (for example, some +versions of inetd do not require the "nowait"). + + IMPORTANT NOTE: inetd has a limit of how many new connections it will +allow in a certain interval, and when this limit is exceeded, it shuts down +the server. If you have anything beyond a small-scale server, you are +probably going to run up against this limit. You'll know when it happens; +your syslog will give the misleading message "imap/tcp server failing +(looping), service terminated" and users will complain that IMAP service is +unavailable for the next 10 minutes. Similarly with "pop3/tcp server +failing"... + + It must be emphasized that this is *NOT* a bug in the IMAP or POP +servers, nor is it anything that I can "fix". It is an inetd problem, and +the only way to fix it is to change inetd's behavior. + + By default, the parameters of this limit are (from inetd.c source code): + +#define TOOMANY 40 /* don't start more than TOOMANY */ +#define CNT_INTVL 60 /* servers in CNT_INTVL sec. */ +#define RETRYTIME (60*10) /* retry after bind or server fail */ + +That is, no more than 40 connections (TOOMANY) in 60 seconds (CNT_INTL), and +if exceeded, shut down the server for 10 minutes (RETRYTIME). This was a +good setting in the 1980s ARPAnet, but is much too small today. + + Some versions of inetd allow you to see a higher maximum in the +/etc/inetd.conf file. Read "man inetd" and see if you see something like +this in the text: + + The wait/nowait entry is applicable to datagram sockets only [...] + [...] The optional ``max'' suffix (separated from + ``wait'' or ``nowait'' by a dot) specifies the maximum number of server + instances that may be spawned from inetd within an interval of 60 sec- + onds. When omitted, ``max'' defaults to 40. + +If you see this, then edit the /etc/inetd.conf entry for imapd to be +something like: + +imap stream tcp nowait.100 root /usr/local/etc/imapd imapd + (or, if you use TCP wrappers) +imap stream tcp nowait.100 root /usr/local/etc/tcpd imapd + + Otherwise, you'll need to edit the inetd source code to set TOOMANY to a +higher value, then rebuild inetd. + + +STEP 2: services setup + + You may also have to edit your /etc/services (or Yellow Pages, +NetInfo, etc. equivalent) to register these services, such as: + +pop 109/tcp +pop3 110/tcp +imap 143/tcp + + +STEP 3: PAM setup + + If your system has PAM (Pluggable Authentication Modules -- most +modern systems do) then you need to set up PAM authenticators for imap and +pop. The correct file names are + /etc/pam.d/imap +and + /etc/pam.d/pop + + It probably works to copy your /etc/pam.d/ftpd file to the above two +names. + + Many people get these file names wrong, and then spend a lot of time +trying to figure out why it doesn't work. Common mistakes are: + /etc/pam.d/imapd + /etc/pam.d/imap4 + /etc/pam.d/imap4rev1 + /etc/pam.d/ipop3d + /etc/pam.d/pop3d + /etc/pam.d/popd + /etc/pam.d/pop3 + + +STEP 4: optional rimap setup + + If you want to enable the rimap capability, which allows users with a +suitable client and .rhosts file on the server to access IMAP services +without transmitting her password in the clear over the network, you need +to have /etc/rimapd as a link to the real copy of imapd. Assuming you have +imapd installed on /usr/local/etc as above: + % ln -s /usr/local/etc/imapd /etc/rimapd + + Technical note: rimap works by having the client routine tcp_aopen() +invoke `rsh _host_ exec /etc/rimapd' in an child process, and then returning +pipes to that process' standard I/O instead of a TCP socket. You can set up +`e-mail only accounts' by making the shell be something which accepts only +that string and not ordinary UNIX shell commands. + + +STEP 4: notes on privileges + + Neither user "root", not any other UID 0 account, can log in via IMAP or +POP. "That's not a bug, it's a feature!" + + This software is designed to run without privileges. The mail spool +directory must be protected 1777; that is, with world write and the sticky +bit. Of course, mail *files* should be protected 600! + + An alternative to having the mail spool directory protected 1777, at the +cost of some performance, is to use the external "mlock" program, available +as part of the imap-utils package. With mlock installed as /etc/mlock and +setgid mail, the spool directory can be protected 775 with group mail. +Please disregard this paragraph if you don't understand it COMPLETELY, and +know EXACTLY what to do without question. + + +STEP 5: SVR4 specific setup + + There is one "gotcha" on System V Release 4 based systems such as +Solaris. These systems do not use the standard UNIX mail format, but rather a +variant of that format that depends upon a bogus "Content-Length:" message +header. This is widely recognized to have been a terrible mistake. One +symptom of the problem is that under certain circumstances, a message may get +broken up into several messages. I'm also aware of security bugs caused by +programs that foolishly trust "Content-Length:" headers with evil values. + + To fix your system, edit your sendmail.cf to 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 + + WIN32 BUILD NOTES + + Visual C++ 6.0 along with the current Microsoft Platform SDK +(specifically the CORE SDK and the Internet Development SDK) is required +to build on Windows 9x/Me/NT/2K/XP. If you do not have the Platform SDK +installed or in your path properly, you'll get errors when building os_nt.c, +typically in env_nt.c, ssl_nt.c, ssl_w2k.c, or gss_shim.c. You can download +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 +now, so you have a clue about how to hack it. + + To build under Windows 95/98/NT, connect to the imap-2007 directory +and do: + nmake -f makefile.nt +The resulting binaries will support SSL if either schannel.dll or +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 +and do: + nmake -f makefile.ntk +The resulting binaries will support SSL if either schannel.dll or +security.dll is installed in Windows, using the old, undocumented SSL +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 +and do: + nmake -f makefile.w2k +The resulting binaries will support SSL and Microsoft Kerberos, using the +official, documented, Microsoft interfaces. Note, however, that these +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 + + These servers are stdio servers. I wrote a simple network listener +for NT called inetlisn; currently it is available as: + ftp://ftp.cac.washington.edu/mail/nt/inetlisn.tar +To build this, use "nmake" after connecting to the inetlisn directory. +inetlisn takes two arguments, the first being the port number and the second +being the binary to run to serve a connection on that port, e.g. + c:\bin\inetlisn 143 c:\mail_daemons\imapd + + Note that NT imapd must be started as SYSTEM in order to be recognized as +being "not logged in"; otherwise it will preauth as whatever user it is +running as which is probably not what you want. One way to have it run as +system is to have inetlisn run by an AT command, e.g. if the time now is +2:05PM, try something like: + AT 14:06 "c:\bin\inetlisn 143 c:\mail_daemons\imapd" + + A more advanced network listener called wsinetd is available on: + http://wsinetd.sourceforge.net +It is based on inetlisn, and essentially is a "completed" version of inetlisn. + + Bottom line: this is not plug-and-play. If you're not a hacker and/or +are unwilling to invest the time to do some programming, you probably want to +buy a commercial server product. + + INACTIVE 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. + + + TOPS-20 BUILD NOTES + + I have provided a c-client port for TOPS-20 systems, but you're on your +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 +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 +that. The command: + DO BUILD.CTL +will build the sources. If you don't have MIC, then SUBMIT BUILD.CTL and let +BATCON execute it. + + + VMS BUILD NOTES + + The VMS port has been tested with imap-2007, 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 +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. +The command to build it is: + @BUILD MULTINET +or @BUILD NETLIB +If you just do @BUILD it will build with dummy TCP code, and since only TCP +based drivers are provided here this isn't too useful. + + If you aren't on the Pacific coast of the US or Canada, you probably will +need to change the wired-in timezone in the BUILD.COM file. Apparently, the +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 + + This port is for the old Mac OS system, not Mac OS X. + + 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 +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 +that. mtext.sit.hqx is a THINK C project file and cute icon for building +mtest, encoded with Binhex and StuffIt. + + THINK C is a truly wretched product which help make me understand why +Macintosh has lost most of its market share. Not only does it do cretinous +things such as barf about a cast in front of an lvalue, it also limits the size +of code *or* data in a single file to 32K! So much for having large character +set tables. Symantec says that "MacOS requires it, break up your files into +smaller pieces" yet somehow gcc under MachTen contrives to compile C programs +without subjecting the programmer to this idiocy. + + As a result of this, I found myself obliged to comment out the #includes +of the East Asian character sets in utf8.c in order to get it to build. It's +also necessary to break up some of the files, at least mail.c and imap4r1.c. +Maybe you don't have to do this in CodeWarrior or whatever the new compiler is +called, but I've pretty much given up on Macintosh. + + If you use precompiled headers, you may get some compilation errors since +some Apple symbols need to be redefined in order to get it to build under all +versions of MacOS. Try turning off the precompiled headers (so it will +re-read the .h files) and see if it builds any better. + + If you use a Mac C compiler with 2-byte ints (such as THINK C's normal +mode) you will need to fix some bugs in the MacTCP C includes and libraries to +prevent it from generating bad code, since those MacTCP files violate Apple's +standards of always using explicit shorts or longs, never ints. You could +avoid this if you set 4-byte ints in THINK C; however, the ANSI and UNIX +libraries in THINK C use 2-byte ints so you will also need to build 4-byte int +versions of these. c-client itself is 2-byte int or 4-byte int clean; it can +be used in either mode. + + The most important bug in the MacTCP files that you need to fix is in the +file AddressXlation.h, you need to change the definition of the rtnCode member +of the hostInfo structure to be long instead of int. There are several other +changes you need to make if you decide to compile dnr.c under THINK C instead +of using the Apple-supplied object file; see me for details if you decide to +undertake such an effort. This is fixed in newer versions from Apple. + + + DOS/WIN16 BUILD NOTES + + If you are building a DOS client, you will need a TCP/IP stack installed +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 +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. +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) +to build for Winsock. + + If you write a program for DOS/Win16, you will probably have to write a +replacement cache manager (look at mm_cache()) and otherwise disable most of +c-client's caching. Even so, memory limitations will be an ongoing problem, +particularly with DOS, and you will have some severe performance problems. +It's a bit better on Win16, but in my opinion you are better off writing a +32-bit program and telling your Win16 customers to upgrade to Windows 95 or at +least install Win32s. + + + WINDOWS CE BUILD NOTES + + 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: + nmake -f makefile.wce + + The only binary produced is a cclient.lib file. I haven't gotten as far +as building mtest on WCE, mainly because I don't have a stdlib library. + + + AMIGA BUILD AND INSTALLATION NOTES + + The Amiga port was contributed. Maybe the UNIX notes will help. + + + OS2 BUILD NOTES + + The OS2 port was contributed. Maybe the Win32 Build Notes will help. diff --git a/imap/docs/CONFIG b/imap/docs/CONFIG new file mode 100644 index 00000000..01ae71f9 --- /dev/null +++ b/imap/docs/CONFIG @@ -0,0 +1,181 @@ +/* ======================================================================== + * Copyright 1988-2006 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 + * + * + * ======================================================================== + */ + + UNIX Configuration Notes + + The IMAP and POP3 servers are plug-and-play on standard UNIX +systems. There is no special configuration needed. Please ignore all +rumors to the effect that you need to create an IMAP configuration +file. + + If your system is non-standard, virtually everything that you are +likely to want to modify can be found in the source file + .../src/osdep/unix/env_unix.c +In particular, special attention should be given to the routines: + env_init() initialize c-client environment variables, + especially the user name and home directory + sysinbox() return the UNIX path of the INBOX in which + mail delivery will place mail + mailboxdir() translate a mailbox name into the associated + UNIX directory for listing + mailboxfile() translate a mailbox name into the associated + UNIX file for opening + + There are also build options in the top-level makefile which you +can give on the command line when building the software. The most +common build options are "SSLTYPE=unix", to build the software with SSL, +and "SSLTYPE=nopwd", to build the software with SSL and disable plaintext +authentication unless the session is encrypted. + + You should modify these routines as necessary for local policy. +The most common modifications are to env_init(), to modify the +software's idea of the home directory (which is used everywhere as the +default directory), and to sysinbox(), to modify where the software +looks for newly-delivered mail. + + Example 1: suppose your mailer delivers mail to file ".mailbox" +in the user's home directory instead of the default UNIX mail spool +directory. You will want to change routine sysinbox(), changing the +line that reads: + + sprintf (tmp,"%s/%s",MAILSPOOL,myusername ()); +to be: + sprintf (tmp,"%s/.mailbox",myhomedir ()); + + Example 2: suppose you want to change c-client's idea of the +user's mailbox directory to be the "mail" subdirectory of the user's +home directory instead of the user's home directory. You will want to +change variable mailsubdir, changing the line that reads: + +static char *mailsubdir = NIL; /* mail subdirectory name */ + to be: +static char *mailsubdir = "mail";/* mail subdirectory name */ + + Example 3: suppose you want to disable plaintext authentication in +the IMAP and POP servers. If you want to disable plaintext authentication +in unencrypted sessions but permit it in encrypted sessions, you should use +"SSLTYPE=nopwd" in the make command line when building the software. For +example, to do this on a Linux system with PAM authentication, do: + make lnp SSLTYPE=nopwd +If you want to disable plaintext authentication under all circumstances +(including SSL or TLS encrypted sessions), use "PASSWDTYPE=nul", e.g.: + make lnx EXTRAAUTHENTICATORS=gss PASSWDTYPE=nul +which will make it impossible to log in except via Kerberos. + + Example 4: suppose you want the IMAP and POP servers to do a chroot() +to the user's home directory. This is not recommended; there are known +ways of attacking chroot() based security mechanisms. Furthermore, if you +do this you can not use a traditional UNIX format INBOX in the mail spool +directory, since chroot() will prevent access to that directory. If you +really want to do this, you need to change variable closedBox, changing +the line which reads: + +static short closedBox = NIL; /* is a closed box */ + to be: +static short closedBox = T; /* is a closed box */ + + Example 5: suppose you want to disable non-namespace access to the +filesystem root and other users' names, but do not want to go to the +extreme of chroot() and you want to allow access to a traditional UNIX +format INBOX in the mail spool directory. You need to change variable +restrictBox, changing the line which reads: + +static short restrictBox = NIL; /* is a restricted box */ + to be: +static short restrictBox = -1; /* is a restricted box */ + +Other values to set in restrictBox can be found in env_unix.h. + + Ignore all references in env_unix.c to a configuration file; that +code is for UW-internal use only. It is extremely unlikely that that +facility will work usefully for you; it is extremely likely that you +will shoot yourself in the foot by using; and it frequently changes in +an incompatible manner. + + There are two other build-time configuration issues which you may +need to consider: drivers and authenticators. Both of these are set +up in the top-level Makefile -- in particular, by the EXTRADRIVERS and +EXTRAAUTHENTICATORS variables. + + Drivers are code modules that support different mailbox storage +technologies. By default, all drivers are enabled. There is little +benefit to be gained by disabling a driver, with one exception. The +mbox driver implements the behavior of automatically moving new mail +from the spool directory to the "mbox" file on the user's home +directory, if and *only* if the "mbox" exists and is in mailbox +format. The mbox driver is listed under EXTRADRIVERS; if you wish to +disable it just remove it from that list and rebuild. + + Authenticators are code modules that support authentication +technology for the server (password file lookup, Kerberos, S/Key, +etc.). EXTRAAUTHENTICATORS is used to add an authenticator. This +subject can be complex; find a wizard if you can't figure it out. + + It is also possible to add your own drivers and authenticators. +This is a topic for wizards, and is beyond the scope of this text. + + NT Configuration Notes + + This software is not plug-and-play on NT. If you're not a hacker +and/or are unwilling to invest the time to do some programming, you +probably want to buy a commercial server for NT. + + The primary issue that you need to deal with is the format of +mail, where the INBOX is located, and where secondary folders are +located. As distributed, the software supports mail in the default +format used on UNIX (unix format) as well as mbx, mtx, and tenex +formats. mbx format is encouraged if at all possible; mtx and tenex +format are for compatibility with the past. However, it all depends +upon how and where your SMTP server delivers mail. + + To change the default mailbox format, edit the symbol +DEFAULTDRIVER in: + ../src/osdep/nt/makefile.nt +or + ../src/osdep/nt/makefile.ntk +To change the default location of INBOX, edit the file: + ../src/osdep/nt/mailfile.h +Virtually everything else having to do with environment that you are +likely to want to modify can be found in the source file: + .../src/osdep/nt/env_nt.c +In particular, special attention should be given to the routines: + env_init() initialize c-client environment variables, + especially the user name and home directory + sysinbox() return the NT path of the INBOX in which + mail delivery will place mail + mailboxdir() translate a mailbox name into the associated + NT directory for listing + mailboxfile() translate a mailbox name into the associated + NT file for opening + + You should modify these routines as necessary. The most common +modifications are to env_init(), to modify the software's idea of the +home directory (which is used everywhere as the default directory), +and to sysinbox(), to modify where the software looks for +newly-delivered mail. + + There are two other build-time configuration issues which you may +need to consider: drivers and authenticators. Both of these are set +up in the top-level Makefile -- in particular, by the EXTRADRIVERS and +EXTRAAUTHENTICATORS variables. + + Drivers are code modules that support different mailbox storage +technologies. By default, all drivers are enabled. There is little +benefit to be gained by disabling a driver. + + Authenticators are code modules that support authentication +technology for the server (password file lookup, Kerberos, S/Key, +etc.). EXTRAAUTHENTICATORS is used to add an authenticator. This +subject can be complex; find a wizard if you can't figure it out. + + It is also possible to add your own drivers and authenticators. diff --git a/imap/docs/FAQ.html b/imap/docs/FAQ.html new file mode 100644 index 00000000..12a9feac --- /dev/null +++ b/imap/docs/FAQ.html @@ -0,0 +1,4226 @@ +<!-- + * ======================================================================== + * 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 + * + * + * ======================================================================== + * +--> + +<!--chtml set title="IMAP Toolkit Frequently Asked Questions"--> +<!--chtml include "//imap/incs/top.inc"--> + + <h2>Table of Contents</h2> + + <ul> + <li> + <a href="#general">1. General/Software Feature Questions</a> + + <ul> + <li><a href="#1.1">1.1 Can I set up a POP or IMAP server on + UNIX/Linux/OSF/etc.?</a></li> + + <li><a href="#1.2">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?</a></li> + + <li><a href="#1.3">1.3 Can I set up a POP or IMAP server on Windows + XP, 2000, NT, Me, 98, or 95?</a></li> + + <li><a href="#1.4">1.4 Can I set up a POP or IMAP server on Windows + 3.1 or DOS?</a></li> + + <li><a href="#1.5">1.5 Can I set up a POP or IMAP server on + Macintosh?</a></li> + + <li><a href="#1.6">1.6 Can I set up a POP or IMAP server on + VAX/VMS?</a></li> + + <li><a href="#1.7">1.7 Can I set up a POP or IMAP server on + TOPS-20?</a></li> + + <li><a href="#1.8">1.8 Are hierarchical mailboxes supported?</a></li> + + <li><a href="#1.9">1.9 Are "dual-use" mailboxes supported?</a></li> + + <li><a href="#1.10">1.10 Can I have a mailbox that has both messages + and sub-mailboxes?</a></li> + + <li><a href="#1.11">1.11 What is the difference between "mailbox" and + "folder"?</a></li> + + <li><a href="#1.12">1.12 What is the status of + internationalization?</a></li> + + <li><a href="#1.13">1.13 Can I use SSL?</a></li> + + <li><a href="#1.14">1.14 Can I use TLS and the STARTTLS + facility?</a></li> + + <li><a href="#1.15">1.15 Can I use CRAM-MD5 authentication?</a></li> + + <li><a href="#1.16">1.16 Can I use APOP authentication?</a></li> + + <li><a href="#1.17">1.17 Can I use Kerberos V5?</a></li> + + <li><a href="#1.18">1.18 Can I use PAM for plaintext + passwords?</a></li> + + <li><a href="#1.19">1.19 Can I use Kerberos 5 for plaintext + passwords?</a></li> + + <li><a href="#1.20">1.20 Can I use AFS for plaintext + passwords?</a></li> + + <li><a href="#1.21">1.21 Can I use DCE for plaintext + passwords?</a></li> + + <li><a href="#1.22">1.22 Can I use the CRAM-MD5 database for + plaintext passwords?</a></li> + + <li><a href="#1.23">1.23 Can I disable plaintext passwords?</a></li> + + <li><a href="#1.24">1.24 Can I disable plaintext passwords on + unencrypted sessions, but allow them on encrypted sessions?</a></li> + + <li><a href="#1.25">1.25 Can I use virtual hosts?</a></li> + + <li><a href="#1.26">1.26 Can I use RPOP authentication?</a></li> + + <li><a href="#1.27">1.27 Can I use Kerberos V4?</a></li> + + <li><a href="#1.28">1.28 Is there support for S/Key or OTP?</a></li> + + <li><a href="#1.29">1.29 Is there support for NTLM or SPA?</a></li> + + <li><a href="#1.30">1.30 Is there support for mh?</a></li> + + <li><a href="#1.31">1.31 Is there support for qmail and the maildir + format?</a></li> + + <li><a href="#1.32">1.32 Is there support for the Cyrus mailbox + format?</a></li> + + <li><a href="#1.33">1.33 Is this software Y2K compliant?</a></li> + </ul> + </li> + + <li> + <a href="#requirements">2. What Do I Need to Build This Software?</a> + + <ul> + <li><a href="#2.1">2.1 What do I need to build this software with SSL + on UNIX?</a></li> + + <li><a href="#2.2">2.2 What do I need to build this software with + Kerberos V on UNIX?</a></li> + + <li><a href="#2.3">2.3 What do I need to use a C++ compiler with this + software to build my own application?</a></li> + + <li><a href="#2.4">2.4 What do I need to build this software on + Windows?</a></li> + + <li><a href="#2.5">2.5 What do I need to build this software on + DOS?</a></li> + + <li><a href="#2.6">2.6 Can't I use Borland C to build this software + on the PC?</a></li> + + <li><a href="#2.7">2.7 What do I need to build this software on the + Mac?</a></li> + + <li><a href="#2.8">2.8 What do I need to build this software on + VMS?</a></li> + + <li><a href="#2.9">2.9 What do I need to build this software on + TOPS-20?</a></li> + + <li><a href="#2.10">2.10 What do I need to build this software on + Amiga or OS/2?</a></li> + + <li><a href="#2.11">2.11 What do I need to build this software on + Windows CE?</a></li> + </ul> + </li> + + <li> + <a href="#build">3. Build and Configuration Questions</a> + + <ul> + <li><a href="#3.1">3.1 How do I configure the IMAP and POP servers on + UNIX?</a></li> + + <li><a href="#3.2">3.2 I built and installed the servers according to + the BUILD instructions. It can't be that easy. Don't I need to write + a config file?</a></li> + + <li><a href="#3.3">3.3 How do I make the IMAP and POP servers look + for INBOX at some place other than the mail spool directory?</a></li> + + <li><a href="#3.4">3.4 How do I make the IMAP server look for + secondary folders at some place other than the user's home + directory?</a></li> + + <li><a href="#3.5">3.5 How do I configure SSL?</a></li> + + <li><a href="#3.6">3.6 How do I configure TLS and the STARTTLS + facility?</a></li> + + <li><a href="#3.7">3.7 How do I build/install OpenSSL and + obtain/create certificates for use with SSL?</a></li> + + <li><a href="#3.8">3.8 How do I configure CRAM-MD5 + authentication?</a></li> + + <li><a href="#3.9">3.9 How do I configure APOP + authentication?</a></li> + + <li><a href="#3.10">3.10 How do I configure Kerberos V5?</a></li> + + <li><a href="#3.11">3.11 How do I configure PAM for plaintext + passwords?</a></li> + + <li><a href="#3.12">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?</a></li> + + <li><a href="#3.13">3.13 How do I configure Kerberos 5 for plaintext + passwords?</a></li> + + <li><a href="#3.14">3.14 How do I configure AFS for plaintext + passwords?</a></li> + + <li><a href="#3.15">3.15 How do I configure DCE for plaintext + passwords?</a></li> + + <li><a href="#3.16">3.16 How do I configure the CRAM-MD5 database for + plaintext passwords?</a></li> + + <li><a href="#3.17">3.17 How do I disable plaintext + passwords?</a></li> + + <li><a href="#3.18">3.18 How do I disable plaintext passwords on + unencrypted sessions, but allow them in SSL or TLS sessions?</a></li> + + <li><a href="#3.19">3.19 How do I configure virtual hosts?</a></li> + + <li> + <a href="#3.20">3.20 Why do I get compiler warning messages such + as: + + <ul> + <li>passing arg 3 of `scandir' from incompatible pointer + type</li> + + <li>Pointers are not assignment-compatible.</li> + + <li>Argument #4 is not the correct type.</li> + </ul>during the build?</a> + </li> + + <li> + <a href="#3.21">3.21 Why do I get compiler warning messages such + as + + <ul> + <li>Operation between types "void(*)(int)" and "void*" is not + allowed.</li> + + <li>Function argument assignment between types "void*" and + "void(*)(int)" is not allowed.</li> + + <li>Pointers are not assignment-compatible.</li> + + <li>Argument #5 is not the correct type.</li> + </ul>during the build?</a> + </li> + + <li> + <a href="#3.22">3.22 Why do I get linker warning messages such + as: + + <ul> + <li>mtest.c:515: the `gets' function is dangerous and should not + be used.</li> + </ul>during the build? Isn't this a security bug?</a> + </li> + + <li> + <a href="#3.23">3.23 Why do I get linker warning messages such + as:</a> + + <ul> + <li>auth_ssl.c:92: the `tmpnam' function is dangerous and should + not be used.</li> + </ul>during the build? Isn't this a security bug? + </li> + + <li><a href="#3.24">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?</a></li> + </ul> + </li> + + <li> + <a href="#operation">4. Operational Questions</a> + + <ul> + <li><a href="#4.1">4.1 How can I enable anonymous IMAP + logins?</a></li> + + <li><a href="#4.2">4.2 How do I set up an alert message that each + IMAP user will see?</a></li> + + <li><a href="#4.3">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 noticed that it can connect on port 143, port 993, via rsh, + and via ssh.</a></li> + + <li><a href="#4.4">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?</a></li> + + <li><a href="#4.5">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 + access.</a></li> + + <li><a href="#4.6">4.6 How do I set up shared mailboxes?</a></li> + + <li><a href="#4.7">4.7 How can I make the server syslogs go to + someplace other than the mail syslog?</a></li> + </ul> + </li> + + <li> + <a href="#security">5. Security Questions</a> + + <ul> + <li><a href="#5.1">5.1 I see that the IMAP server allows access to + arbitary files on the system, including /etc/passwd! How do I disable + this?</a></li> + + <li><a href="#5.2">5.2 I've heard that IMAP servers are insecure. Is + this true?</a></li> + + <li><a href="#5.3">5.3 How do I know that I have the most secure + version of the server?</a></li> + + <li><a href="#5.4">5.4 I see all these strcpy() and sprintf() calls, + those are unsafe, aren't they?</a></li> + + <li><a href="#5.5">5.5 Those /tmp lock files are protected 666, is + that really right?</a></li> + </ul> + </li> + + <li> + <a href="#strange">6. <i>Why Did You Do This Strange Thing?</i> + Questions</a> + + <ul> + <li><a href="#6.1">6.1 Why don't you use GNU autoconfig / automake / + autoblurdybloop?</a></li> + + <li><a href="#6.2">6.2 Why do you insist upon a build with -g? + Doesn't it waste disk and memory space?</a></li> + + <li><a href="#6.3">6.3 Why don't you make c-client a shared + library?</a></li> + + <li><a href="#6.4">6.4 Why don't you use iconv() for + internationalization support?</a></li> + + <li><a href="#6.5">6.5 Why is the IMAP server connected to the home + directory by default?</a></li> + + <li><a href="#6.6">6.6 I have a Windows system. Why isn't the server + plug and play for me?</a></li> + + <li><a href="#6.7">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 the full size?</a></li> + + <li><a href="#6.8">6.8 Why is an mh format INBOX called #mhinbox + instead of just INBOX?</a></li> + + <li><a href="#6.9">6.9 Why don't you support the maildir + format?</a></li> + + <li><a href="#6.10">6.10 Why don't you support the Cyrus + format?</a></li> + + <li><a href="#6.11">6.11 Why is it creating extra forks on my SVR4 + system?</a></li> + + <li><a href="#6.12">6.12 Why are you so fussy about the date/time + format in the internal <code>"From "</code> line in traditional + UNIX mailbox files? My other mail program just considers every line + that starts with <code>"From "</code> to be the start of the + message.</a></li> + + <li><a href="#6.13">6.13 Why is traditional UNIX format the default + format?</a></li> + + <li><a href="#6.14">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?</a></li> + + <li><a href="#6.15">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?</a></li> + + <li><a href="#6.16">6.16 Why aren't "dual-use" mailboxes the + default?</a></li> + + <li><a href="#6.17">6.17 Why do you use ucbcc to build on + Solaris?</a></li> + + <li><a href="#6.18">6.18 Why should I care about some old system with + BSD libraries? cc is the right thing on my Solaris system!</a></li> + + <li><a href="#6.19">6.19 Why do you insist upon writing .lock files + in the spool directory?</a></li> + + <li><a href="#6.20">6.20 Why should I care about compatibility with + the past?</a></li> + </ul> + </li> + + <li> + <a href="#problems">7. Problems and Annoyances</a> + + <ul> + <li><a href="#7.1">7.1 Help! My INBOX is empty! What happened to my + messages?</a></li> + + <li><a href="#7.2">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?</a></li> + + <li> + <a href="#7.3">7.3 Why do I get the message: + + <ul> + <li>CREATE failed: Can't create mailbox node xxxxxxxxx: File + exists</li> + </ul>and how do I fix it?</a> + </li> + + <li><a href="#7.4">7.4 Why can't I log in to the server? The user + name and password are right!</a></li> + + <li><a href="#7.5">7.5 Help! My load average is soaring and I see + hundreds of POP and IMAP servers, many logged in as the same + user!</a></li> + + <li><a href="#7.6">7.6 Why does mail disappear even though I set + "keep mail on server"?</a></li> + + <li> + <a href="#7.7">7.7 Why do I get the message + + <ul> + <li>Moved ##### bytes of new mail to /home/user/mbox from + /var/spool/mail/user</li> + </ul>and why did this happen?</a> + </li> + + <li><a href="#7.8">7.8 Why isn't it showing the local host name as a + fully-qualified domain name?</a></li> + + <li><a href="#7.9">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?</a></li> + + <li> + <a href="#7.10">7.10 What does the message: + + <ul> + <li>Mailbox vulnerable - directory /var/spool/mail must have 1777 + protection</li> + </ul>mean? How can I fix this?</a> + </li> + + <li> + <a href="#7.11">7.11 What does the message: + + <ul> + <li>Mailbox is open by another process, access is readonly</li> + </ul>mean? How do I fix this?</a> + </li> + + <li> + <a href="#7.12">7.12 What does the message: + + <ul> + <li>Can't get write access to mailbox, access is readonly</li> + </ul>mean?</a> + </li> + + <li><a href="#7.13">7.13 I set my POP3 client to "delete messages + from server" but they never get deleted. What is wrong?</a></li> + + <li> + <a href="#7.14">7.14 What do messages such as: + + <ul> + <li>Message ... UID ... already has UID ...</li> + + <li>Message ... UID ... less than ...</li> + + <li>Message ... UID ... greater than last ...</li> + + <li>Invalid UID ... in message ..., rebuilding UIDs</li> + </ul>mean?</a> + </li> + + <li> + <a href="#7.15">7.15 What do the error messages: + + <ul> + <li>Unable to read internal header at ...</li> + + <li>Unable to find CRLF at ...</li> + + <li>Unable to parse internal header at ...</li> + + <li>Unable to parse message date at ...</li> + + <li>Unable to parse message flags at ...</li> + + <li>Unable to parse message UID at ...</li> + + <li>Unable to parse message size at ...</li> + + <li>Last message (at ... ) runs past end of file ...</li> + </ul>mean? I am using mbx format.</a> + </li> + + <li> + <a href="#7.16">7.16 What do the syslog messages: + + <ul> + <li>imap/tcp server failing (looping)</li> + + <li>pop3/tcp server failing (looping)</li> + </ul>mean? When it happens, the listed service shuts down. How can + I fix this?</a> + </li> + + <li> + <a href="#7.17">7.17 What does the syslog message: + + <ul> + <li>Mailbox lock file /tmp/.600.1df3 open failure: Permission + denied</li> + </ul>mean?</a> + </li> + + <li> + <a href="#7.18">7.18 What do the syslog messages: + + <ul> + <li>Command stream end of file, while reading line user=... + host=...</li> + + <li>Command stream end of file, while reading char user=... + host=...</li> + + <li>Command stream end of file, while writing text user=... + host=...</li> + </ul>mean?</a> + </li> + + <li> + <a href="#7.19">7.19 Why did my POP or IMAP session suddenly + disconnect? The syslog has the message: + + <ul> + <li>Killed (lost mailbox lock) user=... host=...</li> + </ul></a> + </li> + + <li><a href="#7.20">7.20 Why does my IMAP client show all the files + on the system, recursively from the UNIX root directory?</a></li> + + <li><a href="#7.21">7.21 Why does my IMAP client show all of my + files, recursively from my UNIX home directory?</a></li> + + <li><a href="#7.22">7.22 Why does my IMAP client show that I have + mailboxes named "#mhinbox", "#mh", "#shared", "#ftp", "#news", and + "#public"?</a></li> + + <li><a href="#7.23">7.23 Why does my IMAP client show all my files in + my home directory?</a></li> + + <li><a href="#7.24">7.24 Why is there a long delay before I get + 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 + 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().</a></li> + + <li><a href="#7.26">7.26 Why does a message sometimes get split into + two or more messages on my SUN system?</a></li> + + <li> + <a href="#7.27">7.27 Why did my POP or IMAP session suddenly + disconnect? The syslog has the message: + + <ul> + <li>Autologout user=<...my user name...> host=<...my + imap server...></li> + </ul></a> + </li> + + <li> + <a href="#7.28">7.28 What does the UNIX error message: + + <ul> + <li>TLS/SSL failure: myserver: SSL negotiation failed</li> + </ul>mean?</a> + </li> + + <li> + <a href="#7.29">7.29 What does the PC error message: + + <ul> + <li>TLS/SSL failure: myserver: Unexpected TCP input + disconnect</li> + </ul>mean?</a> + </li> + + <li> + <a href="#7.30">7.30 What does the error message: + + <ul> + <li>TLS/SSL failure: myserver: Server name does not match + certificate</li> + </ul>mean?</a> + </li> + + <li> + <a href="#7.31">7.31 What does the UNIX error message: + + <ul> + <li>TLS/SSL failure: myserver: self-signed certificate</li> + </ul>mean?</a> + </li> + + <li> + <a href="#7.32">7.32 What does the PC error message + + <ul> + <li>TLS/SSL failure: myserver: Self-signed certificate or + untrusted authority</li> + </ul>mean?</a> + </li> + + <li> + <a href="#7.33">7.33 What does the UNIX error message: + + <ul> + <li>TLS/SSL failure: myserver: unable to get local issuer + certificate</li> + </ul>mean?</a> + </li> + + <li><a href="#7.34">7.34 Why does reading certain messages hang when + using Netscape? It works fine with Pine!</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 + administrator."?</a></li> + + <li><a href="#7.36">7.36 Why is one user creating huge numbers of + IMAP or POP server sessions?</a></li> + + <li><a href="#7.37">7.37 Why don't I get any new mail notifications + from Outlook Express or Outlook after a while?</a></li> + + <li><a href="#7.38">7.38 Why don't I get any new mail notifications + from Entourage?</a></li> + + <li><a href="#7.39">7.39 Why doesn't Entourage work at all?</a></li> + + <li><a href="#7.40">7.40 Why doesn't Netscape Notify (NSNOTIFY.EXE) + work at all?</a></li> + + <li><a href="#7.41">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 file".</a></li> + + <li><a href="#7.42">7.42 Sheesh. Aren't there <i>any</i> good IMAP + clients out there?</a></li> + + <li> + <a href="#7.43">7.43 But wait! PC Pine (or other PC program build + with c-client) crashes with the message + + <ul> + <li>incomplete SecBuffer exceeds maximum buffer size</li> + </ul>when I use SSL connections. This is a bug in c-client, right?</a> + </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 + IMAP. How can I fix this?</a></li> + + <li><a href="#7.45">7.45 Help! I installed the servers but I can't + connect to them from my client!</a></li> + + <li> + <a href="#7.46">7.46 Why do I get the message + + <ul> + <li>Can not authenticate to SMTP server: 421 SMTP connection went + away!</li> + </ul>and why did this happen? There was also something about + + <ul> + <li>SECURITY PROBLEM: insecure server advertised AUTH=PLAIN</li> + </ul></a> + </li> + + <li> + <a href="#7.47">7.47 Why do I get the message + + <ul> + <li>SMTP Authentication cancelled</li> + </ul>and why did this happen? There was also something about + + <ul> + <li>SECURITY PROBLEM: insecure server advertised AUTH=PLAIN</li> + </ul></a> + </li> + + <li> + <a href="#7.48">7.48 Why do I get the message + + <ul> + <li>Invalid base64 string</li> + </ul>when I try to authenticate to a Cyrus server? + </li></a> + </ul> + </li> + + <li> + <a href="#additional">8. Where to Go For Additional Information</a> + + <ul> + <li><a href="#8.1">8.1 Where can I go to ask questions?</a></li> + + <li><a href="#8.2">8.2 I have some ideas for enhancements to IMAP. + Where should I go?</a></li> + + <li><a href="#8.3">8.3 Where can I read more about IMAP and other + email protocols?</a></li> + + <li><a href="#8.4">8.4 Where can I find out more about setting up and + administering an IMAP server?</a></li> + </ul> + </li> + </ul><!--=======START BODY--> + <hr> + + <h2><a name="general">1. General/Software Feature Questions</a></h2> + <hr> + + <p><a name="1.1"><strong>1.1 Can I set up a POP or IMAP server on + UNIX/Linux/OSF/etc.?</strong></a></p> + + <dl> + <dd>Yes. Refer to the UNIX specific notes in files CONFIG and BUILD.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.2"><strong>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?</strong></a></p> + + <dl> + <dd> + Not necessarily. + + <p>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.</p> + + <p>If you are happy with qpopper and just want to add imapd, you should + do that, and defer a decision on changing qpopper to ipop3d. That way, + you can get comfortable with imapd's performance, without changing + anything for your qpopper users.</p> + + <p>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 <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> + question.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.3"><strong>1.3 Can I set up a POP or IMAP server on Windows XP, + 2000, NT, Me, 98, or 95?</strong></a></p> + + <dl> + <dd> + 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 md5.txt. + + <p>There is no file access control on Windows 9x or Me, so you probably + will have to do modifications to env_unix.c to prevent people from + hacking others' mail.</p> + + <p>Note, however, that the server is not plug and play the way it is + for UNIX.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.4"><strong>1.4 Can I set up a POP or IMAP server on Windows 3.1 or + DOS?</strong></a><br> + <a name="1.5"><strong>1.5 Can I set up a POP or IMAP server on + Macintosh?</strong></a><br> + <a name="1.6"><strong>1.6 Can I set up a POP or IMAP server on + VAX/VMS?</strong></a></p> + + <dl> + <dd>Yes, it's just a small matter of programming.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.7"><strong>1.7 Can I set up a POP or IMAP server on + TOPS-20?</strong></a></p> + + <dl> + <dd> + You have a TOPS-20 system? Cool. + + <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 + 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> + + <p>We don't know if anyone wrote a POP3 server for TOPS-20. There + definitely was a POP2 server once upon a time.</p> + + <p>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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.8"><strong>1.8 Are hierarchical mailboxes + supported?</strong></a><br> + <a name="1.9"><strong>1.9 Are "dual-use" mailboxes + supported?</strong></a><br> + <a name="1.10"><strong>1.10 Can I have a mailbox that has both messages and + sub-mailboxes?</strong></a></p> + + <dl> + <dd> + Yes. However, there is one important caveat. + + <p>Some mailbox formats, including the default which is the traditional + UNIX mailbox format, are stored as a single file containing all the + messages. UNIX does not permit a name in the filesystem to be both a + file and a directory; consequently you can not have a sub-mailbox + within a mailbox that is in one of these formats.</p> + + <p>This is not a limitation of the software; this is a limitation of + UNIX. For example, there are mailbox formats in which the name is a + 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 + information on this topic.</p> + + <p>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/".</p> + + <p>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.</p> + + <p>Of course, on Windows systems you would use "\" instead of "/".</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.11"><strong>1.11 What is the difference between "mailbox" and + "folder"?</strong></a></p> + + <dl> + <dd> + The term "mailbox" is IMAP-speak for what a lot of software calls a + "folder" or a "mail folder". However, "folder" is often used in other + contexts to refer to a directory, for example, in the graphic user + interface on both Windows and Macintosh. + + <p>A "mailbox" is specifically defined as a named object that contains + messages. It is not required to be capable of containing other types of + objects including other mailboxes; although some mailbox formats will + permit this.</p> + + <p>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 "no-select name".</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.12"><strong>1.12 What is the status of + internationalization?</strong></a></p> + + <dl> + <dd> + The IMAP toolkit is partially internationalized and multilingualized. + + <p>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.</p> + + <p>All ISO-2022-?? charsets are treated identically, and support ASCII, + JIS Roman, hankaku katakana, ISO-8859-[1 - 10], TIS, GB 2312, JIS X + 0208, JIS X 0212, KSC 5601, and planes 1 and 2 of CNS 11643.</p> + + <p>EUC-JP includes support for JIS X 0212 and hankaku katakana.</p> + + <p>c-client library support also exists to convert text in any of the + above charsets into Unicode, including headers with MIME + encoded-words.</p> + + <p>There is no support for localization (e.g. non-English error + messages) at the present time, but such support is planned.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.13"><strong>1.13 Can I use SSL?</strong></a></p> + + <dl> + <dd>Yes. See the answer to the <a href="#3.5">How do I configure SSL?</a> + question.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.14"><strong>1.14 Can I use TLS and the STARTTLS + facility?</strong></a></p> + + <dl> + <dd>Yes. See the answer to the <a href="#3.6">How do I configure TLS and + the STARTTLS facility?</a> question.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.15"><strong>1.15 Can I use CRAM-MD5 + authentication?</strong></a></p> + + <dl> + <dd>Yes. See the answer to the <a href="#3.8">How do I configure CRAM-MD5 + authentication?</a> question.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.16"><strong>1.16 Can I use APOP authentication?</strong></a></p> + + <dl> + <dd> + Yes. See the <a href="#3.9">How do I configure APOP authentication?</a> + question. + + <p>Note that there is no client support for APOP authentication.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.17"><strong>1.17 Can I use Kerberos V5?</strong></a></p> + + <dl> + <dd>Yes. See the answer to the <a href="#3.10">How do I configure + Kerberos V5?</a> question.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.18"><strong>1.18 Can I use PAM for plaintext + passwords?</strong></a></p> + + <dl> + <dd>Yes. See the answer to the <a href="#3.11">How do I configure PAM for + plaintext passwords?</a> question.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.19"><strong>1.19 Can I use Kerberos 5 for plaintext + passwords?</strong></a></p> + + <dl> + <dd>Yes. See the answer to the <a href="#3.13">How do I configure + Kerberos 5 for plaintext passwords?</a> question.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.20"><strong>1.20 Can I use AFS for plaintext + passwords?</strong></a></p> + + <dl> + <dd>Yes. See the answer to the <a href="#3.14">How do I configure AFS for + plaintext passwords?</a> question.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.21"><strong>1.21 Can I use DCE for plaintext + passwords?</strong></a></p> + + <dl> + <dd>Yes. See the answer to the <a href="#3.15">How do I configure DCE for + plaintext passwords?</a> question.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.22"><strong>1.22 Can I use the CRAM-MD5 database for plaintext + passwords?</strong></a></p> + + <dl> + <dd>Yes. See the answer to the <a href="#3.16">How do I configure the + CRAM-MD5 database for plaintext passwords?</a> question.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.23"><strong>1.23 Can I disable plaintext + passwords?</strong></a></p> + + <dl> + <dd>Yes. See the answer to the <a href="#3.17">How do I disable plaintext + passwords?</a> question.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.24"><strong>1.24 Can I disable plaintext passwords on unencrypted + sessions, but allow them on encrypted sessions?</strong></a></p> + + <dl> + <dd>Yes. See the answer to the <a href="#3.18">How do I disable plaintext + passwords on unencrypted sessions, but allow them in SSL or TLS + sessions?</a> question.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.25"><strong>1.25 Can I use virtual hosts?</strong></a></p> + + <dl> + <dd>Yes. See the answer to the <a href="#3.19">How do I configure virtual + hosts?</a> question.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.26"><strong>1.26 Can I use RPOP authentication?</strong></a></p> + + <dl> + <dd>There is no support for RPOP authentication.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.27"><strong>1.27 Can I use Kerberos V4?</strong></a></p> + + <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. + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.28"><strong>1.28 Is there support for S/Key or + OTP?</strong></a></p> + + <dl> + <dd>There is currently no support for S/Key or OTP. There may be an OTP + SASL authenticator available from third parties.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.29"><strong>1.29 Is there support for NTLM or + SPA?</strong></a></p> + + <dl> + <dd> + 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. + + <p>There may be an NTLM SASL authenticator available from third + parties.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.30"><strong>1.30 Is there support for mh?</strong></a></p> + + <dl> + <dd> + Yes, but only as a legacy format. Your mh format INBOX is accessed by + the name "#mhinbox", and all other mh format mailboxes are accessed by + prefixing "#mh/" to the name, e.g. "#mh/foo". The mh support uses the + "Path:" entry in your .mh_profile file to identify the root directory + of your mh format mailboxes. + + <p>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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.31"><strong>1.31 Is there support for qmail and the maildir + format?</strong></a></p> + + <dl> + <dd>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.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.32"><strong>1.32 Is there support for the Cyrus mailbox + format?</strong></a></p> + + <dl> + <dd>No.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="1.33"><strong>1.33 Is this software Y2K compliant?</strong></a></p> + + <dl> + <dd>Please read the files Y2K and calendar.txt.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><br></p> + + <h2><a name="requirements">2. What Do I Need to Build This Software?</a></h2> + <hr> + + <p><a name="2.1"><strong>2.1 What do I need to build this software with SSL on + UNIX?</strong></a></p> + + <dl> + <dd>You need to build and install OpenSSL first.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="2.2"><strong>2.2 What do I need to build this software with Kerberos + V on UNIX?</strong></a></p> + + <dl> + <dd>You need to build and install MIT Kerberos first.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="2.3"><strong>2.3 What do I need to use a C++ compiler with this + software to build my own application?</strong></a></p> + + <dl> + <dd> + 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++. + + <p>If you use gcc, you may need to use -fno-operator-names as well.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="2.4"><strong>2.4 What do I need to build this software on + Windows?</strong></a></p> + + <dl> + <dd> + 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). + + <p>You do not need to install the entire Platform SDK; it suffices to + install just the Core SDK and the Internet Development SDK.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="2.5"><strong>2.5 What do I need to build this software on + DOS?</strong></a></p> + + <dl> + <dd>It's been several years since we last attempted to do this. At the + time, we used Microsoft C.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="2.6"><strong>2.6 Can't I use Borland C to build this software on the + PC?</strong></a></p> + + <dl> + <dd>Probably not. If you know otherwise, please let us know.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="2.7"><strong>2.7 What do I need to build this software on the + Mac?</strong></a></p> + + <dl> + <dd>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.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="2.8"><strong>2.8 What do I need to build this software on + VMS?</strong></a></p> + + <dl> + <dd>You need the VMS C compiler, and either the Multinet or Netlib + TCP.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="2.9"><strong>2.9 What do I need to build this software on + TOPS-20?</strong></a></p> + + <dl> + <dd>You need the TOPS-20 KCC compiler.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="2.10"><strong>2.10 What do I need to build this software on Amiga or + OS/2?</strong></a></p> + + <dl> + <dd>We don't know.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="2.11"><strong>2.11 What do I need to build this software on Windows + CE?</strong></a></p> + + <dl> + <dd>This port is incomplete. Someone needs to finish it.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><br></p> + + <h2><a name="build">3. Build and Configuration Questions</a></h2> + <hr> + + <p><a name="3.1"><strong>3.1 How do I configure the IMAP and POP servers on + UNIX?</strong></a><br> + <a name="3.2"><strong>3.2 I built and installed the servers according to the + BUILD instructions. It can't be that easy. Don't I need to write a + config file?</strong></a></p> + + <dl> + <dd> + For ordinary "vanilla" UNIX systems, this software is plug and play; + just build it, install it, and you're done. If you have a modified + system, then you may want to do additional work; most of this is to a + single source code file (env_unix.c on UNIX systems). Read the file + CONFIG for more details. + + <p>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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="3.3"><strong>3.3 How do I make the IMAP and POP servers look for + INBOX at some place other than the mail spool + directory?</strong></a><br> + <a name="3.4"><strong>3.4 How do I make the IMAP server look for secondary + folders at some place other than the user's home + directory?</strong></a></p> + + <dl> + <dd>Please read the file CONFIG for discussion of this and other + issues.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="3.5"><strong>3.5 How do I configure SSL?</strong></a><br> + <a name="3.6"><strong>3.6 How do I configure TLS and the STARTTLS + facility?</strong></a></p> + + <dl> + <dd> + imap-2007 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 + for more information.</p> + + <p>SSL is supported via undocumented Microsoft interfaces in Windows 9x + and NT4; and via standard interfaces in Windows 2000, Windows + Millenium, and Windows XP.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="3.7"><strong>3.7 How do I build/install OpenSSL and obtain/create + certificates for use with SSL?</strong></a></p> + + <dl> + <dd>If you need help in doing this, try the contacts mentioned in the + OpenSSL README. We do not offer support for OpenSSL or certificates.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="3.8"><strong>3.8 How do I configure CRAM-MD5 + authentication?</strong></a><br> + <a name="3.9"><strong>3.9 How do I configure APOP + authentication?</strong></a></p> + + <dl> + <dd> + CRAM-MD5 authentication is enabled in the IMAP and POP3 client code on + all platforms. Read md5.txt to learn how to set up CRAM-MD5 and APOP + authentication on UNIX and NT servers. + + <p>There is no support for APOP client authentication.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="3.10"><strong>3.10 How do I configure Kerberos V5?</strong></a></p> + + <dl> + <dd> + imap-2007 supports client and server functionality on UNIX and 32-bit + Windows. + + <p>Kerberos V5 is supported by default in Windows 2000 builds:</p> + <pre> + nmake -f makefile.w2k +</pre> + + <p>Other builds require that a third-party Kerberos package, e.g. MIT + Kerberos, be installed on the system first.</p> + + <p>To build with Kerberos V5 on UNIX, include EXTRAAUTHENTICATORS=gss + in the make command line, e.g.</p> + <pre> + make lnp EXTRAAUTHENTICATORS=gss +</pre> + + <p>To build with Kerberos V5 on Windows 9x, Windows Millenium, and NT4, + use the "makefile.ntk" file instead of "makefile.nt":</p> + <pre> + + nmake -f makefile.ntk +</pre> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="3.11"><strong>3.11 How do I configure PAM for plaintext + passwords?</strong></a></p> + + <dl> + <dd> + On Linux systems, use the lnp port, e.g. + <pre> + make lnp + +</pre>On Solaris systems and other systems with defective PAM +implementations, build with PASSWDTYPE=pmb, e.g. + <pre> + make sol PASSWDTYPE=pmb +</pre>On all other systems, build with PASSWDTYPE=pam, e.g + <pre> + make foo PASSWDTYPE=pam +</pre>If you build with PASSWDTYPE=pam and authentication does not work, try +rebuilding (after a "make clean") with PASSWDTYPE=pmb. + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="3.12"><strong>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?</strong></a></p> + + <dl> + <dd> + Yes and no. + + <p>Doing this will make plaintext password authentication use the + Kerberos password instead of the /etc/passwd password.</p> + + <p>However, this will NOT give you Kerberos-secure authentication. See + the answer to the <a href="#3.10">How do I configure Kerberos V5?</a> + question for how to build with Kerberos-secure authentication.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="3.13"><strong>3.13 How do I configure Kerberos 5 for plaintext + passwords?</strong></a></p> + + <dl> + <dd> + Build with PASSWDTYPE=gss, e.g. + <pre> + make sol PASSWDTYPE=gss +</pre>However, this will NOT give you Kerberos-secure authentication. See the +answer to the <a href="#3.10">How do I configure Kerberos V5?</a> question +for how to build with Kerberos-secure authentication. + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="3.14"><strong>3.14 How do I configure AFS for plaintext + passwords?</strong></a></p> + + <dl> + <dd> + Build with PASSWDTYPE=afs, e.g + <pre> + make sol PASSWDTYPE=afs + +</pre> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="3.15"><strong>3.15 How do I configure DCE for plaintext + passwords?</strong></a></p> + + <dl> + <dd> + Build with PASSWDTYPE=dce, e.g + <pre> + make sol PASSWDTYPE=dce +</pre> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="3.16"><strong>3.16 How do I configure the CRAM-MD5 database for + plaintext passwords?</strong></a></p> + + <dl> + <dd> + The CRAM-MD5 password database is automatically used for plaintext + password if it exists. + + <p>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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="3.17"><strong>3.17 How do I disable plaintext + passwords?</strong></a></p> + + <dl> + <dd> + Server-level plaintext passwords can be disabled by setting + PASSWDTYPE=nul, e.g. + <pre> + make lnx EXTRAAUTHENTICATORS=gss PASSWDTYPE=nul +</pre>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. + + <p>When plaintext passwords are disabled, the IMAP server will + advertise the LOGINDISABLED capability and the POP3 server will not + advertise the USER capability.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + + <p><a name="3.18"><strong>3.18 How do I disable plaintext passwords on + unencrypted sessions, but allow them in SSL or TLS + sessions?</strong></a></p> + + <dl> + <dd> + <p>Do not set PASSWDTYPE=nul or SSLTYPE=unix. Set SSLTYPE=nopwd + instead, e.g.</p> + <pre> + make lnx SSLTYPE=nopwd +</pre> + + <p>When plaintext passwords are disabled, the IMAP server will + advertise the LOGINDISABLED capability and the POP3 server will not + advertise the USER capability.</p> + + <p>Plaintext passwords will always be enabled in SSL sessions; the IMAP + server will not advertise the LOGINDISABLED capability and the POP3 + server will advertise the USER capability.</p> + + <p>If the client does a successful start-TLS in a non-SSL session, + 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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="3.19"><strong>3.19 How do I configure virtual + hosts?</strong></a></p> + + <dl> + <dd> + This is automatic, but with certain restrictions. + + <p>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.</p> + + <p>As distributed, the software uses a global password file; hence user + "fred" on one virtual host is "fred" on all virtual hosts. You may want + to modify the checkpw() routine to implement some other policy (e.g. + separate password files).</p> + + <p>Note that the security model assumes that all users have their own + unique UNIX UID number. So if you use separate password files you + should make certain that the UID numbers do not overlap between + different files.</p> + + <p>More advanced virtual host support may be available as patches from + third parties.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="3.20"><strong>3.20 Why do I get compiler warning messages such + as:</strong></a></p> + <pre> + passing arg 3 of `scandir' from incompatible pointer type + Pointers are not assignment-compatible. + Argument #4 is not the correct type. + +</pre> + + <p><strong>during the build?</strong></p> + + <dl> + <dd> + You can safely ignore these messages. + + <p>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.</p> + + <p>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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="3.21"><strong>3.21 Why do I get compiler warning messages such + as</strong></a></p> + <pre> + Operation between types "void(*)(int)" and "void*" is not allowed. + Function argument assignment between types "void*" and "void(*)(int)" is not allowed. + Pointers are not assignment-compatible. + Argument #5 is not the correct type. +</pre> + + <p><strong>during the build?</strong></p> + + <dl> + <dd> + You can safely ignore these messages. + + <p>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:</p> + <pre> + K.5.7 Function pointer casts + [#1] A pointer to an object or to void may be cast to a pointer + to a function, allowing data to be invoked as a function (6.3.4). + [#2] A pointer to a function may be cast to a pointer to an + object or to void, allowing a function to be inspected or + modified (for example, by a debugger) (6.3.4). + +</pre>It may be just a "common extension", but this facility is relied upon +heavily by c-client. + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="3.22"><strong>3.22 Why do I get linker warning messages such + as:</strong></a></p> + <pre> +mtest.c:515: the `gets' function is dangerous and should not be used. +</pre> + + <p><strong>during the build? Isn't this a security bug?</strong></p> + + <dl> + <dd> + You can safely ignore this message. + + <p>Certain linkers, most notably on Linux, give this warning message. + It is indeed true that the traditional gets() function is not a safe + one.</p> + + <p>However, the mtest program is only a demonstration program, a model + of a very basic application program using c-client. It is not something + that you would install, much less run in any security-sensitive + context.</p> + + <p>mtest has numerous other shortcuts that you wouldn't want to do in a + real application program.</p> + + <p>The only "security bug" with mtest would be if it was run by some + script in a security-sensitive context, but mtest isn't particularly + useful for such purposes. If you wanted to write a script to automate + some email task using c-client, you'd be better off using imapd instead + of mtest.</p> + + <p>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.</p> + + <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> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="3.23"><strong>3.23 Why do I get linker warning messages such + as:</strong></a></p> + <pre> + auth_ssl.c:92: the `tmpnam' function is dangerous and should not be used. +</pre> + + <p><strong>during the build? Isn't this a security bug?</strong></p> + + <dl> + <dd> + You can safely ignore this message. + + <p>Certain linkers, most notably on Linux, give this warning message, + based upon two known issues with tmpnam():</p> + + <dl> + <dd>there can be a buffer overflow if an inadequate buffer is + allocated.</dd> + + <dd>there can be a timing race caused by certain incautious usage of + the return value.</dd> + </dl> + + <p>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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="3.24"><strong>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?</strong></a></p> + + <dl> + <dd>Please forward the details for investigation.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><br></p> + + <h2><a name="operation">4. Operational Questions</a></h2> + <hr> + + <p><a name="4.1"><strong>4.1 How can I enable anonymous IMAP + logins?</strong></a></p> + + <dl> + <dd>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.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="4.2"><strong>4.2 How do I set up an alert message that each IMAP + user will see?</strong></a></p> + + <dl> + <dd>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.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="4.3"><strong>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 noticed that it can connect on port 143, port 993, via rsh, and via + ssh.</strong></a></p> + + <dl> + <dd> + c-client chooses how to establish an IMAP connection via the following + rules: + + <ul> + <li>If /ssl is specified, use an SSL connection. Fail otherwise.</li> + + <li>Else if client is a UNIX system and "ssh server exec /etc/rimapd" + works, use that</li> + + <li>Else if /tryssl is specified and an SSL connection works, use + that.</li> + + <li>Else if client is a UNIX system and "rsh server exec /etc/rimapd" + works, use that.</li> + + <li>Else use a non-SSL connection.</li> + </ul> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="4.4"><strong>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?</strong></a></p> + + <dl> + <dd>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.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <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 + 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 traditional UNIX mailbox format and permits shared access. + + <p>However, and this is <em>very important</em>, 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.</p> + + <p>Some of the formats, including mbx, 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> + + <p>Another problem is that the certain formats, including 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> + + <p>Each of the following steps are in escalating order of involvement. + The further you go down this list, the more deeply committed you + 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 + 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 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 + 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 + 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.</li> + + <li>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.</li> + + <li>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.</li> + </ul> + + <p>Most other servers (e.g. Cyrus) require use of a non-standard + format. A full-fledged format conversion is not significantly different + from what you have to do with other servers. The difference, which + makes format conversion procedures somewhat more complicated with this + server, is that there is no "all or nothing" requirement with this + server. There are many points in between. A format conversion can be + anything from a single mailbox or single user, to systemwide.</p> + + <p>This is good in that you can decide how far to go, or do the steps + incrementally as you become more comfortable with the result. On the + other hand, there's no "One True Way" which can be boiled down to a + simple set of pedagogical instructions.</p> + + <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> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="4.6"><strong>4.6 How do I set up shared mailboxes?</strong></a></p> + + <dl> + <dd> + At the simplest level, a shared mailbox is one which has UNIX file and + directory protections which permit multiple users to access it. What + this means is that your existing skills and tools to create and manage + shared files on your UNIX system apply to shared mailboxes; e.g. + <pre> + chmod 666 mailbox +</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 + traditional UNIX format only allows one read/write session to a + mailbox at a time.</p> + + <p>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.</p> + + <p>#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.</p> + + <p>#public/ refers to an IMAP toolkit convention called "public" files, + and is equivalent to the home directory for UNIX user "imappublic". For + example, #public/foo/bar refers to the file ~imappublic/foo/bar. Public + files are available to anonymous IMAP logins. By default, newly-created + files in #public are created with protection 0666.</p> + + <p>#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 <em>not</em> available to anonymous IMAP logins. By default, + newly-created files in #shared are created with protection 0660.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="4.7"><strong>4.7 How can I make the server syslogs go to someplace + other than the mail syslog?</strong></a></p> + + <dl> + <dd> + The openlog() call that sets the syslog facility is in + <strong>src/osdep/unix/env_unix.c</strong> in routine + <strong>server_init()</strong>. You need to edit this file to change + the syslog facility from LOG_MAIL to the facility you want, then + rebuild. You also need to set up your /etc/syslog.conf properly. + + <p>Refer to the man pages for syslog and syslogd for more 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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><br></p> + + <h2><a name="security">5. Security Questions</a></h2> + <hr> + + <p><a name="5.1"><strong>5.1 I see that the IMAP server allows access to + arbitary files on the system, including /etc/passwd! How do I disable + this?</strong></a></p> + + <dl> + <dd> + You should not worry about this if your IMAP users are allowed shell + access. The IMAP server does not permit any access that the user can + not have via the shell. + + <p>If, and only if, you deny your IMAP users shell access, you may want + to consider one of three choices. Note that these choices reduce IMAP + functionality, and may have undesirable side effects. Each of these + choices involves an edit to file + <strong>src/osdep/unix/env_unix.c</strong></p> + + <p>The first (and recommended) choice is to set + <strong>restrictBox</strong> as described in file CONFIG. This will + disable access to the filesystem root, to other users' home directory, + and to superior directory.</p> + + <p>The second (and strongly NOT recommended) choice is to set + <strong>closedBox</strong> as described in file CONFIG. This puts each + IMAP session into a so-called "chroot jail", and thus setting this + option is <em>extremely</em> dangerous; it can make your system much + less secure and open to root compromise attacks. So do not use this + option unless you are <em>absolutely certain</em> that you understand + all the issues of a "chroot jail."</p> + + <p>The third choice is to rewrite routine + <strong>mailboxfile()</strong> 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 <strong>mailboxfile()</strong> what the + <strong>restrictBox</strong> choice does.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="5.2"><strong>5.2 I've heard that IMAP servers are insecure. Is this + true?</strong></a></p> + + <dl> + <dd> + 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. + + <p>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.</p> + + <p>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.</p> + + <p>It's unfortunate that any vulnerabilities existed in past versions, + and we're doing my best to keep the IMAP toolkit free of + vulnerabilities. No new vulnerabilities have been discovered in quite a + while, but efforts will not be relaxed.</p> + + <p>Beware of vendors who claim that their implementations can not have + vulnerabilities.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="5.3"><strong>5.3 How do I know that I have the most secure version + of the server?</strong></a></p> + + <dl> + <dd> + 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. + + <p>Oldtimers used to refer to a concept of <em>software rot</em>: 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.</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> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="5.4"><strong>5.4 I see all these strcpy() and sprintf() calls, those + are unsafe, aren't they?</strong></a></p> + + <dl> + <dd> + Yes and no. + + <p>It can be unsafe to do these calls if you do not know that the + string being written will fit in the buffer. However, they are + perfectly safe if you do know that.</p> + + <p>Beware of programmers who advocate doing a brute-force change of all + instances of</p> + <pre> + strcpy (s,t); +</pre>to + <pre> + strncpy (s,t,n)[n] = '\0'; +</pre>and similar measures in the name of "fixing all possible buffer +overflows." + + <p>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 credential was truncated.</p> + + <p>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.</p> + + <p>With all this in mind, the software has been inspected, and it is + believed that all places where buffer overflows can happen have been + fixed. The strcpy()s that are still are in the code occur after a size + check was done in some other way.</p> + + <p>Note that the common C idiom of</p> + <pre> + *s++ = c; +</pre>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. + + <p>Nothing replaces careful study of code. That's how the bad guys find + bugs. Security is not accomplished by means of brute-force + shortcuts.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="5.5"><strong>5.5 Those /tmp lock files are protected 666, is that + really right?</strong></a></p> + + <dl> + <dd> + Yes. Shared mailboxes won't work otherwise. Also, you get into + accidental denial of service problems with old lock files left lying + around; this happens fairly frequently. + + <p>The deliberate mischief that can be caused by fiddling with the lock + files is small-scale; harassment level at most. There are many -- and + much more effective -- other ways of harassing another user on UNIX. + It's usually not difficult to determine the culprit.</p> + + <p>Before worrying about deliberate mischief, worry first about things + happening by accident!</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><br></p> + + <h2><a name="strange">6. <em>Why Did You Do This Strange Thing?</em> + Questions</a></h2> + <hr> + + <p><a name="6.1"><strong>6.1 Why don't you use GNU autoconfig / automake / + autoblurdybloop?</strong></a></p> + + <dl> + <dd> + 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 programs add another + layer of complexity to an already complex process. + + <p>Coaxing software that uses autoconfig to build properly on 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.</p> + + <p>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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="6.2"><strong>6.2 Why do you insist upon a build with -g? Doesn't it + waste disk and memory space?</strong></a></p> + + <dl> + <dd> + From time to time a submitted port has snuck in without -g. This has + <em>always</em> ended up causing problems. There are only two valid + excuses for not using -g in a port: + + <ul> + <li>The compiler does not support -g</li> + + <li>An alternate form of -g is needed with optimization, e.g. + -g3.</li> + </ul> + + <p>There will be no new ports added without -g (or a suitable + alternative) being set.</p> + + <p>-g has not been arbitrarily added to the ports which do not + currently have it because we don't know if doing so would break the + build. However, any support issues with one of those port <em>will</em> + lead to the correct -g setting being determined and permanently + added.</p> + + <p>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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="6.3"><strong>6.3 Why don't you make c-client a shared + library?</strong></a></p> + + <dl> + <dd> + All too often, shared libraries create far more problems than they + solve. + + <p>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.</p> + + <p>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.</p> + + <p>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.</p> + + <p>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.</p> + + <p>Several sites and third-party distributors have modified the + c-client makefile in order to make c-client be a shared library. + <em>When</em> (not <em>if</em>) 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.</p> + + <p>Memory is so cheap these days that it's not worth it. Human life is + too short to deal with shared library compatibility problems.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="6.4"><strong>6.4 Why don't you use iconv() for internationalization + support?</strong></a></p> + + <dl> + <dd>iconv() is not ubiquitous enough.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="6.5"><strong>6.5 Why is the IMAP server connected to the home + directory by default?</strong></a></p> + + <dl> + <dd> + 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. + + <p>The IMAP server also doesn't know whether your preferred + subdirectory for mailbox files is "mail/", ".mail/", "Mail/", + "Mailboxes/", or any of a zillion other possibilities. If one such name + were chosen, it would undoubtably anger the partisans of all the other + names.</p> + + <p>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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="6.6"><strong>6.6 I have a Windows system. Why isn't the server plug + and play for me?</strong></a></p> + + <dl> + <dd> + 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. + + <p>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.</p> + + <p>Basically, unless you're an email software hacker, you probably want + to look elsewhere if you want IMAP/POP servers for Windows.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="6.7"><strong>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 the full size?</strong></a></p> + + <dl> + <dd> + This is to avoid an interoperability problem with: + + <ul> + <li>PC IMAP clients that use Microsoft's SChannel.DLL (SSPI) for SSL + support</li> + + <li>Microsoft Exchange server (which also uses SChannel).</li> + </ul> + + <p>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.</p> + + <p>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 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.</p> + + <p>There wasn't a significant difference that we could measure between + 8K and 15K.</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 affects Microsoft Exchange server with + <em>any</em> client that transmits full-sized SSL payloads.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="6.8"><strong>6.8 Why is an mh format INBOX called #mhinbox instead + of just INBOX?</strong></a></p> + + <dl> + <dd> + It's a long story. In brief, the mh format driver is less functional + than any of the other drivers. It turned out that there were some users + (including high-level administrators) who tried mh years ago and no + longer use it, but still had an mh profile left behind. + + <p>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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="6.9"><strong>6.9 Why don't you support the maildir + format?</strong></a></p> + + <dl> + <dd> + It is technically difficult to support maildir in IMAP while + maintaining acceptable performance, robustness, following the + requirements of the IMAP protocol specification, and following the + requirements of maildir. + + <p>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.</p> + + <p>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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="6.10"><strong>6.10 Why don't you support the Cyrus + format?</strong></a></p> + + <dl> + <dd> + 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. + + <p>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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="6.11"><strong>6.11 Why is it creating extra forks on my SVR4 + system?</strong></a></p> + + <dl> + <dd> + 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. + + <p>This design flaw causes unexpected loss of lock, and consequent + mailbox corruption. The workaround is to do certain "dangerous + operations" in another fork, thus avoiding doing a close() in the + vulnerable fork.</p> + + <p>The best way to solve this problem is to upgrade your SVR4 (Solaris, + AIX, HP-UX, SGI) or OSF/1 system to a more advanced operating system, + such as Linux or BSD. These more advanced operating systems have + fcntl() locking for compatibility with SVR4, but also have flock() + locking.</p> + + <p>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().</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="6.12"><strong>6.12 Why are you so fussy about the date/time format in + the internal <code>"From "</code> line in traditional UNIX mailbox + files? My other mail program just considers every line that starts with + <code>"From "</code> to be the start of the message.</strong></a></p> + + <dl> + <dd> + You just answered your own question. If any line that starts with + <code>"From "</code> is treated as the start of a message, then + every message text line which starts with <code>"From "</code> has + to be quoted (typically by prefixing a ">" character). People + complain about this -- "why did a > get stuck in my message?" + + <p>So, good mail reading software only considers a line to be a + <code>"From "</code> line if it follows the actual specification + for a "From " line. This means, among other things, that the day of + week is fixed-format: <code>"May 14"</code>, but + <code>"May 7"</code> (note the extra space) as opposed to + <code>"May 7"</code>. 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.</p> + + <p>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 <code>"From "</code> 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.</p> + + <p>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 and ancient + history, you should seriously consider using the c-client library (e.g. + routine mail_append()) instead of doing the file writes yourself. If + you must do it yourself, use ctime(), as in:</p> + <pre> + fprintf (mbx,"From %s@%h %s",user,host,ctime (time (0))); +</pre>rather than try to figure out a good format yourself. ctime() is the +most traditional format and nobody will flame you for using it. + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="6.13"><strong>6.13 Why is traditional UNIX format the default + format?</strong></a></p> + + <dl> + <dd>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.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="6.14"><strong>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?</strong></a></p> + + <dl> + <dd> + This pseudo-message serves two purposes. + + <p>First, it establishes the mailbox format even when the mailbox has + no messages. Otherwise, a mailbox with no messages is a zero-byte file, + which could be one of several formats.</p> + + <p>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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="6.15"><strong>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?</strong></a></p> + + <dl> + <dd> + In fact, that is what is done if the mailbox is non-empty and does not + already have a FOLDER INTERNAL DATA message. + + <p>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.</p> + + <p>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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="6.16"><strong>6.16 Why aren't "dual-use" mailboxes the + default?</strong></a></p> + + <dl> + <dd>Compatibility with the past 30 or so years of UNIX history, not to + mention compatibility with user expectations when using shell tools.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="6.17"><strong>6.17 Why do you use ucbcc to build on + Solaris?</strong></a></p> + + <dl> + <dd> + It is a long, long story about why cc is set to ucbcc. You need to + invoke the C compiler so that it links with the SVR4 libraries and not + the BSD libraries, otherwise readdir() will return the wrong + information. + + <p>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.</p> + + <p>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.</p> + + <p>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).</p> + + <p>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, that's a pretty good + indicator that you goofed and are running the compiler that will link + with the BSD libraries.</p> + + <p>To recap:</p> + + <ul> + <li>The sol port is designed to be built using the UCB compiler using + the SVR4 libraries. This compiler is "ucbcc", which is lunk to acc. + You use -O2 as one of the CFLAGS.</li> + + <li>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". <strong>BEWARE</strong></li> + + <li>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.</li> + </ul> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="6.18"><strong>6.18 Why should I care about some old system with BSD + libraries? cc is the right thing on my Solaris system!</strong></a></p> + + <dl> + <dd> + 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. + + <p>Too many sites have fallen victim to this problem.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="6.19"><strong>6.19 Why do you insist upon writing .lock files in the + spool directory?</strong></a></p> + + <dl> + <dd>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.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="6.20"><strong>6.20 Why should I care about compatibility with the + past?</strong></a></p> + + <dl> + <dd>This is one of those questions in which the answer never 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.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><br></p> + + <h2><a name="problems">7. Problems and Annoyances</a></h2> + <hr> + + <p><a name="7.1"><strong>7.1 Help! My INBOX is empty! What happened to my + messages?</strong></a></p> + + <dl> + <dd> + 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.: + <pre> + From fred@foo.bar Mon May 7 20:54:30 2001 +</pre> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.2"><strong>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?</strong></a></p> + + <dl> + <dd> + 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.: + <pre> + From fred@foo.bar Mon May 7 20:54:30 2001 +</pre> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.3"><strong>7.3 Why do I get the message:</strong> <tt>CREATE + failed: Can't create mailbox node xxxxxxxxx: File exists</tt> + <strong>and how do I fix it?</strong></a></p> + + <dl> + <dd>See the answer to the <a href="#1.8">Are hierarchical mailboxes + supported?</a> question.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.4"><strong>7.4 Why can't I log in to the server? The user name and + password are right!</strong></a></p> + + <dl> + <dd> + There are a myriad number of possible answers to this question. The + only way to say for sure what is wrong is run the server 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. + + <p>Here are some of the more common reasons why login may fail:</p> + + <ul> + <li>You didn't really give the correct user name and/or + password.</li> + + <li>Your client doesn't send the LOGIN command correctly; for + example, IMAP2 clients won't send a password containing a "*" + correctly to an IMAP4 server.</li> + + <li>If you have set up a CRAM-MD5 database, remember that the + password used is the one in the CRAM-MD5 database, and furthermore + that there must also be an entry in /etc/passwd (but the /etc/passwd + password is not used).</li> + + <li>If you are using PAM, have you created a service file for the + server in /etc/pam.d?</li> + + <li>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.</li> + + <li>If your system has account or password expirations, check to see + that the expiration date hasn't passed.</li> + + <li>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".</li> + </ul> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.5"><strong>7.5 Help! My load average is soaring and I see hundreds + of POP and IMAP servers, many logged in as the same + user!</strong></a></p> + + <dl> + <dd> + 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. + + <p>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.</p> + + <p>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.</p> + + <p>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.</p> + + <p>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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.6"><strong>7.6 Why does mail disappear even though I set "keep + mail on server"?</strong></a><br> + <a name="7.7"><strong>7.7 Why do I get the message</strong> <tt>Moved ##### + bytes of new mail to /home/user/mbox from /var/spool/mail/user</tt> + <strong>and why did this happen?</strong></a></p> + + <dl> + <dd> + This is probably caused by the mbox driver. If the file "mbox" 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. + + <p>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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.8"><strong>7.8 Why isn't it showing the local host name as a + fully-qualified domain name?</strong></a><br> + <a name="7.9"><strong>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?</strong></a></p> + + <dl> + <dd> + Your UNIX system is misconfigured. The entry for your system in + /etc/hosts must have the fully-qualified domain name first, e.g. + <pre> + 105.69.1.234 myserver.example.com myserver +</pre> + + <p>A common mistake of novice system administrators is to have the + short name first, e.g.</p> + <pre> + 105.69.1.234 myserver myserver.example.com + +</pre> + + <p>or to omit the fully qualified domain name entirely, e.g.</p> + <pre> + 105.69.1.234 myserver +</pre> + + <p>The result of this is that when the IMAP toolkit does a + gethostbyname() call to get the fully-qualified domain name, it would + get "myserver" instead of "myserver.example.com".</p> + + <p>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.</p> + + <p>Check the man pages for gethostbyname, hosts, svc, and/or netsvc for + more information.</p> + + <p>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.</p> + + <p>net.folklore once (late 1980s) held that the proper procedure was to + append the results of getdomainname() to the name returned by + gethostname(), and some versions of sendmail configuration files were + distributed that did this. This was incorrect; the string returned from + getdomainname() is the Yellow Pages (a.k.a NIS) domain name, which is a + completely different (albeit unfortunately named) entity from an + Internet domain. These were often fortuitously the same string, except + when they weren't. Frequently, this would result in host names with + spuriously doubled domain names, e.g.</p> + <pre> + myserver.example.com.example.com + +</pre> + + <p>This practice has been thoroughly discredited for many years, but + folklore dies hard.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.10"><strong>7.10 What does the message:</strong> <tt>Mailbox + vulnerable - directory /var/spool/mail must have 1777 protection</tt> + <strong>mean? How can I fix this?</strong></a></p> + + <dl> + <dd> + 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. + + <p>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.</p> + + <p>Directory protection 1777 is secure enough on most well-managed + systems. If you can't trust your users with a 1777 mail spool (petty + harassment is about the limit of the abuse exposure), then you have + much worse problems then that.</p> + + <p>If you absolutely insist upon requiring privileges to create a lock + file, external file locking can be done via a setgid mail program named + /etc/mlock (this is defined by LOCKPGM in the c-client Makefile). If + the toolkit is unable to create a <...mailbox...>.lock file in + 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 + tried to make this sample program secure, but it has not been + thoroughly audited.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.11"><strong>7.11 What does the message:</strong> <tt>Mailbox is + open by another process, access is readonly</tt> <strong>mean? How do I + fix this?</strong></a></p> + + <dl> + <dd> + 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. + + <p>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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.12"><strong>7.12 What does the message:</strong> <tt>Can't get + write access to mailbox, access is readonly</tt> + <strong>mean?</strong></a></p> + + <dl> + <dd>The mailbox file is write-protected against you.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.13"><strong>7.13 I set my POP3 client to "delete messages from + server" but they never get deleted. What is wrong?</strong></a></p> + + <dl> + <dd> + Make sure that your mailbox is not read-only: that the mailbox is owned + by you and write enabled (protection 0600), and that the /tmp directory + is longer world-writeable. /tmp must be world-writeable because lots of + applications use it for scratch space. To fix this, do + <pre> + + chmod 1777 /tmp +</pre>as root. + + <p>Make sure that your POP3 client issues a QUIT command when it + finishes. The POP3 protocol specifies that deletions are discarded + unless a proper QUIT is done.</p> + + <p>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 + <a href="#7.19">What does the syslog message: Killed (lost mailbox + lock) user=... host=... mean?</a> question for more details.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.14"><strong>7.14 What do messages such as:</strong></a></p> + <pre> + Message ... UID ... already has UID ... + Message ... UID ... less than ... + Message ... UID ... greater than last ... + Invalid UID ... in message ..., rebuilding UIDs +</pre> + + <p><strong>mean?</strong></p> + + <dl> + <dd> + 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. + + <p>This problem is relatively harmless; a new valid unique identifier + regime will be created. The main effect is that any references to the + old UIDs will no longer be useful.</p> + + <p>So, unless it is a chronic problem or you feel like debugging, you + can safely ignore these messages.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.15"><strong>7.15 What do the error messages:</strong></a></p> + <pre> + Unable to read internal header at ... + Unable to find CRLF at ... + Unable to parse internal header at ... + Unable to parse message date at ... + Unable to parse message flags at ... + Unable to parse message UID at ... + Unable to parse message size at ... + Last message (at ... ) runs past end of file ... +</pre> + + <p><strong>mean? I am using mbx format.</strong></p> + + <dl> + <dd> + The mbx-format mailbox is corrupted and needs to be repaired. + + <p>You should make an effort to find out why the corruption happened. + Was there an obvious system problem (crash or disk failure)? Did the + user accidentally access the file via NFS? Mailboxes don't get + corrupted by themselves; something caused the problem.</p> + + <p>Some people have developed automated scripts, but if you're + comfortable using emacs it's pretty easy to fix it manually. Do + <em>not</em> use vi or any other editor unless you are certain that + editor can handle binary!!!</p> + + <p>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.</p> + + <p>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:</p> + <pre> + Unable to parse internal header at 43921: ne bombastic blurdybloop +</pre>The problem occurs at the 43,931 byte in the file. That's the point you +need to fix. c-client is expecting an internal header at that byte number, +looking something like: + <pre> + 6-Jan-1998 17:42:24 -0800,1045;000000100001-00000001 +</pre>The format of this internal line is: + <pre> + dd-mmm-yyyy hh:mm:ss +zzzz,ssss;ffffffffFFFF-UUUUUUUU +</pre>The only thing that is variable is the "ssss" field, it can be as many +digits as needed. All other fields (inluding the "dd") are fixed width. So, +the easiest thing to do is to look forward in the file for the next internal +header, and delete everything from the error point to that internal header. + + <p>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.</p> + + <p>Mark where you are in the file, move the cursor to the line after + the internal header, and skip that many bytes ("ssss") forward. If + you're at the point of the error in the file, then that message is + corrupt. If you're at a different point, then perhaps the previous + message is corrupt and has a too long size count that "ate" into this + message.</p> + + <p>Basically, what you need to do is make sure that all those size + counts are right, and that moving "ssss" bytes from the line after the + internal header will land you at another internal header.</p> + + <p>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.</p> + + <p>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.</p> + + <p>In this example, suppose that the corrupt file is INBOX, the error + message is</p> + <pre> + Unable to find CRLF at 132551754 +</pre>and the size of the INBOX file is 132867870 bytes. + + <p>The first step is to split the mailbox file at the point of the + error:</p> + + <ul> + <li>Rename the INBOX file to some other name, such as INBOX.bad.</li> + + <li>Copy the first 132,551,754 bytes of INBOX.bad to another file, + such as INBOX.new.</li> + + <li>Extract the trailing 316,116 bytes (132867870-132551754) of + INBOX.bad into another file, such as INBOX.tail.</li> + + <li>You no longer need INBOX.bad. Delete it.</li> + </ul>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. + + <p>Now, remove the erroneous data:</p> + + <ul> + <li>Verify that you can open INBOX.new in IMAP or Pine.</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 + message from INBOX.new</li> + + <li>Locate the first occurance of text in INBOX.tail which looks like + an internal header, as described above.</li> + + <li>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").</li> + </ul> + + <p>Reassemble the mailbox:</p> + + <ul> + <li>Append INBOX.tail to INBOX.new.</li> + + <li>You no longer need INBOX.tail. Delete it.</li> + + <li>Verify that you can open INBOX.new in IMAP or Pine.</li> + </ul> + + <p>Reinstall INBOX.new as INBOX:</p> + + <ul> + <li>Check to see if you have received any new messages while + repairing INBOX.</li> + + <li>If you haven't received any new messages while repairing INBOX, + just rename INBOX.new to INBOX.</li> + + <li>If you have received new messages, be sure to copy the new + messages from INBOX to INBOX.new before doing the rename.</li> + </ul> + + <p>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 salvaging; otherwise you can + delete the two badmsg files.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.16"><strong>7.16 What do the syslog messages:</strong></a></p> + <pre> + + imap/tcp server failing (looping) + pop3/tcp server failing (looping) +</pre> + + <p><strong>mean? When it happens, the listed service shuts down. How can I + fix this?</strong></p> + + <dl> + <dd> + 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. + + <p>inetd has a limit of 40 new server sessions per minute for any + particular service. If more than 40 sessions are initiated in a minute, + inetd will issue the "failing (looping), service terminated" message + and shut down the service for 10 minutes. 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!</p> + + <p>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.</p> + + <p>On some versions of inetd, such as the one distributed with most + versions of Linux, you can modify the <strong>/etc/inetd.conf</strong> + file to have a larger number of servers by appending a period followed + by a number after the <strong>nowait</strong> word for the server + entry. For example, if your existing /etc/inetd.conf line reads:</p> + <pre> + imap stream tcp nowait root /usr/etc/imapd imapd +</pre>try changing it to be: + <pre> + imap stream tcp nowait.100 root /usr/etc/imapd imapd +</pre>Another example (using TCP wrappers): + <pre> + imap stream tcp nowait root /usr/sbin/tcpd imapd +</pre>try changing it to be: + <pre> + imap stream tcp nowait.100 root /usr/sbin/tcpd imapd + +</pre>to increase the limit to 100 sessions/minute. + + <p>Before making this change, please read the information in "man + inetd" to determine whether or not your inetd has this feature. If it + does not, and you make this change, the likely outcome is that you will + disable IMAP service entirely.</p> + + <p>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 + <strong>TOOMANY</strong> (normally 40) is the maximum number of new + server sessions permitted per minute, and <strong>RETRYTIME</strong> + (normally 600) is the number of seconds inetd will shut down the server + after it exceeds TOOMANY.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.17"><strong>7.17 What does the syslog message:</strong> + <tt>Mailbox lock file /tmp/.600.1df3 open failure: Permission + denied</tt> <strong>mean?</strong></a></p> + + <dl> + <dd> + 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 + <pre> + chmod 1777 /tmp + +</pre>as root. + + <p>If that isn't the answer, check the protection of the named 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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.18"><strong>7.18 What do the syslog messages:</strong></a></p> + <pre> + Command stream end of file, while reading line user=... host=... + Command stream end of file, while reading char user=... host=... + Command stream end of file, while writing text user=... host=... +</pre> + + <p><strong>mean?</strong></p> + + <dl> + <dd> + This message occurs when the session is disconnected without a proper + LOGOUT (IMAP) or QUIT (POP) command being received by the server first. + + <p>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".</p> + + <p>The condition could, however, indicate a client or network + connectivity problem. The server has no way of knowing whether there's + a problem or just a rude client, so it issues this message instead of a + Logout.</p> + + <p>Certain inferior losing clients disconnect abruptly after a 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 <a href="#7.4">Why can't I log in to the server? The + user name and password are right!</a> question.</p> + + <p>If the user isn't reporting a problem, you can probably ignore this + message.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.19"><strong>7.19 Why did my POP or IMAP session suddenly + disconnect? The syslog has the message:</strong> <tt>Killed (lost + mailbox lock) user=... host=...</tt></a></p> + + <dl> + <dd> + 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. + + <p>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 <em>kiss of death</em>, 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.</p> + + <p>Certain poorly-designed clients routinely open multiple sessions to + the same mailbox; the users of those clients tend to get this message a + lot.</p> + + <p>Another cause of this message is a background "check for new mail" + task which does its work by opening a POP session to server every few + seconds. They do this because POP doesn't have a way to announce new + 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 + clients and poorly-designed IMAP clients.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.20"><strong>7.20 Why does my IMAP client show all the files on the + system, recursively from the UNIX root directory?</strong></a><br> + <a name="7.21"><strong>7.21 Why does my IMAP client show all of my files, + recursively from my UNIX home directory?</strong></a></p> + + <dl> + <dd> + 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!). + + <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 + problem.</p> + + <p>See also the answer to <a href="#7.73">Why does my IMAP client show + all my files in my home directory?</a></p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.22"><strong>7.22 Why does my IMAP client show that I have + mailboxes named "#mhinbox", "#mh", "#shared", "#ftp", "#news", and + "#public"?</strong></a></p> + + <dl> + <dd> + 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. + + <p>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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.23"><strong>7.23 Why does my IMAP client show all my files in my + home directory?</strong></a></p> + + <dl> + <dd> + As distributed, the IMAP server is connected to your home directory by + default. It 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. + + <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 + "Path" in your folder-collection, e.g.</p> + <pre> + Nickname : Secondary Folders + Server : imap.example.com + Path : mail/ + View : +</pre>In this example, the user is connected to the "mail" subdirectory of +his home directory. + + <p>Other servers call this the "folder prefix" or similar term.</p> + + <p>It is possible to modify the IMAP server so that all users are + automatically connected to some other directory, e.g. a subdirectory of + the user's home directory. Read the file CONFIG for more details.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.24"><strong>7.24 Why is there a long delay before I get connected + to the IMAP or POP server, no matter what client I use?</strong></a></p> + + <dl> + <dd> + There are two common occurances of this problem: + + <ul> + <li>You are running a system (e.g. certain versions of Linux) which + by default attempts to connect to an "IDENT" protocol (port 113) + server on your client. However, a firewall or NAT box is blocking + connections to that port, so the connection attempt times out. + + <p>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.</p> + + <p>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 no separate + concept of "system administrator" vs. "unprivileged user".</p> + + <p>On either type of system, security-minded people either turn + IDENT off or replace it with an IDENT server that lies. Among other + things, IDENT gives spammers the ability to harvest email addresses + from anyone who connects to a web page.</p> + + <p>This problem has been showing up quite frequently on systems + which use xinetd instead of inetd. Look for files named + /etc/xinetd.conf, /etc/xinetd.d/imapd, /etc/inetd.d/ipop2d, and + /etc/xinetd.d/ipop3d. In those files, look for lines containing + "USERID", e.g.</p> + <pre> + log_on_success += USERID +</pre>Hunt down such lines, and delete them ruthlessly from all files in +which they occur. Don't be shy about it. + </li> + + <li>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.</li> + </ul> + + <p>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.</p> + </dd> + </dl> + + <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 + 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().</strong></a></p> + + <dl> + <dd> + By default, the c-client library attempts to make a connection through + rsh (and ssh, if you enable that). If the command: + <pre> + rsh imapserver exec /etc/rimapd + +</pre>(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. + + <p>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.</p> + + <p>It must be emphasized that this is a bug in rsh. It is <em>not</em> + a bug in the IMAP toolkit.</p> + + <p>The use of rsh can be disabled in any the following ways:</p> + + <ul> + <li>You can disable it for this particular session by either: + + <ul> + <li>setting an explicit port number in the mailbox name, e.g. + <pre> + {imapserver.foo.com:143}INBOX +</pre> + </li> + + <li>using SSL (the /ssl switch)</li> + </ul> + </li> + + <li>You can disable rsh globally by setting the rsh timeout value to + 0 with the call: + <pre> + mail_parameters (NIL,SET_RSHTIMEOUT,0); +</pre> + </li> + </ul> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.26"><strong>7.26 Why does a message sometimes get split into two + or more messages on my SUN system?</strong></a></p> + + <dl> + <dd> + 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 <em>mail tool</em> 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. + + <p>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 + <em>Content-Length:</em> 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).</p> + + <p>One symptom of the problem is that under certain circumstances, a + message may get broken up into several messages. I'm also aware of + security bugs caused by programs that foolishly trust "Content-Length:" + headers with evil values.</p> + + <p>To fix the mailer on your system, edit your sendmail.cf to change + the <strong>Mlocal</strong> line to have the <strong>-E</strong> flag. + A typical entry will lool like:</p> + <pre> + Mlocal, P=/usr/lib/mail.local, F=flsSDFMmnPE, S=10, R=20, + A=mail.local -d $u +</pre>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. + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.27"><strong>7.27 Why did my POP or IMAP session suddenly + disconnect? The syslog has the message:</strong></a></p> + <pre> + Autologout user=<...my user name...> host=<...my client system...> + +</pre> + + <dl> + <dd> + This is a problem in your client. + + <p>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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.28"><strong>7.28 What does the UNIX error message:</strong> + <tt>TLS/SSL failure: myserver: SSL negotiation failed</tt> + <strong>mean?</strong></a><br> + <a name="7.29"><strong>7.29 What does the PC error message:</strong> + <tt>TLS/SSL failure: myserver: Unexpected TCP input disconnect</tt> + <strong>mean?</strong></a></p> + + <dl> + <dd> + This usually means that an attempt to negotiate TLS encryption via the + STARTTLS command failed, because the server advertises STARTTLS + functionality, but doesn't actually have it (e.g. because no + certificates are installed). + + <p>Use the /notls option in the mailbox name to disable TLS + negotiation.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.30"><strong>7.30 What does the error message:</strong> <tt>TLS/SSL + failure: myserver: Server name does not match certificate</tt> + <strong>mean?</strong></a></p> + + <dl> + <dd> + An SSL or TLS session encryption failed because the server name in the + server's certificate does not match the name that you gave it. This + could indicate that the server is not really the system you think that + it is, but can be also be called if you gave a nickname for the server + or name that was not fully-qualified. You must use the fully-qualified + domain name for the server in order to validate its certificate + + <p>Use the /novalidate-cert option in the mailbox name to disable + validation of the certificate.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.31"><strong>7.31 What does the UNIX error message:</strong> + <tt>TLS/SSL failure: myserver: self-signed certificate</tt> + <strong>mean?</strong></a><br> + <a name="7.32"><strong>7.32 What does the PC error message:</strong> + <tt>TLS/SSL failure: myserver: Self-signed certificate or untrusted + authority</tt> <strong>mean?</strong></a></p> + + <dl> + <dd> + 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. + + <p>Use the /novalidate-cert option in the mailbox name to disable + validation of the certificate.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.33"><strong>7.33 What does the UNIX error message:</strong> + <tt>TLS/SSL failure: myserver: unable to get local issuer + certificate</tt> <strong>mean?</strong></a></p> + + <dl> + <dd> + 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. + + <p>If CA certificates are properly installed, you should see + factory.pem and about a dozen other .pem names such as + thawteCb.pem.</p> + + <p>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.</p> + + <p>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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <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> + + <dl> + <dd> + There are two possible causes. + + <p>Check the mail syslog. If you see the message "Killed (lost mailbox + lock)" for the impacted user(s), read the FAQ entry regarding that + message.</p> + + <p>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.</p> + + <p>You can work around this by rebuilding imapd with the + <strong>NETSCAPE_BRAIN_DAMAGE</strong> 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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.35"><strong>7.35 Why does Netscape say that there's a problem with + the IMAP server and that I should "Contact your mail server + administrator."?</strong></a></p> + + <dl> + <dd> + Certain versions of Netscape do this when you click the Manage Mail + button, which uses an undocumented feature of Netscape's proprietary + IMAP server. + + <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 + page.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.36"><strong>7.36 Why is one user creating huge numbers of IMAP or + POP server sessions?</strong></a></p> + + <dl> + <dd>The user is probably using Outlook Express, Eudora, or a similar + program. See the answer to the <a href="#7.5">Help! My load average is + soaring and I see hundreds of POP and IMAP servers, many logged in as the + same user!</a> question.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.37"><strong>7.37 Why don't I get any new mail notifications from + Outlook Express or Outlook after a while?</strong></a></p> + + <dl> + <dd> + This is a known bug in Outlook Express. Microsoft is aware of the + problem and its cause. They have informed us that they do not have any + plans to fix it at the present time. + + <p>The problem is also reported in Outlook 2000, but not verified.</p> + + <p>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.</p> + + <p>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.</p> + + <p>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.</p> + + <p>Modern versions of imapd attempt to work around the problem by + automatically reporting fake new mail after 29 minutes. This causes + Outlook Express to exit the IDLE state; as soon as this 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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.38"><strong>7.38 Why don't I get any new mail notifications from + Entourage?</strong></a></p> + + <dl> + <dd> + This is a known bug in Entourage. + + <p>You built an older version of imapd with the + <strong>MICROSOFT_BRAIN_DAMAGE</strong> option set, in order to disable + support for the IDLE command. However, Entourage won't get new mail + unless IDLE command support exists.</p> + + <p>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.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.39"><strong>7.39 Why doesn't Entourage work at + all?</strong></a></p> + + <dl> + <dd> + It's hard to know. Entourage breaks almost every rule in the book for + IMAP. It is highly instructive to do a packet trace on Entourage, as an + example of how <em>not</em> to use IMAP. It does things like STATUS + (MESSAGES) on the currently selected mailbox and re-fetching the same + static data over and over again. + + <p>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.</p> + + <p>Try building imapd with the <strong>ENTOURAGE_BRAIN_DAMAGE</strong> + option set, in order to disable the diagnostic that occurs when doing + STATUS on the currently selected mailbox.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.40"><strong>7.40 Why doesn't Netscape Notify (NSNOTIFY.EXE) work + at all?</strong></a></p> + + <dl> + <dd> + This is a bug in NSNOTIFY; it doesn't handle unsolicited data from the + server correctly. + + <p>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.</p> + + <p>Consequently, the recommended fix for the NSNOTIFY problem is to + delete the NSNOTIFY binary.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.41"><strong>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 file".</strong></a></p> + + <dl> + <dd>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.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.42"><strong>7.42 Sheesh. Aren't there <em>any</em> good IMAP + clients out there?</strong></a></p> + + <dl> + <dd> + Yes! + + <p>Pine 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 + world.</p> + + <p>There are some good GUI clients out there, mostly from smaller + vendors. Without naming names, look for the vendors who are active in + the IMAP protocol development community, and their products.</p> + + <p>Netscape, Eudora, and Outlook <em>can</em> be configured with enough + effort to be good citizens and work well for users, <em>but</em> they + can also be badly misconfigured, and often the misconfiguration is the + default.</p> + </dd> + </dl> + + <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 + 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> + + <dl> + <dd> + 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. + + <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 + partial fetching, which tends to reduce the number of cases where this + can happen. However, <em>all</em> software which uses SChannel to + support SSL is affected by this bug.</p> + + <p>This problem does not affect UNIX code, since OpenSSL is used on + UNIX.</p> + + <p>This problem most recently showed up with the CommunigatePro IMAP + server. They have an update which trims down their maximum contiguous + 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) + 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* + UNIX based client that transmits full-sized SSL payloads.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <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 + 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. + + <p>Assuming that you want to continue using qpopper, look into + qpopper's <strong>--enable-uw-kludge-flag</strong> configuration flag, + which is documented as "check for and hide UW 'Folder Internal Data' + messages".</p> + + <p>The other alternative is to switch from qpopper to ipop3d.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.45"><strong>7.45 Help! I installed the servers but I can't connect + to them from my client!</strong></a></p> + + <dl> + <dd> + 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. + + <p>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?</p> + + <p>If you have a system with TCP wrappers, have you properly updated + the TCP wrapper files (e.g. /etc/hosts.allow and /etc/hosts.deny) for + the servers?</p> + + <p>If you have a system which uses xinetd instead of inetd, have you + made sure that you have made the correct corresponding xinetd changes + for those services?</p> + + <p>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.</p> + + <p>If you don't know how to make the corresponding changes to these + files, seek the help of a local expert for your system.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.46"><strong>7.46 Why do I get the message</strong> <tt>Can not + authenticate to SMTP server: 421 SMTP connection went away!</tt> + <strong>and why did this happen? There was also something about</strong> + <tt>SECURITY PROBLEM: insecure server advertised AUTH=PLAIN</tt></a></p> + + <dl> + <dd> + 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 already disconnected. + + <p>To work around this, you need to specify /user=... in the host name + specification.</p> + + <p>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 disconnected.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.47"><strong>7.47 Why do I get the message</strong> <tt>SMTP + Authentication cancelled</tt> <strong>and why did this happen? There was + also something about</strong> <tt>SECURITY PROBLEM: insecure server + advertised AUTH=PLAIN</tt></a></p> + + <dl> + <dd> + This is a bug in the SMTP server. + + <p>Some versions of qmail, including that running on + mail.smtp.yahoo.com, have a bug in their implementation of SASL in + their SMTP server, which renders it non-compliant with the + standard.</p> + + <p>If the client does not provide an initial response in the command + line for an authentication mechanism whose profile does not have an + initial challenge, qmail issues a bogus response:</p> + <pre> + 334 ok, go on +</pre>The problem is the "ok, go on". This violates RFC 4954's requirement +that the text part in a 334 response be a BASE64 encoded string; in other +words, it is a protocol syntax error. + + <p>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.</p> + + <p>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 cancelled" problem.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="7.48"><strong>7.48 Why do I get the message</strong> <tt>Invalid + base64 string</tt> <strong>when I try to authenticate to a Cyrus + server?</strong></a></p> + + <dl> + <dd> + This slightly misleading message is the way that a Cyrus server + indicates that an authentication exchange was cancelled. It is not + indicative of a bug or protocol violation. + + <p>The most common reason that this happens is if the Cyrus server + offers Kerberos authentication, c-client is built with Kerberos + support, but your client system is not within the Kerberos realm. In + this case, the client code will try to authenticate via Kerberos, fail + to get the Kerberos credentials, cancel the authentication attempt, and + try the next available authentication technology.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><br></p> + + <h2><a name="additional">8. Where to Go For Additional Information</a></h2> + <hr> + + <p><a name="8.1"><strong>8.1 Where can I go to ask questions?</strong></a><br> + <a name="8.2"><strong>8.2 I have some ideas for enhancements to IMAP. Where + should I go?</strong></a></p> + + <dl> + <dd> + 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 <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 + alternative, you can use the + <strong>comp.mail.imap</strong> newsgroup.</p> + </dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="8.3"><strong>8.3 Where can I read more about IMAP and other email + protocols?</strong></a></p> + + <dl> + <dd>We recommend <em>Internet Email Protocols: A Developer's Guide</em>, + by Kevin Johnson, published by Addison Wesley, ISBN 0-201-43288-9.</dd> + </dl> + + <p><a href="#top">Back to top</a></p> + <hr> + + <p><a name="8.4"><strong>8.4 Where can I find out more about setting up and + administering an IMAP server?</strong></a></p> + + <dl> + <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> + +<!--chtml include "//imap/incs/bottom.inc"--> + diff --git a/imap/docs/FAQ.txt b/imap/docs/FAQ.txt new file mode 100644 index 00000000..797bed09 --- /dev/null +++ b/imap/docs/FAQ.txt @@ -0,0 +1,2993 @@ +/* ======================================================================== + * 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 + +Table of Contents + + * 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.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? + + 1.7 Can I set up a POP or IMAP server on TOPS-20? + + 1.8 Are hierarchical mailboxes supported? + + 1.9 Are "dual-use" mailboxes supported? + + 1.10 Can I have a mailbox that has both messages and + sub-mailboxes? + + 1.11 What is the difference between "mailbox" and "folder"? + + 1.12 What is the status of internationalization? + + 1.13 Can I use SSL? + + 1.14 Can I use TLS and the STARTTLS facility? + + 1.15 Can I use CRAM-MD5 authentication? + + 1.16 Can I use APOP authentication? + + 1.17 Can I use Kerberos V5? + + 1.18 Can I use PAM for plaintext passwords? + + 1.19 Can I use Kerberos 5 for plaintext passwords? + + 1.20 Can I use AFS for plaintext passwords? + + 1.21 Can I use DCE for plaintext passwords? + + 1.22 Can I use the CRAM-MD5 database for plaintext passwords? + + 1.23 Can I disable plaintext passwords? + + 1.24 Can I disable plaintext passwords on unencrypted + sessions, but allow them on encrypted sessions? + + 1.25 Can I use virtual hosts? + + 1.26 Can I use RPOP authentication? + + 1.27 Can I use Kerberos V4? + + 1.28 Is there support for S/Key or OTP? + + 1.29 Is there support for NTLM or SPA? + + 1.30 Is there support for mh? + + 1.31 Is there support for qmail and the maildir format? + + 1.32 Is there support for the Cyrus mailbox format? + + 1.33 Is this software Y2K compliant? + * 2. What Do I Need to Build This Software? + + 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.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? + + 2.7 What do I need to build this software on the Mac? + + 2.8 What do I need to build this software on VMS? + + 2.9 What do I need to build this software on TOPS-20? + + 2.10 What do I need to build this software on Amiga or OS/2? + + 2.11 What do I need to build this software on Windows CE? + * 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 + instructions. It can't be that easy. Don't I need to write a + config file? + + 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? + + 3.5 How do I configure SSL? + + 3.6 How do I configure TLS and the STARTTLS facility? + + 3.7 How do I build/install OpenSSL and obtain/create + certificates for use with SSL? + + 3.8 How do I configure CRAM-MD5 authentication? + + 3.9 How do I configure APOP authentication? + + 3.10 How do I configure Kerberos V5? + + 3.11 How do I configure PAM for plaintext passwords? + + 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? + + 3.13 How do I configure Kerberos 5 for plaintext passwords? + + 3.14 How do I configure AFS for plaintext passwords? + + 3.15 How do I configure DCE for plaintext passwords? + + 3.16 How do I configure the CRAM-MD5 database for plaintext + passwords? + + 3.17 How do I disable plaintext passwords? + + 3.18 How do I disable plaintext passwords on unencrypted + 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 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 Function argument assignment between types "void*" and + "void(*)(int)" is not allowed. + o Pointers are not assignment-compatible. + o Argument #5 is not the correct type. + during the build? + + 3.22 Why do I get linker warning messages such as: + o mtest.c:515: the `gets' function is dangerous and should + not be used. + during the build? Isn't this a security bug? + + 3.23 Why do I get linker warning messages such as: + o auth_ssl.c:92: the `tmpnam' function is dangerous and + should not be used. + during the build? Isn't this a security bug? + + 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? + * 4. Operational Questions + + 4.1 How can I enable anonymous IMAP logins? + + 4.2 How do I set up an alert message that each IMAP user will + see? + + 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 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? + + 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 + access. + + 4.6 How do I set up shared mailboxes? + + 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.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? + + 5.4 I see all these strcpy() and sprintf() calls, those are + unsafe, aren't they? + + 5.5 Those /tmp lock files are protected 666, is that really + right? + * 6. Why Did You Do This Strange Thing? Questions + + 6.1 Why don't you use GNU autoconfig / automake / + autoblurdybloop? + + 6.2 Why do you insist upon a build with -g? Doesn't it waste + disk and memory space? + + 6.3 Why don't you make c-client a shared library? + + 6.4 Why don't you use iconv() for internationalization + support? + + 6.5 Why is the IMAP server connected to the home directory by + default? + + 6.6 I have a Windows system. Why isn't the server plug and + play for me? + + 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 the full size? + + 6.8 Why is an mh format INBOX called #mhinbox instead of just + INBOX? + + 6.9 Why don't you support the maildir format? + + 6.10 Why don't you support the Cyrus format? + + 6.11 Why is it creating extra forks on my SVR4 system? + + 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 just considers every line that starts with + "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? + + 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? + + 6.16 Why aren't "dual-use" mailboxes the default? + + 6.17 Why do you use ucbcc to build on Solaris? + + 6.18 Why should I care about some old system with BSD + libraries? cc is the right thing on my Solaris system! + + 6.19 Why do you insist upon writing .lock files in the spool + directory? + + 6.20 Why should I care about compatibility with the past? + * 7. Problems and Annoyances + + 7.1 Help! My INBOX is empty! What happened to my messages? + + 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? + + 7.3 Why do I get the message: + o CREATE failed: Can't create mailbox node xxxxxxxxx: File + exists + 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.6 Why does mail disappear even though I set "keep mail on + server"? + + 7.7 Why do I get the message + o Moved ##### bytes of new mail to /home/user/mbox from + /var/spool/mail/user + and why did this happen? + + 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.10 What does the message: + o Mailbox vulnerable - directory /var/spool/mail must have + 1777 protection + mean? How can I fix this? + + 7.11 What does the message: + o Mailbox is open by another process, access is readonly + mean? How do I fix this? + + 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.14 What do messages such as: + o Message ... UID ... already has UID ... + o Message ... UID ... less than ... + o Message ... UID ... greater than last ... + o Invalid UID ... in message ..., rebuilding UIDs + mean? + + 7.15 What do the error messages: + o Unable to read internal header at ... + o Unable to find CRLF at ... + o Unable to parse internal header at ... + o Unable to parse message date at ... + o Unable to parse message flags at ... + o Unable to parse message UID at ... + o Unable to parse message size at ... + o Last message (at ... ) runs past end of file ... + mean? I am using mbx format. + + 7.16 What do the syslog messages: + o imap/tcp server failing (looping) + o pop3/tcp server failing (looping) + 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 + mean? + + 7.18 What do the syslog messages: + o Command stream end of file, while reading line user=... + host=... + o Command stream end of file, while reading char user=... + host=... + o Command stream end of file, while writing text user=... + host=... + mean? + + 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.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 + 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(). + + 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 + syslog has the message: + o Autologout user=<...my user name...> host=<...my imap + server...> + + 7.28 What does the UNIX error message: + o TLS/SSL failure: myserver: SSL negotiation failed + mean? + + 7.29 What does the PC error message: + o TLS/SSL failure: myserver: Unexpected TCP input + disconnect + mean? + + 7.30 What does the error message: + o TLS/SSL failure: myserver: Server name does not match + certificate + mean? + + 7.31 What does the UNIX error message: + o TLS/SSL failure: myserver: self-signed certificate + mean? + + 7.32 What does the PC error message + o TLS/SSL failure: myserver: Self-signed certificate or + untrusted authority + mean? + + 7.33 What does the UNIX error message: + o TLS/SSL failure: myserver: unable to get local issuer + certificate + mean? + + 7.34 Why does reading certain messages hang when using + Netscape? It works fine with Pine! + + 7.35 Why does Netscape say that there's a problem with the + IMAP server and that I should "Contact your mail server + administrator."? + + 7.36 Why is one user creating huge numbers of IMAP or POP + server sessions? + + 7.37 Why don't I get any new mail notifications from Outlook + Express or Outlook after a while? + + 7.38 Why don't I get any new mail notifications from + Entourage? + + 7.39 Why doesn't Entourage work at all? + + 7.40 Why doesn't Netscape Notify (NSNOTIFY.EXE) work at all? + + 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 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 + 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 + IMAP. How can I fix this? + + 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! + and why did this happen? There was also something about + o SECURITY PROBLEM: insecure server advertised AUTH=PLAIN + + 7.47 Why do I get the message + o SMTP Authentication cancelled + and why did this happen? There was also something about + o SECURITY PROBLEM: insecure server advertised AUTH=PLAIN + + 7.48 Why do I get the message + o Invalid base64 string + 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.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? + _________________________________________________________________ + +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. + _________________________________________________________________ + + 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? + + Not necessarily. + + 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. + + If you are happy with qpopper and just want to add imapd, you + should do that, and defer a decision on changing qpopper to + ipop3d. That way, you can get comfortable with imapd's + 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. + _________________________________________________________________ + + 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 + md5.txt. + + There is no file access control on Windows 9x or Me, so you + probably will have to do modifications to env_unix.c to prevent + people from hacking others' mail. + + Note, however, that the server is not plug and play the way it + is for UNIX. + _________________________________________________________________ + + 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. + _________________________________________________________________ + + 1.7 Can I set up a POP or IMAP server on TOPS-20? + + You have a TOPS-20 system? Cool. + + 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 + clients won't work with IMAP2 at all. Maybe someone will hack + MAPSER to do IMAP4rev1 some day. + + We don't know if anyone wrote a POP3 server for TOPS-20. There + definitely was a POP2 server once upon a time. + + 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. + _________________________________________________________________ + + 1.8 Are hierarchical mailboxes supported? + 1.9 Are "dual-use" mailboxes supported? + 1.10 Can I have a mailbox that has both messages and sub-mailboxes? + + Yes. However, there is one important caveat. + + Some mailbox formats, including the default which is the + traditional UNIX mailbox format, are stored as a single file + containing all the messages. UNIX does not permit a name in the + filesystem to be both a file and a directory; consequently you + can not have a sub-mailbox within a mailbox that is in one of + these formats. + + This is not a limitation of the software; this is a limitation + of UNIX. For example, there are mailbox formats in which the + name is a 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 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/". + + 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. + + Of course, on Windows systems you would use "\" instead of "/". + _________________________________________________________________ + + 1.11 What is the difference between "mailbox" and "folder"? + + The term "mailbox" is IMAP-speak for what a lot of software + calls a "folder" or a "mail folder". However, "folder" is often + used in other contexts to refer to a directory, for example, in + the graphic user interface on both Windows and Macintosh. + + A "mailbox" is specifically defined as a named object that + contains messages. It is not required to be capable of + containing other types of objects including other mailboxes; + 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 + "no-select name". + _________________________________________________________________ + + 1.12 What is the status of internationalization? + + The IMAP toolkit is partially internationalized and + multilingualized. + + 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. + + All ISO-2022-?? charsets are treated identically, and support + ASCII, JIS Roman, hankaku katakana, ISO-8859-[1 - 10], TIS, GB + 2312, JIS X 0208, JIS X 0212, KSC 5601, and planes 1 and 2 of + CNS 11643. + + EUC-JP includes support for JIS X 0212 and hankaku katakana. + + c-client library support also exists to convert text in any of + the above charsets into Unicode, including headers with MIME + encoded-words. + + There is no support for localization (e.g. non-English error + messages) at the present time, but such support is planned. + _________________________________________________________________ + + 1.13 Can I use SSL? + + Yes. See the answer to the How do I configure SSL? question. + _________________________________________________________________ + + 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. + _________________________________________________________________ + + 1.15 Can I use CRAM-MD5 authentication? + + Yes. See the answer to the How do I configure CRAM-MD5 + authentication? question. + _________________________________________________________________ + + 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. + _________________________________________________________________ + + 1.17 Can I use Kerberos V5? + + Yes. See the answer to the How do I configure Kerberos V5? + question. + _________________________________________________________________ + + 1.18 Can I use PAM for plaintext passwords? + + Yes. See the answer to the How do I configure PAM for plaintext + passwords? question. + _________________________________________________________________ + + 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. + _________________________________________________________________ + + 1.20 Can I use AFS for plaintext passwords? + + Yes. See the answer to the How do I configure AFS for plaintext + passwords? question. + _________________________________________________________________ + + 1.21 Can I use DCE for plaintext passwords? + + Yes. See the answer to the How do I configure DCE for plaintext + passwords? question. + _________________________________________________________________ + + 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. + _________________________________________________________________ + + 1.23 Can I disable plaintext passwords? + + Yes. See the answer to the How do I disable plaintext + passwords? question. + _________________________________________________________________ + + 1.24 Can I disable plaintext passwords on unencrypted sessions, but + allow them on encrypted sessions? + + Yes. See the answer to the How do I disable plaintext passwords + on unencrypted sessions, but allow them in SSL or TLS sessions? + question. + _________________________________________________________________ + + 1.25 Can I use virtual hosts? + + Yes. See the answer to the How do I configure virtual hosts? + question. + _________________________________________________________________ + + 1.26 Can I use RPOP authentication? + + There is no support for RPOP authentication. + _________________________________________________________________ + + 1.27 Can I use Kerberos V4? + + Kerberos V4 is not supported. Kerberos V4 client-only + contributed code is available in + +ftp://ftp.cac.washington.edu/mail/kerberos4-patches.tar.Z + + 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. + _________________________________________________________________ + + 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. + _________________________________________________________________ + + 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 may be an NTLM SASL authenticator available from third + parties. + _________________________________________________________________ + + 1.30 Is there support for mh? + + Yes, but only as a legacy format. Your mh format INBOX is + accessed by the name "#mhinbox", and all other mh format + mailboxes are accessed by prefixing "#mh/" to the name, e.g. + "#mh/foo". The mh support uses the "Path:" entry in your + .mh_profile file to identify the root directory of your mh + format mailboxes. + + 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. + _________________________________________________________________ + + 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. + _________________________________________________________________ + + 1.32 Is there support for the Cyrus mailbox format? + + No. + _________________________________________________________________ + + 1.33 Is this software Y2K compliant? + + Please read the files Y2K and calendar.txt. + _________________________________________________________________ + +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. + _________________________________________________________________ + + 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? + + 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. + _________________________________________________________________ + + 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 do not need to install the entire Platform SDK; it suffices + to install just the Core SDK and the Internet Development SDK. + _________________________________________________________________ + + 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. + _________________________________________________________________ + + 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. + _________________________________________________________________ + + 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. + _________________________________________________________________ + + 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. + _________________________________________________________________ + + 2.9 What do I need to build this software on TOPS-20? + + You need the TOPS-20 KCC compiler. + _________________________________________________________________ + + 2.10 What do I need to build this software on Amiga or OS/2? + + We don't know. + _________________________________________________________________ + + 2.11 What do I need to build this software on Windows CE? + + This port is incomplete. Someone needs to finish it. + _________________________________________________________________ + +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 + instructions. It can't be that easy. Don't I need to write a config + file? + + For ordinary "vanilla" UNIX systems, this software is plug and + play; just build it, install it, and you're done. If you have a + modified system, then you may want to do additional work; most + of this is to a single source code file (env_unix.c on UNIX + systems). Read the file CONFIG for more details. + + 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? + 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. + _________________________________________________________________ + + 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 + 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. + + SSL is supported via undocumented Microsoft interfaces in + Windows 9x and NT4; and via standard interfaces in Windows + 2000, Windows Millenium, and Windows XP. + _________________________________________________________________ + + 3.7 How do I build/install OpenSSL and obtain/create certificates for + use with SSL? + + If you need help in doing this, try the contacts mentioned in + the OpenSSL README. We do not offer support for OpenSSL or + certificates. + _________________________________________________________________ + + 3.8 How do I configure CRAM-MD5 authentication? + 3.9 How do I configure APOP authentication? + + CRAM-MD5 authentication is enabled in the IMAP and POP3 client + code on all platforms. Read md5.txt to learn how to set up + CRAM-MD5 and APOP authentication on UNIX and NT servers. + + There is no support for APOP client authentication. + _________________________________________________________________ + + 3.10 How do I configure Kerberos V5? + + imap-2007 supports client and server functionality on UNIX and + 32-bit Windows. + + Kerberos V5 is supported by default in Windows 2000 builds: + + nmake -f makefile.w2k + + Other builds require that a third-party Kerberos package, e.g. + MIT Kerberos, be installed on the system first. + + To build with Kerberos V5 on UNIX, include + EXTRAAUTHENTICATORS=gss in the make command line, e.g. + + make lnp EXTRAAUTHENTICATORS=gss + + To build with Kerberos V5 on Windows 9x, Windows Millenium, and + NT4, use the "makefile.ntk" file instead of "makefile.nt": + + + nmake -f makefile.ntk + _________________________________________________________________ + + 3.11 How do I configure PAM for plaintext passwords? + + On Linux systems, use the lnp port, e.g. + + make lnp + + On Solaris systems and other systems with defective PAM + implementations, build with PASSWDTYPE=pmb, e.g. + + make sol PASSWDTYPE=pmb + + On all other systems, build with PASSWDTYPE=pam, e.g + + make foo PASSWDTYPE=pam + + If you build with PASSWDTYPE=pam and authentication does not + work, try rebuilding (after a "make clean") with + PASSWDTYPE=pmb. + _________________________________________________________________ + + 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? + + Yes and no. + + Doing this will make plaintext password authentication use the + Kerberos password instead of the /etc/passwd password. + + 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. + _________________________________________________________________ + + 3.13 How do I configure Kerberos 5 for plaintext passwords? + + Build with PASSWDTYPE=gss, e.g. + + make sol PASSWDTYPE=gss + + 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. + _________________________________________________________________ + + 3.14 How do I configure AFS for plaintext passwords? + + Build with PASSWDTYPE=afs, e.g + + make sol PASSWDTYPE=afs + _________________________________________________________________ + + 3.15 How do I configure DCE for plaintext passwords? + + Build with PASSWDTYPE=dce, e.g + + make sol PASSWDTYPE=dce + _________________________________________________________________ + + 3.16 How do I configure the CRAM-MD5 database for plaintext passwords? + + The CRAM-MD5 password database is automatically used for + plaintext password if it exists. + + 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. + _________________________________________________________________ + + 3.17 How do I disable plaintext passwords? + + Server-level plaintext passwords can be disabled by setting + PASSWDTYPE=nul, e.g. + + 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. + + When plaintext passwords are disabled, the IMAP server will + advertise the LOGINDISABLED capability and the POP3 server will + not advertise the USER capability. + + 3.18 How do I disable plaintext passwords on unencrypted sessions, but + allow them in SSL or TLS sessions? + + Do not set PASSWDTYPE=nul or SSLTYPE=unix. Set SSLTYPE=nopwd + instead, e.g. + + make lnx SSLTYPE=nopwd + + When plaintext passwords are disabled, the IMAP server will + advertise the LOGINDISABLED capability and the POP3 server will + not advertise the USER capability. + + Plaintext passwords will always be enabled in SSL sessions; the + IMAP server will not advertise the LOGINDISABLED capability and + the POP3 server will advertise the USER capability. + + If the client does a successful start-TLS in a non-SSL session, + 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. + _________________________________________________________________ + + 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. + + As distributed, the software uses a global password file; hence + user "fred" on one virtual host is "fred" on all virtual hosts. + You may want to modify the checkpw() routine to implement some + other policy (e.g. separate password files). + + Note that the security model assumes that all users have their + own unique UNIX UID number. So if you use separate password + files you should make certain that the UID numbers do not + overlap between different files. + + More advanced virtual host support may be available as patches + from third parties. + _________________________________________________________________ + + 3.20 Why do I get compiler warning messages such as: + passing arg 3 of `scandir' from incompatible pointer type + Pointers are not assignment-compatible. + Argument #4 is not the correct type. + + during the build? + + You can safely ignore these messages. + + 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 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. + _________________________________________________________________ + + 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. + Pointers are not assignment-compatible. + Argument #5 is not the correct type. + + during the build? + + You can safely ignore these messages. + + 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: + + K.5.7 Function pointer casts + [#1] A pointer to an object or to void may be cast to a pointer + to a function, allowing data to be invoked as a function (6.3.4). + [#2] A pointer to a function may be cast to a pointer to an + 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. + _________________________________________________________________ + + 3.22 Why do I get linker warning messages such as: +mtest.c:515: the `gets' function is dangerous and should not be used. + + during the build? Isn't this a security bug? + + You can safely ignore this message. + + Certain linkers, most notably on Linux, give this warning + message. It is indeed true that the traditional gets() function + is not a safe one. + + However, the mtest program is only a demonstration program, a + model of a very basic application program using c-client. It is + not something that you would install, much less run in any + security-sensitive context. + + mtest has numerous other shortcuts that you wouldn't want to do + in a real application program. + + The only "security bug" with mtest would be if it was run by + some script in a security-sensitive context, but mtest isn't + particularly useful for such purposes. If you wanted to write a + 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. + + 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. + _________________________________________________________________ + + 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. + + during the build? Isn't this a security bug? + + You can safely ignore this message. + + Certain linkers, most notably on Linux, give this warning + message, based upon two known issues with tmpnam(): + + there can be a buffer overflow if an inadequate buffer is + allocated. + there can be a timing race caused by certain incautious + usage of the return value. + + 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. + _________________________________________________________________ + + 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? + + Please forward the details for investigation. + _________________________________________________________________ + +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. + _________________________________________________________________ + + 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. + _________________________________________________________________ + + 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 + noticed that it can connect on port 143, port 993, via rsh, and via + ssh. + + c-client chooses how to establish an IMAP connection via the + following rules: + + + If /ssl is specified, use an SSL connection. Fail otherwise. + + Else if client is a UNIX system and "ssh server exec + /etc/rimapd" works, use that + + Else if /tryssl is specified and an SSL connection works, use + that. + + Else if client is a UNIX system and "rsh server exec + /etc/rimapd" works, use that. + + Else use a non-SSL connection. + _________________________________________________________________ + + 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 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. + _________________________________________________________________ + + 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 access. + + The rumors about mbx 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. + + Some of the formats, including mbx, 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. + + 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 + 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, + just use the name ("foo" in this example); the software will + automatically select the driver for mbx 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 + 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. + + Most other servers (e.g. Cyrus) require use of a non-standard + format. A full-fledged format conversion is not significantly + different from what you have to do with other servers. The + difference, which makes format conversion procedures somewhat + more complicated with this server, is that there is no "all or + nothing" requirement with this server. There are many points in + between. A format conversion can be anything from a single + mailbox or single user, to systemwide. + + This is good in that you can decide how far to go, or do the + steps incrementally as you become more comfortable with the + 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. + _________________________________________________________________ + + 4.6 How do I set up shared mailboxes? + + At the simplest level, a shared mailbox is one which has UNIX + file and directory protections which permit multiple users to + access it. What this means is that your existing skills and + tools to create and manage shared files on your UNIX system + apply to shared mailboxes; e.g. + + chmod 666 mailbox + + 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 + 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. + + #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 + "imappublic". For example, #public/foo/bar refers to the file + ~imappublic/foo/bar. Public files are available to anonymous + IMAP logins. By default, newly-created files in #public are + created with protection 0666. + + #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. + _________________________________________________________________ + + 4.7 How can I make the server syslogs go to someplace other than the + mail syslog? + + The openlog() call that sets the syslog facility is in + src/osdep/unix/env_unix.c in routine server_init(). You need to + edit this file to change the syslog facility from LOG_MAIL to + the facility you want, then rebuild. You also need to set up + your /etc/syslog.conf properly. + + Refer to the man pages for syslog and syslogd for more + 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. + _________________________________________________________________ + +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? + + You should not worry about this if your IMAP users are allowed + shell access. The IMAP server does not permit any access that + the user can not have via the shell. + + If, and only if, you deny your IMAP users shell access, you may + want to consider one of three choices. Note that these choices + reduce IMAP functionality, and may have undesirable side + effects. Each of these choices involves an edit to file + src/osdep/unix/env_unix.c + + 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. + + 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." + + 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. + _________________________________________________________________ + + 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. + + 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. + + It's unfortunate that any vulnerabilities existed in past + versions, and we're doing my best to keep the IMAP toolkit free + of vulnerabilities. No new vulnerabilities have been discovered + in quite a while, but efforts will not be relaxed. + + Beware of vendors who claim that their implementations can not + have vulnerabilities. + _________________________________________________________________ + + 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. + + 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 + _________________________________________________________________ + + 5.4 I see all these strcpy() and sprintf() calls, those are unsafe, + aren't they? + + Yes and no. + + It can be unsafe to do these calls if you do not know that the + 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 + + strcpy (s,t); + + to + + strncpy (s,t,n)[n] = '\0'; + + and similar measures in the name of "fixing all possible buffer + overflows." + + 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 + 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. + + With all this in mind, the software has been inspected, and it + is believed that all places where buffer overflows can happen + have been fixed. The strcpy()s that are still are in the code + occur after a size check was done in some other way. + + Note that the common C idiom of + + *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. + + Nothing replaces careful study of code. That's how the bad guys + find bugs. Security is not accomplished by means of brute-force + shortcuts. + _________________________________________________________________ + + 5.5 Those /tmp lock files are protected 666, is that really right? + + Yes. Shared mailboxes won't work otherwise. Also, you get into + accidental denial of service problems with old lock files left + lying around; this happens fairly frequently. + + The deliberate mischief that can be caused by fiddling with the + lock files is small-scale; harassment level at most. There are + many -- and much more effective -- other ways of harassing + another user on UNIX. It's usually not difficult to determine + the culprit. + + Before worrying about deliberate mischief, worry first about + things happening by accident! + _________________________________________________________________ + +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 + programs add another layer of complexity to an already complex + process. + + Coaxing software that uses autoconfig to build properly on + 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. + + 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. + _________________________________________________________________ + + 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: + + + The compiler does not support -g + + 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. + + -g has not been arbitrarily added to the ports which do not + currently have it because we don't know if doing so would break + the build. However, any support issues with one of those port + 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. + _________________________________________________________________ + + 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. + + 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. + + 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. + + 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. + + 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. + + Memory is so cheap these days that it's not worth it. Human + life is too short to deal with shared library compatibility + problems. + _________________________________________________________________ + + 6.4 Why don't you use iconv() for internationalization support? + + iconv() is not ubiquitous enough. + _________________________________________________________________ + + 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 also doesn't know whether your preferred + subdirectory for mailbox files is "mail/", ".mail/", "Mail/", + "Mailboxes/", or any of a zillion other possibilities. If one + such name were chosen, it would undoubtably anger the partisans + of all the other names. + + 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? + + 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. + + Basically, unless you're an email software hacker, you probably + want to look elsewhere if you want IMAP/POP servers for + Windows. + _________________________________________________________________ + + 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 + the full size? + + This is to avoid an interoperability problem with: + + + PC IMAP clients that use Microsoft's SChannel.DLL (SSPI) for + 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. + + 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 + 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. + + There wasn't a significant difference that we could measure + between 8K and 15K. + + 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 any client that transmits + full-sized SSL payloads. + _________________________________________________________________ + + 6.8 Why is an mh format INBOX called #mhinbox instead of just INBOX? + + It's a long story. In brief, the mh format driver is less + functional than any of the other drivers. It turned out that + there were some users (including high-level administrators) who + tried mh years ago and no longer use it, but still had an mh + profile left behind. + + 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. + _________________________________________________________________ + + 6.9 Why don't you support the maildir format? + + It is technically difficult to support maildir in IMAP while + maintaining acceptable performance, robustness, following the + requirements of the IMAP protocol specification, and following + the requirements of maildir. + + 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. + + 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. + _________________________________________________________________ + + 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. + + 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. + _________________________________________________________________ + + 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. + + This design flaw causes unexpected loss of lock, and consequent + mailbox corruption. The workaround is to do certain "dangerous + operations" in another fork, thus avoiding doing a close() in + the vulnerable fork. + + The best way to solve this problem is to upgrade your SVR4 + (Solaris, AIX, HP-UX, SGI) or OSF/1 system to a more advanced + operating system, such as Linux or BSD. These more advanced + operating systems have fcntl() locking for compatibility with + 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(). + _________________________________________________________________ + + 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 + just considers every line that starts with "From " to be the start of + the message. + + You just answered your own question. If any line that starts + with "From " is treated as the start of a message, then every + message text line which starts with "From " has to be quoted + (typically by prefixing a ">" character). People complain about + this -- "why did a > get stuck in my message?" + + So, good mail reading software only considers a line to be a + "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. + + 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. + + 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 + and ancient history, you should seriously consider using the + c-client library (e.g. routine mail_append()) instead of doing + the file writes yourself. If you must do it yourself, use + ctime(), as in: + + 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. + _________________________________________________________________ + + 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. + _________________________________________________________________ + + 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? + + This pseudo-message serves two purposes. + + First, it establishes the mailbox format even when the mailbox + has no messages. Otherwise, a mailbox with no messages is a + zero-byte file, which could be one of several formats. + + 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. + _________________________________________________________________ + + 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. + + 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. + _________________________________________________________________ + + 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. + _________________________________________________________________ + + 6.17 Why do you use ucbcc to build on Solaris? + + It is a long, long story about why cc is set to ucbcc. You need + to invoke the C compiler so that it links with the SVR4 + 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 + 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. + + 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, + that's a pretty good indicator that you goofed and are running + the compiler that will link with the BSD libraries. + + To recap: + + + The sol port is designed to be built using the UCB compiler + 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 + + 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. + _________________________________________________________________ + + 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. + + Too many sites have fallen victim to this problem. + _________________________________________________________________ + + 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. + _________________________________________________________________ + + 6.20 Why should I care about compatibility with the past? + + This is one of those questions in which the answer never + 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. + _________________________________________________________________ + +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.: + + 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? + + 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.: + + From fred@foo.bar Mon May 7 20:54:30 2001 + _________________________________________________________________ + + 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. + _________________________________________________________________ + + 7.4 Why can't I log in to the server? The user name and password are + right! + + There are a myriad number of possible answers to this question. + The only way to say for sure what is wrong is run the server + 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. + + Here are some of the more common reasons why login may fail: + + + You didn't really give the correct user name and/or password. + + Your client doesn't send the LOGIN command correctly; for + example, IMAP2 clients won't send a password containing a "*" + correctly to an IMAP4 server. + + If you have set up a CRAM-MD5 database, remember that the + password used is the one in the CRAM-MD5 database, and + furthermore that there must also be an entry in /etc/passwd + (but the /etc/passwd password is not 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. + + 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! + + 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. + + 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. + + 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. + + 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. + _________________________________________________________________ + + 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 + /home/user/mbox from /var/spool/mail/user and why did this happen? + + This is probably caused by the mbox driver. If the file "mbox" + 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. + + 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. + _________________________________________________________________ + + 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? + + Your UNIX system is misconfigured. The entry for your system in + /etc/hosts must have the fully-qualified domain name first, + e.g. + + 105.69.1.234 myserver.example.com myserver + + A common mistake of novice system administrators is to have the + short name first, e.g. + + 105.69.1.234 myserver myserver.example.com + + or to omit the fully qualified domain name entirely, e.g. + + 105.69.1.234 myserver + + The result of this is that when the IMAP toolkit does a + gethostbyname() call to get the fully-qualified domain name, it + would get "myserver" instead of "myserver.example.com". + + 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. + + 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 + documentation assumes a corporate network that is not connected + to the Internet. + + net.folklore once (late 1980s) held that the proper procedure + was to append the results of getdomainname() to the name + returned by gethostname(), and some versions of sendmail + configuration files were distributed that did this. This was + incorrect; the string returned from getdomainname() is the + Yellow Pages (a.k.a NIS) domain name, which is a completely + different (albeit unfortunately named) entity from an Internet + domain. These were often fortuitously the same string, except + when they weren't. Frequently, this would result in host names + with spuriously doubled domain names, e.g. + + myserver.example.com.example.com + + This practice has been thoroughly discredited for many years, + but folklore dies hard. + _________________________________________________________________ + + 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. + + Directory protection 1777 is secure enough on most well-managed + systems. If you can't trust your users with a 1777 mail spool + (petty harassment is about the limit of the abuse exposure), + then you have much worse problems then that. + + If you absolutely insist upon requiring privileges to create a + lock file, external file locking can be done via a setgid mail + program named /etc/mlock (this is defined by LOCKPGM in the + c-client Makefile). If the toolkit is unable to create a + <...mailbox...>.lock file in the directory by itself, it will + 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. + _________________________________________________________________ + + 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. + + 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. + _________________________________________________________________ + + 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. + _________________________________________________________________ + + 7.13 I set my POP3 client to "delete messages from server" but they + never get deleted. What is wrong? + + Make sure that your mailbox is not read-only: that the mailbox + is owned by you and write enabled (protection 0600), and that + the /tmp directory is longer world-writeable. /tmp must be + world-writeable because lots of applications use it for scratch + space. To fix this, do + + + chmod 1777 /tmp + + as root. + + Make sure that your POP3 client issues a QUIT command when it + 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. + _________________________________________________________________ + + 7.14 What do messages such as: + Message ... UID ... already has UID ... + Message ... UID ... less than ... + Message ... UID ... greater than last ... + Invalid UID ... in message ..., rebuilding UIDs + + mean? + + 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. + + This problem is relatively harmless; a new valid unique + identifier regime will be created. The main effect is that any + references to the old UIDs will no longer be useful. + + So, unless it is a chronic problem or you feel like debugging, + you can safely ignore these messages. + _________________________________________________________________ + + 7.15 What do the error messages: + Unable to read internal header at ... + Unable to find CRLF at ... + Unable to parse internal header at ... + Unable to parse message date at ... + Unable to parse message flags at ... + Unable to parse message UID at ... + Unable to parse message size at ... + Last message (at ... ) runs past end of file ... + + mean? I am using mbx format. + + The mbx-format mailbox is corrupted and needs to be repaired. + + You should make an effort to find out why the corruption + happened. Was there an obvious system problem (crash or disk + failure)? Did the user accidentally access the file via NFS? + Mailboxes don't get corrupted by themselves; something caused + the problem. + + Some people have developed automated scripts, but if you're + comfortable using emacs it's pretty easy to fix it manually. Do + not use vi or any other editor unless you are certain that + 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. + + 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 + + The problem occurs at the 43,931 byte in the file. That's the + point you need to fix. c-client is expecting an internal header + at that byte number, looking something like: + + 6-Jan-1998 17:42:24 -0800,1045;000000100001-00000001 + + The format of this internal line is: + + dd-mmm-yyyy hh:mm:ss +zzzz,ssss;ffffffffFFFF-UUUUUUUU + + The only thing that is variable is the "ssss" field, it can be + as many digits as needed. All other fields (inluding the "dd") + are fixed width. So, the easiest thing to do is to look forward + in the file for the next internal header, and delete everything + from the error point to that internal header. + + 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. + + Mark where you are in the file, move the cursor to the line + after the internal header, and skip that many bytes ("ssss") + forward. If you're at the point of the error in the file, then + that message is corrupt. If you're at a different point, then + perhaps the previous message is corrupt and has a too long size + count that "ate" into this message. + + Basically, what you need to do is make sure that all those size + counts are right, and that moving "ssss" bytes from the line + after the internal header will land you at another internal + 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. + + 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. + + In this example, suppose that the corrupt file is INBOX, the + error message is + + Unable to find CRLF at 132551754 + + and the size of the INBOX file is 132867870 bytes. + + The first step is to split the mailbox file at the point of the + 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. + + 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. + + Now, remove the erroneous data: + + + Verify that you can open INBOX.new in IMAP or Pine. + + 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"). + + 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. + + Reinstall INBOX.new as INBOX: + + + Check to see if you have received any new messages while + repairing INBOX. + + If you haven't received any new messages while repairing + INBOX, just rename INBOX.new to INBOX. + + If you have received new messages, be sure to copy the new + 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 + salvaging; otherwise you can delete the two badmsg files. + _________________________________________________________________ + + 7.16 What do the syslog messages: + + imap/tcp server failing (looping) + pop3/tcp server failing (looping) + + 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. + + inetd has a limit of 40 new server sessions per minute for any + particular service. If more than 40 sessions are initiated in a + minute, inetd will issue the "failing (looping), service + terminated" message and shut down the service for 10 minutes. + 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! + + 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: + + imap stream tcp nowait root /usr/etc/imapd imapd + + try changing it to be: + + imap stream tcp nowait.100 root /usr/etc/imapd imapd + + Another example (using TCP wrappers): + + imap stream tcp nowait root /usr/sbin/tcpd imapd + + try changing it to be: + + imap stream tcp nowait.100 root /usr/sbin/tcpd imapd + + to increase the limit to 100 sessions/minute. + + Before making this change, please read the information in "man + inetd" to determine whether or not your inetd has this feature. + If it does not, and you make this change, the likely outcome is + 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. + _________________________________________________________________ + + 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 + + chmod 1777 /tmp + + as root. + + If that isn't the answer, check the protection of the named + 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. + _________________________________________________________________ + + 7.18 What do the syslog messages: + Command stream end of file, while reading line user=... host=... + Command stream end of file, while reading char user=... host=... + Command stream end of file, while writing text user=... host=... + + mean? + + This message occurs when the session is disconnected without a + 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". + + The condition could, however, indicate a client or network + connectivity problem. The server has no way of knowing whether + there's a problem or just a rude client, so it issues this + message instead of a Logout. + + Certain inferior losing clients disconnect abruptly after a + 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! + 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=... + + 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. + + Another cause of this message is a background "check for new + mail" task which does its work by opening a POP session to + server every few seconds. They do this because POP doesn't have + 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 + waste on POP clients and poorly-designed IMAP clients. + _________________________________________________________________ + + 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? + + 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!). + + 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 problem. + + See also the answer to Why does my IMAP client show all my + files in my home directory? + _________________________________________________________________ + + 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. + + 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. + _________________________________________________________________ + + 7.23 Why does my IMAP client show all my files in my home directory? + + As distributed, the IMAP server is connected to your home + directory by default. It 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. + + Most clients have an option to configure your connected + directory on the IMAP server. For example, in Pine you can + specify this as the "Path" in your folder-collection, e.g. + + Nickname : Secondary Folders + Server : imap.example.com + Path : mail/ + View : + + In this example, the user is connected to the "mail" + subdirectory of his home directory. + + Other servers call this the "folder prefix" or similar term. + + It is possible to modify the IMAP server so that all users are + automatically connected to some other directory, e.g. a + subdirectory of the user's home directory. Read the file CONFIG + for more details. + _________________________________________________________________ + + 7.24 Why is there a long delay before I get connected to the IMAP or + POP server, no matter what client I use? + + There are two common occurances of this problem: + + + You are running a system (e.g. certain versions of Linux) + which by default attempts to connect to an "IDENT" protocol + (port 113) server on your client. However, a firewall or NAT + box is blocking connections to that port, so the connection + attempt times out. + 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. + 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 + no separate concept of "system administrator" vs. + "unprivileged user". + On either type of system, security-minded people either turn + IDENT off or replace it with an IDENT server that lies. Among + other things, IDENT gives spammers the ability to harvest + email addresses from anyone who connects to a web page. + This problem has been showing up quite frequently on systems + which use xinetd instead of inetd. Look for files named + /etc/xinetd.conf, /etc/xinetd.d/imapd, /etc/inetd.d/ipop2d, + and /etc/xinetd.d/ipop3d. In those files, look for lines + containing "USERID", e.g. + 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 + 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 + 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(). + + 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. + + 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. + + 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. + {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); + _________________________________________________________________ + + 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. + + 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). + + One symptom of the problem is that under certain circumstances, + a message may get broken up into several messages. I'm also + aware of security bugs caused by programs that foolishly trust + "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: + + 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. + _________________________________________________________________ + + 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. + + 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. + _________________________________________________________________ + + 7.28 What does the UNIX error message: TLS/SSL failure: myserver: SSL + negotiation failed mean? + 7.29 What does the PC error message: TLS/SSL failure: myserver: + Unexpected TCP input disconnect mean? + + This usually means that an attempt to negotiate TLS encryption + via the STARTTLS command failed, because the server advertises + STARTTLS functionality, but doesn't actually have it (e.g. + because no certificates are installed). + + Use the /notls option in the mailbox name to disable TLS + negotiation. + _________________________________________________________________ + + 7.30 What does the error message: TLS/SSL failure: myserver: Server + name does not match certificate mean? + + An SSL or TLS session encryption failed because the server name + in the server's certificate does not match the name that you + gave it. This could indicate that the server is not really the + system you think that it is, but can be also be called if you + gave a nickname for the server or name that was not + fully-qualified. You must use the fully-qualified domain name + for the server in order to validate its certificate + + Use the /novalidate-cert option in the mailbox name to disable + validation of the certificate. + _________________________________________________________________ + + 7.31 What does the UNIX error message: TLS/SSL failure: myserver: + self-signed certificate mean? + 7.32 What does the PC error message: TLS/SSL failure: myserver: + Self-signed certificate or untrusted authority mean? + + 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. + + Use the /novalidate-cert option in the mailbox name to disable + validation of the certificate. + _________________________________________________________________ + + 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 + possible to validate the server's certificate. + + If CA certificates are properly installed, you should see + factory.pem and about a dozen other .pem names such as + thawteCb.pem. + + 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. + + 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. + _________________________________________________________________ + + 7.34 Why does reading certain messages hang when using Netscape? It + works fine with Pine! + + There are two possible causes. + + Check the mail syslog. If you see the message "Killed (lost + mailbox lock)" for the impacted user(s), read the FAQ entry + 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. + + 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. + _________________________________________________________________ + + 7.35 Why does Netscape say that there's a problem with the IMAP server + and that I should "Contact your mail server administrator."? + + Certain versions of Netscape do this when you click the Manage + Mail button, which uses an undocumented feature of Netscape's + proprietary IMAP server. + + 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. + _________________________________________________________________ + + 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. + _________________________________________________________________ + + 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 + not have any plans to fix it at the present time. + + 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. + + 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. + + Modern versions of imapd attempt to work around the problem by + automatically reporting fake new mail after 29 minutes. This + causes Outlook Express to exit the IDLE state; as soon as this + 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. + _________________________________________________________________ + + 7.38 Why don't I get any new mail notifications from Entourage? + + This is a known bug in Entourage. + + You built an older version of imapd with the + MICROSOFT_BRAIN_DAMAGE option set, in order to disable support + for the IDLE command. However, Entourage won't get new mail + unless IDLE command support exists. + + 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. + _________________________________________________________________ + + 7.39 Why doesn't Entourage work at all? + + It's hard to know. Entourage breaks almost every rule in the + book for IMAP. It is highly instructive to do a packet trace on + Entourage, as an example of how not to use IMAP. It does things + 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 + 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. + _________________________________________________________________ + + 7.40 Why doesn't Netscape Notify (NSNOTIFY.EXE) work at all? + + This is a bug in NSNOTIFY; it doesn't handle unsolicited data + from the server correctly. + + 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. + + Consequently, the recommended fix for the NSNOTIFY problem is + to delete the NSNOTIFY binary. + _________________________________________________________________ + + 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 + file". + + 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. + _________________________________________________________________ + + 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 + 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. + + There are some good GUI clients out there, mostly from smaller + vendors. Without naming names, look for the vendors who are + active in the IMAP protocol development community, and their + 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. + _________________________________________________________________ + + 7.43 But wait! PC Pine (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. + + 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 partial fetching, which tends to reduce the + 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 most recently showed up with the CommunigatePro + IMAP server. They have an update which trims down their maximum + contiguous data to less than 16K, in order to work around the + problem. + + This problem has also shown up with the Exchange IMAP server + with UNIX clients (including Pine 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 + Microsoft Exchange server with *any* UNIX based client that + transmits full-sized SSL payloads. + _________________________________________________________________ + + 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? + + This is an incompatibility between qpopper and the c-client + library used by Pine, 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 + documented as "check for and hide UW 'Folder Internal Data' + messages". + + The other alternative is to switch from qpopper to ipop3d. + _________________________________________________________________ + + 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. + + 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 + /etc/hosts.deny) for the servers? + + If you have a system which uses xinetd instead of inetd, have + you made sure that you have made the correct corresponding + 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 don't know how to make the corresponding changes to + these files, seek the help of a local expert for your system. + _________________________________________________________________ + + 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 + + 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 + already disconnected. + + To work around this, you need to specify /user=... in the host + name specification. + + 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 + 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 + + This is a bug in the SMTP server. + + Some versions of qmail, including that running on + mail.smtp.yahoo.com, have a bug in their implementation of SASL + in their SMTP server, which renders it non-compliant with the + standard. + + If the client does not provide an initial response in the + command line for an authentication mechanism whose profile does + not have an initial challenge, qmail issues a bogus response: + + 334 ok, go on + + The problem is the "ok, go on". This violates RFC 4954's + requirement that the text part in a 334 response be a BASE64 + encoded string; in other words, it is a protocol syntax error. + + 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. + + 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 + cancelled" problem. + _________________________________________________________________ + + 7.48 Why do I get the message Invalid base64 string when I try to + authenticate to a Cyrus server? + + This slightly misleading message is the way that a Cyrus server + indicates that an authentication exchange was cancelled. It is + not indicative of a bug or protocol violation. + + The most common reason that this happens is if the Cyrus server + offers Kerberos authentication, c-client is built with Kerberos + support, but your client system is not within the Kerberos + realm. In this case, the client code will try to authenticate + via Kerberos, fail to get the Kerberos credentials, cancel the + authentication attempt, and try the next available + authentication technology. + _________________________________________________________________ + +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? + + 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 + + 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 + alternative, you can use the comp.mail.imap newsgroup. + _________________________________________________________________ + + 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. + _________________________________________________________________ + + 8.4 Where can I find out more about setting up and administering an + IMAP server? + + 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. + + Last Updated: 15 November 2007 diff --git a/imap/docs/IPv6.txt b/imap/docs/IPv6.txt new file mode 100644 index 00000000..5b1af621 --- /dev/null +++ b/imap/docs/IPv6.txt @@ -0,0 +1,131 @@ +/* ======================================================================== + * Copyright 1988-2006 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 + * + * + * ======================================================================== + */ + +The following information about configuring inetd and xinetd for IPv6 was +contributed by a user. I have not checked it for accuracy or completeness, +but have included it as-is in the hope that it may be useful: + +--------------------------------------------------------------------------- +One thing you might consider adding to the docs are hints for setting up +inetd or xinetd to simultaneously listen on BOTH IPv4 and IPv6 for +different OS. + +Some OS want to see separate IPv4-only and IPv6-only listening sockets +configured in inetd.conf or xinetd.conf. Others will accept IPv4 +connections on lines configured for IPv6 and actually generate errors if +you have both configured when inetd or xinetd start up. It's not clear to +me whether this difference is due to how inetd or xinetd are built or +whether it's due to the kernel's IP stack implementation. I suspect it's +really the latter. Below are some examples: + +Here's a fragment of /usr/local/etc/xinetd.conf for a FreeBSD 4.9 server: + +service imap +{ + socket_type = stream + protocol = tcp + wait = no + user = root + server = /usr/local/libexec/imapd +} +service imap +{ + flags = IPv6 + socket_type = stream + protocol = tcp + wait = no + user = root + server = /usr/local/libexec/imapd +} +service imaps +{ + socket_type = stream + protocol = tcp + wait = no + user = root + server = /usr/local/libexec/imapd +} +service imaps +{ + flags = IPv6 + socket_type = stream + protocol = tcp + wait = no + user = root + server = /usr/local/libexec/imapd +} + +Note that you have to specify a nearly identical paragraph for each +service which differs only by the 'flags = IPv6'. An equivalent +inetd.conf would look something like: + +imap stream tcp nowait root /usr/local/libexec/imapd imapd +imap stream tcp6 nowait root /usr/local/libexec/imapd imapd +imaps stream tcp nowait root /usr/local/libexec/imapd imapd +imaps stream tcp6 nowait root /usr/local/libexec/imapd imapd + +The man pages for inetd suggest that if you use a single entry with +'tcp46' replacing either 'tcp' or 'tcp6' the system will listen on both +types of addresses. At least for the case of FreeBSD this is actually +incorrect. + +Now if you were to use the above xinetd.conf on Fedora Linux, it would +complain. What does work under Linux is to create a single service +paragraph for each service which will accept connections on both IPv4 and +IPv6: + +In /etc/xinetd.d/imap: + +service imap +{ + flags = IPv6 + disable = no + socket_type = stream + wait = no + user = root + server = /usr/local/sbin/imapd +} + +In /etc/xinetd.d/imaps: + +service imaps +{ + flags = IPv6 + disable = no + socket_type = stream + wait = no + user = root + server = /usr/local/sbin/imapd +} + +The man page for xinetd says the IPv6 flag means xinetd will listen ONLY +on IPv6. However the actual behaviour (for Fedora Linux) is to listen on +both IPv4 and IPv6. + +All of the above also applies to ipop3d. Anyway, this might save some +folks a little bit of head scratching time. +--------------------------------------------------------------------------- +Addendum from the original submitter: +--------------------------------------------------------------------------- +I've since learned that the discrepancy really is a function of the OS. +It seems those systems that force you to create separate IPv4 and IPv6 +listeners in inetd (or xinetd) are the same systems that also disable +IPv4-mapped IPv6 addresses by default. This is a boot-time configuration +option. If you enable IPv4-mapped IPv6 addresses, then the 'tcp46' option +in inetd works and the simplified config would look like: + +imap4 stream tcp46 nowait root /usr/local/libexec/imapd imapd +imaps stream tcp46 nowait root /usr/local/libexec/imapd imapd + +In FreeBSD, enabling IPv4-mapped addresses is done by adding +ipv6_ipv4mapping="YES" to /etc/rc.conf (in addition to ipv6_enable="YES"). diff --git a/imap/docs/RELNOTES b/imap/docs/RELNOTES new file mode 100644 index 00000000..5cfd9132 --- /dev/null +++ b/imap/docs/RELNOTES @@ -0,0 +1,787 @@ +/* ======================================================================== + * 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: 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: 29 October 2008 + +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. + + +Updated: 25 March 2008 + +imap-2007b is a maintenance release, consisting primarily of bugfixes to +problems discovered in the release that affected a small number of users. + + +Updated: 2 January 2008 + +imap-2007a is a maintenance release, consisting primarily of bugfixes to +problems discovered in the release that affected a small number of users. + + +Updated: 20 December 2007 + +imap-2007 is a release corresponding with the release of Alpine 1.0. +The primary focus of the imap-2007 release is bugfixes and reliability +improvements. This includes: + . fixes to problems discovered between the Alpine 0.99999 pre-release + and Alpine 1.0 + . fixes to the mix driver to timing race problems uncovered by Timo + Sirainen's imaptest suite. imap-2007 using the mix format is + believed to pass imaptest completely. + +A new function, utf8_csvalidmap(), has been added for the benefit of +Alpine to use in examining UTF-8 text and determining efficiently +whether it can be downgraded to a legacy charset. If you develop an +MUA, this may be useful for you too, although you'll have to read the +source code to see how to use it. The purpose of the "not-CJK" bit is +to prevent messages being downgraded to a CJK charset if all they have +in that charset are some special punctuation. + + +Updated: 5 September 2007 + +imap-2006k is a maintenance release, consisting primarily of bugfixes to +problems discovered in the release that affected a small number of users. + +The primary focus of this maintenance release is to correct deadlock +issues. There were two major causes of the deadlocks: + . a change in imap-2006i attempted to resolve a glibc mutex-based + deadlock in imapd's signal handler, but ended up worsening the problem. + . a bug in the mbx driver, introduced as part of the UIDPLUS work in 2006, + applied an mbx-style lock briefly on a traditional UNIX format mailbox. + If the traditional UNIX format mailbox was already locked by some other + process, the result would be a deadlock of both processes. + +imapd's signal handling logic is rewritten to avoid the mutex issue, and +the mbx driver is fixed so that mbx-style locks are only applied to mbx +format mailboxes. + +imapd now supports the WITHIN extension. + + +Updated: 14 June 2007 + +imap-2006j is a maintenance release, consisting primarily of bugfixes to +problems discovered in the release that affected a small number of users. + + +Updated: 5 June 2007 + +imap-2006i is a maintenance release, consisting primarily of bugfixes to +problems discovered in the release that affected a small number of users. + +imapd now supports the CHILDREN and ESEARCH extensions. + +imapd's attempt to return COPYUID/APPENDUID information for a traditional +UNIX (and MMDF) format mailbox when the mailbox is open by another process +has been declared to be a failure and is now revoked. It was subject to a +timing race, loss of which involved an expensive reset of the mailbox's UID +regime. Any imapd COPY or APPEND to a traditional UNIX or MMDF format that +is open by some other process will now no longer return COPYUID/APPEND. +Although this is technically in violation of RFC 4315, there is a loophole +in that document and the timing race/performance problem is worse. + + +Updated: 4 April 2007 + +imap-2006h is a maintenance release, consisting primarily of bugfixes to +problems discovered in the release that affected a small number of users. + + +Updated: 30 March 2007 + +imap-2006g is a maintenance release, consisting primarily of bugfixes to +problems discovered in the release that affected a small number of users. + + +Updated: 30 January 2007 + +imap-2006f is a maintenance release, consisting primarily of bugfixes to +problems discovered in the release that affected a small number of users. + +For the benefit of multi-threaded applications, use of strtok() has been +abolished in the c-client library. imapd and ipop3d stuff use it though. +The TOPS-20 and VAX/VMS ports still use strtok() since they don't use UNIX +threads. + +This version has been test-built on Linux, Mac OS X, NeXT, Windows XP, +TOPS-20, and VAX/VMS. This will probably be the last test-build on VAX/VMS +since the system I use for that purpose is being shut down. I have no way +to test-build on DOS, legacy Mac OS (OS 9 and earlier), OS/2, or Windows CE; +and the builds on those systems are probably broken. + + +Updated: 26 January 2007 + +imap-2006e is a maintenance release, consisting primarily of bugfixes to +problems discovered in the release that affected a small number of users. + + +Updated: 6 December 2006 + +imap-2006d is a maintenance release, consisting primarily of bugfixes to +problems discovered in the release that affected a small number of users. + +The decomposition mapping, title-case mapping, and character widths tables +have been updated to comply with the Unicode 5.0 standard. + +Prototypes for the utf8aux.c functions have been moved to a new utf8aux.h. + +The general c-client modules now include c-client.h instead of the individual +files. Use of c-client.h instead of individual include files insulates +against future shuffling of include files. + + +Updated: 23 October 2006 + +imap-2006c is a maintenance release, consisting primarily of bugfixes to +problems discovered in the release that affected a small number of users. + +By popular request, if a user has a mix (or other dual-use) format INBOX, +it will no longer be listed as \NoInferiors. It's a bad idea to depend +upon this due to the case ambiguity issue, but it's there. + + +Updated: 26 September 2006 + +imap-2006b is a maintenance release, consisting entirely of bugfixes to +problems discovered in the release that affected a small number of users. + + +Updated: 15 September 2006 + +imap-2006a is a maintenance release, consisting entirely of bugfixes to +problems discovered in the release that affected a small number of users. + +If it is necessary to build IPv4-only on one of the ports that has IPv6 +preconfigured (ldb, lfd, lmd, lrh, lsu, osx, oxp), this can be done by +using IP6=4. You can't do IP=4 in the build command directly since these +ports set IP themselves; however, now instead of setting IP=6 they now set +IP=$(IP6). + + +Updated: 30 August 2006 + +imap-2006 is a major release. Programs written for imap-2004g should +build with this version with minor or no modification. imap-2005 was not +released except as development snapshots. + +imap-2006 contains major extensions to its Unicode support. Searching and +sorting are now done with strings canonicalized to titlecase and decomposed +form. Among other things, this means that Latin letters with diacriticals +will now sort with the basic Latin letter, and case-independent searching of +such letters (e.g., German umlauts) now works. Previously, sorting was done +strictly by Unicode codepoint, and case-independence only worked with ASCII. + +imapd now supports the UIDPLUS extension for mailboxes in unix, mmdf, mbx, mx, +and mix formats. UID EXPUNGE is fully implemented. Note that UIDPLUS is not +supported in the little-used drivers (mh, mtx, tenex) in which meaningful +APPENDUID/COPYUID data can not be returned. Refer to bugs.txt for more +details. + +The new mix format is a dual-use mailbox format designed for performance and +reliability with large mailboxes. mix is documented in file mixfmt.txt. + +SSL/TLS certificate validation on UNIX now checks the alternative names in the +certificate if the CN does not match. + +The new /tls-sslv23 flag in a mailbox name causes a TLS session to use the +(incorrect) SSLv23 client method instead of the TLSv1 client method. Some +broken servers use the SSLv23 server method, and this flag works around that +problem. WARNING: use of this flag will cause TLS negotiation to fail with +a server which uses the proper TLSv1 server method. Additionally, there are +known security risks in SSLv2; so users should be suspicious if this switch +suddenly becomes necesary. + +The silly mailbox flag combination /ssl/tls is now rejected as an invalid +remote specification. Previous versions tried to negotiate TLS over an SSL +session; even if the server permitted such a thing it couldn't work. + +The memory management of several drivers has been redesigned to consume less +memory and hopefully be faster. + +The private.data member of the MESSAGECACHE (elt) has been replaced with +a union that contains private.spare.data and private.spare.ptr, the latter +being a pointer. + +A new FT_RETURNSTRINGSTRUCT flag has been added for mail_fetch_body() and +mail_fetch_text() calls. If this flag is set, *and* if the function returns +NIL, then the requested string data is available on a stringstruct on +stream->private.string. This is a special hack for the IMAP and POP servers +and is subject to incompatible change. The result is a major performance +improvement in the servers with the mbx driver, particularly with large +messages. + + +Updated: 15 September 2005 + +imap-2004g is a maintenance release, and consists solely of a bugfix to +quoted string handling in the mailbox name parsing routine. + + +Updated: 15 August 2005 + +imap-2004f is a maintenance release, and consists solely of a bugfix to +the TCP code. + +Also included is a new version of the UNIX SSL/TLS routines that allows the +SSL/TLS certificate validation client code to validate alternative names in +server certificates. This code has not been thoroughly regression-tested but +is believed to work. To use this new code instead of the old support: + cd imap-2004f/src/osdep/unix + mv ssl_unix.c ssl_unix.old + mv ssl_unix.new ssl_unix.c +Then rebuild. + + +Updated: 21 June 2005 + +imap-2004e is a maintenance release, consisting entirely of bugfixes. + +There are no user-visible functional enhancements in this version. + + +Updated: 20 April 2005 + +imap-2004d is a maintenance release, released concurrently with Pine +4.63, and consists primarily of bugfixes + +There is now a workaround for RedHat breaking flock(). However, since +RedHat has said that they don't support flock(), there is no guarantee +that they won't break it in the future. So you may want to consider some +other Linux distribution or BSD instead. See: + https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=123415 +for the gruesome details. + +There are no user-visible functional enhancements in this version. + + +Updated: 18 January 2005 + +imap-2004c is a maintenance release, released concurrently with Pine +4.62, including fixes to quoted-printable encoding and CRAM-MD5 +authentication. + +NNTP proxy in imapd now supports the LIST and LSUB commands. + +There are no other user-visible functional enhancements in this version. + + +Updated: 29 November 2004 + +imap-2004b is a maintenance release, consisting primarily of bugfixes. +Programs written for imap-2004a will build with this version without +modifification. + +There are new ports for Solaris with Blastwave Community Open Source +Software (gcs) and Mandrake Linux (lmd). + +SET_SNARFINTERVAL now controls how frequently local drivers will move new +mail from the mail spool as well as from a maildrop. Maildrops are still +tied to a minimum interval of 1 minute, but there is now no minimum for the +spool file. + +Character set conversions now map non-breaking space to space if the +destination character set doesn't have nbsp. JIS Roman yen sign is now +mapped to Unicode yen sign. + +There are no user-visible functional enhancements in this version. + + +Updated: 8 July 2004 + +imap-2004a is a maintenance release, consisting primarily of critical +bugfixes. Programs written for imap-2004 will build with this version +without modification. + +imapd now has a supported NNTP proxy capability. If the file /etc/imapd.nntp +exists, the contents of that file are used as the host name of an NNTP +server which will be used whenever a #news. name is used. For example, if +/etc/imapd.nntp contains nntp.example.com, and the IMAP client SELECTs or +EXAMINEs the name #news.comp.mail.imap, what will actually be opened in +imapd is {nntp.example.com/nntp}comp.mail.imap + +The OSF/1 port (Digital UNIX, Tru64) now uses flocksim instead of flcksafe. +Some cretin decided to delete the winning flock() call and make flock() use +the losing fcntl() call instead. + +The unix[nt] and mmdf drivers now prevent mail_append() from writing Status:, +X-Status:, X-UID, X-IMAP[base]:, and X-Keywords: header lines to a +traditional UNIX or MMDF format mailbox. If any such lines are in the +text supplied to mail_append(), they will be quoted by prefixing with +"X-Original-" (e.g. Status: will become X-Original-Status:). + +There are no user-visible functional enhancements in this version. + + +Updated: 10 May 2004 + +imap-2004 is a major release. Programs written for imap-2002e should +build with this version with minor modification. imap-2003 was not +released except as development snapshots. + +mailutil has three new commands: delete, rename, and prune. + +IPv6 support now exists for UNIX and W2K. It is the default in W2K builds. +On UNIX, add "IP=6" to the make command line. Windows IPv6 support is +only for W2K builds. + +The NNTP driver now supports NNTP SASL and TLS. + +The ldb (Debian) and lrh (RedHat) ports now look for mlock on +/usr/sbin/mlock instead of /etc/mlock. + +imapd now supports the LITERAL+ and SASL-IR initial-response extensions. + +The IMAP driver has some additional checks to reduce the amount of network +traffic, including executing "silly searches" (searches of sequence numbers +only) locally. + +The IMAP, POP, SMTP, and NNTP drivers now have diagnostic code to provide +better information about servers which violate SASL's empty challenge +requirements (e.g. with the PLAIN mechanism). + +There is a new mail_fetch_overview_sequence() function which is like +mail_fetch_overview() but takes a sequence number string as an argument. +There should have been a flags argument and FT_UID bit as in all the other +mail_fetch_???() functions but compatibility with the past... :-( + +The overview_t callback (from mail_fetch_overview()) now has a fourth +argument which contains the message sequence number (as opposed to the UID +which is in the second argument). It turned out that some applications were +calling mail_msgno() (which can be moderately expensive) to get the sequence +number, and c-client already knew it. + +Many declarations which are completely internal to a driver have been removed +from the driver .h file, and in those cases where there are no external +declarations left the .h file has been eliminated entirely. As part of this, +the mbox driver routines are now incorporated with the unix driver routines +as opposed to being a separate file. The mbox driver still needs to be lunk +in order to get the mbox functionality. + + +Updated: 27 August 2003 + +imap-2002e is a minor release, released concurrently with Pine 4.58, and +contains primarily bugfixes. Programs written for imap-2002d will build +with this version without modification. + +The NNTP client code now tries to perform better with legacy NNTP servers +which do not comply with the current NNTP protocol specification draft, most +notably Netscape Collabra. + +Delivery notifications now work reliably with SMTP servers that support it. + +The following changes are primarily of concern to developers and power users: + +There is a "limited advertise" option in env_unix.c which, if set, will only +advertise the user's own namespace and the #shared/ namespace. + +It is now possible to build the IMAP toolkit with a separate SSL KEY file +from the certificate file (SSLKEYS vs. SSLCERTS). + +A new BODY structure element, sparep, is available for the main program to +use as a pointer for its own purposes; as well as a SET_FREEBODYSPAREP +function, similar to SET_FREEENVELOPESPAREP, SET_FREEELTSPAREP, etc. + + +Updated: 28 May 2003 + +imap-2002d is a minor release, released concurrently with Pine 4.56, and +contains primarily bugfixes. Programs written for imap-2002 should build +with this version without modification, with one exception. That exception +is the ngbogus envelope flag, which stopped being used in imap-2002c and is +now gone for good. + +The NNTP newsgroup listing code now tries to use wildmats on the NNTP server, +which should result in better performance especially on slow lines. It is +also once again permitted to log in on NNTP servers when /loser is set. + +imapd now supports the UNSELECT command. + +A new envelope flag, imapenvonly, indicates that the envelope in a +MESSAGE/RFC822 BODY structure only has the IMAP envelope components and +not the additional components from c-client: Newsgroups, Followup-To, +and References. + + +Updated: 7 April 2003 + +imap-2002c is a minor release, released concurrently with Pine 4.55, and +contains primarily bugfixes. Programs written for imap-2002 will build +with this version without modification. + +The POP3 driver will, with new servers that support CAPA, use the LIST +command to get the elt->rfc822_size and the TOP command to get the message +header, instead of fetching the entire message. Note that it is a bad idea +to do this with old servers, since they may misimplement LIST and TOP. The +result is a substantial performance improvement. + +Subject extraction for comparisons in SORT and THREAD are now done in full +compliance with the rules laid out in the specification. This only makes +a difference if "re:" was part of a MIME quoted-word. + +The new experimental #move namespace allows download-and-delete from a source +mailbox to a destination mailbox. Immediately following #move is a delimiter +character which must not appear in the source mailbox name, then the source +mailbox name, then the delimiter again, then the destination mailbox name. +For example: + #move+{pop3.foo.com/pop3}+INBOX +will download messages from "pop3.foo.com" into your local INBOX. + +The NNTP driver now uses the LIST EXTENSIONS command as described in the +current NNTP protocol specification draft, and will prefer to use OVER over +XOVER, HDR over XHDR, etc. + +The SET_NNTPRANGE function of mail_parameters() can be used to limit the +number of articles recognized by the NNTP driver, resulting in a substantial +performance improvement with NNTP servers that may have hundreds of thousands +of old articles in the spool. If set non-zero, then only the last n article +numbers will be considered. If you are on a slow link, you may want to set +this to 1000 or less. + +Besides the normally tested UNIX and 32-bit Microsoft platforms, this release +has also been tested and will once build under TOPS-20 and VAX/VMS. I also +fixed a bug which would keep it from building on 16-bit DOS, but I don't know +if it will build on that platform or not since I no longer have a system with +the old DOS C compiler. It has not been tested on Macintosh (note however +that Mac OS X is a type of UNIX and should build), Amiga, or OS/2, and probably +no longer builds on those platforms. + + +Updated: 7 January 2003 + +imap-2002b is a maintenace release, released concurrently with Pine 4.52, +and contains only bugfixes. Programs written for imap-2002 will build with +this version without modification. + +Drivers which do not announce new mail are now indicated by the DR_NONEWMAIL +driver flag. Driver which do not announce new mail when read-only are now +indicated by the DR_NONEWMAILRONLY flag. + +There are no user-visible functional enhancements in this version. + + +Updated: 10 December 2002 + +imap-2002a is a maintenance release, consisting entirely of critical +bugfixes. Programs written for imap-2002 will build with this version +without modification. + +There are no functional enhancements in this version. + + +Updated: 28 October 2002 + +imap-2002 is a major release. Programs written for imap-2001 will probably +build with this version without modification, with one exception. That +exception is if the program uses [GS]ET_DISABLEAUTOMATICSHAREDNAMESPACES, +which has been renamed to [GS]ET_DISABLEAUTOSHAREDNS in order to placate +some compilers which don't like very long names. + +SSLTYPE=nopwd is now the default, in accordance with current IESG security +requirements. In order to build the IMAP toolkit without SSL/TLS you must +now use SSLTYPE=none. At initial build time, you will be told if the SSLTYPE +setting is in compliance with IESG security requirements, and if it is not +you will be asked to confirm to continue the build. + +ORDEREDSUBJECT threading has been changed in accordance with draft 12 of the +IMAP threading specification. Previously, each non-root message in an +ORDEREDSUBJECT thread has been a child of the message immediately preceeding +it in the thread. Draft 12 changes this so that the second message in the +thread is the child of the first (root) message, and all subsequent messages +are siblings of the first message. This is significant in MUAs which display +the thread structure graphically; the new definition is much saner than the +old one since it does not nest endlessly due to parent/child relationships +that may not exist. This also impacts imapd, since imapd's THREAD command +will return a thread structure. + +RFC 1730 server support, which was disabled in imap-2001, is now fully +removed from imapd. imapd still supports IMAP2bis, specifically the FIND +command, since there are still a few IMAP2 clients out there. + +The IMAP client routines in the c-client library continue to support recognize +RFC 1730 servers, but do not implement the deprecated features of RFC 1730. + +The Frequently Asked Questions file is now in HTML format, although a text +version (generated from the HTML version with Lynx) is also provided. + +A new program, mailutil, is now bundled with the IMAP toolkit. mailutil +replaces the old chkmail, imapcopy, imapmove, imapxfer, mbxcopy, mbxcreat, +and mbxcvt programs that were distributed in the imap-utils. In addition, +the tmail, dmail, and mlock programs from the imap-utils are now also +bundled with the IMAP toolkit. + +In addition to the usual bugfixes, the following c-client functionalities +are new in imap-2002: + +The SET_DISABLE822TZTEXT parameter allows a client to suppress generation of +the "human friendly" time zone text in RFC822 dates. This placates netnews +and some broken SMTP servers which think that long timezone names from Windows +are an attempt at a buffer overflow attack. + +The restrictBox option in env_unix.c sets "restricted box" functionality, +which disables access to the root (leading "/"), access to other user's +directories (leading "~"), and access to superior directories via "..". + +Content-Location is now supported by the "location" member of the BODY +structure. Note that there is a bug in the IMAP client code in older +versions of the c-client library that causes it to handle BODYSTRUCTURE +extension data improperly if that data is a literal. The new functionality +for Content-Location may trigger this bug. The fix is either to upgrade +the IMAP client program to the imap-2002 version of c-client or to remove +the Content-Location support from imapd. + +There are now 8 spare bits for application use in both the elts and the +mail streams. + +mail_search() now returns a value (previously it was void). If mail_search() +returns NIL, then the supplied charset was invalid or the IMAP server +returned NO (probably because the supplied charset was invalid). + +New utf8_charset() routine to look up a charset and return c-client's +database about that charset if found. Among other things, this will give +you the scripts supported by that charset and its Unicode conversion table. + +New FT_NOLOOKAHEAD flag for mail_fetch_structure() disables fetching of +any envelopes other than the one specified. Otherwise, it will try to do +anticipatory fetching (up to IMAPLOOKAHEAD). + +New GET_FETCHLOOKAHEAD allows better control of mail_fetch_structure() +lookahead. Instead of looking IMAPLOOKAHEAD messages forward from the +specified message, it will use a supplied SEARCHSET to generate message +sequences and ranges. It will stop at IMAPLOOKAHEAD messages or at the +completion of a range which exceeds IMAPLOOKAHEAD. The search set only +applies to the next mail_fetch_structure() on that stream, and is cleared +once it is used. Call with + SEARCHSET **set = (SEARCHSET **) + mail_parameters (stream,GET_FETCHLOOKAHEAD,(void *) stream); + *set = pointer to desired search set + +New mail_shortdate() routine returns an date in the format expected by +SEARCHPGMs. + + +Updated: 2 November 2001 + +imap-2001a is a maintenance release, consisting primarily of bugfixes +including some critical bugfixes to crash and denial of service problems. +Programs written for imap-2001 will build with this version without +modification. + +The following new facilities have also been added: + +The new /norsh switch in mailbox names provides a more intuitive way of +disabling rsh-IMAP than the existing :143 or setting the rsh-timeout to 0. + +Passwords are no longer returned in mm_dlog() callbacks unless the +application sets the SET_DEBUGSENSITIVE parameter. + +The SET_NETFSSTATBUG parameter allows an application to force the +traditional UNIX mailbox driver to close and reopen the mailbox at ping +time. This is EXTREMELY inefficient, and should only be used to access +files stored on AFS and old NFS systems. + +The ISO 8859 and Windows conversion tables have been updated to comply +with Unicode 3.1, and the KOI8-R table has been verified as compliant with +Unicode 3.1. + +The SPECIALS mechanism for passing parameters to the lowest level Makefile +has been updated to be more general. See the next item for why you might +care. + +New lrh port to build on Red Hat Linux 7.2, with pre-set definitions for +the places where Red Hat has placed Kerberos and SSL. It's actually just +the lnp port with SPECIALS defined accordingly. You may want to use it as +a model if your system needs such definitions. Note that SPECIALS is +primarily for IMAP toolkit (and Pine) purposes, and that user settings +should use EXTRASPECIALS instead. + + +Updated: 22 June 2001 + +imap-2001 is a major release. Programs written for imap-2000 will probably +build with this version without modification. + +The FAQ document has been significantly expanded. Be sure to read it for +more information. + +In addition to the usual bugfixes, the following features are new in +imap-2001: + +SSL is now fully integrated into the IMAP toolkit; the old "alt" kludges to +be able to produce a "sanitized" version of the IMAP toolkit to comply with +late unlamented US export regulations are now completely gone. + +Full client and server TLS support is also in this release. + +The server certificate must be signed by a trusted certificate authority and +the name in the certificate match the user's entry for the server host name; +this means that the user must enter a fully-qualified host name. + +To build with SSL/TLS on UNIX, you now use "SSLTYPE=unix" instead of the +former "SPECIALAUTHENTICATORS=ssl". To build with SSL/TLS on UNIX and disable +the use of plaintext passwords except when under SSL/TLS, use "SSLTYPE=nopwd" +instead of "SSLTYPE=unix". + +RFC 1730 (IMAP4 as opposed to IMAP4rev1) support is turned off by default in +imapd. No clients should still be using RFC 1730 protocol. Look at the imapd +Makefile for how to re-enable RFC 1730 support. Note that this code may be +removed in the future, so if you think you need it you had better let me know. + +There are some new options (turned off by default) which attempt to work around +problems in certain clients. See the FAQ file for more details. + + +Updated: 24 January 2001 + +imap-2000c is a maintenance release, consisting primarily of bugfixes. + + +Updated: 9 January 2001 + +imap-2000b is a maintenance release, consisting primarily of bugfixes. + + +Updated: 9 November 2000 + +imap-2000a is a maintenance release, consisting primarily of bugfixes. + + +Updated: 19 September 2000 + +imap-2000 is a major release. There are major internal and external changes +from earlier versions (imap-4.x and imap-3.x series). Programs written for +imap-4.x will probably build with this version without modification. It is +extremely unlikely that a program written for imap-3.x or earlier series will +build with this version without modifications. Drivers written for earlier +versions will definitely need to be rewritten. + +In addition to the usual bugfixes, the following features are new in imap-2000: + +SSL support is now available. For UNIX, it is necessary to install some +version of OpenSSL; see imap-2000/docs/SSLBUILD for more information. SSL +support is now automatic for the NT, NTK, and W2K ports. SSL use is indicated +by the /ssl switch in the mailbox name. + +With SSL connections, the server certificate is validated by the client code +on UNIX, and Windows 2000 unless /novalidate-cert is specified. Server +certificates are currently is not validated on Windows 9x, Windows Millenium, +or Windows NT 4; this is an artifact of the operating system and not the port +(e.g. client code using the NT port will validate certificates if running on +Windows 2000). On UNIX, the server certificate must be signed by a trusted +certificate authority. On Windows 2000, the certificate must be signed by a +trusted certificate authority and match the user's entry for the server host +name; this means that the user must enter a fully-qualified host name. + +Calendar reclama for the benefit of old broken non-Y2K compliant software. +Two digit years from 00 to 69 will be interpreted as 2000 through 2069. In +addition, three digit years from 100 to 105 will be interpreted as 2000 +through 2005. + +Support for REFERENCES threading (in addition to the previously-existing +ORDEREDSUBJECT threading). + +Support for the IMAP MULTIAPPEND extension. This allows much faster uploading +of multiple messages to an IMAP server. + +Support for the LOGINDISABLED IMAP capability. If the IMAP server sends +LOGINDISABLED as a capability, the client code will never attempt to send an +IMAP LOGIN command. + +Support for SASL authentication identity vs. authorization identity. If the +authentication method does not support this concept (e.g. AUTH=CRAM-MD5, +AUTH=LOGIN, LOGIN command), the "*" character in the user name may be used to +indicate a separate authentication identity; for example, "fred*joe" indicates +authorization identity "fred", authentication identity "joe". + + +UNIX-specific Changes: + +Support for SASL authentication identity vs. authorization identity in the +IMAP and POP3 servers. If the user indicated by the authentication identity +is in the "mailadm" group, he may specify any authorization identity and get +logged in as the authorization identity user. + +If the IMAP and POP3 servers are build with PASSWDTYPE=nul, it will send +LOGINDISABLED as a capability and also disable the AUTH=LOGIN and AUTH=PLAIN +SASL authenticators. + +New MAILSUBDIR build option to change the default mailbox directory from the +user's home directory to a subdirectory of the user's home directory. See +imap-2000/Makefile for more information. + +New CHROOT_SERVER build option for closed server systems only. If defined, a +chroot() call to the user's home directory is done as part of the login +process. See imap-2000/Makefile for more information. + +New ADVERTISE_THE_WORLD build option which will add an IMAP namespace that +points to the root. Not for the faint of heart. + +UNIX format mailboxes no longer require the pseudo-message, nor will a +pseudo-message be added to a mailbox that does not have one. A new +X-IMAPbase: header will be written in the first message. This is rather less +efficient and robust than the pseudo-message (which remains the encouraged +mechanism; UNIX format mailboxes will always be created with it), but perhaps +will pacify some people who get upset by the pseudo-message. + +When building with MIT Kerberos it will try to detect and use libk5crypto.a +instead of libcrypto.a. + +The mbx driver is more aggressive about cleaning up expunged messages that +couldn't be purged because of shared access to the mailbox at the time of +expunge. Now, every checkpoint will try to purge such messages; and a +checkpoint is attempted at close time. + + +Windows-specific Changes: + +New W2K port for Windows 2000. In addition to supporting SSL using the +official SSPI interface (the NT and NTK ports invoke SChannel.DLL directly), +the W2K port also supports Microsoft Kerberos. Note that the NT and NTK ports +will work on Windows 2000, but the W2K port will not work on NT4, Windows +9x, or Windows Millenium. + +There is now a #user namespace, equivalent to the "~" namespace on UNIX. + + + +Changes for Developers: + +New c-client.h file which acts as a master include. c-client based +applications should now include c-client.h instead of the individual c-client +files (mail.h, misc.h, etc.). It is believed that c-client.h will work in C++ +applications. + +New GET_FREEENVELOPESPAREP/SET_FREEENVELOPESPAREP and +GET_FREEELTSPAREP/SET_FREEELTSPAREP function callbacks to free the "sparep" +member of the envelope and cache elements, respectively. + +New OP_MULNEWSRC flag to mail_open() to use multiple newsrc files, and new +GET_NEWSRCQUERY/SET_NEWSRCQUERY function callbacks to get the name of the +newsrc file for news access. + +New "secret" nntp_article() function to do the NNTP ARTICLE command; this is +generally useful only when chasing news URLs. + +New GET_HIDEDOTFILES/SET_HIDEDOTFILES feature to suppress file names that +start with "." in mail_list() results. diff --git a/imap/docs/SSLBUILD b/imap/docs/SSLBUILD new file mode 100644 index 00000000..962e8b29 --- /dev/null +++ b/imap/docs/SSLBUILD @@ -0,0 +1,267 @@ +/* ======================================================================== + * 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 + * + * + * ======================================================================== + */ + + SSL/TLS BUILD AND INSTALLATION NOTES FOR UNIX + Last Updated: 15 November 2007 + +PREREQUISITES BEFORE STARTING: + 1) Review the information in imap-2007/docs/BUILD. + 2) Obtain a copy of OpenSSL. OpenSSL is available from third parties. We + do not provide OpenSSL. + 3) Make sure that you know how to build OpenSSL properly on the standard + /usr/local/ssl directory. In particular, /usr/local/ssl/include (and + /usr/local/ssl/include/openssl) and /usr/local/ssl/lib must be set up + from the OpenSSL build. If you have a non-standard installation, then + you must modify the imap-2007/src/osdep/unix/Makefile file to point + to the appropriate locations. + 4) Make sure that you know how to obtain appropriate certificates on your + system. + +NOTE: We can NOT provide you with support in building/installing OpenSSL, or +in obtaining certificates. If you need help in doing this, try the contacts +mentioned in the OpenSSL README. + + +SSL BUILD: + + By default, the IMAP toolkit builds with SSL and disabling plaintext +passwords unless SSL/TLS encryption is in effect (SSLTYPE=nopwd). This +produces an IMAP server which is compliant with RFC 3501 security +requirements. + + To build with SSL but allow plaintext passwords in insecure sessions, +add "SSLTYPE=unix" to the make command line. Note that doing so will +produce an IMAP server which is NON-COMPLIANT with RFC 3501. + + To build without SSL, add "SSLTYPE=none" to the make command line. +Note that doing so will produce an IMAP server which is NON-COMPLIANT +with RFC 3501. + + There are other make options relevant to SSL, described in + imap-2007/src/osdep/unix/Makefile +The most important of these are SSLDIR, SSLCRYPTO, and SSLRSA. + + SSLDIR is set to /usr/local/ssl by default. This is the normal +installation directory for OpenSSL. If your system uses a different directory +you will need to change this. + + SSLCRYPTO is set to -lcrypto by default. Older versions of MIT Kerberos +also have a libcrypto and will cause a library name conflict. If you are +using an older version of Kerberos, you may need to change SSLCRYPTO to +$(SSLLIB)/libcrypto.a + + SSLRSA is set empty by default. It can be set to specify the RSAREF +libraries, which you once had to use with OpenSSL to use RSA algorithms +legally if you are in the USA, due to patent issues. Since RSA Security Inc. +released the RSA algorithm into the public domain on September 6, 2000, there +is no longer any reason to do this. + + +SSL INSTALLATION: + + 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 + + mtest is normally not used except by c-client developers. + +STEP 1: inetd setup + + + The ipop2d, ipop3d, and imapd daemons should be installed in a system +daemon directory and invoked by a listener such as xinetd or inetd. In the +following examples, /usr/local/etc is used). + +STEP 1(A): xinetd-specific setup + + If your system uses xinetd, the daemons are invoked by files in your +/etc/xinetd.d directory with names corresponding to the service names (that +is: imap, imaps, pop2, pop3, pop3s). You will need to consult your local +xinetd documentation to see what should go into these files. Here is a a +sample /etc/xinetd.d/imaps file: + +service imaps +{ + disable = no + socket_type = stream + wait = no + user = root + server = /usr/local/etc/imapd + groups = yes + flags = REUSE IPv6 +} + +STEP 1(B): inetd-specific setup + + If your system still uses inetd, the daemons are invoked by your +/etc/inetd.conf file with lines such as: + +pop stream tcp nowait root /usr/local/etc/ipop2d ipop2d +pop3 stream tcp nowait root /usr/local/etc/ipop3d ipop3d +imap stream tcp nowait root /usr/local/etc/imapd imapd +pop3s stream tcp nowait root /usr/local/etc/ipop3d ipop3d +imaps stream tcp nowait root /usr/local/etc/imapd imapd + + Please refer to imap-2007/docs/BUILD for an important note about inetd's +limit on the number of new connections. If that note applies to you, and you +can configure the number of connection in /etc/inetd.conf as described in +imap-2007/docs/build, here is the sample /etc/inetd.conf entry with SSL: + +pop3 stream tcp nowait.100 root /usr/local/etc/ipop3d ipop3d +pop3s stream tcp nowait.100 root /usr/local/etc/ipop3d ipop3d +imap stream tcp nowait.100 root /usr/local/etc/imapd imapd +imaps stream tcp nowait.100 root /usr/local/etc/imapd imapd + (or, if you use TCP wrappers) +pop3 stream tcp nowait.100 root /usr/local/etc/tcpd ipop3d +imap stream tcp nowait.100 root /usr/local/etc/tcpd imapd +pop3s stream tcp nowait.100 root /usr/local/etc/ipop3d ipop3d +imaps stream tcp nowait.100 root /usr/local/etc/imapd imapd + +NOTE: do *NOT* use TCP wrappers (tcpd) for the imaps and pop3s services! I +don't know why, but it doesn't work with TCP wrappers. + + +STEP 2: services setup + + You may also have to edit your /etc/services (or Yellow Pages, +NetInfo, etc. equivalent) to register these services, such as: + +pop 109/tcp +pop3 110/tcp +imap 143/tcp +imaps 993/tcp +pop3s 995/tcp + +NOTE: The SSL IMAP service *MUST* be called "imaps", and the SSL POP3 service +*MUST* be called "pop3s". + + +STEP 3: PAM setup + + If your system has PAM (Pluggable Authentication Modules -- most +modern systems do) then you need to set up PAM authenticators for imap and +pop. The correct file names are + /etc/pam.d/imap +and + /etc/pam.d/pop + + It probably works to copy your /etc/pam.d/ftpd file to the above two +names. + + Many people get these file names wrong, and then spend a lot of time +trying to figure out why it doesn't work. Common mistakes are: + /etc/pam.d/imapd + /etc/pam.d/imap4 + /etc/pam.d/imap4rev1 + /etc/pam.d/imaps + /etc/pam.d/ipop3d + /etc/pam.d/pop3d + /etc/pam.d/popd + /etc/pam.d/pop3 + /etc/pam.d/pop3s + + +STEP 4: certificates setup + +NOTE: We can NOT provide you with support in obtaining certificates. If you +need help in doing this, try the contacts mentioned in the OpenSSL README. + +WARNING: Do NOT install servers built with SSL support unless you also plan to +install proper certificates! It is NOT supported to run SSL-enabled servers +on a system without the proper certificates. + + You must set up certificates on /usr/local/ssl/certs (this may be +different if you have a non-standard installation of OpenSSL; for example, +FreeBSD has modified OpenSSL to use /usr/local/certs). You should install +both the certificate authority certificates from the SSL distribution after +building OpenSSL, plus your own certificates. The latter should have been +purchased from a certificate authority, although self-signed certificates are +permissible. A sample certificate file is at the end of this document. + + Install the resulting certificate file on /usr/local/ssl/certs, with a +file name consisting of the server name and a suffix of ".pem". For example, +install the imapd certificate on /usr/local/ssl/certs/imapd.pem and the ipop3d +certificate on /usr/local/ssl/certs/ipop3d.pem. These files should be +protected against random people accessing them. It is permissible for +imapd.pem and ipop3d.pem to be links to the same file. + + The imapd.pem and ipop3d.pem must contain a private key and a +certificate. The private key must not be encrypted. + + The following command to openssl can be used to create a self-signed +certificate with a 10-year expiration: + req -new -x509 -nodes -out imapd.pem -keyout imapd.pem -days 3650 + + *** IMPORTANT *** + We DO NOT recommend, encourage, or sanction the use of self-signed +certificates. Nor will we be responsible for any problems (including security +problems!) which result from your use of a self-signed certificate. Use of +self-signed certificates should be limited to testing only. Buy a real +certificate from a certificate authority! + + *** IMPORTANT *** + + If you have a multihomed system with multiple domain names (and hence +separate certificates for each domain name), you can append the IP address +to the service name. For example, the IMAP certificate for [12.34.56.78] +would be /usr/local/ssl/certs/imapd-12.34.56.78.pem and so on. You only need +to use this feature if you need to use multiple certificates (because different +DNS names are used). + + +SAMPLE CERTIFICATE FILE + + Here is a sample certificate file. Do *NOT* use this on your own +machine; it is simply an example of what one would look like. + +-----BEGIN RSA PRIVATE KEY----- +MIICXQIBAAKBgQDHkqs4YDbakYxRkYXIpY7xLXDQwULR5LW7xWVzuWmmZJOtzwlP +7mN87g+aaiQzwXUVndaCw3Zm6cOG4mytf20jPZq0tvWnjEB3763sorpfpOe/4Vsn +VBFjyQY6YdqYXNmjmzff5gTAecEXOcJ8CrPsaK+nkhw7bHUHX2X+97oMNQIDAQAB +AoGBAMd3YkZAc9LUsig8iDhYsJuAzUb4Qi7Cppj73EBjyqKR18BaM3Z+T1VoIpQ1 +DeXkr39heCrN7aNCdTh1SiXGPG6+fkGj9HVw7LmjwXclp4UZwWp3fVbSAWfe3VRe +LM/6p65qogEYuBRMhbSmsn9rBgz3tYVU0lDMZvWxQmUWWg7BAkEA6EbMJeCVdAYu +nQsjwf4vhsHJTChKv/He6kT93Yr/rvq5ihIAPQK/hwcmWf05P9F6bdrA6JTOm3xu +TvJsT/rIvQJBANv0yczI5pUQszw4s+LTzH+kZSb6asWp316BAMDedX+7ID4HaeKk +e4JnBK//xHKVP7xmHuioKYtRlsnuHpWVtNkCQQDPru2+OE6pTRXEqT8xp3sLPJ4m +ECi18yfjxAhRXIU9CUV4ZJv98UUbEJOEBtx3aW/UZbHyw4rwj5N511xtLsjpAkA9 +p1XRYxbO/clfvf0ePYP621fHHzZChaUo1jwh07lXvloBSQ6zCqvcF4hG1Qh5ncAp +zO4pBMnwVURRAb/s6fOxAkADv2Tilu1asafmqVzpnRsdfBZx2Xt4oPtquR9IN0Q1 +ewRxOC13KZwoAWtkS7l0mY19WD27onF6iAaF7beuK/Va +-----END RSA PRIVATE KEY----- +-----BEGIN CERTIFICATE----- +MIIECTCCA3KgAwIBAgIBADANBgkqhkiG9w0BAQQFADCBujELMAkGA1UEBhMCVVMx +EzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1NlYXR0bGUxHzAdBgNVBAoT +FkJsdXJkeWJsb29wIEluZHVzdHJpZXMxFjAUBgNVBAsTDUlTIERlcGFydG1lbnQx +ITAfBgNVBAMTGEJvbWJhc3RpYyBULiBCbHVyZHlibG9vcDEoMCYGCSqGSIb3DQEJ +ARYZYm9tYmFzdGljQGJsdXJkeWJsb29wLmNvbTAeFw0wMDA2MDYwMDUxMTRaFw0x +MDA2MDQwMDUxMTRaMIG6MQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3Rv +bjEQMA4GA1UEBxMHU2VhdHRsZTEfMB0GA1UEChMWQmx1cmR5Ymxvb3AgSW5kdXN0 +cmllczEWMBQGA1UECxMNSVMgRGVwYXJ0bWVudDEhMB8GA1UEAxMYQm9tYmFzdGlj +IFQuIEJsdXJkeWJsb29wMSgwJgYJKoZIhvcNAQkBFhlib21iYXN0aWNAYmx1cmR5 +Ymxvb3AuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDHkqs4YDbakYxR +kYXIpY7xLXDQwULR5LW7xWVzuWmmZJOtzwlP7mN87g+aaiQzwXUVndaCw3Zm6cOG +4mytf20jPZq0tvWnjEB3763sorpfpOe/4VsnVBFjyQY6YdqYXNmjmzff5gTAecEX +OcJ8CrPsaK+nkhw7bHUHX2X+97oMNQIDAQABo4IBGzCCARcwHQYDVR0OBBYEFD+g +lcPrnpsSvIdkm/eol4sYYg09MIHnBgNVHSMEgd8wgdyAFD+glcPrnpsSvIdkm/eo +l4sYYg09oYHApIG9MIG6MQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3Rv +bjEQMA4GA1UEBxMHU2VhdHRsZTEfMB0GA1UEChMWQmx1cmR5Ymxvb3AgSW5kdXN0 +cmllczEWMBQGA1UECxMNSVMgRGVwYXJ0bWVudDEhMB8GA1UEAxMYQm9tYmFzdGlj +IFQuIEJsdXJkeWJsb29wMSgwJgYJKoZIhvcNAQkBFhlib21iYXN0aWNAYmx1cmR5 +Ymxvb3AuY29tggEAMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEEBQADgYEAwEEk +JXpVXVaFTuG2VJGIzPOxQ+X3V1Cl86y4gM1bDbqlilOUdByUEG4YfSb8ILIn+eXk +WzMAw63Ww5t0/jkO5JRs6i1SUt0Oy80DryNRJYLBVBi499WEduro8GCVD8HuSkDC +yL1Rdq8qlNhWPsggcbhuhvpbEz4pAfzPkrWMBn4= +-----END CERTIFICATE----- diff --git a/imap/docs/Y2K b/imap/docs/Y2K new file mode 100644 index 00000000..12b84284 --- /dev/null +++ b/imap/docs/Y2K @@ -0,0 +1,145 @@ +/* ======================================================================== + * Copyright 1988-2006 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 + * + * + * ======================================================================== + */ + +QUESTION: Is c-client Y2K compliant? + +ANSWER: + + There are no known Y2K issues in c-client; nor have there ever +been any known Y2K issues in c-client from its inception. + + Some older versions of c-client don't like the two-digit year +"00", although the only impact of this is that messages with that year +will sort before any other messages. Nobody should be using two-digit +years in email messages any more (use "2000" instead of "00"). + + You may wish to read the document calendar.txt for more +information about the Y3.3K/Y4K, Y20K, and Y4)K issues. Assuming that +c-client is still around in 2000-40,000 years, someone will have to +deal with these. + + Within the plausible lifetimes of people today, there are three +known date-related issues in c-client which will have to be addressed +in the future. If I am still alive when the first problem hits, I +will be nearly 82 years old, and won't be maintaining c-client any +more. + + +Y2038: + + c-client, like most UNIX software, has Y2038 issues. On Tuesday, +January 19, 2038 at 03:14:08 Coordinated Universal Time (also known as +UTC, UT, or historically GMT), the clock on 32-bit UNIX systems will +wrap around to a negative number; that is, from 0x7fffffff to +0x80000000. + + c-client uses an unsigned long for its 32-bit time; however the C +library on most UNIX systems uses a signed long and will interpret +that time as being Friday, December 13, 1901 at 20:45:52 UTC. + + Fixing this problem will require changing the C library to use +either unsigned longs or a wider (e.g. 64-bit) value for time. Lots +of work will need to be done on 32-bit UNIX systems as 2038 +approaches. History suggests that most of the work will be done in +the autumn of 2037... ;-) It's not known if anything is necessary to +do to c-client other than just rebuild it with the new C library. + + Going to 32-bit unsigned longs means that there will be a Y2106 +bug that someone will have to fix. Hopefully nobody will even think +of using 32-bit systems by then. + + +Y2070: + + c-client assumes that 2-digit years with values of 70 or greater +are in the 20th century, and that 2-digit years with values of 69 or +less are in the 21st century. Time for UNIX began on January 1, 1970 +and email on ARPAnet happened between the first TENEX systems shortly +after that; consequently there is no ambiguity with email data with +2-digit years prior to the year 2070. This is used only when parsing +a 2-digit year. c-client never generates one. + + Fixing this problem requires convincing people not to use 2-digit +years. This is a lesson that people should have figured out 70 years +earlier with Y2K. Consequently, this may be a "non-problem." +Otherwise, look in mail_parse_date() for the comment "two digit year" +and change the statement as desired. [Note: do not change the +definition of BASEYEAR since the UNIX port assumes that this matches +when time began in the operating system.] + + +Y2098: + + On January 1, 2098, the year in per-message internal dates will +expire, since a 7-bit field is allocated for the year. c-client will +mistakenly think that the day is January 1, 1970. + + Fortunately, it is easy to fix this problem. Just increase the +width of "year" in MESSAGECACHE in mail.h. If you make it 8 bits, +it'll be good until January 1, 2216; 9 bits makes it good until 2482. +10 bits will push it back that you'd worry about the Y2800 question +before having to increase it again. If you ignore Y2800, 11 bits will +push it it back to having to worry about Y4K first. + + +Y2800: + + At this year, you will need to decide whether to keep the Gregorian +calendar, which is one day slow every 20,000 years, or go to the more +accurate Eastern Orthodox calendar which is one day slow every 45,000 +years. The Gregorian and Eastern Orthodox calendars diverge at this +year. + + There hasn't been any statement about how the international +community will deal with the situation of the Orthodox calendar being +one day ahead of the Gregorian calendar between 2800 and 2900. This +will happen again between 3200 and 3300, and at gradually increasing +intervals until 48,300 when the shift becomes permanent (assuming no +Y20K or Y40K fixes). + + If you wish to make the transition to the Eastern Orthodox calendar, +rebuild c-client with -DUSEORTHODOXCALENDAR=1. You can then ignore Y4K +and Y20K! + + +Y3.3K/Y4K: + + Some time around the year 3300, the calendar has gotten one day +behind. To remedy this, a little-known rule in the Gregorian calendar +is that years that are evenly divisible by 4000 are not leap years. +Unlike the other rules, this rule hasn't had effect yet, and won't for +another 2000 years. + + To fix the Y4K problem, just rebuild c-client with -DY4KBUGFIX=1. + + +Y20K: + + Those of you who stuck with the Gregorian calendar have a +problem; the calendar is now one day slow. The Pope has not made any +statement about how this problem will be fixed. Maybe they'll declare +that 20,004 is also not a leap year or something. + + There is no fix for this problem in c-client. + + +Y40K: + + Greeks, Serbs, Russians, and other Eastern Orthodox have spent +the past 38,000 years laughing at westerners' increasingly futile +efforts to keep the Gregorian calendar in order. The day of reckoning +has come; the Orthodox calendar is now one day slow. The Patriarch of +Istanbul (nee Constantinople) has not made any statement about how this +will be fixed. + + There is no fix for this problem in c-client. diff --git a/imap/docs/bugs.txt b/imap/docs/bugs.txt new file mode 100644 index 00000000..5f87b3ef --- /dev/null +++ b/imap/docs/bugs.txt @@ -0,0 +1,234 @@ +/* ======================================================================== + * 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 + * + * + * ======================================================================== + */ + + KNOWN BUGS/MISFEATURES/DEFICIENCIES IN THE IMAP TOOLKIT + Last Updated: 15 November 2007 + +The following are known problems/deficiencies in the imap-2007 toolkit: + + . Possible problems for some installations: + . In some versions of Redhat Linux, SVR4-style timezone name lookup + doesn't work properly due to a bug in glibc. The workaround is to + edit os_lnx.c to include tz_bsd.c instead of tz_sv4.c. Note that + other versions of Linux don't support BSD-style timezone name + lookup, so don't make this change unless it's needed on your system. + . In some systems, the OpenSSL distribution is installed other than at + the standard /usr/local/ssl location. If this is the case on your + system and you want to build with SSL support, you will need to set + the SSLDIR variable, either by including a setting of EXTRASPECIALS + in the make command line, e.g. + build lnp SPECIALAUTHENTICATORS=ssl EXTRASPECIALS="SSLDIR=/usr/ssl" + or by editing .../src/osdep/unix/Makefile + . /tmp, /usr/tmp or /var/tmp (if present), and the mail spool directory + must be protected 1777 (world write with sticky bit); otherwise + mailbox locking and updates won't work. An alternative to 1777 on + the mail spool directory is to install the mlock program that is + bundled with the IMAP toolkit. + . Multiple access protection locking does not work if the mailbox or + /tmp are NFS mounted. + . Shared access mailbox formats (mbx, mtx, mx, and tenex) do not work + well with NFS and such usage is not supported. mmdf and unix formats + are supported for use over NFS; however there won't be any multiple + access locking protection. + . Server startup delays may occur if a reverse DNS (IP address to name) + lookup on the client's IP address does not complete in an expeditious + fashion. This is actually a DNS problem and should be fixed in the + DNS and/or the server's host table. A workaround exists (see the + top-level Makefile for details) but is not recommended and can not + be used at all with Kerberos. + . At the insistance of the security gurus, SSL certification validation + is now on by default. This means that you must now use the new + /novalidate-cert switch if establishing an SSL connection to a server + with a self-signed certificate; i.e. if "imap.example.com" has a + self-signed certificate, you must use a mailbox name such as + {imap.example.com/ssl/novalidate-cert}INBOX + to get an SSL session instead of just + {imap.example.com/ssl}INBOX + . GCC 8.x and above on SGI systems does not correctly pass/return + structures which are smaller than 16 bytes and are not 8 bytes. The + problem is that structures are padded at the wrong end; e.g. a 4 byte + structure is loaded into the lower 4 bytes of the register when it + should be loaded into the upper 4 bytes of the register. This affects + IRIX 6 the most because it is a 64-bit system and 4 byte structures are + common. This compiler bug impacts the use of inet_ntoa() in c-client + and causes syslog messages to show IP addresses as 255.255.255.255 + instead of the correct values. The fix is either to use SGI's C compiler + instead of GCC or link with an implementation of inet_ntoa() that was + built with GCC instead of the standard SGI C library version. + . By default, the UNIX SSL build assumes that RSAREF is not needed, because + RSA Security Inc. released the RSA public key encryption algorithm into + the public domain on September 6, 2000. There is no longer any need to + use RSAREF, and since RSAREF is slower than OpenSSL's RSA routines + there's good reason not to. If for some reason you still want to use + RSAREF, you will need to edit .../src/osdep/unix/Makefile to + change SSLRSA to load libRSAglue and librsaref. + . By default, the UNIX SSL build assumes that no name conflict exists + between OpenSSL and Kerberos 5. If you are using an older version + of Kerberos, you may need to edit .../src/osdep/unix/Makefile + to change SSLCRYPTO so that it loads the OpenSSL libcrypto library + explicitly as libcrypto.a. + . By default, host names are canonicalized via gethostbyname() and + gethostbyaddr() for everything except for SSL certificate validation. + This can represent a security bug due to DNS spoofing, but is more + likely to deliver results that users expect and also may be necessary + to get Kerberos to work. Set variable "trustdns" in mail.c to NIL if + you want to disable this. + + . Bugs: + . It doesn't work to have a "}" character as a user name in /user= in a + mailbox name, even if the user name is quoted. In other words, + {example.com/user="foo}bar"}zap + won't work; foo will be interpreted as an unterminated quoted string + and the remote mailbox name will be + bar"}zap. + . The experimental mx driver has performance problems and shouldn't be used + . docs/internal.txt is out of date (again) + + . UIDPLUS bugs/limitations: + . Not supported in all local file formats (see below). + . There are two known issues with UIDPLUS in the mmdf and unix formats: + (a) If the destination mailbox is currently selected (whether in this + or another session), no COPYUID or APPENDUID is returned. The other + choice was to assign a UID based upon the uid_last value and hope + that the session selecting the mailbox would pick it up and update + uid_last. The problem was a timing race if another message was + copied/appended to that mailbox before the selecting session updated + the mailbox. If the timing race is lost, then all UID in the mailbox + would be reassigned by the selecting session, thus making the + returned APPENDUID/COPYUID data useless and causing a performance + problem. + Earlier versions did the "hope for the best" method. This was + revoked in favor of not returning COPYUID/APPENDUID. + Although this violates RFC 4315, there is a loophole which, although + for other purposes, permits this behavior. + (b) There is a known failure if the destination mailbox is currently + selected by legacy software (e.g. older versions of the IMAP + server, Pine, etc.). In this case, all UIDs end up being + reassigned by the legacy software. + + . Annoyances: + . Friendly host names (e.g. "server" instead of "server.foo.com") can't be + used in a mailbox name with SSL certificate validation; you have to enter + the fully-qualified domain name. This is a requirement established by + the security gurus. + + . IMAP client limitations: + . No SASL protection mechanisms (SASL authentication mechanisms are + supported) + + . NNTP client limitations: + . Non-standard IMAP SCAN extension not supported + + . POP client limitations: + . No SASL protection mechanisms (SASL authentication mechanisms are + supported) + . No POP3 UID support + . Non-standard IMAP SCAN extension not supported + + . SMTP client limitations: + . No SASL protection mechanisms (SASL authentication mechanisms are + supported) + . No support for use of TURN, ETRN, and pipelining. + . No support for enhanced status codes + + . UNIX limitations: + . IPv6 is supported but is not the default on most platforms; you have to + use IP=6 in the make command + . Supported local file formats: mbx, mh, mmdf, mix, mtx, mx, news, phile, + tenex, unix + . Supported SASL mechanisms: CRAM-MD5, PLAIN, LOGIN, ANONYMOUS, GSSAPI + . Sticky UIDs are not supported in the mh, mtx, and tenex drivers + . Creation of keywords is not supported in the mh, mtx, and tenex drivers + . Copy and append of keywords only works in the mbx driver. + . Flat file formats (mbx, mmdf, mtx, phile, tenex, unix) do not permit + mailboxes to have inferior names + . SSL temporary key should be seeded better than it is. + . UIDPLUS support is limited to the unix, mmdf, mbx, mx, and mix formats. + . Non-standard IMAP SCAN extension not support for mh and news formats. + + . Amiga limitations: + . Supported local file formats: mbx, mh, mmdf, mix, mtx, mx, news, phile, + tenex, unix + . Supported SASL mechanisms: CRAM-MD5, PLAIN, LOGIN, ANONYMOUS + . Sticky UIDs are not supported in the mh, mtx, and tenex drivers + . Creation of keywords is not supported in the mh, mtx, and tenex drivers + . Copy and append of keywords only works in the mbx driver. + . Flat file formats (mbx, mmdf, mtx, phile, tenex, unix) do not permit + mailboxes to have inferior names + . UIDPLUS support is limited to the unix, mmdf, mbx, mx, and mix formats. + . Non-standard IMAP SCAN extension not supported for mh and news formats. + + . Win32 (Win9x/NT/Windows 2000) limitations: + . IPv6 is supported in W2K builds but is not the default; you have to use + IP=6 in the nmake command + . Supported local file formats: mbx, mtx, tenex, unix + . Supported SASL mechanisms: CRAM-MD5, PLAIN, LOGIN, ANONYMOUS, GSSAPI + . No server SSL or TLS support. + . No server authentication for GSSAPI + . No server authentication for CRAM-MD5 on NT-based Windows (NT/2K/XP); + it does work on DOS-based Windows (9x/Me). + . Sticky UIDs are not supported in the mtxnt and tenexnt drivers + . Creation of keywords is not supported in the mtxnt and tenexnt drivers + . Copy and append of keywords only works in the mbxnt driver. + . No support for TCP open timeouts + . Flat file formats (mbx, mtx, tenex, unix) do not permit mailboxes to have + inferior names + . UIDPLUS support is limited to the unix and mbx formats. + + . Win16 (Win3.1)/DOS limitations: + . IPv6 not supported + . Supported local file formats: bezerk, mtx + . Supported SASL mechanisms: CRAM-MD5, LOGIN, ANONYMOUS + . Supported TCPs: B&W, Novell, PC-NFs, PC/TCP, Waterloo, Winsock + . Sticky UIDs are not supported on local files + . Creation of keywords are not supported on local files + . Bezerk driver is read-only and does not handle LF-only newlines well + . No support for any TCP timeouts on Waterloo DOS + . No support for TCP open timeouts on Winsock and generic DOS + . Flat file formats (bezerk, mtx) do not permit mailboxes to have inferior + names + . Does not work well unless a mailgets routine is armed when fetching + texts. + + . Mac limitations: + . IPv6 not supported + . No local file drivers + . Supported SASL mechanisms: CRAM-MD5, LOGIN, ANONYMOUS + . Does not output human-friendly time zone string + + . TOPS-20 limitations: + . IPv6 not supported + . No local file drivers + . Supported SASL mechanisms: CRAM-MD5, LOGIN, ANONYMOUS + . No support for any TCP timeouts + + . VMS limitations: + . IPv6 not supported + . No local file drivers + . Supported SASL mechanisms: CRAM-MD5, LOGIN, ANONYMOUS + . Supported TCPs: Multinet, Netlib + . No support for any TCP timeouts on VMS Netlib + . No support for TCP open timeouts on VMS Multinet + . Time zone must be configured at build time + . Does not output human-friendly time zone string + + . Windows CE limitations: + . IPv6 not yet supported + . No local file drivers + . Supported SASL mechanisms: CRAM-MD5, LOGIN, ANONYMOUS + . No support for TCP open timeouts + . Not finished, only builds c-client library + + . OS/2 limitations: + . IPv6 not supported + . Not finished, does not build diff --git a/imap/docs/calendar.txt b/imap/docs/calendar.txt new file mode 100644 index 00000000..c1009078 --- /dev/null +++ b/imap/docs/calendar.txt @@ -0,0 +1,332 @@ +/* ======================================================================== + * Copyright 1988-2006 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 + * + * + * ======================================================================== + */ + + ALL ABOUT CALENDARS + + Although one can never be sure of what will happen at some future +time, there is strong historical precedent for presuming that the +present Gregorian calendar will still be in effect within the useful +lifetime of the IMAP toolkit. We have therefore chosen to adhere to +these precedents. + + The purpose of a calendar is to reckon time in advance, to show +how many days have to elapse until a certain event takes place in the +future, such as the harvest or the release of a new version of Pine. +The earliest calendars, naturally, were crude and tended to be based +upon the seasons or the lunar cycle. + + +ANCIENT CALENDARS + + The calendar of the Assyrians, for example, was based upon the +phases of the moon. They knew that a lunation (the time from one full +moon to the next) was 29 1/2 days long, so their lunar year had a +duration of 354 days. This fell short of the solar year by about 11 +days. (The exact time for the solar year is approximately 365 days, 5 +hours, 48 minutes, and 46 seconds.) After 3 years, such a lunar +calendar would be off by a whole month, so the Assyrians added an extra +month from time to time to keep their calendar in synchronization with +the seasons. + + The best approximation that was possible in antiquity was a 19-year +period, with 7 of these 19 years having 13 months (leap months). This +scheme was adopted as the basis for the lunar calendar used by the +Hebrews. The Arabs also used this calendar until Mohammed forbade +shifting from 12 months to 13 months; this causes the Muslim holy month +of Ramadan to move backwards through the seasons, completing a cycle +every 32 1/2 years. + + When Rome emerged as a world power, the difficulties of making a +calendar were well known, but the Romans complicated their lives because +of their superstition that even numbers were unlucky. Hence their +months were 29 or 31 days long, with the exception of February, which +had 28 days. Every second year, the Roman calendar included an extra +month called Mercedonius of 22 or 23 days to keep up with the solar +year. + + +JULIAN CALENDAR + + Even this algorithm was very poor, so that in 45 BCE, Caesar, +advised by the astronomer Sosigenes, ordered a sweeping reform. By +imperial decree, the year 46 BCE was made 445 days long to bring the +calendar back in step with the seasons. The new calendar, similar to +the one we now use was called the Julian calendar (named after Julius +Caesar). + + Months in the Julian calendar were 30 or 31 days in length and +every fourth year was made a leap year (having 366 days) by adding a day +to the end of the year. This leap year rule was not consistantly +applied until 8 CE. The year-ending month of February, never a popular +month, was presently shortened so that Julius Caesar and Emperor +Augustus could each have long months named after them. + + Caesar also decreed that the year would start with the first of +January, which since 153 BCE was the day that Roman consuls took office, +and not the vernal equinox in late March. Not everyone accepted that +part of his reform, as we shall see. + + +GREGORIAN CALENDAR + + Caesar's year was 11 1/2 minutes short of the calculations +recommended by Sosigenes and eventually the date of the vernal equinox +began to drift. Roger Bacon became alarmed and sent a note to Pope +Clement IV, who apparently was not impressed. Pope Sixtus IV later +became convinced that another reform was needed and called the German +astronomer, Regiomontanus, to Rome to advise him. Unfortunately, +Regiomontanus died of the plague shortly thereafter and the plans died +as well. + + In 1545, the Council of Trent authorized Pope Gregory XIII to +reform the calendar once more. Most of the mathematical work was done +by Father Christopher Clavius, S.J. The immediate correction that was +adopted was that Thursday, October 4, 1582 was to be the last day of the +Julian calendar. The next day was Friday, with the date of October 15. +For long range accuracy, a formula suggested by the Vatican librarian +Aloysius Giglio was adopted. It said that every fourth year is a leap +year except for century years that are not divisible by 400. Thus 1700, +1800 and 1900 would not be leap years, but 2000 would be a leap year +since 2000 is divisible by 400. This rule eliminates 3 leap years every +4 centuries, making the calendar sufficiently correct for most ordinary +purposes. This calendar is known as the Gregorian calendar and is the +one that we now use today. + + It is interesting to note that in 1582, all the Protestant princes +ignored the papal decree and so many countries continued to use the +Julian calendar until either 1698 or 1752. Britain and its American +colonies went from Wednesday, September 2, 1752 to Thursday, September +14. Prior to the changeover, the British used March 25 as the start of +the new year. + + In Russia, it needed the revolution to introduce the Gregorian +calendar in 1918. Turkey didn't adopt it until 1927. + + +NUMBERING OF YEARS + + The numbering of the year is generally done according to an "era", +such as the year of a ruler's reign. + + In about 525, a monk named Dionysius Exiguus suggested that the +calculated year of Jesus' birth be designated as year 1 in the Julian +calendar. This suggestion was adopted over the next 500 years and +subsequently followed in the Gregorian calendar. + + For the benefit of those who seek religious significance to the +calendar millenium, note that year 1 is too late by at least 4 years. +Herod the Great, named in the Christian Bible as having all children in +Bethlehem put to death in an attempt to kill the infant Jesus, died in 4 +BCE. + + Nothing particularly significant of an historic or religious nature +happened in Gregorian year 1; however it has become a worldwide standard +as the "common era." In modern times, the terms "CE" (common era) and +"BCE" (before common era) are preferred over the earlier (and, as we +have seen, less accurate) "AD" (anno Domini, "the year of the Lord") and +"BC" (before Christ). + + The Hebrew lunar calendar begins at 3760 BCE, the year of creation +in Jewish tradition. The Muslim lunar calendar begins on July 16, 622, +when Mohammed fled from Mecca to Medina. + + The Japanese, Taiwanese, and North Koreans use the Gregorian +calendar, but number the year by political era. In Japan, an era +begins when an emperor succeeds to the throne; year 1 of the Heisei +era was 1989 when Emperor Akihito ascended to the throne (the first +few days of 1989 was year 64 of the Shouwa era). In Taiwan, year 1 is +the first full year after the founding of the Republic of China in 1911. +In North Korea, year 1 is the year of the Juche (self-reliance) ideal, +corresponding to the birth year of founder Kim Il-Sung (1912). Thus, +year 2000 is Heisei 12 (Japan), 89th year of the Republic (Taiwan), +and Juche 89 (North Korea). + + +FURTHER MODIFICATIONS TO THE GREGORIAN CALENDAR + + Despite the great accuracy of the Gregorian calendar, it still +falls behind very slightly every few years. The most serious problem +is that the earth's rotation is slowing gradually. If you are very +concerned about this problem, we suggest that you tune in short wave +radio station WWV or the Global Positioning System, which broadcasts +official time signals for use in the United States. About once every +3 years, they declare a leap second at which time you should be +careful to adjust your system clock. If you have trouble picking up +their signals, we suggest you purchase an atomic clock (not part of +the IMAP toolkit). + + Another problem is that the Gregorian calendar represents a year +of 365.2425 days, whereas the actual time taken for the earth to +rotate around the Sun is 365.2421991 days. Thus, the Gregorian calendar +is actually 26 seconds slow each year, resulting in the calendar +being one day behind every 3,300 or so years (a Y3.3K problem). + + Consequently, the Gregorian calendar has been modified with a +further rule, which is that years evenly divisible by 4000 are not +leap years. Thus, the year 4000 will not be a leap year. Or, at +least we assume that's what will happen assuming that the calendar +remains unchanged for the next 2000 years. + + The modified Gregorian calendar represents a year of 365.24225 +days. Thus, the modified Gregorian calendar is actually 4 seconds +slow each year, resulting in the calendar being one day slow every +20,000 or so years. So there will be a Y20K problem. + + There is some dispute whether the modified Gregorian calendar was +officially adopted, or if it's just a proposal. Other options (see +below) exist; fortunately no decision needs to be made for several +centuries yet. + + There is code in c-client to support the modified Gregorian +calendar, although it is currently disabled. Sometime in the next +2000 years, someone will need to enable this code so that c-client is +Y4K compiliant. Then, 18,000 years from now, someone will have to +tear into c-client's code to fix the Y20K bug. + + +EASTERN ORTHODOX MODIFICATION OF THE GREGORIAN CALENDAR + + The Eastern Orthodox church in 1923 established its own rules to +correct the Julian calendar. In their calendar, century years modulo +900 must result in value of 200 or 600 to be considered a leap year. +Both the Orthodox and Gregorian calendar agree that the years 2000 and +2400 will be leap years, and the years 1900, 2100, 2200, 2300, 2500, +2600, 2700 are not. However, the year 2800 will be a leap year in the +Gregorian calendar but not in the Orthodox calendar; similarly, the +year 2900 will be a leap year in the Orthodox calendar but not in the +Gregorian calendar. Both calendars will agree that 3000 and +3100 are leap years, but will disagree again in 3200 and 3300. + + There is code in c-client to support the Orthodox calendar. It +can be enabled by adding -DUSEORTHODOXCALENDAR=1 to the c-client +CFLAGS, e.g. + make xxx EXTRACFLAGS="-DUSEORTHODOXCALENDAR=1" + + The Orthodox calendar represents a year of 365.24222222... days. +Thus, the Orthodox calendar is actually 2 seconds slow each year, +resulting in the calendar being one day slow every 40,000 or so years. +The Eastern Orthodox church has not yet made any statements on how the +Y40K bug will be fixed. + + +OTHER ISSUES AFFECTING THE CALENDAR IN THE FUTURE + + The effect of leap seconds also needs to be considered when +looking at the Y3.3K/Y4K, Y20K, and Y40K problems. Leap seconds put +the clock back in line with the Earth's rotation, whereas leap years +put the calendar back in line with the Earth's revolution. Since leap +seconds slow down the clock (and hence the calendar), they actually +bring the day of reckoning for the Gregorian and Orthodox calendars +sooner. + + Another factor is that the next ice age (technically, the end of +the current interglacial period; we are in the middle of an ice age +now!) is due around Y25K. It is not known what perturbations this will +cause on the Earth's rotation and revolution, nor what calendar +adjustments will be necessary at that time. + + Hence my use of "or so" in predicting the years that the calendar +will fall behind. The actual point may be anywhere from decades (in the +case of Y3.3K) to millenia (in the case of Y40K) off from these predictions. + + +MEANINGS OF DAY NAMES + + The names of days of the week from a combination of Roman and +Germanic names for celestial bodies: +. Sunday Latin "dies solis" => "Sun's day" +. Monday Latin "dies lunae" => "Moon's day" +. Tuesday Germanic "Tiw's day" => "Mars' day" +. Wednesday Germanic "Woden's day" => "Mercury's day" +. Thursday Germanic "Thor's day" => "Jupiter's day" +. Friday Germanic "Frigg's day" => "Venus' day" +. Saturday Latin "dies Saturni" => "Saturn's day" + + +MEANINGS OF MONTH NAMES + + The names of the months are from the Roman calendar: +. January Janus, protector of doorways +. February Februalia, a time for sacrifice to atone for sins +. March Mars, god of war +. April Latin "aperire" => "to open" buds +. May Maia, goddess of plant growth +. June Latin "juvenis" => "youth" +. July Julius Caesar +. August Augustus Caesar +. September Latin "septem" => "seven" +. October Latin "octo" => "eight" +. November Latin "novem" => "nine" +. December Latin "decem" => "ten" + + As you'll notice, the last four months are numbered 7 to 10, which +is an artifact of the time when the new year started in March. + + +INTERESTING FORMULAE + + There's another reason why the historical starting of the new year +is significant. Starting with March, the length of months follows a +mathematical series: + 31 30 31 30 31 31 30 31 30 31 31 28 + + This means that you can calculate the day of week for any +arbitrary day/month/year of the Gregorian calendar with the following +formula (note all divisions are integral): + _ _ + | 7 + 31*(m - 1) y y y | + dow = | d + -------------- + y + - - --- + --- | MOD 7 + |_ 12 4 100 400_| +where + d := day of month (1..31) + m := month in old style (March = 1..February = 12) + y := year in old style + dow := day of week (Tuesday = 0..Monday = 6) + + To convert from new style month/year to old style: + if (m > 2) m -= 2; /* Mar-Dec: subtract 2 from month */ + else m += 10,y--; /* Jan-Feb: months 11 & 12 of previous year */ + + Here's another fun formula. To find the number of days between two +days, calculate a pair of calendar days with the formula (again, all +divisions are integral), using new style month/year this time: + m + m + - + 8 y y y + d + 30 * (m - 1) + ----- + y * 365 + - - --- + --- - ld + 2 4 100 400 + +where: + d := day of month (1..31) + m := month in new style (January = 1..December = 12) + y := year in new style + ld := leap day correction factor: + 0 for January and February in non-leap years + 1 for January and February in leap years + 2 for all other months in all years + + In C code, the leap day correction factor is calculated as: + (m < 3) ? !(y % 4) && ((y % 100) || !(y % 400)) : 2 + + It's up to you to figure out how to adapt these formulas for the +Y4K bugfix and the Orthodox calendar. If you're really clever, try to +use these formulae to implement the C library ctime(), gmtime(), and +mktime() functions. Most C library implementations use a table of the +number of days in a month. You don't need it. + + +ACKNOWLEDGEMENT: + +The original version is from an old Digital Equipment Corporation SPR +answer for VMS. Modifications for c-client, and additional information +added by Mark Crispin. diff --git a/imap/docs/commndmt.txt b/imap/docs/commndmt.txt new file mode 100644 index 00000000..7fd9707b --- /dev/null +++ b/imap/docs/commndmt.txt @@ -0,0 +1,101 @@ +/* ======================================================================== + * Copyright 1988-2006 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 + * + * + * ======================================================================== + */ + +[I wrote this tongue-in-cheek, but there's a lot here that people who + build IMAP clients should take careful note. Most existing clients + violate at least one, generally several, of these commandments. + These are based on known user-visible problems that occur with various + commonly used clients. Put another way, behind each commandment is a + plethora of user (and server administrator) complaints caused by a + violator.] + + Ten Commandments of How to Write an IMAP client + Mark Crispin + +1. Thou shalt not assume that it is alright to open multiple IMAP +sessions selected on the same mailbox simultaneously, lest thou face +the righteous wrath of mail stores that doth not permit such access. +Instead, thou shalt labor mightily, even unto having to use thy brain +to thinketh the matter through, such that thy client use existing +sessions that are already open. + +2. Thou shalt not abuse the STATUS command by using it to check for +new mail on a mailbox that you already have selected in an IMAP +session; for that session hath already told thou about new mail +without thy having to ask. + +3. Thou shalt remember the 30 minute inactivity timeout, and remember +to speak to the IMAP server before that timeout expires. If thou +useth the IDLE command, thou shalt send DONE from the IDLE before 29 +minutes hath passed, and issue a new IDLE. If thou maketh no use of +IDLE, then thou shalt send NOOP every few minutes, and the server +shalt tell you about new mail, and there will be much rejoicing in the +land. + +4. Thou shalt not assume that all names are both the name of a mailbox +and the name of a upper level of hierarchy that contains mailboxes; +lest thou face the righteous wrath of mail stores in which a mailbox +is a file and a level of hierarchy is a directory. Thou shalt pay +diligent attention to the \NoSelect and \NoInferiors flags, so that +your users may praise you with great praise. + +5. Thou shalt learn and understand the unique features of IMAP, such +as the unsolicited data model, the strict ascending rule of UIDs, how +UIDs map to sequence numbers, the ENVELOPE and BODYSTRUCTURE +structures; so that thou may use the IMAP protocol effectively. For a +POP client hacked to babble IMAP protocol is still no more than a POP +client. + +6. Thou shalt remember untagged data sent by the server, and when thou +needest data thou shalt consult your memory before asking the server. +For those who must analyze thy protocol transactions are weak of +stomach, and are likely to lose their recent meal should they see thou +repeatedly re-fetch static data. + +7. Thou shalt labor with great effort to work within the IMAP +deleted/expunge model, even if thy own model is that of a trashcan; +for interoperability is paramount and a trashcan model can be done +entirely in the user interface. + +8. Thou shalt not fear to open multiple IMAP sessions to the server; +but thou shalt use this technique with wisdom. For verily it is true; +if thou doth desire to monitor continuously five mailboxes for new +mail, it is better to have five IMAP sessions continuously open on the +mailboxes. It is generally not good to do a succession of five SELECT +or STATUS commands on a periodic basis; and it is truly wretched to +open and close five sessions to do a STATUS or SELECT on a periodic +basis. The cost of opening and closing a session is great, especially +if that session is SSL/TLS protected; and the cost of a STATUS or +SELECT can also be great. By comparison, the cost of an open session +doing an IDLE or getting a NOOP every few minutes is small. Great +praise shall be given to thy wisdom in doing what is less costly +instead of "common sense." + +9. Thou shalt not abuse subscriptions, for verily the LIST command is +the proper way to discover mailboxes on the server. Thou shalt not +subscribe names to the user's subscription list without explicit +instructions from the user; nor shalt thou assume that only subscribed +names are valid. Rather, thou shalt treat subscribed names as akin to +a bookmarks, or perhaps akin to how Windows shows the "My Documents" +folder -- a set of names that are separate from the hierarchy, for +they are such. + +10. Thou shalt use the LIST "*" wildcard only with great care. If +thou doth not fully comprehend the danger of "*", thou shalt use only +"%" and forget about the existance of "*". + +Honor these commandments, and keep them holy in thy heart, so that thy +users shalt maximize their pleasure, and the server administrators +shalt sing thy praises and recommend thy work as a model for others to +emulate. + diff --git a/imap/docs/draft/README b/imap/docs/draft/README new file mode 100644 index 00000000..9aec4719 --- /dev/null +++ b/imap/docs/draft/README @@ -0,0 +1,19 @@ +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 new file mode 100644 index 00000000..f47c6cc7 --- /dev/null +++ b/imap/docs/draft/i18n.txt @@ -0,0 +1,1140 @@ +
+
+
+
+
+
+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/draft/sort.txt b/imap/docs/draft/sort.txt new file mode 100644 index 00000000..4453bb4d --- /dev/null +++ b/imap/docs/draft/sort.txt @@ -0,0 +1,885 @@ +IMAP Extensions Working Group M. Crispin +Internet-Draft K. Murchison +Intended status: Proposed Standard March 10, 2008 +Expires: September 10, 2008 +Document: internet-drafts/draft-ietf-imapext-sort-20.txt + + INTERNET MESSAGE ACCESS PROTOCOL - SORT AND THREAD EXTENSIONS + +Status of this Memo + + By submitting this Internet-Draft, each author represents that + any applicable patent or other IPR claims of which he or she is + aware have been or will be disclosed, and any of which he or she + becomes aware will be disclosed, in accordance with Section 6 of + BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF), its areas, and its working groups. Note that + other groups may also distribute working documents as + Internet-Drafts. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + The list of current Internet-Drafts can be accessed at + http://www.ietf.org/ietf/1id-abstracts.txt + + The list of Internet-Draft Shadow Directories can be accessed at + http://www.ietf.org/shadow.html. + + A revised version of this draft document will be submitted to the RFC + editor as a Proposed Standard for the Internet Community. Discussion + and suggestions for improvement are requested, and should be sent to + ietf-imapext@IMC.ORG. + + Distribution of this memo is unlimited. + +Abstract + + This document describes the base-level server-based sorting and + threading extensions to the [IMAP] protocol. These extensions + provide substantial performance improvements for IMAP clients which + offer sorted and threaded views. + +1. Introduction + + The SORT and THREAD extensions to the [IMAP] protocol provide a means + of server-based sorting and threading of messages, without requiring + that the client download the necessary data to do so itself. This is + particularly useful for online clients as described in [IMAP-MODELS]. + + A server which supports the base-level SORT extension indicates this + with a capability name which starts with "SORT". Future, + upwards-compatible extensions to the SORT extension will all start + with "SORT", indicating support for this base level. + + A server which supports the THREAD extension indicates this with one + or more capability names consisting of "THREAD=" followed by a + supported threading algorithm name as described in this document. + This provides for future upwards-compatible extensions. + + A server which implements the SORT and/or THREAD extensions MUST + collate strings in accordance with the requirements of I18NLEVEL=1, + as described in [IMAP-I18N], and SHOULD implement and advertise the + I18NLEVEL=1 extension. Alternatively, a server MAY implement + I18NLEVEL=2 (or higher) and comply with the rules of that level. + + Discussion: the SORT and THREAD extensions predate [IMAP-I18N] by + several years. At the time of this writing, all known server + implementations of SORT and THREAD comply with the rules of + I18NLEVEL=1, but do not necessarily advertise it. As discussed + in [IMAP-I18N] section 4.5, all server implementations should + eventually be updated to comply with the I18NLEVEL=2 extension. + + Historical note: the REFERENCES threading algorithm is based on the + [THREADING] algorithm written used in "Netscape Mail and News" + versions 2.0 through 3.0. + +2. Terminology + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [KEYWORDS]. + + The word "can" (not "may") is used to refer to a possible + circumstance or situation, as opposed to an optional facility of the + protocol. + + "User" is used to refer to a human user, whereas "client" refers to + the software being run by the user. + + In examples, "C:" and "S:" indicate lines sent by the client and + server respectively. + +2.1 Base Subject + + Subject sorting and threading use the "base subject," which has + specific subject artifacts removed. Due to the complexity of these + artifacts, the formal syntax for the subject extraction rules is + ambiguous. The following procedure is followed to determine the + "base subject", using the [ABNF] formal syntax rules described in + section 5: + + (1) Convert any RFC 2047 encoded-words in the subject to + UTF-8 as described in "internationalization + considerations." Convert all tabs and continuations to + space. Convert all multiple spaces to a single space. + + (2) Remove all trailing text of the subject that matches + the subj-trailer ABNF, repeat until no more matches are + possible. + + (3) Remove all prefix text of the subject that matches the + subj-leader ABNF. + + (4) If there is prefix text of the subject that matches the + subj-blob ABNF, and removing that prefix leaves a non-empty + subj-base, then remove the prefix text. + + (5) Repeat (3) and (4) until no matches remain. + + Note: it is possible to defer step (2) until step (6), but this + requires checking for subj-trailer in step (4). + + (6) If the resulting text begins with the subj-fwd-hdr ABNF + and ends with the subj-fwd-trl ABNF, remove the + subj-fwd-hdr and subj-fwd-trl and repeat from step (2). + + (7) The resulting text is the "base subject" used in the + SORT. + + All servers and disconnected (as described in [IMAP-MODELS]) clients + MUST use exactly this algorithm to determine the "base subject". + Otherwise there is potential for a user to get inconsistent results + based on whether they are running in connected or disconnected mode. + +2.2 Sent Date + + As used in this document, the term "sent date" refers to the date and + time from the Date: header, adjusted by time zone to normalize to + UTC. For example, "31 Dec 2000 16:01:33 -0800" is equivalent to the + UTC date and time of "1 Jan 2001 00:01:33 +0000". + + If the time zone is invalid, the date and time SHOULD be treated as + UTC. If the time is also invalid, the time SHOULD be treated as + 00:00:00. If there is no valid date or time, the date and time + SHOULD be treated as 00:00:00 on the earliest possible date. + + This differs from the date-related criteria in the SEARCH command + (described in [IMAP] section 6.4.4), which use just the date and not + the time, and are not adjusted by time zone. + + If the sent date can not be determined (a Date: header is missing or + can not be parsed), the INTERNALDATE for that message is used as the + sent date. + + When comparing two sent dates that match exactly, the order in which + the two messages appear in the mailbox (that is, by sequence number) + is used as a tie-breaker to determine the order. + +3. Additional Commands + + These commands are extension to the [IMAP] base protocol. + + The section headings are intended to correspond with where they would + be located in the main document if they were part of the base + specification. + +BASE.6.4.SORT. SORT Command + + Arguments: sort program + charset specification + searching criteria (one or more) + + Data: untagged responses: SORT + + Result: OK - sort completed + NO - sort error: can't sort that charset or + criteria + BAD - command unknown or arguments invalid + + The SORT command is a variant of SEARCH with sorting semantics for + the results. Sort has two arguments before the searching criteria + argument; a parenthesized list of sort criteria, and the searching + charset. + + The charset argument is mandatory (unlike SEARCH) and indicates + the [CHARSET] of the strings that appear in the searching + criteria. The US-ASCII and UTF-8 charsets MUST be implemented. + All other charsets are optional. + + There is also a UID SORT command which returns unique identifiers + instead of message sequence numbers. Note that there are separate + searching criteria for message sequence numbers and UIDs; thus the + arguments to UID SORT are interpreted the same as in SORT. This + is analogous to the behavior of UID SEARCH, as opposed to UID + COPY, UID FETCH, or UID STORE. + + The SORT command first searches the mailbox for messages that + match the given searching criteria using the charset argument for + the interpretation of strings in the searching criteria. It then + returns the matching messages in an untagged SORT response, sorted + according to one or more sort criteria. + + Sorting is in ascending order. Earlier dates sort before later + dates; smaller sizes sort before larger sizes; and strings are + sorted according to ascending values established by their + collation algorithm (see under "Internationalization + Considerations"). + + If two or more messages exactly match according to the sorting + criteria, these messages are sorted according to the order in + which they appear in the mailbox. In other words, there is an + implicit sort criterion of "sequence number". + + When multiple sort criteria are specified, the result is sorted in + the priority order that the criteria appear. For example, + (SUBJECT DATE) will sort messages in order by their base subject + text; and for messages with the same base subject text will sort + by their sent date. + + Untagged EXPUNGE responses are not permitted while the server is + responding to a SORT command, but are permitted during a UID SORT + command. + + The defined sort criteria are as follows. Refer to the Formal + Syntax section for the precise syntactic definitions of the + arguments. If the associated RFC-822 header for a particular + criterion is absent, it is treated as the empty string. The empty + string always collates before non-empty strings. + + ARRIVAL + Internal date and time of the message. This differs from the + ON criteria in SEARCH, which uses just the internal date. + + CC + [IMAP] addr-mailbox of the first "cc" address. + + DATE + Sent date and time, as described in section 2.2. + + FROM + [IMAP] addr-mailbox of the first "From" address. + + REVERSE + Followed by another sort criterion, has the effect of that + criterion but in reverse (descending) order. + Note: REVERSE only reverses a single criterion, and does not + affect the implicit "sequence number" sort criterion if all + other criteria are identicial. Consequently, a sort of + REVERSE SUBJECT is not the same as a reverse ordering of a + SUBJECT sort. This can be avoided by use of additional + criteria, e.g. SUBJECT DATE vs. REVERSE SUBJECT REVERSE + DATE. In general, however, it's better (and faster, if the + client has a "reverse current ordering" command) to reverse + the results in the client instead of issuing a new SORT. + + SIZE + Size of the message in octets. + + SUBJECT + Base subject text. + + TO + [IMAP] addr-mailbox of the first "To" address. + + Example: C: A282 SORT (SUBJECT) UTF-8 SINCE 1-Feb-1994 + S: * SORT 2 84 882 + S: A282 OK SORT completed + C: A283 SORT (SUBJECT REVERSE DATE) UTF-8 ALL + S: * SORT 5 3 4 1 2 + S: A283 OK SORT completed + C: A284 SORT (SUBJECT) US-ASCII TEXT "not in mailbox" + S: * SORT + S: A284 OK SORT completed + +BASE.6.4.THREAD. THREAD Command + +Arguments: threading algorithm + charset specification + searching criteria (one or more) + +Data: untagged responses: THREAD + +Result: OK - thread completed + NO - thread error: can't thread that charset or + criteria + BAD - command unknown or arguments invalid + + The THREAD command is a variant of SEARCH with threading semantics + for the results. Thread has two arguments before the searching + criteria argument; a threading algorithm, and the searching + charset. + + The charset argument is mandatory (unlike SEARCH) and indicates + the [CHARSET] of the strings that appear in the searching + criteria. The US-ASCII and UTF-8 charsets MUST be implemented. + All other charsets are optional. + + There is also a UID THREAD command which returns unique + identifiers instead of message sequence numbers. Note that there + are separate searching criteria for message sequence numbers and + UIDs; thus the arguments to UID THREAD are interpreted the same as + in THREAD. This is analogous to the behavior of UID SEARCH, as + opposed to UID COPY, UID FETCH, or UID STORE. + + The THREAD command first searches the mailbox for messages that + match the given searching criteria using the charset argument for + the interpretation of strings in the searching criteria. It then + returns the matching messages in an untagged THREAD response, + threaded according to the specified threading algorithm. + + All collation is in ascending order. Earlier dates collate before + later dates and strings are collated according to ascending values + established by their collation algorithm (see under + "Internationalization Considerations"). + + Untagged EXPUNGE responses are not permitted while the server is + responding to a THREAD command, but are permitted during a UID + THREAD command. + + The defined threading algorithms are as follows: + + ORDEREDSUBJECT + + The ORDEREDSUBJECT threading algorithm is also referred to as + "poor man's threading." The searched messages are sorted by + base subject and then by the sent date. The messages are then + split into separate threads, with each thread containing + messages with the same base subject text. Finally, the threads + are sorted by the sent date of the first message in the thread. + + The first message of each thread are siblings of each other + (the "root"). The second message of a thread is the child of + the first message, and subsequent messages of the thread are + siblings of the second message and hence children of the + message at the root. Hence, there are no grandchildren in + ORDEREDSUBJECT threading. + + Children in ORDEREDSUBJECT threading do not have descendents. + Client implementations SHOULD treat descendents of a child in + a server response as being siblings of that child. + + REFERENCES + + The REFERENCES threading algorithm threads the searched + messages by grouping them together in parent/child + relationships based on which messages are replies to others. + The parent/child relationships are built using two methods: + reconstructing a message's ancestry using the references + contained within it; and checking the original (not base) + subject of a message to see if it is a reply to (or forward of) + another message. + + Note: "Message ID" in the following description refers to a + normalized form of the msg-id in [RFC-2822]. The actual + text in an RFC 2822 may use quoting, resulting in multiple + ways of expressing the same Message ID. Implementations of + the REFERENCES threading algorithm MUST normalize any msg-id + in order to avoid false non-matches due to differences in + quoting. + + For example, the msg-id + <"01KF8JCEOCBS0045PS"@xxx.yyy.com> + and the msg-id + <01KF8JCEOCBS0045PS@xxx.yyy.com> + MUST be interpreted as being the same Message ID. + + The references used for reconstructing a message's ancestry are + found using the following rules: + + If a message contains a References header line, then use the + Message IDs in the References header line as the references. + + If a message does not contain a References header line, or + the References header line does not contain any valid + Message IDs, then use the first (if any) valid Message ID + found in the In-Reply-To header line as the only reference + (parent) for this message. + + Note: Although [RFC-2822] permits multiple Message IDs in + the In-Reply-To header, in actual practice this + discipline has not been followed. For example, + In-Reply-To headers have been observed with message + addresses after the Message ID, and there are no good + heuristics for software to determine the difference. + This is not a problem with the References header however. + + If a message does not contain an In-Reply-To header line, or + the In-Reply-To header line does not contain a valid Message + ID, then the message does not have any references (NIL). + + A message is considered to be a reply or forward if the base + subject extraction rules, applied to the original subject, + remove any of the following: a subj-refwd, a "(fwd)" + subj-trailer, or a subj-fwd-hdr and subj-fwd-trl. + + The REFERENCES algorithm is significantly more complex than + ORDEREDSUBJECT and consists of six main steps. These steps are + outlined in detail below. + + (1) For each searched message: + + (A) Using the Message IDs in the message's references, link + the corresponding messages (those whose Message-ID header + line contains the given reference Message ID) together as + parent/child. Make the first reference the parent of the + second (and the second a child of the first), the second the + parent of the third (and the third a child of the second), + etc. The following rules govern the creation of these + links: + + If a message does not contain a Message-ID header line, + or the Message-ID header line does not contain a valid + Message ID, then assign a unique Message ID to this + message. + + If two or more messages have the same Message ID, then + only use that Message ID in the first (lowest sequence + number) message, and assign a unique Message ID to each + of the subsequent messages with a duplicate of that + Message ID. + + If no message can be found with a given Message ID, + create a dummy message with this ID. Use this dummy + message for all subsequent references to this ID. + + If a message already has a parent, don't change the + existing link. This is done because the References + header line may have been truncated by a MUA. As a + result, there is no guarantee that the messages + corresponding to adjacent Message IDs in the References + header line are parent and child. + + Do not create a parent/child link if creating that link + would introduce a loop. For example, before making + message A the parent of B, make sure that A is not a + descendent of B. + + Note: Message ID comparisons are case-sensitive. + + (B) Create a parent/child link between the last reference + (or NIL if there are no references) and the current message. + If the current message already has a parent, it is probably + the result of a truncated References header line, so break + the current parent/child link before creating the new + correct one. As in step 1.A, do not create the parent/child + link if creating that link would introduce a loop. Note + that if this message has no references, that it will now + have no parent. + + Note: The parent/child links created in steps 1.A and 1.B + MUST be kept consistent with one another at ALL times. + + (2) Gather together all of the messages that have no parents + and make them all children (siblings of one another) of a dummy + parent (the "root"). These messages constitute the first + (head) message of the threads created thus far. + + (3) Prune dummy messages from the thread tree. Traverse each + thread under the root, and for each message: + + If it is a dummy message with NO children, delete it. + + If it is a dummy message with children, delete it, but + promote its children to the current level. In other words, + splice them in with the dummy's siblings. + + Do not promote the children if doing so would make them + children of the root, unless there is only one child. + + (4) Sort the messages under the root (top-level siblings only) + by sent date as described in section 2.2. In the case of a + dummy message, sort its children by sent date and then use the + first child for the top-level sort. + + (5) Gather together messages under the root that have the same + base subject text. + + (A) Create a table for associating base subjects with + messages, called the subject table. + + (B) Populate the subject table with one message per each + base subject. For each child of the root: + + (i) Find the subject of this thread, by using the base + subject from either the current message or its first + child if the current message is a dummy. This is the + thread subject. + + (ii) If the thread subject is empty, skip this message. + + (iii) Look up the message associated with the thread + subject in the subject table. + + (iv) If there is no message in the subject table with the + thread subject, add the current message and the thread + subject to the subject table. + + Otherwise, if the message in the subject table is not a + dummy, AND either of the following criteria are true: + + The current message is a dummy, OR + + The message in the subject table is a reply or forward + and the current message is not. + + then replace the message in the subject table with the + current message. + + (C) Merge threads with the same thread subject. For each + child of the root: + + (i) Find the message's thread subject as in step 5.B.i + above. + + (ii) If the thread subject is empty, skip this message. + + (iii) Lookup the message associated with this thread + subject in the subject table. + + (iv) If the message in the subject table is the current + message, skip this message. + + Otherwise, merge the current message with the one in the + subject table using the following rules: + + If both messages are dummies, append the current + message's children to the children of the message in + the subject table (the children of both messages + become siblings), and then delete the current message. + + If the message in the subject table is a dummy and the + current message is not, make the current message a + child of the message in the subject table (a sibling + of its children). + + If the current message is a reply or forward and the + message in the subject table is not, make the current + message a child of the message in the subject table (a + sibling of its children). + + Otherwise, create a new dummy message and make both + the current message and the message in the subject + table children of the dummy. Then replace the message + in the subject table with the dummy message. + + Note: Subject comparisons are case-insensitive, as + described under "Internationalization + Considerations." + + (6) Traverse the messages under the root and sort each set of + siblings by sent date as described in section 2.2. Traverse + the messages in such a way that the "youngest" set of siblings + are sorted first, and the "oldest" set of siblings are sorted + last (grandchildren are sorted before children, etc). In the + case of a dummy message (which can only occur with top-level + siblings), use its first child for sorting. + + Example: C: A283 THREAD ORDEREDSUBJECT UTF-8 SINCE 5-MAR-2000 + S: * THREAD (166)(167)(168)(169)(172)(170)(171) + (173)(174 (175)(176)(178)(181)(180))(179)(177 + (183)(182)(188)(184)(185)(186)(187)(189))(190) + (191)(192)(193)(194 195)(196 (197)(198))(199) + (200 202)(201)(203)(204)(205)(206 207)(208) + S: A283 OK THREAD completed + C: A284 THREAD ORDEREDSUBJECT US-ASCII TEXT "gewp" + S: * THREAD + S: A284 OK THREAD completed + C: A285 THREAD REFERENCES UTF-8 SINCE 5-MAR-2000 + S: * THREAD (166)(167)(168)(169)(172)((170)(179)) + (171)(173)((174)(175)(176)(178)(181)(180)) + ((177)(183)(182)(188 (184)(189))(185 186)(187)) + (190)(191)(192)(193)((194)(195 196))(197 198) + (199)(200 202)(201)(203)(204)(205 206 207)(208) + S: A285 OK THREAD completed + + Note: The line breaks in the first and third server + responses are for editorial clarity and do not appear in + real THREAD responses. + +4. Additional Responses + + These responses are extensions to the [IMAP] base protocol. + + The section headings of these responses are intended to correspond + with where they would be located in the main document. + +BASE.7.2.SORT. SORT Response + + Data: zero or more numbers + + The SORT response occurs as a result of a SORT or UID SORT + command. The number(s) refer to those messages that match the + search criteria. For SORT, these are message sequence numbers; + for UID SORT, these are unique identifiers. Each number is + delimited by a space. + + Example: S: * SORT 2 3 6 + +BASE.7.2.THREAD. THREAD Response + + Data: zero or more threads + + The THREAD response occurs as a result of a THREAD or UID THREAD + command. It contains zero or more threads. A thread consists of + a parenthesized list of thread members. + + Thread members consist of zero or more message numbers, delimited + by spaces, indicating successive parent and child. This continues + until the thread splits into multiple sub-threads, at which point + the thread nests into multiple sub-threads with the first member + of each subthread being siblings at this level. There is no limit + to the nesting of threads. + + The messages numbers refer to those messages that match the search + criteria. For THREAD, these are message sequence numbers; for UID + THREAD, these are unique identifiers. + + Example: S: * THREAD (2)(3 6 (4 23)(44 7 96)) + + The first thread consists only of message 2. The second thread + consists of the messages 3 (parent) and 6 (child), after which it + splits into two subthreads; the first of which contains messages 4 + (child of 6, sibling of 44) and 23 (child of 4), and the second of + which contains messages 44 (child of 6, sibling of 4), 7 (child of + 44), and 96 (child of 7). Since some later messages are parents + of earlier messages, the messages were probably moved from some + other mailbox at different times. + + -- 2 + + -- 3 + \-- 6 + |-- 4 + | \-- 23 + | + \-- 44 + \-- 7 + \-- 96 + + Example: S: * THREAD ((3)(5)) + + In this example, 3 and 5 are siblings of a parent which does not + match the search criteria (and/or does not exist in the mailbox); + however they are members of the same thread. + +5. Formal Syntax of SORT and THREAD Commands and Responses + + The following syntax specification uses the Augmented Backus-Naur + Form (ABNF) notation as specified in [ABNF]. It also uses [ABNF] + rules defined in [IMAP]. + +sort = ["UID" SP] "SORT" SP sort-criteria SP search-criteria + +sort-criteria = "(" sort-criterion *(SP sort-criterion) ")" + +sort-criterion = ["REVERSE" SP] sort-key + +sort-key = "ARRIVAL" / "CC" / "DATE" / "FROM" / "SIZE" / + "SUBJECT" / "TO" + +thread = ["UID" SP] "THREAD" SP thread-alg SP search-criteria + +thread-alg = "ORDEREDSUBJECT" / "REFERENCES" / thread-alg-ext + +thread-alg-ext = atom + ; New algorithms MUST be registered with IANA + +search-criteria = charset 1*(SP search-key) + +charset = atom / quoted + ; CHARSET values MUST be registered with IANA + +sort-data = "SORT" *(SP nz-number) + +thread-data = "THREAD" [SP 1*thread-list] + +thread-list = "(" (thread-members / thread-nested) ")" + +thread-members = nz-number *(SP nz-number) [SP thread-nested] + +thread-nested = 2*thread-list + + The following syntax describes base subject extraction rules (2)-(6): + +subject = *subj-leader [subj-middle] *subj-trailer + +subj-refwd = ("re" / ("fw" ["d"])) *WSP [subj-blob] ":" + +subj-blob = "[" *BLOBCHAR "]" *WSP + +subj-fwd = subj-fwd-hdr subject subj-fwd-trl + +subj-fwd-hdr = "[fwd:" + +subj-fwd-trl = "]" + +subj-leader = (*subj-blob subj-refwd) / WSP + +subj-middle = *subj-blob (subj-base / subj-fwd) + ; last subj-blob is subj-base if subj-base would + ; otherwise be empty + +subj-trailer = "(fwd)" / WSP + +subj-base = NONWSP *(*WSP NONWSP) + ; can be a subj-blob + +BLOBCHAR = %x01-5a / %x5c / %x5e-ff + ; any CHAR8 except '[' and ']' + +NONWSP = %x01-08 / %x0a-1f / %x21-ff + ; any CHAR8 other than WSP + +6. Security Considerations + + The SORT and THREAD extensions do not raise any security + considerations that are not present in the base [IMAP] protocol, and + these issues are discussed in [IMAP]. Nevertheless, it is important + to remember that [IMAP] protocol transactions, including message + data, are sent in the clear over the network unless protection from + snooping is negotiated, either by the use of STARTTLS, privacy + protection is negotiated in the AUTHENTICATE command, or some other + protection mechanism. + + Although not a security consideration, it is important to recognize + that sorting by REFERENCES can lead to misleading threading trees. + For example, a message with false References: header data will cause + a thread to be incorporated into another thread. + + The process of extracting the base subject may lead to incorrect + collation if the extracted data was significant text as opposed to + a subject artifact. + +7. Internationalization Considerations + + As stated in the introduction, the rules of I18NLEVEL=1 as described + in [IMAP-I18N] MUST be followed; that is, the SORT and THREAD + extensions MUST collate strings according to the i;unicode-casemap + collation described in [UNICASEMAP]. Servers SHOULD also advertise + the I18NLEVEL=1 extension. Alternatively, a server MAY implement + I18NLEVEL=2 (or higher) and comply with the rules of that level. + + As discussed in [IMAP-I18N] section 4.5, all server implementations + should eventually be updated to support the [IMAP-I18N] I18NLEVEL=2 + extension. + + Translations of the "re" or "fw"/"fwd" tokens are not specified for + removal in the base subject extraction process. An attempt to add + such translated tokens would result in a geometrically complex, and + ultimately unimplementable, task. + + Instead, note that [RFC-2822] section 3.6.5 recommends that "re:" + (from the Latin "res", in the matter of) be used to identify a reply. + Although it is evident that, from the multiple forms of token to + identify a forwarded message, there is considerable variation found + in the wild, the variations are (still) manageable. Consequently, it + is suggested that "re:" and one of the variations of the tokens for + forward supported by the base subject extraction rules be adopted for + Internet mail messages, since doing so makes it a simple display time + task to localize the token language for the user. + +8. IANA Considerations + + [IMAP] capabilities are registered by publishing a standards track or + IESG approved experimental RFC. This document constitutes + registration of the SORT and THREAD capabilities in the [IMAP] + capabilities registry. + + This document creates a new [IMAP] threading algorithms registry, + which registers threading algorithms by publishing a standards track + or IESG approved experimental RFC. This document constitutes + registration of the ORDEREDSUBJECT and REFERENCES algorithms in that + registry. + +9. Normative References + + The following documents are normative to this document: + + [ABNF] Crocker, D. and Overell, P. "Augmented BNF + for Syntax Specifications: ABNF", RFC 5234 + January 2008 + + [CHARSET] Freed, N. and Postel, J. "IANA Character Set + Registration Procedures", RFC 2978, October + 2000. + + [IMAP] Crispin, M. "Internet Message Access Protocol - + Version 4rev1", RFC 3501, March 2003. + + [IMAP-I18N] Newman, C. and Gulbrandsen, A. "Internet + Message Access Protocol Internationalization", + Work in Progress. + + [KEYWORDS] Bradner, S. "Key words for use in RFCs to + Indicate Requirement Levels", BCP 14, RFC 2119, + March 1997. + + [RFC-2822] Resnick, P. "Internet Message Format", RFC + 2822, April 2001. + + [UNICASEMAP] Crispin, M. "i;unicode-casemap - Simple Unicode + Collation Algorithm", RFC 5051. + +10. Informative References + + The following documents are informative to this document: + + [IMAP-MODELS] Crispin, M. "Distributed Electronic Mail Models + in IMAP4", RFC 1733, December 1994. + + [THREADING] Zawinski, J. "Message Threading", + http://www.jwz.org/doc/threading.html, + 1997-2002. + +Appendices + +Author's Address + + Mark R. Crispin + Networks and Distributed Computing + University of Washington + 4545 15th Avenue NE + Seattle, WA 98105-4527 + + Phone: +1 (206) 543-5762 + + EMail: MRC@CAC.Washington.EDU + + Kenneth Murchison + Carnegie Mellon University + 5000 Forbes Avenue + Cyert Hall 285 + Pittsburgh, PA 15213 + + Phone: +1 (412) 268-2638 + Email: murch@andrew.cmu.edu + +Full Copyright Statement + + Copyright (C) The IETF Trust (2008). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at ietf- + ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. diff --git a/imap/docs/drivers.txt b/imap/docs/drivers.txt new file mode 100644 index 00000000..de91aa53 --- /dev/null +++ b/imap/docs/drivers.txt @@ -0,0 +1,189 @@ +/* ======================================================================== + * Copyright 1988-2006 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 + * + * + * ======================================================================== + */ + + c-client Driver Characteristics + Mark Crispin + 11 December 2006 + + + Drivers are code modules that support different mailbox storage +technologies. A mailbox storage technology may be implemented by + 1) files and directories on the local system + 2) a database + 3) a network protocol. + + In the case of files and directories on the local system, a +driver supports a particular mailbox format. Mailbox formats are +discussed in more detail in the file formats.txt. + + As of the date this document was written, there was no bundled +support for any databases in c-client. However, it should not be +particularly difficult to write a driver that communicates with a +database. + + Network protocols supported by c-client drivers are the Internet +Mail Access Protocol (all versions: IMAP4rev1, IMAP4, IMAP2bis, and +IMAP2); the Post Office Protocol (version 3); and the Network News +Transport Protocol (NNTP). In addition, c-client also supports NNTP +and the Simple Mail Transport Protocol (SMTP) for mailbox transport. + + By default, all drivers are enabled. There is little benefit to +be gained by disabling a driver, with one exception. The mbox driver +implements the behavior of automatically moving new mail from the +spool directory to the "mbox" file on the user's home directory, if +and *only* if the "mbox" exists and is in mailbox format. The mbox +driver is listed under EXTRADRIVERS; if you wish to disable it just +remove it from that list and rebuild. + +I. Special name "INBOX" + +The following rules to select INBOX and its format apply in +the order given if "black box mode" is not in effect: + 1) mbox format is selected if file ~/mbox exists, and is in unix + format or is zero-length. + 2) mx format is selected if file ~/INBOX/.mxindex exists. + 3) mbx format is selected if file ~/INBOX exists and is in mbx format. + 4) tenex format is selected if: + a) file ~/mail.txt exists, and is in tenex format or is zero-length. + b) file ~/INBOX exists and is in tenex format. + 5) mtx format is selected if: + a) file ~/INBOX.MTX exists, and is in mtx format or is zero-length. + b) file ~/INBOX exists and is in mtx format. + 6) mmdf format is selected if the spool directory file exists and is + in mmdf format. + 7) unix format is selected if the spool directory file exists and is + in unix format. + 8) the dummy driver is selected if the spool directory file does not + exist, or exists and is empty. + +If "black box mode" is not in effect, messages are automatically +transferred ("snarfed") from the spool directory to an INBOX in mbox, +mx, mbx, tenex, and mtx formats. + +The following rules to select INBOX and its format apply in the order +given if "black box mode" is in effect: + 1) mx format is selected if file ~/INBOX/.mxindex exists. + 2) mbx format is selected if file ~/INBOX exists and is in mbx format. + 3) tenex format is selected if file ~/INBOX exists and is in tenex format. + 4) mtx format is selected if file ~/INBOX exists and is in mtx format. + 5) mmdf format is selected if file ~/INBOX exists and is in mmdf format. + 6) unix format is selected if file ~/INBOX exists and is in unix format. + 7) the dummy driver is selected if ~/INBOX does not exist, or exists + and is empty. + +II. Special Name #mhinbox + +#mhinbox always refers to the directory "inbox" in the MH path, which +is declared in the ~/.mh_profile file. Messages are automatically +transferred from the spool directory to #mhinbox mailbox. + + +III. Special Prefix "#mh/" + +Any name prefixed with "#mh/" always refers to a directory in the MH +path, which is declared in the ~/.mh_profile file. For example, the name +"#mh/foo" refers to directory "foo" in the MH path. + + +IV. Special prefix "#news." + +Any name prefixed with "#news" always refers to a newsgroup. For +example, the name "#news.comp.mail.misc" refers to newsgroup +"comp.mail.misc". + + +V. All Other Names + +The driver is selected by generating a file name from the mailbox +name, and then examining the data of the object with the resulting +name. The formats are checked in order: mx, mbx, tenex, mtx, mmdf, +unix, and phile. The dummy driver is selected if the file is empty. + +The file name is generated according to certain rules, based upon the +prefix of the mailbox name. On UNIX, the following rules apply: + +Prefix Interpretation of Suffix +------ ------------------------ +/ [black box] preceeds a user name; "/foo/bar" means + "black box user foo's mailbox bar" + [not black box] preceeds an absolute path name. +~ [not black box] preceeds a user name; "~foo/bar" means + "UNIX user foo's mailbox bar" +#ftp/ preceeds UNIX user ftp's mailbox name +#public/ preceeds UNIX user imappublic's mailbox name +#shared/ preceeds UNIX user imapshared's mailbox name + +All other names are interpreted in the context of the UNIX user's home +directory (not black box), the black box user's black box directory +(black box), or UNIX user ftp's home directory (anonymous). + +The strings "..", "//", and /~ are forbidden in names in: + black box mode + #ftp, #public, or #shared names + anonymous users + +Anonymous users may only access: + INBOX (belonging to UNIX user ftp) + files in or below UNIX user ftp's home directory + #ftp, #news, and #public namespace + +VI. Driver Comparison + +The following information about the local file drivers is an +elaboration of a table compiled by Osma Ahvenlampi. + +Driver CA CE UID Kwd Sub NFS Performance Layout +------ -- -- --- --- --- --- ----------- ------ +unix no no yes yes no limited fair file + ;;; traditional UNIX format +mbox no no yes yes no limited fair file + ;;; traditional UNIX format, INBOX only, using ~/mbox with automatic + ;;; moving from the mail spool directory. +mmdf no no yes yes no limited fair file + ;;; default on SCO systems +mbx yes yes yes yes no no very good prefile + ;;; best performing local file driver; preferred format at UW +tenex yes no no limited no no good prefile + ;;; compatible with UNIX MM +mtx yes no no limited no no very good prefile + ;;; PC Pine standard format; compatible with TOPS-20; identical to tenex + ;;; but instead CRLF newlines instead of LF +mx yes buggy yes yes yes no poor ixdir + ;;; fullest function; *not* recommended due to performance problems and bugs; + ;;; to be redesigned/rewritten +mh yes no no no yes yes very poor dir + ;;; compatible with mh; #mhinbox for INBOX, #mh/ prefix for all other names +news yes no yes no yes yes very poor ixdir + ;;; local news spool access; #news. prefix for all names +phile no no no no no yes good file + ;;; reads arbitrary file as a single readonly message + +IMPORTANT: the "performance" ratings are relative to other drivers, +and not necessarily to other software which implements those formats. +They relate to the driver's performance in typical operations such as +an IMAP "FETCH ALL". + +Key to headings: + CA: concurrent read/write access + CE: expunge permitted in concurrent read/write access + UID: sticky UIDs + Kwd: keyword flags + Sub: subfolders + NFS: usable over network filesystems (NFS, AFS, etc.) + Layout: file - single file + prefile - file with preallocated space for state + dir - directory, messages are files + ixdir - directory, messages are files, with helper index + +In addition, drivers imap, nntp, and pop3 support IMAP4rev1, NNTP, and +POP3 protocols respectively. diff --git a/imap/docs/formats.txt b/imap/docs/formats.txt new file mode 100644 index 00000000..8dfb9dae --- /dev/null +++ b/imap/docs/formats.txt @@ -0,0 +1,217 @@ +/* ======================================================================== + * Copyright 1988-2006 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 + * + * + * ======================================================================== + */ + + Mailbox Format Characteristics + Mark Crispin + 11 December 2006 + + + When a mailbox storage technology uses local files and +directories directly, the file(s) and directories are layed out in a +mailbox format. + +I. Flat-File Formats + + In these formats, a mailbox and all the messages inside are a +single file on the filesystem. The mailbox name is the name of the +file in the filesystem, relative to the user's "mail home directory." + + A flat-file format mailbox is always a file, never a directory. +This means that it is impossible to have a flat-file format mailbox +that has inferior mailbox names under it (so-called "dual-usage" +mailboxes). For some inexplicable reason, some people want this. + + The mail home directory is usually the same as the user login +home directory if that concept is meaningful; otherwise, it is some +other default directory (e.g. "C:\My Documents" on Windows 98). This +can be redefined by modifying the c-client source code or in an +application via the SET_HOMEDIR mail_parameters() call. + + For example, a mailbox named "project" is likely to be found in +the file "project" in the user's home directory. Similarly, a mailbox +named "test/trial1" (assuming a UNIX system) is likely to be found in +the file "trial1" in the subdirectory "test" in the user's home +directory. + + Note that the name "INBOX" has special semantics and rules, as +described in the file naming.txt. + + The following flat-file formats are supported by c-client as of +the time of this writing: + +. unix This is the traditional UNIX mailbox format, in use for nearly + 30 years. It uses a line starting with "From " to indicate + start of message, and stores the message status inside the + RFC822 message header. + + unix is not particularly efficient; the entire mailbox file + must be read when the mailbox is open, and when reading message + texts it is necessary to convert the newline convention to + Internet standard CR LF form. unix preserves UIDs, and allows + the creation of keywords. + + Only one process may have a unix-format mailbox open + read/write at a time. + +. mmdf This is the format used by the MMDF mailer. It uses a line + consisting of 4 <CTRL/A> (0x01) characters to indicate start + and end of message. Optionally, there may also be a unix + format "From " line. It otherwise has the same + characteristics as unix format. + +. mbx This is the current preferred mailbox format. It can be + handled quite efficiently by c-client, without the problems + that exist with unix and mmdf formats. Messages are stored + in Internet standard CR LF format. + + mbx permits shared access, including shared expunge. It + preserves UIDs, and allows the creation of keywords. + +. mtx This is supported for compatibility with the past. This is + the old Tenex/TOPS-20 mail.txt format. It can be handled + quite efficiently by c-client, and has most of the + characteristics of mbx format. + + mtx is deficient in that it does not support shared expunge; + it has no means to store UIDs; and it has no way to define + keywords except through an external configuration file. + +. tenex This is supported for compatibility with the past. This is + the old Columbia MM format. This is similar to mtx format, + only it uses UNIX-style bare-LF newlines instead of CR LF + newlines, thus incurring a performance penalty for newline + conversion. + +. phile This is not strictly a format. Any file which is not in a + recognized format is in phile format, which treats the entire + contents of the file as a single message. + + +II. File/Message Formats + + In these formats, a mailbox is a directory, and each the messages +inside are separate files inside the directory. The file names of +these files are generally the text form of a number, which also +matches the UID of the message. + + In the case of mx, the mailbox name is the name of the directory +in the filesystem, relative to the user's "mail home directory." In +the case of news and mh, the mailbox name is in a separate namespace +as described in the file naming.txt. + + A file/message format mailbox is always a directory. This means +that it is possible to have a file/message format mailbox that has +inferior mailbox names under it (so-called "dual-usage" mailboxes). +For some inexplicable reason, some people want this. + + Note that the name "INBOX" has special semantics and rules, as +described in the file naming.txt. + + The following file/message formats are supported by c-client as of +the time of this writing: + +. mx This is an experimental format, and may be removed in a future + release. An mx format mailbox has a .mxindex file which holds + the message status and unique identifiers. Messages are + stored in Internet standard CF LF form, so the file size of + the message file equals the size of the message. + + mx is somewhat inefficient; the entire directory must be read + and each file stat()'d. We found it intolerable for a + moderate sized mailbox (2000 messages) and have more or less + abandoned it. + +. mh This is supported for compatibility with the past. This is + the format used by the old mh program. + + mh is very inefficient; the entire directory must be read + and each file stat()'d, and in order to determine the size + of a message, the entire file must be read and newline + conversion performed. + + mh is deficient in that it does not support any permanent + flags or keywords; and has no means to store UIDs (because + the mh "compress" command renames all the files, that's + why). + +. news This is an export of the local filesystem's news spool, e.g. + /var/spool/news. Access to mailboxes in news format is read + only; however, message "deleted" status is preserved in a + .newsrc file in the user's home directory. There is no other + status or keywords. + + news is very inefficient; the entire directory must be + read and each file stat()'d, and in order to determine the + size of a message, the entire file must be read and newline + conversion performed. + + news is deficient in that it does not support permanent flags + other than deleted; does not support keywords; and has no + expunge. + + +Soapbox on File/Message Formats + + If it sounds from the above descriptions that we're not putting +too much effort into file/message formats, you are correct. + + There's a general reason why file/message formats are a bad idea. +Just about every filesystem in existance serializes file creation and +deletions because these manipulate the free space map. This turns out +to be an enormous problem when you start creating/deleting more than a +few messages per second; you spend all your time thrashing in the +filesystem. + + It is also extremely slow to do a text search through a +file/message format mailbox. All of those open()s and close()s really +add up to major filesystem thrashing. + + +What about Cyrus and Maildir? + + Both formats are vulnerable to the filesystem thrashing outlined +above. + + The Cyrus format used by CMU's Cyrus server (and Esys' server) +has a special associated flat file in each directory that contains +extensive data (including pre-parsed ENVELOPEs and BODYSTRUCTUREs) +about the messages. Put another way, it's a (considerably) more +featureful form of mx. It also uses certain operating system +facilities (e.g. file/memory mapping) which are not available on older +systems, at a cost of much more limited portability than c-client. +These considerably ameliorate the fundamental problems with +file/message formats; in fact, Cyrus is halfway to being a database. +Rather than support Cyrus format in c-client, you should run Cyrus or +Esys if you want that format. + + The Maildir format used by qmail has all of the performance +disadvantages of mh noted above, with the additional problem that the +files are renamed in order to change their status so you end up having +to rescan the directory frequently to locate the current names +(particularly in a shared mailbox scenario). It doesn't scale, and it +represents a support nightmare; it is therefore not supported in the +official distribution. Maildir support code for c-client is available +from third parties; but, if you use it, it is entirely at your own +risk (read: don't complain about how poorly it performs or bugs). + + +So what does this all mean? + + A database (such as used by Exchange) is really a much better +approach if you want to move away from flat files. mx and especially +Cyrus take a tenative step in that direction; mx failed mostly because +it didn't go anywhere near far enough. Cyrus goes much further, and +scores remarkable benefits from doing so. + + However, a well-designed pure database without the overhead of +separate files would do even better. diff --git a/imap/docs/imaprc.txt b/imap/docs/imaprc.txt new file mode 100644 index 00000000..cda153a6 --- /dev/null +++ b/imap/docs/imaprc.txt @@ -0,0 +1,613 @@ +/* ======================================================================== + * Copyright 1988-2006 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 + * + * + * ======================================================================== + */ + + .imaprc secrets revealed! + Mark Crispin, June 17, 2002 + +The following information describes the format of the /etc/c-client.cf +and ~/.imaprc file. The Columbia MM ~/.mminit file is also read by +c-client; however, the only command that ~/.mminit has in common is +set keywords. + +********************************************************************** +* DANGER! BEWARE! TAKE CARE! * +********************************************************************** +* * +* These files, and this documentation, are for internal UW usage * +* only. This capability is for UW experimental tinkering, and most * +* emphatically *not* for sorcerer's apprentices at other sites who * +* feel that if a config file capability exists, they must write a * +* config file whether or not there is any need for one. * +* * +* This information is subject to change without notice. Commands * +* may be added, removed, or altered. The behavior of comamnds may * +* change. Do not use any of this information without consulting me * +* first. c-client's defaults have been carefully chosen to be right * +* for general-purpose and most special-purpose configurations. If * +* you tinker with these defaults, all hell may break loose. * +* * +* This is not an idle threat. There have been several instances of * +* people who ignored these warnings and have gotten burned. * +* * +* Don't even trust this file to work. Many of the things which can * +* be changed by this file can also be changed by the application, * +* and it is totally unpredictable which will take precedence. It * +* all depends upon how the application is coded. Not only that, you * +* may cause the application to crash. * +* * +* In other words, keep your cotton-pickin' hands off my defaults. * +* If it crashes and erases your mail, I don't want to hear about it. * +* Consider 'em ``mandatory defaults''. Got a nice ring, eh? :-) If * +* you must tinker with defaults, play with the .pinerc and pine.conf * +* files in Pine. It's got options galore, all supported for you to * +* have fun. They're also documented; so well documented, it takes * +* two strong men to carry around all the documentation. ;-) ;-) * +* * +* Joking aside, you really shouldn't be fooling around with this * +* capability. It's dangerous, and you can shoot yourself in the * +* foot easily. If you need custom changes, you are better off with * +* local source code modifications. Seriously. * +* * +* One last warning: don't believe anything that you read in this * +* document. Every effort has been made to ensure that this document * +* is incomplete and inaccurate, and I take no responsibility for any * +* glimmers of correct information that may, by some fluke, be here. * +* * +********************************************************************** + +The files are read in order: /etc/c-client.cf, ~/.mminit, ~/.imaprc, +and an entry in a later file overrides the setting of an earlier file +except as noted below. This ordering and overriding behavior may +change without notice. + +Almost all of these facilities can also be set via the mail_parameters() +call in the program. Whether the file overrides mail_parameters(), or +mail_parameters() overrides the file, is indeterminate. It will vary +from program to program, and it may be one way in one version and the +other way in the next version. It's completely unpredictable, and so +anything you do with these files has to be in complete knowledge of what +the version of each program you're running is going to do. This is +because the files do something for testing, but the real capability for +configurability is put in the program instead. Are you getting the +feeling that you shouldn't be messing with these files yet? + +The very first line of the file MUST start with the exact string "I +accept the risk". This ensures that you have checked the file for +correctness against this version of the IMAP toolkit. This enable +string may change without notice in future versions, and the new +string may or may not be accurately described in an updated version of +this file. So any time you install software that uses the IMAP +toolkit, you need to check the new version against these files (if you +have insisted upon creating them in spite of all warnings). If two +pieces of software use different versions of the IMAP toolkit with +incompatible requirements, one of them won't work. Re-read the +warning above about why you should not use these files. + +Subsequent lines are read from the file one at a time. Case does not +matter. Unrecognized commands are ignored. + +1) set new-folder-format + sets what format new mailboxes are created in. This also controls + default delivery via tmail and dmail. + + a) set new-folder-format same-as-inbox + Folder is created using the same mailbox format as INBOX. If + INBOX is empty, it defaults to system standard. + + b) set new-folder-format system-standard + This is the default. Folder is created using the wired-in system + standard format, which on most UNIX systems is ordinary UNIX + /bin/mail format. On SCO systems, this is MMDF. + + c) set new-folder-format <driver name> + Folder is created using the given driver name, e.g. mbx, unix, + mmdf, etc. + + There is no protection against setting this to a silly value (e.g. + news, nntp, dummy) and doing so is a great way to screw things up. + Setting this to mh does not do what you think it does. Setting this + to tenex or mtx isn't particularly useful. + +2) set empty-folder-format + sets what format data is written into an empty mailbox file using + mail_copy() or mail_append(). This also controls default delivery + via tmail. + + a) set empty-folder-format same-as-inbox + Data is written using the same mailbox format as INBOX. If + INBOX is empty, it defaults to system standard. + + b) set empty-folder-format system-standard + This is the default. Data is written using the wired-in system + standard format, which on most UNIX systems is ordinary UNIX + /bin/mail format. On SCO systems, this is MMDF. + + c) set-empty-folder-format <driver name> + Data is written using the given driver name, e.g. tenex, unix, + mmdf, etc. + + There is no protection against setting this to a silly value (e.g. + news, nntp, dummy) and doing so is a great way to screw things up. + Setting this to mh, mbx, or mx does not work. + +3) set keywords <word1>, <word2>, ... <wordn> + Sets the list of keyword flags (supported by tenex and mtx) to the + given list. Up to 30 flags may be given. Since these names + correspond to numeric bits, the order of the keywords can not be + changed, nor can keywords be removed or inserted (you can append + new keywords, up to the limit of 30). + + Set keywords is a deprecated command. It may not appear in + future versions, or it may appear in a changed form. It exists + only for compatibility with MM, and should only appear in ~/.mminit + and not in the other files. It is likely to disappear entirely in + IMAP4. + + There is no protection against setting these to silly values, and + doing so is a great way to cause a crash. + +4) set from-widget header-only + Sets smart insertion of the > character in front of lines that + begin with ``From ''. Only such lines that are also in UNIX mbox + header file format will have a > character inserted. The default + is to insert the > character in front of all lines which begin with + ``From '', for the benefit of legacy tools that get confused + otherwise. + +5) set black-box-directory <directory name> + Sets the directory in which the user's data can be found. A user's + folders can be found in a subdirectory of the black box directory + named with the user's username. For example, if the blackbox + directory is /usr/spool/folders/, user jones' data can be found + in /usr/spool/folders/jones/. The user's black-box directory is + the location of folders, .mminit, .imaprc, .newsrc, and all other + files used by c-client; internally, it sets c-client's idea of the + user's ``home directory'', overriding /etc/passwd. + + This command may not appear in ~/.mminit or ~/.imaprc + + In black-box mode, it is not permitted to access any folders + outside of the user's personal blackbox directory. The breakouts + ``/'', ``~'', and ``..'' are not permitted. + + In order to make this work without crashing, you must set another + option which is not listed in this document. + + There is no protection against setting this to a silly value, and + doing so is a great way to cause a crash. + +6) set local-host <host name> + Sets c-client's idea of the local host name. + + There is no protection against setting this to a silly value, and + doing so is a great way to cause a crash. + +7) set news-active-file <file name> + Sets the location of the news active file, if it is not in the + standard place. + + It is recommended to use a courtesy symbolic link instead. + + There is no protection against setting this to a silly value, and + doing so is a great way to cause a crash. + +8) set news-spool-directory <directory name> + Sets the location of the news spool, if it is not in the standard + place. + + It is recommended to use a courtesy symbolic link instead. + + There is no protection against setting this to a silly value, and + doing so is a great way to cause a crash. + +9) set news-state-file <file name> + Sets the location of the news state file (normally $(USER)/.newsrc). + + This is not very useful in /etc/c-client.cf because it is a file name. + Setting this in /etc/c-client.cf would set all users to the same file + as their newsrc, which is probably not what you want. + + There is no protection against setting this to a silly value, and + doing so is a great way to cause a crash. + +10) set system-inbox <file name> + Sets the location of the "system inbox", if it is not in the standard + place. This is the default location of INBOX, or the mail drop point + from which mail is snarfed (e.g. in tenex, mtx, mbox, mh formats). + + This is not very useful in /etc/c-client.cf because it is a file name. + Setting this in /etc/c-client.cf would set all users to the same file + as their system inbox, which is probably not what you want. + + There is no protection against setting this to a silly value, and + doing so is a great way to cause a crash. + +11) set tcp-open-timeout <number> + Sets the number of seconds that the TCP routines will block on opening + a TCP connection before timing out. If a timeout occurs, the connection + attempt is aborted. + + The default is zero, meaning use the operating system default (75 + seconds on most UNIX systems). + + There is no protection against setting this to an excessively small + value, such as 1, and doing so is a great way to cause users extreme + grief. + +12) set tcp-read-timeout <number> + Sets the number of seconds that the TCP routines will block on reading + data before calling the timeout routine. If no timeout routine is set + by the program, the connection will be aborted on a timeout. + + The default is zero, meaning infinite. + + There is no protection against setting this to an excessively small + value, such as 1, and doing so is a great way to cause users extreme + grief. + +13) set tcp-write-timeout <number> + Sets the number of seconds that the TCP routines will block on sending + data before calling the timeout routine. If no timeout routine is set + by the program, the connection will be aborted on a timeout. + + The default is zero, meaning infinite. + + There is no protection against setting this to an excessively small + value, such as 1, and doing so is a great way to cause users extreme + grief. + +14) set rsh-timeout <number> + Sets the number of seconds that the rsh routines will block on opening + an rimapd connection before timing out. If a timeout occurs, the + rsh connection attempt is aborted. A zero timeout will disable rsh. + + The default is 15 seconds. + + There is no protection against setting this to an excessively small + value, such as 1, and doing so is a great way to cause users extreme + grief. + +15) set maximum-login-trials <number> + Sets the number of iterations of asking the user, via mm_login(), for + a user name and password, before cancelling the attempt. + + The default is 3. + + There is no protection against setting this to zero, and doing so is + a great way to cause users extreme grief. + +16) set lookahead <number> + Sets the number of envelopes that are looked ahead in IMAP, in + mail_fetchstructure(). This is based on the guess that in such + operations as drawing browser lines, if you get data for message n + you are likely to want it for message n+1, n+2,... in short order. + Lookahead preloads the c-client cache and saves unnecessary RTTs. + + The default is 20, a good number for a browser on a 24x80 screen, and + small enough to usually have no significant real-time difference from + a single message fetch. + + Setting it to 0 turns off lookahead. + + There is no protection against setting this ridiculously high and + incurring performance penalties as a result. + +17) set prefetch <number> + Sets the number of envelops which are automatically fetched for the + messages which match in a search. This is based on the guess that + in a browser that is "zoomed" on the results of a search, you are + likely to want the envelope data for each of those messages in + short order. Prefetching reloads the c-client cache, saves + unnecessary RTTs, and avoids loading undesired envelopes due to + lookahead (see above). + + The default is 20. + + Setting it to 0 turns off prefetch. + + There is no protection against setting this ridiculously high and + incurring performance penalties as a result. + +18) set close-on-error <number> + If non-zero, IMAP connections are closed if an EXAMINE or SELECT + command fails. Otherwise, they are left half-open, and can be used + again to select some other mailbox. The mailbox name in the stream + is set to {serverhost}<no_mailbox> + + The default is zero (do not close on error). + +19) set imap-port <number> + Set the TCP/IP contact port to use for IMAP. This overrides the + wired-in setting and the setting from /etc/services, and can in + turn be overridden by an explicit user specification in the mailbox + name, e.g. {serverhost:143}foo + + The default is zero (use setting from /etc/services or the wired-in + setting (143). + + There is no protection against setting this to a silly value, and + doing so is a great way to cause users extreme grief. + +20) set pop3-port <number> + Set the TCP/IP contact port to use for POP3. This overrides the + wired-in setting and the setting from /etc/services, and can in + turn be overridden by an explicit user specification in the mailbox + name, e.g. {serverhost:110/pop3} + + The default is zero (use setting from /etc/services or the wired-in + setting (110). + + There is no protection against setting this to a silly value, and + doing so is a great way to cause users extreme grief. + +21) set uid-lookahead <number> + Sets the number of UIDs that are looked ahead in IMAP in mail_uid(). + Lookahead preloads the c-client cache and saves unnecessary RTTs. + + The default is 1000, small enough to usually have no significant + real-time difference from a single message UID fetch. + + Setting it to 0 turns off lookahead. + + There is no protection against setting this ridiculously high and + incurring performance penalties as a result. + +22) set mailbox-protection <number> + Set the default protection for newly-created mailbox files. + + The default is 384. + + There is no protection against setting this to a silly value, and + doing so is a great way to screw things up massively. + +23) set directory-protection <number> + Set the default protection for newly-created directories. + + The default is 448. + + There is no protection against setting this to a silly value, and + doing so is a great way to screw things up massively. + +24) set lock-protection <number> + Set the default protection for lock files + + The default is 438, which is necessary if locks are to be respected + by processes running as other UIDs. + + There is no protection against setting this to a silly value, and + contrary to what you may think just about any value other than 438 + turns out to be a silly value. + +25) set disable-fcntl-locking <number> + This only applies to SVR4 systems. + + If non-zero, fnctl() locking is not attempted. In the past, this + was used to avoid locking NFS files. If NFS is involved, the evil + lockd/statd daemons get invoked. These daemons supposedly work over + NFS, but really don't. + + You probably don't really want to do this, though, because now the + flock() emulator (which calls fcntl()) now checks to see if the file + is accessed via NFS and no-ops the lock. This is compatible with + BSD. + + Disabling fcntl() locking loses a great deal of locking protection + on local files as well as NFS files (which now never have locking + protection). + + The default is zero (fcntl() locking is enabled). + +26) set lock-EACCES-error <number> + If non-zero, a warning message is given if an attempt to create a + lock file fails. Otherwise, EACCES is treated as a "silent failure", + and it proceeds without trying to use the lock file. This is for + the benefit of users on systems with paranoid /usr/spool/mail + protections which don't let users create /usr/spool/mail/$(USER).lock + files; these unfortunate users would be harassed with a flood of + error messages otherwise. The problem is that on SVR4, if EACCES + remains disabled and fcntl() locking is also disabled, then there is + no locking at all which is doubleplus-ungood. + + If the site is paranoid on /usr/spool/mail protections AND if there + is no fcntl() locking (SVR4) or usable flock() locking (e.g. NFS), + then there is no way to win. Find a different system to use. + + The default is non-zero (report EACCESS as an error). + +27) set list-maximum-level <number> + Sets the maximum depth of recursion that a * wildcard list will go + down the directory tree. 0 means that no recursion is permitted, + and * becomes like %. + + The default is 20. + + There is no protection against setting this to a ridiculously high + value. Since LIST will follow symbolic links, it can effectively + recurse infinitely, until the name strings get large enough that + some name limit is exceeded. + +28) set anonymous-home-directory <directory name> + Sets the location of the anonymous home directory, if it is not in + the standard place. + + It is recommended to use a courtesy symbolic link instead. + + There is no protection against setting this to a silly value, and + doing so is a great way to cause a crash. + +29) set chroot-server <number> + This option is for closed server systems only. If defined, a chroot() + call to the user's home directory is done as part of the login + process. This has the effect of preventing access to any files + outside of the user's home directory (including shared mailboxes). + + Shared mailboxes with other users can't possibly work with this + option, because there is no way to export lock information to other + users. + + This should be done ONLY on systems which do not permit users to + have shell access + + This option should NEVER(!!) be set if users are allowed shell access. + Doing so actually makes the system *less* secure, since the user could + create an etc subdirectory which would be treated as real /etc by such + programs as /bin/su. + + The default is zero (don't do chroot). + + This option is strongly *NOT* recommended. + +30) set disable-automatic-shared-namespaces <number> + Never look up the "ftp", "imappublic", and "imapshared" users as + posssible home directories for the #ftp, #public, and #shared + namespaces. On some systems (reportedly including AIX 4.3.3) + getpwnam() of an unknown user name is horrendously slow. + + Note that this does not remove the #ftp, #public, and #shared + namespaces, and they can still be set up by other means. + + The default is zero (shared namespaces are automatic). + +31) set advertise-the-world <number> + Include the UNIX root as a shared namespace. This is generally a bad + idea, since certain IMAP clients (names withheld to protect the guilty) + will take this as license to download the entire filesystem tree. + + The default is zero (don't advertise the world). + +32) set mail-subdirectory <subdirectory name> + Change the default connected directory from the user's home directory + to the named subdirectory of the user's home directory. For example, + setting MAILSUBDIR="mail" will cause the POP2 and IMAP servers to + connect to the user's ~/mail subdirectory. This is equivalent to + the env_unix.c edit described in Example 2 of the CONFIG file. + + Note that if the subdirectory does not exist, the result is undefined. + It is probably an extremely bad idea to set this unless you can + guarantee that the subdirectory exists for all users. If you can not + guarantee this, then you should leave the default as the user's home + directory and allow them to configure a personal default in their IMAP + client. + + The default is not to use any subdirectory. + +33) set allow-user-config <number> + Allow users to use ~/.imaprc and ~/.mminit files. + + The default is zero (don't allow user config files). + +34) set allow-reverse-dns <number> + By default, the servers (ipop[23]d and imapd) will do gethostbyaddr() + on the local and remote sockets so that imapd can identify itself + properly (this is important when the same CPU hosts multiple virtual + hosts on different IP addresss) and also includes the client's name + when it writes to the syslog. There are also client gethostbyaddr() + calls, used primarily by authentication mechanisms. + + Setting this option to zero disables all gethostbyaddr() calls. The + returned "host name" string for the socket is just the bracketed + [12.34.56.78] form, as if the reverse DNS lookup failed. + + WARNING: Some authentication mechanisms, e.g. Kerberos V, depend upon + the host names being right, and if you set this option, it won't work. + + You should only do this if you are encountering server performance + problems due to a misconfigured DNS, e.g. long startup delays or + client timeouts. + + The default is non-zero (allow reverse DNS). + +35) set disable-plaintext <number> + Disable plaintext password authentication (LOGIN command, AUTH=LOGIN, + and AUTH=PLAIN). + + The default is zero (allow plaintext authentication). + +36) set trust-dns <number> + By default, host names are canonicalized via gethostbyname() for + everything except for SSL certificate validation. + + This can represent a security bug due to DNS spoofing, but is more + likely to deliver results that users expect. It also may be necessary + for SASL authentication to work right (e.g. generating a correct name + for a Kerberos service principal) if the name entered by the user is a + CNAME or not a fully-qualified domain name. + + If trust-dns is set to zero, no host name canonicalization is done. + The user's actual entered name is used for SASL authentication and + will appear in the mailbox name of the open stream. + + The default is non-zero (do DNS canonicalization). + +37) set sasl-uses-ptr-name <number> + By default, if trust-dns is set, the host names used in authentication + (e.g. to generate a Kerberos service principal) are canonicalized via + gethostbyaddr() instead of by gethostbyname(). If gethostbyaddr() + fails the gethostbyname() canonicalization is used. + + This represents an additional security bug due to DNS spoofing, over and + above trust-dns. It also adds an additional DNS query to starting a + session. + + It is necessary for sites which implement a server cluster with multiple + A records for a cluster name (instead of a CNAME) but each cluster + member has a unique PTR record which it expects for a Kerberos service + principal. + + If sasl-uses-ptr-name is set to zero and trust-dns is set non-zero, the + gethostbyname() canonicalized name is used for SASL authentication. + + The setting of sasl-uses-ptr-name is irrelevant if trust-dns is set to + zero. + + The default is non-zero (use name from PTR record for SASL). + +38) set network-filesystem-stat-bug <number> + By default, traditional UNIX mailbox files are only closed and reopened + at checkpoint and expunge time. This ensures that, prior to rewriting + the file, that any cached stat() data from a network filesystem is + updated with current data. + + Very old versions of NFS, and reputedly also AFS, can get into a state + in which the cached stat() data stays out-of-date, even across a + close and reopen of the file. + + If network-filesystem-stat-bug is set non-zero, then the mailbox file + is closed and reopened at ping time as a workaround for this bug in + these network filesystems. This means that in imapd, the mailbox + file is closed and reopened for every IMAP command. This is obviously + something that should be avoided unless absolutely necessary. + + NFS and AFS are terrible ways to distribute mail. You use use IMAP + servers with a local disk instead. + + The default is zero (only close/reopen at checkpoint and expunge time). + + Setting this option is a great way to ruin your system's performance. + +39) set restrict-mailbox-access <option> <option> ... <option> + This option is for closed server systems only. It is less extreme + than chroot-server, and allows selective restriction of what mailbox + named users can use. The existing options are: + root access not permitted to names starting with "/" + otherusers access not permitted to other users' names; this should + normally be used in conjunction with "root", otherwise + another user's names can be accessed via a root name. + all all of the above + Setting any combination of options also disables access to superior + directories via "..". + + This should be done ONLY on systems which do not permit users to + have shell access + + The default is no restrictions. diff --git a/imap/docs/internal.txt b/imap/docs/internal.txt new file mode 100644 index 00000000..203688e8 --- /dev/null +++ b/imap/docs/internal.txt @@ -0,0 +1,2988 @@ +/* ======================================================================== + * Copyright 1988-2006 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 + * + * + * ======================================================================== + */ + + Documentation of c-client Functions and Interfaces + +REVISED: 19 August 1996 + + Credits + + The original version of this document was written by Mark Crispin at +the University of Washington, and described the version of c-client that +supported the IMAP2 (RFC 1176) and IMAP2bis (unpublished) protocols. + + This version is a substantial rewrite of that document, and was +written by Mark Crispin with funding from Sun Microsystems, Incorporated. +Sun's generous support of this work is gratefully acknowledged. + + + Road Map + + This document is organized into the following sections. Except as +noted, an implementor of an application that uses c-client needs to be +familiar with all of these sections. Someone who plans to write a new +mailbox driver for c-client (or otherwise modify it) needs to be familiar +with all sections, no exception. + +History + History of how c-client came about. + +Overview + Read this before designing an application that uses c-client. + +c-client Structures + Documentation of several important c-client structs which are + used in, and returned by, c-client calls. + +String Structures + Documentation of the concept of a "string structure", which + provides random access to strings without requiring that the + string be in memory. + +c-client Support Functions + Documentation of support functions for c-client; these deal + with c-client functionality. + + Only mail_parameters() is of interest to most application + developers. Advanced application developers, particularly + for limited memory systems, may also need to know about the + readfn_t, mailgets_t, mailcache_t, and tcptimeout_t function + pointer types, and possibly also the mail_valid_net_parse() + function. + +Mailbox Access Functions + Documentation of functions which deal with mailboxes; + listing, subscribing, creating, deleting, renaming, status + inquiries, opening, and closing mailboxes. + +Handle Functions + Documentation of mail stream handles, which provide protection + for an advanced application which may have multiple pointers to + a single mail stream. If a stream has a handle on it, closing + the stream does not release its memory, so pointers to it in + the application remain valid. Freeing the last handle will free + the entire stream. + + This is only of interest for advanced application developers. + +Message Data Fetching Functions + Documentation on message data fetching in an open mailbox, + including parsed representations of RFC-822 and MIME headers + and message text. Also how to fetch message attributes (flags, + internal date, sizes). + +Message Status Manipulation Functions + Documentation on altering message flags in an open mailbox. + +Mailbox Searching + Documentation on searching an open mailbox for messages which + match certain criteria (e.g. "messages sent July 4 from Jones + with text `Paris'"). + +Miscellaneous Mailbox and Message Functions + Documentation on other operations that would be used by an + application but that don't fit into any of the above categories. + +Date/Time Handling Functions + Documentation on functions that deal with date/time strings. + + This is only of interest for advanced application developers + and for implementors of new c-client drivers. + +Utility Functions + Documentation on internal utility functions. + + This is primarily of interest for implementors of new c-client + drivers, but advanced application developers may also use some + of these functions. + +Data Structure Instantiation/Destruction functions + Documentation on creating and destroy c-client structures. + + This is primarily of interest for implementors of new c-client + drivers. However, application developers will need some of + these functions to create and destroy structures which are used + as arguments to various application functions. + +Authentication Functions + Documentation on support for network protocol authentication + functions. + + This is only of interest for implementors of new c-client + drivers which deal with authentication mechanisms. + +Network Access Functions + Documentation on creating and destroy c-client structures. + + This is primarily of interest for implementors of new c-client + drivers which deal with a network. However, advanced + application developers may need to use this information if they + wish to insert their own layer into a network session. + +Subscription Management Functions + Documentation on managing the local (client-based) subscription + database file. + + This is primarily of interest to advanced application developers. + +Miscellaneous Utility Functions + Documentation on various useful utility functions, such as "make + a copy of this string." + +SMTP Functions + Documentation on posting email messages via SMTP protocol. + +NNTP Functions + Documentation on posting netnews messages via NNTP protocol. + +RFC 822 Support Functions + Documentation on public RFC-822/MIME functions. + + This is primarily of interest for implementors of new c-client + drivers and advanced application developers. + +Operating System-Dependent Public Interface + Documentation on OS-dependent functions. With the exception of + fs_get(), fs_give(), and fs_resize(), which should be called + instead of malloc(), free(), and realloc(), these functions are + primarily of interest for implementors of new c-client drivers. + +Main Program Callbacks + Documentation of functions which the main program must provide + as callbacks from c-client. + +Driver Interface + Documentation of the driver dispatch vector and the functions + which a driver must supply. + + This is primarily of interest for implementors of new c-client + drivers. + +Driver Support Functions + Documentation of support functions which are called by drivers. + + This is primarily of interest for implementors of new c-client + drivers. + History + + The c-client API was originally written by Mark Crispin at Stanford +University as a set of routines to support IMAP and SMTP from a main +program which would handle the user interface. In its original form, it +was written as the low-level routines that were to be used as part of a +Macintosh client. + + The first IMAP client, MM-D (for "MM on Xerox D machines" -- MM was a +popular DEC-20 mail program) was written in Interlisp for Xerox Lisp +machines. At that time, there was no name for the embryonic Mac client, +but since it was the first one to be written in C instead of Lisp, it was +given a development name of "C client". This name became "c-client" +because that is the name of the subdirectory on UNIX where the source files +were stored. + + To exercise the routines, a minimal main program which uses c-client, +mtest, was written. mtest has subsequently been extended so that it runs +on every platform that c-client is ported. + + The real Mac client, was eventually written by Frank Gilmurrary and +Bill Yeager at Stanford using the autumn 1988 version of c-client and named +"MacMS". In the winter of 1988-89, Mark Crispin, who had changed jobs to +the University of Washington, developed MS as an MM-like text-based program +for UNIX and MailManager as a GUI-based program for NeXT machines. + + The realization sunk in that this API needed its own name. As early +as spring 1989, there were at least four programs (mtest, MS, MailManager, +and MacMS) that used it. The name c-client thus became permanent. + + In its history, c-client has undergone two major redesigns, both by +Mark Crispin who is now on the staff at the University of Washington. + + The first major redesign added the following: + 1) ANSI C calling conventions throughout to assist in function + argument type checking. + 2) Vectoring mail access calls through "driver" methods; thus + providing transparent access to multiple types of mail + stores with the same call. + 3) MIME support. + + The second major redesign was part of the IMAP4 project. Many +c-client functions were extended with additional arguments and options. +The driver interface was also made simpler, with more work done by +driver-independent code. + + Overview + + The most important file for the author of an application using the +c-client is mail.h. mail.h defines several important structures of +data which are passed between the main program and the c-client. +Although some functions (e.g. mail_fetchtext_body()) return the data +fetched, for certain other data items (e.g. flags) you need to get the +data as a structure reference. mail.h also defines a large number of +useful constants and structures. + + When a function in mail.h exists to reference data, it MUST be +used instead of referencing the structures directly. This is because +in some cases the data is not actually fetched until a reference (via +the function call) is made. For example, although the MESSAGECACHE +element for a message can be obtained by indexing the proper cache +element in the stream, there is no guarantee that the item in fact +exists unless mail_fetchstructure_full() is called for that message. +Less costly functions. also exist to create and load a MESSAGECACHE +element. + + The main program will probably also need to include smtp.h, +misc.h, and osdep.h, but this usage should be solely to receive +function prototypes. Any other definitions in those files should be +considered private to that module. + + Two important predefined symbols are NIL and T. NIL is any sort +of "false"; T is any sort of "true". NIL is also used to null-specify +certain optional arguments. + + * * * IMPORTANT * * * + + Any multi-threaded application should test stream->lock prior to +calling any c-client stream functions. Any attempt to call a +mail_xxx() function while one is already in progress on the same +stream will cause the application to fail in unpredictable ways. + + Note that this check is insufficient in a preemptive-scheduling +multi-tasking application due to the possibility of a timing race. +Such applications must be written so that only one process accesses +the stream, or to have a higher level lock. + + Since MAIL operations will not finish until they are completed, a +single-tasking application does not have to worry about this problem, +except in the callback invoked from MAIL (e.g. mm_exists(), etc.) in which +case the stream is *always* locked. + + c-client Structures + + c-client has a large number of structures which are used for +multiple functions. The most important of these are described here. + + The MAILSTREAM structure is used to reference open mailboxes. +Applications may reference the following: + +char *mailbox; mailbox name +unsigned short use; stream use count, this is incremented +unsigned short sequence; stream sequence, this is incremented + each time a stream is reused (i.e. + mail_open() is called to open a + different mailbox on this stream) +unsigned int rdonly : 1; stream is open read-only +unsigned int anonymous : 1; stream is open with anonymous access +unsigned int halfopen : 1; stream is half-open; it can be + reopened or used for functions that + don't need a open mailbox such as + mail_create() but no message data + can be fetched +unsigned int perm_seen : 1; Seen flag can be set permanently +unsigned int perm_deleted : 1; Deleted flag can be set permanently +unsigned int perm_flagged : 1; Flagged flag can be set permanently +unsigned int perm_answered :1; Answered flag can be set permanently +unsigned int perm_draft : 1; Draft flag can be set permanently +unsigned int kwd_create : 1; new user flags can be created by + referencing then in mail_setflag() or + mail_clearflag(). Note: this can + change during a session (e.g. if + there is a limit on the number of + keywords), so check after creating a + new flag to see if any more can be + created before letting the user try + to do so +unsigned long perm_user_flags; corresponding user flags can be set + permanently. This is a bit mask + which matches the entries in + stream->user_flags[] +unsigned long gensym; generated unique value. Always + referenced with stream->gensys++ +unsigned long nmsgs; number of messages in current mailbox +unsigned long recent; number of recent messages in current + mailbox +unsigned long uid_validity; UID validity value; this is used to + verify that recorded UIDs match the + UIDs that the stream has. If the + mailbox does not have matching UIDs + (e.g. the UIDs were lost or not + recorded) then the UID validity value + will be different +unsigned long uid_last; highest currently assigned UID in the + current mailbox; a new UID will be + assigned with ++stream->uid_last +char *user_flags[NUSERFLAGS]; pointers to user flag names in bit + order from stream->perm_user_flags or + elt->user_flags + + The following MAILSTREAM values are only used internally: + +DRIVER *dtb; dispatch table for this driver +void *local; pointer to driver local data +unsigned int lock : 1; stream lock flag (an operation is in + progress; used as a bug trap to + detect recursion back to c-client + from callback routines). +unsigned int debug : 1; debugging information should be logged + via mm_dlog(). +unsigned int silent : 1; don't do main program callbacks on + this stream (used when a stream is + opened internally) +unsigned int scache : 1; short caching; don't cache information + in memory + + The following MAILSTREAM values are only used by the cache +manager routine (see the documentation about mailcache_t above): + +unsigned long cachesize; size of c-client message cache +union { + void **c; to get at the cache in general + MESSAGECACHE **s; message cache array + LONGCACHE **l; long cache array +} cache; + + The following MAILSTREAM values are for the convenience of +drivers that use short caching and want to be able to garbage collect +any values that they returned: + +unsigned long msgno; message number of `current' message +ENVELOPE *env; pointer to `current' message envelope +BODY *body; pointer to `current' message body +char *text; pointer to `current' text + + + The MESSAGECACHE structure (commonly called an "elt" as a +nickname for "cache ELemenT") contains information about messages. +Applications may use the following: + +unsigned long msgno; message number. If the elt is locked + (by elt->lockcount++), then the elt + pointer can be stored (e.g. with the + data for a window which draws this + message) and elt->msgno will change + automatically whenever expunges are + done so the window will always view + the correct message. If elt->msgno + becomes 0, then the message has been + expunged, but the elt won't be freed + until the elt lock count is + decremented (by mail_free_elt()). +unsigned long uid; message unique ID +unsigned int hours: 5; internal date hours (0-23) +unsigned int minutes: 6; internal date minutes (0-59) +unsigned int seconds: 6; internal date seconds (0-59) +unsigned int zoccident : 1; non-zero if internal date time zone is + west of UTC +unsigned int zhours : 4; internal date time zone hours from UTC + (0-12) +unsigned int zminutes: 6; internal date time zone minutes (0-59) +unsigned int seen : 1; message Seen flag +unsigned int deleted : 1; message Deleted flag +unsigned int flagged : 1; message Flagged flag +unsigned int answered : 1; message Answered glag +unsigned int draft : 1; message Draft flag +unsigned int valid : 1; flags are valid in this elt; an elt + that was newly created but never + loaded with flags won't have this set. +unsigned int recent : 1; message recent flag +unsigned int searched : 1; message matches search criteria in + most recent mail_search_full() call +unsigned int spare : 1; reserved for application use +unsigned int spare2 : 1; reserved for application use +unsigned int spare3 : 1; reserved for application use +unsigned int lockcount : 8; non-zero if multiple references to + this elt. Refer to the msgno member + for more information. +unsigned int day : 5; internal date day of month (1-31) +unsigned int month : 4; internal date month of year (1-12) +unsigned int year : 7; internal date year since BASEYEAR + (currently 1970; was 1969 in older + versions so use BASEYEAR instead of + having the base year wired in) +unsigned long user_flags; message user flags; this is a bit mask + which matches the entries in + stream->user_flags[] +unsigned long rfc822_size; size of message in octets + + The following MESSAGECACHE values are only used internally by +drivers: + +unsigned int sequence : 1; message is in sequence from either + mail_sequence() or mail_uid_sequence() +unsigned long data1; first data item +unsigned long data2; second data item +unsigned long data3; third data item +unsigned long data4; fourth data item + + + The ADDRESS structure is a parsed form of a linked list of RFC 822 +addresses. It contains the following information: + +char *personal; personal name phrase +char *adl; at-domain-list (also called "source + route") +char *mailbox; mailbox name +char *host; domain name of mailbox's host +char *error; error in address from smtp_mail(); if + an error is returned from smtp_mail() + for one of the recipient addresses + the SMTP server's error text for that + recipient can be found here. If it + is null then there was no error (or + an error was found with a prior + recipient +ADDRESS *next; pointer to next address in list + + + The ENVELOPE structure is a parsed form of the RFC 822 header. +Its member names correspond to the RFC 822 field names. It contains +the following information: + +char *remail; remail header if any +ADDRESS *return_path; error return address +char *date; message composition date string +ADDRESS *from; from address list +ADDRESS *sender; sender address list +ADDRESS *reply_to; reply address list +char *subject; message subject string +ADDRESS *to; primary recipient list +ADDRESS *cc; secondary recipient list +ADDRESS *bcc; blind secondary recipient list +char *in_reply_to; replied message ID +char *message_id; message ID +char *newsgroups; USENET newsgroups +char *followup_to; USENET reply newsgroups +char *references; USENET references + + + The BODY structure is a parsed form of a linked list of the MIME +structure of a message. It contains the following information. + +unsigned short type; body primary type code. This is an + index into the body_types vector of + body type names. The following body + types are pre-defined: + TYPETEXT unformatted text + TYPEMULTIPART multiple part + TYPEMESSAGE encapsulated message + TYPEAPPLICATION application data + TYPEAUDIO audio + TYPEIMAGE static image (GIF, JPEG, etc.) + TYPEVIDEO video + TYPEOTHER unknown + Additional types up to TYPEMAX are + dynamically defined if they are + encountered by c-client. +unsigned short encoding; body transfer encoding. This is an + index into the body_encodings vector + of body encoding names. The + following body encodings are + pre-defined: + ENC7BIT 7 bit SMTP semantic data + ENC8BIT 8 bit SMTP semantic data + ENCBINARY 8 bit binary data + ENCBASE64 base-64 encoded data + ENCQUOTEDPRINTABLE human-readable 8-as-7 bit data + ENCOTHER unknown + Additional encodings up to ENCMAX are + dynamically defined if they are + encountered by c-client. +char *subtype; body subtype string +PARAMETER *parameter; parameter list +char *id; body content identifier +char *description; body content description +unsigned char *contents.text; when composing a message that is NOT + of TYPEMULTIPART, non-binary text of + the content is stored here. Note that + this happens even when the text is + of TYPEMESSAGE. Text of encoding + ENC8BIT may be converted to + ENCQUOTEDPRINTABLE when it is sent. + This should not be referenced for any + other reason; in particular, this is + NOT the way for an application to + access content data (use + mail_fetchbody_full() instead). +BINARY *contents.binary; when composing a message that is NOT + of TYPEMULTIPART, binary content (of + encoding ENCBINARY) is stored here. + It will be converted to ENCBASE64 when + it is sent. + This should not be referenced for any + other reason; in particular, this is + NOT the way for an application to + access content data (use + mail_fetchbody_full() instead). +PART *contents.part; for body parts of TYPEMULTIPART, this + contains the list of body parts in + this multipart +MESSAGE contents.msg; for body parts of TYPEMESSAGE with + subtype "RFC822", this contains the + encapsulated message +unsigned long size.lines; size in lines +unsigned long size.bytes; size in octets. This MUST be set when + composing a message if the encoding is + ENC8BIT or ENCBINARY. +char *md5; body content MD5 checksum + + The following BODY information is used only by c-client +internally. The use of this data is driver-specific and it can not be +relied-upon by applications. + +unsigned char *contents.text; drivers can store a pointer to the + body contents as text here. +unsigned long size.ibytes; internal size of the body content (prior + to newline conversion, etc.) in octets + + + The MESSAGE structure is a parsed form of a MESSAGE/RFC822 MIME +body part. It contains the following information: + +ENVELOPE *env; encapsulated message RFC 822 header +BODY *body; encapsulated message MIME structure + + The following MESSAGE information is used only by c-client +internally. The use of this data is driver-specific and it can not be +relied-upon by applications. + +char *hdr; encapsulated message header +unsigned long hdrsize; message header size +char *text; message in RFC 822 form +unsigned long offset; offset of text from header + + + The PARAMETER structure is a parsed form of a linked list of +attribute/value pairs. It contains the following information: + +char *attribute; attribute name +char *value; value +PARAMETER *next; next parameter in list + + + The PART structure is a parsed form of a linked list of MIME body +parts. It contains the following information: + +BODY body; body information for this part +PART *next; next body part + + The following PART information is used only by c-client +internally. The use of this data is driver-specific and it can not be +relied-upon by applications. + +unsigned long offset; offset from body origin + + + The NETMBX structure is a parsed form of a network mailbox name: + +char host[NETMAXHOST]; remote host name +char user[NETMAXUSER]; remote user name if specified +char mailbox[NETMAXMBX]; remote mailbox name +char service[NETMAXSRV]; remote service name (IMAP4, NNTP, etc.) +unsigned long port; TCP/IP port number if specified +unsigned int anoflag : 1; anonymous access requested +unsigned int dbgflag : 1; protocol debugging telemetry, via + mm_dlog(), requested + + + The STRINGLIST structure is a list of strings (which may have +embedded NULs) and their lengths: + +char *text; string text +unsigned long size; string length +STRINGLIST *next; next string in list + + String Structures + + A string structure is analogous to a char*, and is used in some +functions as an input argument. It represents a string of data in a +way that does not necessarily require the entire string to be in +memory at once. This is essential for small machines with +highly-restricted memory limits (e.g. DOS). + + String Structure Access + + To use a string structure, the caller needs to know a string +driver and needs to know the driver-dependent data used by that string +structure. A simple string driver is mail_string, a string driver +that takes an in-memory char* string as the driver-dependent data. +The DOS port uses string drivers that take a struct holding a file +descriptor and a file offset. Often the user of a string driver is +the same module that defined it, so usually the programmer knows about +its conventions. + + The following calls are used to access a string structure: + +void INIT (STRING *s,STRINGDRIVER *d,void *data,unsigned long size); + s pointer to the string structure to be initialized + d pointer to the string driver + data pointer to driver-dependent data, from which the + driver can determine string data + size size of the string + This call initializes the string stucture. + + +unsigned long SIZE (STRING *s); + s pointer to the string structure + This call returns the number of characters remaining in the string +after the current string character pointer. + + +char CHR (STRING *s); + s pointer to the string structure + This call returns the character at the current string character +pointer. + + +char SNX (STRING *s); + s pointer to the string structure + This call returns the character at the current string character +pointer, and increments the string character pointer. + + +unsigned long GETPOS (STRING *s); + s pointer to the string structure + This returns the value of the current string character pointer. + + +void SETPOS (STRING *s,unsigned long i); + s pointer to the string structure + i new string pointer value + This method sets the string character pointer to the given value. + + + String Structure Internals + + A string structure holds the following data: + +void *data; used by the string driver as it likes +unsigned long data1; used by the string driver as it likes +unsigned long size; static, holds the total length of the string + from the INIT call +char *chunk; current chunk of in-memory data; this is used + for buffering to avoid unnecessary calls to + the string driver's next method. +unsigned long chunksize; size of an in-memory data chunk +unsigned long offset; position of first character of the chunk in + the overall string +char *curpos; current position; this is what CHR() will + access +unsigned long cursize; number of characters remaining in the current + string +STRINGDRIVER *dtb; the string driver for this string structure + + + A string structure is manipulated by a string driver, which has +the following access methods: + +void (*init) (STRING *s,void *data,unsigned long size); + s pointer to the string structure to be initialized + data pointer to driver-dependent data, from which the + driver can determine string data + size size of the string + This method initializes the string stucture. It can use the data, +data1, and chunksize values as it likes. The remaining values must be +set up as follows: + size static, copied from the size argument + chunk pointer to a buffer loaded with initial data + chunksize size of the buffer + offset 0 + curpos copied from chunk + cursize copied from chunksize + dtb STRINGDRIVER identity pointer + + +char (*next) (STRING *s); + s pointer to the string structure + This method returns the character at the current string character +pointer, and increments the string character pointer. This method +is likely to call the setpos method if the desired character is not in +the current chunk. + + +void (*setpos) (STRING *s,unsigned long i); + s pointer to the string structure + i new string pointer value + This method sets the string character pointer to the given value. If +the pointer is not in the current chunk, then a new chunk is loaded +and the associated values (chunk, offset, curpos, cursize) are +adjusted accordingly. + + c-client Support Functions + + +void mail_string_init (STRING *s,void *data,unsigned long size); +char mail_string_next (STRING *s); +void mail_string_setpos (STRING *s,unsigned long i); + + These three functions are the init, next, and setpos string +structure access methods for the build-in mail_string string driver. +mail_string is a basic string driver for a char* string. See the +documentation below on "String Structures" for more information. + + +void mail_link (DRIVER *driver); + driver pointer to the driver to be added + + This function adds the specified driver to the list of mailbox +drivers. Initially there are no drivers lunk, so all programs which +intend to use c-client need to have at least one call to this function. + + A function which uses IMAP4 would have a statement such as: + mail_link (&imapdriver); /* link in IMAP driver */ +early in the program's initialization. Normally, this is done by the +statement + #include "linkage.c" +which will include the "system standard driver linkage" defined when +c-client was built. By using linkage.c instead of explicit mail_link() +calls, you are guaranteed that you will have a consistant linkage among +all software built on this system. + + +void auth_link (AUTHENTICATOR *auth); + auth pointer to the authenticator to be added + + This function adds the specified authenticator to the list of +authenticators. Initially there are no authenticators lunk. Normally, +this is done by linkage.c so you don't need to call this routine +explicitly. + + +void *mail_parameters (MAILSTREAM *stream,long function,void *value); + stream stream to poll or NIL + function function code + value new value for function codes that change a parameter + + This function fetches or changes the settings of various c-client +operational parameters depending upon the function. If the stream is +specified, only the action for the underlying driver for that stream is +taken; however, the scope of the operational parameters is global so +there is generally no reason for the stream argument ever to be +non-NIL. + + The function codes ENABLE_DRIVER and DISABLE_DRIVER take a driver +pointer as a value. These functions enable and disable mailbox +processing by that driver. By default, all drivers are enabled. + + The remaining function codes are in a pair named GET_xxx to +fetch an operational parameter and SET_xxx to set the parameter: + + GET_DRIVERS / SET_DRIVERS + The list of currently lunk drivers. + + GET_GETS / SET_GETS + If non-NIL, points to a function for reading message text. + Defaults to NIL. + This function is called with three arguments; a function + pointer to a "reading function", a stream for the reading + function, and a size in octets. The reading function is + in turn called with the stream, a size in octets, and a + pointer to a readin buffer. + This function returns with a char* string, which will be + returned by the mail_fetchheader(), mail_fetchtext(), or + mail_fetchbody() function which triggered the message text + reading. + The purpose is to permit reading of large strings, without + requiring an in-memory buffer for the entire string. The idea + is that this function can store the data in some form other + than a char* (e.g. a temporary file) and the main program will + recognize that it should get the text from there instead of + from the results from mail_fetch....(). + This is only supported on DOS and Win16; on other platforms it + is inconsistent whether or not it works. + + GET_CACHE / SET_CACHE + Points to the c-client cache manager function. Defaults to + mm_cache(). + + GET_SMTPVERBOSE / SET_SMTPVERBOSE + If non-NIL, points to a function that accepts a char* string. + This function is called any time the SMTP routines receive a + response code less than 100. The argument is the text of the + response code + + GET_RFC822OUTPUT / SET_RFC822OUTPUT + If non-NIL, points to an alternate rfc822_output() function. + rfc822_output() will call this function and return instead of + doing its normal action. See the description of + rfc822_output() for more information. + + GET_USERNAME / SET_USERNAME + The logged-in user name. + + GET_HOMEDIR / SET_HOMEDIR + The home directory path name. + + GET_LOCALHOST / SET_LOCALHOST + The local host name. + + GET_SYSINBOX / SET_SYSINBOX + The "system INBOX" (where mail is delivered) path name. + + GET_OPENTIMEOUT / SET_OPENTIMEOUT + TCP/IP open timeout in seconds. Defaults to 0 (system + default timeout, usually 75 seconds on Unix). + + GET_READTIMEOUT / SET_READTIMEOUT + TCP/IP read timeout in seconds. Defaults to 0 (no timeout). + + GET_WRITETIMEOUT / SET_WRITETIMEOUT + TCP/IP write timeout in seconds. Defaults to 0 (no timeout). + + GET_CLOSETIMEOUT / SET_CLOSETIMEOUT + TCP/IP close timeout in seconds. Defaults to 0 (no timeout). + + GET_TIMEOUT / SET_TIMEOUT + If non-NIL, points to the function called when a TCP/IP + timeout occurs. This function is called with the number of + seconds since the start of the TCP operation. If it returns + non-zero, the TCP/IP operation is continued; if it returns + non-zero, the TCP/IP connection is aborted. + + GET_RSHTIMEOUT / SET_RSHTIMEOUT + rsh connection timeout in seconds. Defaults to 15 seconds. + + GET_MAXLOGINTRIALS / SET_MAXLOGINTRIALS + The maximum number of login attempts permitted in an IMAP or + POP connection. Defaults to 3. + + GET_LOOKAHEAD / SET_LOOKAHEAD + The number of subsequent envelopes prefetched in IMAP when an + envelope is fetched. Defaults to 20. + + GET_IMAPPORT / SET_IMAPPORT + The IMAP port number. Defaults to 143. + + GET_PREFETCH / SET_PREFETCH + The number of envelopes prefetched in IMAP from the results + of a SEARCH. Defaults to 20. + + GET_CLOSEONERROR / SET_CLOSEONERROR + If non-NIL, close an opening IMAP connection if the SELECT + command fails instead of returning a half-open stream. + Defaults to NIL. + + GET_POP3PORT / SET_POP3PORT + The POP3 port number. Defaults to 110. + + GET_UIDLOOKAHEAD / SET_UIDLOOKAHEAD + The number of UIDs premapped when a message number is + translated to a UID. Defaults to 1000. + + GET_MBXPROTECTION / SET_MBXPROTECTION + Default file protection for newly created mailboxes. + Defaults to 0600. + + GET_DIRPROTECTION / SET_DIRPROTECTION + Default file protection for newly created directories. + Defaults to 0700. + + GET_LOCKPROTECTION / SET_LOCKPROTECTION + Default file protection for locks. Defaults to 0666. + WARNING: don't blithely change this. If other processes + can't get access to a lock then they will have trouble in + locking properly. + + GET_FROMWIDGET / SET_FROMWIDGET + If non-NIL, APPEND in the Unix mbox format will insert a + ">" character in front of all lines which begin with the + string "From ". If NIL, it will only do so if the entire + line looks like a message delimiter (that is, the date is + also in correct format). Defaults to T. + + GET_NEWSACTIVE / SET_NEWSACTIVE + Netnews active file path name. + + GET_NEWSSPOOL / SET_NEWSSPOOL + Netnews spool directory path name. + + GET_NEWSRC / SET_NEWSRC + Netnews newsgroup reading status file (.newsrc) path name. + + GET_EXTENSION / SET_EXTENSION + If non-NIL, points to a string holding the extension for all + mailbox files. This is only supported on DOS and Win16. + + GET_DISABLEFCNTLLOCK / SET_DISABLEFCNTLLOCK + If non-NIL, disables fcntl() locking on SVR4. This is done + if fcntl() tends to hang for no good reason. Now that the + fcntl() code checks for NFS files and no-ops the locking, + this problem usually doesn't happen much any more. Defaults + to NIL. + + GET_LOCKEACCESERROR / SET_LOCKEACCESERROR + If non-NIL, give a warning if an attempt to create a .lock + file gets an EACCES ("Permission denied") error. This usually + means that somebody protected the system inbox directory (e.g. + /var/mail) instead of making it public-write with the sticky + bit. Defaults to non-NIL, since this is usually bad news. + + GET_LISTMAXLEVEL / SET_LISTMAXLEVEL + The maximum depth of recusion that LIST will go on a * + wildcard. Defaults to 20. + + GET_ANONYMOUSHOME / SET_ANONYMOUSHOME + The anonymous use home directory name. + + +typedef long (*readfn_t) (void *stream,unsigned long size,char *buffer); + stream a designator suitable + size a number of octets to read + buffer a buffer of at least size octets for readin + + This function reads the given number of octets into the buffer, +using the given stream. What sort of object the stream is depends upon +the function and its caller, so you must make sure that the readfn is +suitable for the caller's purpose. Common uses include support of the +mailgets function (see below) and of reading from local files on systems +with limited address space. + + +typedef char *(*mailgets_t) (readfn_t f,void *stream,unsigned long size); + f the readfn to use + stream stream argument for the readfn + size total number of octets to read + + This is the argument to the SET_GETS mail_parameter() call. This +function must read size octets from the stream, using the readfn f. It +may call f multiple times to accomplish this; this will read the data in +a serial fashion. So, for example, if size is a megabyte and there is +only 4K of available buffer space, it can call f 256 times to satisfy +the request. There is no way to back up in the reading, so any +processing or saving of the data must be done when it is read. + + The function mm_gets() in mail.c is a sample mailgets function; it +reads the first MAXMESSAGESIZE of data into memory and discards the +rest. + + +typedef void *(*mailcache_t) (MAILSTREAM *stream,unsigned long msgno,long op); + stream stream to cache manage + msgno message to cache manage in the stream + op cache management operation + + This function manages the c-client cache. Normally, a program will +use the default c-client cache manager routine mm_cache(). However, a +main program may want to supply its own cache manager, e.g. it may want +to store the data on a disk file instead of in memory on DOS and Win16 +where memory is tight. + + If you write your own cache manager, you need to examine the +default mm_cache() manager closely, as well as paying close attention to +what goes into an elt (a MESSAGECACHE element). It is highly likely +that if you roll elts out to disk, you will want to set stream->scache +and *NOT* use long elts (because long elts have ENVELOPE and BODY +pointers that you would have to know how to write to disk and read back). + + The cache management functions are one of the following: + + CH_INIT Initialize the entire cache for the stream. This is + called only when creating a new stream or when freeing + it. The msgno argument is ignored. + + CH_SIZE Make sure that the cache is at least large enough to + support msgno. This is a request to grow the cache if + necessary, not shrink it. + + CH_MAKELELT Return a long elt for msgno, creating it if necessary. + This is the underlying support function for mail_lelt(). + + CH_LELT Return the long elt for msgno, or NIL if it does not + already exist. + + CH_MAKEELT Return an elt for msgno, creating it if necessary. + This is the underlying support function for mail_elt(). + + CH_ELT Return the elt for msgno, or NIL if it does not already + exist. + + CH_FREE Free the [l]elt for msgno. + + CH_EXPUNGE Free the [l]elt for msgno, and reclaim its position. + All subsequent elts are renumbered with their elt->msgno + decremented by 1. [Hence msgno+1 becomes msgno, etc.] + This supports message expunging from the cache. + + +typedef long (*tcptimeout_t) (long time); + time total time spent since TCP operation started + + This function is called when a TCP operation times out. It is set +by the SET_TIMEOUT mail_parameter(). The function can return non-zero +to continue the TCP operation (e.g. after outputting a "do you still +want to wait" prompt) or zero if it wants the TCP operation to abort and +close. If the TCP operation aborts, it will likely cause the upper +level IMAP, SMTP, etc. stream to abort and close as well. + + +DRIVER *mail_valid (MAILSTREAM *stream,char *mailbox,char *purpose); + stream if non-NIL, stream to use for validation + mailbox mailbox name to validate + purpose filled in as xxx in "Can't xxx" in error messages + + This function validates the given mailbox name. It successful, it +returns the driver that can open that name if successful, otherwise it +returns NIL. If stream is non-NIL, the mailbox name must be valid for +the type of mailbox associated with that stream (e.g. an NNTP name can +not be used with an IMAP stream). If purpose is non-NIL, an error +message is passed via mm_log() when an error occurs. + + +DRIVER *mail_valid_net (char *name,DRIVER *drv,char *host,char *mailbox); + name mailbox name to validate + drv driver name to validate against + host buffer to return host name if non-NIL + mailbox buffer to return remote mailbox name if non-NIL + + This function is an alternative to mail_valid_net_parse(). It +validates the given mailbox name as a network name and makes sure that +its service name is the same as the driver in drv. If successful, it +returns drv, and copies the host and mailbox strings as needed. +Otherwise it returns NIL. + + +long mail_valid_net_parse (char *name,NETMBX *mb); + name mailbox name to parse + mb pointer to NETMBX structure to return + + This function parses a network mailbox name. If the name is a +network mailbox name, it returns non-NIL, with the NETMBX structure +loaded with the results form the parse. + + Mailbox Access Functions + +void mail_list (MAILSTREAM *stream,char *ref,char *pat); +void mail_scan (MAILSTREAM *stream,char *ref,char *pat,char *contents); + stream if non-NIL, stream to use + ref mailbox reference string + pat mailbox pattern string + contents contents to search + + This function returns a list of mailboxes via the mm_list() +callback. The reference is applied to the pattern in an implementation +dependent fashion, and the resulting string is used to search for +matching mailbox names. "*" is a wildcard which matches zero or more +characters; "%" is a variant which does not descend a hierarchy level. +Read the IMAP specification for more information. + + mail_scan() is a variant which takes a string to search for in the +text of the mailbox. The string is a free-text string, without regard +for message boundaries, and thus the choice of strings must be made +with care. + + +void mail_lsub (MAILSTREAM *stream,char *ref,char *pat); + stream if non-NIL, stream to use + ref mailbox reference string + pat mailbox pattern string + + This function returns a list of subscribed mailboxes via the +mm_lsub() callback. The reference is applied to the pattern in an +implementation dependent fashion, and the resulting string is used to +search for matching mailbox names in the subscription list. "*" is a +wildcard which matches zero or more characters; "%" is a variant which +does not descend a hierarchy level. Read the IMAP specification for +more information. + + +long mail_subscribe (MAILSTREAM *stream,char *mailbox); + stream if non-NIL, stream to use + mailbox mailbox name + + This function adds the given name to the subscription list. It +returns T if successful, NIL if unsuccessful. If unsuccessful, an +error message is returned via the mm_log() callback. + + +long mail_unsubscribe (MAILSTREAM *stream,char *mailbox); + stream if non-NIL, stream to use + mailbox mailbox name + + This function removes the given name from the subscription list. +It returns T if successful, NIL if unsuccessful. If unsuccessful, an +error message is returned via the mm_log() callback. + + +long mail_create (MAILSTREAM *stream,char *mailbox); + stream if non-NIL, stream to use + mailbox mailbox name + + This function creates a mailbox with the given name. It returns T +if successful, NIL if unsuccessful. If unsuccessful, an error message +is returned via the mm_log() callback. + + It is an error to create INBOX or a mailbox name which already +exists. + + +long mail_delete (MAILSTREAM *stream,char *mailbox); + stream if non-NIL, stream to use + mailbox mailbox name + + This function deletes the named mailbox. It returns T if +successful, NIL if unsuccessful. If unsuccessful, an error message is +returned via the mm_log() callback. + + It is an error to delete INBOX or a mailbox name which does not +already exist. + + +long mail_rename (MAILSTREAM *stream,char *old,char *newname); + stream if non-NIL, stream to use + old existing mailbox name + newname new (not yet existing) mailbox name + + This function renames the old mailbox to the new mailbox name. +It returns T if successful, NIL if unsuccessful. If unsuccessful, an +error message is returned via the mm_log() callback. + + It is an error to reanme a mailbox that does not exist, or rename +a mailbox to a name that already exists. It is permitted to rename +INBOX; a new empty INBOX is created in its place. + + +long mail_status (MAILSTREAM *stream,char *mbx,long flags); + stream if non-NIL, stream to use + mbx mailbox name + flags option flags + + This function returns the status of the given mailbox name via the +mm_status() callback. It returns T if successful, NIL if unsuccessful. +If unsuccessful, an error message is returned via the mm_log() +callback. + + The options are a bit mask with one or more of the following, +indicating the data which should be returned. + SA_MESSAGES number of messages in the mailbox + SA_RECENT number of recent messages in the mailbox + SA_UNSEEN number of unseen messages in the mailbox + SA_UIDNEXT next UID value to be assigned + SA_UIDVALIDITY UID validity value + + Note that, depending upon implementation, some of these values may +be more costly to get than others. For example, calculating the +number of unseen messages may require opening the mailbox and scanning +all of the message flags. A mail_status() call should thus be used +with option flags specifying only the data that is actually needed. + + +MAILSTREAM *mail_open (MAILSTREAM *oldstream,char *name,long options); + oldstream if non-NIL, stream to recycle + name mailbox name to open + options option flags. + + This function opens the mailbox and if successful returns a stream +suitable for use by the other MAIL functions. + + If oldstream is non-NIL, an attempt is made to reuse oldstream as +the stream for this mailbox; this is useful when you want to open +another mailbox to the same IMAP or NNTP server without having to open +a new connection. Doing this will close the previously open mailbox. + + The options are a bit mask with one or more of the following: + OP_DEBUG Log IMAP protocol telemetry through mm_debug() + OP_READONLY Open mailbox read-only. + OP_ANONYMOUS Don't use or update a .newsrc file for news. + OP_SHORTCACHE Don't cache envelopes or body structures + OP_SILENT Don't pass mailbox events (internal use only) + OP_PROTOTYPE Return the "prototype stream" for the driver + associated with this mailbox instead of + opening the stream + OP_HALFOPEN For IMAP and NNTP names, open a connection + to the server but don't open a mailbox. + OP_EXPUNGE Silently expunge the oldstream before recycling + + NIL is returned if this function fails for any reason. + + +MAILSTREAM *mail_close (MAILSTREAM *stream); +MAILSTREAM *mail_close_full (MAILSTREAM *stream,long options); + stream stream to close + options option flags + This function closes the MAIL stream and frees all resources +associated with it that it may have created (subject to any handles +existing). + + The options for mail_close_full() are a bit mask with one or more +of the following: + CL_EXPUNGE Silently expunge before closing + + This function always returns NIL, so it can be used as: + stream = mail_close (stream); + + Handle Functions + + Handles are used when an entity that wishes to access the stream +may survive the stream without knowing that it outlived it. For +example, an object reading a message may have a handle to a stream, +but the message selection object that spawned it (and which owns the +stream) may have gone away. A stream can be closed or recycled while +handles are pointing at it, but it is not completely freed until all +handles are gone. A stream may have an arbitrary number of handles. + + +MAILHANDLE *mail_makehandle (MAILSTREAM *stream); + stream stream to make handle to + + This function creates and returns a handle to the stream. + + +void mail_free_handle (MAILHANDLE **handle); + handle pointer to handle to release + + This function frees the handle and notifies the stream that it has +one fewer handle. If this is the last handle on the stream and the +stream has been closed, then the stream is freed. + + +MAILSTREAM *mail_stream (MAILHANDLE *handle); + handle handle to look up + + This function returns the stream associated with the handle if and +only if the stream still represents the same MAIL connection associated +with the handle. Otherwise, NIL is returned (meaning that there is no +active stream associated with this handle). + + Message Data Fetching Functions + +[Note!! There is an important difference between a "sequence" and a + "msgno". A sequence is a string representing one or more messages in + IMAP4-style sequence format ("n", "n:m", or combination of these + delimited by commas), whereas a msgno is an int representing a single + message.] + +void mail_fetchfast (MAILSTREAM *stream,char *sequence); +void mail_fetchfast_full (MAILSTREAM *stream,char *sequence,long flags); + stream stream to fetch on + sequence IMAP-format set of message sequence numbers + flags option flags + + This function causes a cache load of all the "fast" information +(internal date, RFC 822 size, and flags) for the given sequence. Since +all this information is also fetched by mail_fetchstructure(), this +function is generally not used unless the OP_SHORTCACHE option in the +mail_open() call is used. + + The options for mail_fetchfast_full() are a bit mask with one or +more of the following: + FT_UID The sequence argument contains UIDs instead of + sequence numbers + + +void mail_fetchflags (MAILSTREAM *stream,char *sequence); +void mail_fetchflags_full (MAILSTREAM *stream,char *sequence,long flags); + + This function causes a fetch of the flags for the given sequence. +This main reason for using this function is to update the flags in the +local cache in case some other process changed the flags (multiple +simultaneous write access is allowed to the flags) as part of a "check +entire mailbox" (as opposed to "check for new messages") operation. + + The options for mail_fetchflags_full() are a bit mask with one or more +of the following: + FT_UID The sequence argument contains UIDs instead of + sequence numbers + + +ENVELOPE *mail_fetchenvelope (MAILSTREAM *stream,unsigned long msgno); +ENVELOPE *mail_fetchstructure (MAILSTREAM *stream,unsigned long msgno, + BODY **body); +ENVELOPE *mail_fetchstructure_full (MAILSTREAM *stream,unsigned long msgno, + BODY **body,long flags); + stream stream to fetch on + msgno message sequence number + body pointer to where to return BODY structure if non-NIL + flags option flags + This function causes a fetch of all the structured information +(envelope, internal date, RFC 822 size, flags, and body structure) for +the given msgno and, in the case of IMAP, up to MAPLOOKAHEAD (a +parameter in IMAP2.H) subsequent messages which are not yet in the +cache. No fetch is done if the envelope for the given msgno is already +in the cache. The ENVELOPE and the BODY for this msgno is returned. +It is possible for the BODY to be NIL, in which case no information is +available about the structure of the message body. + + The options for mail_fetchstructure_full() are a bit mask with one +or more of the following: + FT_UID The msgno argument is a UID + + This is the primary function for fetching non-text information +about messages, and should be called before any attempt to reference +cache information about this message via mail_elt(). + + +char *mail_fetchheader (MAILSTREAM *stream,unsigned long msgno); +char *mail_fetchheader_full (MAILSTREAM *stream,unsigned long msgno, + STRINGLIST *lines,unsigned long *len,long flags); + stream stream to fetch on + msgno message sequence number + lines list of header lines to fetch + len returned length in octets + flags option flags + + This function causes a fetch of the complete, unfiltered RFC 822 +format header of the specified message as a text string and returns +that text string. + + If the lines argument is non-NIL, it contains a list of header +field names to use in subsetting the header text. Only those lines +which have that header field name are returned, unless FT_NOT is set in +which case only those lines which do not have that header field name +are returned. + + If the len argument is non-NIL, it holds a pointer in which the +length of the string in octets is returned. This is useful in cases +where there may be an embedded null in the string. + + This function always returns a valid string pointer; if no header +exists or if it can not be fetched (e.g. by a deceased IMAP stream) an +empty string is returned. + + The options for mail_fetchheader_full() are a bit mask with one or +more of the following: + FT_UID The msgno argument is a UID + FT_NOT The returned header lines are those that are + not in the lines argument + FT_INTERNAL The return string is in "internal" format, + without any attempt to canonicalize to CRLF + newlines + FT_PREFETCHTEXT The RFC822.TEXT should be pre-fetched at the + same time. This avoids an extra RTT on an + IMAP connection if a full message text is + desired (e.g. in a "save to local file" + operation) + + +char *mail_fetchtext (MAILSTREAM *stream,unsigned long msgno); +char *mail_fetchtext_full (MAILSTREAM *stream,unsigned long msgno, + unsigned long *len,long flags); + stream stream to fetch on + msgno message sequence number + len returned length in octets + flags option flags + + This function causes a fetch of the non-header text of the +specified message as a text string and returns that text string. No +attempt is made to segregate individual body parts. + + If the len argument is non-NIL, it holds a pointer in which the +length of the string in octets is returned. This is useful in cases +where there may be an embedded null in the string. + + This function always returns a valid string pointer; if no header +exists or if it can not be fetched (e.g. by a deceased IMAP stream) an +empty string is returned. + + The options for mail_fetchtext_full() are a bit mask with one or +more of the following: + FT_UID The msgno argument is a UID + FT_PEEK Do not set the \Seen flag if it not already set + FT_INTERNAL The return string is in "internal" format, + without any attempt to canonicalize to CRLF + newlines + + +char *mail_fetchbody (MAILSTREAM *stream,unsigned long msgno,char *sec, + unsigned long *len); +char *mail_fetchbody_full (MAILSTREAM *stream,unsigned long msgno,char *sec, + unsigned long *len,long flags); + stream stream to fetch on + msgno message sequence number + sec section specifier + len returned length in octets + flags option flags + + This function causes a fetch of the particular section of the +body of the specified message as a text string and returns that text +string. The section specification is a string of integers delimited by +period which index into a body part list as per the IMAP4 +specification. Body parts are not decoded by this function; see +rfc822_base64() and rfc822_quotedprintable(). + + If the len argument is non-NIL, it holds a pointer in which the +length of the string in octets is returned. This is useful in cases +where there may be an embedded null in the string. + + This function may return NIL on error. + + The options for mail_fetchbody_full() are a bit mask with one or +more of the following: + FT_UID The msgno argument is a UID + FT_PEEK Do not set the \Seen flag if it not already set + FT_INTERNAL The return string is in "internal" format, + without any attempt to canonicalize to CRLF + newlines + + +unsigned long mail_uid (MAILSTREAM *stream,unsigned long msgno); + stream stream to fetch on + msgno message sequence number + + This function returns the UID for the given message sequence +number. + + +void mail_fetchfrom (char *s,MAILSTREAM *stream,unsigned long msgno, + long length); + s destination string + stream stream to fetch on + msgno message sequence number + length maximum field length + + This function writes a "from" string of the specified length for +the specified message, suitable for display to the user in a menu line, +into the string pointed to by s. + + If the personal name of the first address in the envelope's from +item is non-NIL, it is used; otherwise a string is created by appending +the mailbox of the first address, an "@", and the host of the first +address. The string is trimmed or padded with trailing spaces as +necessary to make its length match the length argument. + + +void mail_fetchsubject (char *s,MAILSTREAM *stream,unsigned long msgno, + long length); + s destination string + stream stream to fetch on + msgno message sequence number + length maximum field length + + This function returns a "subject" string of the specified length +for the specified message, suitable for display to the user in a menu +line. + + The envelope's subject item is copied and trimmed as necessary +to make its length be no more what the caller requested. Unlike +mail_fetchfrom(), this function can return a string of shorter length +than what the caller requested. + + +LONGCACHE *mail_lelt (MAILSTREAM *stream,unsigned long msgno); +MESSAGECACHE *mail_elt (MAILSTREAM *stream,unsigned long msgno); + stream stream to access + msgno message sequence number + + This function returns the cache entry for the specified message. +Although it will create a cache entry if it does not already exist, +that functionality is for internal use only. This function should +never be called without having first called mail_fetchfast() or +mail_fetchstructure() on the message first. + + A cache entry holds the internal date/time, flags, and RFC 822 +size of a message. It holds other data as well, but that is for +internal use only. + + mail_lelt() is a variant that returns a `long' cache entry, which +consists of an cache entry (as a structure, not a pointer), an envelope +pointer, and a body pointer. This is used in conjunction with the elt +lock count functionality, to allow an application to associate the +cached envelope and body of a message with an open window even if the +message is subsequently expunged or if the stream is closed. + + Unless your application wants to look at cached envelopes and +bodies even after the message is expunged or the stream is closed, it +should not use mail_lelt(). Instead, it should use a returned elt from +mail_elt() and use the elt->msgsno as the argument to +mail_fetchstructure(). + + BEWARE: the behavior of mail_lelt() is undefined if the + stream is open with OP_SHORTCACHE. mail_lelt() is extremely + special purpose, and should only be used in sophisticated + special purpose applications after discussing its use with + the c-client author. If you think you need this function, + you are probably mistaken. In almost all cases, you should + use mail_elt() and mail_fetchstructure() instead. + + Message Status Manipulation Functions + +void mail_setflag (MAILSTREAM *stream,char *sequence,char *flag); +void mail_setflag_full (MAILSTREAM *stream,char *sequence,char *flag, + long flags); + stream stream to use + sequence IMAP-format set of message sequence numbers + flag IMAP-format flag string + flags option flags + + This function causes a store to add the specified flag to the flags +set for the messages in the specified sequence. If there is any +problem in setting flags, a message will be passed to the application +via the mm_log() facility. + + The options for mail_setflag_full() are a bit mask with one or +more of the following: + ST_UID The sequence argument contains UIDs instead of + sequence numbers + ST_SILENT Do not update the local cache with the new + value of the flags. This is useful to save + network bandwidth, at the cost of invalidating + the cache. + + +void mail_clearflag (MAILSTREAM *stream,char *sequence,char *flag); +void mail_clearflag_full (MAILSTREAM *stream,char *sequence,char *flag, + long flags); + stream stream to use + sequence IMAP-format set of message sequence numbers + flag IMAP-format flag string + flags option flags + + This function causes a store to delete the specified flag from the +flags set for the messages in the specified sequence. If there is any +problem in clearing flags, a message will be passed to the application +via the mm_log() facility. + + The options for mail_setflag_full() are a bit mask with one or +more of the following: + ST_UID The sequence argument contains UIDs instead of + sequence numbers + ST_SILENT Do not update the local cache with the new + value of the flags. This is useful to save + network bandwidth, at the cost of invalidating + the cache. + + Mailbox Searching + +void mail_search (MAILSTREAM *stream,char *criteria); +void mail_search_full (MAILSTREAM *stream,char *charset,SEARCHPGM *pgm, + long flags); + stream stream to search + charset MIME character set to use when searching strings + pgm search program + flags option flags + + This function causes a mailbox search, using the given MIME +charset (NIL means the default, US-ASCII) and the given search program. +A search program is a structure that holds the following data: + +SEARCHSET *msgno; a set of message sequence numbers +SEARCHSET *uid; a set of unique identifiers +SEARCHOR *or; OR result of two search programs +SEARCHPGMLIST *not; AND result of list of NOT'ed search programs +SEARCHHEADER *header; message headers +STRINGLIST *bcc; string(s) appear in bcc list +STRINGLIST *body; string(s) appear in message body text +STRINGLIST *cc; string(s) appear in cc list +STRINGLIST *from; string(s) appear in from +STRINGLIST *keyword; user flag string(s) set +STRINGLIST *unkeyword; user flag strings() not set +STRINGLIST *subject; string(s) appear in subject +STRINGLIST *text; string(s) appear in message header or body +STRINGLIST *to; string(s) appear in to list +unsigned long larger; larger than this many octets +unsigned long smaller; smaller than this many octes + The following dates are in form: + ((year - BASEYEAR) << 9) + (month << 5) + day +unsigned short sentbefore; + sent before this date +unsigned short senton; sent on this date +unsigned short sentsince; + sent since this date +unsigned short before; received before this date +unsigned short on; received on this date +unsigned short since; received since this date +unsigned int answered : 1; + message answered +unsigned int unanswered : 1; + message not answered +unsigned int deleted : 1; + message deleted +unsigned int undeleted : 1; + message not deleted +unsigned int draft : 1; message is a draft +unsigned int undraft : 1; + message is not a draft +unsigned int flagged : 1; + message flagged as urgent +unsigned int unflagged : 1; + message not flagged as urgent +unsigned int recent : 1; + message recent since last parse of mailbox +unsigned int old : 1; message not recent since last parse of mailbox +unsigned int seen : 1; message read +unsigned int unseen : 1; + message not read + + The following auxillary structures are used by search programs: + SEARCHHEADER: header line searching +char *line; header line field name +char *text; text header line +SEARCHHEADER *next; next SEARCHHEADER in list (AND'ed) + + SEARCHSET: message number set +unsigned long first; first number in set +unsigned long last; if non-zero, last number in set +SEARCHSET *next; next SEARCHSET in list (AND'ed) + + SEARCHOR: two search programs, OR'ed together +SEARCHPGM *first; first program +SEARCHPGM *second; second program +SEARCHOR *next; next SEARCHOR in list + + SEARCHPGMLIST: list of search programs +SEARCHPGM *pgm; search program (AND'd with others in list) +SEARCHPGMLIST *next; next SEARCHPGM in list + + mail_search(), the older interface, accepts a search criteria +argument as a character string in IMAP2 (RFC-1176) format. Do not try +to use any IMAP4 search criteria with this interface. + + The application's mm_searched() function is called for each +message that matches the search criteria. In addition, after the +search is completed, the "fast" information (see mail_fetchfast_full() +and envelopes of the searched messages are fetched (this is called +pre-fetching). + + If there is any problem in searching, a message will be passed to +the application via the mm_log() facility. + + The flags for mail_search_full() are a bit mask with one or more +of the following: + SE_UID Return UIDs instead of sequence numbers + SE_FREE Return the search program to free storage after + finishing + SE_NOPREFETCH Don't prefetch searched messages. + + +unsigned long *mail_sort (MAILSTREAM *stream,char *charset,SEARCHPGM *spg, + SORTPGM *pgm,long flags); + stream stream to sort + charset MIME character set to use when sorting strings + spg search program + pgm sort program + flags option flags + + + This function is a variant of mail_search_full(). It accepts an +additional argument, a sort program, which specifies one or more sort +rules to be applied to the result. If the searching and sorting are +successful, it returns a 0-terminated vector of message sequence +numbers (or UIDs if SE_UID is set). This vector is created out of +free storage, and must be freed with fs_give() when finished with it. + + A sort program is a structure that holds the following data: +unsigned int reverse : 1; + reverse sorting of this key +short function; sort rule, one of the following: + SORTDATE message Date + SORTARRIVAL arrival date + SORTFROM mailbox in first From address + SORTSUBJECT message Subject + SORTTO mailbox in first To address + SORTCC mailbox in first cc address + SORTSIZE size of message in octets +SORTPGM *next; next sort program to be applied if two or more + messages collate identically with this rule + + The flags for mail_search_full() are a bit mask with one or more +of the following: + SE_UID Return UIDs instead of sequence numbers + SE_FREE Return the search program to free storage after + finishing + SE_NOPREFETCH Don't prefetch searched messages. + SO_FREE Return the sort program to free storage after + finishing + + Miscellaneous Mailbox and Message Functions + +long mail_ping (MAILSTREAM *stream); + stream string to ping + + The function pings the stream to see if it is still active. It may +discover new mail; this is the preferred method for a periodic "new mail +check" as well as a "keep alive" for servers which have an inactivity +timeout. It returns T if the stream is still alive, NIL otherwise. + + If new mail is found, the application's mm_exists() function is +called with the newly-determined number of messages in the mailbox. + + +void mail_check (MAILSTREAM *stream); + stream stream to checkpoint + + This function causes a mailstore-defined checkpoint of the +mailbox. This may include such things as a writeback to disk, a check +for flag changes in a shared mailbox, etc. It is not a "check for new +mail"; mail_ping() performs this function (as potentially does any other +function). The status of the check is passed to the application via the +mm_log() facility. + + +void mail_expunge (MAILSTREAM *stream); + stream string to expunge + + This function causes an expunge (permanent removal of messages +which are marked as deleted) of the mailbox. The application's +mm_expunged() function is called for each message that has been +expunged. The application's mm_exists() function is called at the start +and end of the expunge to ensure synchronization. The status of the +expunge is passed to the application via the mm_log() facility. + + Note that the decrementing of msgno's for subsequent messages +happens immediately; for example, if three consequtive messages starting +at msgno 5 are expunged, mm_expunged() will be called with a msgno of 5 +three times. + + +long mail_copy (MAILSTREAM *stream,char *sequence,char *mailbox); +long mail_move (MAILSTREAM *stream,char *sequence,char *mailbox); +long mail_copy_full (MAILSTREAM *stream,char *sequence,char *mailbox, + long options); + stream stream to copy + sequence IMAP-format set of message numbers + mailbox destination mailbox name + options option flags + + This function causes the messages in the specified sequence to be +copied to the specified mailbox. T is returned if the copy is +successful. mail_move() is equivalent to setting CP_MOVE in the options. + + If there is any problem in copying, a message will be passed to +the application via the mm_log() facility and the function returns NIL. +No copying is actually done in this case. + + Note that the mailbox must be on the same host as the stream and +is a mailbox of the type of the source mailbox only. + + The flags for mail_search_full() are a bit mask with one or more +of the following: + CP_UID The sequence argument contains UIDs instead of + sequence numbers + CP_MOVE Delete the messages from the current mailbox + after copying to the destination. + + +long mail_append (MAILSTREAM *stream,char *mailbox,STRING *message); +long mail_append_full (MAILSTREAM *stream,char *mailbox,char *flags,char *date, + STRING *message); + stream stream to use if non-NIL (in the IMAP case) + mailbox destination mailbox name + flags flags to set on message if non-NIL + date internal date (received date) to set on message if non-NIL + message string structure of message to write + + This function writes the message in the string structure to the +destination mailbox, along with the flags and date if specified. This +is useful in those cases where you can't use mail_copy(), e.g. when +copying from one server to another; you can always fetch the message +and then mail_append() it to the destination. It may also be useful +for maintaining an outbox of your outgoing mail. + + +void mail_gc (MAILSTREAM *stream,long gcflags); + stream stream to GC if non-NIL (else GC's all streams) + flags option flags + + This function garbage collects (purges) the cache of entries of +a specific type. Some drivers do not allow purging of particular +cache types, and an attempt to do so is ignored. + + The flags for mail_gc() are a bit mask with one or more of the +following: + GC_ELT message cache elements + GC_ENV ENVELOPEs and BODYs + GC_TEXTS cached texts + + Date/Time Handling Functions + + +char *mail_date (char *string,MESSAGECACHE *elt); + string destination string + elt message cache element containing date + + This function accepts a message cache element that contains date +information, and writes an IMAP-4 date string, that is, one in form: + dd-mmm-yyyy hh:mm:ss +zzzz +based upon the data in the elt. The destination string must be large +enough to hold this string. + + +char *mail_cdate (char *string,MESSAGECACHE *elt); + string destination string + elt message cache element containing date + + This function accepts a message cache element that contains date +information, and writes a ctime() format date string, that is, one in +form: + www mmm dd hh:mm:ss yyyy\n +based upon the data in the elt. The destination string must be large +enough to hold this string. + + +long mail_parse_date (MESSAGECACHE *elt,char *string); + elt message cache element to store parsed date + string source date string + + This function parses the date/time stored in the given string, +in format: + [www,] date [[hh:mm[:ss][-zzz| +zzzz] +where the date can be any of: + mm/dd/yy, mm/dd/yyyy, dd-mmm-yy, dd-mmm-yyyy, dd mmm yy, dd mmm yyyy +and stores the result of the parse in the elt. If the parse is +successful, T is returned, else NIL. + + +unsigned long mail_longdate (MESSAGECACHE *elt); + elt message cache element containing date. + + This function accepts a message cache element that contains date +information, and returns the number of days since the base time of the +imap-4 toolkit. At present, this is the same as the Unix time() value +for that date/time, and hence can be used for functions such as utime(). + + Utility Functions + +void mail_debug (MAILSTREAM *stream); + stream stream to debug + + This function enables telemetry logging for this stream. All +telemetry is passed to the application via the mm_dlog() facility. + + +void mail_nodebug (MAILSTREAM *stream); + stream stream to disable debugging + + This function disables telemetry logging for this stream. + + +long mail_sequence (MAILSTREAM *stream,char *sequence); + stream stream to set the sequence bits + sequence IMAP-format message set string + + This function parses the given sequence string for message +numbers, sets the sequence bit in the stream's message cache element +of all messages in the sequence (and turns it off in all other message +cache elements). If the parse is successful, T is returned, else NIL. + + +long mail_uid_sequence (MAILSTREAM *stream,char *sequence); + stream stream to set the sequence bits + sequence IMAP-format message set string + + This function parses the given sequence string for unique +identifiers, sets the sequence bit in the stream's message cache +element of all messages in the sequence (and turns it off in all other +message cache elements). If the parse is successful, T is returned, +else NIL. + + +long mail_parse_flags (MAILSTREAM *stream,char *flag,unsigned long *uf); + stream stream (used to get user flags) + flag IMAP-format flag string to parse + uf returned location of user flags + + The function parses the given flag string, and returns the system +flags as its return value and the user flags in the location pointed +to by the uf argument. If there is an error in parse, a log message +is issued via mm_log() and this function returns NIL. + + +unsigned long mail_filter (char *text,unsigned long len,STRINGLIST *lines, + long flags); + text RFC 822 text to filter + len length in octets in the text argument + lines string list of header file names to filter + flags option flags + + This function supports the header lines filtering function of +mail_fetchheader_full(). The lines argument contains a list of header +field names to use in subsetting the header text. Only those lines +which have that header field name are returned, unless FT_NOT is set +in which case only those lines which do not have that header field +name are returned. + + The options for mail_filter() are a bit mask with one or more of +the following: + FT_NOT The returned header lines are those that are + not in the lines argument + + +long mail_search_msg (MAILSTREAM *stream,unsigned long msgno,char *charset, + SEARCHPGM *pgm); + stream stream to search + msgno message number of message to inspect + charset character set of search strings + pgm search program to test + + This function implements mail_search_full() locally in cases when +it is not done by a server (e.g. local mail files, NNTP/POP). It +inspects the given message on that stream to see if it matches the +criteria or not. If it matches, T is returned, else NIL. + + +SEARCHPGM *mail_criteria (char *criteria); + criteria IMAP2-format search criteria string + + This function accepts an IMAP2-format search criteria string and +parses it. If the parse is successful, it returns a search program +suitable for use in mail_search_full(). + WARNING: This function does not accept IMAP4 search criteria. + The source string must be writeable (this restriction was also + in the old IMAP2 c-client). + + Data Structure Instantiation/Destruction functions + + These functions are used to obtain structures from free storage and +to release them. + +ENVELOPE *mail_newenvelope (void); +ADDRESS *mail_newaddr (void); +BODY *mail_newbody (void); +BODY *mail_initbody (BODY *body); +PARAMETER *mail_newbody_parameter (void); +PART *mail_newbody_part (void); +STRINGLIST *mail_newstringlist (void); +SEARCHPGM *mail_newsearchpgm (void); +SEARCHHEADER *mail_newsearchheader (char *line); +SEARCHSET *mail_newsearchset (void); +SEARCHOR *mail_newsearchor (void); +SEARCHPGMLIST *mail_newsearchpgmlist (void); +SORTPGM *mail_newsortpgm (void); + + These functions, all named mail_new...(), create a new structure of +the given type and initialize all of its elements to zero or empty. + +void mail_free_body (BODY **body); +void mail_free_body_parameter (PARAMETER **parameter); +void mail_free_body_part (PART **part); +void mail_free_cache (MAILSTREAM *stream); +void mail_free_elt (MESSAGECACHE **elt); +void mail_free_lelt (LONGCACHE **lelt); +void mail_free_envelope (ENVELOPE **env); +void mail_free_address (ADDRESS **address); +void mail_free_stringlist (STRINGLIST **string); +void mail_free_searchpgm (SEARCHPGM **pgm); +void mail_free_searchheader (SEARCHHEADER **hdr); +void mail_free_searchset (SEARCHSET **set); +void mail_free_searchor (SEARCHOR **orl); +void mail_free_searchpgmlist (SEARCHPGMLIST **pgl); +void mail_free_sortpgm (SORTPGM **pgm); + + These functions, all named mail_free_...(), take a pointer to a +structure pointer, free all contained strings and structures within the +structure, and finally free the structure itself and set its pointer to +NIL. For example, mail_free_envelope() frees all the ADDRESS structures +contained in the envelope. + + Normally, mail_free_elt() and mail_free_lelt() are used only if the +main program has a private pointer to cache elements. If so, it is +expected to increment the cache element's lockcount when it makes a +private pointer, and to call this function when it is finished with it. + + Authentication Functions + +char *mail_auth (char *mechanism,authresponse_t resp,int argc,char *argv[]); + mechanism authentication mechanism name + resp callback function for providing responses + argc main() function argc value + argv main() function argv value + + This server function searches the list of authenticators that was +established by auth_link() for an authenticator with the given name. If +an authenticator is found, authentication is initialized. The function +pointed to by resp is called as the authenticator requires responses. + + +AUTHENTICATOR *mail_lookup_auth (unsigned int i); + i position in authenticator list + + This function returns the nth authenticator in the list, where n is +the value of it. + + +unsigned int mail_lookup_auth_name (char *mechanism); + mechanism authentication mechanism name + + This function searches the list of authenticators for an +authenticator with the given name, and returns its position in the +authenticator list. + + + The functions below are provided by c-client client drivers or by +servers to support the protocol-dependent parts of authentication. + +typedef void *(*authchallenge_t) (void *stream,unsigned long *len); + stream stream to read challenge + len pointer to returned length in octets + + This driver function is called by an authenticator to read a +challenge from the given protocol stream in a protocol-dependent way. +It returns that challenge in binary and its length in octets to the +authenticator. + + +typedef long (*authrespond_t) (void *stream,char *s,unsigned long size); + stream stream to send response + s response string + size length of response string in octets + + This driver function is called by an authenticator to send a +challenge response to the given stream in a protocol-dependent way. +It returns T if successful, NIL if failure. + + +typedef char *(*authresponse_t) (void *challenge,unsigned long clen, + unsigned long *rlen); + challenge challenge string + clen length of challenge string in octets + rlen pointer to returned length of response string + + This server function is called with a challenge string of clen +octets. It sends, according to whatever protocol (IMAP, POP, etc.) it +uses, and returns the received response and response length in octets. + + +typedef long (*authclient_t) (authchallenge_t challenger, + authrespond_t responder,NETMBX *mb,void *s, + unsigned long trial); + challenger pointer to protocol-dependent challenge reader function + responder pointer to protocol-dependent response sender function + mb NETMBX struct of the mailbox desired to open + s stream for protocol-dependent routines to use + trial number of authentication attempts remaining + + This client authenticator function negotiates reading challenges +and sending responses for a particular authenticator (Kerberos, etc.) +over the protocol, and returns T if authenticated or NIL if failed. + + +typedef char *(*authserver_t) (authresponse_t responder,int argc,char *argv[]); + responder pointer to protocol-dependent responder function + argc main() function argc value + argv main() function argv value + + This server authenticator function negotiates sending challenges and +reading responses for a particular authenticator (Kerberos, etc.), and +returns either the authenticated user name or NIL if authentication +failed. + + Network Access Functions + + These functions provide a layer of indirection between the TCP +routines and upper level routines. This makes it possible to insert +additional code (e.g. privacy or checksum handling). + +NETSTREAM *net_open (char *host,char *service,unsigned long port); + host host name + service contact service name + port contact port number + + This function opens a TCP connection to the given host and service +or port. + + +NETSTREAM *net_aopen (NETMBX *mb,char *service,char *usrbuf); + NETMBX parsed mailbox specification + service stream to open (at present, only /etc/rimapd is used) + usrbuf buffer to return login user name + + This function attempts to open a preauthenticated connection to the +given mailbox and service. It will return the login user name of the +preauthenticated connection, as well as an open network stream, if +successful. + + +char *net_getline (NETSTREAM *stream); + stream network stream to read + + This routine reads a text line from the stream. It calls +stream->dtb->getline, which normally points to tcp_getline() but can be +set to some other function. + + +long net_getbuffer (void *stream,unsigned long size,char *buffer); + stream network stream to read + size length of data in octets + buffer buffer of at least size octets + + This routine reads data from the stream. It calls +stream->dtb->getbuffer, which normally points to tcp_getbuffer() but can +be set to some other function. + + +long net_soutr (NETSTREAM *stream,char *string); + stream network stream to write + string null-terminated string to output + + This routine writes a null-terminated string to the stream. It +calls stream->dtb->soutr, which normally points to tcp_soutr() but can +be set to some other function. + + +long net_sout (NETSTREAM *stream,char *string,unsigned long size); + stream network stream to write + string string to output + size length of string in octets + + This routine writes a string of length size to the stream. It +calls stream->dtb->sout, which normally points to tcp_sout() but can be +set to some other function. + + +void net_close (NETSTREAM *stream); + stream stream to close + + This routine closes the stream. It calls stream->dtb->close, which +normally points to tcp_close() but can point to some other function. + + +char *net_host (NETSTREAM *stream); + stream stream to inspect + + This routine returns the remote host name of the stream. It calls +stream->dtb->host, which normally points to tcp_host() but can point +to some other function. + + +unsigned long net_port (NETSTREAM *stream); + stream stream to inspect + + This routine returns the remote port number of the stream. It calls +stream->dtb->port, which normally points to tcp_port() but can point +to some other function. + + +char *net_localhost (NETSTREAM *stream); + stream stream to inspect + + This routine returns the local host name of the stream. It calls +stream->dtb->localhost, which normally points to tcp_localhost() but can +point to some other function. + + Subscription Management Functions + +long sm_subscribe (char *mailbox); + mailbox mailbox name to subscribe + + This function adds the given mailbox name to the local subscription +list, and returns T if successful, NIL if failure. + + +long sm_unsubscribe (char *mailbox); + mailbox mailbox name to unsubscribe + + This function removes the given mailbox name from the local +subscription list, and returns T if successful, NIL if failure. + +char *sm_read (void **sdb); + sdb data to use in subsequent calls, or NIL if first call + + This function returns the local subscription list as null +terminated strings. Each call returns the next element in the list. +The first call should be with sdb pointing to a NIL pointer; this will +be filled in for subsequent calls. At the last call, NIL will be +returned. + + Miscellaneous Utility Functions + +char *ucase (char *string); + string string to convert + + This function converts each lowercase character of the specified +string to uppercase and returns the string. + + +char *lcase (char *string); + string string to convert + + This function converts each uppercase character of the specified +string to lowercase and returns the string. + + +char *cpystr (char *string); + string string to copy + + This function makes a copy of the string from free storage and returns +the copy. + + +long find_rightmost_bit (long *valptr); + valptr pointer to value to search + + This function returns -1 if the 32-bit value pointed to by valptr +is non-zero, otherwise it returns the bit number (0 = LSB, 31 = MSB) of +the right-most bit in that value. This is used to convert from the bits +in the cache's userflags item to an index into the stream's userFlags +array of flag texts. + + +long min (long i,long j); + i first argument + j second argument + + This function returns the minimum of the two integers. + +long max (long i,long j); + i first argument + j second argument + + This function returns the maximum of the two integers. + +long search (char *s,long c,char *pat,long patc); + s string to search + c size of string + pat pattern to search in string + patc size of pattern + + This function does a fast case-independent search for the given +pattern in pat (length patc) in base string s, and returns T if the +pattern is found in the string. + + +long pmatch (char *s,char *pat,delim); +long pmatch_full (char *s,char *pat,delim); + s string to match + pat wildcard (* and %) to match in pattern + delim hierarchy delimiter + + This function returns T if the given wildcard pattern matches the +string in s with hierarchy delimiter delim. Otherwise NIL is returned. + + +long dmatch (char *s,char *pat,char delim); + s string to match + pat wildcard (* and %) to match in pattern + delim hierarchy delimiter + + This function returns T if the given wildcard pattern matches the +directory. If not, then none of the elements in the directory are +considered for recursive checking with pmatch_full(). + + SMTP Functions + +SMTPSTREAM *smtp_open (char **hostlist,long debug); + hostlist vector of SMTP server host names to try + debug non-zero if want protocol telemetry debugging + + This function opens an SMTP connection to a one of the hosts in the +host list and if successful returns a stream suitable for use by the +other SMTP functions. The hosts are tried in order until a connection is +successfully opened. If debug is non-NIL, protocol telemetry is logged +via mm_dlog(). NIL is returned if this function fails to open a +connection to any of the hosts in the list. + +void smtp_close (SMTPSTREAM *stream); + stream stream to close + + This function closes the SMTP stream and frees all resources +associated with it that it may have created. + +long smtp_mail (SMTPSTREAM *stream,char *type,ENVELOPE *msg,BODY *body); + stream stream to transmit mail + type mail type (MAIL, SEND, SAML, SOML) + msg message envelope + body message body + + This function negotiates an SMTP transaction of the specified type +(one of "MAIL", "SEND", "SAML", or "SOML") to deliver the specified +message. This function returns T if success or NIL if there is any +failure. The text reason for the failure is in stream->reply item; if +it is associated with a recipient it is also in that address' +address->error item. + + +void smtp_debug (SMTPSTREAM *stream); + stream stream to enable debugging telemetry + + This function enables SMTP protocol telemetry logging for this +stream. All SMTP protocol operations are passed to the application via +the mm_dlog() facility. + + +void smtp_nodebug (SMTPSTREAM *stream); + stream stream to disable debugging telemetry + + This function disables SMTP protocol telemetry logging for this +stream. + + +typedef void (*smtpverbose_t) (char *buffer); + buffer pointer to verbose reply buffer + + This is the argument to the SET_SMTPVERBOSE mail_parmameter() call. +If this function pointer is non-NIL, then if a verbose SMTP response +(with SMTP code less than 100) is received, this function is called with +that response text as its argument. + + NNTP Functions + +NNTPSTREAM *nntp_open (char **hostlist,long debug); + hostlist vector of NNTP server host names to try + debug non-zero if want protocol telemetry debugging + + This function opens an NNTP connection to a one of the hosts in the +host list and if successful returns a stream suitable for use by the +other MTP functions. The hosts are tried in order until a connection is +successfully opened. If debug is non-NIL, protocol telemetry is logged +via mm_dlog(). NIL is returned if this function fails to open a +connection to any of the hosts in the list. + + +void nntp_close (NNTPSTREAM *stream); + stream stream to close + + This function closes the NNTP stream and frees all resources +associated with it that it may have created. + + +long nntp_mail (NNTPSTREAM *stream,ENVELOPE *msg,BODY *body); + stream stream to transmit mail + msg message envelope + body message body + + This function negotiates an NNTP posting transaction to deliver +the specified news message. This function returns T if success or NIL +if there is any failure. The text reason for the failure is in +stream->reply item; if it is associated with a recipient it is also in +that address' address->error item. + + RFC 822 Support Functions + + Although rfc822.c contains several additional functions besides +these, only the functions documented here should be used by +applications. The other functions are for internal use only. + + +void rfc822_header (char *header,ENVELOPE *env,BODY *body); + header buffer to write RFC 822 header + env message ENVELOPE (used to obtain RFC 822 information) + body message BODY (used to obtain MIME information) + + This function writes an RFC 822 format header into header based +on the information in the envelope and body. The header buffer must +be large enough to contain the full text of the resulting header. + + +void rfc822_write_address (char *dest,ADDRESS *adr); + dest buffer to write address list + adr RFC 822 ADDRESS list + + This function writes an RFC 822 format address list into dest +based on the information in adr. The dest buffer must be large enough +to contain the full text of the resulting address list. + +void rfc822_parse_msg (ENVELOPE **en,BODY **bdy,char *s,unsigned long i, + STRING *b,char *host,char *tmp); + en destination pointer where message ENVELOPE will be stored + bdy destination pointer where message BODY will be stored + s RFC 822 header to parse (character string) + i length of RFC 822 header + b stringstruct of message body + host default host name if an address lacks an @host. + temp scratch buffer, must be long enough to hold unwound + header lines (a buffer that is i octets long is OK) + + This function parses the RFC 822 header pointed to by s with body +pointed to by string structure b into the specified destination +envelope and body pointers, using host as the default host name and +tmp as a scratch buffer. New ENVELOPE and BODY structures are +created; when finished with them the application must free them with +mail_free_envelope() and mail_free_body(). Any parsing errors are +noted via the mm_log() mechanism using log type PARSE. + + +void rfc822_parse_adrlist (ADDRESS **lst,char *string,char *host); + lst destination pointer where ADDRESS will be stored + string string of addresses to parse + host default host name if an address lacks an @host. + + This function parses the address list in the given string into an +address list in lst. Any addresses missing a host name are have the +host name defaulted from the host argument. If the destination list +is non-empty it appends the new addresses to the list. Any parsing +errors are noted via the mm_log() mechanism using log type PARSE. + +long rfc822_output (char *t,ENVELOPE *env,BODY *body,soutr_t f,void *s, + long ok8bit); + t scratch buffer, large enough to hold message header + env message ENVELOPE + body message BODY + f I/O function to write to + s stream for I/O function f + ok8bit non-zero if OK to output 8-bit data + + This function writes the message described with the given +envelope and body. Any body part contents of type ENCBINARY is +converted to ENCBASE64 before sending. If ok8bit is NIL, any message +data of type ENC8BIT is converted to ENCQUOTEDPRINTABLE before +sending; if ok8bit is non-NIL then ENC8BIT data is sent as-is. T is +returned if the function succeeds, else NIL is returned. + + The function f is typically net_soutr(), but it can be any +function which matches + typedef long (*soutr_t) (void *stream,char *string); +where stream holds sufficient information to enable the output routine +to know where to output to, and the string is a null-terminated string +to output. This function returns either T or NIL, and that value is +passed up to rfc822_output() for its return. + + +void *rfc822_base64 (char *src,unsigned long srcl,unsigned long *len); + src source string + srcl size of source string in octets + len pointer to where destination string length in octets + will be returned + + This function decodes a BASE64 body part given a source string +and its length. The decoded body part as a sequence of binary octets +is returned, and its length is returned in len. + + +char *rfc822_qprint (char *src,unsigned long srcl,unsigned long *len); + src source string + srcl size of source string in octets + len pointer to where destination string length in octets + will be returned + + This function decodes a QUOTED-PRINTABLE body part given a source +string and its length. The decoded body part as an 8-bit character +string is returned, and its length is returned in len. + + Operating System-Dependent Public Interface + + These functions are in OS-dependent code, and are rewritten each +time c-client is ported to a new operating system. + + +void rfc822_date (char *date); + date buffer to write the date, must be large enough + + This function is called to get the current date and time in an +RFC 822 format string into the given buffer. + + +void *fs_get (size_t size); + size number of octets requested + + This function allocates and returns a block of free storage of +the specified size. Unlike malloc(), there is no failure return; this +function must return with the requested storage. + + +void fs_resize (void **block,size_t size); + block pointer to pointer to block to be resized + size new size in octets + + This function resizes the free storage block, updating the +pointer if necessary. Unlike realloc(), there is no failure return; +this function must return with the requested storage. + + +void fs_give (void **block); + block pointer to pointer to block to free + + This function releases a block of free storage allocated by +fs_get(). It also erases the block pointer, so it isn't necessary to +do this in the application. + + +void fatal (char *string); + string message string + + This function is called when an "impossible" error is detected +and the client wishes to crash. The string should contain a reason. + + +char *strcrlfcpy (char **dst,long *dstl,char *src,long srcl); + dst pointer to destination string pointer + dstl pointer to destination string size + src source strin + srcl source string size + + This function is called to copy into a destination string dst of +size dstl (resized if necessary), a CRLF newline form string from +local format string src of size srcl. + + +TCPSTREAM *tcp_open (char *host,long port); +TCPSTREAM *tcp_aopen (char *host,char *service); +char *tcp_getline (TCPSTREAM *stream); +long tcp_getbuffer (TCPSTREAM *stream,long size,char *buffer); +long tcp_soutr (TCPSTREAM *stream,char *string); +void tcp_close (TCPSTREAM *stream); +char *tcp_host (TCPSTREAM *stream); +unsigned long tcp_port (TCPSTREAM *stream); +char *tcp_localhost (TCPSTREAM *stream); + + These functions are TCP-specific versions of the more general +net_xxx() functions. These should not be called directly by +applications. + + +char *tcp_clienthost (char *dst); + dst destination string buffer + + This function should be called only by a server called by inetd +or similar mechanism which maps standard input to a network socket. +It returns the host name of the other end (e.g. the client of a +server) using the given string buffer, or NIL if it can't get this +information. + + Main Program Callbacks + + All applications which use the c-client must have the following +callbacks to handle events from c-client. Note that in any callback +which involves a mail stream, the stream is locked and you can not +recursively call c-client from the callback. This may also be true in +callbacks which do not have a stream; in general, the rule is "do not +call c-client, especially any mail_xxx() function, from a c-client +callback". + + +void mm_flags (MAILSTREAM *stream,unsigned long number); + stream stream where event happened + number message number + + This function is called when c-client manipulates the flags for +the given message number. This alerts the application that it may +need to inspect that message's flags to see if there are any +interesting changes. + + +void mm_status (MAILSTREAM *stream,char *mailbox,MAILSTATUS *status); + stream stream where event happened + mailbox mailbox name for this status + status MAILSTATUS structure with message status + + This function is called when c-client reports status of a mailbox +(generally as the result of a mail_status() function call). The +returned MAILSTATUS structure has the following members: + +long flags; validity flags. These are the same as + the SA_xxx option flags in the + mail_status() call, and they indicate + which of the other members of the + MAILSTATUS structure have usable data + (i.e. if SA_MESSAGES is not set, do + not believe status->messages!!). +unsigned long messages; number of messages if SA_MESSAGES +unsigned long recent; number of recent messages if SA_RECENT +unsigned long unseen; number of unseen messages if SA_UNSEEN +unsigned long uidnext; next UID to be assigned if SA_UIDNEXT +unsigned long uidvalidity; UID validity value if SA_UIDVALIDITY + + +void mm_searched (MAILSTREAM *stream,unsigned long number); + stream stream where event happened + number message number + + This function is called to notify the main program that this +message number matches a search (generally as the result of a +mail_search_full() function call). + + +void mm_exists (MAILSTREAM *stream,unsigned long number); + stream stream where event happened + number message number + + This function is called to notify the main program that there are +this many messages in the mailbox. It is also used to notify the main +program of new mail, by announcing a higher number than the main +program was previously aware. + + +void mm_expunged (MAILSTREAM *stream,unsigned long number); + stream stream where event happened + number message number + + This function is called to notify the main program that this +message number has been expunged from the mail file and that all +subsequent messages are now referenced by a message number one less +than before. This implicitly decrements the number of messages in the +mailbox. + + +void mm_list (MAILSTREAM *stream,char delim,char *name,long attrib); + stream stream where event happened + delim hierarchy delimiter + name mailbox name + attrib mailbox attributes + + This function is called to notify the main program that this +mailbox name matches a mailbox listing request (generally as the +result of a mail_list() function call). The hierarchy delimiter is a +character that separates out levels of hierarchy in mailbox names. +The attributes are a bit mask with one of the following: + LATT_NOINFERIORS + it is not possible for there to be any + hierarchy inferiors to this name (that is, + this name followed by the hierarchy delimiter + and additional name characters). + LATT_NOSELECT this is not a mailbox name, just a hierarchy + level, and it may not be opened by mail_open() + LATT_MARKED this mailbox may have recent messages + LATT_UNMARKED this mailbox does not have any recent messages + + +void mm_lsub (MAILSTREAM *stream,char delim,char *name,long attrib); + stream stream where event happened + delim hierarchy delimiter + name mailbox name + attrib mailbox attributes + + + This function is called to notify the main program that this +mailbox name matches a subscribed mailbox listing request (generally +as the result of a mail_lsub() function call). The hierarchy +delimiter is a character that separates out levels of hierarchy in +mailbox names. The attributes are a bit mask with one of the +following: + LATT_NOINFERIORS + it is not possible for there to be any + hierarchy inferiors to this name (that is, + this name followed by the hierarchy delimiter + and additional name characters). + LATT_NOSELECT this is not a mailbox name, just a hierarchy + level, and it may not be opened by mail_open() + LATT_MARKED this mailbox may have recent messages + LATT_UNMARKED this mailbox does not have any recent messages + + +void mm_notify (MAILSTREAM *stream,char *string,long errflg); + stream stream where event happened + string message string + errflg message error level + + This function is called to deliver a stream-oriented message +event. This is the mechanism by which any IMAP response codes for any +application (e.g. TRYCREATE) are delivered to the application. +No newline is included in the string, so this function has to output +its own. + + The message error level is one of the following: + + NIL normal operation. The text is `babble' that may be + interesting to the user, e.g. the greeting message + from a server. + + WARN A warning event. This event should be displayed to + the user. Examples: a mailbox rewrite failed because + of disk full, but the previous mailbox contents were + recovered. + + ERROR An error event. This event should be displayed to + the user, or at least logged someplace. This type of + error shouldn't happen, and so should be called to the + attention of support staff. Whatever happened has + probably disrupted the user's work. Examples: an + untagged BAD from an IMAP server. + + +void mm_log (char *string,long errflg); + string message string + errflg message error level + + This function is called to deliver a log message. No newline is +included in the string, so this function has to output its own. In +general, it is intended that these messages are logged someplace, and +possibly shown to the user. + + The message error level is one of the following: + + NIL normal operation. The text is `babble' that may be + interesting to the user, e.g. "Expunged 3 messages". + + PARSE An RFC 822 parsing error. Since bogus headers are + all-too-common in the real world, these can often be + ignored on the "garbage in, garbage out" princple. + However, since surprising results can be yielded when + trying to parse garbage, this message should be logged + somewhere so it can be figured out what happened. + + WARN A warning event. This event should be displayed to + the user. It occurs when an error condition has + happened, but c-client knows what to do to recover. + Examples: "Can't open read-write, so opening + read-only", "Empty mailbox", "Login failed, try + again", "Waiting for mailbox to become unlocked", + "IMAP protocol error". Although a user should be + told about a warning, it's generally not necessary + to interrupt the flow of her work (e.g. it's alright + to display the warning in a scrolling window, but + not necessary to require the user to do anything). + + ERROR An error event. This event should be displayed to + the user, or at least logged someplace. This is a + serious error condition occured that aborted the + requested operation and possibly also aborted the mail + stream. This ranges from normal error conditions such + as "Can't open mailbox", "too many login failures, go + away" to bizarre conditions such as "Apparent new mail + appeared in the mailbox that doesn't look like mail, + program aborting". Errors must be called to the + user's attention, and probably should require some + sort of acknowledgement (e.g. answering a modal panel) + before the application proceeds. + + +void mm_dlog (char *string); + string message string + + This function is called to deliver a debugging telemetry +message. No newline is included in the string, so this function has +to output its own. This is called only when debugging is enabled. + + +void mm_login (NETMBX *mb,char *user,char *pwd,long trial); + mb parsed mailbox specification + user pointer to where to return user name + pwd pointer to where to return password + trial number of prior login attempts + + This function is called to get a user name and password for the +given network mailbox. It stores the user name and password in the +strings pointed to by the appropriate arguments. The trial argument +is the number of attempts to perform the login and is initially zero +(e.g. for a default username and password login functionality). It is +incremented for each subsequent trial until the maximum number of +trials are made. + + +void mm_critical (MAILSTREAM *stream); + stream stream where event happened + + This function is called to alert the application that c-client +is about to run some critical code on that stream that may result in a +clobbered mail file if it is interrupted. It may be desirable to +disable CTRL/C, etc. during this time. + + +void mm_nocritical (MAILSTREAM *stream); + stream stream where event happened + + This function is called to alert the application that c-client +is no longer running critical code on that stream that may result in a +clobbered mail file if it is interrupted. + + +long mm_diskerror (MAILSTREAM *stream,long errcode,long serious); + stream stream where event happened + errcode OS error code for disk error + serious non-zero if c-client can not undo the operation (and + thus must retry to avoid mail file damage) + + This function is called to alert the application that the +c-client has encountered an unrecoverable write error when trying to +update the mail file. errcode contains the system error code. If +serious is non-zero, then it is probable that the disk copy of the +mailbox has been damaged. + + The return value from this function is the abort flag; if serious +is zero and the abort flag is non-zero, the operation is aborted. If +the abort flag is zero or if serious was non-zero, a return from this +function will retry the failing operation. + + +void mm_fatal (char *string); + string message string + + This function is called from the fatal() routine in the +operating system code to notify the main program that it is about to +crash. The string contains a reason. At the very minimum, the main +program should do something like + mm_log (string,ERROR); +and then return. No newline is included in the string, so this +function has to output its own. + + Driver interface + + When writing a new driver for the c-client, you must provide a +DRIVER stucture giving a dispatch vector between MAIL and the driver. +The DRIVER dispatch vector is described in mail.h. + +char *name; + Name by which the driver is known to c-client. + +unsigned long flags; + Attribute flags for this driver: + DR_DISABLE This driver is currently disabled. + DR_LOCAL This driver deals with local mailboxes; if + this is off it deals with mailboxes over a + network. + DR_MAIL This driver supports e-mail messages. + DR_NEWS This driver supports netnews messages + DR_READONLY This driver only allows read-only access; + mail_setflag(), mail_expunge(), etc. are + no-ops. + DR_NOFAST This driver does not implement mail_fetchfast() + in a fast way (e.g. it may have to fetch the + entire message text over a network to + calculate sizes). + DR_NAMESPACE This driver accepts and uses namespace format + names. + DR_LOWMEM This driver is designed for systems with very + limited amounts of memory (e.g. DOS) and + support routines called by this driver should + try not to use much memory. + +DRIVER *next; + Pointer to the next driver which this application supports (or NIL if +this is the last driver). Drivers are lunk together via the mail_link() +function. + +DRIVER *driver_valid (char *mailbox); + This function returns a pointer to the driver's DRIVER dispatch +vector iff this driver accepts the given name as a valid mailbox for this +driver. Otherwise, it returns the value of the next driver's +driver_valid() or NIL if there is no next driver. In other words, calling +driver_valid() for the first driver will return the driver dispatch vector +for the driver which supports this type of mailbox. + +void *driver_parameters (long function,void *value); + This function implements mail_parameters() for this driver. + +void driver_scan (MAILSTREAM *stream,char *ref,char *pat,char *contents); + This function implements mail_scan() for this driver. + +void driver_list (MAILSTREAM *stream,char *ref,char *pat); + This function implements mail_list() for this driver. + +void driver_lsub (MAILSTREAM *stream,char *ref,char *pat); + This function implements mail_lsub() for this driver. + +long driver_subscribe (MAILSTREAM *stream,char *mailbox); + This function implements mail_subscribe() for this driver. + +long driver_unsubscribe (MAILSTREAM *stream,char *mailbox); + This function implements mail_unsubscribe() for this driver. + +long driver_create (MAILSTREAM *stream,char *mailbox); + This function implements mail_create() for this driver. + +long driver_delete (MAILSTREAM *stream,char *mailbox); + This function implements mail_delete() for this driver. + +long driver_rename (MAILSTREAM *stream,char *old,char *new); + This function implements mail_rename() for this driver. + +long driver_status (MAILSTREAM *stream,char *mailbox,long flags); + This function implements mail_status() for this driver. + +MAILSTREAM *driver_open (MAILSTREAM *stream); + This function opens the mailbox identified by the given stream. It +may use the data on the stream and create additional data on stream->local +as necessary. It should return the given stream unless it failed to open +the mailbox, in which case it should return NIL. + +void driver_close (MAILSTREAM *stream,long options); + This function implements mail_close() for this driver. + +void driver_fetchfast (MAILSTREAM *stream,char *sequence,long flags); + This function implements mail_fetchfast() for this driver. + +void driver_fetchflags (MAILSTREAM *stream,char *sequence,long flags); + This function implements mail_fetchflags() for this driver. + +ENVELOPE *driver_fetchstructure (MAILSTREAM *stream,unsigned long msgno, + BODY **body,long flags); + This function implements mail_fetchstructure() for this driver. + +char *driver_fetchheader (MAILSTREAM *stream,unsigned long msgno, + STRINGLIST *lines,unsigned long *len,long flags); + This function implements mail_fetchheader() for this driver. + +char *driver_fetchtext (MAILSTREAM *stream,unsigned long msgno, + unsigned long *len,long flags); + This function implements mail_fetchtext() for this driver. + +char *driver_fetchbody (MAILSTREAM *stream,unsigned long msgno,char *section, + unsigned long *len,long flags); + This function implements mail_fetchbody() for this driver. + +void driver_setflag (MAILSTREAM *stream,char *sequence,char *flag,long flags); + This function implements mail_setflag() for this driver. + +void driver_clearflag (MAILSTREAM *stream,char *sequence,char *flag, + long flags); + This function implements mail_clearflag() for this driver. + +void driver_search (MAILSTREAM *stream,char *charset,SEARCHPGM *pgm, + long flags); + This function implements mail_search() for this driver. + +unsigned long *driver_sort (MAILSTREAM *stream,char *charset,SEARCHPGM *spg, + SORTPGM *pgm,long flags); + This function implements mail_sort() for this driver. + +void *driver_thread (MAILSTREAM *stream,char *seq,long function,long flag); + This dispatch is reserved for a future threading capability. + +long driver_ping (MAILSTREAM *stream); + This function implements mail_ping() for this driver. + +void driver_check (MAILSTREAM *stream); + This function implements mail_check() for this driver. + +void driver_expunge (MAILSTREAM *stream); + This function implements mail_expunge() for this driver. + +long driver_copy (MAILSTREAM *stream,char *sequence,char *mailbox, + long options); + This function implements mail_copy() for this driver. + +long driver_append (MAILSTREAM *stream,char *mailbox,char *flags,char *date, + STRING *message); + This function implements mail_append() for this driver. + +void driver_gc (MAILSTREAM *stream,long gcflags); + This function implements mail_gc() for this driver. + + Driver Support Functions + +void mail_searched (MAILSTREAM *stream,unsigned long msgno); + stream stream where event happened + msgno message number + + This function is called by the driver to notify c-client that this +message number matches a search. It invokes the main program's +mm_searched() function. + +void mail_exists (MAILSTREAM *stream,unsigned long nmsgs); + stream stream where event happened + nmsgs number of messages + + This function is called by the driver to notify c-client that this +message number exists (i.e. there are this many messages in the mailbox). +It invokes the main program's mm_exists() function. + +void mail_recent (MAILSTREAM *stream,unsigned long recent); + stream stream where event happened + recent number of messages + + This function is called by the driver to notify c-client that this +many messages are "recent" (i.e. arrived in the mailbox since the previous +time the mailbox was opened). + +void mail_expunged (MAILSTREAM *stream,unsigned long msgno); + stream stream where event happened + msgno number of messages + + This function is called by the driver to notify MAIL that this +message number has been expunged from the mail file and that all subsequent +messages are now referenced by a message number one less than before. It +invokes the main program's mm_expunged() function. + +void mail_lock (MAILSTREAM *stream); + stream stream where event happened + This function sets the stream lock. It is an error to set the stream +lock if the stream is already locked. + + This is mainly used to catch errors due to a callback function +(e.g. mm_exists) inadvertantly recursing back to the MAIL routines and +establishing an infinite recursion. Normally, drivers will set the lock +prior to calling one of the callback functions above or, more likely, in +the beginning of the driver's non-reentrant "do operation" section. In the +IMAP4 driver, the stream lock is set when entering imap_send() and cleared +on exit. + +void mail_unlock (MAILSTREAM *stream); + stream stream where event happened + + This function releases the stream lock. It is an error to release the +stream lock if the stream is not locked. diff --git a/imap/docs/locking.txt b/imap/docs/locking.txt new file mode 100644 index 00000000..32ff6c66 --- /dev/null +++ b/imap/docs/locking.txt @@ -0,0 +1,417 @@ +/* ======================================================================== + * Copyright 1988-2006 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 + * + * + * ======================================================================== + */ + + UNIX Advisory File Locking Implications on c-client + Mark Crispin, 28 November 1995 + + + THIS DOCUMENT HAS BEEN UPDATED TO REFLECT THE FACT THAT + LINUX SUPPORTS BOTH flock() AND fcntl() AND THAT OSF/1 + HAS BEEN BROKEN SO THAT IT ONLY SUPPORTS fcntl(). + -- JUNE 15, 2004 + + THIS DOCUMENT HAS BEEN UPDATED TO REFLECT THE CODE IN THE + IMAP-4 TOOLKIT AS OF NOVEMBER 28, 1995. SOME STATEMENTS + IN THIS DOCUMENT DO NOT APPLY TO EARLIER VERSIONS OF THE + IMAP TOOLKIT. + +INTRODUCTION + + Advisory locking is a mechanism by which cooperating processes +can signal to each other their usage of a resource and whether or not +that usage is critical. It is not a mechanism to protect against +processes which do not cooperate in the locking. + + The most basic form of locking involves a counter. This counter +is -1 when the resource is available. If a process wants the lock, it +executes an atomic increment-and-test-if-zero. If the value is zero, +the process has the lock and can execute the critical code that needs +exclusive usage of a resource. When it is finished, it sets the lock +back to -1. In C terms: + + while (++lock) /* try to get lock */ + invoke_other_threads (); /* failed, try again */ + . + . /* critical code here */ + . + lock = -1; /* release lock */ + + This particular form of locking appears most commonly in +multi-threaded applications such as operating system kernels. It +makes several presumptions: + (1) it is alright to keep testing the lock (no overflow) + (2) the critical resource is single-access only + (3) there is shared writeable memory between the two threads + (4) the threads can be trusted to release the lock when finished + + In applications programming on multi-user systems, most commonly +the other threads are in an entirely different process, which may even +be logged in as a different user. Few operating systems offer shared +writeable memory between such processes. + + A means of communicating this is by use of a file with a mutually +agreed upon name. A binary semaphore can be passed by means of the +existance or non-existance of that file, provided that there is an +atomic means to create a file if and only if that file does not exist. +In C terms: + + /* try to get lock */ + while ((fd = open ("lockfile",O_WRONLY|O_CREAT|O_EXCL,0666)) < 0) + sleep (1); /* failed, try again */ + close (fd); /* got the lock */ + . + . /* critical code here */ + . + unlink ("lockfile"); /* release lock */ + + This form of locking makes fewer presumptions, but it still is +guilty of presumptions (2) and (4) above. Presumption (2) limits the +ability to have processes sharing a resource in a non-conflicting +fashion (e.g. reading from a file). Presumption (4) leads to +deadlocks should the process crash while it has a resource locked. + + Most modern operating systems provide a resource locking system +call that has none of these presumptions. In particular, a mechanism +is provided for identifying shared locks as opposed to exclusive +locks. A shared lock permits other processes to obtain a shared lock, +but denies exclusive locks. In other words: + + current state want shared want exclusive + ------------- ----------- -------------- + unlocked YES YES + locked shared YES NO + locked exclusive NO NO + + Furthermore, the operating system automatically relinquishes all +locks held by that process when it terminates. + + A useful operation is the ability to upgrade a shared lock to +exclusive (provided there are no other shared users of the lock) and +to downgrade an exclusive lock to shared. It is important that at no +time is the lock ever removed; a process upgrading to exclusive must +not relenquish its shared lock. + + Most commonly, the resources being locked are files. Shared +locks are particularly important with files; multiple simultaneous +processes can read from a file, but only one can safely write at a +time. Some writes may be safer than others; an append to the end of +the file is safer than changing existing file data. In turn, changing +a file record in place is safer than rewriting the file with an +entirely different structure. + + +FILE LOCKING ON UNIX + + In the oldest versions of UNIX, the use of a semaphore lockfile +was the only available form of locking. Advisory locking system calls +were not added to UNIX until after the BSD vs. System V split. Both +of these system calls deal with file resources only. + + Most systems only have one or the other form of locking. AIX +and newer versions of OSF/1 emulate the BSD form of locking as a jacket +into the System V form. Ultrix and Linux implement both forms. + +BSD + + BSD added the flock() system call. It offers capabilities to +acquire shared lock, acquire exclusive lock, and unlock. Optionally, +the process can request an immediate error return instead of blocking +when the lock is unavailable. + + +FLOCK() BUGS + + flock() advertises that it permits upgrading of shared locks to +exclusive and downgrading of exclusive locks to shared, but it does so +by releasing the former lock and then trying to acquire the new lock. +This creates a window of vulnerability in which another process can +grab the exclusive lock. Therefore, this capability is not useful, +although many programmers have been deluded by incautious reading of +the flock() man page to believe otherwise. This problem can be +programmed around, once the programmer is aware of it. + + flock() always returns as if it succeeded on NFS files, when in +fact it is a no-op. There is no way around this. + + Leaving aside these two problems, flock() works remarkably well, +and has shown itself to be robust and trustworthy. + +SYSTEM V/POSIX + + System V added new functions to the fnctl() system call, and a +simple interface through the lockf() subroutine. This was +subsequently included in POSIX. Both offer the facility to apply the +lock to a particular region of the file instead of to the entire file. +lockf() only supports exclusive locks, and calls fcntl() internally; +hence it won't be discussed further. + + Functionally, fcntl() locking is a superset of flock(); it is +possible to implement a flock() emulator using fcntl(), with one minor +exception: it is not possible to acquire an exclusive lock if the file +is not open for write. + + The fcntl() locking functions are: query lock station of a file +region, lock/unlock a region, and lock/unlock a region and block until +have the lock. The locks may be shared or exclusive. By means of the +statd and lockd daemons, fcntl() locking is available on NFS files. + + When statd is started at system boot, it reads its /etc/state +file (which contains the number of times it has been invoked) and +/etc/sm directory (which contains a list of all remote sites which are +client or server locking with this site), and notifies the statd on +each of these systems that it has been restarted. Each statd then +notifies the local lockd of the restart of that system. + + lockd receives fcntl() requests for NFS files. It communicates +with the lockd at the server and requests it to apply the lock, and +with the statd to request it for notification when the server goes +down. It blocks until all these requests are completed. + + There is quite a mythos about fcntl() locking. + + One religion holds that fcntl() locking is the best thing since +sliced bread, and that programs which use flock() should be converted +to fcntl() so that NFS locking will work. However, as noted above, +very few systems support both calls, so such an exercise is pointless +except on Ultrix and Linux. + + Another religion, which I adhere to, has the opposite viewpoint. + + +FCNTL() BUGS + + For all of the hairy code to do individual section locking of a +file, it's clear that the designers of fcntl() locking never +considered some very basic locking operations. It's as if all they +knew about locking they got out of some CS textbook with not +investigation of real-world needs. + + It is not possible to acquire an exclusive lock unless the file +is open for write. You could have append with shared read, and thus +you could have a case in which a read-only access may need to go +exclusive. This problem can be programmed around once the programmer +is aware of it. + + If the file is opened on another file designator in the same +process, the file is unlocked even if no attempt is made to do any +form of locking on the second designator. This is a very bad bug. It +means that an application must keep track of all the files that it has +opened and locked. + + If there is no statd/lockd on the NFS server, fcntl() will hang +forever waiting for them to appear. This is a bad bug. It means that +any attempt to lock on a server that doesn't run these daemons will +hang. There is no way for an application to request flock() style +``try to lock, but no-op if the mechanism ain't there''. + + There is a rumor to the effect that fcntl() will hang forever on +local files too if there is no local statd/lockd. These daemons are +running on mailer.u, although they appear not to have much CPU time. +A useful experiment would be to kill them and see if imapd is affected +in any way, but I decline to do so without an OK from UCS! ;-) If +killing statd/lockd can be done without breaking fcntl() on local +files, this would become one of the primary means of dealing with this +problem. + + The statd and lockd daemons have quite a reputation for extreme +fragility. There have been numerous reports about the locking +mechanism being wedged on a systemwide or even clusterwide basis, +requiring a reboot to clear. It is rumored that this wedge, once it +happens, also blocks local locking. Presumably killing and restarting +statd would suffice to clear the wedge, but I haven't verified this. + + There appears to be a limit to how many locks may be in use at a +time on the system, although the documentation only mentions it in +passing. On some of their systems, UCS has increased lockd's ``size +of the socket buffer'', whatever that means. + +C-CLIENT USAGE + + c-client uses flock(). On System V systems, flock() is simulated +by an emulator that calls fcntl(). + + +BEZERK AND MMDF + + Locking in the traditional UNIX formats was largely dictated by +the status quo in other applications; however, additional protection +is added against inadvertantly running multiple instances of a +c-client application on the same mail file. + + (1) c-client attempts to create a .lock file (mail file name with +``.lock'' appended) whenever it reads from, or writes to, the mail +file. This is an exclusive lock, and is held only for short periods +of time while c-client is actually doing the I/O. There is a 5-minute +timeout for this lock, after which it is broken on the presumption +that it is a stale lock. If it can not create the .lock file due to +an EACCES (protection failure) error, it once silently proceeded +without this lock; this was for systems which protect /usr/spool/mail +from unprivileged processes creating files. Today, c-client reports +an error unless it is built otherwise. The purpose of this lock is to +prevent against unfavorable interactions with mail delivery. + + (2) c-client applies a shared flock() to the mail file whenever +it reads from the mail file, and an exclusive flock() whenever it +writes to the mail file. This lock is freed as soon as it finishes +reading. The purpose of this lock is to prevent against unfavorable +interactions with mail delivery. + + (3) c-client applies an exclusive flock() to a file on /tmp +(whose name represents the device and inode number of the file) when +it opens the mail file. This lock is maintained throughout the +session, although c-client has a feature (called ``kiss of death'') +which permits c-client to forcibly and irreversibly seize the lock +from a cooperating c-client application that surrenders the lock on +demand. The purpose of this lock is to prevent against unfavorable +interactions with other instances of c-client (rewriting the mail +file). + + Mail delivery daemons use lock (1), (2), or both. Lock (1) works +over NFS; lock (2) is the only one that works on sites that protect +/usr/spool/mail against unprivileged file creation. Prudent mail +delivery daemons use both forms of locking, and of course so does +c-client. + + If only lock (2) is used, then multiple processes can read from +the mail file simultaneously, although in real life this doesn't +really change things. The normal state of locks (1) and (2) is +unlocked except for very brief periods. + + +TENEX AND MTX + + The design of the locking mechanism of these formats was +motivated by a design to enable multiple simultaneous read/write +access. It is almost the reverse of how locking works with +bezerk/mmdf. + + (1) c-client applies a shared flock() to the mail file when it +opens the mail file. It upgrades this lock to exclusive whenever it +tries to expunge the mail file. Because of the flock() bug that +upgrading a lock actually releases it, it will not do so until it has +acquired an exclusive lock (2) first. The purpose of this lock is to +prevent against expunge taking place while some other c-client has the +mail file open (and thus knows where all the messages are). + + (2) c-client applies a shared flock() to a file on /tmp (whose +name represents the device and inode number of the file) when it +parses the mail file. It applies an exclusive flock() to this file +when it appends new mail to the mail file, as well as before it +attempts to upgrade lock (1) to exclusive. The purpose of this lock +is to prevent against data being appended while some other c-client is +parsing mail in the file (to prevent reading of incomplete messages). +It also protects against the lock-releasing timing race on lock (1). + +OBSERVATIONS + + In a perfect world, locking works. You are protected against +unfavorable interactions with the mailer and against your own mistake +by running more than one instance of your mail reader. In tenex/mtx +formats, you have the additional benefit that multiple simultaneous +read/write access works, with the sole restriction being that you +can't expunge if there are any sharers of the mail file. + + If the mail file is NFS-mounted, then flock() locking is a silent +no-op. This is the way BSD implements flock(), and c-client's +emulation of flock() through fcntl() tests for NFS files and +duplicates this functionality. There is no locking protection for +tenex/mtx mail files at all, and only protection against the mailer +for bezerk/mmdf mail files. This has been the accepted state of +affairs on UNIX for many sad years. + + If you can not create .lock files, it should not affect locking, +since the flock() locks suffice for all protection. This is, however, +not true if the mailer does not check for flock() locking, or if the +the mail file is NFS-mounted. + + What this means is that there is *no* locking protection at all +in the case of a client using an NFS-mounted /usr/spool/mail that does +not permit file creation by unprivileged programs. It is impossible, +under these circumstances, for an unprivileged program to do anything +about it. Worse, if EACCES errors on .lock file creation are no-op'ed +, the user won't even know about it. This is arguably a site +configuration error. + + The problem with not being able to create .lock files exists on +System V as well, but the failure modes for flock() -- which is +implemented via fcntl() -- are different. + + On System V, if the mail file is NFS-mounted and either the +client or the server lacks a functioning statd/lockd pair, then the +lock attempt would have hung forever if it weren't for the fact that +c-client tests for NFS and no-ops the flock() emulator in this case. +Systemwide or clusterwide failures of statd/lockd have been known to +occur which cause all locks in all processes to hang (including +local?). Without the special NFS test made by c-client, there would +be no way to request BSD-style no-op behavior, nor is there any way to +determine that this is happening other than the system being hung. + + The additional locking introduced by c-client was shown to cause +much more stress on the System V locking mechanism than has +traditionally been placed upon it. If it was stressed too far, all +hell broke loose. Fortunately, this is now past history. + +TRADEOFFS + + c-client based applications have a reasonable chance of winning +as long as you don't use NFS for remote access to mail files. That's +what IMAP is for, after all. It is, however, very important to +realize that you can *not* use the lock-upgrade feature by itself +because it releases the lock as an interim step -- you need to have +lock-upgrading guarded by another lock. + + If you have the misfortune of using System V, you are likely to +run into problems sooner or later having to do with statd/lockd. You +basically end up with one of three unsatisfactory choices: + 1) Grit your teeth and live with it. + 2) Try to make it work: + a) avoid NFS access so as not to stress statd/lockd. + b) try to understand the code in statd/lockd and hack it + to be more robust. + c) hunt out the system limit of locks, if there is one, + and increase it. Figure on at least two locks per + simultaneous imapd process and four locks per Pine + process. Better yet, make the limit be 10 times the + maximum number of processes. + d) increase the socket buffer (-S switch to lockd) if + it is offered. I don't know what this actually does, + but giving lockd more resources to do its work can't + hurt. Maybe. + 3) Decide that it can't possibly work, and turn off the + fcntl() calls in your program. + 4) If nuking statd/lockd can be done without breaking local + locking, then do so. This would make SVR4 have the same + limitations as BSD locking, with a couple of additional + bugs. + 5) Check for NFS, and don't do the fcntl() in the NFS case. + This is what c-client does. + + Note that if you are going to use NFS to access files on a server +which does not have statd/lockd running, your only choice is (3), (4), +or (5). Here again, IMAP can bail you out. + + These problems aren't unique to c-client applications; they have +also been reported with Elm, Mediamail, and other email tools. + + Of the other two SVR4 locking bugs: + + Programmer awareness is necessary to deal with the bug that you +can not get an exclusive lock unless the file is open for write. I +believe that c-client has fixed all of these cases. + + The problem about opening a second designator smashing any +current locks on the file has not been addressed satisfactorily yet. +This is not an easy problem to deal with, especially in c-client which +really doesn't know what other files/streams may be open by Pine. + + Aren't you so happy that you bought an System V system? diff --git a/imap/docs/md5.txt b/imap/docs/md5.txt new file mode 100644 index 00000000..c43f1023 --- /dev/null +++ b/imap/docs/md5.txt @@ -0,0 +1,91 @@ +/* ======================================================================== + * Copyright 1988-2006 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 + * + * + * ======================================================================== + */ + + MD5 Based Authentication + Mark Crispin + 1 November 1999 + + + The IMAP toolkit makes available two MD5 based authentication +mechanisms, CRAM-MD5 and APOP. CRAM-MD5 is described in RFC 2195, and +is a SASL (RFC 2222) authentication mechanism. APOP is described in +RFC 1939, the standard document for the POP3 protocol. + + These mechanisms use the same general idea. The server issues a +challenge; the client responds with an MD5 checksum of the challenge +plus the password; the server in compares the client's response with +its own calculated value of the checksum. If the client's response +matches the server's calulated value, the client is authenticated. + + Unlike plaintext passwords, this form of authentication is +believed to be secure against the session being monitored; "sniffing" +the session will not disclose the password nor will it provide usable +information to authenticate in another session without knowing the +password. + + The key disadvantage with this form of authentication is that the +server must know a plaintext form of the password. In traditional +UNIX authentication, the server only knows an encrypted form of the +password. Consequently, the authentication database for this form of +authentication must be kept strictly confidential; a bad guy who +acquires access to this database can access any account in the +database. + + CRAM-MD5 client support is implemented unconditionally; any +client application built with the IMAP toolkit will use CRAM-MD5 with +any server which advertises CRAM-MD5 SASL support. + + CRAM-MD5 and APOP server support is implemented if, and only if, +the CRAM-MD5 authentication database exists. By default, the CRAM-MD5 +authentication database is in a UNIX file called + /etc/cram-md5.pwd +It is recommended that this file be protected 0400. + + NOTE: FAILURE TO PROTECT THIS FILE AGAINST UNAUTHORIZED + ACCESS WILL COMPROMSE CRAM-MD5 AND APOP AUTHENTICATION + FOR ALL USERS LISTED IN THIS DATABASE. + + If the CRAM-MD5 authentication database exists, then plaintext +password authentication (e.g. the LOGIN command) will also use the +CRAM-MD5 passwords instead of UNIX passwords. Alternatively, it is +possible to build the IMAP toolkit so that plaintext password +authentication is disabled entirely, by using PASSWDTYPE=nul, e.g. + make aix PASSWDTYPE=nul + + + The CRAM-MD5 authentication database file consists of a series of +text lines, consisting of a UNIX user name, a single tab, and the +password. A line starting with a "#" character is ignored, as are any +lines which are not in valid format. For example: + +------------------------------Sample------------------------------ +# CRAM-MD5 authentication database +# Entries are in form <user><tab><password> +# Lines starting with "#" are comments + +bill hubba-hubba +hillary nysenator +monica beret +tripp wired +kenstarr inquisitor +reno waco +jessie thebody +billgates ruleworld +------------------------------Sample------------------------------ + + Every entry in the CRAM-MD5 authentication database must have a +corresponding entry in the /etc/passwd file. It is STRONGLY +RECOMMENDED that the CRAM-MD5 password NOT be the same as the +/etc/passwd password. It is permitted for the /etc/passwd password to +be disabled; /etc/passwd is just used to get the UID, GID, and home +directory information. diff --git a/imap/docs/mixfmt.txt b/imap/docs/mixfmt.txt new file mode 100644 index 00000000..afe3f940 --- /dev/null +++ b/imap/docs/mixfmt.txt @@ -0,0 +1,363 @@ +/* ======================================================================== + * Copyright 1988-2006 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 + * + * + * ======================================================================== + */ + +Last update: 18 December 2006 + +INTRODUCTION + +This file is the descendant of a design document used to specify the +mix format. An attempt is being made to keep this document more or +less current with the way the mix format actually works. + + +1. Mix mailbox naming + +Mailbox names correspond to directory names; thus mix format mailboxes +are "dual-use" (lack both \NoInferiors and \NoSelect). This will +satisfy some long-standing requests. + + +2. Mailbox files + +A mix format mailbox is a directory with regular files with filenames +of: + .mixmeta mailbox metadata file + .mixindex message index file (message static data) + .mixstatus message status file (message dynamic data) + .mix######## (where ######### is a <hex8>) secondary message + data files. + .mix primary message data file (used in experimental + versions, supported for compatibility only) + +2.1 Metadata, index, and status files + +The mailbox metadata, index, and status files contain a sequence of +CRLF-terminated lines. These files have an update sequence, which is +a strictly-ascending sequence value. Any time the file is changed, +the update sequence is increased; this allows easy detection of +whether the file has been changed by another process. For now, this +update sequence is a modseq (see below). + +2.1.1 Metadata file + +The mailbox metadata file is called ".mixmeta". It contains a series +of CRLF-terminated lines. The first character of the line is a key that +identifies the payload of the line, and the remainder of the line is the +payload. + Key Payload + --- ------- + S <hex8> ;; update sequence + V <hex8> ;; UIDVALIDITY + L <hex8> ;; UIDLAST + N <hex8> ;; current new message file + K [atom 0*(SP atom)] ;; keyword list + +All other keys are reserved for future assignment and must be ignored +(and may be discarded) by software which does not recognize them. The +mailbox metadata file is rewritten as part of new mail delivery (so +APPENDUID/COPYUID can work) and when new keywords are added. + +2.1.2 Message static index file + +The mailbox message static index file is called ".mixindex". It contains +a series of CRLF-terminated lines. The first character of the line is a +key that identifies the payload of the line, and the remainder of the line +is the payload. + Key Payload + --- ------- + S <hex8> ;; update sequence + : <uid>:<date>:<size>:<file>:<pos>:<isiz>:<hsiz> + ;; per-message record + +The per-message records contain the following data: + <uid> = <hex8> ;; message UID + <date> = <yyyymmddhhmmss+zzzz> ;; internal date + <size> = <hex8> ;; rfc822.size + <file> = <hex8> ;; message data file (0 = .mix file) + <pos> = <hex8> ;; message position in file + <isiz> = <hex8> ;; message internal data size + <hsiz> = <hex8> ;; header size (offset to body) + +All other keys, and subsequent fields in per-message records, are +reserved for future assignment and must be ignored (and may be +discarded) by software which does not recognize them. The mailbox +metadata file is appended by new mail delivery and rewritten by +expunge "burping", and otherwise is not altered. + +2.1.3 Message dynamic status file + +The mailbox message dynamic status file is called ".mixstatus". It contains +a series of CRLF-terminated lines. The first character of the line is a +key that identifies the payload of the line, and the remainder of the line +is the payload. + Key Payload + --- ------- + S <hex8> ;; update sequence + : <uid>:<uf>:<sf>:<mod>: ;; per-message record + +The per-message records contain the following data: + <uid> = <hex8> ;; message UID + <keys> = <hex8> ;; keyword flags + <flag> = <hex4> ;; system flags + <mod> = <hex8> ;; date/time last modified (modseq) + +All other keys, and subsequent fields in per-message records, are +reserved for future assignment and must be ignored (and may be +discarded) by software which does not recognize them. The mailbox +dynamic idex file is rewritten by flag changes (or any future change +that alters dynamic data) and is re-read when a session sees that the +mtime has changed (atime and ctime are not used). + +The modseq is an unsigned 32-bit date/time, along with a guarantee +that this value can not go backwards. It currently corresponds to the +time from time(); however, since it is unsigned, it won't run out until +the year 2106. In the future, this may be used as a basic for implementing +the IMAP CONDSTORE extension. + +2.2 Message data files + +A mix message file is a regular file with filename starting with +".mix" followed by a <hex8> suffix which indicates the file number. It +contains a series of CRLF-terminated lines. By special dispensation, the +filename ".mix" is used for file number 0, which was used in experimental +versions of mix as a "primary" file (this concept no longer exists). + +A file number is set to the current modseq when it is created. If a copy +or append causes the file to exceed the compiled-in file size limit, a new +file is started and the metadata is updated accordingly. + +Preceeding each message is per-message record with the following format: + Key Payload + --- ------- + ;; per-message record + : :<code>:<uid>:<date>:<size>: + +The per-message records contain the following data: + <code> = "msg" ;; fixed code + <uid> = <hex8> ;; message UID + <date> = <yyyymmddhhmmss+zzzz> ;; internal date + <size> = <hex8> ;; rfc822.size +The message data begins on the next line + +Subsequent fields are reserved for future assignment and must be ignored. + + +3. New mail delivery + +To deliver a new message, it is necessary to share lock the destination +metadata file, then get an exclusive lock on the destination index and +status files. Once this is done, the new message data is appended to the +new message file. The metadata (UIDLAST value), index, and status +files are all updated to add the new message. + +Then all the destination mailbox files are closed. + + +4. Mailbox pinging + +The index and status files are share locked. Initially, sequences are +remembered as zero, so at open time they are always "altered". + +The sequence from the index file is checked; if it is altered the index +file is read and processed as follows: + . If expunge is permitted, then any messages that are not in the index + are reported as having been expunged via mm_expunged(). + . new messages are announced via mm_exists()/mm_recent(). + +Next, the sequence from the status file is checked. If it is altered, +the status file is read and the status updated for any message which is +new or has an altered modseq in the status file. Altered modseq messages +are announced via mm_flags(). + +Then the index and status files are closed. + + +4. Flag alteration + +The status file is exclusive locked. + +The sequence from the status file is checked. If it is altered, the +status file is read and the status updated for any message which is +new or has an altered modseq in the status file. Altered modseq +messages are announced via mm_flags(). + +The alterations are then applied for all requested messages, updating +the modseq for each requestedmessage which changes flags as a result +of the alteration (alterations which do not result in a change do not +alter the modseq). Then the status file is rewritten with a new +sequence, but only if flags of at least one message was changed. + +Then the status file is closed. + + +5. Checkpoint and expunge + +Checkpoint is identical to expunge, however it skips the step of expunging +deleted messages. + +The index and status files are locked exclusive. If expunging, all +deleted messages are expunged from the index and announced via +mm_expunged(). The message data is notremoved at this time. + +If a checkpoint was requested, or if any messages were expunged, or if +it remembered that a "burp" was needed, then: + . the metadata file is locked exclusive. If this fails, remember that + a burp is needed. Otherwise perform a burp: + . calculate the file byte ranges occupied by expunged messages + . for each file needing "burping", open and slide down subsequent file + data on top of the expunged messages + . update the index and status files + +Then the index and status files are closed. + +5.1 More details on expunging and "burping" + +Shared expunge presents a problem due to the requirements of the IMAP +protocol. You can't "burp" away a message until you are certain that +no sharers have a pointer to any longer. Consequently, for the nonce +"burping" out expunged data be defered to an exclusive expunge as in +mbx format. + +If shared burping is ever implemented, then care will be needed not to +burp data that a session still relies upon. It's easy enough to burp +the index files; just create new index files, deleting the old, and +require that you look for a new one appearing at mailbox ping time +(when it's safe). The data files are a problem, since we +intentionally don't want to keep them open and do want to avoid quota +problems by overwriting in place. Also, when you burp you have to +change the pointers in the index file. + +Bottom line: shared burping is too hairy right now, so the first +version will do exclusive-only burping and not worry about it. If +shared burping is really needed, then that routine will need to be +rewritten. + +Shared burping has been a problem for every other IMAP server. Most +get it wrong, and cause terrible confusion to clients (including +client crashes). + + +6. Message data file file roll out strategy + +The current new message file is finalized, and a new one started, when +an append or copy is done that would cause the file to grow to larger +than a preconfigured size (MIXDATAROLL). A multi-message copy or +append is written into its entirety to a single new message file. In +the case of multi-copy, the new message file is switched when the sum +of the sizes of all messages to be copied would cause the current new +message file to exceed MIXDATAROLL. In the case of multi-append, only +the first message is considered; this is due to technical limitations. + +7. Error detection + +Mix detects bad data in the metadata, index, and status files; and +declares the stream dead. It does not unilaterally reassign +UIDVALIDITY the way that the flat file formats do. + +When mix reads a header from the message file, it also reads the +per-message record and verifies that there is a per-message record there. +This is a simple test for message file corruption. It doesn't declare +the stream dead; it simply issues an error message and returns a +zero-length string for the message header. This makes it possible for +the user to fix the mailbox simply by deleting and expunging any messages +that are in this state. + + +8. Reconstruct tool + +[None of this is implemented yet.] + +The layout of these files is designed to make the reconstruct tool be +as simple as possible. Much of the need for the reconstruct tool is +eliminated since the mix format has a much more limited scope of +writing than the flat file formats; thus there is "less collateral +damage." + +If the metadata file is lost or corrupted, then all keywords are lost; +if the mailbox has any keywords used in the .mixstatus file, it'll be +necessary to create some placeholder names. Otherwise, a new +UIDVALIDITY can be assigned, and a good UIDLAST value calculated by +the reconstruct tool. Since this file is very small, it's not likely +to be damaged. + +If the index file is lost or corrupted, it is possible to reconstruct +it with no loss by reading all the data files. However, this could +cause expunged but not yet burped messages to reappear. + +If the status file is lost or corrupted, then flags are lost and +will revert to a default state of no flags set. Just deleting the +corrupted file is good enough. + +The reconstruct tool can use the per-message record in the message +file to locate messages if the recorded sizes and/or messages are +corrupt. If that happens, it will need to rebuild the index file +(with associated changes to the metadata file to change the +UIDVALIDITY). That should probably be a manual operation and not be +part of the default operation or auto-reconstruct. + + +9. Locking strategy + +The mix format does not use the traditional c-client /tmp file locking. + +The metadata file is open and locked whenever the mailbox is open. +Normally this is a shared lock, but it will be upgraded to exclusive +if the mailbox is expunged. As a guard (since there is no true +lock-upgrade/downgrade on UNIX), the index exclusive lock must be +acquired first before upgrading to exclusive. + +The index file is shared locked when reading the index, and exclusive +locked (and read) when appending new messages to the index or when +expunging (note that expunging also requires an exclusive lock on +metadata). Normally, the index file is not open or locked. + +The status file is shared locked when reading status, and exclusive +locked (and read) when updating status. Normally, the status file is +not open or locked. + +It isn't necessary to lock any of the data files as long as we only +have exclusive burping. + + +10. Memory usage + +The mix format returns a file stringstruct, which is the modern +c-client behavior. This prevents imapd from growing to enormous sizes +due to a godzillagram (how it affects other programs depends upon what +they do with the returned stringstruct). + + +11. Future extensions + +Cached ENVELOPE, BODYSTRUCTURE. Cyrus does, and this will eliminate +most of the reason to access the data files. Possibly cached overviews, +ala NNTP, instead? + + +Support for ANNOTATION. + + +12. RENAME issues + +Mix currently makes no attempt to address the IMAP RENAME problem. +This occurs when a mailbox is deleted, and another mailbox is renamed +with that name in place, no attempt is made to reassign UIDVALIDITY +for this mailbox and all the inferior mailboxes. This potentially can +cause problems for a disconnected-use client that has cached status +for the old mailbox which had that name. + +The RENAME problem is a well known flaw in the IMAP protocol. Few +servers correctly handle it (among other things, not only do all the +UIDVALIDITY values have to be changed but this has to be done +atomically!). It was a mistake to add RENAME into IMAP, but it's much +too late to remove it now. diff --git a/imap/docs/naming.txt b/imap/docs/naming.txt new file mode 100644 index 00000000..b0b484ae --- /dev/null +++ b/imap/docs/naming.txt @@ -0,0 +1,143 @@ +/* ======================================================================== + * Copyright 1988-2006 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 + * + * + * ======================================================================== + */ + + Mailbox Name Conventions + Mark Crispin + 5 October 2005 + + +Please refer to the file drivers.txt for related information. + + +I. Special names + +Special names appear by themselves. + +I.a. INBOX + +The name INBOX is special and refers to primary incoming message +mailbox on the local system. + + +I.b. #mhinbox (UNIX only) + +The name #mhinbox is special and refers to the primary incoming mh +format mailbox on the local system. Don't worry about this if you +don't know what mh format is. + + +II. Special prefixes + +All names which start with a "#" have a "special prefix" which +identifies an alternative namespace. Special prefixes appear in front +of some additional text which constitutes a suffix. + +II.a. #mh/ (UNIX only) + +The prefix #mh/ is special and refers to the mh format mailbox named +with the suffix. For example, #mh/foo refers to the mh format mailbox +named foo. Don't worry about this if you don't know what mh format is. + + +II.b. #news. (UNIX only) + +The prefix #news. is special and refers to the newsgroup named with +the suffix. For example, #news.comp.mail.misc refers to the newsgroup +named comp.mail.misc. + + +II.c. #ftp/ (UNIX only) + +The prefix #ftp/ is special and refers to the anonymous ftp filesystem +named with the suffix. For example, #ftp/foo/bar refers to the file +/foo/bar in the anonymous FTP filesystem. Anonymous FTP files are +available to anonymous IMAP logins. + + +II.d. #public/ (UNIX only) + +The prefix #public/ is special and refers to the public files +filesystem named with the suffix. For example, #public/foo/bar refers +to the file /foo/bar in the public filesystem. Public files are +available to anonymous IMAP logins. + + +II.e. #shared/ (UNIX only) + +The prefix #shared/ is special and refers to the shared files +filesystem named with the suffix. For example, #shared/foo/bar +frefers to the file /foo/bar in the shared filesystem. + + +III. Remote names + +All names which start with "{" are remote names, and are in the form + "{" remote_system_name [":" port] [flags] "}" [mailbox_name] +where: + remote_system_name Internet domain name or bracketed IP address + of server. + port optional TCP port number, default is the + default port for that service + flags optional flags, one of the following: + "/service=" service mailbox access service, default is "imap" + "/user=" user remote user name for login on the server + "/authuser=" user remote authentication user; if specified this + is the user name whose password is used (e.g. + administrator) + "/anonymous" remote access as anonymous user + "/debug" record protocol telemetry in application's + debug log + "/secure" do not transmit a plaintext password over + the network + "/imap", "/imap2", "/imap2bis", "/imap4", "/imap4rev1" + equivalent to /service=imap + "/pop3" equivalent to /service=pop3 + "/nntp" equivalent to /service=nntp + "/norsh" do not use rsh or ssh to establish a preauthenticated + IMAP session + "/ssl" use the Secure Socket Layer to encrypt the session + "/validate-cert" validate certificates from TLS/SSL server (this is the + default behavior) + "/novalidate-cert" do not validate certificates from TLS/SSL server, + needed if server uses self-signed certificates + "/tls" force use of start-TLS to encrypt the session, and + reject connection to servers that do not support it + "/tls-sslv23" use the depreciated SSLv23 client when negotiating + TLS to the server. This is necessary with some + broken servers which (incorrectly) think that TLS + is just another way of doing SSL. + "/notls" do not do start-TLS to encrypt the session, even + with servers that support it + "/readonly" request read-only mailbox open (IMAP only; ignored + on NNTP, and an error with SMTP and POP3) + "/loser" disable various protocol features and perform various + client-side workarounds; for example, it disables + the SEARCH command in IMAP and does client-side + searching instead. The precise measures taken by + /loser depend upon the protocol and are subject to + change over time. /loser is intended for use with + defective servers which do not implement the + protocol specification correctly. It should be used + only as a last resort since it will seriously + degrade performance. + mailbox_name remote mailbox name, default is INBOX + +For example: + {imap.foo.com}INBOX +opens an IMAP connection to system imap.foo.com and selects INBOX. + + +IV. All other names + +All other names are treated as local file names, relative to the +user's home directory. Read drivers.txt for more details. diff --git a/imap/docs/rfc/README b/imap/docs/rfc/README new file mode 100644 index 00000000..550d8d20 --- /dev/null +++ b/imap/docs/rfc/README @@ -0,0 +1,70 @@ +The following documents are necessary to understand the syntax rules +most of the remaining documents. Note that some documents refer to +RFC 2234 which has been replaced by RFC 5234: + rfc5234.txt Augmented BNF for Syntax Specifications - ABNF + rfc4466.txt Collected Extensions to IMAP4 ABNF + + +The following documents specify the IMAP protocol: + rfc3501.txt Internet Message Access Protocol - Version 4rev1 + + +The following documents provide additional information which is useful +in understanding the IMAP protocol: + rfc1733.txt Distributed Electronic Mail Models in IMAP4 + rfc2180.txt IMAP4 Multi-Accessed Mailbox Practice + rfc2683.txt IMAP4 Implementation Recommendations + rfc4549.txt Synchronization Operations for Disconnected IMAP4 Clients + + +The following documents describe extensions to the IMAP protocol. +Items marked with "*" are supported in this distribution: + rfc4314.txt ACL + * rfc3516.txt BINARY + rfc4469.txt CATENATE + * rfc3348.txt CHILDREN + rfc4978.txt COMPRESS + rfc4551.txt CONDSTORE + rfc5161.txt ENABLE + * rfc4731.txt ESEARCH + rfc2971.txt ID + * rfc2177.txt IDLE + * rfc2088.txt LITERAL+ + * rfc2221.txt LOGIN-REFERRALS + * rfc2193.txt MAILBOX-REFERRALS + * rfc3502.txt MULTIAPPEND + * rfc2342.txt NAMESPACE + rfc5162.txt QRESYNC + rfc2087.txt QUOTA + * rfc4959.txt SASL-IR + * rfc4315.txt UIDPLUS + * rfc3691.txt UNSELECT + rfc4467.txt URLAUTH + * rfc5032.txt WITHIN + + +The following documents describe SASL: + rfc4422.txt Simple Authentication and Security Layer (SASL) +and the SASL mechanisms supported in this distribution: + rfc4505.txt ANONYMOUS + rfc2195.txt CRAM-MD5 + rfc4752.txt GSSAPI + rfc4616.txt PLAIN + + +The following documents relate to internationalization issues: + rfc4790.txt Internet Application Protocol Collation Registry + rfc5051.txt i;unicode-casemap - Simple Unicode Collation Algorithm + + +The following documents are primarily of historic interest: + rfc1732.txt IMAP4 Compatibility with IMAP2 and IMAP2bis + rfc2061.txt IMAP4 Compatibility with IMAP2bis + rfc2062.txt Internet Message Access Protocol - Obsolete Syntax + + +The following documents discuss matters which are related to IMAP: + rfc3503.txt MDN Profile for IMAP + rfc3656.txt MUPDATE Distributed Mailbox Database Protocol + rfc4468.txt Message Submission BURL Extension + rfc5092.txt IMAP URL Scheme diff --git a/imap/docs/rfc/rfc1732.txt b/imap/docs/rfc/rfc1732.txt 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] + |