XEP-0124: HTTP Binding

  XMPP Server
      |
      |  [XML streams or server API]
      |
Connection Manager
      |
      |  [HTTP + <body/> wrapper]
      |
  HTTP Client
    
POST /webclient HTTP/1.1
Host: httpcm.jabber.org
Accept-Encoding: gzip, deflate
Content-Type: text/xml; charset=utf-8
Content-Length: 104

<body content='text/xml; charset=utf-8'
      hold='1'
      rid='1573741820'
      to='jabber.org'
      route='xmpp:jabber.org:9999'
      secure='true'
      wait='60'
      xml:lang='en'
      xmlns='http://jabber.org/protocol/httpbind'/>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 128

<body authid='ServerStreamID'
      wait='60'
      inactivity='30'
      polling='5'
      requests='2'
      accept='deflate,gzip'
      sid='SomeSID'
      secure='true'
      charsets='ISO_8859-1 ISO-2022-JP'
      xmlns='http://jabber.org/protocol/httpbind'/>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 417

<body authid='ServerStreamID'
      wait='60'
      inactivity='30'
      polling='5'
      requests='2'
      accept='deflate,gzip'
      sid='SomeSID'
      charsets='ISO_8859-1 ISO-2022-JP'
      xmlns='http://jabber.org/protocol/httpbind'
      xmlns:stream='http://etherx.jabber.org/streams'>
  <stream:features>
    <mechanisms xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
      <mechanism>DIGEST-MD5</mechanism>
      <mechanism>PLAIN</mechanism>
    </mechanisms>
    <bind xmlns='urn:ietf:params:xml:ns:xmpp-bind'>
    <session xmlns='urn:ietf:params:xml:ns:xmpp-session'>
  </stream:features>
</body>
POST /webclient HTTP/1.1
Host: httpcm.jabber.org
Accept-Encoding: gzip, deflate
Content-Type: text/xml; charset=utf-8
Content-Length: 172

<body rid='1573741821'
      sid='SomeSID'
      xmlns='http://jabber.org/protocol/httpbind'>
  <auth xmlns='urn:ietf:params:xml:ns:xmpp-sasl' mechanism='DIGEST-MD5'/>
</body>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 250

<body xmlns='http://jabber.org/protocol/httpbind'>
  <challenge xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
    cmVhbG09InNvbWVyZWFsbSIsbm9uY2U9Ik9BNk1HOXRFUUdtMmhoIixxb3A9
    ImF1dGgiLGNoYXJzZXQ9dXRmLTgsYWxnb3JpdGhtPW1kNS1zZXNzCg==
  </challenge>
</body>
POST /webclient HTTP/1.1
Host: httpcm.jabber.org
Accept-Encoding: gzip, deflate
Content-Type: text/xml; charset=utf-8
Content-Length: 418

<body rid='1573741822'
      sid='SomeSID'
      xmlns='http://jabber.org/protocol/httpbind'>
  <response xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
    dXNlcm5hbWU9InNvbWVub2RlIixyZWFsbT0ic29tZXJlYWxtIixub25jZT0i
    T0E2TUc5dEVRR20yaGgiLGNub25jZT0iT0E2TUhYaDZWcVRyUmsiLG5jPTAw
    MDAwMDAxLHFvcD1hdXRoLGRpZ2VzdC11cmk9InhtcHAvZXhhbXBsZS5jb20i
    LHJlc3BvbnNlPWQzODhkYWQ5MGQ0YmJkNzYwYTE1MjMyMWYyMTQzYWY3LGNo
    YXJzZXQ9dXRmLTgK
  </response>
</body>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 190

<body xmlns='http://jabber.org/protocol/httpbind'>
  <challenge xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
    cnNwYXV0aD1lYTQwZjYwMzM1YzQyN2I1NTI3Yjg0ZGJhYmNkZmZmZAo=
  </challenge>
</body>
POST /webclient HTTP/1.1
Host: httpcm.jabber.org
Accept-Encoding: gzip, deflate
Content-Type: text/xml; charset=utf-8
Content-Length: 152

<body rid='1573741823'
      sid='SomeSID'
      xmlns='http://jabber.org/protocol/httpbind'>
  <response xmlns='urn:ietf:params:xml:ns:xmpp-sasl'/>
</body>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 121

<body xmlns='http://jabber.org/protocol/httpbind'>
  <success xmlns='urn:ietf:params:xml:ns:xmpp-sasl'/>
</body>
POST /webclient HTTP/1.1
Content-Type: text/xml; charset=utf-8
Content-Length: 240

