Network Working Group M. Gahrns Internet Draft Microsoft Document: draft-gahrns-imap-referrals-00.txt January 1997 IMAP4 Referrals Status of this Memo This document is an Internet Draft. 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. Internet Drafts may be updated, replaced, or obsoleted by other documents at any time. It is not appropriate to use Internet Drafts as reference material or to cite them other than as a "working draft" or "work in progress". To learn the current status of any Internet-Draft, please check the 1id-abstracts.txt listing contained in the Internet-Drafts Shadow Directories on ds.internic.net, nic.nordu.net, ftp.isi.edu, or munnari.oz.au. 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. This document will expire before August 1997. Distribution of this draft is unlimited. 1. Abstract When dealing with large amounts of users, messages and geographically dispersed IMAP4 [RFC-2060] servers, it may be desirable to distribute messages and users amongst different servers within an organization. For example, an IMAP4 server may choose to store user's private mailboxes locally, while shared mailboxes are stored remotely on another server. This may be required if it is uneconomical to replicate all shared mailboxes to the user's local server, due to limited bandwidth or disk resources. Using a referral mechanism, an IMAP4 client is able to determine the home server of a user, by examining the referral response code at connection startup or in response to a LOGIN or AUTHENTICATE command. By knowing the name of any IMAP4 server in the organization, a user can be transparently connected to their home IMAP4 server. This greatly facilitates the ability of an administrator to transparently move users between IMAP4 servers for reasons such as hardware failures or organizational changes. In addition, by examining the referrals response code in response to a SELECT command, a client is able to seamlessly access mailboxes that may be distributed across several IMAP4 servers. Gahrns 1 IMAP4 Referrals January 1997 A referral mechanism can provide efficiencies over the alternative "proxy method", where the local IMAP4 server would contact the remote server on behalf of the client, and then transfer the data from the remote server to itself, and then on to the client. The referral mechanism92s 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 remote mailbox is a mailbox that is not hosted on the server that the client is connected to. A local mailbox is a mailbox that is hosted on the server that the client is connected to. A home IMAP4 server, is an IMAP4 server that contains the user's inbox. A shared mailbox, is a mailbox that multiple users have access to. SHOULD, MUST and MAY are terms used in this document to signify the requirements of this specification. They are defined in accordance with [RFC-2060]. 3. Introduction and Overview IMAP4 servers that support the referral extension do not list a new supported keyword in response to the CAPABILITY command. Referrals are returned as untagged responses that IMAP4 compliant clients are prepared to accept at all times. 4. Responses 4.1 Home Server Referrals 4.1.1 LOGIN response extension: untagged REFERRALS response code A referrals enabled IMAP4 server SHOULD respond to a LOGIN command with an untagged NO response, if the specified user is not located on the server, and the server is able to refer the client to the user's home server. The untagged NO response MUST contain a REFFERALS response code that contains as an argument a single IMAP URL as defined in [IMAP-URL]. The IMAP URL SHOULD contain the home server name and optional port. A final tagged NO response MUST be sent to complete the LOGIN response. Example: C: A001 LOGIN MIKE PASSWORD S: * NO [REFERRAL IMAP://SERVER2/] S: A001 NO Specified user is invalid on this server. Try SERVER2 Gahrns 2 IMAP4 Referrals January, 1997 4.1.2 AUTHENTICATE response extension: untagged REFERRALS response code A referrals enabled IMAP4 server SHOULD respond to an AUTHENTICATE command with an untagged NO response, if the user specified during the authentication exchange is not located on the server, and the server is able to refer the client to the user's home server. The untagged NO response MUST contain a REFFERALS response code that contains as an argument a single IMAP URL as defined in [IMAP-URL]. The IMAP URL SHOULD contain the home server name and optional port. A final tagged NO response MUST be sent to complete the AUTHENTICATE response. Example: C: A001 AUTHENTICATE KERBEROS_V4 S: + AweFG-0 C: BFsDdfJLEfdLeLLEFF9KLWsdfelf/Sdfef4sdwe S: + wsEd/aSSWf C: HiWdf3fg45fw:Lge S: * NO [REFERRAL IMAP://SERVER2/] S: A001 NO Specified user is invalid on this server. Try SERVER2 4.1.3 BYE at connection startup extension: untagged REFERRALS response code A referrals enabled IMAP4 server that is not willing to accept connections from a client, MAY respond with an untagged BYE response at connection startup and close the connection immediately. The untagged BYE response SHOULD contain a REFERRALS response code, if the server wishes to direct client logins and authentications to another IMAP4 server. The untagged BYE response MUST contain a REFFERALS response code that contains as an argument a single IMAP URL as defined in [IMAP-URL]. The IMAP URL SHOULD contain the home server name and optional port. Example: S: * BYE [REFERRAL IMAP://NEWSERVER/] IMAP4rev1 Server not accepting connections. Try NEWSERVER 4.2. Mailbox Referrals 4.2.1 SELECT response extension: untagged REFERRALS response code When the SELECT or EXAMINE command is issued on a remote mailbox, a referrals enabled IMAP4 server SHOULD respond with an untagged NO response and REFERRALS response code, for each referral that the server is maintaining for the selected mailbox. A final tagged NO response MUST be sent to complete the SELECT response. The REFERRALS response code MUST contain as an argument a valid URL as defined in RFC 1738[RFC-1738]. In the typical case, where the server is simply referring the client to a single remote mailbox, there will be a single untagged NO response and the REFERRALS response code will contain a single IMAP URL as defined in [IMAP-URL]. Gahrns 3 IMAP4 Referrals January, 1997 The server MAY respond with multiple untagged responses, if there is more than one replica of the mailbox. This allows the client to implement a load balancing scheme, or a failover scheme that allows access to another copy of the data if the preferred server is unavailable. 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 untagged response, with the remaining URLs presented in descending order of preference. A client that supports the REFERRALS extension SHOULD be prepared for a URL or set of URLS of any type, but it need only be able to process IMAP URLs. If the server presents a set of URLs, they MUST all be of the same URL type. Example: C: A001 SELECT PUBLIC S: * NO [REFERRAL IMAP://SERVER2/PUBLIC;TYPE3DLIST] Remote mailbox S: A001 NO Remote mailbox. Try SERVER2 C: A002 SELECT ANNOUNCEMENTS S: * NO [REFERRAL IMAP://SERVER2/ANNOUNCEMENTS;TYPE3DLIST] Remote mailbox S: * NO [REFERRAL IMAP://SERVER3/ANNOUNCEMENTS;TYPE3DLIST] Remote mailbox S: A002 NO Remote mailbox. Try SERVER2 When a client processes an IMAP URL, it SHOULD open a new IMAP4 connection to the remote server. It will be necessary for the client to log on or authenticate itself to the remote server, unless PREAUTH has been implemented. The connection to the remote server SHOULD remain open until the client issues a LOGOUT command or the inactivity autologout time out period is exceeded. Example: <IMAP4 connection to local server> C: A001 SELECT REMOTE S: * NO [REFERRAL IMAP://SERVER2/REMOTE;TYPE3DLIST] Remote mailbox S: A001 NO Remote mailbox. Try SERVER2 <Client opens second connection to remote server (SERVER2, port143)> S: * OK IMAP4rev1 server ready C: B001 LOGIN USER PASSWORD S: B001 OK LOGIN completed 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) Gahrns 4 IMAP4 Referrals January, 1997 S: * OK [PERMANENTFLAGS (\Answered \Flagged \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 C: B004 LOGOUT S: * BYE IMAP4rev1 server logging out S: B004 OK LOGOUT Completed <Client and remote server close connection> <Client continues with first connection> C: A002 SELECT PROJECT S: * NO [REFERRAL IMAP://SERVER2/PROJECT;TYPE3DLIST] Remote mailbox S: A002 NO Remote mailbox. Try SERVER2 . . . Care should be taken by the client to avoid issuing commands on the second connection that could result in ambiguity depending on whether the command was issued against the remote or local server. For example, it is recommended that the commands issued on the second connection to the remote server be kept to the minimum needed to process the items in the remote mailbox. Commands such as LIST could result in a different list of mailboxes being presented when issued against the remote server versus the local server. The SUBSCRIBE and UNSUBSCRIBE command SHOULD work the same on remote mailboxes as they do on local mailboxes. If a server chooses to expose all remote mailboxes on the local server, a client is able to manage the subscription of remote and local mailboxes on the local server. Hierarchy referrals, in which a client would be required to connect to the remote server to discover the inferiors of a mailbox are not addressed in this document. 5. Formal Syntax The following syntax specification uses the augmented Backus-Naur Form (BNF) as described in [ABNF]. connection_referral 3D "*" SPACE "BYE" SPACE <referrals_response_code> (text / text_mime2) Gahrns 5 IMAP4 Referrals January, 1997 login_auth_mailbox_referral 3D "*" SPACE "NO" SPACE <referrals_response_code> (text / text_mime2) referrals_response_code 3D "[" "REFERRAL" SPACE <url> "]" text 3D 1*text_char text_char 3D <any CHAR except CR and LF> text_mime2 3D "3D?" <charset> "?" <encoding> "?" <encoded-text? "?3D" ; <charset>, <encoding>, <encoded-text> syntax defined in [RFC-2047] url 3D <any url as defined in [rfc-1738]> 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 [IMAP-URL]. In the general case, only the remote server information is passed back to the client in the IMAP URL. No referral scenarios are envisioned that would require user and password information to be passed back in the IMAP URL. Should they arise, including passwords in the URL is discouraged unless this can be accomplished in a secure manner. In addition, the IMAP URL scheme allows a client authentication mechanism to be specified and should be used when a server supports a preferred authentication mechanism. 7. References [RFC-2060], Crispin, M., "Internet Message Access Protocol - Version 4rev1", RFC 2060, University of Washington, December 1996. [IMAP-URL], Newman, C., "IMAP URL Scheme", draft-newman-url-imap-03.txt (work in progress), Innosoft, November 1996 [RFC-1738], Berners-Lee, Masinter, McCahill, "Uniform Resource Locators (URL)", RFC 1738, CERN, Xerox Corporation, University of Minnesota, December 1994 [RFC-2047], Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part Three: Message Header Extension for Non-ASCII Text", RFC 2047, November 1996. [ABNF], DRUMS working group, Dave Crocker Editor, "Augmented BNF for Syntax Specifications: ABNF", draft-drums-abnf-01.txt (work in progress), Internet Mail Consortium, November 1996 Gahrns 6 IMAP4 Referrals January, 1997 8. Author's Address Mike Gahrns Microsoft One Microsoft Way Redmond, WA, 98072 Phone: (206) 936-9833 Email: mikega@microsoft.com Gahrns 7