xeps/xep-0446.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 metadata element</title>
  <abstract>This specification defines a generic file metadata element to be used in other specifications.</abstract>
  &LEGALNOTICE;
  <number>0446</number>
  <status>Experimental</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0001</spec>
    <spec>XEP-0082</spec>
    <spec>XEP-0264</spec>
    <spec>XEP-0300</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>file-metadata</shortname>
  &larma;
  <revision>
    <version>0.2.0</version>
    <date>2022-07-17</date>
    <initials>lmw</initials>
    <remark>Use height/width instead of dimensions</remark>
  </revision>
  <revision>
    <version>0.1.0</version>
    <date>2020-11-24</date>
    <initials>XEP Editor (jsc)</initials>
    <remark>Accepted by vote of Council on 2020-11-18.</remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2020-11-03</date>
    <initials>lmw</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>
    Several existing specification have the need to provide metadata on a file.
    The only specification of an element that contains file metadata so far is
    provided as part of &xep0234;. This resulted in the situation that XEPs like
    &xep0385; depend on the mostly unrelated &xep0166; just for the metadata
    element. The motiviation of this XEP is to get rid of such dependencies and
    have a dedicated place to define a file metadata element.
  </p>
</section1>
<section1 topic='Element format' anchor='format'>
  <code><![CDATA[
<file xmlns='urn:xmpp:file:metadata:0'>
    <media-type>text/plain</media-type>
    <name>test.txt</name>
    <date>2015-07-26T21:46:00+01:00</date>
    <size>6144</size>
    <hash xmlns='urn:xmpp:hashes:2'
          algo='sha-1'>w0mcJylzCn+AfvuGdqkty2+KP48=</hash>
</file>]]></code>
  <p>The child elements of the &lt;file/&gt; element are as follows:</p>
  <table caption='File Description Elements'>
    <tr>
      <th>Element Name</th>
      <th>Description</th>
      <th>Example</th>
    </tr>
    <tr>
      <td>date</td>
      <td>Timestamp specifying the last modified time of the file (which MUST conform to the DateTime profile of &xep0082;).</td>
      <td><tt>2015-07-26T21:46:00+01:00</tt></td>
    </tr>
    <tr>
      <td>desc</td>
      <td>A human readable description of the file. Multiple <tt>&lt;desc/&gt;</tt> elements MAY be included if different xml:lang values are specified.</td>
      <td><tt>Picture of 24th XSF Summit</tt></td>
    </tr>
    <tr>
      <td>hash</td>
      <td>A hash of the file content, using the <tt>&lt;hash/&gt;</tt> element defined in &xep0300; and qualifed by the 'urn:xmpp:hashes:2' namespace. Multiple hashes MAY be included for hash agility.</td>
      <td><em>see specification</em></td>
    </tr>
    <tr>
      <td>height</td>
      <td>Vertical dimensions of image or video files, in pixels.</td>
      <td><tt>1920</tt></td>
    </tr>
    <tr>
      <td>length</td>
      <td>Length of an audio or video file, in milliseconds.</td>
      <td><tt>63000</tt></td>
    </tr>
    <tr>
      <td>media-type</td>
      <td>The media type of the file content, which SHOULD be a valid MIME-TYPE as registered with &IANA; (specifically, as listed at &lt;<link url='http://www.iana.org/assignments/media-types'>http://www.iana.org/assignments/media-types</link>&gt;). If not specified, the content is assumed to be "application/octet-stream".</td>
      <td><tt>text/plain</tt></td>
    </tr>
    <tr>
      <td>name</td>
      <td>The name of the file. The name SHOULD NOT contain characters or character sequences that would be interpreted as a directory structure by the local file system (e.g. "/", "\", "../", etc.). If any such characters or character sequences are present (possibly because the local and remote file systems use different syntax for directory structure), they SHOULD be escaped (e.g., via percent-encoding) before using the name as part of any file system operation. See <link url='#security'>Security Considerations</link>.</td>
      <td><tt>text.txt</tt></td>
    </tr>
    <tr>
      <td>size</td>
      <td>The length of the file's content, in bytes.</td>
      <td><tt>6144</tt></td>
    </tr>
    <tr>
      <td>thumbnail</td>
      <td>A thumbnail element of the file, using the &lt;thumbnail/&gt; element defined in &xep0264; and qualified by the 'urn:xmpp:thumbs:1' namespace. Multiple thumbnails MAY be included for media type and size agility.</td>
      <td><em>see specification</em></td>
    </tr>
    <tr>
      <td>width</td>
      <td>Horizontal dimensions of image or video files, in pixels.</td>
      <td><tt>1080</tt></td>
    </tr>
  </table>
  <p>
    All child elements are OPTIONAL, however, specifications making use of the
    file metadata object MAY require providing some of these elements as part
    of their specification.
  </p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>
    Caution needs to be exercised when using the <tt>&lt;name/&gt;</tt> of the metadata
    to control any interaction with a file system. For example, a malicious
    user could request a file with <tt>&lt;name&gt;/etc/passwd&lt;/name&gt;</tt> or
    include file system specific control patterns such as
    <tt>&lt;name&gt;../../private.txt&lt;/name&gt;</tt> to try and access a sensitive
    file outside of the set of files intended to be shared. Or a malicious user
    could offer a file named <tt>/etc/passwd</tt> to try and trick the receiver into
    overwriting that or other sensitive files. Therefore, implementations
    SHOULD escape any file system path separators in the <tt>&lt;name/&gt;</tt> before
    using that value in any file system calls.
  </p>
  <p>
    It is RECOMMENDED for implementations to use the strongest hashing
    algorithm available to both parties. See &xep0300; for further discussion.
  </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='ns'>
    <p>The &REGISTRAR; includes 'urn:xmpp:file:metadata:0' in its registry of protocol namespaces (see &NAMESPACES;).</p>
    <ul>
      <li>urn:xmpp:file:metadata:0</li>
    </ul>
  </section2>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
  <p>Thanks to the authors of &xep0234; which heavily inspired this XEP.</p>
</section1>
</xep>