draft-ietf-extra-imap-list-myrights.xml

<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd'
[
<!ENTITY rfc2119 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml'>
<!ENTITY rfc3501 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.3501.xml'>
<!ENTITY rfc4314 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4314.xml'>
<!ENTITY rfc5234 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5234.xml'>
<!ENTITY rfc5258 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5258.xml'>
<!ENTITY rfc5819 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5819.xml'>
<!ENTITY rfc8174 PUBLIC ''
'http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml'>
]>

<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc strict="yes"?>
<rfc category="std" ipr='trust200902'
     docName='draft-ietf-extra-imap-list-myrights-07'>
  <front>
    <title abbrev="IMAP LIST-MYRIGHTS">IMAP4 Extension for Returning
    MYRIGHTS Information in Extended LIST</title>

    <author initials="K." surname="Murchison" fullname="Kenneth Murchison">
      <organization abbrev="FastMail">FastMail Pty Ltd</organization>
      <address>
        <postal>
          <street>Level 2, 114 William Street</street>
          <city>Melbourne</city> <region>VIC</region>
          <code>3000</code> <country>Australia</country>
        </postal>
        <email>murch@fastmailteam.com</email>
      </address>
    </author>

    <author initials="B." surname="Gondwana" fullname="Bron Gondwana">
      <organization abbrev="FastMail">FastMail Pty Ltd</organization>
      <address>
        <postal>
          <street>Level 2, 114 William Street</street>
          <city>Melbourne</city> <region>VIC</region>
          <code>3000</code> <country>Australia</country>
        </postal>
        <email>brong@fastmailteam.com</email>
      </address>
    </author>

    <date />

    <area>ART</area>
    <workgroup>EXTRA</workgroup>

    <keyword>IMAP4</keyword>
    <keyword>LIST</keyword>
    <keyword>MYRIGHTS</keyword>
    <abstract>
      <t>This document defines an extension to the Internet Message
      Access Protocol (IMAP) LIST 
      command that allows the client to request the set of rights that
      the logged-in user has been granted on mailboxes, along with other
      information typically returned by the LIST command.</t>
    </abstract>

  </front>

  <middle>
    <section title='Introduction'>
      <t><xref target='RFC3501'>IMAP</xref> clients typically fetch
      the set of rights granted on
      mailboxes so they can expose the allowed functionality to the
      logged-in user.  In order to do that, the client is 
      forced to issue a LIST or LSUB command to list all available
      mailboxes, followed by a MYRIGHTS command for each mailbox
      found.  This document defines an extension to the to IMAP LIST
      command that is identified by the capability string
      "LIST-MYRIGHTS".  The LIST-MYRIGHTS extension allows the client
      to request the set of rights that the logged-in user has been
      granted on mailboxes, along with other information typically
      returned by the LIST command.</t>
    </section>

    <section title='Conventions Used in This Document'>
      <t>In examples, "C:" indicates lines sent by a client that is connected
      to a server.  "S:" indicates lines sent by the server to the
      client.</t>

      <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
      NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",
      "MAY", and "OPTIONAL" in this document are to be interpreted as
      described in
      <eref target="https://tools.ietf.org/html/bcp14">BCP 14</eref>
      <xref target='RFC2119' /> <xref target='RFC8174' /> 
      when, and only when, they appear in all capitals, as shown
      here.</t>

    </section>  <!-- Intro -->
    
    <section title='MYRIGHTS Return Option to LIST Command'
             anchor="myrights">
      <t><xref target='RFC4314'/> defines the MYRIGHTS command which is
      used by an IMAP client to determine the set of rights that the
      logged-in user has been granted on a given mailbox.  Frequently,
      a client will have to look up the rights for some or all of
      the mailboxes returned by the LIST command.  Doing so in
      multiple MYRIGHTS commands wastes bandwidth and can degrade
      performance if the client does not pipeline the requests.</t>

      <t>This document extends the LIST command with a new "MYRIGHTS"
      <xref target='RFC5258'>return option</xref>,
      which allows the client to request all of the
      desired information in a single command.  For each listable
      mailbox matching the list pattern and selection options, the
      server MUST return an untagged LIST response and SHOULD also
      return an untagged MYRIGHTS response containing the set of
      rights granted to the logged-in user.  The ordering of the
      responses is significant only in that the server MUST NOT send a
      MYRIGHTS response for a given mailbox before it sends the LIST
      response for that mailbox.</t> 

      <t>If the server is unable to look up the set of rights for a
      given mailbox, it does not send the MYRIGHTS reply for that
      mailbox.</t>

      <t>Client authors ought to note that generating the MYRIGHTS
      responses for a large number of mailboxes may be an expensive
      operation for the server.  Clients SHOULD use a suitable match
      pattern and/or selection option to limit the set of mailboxes
      returned to only those whose rights in which they are
      interested.</t>
    </section>  <!-- MYRIGHTS -->

    <section title='Examples'>

      <figure>
	<preamble>
	  In this example the "bar" mailbox doesn't exist, so it has
          no MYRIGHTS reply.
	</preamble>
        <artwork><![CDATA[
C: A01 LIST "" % RETURN (MYRIGHTS)
S: * LIST () "." "INBOX"
S: * MYRIGHTS "INBOX" lrswipkxtecda
S: * LIST () "." "foo"
S: * MYRIGHTS "foo" lrs
S: * LIST (\NonExistent) "." "bar"
S: A01 OK List completed.
]]></artwork>
      </figure>

      <figure>
	<preamble>
	  In this example the LIST reply for the "foo" mailbox is
          returned because it has matching children, but no MYRIGHTS
          reply is returned because "foo" itself doesn't match the
          selection criteria.
	</preamble>
        <artwork><![CDATA[
C: A02 LIST (SUBSCRIBED RECURSIVEMATCH) "" % RETURN (MYRIGHTS)
S: * LIST (\Subscribed) "." "INBOX"
S: * MYRIGHTS "INBOX" lrswipkxtecda
S: * LIST () "." "foo" (CHILDINFO ("SUBSCRIBED"))
S: A02 OK List completed.
]]></artwork>
      </figure>

    </section>

    <section title='Formal Syntax'>
      <t>The following syntax specification uses the augmented Backus-Naur
      Form (BNF) as described in <xref target='RFC5234' />.  Terms not
      defined here are taken from <xref target='RFC5258' />. </t>

      <figure><artwork><![CDATA[
return-option =/ "MYRIGHTS"
]]></artwork></figure>
    </section>

    <section title='Security Considerations' anchor='security'>
      <t>In addition to the security considerations described in <xref
      target="RFC4314" />,
      this extension makes it a bit easier for clients to overload
      the server by requesting MYRIGHTS information for a large number
      of mailboxes.  However, as already noted in the introduction,
      existing clients already try to do that by generating a large
      number of MYRIGHTS commands for each mailbox in which they are
      interested.  While performing MYRIGHTS information retrieval for
      big lists of mailboxes, a server implementation needs to make
      sure that it can still serve other IMAP connections and yield
      execution to other connections, when necessary.</t>
    </section>

    <section title='Privacy Considerations' anchor='privacy'>
      <t>This specification does not introduce any additional privacy
      concerns beyond those described in <xref target="RFC4314" />.</t>
    </section>

    <section title='IANA Considerations'>
      <section title='Registration of IMAP capability LIST-MYRIGHTS'>
        <t>This document defines the "LIST-MYRIGHTS" IMAP capability
        to be added to the "IMAP Capabilities" registry: <eref
        target='https://www.iana.org/assignments/imap-capabilities/imap-capabilities.xhtml#imap-capabilities-1'
        />.</t>
      </section>

      <section title="Registration of LIST-EXTENDED option MYRIGHTS">
	<t>This section registers the "MYRIGHTS" option to be added to the
        "LIST-EXTENDED options" registry: <eref
        target='https://www.iana.org/assignments/imap-list-extended/imap-list-extended.xhtml#imap-list-extended-1'
        />.
	<list style='hanging'>
	  <t hangText="LIST-EXTENDED option name:">
	    MYRIGHTS
	  </t>
	  <t hangText="LIST-EXTENDED option type:">
	    RETURN
	  </t>
	  <t hangText="LIST-EXTENDED option description:">
	    Causes the LIST command to return MYRIGHTS responses in
            addition to LIST responses.
	  </t>
	  <t hangText="Published specification:">
	    RFC XXXX, <xref target="myrights" />
	  </t>
	  <t hangText="Security considerations:">
	    RFC XXXX, <xref target="security" />
	  </t>
	  <t hangText="Intended usage:">
	    COMMON
	  </t>
	  <t hangText="Person and email address to contact for further
                       information:">
	    Kenneth Murchison &lt;murch@fastmail.com&gt;
	  </t>
	  <t hangText="Owner/Change controller:">
	    IESG &lt;iesg@ietf.org&gt;
	  </t>
	</list>
	</t>
      </section>
    </section> <!-- IANA -->

    <section title='Acknowledgments'>
      <t>This document is based largely on <xref target="RFC5819" />.
      The authors would like to thank the authors of that document for
      providing both inspiration and some borrowed text for this
      document.
      The authors would also like to thank the following individuals for
      contributing their ideas and support for writing this
      specification: Barry Leiba.</t>
