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

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