summaryrefslogtreecommitdiff
path: root/imap/docs
diff options
context:
space:
mode:
Diffstat (limited to 'imap/docs')
-rw-r--r--imap/docs/BUILD491
-rw-r--r--imap/docs/CONFIG181
-rw-r--r--imap/docs/FAQ.html4226
-rw-r--r--imap/docs/FAQ.txt2993
-rw-r--r--imap/docs/IPv6.txt131
-rw-r--r--imap/docs/RELNOTES787
-rw-r--r--imap/docs/SSLBUILD267
-rw-r--r--imap/docs/Y2K145
-rw-r--r--imap/docs/bugs.txt234
-rw-r--r--imap/docs/calendar.txt332
-rw-r--r--imap/docs/commndmt.txt101
-rw-r--r--imap/docs/draft/README19
-rw-r--r--imap/docs/draft/i18n.txt1140
-rw-r--r--imap/docs/draft/sort.txt885
-rw-r--r--imap/docs/drivers.txt189
-rw-r--r--imap/docs/formats.txt217
-rw-r--r--imap/docs/imaprc.txt613
-rw-r--r--imap/docs/internal.txt2988
-rw-r--r--imap/docs/locking.txt417
-rw-r--r--imap/docs/md5.txt91
-rw-r--r--imap/docs/mixfmt.txt363
-rw-r--r--imap/docs/naming.txt143
-rw-r--r--imap/docs/rfc/README70
-rw-r--r--imap/docs/rfc/rfc1732.txt283
-rw-r--r--imap/docs/rfc/rfc1733.txt171
-rw-r--r--imap/docs/rfc/rfc2061.txt171
-rw-r--r--imap/docs/rfc/rfc2062.txt451
-rw-r--r--imap/docs/rfc/rfc2087.txt283
-rw-r--r--imap/docs/rfc/rfc2088.txt115
-rw-r--r--imap/docs/rfc/rfc2177.txt227
-rw-r--r--imap/docs/rfc/rfc2180.txt787
-rw-r--r--imap/docs/rfc/rfc2193.txt507
-rw-r--r--imap/docs/rfc/rfc2195.txt283
-rw-r--r--imap/docs/rfc/rfc2221.txt283
-rw-r--r--imap/docs/rfc/rfc2342.txt563
-rw-r--r--imap/docs/rfc/rfc2683.txt1291
-rw-r--r--imap/docs/rfc/rfc2971.txt451
-rw-r--r--imap/docs/rfc/rfc3348.txt339
-rw-r--r--imap/docs/rfc/rfc3501.txt6052
-rw-r--r--imap/docs/rfc/rfc3502.txt395
-rw-r--r--imap/docs/rfc/rfc3503.txt507
-rw-r--r--imap/docs/rfc/rfc3516.txt451
-rw-r--r--imap/docs/rfc/rfc3656.txt1067
-rw-r--r--imap/docs/rfc/rfc3691.txt283
-rw-r--r--imap/docs/rfc/rfc4314.txt1515
-rw-r--r--imap/docs/rfc/rfc4315.txt451
-rw-r--r--imap/docs/rfc/rfc4422.txt1851
-rw-r--r--imap/docs/rfc/rfc4466.txt955
-rw-r--r--imap/docs/rfc/rfc4467.txt1011
-rw-r--r--imap/docs/rfc/rfc4468.txt787
-rw-r--r--imap/docs/rfc/rfc4469.txt731
-rw-r--r--imap/docs/rfc/rfc4505.txt507
-rw-r--r--imap/docs/rfc/rfc4549.txt1963
-rw-r--r--imap/docs/rfc/rfc4551.txt1403
-rw-r--r--imap/docs/rfc/rfc4616.txt619
-rw-r--r--imap/docs/rfc/rfc4731.txt451
-rw-r--r--imap/docs/rfc/rfc4752.txt563
-rw-r--r--imap/docs/rfc/rfc4790.txt1459
-rw-r--r--imap/docs/rfc/rfc4959.txt395
-rw-r--r--imap/docs/rfc/rfc4978.txt507
-rw-r--r--imap/docs/rfc/rfc5032.txt283
-rw-r--r--imap/docs/rfc/rfc5051.txt395
-rw-r--r--imap/docs/rfc/rfc5092.txt1795
-rw-r--r--imap/docs/rfc/rfc5161.txt395
-rw-r--r--imap/docs/rfc/rfc5162.txt1291
-rw-r--r--imap/docs/rfc/rfc5234.txt899
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&nbsp;"</code> line in traditional
+ UNIX mailbox files? My other mail program just considers every line
+ that starts with <code>"From&nbsp;"</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=&lt;...my user name...&gt; host=&lt;...my
+ imap server...&gt;</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&nbsp;"</code> line in traditional UNIX mailbox
+ files? My other mail program just considers every line that starts with
+ <code>"From&nbsp;"</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&nbsp;"</code> is treated as the start of a message, then
+ every message text line which starts with <code>"From&nbsp;"</code> has
+ to be quoted (typically by prefixing a "&gt;" character). People
+ complain about this -- "why did a &gt; get stuck in my message?"
+
+ <p>So, good mail reading software only considers a line to be a
+ <code>"From&nbsp;"</code> line if it follows the actual specification
+ for a "From&nbsp;" line. This means, among other things, that the day of
+ week is fixed-format: <code>"May&nbsp;14"</code>, but
+ <code>"May&nbsp;&nbsp;7"</code> (note the extra space) as opposed to
+ <code>"May&nbsp;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&nbsp;"</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 &lt;...mailbox...&gt;.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 "&gt;" 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=&lt;...my user name...&gt; host=&lt;...my client system...&gt;
+
+</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 &amp; 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&#252;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]
+