Network Working Group M. Gahrns Internet Draft Microsoft Document: draft-gahrns-imap-referrals-01.txt February 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 September 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 is often desirable to distribute messages and users 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. By examining the REFERRALS response code in response to a SELECT command, a client can seamlessly access mailboxes distributed across several IMAP4 servers. Additionally, users may be frequently moved from one IMAP4 server to another because of hardware failures or organizational changes. By examining the REFERRAL response code at connection startup or in response to a LOGIN or AUTHENTICATE command, an IMAP4 client can transparently connect to an alternate IMAP4 server. Gahrns 1 IMAP4 Referrals February 1997 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 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 this extension MUST list the keyword REFERRALS in their CAPABILITY response. No client action is needed to invoke the REFERRALS capability. Referrals are returned as untagged NO or BYE responses with a REFFERALS response code that IMAP4 compliant clients must be prepared to accept at all times. 4. Responses A REFERRALS capable IMAP4 server MUST NOT return REFERRAL responses that result in a referrals loop. 4.1. Mailbox Referral: SELECT response extension When the SELECT or EXAMINE command is issued on a remote mailbox, a REFERRALS capable IMAP4 server SHOULD respond with an untagged NO response and REFERRAL 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. Gahrns 2 IMAP4 Referrals February 1997 The REFERRAL response code MUST contain as an argument a valid URL as defined in RFC 1738[RFC-1738]. In the typical case, in which the server is referring the client to a single remote mailbox, there should be a single untagged NO response, with the REFERRAL response code containing an IMAP URL as defined in [IMAP-URL]. The server MAY respond with multiple untagged responses if there is more than one replica of the mailbox. This allows the implementation of a load balancing or failover scheme. 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] Remote mailbox S: A001 NO Remote mailbox. Try SERVER2 C: A002 SELECT FOO S: * NO [REFERRAL IMAP://SERVER2/FOO] Remote mailbox S: * NO [REFERRAL IMAP://SERVER3/FOO] Remote mailbox S: A002 NO Remote mailbox. Try SERVER2 When a client processes an IMAP URL, it MUST open a new IMAP4 connection to the remote server. It will be necessary for the client to log on or authenticate 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. The client MAY choose to keep the original connection open, or it MAY close it after successfully connecting to the remote server. Example: <IMAP4 connection to local server> C: A001 SELECT REMOTE S: * NO [REFERRAL IMAP://SERVER2/REMOTE] Remote mailbox S: A001 NO Remote mailbox. Try SERVER2 <Client opens second connection to remote server> S: * OK IMAP4rev1 server ready C: B001 LOGIN USER PASSWORD S: B001 OK LOGIN completed C: B002 SELECT REMOTE Gahrns 3 IMAP4 Referrals February 1997 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 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] 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, a client may choose to issue only the minimum number of commands on the second connection that are 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. 4.2. Home Server Referral: LOGIN response extension A REFERRALS capable IMAP4 server SHOULD respond to a LOGIN command with an untagged NO response, if it wishes to direct the user to Gahrns 4 IMAP4 Referrals February 1997 another IMAP4 server. The untagged NO response MUST contain a REFFERAL 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 4.3. Home Server Referral: AUTHENTICATE response extension A REFERRALS capable IMAP4 server SHOULD respond to an AUTHENTICATE command with an untagged NO response, if it wishes to direct the user to another IMAP4 server. The untagged NO response MUST contain a REFFERAL 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.4. Home Server Referral: BYE at connection startup extension A REFERRALS capable IMAP4 server that is not willing to accept connections from a client, MAY respond with an untagged BYE response and REFERRAL response code at connection startup and immediately close the connection. The untagged BYE response SHOULD contain a REFERRAL response code, if the server wishes to direct the client to another IMAP4 server. The untagged BYE response MUST contain a REFFERAL 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://SERVER2/] IMAP4rev1 Server not accepting connections. Try SERVER2 5. Formal Syntax Gahrns 5 IMAP4 Referrals February 1997 The following syntax specification uses the augmented Backus-Naur Form (BNF) as described in [ABNF]. connection_referral = "*" SPACE "BYE" SPACE <referral_response_code> (text / text_mime2) login_auth_mailbox_referral = "*" SPACE "NO" SPACE <referral_response_code> (text / text_mime2) referral_response_code = "[" "REFERRAL" SPACE <url> "]" text = 1*text_char text_char = <any CHAR except CR and LF> text_mime2 = "=?" <charset> "?" <encoding> "?" <encoded-text? "?=" ; <charset>, <encoding>, <encoded-text> syntax as ; defined in [RFC-2047] url = <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. With the 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. Also made easier, is the ability for a rogue server to inject 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. Gahrns 6 IMAP4 Referrals February 1997 [IMAP-URL], Newman, C., "IMAP URL Scheme", draft-newman-url-imap- 05.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 8. Acknowledgments Many valuable suggestions were received from private discussions and the IMAP4 mailing list. In particular, Raymond Cheng, Mark Crispin, Mark Keasling 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.co m Gahrns 7