]" command. The 328 type of the object may be determined with a "UID FETCH BODYS- 329 TRUCTURE" command and locating the appropriate part in the result- 330 ing BODYSTRUCTURE. Note that unsafe characters in [isection] MUST 331 be percent-encoded as described in [URI-GEN]. 333 The field is optional. If present, it effectively 334 appends "<>" to the end of the UID FETCH 335 BODY.PEEK[

] command constructed as described in the previ- 336 ous paragraph. In other words it allows the client to request a 337 byte range of the message/message part. 339 The field is described in details in section 6.1. 341 6.1 URLAUTH authorized URL 343 URLAUTH authorized URLs are only supported by an IMAP server adver- 344 tising the URLAUTH IMAP capability [URLAUTH]. 346 6.1.1. Concepts 348 6.1.1.1. URLAUTH 350 The URLAUTH is a component, appended at the end of a URL, which 351 conveys authorization to access the data addressed by that URL. It 352 contains an authorized access identifier, an authorization mecha- 353 nism name, and an authorization token. The authorization token is 354 generated from the URL, the authorized access identifer, authoriza- 355 tion mechanism name, and a mailbox access key. 357 (Note that currently this specification only allows for the URLAUTH 358 component in IMAP URLs describing a message or its part.) 360 6.1.1.2. Mailbox Access Key 361 The mailbox access key is a random string with at least 128 bits of 362 entropy. It is generated by software (not by the human user), and 363 MUST be unpredictable. 365 Each user has a table of mailboxes and an associated mailbox access 366 key for each mailbox. Consequently, the mailbox access key is per- 367 user and per-mailbox. In other words, two users sharing the same 368 mailbox each have a different mailbox access key for that mailbox, 369 and each mailbox accessed by a single user also has a different 370 mailbox access key. 372 6.1.1.3. Authorized Access Identifier 374 The authorized access identifier restricts use of the URLAUTH 375 authorized URL to certain users authorized on the server, as 376 described in section 6.1.2. 378 6.1.1.4. Authorization Mechanism 380 The authorization mechanism is the algorithm by which the URLAUTH 381 is generated and subsequently verified, using the mailbox access 382 key. 384 6.1.1.5. Authorization Token 386 The authorization token is a deterministic string of at least 128 387 bits which an entity with knowledge of the secret mailbox access 388 key and URL authorization mechanism can use to verify the URL. 390 6.1.2. URLAUTH extensions to IMAP URL 392 A specific message or message part IMAP URL can optionally contain 393 ";EXPIRE=" and/or ";URLAUTH=::". 395 When ";EXPIRE=" is used, this indicates the latest date 396 and time that the URL is valid. After that date and time, the URL 397 has expired and server implementations MUST reject the URL. If 398 ";EXPIRE=" is not used, the URL has no expiration, but 399 still can be revoked using the RESETKEY command [URLAUTH]. 401 The URLAUTH takes the form ";URLAUTH=::", and 402 MUST be at the end of the URL. It is composed of three parts. The 403 portion provides the authorized access identifiers which 404 may constrain the operations and users that are permitted to use 405 this URL. The portion provides the authorization mechanism 406 used by the IMAP server to generate the authorization token that 407 follows. The portion provides authorization token, which 408 can be generated using the GENURLAUTH command [URLAUTH]. 410 The "submit+" identifier prefix, followed by a userid, 411 indicates that only a userid authorized as a message submission 412 entity on behalf of the specified userid is permitted to use this 413 URL. The IMAP server does not validate the specified userid but 414 does validate that the IMAP session has an authorization identity 415 that is authorized as a message submission entity. The authorized 416 message submission entity MUST validate the userid prior to con- 417 tacting the IMAP server. 419 The "user+" identifier prefix, followed by a userid, indi- 420 cates that use of this URL is limited to IMAP sessions which are 421 logged in as the specified userid (that is, have authorization 422 identity as that userid). 424 Note: if a SASL mechanism which provides both authorization and 425 authentication identifiers is used to authenticate to the IMAP 426 server, the "user+" access identifier MUST match the authoriza- 427 tion identifier. If the SASL mechanism can't transport the 428 authorization identifier, the "user+" access identifier MUST 429 match the authorization identifier derived from the authentica- 430 tion identifier (see [SASL]). 432 The "authuser" identifier indicates that use of this URL 433 is limited to IMAP sessions which are logged in as an authorized 434 user (that is, have authorization identity as an authorized user) 435 of that IMAP server. Use of this URL is prohibited to anonymous 436 IMAP sessions. 438 The "anonymous" identifier indicates that use of this URL 439 is not restricted by session authorization identity; that is, any 440 IMAP session in authenticated or selected state (as defined in 441 [IMAP4]), including anonymous sessions, may issue a URLFETCH 442 [URLAUTH] using this URL. 444 The authorization token is represented as an ASCII-encoded hexadec- 445 imal string, which is used to authorize the URL. The length and 446 the calculation of the authorization token depends upon the mecha- 447 nism used; but, in all cases, the authorization token is at least 448 128 bits (and therefore at least 32 hexadecimal digits). 450 Example: 452 455 7. Relative IMAP URLs 457 Relative IMAP URLs are permitted and are resolved according to the 458 rules defined in [URI-GEN]. In particular in IMAP URLs, parameters 459 are treated as part of the normal path with respect to relative URL 460 resolution. 462 There are 4 forms of relative URLs: , , , . Their syntax is defined in 464 section 11. 466 A relative reference that begins with two slash characters is 467 termed a network-path reference (); such references 468 are rarely used. A relative reference that begins with a single 469 slash character is termed an absolute-path reference (, see also section 7.1). A relative reference that does not 471 begin with a slash character is termed a relative-path reference 472 (, see also section 7.2). The final form is 473 , which is "same-document reference" (see section 4.4 474 of [URI-GEN]). 476 The following observations are important: 478 The grammar element (which is a part of , which 479 is in its turn a part of ; see section 3) is considered 480 part of the user name for purposes of resolving relative IMAP URLs. 481 This means that unless a new user name/server specification is 482 included in the relative URL, the authentication mechanism is 483 inherited from the base IMAP URL. 485 URLs always use "/" as the hierarchy delimiter for the purpose of 486 resolving paths in relative URLs. IMAP4 permits the use of any 487 hierarchy delimiter in mailbox names. For this reason, relative 488 mailbox paths will only work if the mailbox uses "/" as the hierar- 489 chy delimiter. Relative URLs may be used on mailboxes which use 490 other delimiters, but in that case, the entire mailbox name MUST be 491 specified in the relative URL or inherited as a whole from the base 492 URL. 494 If an IMAP server allows for mailbox names starting with "./" or 495 "../", ending with "/." or "/..", or containing sequences "/../" or 496 "/./", then such mailbox names MUST be percent-encoded as described 497 in [URI-GEN]. Otherwise they would be misinterpreted as dot-seg- 498 ments (see Section 3.3 of [URI-GEN]), which are processed specially 499 during relative path resolution process. 501 7.1. absolute-path References 503 A relative reference that begins with a single slash character is 504 termed an absolute-path reference (see section 4.2 of [URI-GEN]). 505 If an IMAP server permits mailbox names with a leading "/", then 506 the leading "/" MUST be percent-encoded as described in [URI-GEN]. 507 Otherwise the produced absolute-path reference URI will be misin- 508 terpreted as a network-path reference [URI-GEN]. 510 7.2. relative-path References 512 A relative reference that does not begin with a slash character is 513 termed a relative-path reference [URI-GEN]. Implementations SHOULD 514 NOT generate or accept relative-path IMAP references. 516 See also section 4.2 of [URI-GEN] for restrictions on relative-path 517 references. 519 8. Internationalization Considerations 521 IMAP4 [IMAP4] section 5.1.3 includes a convention for encoding non- 522 US-ASCII characters in IMAP mailbox names. Because this convention 523 is private to IMAP, it is necessary to convert IMAP's encoding to 524 one that can be more easily interpreted by a URL display program. 525 For this reason, IMAP's modified UTF-7 encoding for mailboxes MUST 526 be converted to UTF-8 [UTF-8]. Since 8-bit octets are not permit- 527 ted in URLs, the UTF-8 octets are percent-encoded as required by 528 the URL specification [URI-GEN], section 2.1. Sample code is 529 included in Appendix A to demonstrate this conversion. 531 IMAP usernames are UTF-8 strings and MUST be percent-encoded as 532 required by the URL specification [URI-GEN], section 2.1. 534 Also note that IMAP SEARCH criteria can contain non US-ASCII char- 535 acters. 8-bit octets in those strings MUST be percent-encoded as 536 required by the URL specification [URI-GEN], section 2.1. 538 9. Examples 540 The following examples demonstrate how an IMAP4 client program 541 might translate various IMAP4 URLs into a series of IMAP4 commands. 542 Commands sent from the client to the server are prefixed with "C:", 543 and responses sent from the server to the client are prefixed with 544 "S:". 546 The URL: 548 551 Results in the following client commands: 553 554 S: * OK [CAPABILITY IMAP4rev1 STARTTLS AUTH=ANONYMOUS] Welcome 555 C: A001 AUTHENTICATE ANONYMOUS 556 S: + 557 C: c2hlcmlkYW5AYmFieWxvbjUuZXhhbXBsZS5vcmc= 558 S: A001 OK Welcome sheridan@babylon5.example.org 559 C: A002 SELECT gray-council 560 561 C: A003 UID FETCH 20 BODY.PEEK[]<0.1024> 563 The URL: 565 568 May results in the following client commands: 570 571 S: * OK [CAPABILITY IMAP4rev1 STARTTLS AUTH=CRAM-MD5] Welcome 572 C: A001 LOGIN ANONYMOUS bester@psycop.psicorp.example.org 573 C: A002 SELECT ~peter/&ZeVnLIqe-/&U,BTFw- 574 576 The URL: 578 581 May result in the following client commands: 583 584 S: * OK Greetings 585 C: A000 CAPABILITY 586 S: * CAPABILITY IMAP4rev1 STARTTLS AUTH=GSSAPI 587 S: A000 OK 588 C: A001 AUTHENTICATE GSSAPI 589 590 C: A002 SELECT gray-council 591 C: A003 UID FETCH 20 BODY.PEEK[1.2] 593 If the following relative URL is located in that body part: 595 <;section=1.4> 597 This could result in the following client commands: 599 C: A004 UID FETCH 20 (BODY.PEEK[1.2.MIME] 600 BODY.PEEK[1.MIME] 601 BODY.PEEK[HEADER.FIELDS (Content-Location)]) 602 604 C: A005 UID FETCH 20 BODY.PEEK[1.4] 606 The URL: 608 611 Could result in the following: 613 614 S: * OK Welcome 615 C: A001 CAPABILITY 616 S: * CAPABILITY IMAP4rev1 AUTH=DIGEST-MD5 617 S: A001 OK 618 C: A002 AUTHENTICATE DIGEST-MD5 619 620 S: A002 OK user lennier authenticated 621 C: A003 SELECT "gray council" 622 ... 623 C: A004 SEARCH SUBJECT shadows 624 S: * SEARCH 8 10 13 14 15 16 625 S: A004 OK SEARCH completed 626 C: A005 FETCH 8,10,13:16 ALL 627 ... 628 NOTE: In this final example, the client has implementation depen- 629 dent choices. The authentication mechanism could be anything, 630 including PREAUTH. And the final FETCH command could fetch more or 631 less information about the messages, depending on what it wishes to 632 display to the user. 634 The URL: 636 640 shows that 8-bit data can be sent using non-synchronizing literals 641 [LITERAL+]. This could result in the following: 643 644 S: * OK Hi there 645 C: A001 CAPABILITY 646 S: * CAPABILITY IMAP4rev1 LITERAL+ AUTH=DIGEST-MD5 647 S: A001 OK 648 C: A002 AUTHENTICATE DIGEST-MD5 649 650 S: A002 OK user john authenticated 651 C: A003 SELECT babylon5/personel 652 ... 653 C: A004 SEARCH CHARSET UTF-8 SUBJECT {14+} 654 C: XXXXXXXXXXXXXX 655 S: * SEARCH 7 10 12 656 S: A004 OK SEARCH completed 657 C: A005 FETCH 7,10,12 ALL 658 ... 660 Where XXXXXXXXXXXXXX is 14 bytes of UTF-8 encoded data as specified 661 in the URL above. 663 9.1. Examples of relative URLs 665 The following absolute-path reference 667 669 is the same as 671 673 I.e. both of them reference the mailbox "foo". 675 The following relative-path reference 677 <;UID=20> 679 references a message with UID in the mailbox specified by the Base 680 URI. 682 The following edge case example demostrates that the ;UIDVALIDITY= 683 modifier is a part of the mailbox name as far as relative URI reso- 684 lution is concerned: 686 <..;UIDVALIDITY=385759045/;UID=20> 688 In this example ".." is not a dot-segment [URI-GEN]. 690 10. Security Considerations 692 Security considerations discussed in the IMAP specification [IMAP4] 693 and the URI specification [URI-GEN] are relevant. Security consid- 694 erations related to authenticated URLs are discussed in section 3 695 of this document. 697 Many email clients store the plain text password for later use 698 after logging into an IMAP server. Such clients MUST NOT use a 699 stored password in response to an IMAP URL without explicit permis- 700 sion from the user to supply that password to the specified host 701 name. 703 Clients resolving IMAP URLs that wish to achieve data confidential- 704 ity and/or integrity SHOULD use the STARTTLS command (if supported 705 by the server) before starting authentication, or use a SASL mecha- 706 nism, such as GSSAPI, that provides a confidentiality security 707 layer. 709 10.1. Security Consideration specific to URLAUTH authorized URL 711 The "user+" access identifier limits resolution of that URL 712 to a particular userid, whereas the "submit+" access iden- 713 tifier is more general and simply requires that the session be 714 authorized by a user that has been granted a "submit" role within 715 the authentication system. Use of either of these access identi- 716 fiers makes it impossible for an attacker, spying on the session, 717 to use the same URL, either directly or by submission to a message 718 submission entity. 720 The "authuser" and "anonymous" access identifiers do not have this 721 level of protection. These access identifiers are primarily useful 722 for public export of data from an IMAP server, without requiring 723 that it be copied to a web or anonymous FTP server. 725 The decision to use the "authuser" access identifier should be made 726 with caution. An "authuser" access identifier can be used by any 727 authorized user of the IMAP server; and therefore use of this 728 access identifier should be limited to content which may be dis- 729 closed to any authorized user of the IMAP server. 731 The decision to use the "anonymous" access identifier should be 732 made with extreme caution. An "anonymous" access identifier can be 733 used by anyone; and therefore use of this access identifier should 734 be limited to content which may be disclosed to anyone. Many IMAP 735 servers do not permit anonymous access; in the case of such servers 736 the "anonymous" access identifer is equivalent to "authuser", but 737 this MUST NOT be relied upon. 739 11. ABNF for IMAP URL scheme 741 Formal syntax is defined using ABNF [ABNF], extending the ABNF 742 rules in section 9 of [IMAP4]. Elements not defined here can be 743 found in the [ABNF], [IMAP4], [IMAPABNF] or [URI-GEN]. Strings are 744 not case sensitive and free insertion of linear-white-space is not 745 permitted. 747 sub-delims-sh = "!" / "$" / "'" / "(" / ")" / 748 "*" / "+" / "," 749 ;; Same as [URI-GEN] sub-delims, but without ";", 750 ;; "&" and "=". 752 uchar = unreserved / sub-delims-sh / pct-encoded 754 achar = uchar / "&" / "=" 755 ;; Same as [URI-GEN] 'unreserved / sub-delims / 756 ;; pct-encoded', but ";" is disallowed. 758 bchar = achar / ":" / "@" / "/" 760 enc-auth-type = 1*achar 761 ; %-encoded version of [IMAP4] "auth-type" 763 enc-mailbox = 1*bchar 764 ; %-encoded version of [IMAP4] "mailbox" 766 enc-search = 1*bchar 767 ; %-encoded version of [IMAPABNF] 768 ; "search-program". Note that IMAP4 769 ; literals may not be used in 770 ; a "search-program", i.e. only 771 ; quoted or non-synchronizing 772 ; literals (if the server supports 773 ; LITERAL+ [LITERAL+]) are allowed. 775 enc-section = 1*bchar 776 ; %-encoded version of [IMAP4] "section-spec" 778 enc-user = 1*achar 779 ; %-encoded version of [IMAP4] authorization 780 ; identity or "userid". 782 imapurl = "imap://" iserver ipath-query 783 ; Defines an absolute IMAP URL 785 ipath-query = ["/" [ icommand ]] 786 ; Corresponds to "path-abempty [ "?" query ]" 787 ; in [URI-GEN] 789 Generic syntax for relative URLs is defined in Section 4.2 790 of [URI-GEN]. For ease of implementation, the relative 791 IMAP URL syntax is defined below: 793 imapurl-rel = inetwork-path 794 / iabsolute-path 795 / irelative-path 796 / ipath-empty 798 inetwork-path = "//" iserver ipath-query 799 ; Corresponds to '"//" authority path-abempty 800 ; [ "?" query ]' in [URI-GEN] 802 iabsolute-path = "/" [ icommand ] 803 ; icommand, if present, MUST NOT start with '/'. 804 ; 805 ; Corresponds to 'path-absolute [ "?" query ]' 806 ; in [URI-GEN] 808 irelative-path = imessagelist / 809 imsg-or-part 810 ; Corresponds to 'path-noscheme [ "?" query ]' 811 ; in [URI-GEN] 813 imsg-or-part = ( imailbox-ref "/" iuid-only ["/" isection-only] 814 ["/" ipartial-only] ) / 815 ( iuid-only ["/" isection-only] 816 ["/" ipartial-only] ) / 817 ( isection-only ["/" ipartial-only] ) / 818 ipartial-only 820 ipath-empty = 0 821 ; Zero characters. 822 ; The same-document reference. 824 The following 3 rules are only used in the presence of the IMAP 825 [URLAUTH] extension: 827 authimapurl = "imap://" iserver "/" imessagepart 828 ; Same as "imapurl" when "[icommand]" is 829 ; "imessagepart" 831 authimapurlfull = authimapurl iurlauth 832 ; Same as "imapurl" when "[icommand]" is 833 ; "imessagepart iurlauth" 835 authimapurlrump = authimapurl iurlauth-rump 837 enc-urlauth = 32*HEXDIG 839 iurlauth = iurlauth-rump iua-verifier 841 iua-verifier = ":" uauth-mechanism ":" enc-urlauth 843 iurlauth-rump = [expire] ";URLAUTH=" access 845 access = ("submit+" enc-user) / ("user+" enc-user) / 846 "authuser" / "anonymous" 848 expire = ";EXPIRE=" date-time 849 ; date-time defined in [DATETIME] 851 uauth-mechanism = "INTERNAL" / 1*(ALPHA / DIGIT / "-" / ".") 852 ; Case-insensitive. 853 ; New mechanisms MUST be registered with IANA. 855 iauth = ";AUTH=" ( "*" / enc-auth-type ) 857 icommand = imessagelist / 858 imessagepart [iurlauth] 860 imailbox-ref = enc-mailbox [uidvalidity] 862 imessagelist = imailbox-ref [ "?" enc-search ] 863 ; "enc-search" is [URI-GEN] "query". 865 imessagepart = imailbox-ref iuid [isection] [ipartial] 867 ipartial = "/" ipartial-only 869 ipartial-only = ";PARTIAL=" partial-range 871 isection = "/" isection-only 873 isection-only = ";SECTION=" enc-section 875 iserver = [iuserinfo "@"] host [ ":" port ] 876 ; This is the same as "authority" defined 877 ; in [URI-GEN]. See [URI-GEN] for "host" 878 ; and "port" definitions. 880 iuid = "/" iuid-only 882 iuid-only = ";UID=" nz-number 883 ; See [IMAP4] for "nz-number" definition 885 iuserinfo = enc-user [iauth] / [enc-user] iauth 886 ; conforms to the generic syntax of 887 ; "userinfo" as defined in [URI-GEN]. 889 partial-range = number ["." nz-number] 890 ; partial FETCH. The first number is 891 ; the offset of the first byte, 892 ; the second number is the length of 893 ; the fragment. 895 uidvalidity = ";UIDVALIDITY=" nz-number 896 ; See [IMAP4] for "nz-number" definition 898 12. IANA Considerations 900 IANA is requested to update "imap" definition in the "Uniform 901 Resource Identifier scheme registry" to point to this document. 903 The registration template (as per [URI-REG]) is specified in sec- 904 tion 12.1 of this document. 906 12.1. IANA Registration of imap: URI Scheme 908 This section provides the information required to register the 909 imap: URI scheme. 911 URI scheme name: imap 913 Status: permanent 915 URI scheme syntax: 916 See section 12 of [RFCXXXX]. 918 URI scheme semantics: 920 The imap: URI scheme is used to designate IMAP servers, 922 mailboxes, messages, MIME bodies [MIME] and their parts, and search 923 programs on Internet hosts accessible using the IMAP protocol. 925 There is no MIME type associated with this URI. 927 Encoding considerations: 929 See Section 9 of [RFCXXXX]. 931 Applications/protocols that use this URI scheme name: 933 The imap: URI is intended to be used by applications that might 934 need access to IMAP mailstore. Such applications may include (but 935 not limited to) IMAP-capable web browsers; IMAP clients that wish 936 to access a mailbox, message, or edit a message on the server using 937 [CATENATE]; [SUBMIT] clients and servers that are requested to 938 assemble a complete message on submission using [BURL]. 940 Interoperability considerations: 942 A widely deployed IMAP client Mozilla/Thubderbird/Seamonkey use 943 a different imap: scheme internally. 945 Security considerations: 947 See Security Considerations (Section 11) of [RFCXXXX]. 949 Contact: 951 Alexey Melnikov 953 Author/Change controller: 955 IESG 957 References: 959 [RFCXXXX] and [IMAP4]. 961 13. References 963 13.1. Normative References 965 [KEYWORDS] Bradner, "Key words for use in RFCs to Indicate Require- 966 ment Levels", BCP 14, RFC 2119, Harvard University, March 1997. 968 [IMAP4] Crispin, M., "Internet Message Access Protocol - Version 969 4rev1", RFC 3501, University of Washington, March 2003. 971 [IMAPABNF] Melnikov, A., and C. Daboo, "Collected extensions to 972 IMAP4 ABNF", RFC 4466, April 2006. 974 [ABNF] Crocker, Overell, "Augmented BNF for Syntax Specifications: 975 ABNF", RFC 4234, October 2005. 977 [MIME] Freed, N., Borenstein, N., "Multipurpose Internet Mail 978 Extensions", RFC 2045, November 1996. 980 [URI-GEN] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform 981 Resource Identifier (URI): Generic Syntax", RFC 3986, January 2005. 983 [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO 984 10646", STD 63, RFC 3629, November 2003. 986 [NAMESPACE] Gahrns, M. and C. Newman, "IMAP4 Namespace", RFC 2342, 987 May 1998. 989 [LITERAL+] Myers, J., "IMAP4 non-synchronizing literals", RFC 2088, 990 January 1997. 992 [ANONYMOUS] Zeilenga, K. (Ed.), "Anonymous Simple Authentication 993 and Security Layer (SASL) Mechanism", RFC 4505, June 2006. 995 [DATETIME] Klyne, G., and Newman, C., "Date and Time on the Inter- 996 net: Timestamps", RFC 3339, July 2002. 998 [URLAUTH] Crispin, M., "Internet Message Access Protocol (IMAP) - 999 URLAUTH Extension", RFC 4467, May 2006. 1001 13.2. Informative References 1003 [SUBMIT] Gellens, R. and J. Klensin, "Message Submission for Mail", 1004 RFC 4409, April 2006. 1006 [BURL] Newman, C. "Message Submission BURL Extension", RFC 4468, 1007 May 2006. 1009 [CATENATE] Resnick, P., "Internet Message Access Protocol (IMAP) 1010 CATENATE Extension", RFC 4469, April 2006. 1012 [SASL] Melnikov, A. and K. Zeilenga, "Simple Authentication and 1013 Security Layer (SASL)", RFC 4422, June 2006. 1015 [GSSAPI] Melnikov, A., "The Kerberos V5 ("GSSAPI") Simple Authenti- 1016 cation and Security Layer (SASL) Mechanism", RFC 4752, November 1017 2006. 1019 [DIGEST-MD5] Leach, P. and C. Newman, "Using Digest Authentication 1020 as a SASL Mechanism", RFC 2831, May 2000. 1022 [URI-REG] Hansen, T., Hardie, T. and L. Masinter, "Guidelines and 1023 Registration Procedures for New URI Schemes", BCP 115, RFC 4395, 1024 February 2006. 1026 14. Author's Address 1028 Chris Newman (Author/Editor) 1029 Sun Microsystems 1030 3401 Centrelake Dr., Suite 410 1031 Ontario, CA 91761 1032 EMail: chris.newman@sun.com 1034 Alexey Melnikov (Editor) 1035 Isode Limited 1036 5 Castle Business Village 1037 36 Station Road 1038 Hampton, Middlesex 1039 TW12 2BX, UK 1040 Email: Alexey.Melnikov@isode.com 1041 URI: http://www.melnikov.ca/ 1043 Stephane H. Maes (Editor) 1044 Oracle Corporation 1045 500 Oracle Parkway 1046 M/S 4op634 1047 Redwood Shores, CA 94065 1048 USA 1049 Phone: +1-650-607-6296 1050 Email: stephane.maes@oracle.com 1052 Appendix A. Sample code 1054 Here is sample C source code to convert between URL paths and IMAP mail- 1055 box names, taking into account mapping between IMAP's modified UTF-7 1056 [IMAP4] and hex-encoded UTF-8 which is more appropriate for URLs. This 1057 code has not been rigorously tested nor does it necessarily behave rea- 1058 sonably with invalid input, but it should serve as a useful example. 1059 This code just converts the mailbox portion of the URL and does not deal 1060 with parameters, query or server components of the URL. 1062 #include 1063 #include 1065 /* hexadecimal lookup table */ 1066 static char hex[] = "0123456789ABCDEF"; 1068 /* URL unsafe printable characters */ 1069 static char urlunsafe[] = " \"#%&+:;<=>?@[\\]^`{|}"; 1071 /* UTF7 modified base64 alphabet */ 1072 static char base64chars[] = 1073 "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+,"; 1074 #define UNDEFINED 64 1076 /* UTF16 definitions */ 1077 #define UTF16MASK 0x03FFUL 1078 #define UTF16SHIFT 10 1079 #define UTF16BASE 0x10000UL 1080 #define UTF16HIGHSTART 0xD800UL 1081 #define UTF16HIGHEND 0xDBFFUL 1082 #define UTF16LOSTART 0xDC00UL 1083 #define UTF16LOEND 0xDFFFUL 1085 /* Convert an IMAP mailbox to a URL path 1086 * dst needs to have roughly 4 times the storage space of src 1087 * Hex encoding can triple the size of the input 1088 * UTF-7 can be slightly denser than UTF-8 1089 * (worst case: 8 octets UTF-7 becomes 9 octets UTF-8) 1090 */ 1091 void MailboxToURL(char *dst, char *src) 1092 { 1093 unsigned char c, i, bitcount; 1094 unsigned long ucs4, utf16, bitbuf; 1095 unsigned char base64[256], utf8[6]; 1096 /* initialize modified base64 decoding table */ 1097 memset(base64, UNDEFINED, sizeof (base64)); 1098 for (i = 0; i < sizeof (base64chars); ++i) { 1099 base64[base64chars[i]] = i; 1100 } 1102 /* loop until end of string */ 1103 while (*src != '\0') { 1104 c = *src++; 1105 /* deal with literal characters and &- */ 1106 if (c != '&' || *src == '-') { 1107 if (c < ' ' || c > '~' || strchr(urlunsafe, c) != NULL) { 1108 /* hex encode if necessary */ 1109 dst[0] = '%'; 1110 dst[1] = hex[c >> 4]; 1111 dst[2] = hex[c & 0x0f]; 1112 dst += 3; 1113 } else { 1114 /* encode literally */ 1115 *dst++ = c; 1116 } 1117 /* skip over the '-' if this is an &- sequence */ 1118 if (c == '&') ++src; 1119 } else { 1120 /* convert modified UTF-7 -> UTF-16 -> UCS-4 -> UTF-8 -> HEX */ 1121 bitbuf = 0; 1122 bitcount = 0; 1123 ucs4 = 0; 1124 while ((c = base64[(unsigned char) *src]) != UNDEFINED) { 1125 ++src; 1126 bitbuf = (bitbuf << 6) | c; 1127 bitcount += 6; 1128 /* enough bits for a UTF-16 character? */ 1129 if (bitcount >= 16) { 1130 bitcount -= 16; 1131 utf16 = (bitcount ? bitbuf >> bitcount 1132 : bitbuf) & 0xffff; 1133 /* convert UTF16 to UCS4 */ 1134 if 1135 (utf16 >= UTF16HIGHSTART && utf16 <= UTF16HIGHEND) { 1136 ucs4 = (utf16 - UTF16HIGHSTART) << UTF16SHIFT; 1137 continue; 1138 } else if 1139 (utf16 >= UTF16LOSTART && utf16 <= UTF16LOEND) { 1140 ucs4 += utf16 - UTF16LOSTART + UTF16BASE; 1141 } else { 1142 ucs4 = utf16; 1143 } 1144 /* convert UTF-16 range of UCS4 to UTF-8 */ 1145 if (ucs4 <= 0x7fUL) { 1146 utf8[0] = ucs4; 1147 i = 1; 1148 } else if (ucs4 <= 0x7ffUL) { 1149 utf8[0] = 0xc0 | (ucs4 >> 6); 1150 utf8[1] = 0x80 | (ucs4 & 0x3f); 1151 i = 2; 1152 } else if (ucs4 <= 0xffffUL) { 1153 utf8[0] = 0xe0 | (ucs4 >> 12); 1154 utf8[1] = 0x80 | ((ucs4 >> 6) & 0x3f); 1155 utf8[2] = 0x80 | (ucs4 & 0x3f); 1156 i = 3; 1157 } else { 1158 utf8[0] = 0xf0 | (ucs4 >> 18); 1159 utf8[1] = 0x80 | ((ucs4 >> 12) & 0x3f); 1160 utf8[2] = 0x80 | ((ucs4 >> 6) & 0x3f); 1161 utf8[3] = 0x80 | (ucs4 & 0x3f); 1162 i = 4; 1163 } 1164 /* convert utf8 to hex */ 1165 for (c = 0; c < i; ++c) { 1166 dst[0] = '%'; 1167 dst[1] = hex[utf8[c] >> 4]; 1168 dst[2] = hex[utf8[c] & 0x0f]; 1169 dst += 3; 1170 } 1171 } 1172 } 1173 /* skip over trailing '-' in modified UTF-7 encoding */ 1174 if (*src == '-') ++src; 1175 } 1176 } 1177 /* terminate destination string */ 1178 *dst = '\0'; 1179 } 1181 /* Convert hex coded UTF-8 URL path to modified UTF-7 IMAP mailbox 1182 * dst should be about twice the length of src to deal with non-hex 1183 * coded URLs 1184 */ 1185 void URLtoMailbox(char *dst, char *src) 1186 { 1187 unsigned int utf8pos, utf8total, i, c, utf7mode, bitstogo, utf16flag; 1188 unsigned long ucs4, bitbuf; 1189 unsigned char hextab[256]; 1191 /* initialize hex lookup table */ 1192 memset(hextab, 0, sizeof (hextab)); 1193 for (i = 0; i < sizeof (hex); ++i) { 1194 hextab[hex[i]] = i; 1195 if (isupper(hex[i])) hextab[tolower(hex[i])] = i; 1196 } 1198 utf7mode = 0; 1199 utf8total = 0; 1200 bitstogo = 0; 1201 while ((c = *src) != '\0') { 1202 ++src; 1203 /* undo hex-encoding */ 1204 if (c == '%' && src[0] != '\0' && src[1] != '\0') { 1205 c = (hextab[src[0]] << 4) | hextab[src[1]]; 1206 src += 2; 1207 } 1208 /* normal character? */ 1209 if (c >= ' ' && c <= '~') { 1210 /* switch out of UTF-7 mode */ 1211 if (utf7mode) { 1212 if (bitstogo) { 1213 *dst++ = base64chars[(bitbuf << (6 - bitstogo)) & 0x3F]; 1214 } 1215 *dst++ = '-'; 1216 utf7mode = 0; 1217 } 1218 *dst++ = c; 1219 /* encode '&' as '&-' */ 1220 if (c == '&') { 1221 *dst++ = '-'; 1222 } 1223 continue; 1224 } 1225 /* switch to UTF-7 mode */ 1226 if (!utf7mode) { 1227 *dst++ = '&'; 1228 utf7mode = 1; 1229 } 1230 /* Encode US-ASCII characters as themselves */ 1231 if (c < 0x80) { 1232 ucs4 = c; 1233 utf8total = 1; 1234 } else if (utf8total) { 1235 /* save UTF8 bits into UCS4 */ 1236 ucs4 = (ucs4 << 6) | (c & 0x3FUL); 1237 if (++utf8pos < utf8total) { 1238 continue; 1239 } 1241 } else { 1242 utf8pos = 1; 1243 if (c < 0xE0) { 1244 utf8total = 2; 1245 ucs4 = c & 0x1F; 1246 } else if (c < 0xF0) { 1247 utf8total = 3; 1248 ucs4 = c & 0x0F; 1249 } else { 1250 /* NOTE: can't convert UTF8 sequences longer than 4 */ 1251 utf8total = 4; 1252 ucs4 = c & 0x03; 1253 } 1254 continue; 1255 } 1256 /* loop to split ucs4 into two utf16 chars if necessary */ 1257 utf8total = 0; 1258 do { 1259 if (ucs4 >= UTF16BASE) { 1260 ucs4 -= UTF16BASE; 1261 bitbuf = (bitbuf << 16) | ((ucs4 >> UTF16SHIFT) 1262 + UTF16HIGHSTART); 1263 ucs4 = (ucs4 & UTF16MASK) + UTF16LOSTART; 1264 utf16flag = 1; 1265 } else { 1266 bitbuf = (bitbuf << 16) | ucs4; 1267 utf16flag = 0; 1268 } 1269 bitstogo += 16; 1270 /* spew out base64 */ 1271 while (bitstogo >= 6) { 1272 bitstogo -= 6; 1273 *dst++ = base64chars[(bitstogo ? (bitbuf >> bitstogo) 1274 : bitbuf) 1275 & 0x3F]; 1276 } 1277 } while (utf16flag); 1278 } 1279 /* if in UTF-7 mode, finish in ASCII */ 1280 if (utf7mode) { 1281 if (bitstogo) { 1282 *dst++ = base64chars[(bitbuf << (6 - bitstogo)) & 0x3F]; 1283 } 1284 *dst++ = '-'; 1285 } 1286 /* tie off string */ 1287 *dst = '\0'; 1288 } 1289 Appendix B. List of changes since RFC 2192 1291 Updated boilerplate, list of editor's, etc. 1292 Updated references. 1293 Updated ABNF not to use _, to use SP instead of SPACE, etc. 1294 Updated example domains to use example.org. 1295 Fixed ABNF error in "imessagelist" non-terminal. 1296 Updated ABNF, due to changes in RFC 3501, RFC 4466 and RFC 3986. 1297 Renamed "iuserauth" non-terminal to "iuserinfo". 1298 Clarified that the userinfo component describes both authorization 1299 identity and mailbox naming scope. 1300 Allow for non-synchronizing literals in "enc-search". 1301 Added "ipartial" specifier that denotes a partial FETCH. 1302 Moved URLAUTH text from RFC 4467 to this document. 1303 Updated ABNF for the whole server to allow missing trailing "/" 1304 (e.g. "imap://imap.example.com" is now valid and is the same as 1305 "imap://imap.example.com/") 1306 Clarified how relative-path references are constructed. 1307 Added more examples demonstrating relative-path references. 1308 Added rules for relative URLs and restructured ABNF as the result. 1309 Removed text on use of relative URLs in MHTML. 1310 Added examples demonstrating security considerations when resolving 1311 URLs. 1312 Recommend usage of STARTTLS/SASL security layer to protect 1313 confidential data. 1314 Removed some advices about connection reuse, which were incorrect. 1315 Removed URLs referencing a list of mailboxes. 1316 Clarified that user name "anonymous" is case-insensitive. 1318 Appendix C. List of changes since RFC 4467 1320 Renamed to . Restructured ABNF. 1322 Appendix D. Acknowledgments 1324 Text describing URLAUTH was lifted from [URLAUTH] by Mark Crispin. 1326 Editors would like to thank Mark Crispin, Ken Murchison, Ted 1327 Hardie, Zoltan Ordogh, Dave Cridland, Kjetil Torgrim Homme and 1328 Filip Navara for the time they devoted to reviewing of this docu- 1329 ment and/or for the comments received. 1331 Intellectual Property 1333 The IETF takes no position regarding the validity or scope of any 1334 Intellectual Property Rights or other rights that might be claimed 1335 to pertain to the implementation or use of the technology 1336 described in this document or the extent to which any license 1337 under such rights might or might not be available; nor does it 1338 represent that it has made any independent effort to identify any 1339 such rights. Information on the procedures with respect to rights 1340 in RFC documents can be found in BCP 78 and BCP 79. 1342 Copies of IPR disclosures made to the IETF Secretariat and any 1343 assurances of licenses to be made available, or the result of an 1344 attempt made to obtain a general license or permission for the use 1345 of such proprietary rights by implementers or users of this 1346 specification can be obtained from the IETF on-line IPR repository 1347 at http://www.ietf.org/ipr. 1349 The IETF invites any interested party to bring to its attention 1350 any copyrights, patents or patent applications, or other 1351 proprietary rights that may cover technology that may be required 1352 to implement this standard. Please address the information to the 1353 IETF at ietf-ipr@ietf.org. 1355 Full Copyright Statement 1357 Copyright (C) The IETF Trust (2007). 1359 This document is subject to the rights, licenses and restrictions 1360 contained in BCP 78, and except as set forth therein, the authors 1361 retain all their rights. 1363 This document and the information contained herein are provided on an 1364 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1365 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1366 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1367 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1368 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1369 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1371 Acknowledgement 1373 Funding for the RFC Editor function is currently provided by the 1374 Internet Society.