XEP-0095: Stream Initiation

Abstract:This specification defines an XMPP protocol extension for initiating a data stream between any two XMPP entities. The protocol includes the ability to include metadata about the stream and provides a pluggable framework so that various profiles of stream initiation can be defined for particular use cases (such as file transfer).
Authors:Thomas Muldowney, Matthew Miller, Ryan Eatmon
Copyright:© 1999 - 2013 XMPP Standards Foundation. SEE LEGAL NOTICES.
Status:Draft
Type:Standards Track
Version:1.1
Last Updated:2004-04-13

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.

Table of Contents


1. Introduction
2. Requirements
3. Use Case
    3.1. Discovery
    3.2. Negotiating Profile and Stream
    3.3. Preparing the Transfer
4. Formal Definition
    4.1. <si/> Root Element
    4.2. Error Codes
5. Implementation Notes
    5.1. Profiles
    5.2. Stream Interaction
6. Security Considerations
7. IANA Considerations
8. XMPP Registrar Considerations
    8.1. Protocol Namespaces
    8.2. Registries
       8.2.1. Profiles Registry
         8.2.1.1. Process
9. 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

As the Jabber protocols are extended beyond basic messaging and presence, the need has arisen for a generic protocol that can be used to negotiate content streams between any two entities. Such streams might be in-band, but more likely will be out-of-band, binary streams used in applications such as file transfer, voice chat, and video conferencing. This document provides a method for negotiating such streams, including meta-information about the intended usage of the stream.

2. Requirements

3. Use Case

The process for stream negotiation is as follows:

  1. Sender discovers if Receiver implements the desired profile. [E1]
  2. Sender offers a stream initiation. [E2]
  3. Receiver accepts stream initiation.
  4. Sender and receiver prepare for using negotiated profile and stream, EUC

Error Conditions:

  1. The Receiver does not support the desired profile, EUC
  2. Receiver rejects the stream initiation, EUC

3.1 Discovery

Before a Stream Initiation is attempted the Sender should be sure that the Receiver supports both Stream Initiation and the specific profile that they wish to use. This is typically accomplished using Service Discovery [1]:

Example 1. Requesting Disco Information From Receiver

<iq type='get' 
    to='receiver@jabber.org/resource' 
    from='sender@jabber.org/resource'
    id='info1'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

The Receiver advertises the "http://jabber.org/protocol/si" namespace as a feature to represent that they implement this document. The specific profiles are also announced this way; they can be found by looking for "http://jabber.org/protocol/si/profile/profile-name". Shown in the result is a potential file transfer profile:

Example 2. Receiver Disco Information Result

<iq type='result'
    to='sender@jabber.org/resource'
    from='receiver@jabber.org/resource'
    id='info1'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='http://jabber.org/protocol/si'/>
    <feature var='http://jabber.org/protocol/si/profile/file-transfer'/>
    ...
  </query>
</iq>

3.2 Negotiating Profile and Stream

Once support is determined, the Sender starts the negotiation with the Receiver by sending an <iq/> stanza of type "set", such as in the following example from SI File Transfer [2]:

Example 3. Offer Stream Initiation

<iq type='set' id='offer1' to='receiver@jabber.org/resource'>
  <si xmlns='http://jabber.org/protocol/si'
      id='a0'
      mime-type='text/plain'
      profile='http://jabber.org/protocol/si/profile/file-transfer'>
    <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
          name='test.txt'
          size='1022'>
      <desc>This is info about the file.</desc>
    </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>jabber:iq:oob</value></option>
          <option><value>http://jabber.org/protocol/ibb</value></option>
        </field>
      </x>
    </feature>
  </si>
</iq>

At this point the Receiver can view the profile and other information to decide if they wish to accept the Stream Initiation. If acceptable the Receiver MUST select one of the presented stream types to use.

