xep-0052.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM "xep.ent">
  %ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>File Transfer</title>
  <abstract>A protocol for transferring a file between two Jabber IDs.</abstract>
  &LEGALNOTICE;
  <number>0052</number>
  <status>Retracted</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XMPP IM</spec>
    <spec>XEP-0004</spec>
    <spec>XEP-0020</spec>
    <spec>XEP-0030</spec>
  </dependencies>
  <supersedes/>
  <supersededby>
    <spec>XEP-0095</spec>
    <spec>XEP-0096</spec>
  </supersededby>
  <shortname>N/A</shortname>
  &temas;
  &linuxwolf;
  &infiniti;
  <revision>
    <version>0.2.1</version>
    <date>2018-11-03</date>
    <initials>pep</initials>
    <remark>Fix a bunch of typos, batch-style.</remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2003-09-30</date>
    <initials>psa</initials>
    <remark>At the request of the authors, the status of this document has been changed to Retracted since it has been superseded by XEP-0095 and XEP-0096.</remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2002-12-03</date>
    <initials>tjm</initials>
    <remark>Initial version, based on original XEP-0052 revision 0.1.</remark>
  </revision>
</header>

<section1 topic='Introduction'>
  <p>
    This document describes the http://www.jabber.org/protocol/filexfer
    namespace, which is used for offering and transferring files from one Jabber
    ID to another.  It tries to expand the basic method (iq:oob) that currently
    exists to allow for numerous stream methods, and more detailed file
    information before accepting an offer.  This document only describes the
    negotiation method and suggests how streams could link back to the
    negotiated information.
  </p>
</section1>

<section1 topic='Use Cases'>
  <p>
    This document covers one use case of sending a file to another user.  Future specifications
    may enhance this to include searching and offering.
  </p>

  <section2 topic='Send File Use Case'>
    <p>Primary Flow:</p>
    <ol>
      <li>Determine if the receiver supports FT through disco/browse. [E1]</li>
      <li>Sender sends metadata and available methods to receiver</li>
      <li>Receiver sends the accepted method to Sender and any range/offset
        information. [E2],[E3]</li>
      <li>Sender and Receiver establish the negotiated method[E4]</li>
      <li>Sender sends data as described by method</li>
      <li>After the stream closes the Receiver notifies the Sender of
        completion.  [E5]</li>
      <li>END</li>
    </ol>
    <p>Errors Conditions:</p>
    <ol>
      <li>User does not support filetransfer.  END</li>
      <li>Receiver rejects send.  END</li>
      <li>Receiver does not have any methods shared with the sender.  END</li>
      <li>The stream is unable to be started.  END</li>
      <li>The Receiver notifies sender of an error transferring.  END</li>
    </ol>
  </section2>
</section1>