<body rid='1573741824'
      sid='SomeSID'
      xmlns='http://jabber.org/protocol/httpbind'>
  <iq id='bind_1'
      type='set'
      xmlns='jabber:client'>
    <bind xmlns='urn:ietf:params:xml:ns:xmpp-bind'>
      <resource>httpclient</resource>
    </bind>
  </iq>
</body>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 221

<body xmlns='http://jabber.org/protocol/httpbind'>
  <iq id='bind_1'
      type='result'
      xmlns='jabber:client'>
    <bind xmlns='urn:ietf:params:xml:ns:xmpp-bind'>
      <jid>stpeter@jabber.org/httpclient</jid>
    </bind>
  </iq>
</body>
POST /webclient HTTP/1.1
Content-Type: text/xml; charset=utf-8
Content-Length: 261

<body rid='1573741825'
      sid='SomeSID'
      xmlns='http://jabber.org/protocol/httpbind'>
  <iq from='stpeter@jabber.org/httpclient'
      id='sess_1'
      to='jabber.org'
      type='set'
      xmlns='jabber:client'>
    <session xmlns='urn:ietf:params:xml:ns:xmpp-session'/>
  </iq>
</body>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 175

<body xmlns='http://jabber.org/protocol/httpbind'>
  <iq from='jabber.org'
      id='sess_1'
      to='stpeter@jabber.org/httpclient'
      type='result'
      xmlns='jabber:client'/>
</body>
POST /webclient HTTP/1.1
Host: httpcm.jabber.org
Accept-Encoding: gzip, deflate
Content-Type: text/xml; charset=utf-8
Content-Length: 281

<body rid='1249243561'
      sid='SomeSID'
      xmlns='http://jabber.org/protocol/httpbind'>
  <iq id='A01'
      type='set'
      xmlns='jabber:client'>
    <query xmlns='jabber:iq:auth'>
      <username>stpeter</username>
      <resource>httpclient</resource>
      <password>jabber-rocks</password>
    </query>
  </iq>
</body>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 144

<body xmlns='http://jabber.org/protocol/httpbind'>
  <iq id='A01'
      type='result'
      xmlns='jabber:client'/>
</body>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 226

<body xmlns='http://jabber.org/protocol/httpbind'>
  <iq id='A01'
      type='error'
      xmlns='jabber:client'>
    <error code='401' type='auth'>
      <not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    </error>
  </iq>
</body>
POST /webclient HTTP/1.1
Host: httpcm.jabber.org
Accept-Encoding: gzip, deflate
Content-Type: text/xml; charset=utf-8
Content-Length: 188

<body rid='1249243562'
      sid='SomeSID'
      xmlns='http://jabber.org/protocol/httpbind'>
  <message to='contact@example.com'
           xmlns='jabber:client'>
    <body>Hi there!</body>
  </message>
  <message to='friend@example.com'
           xmlns='jabber:client'>
    <body>Hi there!</body>
  </message>
</body>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 64

<body xmlns='http://jabber.org/protocol/httpbind'/>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 185

<body xmlns='http://jabber.org/protocol/httpbind'>
  <message from='contact@example.com'
           to='user@example.com'
           xmlns='jabber:client'>
    <body>Hi yourself!</body>
  </message>
  <message from='friend@example.com'
           to='user@example.com'
           xmlns='jabber:client'>
    <body>Hi yourself!</body>
  </message>
</body>
POST /webclient HTTP/1.1
Host: httpcm.jabber.org
Accept-Encoding: gzip, deflate
Content-Type: text/xml; charset=utf-8
Content-Length: 88

<body rid='1249243563'
      sid='SomeSID'
      xmlns='http://jabber.org/protocol/httpbind'/>
HTTP/1.1 403 Forbidden
Content-Type: text/xml; charset=utf-8
Content-Length: 0
POST /webclient HTTP/1.1
Host: httpcm.jabber.org
Accept-Encoding: gzip, deflate
Content-Type: text/xml; charset=utf-8
Content-Length: 153

<body rid='1249243564'
      sid='SomeSID'
      type='terminate'
      xmlns='http://jabber.org/protocol/httpbind'>
  <presence type='unavailable'
            xmlns='jabber:client'/>
</body>
HTTP/1.1 404 Not Found
Content-Type: text/xml; charset=utf-8
Content-Length: 0
HTTP/1.1 404 Not Found
Content-Type: text/xml; charset=utf-8
Content-Length: 0
        K(1) = hex(SHA-1(seed))
        K(2) = hex(SHA-1(K(1)))
        ...
        K(n) = hex(SHA-1(K(n-1)))
      
