rfc2193.txt (16248B)
1 2 3 4 5 6 7 Network Working Group M. Gahrns 8 Request for Comments: 2193 Microsoft 9 Category: Standards Track September 1997 10 11 12 IMAP4 Mailbox Referrals 13 14 Status of this Memo 15 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. 21 22 1. Abstract 23 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. 32 33 Mailbox referrals allow clients to seamlessly access mailboxes that 34 are distributed across several IMAP4 servers. 35 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 43 server. 44 45 2. Conventions used in this document 46 47 In examples, "C:" and "S:" indicate lines sent by the client and 48 server respectively. 49 50 A home server, is an IMAP4 server that contains the user's inbox. 51 52 A remote mailbox is a mailbox that is not hosted on the user's home 53 server. 54 55 56 57 58 Gahrns Standards Track [Page 1] 59 60 RFC 2193 IMAP4 Mailbox Referrals September 1997 61 62 63 A remote server is a server that contains remote mailboxes. 64 65 A shared mailbox, is a mailbox that multiple users have access to. 66 67 An IMAP mailbox referral is when the server directs the client to 68 another IMAP mailbox. 69 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]. 73 74 3. Introduction and Overview 75 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. 79 80 A MAILBOX-REFERRALS capable IMAP4 server MUST NOT return referrals 81 that result in a referrals loop. 82 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. 91 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. 96 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. 103 104 An IMAP mailbox referral may be given in response to an IMAP command 105 that specifies a mailbox as an argument. 106 107 108 109 110 111 112 113 114 Gahrns Standards Track [Page 2] 115 116 RFC 2193 IMAP4 Mailbox Referrals September 1997 117 118 119 Example: 120 121 A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/REMOTE]Remote Mailbox 122 123 NOTE: user;AUTH=* is specified as required by [RFC-2192] to avoid a 124 client falling back to anonymous login. 125 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. 133 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 137 server. 138 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. 144 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. 151 152 4.1. SELECT, EXAMINE, DELETE, SUBSCRIBE, UNSUBSCRIBE, STATUS and APPEND 153 Referrals 154 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. 159 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 163 mailbox. 164 165 166 167 168 169 170 Gahrns Standards Track [Page 3] 171 172 RFC 2193 IMAP4 Mailbox Referrals September 1997 173 174 175 Example: <IMAP4 connection to home server> 176 177 C: A001 DELETE "SHARED/FOO" 178 S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/FOO] 179 Remote mailbox. Try SERVER2. 180 181 <Client established a second connection to SERVER2 and 182 issues the DELETE command on the referred mailbox> 183 184 S: * OK IMAP4rev1 server ready 185 C: B001 AUTHENTICATE KERBEROS_V4 186 <authentication exchange> 187 S: B001 OK user is authenticated 188 189 C: B002 DELETE "SHARED/FOO" 190 S: B002 OK DELETE completed 191 192 Example: <IMAP4 connection to home server> 193 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. 198 199 <Client opens second connection to remote server, and 200 issues the commands needed to process the items in the 201 remote mailbox> 202 203 S: * OK IMAP4rev1 server ready 204 C: B001 AUTHENTICATE KERBEROS_V4 205 <authentication exchange> 206 S: B001 OK user is authenticated 207 208 C: B002 SELECT REMOTE 209 S: * 12 EXISTS 210 S: * 1 RECENT 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 216 217 C: B003 FETCH 10:12 RFC822 218 S: * 10 FETCH . . . 219 S: * 11 FETCH . . . 220 S: * 12 FETCH . . . 221 S: B003 OK FETCH Completed 222 223 224 225 226 Gahrns Standards Track [Page 4] 227 228 RFC 2193 IMAP4 Mailbox Referrals September 1997 229 230 231 <Client is finished processing the REMOTE mailbox and 232 wants to process a mailbox on its home server> 233 234 C: B004 LOGOUT 235 S: * BYE IMAP4rev1 server logging out 236 S: B004 OK LOGOUT Completed 237 238 <Client continues with first connection> 239 240 C: A002 SELECT INBOX 241 S: * 16 EXISTS 242 S: * 2 RECENT 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 248 249 4.2. CREATE Referrals 250 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. 256 257 Example: 258 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 262 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. 268 269 Example: 270 271 C: A001 CREATE "SHARED/FOO" 272 S: A001 OK CREATE succeeded 273 274 C: A002 SELECT "SHARED/FOO" 275 S: A002 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/FOO] 276 Remote mailbox. Try SERVER2 277 278 279 280 281 282 Gahrns Standards Track [Page 5] 283 284 RFC 2193 IMAP4 Mailbox Referrals September 1997 285 286 287 4.3. RENAME Referrals 288 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. 293 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. 299 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. 304 305 Example: 306 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 310 across servers 311 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. 315 316 Example: 317 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 321 located on SERVER2 322 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. 326 327 4.4. COPY Referrals 328 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 333 both servers. 334 335 336 337 338 Gahrns Standards Track [Page 6] 339 340 RFC 2193 IMAP4 Mailbox Referrals September 1997 341 342 343 Example: 344 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. 348 349 5.1 RLIST command 350 351 Arguments: reference name 352 mailbox name with possible wildcards 353 354 Responses: untagged responses: LIST 355 356 Result: OK - RLIST Completed 357 NO - RLIST Failure 358 BAD - command unknown or arguments invalid 359 360 The RLIST command behaves identically to its LIST counterpart, except 361 remote mailboxes are returned in addition to local mailboxes in the 362 LIST responses. 363 364 5.2 RLSUB Command 365 366 Arguments: reference name 367 mailbox name with possible wildcards 368 369 Responses: untagged responses: LSUB 370 371 Result: OK - RLSUB Completed 372 NO - RLSUB Failure 373 BAD - command unknown or arguments invalid 374 375 The RLSUB command behaves identically to its LSUB counterpart, except 376 remote mailboxes are returned in addition to local mailboxes in the 377 LSUB responses. 378 379 6. Formal Syntax 380 381 The following syntax specification uses the augmented Backus-Naur 382 Form (BNF) as described in [ABNF]. 383 384 list_mailbox = <list_mailbox> as defined in [RFC-2060] 385 386 mailbox = <mailbox> as defined in [RFC-2060] 387 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 391 392 393 394 Gahrns Standards Track [Page 7] 395 396 RFC 2193 IMAP4 Mailbox Referrals September 1997 397 398 399 referral_response_code = "[" "REFERRAL" 1*(SPACE <url>) "]" 400 ; See [RFC-1738] for <url> definition 401 402 rlist = "RLIST" SPACE mailbox SPACE list_mailbox 403 404 rlsub = "RLSUB" SPACE mailbox SPACE list_mailbox 405 406 6. Security Considerations 407 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]. 411 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. 417 418 7. References 419 420 [RFC-2060], Crispin, M., "Internet Message Access Protocol - Version 421 4rev1", RFC 2060, University of Washington, December 1996. 422 423 [RFC-2192], Newman, C., "IMAP URL Scheme", RFC 2192, Innosoft, 424 September 1997. 425 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. 429 430 [RFC-2119], Bradner, S., "Key words for use in RFCs to Indicate 431 Requirement Levels", RFC 2119, Harvard University, March 1997. 432 433 [ABNF], DRUMS working group, Dave Crocker Editor, "Augmented BNF for 434 Syntax Specifications: ABNF", Work in Progress, Internet Mail 435 Consortium, April 1997. 436 437 8. Acknowledgments 438 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. 443 444 445 446 447 448 449 450 Gahrns Standards Track [Page 8] 451 452 RFC 2193 IMAP4 Mailbox Referrals September 1997 453 454 455 9. Author's Address 456 457 Mike Gahrns 458 Microsoft 459 One Microsoft Way 460 Redmond, WA, 98072 461 462 Phone: (206) 936-9833 463 EMail: mikega@microsoft.com 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 Gahrns Standards Track [Page 9] 507