<section1 topic='Basic Usage'>

  <p>
    In order to send a file, the sender must first tell the receiver a little
    bit about the file to make sure they will accept it.  At the same time they
    list the stream methods they support in the order they wish to use them.
    This is done by sending the information in the http://www.jabber.org/protocol/filexfer namespace.
  </p>

  <example caption='Generic Offer'>
    &lt;iq type='set' id='ft_1' to='recvr@jabber.org/Home'&gt;
      &lt;file xmlns='http://www.jabber.org/protocol/filexfer'
              action='offer'
              id='a0'
              name='myfile.txt'
              size='1024'
              mime-type='text/plain'&gt;
        &lt;feature xmlns='http://jabber.org/protocol/feature-neg'&gt;
          &lt;x xmlns='jabber:x:data'&gt;
            &lt;field var='file-transfer-method' type='list-single'&gt;
              &lt;option&gt;&lt;value&gt;jabber:iq:oob&lt;/value&gt;&lt;/option&gt;
            &lt;/field&gt;
          &lt;/x&gt;
        &lt;/feature&gt;
      &lt;/file&gt;
    &lt;/iq&gt;
  </example>

  <p>
    That is the basic request, a more complete requeset with range support is
    shown below.
  </p>

  <example caption='Complete File Offer'>
    &lt;iq type='set' id='ft_1' to='recvr@jabber.org/Home'&gt;
      &lt;file xmlns='http://www.jabber.org/protocol/filexfer'
            action='offer'
            id='a0'
            name='myfile.txt'
            size='1024'
            mime-type='text/plain'
            date='20020412T00:00:00'
            hash='23e4ad6b63343b33a333c334'&gt;
        &lt;desc&gt;A cool file&lt;/desc&gt;
        &lt;range/&gt;
        &lt;feature xmlns='http://jabber.org/protocol/feature-neg'&gt;
          &lt;x xmlns='jabber:x:data'&gt;
            &lt;field var='file-transfer-method' type='list-single'&gt;
              &lt;option&gt;&lt;value&gt;jobs&lt;/value&gt;&lt;/option&gt;
              &lt;option&gt;&lt;value&gt;dtcp&lt;/value&gt;&lt;/option&gt;
              &lt;option&gt;&lt;value&gt;jabber:iq:oob&lt;/value&gt;&lt;/option&gt;
              &lt;option&gt;&lt;value&gt;ibb&lt;/value&gt;&lt;/option&gt;
            &lt;/field&gt;
          &lt;/x&gt;
        &lt;/feature&gt;
      &lt;/file&gt;
    &lt;/iq&gt;
  </example>

  <p>If a receiver decides to accept an offered file they request it from the sending with an &lt;iq/&gt; type result. The receiver sends back the id of the file being sent, the method they wish to use, and the range they wish to download (if the sender announced support). When range support is being used the receiver MUST specify the length and MAY specify a beginning offset with the acceptance.</p>

  <example caption='Request the Offered File'>
    &lt;iq type='result' id='ft_req_1' to='sender@jabber.org/res'&gt;
      &lt;file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='get'&gt;
        &lt;feature xmlns='http://jabber.org/protocol/feature-neg'&gt;
          &lt;x xmlns='jabber:x:data'&gt;
            &lt;field var='file-transfer-method'&gt;
              &lt;option&gt;&lt;value&gt;jabber:iq:oob&lt;/value&gt;&lt;/option&gt;
            &lt;/field'&gt;
          &lt;/x&gt;
        &lt;/feature&gt;
      &lt;/file&gt;
    &lt;/iq&gt;
  </example>

  <example caption='Accept the Offered File with a Range and Offset'>
    &lt;iq type='result' id='ft_req_q' to='sender@jabber.org/res'&gt;
      &lt;file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='get'&gt;
        &lt;range offset='100' length='500' /&gt;
          &lt;x xmlns='jabber:x:data'&gt;
            &lt;field var='file-transfer-method'&gt;
              &lt;option&gt;&lt;value&gt;jobs&lt;/value&gt;&lt;/option&gt;
            &lt;/field&gt;
          &lt;/x&gt;
        &lt;/feature&gt;
      &lt;/file&gt;
    &lt;/iq&gt;
  </example>

  <p>
    If the receiver decides to not accept the file they SHOULD send back an
    error 403 to the sender.
  </p>

  <example caption='Declining the Offered File'>
    &lt;iq type='error' id='ft_1' to='sender@jabber.org/res'&gt;
      &lt;error code='403'&gt;Offer Declined&lt;/error&gt;
    &lt;/iq&gt;
  </example>

  <p>
    If the receiver does not support any of the offered stream methods they
    SHOULD send back an error 406 to the sender.
  </p>

  <example caption='No Acceptable Methods'>
    &lt;iq type='error' id='ft_1' to='sender@jabber.org/res'&gt;
      &lt;error code='406'&gt;No Acceptable Methods&lt;/error&gt;
    &lt;/iq&gt;
  </example>

  <p>
    At this point the sender will setup the stream method and begin to transfer
    data.  The stream itself can use the file transfer namespace to tie the
    metadata to the actual data sent, this is illustrated below using iq:oob.
  </p>

  <example caption='Starting an iq:oob transfer'>
    &lt;iq type='set' id='ft_oob_1' to='recvr@jabber.org/Home'&gt;
      &lt;file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='start'/&gt;
      &lt;query xmlns='jabber:iq:oob'&gt;
        &lt;url&gt;http://www.jabber.org/file.txt&lt;/url&gt;
        &lt;desc&gt;Here is the file&lt;/desc&gt;
      &lt;/query&gt;
    &lt;/iq&gt;
  </example>

  <p>
    If the receiver is unable to start the negotiated stream for any reason they
    should send an &lt;error/&gt; with a 502 code to the sender.
  </p>

  <example caption='Unable to Start Stream'>
    &lt;iq type='error' id='ft_oob_e_1' to='sender@jabber.org/res'&gt;
      &lt;file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='error'/&gt;
      &lt;error code='502'&gt;Unable to Start Stream&lt;/error&gt;
    &lt;/iq&gt;
  </example>

  <p>
    Once the data has been transferred the receiver SHOULD send the sender a
    notification that the transfer completed.  This is done by sending an
    &lt;iq/&gt; type set with the file id and a completed action.
  </p>

  <example caption='Completed Transfer Notification'>
    &lt;iq type='set' id='ft_c_1' to='sender@jabber.org/res'&gt;
      &lt;file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='complete' /&gt;
    &lt;/iq&gt;
  </example>

  <p>
    If the transfer does not complete, for any reason after the metadata
    negotiation, the party that has the error SHOULD send an error 500 and
    the file id to the other party.
  </p>

  <example caption='Failed Transfer Error'>
    &lt;iq type='error' id='ft_1' to='sender@jabber.org/res'&gt;
      &lt;error code='500'&gt;File Transfer Failed&lt;/error&gt;
      &lt;file xmlns='http://www.jabber.org/protocol/filexfer' id='a0' action='error'/&gt;
    &lt;/iq&gt;
  </example>