POST /webclient HTTP/1.1
Host: httpcm.jabber.org
Accept-Encoding: gzip, deflate
Content-Type: text/xml; charset=utf-8
Content-Length: 104

<body content='text/xml; charset=utf-8'
      hold='1'
      rid='1573741820'
      to='jabber.org'
      wait='60'
      xml:lang='en'
      newkey='ca393b51b682f61f98e7877d61146407f3d0a770'
      xmlns='http://jabber.org/protocol/httpbind'/>
POST /webclient HTTP/1.1
Host: httpcm.jabber.org
Accept-Encoding: gzip, deflate
Content-Type: text/xml; charset=utf-8
Content-Length: 88

<body rid='1573741821'
      sid='SomeSID'
      key='bfb06a6f113cd6fd3838ab9d300fdb4fe3da2f7d'
      xmlns='http://jabber.org/protocol/httpbind'/>
HTTP/1.1 404 Not Found
Content-Type: text/xml; charset=utf-8
Content-Length: 0
POST /webclient HTTP/1.1
Host: httpcm.jabber.org
Accept-Encoding: gzip, deflate
Content-Type: text/xml; charset=utf-8
Content-Length: 188

<body rid='1573741822'
      sid='SomeSID'
      key='6f825e81f4532b2c5fa2d12457d8a1f22e8f838e'
      newkey='113f58a37245ec9637266cf2fb6e48bfeaf7964e'
      xmlns='http://jabber.org/protocol/httpbind'>
  <message to='contact@example.com'
           xmlns='jabber:client'>
    <body>Hi there!</body>
  </message>
</body>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 128

<body authid='ServerStreamID'
      wait='60'
      inactivity='30'
      polling='5'
      requests='2'
      accept='deflate,gzip'
      sid='SomeSID'
      secure='true'
      stream='firstStreamName'
      charsets='ISO_8859-1 ISO-2022-JP'
      xmlns='http://jabber.org/protocol/httpbind'/>
POST /webclient HTTP/1.1
Host: httpcm.jabber.org
Accept-Encoding: gzip, deflate
Content-Type: text/xml; charset=utf-8
Content-Length: 104

<body sid='SomeSID'
      rid='1573741820'
      to='jabber.org'
      route='xmpp:jabber.org:9999'
      secure='true'
      xml:lang='en'
      xmlns='http://jabber.org/protocol/httpbind'/>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 128

<body stream='secondStreamName'
      authid='ServerStreamID'
      secure='true'
      xmlns='http://jabber.org/protocol/httpbind'/>
POST /webclient HTTP/1.1
Host: httpcm.jabber.org
Accept-Encoding: gzip, deflate
Content-Type: text/xml; charset=utf-8
Content-Length: 188

<body rid='1249243562'
      sid='SomeSID'
      stream='secondStreamName'
      xmlns='http://jabber.org/protocol/httpbind'>
  <message to='contact@example.com'
           xmlns='jabber:client'>
    <body>Hi there!</body>
  </message>
</body>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 185

<body stream='firstStreamName'
      xmlns='http://jabber.org/protocol/httpbind'>
  <message from='contact@example.com'
           to='user@example.com'
           xmlns='jabber:client'>
    <body>Hi yourself!</body>
  </message>
</body>
POST /webclient HTTP/1.1
Host: httpcm.jabber.org
Accept-Encoding: gzip, deflate
Content-Type: text/xml; charset=utf-8
Content-Length: 188

<body rid='1249243562'
      sid='SomeSID'
      xmlns='http://jabber.org/protocol/httpbind'>
  <presence xmlns='jabber:client'>
    <show>away</show>
  </presence>
</body>
POST /webclient HTTP/1.1
Host: httpcm.jabber.org
Accept-Encoding: gzip, deflate
Content-Type: text/xml; charset=utf-8
Content-Length: 153

<body rid='1249243564'
      sid='SomeSID'
      stream='secondStreamName'
      type='terminate'
      xmlns='http://jabber.org/protocol/httpbind'>
  <presence type='unavailable'
            xmlns='jabber:client'/>
</body>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 68

<body type='terminate'
      condition='remote-connection-failed'
      stream='secondStreamName'
      xmlns='http://jabber.org/protocol/httpbind'/>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 68

<body type='terminate'
      condition='remote-connection-failed'
      xmlns='http://jabber.org/protocol/httpbind'/>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 68

