JEP-0114: Jabber Component Protocol

This JEP documents the existing protocol used for communication between servers and "external" components over the Jabber network.

NOTICE: This Historical JEP provides canonical documentation of a protocol that is in wide use within the Jabber community. This JEP is not a standards-track specification within the Jabber Software Foundation's standards process; therefore it may be converted to standards-track in the future or may be obsoleted by a more modern protocol.

JEP Information

Status: Active
Type: Historical
Number: 0114
Version: 1.3
Last Updated: 2004-07-21
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core
Supersedes: None
Superseded By: None
Short Name: component
Schema for jabber:component:accept: <http://jabber.org/protocol/component/accept.xsd>
Schema for jabber:component:connect: <http://jabber.org/protocol/component/connect.xsd>

Author Information

Peter Saint-Andre

Email: stpeter@jabber.org
JID: stpeter@jabber.org

Legal Notice

This Jabber Enhancement Proposal is copyright 1999 - 2004 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <http://www.jabber.org/jsf/ipr-policy.php>. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at <http://www.opencontent.org/openpub/>).

Discussion Venue

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

Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core and XMPP IM specifications contributed by the Jabber Software Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocols defined in this JEP have been developed outside the Internet Standards Process and are to be understood as extensions to XMPP rather than as an evolution, development, or modification of XMPP itself.

Conformance Terms

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

Table of Contents

1. Introduction
2. Concepts
3. Details
4. Security Considerations
5. IANA Considerations
6. Jabber Registrar Considerations
7. XML Schemas
7.1. jabber:component:accept
7.2. jabber:component:connect
Notes
Revision History

1. Introduction

The Jabber network has long included a wire protocol that enables trusted components to connect to Jabber servers. While this component protocol is minimal and will probably be superseded by a more comprehensive component protocol at some point, informational documentation of the existing protocol would be helpful for component and server developers. This JEP provides such documentation.

2. Concepts

Traditionally there have been two basic kinds of server-side components: "internal components" (which utilize the internal API of a server, in the past particularly the jabberd [1] server) and "external components" (which communicate with a server over a wire protocol and therefore are not tied to any particular server implementation). The wire component protocol in use today enables an external component to connect to a server (with proper configuration and authentication) and to send and receive XML stanzas through the server. There are two connection methods: "accept" and "connect". When the "accept" method is used, the server waits for connections from components and accepts them when they are initiated by a component. When the "connect" method is used, the server initiates the connection to a component. The "accept" method is by far the most common method, but both are documented herein. (In the past, there has been one other connection method for external components: "execute". However, this method is obsolete and is not documented herein.)

An external component is called "trusted" because it authenticates with a server using authentication credentials that include a shared secret. This secret is commonly specified in the configuration files used by the server and component, but could be provided at runtime on the command line or extracted from a database. An external component is commonly trusted to do things that clients cannot, such as write 'from' addresses for the server's domain(s). Some server may also allow components to send packets that are used by the server's internal protocol (e.g., <log/> and <xdb/> packets in the jabberd 1.x series); however, those internal protocols are out of scope for this JEP.

3. Details

The main difference between the jabber:component:* namespaces and the 'jabber:client' or 'jabber:server' namespace is authentication. External components do not use the older Non-SASL Authentication [2] protocol (i.e., the 'jabber:iq:auth' namespace), nor do they (yet) use SASL authentication as defined in XMPP Core [3] (although a future component protocol would most likely use SASL). Instead, they use a special <handshake/> element whose CDATA contains credentials for the component's session with the server. The protocol flow is as follows:

Example 1. Stream Negotiation and Authentication


C: Component sends stream header to server

<stream:stream
    xmlns='jabber:component:accept'
    xmlns:stream='http://etherx.jabber.org/streams'
    to='shakespeare.lit'>

S: Server replies with stream header, including StreamID

<stream:stream
    xmlns:stream='http://etherx.jabber.org/streams'
    xmlns='jabber:component:accept'
    from='shakespeare.lit'
    id='3BF96D32'>

C: Component sends handshake element

<handshake>aaee83c26aeeafcbabeabfcbcd50df997e0a2a1e</handshake>

S: Server sends empty handshake element to acknowledge success

<handshake/>

If the credentials supplied by the initiator are not valid, the receiver MUST close the stream and the underlying TCP connection.

