tobias/docker-offlineimap
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge tag 'v6.5.7' into maint

Browse Source 
v6.5.7

Signed-off-by: Nicolas Sebrecht <nicolas.s-dev@laposte.net>
This commit is contained in:
Nicolas Sebrecht 2016-02-24 01:36:07 +01:00
commit d0cdd42d09
156 changed files with 66097 additions and 5784 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
.gitignore vendored
View File

@ -1,8 +1,14 @@
# Generated files # Backups.
.*.swp
.*.swo
*.html
*~
# websites.
/website/
/wiki/
# Generated files.
/docs/dev-doc/
/build/ /build/
*.pyc *.pyc
offlineimap.1 offlineimap.1
# backups offlineimapui.7
.*.swp
.*.swo
*~

123
CONTRIBUTING.rst Normal file
View File

@ -0,0 +1,123 @@
.. -*- coding: utf-8 -*-
.. vim: spelllang=en ts=2 expandtab:
.. _OfflineIMAP: https://github.com/OfflineIMAP/offlineimap
.. _Github: https://github.com/OfflineIMAP/offlineimap
.. _repository: git://github.com/OfflineIMAP/offlineimap.git
.. _maintainers: https://github.com/OfflineIMAP/offlineimap/blob/next/MAINTAINERS.rst
.. _mailing list: http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project
.. _Developer's Certificate of Origin: https://github.com/OfflineIMAP/offlineimap/blob/next/docs/doc-src/dco.rst
.. _Community's website: https://offlineimap.org
.. _APIs in OfflineIMAP: http://offlineimap.org/documentation.html#available-apis
.. _documentation: https://offlineimap.org/documentation.html
.. _Coding Guidelines: http://offlineimap.org/doc/CodingGuidelines.html
.. _Know the status of your patches: http://offlineimap.org/doc/GitAdvanced.html#know-the-status-of-your-patch-after-submission
=================
HOW TO CONTRIBUTE
=================
You'll find here the **basics** to contribute to OfflineIMAP_, addressed to
users as well as learning or experienced developers to quickly provide
contributions.
**For more detailed documentation, see the** `Community's website`_.
.. contents:: :depth: 3
For the imaptients
==================
- `Coding Guidelines`_
- `APIs in OfflineIMAP`_
- `Know the status of your patches`_ after submission
- All the `documentation`_
Submit issues
=============
Issues are welcome to both Github_ and the `mailing list`_, at your own
convenience.
Community
=========
All contributors to OfflineIMAP_ are benevolent volunteers. This makes hacking
to OfflineIMAP_ **fun and open**.
Thanks to Python, almost every developer can quickly become productive. Students
and novices are welcome. Third-parties patches are essential and proved to be a
wonderful source of changes for both fixes and new features.
OfflineIMAP_ is entirely written in Python, works on IMAP and source code is
tracked with Git.
*It is expected that most contributors don't have skills to all of these areas.*
That's why the best thing you could do for you, is to ask us about any
difficulty or question raising in your mind. We actually do our best to help new
comers. **We've all started like this.**
- The official repository_ is maintained by the core team maintainers_.
- The `mailing list`_ is where all the exciting things happen.
Getting started
===============
Occasional contributors
-----------------------
* Clone the official repository_.
Regular contributors
--------------------
* Create an account and login to Github.
* Fork the official repository_.
* Clone your own fork to your local workspace.
* Add a reference to your fork (once)::
$ git remote add myfork https://github.com/<your_Github_account>/offlineimap.git
* Regularly fetch the changes applied by the maintainers::
$ git fetch origin
$ git checkout master
$ git merge offlineimap/master
$ git checkout next
$ git merge offlineimap/next
Making changes (all contributors)
---------------------------------
1. Create your own topic branch off of ``next`` (recently updated) via::
$ git checkout -b my_topic next
2. Check for unnecessary whitespaces with ``git diff --check`` before committing.
3. Commit your changes into logical/atomic commits. **Sign-off your work** to
confirm you agree with the `Developer's Certificate of Origin`_.
4. Write a good *commit message* about **WHY** this patch (take samples from
the ``git log``).
Learn more
==========
There is already a lot of documentation. Here's where you might want to look
first:
- The directory ``offlineimap/docs`` has all kind of additional documentation
(man pages, RFCs).
- The file ``offlineimap.conf`` allows to know all the supported features.
- The file ``TODO.rst`` express code changes we'd like and current *Work In
Progress* (WIP).

34
COPYING
View File

@ -1,3 +1,13 @@
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
GNU GENERAL PUBLIC LICENSE GNU GENERAL PUBLIC LICENSE
Version 2, June 1991 Version 2, June 1991
@ -55,7 +65,7 @@ patent must be licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution and The precise terms and conditions for copying, distribution and
modification follow. modification follow.
GNU GENERAL PUBLIC LICENSE GNU GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@ -110,7 +120,7 @@ above, provided that you also meet all of these conditions:
License. (Exception: if the Program itself is interactive but License. (Exception: if the Program itself is interactive but
does not normally print such an announcement, your work based on does not normally print such an announcement, your work based on
the Program is not required to print an announcement.) the Program is not required to print an announcement.)
These requirements apply to the modified work as a whole. If These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Program, identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in and can be reasonably considered independent and separate works in
@ -168,7 +178,7 @@ access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not distribution of the source code, even though third parties are not
compelled to copy the source along with the object code. compelled to copy the source along with the object code.
4. You may not copy, modify, sublicense, or distribute the Program 4. You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License. Any attempt except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense or distribute the Program is otherwise to copy, modify, sublicense or distribute the Program is
@ -225,7 +235,7 @@ impose that choice.
This section is intended to make thoroughly clear what is believed to This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License. be a consequence of the rest of this License.
8. If the distribution and/or use of the Program is restricted in 8. If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License original copyright holder who places the Program under this License
@ -278,7 +288,7 @@ PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES. POSSIBILITY OF SUCH DAMAGES.
END OF TERMS AND CONDITIONS END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest If you develop a new program, and you want it to be of the greatest
@ -338,3 +348,17 @@ proprietary programs. If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the consider it more useful to permit linking proprietary applications with the
library. If this is what you want to do, use the GNU Library General library. If this is what you want to do, use the GNU Library General
Public License instead of this License. Public License instead of this License.
----------------------------------------------------------------
In addition, as a special exception, the copyright holders give
permission to link the code of portions of this program with the OpenSSL
library under certain conditions as described in each individual source
file, and distribute linked combinations including the two.
You must obey the GNU General Public License in all respects for all of
the code used other than OpenSSL. If you modify file(s) with this
exception, you may extend this exception to your version of the file(s),
but you are not obligated to do so. If you do not wish to do so, delete
this exception statement from your version. If you delete this exception
statement from all source files in the program, then also delete it
here.

17
COPYRIGHT
View File

@ -1,17 +0,0 @@
offlineimap Mail syncing software
Copyright (C) 2002 - 2009 John Goerzen
<jgoerzen@complete.org>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

36
Changelog.draft.rst
View File

@ -1,36 +0,0 @@
=========
ChangeLog
=========
Users should ignore this content: **it is draft**.
Contributors should add entries here in the following section, on top of the
others.
`WIP (coming releases)`
=======================
New Features
------------
Changes
-------
* Give more detailed error when encountering a corrupt UID mapping file.
Bug Fixes
---------
Pending for the next major release
==================================
* UIs get shorter and nicer names. (API changing)
Stalled
=======
* Learn Sqlite support.
Stalled: it would need to learn the ability to choose between the current
format and SQL to help testing the long term.

24
Changelog.maint.md Normal file
View File

@ -0,0 +1,24 @@
---
layout: page
title: Changelog of the stable branch
---
* The following excerpt is only usefull when rendered in the website.
{:toc}
This is the Changelog of the maintenance branch.
**NOTE FROM THE MAINTAINER:**
This branch comes almost as-is. With no URGENT requirements to update this
branch (e.g. big security fix), it is left behind.
If anyone volunteers to maintain it and backport patches, let us know!
### OfflineIMAP v6.3.2.1 (2011-03-23)
#### Bug Fixes
* Sanity checks for SSL cacertfile configuration.
* Fix regression (UIBase is no more).
* Make profiling mode really enforce single-threading.

48
Changelog.maint.rst
View File

@ -1,48 +0,0 @@
=========
ChangeLog
=========
:website: http://offlineimap.org
This is the Changelog of the maintenance branch.
**NOTE FROM THE MAINTAINER:**
Contributors should use the `WIP` section in Changelog.draft.rst in order to
add changes they are working on. I will use it to make the new changelog entry
on releases. And because I'm lazy, it will also be used as a draft for the
releases announces.
OfflineIMAP v6.3.2.3 (2011-08-10)
=================================
Changes
-------
* Output more detailed error on corrupt LocalStatus.
* More detailed error output on corrupt UID mapping files.
Bug Fixes
---------
* Fix typo to force singlethreading in debug mode.
OfflineIMAP v6.3.2.2 (2011-04-24)
=================================
Changes
-------
* Improve traceback on some crashes.
OfflineIMAP v6.3.2.1 (2011-03-23)
=================================
Bug Fixes
---------
* Sanity checks for SSL cacertfile configuration.
* Fix regression (UIBase is no more).
* Make profiling mode really enforce single-threading.

1095
Changelog.md Normal file
View File

File diff suppressed because it is too large Load Diff

190
Changelog.rst
View File

@ -1,190 +0,0 @@
=========
ChangeLog
=========
:website: http://offlineimap.org
**NOTE FROM THE MAINTAINER:**
Contributors should use the `WIP` section in Changelog.draft.rst in order to
add changes they are working on. I will use it to make the new changelog entry
on releases. And because I'm lazy, it will also be used as a draft for the
releases announces.
OfflineIMAP v6.3.2 (2010-02-21)
===============================
Notes
-----
First of all I'm really happy to announce our new official `website`_. Most of
the work started from the impulse of Philippe LeCavalier with the help of
Sebastian Spaeth and other contributors. Thanks to everybody.
In this release, we are still touched by the "SSL3 write pending" but I think
time was long enough to try to fix it. We have our first entry in the "KNOWN
BUG" section of the manual about that. I'm afraid it could impact a lot of users
if some distribution package any SSL library not having underlying (still
obscure) requirements. Distribution maintainers should be care of it. I hope
this release will help us to have more reports.
This release will also be the root of our long maintenance support.
Other bugs were fixed.
Bug Fixes
---------
* Fix craches for getglobalui().
* Fix documentation build.
* Restore compatibiliy with python 2.5.
OfflineIMAP v6.3.2-rc3 (2010-02-06)
===================================
Notes
-----
We are still touched by the "SSL3 write pending" bug it would be really nice to
fix before releasing the coming stable. In the worse case, we'll have to add the
first entry in the "KNOWN BUG" section of the manual. I'm afraid it could impact
a lot of users if some distribution package any SSL library not having
underlying (still obscure) requirements.
The best news with this release are the Curse UI fixed and the better reports
on errors.
In this release I won't merge any patch not fixing a bug or a security issue.
More feedbacks on the main issue would be appreciated.
Changes
-------
* Sample offlineimap.conf states it expects a PEM formatted certificat.
* Give better trace information if an error occurs.
* Have --version ONLY print the version number.
* Code cleanups.
Bug Fixes
---------
* Fix Curses UI (simplified by moving from MultiLock to Rlock implementation).
* Makefile: docutils build work whether python extension command is stripped or not.
* Makefile: clean now removes HTML documentation files.
OfflineIMAP v6.3.2-rc2 (2010-12-21)
===================================
Notes
-----
We are beginning a new tests cycle. At this stage, I expect most people will try
to intensively stuck OfflineIMAP. :-)
New Features
------------
* Makefile learn to build the package and make it the default.
* Introduce a Changelog to involve community in the releasing process.
* Migrate documentation to restructuredtext.
Changes
-------
* Improve CustomConfig documentation.
* Imply single threading mode in debug mode exept for "-d thread".
* Code and import cleanups.
* Allow UI to have arbitrary names.
* Code refactoring around UI and UIBase.
* Improve version managment and make it easier.
* Introduce a true single threading mode.
Bug Fixes
---------
* Understand multiple EXISTS replies from servers like Zimbra.
* Only verify hostname if we actually use CA cert.
* Fix ssl ca-cert in the sample configuration file.
* Fix 'Ctrl+C' interruptions in threads.
* Fix makefile clean for files having whitespaces.
* Fix makefile to not remove unrelated files.
* Fixes in README.
* Remove uneeded files.
OfflineIMAP v6.3.2-rc1 (2010-12-19)
===================================
Notes
-----
We are beginning a tests cycle. If feature topics are sent, I may merge or
delay them until the next stable release.
New Features
------------
* Primitive implementation of SSL certificates check.
Changes
-------
* Use OptionParser instead of getopts.
* Code cleanups.
Bug Fixes
---------
* Fix reading password from UI.
OfflineIMAP v6.3.1 (2010-12-11)
===============================
Notes
-----
Yes, I know I've just annouced the v6.3.0 in the same week. As said, it
was not really a true release for the software. This last release
includes fixes and improvements it might be nice to update to.
Thanks to every body who helped to make this release with patches and
tips through the mailing list. This is clearly a release they own.
Changes
-------
* cProfile becomes the default profiler. Sebastian Spaeth did refactoring to
prepare to the coming unit test suites.
* UI output formating enhanced.
* Some code cleanups.
Bug Fixes
---------
* Fix possible overflow while working with Exchange.
* Fix time sleep while exiting threads.
OfflineIMAP v6.3.0 (2010-12-09)
===============================
Notes
-----
This release is more "administrative" than anything else and mainly marks the
change of the maintainer. New workflow and policy for developers come in. BTW,
I don't think I'll maintain debian/changelog. At least, not in the debian way.
Most users and maintainers may rather want to skip this release.
Bug Fixes
---------
* Fix terminal display on exit.
* netrc password authentication.
* User name querying from netrc.

29
MAINTAINERS.rst Normal file
View File

@ -0,0 +1,29 @@
.. -*- coding: utf-8 -*-
Official maintainers
====================
Eygene Ryabinkin
email: rea at freebsd.org
github: konvpalto
Sebastian Spaeth
email: sebastian at sspaeth.de
github: spaetz
Nicolas Sebrecht
email: nicolas.s-dev at laposte.net
github: nicolas33
Mailing List maintainers
========================
Eygene Ryabinkin
email: rea at freebsd.org
Sebastian Spaeth
email: sebastian at sspaeth.de
Nicolas Sebrecht
email: nicolas.s-dev at laposte.net

14
MANIFEST.in Normal file
View File

@ -0,0 +1,14 @@
global-exclude .gitignore .git *.bak *.orig *.rej
include setup.py
include COPYING
include Changelog*
include MAINTAINERS
include MANIFEST.in
include Makefile
include README.md
include offlineimap.conf*
include offlineimap.py
recursive-include offlineimap *.py
recursive-include bin *
recursive-include docs *
recursive-include test *

20
Makefile
View File

@ -15,10 +15,10 @@
# along with this program; if not, write to the Free Software # along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
VERSION=6.3.2.3 VERSION=`./offlineimap.py --version`
TARGZ=offlineimap_$(VERSION).tar.gz TARGZ=offlineimap_$(VERSION).tar.gz
SHELL=/bin/bash SHELL=/bin/bash
RST2HTML=`type rst2html 2>/dev/null 2>&1 && echo rst2html || echo rst2html.py` RST2HTML=`type rst2html >/dev/null 2>&1 && echo rst2html || echo rst2html.py`
all: build all: build
@ -35,19 +35,15 @@ clean:
-find . -name '*.pygc' -exec rm -f {} \; -find . -name '*.pygc' -exec rm -f {} \;
-find . -name '*.class' -exec rm -f {} \; -find . -name '*.class' -exec rm -f {} \;
-find . -name '.cache*' -exec rm -f {} \; -find . -name '.cache*' -exec rm -f {} \;
-find . -name '*.html' -exec rm -f {} \;
-rm -f manpage.links manpage.refs -rm -f manpage.links manpage.refs
-find . -name auth -exec rm -vf {}/password {}/username \; -find . -name auth -exec rm -vf {}/password {}/username \;
@$(MAKE) -C docs clean @$(MAKE) -C clean
man: docs:
@$(MAKE) -C docs man
doc:
@$(MAKE) -C docs @$(MAKE) -C docs
$(RST2HTML) README.rst readme.html
$(RST2HTML) SubmittingPatches.rst SubmittingPatches.html websitedoc:
$(RST2HTML) Changelog.rst Changelog.html @$(MAKE) -C websitedoc
targz: ../$(TARGZ) targz: ../$(TARGZ)
../$(TARGZ): ../$(TARGZ):
@ -55,7 +51,7 @@ targz: ../$(TARGZ)
echo "Containing directory must be called offlineimap-$(VERSION)"; \ echo "Containing directory must be called offlineimap-$(VERSION)"; \
exit 1; \ exit 1; \
fi; \ fi; \
pwd && cd .. && pwd && tar -zhcv --exclude '.git' -f $(TARGZ) offlineimap-$(VERSION) pwd && cd .. && pwd && tar -zhcv --exclude '.git' --exclude 'website' --exclude 'wiki' -f $(TARGZ) offlineimap-$(VERSION)
rpm: targz rpm: targz
cd .. && sudo rpmbuild -ta $(TARGZ) cd .. && sudo rpmbuild -ta $(TARGZ)

78
README.md Normal file
View File

@ -0,0 +1,78 @@
[offlineimap]: https://github.com/OfflineIMAP/offlineimap
[website]: http://offlineimap.org
[wiki]: http://github.com/OfflineIMAP/offlineimap/wiki
# OfflineImap
## Description
OfflineIMAP is a software to dispose your e-mail mailbox(es) as a **local
Maildir**. OfflineIMAP will synchronize both sides via *IMAP*.
The main downside about IMAP is that you have to **trust** your MAIL provider to
not loose your mails. This is not something impossible while not very common.
With OfflineIMAP, you can download your Mailboxes and make you own backups of
the Maildir.
This allows reading your mails while offline without the need for the mail
reader (MUA) to support IMAP disconnected operations. Need an attachement from a
message without internet? It's fine, the message is still there.
## License
GNU General Public License v2.
## Why should I use OfflineIMAP?
* It is **fast**.
* It is **reliable**.
* It is **flexible**.
* It is **safe**.
## Downloads
You should first check if your distribution already package OfflineIMAP for you.
Downloads releases as [tarball or zipball](https://github.com/OfflineIMAP/offlineimap/tags).
## Feedbacks and contributions
**The user discussions, development, announces and all the exciting stuff take
place in the mailing list.** While not mandatory to send emails, you can
[subscribe here](http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project).
Bugs, issues and contributions can be requested to both the mailing list or the
[official Github project][offlineimap].
## The community
* OfflineIMAP's main site is the [project page at Github][offlineimap].
* There is the [OfflineIMAP community's website][website].
* And finally, [the wiki][wiki].
## Requirements
* Python v2.7
* Python SQlite (optional while recommended)
## Documentation
All the current and updated documentation is at the [community's website][website].
### Dispose locally
You might want to dispose the documentation locally. Get the sources of the website.
For the other documentations, run the approppriate make target:
```
$ ./scripts/get-repository.sh website
$ cd docs
$ make html # Require rst2html
$ make man # Require a2x
$ make api # Require sphinx
```

296
README.rst
View File

@ -1,296 +0,0 @@
.. -*- coding: utf-8 -*-
.. _mailing list: http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project
======
README
======
.. contents::
.. sectnum::
Description
===========
Welcome to the official OfflineIMAP project.
*NOTICE:* this software was written by John Goerzen, who retired from
maintaining. It is now maintained by Nicolas Sebrecht at
https://github.com/nicolas33/offlineimap. Thanks to John for his great job and
to have share this project with us.
OfflineIMAP is a tool to simplify your e-mail reading. With OfflineIMAP, you can
read the same mailbox from multiple computers. You get a current copy of your
messages on each computer, and changes you make one place will be visible on all
other systems. For instance, you can delete a message on your home computer, and
it will appear deleted on your work computer as well. OfflineIMAP is also useful
if you want to use a mail reader that does not have IMAP support, has poor IMAP
support, or does not provide disconnected operation.
OfflineIMAP works on pretty much any POSIX operating system, such as Linux, BSD
operating systems, MacOS X, Solaris, etc.
OfflineIMAP is a Free Software project licensed under the GNU General Public
License. You can download it for free, and you can modify it. In fact, you are
encouraged to contribute to OfflineIMAP, and doing so is fast and easy.
OfflineIMAP is FAST; it synchronizes my two accounts with over 50 folders in 3
seconds. Other similar tools might take over a minute, and achieve a
less-reliable result. Some mail readers can take over 10 minutes to do the same
thing, and some don't even support it at all. Unlike other mail tools,
OfflineIMAP features a multi-threaded synchronization algorithm that can
dramatically speed up performance in many situations by synchronizing several
different things simultaneously.
OfflineIMAP is FLEXIBLE; you can customize which folders are synced via regular
expressions, lists, or Python expressions; a versatile and comprehensive
configuration file is used to control behavior; two user interfaces are
built-in; fine-tuning of synchronization performance is possible; internal or
external automation is supported; SSL and PREAUTH tunnels are both supported;
offline (or "unplugged") reading is supported; and esoteric IMAP features are
supported to ensure compatibility with the widest variety of IMAP servers.
OfflineIMAP is SAFE; it uses an algorithm designed to prevent mail loss at all
costs. Because of the design of this algorithm, even programming errors should
not result in loss of mail. I am so confident in the algorithm that I use my
own personal and work accounts for testing of OfflineIMAP pre-release,
development, and beta releases. Of course, legally speaking, OfflineIMAP comes
with no warranty, so I am not responsible if this turns out to be wrong.
Method of Operation
===================
OfflineIMAP traditionally operates by maintaining a hierarchy of mail folders in
Maildir format locally. Your own mail reader will read mail from this tree, and
need never know that the mail comes from IMAP. OfflineIMAP will detect changes
to the mail folders on your IMAP server and your own computer and
bi-directionally synchronize them, copying, marking, and deleting messages as
necessary.
With OfflineIMAP 4.0, a powerful new ability has been introduced ― the program
can now synchronize two IMAP servers with each other, with no need to have a
Maildir layer in-between. Many people use this if they use a mail reader on
their local machine that does not support Maildirs. People may install an IMAP
server on their local machine, and point both OfflineIMAP and their mail reader
of choice at it. This is often preferable to the mail reader's own IMAP support
since OfflineIMAP supports many features (offline reading, for one) that most
IMAP-aware readers don't. However, this feature is not as time-tested as
traditional syncing, so my advice is to stick with normal methods of operation
for the time being.
Quick Start
===========
If you have already installed OfflineIMAP system-wide, or your system
administrator has done that for you, your task for setting up OfflineIMAP for
the first time is quite simple. You just need to set up your configuration
file, make your folder directory, and run it!
You can quickly set up your configuration file. The distribution includes a
file offlineimap.conf.minimal (Debian users may find this at
``/usr/share/doc/offlineimap/examples/offlineimap.conf.minimal``) that is a
basic example of setting of OfflineIMAP. You can simply copy this file into
your home directory and name it ``.offlineimaprc`` (note the leading period). A
command such as ``cp offlineimap.conf.minimal ~/.offlineimaprc`` will do it.
Or, if you prefer, you can just copy this text to ``~/.offlineimaprc``::
[general]
accounts = Test
[Account Test]
localrepository = Local
remoterepository = Remote
[Repository Local]
type = Maildir
localfolders = ~/Test
[Repository Remote]
type = IMAP
remotehost = examplehost
remoteuser = jgoerzen
Now, edit the ``~/.offlineimaprc`` file with your favorite editor. All you have
to do is specify a directory for your folders to be in (on the localfolders
line), the host name of your IMAP server (on the remotehost line), and your
login name on the remote (on the remoteuser line). That's it!
To run OfflineIMAP, you just have to say offlineimap ― it will fire up, ask you
for a login password if necessary, synchronize your folders, and exit. See?
You can just throw away the rest of this finely-crafted, perfectly-honed manual!
Of course, if you want to see how you can make OfflineIMAP FIVE TIMES FASTER FOR
JUST $19.95 (err, well, $0), you have to read on!
Documentation
=============
If you are reading this file on github, you can find more documentations in the
`docs` directory.
Using your git repository, you can generate documentation with::
$ make doc
Mailing list
============
The user discussion, development and all exciting stuff take place in the
`mailing list`_. You're *NOT* supposed to subscribe to send emails.
Reporting bugs and contributions
================================
Bugs
----
Bugs, issues and contributions should be reported to the `mailing list`_.
**Please, don't use the github features (messages, pull requests, etc) at all.
It would most likely be discarded or ignored.**
========
Examples
========
Here are some example configurations for various situations. Please e-mail any
other examples you have that may be useful to me.
Multiple Accounts with Mutt
===========================
This example shows you how to set up OfflineIMAP to synchronize multiple
accounts with the mutt mail reader.
Start by creating a directory to hold your folders by running ``mkdir ~/Mail``.
Then, in your ``~/.offlineimaprc``, specify::
accounts = Personal, Work
Make sure that you have both an [Account Personal] and an [Account Work]
section. The local repository for each account must have different localfolder
path names. Also, make sure to enable [mbnames].
In each local repository section, write something like this::
localfolders = ~/Mail/Personal
Finally, add these lines to your ``~/.muttrc``::
source ~/path-to-mbnames-muttrc-mailboxes
folder-hook Personal set from="youremail@personal.com"
folder-hook Work set from="youremail@work.com"
set mbox_type=Maildir
set folder=$HOME/Mail
spoolfile=+Personal/INBOX
That's it!
UW-IMAPD and References
=======================
Some users with a UW-IMAPD server need to use OfflineIMAP's "reference" feature
to get at their mailboxes, specifying a reference of ``~/Mail`` or ``#mh/``
depending on the configuration. The below configuration from (originally from
docwhat@gerf.org) shows using a reference of Mail, a nametrans that strips the
leading Mail/ off incoming folder names, and a folderfilter that limits the
folders synced to just three::
[Account Gerf]
localrepository = GerfLocal
remoterepository = GerfRemote
[Repository GerfLocal]
type = Maildir
localfolders = ~/Mail
[Repository GerfRemote]
type = IMAP
remotehost = gerf.org
ssl = yes
remoteuser = docwhat
reference = Mail
# Trims off the preceeding Mail on all the folder names.
nametrans = lambda foldername: \
re.sub('^Mail/', '', foldername)
# Yeah, you have to mention the Mail dir, even though it
# would seem intuitive that reference would trim it.
folderfilter = lambda foldername: foldername in [
'Mail/INBOX',
'Mail/list/zaurus-general',
'Mail/list/zaurus-dev',
]
maxconnections = 1
holdconnectionopen = no
pythonfile Configuration File Option
====================================
You can have OfflineIMAP load up a Python file before evaluating the
configuration file options that are Python expressions. This example is based
on one supplied by Tommi Virtanen for this feature.
In ~/.offlineimaprc, he adds these options::
[general]
pythonfile=~/.offlineimap.py
[Repository foo]
foldersort=mycmp
Then, the ~/.offlineimap.py file will contain::
prioritized = ['INBOX', 'personal', 'announce', 'list']
def mycmp(x, y):
for prefix in prioritized:
xsw = x.startswith(prefix)
ysw = y.startswith(prefix)
if xsw and ysw:
return cmp(x, y)
elif xsw:
return -1
elif ysw:
return +1
return cmp(x, y)
def test_mycmp():
import os, os.path
folders=os.listdir(os.path.expanduser('~/data/mail/tv@hq.yok.utu.fi'))
folders.sort(mycmp)
print folders
This code snippet illustrates how the foldersort option can be customized with a
Python function from the pythonfile to always synchronize certain folders first.
Signals
=======
OfflineIMAP writes its current PID into ``~/.offlineimap/pid`` when it is
running. It is not guaranteed that this file will not exist when OfflineIMAP is
not running.
<!-- not done yet
You can send SIGINT to OfflineIMAP using this file to kill it. SIGUSR1 will
force an immediate resync of all accounts. This will be ignored for all
accounts for which a resync is already in progress.
-->

596
SubmittingPatches.rst
View File

@ -1,596 +0,0 @@
.. -*- coding: utf-8 -*-
.. _mailing list: http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project
=================================================
Checklist (and a short version for the impatient)
=================================================
Commits
=======
* make commits of logical units
* check for unnecessary whitespace with ``git diff --check``
before committing
* do not check in commented out code or unneeded files
* the first line of the commit message should be a short
description (50 characters is the soft limit, see DISCUSSION
in git-commit(1)), and should skip the full stop
* the body should provide a meaningful commit message, which:
* uses the imperative, present tense: **change**,
not **changed** or **changes**.
* includes motivation for the change, and contrasts
its implementation with previous behaviour
* add a ``Signed-off-by: Your Name <you@example.com>`` line to the
commit message (or just use the option `-s` when committing)
to confirm that you agree to the **Developer's Certificate of Origin**
* make sure that you have tests for the bug you are fixing
* make sure that the test suite passes after your commit
Patch
=====
* use ``git format-patch -M`` to create the patch
* do not PGP sign your patch
* do not attach your patch, but read in the mail
body, unless you cannot teach your mailer to
leave the formatting of the patch alone.
* be careful doing cut & paste into your mailer, not to
corrupt whitespaces.
* provide additional information (which is unsuitable for
the commit message) between the ``---`` and the diffstat
* if you change, add, or remove a command line option or
make some other user interface change, the associated
documentation should be updated as well.
* if your name is not writable in ASCII, make sure that
you send off a message in the correct encoding.
* send the patch to the `mailing list`_ and the
maintainer (nicolas.s-dev@laposte.net) if (and only if)
the patch is ready for inclusion. If you use `git-send-email(1)`,
please test it first by sending email to yourself.
* see below for instructions specific to your mailer
============
Long version
============
I started reading over the SubmittingPatches document for Git, primarily because
I wanted to have a document similar to it for OfflineIMAP to make sure people
understand what they are doing when they write `Signed-off-by` line.
But the patch submission requirements are a lot more relaxed here on the
technical/contents front, because the OfflineIMAP is a lot smaller ;-). So here
is only the relevant bits.
Decide what to base your work on
================================
In general, always base your work on the oldest branch that your
change is relevant to.
* A bugfix should be based on 'maint' in general. If the bug is not
present in 'maint', base it on 'master'. For a bug that's not yet
in 'master', find the topic that introduces the regression, and
base your work on the tip of the topic.
* A new feature should be based on 'master' in general. If the new
feature depends on a topic that is in 'pu', but not in 'master',
base your work on the tip of that topic.
* Corrections and enhancements to a topic not yet in 'master' should
be based on the tip of that topic. If the topic has not been merged
to 'next', it's alright to add a note to squash minor corrections
into the series.
* In the exceptional case that a new feature depends on several topics
not in 'master', start working on 'next' or 'pu' privately and send
out patches for discussion. Before the final merge, you may have to
wait until some of the dependent topics graduate to 'master', and
rebase your work.
To find the tip of a topic branch, run ``git log --first-parent
master..pu`` and look for the merge commit. The second parent of this
commit is the tip of the topic branch.
Make separate commits for logically separate changes
====================================================
Unless your patch is really trivial, you should not be sending
out a patch that was generated between your working tree and
your commit head. Instead, always make a commit with complete
commit message and generate a series of patches from your
repository. It is a good discipline.
Describe the technical detail of the change(s).
If your description starts to get too long, that's a sign that you
probably need to split up your commit to finer grained pieces.
That being said, patches which plainly describe the things that
help reviewers check the patch, and future maintainers understand
the code, are the most beautiful patches. Descriptions that summarise
the point in the subject well, and describe the motivation for the
change, the approach taken by the change, and if relevant how this
differs substantially from the prior version, can be found on Usenet
archives back into the late 80's. Consider it like good Netiquette,
but for code.
Generate your patch using git tools out of your commits
-------------------------------------------------------
git based diff tools (git, Cogito, and StGIT included) generate
unidiff which is the preferred format.
You do not have to be afraid to use -M option to ``git diff`` or
``git format-patch``, if your patch involves file renames. The
receiving end can handle them just fine.
Please make sure your patch does not include any extra files
which do not belong in a patch submission. Make sure to review
your patch after generating it, to ensure accuracy. Before
sending out, please make sure it cleanly applies to the "master"
branch head. If you are preparing a work based on "next" branch,
that is fine, but please mark it as such.
Sending your patches
====================
People on the mailing list need to be able to read and
comment on the changes you are submitting. It is important for
a developer to be able to "quote" your changes, using standard
e-mail tools, so that they may comment on specific portions of
your code. For this reason, all patches should be submitted
"inline". WARNING: Be wary of your MUAs word-wrap
corrupting your patch. Do not cut-n-paste your patch; you can
lose tabs that way if you are not careful.
It is a common convention to prefix your subject line with
[PATCH]. This lets people easily distinguish patches from other
e-mail discussions. Use of additional markers after PATCH and
the closing bracket to mark the nature of the patch is also
encouraged. E.g. [PATCH/RFC] is often used when the patch is
not ready to be applied but it is for discussion, [PATCH v2],
[PATCH v3] etc. are often seen when you are sending an update to
what you have previously sent.
``git format-patch`` command follows the best current practice to
format the body of an e-mail message. At the beginning of the
patch should come your commit message, ending with the
Signed-off-by: lines, and a line that consists of three dashes,
followed by the diffstat information and the patch itself. If
you are forwarding a patch from somebody else, optionally, at
the beginning of the e-mail message just before the commit
message starts, you can put a "From: " line to name that person.
You often want to add additional explanation about the patch,
other than the commit message itself. Place such "cover letter"
material between the three dash lines and the diffstat.
Do not attach the patch as a MIME attachment, compressed or not.
Do not let your e-mail client send quoted-printable. Do not let
your e-mail client send format=flowed which would destroy
whitespaces in your patches. Many
popular e-mail applications will not always transmit a MIME
attachment as plain text, making it impossible to comment on
your code. A MIME attachment also takes a bit more time to
process. This does not decrease the likelihood of your
MIME-attached change being accepted, but it makes it more likely
that it will be postponed.
Exception: If your mailer is mangling patches then someone may ask
you to re-send them using MIME, that is OK.
Do not PGP sign your patch, at least for now. Most likely, your
maintainer or other people on the list would not have your PGP
key and would not bother obtaining it anyway. Your patch is not
judged by who you are; a good patch from an unknown origin has a
far better chance of being accepted than a patch from a known,
respected origin that is done poorly or does incorrect things.
If you really really really really want to do a PGP signed
patch, format it as "multipart/signed", not a text/plain message
that starts with '-----BEGIN PGP SIGNED MESSAGE-----'. That is
not a text/plain, it's something else.
Unless your patch is a very trivial and an obviously correct one,
first send it with "To:" set to the mailing list, with "cc:" listing
people who are involved in the area you are touching (the output from
"git blame $path" and "git shortlog --no-merges $path" would help to
identify them), to solicit comments and reviews. After the list
reached a consensus that it is a good idea to apply the patch, re-send
it with "To:" set to the maintainer and optionally "cc:" the list for
inclusion. Do not forget to add trailers such as "Acked-by:",
"Reviewed-by:" and "Tested-by:" after your "Signed-off-by:" line as
necessary.
Sign your work
==============
To improve tracking of who did what, we've borrowed the
"sign-off" procedure from the Linux kernel project on patches
that are being emailed around. Although OfflineIMAP is a lot
smaller project it is a good discipline to follow it.
The sign-off is a simple line at the end of the explanation for
the patch, which **certifies that you wrote it or otherwise have
the right to pass it on as a open-source patch**. The rules are
pretty simple: if you can certify the below:
**Developer's Certificate of Origin 1.1**
-----------------------------------------
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
then you just add a line saying
Signed-off-by: Random J Developer <random@developer.example.org>
This line can be automatically added by git if you run the git-commit
command with the -s option.
Notice that you can place your own Signed-off-by: line when
forwarding somebody else's patch with the above rules for
D-C-O. Indeed you are encouraged to do so. Do not forget to
place an in-body "From: " line at the beginning to properly attribute
the change to its true author (see above).
Also notice that a real name is used in the Signed-off-by: line. Please
don't hide your real name.
If you like, you can put extra tags at the end:
* "Reported-by:" is used to to credit someone who found the bug that
the patch attempts to fix.
* "Acked-by:" says that the person who is more familiar with the area
the patch attempts to modify liked the patch.
* "Reviewed-by:", unlike the other tags, can only be offered by the
reviewer and means that she is completely satisfied that the patch
is ready for application. It is usually offered only after a
detailed review.
* "Tested-by:" is used to indicate that the person applied the patch
and found it to have the desired effect.
You can also create your own tag or use one that's in common usage
such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:".
An ideal patch flow
===================
Here is an ideal patch flow for this project the current maintainer
suggests to the contributors:
(0) You come up with an itch. You code it up.
(1) Send it to the list and cc people who may need to know about
the change.
The people who may need to know are the ones whose code you
are butchering. These people happen to be the ones who are
most likely to be knowledgeable enough to help you, but
they have no obligation to help you (i.e. you ask for help,
don't demand). ``git log -p -- $area_you_are_modifying`` would
help you find out who they are.
(2) You get comments and suggestions for improvements. You may
even get them in a "on top of your change" patch form.
(3) Polish, refine, and re-send to the list and the people who
spend their time to improve your patch. Go back to step (2).
(4) The list forms consensus that the last round of your patch is
good. Send it to the list and cc the maintainer.
(5) A topic branch is created with the patch and is merged to 'next',
and cooked further and eventually graduates to 'master'.
In any time between the (2)-(3) cycle, the maintainer may pick it up
from the list and queue it to 'pu', in order to make it easier for
people play with it without having to pick up and apply the patch to
their trees themselves.
Know the status of your patch after submission
----------------------------------------------
* You can use Git itself to find out when your patch is merged in
master. ``git pull --rebase`` will automatically skip already-applied
patches, and will let you know. This works only if you rebase on top
of the branch in which your patch has been merged (i.e. it will not
tell you if your patch is merged in pu if you rebase on top of
master).
.. * Read the git mailing list, the maintainer regularly posts messages
entitled "What's cooking in git.git" and "What's in git.git" giving
the status of various proposed changes.
MUA specific hints
==================
Some of patches I receive or pick up from the list share common
patterns of breakage. Please make sure your MUA is set up
properly not to corrupt whitespaces. Here are two common ones
I have seen:
* Empty context lines that do not have _any_ whitespace.
* Non empty context lines that have one extra whitespace at the
beginning.
One test you could do yourself if your MUA is set up correctly is:
* Send the patch to yourself, exactly the way you would, except
To: and Cc: lines, which would not contain the list and
maintainer address.
* Save that patch to a file in UNIX mailbox format. Call it say
a.patch.
* Try to apply to the tip of the "master" branch from the
git.git public repository::
$ git fetch http://kernel.org/pub/scm/git/git.git master:test-apply
$ git checkout test-apply
$ git reset --hard
$ git am a.patch
If it does not apply correctly, there can be various reasons.
* Your patch itself does not apply cleanly. That is _bad_ but
does not have much to do with your MUA. Please rebase the
patch appropriately.
* Your MUA corrupted your patch; "am" would complain that
the patch does not apply. Look at .git/rebase-apply/ subdirectory and
see what 'patch' file contains and check for the common
corruption patterns mentioned above.
* While you are at it, check what are in 'info' and
'final-commit' files as well. If what is in 'final-commit' is
not exactly what you would want to see in the commit log
message, it is very likely that your maintainer would end up
hand editing the log message when he applies your patch.
Things like "Hi, this is my first patch.\n", if you really
want to put in the patch e-mail, should come after the
three-dash line that signals the end of the commit message.
Pine
----
(Johannes Schindelin)
I don't know how many people still use pine, but for those poor souls it may
be good to mention that the quell-flowed-text is needed for recent versions.
... the "no-strip-whitespace-before-send" option, too. AFAIK it was introduced
in 4.60.
(Linus Torvalds)
And 4.58 needs at least this
::
---
diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1)
Author: Linus Torvalds <torvalds@g5.osdl.org>
Date: Mon Aug 15 17:23:51 2005 -0700
Fix pine whitespace-corruption bug
There's no excuse for unconditionally removing whitespace from
the pico buffers on close.
diff --git a/pico/pico.c b/pico/pico.c
--- a/pico/pico.c
+++ b/pico/pico.c
@@ -219,7 +219,9 @@ PICO *pm;
switch(pico_all_done){ /* prepare for/handle final events */
case COMP_EXIT : /* already confirmed */
packheader();
+#if 0
stripwhitespace();
+#endif
c |= COMP_EXIT;
break;
(Daniel Barkalow)
> A patch to SubmittingPatches, MUA specific help section for
> users of Pine 4.63 would be very much appreciated.
Ah, it looks like a recent version changed the default behavior to do the
right thing, and inverted the sense of the configuration option. (Either
that or Gentoo did it.) So you need to set the
"no-strip-whitespace-before-send" option, unless the option you have is
"strip-whitespace-before-send", in which case you should avoid checking
it.
Thunderbird
-----------
(A Large Angry SCM)
By default, Thunderbird will both wrap emails as well as flag them as
being 'format=flowed', both of which will make the resulting email unusable
by git.
Here are some hints on how to successfully submit patches inline using
Thunderbird.
There are two different approaches. One approach is to configure
Thunderbird to not mangle patches. The second approach is to use
an external editor to keep Thunderbird from mangling the patches.
**Approach #1 (configuration):**
This recipe is current as of Thunderbird 2.0.0.19. Three steps:
1. Configure your mail server composition as plain text
Edit...Account Settings...Composition & Addressing,
uncheck 'Compose Messages in HTML'.
2. Configure your general composition window to not wrap
Edit..Preferences..Composition, wrap plain text messages at 0
3. Disable the use of format=flowed
Edit..Preferences..Advanced..Config Editor. Search for:
mailnews.send_plaintext_flowed
toggle it to make sure it is set to 'false'.
After that is done, you should be able to compose email as you
otherwise would (cut + paste, git-format-patch | git-imap-send, etc),
and the patches should not be mangled.
**Approach #2 (external editor):**
This recipe appears to work with the current [*1*] Thunderbird from Suse.
The following Thunderbird extensions are needed:
AboutConfig 0.5
http://aboutconfig.mozdev.org/
External Editor 0.7.2
http://globs.org/articles.php?lng=en&pg=8
1) Prepare the patch as a text file using your method of choice.
2) Before opening a compose window, use Edit->Account Settings to
uncheck the "Compose messages in HTML format" setting in the
"Composition & Addressing" panel of the account to be used to send the
patch. [*2*]
3) In the main Thunderbird window, _before_ you open the compose window
for the patch, use Tools->about:config to set the following to the
indicated values::
mailnews.send_plaintext_flowed => false
mailnews.wraplength => 0
4) Open a compose window and click the external editor icon.
5) In the external editor window, read in the patch file and exit the
editor normally.
6) Back in the compose window: Add whatever other text you wish to the
message, complete the addressing and subject fields, and press send.
7) Optionally, undo the about:config/account settings changes made in
steps 2 & 3.
[Footnotes]
*1* Version 1.0 (20041207) from the MozillaThunderbird-1.0-5 rpm of Suse
9.3 professional updates.
*2* It may be possible to do this with about:config and the following
settings but I haven't tried, yet::
mail.html_compose => false
mail.identity.default.compose_html => false
mail.identity.id?.compose_html => false
(Lukas Sandström)
There is a script in contrib/thunderbird-patch-inline which can help you
include patches with Thunderbird in an easy way. To use it, do the steps above
and then use the script as the external editor.
Gnus
----
'|' in the *Summary* buffer can be used to pipe the current
message to an external program, and this is a handy way to drive
"git am". However, if the message is MIME encoded, what is
piped into the program is the representation you see in your
*Article* buffer after unwrapping MIME. This is often not what
you would want for two reasons. It tends to screw up non ASCII
characters (most notably in people's names), and also
whitespaces (fatal in patches). Running 'C-u g' to display the
message in raw form before using '|' to run the pipe can work
this problem around.
KMail
-----
This should help you to submit patches inline using KMail.
1) Prepare the patch as a text file.
2) Click on New Mail.
3) Go under "Options" in the Composer window and be sure that
"Word wrap" is not set.
4) Use Message -> Insert file... and insert the patch.
5) Back in the compose window: add whatever other text you wish to the
message, complete the addressing and subject fields, and press send.
Gmail
-----
GMail does not appear to have any way to turn off line wrapping in the web
interface, so this will mangle any emails that you send. You can however
use "git send-email" and send your patches through the GMail SMTP server, or
use any IMAP email client to connect to the google IMAP server and forward
the emails through that.
To use ``git send-email`` and send your patches through the GMail SMTP server,
edit `~/.gitconfig` to specify your account settings::
[sendemail]
smtpencryption = tls
smtpserver = smtp.gmail.com
smtpuser = user@gmail.com
smtppass = p4ssw0rd
smtpserverport = 587
Once your commits are ready to be sent to the mailing list, run the
following commands::
$ git format-patch --cover-letter -M origin/master -o outgoing/
$ edit outgoing/0000-*
$ git send-email outgoing/*
To submit using the IMAP interface, first, edit your `~/.gitconfig` to specify your
account settings::
[imap]
folder = "[Gmail]/Drafts"
host = imaps://imap.gmail.com
user = user@gmail.com
pass = p4ssw0rd
port = 993
sslverify = false
You might need to instead use: folder = "[Google Mail]/Drafts" if you get an error
that the "Folder doesn't exist".
Once your commits are ready to be sent to the mailing list, run the
following commands::
$ git format-patch --cover-letter -M --stdout origin/master | git imap-send
Just make sure to disable line wrapping in the email client (GMail web
interface will line wrap no matter what, so you need to use a real
IMAP client).

127
TODO.rst Normal file
View File

@ -0,0 +1,127 @@
.. vim: spelllang=en ts=2 expandtab :
.. _coding style: https://github.com/OfflineIMAP/offlineimap/blob/next/docs/CodingGuidelines.rst
============================
TODO list by relevance order
============================
Should be the starting point to improve the `coding style`_.
Write your WIP directly in this file.
TODO list
---------
* Better names for variables, objects, etc.
* Improve comments.
Most of the current comments assume a very good
knowledge of the internals. That sucks because I guess nobody is
anymore aware of ALL of them. Time when this was a one guy made
project has long passed.
* Better policy on objects.
- Turn ALL attributes private and use accessors. This is not
"pythonic" but such pythonic thing turn the code into intricated
code.
- Turn ALL methods not intended to be used outside, private.
* Revamp the factorization.
It's not unusual to find "factorized" code
for bad reasons: because it made the code /look/ nicer, but the
factorized function/methods is actually called from ONE place. While it
might locally help, such practice globally defeat the purpose because
we lose the view of what is true factorized code and what is not.
* Namespace the factorized code.
If a method require a local function, DON'T USE yet another method. Use a
local namespaced function.::
class BLah(object):
def _internal_method(self, arg):
def local_factorized(local_arg):
# local_factorized's code
# _internal_method's code.
Python allows local namespaced functions for good reasons.
* Better inheritance policy.
Take the sample of the folder/LocalStatus(SQlite) and folder/Base stuffs. It's
*nearly IMPOSSIBLE* to know and understand what parent method is used by what
child, for what purpose, etc. So, instead of (re)defining methods in the wild,
keep the well common NON-redefined stuff into the parent and define the
required methods in the childs. We really don't want anything like::
def method(self):
raise NotImplemented
While this is common practice in Python, think about that again: how a
parent object should know all the expected methods/accessors of all the
possible kind of childs?
Inheritance is about factorizing, certainly **NOT** about **defining the
interface** of the childs.
* Introduce as many as intermediate inherited objects as required.
Keeping linear inheritance is good because Python sucks at playing
with multiple parents and it keeps things simple. But a parent should
have ALL its methods used in ALL the childs. If not, it's a good
sign that a new intermediate object should be introduced in the
inheritance line.
* Don't blindly inherit from library objects.
We do want **well defined interfaces**. For example, we do too much things
like imapobj.methodcall() while the imapobj is far inherited from imaplib2.
We have NO clue about what we currently use from the library.
Having a dump wrappper for each call should be made mandatory for
objects inherited from a library. Using composed objects should be
seriously considered in this case, instead of using inheritance.
* Use factories.
Current objects do too much initialization stuff varying with the context it
is used. Move things like that into factories and keep the objects definitions
clean.
* Make it clear when we expect a composite object and what we expect
exactly.
Even the more obvious composed objects are badly defined. For example,
the ``conf`` instances are spread across a lot of objects. Did you know
that such composed objects are sometimes restricted to the section the
object works on, and most of the time it's not restricted at all?
How many time it requires to find and understand on what we are
currently working?
* Seriously improve our debugging/hacking sessions (AGAIN).
Until now, we have limited the improvements to allow better/full stack traces.
While this was actually required, we now hit some limitations of the whole
exception-based paradigm. For example, it's very HARD to follow an instance
during its life time. I have a good overview of what we could do in this area,
so don't matter much about that if you don't get the point or what could be
done.
* Support Python 3.
* Support Unicode.

435
contrib/release.sh Executable file
View File

@ -0,0 +1,435 @@
#!/bin/sh
#
# Put into Public Domain, by Nicolas Sebrecht
#
# Create new releases in OfflineIMAP.
# TODO: https://developer.github.com/v3/repos/releases/#create-a-release
# https://developer.github.com/libraries/
# https://github.com/turnkeylinux/octohub
# https://github.com/michaelliao/githubpy (onefile)
# https://github.com/sigmavirus24/github3.py
# https://github.com/copitux/python-github3
# https://github.com/PyGithub/PyGithub
# https://github.com/micha/resty (curl)
# TODO: move configuration out and source it.
# TODO: implement rollback.
__VERSION__='v0.2'
SPHINXBUILD=sphinx-build
MAILING_LIST='offlineimap-project@lists.alioth.debian.org'
DOCSDIR='docs'
ANNOUNCE_MAGIC='#### Notes '
CHANGELOG_MAGIC='{:toc}'
CHANGELOG='Changelog.md'
CACHEDIR='.git/offlineimap-release'
WEBSITE='website'
WEBSITE_LATEST="${WEBSITE}/_data/latest.yml"
TMP_CHANGELOG_EXCERPT="${CACHEDIR}/changelog.excerpt.md"
TMP_CHANGELOG_EXCERPT_OLD="${TMP_CHANGELOG_EXCERPT}.old"
TMP_CHANGELOG="${CACHEDIR}/changelog.md"
TMP_ANNOUNCE="${CACHEDIR}/announce.txt"
True=0
False=1
Yes=$True
No=$False
DEBUG=$True
#
# $1: EXIT_CODE
# $2..: message
function die () {
n=$1
shift
echo $*
exit $n
}
function debug () {
if test $DEBUG -eq $True
then
echo "DEBUG: $*" >&2
fi
}
#
# $1: question
# $2: message on abort
#
function ask () {
echo
echo -n "--- $1 "
read -r ans
test "n$ans" = 'n' -o "n$ans" = 'ny' && return $Yes
test "n$ans" = "ns" -o "n$ans" = 'nn' && return $No
die 1 "! $2"
}
#
# $1: message
# $1: path to file
#
function edit_file () {
ask "Press Enter to $1"
test $? -eq $Yes && {
$EDITOR "$2"
reset
}
}
function fix_pwd () {
debug 'in fix_pwd'
cd "$(git rev-parse --show-toplevel)" || \
die 2 "cannot determine the root of the repository"
}
function prepare_env () {
debug 'in prepare_env'
mkdir "$CACHEDIR" 2>/dev/null
test ! -d "$CACHEDIR" && die 5 "Could not make cache directory $CACHEDIR"
}
function check_dirty () {
debug 'in check_dirty'
git diff --quiet 2>/dev/null && git diff --quiet --cached 2>/dev/null || {
die 4 "Commit all your changes first!"
}
}
function welcome () {
debug 'in welcome'
cat <<EOF
You will be prompted to answer questions.
Answer by:
- 'y' : yes, continue (default)
- '<Enter>' : yes, continue
- 'n' : no
- 's' : skip (ONLY where applicable, otherwise continue)
Any other key will abort the program.
EOF
ask 'Ready?'
}
function checkout_next () {
debug 'in checkout_next'
git checkout --quiet next || {
die 6 "Could not checkout 'next' branch"
}
}
function get_version () {
debug 'in get_version'
echo "v$(./offlineimap.py --version)"
}
function update_offlineimap_version () {
debug 'in update_offlineimap_version'
edit_file 'update the version in __init__.py' offlineimap/__init__.py
}
#
# $1: previous version
#
function get_git_history () {
debug 'in get_git_history'
git log --oneline "${1}.." | sed -r -e 's,^(.),\- \1,'
}
#
# $1: new version
# $2: shortlog
function changelog_template () {
debug 'in changelog_template'
cat <<EOF
// vim: expandtab ts=2 syntax=markdown
// WARNING: let at least one empy line before the real content.
//
// Write a new Changelog entry.
//
// Comments MUST start at the beginning of the lile with two slashes.
// They will by be ignored by the template engine.
//
### OfflineIMAP $1 ($(date +%Y-%m-%d))
#### Notes
// Add some notes. Good notes are about what was done in this release.
// HINT: explain big changes.
#### Features
// Use list syntax with '- '
#### Fixes
// Use list syntax with '- '
#### Changes
// Use list syntax with '- '
// The preformatted shortlog was added below.
// Make use of this to fill the sections 'Features' and 'Fixes' above.
EOF
}
#
# $1: new version
# $2: previous version
#
function update_changelog () {
debug 'in update_changelog'
# Write Changelog excerpt.
if test ! -f "$TMP_CHANGELOG_EXCERPT"
then
changelog_template "$1" > "$TMP_CHANGELOG_EXCERPT"
get_git_history "$2" >> "$TMP_CHANGELOG_EXCERPT"
edit_file "the Changelog excerpt" $TMP_CHANGELOG_EXCERPT
# Remove comments.
grep -v '//' "$TMP_CHANGELOG_EXCERPT" > "${TMP_CHANGELOG_EXCERPT}.nocomment"
mv -f "${TMP_CHANGELOG_EXCERPT}.nocomment" "$TMP_CHANGELOG_EXCERPT"
fi
# Write new Changelog.
cat "$CHANGELOG" > "$TMP_CHANGELOG"
debug "include excerpt $TMP_CHANGELOG_EXCERPT to $TMP_CHANGELOG"
sed -i -e "/${CHANGELOG_MAGIC}/ r ${TMP_CHANGELOG_EXCERPT}" "$TMP_CHANGELOG"
debug 'remove trailing whitespaces'
sed -i -r -e 's, +$,,' "$TMP_CHANGELOG" # Remove trailing whitespaces.
debug "copy to $TMP_CHANGELOG -> $CHANGELOG"
cp -f "$TMP_CHANGELOG" "$CHANGELOG"
# Check and edit Changelog.
ask "Next step: you'll be asked to review the diff of $CHANGELOG"
action=$No
while test ! $action -eq $Yes
do
git diff -- "$CHANGELOG" | less
ask 'edit Changelog?' $CHANGELOG
action=$?
done
}
#
# $1: new version
#
function git_release () {
debug 'in git_release'
git commit -as -m"$1"
git tag -a "$1" -m"$1"
git checkout master
git merge next
git checkout next
}
function get_last_rc () {
git tag | grep -E '^v([0-9][\.-]){3}rc' | sort -n | tail -n1
}
function get_last_stable () {
git tag | grep -E '^v([0-9][\.])+' | grep -v '\-rc' | sort -n | tail -n1
}
function update_website_releases_info() {
cat > "$WEBSITE_LATEST" <<EOF
# DO NOT EDIT MANUALLY: it is generated by a script (release.sh)
stable: $(get_last_stable)
rc: $(get_last_rc)
EOF
}
#
# $1: new version
#
function update_website () {
debug 'in update_website'
ask "update API of the website? (require $SPHINXBUILD)"
if test $? -eq $Yes
then
# Check sphinx is available.
$SPHINXBUILD --version > /dev/null 2>&1
if test ! $? -eq 0
then
echo "Oops! you don't have $SPHINXBUILD installed?"
echo "Cannot update the webite documentation..."
echo "You should install it and run:"
echo " $ cd docs"
echo " $ make websitedoc"
echo "Then, commit and push changes of the website."
ask 'continue'
return
fi
# Check website sources are available.
cd website
if test ! $? -eq 0
then
echo "ERROR: cannot go to the website sources"
ask 'continue'
return
fi
# Stash any WIP in the website sources.
git diff --quiet 2>/dev/null && git diff --quiet --cached 2>/dev/null || {
echo "There is WIP in the website repository, stashing"
echo "git stash create 'WIP during offlineimap API import'"
git stash create 'WIP during offlineimap API import'
ask 'continue'
}
cd .. # Back to offlineimap.git.
update_website_releases_info
cd "./$DOCSDIR" # Enter the docs directory in offlineimap.git.
# Build the docs!
make websitedoc && {
# Commit changes in a branch.
cd ../website # Enter the website sources.
branch_name="import-$1"
git checkout -b "$branch_name"
git add '_doc/versions'
git commit -a -s -m"update for offlineimap $1"
echo "website: branch '$branch_name' ready for a merge in master!"
}
ask 'website updated locally; continue'
fi
}
function git_username () {
git config --get user.name
}
function git_usermail () {
git config --get user.email
}
#
# $1: new version
#
function announce_header () {
cat <<EOF
Message-Id: <$(git log HEAD~1.. --oneline --pretty='%H.%t.release.%ce')>
Date: $(git log HEAD~1.. --oneline --pretty='%cD')
From: $(git_username) <$(git_usermail)>
To: $MAILING_LIST
Subject: [ANNOUNCE] OfflineIMAP $1 released
OfflineIMAP $1 is out.
Downloads:
http://github.com/OfflineIMAP/offlineimap/archive/${1}.tar.gz
http://github.com/OfflineIMAP/offlineimap/archive/${1}.zip
EOF
}
function announce_footer () {
cat <<EOF
--
$(git_username)
EOF
}
#
# $1: new version
# $2: previous version
#
function build_announce () {
announce_header "$1" > "$TMP_ANNOUNCE"
grep -v '^### OfflineIMAP' "$TMP_CHANGELOG_EXCERPT" | \
grep -v '^#### Notes' >> "$TMP_ANNOUNCE"
sed -i -r -e "s,^$ANNOUNCE_MAGIC,," "$TMP_ANNOUNCE"
sed -i -r -e "s,^#### ,# ," "$TMP_ANNOUNCE"
announce_footer >> "$TMP_ANNOUNCE"
}
function edit_announce () {
edit_file 'edit announce' "$TMP_ANNOUNCE"
}
#
# run
#
function run () {
debug 'in run'
fix_pwd
check_dirty
prepare_env
checkout_next
clear
welcome
if test -f "$TMP_CHANGELOG_EXCERPT"
then
head "$TMP_CHANGELOG_EXCERPT"
ask "A previous Changelog excerpt (head above) was found, use it?"
if test ! $? -eq $Yes
then
mv -f "$TMP_CHANGELOG_EXCERPT" "$TMP_CHANGELOG_EXCERPT_OLD"
fi
fi
previous_version="$(get_version)"
message="Safety check: release after version:"
ask "$message $previous_version ?"
update_offlineimap_version
new_version="$(get_version)"
ask "Safety check: make a new release with version: '$new_version'" "Clear changes and restart"
update_changelog "$new_version" "$previous_version"
build_announce "$new_version" "$previous_version"
edit_announce
git_release $new_version
update_website $new_version
}
run
cat <<EOF
Release is ready!
Make your checks and push the changes for both offlineimap and the website.
Announce template stands in '$TMP_ANNOUNCE'.
Have fun! ,-)
EOF
# vim: expandtab ts=2 :

19
contrib/systemd/README.md Normal file
View File

@ -0,0 +1,19 @@
---
layout: page
title: Integrating OfflineIMAP into systemd
author: Ben Boeckel
date: 2015-03-22
contributors: Abdo Roig-Maranges
updated: 2015-03-25
---
<!-- This file is copied to the website by script. -->
## Systemd units
These unit files are meant to be used in the user session. You may drop them into `/etc/systemd/user` or `${XDG_DATA_HOME}/systemd/user` followed by `systemctl --user daemon-reload` to have systemd aware of the unit files.
These files are meant to be triggered either manually using `systemctl --user start offlineimap.service` or by enabling the timer unit using `systemctl --user enable offlineimap.timer`. Additionally, specific accounts may be triggered by using `offlineimap@myaccount.timer` or `offlineimap@myaccount.service`.
These unit files are installed as being enabled via a `mail.target` unit which is intended to be a catch-all for mail-related unit files. A simple `mail.target` file is also provided.

5
contrib/systemd/mail.target Normal file
View File

@ -0,0 +1,5 @@
[Unit]
Description=Mail Target
[Install]
WantedBy=default.target

9
contrib/systemd/offlineimap.service Normal file
View File

@ -0,0 +1,9 @@
[Unit]
Description=Offlineimap Service
[Service]
Type=oneshot
ExecStart=/usr/bin/offlineimap -o
[Install]
WantedBy=mail.target

9
contrib/systemd/offlineimap.timer Normal file
View File

@ -0,0 +1,9 @@
[Unit]
Description=Offlineimap Query Timer
[Timer]
OnUnitInactiveSec=15m
Unit=offlineimap.service
[Install]
WantedBy=mail.target

9
contrib/systemd/offlineimap@.service Normal file
View File

@ -0,0 +1,9 @@
[Unit]
Description=Offlineimap Service for account %i
[Service]
Type=oneshot
ExecStart=/usr/bin/offlineimap -o -a %i
[Install]
WantedBy=mail.target

9
contrib/systemd/offlineimap@.timer Normal file
View File

@ -0,0 +1,9 @@
[Unit]
Description=Offlineimap Query Timer for account %i
[Timer]
OnUnitInactiveSec=15m
Unit=offlineimap@%i.service
[Install]
WantedBy=mail.target

384
docs/FAQ.rst
View File

@ -1,384 +0,0 @@
.. -*- coding: utf-8 -*-
.. NOTE TO MAINTAINERS: Please add new questions to the end of their
sections, so section/question numbers remain stable.
=============================================
OfflineIMAP FAQ (Frequently Asked Questions)
=============================================
:Web site: https://github.com/nicolas33/offlineimap
:Copyright: This document is licensed under GPLv2.
.. contents::
.. sectnum::
This is a work in progress.
Please feel free to ask questions and/or provide answers; send email to the
`mailing list`_.
.. _mailing list: http://lists.alioth.debian.org/mailman/listinfo/offlineimap-project
.. _OfflineIMAP: https://github.com/nicolas33/offlineimap
OfflineIMAP
===========
Where do I get OfflineIMAP?
---------------------------
See the information on the Home page `OfflineIMAP`_.
How fast is it?
---------------
OfflineIMAP has a multithreaded sync, so it should have very nice performance.
OfflineIMAP versions 2.0 and above contain a multithreaded system. A good way
to experiment is by setting maxsyncaccounts to 3 and maxconnections to 3 in
each account clause.
This lets OfflineIMAP open up multiple connections simultaneously. That will
let it process multiple folders and messages at once. In most cases, this will
increase performance of the sync.
Don’t set the number too high. If you do that, things might actually slow down
as your link gets saturated. Also, too many connections can cause mail servers
to have excessive load. Administrators might take unkindly to this, and the
server might bog down. There are many variables in the optimal setting;
experimentation may help.
An informal benchmark yields these results for my setup::
* 10 minutes with MacOS X Mail.app “manual cache”
* 5 minutes with GNUS agent sync
* 20 seconds with OfflineIMAP 1.x
* 9 seconds with OfflineIMAP 2.x
* 3 seconds with OfflineIMAP 3.x “cold start”
* 2 seconds with OfflineIMAP 3.x “held connection”
What platforms does OfflineIMAP support?
----------------------------------------
It should run on most platforms supported by Python, which are quite a few. I
do not support Windows myself, but some have made it work there. Use on
Windows
These answers have been reported by OfflineIMAP users. I do not run OfflineIMAP
on Windows myself, so I can’t directly address their accuracy.
The basic answer is that it’s possible and doesn’t require hacking OfflineIMAP
source code. However, it’s not necessarily trivial. The information below is
based in instructions submitted by Chris Walker.
First, you must run OfflineIMAP in the Cygwin environment. The Windows
filesystem is not powerful enough to accomodate Maildir by itself.
Next, you’ll need to mount your Maildir directory in a special way. There is
information for doing that at http://barnson.org/node/295. That site gives this
example::
mount -f -s -b -o managed "d:/tmp/mail" "/home/of/mail"
That URL also has more details on making OfflineIMAP work with Windows.
Does OfflineIMAP support mbox, mh, or anything else other than Maildir?
-----------------------------------------------------------------------
Not directly. Maildir was the easiest to implement. I’m not planning to write
mbox code for OfflineIMAP, though if someone sent me well-written mbox support
and pledged to support it, I’d commit it to the tree.
However, OfflineIMAP can directly sync accounts on two different IMAP servers
together. So you could install an IMAP server on your local machine that
supports mbox, sync to it, and then instruct your mail readers to use the
mboxes.
Or you could install whatever IMAP server you like on the local machine, and
point your mail readers to that IMAP server on localhost.
What is the UID validity problem for folder?
--------------------------------------------
IMAP servers use a unique ID (UID) to refer to a specific message. This number
is guaranteed to be unique to a particular message forever. No other message in
the same folder will ever get the same UID. UIDs are an integral part of
`OfflineIMAP`_'s synchronization scheme; they are used to match up messages on
your computer to messages on the server.
Sometimes, the UIDs on the server might get reset. Usually this will happen if
you delete and then recreate a folder. When you create a folder, the server
will often start the UID back from 1. But `OfflineIMAP`_ might still have the
UIDs from the previous folder by the same name stored. `OfflineIMAP`_ will
detect this condition and skip the folder. This is GOOD, because it prevents
data loss.
You can fix it by removing your local folder and cache data. For instance, if
your folders are under `~/Folders` and the folder with the problem is INBOX,
you'd type this::
rm -r ~/Folders/INBOX
rm -r ~/.offlineimap/Account-AccountName/LocalStatus/INBOX
rm -r ~/.offlineimap/Repository-RemoteRepositoryName/FolderValidity/INBOX
(Of course, replace AccountName and RemoteRepositoryName with the names as
specified in `~/.offlineimaprc`).
Next time you run `OfflineIMAP`_, it will re-download the folder with the new
UIDs. Note that the procedure specified above will lose any local changes made
to the folder.
Some IMAP servers are broken and do not support UIDs properly. If you continue
to get this error for all your folders even after performing the above
procedure, it is likely that your IMAP server falls into this category.
`OfflineIMAP`_ is incompatible with such servers. Using `OfflineIMAP`_ with
them will not destroy any mail, but at the same time, it will not actually
synchronize it either. (`OfflineIMAP`_ will detect this condition and abort
prior to synchronization.)
This question comes up frequently on the `mailing list`_. You can find a detailed
discussion of the problem there
http://lists.complete.org/offlineimap@complete.org/2003/04/msg00012.html.gz.
How do I add or delete a folder?
--------------------------------
OfflineIMAP does not currently provide this feature. However, if you create a
new folder on the remote server, OfflineIMAP will detect this and create the
corresponding folder locally automatically.
May I delete local folders?
---------------------------
`OfflineIMAP`_ does a two-way synchronization. That is, if you make a change
to the mail on the server, it will be propagated to your local copy, and
vise-versa. Some people might think that it would be wise to just delete all
their local mail folders periodically. If you do this with `OfflineIMAP`_,
remember to also remove your local status cache (`~/.offlineimap` by default).
Otherwise, `OfflineIMAP`_ will take this as an intentional deletion of many
messages and will interpret your action as requesting them to be deleted from
the server as well. (If you don't understand this, don't worry; you probably
won't encounter this situation.)
Can I run multiple instances?
-----------------------------
`OfflineIMAP`_ is not designed to have several instances (for instance, a cron
job and an interactive invocation) run over the same mailbox simultaneously.
It will perform a check on startup and abort if another `OfflineIMAP`_ is
already running. If you need to schedule synchronizations, you'll probably
find autorefresh settings more convenient than cron. Alternatively, you can
set a separate metadata directory for each instance.
Can I copy messages between folders?
---------------------------------------
Normally, when you copy a message between folders or add a new message to a
folder locally, `OfflineIMAP`_ will just do the right thing. However,
sometimes this can be tricky ― if your IMAP server does not provide the SEARCH
command, or does not return something useful, `OfflineIMAP`_ cannot determine
the new UID of the message. So, in these rare instances, OfflineIMAP will
upload the message to the IMAP server and delete it from your local folder.
Then, on your next sync, the message will be re-downloaded with the proper UID.
`OfflineIMAP`_ makes sure that the message was properly uploaded before
deleting it, so there should be no risk of data loss.
Does OfflineIMAP support POP?
-----------------------------
No. POP is not robust enough to do a completely reliable multi-machine sync
like OfflineIMAP can do.
OfflineIMAP will never support POP.
How is OfflineIMAP conformance?
-------------------------------
* Internet Message Access Protocol version 4rev1 (IMAP 4rev1) as specified in
`2060`:RFC: and `3501`:RFC:
* CRAM-MD5 as specified in `2195`:RFC:
* Maildir as specified in the Maildir manpage and the qmail website
* Standard Python 2.6 as implemented on POSIX-compliant systems
Configuration Questions
=======================
Can I synchronize multiple accounts with OfflineIMAP?
-----------------------------------------------------
Of course!
Just name them all in the accounts line in the general section of the
configuration file, and add a per-account section for each one.
You can also optionally use the -a option when you run OfflineIMAP to request
that it only operate upon a subset of the accounts for a particular run.
How do I specify the names of folders?
--------------------------------------
You do not need to. OfflineIMAP is smart enough to automatically figure out
what folders are present on the IMAP server and synchronize them. You can use
the folderfilter and nametrans configuration file options to request only
certain folders and rename them as they come in if you like.
How do I prevent certain folders from being synced?
---------------------------------------------------
Use the folderfilter option.
What is the mailbox name recorder (mbnames) for?
------------------------------------------------
Some mail readers, such as mutt, are not capable of automatically determining the names of your mailboxes. OfflineIMAP can help these programs by writing the names of the folders in a format you specify. See the example offlineimap.conf for details.
IMAP Server Notes
=================
In general, OfflineIMAP works with any IMAP server that provides compatibility
with the IMAP RFCs. Some servers provide imperfect compatibility that may be
good enough for general clients. OfflineIMAP needs more features, specifically
support for UIDs, in order to do its job accurately and completely.
Microsoft Exchange
------------------
Several users have reported problems with Microsoft Exchange servers in
conjunction with OfflineIMAP. This generally seems to be related to the
Exchange servers not properly following the IMAP standards.
Mark Biggers has posted some information to the OfflineIMAP `mailing list`_
about how he made it work.
Other users have indicated that older (5.5) releases of Exchange are so bad
that they will likely not work at all.
I do not have access to Exchange servers for testing, so any problems with it,
if they can even be solved at all, will require help from OfflineIMAP users to
find and fix.
Client Notes
============
What clients does OfflineIMAP work with?
----------------------------------------
Any client that supports Maildir. Popular ones include mutt, Evolution and
KMail. Thunderbird does not have maildir suppport.
With OfflineIMAP’s IMAP-to-IMAP syncing, this can be even wider; see the next
question.
Evolution
---------
OfflineIMAP can work with Evolution. To do so, first configure your OfflineIMAP
account to have sep = / in its configuration. Then, configure Evolution with
the “Maildir-format mail directories” server type. For the path, you will need
to specify the name of the top-level folder inside your OfflineIMAP storage
location. You’re now set!
KMail
-----
At this time, I believe that OfflineIMAP with Maildirs is not compatible with
KMail. KMail cannot work in any mode other than to move all messages out of all
folders immediately, which (besides being annoying and fundamentally broken) is
incompatible with OfflineIMAP.
However, I have made KMail version 3 work well with OfflineIMAP by installing
an IMAP server on my local machine, having OfflineIMAP sync to that, and
pointing KMail at the same server.
Another way to see mails downloaded with offlineimap in KMail (KDE4) is to
create a local folder (e.g. Backup) and then use ``ln -s
localfolders_in_offlineimaprc ~/.kde/share/apps/kmail/mail/.Backup.directory``.
Maybe you have to rebuild the index of the new folder. Works well with KMail
1.11.4 (KDE4.x), offlineimap 6.1.2 and ArchLinux and sep = / in .offlineimaprc.
Mutt
----
* Do I need to use set maildir_trash?
Other IMAP sync programs require you to do this. OfflineIMAP does not. You’ll
get the best results without it, in fact, though turning it on won’t hurt
anything.
* How do I set up mbnames with mutt?
The example offlineimap.conf file has this example. In your offlineimap.conf,
you’ll list this::
[mbnames]
enabled = yes
filename = ~/Mutt/muttrc.mailboxes
header = "mailboxes "
peritem = "+%(accountname)s/%(foldername)s"
sep = " "
footer = "\n"
Then in your ``.muttrc``::
source ~/Mutt/muttrc.mailboxes
You might also want to set::
set mbox_type=Maildir
set folder=$HOME/Maildirpath
The OfflineIMAP manual has a more detailed example for doing this for multiple
accounts.
Miscellaneous Questions
=======================
Why are your Maildir message filenames so long?
-----------------------------------------------
OfflineIMAP has two relevant principles: 1) never modifying your messages in
any way and 2) ensuring 100% reliable synchronizations. In order to do a
reliable sync, OfflineIMAP must have a way to uniquely identify each e-mail.
Three pieces of information are required to do this: your account name, the
folder name, and the message UID. The account name can be calculated from the
path in which your messages are. The folder name can usually be as well, BUT
some mail clients move messages between folders by simply moving the file,
leaving the name intact.
So, OfflineIMAP must store both a message UID and a folder ID. The
folder ID is necessary so OfflineIMAP can detect a message being moved
to a different folder. OfflineIMAP stores the UID (U= number) and an
md5sum of the foldername (FMD5= number) to facilitate this.
What can I do to ensure OfflineIMAP is still running and hasn’t crashed?
------------------------------------------------------------------------
This shell script will restart OfflineIMAP if it has crashed. Sorry, its
written in Korn, so you’ll need ksh, pdksh, or mksh to run it::
#!/bin/ksh
# remove any old instances of this shell script or offlineimap
for pid in $(pgrep offlineimap)
do
if $pid -ne $$
then
kill $pid
fi
done
# wait for compiz (or whatever) to start and setup wifi
sleep 20
# If offlineimap exits, restart it
while true
do
( exec /usr/bin/offlineimap -u Noninteractive.Quiet )
sleep 60 # prevents extended failure condition

97
docs/INSTALL.rst
View File

@ -1,97 +0,0 @@
.. -*- coding: utf-8 -*-
.. _OfflineIMAP: https://github.com/nicolas33/offlineimap
.. contents::
.. sectnum::
=============
Prerequisites
=============
In order to use `OfflineIMAP`_, you need to have these conditions satisfied:
1. Your mail server must support IMAP. Most Internet Service Providers and
corporate networks do, and most operating systems have an IMAP implementation
readily available. A special Gmail mailbox type is available to interface with
Gmail's IMAP front-end.
2. You must have Python version 2.6 or above installed. If you are running on
Debian GNU/Linux, this requirement will automatically be taken care of for you.
If you do not have Python already, check with your system administrator or
operating system vendor; or, download it from the Python website. If you intend
to use the SSL interface, your Python must have been built with SSL support.
3. Have a mail reader that supports the Maildir mailbox format. Most modern
mail readers have this support built-in, so you can choose from a wide variety
of mail servers. This format is also known as the "qmail" format, so any mail
reader compatible with it will work with `OfflineIMAP`_. If you do not have a
mail reader that supports Maildir, you can often install a local IMAP server and
point both `OfflineIMAP`_ and your mail reader at it.
============
Installation
============
You have three options:
1. a system-wide installation with Debian
2. a system-wide installation with other systems
3. a single-user installation. You can checkout the latest version of
`OfflineIMAP`_ from official `OfflineIMAP`_ repository.
System-Wide Installation, Debian
================================
If you are tracking Debian unstable, you may install `OfflineIMAP`_ by simply
running the following command as root::
apt-get install offlineimap
If you are not tracking Debian unstable, download the Debian `.deb` package from
the `OfflineIMAP`_ website and then run ``dpkg -i`` to install the downloaded
package. Then, skip to below. You will type offlineimap to invoke the
program.
System-Wide Installation, Other
===============================
Download the tar.gz version of the package from the website. Then run these
commands, making sure that you are the "root" user first::
tar -zxvf offlineimap_x.y.z.tar.gz
cd offlineimap-x.y.z
python2.2 setup.py install
On some systems, you will need to use python instead of python2.6. Next,
proceed to below. You will type offlineimap to invoke the program.
Single-Account Installation
===========================
Download the tar.gz version of the package from the website. Then run these
commands::
tar -zxvf offlineimap_x.y.z.tar.gz
cd offlineimap-x.y.z
When you want to run `OfflineIMAP`_, you will issue the cd command as above and
then type `./offlineimap.py`; there is no installation step necessary.
=============
Configuration
=============
`OfflineIMAP`_ is regulated by a configuration file that is normally stored in
`~/.offlineimaprc`. `OfflineIMAP`_ ships with a file named `offlineimap.conf`
that you should copy to that location and then edit. This file is vital to
proper operation of the system; it sets everything you need to run
`OfflineIMAP`_. Full documentation for the configuration file is included
within the sample file.
`OfflineIMAP`_ also ships a file named `offlineimap.conf.minimal` that you can
also try. It's useful if you want to get started with the most basic feature
set, and you can read about other features later with `offlineimap.conf`.

280
docs/MANUAL.rst
View File

@ -1,280 +0,0 @@
====================
OfflineIMAP Manual
====================
--------------------------------------------------------
Powerful IMAP/Maildir synchronization and reader support
--------------------------------------------------------
:Author: John Goerzen <jgoerzen@complete.org>
:Date: 2011-01-15
:Copyright: GPL v2
:Manual section: 1
.. TODO: :Manual group:
SYNOPSIS
========
offlineimap [-h|--help]
offlineimap [OPTIONS]
| -1
| -P profiledir
| -a accountlist
| -c configfile
| -d debugtype[,...]
| -f foldername[,...]
| -k [section:]option=value
| -l filename
| -o
| -u interface
DESCRIPTION
===========
Most configuration is done via the configuration file. Nevertheless, there are
a few command-line options that you may set for OfflineIMAP.
OPTIONS
=======
-1 Disable most multithreading operations
Use solely a single-connection sync. This effectively sets the
maxsyncaccounts and all maxconnections configuration file variables to 1.
-P profiledir
Sets OfflineIMAP into profile mode. The program will create profiledir (it
must not already exist). As it runs, Python profiling information about each
thread is logged into profiledir. Please note: This option is present for
debugging and optimization only, and should NOT be used unless you have a
specific reason to do so. It will significantly slow program performance, may
reduce reliability, and can generate huge amounts of data. You must use the
-1 option when you use -P.
-a accountlist
Overrides the accounts option in the general section of the configuration
file. You might use this to exclude certain accounts, or to sync some
accounts that you normally prefer not to. Separate the accounts by commas,
and use no embedded spaces.
-c configfile
Specifies a configuration file to use in lieu of the default,
``~/.offlineimaprc``.
-d debugtype[,...]
Enables debugging for OfflineIMAP. This is useful if you are trying to track
down a malfunction or figure out what is going on under the hood. I suggest
that you use this with -1 to make the results more sensible.
-d requires one or more debugtypes, separated by commas. These define what
exactly will be debugged, and include three options: imap, maildir, and
thread. The imap option will enable IMAP protocol stream and parsing
debugging. Note that the output may contain passwords, so take care to remove
that from the debugging output before sending it to anyone else. The maildir
option will enable debugging for certain Maildir operations. And thread will
debug the threading model.
-f foldername[,foldername]
Only sync the specified folders. The foldernames are the untranslated
foldernames. This command-line option overrides any folderfilter and
folderincludes options in the configuration file.
-k [section:]option=value
Override configuration file option. If "section" is omitted, it defaults to
general. Any underscores "_" in the section name are replaced with spaces:
for instance, to override option autorefresh in the "[Account Personal]"
section in the config file one would use "-k Account_Personal:autorefresh=30".
You may give more than one -k on the command line if you wish.
-l filename
Enables logging to filename. This will log everything that goes to the screen
to the specified file. Additionally, if any debugging is specified with -d,
then debug messages will not go to the screen, but instead to the logfile
only.
-o Run only once,
ignoring all autorefresh settings in the configuration file.
-q Run only quick synchronizations.
Ignore any flag updates on IMAP servers.
-h|--help Show summary of options.
-u interface
Specifies an alternative user interface module to use. This overrides the
default specified in the configuration file. The pre-defined options are
listed in the User Interfaces section.
User Interfaces
===============
OfflineIMAP has a pluggable user interface system that lets you choose how the
program communicates information to you. There are two graphical interfaces,
two terminal interfaces, and two noninteractive interfaces suitable for
scripting or logging purposes. The ui option in the configuration file
specifies user interface preferences. The -u command-line option can override
the configuration file setting. The available values for the configuration file
or command-line are described in this section.
Curses.Blinkenlights
--------------------
Curses.Blinkenlights is an interface designed to be sleek, fun to watch, and
informative of the overall picture of what OfflineIMAP is doing. I consider it
to be the best general-purpose interface in OfflineIMAP.
Curses.Blinkenlights contains a row of "LEDs" with command buttons and a log.
The log shows more detail about what is happening and is color-coded to match
the color of the lights.
Each light in the Blinkenlights interface represents a thread of execution --
that is, a particular task that OfflineIMAP is performing right now. The colors
indicate what task the particular thread is performing, and are as follows:
* Black:
indicates that this light's thread has terminated; it will light up again
later when new threads start up. So, black indicates no activity.
* Red (Meaning 1):
is the color of the main program's thread, which basically does nothing but
monitor the others. It might remind you of HAL 9000 in 2001.
* Gray:
indicates that the thread is establishing a new connection to the IMAP
server.
* Purple:
is the color of an account synchronization thread that is monitoring the
progress of the folders in that account (not generating any I/O).
* Cyan:
indicates that the thread is syncing a folder.
* Green:
means that a folder's message list is being loaded.
* Blue:
is the color of a message synchronization controller thread.
* Orange:
indicates that an actual message is being copied. (We use fuchsia for fake
messages.)
* Red (meaning 2):
indicates that a message is being deleted.
* Yellow / bright orange:
indicates that message flags are being added.
* Pink / bright red:
indicates that message flags are being removed.
* Red / Black Flashing:
corresponds to the countdown timer that runs between synchronizations.
The name of this interfaces derives from a bit of computer history. Eric
Raymond's Jargon File defines blinkenlights, in part, as:
Front-panel diagnostic lights on a computer, esp. a dinosaur. Now that
dinosaurs are rare, this term usually refers to status lights on a modem,
network hub, or the like.
This term derives from the last word of the famous blackletter-Gothic sign in
mangled pseudo-German that once graced about half the computer rooms in the
English-speaking world. One version ran in its entirety as follows:
| ACHTUNG! ALLES LOOKENSPEEPERS!
|
| Das computermachine ist nicht fuer gefingerpoken und mittengrabben.
| Ist easy schnappen der springenwerk, blowenfusen und poppencorken
| mit spitzensparken. Ist nicht fuer gewerken bei das dumpkopfen.
| Das rubbernecken sichtseeren keepen das cotten-pickenen hans in das
| pockets muss; relaxen und watchen das blinkenlichten.
TTY.TTYUI
---------
TTY.TTYUI interface is for people running in basic, non-color terminals. It
prints out basic status messages and is generally friendly to use on a console
or xterm.
Noninteractive.Basic
--------------------
Noninteractive.Basic is designed for situations in which OfflineIMAP will be run
non-attended and the status of its execution will be logged. You might use it,
for instance, to have the system run automatically and e-mail you the results of
the synchronization. This user interface is not capable of reading a password
from the keyboard; account passwords must be specified using one of the
configuration file options.
Noninteractive.Quiet
--------------------
Noninteractive.Quiet is designed for non-attended running in situations where
normal status messages are not desired. It will output nothing except errors
and serious warnings. Like Noninteractive.Basic, this user interface is not
capable of reading a password from the keyboard; account passwords must be
specified using one of the configuration file options.
Machine.MachineUI
-----------------
Machine.MachineUI generates output in a machine-parsable format. It is designed
for other programs that will interface to OfflineIMAP.
KNOWN BUGS
==========
* SSL3 write pending:
users enabling SSL may hit a bug about "SSL3 write pending". If so, the
account(s) will stay unsynchronised from the time the bug appeared. Running
OfflineIMAP again can help. We are still working on this bug. Patches or
detailed bug reports would be appreciated. Please check you're running the
last stable version and send us a report to the mailing list including the
full log.
SEE ALSO
========

32
docs/Makefile
View File

@ -5,22 +5,38 @@ SOURCES = $(wildcard *.rst)
HTML_TARGETS = $(patsubst %.rst,%.html,$(SOURCES)) HTML_TARGETS = $(patsubst %.rst,%.html,$(SOURCES))
RM = rm RM = rm
RST2HTML=`type rst2html 2>/dev/null 2>&1 && echo rst2html || echo rst2html.py` RST2HTML=`type rst2html >/dev/null 2>&1 && echo rst2html || echo rst2html.py`
RST2MAN=`type rst2man 2>/dev/null 2>&1 && echo rst2man || echo rst2man.py` RST2MAN=`type rst2man >/dev/null 2>&1 && echo rst2man || echo rst2man.py`
SPHINXBUILD = sphinx-build
all: html docs: man api
html: $(HTML_TARGETS) html: $(HTML_TARGETS)
$(HTML_TARGETS): %.html : %.rst $(HTML_TARGETS): %.html : %.rst
$(RST2HTML) $? $@ $(RST2HTML) $? $@
man: offlineimap.1 man: offlineimap.1 offlineimapui.7
offlineimap.1: MANUAL.rst offlineimap.1: offlineimap.txt
$(RST2MAN) MANUAL.rst offlineimap.1 a2x -v -f manpage $?
cp -f offlineimap.1 ..
offlineimapui.7: offlineimapui.txt
a2x -v -f manpage $?
api:
$(SPHINXBUILD) -b html -d html/doctrees doc-src html
websitedoc:
./website-doc.sh releases
./website-doc.sh api
./website-doc.sh contrib
clean: clean:
$(RM) -f $(HTML_TARGETS) $(RM) -f $(HTML_TARGETS)
$(RM) -f offlineimap.1 ../offlineimap.1 $(RM) -f offlineimap.1
$(RM) -f offlineimap.7
$(RM) -rf html/*
-find ./docs -name '*.html' -exec rm -f {} \;
.PHONY: clean doc

26
docs/UPGRADE.rst
View File

@ -1,26 +0,0 @@
Upgrading to 4.0
----------------
If you are upgrading from a version of OfflineIMAP prior to 3.99.12, you will
find that you will get errors when OfflineIMAP starts up (relating to
ConfigParser or AccountHashGenerator) and the configuration file. This is
because the config file format had to change to accommodate new features in 4.0.
Fortunately, it's not difficult to adjust it to suit.
First thing you need to do is stop any running OfflineIMAP instance, making sure
first that it's synced all your mail. Then, modify your `~/.offlineimaprc` file.
You'll need to split up each account section (make sure that it now starts with
"Account ") into two Repository sections (one for the local side and another for
the remote side.) See the files offlineimap.conf.minimal and offlineimap.conf
in the distribution if you need more assistance.
OfflineIMAP's status directory area has also changed. Therefore, you should
delete everything in `~/.offlineimap` as well as your local mail folders.
When you start up OfflineIMAP 4.0, it will re-download all your mail from the
server and then you can continue using it like normal.

86
docs/doc-src/API.rst Normal file
View File

@ -0,0 +1,86 @@
.. OfflineImap API documentation
.. currentmodule:: offlineimap
.. _API docs:
:mod:`offlineimap's` API documentation
======================================
Within :mod:`offlineimap`, the classes :class:`OfflineImap` provides the
high-level functionality. The rest of the classes should usually not needed to
be touched by the user. Email repositories are represented by a
:class:`offlineimap.repository.Base.BaseRepository` or derivatives (see
:mod:`offlineimap.repository` for details). A folder within a repository is
represented by a :class:`offlineimap.folder.Base.BaseFolder` or any derivative
from :mod:`offlineimap.folder`.
This page contains the main API overview of OfflineImap |release|.
OfflineImap can be imported as::
from offlineimap import OfflineImap
:mod:`offlineimap` -- The OfflineImap module
=============================================
.. module:: offlineimap
.. autoclass:: offlineimap.OfflineImap(cmdline_opts = None)
:members:
:inherited-members:
:undoc-members:
:private-members:
:class:`offlineimap.account`
============================
An :class:`accounts.Account` connects two email repositories that are to be
synced. It comes in two flavors, normal and syncable.
.. autoclass:: offlineimap.accounts.Account
.. autoclass:: offlineimap.accounts.SyncableAccount
:members:
:inherited-members:
.. autodata:: ui
Contains the current :mod:`offlineimap.ui`, and can be used for logging etc.
:exc:`OfflineImapError` -- A Notmuch execution error
--------------------------------------------------------
.. autoexception:: offlineimap.error.OfflineImapError
:members:
This exception inherits directly from :exc:`Exception` and is raised
on errors during the offlineimap execution. It has an attribute
`severity` that denotes the severity level of the error.
:mod:`offlineimap.globals` -- module with global variables
==========================================================
Module `offlineimap.globals` provides the read-only storage
for the global variables.
All exported module attributes can be set manually, but this practice
is highly discouraged and shouldn't be used.
However, attributes of all stored variables can only be read, write
access to them is denied.
Currently, we have only :attr:`options` attribute that holds
command-line options as returned by OptionParser.
The value of :attr:`options` must be set by :func:`set_options`
prior to its first use.
.. automodule:: offlineimap.globals
:members:
.. data:: options
You can access the values of stored options using the usual
syntax, offlineimap.globals.options.<option-name>

201
docs/doc-src/conf.py Normal file
View File

@ -0,0 +1,201 @@
# -*- coding: utf-8 -*-
#
# pyDNS documentation build configuration file, created by
# sphinx-quickstart on Tue Feb 2 10:00:47 2010.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys, os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('../..'))
from offlineimap import __version__, __bigversion__, __author__, __copyright__
# -- General configuration -----------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest',
'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.viewcode']
autoclass_content = "both"
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'OfflineIMAP'
copyright = __copyright__
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = __version__
# The full version, including alpha/beta/rc tags.
release = __bigversion__
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of documents that shouldn't be included in the build.
#unused_docs = []
# List of directories, relative to source directory, that shouldn't be searched
# for source files.
exclude_trees = []
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
add_module_names = False
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. Major themes that come with
# Sphinx are currently 'default' and 'sphinxdoc'.
html_theme = 'default'
#html_style = ''
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
#html_static_path = ['html']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
html_use_modindex = False
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = ''
# Output file base name for HTML help builder.
htmlhelp_basename = 'dev-doc'
# -- Options for LaTeX output --------------------------------------------------
# The paper size ('letter' or 'a4').
#latex_paper_size = 'letter'
# The font size ('10pt', '11pt' or '12pt').
#latex_font_size = '10pt'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'offlineimap.tex', u'OfflineIMAP Documentation',
u'OfflineIMAP contributors', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# Additional stuff for the LaTeX preamble.
#latex_preamble = ''
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_use_modindex = True
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'http://docs.python.org/': None}

69
docs/doc-src/dco.rst Normal file
View File

@ -0,0 +1,69 @@
.. _dco
Developer's Certificate of Origin
=================================
v1.1::
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
Then, you just add a line saying::
Signed-off-by: Random J Developer <random@developer.example.org>
This line can be automatically added by git if you run the git-commit command
with the ``-s`` option. Signing can made be afterword with ``--amend -s``.
Notice that you can place your own ``Signed-off-by:`` line when forwarding
somebody else's patch with the above rules for D-C-O. Indeed you are encouraged
to do so. Do not forget to place an in-body ``From:`` line at the beginning to
properly attribute the change to its true author (see above).
Also notice that a real name is used in the ``Signed-off-by:`` line. Please
don't hide your real name.
If you like, you can put extra tags at the end:
Reported-by
is used to to credit someone who found the bug that the patch attempts to fix.
Acked-by
says that the person who is more familiar with the area the patch attempts to
modify liked the patch.
Reviewed-by
unlike the other tags, can only be offered by the reviewer and means that she
is completely satisfied that the patch is ready for application. It is
usually offered only after a detailed review.
Tested-by
is used to indicate that the person applied the patch and found it to have the
desired effect.
You can also create your own tag or use one that's in common usage such as
``Thanks-to:``, ``Based-on-patch-by:``, or ``Mentored-by:``.

21
docs/doc-src/index.rst Normal file
View File

@ -0,0 +1,21 @@
.. OfflineImap documentation master file
.. _OfflineIMAP: http://offlineimap.org
Welcome to OfflineIMAP's developer documentation
================================================
**License**
:doc:`dco` (dco)
**Documented APIs**
.. toctree::
API
repository
ui
.. moduleauthor:: John Goerzen, and many others. See AUTHORS and the git history for a full list.
:License: This module is covered under the GNU GPL v2 (or later).

68
docs/doc-src/repository.rst Normal file
View File

@ -0,0 +1,68 @@
.. currentmodule:: offlineimap.repository
:mod:`offlineimap.repository` -- Email repositories
------------------------------------------------------------
A derivative of class
:class:`Base.BaseRepository` represents an email
repository depending on the type of storage, possible options are:
* :class:`IMAPRepository`,
* :class:`MappedIMAPRepository`
* :class:`GmailRepository`,
* :class:`MaildirRepository`, or
* :class:`LocalStatusRepository`.
Which class you need depends on your account
configuration. The helper class :class:`offlineimap.repository.Repository` is
an *autoloader*, that returns the correct class depending
on your configuration. So when you want to instanciate a new
:mod:`offlineimap.repository`, you will mostly do it through this class.
.. autoclass:: offlineimap.repository.Repository
:members:
:inherited-members:
:mod:`offlineimap.repository.Base.BaseRepository` -- Representation of a mail repository
------------------------------------------------------------------------------------------
.. autoclass:: offlineimap.repository.Base.BaseRepository
:members:
:inherited-members:
:undoc-members:
.. .. note:: :meth:`foo`
.. .. attribute:: Database.MODE
Defines constants that are used as the mode in which to open a database.
MODE.READ_ONLY
Open the database in read-only mode
MODE.READ_WRITE
Open the database in read-write mode
.. autoclass:: offlineimap.repository.IMAPRepository
.. autoclass:: offlineimap.repository.MappedIMAPRepository
.. autoclass:: offlineimap.repository.GmailRepository
.. autoclass:: offlineimap.repository.MaildirRepository
.. autoclass:: offlineimap.repository.LocalStatusRepository
:mod:`offlineimap.folder` -- Basic representation of a local or remote Mail folder
---------------------------------------------------------------------------------------------------------
.. autoclass:: offlineimap.folder.Base.BaseFolder
:members:
:inherited-members:
:undoc-members:
.. .. attribute:: Database.MODE
Defines constants that are used as the mode in which to open a database.
MODE.READ_ONLY
Open the database in read-only mode
MODE.READ_WRITE
Open the database in read-write mode

30
docs/doc-src/ui.rst Normal file
View File

@ -0,0 +1,30 @@
:mod:`offlineimap.ui` -- A flexible logging system
--------------------------------------------------------
.. currentmodule:: offlineimap.ui
OfflineImap has various ui systems, that can be selected. They offer various
functionalities. They must implement all functions that the
:class:`offlineimap.ui.UIBase` offers. Early on, the ui must be set using
:meth:`getglobalui`
.. automethod:: offlineimap.ui.setglobalui
.. automethod:: offlineimap.ui.getglobalui
Base UI plugin
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. autoclass:: offlineimap.ui.UIBase.UIBase
:members:
:inherited-members:
.. .. note:: :meth:`foo`
.. .. attribute:: Database.MODE
Defines constants that are used as the mode in which to open a database.
MODE.READ_ONLY
Open the database in read-only mode
MODE.READ_WRITE
Open the database in read-write mode

425
docs/offlineimap.txt Normal file
View File

@ -0,0 +1,425 @@
offlineimap(1)
==============
NAME
----
offlineimap - Synchronize mailboxes and Maildirs
SYNOPSIS
--------
[verse]
'offlineimap' (options)
DESCRIPTION
-----------
Synchronize the accounts configured in the configuration file via IMAP. Each
account has two sides.
One of the side must be an IMAP server.
The other side can either be a Maildir or another IMAP server.
OPTIONS
-------
-h::
--help::
Display summary of options.
--version::
Output version.
--dry-run::
Run in dry run mode.
+
Do not actually modify any store but check and print what synchronization
actions would be taken if a sync would be performed. It will not precisely
give the exact information what will happen. If e.g. we need to create a
folder, it merely outputs 'Would create folder X', but not how many and which
mails it would transfer.
--info::
Output information on the configured email repositories.
+
Useful for debugging and bug reporting. Use in conjunction with the -a option
to limit the output to a single account. This mode will prevent any actual
sync to occur and exits after it outp ut the debug information.
-1::
Limit multithreading operations and run solely a single-thread sync.
+
This effectively sets the maxsyncaccounts and all maxconnections configuration
file variables to 1. This is 1, the number.
-P <directory>::
Set OfflineIMAP into profile mode.
+
The program will create DIR (it must not already exist). As it runs, Python
profiling information about each thread is logged into profiledir. Please
note: This option is present for debugging and optimization only, and should
NOT be used unless you have a specific reason to do so. It will significantly
decrease program performance, may reduce reliability, and can generate huge
amounts of data. This option implies the -1 option.
-a <account1[,account2[,...]]>::
Overrides the accounts section in the config file.
+
Allows to specify a particular account or set of accounts to sync without
having to edit the config file.
-c <path/to/configuration_file>::
Specifies a configuration file to use.
-d <type1[,type2[,...]]>::
Enables debugging for OfflineIMAP.
+
This is useful if you are to track down a malfunction or figure out what is
going on under the hood. This option requires one or more debugtypes,
separated by commas. These define what exactly will be debugged, and so far
include two options: imap, thread, maildir or ALL. The imap option will enable
IMAP protocol stream and parsing debugging. Note that the output may contain
passwords, so take care to remove that from the debugging output before
sending it to anyone else. The maildir option will enable debugging for
certain Maildir operations. The use of any debug option (unless 'thread' is
included), implies the single-thread option -1.
-l <path/to/file.log>::
Send logs to <file.log>.
-f <folder1[,folder1[,...]]>::
Only sync the specified folders.
+
The folder names are the untranslated foldernames of the remote repository.
This command-line option overrides any 'folderfilter' and 'folderincludes'
options in the configuration file.
-k <[section:]option=value::
Override any configuration file option.
+
If "section" is omitted, it defaults to "general". Any underscores in the
section name are replaced with spaces: for instance, to override option
"autorefresh" in the "[Account Personal]" section in the config file one would
use "-k Account_Personal:autorefresh=30". Repeat this option as much as
necessary to redefine multiple options.
-o::
Run only once.
+
Ignore any autorefresh setting in the configuration file.
-q::
Run only quick synchronizations.
+
Ignore any flag updates on IMAP servers. If a flag on the remote IMAP changes,
and we have the message locally, it will be left untouched in a quick run. This
option is ignored if maxage is set.
-u <UI>::
Specifies an alternative user interface to use.
+
This overrides the default specified in the configuration file. The UI
specified with -u will be forced to be used, even if checks determine that it
is not usable. Possible interface choices are: quiet, basic, ttyui,
blinkenlights, machineui.
--column[=<options>]::
--no-column::
Display branch listing in columns. See configuration variable
column.branch for option syntax.`--column` and `--no-column`
without options are equivalent to 'always' and 'never' respectively.
+
This option is only applicable in non-verbose mode.
Synchronization Performance
---------------------------
By default, we use fairly conservative settings that are safe for syncing but
that might not be the best performing one. Once you got everything set up and
running, you might want to look into speeding up your synchronization. Here
are a couple of hints and tips on how to achieve this.
1. Use maxconnections > 1.
+
By default we only use one connection to an IMAP server. Using 2 or even 3
speeds things up considerably in most cases. This setting goes into the
[Repository XXX] section.
2. Use folderfilters.
+
The quickest sync is a sync that can ignore some folders. I sort my inbox into
monthly folders, and ignore every folder that is more than 2-3 months old,
this lets me only inspect a fraction of my Mails on every sync. If you haven't
done this yet, do it :). See the folderfilter section the example
offlineimap.conf.
3. The cache.
+
The default status cache is a plain text file that will write out the complete
file for each single new message (or even changed flag) to a temporary file.
If you have plenty of files in a folder, this is a few hundred kilo to
megabytes for each mail and is bound to make things slower. I recommend to use
the sqlite backend for that. See the status_backend = sqlite setting in the
example offlineimap.conf. You will need to have python-sqlite installed in
order to use this. This will save you plenty of disk activity. Do note that
the sqlite backend is still considered experimental as it has only been
included recently (although a loss of your status cache should not be a
tragedy as that file can be rebuilt automatically)
4. Use quick sync.
+
A regular sync will request all flags and all UIDs of all mails in each folder
which takes quite some time. A 'quick' sync only compares the number of
messages in a folder on the IMAP side (it will detect flag changes on the
Maildir side of things though). A quick sync on my smallish account will take
7 seconds rather than 40 seconds. Eg, I run a cron script that does a regular
sync once a day, and does quick syncs (-q) only synchronizing the "-f INBOX"
in between.
5. Turn off fsync.
+
In the [general] section you can set fsync to True or False. If you want to
play 110% safe and wait for all operations to hit the disk before continueing,
you can set this to True. If you set it to False, you lose some of that
safety, trading it for speed.
Upgrading from plain text to SQLite cache format
------------------------------------------------
OfflineImap uses a cache to store the last know status of mails (flags etc).
Historically that has meant plain text files, but recently we introduced
sqlite-based cache, which helps with performance and CPU usage on large
folders. Here is how to upgrade existing plain text cache installations to
sqlite based one:
1. Sync to make sure things are reasonably similar.
2. Change the account section to "status_backend = sqlite".
3. Run a new sync.
+
This will convert your plain text cache to an sqlite cache (but leave
the old plain text cache around for easy reverting). This must be quick and
not involve any mail up/downloading.
4. See if it works! :-)
5. If it does not work, go back to the old version or set "status_backend = plain"
6. Delete the old text cache files.
Once you are sure it works, you can delete the
~/.offlineimap/Account-foo/LocalStatus folder (the new cache will be in the
LocalStatus-sqlite folder)
Security and SSL
----------------
By default, OfflineIMAP will connect using any method that 'openssl' supports,
that is SSLv2, SSLv3, or TLSv1.
Do note that SSLv2 is notoriously insecure and deprecated. Unfortunately,
python2 does not offer easy ways to disable SSLv2. It is recommended you test
your setup and make sure that the mail server does not use an SSLv2
connection. Use e.g. "openssl s_client -host mail.server -port 443" to find
out the connection that is used by default.
* Certificate checking
+
Unfortunately, by default we will not verify the certificate of an IMAP
TLS/SSL server we connect to, so connecting by SSL is no guarantee against
man-in-the-middle attacks. While verifying a server certificate fingerprint is
being planned, it is not implemented yet. There is currently only one safe way
to ensure that you connect to the correct server in an encrypted manner: you
can specify a 'sslcacertfile' setting in your repository section of
offlineimap.conf pointing to a file that contains (among others) a CA
Certificate in PEM format which validating your server certificate. In this
case, we will check that:
1. The server SSL certificate is validated by the CA Certificate.
2. The server host name matches the SSL certificate.
3. The server certificate is not past its expiration date.
The FAQ has an entry on how to create your own certificate and CA certificate.
* StartTLS
+
If you have not configured your account to connect via SSL anyway, OfflineImap
will still attempt to set up an SSL connection via the STARTTLS function, in
case the imap server supports it.
+
There is no certificate or fingerprint checking involved at all, when using
STARTTLS (the underlying imaplib library does not support this yet). This
means that you will be protected against passively listening eavesdroppers and
they will not be able to see your password or email contents. However, this
will not protect you from active attacks, such as Man-In-The-Middle attacks
which cause you to connect to the wrong server and pretend to be your mail
server.
+
DO NOT RELY ON STARTTLS AS A SAFE CONNECTION GUARANTEEING THE AUTHENTICITY OF
YOUR IMAP SERVER!
Unix Signals
------------
OfflineImap listens to the unix signals SIGUSR1, SIGUSR2, SIGTERM, SIGINT,
SIGHUP, SIGQUIT.
* If sent a SIGUSR1 it will abort any current (or next future) sleep of all
accounts that are configured to "autorefresh". In effect, this will trigger a
full sync of all accounts to be performed as soon as possible.
* If sent a SIGUSR2, it will stop "autorefresh mode" for all accounts. That
is, accounts will abort any current sleep and will exit after a currently
running synchronization has finished. This signal can be used to gracefully
exit out of a running offlineimap "daemon".
* SIGTERM, SIGINT, SIGHUP are all treated to gracefully terminate as soon as
possible. This means it will finish syncing the current folder in each
account, close keep alive connections, remove locks on the accounts and exit.
+
It may take up to 10 seconds, if autorefresh option is used.
* If sent SIGQUIT, dumps stack traces for all threads and tries to dump
process core.
Known Issues
------------
* SSL3 write pending.
+
Users enabling SSL may hit a bug about "SSL3 write pending". If so, the
account(s) will stay unsynchronised from the time the bug appeared. Running
OfflineIMAP again can help. We are still working on this bug. Patches or
detailed bug reports would be appreciated. Please check you're running the
last stable version and send us a report to the mailing list including the
full log.
* IDLE support is incomplete and experimental. Bugs may be encountered.
- No hook exists for "run after an IDLE response".
+
Email will show up, but may not be processed until the next refresh cycle.
- nametrans may not be supported correctly.
- IMAP IDLE <-> IMAP IDLE doesn't work yet.
- IDLE may only work "once" per refresh.
+
If you encounter this bug, please send a report to the list!
* Maildir support in Windows drive.
+
Maildir uses colon caracter (:) in message file names. Colon is however
forbidden character in windows drives. There are several workarounds for that
situation:
. Enable file name character translation in windows registry (not tested).
- <http://support.microsoft.com/kb/289627>
. Use cygwin managed mount (not tested).
- not available anymore since cygwin 1.7
. Use "maildir-windows-compatible = yes" account OfflineIMAP configuration.
- That makes OfflineIMAP to use exclamation mark (!) instead of colon for
storing messages. Such files can be written to windows partitions. But
you will probably loose compatibility with other programs trying to
read the same Maildir.
+
- Exclamation mark was chosen because of the note in
http://docs.python.org/library/mailbox.html
+
- If you have some messages already stored without this option, you will
have to re-sync them again
* OfflineIMAP confused after system suspend.
+
When resuming a suspended session, OfflineIMAP does not cleanly handles the
broken socket(s) if socktimeout option is not set.
You should enable this option with a value like 10.
* OfflineIMAP confused when mails change while in a sync.
+
When OfflineIMAP is syncing, some events happening since the invokation on
remote or local side are badly handled. OfflineIMAP won't track for changes
during the sync.
* Sharing a maildir with multiple IMAP servers.
+
Generally a word of caution mixing IMAP repositories on the same Maildir root.
You have to be careful that you *never* use the same maildir folder for 2 IMAP
servers. In the best case, the folder MD5 will be different, and you will get
a loop where it will upload your mails to both servers in turn (infinitely!)
as it thinks you have placed new mails in the local Maildir. In the worst
case, the MD5 is the same (likely) and mail UIDs overlap (likely too!) and it
will fail to sync some mails as it thinks they are already existent.
+
I would create a new local Maildir Repository for the Personal Gmail and
use a different root to be on the safe side here. You could e.g. use
`~/mail/Pro` as Maildir root for the ProGmail and
`~/mail/Personal` as root for the personal one.
+
If you then point your local mutt, or whatever MUA you use to `~/mail/`
as root, it should still recognize all folders.
* Edge cases with maxage causing too many messages to be synced.
+
All messages from at most maxage days ago (+/- a few hours, depending on
timezones) are synced, but there are cases in which older messages can also be
synced. This happens when a message's UID is significantly higher than those of
other messages with similar dates, e.g. when messages are added to the local
folder behind offlineimap's back, causing them to get assigned a new UID, or
when offlineimap first syncs a pre-existing Maildir. In the latter case, it
could appear as if a noticeable and random subset of old messages are synced.
Main authors
------------
John Goerzen, Sebastian Spaetz, Eygene Ryabinkin, Nicolas Sebrecht.
See Also
--------
offlineimapui(7), openssl(1), signal(7), sqlite3(1).
http://offlineimap.org

140
docs/offlineimapui.txt Normal file
View File

@ -0,0 +1,140 @@
offlineimapui(7)
================
NAME
----
offlineimapui - The User Interfaces
DESCRIPTION
-----------
OfflineIMAP comes with differents UI, each aiming its own purpose.
TTYUI
------
TTYUI interface is for people running in terminals. It prints out basic
status messages and is generally friendly to use on a console or xterm.
Basic
------
Basic is designed for situations in which OfflineIMAP will be run non-attended
and the status of its execution will be logged.
+
This user interface is not capable of reading a password from the keyboard;
account passwords must be specified using one of the configuration file
options. For example, it will not print periodic sleep announcements and tends
to be a tad less verbose, in general.
Blinkenlights
-------------
Blinkenlights is an interface designed to be sleek, fun to watch, and
informative of the overall picture of what OfflineIMAP is doing.
Blinkenlights contains a row of "LEDs" with command buttons and a log. The
log shows more detail about what is happening and is color-coded to match the
color of the lights.
Each light in the Blinkenlights interface represents a thread of execution --
that is, a particular task that OfflineIMAP is performing right now. The
colors indicate what task the particular thread is performing, and are as
follows:
* Black
indicates that this light's thread has terminated; it will light up again
later when new threads start up. So, black indicates no activity.
* Red (Meaning 1)
is the color of the main program's thread, which basically does nothing but
monitor the others. It might remind you of HAL 9000 in 2001.
* Gray
indicates that the thread is establishing a new connection to the IMAP
server.
* Purple
is the color of an account synchronization thread that is monitoring the
progress of the folders in that account (not generating any I/O).
* Cyan
indicates that the thread is syncing a folder.
* Green
means that a folder's message list is being loaded.
* Blue
is the color of a message synchronization controller thread.
* Orange
indicates that an actual message is being copied. (We use fuchsia for fake
messages.)
* Red (meaning 2)
indicates that a message is being deleted.
* Yellow / bright orange
indicates that message flags are being added.
* Pink / bright red
indicates that message flags are being removed.
* Red / Black Flashing
corresponds to the countdown timer that runs between synchronizations.
The name of this interfaces derives from a bit of computer history. Eric
Raymond's Jargon File defines blinkenlights, in part, as:
Front-panel diagnostic lights on a computer, esp. a dinosaur. Now that
dinosaurs are rare, this term usually refers to status lights on a modem,
network hub, or the like.
This term derives from the last word of the famous blackletter-Gothic sign in
mangled pseudo-German that once graced about half the computer rooms in the
English-speaking world. One version ran in its entirety as follows:
ACHTUNG! ALLES LOOKENSPEEPERS!
Das computermachine ist nicht fuer gefingerpoken und mittengrabben.
Ist easy schnappen der springenwerk, blowenfusen und poppencorken
mit spitzensparken. Ist nicht fuer gewerken bei das dumpkopfen.
Das rubbernecken sichtseeren keepen das cotten-pickenen hans in das
pockets muss; relaxen und watchen das blinkenlichten.
Quiet
-----
It will output nothing except errors and serious warnings. Like Basic, this
user interface is not capable of reading a password from the keyboard; account
passwords must be specified using one of the configuration file options.
MachineUI
---------
MachineUI generates output in a machine-parsable format. It is designed
for other programs that will interface to OfflineIMAP.
See Also
--------
offlineimap(1)

4
docs/rfcs/README.md Normal file
View File

@ -0,0 +1,4 @@
All RFCs related to IMAP.
TODO: Add a brief introduction here to introduce the most important RFCs.

339
docs/rfcs/rfc1731.IMAP4_auth.txt Normal file
View File

@ -0,0 +1,339 @@
Network Working Group J. Myers
Request for Comments: 1731 Carnegie Mellon
Category: Standards Track December 1994
IMAP4 Authentication Mechanisms
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. Introduction
The Internet Message Access Protocol, Version 4 [IMAP4] contains the
AUTHENTICATE command, for identifying and authenticating a user to an
IMAP4 server and for optionally negotiating a protection mechanism
for subsequent protocol interactions. This document describes
several authentication mechanisms for use by the IMAP4 AUTHENTICATE
command.
2. Kerberos version 4 authentication mechanism
The authentication type associated with Kerberos version 4 is
"KERBEROS_V4".
The data encoded in the first ready response contains a random 32-bit
number in network byte order. The client should respond with a
Kerberos ticket and an authenticator for the principal
"imap.hostname@realm", where "hostname" is the first component of the
host name of the server with all letters in lower case and where
"realm" is the Kerberos realm of the server. The encrypted checksum
field included within the Kerberos authenticator should contain the
server provided 32-bit number in network byte order.
Upon decrypting and verifying the ticket and authenticator, the
server should verify that the contained checksum field equals the
original server provided random 32-bit number. Should the
verification be successful, the server must add one to the checksum
and construct 8 octets of data, with the first four octets containing
the incremented checksum in network byte order, the fifth octet
containing a bit-mask specifying the protection mechanisms supported
by the server, and the sixth through eighth octets containing, in
Myers [Page 1]
RFC 1731 IMAP4 Authentication Mechanisms December 1994
network byte order, the maximum cipher-text buffer size the server is
able to receive. The server must encrypt the 8 octets of data in the
session key and issue that encrypted data in a second ready response.
The client should consider the server authenticated if the first four
octets the un-encrypted data is equal to one plus the checksum it
previously sent.
The client must construct data with the first four octets containing
the original server-issued checksum in network byte order, the fifth
octet containing the bit-mask specifying the selected protection
mechanism, the sixth through eighth octets containing in network byte
order the maximum cipher-text buffer size the client is able to
receive, and the following octets containing a user name string. The
client must then append from one to eight octets so that the length
of the data is a multiple of eight octets. The client must then PCBC
encrypt the data with the session key and respond to the second ready
response with the encrypted data. The server decrypts the data and
verifies the contained checksum. The username field identifies the
user for whom subsequent IMAP operations are to be performed; the
server must verify that the principal identified in the Kerberos
ticket is authorized to connect as that user. After these
verifications, the authentication process is complete.
The protection mechanisms and their corresponding bit-masks are as
follows:
1 No protection mechanism
2 Integrity (krb_mk_safe) protection
4 Privacy (krb_mk_priv) protection
EXAMPLE: The following are two Kerberos version 4 login scenarios
(note that the line breaks in the sample authenticators are for
editorial clarity and are not in real authenticators)
S: * OK IMAP4 Server
C: A001 AUTHENTICATE KERBEROS_V4
S: + AmFYig==
C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT
+nZImJjnTNHJUtxAA+o0KPKfHEcAFs9a3CL5Oebe/ydHJUwYFd
WwuQ1MWiy6IesKvjL5rL9WjXUb9MwT9bpObYLGOKi1Qh
S: + or//EoAADZI=
C: DiAF5A4gA+oOIALuBkAAmw==
S: A001 OK Kerberos V4 authentication successful
Myers [Page 2]
RFC 1731 IMAP4 Authentication Mechanisms December 1994
S: * OK IMAP4 Server
C: A001 AUTHENTICATE KERBEROS_V4
S: + gcfgCA==
C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT
+nZImJjnTNHJUtxAA+o0KPKfHEcAFs9a3CL5Oebe/ydHJUwYFd
WwuQ1MWiy6IesKvjL5rL9WjXUb9MwT9bpObYLGOKi1Qh
S: A001 NO Kerberos V4 authentication failed
3. GSSAPI authentication mechanism
The authentication type associated with all mechanisms employing the
GSSAPI [RFC1508] is "GSSAPI".
The first ready response issued by the server contains no data. The
client should call GSS_Init_sec_context, passing in 0 for
input_context_handle (initially) and a targ_name equal to output_name
from GSS_Import_Name called with input_name_type of NULL and
input_name_string of "SERVICE:imap@hostname" where "hostname" is the
fully qualified host name of the server with all letters in lower
case. The client must then respond with the resulting output_token.
If GSS_Init_sec_context returns GSS_CONTINUE_NEEDED, then the client
should expect the server to issue a token in a subsequent ready
response. The client must pass the token to another call to
GSS_Init_sec_context.
If GSS_Init_sec_context returns GSS_COMPLETE, then the client should
respond with any resulting output_token. If there is no
output_token, the client should respond with no data. The client
should then expect the server to issue a token in a subsequent ready
response. The client should pass this token to GSS_Unseal and
interpret the first octet of resulting cleartext as a bit-mask
specifying the protection mechanisms supported by the server and the
second through fourth octets as the maximum size output_message to
send to the server. The client should construct data, with the first
octet containing the bit-mask specifying the selected protection
mechanism, the second through fourth octets containing in network
byte order the maximum size output_message the client is able to
receive, and the remaining octets containing a user name string. The
client must pass the data to GSS_Seal with conf_flag set to FALSE,
and respond with the generated output_message. The client can then
consider the server authenticated.
The server must issue a ready response with no data and pass the
resulting client supplied token to GSS_Accept_sec_context as
input_token, setting acceptor_cred_handle to NULL (for "use default
credentials"), and 0 for input_context_handle (initially). If
GSS_Accept_sec_context returns GSS_CONTINUE_NEEDED, the server should
Myers [Page 3]
RFC 1731 IMAP4 Authentication Mechanisms December 1994
return the generated output_token to the client in a ready response
and pass the resulting client supplied token to another call to
GSS_Accept_sec_context.
If GSS_Accept_sec_context returns GSS_COMPLETE, then if an
output_token is returned, the server should return it to the client
in a ready response and expect a reply from the client with no data.
Whether or not an output_token was returned, the server then should
then construct 4 octets of data, with the first octet containing a
bit-mask specifying the protection mechanisms 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. The
server must then pass the plaintext to GSS_Seal with conf_flag set to
FALSE and issue the generated output_message to the client in a ready
response. The server must then pass the resulting client supplied
token to GSS_Unseal and interpret the first octet of resulting
cleartext as the bit-mask for the selected protection mechanism, the
second through fourth octets as the maximum size output_message to
send to the client, and the remaining octets as the user name. Upon
verifying the src_name is authorized to authenticate as the user
name, The server should then consider the client authenticated.
The protection mechanisms and their corresponding bit-masks are as
follows:
1 No protection mechanism
2 Integrity protection.
Sender calls GSS_Seal with conf_flag set to FALSE
4 Privacy protection.
Sender calls GSS_Seal with conf_flag set to TRUE
4. S/Key authentication mechanism
The authentication type associated with S/Key [SKEY] is "SKEY".
The first ready response issued by the server contains no data. The
client responds with the user name string.
The data encoded in the second ready response contains the decimal
sequence number followed by a single space and the seed string for
the indicated user. The client responds with the one-time-password,
as either a 64-bit value in network byte order or encoded in the "six
English words" format.
Upon successful verification of the one-time-password, the server
should consider the client authenticated.
Myers [Page 4]
RFC 1731 IMAP4 Authentication Mechanisms December 1994
S/Key authentication does not provide for any protection mechanisms.
EXAMPLE: The following are two S/Key login scenarios.
S: * OK IMAP4 Server
C: A001 AUTHENTICATE SKEY
S: +
C: bW9yZ2Fu
S: + OTUgUWE1ODMwOA==
C: Rk9VUiBNQU5OIFNPT04gRklSIFZBUlkgTUFTSA==
S: A001 OK S/Key authentication successful
S: * OK IMAP4 Server
C: A001 AUTHENTICATE SKEY
S: +
C: c21pdGg=
S: + OTUgUWE1ODMwOA==
C: BsAY3g4gBNo=
S: A001 NO S/Key authentication failed
5. References
[IMAP4] Crispin, M., "Internet Message Access Protocol - Version 4",
RFC 1730, University of Washington, December 1994.
[RFC1508] Linn, J., "Generic Security Service Application Program
Interface", RFC 1508, Geer Zolot Associates, September 1993.
[SKEY] Haller, Neil M. "The S/Key One-Time Password System",
Bellcore, Morristown, New Jersey, October 1993,
thumper.bellcore.com:pub/nmh/docs/ISOC.symp.ps
Myers [Page 5]
RFC 1731 IMAP4 Authentication Mechanisms December 1994
6. Security Considerations
Security issues are discussed throughout this memo.
7. Author's Address
John G. Myers
Carnegie-Mellon University
5000 Forbes Ave.
Pittsburgh PA, 15213-3890
EMail: jgm+@cmu.edu
Myers [Page 6]

283
docs/rfcs/rfc1732.compatibiliy_IMAP2-IMAP2bis.txt Normal file
View File

@ -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]

171
docs/rfcs/rfc1733.models_in_IMAP4.txt Normal file
View File

@ -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]

439
docs/rfcs/rfc1734.POP3_AUTHentication Normal file
View File

@ -0,0 +1,439 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head profile="http://dublincore.org/documents/2008/08/04/dc-html/">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="robots" content="index,follow" />
<meta name="creator" content="rfcmarkup version 1.111" />
<link rel="schema.DC" href="http://purl.org/dc/elements/1.1/" />
<meta name="DC.Identifier" content="urn:ietf:rfc:1734" />
<meta name="DC.Description.Abstract" content="This document describes the optional AUTH command, for indicating an
authentication mechanism to the server, performing an authentication
protocol exchange, and optionally negotiating a protection mechanism
for subsequent protocol interactions. [STANDARDS-TRACK]" />
<meta name="DC.Creator" content="J. Myers" />
<meta name="DC.Date.Issued" content="December, 1994" />
<meta name="DC.Title" content="POP3 AUTHentication command" />
<link rel="icon" href="/images/rfc.png" type="image/png" />
<link rel="shortcut icon" href="/images/rfc.png" type="image/png" />
<title>RFC 1734 - POP3 AUTHentication command</title>
<style type="text/css">
body {
margin: 0px 8px;
font-size: 1em;
}
h1, h2, h3, h4, h5, h6, .h1, .h2, .h3, .h4, .h5, .h6 {
font-weight: bold;
line-height: 0pt;
display: inline;
white-space: pre;
font-family: monospace;
font-size: 1em;
font-weight: bold;
}
pre {
font-size: 1em;
margin-top: 0px;
margin-bottom: 0px;
}
.pre {
white-space: pre;
font-family: monospace;
}
.header{
font-weight: bold;
}
.newpage {
page-break-before: always;
}
.invisible {
text-decoration: none;
color: white;
}
a.selflink {
color: black;
text-decoration: none;
}
@media print {
body {
font-family: monospace;
font-size: 10.5pt;
}
h1, h2, h3, h4, h5, h6 {
font-size: 1em;
}
a:link, a:visited {
color: inherit;
text-decoration: none;
}
.noprint {
display: none;
}
}
@media screen {
.grey, .grey a:link, .grey a:visited {
color: #777;
}
.docinfo {
background-color: #EEE;
}
.top {
border-top: 7px solid #EEE;
}
.bgwhite { background-color: white; }
.bgred { background-color: #F44; }
.bggrey { background-color: #666; }
.bgbrown { background-color: #840; }
.bgorange { background-color: #FA0; }
.bgyellow { background-color: #EE0; }
.bgmagenta{ background-color: #F4F; }
.bgblue { background-color: #66F; }
.bgcyan { background-color: #4DD; }
.bggreen { background-color: #4F4; }
.legend { font-size: 90%; }
.cplate { font-size: 70%; border: solid grey 1px; }
}
</style>
<!--[if IE]>
<style>
body {
font-size: 13px;
margin: 10px 10px;
}
</style>
<![endif]-->
<script type="text/javascript"><!--
function addHeaderTags() {
var spans = document.getElementsByTagName("span");
for (var i=0; i < spans.length; i++) {
var elem = spans[i];
if (elem) {
var level = elem.getAttribute("class");
if (level == "h1" || level == "h2" || level == "h3" || level == "h4" || level == "h5" || level == "h6") {
elem.innerHTML = "<"+level+">"+elem.innerHTML+"</"+level+">";
}
}
}
}
var legend_html = "Colour legend:<br /> <table> <tr><td>Unknown:</td> <td><span class='cplate bgwhite'>&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr> <tr><td>Draft:</td> <td><span class='cplate bgred'>&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr> <tr><td>Informational:</td> <td><span class='cplate bgorange'>&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr> <tr><td>Experimental:</td> <td><span class='cplate bgyellow'>&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr> <tr><td>Best Common Practice:</td> <td><span class='cplate bgmagenta'>&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr> <tr><td>Proposed Standard:</td> <td><span class='cplate bgblue'>&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr> <tr><td>Draft Standard (old designation):</td> <td><span class='cplate bgcyan'>&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr> <tr><td>Internet Standard:</td> <td><span class='cplate bggreen'>&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr> <tr><td>Historic:</td> <td><span class='cplate bggrey'>&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr> <tr><td>Obsolete:</td> <td><span class='cplate bgbrown'>&nbsp;&nbsp;&nbsp;&nbsp;</span></td></tr> </table>";
function showElem(id) {
var elem = document.getElementById(id);
elem.innerHTML = eval(id+"_html");
elem.style.visibility='visible';
}
function hideElem(id) {
var elem = document.getElementById(id);
elem.style.visibility='hidden';
elem.innerHTML = "";
}
// -->
</script>
</head>
<body onload="addHeaderTags()">
<div style="height: 13px;">
<div onmouseover="this.style.cursor='pointer';"
onclick="showElem('legend');"
onmouseout="hideElem('legend')"
style="height: 6px; position: absolute;"
class="pre noprint docinfo bgbrown"
title="Click for colour legend." > </div>
<div id="legend"
class="docinfo noprint pre legend"
style="position:absolute; top: 4px; left: 4ex; visibility:hidden; background-color: white; padding: 4px 9px 5px 7px; border: solid #345 1px; "
onmouseover="showElem('legend');"
onmouseout="hideElem('legend');">
</div>
</div>
<span class="pre noprint docinfo top">[<a href="../html/" title="Document search and retrieval page">Docs</a>] [<a href="/rfc/rfc1734.txt" title="Plaintext version of this document">txt</a>|<a href="/pdf/rfc1734" title="PDF version of this document">pdf</a>] [<a href="./draft-myers-pop3-auth" title="draft-myers-pop3-auth">draft-myers-pop3-...</a>] [<a href="/rfcdiff?difftype=--hwdiff&amp;url2=rfc1734" title="Inline diff (wdiff)">Diff1</a>] [<a href="/rfcdiff?url2=rfc1734" title="Side-by-side diff">Diff2</a>] </span><br />
<span class="pre noprint docinfo"> </span><br />
<span class="pre noprint docinfo">Obsoleted by: <a href="./rfc5034">5034</a> PROPOSED STANDARD</span><br />
<span class="pre noprint docinfo"> </span><br />
<pre>
Network Working Group J. Myers
Request for Comments: 1734 Carnegie Mellon
Category: Standards Track December 1994
<span class="h1">POP3 AUTHentication command</span>
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.
<span class="h2"><a class="selflink" name="section-1" href="#section-1">1</a>. Introduction</span>
This document describes the optional AUTH command, for indicating an
authentication mechanism to the server, performing an authentication
protocol exchange, and optionally negotiating a protection mechanism
for subsequent protocol interactions. The authentication and
protection mechanisms used by the POP3 AUTH command are those used by
IMAP4.
<span class="h2"><a class="selflink" name="section-2" href="#section-2">2</a>. The AUTH command</span>
AUTH mechanism
Arguments:
a string identifying an IMAP4 authentication mechanism,
such as defined by [<a href="#ref-IMAP4-AUTH" title="&quot;IMAP4 Authentication Mechanisms&quot;">IMAP4-AUTH</a>]. Any use of the string
"imap" used in a server authentication identity in the
definition of an authentication mechanism is replaced with
the string "pop".
Restrictions:
may only be given in the AUTHORIZATION state
Discussion:
The AUTH command indicates an authentication mechanism to
the server. If the server supports the requested
authentication mechanism, it performs an authentication
protocol exchange to authenticate and identify the user.
Optionally, it also negotiates a protection mechanism for
subsequent protocol interactions. If the requested
authentication mechanism is not supported, the server
<span class="grey">Myers [Page 1]</span>
</pre><!--NewPage--><pre class='newpage'><a name="page-2" id="page-2" href="#page-2" class="invisible"> </a>
<span class="grey"><a href="./rfc1734">RFC 1734</a> POP3 AUTH December 1994</span>
should reject the AUTH command by sending a negative
response.
The authentication protocol exchange consists of a series
of server challenges and client answers that are specific
to the authentication mechanism. A server challenge,
otherwise known as a ready response, is a line consisting
of a "+" character followed by a single space and a BASE64
encoded string. The client answer consists of a line
containing a BASE64 encoded string. If the client wishes
to cancel an authentication exchange, it should issue a
line with a single "*". If the server receives such an
answer, it must reject the AUTH command by sending a
negative response.
A protection mechanism provides integrity and privacy
protection to the protocol session. If a protection
mechanism is negotiated, it is applied to all subsequent
data sent over the connection. The protection mechanism
takes effect immediately following the CRLF that concludes
the authentication exchange for the client, and the CRLF of
the positive response for the server. Once the protection
mechanism is in effect, the stream of command and response
octets is processed into buffers of ciphertext. Each
buffer is transferred over the connection as a stream of
octets prepended with a four octet field in network byte
order that represents the length of the following data.
The maximum ciphertext buffer length is defined by the
protection mechanism.
The server is not required to support any particular
authentication mechanism, nor are authentication mechanisms
required to support any protection mechanisms. If an AUTH
command fails with a negative response, the session remains
in the AUTHORIZATION state and client may try another
authentication mechanism by issuing another AUTH command,
or may attempt to authenticate by using the USER/PASS or
APOP commands. In other words, the client may request
authentication types in decreasing order of preference,
with the USER/PASS or APOP command as a last resort.
Should the client successfully complete the authentication
exchange, the POP3 server issues a positive response and
the POP3 session enters the TRANSACTION state.
Possible Responses:
+OK maildrop locked and ready
-ERR authentication exchange failed
<span class="grey">Myers [Page 2]</span>
</pre><!--NewPage--><pre class='newpage'><a name="page-3" id="page-3" href="#page-3" class="invisible"> </a>
<span class="grey"><a href="./rfc1734">RFC 1734</a> POP3 AUTH December 1994</span>
Examples:
S: +OK POP3 server ready
C: AUTH KERBEROS_V4
S: + AmFYig==
C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT
+nZImJjnTNHJUtxAA+o0KPKfHEcAFs9a3CL5Oebe/ydHJUwYFd
WwuQ1MWiy6IesKvjL5rL9WjXUb9MwT9bpObYLGOKi1Qh
S: + or//EoAADZI=
C: DiAF5A4gA+oOIALuBkAAmw==
S: +OK Kerberos V4 authentication successful
...
C: AUTH FOOBAR
S: -ERR Unrecognized authentication type
Note: the line breaks in the first client answer are
for editorial clarity and are not in real authentica-
tors.
<span class="grey">Myers [Page 3]</span>
</pre><!--NewPage--><pre class='newpage'><a name="page-4" id="page-4" href="#page-4" class="invisible"> </a>
<span class="grey"><a href="./rfc1734">RFC 1734</a> POP3 AUTH December 1994</span>
<span class="h2"><a class="selflink" name="section-3" href="#section-3">3</a>. Formal Syntax</span>
The following syntax specification uses the augmented Backus-Naur
Form (BNF) notation as specified in <a href="./rfc822">RFC 822</a>.
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.
ATOM_CHAR ::= &lt;any CHAR except atom_specials&gt;
atom_specials ::= "(" / ")" / "{" / SPACE / CTLs / "%" / "*" /
&lt;"&gt; / "\"
auth ::= "AUTH" 1*(SPACE / TAB) auth_type *(CRLF base64)
CRLF
auth_type ::= 1*ATOM_CHAR
base64 ::= *(4base64_CHAR) [base64_terminal]
base64_char ::= "A" / "B" / "C" / "D" / "E" / "F" / "G" / "H" /
"I" / "J" / "K" / "L" / "M" / "N" / "O" / "P" /
"Q" / "R" / "S" / "T" / "U" / "V" / "W" / "X" /
"Y" / "Z" /
"a" / "b" / "c" / "d" / "e" / "f" / "g" / "h" /
"i" / "j" / "k" / "l" / "m" / "n" / "o" / "p" /
"q" / "r" / "s" / "t" / "u" / "v" / "w" / "x" /
"y" / "z" /
"0" / "1" / "2" / "3" / "4" / "5" / "6" / "7" /
"8" / "9" / "+" / "/"
;; Case-sensitive
base64_terminal ::= (2base64_char "==") / (3base64_char "=")
CHAR ::= &lt;any 7-bit US-ASCII character except NUL,
0x01 - 0x7f&gt;
continue_req ::= "+" SPACE base64 CRLF
CR ::= &lt;ASCII CR, carriage return, 0x0C&gt;
CRLF ::= CR LF
CTL ::= &lt;any ASCII control character and DEL,
0x00 - 0x1f, 0x7f&gt;
<span class="grey">Myers [Page 4]</span>
</pre><!--NewPage--><pre class='newpage'><a name="page-5" id="page-5" href="#page-5" class="invisible"> </a>
<span class="grey"><a href="./rfc1734">RFC 1734</a> POP3 AUTH December 1994</span>
LF ::= &lt;ASCII LF, line feed, 0x0A&gt;
SPACE ::= &lt;ASCII SP, space, 0x20&gt;
TAB ::= &lt;ASCII HT, tab, 0x09&gt;
<span class="h2"><a class="selflink" name="section-4" href="#section-4">4</a>. References</span>
[<a name="ref-IMAP4-AUTH" id="ref-IMAP4-AUTH">IMAP4-AUTH</a>] Myers, J., "IMAP4 Authentication Mechanisms", <a href="./rfc1731">RFC 1731</a>,
Carnegie Mellon, December 1994.
<span class="h2"><a class="selflink" name="section-5" href="#section-5">5</a>. Security Considerations</span>
Security issues are discussed throughout this memo.
<span class="h2"><a class="selflink" name="section-6" href="#section-6">6</a>. Author's Address</span>
John G. Myers
Carnegie-Mellon University
5000 Forbes Ave
Pittsburgh, PA 15213
EMail: jgm+@cmu.edu
Myers [Page 5]
</pre><br />
<span class="noprint"><small><small>Html markup produced by rfcmarkup 1.111, available from
<a href="https://tools.ietf.org/tools/rfcmarkup/">https://tools.ietf.org/tools/rfcmarkup/</a>
</small></small></span>
</body></html>

171
docs/rfcs/rfc2061.compatibility_IMAP4-IMAP2bis.txt Normal file
View File

@ -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]

451
docs/rfcs/rfc2086.IMAP4_ACL_extension.txt Normal file
View File

@ -0,0 +1,451 @@
Network Working Group J. Myers
Request for Comments: 2086 Carnegie Mellon
Category: Standards Track January 1997
IMAP4 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.
1. Abstract
The ACL extension of the Internet Message Access Protocol [IMAP4]
permits access control lists 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............................................... 3
4.1. SETACL................................................. 3
4.2. DELETEACL.............................................. 4
4.3. GETACL................................................. 4
4.4. LISTRIGHTS............................................. 4
4.5. MYRIGHTS............................................... 5
5. Responses.............................................. 5
5.1. ACL.................................................... 5
5.2. LISTRIGHTS............................................. 6
5.3. MYRIGHTS............................................... 6
6. Formal Syntax.......................................... 6
7. References............................................. 7
8. Security Considerations................................ 7
9. Author's Address....................................... 8
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 2086 ACL extension January 1997
3. Introduction and Overview
The ACL extension is present in any IMAP4 implementation which
returns "ACL" as one of the supported capabilities to the CAPABILITY
command.
An access control list is a set of <identifier,rights> pairs.
Identifier is a US-ASCII 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 user. Identifiers starting with
a dash ("-") are reserved for "negative rights", described below.
All other identifier strings are interpreted in an implementation-
defined manner.
Rights is a string listing a (possibly empty) set of alphanumeric
characters, each character listing a set of operations which is being
controlled. Letters are reserved for ``standard'' rights, listed
below. The set of standard rights may only be extended by a
standards-track document. Digits are reserved for implementation or
site defined rights. The currently defined standard rights are:
l - lookup (mailbox is visible to LIST/LSUB commands)
r - read (SELECT the mailbox, perform CHECK, FETCH, PARTIAL,
SEARCH, COPY from mailbox)
s - keep seen/unseen information across sessions (STORE SEEN flag)
w - write (STORE flags other than SEEN and DELETED)
i - insert (perform APPEND, COPY into mailbox)
p - post (send mail to submission address for mailbox,
not enforced by IMAP4 itself)
c - create (CREATE new sub-mailboxes in any implementation-defined
hierarchy)
d - delete (STORE DELETED flag, perform EXPUNGE)
a - administer (perform SETACL)
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 "wisd" 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 may discover the set of rights
which may be granted to a given identifier in the ACL for a given
mailbox by using the LISTRIGHTS command.
Myers Standards Track [Page 2]
RFC 2086 ACL extension January 1997
It is possible for multiple identifiers in an access control list to
apply to a given user (or other authentication identity). For
example, an ACL may include rights to be granted to the identifier
matching the user, one or more implementation-defined identifiers
matching groups which 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
only use those rights granted to the most specific identifier present
in the ACL. A client may determine the set of rights granted to the
logged-in user for a given mailbox 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 that is
prefixed by the dash. For example, 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". Implementations
need not support having identifiers which start with a dash in ACLs.
4. Commands
4.1. SETACL
Arguments: mailbox name
authentication identifier
access right modification
Data: no specific data for this command
Result: OK - setacl completed
NO - setacl failure: can't set acl
BAD - command unknown or 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 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.
Myers Standards Track [Page 3]
RFC 2086 ACL extension January 1997
4.2. DELETEACL
Arguments: mailbox name
authentication identifier
Data: no specific data for this command
Result: OK - deleteacl completed
NO - deleteacl failure: can't delete acl
BAD - command unknown or arguments invalid
The DELETEACL command removes any <identifier,rights> pair for the
specified identifier from the access control list for the specified
mailbox.
4.3. GETACL
Arguments: mailbox name
Data: untagged responses: ACL
Result: OK - getacl completed
NO - getacl failure: can't get acl
BAD - command unknown or arguments invalid
The GETACL command returns the access control list for mailbox in
an untagged ACL reply.
Example: C: A002 GETACL INBOX
S: * ACL INBOX Fred rwipslda
S: A002 OK Getacl complete
4.4. LISTRIGHTS
Arguments: mailbox name
authentication identifier
Data: untagged responses: LISTRIGHTS
Result: OK - listrights completed
NO - listrights failure: can't get rights list
BAD - command unknown or arguments invalid
The LISTRIGHTS command takes a mailbox name and an identifier and
returns information about what rights may be granted to the identifier
in the ACL for the mailbox.
Myers Standards Track [Page 4]
RFC 2086 ACL extension January 1997
Example: C: a001 LISTRIGHTS ~/Mail/saved smith
S: * LISTRIGHTS ~/Mail/saved smith la r swicd
S: a001 OK Listrights completed
C: a005 LISTRIGHTS archive.imap anyone
S: * LISTRIGHTS archive.imap anyone "" l r s w i p c d a
0 1 2 3 4 5 6 7 8 9
4.5. MYRIGHTS
Arguments: mailbox name
Data: untagged responses: MYRIGHTS
Result: OK - myrights completed
NO - myrights failure: can't get rights
BAD - command unknown or 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 rwipslda
S: A003 OK Myrights complete
5. Responses
5.1. ACL
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.
Myers Standards Track [Page 5]
RFC 2086 ACL extension January 1997
5.2. LISTRIGHTS
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 may be granted in the mailbox. Rights
mentioned in the same string are tied together--either all must be
granted to the identifier in the mailbox or none may be granted.
The same right may not be listed more than once in the LISTRIGHTS
command.
5.3. MYRIGHTS
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.
6. 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.
Myers Standards Track [Page 6]
RFC 2086 ACL extension January 1997
acl_data ::= "ACL" SPACE mailbox *(SPACE identifier SPACE
rights)
deleteacl ::= "DELETEACL" SPACE mailbox SPACE identifier
getacl ::= "GETACL" SPACE mailbox
identifier ::= astring
listrights ::= "LISTRIGHTS" SPACE mailbox SPACE identifier
listrights_data ::= "LISTRIGHTS" SPACE mailbox SPACE identifier
SPACE rights *(SPACE rights)
mod_rights ::= astring
;; +rights to add, -rights to remove
;; rights to replace
myrights ::= "MYRIGHTS" SPACE mailbox
myrights_data ::= "MYRIGHTS" SPACE mailbox SPACE rights
rights ::= astring
setacl ::= "SETACL" SPACE mailbox SPACE identifier
SPACE mod_rights
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
An implementation must make sure the ACL commands themselves do not
give information about mailboxes with appropriately restricted ACL's.
For example, a GETACL command on a mailbox for which the user has
insufficient rights should not admit the mailbox exists, much less
return the mailbox's ACL.
Myers Standards Track [Page 7]
RFC 2086 ACL extension January 1997
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 8]

283
docs/rfcs/rfc2087.IMAP4_QUOTA_extension.txt Normal file
View File

@ -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]

115
docs/rfcs/rfc2088.IMAP4_non_synchronizing_literals.txt Normal file
View File

@ -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]

283
docs/rfcs/rfc2095.IMAP-POP_AUTHorize_extension.txt Normal file
View File

@ -0,0 +1,283 @@
Network Working Group J. Klensin
Request for Comments: 2095 R. Catoe
Category: Standards Track P. Krumviede
MCI
January 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 2095 IMAP/POP AUTHorize Extension January 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 2095 IMAP/POP AUTHorize Extension January 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 2095 IMAP/POP AUTHorize Extension January 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, H., "HMAC-MD5: Keyed-MD5 for Message
Authentication", Work in Progess.
[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 2095 IMAP/POP AUTHorize Extension January 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]

227
docs/rfcs/rfc2177.IMAP4_IDLE_command.txt Normal file
View File

@ -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]

787
docs/rfcs/rfc2180.IMAP4_multi-accessed_Mailbox_practice.txt Normal file
View File

@ -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]

899
docs/rfcs/rfc2192.IMAP_URL_scheme.txt Normal file
View File

@ -0,0 +1,899 @@
Network Working Group C. Newman
Request for Comments: 2192 Innosoft
Category: Standards Track September 1997
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 [IMAP4] 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.
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" [KEYWORDS].
2. IMAP scheme
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.
The IMAP URL follows the common Internet scheme syntax as defined
in RFC 1738 [BASIC-URL] except that clear text passwords are not
permitted. If :<port> is omitted, the port defaults to 143.
Newman Standards Track [Page 1]
RFC 2192 IMAP URL Scheme September 1997
An IMAP URL takes one of the following forms:
imap://<iserver>/
imap://<iserver>/<enc_list_mailbox>;TYPE=<list_type>
imap://<iserver>/<enc_mailbox>[uidvalidity][?<enc_search>]
imap://<iserver>/<enc_mailbox>[uidvalidity]<iuid>[isection]
The first form is used to refer to an IMAP server, the second form
refers to a list of mailboxes, the third form refers to the
contents of a mailbox or a set of messages resulting from a search,
and the final form refers to a specific message or message part.
Note that the syntax here is informal. The authoritative formal
syntax for IMAP URLs is defined in section 11.
3. IMAP User Name and Authentication Mechanism
A user name and/or authentication mechanism may be supplied. They
are used in the "LOGIN" or "AUTHENTICATE" commands after making the
connection to the IMAP server. If no user name or authentication
mechanism is supplied, the user name "anonymous" is used with the
"LOGIN" command and the password is supplied as the Internet e-mail
address of the end user accessing the resource. If the URL doesn't
supply a user name, the program interpreting the IMAP URL SHOULD
request one from the user if necessary.
An authentication mechanism can be expressed by adding
";AUTH=<enc_auth_type>" to the end of the user name. 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
SHOULD be obtained from the mechanism or requested from the user as
appropriate.
The string ";AUTH=*" indicates that the client SHOULD select an
appropriate authentication mechanism. It MAY use any mechanism
listed in the CAPABILITY command 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. This allows a URL which 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.
Newman Standards Track [Page 2]
RFC 2192 IMAP URL Scheme September 1997
Since URLs can easily come from untrusted sources, care must be
taken when resolving a URL which requires or requests any sort of
authentication. If authentication credentials are supplied to the
wrong server, it may compromise the security of the user's account.
The program resolving the URL should make sure it meets at least
one of the following criteria in this case:
(1) The URL comes from a trusted source, such as a referral server
which 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, if the client knows the site
domain name, site policy may dictate that any hostname ending in
that domain is trusted.
(3) The user confirms that connecting to that domain name with the
specified credentials and/or mechanism is permitted.
(4) A mechanism is used which validates the server before passing
potentially compromising client credentials.
(5) An authentication mechanism is used which will not reveal
information to the server which could be used to compromise future
connections.
URLs which do not include a user name must be treated with extra
care, since 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 plain text password
as a fallback with ";AUTH=*" unless the connection has strong
encryption (e.g. a key length of greater than 56 bits).
A program interpreting IMAP URLs MAY cache open connections to an
IMAP server for later re-use. If a URL contains a user name, only
connections authenticated as that user may be re-used. If a URL
does not contain a user name or authentication mechanism, then only
an anonymous connection may be re-used. If a URL contains an
authentication mechanism without a user name, then any non-
anonymous connection may be re-used.
Note that if unsafe or reserved characters such as " " or ";" are
present in the user name or authentication mechanism, they MUST be
encoded as described in RFC 1738 [BASIC-URL].
Newman Standards Track [Page 3]
RFC 2192 IMAP URL Scheme September 1997
4. IMAP server
An IMAP URL referring to an IMAP server has the following form:
imap://<iserver>/
A program interpreting this URL would issue the standard set of
commands it uses to present a view of the contents of an IMAP
server. This is likely to be semanticly equivalent to one of the
following URLs:
imap://<iserver>/;TYPE=LIST
imap://<iserver>/;TYPE=LSUB
The program interpreting this URL SHOULD use the LSUB form if it
supports mailbox subscriptions.
5. Lists of mailboxes
An IMAP URL referring to a list of mailboxes has the following
form:
imap://<iserver>/<enc_list_mailbox>;TYPE=<list_type>
The <list_type> may be either "LIST" or "LSUB", and is case
insensitive. The field ";TYPE=<list_type>" MUST be included.
The <enc_list_mailbox> is any argument suitable for the
list_mailbox field of the IMAP [IMAP4] LIST or LSUB commands. The
field <enc_list_mailbox> may be omitted, in which case the program
interpreting the IMAP URL may use "*" or "%" as the
<enc_list_mailbox>. The program SHOULD use "%" if it supports a
hierarchical view, otherwise it SHOULD use "*".
Note that if unsafe or reserved characters such as " " or "%" are
present in <enc_list_mailbox> they MUST be encoded as described in
RFC 1738 [BASIC-URL]. If the character "/" is present in
enc_list_mailbox, it SHOULD NOT be encoded.
6. Lists of messages
An IMAP URL referring to a list of messages has the following form:
imap://<iserver>/<enc_mailbox>[uidvalidity][?<enc_search>]
Newman Standards Track [Page 4]
RFC 2192 IMAP URL Scheme September 1997
The <enc_mailbox> field is used as the argument to the IMAP4
"SELECT" command. Note that if unsafe or reserved characters such
as " ", ";", or "?" are present in <enc_mailbox> they MUST be
encoded as described in RFC 1738 [BASIC-URL]. If the character "/"
is present in enc_mailbox, it SHOULD NOT be encoded.
The [uidvalidity] field is optional. If it is present, it MUST be
the argument to the IMAP4 UIDVALIDITY status response at the time
the URL was created. This SHOULD be used by the program
interpreting the IMAP URL to determine if the URL is stale.
The [?<enc_search>] field is optional. If it is not present, the
contents of the mailbox SHOULD be presented by the program
interpreting the URL. If it is present, it SHOULD be used as the
arguments following an IMAP4 SEARCH command with unsafe characters
such as " " (which are likely to be present in the <enc_search>)
encoded as described in RFC 1738 [BASIC-URL].
7. 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]
The <enc_mailbox> and [uidvalidity] are as defined 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 UID, and 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 with a "UID FETCH <uid>
BODYSTRUCTURE" command and locating the appropriate part in the
resulting BODYSTRUCTURE. Note that unsafe characters in [isection]
MUST be encoded as described in [BASIC-URL].
Newman Standards Track [Page 5]
RFC 2192 IMAP URL Scheme September 1997
8. Relative IMAP URLs
Relative IMAP URLs are permitted and are resolved according to the
rules defined in RFC 1808 [REL-URL] with one exception. In IMAP
URLs, parameters are treated as part of the normal path with
respect to relative URL resolution. This is believed to be the
behavior of the installed base and is likely to be documented in a
future revision of the relative URL specification.
The following observations are also important:
The <iauth> grammar element is considered part of the user name for
purposes of resolving relative IMAP URLs. This means that unless a
new login/server specification is included in the relative URL, the
authentication mechanism is inherited from a 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 which
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.
The base URL for a list of mailboxes or messages which was referred
to by an IMAP URL is always the referring IMAP URL itself. The
base URL for a message or message part which was referred to by an
IMAP URL may be more complicated to determine. The program
interpreting the relative URL will have to check the headers of the
MIME entity and any enclosing MIME entities in order to locate the
"Content-Base" and "Content-Location" headers. These headers are
used to determine the base URL as defined in [HTTP]. For example,
if the referring IMAP URL contains a "/;SECTION=1.2" parameter,
then the MIME headers for section 1.2, for section 1, and for the
enclosing message itself SHOULD be checked in that order for
"Content-Base" or "Content-Location" headers.
9. Multinational Considerations
IMAP4 [IMAP4] section 5.1.3 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 [UTF8]. Since 8-bit
characters are not permitted in URLs, the UTF-8 characters are
Newman Standards Track [Page 6]
RFC 2192 IMAP URL Scheme September 1997
encoded as required by the URL specification [BASIC-URL]. Sample
code is included in Appendix A to demonstrate this conversion.
10. 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.org/gray-council;UIDVALIDITY=385759045/;UID=20>
Results in the following client commands:
<connect to minbari.org, port 143>
C: A001 LOGIN ANONYMOUS sheridan@babylon5.org
C: A002 SELECT gray-council
<client verifies the UIDVALIDITY matches>
C: A003 UID FETCH 20 BODY.PEEK[]
The URL:
<imap://michael@minbari.org/users.*;type=list>
Results in the following client commands:
<client requests password from user>
<connect to minbari.org imap server, activate strong encryption>
C: A001 LOGIN MICHAEL zipper
C: A002 LIST "" users.*
The URL:
<imap://psicorp.org/~peter/%E6%97%A5%E6%9C%AC%E8%AA%9E/
%E5%8F%B0%E5%8C%97>
Results in the following client commands:
<connect to psicorp.org, port 143>
C: A001 LOGIN ANONYMOUS bester@psycop.psicorp.org
C: A002 SELECT ~peter/&ZeVnLIqe-/&U,BTFw-
<commands the client uses for viewing the contents of a mailbox>
Newman Standards Track [Page 7]
RFC 2192 IMAP URL Scheme September 1997
The URL:
<imap://;AUTH=KERBEROS_V4@minbari.org/gray-council/;uid=20/
;section=1.2>
Results in the following client commands:
<connect to minbari.org, port 143>
C: A001 AUTHENTICATE KERBEROS_V4
<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-Base Content-Location)])
<Client looks for Content-Base or 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.org/gray%20council?SUBJECT%20shadows>
Could result in the following:
<connect to minbari.org, port 143>
C: A001 CAPABILITY
S: * CAPABILITY IMAP4rev1 AUTH=GSSAPI
S: A001 OK
C: A002 AUTHENTICATE GSSAPI
<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
...
Newman Standards Track [Page 8]
RFC 2192 IMAP URL Scheme September 1997
NOTE: In this final example, the client has implementation
dependent choices. The authentication mechanism could be anything,
including PREAUTH. And the final FETCH command could fetch more or
less information about the messages, depending on what it wishes to
display to the user.
11. Security Considerations
Security considerations discussed in the IMAP specification [IMAP4]
and the URL specification [BASIC-URL] are relevant. Security
considerations related to authenticated URLs are discussed in
section 3 of this document.
Many email clients store the plain text 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.
12. ABNF for IMAP URL scheme
This uses ABNF as defined in RFC 822 [IMAIL]. Terminals from the
BNF for IMAP [IMAP4] and URLs [BASIC-URL] are also used. Strings
are not case sensitive and free insertion of linear-white-space is
not permitted.
achar = uchar / "&" / "=" / "~"
; see [BASIC-URL] for "uchar" definition
bchar = achar / ":" / "@" / "/"
enc_auth_type = 1*achar
; encoded version of [IMAP-AUTH] "auth_type"
enc_list_mailbox = 1*bchar
; encoded version of [IMAP4] "list_mailbox"
enc_mailbox = 1*bchar
; encoded version of [IMAP4] "mailbox"
enc_search = 1*bchar
; encoded version of search_program below
enc_section = 1*bchar
; encoded version of section below
Newman Standards Track [Page 9]
RFC 2192 IMAP URL Scheme September 1997
enc_user = 1*achar
; encoded version of [IMAP4] "userid"
imapurl = "imap://" iserver "/" [ icommand ]
iauth = ";AUTH=" ( "*" / enc_auth_type )
icommand = imailboxlist / imessagelist / imessagepart
imailboxlist = [enc_list_mailbox] ";TYPE=" list_type
imessagelist = enc_mailbox [ "?" enc_search ] [uidvalidity]
imessagepart = enc_mailbox [uidvalidity] iuid [isection]
isection = "/;SECTION=" enc_section
iserver = [iuserauth "@"] hostport
; See [BASIC-URL] for "hostport" definition
iuid = "/;UID=" nz_number
; See [IMAP4] for "nz_number" definition
iuserauth = enc_user [iauth] / [enc_user] iauth
list_type = "LIST" / "LSUB"
search_program = ["CHARSET" SPACE astring SPACE]
search_key *(SPACE search_key)
; IMAP4 literals may not be used
; See [IMAP4] for "astring" and "search_key"
section = section_text / (nz_number *["." nz_number]
["." (section_text / "MIME")])
; See [IMAP4] for "section_text" and "nz_number"
uidvalidity = ";UIDVALIDITY=" nz_number
; See [IMAP4] for "nz_number" definition
13. References
[BASIC-URL] Berners-Lee, Masinter, McCahill, "Uniform Resource
Locators (URL)", RFC 1738, CERN, Xerox Corporation, University of
Minnesota, December 1994.
<ftp://ds.internic.net/rfc/rfc1738.txt>
Newman Standards Track [Page 10]
RFC 2192 IMAP URL Scheme September 1997
[IMAP4] Crispin, M., "Internet Message Access Protocol - Version
4rev1", RFC 2060, University of Washington, December 1996.
<ftp://ds.internic.net/rfc/rfc2060.txt>
[IMAP-AUTH] Myers, J., "IMAP4 Authentication Mechanism", RFC 1731,
Carnegie-Mellon University, December 1994.
<ftp://ds.internic.net/rfc/rfc1731.txt>
[HTTP] Fielding, Gettys, Mogul, Frystyk, Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2068, UC Irvine, DEC, MIT/LCS,
January 1997.
<ftp://ds.internic.net/rfc/rfc2068.txt>
[IMAIL] Crocker, "Standard for the Format of ARPA Internet Text
Messages", STD 11, RFC 822, University of Delaware, August 1982.
<ftp://ds.internic.net/rfc/rfc822.txt>
[KEYWORDS] Bradner, "Key words for use in RFCs to Indicate
Requirement Levels", RFC 2119, Harvard University, March 1997.
<ftp://ds.internic.net/rfc/rfc2119.txt>
[MIME] Freed, N., Borenstein, N., "Multipurpose Internet Mail
Extensions", RFC 2045, Innosoft, First Virtual, November 1996.
<ftp://ds.internic.net/rfc/rfc2045.txt>
[REL-URL] Fielding, "Relative Uniform Resource Locators", RFC 1808,
UC Irvine, June 1995.
<ftp://ds.internic.net/rfc/rfc1808.txt>
[UTF8] Yergeau, F. "UTF-8, a transformation format of Unicode and
ISO 10646", RFC 2044, Alis Technologies, October 1996.
<ftp://ds.internic.net/rfc/rfc2044.txt>
14. Author's Address
Chris Newman
Innosoft International, Inc.
1050 Lakes Drive
West Covina, CA 91790 USA
EMail: chris.newman@innosoft.com
Newman Standards Track [Page 11]
RFC 2192 IMAP URL Scheme September 1997
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.
#include <stdio.h>
#include <string.h>
/* hexadecimal lookup table */
static char hex[] = "0123456789ABCDEF";
/* URL unsafe printable characters */
static char urlunsafe[] = " \"#%&+:;<=>?@[\\]^`{|}";
/* UTF7 modified base64 alphabet */
static 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];
Newman Standards Track [Page 12]
RFC 2192 IMAP URL Scheme September 1997
/* initialize modified base64 decoding table */
memset(base64, UNDEFINED, sizeof (base64));
for (i = 0; i < sizeof (base64chars); ++i) {
base64[base64chars[i]] = i;
}
/* loop until end of string */
while (*src != '\0') {
c = *src++;
/* deal with literal characters and &- */
if (c != '&' || *src == '-') {
if (c < ' ' || c > '~' || strchr(urlunsafe, 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 {
ucs4 = utf16;
}
Newman Standards Track [Page 13]
RFC 2192 IMAP URL Scheme September 1997
/* convert UTF-16 range of UCS4 to UTF-8 */
if (ucs4 <= 0x7fUL) {
utf8[0] = ucs4;
i = 1;
} else if (ucs4 <= 0x7ffUL) {
utf8[0] = 0xc0 | (ucs4 >> 6);
utf8[1] = 0x80 | (ucs4 & 0x3f);
i = 2;
} else if (ucs4 <= 0xffffUL) {
utf8[0] = 0xe0 | (ucs4 >> 12);
utf8[1] = 0x80 | ((ucs4 >> 6) & 0x3f);
utf8[2] = 0x80 | (ucs4 & 0x3f);
i = 3;
} else {
utf8[0] = 0xf0 | (ucs4 >> 18);
utf8[1] = 0x80 | ((ucs4 >> 12) & 0x3f);
utf8[2] = 0x80 | ((ucs4 >> 6) & 0x3f);
utf8[3] = 0x80 | (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
*/
void URLtoMailbox(char *dst, char *src)
{
unsigned int utf8pos, utf8total, i, c, utf7mode, bitstogo, utf16flag;
unsigned long ucs4, bitbuf;
unsigned char hextab[256];
/* initialize hex lookup table */
Newman Standards Track [Page 14]
RFC 2192 IMAP URL Scheme September 1997
memset(hextab, 0, sizeof (hextab));
for (i = 0; i < sizeof (hex); ++i) {
hextab[hex[i]] = i;
if (isupper(hex[i])) hextab[tolower(hex[i])] = i;
}
utf7mode = 0;
utf8total = 0;
bitstogo = 0;
while ((c = *src) != '\0') {
++src;
/* undo hex-encoding */
if (c == '%' && src[0] != '\0' && src[1] != '\0') {
c = (hextab[src[0]] << 4) | hextab[src[1]];
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;
}
*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) {
/* save UTF8 bits into UCS4 */
ucs4 = (ucs4 << 6) | (c & 0x3FUL);
if (++utf8pos < utf8total) {
continue;
}
Newman Standards Track [Page 15]
RFC 2192 IMAP URL Scheme September 1997
} else {
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;
}
/* 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)
: 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';
}
Newman Standards Track [Page 16]

507
docs/rfcs/rfc2193.IMAP4_Mailbox_referrals.txt Normal file
View File

@ -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]

283
docs/rfcs/rfc2195.IMAP-POP_AUTHorize_extension.txt Normal file
View File

@ -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]

283
docs/rfcs/rfc2221.IMAP4_Login_referrals.txt Normal file
View File

@ -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]

4035
docs/rfcs/rfc2244.ACAP.txt Normal file
View File

File diff suppressed because it is too large Load Diff

563
docs/rfcs/rfc2342.IMAP4_Namespace.txt Normal file
View File

@ -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]

339
docs/rfcs/rfc2359.IMAP4_UIDPLUS_extension.txt Normal file
View File

@ -0,0 +1,339 @@
Network Working Group J. Myers
Request for Comments: 2359 Netscape Communications
Category: Standards Track June 1998
IMAP4 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 (1998). All Rights Reserved.
IESG NOTE
The IMAP extension described here assumes a particular means of using
IMAP to support disconnected operation. However, this means of
supporting disconnected operation is not yet documented. Also, there
are multiple theories about how best to do disconnected operation in
IMAP, and as yet, there is no consensus on which one should be
adopted as a standard.
This document is being approved as a Proposed Standard because it
does not appear to have technical flaws in itelf. However, approval
of this document as a Proposed Standard should not be considered an
IETF endorsement of any particular means of doing disconnected
operation in IMAP.
Table of Contents
1. Abstract .............................................. 2
2. Conventions Used in this Document ..................... 2
3. Introduction and Overview ............................. 2
4. Features .............................................. 2
4.1. UID EXPUNGE Command ................................... 2
4.2. APPENDUID response code ............................... 3
4.3. COPYUID response code ................................. 4
5. Formal Syntax ......................................... 4
6. References ............................................ 4
7. Security Considerations ............................... 5
8. Author's Address ...................................... 5
9. Full Copyright Statement .............................. 6
Myers Standards Track [Page 1]
RFC 2359 IMAP4 UIDPLUS extension June 1998
1. Abstract
The UIDPLUS extension of the Internet Message Access Protocol [IMAP4]
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.
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].
3. Introduction and Overview
The UIDPLUS extension is present in any IMAP4 server implementation
which returns "UIDPLUS" as one of the supported capabilities to the
CAPABILITY command. The UIDPLUS extension contains one additional
command and additional data returned with successful APPEND and COPY
commands.
Clients that wish to use the new command in UIDPLUS must of course
first test for the presence of the extension by issuing a CAPABILITY
command. Each of the features in UIDPLUS are optimizations; clients
can provide the same functionality, albeit more slowly, by using
commands in the base protocol. With each feature, this document
recommends a fallback approach to take when the UIDPLUS extension is
not supported by the server.
4. Features
4.1. UID EXPUNGE Command
Arguments: message set
Data: untagged responses: EXPUNGE
Result: OK - expunge completed
NO - expunge failure (e.g. permission denied)
BAD - command unknown or arguments invalid
Myers Standards Track [Page 2]
RFC 2359 IMAP4 UIDPLUS extension June 1998
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 is has a
UID that is not included in the specified message set, it is not
affected.
This command may be used to ensure that a replayed EXPUNGE command
does not remove any messages that have been marked as \Deleted
between the time that the user requested the expunge operation and
the time the server processes the command.
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. The
client could alternatively fall back to using the EXPUNGE command,
risking the unintended removal of some messages.
Example: C: A003 UID EXPUNGE 3000:3002
S: * 3 EXPUNGE
S: * 3 EXPUNGE
S: * 3 EXPUNGE
S: A003 OK UID EXPUNGE completed
4.2. APPENDUID response code
Successful APPEND commands return an APPENDUID response code in the
tagged OK response. The APPENDUID response code contains as
arguments the UIDVALIDITY of the destination mailbox and the UID
assigned to the appended message.
If the server does not support the UIDPLUS capability, the client can
only discover this information by selecting the destination mailbox
and issuing FETCH commands.
Example: C: A003 APPEND saved-messages (\Seen) {310}
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 [APPENDUID 38505 3955] APPEND completed
Myers Standards Track [Page 3]
RFC 2359 IMAP4 UIDPLUS extension June 1998
4.3. COPYUID response code
Successful COPY and UID COPY commands return a COPYUID response code
in the tagged OK response whenever at least one message was copied.
The COPYUID response code contains as an argument the UIDVALIDITY of
the appended-to mailbox, a message set containing the UIDs of the
messages copied to the destination mailbox, in the order they were
copied, and a message containing the UIDs assigned to the copied
messages, in the order they were assigned. Neither of the message
sets may contain extraneous UIDs or the symbol '*'.
If the server does not support the UIDPLUS capability, the client can
only discover this information by selecting the destination mailbox
and issuing FETCH commands.
Example: C: A003 COPY 2:4 MEETING
S: A003 OK [COPYUID 38505 304,319:320 3956:3958] Done
C: A003 UID COPY 305:310 MEETING
S: A003 OK Done
5. 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.
resp_code_apnd ::= "APPENDUID" SPACE nz_number SPACE uniqueid
resp_code_copy ::= "COPYUID" SPACE nz_number SPACE set SPACE set
uid_expunge ::= "UID" SPACE "EXPUNGE" SPACE set
6. References
[IMAP4] Crispin, M., "Internet Message Access Protocol -
Version 4rev1", RFC 2060, December 1996.
[KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC-822] Crocker, D., "Standard for the Format of ARPA Internet
Text Messages", STD 11, RFC 822, August 1982.
Myers Standards Track [Page 4]
RFC 2359 IMAP4 UIDPLUS extension June 1998
7. Security Considerations
There are no known security issues with this extension.
8. Author's Address
John Gardiner Myers
Netscape Communications
501 East Middlefield Road
Mail Stop MV-029
Mountain View, CA 94043
EMail: jgmyers@netscape.com
Myers Standards Track [Page 5]
RFC 2359 IMAP4 UIDPLUS extension June 1998
9. 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.
Myers Standards Track [Page 6]

843
docs/rfcs/rfc2595.TLS_with_IMAP-POP3_and_ACAP.txt Normal file
View File

@ -0,0 +1,843 @@
Network Working Group C. Newman
Request for Comments: 2595 Innosoft
Category: Standards Track June 1999
Using TLS with IMAP, POP3 and ACAP
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 (1999). All Rights Reserved.
1. Motivation
The TLS protocol (formerly known as SSL) provides a way to secure an
application protocol from tampering and eavesdropping. The option of
using such security is desirable for IMAP, POP and ACAP due to common
connection eavesdropping and hijacking attacks [AUTH]. Although
advanced SASL authentication mechanisms can provide a lightweight
version of this service, TLS is complimentary to simple
authentication-only SASL mechanisms or deployed clear-text password
login commands.
Many sites have a high investment in authentication infrastructure
(e.g., a large database of a one-way-function applied to user
passwords), so a privacy layer which is not tightly bound to user
authentication can protect against network eavesdropping attacks
without requiring a new authentication infrastructure and/or forcing
all users to change their password. Recognizing that such sites will
desire simple password authentication in combination with TLS
encryption, this specification defines the PLAIN SASL mechanism for
use with protocols which lack a simple password authentication
command such as ACAP and SMTP. (Note there is a separate RFC for the
STARTTLS command in SMTP [SMTPTLS].)
There is a strong desire in the IETF to eliminate the transmission of
clear-text passwords over unencrypted channels. While SASL can be
used for this purpose, TLS provides an additional tool with different
deployability characteristics. A server supporting both TLS with
Newman Standards Track [Page 1]
RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
simple passwords and a challenge/response SASL mechanism is likely to
interoperate with a wide variety of clients without resorting to
unencrypted clear-text passwords.
The STARTTLS command rectifies a number of the problems with using a
separate port for a "secure" protocol variant. Some of these are
mentioned in section 7.
1.1. Conventions Used in this Document
The key words "REQUIRED", "MUST", "MUST NOT", "SHOULD", "SHOULD NOT",
"MAY", and "OPTIONAL" in this document are to be interpreted as
described in "Key words for use in RFCs to Indicate Requirement
Levels" [KEYWORDS].
Terms related to authentication are defined in "On Internet
Authentication" [AUTH].
Formal syntax is defined using ABNF [ABNF].
In examples, "C:" and "S:" indicate lines sent by the client and
server respectively.
2. Basic Interoperability and Security Requirements
The following requirements apply to all implementations of the
STARTTLS extension for IMAP, POP3 and ACAP.
2.1. Cipher Suite Requirements
Implementation of the TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA [TLS] cipher
suite is REQUIRED. This is important as it assures that any two
compliant implementations can be configured to interoperate.
All other cipher suites are OPTIONAL.
2.2. Privacy Operational Mode Security Requirements
Both clients and servers SHOULD have a privacy operational mode which
refuses authentication unless successful activation of an encryption
layer (such as that provided by TLS) occurs prior to or at the time
of authentication and which will terminate the connection if that
encryption layer is deactivated. Implementations are encouraged to
have flexability with respect to the minimal encryption strength or
cipher suites permitted. A minimalist approach to this
recommendation would be an operational mode where the
TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA cipher suite is mandatory prior to
permitting authentication.
Newman Standards Track [Page 2]
RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
Clients MAY have an operational mode which uses encryption only when
it is advertised by the server, but authentication continues
regardless. For backwards compatibility, servers SHOULD have an
operational mode where only the authentication mechanisms required by
the relevant base protocol specification are needed to successfully
authenticate.
2.3. Clear-Text Password Requirements
Clients and servers which implement STARTTLS MUST be configurable to
refuse all clear-text login commands or mechanisms (including both
standards-track and nonstandard mechanisms) unless an encryption
layer of adequate strength is active. Servers which allow
unencrypted clear-text logins SHOULD be configurable to refuse
clear-text logins both for the entire server, and on a per-user
basis.
2.4. Server Identity Check
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. 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.
- 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.
If the match fails, the client SHOULD either ask for explicit user
confirmation, or terminate the connection and indicate the server's
identity is suspect.
Newman Standards Track [Page 3]
RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
2.5. TLS Security Policy Check
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. Ignoring this step
completely invalidates using TLS for security. The decision about
whether acceptable authentication or privacy was achieved is made
locally, is implementation-dependent, and is beyond the scope of this
document.
3. IMAP STARTTLS extension
When the TLS extension is present in IMAP, "STARTTLS" is listed as a
capability in response to the CAPABILITY command. This extension
adds a single command, "STARTTLS" to the IMAP protocol which is used
to begin a TLS negotiation.
3.1. STARTTLS Command
Arguments: none
Responses: no specific responses for this command
Result: OK - 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 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
[SASL] EXTERNAL mechanism MAY be used to authenticate once TLS
client credentials are successfully exchanged, but servers
supporting the STARTTLS command are not required to support the
EXTERNAL mechanism.
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.
The formal syntax for IMAP is amended as follows:
Newman Standards Track [Page 4]
RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
command_any =/ "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=EXTERNAL
S: a003 OK CAPABILITY completed
C: a004 LOGIN joe password
S: a004 OK LOGIN completed
3.2. IMAP LOGINDISABLED capability
The current IMAP protocol specification (RFC 2060) requires the
implementation of the LOGIN command which uses clear-text passwords.
Many sites may choose to disable this command unless encryption is
active for security reasons. An IMAP server MAY advertise that the
LOGIN command is disabled by including the LOGINDISABLED capability
in the capability response. Such a server will respond with a tagged
"NO" response to any attempt to use the LOGIN command.
An IMAP server which implements STARTTLS MUST implement support for
the LOGINDISABLED capability on unencrypted connections.
An IMAP client which complies with this specification MUST NOT issue
the LOGIN command if this capability is present.
This capability is useful to prevent clients compliant with this
specification from sending an unencrypted password in an environment
subject to passive attacks. It has no impact on an environment
subject to active attacks as a man-in-the-middle attacker can remove
this capability. Therefore this does not relieve clients of the need
to follow the privacy mode recommendation in section 2.2.
Servers advertising this capability will fail to interoperate with
many existing compliant IMAP clients and will be unable to prevent
those clients from disclosing the user's password.
4. POP3 STARTTLS extension
The POP3 STARTTLS extension adds the STLS command to POP3 servers.
If this is implemented, the POP3 extension mechanism [POP3EXT] MUST
also be implemented to avoid the need for client probing of multiple
commands. The capability name "STLS" indicates this command is
present and permitted in the current state.
Newman Standards Track [Page 5]
RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
STLS
Arguments: none
Restrictions:
Only permitted in AUTHORIZATION state.
Discussion:
A TLS negotiation begins immediately after the CRLF at the
end of the +OK response from the server. A -ERR response
MAY result if a security layer is already active. Once a
client issues a STLS command, it MUST NOT issue further
commands until a server response is seen and the TLS
negotiation is complete.
The STLS command is only permitted in AUTHORIZATION state
and the server remains in AUTHORIZATION state, even if
client credentials are supplied during the TLS negotiation.
The AUTH command [POP-AUTH] with the EXTERNAL mechanism
[SASL] MAY be used to authenticate once TLS client
credentials are successfully exchanged, but servers
supporting the STLS command are not required to support the
EXTERNAL mechanism.
Once TLS has been started, the client MUST discard cached
information about server capabilities and SHOULD re-issue
the CAPA command. This is necessary to protect against
man-in-the-middle attacks which alter the capabilities list
prior to STLS. The server MAY advertise different
capabilities after STLS.
Possible Responses:
+OK -ERR
Examples:
C: STLS
S: +OK Begin TLS negotiation
<TLS negotiation, further commands are under TLS layer>
...
C: STLS
S: -ERR Command not permitted when TLS active
Newman Standards Track [Page 6]
RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
5. ACAP STARTTLS extension
When the TLS extension is present in ACAP, "STARTTLS" is listed as a
capability in the ACAP greeting. No arguments to this capability are
defined at this time. This extension adds a single command,
"STARTTLS" to the ACAP protocol which is used to begin a TLS
negotiation.
5.1. STARTTLS Command
Arguments: none
Responses: no specific responses for this command
Result: OK - 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 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
[SASL] EXTERNAL mechanism MAY be used to authenticate once TLS
client credentials are successfully exchanged, but servers
supporting the STARTTLS command are not required to support the
EXTERNAL mechanism.
After the TLS layer is established, the server MUST re-issue an
untagged ACAP greeting. This is necessary to protect against
man-in-the-middle attacks which alter the capabilities list prior
to STARTTLS. The client MUST discard cached capability
information and replace it with the information from the new ACAP
greeting. The server MAY advertise different capabilities after
STARTTLS.
The formal syntax for ACAP is amended as follows:
command_any =/ "STARTTLS"
Example: S: * ACAP (SASL "CRAM-MD5") (STARTTLS)
C: a002 STARTTLS
S: a002 OK "Begin TLS negotiation now"
<TLS negotiation, further commands are under TLS layer>
S: * ACAP (SASL "CRAM-MD5" "PLAIN" "EXTERNAL")
Newman Standards Track [Page 7]
RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
6. PLAIN SASL mechanism
Clear-text 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 an unencrypted network connection.
This defines the "PLAIN" SASL mechanism for use with ACAP and other
protocols with no clear-text login command. The PLAIN SASL mechanism
MUST NOT be advertised or used unless a strong encryption layer (such
as the provided by TLS) is active or backwards compatibility dictates
otherwise.
The mechanism consists of a single message from the client to the
server. The client sends the authorization identity (identity to
login as), followed by a US-ASCII NUL character, followed by the
authentication identity (identity whose password will be used),
followed by a US-ASCII NUL character, followed by the clear-text
password. The client may leave the authorization identity empty to
indicate that it is the same as the authentication identity.
The server will verify the authentication identity and password with
the system authentication database and verify that the authentication
credentials permit the client to login as the authorization identity.
If both steps succeed, the user is logged in.
The server MAY also use the password to initialize any new
authentication database, such as one suitable for CRAM-MD5
[CRAM-MD5].
Non-US-ASCII characters are permitted as long as they are represented
in UTF-8 [UTF-8]. Use of non-visible characters or characters which
a user may be unable to enter on some keyboards is discouraged.
The formal grammar for the client message using Augmented BNF [ABNF]
follows.
message = [authorize-id] NUL authenticate-id NUL password
authenticate-id = 1*UTF8-SAFE ; MUST accept up to 255 octets
authorize-id = 1*UTF8-SAFE ; MUST accept up to 255 octets
password = 1*UTF8-SAFE ; MUST accept up to 255 octets
NUL = %x00
UTF8-SAFE = %x01-09 / %x0B-0C / %x0E-7F / UTF8-2 /
UTF8-3 / UTF8-4 / UTF8-5 / UTF8-6
UTF8-1 = %x80-BF
UTF8-2 = %xC0-DF UTF8-1
UTF8-3 = %xE0-EF 2UTF8-1
Newman Standards Track [Page 8]
RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
UTF8-4 = %xF0-F7 3UTF8-1
UTF8-5 = %xF8-FB 4UTF8-1
UTF8-6 = %xFC-FD 5UTF8-1
Here is an example of how this might be used to initialize a CRAM-MD5
authentication database for ACAP:
Example: S: * ACAP (SASL "CRAM-MD5") (STARTTLS)
C: a001 AUTHENTICATE "CRAM-MD5"
S: + "<1896.697170952@postoffice.reston.mci.net>"
C: "tim b913a602c7eda7a495b4e6e7334d3890"
S: a001 NO (TRANSITION-NEEDED)
"Please change your password, or use TLS to login"
C: a002 STARTTLS
S: a002 OK "Begin TLS negotiation now"
<TLS negotiation, further commands are under TLS layer>
S: * ACAP (SASL "CRAM-MD5" "PLAIN" "EXTERNAL")
C: a003 AUTHENTICATE "PLAIN" {21+}
C: <NUL>tim<NUL>tanstaaftanstaaf
S: a003 OK CRAM-MD5 password initialized
Note: In this example, <NUL> represents a single ASCII NUL octet.
7. imaps and pop3s ports
Separate "imaps" and "pop3s" ports were registered for use with SSL.
Use of these ports is discouraged in favor of the STARTTLS or STLS
commands.
A number of problems have been observed with separate ports for
"secure" variants of protocols. This is an attempt to enumerate some
of those problems.
- Separate ports lead to a separate URL scheme which intrudes into
the user interface in inappropriate ways. For example, many web
pages use language like "click here if your browser supports SSL."
This is a decision the browser is often more capable of making than
the user.
- Separate ports imply a model of either "secure" or "not secure."
This can be misleading in a number of ways. First, the "secure"
port may not in fact be acceptably secure as an export-crippled
cipher suite might be in use. This can mislead users into a false
sense of security. Second, the normal port might in fact be
secured by using a SASL mechanism which includes a security layer.
Thus the separate port distinction makes the complex topic of
security policy even more confusing. One common result of this
confusion is that firewall administrators are often misled into
Newman Standards Track [Page 9]
RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
permitting the "secure" port and blocking the standard port. This
could be a poor choice given the common use of SSL with a 40-bit
key encryption layer and plain-text password authentication is less
secure than strong SASL mechanisms such as GSSAPI with Kerberos 5.
- Use of separate ports for SSL has caused clients to implement only
two security policies: use SSL or don't use SSL. The desirable
security policy "use TLS when available" would be cumbersome with
the separate port model, but is simple with STARTTLS.
- Port numbers are a limited resource. While they are not yet in
short supply, it is unwise to set a precedent that could double (or
worse) the speed of their consumption.
8. IANA Considerations
This constitutes registration of the "STARTTLS" and "LOGINDISABLED"
IMAP capabilities as required by section 7.2.1 of RFC 2060 [IMAP].
The registration for the POP3 "STLS" capability follows:
CAPA tag: STLS
Arguments: none
Added commands: STLS
Standard commands affected: May enable USER/PASS as a side-effect.
CAPA command SHOULD be re-issued after successful completion.
Announced states/Valid states: AUTHORIZATION state only.
Specification reference: this memo
The registration for the ACAP "STARTTLS" capability follows:
Capability name: STARTTLS
Capability keyword: STARTTLS
Capability arguments: none
Published Specification(s): this memo
Person and email address for further information:
see author's address section below
The registration for the PLAIN SASL mechanism follows:
SASL mechanism name: PLAIN
Security Considerations: See section 9 of this memo
Published specification: this memo
Person & email address to contact for further information:
see author's address section below
Intended usage: COMMON
Author/Change controller: see author's address section below
Newman Standards Track [Page 10]
RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
9. Security Considerations
TLS only provides protection for data sent over a network connection.
Messages transferred over IMAP or POP3 are still available to server
administrators and usually subject to eavesdropping, tampering and
forgery when transmitted through SMTP or NNTP. TLS is no substitute
for an end-to-end message security mechanism using MIME security
multiparts [MIME-SEC].
A man-in-the-middle attacker can remove STARTTLS from the capability
list or generate a failure response to the STARTTLS command. In
order to detect such an attack, clients SHOULD warn the user when
session privacy is not active and/or be configurable to refuse to
proceed without an acceptable level of security.
A man-in-the-middle attacker can always cause a down-negotiation to
the weakest authentication mechanism or cipher suite available. For
this reason, implementations SHOULD be configurable to refuse weak
mechanisms or cipher suites.
Any protocol interactions prior to the TLS handshake are performed in
the clear and can be modified by a man-in-the-middle attacker. For
this reason, clients MUST discard cached information about server
capabilities advertised prior to the start of the TLS handshake.
Clients are encouraged to clearly indicate when the level of
encryption active is known to be vulnerable to attack using modern
hardware (such as encryption keys with 56 bits of entropy or less).
The LOGINDISABLED IMAP capability (discussed in section 3.2) only
reduces the potential for passive attacks, it provides no protection
against active attacks. The responsibility remains with the client
to avoid sending a password over a vulnerable channel.
The PLAIN mechanism relies on the TLS encryption layer for security.
When used without TLS, it is vulnerable to a common network
eavesdropping attack. Therefore PLAIN MUST NOT be advertised or used
unless a suitable TLS encryption layer is active or backwards
compatibility dictates otherwise.
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 network privacy
mechanisms. While many other authentication mechanisms have similar
weaknesses, stronger SASL mechanisms such as Kerberos address this
issue. Clients are encouraged to have an operational mode where all
mechanisms which are likely to reveal the user's password to the
server are disabled.
Newman Standards Track [Page 11]
RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
The security considerations for TLS apply to STARTTLS and the
security considerations for SASL apply to the PLAIN mechanism.
Additional security requirements are discussed in section 2.
10. References
[ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 2234, November 1997.
[ACAP] Newman, C. and J. Myers, "ACAP -- Application
Configuration Access Protocol", RFC 2244, November 1997.
[AUTH] Haller, N. and R. Atkinson, "On Internet Authentication",
RFC 1704, October 1994.
[CRAM-MD5] Klensin, J., Catoe, R. and P. Krumviede, "IMAP/POP
AUTHorize Extension for Simple Challenge/Response", RFC
2195, September 1997.
[IMAP] Crispin, M., "Internet Message Access Protocol - Version
4rev1", RFC 2060, December 1996.
[KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[MIME-SEC] Galvin, J., Murphy, S., Crocker, S. and N. Freed,
"Security Multiparts for MIME: Multipart/Signed and
Multipart/Encrypted", RFC 1847, October 1995.
[POP3] Myers, J. and M. Rose, "Post Office Protocol - Version 3",
STD 53, RFC 1939, May 1996.
[POP3EXT] Gellens, R., Newman, C. and L. Lundblade, "POP3 Extension
Mechanism", RFC 2449, November 1998.
[POP-AUTH] Myers, J., "POP3 AUTHentication command", RFC 1734,
December 1994.
[SASL] Myers, J., "Simple Authentication and Security Layer
(SASL)", RFC 2222, October 1997.
[SMTPTLS] Hoffman, P., "SMTP Service Extension for Secure SMTP over
TLS", RFC 2487, January 1999.
[TLS] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
RFC 2246, January 1999.
Newman Standards Track [Page 12]
RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
[UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO
10646", RFC 2279, January 1998.
11. Author's Address
Chris Newman
Innosoft International, Inc.
1050 Lakes Drive
West Covina, CA 91790 USA
EMail: chris.newman@innosoft.com
A. Appendix -- Compliance Checklist
An implementation is not compliant if it fails to satisfy one or more
of the MUST requirements for the protocols it implements. An
implementation that satisfies all the MUST and all the SHOULD
requirements for its protocols is said to be "unconditionally
compliant"; one that satisfies all the MUST requirements but not all
the SHOULD requirements for its protocols is said to be
"conditionally compliant".
Rules Section
----- -------
Mandatory-to-implement Cipher Suite 2.1
SHOULD have mode where encryption required 2.2
server SHOULD have mode where TLS not required 2.2
MUST be configurable to refuse all clear-text login
commands or mechanisms 2.3
server SHOULD be configurable to refuse clear-text
login commands on entire server and on per-user basis 2.3
client MUST check server identity 2.4
client MUST use hostname used to open connection 2.4
client MUST NOT use hostname from insecure remote lookup 2.4
client SHOULD support subjectAltName of dNSName type 2.4
client SHOULD ask for confirmation or terminate on fail 2.4
MUST check result of STARTTLS for acceptable privacy 2.5
client MUST NOT issue commands after STARTTLS
until server response and negotiation done 3.1,4,5.1
client MUST discard cached information 3.1,4,5.1,9
client SHOULD re-issue CAPABILITY/CAPA command 3.1,4
IMAP server with STARTTLS MUST implement LOGINDISABLED 3.2
IMAP client MUST NOT issue LOGIN if LOGINDISABLED 3.2
POP server MUST implement POP3 extensions 4
ACAP server MUST re-issue ACAP greeting 5.1
Newman Standards Track [Page 13]
RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
client SHOULD warn when session privacy not active and/or
refuse to proceed without acceptable security level 9
SHOULD be configurable to refuse weak mechanisms or
cipher suites 9
The PLAIN mechanism is an optional part of this specification.
However if it is implemented the following rules apply:
Rules Section
----- -------
MUST NOT use PLAIN unless strong encryption active
or backwards compatibility dictates otherwise 6,9
MUST use UTF-8 encoding for characters in PLAIN 6
Newman Standards Track [Page 14]
RFC 2595 Using TLS with IMAP, POP3 and ACAP June 1999
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.
Newman Standards Track [Page 15]

1291
docs/rfcs/rfc2683.IMAP4_Implementation_recommendations.txt Normal file
View File

File diff suppressed because it is too large Load Diff

1515
docs/rfcs/rfc2831.Obsolete_Digest_AUTHentication_as_a_SASL_mech.txt Normal file
View File

File diff suppressed because it is too large Load Diff

451
docs/rfcs/rfc2971.IMAP4_ID_extension.txt Normal file
View File

@ -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]

2019
docs/rfcs/rfc3028.Sieve_Mail_filtering_language.txt Normal file
View File

File diff suppressed because it is too large Load Diff

339
docs/rfcs/rfc3348.IMAP4_Child_Mailbox_extension.txt Normal file
View File

@ -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]

6051
docs/rfcs/rfc3501.IMAP4rev1.txt Normal file
View File

File diff suppressed because it is too large Load Diff

395
docs/rfcs/rfc3502.MULTIAPPEND_extension.txt Normal file
View File

@ -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]

507
docs/rfcs/rfc3503.Message_Disposition_Notification.txt Normal file
View File

@ -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]

451
docs/rfcs/rfc3516.IMAP4_Binary_content_extension.txt Normal file
View File

@ -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]

283
docs/rfcs/rfc3691.IMAP_UNSELECT_command.txt Normal file
View File

@ -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]

1515
docs/rfcs/rfc4314.IMAP4_ACL_extension.txt Normal file
View File

File diff suppressed because it is too large Load Diff

451
docs/rfcs/rfc4315.IMAP_UIDPLUS_extension.txt Normal file
View File

@ -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]

955
docs/rfcs/rfc4466.Collected_extensions_to_IMAP4_ABNF.txt Normal file
View File

@ -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]

1011
docs/rfcs/rfc4467.IMAP_URLAUTH_extension.txt Normal file
View File

File diff suppressed because it is too large Load Diff

731
docs/rfcs/rfc4469.IMAP_CATENATE_extension.txt Normal file
View File

@ -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]

1963
docs/rfcs/rfc4549.Sync_operations_for_disconnected_IMAP4_Clients.txt Normal file
View File

File diff suppressed because it is too large Load Diff

1403
docs/rfcs/rfc4551.IMAP_Conditional_STORE_or_Quick_flag_changes_resync.txt Normal file
View File

File diff suppressed because it is too large Load Diff

451
docs/rfcs/rfc4731.IMAP4_Extension_to_SEARCH_command.txt Normal file
View File

@ -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]

507
docs/rfcs/rfc4978.IMAP_Compress_extension.txt Normal file
View File

@ -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]

283
docs/rfcs/rfc5032.IMAP_WITHIN_Search_extension.txt Normal file
View File

@ -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]

395
docs/rfcs/rfc5161.IMAP_ENABLE_extension.txt Normal file
View File

@ -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]

1291
docs/rfcs/rfc5162.IMAP4_Extensions_for_Quick_Mailbox_resync.txt Normal file
View File

File diff suppressed because it is too large Load Diff

731
docs/rfcs/rfc5182.IMAP_extension_last_SEARCH_result.txt Normal file
View File

@ -0,0 +1,731 @@
Network Working Group A. Melnikov
Request for Comments: 5182 Isode Ltd.
Updates: 3501 March 2008
Category: Standards Track
IMAP Extension for Referencing the Last SEARCH Result
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
Many IMAP clients use the result of a SEARCH command as the input to
perform another operation, for example, fetching the found messages,
deleting them, or copying them to another mailbox.
This can be achieved using standard IMAP operations described in RFC
3501; however, this would be suboptimal. The server will send the
list of found messages to the client; after that, the client will
have to parse the list, reformat it, and send it back to the server.
The client can't pipeline the SEARCH command with the subsequent
command, and, as a result, the server might not be able to perform
some optimizations.
This document proposes an IMAP extension that allows a client to tell
a server to use the result of a SEARCH (or Unique Identifier (UID)
SEARCH) command as an input to any subsequent command.
1. Introduction
Many IMAP clients use the result of a SEARCH command as the input to
perform another operation, for example, fetching the found messages,
deleting them, or copying them to another mailbox.
This document proposes an IMAP extension that allows a client to tell
a server to use the result of a SEARCH (or UID SEARCH) command as an
input to any subsequent command.
The SEARCH result reference extension defines a new SEARCH result
option [IMAPABNF] "SAVE" that tells the server to remember the result
of the SEARCH or UID SEARCH command (as well as any command based on
SEARCH, e.g., SORT and THREAD [SORT]) and store it in an internal
Melnikov Standards Track [Page 1]
RFC 5182 Last SEARCH Result Reference March 2008
variable that we will reference as the "search result variable". The
client can use the "$" marker to reference the content of this
internal variable. The "$" marker can be used instead of message
sequence or UID sequence in order to indicate that the server should
substitute it with the list of messages from the search result
variable. Thus, the client can use the result of the latest
remembered SEARCH command as a parameter to another command. The
search result marker has several advantages:
* it avoids wasted bandwidth and associated delay;
* it allows the client to pipeline a SEARCH [IMAP4] command with a
subsequent FETCH/STORE/COPY/SEARCH [IMAP4] or UID EXPUNGE
[UIDPLUS] command;
* the client doesn't need to spend time reformatting the result of
a SEARCH command into a message set used in the subsequent
command;
* it allows the server to perform optimizations. For example, if
the server can execute several pipelined commands in parallel
(or out of order), presence of the search result marker can
allow the server to decide which commands may or may not be
executed out of order.
In absence of any other SEARCH result option, the SAVE result option
also suppresses any SEARCH response that would have been otherwise
returned by the SEARCH command.
1.1. Conventions Used in This Document
In examples, "C:" indicates lines sent by a client that is connected
to a server. "S:" indicates lines sent by the server to the client.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [KEYWORDS].
Explanatory comments in examples start with // and are not part of
the protocol.
Melnikov Standards Track [Page 2]
RFC 5182 Last SEARCH Result Reference March 2008
2. Overview
2.1. Normative Description of the SEARCHRES Extension
The SEARCH result reference extension described in this document is
present in any IMAP4 server implementation that returns "SEARCHRES"
as one of the supported capabilities in the CAPABILITY command
response. Any such server MUST also implement the [ESEARCH]
extension.
Upon successful completion of a SELECT or an EXAMINE command (after
the tagged OK response), the current search result variable is reset
to the empty sequence.
A successful SEARCH command with the SAVE result option sets the
value of the search result variable to the list of messages found in
the SEARCH command. For example, if no messages were found, the
search result variable will contain the empty list.
Any of the following SEARCH commands MUST NOT change the search
result variable:
o a SEARCH command that caused the server to return the BAD tagged
response,
o a SEARCH command with no SAVE result option that caused the
server to return NO tagged response,
o a successful SEARCH command with no SAVE result option.
A SEARCH command with the SAVE result option that caused the server
to return the NO tagged response sets the value of the search result
variable to the empty sequence.
When a message listed in the search result variable is EXPUNGEd, it
is automatically removed from the list. Implementors are reminded
that if the server stores the list as a list of message numbers, it
MUST automatically adjust them when notifying the client about
expunged messages, as described in Section 7.4.1 of [IMAP4].
If the server decides to send a new UIDVALIDITY value while the
mailbox is opened, this causes resetting of the search variable to
the empty list.
Melnikov Standards Track [Page 3]
RFC 5182 Last SEARCH Result Reference March 2008
Note that even if the "$" marker contains the empty list of messages,
it must be treated by all commands accepting message sets as
parameters as a valid, but non-matching list of messages. For
example, the "FETCH $" command would return a tagged OK response and
no FETCH responses. See also the Example 5 below.
Note that even if the "$" marker contains the empty list of messages,
it must be treated as a valid but non-matching list of messages, by
all commands that accept message sets as parameters.
Implementation note: server implementors should note that "$" can
reference IMAP message sequences or UID sequences, depending on the
context where it is used. For example, the "$" marker can be set as
a result of a SEARCH (SAVE) command and used as a parameter to a UID
FETCH command (which accepts a UID sequence, not a message sequence),
or the "$" marker can be set as a result of a UID SEARCH (SAVE)
command and used as a parameter to a FETCH command (which accepts a
message sequence, not a UID sequence).
2.2. Examples
1) The following example demonstrates how the client can use the
result of a SEARCH command to FETCH headers of interesting
messages:
Example 1:
C: A282 SEARCH RETURN (SAVE) FLAGGED SINCE 1-Feb-1994
NOT FROM "Smith"
S: A282 OK SEARCH completed, result saved
C: A283 FETCH $ (UID INTERNALDATE FLAGS RFC822.HEADER)
S: * 2 FETCH (UID 14 ...
S: * 84 FETCH (UID 100 ...
S: * 882 FETCH (UID 1115 ...
S: A283 OK completed
The client can also pipeline the two commands:
Example 2:
C: A282 SEARCH RETURN (SAVE) FLAGGED SINCE 1-Feb-1994
NOT FROM "Smith"
C: A283 FETCH $ (UID INTERNALDATE FLAGS RFC822.HEADER)
S: A282 OK SEARCH completed
S: * 2 FETCH (UID 14 ...
S: * 84 FETCH (UID 100 ...
S: * 882 FETCH (UID 1115 ...
S: A283 OK completed
Melnikov Standards Track [Page 4]
RFC 5182 Last SEARCH Result Reference March 2008
2) The following example demonstrates that the result of one SEARCH
command can be used as input to another SEARCH command:
Example 3:
C: A300 SEARCH RETURN (SAVE) SINCE 1-Jan-2004
NOT FROM "Smith"
S: A300 OK SEARCH completed
C: A301 UID SEARCH UID $ SMALLER 4096
S: * SEARCH 17 900 901
S: A301 OK completed
Note that the second command in Example 3 can be replaced with:
C: A301 UID SEARCH $ SMALLER 4096
and the result of the command would be the same.
3) The following example shows that the "$"
marker can be combined with other message numbers using the OR
SEARCH criterion.
Example 4:
C: P282 SEARCH RETURN (SAVE) SINCE 1-Feb-1994
NOT FROM "Smith"
S: P282 OK SEARCH completed
C: P283 SEARCH CHARSET UTF-8 (OR $ 1,3000:3021) TEXT {8}
C: YYYYYYYY
S: * SEARCH 882 1102 3003 3005 3006
S: P283 OK completed
Note: Since this document format is restricted to 7-bit ASCII text,
it is not possible to show actual UTF-8 data. The "YYYYYYYY" is a
placeholder for what would be 8 octets of 8-bit data in an actual
transaction.
Melnikov Standards Track [Page 5]
RFC 5182 Last SEARCH Result Reference March 2008
4) The following example demonstrates that a failed SEARCH sets the
search result variable to the empty list.
Example 5:
C: B282 SEARCH RETURN (SAVE) SINCE 1-Feb-1994
NOT FROM "Smith"
S: B282 OK SEARCH completed
C: B283 SEARCH CHARSET KOI8-R (OR $ 1,3000:3021) TEXT {4}
C: XXXX
S: B283 NO [BADCHARSET UTF-8] KOI8-R is not supported
//After this command the saved result variable contains
//no messages. A client that wants to reissue the B283
//SEARCH command with another CHARSET would have to reissue
//the B282 command as well. One possible workaround for
//this is to include the desired CHARSET parameter
//in the earliest SEARCH RETURN (SAVE) command in a
//sequence of related SEARCH commands.
//A better approach might be to always use CHARSET UTF-8
//instead.
Note: Since this document format is restricted to 7-bit ASCII text,
it is not possible to show actual KOI8-R data. The "XXXX" is a
placeholder for what would be 4 octets of 8-bit data in an actual
transaction.
5) The following example demonstrates that it is not an error to use
the "$" marker when it contains no messages.
Example 6:
C: E282 SEARCH RETURN (SAVE) SINCE 28-Oct-2006
NOT FROM "Eric"
C: E283 COPY $ "Other Messages"
//The "$" contains no messages
S: E282 OK SEARCH completed
S: E283 OK COPY completed, nothing copied
2.3. Multiple Commands in Progress
Use of a SEARCH RETURN (SAVE) command followed by a command using the
"$" marker creates direct dependency between the two commands. As
directed by Section 5.5 of [IMAP4], a server MUST execute the two
commands in the order they were received. (A server capable of
out-of-order execution can in some cases execute the two commands in
parallel, for example, if a SEARCH RETURN (SAVE) is followed by
"SEARCH $", the search criteria from the first command can be
directly substituted into the second command.)
Melnikov Standards Track [Page 6]
RFC 5182 Last SEARCH Result Reference March 2008
A client supporting this extension MAY pipeline a SEARCH RETURN
(SAVE) command with one or more command using the "$" marker, as long
as this doesn't create an ambiguity, as described in Section 5.5 of
[IMAP4].
Example 7:
C: F282 SEARCH RETURN (SAVE) KEYWORD $Junk
C: F283 COPY $ "Junk"
C: F284 STORE $ +FLAGS.Silent (\Deleted)
S: F282 OK SEARCH completed
S: F283 OK COPY completed
S: F284 OK STORE completed
Example 8:
C: G282 SEARCH RETURN (SAVE) KEYWORD $Junk
C: G283 SEARCH RETURN (ALL) SINCE 28-Oct-2006
FROM "Eric"
//The server can execute the two SEARCH commands
//in any order, as they don't have any dependency.
//Note that the second command is making use of
//the [ESEARCH] extension.
S: * ESEARCH (TAG "G283") ALL 3:15,27,29:103
S: G283 OK SEARCH completed
S: G282 OK SEARCH completed
The following example demonstrates that the result of the second
SEARCH always overrides the result of the first.
Example 9:
C: H282 SEARCH RETURN (SAVE) KEYWORD $Junk
C: H283 SEARCH RETURN (SAVE) SINCE 28-Oct-2006
FROM "Eric"
S: H282 OK SEARCH completed
S: H283 OK SEARCH completed
2.4. Interaction with ESEARCH Extension
Servers that implement the extension defined in this document MUST
implement [ESEARCH] and conform to additional requirements listed in
this section.
The SAVE result option doesn't change whether the server would return
items corresponding to MIN, MAX, ALL, or COUNT [ESEARCH] result
options.
Melnikov Standards Track [Page 7]
RFC 5182 Last SEARCH Result Reference March 2008
When the SAVE result option is combined with the MIN or MAX [ESEARCH]
result option, and none of the other ESEARCH result options are
present, the corresponding MIN/MAX is returned (if the search result
is not empty), but the "$" marker would contain a single message as
returned in the MIN/MAX return item.
If the SAVE result option is combined with both MIN and MAX result
options, and none of the other ESEARCH result options are present,
the "$" marker would contain one or two messages as returned in the
MIN/MAX return items.
If the SAVE result option is combined with the ALL and/or COUNT
result option(s), the "$" marker would always contain all messages
found by the SEARCH or UID SEARCH command. (Note that the last rule
might affect ESEARCH implementations that optimize how the COUNT
result is constructed.)
The following table summarizes the additional requirement on ESEARCH
server implementations described in this section.
+----------------+-------------------+
| Combination of | "$" marker value |
| Result option | |
+----------------+-------------------+
| SAVE MIN | MIN |
+----------------+-------------------+
| SAVE MAX | MAX |
+----------------+-------------------+
| SAVE MIN MAX | MIN & MAX |
+----------------+-------------------+
| SAVE * [m] | all found messages|
+----------------+-------------------+
where '*' means "ALL" and/or "COUNT"
'[m]' means optional "MIN" and/or "MAX"
Melnikov Standards Track [Page 8]
RFC 5182 Last SEARCH Result Reference March 2008
The following example demonstrates behavioral difference for
different combinations of ESEARCH result options. Explanatory
comments start with // and are not part of the protocol:
Example 10:
C: C282 SEARCH RETURN (ALL) SINCE 12-Feb-2006
NOT FROM "Smith"
S: * ESEARCH (TAG "C283") ALL 2,10:15,21
//$ value hasn't changed
S: C282 OK SEARCH completed
C: C283 SEARCH RETURN (ALL SAVE) SINCE 12-Feb-2006
NOT FROM "Smith"
S: * ESEARCH (TAG "C283") ALL 2,10:15,21
//$ value is 2,10:15,21
S: C283 OK SEARCH completed
C: C284 SEARCH RETURN (SAVE MIN) SINCE 12-Feb-2006
NOT FROM "Smith"
S: * ESEARCH (TAG "C284") MIN 2
//$ value is 2
S: C284 OK SEARCH completed
C: C285 SEARCH RETURN (MAX SAVE MIN) SINCE
12-Feb-2006 NOT FROM "Smith"
S: * ESEARCH (TAG "C285") MIN 2 MAX 21
//$ value is 2,21
S: C285 OK SEARCH completed
C: C286 SEARCH RETURN (MAX SAVE MIN COUNT)
SINCE 12-Feb-2006 NOT FROM "Smith"
S: * ESEARCH (TAG "C286") MIN 2 MAX 21 COUNT 8
//$ value is 2,10:15,21
S: C286 OK SEARCH completed
C: C286 SEARCH RETURN (ALL SAVE MIN) SINCE
12-Feb-2006 NOT FROM "Smith"
S: * ESEARCH (TAG "C286") MIN 2 ALL 2,10:15,21
//$ value is 2,10:15,21
S: C286 OK SEARCH completed
Melnikov Standards Track [Page 9]
RFC 5182 Last SEARCH Result Reference March 2008
2.5. Refusing to Save Search Results
In some cases, the server MAY refuse to save a SEARCH (SAVE) result,
for example, if an internal limit on the number of saved results is
reached.
In this case, the server MUST return a tagged NO response containing
the NOTSAVED response code and set the search result variable to the
empty sequence, as described in Section 2.1.
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 in [IMAP4] or
[IMAPABNF].
Except as noted otherwise, all alphabetic characters are
case-insensitive. The use of upper- or lower-case characters to
define token strings is for editorial clarity only. Implementations
MUST accept these strings in a case-insensitive fashion.
capability =/ "SEARCHRES"
;; capability is defined in [IMAP4]
sequence-set =/ seq-last-command
;; extends sequence-set to allow for
;; "result of the last command" indicator.
seq-last-command = "$"
search-return-opt = "SAVE"
;; conforms to generic search-return-opt
;; syntax defined in [IMAPABNF]
resp-text-code =/ "NOTSAVED"
;; <resp-text-code> from [IMAP4]
Melnikov Standards Track [Page 10]
RFC 5182 Last SEARCH Result Reference March 2008
4. Security Considerations
This extension requires the server to keep additional state, that may
be used to simplify Denial of Service attacks. In order to minimize
damage from such attacks, server implementations MAY limit the number
of saved searches they allow across all connections at any given time
and return the tagged NO response containing the NOTSAVED response
code (see Section 2.5) to a SEARCH RETURN (SAVE) command when this
limit is exceeded.
Apart from that, it is believed that this extension doesn't raise any
additional security concerns not already discussed in [IMAP4].
5. IANA Considerations
This document defines the "SEARCHRES" IMAP capability. IANA has
added it to the IMAP4 Capabilities Registry, which is currently
located at:
http://www.iana.org/assignments/imap4-capabilities
6. Acknowledgments
The author would like to thank Mark Crispin, Cyrus Daboo, and Curtis
King for remembering that this document had to be written, as well as
for comments and corrections received.
The author would also like to thank Dave Cridland, Mark Crispin,
Chris Newman, Dan Karp, and Spencer Dawkins for comments and
corrections received.
Valuable comments, both in agreement and in dissent, were received
from Arnt Gulbrandsen.
Melnikov Standards Track [Page 11]
RFC 5182 Last SEARCH Result Reference March 2008
7. References
7.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., Ed., and P. Overell, "Augmented BNF for
Syntax Specifications: ABNF", STD 68, RFC 5234, January
2008.
[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.
[ESEARCH] Melnikov, A. and D. Cridland, "IMAP4 Extension to SEARCH
Command for Controlling What Kind of Information Is
Returned", RFC 4731, November 2006.
7.2. Informative References
[UIDPLUS] Crispin, M., "Internet Message Access Protocol (IMAP) -
UIDPLUS extension", RFC 4315, December 2005.
[SORT] Crispin, M. and K. Murchison, "INTERNET MESSAGE ACCESS
PROTOCOL - SORT AND THREAD EXTENSIONS", Work in Progress,
Septemeber 2007.
Author's Address
Alexey Melnikov
Isode Ltd.
5 Castle Business Village,
36 Station Road,
Hampton, Middlesex,
TW12 2BX, United Kingdom
EMail: Alexey.Melnikov@isode.com
Melnikov Standards Track [Page 12]
RFC 5182 Last SEARCH Result Reference 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 Standards Track [Page 13]

2355
docs/rfcs/rfc5182.Sieve_and_extensions.txt Normal file
View File

File diff suppressed because it is too large Load Diff

1123
docs/rfcs/rfc5255.IMAP_i18n.txt Normal file
View File

File diff suppressed because it is too large Load Diff

1739
docs/rfcs/rfc5257.IMAP_ANNOTATE_extension.txt Normal file
View File

File diff suppressed because it is too large Load Diff

1739
docs/rfcs/rfc5258.IMAP4_LIST_command_extension.txt Normal file
View File

File diff suppressed because it is too large Load Diff

955
docs/rfcs/rfc5423.IM_Store_Events.txt Normal file
View File

@ -0,0 +1,955 @@
Network Working Group R. Gellens
Request for Comments: 5423 QUALCOMM Inc.
Category: Standards Track C. Newman
Sun Microsystems
March 2009
Internet Message Store Events
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (c) 2009 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents in effect on the date of
publication of this document (http://trustee.ietf.org/license-info).
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document.
Abstract
One of the missing features in the existing Internet mail and
messaging standards is a facility for server-to-server and server-to-
client event notifications related to message store events. As the
scope of Internet mail expands to support more diverse media (such as
voice mail) and devices (such as cell phones) and to provide rich
interactions with other services (such as web portals and legal
compliance systems), the need for an interoperable notification
system increases. This document attempts to enumerate the types of
events that interest real-world consumers of such a system.
This document describes events and event parameters that are useful
for several cases, including notification to administrative systems
and end users. This is not intended as a replacement for a message
access facility such as IMAP.
Gellens & Newman Standards Track [Page 1]
RFC 5423 Internet Message Store Events March 2009
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Conventions Used in This Document . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Event Model . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. Event Types . . . . . . . . . . . . . . . . . . . . . . . . . 5
4.1. Message Addition and Deletion . . . . . . . . . . . . . . 5
4.2. Message Flags . . . . . . . . . . . . . . . . . . . . . . 7
4.3. Access Accounting . . . . . . . . . . . . . . . . . . . . 8
4.4. Mailbox Management . . . . . . . . . . . . . . . . . . . . 8
5. Event Parameters . . . . . . . . . . . . . . . . . . . . . . . 10
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
7. Security Considerations . . . . . . . . . . . . . . . . . . . 14
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 15
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15
9.1. Normative References . . . . . . . . . . . . . . . . . . . 15
9.2. Informative References . . . . . . . . . . . . . . . . . . 15
Appendix A. Future Extensions . . . . . . . . . . . . . . . . . . 17
1. Introduction
A message store is used to organize Internet Messages [RFC5322] into
one or more mailboxes (possibly hierarchical), annotate them in
various ways, and provide access to these messages and associated
metadata. Three different standards-based protocols have been widely
deployed to remotely access a message store. The Post Office
Protocol (POP) [RFC1939] provides simple download-and-delete access
to a single mail drop (which is a subset of the functionality
typically associated with a message store). The Internet Message
Access Protocol (IMAP) [RFC3501] provides an extensible feature-rich
model for online, offline, and disconnected access to a message store
with minimal constraints on any associated "fat-client" user
interface. Finally, mail access applications built on top of the
Hypertext Transfer Protocol (HTTP) [RFC2616] that run in standards-
based web browsers provide a third standards-based access mechanism
for online-only access.
While simple and/or ad-hoc mechanisms for notifications have sufficed
to some degree in the past (e.g., "Simple New Mail Notification"
[RFC4146], "IMAP4 IDLE Command" [RFC2177]), as the scope and
importance of message stores expand, the demand for a more complete
store notification system increases. Some of the driving forces
behind this demand include:
o Mobile devices with intermittent network connectivity that have
"new mail" or "message count" indicators.
Gellens & Newman Standards Track [Page 2]
RFC 5423 Internet Message Store Events March 2009
o Unified messaging systems that include both Internet and voice
mail require support for a message-waiting indicator on phones.
o Interaction with systems for event-based or utility-computing
billing.
o Simplification of the process of passing message store events to
non-Internet notification systems.
o A calendar system may wish to subscribe to MessageNew
notifications in order to support iMIP [RFC2447].
o Some jurisdictions have laws or regulations for information
protection and auditing that require interoperable protocols
between message stores built by messaging experts and compliance
auditing systems built by compliance experts.
Vendors who have deployed proprietary notification systems for their
Internet message stores have seen significant demand to provide
notifications for more and more events. As a first step towards
building a notification system, this document attempts to enumerate
the core events that real-world customers demand.
This document includes those events that can be generated by the use
of IMAP4rev1 [RFC3501] and some existing extensions. As new IMAP
extensions are defined, or additional event types or parameters need
to be added, the set specified here can be extended by means of an
IANA registry with update requirements, as specified in Section 6.
1.1. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119].
When these words appear in lower-case or with initial capital
letters, they are not RFC 2119 key words.
2. Terminology
The following terminology is used in this document:
mailbox
A container for Internet messages and/or child mailboxes. A
mailbox may or may not permit delivery of new messages via a mail
delivery agent.
Gellens & Newman Standards Track [Page 3]
RFC 5423 Internet Message Store Events March 2009
mailbox identifier
A mailbox identifier provides sufficient information to identify a
specific mailbox on a specific server instance. An IMAP URL can
be a mailbox identifier.
message access protocols
Protocols that provide clients (e.g., a mail user agent or web
browser) with access to the message store, including but not
limited to IMAP, POP, and HTTP.
message context
As defined in [RFC3458].
UIDVALIDITY
As defined in IMAP4rev1 [RFC3501]. UIDVALIDITY is critical to the
correct operation of a caching mail client. When it changes, the
client MUST flush its cache. It's particularly important to
include UIDVALIDITY with event notifications related to message
addition or removal in order to keep the message data correctly
synchronized.
3. Event Model
The events that are generated by a message store depend to some
degree on the model used to represent a message store. The model the
IETF has for a message store is implicit from IMAP4rev1 and
extensions, so that model is assumed by this document.
A message store event typically has an associated mailbox name and
usually has an associated user name (or authorization identity if
using the terminology from "Simple Authentication and Security Layer"
(SASL) [RFC4422]). Events referring to a specific message can use an
IMAP URL [RFC5092] to do so. Events referring to a set of messages
can use an IMAP URL to the mailbox plus an IMAP UID (Unique
Identifier) set.
Each notification has a type and parameters. The type determines the
type of event, while the parameters supply information about the
context of the event that may be used to adjust subscription
preferences or may simply supply data associated with the event. The
types and parameter names in this document are restricted to US-ASCII
printable characters, so these events can be easily mapped to an
arbitrary notification system. However, this document assumes that
arbitrary parameter values (including large and multi-line values)
can be encoded with the notification system. Systems which lack that
feature could only implement a subset of these events.
Gellens & Newman Standards Track [Page 4]
RFC 5423 Internet Message Store Events March 2009
This document does not indicate which event parameters are mandatory
or optional. That is done in documents that specify specific message
formats or bindings to a notification system.
For scalability reasons, some degree of filtering at event generation
is necessary. At the very least, the ability to turn on and off
groups of related events and to suppress inclusion of large
parameters (such as messageContent) is needed. A sophisticated
publish/subscribe notification system may be able to propagate
cumulative subscription information to the publisher.
Some of these events might be logically collapsed into a single event
type with a required parameter to distinguish between the cases
(e.g., QuotaExceed and QuotaWithin). However, until such time that
an event subscription model is formulated, it's not practical to make
such decisions. We thus note only the fact that some of these events
may be viewed as a single event type.
4. Event Types
This section discusses the different types of events useful in a
message store event notification system. The intention is to
document the events sufficient to cover an overwhelming majority of
known use cases while leaving less common event types for the future.
This section mentions parameters that are important or specific to
the events described here. Event parameters likely to be included in
most or all notifications are discussed in the next section.
4.1. Message Addition and Deletion
This section includes events related to message addition and
deletion.
MessageAppend
A message was appended or concatenated to a mailbox by a message
access client. For the most part, this is identical to the
MessageNew event type except that the SMTP envelope information is
not included as a parameter, but information about which protocol
triggered the event MAY be included. See the MessageNew event for
more information.
MessageExpire
One or more messages were expired from a mailbox due to server
expiration policy and are no longer accessible by the end user.
The parameters include a mailbox identifier that MUST include
UIDVALIDITY and a UID set that describes the messages.
Gellens & Newman Standards Track [Page 5]
RFC 5423 Internet Message Store Events March 2009
Information about which server expiration policy was applied may
be included in the future.
MessageExpunge
One or more messages were expunged from a mailbox by an IMAP
CLOSE/EXPUNGE, POP3 DELE+QUIT, HTTP, or equivalent client action
and are no longer accessible by the end user.
The parameters include a mailbox identifier that MUST include
UIDVALIDITY, a UID set, and MAY also indicate which access
protocol triggered the event.
MessageNew
A new message was received into a mailbox via a message delivery
agent.
The parameters include a message identifier that, for IMAP-
accessible message stores, MUST include UIDVALIDITY and a UID.
The parameters MAY also include an SMTP envelope and other
arbitrary message and mailbox metadata. In some cases, the entire
new message itself may be included. The set of parameters SHOULD
be adjustable to the client's preference, with limits set by
server policy. An interesting policy, for example, would be to
include messages up to 2K in size with the notification, but to
include a URLAUTH [RFC4467] reference for larger messages.
QuotaExceed
An operation failed (typically MessageNew) because the user's
mailbox exceeded one of the quotas (e.g., disk quota, message
quota, quota by message context, etc.). The parameters SHOULD
include at least the relevant user and quota and, optionally, the
mailbox. Quota usage SHOULD be included if possible. Parameters
needed to extend this to support quota by context are not
presently described in this document but could be added in the
future.
QuotaWithin
An operation occurred (typically MessageExpunge or MessageExpire)
that reduced the user's quota usage under the limit.
QuotaChange
The user's quota was changed.
Gellens & Newman Standards Track [Page 6]
RFC 5423 Internet Message Store Events March 2009
4.2. Message Flags
This section includes events related to changes in message flags.
MessageRead
One or more messages in the mailbox were marked as read or seen by
a user. Note that POP has no concept of read or seen messages, so
these events are only generated by IMAP or HTTP clients (or
equivalent).
The parameters include a mailbox identifier and a set of message
UIDs.
MessageTrash
One or more messages were marked for future deletion by the user
but are still accessible over the protocol (the user's client may
or may not make these messages accessible through its user
interface).
The parameters include a mailbox identifier and a set of message
UIDs.
FlagsSet
One or more messages in the mailbox had one or more IMAP flags or
keywords set.
The parameters include a list of IMAP flag or keyword names that
were set, a mailbox identifier, and the set of UIDs of affected
messages. The flagNames MUST NOT include \Recent. For
compatibility with simpler clients, it SHOULD be configurable
whether setting the \Seen or \Deleted flags results in this event
or the simpler MessageRead/MessageTrash events. By default, the
simpler message forms SHOULD be used for MessageRead and
MessageTrash.
FlagsClear
One or more messages in the mailbox had one or more IMAP flags or
keywords cleared.
The parameters include a list of IMAP flag or keyword names that
were cleared, a mailbox identifier, and the set of UIDs of
affected messages. The flagNames parameter MUST NOT include
\Recent.
Gellens & Newman Standards Track [Page 7]
RFC 5423 Internet Message Store Events March 2009
4.3. Access Accounting
This section lists events related to message store access accounting.
Login
A user has logged into the system via IMAP, HTTP, POP, or some
other mechanism.
The parameters include the domain name and port used to access the
server and the user's authorization identity. Additional possible
parameters include the client's IP address and port, the
authentication identity (if different from the authorization
identity), the service name, the authentication mechanism,
information about any negotiated security layers, a timestamp, and
other information.
Logout
A user has logged out or otherwise been disconnected from the
message store via IMAP, HTTP, POP, or some other mechanism.
The parameters include the server domain name and the user's
authorization identity. Additional parameters MAY include any of
the information from the "Login" event as well as information
about the type of disconnect (suggested values include graceful,
abort, timeout, and security layer error), the duration of the
connection or session, and other information.
4.4. Mailbox Management
This section lists events related to the management of mailboxes.
MailboxCreate
A mailbox has been created, or an access control changed on an
existing mailbox so that it is now accessible by the user. If the
mailbox creation caused the creation of new mailboxes earlier in
the hierarchy, separate MailboxCreate events are not generated, as
their creation is implied.
The parameters include the created mailbox identifier, its
UIDVALIDITY for IMAP-accessible message stores, and MAY also
indicate which access protocol triggered the event. Access and
permissions information (such as Access Control List (ACL)
[RFC4314] settings) require a standardized format to be included,
and so are left for future extension.
Gellens & Newman Standards Track [Page 8]
RFC 5423 Internet Message Store Events March 2009
MailboxDelete
A mailbox has been deleted, or an access control changed on an
existing mailbox so that it is no longer accessible by the user.
Note that if the mailbox has child mailboxes, only the specified
mailbox has been deleted, not the children. The mailbox becomes
\NOSELECT, and the hierarchy remains unchanged, as per the
description of the DELETE command in IMAP4rev1 [RFC3501].
The parameters include the deleted mailbox identifier and MAY also
indicate which access protocol triggered the event.
MailboxRename
A mailbox has been renamed. Note that, per the description of the
RENAME command in IMAP4rev1 [RFC3501], special semantics regarding
the mailbox hierarchy apply when INBOX is renamed (child mailboxes
are usually included in the rename, but are excluded when INBOX is
renamed). When a mailbox other than INBOX is renamed and its
child mailboxes are also renamed as a result, separate
MailboxRename events are not generated for the child mailboxes, as
their renaming is implied. If the rename caused the creation of
new mailboxes earlier in the hierarchy, separate MailboxCreate
events are not generated for those, as their creation is implied.
When INBOX is renamed, a new INBOX is created. A MailboxCreate
event is not generated for the new INBOX, since it is implied.
The parameters include the old mailbox identifier, the new mailbox
identifier, and MAY also indicate which access protocol triggered
the event.
MailboxSubscribe
A mailbox has been added to the server-stored subscription list,
such as the one managed by the IMAP SUBSCRIBE and UNSUBSCRIBE
commands.
The parameters include the user whose subscription list has been
affected, the mailbox identifier, and MAY also indicate which
access protocol triggered the event.
MailboxUnSubscribe
A mailbox has been removed from the subscription list.
The parameters include the user whose subscription list has been
affected, the mailbox identifier, and MAY also indicate which
access protocol triggered the event.
Gellens & Newman Standards Track [Page 9]
RFC 5423 Internet Message Store Events March 2009
5. Event Parameters
This section lists parameters included with these events.
admin
Included with all events generated by message access protocols.
The authentication identity associated with this event, as
distinct from the authorization identity (see "user"). This is
not included when it is the same as the value of the user
parameter.
bodyStructure
May be included with MessageAppend and MessageNew.
The IMAP BODYSTRUCTURE of the message.
clientIP
Included with all events generated by message access protocols.
The IPv4 or IPv6 address of the message store access client that
performed the action that triggered the notification.
clientPort
Included with all events generated by message access protocols.
The port number of the message store access client that performed
an action that triggered the notification (the port from which the
connection occurred).
diskQuota
Included with QuotaExceed, QuotaWithin, and QuotaChange
notifications relating to a user or mailbox disk quota. May be
included with other notifications.
Disk quota limit in kilobytes (1024 octets).
diskUsed
Included with QuotaExceed and QuotaWithin notifications relating
to a user or mailbox disk quota. May be included with other
notifications.
Disk space used in kilobytes (1024 octets). Only disk space that
counts against the quota is included.
Gellens & Newman Standards Track [Page 10]
RFC 5423 Internet Message Store Events March 2009
envelope
May be included with the MessageNew notification.
The message transfer envelope associated with final delivery of
the message for the MessageNew notification. This includes the
MAIL FROM and relevant RCPT TO line(s) used for final delivery
with CRLF delimiters and any ESMTP parameters.
flagNames
Included with FlagsSet and FlagsClear events. May be included
with MessageAppend and MessageNew to indicate flags that were set
initially by the APPEND command or delivery agent, respectively.
A list (likely to be space-separated) of IMAP flag or keyword
names that were set or cleared. Flag names begin with a backslash
while keyword names do not. The \Recent flag is explicitly not
permitted in the list.
mailboxID
Included in events that affect mailboxes. A URI describing the
mailbox. In the case of MailboxRename, this refers to the new
name.
maxMessages
Included with QuotaExceed and QuotaWithin notifications relating
to a user or mailbox message count quota. May be included with
other notifications.
Quota limit on the number of messages in the mailbox, for events
referring to a mailbox.
messageContent
May be included with MessageAppend and MessageNew.
The entire message itself. Size-based suppression of this SHOULD
be available.
messageSize
May be included with MessageAppend and MessageNew.
Size of the RFC 5322 message itself in octets. This value matches
the length of the IMAP literal returned in response to an IMAP
FETCH of BODY[] for the referenced message.
Gellens & Newman Standards Track [Page 11]
RFC 5423 Internet Message Store Events March 2009
messages
Included with QuotaExceed and QuotaWithin notifications relating
to a user or mailbox message count quota. May be included with
other notifications.
Number of messages in the mailbox. This is typically included
with message addition and deletion events.
modseq
May be included with any notification referring to one message.
This is the 64-bit integer MODSEQ as defined in [RFC4551]. No
assumptions about MODSEQ can be made if this is omitted.
oldMailboxID
A URI describing the old name of a renamed or moved mailbox.
pid
May be included with any notification.
The process ID of the process that generated the notification.
process
May be included with any notification.
The name of the process that generated the notification.
serverDomain
Included in Login and optionally in Logout or other events. The
domain name or IP address (v4 or v6) used to access the server or
mailbox.
serverPort
Included in Login and optionally in Logout or other events. The
port number used to access the server. This is often a well-known
port.
serverFQDN
May be included with any notification.
The fully qualified domain name of the server that generated the
event. Note that this may be different from the server name used
to access the mailbox included in the mailbox identifier.
Gellens & Newman Standards Track [Page 12]
RFC 5423 Internet Message Store Events March 2009
service
May be included with any notification.
The name of the service that triggered the event. Suggested
values include "imap", "pop", "http", and "admincli" (for an
administrative client).
tags
May be included with any notification.
A list of UTF-8 tags (likely to be comma-separated). One or more
tags can be set at the time a notification criteria or
notification subscription is created. Subscribers can use tags
for additional client-side filtering or dispatch of events.
timestamp
May be included with any notification.
The time at which the event occurred that triggered the
notification (the underlying protocol carrying the notification
may contain a timestamp for when the notification was generated).
This MAY be an approximate time.
Timestamps are expressed in local time and contain the offset from
UTC (this information is used in several places in Internet mail)
and are normally in [RFC3339] format.
uidnext
May be included with any notification referring to a mailbox.
The UID that is projected to be assigned next in the mailbox.
This is typically included with message addition and deletion
events. This is equivalent to the UIDNEXT status item in the IMAP
STATUS command.
uidset
Included with MessageExpires, MessageExpunges, MessageRead,
MessageTrash, FlagsSet, and FlagsClear.
This includes the set of IMAP UIDs referenced.
uri
Included with all notifications. A reference to the IMAP server,
a mailbox, or a message.
Typically an IMAP URL. This can include the name of the server
used to access the mailbox/message, the mailbox name, the
UIDVALIDITY of the mailbox, and the UID of a specific message.
Gellens & Newman Standards Track [Page 13]
RFC 5423 Internet Message Store Events March 2009
user
Included with all events generated by message access protocols.
This is the authorization identifier used when the client
connected to the access protocol that triggered the event. Some
protocols (for example, many SASL mechanisms) distinguish between
authorization and authentication identifiers. For events
associated with a mailbox, this may be different from the owner of
the mailbox specified in the IMAP URL.
6. IANA Considerations
The IANA has created a new registry for "Internet Message Store
Events" that contains two sub-registries: event names and event
parameters. For both event names and event parameters, entries that
do not start with "vnd." are added by the IETF and are intended for
interoperable use. Entries that start with "vnd." are intended for
private use by one or more parties and are allocated to avoid
collisions.
The initial values are contained in this document.
Using IANA Considerations [RFC5226] terminology, entries that do not
start with "vnd." are allocated by IETF Consensus, while those
starting with "vnd." are allocated First Come First Served.
7. Security Considerations
Notifications can produce a large amount of traffic and expose
sensitive information. When notification mechanisms are used to
maintain state between different entities, the ability to corrupt or
manipulate notification messages could enable an attacker to modulate
the state of these entities. For example, if an attacker were able
to modify notifications sent from a message store to an auditing
server, he could modify the "user" and "messageContent" parameters in
MessageNew notifications to create false audit log entries.
A competent transfer protocol for notifications must consider
authentication, authorization, privacy, and message integrity, as
well as denial-of-service issues. While the IETF has adequate tools
and experience to address these issues for mechanisms that involve
only one TCP connection, notification or publish/subscribe protocols
that are more sophisticated than a single end-to-end TCP connection
will need to pay extra attention to these issues and carefully
balance requirements to successfully deploy a system with security
and privacy considerations.
Gellens & Newman Standards Track [Page 14]
RFC 5423 Internet Message Store Events March 2009
8. Acknowledgments
Alexey Melnikov, Arnt Gulbrandsen, and Zoltan Ordogh have reviewed
and offered improvements to this document. Richard Barnes did a nice
review during Last Call.
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.
[RFC5092] Melnikov, A. and C. Newman, "IMAP URL Scheme", RFC 5092,
November 2007.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
9.2. Informative References
[RFC1939] Myers, J. and M. Rose, "Post Office Protocol - Version 3",
STD 53, RFC 1939, May 1996.
[RFC2177] Leiba, B., "IMAP4 IDLE command", RFC 2177, June 1997.
[RFC2447] Dawson, F., Mansour, S., and S. Silverberg, "iCalendar
Message-Based Interoperability Protocol (iMIP)", RFC 2447,
November 1998.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
Internet: Timestamps", RFC 3339, July 2002.
[RFC3458] Burger, E., Candell, E., Eliot, C., and G. Klyne, "Message
Context for Internet Mail", RFC 3458, January 2003.
[RFC4146] Gellens, R., "Simple New Mail Notification", RFC 4146,
August 2005.
Gellens & Newman Standards Track [Page 15]
RFC 5423 Internet Message Store Events March 2009
[RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) Extension",
RFC 4314, December 2005.
[RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication and
Security Layer (SASL)", RFC 4422, June 2006.
[RFC4467] Crispin, M., "Internet Message Access Protocol (IMAP) -
URLAUTH Extension", RFC 4467, May 2006.
[RFC4551] Melnikov, A. and S. Hole, "IMAP Extension for Conditional
STORE Operation or Quick Flag Changes Resynchronization",
RFC 4551, June 2006.
[RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
October 2008.
Gellens & Newman Standards Track [Page 16]
RFC 5423 Internet Message Store Events March 2009
Appendix A. Future Extensions
This document specifies core functionality based on events that are
believed to be well understood, have known use cases, and are
implemented by at least one deployed real-world Internet message
store. (A few events are exceptions to the last test only: FlagsSet,
FlagsClear, MailboxCreate, MailboxDelete, MailboxRename,
MailboxSubscribe, and MailboxUnSubscribe.)
Some events have been suggested but are postponed to future
extensions because they do not meet this criteria. These events
include messages that have been moved to archive storage and may
require extra time to access, quota by message context,
authentication failure, user mail account disabled, annotations, and
mailbox ACL or metadata change. The descriptions of several events
note additional parameters that are likely candidates for future
inclusion. See Section 6 for how the list of events and parameters
can be extended.
In order to narrow the scope of this document to something that can
be completed, only events generated from the message store (by a
message access module, administrative module, or message delivery
agent) are considered. A complete mail system is normally linked
with an identity system that would also publish events of interest to
a message store event subscriber. Events of interest include account
created/deleted/disabled and password changed/expired.
Authors' Addresses
Randall Gellens
QUALCOMM Incorporated
5775 Morehouse Drive
San Diego, CA 92651
USA
Phone:
EMail: rg+ietf@qualcomm.com
Chris Newman
Sun Microsystems
800 Royal Oaks
Monrovia, CA 91016-6347
USA
Phone:
EMail: chris.newman@sun.com
Gellens & Newman Standards Track [Page 17]

1177
docs/rfcs/rfc5464.IMAP_METADATA_extension.txt Normal file
View File

File diff suppressed because it is too large Load Diff

1235
docs/rfcs/rfc5465.IMAP_NOTIFY_extension.txt Normal file
View File

File diff suppressed because it is too large Load Diff

507
docs/rfcs/rfc5530.IMAP_Response_codes.txt Normal file
View File

@ -0,0 +1,507 @@
Network Working Group A. Gulbrandsen
Request for Comments: 5530 Oryx Mail Systems GmbH
Category: Standards Track May 2009
IMAP Response Codes
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (c) 2009 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents in effect on the date of
publication of this document (http://trustee.ietf.org/license-info).
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document.
Abstract
IMAP responses consist of a response type (OK, NO, BAD), an optional
machine-readable response code, and a human-readable text.
This document collects and documents a variety of machine-readable
response codes, for better interoperation and error reporting.
Gulbrandsen Standards Track [Page 1]
RFC 5530 IMAP Response Codes May 2009
1. Introduction
Section 7.1 of [RFC3501] defines a number of response codes that can
help tell an IMAP client why a command failed. However, experience
has shown that more codes are useful. For example, it is useful for
a client to know that an authentication attempt failed because of a
server problem as opposed to a password problem.
Currently, many IMAP servers use English-language, human-readable
text to describe these errors, and a few IMAP clients attempt to
translate this text into the user's language.
This document names a variety of errors as response codes. It is
based on errors that have been checked and reported on in some IMAP
server implementations, and on the needs of some IMAP clients.
This document doesn't require any servers to test for these errors or
any clients to test for these names. It only names errors for better
reporting and handling.
2. Conventions Used in This Document
Formal syntax is defined by [RFC5234] as modified by [RFC3501].
Example lines prefaced by "C:" are sent by the client and ones
prefaced by "S:" by the server. "[...]" means elision.
3. Response Codes
This section defines all the new response codes. Each definition is
followed by one or more examples.
UNAVAILABLE
Temporary failure because a subsystem is down. For example, an
IMAP server that uses a Lightweight Directory Access Protocol
(LDAP) or Radius server for authentication might use this
response code when the LDAP/Radius server is down.
C: a LOGIN "fred" "foo"
S: a NO [UNAVAILABLE] User's backend down for maintenance
AUTHENTICATIONFAILED
Authentication failed for some reason on which the server is
unwilling to elaborate. Typically, this includes "unknown
user" and "bad password".
Gulbrandsen Standards Track [Page 2]
RFC 5530 IMAP Response Codes May 2009
This is the same as not sending any response code, except that
when a client sees AUTHENTICATIONFAILED, it knows that the
problem wasn't, e.g., UNAVAILABLE, so there's no point in
trying the same login/password again later.
C: b LOGIN "fred" "foo"
S: b NO [AUTHENTICATIONFAILED] Authentication failed
AUTHORIZATIONFAILED
Authentication succeeded in using the authentication identity,
but the server cannot or will not allow the authentication
identity to act as the requested authorization identity. This
is only applicable when the authentication and authorization
identities are different.
C: c1 AUTHENTICATE PLAIN
[...]
S: c1 NO [AUTHORIZATIONFAILED] No such authorization-ID
C: c2 AUTHENTICATE PLAIN
[...]
S: c2 NO [AUTHORIZATIONFAILED] Authenticator is not an admin
EXPIRED
Either authentication succeeded or the server no longer had the
necessary data; either way, access is no longer permitted using
that passphrase. The client or user should get a new
passphrase.
C: d login "fred" "foo"
S: d NO [EXPIRED] That password isn't valid any more
PRIVACYREQUIRED
The operation is not permitted due to a lack of privacy. If
Transport Layer Security (TLS) is not in use, the client could
try STARTTLS (see Section 6.2.1 of [RFC3501]) and then repeat
the operation.
C: d login "fred" "foo"
S: d NO [PRIVACYREQUIRED] Connection offers no privacy
C: d select inbox
S: d NO [PRIVACYREQUIRED] Connection offers no privacy
Gulbrandsen Standards Track [Page 3]
RFC 5530 IMAP Response Codes May 2009
CONTACTADMIN
The user should contact the system administrator or support
desk.
C: e login "fred" "foo"
S: e OK [CONTACTADMIN]
NOPERM
The access control system (e.g., Access Control List (ACL), see
[RFC4314]) does not permit this user to carry out an operation,
such as selecting or creating a mailbox.
C: f select "/archive/projects/experiment-iv"
S: f NO [NOPERM] Access denied
INUSE
An operation has not been carried out because it involves
sawing off a branch someone else is sitting on. Someone else
may be holding an exclusive lock needed for this operation, or
the operation may involve deleting a resource someone else is
using, typically a mailbox.
The operation may succeed if the client tries again later.
C: g delete "/archive/projects/experiment-iv"
S: g NO [INUSE] Mailbox in use
EXPUNGEISSUED
Someone else has issued an EXPUNGE for the same mailbox. The
client may want to issue NOOP soon. [RFC2180] discusses this
subject in depth.
C: h search from fred@example.com
S: * SEARCH 1 2 3 5 8 13 21 42
S: h OK [EXPUNGEISSUED] Search completed
CORRUPTION
The server discovered that some relevant data (e.g., the
mailbox) are corrupt. This response code does not include any
information about what's corrupt, but the server can write that
to its logfiles.
C: i select "/archive/projects/experiment-iv"
S: i NO [CORRUPTION] Cannot open mailbox
Gulbrandsen Standards Track [Page 4]
RFC 5530 IMAP Response Codes May 2009
SERVERBUG
The server encountered a bug in itself or violated one of its
own invariants.
C: j select "/archive/projects/experiment-iv"
S: j NO [SERVERBUG] This should not happen
CLIENTBUG
The server has detected a client bug. This can accompany all
of OK, NO, and BAD, depending on what the client bug is.
C: k1 select "/archive/projects/experiment-iv"
[...]
S: k1 OK [READ-ONLY] Done
C: k2 status "/archive/projects/experiment-iv" (messages)
[...]
S: k2 OK [CLIENTBUG] Done
CANNOT
The operation violates some invariant of the server and can
never succeed.
C: l create "///////"
S: l NO [CANNOT] Adjacent slashes are not supported
LIMIT
The operation ran up against an implementation limit of some
kind, such as the number of flags on a single message or the
number of flags used in a mailbox.
C: m STORE 42 FLAGS f1 f2 f3 f4 f5 ... f250
S: m NO [LIMIT] At most 32 flags in one mailbox supported
OVERQUOTA
The user would be over quota after the operation. (The user
may or may not be over quota already.)
Note that if the server sends OVERQUOTA but doesn't support the
IMAP QUOTA extension defined by [RFC2087], then there is a
quota, but the client cannot find out what the quota is.
C: n1 uid copy 1:* oldmail
S: n1 NO [OVERQUOTA] Sorry
C: n2 uid copy 1:* oldmail
S: n2 OK [OVERQUOTA] You are now over your soft quota
Gulbrandsen Standards Track [Page 5]
RFC 5530 IMAP Response Codes May 2009
ALREADYEXISTS
The operation attempts to create something that already exists,
such as when the CREATE or RENAME directories attempt to create
a mailbox and there is already one of that name.
C: o RENAME this that
S: o NO [ALREADYEXISTS] Mailbox "that" already exists
NONEXISTENT
The operation attempts to delete something that does not exist.
Similar to ALREADYEXISTS.
C: p RENAME this that
S: p NO [NONEXISTENT] No such mailbox
4. Formal Syntax
The following syntax specification uses the Augmented Backus-Naur
Form (ABNF) notation as specified in [RFC5234]. [RFC3501] defines
the non-terminal "resp-text-code".
Except as noted otherwise, all alphabetic characters are case-
insensitive. The use of upper or lowercase characters to define
token strings is for editorial clarity only.
resp-text-code =/ "UNAVAILABLE" / "AUTHENTICATIONFAILED" /
"AUTHORIZATIONFAILED" / "EXPIRED" /
"PRIVACYREQUIRED" / "CONTACTADMIN" / "NOPERM" /
"INUSE" / "EXPUNGEISSUED" / "CORRUPTION" /
"SERVERBUG" / "CLIENTBUG" / "CANNOT" /
"LIMIT" / "OVERQUOTA" / "ALREADYEXISTS" /
"NONEXISTENT"
5. Security Considerations
Revealing information about a passphrase to unauthenticated IMAP
clients causes bad karma.
Response codes are easier to parse than human-readable text. This
can amplify the consequences of an information leak. For example,
selecting a mailbox can fail because the mailbox doesn't exist,
because the user doesn't have the "l" right (right to know the
mailbox exists) or "r" right (right to read the mailbox). If the
server sent different responses in the first two cases in the past,
only malevolent clients would discover it. With response codes it's
possible, perhaps probable, that benevolent clients will forward the
Gulbrandsen Standards Track [Page 6]
RFC 5530 IMAP Response Codes May 2009
leaked information to the user. Server authors are encouraged to be
particularly careful with the NOPERM and authentication-related
responses.
6. IANA Considerations
The IANA has created the IMAP Response Codes registry. The registry
has been populated with the following codes:
NEWNAME RFC 2060 (obsolete)
REFERRAL RFC 2221
ALERT RFC 3501
BADCHARSET RFC 3501
PARSE RFC 3501
PERMANENTFLAGS RFC 3501
READ-ONLY RFC 3501
READ-WRITE RFC 3501
TRYCREATE RFC 3501
UIDNEXT RFC 3501
UIDVALIDITY RFC 3501
UNSEEN RFC 3501
UNKNOWN-CTE RFC 3516
UIDNOTSTICKY RFC 4315
APPENDUID RFC 4315
COPYUID RFC 4315
URLMECH RFC 4467
TOOBIG RFC 4469
BADURL RFC 4469
HIGHESTMODSEQ RFC 4551
NOMODSEQ RFC 4551
MODIFIED RFC 4551
COMPRESSIONACTIVE RFC 4978
CLOSED RFC 5162
NOTSAVED RFC 5182
BADCOMPARATOR RFC 5255
ANNOTATE RFC 5257
ANNOTATIONS RFC 5257
TEMPFAIL RFC 5259
MAXCONVERTMESSAGES RFC 5259
MAXCONVERTPARTS RFC 5259
NOUPDATE RFC 5267
METADATA RFC 5464
NOTIFICATIONOVERFLOW RFC 5465
BADEVENT RFC 5465
UNDEFINED-FILTER RFC 5466
UNAVAILABLE RFC 5530
AUTHENTICATIONFAILED RFC 5530
AUTHORIZATIONFAILED RFC 5530
Gulbrandsen Standards Track [Page 7]
RFC 5530 IMAP Response Codes May 2009
EXPIRED RFC 5530
PRIVACYREQUIRED RFC 5530
CONTACTADMIN RFC 5530
NOPERM RFC 5530
INUSE RFC 5530
EXPUNGEISSUED RFC 5530
CORRUPTION RFC 5530
SERVERBUG RFC 5530
CLIENTBUG RFC 5530
CANNOT RFC 5530
LIMIT RFC 5530
OVERQUOTA RFC 5530
ALREADYEXISTS RFC 5530
NONEXISTENT RFC 5530
The new registry can be extended by sending a registration request to
IANA. IANA will forward this request to a Designated Expert,
appointed by the responsible IESG Area Director, CCing it to the IMAP
Extensions mailing list at <ietf-imapext@imc.org> (or a successor
designated by the Area Director). After either allowing 30 days for
community input on the IMAP Extensions mailing list or a successful
IETF Last Call, the expert will determine the appropriateness of the
registration request and either approve or disapprove the request by
sending a notice of the decision to the requestor, CCing the IMAP
Extensions mailing list and IANA. A denial notice must be justified
by an explanation, and, in cases where it is possible, concrete
suggestions on how the request can be modified so as to become
acceptable should be provided.
For each response code, the registry contains a list of relevant RFCs
that describe (or extend) the response code and an optional response
code status description, such as "obsolete" or "reserved to prevent
collision with deployed software". (Note that in the latter case,
the RFC number can be missing.) Presence of the response code status
description means that the corresponding response code is NOT
RECOMMENDED for widespread use.
The intention is that any future allocation will be accompanied by a
published RFC (including direct submissions to the RFC Editor). But
in order to allow for the allocation of values prior to the RFC being
approved for publication, the Designated Expert can approve
allocations once it seems clear that an RFC will be published, for
example, before requesting IETF LC for the document.
The Designated Expert can also approve registrations for response
codes used in deployed software when no RFC exists. Such
registrations must be marked as "reserved to prevent collision with
deployed software".
Gulbrandsen Standards Track [Page 8]
RFC 5530 IMAP Response Codes May 2009
Response code registrations may not be deleted; response codes that
are no longer believed appropriate for use (for example, if there is
a problem with the syntax of said response code or if the
specification describing it was moved to Historic) should be marked
"obsolete" in the registry, clearly marking the lists published by
IANA.
7. Acknowledgements
Peter Coates, Mark Crispin, Philip Guenther, Alexey Melnikov, Ken
Murchison, Chris Newman, Timo Sirainen, Philip Van Hoof, Dale
Wiggins, and Sarah Wilkin helped with this document.
8. References
8.1. Normative References
[RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
4rev1", RFC 3501, March 2003.
[RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for
Syntax Specifications: ABNF", STD 68, RFC 5234, January
2008.
9. Informative References
[RFC2087] Myers, J., "IMAP4 QUOTA extension", RFC 2087, January
1997.
[RFC2180] Gahrns, M., "IMAP4 Multi-Accessed Mailbox Practice", RFC
2180, July 1997.
[RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) Extension",
RFC 4314, December 2005.
Author's Address
Arnt Gulbrandsen
Oryx Mail Systems GmbH
Schweppermannstr. 8
D-81671 Muenchen
Germany
Fax: +49 89 4502 9758
EMail: arnt@oryx.com
Gulbrandsen Standards Track [Page 9]

843
docs/rfcs/rfc5738.IMAP_UTF8.txt Normal file
View File

@ -0,0 +1,843 @@
Network Working Group P. Resnick
Request for Comments: 5738 Qualcomm Incorporated
Updates: 3501 C. Newman
Category: Experimental Sun Microsystems
March 2010
IMAP Support for UTF-8
Abstract
This specification extends the Internet Message Access Protocol
version 4rev1 (IMAP4rev1) to support UTF-8 encoded international
characters in user names, mail addresses, and message headers.
Status of This Memo
This document is not an Internet Standards Track specification; it is
published for examination, experimental implementation, and
evaluation.
This document defines an Experimental Protocol for the Internet
community. This document is a product of the Internet Engineering
Task Force (IETF). It represents the consensus of the IETF
community. It has received public review and has been approved for
publication by the Internet Engineering Steering Group (IESG). Not
all documents approved by the IESG are a candidate for any level of
Internet Standard; see Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc5738.
Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Resnick & Newman Experimental [Page 1]
RFC 5738 IMAP Support for UTF-8 March 2010
This document may contain material from IETF Documents or IETF
Contributions published or made publicly available before November
10, 2008. The person(s) controlling the copyright in some of this
material may not have granted the IETF Trust the right to allow
modifications of such material outside the IETF Standards Process.
Without obtaining an adequate license from the person(s) controlling
the copyright in such materials, this document may not be modified
outside the IETF Standards Process, and derivative works of it may
not be created outside the IETF Standards Process, except to format
it for publication as an RFC or to translate it into languages other
than English.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions Used in This Document . . . . . . . . . . . . . . 3
3. UTF8=ACCEPT IMAP Capability . . . . . . . . . . . . . . . . . 3
3.1. IMAP UTF-8 Quoted Strings . . . . . . . . . . . . . . . . 3
3.2. UTF8 Parameter to SELECT and EXAMINE . . . . . . . . . . . 5
3.3. UTF-8 LIST and LSUB Responses . . . . . . . . . . . . . . 5
3.4. UTF-8 Interaction with IMAP4 LIST Command Extensions . . . 6
3.4.1. UTF8 and UTF8ONLY LIST Selection Options . . . . . . . 6
3.4.2. UTF8 LIST Return Option . . . . . . . . . . . . . . . 6
4. UTF8=APPEND Capability . . . . . . . . . . . . . . . . . . . . 7
5. UTF8=USER Capability . . . . . . . . . . . . . . . . . . . . . 7
6. UTF8=ALL Capability . . . . . . . . . . . . . . . . . . . . . 7
7. UTF8=ONLY Capability . . . . . . . . . . . . . . . . . . . . . 8
8. Up-Conversion Server Requirements . . . . . . . . . . . . . . 8
9. Issues with UTF-8 Header Mailstore . . . . . . . . . . . . . . 9
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
11. Security Considerations . . . . . . . . . . . . . . . . . . . 11
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11
12.1. Normative References . . . . . . . . . . . . . . . . . . . 11
12.2. Informative References . . . . . . . . . . . . . . . . . . 13
Appendix A. Design Rationale . . . . . . . . . . . . . . . . . . 14
Appendix B. Examples Demonstrating Relationships between
UTF8= Capabilities . . . . . . . . . . . . . . . . . 15
Appendix C. Acknowledgments . . . . . . . . . . . . . . . . . . . 15
Resnick & Newman Experimental [Page 2]
RFC 5738 IMAP Support for UTF-8 March 2010
1. Introduction
This specification extends IMAP4rev1 [RFC3501] to permit UTF-8
[RFC3629] in headers as described in "Internationalized Email
Headers" [RFC5335]. It also adds a mechanism to support mailbox
names, login names, and passwords using the UTF-8 charset. This
specification creates five new IMAP capabilities to allow servers to
advertise these new extensions, along with two new IMAP LIST
selection options and a new IMAP LIST return option.
2. Conventions Used in This Document
The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
in this document are to be interpreted as defined in "Key words for
use in RFCs to Indicate Requirement Levels" [RFC2119].
The formal syntax uses the Augmented Backus-Naur Form (ABNF)
[RFC5234] notation including the core rules defined in Appendix B of
[RFC5234]. In addition, rules from IMAP4rev1 [RFC3501], UTF-8
[RFC3629], "Collected Extensions to IMAP4 ABNF" [RFC4466], and IMAP4
LIST Command Extensions [RFC5258] are also referenced.
In examples, "C:" and "S:" indicate lines sent by the client and
server, respectively. If a single "C:" or "S:" label applies to
multiple lines, then the line breaks between those lines are for
editorial clarity only and are not part of the actual protocol
exchange.
3. UTF8=ACCEPT IMAP Capability
The "UTF8=ACCEPT" capability indicates that the server supports UTF-8
quoted strings, the "UTF8" parameter to SELECT and EXAMINE, and UTF-8
responses from the LIST and LSUB commands.
A client MUST use the "ENABLE UTF8=ACCEPT" command (defined in
[RFC5161]) to indicate to the server that the client accepts UTF-8
quoted-strings. The "ENABLE UTF8=ACCEPT" command MUST only be used
in the authenticated state. (Note that the "UTF8=ONLY" capability
described in Section 7 and the "UTF8=ALL" capability described in
Section 6 imply the "UTF8=ACCEPT" capability. See additional
information in these sections.)
3.1. IMAP UTF-8 Quoted Strings
The IMAP4rev1 [RFC3501] base specification forbids the use of 8-bit
characters in atoms or quoted strings. Thus, a UTF-8 string can only
be sent as a literal. This can be inconvenient from a coding
standpoint, and unless the server offers IMAP4 non-synchronizing
Resnick & Newman Experimental [Page 3]
RFC 5738 IMAP Support for UTF-8 March 2010
literals [RFC2088], this requires an extra round trip for each UTF-8
string sent by the client. When the IMAP server advertises the
"UTF8=ACCEPT" capability, it informs the client that it supports
native UTF-8 quoted-strings with the following syntax:
string =/ utf8-quoted
utf8-quoted = "*" DQUOTE *UQUOTED-CHAR DQUOTE
UQUOTED-CHAR = QUOTED-CHAR / UTF8-2 / UTF8-3 / UTF8-4
; UTF8-2, UTF8-3, and UTF8-4 are as defined in RFC 3629
When this quoting mechanism is used by the client (specifically an
octet sequence beginning with *" and ending with "), then the server
MUST reject octet sequences with the high bit set that fail to comply
with the formal syntax in [RFC3629] with a BAD response.
The IMAP server MUST NOT send utf8-quoted syntax to the client unless
the client has indicated support for that syntax by using the "ENABLE
UTF8=ACCEPT" command.
If the server advertises the "UTF8=ACCEPT" capability, the client MAY
use utf8-quoted syntax with any IMAP argument that permits a string
(including astring and nstring). However, if characters outside the
US-ASCII repertoire are used in an inappropriate place, the results
would be the same as if other syntactically valid but semantically
invalid characters were used. For example, if the client includes
UTF-8 characters in the user or password arguments (and the server
has not advertised "UTF8=USER"), the LOGIN command will fail as it
would with any other invalid user name or password. Specific cases
where UTF-8 characters are permitted or not permitted are described
in the following paragraphs.
All IMAP servers that advertise the "UTF8=ACCEPT" capability SHOULD
accept UTF-8 in mailbox names, and those that also support the
"Mailbox International Naming Convention" described in RFC 3501,
Section 5.1.3 MUST accept utf8-quoted mailbox names and convert them
to the appropriate internal format. Mailbox names MUST comply with
the Net-Unicode Definition (Section 2 of [RFC5198]) with the specific
exception that they MUST NOT contain control characters (0000-001F,
0080-009F), delete (007F), line separator (2028), or paragraph
separator (2029).
An IMAP client MUST NOT issue a SEARCH command that uses a mixture of
utf8-quoted syntax and a SEARCH CHARSET other than UTF-8. If an IMAP
server receives such a SEARCH command, it SHOULD reject the command
with a BAD response (due to the conflicting charset labels).
Resnick & Newman Experimental [Page 4]
RFC 5738 IMAP Support for UTF-8 March 2010
3.2. UTF8 Parameter to SELECT and EXAMINE
The "UTF8=ACCEPT" capability also indicates that the server supports
the "UTF8" parameter to SELECT and EXAMINE. When a mailbox is
selected with the "UTF8" parameter, it alters the behavior of all
IMAP commands related to message sizes, message headers, and MIME
body headers so they refer to the message with UTF-8 headers. If the
mailstore is not UTF-8 header native and the SELECT or EXAMINE
command with UTF-8 header modifier succeeds, then the server MUST
return results as if the mailstore were UTF-8 header native with
upconversion requirements as described in Section 8. The server MAY
reject the SELECT or EXAMINE command with the [NOT-UTF-8] response
code, unless the "UTF8=ALL" or "UTF8=ONLY" capability is advertised.
Servers MAY include mailboxes that can only be selected or examined
if the "UTF8" parameter is provided. However, such mailboxes MUST
NOT be included in the output of an unextended LIST, LSUB, or
equivalent command. If a client attempts to SELECT or EXAMINE such
mailboxes without the "UTF8" parameter, the server MUST reject the
command with a [UTF-8-ONLY] response code. As a result, such
mailboxes will not be accessible by IMAP clients written prior to
this specification and are discouraged unless the server advertises
"UTF8=ONLY" or the server implements IMAP4 LIST Command Extensions
[RFC5258].
utf8-select-param = "UTF8"
;; Conforms to <select-param> from RFC 4466
C: a SELECT newmailbox (UTF8)
S: ...
S: a OK SELECT completed
C: b FETCH 1 (SIZE ENVELOPE BODY)
S: ... < UTF-8 header native results >
S: b OK FETCH completed
C: c EXAMINE legacymailbox (UTF8)
S: c NO [NOT-UTF-8] Mailbox does not support UTF-8 access
C: d SELECT funky-new-mailbox
S: d NO [UTF-8-ONLY] Mailbox requires UTF-8 client
3.3. UTF-8 LIST and LSUB Responses
After an IMAP client successfully issues an "ENABLE UTF8=ACCEPT"
command, the server MUST NOT return in LIST results any mailbox names
to the client following the IMAP4 Mailbox International Naming
Convention. Instead, the server MUST return any mailbox names with
characters outside the US-ASCII repertoire using utf8-quoted syntax.
Resnick & Newman Experimental [Page 5]
RFC 5738 IMAP Support for UTF-8 March 2010
(The IMAP4 Mailbox International Naming Convention has proved
problematic in the past, so the desire is to make this syntax
obsolete as quickly as possible.)
3.4. UTF-8 Interaction with IMAP4 LIST Command Extensions
When an IMAP server advertises both the "UTF8=ACCEPT" capability and
the "LIST-EXTENDED" [RFC5258] capability, the server MUST support the
LIST extensions described in this section.
3.4.1. UTF8 and UTF8ONLY LIST Selection Options
The "UTF8" LIST selection option tells the server to include
mailboxes that only support UTF-8 headers in the output of the list
command. The "UTF8ONLY" LIST selection option tells the server to
include all mailboxes that support UTF-8 headers and to exclude
mailboxes that don't support UTF-8 headers. Note that "UTF8ONLY"
implies "UTF8", so it is not necessary for the client to request
both. Use of either selection option will also result in UTF-8
mailbox names in the result as described in Section 3.3 and implies
the "UTF8" List return option described in Section 3.4.2.
3.4.2. UTF8 LIST Return Option
If the client supplies the "UTF8" LIST return option, then the server
MUST include either the "\NoUTF8" or the "\UTF8Only" mailbox
attribute as appropriate. The "\NoUTF8" mailbox attribute indicates
that an attempt to SELECT or EXAMINE that mailbox with the "UTF8"
parameter will fail with a [NOT-UTF-8] response code. The
"\UTF8Only" mailbox attribute indicates that an attempt to SELECT or
EXAMINE that mailbox without the "UTF8" parameter will fail with a
[UTF-8-ONLY] response code. Note that computing this information may
be expensive on some server implementations, so this return option
should not be used unless necessary.
The ABNF [RFC5234] for these LIST extensions follows:
list-select-independent-opt =/ "UTF8"
list-select-base-opt =/ "UTF8ONLY"
mbx-list-oflag =/ "\NoUTF8" / "\UTF8Only"
return-option =/ "UTF8"
resp-text-code =/ "NOT-UTF-8" / "UTF-8-ONLY"
Resnick & Newman Experimental [Page 6]
RFC 5738 IMAP Support for UTF-8 March 2010
4. UTF8=APPEND Capability
If the "UTF8=APPEND" capability is advertised, then the server
accepts UTF-8 headers in the APPEND command message argument. A
client that sends a message with UTF-8 headers to the server MUST
send them using the "UTF8" APPEND data extension. If the server also
advertises the CATENATE capability (as specified in [RFC4469]), the
client can use the same data extension to include such a message in a
CATENATE message part. The ABNF for the APPEND data extension and
CATENATE extension follows:
utf8-literal = "UTF8" SP "(" literal8 ")"
append-data =/ utf8-literal
cat-part =/ utf8-literal
A server that advertises "UTF8=APPEND" has to comply with the
requirements of the IMAP base specification and [RFC5322] for message
fetching. Mechanisms for 7-bit downgrading to help comply with the
standards are discussed in Downgrading mechanism for
Internationalized eMail Address (IMA) [RFC5504].
IMAP servers that do not advertise the "UTF8=APPEND" or "UTF8=ONLY"
capability SHOULD reject an APPEND command that includes any 8-bit in
the message headers with a "NO" response.
Note that the "UTF8=ONLY" capability described in Section 7 implies
the "UTF8=APPEND" capability. See additional information in that
section.
5. UTF8=USER Capability
If the "UTF8=USER" capability is advertised, that indicates the
server accepts UTF-8 user names and passwords and applies SASLprep
[RFC4013] to both arguments of the LOGIN command. The server MUST
reject UTF-8 that fails to comply with the formal syntax in RFC 3629
[RFC3629] or if it encounters Unicode characters listed in Section
2.3 of SASLprep RFC 4013 [RFC4013].
6. UTF8=ALL Capability
The "UTF8=ALL" capability indicates all server mailboxes support
UTF-8 headers. Specifically, SELECT and EXAMINE with the "UTF8"
parameter will never fail with a [NOT-UTF-8] response code.
Resnick & Newman Experimental [Page 7]
RFC 5738 IMAP Support for UTF-8 March 2010
Note that the "UTF8=ONLY" capability described in Section 7 implies
the "UTF8=ALL" capability. See additional information in that
section.
Note that the "UTF8=ALL" capability implies the "UTF8=ACCEPT"
capability.
7. UTF8=ONLY Capability
The "UTF8=ONLY" capability permits an IMAP server to advertise that
it does not support the international mailbox name convention
(modified UTF-7), and does not permit selection or examination of any
mailbox unless the "UTF8" parameter is provided. As this is an
incompatible change to IMAP, a clear warning is necessary. IMAP
clients that find implementation of the "UTF8=ONLY" capability
problematic are encouraged to at least detect the "UTF8=ONLY"
capability and provide an informative error message to the end-user.
When an IMAP mailbox internally uses UTF-8 header native storage, the
down-conversion step is necessary to permit selection or examination
of the mailbox in a backwards compatible fashion will become more
difficult to support. Although it is hoped that deployed IMAP
servers will not advertise "UTF8=ONLY" for some years, this
capability is intended to minimize the disruption when legacy support
finally goes away.
The "UTF8=ONLY" capability implies the "UTF8=ACCEPT" capability, the
"UTF8=ALL" capability, and the "UTF8=APPEND" capability. A server
that advertises "UTF8=ONLY" need not advertise the three implicit
capabilities.
8. Up-Conversion Server Requirements
When an IMAP4 server uses a traditional mailbox format that includes
7-bit headers and it chooses to permit access to that mailbox with
the "UTF8" parameter, it MUST support minimal up-conversion as
described in this section.
The server MUST support up-conversion of the following address
header-fields in the message header: From, Sender, To, CC, Bcc,
Resent-From, Resent-Sender, Resent-To, Resent-CC, Resent-Bcc, and
Reply-To. This up-conversion MUST include address local-parts in
fields downgraded according to [RFC5504], address domains encoded
according to Internationalizing Domain Names in Applications (IDNA)
[RFC3490], and MIME header encoding [RFC2047] of display-names and
any [RFC5322] comments.
Resnick & Newman Experimental [Page 8]
RFC 5738 IMAP Support for UTF-8 March 2010
The following charsets MUST be supported for up-conversion of MIME
header encoding [RFC2047]: UTF-8, US-ASCII, ISO-8859-1, ISO-8859-2,
ISO-8859-3, ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7,
ISO-8859-8, ISO-8859-9, ISO-8859-10, ISO-8859-14, and ISO-8859-15.
If the server supports other charsets in IMAP SEARCH or IMAP CONVERT
[RFC5259], it SHOULD also support those charsets in this conversion.
Up-conversion of MIME header encoding of the following headers MUST
also be implemented: Subject, Date ([RFC5322] comments only),
Comments, Keywords, and Content-Description.
Server implementations also SHOULD up-convert all MIME body headers
[RFC2045], SHOULD up-convert or remove the deprecated (and misused)
"name" parameter [RFC1341] on Content-Type, and MUST up-convert the
Content-Disposition [RFC2183] "filename" parameter, except when any
of these are contained within a multipart/signed MIME body part (see
below). These parameters can be encoded using the standard MIME
parameter encoding [RFC2231] mechanism, or via non-standard use of
MIME header encoding [RFC2047] in quoted strings.
The IMAP server MUST NOT perform up-conversion of headers and content
of multipart/signed, as well as Original-Recipient and Return-Path.
9. Issues with UTF-8 Header Mailstore
When an IMAP server uses a mailbox format that supports UTF-8 headers
and it permits selection or examination of that mailbox without the
"UTF8" parameter, it is the responsibility of the server to comply
with the IMAP4rev1 base specification [RFC3501] and [RFC5322] with
respect to all header information transmitted over the wire.
Mechanisms for 7-bit downgrading to help comply with the standards
are discussed in "Downgrading Mechanism for Email Address
Internationalization" [RFC5504].
An IMAP server with a mailbox that supports UTF-8 headers MUST comply
with the protocol requirements implicit from Section 8. However, the
code necessary for such compliance need not be part of the IMAP
server itself in this case. For example, the minimal required up-
conversion could be performed when a message is inserted into the
IMAP-accessible mailbox.
10. IANA Considerations
This adds five new capabilities ("UTF8=ACCEPT", "UTF8=USER",
"UTF8=APPEND", "UTF8=ALL", and "UTF8=ONLY") to the IMAP4rev1
Capabilities registry [RFC3501].
Resnick & Newman Experimental [Page 9]
RFC 5738 IMAP Support for UTF-8 March 2010
This adds two new IMAP4 list selection options and one new IMAP4 list
return option.
1. LIST-EXTENDED option name: UTF8
LIST-EXTENDED option type: SELECTION
Implied return options(s): UTF8
LIST-EXTENDED option description: Causes the LIST response to
include mailboxes that mandate the UTF8 SELECT/EXAMINE parameter.
Published specification: RFC 5738, Section 3.4.1
Security considerations: RFC 5738, Section 11
Intended usage: COMMON
Person and email address to contact for further information: see
the Authors' Addresses at the end of this specification
Owner/Change controller: iesg@ietf.org
2. LIST-EXTENDED option name: UTF8ONLY
LIST-EXTENDED option type: SELECTION
Implied return options(s): UTF8
LIST-EXTENDED option description: Causes the LIST response to
include mailboxes that mandate the UTF8 SELECT/EXAMINE parameter
and exclude mailboxes that do not support the UTF8 SELECT/EXAMINE
parameter.
Published specification: RFC 5738, Section 3.4.1
Security considerations: RFC 5738, Section 11
Intended usage: COMMON
Person and email address to contact for further information: see
the Authors' Addresses at the end of this specification
Owner/Change controller: iesg@ietf.org
Resnick & Newman Experimental [Page 10]
RFC 5738 IMAP Support for UTF-8 March 2010
3. LIST-EXTENDED option name: UTF8
LIST-EXTENDED option type: RETURN
Implied return options(s): none
LIST-EXTENDED option description: Causes the LIST response to
include \NoUTF8 and \UTF8Only mailbox attributes.
Published specification: RFC 5738, Section 3.4.1
Security considerations: RFC 5738, Section 11
Intended usage: COMMON
Person and email address to contact for further information: see
the Authors' Addresses at the end of this specification
Owner/Change controller: iesg@ietf.org
11. Security Considerations
The security considerations of UTF-8 [RFC3629] and SASLprep [RFC4013]
apply to this specification, particularly with respect to use of
UTF-8 in user names and passwords. Otherwise, this is not believed
to alter the security considerations of IMAP4rev1.
12. References
12.1. Normative References
[RFC1341] Borenstein, N. and N. Freed, "MIME (Multipurpose Internet
Mail Extensions): Mechanisms for Specifying and Describing
the Format of Internet Message Bodies", RFC 1341,
June 1992.
[RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part One: Format of Internet Message
Bodies", RFC 2045, November 1996.
[RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions)
Part Three: Message Header Extensions for Non-ASCII Text",
RFC 2047, November 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
Resnick & Newman Experimental [Page 11]
RFC 5738 IMAP Support for UTF-8 March 2010
[RFC2183] Troost, R., Dorner, S., and K. Moore, "Communicating
Presentation Information in Internet Messages: The
Content-Disposition Header Field", RFC 2183, August 1997.
[RFC2231] Freed, N. and K. Moore, "MIME Parameter Value and Encoded
Word Extensions:
Character Sets, Languages, and Continuations", RFC 2231,
November 1997.
[RFC3490] Faltstrom, P., Hoffman, P., and A. Costello,
"Internationalizing Domain Names in Applications (IDNA)",
RFC 3490, March 2003.
[RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
4rev1", RFC 3501, March 2003.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003.
[RFC4013] Zeilenga, K., "SASLprep: Stringprep Profile for User Names
and Passwords", RFC 4013, February 2005.
[RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
ABNF", RFC 4466, April 2006.
[RFC4469] Resnick, P., "Internet Message Access Protocol (IMAP)
CATENATE Extension", RFC 4469, April 2006.
[RFC5161] Gulbrandsen, A. and A. Melnikov, "The IMAP ENABLE
Extension", RFC 5161, March 2008.
[RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network
Interchange", RFC 5198, March 2008.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008.
[RFC5258] Leiba, B. and A. Melnikov, "Internet Message Access
Protocol version 4 - LIST Command Extensions", RFC 5258,
June 2008.
[RFC5259] Melnikov, A. and P. Coates, "Internet Message Access
Protocol - CONVERT Extension", RFC 5259, July 2008.
[RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
October 2008.
Resnick & Newman Experimental [Page 12]
RFC 5738 IMAP Support for UTF-8 March 2010
[RFC5335] Abel, Y., "Internationalized Email Headers", RFC 5335,
September 2008.
[RFC5504] Fujiwara, K. and Y. Yoneya, "Downgrading Mechanism for
Email Address Internationalization", RFC 5504, March 2009.
12.2. Informative References
[RFC2049] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Five: Conformance Criteria and
Examples", RFC 2049, November 1996.
[RFC2088] Myers, J., "IMAP4 non-synchronizing literals", RFC 2088,
January 1997.
[RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
Languages", BCP 18, RFC 2277, January 1998.
[RFC5721] Gellens, R. and C. Newman, "POP3 Support for UTF-8",
RFC 5721, February 2010.
Resnick & Newman Experimental [Page 13]
RFC 5738 IMAP Support for UTF-8 March 2010
Appendix A. Design Rationale
This non-normative section discusses the reasons behind some of the
design choices in the above specification.
The basic approach of advertising the ability to access a mailbox in
UTF-8 mode is intended to permit graceful upgrade, including servers
that support multiple mailbox formats. In particular, it would be
undesirable to force conversion of an entire server mailstore to
UTF-8 headers, so being able to phase-in support for new mailboxes
and gradually migrate old mailboxes is permitted by this design.
"UTF8=USER" is optional because many identity systems are US-ASCII
only, so it's helpful to inform the client up front that UTF-8 won't
work.
"UTF8=APPEND" is optional because it effectively requires IMAP server
support for down-conversion, which is a much more complex operation
than up-conversion.
The "UTF8=ONLY" mechanism simplifies diagnosis of interoperability
problems when legacy support goes away. In the situation where
backwards compatibility is broken anyway, just-send-UTF-8 IMAP has
the advantage that it might work with some legacy clients. However,
the difficulty of diagnosing interoperability problems caused by a
just-send-UTF-8 IMAP mechanism is the reason the "UTF8=ONLY"
capability mechanism was chosen.
The up-conversion requirements are designed to balance the desire to
deprecate and eventually eliminate complicated encodings (like MIME
header encodings) without creating a significant deployment burden
for servers. As IMAP4 servers already require a MIME parser, this
includes additional server up-conversion requirements not present in
POP3 Support for UTF-8 [RFC5721].
The set of mandatory charsets comes from two sources: MIME
requirements [RFC2049] and IETF Policy on Character Sets [RFC2277].
Including a requirement to up-convert widely deployed encoded
ideographic charsets to UTF-8 would be reasonable for most scenarios,
but may require unacceptable table sizes for some embedded devices.
The open-ended recommendation to support widely deployed charsets
avoids the political ramifications of attempting to list such
charsets. The authors believe market forces, existing open-source
software, and public conversion tables are sufficient to deploy the
appropriate charsets.
Resnick & Newman Experimental [Page 14]
RFC 5738 IMAP Support for UTF-8 March 2010
Appendix B. Examples Demonstrating Relationships between UTF8=
Capabilities
UTF8=ACCEPT UTF8=USER UTF8=APPEND
UTF8=ACCEPT UTF8=ALL
UTF8=ALL ; Note, same as above
UTF8=ACCEPT UTF8=USER UTF8=APPEND UTF8=ALL UTF8=ONLY
UTF8=USER UTF8=ONLY ; Note, same as above
Appendix C. Acknowledgments
The authors wish to thank the participants of the EAI working group
for their contributions to this document with particular thanks to
Harald Alvestrand, David Black, Randall Gellens, Arnt Gulbrandsen,
Kari Hurtta, John Klensin, Xiaodong Lee, Charles Lindsey, Alexey
Melnikov, Subramanian Moonesamy, Shawn Steele, Daniel Taharlev, and
Joseph Yee for their specific contributions to the discussion.
Authors' Addresses
Pete Resnick
Qualcomm Incorporated
5775 Morehouse Drive
San Diego, CA 92121-1714
US
Phone: +1 858 651 4478
EMail: presnick@qualcomm.com
URI: http://www.qualcomm.com/~presnick/
Chris Newman
Sun Microsystems
800 Royal Oaks
Monrovia, CA 91016
US
EMail: chris.newman@sun.com
Resnick & Newman Experimental [Page 15]

619
docs/rfcs/rfc5788.IMAP4_Keyword_registry.txt Normal file
View File

@ -0,0 +1,619 @@
Internet Engineering Task Force (IETF) A. Melnikov
Request for Comments: 5788 D. Cridland
Category: Standards Track Isode Limited
ISSN: 2070-1721 March 2010
IMAP4 Keyword Registry
Abstract
The aim of this document is to establish a new IANA registry for IMAP
keywords and to define a procedure for keyword registration, in order
to improve interoperability between different IMAP clients.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc5788.
Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Melnikov & Cridland Standards Track [Page 1]
RFC 5788 IMAP4 Keyword Registry March 2010
Table of Contents
1. Introduction ....................................................2
2. Conventions Used in This Document ...............................2
3. IANA Considerations .............................................3
3.1. Review Guidelines for the Designated Expert Reviewer .......4
3.2. Comments on IMAP Keywords' Registrations ...................5
3.3. Change Control .............................................5
3.4. Initial Registrations ......................................6
3.4.1. $MDNSent IMAP Keyword Registration ..................6
3.4.2. $Forwarded IMAP Keyword Registration ................7
3.4.3. $SubmitPending IMAP Keyword Registration ............8
3.4.4. $Submitted IMAP Keyword Registration ................9
4. Security Considerations ........................................10
5. Acknowledgements ...............................................10
6. References .....................................................10
6.1. Normative References ......................................10
6.2. Informative References ....................................11
1. Introduction
IMAP keywords [RFC3501] are boolean named flags that can be used by
clients to annotate messages in an IMAP mailbox. Although IMAP
keywords are an optional feature of IMAP, the majority of IMAP
servers can store arbitrary keywords. Many mainstream IMAP clients
use a limited set of specific keywords, and some can manage (create,
edit, display) arbitrary IMAP keywords.
Over the years, some IMAP keywords have become de-facto standards,
with some specific semantics associated with them. In some cases,
different client implementors decided to define and use keywords with
different names, but the same semantics. Some server implementors
decided to map such keywords automatically in order to improve cross-
client interoperability.
In other cases, the same keywords have been used with different
semantics, thus causing interoperability problems.
This document attempts to prevent further incompatible uses of IMAP
keywords by establishing an "IMAP Keywords" registry and allocating a
special prefix for standardized keywords.
2. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [Kwds].
Melnikov & Cridland Standards Track [Page 2]
RFC 5788 IMAP4 Keyword Registry March 2010
3. IANA Considerations
IANA has established a new registry for IMAP keywords.
Registration of an IMAP keyword is requested by filling in the
following template and following the instructions on the IANA pages
for the registry to submit it to IANA:
Subject: Registration of IMAP keyword X
IMAP keyword name:
Purpose (description):
Private or Shared on a server: (One of PRIVATE, SHARED, or BOTH.
PRIVATE means that each different
user has a distinct copy of the
keyword. SHARED means that all
different users see the same value of
the keyword. BOTH means that an IMAP
server can have the keyword as either
private or shared.)
Is it an advisory keyword or may it cause an automatic action:
When/by whom the keyword is set/cleared:
Related keywords: (for example, "mutually exclusive with keywords Y
and Z")
Related IMAP capabilities:
Security considerations:
Published specification (recommended):
Person & email address to contact for further information:
Intended usage: (One of COMMON, LIMITED USE, or DEPRECATED (i.e.,
not recommended for use))
Owner/Change controller: (MUST be "IESG" for any "common use"
keyword registration specified in an IETF
Review document. See definition of "common
use" below in this section. When the
Owner/Change controller is not a
Standardization Organization, the
registration request MUST make it clear if
Melnikov & Cridland Standards Track [Page 3]
RFC 5788 IMAP4 Keyword Registry March 2010
the registration is controlled by a
company, or the individual performing the
registration.)
Note: (Any other information that the author deems interesting
may be added here, for example, if the keyword(s) is
supported by existing clients.)
Registration of an IMAP keyword requires Expert Review [RFC5226].
Registration of any IMAP keyword is initiated by posting a
registration request to the Message Organization WG mailing list
<morg@ietf.org> (or its replacement as chosen by the responsible
Application Area Director) and CCing IANA (<iana@iana.org>). After
allowing for at least two weeks for community input on the designated
mailing list, the expert will determine the appropriateness of the
registration request and either approve or disapprove the request
with notice to the requestor, the mailing list, and IANA. Any
refusal must come with a clear explanation.
The IESG appoints one or more Expert Reviewers for the IMAP keyword
registry established by this document.
The Expert Reviewer should strive for timely reviews. The Expert
Reviewer should take no longer than six weeks to make and announce
the decision, or notify the mailing list that more time is required.
Decisions (or lack of) made by an Expert Reviewer can be first
appealed to Application Area Directors and, if the appellant is not
satisfied with the response, to the full IESG.
There are two types of IMAP keywords in the "IMAP Keywords" registry:
intended for "common use" and vendor-/organization-specific use (also
known as "limited use"). An IMAP keyword is said to be for "common
use" if it is reasonably expected to be implemented in at least two
independent client implementations. The two types of IMAP keywords
have different levels of requirements for registration (see below).
3.1. Review Guidelines for the Designated Expert Reviewer
Expert Reviewers should focus on the following requirements.
Registration of a vendor-/organization-specific ("limited use") IMAP
keyword is easier. The Expert Reviewer only needs to check that the
requested name doesn't conflict with an already registered name, and
that the name is not too generic, misleading, etc. The Expert
Reviewer MAY request the IMAP keyword name change before approving
Melnikov & Cridland Standards Track [Page 4]
RFC 5788 IMAP4 Keyword Registry March 2010
the registration. The Expert Reviewer SHOULD refuse a registration
if there is an already registered IMAP keyword that serves the same
purpose, but has a different name.
When registering an IMAP keyword for "common use", the Expert
Reviewer performs the checks described for vendor-/
organization-specific IMAP keywords, plus additional checks as
detailed below.
Keywords intended for "common use" SHOULD start with the "$" prefix.
(Note that this is a SHOULD because some of the commonly used IMAP
keywords in widespread use don't follow this convention.)
IMAP keywords intended for "common use" SHOULD be standardized in
IETF Review [RFC5226] documents. (Note that IETF Review documents
still require Expert Review.)
Values in the "IMAP Keywords" IANA registry intended for "common use"
must be clearly documented and likely to ensure interoperability.
They must be useful, not harmful to the Internet. In cases when an
IMAP keyword being registered is already deployed, Expert Reviewers
should favor registering it over requiring perfect documentation
and/or requesting a change to the name of the IMAP keyword.
The Expert Reviewer MAY automatically "upgrade" registration requests
for a "limited use" IMAP keyword to "common use" level. The Expert
Reviewer MAY also request that a registration targeted for "common
use" be registered as "limited use" instead.
3.2. Comments on IMAP Keywords' Registrations
Comments on registered IMAP keywords should be sent to both the
"owner" of the mechanism and to the mailing list designated to IMAP
keyword review (see Section 3). This improves the chances of getting
a timely response.
Submitters of comments may, after a reasonable attempt to contact the
owner and after soliciting comments on the IMAP mailing list, request
the designated Expert Reviewer to attach their comment to the IMAP
keyword registration itself. The procedure is similar to requesting
an Expert Review for the affected keyword.
3.3. Change Control
Once an IMAP keyword registration has been published by IANA, the
owner may request a change to its definition. The change request
(including a change to the "intended usage" field) follows the same
procedure as the initial registration request, with the exception of
Melnikov & Cridland Standards Track [Page 5]
RFC 5788 IMAP4 Keyword Registry March 2010
changes to the "Person & email address to contact for further
information" and "Owner/Change controller" fields. The latter can be
changed by the owner by informing IANA; this can be done without
discussion or review.
The IESG may reassign responsibility for an IMAP keyword. The most
common case of this will be to enable clarifications to be made to
keywords where the owner of the registration has died, moved out of
contact, or is otherwise unable to make changes that are important to
the community.
IMAP keyword registrations MUST NOT be deleted; keywords that are no
longer believed appropriate for use can be declared DEPRECATED by a
change to their "intended usage" field.
The IESG is considered the owner of all "common use" IMAP keywords
that are published in an IETF Review document.
3.4. Initial Registrations
IANA has registered the IMAP keywords specified in following
subsections in the registry established by this document.
3.4.1. $MDNSent IMAP Keyword Registration
Subject: Registration of IMAP keyword $MDNSent
IMAP keyword name: $MDNSent
Purpose (description): Specifies that a Message Disposition
Notification (MDN) must not be sent for any
message annotated with the $MDNSent IMAP
keyword.
Private or Shared on a server: SHARED
Is it an advisory keyword or may it cause an automatic action:
This keyword can cause automatic action by
the client. See [RFC3503] for more details.
When/by whom the keyword is set/cleared:
This keyword is set by an IMAP client when it
decides to act on an MDN request, or when
uploading a sent or draft message. It can
also be set by a delivery agent. Once set,
the flag SHOULD NOT be cleared.
Melnikov & Cridland Standards Track [Page 6]
RFC 5788 IMAP4 Keyword Registry March 2010
Related keywords: None
Related IMAP capabilities: None
Security considerations: See Section 6 of [RFC3503]
Published specification (recommended): [RFC3503]
Person & email address to contact for further information:
Alexey Melnikov <alexey.melnikov@isode.com>
Intended usage: COMMON
Owner/Change controller: IESG
Note:
3.4.2. $Forwarded IMAP Keyword Registration
Subject: Registration of the IMAP keyword $Forwarded
IMAP keyword name: $Forwarded
Purpose (description): $Forwarded is used by several IMAP clients to
specify that the message was resent to
another email address, embedded within or
attached to a new message. This keyword is
set by the mail client when it successfully
forwards the message to another email
address. Typical usage of this keyword is to
show a different (or additional) icon for a
message that has been forwarded.
Private or Shared on a server: BOTH
Is it an advisory keyword or may it cause an automatic action:
advisory
When/by whom the keyword is set/cleared:
This keyword can be set by either a delivery
agent or a mail client. Once set, the flag
SHOULD NOT be cleared. Notes: There is no
way to tell if a message with $Forwarded
keyword set was forwarded more than once.
Related keywords: None
Related IMAP capabilities: None
Melnikov & Cridland Standards Track [Page 7]
RFC 5788 IMAP4 Keyword Registry March 2010
Security considerations: A server implementing this keyword as a
shared keyword may disclose that a
confidential message was forwarded.
Published specification (recommended): [RFC5550]
Person & email address to contact for further information:
Alexey Melnikov <alexey.melnikov@isode.com>
Intended usage: COMMON
Owner/Change controller: IESG
Note:
3.4.3. $SubmitPending IMAP Keyword Registration
Subject: Registration of IMAP keyword $SubmitPending
IMAP keyword name: $SubmitPending
Purpose (description): The $SubmitPending IMAP keyword designates
the message as awaiting to be submitted.
This keyword allows storing messages waiting
to be submitted in the same mailbox where
messages that were already submitted and/or
are being edited are stored.
A message that has both $Submitted and
$SubmitPending IMAP keywords set is a message
being actively submitted.
Private or Shared on a server: SHARED
Is it an advisory keyword or may it cause an automatic action:
This keyword can cause automatic action by
the client. See Section 5.10 of [RFC5550]
for more details.
When/by whom the keyword is set/cleared:
This keyword is set by a mail client when it
decides that the message needs to be sent
out.
Related keywords: $Submitted
Related IMAP capabilities: None
Melnikov & Cridland Standards Track [Page 8]
RFC 5788 IMAP4 Keyword Registry March 2010
Security considerations: A server implementing this keyword as a
shared keyword may disclose that a
confidential message is scheduled to be
sent out or is being actively sent out.
Published specification (recommended): [RFC5550]
Person & email address to contact for further information:
Alexey Melnikov <alexey.melnikov@isode.com>
Intended usage: COMMON
Owner/Change controller: IESG
Note:
3.4.4. $Submitted IMAP Keyword Registration
Subject: Registration of IMAP keyword $Submitted
IMAP keyword name: $Submitted
Purpose (description): The $Submitted IMAP keyword designates the
message as being sent out.
A message that has both $Submitted and
$SubmitPending IMAP keywords set is a message
being actively submitted.
Private or Shared on a server: SHARED
Is it an advisory keyword or may it cause an automatic action:
This keyword can cause automatic action by
the client. See Section 5.10 of [RFC5550]
for more details.
When/by whom the keyword is set/cleared:
This keyword is set by a mail client when it
decides to start sending it.
Related keywords: $SubmitPending
Related IMAP capabilities: None
Security considerations: A server implementing this keyword as a
shared keyword may disclose that a
confidential message was sent or is being
actively sent out.
Melnikov & Cridland Standards Track [Page 9]
RFC 5788 IMAP4 Keyword Registry March 2010
Published specification (recommended): [RFC5550]
Person & email address to contact for further information:
Alexey Melnikov <alexey.melnikov@isode.com>
Intended usage: COMMON
Owner/Change controller: IESG
Note:
4. Security Considerations
IMAP keywords are one of the base IMAP features [RFC3501]. This
document doesn't change their behavior, so it does not add new
security issues.
A particular IMAP keyword might have specific security
considerations, which are documented in the IMAP keyword
registration template standardized by this document.
5. Acknowledgements
The creation of this document was prompted by one of many discussions
on the IMAP mailing list.
John Neystadt co-authored the first version of this document.
Special thanks to Chris Newman, David Harris, Lyndon Nerenberg, Mark
Crispin, Samuel Weiler, Alfred Hoenes, Lars Eggert, and Cullen
Jennings for reviewing different versions of this document. However,
all errors or omissions must be attributed to the authors of this
document.
The authors would also like to thank the developers of Mozilla mail
clients for providing food for thought.
6. References
6.1. Normative References
[Kwds] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
4rev1", RFC 3501, March 2003.
Melnikov & Cridland Standards Track [Page 10]
RFC 5788 IMAP4 Keyword Registry March 2010
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
6.2. Informative References
[RFC3503] Melnikov, A., "Message Disposition Notification (MDN)
profile for Internet Message Access Protocol (IMAP)",
RFC 3503, March 2003.
[RFC5550] Cridland, D., Melnikov, A., and S. Maes, "The Internet
Email to Support Diverse Service Environments (Lemonade)
Profile", RFC 5550, August 2009.
Authors' Addresses
Alexey Melnikov
Isode Limited
5 Castle Business Village
36 Station Road
Hampton, Middlesex TW12 2BX
UK
EMail: Alexey.Melnikov@isode.com
URI: http://www.melnikov.ca/
Dave Cridland
Isode Limited
5 Castle Business Village
36 Station Road
Hampton, Middlesex TW12 2BX
UK
EMail: dave.cridland@isode.com
Melnikov & Cridland Standards Track [Page 11]

339
docs/rfcs/rfc5819.IMAP4_extension_Returning_STATUS_info_in_LIST.txt Normal file
View File

@ -0,0 +1,339 @@
Internet Engineering Task Force (IETF) A. Melnikov
Request for Comments: 5819 Isode Limited
Category: Standards Track T. Sirainen
ISSN: 2070-1721 Unaffiliated
March 2010
IMAP4 Extension for Returning STATUS Information in Extended LIST
Abstract
Many IMAP clients display information about total number of
messages / total number of unseen messages in IMAP mailboxes. In
order to do that, they are forced to issue a LIST or LSUB command and
to list all available mailboxes, followed by a STATUS command for
each mailbox found. This document provides an extension to LIST
command that allows the client to request STATUS information for
mailboxes together with other information typically returned by the
LIST command.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc5819.
Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Melnikov & Sirainen Standards Track [Page 1]
RFC 5819 TITLE* March 2010
Table of Contents
1. Introduction ....................................................2
1.1. Conventions Used in This Document ..........................2
2. STATUS Return Option to LIST Command ............................2
3. Examples ........................................................3
4. Formal Syntax ...................................................4
5. Security Considerations .........................................4
6. IANA Considerations .............................................4
7. Acknowledgements ................................................5
8. Normative References ............................................5
1. Introduction
Many IMAP clients display information about the total number of
messages / total number of unseen messages in IMAP mailboxes. In
order to do that, they are forced to issue a LIST or LSUB command and
to list all available mailboxes, followed by a STATUS command for
each mailbox found. This document provides an extension to LIST
command that allows the client to request STATUS information for
mailboxes together with other information typically returned by the
LIST command.
1.1. Conventions Used in This Document
In examples, "C:" indicates lines sent by a client that is connected
to a server. "S:" indicates lines sent by the server to the client.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [Kwds].
2. STATUS Return Option to LIST Command
[RFC3501] explicitly disallows mailbox patterns in the STATUS
command. The main reason was to discourage frequent use of the
STATUS command by clients, as it might be quite expensive for an IMAP
server to perform. However, this prohibition had resulted in an
opposite effect: a new generation of IMAP clients appeared, that
issues a STATUS command for each mailbox returned by the LIST
command. This behavior is suboptimal to say at least. It wastes
extra bandwidth and, in the case of a client that doesn't support
IMAP pipelining, also degrades performance by using too many round
trips. This document tries to remedy the situation by specifying a
single command that can be used by the client to request all the
necessary information. In order to achieve this goal, this document
is extending the LIST command with a new return option, STATUS. This
option takes STATUS data items as parameters. For each selectable
Melnikov & Sirainen Standards Track [Page 2]
RFC 5819 TITLE* March 2010
mailbox matching the list pattern and selection options, the server
MUST return an untagged LIST response followed by an untagged STATUS
response containing the information requested in the STATUS return
option.
If an attempted STATUS for a listed mailbox fails because the mailbox
can't be selected (e.g., if the "l" ACL right [ACL] is granted to the
mailbox and the "r" right is not granted, or due to a race condition
between LIST and STATUS changing the mailbox to \NoSelect), the
STATUS response MUST NOT be returned and the LIST response MUST
include the \NoSelect attribute. This means the server may have to
buffer the LIST reply until it has successfully looked up the
necessary STATUS information.
If the server runs into unexpected problems while trying to look up
the STATUS information, it MAY drop the corresponding STATUS reply.
In such a situation, the LIST command would still return a tagged OK
reply.
3. Examples
C: A01 LIST "" % RETURN (STATUS (MESSAGES UNSEEN))
S: * LIST () "." "INBOX"
S: * STATUS "INBOX" (MESSAGES 17 UNSEEN 16)
S: * LIST () "." "foo"
S: * STATUS "foo" (MESSAGES 30 UNSEEN 29)
S: * LIST (\NoSelect) "." "bar"
S: A01 OK List completed.
The "bar" mailbox isn't selectable, so it has no STATUS reply.
C: A02 LIST (SUBSCRIBED RECURSIVEMATCH)"" % RETURN (STATUS
(MESSAGES))
S: * LIST (\Subscribed) "." "INBOX"
S: * STATUS "INBOX" (MESSAGES 17)
S: * LIST () "." "foo" (CHILDINFO ("SUBSCRIBED"))
S: A02 OK List completed.
The LIST reply for "foo" is returned because it has matching
children, but no STATUS reply is returned because "foo" itself
doesn't match the selection criteria.
Melnikov & Sirainen Standards Track [Page 3]
RFC 5819 TITLE* March 2010
4. Formal Syntax
The following syntax specification uses the augmented Backus-Naur
Form (BNF) as described in [ABNF]. Terms not defined here are taken
from [RFC3501] and [LISTEXT].
return-option =/ status-option
status-option = "STATUS" SP "(" status-att *(SP status-att) ")"
;; This ABNF production complies with
;; <option-extension> syntax.
5. Security Considerations
This extension makes it a bit easier for clients to overload the
server by requesting STATUS information for a large number of
mailboxes. However, as already noted in the introduction, existing
clients already try to do that by generating a large number of STATUS
commands for each mailbox in which they are interested. While
performing STATUS information retrieval for big lists of mailboxes, a
server implementation needs to make sure that it can still serve
other IMAP connections and yield execution to other connections, when
necessary.
6. IANA Considerations
IMAP4 capabilities are registered by publishing a Standards Track or
IESG-approved Experimental RFC. The "IMAP 4 Capabilities" registry
is available from the IANA webiste:
http://www.iana.org
This document defines the LIST-STATUS IMAP capability. IANA has
added it to the registry.
IANA has also added the following new LIST-EXTENDED option to the
IANA registry established by [LISTEXT]:
To: iana@iana.org
Subject: Registration of LIST-EXTENDED option STATUS
LIST-EXTENDED option name: STATUS
LIST-EXTENDED option type: RETURN
LIST-EXTENDED option description: Causes the LIST command to return
STATUS responses in addition to LIST responses.
Melnikov & Sirainen Standards Track [Page 4]
RFC 5819 TITLE* March 2010
Published specification: RFC 5819
Security considerations: RFC 5819
Intended usage: COMMON
Person and email address to contact for further information:
Alexey Melnikov <Alexey.Melnikov@isode.com>
Owner/Change controller: iesg@ietf.org
7. Acknowledgements
Thanks to Philip Van Hoof who pointed out that STATUS and LIST
commands should be combined in order to optimize traffic and number
of round trips.
8. Normative References
[ABNF] Crocker, D., Ed., and P. Overell, "Augmented BNF for
Syntax Specifications: ABNF", STD 68, RFC 5234, January
2008.
[ACL] Melnikov, A., "IMAP4 Access Control List (ACL) Extension",
RFC 4314, December 2005.
[Kwds] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[LISTEXT] Leiba, B. and A. Melnikov, "Internet Message Access
Protocol version 4 - LIST Command Extensions", RFC 5258,
June 2008.
[RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
4rev1", RFC 3501, March 2003.
Melnikov & Sirainen Standards Track [Page 5]
RFC 5819 TITLE* March 2010
Authors' Addresses
Alexey Melnikov
Isode Limited
5 Castle Business Village
36 Station Road
Hampton, Middlesex TW12 2BX
UK
EMail: Alexey.Melnikov@isode.com
URI: http://www.melnikov.ca/
Timo Sirainen
EMail: tss@iki.fi
Melnikov & Sirainen Standards Track [Page 6]

283
docs/rfcs/rfc5957.IMAP4_SORT_extension.txt Normal file
View File

@ -0,0 +1,283 @@
Internet Engineering Task Force (IETF) D. Karp
Request for Comments: 5957 Zimbra
Updates: 5256 July 2010
Category: Standards Track
ISSN: 2070-1721
Display-Based Address Sorting for the IMAP4 SORT Extension
Abstract
This document describes an IMAP protocol extension enabling server-
side message sorting on the commonly displayed portion of the From
and To header fields.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc5957.
Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Karp IMAP4 Display-Based Address Sorting [Page 1]
RFC 5957 July 2010
Table of Contents
1. Introduction ....................................................2
2. Conventions Used in This Document ...............................2
3. DISPLAY Sort Value for an Address ...............................2
4. The DISPLAYFROM and DISPLAYTO Sort Criteria .....................3
5. Formal Syntax ...................................................3
6. Security Considerations .........................................3
7. Internationalization Considerations .............................4
8. IANA Considerations .............................................4
9. Normative References ............................................4
1. Introduction
The [SORT] extension to the [IMAP] protocol provides a means for the
server-based sorting of messages. It defines a set of sort criteria
and the mechanism for determining the sort value of a message for
each such ordering.
The [SORT] FROM and TO orderings sort messages lexically on the
[IMAP] addr-mailbox of the first address in the message's From and To
headers, respectively. This document provides two alternative
orderings, DISPLAYFROM and DISPLAYTO, which sort messages based on
the first From or To address's [IMAP] addr-name (generally the same
as its [RFC5322] display-name), when present.
A server that supports the full [SORT] extension as well as both the
DISPLAYFROM and DISPLAYTO sort criteria indicates this by returning
"SORT=DISPLAY" in its CAPABILITY response.
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].
3. DISPLAY Sort Value for an Address
For the purposes of the sort criteria defined in this document, the
sort value for an [IMAP] address structure is defined as follows:
o If the address structure's [IMAP] addr-name is non-NIL, apply the
procedure from [RFC5255], Section 4.6. (That is, decode any
[RFC2047] encoded-words and convert the resulting character string
into a charset valid for the currently active [RFC4790] collation,
with a default of UTF-8.) If the resulting octet string is not
the empty string, use it as the sort value for the address.
Karp IMAP4 Display-Based Address Sorting [Page 2]
RFC 5957 July 2010
o Otherwise, if the address structure's [IMAP] addr-mailbox and
[IMAP] addr-host are both non-NIL, the sort value for the address
is addr-mailbox@addr-host.
o Otherwise, if the address structure's [IMAP] addr-mailbox is non-
NIL, the sort value for the address is its addr-mailbox.
o If none of the above conditions are met, the sort value for the
address is the empty string.
4. The DISPLAYFROM and DISPLAYTO Sort Criteria
This document introduces two new [SORT] sort criteria, DISPLAYFROM
and DISPLAYTO. A message's sort value under these orderings MUST be
derived as follows:
A "derived-addr" value is created from the [IMAP] envelope structure
resulting from a FETCH ENVELOPE on the message. For DISPLAYFROM, the
derived-addr value is the [IMAP] env-from value. For DISPLAYTO, the
derived-addr value is the [IMAP] env-to value.
o If the derived-addr value is NIL, the message's sort value is the
empty string.
o Otherwise, the message's sort value is the DISPLAY sort value of
the first [IMAP] address in the derived-addr value.
5. Formal Syntax
The following syntax specification uses the Augmented Backus-Naur
Form (ABNF) notation as specified in [RFC5234]. [IMAP] defines the
non-terminal "capability", and [SORT] defines "sort-key".
capability =/ "SORT=DISPLAY"
sort-key =/ "DISPLAYFROM" / "DISPLAYTO"
6. Security Considerations
This document defines an additional IMAP4 capability. As such, it
does not change the underlying security considerations of [IMAP].
The author believes that no new security issues are introduced with
this additional IMAP4 capability.
Karp IMAP4 Display-Based Address Sorting [Page 3]
RFC 5957 July 2010
7. Internationalization Considerations
DISPLAYFROM and DISPLAYTO are string-based sort criteria. As stated
in [SORT], the active [RFC4790] collation as per [RFC5255] MUST be
used when sorting such strings.
The DISPLAYFROM and DISPLAYTO orderings sort on the full decoded
[IMAP] addr-name, when present. They do not attempt to parse this
string in a locale- or language-dependent manner in order to
determine and sort on some semantically meaningful substring such as
the surname.
8. IANA Considerations
[IMAP] capabilities are registered by publishing a Standards Track or
IESG-approved Experimental RFC. This document constitutes
registration of the SORT=DISPLAY capability in the [IMAP]
capabilities registry.
9. Normative References
[IMAP] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
4rev1", RFC 3501, March 2003.
[RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions)
Part Three: Message Header Extensions for Non-ASCII Text",
RFC 2047, November 1996.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC4790] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet
Application Protocol Collation Registry", RFC 4790, March
2007.
[RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for
Syntax Specifications: ABNF", STD 68, RFC 5234, January
2008.
[RFC5255] Newman, C., Gulbrandsen, A., and A. Melnikov, "Internet
Message Access Protocol Internationalization", RFC 5255,
June 2008.
[RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322,
October 2008.
Karp IMAP4 Display-Based Address Sorting [Page 4]
RFC 5957 July 2010
[SORT] Crispin, M. and K. Murchison, "Internet Message Access
Protocol - SORT and THREAD Extensions", RFC 5256, June
2008.
Author's Address
Dan Karp
Zimbra
3401 Hillview Avenue
Palo Alto, CA 94304
USA
EMail: dkarp@zimbra.com
URI: http://www.zimbra.com
Karp IMAP4 Display-Based Address Sorting [Page 5]

675
docs/rfcs/rfc6154.IMAP_LIST_Special-use_Mailboxes.txt Normal file
View File

@ -0,0 +1,675 @@
Internet Engineering Task Force (IETF) B. Leiba
Request for Comments: 6154 Huawei Technologies
Category: Standards Track J. Nicolson
ISSN: 2070-1721 Google
March 2011
IMAP LIST Extension for Special-Use Mailboxes
Abstract
Some IMAP message stores include special-use mailboxes, such as those
used to hold draft messages or sent messages. Many mail clients
allow users to specify where draft or sent messages should be put,
but configuring them requires that the user know which mailboxes the
server has set aside for these purposes. This extension adds new
optional mailbox attributes that a server may include in IMAP LIST
command responses to identify special-use mailboxes to the client,
easing configuration.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc6154.
Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Leiba & Nicolson Standards Track [Page 1]
RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Conventions Used in This Document . . . . . . . . . . . . 3
2. New Mailbox Attributes Identifying Special-Use Mailboxes . . . 3
3. Extension to IMAP CREATE Command to Set Special-Use
Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . 5
4. IMAP METADATA Entry for Special-Use Attributes . . . . . . . . 6
5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
5.1. Example of an IMAP LIST Command . . . . . . . . . . . . . 7
5.2. Example of an Extended IMAP LIST Command . . . . . . . . . 7
5.3. Example of an IMAP CREATE Command . . . . . . . . . . . . 8
5.4. Example of Using IMAP METADATA to Manipulate
Special-Use Attributes . . . . . . . . . . . . . . . . . . 8
6. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 9
7. Security Considerations . . . . . . . . . . . . . . . . . . . 9
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
8.1. Registration of USEATTR IMAP Response Code . . . . . . . . 10
8.2. Registration of CREATE-SPECIAL-USE IMAP Capability . . . . 10
8.3. Registration of SPECIAL-USE IMAP Capability . . . . . . . 10
8.4. Registration of SPECIAL-USE Selection Option . . . . . . . 10
8.5. Registration of SPECIAL-USE Return Option . . . . . . . . 11
8.6. Registration of SPECIAL-USE Metadata . . . . . . . . . . . 11
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12
9.1. Normative References . . . . . . . . . . . . . . . . . . . 12
9.2. Informative References . . . . . . . . . . . . . . . . . . 12
Leiba & Nicolson Standards Track [Page 2]
RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
1. Introduction
Some IMAP message stores include special-use mailboxes, such as those
used to hold draft messages or sent messages. Many mail clients
allow users to specify where draft or sent messages should be put,
but configuring them requires that the user know which mailboxes the
server has set aside for these purposes. This extension adds new
optional mailbox attributes that a server may include in IMAP LIST
command responses to identify special-use mailboxes to the client,
easing configuration.
In addition, this extension adds an optional parameter on the IMAP
CREATE command, allowing a client to assign a special use to a
mailbox when it is created. Servers may choose to support this part
of the extension, but are not required to.
1.1. Conventions Used in This Document
In examples, "C:" indicates lines sent by a client that is connected
to a server. "S:" indicates lines sent by the server to the client.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119].
2. New Mailbox Attributes Identifying Special-Use Mailboxes
An IMAP server that supports this extension MAY include any or all of
the following attributes in responses to the non-extended IMAP LIST
command. The new attributes are included along with existing
attributes, such as "\Marked" and "\Noselect". A given mailbox may
have none, one, or more than one of these attributes. In some cases,
a special use is advice to a client about what to put in that
mailbox. In other cases, it's advice to a client about what to
expect to find there. There is no capability string related to the
support of special-use attributes on the non-extended LIST command.
For the extended list command [RFC5258], this extension adds a new
capability string, a new selection option, and a new return option,
all called "SPECIAL-USE". Supporting implementations MUST include
the "SPECIAL-USE" capability string in response to an IMAP CAPABILITY
command. If the client specifies the "SPECIAL-USE" selection option,
the LIST command MUST return only those mailboxes that have a
special-use attribute set. If the client specifies the "SPECIAL-USE"
return option, the LIST command MUST return the new special-use
attributes on those mailboxes that have them set. The "SPECIAL-USE"
Leiba & Nicolson Standards Track [Page 3]
RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
return option is implied by the "SPECIAL-USE" selection option. The
extended LIST command MAY return SPECIAL-USE attributes even if the
client does not specify the return option.
The new attributes defined here are as follows:
\All
This mailbox presents all messages in the user's message store.
Implementations MAY omit some messages, such as, perhaps, those
in \Trash and \Junk. When this special use is supported, it is
almost certain to represent a virtual mailbox.
\Archive
This mailbox is used to archive messages. The meaning of an
"archival" mailbox is server-dependent; typically, it will be
used to get messages out of the inbox, or otherwise keep them
out of the user's way, while still making them accessible.
\Drafts
This mailbox is used to hold draft messages -- typically,
messages that are being composed but have not yet been sent. In
some server implementations, this might be a virtual mailbox,
containing messages from other mailboxes that are marked with
the "\Draft" message flag. Alternatively, this might just be
advice that a client put drafts here.
\Flagged
This mailbox presents all messages marked in some way as
"important". When this special use is supported, it is likely
to represent a virtual mailbox collecting messages (from other
mailboxes) that are marked with the "\Flagged" message flag.
\Junk
This mailbox is where messages deemed to be junk mail are held.
Some server implementations might put messages here
automatically. Alternatively, this might just be advice to a
client-side spam filter.
\Sent
This mailbox is used to hold copies of messages that have been
sent. Some server implementations might put messages here
automatically. Alternatively, this might just be advice that a
client save sent messages here.
\Trash
This mailbox is used to hold messages that have been deleted or
marked for deletion. In some server implementations, this might
be a virtual mailbox, containing messages from other mailboxes
Leiba & Nicolson Standards Track [Page 4]
RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
that are marked with the "\Deleted" message flag.
Alternatively, this might just be advice that a client that
chooses not to use the IMAP "\Deleted" model should use this as
its trash location. In server implementations that strictly
expect the IMAP "\Deleted" model, this special use is likely not
to be supported.
All of the above attributes are OPTIONAL, and any given server or
message store may support any combination of the attributes, or none
at all. In most cases, there will likely be at most one mailbox with
a given attribute for a given user, but in some server or message
store implementations it might be possible for multiple mailboxes to
have the same special-use attribute.
Special-use attributes are likely to be user-specific. User Adam
might share his \Sent mailbox with user Barb, but that mailbox is
unlikely to also serve as Barb's \Sent mailbox. It's certainly
possible for Adam and Barb to each set the \Sent use on the same
mailbox, but that would be done by specific action (see the sections
below).
3. Extension to IMAP CREATE Command to Set Special-Use Attributes
As an OPTIONAL feature, a server MAY allow clients to designate a
mailbox, at creation, as having one or more special uses. This
extension defines the "USE" parameter to the IMAP CREATE command for
that purpose (using the syntax defined in RFC 4466 section 2.2
[RFC4466]). The new OPTIONAL "USE" parameter is followed by a
parenthesized list of zero or more special-use attributes, as defined
above.
In some server implementations, some special uses may imply automatic
action by the server. For example, creation of a "\Junk" mailbox
might cause the server to start placing messages that have been
evaluated as spam into the mailbox.
In some server implementations, some special uses may result in a
mailbox with unusual characteristics or side effects. For example,
creation of an "\All" mailbox might cause the server to create a
virtual mailbox, rather than a standard one, and that mailbox might
behave in unexpected ways (COPY into it might fail, for example).
Servers MAY allow the creation of a special-use mailbox even if one
so designated already exists. This might have the effect of moving
the special use from the old mailbox to the new one, or might create
multiple mailboxes with the same special use. Alternatively, servers
MAY refuse the creation, considering the designation to be a
conflict.
Leiba & Nicolson Standards Track [Page 5]
RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
If the server cannot create a mailbox with the designated special use
defined, for whatever reason, it MUST NOT create the mailbox, and
MUST respond to the CREATE command with a tagged NO response. If the
reason for the failure is related to the special-use attribute (the
specified special use is not supported or cannot be assigned to the
specified mailbox), the server SHOULD include the new "USEATTR"
response code in the tagged response (see Section 5.3 for an
example).
An IMAP server that supports this OPTIONAL feature will advertise the
"CREATE-SPECIAL-USE" capability string. Clients MUST NOT use the
"USE" parameter unless the server advertises the capability. Note
that this capability string is different from the "SPECIAL-USE"
string defined above, and a server that supports both functions MUST
advertise both capability strings.
4. IMAP METADATA Entry for Special-Use Attributes
If a server supports this extension and the METADATA extension
[RFC5464], it SHOULD tie the special-use attributes for a mailbox to
its metadata entry "/private/specialuse". The value of /private/
specialuse is either NIL (if there are no special-use attributes for
that mailbox) or a space-separated list of special-use attributes,
presented the same way they would be presented in the LIST command
response.
Such a server MAY allow the setting of special-use attributes through
the METADATA mechanisms, thereby allowing clients to change the
special uses of existing mailboxes. These changes might have side
effects, as the server automatically adjusts the special uses
accordingly, just as it might do with CREATE USE, above. See
Section 5.4 for an example.
A server that supports this MUST check the validity of changes to the
special-use attributes that are done through the metadata in the same
way that it checks validity for the CREATE command and for any
internal mechanisms for setting special uses on mailboxes. It MUST
NOT just blindly accept setting of these metadata by clients, which
might result in the setting of special uses that the implementation
does not support, multiple mailboxes with the same special use, or
other situations that the implementation considers invalid.
Leiba & Nicolson Standards Track [Page 6]
RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
5. Examples
5.1. Example of an IMAP LIST Command
This example shows an IMAP LIST response from a server that supports
this extension. Note that not all of the attributes are used. This
server also supports the Child Mailbox extension [RFC3348].
C: t1 LIST "" "%"
S: * LIST (\Marked \HasNoChildren) "/" Inbox
S: * LIST (\HasNoChildren) "/" ToDo
S: * LIST (\HasChildren) "/" Projects
S: * LIST (\Sent \HasNoChildren) "/" SentMail
S: * LIST (\Marked \Drafts \HasNoChildren) "/" MyDrafts
S: * LIST (\Trash \HasNoChildren) "/" Trash
S: t1 OK done
5.2. Example of an Extended IMAP LIST Command
This example shows an IMAP LIST response from a server that supports
this extension. The client uses the extended IMAP LIST command.
C: t1 CAPABILITY
S: * CAPABILITY IMAP4rev1 SPECIAL-USE
S: t1 OK done
C: t2 LIST "" "%" RETURN (SPECIAL-USE)
S: * LIST (\Marked) "/" Inbox
S: * LIST () "/" ToDo
S: * LIST () "/" Projects
S: * LIST (\Sent) "/" SentMail
S: * LIST (\Marked \Drafts) "/" MyDrafts
S: * LIST (\Trash) "/" Trash
S: t2 OK done
Here, the client also includes the "SPECIAL-USE" selection option for
the same list. The "SPECIAL-USE" return option could also have been
specified, but it is unnecessary, as it is implied by the selection
option. Note that in this case, mailboxes that do not have a
special-use attribute are not listed. Also note that we've used the
wildcard "*", rather than "%", to make sure we see all special-use
mailboxes, even ones that might not be at the namespace's root.
C: t3 LIST (SPECIAL-USE) "" "*"
S: * LIST (\Sent) "/" SentMail
S: * LIST (\Marked \Drafts) "/" MyDrafts
S: * LIST (\Trash) "/" Trash
S: t3 OK done
Leiba & Nicolson Standards Track [Page 7]
RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
5.3. Example of an IMAP CREATE Command
This example shows an IMAP CREATE command that might be used to
create a mailbox designated to hold draft and sent messages. It also
attempts to create a mailbox that will contain all the user's
messages, but the server does not support that special use for this
user's message store.
C: t1 CAPABILITY
S: * CAPABILITY IMAP4rev1 CREATE-SPECIAL-USE
S: t1 OK done
C: t2 CREATE MySpecial (USE (\Drafts \Sent))
S: t2 OK MySpecial created
C: t3 CREATE Everything (USE (\All))
S: t3 NO [USEATTR] \All not supported
5.4. Example of Using IMAP METADATA to Manipulate Special-Use
Attributes
This example shows how IMAP METADATA can be used to manipulate
special-use attributes, if the operation is supported on the server.
==> Starting point:
C: t1 LIST "" "%" RETURN (SPECIAL-USE)
S: * LIST (\Sent) "/" SentMail
S: * LIST (\Drafts) "/" MyDrafts
S: * LIST () "/" SavedDrafts
S: * LIST (\Trash) "/" Trash
S: t1 OK done
==> Demonstrate the connection:
C: t2 GETMETADATA "MyDrafts" /private/specialuse
S: * METADATA "MyDrafts" (/private/specialuse "\\Drafts")
S: t2 OK done
==> Set new use for SavedDrafts; MyDrafts changes automatically:
C: t3 SETMETADATA "SavedDrafts" (/private/specialuse "\\Drafts")
S: * METADATA "MyDrafts" (/private/specialuse NIL)
S: t3 OK SETMETADATA complete
==> Remove special use for SentMail:
C: t4 SETMETADATA "SentMail" (/private/specialuse NIL)
S: t4 OK SETMETADATA complete
Leiba & Nicolson Standards Track [Page 8]
RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
==> Check the results:
C: t5 LIST "" "%" RETURN (SPECIAL-USE)
S: * LIST () "/" SentMail
S: * LIST () "/" MyDrafts
S: * LIST (\Drafts) "/" SavedDrafts
S: * LIST (\Trash) "/" Trash
S: t5 OK done
6. Formal Syntax
The following syntax specification uses the augmented Backus-Naur
Form (BNF) as described in [RFC5234].
create-param =/ "USE" SP "(" [use-attr *(SP use-attr)] ")"
; Extends "create-param" from RFC 4466 [RFC4466]
mbx-list-oflag =/ use-attr
; Extends "mbx-list-oflag" from IMAP base [RFC3501]
list-select-independent-opt =/ "SPECIAL-USE"
; Extends "list-select-independent-opt" from
; LIST-extended [RFC5258]
return-option =/ "SPECIAL-USE"
; Extends "return-option" from
; LIST-extended [RFC5258]
resp-text-code =/ "USEATTR"
; Extends "resp-text-code" from
; IMAP [RFC3501]
use-attr = "\All" / "\Archive" / "\Drafts" / "\Flagged" /
"\Junk" / "\Sent" / "\Trash" / use-attr-ext
use-attr-ext = "\" atom
; Reserved for future extensions. Clients
; MUST ignore list attributes they do not understand
; Server implementations MUST NOT generate
; extension attributes except as defined by
; future Standards-Track revisions of or
; extensions to this specification.
7. Security Considerations
LIST response:
Conveying special-use information to a client exposes a small bit of
extra information that could be of value to an attacker. Knowing,
for example, that a particular mailbox (\All) contains pointers to
Leiba & Nicolson Standards Track [Page 9]
RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
every message the user has might be of particular value. If the IMAP
channel is not protected from passive eavesdropping, this could be an
issue.
CREATE command "USE" parameter and metadata extension: In some server
implementations, some special uses may imply automatic action by the
server. For example, creation of a "\Junk" mailbox might cause the
server to start placing messages that have been evaluated as spam
into the mailbox. Implementors SHOULD consider the consequences of
allowing a user (or client program) to designate the target of such
automatic action.
Example: If a user is allowed to give the "\Junk" attribute to a
shared mailbox, legitimate mail that's misclassified as junk (false
positives) will be put into that shared mailbox, exposing the user's
private mail to others. The server might warn a user of that
possibility, or might refuse to allow the specification to be made on
a shared mailbox. (Note that this problem exists independent of this
specification, if the server allows a user to share a mailbox that's
already in use for such a function.)
8. IANA Considerations
8.1. Registration of USEATTR IMAP Response Code
This document defines a new IMAP response code, "USEATTR", which IANA
added to the IMAP Response Codes registry.
8.2. Registration of CREATE-SPECIAL-USE IMAP Capability
This document defines a new IMAP capability, "CREATE-SPECIAL-USE",
which IANA added to the IMAP 4 Capabilities registry.
8.3. Registration of SPECIAL-USE IMAP Capability
This document defines a new IMAP capability, "SPECIAL-USE", which
IANA added to the IMAP 4 Capabilities registry.
8.4. Registration of SPECIAL-USE Selection Option
This document defines a new IMAP4 List Extended selection option,
"SPECIAL-USE", which IANA added to the IMAP4 List Extended registry,
as follows:
To: iana@iana.org
Subject: Registration of LIST-EXTENDED selection option SPECIAL-USE
LIST-EXTENDED option name: SPECIAL-USE
LIST-EXTENDED option type: SELECTION
Leiba & Nicolson Standards Track [Page 10]
RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
Implied return option(s): SPECIAL-USE
LIST-EXTENDED option description: Limit the list to special-use
mailboxes only
Published specification: RFC 6154
Security considerations: none
Intended usage: COMMON
Person and email address to contact for further information: Authors'
Addresses at the end of RFC 6154
Owner/Change controller: iesg@ietf.org
8.5. Registration of SPECIAL-USE Return Option
This document defines a new IMAP4 List Extended return option,
"SPECIAL-USE", which IANA added to the IMAP4 List Extended registry,
as follows:
To: iana@iana.org
Subject: Registration of LIST-EXTENDED return option SPECIAL-USE
LIST-EXTENDED option name: SPECIAL-USE
LIST-EXTENDED option type: RETURN
LIST-EXTENDED option description: Request special-use mailbox
information
Published specification: RFC 6154
Security considerations: none
Intended usage: COMMON
Person and email address to contact for further information: Authors'
Addresses at the end of RFC 6154
Owner/Change controller: iesg@ietf.org
8.6. Registration of SPECIAL-USE Metadata
This document defines a new IMAP METADATA entry. IANA added the
following to the IMAP METADATA Mailbox Entry registry:
To: iana@iana.org
Subject: IMAP METADATA Entry Registration
Type: Mailbox
Name: /private/specialuse
Description: Defines any special-use features of a mailbox. See the
reference specification for details of its use.
Content-type: text/plain; charset=us-ascii
RFC Number: RFC 6154
Contact: MORG mailing list mailto:morg@ietf.org
Leiba & Nicolson Standards Track [Page 11]
RFC 6154 IMAP LIST: Special-Use Mailboxes March 2011
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.
[RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
ABNF", RFC 4466, April 2006.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008.
[RFC5258] Leiba, B. and A. Melnikov, "Internet Message Access
Protocol version 4 - LIST Command Extensions", RFC 5258,
June 2008.
[RFC5464] Daboo, C., "The IMAP METADATA Extension", RFC 5464,
February 2009.
9.2. Informative References
[RFC3348] Gahrns, M. and R. Cheng, "The Internet Message Action
Protocol (IMAP4) Child Mailbox Extension", RFC 3348,
July 2002.
Authors' Addresses
Barry Leiba
Huawei Technologies
Phone: +1 646 827 0648
EMail: barryleiba@computer.org
URI: http://internetmessagingtechnology.org/
Jamie Nicolson
Google
EMail: nicolson@google.com
Leiba & Nicolson Standards Track [Page 12]

395
docs/rfcs/rfc6203.IMAP4_Fuzzy_SEARCH_extension.txt Normal file
View File

@ -0,0 +1,395 @@
Internet Engineering Task Force (IETF) T. Sirainen
Request for Comments: 6203 March 2011
Category: Standards Track
ISSN: 2070-1721
IMAP4 Extension for Fuzzy Search
Abstract
This document describes an IMAP protocol extension enabling a server
to perform searches with inexact matching and assigning relevancy
scores for matched messages.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc6203.
Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Sirainen Standards Track [Page 1]
RFC 6203 IMAP4 FUZZY Search March 2011
1. Introduction
When humans perform searches in IMAP clients, they typically want to
see the most relevant search results first. IMAP servers are able to
do this in the most efficient way when they're free to internally
decide how searches should match messages. This document describes a
new SEARCH=FUZZY extension that provides such functionality.
2. Conventions Used in This Document
In examples, "C:" indicates lines sent by a client that is connected
to a server. "S:" indicates lines sent by the server to the client.
The key words "MUST", "MUST NOT", "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. The FUZZY Search Key
The FUZZY search key takes another search key as its argument. The
server is allowed to perform all matching in an implementation-
defined manner for this search key, including ignoring the active
comparator as defined by [RFC5255]. Typically, this would be used to
search for strings. For example:
C: A1 SEARCH FUZZY (SUBJECT "IMAP break")
S: * SEARCH 1 5 10
S: A1 OK Search completed.
Besides matching messages with a subject of "IMAP break", the above
search may also match messages with subjects "broken IMAP", "IMAP is
broken", or anything else the server decides that might be a good
match.
This example does a fuzzy SUBJECT search, but a non-fuzzy FROM
search:
C: A2 SEARCH FUZZY SUBJECT work FROM user@example.com
S: * SEARCH 1 4
S: A2 OK Search completed.
How the server handles multiple separate FUZZY search keys is
implementation-defined.
Fuzzy search algorithms might change, or the results of the
algorithms might be different from search to search, so that fuzzy
searches with the same parameters might give different results for
1) the same user at different times, 2) different users (searches
Sirainen Standards Track [Page 2]
RFC 6203 IMAP4 FUZZY Search March 2011
executed simultaneously), or 3) different users (searches executed at
different times). For example, a fuzzy search might adapt to a
user's search habits in an attempt to give more relevant results (in
a "learning" manner). Such differences can also occur because of
operational decisions, such as load balancing. Clients asking for
"fuzzy" really are requesting search results in a not-necessarily-
deterministic way and need to give the user appropriate warning about
that.
4. Relevancy Scores for Search Results
Servers SHOULD assign a search relevancy score for each matched
message when the FUZZY search key is given. Relevancy scores are
given in the range 1-100, where 100 is the highest relevancy. The
relevancy scores SHOULD use the full 1-100 range, so that clients can
show them to users in a meaningful way, e.g., as a percentage value.
As the name already indicates, relevancy scores specify how relevant
to the search the matched message is. It's not necessarily the same
as how precisely the message matched. For example, a message whose
subject fuzzily matches the search string might get a higher
relevancy score than a message whose body had the exact string in the
middle of a sentence. When multiple search keys are matched fuzzily,
how the relevancy score is calculated is server-dependent.
If the server also advertises the ESEARCH capability as defined by
[ESEARCH], the relevancy scores can be retrieved using the new
RELEVANCY return option for SEARCH:
C: B1 SEARCH RETURN (RELEVANCY ALL) FUZZY TEXT "Helo"
S: * ESEARCH (TAG "B1") ALL 1,5,10 RELEVANCY (4 99 42)
S: B1 OK Search completed.
In the example above, the server would treat "hello", "help", and
other similar strings as fuzzily matching the misspelled "Helo".
The RELEVANCY return option MUST NOT be used unless a FUZZY search
key is also given. Note that SEARCH results aren't sorted by
relevancy; SORT is needed for that.
5. Fuzzy Matching with Non-String Search Keys
Fuzzy matching is not limited to just string matching. All search
keys SHOULD be matched fuzzily, although exactly what that means for
different search keys is left for server implementations to decide --
including deciding that fuzzy matching is meaningless for a
particular key, and falling back to exact matching. Some suggestions
are given below.
Sirainen Standards Track [Page 3]
RFC 6203 IMAP4 FUZZY Search March 2011
Dates:
A typical example could be when a user wants to find a message
"from Dave about a week ago". A client could perform this search
using SEARCH FUZZY (FROM "Dave" SINCE 21-Jan-2009 BEFORE
24-Jan-2009). The server could return messages outside the
specified date range, but the further away the message is, the
lower the relevancy score.
Sizes:
These should be handled similarly to dates. If a user wants to
search for "about 1 MB attachments", the client could do this by
sending SEARCH FUZZY (LARGER 900000 SMALLER 1100000). Again, the
further away the message size is from the specified range, the
lower the relevancy score.
Flags:
If other search criteria match, the server could return messages
that don't have the specified flags set, but with lower relevancy
scores. SEARCH SUBJECT "xyz" FUZZY ANSWERED, for example, might
be useful if the user thinks the message he is looking for has the
ANSWERED flag set, but he isn't sure.
Unique Identifiers (UIDs), sequences, modification sequences: These
are examples of keys for which exact matching probably makes sense.
Alternatively, a server might choose, for instance, to expand a UID
range by 5% on each side.
6. Extensions to SORT and SEARCH
If the server also advertises the SORT capability as defined by
[SORT], the results can be sorted by the new RELEVANCY sort criteria:
C: C1 SORT (RELEVANCY) UTF-8 FUZZY SUBJECT "Helo"
S: * SORT 5 10 1
S: C1 OK Sort completed.
The message with the highest score is returned first. As with the
RELEVANCY return option, RELEVANCY sort criteria MUST NOT be used
unless a FUZZY search key is also given.
If the server also advertises the ESORT capability as defined by
[CONTEXT], the relevancy scores can be retrieved using the new
RELEVANCY return option for SORT:
C: C2 SORT RETURN (RELEVANCY ALL) (RELEVANCY) UTF-8 FUZZY TEXT
"Helo"
S: * ESEARCH (TAG "C2") ALL 5,10,1 RELEVANCY (99 42 4)
S: C2 OK Sort completed.
Sirainen Standards Track [Page 4]
RFC 6203 IMAP4 FUZZY Search March 2011
Furthermore, if the server advertises the CONTEXT=SORT (or
CONTEXT=SEARCH) capability, then the client can limit the number of
returned messages to a SORT (or a SEARCH) by using the PARTIAL return
option. For example, this returns the 10 most relevant messages:
C: C3 SORT RETURN (PARTIAL 1:10) (RELEVANCY) UTF-8 FUZZY TEXT
"World"
S: * ESEARCH (TAG "C3") PARTIAL (1:10 42,9,34,13,15,4,2,7,23,82)
S: C3 OK Sort completed.
7. Formal Syntax
The following syntax specification uses the augmented Backus-Naur
Form (BNF) as described in [ABNF]. It includes definitions from
[RFC3501], [IMAP-ABNF], and [SORT].
capability =/ "SEARCH=FUZZY"
score = 1*3DIGIT
;; (1 <= n <= 100)
score-list = "(" [score *(SP score)] ")"
search-key =/ "FUZZY" SP search-key
search-return-data =/ "RELEVANCY" SP score-list
;; Conforms to <search-return-data>, from [IMAP-ABNF]
search-return-opt =/ "RELEVANCY"
;; Conforms to <search-return-opt>, from [IMAP-ABNF]
sort-key =/ "RELEVANCY"
8. Security Considerations
Implementation of this extension might enable denial-of-service
attacks against server resources. Servers MAY limit the resources
that a single search (or a single user) may use. Additionally,
implementors should be aware of the following: Fuzzy search engines
are often complex with non-obvious disk space, memory, and/or CPU
usage patterns. Server implementors should at least test the fuzzy-
search behavior with large messages that contain very long words
and/or unique random strings. Also, very long search keys might
cause excessive memory or CPU usage.
Invalid input may also be problematic. For example, if the search
engine takes a UTF-8 stream as input, it might fail more or less
badly when illegal UTF-8 sequences are fed to it from a message whose
Sirainen Standards Track [Page 5]
RFC 6203 IMAP4 FUZZY Search March 2011
character set was claimed to be UTF-8. This could be avoided by
validating all the input and, for example, replacing illegal UTF-8
sequences with the Unicode replacement character (U+FFFD).
Search relevancy rankings might be susceptible to "poisoning" by
smart attackers using certain keywords or hidden markup (e.g., HTML)
in their messages to boost the rankings. This can't be fully
prevented by servers, so clients should prepare for it by at least
allowing users to see all the search results, rather than hiding
results below a certain score.
9. IANA Considerations
IMAP4 capabilities are registered by publishing a standards track or
IESG-approved experimental RFC. The "Internet Message Access
Protocol (IMAP) 4 Capabilities Registry" is available from
http://www.iana.org/.
This document defines the SEARCH=FUZZY IMAP capability. IANA has
added it to the registry.
10. Acknowledgements
Alexey Melnikov, Zoltan Ordogh, Barry Leiba, Cyrus Daboo, and Dave
Cridland have helped with this document.
11. Normative References
[ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for
Syntax Specifications: ABNF", STD 68, RFC 5234,
January 2008.
[CONTEXT] Cridland, D. and C. King, "Contexts for IMAP4",
RFC 5267, July 2008.
[ESEARCH] Melnikov, A. and D. Cridland, "IMAP4 Extension to SEARCH
Command for Controlling What Kind of Information Is
Returned", RFC 4731, November 2006.
[IMAP-ABNF] Melnikov, A. and C. Daboo, "Collected Extensions to
IMAP4 ABNF", RFC 4466, April 2006.
[KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
4rev1", RFC 3501, March 2003.
Sirainen Standards Track [Page 6]
RFC 6203 IMAP4 FUZZY Search March 2011
[RFC5255] Newman, C., Gulbrandsen, A., and A. Melnikov, "Internet
Message Access Protocol Internationalization", RFC 5255,
June 2008.
[SORT] Crispin, M. and K. Murchison, "Internet Message Access
Protocol - SORT and THREAD Extensions", RFC 5256,
June 2008.
Author's Address
Timo Sirainen
EMail: tss@iki.fi
Sirainen Standards Track [Page 7]

563
docs/rfcs/rfc6237.IMAP4_Multimailbox_SEARCH_extension.txt Normal file
View File

@ -0,0 +1,563 @@
Internet Engineering Task Force (IETF) B. Leiba
Request for Comments: 6237 Huawei Technologies
Updates: 4466 A. Melnikov
Category: Experimental Isode Limited
ISSN: 2070-1721 May 2011
IMAP4 Multimailbox SEARCH Extension
Abstract
The IMAP4 specification allows the searching of only the selected
mailbox. A user often wants to search multiple mailboxes, and a
client that wishes to support this must issue a series of SELECT and
SEARCH commands, waiting for each to complete before moving on to the
next. This extension allows a client to search multiple mailboxes
with one command, limiting the round trips and waiting for various
searches to complete, and not requiring disruption of the currently
selected mailbox. This extension also uses MAILBOX and TAG fields in
ESEARCH responses, allowing a client to pipeline the searches if it
chooses. This document updates RFC 4466.
Status of This Memo
This document is not an Internet Standards Track specification; it is
published for examination, experimental implementation, and
evaluation.
This document defines an Experimental Protocol for the Internet
community. This document is a product of the Internet Engineering
Task Force (IETF). It represents the consensus of the IETF
community. It has received public review and has been approved for
publication by the Internet Engineering Steering Group (IESG). Not
all documents approved by the IESG are a candidate for any level of
Internet Standard; see Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc6237.
Leiba & Melnikov Experimental [Page 1]
RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011
Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction ....................................................2
1.1. Conventions Used in This Document ..........................3
2. New ESEARCH Command .............................................3
2.1. The ESEARCH Response .......................................4
2.2. Source Options: Specifying Mailboxes to Search .............5
3. Examples ........................................................6
4. Formal Syntax ...................................................7
5. Security Considerations .........................................8
6. IANA Considerations .............................................9
7. Acknowledgements ................................................9
8. Normative References ............................................9
1. Introduction
The IMAP4 specification allows the searching of only the selected
mailbox. A user often wants to search multiple mailboxes, and a
client that wishes to support this must issue a series of SELECT and
SEARCH commands, waiting for each to complete before moving on to the
next. The commands can't be pipelined, because the server might run
them in parallel, and the untagged SEARCH responses could not then be
distinguished from each other.
This extension allows a client to search multiple mailboxes with one
command, and includes MAILBOX and TAG fields in the ESEARCH response,
yielding the following advantages:
o A single command limits the number of round trips needed to search
a set of mailboxes.
o A single command eliminates the need to wait for one search to
complete before starting the next.
Leiba & Melnikov Experimental [Page 2]
RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011
o A single command allows the server to optimize the search, if it
can.
o A command that is not dependent upon the selected mailbox
eliminates the need to disrupt the selection state or to open
another IMAP connection.
o The MAILBOX, UIDVALIDITY, and TAG fields in the responses allow a
client to distinguish which responses go with which search (and
which mailbox). A client can safely pipeline these search
commands without danger of confusion. The addition of the MAILBOX
and UIDVALIDITY fields updates the search-correlator item defined
in [RFC4466].
1.1. Conventions Used in This Document
In examples, "C:" indicates lines sent by a client that is connected
to a server. "S:" indicates lines sent by the server to the client.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119].
2. New ESEARCH Command
Arguments: OPTIONAL source options
OPTIONAL result options
OPTIONAL charset specification (see [RFC2978])
searching criteria (one or more)
Responses: REQUIRED untagged response: ESEARCH
Result: OK -- search completed
NO -- error: cannot search that charset or criteria
BAD -- command unknown or arguments invalid
This section defines a new ESEARCH command, which works similarly to
the UID SEARCH command described in Section 2.6.1 of [RFC4466]
(initially described in Section 6.4.4 of [RFC3501] and extended by
[RFC4731]).
The ESEARCH command further extends searching by allowing for
optional source and result options. This document does not define
any new result options (see Section 3.1 of [RFC4731]). A server that
supports this extension includes "MULTISEARCH" in its IMAP capability
string.
Leiba & Melnikov Experimental [Page 3]
RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011
Because there has been confusion about this, it is worth pointing out
that with ESEARCH, as with *any* SEARCH or UID SEARCH command, it
MUST NOT be considered an error if the search terms include a range
of message numbers that extends (or, in fact, starts) beyond the end
of the mailbox. For example, a client might want to establish a
rolling window through the search results this way:
C: tag1 UID ESEARCH FROM "frobozz" 1:100
...followed later by this:
C: tag1 UID ESEARCH FROM "frobozz" 101:200
...and so on. This tells the server to match only the first hundred
messages in the mailbox the first time, the second hundred the second
time, etc. In fact, it might likely allow the server to optimize the
search significantly. In the above example, whether the mailbox
contains 50 or 150 or 250 messages, neither of the search commands
shown will result in an error. It is up to the client to know when
to stop moving its search window.
2.1. The ESEARCH Response
In response to an ESEARCH command, the server MUST return ESEARCH
responses [RFC4731] (that is, not SEARCH responses). Because message
numbers are not useful for mailboxes that are not selected, the
responses MUST contain information about UIDs, not message numbers.
This is true even if the source options specify that only the
selected mailbox be searched.
Presence of a source option in the absence of a result option implies
the "ALL" result option (see Section 3.1 of [RFC4731]). Note that
this is not the same as the result from the SEARCH command described
in the IMAP base protocol [RFC3501].
Source options describe which mailboxes must be searched for
messages. An ESEARCH command with source options does not affect
which mailbox, if any, is currently selected, regardless of which
mailboxes are searched.
For each mailbox satisfying the source options, a single ESEARCH
response MUST be returned if any messages in that mailbox match the
search criteria. An ESEARCH response MUST NOT be returned for
mailboxes that contain no matching messages. This is true even when
result options such as MIN, MAX, and COUNT are specified (see
Section 3.1 of [RFC4731]), and the values returned (lowest UID
matched, highest UID matched, and number of messages matched,
respectively) apply to the mailbox reported in that ESEARCH response.
Leiba & Melnikov Experimental [Page 4]
RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011
Note that it is possible for an ESEARCH command to return *no*
untagged responses (no ESEARCH responses at all), in the case that
there are no matches to the search in any of the mailboxes that
satisfy the source options. Clients can detect this situation by
finding the tagged OK response without having received any matching
untagged ESEARCH responses.
Each ESEARCH response MUST contain the MAILBOX, TAG, and UIDVALIDITY
correlators. Correlators allow clients to issue several ESEARCH
commands at once (pipelined). If the SEARCHRES [RFC5182] extension
is used in an ESEARCH command, that ESEARCH command MUST be executed
by the server after all previous SEARCH/ESEARCH commands have
completed and before any subsequent SEARCH/ESEARCH commands are
executed. The server MAY perform consecutive ESEARCH commands in
parallel as long as none of them use the SEARCHRES extension.
2.2. Source Options: Specifying Mailboxes to Search
The source options, if present, MUST contain a mailbox specifier as
defined in the IMAP NOTIFY extension [RFC5465], Section 6 (using the
"filter-mailboxes" ABNF item), with the following differences:
1. The "selected-delayed" specifier is not valid here.
2. A "subtree-one" specifier is added. The "subtree" specifier
results in a search of the specified mailbox and all selectable
mailboxes that are subordinate to it, through an indefinitely
deep hierarchy. The "subtree-one" specifier results in a search
of the specified mailbox and all selectable child mailboxes, one
hierarchy level down.
If "subtree" is specified, the server MUST defend against loops in
the hierarchy (for example, those caused by recursive file-system
links within the message store). The server SHOULD do this by
keeping track of the mailboxes that have been searched, and
terminating the hierarchy traversal when a repeat is found. If it
cannot do that, it MAY do it by limiting the hierarchy depth.
If the source options are not present, the value "selected" is
assumed -- that is, only the currently selected mailbox is searched.
The "personal" source option is a particularly convenient way to
search all of the current user's mailboxes. Note that there is no
way to use wildcard characters to search all mailboxes; the
"mailboxes" source option does not do wildcard expansion.
Leiba & Melnikov Experimental [Page 5]
RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011
If the source options include (or default to) "selected", the IMAP
session MUST be in "selected" state. If the source options specify
other mailboxes and NOT "selected", then the IMAP session MUST be in
either "selected" or "authenticated" state. If the session is not in
a correct state, the ESEARCH command MUST return a "BAD" result.
If the server supports the SEARCHRES [RFC5182] extension, then the
"SAVE" result option is valid *only* if "selected" is specified or
defaulted as the sole mailbox to be searched. If any source option
other than "selected" is specified, the ESEARCH command MUST return a
"BAD" result.
If the server supports the CONTEXT=SEARCH and/or CONTEXT=SORT
extension [RFC5267], then the following additional rules apply:
o The CONTEXT return option (Section 4.2 of [RFC5267]) can be used
with an ESEARCH command.
o If the UPDATE return option is used (Section 4.3 of [RFC5267]), it
MUST apply ONLY to the currently selected mailbox. If UPDATE is
used and there is no mailbox currently selected, the ESEARCH
command MUST return a "BAD" result.
o The PARTIAL search return option (Section 4.4 of [RFC5267]) can be
used and applies to each mailbox searched by the ESEARCH command.
If the server supports the Access Control List (ACL) [RFC4314]
extension, then the logged-in user is required to have the "r" right
for each mailbox she wants to search. In addition, any mailboxes
that are not explicitly named (accessed through "personal" or
"subtree", for example) are required to have the "l" right.
Mailboxes matching the source options for which the logged-in user
lacks sufficient rights MUST be ignored by the ESEARCH command
processing. In particular, ESEARCH responses MUST NOT be returned
for those mailboxes.
3. Examples
In the following example, note that two ESEARCH commands are
pipelined, and that the server is running them in parallel,
interleaving a response to the second search amid the responses to
the first (watch the tags).
C: tag1 ESEARCH IN (mailboxes "folder1" subtree "folder2") unseen
C: tag2 ESEARCH IN (mailboxes "folder1" subtree-one "folder2")
subject "chad"
S: * ESEARCH (TAG "tag1" MAILBOX "folder1" UIDVALIDITY 1) UID ALL
4001,4003,4005,4007,4009
Leiba & Melnikov Experimental [Page 6]
RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011
S: * ESEARCH (TAG "tag2" MAILBOX "folder1" UIDVALIDITY 1) UID ALL
3001:3004,3788
S: * ESEARCH (TAG "tag1" MAILBOX "folder2/banana" UIDVALIDITY 503)
UID ALL 3002,4004
S: * ESEARCH (TAG "tag1" MAILBOX "folder2/peach" UIDVALIDITY 3) UID
ALL 921691
S: tag1 OK done
S: * ESEARCH (TAG "tag2" MAILBOX "folder2/salmon" UIDVALIDITY
1111111) UID ALL 50003,50006,50009,50012
S: tag2 OK done
4. Formal Syntax
The following syntax specification uses the Augmented Backus-Naur
Form (ABNF) as described in [RFC5234]. Terms not defined here are
taken from [RFC3501], [RFC5465], or [RFC4466].
command-auth =/ esearch
; Update definition from IMAP base [RFC3501].
; Add new "esearch" command.
command-select =/ esearch
; Update definition from IMAP base [RFC3501].
; Add new "esearch" command.
filter-mailboxes-other =/ ("subtree-one" SP one-or-more-mailbox)
; Update definition from IMAP Notify [RFC5465].
; Add new "subtree-one" selector.
filter-mailboxes-selected = "selected"
; Update definition from IMAP Notify [RFC5465].
; We forbid the use of "selected-delayed".
one-correlator = ("TAG" SP tag-string) / ("MAILBOX" SP astring) /
("UIDVALIDITY" SP nz-number)
; Each correlator MUST appear exactly once.
scope-option = scope-option-name [SP scope-option-value]
; No options defined here. Syntax for future extensions.
scope-option-name = tagged-ext-label
; No options defined here. Syntax for future extensions.
scope-option-value = tagged-ext-val
; No options defined here. Syntax for future extensions.
Leiba & Melnikov Experimental [Page 7]
RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011
scope-options = scope-option *(SP scope-option)
; A given option may only appear once.
; No options defined here. Syntax for future extensions.
esearch = "ESEARCH" [SP esearch-source-opts]
[SP search-return-opts] SP search-program
search-correlator = SP "(" one-correlator *(SP one-correlator) ")"
; Updates definition in IMAP4 ABNF [RFC4466].
esearch-source-opts = "IN" SP "(" source-mbox [SP
"(" scope-options ")"] ")"
source-mbox = filter-mailboxes *(SP filter-mailboxes)
; "filter-mailboxes" is defined in IMAP Notify [RFC5465].
; See updated definition of filter-mailboxes-other, above.
; See updated definition of filter-mailboxes-selected, above.
5. Security Considerations
This new IMAP ESEARCH command allows a single command to search many
mailboxes at once. On the one hand, a client could do that by
sending many IMAP SEARCH commands. On the other hand, this makes it
easier for a client to overwork a server, by sending a single command
that results in an expensive search of tens of thousands of
mailboxes. Server implementations need to be aware of that, and
provide mechanisms that prevent a client from adversely affecting
other users. Limitations on the number of mailboxes that may be
searched in one command, and/or on the server resources that will be
devoted to responding to a single client, are reasonable limitations
for an implementation to impose.
Implementations MUST, of course, apply access controls appropriately,
limiting a user's access to ESEARCH in the same way its access is
limited for any other IMAP commands. This extension has no data-
access risks beyond what may be there in the unextended IMAP
implementation.
Mailboxes matching the source options for which the logged-in user
lacks sufficient rights MUST be ignored by the ESEARCH command
processing (see the paragraph about this in Section 2.2). In
particular, any attempt to distinguish insufficient access from
non-existent mailboxes may expose information about the mailbox
hierarchy that isn't otherwise available to the client.
If "subtree" is specified, the server MUST defend against loops in
the hierarchy (see the paragraph about this in Section 2.2).
Leiba & Melnikov Experimental [Page 8]
RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011
6. IANA Considerations
IMAP4 capabilities are registered by publishing a Standards Track or
IESG-approved Experimental RFC. The "IMAP 4 Capabilities" registry
is currently located here:
http://www.iana.org/
This document defines the IMAP capability "MULTISEARCH", and IANA has
added it to the registry.
7. Acknowledgements
The authors gratefully acknowledge feedback provided by Timo
Sirainen, Peter Coates, and Arnt Gulbrandsen.
8. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2978] Freed, N. and J. Postel, "IANA Charset Registration
Procedures", BCP 19, RFC 2978, October 2000.
[RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
4rev1", RFC 3501, March 2003.
[RFC4314] Melnikov, A., "IMAP4 Access Control List (ACL) Extension",
RFC 4314, December 2005.
[RFC4466] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
ABNF", RFC 4466, April 2006.
[RFC4731] Melnikov, A. and D. Cridland, "IMAP4 Extension to SEARCH
Command for Controlling What Kind of Information Is
Returned", RFC 4731, November 2006.
[RFC5182] Melnikov, A., "IMAP Extension for Referencing the Last
SEARCH Result", RFC 5182, March 2008.
[RFC5234] Crocker, D., Ed., and P. Overell, "Augmented BNF for
Syntax Specifications: ABNF", STD 68, RFC 5234,
January 2008.
[RFC5267] Cridland, D. and C. King, "Contexts for IMAP4", RFC 5267,
July 2008.
Leiba & Melnikov Experimental [Page 9]
RFC 6237 IMAP4 Multimailbox SEARCH Extension May 2011
[RFC5465] Gulbrandsen, A., King, C., and A. Melnikov, "The IMAP
NOTIFY Extension", RFC 5465, February 2009.
Authors' Addresses
Barry Leiba
Huawei Technologies
Phone: +1 646 827 0648
EMail: barryleiba@computer.org
URI: http://internetmessagingtechnology.org/
Alexey Melnikov
Isode Limited
5 Castle Business Village
36 Station Road
Hampton, Middlesex TW12 2BX
UK
EMail: Alexey.Melnikov@isode.com
URI: http://www.melnikov.ca/
Leiba & Melnikov Experimental [Page 10]

339
docs/rfcs/rfc6331.Moving_Digest-MD5_to_Historic Normal file
View File

@ -0,0 +1,339 @@
Internet Engineering Task Force (IETF) A. Melnikov
Request for Comments: 6331 Isode Limited
Obsoletes: 2831 July 2011
Category: Informational
ISSN: 2070-1721
Moving DIGEST-MD5 to Historic
Abstract
This memo describes problems with the DIGEST-MD5 Simple
Authentication and Security Layer (SASL) mechanism as specified in
RFC 2831. It marks DIGEST-MD5 as OBSOLETE in the IANA Registry of
SASL mechanisms and moves RFC 2831 to Historic status.
Status of This Memo
This document is not an Internet Standards Track specification; it is
published for informational purposes.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Not all documents
approved by the IESG are a candidate for any level of Internet
Standard; see Section 2 of RFC 5741.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc6331.
Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Melnikov Informational [Page 1]
RFC 6331 Moving DIGEST-MD5 to Historic July 2011
This document may contain material from IETF Documents or IETF
Contributions published or made publicly available before November
10, 2008. The person(s) controlling the copyright in some of this
material may not have granted the IETF Trust the right to allow
modifications of such material outside the IETF Standards Process.
Without obtaining an adequate license from the person(s) controlling
the copyright in such materials, this document may not be modified
outside the IETF Standards Process, and derivative works of it may
not be created outside the IETF Standards Process, except to format
it for publication as an RFC or to translate it into languages other
than English.
Table of Contents
1. Introduction and Overview . . . . . . . . . . . . . . . . . . 2
2. Security Considerations . . . . . . . . . . . . . . . . . . . 5
3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5
4. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 5
5. References . . . . . . . . . . . . . . . . . . . . . . . . . 5
5.1. Normative References . . . . . . . . . . . . . . . . . . . . 5
5.2. Informative References . . . . . . . . . . . . . . . . . . . 5
1. Introduction and Overview
[RFC2831] defines how HTTP Digest Authentication [RFC2617] can be
used as a Simple Authentication and Security Layer (SASL) [RFC4422]
mechanism for any protocol that has a SASL profile. It was intended
both as an improvement over CRAM-MD5 [RFC2195] and as a convenient
way to support a single authentication mechanism for web, email, the
Lightweight Directory Access Protocol (LDAP), and other protocols.
While it can be argued that it is an improvement over CRAM-MD5, many
implementors commented that the additional complexity of DIGEST-MD5
makes it difficult to implement fully and securely.
Below is an incomplete list of problems with the DIGEST-MD5 mechanism
as specified in [RFC2831]:
1. The mechanism has too many options and modes. Some of them are
not well described and are not widely implemented. For example,
DIGEST-MD5 allows the "qop" directive to contain multiple values,
but it also allows for multiple qop directives to be specified.
The handling of multiple options is not specified, which results
in minor interoperability problems. Some implementations
amalgamate multiple qop values into one, while others treat
multiple qops as an error. Another example is the use of an
empty authorization identity. In SASL, an empty authorization
identity means that the client is willing to authorize as the
authentication identity. The document is not clear on whether
Melnikov Informational [Page 2]
RFC 6331 Moving DIGEST-MD5 to Historic July 2011
the authzid must be omitted or if it can be specified with an
empty value to convey this. The requirement for backward
compatibility with HTTP Digest means that the situation is even
worse. For example, DIGEST-MD5 requires all usernames/passwords
that can be entirely represented in the ISO-8859-1 charset to be
down converted from UTF-8 [RFC3629] to ISO-8859-1 [ISO-8859-1].
Another example is the use of quoted strings. Handling of
characters that need escaping is not properly described, and the
DIGEST-MD5 document has no examples to demonstrate correct
behavior.
2. The DIGEST-MD5 document uses ABNF from RFC 822 [RFC0822], which
allows an extra construct and allows for "implied folding
whitespace" to be inserted in many places. The difference from a
more common ABNF defined in [RFC5234] is confusing for some
implementors. As a result, many implementations do not accept
folding whitespace in many places where it is allowed.
3. The DIGEST-MD5 document uses the concept of a "realm" to define a
collection of accounts. A DIGEST-MD5 server can support one or
more realms. The DIGEST-MD5 document does not provide any
guidance on how realms should be named and, more importantly, how
they can be entered in User Interfaces (UIs). As a result, many
DIGEST-MD5 clients have confusing UIs, do not allow users to
enter a realm, and/or do not allow users to pick one of the
server-supported realms.
4. Use of username in the inner hash is problematic. The inner hash
of DIGEST-MD5 is an MD5 hash of colon-separated username, realm,
and password. Implementations may choose to store inner hashes
instead of clear text passwords. This has some useful
properties, such as protection from compromise of authentication
databases containing the same username and password on other
servers if a server with the username and password is
compromised; however, this is rarely done in practice. First,
the inner hash is not compatible with widely deployed Unix
password databases, and second, changing the username would
invalidate the inner hash.
5. Description of DES/3DES [DES] and RC4 security layers are
inadequate to produce independently developed interoperable
implementations. In the DES/3DES case, this is partly a problem
with existing DES APIs.
6. DIGEST-MD5 outer hash (the value of the "response" directive)
does not protect the whole authentication exchange, which makes
the mechanism vulnerable to "man-in-the-middle" (MITM) attacks,
such as modification of the list of supported qops or ciphers.
Melnikov Informational [Page 3]
RFC 6331 Moving DIGEST-MD5 to Historic July 2011
7. The following features are missing from DIGEST-MD5, making it
insecure or unsuitable for use in protocols:
A. Channel bindings [RFC5056].
B. Hash agility (i.e., no easy way to replace the MD5 hash
function with another one).
C. Support for SASLPrep [RFC4013] or any other type of Unicode
character normalization of usernames and passwords. The
original DIGEST-MD5 document predates SASLPrep and does not
recommend any Unicode character normalization.
8. The cryptographic primitives in DIGEST-MD5 are not up to today's
standards, in particular:
A. The MD5 hash is sufficiently weak to make a brute force
attack on DIGEST-MD5 easy with common hardware [RFC6151].
B. The RC4 algorithm is prone to attack when used as the
security layer without discarding the initial key stream
output [RFC6229].
C. The DES cipher for the security layer is considered insecure
due to its small key space [RFC3766].
Note that most of the problems listed above are already present in
the HTTP Digest authentication mechanism.
Because DIGEST-MD5 is defined as an extensible mechanism, it is
possible to fix most of the problems listed above. However, this
would increase implementation complexity of an already complex
mechanism even further, so the effort is not worth the cost. In
addition, an implementation of a "fixed" DIGEST-MD5 specification
would likely either not interoperate with any existing implementation
of [RFC2831] or would be vulnerable to various downgrade attacks.
Note that despite DIGEST-MD5 seeing some deployment on the Internet,
this specification recommends obsoleting DIGEST-MD5 because DIGEST-
MD5, as implemented, is not a reasonable candidate for further
standardization and should be deprecated in favor of one or more new
password-based mechanisms currently being designed.
The Salted Challenge Response Authentication Mechanism (SCRAM) family
of SASL mechanisms [RFC5802] has been developed to provide similar
features as DIGEST-MD5 but with a better design.
Melnikov Informational [Page 4]
RFC 6331 Moving DIGEST-MD5 to Historic July 2011
2. Security Considerations
Security issues are discussed throughout this document.
3. IANA Considerations
IANA has changed the "Intended usage" of the DIGEST-MD5 mechanism
registration in the SASL mechanism registry to OBSOLETE. The SASL
mechanism registry is specified in [RFC4422] and is currently
available at:
http://www.iana.org/assignments/sasl-mechanisms
4. Acknowledgements
The author gratefully acknowledges the feedback provided by Chris
Newman, Simon Josefsson, Kurt Zeilenga, Sean Turner, and Abhijit
Menon-Sen. Various text was copied from other RFCs, in particular,
from [RFC2831].
5. References
5.1. Normative References
[RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence,
S., Leach, P., Luotonen, A., and L. Stewart, "HTTP
Authentication: Basic and Digest Access
Authentication", RFC 2617, June 1999.
[RFC2831] Leach, P. and C. Newman, "Using Digest Authentication
as a SASL Mechanism", RFC 2831, May 2000.
5.2. Informative References
[DES] National Institute of Standards and Technology, "Data
Encryption Standard (DES)", FIPS PUB 46-3,
October 1999.
[ISO-8859-1] International Organization for Standardization,
"Information technology - 8-bit single-byte coded
graphic character sets - Part 1: Latin alphabet No. 1",
ISO/IEC 8859-1, 1998.
[RFC0822] Crocker, D., "Standard for the format of ARPA Internet
text messages", STD 11, RFC 822, August 1982.
Melnikov Informational [Page 5]
RFC 6331 Moving DIGEST-MD5 to Historic July 2011
[RFC2195] Klensin, J., Catoe, R., and P. Krumviede, "IMAP/POP
AUTHorize Extension for Simple Challenge/Response",
RFC 2195, September 1997.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003.
[RFC3766] Orman, H. and P. Hoffman, "Determining Strengths For
Public Keys Used For Exchanging Symmetric Keys",
BCP 86, RFC 3766, April 2004.
[RFC4013] Zeilenga, K., "SASLprep: Stringprep Profile for User
Names and Passwords", RFC 4013, February 2005.
[RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication
and Security Layer (SASL)", RFC 4422, June 2006.
[RFC5056] Williams, N., "On the Use of Channel Bindings to Secure
Channels", RFC 5056, November 2007.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008.
[RFC5802] Newman, C., Menon-Sen, A., Melnikov, A., and N.
Williams, "Salted Challenge Response Authentication
Mechanism (SCRAM) SASL and GSS-API Mechanisms",
RFC 5802, July 2010.
[RFC6151] Turner, S. and L. Chen, "Updated Security
Considerations for the MD5 Message-Digest and the HMAC-
MD5 Algorithms", RFC 6151, March 2011.
[RFC6229] Strombergson, J. and S. Josefsson, "Test Vectors for
the Stream Cipher RC4", RFC 6229, May 2011.
Author'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 Informational [Page 6]

119
docs/website-doc.sh Executable file
View File

@ -0,0 +1,119 @@
#!/bin/sh
#
# vim: expandtab ts=2 :
ARGS=$*
SPHINXBUILD=sphinx-build
TMPDIR='/tmp/offlineimap-sphinx-doctrees'
WEBSITE='./website'
DOCBASE="${WEBSITE}/_doc"
DESTBASE="${DOCBASE}/versions"
VERSIONS_YML="${WEBSITE}/_data/versions.yml"
ANNOUNCES_YML="${WEBSITE}/_data/announces.yml"
CONTRIB_YML="${WEBSITE}/_data/contribs.yml"
CONTRIB="${DOCBASE}/contrib"
HEADER="# DO NOT EDIT MANUALLY: it is generated by a script (website-doc.sh)."
function fix_pwd () {
cd "$(git rev-parse --show-toplevel)" || \
exit 2 "cannot determine the root of the repository"
test -d "$DESTBASE" || exit 1
}
fix_pwd
version="v$(./offlineimap.py --version)"
#
# Add the doc for the contrib files.
#
function contrib () {
echo $HEADER > "$CONTRIB_YML"
# systemd
cp -afv "./contrib/systemd/README.md" "${CONTRIB}/systemd.md"
echo "- {filename: 'systemd', linkname: 'Integrate with systemd'}" >> "$CONTRIB_YML"
}
#
# Build the sphinx documentation.
#
function api () {
# Build the doc with sphinx.
dest="${DESTBASE}/${version}"
echo "Cleaning target directory: $dest"
rm -rf "$dest"
$SPHINXBUILD -b html -d "$TMPDIR" ./docs/doc-src "$dest"
# Build the JSON definitions for Jekyll.
# This let know the website about the available APIs documentations.
echo "Building Jekyll data: $VERSIONS_YML"
# Erase previous content.
echo "$HEADER" > "$VERSIONS_YML"
for version in $(ls "$DESTBASE" -1 | sort -nr)
do
echo "- $version"
done >> "$VERSIONS_YML"
}
#
# Make Changelog public and save links to them as JSON.
#
function releases () {
# Copy the Changelogs.
for foo in ./Changelog.md ./Changelog.maint.md
do
cp -afv "$foo" "$DOCBASE"
done
# Build the announces JSON list. Format is JSON:
# - {version: '<version>', link: '<link>'}
# - ...
echo "$HEADER" > "$ANNOUNCES_YML"
grep -E '^### OfflineIMAP' ./Changelog.md | while read title
do
link="$(echo $title | sed -r -e 's,^### (OfflineIMAP.*)\),\1,' \
| tr '[:upper:]' '[:lower:]' \
| sed -r -e 's,[\.("],,g' \
| sed -r -e 's, ,-,g'
)"
v="$(echo $title \
| sed -r -e 's,^### [a-Z]+ (v[^ ]+).*,\1,'
)"
echo "- {version: '${v}', link: '$link'}"
done | tee -a "$ANNOUNCES_YML"
}
exit_code=0
test "n$ARGS" = 'n' && ARG='usage' # no option passed
for arg in $ARGS
do
# PWD was fixed at the very beginning.
case "n$arg" in
"nreleases")
releases
;;
"napi")
api
;;
"ncontrib")
contrib
;;
"nusage")
echo "Usage: website-doc.sh <releases|api|contrib|usage>"
;;
*)
echo "unkown option $arg"
exit_code=$(( $exit_code + 1 ))
;;
esac
done
exit $exit_code

1029
offlineimap.conf
View File

File diff suppressed because it is too large Load Diff

2
offlineimap.conf.minimal
View File

@ -1,5 +1,5 @@
# Sample minimal config file. Copy this to ~/.offlineimaprc and edit to # Sample minimal config file. Copy this to ~/.offlineimaprc and edit to
# suit to get started fast. # get started fast.
[general] [general]
accounts = Test accounts = Test

13
offlineimap.py
View File

@ -17,6 +17,19 @@
# along with this program; if not, write to the Free Software # along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
import os
import sys
if not 'DEVELOPING_OFFLINEIMAP_PYTHON3_SUPPORT' in os.environ:
if sys.version_info[0] > 2:
sys.stderr.write("""IIMAPS!
Sorry, OfflineIMAP currently doesn't support Python higher than 2.x.
We're doing our best to bring in support for 3.x really soon. You can
also join us at https://github.com/OfflineIMAP/offlineimap/ and help.
""")
sys.exit(1)
from offlineimap import OfflineImap from offlineimap import OfflineImap
oi = OfflineImap() oi = OfflineImap()

260
offlineimap/CustomConfig.py
View File

@ -1,5 +1,4 @@
# Copyright (C) 2003 John Goerzen # Copyright (C) 2003-2015 John Goerzen & contributors
# <jgoerzen@complete.org>
# #
# This program is free software; you can redistribute it and/or modify # This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by # it under the terms of the GNU General Public License as published by
@ -15,104 +14,299 @@
# along with this program; if not, write to the Free Software # along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
from ConfigParser import ConfigParser
from offlineimap.localeval import LocalEval
import os import os
import re
from sys import exc_info
try:
from ConfigParser import SafeConfigParser, Error
except ImportError: #python3
from configparser import SafeConfigParser, Error
from offlineimap.localeval import LocalEval
class CustomConfigParser(SafeConfigParser):
def __init__(self):
SafeConfigParser.__init__(self)
self.localeval = None
class CustomConfigParser(ConfigParser):
def getdefault(self, section, option, default, *args, **kwargs): def getdefault(self, section, option, default, *args, **kwargs):
"""Same as config.get, but returns the "default" option if there """Same as config.get, but returns the value of `default`
is no such option specified.""" if there is no such option specified."""
if self.has_option(section, option): if self.has_option(section, option):
return apply(self.get, [section, option] + list(args), kwargs) return self.get(*(section, option) + args, **kwargs)
else: else:
return default return default
def getdefaultint(self, section, option, default, *args, **kwargs): def getdefaultint(self, section, option, default, *args, **kwargs):
"""Same as config.getint, but returns the value of `default`
if there is no such option specified."""
if self.has_option(section, option): if self.has_option(section, option):
return apply(self.getint, [section, option] + list(args), kwargs) return self.getint(*(section, option) + args, **kwargs)
else: else:
return default return default
def getdefaultfloat(self, section, option, default, *args, **kwargs): def getdefaultfloat(self, section, option, default, *args, **kwargs):
"""Same as config.getfloat, but returns the value of `default`
if there is no such option specified."""
if self.has_option(section, option): if self.has_option(section, option):
return apply(self.getfloat, [section, option] + list(args), kwargs) return self.getfloat(*(section, option) + args, **kwargs)
else: else:
return default return default
def getdefaultboolean(self, section, option, default, *args, **kwargs): def getdefaultboolean(self, section, option, default, *args, **kwargs):
"""Same as config.getboolean, but returns the value of `default`
if there is no such option specified."""
if self.has_option(section, option): if self.has_option(section, option):
return apply(self.getboolean, [section, option] + list(args), return self.getboolean(*(section, option) + args, **kwargs)
kwargs) else:
return default
def getlist(self, section, option, separator_re):
"""Parses option as the list of values separated
by the given regexp."""
try:
val = self.get(section, option).strip()
return re.split(separator_re, val)
except re.error as e:
raise Error("Bad split regexp '%s': %s" % \
(separator_re, e)), None, exc_info()[2]
def getdefaultlist(self, section, option, default, separator_re):
"""Same as getlist, but returns the value of `default`
if there is no such option specified."""
if self.has_option(section, option):
return self.getlist(*(section, option, separator_re))
else: else:
return default return default
def getmetadatadir(self): def getmetadatadir(self):
metadatadir = os.path.expanduser(self.getdefault("general", "metadata", "~/.offlineimap")) xforms = [os.path.expanduser, os.path.expandvars]
d = self.getdefault("general", "metadata", "~/.offlineimap")
metadatadir = self.apply_xforms(d, xforms)
if not os.path.exists(metadatadir): if not os.path.exists(metadatadir):
os.mkdir(metadatadir, 0700) os.mkdir(metadatadir, 0o700)
return metadatadir return metadatadir
def getlocaleval(self): def getlocaleval(self):
# We already loaded pythonfile, so return this copy.
if self.localeval is not None:
return self.localeval
xforms = [os.path.expanduser, os.path.expandvars]
if self.has_option("general", "pythonfile"): if self.has_option("general", "pythonfile"):
path = os.path.expanduser(self.get("general", "pythonfile")) path = self.get("general", "pythonfile")
path = self.apply_xforms(path, xforms)
else: else:
path = None path = None
return LocalEval(path)
self.localeval = LocalEval(path)
return self.localeval
def getsectionlist(self, key): def getsectionlist(self, key):
"""Returns a list of sections that start with key + " ". That is, """Returns a list of sections that start with (str) key + " ".
if key is "Account", returns all section names that start with
"Account ", but strips off the "Account ". For instance, for That is, if key is "Account", returns all section names that
"Account Test", returns "Test".""" start with "Account ", but strips off the "Account ".
For instance, for "Account Test", returns "Test"."""
key = key + ' ' key = key + ' '
return [x[len(key):] for x in self.sections() \ return [x[len(key):] for x in self.sections() \
if x.startswith(key)] if x.startswith(key)]
def set_if_not_exists(self, section, option, value):
"""Set a value if it does not exist yet.
This allows to set default if the user has not explicitly
configured anything."""
if not self.has_option(section, option):
self.set(section, option, value)
def apply_xforms(self, string, transforms):
"""Applies set of transformations to a string.
Arguments:
- string: source string; if None, then no processing will
take place.
- transforms: iterable that returns transformation function
on each turn.
Returns transformed string."""
if string == None:
return None
for f in transforms:
string = f(string)
return string
def CustomConfigDefault(): def CustomConfigDefault():
"""Just a constant that won't occur anywhere else. """Just a constant that won't occur anywhere else.
This allows us to differentiate if the user has passed in any This allows us to differentiate if the user has passed in any
default value to the getconf* functions in ConfigHelperMixin default value to the getconf* functions in ConfigHelperMixin
derived classes.""" derived classes."""
pass pass
class ConfigHelperMixin: class ConfigHelperMixin:
"""Allow comfortable retrieving of config values pertaining to a section. """Allow comfortable retrieving of config values pertaining
to a section.
If a class inherits from this cls:`ConfigHelperMixin`, it needs If a class inherits from cls:`ConfigHelperMixin`, it needs
to provide 2 functions: meth:`getconfig` (returning a to provide 2 functions:
ConfigParser object) and meth:`getsection` (returning a string - meth:`getconfig` (returning a CustomConfigParser object)
which represents the section to look up). All calls to getconf* - and meth:`getsection` (returning a string which represents
will then return the configuration values for the ConfigParser the section to look up).
object in the specific section.""" All calls to getconf* will then return the configuration values
for the CustomConfigParser object in the specific section.
"""
def _confighelper_runner(self, option, default, defaultfunc, mainfunc): def _confighelper_runner(self, option, default, defaultfunc, mainfunc, *args):
"""Return config value for getsection()""" """Returns configuration or default value for option
that contains in section identified by getsection().
Arguments:
- option: name of the option to retrieve;
- default: governs which function we will call.
* When CustomConfigDefault is passed, we will call
the mainfunc.
* When any other value is passed, we will call
the defaultfunc and the value of `default` will
be passed as the third argument to this function.
- defaultfunc and mainfunc: processing helpers.
- args: additional trailing arguments that will be passed
to all processing helpers.
"""
lst = [self.getsection(), option]
if default == CustomConfigDefault: if default == CustomConfigDefault:
return apply(mainfunc, [self.getsection(), option]) return mainfunc(*(lst + list(args)))
else: else:
return apply(defaultfunc, [self.getsection(), option, default]) lst.append(default)
return defaultfunc(*(lst + list(args)))
def getconfig(self):
"""Returns CustomConfigParser object that we will use
for all our actions.
Must be overriden in all classes that use this mix-in."""
raise NotImplementedError("ConfigHelperMixin.getconfig() "
"is to be overriden")
def getconf(self, option,
default = CustomConfigDefault): def getsection(self):
"""Returns name of configuration section in which our
class keeps its configuration.
Must be overriden in all classes that use this mix-in."""
raise NotImplementedError("ConfigHelperMixin.getsection() "
"is to be overriden")
def getconf(self, option, default = CustomConfigDefault):
"""Retrieves string from the configuration.
Arguments:
- option: option name whose value is to be retrieved;
- default: default return value if no such option
exists.
"""
return self._confighelper_runner(option, default, return self._confighelper_runner(option, default,
self.getconfig().getdefault, self.getconfig().getdefault,
self.getconfig().get) self.getconfig().get)
def getconf_xform(self, option, xforms, default = CustomConfigDefault):
"""Retrieves string from the configuration transforming the result.
Arguments:
- option: option name whose value is to be retrieved;
- xforms: iterable that returns transform functions
to be applied to the value of the option,
both retrieved and default one;
- default: default value for string if no such option
exists.
"""
value = self.getconf(option, default)
return self.getconfig().apply_xforms(value, xforms)
def getconfboolean(self, option, default = CustomConfigDefault): def getconfboolean(self, option, default = CustomConfigDefault):
"""Retrieves boolean value from the configuration.
Arguments:
- option: option name whose value is to be retrieved;
- default: default return value if no such option
exists.
"""
return self._confighelper_runner(option, default, return self._confighelper_runner(option, default,
self.getconfig().getdefaultboolean, self.getconfig().getdefaultboolean,
self.getconfig().getboolean) self.getconfig().getboolean)
def getconfint(self, option, default = CustomConfigDefault): def getconfint(self, option, default = CustomConfigDefault):
"""
Retrieves integer value from the configuration.
Arguments:
- option: option name whose value is to be retrieved;
- default: default return value if no such option
exists.
"""
return self._confighelper_runner(option, default, return self._confighelper_runner(option, default,
self.getconfig().getdefaultint, self.getconfig().getdefaultint,
self.getconfig().getint) self.getconfig().getint)
def getconffloat(self, option, default = CustomConfigDefault): def getconffloat(self, option, default = CustomConfigDefault):
"""Retrieves floating-point value from the configuration.
Arguments:
- option: option name whose value is to be retrieved;
- default: default return value if no such option
exists.
"""
return self._confighelper_runner(option, default, return self._confighelper_runner(option, default,
self.getconfig().getdefaultfloat, self.getconfig().getdefaultfloat,
self.getconfig().getfloat) self.getconfig().getfloat)
def getconflist(self, option, separator_re,
default = CustomConfigDefault):
"""Retrieves strings from the configuration and splits it
into the list of strings.
Arguments:
- option: option name whose value is to be retrieved;
- separator_re: regular expression for separator
to be used for split operation;
- default: default return value if no such option
exists.
"""
return self._confighelper_runner(option, default,
self.getconfig().getdefaultlist,
self.getconfig().getlist, separator_re)

Some files were not shown because too many files have changed in this diff Show More