XEP-0231: Data Element

This specification defines an XMPP protocol extension for including small bits of binary data in an XML stanza.

NOTICE: This document is currently within Last Call or under consideration by the XMPP Council for advancement to the next stage in the XSF standards process.

Document Information

Series: XEP
Number: 0231
Publisher: XMPP Standards Foundation
Status: Proposed
Type: Standards Track
Version: 0.5
Last Updated: 2008-08-06
Approving Body: XMPP Council
Dependencies: XMPP Core, RFC 2045, RFC 2111, RFC 2965, RFC 4648
Supersedes: None
Superseded By: None
Short Name: NOT_YET_ASSIGNED
Wiki Page: <http://wiki.jabber.org/index.php/Data Element (XEP-0231)>

Author Information

Legal Notices

Discussion Venue

The preferred venue for discussion of this document is the Standards discussion list: <http://mail.jabber.org/mailman/listinfo/standards>.

Given that this XMPP Extension Protocol normatively references IETF technologies, discussion on the XSF-IETF list may also be appropriate (see <http://mail.jabber.org/mailman/listinfo/jsf-ietf> for details).

Errata may be sent to <editor@xmpp.org>.

Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Conformance Terms

The following keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".

Table of Contents

1. Introduction

Sometimes it is desirable to include a small bit of binary data in an XMPP stanza. Typical use cases might be inclusion of an icon or emoticon in a message, a thumbnail in a file transfer request, a rasterized image in a whiteboarding session, or a small bit of media in a data form. At present, there is no lightweight method for including such data in an XMPP stanza, since existing methods (e.g., In-Band Bytestreams [1]) are designed for larger blobs of data and therefore require some form of negotiation (e.g., via SI File Transfer [2] or Jingle File Transfer [3]). Therefore, this document specifies just such a lightweight method, using a <data/> element that provides semantics similar to the data: URL scheme defined in RFC 2397 [4].

2. Format

The format for including binary data is straightforward: the data is encapsulated as the XML character data of a <data/> element qualified by the 'urn:xmpp:tmp:data-element' namespace (see Protocol Namespaces regarding issuance of one or more permanent namespaces), where the data MUST be encoded as Base64 in accordance with Section 4 of RFC 4648 [5] (note: the Base64 output MUST NOT include whitespace and MUST set the number of pad bits to zero).

The <data/> element MUST be used only to encapsulate small bits of binary data and MUST NOT be used for large data transfers. Naturally the definitions of "small" and "large" are rather loose. In general, the data SHOULD NOT be more than 8 kilobytes, and dedicated file transfer methods (e.g., SOCKS5 Bytestreams [6] or In-Band Bytestreams [7]) SHOULD be used for exchanging blobs of data larger than 8 kilobytes. Naturally, implementations or deployments may impose their own limits.

The following attributes are defined for the <data/> element.

The following example illustrates the format (line endings are provided for readability only).

Example 1. Data element format

<data xmlns='urn:xmpp:tmp:data-element' 
      cid='f81d4fae-7dec-11d0-a765-00a0c91e6bf6@shakespeare.lit'
      max-age='86400'
      type='image/png'>
  iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAABGdBTUEAALGP
  C/xhBQAAAAlwSFlzAAALEwAACxMBAJqcGAAAAAd0SU1FB9YGARc5KB0XV+IA
  AAAddEVYdENvbW1lbnQAQ3JlYXRlZCB3aXRoIFRoZSBHSU1Q72QlbgAAAF1J
  REFUGNO9zL0NglAAxPEfdLTs4BZM4DIO4C7OwQg2JoQ9LE1exdlYvBBeZ7jq
  ch9//q1uH4TLzw4d6+ErXMMcXuHWxId3KOETnnXXV6MJpcq2MLaI97CER3N0
  vr4MkhoXe0rZigAAAABJRU5ErkJggg==
</data>
  

When the <data/> element is included in an XMPP <message/> or <presence/> stanza, it SHOULD be included as a first-level child of the stanza.

When the <data/> element is included in an XMPP <iq/> stanza for data retrieval, it MUST be included as a first-level child of the stanza.

When the <data/> element is included in an XMPP <iq/> stanza to refer to the data, it MUST be included as a second-level child of the stanza.

3. Caching of Data

When one party sends a data element to another party, it SHOULD NOT include the data itself unless the data is particularly small (e.g., less than 1k) or is ephemeral and therefore will never be used again. Instead, it SHOULD send an empty <data/> element with a 'cid' attribute, then depend on the receiving party to retrieve the data if not cached.

As a hint regarding the suggested period for caching the data, the sending party SHOULD include a 'max-age' attribute whenever it sends a non-empty <data/> element. The semantics of the 'max-age' attribute exactly matches that of the Max-Age attribute from RFC 2965.

It is RECOMMENDED for the receiving entity to cache data; however, the receiving entity MAY opt not to cache data, for example because it runs on an a device that does not have sufficient space for data storage.

The default behavior is for the receiving entity to cache the data only for the life of the entity's application session (not a controlling user's presence session with the server or the controlling user's communication session with the contact from whom the user received the data); that is, the receiving entity would clear the cache when the application is terminated or restarted.

If it is not suggested to cache the data (e.g., because it is ephemeral), the value of the 'max-age' attribute MUST be "0" (the number zero).

A receiving entity MUST cache based on the JID of the sending entity; this helps to prevent certain data poisoning attacks.

4. Retrieving Uncached Data

Data can be requested and transferred using the XMPP <iq/> stanza type by making reference to the 'cid' of the data to be retrieved. In particular, the requesting entity can request data by sending an IQ-get containing an empty <data/> element with a 'cid' attribute.

Example 2. Requesting data

<iq from='doctor@shakespeare.lit/pda'
    id='get-data-1'
    to='gentlewoman@shakespeare.lit/phone'
    type='get'>
  <data xmlns='urn:xmpp:tmp:data-element' 
        cid='f81d4fae-7dec-11d0-a765-00a0c91e6bf6@shakespeare.lit'/>
</iq>
  

The responding entity then would either return an error (e.g., <item-not-found/> if it does not have data matching the Content-ID) or return the data.

Example 3. Returning data

<iq from='gentlewoman@shakespeare.lit/phone'
    id='get-data-1'
    to='doctor@shakespeare.lit/pda'
    type='result'>
  <data xmlns='urn:xmpp:tmp:data-element' 
        cid='f81d4fae-7dec-11d0-a765-00a0c91e6bf6@shakespeare.lit'
        max-age='86400'
        type='image/png'>
    iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAABGdBTUEAALGP
    C/xhBQAAAAlwSFlzAAALEwAACxMBAJqcGAAAAAd0SU1FB9YGARc5KB0XV+IA
    AAAddEVYdENvbW1lbnQAQ3JlYXRlZCB3aXRoIFRoZSBHSU1Q72QlbgAAAF1J
    REFUGNO9zL0NglAAxPEfdLTs4BZM4DIO4C7OwQg2JoQ9LE1exdlYvBBeZ7jq
    ch9//q1uH4TLzw4d6+ErXMMcXuHWxId3KOETnnXXV6MJpcq2MLaI97CER3N0
    vr4MkhoXe0rZigAAAABJRU5ErkJggg==
  </data>
</iq>
  

This specification does not place limits on the entities from which data can be requested. In particular, such an entity need not be the "owner" of the data (e.g., it could be a peer in a chatroom or whiteboarding session, or the chatroom or whiteboarding service itself).

In addition, bits of data could be hosted by XMPP servers, distributed via Publish-Subscribe [14] nodes, or included in data collections that are available via HTTP (e.g., emoticon sets). Such data could be identified by the value of the 'cid' attribute, but methods for specifying those values are out of scope for this specification.

5. Examples

As an example, consider the use of the <data/> element in conjunction with XHTML-IM [15]. Here the cid: URL scheme points to a data element within a <message/> stanza.

Example 4. A message with included data

<message from='ladymacbeth@shakespeare.lit/castle'
         to='macbeth@chat.shakespeare.lit'
         type='groupchat'>
  <body>Yet here's a spot.</body>
  <html xmlns='http://jabber.org/protocol/xhtml-im'>
    <body xmlns='http://www.w3.org/1999/xhtml'>
      <p>
        Yet here's a spot.
        <img alt='A spot'
             src='cid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6@shakespeare.lit'/>
      </p>
    </body>
  </html>
  <data xmlns='urn:xmpp:tmp:data-element' 
        cid='f81d4fae-7dec-11d0-a765-00a0c91e6bf6@shakespeare.lit'
        max-age='86400'
        type='image/png'/>
</message>
  

Once the data element is communicated, a subsequent message in the same session can refer to the data again (via a cid: URI) without including the data element itself.

Example 5. A message with referenced data

<message from='ladymacbeth@shakespeare.lit/castle'
         to='macbeth@chat.shakespeare.lit'
         type='groupchat'>
  <body>Out, damned spot!</body>
  <html xmlns='http://jabber.org/protocol/xhtml-im'>
    <body xmlns='http://www.w3.org/1999/xhtml'>
      <p>
        Out damned spot! 
        <img alt='A spot'
             src='cid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6@shakespeare.lit'/>
      </p>
    </body>
  </html>
</message>
  

If the receiving entity has not cached the data, it can request the data as described in the Retrieving Data section of this document.

6. Security Considerations

The ability to include arbitrary binary data implies that it is possible to send scripts, applets, images, and executable code, which may be potentially harmful. To reduce the risk of such exposure, an implementation MAY choose to not display or process such data but instead either completely ignore the data, show only the value of the 'alt' attribute, or prompt a human user for approval (either explicitly via user action or implicitly via a list of approved entities from whom the user will accept binary data without per-event approval).

The receiving entity SHOULD cache data based on the sender's JabberID; this helps to avoid data poisoning attacks.

7. IANA Considerations

This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [16].

8. XMPP Registrar Considerations

9. XML Schema

<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:tmp:data-element'
    xmlns='urn:xmpp:tmp:data-element'
    elementFormDefault='qualified'>

  <xs:element name='data'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:base64Binary'>
          <xs:attribute name='cid' type='xs:string' use='optional'/>
          <xs:attribute name='max-age' type='xs:nonNegativeInteger' use='optional'/>
          <xs:attribute name='type' type='xs:string' use='required'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

</xs:schema>
  

10. Acknowledgements

Thanks to Rachel Blackman, Dave Cridland, and Tomasz Sterna for their feedback.

Notes

Revision History

END