1
2
3
4
5
6
7Network Working Group A. Melnikov, Ed.
8Request for Comments: 5092 Isode Ltd.
9Obsoletes: 2192 C. Newman
10Updates: 4467 Sun Microsystems
11Category: Standards Track November 2007
12
13
14 IMAP URL Scheme
15
16Status of This Memo
17
18 This document specifies an Internet standards track protocol for the
19 Internet community, and requests discussion and suggestions for
20 improvements. Please refer to the current edition of the "Internet
21 Official Protocol Standards" (STD 1) for the standardization state
22 and status of this protocol. Distribution of this memo is unlimited.
23
24Abstract
25
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.
31
32 This document obsoletes RFC 2192. It also updates RFC 4467.
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58Melnikov & Newman Standards Track [Page 1]
59
60RFC 5092 IMAP URL Scheme November 2007
61
62
63Table of Contents
64
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
101
1021. Introduction
103
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.
107
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]).
111
112
113
114Melnikov & Newman Standards Track [Page 2]
115
116RFC 5092 IMAP URL Scheme November 2007
117
118
119 An absolute IMAP URL takes one of the following forms:
120
121 imap://<iserver>[/]
122
123 imap://<iserver>/<enc-mailbox>[<uidvalidity>][?<enc-search>]
124
125 imap://<iserver>/<enc-mailbox>[<uidvalidity>]<iuid>
126 [<isection>][<ipartial>][<iurlauth>]
127
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).
135
136 The <iserver> component common to all types of absolute IMAP URLs has
137 the following syntax expressed in ABNF [ABNF]:
138
139 [iuserinfo "@"] host [ ":" port ]
140
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].
145
1462. Conventions Used in This Document
147
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].
151
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].
157
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.
165
166
167
168
169
170Melnikov & Newman Standards Track [Page 3]
171
172RFC 5092 IMAP URL Scheme November 2007
173
174
1753. IMAP userinfo Component (iuserinfo)
176
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]:
180
181 enc-user [iauth] / [enc-user] iauth
182
183 The meaning of the different parts is described in subsections of
184 this section.
185
1863.1. IMAP Mailbox Naming Scope
187
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.
194
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.
199
2003.2. IMAP User Name and Authentication Mechanism
201
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.
209
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.
219
220 Note that, as described in RFC 3501, the "LOGIN" command MUST NOT be
221 used when the IMAP server advertises the LOGINDISABLED capability.
222
223
224
225
226Melnikov & Newman Standards Track [Page 4]
227
228RFC 5092 IMAP URL Scheme November 2007
229
230
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.
239
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.
253
254 If a user name is included with no authentication mechanism, then
255 ";AUTH=*" is assumed.
256
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:
263
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.
269
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.
275
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
279
280
281
282Melnikov & Newman Standards Track [Page 5]
283
284RFC 5092 IMAP URL Scheme November 2007
285
286
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".
291
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.
299
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].
304
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.
312
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.
318
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].
322
3233.3. Limitations of enc-user
324
325 As per Sections 3.1 and 3.2 of this document, the IMAP URI enc-user
326 has two purposes:
327
328 1) It provides context for user-specific mailbox paths such as
329 "INBOX" (Section 3.1).
330
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).
334
335
336
337
338Melnikov & Newman Standards Track [Page 6]
339
340RFC 5092 IMAP URL Scheme November 2007
341
342
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.
347
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.
352
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.
357
3584. IMAP Server
359
360 An IMAP URL referring to an IMAP server has the following form:
361
362 imap://<iserver>[/]
363
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.
371
3725. Lists of Messages
373
374 An IMAP URL referring to a list of messages has the following form:
375
376 imap://<iserver>/<enc-mailbox>[<uidvalidity>][?<enc-search>]
377
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].
382
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.
389
390
391
392
393
394Melnikov & Newman Standards Track [Page 7]
395
396RFC 5092 IMAP URL Scheme November 2007
397
398
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.
403
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.
407
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].
414
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]).
421
4226. A Specific Message or Message Part
423
424 An IMAP URL referring to a specific message or message part has the
425 following form:
426
427 imap://<iserver>/<enc-mailbox>[<uidvalidity>]<iuid>
428 [<isection>][<ipartial>][<iurlauth>]
429
430 The <enc-mailbox> and [uidvalidity] are as defined in Section 5
431 above.
432
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.
435
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.
439
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
446
447
448
449
450Melnikov & Newman Standards Track [Page 8]
451
452RFC 5092 IMAP URL Scheme November 2007
453
454
455 resulting BODYSTRUCTURE. Note that unsafe characters in [isection]
456 MUST be percent-encoded as described in [URI-GEN].
457
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.
463
464 The <iurlauth> field is described in detail in Section 6.1.
465
4666.1. URLAUTH Authorized URL
467
468 URLAUTH authorized URLs are only supported by an IMAP server
469 advertising the URLAUTH IMAP capability [URLAUTH].
470
4716.1.1. Concepts
472
4736.1.1.1. URLAUTH
474
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.
481
482 Note: This specification only allows for the URLAUTH component in
483 IMAP URLs describing a message or its part.
484
4856.1.1.2. Mailbox Access Key
486
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).
490
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.
497
4986.1.1.3. Authorized Access Identifier
499
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.
503
504
505
506Melnikov & Newman Standards Track [Page 9]
507
508RFC 5092 IMAP URL Scheme November 2007
509
510
5116.1.1.4. Authorization Mechanism
512
513 The authorization mechanism is the algorithm by which the URLAUTH is
514 generated and subsequently verified, using the mailbox access key.
515
5166.1.1.5. Authorization Token
517
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.
521
5226.1.2. URLAUTH Extensions to IMAP URL
523
524 A specific message or message part IMAP URL can optionally contain
525 ";EXPIRE=<datetime>" and/or ";URLAUTH=<access>:<mech>:<token>".
526
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].
532
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].
541
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.
550
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).
555
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
559
560
561
562Melnikov & Newman Standards Track [Page 10]
563
564RFC 5092 IMAP URL Scheme November 2007
565
566
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]).
571
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.
579
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.
585
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).
591
592 Example:
593
594 <imap://joe@example.com/INBOX/;uid=20/;section=1.2;urlauth=
595 submit+fred:internal:91354a473744909de610943775f92038>
596
5977. Relative IMAP URLs
598
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.
603
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.
607
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
615
616
617
618Melnikov & Newman Standards Track [Page 11]
619
620RFC 5092 IMAP URL Scheme November 2007
621
622
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]).
626
627 The following observations about relative URLs are important:
628
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.
635
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.
644
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.
651
6527.1. absolute-path References
653
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.
661
6627.2. relative-path References
663
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.
667
668 See also Section 4.2 of [URI-GEN] for restrictions on relative-path
669 references.
670
671
672
673
674Melnikov & Newman Standards Track [Page 12]
675
676RFC 5092 IMAP URL Scheme November 2007
677
678
6798. Internationalization Considerations
680
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.
690
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.
693
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.
697
6989. Examples
699
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:".
705
706 The URL:
707
708 <imap://minbari.example.org/gray-council;UIDVALIDITY=385759045/;
709 UID=20/;PARTIAL=0.1024>
710
711 may result in the following client commands and server responses:
712
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>
722
723 The URL:
724
725 <imap://psicorp.example.org/~peter/%E6%97%A5%E6%9C%AC%E8%AA%9E/
726 %E5%8F%B0%E5%8C%97>
727
728
729
730Melnikov & Newman Standards Track [Page 13]
731
732RFC 5092 IMAP URL Scheme November 2007
733
734
735 may result in the following client commands:
736
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>
743
744 The URL:
745
746 <imap://;AUTH=GSSAPI@minbari.example.org/gray-council/;uid=20/
747 ;section=1.2>
748
749 may result in the following client commands:
750
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]
760
761 If the following relative URL is located in that body part:
762
763 <;section=1.4>
764
765 this could result in the following client commands:
766
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]
773
774 The URL:
775
776 <imap://;AUTH=*@minbari.example.org/gray%20council?
777 SUBJECT%20shadows>
778
779
780
781
782
783
784
785
786Melnikov & Newman Standards Track [Page 14]
787
788RFC 5092 IMAP URL Scheme November 2007
789
790
791 could result in the following:
792
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 ...
808
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.
814
815 The URL:
816
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>
820
821 shows that 8-bit data can be sent using non-synchronizing literals
822 [LITERAL+]. This could result in the following:
823
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
839
840
841
842Melnikov & Newman Standards Track [Page 15]
843
844RFC 5092 IMAP URL Scheme November 2007
845
846
847 ...
848
849 where XXXXXXXXXXXXXX is 14 bytes of UTF-8 encoded data as specified
850 in the URL above.
851
8529.1. Examples of Relative URLs
853
854 The following absolute-path reference
855
856 </foo/;UID=20/..>
857
858 is the same as
859
860 </foo>
861
862 That is, both of them reference the mailbox "foo" located on the IMAP
863 server described by the corresponding Base URI.
864
865 The following relative-path reference
866
867 <;UID=20>
868
869 references a message with UID in the mailbox specified by the Base
870 URI.
871
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:
875
876 <..;UIDVALIDITY=385759045/;UID=20>
877
878 In this example, ".." is not a dot-segment [URI-GEN].
879
88010. Security Considerations
881
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.
886
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.
891
892 Clients resolving IMAP URLs that wish to achieve data confidentiality
893 and/or integrity SHOULD use the STARTTLS command (if supported by the
894
895
896
897
898Melnikov & Newman Standards Track [Page 16]
899
900RFC 5092 IMAP URL Scheme November 2007
901
902
903 server) before starting authentication, or use a SASL mechanism, such
904 as GSSAPI, that provides a confidentiality security layer.
905
90610.1. Security Consideration Specific to URLAUTH Authorized URL
907
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.
915
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.
920
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.
926
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.
931
93211. ABNF for IMAP URL Scheme
933
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.
938
939 sub-delims-sh = "!" / "$" / "'" / "(" / ")" /
940 "*" / "+" / ","
941 ;; Same as [URI-GEN] sub-delims,
942 ;; but without ";", "&" and "=".
943
944 uchar = unreserved / sub-delims-sh / pct-encoded
945
946 achar = uchar / "&" / "="
947 ;; Same as [URI-GEN] 'unreserved / sub-delims /
948 ;; pct-encoded', but ";" is disallowed.
949
950 bchar = achar / ":" / "@" / "/"
951
952
953
954Melnikov & Newman Standards Track [Page 17]
955
956RFC 5092 IMAP URL Scheme November 2007
957
958
959 enc-auth-type = 1*achar
960 ; %-encoded version of [IMAP4] "auth-type"
961
962 enc-mailbox = 1*bchar
963 ; %-encoded version of [IMAP4] "mailbox"
964
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.
973
974 enc-section = 1*bchar
975 ; %-encoded version of [IMAP4] "section-spec"
976
977 enc-user = 1*achar
978 ; %-encoded version of [IMAP4] authorization
979 ; identity or "userid".
980
981 imapurl = "imap://" iserver ipath-query
982 ; Defines an absolute IMAP URL
983
984 ipath-query = ["/" [ icommand ]]
985 ; Corresponds to "path-abempty [ "?" query ]"
986 ; in [URI-GEN]
987
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:
991
992 imapurl-rel = inetwork-path
993
994 / iabsolute-path
995 / irelative-path
996 / ipath-empty
997
998 inetwork-path = "//" iserver ipath-query
999 ; Corresponds to '"//" authority path-abempty
1000 ; [ "?" query ]' in [URI-GEN]
1001
1002 iabsolute-path = "/" [ icommand ]
1003 ; icommand, if present, MUST NOT start with '/'.
1004 ;
1005 ; Corresponds to 'path-absolute [ "?" query ]'
1006 ; in [URI-GEN]
1007
1008
1009
1010Melnikov & Newman Standards Track [Page 18]
1011
1012RFC 5092 IMAP URL Scheme November 2007
1013
1014
1015 irelative-path = imessagelist /
1016 imsg-or-part
1017 ; Corresponds to 'path-noscheme [ "?" query ]'
1018 ; in [URI-GEN]
1019
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
1026
1027 ipath-empty = 0<pchar>
1028 ; Zero characters.
1029 ; The same-document reference.
1030
1031 The following three rules are only used in the presence of the IMAP
1032 [URLAUTH] extension:
1033
1034 authimapurl = "imap://" iserver "/" imessagepart
1035 ; Same as "imapurl" when "[icommand]" is
1036 ; "imessagepart"
1037
1038 authimapurlfull = authimapurl iurlauth
1039 ; Same as "imapurl" when "[icommand]" is
1040 ; "imessagepart iurlauth"
1041
1042 authimapurlrump = authimapurl iurlauth-rump
1043
1044
1045 enc-urlauth = 32*HEXDIG
1046
1047 iurlauth = iurlauth-rump iua-verifier
1048
1049 iua-verifier = ":" uauth-mechanism ":" enc-urlauth
1050
1051 iurlauth-rump = [expire] ";URLAUTH=" access
1052
1053 access = ("submit+" enc-user) / ("user+" enc-user) /
1054 "authuser" / "anonymous"
1055
1056 expire = ";EXPIRE=" date-time
1057 ; date-time is defined in [DATETIME]
1058
1059 uauth-mechanism = "INTERNAL" / 1*(ALPHA / DIGIT / "-" / ".")
1060 ; Case-insensitive.
1061 ; New mechanisms MUST be registered with IANA.
1062
1063
1064
1065
1066Melnikov & Newman Standards Track [Page 19]
1067
1068RFC 5092 IMAP URL Scheme November 2007
1069
1070
1071 iauth = ";AUTH=" ( "*" / enc-auth-type )
1072
1073 icommand = imessagelist /
1074 imessagepart [iurlauth]
1075
1076 imailbox-ref = enc-mailbox [uidvalidity]
1077
1078 imessagelist = imailbox-ref [ "?" enc-search ]
1079 ; "enc-search" is [URI-GEN] "query".
1080
1081 imessagepart = imailbox-ref iuid [isection] [ipartial]
1082
1083 ipartial = "/" ipartial-only
1084
1085 ipartial-only = ";PARTIAL=" partial-range
1086
1087 isection = "/" isection-only
1088
1089 isection-only = ";SECTION=" enc-section
1090
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.
1095
1096 iuid = "/" iuid-only
1097
1098 iuid-only = ";UID=" nz-number
1099 ; See [IMAP4] for "nz-number" definition
1100
1101 iuserinfo = enc-user [iauth] / [enc-user] iauth
1102 ; conforms to the generic syntax of
1103 ; "userinfo" as defined in [URI-GEN].
1104
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.
1110
1111 uidvalidity = ";UIDVALIDITY=" nz-number
1112 ; See [IMAP4] for "nz-number" definition
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122Melnikov & Newman Standards Track [Page 20]
1123
1124RFC 5092 IMAP URL Scheme November 2007
1125
1126
112712. IANA Considerations
1128
1129 IANA has updated the "imap" definition in the "Uniform Resource
1130 Identifier scheme registry" to point to this document.
1131
1132 The registration template (as per [URI-REG]) is specified in Section
1133 12.1 of this document.
1134
113512.1. IANA Registration of imap: URI Scheme
1136
1137 This section provides the information required to register the imap:
1138 URI scheme.
1139
1140 URI scheme name: imap
1141
1142 Status: permanent
1143
1144 URI scheme syntax:
1145
1146 See Section 11 of [RFC5092].
1147
1148 URI scheme semantics:
1149
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.
1153
1154 There is no MIME type associated with this URI.
1155
1156 Encoding considerations:
1157
1158 See Section 8 of [RFC5092].
1159
1160 Applications/protocols that use this URI scheme name:
1161
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].
1169
1170 Interoperability considerations:
1171
1172 A widely deployed IMAP client Netscape Mail (and possibly
1173 Mozilla/Thunderbird/Seamonkey) uses a different imap: scheme
1174 internally.
1175
1176
1177
1178Melnikov & Newman Standards Track [Page 21]
1179
1180RFC 5092 IMAP URL Scheme November 2007
1181
1182
1183 Security considerations:
1184
1185 See Security Considerations (Section 10) of [RFC5092].
1186
1187 Contact:
1188
1189 Alexey Melnikov <alexey.melnikov@isode.com>
1190
1191 Author/Change controller:
1192
1193 IESG
1194
1195 References:
1196
1197 [RFC5092] and [IMAP4].
1198
119913. References
1200
120113.1. Normative References
1202
1203 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
1204 Requirement Levels", BCP 14, RFC 2119, March 1997.
1205
1206 [IMAP4] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
1207 4rev1", RFC 3501, March 2003.
1208
1209 [IMAPABNF] Melnikov, A. and C. Daboo, "Collected Extensions to
1210 IMAP4 ABNF", RFC 4466, April 2006.
1211
1212 [ABNF] Crocker, D., Ed., and P. Overell, "Augmented BNF for
1213 Syntax Specifications: ABNF", RFC 4234, October 2005.
1214
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.
1218
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.
1222
1223 [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO
1224 10646", STD 63, RFC 3629, November 2003.
1225
1226 [NAMESPACE] Gahrns, M. and C. Newman, "IMAP4 Namespace", RFC 2342,
1227 May 1998.
1228
1229 [LITERAL+] Myers, J., "IMAP4 non-synchronizing literals", RFC 2088,
1230 January 1997.
1231
1232
1233
1234Melnikov & Newman Standards Track [Page 22]
1235
1236RFC 5092 IMAP URL Scheme November 2007
1237
1238
1239 [ANONYMOUS] Zeilenga, K., "Anonymous Simple Authentication and
1240 Security Layer (SASL) Mechanism", RFC 4505, June 2006.
1241
1242 [DATETIME] Klyne, G. and C. Newman, "Date and Time on the Internet:
1243 Timestamps", RFC 3339, July 2002.
1244
1245 [URLAUTH] Crispin, M., "Internet Message Access Protocol (IMAP) -
1246 URLAUTH Extension", RFC 4467, May 2006.
1247
124813.2. Informative References
1249
1250 [SUBMIT] Gellens, R. and J. Klensin, "Message Submission for
1251 Mail", RFC 4409, April 2006.
1252
1253 [BURL] Newman, C., "Message Submission BURL Extension", RFC
1254 4468, May 2006.
1255
1256 [CATENATE] Resnick, P., "Internet Message Access Protocol (IMAP)
1257 CATENATE Extension", RFC 4469, April 2006.
1258
1259 [SASL] Melnikov, A., Ed., and K. Zeilenga, Ed., "Simple
1260 Authentication and Security Layer (SASL)", RFC 4422,
1261 June 2006.
1262
1263 [GSSAPI] Melnikov, A., Ed., "The Kerberos V5 ("GSSAPI") Simple
1264 Authentication and Security Layer (SASL) Mechanism", RFC
1265 4752, November 2006.
1266
1267 [DIGEST-MD5] Leach, P. and C. Newman, "Using Digest Authentication as
1268 a SASL Mechanism", RFC 2831, May 2000.
1269
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.
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290Melnikov & Newman Standards Track [Page 23]
1291
1292RFC 5092 IMAP URL Scheme November 2007
1293
1294
1295Appendix A. Sample Code
1296
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.
1305
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.
1309
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.
1317
1318 Derivative works need not be licensed under similar terms.
1319 */
1320
1321#include <stdio.h>
1322#include <string.h>
1323
1324/* hexadecimal lookup table */
1325static const char hex[] = "0123456789ABCDEF";
1326
1327#define XX 127
1328/*
1329 * Table for decoding hexadecimal in %encoding
1330 */
1331static 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,
1343
1344
1345
1346Melnikov & Newman Standards Track [Page 24]
1347
1348RFC 5092 IMAP URL Scheme November 2007
1349
1350
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)])
1358
1359/* "gen-delims" excluding "/" but including "%" */
1360#define GENERAL_DELIMS_NO_SLASH ":?#[]@" "%"
1361
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 " \"<>\\^`{|}"
1366
1367/* URL unsafe printable characters */
1368static const char mailbox_url_unsafe[] = GENERAL_UNSAFE_NO_SLASH
1369 OTHER_UNSAFE;
1370
1371/* UTF7 modified base64 alphabet */
1372static const char base64chars[] =
1373 "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+,";
1374
1375#define UNDEFINED 64
1376
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
1385
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 */
1392void 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];
1397
1398 /* initialize modified base64 decoding table */
1399
1400
1401
1402Melnikov & Newman Standards Track [Page 25]
1403
1404RFC 5092 IMAP URL Scheme November 2007
1405
1406
1407 memset(base64, UNDEFINED, sizeof (base64));
1408 for (i = 0; i < sizeof (base64chars); ++i) {
1409 base64[(int) base64chars[i]] = i;
1410 }
1411
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;
1431
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 {
1455
1456
1457
1458Melnikov & Newman Standards Track [Page 26]
1459
1460RFC 5092 IMAP URL Scheme November 2007
1461
1462
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}
1501
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 */
1506int 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;
1511
1512
1513
1514Melnikov & Newman Standards Track [Page 27]
1515
1516RFC 5092 IMAP URL Scheme November 2007
1517
1518
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 */
1567
1568
1569
1570Melnikov & Newman Standards Track [Page 28]
1571
1572RFC 5092 IMAP URL Scheme November 2007
1573
1574
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)
1623
1624
1625
1626Melnikov & Newman Standards Track [Page 29]
1627
1628RFC 5092 IMAP URL Scheme November 2007
1629
1630
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}
1647
1648Appendix B. List of Changes since RFC 2192
1649
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.
1677
1678
1679
1680
1681
1682Melnikov & Newman Standards Track [Page 30]
1683
1684RFC 5092 IMAP URL Scheme November 2007
1685
1686
1687Appendix C. List of Changes since RFC 4467
1688
1689 Renamed <mechanism> to <uauth-mechanism>. Restructured ABNF.
1690
1691Appendix D. Acknowledgments
1692
1693 Text describing URLAUTH was lifted from [URLAUTH] by Mark Crispin.
1694
1695 Stephane H. Maes contributed some ideas to this document; he also
1696 co-edited early versions of this document.
1697
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.
1703
1704Authors' Addresses
1705
1706 Chris Newman (Author/Editor)
1707 Sun Microsystems
1708 3401 Centrelake Dr., Suite 410
1709 Ontario, CA 91761
1710 EMail: chris.newman@sun.com
1711
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/
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738Melnikov & Newman Standards Track [Page 31]
1739
1740RFC 5092 IMAP URL Scheme November 2007
1741
1742
1743Full Copyright Statement
1744
1745 Copyright (C) The IETF Trust (2007).
1746
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.
1750
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.
1758
1759Intellectual Property
1760
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.
1769
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.
1776
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.
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794Melnikov & Newman Standards Track [Page 32]
1795
1796