rfc2342.txt (19489B)
1 2 3 4 5 6 7 Network Working Group M. Gahrns 8 Request for Comments: 2342 Microsoft 9 Category: Standards Track C. Newman 10 Innosoft 11 May 1998 12 13 14 IMAP4 Namespace 15 16 Status of this Memo 17 18 This document specifies an Internet standards track protocol for the 19 Internet community, and requests discussion and suggestions for 20 improvements. Please refer to the current edition of the "Internet 21 Official Protocol Standards" (STD 1) for the standardization state 22 and status of this protocol. Distribution of this memo is unlimited. 23 24 Copyright Notice 25 26 Copyright (C) The Internet Society (1998). All Rights Reserved. 27 28 1. Abstract 29 30 IMAP4 [RFC-2060] does not define a default server namespace. As a 31 result, two common namespace models have evolved: 32 33 The "Personal Mailbox" model, in which the default namespace that is 34 presented consists of only the user's personal mailboxes. To access 35 shared mailboxes, the user must use an escape mechanism to reach 36 another namespace. 37 38 The "Complete Hierarchy" model, in which the default namespace that 39 is presented includes the user's personal mailboxes along with any 40 other mailboxes they have access to. 41 42 These two models, create difficulties for certain client operations. 43 This document defines a NAMESPACE command that allows a client to 44 discover the prefixes of namespaces used by a server for personal 45 mailboxes, other users' mailboxes, and shared mailboxes. This allows 46 a client to avoid much of the manual user configuration that is now 47 necessary when mixing and matching IMAP4 clients and servers. 48 49 2. Conventions used in this document 50 51 In examples, "C:" and "S:" indicate lines sent by the client and 52 server respectively. If such lines are wrapped without a new "C:" or 53 "S:" label, then the wrapping is for editorial clarity and is not 54 part of the command. 55 56 57 58 Gahrns & Newman Standards Track [Page 1] 59 60 RFC 2342 IMAP4 Namespace May 1998 61 62 63 Personal Namespace: A namespace that the server considers within the 64 personal scope of the authenticated user on a particular connection. 65 Typically, only the authenticated user has access to mailboxes in 66 their Personal Namespace. It is the part of the namespace that 67 belongs to the user that is allocated for mailboxes. If an INBOX 68 exists for a user, it MUST appear within the user's personal 69 namespace. In the typical case, there SHOULD be only one Personal 70 Namespace on a server. 71 72 Other Users' Namespace: A namespace that consists of mailboxes from 73 the Personal Namespaces of other users. To access mailboxes in the 74 Other Users' Namespace, the currently authenticated user MUST be 75 explicitly granted access rights. For example, it is common for a 76 manager to grant to their secretary access rights to their mailbox. 77 In the typical case, there SHOULD be only one Other Users' Namespace 78 on a server. 79 80 Shared Namespace: A namespace that consists of mailboxes that are 81 intended to be shared amongst users and do not exist within a user's 82 Personal Namespace. 83 84 The namespaces a server uses MAY differ on a per-user basis. 85 86 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 87 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 88 document are to be interpreted as described in [RFC-2119]. 89 90 3. Introduction and Overview 91 92 Clients often attempt to create mailboxes for such purposes as 93 maintaining a record of sent messages (e.g. "Sent Mail") or 94 temporarily saving messages being composed (e.g. "Drafts"). For 95 these clients to inter-operate correctly with the variety of IMAP4 96 servers available, the user must enter the prefix of the Personal 97 Namespace used by the server. Using the NAMESPACE command, a client 98 is able to automatically discover this prefix without manual user 99 configuration. 100 101 In addition, users are often required to manually enter the prefixes 102 of various namespaces in order to view the mailboxes located there. 103 For example, they might be required to enter the prefix of #shared to 104 view the shared mailboxes namespace. The NAMESPACE command allows a 105 client to automatically discover the namespaces that are available on 106 a server. This allows a client to present the available namespaces to 107 the user in what ever manner it deems appropriate. For example, a 108 109 110 111 112 113 114 Gahrns & Newman Standards Track [Page 2] 115 116 RFC 2342 IMAP4 Namespace May 1998 117 118 119 client could choose to initially display only personal mailboxes, or 120 it may choose to display the complete list of mailboxes available, 121 and initially position the user at the root of their Personal 122 Namespace. 123 124 A server MAY choose to make available to the NAMESPACE command only a 125 subset of the complete set of namespaces the server supports. To 126 provide the ability to access these namespaces, a client SHOULD allow 127 the user the ability to manually enter a namespace prefix. 128 129 4. Requirements 130 131 IMAP4 servers that support this extension MUST list the keyword 132 NAMESPACE in their CAPABILITY response. 133 134 The NAMESPACE command is valid in the Authenticated and Selected 135 state. 136 137 5. NAMESPACE Command 138 139 Arguments: none 140 141 Response: an untagged NAMESPACE response that contains the prefix 142 and hierarchy delimiter to the server's Personal 143 Namespace(s), Other Users' Namespace(s), and Shared 144 Namespace(s) that the server wishes to expose. The 145 response will contain a NIL for any namespace class 146 that is not available. Namespace_Response_Extensions 147 MAY be included in the response. 148 Namespace_Response_Extensions which are not on the IETF 149 standards track, MUST be prefixed with an "X-". 150 151 Result: OK - Command completed 152 NO - Error: Can't complete command 153 BAD - argument invalid 154 155 Example 5.1: 156 =========== 157 158 < A server that supports a single personal namespace. No leading 159 prefix is used on personal mailboxes and "/" is the hierarchy 160 delimiter.> 161 162 C: A001 NAMESPACE 163 S: * NAMESPACE (("" "/")) NIL NIL 164 S: A001 OK NAMESPACE command completed 165 166 167 168 169 170 Gahrns & Newman Standards Track [Page 3] 171 172 RFC 2342 IMAP4 Namespace May 1998 173 174 175 Example 5.2: 176 =========== 177 178 < A user logged on anonymously to a server. No personal mailboxes 179 are associated with the anonymous user and the user does not have 180 access to the Other Users' Namespace. No prefix is required to 181 access shared mailboxes and the hierarchy delimiter is "." > 182 183 C: A001 NAMESPACE 184 S: * NAMESPACE NIL NIL (("" ".")) 185 S: A001 OK NAMESPACE command completed 186 187 Example 5.3: 188 =========== 189 190 < A server that contains a Personal Namespace and a single Shared 191 Namespace. > 192 193 C: A001 NAMESPACE 194 S: * NAMESPACE (("" "/")) NIL (("Public Folders/" "/")) 195 S: A001 OK NAMESPACE command completed 196 197 Example 5.4: 198 =========== 199 200 < A server that contains a Personal Namespace, Other Users' 201 Namespace and multiple Shared Namespaces. Note that the hierarchy 202 delimiter used within each namespace can be different. > 203 204 C: A001 NAMESPACE 205 S: * NAMESPACE (("" "/")) (("~" "/")) (("#shared/" "/") 206 ("#public/" "/")("#ftp/" "/")("#news." ".")) 207 S: A001 OK NAMESPACE command completed 208 209 The prefix string allows a client to do things such as automatically 210 creating personal mailboxes or LISTing all available mailboxes within 211 a namespace. 212 213 Example 5.5: 214 =========== 215 216 < A server that supports only the Personal Namespace, with a 217 leading prefix of INBOX to personal mailboxes and a hierarchy 218 delimiter of "."> 219 220 C: A001 NAMESPACE 221 S: * NAMESPACE (("INBOX." ".")) NIL NIL 222 S: A001 OK NAMESPACE command completed 223 224 225 226 Gahrns & Newman Standards Track [Page 4] 227 228 RFC 2342 IMAP4 Namespace May 1998 229 230 231 < Automatically create a mailbox to store sent items.> 232 233 C: A002 CREATE "INBOX.Sent Mail" 234 S: A002 OK CREATE command completed 235 236 Although typically a server will support only a single Personal 237 Namespace, and a single Other User's Namespace, circumstances exist 238 where there MAY be multiples of these, and a client MUST be prepared 239 for them. If a client is configured such that it is required to 240 create a certain mailbox, there can be circumstances where it is 241 unclear which Personal Namespaces it should create the mailbox in. 242 In these situations a client SHOULD let the user select which 243 namespaces to create the mailbox in. 244 245 Example 5.6: 246 =========== 247 248 < In this example, a server supports 2 Personal Namespaces. In 249 addition to the regular Personal Namespace, the user has an 250 additional personal namespace to allow access to mailboxes in an 251 MH format mailstore. > 252 253 < The client is configured to save a copy of all mail sent by the 254 user into a mailbox called 'Sent Mail'. Furthermore, after a 255 message is deleted from a mailbox, the client is configured to 256 move that message to a mailbox called 'Deleted Items'.> 257 258 < Note that this example demonstrates how some extension flags can 259 be passed to further describe the #mh namespace. > 260 261 C: A001 NAMESPACE 262 S: * NAMESPACE (("" "/")("#mh/" "/" "X-PARAM" ("FLAG1" "FLAG2"))) 263 NIL NIL 264 S: A001 OK NAMESPACE command completed 265 266 < It is desired to keep only one copy of sent mail. It is unclear 267 which Personal Namespace the client should use to create the 'Sent 268 Mail' mailbox. The user is prompted to select a namespace and 269 only one 'Sent Mail' mailbox is created. > 270 271 C: A002 CREATE "Sent Mail" 272 S: A002 OK CREATE command completed 273 274 < The client is designed so that it keeps two 'Deleted Items' 275 mailboxes, one for each namespace. > 276 277 C: A003 CREATE "Delete Items" 278 S: A003 OK CREATE command completed 279 280 281 282 Gahrns & Newman Standards Track [Page 5] 283 284 RFC 2342 IMAP4 Namespace May 1998 285 286 287 C: A004 CREATE "#mh/Deleted Items" 288 S: A004 OK CREATE command completed 289 290 The next level of hierarchy following the Other Users' Namespace 291 prefix SHOULD consist of <username>, where <username> is a user name 292 as per the IMAP4 LOGIN or AUTHENTICATE command. 293 294 A client can construct a LIST command by appending a "%" to the Other 295 Users' Namespace prefix to discover the Personal Namespaces of other 296 users that are available to the currently authenticated user. 297 298 In response to such a LIST command, a server SHOULD NOT return user 299 names that have not granted access to their personal mailboxes to the 300 user in question. 301 302 A server MAY return a LIST response containing only the names of 303 users that have explicitly granted access to the user in question. 304 305 Alternatively, a server MAY return NO to such a LIST command, 306 requiring that a user name be included with the Other Users' 307 Namespace prefix before listing any other user's mailboxes. 308 309 Example 5.7: 310 =========== 311 312 < A server that supports providing a list of other user's 313 mailboxes that are accessible to the currently logged on user. > 314 315 C: A001 NAMESPACE 316 S: * NAMESPACE (("" "/")) (("Other Users/" "/")) NIL 317 S: A001 OK NAMESPACE command completed 318 319 C: A002 LIST "" "Other Users/%" 320 S: * LIST () "/" "Other Users/Mike" 321 S: * LIST () "/" "Other Users/Karen" 322 S: * LIST () "/" "Other Users/Matthew" 323 S: * LIST () "/" "Other Users/Tesa" 324 S: A002 OK LIST command completed 325 326 Example 5.8: 327 =========== 328 329 < A server that does not support providing a list of other user's 330 mailboxes that are accessible to the currently logged on user. 331 The mailboxes are listable if the client includes the name of the 332 other user with the Other Users' Namespace prefix. > 333 334 335 336 337 338 Gahrns & Newman Standards Track [Page 6] 339 340 RFC 2342 IMAP4 Namespace May 1998 341 342 343 C: A001 NAMESPACE 344 S: * NAMESPACE (("" "/")) (("#Users/" "/")) NIL 345 S: A001 OK NAMESPACE command completed 346 347 < In this example, the currently logged on user has access to the 348 Personal Namespace of user Mike, but the server chose to suppress 349 this information in the LIST response. However, by appending the 350 user name Mike (received through user input) to the Other Users' 351 Namespace prefix, the client is able to get a listing of the 352 personal mailboxes of user Mike. > 353 354 C: A002 LIST "" "#Users/%" 355 S: A002 NO The requested item could not be found. 356 357 C: A003 LIST "" "#Users/Mike/%" 358 S: * LIST () "/" "#Users/Mike/INBOX" 359 S: * LIST () "/" "#Users/Mike/Foo" 360 S: A003 OK LIST command completed. 361 362 A prefix string might not contain a hierarchy delimiter, because 363 in some cases it is not needed as part of the prefix. 364 365 Example 5.9: 366 =========== 367 368 < A server that allows access to the Other Users' Namespace by 369 prefixing the others' mailboxes with a '~' followed by <username>, 370 where <username> is a user name as per the IMAP4 LOGIN or 371 AUTHENTICATE command.> 372 373 C: A001 NAMESPACE 374 S: * NAMESPACE (("" "/")) (("~" "/")) NIL 375 S: A001 OK NAMESPACE command completed 376 377 < List the mailboxes for user mark > 378 379 C: A002 LIST "" "~mark/%" 380 S: * LIST () "/" "~mark/INBOX" 381 S: * LIST () "/" "~mark/foo" 382 S: A002 OK LIST command completed 383 384 Historical convention has been to start all namespaces with the "#" 385 character. Namespaces that include the "#" character are not IMAP 386 URL [IMAP-URL] friendly requiring the "#" character to be represented 387 as %23 when within URLs. As such, server implementers MAY instead 388 consider using namespace prefixes that do not contain the "#" 389 character. 390 391 392 393 394 Gahrns & Newman Standards Track [Page 7] 395 396 RFC 2342 IMAP4 Namespace May 1998 397 398 399 6. Formal Syntax 400 401 The following syntax specification uses the augmented Backus-Naur 402 Form (BNF) as described in [ABNF]. 403 404 atom = <atom> 405 ; <atom> as defined in [RFC-2060] 406 407 Namespace = nil / "(" 1*( "(" string SP (<"> QUOTED_CHAR <"> / 408 nil) *(Namespace_Response_Extension) ")" ) ")" 409 410 Namespace_Command = "NAMESPACE" 411 412 Namespace_Response_Extension = SP string SP "(" string *(SP string) 413 ")" 414 415 Namespace_Response = "*" SP "NAMESPACE" SP Namespace SP Namespace SP 416 Namespace 417 418 ; The first Namespace is the Personal Namespace(s) 419 ; The second Namespace is the Other Users' Namespace(s) 420 ; The third Namespace is the Shared Namespace(s) 421 422 nil = <nil> 423 ; <nil> as defined in [RFC-2060] 424 425 QUOTED_CHAR = <QUOTED_CHAR> 426 ; <QUOTED_CHAR> as defined in [RFC-2060] 427 428 string = <string> 429 ; <string> as defined in [RFC-2060] 430 ; Note that the namespace prefix is to a mailbox and following 431 ; IMAP4 convention, any international string in the NAMESPACE 432 ; response MUST be of modified UTF-7 format as described in 433 ; [RFC-2060]. 434 435 7. Security Considerations 436 437 In response to a LIST command containing an argument of the Other 438 Users' Namespace prefix, a server SHOULD NOT list users that have not 439 granted list access to their personal mailboxes to the currently 440 authenticated user. Providing such a list, could compromise security 441 by potentially disclosing confidential information of who is located 442 on the server, or providing a starting point of a list of user 443 accounts to attack. 444 445 446 447 448 449 450 Gahrns & Newman Standards Track [Page 8] 451 452 RFC 2342 IMAP4 Namespace May 1998 453 454 455 8. References 456 457 [RFC-2060], Crispin, M., "Internet Message Access Protocol Version 458 4rev1", RFC 2060, December 1996. 459 460 [RFC-2119], Bradner, S., "Key words for use in RFCs to Indicate 461 Requirement Levels", BCP 14, RFC 2119, March 1997. 462 463 [ABNF] Crocker, D., Editor, and P. Overell, "Augmented BNF for Syntax 464 Specifications: ABNF", RFC 2234, November 1997. 465 466 [IMAP-URL], Newman, C., "IMAP URL Scheme", RFC 2192, September 1997. 467 468 9. Acknowledgments 469 470 Many people have participated in the discussion of IMAP namespaces on 471 the IMAP mailing list. In particular, the authors would like to 472 thank Mark Crispin for many of the concepts relating to the Personal 473 Namespace and accessing the Personal Namespace of other users, Steve 474 Hole for summarizing the two namespace models, John Myers and Jack De 475 Winter for their work in a preceding effort trying to define a 476 standardized personal namespace, and Larry Osterman for his review 477 and collaboration on this document. 478 479 11. Authors' Addresses 480 481 Mike Gahrns 482 Microsoft 483 One Microsoft Way 484 Redmond, WA, 98072, USA 485 486 Phone: (425) 936-9833 487 EMail: mikega@microsoft.com 488 489 490 Chris Newman 491 Innosoft International, Inc. 492 1050 East Garvey Ave. South 493 West Covina, CA, 91790, USA 494 495 EMail: chris.newman@innosoft.com 496 497 498 499 500 501 502 503 504 505 506 Gahrns & Newman Standards Track [Page 9] 507 508 RFC 2342 IMAP4 Namespace May 1998 509 510 511 12. Full Copyright Statement 512 513 Copyright (C) The Internet Society (1998). All Rights Reserved. 514 515 This document and translations of it may be copied and furnished to 516 others, and derivative works that comment on or otherwise explain it 517 or assist in its implementation may be prepared, copied, published 518 and distributed, in whole or in part, without restriction of any 519 kind, provided that the above copyright notice and this paragraph are 520 included on all such copies and derivative works. However, this 521 document itself may not be modified in any way, such as by removing 522 the copyright notice or references to the Internet Society or other 523 Internet organizations, except as needed for the purpose of 524 developing Internet standards in which case the procedures for 525 copyrights defined in the Internet Standards process must be 526 followed, or as required to translate it into languages other than 527 English. 528 529 The limited permissions granted above are perpetual and will not be 530 revoked by the Internet Society or its successors or assigns. 531 532 This document and the information contained herein is provided on an 533 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 534 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 535 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 536 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 537 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 Gahrns & Newman Standards Track [Page 10] 563