xep-0114.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>Jabber Component Protocol</title>
  <abstract>This specification documents the existing protocol used for communication between servers and "external" components over the Jabber network.</abstract>
  &LEGALNOTICE;
  <number>0114</number>
  <status>Active</status>
  <type>Historical</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>component</shortname>
  <schemaloc>
    <ns>jabber:component:accept</ns>
    <url>http://xmpp.org/schemas/component-accept.xsd</url>
  </schemaloc>
  <schemaloc>
    <ns>jabber:component:connect</ns>
    <url>http://xmpp.org/schemas/component-connect.xsd</url>
  </schemaloc>
  &stpeter;
  <revision>
    <version>1.6</version>
    <date>2012-01-25</date>
    <initials>psa</initials>
    <remark>Removed unnecessary and unimplemented requirement to escape predefined XML entities.</remark>
  </revision>
  <revision>
    <version>1.5</version>
    <date>2005-03-03</date>
    <initials>psa</initials>
    <remark>Clarified handling of errors related to initial stream header and referred the reader to RFC 3920 for details.</remark>
  </revision>
  <revision>
    <version>1.4</version>
    <date>2004-11-05</date>
    <initials>psa</initials>
    <remark>Corrected error regarding to and from attributes.</remark>
  </revision>
  <revision>
    <version>1.3</version>
    <date>2004-07-21</date>
    <initials>psa</initials>
    <remark>Removed reference to UTF-16; further modified schema to track XMPP specifications.</remark>
  </revision>
  <revision>
    <version>1.2</version>
    <date>2004-03-01</date>
    <initials>psa</initials>
    <remark>Modified schema to track XMPP specifications.</remark>
  </revision>
  <revision>
    <version>1.1</version>
    <date>2004-01-06</date>
    <initials>psa</initials>
    <remark>Added schema.</remark>
  </revision>
  <revision>
    <version>1.0</version>
    <date>2003-10-08</date>
    <initials>psa</initials>
    <remark>Per a vote of the Jabber Council, changed status to Active.</remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2003-08-26</date>
    <initials>psa</initials>
    <remark>Initial version.</remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>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 specification provides such documentation.</p>
</section1>
<section1 topic='Concepts' anchor='concepts'>
  <p>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; 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.)</p>
  <p>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., &lt;log/&gt; and &lt;xdb/&gt; packets in the jabberd 1.x series); however, those internal protocols are out of scope for this document.</p>