<!--
      <t>The author would also like to thank the following individuals for
      contributing their ideas and support for writing this
      specification: Cyrus Daboo.</t>
-->
    </section>

  </middle>

  <back>
    <references title='Normative References'>
      &rfc2119;
      &rfc3501;
      &rfc4314;
      &rfc5234;
      &rfc5258;
      &rfc8174;
    </references>

    <references title='Informative References'>
      &rfc5819;
    </references>

    <section title="Change History (To be removed by RFC Editor before
    publication)">
      <t>Changes from draft-ietf-extra-imap-list-myrights-06:
      <list style='symbols'>
        <t>Editorial fix.</t>
      </list>
      </t>

      <t>Changes from draft-ietf-extra-imap-list-myrights-05:
      <list style='symbols'>
        <t>Updated Keywords boilerplate.</t>
        <t>Referenced security concerns in RFC 4314.</t>
        <t>Reworded first sentence in second paragraph of Section 3.</t>
        <t>Added informative reference to RFC5819.</t>
      </list>
      </t>

      <t>Changes from draft-ietf-extra-imap-list-myrights-04:
      <list style='symbols'>
        <t>Added references for "IMAP" and "return option".</t>
      </list>
      </t>

      <t>Changes from draft-ietf-extra-imap-list-myrights-03:
      <list style='symbols'>
        <t>Fixed a typo in the Abstract.</t>
      </list>
      </t>

      <t>Changes from draft-ietf-extra-imap-list-myrights-02:
      <list style='symbols'>
        <t>WGLC editorial changes from Barry Leiba.</t>
      </list>
      </t>

      <t>Changes from draft-ietf-extra-imap-list-myrights-01:
      <list style='symbols'>
        <t>Removed 'n' right from example.</t>

        <t>Added advice to client authors regarding expense of
        calculating MYRIGHTS.</t>

        <t>Replicated Security Considerations section from RFC 5819.</t>
      </list>
      </t>

      <t>Changes from draft-ietf-extra-imap-list-myrights-00:
      <list style='symbols'>
        <t>Corrected contact email address in IANA registration.</t>

        <t>Fixed typos (extra SP) in examples.</t>
      </list>
      </t>

      <t>Changes from draft-murchison-imap-list-myrights-01:
      <list style='symbols'>
        <t>Renamed document to be a work product of the EXTRA WG.</t>

        <t>Updated authors' addresses.</t>
      </list>
      </t>

      <t>Changes from draft-murchison-imap-list-myrights-00:
      <list style='symbols'>
        <t>Augmented Introduction with mention of "LIST-MYRIGHTS"
        capability string.</t>

        <t>Minor editorial changes.</t>
      </list>
      </t>
    </section>

  </back>
</rfc>