The handshake value is always supplied by the initiator. Thus for jabber:component:accept connections, the handshake value is provided by the component, whereas for jabber:component:connect connections, the handshake value is provided by the server.

The CDATA of the handshake element is computed according to the following algorithm:

  1. Concatenate the Stream ID received from the server with the shared secret (if necessary, characters that map to predefined XML entities MUST be escaped according to the rules defined in section 4.6 of the XML specification, and any non-ASCII characters MUST be encoded according to the encoding of XML streams as specified in XMPP Core, i.e., UTF-8 as defined in RFC 3269 [4]).
  2. Hash the concatenated string according to the SHA1 algorithm, i.e., SHA1( concat (sid, password)).
  3. Ensure that the hash output is in hexadecimal format, not binary or base64.
  4. Convert the hash output to all lowercase characters.

Once authenticated, the component can send stanzas through the server and receive stanzas from the server. All stanzas sent to the server MUST possess a 'from' attribute and a 'to' attribute, as in the 'jabber:server' namespace. The domain identifier portion of the JID contained in the 'from' attribute MUST match the hostname of the component. However, this is the only restriction on 'from' addresses, and the component MAY send stanzas from any user at its hostname.

4. Security Considerations

Given that an external component is trusted to write 'from' addresses for any user at the component's hostname, server administrators SHOULD make sure that they in fact do trust the component software.

5. IANA Considerations

This JEP requires no interaction with the the Internet Assigned Numbers Authority (IANA) [5]

6. Jabber Registrar Considerations

The 'jabber:component:accept' and 'jabber:component:connect' namespaces shall be registered with Jabber Registrar [6] as a result of this JEP.

7. XML Schemas

7.1 jabber:component:accept 

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

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    xmlns:xml='http://www.w3.org/XML/1998/namespace'
    targetNamespace='jabber:component:accept'
    xmlns='jabber:component:accept'
    elementFormDefault='qualified'>

  <xs:import namespace='urn:ietf:params:xml:ns:xmpp-streams'/>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      JEP-0114: http://www.jabber.org/jeps/jep-0114.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='handshake' type='xs:string'/>

  <xs:element name='message'>
     <xs:complexType>
        <xs:sequence>
          <xs:choice minOccurs='0' maxOccurs='unbounded'>
            <xs:element ref='subject'/>
            <xs:element ref='body'/>
            <xs:element ref='thread'/>
          </xs:choice>
          <xs:any     namespace='##other'
                      minOccurs='0'
                      maxOccurs='unbounded'/>
          <xs:element ref='error'
                      minOccurs='0'/>
        </xs:sequence>
        <xs:attribute name='from'
                      type='xs:string'
                      use='required'/>
        <xs:attribute name='id'
                      type='xs:NMTOKEN'
                      use='optional'/>
        <xs:attribute name='to'
                      type='xs:string'
                      use='required'/>
        <xs:attribute name='type' use='optional' default='normal'>
          <xs:simpleType>
            <xs:restriction base='xs:NCName'>
              <xs:enumeration value='chat'/>
              <xs:enumeration value='error'/>
              <xs:enumeration value='groupchat'/>
              <xs:enumeration value='headline'/>
              <xs:enumeration value='normal'/>
            </xs:restriction>
          </xs:simpleType>
        </xs:attribute>
        <xs:attribute ref='xml:lang' use='optional'/>
     </xs:complexType>
  </xs:element>

  <xs:element name='body'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:string'>
          <xs:attribute ref='xml:lang' use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='subject'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:string'>
          <xs:attribute ref='xml:lang' use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='thread' type='xs:NMTOKEN'/>

  <xs:element name='presence'>
    <xs:complexType>
      <xs:sequence>
        <xs:choice minOccurs='0' maxOccurs='unbounded'>
          <xs:element ref='show'/>
          <xs:element ref='status'/>
          <xs:element ref='priority'/>
        </xs:choice>
        <xs:any     namespace='##other'
                    minOccurs='0'
                    maxOccurs='unbounded'/>
        <xs:element ref='error'
                    minOccurs='0'/>
      </xs:sequence>
      <xs:attribute name='from'
                    type='xs:string'
                    use='required'/>
      <xs:attribute name='id'
                    type='xs:NMTOKEN'
                    use='optional'/>
      <xs:attribute name='to'
                    type='xs:string'
                    use='required'/>
      <xs:attribute name='type' use='optional'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='subscribe'/>
            <xs:enumeration value='subscribed'/>
            <xs:enumeration value='unsubscribe'/>
            <xs:enumeration value='unsubscribed'/>
            <xs:enumeration value='unavailable'/>
            <xs:enumeration value='probe'/>
            <xs:enumeration value='error'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute ref='xml:lang' use='optional'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='show'>
    <xs:simpleType>
      <xs:restriction base='xs:NCName'>
        <xs:enumeration value='away'/>
        <xs:enumeration value='chat'/>
        <xs:enumeration value='dnd'/>
        <xs:enumeration value='xa'/>
      </xs:restriction>
    </xs:simpleType>
  </xs:element>

  <xs:element name='status'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:string'>
          <xs:attribute ref='xml:lang' use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='priority' type='xs:byte'/>

  <xs:element name='iq'>
    <xs:complexType>
      <xs:sequence>
        <xs:any     namespace='##other'
                    minOccurs='0'
                    maxOccurs='1'/>
        <xs:element ref='error'
                    minOccurs='0'
                    maxOccurs='1'/>
      </xs:sequence>
      <xs:attribute name='from'
                    type='xs:string'
                    use='required'/>
      <xs:attribute name='id'
                    type='xs:NMTOKEN'
                    use='required'/>
      <xs:attribute name='to'
                    type='xs:string'
                    use='required'/>
      <xs:attribute name='type' use='required'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='get'/>
            <xs:enumeration value='set'/>
            <xs:enumeration value='result'/>
            <xs:enumeration value='error'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute ref='xml:lang' use='optional'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='error'>
    <xs:complexType>
      <xs:sequence  xmlns:err='urn:ietf:params:xml:ns:xmpp-streams'>
        <xs:group   ref='err:stanzaErrorGroup'/>
        <xs:element ref='err:text'
                    minOccurs='0'
                    maxOccurs='1'/>
      </xs:sequence>
      <xs:attribute name='code' type='xs:byte' use='optional'/>
      <xs:attribute name='type' use='required'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='cancel'/>
            <xs:enumeration value='continue'/>
            <xs:enumeration value='modify'/>
            <xs:enumeration value='auth'/>
            <xs:enumeration value='wait'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
    </xs:complexType>
  </xs:element>

