imapext-2007
view docs/rfc/rfc5092.txt @ 0:ada5e610ab86
imap-2007e
| author | yuuji@gentei.org |
|---|---|
| date | Mon, 14 Sep 2009 15:17:45 +0900 |
| parents | |
| children |
line source
7 Network Working Group A. Melnikov, Ed.
8 Request for Comments: 5092 Isode Ltd.
9 Obsoletes: 2192 C. Newman
10 Updates: 4467 Sun Microsystems
11 Category: Standards Track November 2007
14 IMAP URL Scheme
16 Status of This Memo
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.
24 Abstract
26 IMAP (RFC 3501) is a rich protocol for accessing remote message
27 stores. It provides an ideal mechanism for accessing public mailing
28 list archives as well as private and shared message stores. This
29 document defines a URL scheme for referencing objects on an IMAP
30 server.
32 This document obsoletes RFC 2192. It also updates RFC 4467.
58 Melnikov & Newman Standards Track [Page 1]
60 RFC 5092 IMAP URL Scheme November 2007
63 Table of Contents
65 1. Introduction ....................................................2
66 2. Conventions Used in This Document ...............................3
67 3. IMAP userinfo Component (iuserinfo) .............................4
68 3.1. IMAP Mailbox Naming Scope ..................................4
69 3.2. IMAP User Name and Authentication Mechanism ................4
70 3.3. Limitations of enc-user ....................................6
71 4. IMAP Server .....................................................7
72 5. Lists of Messages ...............................................7
73 6. A Specific Message or Message Part ..............................8
74 6.1. URLAUTH Authorized URL .....................................9
75 6.1.1. Concepts ............................................9
76 6.1.1.1. URLAUTH ....................................9
77 6.1.1.2. Mailbox Access Key .........................9
78 6.1.1.3. Authorized Access Identifier ...............9
79 6.1.1.4. Authorization Mechanism ...................10
80 6.1.1.5. Authorization Token .......................10
81 6.1.2. URLAUTH Extensions to IMAP URL .....................10
82 7. Relative IMAP URLs .............................................11
83 7.1. absolute-path References ..................................12
84 7.2. relative-path References ..................................12
85 8. Internationalization Considerations ............................13
86 9. Examples .......................................................13
87 9.1. Examples of Relative URLs .................................16
88 10. Security Considerations .......................................16
89 10.1. Security Considerations Specific to URLAUTH Authorized
90 URL ......................................................17
91 11. ABNF for IMAP URL Scheme ......................................17
92 12. IANA Considerations ...........................................21
93 12.1. IANA Registration of imap: URI Scheme ....................21
94 13. References ....................................................22
95 13.1. Normative References .....................................22
96 13.2. Informative References ...................................23
97 Appendix A. Sample Code............................................24
98 Appendix B. List of Changes since RFC 2192.........................30
99 Appendix C. List of Changes since RFC 4467.........................31
100 Appendix D. Acknowledgments........................................31
102 1. Introduction
104 The IMAP URL scheme is used to designate IMAP servers, mailboxes,
105 messages, MIME bodies [MIME], and search programs on Internet hosts
106 accessible using the IMAP protocol over TCP.
108 The IMAP URL follows the common Internet scheme syntax as defined in
109 [URI-GEN]. If :<port> is omitted, the port defaults to 143 (as
110 defined in Section 2.1 of [IMAP4]).
114 Melnikov & Newman Standards Track [Page 2]
116 RFC 5092 IMAP URL Scheme November 2007
119 An absolute IMAP URL takes one of the following forms:
121 imap://<iserver>[/]
123 imap://<iserver>/<enc-mailbox>[<uidvalidity>][?<enc-search>]
125 imap://<iserver>/<enc-mailbox>[<uidvalidity>]<iuid>
126 [<isection>][<ipartial>][<iurlauth>]
128 The first form is used to refer to an IMAP server (see Section 4),
129 the second form refers to the contents of a mailbox or a set of
130 messages resulting from a search (see Section 5), and the final form
131 refers to a specific message or message part, and possibly a byte
132 range in that part (see Section 6). If [URLAUTH] extension is
133 supported, then the final form can have the <iurlauth> component (see
134 Section 6.1 for more details).
136 The <iserver> component common to all types of absolute IMAP URLs has
137 the following syntax expressed in ABNF [ABNF]:
139 [iuserinfo "@"] host [ ":" port ]
141 The <iserver> component is the same as "authority" defined in
142 [URI-GEN]. The syntax and uses of the <iuserinfo> ("IMAP userinfo
143 component") are described in detail in Section 3. The syntax of
144 <host> and <port> is described in [URI-GEN].
146 2. Conventions Used in This Document
148 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
149 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
150 document are to be interpreted as described in RFC 2119 [KEYWORDS].
152 This document references many productions from [URI-GEN]. When the
153 document needs to emphasize IMAP URI-specific differences from [URI-
154 GEN] (i.e., for parts of IMAP URIs that have more restricted syntax
155 than generic URIs), it uses a non-terminal i<foo> to define an IMAP-
156 specific version of the non-terminal <foo> from [URI-GEN].
158 Note that the ABNF syntax shown in Section 11 is normative. Sections
159 2-6 may use a less formal syntax that does not necessarily match the
160 normative ABNF shown in Section 11. If there are any differences
161 between the syntax shown in Sections 2-6 and Section 11, then the
162 syntax shown in Section 11 must be treated as authoritative. Non-
163 syntax requirements included in Sections 2-6 are, of course,
164 normative.
170 Melnikov & Newman Standards Track [Page 3]
172 RFC 5092 IMAP URL Scheme November 2007
175 3. IMAP userinfo Component (iuserinfo)
177 The <iuserinfo> component conforms to the generic syntax of
178 <userinfo> defined in [URI-GEN]. It has the following syntax
179 expressed in ABNF [ABNF]:
181 enc-user [iauth] / [enc-user] iauth
183 The meaning of the different parts is described in subsections of
184 this section.
186 3.1. IMAP Mailbox Naming Scope
188 The "enc-user" part of the "iuserinfo" component, if present, denotes
189 mailbox naming scope. If it is absent, the IMAP URL can only
190 reference mailboxes with globally unique names, i.e., mailboxes with
191 names that don't change depending on the user the client
192 authenticated as to the IMAP server. Note that not all IMAP
193 implementations support globally unique names.
195 For example, a personal mailbox described by the following URL
196 <imap://michael@example.org/INBOX> is most likely different from a
197 personal mailbox described by <imap://bester@example.org/INBOX>, even
198 though both URLs use the same mailbox name.
200 3.2. IMAP User Name and Authentication Mechanism
202 The userinfo component (see [URI-GEN]) of an IMAP URI may contain an
203 IMAP user name (a.k.a. authorization identity [SASL], "enc-user")
204 and/or an authentication mechanism. (Note that the "enc-user" also
205 defines a mailbox naming scope as described in Section 3.1). The
206 IMAP user name and the authentication mechanism are used in the
207 "LOGIN" or "AUTHENTICATE" commands after making the connection to the
208 IMAP server.
210 If no user name and no authentication mechanism are supplied, the
211 client MUST authenticate as anonymous to the server. If the server
212 advertises AUTH=ANONYMOUS IMAP capability, the client MUST use the
213 AUTHENTICATE command with ANONYMOUS [ANONYMOUS] SASL mechanism. If
214 SASL ANONYMOUS is not available, the (case-insensitive) user name
215 "anonymous" is used with the "LOGIN" command and the Internet email
216 address of the end user accessing the resource is supplied as the
217 password. The latter option is given in order to provide for
218 interoperability with deployed servers.
220 Note that, as described in RFC 3501, the "LOGIN" command MUST NOT be
221 used when the IMAP server advertises the LOGINDISABLED capability.
226 Melnikov & Newman Standards Track [Page 4]
228 RFC 5092 IMAP URL Scheme November 2007
231 An authentication mechanism (as used by the IMAP AUTHENTICATE
232 command) can be expressed by adding ";AUTH=<enc-auth-type>" to the
233 end of the user name in an IMAP URL. When such an <enc-auth-type> is
234 indicated, the client SHOULD request appropriate credentials from
235 that mechanism and use the "AUTHENTICATE" command instead of the
236 "LOGIN" command. If no user name is specified, one MUST be obtained
237 from the mechanism or requested from the user/configuration as
238 appropriate.
240 The string ";AUTH=*" indicates that the client SHOULD select an
241 appropriate authentication mechanism. (Though the '*' character in
242 this usage is not strictly a delimiter, it is being treated like a
243 sub-delim [URI-GEN] in this instance. It MUST NOT be percent-encoded
244 in this usage, as ";AUTH=%2A" will not match this production.) It
245 MAY use any mechanism listed in the response to the CAPABILITY
246 command (or CAPABILITY response code) or use an out-of-band security
247 service resulting in a PREAUTH connection. If no user name is
248 specified and no appropriate authentication mechanisms are available,
249 the client SHOULD fall back to anonymous login as described above.
250 The behavior prescribed in this section allows a URL that grants
251 read-write access to authorized users and read-only anonymous access
252 to other users.
254 If a user name is included with no authentication mechanism, then
255 ";AUTH=*" is assumed.
257 Clients must take care when resolving a URL that requires or requests
258 any sort of authentication, since URLs can easily come from untrusted
259 sources. Supplying authentication credentials to the wrong server
260 may compromise the security of the user's account; therefore, the
261 program resolving the URL should meet at least one of the following
262 criteria in this case:
264 1) The URL comes from a trusted source, such as a referral server
265 that the client has validated and trusts according to site policy.
266 Note that user entry of the URL may or may not count as a trusted
267 source, depending on the experience level of the user and site
268 policy.
270 2) Explicit local site policy permits the client to connect to the
271 server in the URL. For example, a company example.com may have a
272 site policy to trust all IMAP server names ending in example.com,
273 whereas such a policy would be unwise for example.edu where random
274 students can set up IMAP servers.
276 3) The user confirms that connecting to that domain name with the
277 specified credentials and/or mechanism is permitted. For example,
278 when using "LOGIN" or SASL PLAIN with Transport Layer Security
282 Melnikov & Newman Standards Track [Page 5]
284 RFC 5092 IMAP URL Scheme November 2007
287 (TLS), the IMAP URL client presents a dialog box "Is it OK to send
288 your password to server "example.com"? Please be aware the owners
289 of example.com will be able to reuse your password to connect to
290 other servers on your behalf".
292 4) A mechanism is used that validates the server before passing
293 potentially compromising client credentials. For example, a site
294 has a designated TLS certificate used to certify site-trusted IMAP
295 server certificates, and this has been configured explicitly into
296 the IMAP URL client. Another example is use of a Simple
297 Authentication and Security Layer (SASL) mechanism such as
298 DIGEST-MD5 [DIGEST-MD5], which supports mutual authentication.
300 5) An authentication mechanism is used that will not reveal any
301 information to the server that could be used to compromise future
302 connections. Examples are SASL ANONYMOUS [ANONYMOUS] or GSSAPI
303 [GSSAPI].
305 URLs that do not include a user name but include an authentication
306 mechanism (";AUTH=<mech>") must be treated with extra care, since for
307 some <mech>s they are more likely to compromise the user's primary
308 account. A URL containing ";AUTH=*" must also be treated with extra
309 care since it might fall back on a weaker security mechanism.
310 Finally, clients are discouraged from using a plaintext password as a
311 fallback with ";AUTH=*" unless the connection has strong encryption.
313 A program interpreting IMAP URLs MAY cache open connections to an
314 IMAP server for later reuse. If a URL contains a user name, only
315 connections authenticated as that user may be reused. If a URL does
316 not contain a user name or authentication mechanism, then only an
317 anonymous connection may be reused.
319 Note that if unsafe or reserved characters such as " " (space) or ";"
320 are present in the user name or authentication mechanism, they MUST
321 be percent-encoded as described in [URI-GEN].
323 3.3. Limitations of enc-user
325 As per Sections 3.1 and 3.2 of this document, the IMAP URI enc-user
326 has two purposes:
328 1) It provides context for user-specific mailbox paths such as
329 "INBOX" (Section 3.1).
331 2) It specifies that resolution of the URL requires logging in as
332 that user and limits use of that URL to only that user (Section
333 3.2).
338 Melnikov & Newman Standards Track [Page 6]
340 RFC 5092 IMAP URL Scheme November 2007
343 An obvious limitation of using the same field for both purposes is
344 that the URL can be resolved only by the mailbox owner. In order to
345 avoid this restriction, implementations should use globally unique
346 mailbox names (see Section 3.1) whenever possible.
348 Note: There is currently no general way in IMAP of learning a
349 globally unique name for a mailbox. However, by looking at the
350 NAMESPACE [NAMESPACE] command result, it is possible to determine
351 whether or not a mailbox name is globally unique.
353 The URLAUTH component overrides the second purpose of the enc-user in
354 the IMAP URI and by default permits the URI to be resolved by any
355 user permitted by the <access> identifier. URLAUTH and <access>
356 identifier are described in Section 6.1.
358 4. IMAP Server
360 An IMAP URL referring to an IMAP server has the following form:
362 imap://<iserver>[/]
364 This URL type is frequently used to describe a location of an IMAP
365 server, both in referrals and in configuration. It may optionally
366 contain the <iuserinfo> component (see Sections 3 and 11). A program
367 interpreting this URL would issue the standard set of commands it
368 uses to present a view of the content of the IMAP server, as visible
369 to the user described by the "enc-user" part of the <iuserinfo>
370 component, if the "enc-user" part is specified.
372 5. Lists of Messages
374 An IMAP URL referring to a list of messages has the following form:
376 imap://<iserver>/<enc-mailbox>[<uidvalidity>][?<enc-search>]
378 The <enc-mailbox> field is used as the argument to the IMAP4 "SELECT"
379 or "EXAMINE" command. Note that if unsafe or reserved characters
380 such as " " (space), ";", or "?" are present in <enc-mailbox>, they
381 MUST be percent-encoded as described in [URI-GEN].
383 The <uidvalidity> field is optional. If it is present, it MUST be
384 the same as the value of IMAP4 UIDVALIDITY response code at the time
385 the URL was created. This MUST be used by the program interpreting
386 the IMAP URL to determine if the URL is stale. If the IMAP URL is
387 stale, then the program should behave as if the corresponding mailbox
388 doesn't exist.
394 Melnikov & Newman Standards Track [Page 7]
396 RFC 5092 IMAP URL Scheme November 2007
399 Note that the <uidvalidity> field is a modifier to the <enc-mailbox>,
400 i.e., it is considered a part of the last "component" (as used in
401 [URI-GEN]) of the <enc-mailbox>. This is significant during relative
402 URI resolution.
404 The "?<enc-search>" field is optional. If it is not present, the
405 program interpreting the URL will present the entire content of the
406 mailbox.
408 If the "?<enc-search>" field is present, the program interpreting the
409 URL should use the contents of this field as arguments following an
410 IMAP4 SEARCH command. These arguments are likely to contain unsafe
411 characters such as " " (space) (which are likely to be present in the
412 <enc-search>). If unsafe characters are present, they MUST be
413 percent-encoded as described in [URI-GEN].
415 Note that quoted strings and non-synchronizing literals [LITERAL+]
416 are allowed in the <enc-search> content; however, synchronizing
417 literals are not allowed, as their presence would effectively mean
418 that the agent interpreting IMAP URLs needs to parse an <enc-search>
419 content, find all synchronizing literals, and perform proper command
420 continuation request handling (see Sections 4.3 and 7 of [IMAP4]).
422 6. A Specific Message or Message Part
424 An IMAP URL referring to a specific message or message part has the
425 following form:
427 imap://<iserver>/<enc-mailbox>[<uidvalidity>]<iuid>
428 [<isection>][<ipartial>][<iurlauth>]
430 The <enc-mailbox> and [uidvalidity] are as defined in Section 5
431 above.
433 If <uidvalidity> is present in this form, it SHOULD be used by the
434 program interpreting the URL to determine if the URL is stale.
436 The <iuid> refers to an IMAP4 message Unique Identifier (UID), and it
437 SHOULD be used as the <set> argument to the IMAP4 "UID FETCH"
438 command.
440 The <isection> field is optional. If not present, the URL refers to
441 the entire Internet message as returned by the IMAP command "UID
442 FETCH <uid> BODY.PEEK[]". If present, the URL refers to the object
443 returned by a "UID FETCH <uid> BODY.PEEK[<section>]" command. The
444 type of the object may be determined by using a "UID FETCH <uid>
445 BODYSTRUCTURE" command and locating the appropriate part in the
450 Melnikov & Newman Standards Track [Page 8]
452 RFC 5092 IMAP URL Scheme November 2007
455 resulting BODYSTRUCTURE. Note that unsafe characters in [isection]
456 MUST be percent-encoded as described in [URI-GEN].
458 The <ipartial> field is optional. If present, it effectively appends
459 "<<partial-range>>" to the end of the UID FETCH BODY.PEEK[<section>]
460 command constructed as described in the previous paragraph. In other
461 words, it allows the client to request a byte range of the
462 message/message part.
464 The <iurlauth> field is described in detail in Section 6.1.
466 6.1. URLAUTH Authorized URL
468 URLAUTH authorized URLs are only supported by an IMAP server
469 advertising the URLAUTH IMAP capability [URLAUTH].
471 6.1.1. Concepts
473 6.1.1.1. URLAUTH
475 URLAUTH is a component, appended at the end of a URL, that conveys
476 authorization to access the data addressed by that URL. It contains
477 an authorized access identifier, an authorization mechanism name, and
478 an authorization token. The authorization token is generated from
479 the URL, the authorized access identifier, authorization mechanism
480 name, and a mailbox access key.
482 Note: This specification only allows for the URLAUTH component in
483 IMAP URLs describing a message or its part.
485 6.1.1.2. Mailbox Access Key
487 The mailbox access key is an unpredictable, random string. To ensure
488 unpredictability, the random string with at least 128 bits of entropy
489 is generated by software or hardware (not by the human user).
491 Each user has a table of mailboxes and an associated mailbox access
492 key for each mailbox. Consequently, the mailbox access key is per-
493 user and per-mailbox. In other words, two users sharing the same
494 mailbox each have a different mailbox access key for that mailbox,
495 and each mailbox accessed by a single user also has a different
496 mailbox access key.
498 6.1.1.3. Authorized Access Identifier
500 The authorized <access> identifier restricts use of the URLAUTH
501 authorized URL to certain users authorized on the server, as
502 described in Section 6.1.2.
506 Melnikov & Newman Standards Track [Page 9]
508 RFC 5092 IMAP URL Scheme November 2007
511 6.1.1.4. Authorization Mechanism
513 The authorization mechanism is the algorithm by which the URLAUTH is
514 generated and subsequently verified, using the mailbox access key.
516 6.1.1.5. Authorization Token
518 The authorization token is a deterministic string of at least 128
519 bits that an entity with knowledge of the secret mailbox access key
520 and URL authorization mechanism can use to verify the URL.
522 6.1.2. URLAUTH Extensions to IMAP URL
524 A specific message or message part IMAP URL can optionally contain
525 ";EXPIRE=<datetime>" and/or ";URLAUTH=<access>:<mech>:<token>".
527 When ";EXPIRE=<datetime>" is used, this indicates the latest date and
528 time that the URL is valid. After that date and time, the URL has
529 expired and server implementations MUST reject the URL. If
530 ";EXPIRE=<datetime>" is not used, the URL has no expiration, but can
531 still be revoked using the RESETKEY command [URLAUTH].
533 The URLAUTH takes the form ";URLAUTH=<access>:<mech>:<token>", and it
534 MUST be at the end of the URL. It is composed of three parts. The
535 <access> portion provides the authorized access identifiers that may
536 constrain the operations and users that are permitted to use this
537 URL. The <mech> portion provides the authorization mechanism used by
538 the IMAP server to generate the authorization token that follows.
539 The <token> portion provides the authorization token, which can be
540 generated using the GENURLAUTH command [URLAUTH].
542 The "submit+" <access> identifier prefix, followed by a userid,
543 indicates that only a userid authorized as a message submission
544 entity on behalf of the specified userid is permitted to use this
545 URL. The IMAP server does not validate the specified userid but does
546 validate that the IMAP session has an authorization identity that is
547 authorized as a message submission entity. The authorized message
548 submission entity MUST validate the userid prior to contacting the
549 IMAP server.
551 The "user+" <access> identifier prefix, followed by a userid,
552 indicates that use of this URL is limited to IMAP sessions that are
553 logged in as the specified userid (that is, have authorization
554 identity as that userid).
556 Note: If a SASL mechanism that provides both authorization and
557 authentication identifiers is used to authenticate to the IMAP
558 server, the "user+" <access> identifier MUST match the
562 Melnikov & Newman Standards Track [Page 10]
564 RFC 5092 IMAP URL Scheme November 2007
567 authorization identifier. If the SASL mechanism can't transport
568 the authorization identifier, the "user+" <access> identifier MUST
569 match the authorization identifier derived from the authentication
570 identifier (see [SASL]).
572 The "authuser" <access> identifier indicates that use of this URL is
573 limited to authenticated IMAP sessions that are logged in as any
574 non-anonymous user (that is, have authorization identity as a non-
575 anonymous user) of that IMAP server. To restate this: use of this
576 type of URL is prohibited to anonymous IMAP sessions, i.e., any
577 URLFETCH command containing this type of URL issued in an anonymous
578 session MUST return NIL in the URLFETCH response.
580 The "anonymous" <access> identifier indicates that use of this URL is
581 not restricted by session authorization identity; that is, any IMAP
582 session in authenticated or selected state (as defined in [IMAP4]),
583 including anonymous sessions, may issue a URLFETCH [URLAUTH] using
584 this URL.
586 The authorization token is represented as an ASCII-encoded
587 hexadecimal string, which is used to authorize the URL. The length
588 and the calculation of the authorization token depend upon the
589 mechanism used, but in all cases, the authorization token is at least
590 128 bits (and therefore at least 32 hexadecimal digits).
592 Example:
594 <imap://joe@example.com/INBOX/;uid=20/;section=1.2;urlauth=
595 submit+fred:internal:91354a473744909de610943775f92038>
597 7. Relative IMAP URLs
599 Relative IMAP URLs are permitted and are resolved according to the
600 rules defined in [URI-GEN]. In particular, in IMAP URLs parameters
601 (such as ";uid=" or ";section=") are treated as part of the normal
602 path with respect to relative URL resolution.
604 [URI-GEN] defines four forms of relative URLs: <inetwork-path>,
605 <iabsolute-path>, <irelative-path>, and <ipath-empty>. Their syntax
606 is defined in Section 11.
608 A relative reference that begins with two slash characters is termed
609 a network-path reference (<inetwork-path>); such references are
610 rarely used, because in most cases they can be replaced with an
611 equivalent absolute URL. A relative reference that begins with a
612 single slash character is termed an absolute-path reference
613 (<iabsolute-path>; see also Section 7.1). A relative reference that
614 does not begin with a slash character is termed a relative-path
618 Melnikov & Newman Standards Track [Page 11]
620 RFC 5092 IMAP URL Scheme November 2007
623 reference (<irelative-path>; see also Section 7.2). The final form
624 is <ipath-empty>, which is "same-document reference" (see Section 4.4
625 of [URI-GEN]).
627 The following observations about relative URLs are important:
629 The <iauth> grammar element (which is a part of <iuserinfo>, which
630 is, in turn, a part of <iserver>; see Section 3) is considered part
631 of the user name for purposes of resolving relative IMAP URLs. This
632 means that unless a new user name/server specification is included in
633 the relative URL, the authentication mechanism is inherited from the
634 base IMAP URL.
636 URLs always use "/" as the hierarchy delimiter for the purpose of
637 resolving paths in relative URLs. IMAP4 permits the use of any
638 hierarchy delimiter in mailbox names. For this reason, relative
639 mailbox paths will only work if the mailbox uses "/" as the hierarchy
640 delimiter. Relative URLs may be used on mailboxes that use other
641 delimiters, but in that case, the entire mailbox name MUST be
642 specified in the relative URL or inherited as a whole from the base
643 URL.
645 If an IMAP server allows for mailbox names starting with "./" or
646 "../", ending with "/." or "/..", or containing sequences "/../" or
647 "/./", then such mailbox names MUST be percent-encoded as described
648 in [URI-GEN]. Otherwise, they would be misinterpreted as dot-
649 segments (see Section 3.3 of [URI-GEN]), which are processed
650 specially during the relative path resolution process.
652 7.1. absolute-path References
654 A relative reference that begins with a single slash character is
655 termed an absolute-path reference (see Section 4.2 of [URI-GEN]). If
656 an IMAP server permits mailbox names with a leading "/", then the
657 leading "/" MUST be percent-encoded as described in [URI-GEN].
658 Otherwise, the produced absolute-path reference URI will be
659 misinterpreted as a network-path reference [URI-GEN] described by the
660 <inetwork-path> non-terminal.
662 7.2. relative-path References
664 A relative reference that does not begin with a slash character is
665 termed a relative-path reference [URI-GEN]. Implementations MUST NOT
666 generate or accept relative-path IMAP references.
668 See also Section 4.2 of [URI-GEN] for restrictions on relative-path
669 references.
674 Melnikov & Newman Standards Track [Page 12]
676 RFC 5092 IMAP URL Scheme November 2007
679 8. Internationalization Considerations
681 IMAP4, Section 5.1.3 [IMAP4] includes a convention for encoding non-
682 US-ASCII characters in IMAP mailbox names. Because this convention
683 is private to IMAP, it is necessary to convert IMAP's encoding to one
684 that can be more easily interpreted by a URL display program. For
685 this reason, IMAP's modified UTF-7 encoding for mailboxes MUST be
686 converted to UTF-8 [UTF-8]. Since 8-bit octets are not permitted in
687 URLs, the UTF-8 octets are percent-encoded as required by the URL
688 specification [URI-GEN], Section 2.1. Sample code is included in
689 Appendix A to demonstrate this conversion.
691 IMAP user names are UTF-8 strings and MUST be percent-encoded as
692 required by the URL specification [URI-GEN], Section 2.1.
694 Also note that IMAP SEARCH criteria can contain non-US-ASCII
695 characters. 8-bit octets in those strings MUST be percent-encoded as
696 required by the URL specification [URI-GEN], Section 2.1.
698 9. Examples
700 The following examples demonstrate how an IMAP4 client program might
701 translate various IMAP4 URLs into a series of IMAP4 commands.
702 Commands sent from the client to the server are prefixed with "C:",
703 and responses sent from the server to the client are prefixed with
704 "S:".
706 The URL:
708 <imap://minbari.example.org/gray-council;UIDVALIDITY=385759045/;
709 UID=20/;PARTIAL=0.1024>
711 may result in the following client commands and server responses:
713 <connect to minbari.example.org, port 143>
714 S: * OK [CAPABILITY IMAP4rev1 STARTTLS AUTH=ANONYMOUS] Welcome
715 C: A001 AUTHENTICATE ANONYMOUS
716 S: +
717 C: c2hlcmlkYW5AYmFieWxvbjUuZXhhbXBsZS5vcmc=
718 S: A001 OK Welcome sheridan@babylon5.example.org
719 C: A002 SELECT gray-council
720 <client verifies the UIDVALIDITY matches>
721 C: A003 UID FETCH 20 BODY.PEEK[]<0.1024>
723 The URL:
725 <imap://psicorp.example.org/~peter/%E6%97%A5%E6%9C%AC%E8%AA%9E/
726 %E5%8F%B0%E5%8C%97>
730 Melnikov & Newman Standards Track [Page 13]
732 RFC 5092 IMAP URL Scheme November 2007
735 may result in the following client commands:
737 <connect to psicorp.example.org, port 143>
738 S: * OK [CAPABILITY IMAP4rev1 STARTTLS AUTH=CRAM-MD5] Welcome
739 C: A001 LOGIN ANONYMOUS bester@psycop.psicorp.example.org
740 C: A002 SELECT ~peter/&ZeVnLIqe-/&U,BTFw-
741 <commands the client uses for viewing the contents of
742 the mailbox>
744 The URL:
746 <imap://;AUTH=GSSAPI@minbari.example.org/gray-council/;uid=20/
747 ;section=1.2>
749 may result in the following client commands:
751 <connect to minbari.example.org, port 143>
752 S: * OK Greetings
753 C: A000 CAPABILITY
754 S: * CAPABILITY IMAP4rev1 STARTTLS AUTH=GSSAPI
755 S: A000 OK
756 C: A001 AUTHENTICATE GSSAPI
757 <authentication exchange>
758 C: A002 SELECT gray-council
759 C: A003 UID FETCH 20 BODY.PEEK[1.2]
761 If the following relative URL is located in that body part:
763 <;section=1.4>
765 this could result in the following client commands:
767 C: A004 UID FETCH 20 (BODY.PEEK[1.2.MIME]
768 BODY.PEEK[1.MIME]
769 BODY.PEEK[HEADER.FIELDS (Content-Location)])
770 <Client looks for Content-Location headers in
771 result. If no such headers, then it does the following>
772 C: A005 UID FETCH 20 BODY.PEEK[1.4]
774 The URL:
776 <imap://;AUTH=*@minbari.example.org/gray%20council?
777 SUBJECT%20shadows>
786 Melnikov & Newman Standards Track [Page 14]
788 RFC 5092 IMAP URL Scheme November 2007
791 could result in the following:
793 <connect to minbari.example.org, port 143>
794 S: * OK Welcome
795 C: A001 CAPABILITY
796 S: * CAPABILITY IMAP4rev1 AUTH=DIGEST-MD5
797 S: A001 OK
798 C: A002 AUTHENTICATE DIGEST-MD5
799 <authentication exchange>
800 S: A002 OK user lennier authenticated
801 C: A003 SELECT "gray council"
802 ...
803 C: A004 SEARCH SUBJECT shadows
804 S: * SEARCH 8 10 13 14 15 16
805 S: A004 OK SEARCH completed
806 C: A005 FETCH 8,10,13:16 ALL
807 ...
809 In the example above, the client has implementation-dependent
810 choices. The authentication mechanism could be anything, including
811 PREAUTH. The final FETCH command could fetch more or less
812 information about the messages, depending on what it wishes to
813 display to the user.
815 The URL:
817 <imap://john;AUTH=*@minbari.example.org/babylon5/personel?
818 charset%20UTF-8%20SUBJECT%20%7B14+%7D%0D%0A%D0%98%D0%B2%
819 D0%B0%D0%BD%D0%BE%D0%B2%D0%B0>
821 shows that 8-bit data can be sent using non-synchronizing literals
822 [LITERAL+]. This could result in the following:
824 <connect to minbari.example.org, port 143>
825 S: * OK Hi there
826 C: A001 CAPABILITY
827 S: * CAPABILITY IMAP4rev1 LITERAL+ AUTH=DIGEST-MD5
828 S: A001 OK
829 C: A002 AUTHENTICATE DIGEST-MD5
830 <authentication exchange>
831 S: A002 OK user john authenticated
832 C: A003 SELECT babylon5/personel
833 ...
834 C: A004 SEARCH CHARSET UTF-8 SUBJECT {14+}
835 C: XXXXXXXXXXXXXX
836 S: * SEARCH 7 10 12
837 S: A004 OK SEARCH completed
838 C: A005 FETCH 7,10,12 ALL
842 Melnikov & Newman Standards Track [Page 15]
844 RFC 5092 IMAP URL Scheme November 2007
847 ...
849 where XXXXXXXXXXXXXX is 14 bytes of UTF-8 encoded data as specified
850 in the URL above.
852 9.1. Examples of Relative URLs
854 The following absolute-path reference
856 </foo/;UID=20/..>
858 is the same as
860 </foo>
862 That is, both of them reference the mailbox "foo" located on the IMAP
863 server described by the corresponding Base URI.
865 The following relative-path reference
867 <;UID=20>
869 references a message with UID in the mailbox specified by the Base
870 URI.
872 The following edge case example demonstrates that the ;UIDVALIDITY=
873 modifier is a part of the mailbox name as far as relative URI
874 resolution is concerned:
876 <..;UIDVALIDITY=385759045/;UID=20>
878 In this example, ".." is not a dot-segment [URI-GEN].
880 10. Security Considerations
882 Security considerations discussed in the IMAP specification [IMAP4]
883 and the URI specification [URI-GEN] are relevant. Security
884 considerations related to authenticated URLs are discussed in Section
885 3.2 of this document.
887 Many email clients store the plaintext password for later use after
888 logging into an IMAP server. Such clients MUST NOT use a stored
889 password in response to an IMAP URL without explicit permission from
890 the user to supply that password to the specified host name.
892 Clients resolving IMAP URLs that wish to achieve data confidentiality
893 and/or integrity SHOULD use the STARTTLS command (if supported by the
898 Melnikov & Newman Standards Track [Page 16]
900 RFC 5092 IMAP URL Scheme November 2007
903 server) before starting authentication, or use a SASL mechanism, such
904 as GSSAPI, that provides a confidentiality security layer.
906 10.1. Security Consideration Specific to URLAUTH Authorized URL
908 The "user+<userid>" <access> identifier limits resolution of that URL
909 to a particular userid, whereas the "submit+<userid>" <access>
910 identifier is more general and simply requires that the session be
911 authorized by a user that has been granted a "submit" role within the
912 authentication system. Use of either of these mechanisms limits the
913 scope of the URL. An attacker who cannot authenticate using the
914 appropriate credentials cannot make use of the URL.
916 The "authuser" and "anonymous" <access> identifiers do not have this
917 level of protection. These access identifiers are primarily useful
918 for public export of data from an IMAP server, without requiring that
919 it be copied to a web or anonymous FTP server.
921 The decision to use the "authuser" <access> identifier should be made
922 with caution. An "authuser" <access> identifier can be used by any
923 authorized user of the IMAP server; therefore, use of this access
924 identifier should be limited to content that may be disclosed to any
925 authorized user of the IMAP server.
927 The decision to use the "anonymous" <access> identifier should be
928 made with extreme caution. An "anonymous" <access> identifier can be
929 used by anyone; therefore, use of this access identifier should be
930 limited to content that may be disclosed to anyone.
932 11. ABNF for IMAP URL Scheme
934 Formal syntax is defined using ABNF [ABNF], extending the ABNF rules
935 in Section 9 of [IMAP4]. Elements not defined here can be found in
936 [ABNF], [IMAP4], [IMAPABNF], or [URI-GEN]. Strings are not case
937 sensitive, and free insertion of linear white space is not permitted.
939 sub-delims-sh = "!" / "$" / "'" / "(" / ")" /
940 "*" / "+" / ","
941 ;; Same as [URI-GEN] sub-delims,
942 ;; but without ";", "&" and "=".
944 uchar = unreserved / sub-delims-sh / pct-encoded
946 achar = uchar / "&" / "="
947 ;; Same as [URI-GEN] 'unreserved / sub-delims /
948 ;; pct-encoded', but ";" is disallowed.
950 bchar = achar / ":" / "@" / "/"
954 Melnikov & Newman Standards Track [Page 17]
956 RFC 5092 IMAP URL Scheme November 2007
959 enc-auth-type = 1*achar
960 ; %-encoded version of [IMAP4] "auth-type"
962 enc-mailbox = 1*bchar
963 ; %-encoded version of [IMAP4] "mailbox"
965 enc-search = 1*bchar
966 ; %-encoded version of [IMAPABNF]
967 ; "search-program". Note that IMAP4
968 ; literals may not be used in
969 ; a "search-program", i.e., only
970 ; quoted or non-synchronizing
971 ; literals (if the server supports
972 ; LITERAL+ [LITERAL+]) are allowed.
974 enc-section = 1*bchar
975 ; %-encoded version of [IMAP4] "section-spec"
977 enc-user = 1*achar
978 ; %-encoded version of [IMAP4] authorization
979 ; identity or "userid".
981 imapurl = "imap://" iserver ipath-query
982 ; Defines an absolute IMAP URL
984 ipath-query = ["/" [ icommand ]]
985 ; Corresponds to "path-abempty [ "?" query ]"
986 ; in [URI-GEN]
988 Generic syntax for relative URLs is defined in Section 4.2 of
989 [URI-GEN]. For ease of implementation, the relative IMAP URL syntax
990 is defined below:
992 imapurl-rel = inetwork-path
994 / iabsolute-path
995 / irelative-path
996 / ipath-empty
998 inetwork-path = "//" iserver ipath-query
999 ; Corresponds to '"//" authority path-abempty
1000 ; [ "?" query ]' in [URI-GEN]
1002 iabsolute-path = "/" [ icommand ]
1003 ; icommand, if present, MUST NOT start with '/'.
1004 ;
1005 ; Corresponds to 'path-absolute [ "?" query ]'
1006 ; in [URI-GEN]
1010 Melnikov & Newman Standards Track [Page 18]
1012 RFC 5092 IMAP URL Scheme November 2007
1015 irelative-path = imessagelist /
1016 imsg-or-part
1017 ; Corresponds to 'path-noscheme [ "?" query ]'
1018 ; in [URI-GEN]
1020 imsg-or-part = ( imailbox-ref "/" iuid-only ["/" isection-only]
1021 ["/" ipartial-only] ) /
1022 ( iuid-only ["/" isection-only]
1023 ["/" ipartial-only] ) /
1024 ( isection-only ["/" ipartial-only] ) /
1025 ipartial-only
1027 ipath-empty = 0<pchar>
1028 ; Zero characters.
1029 ; The same-document reference.
1031 The following three rules are only used in the presence of the IMAP
1032 [URLAUTH] extension:
1034 authimapurl = "imap://" iserver "/" imessagepart
1035 ; Same as "imapurl" when "[icommand]" is
1036 ; "imessagepart"
1038 authimapurlfull = authimapurl iurlauth
1039 ; Same as "imapurl" when "[icommand]" is
1040 ; "imessagepart iurlauth"
1042 authimapurlrump = authimapurl iurlauth-rump
1045 enc-urlauth = 32*HEXDIG
1047 iurlauth = iurlauth-rump iua-verifier
1049 iua-verifier = ":" uauth-mechanism ":" enc-urlauth
1051 iurlauth-rump = [expire] ";URLAUTH=" access
1053 access = ("submit+" enc-user) / ("user+" enc-user) /
1054 "authuser" / "anonymous"
1056 expire = ";EXPIRE=" date-time
1057 ; date-time is defined in [DATETIME]
1059 uauth-mechanism = "INTERNAL" / 1*(ALPHA / DIGIT / "-" / ".")
1060 ; Case-insensitive.
1061 ; New mechanisms MUST be registered with IANA.
1066 Melnikov & Newman Standards Track [Page 19]
1068 RFC 5092 IMAP URL Scheme November 2007
1071 iauth = ";AUTH=" ( "*" / enc-auth-type )
1073 icommand = imessagelist /
1074 imessagepart [iurlauth]
1076 imailbox-ref = enc-mailbox [uidvalidity]
1078 imessagelist = imailbox-ref [ "?" enc-search ]
1079 ; "enc-search" is [URI-GEN] "query".
1081 imessagepart = imailbox-ref iuid [isection] [ipartial]
1083 ipartial = "/" ipartial-only
1085 ipartial-only = ";PARTIAL=" partial-range
1087 isection = "/" isection-only
1089 isection-only = ";SECTION=" enc-section
1091 iserver = [iuserinfo "@"] host [ ":" port ]
1092 ; This is the same as "authority" defined
1093 ; in [URI-GEN]. See [URI-GEN] for "host"
1094 ; and "port" definitions.
1096 iuid = "/" iuid-only
1098 iuid-only = ";UID=" nz-number
1099 ; See [IMAP4] for "nz-number" definition
1101 iuserinfo = enc-user [iauth] / [enc-user] iauth
1102 ; conforms to the generic syntax of
1103 ; "userinfo" as defined in [URI-GEN].
1105 partial-range = number ["." nz-number]
1106 ; partial FETCH. The first number is
1107 ; the offset of the first byte,
1108 ; the second number is the length of
1109 ; the fragment.
1111 uidvalidity = ";UIDVALIDITY=" nz-number
1112 ; See [IMAP4] for "nz-number" definition
1122 Melnikov & Newman Standards Track [Page 20]
1124 RFC 5092 IMAP URL Scheme November 2007
1127 12. IANA Considerations
1129 IANA has updated the "imap" definition in the "Uniform Resource
1130 Identifier scheme registry" to point to this document.
1132 The registration template (as per [URI-REG]) is specified in Section
1133 12.1 of this document.
1135 12.1. IANA Registration of imap: URI Scheme
1137 This section provides the information required to register the imap:
1138 URI scheme.
1140 URI scheme name: imap
1142 Status: permanent
1144 URI scheme syntax:
1146 See Section 11 of [RFC5092].
1148 URI scheme semantics:
1150 The imap: URI scheme is used to designate IMAP servers, mailboxes,
1151 messages, MIME bodies [MIME] and their parts, and search programs
1152 on Internet hosts accessible using the IMAP protocol.
1154 There is no MIME type associated with this URI.
1156 Encoding considerations:
1158 See Section 8 of [RFC5092].
1160 Applications/protocols that use this URI scheme name:
1162 The imap: URI is intended to be used by applications that might
1163 need access to an IMAP mailstore. Such applications may include
1164 (but are not limited to) IMAP-capable web browsers; IMAP clients
1165 that wish to access a mailbox, message, or edit a message on the
1166 server using [CATENATE]; [SUBMIT] clients and servers that are
1167 requested to assemble a complete message on submission using
1168 [BURL].
1170 Interoperability considerations:
1172 A widely deployed IMAP client Netscape Mail (and possibly
1173 Mozilla/Thunderbird/Seamonkey) uses a different imap: scheme
1174 internally.
1178 Melnikov & Newman Standards Track [Page 21]
1180 RFC 5092 IMAP URL Scheme November 2007
1183 Security considerations:
1185 See Security Considerations (Section 10) of [RFC5092].
1187 Contact:
1189 Alexey Melnikov <alexey.melnikov@isode.com>
1191 Author/Change controller:
1193 IESG
1195 References:
1197 [RFC5092] and [IMAP4].
1199 13. References
1201 13.1. Normative References
1203 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
1204 Requirement Levels", BCP 14, RFC 2119, March 1997.
1206 [IMAP4] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
1207 4rev1", RFC 3501, March 2003.
1209 [IMAPABNF] Melnikov, A. and C. Daboo, "Collected Extensions to
1210 IMAP4 ABNF", RFC 4466, April 2006.
1212 [ABNF] Crocker, D., Ed., and P. Overell, "Augmented BNF for
1213 Syntax Specifications: ABNF", RFC 4234, October 2005.
1215 [MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
1216 Extensions (MIME) Part One: Format of Internet Message
1217 Bodies", RFC 2045, November 1996.
1219 [URI-GEN] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
1220 Resource Identifier (URI): Generic Syntax", STD 66, RFC
1221 3986, January 2005.
1223 [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO
1224 10646", STD 63, RFC 3629, November 2003.
1226 [NAMESPACE] Gahrns, M. and C. Newman, "IMAP4 Namespace", RFC 2342,
1227 May 1998.
1229 [LITERAL+] Myers, J., "IMAP4 non-synchronizing literals", RFC 2088,
1230 January 1997.
1234 Melnikov & Newman Standards Track [Page 22]
1236 RFC 5092 IMAP URL Scheme November 2007
1239 [ANONYMOUS] Zeilenga, K., "Anonymous Simple Authentication and
1240 Security Layer (SASL) Mechanism", RFC 4505, June 2006.
1242 [DATETIME] Klyne, G. and C. Newman, "Date and Time on the Internet:
1243 Timestamps", RFC 3339, July 2002.
1245 [URLAUTH] Crispin, M., "Internet Message Access Protocol (IMAP) -
1246 URLAUTH Extension", RFC 4467, May 2006.
1248 13.2. Informative References
1250 [SUBMIT] Gellens, R. and J. Klensin, "Message Submission for
1251 Mail", RFC 4409, April 2006.
1253 [BURL] Newman, C., "Message Submission BURL Extension", RFC
1254 4468, May 2006.
1256 [CATENATE] Resnick, P., "Internet Message Access Protocol (IMAP)
1257 CATENATE Extension", RFC 4469, April 2006.
1259 [SASL] Melnikov, A., Ed., and K. Zeilenga, Ed., "Simple
1260 Authentication and Security Layer (SASL)", RFC 4422,
1261 June 2006.
1263 [GSSAPI] Melnikov, A., Ed., "The Kerberos V5 ("GSSAPI") Simple
1264 Authentication and Security Layer (SASL) Mechanism", RFC
1265 4752, November 2006.
1267 [DIGEST-MD5] Leach, P. and C. Newman, "Using Digest Authentication as
1268 a SASL Mechanism", RFC 2831, May 2000.
1270 [URI-REG] Hansen, T., Hardie, T., and L. Masinter, "Guidelines and
1271 Registration Procedures for New URI Schemes", BCP 115,
1272 RFC 4395, February 2006.
1290 Melnikov & Newman Standards Track [Page 23]
1292 RFC 5092 IMAP URL Scheme November 2007
1295 Appendix A. Sample Code
1297 Here is sample C source code to convert between URL paths and IMAP
1298 mailbox names, taking into account mapping between IMAP's modified
1299 UTF-7 [IMAP4] and hex-encoded UTF-8, which is more appropriate for
1300 URLs. This code has not been rigorously tested nor does it
1301 necessarily behave reasonably with invalid input, but it should serve
1302 as a useful example. This code just converts the mailbox portion of
1303 the URL and does not deal with parameters, query, or server
1304 components of the URL.
1306 /* Copyright (C) The IETF Trust (2007). This version of
1307 sample C code is part of RFC XXXX; see the RFC itself
1308 for full legal notices.
1310 Regarding this sample C code (or any portion of it), the authors
1311 make no guarantees and are not responsible for any damage
1312 resulting from its use. The authors grant irrevocable permission
1313 to anyone to use, modify, and distribute it in any way that does
1314 not diminish the rights of anyone else to use, modify, and
1315 distribute it, provided that redistributed derivative works do
1316 not contain misleading author or version information.
1318 Derivative works need not be licensed under similar terms.
1319 */
1321 #include <stdio.h>
1322 #include <string.h>
1324 /* hexadecimal lookup table */
1325 static const char hex[] = "0123456789ABCDEF";
1327 #define XX 127
1328 /*
1329 * Table for decoding hexadecimal in %encoding
1330 */
1331 static const char index_hex[256] = {
1332 XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
1333 XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
1334 XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
1335 0, 1, 2, 3, 4, 5, 6, 7, 8, 9,XX,XX, XX,XX,XX,XX,
1336 XX,10,11,12, 13,14,15,XX, XX,XX,XX,XX, XX,XX,XX,XX,
1337 XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
1338 XX,10,11,12, 13,14,15,XX, XX,XX,XX,XX, XX,XX,XX,XX,
1339 XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
1340 XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
1341 XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
1342 XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
1346 Melnikov & Newman Standards Track [Page 24]
1348 RFC 5092 IMAP URL Scheme November 2007
1351 XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
1352 XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
1353 XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
1354 XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
1355 XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX, XX,XX,XX,XX,
1356 };
1357 #define HEXCHAR(c) (index_hex[(unsigned char)(c)])
1359 /* "gen-delims" excluding "/" but including "%" */
1360 #define GENERAL_DELIMS_NO_SLASH ":?#[]@" "%"
1362 /* "gen-delims" (excluding "/", but including "%")
1363 plus subset of "sub-delims" */
1364 #define GENERAL_UNSAFE_NO_SLASH GENERAL_DELIMS_NO_SLASH ";&=+"
1365 #define OTHER_UNSAFE " \"<>\\^`{|}"
1367 /* URL unsafe printable characters */
1368 static const char mailbox_url_unsafe[] = GENERAL_UNSAFE_NO_SLASH
1369 OTHER_UNSAFE;
1371 /* UTF7 modified base64 alphabet */
1372 static const char base64chars[] =
1373 "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+,";
1375 #define UNDEFINED 64
1377 /* UTF16 definitions */
1378 #define UTF16MASK 0x03FFUL
1379 #define UTF16SHIFT 10
1380 #define UTF16BASE 0x10000UL
1381 #define UTF16HIGHSTART 0xD800UL
1382 #define UTF16HIGHEND 0xDBFFUL
1383 #define UTF16LOSTART 0xDC00UL
1384 #define UTF16LOEND 0xDFFFUL
1386 /* Convert an IMAP mailbox to a URL path
1387 * dst needs to have roughly 4 times the storage space of src
1388 * Hex encoding can triple the size of the input
1389 * UTF-7 can be slightly denser than UTF-8
1390 * (worst case: 8 octets UTF-7 becomes 9 octets UTF-8)
1391 */
1392 void MailboxToURL(char *dst, char *src)
1393 {
1394 unsigned char c, i, bitcount;
1395 unsigned long ucs4, utf16, bitbuf;
1396 unsigned char base64[256], utf8[6];
1398 /* initialize modified base64 decoding table */
1402 Melnikov & Newman Standards Track [Page 25]
1404 RFC 5092 IMAP URL Scheme November 2007
1407 memset(base64, UNDEFINED, sizeof (base64));
1408 for (i = 0; i < sizeof (base64chars); ++i) {
1409 base64[(int) base64chars[i]] = i;
1410 }
1412 /* loop until end of string */
1413 while (*src != '\0') {
1414 c = *src++;
1415 /* deal with literal characters and &- */
1416 if (c != '&' || *src == '-') {
1417 /* NB: There are no "URL safe" characters after the '~' */
1418 if (c < ' ' || c > '~' ||
1419 strchr(mailbox_url_unsafe, c) != NULL) {
1420 /* hex encode if necessary */
1421 dst[0] = '%';
1422 dst[1] = hex[c >> 4];
1423 dst[2] = hex[c & 0x0f];
1424 dst += 3;
1425 } else {
1426 /* encode literally */
1427 *dst++ = c;
1428 }
1429 /* skip over the '-' if this is an &- sequence */
1430 if (c == '&') ++src;
1432 } else {
1433 /* convert modified UTF-7 -> UTF-16 -> UCS-4 -> UTF-8 -> HEX */
1434 bitbuf = 0;
1435 bitcount = 0;
1436 ucs4 = 0;
1437 while ((c = base64[(unsigned char) *src]) != UNDEFINED) {
1438 ++src;
1439 bitbuf = (bitbuf << 6) | c;
1440 bitcount += 6;
1441 /* enough bits for a UTF-16 character? */
1442 if (bitcount >= 16) {
1443 bitcount -= 16;
1444 utf16 = (bitcount ? bitbuf >> bitcount
1445 : bitbuf) & 0xffff;
1446 /* convert UTF16 to UCS4 */
1447 if
1448 (utf16 >= UTF16HIGHSTART && utf16 <= UTF16HIGHEND) {
1449 ucs4 = (utf16 - UTF16HIGHSTART) << UTF16SHIFT;
1450 continue;
1451 } else if
1452 (utf16 >= UTF16LOSTART && utf16 <= UTF16LOEND) {
1453 ucs4 += utf16 - UTF16LOSTART + UTF16BASE;
1454 } else {
1458 Melnikov & Newman Standards Track [Page 26]
1460 RFC 5092 IMAP URL Scheme November 2007
1463 ucs4 = utf16;
1464 }
1465 /* convert UTF-16 range of UCS4 to UTF-8 */
1466 if (ucs4 <= 0x7fUL) {
1467 utf8[0] = (unsigned char) ucs4;
1468 i = 1;
1469 } else if (ucs4 <= 0x7ffUL) {
1470 utf8[0] = 0xc0 | (unsigned char) (ucs4 >> 6);
1471 utf8[1] = 0x80 | (unsigned char) (ucs4 & 0x3f);
1472 i = 2;
1473 } else if (ucs4 <= 0xffffUL) {
1474 utf8[0] = 0xe0 | (unsigned char) (ucs4 >> 12);
1475 utf8[1] = 0x80 | (unsigned char) ((ucs4 >> 6) & 0x3f);
1476 utf8[2] = 0x80 | (unsigned char) (ucs4 & 0x3f);
1477 i = 3;
1478 } else {
1479 utf8[0] = 0xf0 | (unsigned char) (ucs4 >> 18);
1480 utf8[1] = 0x80 | (unsigned char) ((ucs4 >> 12) & 0x3f);
1481 utf8[2] = 0x80 | (unsigned char) ((ucs4 >> 6) & 0x3f);
1482 utf8[3] = 0x80 | (unsigned char) (ucs4 & 0x3f);
1483 i = 4;
1484 }
1485 /* convert utf8 to hex */
1486 for (c = 0; c < i; ++c) {
1487 dst[0] = '%';
1488 dst[1] = hex[utf8[c] >> 4];
1489 dst[2] = hex[utf8[c] & 0x0f];
1490 dst += 3;
1491 }
1492 }
1493 }
1494 /* skip over trailing '-' in modified UTF-7 encoding */
1495 if (*src == '-') ++src;
1496 }
1497 }
1498 /* terminate destination string */
1499 *dst = '\0';
1500 }
1502 /* Convert hex coded UTF-8 URL path to modified UTF-7 IMAP mailbox
1503 * dst should be about twice the length of src to deal with non-hex
1504 * coded URLs
1505 */
1506 int URLtoMailbox(char *dst, char *src)
1507 {
1508 unsigned int utf8pos = 0;
1509 unsigned int utf8total, i, c, utf7mode, bitstogo, utf16flag;
1510 unsigned long ucs4 = 0, bitbuf = 0;
1514 Melnikov & Newman Standards Track [Page 27]
1516 RFC 5092 IMAP URL Scheme November 2007
1519 utf7mode = 0; /* is the output UTF7 currently in base64 mode? */
1520 utf8total = 0; /* how many octets is the current input UTF-8 char;
1521 0 == between characters */
1522 bitstogo = 0; /* bits that need to be encoded into base64; if
1523 bitstogo != 0 then utf7mode == 1 */
1524 while ((c = (unsigned char)*src) != '\0') {
1525 ++src;
1526 /* undo hex-encoding */
1527 if (c == '%' && src[0] != '\0' && src[1] != '\0') {
1528 c = HEXCHAR(src[0]);
1529 i = HEXCHAR(src[1]);
1530 if (c == XX || i == XX) {
1531 return 0;
1532 } else {
1533 c = (char)((c << 4) | i);
1534 }
1535 src += 2;
1536 }
1537 /* normal character? */
1538 if (c >= ' ' && c <= '~') {
1539 /* switch out of UTF-7 mode */
1540 if (utf7mode) {
1541 if (bitstogo) {
1542 *dst++ = base64chars[(bitbuf << (6 - bitstogo)) & 0x3F];
1543 }
1544 *dst++ = '-';
1545 utf7mode = 0;
1546 bitstogo = bitbuf = 0;
1547 }
1548 *dst++ = c;
1549 /* encode '&' as '&-' */
1550 if (c == '&') {
1551 *dst++ = '-';
1552 }
1553 continue;
1554 }
1555 /* switch to UTF-7 mode */
1556 if (!utf7mode) {
1557 *dst++ = '&';
1558 utf7mode = 1;
1559 }
1560 /* Encode US-ASCII characters as themselves */
1561 if (c < 0x80) {
1562 ucs4 = c;
1563 utf8total = 1;
1564 } else if (utf8total) {
1565 /* this is a subsequent octet of a multi-octet character */
1566 /* save UTF8 bits into UCS4 */
1570 Melnikov & Newman Standards Track [Page 28]
1572 RFC 5092 IMAP URL Scheme November 2007
1575 ucs4 = (ucs4 << 6) | (c & 0x3FUL);
1576 if (++utf8pos < utf8total) {
1577 continue;
1578 }
1579 } else {
1580 /* this is the first octet of a multi-octet character */
1581 utf8pos = 1;
1582 if (c < 0xE0) {
1583 utf8total = 2;
1584 ucs4 = c & 0x1F;
1585 } else if (c < 0xF0) {
1586 utf8total = 3;
1587 ucs4 = c & 0x0F;
1588 } else {
1589 /* NOTE: can't convert UTF8 sequences longer than 4 */
1590 utf8total = 4;
1591 ucs4 = c & 0x03;
1592 }
1593 continue;
1594 }
1595 /* Finished with UTF-8 character. Make sure it isn't an
1596 overlong sequence. If it is, return failure. */
1597 if ((ucs4 < 0x80 && utf8total > 1) ||
1598 (ucs4 < 0x0800 && utf8total > 2) ||
1599 (ucs4 < 0x00010000 && utf8total > 3) ||
1600 (ucs4 < 0x00200000 && utf8total > 4) ||
1601 (ucs4 < 0x04000000 && utf8total > 5) ||
1602 (ucs4 < 0x80000000 && utf8total > 6)) {
1603 return 0;
1604 }
1605 /* loop to split ucs4 into two utf16 chars if necessary */
1606 utf8total = 0;
1607 do {
1608 if (ucs4 >= UTF16BASE) {
1609 ucs4 -= UTF16BASE;
1610 bitbuf = (bitbuf << 16) | ((ucs4 >> UTF16SHIFT)
1611 + UTF16HIGHSTART);
1612 ucs4 = (ucs4 & UTF16MASK) + UTF16LOSTART;
1613 utf16flag = 1;
1614 } else {
1615 bitbuf = (bitbuf << 16) | ucs4;
1616 utf16flag = 0;
1617 }
1618 bitstogo += 16;
1619 /* spew out base64 */
1620 while (bitstogo >= 6) {
1621 bitstogo -= 6;
1622 *dst++ = base64chars[(bitstogo ? (bitbuf >> bitstogo)
1626 Melnikov & Newman Standards Track [Page 29]
1628 RFC 5092 IMAP URL Scheme November 2007
1631 : bitbuf)
1632 & 0x3F];
1633 }
1634 } while (utf16flag);
1635 }
1636 /* if in UTF-7 mode, finish in ASCII */
1637 if (utf7mode) {
1638 if (bitstogo) {
1639 *dst++ = base64chars[(bitbuf << (6 - bitstogo)) & 0x3F];
1640 }
1641 *dst++ = '-';
1642 }
1643 /* tie off string */
1644 *dst = '\0';
1645 return 1;
1646 }
1648 Appendix B. List of Changes since RFC 2192
1650 Updated boilerplate, list of editor's, etc.
1651 Updated references.
1652 Updated ABNF not to use _, to use SP instead of SPACE, etc.
1653 Updated example domains to use example.org.
1654 Fixed ABNF error in "imessagelist" non-terminal.
1655 Updated ABNF, due to changes in RFC 3501, RFC 4466, and RFC 3986.
1656 Renamed "iuserauth" non-terminal to <iuserinfo>.
1657 Clarified that the userinfo component describes both authorization
1658 identity and mailbox naming scope.
1659 Allow for non-synchronizing literals in "enc-search".
1660 Added "ipartial" specifier that denotes a partial FETCH.
1661 Moved URLAUTH text from RFC 4467 to this document.
1662 Updated ABNF for the whole server to allow missing trailing "/"
1663 (e.g., "imap://imap.example.com" is now valid and is the same as
1664 "imap://imap.example.com/").
1665 Clarified how relative-path references are constructed.
1666 Added more examples demonstrating relative-path references.
1667 Added rules for relative URLs and restructured ABNF as the result.
1668 Removed text on use of relative URLs in MHTML.
1669 Added examples demonstrating security considerations when resolving
1670 URLs.
1671 Recommend usage of STARTTLS/SASL security layer to protect
1672 confidential data.
1673 Removed some advices about connection reuse that were incorrect.
1674 Removed URLs referencing a list of mailboxes, as this feature
1675 hasn't seen any deployments.
1676 Clarified that user name "anonymous" is case-insensitive.
1682 Melnikov & Newman Standards Track [Page 30]
1684 RFC 5092 IMAP URL Scheme November 2007
1687 Appendix C. List of Changes since RFC 4467
1689 Renamed <mechanism> to <uauth-mechanism>. Restructured ABNF.
1691 Appendix D. Acknowledgments
1693 Text describing URLAUTH was lifted from [URLAUTH] by Mark Crispin.
1695 Stephane H. Maes contributed some ideas to this document; he also
1696 co-edited early versions of this document.
1698 The editors would like to thank Mark Crispin, Ken Murchison, Ted
1699 Hardie, Zoltan Ordogh, Dave Cridland, Kjetil Torgrim Homme, Lisa
1700 Dusseault, Spencer Dawkins, Filip Navara, Shawn M. Emery, Sam
1701 Hartman, Russ Housley, and Lars Eggert for the time they devoted to
1702 reviewing this document and/or for the comments received.
1704 Authors' Addresses
1706 Chris Newman (Author/Editor)
1707 Sun Microsystems
1708 3401 Centrelake Dr., Suite 410
1709 Ontario, CA 91761
1710 EMail: chris.newman@sun.com
1712 Alexey Melnikov (Editor)
1713 Isode Limited
1714 5 Castle Business Village
1715 36 Station Road
1716 Hampton, Middlesex
1717 TW12 2BX, UK
1718 EMail: Alexey.Melnikov@isode.com
1719 URI: http://www.melnikov.ca/
1738 Melnikov & Newman Standards Track [Page 31]
1740 RFC 5092 IMAP URL Scheme November 2007
1743 Full Copyright Statement
1745 Copyright (C) The IETF Trust (2007).
1747 This document is subject to the rights, licenses and restrictions
1748 contained in BCP 78, and except as set forth therein, the authors
1749 retain all their rights.
1751 This document and the information contained herein are provided on an
1752 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
1753 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
1754 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
1755 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
1756 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
1757 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1759 Intellectual Property
1761 The IETF takes no position regarding the validity or scope of any
1762 Intellectual Property Rights or other rights that might be claimed to
1763 pertain to the implementation or use of the technology described in
1764 this document or the extent to which any license under such rights
1765 might or might not be available; nor does it represent that it has
1766 made any independent effort to identify any such rights. Information
1767 on the procedures with respect to rights in RFC documents can be
1768 found in BCP 78 and BCP 79.
1770 Copies of IPR disclosures made to the IETF Secretariat and any
1771 assurances of licenses to be made available, or the result of an
1772 attempt made to obtain a general license or permission for the use of
1773 such proprietary rights by implementers or users of this
1774 specification can be obtained from the IETF on-line IPR repository at
1775 http://www.ietf.org/ipr.
1777 The IETF invites any interested party to bring to its attention any
1778 copyrights, patents or patent applications, or other proprietary
1779 rights that may cover technology that may be required to implement
1780 this standard. Please address the information to the IETF at
1781 ietf-ipr@ietf.org.
1794 Melnikov & Newman Standards Track [Page 32]