1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/rfc/rfc2193.txt	Mon Sep 14 15:17:45 2009 +0900
     1.3 @@ -0,0 +1,507 @@
     1.4 +
     1.5 +
     1.6 +
     1.7 +
     1.8 +
     1.9 +
    1.10 +Network Working Group                                        M. Gahrns
    1.11 +Request for Comments: 2193                                   Microsoft
    1.12 +Category: Standards Track                               September 1997
    1.13 +
    1.14 +
    1.15 +                        IMAP4 Mailbox Referrals
    1.16 +
    1.17 +Status of this Memo
    1.18 +
    1.19 +   This document specifies an Internet standards track protocol for the
    1.20 +   Internet community, and requests discussion and suggestions for
    1.21 +   improvements.  Please refer to the current edition of the "Internet
    1.22 +   Official Protocol Standards" (STD 1) for the standardization state
    1.23 +   and status of this protocol.  Distribution of this memo is unlimited.
    1.24 +
    1.25 +1. Abstract
    1.26 +
    1.27 +   When dealing with large amounts of users, messages and geographically
    1.28 +   dispersed IMAP4 [RFC-2060] servers, it is often desirable to
    1.29 +   distribute messages amongst different servers within an organization.
    1.30 +   For example an administrator may choose to store user's personal
    1.31 +   mailboxes on a local IMAP4 server, while storing shared mailboxes
    1.32 +   remotely on another server.  This type of configuration is common
    1.33 +   when it is uneconomical to store all data centrally due to limited
    1.34 +   bandwidth or disk resources.
    1.35 +
    1.36 +   Mailbox referrals allow clients to seamlessly access mailboxes that
    1.37 +   are distributed across several IMAP4 servers.
    1.38 +
    1.39 +   A referral mechanism can provide efficiencies over the alternative
    1.40 +   "proxy method", in which the local IMAP4 server contacts the remote
    1.41 +   server on behalf of the client, and then transfers the data from the
    1.42 +   remote server to itself, and then on to the client.  The referral
    1.43 +   mechanism's direct client connection to the remote server is often a
    1.44 +   more efficient use of bandwidth, and does not require the local
    1.45 +   server to impersonate the client when authenticating to the remote
    1.46 +   server.
    1.47 +
    1.48 +2. Conventions used in this document
    1.49 +
    1.50 +   In examples, "C:" and "S:" indicate lines sent by the client and
    1.51 +   server respectively.
    1.52 +
    1.53 +   A home server, is an IMAP4 server that contains the user's inbox.
    1.54 +
    1.55 +   A remote mailbox is a mailbox that is not hosted on the user's home
    1.56 +   server.
    1.57 +
    1.58 +
    1.59 +
    1.60 +
    1.61 +Gahrns                      Standards Track                     [Page 1]
    1.62 +
    1.63 +RFC 2193                IMAP4 Mailbox Referrals           September 1997
    1.64 +
    1.65 +
    1.66 +   A remote server is a server that contains remote mailboxes.
    1.67 +
    1.68 +   A shared mailbox, is a mailbox that multiple users have access to.
    1.69 +
    1.70 +   An IMAP mailbox referral is when the server directs the client to
    1.71 +   another IMAP mailbox.
    1.72 +
    1.73 +   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
    1.74 +   "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this
    1.75 +   document are to be interpreted as described in [RFC-2119].
    1.76 +
    1.77 +3. Introduction and Overview
    1.78 +
    1.79 +   IMAP4 servers that support this extension MUST list the keyword
    1.80 +   MAILBOX-REFERRALS in their CAPABILITY response.  No client action is
    1.81 +   needed to invoke the MAILBOX-REFERRALS capability in a server.
    1.82 +
    1.83 +   A MAILBOX-REFERRALS capable IMAP4 server MUST NOT return referrals
    1.84 +   that result in a referrals loop.
    1.85 +
    1.86 +   A referral response consists of a tagged NO response and a REFERRAL
    1.87 +   response code.  The REFERRAL response code MUST contain as an
    1.88 +   argument a one or more valid URLs separated by a space as defined in
    1.89 +   [RFC-1738]. If a server replies with multiple URLs for a particular
    1.90 +   object, they MUST all be of the same type. In this case, the URL MUST
    1.91 +   be an IMAP URL as defined in [RFC-2192].  A client that supports the
    1.92 +   REFERRALS extension MUST be prepared for a URL of any type, but it
    1.93 +   need only be able to process IMAP URLs.
    1.94 +
    1.95 +   A server MAY respond with multiple IMAP mailbox referrals if there is
    1.96 +   more than one replica of the mailbox.  This allows the implementation
    1.97 +   of a load balancing or failover scheme. How a server keeps multiple
    1.98 +   replicas of a mailbox in sync is not addressed by this document.
    1.99 +
   1.100 +   If the server has a preferred order in which the client should
   1.101 +   attempt to access the URLs, the preferred URL SHOULD be listed in the
   1.102 +   first, with the remaining URLs presented in descending order of
   1.103 +   preference.  If multiple referrals are given for a mailbox, a server
   1.104 +   should be aware that there are synchronization issues for a client if
   1.105 +   the UIDVALIDITY of the referred mailboxes are different.
   1.106 +
   1.107 +   An IMAP mailbox referral may be given in response to an IMAP command
   1.108 +   that specifies a mailbox as an argument.
   1.109 +
   1.110 +
   1.111 +
   1.112 +
   1.113 +
   1.114 +
   1.115 +
   1.116 +
   1.117 +Gahrns                      Standards Track                     [Page 2]
   1.118 +
   1.119 +RFC 2193                IMAP4 Mailbox Referrals           September 1997
   1.120 +
   1.121 +
   1.122 +   Example:
   1.123 +
   1.124 +      A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/REMOTE]Remote Mailbox
   1.125 +
   1.126 +   NOTE: user;AUTH=* is specified as required by [RFC-2192] to avoid a
   1.127 +   client falling back to anonymous login.
   1.128 +
   1.129 +   Remote mailboxes and their inferiors, that are accessible only via
   1.130 +   referrals SHOULD NOT appear in LIST and LSUB responses issued against
   1.131 +   the user's home server.  They MUST appear in RLIST and RLSUB
   1.132 +   responses issued against the user's home server. Hierarchy referrals,
   1.133 +   in which a client would be required to connect to the remote server
   1.134 +   to issue a LIST to discover the inferiors of a mailbox are not
   1.135 +   addressed in this document.
   1.136 +
   1.137 +   For example, if shared mailboxes were only accessible via referrals
   1.138 +   on a remote server, a RLIST "" "#SHARED/%" command would return the
   1.139 +   same response if issued against the user's home server or the remote
   1.140 +   server.
   1.141 +
   1.142 +   Note: Mailboxes that are available on the user's home server do not
   1.143 +   need to be available on the remote server.  In addition, there may be
   1.144 +   additional mailboxes available on the remote server, but they will
   1.145 +   not accessible to the client via referrals unless they appear in the
   1.146 +   LIST response to the RLIST command against the user's home server.
   1.147 +
   1.148 +   A MAILBOX-REFERRALS capable client will issue the RLIST and RLSUB
   1.149 +   commands in lieu of LIST and LSUB.  The RLIST and RLSUB commands
   1.150 +   behave identically to their LIST and LSUB counterparts, except remote
   1.151 +   mailboxes are returned in addition to local mailboxes in the LIST and
   1.152 +   LSUB responses.  This avoids displaying to a non MAILBOX-REFERRALS
   1.153 +   enabled client inaccessible remote mailboxes.
   1.154 +
   1.155 +4.1. SELECT, EXAMINE, DELETE, SUBSCRIBE, UNSUBSCRIBE, STATUS and APPEND
   1.156 +     Referrals
   1.157 +
   1.158 +   An IMAP4 server MAY respond to the SELECT, EXAMINE, DELETE,
   1.159 +   SUBSCRIBE, UNSUBSCRIBE, STATUS or APPEND command with one or more
   1.160 +   IMAP mailbox referrals to indicate to the client that the mailbox is
   1.161 +   hosted on a remote server.
   1.162 +
   1.163 +   When a client processes an IMAP mailbox referral, it will open a new
   1.164 +   connection or use an existing connection to the remote server so that
   1.165 +   it is able to issue the commands necessary to process the remote
   1.166 +   mailbox.
   1.167 +
   1.168 +
   1.169 +
   1.170 +
   1.171 +
   1.172 +
   1.173 +Gahrns                      Standards Track                     [Page 3]
   1.174 +
   1.175 +RFC 2193                IMAP4 Mailbox Referrals           September 1997
   1.176 +
   1.177 +
   1.178 +   Example:  <IMAP4 connection to home server>
   1.179 +
   1.180 +      C: A001 DELETE "SHARED/FOO"
   1.181 +      S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/FOO]
   1.182 +             Remote mailbox. Try SERVER2.
   1.183 +
   1.184 +      <Client established a second connection to SERVER2 and
   1.185 +      issues the DELETE command on the referred mailbox>
   1.186 +
   1.187 +      S: * OK IMAP4rev1 server ready
   1.188 +      C: B001 AUTHENTICATE KERBEROS_V4
   1.189 +      <authentication exchange>
   1.190 +      S: B001 OK user is authenticated
   1.191 +
   1.192 +      C: B002 DELETE "SHARED/FOO"
   1.193 +      S: B002 OK DELETE completed
   1.194 +
   1.195 +   Example:  <IMAP4 connection to home server>
   1.196 +
   1.197 +      C: A001 SELECT REMOTE
   1.198 +      S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/REMOTE
   1.199 +          IMAP://user;AUTH=*@SERVER3/REMOTE] Remote mailbox.
   1.200 +          Try SERVER2 or SERVER3.
   1.201 +
   1.202 +      <Client opens second connection to remote server, and
   1.203 +       issues the commands needed to process the items in the
   1.204 +       remote mailbox>
   1.205 +
   1.206 +      S: * OK IMAP4rev1 server ready
   1.207 +      C: B001 AUTHENTICATE KERBEROS_V4
   1.208 +      <authentication exchange>
   1.209 +      S: B001 OK user is authenticated
   1.210 +
   1.211 +      C: B002 SELECT REMOTE
   1.212 +      S: * 12 EXISTS
   1.213 +      S: * 1 RECENT
   1.214 +      S: * OK [UNSEEN 10] Message 10 is first unseen
   1.215 +      S: * OK [UIDVALIDITY 123456789]
   1.216 +      S: * FLAGS (Answered Flagged Deleted Seen Draft)
   1.217 +      S: * OK [PERMANENTFLAGS (Answered Deleted Seen ]
   1.218 +      S: B002 OK [READ-WRITE] Selected completed
   1.219 +
   1.220 +      C: B003 FETCH 10:12 RFC822
   1.221 +      S: * 10 FETCH . . .
   1.222 +      S: * 11 FETCH . . .
   1.223 +      S: * 12 FETCH . . .
   1.224 +      S: B003 OK FETCH Completed
   1.225 +
   1.226 +
   1.227 +
   1.228 +
   1.229 +Gahrns                      Standards Track                     [Page 4]
   1.230 +
   1.231 +RFC 2193                IMAP4 Mailbox Referrals           September 1997
   1.232 +
   1.233 +
   1.234 +      <Client is finished processing the REMOTE mailbox and
   1.235 +       wants to process a mailbox on its home server>
   1.236 +
   1.237 +      C: B004 LOGOUT
   1.238 +      S: * BYE IMAP4rev1 server logging out
   1.239 +      S: B004 OK LOGOUT Completed
   1.240 +
   1.241 +      <Client continues with first connection>
   1.242 +
   1.243 +      C: A002 SELECT INBOX
   1.244 +      S: * 16 EXISTS
   1.245 +      S: * 2 RECENT
   1.246 +      S: * OK [UNSEEN 10] Message 10 is first unseen
   1.247 +      S: * OK [UIDVALIDITY 123456789]
   1.248 +      S: * FLAGS (Answered Flagged Deleted Seen Draft)
   1.249 +      S: * OK [PERMANENTFLAGS (Answered Deleted Seen ]
   1.250 +      S: A002 OK [READ-WRITE] Selected completed
   1.251 +
   1.252 +4.2. CREATE Referrals
   1.253 +
   1.254 +   An IMAP4 server MAY respond to the CREATE command with one or more
   1.255 +   IMAP mailbox referrals, if it wishes to direct the client to issue
   1.256 +   the CREATE against another server.  The server can employ any means,
   1.257 +   such as examining the hierarchy of the specified mailbox name, in
   1.258 +   determining which server the mailbox should be created on.
   1.259 +
   1.260 +   Example:
   1.261 +
   1.262 +      C: A001 CREATE "SHARED/FOO"
   1.263 +      S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/FOO]
   1.264 +         Mailbox should be created on remote server
   1.265 +
   1.266 +   Alternatively, because a home server is required to maintain a
   1.267 +   listing of referred remote mailboxes, a server MAY allow the creation
   1.268 +   of a mailbox that will ultimately reside on a remote server against
   1.269 +   the home server, and provide referrals on subsequent commands that
   1.270 +   manipulate the mailbox.
   1.271 +
   1.272 +   Example:
   1.273 +
   1.274 +      C: A001 CREATE "SHARED/FOO"
   1.275 +      S: A001 OK CREATE succeeded
   1.276 +
   1.277 +      C: A002 SELECT "SHARED/FOO"
   1.278 +      S: A002 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/FOO]
   1.279 +         Remote mailbox.  Try SERVER2
   1.280 +
   1.281 +
   1.282 +
   1.283 +
   1.284 +
   1.285 +Gahrns                      Standards Track                     [Page 5]
   1.286 +
   1.287 +RFC 2193                IMAP4 Mailbox Referrals           September 1997
   1.288 +
   1.289 +
   1.290 +4.3. RENAME Referrals
   1.291 +
   1.292 +   An IMAP4 server MAY respond to the RENAME command with one or more
   1.293 +   pairs of IMAP mailbox referrals.  In each pair of IMAP mailbox
   1.294 +   referrals, the first one is an URL to the existing mailbox name and
   1.295 +   the second is an URL to the requested new mailbox name.
   1.296 +
   1.297 +   If within an IMAP mailbox referral pair, the existing and new mailbox
   1.298 +   URLs are on different servers, the remote servers are unable to
   1.299 +   perform the RENAME operation.   To achieve the same behavior of
   1.300 +   server RENAME, the client MAY issue the constituent CREATE, FETCH,
   1.301 +   APPEND, and DELETE commands against both servers.
   1.302 +
   1.303 +   If within an IMAP mailbox referral pair, the existing and new mailbox
   1.304 +   URLs are on the same server it is an indication that the currently
   1.305 +   connected server is unable to perform the operation.  The client can
   1.306 +   simply re-issue the RENAME command on the remote server.
   1.307 +
   1.308 +   Example:
   1.309 +
   1.310 +      C: A001 RENAME FOO BAR
   1.311 +      S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER1/FOO
   1.312 +              IMAP://user;AUTH=*@SERVER2/BAR] Unable to rename mailbox
   1.313 +              across servers
   1.314 +
   1.315 +   Since the existing and new mailbox names are on different servers,
   1.316 +   the client would be required to make a connection to both servers and
   1.317 +   issue the constituent commands require to achieve the RENAME.
   1.318 +
   1.319 +   Example:
   1.320 +
   1.321 +      C: A001 RENAME FOO BAR
   1.322 +      S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/FOO
   1.323 +              IMAP://user;AUTH=*@SERVER2/BAR] Unable to rename mailbox
   1.324 +              located on SERVER2
   1.325 +
   1.326 +   Since both the existing and new mailbox are on the same remote
   1.327 +   server, the client can simply make a connection to the remote server
   1.328 +   and re-issue the RENAME command.
   1.329 +
   1.330 +4.4. COPY Referrals
   1.331 +
   1.332 +   An IMAP4 server MAY respond to the COPY command with one or more IMAP
   1.333 +   mailbox referrals.  This indicates that the destination mailbox is on
   1.334 +   a remote server.  To achieve the same behavior of a server COPY, the
   1.335 +   client MAY issue the constituent FETCH and APPEND commands against
   1.336 +   both servers.
   1.337 +
   1.338 +
   1.339 +
   1.340 +
   1.341 +Gahrns                      Standards Track                     [Page 6]
   1.342 +
   1.343 +RFC 2193                IMAP4 Mailbox Referrals           September 1997
   1.344 +
   1.345 +
   1.346 +   Example:
   1.347 +
   1.348 +      C: A001 COPY 1 "SHARED/STUFF"
   1.349 +      S: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/SHARED/STUFF]
   1.350 +              Unable to copy message(s) to SERVER2.
   1.351 +
   1.352 +5.1 RLIST command
   1.353 +
   1.354 +   Arguments:  reference name
   1.355 +               mailbox name with possible wildcards
   1.356 +
   1.357 +   Responses:  untagged responses: LIST
   1.358 +
   1.359 +   Result:     OK - RLIST Completed
   1.360 +               NO - RLIST Failure
   1.361 +               BAD - command unknown or arguments invalid
   1.362 +
   1.363 +   The RLIST command behaves identically to its LIST counterpart, except
   1.364 +   remote mailboxes are returned in addition to local mailboxes in the
   1.365 +   LIST responses.
   1.366 +
   1.367 +5.2 RLSUB Command
   1.368 +
   1.369 +   Arguments:  reference name
   1.370 +               mailbox name with possible wildcards
   1.371 +
   1.372 +   Responses:  untagged responses: LSUB
   1.373 +
   1.374 +   Result:     OK - RLSUB Completed
   1.375 +               NO - RLSUB Failure
   1.376 +               BAD - command unknown or arguments invalid
   1.377 +
   1.378 +   The RLSUB command behaves identically to its LSUB counterpart, except
   1.379 +   remote mailboxes are returned in addition to local mailboxes in the
   1.380 +   LSUB responses.
   1.381 +
   1.382 +6. Formal Syntax
   1.383 +
   1.384 +   The following syntax specification uses the augmented Backus-Naur
   1.385 +   Form (BNF) as described in [ABNF].
   1.386 +
   1.387 +   list_mailbox = <list_mailbox> as defined in [RFC-2060]
   1.388 +
   1.389 +   mailbox = <mailbox> as defined in [RFC-2060]
   1.390 +
   1.391 +   mailbox_referral = <tag> SPACE "NO" SPACE
   1.392 +      <referral_response_code> (text / text_mime2)
   1.393 +      ; See [RFC-2060] for <tag>, text and text_mime2 definition
   1.394 +
   1.395 +
   1.396 +
   1.397 +Gahrns                      Standards Track                     [Page 7]
   1.398 +
   1.399 +RFC 2193                IMAP4 Mailbox Referrals           September 1997
   1.400 +
   1.401 +
   1.402 +   referral_response_code = "[" "REFERRAL" 1*(SPACE <url>) "]"
   1.403 +      ; See [RFC-1738] for <url> definition
   1.404 +
   1.405 +   rlist = "RLIST" SPACE mailbox SPACE list_mailbox
   1.406 +
   1.407 +   rlsub = "RLSUB" SPACE mailbox SPACE list_mailbox
   1.408 +
   1.409 +6. Security Considerations
   1.410 +
   1.411 +   The IMAP4 referral mechanism makes use of IMAP URLs, and as such,
   1.412 +   have the same security considerations as general internet URLs [RFC-
   1.413 +   1738], and in particular IMAP URLs [RFC-2192].
   1.414 +
   1.415 +   With the MAILBOX-REFERRALS capability, it is potentially easier to
   1.416 +   write a rogue server that injects a bogus referral response that
   1.417 +   directs a user to an incorrect mailbox.  Although referrals reduce
   1.418 +   the effort to write such a server, the referral response makes
   1.419 +   detection of the intrusion easier.
   1.420 +
   1.421 +7. References
   1.422 +
   1.423 +   [RFC-2060], Crispin, M., "Internet Message Access Protocol - Version
   1.424 +   4rev1", RFC 2060, University of Washington, December 1996.
   1.425 +
   1.426 +   [RFC-2192], Newman, C., "IMAP URL Scheme", RFC 2192, Innosoft,
   1.427 +   September 1997.
   1.428 +
   1.429 +   [RFC-1738], Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform
   1.430 +   Resource Locators (URL)", RFC 1738, CERN, Xerox Corporation,
   1.431 +   University of Minnesota, December 1994.
   1.432 +
   1.433 +   [RFC-2119], Bradner, S., "Key words for use in RFCs to Indicate
   1.434 +   Requirement Levels", RFC 2119, Harvard University, March 1997.
   1.435 +
   1.436 +   [ABNF], DRUMS working group, Dave Crocker Editor, "Augmented BNF for
   1.437 +   Syntax Specifications: ABNF", Work in Progress, Internet Mail
   1.438 +   Consortium, April 1997.
   1.439 +
   1.440 +8.  Acknowledgments
   1.441 +
   1.442 +   Many valuable suggestions were received from private discussions and
   1.443 +   the IMAP4 mailing list.  In particular, Raymond Cheng, Mark Crispin,
   1.444 +   Mark Keasling, Chris Newman and Larry Osterman made significant
   1.445 +   contributions to this document.
   1.446 +
   1.447 +
   1.448 +
   1.449 +
   1.450 +
   1.451 +
   1.452 +
   1.453 +Gahrns                      Standards Track                     [Page 8]
   1.454 +
   1.455 +RFC 2193                IMAP4 Mailbox Referrals           September 1997
   1.456 +
   1.457 +
   1.458 +9. Author's Address
   1.459 +
   1.460 +   Mike Gahrns
   1.461 +   Microsoft
   1.462 +   One Microsoft Way
   1.463 +   Redmond, WA, 98072
   1.464 +
   1.465 +   Phone: (206) 936-9833
   1.466 +   EMail: mikega@microsoft.com
   1.467 +
   1.468 +
   1.469 +
   1.470 +
   1.471 +
   1.472 +
   1.473 +
   1.474 +
   1.475 +
   1.476 +
   1.477 +
   1.478 +
   1.479 +
   1.480 +
   1.481 +
   1.482 +
   1.483 +
   1.484 +
   1.485 +
   1.486 +
   1.487 +
   1.488 +
   1.489 +
   1.490 +
   1.491 +
   1.492 +
   1.493 +
   1.494 +
   1.495 +
   1.496 +
   1.497 +
   1.498 +
   1.499 +
   1.500 +
   1.501 +
   1.502 +
   1.503 +
   1.504 +
   1.505 +
   1.506 +
   1.507 +
   1.508 +
   1.509 +Gahrns                      Standards Track                     [Page 9]
   1.510 +