Example 4. Accept Stream Initiation

    
<iq type='result' to='sender@jabber.org/resource' id='offer1'>
  <si xmlns='http://jabber.org/protocol/si'>
    <feature xmlns='http://jabber.org/protocol/feature-neg'>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='stream-method'>
          <value>http://jabber.org/protocol/bytestreams</value>
        </field>
      </x>
    </feature>
  </si>
</iq>

If the profile describes data to be sent back in the result it MUST be present as described in the profile's specification.

Example 5. Accept Stream Initiation with Profile

<iq type='result' to='sender@jabber.org/resource' id='offer1'>
  <si xmlns='http://jabber.org/protocol/si'>
    <file xmlns='http://jabber.org/protocol/si/profile/profile-name'>
      <value>returned value</value>
    </file>
    <feature xmlns='http://jabber.org/protocol/feature-neg'>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='stream-method'>
          <value>http://jabber.org/protocol/bytestreams</value>
        </field>
      </x>
    </feature>
  </si>
</iq>

If none of the stream types are acceptable, or if the profile is not understood, the Receiver MUST reply with a "bad request" error:

Example 6. No Valid Streams

<iq type='error' to='sender@jabber.org/resource' id='offer1'>
  <error code='400' type='cancel'>
    <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <no-valid-streams xmlns='http://jabber.org/protocol/si'/>
  </error>
</iq>

Example 7. Profile not understood

<iq type='error' to='sender@jabber.org/resource' id='offer1'>
  <error code='400' type='cancel'>
    <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <bad-profile xmlns='http://jabber.org/protocol/si'/>
  </error>
</iq>

If the Receiver rejects the request, they reply with a "forbidden" error:

Example 8. Rejecting Stream Initiation

<iq type='error' to='sender@jabber.org/resource' id='offer1'>
  <error code='403' type='cancel'>
    <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>Offer Declined</text>
  </error>
</iq>

3.3 Preparing the Transfer

At this point, the Sender and Receiver make any preparations necessary for the stream to be used. The exact process is specific to each protocol, and is beyond the scope of this document. This step now marks the end of SI's responsibilities.

4. Formal Definition

4.1 <si/> Root Element

The <si/> element is the root element for this protocol. It is an identifiable container for all the information necessary for negotiation and signalling. It contains attributes for the identifier, intended MIME-type, and profile. The contents convey stream-negotation and profile information.

The "id" attribute is an opaque identifier. This attribute MUST be present on type='set', and MUST be a valid string. This SHOULD NOT be sent back on type='result', since the <iq/> "id" attribute provides the only context needed. This value is generated by the Sender, and the same value MUST be used throughout a session when talking to the Receiver.

