1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/rfc/rfc5092.txt	Mon Sep 14 15:17:45 2009 +0900
     1.3 @@ -0,0 +1,1795 @@
     1.4 +
     1.5 +
     1.6 +
     1.7 +
     1.8 +
     1.9 +
    1.10 +Network Working Group                                   A. Melnikov, Ed.
    1.11 +Request for Comments: 5092                                    Isode Ltd.
    1.12 +Obsoletes: 2192                                                C. Newman
    1.13 +Updates: 4467                                           Sun Microsystems
    1.14 +Category: Standards Track                                  November 2007
    1.15 +
    1.16 +
    1.17 +                            IMAP URL Scheme
    1.18 +
    1.19 +Status of This Memo
    1.20 +
    1.21 +   This document specifies an Internet standards track protocol for the
    1.22 +   Internet community, and requests discussion and suggestions for
    1.23 +   improvements.  Please refer to the current edition of the "Internet
    1.24 +   Official Protocol Standards" (STD 1) for the standardization state
    1.25 +   and status of this protocol.  Distribution of this memo is unlimited.
    1.26 +
    1.27 +Abstract
    1.28 +
    1.29 +   IMAP (RFC 3501) is a rich protocol for accessing remote message
    1.30 +   stores.  It provides an ideal mechanism for accessing public mailing
    1.31 +   list archives as well as private and shared message stores.  This
    1.32 +   document defines a URL scheme for referencing objects on an IMAP
    1.33 +   server.
    1.34 +
    1.35 +   This document obsoletes RFC 2192.  It also updates RFC 4467.
    1.36 +
    1.37 +
    1.38 +
    1.39 +
    1.40 +
    1.41 +
    1.42 +
    1.43 +
    1.44 +
    1.45 +
    1.46 +
    1.47 +
    1.48 +
    1.49 +
    1.50 +
    1.51 +
    1.52 +
    1.53 +
    1.54 +
    1.55 +
    1.56 +
    1.57 +
    1.58 +
    1.59 +
    1.60 +
    1.61 +Melnikov & Newman           Standards Track                     [Page 1]
    1.62 +
    1.63 +RFC 5092                    IMAP URL Scheme                November 2007
    1.64 +
    1.65 +
    1.66 +Table of Contents
    1.67 +
    1.68 +   1. Introduction ....................................................2
    1.69 +   2. Conventions Used in This Document ...............................3
    1.70 +   3. IMAP userinfo Component (iuserinfo) .............................4
    1.71 +      3.1. IMAP Mailbox Naming Scope ..................................4
    1.72 +      3.2. IMAP User Name and Authentication Mechanism ................4
    1.73 +      3.3. Limitations of enc-user ....................................6
    1.74 +   4. IMAP Server .....................................................7
    1.75 +   5. Lists of Messages ...............................................7
    1.76 +   6. A Specific Message or Message Part ..............................8
    1.77 +      6.1. URLAUTH Authorized URL .....................................9
    1.78 +           6.1.1. Concepts ............................................9
    1.79 +                  6.1.1.1. URLAUTH ....................................9
    1.80 +                  6.1.1.2. Mailbox Access Key .........................9
    1.81 +                  6.1.1.3. Authorized Access Identifier ...............9
    1.82 +                  6.1.1.4. Authorization Mechanism ...................10
    1.83 +                  6.1.1.5. Authorization Token .......................10
    1.84 +           6.1.2. URLAUTH Extensions to IMAP URL .....................10
    1.85 +   7. Relative IMAP URLs .............................................11
    1.86 +      7.1. absolute-path References ..................................12
    1.87 +      7.2. relative-path References ..................................12
    1.88 +   8. Internationalization Considerations ............................13
    1.89 +   9. Examples .......................................................13
    1.90 +      9.1. Examples of Relative URLs .................................16
    1.91 +   10. Security Considerations .......................................16
    1.92 +      10.1. Security Considerations Specific to URLAUTH Authorized
    1.93 +            URL ......................................................17
    1.94 +   11. ABNF for IMAP URL Scheme ......................................17
    1.95 +   12. IANA Considerations ...........................................21
    1.96 +      12.1. IANA Registration of imap: URI Scheme ....................21
    1.97 +   13. References ....................................................22
    1.98 +      13.1. Normative References .....................................22
    1.99 +      13.2. Informative References ...................................23
   1.100 +   Appendix A. Sample Code............................................24
   1.101 +   Appendix B. List of Changes since RFC 2192.........................30
   1.102 +   Appendix C. List of Changes since RFC 4467.........................31
   1.103 +   Appendix D. Acknowledgments........................................31
   1.104 +
   1.105 +1.  Introduction
   1.106 +
   1.107 +   The IMAP URL scheme is used to designate IMAP servers, mailboxes,
   1.108 +   messages, MIME bodies [MIME], and search programs on Internet hosts
   1.109 +   accessible using the IMAP protocol over TCP.
   1.110 +
   1.111 +   The IMAP URL follows the common Internet scheme syntax as defined in
   1.112 +   [URI-GEN].  If :<port> is omitted, the port defaults to 143 (as
   1.113 +   defined in Section 2.1 of [IMAP4]).
   1.114 +
   1.115 +
   1.116 +
   1.117 +Melnikov & Newman           Standards Track                     [Page 2]
   1.118 +
   1.119 +RFC 5092                    IMAP URL Scheme                November 2007
   1.120 +
   1.121 +
   1.122 +   An absolute IMAP URL takes one of the following forms:
   1.123 +
   1.124 +      imap://<iserver>[/]
   1.125 +
   1.126 +      imap://<iserver>/<enc-mailbox>[<uidvalidity>][?<enc-search>]
   1.127 +
   1.128 +      imap://<iserver>/<enc-mailbox>[<uidvalidity>]<iuid>
   1.129 +       [<isection>][<ipartial>][<iurlauth>]
   1.130 +
   1.131 +   The first form is used to refer to an IMAP server (see Section 4),
   1.132 +   the second form refers to the contents of a mailbox or a set of
   1.133 +   messages resulting from a search (see Section 5), and the final form
   1.134 +   refers to a specific message or message part, and possibly a byte
   1.135 +   range in that part (see Section 6).  If [URLAUTH] extension is
   1.136 +   supported, then the final form can have the <iurlauth> component (see
   1.137 +   Section 6.1 for more details).
   1.138 +
   1.139 +   The <iserver> component common to all types of absolute IMAP URLs has
   1.140 +   the following syntax expressed in ABNF [ABNF]:
   1.141 +
   1.142 +      [iuserinfo "@"] host [ ":" port ]
   1.143 +
   1.144 +   The <iserver> component is the same as "authority" defined in
   1.145 +   [URI-GEN].  The syntax and uses of the <iuserinfo> ("IMAP userinfo
   1.146 +   component") are described in detail in Section 3.  The syntax of
   1.147 +   <host> and <port> is described in [URI-GEN].
   1.148 +
   1.149 +2.  Conventions Used in This Document
   1.150 +
   1.151 +   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   1.152 +   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   1.153 +   document are to be interpreted as described in RFC 2119 [KEYWORDS].
   1.154 +
   1.155 +   This document references many productions from [URI-GEN].  When the
   1.156 +   document needs to emphasize IMAP URI-specific differences from [URI-
   1.157 +   GEN] (i.e., for parts of IMAP URIs that have more restricted syntax
   1.158 +   than generic URIs), it uses a non-terminal i<foo> to define an IMAP-
   1.159 +   specific version of the non-terminal <foo> from [URI-GEN].
   1.160 +
   1.161 +   Note that the ABNF syntax shown in Section 11 is normative.  Sections
   1.162 +   2-6 may use a less formal syntax that does not necessarily match the
   1.163 +   normative ABNF shown in Section 11.  If there are any differences
   1.164 +   between the syntax shown in Sections 2-6 and Section 11, then the
   1.165 +   syntax shown in Section 11 must be treated as authoritative.  Non-
   1.166 +   syntax requirements included in Sections 2-6 are, of course,
   1.167 +   normative.
   1.168 +
   1.169 +
   1.170 +
   1.171 +
   1.172 +
   1.173 +Melnikov & Newman           Standards Track                     [Page 3]
   1.174 +
   1.175 +RFC 5092                    IMAP URL Scheme                November 2007
   1.176 +
   1.177 +
   1.178 +3.  IMAP userinfo Component (iuserinfo)
   1.179 +
   1.180 +   The <iuserinfo> component conforms to the generic syntax of
   1.181 +   <userinfo> defined in [URI-GEN].  It has the following syntax
   1.182 +   expressed in ABNF [ABNF]:
   1.183 +
   1.184 +      enc-user [iauth] / [enc-user] iauth
   1.185 +
   1.186 +   The meaning of the different parts is described in subsections of
   1.187 +   this section.
   1.188 +
   1.189 +3.1.  IMAP Mailbox Naming Scope
   1.190 +
   1.191 +   The "enc-user" part of the "iuserinfo" component, if present, denotes
   1.192 +   mailbox naming scope.  If it is absent, the IMAP URL can only
   1.193 +   reference mailboxes with globally unique names, i.e., mailboxes with
   1.194 +   names that don't change depending on the user the client
   1.195 +   authenticated as to the IMAP server.  Note that not all IMAP
   1.196 +   implementations support globally unique names.
   1.197 +
   1.198 +   For example, a personal mailbox described by the following URL
   1.199 +   <imap://michael@example.org/INBOX> is most likely different from a
   1.200 +   personal mailbox described by <imap://bester@example.org/INBOX>, even
   1.201 +   though both URLs use the same mailbox name.
   1.202 +
   1.203 +3.2.  IMAP User Name and Authentication Mechanism
   1.204 +
   1.205 +   The userinfo component (see [URI-GEN]) of an IMAP URI may contain an
   1.206 +   IMAP user name (a.k.a. authorization identity [SASL], "enc-user")
   1.207 +   and/or an authentication mechanism. (Note that the "enc-user" also
   1.208 +   defines a mailbox naming scope as described in Section 3.1).  The
   1.209 +   IMAP user name and the authentication mechanism are used in the
   1.210 +   "LOGIN" or "AUTHENTICATE" commands after making the connection to the
   1.211 +   IMAP server.
   1.212 +
   1.213 +   If no user name and no authentication mechanism are supplied, the
   1.214 +   client MUST authenticate as anonymous to the server.  If the server
   1.215 +   advertises AUTH=ANONYMOUS IMAP capability, the client MUST use the
   1.216 +   AUTHENTICATE command with ANONYMOUS [ANONYMOUS] SASL mechanism.  If
   1.217 +   SASL ANONYMOUS is not available, the (case-insensitive) user name
   1.218 +   "anonymous" is used with the "LOGIN" command and the Internet email
   1.219 +   address of the end user accessing the resource is supplied as the
   1.220 +   password.  The latter option is given in order to provide for
   1.221 +   interoperability with deployed servers.
   1.222 +
   1.223 +   Note that, as described in RFC 3501, the "LOGIN" command MUST NOT be
   1.224 +   used when the IMAP server advertises the LOGINDISABLED capability.
   1.225 +
   1.226 +
   1.227 +
   1.228 +
   1.229 +Melnikov & Newman           Standards Track                     [Page 4]
   1.230 +
   1.231 +RFC 5092                    IMAP URL Scheme                November 2007
   1.232 +
   1.233 +
   1.234 +   An authentication mechanism (as used by the IMAP AUTHENTICATE
   1.235 +   command) can be expressed by adding ";AUTH=<enc-auth-type>" to the
   1.236 +   end of the user name in an IMAP URL.  When such an <enc-auth-type> is
   1.237 +   indicated, the client SHOULD request appropriate credentials from
   1.238 +   that mechanism and use the "AUTHENTICATE" command instead of the
   1.239 +   "LOGIN" command.  If no user name is specified, one MUST be obtained
   1.240 +   from the mechanism or requested from the user/configuration as
   1.241 +   appropriate.
   1.242 +
   1.243 +   The string ";AUTH=*" indicates that the client SHOULD select an
   1.244 +   appropriate authentication mechanism.  (Though the '*' character in
   1.245 +   this usage is not strictly a delimiter, it is being treated like a
   1.246 +   sub-delim [URI-GEN] in this instance.  It MUST NOT be percent-encoded
   1.247 +   in this usage, as ";AUTH=%2A" will not match this production.)  It
   1.248 +   MAY use any mechanism listed in the response to the CAPABILITY
   1.249 +   command (or CAPABILITY response code) or use an out-of-band security
   1.250 +   service resulting in a PREAUTH connection.  If no user name is
   1.251 +   specified and no appropriate authentication mechanisms are available,
   1.252 +   the client SHOULD fall back to anonymous login as described above.
   1.253 +   The behavior prescribed in this section allows a URL that grants
   1.254 +   read-write access to authorized users and read-only anonymous access
   1.255 +   to other users.
   1.256 +
   1.257 +   If a user name is included with no authentication mechanism, then
   1.258 +   ";AUTH=*" is assumed.
   1.259 +
   1.260 +   Clients must take care when resolving a URL that requires or requests
   1.261 +   any sort of authentication, since URLs can easily come from untrusted
   1.262 +   sources.  Supplying authentication credentials to the wrong server
   1.263 +   may compromise the security of the user's account; therefore, the
   1.264 +   program resolving the URL should meet at least one of the following
   1.265 +   criteria in this case:
   1.266 +
   1.267 +   1) The URL comes from a trusted source, such as a referral server
   1.268 +      that the client has validated and trusts according to site policy.
   1.269 +      Note that user entry of the URL may or may not count as a trusted
   1.270 +      source, depending on the experience level of the user and site
   1.271 +      policy.
   1.272 +
   1.273 +   2) Explicit local site policy permits the client to connect to the
   1.274 +      server in the URL.  For example, a company example.com may have a
   1.275 +      site policy to trust all IMAP server names ending in example.com,
   1.276 +      whereas such a policy would be unwise for example.edu where random
   1.277 +      students can set up IMAP servers.
   1.278 +
   1.279 +   3) The user confirms that connecting to that domain name with the
   1.280 +      specified credentials and/or mechanism is permitted.  For example,
   1.281 +      when using "LOGIN" or SASL PLAIN with Transport Layer Security
   1.282 +
   1.283 +
   1.284 +
   1.285 +Melnikov & Newman           Standards Track                     [Page 5]
   1.286 +
   1.287 +RFC 5092                    IMAP URL Scheme                November 2007
   1.288 +
   1.289 +
   1.290 +      (TLS), the IMAP URL client presents a dialog box "Is it OK to send
   1.291 +      your password to server "example.com"?  Please be aware the owners
   1.292 +      of example.com will be able to reuse your password to connect to
   1.293 +      other servers on your behalf".
   1.294 +
   1.295 +   4) A mechanism is used that validates the server before passing
   1.296 +      potentially compromising client credentials.  For example, a site
   1.297 +      has a designated TLS certificate used to certify site-trusted IMAP
   1.298 +      server certificates, and this has been configured explicitly into
   1.299 +      the IMAP URL client.  Another example is use of a Simple
   1.300 +      Authentication and Security Layer (SASL) mechanism such as
   1.301 +      DIGEST-MD5 [DIGEST-MD5], which supports mutual authentication.
   1.302 +
   1.303 +   5) An authentication mechanism is used that will not reveal any
   1.304 +      information to the server that could be used to compromise future
   1.305 +      connections.  Examples are SASL ANONYMOUS [ANONYMOUS] or GSSAPI
   1.306 +      [GSSAPI].
   1.307 +
   1.308 +   URLs that do not include a user name but include an authentication
   1.309 +   mechanism (";AUTH=<mech>") must be treated with extra care, since for
   1.310 +   some <mech>s they are more likely to compromise the user's primary
   1.311 +   account.  A URL containing ";AUTH=*" must also be treated with extra
   1.312 +   care since it might fall back on a weaker security mechanism.
   1.313 +   Finally, clients are discouraged from using a plaintext password as a
   1.314 +   fallback with ";AUTH=*" unless the connection has strong encryption.
   1.315 +
   1.316 +   A program interpreting IMAP URLs MAY cache open connections to an
   1.317 +   IMAP server for later reuse.  If a URL contains a user name, only
   1.318 +   connections authenticated as that user may be reused.  If a URL does
   1.319 +   not contain a user name or authentication mechanism, then only an
   1.320 +   anonymous connection may be reused.
   1.321 +
   1.322 +   Note that if unsafe or reserved characters such as " " (space) or ";"
   1.323 +   are present in the user name or authentication mechanism, they MUST
   1.324 +   be percent-encoded as described in [URI-GEN].
   1.325 +
   1.326 +3.3.  Limitations of enc-user
   1.327 +
   1.328 +   As per Sections 3.1 and 3.2 of this document, the IMAP URI enc-user
   1.329 +   has two purposes:
   1.330 +
   1.331 +      1) It provides context for user-specific mailbox paths such as
   1.332 +         "INBOX" (Section 3.1).
   1.333 +
   1.334 +      2) It specifies that resolution of the URL requires logging in as
   1.335 +         that user and limits use of that URL to only that user (Section
   1.336 +         3.2).
   1.337 +
   1.338 +
   1.339 +
   1.340 +
   1.341 +Melnikov & Newman           Standards Track                     [Page 6]
   1.342 +
   1.343 +RFC 5092                    IMAP URL Scheme                November 2007
   1.344 +
   1.345 +
   1.346 +   An obvious limitation of using the same field for both purposes is
   1.347 +   that the URL can be resolved only by the mailbox owner.  In order to
   1.348 +   avoid this restriction, implementations should use globally unique
   1.349 +   mailbox names (see Section 3.1) whenever possible.
   1.350 +
   1.351 +      Note: There is currently no general way in IMAP of learning a
   1.352 +      globally unique name for a mailbox.  However, by looking at the
   1.353 +      NAMESPACE [NAMESPACE] command result, it is possible to determine
   1.354 +      whether or not a mailbox name is globally unique.
   1.355 +
   1.356 +   The URLAUTH component overrides the second purpose of the enc-user in
   1.357 +   the IMAP URI and by default permits the URI to be resolved by any
   1.358 +   user permitted by the <access> identifier.  URLAUTH and <access>
   1.359 +   identifier are described in Section 6.1.
   1.360 +
   1.361 +4.  IMAP Server
   1.362 +
   1.363 +   An IMAP URL referring to an IMAP server has the following form:
   1.364 +
   1.365 +      imap://<iserver>[/]
   1.366 +
   1.367 +   This URL type is frequently used to describe a location of an IMAP
   1.368 +   server, both in referrals and in configuration.  It may optionally
   1.369 +   contain the <iuserinfo> component (see Sections 3 and 11).  A program
   1.370 +   interpreting this URL would issue the standard set of commands it
   1.371 +   uses to present a view of the content of the IMAP server, as visible
   1.372 +   to the user described by the "enc-user" part of the <iuserinfo>
   1.373 +   component, if the "enc-user" part is specified.
   1.374 +
   1.375 +5.  Lists of Messages
   1.376 +
   1.377 +   An IMAP URL referring to a list of messages has the following form:
   1.378 +
   1.379 +      imap://<iserver>/<enc-mailbox>[<uidvalidity>][?<enc-search>]
   1.380 +
   1.381 +   The <enc-mailbox> field is used as the argument to the IMAP4 "SELECT"
   1.382 +   or "EXAMINE" command.  Note that if unsafe or reserved characters
   1.383 +   such as " " (space), ";", or "?" are present in <enc-mailbox>, they
   1.384 +   MUST be percent-encoded as described in [URI-GEN].
   1.385 +
   1.386 +   The <uidvalidity> field is optional.  If it is present, it MUST be
   1.387 +   the same as the value of IMAP4 UIDVALIDITY response code at the time
   1.388 +   the URL was created.  This MUST be used by the program interpreting
   1.389 +   the IMAP URL to determine if the URL is stale.  If the IMAP URL is
   1.390 +   stale, then the program should behave as if the corresponding mailbox
   1.391 +   doesn't exist.
   1.392 +
   1.393 +
   1.394 +
   1.395 +
   1.396 +
   1.397 +Melnikov & Newman           Standards Track                     [Page 7]
   1.398 +
   1.399 +RFC 5092                    IMAP URL Scheme                November 2007
   1.400 +
   1.401 +
   1.402 +   Note that the <uidvalidity> field is a modifier to the <enc-mailbox>,
   1.403 +   i.e., it is considered a part of the last "component" (as used in
   1.404 +   [URI-GEN]) of the <enc-mailbox>.  This is significant during relative
   1.405 +   URI resolution.
   1.406 +
   1.407 +   The "?<enc-search>" field is optional.  If it is not present, the
   1.408 +   program interpreting the URL will present the entire content of the
   1.409 +   mailbox.
   1.410 +
   1.411 +   If the "?<enc-search>" field is present, the program interpreting the
   1.412 +   URL should use the contents of this field as arguments following an
   1.413 +   IMAP4 SEARCH command.  These arguments are likely to contain unsafe
   1.414 +   characters such as " " (space) (which are likely to be present in the
   1.415 +   <enc-search>).  If unsafe characters are present, they MUST be
   1.416 +   percent-encoded as described in [URI-GEN].
   1.417 +
   1.418 +   Note that quoted strings and non-synchronizing literals [LITERAL+]
   1.419 +   are allowed in the <enc-search> content; however, synchronizing
   1.420 +   literals are not allowed, as their presence would effectively mean
   1.421 +   that the agent interpreting IMAP URLs needs to parse an <enc-search>
   1.422 +   content, find all synchronizing literals, and perform proper command
   1.423 +   continuation request handling (see Sections 4.3 and 7 of [IMAP4]).
   1.424 +
   1.425 +6.  A Specific Message or Message Part
   1.426 +
   1.427 +   An IMAP URL referring to a specific message or message part has the
   1.428 +   following form:
   1.429 +
   1.430 +      imap://<iserver>/<enc-mailbox>[<uidvalidity>]<iuid>
   1.431 +      [<isection>][<ipartial>][<iurlauth>]
   1.432 +
   1.433 +   The <enc-mailbox> and [uidvalidity] are as defined in Section 5
   1.434 +   above.
   1.435 +
   1.436 +   If <uidvalidity> is present in this form, it SHOULD be used by the
   1.437 +   program interpreting the URL to determine if the URL is stale.
   1.438 +
   1.439 +   The <iuid> refers to an IMAP4 message Unique Identifier (UID), and it
   1.440 +   SHOULD be used as the <set> argument to the IMAP4 "UID FETCH"
   1.441 +   command.
   1.442 +
   1.443 +   The <isection> field is optional.  If not present, the URL refers to
   1.444 +   the entire Internet message as returned by the IMAP command "UID
   1.445 +   FETCH <uid> BODY.PEEK[]".  If present, the URL refers to the object
   1.446 +   returned by a "UID FETCH <uid> BODY.PEEK[<section>]" command.  The
   1.447 +   type of the object may be determined by using a "UID FETCH <uid>
   1.448 +   BODYSTRUCTURE" command and locating the appropriate part in the
   1.449 +
   1.450 +
   1.451 +
   1.452 +
   1.453 +Melnikov & Newman           Standards Track                     [Page 8]
   1.454 +
   1.455 +RFC 5092                    IMAP URL Scheme                November 2007
   1.456 +
   1.457 +
   1.458 +   resulting BODYSTRUCTURE.  Note that unsafe characters in [isection]
   1.459 +   MUST be percent-encoded as described in [URI-GEN].
   1.460 +
   1.461 +   The <ipartial> field is optional.  If present, it effectively appends
   1.462 +   "<<partial-range>>" to the end of the UID FETCH BODY.PEEK[<section>]
   1.463 +   command constructed as described in the previous paragraph.  In other
   1.464 +   words, it allows the client to request a byte range of the
   1.465 +   message/message part.
   1.466 +
   1.467 +   The <iurlauth> field is described in detail in Section 6.1.
   1.468 +
   1.469 +6.1.  URLAUTH Authorized URL
   1.470 +
   1.471 +   URLAUTH authorized URLs are only supported by an IMAP server
   1.472 +   advertising the URLAUTH IMAP capability [URLAUTH].
   1.473 +
   1.474 +6.1.1.  Concepts
   1.475 +
   1.476 +6.1.1.1.  URLAUTH
   1.477 +
   1.478 +   URLAUTH is a component, appended at the end of a URL, that conveys
   1.479 +   authorization to access the data addressed by that URL.  It contains
   1.480 +   an authorized access identifier, an authorization mechanism name, and
   1.481 +   an authorization token.  The authorization token is generated from
   1.482 +   the URL, the authorized access identifier, authorization mechanism
   1.483 +   name, and a mailbox access key.
   1.484 +
   1.485 +      Note: This specification only allows for the URLAUTH component in
   1.486 +      IMAP URLs describing a message or its part.
   1.487 +
   1.488 +6.1.1.2.  Mailbox Access Key
   1.489 +
   1.490 +   The mailbox access key is an unpredictable, random string.  To ensure
   1.491 +   unpredictability, the random string with at least 128 bits of entropy
   1.492 +   is generated by software or hardware (not by the human user).
   1.493 +
   1.494 +   Each user has a table of mailboxes and an associated mailbox access
   1.495 +   key for each mailbox.  Consequently, the mailbox access key is per-
   1.496 +   user and per-mailbox.  In other words, two users sharing the same
   1.497 +   mailbox each have a different mailbox access key for that mailbox,
   1.498 +   and each mailbox accessed by a single user also has a different
   1.499 +   mailbox access key.
   1.500 +
   1.501 +6.1.1.3.  Authorized Access Identifier
   1.502 +
   1.503 +   The authorized <access> identifier restricts use of the URLAUTH
   1.504 +   authorized URL to certain users authorized on the server, as
   1.505 +   described in Section 6.1.2.
   1.506 +
   1.507 +
   1.508 +
   1.509 +Melnikov & Newman           Standards Track                     [Page 9]
   1.510 +
   1.511 +RFC 5092                    IMAP URL Scheme                November 2007
   1.512 +
   1.513 +
   1.514 +6.1.1.4.  Authorization Mechanism
   1.515 +
   1.516 +   The authorization mechanism is the algorithm by which the URLAUTH is
   1.517 +   generated and subsequently verified, using the mailbox access key.
   1.518 +
   1.519 +6.1.1.5.  Authorization Token
   1.520 +
   1.521 +   The authorization token is a deterministic string of at least 128
   1.522 +   bits that an entity with knowledge of the secret mailbox access key
   1.523 +   and URL authorization mechanism can use to verify the URL.
   1.524 +
   1.525 +6.1.2.  URLAUTH Extensions to IMAP URL
   1.526 +
   1.527 +   A specific message or message part IMAP URL can optionally contain
   1.528 +   ";EXPIRE=<datetime>" and/or ";URLAUTH=<access>:<mech>:<token>".
   1.529 +
   1.530 +   When ";EXPIRE=<datetime>" is used, this indicates the latest date and
   1.531 +   time that the URL is valid.  After that date and time, the URL has
   1.532 +   expired and server implementations MUST reject the URL.  If
   1.533 +   ";EXPIRE=<datetime>" is not used, the URL has no expiration, but can
   1.534 +   still be revoked using the RESETKEY command [URLAUTH].
   1.535 +
   1.536 +   The URLAUTH takes the form ";URLAUTH=<access>:<mech>:<token>", and it
   1.537 +   MUST be at the end of the URL.  It is composed of three parts.  The
   1.538 +   <access> portion provides the authorized access identifiers that may
   1.539 +   constrain the operations and users that are permitted to use this
   1.540 +   URL.  The <mech> portion provides the authorization mechanism used by
   1.541 +   the IMAP server to generate the authorization token that follows.
   1.542 +   The <token> portion provides the authorization token, which can be
   1.543 +   generated using the GENURLAUTH command [URLAUTH].
   1.544 +
   1.545 +   The "submit+" <access> identifier prefix, followed by a userid,
   1.546 +   indicates that only a userid authorized as a message submission
   1.547 +   entity on behalf of the specified userid is permitted to use this
   1.548 +   URL.  The IMAP server does not validate the specified userid but does
   1.549 +   validate that the IMAP session has an authorization identity that is
   1.550 +   authorized as a message submission entity.  The authorized message
   1.551 +   submission entity MUST validate the userid prior to contacting the
   1.552 +   IMAP server.
   1.553 +
   1.554 +   The "user+" <access> identifier prefix, followed by a userid,
   1.555 +   indicates that use of this URL is limited to IMAP sessions that are
   1.556 +   logged in as the specified userid (that is, have authorization
   1.557 +   identity as that userid).
   1.558 +
   1.559 +      Note: If a SASL mechanism that provides both authorization and
   1.560 +      authentication identifiers is used to authenticate to the IMAP
   1.561 +      server, the "user+" <access> identifier MUST match the
   1.562 +
   1.563 +
   1.564 +
   1.565 +Melnikov & Newman           Standards Track                    [Page 10]
   1.566 +
   1.567 +RFC 5092                    IMAP URL Scheme                November 2007
   1.568 +
   1.569 +
   1.570 +      authorization identifier.  If the SASL mechanism can't transport
   1.571 +      the authorization identifier, the "user+" <access> identifier MUST
   1.572 +      match the authorization identifier derived from the authentication
   1.573 +      identifier (see [SASL]).
   1.574 +
   1.575 +   The "authuser" <access> identifier indicates that use of this URL is
   1.576 +   limited to authenticated IMAP sessions that are logged in as any
   1.577 +   non-anonymous user (that is, have authorization identity as a non-
   1.578 +   anonymous user) of that IMAP server.  To restate this: use of this
   1.579 +   type of URL is prohibited to anonymous IMAP sessions, i.e., any
   1.580 +   URLFETCH command containing this type of URL issued in an anonymous
   1.581 +   session MUST return NIL in the URLFETCH response.
   1.582 +
   1.583 +   The "anonymous" <access> identifier indicates that use of this URL is
   1.584 +   not restricted by session authorization identity; that is, any IMAP
   1.585 +   session in authenticated or selected state (as defined in [IMAP4]),
   1.586 +   including anonymous sessions, may issue a URLFETCH [URLAUTH] using
   1.587 +   this URL.
   1.588 +
   1.589 +   The authorization token is represented as an ASCII-encoded
   1.590 +   hexadecimal string, which is used to authorize the URL.  The length
   1.591 +   and the calculation of the authorization token depend upon the
   1.592 +   mechanism used, but in all cases, the authorization token is at least
   1.593 +   128 bits (and therefore at least 32 hexadecimal digits).
   1.594 +
   1.595 +   Example:
   1.596 +
   1.597 +      <imap://joe@example.com/INBOX/;uid=20/;section=1.2;urlauth=
   1.598 +      submit+fred:internal:91354a473744909de610943775f92038>
   1.599 +
   1.600 +7.  Relative IMAP URLs
   1.601 +
   1.602 +   Relative IMAP URLs are permitted and are resolved according to the
   1.603 +   rules defined in [URI-GEN].  In particular, in IMAP URLs parameters
   1.604 +   (such as ";uid=" or ";section=") are treated as part of the normal
   1.605 +   path with respect to relative URL resolution.
   1.606 +
   1.607 +   [URI-GEN] defines four forms of relative URLs: <inetwork-path>,
   1.608 +   <iabsolute-path>, <irelative-path>, and <ipath-empty>.  Their syntax
   1.609 +   is defined in Section 11.
   1.610 +
   1.611 +   A relative reference that begins with two slash characters is termed
   1.612 +   a network-path reference (<inetwork-path>); such references are
   1.613 +   rarely used, because in most cases they can be replaced with an
   1.614 +   equivalent absolute URL.  A relative reference that begins with a
   1.615 +   single slash character is termed an absolute-path reference
   1.616 +   (<iabsolute-path>; see also Section 7.1).  A relative reference that
   1.617 +   does not begin with a slash character is termed a relative-path
   1.618 +
   1.619 +
   1.620 +
   1.621 +Melnikov & Newman           Standards Track                    [Page 11]
   1.622 +
   1.623 +RFC 5092                    IMAP URL Scheme                November 2007
   1.624 +
   1.625 +
   1.626 +   reference (<irelative-path>; see also Section 7.2).  The final form
   1.627 +   is <ipath-empty>, which is "same-document reference" (see Section 4.4
   1.628 +   of [URI-GEN]).
   1.629 +
   1.630 +   The following observations about relative URLs are important:
   1.631 +
   1.632 +   The <iauth> grammar element (which is a part of <iuserinfo>, which
   1.633 +   is, in turn, a part of <iserver>; see Section 3) is considered part
   1.634 +   of the user name for purposes of resolving relative IMAP URLs.  This
   1.635 +   means that unless a new user name/server specification is included in
   1.636 +   the relative URL, the authentication mechanism is inherited from the
   1.637 +   base IMAP URL.
   1.638 +
   1.639 +   URLs always use "/" as the hierarchy delimiter for the purpose of
   1.640 +   resolving paths in relative URLs.  IMAP4 permits the use of any
   1.641 +   hierarchy delimiter in mailbox names.  For this reason, relative
   1.642 +   mailbox paths will only work if the mailbox uses "/" as the hierarchy
   1.643 +   delimiter.  Relative URLs may be used on mailboxes that use other
   1.644 +   delimiters, but in that case, the entire mailbox name MUST be
   1.645 +   specified in the relative URL or inherited as a whole from the base
   1.646 +   URL.
   1.647 +
   1.648 +   If an IMAP server allows for mailbox names starting with "./" or
   1.649 +   "../", ending with "/." or "/..", or containing sequences "/../" or
   1.650 +   "/./", then such mailbox names MUST be percent-encoded as described
   1.651 +   in [URI-GEN].  Otherwise, they would be misinterpreted as dot-
   1.652 +   segments (see Section 3.3 of [URI-GEN]), which are processed
   1.653 +   specially during the relative path resolution process.
   1.654 +
   1.655 +7.1.  absolute-path References
   1.656 +
   1.657 +   A relative reference that begins with a single slash character is
   1.658 +   termed an absolute-path reference (see Section 4.2 of [URI-GEN]).  If
   1.659 +   an IMAP server permits mailbox names with a leading "/", then the
   1.660 +   leading "/" MUST be percent-encoded as described in [URI-GEN].
   1.661 +   Otherwise, the produced absolute-path reference URI will be
   1.662 +   misinterpreted as a network-path reference [URI-GEN] described by the
   1.663 +   <inetwork-path> non-terminal.
   1.664 +
   1.665 +7.2.  relative-path References
   1.666 +
   1.667 +   A relative reference that does not begin with a slash character is
   1.668 +   termed a relative-path reference [URI-GEN].  Implementations MUST NOT
   1.669 +   generate or accept relative-path IMAP references.
   1.670 +
   1.671 +   See also Section 4.2 of [URI-GEN] for restrictions on relative-path
   1.672 +   references.
   1.673 +
   1.674 +
   1.675 +
   1.676 +
   1.677 +Melnikov & Newman           Standards Track                    [Page 12]
   1.678 +
   1.679 +RFC 5092                    IMAP URL Scheme                November 2007
   1.680 +
   1.681 +
   1.682 +8.  Internationalization Considerations
   1.683 +
   1.684 +   IMAP4, Section 5.1.3 [IMAP4] includes a convention for encoding non-
   1.685 +   US-ASCII characters in IMAP mailbox names.  Because this convention
   1.686 +   is private to IMAP, it is necessary to convert IMAP's encoding to one
   1.687 +   that can be more easily interpreted by a URL display program.  For
   1.688 +   this reason, IMAP's modified UTF-7 encoding for mailboxes MUST be
   1.689 +   converted to UTF-8 [UTF-8].  Since 8-bit octets are not permitted in
   1.690 +   URLs, the UTF-8 octets are percent-encoded as required by the URL
   1.691 +   specification [URI-GEN], Section 2.1.  Sample code is included in
   1.692 +   Appendix A to demonstrate this conversion.
   1.693 +
   1.694 +   IMAP user names are UTF-8 strings and MUST be percent-encoded as
   1.695 +   required by the URL specification [URI-GEN], Section 2.1.
   1.696 +
   1.697 +   Also note that IMAP SEARCH criteria can contain non-US-ASCII
   1.698 +   characters.  8-bit octets in those strings MUST be percent-encoded as
   1.699 +   required by the URL specification [URI-GEN], Section 2.1.
   1.700 +
   1.701 +9.  Examples
   1.702 +
   1.703 +   The following examples demonstrate how an IMAP4 client program might
   1.704 +   translate various IMAP4 URLs into a series of IMAP4 commands.
   1.705 +   Commands sent from the client to the server are prefixed with "C:",
   1.706 +   and responses sent from the server to the client are prefixed with
   1.707 +   "S:".
   1.708 +
   1.709 +   The URL:
   1.710 +
   1.711 +      <imap://minbari.example.org/gray-council;UIDVALIDITY=385759045/;
   1.712 +      UID=20/;PARTIAL=0.1024>
   1.713 +
   1.714 +   may result in the following client commands and server responses:
   1.715 +
   1.716 +      <connect to minbari.example.org, port 143>
   1.717 +      S: * OK [CAPABILITY IMAP4rev1 STARTTLS AUTH=ANONYMOUS] Welcome
   1.718 +      C: A001 AUTHENTICATE ANONYMOUS
   1.719 +      S: +
   1.720 +      C: c2hlcmlkYW5AYmFieWxvbjUuZXhhbXBsZS5vcmc=
   1.721 +      S: A001 OK Welcome sheridan@babylon5.example.org
   1.722 +      C: A002 SELECT gray-council
   1.723 +      <client verifies the UIDVALIDITY matches>
   1.724 +      C: A003 UID FETCH 20 BODY.PEEK[]<0.1024>
   1.725 +
   1.726 +   The URL:
   1.727 +
   1.728 +      <imap://psicorp.example.org/~peter/%E6%97%A5%E6%9C%AC%E8%AA%9E/
   1.729 +      %E5%8F%B0%E5%8C%97>
   1.730 +
   1.731 +
   1.732 +
   1.733 +Melnikov & Newman           Standards Track                    [Page 13]
   1.734 +
   1.735 +RFC 5092                    IMAP URL Scheme                November 2007
   1.736 +
   1.737 +
   1.738 +   may result in the following client commands:
   1.739 +
   1.740 +      <connect to psicorp.example.org, port 143>
   1.741 +      S: * OK [CAPABILITY IMAP4rev1 STARTTLS AUTH=CRAM-MD5] Welcome
   1.742 +      C: A001 LOGIN ANONYMOUS bester@psycop.psicorp.example.org
   1.743 +      C: A002 SELECT ~peter/&ZeVnLIqe-/&U,BTFw-
   1.744 +      <commands the client uses for viewing the contents of
   1.745 +       the mailbox>
   1.746 +
   1.747 +   The URL:
   1.748 +
   1.749 +      <imap://;AUTH=GSSAPI@minbari.example.org/gray-council/;uid=20/
   1.750 +      ;section=1.2>
   1.751 +
   1.752 +   may result in the following client commands:
   1.753 +
   1.754 +      <connect to minbari.example.org, port 143>
   1.755 +      S: * OK Greetings
   1.756 +      C: A000 CAPABILITY
   1.757 +      S: * CAPABILITY IMAP4rev1 STARTTLS AUTH=GSSAPI
   1.758 +      S: A000 OK
   1.759 +      C: A001 AUTHENTICATE GSSAPI
   1.760 +      <authentication exchange>
   1.761 +      C: A002 SELECT gray-council
   1.762 +      C: A003 UID FETCH 20 BODY.PEEK[1.2]
   1.763 +
   1.764 +   If the following relative URL is located in that body part:
   1.765 +
   1.766 +      <;section=1.4>
   1.767 +
   1.768 +   this could result in the following client commands:
   1.769 +
   1.770 +      C: A004 UID FETCH 20 (BODY.PEEK[1.2.MIME]
   1.771 +            BODY.PEEK[1.MIME]
   1.772 +            BODY.PEEK[HEADER.FIELDS (Content-Location)])
   1.773 +      <Client looks for Content-Location headers in
   1.774 +       result.  If no such headers, then it does the following>
   1.775 +      C: A005 UID FETCH 20 BODY.PEEK[1.4]
   1.776 +
   1.777 +   The URL:
   1.778 +
   1.779 +      <imap://;AUTH=*@minbari.example.org/gray%20council?
   1.780 +      SUBJECT%20shadows>
   1.781 +
   1.782 +
   1.783 +
   1.784 +
   1.785 +
   1.786 +
   1.787 +
   1.788 +
   1.789 +Melnikov & Newman           Standards Track                    [Page 14]
   1.790 +
   1.791 +RFC 5092                    IMAP URL Scheme                November 2007
   1.792 +
   1.793 +
   1.794 +   could result in the following:
   1.795 +
   1.796 +      <connect to minbari.example.org, port 143>
   1.797 +      S: * OK Welcome
   1.798 +      C: A001 CAPABILITY
   1.799 +      S: * CAPABILITY IMAP4rev1 AUTH=DIGEST-MD5
   1.800 +      S: A001 OK
   1.801 +      C: A002 AUTHENTICATE DIGEST-MD5
   1.802 +      <authentication exchange>
   1.803 +      S: A002 OK user lennier authenticated
   1.804 +      C: A003 SELECT "gray council"
   1.805 +      ...
   1.806 +      C: A004 SEARCH SUBJECT shadows
   1.807 +      S: * SEARCH 8 10 13 14 15 16
   1.808 +      S: A004 OK SEARCH completed
   1.809 +      C: A005 FETCH 8,10,13:16 ALL
   1.810 +      ...
   1.811 +
   1.812 +   In the example above, the client has implementation-dependent
   1.813 +   choices.  The authentication mechanism could be anything, including
   1.814 +   PREAUTH.  The final FETCH command could fetch more or less
   1.815 +   information about the messages, depending on what it wishes to
   1.816 +   display to the user.
   1.817 +
   1.818 +   The URL:
   1.819 +
   1.820 +      <imap://john;AUTH=*@minbari.example.org/babylon5/personel?
   1.821 +      charset%20UTF-8%20SUBJECT%20%7B14+%7D%0D%0A%D0%98%D0%B2%
   1.822 +      D0%B0%D0%BD%D0%BE%D0%B2%D0%B0>
   1.823 +
   1.824 +   shows that 8-bit data can be sent using non-synchronizing literals
   1.825 +   [LITERAL+].  This could result in the following:
   1.826 +
   1.827 +      <connect to minbari.example.org, port 143>
   1.828 +      S: * OK Hi there
   1.829 +      C: A001 CAPABILITY
   1.830 +      S: * CAPABILITY IMAP4rev1 LITERAL+ AUTH=DIGEST-MD5
   1.831 +      S: A001 OK
   1.832 +      C: A002 AUTHENTICATE DIGEST-MD5
   1.833 +      <authentication exchange>
   1.834 +      S: A002 OK user john authenticated
   1.835 +      C: A003 SELECT babylon5/personel
   1.836 +      ...
   1.837 +      C: A004 SEARCH CHARSET UTF-8 SUBJECT {14+}
   1.838 +      C: XXXXXXXXXXXXXX
   1.839 +      S: * SEARCH 7 10 12
   1.840 +      S: A004 OK SEARCH completed
   1.841 +      C: A005 FETCH 7,10,12 ALL
   1.842 +
   1.843 +
   1.844 +
   1.845 +Melnikov & Newman           Standards Track                    [Page 15]
   1.846 +
   1.847 +RFC 5092                    IMAP URL Scheme                November 2007
   1.848 +
   1.849 +
   1.850 +      ...
   1.851 +
   1.852 +   where XXXXXXXXXXXXXX is 14 bytes of UTF-8 encoded data as specified
   1.853 +   in the URL above.
   1.854 +
   1.855 +9.1.  Examples of Relative URLs
   1.856 +
   1.857 +   The following absolute-path reference
   1.858 +
   1.859 +      </foo/;UID=20/..>
   1.860 +
   1.861 +   is the same as
   1.862 +
   1.863 +      </foo>
   1.864 +
   1.865 +   That is, both of them reference the mailbox "foo" located on the IMAP
   1.866 +   server described by the corresponding Base URI.
   1.867 +
   1.868 +   The following relative-path reference
   1.869 +
   1.870 +      <;UID=20>
   1.871 +
   1.872 +   references a message with UID in the mailbox specified by the Base
   1.873 +   URI.
   1.874 +
   1.875 +   The following edge case example demonstrates that the ;UIDVALIDITY=
   1.876 +   modifier is a part of the mailbox name as far as relative URI
   1.877 +   resolution is concerned:
   1.878 +
   1.879 +      <..;UIDVALIDITY=385759045/;UID=20>
   1.880 +
   1.881 +   In this example, ".." is not a dot-segment [URI-GEN].
   1.882 +
   1.883 +10.  Security Considerations
   1.884 +
   1.885 +   Security considerations discussed in the IMAP specification [IMAP4]
   1.886 +   and the URI specification [URI-GEN] are relevant.  Security
   1.887 +   considerations related to authenticated URLs are discussed in Section
   1.888 +   3.2 of this document.
   1.889 +
   1.890 +   Many email clients store the plaintext password for later use after
   1.891 +   logging into an IMAP server.  Such clients MUST NOT use a stored
   1.892 +   password in response to an IMAP URL without explicit permission from
   1.893 +   the user to supply that password to the specified host name.
   1.894 +
   1.895 +   Clients resolving IMAP URLs that wish to achieve data confidentiality
   1.896 +   and/or integrity SHOULD use the STARTTLS command (if supported by the
   1.897 +
   1.898 +
   1.899 +
   1.900 +
   1.901 +Melnikov & Newman           Standards Track                    [Page 16]
   1.902 +
   1.903 +RFC 5092                    IMAP URL Scheme                November 2007
   1.904 +
   1.905 +
   1.906 +   server) before starting authentication, or use a SASL mechanism, such
   1.907 +   as GSSAPI, that provides a confidentiality security layer.
   1.908 +
   1.909 +10.1.  Security Consideration Specific to URLAUTH Authorized URL
   1.910 +
   1.911 +   The "user+<userid>" <access> identifier limits resolution of that URL
   1.912 +   to a particular userid, whereas the "submit+<userid>" <access>
   1.913 +   identifier is more general and simply requires that the session be
   1.914 +   authorized by a user that has been granted a "submit" role within the
   1.915 +   authentication system.  Use of either of these mechanisms limits the
   1.916 +   scope of the URL.  An attacker who cannot authenticate using the
   1.917 +   appropriate credentials cannot make use of the URL.
   1.918 +
   1.919 +   The "authuser" and "anonymous" <access> identifiers do not have this
   1.920 +   level of protection.  These access identifiers are primarily useful
   1.921 +   for public export of data from an IMAP server, without requiring that
   1.922 +   it be copied to a web or anonymous FTP server.
   1.923 +
   1.924 +   The decision to use the "authuser" <access> identifier should be made
   1.925 +   with caution.  An "authuser" <access> identifier can be used by any
   1.926 +   authorized user of the IMAP server; therefore, use of this access
   1.927 +   identifier should be limited to content that may be disclosed to any
   1.928 +   authorized user of the IMAP server.
   1.929 +
   1.930 +   The decision to use the "anonymous" <access> identifier should be
   1.931 +   made with extreme caution.  An "anonymous" <access> identifier can be
   1.932 +   used by anyone; therefore, use of this access identifier should be
   1.933 +   limited to content that may be disclosed to anyone.
   1.934 +
   1.935 +11.  ABNF for IMAP URL Scheme
   1.936 +
   1.937 +   Formal syntax is defined using ABNF [ABNF], extending the ABNF rules
   1.938 +   in Section 9 of [IMAP4].  Elements not defined here can be found in
   1.939 +   [ABNF], [IMAP4], [IMAPABNF], or [URI-GEN].  Strings are not case
   1.940 +   sensitive, and free insertion of linear white space is not permitted.
   1.941 +
   1.942 +   sub-delims-sh = "!" / "$" / "'" / "(" / ")" /
   1.943 +                   "*" / "+" / ","
   1.944 +                      ;; Same as [URI-GEN] sub-delims,
   1.945 +                      ;; but without ";", "&" and "=".
   1.946 +
   1.947 +   uchar            = unreserved / sub-delims-sh / pct-encoded
   1.948 +
   1.949 +   achar            = uchar / "&" / "="
   1.950 +                      ;; Same as [URI-GEN] 'unreserved / sub-delims /
   1.951 +                      ;; pct-encoded', but ";" is disallowed.
   1.952 +
   1.953 +   bchar            = achar / ":" / "@" / "/"
   1.954 +
   1.955 +
   1.956 +
   1.957 +Melnikov & Newman           Standards Track                    [Page 17]
   1.958 +
   1.959 +RFC 5092                    IMAP URL Scheme                November 2007
   1.960 +
   1.961 +
   1.962 +   enc-auth-type    = 1*achar
   1.963 +                   ; %-encoded version of [IMAP4] "auth-type"
   1.964 +
   1.965 +   enc-mailbox      = 1*bchar
   1.966 +                  ; %-encoded version of [IMAP4] "mailbox"
   1.967 +
   1.968 +   enc-search       = 1*bchar
   1.969 +                           ; %-encoded version of [IMAPABNF]
   1.970 +                           ; "search-program".  Note that IMAP4
   1.971 +                           ; literals may not be used in
   1.972 +                           ; a "search-program", i.e., only
   1.973 +                           ; quoted or non-synchronizing
   1.974 +                           ; literals (if the server supports
   1.975 +                           ; LITERAL+ [LITERAL+]) are allowed.
   1.976 +
   1.977 +   enc-section      = 1*bchar
   1.978 +                  ; %-encoded version of [IMAP4] "section-spec"
   1.979 +
   1.980 +   enc-user         = 1*achar
   1.981 +                  ; %-encoded version of [IMAP4] authorization
   1.982 +                  ; identity or "userid".
   1.983 +
   1.984 +   imapurl          = "imap://" iserver ipath-query
   1.985 +               ; Defines an absolute IMAP URL
   1.986 +
   1.987 +   ipath-query      = ["/" [ icommand ]]
   1.988 +                    ; Corresponds to "path-abempty [ "?" query ]"
   1.989 +                    ; in [URI-GEN]
   1.990 +
   1.991 +   Generic syntax for relative URLs is defined in Section 4.2 of
   1.992 +   [URI-GEN].  For ease of implementation, the relative IMAP URL syntax
   1.993 +   is defined below:
   1.994 +
   1.995 +   imapurl-rel     = inetwork-path
   1.996 +
   1.997 +                     / iabsolute-path
   1.998 +                     / irelative-path
   1.999 +                     / ipath-empty
  1.1000 +
  1.1001 +   inetwork-path   = "//" iserver ipath-query
  1.1002 +               ; Corresponds to '"//" authority path-abempty
  1.1003 +               ; [ "?" query ]' in [URI-GEN]
  1.1004 +
  1.1005 +   iabsolute-path  = "/" [ icommand ]
  1.1006 +               ; icommand, if present, MUST NOT start with '/'.
  1.1007 +               ;
  1.1008 +               ; Corresponds to 'path-absolute [ "?" query ]'
  1.1009 +               ; in [URI-GEN]
  1.1010 +
  1.1011 +
  1.1012 +
  1.1013 +Melnikov & Newman           Standards Track                    [Page 18]
  1.1014 +
  1.1015 +RFC 5092                    IMAP URL Scheme                November 2007
  1.1016 +
  1.1017 +
  1.1018 +   irelative-path  = imessagelist /
  1.1019 +                     imsg-or-part
  1.1020 +               ; Corresponds to 'path-noscheme [ "?" query ]'
  1.1021 +               ; in [URI-GEN]
  1.1022 +
  1.1023 +   imsg-or-part    = ( imailbox-ref "/" iuid-only ["/" isection-only]
  1.1024 +                       ["/" ipartial-only] ) /
  1.1025 +                     ( iuid-only ["/" isection-only]
  1.1026 +                       ["/" ipartial-only] ) /
  1.1027 +                     ( isection-only ["/" ipartial-only] ) /
  1.1028 +                     ipartial-only
  1.1029 +
  1.1030 +   ipath-empty     = 0<pchar>
  1.1031 +                    ; Zero characters.
  1.1032 +                    ; The same-document reference.
  1.1033 +
  1.1034 +   The following three rules are only used in the presence of the IMAP
  1.1035 +   [URLAUTH] extension:
  1.1036 +
  1.1037 +   authimapurl     = "imap://" iserver "/" imessagepart
  1.1038 +                     ; Same as "imapurl" when "[icommand]" is
  1.1039 +                     ; "imessagepart"
  1.1040 +
  1.1041 +   authimapurlfull = authimapurl iurlauth
  1.1042 +                     ; Same as "imapurl" when "[icommand]" is
  1.1043 +                     ; "imessagepart iurlauth"
  1.1044 +
  1.1045 +   authimapurlrump = authimapurl iurlauth-rump
  1.1046 +
  1.1047 +
  1.1048 +   enc-urlauth     = 32*HEXDIG
  1.1049 +
  1.1050 +   iurlauth        = iurlauth-rump iua-verifier
  1.1051 +
  1.1052 +   iua-verifier    = ":" uauth-mechanism ":" enc-urlauth
  1.1053 +
  1.1054 +   iurlauth-rump   = [expire] ";URLAUTH=" access
  1.1055 +
  1.1056 +   access          = ("submit+" enc-user) / ("user+" enc-user) /
  1.1057 +                       "authuser" / "anonymous"
  1.1058 +
  1.1059 +   expire          = ";EXPIRE=" date-time
  1.1060 +                         ; date-time is defined in [DATETIME]
  1.1061 +
  1.1062 +   uauth-mechanism = "INTERNAL" / 1*(ALPHA / DIGIT / "-" / ".")
  1.1063 +                        ; Case-insensitive.
  1.1064 +                        ; New mechanisms MUST be registered with IANA.
  1.1065 +
  1.1066 +
  1.1067 +
  1.1068 +
  1.1069 +Melnikov & Newman           Standards Track                    [Page 19]
  1.1070 +
  1.1071 +RFC 5092                    IMAP URL Scheme                November 2007
  1.1072 +
  1.1073 +
  1.1074 +   iauth            = ";AUTH=" ( "*" / enc-auth-type )
  1.1075 +
  1.1076 +   icommand         = imessagelist /
  1.1077 +                      imessagepart [iurlauth]
  1.1078 +
  1.1079 +   imailbox-ref     = enc-mailbox [uidvalidity]
  1.1080 +
  1.1081 +   imessagelist     = imailbox-ref [ "?" enc-search ]
  1.1082 +                  ; "enc-search" is [URI-GEN] "query".
  1.1083 +
  1.1084 +   imessagepart     = imailbox-ref iuid [isection] [ipartial]
  1.1085 +
  1.1086 +   ipartial         = "/" ipartial-only
  1.1087 +
  1.1088 +   ipartial-only    = ";PARTIAL=" partial-range
  1.1089 +
  1.1090 +   isection         = "/" isection-only
  1.1091 +
  1.1092 +   isection-only    = ";SECTION=" enc-section
  1.1093 +
  1.1094 +   iserver          = [iuserinfo "@"] host [ ":" port ]
  1.1095 +                           ; This is the same as "authority" defined
  1.1096 +                           ; in [URI-GEN].  See [URI-GEN] for "host"
  1.1097 +                           ; and "port" definitions.
  1.1098 +
  1.1099 +   iuid             = "/" iuid-only
  1.1100 +
  1.1101 +   iuid-only        = ";UID=" nz-number
  1.1102 +                  ; See [IMAP4] for "nz-number" definition
  1.1103 +
  1.1104 +   iuserinfo        = enc-user [iauth] / [enc-user] iauth
  1.1105 +                                ; conforms to the generic syntax of
  1.1106 +                                ; "userinfo" as defined in [URI-GEN].
  1.1107 +
  1.1108 +   partial-range    = number ["." nz-number]
  1.1109 +                  ; partial FETCH.  The first number is
  1.1110 +                           ; the offset of the first byte,
  1.1111 +                           ; the second number is the length of
  1.1112 +                           ; the fragment.
  1.1113 +
  1.1114 +   uidvalidity      = ";UIDVALIDITY=" nz-number
  1.1115 +                       ; See [IMAP4] for "nz-number" definition
  1.1116 +
  1.1117 +
  1.1118 +
  1.1119 +
  1.1120 +
  1.1121 +
  1.1122 +
  1.1123 +
  1.1124 +
  1.1125 +Melnikov & Newman           Standards Track                    [Page 20]
  1.1126 +
  1.1127 +RFC 5092                    IMAP URL Scheme                November 2007
  1.1128 +
  1.1129 +
  1.1130 +12.  IANA Considerations
  1.1131 +
  1.1132 +   IANA has updated the "imap" definition in the "Uniform Resource
  1.1133 +   Identifier scheme registry" to point to this document.
  1.1134 +
  1.1135 +   The registration template (as per [URI-REG]) is specified in Section
  1.1136 +   12.1 of this document.
  1.1137 +
  1.1138 +12.1.  IANA Registration of imap: URI Scheme
  1.1139 +
  1.1140 +   This section provides the information required to register the imap:
  1.1141 +   URI scheme.
  1.1142 +
  1.1143 +   URI scheme name: imap
  1.1144 +
  1.1145 +   Status: permanent
  1.1146 +
  1.1147 +   URI scheme syntax:
  1.1148 +
  1.1149 +      See Section 11 of [RFC5092].
  1.1150 +
  1.1151 +   URI scheme semantics:
  1.1152 +
  1.1153 +      The imap: URI scheme is used to designate IMAP servers, mailboxes,
  1.1154 +      messages, MIME bodies [MIME] and their parts, and search programs
  1.1155 +      on Internet hosts accessible using the IMAP protocol.
  1.1156 +
  1.1157 +      There is no MIME type associated with this URI.
  1.1158 +
  1.1159 +   Encoding considerations:
  1.1160 +
  1.1161 +      See Section 8 of [RFC5092].
  1.1162 +
  1.1163 +   Applications/protocols that use this URI scheme name:
  1.1164 +
  1.1165 +      The imap: URI is intended to be used by applications that might
  1.1166 +      need access to an IMAP mailstore.  Such applications may include
  1.1167 +      (but are not limited to) IMAP-capable web browsers; IMAP clients
  1.1168 +      that wish to access a mailbox, message, or edit a message on the
  1.1169 +      server using [CATENATE]; [SUBMIT] clients and servers that are
  1.1170 +      requested to assemble a complete message on submission using
  1.1171 +      [BURL].
  1.1172 +
  1.1173 +   Interoperability considerations:
  1.1174 +
  1.1175 +      A widely deployed IMAP client Netscape Mail (and possibly
  1.1176 +      Mozilla/Thunderbird/Seamonkey) uses a different imap: scheme
  1.1177 +      internally.
  1.1178 +
  1.1179 +
  1.1180 +
  1.1181 +Melnikov & Newman           Standards Track                    [Page 21]
  1.1182 +
  1.1183 +RFC 5092                    IMAP URL Scheme                November 2007
  1.1184 +
  1.1185 +
  1.1186 +   Security considerations:
  1.1187 +
  1.1188 +      See Security Considerations (Section 10) of [RFC5092].
  1.1189 +
  1.1190 +   Contact:
  1.1191 +
  1.1192 +      Alexey Melnikov <alexey.melnikov@isode.com>
  1.1193 +
  1.1194 +   Author/Change controller:
  1.1195 +
  1.1196 +      IESG
  1.1197 +
  1.1198 +   References:
  1.1199 +
  1.1200 +      [RFC5092] and [IMAP4].
  1.1201 +
  1.1202 +13. References
  1.1203 +
  1.1204 +13.1.  Normative References
  1.1205 +
  1.1206 +   [KEYWORDS]   Bradner, S., "Key words for use in RFCs to Indicate
  1.1207 +                Requirement Levels", BCP 14, RFC 2119, March 1997.
  1.1208 +
  1.1209 +   [IMAP4]      Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
  1.1210 +                4rev1", RFC 3501, March 2003.
  1.1211 +
  1.1212 +   [IMAPABNF]   Melnikov, A. and C. Daboo, "Collected Extensions to
  1.1213 +                IMAP4 ABNF", RFC 4466, April 2006.
  1.1214 +
  1.1215 +   [ABNF]       Crocker, D., Ed., and P. Overell, "Augmented BNF for
  1.1216 +                Syntax Specifications: ABNF", RFC 4234, October 2005.
  1.1217 +
  1.1218 +   [MIME]       Freed, N. and N. Borenstein, "Multipurpose Internet Mail
  1.1219 +                Extensions (MIME) Part One: Format of Internet Message
  1.1220 +                Bodies", RFC 2045, November 1996.
  1.1221 +
  1.1222 +   [URI-GEN]    Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
  1.1223 +                Resource Identifier (URI): Generic Syntax", STD 66, RFC
  1.1224 +                3986, January 2005.
  1.1225 +
  1.1226 +   [UTF-8]      Yergeau, F., "UTF-8, a transformation format of ISO
  1.1227 +                10646", STD 63, RFC 3629, November 2003.
  1.1228 +
  1.1229 +   [NAMESPACE]  Gahrns, M. and C. Newman, "IMAP4 Namespace", RFC 2342,
  1.1230 +                May 1998.
  1.1231 +
  1.1232 +   [LITERAL+]   Myers, J., "IMAP4 non-synchronizing literals", RFC 2088,
  1.1233 +                January 1997.
  1.1234 +
  1.1235 +
  1.1236 +
  1.1237 +Melnikov & Newman           Standards Track                    [Page 22]
  1.1238 +
  1.1239 +RFC 5092                    IMAP URL Scheme                November 2007
  1.1240 +
  1.1241 +
  1.1242 +   [ANONYMOUS]  Zeilenga, K., "Anonymous Simple Authentication and
  1.1243 +                Security Layer (SASL) Mechanism", RFC 4505, June 2006.
  1.1244 +
  1.1245 +   [DATETIME]   Klyne, G. and C. Newman, "Date and Time on the Internet:
  1.1246 +                Timestamps", RFC 3339, July 2002.
  1.1247 +
  1.1248 +   [URLAUTH]    Crispin, M., "Internet Message Access Protocol (IMAP) -
  1.1249 +                URLAUTH Extension", RFC 4467, May 2006.
  1.1250 +
  1.1251 +13.2.  Informative References
  1.1252 +
  1.1253 +   [SUBMIT]     Gellens, R. and J. Klensin, "Message Submission for
  1.1254 +                Mail", RFC 4409, April 2006.
  1.1255 +
  1.1256 +   [BURL]       Newman, C., "Message Submission BURL Extension", RFC
  1.1257 +                4468, May 2006.
  1.1258 +
  1.1259 +   [CATENATE]   Resnick, P., "Internet Message Access Protocol (IMAP)
  1.1260 +                CATENATE Extension", RFC 4469, April 2006.
  1.1261 +
  1.1262 +   [SASL]       Melnikov, A., Ed., and K. Zeilenga, Ed., "Simple
  1.1263 +                Authentication and Security Layer (SASL)", RFC 4422,
  1.1264 +                June 2006.
  1.1265 +
  1.1266 +   [GSSAPI]     Melnikov, A., Ed., "The Kerberos V5 ("GSSAPI") Simple
  1.1267 +                Authentication and Security Layer (SASL) Mechanism", RFC
  1.1268 +                4752, November 2006.
  1.1269 +
  1.1270 +   [DIGEST-MD5] Leach, P. and C. Newman, "Using Digest Authentication as
  1.1271 +                a SASL Mechanism", RFC 2831, May 2000.
  1.1272 +
  1.1273 +   [URI-REG]    Hansen, T., Hardie, T., and L. Masinter, "Guidelines and
  1.1274 +                Registration Procedures for New URI Schemes", BCP 115,
  1.1275 +                RFC 4395, February 2006.
  1.1276 +
  1.1277 +
  1.1278 +
  1.1279 +
  1.1280 +
  1.1281 +
  1.1282 +
  1.1283 +
  1.1284 +
  1.1285 +
  1.1286 +
  1.1287 +
  1.1288 +
  1.1289 +
  1.1290 +
  1.1291 +
  1.1292 +
  1.1293 +Melnikov & Newman           Standards Track                    [Page 23]
  1.1294 +
  1.1295 +RFC 5092                    IMAP URL Scheme                November 2007
  1.1296 +
  1.1297 +
  1.1298 +Appendix A.  Sample Code
  1.1299 +
  1.1300 +   Here is sample C source code to convert between URL paths and IMAP
  1.1301 +   mailbox names, taking into account mapping between IMAP's modified
  1.1302 +   UTF-7 [IMAP4] and hex-encoded UTF-8, which is more appropriate for
  1.1303 +   URLs.  This code has not been rigorously tested nor does it
  1.1304 +   necessarily behave reasonably with invalid input, but it should serve
  1.1305 +   as a useful example.  This code just converts the mailbox portion of
  1.1306 +   the URL and does not deal with parameters, query, or server
  1.1307 +   components of the URL.
  1.1308 +
  1.1309 +/* Copyright (C) The IETF Trust (2007).  This version of
  1.1310 +   sample C code is part of RFC XXXX; see the RFC itself
  1.1311 +   for full legal notices.
  1.1312 +
  1.1313 +   Regarding this sample C code (or any portion of it), the authors
  1.1314 +   make no guarantees and are not responsible for any damage
  1.1315 +   resulting from its use.  The authors grant irrevocable permission
  1.1316 +   to anyone to use, modify, and distribute it in any way that does
  1.1317 +   not diminish the rights of anyone else to use, modify, and
  1.1318 +   distribute it, provided that redistributed derivative works do
  1.1319 +   not contain misleading author or version information.
  1.1320 +
  1.1321 +   Derivative works need not be licensed under similar terms.
  1.1322 + */
  1.1323 +
  1.1324 +#include <stdio.h>
  1.1325 +#include <string.h>
  1.1326 +
  1.1327 +/* hexadecimal lookup table */
  1.1328 +static const char hex[] = "0123456789ABCDEF";
  1.1329 +
  1.1330 +#define XX 127
  1.1331 +/*
  1.1332 + * Table for decoding hexadecimal in %encoding
  1.1333 + */
  1.1334 +static const char index_hex[256] = {
  1.1335 +    XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
  1.1336 +    XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
  1.1337 +    XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
  1.1338 +     0, 1, 2, 3,  4, 5, 6, 7,  8, 9,XX,XX, XX,XX,XX,XX,
  1.1339 +    XX,10,11,12, 13,14,15,XX, XX,XX,XX,XX, XX,XX,XX,XX,
  1.1340 +    XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
  1.1341 +    XX,10,11,12, 13,14,15,XX, XX,XX,XX,XX, XX,XX,XX,XX,
  1.1342 +    XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
  1.1343 +    XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
  1.1344 +    XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
  1.1345 +    XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
  1.1346 +
  1.1347 +
  1.1348 +
  1.1349 +Melnikov & Newman           Standards Track                    [Page 24]
  1.1350 +
  1.1351 +RFC 5092                    IMAP URL Scheme                November 2007
  1.1352 +
  1.1353 +
  1.1354 +    XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
  1.1355 +    XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
  1.1356 +    XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
  1.1357 +    XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
  1.1358 +    XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
  1.1359 +};
  1.1360 +#define HEXCHAR(c)  (index_hex[(unsigned char)(c)])
  1.1361 +
  1.1362 +/* "gen-delims" excluding "/" but including "%" */
  1.1363 +#define GENERAL_DELIMS_NO_SLASH     ":?#[]@" "%"
  1.1364 +
  1.1365 +/* "gen-delims" (excluding "/", but including "%")
  1.1366 +   plus subset of "sub-delims" */
  1.1367 +#define GENERAL_UNSAFE_NO_SLASH     GENERAL_DELIMS_NO_SLASH ";&=+"
  1.1368 +#define OTHER_UNSAFE                " \"<>\\^`{|}"
  1.1369 +
  1.1370 +/* URL unsafe printable characters */
  1.1371 +static const char mailbox_url_unsafe[] = GENERAL_UNSAFE_NO_SLASH
  1.1372 +                                         OTHER_UNSAFE;
  1.1373 +
  1.1374 +/* UTF7 modified base64 alphabet */
  1.1375 +static const char base64chars[] =
  1.1376 +  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+,";
  1.1377 +
  1.1378 +#define UNDEFINED 64
  1.1379 +
  1.1380 +/* UTF16 definitions */
  1.1381 +#define UTF16MASK   0x03FFUL
  1.1382 +#define UTF16SHIFT  10
  1.1383 +#define UTF16BASE   0x10000UL
  1.1384 +#define UTF16HIGHSTART   0xD800UL
  1.1385 +#define UTF16HIGHEND     0xDBFFUL
  1.1386 +#define UTF16LOSTART     0xDC00UL
  1.1387 +#define UTF16LOEND  0xDFFFUL
  1.1388 +
  1.1389 +/* Convert an IMAP mailbox to a URL path
  1.1390 + *  dst needs to have roughly 4 times the storage space of src
  1.1391 + *    Hex encoding can triple the size of the input
  1.1392 + *    UTF-7 can be slightly denser than UTF-8
  1.1393 + *     (worst case: 8 octets UTF-7 becomes 9 octets UTF-8)
  1.1394 + */
  1.1395 +void MailboxToURL(char *dst, char *src)
  1.1396 +{
  1.1397 +    unsigned char c, i, bitcount;
  1.1398 +    unsigned long ucs4, utf16, bitbuf;
  1.1399 +    unsigned char base64[256], utf8[6];
  1.1400 +
  1.1401 +    /* initialize modified base64 decoding table */
  1.1402 +
  1.1403 +
  1.1404 +
  1.1405 +Melnikov & Newman           Standards Track                    [Page 25]
  1.1406 +
  1.1407 +RFC 5092                    IMAP URL Scheme                November 2007
  1.1408 +
  1.1409 +
  1.1410 +    memset(base64, UNDEFINED, sizeof (base64));
  1.1411 +    for (i = 0; i < sizeof (base64chars); ++i) {
  1.1412 +     base64[(int) base64chars[i]] = i;
  1.1413 +    }
  1.1414 +
  1.1415 +    /* loop until end of string */
  1.1416 +    while (*src != '\0') {
  1.1417 +     c = *src++;
  1.1418 +     /* deal with literal characters and &- */
  1.1419 +     if (c != '&' || *src == '-') {
  1.1420 +         /* NB: There are no "URL safe" characters after the '~' */
  1.1421 +         if (c < ' ' || c > '~' ||
  1.1422 +             strchr(mailbox_url_unsafe, c) != NULL) {
  1.1423 +          /* hex encode if necessary */
  1.1424 +          dst[0] = '%';
  1.1425 +          dst[1] = hex[c >> 4];
  1.1426 +          dst[2] = hex[c & 0x0f];
  1.1427 +          dst += 3;
  1.1428 +         } else {
  1.1429 +          /* encode literally */
  1.1430 +          *dst++ = c;
  1.1431 +         }
  1.1432 +         /* skip over the '-' if this is an &- sequence */
  1.1433 +         if (c == '&') ++src;
  1.1434 +
  1.1435 +     } else {
  1.1436 +        /* convert modified UTF-7 -> UTF-16 -> UCS-4 -> UTF-8 -> HEX */
  1.1437 +         bitbuf = 0;
  1.1438 +         bitcount = 0;
  1.1439 +         ucs4 = 0;
  1.1440 +         while ((c = base64[(unsigned char) *src]) != UNDEFINED) {
  1.1441 +          ++src;
  1.1442 +          bitbuf = (bitbuf << 6) | c;
  1.1443 +          bitcount += 6;
  1.1444 +          /* enough bits for a UTF-16 character? */
  1.1445 +          if (bitcount >= 16) {
  1.1446 +              bitcount -= 16;
  1.1447 +              utf16 = (bitcount ? bitbuf >> bitcount
  1.1448 +                             : bitbuf) & 0xffff;
  1.1449 +              /* convert UTF16 to UCS4 */
  1.1450 +              if
  1.1451 +                    (utf16 >= UTF16HIGHSTART && utf16 <= UTF16HIGHEND) {
  1.1452 +               ucs4 = (utf16 - UTF16HIGHSTART) << UTF16SHIFT;
  1.1453 +               continue;
  1.1454 +              } else if
  1.1455 +                    (utf16 >= UTF16LOSTART && utf16 <= UTF16LOEND) {
  1.1456 +               ucs4 += utf16 - UTF16LOSTART + UTF16BASE;
  1.1457 +              } else {
  1.1458 +
  1.1459 +
  1.1460 +
  1.1461 +Melnikov & Newman           Standards Track                    [Page 26]
  1.1462 +
  1.1463 +RFC 5092                    IMAP URL Scheme                November 2007
  1.1464 +
  1.1465 +
  1.1466 +               ucs4 = utf16;
  1.1467 +              }
  1.1468 +              /* convert UTF-16 range of UCS4 to UTF-8 */
  1.1469 +              if (ucs4 <= 0x7fUL) {
  1.1470 +               utf8[0] = (unsigned char) ucs4;
  1.1471 +               i = 1;
  1.1472 +              } else if (ucs4 <= 0x7ffUL) {
  1.1473 +               utf8[0] = 0xc0 | (unsigned char) (ucs4 >> 6);
  1.1474 +               utf8[1] = 0x80 | (unsigned char) (ucs4 & 0x3f);
  1.1475 +               i = 2;
  1.1476 +              } else if (ucs4 <= 0xffffUL) {
  1.1477 +               utf8[0] = 0xe0 | (unsigned char) (ucs4 >> 12);
  1.1478 +               utf8[1] = 0x80 | (unsigned char) ((ucs4 >> 6) & 0x3f);
  1.1479 +               utf8[2] = 0x80 | (unsigned char) (ucs4 & 0x3f);
  1.1480 +               i = 3;
  1.1481 +              } else {
  1.1482 +               utf8[0] = 0xf0 | (unsigned char) (ucs4 >> 18);
  1.1483 +               utf8[1] = 0x80 | (unsigned char) ((ucs4 >> 12) & 0x3f);
  1.1484 +               utf8[2] = 0x80 | (unsigned char) ((ucs4 >> 6) & 0x3f);
  1.1485 +               utf8[3] = 0x80 | (unsigned char) (ucs4 & 0x3f);
  1.1486 +               i = 4;
  1.1487 +              }
  1.1488 +              /* convert utf8 to hex */
  1.1489 +              for (c = 0; c < i; ++c) {
  1.1490 +               dst[0] = '%';
  1.1491 +               dst[1] = hex[utf8[c] >> 4];
  1.1492 +               dst[2] = hex[utf8[c] & 0x0f];
  1.1493 +               dst += 3;
  1.1494 +              }
  1.1495 +          }
  1.1496 +         }
  1.1497 +         /* skip over trailing '-' in modified UTF-7 encoding */
  1.1498 +         if (*src == '-') ++src;
  1.1499 +     }
  1.1500 +    }
  1.1501 +    /* terminate destination string */
  1.1502 +    *dst = '\0';
  1.1503 +}
  1.1504 +
  1.1505 +/* Convert hex coded UTF-8 URL path to modified UTF-7 IMAP mailbox
  1.1506 + *  dst should be about twice the length of src to deal with non-hex
  1.1507 + *  coded URLs
  1.1508 + */
  1.1509 +int URLtoMailbox(char *dst, char *src)
  1.1510 +{
  1.1511 +    unsigned int utf8pos = 0;
  1.1512 +    unsigned int utf8total, i, c, utf7mode, bitstogo, utf16flag;
  1.1513 +    unsigned long ucs4 = 0, bitbuf = 0;
  1.1514 +
  1.1515 +
  1.1516 +
  1.1517 +Melnikov & Newman           Standards Track                    [Page 27]
  1.1518 +
  1.1519 +RFC 5092                    IMAP URL Scheme                November 2007
  1.1520 +
  1.1521 +
  1.1522 +    utf7mode = 0; /* is the output UTF7 currently in base64 mode? */
  1.1523 +    utf8total = 0; /* how many octets is the current input UTF-8 char;
  1.1524 +                      0 == between characters */
  1.1525 +    bitstogo = 0; /* bits that need to be encoded into base64; if
  1.1526 +                     bitstogo != 0 then utf7mode == 1 */
  1.1527 +    while ((c = (unsigned char)*src) != '\0') {
  1.1528 +     ++src;
  1.1529 +     /* undo hex-encoding */
  1.1530 +     if (c == '%' && src[0] != '\0' && src[1] != '\0') {
  1.1531 +         c = HEXCHAR(src[0]);
  1.1532 +         i = HEXCHAR(src[1]);
  1.1533 +         if (c == XX || i == XX) {
  1.1534 +             return 0;
  1.1535 +         } else {
  1.1536 +             c = (char)((c << 4) | i);
  1.1537 +         }
  1.1538 +         src += 2;
  1.1539 +     }
  1.1540 +     /* normal character? */
  1.1541 +     if (c >= ' ' && c <= '~') {
  1.1542 +         /* switch out of UTF-7 mode */
  1.1543 +         if (utf7mode) {
  1.1544 +          if (bitstogo) {
  1.1545 +          *dst++ = base64chars[(bitbuf << (6 - bitstogo)) & 0x3F];
  1.1546 +          }
  1.1547 +          *dst++ = '-';
  1.1548 +          utf7mode = 0;
  1.1549 +          bitstogo = bitbuf = 0;
  1.1550 +         }
  1.1551 +         *dst++ = c;
  1.1552 +         /* encode '&' as '&-' */
  1.1553 +         if (c == '&') {
  1.1554 +          *dst++ = '-';
  1.1555 +         }
  1.1556 +         continue;
  1.1557 +     }
  1.1558 +     /* switch to UTF-7 mode */
  1.1559 +     if (!utf7mode) {
  1.1560 +         *dst++ = '&';
  1.1561 +         utf7mode = 1;
  1.1562 +     }
  1.1563 +     /* Encode US-ASCII characters as themselves */
  1.1564 +     if (c < 0x80) {
  1.1565 +         ucs4 = c;
  1.1566 +         utf8total = 1;
  1.1567 +     } else if (utf8total) {
  1.1568 +         /* this is a subsequent octet of a multi-octet character */
  1.1569 +         /* save UTF8 bits into UCS4 */
  1.1570 +
  1.1571 +
  1.1572 +
  1.1573 +Melnikov & Newman           Standards Track                    [Page 28]
  1.1574 +
  1.1575 +RFC 5092                    IMAP URL Scheme                November 2007
  1.1576 +
  1.1577 +
  1.1578 +         ucs4 = (ucs4 << 6) | (c & 0x3FUL);
  1.1579 +         if (++utf8pos < utf8total) {
  1.1580 +          continue;
  1.1581 +         }
  1.1582 +     } else {
  1.1583 +         /* this is the first octet of a multi-octet character */
  1.1584 +         utf8pos = 1;
  1.1585 +         if (c < 0xE0) {
  1.1586 +          utf8total = 2;
  1.1587 +          ucs4 = c & 0x1F;
  1.1588 +         } else if (c < 0xF0) {
  1.1589 +          utf8total = 3;
  1.1590 +          ucs4 = c & 0x0F;
  1.1591 +         } else {
  1.1592 +          /* NOTE: can't convert UTF8 sequences longer than 4 */
  1.1593 +          utf8total = 4;
  1.1594 +          ucs4 = c & 0x03;
  1.1595 +         }
  1.1596 +         continue;
  1.1597 +     }
  1.1598 +     /* Finished with UTF-8 character.  Make sure it isn't an
  1.1599 +        overlong sequence.  If it is, return failure. */
  1.1600 +     if ((ucs4 < 0x80 && utf8total > 1) ||
  1.1601 +         (ucs4 < 0x0800 && utf8total > 2) ||
  1.1602 +         (ucs4 < 0x00010000 && utf8total > 3) ||
  1.1603 +         (ucs4 < 0x00200000 && utf8total > 4) ||
  1.1604 +         (ucs4 < 0x04000000 && utf8total > 5) ||
  1.1605 +         (ucs4 < 0x80000000 && utf8total > 6)) {
  1.1606 +         return 0;
  1.1607 +     }
  1.1608 +     /* loop to split ucs4 into two utf16 chars if necessary */
  1.1609 +     utf8total = 0;
  1.1610 +     do {
  1.1611 +         if (ucs4 >= UTF16BASE) {
  1.1612 +                ucs4 -= UTF16BASE;
  1.1613 +          bitbuf = (bitbuf << 16) | ((ucs4 >> UTF16SHIFT)
  1.1614 +                            + UTF16HIGHSTART);
  1.1615 +          ucs4 = (ucs4 & UTF16MASK) + UTF16LOSTART;
  1.1616 +          utf16flag = 1;
  1.1617 +         } else {
  1.1618 +          bitbuf = (bitbuf << 16) | ucs4;
  1.1619 +          utf16flag = 0;
  1.1620 +         }
  1.1621 +         bitstogo += 16;
  1.1622 +         /* spew out base64 */
  1.1623 +         while (bitstogo >= 6) {
  1.1624 +          bitstogo -= 6;
  1.1625 +          *dst++ = base64chars[(bitstogo ? (bitbuf >> bitstogo)
  1.1626 +
  1.1627 +
  1.1628 +
  1.1629 +Melnikov & Newman           Standards Track                    [Page 29]
  1.1630 +
  1.1631 +RFC 5092                    IMAP URL Scheme                November 2007
  1.1632 +
  1.1633 +
  1.1634 +                               : bitbuf)
  1.1635 +                         & 0x3F];
  1.1636 +         }
  1.1637 +     } while (utf16flag);
  1.1638 +    }
  1.1639 +    /* if in UTF-7 mode, finish in ASCII */
  1.1640 +    if (utf7mode) {
  1.1641 +     if (bitstogo) {
  1.1642 +         *dst++ = base64chars[(bitbuf << (6 - bitstogo)) & 0x3F];
  1.1643 +     }
  1.1644 +     *dst++ = '-';
  1.1645 +    }
  1.1646 +    /* tie off string */
  1.1647 +    *dst = '\0';
  1.1648 +    return 1;
  1.1649 +}
  1.1650 +
  1.1651 +Appendix B.  List of Changes since RFC 2192
  1.1652 +
  1.1653 +   Updated boilerplate, list of editor's, etc.
  1.1654 +   Updated references.
  1.1655 +   Updated ABNF not to use _, to use SP instead of SPACE, etc.
  1.1656 +   Updated example domains to use example.org.
  1.1657 +   Fixed ABNF error in "imessagelist" non-terminal.
  1.1658 +   Updated ABNF, due to changes in RFC 3501, RFC 4466, and RFC 3986.
  1.1659 +   Renamed "iuserauth" non-terminal to <iuserinfo>.
  1.1660 +   Clarified that the userinfo component describes both authorization
  1.1661 +   identity and mailbox naming scope.
  1.1662 +   Allow for non-synchronizing literals in "enc-search".
  1.1663 +   Added "ipartial" specifier that denotes a partial FETCH.
  1.1664 +   Moved URLAUTH text from RFC 4467 to this document.
  1.1665 +   Updated ABNF for the whole server to allow missing trailing "/"
  1.1666 +   (e.g., "imap://imap.example.com" is now valid and is the same as
  1.1667 +   "imap://imap.example.com/").
  1.1668 +   Clarified how relative-path references are constructed.
  1.1669 +   Added more examples demonstrating relative-path references.
  1.1670 +   Added rules for relative URLs and restructured ABNF as the result.
  1.1671 +   Removed text on use of relative URLs in MHTML.
  1.1672 +   Added examples demonstrating security considerations when resolving
  1.1673 +   URLs.
  1.1674 +   Recommend usage of STARTTLS/SASL security layer to protect
  1.1675 +   confidential data.
  1.1676 +   Removed some advices about connection reuse that were incorrect.
  1.1677 +   Removed URLs referencing a list of mailboxes, as this feature
  1.1678 +   hasn't seen any deployments.
  1.1679 +   Clarified that user name "anonymous" is case-insensitive.
  1.1680 +
  1.1681 +
  1.1682 +
  1.1683 +
  1.1684 +
  1.1685 +Melnikov & Newman           Standards Track                    [Page 30]
  1.1686 +
  1.1687 +RFC 5092                    IMAP URL Scheme                November 2007
  1.1688 +
  1.1689 +
  1.1690 +Appendix C.  List of Changes since RFC 4467
  1.1691 +
  1.1692 +   Renamed <mechanism> to <uauth-mechanism>.  Restructured ABNF.
  1.1693 +
  1.1694 +Appendix D.  Acknowledgments
  1.1695 +
  1.1696 +   Text describing URLAUTH was lifted from [URLAUTH] by Mark Crispin.
  1.1697 +
  1.1698 +   Stephane H. Maes contributed some ideas to this document; he also
  1.1699 +   co-edited early versions of this document.
  1.1700 +
  1.1701 +   The editors would like to thank Mark Crispin, Ken Murchison, Ted
  1.1702 +   Hardie, Zoltan Ordogh, Dave Cridland, Kjetil Torgrim Homme, Lisa
  1.1703 +   Dusseault, Spencer Dawkins, Filip Navara, Shawn M. Emery, Sam
  1.1704 +   Hartman, Russ Housley, and Lars Eggert for the time they devoted to
  1.1705 +   reviewing this document and/or for the comments received.
  1.1706 +
  1.1707 +Authors' Addresses
  1.1708 +
  1.1709 +   Chris Newman (Author/Editor)
  1.1710 +   Sun Microsystems
  1.1711 +   3401 Centrelake Dr., Suite 410
  1.1712 +   Ontario, CA 91761
  1.1713 +   EMail: chris.newman@sun.com
  1.1714 +
  1.1715 +   Alexey Melnikov (Editor)
  1.1716 +   Isode Limited
  1.1717 +   5 Castle Business Village
  1.1718 +   36 Station Road
  1.1719 +   Hampton, Middlesex
  1.1720 +   TW12 2BX, UK
  1.1721 +   EMail: Alexey.Melnikov@isode.com
  1.1722 +   URI:   http://www.melnikov.ca/
  1.1723 +
  1.1724 +
  1.1725 +
  1.1726 +
  1.1727 +
  1.1728 +
  1.1729 +
  1.1730 +
  1.1731 +
  1.1732 +
  1.1733 +
  1.1734 +
  1.1735 +
  1.1736 +
  1.1737 +
  1.1738 +
  1.1739 +
  1.1740 +
  1.1741 +Melnikov & Newman           Standards Track                    [Page 31]
  1.1742 +
  1.1743 +RFC 5092                    IMAP URL Scheme                November 2007
  1.1744 +
  1.1745 +
  1.1746 +Full Copyright Statement
  1.1747 +
  1.1748 +   Copyright (C) The IETF Trust (2007).
  1.1749 +
  1.1750 +   This document is subject to the rights, licenses and restrictions
  1.1751 +   contained in BCP 78, and except as set forth therein, the authors
  1.1752 +   retain all their rights.
  1.1753 +
  1.1754 +   This document and the information contained herein are provided on an
  1.1755 +   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
  1.1756 +   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
  1.1757 +   THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
  1.1758 +   OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
  1.1759 +   THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
  1.1760 +   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
  1.1761 +
  1.1762 +Intellectual Property
  1.1763 +
  1.1764 +   The IETF takes no position regarding the validity or scope of any
  1.1765 +   Intellectual Property Rights or other rights that might be claimed to
  1.1766 +   pertain to the implementation or use of the technology described in
  1.1767 +   this document or the extent to which any license under such rights
  1.1768 +   might or might not be available; nor does it represent that it has
  1.1769 +   made any independent effort to identify any such rights.  Information
  1.1770 +   on the procedures with respect to rights in RFC documents can be
  1.1771 +   found in BCP 78 and BCP 79.
  1.1772 +
  1.1773 +   Copies of IPR disclosures made to the IETF Secretariat and any
  1.1774 +   assurances of licenses to be made available, or the result of an
  1.1775 +   attempt made to obtain a general license or permission for the use of
  1.1776 +   such proprietary rights by implementers or users of this
  1.1777 +   specification can be obtained from the IETF on-line IPR repository at
  1.1778 +   http://www.ietf.org/ipr.
  1.1779 +
  1.1780 +   The IETF invites any interested party to bring to its attention any
  1.1781 +   copyrights, patents or patent applications, or other proprietary
  1.1782 +   rights that may cover technology that may be required to implement
  1.1783 +   this standard.  Please address the information to the IETF at
  1.1784 +   ietf-ipr@ietf.org.
  1.1785 +
  1.1786 +
  1.1787 +
  1.1788 +
  1.1789 +
  1.1790 +
  1.1791 +
  1.1792 +
  1.1793 +
  1.1794 +
  1.1795 +
  1.1796 +
  1.1797 +Melnikov & Newman           Standards Track                    [Page 32]
  1.1798 +