doc/src/rfc2342.txt

   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 \f
  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 \f
 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 \f
 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 \f
 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 \f
 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 \f
 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 \f
 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 \f
 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 \f
 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 \f