</xs:schema>

7.2 jabber:component:connect 

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

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    xmlns:xml='http://www.w3.org/XML/1998/namespace'
    targetNamespace='jabber:component:connect'
    xmlns='jabber:component:connect'
    elementFormDefault='qualified'>

  <xs:import namespace='urn:ietf:params:xml:ns:xmpp-streams'/>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      JEP-0114: http://www.jabber.org/jeps/jep-0114.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='handshake' type='xs:string'/>

  <xs:element name='message'>
     <xs:complexType>
        <xs:sequence>
          <xs:choice minOccurs='0' maxOccurs='unbounded'>
            <xs:element ref='subject'/>
            <xs:element ref='body'/>
            <xs:element ref='thread'/>
          </xs:choice>
          <xs:any     namespace='##other'
                      minOccurs='0'
                      maxOccurs='unbounded'/>
          <xs:element ref='error'
                      minOccurs='0'/>
        </xs:sequence>
        <xs:attribute name='from'
                      type='xs:string'
                      use='required'/>
        <xs:attribute name='id'
                      type='xs:NMTOKEN'
                      use='optional'/>
        <xs:attribute name='to'
                      type='xs:string'
                      use='required'/>
        <xs:attribute name='type' use='optional' default='normal'>
          <xs:simpleType>
            <xs:restriction base='xs:NCName'>
              <xs:enumeration value='chat'/>
              <xs:enumeration value='error'/>
              <xs:enumeration value='groupchat'/>
              <xs:enumeration value='headline'/>
              <xs:enumeration value='normal'/>
            </xs:restriction>
          </xs:simpleType>
        </xs:attribute>
        <xs:attribute ref='xml:lang' use='optional'/>
     </xs:complexType>
  </xs:element>

  <xs:element name='body'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:string'>
          <xs:attribute ref='xml:lang' use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='subject'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:string'>
          <xs:attribute ref='xml:lang' use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='thread' type='xs:NMTOKEN'/>

  <xs:element name='presence'>
    <xs:complexType>
      <xs:sequence>
        <xs:choice minOccurs='0' maxOccurs='unbounded'>
          <xs:element ref='show'/>
          <xs:element ref='status'/>
          <xs:element ref='priority'/>
        </xs:choice>
        <xs:any     namespace='##other'
                    minOccurs='0'
                    maxOccurs='unbounded'/>
        <xs:element ref='error'
                    minOccurs='0'/>
      </xs:sequence>
      <xs:attribute name='from'
                    type='xs:string'
                    use='required'/>
      <xs:attribute name='id'
                    type='xs:NMTOKEN'
                    use='optional'/>
      <xs:attribute name='to'
                    type='xs:string'
                    use='required'/>
      <xs:attribute name='type' use='optional'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='subscribe'/>
            <xs:enumeration value='subscribed'/>
            <xs:enumeration value='unsubscribe'/>
            <xs:enumeration value='unsubscribed'/>
            <xs:enumeration value='unavailable'/>
            <xs:enumeration value='probe'/>
            <xs:enumeration value='error'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute ref='xml:lang' use='optional'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='show'>
    <xs:simpleType>
      <xs:restriction base='xs:NCName'>
        <xs:enumeration value='away'/>
        <xs:enumeration value='chat'/>
        <xs:enumeration value='dnd'/>
        <xs:enumeration value='xa'/>
      </xs:restriction>
    </xs:simpleType>
  </xs:element>

  <xs:element name='status'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:string'>
          <xs:attribute ref='xml:lang' use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  <xs:element name='priority' type='xs:byte'/>

  <xs:element name='iq'>
    <xs:complexType>
      <xs:sequence>
        <xs:any     namespace='##other'
                    minOccurs='0'
                    maxOccurs='1'/>
        <xs:element ref='error'
                    minOccurs='0'
                    maxOccurs='1'/>
      </xs:sequence>
      <xs:attribute name='from'
                    type='xs:string'
                    use='required'/>
      <xs:attribute name='id'
                    type='xs:NMTOKEN'
                    use='required'/>
      <xs:attribute name='to'
                    type='xs:string'
                    use='required'/>
      <xs:attribute name='type' use='required'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='get'/>
            <xs:enumeration value='set'/>
            <xs:enumeration value='result'/>
            <xs:enumeration value='error'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute ref='xml:lang' use='optional'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='error'>
    <xs:complexType>
      <xs:sequence  xmlns:err='urn:ietf:params:xml:ns:xmpp-streams'>
        <xs:group   ref='err:stanzaErrorGroup'/>
        <xs:element ref='err:text'
                    minOccurs='0'
                    maxOccurs='1'/>
      </xs:sequence>
      <xs:attribute name='code' type='xs:byte' use='optional'/>
      <xs:attribute name='type' use='required'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='cancel'/>
            <xs:enumeration value='continue'/>
            <xs:enumeration value='modify'/>
            <xs:enumeration value='auth'/>
            <xs:enumeration value='wait'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
    </xs:complexType>
  </xs:element>

</xs:schema>

Notes

1. The jabberd server is the original server implementation of the Jabber protocols, first developed by Jeremie Miller, inventor of Jabber. For further information, see <http://jabberd.jabberstudio.org/>.

2. JEP-0078: Non-SASL Authentication <http://www.jabber.org/jeps/jep-0078.html>.

3. RFC 3920: Extensible Messaging and Presence Protocol (XMPP): Core <http://www.ietf.org/rfc/rfc3920.txt>.

4. RFC 3269: UTF-8, a transformation format of ISO 10646 <http://www.ietf.org/rfc/rfc3269.txt>.

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 Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.

Revision History

Version 1.3 (2004-07-21)

Removed reference to UTF-16; further modified schema to track XMPP specifications. (psa)

Version 1.2 (2004-03-01)

Modified schema to track XMPP specifications. (psa)

Version 1.1 (2004-01-06)

Added schema. (psa)

Version 1.0 (2003-10-08)

Per a vote of the Jabber Council, changed status to Active. (psa)

Version 0.1 (2003-08-26)

Initial version. (psa)

END