XEP-0047: In-Band Bytestreams (IBB)

This specification defines an XMPP protocol extension that enables any two entities to establish a one-to-one bytestream between themselves, where the data is broken down into smaller chunks and transported in-band over XMPP.

NOTICE: The protocol defined herein is a Draft Standard of the XMPP Standards Foundation. Implementations are encouraged and the protocol is appropriate for deployment in production systems, but some changes to the protocol are possible before it becomes a Final Standard.

1. Introduction
2. Uses
3. Implementation
    3.1. Creating a bytestream
    3.2. Sending data
    3.3. Closing the bytestream
    3.4. Receiving packets
4. Usage Guidelines
5. Security Considerations
6. IANA Considerations
7. XMPP Registrar Considerations
    7.1. Protocol Namespaces
8. XML Schema

Appendices
    A: Document Information
    B: Author Information
    C: Legal Notices
    D: Relation to XMPP
    E: Discussion Venue
    F: Requirements Conformance
    G: Notes
    H: Revision History

1. Introduction

This document describes In-Band Bytestreams (or IBB), a reliable bytestream protocol between two Jabber entities over a Jabber XML stream. The basic idea is that binary data is encoded as Base64 and transferred over the Jabber network.

2. Uses

IBB is a generic bytestream, and so its usage is left open-ended. It is likely to be useful for sending small payloads, such as files that would otherwise be too cumbersome to send as an instant message (such as a text file) or impossible to send (such as a small binary image file). It could also be useful for any kind of low-bandwidth activity, such as a chess game or a shell session. And, while it is mostly intended as a fallback in situations where a SOCKS5 Bytestreams [1] is unavailable, IBB could be more desirable for many of the simple bytestream use-cases that do not have high bandwidth requirements.

3. Implementation

3.1 Creating a bytestream

Example 1. Initiation of Interaction

<iq type='set' 
    from='romeo@montague.net/orchard'
    to='juliet@capulet.com/balcony'
    id='inband_1'>
  <open sid='mySID' 
        block-size='4096'
        xmlns='http://jabber.org/protocol/ibb'/>
</iq>

This asks Juliet if she would like to form an In-Band Bytestreams connection, using the session ID 'mySID' (generated by the initiator here) to uniquely reference the bytestream. The 'block-size' attribute specifies the maximum amount of data (in bytes) that an IBB packet may contain.

Example 2. Success Response

<iq type='result' 
    from='juliet@capulet.com/balcony'
    to='romeo@montague.net/orchard'
    id='inband_1'/>

This is a success response from juliet@capulet.com/balcony, saying that the bytestream is active.

Example 3. Error

<iq type='error' 
    from='juliet@capulet.com/balcony'
    to='romeo@montague.net/orchard'
    id='inband_1'/>
  <error code='501' type='cancel'>
    <feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

This is an error response from juliet@capulet.com/balcony saying that an In-Band Bytestreams is not possible.

3.2 Sending data

Data is sent using either <message> or <iq> stanzas. Either participant in the bytestream may send such packets. The data to be sent, prior to any encoding or wrapping in the stanza, must be no larger than the 'block-size' determined in the stream negotiation. All stanzas are to be addressed to the FULL JID of the bytestream peer. In order to keep track of stanzas sent and any errors received, the sender SHOULD include the 'id' attribute on stanzas sent to the recipient. When using <message> stanzas, Advanced Message Processing [2] SHOULD be used to ensure that the data packet is not spooled or sent to the wrong resource.

Example 4. Sending data using message

<message from='romeo@montague.net/orchard' to='juliet@capulet.com/balcony' id='msg1'>
  <data xmlns='http://jabber.org/protocol/ibb' sid='mySID' seq='0'>
    qANQR1DBwU4DX7jmYZnncmUQB/9KuKBddzQH+tZ1ZywKK0yHKnq57kWq+RFtQdCJ
    WpdWpR0uQsuJe7+vh3NWn59/gTc5MDlX8dS9p0ovStmNcyLhxVgmqS8ZKhsblVeu
    IpQ0JgavABqibJolc3BKrVtVV1igKiX/N7Pi8RtY1K18toaMDhdEfhBRzO/XB0+P
    AQhYlRjNacGcslkhXqNjK5Va4tuOAPy2n1Q8UUrHbUd0g+xJ9Bm0G0LZXyvCWyKH
    kuNEHFQiLuCY6Iv0myq6iX6tjuHehZlFSh80b5BVV9tNLwNR5Eqz1klxMhoghJOA
  </data>
  <amp xmlns='http://jabber.org/protocol/amp'>
    <rule condition='deliver' value='stored' action='error'/>
    <rule condition='match-resource' value='exact' action='error'/>
  </amp>
</message>

Example 5. Sending data using iq

<iq from='romeo@montague.net/orchard' to='juliet@capulet.com/balcony' type='set' id='ibb1'>
  <data xmlns='http://jabber.org/protocol/ibb' sid='mySID' seq='0'>
    qANQR1DBwU4DX7jmYZnncmUQB/9KuKBddzQH+tZ1ZywKK0yHKnq57kWq+RFtQdCJ
    WpdWpR0uQsuJe7+vh3NWn59/gTc5MDlX8dS9p0ovStmNcyLhxVgmqS8ZKhsblVeu
    IpQ0JgavABqibJolc3BKrVtVV1igKiX/N7Pi8RtY1K18toaMDhdEfhBRzO/XB0+P
    AQhYlRjNacGcslkhXqNjK5Va4tuOAPy2n1Q8UUrHbUd0g+xJ9Bm0G0LZXyvCWyKH
    kuNEHFQiLuCY6Iv0myq6iX6tjuHehZlFSh80b5BVV9tNLwNR5Eqz1klxMhoghJOA
  </data>
