home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / drafts / draft_n_r / draft-newman-url-imap-06.txt < prev    next >
Text File  |  1997-03-04  |  20KB  |  564 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Network Working Group                                          C. Newman
  8. Internet Draft: IMAP URL Scheme                                 Innosoft
  9. Document: draft-newman-url-imap-06.txt                        March 1997
  10.  
  11.  
  12.                             IMAP URL Scheme
  13.  
  14.  
  15. Status of this memo
  16.  
  17.      This document is an Internet Draft.  Internet Drafts are working
  18.      documents of the Internet Engineering Task Force (IETF), its Areas,
  19.      and its Working Groups.  Note that other groups may also distribute
  20.      working documents as Internet Drafts.
  21.  
  22.      Internet Drafts are draft documents valid for a maximum of six
  23.      months.  Internet Drafts may be updated, replaced, or obsoleted by
  24.      other documents at any time.  It is not appropriate to use Internet
  25.      Drafts as reference material or to cite them other than as a
  26.      ``working draft'' or ``work in progress``.
  27.  
  28.      To learn the current status of any Internet-Draft, please check the
  29.      1id-abstracts.txt listing contained in the Internet-Drafts Shadow
  30.      Directories on ds.internic.net, nic.nordu.net, ftp.isi.edu, or
  31.      munnari.oz.au.
  32.  
  33.      A revised version of this draft document will be submitted to the
  34.      RFC editor as a Proposed Standard for the Internet Community.
  35.      Discussion and suggestions for improvement are requested.  This
  36.      document will expire six months after publication.  Distribution of
  37.      this draft is unlimited.
  38.  
  39.  
  40.  
  41. 1. Introduction
  42.  
  43.      IMAP [IMAP4] is a rich protocol for accessing remote message
  44.      stores.  It provides an ideal mechanism for accessing public
  45.      mailing list archives as well as private and shared message stores.
  46.      This document defines a URL scheme for referencing objects on an
  47.      IMAP server.
  48.  
  49.  
  50. 2. Conventions used in this document
  51.  
  52.      The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
  53.      in this document are to be interpreted as defined in RFC XXXX-
  54.      draft-bradner-key-words-03.txt.
  55.  
  56.  
  57.  
  58. Newman                                                          [Page 1]
  59.  
  60. Internet Draft              IMAP URL Scheme                   March 1997
  61.  
  62.  
  63. 3. IMAP scheme
  64.  
  65.      The IMAP URL scheme is used to designate mailboxes, messages, MIME
  66.      bodies [MIME], and search programs on Internet hosts accessible
  67.      using the IMAP protocol.
  68.  
  69.      The IMAP URL follows the common Internet scheme syntax as defined
  70.      in RFC 1738 [RFC1738].  If :<port> is omitted, the port defaults to
  71.      143.
  72.  
  73.      An IMAP URL takes one of the following forms:
  74.  
  75.          imap://<iserver>/<enc_list_mailbox>;TYPE=<list_type>
  76.          imap://<iserver>/<enc_mailbox>[uidvalidity][?<enc_search>]
  77.          imap://<iserver>/<enc_mailbox>[uidvalidity]<iuid>[isection]
  78.  
  79.      The first form is used to refer to a list of mailboxes, the second
  80.      form refers to the contents of a mailbox or a set of messages
  81.      resulting from a search, and the final form refers to a specific
  82.      message or message part.
  83.  
  84.  
  85. 4. IMAP User Name, Authentication Mechanism and Password
  86.  
  87.      A user name, authentication mechanism and/or password may be
  88.      supplied.  They are used in the "LOGIN" or "AUTHENTICATE" commands
  89.      after making the connection to the IMAP server.  If no user name,
  90.      authentication mechanism or password is supplied, the user name
  91.      "anonymous" is used with the "LOGIN" command and the password is
  92.      supplied as the Internet e-mail address of the end user accessing
  93.      the resource.  If the URL supplies a user name but no password, the
  94.      program interpreting the IMAP URL SHOULD request one from the user
  95.      if necessary.
  96.  
  97.      An authentication mechanism can be expressed by adding
  98.      ";AUTH=<enc_auth_type>" to the end of the user name.  When such an
  99.      <enc_auth_type> is indicated, the client SHOULD request appropriate
  100.      credentials from that mechanism and use the "AUTHENTICATE" command
  101.      instead of the "LOGIN" command.  If no user name is specified, one
  102.      SHOULD be obtained from the mechanism or requested from the user as
  103.      appropriate.
  104.  
  105.      The string ";AUTH=*" indicates that the client SHOULD select an
  106.      appropriate authentication mechanism.  It MAY use any mechanism
  107.      listed in the CAPABILITY command or use an out of band security
  108.      service resulting in a PREAUTH connection.  If no user name is
  109.      specified and no appropriate authentication mechanisms are
  110.      available, the client SHOULD fall back to anonymous login as
  111.  
  112.  
  113.  
  114. Newman                                                          [Page 2]
  115.  
  116. Internet Draft              IMAP URL Scheme                   March 1997
  117.  
  118.  
  119.      described above.  This allows a URL which grants read-write access
  120.      to authorized users, and read-only anonymous access to other users.
  121.  
  122.      Note that if unsafe or reserved characters such as " " or ";" are
  123.      present in the user name, authentication mechanism or password,
  124.      they MUST be encoded as described in RFC 1738 [RFC1738].
  125.  
  126.  
  127. 5. Lists of mailboxes
  128.  
  129.      An IMAP URL referring to a list of mailboxes has the following
  130.      form:
  131.  
  132.          imap://<iserver>/<enc_list_mailbox>;TYPE=<list_type>
  133.  
  134.      The <list_type> may be either "LIST" or "LSUB", and is case
  135.      insensitive.  The field ";TYPE=<list_type>" MUST be included.
  136.  
  137.      The <enc_list_mailbox> is any argument suitable for the
  138.      list_mailbox field of the IMAP [IMAP4] LIST or LSUB commands.  The
  139.      field <enc_list_mailbox> may be omitted, in which case the program
  140.      interpreting the IMAP URL may use "*" or "%" as the
  141.      <enc_list_mailbox>.  The program SHOULD use "%" if it supports a
  142.      hierarchical view, otherwise it SHOULD use "*".
  143.  
  144.      Note that if unsafe or reserved characters such as " " or "%" are
  145.      present in <enc_list_mailbox> they MUST be encoded as described in
  146.      RFC 1738 [RFC1738].  If the character "/" is present in
  147.      enc_list_mailbox, it SHOULD NOT be encoded.
  148.  
  149.  
  150. 6. Lists of messages
  151.  
  152.      An IMAP URL referring to a list of messages has the following form:
  153.  
  154.          imap://<iserver>/<enc_mailbox>[uidvalidity][?<enc_search>]
  155.  
  156.      The <enc_mailbox> field is used as the argument to the IMAP4
  157.      "SELECT" command.  Note that if unsafe or reserved characters such
  158.      as " ", ";", or "?" are present in <enc_mailbox> they MUST be
  159.      encoded as described in RFC 1738 [RFC1738].  If the character "/"
  160.      is present in enc_mailbox, it SHOULD NOT be encoded.
  161.  
  162.      The [uidvalidity] field is optional.  If it is present, it MUST be
  163.      the argument to the IMAP4 UIDVALIDITY status response at the time
  164.      the URL was created.  This SHOULD be used by the program
  165.      interpreting the IMAP URL to determine if the URL is stale.
  166.  
  167.  
  168.  
  169.  
  170. Newman                                                          [Page 3]
  171.  
  172. Internet Draft              IMAP URL Scheme                   March 1997
  173.  
  174.  
  175.      The [?<enc_search>] field is optional.  If it is not present, the
  176.      contents of the mailbox SHOULD be presented by the program
  177.      interpreting the URL.  If it is present, it SHOULD be used as the
  178.      arguments following an IMAP4 SEARCH command with unsafe characters
  179.      such as " " (which are likely to be present in the <enc_search>)
  180.      encoded as described in RFC 1738 [RFC1738].
  181.  
  182.  
  183. 7. A specific message or message part
  184.  
  185.      An IMAP URL referring to a specific message or message part has the
  186.      following form:
  187.  
  188.          imap://<iserver>/<enc_mailbox>[uidvalidity]<iuid>[isection]
  189.  
  190.      The <enc_mailbox> and [uidvalidity] are as defined above.
  191.  
  192.      If [uidvalidity] is present in this form, it SHOULD be used by the
  193.      program interpreting the URL to determine if the URL is stale.
  194.  
  195.      The <uid> refers to an IMAP4 message UID, and SHOULD be used as the
  196.      <set> argument to the IMAP4 "UID FETCH" command.
  197.  
  198.      The [isection] field is optional.  If not present, the URL refers
  199.      to the entire RFC 822 message as returned by the IMAP command "UID
  200.      FETCH <uid> RFC822.PEEK".  If present, the URL refers to the object
  201.      returned by a "UID FETCH <uid> BODY.PEEK[<section>]" command.  The
  202.      type of the object may be determined with a "UID FETCH <uid>
  203.      BODYSTRUCTURE" command and locating the appropriate part in the
  204.      resulting BODYSTRUCTURE.  Note that unsafe characters in
  205.      [isection], such as " " MUST be encoded as described in RFC 1738
  206.      [RFC1738].
  207.  
  208.  
  209. 8. Relative IMAP URLs
  210.  
  211.      Relative IMAP URLs are permitted and are resolved according to the
  212.      rules defined in RFC 1808 [RFC1808] with one exception.  When the
  213.      relative URL includes a "SECTION=" parameter and does not include a
  214.      "UID=" parameter, then the "UID=" parameter is inherited from the
  215.      base URL.  The following observations are also important:
  216.  
  217.      The <iauth> grammar element is considered part of the user name for
  218.      purposes of resolving relative IMAP URLs.  This means that unless a
  219.      new login/server specification is included in the relative URL, the
  220.      authentication mechanism is inherited from a base IMAP URL.
  221.  
  222.      URLs always use "/" as the hierarchy delimiter for the purpose of
  223.  
  224.  
  225.  
  226. Newman                                                          [Page 4]
  227.  
  228. Internet Draft              IMAP URL Scheme                   March 1997
  229.  
  230.  
  231.      resolving paths in relative URLs.  IMAP4 permits the use of any
  232.      hierarchy delimiter in mailbox names.  For this reason, relative
  233.      mailbox paths will only work if the mailbox uses "/" as the
  234.      hierarchy delimiter.  Relative URLs may be used on mailboxes which
  235.      use other delimiters, but in that case, the entire mailbox name
  236.      MUST be specified in the relative URL or inherited as a whole from
  237.      the base URL.
  238.  
  239.      The base URL for a list of mailboxes or messages which was referred
  240.      to by an IMAP URL is always the referring IMAP URL itself.  The
  241.      base URL for a message or message part which was referred to by an
  242.      IMAP URL may be more complicated to determine.  The program
  243.      interpreting the relative URL will have to check the headers of the
  244.      MIME entity and any enclosing MIME entities in order to locate the
  245.      "Content-Base" and "Content-Location" headers.  These headers are
  246.      used to determine the base URL as defined in [HTTP].  For example,
  247.      if the referring IMAP URL contains a ";SECTION=1.2" parameter, then
  248.      the MIME headers for section 1.2, for section 1, and for the
  249.      enclosing message itself SHOULD be checked in that order for
  250.      "Content-Base" or "Content-Location" headers.
  251.  
  252.  
  253. 9. Multinational Considerations
  254.  
  255.      IMAP4 [IMAP4] section 5.1.3 includes a convention for encoding
  256.      non-US-ASCII characters in IMAP mailbox names.  This convention MAY
  257.      be used in IMAP4 URLs, although this results in rather ugly URLs.
  258.  
  259.      Proposals have been made within the IETF to standardize a single
  260.      encoding for multinational characters in URLs.  Programs generating
  261.      and interpreting IMAP URLs may need to convert between IMAP's
  262.      international mailbox naming convention and any future standard for
  263.      multinational characters in URLs so that those characters can be
  264.      displayed unencoded to the user.
  265.  
  266.  
  267. 10. Examples
  268.  
  269.      The following examples demonstrate how an IMAP4 client program
  270.      might translate various IMAP4 URL into a series of IMAP4 commands.
  271.      Commands sent from the client to the server are prefixed with "C:",
  272.      and responses sent from the server to the client are prefixed with
  273.      "S:".
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282. Newman                                                          [Page 5]
  283.  
  284. Internet Draft              IMAP URL Scheme                   March 1997
  285.  
  286.  
  287.      The URL:
  288.  
  289.          <imap://minbari.org/gray-council;UIDVALIDITY=385759045;UID=20>
  290.  
  291.      Results in the following client commands:
  292.  
  293.          <connect to minbari.org, port 143>
  294.          C: A001 LOGIN ANONYMOUS sheridan@babylon5.org
  295.          C: A002 SELECT gray-council
  296.          <client verifies the UIDVALIDITY matches>
  297.          C: A003 UID FETCH 20 RFC822.PEEK
  298.  
  299.      The URL:
  300.  
  301.          <imap://michael@minbari.org/users.*;type=list>
  302.  
  303.      Results in the following client commands:
  304.  
  305.          <client requests password from user>
  306.          <connect to minbari.org, port 143>
  307.          C: A001 LOGIN MICHAEL zipper
  308.          C: A002 LIST "" users.*
  309.  
  310.      The URL:
  311.  
  312.          <imap://;AUTH=KERBEROS_V4@minbari.org/gray-council;uid=20;section=1.2>
  313.  
  314.      Results in the following client commands:
  315.  
  316.          <connect to minbari.org, port 143>
  317.          C: A001 AUTHENTICATE KERBEROS_V4
  318.          <authentication exchange>
  319.          C: A002 SELECT gray-council
  320.          C: A003 UID FETCH 20 BODY.PEEK[1.2]
  321.  
  322.      If the following relative URL is located in that body part:
  323.  
  324.           <;section=1.4>
  325.  
  326.      This could result in the following client commands:
  327.  
  328.          C: A004 UID FETCH 20 (BODY.PEEK[1.2.MIME]
  329.                  BODY.PEEK[1.MIME]
  330.                  BODY.PEEK[HEADER.FIELDS (Content-Base Content-Location)])
  331.          <Client looks for Content-Base or Content-Location headers in
  332.           result.  If no such headers, then it does the following>
  333.          C: A005 UID FETCH 20 BODY.PEEK[1.4]
  334.  
  335.  
  336.  
  337.  
  338. Newman                                                          [Page 6]
  339.  
  340. Internet Draft              IMAP URL Scheme                   March 1997
  341.  
  342.  
  343.      The URL:
  344.  
  345.          <imap://;AUTH=*@minbari.org/gray%20council?SUBJECT%20shadows>
  346.  
  347.      Could result in the following:
  348.  
  349.          <connect to minbari.org, port 143>
  350.          C: A001 CAPABILITY
  351.          S: * CAPABILITY IMAP4rev1 AUTH=GSSAPI
  352.          S: A001 OK
  353.          C: A002 AUTHENTICATE GSSAPI
  354.          <authentication exchange>
  355.          S: A002 OK user lennier authenticated
  356.          C: A003 SELECT "gray council"
  357.          ...
  358.          C: A004 SEARCH SUBJECT shadows
  359.          S: * SEARCH 8 10 13 14 15 16
  360.          S: A004 OK SEARCH completed
  361.          C: A005 FETCH 8,10,13:16 ALL
  362.          ...
  363.  
  364.      NOTE: In this final example, the client has implementation dependent
  365.      choices.  The authentication mechanism could be anything, including
  366.      PREAUTH.  And the final FETCH command could fetch more or less
  367.      information about the messages, depending on what it wishes to display
  368.      to the user.
  369.  
  370.  
  371. 11. ABNF for IMAP URL scheme
  372.  
  373.      This uses ABNF as used in the IMAP specification [IMAP4].
  374.      Terminals from the BNF for URLs [RFC1738] are also used.  Strings
  375.      are not case sensitive.
  376.  
  377.      achar            ::= uchar / "&" / "=" / "~"
  378.                              ; see RFC 1738 for "uchar" definition
  379.  
  380.      bchar            ::= achar / ":" / "@" / "/"
  381.  
  382.      enc_auth_type    ::= 1*achar
  383.                              ; encoded version of [IMAP-AUTH] "auth_type"
  384.  
  385.      enc_list_mailbox ::= 1*bchar
  386.                              ; encoded version of [IMAP4] "list_mailbox"
  387.  
  388.      enc_mailbox      ::= 1*bchar
  389.                              ; encoded version of [IMAP4] "mailbox"
  390.  
  391.  
  392.  
  393.  
  394. Newman                                                          [Page 7]
  395.  
  396. Internet Draft              IMAP URL Scheme                   March 1997
  397.  
  398.  
  399.      enc_pass         ::= *achar
  400.                              ; encoded version of [IMAP4] "password"
  401.  
  402.      enc_search       ::= 1*bchar
  403.                              ; encoded version of search_program below
  404.  
  405.      enc_section      ::= 1*bchar
  406.                              ; encoded version of section below
  407.  
  408.      enc_user         ::= *achar
  409.                              ; encoded version of [IMAP4] "userid"
  410.  
  411.      imapurl          ::= "imap://" iserver "/" [ icommand ] [ iauth ]
  412.  
  413.      iauth            ::= ";AUTH=" ( "*" / enc_auth_type )
  414.  
  415.      icommand         ::= imailboxlist / ipath / isearch
  416.  
  417.      imailboxlist     ::= [enc_list_mailbox] [ ";TYPE=" list_type ]
  418.  
  419.      ipath            ::= enc_mailbox [uidvalidity] iuid [isection]
  420.  
  421.      isearch          ::= enc_mailbox [ "?" enc_search ] [uidvalidity]
  422.  
  423.      isection         ::= ";SECTION=" enc_section
  424.  
  425.      iserver          ::= [enc_user [ iauth ] [ ":" enc_pass ] "@"] hostport
  426.                              ; See RFC 1738 for "hostport" definition
  427.  
  428.      iuid             ::= ";UID=" nz_number
  429.                              ; See [IMAP4] for "nz_number" definition
  430.  
  431.      list_type        ::= "LIST" / "LSUB"
  432.  
  433.      search_program   ::= ["CHARSET" SPACE astring SPACE] 1#search_key
  434.                              ; IMAP4 literals may not be used
  435.                              ; See [IMAP4] for "astring" and "search_key"
  436.  
  437.      section          ::= section_text / (nz_number *["." nz_number]
  438.                          ["." (section_text / "MIME")])
  439.                  ; See [IMAP4] for "section_text" and "nz_number"
  440.  
  441.      uidvalidity      ::= ";UIDVALIDITY=" nz_number
  442.                              ; See [IMAP4] for "nz_number" definition
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450. Newman                                                          [Page 8]
  451.  
  452. Internet Draft              IMAP URL Scheme                   March 1997
  453.  
  454.  
  455. 12. References
  456.  
  457.      [IMAP4] Crispin, M., "Internet Message Access Protocol - Version
  458.      4rev1", RFC 2060, University of Washington, December 1996.
  459.  
  460.          <ftp://ds.internic.net/rfc/rfc2060.txt>
  461.  
  462.      [IMAP-AUTH] Myers, J., "IMAP4 Authentication Mechanism", RFC 1731,
  463.      Carnegie-Mellon University, December 1994.
  464.  
  465.          <ftp://ds.internic.net/rfc/rfc1731.txt>
  466.  
  467.      [MIME] Freed, N., Borenstein, N., "Multipurpose Internet Mail
  468.      Extensions", RFC 2045, Innosoft, First Virtual, November 1996.
  469.  
  470.         <ftp://ds.internic.net/rfc/rfc2045.txt>
  471.  
  472.      [RFC1738] Berners-Lee, Masinter, McCahill, "Uniform Resource
  473.      Locators (URL)", RFC 1738, CERN, Xerox Corporation, University of
  474.      Minnesota, December 1994.
  475.  
  476.          <ftp://ds.internic.net/rfc/rfc1738.txt>
  477.  
  478.      [RFC1808] Fielding, "Relative Uniform Resource Locators", RFC 1808,
  479.      UC Irvine, June 1995.
  480.  
  481.          <ftp://ds.internic.net/rfc/rfc1808.txt>
  482.  
  483.      [HTTP] Fielding, Gettys, Mogul, Frystyk, Berners-Lee, "Hypertext
  484.      Transfer Protocol -- HTTP/1.1", RFC 2068, UC Irvine, DEC, MIT/LCS,
  485.      January 1997.
  486.  
  487.          <ftp://ds.internic.net/rfc/rfc2068.txt>
  488.  
  489.  
  490. 13. Security Considerations
  491.  
  492.      IMAP URLs have the same security considerations as general Internet
  493.      URLs [RFC1738].  Specifically, including passwords in the URL makes
  494.      the password vulnerable to network eavesdroppers both when the URL
  495.      is transmitted and when the "LOGIN" command is sent to the IMAP
  496.      server.  Some web browsers store URLs in history files which may
  497.      expose them further.  For these reasons, passwords SHOULD NOT be in
  498.      the URL.
  499.  
  500.      Security considerations discussed in the IMAP specification [IMAP4]
  501.      are also relevant.
  502.  
  503.  
  504.  
  505.  
  506. Newman                                                          [Page 9]
  507.  
  508. Internet Draft              IMAP URL Scheme                   March 1997
  509.  
  510.  
  511.      Client authors SHOULD be careful when selecting an authentication
  512.      mechanism if ";AUTH=*" is specified.  Clients SHOULD NOT fall back
  513.      to the "LOGIN" command with a user other than "anonymous".  A
  514.      client which violates this rule is vulnerable to an active attacker
  515.      which spoofs the server and does not declare support for any
  516.      AUTHENTICATE mechanisms.
  517.  
  518.      Many email clients store the plain text password for later use
  519.      after logging into an IMAP server.  Such clients MUST NOT use a
  520.      stored password in response to an IMAP URL without explicit
  521.      permission from the user to supply that password to the specified
  522.      host name.
  523.  
  524.  
  525. 14. Author's Address
  526.  
  527.      Chris Newman
  528.      Innosoft International, Inc.
  529.      1050 East Garvey Ave. South
  530.      West Covina, CA 91790 USA
  531.  
  532.      Email: chris.newman@innosoft.com
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562. Newman                                                         [Page 10]
  563.  
  564.