RFC relevance of following

]" command.
type of the object may be determined with a "UID FETCH BODYSTRUCTURE" command and locating the appropriate part in
resulting BODYSTRUCTURE. Note that unsafe characters in [isection
MUST be encoded as described in [BASIC-URL].

Newman Standards Track [Page 5]

RFC 2192 IMAP URL Scheme September 1997

8. Relative IMAP

Relative IMAP URLs are permitted and are resolved according to
rules defined in RFC 1808 [REL-URL] with one exception. In
URLs, parameters are treated as part of the normal path
respect to relative URL resolution. This is believed to be
behavior of the installed base and is likely to be documented in
future revision of the relative URL specification

The following observations are also important

The grammar element is considered part of the user name
purposes of resolving relative IMAP URLs. This means that unless
new login/server specification is included in the relative URL,
authentication mechanism is inherited from a base IMAP URL

URLs always use "/" as the hierarchy delimiter for the purpose
resolving paths in relative URLs. IMAP4 permits the use of
hierarchy delimiter in mailbox names. For this reason,
mailbox paths will only work if the mailbox uses "/" as
hierarchy delimiter. Relative URLs may be used on mailboxes
use other delimiters, but in that case, the entire mailbox
MUST be specified in the relative URL or inherited as a whole
the base URL

The base URL for a list of mailboxes or messages which was
to by an IMAP URL is always the referring IMAP URL itself.
base URL for a message or message part which was referred to by
IMAP URL may be more complicated to determine. The
interpreting the relative URL will have to check the headers of
MIME entity and any enclosing MIME entities in order to locate
"Content-Base" and "Content-Location" headers. These headers
used to determine the base URL as defined in [HTTP]. For example
if the referring IMAP URL contains a "/;SECTION=1.2" parameter
then the MIME headers for section 1.2, for section 1, and for
enclosing message itself SHOULD be checked in that order
"Content-Base" or "Content-Location" headers

9. Multinational

IMAP4 [IMAP4] section 5.1.3 includes a convention for
non-US-ASCII characters in IMAP mailbox names. Because
convention is private to IMAP, it is necessary to convert IMAP'
encoding to one that can be more easily interpreted by a
display program. For this reason, IMAP's modified UTF-7
for mailboxes MUST be converted to UTF-8 [UTF8]. Since 8-
characters are not permitted in URLs, the UTF-8 characters

Newman Standards Track [Page 6]

RFC 2192 IMAP URL Scheme September 1997

encoded as required by the URL specification [BASIC-URL].
code is included in Appendix A to demonstrate this conversion

10.

The following examples demonstrate how an IMAP4 client
might translate various IMAP4 URLs into a series of IMAP4 commands
Commands sent from the client to the server are prefixed with "C:",
and responses sent from the server to the client are prefixed
"S:".

The URL

Results in the following client commands

C: A001 LOGIN ANONYMOUS sheridan@babylon5.
C: A002 SELECT gray-
C: A003 UID FETCH 20 BODY.PEEK[]

The URL

Results in the following client commands

requests password from user
encryption
C: A001 LOGIN MICHAEL
C: A002 LIST "" users.*

The URL

%E5%8F%B0%E5%8C%97>

Results in the following client commands

C: A001 LOGIN ANONYMOUS bester@psycop.psicorp.
C: A002 SELECT ~peter/&ZeVnLIqe-/&U,BTFw
<commands the client uses for viewing the contents of a mailbox

Newman Standards Track [Page 7]

RFC 2192 IMAP URL Scheme September 1997

The URL

KERBEROS_V4@minbari.org/gray-council/;uid=20/
;section=1.2>

Results in the following client commands

C: A001 AUTHENTICATE KERBEROS_V
<authentication exchange
C: A002 SELECT gray-
C: A003 UID FETCH 20 BODY.PEEK[1.2]

If the following relative URL is located in that body part

<;section=1.4>

This could result in the following client commands

C: A004 UID FETCH 20 (BODY.PEEK[1.2.MIME
BODY.PEEK[1.MIME
BODY.PEEK[HEADER.FIELDS (Content-Base Content-Location)])
Location headers
result. If no such headers, then it does the following
C: A005 UID FETCH 20 BODY.PEEK[1.4]

The URL

Could result in the following

C: A001
S: * CAPABILITY IMAP4rev1 AUTH=
S: A001
C: A002 AUTHENTICATE
<authentication exchange
S: A002 OK user lennier
C: A003 SELECT "gray council
...
C: A004 SEARCH SUBJECT
S: * SEARCH 8 10 13 14 15 16
S: A004 OK SEARCH
C: A005 FETCH 8,10,13:16
...

Newman Standards Track [Page 8]

RFC 2192 IMAP URL Scheme September 1997

NOTE: In this final example, the client has
dependent choices. The authentication mechanism could be anything
including PREAUTH. And the final FETCH command could fetch more
less information about the messages, depending on what it wishes
display to the user

11. Security

Security considerations discussed in the IMAP specification [IMAP4]
and the URL specification [BASIC-URL] are relevant.
considerations related to authenticated URLs are discussed
section 3 of this document

Many email clients store the plain text password for later
after logging into an IMAP server. Such clients MUST NOT use
stored password in response to an IMAP URL without
permission from the user to supply that password to the
host name

12. ABNF for IMAP URL

This uses ABNF as defined in RFC 822 [IMAIL]. Terminals from
BNF for IMAP [IMAP4] and URLs [BASIC-URL] are also used.
are not case sensitive and free insertion of linear-white-space
not permitted

achar = uchar / "&" / "=" / "~"
; see [BASIC-URL] for "uchar"

bchar = achar / ":" / "@" / "/"

enc_auth_type = 1*
; encoded version of [IMAP-AUTH] "auth_type

enc_list_mailbox = 1*
; encoded version of [IMAP4] "list_mailbox

enc_mailbox = 1*
; encoded version of [IMAP4] "mailbox

enc_search = 1*
; encoded version of search_program

enc_section = 1*
; encoded version of section

Newman Standards Track [Page 9]

RFC 2192 IMAP URL Scheme September 1997

enc_user = 1*
; encoded version of [IMAP4] "userid

imapurl = "imap://" iserver "/" [ icommand ]

iauth = ";AUTH=" ( "*" / enc_auth_type )

icommand = imailboxlist / imessagelist /

imailboxlist = [enc_list_mailbox] ";TYPE=" list_

imessagelist = enc_mailbox [ "?" enc_search ] [uidvalidity

imessagepart = enc_mailbox [uidvalidity] iuid [isection

isection = "/;SECTION=" enc_

iserver = [iuserauth "@"]
; See [BASIC-URL] for "hostport"

iuid = "/;UID=" nz_
; See [IMAP4] for "nz_number"

iuserauth = enc_user [iauth] / [enc_user]

list_type = "LIST" / "LSUB

search_program = ["CHARSET" SPACE astring SPACE
search_key *(SPACE search_key
; IMAP4 literals may not be
; See [IMAP4] for "astring" and "search_key

section = section_text / (nz_number *["." nz_number
["." (section_text / "MIME")])
; See [IMAP4] for "section_text" and "nz_number

uidvalidity = ";UIDVALIDITY=" nz_
; See [IMAP4] for "nz_number"

13.

[BASIC-URL] Berners-Lee, Masinter, McCahill, "Uniform
Locators (URL)", RFC 1738, CERN, Xerox Corporation, University
Minnesota, December 1994.

internic.net/rfc/rfc1738.txt

Newman Standards Track [Page 10]

RFC 2192 IMAP URL Scheme September 1997

[IMAP4] Crispin, M., "Internet Message Access Protocol -
4rev1", RFC 2060, University of Washington, December 1996.

internic.net/rfc/rfc2060.txt

[IMAP-AUTH] Myers, J., "IMAP4 Authentication Mechanism", RFC 1731,
Carnegie-Mellon University, December 1994.

internic.net/rfc/rfc1731.txt

[HTTP] Fielding, Gettys, Mogul, Frystyk, Berners-Lee, "
Transfer Protocol -- HTTP/1.1", RFC 2068, UC Irvine, DEC, MIT/LCS
January 1997.

internic.net/rfc/rfc2068.txt

[IMAIL] Crocker, "Standard for the Format of ARPA Internet
Messages", STD 11, RFC 822, University of Delaware, August 1982.

internic.net/rfc/rfc822.txt

[KEYWORDS] Bradner, "Key words for use in RFCs to
Requirement Levels", RFC 2119, Harvard University, March 1997.

internic.net/rfc/rfc2119.txt

[MIME] Freed, N., Borenstein, N., "Multipurpose Internet
Extensions", RFC 2045, Innosoft, First Virtual, November 1996.

internic.net/rfc/rfc2045.txt

[REL-URL] Fielding, "Relative Uniform Resource Locators", RFC 1808,
UC Irvine, June 1995.

internic.net/rfc/rfc1808.txt

[UTF8] Yergeau, F. "UTF-8, a transformation format of Unicode
ISO 10646", RFC 2044, Alis Technologies, October 1996.

internic.net/rfc/rfc2044.txt

14. Author's

Chris
Innosoft International, Inc
1050 Lakes
West Covina, CA 91790
EMail: chris.newman@innosoft.

Newman Standards Track [Page 11]

RFC 2192 IMAP URL Scheme September 1997

Appendix A. Sample

Here is sample C source code to convert between URL paths and
mailbox names, taking into account mapping between IMAP's modified UTF-7
[IMAP4] and hex-encoded UTF-8 which is more appropriate for URLs.
code has not been rigorously tested nor does it necessarily
reasonably with invalid input, but it should serve as a useful example
This code just converts the mailbox portion of the URL and does not
with parameters, query or server components of the URL

#include #include
/* hexadecimal lookup table */
static char hex[] = "0123456789ABCDEF";

/* URL unsafe printable characters */
static char urlunsafe[] = " \"#%&+:;<=>?@[\\]^`{|}";

/* UTF7 modified base64 alphabet */
static char base64chars[] =
"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+,";
#define UNDEFINED 64

/* UTF16 definitions */
#define UTF16MASK 0x03
#define UTF16SHIFT 10
#define UTF16BASE 0x10000
#define UTF16HIGHSTART 0xD800
#define UTF16HIGHEND 0
#define UTF16LOSTART 0xDC00
#define UTF16LOEND 0

/* Convert an IMAP mailbox to a URL
* dst needs to have roughly 4 times the storage space of
* Hex encoding can triple the size of the
* UTF-7 can be slightly denser than UTF-8
* (worst case: 8 octets UTF-7 becomes 9 octets UTF-8)
*/
void MailboxToURL(char *dst, char *src

unsigned char c, i, bitcount
unsigned long ucs4, utf16, bitbuf
unsigned char base64[256], utf8[6];

Newman Standards Track [Page 12]

RFC 2192 IMAP URL Scheme September 1997

/* initialize modified base64 decoding table */
memset(base64, UNDEFINED, sizeof (base64));
for (i = 0; i < sizeof (base64chars); ++i) {
base64[base64chars[i]] = i
}

/* loop until end of string */
while (*src != '\0') {
c = *src++;
/* deal with literal characters and &- */
if (c != '&' || *src == '-') {
if (c < ' ' || c > '~' || strchr(urlunsafe, c) != NULL) {
/* hex encode if necessary */
dst[0] = '%';
dst[1] = hex[c >> 4];
dst[2] = hex[c & 0x0f];
dst += 3;
} else {
/* encode literally */
*dst++ = c
}
/* skip over the '-' if this is an &- sequence */
if (c == '&') ++src
} else {
/* convert modified UTF-7 -> UTF-16 -> UCS-4 -> UTF-8 -> HEX */
bitbuf = 0;
bitcount = 0;
ucs4 = 0;
while ((c = base64[(unsigned char) *src]) != UNDEFINED) {
++src
bitbuf = (bitbuf << 6) | c
bitcount += 6;
/* enough bits for a UTF-16 character? */
if (bitcount >= 16) {
bitcount -= 16;
utf16 = (bitcount ? bitbuf >>
: bitbuf) & 0xffff
/* convert UTF16 to UCS4 */

(utf16 >= UTF16HIGHSTART && utf16 <= UTF16HIGHEND) {
ucs4 = (utf16 - UTF16HIGHSTART) << UTF16SHIFT
continue
} else
(utf16 >= UTF16LOSTART && utf16 <= UTF16LOEND) {
ucs4 += utf16 - UTF16LOSTART + UTF16BASE
} else {
ucs4 = utf16;
}

Newman Standards Track [Page 13]

RFC 2192 IMAP URL Scheme September 1997

/* convert UTF-16 range of UCS4 to UTF-8 */
if (ucs4 <= 0x7fUL) {
utf8[0] = ucs4;
i = 1;
} else if (ucs4 <= 0x7ffUL) {
utf8[0] = 0xc0 | (ucs4 >> 6);
utf8[1] = 0x80 | (ucs4 & 0x3f);
i = 2;
} else if (ucs4 <= 0xffffUL) {
utf8[0] = 0xe0 | (ucs4 >> 12);
utf8[1] = 0x80 | ((ucs4 >> 6) & 0x3f);
utf8[2] = 0x80 | (ucs4 & 0x3f);
i = 3;
} else {
utf8[0] = 0xf0 | (ucs4 >> 18);
utf8[1] = 0x80 | ((ucs4 >> 12) & 0x3f);
utf8[2] = 0x80 | ((ucs4 >> 6) & 0x3f);
utf8[3] = 0x80 | (ucs4 & 0x3f);
i = 4;
}
/* convert utf8 to hex */
for (c = 0; c < i; ++c) {
dst[0] = '%';
dst[1] = hex[utf8[c] >> 4];
dst[2] = hex[utf8[c] & 0x0f];
dst += 3;
}
}
}
/* skip over trailing '-' in modified UTF-7 encoding */
if (*src == '-') ++src
}
}
/* terminate destination string */
*dst = '\0';

/* Convert hex coded UTF-8 URL path to modified UTF-7 IMAP
* dst should be about twice the length of src to deal with non-
* coded
*/
void URLtoMailbox(char *dst, char *src

unsigned int utf8pos, utf8total, i, c, utf7mode, bitstogo, utf16flag
unsigned long ucs4, bitbuf
unsigned char hextab[256];

/* initialize hex lookup table */

Newman Standards Track [Page 14]

RFC 2192 IMAP URL Scheme September 1997

memset(hextab, 0, sizeof (hextab));
for (i = 0; i < sizeof (hex); ++i) {
hextab[hex[i]] = i
if (isupper(hex[i])) hextab[tolower(hex[i])] = i
}

utf7mode = 0;
utf8total = 0;
bitstogo = 0;
while ((c = *src) != '\0') {
++src
/* undo hex-encoding */
if (c == '%' && src[0] != '\0' && src[1] != '\0') {
c = (hextab[src[0]] << 4) | hextab[src[1]];
src += 2;
}
/* normal character? */
if (c >= ' ' && c <= '~') {
/* switch out of UTF-7 mode */
if (utf7mode) {
if (bitstogo) {
*dst++ = base64chars[(bitbuf << (6 - bitstogo)) & 0x3F];
}
*dst++ = '-';
utf7mode = 0;
}
*dst++ = c
/* encode '&' as '&-' */
if (c == '&') {
*dst++ = '-';
}
continue
}
/* switch to UTF-7 mode */
if (!utf7mode) {
*dst++ = '&';
utf7mode = 1;
}
/* Encode US-ASCII characters as themselves */
if (c < 0x80) {
ucs4 = c
utf8total = 1;
} else if (utf8total) {
/* save UTF8 bits into UCS4 */
ucs4 = (ucs4 << 6) | (c & 0x3FUL);
if (++utf8pos < utf8total) {
continue
}

Newman Standards Track [Page 15]

RFC 2192 IMAP URL Scheme September 1997

} else {
utf8pos = 1;
if (c < 0xE0) {
utf8total = 2;
ucs4 = c & 0x1F
} else if (c < 0xF0) {
utf8total = 3;
ucs4 = c & 0x0F
} else {
/* NOTE: can't convert UTF8 sequences longer than 4 */
utf8total = 4;
ucs4 = c & 0x03;
}
continue
}
/* loop to split ucs4 into two utf16 chars if necessary */
utf8total = 0;
do {
if (ucs4 >= UTF16BASE) {
ucs4 -= UTF16BASE
bitbuf = (bitbuf << 16) | ((ucs4 >> UTF16SHIFT
+ UTF16HIGHSTART);
ucs4 = (ucs4 & UTF16MASK) + UTF16LOSTART
utf16flag = 1;
} else {
bitbuf = (bitbuf << 16) | ucs4;
utf16flag = 0;
}
bitstogo += 16;
/* spew out base64 */
while (bitstogo >= 6) {
bitstogo -= 6;
*dst++ = base64chars[(bitstogo ? (bitbuf >> bitstogo
: bitbuf
& 0x3F];
}
} while (utf16flag);
}
/* if in UTF-7 mode, finish in ASCII */
if (utf7mode) {
if (bitstogo) {
*dst++ = base64chars[(bitbuf << (6 - bitstogo)) & 0x3F];
}
*dst++ = '-';
}
/* tie off string */
*dst = '\0';

Newman Standards Track [Page 16]

if you see any problems within the linking, don't worry be happy,
this is version 0.1 of the Relevance System and you gotta expect some crappy subroutines sometimes,
just be content we did not write this in Java, which would have made this "bigger and better" HAHAHHA.

RFC documents can be found at I.E.T.F.

Relevance System Copyright © 2002 Spectrum WorldResearch
other technical nosh by ServerMasters Corporation
collaboration of BobX