The "mime-type" attribute identifies the MIME-type for the data across the stream. This attribute MUST be a valid MIME-type as registered with the Internet Assigned Numbers Authority (IANA) [3] (specifically, as listed at <http://www.iana.org/assignments/media-types>). During negotiation, this attribute SHOULD be present, and is otherwise not required. If not included during negotiation, its value is assumed to be "application/octet-stream".

The "profile" attribute defines the SI profile in use. This value MUST be present during negotiation, and is the namespace of the profile to use.

When the Sender first negotiates a Stream Initiation, all of the attributes SHOULD be present, and the id" and "profile" MUST be present. The contents MUST contain one profile, in the namespace declared in the "profile" attribute, and the feature negotiation for the stream. The feature negotiation MUST contain at least one option and use the field var "stream-method".

When the Receiver accepts a Stream Initiation, the <si/> element SHOULD NOT possess any attributes. The selected stream MUST be in the feature negotiation for the stream. There MUST only be one selected stream.

4.2 Error Codes

To simplify the discussion on error conditions, this document uses the following mapping between namespace URIs and namespace prefixes [4].

Table 1: Namespace Mappings

Prefix URI
xmpp urn:ietf:params:xml:ns:xmpp-stanzas
si http://jabber.org/protocol/si

Below are the most common errors that can result.

Table 2: Error Conditions/Codes

Error Code Error Type General Condition Specific Condition Description
400 cancel <xmpp:bad-request/> <si:no-valid-streams/> None of the available streams are acceptable.
400 modify <xmpp:bad-request/> <si:bad-profile/> The profile is not understood or invalid. The profile MAY supply a profile-specific error condition.
403 cancel <xmpp:forbidden/> NONE The stream is rejected.

For further information about the relationship between XMPP error handling and "legacy" (HTTP-style) error codes, refer to Error Condition Mappings [5].

5. Implementation Notes

5.1 Profiles

Stream Initiation on its own is of limited use; the Receiver almost always requires some reason for SI. Knowing this allows the Receiver to make a more educated choice about whether or not to accept the stream. This information is provided in Stream Initiation via a profile. A profile is a collection of information that describes the reason for and structure of the stream data, including what the data represents and what stream protocols are expected to be supported.

The initial request for Stream Initiation MUST have only one profile, and this profile is in its own namespace. The profile is indicated not only by the presence of a "root" element in that particular namespace, but also be the "profile" attribute in <si/> The SUGGESTED format for profile namespaces is:

http://jabber.org/protocol/si/profile/profile-name

The information that the profile presents SHOULD be defined in an official XEP. The XEP defining the profile SHOULD contain explanations of what the profile consists of and MUST define the profile in a complete manner using DTD, Schema or another appropiate definition language.

A profile SHOULD define what stream protocols MUST be supported, and MUST define what stream protocols MAY be supported. If a profile specifies only a single stream protocol that MUST be supported (even if others MAY also be supported), the "fneg" for the stream protocol may be omitted from the initial <si/>; the receiving entity then assumes the stream protocol that MUST be supported is the one to use.

This document does not define any profiles, nor does it place any restrictions on what type of information a profile should detail. Other specifications will define profiles to be used with Stream Initiation.

5.2 Stream Interaction

While Stream Initiation is not directly required for stream usage, it does provide many benefits. In order to fully appreciate these benefits, streams must link the Stream Initiation to the stream. The "id" attribute transported on the <si/> element is intended to do this. Once a session is fully negotiated, the value of the <si/> "id" attribute is used during the actual stream negotiation as the protocol's stream identifier attribute.

To be compatible to this document, a stream protocol MUST define a stream identifier (typically "sid"), which MUST have a unique string representation. The stream protocol MUST be able to use any string identifier chosen during Stream Initiation, as long as the sending party does not use the same identifier more than once.

6. Security Considerations

Data security concerns are left to the profiles to define. Wire security concerns are left to the stream definitions.

7. IANA Considerations

This document uses the MIME types as recorded by the IANA, but no direct interaction with the IANA is necessary.

8. XMPP Registrar Considerations

8.1 Protocol Namespaces

The XMPP Registrar [6] includes the 'http://jabber.org/protocol/si' namespace in its registry of protocol namespaces.

8.2 Registries

8.2.1 Profiles Registry

The XMPP Registrar shall maintain a registry of stream initiation profiles, located at <http://xmpp.org/registrar/si-profiles.html>. Any such profile defined in a XMPP Extension Protocol specification MUST be submitted to the XMPP Registrar; profiles defined in non-standard protocol extensions SHOULD be submitted to the XMPP Registrar.

8.2.1.1 Process

In order to submit new values to this registry, the registrant shall define an XML fragment of the following form and either include it in the relevant XMPP Extension Protocol or send it to the email address <registrar@xmpp.org>:

<profile>
  <name>The profile name</name>
  <doc>The specification that defines the profile</doc>
  <desc>A natural-language description of the profile</desc>
</profile>

9. XML Schema

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

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://jabber.org/protocol/si'
    xmlns='http://jabber.org/protocol/si'
    elementFormDefault='qualified'>
  
  <xs:import 
      namespace='http://jabber.org/protocol/feature-neg'
      schemaLocation='http://www.xmpp.org/schemas/feature-neg.xsd'/>

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

  <xs:element name='si'>
    <xs:annotation>
      <xs:documentation>
        This is the root content element. All other elements in
        this namespace are for communicating error information.
      </xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence xmlns:fneg='http://jabber.org/protocol/feature-neg'>
        <xs:any namespace='##other' minOccurs='0'/>
        <xs:element ref='fneg:feature'/>
      </xs:sequence>
      <xs:attribute name='id' type='xs:string' use='optional'/>
      <xs:attribute name='mime-type' type='xs:string' use='optional'/>
      <xs:attribute name='profile' type='xs:string' use='optional'/>
    </xs:complexType>
  </xs:element>
  
  <xs:element name='bad-profile' type='empty'/>
  <xs:element name='no-valid-streams' type='empty'/>

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

</xs:schema>

Appendices

Appendix A: Document Information

Series: XEP
Number: 0095
Publisher: XMPP Standards Foundation
Status: Draft
Type: Standards Track
Version: 1.1
Last Updated: 2004-04-13
Approving Body: XMPP Council
Dependencies: XMPP Core, XEP-0030
Supersedes: None
Superseded By: None
Short Name: si
Schema: <http://www.xmpp.org/schemas/si.xsd>
Registry: <http://xmpp.org/registrar/si.html>
Source Control: HTML
This document in other formats: XML  PDF

Appendix B: Author Information

Thomas Muldowney

Email: temas@jabber.org
JabberID: temas@jabber.org

Matthew Miller

Email: linuxwolf@outer-planes.net
JabberID: linuxwolf@outer-planes.net

Ryan Eatmon

Email: reatmon@jabber.org
JabberID: reatmon@jabber.org

Appendix C: Legal Notices

Copyright

This XMPP Extension Protocol is copyright © 1999 - 2013 by the XMPP Standards Foundation (XSF).

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. ##

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 from, out of, or in connection with the Specification or the implementation, deployment, or other use of 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 can be found at <http://xmpp.org/about-xmpp/xsf/xsf-ipr-policy/> or obtained by writing to XMPP Standards Foundation, 1899 Wynkoop Street, Suite 600, Denver, CO 80202 USA).

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) 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.

Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.

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

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-0030: Service Discovery <http://xmpp.org/extensions/xep-0030.html>.

