<abstract>This specification documents the existing protocol used for communication between servers and "external" components over the Jabber network.</abstract>
<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>
<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., <log/> and <xdb/> packets in the jabberd 1.x series); however, those internal protocols are out of scope for this document.</p>
<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 <handshake/> 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>
<examplecaption='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>
<examplecaption='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., <conflict/> or <host-unknown/>). 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 <invalid-namespace/> 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 <cite>RFC 3920</cite> for details).</p>
<p>After receiving the stream header reply from the server, the component MUST send a <handshake/> 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>
<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 (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 <strong>XMPP Core</strong>, i.e., UTF-8 as defined in &rfc3269;).</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 <not-authorized/> stream error.</p>
<p>If the credentials are acceptable, the receiving application (in this case the server) MUST return an empty <handshake/> element.</p>
<examplecaption='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>
<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>