</section1>
<section1 topic='Protocol Flow' anchor='proto'>
  <p>The main difference between the jabber:component:* namespaces and the 'jabber:client' or 'jabber:server' namespace is authentication. External components do not use the obsolete &xep0078; protocol (i.e., the 'jabber:iq:auth' namespace), nor do they (yet) use SASL authentication as defined in &xmppcore; (although a future component protocol would most likely use SASL). Instead, they use a special &lt;handshake/&gt; element whose XML character data specifies credentials for the component's session with the server. The protocol flow for stream negotiation and authentication using jabber:component:accept is as follows:</p>
    <example caption='Component sends stream header to server'><![CDATA[
<stream:stream
    xmlns='jabber:component:accept'
    xmlns:stream='http://etherx.jabber.org/streams'
    to='plays.shakespeare.lit'>
]]></example>
    <p>Note: In the 'jabber:component:accept' namespace, the value of the 'to' address is the component name, not the server name; <note>In the 'jabber:component:connect' namespace, the server would set the 'from' attribute to the component name.</note> this enables the server to determine whether it will service a component of that name (e.g., based on server configuration or some other implementation-specific mechanism). If so, the server MUST reply with a stream header.</p>
    <example caption='Server replies with stream header, including StreamID'><![CDATA[
<stream:stream
    xmlns:stream='http://etherx.jabber.org/streams'
    xmlns='jabber:component:accept'
    from='plays.shakespeare.lit'
    id='3BF96D32'>
]]></example>
    <p>If the server will not service the component name specified in the 'to' attribute of the stream header, it MUST return a stream error (e.g., &lt;conflict/&gt; or &lt;host-unknown/&gt;). If the server does not recognize or support the namespace specified in the stream header (e.g., it does not support streams qualified by the 'jabber:component:accept' namespace), it MUST return an &lt;invalid-namespace/&gt; stream error. For all errors related to the stream header, the server MUST follow the rules in Section 4.7.1 of <cite>XMPP Core</cite> by returning an opening stream tag, stream error element, and closing stream tag rather than merely a stream error element (refer to &rfc3920; for details).</p>
    <p>After receiving the stream header reply from the server, the component MUST send a &lt;handshake/&gt; element with appropriate contents. <note>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.</note></p>
    <example caption='Component sends handshake element'><![CDATA[
<handshake>aaee83c26aeeafcbabeabfcbcd50df997e0a2a1e</handshake>
]]></example>
    <p>The XML character data of the handshake element is computed according to the following algorithm:</p>
    <ol>
      <li>Concatenate the Stream ID received from the server with the shared secret.</li>
      <li>Hash the concatenated string according to the SHA1 algorithm, i.e., SHA1( concat (sid, password)).</li>
      <li>Ensure that the hash output is in hexadecimal format, not binary or base64.</li>
      <li>Convert the hash output to all lowercase characters.</li>
    </ol>
    <p>If the credentials supplied by the initiator are not valid, the receiver MUST close the stream and the underlying TCP connection, and SHOULD return a &lt;not-authorized/&gt; stream error.</p>
    <p>If the credentials are acceptable, the receiving application (in this case the server) MUST return an empty &lt;handshake/&gt; element.</p>
    <example caption='Server sends empty handshake element to acknowledge success'><![CDATA[
<handshake/>
]]></example>
    <p>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.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>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.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with the &IANA;</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <p>The &REGISTRAR; includes 'jabber:component:accept' and 'jabber:component:connect' in its registry of protocol namespaces.</p>
</section1>
<section1 topic='XML Schemas' anchor='schema'>
  <section2 topic='jabber:component:accept' anchor='schema-accept'>
    <code><![CDATA[
<?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:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0114: http://xmpp.org/extensions/xep-0114.html
    </xs:documentation>
  </xs:annotation>

  <xs:import namespace='urn:ietf:params:xml:ns:xmpp-stanzas'
             schemaLocation='http://xmpp.org/schemas/stanzaerror.xsd'/>

  <xs:import namespace='http://www.w3.org/XML/1998/namespace'
             schemaLocation='http://www.w3.org/2001/03/xml.xsd'/>

  <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-stanzas'>
        <xs:group   ref='err:stanzaErrorGroup'/>
        <xs:element ref='err:text'
                    minOccurs='0'
                    maxOccurs='1'/>
      </xs:sequence>
      <xs:attribute name='by' type='xs:string' use='optional'/>
      <xs:attribute name='type' use='required'>
        <xs:simpleType>
          <xs:restriction base='xs:NMTOKEN'>
            <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>
]]></code>
  </section2>
  <section2 topic='jabber:component:connect' anchor='schema-connect'>
    <code><![CDATA[
<?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:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0114: http://xmpp.org/extensions/xep-0114.html
    </xs:documentation>
  </xs:annotation>

  <xs:import namespace='urn:ietf:params:xml:ns:xmpp-stanzas'
             schemaLocation='http://xmpp.org/schemas/stanzaerror.xsd'/>

  <xs:import namespace='http://www.w3.org/XML/1998/namespace'
             schemaLocation='http://www.w3.org/2001/03/xml.xsd'/>

  <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-stanzas'>
        <xs:group   ref='err:streamErrorGroup'/>
        <xs:element ref='err:text'
                    minOccurs='0'
                    maxOccurs='1'/>
      </xs:sequence>
      <xs:attribute name='by' type='xs:string' use='optional'/>
      <xs:attribute name='type' use='required'>
        <xs:simpleType>
          <xs:restriction base='xs:NMTOKEN'>
            <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>
]]></code>
  </section2>
</section1>
</xep>