XEP-0087: Stream Initiation

WARNING: This document has been retracted by the author(s). Implementation of the protocol described herein is not recommended. Developers desiring similar functionality are advised to implement the protocol that supersedes this one (if any).

1. Introduction
2. Requirements
    2.1. Use Case
3. Basic Usage
4. Detailed Usage
    4.1. Profiles
    4.2. Stream Interaction
    4.3. <si> Explanation
    4.4. Error Codes
5. Security Considerations
6. IANA Considerations
7. XMPP Registrar Considerations
8. Formal Definition
    8.1. Schema
    8.2. DTD

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 more people begin to make use of streams in Jabber, there becomes a need for more descriptive negotiation of which stream to use. This document provides a method to negotiate a stream and provide some meta-information about the streams usage.

2. Requirements

2.1 Use Case

Sender wishes to interact with another user, using a method that requires streams.

Primary Flow:

Sender discovers if Receiver implements the desired profile. [E1]
Sender offers a stream initiation. [E2]
Receiver accepts stream initiation.
Sender uses the negotiated stream and profile to send the information.

Error Conditions:

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

3. Basic Usage

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 discovered by using Service Discovery [1]:

    
    <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 will advertise the "http://jabber.org/protocol/si" namespace as a feature to represent they implement this document. The specific profiles can be found by looking for "http://jabber.org/protocol/si/profile/profile-name". Shown in the result is a potential file transfer profile:

    
    <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='htpt://jabber.org/protocol/si/profile/filexfer'/>
      </query>
    </iq>

Now that the Sender is sure that the Receiver support Stream Initiation they send the offer:

    
    <iq type='set' id='offer1' to='receiver@jabber.org/resource'>
      <si 
        xmlns='http://jabber.org/protocol/si' 
        id='a0'
        mime-type='application/octet-stream'
        profile='http://jabber.org/protocol/si/profile/profile-name'>
        <header name='key'>value</header>
        <feature xmlns='http://jabber.org/protocol/feature-neg'>
          <x xmlns='jabber:x:data'>
            <field var='file-transfer-method' type='list-single'>
              <option><value>s5b</value></option>
              <option><value>jabber:iq:oob</value></option>
              <option><value>ibb</value></option>
            </field>
          </x>
        </feature>
      </si>
    </iq>

At this point the Receiver can view the headers and other information to decide if they wish to accept the Stream Initiation. If they accept they MUST select one of the presented stream types to use. If none of the stream types are acceptable the Receiver MUST reply with an error:

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

    
    <iq type='error' to='sender@jabber.org/resource' id='offer1'>
      <error code='403'>Offer Declined</error>
    </iq>

    
    <iq type='error' to='sender@jabber.org/resource' id='offer1'>
      <error code='406'>No Valid Streams</error>
    </iq>

If the Receiver has accepted the Stream Initiation the Sender may then used the semantics defined by the selected stream and start the usage.

4. Detailed Usage

4.1 Profiles

While Stream Initiation itself is helpful, it makes much more sense when what is being transported over the stream is known. Knowing this allows the Receiver to make a more educated choice about whether or not to accept the stream. This information is transported in Stream Initiation through a profile. A profile is a series of required and optional headers that describe the stream data or how the stream is to be used. Each Stream Initiation MUST have only one profile, so the stream usage is kept clear.

Creating a profile is fairly simple. First, a name is chosen, the complete name is formatted like:

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

The complete name is what is presented in information discovery requests in order to show that the profile is supported. It is also used for the <si> profile attribute. Next, the information for the headers is decided upon. Each piece of information will be transported in a <header> tag. The name attribute is a descriptive key that can be looked up at the XMPP Registrar or XEP describing the profile. The actual data in the <header> is the fact related to the name attribute. It must also be stated whether the header is required or optional.

This document does not define any profiles, nor does it place any restrictions on what type of information a profile should detail. This document also does not place restrictions on what may be placed in a <header>. Other XEPs will define profiles to be used with Stream Initiation.

4.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 of the <si> node is intended to provide this link. It is out of scope of this document to define how streams will make use of this facility, but it does suggest some methods:

Transport the Stream Initiation id with the stream negotitation as a namespaced attribute, such as:

            
            <stream id='0' xmlns:si='http://jabber.org/protocol/si' si:id='si0'>
              <start/>
            </stream>

Transport the Stream Initiation id in a namespaced tag, such as:

            
            <stream id='0'>
              <start/>
              <si xmlns='http://jabber.org/protocol/si' id='si0'/>
            </stream>

4.3 <si> Explanation

The attributes and data of <si> are fairly simple:

id - An opaque identifier generated by the Sender.
mime-type - The mime-type of the data being negotiated, selected by Sender.
profile - The profile's fulle name, selected by Sender.

The data of the node is a mixture of a feature negotiation for the stream and the profiles headers.

When the Sender is offering a Stream Initiation all of the attributes must be present. The data MUST contain the required profile headers and the feature negotiation for the stream MUST be present with at least one option. The optional profile headers MAY also be in the node data.

When the Receiver accepts a Stream Initiation the id attribute MUST be present, all other attributes MUST NOT be present. The selected stream MUST be in the feature negotiation for the stream. There MUST only be one selected stream.

4.4 Error Codes

There are two error codes that are used. Following are the conditions, meanings and data:

Declining Transfer (403): During the Stream Initiation the Receiver may decline the transfer by sending the 403 error. The <error/> CDATA MAY contain a descriptive reason why, but is not necessary.
No Available Methods (406): When the Sender presents the available stream methods, and the Receiver can not use any of them, they send a 406 error. The <error/> CDATA is not important.

5. Security Considerations

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

6. IANA Considerations

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

7. XMPP Registrar Considerations

The "http://jabber.org/protocol/si" namespace will be registered. The registrar will track header profiles for different stream initiation uses.

8. Formal Definition

8.1 Schema

To follow.

Appendices

Appendix A: Document Information

Series: XEP
Number: 0087
Publisher: XMPP Standards Foundation
Status: Retracted
Type: Standards Track
Version: 0.1
Last Updated: 2003-05-22
Approving Body: XMPP Council
Dependencies: None
Supersedes: None
Superseded By: None
Short Name: si
Source Control: HTML
This document in other formats: XML PDF

Appendix B: Author Information

Thomas Muldowney

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

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

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

Abstract:	A common method to initiate a stream with meta information
Author:	Thomas Muldowney
Copyright:	© 1999 - 2011 XMPP Standards Foundation. SEE LEGAL NOTICES.
Status:	Retracted
Type:	Standards Track
Version:	0.1
Last Updated:	2003-05-22