xeps/xep-0264.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 Thumbnails</title>
  <abstract>This specification defines a way for a client supply a preview image for a file transfer.</abstract>
  &LEGALNOTICE;
  <number>0264</number>
  <status>Experimental</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0096</spec>
    <spec>XEP-0231</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>thumbs</shortname>
  <author>
    <firstname>Marcus</firstname>
    <surname>Lundblad</surname>
    <email>ml@update.uu.se</email>
    <jid>mlundblad@jabber.org</jid>
  </author>
  <revision>
    <version>0.3</version>
    <date>2009-04-27</date>
    <initials>ml</initials>
    <remark><p>Fixed typo in author's name :).</p></remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2009-04-06</date>
    <initials>ml</initials>
    <remark><p>Add paragraph in security section about protecting against malicious thumbnail dimensions in offer. Fixed a typo.</p></remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2009-04-02</date>
    <initials>psa</initials>
    <remark><p>Initial published version.</p></remark>
  </revision>
  <revision>
    <version>0.0.3</version>
    <date>2009-03-10</date>
    <initials>ml</initials>
    <remark><p>Split use-case section into "Introduction", "Requirements", and "Use case".</p>
    </remark>
  </revision>
  <revision>
    <version>0.0.2</version>
    <date>2009-02-25</date>
    <initials>ml</initials>
    <remark><p>Removed service disovery.
Added missing namespace on thumnail elements.</p>
    </remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2009-02-23</date>
    <initials>ml</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='introduction'>
  <p>The current methods for file transfers include basic meta data about the
file being offered (name, size, and date). There currently is no way to provide an image thumbnail for files such as photos.</p>
</section1>
<section1 topic='Requirements' anchor='requirements'>
  <p>This documents defines a way to include a thumbnail image as an additional metadata in a file transfer.</p>
</section1>
<section1 topic='Use Case' anchor='usecase'>
  <p>When a client wishes to supply a thumbnail in a transfer offer, it can do so by including an extra <![CDATA[<thumbnail/>]]> element as shown in the following exaples.</p>
  <example caption='Inclusion of a thumbnail in SI file transfer offer'><![CDATA[
<iq type='set' id='offer1' to='receiver@jabber.org/resource'>
  <si xmlns='http://jabber.org/protocol/si' 
      id='a0'
      mime-type='image/jpeg'
      profile='http://jabber.org/protocol/si/profile/file-transfer'>
    <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
          name='image.jpg'
          size='3032449'>
      <thumbnail xmlns='urn:xmpp:thumbs:0'
		 cid='sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org'
		 mime-type='image/png'
		 width='128'
		 height='96'/>
    </file>
    <feature xmlns='http://jabber.org/protocol/feature-neg'>
      <x xmlns='jabber:x:data' type='form'>
        <field var='stream-method' type='list-single'>
          <option><value>http://jabber.org/protocol/bytestreams</value></option>
          <option><value>http://jabber.org/protocol/ibb</value></option>
        </field>
      </x>
    </feature>
  </si>
</iq>
    ]]>
</example>
  <p>The receiver MAY now request the data using the protocol defined in &xep0231;.</p>
<example caption='Inclusion of a thumbnail in a Jingle file transfer offer'><![CDATA[
<iq from='romeo@montague.lit/orchard'
    id='nzu25s8'
    to='juliet@capulet.lit/balcony'
    type='set'>
  <jingle xmlns='urn:xmpp:jingle:0'
          action='session-initiate'
          initiator='romeo@montague.lit/orchard'
          sid='851ba2'>
    <content creator='initiator' name='a-file-offer'>
      <description xmlns='urn:xmpp:jingle:apps:file-transfer:1'>
        <offer>
          <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
                name='image.jpg'
                size='3032449'
                hash='552da749930852c69ae5d2141d3766b1'
                date='1969-07-21T02:56:15Z'>
            <desc>This is a test. If this were a real file...</desc>
	    <thumbnail xmlns='urn:xmpp:thumbs:0'
		       cid='sha1+ffd7c8d28e9c5e82afea41f97108c6b4@bob.xmpp.org'
		       mime-type='image/png'
		       width='128'
		       height='96'/>
          </file>
        </offer>
      </description>
      ...
    </content>
  </jingle>
</iq>
]]>
</example>
  <section2 topic='Definition of the thumbnail Element' 
	    anchor='thumbnail_element'>
    <p>The following attributes are defined for the &lt;thumbnail/&gt; element.</p>
    <table caption='Attributes of the thumbnail Element'>
      <tr>
        <th>Attribute</th>
        <th>Description</th>
        <th>Inclusion</th>
      </tr>
      <tr>
        <td>cid</td>
        <td>A Content-ID that can be mapped to a cid: URL as specified in &rfc2111;. The 'cid' value SHOULD be of the form algo+hash@bob.xmpp.org, where the "algo" is the hashing algorithm used (e.g., "sha1" for the SHA-1 algorithm as specified in &rfc3174;) and the "hash" is the hex output of the algorithm applied to the binary data itself.</td>
        <td>REQUIRED</td>
      </tr>
      <tr>
        <td>mime-type</td>
        <td>The value of the 'mime-type' attribute MUST match the syntax specified in &rfc2045;. That is, the value MUST include a top-level media type, the "/" character, and a subtype; in addition, it MAY include one or more optional parameters (e.g., the "audio/ogg" MIME type in the example shown below includes a "codecs" parameter as specified in &rfc4281;). The "type/subtype" string SHOULD be registered in the &ianamedia;, but MAY be an unregistered or yet-to-be-registered value.</td>
        <td>RECOMMENDED</td>
      </tr>
      <tr>
	<td>width</td>
	<td>The intended display width of the thumbnail image. Used as a hint for the receiving client to prepare i.e. a dialog window.</td>
	<td>OPTIONAL</td>
      </tr>
      <tr>
	<td>height</td>
	<td>The intended display height of the thumbnail image. Used as a hint for the receiving client to prepare i.e. a dialog window.</td>
	<td>OPTIONAL</td>
      </tr>
    </table>

  </section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>The inclusion of an image thumbnail may leak information about a transfer
otherwise taking place on an e2e encrypted file transfer stream. A client MAY
wish to not include a thumbnail.</p>
  <p>A client MUST NOT rely on the values specified for the width and height of a thumbnail to allocate a bitmap data buffer for the thumbnail, to prevent possible DoS attacks. Also a client SHOULD apply implementation-specific limits on the thumbnails, if using these values to pepare a UI element for the thumbnail image, of f.ex. 128x128 pixels, values exceeding these would then be truncated and the thumbnail image scaled down when received.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
    <p>This specification defines the following XML namespace:</p>
    <ul>
      <li>urn:xmpp:thumbs:0</li>
    </ul>
    <p>The &REGISTRAR; includes this namespace in the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
  </section2>
  <section2 topic='Protocol Versioning' anchor='registrar-versioning'>
    &NSVER;
  </section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
  <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:thumbs:0'
    xmlns='urn:xmpp:thumbs:0'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      xxx
    </xs:documentation>
  </xs:annotation>

  <xs:element name='thumbnail'>
    <xs:complexType>
      <xs:attribute name='cid' type='xs:string' use='required'/>
      <xs:attribute name='mime-type' type='xs:string' use='optional'/>
      <xs:attribute name='width' type='xs:integer' use='optional'/>
      <xs:attribute name='height' type='xs:integer' use='optional'/>
    </xs:complexType>
  </xs:element>
</xs:schema>
  ]]></code>
</section1>
</xep>