2. XEP-0096: SI File Transfer <http://xmpp.org/extensions/xep-0096.html>.

3. 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/>.

4. This mapping is provided for the purpose of simplifying this discussion, and is not intended to be used in the actual protocol.

5. XEP-0086: Error Condition Mappings <http://xmpp.org/extensions/xep-0086.html>.

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/>.

Appendix H: Revision History

Note: Older versions of this specification might be available at http://xmpp.org/extensions/attic/

Version 1.1 (2004-04-13)

More fully defined the XMPP Registrar considerations. (psa)

Version 1.0 (2003-10-17)

Per a vote of the Jabber Council, advanced status to Draft. (psa)

Version 0.6 (2003-07-15)

Stream ids not needed on return results. Moved s5b, ibb, and url-data to the actual namespaces of the stream protocols. (rwe)

Version 0.5 (2003-07-06)

Removed signalling; Strengthened the profile definition requirements; Allowed for optional feature negotiation under certain circumstances (lw)

Version 0.4 (2003-06-30)

Actually added XML schemas; Added clarifications/requirements for stream interaction.; Fixed various typos and inconsistencies (lw)

Version 0.3 (2003-06-30)

Added XML schemas; Added XMPP-style error conditions; Added signal/notification support; Moderate reorganization to accommodate changes (lw)

Version 0.2 (2003-06-23)

Added linuxwolf as an author (should have been there from the start), form uses stream-method as the field var, clarified the stream interaction. (tjm)

Version 0.1 (2003-06-10)

Initial version. (tjm)

END