</iq>

The data to send is included as XML character data of the <data/> element after being encoded as Base64 as specified in Section 4 of RFC 4648 [3]. The 'seq' attribute is a 16-bit unsigned integer counter starting at 0, and MUST be incremented for each packet sent. Thus, the next packet sent should have a 'seq' of 1, the one after that with a 'seq' of 2, and so on. The counter loops at maximum, so after value 65535, 'seq' MUST start again at 0.

Note that in the case of iq stanzas, the recipient must reply with an iq of type 'result'.

Example 6. Acknowledging data using iq

<iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' type='result' id='ibb1'/>

The sender need not wait for these acknowledgements before sending further stanzas. However, it is RECOMMENDED that the sender does wait in order to minimize possible rate-limiting penalties.

It is possible that the stanza may fail to be delivered:

Example 7. Failed delivery with message

<message from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='msg1' type='error'>
  ...
  <error code='504' type='cancel'>
    <remote-server-timeout xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</message>

Example 8. Failed delivery with iq

<iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='ibb1' type='error'>
  ...
  <error code='504' type='cancel'>
    <remote-server-timeout xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

Upon delivery failure, the sender MUST consider the bytestream to be closed and invalid.

3.3 Closing the bytestream

To close the bytestream, send the following:

Example 9. Closing the bytestream

<iq type='set' 
    from='romeo@montague.net/orchard'
    to='juliet@capulet.com/balcony'
    id='inband_2'>
  <close xmlns='http://jabber.org/protocol/ibb' sid='mySID'/>
</iq>

Example 10. Success response

<iq type='result' 
    from='juliet@capulet.com/balcony'
    to='romeo@montague.net/orchard'
    id='inband_2'/>

This is a success response from juliet@capulet.com/balcony, saying that the bytestream is now closed.

Example 11. Possible error

<iq type='error' 
    from='juliet@capulet.com/balcony'
    to='romeo@montague.net/orchard'
    id='inband_2'>
  <error code='404' type='cancel'>
    <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

Upon error, the bytestream MUST be considered closed and invalid.

3.4 Receiving packets

Data packets MUST be processed in the order they are received. If an out-of-sequence packet is received for a particular bytestream (determined by checking the 'seq' attribute), then this indicates that a packet has been lost. The recipient MUST NOT process the data of such an out-of-sequence packet, nor any that follow it within the same bytestream, and at this point MUST consider the bytestream closed and invalid.

4. Usage Guidelines

5. Security Considerations

In-Band Bytestreams is as secure as the underlying Jabber transport. The bytestream application could have its own security layer, but this is outside of the scope of IBB.

An entity MUST verify any Base64 data received. An implementation MUST reject (not ignore) any characters that are not explicitly allowed by the Base64 alphabet; this helps to guard against creation of a covert channel that could be used to "leak" information. An implementation MUST NOT break on invalid input and MUST reject any sequence of Base64 characters containing the pad ('=') character if that character is included as something other than the last character of the data (e.g. "=AAA" or "BBBB=CCC"); this helps to guard against buffer overflow attacks and other attacks on the implementation. Base encoding visually hides otherwise easily recognized information, such as passwords, but does not provide any computational confidentiality. Base64 encoding MUST follow the definition in Section 4 of RFC 4648.

6. IANA Considerations

7. XMPP Registrar Considerations

7.1 Protocol Namespaces

The XMPP Registrar [6] shall register the 'http://jabber.org/protocol/ibb' namespace as a result of this document.

8. XML Schema

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

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://jabber.org/protocol/ibb'
    xmlns='http://jabber.org/protocol/ibb'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0047: http://www.xmpp.org/extensions/xep-0047.html
    </xs:documentation>
  </xs:annotation>

   <xs:element name='open'>
     <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='sid' type='xs:string' use='required'/>
          <xs:attribute name='block-size' type='xs:string' use='required'/>
        </xs:extension>
      </xs:simpleContent>
     </xs:complexType>
   </xs:element>

   <xs:element name='close'>
     <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='empty'>
          <xs:attribute name='sid' type='xs:string' use='required'/>
        </xs:extension>
      </xs:simpleContent>
     </xs:complexType>
   </xs:element>

   <xs:element name='data'>
     <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:string'>
          <xs:attribute name='sid' type='xs:string' use='required'/>
          <xs:attribute name='seq' type='xs:string' use='required'/>
        </xs:extension>
      </xs:simpleContent>
     </xs:complexType>
   </xs:element>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>

Appendices

Appendix A: Document Information

Appendix B: Author Information

Justin Karneges

Email: justin@affinix.com
JabberID: justin@andbit.net

Appendix C: Legal Notices

Copyright

Permissions

Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <http://xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA).

Appendix D: 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.

Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Appendix F: Requirements Conformance

The following requirements 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".

Appendix G: Notes

1. XEP-0065: SOCKS5 Bytestreams <http://xmpp.org/extensions/xep-0065.html>.

2. XEP-0079: Advanced Message Processing <http://xmpp.org/extensions/xep-0079.html>.

3. RFC 4648: The Base16, Base32, and Base64 Data Encodings <http://tools.ietf.org/html/rfc4648>.

4. XEP-0079: Advanced Message Processing <http://xmpp.org/extensions/xep-0079.html>.

5. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

6. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <http://xmpp.org/registrar/>.