</section1>
<section1 topic='Stream Relation'>
  <p>By staying in just the realm of negotiating the metadata to a file, we allow for multiple transport layers, or streams, to be used. Some streams will need to tie the metadata to the actual data transfer, to help accomodate this the stream may use the &lt;file/&gt; with an action of start and the correct id. The &lt;file/&gt; could be transported in the stream negotiations, or along side it. Although this spec does not mandate any specific methods to new stream authors, it does provide the syntax for the currently existing "iq:oob" system.</p>
  <section2 topic='"iq:oob" Relation'>
    <p>For an "iq:oob" transfer to be related to its metadata, a &lt;file/&gt; is transported along side the &lt;query/&gt;. The id used on the &lt;file/&gt; is the id for the metadata of the actual data that is being sent. The action on the &lt;file/&gt; is "start".  An example of this can be found in the Basic Usage section.</p>
  </section2>
</section1>
<section1 topic='Formal Description'>
  <section2 topic='DTD'>
    <code><![CDATA[
<!ELEMENT file  ( ( desc )? | ( range )? | ( PCDATA )* ) >
<!ELEMENT desc    ( #PCDATA )*  >
<!ELEMENT range   EMPTY         >

<!ATTLIST file
    id        CDATA   #REQUIRED
    action    "offer" | "get" | "complete" | "start" | "error"  #IMPLIED "offer"
    name      CDATA   #OPTIONAL
    size      CDATA   #OPTIONAL >
    mime-type CDATA   #OPTIONAL
    date      CDATA   #OPTIONAL
    hash      CDATA   #OPTIONAL
<!ATTLIST range
    length    CDATA   #OPTIONAL
    offset    CDATA   #OPTIONAL >
]]></code>
  </section2>
  <section2 topic='&lt;file/&gt; Element'>
    <p>The &lt;file/&gt; element is the "workhorse" element. This element is used to convey metadata and report file transfer actions. This elemnt contains attributes for file metadata and actions, and MAY contain a &lt;desc/&gt;, a &lt;range/&gt;, and zero or more &lt;feature xmlns='jabber:iq:negotiate'/&gt; (&xep0020;) elements.</p>
    <p>The "id" attribute specifies the identifier for this particular file transfer. This attribute MUST be present at all times. There are no value requirements other than it MUST be unique between the sender and receiver.</p>
    <p>The "action" attribute specifies the action to undertake with the given file. This attribute SHOULD be present in most cases. If not present, the value "offer" is implied. The value of "action" MUST be one of the following:</p>
    <table caption='Possible "action" values'>
      <tr>
        <th>Value</th>
        <th>Description</th>
      </tr>
      <tr>
        <td>complete</td>
        <td>The file transfer is complete.</td>
      </tr>
      <tr>
        <td>get</td>
        <td>The file transfer should start.</td>
      </tr>
      <tr>
        <td>offer</td>
        <td>The file transfer is offered (metadata MUST be present)</td>
      </tr>
      <tr>
        <td>start</td>
        <td>The file transfer is starting.</td>
      </tr>
      <tr>
        <td>error</td>
        <td>The file transfer has failed.  The outlying error tag has more
          information.
        </td>
      </tr>
    </table>
    <p>The "name" attribute specifies the file name. This attribute MUST be present if the action is "offer", otherwise it SHOULD NOT be present.</p>
    <p>The "size" attribute specifies the file size, in bytes. This attribute MUST be present if the action is "offer", otherwise it SHOULD NOT be present.</p>
    <p>The "mime-type" attribute specifies the MIME-type for the file. This attribute SHOULD be present if the action is "offer", otherwise it SHOULD NOT be present. The value of this attribute MUST follow the specification for MIME-types from RFC-2046<note>RFC 2046: "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types" -- <link url='http://www.ietf.org/rfc/rfc2046.txt'>http://www.ietf.org/rfc/rfc2046.txt</link></note>.</p>
    <p>The "date" attribute specifies the file date. This attribute MAY be present if the action is "offer", otherwise it SHOULD NOT be present. The value MUST follow the specification for ISO 8601 date/time formats<note>ISO 8601: "[Summary of the] International Standard Date and Time Notation" -- <link url='http://www.cl.cam.ac.uk/~mgk25/iso-time.html'>http://www.cl.cam.ac.uk/~mgk25/iso-time.html</link></note>.</p>
    <p>The "hash" attribute specifies the hash of the file contents. This attribute MAY be present if the action is "offer", otherwise it SHOULD NOT be present. The value MUST be an SHA1 hash of the file contents.</p>
  </section2>
  <section2 topic='&lt;desc/&gt; Element'>
    <p>The &lt;desc/&gt; element contains a human-readable description of the file. This element has no attributes, and contains character data content.</p>
  </section2>
  <section2 topic='&lt;range/&gt; Element'>
    <p>The &lt;range/&gt; element describes range information for a partial transfer. This element has attributes to define the range length and range offset.  This element contains no content.</p>
    <p>The "length" attribute defines the range length, in bytes. This attribute MUST be present if the containing &lt;file/&gt; has an action value of "get", otherwise it SHOULD NOT be present. The value of this attribute MUST be an integer value and MUST be less than or equal to the (size + offset) of the file.</p>
    <p>The "offset" attribute defines the range offset, in bytes. This attribute MAY be present if the containing &lt;file/&gt; has an action value of "get", otherwise it SHOULD NOT be present. If this attribute is not present, a value of 0 is implied. The value of this attribute MUST be an integer, MUST NOT be less than 0, and MUST be less than (size - length).</p>
  </section2>
  <section2 topic='Error Descriptions'>
    <p>There are three main error conditions in file transfer.  Following are the
      conditions, error codes and descriptions:</p>
      <ul>
        <li>
          <em>Declining Transfer (403)</em>:  During the metadata negotiation
          the receiver may decline the transfer by sending the 403 error.  The
          &lt;error/&gt; CDATA MAY contain a descriptive reason why, but is not
          necessary.
        </li>
        <li>
          <em>No Available Methods (406)</em>:  When the sender presents the
          available stream methods, and the receiver can not use any of them,
          they send a 406 error.  The &lt;error/&gt; CDATA is not important.
        </li>
        <li>
          <em>Transfer Failed (500)</em>:  If the file transfer fails for any
          reason after negotiation, the error generator SHOULD send a 500 error
          to the other party.  This is the only error message that both the
          sender and reciever may send.  The &lt;error/&gt; CDATA MAY contain
          information about the failure.
        </li>
        <li>
          <em>Unable to Start Stream (502)</em>:  When the receiver is unable to
          start the negotiated stream method they send a 502 error to the
          sender.  The &lt;error/&gt; CDATA is not important.
        </li>
      </ul>
  </section2>
</section1>

<section1 topic='Security Considerations'>
  <p>
    Data integrity can be checked with the sha1 of the file that is sent.  This
    could be attacked via a man in the middle attack, but much more embarrasing
    things could result from that than a bad file.  The wire integrity is left
    to the stream method.
  </p>
</section1>

<section1 topic='IANA Considerations'>
  <p>
    The mime-type attribute on &lt;file/&gt; is a valid MIME type as controlled
    by the IANA.
  </p>
</section1>

<section1 topic='JANA Considerations'>
  <p>
    The "http://jabber.org/protocol/filexfer" is the only namespace that needs
    to be registered with the JANA.
  </p>
</section1>

</xep>