<body condition='see-other-uri'
      type='terminate'
      xmlns='http://jabber.org/protocol/httpbind'>
  <uri>https://secure.jabber.org/xmppcm</uri>
</body>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 68

<body condition='remote-stream-error'
      type='terminate'
      xmlns='http://jabber.org/protocol/httpbind'>
  <xml-not-well-formed xmlns='urn:ietf:params:xml:ns:xmpp-streams'/>
  <text xmlns='urn:ietf:params:xml:ns:xmpp-streams'
        xml:lang='en'>
    Some special application diagnostic information!
  </text>
  <escape-your-data xmlns='application-ns'/>
</body>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: 68

<body type='error'
      xmlns='http://jabber.org/protocol/httpbind'/>
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    xmlns:stream='http://etherx.jabber.org/streams'
    targetNamespace='http://jabber.org/protocol/httpbind'
    xmlns='http://jabber.org/protocol/httpbind'
    elementFormDefault='qualified'>

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

  <xs:import namespace='http://etherx.jabber.org/streams'
             schemaLocation='http://www.xmpp.org/schemas/streams.xsd'/>

  <xs:element name='body'>
    <xs:complexType>
      <xs:choice xmlns:stream='http://etherx.jabber.org/streams'>
        <xs:element ref='stream:features'
                minOccurs='0'
                maxOccurs='1'/>
        <xs:any namespace='urn:ietf:params:xml:ns:xmpp-tls'
                minOccurs='0'
                maxOccurs='1'/>
        <xs:any namespace='urn:ietf:params:xml:ns:xmpp-sasl'
                minOccurs='0'
                maxOccurs='1'/>
        <xs:any namespace='urn:ietf:params:xml:ns:xmpp-streams'
                minOccurs='0'
                maxOccurs='1'/>
        <xs:any namespace='jabber:client'
                minOccurs='0'
                maxOccurs='unbounded'/>
        <xs:element name='uri'
                minOccurs='0'
                maxOccurs='1'
                type='xs:string'/>
        <xs:any namespace='##other'
                minOccurs='0'
                maxOccurs='unbounded'
                processContents='lax'/>
      </xs:choice>
      <xs:attribute name='accept' type='xs:string' use='optional'/>
      <xs:attribute name='authid' type='xs:string' use='optional'/>
      <xs:attribute name='charsets' type='xs:NMTOKENS' use='optional'/>
      <xs:attribute name='condition' use='optional'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='host-gone'/>
            <xs:enumeration value='host-unknown'/>
            <xs:enumeration value='improper-addressing'/>
            <xs:enumeration value='internal-server-error'/>
            <xs:enumeration value='remote-connection-failed'/>
            <xs:enumeration value='remote-stream-error'/>
            <xs:enumeration value='see-other-uri'/>
            <xs:enumeration value='system-shutdown'/>
            <xs:enumeration value='undefined-condition'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute name='content' type='xs:string' use='optional'/>
      <xs:attribute name='hold' type='xs:byte' use='optional'/>
      <xs:attribute name='inactivity' type='xs:short' use='optional'/>
      <xs:attribute name='key' type='xs:string' use='optional'/>
      <xs:attribute name='newkey' type='xs:string' use='optional'/>
      <xs:attribute name='polling' type='xs:short' use='optional'/>
      <xs:attribute name='requests' type='xs:byte' use='optional'/>
      <xs:attribute name='rid' type='xs:positiveInteger' use='optional'/>
      <xs:attribute name='route' type='xs:string' use='optional'/>
      <xs:attribute name='secure' type='xs:boolean' use='optional' default='false'/>
      <xs:attribute name='sid' type='xs:string' use='optional'/>
      <xs:attribute name='stream' type='xs:string' use='optional'/>
      <xs:attribute name='to' type='xs:string' use='optional'/>
      <xs:attribute name='type' type='xs:string' use='optional'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='error'/>
            <xs:enumeration value='terminate'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute name='wait' type='xs:short' use='optional'/>
      <xs:attribute name='xml:lang' type='xs:string' use='optional'/>
      <xs:anyAttribute namespace='##other' processContents='lax'/>
    </xs:complexType>
  </xs:element>

</xs:schema>

