7
Network Working Group M. Gahrns
8
Request for Comments: 2193 Microsoft
9
Category: Standards Track September 1997
12
IMAP4 Mailbox Referrals
16
This document specifies an Internet standards track protocol for the
17
Internet community, and requests discussion and suggestions for
18
improvements. Please refer to the current edition of the "Internet
19
Official Protocol Standards" (STD 1) for the standardization state
20
and status of this protocol. Distribution of this memo is unlimited.
24
When dealing with large amounts of users, messages and geographically
25
dispersed IMAP4 [RFC-2060] servers, it is often desirable to
26
distribute messages amongst different servers within an organization.
27
For example an administrator may choose to store user's personal
28
mailboxes on a local IMAP4 server, while storing shared mailboxes
29
remotely on another server. This type of configuration is common
30
when it is uneconomical to store all data centrally due to limited
31
bandwidth or disk resources.
33
Mailbox referrals allow clients to seamlessly access mailboxes that
34
are distributed across several IMAP4 servers.
36
A referral mechanism can provide efficiencies over the alternative
37
"proxy method", in which the local IMAP4 server contacts the remote
38
server on behalf of the client, and then transfers the data from the
39
remote server to itself, and then on to the client. The referral
40
mechanism's direct client connection to the remote server is often a
41
more efficient use of bandwidth, and does not require the local
42
server to impersonate the client when authenticating to the remote
45
2. Conventions used in this document
47
In examples, "C:" and "S:" indicate lines sent by the client and
50
A home server, is an IMAP4 server that contains the user's inbox.
52
A remote mailbox is a mailbox that is not hosted on the user's home
58
Gahrns Standards Track [Page 1]
60
RFC 2193 IMAP4 Mailbox Referrals September 1997
63
A remote server is a server that contains remote mailboxes.
65
A shared mailbox, is a mailbox that multiple users have access to.
67
An IMAP mailbox referral is when the server directs the client to
70
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
71
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
72
document are to be interpreted as described in [RFC-2119].
74
3. Introduction and Overview
76
IMAP4 servers that support this extension MUST list the keyword
77
MAILBOX-REFERRALS in their CAPABILITY response. No client action is
78
needed to invoke the MAILBOX-REFERRALS capability in a server.
80
A MAILBOX-REFERRALS capable IMAP4 server MUST NOT return referrals
81
that result in a referrals loop.
83
A referral response consists of a tagged NO response and a REFERRAL
84
response code. The REFERRAL response code MUST contain as an
85
argument a one or more valid URLs separated by a space as defined in
86
[RFC-1738]. If a server replies with multiple URLs for a particular
87
object, they MUST all be of the same type. In this case, the URL MUST
88
be an IMAP URL as defined in [RFC-2192]. A client that supports the
89
REFERRALS extension MUST be prepared for a URL of any type, but it
90
need only be able to process IMAP URLs.
92
A server MAY respond with multiple IMAP mailbox referrals if there is
93
more than one replica of the mailbox. This allows the implementation
94
of a load balancing or failover scheme. How a server keeps multiple
95
replicas of a mailbox in sync is not addressed by this document.
97
If the server has a preferred order in which the client should
98
attempt to access the URLs, the preferred URL SHOULD be listed in the
99
first, with the remaining URLs presented in descending order of
100
preference. If multiple referrals are given for a mailbox, a server
101
should be aware that there are synchronization issues for a client if
102
the UIDVALIDITY of the referred mailboxes are different.
104
An IMAP mailbox referral may be given in response to an IMAP command
105
that specifies a mailbox as an argument.
114
Gahrns Standards Track [Page 2]
116
RFC 2193 IMAP4 Mailbox Referrals September 1997
121
A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/REMOTE]Remote Mailbox
123
NOTE: user;AUTH=* is specified as required by [RFC-2192] to avoid a
124
client falling back to anonymous login.
126
Remote mailboxes and their inferiors, that are accessible only via
127
referrals SHOULD NOT appear in LIST and LSUB responses issued against
128
the user's home server. They MUST appear in RLIST and RLSUB
129
responses issued against the user's home server. Hierarchy referrals,
130
in which a client would be required to connect to the remote server
131
to issue a LIST to discover the inferiors of a mailbox are not
132
addressed in this document.
134
For example, if shared mailboxes were only accessible via referrals
135
on a remote server, a RLIST "" "#SHARED/%" command would return the
136
same response if issued against the user's home server or the remote
139
Note: Mailboxes that are available on the user's home server do not
140
need to be available on the remote server. In addition, there may be
141
additional mailboxes available on the remote server, but they will
142
not accessible to the client via referrals unless they appear in the
143
LIST response to the RLIST command against the user's home server.
145
A MAILBOX-REFERRALS capable client will issue the RLIST and RLSUB
146
commands in lieu of LIST and LSUB. The RLIST and RLSUB commands
147
behave identically to their LIST and LSUB counterparts, except remote
148
mailboxes are returned in addition to local mailboxes in the LIST and
149
LSUB responses. This avoids displaying to a non MAILBOX-REFERRALS
150
enabled client inaccessible remote mailboxes.
152
4.1. SELECT, EXAMINE, DELETE, SUBSCRIBE, UNSUBSCRIBE, STATUS and APPEND
155
An IMAP4 server MAY respond to the SELECT, EXAMINE, DELETE,
156
SUBSCRIBE, UNSUBSCRIBE, STATUS or APPEND command with one or more
157
IMAP mailbox referrals to indicate to the client that the mailbox is
158
hosted on a remote server.
160
When a client processes an IMAP mailbox referral, it will open a new
161
connection or use an existing connection to the remote server so that
162
it is able to issue the commands necessary to process the remote
170
Gahrns Standards Track [Page 3]
172
RFC 2193 IMAP4 Mailbox Referrals September 1997
175
Example: <IMAP4 connection to home server>
177
C: A001 DELETE "SHARED/FOO"
178
S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/FOO]
179
Remote mailbox. Try SERVER2.
181
<Client established a second connection to SERVER2 and
182
issues the DELETE command on the referred mailbox>
184
S: * OK IMAP4rev1 server ready
185
C: B001 AUTHENTICATE KERBEROS_V4
186
<authentication exchange>
187
S: B001 OK user is authenticated
189
C: B002 DELETE "SHARED/FOO"
190
S: B002 OK DELETE completed
192
Example: <IMAP4 connection to home server>
194
C: A001 SELECT REMOTE
195
S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/REMOTE
196
IMAP://user;AUTH=*@SERVER3/REMOTE] Remote mailbox.
197
Try SERVER2 or SERVER3.
199
<Client opens second connection to remote server, and
200
issues the commands needed to process the items in the
203
S: * OK IMAP4rev1 server ready
204
C: B001 AUTHENTICATE KERBEROS_V4
205
<authentication exchange>
206
S: B001 OK user is authenticated
208
C: B002 SELECT REMOTE
211
S: * OK [UNSEEN 10] Message 10 is first unseen
212
S: * OK [UIDVALIDITY 123456789]
213
S: * FLAGS (Answered Flagged Deleted Seen Draft)
214
S: * OK [PERMANENTFLAGS (Answered Deleted Seen ]
215
S: B002 OK [READ-WRITE] Selected completed
217
C: B003 FETCH 10:12 RFC822
221
S: B003 OK FETCH Completed
226
Gahrns Standards Track [Page 4]
228
RFC 2193 IMAP4 Mailbox Referrals September 1997
231
<Client is finished processing the REMOTE mailbox and
232
wants to process a mailbox on its home server>
235
S: * BYE IMAP4rev1 server logging out
236
S: B004 OK LOGOUT Completed
238
<Client continues with first connection>
243
S: * OK [UNSEEN 10] Message 10 is first unseen
244
S: * OK [UIDVALIDITY 123456789]
245
S: * FLAGS (Answered Flagged Deleted Seen Draft)
246
S: * OK [PERMANENTFLAGS (Answered Deleted Seen ]
247
S: A002 OK [READ-WRITE] Selected completed
249
4.2. CREATE Referrals
251
An IMAP4 server MAY respond to the CREATE command with one or more
252
IMAP mailbox referrals, if it wishes to direct the client to issue
253
the CREATE against another server. The server can employ any means,
254
such as examining the hierarchy of the specified mailbox name, in
255
determining which server the mailbox should be created on.
259
C: A001 CREATE "SHARED/FOO"
260
S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/FOO]
261
Mailbox should be created on remote server
263
Alternatively, because a home server is required to maintain a
264
listing of referred remote mailboxes, a server MAY allow the creation
265
of a mailbox that will ultimately reside on a remote server against
266
the home server, and provide referrals on subsequent commands that
267
manipulate the mailbox.
271
C: A001 CREATE "SHARED/FOO"
272
S: A001 OK CREATE succeeded
274
C: A002 SELECT "SHARED/FOO"
275
S: A002 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/FOO]
276
Remote mailbox. Try SERVER2
282
Gahrns Standards Track [Page 5]
284
RFC 2193 IMAP4 Mailbox Referrals September 1997
287
4.3. RENAME Referrals
289
An IMAP4 server MAY respond to the RENAME command with one or more
290
pairs of IMAP mailbox referrals. In each pair of IMAP mailbox
291
referrals, the first one is an URL to the existing mailbox name and
292
the second is an URL to the requested new mailbox name.
294
If within an IMAP mailbox referral pair, the existing and new mailbox
295
URLs are on different servers, the remote servers are unable to
296
perform the RENAME operation. To achieve the same behavior of
297
server RENAME, the client MAY issue the constituent CREATE, FETCH,
298
APPEND, and DELETE commands against both servers.
300
If within an IMAP mailbox referral pair, the existing and new mailbox
301
URLs are on the same server it is an indication that the currently
302
connected server is unable to perform the operation. The client can
303
simply re-issue the RENAME command on the remote server.
307
C: A001 RENAME FOO BAR
308
S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER1/FOO
309
IMAP://user;AUTH=*@SERVER2/BAR] Unable to rename mailbox
312
Since the existing and new mailbox names are on different servers,
313
the client would be required to make a connection to both servers and
314
issue the constituent commands require to achieve the RENAME.
318
C: A001 RENAME FOO BAR
319
S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/FOO
320
IMAP://user;AUTH=*@SERVER2/BAR] Unable to rename mailbox
323
Since both the existing and new mailbox are on the same remote
324
server, the client can simply make a connection to the remote server
325
and re-issue the RENAME command.
329
An IMAP4 server MAY respond to the COPY command with one or more IMAP
330
mailbox referrals. This indicates that the destination mailbox is on
331
a remote server. To achieve the same behavior of a server COPY, the
332
client MAY issue the constituent FETCH and APPEND commands against
338
Gahrns Standards Track [Page 6]
340
RFC 2193 IMAP4 Mailbox Referrals September 1997
345
C: A001 COPY 1 "SHARED/STUFF"
346
S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/STUFF]
347
Unable to copy message(s) to SERVER2.
351
Arguments: reference name
352
mailbox name with possible wildcards
354
Responses: untagged responses: LIST
356
Result: OK - RLIST Completed
358
BAD - command unknown or arguments invalid
360
The RLIST command behaves identically to its LIST counterpart, except
361
remote mailboxes are returned in addition to local mailboxes in the
366
Arguments: reference name
367
mailbox name with possible wildcards
369
Responses: untagged responses: LSUB
371
Result: OK - RLSUB Completed
373
BAD - command unknown or arguments invalid
375
The RLSUB command behaves identically to its LSUB counterpart, except
376
remote mailboxes are returned in addition to local mailboxes in the
381
The following syntax specification uses the augmented Backus-Naur
382
Form (BNF) as described in [ABNF].
384
list_mailbox = <list_mailbox> as defined in [RFC-2060]
386
mailbox = <mailbox> as defined in [RFC-2060]
388
mailbox_referral = <tag> SPACE "NO" SPACE
389
<referral_response_code> (text / text_mime2)
390
; See [RFC-2060] for <tag>, text and text_mime2 definition
394
Gahrns Standards Track [Page 7]
396
RFC 2193 IMAP4 Mailbox Referrals September 1997
399
referral_response_code = "[" "REFERRAL" 1*(SPACE <url>) "]"
400
; See [RFC-1738] for <url> definition
402
rlist = "RLIST" SPACE mailbox SPACE list_mailbox
404
rlsub = "RLSUB" SPACE mailbox SPACE list_mailbox
406
6. Security Considerations
408
The IMAP4 referral mechanism makes use of IMAP URLs, and as such,
409
have the same security considerations as general internet URLs [RFC-
410
1738], and in particular IMAP URLs [RFC-2192].
412
With the MAILBOX-REFERRALS capability, it is potentially easier to
413
write a rogue server that injects a bogus referral response that
414
directs a user to an incorrect mailbox. Although referrals reduce
415
the effort to write such a server, the referral response makes
416
detection of the intrusion easier.
420
[RFC-2060], Crispin, M., "Internet Message Access Protocol - Version
421
4rev1", RFC 2060, University of Washington, December 1996.
423
[RFC-2192], Newman, C., "IMAP URL Scheme", RFC 2192, Innosoft,
426
[RFC-1738], Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform
427
Resource Locators (URL)", RFC 1738, CERN, Xerox Corporation,
428
University of Minnesota, December 1994.
430
[RFC-2119], Bradner, S., "Key words for use in RFCs to Indicate
431
Requirement Levels", RFC 2119, Harvard University, March 1997.
433
[ABNF], DRUMS working group, Dave Crocker Editor, "Augmented BNF for
434
Syntax Specifications: ABNF", Work in Progress, Internet Mail
435
Consortium, April 1997.
439
Many valuable suggestions were received from private discussions and
440
the IMAP4 mailing list. In particular, Raymond Cheng, Mark Crispin,
441
Mark Keasling, Chris Newman and Larry Osterman made significant
442
contributions to this document.
450
Gahrns Standards Track [Page 8]
452
RFC 2193 IMAP4 Mailbox Referrals September 1997
462
Phone: (206) 936-9833
463
EMail: mikega@microsoft.com
506
Gahrns Standards Track [Page 9]
added
removed
imap/docs/rfc/rfc2193.txt
