dany/imap
1
0
Fork 0
mirror of https://github.com/uw-imap/imap.git synced 2024-11-16 10:28:23 +01:00
Code Issues Packages Projects Releases Wiki Activity

Source from upstream; imap-2007f.tar.gz

Browse Source 
MD5 2126fd125ea26b73b20f01fcd5940369
This commit is contained in:
Chris 2019-01-03 04:12:17 -06:00
parent c6e9661b42
commit 22f316e36d
581 changed files with 216530 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
CONTENTS Normal file
View File

@ -0,0 +1,75 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
TOOLKIT DIRECTORY CONTENTS
Documentation:
. CONTENTS this file
. LICENSE.txt software license
. NOTICE copyright notice
. README read this file first
. SUPPORT where to go to ask questions and/or report bugs
. docs/BUILD build and installation instructions
. docs/CONFIG detailed configuration notes
. docs/FAQ.html frequently asked questions and answers
. docs/FAQ.txt text version of FAQ.HTML
. docs/RELNOTES release notes
. docs/SSLBUILD build and installation instructions using SSL
. docs/Y2K information relating to Y2K issues
. docs/bugs.txt known bugs and deficiencies in this software
. docs/calendar.txt information relating to the calendar
. docs/commndmt.txt "ten commandments" on how to write a good IMAP client
. docs/draft/ Internet protocol documentation drafts
. docs/drivers.txt how various mailbox format drivers interact, and
comparable features and performance
. docs/formats.txt mailbox formats
. docs/internal.txt programming interfaces
. docs/locking.txt how file locking works
. docs/md5.txt CRAM-MD5 authentication setup instructions
. docs/mixfmt.txt specification of new mix format
. docs/naming.txt mailbox naming conventions
. docs/rfc/ Internet protocol documentation
Sources:
. Makefile master makefile for UNIX
. makefile.nt master makefile for NT/Win32
. makefile.ntk master makefile for NT/Win32 using Kerberos V
. makefile.os2 master makefile for OS/2
. makefile.w2k master makefile for Windows 2000
. makefile.wce master makefile for Windows CE
. src/ansilib pre-processed ANSI library routines
. src/c-client pre-processed c-client sources
. src/charset pre-processed character set conversion tables
. src/dmail pre-processed user mail delivery sources
. src/ipopd pre-processed POP2/POP3 daemon sources
. src/imapd pre-processed IMAP4rev1 daemon sources
. src/mailutil pre-processed mailbox utility sources
. src/mlock pre-processed mailbox locking sources
. src/mtest pre-processed c-client testbed sources
. src/osdep/amiga pre-processed Amiga-specific sources
. src/osdep/dos pre-processed DOS-specific sources
. src/osdep/mac pre-processed Mac-specific sources
. src/osdep/nt pre-processed NT-specific sources
. src/osdep/os2 pre-processed OS/2-specific sources (incomplete)
. src/osdep/tops-20 pre-processed TOPS-20 specific sources
. src/osdep/unix pre-processed UNIX-specific sources
. src/osdep/vms pre-processed VAX/VMS specific sources
. src/osdep/wce pre-processed Windows CE-specific sources (incomplete)
. src/tmail pre-processed system mail delivery sources
. tools internal tools needed as part of the build process
Directories created at build time on UNIX and NT/Win32:
. c-client post-processed c-client sources and binary
. ipopd post-processed POP2/POP3 daemon sources and binaries
. imapd post-processed IMAP4rev1 daemon sources and binaries
. mtest post-processed c-client testbed sources and binaries

201
LICENSE.txt Normal file
View File

@ -0,0 +1,201 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

737
Makefile Normal file
View File

@ -0,0 +1,737 @@
# ========================================================================
# Copyright 1988-2008 University of Washington
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
#
# ========================================================================
# Program: IMAP Toolkit Makefile
#
# Author: Mark Crispin
# UW Technology
# Seattle, WA 98195
# Internet: MRC@Washington.EDU
#
# Date: 7 December 1989
# Last Edited: 12 May 2008
# Normal command to build IMAP toolkit:
# make <port> [EXTRAAUTHENTICATORS=xxx] [EXTRADRIVERS=xxx] [EXTRACFLAGS=xxx]
# [PASSWDTYPE=xxx] [SSLTYPE=xxx] [IP=n]
# Port name. These refer to the *standard* compiler on the given system.
# This means, for example, that the hpx port is for HP's compiler and not for
# a non-standard compiler such as gcc.
#
# If you are using gcc and it is not the standard compiler on your system, try
# using an ANSI port that is close to what you have. For example, if your
# system is SVR4ish, try a32 or lnx; if it's more BSDish, try nxt, mct, or bsi.
#
# The following ports are bundled:
# a32 AIX 3.2 for RS/6000
# a41 AIX 4.1 for RS/6000
# a52 Attempt at AIX 5.2
# aix AIX/370 (not RS/6000!!)
# ami AmigaDOS
# am2 AmigaDOS with a 68020+
# ama AmigaDOS using AS225R2
# amn AmigaDOS with a 680x0 using "new" socket library
# aos AOS for RT
# art AIX 2.2.1 for RT
# asv Altos SVR4
# aux A/UX
# bs3 BSD/i386 3.0 and higher
# bsd generic BSD 4.3 (as in ancient 1980s version)
# bsf FreeBSD
# bsi BSD/i386
# bso OpenBSD (yes, yet another one...)
# cvx Convex
# cyg Cygwin
# d-g Data General DG/UX prior to 5.4 (d41 port no longer exists)
# d54 Data General DG/UX 5.4
# do4 Apollo Domain/OS sr10.4
# dpx Bull DPX/2 B.O.S.
# drs ICL DRS/NX
# dyn Dynix
# epx EP/IX
# ga4 GCC AIX 4.x for RS/6000
# gas GCC Altos SVR4
# gcs GCC Solaris with Blastwave Community Open Source Software
# gh9 GCC HP-UX 9.x
# ghp GCC HP-UX 10.x
# ghs GCC HP-UX 10.x with Trusted Computer Base
# go5 GCC 2.7.1 (95q4 from Skunkware _not_ 98q2!) SCO Open Server 5.0.x
# gsc GCC Santa Cruz Operation
# gsg GCC SGI
# gso GCC Solaris
# gsu GCC SUN-OS
# gul GCC RISC Ultrix (DEC-5000)
# h11 HP-UX 11i
# hpp HP-UX 9.x (see gh9)
# hpx HP-UX 10.x (see ghp, ghs, hxd, and shp)
# hxd HP-UX 10.x with DCE security (see shp)
# isc Interactive Systems
# ldb Debian Linux
# lfd Fedora Core 4
# ln8 Linux for Nokia N800
# lnx Linux with traditional passwords and crypt() in the C library
# (see lnp, sl4, sl5, and slx)
# lnp Linux with Pluggable Authentication Modules (PAM)
# lmd Mandrake Linux
# lr5 RedHat Enterprise 5 and later (same as lfd)
# lrh RedHat Linux 7.2 and later
# lsu SuSE Linux (same as lrh)
# lyn LynxOS
# mct MachTen
# mnt Atari ST Mint (not MacMint)
# neb NetBSD
# nec NEC UX
# nto QNX Neutrine RTP
# nxt NEXTSTEP
# nx3 NEXTSTEP 3.x
# osf OSF/1 (see sos, os4)
# os4 OSF/1 (Digital UNIX) 4
# osi Apple iPhone and iPod Touch
# osx Mac OS X
# oxp Mac OS X with Pluggable Authentication Modules (PAM)
# ptx PTX
# pyr Pyramid
# qnx QNX 4
# s40 SUN-OS 4.0 (*not* Solaris)
# sc5 SCO Open Server 5.0.x (see go5)
# sco Santa Cruz Operation (see sc5, go5)
# shp HP-UX with Trusted Computer Base
# sgi Silicon Graphics IRIX
# sg6 Silicon Graphics IRIX 6.5
# sl4 Linux using -lshadow to get the crypt() function
# sl5 Linux with shadow passwords, no extra libraries
# slx Linux using -lcrypt to get the crypt() function
# snx Siemens Nixdorf SININX or Reliant UNIX
# soc Solaris with /opt/SUNWspro/bin/cc
# sol Solaris (won't work unless "ucbcc" works -- use gso instead)
# sos OSF/1 with SecureWare
# ssn SUN-OS with shadow password security
# sua Windows Vista (Enterprise or Ultima) Subsystem for Unix Applications
# sun SUN-OS 4.1 or better (*not* Solaris) (see ssn)
# sv2 SVR2 on AT&T PC-7300 (incomplete port)
# sv4 generic SVR4
# ult RISC Ultrix (DEC-5000)
# uw2 UnixWare SVR4.2
# vul VAX Ultrix
# vu2 VAX Ultrix 2.3 (e.g. for VAXstation-2000 or similar old version)
# Extra authenticators (e.g. OTP, Kerberos, etc.). Adds linkage for
# auth_xxx.c and executes Makefile.xxx, where xxx is the name of the
# authenticator. Some authenticators are only available from third parties.
#
# The following extra authenticators are bundled:
# gss Kerberos V
EXTRAAUTHENTICATORS=
# Additional mailbox drivers. Add linkage for xxxdriver. Some drivers are
# only available from third parties.
#
# The following extra drivers are bundled:
# mbox if file "mbox" exists on the home directory, automatically moves mail
# from the spool directory to "mbox" and uses "mbox" as INBOX.
EXTRADRIVERS=mbox
# Plaintext password type. Defines how plaintext password authentication is
# done on this system.
#
# The following plaintext login types are bundled:
# afs AFS authentication database
# dce DCE authentication database
# gss Kerberos V
# nul plaintext authentication never permitted
# pam PAM authentication (note: for Linux, you should use the "lnp" port
# instead of setting this...also, you may have to modify PAMLDFLAGS
# in the imap-[]/src/osdep/unix/Makefile
# pmb PAM authentication for broken implementations such as Solaris.
# you may have to modify PAMLDFLAGS
# std system standard (typically passwd file), determined by port
# two try alternative (defined by CHECKPWALT), then std
PASSWDTYPE=std
# SSL type. Defines whether or not SSL support is on this system
#
# The following SSL types are bundled:
# none no SSL support
# unix SSL support using OpenSSL
# nopwd SSL support using OpenSSL, and plaintext authentication permitted only
# in SSL/TLS sessions
# sco link SSL before other libraries (for SCO systems)
# unix.nopwd same as nopwd
# sco.nopwd same as nopwd, plaintext authentication in SSL/TLS only
#
# SSLTYPE=nopwd is now the default as required by RFC 3501
SSLTYPE=nopwd
# IP protocol version
#
# The following IP protocol versions are defined:
# o IPv4 support, no DNS (truly ancient systems)
# 4 (default) IPv4 support only
# 6 IPv6 and IPv4 support
IP=4
IP6=6
# The following extra compilation flags are defined. None of these flags are
# recommended. If you use these, include them in the EXTRACFLAGS.
#
# -DDISABLE_POP_PROXY
# By default, the ipop[23]d servers offer POP->IMAP proxy access,
# which allow a POP client to access mail on an IMAP server by using the
# POP server as a go-between. Setting this option disables this
# facility.
#
# -DOLDFILESUFFIX=\"xxx\"
# Change the default suffix appended to the backup .newsrc file from
# "old".
#
# -DSTRICT_RFC822_TIMEZONES
# Disable recognition of the non-standard UTC (0000), MET (+0100),
# EET (+0200), JST (+0900), ADT (-0300), AST (-0400), YDT (-0800),
# YST (-0900), and HST (-1000) symbolic timezones.
#
# -DBRITISH_SUMMER_TIME
# Enables recognition of non-standard symbolic timezone BST as +0100.
#
# -DBERING_STANDARD_TIME
# Enables recognition of non-standard symbolic timezone BST as -1100.
#
# -DNEWFOUNDLAND_STANDARD_TIME
# Enables recognition of non-standard symbolic timezone NST as -0330.
#
# -DNOME_STANDARD_TIME
# Enables recognition of non-standard symbolic timezone NST as -1100.
#
# -DSAMOA_STANDARD_TIME
# Enables recognition of non-standard symbolic timezone SST as -1100.
#
# -DY4KBUGFIX
# Turn on the Y4K bugfix (yes, that's year 4000). It isn't well-known,
# but century years evenly divisible by 4000 are *not* leap years in the
# Gregorian calendar. A lot of "Y2K compilant" software does not know
# about this rule. Remember to turn this on sometime in the next 2000
# years.
#
# -DUSEORTHODOXCALENDAR
# Use the more accurate Eastern Orthodox calendar instead of the
# Gregorian calendar. The century years which are leap years happen
# at alternating 400 and 500 year intervals without shifts every 4000
# years. The Orthodox and Gregorian calendars diverge by 1 day for
# gradually-increasing intervals, starting at 2800-2900, and becoming
# permanent at 48,300.
#
# -DUSEJULIANCALENDAR
# Use the less accurate Julian calendar instead of the Gregorian
# calendar. Leap years are every 4 years, including century years.
# My apologies to those in the English-speaking world who object to
# the reform of September 2, 1752 -> September 14, 1752, since this
# code still uses January 1 (which Julius Ceasar decreed as the start
# of the year, which since 153 BCE was the day that Roman consuls
# took office), rather than the traditional March 25 used by the
# British. As of 2005, the Julian calendar and the Gregorian calendar
# diverge by 15 days.
EXTRACFLAGS=
# Extra linker flags (additional/alternative libraries, etc.)
EXTRALDFLAGS=
# Special make flags (e.g. to override make environment variables)
EXTRASPECIALS=
SPECIALS=
# Normal commands
CAT=cat
CD=cd
LN=ln -s
MAKE=make
MKDIR=mkdir
BUILDTYPE=rebuild
RM=rm -rf
SH=sh
SYSTEM=unix
TOOLS=tools
TOUCH=touch
# Primary build command
BUILD=$(MAKE) build EXTRACFLAGS='$(EXTRACFLAGS)'\
EXTRALDFLAGS='$(EXTRALDFLAGS)'\
EXTRADRIVERS='$(EXTRADRIVERS)'\
EXTRAAUTHENTICATORS='$(EXTRAAUTHENTICATORS)'\
PASSWDTYPE=$(PASSWDTYPE) SSLTYPE=$(SSLTYPE) IP=$(IP)\
EXTRASPECIALS='$(EXTRASPECIALS)'
# Make the IMAP Toolkit
all: c-client SPECIALS rebuild bundled
c-client:
@echo Not processed yet. In a first-time build, you must specify
@echo the system type so that the sources are properly processed.
@false
SPECIALS:
echo $(SPECIALS) > SPECIALS
# Note on SCO you may have to set LN to "ln".
a32 a41 a52 aix bs3 bsi d-g d54 do4 drs epx ga4 gas gh9 ghp ghs go5 gsc gsg gso gul h11 hpp hpx lnp lyn mct mnt nec nto nxt nx3 osf os4 ptx qnx sc5 sco sgi sg6 shp sl4 sl5 slx snx soc sol sos uw2: an
$(BUILD) BUILDTYPE=$@
# If you use sv4, you may find that it works to move it to use the an process.
# If so, you probably will want to delete the "-Dconst=" from the sv4 CFLAGS in
# the c-client Makefile.
aos art asv aux bsd cvx dpx dyn isc pyr sv4 ult vul vu2: ua
$(BUILD) BUILDTYPE=$@
# Knotheads moved Kerberos and SSL locations on these platforms
# Paul Vixie claims that all FreeBSD versions have working IPv6
bsf: an
$(TOUCH) ip6
$(BUILD) BUILDTYPE=$@ IP=$(IP6) \
PASSWDTYPE=pam \
SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/etc/ssl/certs SSLKEYS=/etc/ssl/private GSSINCLUDE=/usr/include GSSLIB=/usr/lib PAMLDFLAGS=-lpam"
# I assume that Theo did the right thing for IPv6. OpenBSD does not have PAM.
bso: an
$(TOUCH) ip6
$(BUILD) BUILDTYPE=$@ IP=$(IP6) \
SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/etc/ssl SSLKEYS=/etc/ssl/private GSSINCLUDE=/usr/include GSSLIB=/usr/lib"
# Info from Joel Reicher about NetBSD SSL paths. I assume it has PAM because pam is in NetBSD sources...
neb: an
$(TOUCH) ip6
$(BUILD) BUILDTYPE=$@ IP=$(IP6) \
PASSWDTYPE=pam \
SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/etc/openssl/certs SSLKEYS=/etc/openssl/private GSSINCLUDE=/usr/include GSSLIB=/usr/lib PAMLDFLAGS=-lpam"
cyg: an
$(BUILD) BUILDTYPE=cyg \
SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/usr/ssl/certs SSLKEYS=/usr/ssl/certs"
gcs: an
$(BUILD) BUILDTYPE=gso \
SPECIALS="SSLINCLUDE=/opt/csw/include/openssl SSLLIB=/opt/csw/lib SSLCERTS=/opt/csw/ssl/certs SSLKEYS=/opt/csw/ssl/certs"
ldb: an
$(BUILD) BUILDTYPE=lnp IP=$(IP6) \
SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/etc/ssl/certs SSLKEYS=/etc/ssl/private GSSINCLUDE=/usr/include GSSLIB=/usr/lib MAILSPOOL=/var/mail"
lfd: an
$(BUILD) BUILDTYPE=lnp IP=$(IP6) \
SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/etc/pki/tls/certs SSLKEYS=/etc/pki/tls/private GSSDIR=/usr/kerberos"
ln8: an
$(TOUCH) ip6
$(BUILD) BUILDTYPE=slx IP=$(IP6) \
SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/usr/lib/ssl/certs MAILSPOOL=/var/mail"
# RHE5 does not have the IPv6 bug
lr5: an
$(TOUCH) ip6
$(BUILD) BUILDTYPE=lnp IP=$(IP6) \
SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/etc/pki/tls/certs SSLKEYS=/etc/pki/tls/private GSSDIR=/usr/kerberos"
lmd: an
$(BUILD) BUILDTYPE=lnp IP=$(IP6) \
SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/usr/lib/ssl/certs SSLKEYS=/usr/lib/ssl/private GSSINCLUDE=/usr/include GSSLIB=/usr/lib"
# RHE3 definitely has the IPv6 bug
lrh: lrhok an
$(BUILD) BUILDTYPE=lnp IP=$(IP6) \
SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/usr/share/ssl/certs SSLKEYS=/usr/share/ssl/private GSSDIR=/usr/kerberos"
lrhok:
@$(SH) -c '(test ! -d /etc/pki/tls ) || make lrhwarn'
@$(TOUCH) lrhok
lrhwarn:
@echo You are building for OLD versions of RedHat Linux. This build
@echo is NOT suitable for RedHat Enterprise 5, which stores SSL/TLS
@echo certificates and keys in /etc/pki/tls rather than /usr/share/ssl.
@echo If you want to build for modern RedHat Linux, you should use
@echo make lr5 instead.
@echo Do you want to continue this build? Type y or n please:
@$(SH) -c 'read x; case "$$x" in y) exit 0;; *) exit 1;; esac'
@echo OK, I will remember that you really want to build for old
@echo RedHat Linux. You will not see this message again.
@echo If you realize that you really wanted to build for modern
@echo RedHat Linux, then do the following commands:
@echo % rm lrhok
@echo % make clean
@echo % make lr5
lsu: an
$(BUILD) BUILDTYPE=lnp IP=$(IP6) \
SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/usr/share/ssl/certs SSLKEYS=/usr/share/ssl/private GSSDIR=/usr/kerberos"
# iToy does not have Kerberos or PAM. It doesn't have a
# /System/Library/OpenSSL directory either, but the libcrypto shared library
# has these locations so this is what we will use.
osi: an
$(TOUCH) ip6
$(BUILD) BUILDTYPE=osx IP=$(IP6) CC=arm-apple-darwin-gcc \
SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/System/Library/OpenSSL/certs SSLKEYS=/System/Library/OpenSSL/private"
oxp: an
$(TOUCH) ip6
$(BUILD) BUILDTYPE=osx IP=$(IP6) EXTRAAUTHENTICATORS="$(EXTRAAUTHENTICATORS) gss" \
PASSWDTYPE=pam \
EXTRACFLAGS="$(EXTRACFLAGS) -DMAC_OSX_KLUDGE=1" \
SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/System/Library/OpenSSL/certs SSLKEYS=/System/Library/OpenSSL/private GSSINCLUDE=/usr/include GSSLIB=/usr/lib PAMDLFLAGS=-lpam"
osx: osxok an
$(TOUCH) ip6
$(BUILD) BUILDTYPE=$@ IP=$(IP6) EXTRAAUTHENTICATORS="$(EXTRAAUTHENTICATORS) gss" \
SPECIALS="SSLINCLUDE=/usr/include/openssl SSLLIB=/usr/lib SSLCERTS=/System/Library/OpenSSL/certs SSLKEYS=/System/Library/OpenSSL/private GSSINCLUDE=/usr/include GSSLIB=/usr/lib"
osxok:
@$(SH) -c '(test ! -f /usr/include/pam/pam_appl.h ) || make osxwarn'
@$(TOUCH) osxok
osxwarn:
@echo You are building for OLD versions of Mac OS X. This build is
@echo NOT suitable for modern versions of Mac OS X, such as Tiger,
@echo which use PAM-based authentication. If you want to build for
@echo modern Mac OS X, you should use make oxp instead.
@echo Do you want to continue this build? Type y or n please:
@$(SH) -c 'read x; case "$$x" in y) exit 0;; *) exit 1;; esac'
@echo OK, I will remember that you really want to build for old
@echo Mac OS X. You will not see this message again.
@echo If you realize that you really wanted to build for modern
@echo Mac OS X, then do the following commands:
@echo % rm osxok
@echo % make clean
@echo % make oxp
# Linux shadow password support doesn't build on traditional systems, but most
# Linux systems are shadow these days.
lnx: lnxnul an
$(BUILD) BUILDTYPE=$@
lnxnul:
@$(SH) -c '(test $(PASSWDTYPE) = nul) || make lnxok'
lnxok:
@echo You are building for traditional Linux. Most modern Linux
@echo systems require that you build using make slx.
@echo Do you want to continue this build? Type y or n please:
@$(SH) -c 'read x; case "$$x" in y) exit 0;; *) exit 1;; esac'
@echo OK, I will remember that you really want to build for
@echo traditional Linux. You will not see this message again.
@echo If you discover that you can not log in to the POP and IMAP
@echo servers, then do the following commands:
@echo % rm lnxok
@echo % make clean
@echo % make slx
@echo If slx does not work, try sl4 or sl5. Be sure to do a
@echo make clean between each try!
@$(TOUCH) lnxok
# SUN-OS C compiler makes you load libdl by hand...
ssn sun: sunok suntools ua
$(BUILD) BUILDTYPE=$@
suntools:
$(CD) tools;$(MAKE) LDFLAGS=-ldl
gsu: sunok an
$(BUILD) BUILDTYPE=$@
s40: sunok ua
$(BUILD) BUILDTYPE=$@
sunok:
@echo You are building for the old BSD-based SUN-OS. This is NOT
@echo the modern SVR4-based Solaris. If you want to build for
@echo Solaris, you should use make gso or make sol or make soc. Do
@echo you want to continue this build? Type y or n please:
@$(SH) -c 'read x; case "$$x" in y) exit 0;; *) exit 1;; esac'
@echo OK, I will remember that you really want to build for the old
@echo BSD-based SUN-OS. You will not see this message again.
@echo If the build fails and you realize that you really wanted to
@echo build for Solaris, then do the following commands:
@echo % rm sunok
@echo % make clean
@echo % make gso
@echo If gso does not work, try sol. Be sure to do a make clean
@echo between each try!
@$(TOUCH) sunok
# SVR2 doesn't have symbolic links (at least my SVR2 system doesn't)
sv2:
$(MAKE) ua LN=ln
$(BUILD) BUILDTYPE=$@ LN=ln
# Hard links don't quite work right in SUA, and there don't seem to be any
# SSL includes. However, IPv6 works.
sua:
$(TOUCH) ip6 sslnone
$(MAKE) an LN=cp SSLTYPE=none
$(BUILD) BUILDTYPE=$@ LN=cp IP=$(IP6) SSLTYPE=none
# Pine port names, not distinguished in c-client
bs2: an
$(BUILD) BUILDTYPE=bsi
pt1: an
$(BUILD) BUILDTYPE=ptx
# Compatibility
hxd:
$(BUILD) BUILDTYPE=hpx PASSWDTYPE=dce
# Amiga
ami am2 ama amn:
$(MAKE) an LN=cp SYSTEM=amiga
$(BUILD) BUILDTYPE=$@ LN=cp
# Courtesy entries for Microsoft systems
nt:
nmake /nologo /f makefile.nt
ntk:
nmake /nologo /f makefile.ntk
w2k:
nmake /nologo /f makefile.w2k
wce:
nmake /nologo /f makefile.wce
# SSL build choices
sslnopwd sslunix.nopwd sslsco.nopwd:
@echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@echo + Building in full compliance with RFC 3501 security
@echo + requirements:
@echo ++ TLS/SSL encryption is supported
@echo ++ Unencrypted plaintext passwords are prohibited
@echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
sslunix sslsco:
@echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@echo + Building in PARTIAL compliance with RFC 3501 security
@echo + requirements:
@echo + Compliant:
@echo ++ TLS/SSL encryption is supported
@echo + Non-compliant:
@echo ++ Unencrypted plaintext passwords are permitted
@echo +
@echo + In order to rectify this problem, you MUST build with:
@echo ++ SSLTYPE=$(SSLTYPE).nopwd
@echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@echo
@echo Do you want to continue this build anyway? Type y or n please:
@$(SH) -c 'read x; case "$$x" in y) exit 0;; *) (make nounenc;exit 1);; esac'
nounenc:
@echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@echo + At your request, this build with unencrypted authentication has
@echo + been CANCELLED.
@echo + You must start over with a new make command.
@echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
sslnone:
@echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@echo + Building in NON-COMPLIANCE with RFC 3501 security requirements:
@echo + Non-compliant:
@echo ++ TLS/SSL encryption is NOT supported
@echo ++ Unencrypted plaintext passwords are permitted
@echo +
@echo + In order to rectify this problem, you MUST build with:
@echo ++ SSLTYPE=nopwd
@echo + You must also have OpenSSL or equivalent installed.
@echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@echo
@echo Do you want to continue this build anyway? Type y or n please:
@$(SH) -c 'read x; case "$$x" in y) exit 0;; *) (make nonossl;exit 1);; esac'
nonossl:
@echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@echo + At your request, this build with no TLS/SSL support has been
@echo + CANCELLED.
@echo + You must start over with a new make command.
@echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# IP build choices
ip4:
@echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@echo + Building with IPv4 support
@echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
ip6:
@echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@echo + Building with IPv6 support
@echo +
@echo + NOTE: Some versions of glibc have a bug in the getaddrinfo
@echo + call which does DNS name resolution. This bug causes host
@echo + names to be canonicalized incorrectly, as well as doing an
@echo + unnecessary and performance-sapping reverse DNS call. This
@echo + problem does not affect the IPv4 gethostbyname call.
@echo +
@echo + getaddrinfo works properly on Mac OS X and Windows. However,
@echo + the problem has been observed on some Linux systems.
@echo +
@echo + If you answer n to the following question the build will be
@echo + cancelled and you must rebuild. If you did not specify IPv6
@echo + yourself, try adding IP6=4 to the make command line.
@echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@echo
@echo Do you want to build with IPv6 anyway? Type y or n please:
@$(SH) -c 'read x; case "$$x" in y) exit 0;; *) (make noip6;exit 1);; esac'
@echo OK, I will remember that you really want to build with IPv6.
@echo You will not see this message again.
@$(TOUCH) ip6
noip6:
$(MAKE) clean
@echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@echo + At your request, this build with IPv6 has been CANCELLED.
@echo + You must start over with a new make command.
@echo +
@echo + If you wish to rebuild without IPv6 support, do one of the
@echo + following:
@echo +
@echo + 1. If you specified IP=6 on the make command line, omit it.
@echo +
@echo + 2. Some of the Linux builds automatically select IPv6. If
@echo + you choose one of those builds, add IP6=4 to the make command
@echo + line. Note that this is IP6=4, not IP=4.
@echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# C compiler types
an ua:
@$(MAKE) ssl$(SSLTYPE)
@echo Applying $@ process to sources...
$(TOOLS)/$@ "$(LN)" src/c-client c-client
$(TOOLS)/$@ "$(LN)" src/ansilib c-client
$(TOOLS)/$@ "$(LN)" src/charset c-client
$(TOOLS)/$@ "$(LN)" src/osdep/$(SYSTEM) c-client
$(TOOLS)/$@ "$(LN)" src/mtest mtest
$(TOOLS)/$@ "$(LN)" src/ipopd ipopd
$(TOOLS)/$@ "$(LN)" src/imapd imapd
$(TOOLS)/$@ "$(LN)" src/mailutil mailutil
$(TOOLS)/$@ "$(LN)" src/mlock mlock
$(TOOLS)/$@ "$(LN)" src/dmail dmail
$(TOOLS)/$@ "$(LN)" src/tmail tmail
$(LN) $(TOOLS)/$@ .
build: OSTYPE rebuild rebuildclean bundled
OSTYPE:
@$(MAKE) ip$(IP)
@echo Building c-client for $(BUILDTYPE)...
@$(TOUCH) SPECIALS
echo `$(CAT) SPECIALS` $(EXTRASPECIALS) > c-client/SPECIALS
$(CD) c-client;$(MAKE) $(BUILDTYPE) EXTRACFLAGS='$(EXTRACFLAGS)'\
EXTRALDFLAGS='$(EXTRALDFLAGS)'\
EXTRADRIVERS='$(EXTRADRIVERS)'\
EXTRAAUTHENTICATORS='$(EXTRAAUTHENTICATORS)'\
PASSWDTYPE=$(PASSWDTYPE) SSLTYPE=$(SSLTYPE) IP=$(IP)\
$(SPECIALS) $(EXTRASPECIALS)
echo $(BUILDTYPE) > OSTYPE
$(TOUCH) rebuild
rebuild:
@$(SH) -c '(test $(BUILDTYPE) = rebuild -o $(BUILDTYPE) = `$(CAT) OSTYPE`) || (echo Already built for `$(CAT) OSTYPE` -- you must do \"make clean\" first && exit 1)'
@echo Rebuilding c-client for `$(CAT) OSTYPE`...
@$(TOUCH) SPECIALS
$(CD) c-client;$(MAKE) all CC=`$(CAT) CCTYPE` \
CFLAGS="`$(CAT) CFLAGS`" `$(CAT) SPECIALS`
rebuildclean:
$(SH) -c '$(RM) rebuild || true'
bundled:
@echo Building bundled tools...
$(CD) mtest;$(MAKE)
$(CD) ipopd;$(MAKE)
$(CD) imapd;$(MAKE)
$(CD) mailutil;$(MAKE)
@$(SH) -c '(test -f /usr/include/sysexits.h ) || make sysexitwarn'
$(CD) mlock;$(MAKE) || true
$(CD) dmail;$(MAKE) || true
$(CD) tmail;$(MAKE) || true
sysexitwarn:
@echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@echo + Hmm...it does not look like /usr/include/sysexits.h exists.
@echo + Either your system is too ancient to have the sysexits.h
@echo + include, or your C compiler gets it from some other location
@echo + than /usr/include. If your system is too old to have the
@echo + sysexits.h include, you will not be able to build the
@echo + following programs.
@echo +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
clean:
@echo Removing old processed sources and binaries...
$(SH) -c '$(RM) an ua OSTYPE SPECIALS c-client mtest imapd ipopd mailutil mlock dmail tmail || true'
$(CD) tools;$(MAKE) clean
# A monument to a hack of long ago and far away...
love:
@echo not war?

17
NOTICE Normal file
View File

@ -0,0 +1,17 @@
UW IMAP toolkit notices:
This software was developed by the University of Washington
(http://www.washington.edu/).
The Univerity of Washington IMAP Toolkit (c-client API, dmail, imapd,
ipop2d, ipop3d, mailutil, mlock, mtest, and tmail software; and its
included text) is Copyright 1988-2007 by the University of Washington.
The c-client library and mtest software are in part based upon code
developed by Mark Crispin at Stanford University, and is
* Copyright 1988 Stanford University and was developed in the
* Symbolic Systems Resources Group of the Knowledge Systems Laboratory
* at Stanford University in 1987-88, and was funded by the
* Biomedical Research Technology Program of the National Institutes of
* Health under grant number RR-00785.

74
README Normal file
View File

@ -0,0 +1,74 @@
/* ========================================================================
* Copyright 1988-2007 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
IMAP Toolkit Environment
4 April 2007
Mark Crispin
UNIX QUICK BUILD NOTES
These quick build notes assume that you have installed OpenSSL before
attempting to build this software, and that you do not have any non-default
configuration parameters.
If you need additional information in building this software with OpenSSL,
please refer to the docs/SSLBUILD file for more information.
If you intend to build this software with a non-default configuration
(including building a non-compliant server without SSL support), please
refer to the docs/BUILD file for more information.
1) Look in the top-level Makefile and find your system type code. For example,
modern versions of Linux will use either "slx", "lnp", or one of the
lnp-variants (such as "lrh").
2) Type "make" followed by the system type, e.g. "make slx".
3) Install the POP2 daemon (ipopd/ipop2d), the POP3 daemon (ipopd/ipop3d), and
the IMAP daemon (imapd/imapd) on a system directory of your choosing.
4) Update /etc/services to register the pop2 service on TCP port 109, the
pop3 service on TCP port 110, and the imap service on TCP port 143. Also
update Yellow Pages/NIS/NetInfo/etc. if appropriate on your system.
5) Update /etc/inetd.conf (or install files on /etc/xinetd.d) to invoke the
POP2, POP3, and IMAP daemons on their associated services.
6) If your system uses PAM authentication, be sure to set up /etc/pam.d/imap
(*not* /etc/pam.d/imapd) and /etc/pam.d/pop (*not* /etc/pam.d/ipop3d or
/etc/pam.d/pop3d or /etc/pam.d/popd or /etc/pam.d/pop3).
7) Unless you built your system without SSL support, you will need to set
up SSL server certificates as described in docs/SSLBUILD.
6) That's all!
Read the file docs/BUILD and docs/SSLBUILD if you need more detailed
information and/or you don't understand these quick build instructions.
MISCELLANEOUS NOTES
mtest has been run under UNIX, DOS, Windows, NT, Macintosh, TOPS-20, and
VMS. It is a very primitive interface, however, and is suited mainly as a
model of how to write a main program for c-client. You should take a look at
the source to figure out how to use it. Briefly, it first asks for a mailbox
name (either a local file path or an IMAP mailbox in the form
"{hostname}mailbox") and then puts you in a command mode where "?" will give
you a list of commands.
Pine is available separately on the FTP.CAC.Washington.EDU archives.
The focus of development and support is for UNIX and Win32 (including
Windows 95/98/Millenium, Windows NT, and Windows 2000). The other ports are
not frequently used or tested, and may be incomplete.

22
SUPPORT Normal file
View File

@ -0,0 +1,22 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
BUG REPORTING ADDRESS
Bug reports, comments, or questions regarding this software may
be reported to the imap-uw@u.washington.edu mailing list (this replaces
the old c-client@u.washington.edu mailing list). You can subscribe to
this list by sending a message to:
imap-uw-subscribe@mailman.u.washington.edu
An alternative is to use the comp.mail.imap newsgroup.

491
docs/BUILD Normal file
View File

@ -0,0 +1,491 @@
/* ========================================================================
* Copyright 1988-2007 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
BUILD AND INSTALLATION NOTES
Last Updated: 15 November 2007
Table of Contents:
1. UNIX Build Notes
2. UNIX Installation Notes
3. Win32 Build Notes
4. Win32 Installation Notes
5. Inactive Ports (TOPS-20, VMS)
6. Other ports (Macintosh, DOS/Win16, Windows CE, Amiga, OS/2)
UNIX BUILD NOTES
The default build on many systems with IPv4 only. To build with IPv6,
add "IP=6" to the make command line, e.g.
make lnp IP=6
The default build is to build with SSL and disabling plaintext passwords
unless SSL/TLS encryption is in effect (SSLTYPE=nopwd). This means that
OpenSSL MUST be installed before building the IMAP toolkit. Please refer to
the SSLBUILD file for more information.
To build without SSL, add "SSLTYPE=none" to the make command line.
Note that doing so will produce an IMAP server which is NON-COMPLIANT with
RFC 3501.
You must build through the top-level imap-2007/Makefile, which will run
a "process" step the first time and create the imap-2007/c-client,
imap-2007/ipopd, and imap-2007/imapd directories in which building actually
takes place.
Before doing a make on UNIX, you should read imap-2007/Makefile and see
if your system type is known. The various system types are three-letter codes.
If your system type is known, then use this as the make option. After the
first time you do a make, this option is remembered in a file called OSTYPE,
so just typing "make" suffices.
For example, if you are using a more or less modern Linux system, your
system type is probably one of the specific distribution types (such as lrh for
RedHat). For more generic builds, try slx (shadow passwords only) or lnp (PAM).
To build for RedHat, do:
make lrh
There are other make options, described in imap-2007/src/osdep/Makefile.
It's probably best to see if an existing port will work on your system
before inventing a new port. Try:
sv4 generic SVR4, non-ANSI compiler
a32 modern SVR4
bsd basic 4.3 BSD, non-ANSI compiler
bsf modern BSD
If you must invent a new port, you need to create an entry in
imap-2007/Makefile and imap-2007/src/osdep/Makefile for your new port, as
well as osdep/os_???.h and osdep/os_???.c files with the appropriate
OS-dependent support for that system. You also need to determine which setup
process to use. You should use the ua process unless you are sure that your
compiler supports *ALL* aspects of ANSI C prototyping. Note that some
compilers, such as Ultrix, support some aspects of ANSI C but not others;
c-client really beats on the full prototyping capability of ANSI C so you
have to use the non-ANSI source tree for such systems.
If you send a new port back to us, we will make it available for others
who use your particular system type.
The mbox driver is now enabled by default. If the file "mbox" exists on
the user's home directory and is in UNIX mailbox format, then when INBOX is
opened this file will be selected as INBOX instead of the mail spool file.
Messages will be automatically transferred from the mail spool file into the
mbox file. To disable this behavior, delete "mbox" from the EXTRADRIVERS list
in the top-level Makefile and rebuild.
WARNING: The SVR2 (sv2) port is *incomplete*. SVR2 does not appear to
have any way to do ftruncate(), which is needed by the mbox, mbx, mmdf, mtx,
tenex, and unix drivers.
UNIX INSTALLATION NOTES
Binaries from the build are:
imap-2007/mtest/mtest c-client testbed program
imap-2007/ipopd/ipop2d POP2 daemon
imap-2007/ipopd/ipop3d POP3 daemon
imap-2007/imapd/imapd IMAP4rev1 daemon
mtest is normally not used except by c-client developers.
STEP 1: [x]inetd setup
The ipop2d, ipop3d, and imapd daemons should be installed in a system
daemon directory and invoked by a listener such as xinetd or inetd. In the
following examples, /usr/local/etc is used).
STEP 1(A): xinetd-specific setup
If your system uses xinetd, the daemons are invoked by files in your
/etc/xinetd.d directory with names corresponding to the service names (that
is: imap, pop2, pop3). You will need to consult your local xinetd
documentation to see what should go into these files. Here is a a sample
/etc/xinetd.d/imap file:
service imap
{
disable = no
socket_type = stream
wait = no
user = root
server = /usr/local/etc/imapd
groups = yes
flags = REUSE IPv6
}
STEP 1(B): inetd-specific setup
If your system still uses inetd, the daemons are invoked by your
/etc/inetd.conf file with lines such as:
pop stream tcp nowait root /usr/local/etc/ipop2d ipop2d
pop3 stream tcp nowait root /usr/local/etc/ipop3d ipop3d
imap stream tcp nowait root /usr/local/etc/imapd imapd
Note that different variants of UNIX have different versions of inetd,
so you should verify the precise form of these commands (for example, some
versions of inetd do not require the "nowait").
IMPORTANT NOTE: inetd has a limit of how many new connections it will
allow in a certain interval, and when this limit is exceeded, it shuts down
the server. If you have anything beyond a small-scale server, you are
probably going to run up against this limit. You'll know when it happens;
your syslog will give the misleading message "imap/tcp server failing
(looping), service terminated" and users will complain that IMAP service is
unavailable for the next 10 minutes. Similarly with "pop3/tcp server
failing"...
It must be emphasized that this is *NOT* a bug in the IMAP or POP
servers, nor is it anything that I can "fix". It is an inetd problem, and
the only way to fix it is to change inetd's behavior.
By default, the parameters of this limit are (from inetd.c source code):
#define TOOMANY 40 /* don't start more than TOOMANY */
#define CNT_INTVL 60 /* servers in CNT_INTVL sec. */
#define RETRYTIME (60*10) /* retry after bind or server fail */
That is, no more than 40 connections (TOOMANY) in 60 seconds (CNT_INTL), and
if exceeded, shut down the server for 10 minutes (RETRYTIME). This was a
good setting in the 1980s ARPAnet, but is much too small today.
Some versions of inetd allow you to see a higher maximum in the
/etc/inetd.conf file. Read "man inetd" and see if you see something like
this in the text:
The wait/nowait entry is applicable to datagram sockets only [...]
[...] The optional ``max'' suffix (separated from
``wait'' or ``nowait'' by a dot) specifies the maximum number of server
instances that may be spawned from inetd within an interval of 60 sec-
onds. When omitted, ``max'' defaults to 40.
If you see this, then edit the /etc/inetd.conf entry for imapd to be
something like:
imap stream tcp nowait.100 root /usr/local/etc/imapd imapd
(or, if you use TCP wrappers)
imap stream tcp nowait.100 root /usr/local/etc/tcpd imapd
Otherwise, you'll need to edit the inetd source code to set TOOMANY to a
higher value, then rebuild inetd.
STEP 2: services setup
You may also have to edit your /etc/services (or Yellow Pages,
NetInfo, etc. equivalent) to register these services, such as:
pop 109/tcp
pop3 110/tcp
imap 143/tcp
STEP 3: PAM setup
If your system has PAM (Pluggable Authentication Modules -- most
modern systems do) then you need to set up PAM authenticators for imap and
pop. The correct file names are
/etc/pam.d/imap
and
/etc/pam.d/pop
It probably works to copy your /etc/pam.d/ftpd file to the above two
names.
Many people get these file names wrong, and then spend a lot of time
trying to figure out why it doesn't work. Common mistakes are:
/etc/pam.d/imapd
/etc/pam.d/imap4
/etc/pam.d/imap4rev1
/etc/pam.d/ipop3d
/etc/pam.d/pop3d
/etc/pam.d/popd
/etc/pam.d/pop3
STEP 4: optional rimap setup
If you want to enable the rimap capability, which allows users with a
suitable client and .rhosts file on the server to access IMAP services
without transmitting her password in the clear over the network, you need
to have /etc/rimapd as a link to the real copy of imapd. Assuming you have
imapd installed on /usr/local/etc as above:
% ln -s /usr/local/etc/imapd /etc/rimapd
Technical note: rimap works by having the client routine tcp_aopen()
invoke `rsh _host_ exec /etc/rimapd' in an child process, and then returning
pipes to that process' standard I/O instead of a TCP socket. You can set up
`e-mail only accounts' by making the shell be something which accepts only
that string and not ordinary UNIX shell commands.
STEP 4: notes on privileges
Neither user "root", not any other UID 0 account, can log in via IMAP or
POP. "That's not a bug, it's a feature!"
This software is designed to run without privileges. The mail spool
directory must be protected 1777; that is, with world write and the sticky
bit. Of course, mail *files* should be protected 600!
An alternative to having the mail spool directory protected 1777, at the
cost of some performance, is to use the external "mlock" program, available
as part of the imap-utils package. With mlock installed as /etc/mlock and
setgid mail, the spool directory can be protected 775 with group mail.
Please disregard this paragraph if you don't understand it COMPLETELY, and
know EXACTLY what to do without question.
STEP 5: SVR4 specific setup
There is one "gotcha" on System V Release 4 based systems such as
Solaris. These systems do not use the standard UNIX mail format, but rather a
variant of that format that depends upon a bogus "Content-Length:" message
header. This is widely recognized to have been a terrible mistake. One
symptom of the problem is that under certain circumstances, a message may get
broken up into several messages. I'm also aware of security bugs caused by
programs that foolishly trust "Content-Length:" headers with evil values.
To fix your system, edit your sendmail.cf to change the Mlocal line to
have the -E flag. A typical entry will lool like:
Mlocal, P=/usr/lib/mail.local, F=flsSDFMmnPE, S=10, R=20, A=mail.local -d $u
WIN32 BUILD NOTES
Visual C++ 6.0 along with the current Microsoft Platform SDK
(specifically the CORE SDK and the Internet Development SDK) is required
to build on Windows 9x/Me/NT/2K/XP. If you do not have the Platform SDK
installed or in your path properly, you'll get errors when building os_nt.c,
typically in env_nt.c, ssl_nt.c, ssl_w2k.c, or gss_shim.c. You can download
the Microsoft Platform SDK from Microsoft's web site.
There is also considerable debate about how new mail is to be snarfed.
I am currently using something that seems to work with WinSMTP. Look at
the definition of MAILFILE in imap-2007/src/osdep/nt/mailfile.h and at the
sysinbox() function in imap-2007/src/osdep/nt/env_nt.c to see what's there
now, so you have a clue about how to hack it.
To build under Windows 95/98/NT, connect to the imap-2007 directory
and do:
nmake -f makefile.nt
The resulting binaries will support SSL if either schannel.dll or
security.dll is installed in Windows, using the old, undocumented, SSL
interfaces. You can also use this to build under Me/2000/XP, but it is
not the preferred build on this platform.
To build with MIT Kerberos support, connect to the imap-2007 directory
and do:
nmake -f makefile.ntk
The resulting binaries will support SSL if either schannel.dll or
security.dll is installed in Windows, using the old, undocumented SSL
interfaces. They will also support MIT Kerberos. Note, however, that
these binaries will only run on systems which have the MIT Kerberos DLLs
installed, and will not run otherwise.
To build under Windows Me/2000/XP, connect to the imap-2007 directory
and do:
nmake -f makefile.w2k
The resulting binaries will support SSL and Microsoft Kerberos, using the
official, documented, Microsoft interfaces. Note, however, that these
binaries will not run under Windows 95, Windows 98, or Windows NT4.
WIN32 INSTALLATION NOTES
The resulting binaries will be:
imap-2007\mtest\mtest.exe (testbed client)
imap-2007\ipopd\ipop2d.exe POP2 server
imap-2007\ipopd\ipop3d.exe POP3 server
imap-2007\imapd\imapd.exe IMAP4rev1 server
These servers are stdio servers. I wrote a simple network listener
for NT called inetlisn; currently it is available as:
ftp://ftp.cac.washington.edu/mail/nt/inetlisn.tar
To build this, use "nmake" after connecting to the inetlisn directory.
inetlisn takes two arguments, the first being the port number and the second
being the binary to run to serve a connection on that port, e.g.
c:\bin\inetlisn 143 c:\mail_daemons\imapd
Note that NT imapd must be started as SYSTEM in order to be recognized as
being "not logged in"; otherwise it will preauth as whatever user it is
running as which is probably not what you want. One way to have it run as
system is to have inetlisn run by an AT command, e.g. if the time now is
2:05PM, try something like:
AT 14:06 "c:\bin\inetlisn 143 c:\mail_daemons\imapd"
A more advanced network listener called wsinetd is available on:
http://wsinetd.sourceforge.net
It is based on inetlisn, and essentially is a "completed" version of inetlisn.
Bottom line: this is not plug-and-play. If you're not a hacker and/or
are unwilling to invest the time to do some programming, you probably want to
buy a commercial server product.
INACTIVE PORTS
The TOPS-20 and VMS ports were developed at one time or another, but are
no longer actively developed. However, from time to time I test build both
of these to make sure that they compile without errors and that mtest runs,
and will continue doing so as long as I have access to systems running these
operating systems.
TOPS-20 BUILD NOTES
I have provided a c-client port for TOPS-20 systems, but you're on your
own in terms of a nice TOPS-20 like main program. Maybe someday some nice
person will try porting Pine to TOPS-20. This assumes the use of KCC 6, and
probably will not build with other compilers or older versions of KCC.
You do not use imap-2007/Makefile under TOPS-20, nor do you build any
components other than c-client and mtest. Merge the contents of
imap-2007/src/c-client, imap-2007/src/charset, imap-2007/src/mtest, and
imap-2007/src/osdep/tops-20 onto a single directory on TOPS-20 and build from
that. The command:
DO BUILD.CTL
will build the sources. If you don't have MIC, then SUBMIT BUILD.CTL and let
BATCON execute it.
VMS BUILD NOTES
The VMS port has been tested with imap-2007, but as I am soon going
to lose access to a VMS system I will no longer be able able to test and
this port will be moved to the "other ports" category".
You do not use imap-2007/Makefile under VMS, nor do you build any
components other than c-client and mtest. Merge the contents of
imap-2007/src/c-client, imap-2007/src/charset, imap-2007/src/mtest, and
imap-2007/src/osdep/vms onto a single directory on VMS and build from that.
The command to build it is:
@BUILD MULTINET
or @BUILD NETLIB
If you just do @BUILD it will build with dummy TCP code, and since only TCP
based drivers are provided here this isn't too useful.
If you aren't on the Pacific coast of the US or Canada, you probably will
need to change the wired-in timezone in the BUILD.COM file. Apparently, the
wonderful VMS system that DEC loves so much doesn't maintain any concept of
time zone; the VMS C compiler returns a null pointer from gmtime()!
Otherwise you're pretty much on your own here.
OTHER PORTS
The following ports were developed at one time or another, but are no
longer actively developed or tested. It is not known if they still work or
not.
Port Status
---- ------
Macintosh Obsolete; Mac OS X uses UNIX port
DOS/Win16 Obsolete; modern PCs use Win32 port
Windows CE Never completed
Amiga Unknown
OS/2 Unknown
MACINTOSH BUILD NOTES
This port is for the old Mac OS system, not Mac OS X.
If you are building a Macintosh client, you will need MacTCP installed on
your system as well as the MacTCP C includes and libraries.
You do not use imap-2007/Makefile on the Mac, nor do you build any
components other than c-client and mtest. Merge the contents of
imap-2007/src/c-client, imap-2007/src/charset, imap-2007/src/mtest, and
imap-2007/src/osdep/mac onto a single directory on the Mac and build from
that. mtext.sit.hqx is a THINK C project file and cute icon for building
mtest, encoded with Binhex and StuffIt.
THINK C is a truly wretched product which help make me understand why
Macintosh has lost most of its market share. Not only does it do cretinous
things such as barf about a cast in front of an lvalue, it also limits the size
of code *or* data in a single file to 32K! So much for having large character
set tables. Symantec says that "MacOS requires it, break up your files into
smaller pieces" yet somehow gcc under MachTen contrives to compile C programs
without subjecting the programmer to this idiocy.
As a result of this, I found myself obliged to comment out the #includes
of the East Asian character sets in utf8.c in order to get it to build. It's
also necessary to break up some of the files, at least mail.c and imap4r1.c.
Maybe you don't have to do this in CodeWarrior or whatever the new compiler is
called, but I've pretty much given up on Macintosh.
If you use precompiled headers, you may get some compilation errors since
some Apple symbols need to be redefined in order to get it to build under all
versions of MacOS. Try turning off the precompiled headers (so it will
re-read the .h files) and see if it builds any better.
If you use a Mac C compiler with 2-byte ints (such as THINK C's normal
mode) you will need to fix some bugs in the MacTCP C includes and libraries to
prevent it from generating bad code, since those MacTCP files violate Apple's
standards of always using explicit shorts or longs, never ints. You could
avoid this if you set 4-byte ints in THINK C; however, the ANSI and UNIX
libraries in THINK C use 2-byte ints so you will also need to build 4-byte int
versions of these. c-client itself is 2-byte int or 4-byte int clean; it can
be used in either mode.
The most important bug in the MacTCP files that you need to fix is in the
file AddressXlation.h, you need to change the definition of the rtnCode member
of the hostInfo structure to be long instead of int. There are several other
changes you need to make if you decide to compile dnr.c under THINK C instead
of using the Apple-supplied object file; see me for details if you decide to
undertake such an effort. This is fixed in newer versions from Apple.
DOS/WIN16 BUILD NOTES
If you are building a DOS client, you will need a TCP/IP stack installed
on your DOS system along with its development environment. The currently
supported stacks are Beame & Whiteside, PC-NFS, Novell, PC/IP, Waterloo, and
Winsock. mtest and a version of Pine called PC Pine run under DOS.
You do not use imap-2007/Makefile under DOS, nor do you build any
components other than c-client and mtest. Merge the contents of
imap-2007/src/c-client, imap-2007/src/charset, imap-2007/src/mtest, and
imap-2007/src/osdep/dos onto a single directory on DOS and build from that.
The MAKE command on DOS takes an argument identifying the TCP/IP stack in use.
For example, do:
MAKE MAKEFILE OS=WSK (or MAKE -F MAKEFILE OS=WSK)
to build for Winsock.
If you write a program for DOS/Win16, you will probably have to write a
replacement cache manager (look at mm_cache()) and otherwise disable most of
c-client's caching. Even so, memory limitations will be an ongoing problem,
particularly with DOS, and you will have some severe performance problems.
It's a bit better on Win16, but in my opinion you are better off writing a
32-bit program and telling your Win16 customers to upgrade to Windows 95 or at
least install Win32s.
WINDOWS CE BUILD NOTES
I build using Visual C++ 6.0 with the WCE extensions. The current code
has SH3 wired in for the compiler building.
To build under NT, connect to the imap-2007 directory and do:
nmake -f makefile.wce
The only binary produced is a cclient.lib file. I haven't gotten as far
as building mtest on WCE, mainly because I don't have a stdlib library.
AMIGA BUILD AND INSTALLATION NOTES
The Amiga port was contributed. Maybe the UNIX notes will help.
OS2 BUILD NOTES
The OS2 port was contributed. Maybe the Win32 Build Notes will help.

181
docs/CONFIG Normal file
View File

@ -0,0 +1,181 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
UNIX Configuration Notes
The IMAP and POP3 servers are plug-and-play on standard UNIX
systems. There is no special configuration needed. Please ignore all
rumors to the effect that you need to create an IMAP configuration
file.
If your system is non-standard, virtually everything that you are
likely to want to modify can be found in the source file
.../src/osdep/unix/env_unix.c
In particular, special attention should be given to the routines:
env_init() initialize c-client environment variables,
especially the user name and home directory
sysinbox() return the UNIX path of the INBOX in which
mail delivery will place mail
mailboxdir() translate a mailbox name into the associated
UNIX directory for listing
mailboxfile() translate a mailbox name into the associated
UNIX file for opening
There are also build options in the top-level makefile which you
can give on the command line when building the software. The most
common build options are "SSLTYPE=unix", to build the software with SSL,
and "SSLTYPE=nopwd", to build the software with SSL and disable plaintext
authentication unless the session is encrypted.
You should modify these routines as necessary for local policy.
The most common modifications are to env_init(), to modify the
software's idea of the home directory (which is used everywhere as the
default directory), and to sysinbox(), to modify where the software
looks for newly-delivered mail.
Example 1: suppose your mailer delivers mail to file ".mailbox"
in the user's home directory instead of the default UNIX mail spool
directory. You will want to change routine sysinbox(), changing the
line that reads:
sprintf (tmp,"%s/%s",MAILSPOOL,myusername ());
to be:
sprintf (tmp,"%s/.mailbox",myhomedir ());
Example 2: suppose you want to change c-client's idea of the
user's mailbox directory to be the "mail" subdirectory of the user's
home directory instead of the user's home directory. You will want to
change variable mailsubdir, changing the line that reads:
static char *mailsubdir = NIL; /* mail subdirectory name */
to be:
static char *mailsubdir = "mail";/* mail subdirectory name */
Example 3: suppose you want to disable plaintext authentication in
the IMAP and POP servers. If you want to disable plaintext authentication
in unencrypted sessions but permit it in encrypted sessions, you should use
"SSLTYPE=nopwd" in the make command line when building the software. For
example, to do this on a Linux system with PAM authentication, do:
make lnp SSLTYPE=nopwd
If you want to disable plaintext authentication under all circumstances
(including SSL or TLS encrypted sessions), use "PASSWDTYPE=nul", e.g.:
make lnx EXTRAAUTHENTICATORS=gss PASSWDTYPE=nul
which will make it impossible to log in except via Kerberos.
Example 4: suppose you want the IMAP and POP servers to do a chroot()
to the user's home directory. This is not recommended; there are known
ways of attacking chroot() based security mechanisms. Furthermore, if you
do this you can not use a traditional UNIX format INBOX in the mail spool
directory, since chroot() will prevent access to that directory. If you
really want to do this, you need to change variable closedBox, changing
the line which reads:
static short closedBox = NIL; /* is a closed box */
to be:
static short closedBox = T; /* is a closed box */
Example 5: suppose you want to disable non-namespace access to the
filesystem root and other users' names, but do not want to go to the
extreme of chroot() and you want to allow access to a traditional UNIX
format INBOX in the mail spool directory. You need to change variable
restrictBox, changing the line which reads:
static short restrictBox = NIL; /* is a restricted box */
to be:
static short restrictBox = -1; /* is a restricted box */
Other values to set in restrictBox can be found in env_unix.h.
Ignore all references in env_unix.c to a configuration file; that
code is for UW-internal use only. It is extremely unlikely that that
facility will work usefully for you; it is extremely likely that you
will shoot yourself in the foot by using; and it frequently changes in
an incompatible manner.
There are two other build-time configuration issues which you may
need to consider: drivers and authenticators. Both of these are set
up in the top-level Makefile -- in particular, by the EXTRADRIVERS and
EXTRAAUTHENTICATORS variables.
Drivers are code modules that support different mailbox storage
technologies. By default, all drivers are enabled. There is little
benefit to be gained by disabling a driver, with one exception. The
mbox driver implements the behavior of automatically moving new mail
from the spool directory to the "mbox" file on the user's home
directory, if and *only* if the "mbox" exists and is in mailbox
format. The mbox driver is listed under EXTRADRIVERS; if you wish to
disable it just remove it from that list and rebuild.
Authenticators are code modules that support authentication
technology for the server (password file lookup, Kerberos, S/Key,
etc.). EXTRAAUTHENTICATORS is used to add an authenticator. This
subject can be complex; find a wizard if you can't figure it out.
It is also possible to add your own drivers and authenticators.
This is a topic for wizards, and is beyond the scope of this text.
NT Configuration Notes
This software is not plug-and-play on NT. If you're not a hacker
and/or are unwilling to invest the time to do some programming, you
probably want to buy a commercial server for NT.
The primary issue that you need to deal with is the format of
mail, where the INBOX is located, and where secondary folders are
located. As distributed, the software supports mail in the default
format used on UNIX (unix format) as well as mbx, mtx, and tenex
formats. mbx format is encouraged if at all possible; mtx and tenex
format are for compatibility with the past. However, it all depends
upon how and where your SMTP server delivers mail.
To change the default mailbox format, edit the symbol
DEFAULTDRIVER in:
../src/osdep/nt/makefile.nt
or
../src/osdep/nt/makefile.ntk
To change the default location of INBOX, edit the file:
../src/osdep/nt/mailfile.h
Virtually everything else having to do with environment that you are
likely to want to modify can be found in the source file:
.../src/osdep/nt/env_nt.c
In particular, special attention should be given to the routines:
env_init() initialize c-client environment variables,
especially the user name and home directory
sysinbox() return the NT path of the INBOX in which
mail delivery will place mail
mailboxdir() translate a mailbox name into the associated
NT directory for listing
mailboxfile() translate a mailbox name into the associated
NT file for opening
You should modify these routines as necessary. The most common
modifications are to env_init(), to modify the software's idea of the
home directory (which is used everywhere as the default directory),
and to sysinbox(), to modify where the software looks for
newly-delivered mail.
There are two other build-time configuration issues which you may
need to consider: drivers and authenticators. Both of these are set
up in the top-level Makefile -- in particular, by the EXTRADRIVERS and
EXTRAAUTHENTICATORS variables.
Drivers are code modules that support different mailbox storage
technologies. By default, all drivers are enabled. There is little
benefit to be gained by disabling a driver.
Authenticators are code modules that support authentication
technology for the server (password file lookup, Kerberos, S/Key,
etc.). EXTRAAUTHENTICATORS is used to add an authenticator. This
subject can be complex; find a wizard if you can't figure it out.
It is also possible to add your own drivers and authenticators.

4226
docs/FAQ.html Normal file
View File

File diff suppressed because it is too large Load Diff

2993
docs/FAQ.txt Normal file
View File

File diff suppressed because it is too large Load Diff

131
docs/IPv6.txt Normal file
View File

@ -0,0 +1,131 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
The following information about configuring inetd and xinetd for IPv6 was
contributed by a user. I have not checked it for accuracy or completeness,
but have included it as-is in the hope that it may be useful:
---------------------------------------------------------------------------
One thing you might consider adding to the docs are hints for setting up
inetd or xinetd to simultaneously listen on BOTH IPv4 and IPv6 for
different OS.
Some OS want to see separate IPv4-only and IPv6-only listening sockets
configured in inetd.conf or xinetd.conf. Others will accept IPv4
connections on lines configured for IPv6 and actually generate errors if
you have both configured when inetd or xinetd start up. It's not clear to
me whether this difference is due to how inetd or xinetd are built or
whether it's due to the kernel's IP stack implementation. I suspect it's
really the latter. Below are some examples:
Here's a fragment of /usr/local/etc/xinetd.conf for a FreeBSD 4.9 server:
service imap
{
socket_type = stream
protocol = tcp
wait = no
user = root
server = /usr/local/libexec/imapd
}
service imap
{
flags = IPv6
socket_type = stream
protocol = tcp
wait = no
user = root
server = /usr/local/libexec/imapd
}
service imaps
{
socket_type = stream
protocol = tcp
wait = no
user = root
server = /usr/local/libexec/imapd
}
service imaps
{
flags = IPv6
socket_type = stream
protocol = tcp
wait = no
user = root
server = /usr/local/libexec/imapd
}
Note that you have to specify a nearly identical paragraph for each
service which differs only by the 'flags = IPv6'. An equivalent
inetd.conf would look something like:
imap stream tcp nowait root /usr/local/libexec/imapd imapd
imap stream tcp6 nowait root /usr/local/libexec/imapd imapd
imaps stream tcp nowait root /usr/local/libexec/imapd imapd
imaps stream tcp6 nowait root /usr/local/libexec/imapd imapd
The man pages for inetd suggest that if you use a single entry with
'tcp46' replacing either 'tcp' or 'tcp6' the system will listen on both
types of addresses. At least for the case of FreeBSD this is actually
incorrect.
Now if you were to use the above xinetd.conf on Fedora Linux, it would
complain. What does work under Linux is to create a single service
paragraph for each service which will accept connections on both IPv4 and
IPv6:
In /etc/xinetd.d/imap:
service imap
{
flags = IPv6
disable = no
socket_type = stream
wait = no
user = root
server = /usr/local/sbin/imapd
}
In /etc/xinetd.d/imaps:
service imaps
{
flags = IPv6
disable = no
socket_type = stream
wait = no
user = root
server = /usr/local/sbin/imapd
}
The man page for xinetd says the IPv6 flag means xinetd will listen ONLY
on IPv6. However the actual behaviour (for Fedora Linux) is to listen on
both IPv4 and IPv6.
All of the above also applies to ipop3d. Anyway, this might save some
folks a little bit of head scratching time.
---------------------------------------------------------------------------
Addendum from the original submitter:
---------------------------------------------------------------------------
I've since learned that the discrepancy really is a function of the OS.
It seems those systems that force you to create separate IPv4 and IPv6
listeners in inetd (or xinetd) are the same systems that also disable
IPv4-mapped IPv6 addresses by default. This is a boot-time configuration
option. If you enable IPv4-mapped IPv6 addresses, then the 'tcp46' option
in inetd works and the simplified config would look like:
imap4 stream tcp46 nowait root /usr/local/libexec/imapd imapd
imaps stream tcp46 nowait root /usr/local/libexec/imapd imapd
In FreeBSD, enabling IPv4-mapped addresses is done by adding
ipv6_ipv4mapping="YES" to /etc/rc.conf (in addition to ipv6_enable="YES").

798
docs/RELNOTES Normal file
View File

@ -0,0 +1,798 @@
/* ========================================================================
* Copyright 1988-2008 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
Updated: 22 July 2011
imap-2007f fixes a couple bugs.
Fix for RFC 4959 Initial Client Response auth failures noted first by
MacOSX Lion Mail users.
Adjust tcp_open.c:tcp_socket_open to make it a little more useful by adding
a write file descriptor test to the select in the case that the open
timeout is set.
In osdep/unix/env_unix.c:create_path there was a printf that should have
been an sprintf. Doesn't matter on modern systems.
Updated: 16 December 2008
imap-2007e is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users
plus a security fix for users of the RFC822BUFFER routines.
Updated: 29 October 2008
imap-2007d is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users
plus a security fix for users of tmail or dmail.
Updated: 25 March 2008
imap-2007b is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.
Updated: 2 January 2008
imap-2007a is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.
Updated: 20 December 2007
imap-2007 is a release corresponding with the release of Alpine 1.0.
The primary focus of the imap-2007 release is bugfixes and reliability
improvements. This includes:
. fixes to problems discovered between the Alpine 0.99999 pre-release
and Alpine 1.0
. fixes to the mix driver to timing race problems uncovered by Timo
Sirainen's imaptest suite. imap-2007 using the mix format is
believed to pass imaptest completely.
A new function, utf8_csvalidmap(), has been added for the benefit of
Alpine to use in examining UTF-8 text and determining efficiently
whether it can be downgraded to a legacy charset. If you develop an
MUA, this may be useful for you too, although you'll have to read the
source code to see how to use it. The purpose of the "not-CJK" bit is
to prevent messages being downgraded to a CJK charset if all they have
in that charset are some special punctuation.
Updated: 5 September 2007
imap-2006k is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.
The primary focus of this maintenance release is to correct deadlock
issues. There were two major causes of the deadlocks:
. a change in imap-2006i attempted to resolve a glibc mutex-based
deadlock in imapd's signal handler, but ended up worsening the problem.
. a bug in the mbx driver, introduced as part of the UIDPLUS work in 2006,
applied an mbx-style lock briefly on a traditional UNIX format mailbox.
If the traditional UNIX format mailbox was already locked by some other
process, the result would be a deadlock of both processes.
imapd's signal handling logic is rewritten to avoid the mutex issue, and
the mbx driver is fixed so that mbx-style locks are only applied to mbx
format mailboxes.
imapd now supports the WITHIN extension.
Updated: 14 June 2007
imap-2006j is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.
Updated: 5 June 2007
imap-2006i is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.
imapd now supports the CHILDREN and ESEARCH extensions.
imapd's attempt to return COPYUID/APPENDUID information for a traditional
UNIX (and MMDF) format mailbox when the mailbox is open by another process
has been declared to be a failure and is now revoked. It was subject to a
timing race, loss of which involved an expensive reset of the mailbox's UID
regime. Any imapd COPY or APPEND to a traditional UNIX or MMDF format that
is open by some other process will now no longer return COPYUID/APPEND.
Although this is technically in violation of RFC 4315, there is a loophole
in that document and the timing race/performance problem is worse.
Updated: 4 April 2007
imap-2006h is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.
Updated: 30 March 2007
imap-2006g is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.
Updated: 30 January 2007
imap-2006f is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.
For the benefit of multi-threaded applications, use of strtok() has been
abolished in the c-client library. imapd and ipop3d stuff use it though.
The TOPS-20 and VAX/VMS ports still use strtok() since they don't use UNIX
threads.
This version has been test-built on Linux, Mac OS X, NeXT, Windows XP,
TOPS-20, and VAX/VMS. This will probably be the last test-build on VAX/VMS
since the system I use for that purpose is being shut down. I have no way
to test-build on DOS, legacy Mac OS (OS 9 and earlier), OS/2, or Windows CE;
and the builds on those systems are probably broken.
Updated: 26 January 2007
imap-2006e is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.
Updated: 6 December 2006
imap-2006d is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.
The decomposition mapping, title-case mapping, and character widths tables
have been updated to comply with the Unicode 5.0 standard.
Prototypes for the utf8aux.c functions have been moved to a new utf8aux.h.
The general c-client modules now include c-client.h instead of the individual
files. Use of c-client.h instead of individual include files insulates
against future shuffling of include files.
Updated: 23 October 2006
imap-2006c is a maintenance release, consisting primarily of bugfixes to
problems discovered in the release that affected a small number of users.
By popular request, if a user has a mix (or other dual-use) format INBOX,
it will no longer be listed as \NoInferiors. It's a bad idea to depend
upon this due to the case ambiguity issue, but it's there.
Updated: 26 September 2006
imap-2006b is a maintenance release, consisting entirely of bugfixes to
problems discovered in the release that affected a small number of users.
Updated: 15 September 2006
imap-2006a is a maintenance release, consisting entirely of bugfixes to
problems discovered in the release that affected a small number of users.
If it is necessary to build IPv4-only on one of the ports that has IPv6
preconfigured (ldb, lfd, lmd, lrh, lsu, osx, oxp), this can be done by
using IP6=4. You can't do IP=4 in the build command directly since these
ports set IP themselves; however, now instead of setting IP=6 they now set
IP=$(IP6).
Updated: 30 August 2006
imap-2006 is a major release. Programs written for imap-2004g should
build with this version with minor or no modification. imap-2005 was not
released except as development snapshots.
imap-2006 contains major extensions to its Unicode support. Searching and
sorting are now done with strings canonicalized to titlecase and decomposed
form. Among other things, this means that Latin letters with diacriticals
will now sort with the basic Latin letter, and case-independent searching of
such letters (e.g., German umlauts) now works. Previously, sorting was done
strictly by Unicode codepoint, and case-independence only worked with ASCII.
imapd now supports the UIDPLUS extension for mailboxes in unix, mmdf, mbx, mx,
and mix formats. UID EXPUNGE is fully implemented. Note that UIDPLUS is not
supported in the little-used drivers (mh, mtx, tenex) in which meaningful
APPENDUID/COPYUID data can not be returned. Refer to bugs.txt for more
details.
The new mix format is a dual-use mailbox format designed for performance and
reliability with large mailboxes. mix is documented in file mixfmt.txt.
SSL/TLS certificate validation on UNIX now checks the alternative names in the
certificate if the CN does not match.
The new /tls-sslv23 flag in a mailbox name causes a TLS session to use the
(incorrect) SSLv23 client method instead of the TLSv1 client method. Some
broken servers use the SSLv23 server method, and this flag works around that
problem. WARNING: use of this flag will cause TLS negotiation to fail with
a server which uses the proper TLSv1 server method. Additionally, there are
known security risks in SSLv2; so users should be suspicious if this switch
suddenly becomes necesary.
The silly mailbox flag combination /ssl/tls is now rejected as an invalid
remote specification. Previous versions tried to negotiate TLS over an SSL
session; even if the server permitted such a thing it couldn't work.
The memory management of several drivers has been redesigned to consume less
memory and hopefully be faster.
The private.data member of the MESSAGECACHE (elt) has been replaced with
a union that contains private.spare.data and private.spare.ptr, the latter
being a pointer.
A new FT_RETURNSTRINGSTRUCT flag has been added for mail_fetch_body() and
mail_fetch_text() calls. If this flag is set, *and* if the function returns
NIL, then the requested string data is available on a stringstruct on
stream->private.string. This is a special hack for the IMAP and POP servers
and is subject to incompatible change. The result is a major performance
improvement in the servers with the mbx driver, particularly with large
messages.
Updated: 15 September 2005
imap-2004g is a maintenance release, and consists solely of a bugfix to
quoted string handling in the mailbox name parsing routine.
Updated: 15 August 2005
imap-2004f is a maintenance release, and consists solely of a bugfix to
the TCP code.
Also included is a new version of the UNIX SSL/TLS routines that allows the
SSL/TLS certificate validation client code to validate alternative names in
server certificates. This code has not been thoroughly regression-tested but
is believed to work. To use this new code instead of the old support:
cd imap-2004f/src/osdep/unix
mv ssl_unix.c ssl_unix.old
mv ssl_unix.new ssl_unix.c
Then rebuild.
Updated: 21 June 2005
imap-2004e is a maintenance release, consisting entirely of bugfixes.
There are no user-visible functional enhancements in this version.
Updated: 20 April 2005
imap-2004d is a maintenance release, released concurrently with Pine
4.63, and consists primarily of bugfixes
There is now a workaround for RedHat breaking flock(). However, since
RedHat has said that they don't support flock(), there is no guarantee
that they won't break it in the future. So you may want to consider some
other Linux distribution or BSD instead. See:
https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=123415
for the gruesome details.
There are no user-visible functional enhancements in this version.
Updated: 18 January 2005
imap-2004c is a maintenance release, released concurrently with Pine
4.62, including fixes to quoted-printable encoding and CRAM-MD5
authentication.
NNTP proxy in imapd now supports the LIST and LSUB commands.
There are no other user-visible functional enhancements in this version.
Updated: 29 November 2004
imap-2004b is a maintenance release, consisting primarily of bugfixes.
Programs written for imap-2004a will build with this version without
modifification.
There are new ports for Solaris with Blastwave Community Open Source
Software (gcs) and Mandrake Linux (lmd).
SET_SNARFINTERVAL now controls how frequently local drivers will move new
mail from the mail spool as well as from a maildrop. Maildrops are still
tied to a minimum interval of 1 minute, but there is now no minimum for the
spool file.
Character set conversions now map non-breaking space to space if the
destination character set doesn't have nbsp. JIS Roman yen sign is now
mapped to Unicode yen sign.
There are no user-visible functional enhancements in this version.
Updated: 8 July 2004
imap-2004a is a maintenance release, consisting primarily of critical
bugfixes. Programs written for imap-2004 will build with this version
without modification.
imapd now has a supported NNTP proxy capability. If the file /etc/imapd.nntp
exists, the contents of that file are used as the host name of an NNTP
server which will be used whenever a #news. name is used. For example, if
/etc/imapd.nntp contains nntp.example.com, and the IMAP client SELECTs or
EXAMINEs the name #news.comp.mail.imap, what will actually be opened in
imapd is {nntp.example.com/nntp}comp.mail.imap
The OSF/1 port (Digital UNIX, Tru64) now uses flocksim instead of flcksafe.
Some cretin decided to delete the winning flock() call and make flock() use
the losing fcntl() call instead.
The unix[nt] and mmdf drivers now prevent mail_append() from writing Status:,
X-Status:, X-UID, X-IMAP[base]:, and X-Keywords: header lines to a
traditional UNIX or MMDF format mailbox. If any such lines are in the
text supplied to mail_append(), they will be quoted by prefixing with
"X-Original-" (e.g. Status: will become X-Original-Status:).
There are no user-visible functional enhancements in this version.
Updated: 10 May 2004
imap-2004 is a major release. Programs written for imap-2002e should
build with this version with minor modification. imap-2003 was not
released except as development snapshots.
mailutil has three new commands: delete, rename, and prune.
IPv6 support now exists for UNIX and W2K. It is the default in W2K builds.
On UNIX, add "IP=6" to the make command line. Windows IPv6 support is
only for W2K builds.
The NNTP driver now supports NNTP SASL and TLS.
The ldb (Debian) and lrh (RedHat) ports now look for mlock on
/usr/sbin/mlock instead of /etc/mlock.
imapd now supports the LITERAL+ and SASL-IR initial-response extensions.
The IMAP driver has some additional checks to reduce the amount of network
traffic, including executing "silly searches" (searches of sequence numbers
only) locally.
The IMAP, POP, SMTP, and NNTP drivers now have diagnostic code to provide
better information about servers which violate SASL's empty challenge
requirements (e.g. with the PLAIN mechanism).
There is a new mail_fetch_overview_sequence() function which is like
mail_fetch_overview() but takes a sequence number string as an argument.
There should have been a flags argument and FT_UID bit as in all the other
mail_fetch_???() functions but compatibility with the past... :-(
The overview_t callback (from mail_fetch_overview()) now has a fourth
argument which contains the message sequence number (as opposed to the UID
which is in the second argument). It turned out that some applications were
calling mail_msgno() (which can be moderately expensive) to get the sequence
number, and c-client already knew it.
Many declarations which are completely internal to a driver have been removed
from the driver .h file, and in those cases where there are no external
declarations left the .h file has been eliminated entirely. As part of this,
the mbox driver routines are now incorporated with the unix driver routines
as opposed to being a separate file. The mbox driver still needs to be lunk
in order to get the mbox functionality.
Updated: 27 August 2003
imap-2002e is a minor release, released concurrently with Pine 4.58, and
contains primarily bugfixes. Programs written for imap-2002d will build
with this version without modification.
The NNTP client code now tries to perform better with legacy NNTP servers
which do not comply with the current NNTP protocol specification draft, most
notably Netscape Collabra.
Delivery notifications now work reliably with SMTP servers that support it.
The following changes are primarily of concern to developers and power users:
There is a "limited advertise" option in env_unix.c which, if set, will only
advertise the user's own namespace and the #shared/ namespace.
It is now possible to build the IMAP toolkit with a separate SSL KEY file
from the certificate file (SSLKEYS vs. SSLCERTS).
A new BODY structure element, sparep, is available for the main program to
use as a pointer for its own purposes; as well as a SET_FREEBODYSPAREP
function, similar to SET_FREEENVELOPESPAREP, SET_FREEELTSPAREP, etc.
Updated: 28 May 2003
imap-2002d is a minor release, released concurrently with Pine 4.56, and
contains primarily bugfixes. Programs written for imap-2002 should build
with this version without modification, with one exception. That exception
is the ngbogus envelope flag, which stopped being used in imap-2002c and is
now gone for good.
The NNTP newsgroup listing code now tries to use wildmats on the NNTP server,
which should result in better performance especially on slow lines. It is
also once again permitted to log in on NNTP servers when /loser is set.
imapd now supports the UNSELECT command.
A new envelope flag, imapenvonly, indicates that the envelope in a
MESSAGE/RFC822 BODY structure only has the IMAP envelope components and
not the additional components from c-client: Newsgroups, Followup-To,
and References.
Updated: 7 April 2003
imap-2002c is a minor release, released concurrently with Pine 4.55, and
contains primarily bugfixes. Programs written for imap-2002 will build
with this version without modification.
The POP3 driver will, with new servers that support CAPA, use the LIST
command to get the elt->rfc822_size and the TOP command to get the message
header, instead of fetching the entire message. Note that it is a bad idea
to do this with old servers, since they may misimplement LIST and TOP. The
result is a substantial performance improvement.
Subject extraction for comparisons in SORT and THREAD are now done in full
compliance with the rules laid out in the specification. This only makes
a difference if "re:" was part of a MIME quoted-word.
The new experimental #move namespace allows download-and-delete from a source
mailbox to a destination mailbox. Immediately following #move is a delimiter
character which must not appear in the source mailbox name, then the source
mailbox name, then the delimiter again, then the destination mailbox name.
For example:
#move+{pop3.foo.com/pop3}+INBOX
will download messages from "pop3.foo.com" into your local INBOX.
The NNTP driver now uses the LIST EXTENSIONS command as described in the
current NNTP protocol specification draft, and will prefer to use OVER over
XOVER, HDR over XHDR, etc.
The SET_NNTPRANGE function of mail_parameters() can be used to limit the
number of articles recognized by the NNTP driver, resulting in a substantial
performance improvement with NNTP servers that may have hundreds of thousands
of old articles in the spool. If set non-zero, then only the last n article
numbers will be considered. If you are on a slow link, you may want to set
this to 1000 or less.
Besides the normally tested UNIX and 32-bit Microsoft platforms, this release
has also been tested and will once build under TOPS-20 and VAX/VMS. I also
fixed a bug which would keep it from building on 16-bit DOS, but I don't know
if it will build on that platform or not since I no longer have a system with
the old DOS C compiler. It has not been tested on Macintosh (note however
that Mac OS X is a type of UNIX and should build), Amiga, or OS/2, and probably
no longer builds on those platforms.
Updated: 7 January 2003
imap-2002b is a maintenace release, released concurrently with Pine 4.52,
and contains only bugfixes. Programs written for imap-2002 will build with
this version without modification.
Drivers which do not announce new mail are now indicated by the DR_NONEWMAIL
driver flag. Driver which do not announce new mail when read-only are now
indicated by the DR_NONEWMAILRONLY flag.
There are no user-visible functional enhancements in this version.
Updated: 10 December 2002
imap-2002a is a maintenance release, consisting entirely of critical
bugfixes. Programs written for imap-2002 will build with this version
without modification.
There are no functional enhancements in this version.
Updated: 28 October 2002
imap-2002 is a major release. Programs written for imap-2001 will probably
build with this version without modification, with one exception. That
exception is if the program uses [GS]ET_DISABLEAUTOMATICSHAREDNAMESPACES,
which has been renamed to [GS]ET_DISABLEAUTOSHAREDNS in order to placate
some compilers which don't like very long names.
SSLTYPE=nopwd is now the default, in accordance with current IESG security
requirements. In order to build the IMAP toolkit without SSL/TLS you must
now use SSLTYPE=none. At initial build time, you will be told if the SSLTYPE
setting is in compliance with IESG security requirements, and if it is not
you will be asked to confirm to continue the build.
ORDEREDSUBJECT threading has been changed in accordance with draft 12 of the
IMAP threading specification. Previously, each non-root message in an
ORDEREDSUBJECT thread has been a child of the message immediately preceeding
it in the thread. Draft 12 changes this so that the second message in the
thread is the child of the first (root) message, and all subsequent messages
are siblings of the first message. This is significant in MUAs which display
the thread structure graphically; the new definition is much saner than the
old one since it does not nest endlessly due to parent/child relationships
that may not exist. This also impacts imapd, since imapd's THREAD command
will return a thread structure.
RFC 1730 server support, which was disabled in imap-2001, is now fully
removed from imapd. imapd still supports IMAP2bis, specifically the FIND
command, since there are still a few IMAP2 clients out there.
The IMAP client routines in the c-client library continue to support recognize
RFC 1730 servers, but do not implement the deprecated features of RFC 1730.
The Frequently Asked Questions file is now in HTML format, although a text
version (generated from the HTML version with Lynx) is also provided.
A new program, mailutil, is now bundled with the IMAP toolkit. mailutil
replaces the old chkmail, imapcopy, imapmove, imapxfer, mbxcopy, mbxcreat,
and mbxcvt programs that were distributed in the imap-utils. In addition,
the tmail, dmail, and mlock programs from the imap-utils are now also
bundled with the IMAP toolkit.
In addition to the usual bugfixes, the following c-client functionalities
are new in imap-2002:
The SET_DISABLE822TZTEXT parameter allows a client to suppress generation of
the "human friendly" time zone text in RFC822 dates. This placates netnews
and some broken SMTP servers which think that long timezone names from Windows
are an attempt at a buffer overflow attack.
The restrictBox option in env_unix.c sets "restricted box" functionality,
which disables access to the root (leading "/"), access to other user's
directories (leading "~"), and access to superior directories via "..".
Content-Location is now supported by the "location" member of the BODY
structure. Note that there is a bug in the IMAP client code in older
versions of the c-client library that causes it to handle BODYSTRUCTURE
extension data improperly if that data is a literal. The new functionality
for Content-Location may trigger this bug. The fix is either to upgrade
the IMAP client program to the imap-2002 version of c-client or to remove
the Content-Location support from imapd.
There are now 8 spare bits for application use in both the elts and the
mail streams.
mail_search() now returns a value (previously it was void). If mail_search()
returns NIL, then the supplied charset was invalid or the IMAP server
returned NO (probably because the supplied charset was invalid).
New utf8_charset() routine to look up a charset and return c-client's
database about that charset if found. Among other things, this will give
you the scripts supported by that charset and its Unicode conversion table.
New FT_NOLOOKAHEAD flag for mail_fetch_structure() disables fetching of
any envelopes other than the one specified. Otherwise, it will try to do
anticipatory fetching (up to IMAPLOOKAHEAD).
New GET_FETCHLOOKAHEAD allows better control of mail_fetch_structure()
lookahead. Instead of looking IMAPLOOKAHEAD messages forward from the
specified message, it will use a supplied SEARCHSET to generate message
sequences and ranges. It will stop at IMAPLOOKAHEAD messages or at the
completion of a range which exceeds IMAPLOOKAHEAD. The search set only
applies to the next mail_fetch_structure() on that stream, and is cleared
once it is used. Call with
SEARCHSET **set = (SEARCHSET **)
mail_parameters (stream,GET_FETCHLOOKAHEAD,(void *) stream);
*set = pointer to desired search set
New mail_shortdate() routine returns an date in the format expected by
SEARCHPGMs.
Updated: 2 November 2001
imap-2001a is a maintenance release, consisting primarily of bugfixes
including some critical bugfixes to crash and denial of service problems.
Programs written for imap-2001 will build with this version without
modification.
The following new facilities have also been added:
The new /norsh switch in mailbox names provides a more intuitive way of
disabling rsh-IMAP than the existing :143 or setting the rsh-timeout to 0.
Passwords are no longer returned in mm_dlog() callbacks unless the
application sets the SET_DEBUGSENSITIVE parameter.
The SET_NETFSSTATBUG parameter allows an application to force the
traditional UNIX mailbox driver to close and reopen the mailbox at ping
time. This is EXTREMELY inefficient, and should only be used to access
files stored on AFS and old NFS systems.
The ISO 8859 and Windows conversion tables have been updated to comply
with Unicode 3.1, and the KOI8-R table has been verified as compliant with
Unicode 3.1.
The SPECIALS mechanism for passing parameters to the lowest level Makefile
has been updated to be more general. See the next item for why you might
care.
New lrh port to build on Red Hat Linux 7.2, with pre-set definitions for
the places where Red Hat has placed Kerberos and SSL. It's actually just
the lnp port with SPECIALS defined accordingly. You may want to use it as
a model if your system needs such definitions. Note that SPECIALS is
primarily for IMAP toolkit (and Pine) purposes, and that user settings
should use EXTRASPECIALS instead.
Updated: 22 June 2001
imap-2001 is a major release. Programs written for imap-2000 will probably
build with this version without modification.
The FAQ document has been significantly expanded. Be sure to read it for
more information.
In addition to the usual bugfixes, the following features are new in
imap-2001:
SSL is now fully integrated into the IMAP toolkit; the old "alt" kludges to
be able to produce a "sanitized" version of the IMAP toolkit to comply with
late unlamented US export regulations are now completely gone.
Full client and server TLS support is also in this release.
The server certificate must be signed by a trusted certificate authority and
the name in the certificate match the user's entry for the server host name;
this means that the user must enter a fully-qualified host name.
To build with SSL/TLS on UNIX, you now use "SSLTYPE=unix" instead of the
former "SPECIALAUTHENTICATORS=ssl". To build with SSL/TLS on UNIX and disable
the use of plaintext passwords except when under SSL/TLS, use "SSLTYPE=nopwd"
instead of "SSLTYPE=unix".
RFC 1730 (IMAP4 as opposed to IMAP4rev1) support is turned off by default in
imapd. No clients should still be using RFC 1730 protocol. Look at the imapd
Makefile for how to re-enable RFC 1730 support. Note that this code may be
removed in the future, so if you think you need it you had better let me know.
There are some new options (turned off by default) which attempt to work around
problems in certain clients. See the FAQ file for more details.
Updated: 24 January 2001
imap-2000c is a maintenance release, consisting primarily of bugfixes.
Updated: 9 January 2001
imap-2000b is a maintenance release, consisting primarily of bugfixes.
Updated: 9 November 2000
imap-2000a is a maintenance release, consisting primarily of bugfixes.
Updated: 19 September 2000
imap-2000 is a major release. There are major internal and external changes
from earlier versions (imap-4.x and imap-3.x series). Programs written for
imap-4.x will probably build with this version without modification. It is
extremely unlikely that a program written for imap-3.x or earlier series will
build with this version without modifications. Drivers written for earlier
versions will definitely need to be rewritten.
In addition to the usual bugfixes, the following features are new in imap-2000:
SSL support is now available. For UNIX, it is necessary to install some
version of OpenSSL; see imap-2000/docs/SSLBUILD for more information. SSL
support is now automatic for the NT, NTK, and W2K ports. SSL use is indicated
by the /ssl switch in the mailbox name.
With SSL connections, the server certificate is validated by the client code
on UNIX, and Windows 2000 unless /novalidate-cert is specified. Server
certificates are currently is not validated on Windows 9x, Windows Millenium,
or Windows NT 4; this is an artifact of the operating system and not the port
(e.g. client code using the NT port will validate certificates if running on
Windows 2000). On UNIX, the server certificate must be signed by a trusted
certificate authority. On Windows 2000, the certificate must be signed by a
trusted certificate authority and match the user's entry for the server host
name; this means that the user must enter a fully-qualified host name.
Calendar reclama for the benefit of old broken non-Y2K compliant software.
Two digit years from 00 to 69 will be interpreted as 2000 through 2069. In
addition, three digit years from 100 to 105 will be interpreted as 2000
through 2005.
Support for REFERENCES threading (in addition to the previously-existing
ORDEREDSUBJECT threading).
Support for the IMAP MULTIAPPEND extension. This allows much faster uploading
of multiple messages to an IMAP server.
Support for the LOGINDISABLED IMAP capability. If the IMAP server sends
LOGINDISABLED as a capability, the client code will never attempt to send an
IMAP LOGIN command.
Support for SASL authentication identity vs. authorization identity. If the
authentication method does not support this concept (e.g. AUTH=CRAM-MD5,
AUTH=LOGIN, LOGIN command), the "*" character in the user name may be used to
indicate a separate authentication identity; for example, "fred*joe" indicates
authorization identity "fred", authentication identity "joe".
UNIX-specific Changes:
Support for SASL authentication identity vs. authorization identity in the
IMAP and POP3 servers. If the user indicated by the authentication identity
is in the "mailadm" group, he may specify any authorization identity and get
logged in as the authorization identity user.
If the IMAP and POP3 servers are build with PASSWDTYPE=nul, it will send
LOGINDISABLED as a capability and also disable the AUTH=LOGIN and AUTH=PLAIN
SASL authenticators.
New MAILSUBDIR build option to change the default mailbox directory from the
user's home directory to a subdirectory of the user's home directory. See
imap-2000/Makefile for more information.
New CHROOT_SERVER build option for closed server systems only. If defined, a
chroot() call to the user's home directory is done as part of the login
process. See imap-2000/Makefile for more information.
New ADVERTISE_THE_WORLD build option which will add an IMAP namespace that
points to the root. Not for the faint of heart.
UNIX format mailboxes no longer require the pseudo-message, nor will a
pseudo-message be added to a mailbox that does not have one. A new
X-IMAPbase: header will be written in the first message. This is rather less
efficient and robust than the pseudo-message (which remains the encouraged
mechanism; UNIX format mailboxes will always be created with it), but perhaps
will pacify some people who get upset by the pseudo-message.
When building with MIT Kerberos it will try to detect and use libk5crypto.a
instead of libcrypto.a.
The mbx driver is more aggressive about cleaning up expunged messages that
couldn't be purged because of shared access to the mailbox at the time of
expunge. Now, every checkpoint will try to purge such messages; and a
checkpoint is attempted at close time.
Windows-specific Changes:
New W2K port for Windows 2000. In addition to supporting SSL using the
official SSPI interface (the NT and NTK ports invoke SChannel.DLL directly),
the W2K port also supports Microsoft Kerberos. Note that the NT and NTK ports
will work on Windows 2000, but the W2K port will not work on NT4, Windows
9x, or Windows Millenium.
There is now a #user namespace, equivalent to the "~" namespace on UNIX.
Changes for Developers:
New c-client.h file which acts as a master include. c-client based
applications should now include c-client.h instead of the individual c-client
files (mail.h, misc.h, etc.). It is believed that c-client.h will work in C++
applications.
New GET_FREEENVELOPESPAREP/SET_FREEENVELOPESPAREP and
GET_FREEELTSPAREP/SET_FREEELTSPAREP function callbacks to free the "sparep"
member of the envelope and cache elements, respectively.
New OP_MULNEWSRC flag to mail_open() to use multiple newsrc files, and new
GET_NEWSRCQUERY/SET_NEWSRCQUERY function callbacks to get the name of the
newsrc file for news access.
New "secret" nntp_article() function to do the NNTP ARTICLE command; this is
generally useful only when chasing news URLs.
New GET_HIDEDOTFILES/SET_HIDEDOTFILES feature to suppress file names that
start with "." in mail_list() results.

267
docs/SSLBUILD Normal file
View File

@ -0,0 +1,267 @@
/* ========================================================================
* Copyright 1988-2007 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
SSL/TLS BUILD AND INSTALLATION NOTES FOR UNIX
Last Updated: 15 November 2007
PREREQUISITES BEFORE STARTING:
1) Review the information in imap-2007/docs/BUILD.
2) Obtain a copy of OpenSSL. OpenSSL is available from third parties. We
do not provide OpenSSL.
3) Make sure that you know how to build OpenSSL properly on the standard
/usr/local/ssl directory. In particular, /usr/local/ssl/include (and
/usr/local/ssl/include/openssl) and /usr/local/ssl/lib must be set up
from the OpenSSL build. If you have a non-standard installation, then
you must modify the imap-2007/src/osdep/unix/Makefile file to point
to the appropriate locations.
4) Make sure that you know how to obtain appropriate certificates on your
system.
NOTE: We can NOT provide you with support in building/installing OpenSSL, or
in obtaining certificates. If you need help in doing this, try the contacts
mentioned in the OpenSSL README.
SSL BUILD:
By default, the IMAP toolkit builds with SSL and disabling plaintext
passwords unless SSL/TLS encryption is in effect (SSLTYPE=nopwd). This
produces an IMAP server which is compliant with RFC 3501 security
requirements.
To build with SSL but allow plaintext passwords in insecure sessions,
add "SSLTYPE=unix" to the make command line. Note that doing so will
produce an IMAP server which is NON-COMPLIANT with RFC 3501.
To build without SSL, add "SSLTYPE=none" to the make command line.
Note that doing so will produce an IMAP server which is NON-COMPLIANT
with RFC 3501.
There are other make options relevant to SSL, described in
imap-2007/src/osdep/unix/Makefile
The most important of these are SSLDIR, SSLCRYPTO, and SSLRSA.
SSLDIR is set to /usr/local/ssl by default. This is the normal
installation directory for OpenSSL. If your system uses a different directory
you will need to change this.
SSLCRYPTO is set to -lcrypto by default. Older versions of MIT Kerberos
also have a libcrypto and will cause a library name conflict. If you are
using an older version of Kerberos, you may need to change SSLCRYPTO to
$(SSLLIB)/libcrypto.a
SSLRSA is set empty by default. It can be set to specify the RSAREF
libraries, which you once had to use with OpenSSL to use RSA algorithms
legally if you are in the USA, due to patent issues. Since RSA Security Inc.
released the RSA algorithm into the public domain on September 6, 2000, there
is no longer any reason to do this.
SSL INSTALLATION:
Binaries from the build are:
imap-2007/mtest/mtest c-client testbed program
imap-2007/ipopd/ipop2d POP2 daemon
imap-2007/ipopd/ipop3d POP3 daemon
imap-2007/imapd/imapd IMAP4rev1 daemon
mtest is normally not used except by c-client developers.
STEP 1: inetd setup
The ipop2d, ipop3d, and imapd daemons should be installed in a system
daemon directory and invoked by a listener such as xinetd or inetd. In the
following examples, /usr/local/etc is used).
STEP 1(A): xinetd-specific setup
If your system uses xinetd, the daemons are invoked by files in your
/etc/xinetd.d directory with names corresponding to the service names (that
is: imap, imaps, pop2, pop3, pop3s). You will need to consult your local
xinetd documentation to see what should go into these files. Here is a a
sample /etc/xinetd.d/imaps file:
service imaps
{
disable = no
socket_type = stream
wait = no
user = root
server = /usr/local/etc/imapd
groups = yes
flags = REUSE IPv6
}
STEP 1(B): inetd-specific setup
If your system still uses inetd, the daemons are invoked by your
/etc/inetd.conf file with lines such as:
pop stream tcp nowait root /usr/local/etc/ipop2d ipop2d
pop3 stream tcp nowait root /usr/local/etc/ipop3d ipop3d
imap stream tcp nowait root /usr/local/etc/imapd imapd
pop3s stream tcp nowait root /usr/local/etc/ipop3d ipop3d
imaps stream tcp nowait root /usr/local/etc/imapd imapd
Please refer to imap-2007/docs/BUILD for an important note about inetd's
limit on the number of new connections. If that note applies to you, and you
can configure the number of connection in /etc/inetd.conf as described in
imap-2007/docs/build, here is the sample /etc/inetd.conf entry with SSL:
pop3 stream tcp nowait.100 root /usr/local/etc/ipop3d ipop3d
pop3s stream tcp nowait.100 root /usr/local/etc/ipop3d ipop3d
imap stream tcp nowait.100 root /usr/local/etc/imapd imapd
imaps stream tcp nowait.100 root /usr/local/etc/imapd imapd
(or, if you use TCP wrappers)
pop3 stream tcp nowait.100 root /usr/local/etc/tcpd ipop3d
imap stream tcp nowait.100 root /usr/local/etc/tcpd imapd
pop3s stream tcp nowait.100 root /usr/local/etc/ipop3d ipop3d
imaps stream tcp nowait.100 root /usr/local/etc/imapd imapd
NOTE: do *NOT* use TCP wrappers (tcpd) for the imaps and pop3s services! I
don't know why, but it doesn't work with TCP wrappers.
STEP 2: services setup
You may also have to edit your /etc/services (or Yellow Pages,
NetInfo, etc. equivalent) to register these services, such as:
pop 109/tcp
pop3 110/tcp
imap 143/tcp
imaps 993/tcp
pop3s 995/tcp
NOTE: The SSL IMAP service *MUST* be called "imaps", and the SSL POP3 service
*MUST* be called "pop3s".
STEP 3: PAM setup
If your system has PAM (Pluggable Authentication Modules -- most
modern systems do) then you need to set up PAM authenticators for imap and
pop. The correct file names are
/etc/pam.d/imap
and
/etc/pam.d/pop
It probably works to copy your /etc/pam.d/ftpd file to the above two
names.
Many people get these file names wrong, and then spend a lot of time
trying to figure out why it doesn't work. Common mistakes are:
/etc/pam.d/imapd
/etc/pam.d/imap4
/etc/pam.d/imap4rev1
/etc/pam.d/imaps
/etc/pam.d/ipop3d
/etc/pam.d/pop3d
/etc/pam.d/popd
/etc/pam.d/pop3
/etc/pam.d/pop3s
STEP 4: certificates setup
NOTE: We can NOT provide you with support in obtaining certificates. If you
need help in doing this, try the contacts mentioned in the OpenSSL README.
WARNING: Do NOT install servers built with SSL support unless you also plan to
install proper certificates! It is NOT supported to run SSL-enabled servers
on a system without the proper certificates.
You must set up certificates on /usr/local/ssl/certs (this may be
different if you have a non-standard installation of OpenSSL; for example,
FreeBSD has modified OpenSSL to use /usr/local/certs). You should install
both the certificate authority certificates from the SSL distribution after
building OpenSSL, plus your own certificates. The latter should have been
purchased from a certificate authority, although self-signed certificates are
permissible. A sample certificate file is at the end of this document.
Install the resulting certificate file on /usr/local/ssl/certs, with a
file name consisting of the server name and a suffix of ".pem". For example,
install the imapd certificate on /usr/local/ssl/certs/imapd.pem and the ipop3d
certificate on /usr/local/ssl/certs/ipop3d.pem. These files should be
protected against random people accessing them. It is permissible for
imapd.pem and ipop3d.pem to be links to the same file.
The imapd.pem and ipop3d.pem must contain a private key and a
certificate. The private key must not be encrypted.
The following command to openssl can be used to create a self-signed
certificate with a 10-year expiration:
req -new -x509 -nodes -out imapd.pem -keyout imapd.pem -days 3650
*** IMPORTANT ***
We DO NOT recommend, encourage, or sanction the use of self-signed
certificates. Nor will we be responsible for any problems (including security
problems!) which result from your use of a self-signed certificate. Use of
self-signed certificates should be limited to testing only. Buy a real
certificate from a certificate authority!
*** IMPORTANT ***
If you have a multihomed system with multiple domain names (and hence
separate certificates for each domain name), you can append the IP address
to the service name. For example, the IMAP certificate for [12.34.56.78]
would be /usr/local/ssl/certs/imapd-12.34.56.78.pem and so on. You only need
to use this feature if you need to use multiple certificates (because different
DNS names are used).
SAMPLE CERTIFICATE FILE
Here is a sample certificate file. Do *NOT* use this on your own
machine; it is simply an example of what one would look like.
-----BEGIN RSA PRIVATE KEY-----
MIICXQIBAAKBgQDHkqs4YDbakYxRkYXIpY7xLXDQwULR5LW7xWVzuWmmZJOtzwlP
7mN87g+aaiQzwXUVndaCw3Zm6cOG4mytf20jPZq0tvWnjEB3763sorpfpOe/4Vsn
VBFjyQY6YdqYXNmjmzff5gTAecEXOcJ8CrPsaK+nkhw7bHUHX2X+97oMNQIDAQAB
AoGBAMd3YkZAc9LUsig8iDhYsJuAzUb4Qi7Cppj73EBjyqKR18BaM3Z+T1VoIpQ1
DeXkr39heCrN7aNCdTh1SiXGPG6+fkGj9HVw7LmjwXclp4UZwWp3fVbSAWfe3VRe
LM/6p65qogEYuBRMhbSmsn9rBgz3tYVU0lDMZvWxQmUWWg7BAkEA6EbMJeCVdAYu
nQsjwf4vhsHJTChKv/He6kT93Yr/rvq5ihIAPQK/hwcmWf05P9F6bdrA6JTOm3xu
TvJsT/rIvQJBANv0yczI5pUQszw4s+LTzH+kZSb6asWp316BAMDedX+7ID4HaeKk
e4JnBK//xHKVP7xmHuioKYtRlsnuHpWVtNkCQQDPru2+OE6pTRXEqT8xp3sLPJ4m
ECi18yfjxAhRXIU9CUV4ZJv98UUbEJOEBtx3aW/UZbHyw4rwj5N511xtLsjpAkA9
p1XRYxbO/clfvf0ePYP621fHHzZChaUo1jwh07lXvloBSQ6zCqvcF4hG1Qh5ncAp
zO4pBMnwVURRAb/s6fOxAkADv2Tilu1asafmqVzpnRsdfBZx2Xt4oPtquR9IN0Q1
ewRxOC13KZwoAWtkS7l0mY19WD27onF6iAaF7beuK/Va
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
MIIECTCCA3KgAwIBAgIBADANBgkqhkiG9w0BAQQFADCBujELMAkGA1UEBhMCVVMx
EzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcTB1NlYXR0bGUxHzAdBgNVBAoT
FkJsdXJkeWJsb29wIEluZHVzdHJpZXMxFjAUBgNVBAsTDUlTIERlcGFydG1lbnQx
ITAfBgNVBAMTGEJvbWJhc3RpYyBULiBCbHVyZHlibG9vcDEoMCYGCSqGSIb3DQEJ
ARYZYm9tYmFzdGljQGJsdXJkeWJsb29wLmNvbTAeFw0wMDA2MDYwMDUxMTRaFw0x
MDA2MDQwMDUxMTRaMIG6MQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3Rv
bjEQMA4GA1UEBxMHU2VhdHRsZTEfMB0GA1UEChMWQmx1cmR5Ymxvb3AgSW5kdXN0
cmllczEWMBQGA1UECxMNSVMgRGVwYXJ0bWVudDEhMB8GA1UEAxMYQm9tYmFzdGlj
IFQuIEJsdXJkeWJsb29wMSgwJgYJKoZIhvcNAQkBFhlib21iYXN0aWNAYmx1cmR5
Ymxvb3AuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDHkqs4YDbakYxR
kYXIpY7xLXDQwULR5LW7xWVzuWmmZJOtzwlP7mN87g+aaiQzwXUVndaCw3Zm6cOG
4mytf20jPZq0tvWnjEB3763sorpfpOe/4VsnVBFjyQY6YdqYXNmjmzff5gTAecEX
OcJ8CrPsaK+nkhw7bHUHX2X+97oMNQIDAQABo4IBGzCCARcwHQYDVR0OBBYEFD+g
lcPrnpsSvIdkm/eol4sYYg09MIHnBgNVHSMEgd8wgdyAFD+glcPrnpsSvIdkm/eo
l4sYYg09oYHApIG9MIG6MQswCQYDVQQGEwJVUzETMBEGA1UECBMKV2FzaGluZ3Rv
bjEQMA4GA1UEBxMHU2VhdHRsZTEfMB0GA1UEChMWQmx1cmR5Ymxvb3AgSW5kdXN0
cmllczEWMBQGA1UECxMNSVMgRGVwYXJ0bWVudDEhMB8GA1UEAxMYQm9tYmFzdGlj
IFQuIEJsdXJkeWJsb29wMSgwJgYJKoZIhvcNAQkBFhlib21iYXN0aWNAYmx1cmR5
Ymxvb3AuY29tggEAMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEEBQADgYEAwEEk
JXpVXVaFTuG2VJGIzPOxQ+X3V1Cl86y4gM1bDbqlilOUdByUEG4YfSb8ILIn+eXk
WzMAw63Ww5t0/jkO5JRs6i1SUt0Oy80DryNRJYLBVBi499WEduro8GCVD8HuSkDC
yL1Rdq8qlNhWPsggcbhuhvpbEz4pAfzPkrWMBn4=
-----END CERTIFICATE-----

145
docs/Y2K Normal file
View File

@ -0,0 +1,145 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
QUESTION: Is c-client Y2K compliant?
ANSWER:
There are no known Y2K issues in c-client; nor have there ever
been any known Y2K issues in c-client from its inception.
Some older versions of c-client don't like the two-digit year
"00", although the only impact of this is that messages with that year
will sort before any other messages. Nobody should be using two-digit
years in email messages any more (use "2000" instead of "00").
You may wish to read the document calendar.txt for more
information about the Y3.3K/Y4K, Y20K, and Y4)K issues. Assuming that
c-client is still around in 2000-40,000 years, someone will have to
deal with these.
Within the plausible lifetimes of people today, there are three
known date-related issues in c-client which will have to be addressed
in the future. If I am still alive when the first problem hits, I
will be nearly 82 years old, and won't be maintaining c-client any
more.
Y2038:
c-client, like most UNIX software, has Y2038 issues. On Tuesday,
January 19, 2038 at 03:14:08 Coordinated Universal Time (also known as
UTC, UT, or historically GMT), the clock on 32-bit UNIX systems will
wrap around to a negative number; that is, from 0x7fffffff to
0x80000000.
c-client uses an unsigned long for its 32-bit time; however the C
library on most UNIX systems uses a signed long and will interpret
that time as being Friday, December 13, 1901 at 20:45:52 UTC.
Fixing this problem will require changing the C library to use
either unsigned longs or a wider (e.g. 64-bit) value for time. Lots
of work will need to be done on 32-bit UNIX systems as 2038
approaches. History suggests that most of the work will be done in
the autumn of 2037... ;-) It's not known if anything is necessary to
do to c-client other than just rebuild it with the new C library.
Going to 32-bit unsigned longs means that there will be a Y2106
bug that someone will have to fix. Hopefully nobody will even think
of using 32-bit systems by then.
Y2070:
c-client assumes that 2-digit years with values of 70 or greater
are in the 20th century, and that 2-digit years with values of 69 or
less are in the 21st century. Time for UNIX began on January 1, 1970
and email on ARPAnet happened between the first TENEX systems shortly
after that; consequently there is no ambiguity with email data with
2-digit years prior to the year 2070. This is used only when parsing
a 2-digit year. c-client never generates one.
Fixing this problem requires convincing people not to use 2-digit
years. This is a lesson that people should have figured out 70 years
earlier with Y2K. Consequently, this may be a "non-problem."
Otherwise, look in mail_parse_date() for the comment "two digit year"
and change the statement as desired. [Note: do not change the
definition of BASEYEAR since the UNIX port assumes that this matches
when time began in the operating system.]
Y2098:
On January 1, 2098, the year in per-message internal dates will
expire, since a 7-bit field is allocated for the year. c-client will
mistakenly think that the day is January 1, 1970.
Fortunately, it is easy to fix this problem. Just increase the
width of "year" in MESSAGECACHE in mail.h. If you make it 8 bits,
it'll be good until January 1, 2216; 9 bits makes it good until 2482.
10 bits will push it back that you'd worry about the Y2800 question
before having to increase it again. If you ignore Y2800, 11 bits will
push it it back to having to worry about Y4K first.
Y2800:
At this year, you will need to decide whether to keep the Gregorian
calendar, which is one day slow every 20,000 years, or go to the more
accurate Eastern Orthodox calendar which is one day slow every 45,000
years. The Gregorian and Eastern Orthodox calendars diverge at this
year.
There hasn't been any statement about how the international
community will deal with the situation of the Orthodox calendar being
one day ahead of the Gregorian calendar between 2800 and 2900. This
will happen again between 3200 and 3300, and at gradually increasing
intervals until 48,300 when the shift becomes permanent (assuming no
Y20K or Y40K fixes).
If you wish to make the transition to the Eastern Orthodox calendar,
rebuild c-client with -DUSEORTHODOXCALENDAR=1. You can then ignore Y4K
and Y20K!
Y3.3K/Y4K:
Some time around the year 3300, the calendar has gotten one day
behind. To remedy this, a little-known rule in the Gregorian calendar
is that years that are evenly divisible by 4000 are not leap years.
Unlike the other rules, this rule hasn't had effect yet, and won't for
another 2000 years.
To fix the Y4K problem, just rebuild c-client with -DY4KBUGFIX=1.
Y20K:
Those of you who stuck with the Gregorian calendar have a
problem; the calendar is now one day slow. The Pope has not made any
statement about how this problem will be fixed. Maybe they'll declare
that 20,004 is also not a leap year or something.
There is no fix for this problem in c-client.
Y40K:
Greeks, Serbs, Russians, and other Eastern Orthodox have spent
the past 38,000 years laughing at westerners' increasingly futile
efforts to keep the Gregorian calendar in order. The day of reckoning
has come; the Orthodox calendar is now one day slow. The Patriarch of
Istanbul (nee Constantinople) has not made any statement about how this
will be fixed.
There is no fix for this problem in c-client.

234
docs/bugs.txt Normal file
View File

@ -0,0 +1,234 @@
/* ========================================================================
* Copyright 1988-2007 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
KNOWN BUGS/MISFEATURES/DEFICIENCIES IN THE IMAP TOOLKIT
Last Updated: 15 November 2007
The following are known problems/deficiencies in the imap-2007 toolkit:
. Possible problems for some installations:
. In some versions of Redhat Linux, SVR4-style timezone name lookup
doesn't work properly due to a bug in glibc. The workaround is to
edit os_lnx.c to include tz_bsd.c instead of tz_sv4.c. Note that
other versions of Linux don't support BSD-style timezone name
lookup, so don't make this change unless it's needed on your system.
. In some systems, the OpenSSL distribution is installed other than at
the standard /usr/local/ssl location. If this is the case on your
system and you want to build with SSL support, you will need to set
the SSLDIR variable, either by including a setting of EXTRASPECIALS
in the make command line, e.g.
build lnp SPECIALAUTHENTICATORS=ssl EXTRASPECIALS="SSLDIR=/usr/ssl"
or by editing .../src/osdep/unix/Makefile
. /tmp, /usr/tmp or /var/tmp (if present), and the mail spool directory
must be protected 1777 (world write with sticky bit); otherwise
mailbox locking and updates won't work. An alternative to 1777 on
the mail spool directory is to install the mlock program that is
bundled with the IMAP toolkit.
. Multiple access protection locking does not work if the mailbox or
/tmp are NFS mounted.
. Shared access mailbox formats (mbx, mtx, mx, and tenex) do not work
well with NFS and such usage is not supported. mmdf and unix formats
are supported for use over NFS; however there won't be any multiple
access locking protection.
. Server startup delays may occur if a reverse DNS (IP address to name)
lookup on the client's IP address does not complete in an expeditious
fashion. This is actually a DNS problem and should be fixed in the
DNS and/or the server's host table. A workaround exists (see the
top-level Makefile for details) but is not recommended and can not
be used at all with Kerberos.
. At the insistance of the security gurus, SSL certification validation
is now on by default. This means that you must now use the new
/novalidate-cert switch if establishing an SSL connection to a server
with a self-signed certificate; i.e. if "imap.example.com" has a
self-signed certificate, you must use a mailbox name such as
{imap.example.com/ssl/novalidate-cert}INBOX
to get an SSL session instead of just
{imap.example.com/ssl}INBOX
. GCC 8.x and above on SGI systems does not correctly pass/return
structures which are smaller than 16 bytes and are not 8 bytes. The
problem is that structures are padded at the wrong end; e.g. a 4 byte
structure is loaded into the lower 4 bytes of the register when it
should be loaded into the upper 4 bytes of the register. This affects
IRIX 6 the most because it is a 64-bit system and 4 byte structures are
common. This compiler bug impacts the use of inet_ntoa() in c-client
and causes syslog messages to show IP addresses as 255.255.255.255
instead of the correct values. The fix is either to use SGI's C compiler
instead of GCC or link with an implementation of inet_ntoa() that was
built with GCC instead of the standard SGI C library version.
. By default, the UNIX SSL build assumes that RSAREF is not needed, because
RSA Security Inc. released the RSA public key encryption algorithm into
the public domain on September 6, 2000. There is no longer any need to
use RSAREF, and since RSAREF is slower than OpenSSL's RSA routines
there's good reason not to. If for some reason you still want to use
RSAREF, you will need to edit .../src/osdep/unix/Makefile to
change SSLRSA to load libRSAglue and librsaref.
. By default, the UNIX SSL build assumes that no name conflict exists
between OpenSSL and Kerberos 5. If you are using an older version
of Kerberos, you may need to edit .../src/osdep/unix/Makefile
to change SSLCRYPTO so that it loads the OpenSSL libcrypto library
explicitly as libcrypto.a.
. By default, host names are canonicalized via gethostbyname() and
gethostbyaddr() for everything except for SSL certificate validation.
This can represent a security bug due to DNS spoofing, but is more
likely to deliver results that users expect and also may be necessary
to get Kerberos to work. Set variable "trustdns" in mail.c to NIL if
you want to disable this.
. Bugs:
. It doesn't work to have a "}" character as a user name in /user= in a
mailbox name, even if the user name is quoted. In other words,
{example.com/user="foo}bar"}zap
won't work; foo will be interpreted as an unterminated quoted string
and the remote mailbox name will be
bar"}zap.
. The experimental mx driver has performance problems and shouldn't be used
. docs/internal.txt is out of date (again)
. UIDPLUS bugs/limitations:
. Not supported in all local file formats (see below).
. There are two known issues with UIDPLUS in the mmdf and unix formats:
(a) If the destination mailbox is currently selected (whether in this
or another session), no COPYUID or APPENDUID is returned. The other
choice was to assign a UID based upon the uid_last value and hope
that the session selecting the mailbox would pick it up and update
uid_last. The problem was a timing race if another message was
copied/appended to that mailbox before the selecting session updated
the mailbox. If the timing race is lost, then all UID in the mailbox
would be reassigned by the selecting session, thus making the
returned APPENDUID/COPYUID data useless and causing a performance
problem.
Earlier versions did the "hope for the best" method. This was
revoked in favor of not returning COPYUID/APPENDUID.
Although this violates RFC 4315, there is a loophole which, although
for other purposes, permits this behavior.
(b) There is a known failure if the destination mailbox is currently
selected by legacy software (e.g. older versions of the IMAP
server, Pine, etc.). In this case, all UIDs end up being
reassigned by the legacy software.
. Annoyances:
. Friendly host names (e.g. "server" instead of "server.foo.com") can't be
used in a mailbox name with SSL certificate validation; you have to enter
the fully-qualified domain name. This is a requirement established by
the security gurus.
. IMAP client limitations:
. No SASL protection mechanisms (SASL authentication mechanisms are
supported)
. NNTP client limitations:
. Non-standard IMAP SCAN extension not supported
. POP client limitations:
. No SASL protection mechanisms (SASL authentication mechanisms are
supported)
. No POP3 UID support
. Non-standard IMAP SCAN extension not supported
. SMTP client limitations:
. No SASL protection mechanisms (SASL authentication mechanisms are
supported)
. No support for use of TURN, ETRN, and pipelining.
. No support for enhanced status codes
. UNIX limitations:
. IPv6 is supported but is not the default on most platforms; you have to
use IP=6 in the make command
. Supported local file formats: mbx, mh, mmdf, mix, mtx, mx, news, phile,
tenex, unix
. Supported SASL mechanisms: CRAM-MD5, PLAIN, LOGIN, ANONYMOUS, GSSAPI
. Sticky UIDs are not supported in the mh, mtx, and tenex drivers
. Creation of keywords is not supported in the mh, mtx, and tenex drivers
. Copy and append of keywords only works in the mbx driver.
. Flat file formats (mbx, mmdf, mtx, phile, tenex, unix) do not permit
mailboxes to have inferior names
. SSL temporary key should be seeded better than it is.
. UIDPLUS support is limited to the unix, mmdf, mbx, mx, and mix formats.
. Non-standard IMAP SCAN extension not support for mh and news formats.
. Amiga limitations:
. Supported local file formats: mbx, mh, mmdf, mix, mtx, mx, news, phile,
tenex, unix
. Supported SASL mechanisms: CRAM-MD5, PLAIN, LOGIN, ANONYMOUS
. Sticky UIDs are not supported in the mh, mtx, and tenex drivers
. Creation of keywords is not supported in the mh, mtx, and tenex drivers
. Copy and append of keywords only works in the mbx driver.
. Flat file formats (mbx, mmdf, mtx, phile, tenex, unix) do not permit
mailboxes to have inferior names
. UIDPLUS support is limited to the unix, mmdf, mbx, mx, and mix formats.
. Non-standard IMAP SCAN extension not supported for mh and news formats.
. Win32 (Win9x/NT/Windows 2000) limitations:
. IPv6 is supported in W2K builds but is not the default; you have to use
IP=6 in the nmake command
. Supported local file formats: mbx, mtx, tenex, unix
. Supported SASL mechanisms: CRAM-MD5, PLAIN, LOGIN, ANONYMOUS, GSSAPI
. No server SSL or TLS support.
. No server authentication for GSSAPI
. No server authentication for CRAM-MD5 on NT-based Windows (NT/2K/XP);
it does work on DOS-based Windows (9x/Me).
. Sticky UIDs are not supported in the mtxnt and tenexnt drivers
. Creation of keywords is not supported in the mtxnt and tenexnt drivers
. Copy and append of keywords only works in the mbxnt driver.
. No support for TCP open timeouts
. Flat file formats (mbx, mtx, tenex, unix) do not permit mailboxes to have
inferior names
. UIDPLUS support is limited to the unix and mbx formats.
. Win16 (Win3.1)/DOS limitations:
. IPv6 not supported
. Supported local file formats: bezerk, mtx
. Supported SASL mechanisms: CRAM-MD5, LOGIN, ANONYMOUS
. Supported TCPs: B&W, Novell, PC-NFs, PC/TCP, Waterloo, Winsock
. Sticky UIDs are not supported on local files
. Creation of keywords are not supported on local files
. Bezerk driver is read-only and does not handle LF-only newlines well
. No support for any TCP timeouts on Waterloo DOS
. No support for TCP open timeouts on Winsock and generic DOS
. Flat file formats (bezerk, mtx) do not permit mailboxes to have inferior
names
. Does not work well unless a mailgets routine is armed when fetching
texts.
. Mac limitations:
. IPv6 not supported
. No local file drivers
. Supported SASL mechanisms: CRAM-MD5, LOGIN, ANONYMOUS
. Does not output human-friendly time zone string
. TOPS-20 limitations:
. IPv6 not supported
. No local file drivers
. Supported SASL mechanisms: CRAM-MD5, LOGIN, ANONYMOUS
. No support for any TCP timeouts
. VMS limitations:
. IPv6 not supported
. No local file drivers
. Supported SASL mechanisms: CRAM-MD5, LOGIN, ANONYMOUS
. Supported TCPs: Multinet, Netlib
. No support for any TCP timeouts on VMS Netlib
. No support for TCP open timeouts on VMS Multinet
. Time zone must be configured at build time
. Does not output human-friendly time zone string
. Windows CE limitations:
. IPv6 not yet supported
. No local file drivers
. Supported SASL mechanisms: CRAM-MD5, LOGIN, ANONYMOUS
. No support for TCP open timeouts
. Not finished, only builds c-client library
. OS/2 limitations:
. IPv6 not supported
. Not finished, does not build

332
docs/calendar.txt Normal file
View File

@ -0,0 +1,332 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
ALL ABOUT CALENDARS
Although one can never be sure of what will happen at some future
time, there is strong historical precedent for presuming that the
present Gregorian calendar will still be in effect within the useful
lifetime of the IMAP toolkit. We have therefore chosen to adhere to
these precedents.
The purpose of a calendar is to reckon time in advance, to show
how many days have to elapse until a certain event takes place in the
future, such as the harvest or the release of a new version of Pine.
The earliest calendars, naturally, were crude and tended to be based
upon the seasons or the lunar cycle.
ANCIENT CALENDARS
The calendar of the Assyrians, for example, was based upon the
phases of the moon. They knew that a lunation (the time from one full
moon to the next) was 29 1/2 days long, so their lunar year had a
duration of 354 days. This fell short of the solar year by about 11
days. (The exact time for the solar year is approximately 365 days, 5
hours, 48 minutes, and 46 seconds.) After 3 years, such a lunar
calendar would be off by a whole month, so the Assyrians added an extra
month from time to time to keep their calendar in synchronization with
the seasons.
The best approximation that was possible in antiquity was a 19-year
period, with 7 of these 19 years having 13 months (leap months). This
scheme was adopted as the basis for the lunar calendar used by the
Hebrews. The Arabs also used this calendar until Mohammed forbade
shifting from 12 months to 13 months; this causes the Muslim holy month
of Ramadan to move backwards through the seasons, completing a cycle
every 32 1/2 years.
When Rome emerged as a world power, the difficulties of making a
calendar were well known, but the Romans complicated their lives because
of their superstition that even numbers were unlucky. Hence their
months were 29 or 31 days long, with the exception of February, which
had 28 days. Every second year, the Roman calendar included an extra
month called Mercedonius of 22 or 23 days to keep up with the solar
year.
JULIAN CALENDAR
Even this algorithm was very poor, so that in 45 BCE, Caesar,
advised by the astronomer Sosigenes, ordered a sweeping reform. By
imperial decree, the year 46 BCE was made 445 days long to bring the
calendar back in step with the seasons. The new calendar, similar to
the one we now use was called the Julian calendar (named after Julius
Caesar).
Months in the Julian calendar were 30 or 31 days in length and
every fourth year was made a leap year (having 366 days) by adding a day
to the end of the year. This leap year rule was not consistantly
applied until 8 CE. The year-ending month of February, never a popular
month, was presently shortened so that Julius Caesar and Emperor
Augustus could each have long months named after them.
Caesar also decreed that the year would start with the first of
January, which since 153 BCE was the day that Roman consuls took office,
and not the vernal equinox in late March. Not everyone accepted that
part of his reform, as we shall see.
GREGORIAN CALENDAR
Caesar's year was 11 1/2 minutes short of the calculations
recommended by Sosigenes and eventually the date of the vernal equinox
began to drift. Roger Bacon became alarmed and sent a note to Pope
Clement IV, who apparently was not impressed. Pope Sixtus IV later
became convinced that another reform was needed and called the German
astronomer, Regiomontanus, to Rome to advise him. Unfortunately,
Regiomontanus died of the plague shortly thereafter and the plans died
as well.
In 1545, the Council of Trent authorized Pope Gregory XIII to
reform the calendar once more. Most of the mathematical work was done
by Father Christopher Clavius, S.J. The immediate correction that was
adopted was that Thursday, October 4, 1582 was to be the last day of the
Julian calendar. The next day was Friday, with the date of October 15.
For long range accuracy, a formula suggested by the Vatican librarian
Aloysius Giglio was adopted. It said that every fourth year is a leap
year except for century years that are not divisible by 400. Thus 1700,
1800 and 1900 would not be leap years, but 2000 would be a leap year
since 2000 is divisible by 400. This rule eliminates 3 leap years every
4 centuries, making the calendar sufficiently correct for most ordinary
purposes. This calendar is known as the Gregorian calendar and is the
one that we now use today.
It is interesting to note that in 1582, all the Protestant princes
ignored the papal decree and so many countries continued to use the
Julian calendar until either 1698 or 1752. Britain and its American
colonies went from Wednesday, September 2, 1752 to Thursday, September
14. Prior to the changeover, the British used March 25 as the start of
the new year.
In Russia, it needed the revolution to introduce the Gregorian
calendar in 1918. Turkey didn't adopt it until 1927.
NUMBERING OF YEARS
The numbering of the year is generally done according to an "era",
such as the year of a ruler's reign.
In about 525, a monk named Dionysius Exiguus suggested that the
calculated year of Jesus' birth be designated as year 1 in the Julian
calendar. This suggestion was adopted over the next 500 years and
subsequently followed in the Gregorian calendar.
For the benefit of those who seek religious significance to the
calendar millenium, note that year 1 is too late by at least 4 years.
Herod the Great, named in the Christian Bible as having all children in
Bethlehem put to death in an attempt to kill the infant Jesus, died in 4
BCE.
Nothing particularly significant of an historic or religious nature
happened in Gregorian year 1; however it has become a worldwide standard
as the "common era." In modern times, the terms "CE" (common era) and
"BCE" (before common era) are preferred over the earlier (and, as we
have seen, less accurate) "AD" (anno Domini, "the year of the Lord") and
"BC" (before Christ).
The Hebrew lunar calendar begins at 3760 BCE, the year of creation
in Jewish tradition. The Muslim lunar calendar begins on July 16, 622,
when Mohammed fled from Mecca to Medina.
The Japanese, Taiwanese, and North Koreans use the Gregorian
calendar, but number the year by political era. In Japan, an era
begins when an emperor succeeds to the throne; year 1 of the Heisei
era was 1989 when Emperor Akihito ascended to the throne (the first
few days of 1989 was year 64 of the Shouwa era). In Taiwan, year 1 is
the first full year after the founding of the Republic of China in 1911.
In North Korea, year 1 is the year of the Juche (self-reliance) ideal,
corresponding to the birth year of founder Kim Il-Sung (1912). Thus,
year 2000 is Heisei 12 (Japan), 89th year of the Republic (Taiwan),
and Juche 89 (North Korea).
FURTHER MODIFICATIONS TO THE GREGORIAN CALENDAR
Despite the great accuracy of the Gregorian calendar, it still
falls behind very slightly every few years. The most serious problem
is that the earth's rotation is slowing gradually. If you are very
concerned about this problem, we suggest that you tune in short wave
radio station WWV or the Global Positioning System, which broadcasts
official time signals for use in the United States. About once every
3 years, they declare a leap second at which time you should be
careful to adjust your system clock. If you have trouble picking up
their signals, we suggest you purchase an atomic clock (not part of
the IMAP toolkit).
Another problem is that the Gregorian calendar represents a year
of 365.2425 days, whereas the actual time taken for the earth to
rotate around the Sun is 365.2421991 days. Thus, the Gregorian calendar
is actually 26 seconds slow each year, resulting in the calendar
being one day behind every 3,300 or so years (a Y3.3K problem).
Consequently, the Gregorian calendar has been modified with a
further rule, which is that years evenly divisible by 4000 are not
leap years. Thus, the year 4000 will not be a leap year. Or, at
least we assume that's what will happen assuming that the calendar
remains unchanged for the next 2000 years.
The modified Gregorian calendar represents a year of 365.24225
days. Thus, the modified Gregorian calendar is actually 4 seconds
slow each year, resulting in the calendar being one day slow every
20,000 or so years. So there will be a Y20K problem.
There is some dispute whether the modified Gregorian calendar was
officially adopted, or if it's just a proposal. Other options (see
below) exist; fortunately no decision needs to be made for several
centuries yet.
There is code in c-client to support the modified Gregorian
calendar, although it is currently disabled. Sometime in the next
2000 years, someone will need to enable this code so that c-client is
Y4K compiliant. Then, 18,000 years from now, someone will have to
tear into c-client's code to fix the Y20K bug.
EASTERN ORTHODOX MODIFICATION OF THE GREGORIAN CALENDAR
The Eastern Orthodox church in 1923 established its own rules to
correct the Julian calendar. In their calendar, century years modulo
900 must result in value of 200 or 600 to be considered a leap year.
Both the Orthodox and Gregorian calendar agree that the years 2000 and
2400 will be leap years, and the years 1900, 2100, 2200, 2300, 2500,
2600, 2700 are not. However, the year 2800 will be a leap year in the
Gregorian calendar but not in the Orthodox calendar; similarly, the
year 2900 will be a leap year in the Orthodox calendar but not in the
Gregorian calendar. Both calendars will agree that 3000 and
3100 are leap years, but will disagree again in 3200 and 3300.
There is code in c-client to support the Orthodox calendar. It
can be enabled by adding -DUSEORTHODOXCALENDAR=1 to the c-client
CFLAGS, e.g.
make xxx EXTRACFLAGS="-DUSEORTHODOXCALENDAR=1"
The Orthodox calendar represents a year of 365.24222222... days.
Thus, the Orthodox calendar is actually 2 seconds slow each year,
resulting in the calendar being one day slow every 40,000 or so years.
The Eastern Orthodox church has not yet made any statements on how the
Y40K bug will be fixed.
OTHER ISSUES AFFECTING THE CALENDAR IN THE FUTURE
The effect of leap seconds also needs to be considered when
looking at the Y3.3K/Y4K, Y20K, and Y40K problems. Leap seconds put
the clock back in line with the Earth's rotation, whereas leap years
put the calendar back in line with the Earth's revolution. Since leap
seconds slow down the clock (and hence the calendar), they actually
bring the day of reckoning for the Gregorian and Orthodox calendars
sooner.
Another factor is that the next ice age (technically, the end of
the current interglacial period; we are in the middle of an ice age
now!) is due around Y25K. It is not known what perturbations this will
cause on the Earth's rotation and revolution, nor what calendar
adjustments will be necessary at that time.
Hence my use of "or so" in predicting the years that the calendar
will fall behind. The actual point may be anywhere from decades (in the
case of Y3.3K) to millenia (in the case of Y40K) off from these predictions.
MEANINGS OF DAY NAMES
The names of days of the week from a combination of Roman and
Germanic names for celestial bodies:
. Sunday Latin "dies solis" => "Sun's day"
. Monday Latin "dies lunae" => "Moon's day"
. Tuesday Germanic "Tiw's day" => "Mars' day"
. Wednesday Germanic "Woden's day" => "Mercury's day"
. Thursday Germanic "Thor's day" => "Jupiter's day"
. Friday Germanic "Frigg's day" => "Venus' day"
. Saturday Latin "dies Saturni" => "Saturn's day"
MEANINGS OF MONTH NAMES
The names of the months are from the Roman calendar:
. January Janus, protector of doorways
. February Februalia, a time for sacrifice to atone for sins
. March Mars, god of war
. April Latin "aperire" => "to open" buds
. May Maia, goddess of plant growth
. June Latin "juvenis" => "youth"
. July Julius Caesar
. August Augustus Caesar
. September Latin "septem" => "seven"
. October Latin "octo" => "eight"
. November Latin "novem" => "nine"
. December Latin "decem" => "ten"
As you'll notice, the last four months are numbered 7 to 10, which
is an artifact of the time when the new year started in March.
INTERESTING FORMULAE
There's another reason why the historical starting of the new year
is significant. Starting with March, the length of months follows a
mathematical series:
31 30 31 30 31 31 30 31 30 31 31 28
This means that you can calculate the day of week for any
arbitrary day/month/year of the Gregorian calendar with the following
formula (note all divisions are integral):
_ _
| 7 + 31*(m - 1) y y y |
dow = | d + -------------- + y + - - --- + --- | MOD 7
|_ 12 4 100 400_|
where
d := day of month (1..31)
m := month in old style (March = 1..February = 12)
y := year in old style
dow := day of week (Tuesday = 0..Monday = 6)
To convert from new style month/year to old style:
if (m > 2) m -= 2; /* Mar-Dec: subtract 2 from month */
else m += 10,y--; /* Jan-Feb: months 11 & 12 of previous year */
Here's another fun formula. To find the number of days between two
days, calculate a pair of calendar days with the formula (again, all
divisions are integral), using new style month/year this time:
m
m + -
8 y y y
d + 30 * (m - 1) + ----- + y * 365 + - - --- + --- - ld
2 4 100 400
where:
d := day of month (1..31)
m := month in new style (January = 1..December = 12)
y := year in new style
ld := leap day correction factor:
0 for January and February in non-leap years
1 for January and February in leap years
2 for all other months in all years
In C code, the leap day correction factor is calculated as:
(m < 3) ? !(y % 4) && ((y % 100) || !(y % 400)) : 2
It's up to you to figure out how to adapt these formulas for the
Y4K bugfix and the Orthodox calendar. If you're really clever, try to
use these formulae to implement the C library ctime(), gmtime(), and
mktime() functions. Most C library implementations use a table of the
number of days in a month. You don't need it.
ACKNOWLEDGEMENT:
The original version is from an old Digital Equipment Corporation SPR
answer for VMS. Modifications for c-client, and additional information
added by Mark Crispin.

101
docs/commndmt.txt Normal file
View File

@ -0,0 +1,101 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
[I wrote this tongue-in-cheek, but there's a lot here that people who
build IMAP clients should take careful note. Most existing clients
violate at least one, generally several, of these commandments.
These are based on known user-visible problems that occur with various
commonly used clients. Put another way, behind each commandment is a
plethora of user (and server administrator) complaints caused by a
violator.]
Ten Commandments of How to Write an IMAP client
Mark Crispin
1. Thou shalt not assume that it is alright to open multiple IMAP
sessions selected on the same mailbox simultaneously, lest thou face
the righteous wrath of mail stores that doth not permit such access.
Instead, thou shalt labor mightily, even unto having to use thy brain
to thinketh the matter through, such that thy client use existing
sessions that are already open.
2. Thou shalt not abuse the STATUS command by using it to check for
new mail on a mailbox that you already have selected in an IMAP
session; for that session hath already told thou about new mail
without thy having to ask.
3. Thou shalt remember the 30 minute inactivity timeout, and remember
to speak to the IMAP server before that timeout expires. If thou
useth the IDLE command, thou shalt send DONE from the IDLE before 29
minutes hath passed, and issue a new IDLE. If thou maketh no use of
IDLE, then thou shalt send NOOP every few minutes, and the server
shalt tell you about new mail, and there will be much rejoicing in the
land.
4. Thou shalt not assume that all names are both the name of a mailbox
and the name of a upper level of hierarchy that contains mailboxes;
lest thou face the righteous wrath of mail stores in which a mailbox
is a file and a level of hierarchy is a directory. Thou shalt pay
diligent attention to the \NoSelect and \NoInferiors flags, so that
your users may praise you with great praise.
5. Thou shalt learn and understand the unique features of IMAP, such
as the unsolicited data model, the strict ascending rule of UIDs, how
UIDs map to sequence numbers, the ENVELOPE and BODYSTRUCTURE
structures; so that thou may use the IMAP protocol effectively. For a
POP client hacked to babble IMAP protocol is still no more than a POP
client.
6. Thou shalt remember untagged data sent by the server, and when thou
needest data thou shalt consult your memory before asking the server.
For those who must analyze thy protocol transactions are weak of
stomach, and are likely to lose their recent meal should they see thou
repeatedly re-fetch static data.
7. Thou shalt labor with great effort to work within the IMAP
deleted/expunge model, even if thy own model is that of a trashcan;
for interoperability is paramount and a trashcan model can be done
entirely in the user interface.
8. Thou shalt not fear to open multiple IMAP sessions to the server;
but thou shalt use this technique with wisdom. For verily it is true;
if thou doth desire to monitor continuously five mailboxes for new
mail, it is better to have five IMAP sessions continuously open on the
mailboxes. It is generally not good to do a succession of five SELECT
or STATUS commands on a periodic basis; and it is truly wretched to
open and close five sessions to do a STATUS or SELECT on a periodic
basis. The cost of opening and closing a session is great, especially
if that session is SSL/TLS protected; and the cost of a STATUS or
SELECT can also be great. By comparison, the cost of an open session
doing an IDLE or getting a NOOP every few minutes is small. Great
praise shall be given to thy wisdom in doing what is less costly
instead of "common sense."
9. Thou shalt not abuse subscriptions, for verily the LIST command is
the proper way to discover mailboxes on the server. Thou shalt not
subscribe names to the user's subscription list without explicit
instructions from the user; nor shalt thou assume that only subscribed
names are valid. Rather, thou shalt treat subscribed names as akin to
a bookmarks, or perhaps akin to how Windows shows the "My Documents"
folder -- a set of names that are separate from the hierarchy, for
they are such.
10. Thou shalt use the LIST "*" wildcard only with great care. If
thou doth not fully comprehend the danger of "*", thou shalt use only
"%" and forget about the existance of "*".
Honor these commandments, and keep them holy in thy heart, so that thy
users shalt maximize their pleasure, and the server administrators
shalt sing thy praises and recommend thy work as a model for others to
emulate.

19
docs/draft/README Normal file
View File

@ -0,0 +1,19 @@
Last Updated: 6 March 2008
This directory contains Internet Drafts which, at the time of release of
this software, were not yet been published as RFCs. These documents are
expected to be released as RFCs in the near future.
This software adheres to the specification in these documents, which
are included for informational purposes. Note, however, that these
documents must be considered preliminary in nature and will be superceded
by the successor RFC.
File Name I-D Name
--------- --------
sort.txt draft-ietf-imapext-sort-20.txt
;; SORT and THREAD commands
;; Status: approved, blocked waiting for i18n
i18n.txt draft-ietf-imapext-i18n-15.txt
;; internationalization in IMAP

1140
docs/draft/i18n.txt Normal file
View File

File diff suppressed because it is too large Load Diff

885
docs/draft/sort.txt Normal file
View File

@ -0,0 +1,885 @@
IMAP Extensions Working Group M. Crispin
Internet-Draft K. Murchison
Intended status: Proposed Standard March 10, 2008
Expires: September 10, 2008
Document: internet-drafts/draft-ietf-imapext-sort-20.txt
INTERNET MESSAGE ACCESS PROTOCOL - SORT AND THREAD EXTENSIONS
Status of this Memo
By submitting this Internet-Draft, each author represents that
any applicable patent or other IPR claims of which he or she is
aware have been or will be disclosed, and any of which he or she
becomes aware will be disclosed, in accordance with Section 6 of
BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
A revised version of this draft document will be submitted to the RFC
editor as a Proposed Standard for the Internet Community. Discussion
and suggestions for improvement are requested, and should be sent to
ietf-imapext@IMC.ORG.
Distribution of this memo is unlimited.
Abstract
This document describes the base-level server-based sorting and
threading extensions to the [IMAP] protocol. These extensions
provide substantial performance improvements for IMAP clients which
offer sorted and threaded views.
1. Introduction
The SORT and THREAD extensions to the [IMAP] protocol provide a means
of server-based sorting and threading of messages, without requiring
that the client download the necessary data to do so itself. This is
particularly useful for online clients as described in [IMAP-MODELS].
A server which supports the base-level SORT extension indicates this
with a capability name which starts with "SORT". Future,
upwards-compatible extensions to the SORT extension will all start
with "SORT", indicating support for this base level.
A server which supports the THREAD extension indicates this with one
or more capability names consisting of "THREAD=" followed by a
supported threading algorithm name as described in this document.
This provides for future upwards-compatible extensions.
A server which implements the SORT and/or THREAD extensions MUST
collate strings in accordance with the requirements of I18NLEVEL=1,
as described in [IMAP-I18N], and SHOULD implement and advertise the
I18NLEVEL=1 extension. Alternatively, a server MAY implement
I18NLEVEL=2 (or higher) and comply with the rules of that level.
Discussion: the SORT and THREAD extensions predate [IMAP-I18N] by
several years. At the time of this writing, all known server
implementations of SORT and THREAD comply with the rules of
I18NLEVEL=1, but do not necessarily advertise it. As discussed
in [IMAP-I18N] section 4.5, all server implementations should
eventually be updated to comply with the I18NLEVEL=2 extension.
Historical note: the REFERENCES threading algorithm is based on the
[THREADING] algorithm written used in "Netscape Mail and News"
versions 2.0 through 3.0.
2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [KEYWORDS].
The word "can" (not "may") is used to refer to a possible
circumstance or situation, as opposed to an optional facility of the
protocol.
"User" is used to refer to a human user, whereas "client" refers to
the software being run by the user.
In examples, "C:" and "S:" indicate lines sent by the client and
server respectively.
2.1 Base Subject
Subject sorting and threading use the "base subject," which has
specific subject artifacts removed. Due to the complexity of these
artifacts, the formal syntax for the subject extraction rules is
ambiguous. The following procedure is followed to determine the
"base subject", using the [ABNF] formal syntax rules described in
section 5:
(1) Convert any RFC 2047 encoded-words in the subject to
UTF-8 as described in "internationalization
considerations." Convert all tabs and continuations to
space. Convert all multiple spaces to a single space.
(2) Remove all trailing text of the subject that matches
the subj-trailer ABNF, repeat until no more matches are
possible.
(3) Remove all prefix text of the subject that matches the
subj-leader ABNF.
(4) If there is prefix text of the subject that matches the
subj-blob ABNF, and removing that prefix leaves a non-empty
subj-base, then remove the prefix text.
(5) Repeat (3) and (4) until no matches remain.
Note: it is possible to defer step (2) until step (6), but this
requires checking for subj-trailer in step (4).
(6) If the resulting text begins with the subj-fwd-hdr ABNF
and ends with the subj-fwd-trl ABNF, remove the
subj-fwd-hdr and subj-fwd-trl and repeat from step (2).
(7) The resulting text is the "base subject" used in the
SORT.
All servers and disconnected (as described in [IMAP-MODELS]) clients
MUST use exactly this algorithm to determine the "base subject".
Otherwise there is potential for a user to get inconsistent results
based on whether they are running in connected or disconnected mode.
2.2 Sent Date
As used in this document, the term "sent date" refers to the date and
time from the Date: header, adjusted by time zone to normalize to
UTC. For example, "31 Dec 2000 16:01:33 -0800" is equivalent to the
UTC date and time of "1 Jan 2001 00:01:33 +0000".
If the time zone is invalid, the date and time SHOULD be treated as
UTC. If the time is also invalid, the time SHOULD be treated as
00:00:00. If there is no valid date or time, the date and time
SHOULD be treated as 00:00:00 on the earliest possible date.
This differs from the date-related criteria in the SEARCH command
(described in [IMAP] section 6.4.4), which use just the date and not
the time, and are not adjusted by time zone.
If the sent date can not be determined (a Date: header is missing or
can not be parsed), the INTERNALDATE for that message is used as the
sent date.
When comparing two sent dates that match exactly, the order in which
the two messages appear in the mailbox (that is, by sequence number)
is used as a tie-breaker to determine the order.
3. Additional Commands
These commands are extension to the [IMAP] base protocol.
The section headings are intended to correspond with where they would
be located in the main document if they were part of the base
specification.
BASE.6.4.SORT. SORT Command
Arguments: sort program
charset specification
searching criteria (one or more)
Data: untagged responses: SORT
Result: OK - sort completed
NO - sort error: can't sort that charset or
criteria
BAD - command unknown or arguments invalid
The SORT command is a variant of SEARCH with sorting semantics for
the results. Sort has two arguments before the searching criteria
argument; a parenthesized list of sort criteria, and the searching
charset.
The charset argument is mandatory (unlike SEARCH) and indicates
the [CHARSET] of the strings that appear in the searching
criteria. The US-ASCII and UTF-8 charsets MUST be implemented.
All other charsets are optional.
There is also a UID SORT command which returns unique identifiers
instead of message sequence numbers. Note that there are separate
searching criteria for message sequence numbers and UIDs; thus the
arguments to UID SORT are interpreted the same as in SORT. This
is analogous to the behavior of UID SEARCH, as opposed to UID
COPY, UID FETCH, or UID STORE.
The SORT command first searches the mailbox for messages that
match the given searching criteria using the charset argument for
the interpretation of strings in the searching criteria. It then
returns the matching messages in an untagged SORT response, sorted
according to one or more sort criteria.
Sorting is in ascending order. Earlier dates sort before later
dates; smaller sizes sort before larger sizes; and strings are
sorted according to ascending values established by their
collation algorithm (see under "Internationalization
Considerations").
If two or more messages exactly match according to the sorting
criteria, these messages are sorted according to the order in
which they appear in the mailbox. In other words, there is an
implicit sort criterion of "sequence number".
When multiple sort criteria are specified, the result is sorted in
the priority order that the criteria appear. For example,
(SUBJECT DATE) will sort messages in order by their base subject
text; and for messages with the same base subject text will sort
by their sent date.
Untagged EXPUNGE responses are not permitted while the server is
responding to a SORT command, but are permitted during a UID SORT
command.
The defined sort criteria are as follows. Refer to the Formal
Syntax section for the precise syntactic definitions of the
arguments. If the associated RFC-822 header for a particular
criterion is absent, it is treated as the empty string. The empty
string always collates before non-empty strings.
ARRIVAL
Internal date and time of the message. This differs from the
ON criteria in SEARCH, which uses just the internal date.
CC
[IMAP] addr-mailbox of the first "cc" address.
DATE
Sent date and time, as described in section 2.2.
FROM
[IMAP] addr-mailbox of the first "From" address.
REVERSE
Followed by another sort criterion, has the effect of that
criterion but in reverse (descending) order.
Note: REVERSE only reverses a single criterion, and does not
affect the implicit "sequence number" sort criterion if all
other criteria are identicial. Consequently, a sort of
REVERSE SUBJECT is not the same as a reverse ordering of a
SUBJECT sort. This can be avoided by use of additional
criteria, e.g. SUBJECT DATE vs. REVERSE SUBJECT REVERSE
DATE. In general, however, it's better (and faster, if the
client has a "reverse current ordering" command) to reverse
the results in the client instead of issuing a new SORT.
SIZE
Size of the message in octets.
SUBJECT
Base subject text.
TO
[IMAP] addr-mailbox of the first "To" address.
Example: C: A282 SORT (SUBJECT) UTF-8 SINCE 1-Feb-1994
S: * SORT 2 84 882
S: A282 OK SORT completed
C: A283 SORT (SUBJECT REVERSE DATE) UTF-8 ALL
S: * SORT 5 3 4 1 2
S: A283 OK SORT completed
C: A284 SORT (SUBJECT) US-ASCII TEXT "not in mailbox"
S: * SORT
S: A284 OK SORT completed
BASE.6.4.THREAD. THREAD Command
Arguments: threading algorithm
charset specification
searching criteria (one or more)
Data: untagged responses: THREAD
Result: OK - thread completed
NO - thread error: can't thread that charset or
criteria
BAD - command unknown or arguments invalid
The THREAD command is a variant of SEARCH with threading semantics
for the results. Thread has two arguments before the searching
criteria argument; a threading algorithm, and the searching
charset.
The charset argument is mandatory (unlike SEARCH) and indicates
the [CHARSET] of the strings that appear in the searching
criteria. The US-ASCII and UTF-8 charsets MUST be implemented.
All other charsets are optional.
There is also a UID THREAD command which returns unique
identifiers instead of message sequence numbers. Note that there
are separate searching criteria for message sequence numbers and
UIDs; thus the arguments to UID THREAD are interpreted the same as
in THREAD. This is analogous to the behavior of UID SEARCH, as
opposed to UID COPY, UID FETCH, or UID STORE.
The THREAD command first searches the mailbox for messages that
match the given searching criteria using the charset argument for
the interpretation of strings in the searching criteria. It then
returns the matching messages in an untagged THREAD response,
threaded according to the specified threading algorithm.
All collation is in ascending order. Earlier dates collate before
later dates and strings are collated according to ascending values
established by their collation algorithm (see under
"Internationalization Considerations").
Untagged EXPUNGE responses are not permitted while the server is
responding to a THREAD command, but are permitted during a UID
THREAD command.
The defined threading algorithms are as follows:
ORDEREDSUBJECT
The ORDEREDSUBJECT threading algorithm is also referred to as
"poor man's threading." The searched messages are sorted by
base subject and then by the sent date. The messages are then
split into separate threads, with each thread containing
messages with the same base subject text. Finally, the threads
are sorted by the sent date of the first message in the thread.
The first message of each thread are siblings of each other
(the "root"). The second message of a thread is the child of
the first message, and subsequent messages of the thread are
siblings of the second message and hence children of the
message at the root. Hence, there are no grandchildren in
ORDEREDSUBJECT threading.
Children in ORDEREDSUBJECT threading do not have descendents.
Client implementations SHOULD treat descendents of a child in
a server response as being siblings of that child.
REFERENCES
The REFERENCES threading algorithm threads the searched
messages by grouping them together in parent/child
relationships based on which messages are replies to others.
The parent/child relationships are built using two methods:
reconstructing a message's ancestry using the references
contained within it; and checking the original (not base)
subject of a message to see if it is a reply to (or forward of)
another message.
Note: "Message ID" in the following description refers to a
normalized form of the msg-id in [RFC-2822]. The actual
text in an RFC 2822 may use quoting, resulting in multiple
ways of expressing the same Message ID. Implementations of
the REFERENCES threading algorithm MUST normalize any msg-id
in order to avoid false non-matches due to differences in
quoting.
For example, the msg-id
<"01KF8JCEOCBS0045PS"@xxx.yyy.com>
and the msg-id
<01KF8JCEOCBS0045PS@xxx.yyy.com>
MUST be interpreted as being the same Message ID.
The references used for reconstructing a message's ancestry are
found using the following rules:
If a message contains a References header line, then use the
Message IDs in the References header line as the references.
If a message does not contain a References header line, or
the References header line does not contain any valid
Message IDs, then use the first (if any) valid Message ID
found in the In-Reply-To header line as the only reference
(parent) for this message.
Note: Although [RFC-2822] permits multiple Message IDs in
the In-Reply-To header, in actual practice this
discipline has not been followed. For example,
In-Reply-To headers have been observed with message
addresses after the Message ID, and there are no good
heuristics for software to determine the difference.
This is not a problem with the References header however.
If a message does not contain an In-Reply-To header line, or
the In-Reply-To header line does not contain a valid Message
ID, then the message does not have any references (NIL).
A message is considered to be a reply or forward if the base
subject extraction rules, applied to the original subject,
remove any of the following: a subj-refwd, a "(fwd)"
subj-trailer, or a subj-fwd-hdr and subj-fwd-trl.
The REFERENCES algorithm is significantly more complex than
ORDEREDSUBJECT and consists of six main steps. These steps are
outlined in detail below.
(1) For each searched message:
(A) Using the Message IDs in the message's references, link
the corresponding messages (those whose Message-ID header
line contains the given reference Message ID) together as
parent/child. Make the first reference the parent of the
second (and the second a child of the first), the second the
parent of the third (and the third a child of the second),
etc. The following rules govern the creation of these
links:
If a message does not contain a Message-ID header line,
or the Message-ID header line does not contain a valid
Message ID, then assign a unique Message ID to this
message.
If two or more messages have the same Message ID, then
only use that Message ID in the first (lowest sequence
number) message, and assign a unique Message ID to each
of the subsequent messages with a duplicate of that
Message ID.
If no message can be found with a given Message ID,
create a dummy message with this ID. Use this dummy
message for all subsequent references to this ID.
If a message already has a parent, don't change the
existing link. This is done because the References
header line may have been truncated by a MUA. As a
result, there is no guarantee that the messages
corresponding to adjacent Message IDs in the References
header line are parent and child.
Do not create a parent/child link if creating that link
would introduce a loop. For example, before making
message A the parent of B, make sure that A is not a
descendent of B.
Note: Message ID comparisons are case-sensitive.
(B) Create a parent/child link between the last reference
(or NIL if there are no references) and the current message.
If the current message already has a parent, it is probably
the result of a truncated References header line, so break
the current parent/child link before creating the new
correct one. As in step 1.A, do not create the parent/child
link if creating that link would introduce a loop. Note
that if this message has no references, that it will now
have no parent.
Note: The parent/child links created in steps 1.A and 1.B
MUST be kept consistent with one another at ALL times.
(2) Gather together all of the messages that have no parents
and make them all children (siblings of one another) of a dummy
parent (the "root"). These messages constitute the first
(head) message of the threads created thus far.
(3) Prune dummy messages from the thread tree. Traverse each
thread under the root, and for each message:
If it is a dummy message with NO children, delete it.
If it is a dummy message with children, delete it, but
promote its children to the current level. In other words,
splice them in with the dummy's siblings.
Do not promote the children if doing so would make them
children of the root, unless there is only one child.
(4) Sort the messages under the root (top-level siblings only)
by sent date as described in section 2.2. In the case of a
dummy message, sort its children by sent date and then use the
first child for the top-level sort.
(5) Gather together messages under the root that have the same
base subject text.
(A) Create a table for associating base subjects with
messages, called the subject table.
(B) Populate the subject table with one message per each
base subject. For each child of the root:
(i) Find the subject of this thread, by using the base
subject from either the current message or its first
child if the current message is a dummy. This is the
thread subject.
(ii) If the thread subject is empty, skip this message.
(iii) Look up the message associated with the thread
subject in the subject table.
(iv) If there is no message in the subject table with the
thread subject, add the current message and the thread
subject to the subject table.
Otherwise, if the message in the subject table is not a
dummy, AND either of the following criteria are true:
The current message is a dummy, OR
The message in the subject table is a reply or forward
and the current message is not.
then replace the message in the subject table with the
current message.
(C) Merge threads with the same thread subject. For each
child of the root:
(i) Find the message's thread subject as in step 5.B.i
above.
(ii) If the thread subject is empty, skip this message.
(iii) Lookup the message associated with this thread
subject in the subject table.
(iv) If the message in the subject table is the current
message, skip this message.
Otherwise, merge the current message with the one in the
subject table using the following rules:
If both messages are dummies, append the current
message's children to the children of the message in
the subject table (the children of both messages
become siblings), and then delete the current message.
If the message in the subject table is a dummy and the
current message is not, make the current message a
child of the message in the subject table (a sibling
of its children).
If the current message is a reply or forward and the
message in the subject table is not, make the current
message a child of the message in the subject table (a
sibling of its children).
Otherwise, create a new dummy message and make both
the current message and the message in the subject
table children of the dummy. Then replace the message
in the subject table with the dummy message.
Note: Subject comparisons are case-insensitive, as
described under "Internationalization
Considerations."
(6) Traverse the messages under the root and sort each set of
siblings by sent date as described in section 2.2. Traverse
the messages in such a way that the "youngest" set of siblings
are sorted first, and the "oldest" set of siblings are sorted
last (grandchildren are sorted before children, etc). In the
case of a dummy message (which can only occur with top-level
siblings), use its first child for sorting.
Example: C: A283 THREAD ORDEREDSUBJECT UTF-8 SINCE 5-MAR-2000
S: * THREAD (166)(167)(168)(169)(172)(170)(171)
(173)(174 (175)(176)(178)(181)(180))(179)(177
(183)(182)(188)(184)(185)(186)(187)(189))(190)
(191)(192)(193)(194 195)(196 (197)(198))(199)
(200 202)(201)(203)(204)(205)(206 207)(208)
S: A283 OK THREAD completed
C: A284 THREAD ORDEREDSUBJECT US-ASCII TEXT "gewp"
S: * THREAD
S: A284 OK THREAD completed
C: A285 THREAD REFERENCES UTF-8 SINCE 5-MAR-2000
S: * THREAD (166)(167)(168)(169)(172)((170)(179))
(171)(173)((174)(175)(176)(178)(181)(180))
((177)(183)(182)(188 (184)(189))(185 186)(187))
(190)(191)(192)(193)((194)(195 196))(197 198)
(199)(200 202)(201)(203)(204)(205 206 207)(208)
S: A285 OK THREAD completed
Note: The line breaks in the first and third server
responses are for editorial clarity and do not appear in
real THREAD responses.
4. Additional Responses
These responses are extensions to the [IMAP] base protocol.
The section headings of these responses are intended to correspond
with where they would be located in the main document.
BASE.7.2.SORT. SORT Response
Data: zero or more numbers
The SORT response occurs as a result of a SORT or UID SORT
command. The number(s) refer to those messages that match the
search criteria. For SORT, these are message sequence numbers;
for UID SORT, these are unique identifiers. Each number is
delimited by a space.
Example: S: * SORT 2 3 6
BASE.7.2.THREAD. THREAD Response
Data: zero or more threads
The THREAD response occurs as a result of a THREAD or UID THREAD
command. It contains zero or more threads. A thread consists of
a parenthesized list of thread members.
Thread members consist of zero or more message numbers, delimited
by spaces, indicating successive parent and child. This continues
until the thread splits into multiple sub-threads, at which point
the thread nests into multiple sub-threads with the first member
of each subthread being siblings at this level. There is no limit
to the nesting of threads.
The messages numbers refer to those messages that match the search
criteria. For THREAD, these are message sequence numbers; for UID
THREAD, these are unique identifiers.
Example: S: * THREAD (2)(3 6 (4 23)(44 7 96))
The first thread consists only of message 2. The second thread
consists of the messages 3 (parent) and 6 (child), after which it
splits into two subthreads; the first of which contains messages 4
(child of 6, sibling of 44) and 23 (child of 4), and the second of
which contains messages 44 (child of 6, sibling of 4), 7 (child of
44), and 96 (child of 7). Since some later messages are parents
of earlier messages, the messages were probably moved from some
other mailbox at different times.
-- 2
-- 3
\-- 6
|-- 4
| \-- 23
|
\-- 44
\-- 7
\-- 96
Example: S: * THREAD ((3)(5))
In this example, 3 and 5 are siblings of a parent which does not
match the search criteria (and/or does not exist in the mailbox);
however they are members of the same thread.
5. Formal Syntax of SORT and THREAD Commands and Responses
The following syntax specification uses the Augmented Backus-Naur
Form (ABNF) notation as specified in [ABNF]. It also uses [ABNF]
rules defined in [IMAP].
sort = ["UID" SP] "SORT" SP sort-criteria SP search-criteria
sort-criteria = "(" sort-criterion *(SP sort-criterion) ")"
sort-criterion = ["REVERSE" SP] sort-key
sort-key = "ARRIVAL" / "CC" / "DATE" / "FROM" / "SIZE" /
"SUBJECT" / "TO"
thread = ["UID" SP] "THREAD" SP thread-alg SP search-criteria
thread-alg = "ORDEREDSUBJECT" / "REFERENCES" / thread-alg-ext
thread-alg-ext = atom
; New algorithms MUST be registered with IANA
search-criteria = charset 1*(SP search-key)
charset = atom / quoted
; CHARSET values MUST be registered with IANA
sort-data = "SORT" *(SP nz-number)
thread-data = "THREAD" [SP 1*thread-list]
thread-list = "(" (thread-members / thread-nested) ")"
thread-members = nz-number *(SP nz-number) [SP thread-nested]
thread-nested = 2*thread-list
The following syntax describes base subject extraction rules (2)-(6):
subject = *subj-leader [subj-middle] *subj-trailer
subj-refwd = ("re" / ("fw" ["d"])) *WSP [subj-blob] ":"
subj-blob = "[" *BLOBCHAR "]" *WSP
subj-fwd = subj-fwd-hdr subject subj-fwd-trl
subj-fwd-hdr = "[fwd:"
subj-fwd-trl = "]"
subj-leader = (*subj-blob subj-refwd) / WSP
subj-middle = *subj-blob (subj-base / subj-fwd)
; last subj-blob is subj-base if subj-base would
; otherwise be empty
subj-trailer = "(fwd)" / WSP
subj-base = NONWSP *(*WSP NONWSP)
; can be a subj-blob
BLOBCHAR = %x01-5a / %x5c / %x5e-ff
; any CHAR8 except '[' and ']'
NONWSP = %x01-08 / %x0a-1f / %x21-ff
; any CHAR8 other than WSP
6. Security Considerations
The SORT and THREAD extensions do not raise any security
considerations that are not present in the base [IMAP] protocol, and
these issues are discussed in [IMAP]. Nevertheless, it is important
to remember that [IMAP] protocol transactions, including message
data, are sent in the clear over the network unless protection from
snooping is negotiated, either by the use of STARTTLS, privacy
protection is negotiated in the AUTHENTICATE command, or some other
protection mechanism.
Although not a security consideration, it is important to recognize
that sorting by REFERENCES can lead to misleading threading trees.
For example, a message with false References: header data will cause
a thread to be incorporated into another thread.
The process of extracting the base subject may lead to incorrect
collation if the extracted data was significant text as opposed to
a subject artifact.
7. Internationalization Considerations
As stated in the introduction, the rules of I18NLEVEL=1 as described
in [IMAP-I18N] MUST be followed; that is, the SORT and THREAD
extensions MUST collate strings according to the i;unicode-casemap
collation described in [UNICASEMAP]. Servers SHOULD also advertise
the I18NLEVEL=1 extension. Alternatively, a server MAY implement
I18NLEVEL=2 (or higher) and comply with the rules of that level.
As discussed in [IMAP-I18N] section 4.5, all server implementations
should eventually be updated to support the [IMAP-I18N] I18NLEVEL=2
extension.
Translations of the "re" or "fw"/"fwd" tokens are not specified for
removal in the base subject extraction process. An attempt to add
such translated tokens would result in a geometrically complex, and
ultimately unimplementable, task.
Instead, note that [RFC-2822] section 3.6.5 recommends that "re:"
(from the Latin "res", in the matter of) be used to identify a reply.
Although it is evident that, from the multiple forms of token to
identify a forwarded message, there is considerable variation found
in the wild, the variations are (still) manageable. Consequently, it
is suggested that "re:" and one of the variations of the tokens for
forward supported by the base subject extraction rules be adopted for
Internet mail messages, since doing so makes it a simple display time
task to localize the token language for the user.
8. IANA Considerations
[IMAP] capabilities are registered by publishing a standards track or
IESG approved experimental RFC. This document constitutes
registration of the SORT and THREAD capabilities in the [IMAP]
capabilities registry.
This document creates a new [IMAP] threading algorithms registry,
which registers threading algorithms by publishing a standards track
or IESG approved experimental RFC. This document constitutes
registration of the ORDEREDSUBJECT and REFERENCES algorithms in that
registry.
9. Normative References
The following documents are normative to this document:
[ABNF] Crocker, D. and Overell, P. "Augmented BNF
for Syntax Specifications: ABNF", RFC 5234
January 2008
[CHARSET] Freed, N. and Postel, J. "IANA Character Set
Registration Procedures", RFC 2978, October
2000.
[IMAP] Crispin, M. "Internet Message Access Protocol -
Version 4rev1", RFC 3501, March 2003.
[IMAP-I18N] Newman, C. and Gulbrandsen, A. "Internet
Message Access Protocol Internationalization",
Work in Progress.
[KEYWORDS] Bradner, S. "Key words for use in RFCs to
Indicate Requirement Levels", BCP 14, RFC 2119,
March 1997.
[RFC-2822] Resnick, P. "Internet Message Format", RFC
2822, April 2001.
[UNICASEMAP] Crispin, M. "i;unicode-casemap - Simple Unicode
Collation Algorithm", RFC 5051.
10. Informative References
The following documents are informative to this document:
[IMAP-MODELS] Crispin, M. "Distributed Electronic Mail Models
in IMAP4", RFC 1733, December 1994.
[THREADING] Zawinski, J. "Message Threading",
http://www.jwz.org/doc/threading.html,
1997-2002.
Appendices
Author's Address
Mark R. Crispin
Networks and Distributed Computing
University of Washington
4545 15th Avenue NE
Seattle, WA 98105-4527
Phone: +1 (206) 543-5762
EMail: MRC@CAC.Washington.EDU
Kenneth Murchison
Carnegie Mellon University
5000 Forbes Avenue
Cyert Hall 285
Pittsburgh, PA 15213
Phone: +1 (412) 268-2638
Email: murch@andrew.cmu.edu
Full Copyright Statement
Copyright (C) The IETF Trust (2008).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at ietf-
ipr@ietf.org.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.

189
docs/drivers.txt Normal file
View File

@ -0,0 +1,189 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
c-client Driver Characteristics
Mark Crispin
11 December 2006
Drivers are code modules that support different mailbox storage
technologies. A mailbox storage technology may be implemented by
1) files and directories on the local system
2) a database
3) a network protocol.
In the case of files and directories on the local system, a
driver supports a particular mailbox format. Mailbox formats are
discussed in more detail in the file formats.txt.
As of the date this document was written, there was no bundled
support for any databases in c-client. However, it should not be
particularly difficult to write a driver that communicates with a
database.
Network protocols supported by c-client drivers are the Internet
Mail Access Protocol (all versions: IMAP4rev1, IMAP4, IMAP2bis, and
IMAP2); the Post Office Protocol (version 3); and the Network News
Transport Protocol (NNTP). In addition, c-client also supports NNTP
and the Simple Mail Transport Protocol (SMTP) for mailbox transport.
By default, all drivers are enabled. There is little benefit to
be gained by disabling a driver, with one exception. The mbox driver
implements the behavior of automatically moving new mail from the
spool directory to the "mbox" file on the user's home directory, if
and *only* if the "mbox" exists and is in mailbox format. The mbox
driver is listed under EXTRADRIVERS; if you wish to disable it just
remove it from that list and rebuild.
I. Special name "INBOX"
The following rules to select INBOX and its format apply in
the order given if "black box mode" is not in effect:
1) mbox format is selected if file ~/mbox exists, and is in unix
format or is zero-length.
2) mx format is selected if file ~/INBOX/.mxindex exists.
3) mbx format is selected if file ~/INBOX exists and is in mbx format.
4) tenex format is selected if:
a) file ~/mail.txt exists, and is in tenex format or is zero-length.
b) file ~/INBOX exists and is in tenex format.
5) mtx format is selected if:
a) file ~/INBOX.MTX exists, and is in mtx format or is zero-length.
b) file ~/INBOX exists and is in mtx format.
6) mmdf format is selected if the spool directory file exists and is
in mmdf format.
7) unix format is selected if the spool directory file exists and is
in unix format.
8) the dummy driver is selected if the spool directory file does not
exist, or exists and is empty.
If "black box mode" is not in effect, messages are automatically
transferred ("snarfed") from the spool directory to an INBOX in mbox,
mx, mbx, tenex, and mtx formats.
The following rules to select INBOX and its format apply in the order
given if "black box mode" is in effect:
1) mx format is selected if file ~/INBOX/.mxindex exists.
2) mbx format is selected if file ~/INBOX exists and is in mbx format.
3) tenex format is selected if file ~/INBOX exists and is in tenex format.
4) mtx format is selected if file ~/INBOX exists and is in mtx format.
5) mmdf format is selected if file ~/INBOX exists and is in mmdf format.
6) unix format is selected if file ~/INBOX exists and is in unix format.
7) the dummy driver is selected if ~/INBOX does not exist, or exists
and is empty.
II. Special Name #mhinbox
#mhinbox always refers to the directory "inbox" in the MH path, which
is declared in the ~/.mh_profile file. Messages are automatically
transferred from the spool directory to #mhinbox mailbox.
III. Special Prefix "#mh/"
Any name prefixed with "#mh/" always refers to a directory in the MH
path, which is declared in the ~/.mh_profile file. For example, the name
"#mh/foo" refers to directory "foo" in the MH path.
IV. Special prefix "#news."
Any name prefixed with "#news" always refers to a newsgroup. For
example, the name "#news.comp.mail.misc" refers to newsgroup
"comp.mail.misc".
V. All Other Names
The driver is selected by generating a file name from the mailbox
name, and then examining the data of the object with the resulting
name. The formats are checked in order: mx, mbx, tenex, mtx, mmdf,
unix, and phile. The dummy driver is selected if the file is empty.
The file name is generated according to certain rules, based upon the
prefix of the mailbox name. On UNIX, the following rules apply:
Prefix Interpretation of Suffix
------ ------------------------
/ [black box] preceeds a user name; "/foo/bar" means
"black box user foo's mailbox bar"
[not black box] preceeds an absolute path name.
~ [not black box] preceeds a user name; "~foo/bar" means
"UNIX user foo's mailbox bar"
#ftp/ preceeds UNIX user ftp's mailbox name
#public/ preceeds UNIX user imappublic's mailbox name
#shared/ preceeds UNIX user imapshared's mailbox name
All other names are interpreted in the context of the UNIX user's home
directory (not black box), the black box user's black box directory
(black box), or UNIX user ftp's home directory (anonymous).
The strings "..", "//", and /~ are forbidden in names in:
black box mode
#ftp, #public, or #shared names
anonymous users
Anonymous users may only access:
INBOX (belonging to UNIX user ftp)
files in or below UNIX user ftp's home directory
#ftp, #news, and #public namespace
VI. Driver Comparison
The following information about the local file drivers is an
elaboration of a table compiled by Osma Ahvenlampi.
Driver CA CE UID Kwd Sub NFS Performance Layout
------ -- -- --- --- --- --- ----------- ------
unix no no yes yes no limited fair file
;;; traditional UNIX format
mbox no no yes yes no limited fair file
;;; traditional UNIX format, INBOX only, using ~/mbox with automatic
;;; moving from the mail spool directory.
mmdf no no yes yes no limited fair file
;;; default on SCO systems
mbx yes yes yes yes no no very good prefile
;;; best performing local file driver; preferred format at UW
tenex yes no no limited no no good prefile
;;; compatible with UNIX MM
mtx yes no no limited no no very good prefile
;;; PC Pine standard format; compatible with TOPS-20; identical to tenex
;;; but instead CRLF newlines instead of LF
mx yes buggy yes yes yes no poor ixdir
;;; fullest function; *not* recommended due to performance problems and bugs;
;;; to be redesigned/rewritten
mh yes no no no yes yes very poor dir
;;; compatible with mh; #mhinbox for INBOX, #mh/ prefix for all other names
news yes no yes no yes yes very poor ixdir
;;; local news spool access; #news. prefix for all names
phile no no no no no yes good file
;;; reads arbitrary file as a single readonly message
IMPORTANT: the "performance" ratings are relative to other drivers,
and not necessarily to other software which implements those formats.
They relate to the driver's performance in typical operations such as
an IMAP "FETCH ALL".
Key to headings:
CA: concurrent read/write access
CE: expunge permitted in concurrent read/write access
UID: sticky UIDs
Kwd: keyword flags
Sub: subfolders
NFS: usable over network filesystems (NFS, AFS, etc.)
Layout: file - single file
prefile - file with preallocated space for state
dir - directory, messages are files
ixdir - directory, messages are files, with helper index
In addition, drivers imap, nntp, and pop3 support IMAP4rev1, NNTP, and
POP3 protocols respectively.

217
docs/formats.txt Normal file
View File

@ -0,0 +1,217 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
Mailbox Format Characteristics
Mark Crispin
11 December 2006
When a mailbox storage technology uses local files and
directories directly, the file(s) and directories are layed out in a
mailbox format.
I. Flat-File Formats
In these formats, a mailbox and all the messages inside are a
single file on the filesystem. The mailbox name is the name of the
file in the filesystem, relative to the user's "mail home directory."
A flat-file format mailbox is always a file, never a directory.
This means that it is impossible to have a flat-file format mailbox
that has inferior mailbox names under it (so-called "dual-usage"
mailboxes). For some inexplicable reason, some people want this.
The mail home directory is usually the same as the user login
home directory if that concept is meaningful; otherwise, it is some
other default directory (e.g. "C:\My Documents" on Windows 98). This
can be redefined by modifying the c-client source code or in an
application via the SET_HOMEDIR mail_parameters() call.
For example, a mailbox named "project" is likely to be found in
the file "project" in the user's home directory. Similarly, a mailbox
named "test/trial1" (assuming a UNIX system) is likely to be found in
the file "trial1" in the subdirectory "test" in the user's home
directory.
Note that the name "INBOX" has special semantics and rules, as
described in the file naming.txt.
The following flat-file formats are supported by c-client as of
the time of this writing:
. unix This is the traditional UNIX mailbox format, in use for nearly
30 years. It uses a line starting with "From " to indicate
start of message, and stores the message status inside the
RFC822 message header.
unix is not particularly efficient; the entire mailbox file
must be read when the mailbox is open, and when reading message
texts it is necessary to convert the newline convention to
Internet standard CR LF form. unix preserves UIDs, and allows
the creation of keywords.
Only one process may have a unix-format mailbox open
read/write at a time.
. mmdf This is the format used by the MMDF mailer. It uses a line
consisting of 4 <CTRL/A> (0x01) characters to indicate start
and end of message. Optionally, there may also be a unix
format "From " line. It otherwise has the same
characteristics as unix format.
. mbx This is the current preferred mailbox format. It can be
handled quite efficiently by c-client, without the problems
that exist with unix and mmdf formats. Messages are stored
in Internet standard CR LF format.
mbx permits shared access, including shared expunge. It
preserves UIDs, and allows the creation of keywords.
. mtx This is supported for compatibility with the past. This is
the old Tenex/TOPS-20 mail.txt format. It can be handled
quite efficiently by c-client, and has most of the
characteristics of mbx format.
mtx is deficient in that it does not support shared expunge;
it has no means to store UIDs; and it has no way to define
keywords except through an external configuration file.
. tenex This is supported for compatibility with the past. This is
the old Columbia MM format. This is similar to mtx format,
only it uses UNIX-style bare-LF newlines instead of CR LF
newlines, thus incurring a performance penalty for newline
conversion.
. phile This is not strictly a format. Any file which is not in a
recognized format is in phile format, which treats the entire
contents of the file as a single message.
II. File/Message Formats
In these formats, a mailbox is a directory, and each the messages
inside are separate files inside the directory. The file names of
these files are generally the text form of a number, which also
matches the UID of the message.
In the case of mx, the mailbox name is the name of the directory
in the filesystem, relative to the user's "mail home directory." In
the case of news and mh, the mailbox name is in a separate namespace
as described in the file naming.txt.
A file/message format mailbox is always a directory. This means
that it is possible to have a file/message format mailbox that has
inferior mailbox names under it (so-called "dual-usage" mailboxes).
For some inexplicable reason, some people want this.
Note that the name "INBOX" has special semantics and rules, as
described in the file naming.txt.
The following file/message formats are supported by c-client as of
the time of this writing:
. mx This is an experimental format, and may be removed in a future
release. An mx format mailbox has a .mxindex file which holds
the message status and unique identifiers. Messages are
stored in Internet standard CF LF form, so the file size of
the message file equals the size of the message.
mx is somewhat inefficient; the entire directory must be read
and each file stat()'d. We found it intolerable for a
moderate sized mailbox (2000 messages) and have more or less
abandoned it.
. mh This is supported for compatibility with the past. This is
the format used by the old mh program.
mh is very inefficient; the entire directory must be read
and each file stat()'d, and in order to determine the size
of a message, the entire file must be read and newline
conversion performed.
mh is deficient in that it does not support any permanent
flags or keywords; and has no means to store UIDs (because
the mh "compress" command renames all the files, that's
why).
. news This is an export of the local filesystem's news spool, e.g.
/var/spool/news. Access to mailboxes in news format is read
only; however, message "deleted" status is preserved in a
.newsrc file in the user's home directory. There is no other
status or keywords.
news is very inefficient; the entire directory must be
read and each file stat()'d, and in order to determine the
size of a message, the entire file must be read and newline
conversion performed.
news is deficient in that it does not support permanent flags
other than deleted; does not support keywords; and has no
expunge.
Soapbox on File/Message Formats
If it sounds from the above descriptions that we're not putting
too much effort into file/message formats, you are correct.
There's a general reason why file/message formats are a bad idea.
Just about every filesystem in existance serializes file creation and
deletions because these manipulate the free space map. This turns out
to be an enormous problem when you start creating/deleting more than a
few messages per second; you spend all your time thrashing in the
filesystem.
It is also extremely slow to do a text search through a
file/message format mailbox. All of those open()s and close()s really
add up to major filesystem thrashing.
What about Cyrus and Maildir?
Both formats are vulnerable to the filesystem thrashing outlined
above.
The Cyrus format used by CMU's Cyrus server (and Esys' server)
has a special associated flat file in each directory that contains
extensive data (including pre-parsed ENVELOPEs and BODYSTRUCTUREs)
about the messages. Put another way, it's a (considerably) more
featureful form of mx. It also uses certain operating system
facilities (e.g. file/memory mapping) which are not available on older
systems, at a cost of much more limited portability than c-client.
These considerably ameliorate the fundamental problems with
file/message formats; in fact, Cyrus is halfway to being a database.
Rather than support Cyrus format in c-client, you should run Cyrus or
Esys if you want that format.
The Maildir format used by qmail has all of the performance
disadvantages of mh noted above, with the additional problem that the
files are renamed in order to change their status so you end up having
to rescan the directory frequently to locate the current names
(particularly in a shared mailbox scenario). It doesn't scale, and it
represents a support nightmare; it is therefore not supported in the
official distribution. Maildir support code for c-client is available
from third parties; but, if you use it, it is entirely at your own
risk (read: don't complain about how poorly it performs or bugs).
So what does this all mean?
A database (such as used by Exchange) is really a much better
approach if you want to move away from flat files. mx and especially
Cyrus take a tenative step in that direction; mx failed mostly because
it didn't go anywhere near far enough. Cyrus goes much further, and
scores remarkable benefits from doing so.
However, a well-designed pure database without the overhead of
separate files would do even better.

613
docs/imaprc.txt Normal file
View File

@ -0,0 +1,613 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
.imaprc secrets revealed!
Mark Crispin, June 17, 2002
The following information describes the format of the /etc/c-client.cf
and ~/.imaprc file. The Columbia MM ~/.mminit file is also read by
c-client; however, the only command that ~/.mminit has in common is
set keywords.
**********************************************************************
* DANGER! BEWARE! TAKE CARE! *
**********************************************************************
* *
* These files, and this documentation, are for internal UW usage *
* only. This capability is for UW experimental tinkering, and most *
* emphatically *not* for sorcerer's apprentices at other sites who *
* feel that if a config file capability exists, they must write a *
* config file whether or not there is any need for one. *
* *
* This information is subject to change without notice. Commands *
* may be added, removed, or altered. The behavior of comamnds may *
* change. Do not use any of this information without consulting me *
* first. c-client's defaults have been carefully chosen to be right *
* for general-purpose and most special-purpose configurations. If *
* you tinker with these defaults, all hell may break loose. *
* *
* This is not an idle threat. There have been several instances of *
* people who ignored these warnings and have gotten burned. *
* *
* Don't even trust this file to work. Many of the things which can *
* be changed by this file can also be changed by the application, *
* and it is totally unpredictable which will take precedence. It *
* all depends upon how the application is coded. Not only that, you *
* may cause the application to crash. *
* *
* In other words, keep your cotton-pickin' hands off my defaults. *
* If it crashes and erases your mail, I don't want to hear about it. *
* Consider 'em ``mandatory defaults''. Got a nice ring, eh? :-) If *
* you must tinker with defaults, play with the .pinerc and pine.conf *
* files in Pine. It's got options galore, all supported for you to *
* have fun. They're also documented; so well documented, it takes *
* two strong men to carry around all the documentation. ;-) ;-) *
* *
* Joking aside, you really shouldn't be fooling around with this *
* capability. It's dangerous, and you can shoot yourself in the *
* foot easily. If you need custom changes, you are better off with *
* local source code modifications. Seriously. *
* *
* One last warning: don't believe anything that you read in this *
* document. Every effort has been made to ensure that this document *
* is incomplete and inaccurate, and I take no responsibility for any *
* glimmers of correct information that may, by some fluke, be here. *
* *
**********************************************************************
The files are read in order: /etc/c-client.cf, ~/.mminit, ~/.imaprc,
and an entry in a later file overrides the setting of an earlier file
except as noted below. This ordering and overriding behavior may
change without notice.
Almost all of these facilities can also be set via the mail_parameters()
call in the program. Whether the file overrides mail_parameters(), or
mail_parameters() overrides the file, is indeterminate. It will vary
from program to program, and it may be one way in one version and the
other way in the next version. It's completely unpredictable, and so
anything you do with these files has to be in complete knowledge of what
the version of each program you're running is going to do. This is
because the files do something for testing, but the real capability for
configurability is put in the program instead. Are you getting the
feeling that you shouldn't be messing with these files yet?
The very first line of the file MUST start with the exact string "I
accept the risk". This ensures that you have checked the file for
correctness against this version of the IMAP toolkit. This enable
string may change without notice in future versions, and the new
string may or may not be accurately described in an updated version of
this file. So any time you install software that uses the IMAP
toolkit, you need to check the new version against these files (if you
have insisted upon creating them in spite of all warnings). If two
pieces of software use different versions of the IMAP toolkit with
incompatible requirements, one of them won't work. Re-read the
warning above about why you should not use these files.
Subsequent lines are read from the file one at a time. Case does not
matter. Unrecognized commands are ignored.
1) set new-folder-format
sets what format new mailboxes are created in. This also controls
default delivery via tmail and dmail.
a) set new-folder-format same-as-inbox
Folder is created using the same mailbox format as INBOX. If
INBOX is empty, it defaults to system standard.
b) set new-folder-format system-standard
This is the default. Folder is created using the wired-in system
standard format, which on most UNIX systems is ordinary UNIX
/bin/mail format. On SCO systems, this is MMDF.
c) set new-folder-format <driver name>
Folder is created using the given driver name, e.g. mbx, unix,
mmdf, etc.
There is no protection against setting this to a silly value (e.g.
news, nntp, dummy) and doing so is a great way to screw things up.
Setting this to mh does not do what you think it does. Setting this
to tenex or mtx isn't particularly useful.
2) set empty-folder-format
sets what format data is written into an empty mailbox file using
mail_copy() or mail_append(). This also controls default delivery
via tmail.
a) set empty-folder-format same-as-inbox
Data is written using the same mailbox format as INBOX. If
INBOX is empty, it defaults to system standard.
b) set empty-folder-format system-standard
This is the default. Data is written using the wired-in system
standard format, which on most UNIX systems is ordinary UNIX
/bin/mail format. On SCO systems, this is MMDF.
c) set-empty-folder-format <driver name>
Data is written using the given driver name, e.g. tenex, unix,
mmdf, etc.
There is no protection against setting this to a silly value (e.g.
news, nntp, dummy) and doing so is a great way to screw things up.
Setting this to mh, mbx, or mx does not work.
3) set keywords <word1>, <word2>, ... <wordn>
Sets the list of keyword flags (supported by tenex and mtx) to the
given list. Up to 30 flags may be given. Since these names
correspond to numeric bits, the order of the keywords can not be
changed, nor can keywords be removed or inserted (you can append
new keywords, up to the limit of 30).
Set keywords is a deprecated command. It may not appear in
future versions, or it may appear in a changed form. It exists
only for compatibility with MM, and should only appear in ~/.mminit
and not in the other files. It is likely to disappear entirely in
IMAP4.
There is no protection against setting these to silly values, and
doing so is a great way to cause a crash.
4) set from-widget header-only
Sets smart insertion of the > character in front of lines that
begin with ``From ''. Only such lines that are also in UNIX mbox
header file format will have a > character inserted. The default
is to insert the > character in front of all lines which begin with
``From '', for the benefit of legacy tools that get confused
otherwise.
5) set black-box-directory <directory name>
Sets the directory in which the user's data can be found. A user's
folders can be found in a subdirectory of the black box directory
named with the user's username. For example, if the blackbox
directory is /usr/spool/folders/, user jones' data can be found
in /usr/spool/folders/jones/. The user's black-box directory is
the location of folders, .mminit, .imaprc, .newsrc, and all other
files used by c-client; internally, it sets c-client's idea of the
user's ``home directory'', overriding /etc/passwd.
This command may not appear in ~/.mminit or ~/.imaprc
In black-box mode, it is not permitted to access any folders
outside of the user's personal blackbox directory. The breakouts
``/'', ``~'', and ``..'' are not permitted.
In order to make this work without crashing, you must set another
option which is not listed in this document.
There is no protection against setting this to a silly value, and
doing so is a great way to cause a crash.
6) set local-host <host name>
Sets c-client's idea of the local host name.
There is no protection against setting this to a silly value, and
doing so is a great way to cause a crash.
7) set news-active-file <file name>
Sets the location of the news active file, if it is not in the
standard place.
It is recommended to use a courtesy symbolic link instead.
There is no protection against setting this to a silly value, and
doing so is a great way to cause a crash.
8) set news-spool-directory <directory name>
Sets the location of the news spool, if it is not in the standard
place.
It is recommended to use a courtesy symbolic link instead.
There is no protection against setting this to a silly value, and
doing so is a great way to cause a crash.
9) set news-state-file <file name>
Sets the location of the news state file (normally $(USER)/.newsrc).
This is not very useful in /etc/c-client.cf because it is a file name.
Setting this in /etc/c-client.cf would set all users to the same file
as their newsrc, which is probably not what you want.
There is no protection against setting this to a silly value, and
doing so is a great way to cause a crash.
10) set system-inbox <file name>
Sets the location of the "system inbox", if it is not in the standard
place. This is the default location of INBOX, or the mail drop point
from which mail is snarfed (e.g. in tenex, mtx, mbox, mh formats).
This is not very useful in /etc/c-client.cf because it is a file name.
Setting this in /etc/c-client.cf would set all users to the same file
as their system inbox, which is probably not what you want.
There is no protection against setting this to a silly value, and
doing so is a great way to cause a crash.
11) set tcp-open-timeout <number>
Sets the number of seconds that the TCP routines will block on opening
a TCP connection before timing out. If a timeout occurs, the connection
attempt is aborted.
The default is zero, meaning use the operating system default (75
seconds on most UNIX systems).
There is no protection against setting this to an excessively small
value, such as 1, and doing so is a great way to cause users extreme
grief.
12) set tcp-read-timeout <number>
Sets the number of seconds that the TCP routines will block on reading
data before calling the timeout routine. If no timeout routine is set
by the program, the connection will be aborted on a timeout.
The default is zero, meaning infinite.
There is no protection against setting this to an excessively small
value, such as 1, and doing so is a great way to cause users extreme
grief.
13) set tcp-write-timeout <number>
Sets the number of seconds that the TCP routines will block on sending
data before calling the timeout routine. If no timeout routine is set
by the program, the connection will be aborted on a timeout.
The default is zero, meaning infinite.
There is no protection against setting this to an excessively small
value, such as 1, and doing so is a great way to cause users extreme
grief.
14) set rsh-timeout <number>
Sets the number of seconds that the rsh routines will block on opening
an rimapd connection before timing out. If a timeout occurs, the
rsh connection attempt is aborted. A zero timeout will disable rsh.
The default is 15 seconds.
There is no protection against setting this to an excessively small
value, such as 1, and doing so is a great way to cause users extreme
grief.
15) set maximum-login-trials <number>
Sets the number of iterations of asking the user, via mm_login(), for
a user name and password, before cancelling the attempt.
The default is 3.
There is no protection against setting this to zero, and doing so is
a great way to cause users extreme grief.
16) set lookahead <number>
Sets the number of envelopes that are looked ahead in IMAP, in
mail_fetchstructure(). This is based on the guess that in such
operations as drawing browser lines, if you get data for message n
you are likely to want it for message n+1, n+2,... in short order.
Lookahead preloads the c-client cache and saves unnecessary RTTs.
The default is 20, a good number for a browser on a 24x80 screen, and
small enough to usually have no significant real-time difference from
a single message fetch.
Setting it to 0 turns off lookahead.
There is no protection against setting this ridiculously high and
incurring performance penalties as a result.
17) set prefetch <number>
Sets the number of envelops which are automatically fetched for the
messages which match in a search. This is based on the guess that
in a browser that is "zoomed" on the results of a search, you are
likely to want the envelope data for each of those messages in
short order. Prefetching reloads the c-client cache, saves
unnecessary RTTs, and avoids loading undesired envelopes due to
lookahead (see above).
The default is 20.
Setting it to 0 turns off prefetch.
There is no protection against setting this ridiculously high and
incurring performance penalties as a result.
18) set close-on-error <number>
If non-zero, IMAP connections are closed if an EXAMINE or SELECT
command fails. Otherwise, they are left half-open, and can be used
again to select some other mailbox. The mailbox name in the stream
is set to {serverhost}<no_mailbox>
The default is zero (do not close on error).
19) set imap-port <number>
Set the TCP/IP contact port to use for IMAP. This overrides the
wired-in setting and the setting from /etc/services, and can in
turn be overridden by an explicit user specification in the mailbox
name, e.g. {serverhost:143}foo
The default is zero (use setting from /etc/services or the wired-in
setting (143).
There is no protection against setting this to a silly value, and
doing so is a great way to cause users extreme grief.
20) set pop3-port <number>
Set the TCP/IP contact port to use for POP3. This overrides the
wired-in setting and the setting from /etc/services, and can in
turn be overridden by an explicit user specification in the mailbox
name, e.g. {serverhost:110/pop3}
The default is zero (use setting from /etc/services or the wired-in
setting (110).
There is no protection against setting this to a silly value, and
doing so is a great way to cause users extreme grief.
21) set uid-lookahead <number>
Sets the number of UIDs that are looked ahead in IMAP in mail_uid().
Lookahead preloads the c-client cache and saves unnecessary RTTs.
The default is 1000, small enough to usually have no significant
real-time difference from a single message UID fetch.
Setting it to 0 turns off lookahead.
There is no protection against setting this ridiculously high and
incurring performance penalties as a result.
22) set mailbox-protection <number>
Set the default protection for newly-created mailbox files.
The default is 384.
There is no protection against setting this to a silly value, and
doing so is a great way to screw things up massively.
23) set directory-protection <number>
Set the default protection for newly-created directories.
The default is 448.
There is no protection against setting this to a silly value, and
doing so is a great way to screw things up massively.
24) set lock-protection <number>
Set the default protection for lock files
The default is 438, which is necessary if locks are to be respected
by processes running as other UIDs.
There is no protection against setting this to a silly value, and
contrary to what you may think just about any value other than 438
turns out to be a silly value.
25) set disable-fcntl-locking <number>
This only applies to SVR4 systems.
If non-zero, fnctl() locking is not attempted. In the past, this
was used to avoid locking NFS files. If NFS is involved, the evil
lockd/statd daemons get invoked. These daemons supposedly work over
NFS, but really don't.
You probably don't really want to do this, though, because now the
flock() emulator (which calls fcntl()) now checks to see if the file
is accessed via NFS and no-ops the lock. This is compatible with
BSD.
Disabling fcntl() locking loses a great deal of locking protection
on local files as well as NFS files (which now never have locking
protection).
The default is zero (fcntl() locking is enabled).
26) set lock-EACCES-error <number>
If non-zero, a warning message is given if an attempt to create a
lock file fails. Otherwise, EACCES is treated as a "silent failure",
and it proceeds without trying to use the lock file. This is for
the benefit of users on systems with paranoid /usr/spool/mail
protections which don't let users create /usr/spool/mail/$(USER).lock
files; these unfortunate users would be harassed with a flood of
error messages otherwise. The problem is that on SVR4, if EACCES
remains disabled and fcntl() locking is also disabled, then there is
no locking at all which is doubleplus-ungood.
If the site is paranoid on /usr/spool/mail protections AND if there
is no fcntl() locking (SVR4) or usable flock() locking (e.g. NFS),
then there is no way to win. Find a different system to use.
The default is non-zero (report EACCESS as an error).
27) set list-maximum-level <number>
Sets the maximum depth of recursion that a * wildcard list will go
down the directory tree. 0 means that no recursion is permitted,
and * becomes like %.
The default is 20.
There is no protection against setting this to a ridiculously high
value. Since LIST will follow symbolic links, it can effectively
recurse infinitely, until the name strings get large enough that
some name limit is exceeded.
28) set anonymous-home-directory <directory name>
Sets the location of the anonymous home directory, if it is not in
the standard place.
It is recommended to use a courtesy symbolic link instead.
There is no protection against setting this to a silly value, and
doing so is a great way to cause a crash.
29) set chroot-server <number>
This option is for closed server systems only. If defined, a chroot()
call to the user's home directory is done as part of the login
process. This has the effect of preventing access to any files
outside of the user's home directory (including shared mailboxes).
Shared mailboxes with other users can't possibly work with this
option, because there is no way to export lock information to other
users.
This should be done ONLY on systems which do not permit users to
have shell access
This option should NEVER(!!) be set if users are allowed shell access.
Doing so actually makes the system *less* secure, since the user could
create an etc subdirectory which would be treated as real /etc by such
programs as /bin/su.
The default is zero (don't do chroot).
This option is strongly *NOT* recommended.
30) set disable-automatic-shared-namespaces <number>
Never look up the "ftp", "imappublic", and "imapshared" users as
posssible home directories for the #ftp, #public, and #shared
namespaces. On some systems (reportedly including AIX 4.3.3)
getpwnam() of an unknown user name is horrendously slow.
Note that this does not remove the #ftp, #public, and #shared
namespaces, and they can still be set up by other means.
The default is zero (shared namespaces are automatic).
31) set advertise-the-world <number>
Include the UNIX root as a shared namespace. This is generally a bad
idea, since certain IMAP clients (names withheld to protect the guilty)
will take this as license to download the entire filesystem tree.
The default is zero (don't advertise the world).
32) set mail-subdirectory <subdirectory name>
Change the default connected directory from the user's home directory
to the named subdirectory of the user's home directory. For example,
setting MAILSUBDIR="mail" will cause the POP2 and IMAP servers to
connect to the user's ~/mail subdirectory. This is equivalent to
the env_unix.c edit described in Example 2 of the CONFIG file.
Note that if the subdirectory does not exist, the result is undefined.
It is probably an extremely bad idea to set this unless you can
guarantee that the subdirectory exists for all users. If you can not
guarantee this, then you should leave the default as the user's home
directory and allow them to configure a personal default in their IMAP
client.
The default is not to use any subdirectory.
33) set allow-user-config <number>
Allow users to use ~/.imaprc and ~/.mminit files.
The default is zero (don't allow user config files).
34) set allow-reverse-dns <number>
By default, the servers (ipop[23]d and imapd) will do gethostbyaddr()
on the local and remote sockets so that imapd can identify itself
properly (this is important when the same CPU hosts multiple virtual
hosts on different IP addresss) and also includes the client's name
when it writes to the syslog. There are also client gethostbyaddr()
calls, used primarily by authentication mechanisms.
Setting this option to zero disables all gethostbyaddr() calls. The
returned "host name" string for the socket is just the bracketed
[12.34.56.78] form, as if the reverse DNS lookup failed.
WARNING: Some authentication mechanisms, e.g. Kerberos V, depend upon
the host names being right, and if you set this option, it won't work.
You should only do this if you are encountering server performance
problems due to a misconfigured DNS, e.g. long startup delays or
client timeouts.
The default is non-zero (allow reverse DNS).
35) set disable-plaintext <number>
Disable plaintext password authentication (LOGIN command, AUTH=LOGIN,
and AUTH=PLAIN).
The default is zero (allow plaintext authentication).
36) set trust-dns <number>
By default, host names are canonicalized via gethostbyname() for
everything except for SSL certificate validation.
This can represent a security bug due to DNS spoofing, but is more
likely to deliver results that users expect. It also may be necessary
for SASL authentication to work right (e.g. generating a correct name
for a Kerberos service principal) if the name entered by the user is a
CNAME or not a fully-qualified domain name.
If trust-dns is set to zero, no host name canonicalization is done.
The user's actual entered name is used for SASL authentication and
will appear in the mailbox name of the open stream.
The default is non-zero (do DNS canonicalization).
37) set sasl-uses-ptr-name <number>
By default, if trust-dns is set, the host names used in authentication
(e.g. to generate a Kerberos service principal) are canonicalized via
gethostbyaddr() instead of by gethostbyname(). If gethostbyaddr()
fails the gethostbyname() canonicalization is used.
This represents an additional security bug due to DNS spoofing, over and
above trust-dns. It also adds an additional DNS query to starting a
session.
It is necessary for sites which implement a server cluster with multiple
A records for a cluster name (instead of a CNAME) but each cluster
member has a unique PTR record which it expects for a Kerberos service
principal.
If sasl-uses-ptr-name is set to zero and trust-dns is set non-zero, the
gethostbyname() canonicalized name is used for SASL authentication.
The setting of sasl-uses-ptr-name is irrelevant if trust-dns is set to
zero.
The default is non-zero (use name from PTR record for SASL).
38) set network-filesystem-stat-bug <number>
By default, traditional UNIX mailbox files are only closed and reopened
at checkpoint and expunge time. This ensures that, prior to rewriting
the file, that any cached stat() data from a network filesystem is
updated with current data.
Very old versions of NFS, and reputedly also AFS, can get into a state
in which the cached stat() data stays out-of-date, even across a
close and reopen of the file.
If network-filesystem-stat-bug is set non-zero, then the mailbox file
is closed and reopened at ping time as a workaround for this bug in
these network filesystems. This means that in imapd, the mailbox
file is closed and reopened for every IMAP command. This is obviously
something that should be avoided unless absolutely necessary.
NFS and AFS are terrible ways to distribute mail. You use use IMAP
servers with a local disk instead.
The default is zero (only close/reopen at checkpoint and expunge time).
Setting this option is a great way to ruin your system's performance.
39) set restrict-mailbox-access <option> <option> ... <option>
This option is for closed server systems only. It is less extreme
than chroot-server, and allows selective restriction of what mailbox
named users can use. The existing options are:
root access not permitted to names starting with "/"
otherusers access not permitted to other users' names; this should
normally be used in conjunction with "root", otherwise
another user's names can be accessed via a root name.
all all of the above
Setting any combination of options also disables access to superior
directories via "..".
This should be done ONLY on systems which do not permit users to
have shell access
The default is no restrictions.

2988
docs/internal.txt Normal file
View File

File diff suppressed because it is too large Load Diff

417
docs/locking.txt Normal file
View File

@ -0,0 +1,417 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
UNIX Advisory File Locking Implications on c-client
Mark Crispin, 28 November 1995
THIS DOCUMENT HAS BEEN UPDATED TO REFLECT THE FACT THAT
LINUX SUPPORTS BOTH flock() AND fcntl() AND THAT OSF/1
HAS BEEN BROKEN SO THAT IT ONLY SUPPORTS fcntl().
-- JUNE 15, 2004
THIS DOCUMENT HAS BEEN UPDATED TO REFLECT THE CODE IN THE
IMAP-4 TOOLKIT AS OF NOVEMBER 28, 1995. SOME STATEMENTS
IN THIS DOCUMENT DO NOT APPLY TO EARLIER VERSIONS OF THE
IMAP TOOLKIT.
INTRODUCTION
Advisory locking is a mechanism by which cooperating processes
can signal to each other their usage of a resource and whether or not
that usage is critical. It is not a mechanism to protect against
processes which do not cooperate in the locking.
The most basic form of locking involves a counter. This counter
is -1 when the resource is available. If a process wants the lock, it
executes an atomic increment-and-test-if-zero. If the value is zero,
the process has the lock and can execute the critical code that needs
exclusive usage of a resource. When it is finished, it sets the lock
back to -1. In C terms:
while (++lock) /* try to get lock */
invoke_other_threads (); /* failed, try again */
.
. /* critical code here */
.
lock = -1; /* release lock */
This particular form of locking appears most commonly in
multi-threaded applications such as operating system kernels. It
makes several presumptions:
(1) it is alright to keep testing the lock (no overflow)
(2) the critical resource is single-access only
(3) there is shared writeable memory between the two threads
(4) the threads can be trusted to release the lock when finished
In applications programming on multi-user systems, most commonly
the other threads are in an entirely different process, which may even
be logged in as a different user. Few operating systems offer shared
writeable memory between such processes.
A means of communicating this is by use of a file with a mutually
agreed upon name. A binary semaphore can be passed by means of the
existance or non-existance of that file, provided that there is an
atomic means to create a file if and only if that file does not exist.
In C terms:
/* try to get lock */
while ((fd = open ("lockfile",O_WRONLY|O_CREAT|O_EXCL,0666)) < 0)
sleep (1); /* failed, try again */
close (fd); /* got the lock */
.
. /* critical code here */
.
unlink ("lockfile"); /* release lock */
This form of locking makes fewer presumptions, but it still is
guilty of presumptions (2) and (4) above. Presumption (2) limits the
ability to have processes sharing a resource in a non-conflicting
fashion (e.g. reading from a file). Presumption (4) leads to
deadlocks should the process crash while it has a resource locked.
Most modern operating systems provide a resource locking system
call that has none of these presumptions. In particular, a mechanism
is provided for identifying shared locks as opposed to exclusive
locks. A shared lock permits other processes to obtain a shared lock,
but denies exclusive locks. In other words:
current state want shared want exclusive
------------- ----------- --------------
unlocked YES YES
locked shared YES NO
locked exclusive NO NO
Furthermore, the operating system automatically relinquishes all
locks held by that process when it terminates.
A useful operation is the ability to upgrade a shared lock to
exclusive (provided there are no other shared users of the lock) and
to downgrade an exclusive lock to shared. It is important that at no
time is the lock ever removed; a process upgrading to exclusive must
not relenquish its shared lock.
Most commonly, the resources being locked are files. Shared
locks are particularly important with files; multiple simultaneous
processes can read from a file, but only one can safely write at a
time. Some writes may be safer than others; an append to the end of
the file is safer than changing existing file data. In turn, changing
a file record in place is safer than rewriting the file with an
entirely different structure.
FILE LOCKING ON UNIX
In the oldest versions of UNIX, the use of a semaphore lockfile
was the only available form of locking. Advisory locking system calls
were not added to UNIX until after the BSD vs. System V split. Both
of these system calls deal with file resources only.
Most systems only have one or the other form of locking. AIX
and newer versions of OSF/1 emulate the BSD form of locking as a jacket
into the System V form. Ultrix and Linux implement both forms.
BSD
BSD added the flock() system call. It offers capabilities to
acquire shared lock, acquire exclusive lock, and unlock. Optionally,
the process can request an immediate error return instead of blocking
when the lock is unavailable.
FLOCK() BUGS
flock() advertises that it permits upgrading of shared locks to
exclusive and downgrading of exclusive locks to shared, but it does so
by releasing the former lock and then trying to acquire the new lock.
This creates a window of vulnerability in which another process can
grab the exclusive lock. Therefore, this capability is not useful,
although many programmers have been deluded by incautious reading of
the flock() man page to believe otherwise. This problem can be
programmed around, once the programmer is aware of it.
flock() always returns as if it succeeded on NFS files, when in
fact it is a no-op. There is no way around this.
Leaving aside these two problems, flock() works remarkably well,
and has shown itself to be robust and trustworthy.
SYSTEM V/POSIX
System V added new functions to the fnctl() system call, and a
simple interface through the lockf() subroutine. This was
subsequently included in POSIX. Both offer the facility to apply the
lock to a particular region of the file instead of to the entire file.
lockf() only supports exclusive locks, and calls fcntl() internally;
hence it won't be discussed further.
Functionally, fcntl() locking is a superset of flock(); it is
possible to implement a flock() emulator using fcntl(), with one minor
exception: it is not possible to acquire an exclusive lock if the file
is not open for write.
The fcntl() locking functions are: query lock station of a file
region, lock/unlock a region, and lock/unlock a region and block until
have the lock. The locks may be shared or exclusive. By means of the
statd and lockd daemons, fcntl() locking is available on NFS files.
When statd is started at system boot, it reads its /etc/state
file (which contains the number of times it has been invoked) and
/etc/sm directory (which contains a list of all remote sites which are
client or server locking with this site), and notifies the statd on
each of these systems that it has been restarted. Each statd then
notifies the local lockd of the restart of that system.
lockd receives fcntl() requests for NFS files. It communicates
with the lockd at the server and requests it to apply the lock, and
with the statd to request it for notification when the server goes
down. It blocks until all these requests are completed.
There is quite a mythos about fcntl() locking.
One religion holds that fcntl() locking is the best thing since
sliced bread, and that programs which use flock() should be converted
to fcntl() so that NFS locking will work. However, as noted above,
very few systems support both calls, so such an exercise is pointless
except on Ultrix and Linux.
Another religion, which I adhere to, has the opposite viewpoint.
FCNTL() BUGS
For all of the hairy code to do individual section locking of a
file, it's clear that the designers of fcntl() locking never
considered some very basic locking operations. It's as if all they
knew about locking they got out of some CS textbook with not
investigation of real-world needs.
It is not possible to acquire an exclusive lock unless the file
is open for write. You could have append with shared read, and thus
you could have a case in which a read-only access may need to go
exclusive. This problem can be programmed around once the programmer
is aware of it.
If the file is opened on another file designator in the same
process, the file is unlocked even if no attempt is made to do any
form of locking on the second designator. This is a very bad bug. It
means that an application must keep track of all the files that it has
opened and locked.
If there is no statd/lockd on the NFS server, fcntl() will hang
forever waiting for them to appear. This is a bad bug. It means that
any attempt to lock on a server that doesn't run these daemons will
hang. There is no way for an application to request flock() style
``try to lock, but no-op if the mechanism ain't there''.
There is a rumor to the effect that fcntl() will hang forever on
local files too if there is no local statd/lockd. These daemons are
running on mailer.u, although they appear not to have much CPU time.
A useful experiment would be to kill them and see if imapd is affected
in any way, but I decline to do so without an OK from UCS! ;-) If
killing statd/lockd can be done without breaking fcntl() on local
files, this would become one of the primary means of dealing with this
problem.
The statd and lockd daemons have quite a reputation for extreme
fragility. There have been numerous reports about the locking
mechanism being wedged on a systemwide or even clusterwide basis,
requiring a reboot to clear. It is rumored that this wedge, once it
happens, also blocks local locking. Presumably killing and restarting
statd would suffice to clear the wedge, but I haven't verified this.
There appears to be a limit to how many locks may be in use at a
time on the system, although the documentation only mentions it in
passing. On some of their systems, UCS has increased lockd's ``size
of the socket buffer'', whatever that means.
C-CLIENT USAGE
c-client uses flock(). On System V systems, flock() is simulated
by an emulator that calls fcntl().
BEZERK AND MMDF
Locking in the traditional UNIX formats was largely dictated by
the status quo in other applications; however, additional protection
is added against inadvertantly running multiple instances of a
c-client application on the same mail file.
(1) c-client attempts to create a .lock file (mail file name with
``.lock'' appended) whenever it reads from, or writes to, the mail
file. This is an exclusive lock, and is held only for short periods
of time while c-client is actually doing the I/O. There is a 5-minute
timeout for this lock, after which it is broken on the presumption
that it is a stale lock. If it can not create the .lock file due to
an EACCES (protection failure) error, it once silently proceeded
without this lock; this was for systems which protect /usr/spool/mail
from unprivileged processes creating files. Today, c-client reports
an error unless it is built otherwise. The purpose of this lock is to
prevent against unfavorable interactions with mail delivery.
(2) c-client applies a shared flock() to the mail file whenever
it reads from the mail file, and an exclusive flock() whenever it
writes to the mail file. This lock is freed as soon as it finishes
reading. The purpose of this lock is to prevent against unfavorable
interactions with mail delivery.
(3) c-client applies an exclusive flock() to a file on /tmp
(whose name represents the device and inode number of the file) when
it opens the mail file. This lock is maintained throughout the
session, although c-client has a feature (called ``kiss of death'')
which permits c-client to forcibly and irreversibly seize the lock
from a cooperating c-client application that surrenders the lock on
demand. The purpose of this lock is to prevent against unfavorable
interactions with other instances of c-client (rewriting the mail
file).
Mail delivery daemons use lock (1), (2), or both. Lock (1) works
over NFS; lock (2) is the only one that works on sites that protect
/usr/spool/mail against unprivileged file creation. Prudent mail
delivery daemons use both forms of locking, and of course so does
c-client.
If only lock (2) is used, then multiple processes can read from
the mail file simultaneously, although in real life this doesn't
really change things. The normal state of locks (1) and (2) is
unlocked except for very brief periods.
TENEX AND MTX
The design of the locking mechanism of these formats was
motivated by a design to enable multiple simultaneous read/write
access. It is almost the reverse of how locking works with
bezerk/mmdf.
(1) c-client applies a shared flock() to the mail file when it
opens the mail file. It upgrades this lock to exclusive whenever it
tries to expunge the mail file. Because of the flock() bug that
upgrading a lock actually releases it, it will not do so until it has
acquired an exclusive lock (2) first. The purpose of this lock is to
prevent against expunge taking place while some other c-client has the
mail file open (and thus knows where all the messages are).
(2) c-client applies a shared flock() to a file on /tmp (whose
name represents the device and inode number of the file) when it
parses the mail file. It applies an exclusive flock() to this file
when it appends new mail to the mail file, as well as before it
attempts to upgrade lock (1) to exclusive. The purpose of this lock
is to prevent against data being appended while some other c-client is
parsing mail in the file (to prevent reading of incomplete messages).
It also protects against the lock-releasing timing race on lock (1).
OBSERVATIONS
In a perfect world, locking works. You are protected against
unfavorable interactions with the mailer and against your own mistake
by running more than one instance of your mail reader. In tenex/mtx
formats, you have the additional benefit that multiple simultaneous
read/write access works, with the sole restriction being that you
can't expunge if there are any sharers of the mail file.
If the mail file is NFS-mounted, then flock() locking is a silent
no-op. This is the way BSD implements flock(), and c-client's
emulation of flock() through fcntl() tests for NFS files and
duplicates this functionality. There is no locking protection for
tenex/mtx mail files at all, and only protection against the mailer
for bezerk/mmdf mail files. This has been the accepted state of
affairs on UNIX for many sad years.
If you can not create .lock files, it should not affect locking,
since the flock() locks suffice for all protection. This is, however,
not true if the mailer does not check for flock() locking, or if the
the mail file is NFS-mounted.
What this means is that there is *no* locking protection at all
in the case of a client using an NFS-mounted /usr/spool/mail that does
not permit file creation by unprivileged programs. It is impossible,
under these circumstances, for an unprivileged program to do anything
about it. Worse, if EACCES errors on .lock file creation are no-op'ed
, the user won't even know about it. This is arguably a site
configuration error.
The problem with not being able to create .lock files exists on
System V as well, but the failure modes for flock() -- which is
implemented via fcntl() -- are different.
On System V, if the mail file is NFS-mounted and either the
client or the server lacks a functioning statd/lockd pair, then the
lock attempt would have hung forever if it weren't for the fact that
c-client tests for NFS and no-ops the flock() emulator in this case.
Systemwide or clusterwide failures of statd/lockd have been known to
occur which cause all locks in all processes to hang (including
local?). Without the special NFS test made by c-client, there would
be no way to request BSD-style no-op behavior, nor is there any way to
determine that this is happening other than the system being hung.
The additional locking introduced by c-client was shown to cause
much more stress on the System V locking mechanism than has
traditionally been placed upon it. If it was stressed too far, all
hell broke loose. Fortunately, this is now past history.
TRADEOFFS
c-client based applications have a reasonable chance of winning
as long as you don't use NFS for remote access to mail files. That's
what IMAP is for, after all. It is, however, very important to
realize that you can *not* use the lock-upgrade feature by itself
because it releases the lock as an interim step -- you need to have
lock-upgrading guarded by another lock.
If you have the misfortune of using System V, you are likely to
run into problems sooner or later having to do with statd/lockd. You
basically end up with one of three unsatisfactory choices:
1) Grit your teeth and live with it.
2) Try to make it work:
a) avoid NFS access so as not to stress statd/lockd.
b) try to understand the code in statd/lockd and hack it
to be more robust.
c) hunt out the system limit of locks, if there is one,
and increase it. Figure on at least two locks per
simultaneous imapd process and four locks per Pine
process. Better yet, make the limit be 10 times the
maximum number of processes.
d) increase the socket buffer (-S switch to lockd) if
it is offered. I don't know what this actually does,
but giving lockd more resources to do its work can't
hurt. Maybe.
3) Decide that it can't possibly work, and turn off the
fcntl() calls in your program.
4) If nuking statd/lockd can be done without breaking local
locking, then do so. This would make SVR4 have the same
limitations as BSD locking, with a couple of additional
bugs.
5) Check for NFS, and don't do the fcntl() in the NFS case.
This is what c-client does.
Note that if you are going to use NFS to access files on a server
which does not have statd/lockd running, your only choice is (3), (4),
or (5). Here again, IMAP can bail you out.
These problems aren't unique to c-client applications; they have
also been reported with Elm, Mediamail, and other email tools.
Of the other two SVR4 locking bugs:
Programmer awareness is necessary to deal with the bug that you
can not get an exclusive lock unless the file is open for write. I
believe that c-client has fixed all of these cases.
The problem about opening a second designator smashing any
current locks on the file has not been addressed satisfactorily yet.
This is not an easy problem to deal with, especially in c-client which
really doesn't know what other files/streams may be open by Pine.
Aren't you so happy that you bought an System V system?

91
docs/md5.txt Normal file
View File

@ -0,0 +1,91 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
MD5 Based Authentication
Mark Crispin
1 November 1999
The IMAP toolkit makes available two MD5 based authentication
mechanisms, CRAM-MD5 and APOP. CRAM-MD5 is described in RFC 2195, and
is a SASL (RFC 2222) authentication mechanism. APOP is described in
RFC 1939, the standard document for the POP3 protocol.
These mechanisms use the same general idea. The server issues a
challenge; the client responds with an MD5 checksum of the challenge
plus the password; the server in compares the client's response with
its own calculated value of the checksum. If the client's response
matches the server's calulated value, the client is authenticated.
Unlike plaintext passwords, this form of authentication is
believed to be secure against the session being monitored; "sniffing"
the session will not disclose the password nor will it provide usable
information to authenticate in another session without knowing the
password.
The key disadvantage with this form of authentication is that the
server must know a plaintext form of the password. In traditional
UNIX authentication, the server only knows an encrypted form of the
password. Consequently, the authentication database for this form of
authentication must be kept strictly confidential; a bad guy who
acquires access to this database can access any account in the
database.
CRAM-MD5 client support is implemented unconditionally; any
client application built with the IMAP toolkit will use CRAM-MD5 with
any server which advertises CRAM-MD5 SASL support.
CRAM-MD5 and APOP server support is implemented if, and only if,
the CRAM-MD5 authentication database exists. By default, the CRAM-MD5
authentication database is in a UNIX file called
/etc/cram-md5.pwd
It is recommended that this file be protected 0400.
NOTE: FAILURE TO PROTECT THIS FILE AGAINST UNAUTHORIZED
ACCESS WILL COMPROMSE CRAM-MD5 AND APOP AUTHENTICATION
FOR ALL USERS LISTED IN THIS DATABASE.
If the CRAM-MD5 authentication database exists, then plaintext
password authentication (e.g. the LOGIN command) will also use the
CRAM-MD5 passwords instead of UNIX passwords. Alternatively, it is
possible to build the IMAP toolkit so that plaintext password
authentication is disabled entirely, by using PASSWDTYPE=nul, e.g.
make aix PASSWDTYPE=nul
The CRAM-MD5 authentication database file consists of a series of
text lines, consisting of a UNIX user name, a single tab, and the
password. A line starting with a "#" character is ignored, as are any
lines which are not in valid format. For example:
------------------------------Sample------------------------------
# CRAM-MD5 authentication database
# Entries are in form <user><tab><password>
# Lines starting with "#" are comments
bill hubba-hubba
hillary nysenator
monica beret
tripp wired
kenstarr inquisitor
reno waco
jessie thebody
billgates ruleworld
------------------------------Sample------------------------------
Every entry in the CRAM-MD5 authentication database must have a
corresponding entry in the /etc/passwd file. It is STRONGLY
RECOMMENDED that the CRAM-MD5 password NOT be the same as the
/etc/passwd password. It is permitted for the /etc/passwd password to
be disabled; /etc/passwd is just used to get the UID, GID, and home
directory information.

363
docs/mixfmt.txt Normal file
View File

@ -0,0 +1,363 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
Last update: 18 December 2006
INTRODUCTION
This file is the descendant of a design document used to specify the
mix format. An attempt is being made to keep this document more or
less current with the way the mix format actually works.
1. Mix mailbox naming
Mailbox names correspond to directory names; thus mix format mailboxes
are "dual-use" (lack both \NoInferiors and \NoSelect). This will
satisfy some long-standing requests.
2. Mailbox files
A mix format mailbox is a directory with regular files with filenames
of:
.mixmeta mailbox metadata file
.mixindex message index file (message static data)
.mixstatus message status file (message dynamic data)
.mix######## (where ######### is a <hex8>) secondary message
data files.
.mix primary message data file (used in experimental
versions, supported for compatibility only)
2.1 Metadata, index, and status files
The mailbox metadata, index, and status files contain a sequence of
CRLF-terminated lines. These files have an update sequence, which is
a strictly-ascending sequence value. Any time the file is changed,
the update sequence is increased; this allows easy detection of
whether the file has been changed by another process. For now, this
update sequence is a modseq (see below).
2.1.1 Metadata file
The mailbox metadata file is called ".mixmeta". It contains a series
of CRLF-terminated lines. The first character of the line is a key that
identifies the payload of the line, and the remainder of the line is the
payload.
Key Payload
--- -------
S <hex8> ;; update sequence
V <hex8> ;; UIDVALIDITY
L <hex8> ;; UIDLAST
N <hex8> ;; current new message file
K [atom 0*(SP atom)] ;; keyword list
All other keys are reserved for future assignment and must be ignored
(and may be discarded) by software which does not recognize them. The
mailbox metadata file is rewritten as part of new mail delivery (so
APPENDUID/COPYUID can work) and when new keywords are added.
2.1.2 Message static index file
The mailbox message static index file is called ".mixindex". It contains
a series of CRLF-terminated lines. The first character of the line is a
key that identifies the payload of the line, and the remainder of the line
is the payload.
Key Payload
--- -------
S <hex8> ;; update sequence
: <uid>:<date>:<size>:<file>:<pos>:<isiz>:<hsiz>
;; per-message record
The per-message records contain the following data:
<uid> = <hex8> ;; message UID
<date> = <yyyymmddhhmmss+zzzz> ;; internal date
<size> = <hex8> ;; rfc822.size
<file> = <hex8> ;; message data file (0 = .mix file)
<pos> = <hex8> ;; message position in file
<isiz> = <hex8> ;; message internal data size
<hsiz> = <hex8> ;; header size (offset to body)
All other keys, and subsequent fields in per-message records, are
reserved for future assignment and must be ignored (and may be
discarded) by software which does not recognize them. The mailbox
metadata file is appended by new mail delivery and rewritten by
expunge "burping", and otherwise is not altered.
2.1.3 Message dynamic status file
The mailbox message dynamic status file is called ".mixstatus". It contains
a series of CRLF-terminated lines. The first character of the line is a
key that identifies the payload of the line, and the remainder of the line
is the payload.
Key Payload
--- -------
S <hex8> ;; update sequence
: <uid>:<uf>:<sf>:<mod>: ;; per-message record
The per-message records contain the following data:
<uid> = <hex8> ;; message UID
<keys> = <hex8> ;; keyword flags
<flag> = <hex4> ;; system flags
<mod> = <hex8> ;; date/time last modified (modseq)
All other keys, and subsequent fields in per-message records, are
reserved for future assignment and must be ignored (and may be
discarded) by software which does not recognize them. The mailbox
dynamic idex file is rewritten by flag changes (or any future change
that alters dynamic data) and is re-read when a session sees that the
mtime has changed (atime and ctime are not used).
The modseq is an unsigned 32-bit date/time, along with a guarantee
that this value can not go backwards. It currently corresponds to the
time from time(); however, since it is unsigned, it won't run out until
the year 2106. In the future, this may be used as a basic for implementing
the IMAP CONDSTORE extension.
2.2 Message data files
A mix message file is a regular file with filename starting with
".mix" followed by a <hex8> suffix which indicates the file number. It
contains a series of CRLF-terminated lines. By special dispensation, the
filename ".mix" is used for file number 0, which was used in experimental
versions of mix as a "primary" file (this concept no longer exists).
A file number is set to the current modseq when it is created. If a copy
or append causes the file to exceed the compiled-in file size limit, a new
file is started and the metadata is updated accordingly.
Preceeding each message is per-message record with the following format:
Key Payload
--- -------
;; per-message record
: :<code>:<uid>:<date>:<size>:
The per-message records contain the following data:
<code> = "msg" ;; fixed code
<uid> = <hex8> ;; message UID
<date> = <yyyymmddhhmmss+zzzz> ;; internal date
<size> = <hex8> ;; rfc822.size
The message data begins on the next line
Subsequent fields are reserved for future assignment and must be ignored.
3. New mail delivery
To deliver a new message, it is necessary to share lock the destination
metadata file, then get an exclusive lock on the destination index and
status files. Once this is done, the new message data is appended to the
new message file. The metadata (UIDLAST value), index, and status
files are all updated to add the new message.
Then all the destination mailbox files are closed.
4. Mailbox pinging
The index and status files are share locked. Initially, sequences are
remembered as zero, so at open time they are always "altered".
The sequence from the index file is checked; if it is altered the index
file is read and processed as follows:
. If expunge is permitted, then any messages that are not in the index
are reported as having been expunged via mm_expunged().
. new messages are announced via mm_exists()/mm_recent().
Next, the sequence from the status file is checked. If it is altered,
the status file is read and the status updated for any message which is
new or has an altered modseq in the status file. Altered modseq messages
are announced via mm_flags().
Then the index and status files are closed.
4. Flag alteration
The status file is exclusive locked.
The sequence from the status file is checked. If it is altered, the
status file is read and the status updated for any message which is
new or has an altered modseq in the status file. Altered modseq
messages are announced via mm_flags().
The alterations are then applied for all requested messages, updating
the modseq for each requestedmessage which changes flags as a result
of the alteration (alterations which do not result in a change do not
alter the modseq). Then the status file is rewritten with a new
sequence, but only if flags of at least one message was changed.
Then the status file is closed.
5. Checkpoint and expunge
Checkpoint is identical to expunge, however it skips the step of expunging
deleted messages.
The index and status files are locked exclusive. If expunging, all
deleted messages are expunged from the index and announced via
mm_expunged(). The message data is notremoved at this time.
If a checkpoint was requested, or if any messages were expunged, or if
it remembered that a "burp" was needed, then:
. the metadata file is locked exclusive. If this fails, remember that
a burp is needed. Otherwise perform a burp:
. calculate the file byte ranges occupied by expunged messages
. for each file needing "burping", open and slide down subsequent file
data on top of the expunged messages
. update the index and status files
Then the index and status files are closed.
5.1 More details on expunging and "burping"
Shared expunge presents a problem due to the requirements of the IMAP
protocol. You can't "burp" away a message until you are certain that
no sharers have a pointer to any longer. Consequently, for the nonce
"burping" out expunged data be defered to an exclusive expunge as in
mbx format.
If shared burping is ever implemented, then care will be needed not to
burp data that a session still relies upon. It's easy enough to burp
the index files; just create new index files, deleting the old, and
require that you look for a new one appearing at mailbox ping time
(when it's safe). The data files are a problem, since we
intentionally don't want to keep them open and do want to avoid quota
problems by overwriting in place. Also, when you burp you have to
change the pointers in the index file.
Bottom line: shared burping is too hairy right now, so the first
version will do exclusive-only burping and not worry about it. If
shared burping is really needed, then that routine will need to be
rewritten.
Shared burping has been a problem for every other IMAP server. Most
get it wrong, and cause terrible confusion to clients (including
client crashes).
6. Message data file file roll out strategy
The current new message file is finalized, and a new one started, when
an append or copy is done that would cause the file to grow to larger
than a preconfigured size (MIXDATAROLL). A multi-message copy or
append is written into its entirety to a single new message file. In
the case of multi-copy, the new message file is switched when the sum
of the sizes of all messages to be copied would cause the current new
message file to exceed MIXDATAROLL. In the case of multi-append, only
the first message is considered; this is due to technical limitations.
7. Error detection
Mix detects bad data in the metadata, index, and status files; and
declares the stream dead. It does not unilaterally reassign
UIDVALIDITY the way that the flat file formats do.
When mix reads a header from the message file, it also reads the
per-message record and verifies that there is a per-message record there.
This is a simple test for message file corruption. It doesn't declare
the stream dead; it simply issues an error message and returns a
zero-length string for the message header. This makes it possible for
the user to fix the mailbox simply by deleting and expunging any messages
that are in this state.
8. Reconstruct tool
[None of this is implemented yet.]
The layout of these files is designed to make the reconstruct tool be
as simple as possible. Much of the need for the reconstruct tool is
eliminated since the mix format has a much more limited scope of
writing than the flat file formats; thus there is "less collateral
damage."
If the metadata file is lost or corrupted, then all keywords are lost;
if the mailbox has any keywords used in the .mixstatus file, it'll be
necessary to create some placeholder names. Otherwise, a new
UIDVALIDITY can be assigned, and a good UIDLAST value calculated by
the reconstruct tool. Since this file is very small, it's not likely
to be damaged.
If the index file is lost or corrupted, it is possible to reconstruct
it with no loss by reading all the data files. However, this could
cause expunged but not yet burped messages to reappear.
If the status file is lost or corrupted, then flags are lost and
will revert to a default state of no flags set. Just deleting the
corrupted file is good enough.
The reconstruct tool can use the per-message record in the message
file to locate messages if the recorded sizes and/or messages are
corrupt. If that happens, it will need to rebuild the index file
(with associated changes to the metadata file to change the
UIDVALIDITY). That should probably be a manual operation and not be
part of the default operation or auto-reconstruct.
9. Locking strategy
The mix format does not use the traditional c-client /tmp file locking.
The metadata file is open and locked whenever the mailbox is open.
Normally this is a shared lock, but it will be upgraded to exclusive
if the mailbox is expunged. As a guard (since there is no true
lock-upgrade/downgrade on UNIX), the index exclusive lock must be
acquired first before upgrading to exclusive.
The index file is shared locked when reading the index, and exclusive
locked (and read) when appending new messages to the index or when
expunging (note that expunging also requires an exclusive lock on
metadata). Normally, the index file is not open or locked.
The status file is shared locked when reading status, and exclusive
locked (and read) when updating status. Normally, the status file is
not open or locked.
It isn't necessary to lock any of the data files as long as we only
have exclusive burping.
10. Memory usage
The mix format returns a file stringstruct, which is the modern
c-client behavior. This prevents imapd from growing to enormous sizes
due to a godzillagram (how it affects other programs depends upon what
they do with the returned stringstruct).
11. Future extensions
Cached ENVELOPE, BODYSTRUCTURE. Cyrus does, and this will eliminate
most of the reason to access the data files. Possibly cached overviews,
ala NNTP, instead?
Support for ANNOTATION.
12. RENAME issues
Mix currently makes no attempt to address the IMAP RENAME problem.
This occurs when a mailbox is deleted, and another mailbox is renamed
with that name in place, no attempt is made to reassign UIDVALIDITY
for this mailbox and all the inferior mailboxes. This potentially can
cause problems for a disconnected-use client that has cached status
for the old mailbox which had that name.
The RENAME problem is a well known flaw in the IMAP protocol. Few
servers correctly handle it (among other things, not only do all the
UIDVALIDITY values have to be changed but this has to be done
atomically!). It was a mistake to add RENAME into IMAP, but it's much
too late to remove it now.

143
docs/naming.txt Normal file
View File

@ -0,0 +1,143 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
Mailbox Name Conventions
Mark Crispin
5 October 2005
Please refer to the file drivers.txt for related information.
I. Special names
Special names appear by themselves.
I.a. INBOX
The name INBOX is special and refers to primary incoming message
mailbox on the local system.
I.b. #mhinbox (UNIX only)
The name #mhinbox is special and refers to the primary incoming mh
format mailbox on the local system. Don't worry about this if you
don't know what mh format is.
II. Special prefixes
All names which start with a "#" have a "special prefix" which
identifies an alternative namespace. Special prefixes appear in front
of some additional text which constitutes a suffix.
II.a. #mh/ (UNIX only)
The prefix #mh/ is special and refers to the mh format mailbox named
with the suffix. For example, #mh/foo refers to the mh format mailbox
named foo. Don't worry about this if you don't know what mh format is.
II.b. #news. (UNIX only)
The prefix #news. is special and refers to the newsgroup named with
the suffix. For example, #news.comp.mail.misc refers to the newsgroup
named comp.mail.misc.
II.c. #ftp/ (UNIX only)
The prefix #ftp/ is special and refers to the anonymous ftp filesystem
named with the suffix. For example, #ftp/foo/bar refers to the file
/foo/bar in the anonymous FTP filesystem. Anonymous FTP files are
available to anonymous IMAP logins.
II.d. #public/ (UNIX only)
The prefix #public/ is special and refers to the public files
filesystem named with the suffix. For example, #public/foo/bar refers
to the file /foo/bar in the public filesystem. Public files are
available to anonymous IMAP logins.
II.e. #shared/ (UNIX only)
The prefix #shared/ is special and refers to the shared files
filesystem named with the suffix. For example, #shared/foo/bar
frefers to the file /foo/bar in the shared filesystem.
III. Remote names
All names which start with "{" are remote names, and are in the form
"{" remote_system_name [":" port] [flags] "}" [mailbox_name]
where:
remote_system_name Internet domain name or bracketed IP address
of server.
port optional TCP port number, default is the
default port for that service
flags optional flags, one of the following:
"/service=" service mailbox access service, default is "imap"
"/user=" user remote user name for login on the server
"/authuser=" user remote authentication user; if specified this
is the user name whose password is used (e.g.
administrator)
"/anonymous" remote access as anonymous user
"/debug" record protocol telemetry in application's
debug log
"/secure" do not transmit a plaintext password over
the network
"/imap", "/imap2", "/imap2bis", "/imap4", "/imap4rev1"
equivalent to /service=imap
"/pop3" equivalent to /service=pop3
"/nntp" equivalent to /service=nntp
"/norsh" do not use rsh or ssh to establish a preauthenticated
IMAP session
"/ssl" use the Secure Socket Layer to encrypt the session
"/validate-cert" validate certificates from TLS/SSL server (this is the
default behavior)
"/novalidate-cert" do not validate certificates from TLS/SSL server,
needed if server uses self-signed certificates
"/tls" force use of start-TLS to encrypt the session, and
reject connection to servers that do not support it
"/tls-sslv23" use the depreciated SSLv23 client when negotiating
TLS to the server. This is necessary with some
broken servers which (incorrectly) think that TLS
is just another way of doing SSL.
"/notls" do not do start-TLS to encrypt the session, even
with servers that support it
"/readonly" request read-only mailbox open (IMAP only; ignored
on NNTP, and an error with SMTP and POP3)
"/loser" disable various protocol features and perform various
client-side workarounds; for example, it disables
the SEARCH command in IMAP and does client-side
searching instead. The precise measures taken by
/loser depend upon the protocol and are subject to
change over time. /loser is intended for use with
defective servers which do not implement the
protocol specification correctly. It should be used
only as a last resort since it will seriously
degrade performance.
mailbox_name remote mailbox name, default is INBOX
For example:
{imap.foo.com}INBOX
opens an IMAP connection to system imap.foo.com and selects INBOX.
IV. All other names
All other names are treated as local file names, relative to the
user's home directory. Read drivers.txt for more details.

70
docs/rfc/README Normal file
View File

@ -0,0 +1,70 @@
The following documents are necessary to understand the syntax rules
most of the remaining documents. Note that some documents refer to
RFC 2234 which has been replaced by RFC 5234:
rfc5234.txt Augmented BNF for Syntax Specifications - ABNF
rfc4466.txt Collected Extensions to IMAP4 ABNF
The following documents specify the IMAP protocol:
rfc3501.txt Internet Message Access Protocol - Version 4rev1
The following documents provide additional information which is useful
in understanding the IMAP protocol:
rfc1733.txt Distributed Electronic Mail Models in IMAP4
rfc2180.txt IMAP4 Multi-Accessed Mailbox Practice
rfc2683.txt IMAP4 Implementation Recommendations
rfc4549.txt Synchronization Operations for Disconnected IMAP4 Clients
The following documents describe extensions to the IMAP protocol.
Items marked with "*" are supported in this distribution:
rfc4314.txt ACL
* rfc3516.txt BINARY
rfc4469.txt CATENATE
* rfc3348.txt CHILDREN
rfc4978.txt COMPRESS
rfc4551.txt CONDSTORE
rfc5161.txt ENABLE
* rfc4731.txt ESEARCH
rfc2971.txt ID
* rfc2177.txt IDLE
* rfc2088.txt LITERAL+
* rfc2221.txt LOGIN-REFERRALS
* rfc2193.txt MAILBOX-REFERRALS
* rfc3502.txt MULTIAPPEND
* rfc2342.txt NAMESPACE
rfc5162.txt QRESYNC
rfc2087.txt QUOTA
* rfc4959.txt SASL-IR
* rfc4315.txt UIDPLUS
* rfc3691.txt UNSELECT
rfc4467.txt URLAUTH
* rfc5032.txt WITHIN
The following documents describe SASL:
rfc4422.txt Simple Authentication and Security Layer (SASL)
and the SASL mechanisms supported in this distribution:
rfc4505.txt ANONYMOUS
rfc2195.txt CRAM-MD5
rfc4752.txt GSSAPI
rfc4616.txt PLAIN
The following documents relate to internationalization issues:
rfc4790.txt Internet Application Protocol Collation Registry
rfc5051.txt i;unicode-casemap - Simple Unicode Collation Algorithm
The following documents are primarily of historic interest:
rfc1732.txt IMAP4 Compatibility with IMAP2 and IMAP2bis
rfc2061.txt IMAP4 Compatibility with IMAP2bis
rfc2062.txt Internet Message Access Protocol - Obsolete Syntax
The following documents discuss matters which are related to IMAP:
rfc3503.txt MDN Profile for IMAP
rfc3656.txt MUPDATE Distributed Mailbox Database Protocol
rfc4468.txt Message Submission BURL Extension
rfc5092.txt IMAP URL Scheme

283
docs/rfc/rfc1732.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/rfc/rfc1733.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]

171
docs/rfc/rfc2061.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/rfc/rfc2062.txt Normal file
View File

@ -0,0 +1,451 @@
Network Working Group M. Crispin
Request for Comments: 2062 University of Washington
Category: Informational December 1996
Internet Message Access Protocol - Obsolete Syntax
Status of this Memo
This memo provides information for the Internet community. This memo
does not specify an Internet standard of any kind. Distribution of
this memo is unlimited.
Abstract
This document describes obsolete syntax which may be encountered by
IMAP4 implementations which deal with older versions of the Internet
Mail Access Protocol. IMAP4 implementations MAY implement this
syntax in order to maximize interoperability with older
implementations.
This document repeats information from earlier documents, most
notably RFC 1176 and RFC 1730.
Obsolete Commands and Fetch Data Items
The following commands are OBSOLETE. It is NOT required to support
any of these commands or fetch data items in new server
implementations. These commands are documented here for the benefit
of implementors who may wish to support them for compatibility with
old client implementations.
The section headings of these commands are intended to correspond
with where they would be located in the main document if they were
not obsoleted.
6.3.OBS.1. FIND ALL.MAILBOXES Command
Arguments: mailbox name with possible wildcards
Data: untagged responses: MAILBOX
Result: OK - find completed
NO - find failure: can't list that name
BAD - command unknown or arguments invalid
Crispin Informational [Page 1]
RFC 2062 IMAP4 Obsolete December 1996
The FIND ALL.MAILBOXES command returns a subset of names from the
complete set of all names available to the user. It returns zero
or more untagged MAILBOX replies. The mailbox argument to FIND
ALL.MAILBOXES is similar to that for LIST with an empty reference,
except that the characters "%" and "?" match a single character.
Example: C: A002 FIND ALL.MAILBOXES *
S: * MAILBOX blurdybloop
S: * MAILBOX INBOX
S: A002 OK FIND ALL.MAILBOXES completed
6.3.OBS.2. FIND MAILBOXES Command
Arguments: mailbox name with possible wildcards
Data: untagged responses: MAILBOX
Result: OK - find completed
NO - find failure: can't list that name
BAD - command unknown or arguments invalid
The FIND MAILBOXES command returns a subset of names from the set
of names that the user has declared as being "active" or
"subscribed". It returns zero or more untagged MAILBOX replies.
The mailbox argument to FIND MAILBOXES is similar to that for LSUB
with an empty reference, except that the characters "%" and "?"
match a single character.
Example: C: A002 FIND MAILBOXES *
S: * MAILBOX blurdybloop
S: * MAILBOX INBOX
S: A002 OK FIND MAILBOXES completed
6.3.OBS.3. SUBSCRIBE MAILBOX Command
Arguments: mailbox name
Data: no specific data for this command
Result: OK - subscribe completed
NO - subscribe failure: can't subscribe to that name
BAD - command unknown or arguments invalid
The SUBSCRIBE MAILBOX command is identical in effect to the
SUBSCRIBE command. A server which implements this command must be
able to distinguish between a SUBSCRIBE MAILBOX command and a
SUBSCRIBE command with a mailbox name argument of "MAILBOX".
Crispin Informational [Page 2]
RFC 2062 IMAP4 Obsolete December 1996
Example: C: A002 SUBSCRIBE MAILBOX #news.comp.mail.mime
S: A002 OK SUBSCRIBE MAILBOX to #news.comp.mail.mime
completed
C: A003 SUBSCRIBE MAILBOX
S: A003 OK SUBSCRIBE to MAILBOX completed
6.3.OBS.4. UNSUBSCRIBE MAILBOX Command
Arguments: mailbox name
Data: no specific data for this command
Result: OK - unsubscribe completed
NO - unsubscribe failure: can't unsubscribe that name
BAD - command unknown or arguments invalid
The UNSUBSCRIBE MAILBOX command is identical in effect to the
UNSUBSCRIBE command. A server which implements this command must
be able to distinguish between a UNSUBSCRIBE MAILBOX command and
an UNSUBSCRIBE command with a mailbox name argument of "MAILBOX".
Example: C: A002 UNSUBSCRIBE MAILBOX #news.comp.mail.mime
S: A002 OK UNSUBSCRIBE MAILBOX from #news.comp.mail.mime
completed
C: A003 UNSUBSCRIBE MAILBOX
S: A003 OK UNSUBSCRIBE from MAILBOX completed
6.4.OBS.1 PARTIAL Command
Arguments: message sequence number
message data item name
position of first octet
number of octets
Data: untagged responses: FETCH
Result: OK - partial completed
NO - partial error: can't fetch that data
BAD - command unknown or arguments invalid
The PARTIAL command is equivalent to the associated FETCH command,
with the added functionality that only the specified number of
octets, beginning at the specified starting octet, are returned.
Only a single message can be fetched at a time. The first octet
of a message, and hence the minimum for the starting octet, is
octet 1.
Crispin Informational [Page 3]
RFC 2062 IMAP4 Obsolete December 1996
The following FETCH items are valid data for PARTIAL: RFC822,
RFC822.HEADER, RFC822.TEXT, BODY[<section>], as well as any .PEEK
forms of these.
Any partial fetch that attempts to read beyond the end of the text
is truncated as appropriate. If the starting octet is beyond the
end of the text, an empty string is returned.
The data are returned with the FETCH response. There is no
indication of the range of the partial data in this response. It
is not possible to stream multiple PARTIAL commands of the same
data item without processing and synchronizing at each step, since
streamed commands may be executed out of order.
There is no requirement that partial fetches follow any sequence.
For example, if a partial fetch of octets 1 through 10000 breaks
in an awkward place for BASE64 decoding, it is permitted to
continue with a partial fetch of 9987 through 19987, etc.
The handling of the \Seen flag is the same as in the associated
FETCH command.
Example: C: A005 PARTIAL 4 RFC822 1 1024
S: * 1 FETCH (RFC822 {1024}
S: Return-Path: <gray@cac.washington.edu>
S: ...
S: ......... FLAGS (\Seen))
S: A005 OK PARTIAL completed
6.4.5.OBS.1 Obsolete FETCH Data Items
The following FETCH data items are obsolete:
BODY[<...>0] A body part number of 0 is the [RFC-822] header of
the message. BODY[0] is functionally equivalent to
BODY[HEADER], differing in the syntax of the
resulting untagged FETCH data (BODY[0] is
returned).
RFC822.HEADER.LINES <header_list>
Functionally equivalent to BODY.PEEK[HEADER.LINES
<header_list>], differing in the syntax of the
resulting untagged FETCH data (RFC822.HEADER is
returned).
Crispin Informational [Page 4]
RFC 2062 IMAP4 Obsolete December 1996
RFC822.HEADER.LINES.NOT <header_list>
Functionally equivalent to
BODY.PEEK[HEADER.LINES.NOT <header_list>],
differing in the syntax of the resulting untagged
FETCH data (RFC822.HEADER is returned).
RFC822.PEEK Functionally equivalent to BODY.PEEK[], except for
the syntax of the resulting untagged FETCH data
(RFC822 is returned).
RFC822.TEXT.PEEK
Functionally equivalent to BODY.PEEK[TEXT], except
for the syntax of the resulting untagged FETCH data
(RFC822.TEXT is returned).
Obsolete Responses
The following responses are OBSOLETE. Except as noted below, these
responses MUST NOT be transmitted by new server implementations.
Client implementations SHOULD accept these responses.
The section headings of these responses are intended to correspond
with where they would be located in the main document if they were
not obsoleted.
7.2.OBS.1. MAILBOX Response
Data: name
The MAILBOX response MUST NOT be transmitted by server
implementations except in response to the obsolete FIND MAILBOXES
and FIND ALL.MAILBOXES commands. Client implementations that do
not use these commands MAY ignore this response. It is documented
here for the benefit of implementors who may wish to support it
for compatibility with old client implementations.
This response occurs as a result of the FIND MAILBOXES and FIND
ALL.MAILBOXES commands. It returns a single name that matches the
FIND specification. There are no attributes or hierarchy
delimiter.
Example: S: * MAILBOX blurdybloop
Crispin Informational [Page 5]
RFC 2062 IMAP4 Obsolete December 1996
7.3.OBS.1. COPY Response
Data: none
The COPY response MUST NOT be transmitted by new server
implementations. Client implementations MUST ignore the COPY
response. It is documented here for the benefit of client
implementors who may encounter this response from old server
implementations.
In some experimental versions of this protocol, this response was
returned in response to a COPY command to indicate on a
per-message basis that the message was copied successfully.
Example: S: * 44 COPY
7.3.OBS.2. STORE Response
Data: message data
The STORE response MUST NOT be transmitted by new server
implementations. Client implementations MUST treat the STORE
response as equivalent to the FETCH response. It is documented
here for the benefit of client implementors who may encounter this
response from old server implementations.
In some experimental versions of this protocol, this response was
returned instead of FETCH in response to a STORE command to report
the new value of the flags.
Example: S: * 69 STORE (FLAGS (\Deleted))
Formal Syntax of Obsolete Commands and Responses
Each obsolete syntax rule that is suffixed with "_old" is added to
the corresponding name in the formal syntax. For example,
command_auth_old adds the FIND command to command_auth.
command_auth_old ::= find
command_select_old
::= partial
date_year_old ::= 2digit
;; (year - 1900)
date_time_old ::= <"> date_day_fixed "-" date_month "-" date_year
SPACE time "-" zone_name <">
Crispin Informational [Page 6]
RFC 2062 IMAP4 Obsolete December 1996
find ::= "FIND" SPACE ["ALL."] "MAILBOXES" SPACE
list_mailbox
fetch_att_old ::= "RFC822.HEADER.LINES" [".NOT"] SPACE header_list /
fetch_text_old
fetch_text_old ::= "BODY" [".PEEK"] section_old /
"RFC822" [".HEADER" / ".TEXT" [".PEEK"]]
msg_data_old ::= "COPY" / ("STORE" SPACE msg_att)
partial ::= "PARTIAL" SPACE nz_number SPACE fetch_text_old SPACE
number SPACE number
section_old ::= "[" (number ["." number]) "]"
subscribe_old ::= "SUBSCRIBE" SPACE "MAILBOX" SPACE mailbox
unsubscribe_old ::= "UNSUBSCRIBE" SPACE "MAILBOX" SPACE mailbox
zone_name ::= "UT" / "GMT" / "Z" / ;; +0000
"AST" / "EDT" / ;; -0400
"EST" / "CDT" / ;; -0500
"CST" / "MDT" / ;; -0600
"MST" / "PDT" / ;; -0700
"PST" / "YDT" / ;; -0800
"YST" / "HDT" / ;; -0900
"HST" / "BDT" / ;; -1000
"BST" / ;; -1100
"A" / "B" / "C" / "D" / "E" / "F" / ;; +1 to +6
"G" / "H" / "I" / "K" / "L" / "M" / ;; +7 to +12
"N" / "O" / "P" / "Q" / "R" / "S" / ;; -1 to -6
"T" / "U" / "V" / "W" / "X" / "Y" ;; -7 to -12
Security Considerations
Security issues are not discussed in this memo.
Crispin Informational [Page 7]
RFC 2062 IMAP4 Obsolete December 1996
Author's Address
Mark R. Crispin
Networks and Distributed Computing
University of Washington
4545 15th Aveneue NE
Seattle, WA 98105-4527
Phone: (206) 543-5762
EMail: MRC@CAC.Washington.EDU
Crispin Informational [Page 8]

283
docs/rfc/rfc2087.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/rfc/rfc2088.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]

227
docs/rfc/rfc2177.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/rfc/rfc2180.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]

507
docs/rfc/rfc2193.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/rfc/rfc2195.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/rfc/rfc2221.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]

563
docs/rfc/rfc2342.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]

1291
docs/rfc/rfc2683.txt Normal file
View File

File diff suppressed because it is too large Load Diff

451
docs/rfc/rfc2971.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]

339
docs/rfc/rfc3348.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]

6052
docs/rfc/rfc3501.txt Normal file
View File

File diff suppressed because it is too large Load Diff

395
docs/rfc/rfc3502.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/rfc/rfc3503.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/rfc/rfc3516.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]

1067
docs/rfc/rfc3656.txt Normal file
View File

File diff suppressed because it is too large Load Diff

283
docs/rfc/rfc3691.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/rfc/rfc4314.txt Normal file
View File

File diff suppressed because it is too large Load Diff

451
docs/rfc/rfc4315.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]

1851
docs/rfc/rfc4422.txt Normal file
View File

File diff suppressed because it is too large Load Diff

955
docs/rfc/rfc4466.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/rfc/rfc4467.txt Normal file
View File

File diff suppressed because it is too large Load Diff

787
docs/rfc/rfc4468.txt Normal file
View File

@ -0,0 +1,787 @@
Network Working Group C. Newman
Request for Comments: 4468 Sun Microsystems
Updates: 3463 May 2006
Category: Standards Track
Message Submission BURL Extension
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2006).
Abstract
The submission profile of Simple Mail Transfer Protocol (SMTP)
provides a standard way for an email client to submit a complete
message for delivery. This specification extends the submission
profile by adding a new BURL command that can be used to fetch
submission data from an Internet Message Access Protocol (IMAP)
server. This permits a mail client to inject content from an IMAP
server into the SMTP infrastructure without downloading it to the
client and uploading it back to the server.
Newman Standards Track [Page 1]
RFC 4468 Message Submission BURL Extension May 2006
Table of Contents
1. Introduction ....................................................2
2. Conventions Used in This Document ...............................2
3. BURL Submission Extension .......................................3
3.1. SMTP Submission Extension Registration .....................3
3.2. BURL Transaction ...........................................3
3.3. The BURL IMAP Options ......................................4
3.4. Examples ...................................................5
3.5. Formal Syntax ..............................................6
4. 8-Bit and Binary ................................................7
5. Updates to RFC 3463 .............................................7
6. Response Codes ..................................................7
7. IANA Considerations .............................................9
8. Security Considerations .........................................9
9. References .....................................................11
9.1. Normative References ......................................11
9.2. Informative References ....................................12
Appendix A. Acknowledgements .....................................13
1. Introduction
This specification defines an extension to the standard Message
Submission [RFC4409] protocol to permit data to be fetched from an
IMAP server at message submission time. This MAY be used in
conjunction with the CHUNKING [RFC3030] mechanism so that chunks of
the message can come from an external IMAP server. This provides the
ability to forward an email message without first downloading it to
the client.
2. Conventions Used in This Document
The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
in this document are to be interpreted as defined in "Key words for
use in RFCs to Indicate Requirement Levels" [RFC2119].
The formal syntax uses the Augmented Backus-Naur Form (ABNF)
[RFC4234] notation including the core rules defined in Appendix B of
RFC 4234.
Newman Standards Track [Page 2]
RFC 4468 Message Submission BURL Extension May 2006
3. BURL Submission Extension
This section defines the BURL submission extension.
3.1. SMTP Submission Extension Registration
1. The name of this submission extension is "BURL". This extends
the Message Submission protocol on port 587 and MUST NOT be
advertised by a regular SMTP [RFC2821] server on port 25 that
acts as a relay for incoming mail from other SMTP relays.
2. The EHLO keyword value associated with the extension is "BURL".
3. The BURL EHLO keyword will have zero or more arguments. The only
argument defined at this time is the "imap" argument, which MUST
be present in order to use IMAP URLs with BURL. Clients MUST
ignore other arguments after the BURL EHLO keyword unless they
are defined by a subsequent IETF standards track specification.
The arguments that appear after the BURL EHLO keyword may change
subsequent to the use of SMTP AUTH [RFC2554], so a server that
advertises BURL with no arguments prior to authentication
indicates that BURL is supported but authentication is required
to use it.
4. This extension adds the BURL SMTP verb. This verb is used as a
replacement for the DATA command and is only permitted during a
mail transaction after at least one successful RCPT TO.
3.2. BURL Transaction
A simple BURL transaction will consist of MAIL FROM, one or more RCPT
TO headers, and a BURL command with the "LAST" tag. The BURL command
will include an IMAP URL pointing to a fully formed message ready for
injection into the SMTP infrastructure. If PIPELINING [RFC2920] is
advertised, the client MAY send the entire transaction in one round
trip. If no valid RCPT TO address is supplied, the BURL command will
simply fail, and no resolution of the BURL URL argument will be
performed. If at least one valid RCPT TO address is supplied, then
the BURL URL argument will be resolved before the server responds to
the command.
A more sophisticated BURL transaction MAY occur when the server also
advertises CHUNKING [RFC3030]. In this case, the BURL and BDAT
commands may be interleaved until one of them terminates the
transaction with the "LAST" argument. If PIPELINING [RFC2920] is
also advertised, then the client may pipeline the entire transaction
in one round-trip. However, it MUST wait for the results of the
"LAST" BDAT or BURL command prior to initiating a new transaction.
Newman Standards Track [Page 3]
RFC 4468 Message Submission BURL Extension May 2006
The BURL command directs the server to fetch the data object to which
the URL refers and include it in the message. If the URL fetch
fails, the server will fail the entire transaction.
3.3. The BURL IMAP Options
When "imap" is present in the space-separated list of arguments
following the BURL EHLO keyword, it indicates that the BURL command
supports the URLAUTH [RFC4467] extended form of IMAP URLs [RFC2192]
and that the submit server is configured with the necessary
credentials to resolve "urlauth=submit+" IMAP URLs for the submit
server's domain.
Subsequent to a successful SMTP AUTH command, the submission server
MAY indicate a prearranged trust relationship with a specific IMAP
server by including a BURL EHLO keyword argument of the form
"imap://imap.example.com". In this case, the submission server will
permit a regular IMAP URL referring to messages or parts of messages
on imap.example.com that the user who authenticated to the submit
server can access. Note that this form does not imply that the
submit server supports URLAUTH URLs; the submit server must advertise
both "imap" and "imap://imap.example.com" to indicate support for
both extended and non-extended URL forms.
When the submit server connects to the IMAP server, it acts as an
IMAP client and thus is subject to both the mandatory-to-implement
IMAP capabilities in Section 6.1.1 of RFC 3501, and the security
considerations in Section 11 of RFC 3501. Specifically, this
requires that the submit server implement a configuration that uses
STARTTLS followed by SASL PLAIN [SASL-PLAIN] to authenticate to the
IMAP server.
When the submit server resolves a URLAUTH IMAP URL, it uses submit
server credentials when authenticating to the IMAP server. The
authentication identity and password used for submit credentials MUST
be configurable. The string "submit" is suggested as a default value
for the authentication identity, with no default for the password.
Typically, the authorization identity is empty in this case; thus the
IMAP server will derive the authorization identity from the
authentication identity. If the IMAP URL uses the "submit+" access
identifier prefix, the submit server MUST refuse the BURL command
unless the userid in the URL's <access> token matches the submit
client's authorization identity.
When the submit server resolves a regular IMAP URL, it uses the
submit client's authorization identity when authenticating to the
IMAP server. If both the submit client and the submit server's
embedded IMAP client use SASL PLAIN (or the equivalent), the submit
Newman Standards Track [Page 4]
RFC 4468 Message Submission BURL Extension May 2006
server SHOULD forward the client's credentials if and only if the
submit server knows that the IMAP server is in the same
administrative domain. If the submit server supports SASL mechanisms
other than PLAIN, it MUST implement a configuration in which the
submit server's embedded IMAP client uses STARTTLS and SASL PLAIN
with the submit server's authentication identity and password (for
the respective IMAP server) and the submit client's authorization
identity.
3.4. Examples
In examples, "C:" and "S:" indicate lines sent by the client and
server, respectively. If a single "C:" or "S:" label applies to
multiple lines, then the line breaks between those lines are for
editorial clarity only and are not part of the actual protocol
exchange.
Two successful submissions (without and with pipelining) follow:
<SSL/TLS encryption layer negotiated>
C: EHLO potter.example.com
S: 250-owlry.example.com
S: 250-8BITMIME
S: 250-BURL imap
S: 250-AUTH PLAIN
S: 250-DSN
S: 250 ENHANCEDSTATUSCODES
C: AUTH PLAIN aGFycnkAaGFycnkAYWNjaW8=
S: 235 2.7.0 PLAIN authentication successful.
C: MAIL FROM:<harry@gryffindor.example.com>
S: 250 2.5.0 Address Ok.
C: RCPT TO:<ron@gryffindor.example.com>
S: 250 2.1.5 ron@gryffindor.example.com OK.
C: BURL imap://harry@gryffindor.example.com/outbox
;uidvalidity=1078863300/;uid=25;urlauth=submit+harry
:internal:91354a473744909de610943775f92038 LAST
S: 250 2.5.0 Ok.
<SSL/TLS encryption layer negotiated>
C: EHLO potter.example.com
S: 250-owlry.example.com
S: 250-8BITMIME
S: 250-PIPELINING
S: 250-BURL imap
S: 250-AUTH PLAIN
S: 250-DSN
S: 250 ENHANCEDSTATUSCODES
C: AUTH PLAIN aGFycnkAaGFycnkAYWNjaW8=
Newman Standards Track [Page 5]
RFC 4468 Message Submission BURL Extension May 2006
C: MAIL FROM:<harry@gryffindor.example.com>
C: RCPT TO:<ron@gryffindor.example.com>
C: BURL imap://harry@gryffindor.example.com/outbox
;uidvalidity=1078863300/;uid=25;urlauth=submit+harry
:internal:91354a473744909de610943775f92038 LAST
S: 235 2.7.0 PLAIN authentication successful.
S: 250 2.5.0 Address Ok.
S: 250 2.1.5 ron@gryffindor.example.com OK.
S: 250 2.5.0 Ok.
Note that PIPELINING of the AUTH command is only permitted if the
selected mechanism can be completed in one round trip, a client
initial response is provided, and no SASL security layer is
negotiated. This is possible for PLAIN and EXTERNAL, but not for
most other SASL mechanisms.
Some examples of failure cases:
C: MAIL FROM:<harry@gryffindor.example.com>
C: RCPT TO:<malfoy@slitherin.example.com>
C: BURL imap://harry@gryffindor.example.com/outbox
;uidvalidity=1078863300/;uid=25;urlauth=submit+harry
:internal:91354a473744909de610943775f92038 LAST
S: 250 2.5.0 Address Ok.
S: 550 5.7.1 Relaying not allowed: malfoy@slitherin.example.com
S: 554 5.5.0 No recipients have been specified.
C: MAIL FROM:<harry@gryffindor.example.com>
C: RCPT TO:<ron@gryffindor.example.com>
C: BURL imap://harry@gryffindor.example.com/outbox
;uidvalidity=1078863300/;uid=25;urlauth=submit+harry
:internal:71354a473744909de610943775f92038 LAST
S: 250 2.5.0 Address Ok.
S: 250 2.1.5 ron@gryffindor.example.com OK.
S: 554 5.7.0 IMAP URL authorization failed
3.5. Formal Syntax
The following syntax specification inherits ABNF [RFC4234] and
Uniform Resource Identifiers [RFC3986].
burl-param = "imap" / ("imap://" authority)
; parameter to BURL EHLO keyword
burl-cmd = "BURL" SP absolute-URI [SP end-marker] CRLF
end-marker = "LAST"
Newman Standards Track [Page 6]
RFC 4468 Message Submission BURL Extension May 2006
4. 8-Bit and Binary
A submit server that advertises BURL MUST also advertise 8BITMIME
[RFC1652] and perform the down conversion described in that
specification on the resulting complete message if 8-bit data is
received with the BURL command and passed to a 7-bit server. If the
URL argument to BURL refers to binary data, then the submit server
MAY refuse the command or down convert as described in Binary SMTP
[RFC3030].
The Submit server MAY refuse to accept a BURL command or combination
of BURL and BDAT commands that result in un-encoded 8-bit data in
mail or MIME [RFC2045] headers. Alternatively, the server MAY accept
such data and down convert to MIME header encoding [RFC2047].
5. Updates to RFC 3463
SMTP or Submit servers that advertise ENHANCEDSTATUSCODES [RFC2034]
use enhanced status codes defined in RFC 3463 [RFC3463]. The BURL
extension introduces new error cases that that RFC did not consider.
The following additional enhanced status codes are defined by this
specification:
X.6.6 Message content not available
The message content could not be fetched from a remote system.
This may be useful as a permanent or persistent temporary
notification.
X.7.8 Trust relationship required
The submission server requires a configured trust relationship
with a third-party server in order to access the message content.
6. Response Codes
This section includes example response codes to the BURL command.
Other text may be used with the same response codes. This list is
not exhaustive, and BURL clients MUST tolerate any valid SMTP
response code. Most of these examples include the appropriate
enhanced status code [RFC3463].
554 5.5.0 No recipients have been specified
This response code occurs when BURL is used (for example, with
PIPELINING) and all RCPT TOs failed.
Newman Standards Track [Page 7]
RFC 4468 Message Submission BURL Extension May 2006
503 5.5.0 Valid RCPT TO required before BURL
This response code is an alternative to the previous one when BURL
is used (for example, with PIPELINING) and all RCPT TOs failed.
554 5.6.3 Conversion required but not supported
This response code occurs when the URL points to binary data and
the implementation does not support down conversion to base64.
This can also be used if the URL points to message data with 8-bit
content in headers and the server does not down convert such
content.
554 5.3.4 Message too big for system
The message (subsequent to URL resolution) is larger than the
per-message size limit for this server.
554 5.7.8 URL resolution requires trust relationship
The submit server does not have a trust relationship with the IMAP
server specified in the URL argument to BURL.
552 5.2.2 Mailbox full
The recipient is local, the submit server supports direct
delivery, and the recipient has exceeded his quota and any grace
period for delivery attempts.
554 5.6.6 IMAP URL resolution failed
The IMAP URLFETCH command returned an error or no data.
250 2.5.0 Waiting for additional BURL or BDAT commands
A BURL command without the "LAST" modifier was sent. The URL for
this BURL command was successfully resolved, but the content will
not necessarily be committed to persistent storage until the rest
of the message content is collected. For example, a Unix server
may have written the content to a queue file buffer, but may not
yet have performed an fsync() operation. If the server loses
power, the content can still be lost.
451 4.4.1 IMAP server unavailable
The connection to the IMAP server to resolve the URL failed.
Newman Standards Track [Page 8]
RFC 4468 Message Submission BURL Extension May 2006
250 2.5.0 Ok.
The URL was successfully resolved, and the complete message data
has been committed to persistent storage.
250 2.6.4 MIME header conversion with loss performed
The URL pointed to message data that included mail or MIME headers
with 8-bit data. This data was converted to MIME header encoding
[RFC2047], but the submit server may not have correctly guessed
the unlabeled character set.
7. IANA Considerations
The "BURL" SMTP extension as described in Section 3 has been
registered. This registration has been marked for use by message
submission [RFC4409] only in the registry.
8. Security Considerations
Modern SMTP submission servers often include content-based security
and denial-of-service defense mechanisms such as virus filtering,
size limits, server-generated signatures, spam filtering, etc.
Implementations of BURL should fetch the URL content prior to
application of such content-based mechanisms in order to preserve
their function.
Clients that generate unsolicited bulk email or email with viruses
could use this mechanism to compensate for a slow link between the
client and submit server. In particular, this mechanism would make
it feasible for a programmable cell phone or other device on a slow
link to become a significant source of unsolicited bulk email and/or
viruses. This makes it more important for submit server vendors
implementing BURL to have auditing and/or defenses against such
denial-of-service attacks including mandatory authentication, logging
that associates unique client identifiers with mail transactions,
limits on reuse of the same IMAP URL, rate limits, recipient count
limits, and content filters.
Transfer of the URLAUTH [RFC4467] form of IMAP URLs in the clear can
expose the authorization token to network eavesdroppers.
Implementations that support such URLs can address this issue by
using a strong confidentiality protection mechanism. For example,
the SMTP STARTTLS [RFC3207] and the IMAP STARTTLS [RFC3501]
extensions, in combination with a configuration setting that requires
their use with such IMAP URLs, would address this concern.
Newman Standards Track [Page 9]
RFC 4468 Message Submission BURL Extension May 2006
Use of a prearranged trust relationship between a submit server and a
specific IMAP server introduces security considerations. A
compromise of the submit server should not automatically compromise
all accounts on the IMAP server, so trust relationships involving
super-user proxy credentials are strongly discouraged. A system that
requires the submit server to authenticate to the IMAP server with
submit credentials and subsequently requires a URLAUTH URL to fetch
any content addresses this concern. A trusted third party model for
proxy credentials (such as that provided by Kerberos 5 [RFC4120])
would also suffice.
When a client uses SMTP STARTTLS to send a BURL command that
references non-public information, there is a user expectation that
the entire message content will be treated confidentially. To
address this expectation, the message submission server SHOULD use
STARTTLS or a mechanism providing equivalent data confidentiality
when fetching the content referenced by that URL.
A legitimate user of a submit server may try to compromise other
accounts on the server by providing an IMAP URLAUTH URL that points
to a server under that user's control that is designed to undermine
the security of the submit server. For this reason, the IMAP client
code that the submit server uses must be robust with respect to
arbitrary input sizes (including large IMAP literals) and arbitrary
delays from the IMAP server. Requiring a prearranged trust
relationship between a submit server and the IMAP server also
addresses this concern.
An authorized user of the submit server could set up a fraudulent
IMAP server and pass a URL for that server to the submit server. The
submit server might then contact the fraudulent IMAP server to
authenticate with submit credentials and fetch content. There are
several ways to mitigate this potential attack. A submit server that
only uses submit credentials with a fixed set of trusted IMAP servers
will not be vulnerable to exposure of those credentials. A submit
server can treat the IMAP server as untrusted and include defenses
for buffer overflows, denial-of-service slowdowns, and other
potential attacks. Finally, because authentication is required to
use BURL, it is possible to keep a secure audit trail and use that to
detect and punish the offending party.
Newman Standards Track [Page 10]
RFC 4468 Message Submission BURL Extension May 2006
9. References
9.1. Normative References
[RFC1652] Klensin, J., Freed, N., Rose, M., Stefferud, E., and D.
Crocker, "SMTP Service Extension for
8bit-MIMEtransport", RFC 1652, July 1994.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2192] Newman, C., "IMAP URL Scheme", RFC 2192,
September 1997.
[RFC2554] Myers, J., "SMTP Service Extension for Authentication",
RFC 2554, March 1999.
[RFC2821] Klensin, J., "Simple Mail Transfer Protocol", RFC 2821,
April 2001.
[RFC3207] Hoffman, P., "SMTP Service Extension for Secure SMTP
over Transport Layer Security", RFC 3207,
February 2002.
[RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL -
VERSION 4rev1", RFC 3501, March 2003.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter,
"Uniform Resource Identifier (URI): Generic Syntax",
STD 66, RFC 3986, January 2005.
[RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 4234, October 2005.
[RFC4409] Gellens, R. and J. Klensin, "Message Submission for
Mail", RFC 4409, April 2006.
[RFC4467] Crispin, M., "Internet Message Access Protocol (IMAP) -
URLAUTH Extension", RFC 4467, May 2006.
Newman Standards Track [Page 11]
RFC 4468 Message Submission BURL Extension May 2006
9.2. Informative References
[RFC2034] Freed, N., "SMTP Service Extension for Returning
Enhanced Error Codes", RFC 2034, October 1996.
[RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet
Mail Extensions (MIME) Part One: Format of Internet
Message Bodies", RFC 2045, November 1996.
[RFC2047] Moore, K., "MIME (Multipurpose Internet Mail
Extensions) Part Three: Message Header Extensions for
Non-ASCII Text", RFC 2047, November 1996.
[RFC2920] Freed, N., "SMTP Service Extension for Command
Pipelining", STD 60, RFC 2920, September 2000.
[RFC3030] Vaudreuil, G., "SMTP Service Extensions for
Transmission of Large and Binary MIME Messages",
RFC 3030, December 2000.
[RFC3463] Vaudreuil, G., "Enhanced Mail System Status Codes",
RFC 3463, January 2003.
[RFC4120] Neuman, C., Yu, T., Hartman, S., and K. Raeburn, "The
Kerberos Network Authentication Service (V5)", RFC
4120, July 2005.
[SASL-PLAIN] Zeilenga, K., "The Plain SASL Mechanism", Work in
Progress, March 2005.
Newman Standards Track [Page 12]
RFC 4468 Message Submission BURL Extension May 2006
Appendix A. Acknowledgements
This document is a product of the lemonade WG. Many thanks are due
to all the participants of that working group for their input. Mark
Crispin was instrumental in the conception of this mechanism. Thanks
to Randall Gellens, Alexey Melnikov, Sam Hartman, Ned Freed, Dave
Cridland, Peter Coates, and Mark Crispin for review comments on the
document. Thanks to the RFC Editor for correcting the author's
grammar mistakes. Thanks to Ted Hardie, Randall Gellens, Mark
Crispin, Pete Resnick, and Greg Vaudreuil for extremely interesting
debates comparing this proposal and alternatives. Thanks to the
lemonade WG chairs Eric Burger and Glenn Parsons for concluding the
debate at the correct time and making sure this document got
completed.
Author's Address
Chris Newman
Sun Microsystems
3401 Centrelake Dr., Suite 410
Ontario, CA 91761
US
EMail: chris.newman@sun.com
Newman Standards Track [Page 13]
RFC 4468 Message Submission BURL Extension May 2006
Full Copyright Statement
Copyright (C) The Internet Society (2006).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Acknowledgement
Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).
Newman Standards Track [Page 14]

731
docs/rfc/rfc4469.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]

507
docs/rfc/rfc4505.txt Normal file
View File

@ -0,0 +1,507 @@
Network Working Group K. Zeilenga, Ed.
Request for Comments: 4505 OpenLDAP Foundation
Obsoletes: 2245 June 2006
Category: Standards Track
Anonymous Simple Authentication and Security Layer (SASL) Mechanism
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2006).
Abstract
On the Internet, it is common practice to permit anonymous access to
various services. Traditionally, this has been done with a plain-
text password mechanism using "anonymous" as the user name and using
optional trace information, such as an email address, as the
password. As plain-text login commands are not permitted in new IETF
protocols, a new way to provide anonymous login is needed within the
context of the Simple Authentication and Security Layer (SASL)
framework.
1. Introduction
This document defines an anonymous mechanism for the Simple
Authentication and Security Layer ([SASL]) framework. The name
associated with this mechanism is "ANONYMOUS".
Unlike many other SASL mechanisms, whose purpose is to authenticate
and identify the user to a server, the purpose of this SASL mechanism
is to allow the user to gain access to services or resources without
requiring the user to establish or otherwise disclose their identity
to the server. That is, this mechanism provides an anonymous login
method.
This mechanism does not provide a security layer.
This document replaces RFC 2245. Changes since RFC 2245 are detailed
in Appendix A.
Zeilenga Standards Track [Page 1]
RFC 4505 Anonymous SASL Mechanism June 2006
2. The Anonymous Mechanism
The mechanism consists of a single message from the client to the
server. The client may include in this message trace information in
the form of a string of [UTF-8]-encoded [Unicode] characters prepared
in accordance with [StringPrep] and the "trace" stringprep profile
defined in Section 3 of this document. The trace information, which
has no semantical value, should take one of two forms: an Internet
email address, or an opaque string that does not contain the '@'
(U+0040) character and that can be interpreted by the system
administrator of the client's domain. For privacy reasons, an
Internet email address or other information identifying the user
should only be used with permission from the user.
A server that permits anonymous access will announce support for the
ANONYMOUS mechanism and allow anyone to log in using that mechanism,
usually with restricted access.
A formal grammar for the client message using Augmented BNF [ABNF] is
provided below as a tool for understanding this technical
specification.
message = [ email / token ]
;; to be prepared in accordance with Section 3
UTF1 = %x00-3F / %x41-7F ;; less '@' (U+0040)
UTF2 = %xC2-DF UTF0
UTF3 = %xE0 %xA0-BF UTF0 / %xE1-EC 2(UTF0) /
%xED %x80-9F UTF0 / %xEE-EF 2(UTF0)
UTF4 = %xF0 %x90-BF 2(UTF0) / %xF1-F3 3(UTF0) /
%xF4 %x80-8F 2(UTF0)
UTF0 = %x80-BF
TCHAR = UTF1 / UTF2 / UTF3 / UTF4
;; any UTF-8 encoded Unicode character
;; except '@' (U+0040)
email = addr-spec
;; as defined in [IMAIL]
token = 1*255TCHAR
Note to implementors:
The <token> production is restricted to 255 UTF-8-encoded Unicode
characters. As the encoding of a characters uses a sequence of 1
to 4 octets, a token may be as long as 1020 octets.
Zeilenga Standards Track [Page 2]
RFC 4505 Anonymous SASL Mechanism June 2006
3. The "trace" Profile of "Stringprep"
This section defines the "trace" profile of [StringPrep]. This
profile is designed for use with the SASL ANONYMOUS Mechanism.
Specifically, the client is to prepare the <message> production in
accordance with this profile.
The character repertoire of this profile is Unicode 3.2 [Unicode].
No mapping is required by this profile.
No Unicode normalization is required by this profile.
The list of unassigned code points for this profile is that provided
in Appendix A of [StringPrep]. Unassigned code points are not
prohibited.
Characters from the following tables of [StringPrep] are prohibited:
- C.2.1 (ASCII control characters)
- C.2.2 (Non-ASCII control characters)
- C.3 (Private use characters)
- C.4 (Non-character code points)
- C.5 (Surrogate codes)
- C.6 (Inappropriate for plain text)
- C.8 (Change display properties are deprecated)
- C.9 (Tagging characters)
No additional characters are prohibited.
This profile requires bidirectional character checking per Section 6
of [StringPrep].
4. Example
Here is a sample ANONYMOUS login between an IMAP client and server.
In this example, "C:" and "S:" indicate lines sent by the client and
server, respectively. If such lines are wrapped without a new "C:"
or "S:" label, then the wrapping is for editorial clarity and is not
part of the command.
Note that this example uses the IMAP profile [IMAP4] of SASL. The
base64 encoding of challenges and responses as well as the "+ "
preceding the responses are part of the IMAP4 profile, not part of
SASL itself. Additionally, protocols with SASL profiles permitting
an initial client response will be able to avoid the extra round trip
below (the server response with an empty "+ ").
Zeilenga Standards Track [Page 3]
RFC 4505 Anonymous SASL Mechanism June 2006
In this example, the trace information is "sirhc".
S: * OK IMAP4 server ready
C: A001 CAPABILITY
S: * CAPABILITY IMAP4 IMAP4rev1 AUTH=DIGEST-MD5 AUTH=ANONYMOUS
S: A001 OK done
C: A002 AUTHENTICATE ANONYMOUS
S: +
C: c2lyaGM=
S: A003 OK Welcome, trace information has been logged.
5. Security Considerations
The ANONYMOUS mechanism grants access to services and/or resources by
anyone. For this reason, it should be disabled by default so that
the administrator can make an explicit decision to enable it.
If the anonymous user has any write privileges, a denial-of-service
attack is possible by filling up all available space. This can be
prevented by disabling all write access by anonymous users.
If anonymous users have read and write access to the same area, the
server can be used as a communication mechanism to exchange
information anonymously. Servers that accept anonymous submissions
should implement the common "drop box" model, which forbids anonymous
read access to the area where anonymous submissions are accepted.
If the anonymous user can run many expensive operations (e.g., an
IMAP SEARCH BODY command), this could enable a denial-of-service
attack. Servers are encouraged to reduce the priority of anonymous
users or limit their resource usage.
While servers may impose a limit on the number of anonymous users,
note that such limits enable denial-of-service attacks and should be
used with caution.
The trace information is not authenticated, so it can be falsified.
This can be used as an attempt to get someone else in trouble for
access to questionable information. Administrators investigating
abuse need to realize that this trace information may be falsified.
A client that uses the user's correct email address as trace
information without explicit permission may violate that user's
privacy. Anyone who accesses an anonymous archive on a sensitive
subject (e.g., sexual abuse) likely has strong privacy needs.
Clients should not send the email address without the explicit
permission of the user and should offer the option of supplying no
trace information, thus only exposing the source IP address and time.
Zeilenga Standards Track [Page 4]
RFC 4505 Anonymous SASL Mechanism June 2006
Anonymous proxy servers could enhance this privacy but would have to
consider the resulting potential denial-of-service attacks.
Anonymous connections are susceptible to man-in-the-middle attacks
that view or alter the data transferred. Clients and servers are
encouraged to support external data security services.
Protocols that fail to require an explicit anonymous login are more
susceptible to break-ins given certain common implementation
techniques. Specifically, Unix servers that offer user login may
initially start up as root and switch to the appropriate user id
after an explicit login command. Normally, such servers refuse all
data access commands prior to explicit login and may enter a
restricted security environment (e.g., the Unix chroot(2) function)
for anonymous users. If anonymous access is not explicitly
requested, the entire data access machinery is exposed to external
security attacks without the chance for explicit protective measures.
Protocols that offer restricted data access should not allow
anonymous data access without an explicit login step.
General [SASL] security considerations apply to this mechanism.
[StringPrep] security considerations and [Unicode] security
considerations discussed in [StringPrep] apply to this mechanism.
[UTF-8] security considerations also apply.
6. IANA Considerations
The SASL Mechanism registry [IANA-SASL] entry for the ANONYMOUS
mechanism has been updated by the IANA to reflect that this document
now provides its technical specification.
To: iana@iana.org
Subject: Updated Registration of SASL mechanism ANONYMOUS
SASL mechanism name: ANONYMOUS
Security considerations: See RFC 4505.
Published specification (optional, recommended): RFC 4505
Person & email address to contact for further information:
Kurt Zeilenga <Kurt@OpenLDAP.org>
Chris Newman <Chris.Newman@sun.com>
Intended usage: COMMON
Author/Change controller: IESG <iesg@ietf.org>
Note: Updates existing entry for ANONYMOUS
Zeilenga Standards Track [Page 5]
RFC 4505 Anonymous SASL Mechanism June 2006
The [StringPrep] profile "trace", first defined in this RFC, has been
registered:
To: iana@iana.org
Subject: Initial Registration of Stringprep "trace" profile
Stringprep profile: trace
Published specification: RFC 4505
Person & email address to contact for further information:
Kurt Zeilenga <kurt@openldap.org>
7. Acknowledgement
This document is a revision of RFC 2245 by Chris Newman. Portions of
the grammar defined in Section 1 were borrowed from RFC 3629 by
Francois Yergeau.
This document is a product of the IETF SASL WG.
8. Normative References
[ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 4234, October 2005.
[IMAIL] Resnick, P., "Internet Message Format", RFC 2822, April
2001.
[SASL] Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple
Authentication and Security Layer (SASL)", RFC 4422,
June 2006.
[StringPrep] Hoffman, P. and M. Blanchet, "Preparation of
Internationalized Strings ('stringprep')", RFC 3454,
December 2002.
[Unicode] The Unicode Consortium, "The Unicode Standard, Version
3.2.0" is defined by "The Unicode Standard, Version 3.0"
(Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5),
as amended by the "Unicode Standard Annex #27: Unicode
3.1" (http://www.unicode.org/reports/tr27/) and by the
"Unicode Standard Annex #28: Unicode 3.2"
(http://www.unicode.org/reports/tr28/).
[UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO
10646", RFC 3629 (also STD 63), November 2003.
Zeilenga Standards Track [Page 6]
RFC 4505 Anonymous SASL Mechanism June 2006
9. Informative References
[IMAP4] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
4rev1", RFC 3501, March 2003.
[IANA-SASL] IANA, "SIMPLE AUTHENTICATION AND SECURITY LAYER (SASL)
MECHANISMS", <http://www.iana.org/assignments/sasl-
mechanisms>.
Zeilenga Standards Track [Page 7]
RFC 4505 Anonymous SASL Mechanism June 2006
Appendix A. Changes since RFC 2245
This appendix is non-normative.
RFC 2245 allows the client to include optional trace information in
the form of a human readable string. RFC 2245 restricted this string
to US-ASCII. As the Internet is international, this document uses a
string restricted to UTF-8 encoded Unicode characters. A
"stringprep" profile is defined to precisely define which Unicode
characters are allowed in this string. While the string remains
restricted to 255 characters, the encoded length of each character
may now range from 1 to 4 octets.
Additionally, a number of editorial changes were made.
Editor's Address
Kurt D. Zeilenga
OpenLDAP Foundation
EMail: Kurt@OpenLDAP.org
Zeilenga Standards Track [Page 8]
RFC 4505 Anonymous SASL Mechanism June 2006
Full Copyright Statement
Copyright (C) The Internet Society (2006).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Acknowledgement
Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).
Zeilenga Standards Track [Page 9]

1963
docs/rfc/rfc4549.txt Normal file
View File

File diff suppressed because it is too large Load Diff

1403
docs/rfc/rfc4551.txt Normal file
View File

File diff suppressed because it is too large Load Diff

619
docs/rfc/rfc4616.txt Normal file
View File

@ -0,0 +1,619 @@
Network Working Group K. Zeilenga, Ed.
Request for Comments: 4616 OpenLDAP Foundation
Updates: 2595 August 2006
Category: Standards Track
The PLAIN Simple Authentication and Security Layer (SASL) Mechanism
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2006).
Abstract
This document defines a simple clear-text user/password Simple
Authentication and Security Layer (SASL) mechanism called the PLAIN
mechanism. The PLAIN mechanism is intended to be used, in
combination with data confidentiality services provided by a lower
layer, in protocols that lack a simple password authentication
command.
Zeilenga Standards Track [Page 1]
RFC 4616 The PLAIN SASL Mechanism August 2006
1. Introduction
Clear-text, multiple-use passwords are simple, interoperate with
almost all existing operating system authentication databases, and
are useful for a smooth transition to a more secure password-based
authentication mechanism. The drawback is that they are unacceptable
for use over network connections where data confidentiality is not
ensured.
This document defines the PLAIN Simple Authentication and Security
Layer ([SASL]) mechanism for use in protocols with no clear-text
login command (e.g., [ACAP] or [SMTP-AUTH]). This document updates
RFC 2595, replacing Section 6. Changes since RFC 2595 are detailed
in Appendix A.
The name associated with this mechanism is "PLAIN".
The PLAIN SASL mechanism does not provide a security layer.
The PLAIN mechanism should not be used without adequate data security
protection as this mechanism affords no integrity or confidentiality
protections itself. The mechanism is intended to be used with data
security protections provided by application-layer protocol,
generally through its use of Transport Layer Security ([TLS])
services.
By default, implementations SHOULD advertise and make use of the
PLAIN mechanism only when adequate data security services are in
place. Specifications for IETF protocols that indicate that this
mechanism is an applicable authentication mechanism MUST mandate that
implementations support an strong data security service, such as TLS.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [Keywords].
2. PLAIN SASL Mechanism
The mechanism consists of a single message, a string of [UTF-8]
encoded [Unicode] characters, from the client to the server. The
client presents the authorization identity (identity to act as),
followed by a NUL (U+0000) character, followed by the authentication
identity (identity whose password will be used), followed by a NUL
(U+0000) character, followed by the clear-text password. As with
other SASL mechanisms, the client does not provide an authorization
identity when it wishes the server to derive an identity from the
credentials and use that as the authorization identity.
Zeilenga Standards Track [Page 2]
RFC 4616 The PLAIN SASL Mechanism August 2006
The formal grammar for the client message using Augmented BNF [ABNF]
follows.
message = [authzid] UTF8NUL authcid UTF8NUL passwd
authcid = 1*SAFE ; MUST accept up to 255 octets
authzid = 1*SAFE ; MUST accept up to 255 octets
passwd = 1*SAFE ; MUST accept up to 255 octets
UTF8NUL = %x00 ; UTF-8 encoded NUL character
SAFE = UTF1 / UTF2 / UTF3 / UTF4
;; any UTF-8 encoded Unicode character except NUL
UTF1 = %x01-7F ;; except NUL
UTF2 = %xC2-DF UTF0
UTF3 = %xE0 %xA0-BF UTF0 / %xE1-EC 2(UTF0) /
%xED %x80-9F UTF0 / %xEE-EF 2(UTF0)
UTF4 = %xF0 %x90-BF 2(UTF0) / %xF1-F3 3(UTF0) /
%xF4 %x80-8F 2(UTF0)
UTF0 = %x80-BF
The authorization identity (authzid), authentication identity
(authcid), password (passwd), and NUL character deliminators SHALL be
transferred as [UTF-8] encoded strings of [Unicode] characters. As
the NUL (U+0000) character is used as a deliminator, the NUL (U+0000)
character MUST NOT appear in authzid, authcid, or passwd productions.
The form of the authzid production is specific to the application-
level protocol's SASL profile [SASL]. The authcid and passwd
productions are form-free. Use of non-visible characters or
characters that a user may be unable to enter on some keyboards is
discouraged.
Servers MUST be capable of accepting authzid, authcid, and passwd
productions up to and including 255 octets. It is noted that the
UTF-8 encoding of a Unicode character may be as long as 4 octets.
Upon receipt of the message, the server will verify the presented (in
the message) authentication identity (authcid) and password (passwd)
with the system authentication database, and it will verify that the
authentication credentials permit the client to act as the (presented
or derived) authorization identity (authzid). If both steps succeed,
the user is authenticated.
The presented authentication identity and password strings, as well
as the database authentication identity and password strings, are to
be prepared before being used in the verification process. The
[SASLPrep] profile of the [StringPrep] algorithm is the RECOMMENDED
preparation algorithm. The SASLprep preparation algorithm is
Zeilenga Standards Track [Page 3]
RFC 4616 The PLAIN SASL Mechanism August 2006
recommended to improve the likelihood that comparisons behave in an
expected manner. The SASLprep preparation algorithm is not mandatory
so as to allow the server to employ other preparation algorithms
(including none) when appropriate. For instance, use of a different
preparation algorithm may be necessary for the server to interoperate
with an external system.
When preparing the presented strings using [SASLPrep], the presented
strings are to be treated as "query" strings (Section 7 of
[StringPrep]) and hence unassigned code points are allowed to appear
in their prepared output. When preparing the database strings using
[SASLPrep], the database strings are to be treated as "stored"
strings (Section 7 of [StringPrep]) and hence unassigned code points
are prohibited from appearing in their prepared output.
Regardless of the preparation algorithm used, if the output of a
non-invertible function (e.g., hash) of the expected string is
stored, the string MUST be prepared before input to that function.
Regardless of the preparation algorithm used, if preparation fails or
results in an empty string, verification SHALL fail.
When no authorization identity is provided, the server derives an
authorization identity from the prepared representation of the
provided authentication identity string. This ensures that the
derivation of different representations of the authentication
identity produces the same authorization identity.
The server MAY use the credentials to initialize any new
authentication database, such as one suitable for [CRAM-MD5] or
[DIGEST-MD5].
3. Pseudo-Code
This section provides pseudo-code illustrating the verification
process (using hashed passwords and the SASLprep preparation
function) discussed above. This section is not definitive.
boolean Verify(string authzid, string authcid, string passwd) {
string pAuthcid = SASLprep(authcid, true); # prepare authcid
string pPasswd = SASLprep(passwd, true); # prepare passwd
if (pAuthcid == NULL || pPasswd == NULL) {
return false; # preparation failed
}
if (pAuthcid == "" || pPasswd == "") {
return false; # empty prepared string
}
Zeilenga Standards Track [Page 4]
RFC 4616 The PLAIN SASL Mechanism August 2006
storedHash = FetchPasswordHash(pAuthcid);
if (storedHash == NULL || storedHash == "") {
return false; # error or unknown authcid
}
if (!Compare(storedHash, Hash(pPasswd))) {
return false; # incorrect password
}
if (authzid == NULL ) {
authzid = DeriveAuthzid(pAuthcid);
if (authzid == NULL || authzid == "") {
return false; # could not derive authzid
}
}
if (!Authorize(pAuthcid, authzid)) {
return false; # not authorized
}
return true;
}
The second parameter of the SASLprep function, when true, indicates
that unassigned code points are allowed in the input. When the
SASLprep function is called to prepare the password prior to
computing the stored hash, the second parameter would be false.
The second parameter provided to the Authorize function is not
prepared by this code. The application-level SASL profile should be
consulted to determine what, if any, preparation is necessary.
Note that the DeriveAuthzid and Authorize functions (whether
implemented as one function or two, whether designed in a manner in
which these functions or whether the mechanism implementation can be
reused elsewhere) require knowledge and understanding of mechanism
and the application-level protocol specification and/or
implementation details to implement.
Note that the Authorize function outcome is clearly dependent on
details of the local authorization model and policy. Both functions
may be dependent on other factors as well.
Zeilenga Standards Track [Page 5]
RFC 4616 The PLAIN SASL Mechanism August 2006
4. Examples
This section provides examples of PLAIN authentication exchanges.
The examples are intended to help the readers understand the above
text. The examples are not definitive.
"C:" and "S:" indicate lines sent by the client and server,
respectively. "<NUL>" represents a single NUL (U+0000) character.
The Application Configuration Access Protocol ([ACAP]) is used in the
examples.
The first example shows how the PLAIN mechanism might be used for
user authentication.
S: * ACAP (SASL "CRAM-MD5") (STARTTLS)
C: a001 STARTTLS
S: a001 OK "Begin TLS negotiation now"
<TLS negotiation, further commands are under TLS layer>
S: * ACAP (SASL "CRAM-MD5" "PLAIN")
C: a002 AUTHENTICATE "PLAIN"
S: + ""
C: {21}
C: <NUL>tim<NUL>tanstaaftanstaaf
S: a002 OK "Authenticated"
The second example shows how the PLAIN mechanism might be used to
attempt to assume the identity of another user. In this example, the
server rejects the request. Also, this example makes use of the
protocol optional initial response capability to eliminate a round-
trip.
S: * ACAP (SASL "CRAM-MD5") (STARTTLS)
C: a001 STARTTLS
S: a001 OK "Begin TLS negotiation now"
<TLS negotiation, further commands are under TLS layer>
S: * ACAP (SASL "CRAM-MD5" "PLAIN")
C: a002 AUTHENTICATE "PLAIN" {20+}
C: Ursel<NUL>Kurt<NUL>xipj3plmq
S: a002 NO "Not authorized to requested authorization identity"
5. Security Considerations
As the PLAIN mechanism itself provided no integrity or
confidentiality protections, it should not be used without adequate
external data security protection, such as TLS services provided by
many application-layer protocols. By default, implementations SHOULD
NOT advertise and SHOULD NOT make use of the PLAIN mechanism unless
adequate data security services are in place.
Zeilenga Standards Track [Page 6]
RFC 4616 The PLAIN SASL Mechanism August 2006
When the PLAIN mechanism is used, the server gains the ability to
impersonate the user to all services with the same password
regardless of any encryption provided by TLS or other confidentiality
protection mechanisms. Whereas many other authentication mechanisms
have similar weaknesses, stronger SASL mechanisms address this issue.
Clients are encouraged to have an operational mode where all
mechanisms that are likely to reveal the user's password to the
server are disabled.
General [SASL] security considerations apply to this mechanism.
Unicode, [UTF-8], and [StringPrep] security considerations also
apply.
6. IANA Considerations
The SASL Mechanism registry [IANA-SASL] entry for the PLAIN mechanism
has been updated by the IANA to reflect that this document now
provides its technical specification.
To: iana@iana.org
Subject: Updated Registration of SASL mechanism PLAIN
SASL mechanism name: PLAIN
Security considerations: See RFC 4616.
Published specification (optional, recommended): RFC 4616
Person & email address to contact for further information:
Kurt Zeilenga <kurt@openldap.org>
IETF SASL WG <ietf-sasl@imc.org>
Intended usage: COMMON
Author/Change controller: IESG <iesg@ietf.org>
Note: Updates existing entry for PLAIN
7. Acknowledgements
This document is a revision of RFC 2595 by Chris Newman. Portions of
the grammar defined in Section 2 were borrowed from [UTF-8] by
Francois Yergeau.
This document is a product of the IETF Simple Authentication and
Security Layer (SASL) Working Group.
Zeilenga Standards Track [Page 7]
RFC 4616 The PLAIN SASL Mechanism August 2006
8. Normative References
[ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for
Syntax Specifications: ABNF", RFC 4234, October 2005.
[Keywords] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[SASL] Melnikov, A., Ed., and K. Zeilenga, Ed., "Simple
Authentication and Security Layer (SASL)", RFC 4422,
June 2006.
[SASLPrep] Zeilenga, K., "SASLprep: Stringprep Profile for User
Names and Passwords", RFC 4013, February 2005.
[StringPrep] Hoffman, P. and M. Blanchet, "Preparation of
Internationalized Strings ("stringprep")", RFC 3454,
December 2002.
[Unicode] The Unicode Consortium, "The Unicode Standard, Version
3.2.0" is defined by "The Unicode Standard, Version
3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-
61633-5), as amended by the "Unicode Standard Annex
#27: Unicode 3.1"
(http://www.unicode.org/reports/tr27/) and by the
"Unicode Standard Annex #28: Unicode 3.2"
(http://www.unicode.org/reports/tr28/).
[UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003.
[TLS] Dierks, T. and E. Rescorla, "The Transport Layer
Security (TLS) Protocol Version 1.1", RFC 4346, April
2006.
9. Informative References
[ACAP] Newman, C. and J. Myers, "ACAP -- Application
Configuration Access Protocol", RFC 2244, November
1997.
[CRAM-MD5] Nerenberg, L., Ed., "The CRAM-MD5 SASL Mechanism", Work
in Progress, June 2006.
[DIGEST-MD5] Melnikov, A., Ed., "Using Digest Authentication as a
SASL Mechanism", Work in Progress, June 2006.
Zeilenga Standards Track [Page 8]
RFC 4616 The PLAIN SASL Mechanism August 2006
[IANA-SASL] IANA, "SIMPLE AUTHENTICATION AND SECURITY LAYER (SASL)
MECHANISMS",
<http://www.iana.org/assignments/sasl-mechanisms>.
[SMTP-AUTH] Myers, J., "SMTP Service Extension for Authentication",
RFC 2554, March 1999.
Zeilenga Standards Track [Page 9]
RFC 4616 The PLAIN SASL Mechanism August 2006
Appendix A. Changes since RFC 2595
This appendix is non-normative.
This document replaces Section 6 of RFC 2595.
The specification details how the server is to compare client-
provided character strings with stored character strings.
The ABNF grammar was updated. In particular, the grammar now allows
LINE FEED (U+000A) and CARRIAGE RETURN (U+000D) characters in the
authzid, authcid, passwd productions. However, whether these control
characters may be used depends on the string preparation rules
applicable to the production. For passwd and authcid productions,
control characters are prohibited. For authzid, one must consult the
application-level SASL profile. This change allows PLAIN to carry
all possible authorization identity strings allowed in SASL.
Pseudo-code was added.
The example section was expanded to illustrate more features of the
PLAIN mechanism.
Editor's Address
Kurt D. Zeilenga
OpenLDAP Foundation
EMail: Kurt@OpenLDAP.org
Zeilenga Standards Track [Page 10]
RFC 4616 The PLAIN SASL Mechanism August 2006
Full Copyright Statement
Copyright (C) The Internet Society (2006).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Acknowledgement
Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).
Zeilenga Standards Track [Page 11]

451
docs/rfc/rfc4731.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]

563
docs/rfc/rfc4752.txt Normal file
View File

@ -0,0 +1,563 @@
Network Working Group A. Melnikov, Ed.
Request for Comments: 4752 Isode
Obsoletes: 2222 November 2006
Category: Standards Track
The Kerberos V5 ("GSSAPI")
Simple Authentication and Security Layer (SASL) Mechanism
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The IETF Trust (2006).
Abstract
The Simple Authentication and Security Layer (SASL) is a framework
for adding authentication support to connection-based protocols.
This document describes the method for using the Generic Security
Service Application Program Interface (GSS-API) Kerberos V5 in the
SASL.
This document replaces Section 7.2 of RFC 2222, the definition of the
"GSSAPI" SASL mechanism. This document, together with RFC 4422,
obsoletes RFC 2222.
Melnikov Standards Track [Page 1]
RFC 4752 SASL GSSAPI Mechanism November 2006
Table of Contents
1. Introduction ....................................................2
1.1. Relationship to Other Documents ............................2
2. Conventions Used in This Document ...............................2
3. Kerberos V5 GSS-API Mechanism ...................................2
3.1. Client Side of Authentication Protocol Exchange ............3
3.2. Server Side of Authentication Protocol Exchange ............4
3.3. Security Layer .............................................6
4. IANA Considerations .............................................7
5. Security Considerations .........................................7
6. Acknowledgements ................................................8
7. Changes since RFC 2222 ..........................................8
8. References ......................................................8
8.1. Normative References .......................................8
8.2. Informative References .....................................9
1. Introduction
This specification documents currently deployed Simple Authentication
and Security Layer (SASL [SASL]) mechanism supporting the Kerberos V5
[KERBEROS] Generic Security Service Application Program Interface
([GSS-API]) mechanism [RFC4121]. The authentication sequence is
described in Section 3. Note that the described authentication
sequence has known limitations, in particular, it lacks channel
bindings and the number of round-trips required to complete
authentication exchange is not minimal. SASL WG is working on a
separate document that should address these limitations.
1.1. Relationship to Other Documents
This document, together with RFC 4422, obsoletes RFC 2222 in its
entirety. This document replaces Section 7.2 of RFC 2222. The
remainder is obsoleted as detailed in Section 1.2 of RFC 4422.
2. Conventions Used in This Document
The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
in this document are to be interpreted as defined in "Key words for
use in RFCs to Indicate Requirement Levels" [KEYWORDS].
3. Kerberos V5 GSS-API Mechanism
The SASL mechanism name for the Kerberos V5 GSS-API mechanism
[RFC4121] is "GSSAPI". Though known as the SASL GSSAPI mechanism,
the mechanism is specifically tied to Kerberos V5 and GSS-API's
Kerberos V5 mechanism.
Melnikov Standards Track [Page 2]
RFC 4752 SASL GSSAPI Mechanism November 2006
The GSSAPI SASL mechanism is a "client goes first" SASL mechanism;
i.e., it starts with the client sending a "response" created as
described in the following section.
The implementation MAY set any GSS-API flags or arguments not
mentioned in this specification as is necessary for the
implementation to enforce its security policy.
Note that major status codes returned by GSS_Init_sec_context() or
GSS_Accept_sec_context() other than GSS_S_COMPLETE or
GSS_S_CONTINUE_NEEDED cause authentication failure. Major status
codes returned by GSS_Unwrap() other than GSS_S_COMPLETE (without any
additional supplementary status codes) cause authentication and/or
security layer failure.
3.1. Client Side of Authentication Protocol Exchange
The client calls GSS_Init_sec_context, passing in
input_context_handle of 0 (initially), mech_type of the Kerberos V5
GSS-API mechanism [KRB5GSS], chan_binding of NULL, and targ_name
equal to output_name from GSS_Import_Name called with input_name_type
of GSS_C_NT_HOSTBASED_SERVICE (*) and input_name_string of
"service@hostname" where "service" is the service name specified in
the protocol's profile, and "hostname" is the fully qualified host
name of the server. When calling the GSS_Init_sec_context, the
client MUST pass the integ_req_flag of TRUE (**). If the client will
be requesting a security layer, it MUST also supply to the
GSS_Init_sec_context a mutual_req_flag of TRUE, and a
sequence_req_flag of TRUE. If the client will be requesting a
security layer providing confidentiality protection, it MUST also
supply to the GSS_Init_sec_context a conf_req_flag of TRUE. The
client then responds with the resulting output_token. If
GSS_Init_sec_context returns GSS_S_CONTINUE_NEEDED, then the client
should expect the server to issue a token in a subsequent challenge.
The client must pass the token to another call to
GSS_Init_sec_context, repeating the actions in this paragraph.
(*) Clients MAY use name types other than GSS_C_NT_HOSTBASED_SERVICE
to import servers' acceptor names, but only when they have a priori
knowledge that the servers support alternate name types. Otherwise
clients MUST use GSS_C_NT_HOSTBASED_SERVICE for importing acceptor
names.
(**) Note that RFC 2222 [RFC2222] implementations will not work with
GSS-API implementations that require integ_req_flag to be true. No
implementations of RFC 1964 [KRB5GSS] or RFC 4121 [RFC4121] that
require integ_req_flag to be true are believed to exist and it is
expected that any future update to [RFC4121] will require that
Melnikov Standards Track [Page 3]
RFC 4752 SASL GSSAPI Mechanism November 2006
integrity be available even in not explicitly requested by the
application.
When GSS_Init_sec_context returns GSS_S_COMPLETE, the client examines
the context to ensure that it provides a level of protection
permitted by the client's security policy. In particular, if the
integ_avail flag is not set in the context, then no security layer
can be offered or accepted.
If the conf_avail flag is not set in the context, then no security
layer with confidentiality can be offered or accepted. If the
context is acceptable, the client takes the following actions: If the
last call to GSS_Init_sec_context returned an output_token, then the
client responds with the output_token, otherwise the client responds
with no data. The client should then expect the server to issue a
token in a subsequent challenge. The client passes this token to
GSS_Unwrap and interprets the first octet of resulting cleartext as a
bit-mask specifying the security layers supported by the server and
the second through fourth octets as the maximum size output_message
the server is able to receive (in network byte order). If the
resulting cleartext is not 4 octets long, the client fails the
negotiation. The client verifies that the server maximum buffer is 0
if the server does not advertise support for any security layer.
The client then constructs data, with the first octet containing the
bit-mask specifying the selected security layer, the second through
fourth octets containing in network byte order the maximum size
output_message the client is able to receive (which MUST be 0 if the
client does not support any security layer), and the remaining octets
containing the UTF-8 [UTF8] encoded authorization identity.
(Implementation note: The authorization identity is not terminated
with the zero-valued (%x00) octet (e.g., the UTF-8 encoding of the
NUL (U+0000) character)). The client passes the data to GSS_Wrap
with conf_flag set to FALSE and responds with the generated
output_message. The client can then consider the server
authenticated.
3.2. Server Side of Authentication Protocol Exchange
A server MUST NOT advertise support for the "GSSAPI" SASL mechanism
described in this document unless it has acceptor credential for the
Kerberos V GSS-API mechanism [KRB5GSS].
The server passes the initial client response to
GSS_Accept_sec_context as input_token, setting input_context_handle
to 0 (initially), chan_binding of NULL, and a suitable
acceptor_cred_handle (see below). If GSS_Accept_sec_context returns
GSS_S_CONTINUE_NEEDED, the server returns the generated output_token
Melnikov Standards Track [Page 4]
RFC 4752 SASL GSSAPI Mechanism November 2006
to the client in challenge and passes the resulting response to
another call to GSS_Accept_sec_context, repeating the actions in this
paragraph.
Servers SHOULD use a credential obtained by calling GSS_Acquire_cred
or GSS_Add_cred for the GSS_C_NO_NAME desired_name and the Object
Identifier (OID) of the Kerberos V5 GSS-API mechanism [KRB5GSS](*).
Servers MAY use GSS_C_NO_CREDENTIAL as an acceptor credential handle.
Servers MAY use a credential obtained by calling GSS_Acquire_cred or
GSS_Add_cred for the server's principal name(s) (**) and the Kerberos
V5 GSS-API mechanism [KRB5GSS].
(*) Unlike GSS_Add_cred the GSS_Acquire_cred uses an OID set of GSS-
API mechanism as an input parameter. The OID set can be created by
using GSS_Create_empty_OID_set and GSS_Add_OID_set_member. It can be
freed by calling the GSS_Release_oid_set.
(**) Use of server's principal names having
GSS_C_NT_HOSTBASED_SERVICE name type and "service@hostname" format,
where "service" is the service name specified in the protocol's
profile, and "hostname" is the fully qualified host name of the
server, is RECOMMENDED. The server name is generated by calling
GSS_Import_name with input_name_type of GSS_C_NT_HOSTBASED_SERVICE
and input_name_string of "service@hostname".
Upon successful establishment of the security context (i.e.,
GSS_Accept_sec_context returns GSS_S_COMPLETE), the server SHOULD
verify that the negotiated GSS-API mechanism is indeed Kerberos V5
[KRB5GSS]. This is done by examining the value of the mech_type
parameter returned from the GSS_Accept_sec_context call. If the
value differs, SASL authentication MUST be aborted.
Upon successful establishment of the security context and if the
server used GSS_C_NO_NAME/GSS_C_NO_CREDENTIAL to create acceptor
credential handle, the server SHOULD also check using the
GSS_Inquire_context that the target_name used by the client matches
either
- the GSS_C_NT_HOSTBASED_SERVICE "service@hostname" name syntax,
where "service" is the service name specified in the application
protocol's profile,
or
- the GSS_KRB5_NT_PRINCIPAL_NAME [KRB5GSS] name syntax for a two-
component principal where the first component matches the service
name specified in the application protocol's profile.
Melnikov Standards Track [Page 5]
RFC 4752 SASL GSSAPI Mechanism November 2006
When GSS_Accept_sec_context returns GSS_S_COMPLETE, the server
examines the context to ensure that it provides a level of protection
permitted by the server's security policy. In particular, if the
integ_avail flag is not set in the context, then no security layer
can be offered or accepted. If the conf_avail flag is not set in the
context, then no security layer with confidentiality can be offered
or accepted.
If the context is acceptable, the server takes the following actions:
If the last call to GSS_Accept_sec_context returned an output_token,
the server returns it to the client in a challenge and expects a
reply from the client with no data. Whether or not an output_token
was returned (and after receipt of any response from the client to
such an output_token), the server then constructs 4 octets of data,
with the first octet containing a bit-mask specifying the security
layers supported by the server and the second through fourth octets
containing in network byte order the maximum size output_token the
server is able to receive (which MUST be 0 if the server does not
support any security layer). The server must then pass the plaintext
to GSS_Wrap with conf_flag set to FALSE and issue the generated
output_message to the client in a challenge.
The server must then pass the resulting response to GSS_Unwrap and
interpret the first octet of resulting cleartext as the bit-mask for
the selected security layer, the second through fourth octets as the
maximum size output_message the client is able to receive (in network
byte order), and the remaining octets as the authorization identity.
The server verifies that the client has selected a security layer
that was offered and that the client maximum buffer is 0 if no
security layer was chosen. The server must verify that the src_name
is authorized to act as the authorization identity. After these
verifications, the authentication process is complete. The server is
not expected to return any additional data with the success
indicator.
3.3. Security Layer
The security layers and their corresponding bit-masks are as follows:
1 No security layer
2 Integrity protection.
Sender calls GSS_Wrap with conf_flag set to FALSE
4 Confidentiality protection.
Sender calls GSS_Wrap with conf_flag set to TRUE
Other bit-masks may be defined in the future; bits that are not
understood must be negotiated off.
Melnikov Standards Track [Page 6]
RFC 4752 SASL GSSAPI Mechanism November 2006
When decoding any received data with GSS_Unwrap, the major_status
other than the GSS_S_COMPLETE MUST be treated as a fatal error.
Note that SASL negotiates the maximum size of the output_message to
send. Implementations can use the GSS_Wrap_size_limit call to
determine the corresponding maximum size input_message.
4. IANA Considerations
IANA modified the existing registration for "GSSAPI" as follows:
Family of SASL mechanisms: NO
SASL mechanism name: GSSAPI
Security considerations: See Section 5 of RFC 4752
Published specification: RFC 4752
Person & email address to contact for further information:
Alexey Melnikov <Alexey.Melnikov@isode.com>
Intended usage: COMMON
Owner/Change controller: iesg@ietf.org
Additional information: This mechanism is for the Kerberos V5
mechanism of GSS-API.
5. Security Considerations
Security issues are discussed throughout this memo.
When constructing the input_name_string, the client SHOULD NOT
canonicalize the server's fully qualified domain name using an
insecure or untrusted directory service.
For compatibility with deployed software, this document requires that
the chan_binding (channel bindings) parameter to GSS_Init_sec_context
and GSS_Accept_sec_context be NULL, hence disallowing use of GSS-API
support for channel bindings. GSS-API channel bindings in SASL is
expected to be supported via a new GSS-API family of SASL mechanisms
(to be introduced in a future document).
Additional security considerations are in the [SASL] and [GSS-API]
specifications. Additional security considerations for the GSS-API
mechanism can be found in [KRB5GSS] and [KERBEROS].
Melnikov Standards Track [Page 7]
RFC 4752 SASL GSSAPI Mechanism November 2006
6. Acknowledgements
This document replaces Section 7.2 of RFC 2222 [RFC2222] by John G.
Myers. He also contributed significantly to this revision.
Lawrence Greenfield converted text of this document to the XML
format.
Contributions of many members of the SASL mailing list are gratefully
acknowledged, in particular comments from Chris Newman, Nicolas
Williams, Jeffrey Hutzelman, Sam Hartman, Mark Crispin, and Martin
Rex.
7. Changes since RFC 2222
RFC 2078 [RFC2078] specifies the version of GSS-API used by RFC 2222
[RFC2222], which provided the original version of this specification.
That version of GSS-API did not provide the integ_integ_avail flag as
an input to GSS_Init_sec_context. Instead, integrity was always
requested. RFC 4422 [SASL] requires that when possible, the security
layer negotiation be integrity protected. To meet this requirement
and as part of moving from RFC 2078 [RFC2078] to RFC 2743 [GSS-API],
this specification requires that clients request integrity from
GSS_Init_sec_context so they can use GSS_Wrap to protect the security
layer negotiation. This specification does not require that the
mechanism offer the integrity security layer, simply that the
security layer negotiation be wrapped.
8. References
8.1. Normative References
[GSS-API] Linn, J., "Generic Security Service Application Program
Interface Version 2, Update 1", RFC 2743, January 2000.
[KERBEROS] Neuman, C., Yu, T., Hartman, S., and K. Raeburn, "The
Kerberos Network Authentication Service (V5)", RFC 4120,
July 2005.
[KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[KRB5GSS] Linn, J., "The Kerberos Version 5 GSS-API Mechanism", RFC
1964, June 1996.
Melnikov Standards Track [Page 8]
RFC 4752 SASL GSSAPI Mechanism November 2006
[RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos
Version 5 Generic Security Service Application Program
Interface (GSS-API) Mechanism: Version 2", RFC 4121, July
2005.
[SASL] Melnikov, A. and K. Zeilenga, "Simple Authentication and
Security Layer (SASL)", RFC 4422, June 2006.
[UTF8] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003.
8.2. Informative References
[RFC2078] Linn, J., "Generic Security Service Application Program
Interface, Version 2", RFC 2078, January 1997.
[RFC2222] Myers, J., "Simple Authentication and Security Layer
(SASL)", RFC 2222, October 1997.
Editor's Address
Alexey Melnikov
Isode Limited
5 Castle Business Village
36 Station Road
Hampton, Middlesex TW12 2BX
UK
EMail: Alexey.Melnikov@isode.com
URI: http://www.melnikov.ca/
Melnikov Standards Track [Page 9]
RFC 4752 SASL GSSAPI Mechanism November 2006
Full Copyright Statement
Copyright (C) The IETF Trust (2006).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST,
AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT
THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY
IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.
Melnikov Standards Track [Page 10]

1459
docs/rfc/rfc4790.txt Normal file
View File

File diff suppressed because it is too large Load Diff

395
docs/rfc/rfc4959.txt Normal file
View File

@ -0,0 +1,395 @@
Network Working Group R. Siemborski
Request for Comments: 4959 Google, Inc.
Category: Standards Track A. Gulbrandsen
Oryx Mail Systems GmbH
September 2007
IMAP Extension for Simple Authentication and Security Layer (SASL)
Initial Client Response
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Abstract
To date, the Internet Message Access Protocol (IMAP) has used a
Simple Authentication and Security Layer (SASL) profile which always
required at least one complete round trip for an authentication, as
it did not support an initial client response argument. This
additional round trip at the beginning of the session is undesirable,
especially when round-trip costs are high.
This document defines an extension to IMAP which allows clients and
servers to avoid this round trip by allowing an initial client
response argument to the IMAP AUTHENTICATE command.
Siemborski & Gulbrandsen Standards Track [Page 1]
RFC 4959 IMAP Ext for SASL Initial Client Response September 2007
1. Introduction
The SASL initial client response extension is present in any IMAP
[RFC3501] server implementation which returns "SASL-IR" as one of the
supported capabilities in its CAPABILITY response.
Servers which support this extension will accept an optional initial
client response with the AUTHENTICATE command for any SASL [RFC4422]
mechanisms which support it.
2. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
In examples, "C:" and "S:" indicate lines sent by the client and
server, respectively.
Formal syntax is defined by [RFC4234] as extended by [RFC3501].
3. IMAP Changes to the IMAP AUTHENTICATE Command
This extension adds an optional second argument to the AUTHENTICATE
command that is defined in Section 6.2.2 of [RFC3501]. If this
second argument is present, it represents the contents of the
"initial client response" defined in Section 5.1 of [RFC4422].
As with any other client response, this initial client response MUST
be encoded as defined in Section 4 of [RFC4648]. It also MUST be
transmitted outside of a quoted string or literal. To send a zero-
length initial response, the client MUST send a single pad character
("="). This indicates that the response is present, but is a zero-
length string.
When decoding the BASE64 [RFC4648] data in the initial client
response, decoding errors MUST be treated as IMAP [RFC3501] would
handle them in any normal SASL client response. In particular, the
server should check for any characters not explicitly allowed by the
BASE64 alphabet, as well as any sequence of BASE64 characters that
contains the pad character ('=') anywhere other than the end of the
string (e.g., "=AAA" and "AAA=BBB" are not allowed).
If the client uses an initial response with a SASL mechanism that
does not support an initial response, the server MUST reject the
command with a tagged BAD response.
Siemborski & Gulbrandsen Standards Track [Page 2]
RFC 4959 IMAP Ext for SASL Initial Client Response September 2007
Note: support and use of the initial client response is optional for
both clients and servers. Servers that implement this extension MUST
support clients that omit the initial client response, and clients
that implement this extension MUST NOT send an initial client
response to servers that do not advertise the SASL-IR capability. In
such a situation, clients MUST fall back to an IMAP [RFC3501]
compatible mode.
If either the client or the server do not support the SASL-IR
capability, a mechanism which uses an initial client response is
negotiated using the challenge/response exchange described in
[RFC3501], with an initial zero-length server challenge.
4. Examples
The following is an example authentication using the PLAIN (see
[RFC4616]) SASL mechanism (under a TLS protection layer, see
[RFC4346]) and an initial client response:
... client connects to server and negotiates a TLS
protection layer ...
C: C01 CAPABILITY
S: * CAPABILITY IMAP4rev1 SASL-IR AUTH=PLAIN
S: C01 OK Completed
C: A01 AUTHENTICATE PLAIN dGVzdAB0ZXN0AHRlc3Q=
S: A01 OK Success (tls protection)
Note that even when a server supports this extension, the following
negotiation (which does not use the initial response) is still valid
and MUST be supported by the server:
... client connects to server and negotiates a TLS
protection layer ...
C: C01 CAPABILITY
S: * CAPABILITY IMAP4rev1 SASL-IR AUTH=PLAIN
S: C01 OK Completed
C: A01 AUTHENTICATE PLAIN
(note that there is a space following the "+" in the
following line)
S: +
C: dGVzdAB0ZXN0AHRlc3Q=
S: A01 OK Success (tls protection)
The following is an example authentication using the SASL EXTERNAL
mechanism (defined in [RFC4422]) under a TLS protection layer (see
[RFC4346]) and an empty initial client response:
Siemborski & Gulbrandsen Standards Track [Page 3]
RFC 4959 IMAP Ext for SASL Initial Client Response September 2007
... client connects to server and negotiates a TLS
protection layer ...
C: C01 CAPABILITY
S: * CAPABILITY IMAP4rev1 SASL-IR AUTH=PLAIN AUTH=EXTERNAL
S: C01 OK Completed
C: A01 AUTHENTICATE EXTERNAL =
S: A01 OK Success (tls protection)
This is in contrast with the handling of such a situation when an
initial response is omitted:
... client connects to server and negotiates a TLS protection
layer ...
C: C01 CAPABILITY
S: * CAPABILITY IMAP4rev1 SASL-IR AUTH=PLAIN AUTH=EXTERNAL
S: C01 OK Completed
C: A01 AUTHENTICATE EXTERNAL
(note that there is a space following the "+" in the
following line)
S: +
C:
S: A01 OK Success (tls protection)
5. IANA Considerations
The IANA has added SASL-IR to the IMAP4 Capabilities Registry.
6. Security Considerations
The extension defined in this document is subject to many of the
Security Considerations defined in [RFC3501] and [RFC4422].
Server implementations MUST treat the omission of an initial client
response from the AUTHENTICATE command as defined by [RFC3501] (as if
this extension did not exist).
Although [RFC3501] has no express line length limitations, some
implementations choose to enforce them anyway. Such implementations
MUST be aware that the addition of the initial response parameter to
AUTHENTICATE may increase the maximum line length that IMAP parsers
may expect to support. Server implementations MUST be able to
receive the largest possible initial client response that their
supported mechanisms might receive.
Siemborski & Gulbrandsen Standards Track [Page 4]
RFC 4959 IMAP Ext for SASL Initial Client Response September 2007
7. Formal Syntax
The following syntax specification uses the Augmented Backus-Naur
Form [RFC4234] notation. [RFC3501] defines the non-terminals
capability, auth-type, and base64.
capability =/ "SASL-IR"
authenticate = "AUTHENTICATE" SP auth-type [SP (base64 / "=")]
*(CRLF base64)
;;redefine AUTHENTICATE from [RFC3501]
8. Acknowledgments
The authors would like to acknowledge the contributions of Ken
Murchison and Mark Crispin, along with the rest of the IMAPEXT
Working Group for their assistance in reviewing this document.
Alexey Melnikov and Cyrus Daboo also had some early discussions about
this extension.
9. References
9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
4rev1", RFC 3501, March 2003.
[RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 4234, October 2005.
[RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication and
Security Layer (SASL)", RFC 4422, June 2006.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, October 2006.
9.2. Informative References
[RFC4616] Zeilenga, K., "The PLAIN Simple Authentication and
Security Layer (SASL) Mechanism", RFC 4616, August 2006.
[RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.1", RFC 4346, April 2006.
Siemborski & Gulbrandsen Standards Track [Page 5]
RFC 4959 IMAP Ext for SASL Initial Client Response September 2007
Authors' Addresses
Robert Siemborski
Google, Inc.
1600 Ampitheatre Parkway
Mountain View, CA 94043
Phone: +1 650 623 6925
EMail: robsiemb@google.com
Arnt Gulbrandsen
Oryx Mail Systems GmbH
Schweppermannstr. 8
D-81671 Muenchen
Germany
EMail: arnt@oryx.com
Siemborski & Gulbrandsen Standards Track [Page 6]
RFC 4959 IMAP Ext for SASL Initial Client Response September 2007
Full Copyright Statement
Copyright (C) The IETF Trust (2007).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Siemborski & Gulbrandsen Standards Track [Page 7]

507
docs/rfc/rfc4978.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/rfc/rfc5032.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/rfc/rfc5051.txt Normal file
View File

@ -0,0 +1,395 @@
Network Working Group M. Crispin
Request for Comments: 5051 University of Washington
Category: Standards Track October 2007
i;unicode-casemap - Simple Unicode Collation Algorithm
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Abstract
This document describes "i;unicode-casemap", a simple case-
insensitive collation for Unicode strings. It provides equality,
substring, and ordering operations.
1. Introduction
The "i;ascii-casemap" collation described in [COMPARATOR] is quite
simple to implement and provides case-independent comparisons for the
26 Latin alphabetics. It is specified as the default and/or baseline
comparator in some application protocols, e.g., [IMAP-SORT].
However, the "i;ascii-casemap" collation does not produce
satisfactory results with non-ASCII characters. It is possible, with
a modest extension, to provide a more sophisticated collation with
greater multilingual applicability than "i;ascii-casemap". This
extension provides case-independent comparisons for a much greater
number of characters. It also collates characters with diacriticals
with the non-diacritical character forms.
This collation, "i;unicode-casemap", is intended to be an alternative
to, and preferred over, "i;ascii-casemap". It does not replace the
"i;basic" collation described in [BASIC].
2. Unicode Casemap Collation Description
The "i;unicode-casemap" collation is a simple collation which is
case-insensitive in its treatment of characters. It provides
equality, substring, and ordering operations. The validity test
operation returns "valid" for any input.
Crispin Standards Track [Page 1]
RFC 5051 i;unicode-casemap October 2007
This collation allows strings in arbitrary (and mixed) character
sets, as long as the character set for each string is identified and
it is possible to convert the string to Unicode. Strings which have
an unidentified character set and/or cannot be converted to Unicode
are not rejected, but are treated as binary.
Each input string is prepared by converting it to a "titlecased
canonicalized UTF-8" string according to the following steps, using
UnicodeData.txt ([UNICODE-DATA]):
(1) A Unicode codepoint is obtained from the input string.
(a) If the input string is in a known charset that can be
converted to Unicode, a sequence in the string's charset
is read and checked for validity according to the rules of
that charset. If the sequence is valid, it is converted
to a Unicode codepoint. Note that for input strings in
UTF-8, the UTF-8 sequence must be valid according to the
rules of [UTF-8]; e.g., overlong UTF-8 sequences are
invalid.
(b) If the input string is in an unknown charset, or an
invalid sequence occurs in step (1)(a), conversion ceases.
No further preparation is performed, and any partial
preparation results are discarded. The original string is
used unchanged with the i;octet comparator.
(2) The following steps, using UnicodeData.txt ([UNICODE-DATA]),
are performed on the resulting codepoint from step (1)(a).
(a) If the codepoint has a titlecase property in
UnicodeData.txt (this is normally the same as the
uppercase property), the codepoint is converted to the
codepoints in the titlecase property.
(b) If the resulting codepoint from (2)(a) has a decomposition
property of any type in UnicodeData.txt, the codepoint is
converted to the codepoints in the decomposition property.
This step is recursively applied to each of the resulting
codepoints until no more decomposition is possible
(effectively Normalization Form KD).
Example: codepoint U+01C4 (LATIN CAPITAL LETTER DZ WITH CARON)
has a titlecase property of U+01C5 (LATIN CAPITAL LETTER D
WITH SMALL LETTER Z WITH CARON). Codepoint U+01C5 has a
decomposition property of U+0044 (LATIN CAPITAL LETTER D)
U+017E (LATIN SMALL LETTER Z WITH CARON). U+017E has a
decomposition property of U+007A (LATIN SMALL LETTER Z) U+030c
Crispin Standards Track [Page 2]
RFC 5051 i;unicode-casemap October 2007
(COMBINING CARON). Neither U+0044, U+007A, nor U+030C have
any decomposition properties. Therefore, U+01C4 is converted
to U+0044 U+007A U+030C by this step.
(3) The resulting codepoint(s) from step (2) is/are appended, in
UTF-8 format, to the "titlecased canonicalized UTF-8" string.
(4) Repeat from step (1) until there is no more data in the input
string.
Following the above preparation process on each string, the equality,
ordering, and substring operations are as for i;octet.
It is permitted to use an alternative implementation of the above
preparation process if it produces the same results. For example, it
may be more convenient for an implementation to convert all input
strings to a sequence of UTF-16 or UTF-32 values prior to performing
any of the step (2) actions. Similarly, if all input strings are (or
are convertible to) Unicode, it may be possible to use UTF-32 as an
alternative to UTF-8 in step (3).
Note: UTF-16 is unsuitable as an alternative to UTF-8 in step (3),
because UTF-16 surrogates will cause i;octet to collate codepoints
U+E0000 through U+FFFF after non-BMP codepoints.
This collation is not locale sensitive. Consequently, care should be
taken when using OS-supplied functions to implement this collation.
Functions such as strcasecmp and toupper are sometimes locale
sensitive and may inconsistently casemap letters.
The i;unicode-casemap collation is well suited to use with many
Internet protocols and computer languages. Use with natural language
is often inappropriate; even though the collation apparently supports
languages such as Swahili and English, in real-world use it tends to
mis-sort a number of types of string:
o people and place names containing scripts that are not collated
according to "alphabetical order".
o words with characters that have diacriticals. However,
i;unicode-casemap generally does a better job than i;ascii-casemap
for most (but not all) languages. For example, German umlaut
letters will sort correctly, but some Scandinavian letters will
not.
o names such as "Lloyd" (which in Welsh sorts after "Lyon", unlike
in English),
o strings containing other non-letter symbols; e.g., euro and pound
sterling symbols, quotation marks other than '"', dashes/hyphens,
etc.
Crispin Standards Track [Page 3]
RFC 5051 i;unicode-casemap October 2007
3. Unicode Casemap Collation Registration
<?xml version='1.0'?>
<!DOCTYPE collation SYSTEM 'collationreg.dtd'>
<collation rfc="5051" scope="global" intendedUse="common">
<identifier>i;unicode-casemap</identifier>
<title>Unicode Casemap</title>
<operations>equality order substring</operations>
<specification>RFC 5051</specification>
<owner>IETF</owner>
<submitter>mrc@cac.washington.edu</submitter>
</collation>
4. Security Considerations
The security considerations for [UTF-8], [STRINGPREP], and [UNICODE-
SECURITY] apply and are normative to this specification.
The results from this comparator will vary depending upon the
implementation for several reasons. Implementations MUST consider
whether these possibilities are a problem for their use case:
1) New characters added in Unicode may have decomposition or
titlecase properties that will not be known to an implementation
based upon an older revision of Unicode. This impacts step (2).
2) Step (2)(b) defines a subset of Normalization Form KD (NFKD) that
does not require normalization of out-of-order diacriticals.
However, an implementation MAY use an NFKD library routine that
does such normalization. This impacts step (2)(b) and possibly
also step (1)(a), and is an issue only with ill-formed UTF-8
input.
3) The set of charsets handled in step (1)(a) is open-ended. UTF-8
(and, by extension, US-ASCII) are the only mandatory-to-implement
charsets. This impacts step (1)(a).
Implementations SHOULD, as far as feasible, support all the
charsets they are likely to encounter in the input data, in order
to avoid poor collation caused by the fall through to the (1)(b)
rule.
4) Other charsets may have revisions which add new characters that
are not known to an implementation based upon an older revision.
This impacts step (1)(a) and possibly also step (1)(b).
Crispin Standards Track [Page 4]
RFC 5051 i;unicode-casemap October 2007
An attacker may create input that is ill-formed or in an unknown
charset, with the intention of impacting the results of this
comparator or exploiting other parts of the system which process this
input in different ways. Note, however, that even well-formed data
in a known charset can impact the result of this comparator in
unexpected ways. For example, an attacker can substitute U+0041
(LATIN CAPITAL LETTER A) with U+0391 (GREEK CAPITAL LETTER ALPHA) or
U+0410 (CYRILLIC CAPITAL LETTER A) in the intention of causing a
non-match of strings which visually appear the same and/or causing
the string to appear elsewhere in a sort.
5. IANA Considerations
The i;unicode-casemap collation defined in section 2 has been added
to the registry of collations defined in [COMPARATOR].
6. Normative References
[COMPARATOR] Newman, C., Duerst, M., and A. Gulbrandsen,
"Internet Application Protocol Collation
Registry", RFC 4790, February 2007.
[STRINGPREP] Hoffman, P. and M. Blanchet, "Preparation of
Internationalized Strings ("stringprep")", RFC
3454, December 2002.
[UTF-8] Yergeau, F., "UTF-8, a transformation format of
ISO 10646", STD 63, RFC 3629, November 2003.
[UNICODE-DATA] <http://www.unicode.org/Public/UNIDATA/
UnicodeData.txt>
Although the UnicodeData.txt file referenced
here is part of the Unicode standard, it is
subject to change as new characters are added
to Unicode and errors are corrected in Unicode
revisions. As a result, it may be less stable
than might otherwise be implied by the
standards status of this specification.
[UNICODE-SECURITY] Davis, M. and M. Suignard, "Unicode Security
Considerations", February 2006,
<http://www.unicode.org/reports/tr36/>.
Crispin Standards Track [Page 5]
RFC 5051 i;unicode-casemap October 2007
7. Informative References
[BASIC] Newman, C., Duerst, M., and A. Gulbrandsen,
"i;basic - the Unicode Collation Algorithm",
Work in Progress, March 2007.
[IMAP-SORT] Crispin, M. and K. Murchison, "Internet Message
Access Protocol - SORT and THREAD Extensions",
Work in Progress, September 2007.
Author's Address
Mark R. Crispin
Networks and Distributed Computing
University of Washington
4545 15th Avenue NE
Seattle, WA 98105-4527
Phone: +1 (206) 543-5762
EMail: MRC@CAC.Washington.EDU
Crispin Standards Track [Page 6]
RFC 5051 i;unicode-casemap October 2007
Full Copyright Statement
Copyright (C) The IETF Trust (2007).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Crispin Standards Track [Page 7]

1795
docs/rfc/rfc5092.txt Normal file
View File

File diff suppressed because it is too large Load Diff

395
docs/rfc/rfc5161.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/rfc/rfc5162.txt Normal file
View File

File diff suppressed because it is too large Load Diff

899
docs/rfc/rfc5234.txt Normal file
View File

@ -0,0 +1,899 @@
Network Working Group D. Crocker, Ed.
Request for Comments: 5234 Brandenburg InternetWorking
STD: 68 P. Overell
Obsoletes: 4234 THUS plc.
Category: Standards Track January 2008
Augmented BNF for Syntax Specifications: ABNF
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Abstract
Internet technical specifications often need to define a formal
syntax. Over the years, a modified version of Backus-Naur Form
(BNF), called Augmented BNF (ABNF), has been popular among many
Internet specifications. The current specification documents ABNF.
It balances compactness and simplicity with reasonable
representational power. The differences between standard BNF and
ABNF involve naming rules, repetition, alternatives, order-
independence, and value ranges. This specification also supplies
additional rule definitions and encoding for a core lexical analyzer
of the type common to several Internet specifications.
Crocker & Overell Standards Track [Page 1]
RFC 5234 ABNF January 2008
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Rule Definition . . . . . . . . . . . . . . . . . . . . . . . 3
2.1. Rule Naming . . . . . . . . . . . . . . . . . . . . . . . 3
2.2. Rule Form . . . . . . . . . . . . . . . . . . . . . . . . 4
2.3. Terminal Values . . . . . . . . . . . . . . . . . . . . . 4
2.4. External Encodings . . . . . . . . . . . . . . . . . . . . 6
3. Operators . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.1. Concatenation: Rule1 Rule2 . . . . . . . . . . . . . . . 6
3.2. Alternatives: Rule1 / Rule2 . . . . . . . . . . . . . . . 7
3.3. Incremental Alternatives: Rule1 =/ Rule2 . . . . . . . . . 7
3.4. Value Range Alternatives: %c##-## . . . . . . . . . . . . 8
3.5. Sequence Group: (Rule1 Rule2) . . . . . . . . . . . . . . 8
3.6. Variable Repetition: *Rule . . . . . . . . . . . . . . . 9
3.7. Specific Repetition: nRule . . . . . . . . . . . . . . . 9
3.8. Optional Sequence: [RULE] . . . . . . . . . . . . . . . . 9
3.9. Comment: ; Comment . . . . . . . . . . . . . . . . . . . 9
3.10. Operator Precedence . . . . . . . . . . . . . . . . . . . 10
4. ABNF Definition of ABNF . . . . . . . . . . . . . . . . . . . 10
5. Security Considerations . . . . . . . . . . . . . . . . . . . 12
6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12
6.1. Normative References . . . . . . . . . . . . . . . . . . . 12
6.2. Informative References . . . . . . . . . . . . . . . . . . 12
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 13
Appendix B. Core ABNF of ABNF . . . . . . . . . . . . . . . . . . 13
B.1. Core Rules . . . . . . . . . . . . . . . . . . . . . . . . 13
B.2. Common Encoding . . . . . . . . . . . . . . . . . . . . . 15
Crocker & Overell Standards Track [Page 2]
RFC 5234 ABNF January 2008
1. Introduction
Internet technical specifications often need to define a formal
syntax and are free to employ whatever notation their authors deem
useful. Over the years, a modified version of Backus-Naur Form
(BNF), called Augmented BNF (ABNF), has been popular among many
Internet specifications. It balances compactness and simplicity with
reasonable representational power. In the early days of the Arpanet,
each specification contained its own definition of ABNF. This
included the email specifications, [RFC733] and then [RFC822], which
came to be the common citations for defining ABNF. The current
document separates those definitions to permit selective reference.
Predictably, it also provides some modifications and enhancements.
The differences between standard BNF and ABNF involve naming rules,
repetition, alternatives, order-independence, and value ranges.
Appendix B supplies rule definitions and encoding for a core lexical
analyzer of the type common to several Internet specifications. It
is provided as a convenience and is otherwise separate from the meta
language defined in the body of this document, and separate from its
formal status.
2. Rule Definition
2.1. Rule Naming
The name of a rule is simply the name itself, that is, a sequence of
characters, beginning with an alphabetic character, and followed by a
combination of alphabetics, digits, and hyphens (dashes).
NOTE:
Rule names are case insensitive.
The names <rulename>, <Rulename>, <RULENAME>, and <rUlENamE> all
refer to the same rule.
Unlike original BNF, angle brackets ("<", ">") are not required.
However, angle brackets may be used around a rule name whenever their
presence facilitates in discerning the use of a rule name. This is
typically restricted to rule name references in free-form prose, or
to distinguish partial rules that combine into a string not separated
by white space, such as shown in the discussion about repetition,
below.
Crocker & Overell Standards Track [Page 3]
RFC 5234 ABNF January 2008
2.2. Rule Form
A rule is defined by the following sequence:
name = elements crlf
where <name> is the name of the rule, <elements> is one or more rule
names or terminal specifications, and <crlf> is the end-of-line
indicator (carriage return followed by line feed). The equal sign
separates the name from the definition of the rule. The elements
form a sequence of one or more rule names and/or value definitions,
combined according to the various operators defined in this document,
such as alternative and repetition.
For visual ease, rule definitions are left aligned. When a rule
requires multiple lines, the continuation lines are indented. The
left alignment and indentation are relative to the first lines of the
ABNF rules and need not match the left margin of the document.
2.3. Terminal Values
Rules resolve into a string of terminal values, sometimes called
characters. In ABNF, a character is merely a non-negative integer.
In certain contexts, a specific mapping (encoding) of values into a
character set (such as ASCII) will be specified.
Terminals are specified by one or more numeric characters, with the
base interpretation of those characters indicated explicitly. The
following bases are currently defined:
b = binary
d = decimal
x = hexadecimal
Hence:
CR = %d13
CR = %x0D
respectively specify the decimal and hexadecimal representation of
[US-ASCII] for carriage return.
Crocker & Overell Standards Track [Page 4]
RFC 5234 ABNF January 2008
A concatenated string of such values is specified compactly, using a
period (".") to indicate a separation of characters within that
value. Hence:
CRLF = %d13.10
ABNF permits the specification of literal text strings directly,
enclosed in quotation marks. Hence:
command = "command string"
Literal text strings are interpreted as a concatenated set of
printable characters.
NOTE:
ABNF strings are case insensitive and the character set for these
strings is US-ASCII.
Hence:
rulename = "abc"
and:
rulename = "aBc"
will match "abc", "Abc", "aBc", "abC", "ABc", "aBC", "AbC", and
"ABC".
To specify a rule that is case sensitive, specify the characters
individually.
For example:
rulename = %d97 %d98 %d99
or
rulename = %d97.98.99
will match only the string that comprises only the lowercase
characters, abc.
Crocker & Overell Standards Track [Page 5]
RFC 5234 ABNF January 2008
2.4. External Encodings
External representations of terminal value characters will vary
according to constraints in the storage or transmission environment.
Hence, the same ABNF-based grammar may have multiple external
encodings, such as one for a 7-bit US-ASCII environment, another for
a binary octet environment, and still a different one when 16-bit
Unicode is used. Encoding details are beyond the scope of ABNF,
although Appendix B provides definitions for a 7-bit US-ASCII
environment as has been common to much of the Internet.
By separating external encoding from the syntax, it is intended that
alternate encoding environments can be used for the same syntax.
3. Operators
3.1. Concatenation: Rule1 Rule2
A rule can define a simple, ordered string of values (i.e., a
concatenation of contiguous characters) by listing a sequence of rule
names. For example:
foo = %x61 ; a
bar = %x62 ; b
mumble = foo bar foo
So that the rule <mumble> matches the lowercase string "aba".
Linear white space: Concatenation is at the core of the ABNF parsing
model. A string of contiguous characters (values) is parsed
according to the rules defined in ABNF. For Internet specifications,
there is some history of permitting linear white space (space and
horizontal tab) to be freely and implicitly interspersed around major
constructs, such as delimiting special characters or atomic strings.
NOTE:
This specification for ABNF does not provide for implicit
specification of linear white space.
Any grammar that wishes to permit linear white space around
delimiters or string segments must specify it explicitly. It is
often useful to provide for such white space in "core" rules that are
then used variously among higher-level rules. The "core" rules might
be formed into a lexical analyzer or simply be part of the main
ruleset.
Crocker & Overell Standards Track [Page 6]
RFC 5234 ABNF January 2008
3.2. Alternatives: Rule1 / Rule2
Elements separated by a forward slash ("/") are alternatives.
Therefore,
foo / bar
will accept <foo> or <bar>.
NOTE:
A quoted string containing alphabetic characters is a special form
for specifying alternative characters and is interpreted as a non-
terminal representing the set of combinatorial strings with the
contained characters, in the specified order but with any mixture
of upper- and lowercase.
3.3. Incremental Alternatives: Rule1 =/ Rule2
It is sometimes convenient to specify a list of alternatives in
fragments. That is, an initial rule may match one or more
alternatives, with later rule definitions adding to the set of
alternatives. This is particularly useful for otherwise independent
specifications that derive from the same parent ruleset, such as
often occurs with parameter lists. ABNF permits this incremental
definition through the construct:
oldrule =/ additional-alternatives
So that the ruleset
ruleset = alt1 / alt2
ruleset =/ alt3
ruleset =/ alt4 / alt5
is the same as specifying
ruleset = alt1 / alt2 / alt3 / alt4 / alt5
Crocker & Overell Standards Track [Page 7]
RFC 5234 ABNF January 2008
3.4. Value Range Alternatives: %c##-##
A range of alternative numeric values can be specified compactly,
using a dash ("-") to indicate the range of alternative values.
Hence:
DIGIT = %x30-39
is equivalent to:
DIGIT = "0" / "1" / "2" / "3" / "4" / "5" / "6" /
"7" / "8" / "9"
Concatenated numeric values and numeric value ranges cannot be
specified in the same string. A numeric value may use the dotted
notation for concatenation or it may use the dash notation to specify
one value range. Hence, to specify one printable character between
end-of-line sequences, the specification could be:
char-line = %x0D.0A %x20-7E %x0D.0A
3.5. Sequence Group: (Rule1 Rule2)
Elements enclosed in parentheses are treated as a single element,
whose contents are strictly ordered. Thus,
elem (foo / bar) blat
matches (elem foo blat) or (elem bar blat), and
elem foo / bar blat
matches (elem foo) or (bar blat).
NOTE:
It is strongly advised that grouping notation be used, rather than
relying on the proper reading of "bare" alternations, when
alternatives consist of multiple rule names or literals.
Hence, it is recommended that the following form be used:
(elem foo) / (bar blat)
It will avoid misinterpretation by casual readers.
Crocker & Overell Standards Track [Page 8]
RFC 5234 ABNF January 2008
The sequence group notation is also used within free text to set off
an element sequence from the prose.
3.6. Variable Repetition: *Rule
The operator "*" preceding an element indicates repetition. The full
form is:
<a>*<b>element
where <a> and <b> are optional decimal values, indicating at least
<a> and at most <b> occurrences of the element.
Default values are 0 and infinity so that *<element> allows any
number, including zero; 1*<element> requires at least one;
3*3<element> allows exactly 3; and 1*2<element> allows one or two.
3.7. Specific Repetition: nRule
A rule of the form:
<n>element
is equivalent to
<n>*<n>element
That is, exactly <n> occurrences of <element>. Thus, 2DIGIT is a
2-digit number, and 3ALPHA is a string of three alphabetic
characters.
3.8. Optional Sequence: [RULE]
Square brackets enclose an optional element sequence:
[foo bar]
is equivalent to
*1(foo bar).
3.9. Comment: ; Comment
A semicolon starts a comment that continues to the end of line. This
is a simple way of including useful notes in parallel with the
specifications.
Crocker & Overell Standards Track [Page 9]
RFC 5234 ABNF January 2008
3.10. Operator Precedence
The various mechanisms described above have the following precedence,
from highest (binding tightest) at the top, to lowest (loosest) at
the bottom:
Rule name, prose-val, Terminal value
Comment
Value range
Repetition
Grouping, Optional
Concatenation
Alternative
Use of the alternative operator, freely mixed with concatenations,
can be confusing.
Again, it is recommended that the grouping operator be used to
make explicit concatenation groups.
4. ABNF Definition of ABNF
NOTES:
1. This syntax requires a formatting of rules that is relatively
strict. Hence, the version of a ruleset included in a
specification might need preprocessing to ensure that it can
be interpreted by an ABNF parser.
2. This syntax uses the rules provided in Appendix B.
rulelist = 1*( rule / (*c-wsp c-nl) )
rule = rulename defined-as elements c-nl
; continues if next line starts
; with white space
rulename = ALPHA *(ALPHA / DIGIT / "-")
Crocker & Overell Standards Track [Page 10]
RFC 5234 ABNF January 2008
defined-as = *c-wsp ("=" / "=/") *c-wsp
; basic rules definition and
; incremental alternatives
elements = alternation *c-wsp
c-wsp = WSP / (c-nl WSP)
c-nl = comment / CRLF
; comment or newline
comment = ";" *(WSP / VCHAR) CRLF
alternation = concatenation
*(*c-wsp "/" *c-wsp concatenation)
concatenation = repetition *(1*c-wsp repetition)
repetition = [repeat] element
repeat = 1*DIGIT / (*DIGIT "*" *DIGIT)
element = rulename / group / option /
char-val / num-val / prose-val
group = "(" *c-wsp alternation *c-wsp ")"
option = "[" *c-wsp alternation *c-wsp "]"
char-val = DQUOTE *(%x20-21 / %x23-7E) DQUOTE
; quoted string of SP and VCHAR
; without DQUOTE
num-val = "%" (bin-val / dec-val / hex-val)
bin-val = "b" 1*BIT
[ 1*("." 1*BIT) / ("-" 1*BIT) ]
; series of concatenated bit values
; or single ONEOF range
dec-val = "d" 1*DIGIT
[ 1*("." 1*DIGIT) / ("-" 1*DIGIT) ]
hex-val = "x" 1*HEXDIG
[ 1*("." 1*HEXDIG) / ("-" 1*HEXDIG) ]
Crocker & Overell Standards Track [Page 11]
RFC 5234 ABNF January 2008
prose-val = "<" *(%x20-3D / %x3F-7E) ">"
; bracketed string of SP and VCHAR
; without angles
; prose description, to be used as
; last resort
5. Security Considerations
Security is truly believed to be irrelevant to this document.
6. References
6.1. Normative References
[US-ASCII] American National Standards Institute, "Coded Character
Set -- 7-bit American Standard Code for Information
Interchange", ANSI X3.4, 1986.
6.2. Informative References
[RFC733] Crocker, D., Vittal, J., Pogran, K., and D. Henderson,
"Standard for the format of ARPA network text messages",
RFC 733, November 1977.
[RFC822] Crocker, D., "Standard for the format of ARPA Internet
text messages", STD 11, RFC 822, August 1982.
Crocker & Overell Standards Track [Page 12]
RFC 5234 ABNF January 2008
Appendix A. Acknowledgements
The syntax for ABNF was originally specified in RFC 733. Ken L.
Harrenstien, of SRI International, was responsible for re-coding the
BNF into an Augmented BNF that makes the representation smaller and
easier to understand.
This recent project began as a simple effort to cull out the portion
of RFC 822 that has been repeatedly cited by non-email specification
writers, namely the description of Augmented BNF. Rather than simply
and blindly converting the existing text into a separate document,
the working group chose to give careful consideration to the
deficiencies, as well as benefits, of the existing specification and
related specifications made available over the last 15 years, and
therefore to pursue enhancement. This turned the project into
something rather more ambitious than was first intended.
Interestingly, the result is not massively different from that
original, although decisions, such as removing the list notation,
came as a surprise.
This "separated" version of the specification was part of the DRUMS
working group, with significant contributions from Jerome Abela,
Harald Alvestrand, Robert Elz, Roger Fajman, Aviva Garrett, Tom
Harsch, Dan Kohn, Bill McQuillan, Keith Moore, Chris Newman, Pete
Resnick, and Henning Schulzrinne.
Julian Reschke warrants a special thanks for converting the Draft
Standard version to XML source form.
Appendix B. Core ABNF of ABNF
This appendix contains some basic rules that are in common use.
Basic rules are in uppercase. Note that these rules are only valid
for ABNF encoded in 7-bit ASCII or in characters sets that are a
superset of 7-bit ASCII.
B.1. Core Rules
Certain basic rules are in uppercase, such as SP, HTAB, CRLF, DIGIT,
ALPHA, etc.
ALPHA = %x41-5A / %x61-7A ; A-Z / a-z
BIT = "0" / "1"
CHAR = %x01-7F
; any 7-bit US-ASCII character,
; excluding NUL
Crocker & Overell Standards Track [Page 13]
RFC 5234 ABNF January 2008
CR = %x0D
; carriage return
CRLF = CR LF
; Internet standard newline
CTL = %x00-1F / %x7F
; controls
DIGIT = %x30-39
; 0-9
DQUOTE = %x22
; " (Double Quote)
HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F"
HTAB = %x09
; horizontal tab
LF = %x0A
; linefeed
LWSP = *(WSP / CRLF WSP)
; Use of this linear-white-space rule
; permits lines containing only white
; space that are no longer legal in
; mail headers and have caused
; interoperability problems in other
; contexts.
; Do not use when defining mail
; headers and use with caution in
; other contexts.
OCTET = %x00-FF
; 8 bits of data
SP = %x20
VCHAR = %x21-7E
; visible (printing) characters
WSP = SP / HTAB
; white space
Crocker & Overell Standards Track [Page 14]
RFC 5234 ABNF January 2008
B.2. Common Encoding
Externally, data are represented as "network virtual ASCII" (namely,
7-bit US-ASCII in an 8-bit field), with the high (8th) bit set to
zero. A string of values is in "network byte order", in which the
higher-valued bytes are represented on the left-hand side and are
sent over the network first.
Authors' Addresses
Dave Crocker (editor)
Brandenburg InternetWorking
675 Spruce Dr.
Sunnyvale, CA 94086
US
Phone: +1.408.246.8253
EMail: dcrocker@bbiw.net
Paul Overell
THUS plc.
1/2 Berkeley Square,
99 Berkeley Street
Glasgow G3 7HR
UK
EMail: paul.overell@thus.net
Crocker & Overell Standards Track [Page 15]
RFC 5234 ABNF January 2008
Full Copyright Statement
Copyright (C) The IETF Trust (2008).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Crocker & Overell Standards Track [Page 16]

76
makefile.nt Normal file
View File

@ -0,0 +1,76 @@
# ========================================================================
# Copyright 1988-2006 University of Washington
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
#
# ========================================================================
# Program: IMAP Toolkit Makefile for Windows 9x and Windows NT
#
# Author: Mark Crispin
# Networks and Distributed Computing
# Computing & Communications
# University of Washington
# Administration Building, AG-44
# Seattle, WA 98195
# Internet: MRC@CAC.Washington.EDU
#
# Date: 7 December 1989
# Last Edited: 30 August 2006
COPY=copy
CD=cd
MAKE=nmake /nologo /f makefile.nt
MKDIR=mkdir
RD=rmdir /s /q
# Make the IMAP Toolkit
build: c-client mtest mailutil imapd ipopd
$(CD) c-client
$(MAKE)
$(CD) ..\mtest
$(MAKE)
$(CD) ..\mailutil
$(MAKE)
$(CD) ..\ipopd
$(MAKE)
$(CD) ..\imapd
$(MAKE)
$(CD) ..
c-client:
$(MKDIR) c-client
$(COPY) src\c-client\*.* c-client
$(COPY) src\charset\*.* c-client
$(COPY) src\osdep\nt\*.* c-client
mtest:
$(MKDIR) mtest
$(COPY) src\mtest\*.* mtest
mailutil:
$(MKDIR) mailutil
$(COPY) src\mailutil\*.* mailutil
ipopd:
$(MKDIR) ipopd
$(COPY) src\ipopd\*.* ipopd
imapd:
$(MKDIR) imapd
$(COPY) src\imapd\*.* imapd
clean:
$(RD) c-client mtest mailutil ipopd imapd
# A monument to a hack of long ago and far away...
love:
@echo 'not war?'

76
makefile.ntk Normal file
View File

@ -0,0 +1,76 @@
# ========================================================================
# Copyright 1988-2006 University of Washington
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
#
# ========================================================================
# Program: IMAP Toolkit Makefile for Windows 9x and Windows NT + Kerberos
#
# Author: Mark Crispin
# Networks and Distributed Computing
# Computing & Communications
# University of Washington
# Administration Building, AG-44
# Seattle, WA 98195
# Internet: MRC@CAC.Washington.EDU
#
# Date: 7 December 1989
# Last Edited: 30 August 2006
COPY=copy
CD=cd
MAKE=nmake /nologo /f makefile.ntk
MKDIR=mkdir
RD=rmdir /s /q
# Make the IMAP Toolkit
build: c-client mtest mailutil imapd ipopd
$(CD) c-client
$(MAKE)
$(CD) ..\mtest
$(MAKE)
$(CD) ..\mailutil
$(MAKE)
$(CD) ..\ipopd
$(MAKE)
$(CD) ..\imapd
$(MAKE)
$(CD) ..
c-client:
$(MKDIR) c-client
$(COPY) src\c-client\*.* c-client
$(COPY) src\charset\*.* c-client
$(COPY) src\osdep\nt\*.* c-client
mtest:
$(MKDIR) mtest
$(COPY) src\mtest\*.* mtest
mailutil:
$(MKDIR) mailutil
$(COPY) src\mailutil\*.* mailutil
ipopd:
$(MKDIR) ipopd
$(COPY) src\ipopd\*.* ipopd
imapd:
$(MKDIR) imapd
$(COPY) src\imapd\*.* imapd
clean:
$(RD) c-client mtest mailutil ipopd imapd
# A monument to a hack of long ago and far away...
love:
@echo 'not war?'

59
makefile.os2 Normal file
View File

@ -0,0 +1,59 @@
# ========================================================================
# Copyright 1988-2006 University of Washington
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
#
# ========================================================================
# Program: IMAP Toolkit Makefile
#
# Author: Mark Crispin
# Networks and Distributed Computing
# Computing & Communications
# University of Washington
# Administration Building, AG-44
# Seattle, WA 98195
# Internet: MRC@CAC.Washington.EDU
#
# Date: 7 December 1989
# Last Edited: 30 August 2006
COPY=copy
MAKE=make -f makefile.os2
MKDIR=md
RD=rm -rf
# Make the IMAP Toolkit
build: c-client mtest mailutil
(cd c-client & $(MAKE))
(cd mtest & $(MAKE))
(cd mailutil & $(MAKE))
c-client:
$(MKDIR) c-client
$(COPY) src\c-client\\* c-client
$(COPY) src\charset\\* c-client
$(COPY) src\osdep\os2\\* c-client
mtest:
$(MKDIR) mtest
$(COPY) src\mtest\\* mtest
mailutil:
$(MKDIR) mailutil
$(COPY) src\mailutil\\* mailutil
clean:
$(RD) c-client mtest mailutil
# A monument to a hack of long ago and far away...
love:
@echo 'not war?'

77
makefile.w2k Normal file
View File

@ -0,0 +1,77 @@
# ========================================================================
# Copyright 1988-2006 University of Washington
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
#
# ========================================================================
# Program: IMAP Toolkit Makefile for Windows 2000/XP
#
# Author: Mark Crispin
# Networks and Distributed Computing
# Computing & Communications
# University of Washington
# Administration Building, AG-44
# Seattle, WA 98195
# Internet: MRC@CAC.Washington.EDU
#
# Date: 7 December 1989
# Last Edited: 20 August 2006
IP=6
COPY=copy
CD=cd
MAKE=nmake /nologo /f makefile.w2k IP=$(IP)
MKDIR=mkdir
RD=rmdir /s /q
# Make the IMAP Toolkit
build: c-client mtest mailutil imapd ipopd
$(CD) c-client
$(MAKE)
$(CD) ..\mtest
$(MAKE)
$(CD) ..\mailutil
$(MAKE)
$(CD) ..\ipopd
$(MAKE)
$(CD) ..\imapd
$(MAKE)
$(CD) ..
c-client:
$(MKDIR) c-client
$(COPY) src\c-client\*.* c-client
$(COPY) src\charset\*.* c-client
$(COPY) src\osdep\nt\*.* c-client
mtest:
$(MKDIR) mtest
$(COPY) src\mtest\*.* mtest
mailutil:
$(MKDIR) mailutil
$(COPY) src\mailutil\*.* mailutil
ipopd:
$(MKDIR) ipopd
$(COPY) src\ipopd\*.* ipopd
imapd:
$(MKDIR) imapd
$(COPY) src\imapd\*.* imapd
clean:
$(RD) c-client mtest mailutil ipopd imapd
# A monument to a hack of long ago and far away...
love:
@echo 'not war?'

64
makefile.wce Normal file
View File

@ -0,0 +1,64 @@
# ========================================================================
# Copyright 1988-2006 University of Washington
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
#
# ========================================================================
# Program: IMAP Toolkit Makefile
#
# Author: Mark Crispin
# Networks and Distributed Computing
# Computing & Communications
# University of Washington
# Administration Building, AG-44
# Seattle, WA 98195
# Internet: MRC@CAC.Washington.EDU
#
# Date: 7 December 1989
# Last Edited: 30 August 2006
COPY=copy
CD=cd
MAKE=nmake /nologo /f makefile.wce
MKDIR=mkdir
RD=rmdir /s /q
# Make the IMAP Toolkit
build: c-client mtest mailutil
$(CD) c-client
$(MAKE)
# $(CD) ..\mtest
# $(MAKE)
# $(CD) ..\mailutil
# $(MAKE)
$(CD) ..
c-client:
$(MKDIR) c-client
$(COPY) src\c-client\*.* c-client
$(COPY) src\charset\*.* c-client
$(COPY) src\osdep\wce\*.* c-client
mtest:
$(MKDIR) mtest
$(COPY) src\mtest\*.* mtest
mailutil:
$(MKDIR) mailutil
$(COPY) src\mailutil\*.* mailutil
clean:
$(RD) c-client mtest
# A monument to a hack of long ago and far away...
love:
@echo 'not war?'

40
src/ansilib/memmove.c Normal file
View File

@ -0,0 +1,40 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
/*
* Program: Memory move
*
* Author: Mark Crispin
* Networks and Distributed Computing
* Computing & Communications
* University of Washington
* Administration Building, AG-44
* Seattle, WA 98195
* Internet: MRC@CAC.Washington.EDU
*
* Date: 1 August 1988
* Last Edited: 30 August 2006
*/
/* Copy memory block
* Accepts: destination pointer
* source pointer
* length
* Returns: destination pointer
*/
void *memmove (void *s,void *ct,size_t n)
{
bcopy (ct,s,n); /* they should have this one */
return s;
}

49
src/ansilib/memmove2.c Normal file
View File

@ -0,0 +1,49 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
/*
* Program: Memory move when no bcopy()
*
* Author: Mark Crispin
* Networks and Distributed Computing
* Computing & Communications
* University of Washington
* Administration Building, AG-44
* Seattle, WA 98195
* Internet: MRC@CAC.Washington.EDU
*
* Date: 11 May 1989
* Last Edited: 30 August 2006
*/
/* Copy memory block
* Accepts: destination pointer
* source pointer
* length
* Returns: destination pointer
*/
void *memmove (void *s,void *ct,size_t n)
{
char *dp,*sp;
int i;
unsigned long dest = (unsigned long) s;
unsigned long src = (unsigned long) ct;
if (((dest < src) && ((dest + n) < src)) ||
((dest > src) && ((src + n) < dest))) return (void *) memcpy (s,ct,n);
dp = (char *) s;
sp = (char *) ct;
if (dest < src) for (i = 0; i < n; ++i) dp[i] = sp[i];
else if (dest > src) for (i = n - 1; i >= 0; --i) dp[i] = sp[i];
return s;
}

40
src/ansilib/memset.c Normal file
View File

@ -0,0 +1,40 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
/*
* Program: Set memory
*
* Author: Mark Crispin
* Networks and Distributed Computing
* Computing & Communications
* University of Washington
* Administration Building, AG-44
* Seattle, WA 98195
*
* Date: 11 May 1989
* Last Edited: 30 August 2006
*/
/* Set a block of memory
* Accepts: destination pointer
* value to set
* length
* Returns: destination pointer
*/
void *memset (void *s,int c,size_t n)
{
if (c) while (n) s[--n] = c; /* this way if non-zero */
else bzero (s,n); /* they should have this one */
return s;
}

40
src/ansilib/strpbrk.c Normal file
View File

@ -0,0 +1,40 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
/*
* Program: String search for break character
*
* Author: Mark Crispin
* Networks and Distributed Computing
* Computing & Communications
* University of Washington
* Administration Building, AG-44
* Seattle, WA 98195
*
* Date: 11 May 1989
* Last Edited: 30 August 2006
*/
/* Return pointer to first occurance in string of any delimiter
* Accepts: source pointer
* vector of delimiters pointer
* Returns: pointer to delimiter or NIL if not found
*/
char *strpbrk (char *cs,char *ct)
{
char *s;
/* search for delimiter until end of string */
for (; *cs; cs++) for (s = ct; *s; s++) if (*s == *cs) return cs;
return NIL; /* not found */
}

45
src/ansilib/strstr.c Normal file
View File

@ -0,0 +1,45 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
/*
* Program: Substring search
*
* Author: Mark Crispin
* Networks and Distributed Computing
* Computing & Communications
* University of Washington
* Administration Building, AG-44
* Seattle, WA 98195
*
* Date: 11 May 1989
* Last Edited: 30 August 2006
*/
/* Return pointer to first occurance in string of a substring
* Accepts: source pointer
* substring pointer
* Returns: pointer to substring in source or NIL if not found
*/
char *strstr (char *cs,char *ct)
{
char *s;
char *t;
while (cs = strchr (cs,*ct)) {/* for each occurance of the first character */
/* see if remainder of string matches */
for (s = cs + 1, t = ct + 1; *t && *s == *t; s++, t++);
if (!*t) return cs; /* if ran out of substring then have match */
cs++; /* try from next character */
}
return NIL; /* not found */
}

67
src/ansilib/strtok.c Normal file
View File

@ -0,0 +1,67 @@
/* ========================================================================
* Copyright 1988-2007 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
/*
* Program: String return successive tokens
*
* Author: Mark Crispin
* Networks and Distributed Computing
* Computing & Communications
* University of Washington
* Administration Building, AG-44
* Seattle, WA 98195
*
* Date: 11 May 1989
* Last Edited: 30 January 2007
*/
/* Find token in string
* Accepts: source pointer or NIL to use previous source
* vector of token delimiters pointer
* Returns: pointer to next token
*/
static char *state = NIL; /* string to locate tokens */
char *strtok (char *s,char *ct)
{
return strtok_r (s,ct,&state);/* jacket into reentrant routine */
}
/* Find token in string (reentrant)
* Accepts: source pointer or NIL to use previous source
* vector of token delimiters pointer
* returned state pointer
* Returns: pointer to next token
*/
char *strtok_r (char *s,char *ct,char **r)
{
char *t,*ts;
if (!s) s = *r; /* use previous token if none specified */
*r = NIL; /* default to no returned state */
if (!(s && *s)) return NIL; /* no tokens left */
/* find any leading delimiters */
do for (t = ct, ts = NIL; *t; t++) if (*t == *s) {
if (*(ts = ++s)) break; /* yes, restart search if more in string */
return NIL; /* else no more tokens */
} while (ts); /* continue until no more leading delimiters */
/* can we find a new delimiter? */
for (ts = s; *ts; ts++) for (t = ct; *t; t++) if (*t == *ts) {
*ts++ = '\0'; /* yes, tie off token at that point */
*r = ts; /* save subsequent tokens for future call */
return s; /* return our token */
}
return s; /* return final token */
}

73
src/ansilib/strtoul.c Normal file
View File

@ -0,0 +1,73 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
/*
* Program: String to unsigned long
*
* Author: Mark Crispin
* Networks and Distributed Computing
* Computing & Communications
* University of Washington
* Administration Building, AG-44
* Seattle, WA 98195
*
* Date: 14 February 1995
* Last Edited: 30 August 2006
*/
/*
* Turn a string unsigned long into the real thing
* Accepts: source string
* pointer to place to return end pointer
* base
* Returns: parsed unsigned long integer, end pointer is updated
*/
unsigned long strtoul (char *t,char **endp,int base)
{
unsigned long value = 0; /* the accumulated value */
int negative = 0; /* this a negative number? */
unsigned char c,*s = t;
if (base && (base < 2 || base > 36)) {
errno = EINVAL; /* insist upon valid base */
return value;
}
while (isspace (*s)) s++; /* skip leading whitespace */
switch (*s) { /* check for leading sign char */
case '-':
negative = 1; /* yes, negative #. fall into '+' */
case '+':
s++; /* skip the sign character */
}
if (!base) { /* base not specified? */
if (*s != '0') base = 10; /* must be decimal if doesn't start with 0 */
/* starts with 0x? */
else if (tolower (*++s) == 'x') {
base = 16; /* yes, is hex */
s++; /* skip the x */
}
else base = 8; /* ...or octal */
}
do { /* convert to numeric form if digit */
if (isdigit (*s)) c = *s - '0';
/* alphabetic conversion */
else if (isalpha (*s)) c = *s - (isupper (*s) ? 'A' : 'a') + 10;
else break; /* else no way it's valid */
if (c >= base) break; /* digit out of range for base? */
value = value * base + c; /* accumulate the digit */
} while (*++s); /* loop until non-numeric character */
if (tolower (*s) == 'l') s++; /* ignore 'l' or 'L' marker */
if (endp) *endp = s; /* save users endp to after number */
/* negate number if needed */
return negative ? -value : value;
}

96
src/c-client/auth_ext.c Normal file
View File

@ -0,0 +1,96 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
/*
* Program: EXTERNAL authenticator
*
* Author: Mark Crispin
* Networks and Distributed Computing
* Computing & Communications
* University of Washington
* Administration Building, AG-44
* Seattle, WA 98195
* Internet: MRC@CAC.Washington.EDU
*
* Date: 6 April 2005
* Last Edited: 30 August 2006
*/
long auth_external_client (authchallenge_t challenger,authrespond_t responder,
char *service,NETMBX *mb,void *stream,
unsigned long *trial,char *user);
char *auth_external_server (authresponse_t responder,int argc,char *argv[]);
AUTHENTICATOR auth_ext = { /* secure, has full auth, hidden */
AU_SECURE | AU_AUTHUSER | AU_HIDE,
"EXTERNAL", /* authenticator name */
NIL, /* always valid */
auth_external_client, /* client method */
auth_external_server, /* server method */
NIL /* next authenticator */
};
/* Client authenticator
* Accepts: challenger function
* responder function
* SASL service name
* parsed network mailbox structure
* stream argument for functions
* pointer to current trial count
* returned user name
* Returns: T if success, NIL otherwise, number of trials incremented if retry
*/
long auth_external_client (authchallenge_t challenger,authrespond_t responder,
char *service,NETMBX *mb,void *stream,
unsigned long *trial,char *user)
{
void *challenge;
unsigned long clen;
long ret = NIL;
*trial = 65535; /* never retry */
if (challenge = (*challenger) (stream,&clen)) {
fs_give ((void **) &challenge);
/* send authorization id (empty string OK) */
if ((*responder) (stream,strcpy (user,mb->user),strlen (mb->user))) {
if (challenge = (*challenger) (stream,&clen))
fs_give ((void **) &challenge);
else ret = LONGT; /* check the authentication */
}
}
return ret;
}
/* Server authenticator
* Accepts: responder function
* argument count
* argument vector
* Returns: authenticated user name or NIL
*/
char *auth_external_server (authresponse_t responder,int argc,char *argv[])
{
unsigned long len;
char *authid;
char *authenid = (char *) mail_parameters (NIL,GET_EXTERNALAUTHID,NIL);
char *ret = NIL;
/* get authorization identity */
if (authenid && (authid = (*responder) ("",0,&len))) {
/* note: responders null-terminate */
if (*authid ? authserver_login (authid,authenid,argc,argv) :
authserver_login (authenid,NIL,argc,argv)) ret = myusername ();
fs_give ((void **) &authid);
}
return ret;
}

423
src/c-client/auth_gss.c Normal file
View File

@ -0,0 +1,423 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
/*
* Program: GSSAPI authenticator
*
* Author: Mark Crispin
* Networks and Distributed Computing
* Computing & Communications
* University of Washington
* Administration Building, AG-44
* Seattle, WA 98195
* Internet: MRC@CAC.Washington.EDU
*
* Date: 12 January 1998
* Last Edited: 30 August 2006
*/
long auth_gssapi_valid (void);
long auth_gssapi_client (authchallenge_t challenger,authrespond_t responder,
char *service,NETMBX *mb,void *stream,
unsigned long *trial,char *user);
long auth_gssapi_client_work (authchallenge_t challenger,gss_buffer_desc chal,
authrespond_t responder,char *service,NETMBX *mb,
void *stream,char *user,kinit_t ki);
char *auth_gssapi_server (authresponse_t responder,int argc,char *argv[]);
AUTHENTICATOR auth_gss = {
AU_SECURE | AU_AUTHUSER, /* secure authenticator */
"GSSAPI", /* authenticator name */
auth_gssapi_valid, /* check if valid */
auth_gssapi_client, /* client method */
auth_gssapi_server, /* server method */
NIL /* next authenticator */
};
#define AUTH_GSSAPI_P_NONE 1
#define AUTH_GSSAPI_P_INTEGRITY 2
#define AUTH_GSSAPI_P_PRIVACY 4
#define AUTH_GSSAPI_C_MAXSIZE 8192
#define SERVER_LOG(x,y) syslog (LOG_ALERT,x,y)
/* Check if GSSAPI valid on this system
* Returns: T if valid, NIL otherwise
*/
long auth_gssapi_valid (void)
{
char tmp[MAILTMPLEN];
OM_uint32 smn;
gss_buffer_desc buf;
gss_name_t name;
/* make service name */
sprintf (tmp,"%s@%s",(char *) mail_parameters (NIL,GET_SERVICENAME,NIL),
mylocalhost ());
buf.length = strlen (buf.value = tmp);
/* see if can build a name */
if (gss_import_name (&smn,&buf,GSS_C_NT_HOSTBASED_SERVICE,&name) !=
GSS_S_COMPLETE) return NIL;
/* remove server method if no keytab */
if (!kerberos_server_valid ()) auth_gss.server = NIL;
gss_release_name (&smn,&name);/* finished with name */
return LONGT;
}
/* Client authenticator
* Accepts: challenger function
* responder function
* SASL service name
* parsed network mailbox structure
* stream argument for functions
* pointer to current trial count
* returned user name
* Returns: T if success, NIL otherwise, number of trials incremented if retry
*/
long auth_gssapi_client (authchallenge_t challenger,authrespond_t responder,
char *service,NETMBX *mb,void *stream,
unsigned long *trial,char *user)
{
gss_buffer_desc chal;
kinit_t ki = (kinit_t) mail_parameters (NIL,GET_KINIT,NIL);
long ret = NIL;
*trial = 65535; /* never retry */
/* get initial (empty) challenge */
if (chal.value = (*challenger) (stream,(unsigned long *) &chal.length)) {
if (chal.length) { /* abort if challenge non-empty */
mm_log ("Server bug: non-empty initial GSSAPI challenge",WARN);
(*responder) (stream,NIL,0);
ret = LONGT; /* will get a BAD response back */
}
else if (mb->authuser[0] && strcmp (mb->authuser,myusername ())) {
mm_log ("Can't use Kerberos: invalid /authuser",WARN);
(*responder) (stream,NIL,0);
ret = LONGT; /* will get a BAD response back */
}
else ret = auth_gssapi_client_work (challenger,chal,responder,service,mb,
stream,user,ki);
}
return ret;
}
/* Client authenticator worker function
* Accepts: challenger function
* responder function
* SASL service name
* parsed network mailbox structure
* stream argument for functions
* returned user name
* kinit function pointer if should retry with kinit
* Returns: T if success, NIL otherwise
*/
long auth_gssapi_client_work (authchallenge_t challenger,gss_buffer_desc chal,
authrespond_t responder,char *service,NETMBX *mb,
void *stream,char *user,kinit_t ki)
{
char tmp[MAILTMPLEN];
OM_uint32 smj,smn,dsmj,dsmn;
OM_uint32 mctx = 0;
gss_ctx_id_t ctx = GSS_C_NO_CONTEXT;
gss_buffer_desc resp,buf;
long i;
int conf;
gss_qop_t qop;
gss_name_t crname = NIL;
blocknotify_t bn = (blocknotify_t) mail_parameters (NIL,GET_BLOCKNOTIFY,NIL);
void *data;
long ret = NIL;
sprintf (tmp,"%s@%s",service,mb->host);
buf.length = strlen (buf.value = tmp);
/* get service name */
if (gss_import_name (&smn,&buf,GSS_C_NT_HOSTBASED_SERVICE,&crname) !=
GSS_S_COMPLETE) {
mm_log ("Can't import Kerberos service name",WARN);
(*responder) (stream,NIL,0);
}
else {
data = (*bn) (BLOCK_SENSITIVE,NIL);
/* negotiate with KDC */
smj = gss_init_sec_context (&smn,GSS_C_NO_CREDENTIAL,&ctx,crname,NIL,
GSS_C_INTEG_FLAG | GSS_C_MUTUAL_FLAG |
GSS_C_REPLAY_FLAG,0,GSS_C_NO_CHANNEL_BINDINGS,
GSS_C_NO_BUFFER,NIL,&resp,NIL,NIL);
(*bn) (BLOCK_NONSENSITIVE,data);
/* while continuation needed */
while (smj == GSS_S_CONTINUE_NEEDED) {
if (chal.value) fs_give ((void **) &chal.value);
/* send response, get next challenge */
i = (*responder) (stream,resp.value,resp.length) &&
(chal.value = (*challenger) (stream,(unsigned long *) &chal.length));
gss_release_buffer (&smn,&resp);
if (i) { /* negotiate continuation with KDC */
data = (*bn) (BLOCK_SENSITIVE,NIL);
switch (smj = /* make sure continuation going OK */
gss_init_sec_context (&smn,GSS_C_NO_CREDENTIAL,&ctx,
crname,GSS_C_NO_OID,GSS_C_INTEG_FLAG |
GSS_C_MUTUAL_FLAG | GSS_C_REPLAY_FLAG,0,
GSS_C_NO_CHANNEL_BINDINGS,&chal,NIL,
&resp,NIL,NIL)) {
case GSS_S_CONTINUE_NEEDED:
case GSS_S_COMPLETE:
break;
default: /* error, don't need context any more */
gss_delete_sec_context (&smn,&ctx,NIL);
}
(*bn) (BLOCK_NONSENSITIVE,data);
}
else { /* error in continuation */
mm_log ("Error in negotiating Kerberos continuation",WARN);
(*responder) (stream,NIL,0);
/* don't need context any more */
gss_delete_sec_context (&smn,&ctx,NIL);
break;
}
}
switch (smj) { /* done - deal with final condition */
case GSS_S_COMPLETE:
if (chal.value) fs_give ((void **) &chal.value);
/* get prot mechanisms and max size */
if ((*responder) (stream,resp.value ? resp.value : "",resp.length) &&
(chal.value = (*challenger) (stream,(unsigned long *)&chal.length))&&
(gss_unwrap (&smn,ctx,&chal,&resp,&conf,&qop) == GSS_S_COMPLETE) &&
(resp.length >= 4) && (*((char *) resp.value) & AUTH_GSSAPI_P_NONE)){
/* make copy of flags and length */
memcpy (tmp,resp.value,4);
gss_release_buffer (&smn,&resp);
/* no session protection */
tmp[0] = AUTH_GSSAPI_P_NONE;
/* install user name */
strcpy (tmp+4,strcpy (user,mb->user[0] ? mb->user : myusername ()));
buf.value = tmp; buf.length = strlen (user) + 4;
/* successful negotiation */
switch (smj = gss_wrap (&smn,ctx,NIL,qop,&buf,&conf,&resp)) {
case GSS_S_COMPLETE:
if ((*responder) (stream,resp.value,resp.length)) ret = T;
gss_release_buffer (&smn,&resp);
break;
default:
do switch (dsmj = gss_display_status (&dsmn,smj,GSS_C_GSS_CODE,
GSS_C_NO_OID,&mctx,&resp)) {
case GSS_S_COMPLETE:
mctx = 0;
case GSS_S_CONTINUE_NEEDED:
sprintf (tmp,"Unknown gss_wrap failure: %s",(char *) resp.value);
mm_log (tmp,WARN);
gss_release_buffer (&dsmn,&resp);
}
while (dsmj == GSS_S_CONTINUE_NEEDED);
do switch (dsmj = gss_display_status (&dsmn,smn,GSS_C_MECH_CODE,
GSS_C_NO_OID,&mctx,&resp)) {
case GSS_S_COMPLETE:
case GSS_S_CONTINUE_NEEDED:
sprintf (tmp,"GSSAPI mechanism status: %s",(char *) resp.value);
mm_log (tmp,WARN);
gss_release_buffer (&dsmn,&resp);
}
while (dsmj == GSS_S_CONTINUE_NEEDED);
(*responder) (stream,NIL,0);
}
}
/* flush final challenge */
if (chal.value) fs_give ((void **) &chal.value);
/* don't need context any more */
gss_delete_sec_context (&smn,&ctx,NIL);
break;
case GSS_S_CREDENTIALS_EXPIRED:
if (chal.value) fs_give ((void **) &chal.value);
/* retry if application kinits */
if (ki && (*ki) (mb->host,"Kerberos credentials expired"))
ret = auth_gssapi_client_work (challenger,chal,responder,service,mb,
stream,user,NIL);
else { /* application can't kinit */
sprintf (tmp,"Kerberos credentials expired (try running kinit) for %s",
mb->host);
mm_log (tmp,WARN);
(*responder) (stream,NIL,0);
}
break;
case GSS_S_FAILURE:
if (chal.value) fs_give ((void **) &chal.value);
do switch (dsmj = gss_display_status (&dsmn,smn,GSS_C_MECH_CODE,
GSS_C_NO_OID,&mctx,&resp)) {
case GSS_S_COMPLETE: /* end of message, can kinit? */
if (ki && kerberos_try_kinit (smn) &&
(*ki) (mb->host,(char *) resp.value)) {
gss_release_buffer (&dsmn,&resp);
ret = auth_gssapi_client_work (challenger,chal,responder,service,mb,
stream,user,NIL);
break; /* done */
}
else (*responder) (stream,NIL,0);
case GSS_S_CONTINUE_NEEDED:
sprintf (tmp,kerberos_try_kinit (smn) ?
"Kerberos error: %.80s (try running kinit) for %.80s" :
"GSSAPI failure: %s for %.80s",(char *) resp.value,mb->host);
mm_log (tmp,WARN);
gss_release_buffer (&dsmn,&resp);
} while (dsmj == GSS_S_CONTINUE_NEEDED);
break;
default: /* miscellaneous errors */
if (chal.value) fs_give ((void **) &chal.value);
do switch (dsmj = gss_display_status (&dsmn,smj,GSS_C_GSS_CODE,
GSS_C_NO_OID,&mctx,&resp)) {
case GSS_S_COMPLETE:
mctx = 0;
case GSS_S_CONTINUE_NEEDED:
sprintf (tmp,"Unknown GSSAPI failure: %s",(char *) resp.value);
mm_log (tmp,WARN);
gss_release_buffer (&dsmn,&resp);
}
while (dsmj == GSS_S_CONTINUE_NEEDED);
do switch (dsmj = gss_display_status (&dsmn,smn,GSS_C_MECH_CODE,
GSS_C_NO_OID,&mctx,&resp)) {
case GSS_S_COMPLETE:
case GSS_S_CONTINUE_NEEDED:
sprintf (tmp,"GSSAPI mechanism status: %s",(char *) resp.value);
mm_log (tmp,WARN);
gss_release_buffer (&dsmn,&resp);
}
while (dsmj == GSS_S_CONTINUE_NEEDED);
(*responder) (stream,NIL,0);
break;
}
/* finished with credentials name */
if (crname) gss_release_name (&smn,&crname);
}
return ret; /* return status */
}
/* Server authenticator
* Accepts: responder function
* argument count
* argument vector
* Returns: authenticated user name or NIL
*/
char *auth_gssapi_server (authresponse_t responder,int argc,char *argv[])
{
char *ret = NIL;
char tmp[MAILTMPLEN];
unsigned long maxsize = htonl (AUTH_GSSAPI_C_MAXSIZE);
int conf;
OM_uint32 smj,smn,dsmj,dsmn,flags;
OM_uint32 mctx = 0;
gss_name_t crname,name;
gss_OID mech;
gss_buffer_desc chal,resp,buf;
gss_cred_id_t crd;
gss_ctx_id_t ctx = GSS_C_NO_CONTEXT;
gss_qop_t qop = GSS_C_QOP_DEFAULT;
/* make service name */
sprintf (tmp,"%s@%s",(char *) mail_parameters (NIL,GET_SERVICENAME,NIL),
tcp_serverhost ());
buf.length = strlen (buf.value = tmp);
/* acquire credentials */
if ((gss_import_name (&smn,&buf,GSS_C_NT_HOSTBASED_SERVICE,&crname)) ==
GSS_S_COMPLETE) {
if ((smj = gss_acquire_cred (&smn,crname,0,NIL,GSS_C_ACCEPT,&crd,NIL,NIL))
== GSS_S_COMPLETE) {
if (resp.value = (*responder) ("",0,(unsigned long *) &resp.length)) {
do { /* negotiate authentication */
smj = gss_accept_sec_context (&smn,&ctx,crd,&resp,
GSS_C_NO_CHANNEL_BINDINGS,&name,&mech,
&chal,&flags,NIL,NIL);
/* don't need response any more */
fs_give ((void **) &resp.value);
switch (smj) { /* how did it go? */
case GSS_S_COMPLETE: /* successful */
case GSS_S_CONTINUE_NEEDED:
if (chal.value) { /* send challenge, get next response */
resp.value = (*responder) (chal.value,chal.length,
(unsigned long *) &resp.length);
gss_release_buffer (&smn,&chal);
}
break;
}
}
while (resp.value && resp.length && (smj == GSS_S_CONTINUE_NEEDED));
/* successful exchange? */
if ((smj == GSS_S_COMPLETE) &&
(gss_display_name (&smn,name,&buf,&mech) == GSS_S_COMPLETE)) {
/* send security and size */
memcpy (resp.value = tmp,(void *) &maxsize,resp.length = 4);
tmp[0] = AUTH_GSSAPI_P_NONE;
if (gss_wrap (&smn,ctx,NIL,qop,&resp,&conf,&chal) == GSS_S_COMPLETE){
resp.value = (*responder) (chal.value,chal.length,
(unsigned long *) &resp.length);
gss_release_buffer (&smn,&chal);
if (gss_unwrap (&smn,ctx,&resp,&chal,&conf,&qop)==GSS_S_COMPLETE) {
/* client request valid */
if (chal.value && (chal.length > 4) &&
(chal.length < (MAILTMPLEN - 1)) &&
memcpy (tmp,chal.value,chal.length) &&
(tmp[0] & AUTH_GSSAPI_P_NONE)) {
/* tie off authorization ID */
tmp[chal.length] = '\0';
ret = kerberos_login (tmp+4,buf.value,argc,argv);
}
/* done with user name */
gss_release_buffer (&smn,&chal);
}
/* finished with response */
fs_give ((void **) &resp.value);
}
/* don't need name buffer any more */
gss_release_buffer (&smn,&buf);
}
/* don't need client name any more */
gss_release_name (&smn,&name);
/* don't need context any more */
if (ctx != GSS_C_NO_CONTEXT) gss_delete_sec_context (&smn,&ctx,NIL);
}
/* finished with credentials */
gss_release_cred (&smn,&crd);
}
else { /* can't acquire credentials! */
if (gss_display_name (&dsmn,crname,&buf,&mech) == GSS_S_COMPLETE)
SERVER_LOG ("Failed to acquire credentials for %s",buf.value);
if (smj != GSS_S_FAILURE) do
switch (dsmj = gss_display_status (&dsmn,smj,GSS_C_GSS_CODE,
GSS_C_NO_OID,&mctx,&resp)) {
case GSS_S_COMPLETE:
mctx = 0;
case GSS_S_CONTINUE_NEEDED:
SERVER_LOG ("Unknown GSSAPI failure: %s",resp.value);
gss_release_buffer (&dsmn,&resp);
}
while (dsmj == GSS_S_CONTINUE_NEEDED);
do switch (dsmj = gss_display_status (&dsmn,smn,GSS_C_MECH_CODE,
GSS_C_NO_OID,&mctx,&resp)) {
case GSS_S_COMPLETE:
case GSS_S_CONTINUE_NEEDED:
SERVER_LOG ("GSSAPI mechanism status: %s",resp.value);
gss_release_buffer (&dsmn,&resp);
}
while (dsmj == GSS_S_CONTINUE_NEEDED);
}
/* finished with credentials name */
gss_release_name (&smn,&crname);
}
return ret; /* return status */
}

117
src/c-client/auth_log.c Normal file
View File

@ -0,0 +1,117 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
/*
* Program: Login authenticator
*
* Author: Mark Crispin
* Networks and Distributed Computing
* Computing & Communications
* University of Washington
* Administration Building, AG-44
* Seattle, WA 98195
* Internet: MRC@CAC.Washington.EDU
*
* Date: 5 December 1995
* Last Edited: 30 August 2006
*/
long auth_login_client (authchallenge_t challenger,authrespond_t responder,
char *service,NETMBX *mb,void *stream,
unsigned long *trial,char *user);
char *auth_login_server (authresponse_t responder,int argc,char *argv[]);
AUTHENTICATOR auth_log = {
AU_HIDE, /* hidden */
"LOGIN", /* authenticator name */
NIL, /* always valid */
auth_login_client, /* client method */
auth_login_server, /* server method */
NIL /* next authenticator */
};
#define PWD_USER "User Name"
#define PWD_PWD "Password"
/* Client authenticator
* Accepts: challenger function
* responder function
* SASL service name
* parsed network mailbox structure
* stream argument for functions
* pointer to current trial count
* returned user name
* Returns: T if success, NIL otherwise, number of trials incremented if retry
*/
long auth_login_client (authchallenge_t challenger,authrespond_t responder,
char *service,NETMBX *mb,void *stream,
unsigned long *trial,char *user)
{
char pwd[MAILTMPLEN];
void *challenge;
unsigned long clen;
long ret = NIL;
/* get user name prompt */
if (challenge = (*challenger) (stream,&clen)) {
fs_give ((void **) &challenge);
pwd[0] = NIL; /* prompt user */
mm_login (mb,user,pwd,*trial);
if (!pwd[0]) { /* user requested abort */
(*responder) (stream,NIL,0);
*trial = 0; /* cancel subsequent attempts */
ret = LONGT; /* will get a BAD response back */
}
/* send user name */
else if ((*responder) (stream,user,strlen (user)) &&
(challenge = (*challenger) (stream,&clen))) {
fs_give ((void **) &challenge);
/* send password */
if ((*responder) (stream,pwd,strlen (pwd))) {
if (challenge = (*challenger) (stream,&clen))
fs_give ((void **) &challenge);
else {
++*trial; /* can try again if necessary */
ret = LONGT; /* check the authentication */
}
}
}
}
memset (pwd,0,MAILTMPLEN); /* erase password */
if (!ret) *trial = 65535; /* don't retry if bad protocol */
return ret;
}
/* Server authenticator
* Accepts: responder function
* argument count
* argument vector
* Returns: authenticated user name or NIL
*/
char *auth_login_server (authresponse_t responder,int argc,char *argv[])
{
char *ret = NIL;
char *user,*pass,*authuser;
if (user = (*responder) (PWD_USER,sizeof (PWD_USER),NIL)) {
if (pass = (*responder) (PWD_PWD,sizeof (PWD_PWD),NIL)) {
/* delimit user from possible admin */
if (authuser = strchr (user,'*')) *authuser++ = '\0';
if (server_login (user,pass,authuser,argc,argv)) ret = myusername ();
fs_give ((void **) &pass);
}
fs_give ((void **) &user);
}
return ret;
}

495
src/c-client/auth_md5.c Normal file
View File

@ -0,0 +1,495 @@
/* ========================================================================
* Copyright 1988-2007 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
/*
* Program: CRAM-MD5 authenticator
*
* Author: Mark Crispin
* Networks and Distributed Computing
* Computing & Communications
* University of Washington
* Administration Building, AG-44
* Seattle, WA 98195
* Internet: MRC@CAC.Washington.EDU
*
* Date: 21 October 1998
* Last Edited: 30 January 2007
*/
/* MD5 context */
#define MD5BLKLEN 64 /* MD5 block length */
#define MD5DIGLEN 16 /* MD5 digest length */
typedef struct {
unsigned long chigh; /* high 32bits of byte count */
unsigned long clow; /* low 32bits of byte count */
unsigned long state[4]; /* state (ABCD) */
unsigned char buf[MD5BLKLEN]; /* input buffer */
unsigned char *ptr; /* buffer position */
} MD5CONTEXT;
/* Prototypes */
long auth_md5_valid (void);
long auth_md5_client (authchallenge_t challenger,authrespond_t responder,
char *service,NETMBX *mb,void *stream,
unsigned long *trial,char *user);
char *auth_md5_server (authresponse_t responder,int argc,char *argv[]);
char *auth_md5_pwd (char *user);
char *apop_login (char *chal,char *user,char *md5,int argc,char *argv[]);
char *hmac_md5 (char *text,unsigned long tl,char *key,unsigned long kl);
void md5_init (MD5CONTEXT *ctx);
void md5_update (MD5CONTEXT *ctx,unsigned char *data,unsigned long len);
void md5_final (unsigned char *digest,MD5CONTEXT *ctx);
static void md5_transform (unsigned long *state,unsigned char *block);
static void md5_encode (unsigned char *dst,unsigned long *src,int len);
static void md5_decode (unsigned long *dst,unsigned char *src,int len);
/* Authenticator linkage */
AUTHENTICATOR auth_md5 = {
AU_SECURE, /* secure authenticator */
"CRAM-MD5", /* authenticator name */
auth_md5_valid, /* check if valid */
auth_md5_client, /* client method */
auth_md5_server, /* server method */
NIL /* next authenticator */
};
/* Check if CRAM-MD5 valid on this system
* Returns: T, always
*/
long auth_md5_valid (void)
{
struct stat sbuf;
/* server forbids MD5 if no MD5 enable file */
if (stat (MD5ENABLE,&sbuf)) auth_md5.server = NIL;
return T; /* MD5 is otherwise valid */
}
/* Client authenticator
* Accepts: challenger function
* responder function
* SASL service name
* parsed network mailbox structure
* stream argument for functions
* pointer to current trial count
* returned user name
* Returns: T if success, NIL otherwise, number of trials incremented if retry
*/
long auth_md5_client (authchallenge_t challenger,authrespond_t responder,
char *service,NETMBX *mb,void *stream,
unsigned long *trial,char *user)
{
char pwd[MAILTMPLEN];
void *challenge;
unsigned long clen;
long ret = NIL;
/* get challenge */
if (challenge = (*challenger) (stream,&clen)) {
pwd[0] = NIL; /* prompt user */
mm_login (mb,user,pwd,*trial);
if (!pwd[0]) { /* user requested abort */
fs_give ((void **) &challenge);
(*responder) (stream,NIL,0);
*trial = 0; /* cancel subsequent attempts */
ret = LONGT; /* will get a BAD response back */
}
else { /* got password, build response */
sprintf (pwd,"%.65s %.33s",user,hmac_md5 (challenge,clen,
pwd,strlen (pwd)));
fs_give ((void **) &challenge);
/* send credentials, allow retry if OK */
if ((*responder) (stream,pwd,strlen (pwd))) {
if (challenge = (*challenger) (stream,&clen))
fs_give ((void **) &challenge);
else {
++*trial; /* can try again if necessary */
ret = LONGT; /* check the authentication */
}
}
}
}
memset (pwd,0,MAILTMPLEN); /* erase password in case not overwritten */
if (!ret) *trial = 65535; /* don't retry if bad protocol */
return ret;
}
/* Server authenticator
* Accepts: responder function
* argument count
* argument vector
* Returns: authenticated user name or NIL
*
* This is much hairier than it needs to be due to the necessary of zapping
* the password data.
*/
static int md5try = MAXLOGINTRIALS;
char *auth_md5_server (authresponse_t responder,int argc,char *argv[])
{
char *ret = NIL;
char *p,*u,*user,*authuser,*hash,chal[MAILTMPLEN];
unsigned long cl,pl;
/* generate challenge */
sprintf (chal,"<%lu.%lu@%s>",(unsigned long) getpid (),
(unsigned long) time (0),mylocalhost ());
/* send challenge, get user and hash */
if (user = (*responder) (chal,cl = strlen (chal),NIL)) {
/* got user, locate hash */
if (hash = strrchr (user,' ')) {
*hash++ = '\0'; /* tie off user */
/* see if authentication user */
if (authuser = strchr (user,'*')) *authuser++ = '\0';
/* get password */
if (p = auth_md5_pwd ((authuser && *authuser) ? authuser : user)) {
pl = strlen (p);
u = (md5try && !strcmp (hash,hmac_md5 (chal,cl,p,pl))) ? user : NIL;
memset (p,0,pl); /* erase sensitive information */
fs_give ((void **) &p); /* flush erased password */
/* now log in for real */
if (u && authserver_login (u,authuser,argc,argv)) ret = myusername ();
else if (md5try) --md5try;
}
}
fs_give ((void **) &user);
}
if (!ret) sleep (3); /* slow down possible cracker */
return ret;
}
/* Return MD5 password for user
* Accepts: user name
* Returns: plaintext password if success, else NIL
*
* This is much hairier than it needs to be due to the necessary of zapping
* the password data. That's why we don't use stdio here.
*/
char *auth_md5_pwd (char *user)
{
struct stat sbuf;
int fd = open (MD5ENABLE,O_RDONLY,NIL);
unsigned char *s,*t,*buf,*lusr,*lret;
char *r;
char *ret = NIL;
if (fd >= 0) { /* found the file? */
fstat (fd,&sbuf); /* yes, slurp it into memory */
read (fd,buf = (char *) fs_get (sbuf.st_size + 1),sbuf.st_size);
/* see if any uppercase characters in user */
for (s = user; *s && ((*s < 'A') || (*s > 'Z')); s++);
/* yes, make lowercase copy */
lusr = *s ? lcase (cpystr (user)) : NIL;
for (s = strtok_r ((char *) buf,"\015\012",&r),lret = NIL; s;
s = ret ? NIL : strtok_r (NIL,"\015\012",&r))
/* must be valid entry line */
if (*s && (*s != '#') && (t = strchr (s,'\t')) && t[1]) {
*t++ = '\0'; /* found tab, tie off user, point to pwd */
if (!strcmp (s,user)) ret = cpystr (t);
else if (lusr && !lret) if (!strcmp (s,lusr)) lret = t;
}
/* accept case-independent name */
if (!ret && lret) ret = cpystr (lret);
/* don't need lowercase copy any more */
if (lusr) fs_give ((void **) &lusr);
/* erase sensitive information from buffer */
memset (buf,0,sbuf.st_size + 1);
fs_give ((void **) &buf); /* flush the buffer */
close (fd); /* don't need file any longer */
}
return ret; /* return password */
}
/* APOP server login
* Accepts: challenge
* desired user name
* purported MD5
* argument count
* argument vector
* Returns: authenticated user name or NIL
*/
char *apop_login (char *chal,char *user,char *md5,int argc,char *argv[])
{
int i,j;
char *ret = NIL;
char *s,*authuser,tmp[MAILTMPLEN];
unsigned char digest[MD5DIGLEN];
MD5CONTEXT ctx;
char *hex = "0123456789abcdef";
/* see if authentication user */
if (authuser = strchr (user,'*')) *authuser++ = '\0';
/* get password */
if (s = auth_md5_pwd ((authuser && *authuser) ? authuser : user)) {
md5_init (&ctx); /* initialize MD5 context */
/* build string to get MD5 digest */
sprintf (tmp,"%.128s%.128s",chal,s);
memset (s,0,strlen (s)); /* erase sensitive information */
fs_give ((void **) &s); /* flush erased password */
md5_update (&ctx,(unsigned char *) tmp,strlen (tmp));
memset (tmp,0,MAILTMPLEN); /* erase sensitive information */
md5_final (digest,&ctx);
/* convert to printable hex */
for (i = 0, s = tmp; i < MD5DIGLEN; i++) {
*s++ = hex[(j = digest[i]) >> 4];
*s++ = hex[j & 0xf];
}
*s = '\0'; /* tie off hash text */
memset (digest,0,MD5DIGLEN);/* erase sensitive information */
if (md5try && !strcmp (md5,tmp) &&
authserver_login (user,authuser,argc,argv))
ret = cpystr (myusername ());
else if (md5try) --md5try;
memset (tmp,0,MAILTMPLEN); /* erase sensitive information */
}
if (!ret) sleep (3); /* slow down possible cracker */
return ret;
}
/*
* RFC 2104 HMAC hashing
* Accepts: text to hash
* text length
* key
* key length
* Returns: hash as text, always
*/
char *hmac_md5 (char *text,unsigned long tl,char *key,unsigned long kl)
{
int i,j;
static char hshbuf[2*MD5DIGLEN + 1];
char *s;
MD5CONTEXT ctx;
char *hex = "0123456789abcdef";
unsigned char digest[MD5DIGLEN],k_ipad[MD5BLKLEN+1],k_opad[MD5BLKLEN+1];
if (kl > MD5BLKLEN) { /* key longer than pad length? */
md5_init (&ctx); /* yes, set key as MD5(key) */
md5_update (&ctx,(unsigned char *) key,kl);
md5_final (digest,&ctx);
key = (char *) digest;
kl = MD5DIGLEN;
}
memcpy (k_ipad,key,kl); /* store key in pads */
memset (k_ipad+kl,0,(MD5BLKLEN+1)-kl);
memcpy (k_opad,k_ipad,MD5BLKLEN+1);
/* XOR key with ipad and opad values */
for (i = 0; i < MD5BLKLEN; i++) {
k_ipad[i] ^= 0x36;
k_opad[i] ^= 0x5c;
}
md5_init (&ctx); /* inner MD5: hash ipad and text */
md5_update (&ctx,k_ipad,MD5BLKLEN);
md5_update (&ctx,(unsigned char *) text,tl);
md5_final (digest,&ctx);
md5_init (&ctx); /* outer MD5: hash opad and inner results */
md5_update (&ctx,k_opad,MD5BLKLEN);
md5_update (&ctx,digest,MD5DIGLEN);
md5_final (digest,&ctx);
/* convert to printable hex */
for (i = 0, s = hshbuf; i < MD5DIGLEN; i++) {
*s++ = hex[(j = digest[i]) >> 4];
*s++ = hex[j & 0xf];
}
*s = '\0'; /* tie off hash text */
return hshbuf;
}
/* Everything after this point is derived from the RSA Data Security, Inc.
* MD5 Message-Digest Algorithm
*/
/* You may wonder why these strange "a &= 0xffffffff;" statements are here.
* This is to ensure correct results on machines with a unsigned long size of
* larger than 32 bits.
*/
#define RND1(a,b,c,d,x,s,ac) \
a += ((b & c) | (d & ~b)) + x + (unsigned long) ac; \
a &= 0xffffffff; \
a = b + ((a << s) | (a >> (32 - s)));
#define RND2(a,b,c,d,x,s,ac) \
a += ((b & d) | (c & ~d)) + x + (unsigned long) ac; \
a &= 0xffffffff; \
a = b + ((a << s) | (a >> (32 - s)));
#define RND3(a,b,c,d,x,s,ac) \
a += (b ^ c ^ d) + x + (unsigned long) ac; \
a &= 0xffffffff; \
a = b + ((a << s) | (a >> (32 - s)));
#define RND4(a,b,c,d,x,s,ac) \
a += (c ^ (b | ~d)) + x + (unsigned long) ac; \
a &= 0xffffffff; \
a = b + ((a << s) | (a >> (32 - s)));
/* Initialize MD5 context
* Accepts: context to initialize
*/
void md5_init (MD5CONTEXT *ctx)
{
ctx->clow = ctx->chigh = 0; /* initialize byte count to zero */
/* initialization constants */
ctx->state[0] = 0x67452301; ctx->state[1] = 0xefcdab89;
ctx->state[2] = 0x98badcfe; ctx->state[3] = 0x10325476;
ctx->ptr = ctx->buf; /* reset buffer pointer */
}
/* MD5 add data to context
* Accepts: context
* input data
* length of data
*/
void md5_update (MD5CONTEXT *ctx,unsigned char *data,unsigned long len)
{
unsigned long i = (ctx->buf + MD5BLKLEN) - ctx->ptr;
/* update double precision number of bytes */
if ((ctx->clow += len) < len) ctx->chigh++;
while (i <= len) { /* copy/transform data, 64 bytes at a time */
memcpy (ctx->ptr,data,i); /* fill up 64 byte chunk */
md5_transform (ctx->state,ctx->ptr = ctx->buf);
data += i,len -= i,i = MD5BLKLEN;
}
memcpy (ctx->ptr,data,len); /* copy final bit of data in buffer */
ctx->ptr += len; /* update buffer pointer */
}
/* MD5 Finalization
* Accepts: destination digest
* context
*/
void md5_final (unsigned char *digest,MD5CONTEXT *ctx)
{
unsigned long i,bits[2];
bits[0] = ctx->clow << 3; /* calculate length in bits (before padding) */
bits[1] = (ctx->chigh << 3) + (ctx->clow >> 29);
*ctx->ptr++ = 0x80; /* padding byte */
if ((i = (ctx->buf + MD5BLKLEN) - ctx->ptr) < 8) {
memset (ctx->ptr,0,i); /* pad out buffer with zeros */
md5_transform (ctx->state,ctx->buf);
/* pad out with zeros, leaving 8 bytes */
memset (ctx->buf,0,MD5BLKLEN - 8);
ctx->ptr = ctx->buf + MD5BLKLEN - 8;
}
else if (i -= 8) { /* need to pad this buffer? */
memset (ctx->ptr,0,i); /* yes, pad out with zeros, leaving 8 bytes */
ctx->ptr += i;
}
md5_encode (ctx->ptr,bits,2); /* make LSB-first length */
md5_transform (ctx->state,ctx->buf);
/* store state in digest */
md5_encode (digest,ctx->state,4);
/* erase context */
memset (ctx,0,sizeof (MD5CONTEXT));
}
/* MD5 basic transformation
* Accepts: state vector
* current 64-byte block
*/
static void md5_transform (unsigned long *state,unsigned char *block)
{
unsigned long a = state[0],b = state[1],c = state[2],d = state[3],x[16];
md5_decode (x,block,16); /* decode into 16 longs */
/* round 1 */
RND1 (a,b,c,d,x[ 0], 7,0xd76aa478); RND1 (d,a,b,c,x[ 1],12,0xe8c7b756);
RND1 (c,d,a,b,x[ 2],17,0x242070db); RND1 (b,c,d,a,x[ 3],22,0xc1bdceee);
RND1 (a,b,c,d,x[ 4], 7,0xf57c0faf); RND1 (d,a,b,c,x[ 5],12,0x4787c62a);
RND1 (c,d,a,b,x[ 6],17,0xa8304613); RND1 (b,c,d,a,x[ 7],22,0xfd469501);
RND1 (a,b,c,d,x[ 8], 7,0x698098d8); RND1 (d,a,b,c,x[ 9],12,0x8b44f7af);
RND1 (c,d,a,b,x[10],17,0xffff5bb1); RND1 (b,c,d,a,x[11],22,0x895cd7be);
RND1 (a,b,c,d,x[12], 7,0x6b901122); RND1 (d,a,b,c,x[13],12,0xfd987193);
RND1 (c,d,a,b,x[14],17,0xa679438e); RND1 (b,c,d,a,x[15],22,0x49b40821);
/* round 2 */
RND2 (a,b,c,d,x[ 1], 5,0xf61e2562); RND2 (d,a,b,c,x[ 6], 9,0xc040b340);
RND2 (c,d,a,b,x[11],14,0x265e5a51); RND2 (b,c,d,a,x[ 0],20,0xe9b6c7aa);
RND2 (a,b,c,d,x[ 5], 5,0xd62f105d); RND2 (d,a,b,c,x[10], 9, 0x2441453);
RND2 (c,d,a,b,x[15],14,0xd8a1e681); RND2 (b,c,d,a,x[ 4],20,0xe7d3fbc8);
RND2 (a,b,c,d,x[ 9], 5,0x21e1cde6); RND2 (d,a,b,c,x[14], 9,0xc33707d6);
RND2 (c,d,a,b,x[ 3],14,0xf4d50d87); RND2 (b,c,d,a,x[ 8],20,0x455a14ed);
RND2 (a,b,c,d,x[13], 5,0xa9e3e905); RND2 (d,a,b,c,x[ 2], 9,0xfcefa3f8);
RND2 (c,d,a,b,x[ 7],14,0x676f02d9); RND2 (b,c,d,a,x[12],20,0x8d2a4c8a);
/* round 3 */
RND3 (a,b,c,d,x[ 5], 4,0xfffa3942); RND3 (d,a,b,c,x[ 8],11,0x8771f681);
RND3 (c,d,a,b,x[11],16,0x6d9d6122); RND3 (b,c,d,a,x[14],23,0xfde5380c);
RND3 (a,b,c,d,x[ 1], 4,0xa4beea44); RND3 (d,a,b,c,x[ 4],11,0x4bdecfa9);
RND3 (c,d,a,b,x[ 7],16,0xf6bb4b60); RND3 (b,c,d,a,x[10],23,0xbebfbc70);
RND3 (a,b,c,d,x[13], 4,0x289b7ec6); RND3 (d,a,b,c,x[ 0],11,0xeaa127fa);
RND3 (c,d,a,b,x[ 3],16,0xd4ef3085); RND3 (b,c,d,a,x[ 6],23, 0x4881d05);
RND3 (a,b,c,d,x[ 9], 4,0xd9d4d039); RND3 (d,a,b,c,x[12],11,0xe6db99e5);
RND3 (c,d,a,b,x[15],16,0x1fa27cf8); RND3 (b,c,d,a,x[ 2],23,0xc4ac5665);
/* round 4 */
RND4 (a,b,c,d,x[ 0], 6,0xf4292244); RND4 (d,a,b,c,x[ 7],10,0x432aff97);
RND4 (c,d,a,b,x[14],15,0xab9423a7); RND4 (b,c,d,a,x[ 5],21,0xfc93a039);
RND4 (a,b,c,d,x[12], 6,0x655b59c3); RND4 (d,a,b,c,x[ 3],10,0x8f0ccc92);
RND4 (c,d,a,b,x[10],15,0xffeff47d); RND4 (b,c,d,a,x[ 1],21,0x85845dd1);
RND4 (a,b,c,d,x[ 8], 6,0x6fa87e4f); RND4 (d,a,b,c,x[15],10,0xfe2ce6e0);
RND4 (c,d,a,b,x[ 6],15,0xa3014314); RND4 (b,c,d,a,x[13],21,0x4e0811a1);
RND4 (a,b,c,d,x[ 4], 6,0xf7537e82); RND4 (d,a,b,c,x[11],10,0xbd3af235);
RND4 (c,d,a,b,x[ 2],15,0x2ad7d2bb); RND4 (b,c,d,a,x[ 9],21,0xeb86d391);
/* update state */
state[0] += a; state[1] += b; state[2] += c; state[3] += d;
memset (x,0,sizeof (x)); /* erase sensitive data */
}
/* You may wonder why these strange "& 0xff" maskings are here. This is to
* ensure correct results on machines with a char size of larger than 8 bits.
* For example, the KCC compiler on the PDP-10 uses 9-bit chars.
*/
/* MD5 encode unsigned long into LSB-first bytes
* Accepts: destination pointer
* source
* length of source
*/
static void md5_encode (unsigned char *dst,unsigned long *src,int len)
{
int i;
for (i = 0; i < len; i++) {
*dst++ = (unsigned char) (src[i] & 0xff);
*dst++ = (unsigned char) ((src[i] >> 8) & 0xff);
*dst++ = (unsigned char) ((src[i] >> 16) & 0xff);
*dst++ = (unsigned char) ((src[i] >> 24) & 0xff);
}
}
/* MD5 decode LSB-first bytes into unsigned long
* Accepts: destination pointer
* source
* length of destination
*/
static void md5_decode (unsigned long *dst,unsigned char *src,int len)
{
int i, j;
for (i = 0, j = 0; i < len; i++, j += 4)
dst[i] = ((unsigned long) (src[j] & 0xff)) |
(((unsigned long) (src[j+1] & 0xff)) << 8) |
(((unsigned long) (src[j+2] & 0xff)) << 16) |
(((unsigned long) (src[j+3] & 0xff)) << 24);
}

133
src/c-client/auth_pla.c Normal file
View File

@ -0,0 +1,133 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
/*
* Program: Plain authenticator
*
* Author: Mark Crispin
* Networks and Distributed Computing
* Computing & Communications
* University of Washington
* Administration Building, AG-44
* Seattle, WA 98195
* Internet: MRC@CAC.Washington.EDU
*
* Date: 22 September 1998
* Last Edited: 30 August 2006
*/
long auth_plain_client (authchallenge_t challenger,authrespond_t responder,
char *service,NETMBX *mb,void *stream,
unsigned long *trial,char *user);
char *auth_plain_server (authresponse_t responder,int argc,char *argv[]);
AUTHENTICATOR auth_pla = {
AU_AUTHUSER | AU_HIDE, /* allow authuser, hidden */
"PLAIN", /* authenticator name */
NIL, /* always valid */
auth_plain_client, /* client method */
auth_plain_server, /* server method */
NIL /* next authenticator */
};
/* Client authenticator
* Accepts: challenger function
* responder function
* SASL service name
* parsed network mailbox structure
* stream argument for functions
* pointer to current trial count
* returned user name
* Returns: T if success, NIL otherwise, number of trials incremented if retry
*/
long auth_plain_client (authchallenge_t challenger,authrespond_t responder,
char *service,NETMBX *mb,void *stream,
unsigned long *trial,char *user)
{
char *u,pwd[MAILTMPLEN];
void *challenge;
unsigned long clen;
long ret = NIL;
/* snarl if not SSL/TLS session */
if (!mb->sslflag && !mb->tlsflag)
mm_log ("SECURITY PROBLEM: insecure server advertised AUTH=PLAIN",WARN);
/* get initial (empty) challenge */
if (challenge = (*challenger) (stream,&clen)) {
fs_give ((void **) &challenge);
if (clen) { /* abort if challenge non-empty */
mm_log ("Server bug: non-empty initial PLAIN challenge",WARN);
(*responder) (stream,NIL,0);
ret = LONGT; /* will get a BAD response back */
}
pwd[0] = NIL; /* prompt user if empty challenge */
mm_login (mb,user,pwd,*trial);
if (!pwd[0]) { /* empty challenge or user requested abort */
(*responder) (stream,NIL,0);
*trial = 0; /* cancel subsequent attempts */
ret = LONGT; /* will get a BAD response back */
}
else {
unsigned long rlen =
strlen (mb->authuser) + strlen (user) + strlen (pwd) + 2;
char *response = (char *) fs_get (rlen);
char *t = response; /* copy authorization id */
if (mb->authuser[0]) for (u = user; *u; *t++ = *u++);
*t++ = '\0'; /* delimiting NUL */
/* copy authentication id */
for (u = mb->authuser[0] ? mb->authuser : user; *u; *t++ = *u++);
*t++ = '\0'; /* delimiting NUL */
/* copy password */
for (u = pwd; *u; *t++ = *u++);
/* send credentials */
if ((*responder) (stream,response,rlen)) {
if (challenge = (*challenger) (stream,&clen))
fs_give ((void **) &challenge);
else {
++*trial; /* can try again if necessary */
ret = LONGT; /* check the authentication */
}
}
memset (response,0,rlen); /* erase credentials */
fs_give ((void **) &response);
}
}
memset (pwd,0,MAILTMPLEN); /* erase password */
if (!ret) *trial = 65535; /* don't retry if bad protocol */
return ret;
}
/* Server authenticator
* Accepts: responder function
* argument count
* argument vector
* Returns: authenticated user name or NIL
*/
char *auth_plain_server (authresponse_t responder,int argc,char *argv[])
{
char *ret = NIL;
char *user,*aid,*pass;
unsigned long len;
/* get user name */
if (aid = (*responder) ("",0,&len)) {
/* note: responders null-terminate */
if ((((unsigned long) ((user = aid + strlen (aid) + 1) - aid)) < len) &&
(((unsigned long) ((pass = user + strlen (user) + 1) - aid)) < len) &&
(((unsigned long) ((pass + strlen (pass)) - aid)) == len) &&
(*aid ? server_login (aid,pass,user,argc,argv) :
server_login (user,pass,NIL,argc,argv))) ret = myusername ();
fs_give ((void **) &aid);
}
return ret;
}

55
src/c-client/c-client.h Normal file
View File

@ -0,0 +1,55 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
/*
* Program: c-client master include for application programs
*
* Author: Mark Crispin
* Networks and Distributed Computing
* Computing & Communications
* University of Washington
* Administration Building, AG-44
* Seattle, WA 98195
* Internet: MRC@CAC.Washington.EDU
*
* Date: 19 May 2000
* Last Edited: 6 December 2006
*/
#ifndef __CCLIENT_H /* nobody should include this twice... */
#define __CCLIENT_H
#ifdef __cplusplus /* help out people who use C++ compilers */
extern "C" {
/* If you use gcc, you may also have to use -fno-operator-names */
#define private cclientPrivate /* private to c-client */
#define and cclientAnd /* C99 doesn't realize that ISO 646 is dead */
#define or cclientOr
#define not cclientNot
#endif
#include "mail.h" /* primary interfaces */
#include "osdep.h" /* OS-dependent routines */
#include "rfc822.h" /* RFC822 and MIME routines */
#include "smtp.h" /* SMTP sending routines */
#include "nntp.h" /* NNTP sending routines */
#include "utf8.h" /* Unicode and charset routines */
#include "utf8aux.h" /* Unicode auxillary routines */
#include "misc.h" /* miscellaneous utility routines */
#ifdef __cplusplus /* undo the C++ mischief */
#undef private
}
#endif
#endif

45
src/c-client/env.h Normal file
View File

@ -0,0 +1,45 @@
/* ========================================================================
* Copyright 1988-2008 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
/*
* Program: Environment routines
*
* Author: Mark Crispin
* UW Technology
* University of Washington
* Seattle, WA 98195
* Internet: MRC@Washington.EDU
*
* Date: 1 August 1988
* Last Edited: 13 February 2008
*/
/* Function prototypes */
long pmatch_full (unsigned char *s,unsigned char *pat,unsigned char delim);
long dmatch (unsigned char *s,unsigned char *pat,unsigned char delim);
void *env_parameters (long function,void *value);
void rfc822_date (char *date);
void rfc822_timezone (char *s,void *t);
void internal_date (char *date);
long server_input_wait (long seconds);
void server_init (char *server,char *service,char *sasl,
void *clkint,void *kodint,void *hupint,void *trmint,
void *staint);
long server_login (char *user,char *pass,char *authuser,int argc,char *argv[]);
long authserver_login (char *user,char *authuser,int argc,char *argv[]);
long anonymous_login (int argc,char *argv[]);
char *mylocalhost (void);
char *myhomedir (void);
char *mailboxfile (char *dst,char *name);
MAILSTREAM *default_proto (long type);

91
src/c-client/flstring.c Normal file
View File

@ -0,0 +1,91 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
/*
* Program: File string routines
*
* Author: Mark Crispin
* Networks and Distributed Computing
* Computing & Communications
* University of Washington
* Administration Building, AG-44
* Seattle, WA 98195
* Internet: MRC@CAC.Washington.EDU
*
* Date: 15 April 1997
* Last Edited: 6 December 2006
*/
#include <stdio.h>
#include "mail.h"
#include "flstring.h"
/* String driver for stdio file strings */
static void file_string_init (STRING *s,void *data,unsigned long size);
static char file_string_next (STRING *s);
static void file_string_setpos (STRING *s,unsigned long i);
STRINGDRIVER file_string = {
file_string_init, /* initialize string structure */
file_string_next, /* get next byte in string structure */
file_string_setpos /* set position in string structure */
};
/* Initialize mail string structure for file
* Accepts: string structure
* pointer to string
* size of string
*/
static void file_string_init (STRING *s,void *data,unsigned long size)
{
s->data = data; /* note file descriptor */
/* big enough for one byte */
s->chunk = s->curpos = (char *) &s->data1;
s->size = size; /* data size */
s->cursize = s->chunksize = 1;/* always call stdio */
file_string_setpos (s,0); /* initial offset is 0 */
}
/* Get next character from string
* Accepts: string structure
* Returns: character, string structure chunk refreshed
*/
static char file_string_next (STRING *s)
{
char ret = *s->curpos;
s->offset++; /* advance position */
s->cursize = 1; /* reset size */
*s->curpos = (char) getc ((FILE *) s->data);
return ret;
}
/* Set string pointer position
* Accepts: string structure
* new position
*/
static void file_string_setpos (STRING *s,unsigned long i)
{
s->offset = i; /* note new offset */
fseek ((FILE *) s->data,i,SEEK_SET);
/* in case using returnstringstruct hack */
s->chunk = s->curpos = (char *) &s->data1;
*s->curpos = (char) getc ((FILE *) s->data);
}

30
src/c-client/flstring.h Normal file
View File

@ -0,0 +1,30 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
/*
* Program: File string routines
*
* Author: Mark Crispin
* Networks and Distributed Computing
* Computing & Communications
* University of Washington
* Administration Building, AG-44
* Seattle, WA 98195
* Internet: MRC@CAC.Washington.EDU
*
* Date: 15 April 1997
* Last Edited: 30 August 2006
*/
extern STRINGDRIVER file_string;

34
src/c-client/fs.h Normal file
View File

@ -0,0 +1,34 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
/*
* Program: Free storage management routines
*
* Author: Mark Crispin
* Networks and Distributed Computing
* Computing & Communications
* University of Washington
* Administration Building, AG-44
* Seattle, WA 98195
* Internet: MRC@CAC.Washington.EDU
*
* Date: 1 August 1988
* Last Edited: 30 August 2006
*/
/* Function prototypes */
void *fs_get (size_t size);
void fs_resize (void **block,size_t size);
void fs_give (void **block);

32
src/c-client/ftl.h Normal file
View File

@ -0,0 +1,32 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
/*
* Program: Crash management routines
*
* Author: Mark Crispin
* Networks and Distributed Computing
* Computing & Communications
* University of Washington
* Administration Building, AG-44
* Seattle, WA 98195
* Internet: MRC@CAC.Washington.EDU
*
* Date: 1 August 1988
* Last Edited: 30 August 2006
*/
/* Function prototypes */
void fatal (char *string);

5670
src/c-client/imap4r1.c Normal file
View File

File diff suppressed because it is too large Load Diff

281
src/c-client/imap4r1.h Normal file
View File

@ -0,0 +1,281 @@
/* ========================================================================
* Copyright 1988-2007 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
/*
* Program: Interactive Mail Access Protocol 4rev1 (IMAP4R1) routines
*
* Author: Mark Crispin
* Networks and Distributed Computing
* Computing & Communications
* University of Washington
* Administration Building, AG-44
* Seattle, WA 98195
* Internet: MRC@CAC.Washington.EDU
*
* Date: 14 October 1988
* Last Edited: 5 September 2007
*/
/* This include file is provided for applications which need to look under
* the covers at the IMAP driver and in particular want to do different
* operations depending upon the IMAP server's protocol level and
* capabilities. It is NOT included in the normal c-client.h application
* export, and most applications do NOT need the definitions in this file.
*
* As of October 15, 2003, it is believed that:
*
* Version RFC Status Known Implementations
* ------- --- ------ ---------------------
* IMAP1 none extinct experimental TOPS-20 server
* IMAP2 1064 extinct old TOPS-20, SUMEX servers
* IMAP2 1176 rare TOPS-20, old UW servers
* IMAP2bis expired I-D uncommon old UW, Cyrus servers
* IMAP3 1203 extinct none (never implemented)
* IMAP4 1730 rare old UW, Cyrus, Netscape servers
* IMAP4rev1 2060, 3501 ubiquitous UW, Cyrus, and many others
*
* Most client implementations will only interoperate with an IMAP4rev1
* server. c-client based client implementations can interoperate with IMAP2,
* IMAP2bis, IMAP4, and IMAP4rev1 servers, but only if they are very careful.
*
* The LEVELxxx() macros in this file enable the client to determine the
* server protocol level and capabilities. This file also contains a few
* backdoor calls into the IMAP driver.
*/
/* Server protocol level and capabilities */
typedef struct imap_cap {
unsigned int rfc1176 : 1; /* server is RFC-1176 IMAP2 */
unsigned int imap2bis : 1; /* server is IMAP2bis */
unsigned int imap4 : 1; /* server is IMAP4 (RFC 1730) */
unsigned int imap4rev1 : 1; /* server is IMAP4rev1 */
unsigned int acl : 1; /* server has ACL (RFC 2086) */
unsigned int quota : 1; /* server has QUOTA (RFC 2087) */
unsigned int litplus : 1; /* server has LITERAL+ (RFC 2088) */
unsigned int idle : 1; /* server has IDLE (RFC 2177) */
unsigned int mbx_ref : 1; /* server has mailbox referrals (RFC 2193) */
unsigned int log_ref : 1; /* server has login referrals (RFC 2221) */
unsigned int authanon : 1; /* server has anonymous SASL (RFC 2245) */
unsigned int namespace :1; /* server has NAMESPACE (RFC 2342) */
unsigned int uidplus : 1; /* server has UIDPLUS (RFC 2359) */
unsigned int starttls : 1; /* server has STARTTLS (RFC 2595) */
/* server disallows LOGIN command (RFC 2595) */
unsigned int logindisabled : 1;
unsigned int id : 1; /* server has ID (RFC 2971) */
unsigned int children : 1; /* server has CHILDREN (RFC 3348) */
unsigned int multiappend : 1; /* server has multi-APPEND (RFC 3502) ;*/
unsigned int binary : 1; /* server has BINARY (RFC 3516) */
unsigned int unselect : 1; /* server has UNSELECT */
unsigned int sasl_ir : 1; /* server has SASL-IR initial response */
unsigned int sort : 1; /* server has SORT */
unsigned int scan : 1; /* server has SCAN */
unsigned int urlauth : 1; /* server has URLAUTH (RFC 4467) */
unsigned int catenate : 1; /* server has CATENATE (RFC 4469) */
unsigned int condstore : 1; /* server has CONDSTORE (RFC 4551) */
unsigned int esearch : 1; /* server has ESEARCH (RFC 4731) */
unsigned int within : 1; /* server has WITHIN (RFC 5032) */
unsigned int extlevel; /* extension data level supported by server */
/* supported authenticators */
unsigned int auth : MAXAUTHENTICATORS;
THREADER *threader; /* list of threaders */
} IMAPCAP;
/* IMAP4rev1 level or better */
#define LEVELIMAP4rev1(stream) imap_cap (stream)->imap4rev1
#define LEVELSTATUS LEVELIMAP4rev1
/* IMAP4 level or better (not including RFC 1730 design mistakes) */
#define LEVELIMAP4(stream) (imap_cap (stream)->imap4rev1 || \
imap_cap (stream)->imap4)
/* IMAP4 RFC-1730 level */
#define LEVEL1730(stream) imap_cap (stream)->imap4
/* IMAP2bis level or better */
#define LEVELIMAP2bis(stream) imap_cap (stream)->imap2bis
/* IMAP2 RFC-1176 level or better */
#define LEVEL1176(stream) imap_cap (stream)->rfc1176
/* IMAP2 RFC-1064 or better */
#define LEVEL1064(stream) 1
/* Has ACL extension */
#define LEVELACL(stream) imap_cap (stream)->acl
/* Has QUOTA extension */
#define LEVELQUOTA(stream) imap_cap (stream)->quota
/* Has LITERALPLUS extension */
#define LEVELLITERALPLUS(stream) imap_cap (stream)->litplus
/* Has IDLE extension */
#define LEVELIDLE(stream) imap_cap (stream)->idle
/* Has mailbox referrals */
#define LEVELMBX_REF(stream) imap_cap (stream)->mbx_ref
/* Has login referrals */
#define LEVELLOG_REF(stream) imap_cap (stream)->log_ref
/* Has AUTH=ANONYMOUS extension */
#define LEVELANONYMOUS(stream) imap_cap (stream)->authanon
/* Has NAMESPACE extension */
#define LEVELNAMESPACE(stream) imap_cap (stream)->namespace
/* Has UIDPLUS extension */
#define LEVELUIDPLUS(stream) imap_cap (stream)->uidplus
/* Has STARTTLS extension */
#define LEVELSTARTTLS(stream) imap_cap (stream)->starttls
/* Has LOGINDISABLED extension */
#define LEVELLOGINDISABLED(stream) imap_cap (stream)->logindisabled
/* Has ID extension */
#define LEVELID(stream) imap_cap (stream)->id
/* Has CHILDREN extension */
#define LEVELCHILDREN(stream) imap_cap (stream)->children
/* Has MULTIAPPEND extension */
#define LEVELMULTIAPPEND(stream) imap_cap (stream)->multiappend
/* Has BINARY extension */
#define LEVELBINARY(stream) imap_cap (stream)->binary
/* Has UNSELECT extension */
#define LEVELUNSELECT(stream) imap_cap (stream)->unselect
/* Has SASL initial response extension */
#define LEVELSASLIR(stream) imap_cap (stream)->sasl_ir
/* Has SORT extension */
#define LEVELSORT(stream) imap_cap (stream)->sort
/* Has at least one THREAD extension */
#define LEVELTHREAD(stream) ((imap_cap (stream)->threader) ? T : NIL)
/* Has SCAN extension */
#define LEVELSCAN(stream) imap_cap (stream)->scan
/* Has URLAUTH extension */
#define LEVELURLAUTH(stream) imap_cap (stream)->urlauth
/* Has CATENATE extension */
#define LEVELCATENATE(stream) imap_cap (stream)->catenate
/* Has CONDSTORE extension */
#define LEVELCONDSTORE(stream) imap_cap (stream)->condstore
/* Has ESEARCH extension */
#define LEVELESEARCH(stream) imap_cap (stream)->esearch
/* Has WITHIN extension */
#define LEVELWITHIN(stream) imap_cap (stream)->within
/* Body structure extension levels */
/* These are in BODYSTRUCTURE order. Note that multipart bodies do not have
* body-fld-md5. This is alright, since all subsequent body structure
* extensions are in both singlepart and multipart bodies. If that ever
* changes, this will have to be split.
*/
#define BODYEXTMD5 1 /* body-fld-md5 */
#define BODYEXTDSP 2 /* body-fld-dsp */
#define BODYEXTLANG 3 /* body-fld-lang */
#define BODYEXTLOC 4 /* body-fld-loc */
/* Function prototypes */
IMAPCAP *imap_cap (MAILSTREAM *stream);
char *imap_host (MAILSTREAM *stream);
long imap_cache (MAILSTREAM *stream,unsigned long msgno,char *seg,
STRINGLIST *stl,SIZEDTEXT *text);
/* Temporary */
long imap_setacl (MAILSTREAM *stream,char *mailbox,char *id,char *rights);
long imap_deleteacl (MAILSTREAM *stream,char *mailbox,char *id);
long imap_getacl (MAILSTREAM *stream,char *mailbox);
long imap_listrights (MAILSTREAM *stream,char *mailbox,char *id);
long imap_myrights (MAILSTREAM *stream,char *mailbox);
long imap_setquota (MAILSTREAM *stream,char *qroot,STRINGLIST *limits);
long imap_getquota (MAILSTREAM *stream,char *qroot);
long imap_getquotaroot (MAILSTREAM *stream,char *mailbox);

6331
src/c-client/mail.c Normal file
View File

File diff suppressed because it is too large Load Diff

1837
src/c-client/mail.h Normal file
View File

File diff suppressed because it is too large Load Diff

475
src/c-client/misc.c Normal file
View File

@ -0,0 +1,475 @@
/* ========================================================================
* Copyright 1988-2006 University of Washington
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* ========================================================================
*/
/*
* Program: Miscellaneous utility routines
*
* Author: Mark Crispin
* Networks and Distributed Computing
* Computing & Communications
* University of Washington
* Administration Building, AG-44
* Seattle, WA 98195
* Internet: MRC@CAC.Washington.EDU
*
* Date: 5 July 1988
* Last Edited: 6 December 2006
*
* This original version of this file is
* Copyright 1988 Stanford University
* and was developed in the Symbolic Systems Resources Group of the Knowledge
* Systems Laboratory at Stanford University in 1987-88, and was funded by the
* Biomedical Research Technology Program of the NationalInstitutes of Health
* under grant number RR-00785.
*/
#include <ctype.h>
#include "c-client.h"
/* Convert ASCII string to all uppercase
* Accepts: string pointer
* Returns: string pointer
*
* Don't use islower/toupper since this function must be ASCII only.
*/
unsigned char *ucase (unsigned char *s)
{
unsigned char *t;
/* if lowercase covert to upper */
for (t = s; *t; t++) if ((*t >= 'a') && (*t <= 'z')) *t -= ('a' - 'A');
return s; /* return string */
}
/* Convert string to all lowercase
* Accepts: string pointer
* Returns: string pointer
*
* Don't use isupper/tolower since this function must be ASCII only.
*/
unsigned char *lcase (unsigned char *s)
{
unsigned char *t;
/* if uppercase covert to lower */
for (t = s; *t; t++) if ((*t >= 'A') && (*t <= 'Z')) *t += ('a' - 'A');
return s; /* return string */
}
/* Copy string to free storage
* Accepts: source string
* Returns: free storage copy of string
*/
char *cpystr (const char *string)
{
return string ? strcpy ((char *) fs_get (1 + strlen (string)),string) : NIL;
}
/* Copy text/size to free storage as sized text
* Accepts: destination sized text
* pointer to source text
* size of source text
* Returns: text as a char *
*/
char *cpytxt (SIZEDTEXT *dst,char *text,unsigned long size)
{
/* flush old space */
if (dst->data) fs_give ((void **) &dst->data);
/* copy data in sized text */
memcpy (dst->data = (unsigned char *)
fs_get ((size_t) (dst->size = size) + 1),text,(size_t) size);
dst->data[size] = '\0'; /* tie off text */
return (char *) dst->data; /* convenience return */
}
/* Copy sized text to free storage as sized text
* Accepts: destination sized text
* source sized text
* Returns: text as a char *
*/
char *textcpy (SIZEDTEXT *dst,SIZEDTEXT *src)
{
/* flush old space */
if (dst->data) fs_give ((void **) &dst->data);
/* copy data in sized text */
memcpy (dst->data = (unsigned char *)
fs_get ((size_t) (dst->size = src->size) + 1),
src->data,(size_t) src->size);
dst->data[dst->size] = '\0'; /* tie off text */
return (char *) dst->data; /* convenience return */
}
/* Copy stringstruct to free storage as sized text
* Accepts: destination sized text
* source stringstruct
* Returns: text as a char *
*/
char *textcpystring (SIZEDTEXT *text,STRING *bs)
{
unsigned long i = 0;
/* clear old space */
if (text->data) fs_give ((void **) &text->data);
/* make free storage space in sized text */
text->data = (unsigned char *) fs_get ((size_t) (text->size = SIZE (bs)) +1);
while (i < text->size) text->data[i++] = SNX (bs);
text->data[i] = '\0'; /* tie off text */
return (char *) text->data; /* convenience return */
}
/* Copy stringstruct from offset to free storage as sized text
* Accepts: destination sized text
* source stringstruct
* offset into stringstruct
* size of source text
* Returns: text as a char *
*/
char *textcpyoffstring (SIZEDTEXT *text,STRING *bs,unsigned long offset,
unsigned long size)
{
unsigned long i = 0;
/* clear old space */
if (text->data) fs_give ((void **) &text->data);
SETPOS (bs,offset); /* offset the string */
/* make free storage space in sized text */
text->data = (unsigned char *) fs_get ((size_t) (text->size = size) + 1);
while (i < size) text->data[i++] = SNX (bs);
text->data[i] = '\0'; /* tie off text */
return (char *) text->data; /* convenience return */
}
/* Returns index of rightmost bit in word
* Accepts: pointer to a 32 bit value
* Returns: -1 if word is 0, else index of rightmost bit
*
* Bit is cleared in the word
*/
unsigned long find_rightmost_bit (unsigned long *valptr)
{
unsigned long value = *valptr;
unsigned long bit = 0;
if (!(value & 0xffffffff)) return 0xffffffff;
/* binary search for rightmost bit */
if (!(value & 0xffff)) value >>= 16, bit += 16;
if (!(value & 0xff)) value >>= 8, bit += 8;
if (!(value & 0xf)) value >>= 4, bit += 4;
if (!(value & 0x3)) value >>= 2, bit += 2;
if (!(value & 0x1)) value >>= 1, bit += 1;
*valptr ^= (1 << bit); /* clear specified bit */
return bit;
}
/* Return minimum of two integers
* Accepts: integer 1
* integer 2
* Returns: minimum
*/
long min (long i,long j)
{
return ((i < j) ? i : j);
}
/* Return maximum of two integers
* Accepts: integer 1
* integer 2
* Returns: maximum
*/
long max (long i,long j)
{
return ((i > j) ? i : j);
}
/* Search, case-insensitive for ASCII characters
* Accepts: base string
* length of base string
* pattern string
* length of pattern string
* Returns: T if pattern exists inside base, else NIL
*/
long search (unsigned char *base,long basec,unsigned char *pat,long patc)
{
long i,j,k;
int c;
unsigned char mask[256];
static unsigned char alphatab[256] = {
255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
255,223,223,223,223,223,223,223,223,223,223,223,223,223,223,223,
223,223,223,223,223,223,223,223,223,223,223,255,255,255,255,255,
255,223,223,223,223,223,223,223,223,223,223,223,223,223,223,223,
223,223,223,223,223,223,223,223,223,223,223,255,255,255,255,255,
255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,
255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255
};
/* validate arguments */
if (base && (basec > 0) && pat && (basec >= patc)) {
if (patc <= 0) return T; /* empty pattern always succeeds */
memset (mask,0,256); /* initialize search validity mask */
for (i = 0; i < patc; i++) if (!mask[c = pat[i]]) {
/* mark single character if non-alphabetic */
if (alphatab[c] & 0x20) mask[c] = T;
/* else mark both cases */
else mask[c & 0xdf] = mask[c | 0x20] = T;
}
/* Boyer-Moore type search */
for (i = --patc; i < basec; i += (mask[c] ? 1 : (j + 1)))
for (j = patc,c = base[k = i]; !((c ^ pat[j]) & alphatab[c]);
j--,c = base[--k])
if (!j) return T; /* found a match! */
}
return NIL; /* pattern not found */
}
/* Boyer-Moore string search
* Accepts: base string
* length of base string
* pattern string
* length of pattern string
* Returns: T if pattern exists inside base, else NIL
*/
long ssearch (unsigned char *base,long basec,unsigned char *pat,long patc)
{
long i,j,k;
int c;
unsigned char mask[256];
/* validate arguments */
if (base && (basec > 0) && pat && (basec >= patc)) {
if (patc <= 0) return T; /* empty pattern always succeeds */
memset (mask,0,256); /* initialize search validity mask */
for (i = 0; i < patc; i++) mask[pat[i]] = T;
/* Boyer-Moore type search */
for (i = --patc, c = pat[i]; i < basec; i += (mask[c] ? 1 : (j + 1)))
for (j = patc,c = base[k = i]; (c == pat[j]); j--,c = base[--k])
if (!j) return T; /* found a match! */
}
return NIL; /* pattern not found */
}
/* Create a hash table
* Accepts: size of new table (note: should be a prime)
* Returns: hash table
*/
HASHTAB *hash_create (size_t size)
{
size_t i = sizeof (size_t) + size * sizeof (HASHENT *);
HASHTAB *ret = (HASHTAB *) memset (fs_get (i),0,i);
ret->size = size;
return ret;
}
/* Destroy hash table
* Accepts: hash table
*/
void hash_destroy (HASHTAB **hashtab)
{
if (*hashtab) {
hash_reset (*hashtab); /* reset hash table */
fs_give ((void **) hashtab);
}
}
/* Reset hash table
* Accepts: hash table
*/
void hash_reset (HASHTAB *hashtab)
{
size_t i;
HASHENT *ent,*nxt;
/* free each hash entry */
for (i = 0; i < hashtab->size; i++) if (ent = hashtab->table[i])
for (hashtab->table[i] = NIL; ent; ent = nxt) {
nxt = ent->next; /* get successor */
fs_give ((void **) &ent); /* flush this entry */
}
}
/* Calculate index into hash table
* Accepts: hash table
* entry name
* Returns: index
*/
unsigned long hash_index (HASHTAB *hashtab,char *key)
{
unsigned long i,ret;
/* polynomial of letters of the word */
for (ret = 0; i = (unsigned int) *key++; ret += i) ret *= HASHMULT;
return ret % (unsigned long) hashtab->size;
}
/* Look up name in hash table
* Accepts: hash table
* key
* Returns: associated data
*/
void **hash_lookup (HASHTAB *hashtab,char *key)
{
HASHENT *ret;
for (ret = hashtab->table[hash_index (hashtab,key)]; ret; ret = ret->next)
if (!strcmp (key,ret->name)) return ret->data;
return NIL;
}
/* Add entry to hash table
* Accepts: hash table
* key
* associated data
* number of extra data slots
* Returns: hash entry
* Caller is responsible for ensuring that entry isn't already in table
*/
HASHENT *hash_add (HASHTAB *hashtab,char *key,void *data,long extra)
{
unsigned long i = hash_index (hashtab,key);
size_t j = sizeof (HASHENT) + (extra * sizeof (void *));
HASHENT *ret = (HASHENT *) memset (fs_get (j),0,j);
ret->next = hashtab->table[i];/* insert as new head in this index */
ret->name = key; /* set up hash key */
ret->data[0] = data; /* and first data */
return hashtab->table[i] = ret;
}
/* Look up name in hash table
* Accepts: hash table
* key
* associated data
* number of extra data slots
* Returns: associated data
*/
void **hash_lookup_and_add (HASHTAB *hashtab,char *key,void *data,long extra)
{
HASHENT *ret;
unsigned long i = hash_index (hashtab,key);
size_t j = sizeof (HASHENT) + (extra * sizeof (void *));
for (ret = hashtab->table[i]; ret; ret = ret->next)
if (!strcmp (key,ret->name)) return ret->data;
ret = (HASHENT *) memset (fs_get (j),0,j);
ret->next = hashtab->table[i];/* insert as new head in this index */
ret->name = key; /* set up hash key */
ret->data[0] = data; /* and first data */
return (hashtab->table[i] = ret)->data;
}
/* Convert two hex characters into byte
* Accepts: char for high nybble
* char for low nybble
* Returns: byte
*
* Arguments must be isxdigit validated
*/
unsigned char hex2byte (unsigned char c1,unsigned char c2)
{
/* merge the two nybbles */
return ((c1 -= (isdigit (c1) ? '0' : ((c1 <= 'Z') ? 'A' : 'a') - 10)) << 4) +
(c2 - (isdigit (c2) ? '0' : ((c2 <= 'Z') ? 'A' : 'a') - 10));
}
/* Compare two unsigned longs
* Accepts: first value
* second value
* Returns: -1 if l1 < l2, 0 if l1 == l2, 1 if l1 > l2
*/
int compare_ulong (unsigned long l1,unsigned long l2)
{
if (l1 < l2) return -1;
if (l1 > l2) return 1;
return 0;
}
/* Compare two unsigned chars, case-independent
* Accepts: first value
* second value
* Returns: -1 if c1 < c2, 0 if c1 == c2, 1 if c1 > c2
*
* Don't use isupper/tolower since this function must be ASCII only.
*/
int compare_uchar (unsigned char c1,unsigned char c2)
{
return compare_ulong (((c1 >= 'A') && (c1 <= 'Z')) ? c1 + ('a' - 'A') : c1,
((c2 >= 'A') && (c2 <= 'Z')) ? c2 + ('a' - 'A') : c2);
}
/* Compare two case-independent ASCII strings
* Accepts: first string
* second string
* Returns: -1 if s1 < s2, 0 if s1 == s2, 1 if s1 > s2
*/
int compare_cstring (unsigned char *s1,unsigned char *s2)
{
int i;
if (!s1) return s2 ? -1 : 0; /* empty string cases */
else if (!s2) return 1;
for (; *s1 && *s2; s1++,s2++) if (i = (compare_uchar (*s1,*s2))) return i;
if (*s1) return 1; /* first string is longer */
return *s2 ? -1 : 0; /* second string longer : strings identical */
}
/* Compare case-independent string with sized text
* Accepts: first string
* sized text
* Returns: -1 if s1 < s2, 0 if s1 == s2, 1 if s1 > s2
*/
int compare_csizedtext (unsigned char *s1,SIZEDTEXT *s2)
{
int i;
unsigned char *s;
unsigned long j;
if (!s1) return s2 ? -1 : 0; /* null string cases */
else if (!s2) return 1;
for (s = (char *) s2->data,j = s2->size; *s1 && j; ++s1,++s,--j)
if (i = (compare_uchar (*s1,*s))) return i;
if (*s1) return 1; /* first string is longer */
return j ? -1 : 0; /* second string longer : strings identical */
}

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