]" command. The 342 type of the object may be determined with a "UID FETCH BODYS- 343 TRUCTURE" command and locating the appropriate part in the result- 344 ing BODYSTRUCTURE. Note that unsafe characters in [isection] MUST 345 be percent-encoded as described in [URI-GEN]. 347 The field is optional. If present, it effectively 348 appends "<>" to the end of the UID FETCH 349 BODY.PEEK[

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