Condition Type	Description
HTTP Conditions	The connection manager responds to an invalid client request with a standard HTTP error. These are used for binding syntax errors, possible attacks, etc. Note that constrained clients are unable to differentiate between HTTP errors.
Terminal Binding Conditions	These error conditions may be read by constrained clients. They are used for connection manager problems, abstracting stream errors, and communication problems between the connection manager and the XMPP server.
Recoverable Binding Conditions	These report communication problems between the connection manager and the client. They do not terminate the session. Clients recover from these errors by resending all the preceding <body/> wrapper elements that have not received responses.
XMPP Stanza Conditions	XMPP errors relating to XML stanzas within <body/> wrapper elements are, in general, defined in the appropriate RFC or XEP. They do not terminate the session. (An example of such usage is shown in jabber:iq:auth above.)

Code	Name	Purpose
200	OK	Response to valid client request.
400	Bad Request	Inform client that the format of an HTTP header or binding element is unacceptable (e.g., syntax error).
403	Forbidden	Inform client that it has broken the session rules (polling too-frequently, too many simultaneous connections).
404	Not Found	Inform client that (1) 'sid' is not valid, (2) 'stream' is not valid, (3) 'rid' is larger than the upper limit of the expected window, (4) connection manager is unable to resend response, (5) 'key' sequence is invalid.

Condition	Purpose
host-gone	The target domain specified in the 'to' attribute or the target host or port specified in the 'route' attribute is no longer serviced by the connection manager.
host-unknown	The target domain specified in the 'to' attribute or the target host or port specified in the 'route' attribute is unknown to the connection manager.
improper-addressing	The initialization element lacks a 'to' or 'route' attribute (or the attribute has no value) but the connection manager requires one.
internal-server-error	The connection manager has experienced an internal error that prevents it from servicing the request.
other-request	Another request being processed at the same time as this request caused the session to terminate.
remote-connection-failed	The connection manager was unable to connect to, or unable to connect securely to, or has lost its connection to, the XMPP server.
remote-stream-error	Encapsulates an XMPP stream error. The content of the binding is a copy of the content of the <stream:error/> element received from the XMPP server.
see-other-uri	The connection manager does not operate at this URI (e.g., the connection manager accepts only SSL or TLS connections at some https: URI rather than the http: URI requested by the client). The client may try POSTing to the URI in the content of the <uri/> child element.
system-shutdown	The connection manager is being shut down. All active HTTP sessions are being terminated. No new sessions can be created.
undefined-condition	The error is not one of those defined herein; the connection manager SHOULD include application-specific information in the content of the <body/> wrapper element.

XEP-0124: HTTP Binding

Document Information

Author Information

Ian Paterson

Dave Smith

Peter Saint-Andre

Legal Notice

Discussion Venue

Relation to XMPP

Conformance Terms

Table of Contents

1. Introduction

2. Terminology

2.1 HTTP Terms

3. Requirements

4. Architectural Assumptions

5. HTTP Version and HTTP Headers

6. Compression

7. <body/> Wrapper Element

8. Initiating an HTTP Session

8.1 Requesting a Session

8.2 Session Creation

8.3 Communication of Stream Features

9. Additional Preconditions

9.1 XMPP Methods

9.2 jabber:iq:auth

10. Sending and Receiving XML Stanzas

11. Terminating the HTTP Session

12. Request IDs

12.1 Syntax

12.2 In-Order Message Forwarding

12.3 Broken Connections

13. Protecting Insecure Sessions

13.1 Applicability

13.2 Introduction

13.3 Generating the Key Sequence

13.4 Use of Keys

13.5 Switching to Another Key Sequence

14. Multiple Streams

14.1 Introduction

14.2 Discovery

14.3 Adding Streams To A Session

14.4 Transmitting Stanzas

14.5 Closing a Stream

14.6 Error Conditions

15. Error and Status Codes

15.1 HTTP Conditions

15.2 Terminal Binding Conditions

15.3 Recoverable Binding Conditions

15.4 XMPP Stanza Conditions

16. Implementation Notes

17. Security Considerations

18. IANA Considerations

19. XMPP Registrar Considerations

19.1 Protocol Namespaces

20. XML Schema

Notes

Revision History

Version 1.5 (2006-04-28)

Version 1.4 (2005-12-14)

Version 1.3 (2005-11-02)

Version 1.2 (2005-06-16)

Version 1.1 (2005-06-02)

Version 1.0 (2005-03-03)

Version 0.10 (2004-11-08)

Version 0.9 (2004-10-26)

Version 0.8 (2004-10-26)

Version 0.7 (2004-08-12)

Version 0.6 (2004-07-19)

Version 0.5 (2004-05-07)

Version 0.4 (2004-02-23)

Version 0.3 (2004-02-19)

Version 0.2 (2004-01-13)

Version 0.1 (2003-11-06)