XEP-0124
本文的英文原文来自XEP-0124
XEP-0124: 基于同步HTTP的双向流
| 摘要: | 本协议定义了一个传输协议来模拟两个实体 (例如一个客户端和一个服务器) 之间的长连双向TCP连接的语义，它有效地运用多个同步的HTTP"请求/应答"对，而不需要使用频繁的轮询或者分块响应. |
|---|---|
| 作者: | Ian Paterson, Dave Smith, Peter Saint-Andre, Jack Moffitt |
| 版权: | © 1999 - 2011 XMPP标准化基金会(XSF). 参见法律通告. |
| 状态: | 草案 |
| 类型: | 标准跟踪 |
| 版本: | 1.10 |
| 最后更新日期: | 2010-07-02 |
注意: 这里定义的协议是XMPP标准化基金会的一个 草案标准 .对本协议的执行是被鼓励的,也适于部署到生产系统,但是在它成为最终标准之前可能还会有一些变动.
简介
传输控制协议 (TCP; RFC 793 1 ) 经常用来建立两个实体之间的面向流的连接. 这些连接可以保持常连，使得实体之间的 "会话" 能够交互式的进行. 无论如何, 有时候设备或网络的性质可能会阻止一个应用程序去维护一个常连的TCP连接到一个服务器或对端. 在这种情况下, 需要使用一个替代的连接方法，使用排序的一系列请求和应答在短连的连接上交换信息来模拟常连的TCP连接. 通过 RFC1945 2 和 RFC2616 3 定义的超文本传输协议(HTTP)可以获得很多可用的合适的 请求-应答 语义.
BOSH, 本文定义的这种技术, 实质上为常连的双向TCP连接提供了一个 "drop-in" 的替代品. 它是一个成熟的, 全功能的技术，自2004年以来已经被广泛实现和布署. 据我们所知它是众多类似技术中的第一个, 它现在包含了正规化的Bayeux协议 4 的 彗星(Comet) 方法(译者注：Comet就是Ajax web应用程序的服务器推送技术的结合)，以及 Web Socket协议 5 和 反向HTTP 6.
BOSH被设计成有效地传输任何数据并且在两个方向上都保持最小延迟. 对应用程序来讲那同时需要 "推" 和 "拉" 语义, BOSH显然比其他大多数双向的基于HTTP的传输协议更节省带宽和响应更迅速，这个技术现在通常称为 "Ajax". BOSH通过对多个同步的"HTTP请求/响应对"使用所谓"长轮询"来达到高效. 此外, 通过使用不需要"cookies"而全兼容HTTP 1.0 (见 RFC 2965 7 ) 8 或甚至访问HTTP头，BOSH可以解决受限客户端的需要 .
BOSH原本是由 Jabber/XMPP 社区开发出来替代更早的基于HTTP的技术 Jabber HTTP轮询 9 . 尽管BOSH假定HTTP请求和应答的 "载荷" 是XML, 载荷的格式未受XMPP节 (见 XMPP Core 10 ) 的限制,并且可以包含不同协议定义的命名空间的元素的混合物 (例如, 同时包含 XMPP 和 JSON). 这种混合是必要的，因为一些连接管理者可能不支持多重流，而受限的客户端经常无法访问HTTP流水线 (这限制同一时间只能拥有一个BOSH会话). BOSH连接管理者通常不需要理解它们所传输的XML的任何内容，除了确保每个XML载荷被正确的命名空间所限定.
注意: XMPP Over BOSH 11 记录了一些以前包含在本协议中的XMPP特有的扩展.
需求
以下的设计需求反映了提供接近标准TCP连接的性能的需要.
- 和受约束的运行时环境兼容* (例如, 手机和基于浏览器的客户端).
- 和缓冲了部分HTTP应答的代理兼容.
- 高效的通过那些限制HTTP响应时间的代理.
- 完全兼容HTTP/1.0.
- 兼容受限的网络连接 (例如, 防火墙, 代理, 以及网关).
- 容错 (例如, 在HTTP请求的任何阶段，底层TCP连接中断之后，会话恢复).
- 可扩展.
- 带宽消耗显著低于基于轮询的协议.
- 比基于轮询的协议显著快速响应 (低延迟).
- 支持轮询 (支持那些限制同一时间只有一个HTTP连接的客户端轮询).
- 顺序递送数据.
- 防范未经授权的用户会话注入HTTP请求.
- 防止拒绝服务攻击.
- 复用数据流.
- 注意: 和受约束的运行环境兼容意味着以下限制:
- 客户端不需要编程访问每个HTTP请求和应答的头 (例如, cookies 或 状态码).
- 每个HTTP请求和应答的 body 是一个可解析的根元素的XML.
- 客户端可以指定它们接收的HTTP应答的 Content-Type.
Architectural Assumptions
This document assumes that most implementations will utilize a specialized connection manager ("CM") to handle HTTP connections rather than the native connection type for the relevant application (e.g., TCP connections in XMPP). Effectively, such a connection manager is a specialized HTTP server that translates between the HTTP requests and responses defined herein and the data streams (or API) implemented by the server with which it communicates, thus enabling a client to connect to a server via HTTP on port 80 or 443 instead of an application-specific port. We can illustrate this graphically as follows:
Server
|
| [unwrapped data streams]
|
HTTP CM
|
| [HTTP + <body/> wrapper]
|
Client
This specification covers communication only between a client and the connection manager. It does not cover communication between the connection manager and the server, since such communications are implementation-specific (e.g., the server might natively support this HTTP binding, in which case the connection manager will be a logical entity rather than a physical entity; alternatively the connection manager might be an independent translating proxy such that the server might believe it is talking directly to the client over TCP; or the connection manager and the server might use a component protocol or an API defined by the server implementation).
Furthermore, no aspect of this protocol limits its use to communication between a client and a server. For example, it could be used for communication between a server and a peer server if such communication can occur for the relevant application (e.g., in XMPP). However, this document focuses exclusively on use of the transport by clients that cannot maintain arbitrary persistent TCP connections with a server. We assume that servers and components are under no such restrictions and thus would use the native connection transport for the relevant application. (However, on some unreliable networks, BOSH might enable more stable communication between servers.)
The BOSH Technique
Since HTTP is a synchronous request/response protocol, the traditional solution to emulating a bidirectional-stream over HTTP involved the client intermittently polling the connection manager to discover if it has any data queued for delivery to the client. This naive approach wastes a lot of network bandwidth by polling when no data is available. It also reduces the responsiveness of the application since the data spends time queued waiting until the connection manager receives the next poll (HTTP request) from the client. This results in an inevitable trade-off between responsiveness and bandwidth, since increasing the polling frequency will decrease latency but simultaneously increase bandwidth consumption (or vice versa if polling frequency is decreased).
The technique employed by BOSH achieves both low latency and low bandwidth consumption by encouraging the connection manager not to respond to a request until it actually has data to send to the client. As soon as the client receives a response from the connection manager it sends another request, thereby ensuring that the connection manager is (almost) always holding a request that it can use to "push" data to the client.
If the client needs to send some data to the connection manager then it simply sends a second request containing the data. Unfortunately most constrained clients do not support HTTP Pipelining (concurrent requests over a single connection), so the client typically needs to send the data over a second HTTP connection. The connection manager always responds to the request it has been holding on the first connection as soon as it receives a new request from the client -- even if it has no data to send the client. It does so to make sure the client can send more data immediately if necessary. (The client SHOULD NOT open more than two HTTP connections to the connection manager at the same time, [12] so it would otherwise have to wait until the connection manager responds to one of the requests.)
BOSH works reliably even if network conditions force every HTTP request to be made over a different TCP connection. However, if as is usually the case, the client is able to use HTTP/1.1, then (assuming reliable network conditions) all requests during a session will pass over the same two persistent TCP connections. Almost all of the time (see below) the client is able to push data on one of the connections, while the connection manager is able to push data on the other (so latency is as low as a standard TCP connection). It's interesting to note that the roles of the two connections typically switch whenever the client sends data to the connection manager.
If there is no traffic in either direction for an agreed amount of time (typically several minutes), then the connection manager responds to the client with no data, and that response immediately triggers a fresh client request. The connection manager does so to ensure that if a network connection is broken then both parties will realise within a reasonable amount of time. This exchange is similar to the "keep-alive" or "ping" that is common practice over most persistent TCP connections. Since the BOSH technique involves no polling, bandwidth consumption is not significantly greater than a standard TCP connection. [13]
Most of the time data can be pushed immediately. However, if one of the endpoints has just pushed some data then it will usually have to wait for a network round trip until it is able to push again. If HTTP Pipelining is available to the client then multiple concurrent requests are possible. Thus the client can always push data immediately. It can also ensure the connection manager is always holding enough requests such that even during bursts of activity it will never have to wait before pushing data. Furthermore, if the pool of requests being held by the connection manager is large enough, then the client will not be under pressure to send a new empty request immediately after receiving data from the connection manager. It can instead wait until it needs to send data. Therefore, if over time the traffic to and from the client is balanced, bandwidth consumption will be about the same as if a standard TCP connection were being used.
Each block of data pushed by the connection manager is a complete HTTP response. So, unlike the Comet technique, the BOSH technique works through intermediate proxies that buffer partial HTTP responses. It is also fully compliant with HTTP/1.0 -- which does not provide for chunked transfer encoding.
HTTP Overview
All information is encoded in the body of standard HTTP POST requests and responses. Each HTTP body contains a single <body/> wrapper which encapsulates the XML elements being transferred (see <body/> Wrapper Element).
Clients SHOULD send all HTTP requests over a single persistent HTTP/1.1 connection using HTTP Pipelining. However, a client MAY deliver its POST requests in any way permitted by RFC 1945 or RFC 2616. For example, constrained clients can be expected to open more than one persistent connection instead of using Pipelining, or in some cases to open a new HTTP/1.0 connection to send each request. However, clients and connection managers SHOULD NOT use Chunked Transfer Coding, since intermediaries might buffer each partial HTTP request or response and only forward the full request or response once it is available.
Clients MAY include an HTTP Accept-Encoding header in any request. If the connection manager receives a request with an Accept-Encoding header, it MAY include an HTTP Content-Encoding header in the response (indicating one of the encodings specified in the request) and compress the response body accordingly.
Requests and responses MAY include HTTP headers not specified herein. The receiver SHOULD ignore any such headers.
Each BOSH session MAY share the HTTP connection(s) it uses with other HTTP traffic, including other BOSH sessions and HTTP requests and responses completely unrelated to this protocol (e.g., web page downloads). However, the responses to requests that are not part of the session sent over the same connection using HTTP pipelining (or queued to be sent over the same connection) might be delayed if they were sent while a request that is part of the session is being held (since the connection manager MUST send its responses in the same order that the requests were received, and the connection manager typically delays its responses).
The HTTP Content-Type header of all client requests SHOULD be "text/xml; charset=utf-8". However, clients MAY specify another value if they are constrained to do so (e.g., "application/x-www-form-urlencoded" or "text/plain"). The client and connection manager SHOULD ignore all HTTP Content-Type headers they receive.
<body/> Wrapper Element
The body of each HTTP request and response contains a single <body/> wrapper element qualified by the 'http://jabber.org/protocol/httpbind' namespace. The content of the wrapper is the data being transferred. The <body/> element and its content together MUST conform to the specifications set out in XML 1.0 [14]. They SHOULD also conform to Namespaces in XML [15]. The content MUST NOT contain any of the following (all defined in XML 1.0):
- Partial XML elements
- XML comments
- XML processing instructions
- Internal or external DTD subsets
- Internal or external entity references (with the exception of predefined entities)
The <body/> wrapper MUST NOT contain any XML character data, although its child elements MAY contain character data. The <body/> wrapper MUST contain zero or more complete XML immediate child elements (called "payloads" in this document, e.g., XMPP stanzas as defined in RFC 6120 or elements containing XML character data that represents objects using the JSON data interchange format as defined in RFC 4627 [16]). Each <body/> wrapper MAY contain payloads qualified under a wide variety of different namespaces.
The <body/> element of every client request MUST possess a sequential request ID encapsulated via the 'rid' attribute; for details, refer to the Request IDs section of this document.
Initiating a BOSH Session
Session Creation Request
The first request from the client to the connection manager requests a new session.
The <body/> element of the first request SHOULD possess the following attributes (they SHOULD NOT be included in any other requests except as specified under Adding Streams To A Session):
- 'to' -- This attribute specifies the target domain of the first stream.
- 'xml:lang' -- This attribute (as defined in Section 2.12 of XML 1.0 [17]) specifies the default language of any human-readable XML character data sent or received during the session.
- 'ver' -- This attribute specifies the highest version of the BOSH protocol that the client supports. The numbering scheme is "<major>.<minor>" (where the minor number MAY be incremented higher than a single digit, so it MUST be treated as a separate integer). Note: The 'ver' attribute should not be confused with the version of any protocol being transported.
- 'wait' -- This attribute specifies the longest time (in seconds) that the connection manager is allowed to wait before responding to any request during the session. This enables the client to limit the delay before it discovers any network failure, and to prevent its HTTP/TCP connection from expiring due to inactivity.
- 'hold' -- This attribute specifies the maximum number of requests the connection manager is allowed to keep waiting at any one time during the session. If the client is not able to use HTTP Pipelining then this SHOULD be set to "1".
Note: Clients that only support Polling Sessions MAY prevent the connection manager from waiting by setting 'wait' or 'hold' to "0". However, polling is NOT RECOMMENDED since the associated increase in bandwidth consumption and the decrease in responsiveness are both typically one or two orders of magnitude!
A connection manager MAY be configured to enable sessions with more than one server in different domains. When requesting a session with such a "proxy" connection manager, a client SHOULD include a 'route' attribute that specifies the protocol, hostname, and port of the server with which it wants to communicate, formatted as "proto:host:port" (e.g., "xmpp:example.com:9999"). [18] A connection manager that is configured to work only with a single server (or only with a defined list of domains and the associated list of hostnames and ports that are serving those domains) MAY ignore the 'route' attribute. (Note that the 'to' attribute specifies the domain being served, not the hostname of the machine that is serving the domain.)
The <body/> element of the first request MAY also possess a 'from' attribute, which specifies the originator of the first stream and which enables the connection manager to forward the originating entity's identity to the application server (e.g., the JabberID of an entity that is connecting to an XMPP server; see XEP-0206).
A client MAY include an 'ack' attribute (set to "1") to indicate that it will be using acknowledgements throughout the session and that the absence of an 'ack' attribute in any request is meaningful (see Acknowledgements).
Some clients are constrained to only accept HTTP responses with specific Content-Types (e.g., "text/html"). The <body/> element of the first request MAY possess a 'content' attribute. This specifies the value of the HTTP Content-Type header that MUST appear in all the connection manager's responses during the session. If the client request does not possess a 'content' attribute, then the HTTP Content-Type header of responses MUST be "text/xml; charset=utf-8".
Example 1. Requesting a BOSH session
POST /webclient HTTP/1.1 Host: httpcm.example.com Accept-Encoding: gzip, deflate Content-Type: text/xml; charset=utf-8 Content-Length: 104 <body content='text/xml; charset=utf-8' from='user@example.com' hold='1' rid='1573741820' to='example.com' route='xmpp:example.com:9999' ver='1.6' wait='60' ack='1' xml:lang='en' xmlns='http://jabber.org/protocol/httpbind'/>
Note: All requests after the first one MUST include a valid 'sid' attribute (provided by the connection manager in the Session Creation Response). The initialization request is unique in that the <body/> element MUST NOT possess a 'sid' attribute.
Session Creation Response
After receiving a new session request, the connection manager MUST generate an opaque, unpredictable session identifier (or SID). The SID MUST be unique within the context of the connection manager application. The <body/> element of the connection manager's response to the client's session creation request MUST possess the following attributes (they SHOULD NOT be included in any other responses):
- 'sid' -- This attribute specifies the SID
- 'wait' -- This is the longest time (in seconds) that the connection manager will wait before responding to any request during the session. The time MUST be less than or equal to the value specified in the session request.
The <body/> element SHOULD also include the following attributes (they SHOULD NOT be included in any other responses):
- 'ver' -- This attribute specifies the highest version of the BOSH protocol that the connection manager supports, or the version specified by the client in its request, whichever is lower.
- 'polling' -- This attribute specifies the shortest allowable polling interval (in seconds). This enables the client to not send empty request elements more often than desired (see Polling Sessions and Overactivity).
- 'inactivity' -- This attribute specifies the longest allowable inactivity period (in seconds). This enables the client to ensure that the periods with no requests pending are never too long (see Polling Sessions and Inactivity).
- 'requests' -- This attribute enables the connection manager to limit the number of simultaneous requests the client makes (see Overactivity and Polling Sessions). The RECOMMENDED values are either "2" or one more than the value of the 'hold' attribute specified in the session request.
- 'hold' -- This attribute informs the client about the maximum number of requests the connection manager will keep waiting at any one time during the session. This value MUST NOT be greater than the value specified by the client in the session request.
- 'to' -- This attribute communicates the identity of the backend server to which the client is attempting to connect.
The connection manager MAY include an 'accept' attribute in the session creation response element, to specify a space-separated list of the content encodings it can decompress. After receiving a session creation response with an 'accept' attribute, clients MAY include an HTTP Content-Encoding header in subsequent requests (indicating one of the encodings specified in the 'accept' attribute) and compress the bodies of the requests accordingly.
A connection manager MAY include an 'ack' attribute (set to the value of the 'rid' attribute of the session creation request) to indicate that it will be using acknowledgements throughout the session and that the absence of an 'ack' attribute in any response is meaningful (see Acknowledgements).
If the connection manager supports session pausing (see Inactivity) then it SHOULD advertise that to the client by including a 'maxpause' attribute in the session creation response element. The value of the attribute indicates the maximum length of a temporary session pause (in seconds) that a client can request.
For both requests and responses, the <body/> element and its content SHOULD be UTF-8 encoded. If the HTTP Content-Type header of a request/response specifies a character encoding other than UTF-8, then the connection manager MAY convert between UTF-8 and the other character encoding. However, even in this case, it is OPTIONAL for the connection manager to convert between encodings. The connection manager MAY inform the client which encodings it can convert by setting the optional 'charsets' attribute in the session creation response element to a space-separated list of encodings. [19]
As soon as the connection manager has established a connection to the server and discovered its identity, it MAY forward the identity to the client by including a 'from' attribute in a response, either in its session creation response, or (if it has not received the identity from the server by that time) in any subsequent response to the client. If it established a secure connection to the server (as defined in Initiating a BOSH Session), then in the same response the connection manager SHOULD also include the 'secure' attribute set to "true" or "1".
Example 2. Session creation response
HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 128 <body wait='60' inactivity='30' polling='5' requests='2' hold='1' ack='1573741820' accept='deflate,gzip' maxpause='120' sid='SomeSID' charsets='ISO_8859-1 ISO-2022-JP' ver='1.6' from='example.com' xmlns='http://jabber.org/protocol/httpbind'/>
Example 3. Subsequent response with 'from' and 'secure' attributes
HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 128 <body from='example.com' xmlns='http://jabber.org/protocol/httpbind'/>
Sending and Receiving XML Payloads
After the client has successfully completed all required preconditions, it can send and receive XML payloads via the HTTP binding.
Example 4. Transmitting payloads
POST /webclient HTTP/1.1 Host: httpcm.example.com 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>Good morning!</body> </message> <message to='friend@example.com' xmlns='jabber:client'> <body>Hey, what's up?</body> </message> </body>
Upon receipt of a request, the connection manager SHOULD forward the content of the <body/> element to the server as soon as possible. In any case it MUST forward the content from different requests in the order specified by their 'rid' attributes.
The connection manager MUST also return an HTTP 200 OK response with a <body/> element to the client. Note: This does not indicate that the payloads have been successfully delivered to the application server.
It is RECOMMENDED that the connection manager not return an HTTP result until a payload has arrived from the application server for delivery to the client. However, the connection manager SHOULD NOT wait longer than the time specified by the client in the 'wait' attribute of its Session Creation Request, and it SHOULD NOT keep more HTTP requests waiting at a time than the number specified in the 'hold' attribute of the session creation request. In any case it MUST respond to requests in the order specified by their 'rid' attributes.
If there are no payloads waiting or ready to be delivered within the waiting period, then the connection manager SHOULD include an empty <body/> element in the HTTP result:
Example 5. Empty response
HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 64 <body xmlns='http://jabber.org/protocol/httpbind'/>
If the connection manager has received one or more payloads from the application server for delivery to the client, then it SHOULD return the payloads in the body of its response as soon as possible after receiving them from the server. The example below includes payloads qualified by different namespaces:
Example 6. Response with queued stanza
HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 185 <body xmlns='http://jabber.org/protocol/httpbind' xmlns:json='http://json.org/'> <message from='contact@example.com' to='user@example.com' xmlns='jabber:client'> <body>Good morning to you!</body> </message> <message from='friend@example.com' to='user@example.com' xmlns='jabber:client'> <body>Not much, how about with you?</body> </message> <json:json> [ { "precision": "zip", "Latitude": 37.7668, "Longitude": -122.3959, "Address": "", "City": "SAN FRANCISCO", "State": "CA", "Zip": "94107", "Country": "US" }, { "precision": "zip", "Latitude": 37.371991, "Longitude": -122.026020, "Address": "", "City": "SUNNYVALE", "State": "CA", "Zip": "94085", "Country": "US" } ] </json:json> </body>
The client MAY poll the connection manager for incoming payloads by sending an empty <body/> element.
Example 7. Requesting XML Payloads
POST /webclient HTTP/1.1 Host: httpcm.example.com 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'/>
The connection manager MUST wait and respond in the same way as it does after receiving payloads from the client.
Acknowledgements
Request Acknowledgements
When responding to a request that it has been holding, if the connection manager finds it has already received another request with a higher 'rid' attribute (typically while it was holding the first request), then it MAY acknowledge the reception to the client. The connection manager MAY set the 'ack' attribute of any response to the value of the highest 'rid' attribute it has received in the case where it has also received all requests with lower 'rid' values.
Example 8. Response with request acknowledgement
HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 64 <body ack='1249243564' xmlns='http://jabber.org/protocol/httpbind'/>
If the connection manager will be including 'ack' attributes on responses during a session, then it MUST include an 'ack' attribute in its session creation response, and set the 'ack' attribute of responses throughout the session. The only exception is that, after its session creation response, the connection manager SHOULD NOT include an 'ack' attribute in any response if the value would be the 'rid' of the request being responded to.
If the connection manager is permitted to hold more than one request at a time, then the reception of a lower-than-expected 'ack' value from the connection manager (or the unexpected abscence of an 'ack' attribute) can give the client an early warning that a network failure might have occurred (e.g., if the client believes the connection manager should have received another request by the time it responded).
Response Acknowledgements
The client MAY similarly inform the connection manager about the responses it has received by setting the 'ack' attribute of any request to the value of the highest 'rid' of a request for which it has already received a response in the case where it has also received all responses associated with lower 'rid' values. If the client will be including 'ack' attributes on requests during a session, then it MUST include an 'ack' attribute (set to '1') in its session creation request, and set the 'ack' attribute of requests throughout the session. The only exception is that, after its session creation request, the client SHOULD NOT include an 'ack' attribute in any request if it has received responses to all its previous requests.
Example 9. Request with response acknowledgement
POST /webclient HTTP/1.1 Host: httpcm.example.com Accept-Encoding: gzip, deflate Content-Type: text/xml; charset=utf-8 Content-Length: 88 <body rid='1249243566' sid='SomeSID' ack='1249243564' xmlns='http://jabber.org/protocol/httpbind'/>
After receiving a request with an 'ack' value less than the 'rid' of the last request that it has already responded to, the connection manager MAY inform the client of the situation by sending its next response immediately instead of waiting until it has payloads to send to the client (e.g., if some time has passed since it responded). In this case it SHOULD include a 'report' attribute set to one greater than the 'ack' attribute it received from the client, and a 'time' attribute set to the number of milliseconds since it sent the response associated with the 'report' attribute.
Example 10. Response with report
HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 64 <body report='1249243565' time='852' xmlns='http://jabber.org/protocol/httpbind'/>
Upon reception of a response with 'report' and 'time' attributes, if the client has still not received the response associated with the request identifier specified by the 'report' attribute, then it MAY choose to resend the request associated with the missing response (see Broken Connections).
Inactivity
After receiving a response from the connection manager, if none of the client's requests are still being held by the connection manager (and if the session is not a Polling Session), the client SHOULD make a new request as soon as possible. In any case, if no requests are being held, the client MUST make a new request before the maximum inactivity period has expired. The length of this period (in seconds) is specified by the 'inactivity' attribute in the session creation response.
If the connection manager has responded to all the requests it has received within a session and the time since its last response is longer than the maximum inactivity period, then it SHOULD assume the client has been disconnected and terminate the session without informing the client. If the client subsequently makes another request, then the connection manager SHOULD respond as if the session does not exist.
If the connection manager did not specify a maximum inactivity period in the session creation response, then it SHOULD allow the client to be inactive for as long as it chooses.
If the session is not a polling session then the connection manager SHOULD specify a relatively short inactivity period to ensure that disconnections are discovered as quickly as possible. The RECOMMENDED time would be a little more than the number of seconds for a comfortable network round trip between the connection manager and the client under difficult network conditions (since the client can be expected to make a new request immediately -- see above).
If a client encounters an exceptional temporary situation during which it will be unable to send requests to the connection manager for a period of time greater than the maximum inactivity period (e.g., while a runtime environment changes from one web page to another), and if the connection manager included a 'maxpause' attribute in its Session Creation Response, then the client MAY request a temporary increase to the maximum inactivity period by including a 'pause' attribute in a request. Note: If the connection manager did not specify a 'maxpause' attribute at the start of the session then the client MUST NOT send a 'pause' attribute during the session.
Example 11. Requesting a Session Pause
POST /webclient HTTP/1.1 Host: httpcm.example.com Accept-Encoding: gzip, deflate Content-Type: text/xml; charset=utf-8 Content-Length: 98 <body rid='1249243564' sid='SomeSID' pause='60' xmlns='http://jabber.org/protocol/httpbind'/>
Upon reception of a session pause request, if the requested period is not greater than the maximum permitted time, then the connection manager SHOULD respond immediately to all pending requests (including the pause request) and temporarily increase the maximum inactivity period to the requested time. Note: The response to the pause request MUST NOT contain any payloads.
Note: If the client simply wants the connection manager to return all the requests it is holding then it MAY set the value of the 'pause' attribute to be the value of the 'inactivity' attribute in the connection manager's session creation response. (If the client believes it is in danger of becoming disconnected indefinitely then it MAY even request a temporary reduction of the maximum inactivity period by specifying a 'pause' value less than the 'inactivity' value, thus enabling the connection manager to discover any subsequent disconnection more quickly.)
The connection manager SHOULD set the maximum inactivity period back to normal upon reception of the next request from the client (assuming the connection manager has not already terminated the session).
Overactivity
The client SHOULD NOT make more simultaneous requests than specified by the 'requests' attribute in the connection manager's Session Creation Response. However the client MAY make one additional request if it is to pause or terminate a session.
If during any period the client sends a sequence of new requests (i.e. requests with incremented rid attributes, not repeat requests) longer than the number specified by the 'requests' attribute, and if the connection manager has not yet responded to any of the requests, and if the last request did not include either a 'pause' attribute or a 'type' attribute set to "terminate", then the connection manager SHOULD consider that the client is making too many simultaneous requests, and terminate the HTTP session with a 'policy-violation' terminal binding error to the client. Note: This behavior applies to equally to normal and polling sessions.
Example 12. Too many simultaneous requests response
HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 68 <body type='terminate' condition='policy-violation' xmlns='http://jabber.org/protocol/httpbind'/>
Note: If the connection manager did not specify a 'requests' attribute in the session creation response, then it MUST allow the client to send as many simultaneous requests as it chooses.
If during any period the client sends a sequence of new requests equal in length to the number specified by the 'requests' attribute, and if the connection manager has not yet responded to any of the requests, and if the last request was empty and did not include either a 'pause' attribute or a 'type' attribute set to "terminate", and if the last two requests arrived within a period shorter than the number of seconds specified by the 'polling' attribute in the session creation response, then the connection manager SHOULD consider that the client is making requests more frequently than it was permitted and terminate the HTTP session and return a 'policy-violation' terminal binding error to the client. Note: the behavior for Polling Sessions is slightly different.
Example 13. Too frequent requests response
HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 68 <body type='terminate' condition='policy-violation' xmlns='http://jabber.org/protocol/httpbind'/>
Note: If the connection manager did not specify a 'polling' attribute in the session creation response, then it MUST allow the client to send requests as frequently as it chooses.
Polling Sessions
It is not always possible for a constrained client to either use HTTP Pipelining or open more than one HTTP connection with the connection manager at a time. In this case the client SHOULD inform the connection manager by setting the values of the 'wait' and/or 'hold' attributes in its session creation request to "0", and then "poll" the connection manager at regular intervals throughout the session for payloads it might have received from the server. Note: Even if the client does not request a polling session, the connection manager MAY require a client to use polling by setting the 'requests' attribute (which specifies the number of simultaneous requests the client can make) of its Session Creation Response to "1", however this is NOT RECOMMENDED.
If a session will use polling, the connection manager SHOULD specify a higher than normal value for the 'inactivity' attribute (see Inactivity) in its session creation response. The increase SHOULD be greater than the value it specifies for the 'polling' attribute.
If the client sends two consecutive empty new requests (i.e. requests with incremented rid attributes, not repeat requests) within a period shorter than the number of seconds specified by the 'polling' attribute (the shortest allowable polling interval) in the session creation response, and if the connection manager's response to the first request contained no payloads, then upon reception of the second request the connection manager SHOULD terminate the HTTP session and return a 'policy-violation' terminal binding error to the client.
Example 14. Too frequent polling response
HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 68 <body type='terminate' condition='policy-violation' xmlns='http://jabber.org/protocol/httpbind'/>
Note: If the connection manager did not specify a 'polling' attribute in the session creation response, then it MUST allow the client to poll as frequently as it chooses.
Terminating the HTTP Session
At any time, the client MAY gracefully terminate the session by sending a <body/> element with a 'type' attribute set to "terminate". The termination request MAY include one or more payloads that the connection manager MUST forward to the server to ensure graceful logoff.
Example 15. Session termination by client
POST /webclient HTTP/1.1 Host: httpcm.example.com Accept-Encoding: gzip, deflate Content-Type: text/xml; charset=utf-8 Content-Length: 153 <body rid='1249243565' sid='SomeSID' type='terminate' xmlns='http://jabber.org/protocol/httpbind'> <presence type='unavailable' xmlns='jabber:client'/> </body>
The connection manager SHOULD respond to this request with an HTTP 200 OK containing an empty <body/> element.
Example 16. Connection manager acknowledges termination
HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 72 <body type='terminate' xmlns='http://jabber.org/protocol/httpbind'/>
Upon receiving the response, the client MUST consider the HTTP session to have been terminated.
Request IDs
Generation
The client MUST generate a large, random, positive integer for the initial 'rid' (see Security Considerations) and then increment that value by one for each subsequent request. The client MUST take care to choose an initial 'rid' that will never be incremented above 9007199254740991 [21] within the session. In practice, a session would have to be extraordinarily long (or involve the exchange of an extraordinary number of packets) to exceed the defined limit.
In-Order Message Forwarding
When a client makes simultaneous requests, the connection manager might receive them out of order. The connection manager MUST forward the payloads to the server and respond to the client requests in the order specified by the 'rid' attributes. The client MUST process responses received from the connection manager in the order the requests were made.
The connection manager SHOULD expect the 'rid' attribute to be within a window of values greater than the 'rid' of the previous request. The size of the window is equal to the maximum number of simultaneous requests allowed by the connection manager. If it receives a request with a 'rid' greater than the values in the window, then the connection manager MUST terminate the session with an error:
Example 17. Unexpected rid error
HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 68 <body type='terminate' condition='item-not-found' xmlns='http://jabber.org/protocol/httpbind'/>
Broken Connections
Unreliable network communications or client constraints can result in broken connections. The connection manager SHOULD remember the 'rid' and the associated HTTP response body of the client's most recent requests which were not session pause requests (see Inactivity) and which did not result in an HTTP or binding error. The number of responses to non-pause requests kept in the buffer SHOULD be either the same as the maximum number of simultaneous requests allowed by the connection manager or, if Acknowledgements are being used, the number of responses that have not yet been acknowledged.
If the network connection is broken or closed before the client receives a response to a request from the connection manager, then the client MAY resend an exact copy of the original request. Whenever the connection manager receives a request with a 'rid' that it has already received, it SHOULD return an HTTP 200 (OK) response that includes the buffered copy of the original XML response to the client (i.e., a <body/> wrapper possessing appropriate attributes and optionally containing one or more XML payloads). If the original response is not available (e.g., it is no longer in the buffer), then the connection manager MUST return an 'item-not-found' terminal binding error:
Example 18. Response not in buffer error
HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 68 <body type='terminate' condition='item-not-found' xmlns='http://jabber.org/protocol/httpbind'/>
Note: The error is the same whether the 'rid' is too large or too small. This makes it more difficult for an attacker to discover an acceptable value.
Protecting Insecure Sessions
Applicability
The OPTIONAL key sequencing mechanism described here MAY be used if the client's session with the connection manager is not secure. The session SHOULD be considered secure only if all client requests are made via SSL (or TLS) HTTP connections and the connection manager generates an unpredictable session ID. If the session is secure, it is not necessary to use this key sequencing mechanism.
Even if the session is not secure, the unpredictable session and request IDs specified in the preceding sections of this document already provide a level of protection similar to that provided by a connection bound to a single pair of persistent TCP/IP connections, and thus provide sufficient protection against a 'blind' attacker. However, in some circumstances, the key sequencing mechanism defined below helps to protect against a more determined and knowledgeable attacker.
It is important to recognize that the key sequencing mechanism defined below helps to protect only against an attacker who is able to view the contents of all requests or responses in an insecure session but who is not able to alter the contents of those requests (in this case, the mechanism prevents the attacker from injecting HTTP requests into the session, e.g., termination requests or responses). However, the key sequencing mechanism does not provide any protection when the attacker is able to alter the contents of insecure requests or responses.
Introduction
The HTTP requests of each session MAY be spread across a series of different socket connections. This would enable an unauthorized user that obtains the session ID and request ID of a session to then use their own socket connection to inject <body/> request elements into the session and receive the corresponding responses.
The key sequencing mechanism below protects against such attacks by enabling a connection manager to detect <body/> request elements injected by a third party.
Generating the Key Sequence
Prior to requesting a new session, the client MUST select an unpredictable counter ("n") and an unpredictable value ("seed"). The client then processes the "seed" through a cryptographic hash and converts the resulting 160 bits to a hexadecimal string K(1). It does this "n" times to arrive at the initial key K(n). The hashing algorithm MUST be SHA-1 as defined in RFC 3174 [22].
Example 19. Creating the key sequence
K(1) = hex(SHA-1(seed))
K(2) = hex(SHA-1(K(1)))
...
K(n) = hex(SHA-1(K(n-1)))
Use of Keys
The client MUST set the 'newkey' attribute of the first request in the session to the value K(n).
Example 20. Session Request with Initial Key
POST /webclient HTTP/1.1 Host: httpcm.example.com 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='example.com' wait='60' xml:lang='en' newkey='ca393b51b682f61f98e7877d61146407f3d0a770' xmlns='http://jabber.org/protocol/httpbind'/>
The client MUST set the 'key' attribute of all subsequent requests to the value of the next key in the generated sequence (decrementing from K(n-1) towards K(1) with each request sent).
Example 21. Request with Key
POST /webclient HTTP/1.1 Host: httpcm.example.com 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'/>
The connection manager MAY verify the key by calculating the SHA-1 hash of the key and comparing it to the 'newkey' attribute of the previous request (or the 'key' attribute if the 'newkey' attribute was not set). If the values do not match (or if it receives a request without a 'key' attribute and the 'newkey' or 'key' attribute of the previous request was set), then the connection manager MUST NOT process the element, MUST terminate the session, and MUST return an 'item-not-found' terminal binding error.
Example 22. Invalid Key Sequence Error
HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 68 <body type='terminate' condition='item-not-found' xmlns='http://jabber.org/protocol/httpbind'/>
Switching to Another Key Sequence
A client SHOULD choose a high value for "n" when generating the key sequence. However, if the session lasts long enough that the client arrives at the last key in the sequence K(1) then the client MUST switch to a new key sequence.
The client MUST:
1. Choose new values for "seed" and "n". 2. Generate a new key sequence using the algorithm defined above. 3. Set the 'key' attribute of the request to the next value in the old sequence (i.e. K(1), the last value). 4. Set the 'newkey' attribute of the request to the value K(n) from the new sequence.
Example 23. New Key Sequence
POST /webclient HTTP/1.1 Host: httpcm.example.com 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>I said "Hi!"</body> </message> </body>
Multiple Streams
Introduction
The OPTIONAL feature described in this section enables multiple XML streams to be contained within a single HTTP session. This feature is essential in runtime environments that prevent HTTP Pipelining, thereby constraining the number of simultaneous HTTP requests a client can make to each connection manager, since clients running in such environments need multi-stream sessions if they are to connect using more than one account at the same time. This feature also reduces network traffic for any client that needs to establish parallel streams over HTTP.
Discovery
If a connection manager supports the multi-streams feature, it MUST include a 'stream' attribute in its Session Creation Response. If a client does not receive the 'stream' attribute then it MUST assume that the connection manager does not support the feature. [23]
The 'stream' attribute identifies the first stream to be opened for the session. The value of each 'stream' attribute MUST be an opaque and unpredictable name that is unique within the context of the connection manager application.
Example 24. Session creation response with stream name
HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 128 <body wait='60' inactivity='30' polling='5' requests='2' hold='1' accept='deflate,gzip' stream='firstStreamName' maxpause='120' sid='SomeSID' charsets='ISO_8859-1 ISO-2022-JP' ver='1.6' from='example.com' xmlns='http://jabber.org/protocol/httpbind'/>
Adding Streams To A Session
If the connection manager included a 'stream' attribute in its session creation response then the client MAY ask it to open another stream at any time by sending it an empty <body/> element with a 'to' attribute. The request MUST include valid 'sid' and 'rid' [24] attributes, and SHOULD also include an 'xml:lang' attribute. The request MAY include 'route', 'from' and 'secure' attributes (see Session Creation Request), but it SHOULD NOT include 'ver', 'content', 'hold' or 'wait' attributes (since a new session is not being created).
Example 25. Requesting another stream
POST /webclient HTTP/1.1 Host: httpcm.example.com Accept-Encoding: gzip, deflate Content-Type: text/xml; charset=utf-8 Content-Length: 104 <body sid='SomeSID' rid='1573741820' to='example.com' route='xmpp:example.com:9999' xml:lang='en' xmlns='http://jabber.org/protocol/httpbind'/>
If the connection manager did not indicate its support for multiple streams at the start of the session, then it MUST ignore the extra attributes and treat the request as a normal empty request for payloads (see Sending and Receiving XML Payloads). [25] Otherwise it MUST open a new stream with the specified server (see Session Creation Response), generate a new stream name, and respond to the client with the name. The response MAY also include 'from' and 'secure' attributes, but it SHOULD NOT include 'sid', 'requests', 'polling', 'hold', 'inactivity', 'maxpause', 'accept', 'charsets', 'ver' or 'wait' attributes.
Example 26. Add stream response
HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: 128 <body stream='secondStreamName' from='example.com' xmlns='http://jabber.org/protocol/httpbind'/>
Note: If the response did not include either 'from' or 'secure' attributes then they MAY be sent in a subsequent response instead (see Session Creation Response). In that case the 'stream' attribute MUST also be specified.
Transmitting Payloads
If more than one stream has been opened within a session, then all non-empty <body/> elements sent by the connection manager MUST include a 'stream' attribute that specifies which stream all the payloads it contains belong to. The client SHOULD include a 'stream' attribute for the same purpose. The client MAY omit the 'stream' attribute if it wants the connection manager to broadcast the payloads over all open streams. Note: A <body/> element MUST NOT contain different payloads for different streams.
If a stream name does not correspond to one of the session's open streams, then the receiving connection manager SHOULD return an 'item-not-found' terminal binding error, or the receiving client SHOULD terminate the session. However, if the receiving entity has only just closed the stream (and the sender might not have been aware of that when it sent the payloads), then it MAY instead simply silently ignore any payloads the <body/> element contains.
Note: Empty <body/> elements that do not include a 'from' or 'secure' attribute SHOULD NOT include a 'stream' attribute (since nothing is being transmitted for any stream). If such a <body/> element does include a 'stream' attribute then the receiving entity SHOULD ignore the attribute.
Example 27. Client sends payload with a stream name
POST /webclient HTTP/1.1 Host: httpcm.example.com 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>I said hello.</body> </message> </body>
Note: The value of the 'stream' attribute of the response MAY be different than the corresponding request. [26]
Example 28. Connection manager responds with a different stream name
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>
If no stream name is specified by the connection manager then the client MUST assume the payloads are associated with the first stream (even if the first stream has been closed).
If no stream name is specified by the client then the connection manager MUST broadcast the payloads over all open streams. [27]
Example 29. Client asks for a payload to be broadcast
POST /webclient HTTP/1.1 Host: httpcm.example.com 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>
Closing a Stream
If more than one stream is open within a session, the client MAY close one open stream at any time using the procedure described in the section Terminating the HTTP Session above, taking care to specify the stream name with a 'stream' attribute. If the client closes the last stream the connection manager MUST terminate the session. If the client does not specify a stream name then the connection manager MUST close all open streams (sending any payloads the terminate request contains to all streams), and terminate the session.
Example 30. Client closes one stream
POST /webclient HTTP/1.1 Host: httpcm.example.com 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>
Error Conditions
If more than one stream is open within a session, the connection manager MAY include a 'stream' attribute in a fatal binding error (see Terminal Binding Conditions). If a 'stream' attribute is specified then the stream MUST be closed by both entities but the session SHOULD NOT be terminated.
Example 31. Fatal stream error
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'/>
Note: If the connection manager does not include a 'stream' attribute in a fatal binding error then all the session's open streams MUST be closed by both entities and the session MUST be terminated.
Error and Status Codes
There are four types of error and status reporting in HTTP responses:
Table 1: Error Condition Types
| Condition Type | Description |
|---|---|
| HTTP Conditions (Deprecated) | The connection manager responds to an invalid request from a legacy client 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 can be read by constrained clients. They are used for connection manager problems, abstracting stream errors, communication problems between the connection manager and the server, and invalid client requests (binding syntax errors, possible attacks, etc.) |
| 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/> wrappers that have not received responses. |
| Transported Protocol Conditions | Errors relating to the XML payloads within <body/> wrappers are, in general, defined in the documentation of the protocol being transported. They do not terminate the session. |
Full descriptions are provided below.
HTTP Conditions
Note: All HTTP codes except 200 have been superseded by Terminal Binding Conditions to allow clients to determine whether the source of errors is the connection manager application or an HTTP intermediary.
A legacy client (or connection manager) is a client (or connection manager) that did not include a 'ver' attribute in its session creation request (or response). A legacy client (or connection manager) will interpret (or respond with) HTTP error codes according to the table below. Non-legacy connection managers SHOULD NOT send HTTP error codes unless they are communicating with a legacy client. Upon receiving an HTTP error (400, 403, 404), a legacy client or any client that is communicating with a legacy connection manager MUST consider the HTTP session to be null and void. A non-legacy client that is communicating with a non-legacy connection manager MAY consider that the session is still active.
Table 2: HTTP Error and Status Codes
| Code | Name | Superseded by | Purpose |
|---|---|---|---|
| 200 | OK | - | Response to valid client request. |
| 400 | Bad Request | bad-request | Inform client that the format of an HTTP header or binding element is unacceptable (e.g., syntax error). |
| 403 | Forbidden | policy-violation | Inform client that it has broken the session rules (polling too frequently, requesting too frequently, too many simultaneous requests). |
| 404 | Not Found | item-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. |
Note: No other HTTP error and status codes were defined in the early versions of BOSH (e.g., Internal Server Error).
Terminal Binding Conditions
In any response it sends to the client, the connection manager MAY return a fatal error by setting a 'type' attribute of the <body/> element to "terminate". These binding errors imply that the HTTP session is terminated (unless a 'stream' attribute is specified -- see Multiple Stream Error Conditions).
Note: Although many of these conditions are similar to the XMPP stream error conditions specified in RFC 6120, they are not to be confused with XMPP stream errors. In cases where BOSH is being used to transport XMPP, any fatal XMPP stream error conditions experienced between the connection manager and the XMPP server SHOULD only be reported using the "remote-stream-error" condition as described below.
Example 32. Remote connection failed error
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'/>
The following values of the 'condition' attribute are defined:
Table 3: Terminal Binding Error Conditions
| Condition | Purpose |
|---|---|
| bad-request* | The format of an HTTP header or binding element received from the client is unacceptable (e.g., syntax error). |
| 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. |
| item-not-found* | (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. |
| other-request | Another request being processed at the same time as this request caused the session to terminate. |
| policy-violation* | The client has broken the session rules (polling too frequently, requesting too frequently, sending too many simultaneous requests). |
| remote-connection-failed | The connection manager was unable to connect to, or unable to connect securely to, or has lost its connection to, the server. |
| remote-stream-error | Encapsulates an error in the protocol being transported. |
| 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 can 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. |
- If the client did not include a 'ver' attribute in its session creation request then the connection manager SHOULD send a deprecated HTTP Error Condition instead of this terminal binding condition. If the connection manager did not include a 'ver' attribute in its session creation response then the client SHOULD expect it to send a deprecated HTTP Error Condition instead of this terminal binding condition.
The following is an example of a "see-other-uri" condition:
Example 33. See other URI error
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>
The following is an example including a "remote-stream-error" condition:
Example 34. Remote error
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' xmlns:stream='http://etherx.jabber.org/streams'> <message from='contact@example.com' to='user@example.com' xmlns='jabber:client'> <body>I said "Hi!"</body> </message> <stream:error> <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'/> </stream:error> </body>
Naturally, the client MAY report binding errors to the connection manager as well, although this is unlikely.
Recoverable Binding Conditions
In any response it sends to the client, the connection manager MAY return a recoverable error by setting a 'type' attribute of the <body/> element to "error". These errors do not imply that the HTTP session is terminated.
If it decides to recover from the error, then the client MUST repeat the HTTP request that resulted in the error, as well as all the preceding HTTP requests that have not received responses. The content of these requests MUST be identical to the <body/> elements of the original requests. This enables the connection manager to recover a session after the previous request was lost due to a communication failure.
Example 35. Recoverable error
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 Payload Conditions
Application-level error conditions described in the documentation of the protocol being transported are routed to the client through the connection manager. They are transparent to the connection manager, and therefore out of scope for the transport binding defined herein.
Implementation Notes
HTTP Pipelining
Even if the client requests HTTP Pipelining and the connection manager supports it, there is no guarantee that pipelining will succeed, because it might not be supported by intermediate proxies.
The best the client can do is to request the use of HTTP Pipelining by setting the 'hold' attribute to a value of "1". If HTTP Pipelining does not work (because the server returns HTTP 1.0 or connection:close), then the client SHOULD degrade gracefully by using multiple connections.
Security Considerations
Connection Between Client and BOSH Service
All communications between a client and a BOSH service SHOULD occur over encrypted HTTP connections. Negotiation of encryption between the client and the connection manager SHOULD occur at the transport layer or the HTTP layer, not the application layer; such negotiation SHOULD follow the HTTP/SSL protocol defined in SSL [28], although MAY follow the HTTP/TLS protocol defined in RFC 2818 [29] or the TLS Within HTTP protocol defined in RFC 2817 [30].
If the HTTP connection used to send the initial session request is encrypted, then all the other HTTP connections used within the session MUST also be encrypted. Furthermore, if authentication certificates are exchanged when establishing the encrypted connection that is used to send the initial session request, then the client and/or connection manager SHOULD ensure that the same authentication certificates are employed for all subsequent connections used by the session. Once such a "secure session" has been established:
- If the connection manager refuses to establish an encrypted connection or offers a different certificate, then the client SHOULD close the connection and terminate the session without sending any more requests.
- If the client sends a wrapper element that is part of a "secure session" over a connection that either is not encrypted or uses a different certificate, then the connection manager SHOULD simply close the connection. The connection manager SHOULD NOT terminate the session since that would facilitate denial of service attacks.
Connection Between BOSH Service and Application
A BOSH service SHOULD encrypt its connection to the backend application using appropriate technologies such as Secure Sockets Layer (SSL), Transport Layer Security (TLS), and StartTLS if supported by the backend application. Alternatively, the BOSH service can be considered secure (1) if it is running on the same physical machine as the backend application or (2) if it running on the same private network as the backend application and the administrators are sure that unknown individuals or processes do not have access to that private network.
If data privacy is desired, the client SHOULD encrypt its messages using an application-specific end-to-end encryption technology, because there is no way for the client to be sure that the BOSH service encrypts its connection to the application; methods for doing so are outside the scope of this specification.
Unpredictable SID and RID
The session identifier (SID) and initial request identifier (RID) are security-critical and therefore MUST be both unpredictable and nonrepeating (see RFC 1750 [31] for recommendations regarding randomness of SIDs and initial RIDs for security purposes).
Use of SHA-1
Recent research has shown that in select cases it is possible to compromise the hashes produced by the SHA-1 hashing algorithm (see RFC 4270 [32]). However, the use to which SHA-1 is put in BOSH will likely minimize the applicability of the attacks described in the literature. Furthermore, current estimates suggest that even with the recently-discovered attack, it would still take one year of computing by a government-sized entity to produce a collision.
IANA Considerations
TCP port 5280, conventially used for communication between BOSH clients and BOSH connection mangers, is registered with the Internet Assigned Numbers Authority (IANA) [33] in its port registry at IANA Port Numbers Registry [34], with a keyword of "xmpp-bosh". (Although use of this port is OPTIONAL, it is helpful to define this port in a standardized way so that BOSH clients can contact any given XMPP service via BOSH without the need either for DNS TXT records as described in Discovering Alternative XMPP Connection Methods [35] or for more advanced methods such as U-NAPTR.
XMPP Registrar Considerations
Protocol Namespaces
The XMPP Registrar includes 'http://jabber.org/protocol/httpbind' in its registry of protocol namespaces.
XML Schema
<?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://www.w3.org/XML/1998/namespace' schemaLocation='http://www.w3.org/2001/03/xml.xsd'/> <xs:element name='body'> <xs:complexType> <xs:choice> <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='ack' type='xs:positiveInteger' 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='bad-request'/> <xs:enumeration value='host-gone'/> <xs:enumeration value='host-unknown'/> <xs:enumeration value='improper-addressing'/> <xs:enumeration value='internal-server-error'/> <xs:enumeration value='item-not-found'/> <xs:enumeration value='other-request'/> <xs:enumeration value='policy-violation'/> <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='from' type='xs:string' use='optional'/> <xs:attribute name='hold' type='xs:unsignedByte' use='optional'/> <xs:attribute name='inactivity' type='xs:unsignedShort' use='optional'/> <xs:attribute name='key' type='xs:string' use='optional'/> <xs:attribute name='maxpause' type='xs:unsignedShort' use='optional'/> <xs:attribute name='newkey' type='xs:string' use='optional'/> <xs:attribute name='pause' type='xs:unsignedShort' use='optional'/> <xs:attribute name='polling' type='xs:unsignedShort' use='optional'/> <xs:attribute name='report' type='xs:positiveInteger' use='optional'/> <xs:attribute name='requests' type='xs:unsignedByte' use='optional'/> <xs:attribute name='rid' type='xs:positiveInteger' use='optional'/> <xs:attribute name='route' type='xs:string' use='optional'/> <xs:attribute name='sid' type='xs:string' use='optional'/> <xs:attribute name='stream' type='xs:string' use='optional'/> <xs:attribute name='time' type='xs:unsignedShort' use='optional'/> <xs:attribute name='to' type='xs:string' use='optional'/> <xs:attribute name='type' 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='ver' type='xs:string' use='optional'/> <xs:attribute name='wait' type='xs:unsignedShort' use='optional'/> <xs:attribute ref='xml:lang' use='optional'/> <xs:anyAttribute namespace='##other' processContents='lax'/> </xs:complexType> </xs:element> </xs:schema>
Acknowledgements
Thanks to Mike Cumings, Tomas Karasek, Tobias Markmann, Chris Seymour, Safa Sofuoğlu, Stefan Strigler, Matthew Wild, Kevin Winters, and Christopher Zorn for their feedback.
Appendices
Appendix A: Document Information
Series: XEP Number: 0124 Publisher: XMPP Standards Foundation Status: Draft Type: Standards Track Version: 1.10 Last Updated: 2010-07-02 Approving Body: XMPP Council Dependencies: RFC 1945, RFC 2616, RFC 3174 Supersedes: None Superseded By: None Short Name: bosh Schema: <http://www.xmpp.org/schemas/httpbind.xsd> Source Control: HTML RSS This document in other formats: XML PDF
Appendix B: Author Information
Ian Paterson
Email: ian.paterson@clientside.co.uk JabberID: ian@zoofy.com Dave Smith
Email: dizzyd@jabber.org JabberID: dizzyd@jabber.org Peter Saint-Andre
Email: stpeter@jabber.org JabberID: stpeter@jabber.org URI: https://stpeter.im/ Jack Moffitt
Email: jack@chesspark.com JabberID: jack@chesspark.com
附录C:法律通告
- 版权
- XMPP扩展协议的版权(1999 - 2011)归XMPP标准化基金会(XSF)所有.
- 权限
- 特此授权,费用全免,对任何获得本协议副本的人,对使用本协议没有限制,包括不限制在软件程序中实现本协议,不限制在网络服务中布署本协议,不限制拷贝,修改,合并,发行,翻译,分发,转授,或销售本协议的副本,被允许使用本协议做了以上工作的人士,应接受前述的版权声明和本许可通知并且必须包含在所有的副本或实质性部分的规格中.除非单独的许可，被重新分发的修改工作，不得含有关于作者，标题，编号，或出版者的规格的误导性资料，并不得宣称修改工作是由本文的作者，作者所属的任何组织或项目，或XMPP标准基金会签注。
- 免责声明
- ##特别注意：本协议是提供的“原样”的基础，没有担保或任何形式的条件，明示或暗示，包括，但不限于任何担保或关于名称，非侵权性，适销性或适合作某一特定目的的条件. ##
- 责任限制
- 在任何情况下以及没有任何法律规定时，不论是侵权行为（包括疏忽），合同或其它方面，除非根据适用法律的要求（如蓄意和有严重疏忽行为）或以书面形式同意，XMPP标准基金会或任何作者不对本协议所造成的损失承担责任，包括任何直接，间接，特殊，偶发，或任何从本协议出，入，连接的字符产生的或实现，布署或其他对本协议的使用导致的相应的损害赔偿（包括但不限于善意的损失，停止作业，电脑失灵或故障，或任何和所有其他商业损害或损失） ，即使XMPP标准基金会或作者已被告知此类损害的可能性。
- 知识产权的一致性
- XMPP扩展协议完全遵守XSF的知识产权策略(可在<http://www.xmpp.org/extensions/ipr-policy.shtml>找到副本或写信给XMPP标准基金会, 1899 Wynkoop Street, Suite 600, Denver, CO 80202 USA).
附录D:和XMPP的关系
可扩展的消息和出席信息协议 (XMPP) 定义于 XMPP Core (RFC 3920) 和 XMPP IM (RFC 3921) 规范里，由 XMPP标准基金会贡献到由依据RFC 2026成立的互联网工程人物组管理的互联网标准流程 Internet Standards Process. 本文定义的任何协议已在互联网标准流程之外开发，并且被理解为 XMPP 的扩展而不是一个XMPP本身的演化, 开发, 或修改.
附录E:讨论地点
主要的XMPP扩展协议讨论地点是 <standards@xmpp.org> 讨论列表.
在 xmpp.org 的其它讨论列表中的讨论可能也有合适的; 所有的列表见 <http://xmpp.org/about/discuss.shtml> .
Given that this XMPP Extension Protocol normatively references IETF technologies, discussion on the <xsf-ietf@xmpp.org> list might also be appropriate.
勘误表可以发送邮件到 <editor@xmpp.org>.
附录F:需求一致性
以下用于本文的需求关键字的解释见于 RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".
Appendix G: Notes
1. RFC 793: Transmission Control Protocol <http://tools.ietf.org/html/rfc0793>.
2. RFC 1945: Hypertext Transfer Protocol -- HTTP/1.0 <http://tools.ietf.org/html/rfc1945>.
3. RFC 2616: Hypertext Transport Protocol -- HTTP/1.1 <http://tools.ietf.org/html/rfc2616>.
4. Bayeux Protocol <http://svn.cometd.org/trunk/bayeux/bayeux.html>.
5. The Web Socket Protocol <http://tools.ietf.org/html/draft-hixie-thewebsocketprotocol>.
6. Reverse HTTP <http://tools.ietf.org/html/draft-lentczner-rhttp>.
7. RFC 2965: HTTP State Management Mechanism <http://tools.ietf.org/html/rfc2965>.
8. Requiring cookies is sub-optimal because several significant computing platforms provide only limited access to underlying HTTP requests/responses; worse, some platforms hide or remove cookie-related headers.
9. XEP-0025: Jabber HTTP Polling <http://xmpp.org/extensions/xep-0025.html>.
10. RFC 6120: Extensible Messaging and Presence Protocol (XMPP): Core <http://tools.ietf.org/html/rfc6120>.
11. XEP-0206: XMPP Over BOSH <http://xmpp.org/extensions/xep-0206.html>.
12. In order to reduce network congestion, RFC 2616 recommends that clients SHOULD NOT keep more than two HTTP connections to the same HTTP server open at the same time. Clients running in constrained enviroments typically have no choice but to abide by that recommendation.
13. If there is no traffic other than the "pings" then bandwidth consumption will be double that of a TCP connection (although double nothing is still nothing). If data is sent in large packets then bandwidth consumption will be almost identical.
14. Extensible Markup Language (XML) 1.0 (Fourth Edition) <http://www.w3.org/TR/REC-xml/>.
15. Namespaces in XML <http://www.w3.org/TR/REC-xml-names/>.
16. RFC 4627: The application/json Media Type for JavaScript Object Notation (JSON) <http://tools.ietf.org/html/rfc4627>.
17. Extensible Markup Language (XML) 1.0 (Fourth Edition) <http://www.w3.org/TR/REC-xml/>.
18. Although the syntax of the 'route' attribute bears a superficial resemblance to a URI or IRI, it is not a URI/IRI and MUST NOT be processed in accordance with the rules specified in RFC 3986, RFC 3987, or (for XMPP) RFC 5122.
19. Each character set name (or character encoding name -- we use the terms interchangeably) SHOULD be of type NMTOKEN, where the names are separated by the white space character #x20, resulting in a tokenized attribute type of NMTOKENS (see Section 3.3.1 of XML 1.0 [20]). Strictly speaking, the Character Sets registry maintained by the Internet Assigned Numbers Authority (see <http://www.iana.org/assignments/character-sets>) allows a character set name to contain any printable US-ASCII character, which might include characters not allowed by the NMTOKEN construction of XML 1.0; however, the only existing character set name which includes such a character is "NF_Z_62-010_(1973)".
20. Extensible Markup Language (XML) 1.0 (Fourth Edition) <http://www.w3.org/TR/REC-xml/>.
21. 9007199254740991 is 253-1. Some weakly typed languages use IEEE Standard 754 Doubles to represent all numbers. These Doubles cannot represent integers above 253 accurately.
22. RFC 3174: US Secure Hash Algorithm 1 (SHA1) <http://tools.ietf.org/html/rfc3174>.
23. Therefore a client and a connection manager will be compatible even if one or the other offers no support for multi-stream sessions.
24. The 'rid' attribute is always incremented normally without reference to any 'stream' attribute.
25. This helps to ensure backwards-compatibility with older implementations.
26. Each HTTP response MUST belong to the same session as the request that triggered it, but not necessarily to the same stream.
27. The broadcast payloads can be of any type.
28. SSL V3.0 <http://wp.netscape.com/eng/ssl3/draft302.txt>.
29. RFC 2818: HTTP Over TLS <http://tools.ietf.org/html/rfc2818>.
30. RFC 2817: Upgrading to TLS Within HTTP/1.1 <http://tools.ietf.org/html/rfc2817>.
31. RFC 1750: Randomness Recommendations for Security <http://tools.ietf.org/html/rfc1750>.
32. RFC 4270: Attacks on Cryptographic Hashes in Internet Protocols <http://tools.ietf.org/html/rfc4270>.
33. 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/>.
34. IANA registry of port numbers <http://www.iana.org/assignments/port-numbers>.
35. XEP-0156: Discovering Alternative XMPP Connection Methods <http://xmpp.org/extensions/xep-0156.html>.
Appendix H: Revision History
Note: Older versions of this specification might be available at http://xmpp.org/extensions/attic/
- Version 1.10 (2010-07-02)
- Further clarified use of 'from' and 'to' attributes; added missing condition values to the schema.
- (psa)
- Version 1.9 (2009-11-06)
- Added information for registration of port 5280 with IANA.
- (psa)
- Version 1.8 (2009-04-30)
- Removed secure attribute because it did not solve the problem it was intended to solve; added security consideration regarding link between connection manager and application server; changed "stanza" to "payload" for disambiguation with XMPP; clarified design objectives and relationship to similar technologies; corrected several errors in the schema.
- (psa/jm)
- Version 1.7 (2008-10-29)
- Moved alternative script syntax to historical specification; added implementation note about HTTP Pipelining; adjusted architectural description.
- (psa)
- Version 1.6 (2007-02-21)
- Multiple clarifications and restructuring without changes to protocol itself; changed title to BOSH; added section that fully explains the technique underlying the protocol; separated XMPP-specific features into new XEP-0206; added optional new Script Syntax and session pauses; added Acknowledgements section; added from and ver attributes; added hold attribute to session creation response; clarified polling too-frequently error; recommended that clients use HTTP Pipelining.
- (ip)
- Version 1.5 (2006-04-28)
- Added optional Multiple Streams section; added security considerations about encrypted HTTP connections; recommended use of SSL rather than HTTP over TLS; specified that request ID values must not exceed 9007199254740991; corrected datatypes of inactivity, polling, rid, and wait attributes in the schema; added <any/> and <anyAttribute/> elements to schema to optionally support non-XMPP XML elements and attributes; deprecated HTTP error codes in favor of new terminal binding conditions.
- (ip/psa)
- Version 1.4 (2005-12-14)
- Modified syntax of route attribute to be proto:host:port rather than XMPP URI/IRI.
- (psa)
- Version 1.3 (2005-11-02)
- Corrected stream:features namespace and the Recoverable Binding Conditions section; recommended that connection manager shall return secure attribute to client; recommended end-to-end encryption through proxy connection managers.
- (ip)
- Version 1.2 (2005-06-16)
- Specified optional use of route and secure attributes in session request. Minor correction: the stream features element should be included in the response that contains the authid attribute (this is not necessarily the session creation response).
- (ip)
- Version 1.1 (2005-06-02)
- Specified optional use of HTTP Accept-Encoding and Content-Encoding headers for compression at HTTP binding level.
- (ip)
- Version 1.0 (2005-03-03)
- Per a vote of the Jabber Council, advanced status to Draft.
- (psa)
- Version 0.10 (2004-11-08)
- Changed HTTP 401 errors to HTTP 404.
- (ip)
- Version 0.9 (2004-10-26)
- Added charset attribute.
- (ip/psa)
- Version 0.8 (2004-10-26)
- Specified that wait attribute must be included in the session creation response.
- (ip)
- Version 0.7 (2004-08-12)
- Defined appropriate XMPP stanza error conditions.
- (psa/ip)
- Version 0.6 (2004-07-19)
- Added xml:lang attribute to the session request; added recoverable binding error conditions.
- (ip)
- Version 0.5 (2004-05-07)
- Protocol refactored to enable simultaneous requests (request identifier attribute, wait attribute, hold attribute, requests attribute) and recovery of broken connections; added content attribute; removed all wrapper types except 'terminate'; updated error handling; made key mechanism optional (should use SSL/TLS instead).
- (ip/psa)
- Version 0.4 (2004-02-23)
- Fixed typos; removed "resource-constraint" binding error; added HTTP 403 error to table.
- (psa/ip)
- Version 0.3 (2004-02-19)
- Added 'authid' attribute to enable communication of XMPP stream ID (used in digest authentication); specified that Content-Types other than "text/xml" are allowed to support older HTTP clients; specified business rule for connection manager queueing of client requests; changed <packet/> to <body/> to support older HTTP clients; changed 'to' attribute on initialization element from MAY to SHOULD; recommended inclusion of unavailable presence in termination element sent from client; described architectural assumptions; specified binding-specific error handling.
- (psa/ip)
- Version 0.2 (2004-01-13)
- Added 'to' attribute on the initialization element; specified that 'text/html' is allowable for backwards-compatibility.
- (dss/psa/ip)
- Version 0.1 (2003-11-06)
- Initial version.
- (dss/psa)
结束
