The AMQP WebSocket Binding specification defines a mechanism for tunneling an AMQP connection over a WebSocket transport. It is applicable as an approach for general firewall tunneling and for Web browser messaging scenarios.

Status:

This document was last revised or approved by the OASIS Advanced Message Queuing Protocol (AMQP) Bindings and Mappings (AMQP-BINDMAP) TC on the above date. The level of approval is also listed above. Check the “Latest version” location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=amqp-bindmap#technical.

TC members should send comments on this specification to the TC’s email list. Others should send comments to the TC’s public comment list, after subscribing to it by following the instructions at the “Send A Comment” button on the TC’s web page at https://www.oasis-open.org/committees/amqp-bindmap/.

For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the TC’s web page (https://www.oasis-open.org/committees/amqp-bindmap/ipr.php).

Citation format:

When referencing this specification the following citation format should be used:

[amqp-wsb-v1.0]

Advanced Message Queuing Protocol (AMQP) WebSocket Binding (WSB) Version 1.0. Edited by John Fallows, David Ingham, and Robert Godfrey. 16 August 2016. OASIS Committee Specification 01. http://docs.oasis-open.org/amqp-bindmap/amqp-wsb/v1.0/cs01/amqp-wsb-v1.0-cs01.html. Latest version: http://docs.oasis-open.org/amqp-bindmap/amqp-wsb/v1.0/amqp-wsb-v1.0.html.

Notices

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.

OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark for above guidance.

Table of Contents

1 Introduction. 5

1.1 Terminology. 5

1.2 Normative References. 5

2 Opening a Connection. 6

2.1 Opening a WebSocket Connection. 6

2.1.1 Example. 7

2.2 Establishing a SASL Security Layer 7

2.2.1 SASL Protocol Header 7

2.2.2 SASL Negotiation. 8

2.3 AMQP Protocol Version Handshake. 8

2.4 Exchanging AMQP Frames. 8

2.5 Opening an AMQP Connection. 8

3 Handling AMQP Redirects. 10

3.1 Connection-level Redirect 10

3.2 Link-level Redirect 11

4 Closing a Connection. 13

5 Security. 14

6 IANA Considerations. 15

7 Conformance. 16

Appendix A. Acknowledgments. 17

Appendix B. Revision History. 18

1 Introduction

This specification describes how the WebSocket protocol can be used as a transport for AMQP 1.0 protocol traffic. It is applicable for two main scenarios:

● Firewall traversal. Since WebSocket connection establishment is implemented as standard HTTP traffic using the default ports (80 and 443), it is often able to pass through network security devices without requiring special configuration or opening of additional ports. When WebSocket is used as a transport for AMQP 1.0 protocol traffic, this enables communication between arbitrary AMQP peers such as an application using an AMQP client library and an AMQP message broker, separated by a firewall.

● Browser-based messaging. HTML5 compatible Web browsers have built-in support for the WebSocket protocol, thereby enabling a broad range of browser-based AMQP messaging scenarios.

An AMQP 1.0 protocol session begins with the protocol version negotiation, including the establishment of layered security layers if required. Once this is complete, the session continues with the exchange of AMQP frames that control the operation of the protocol and transport business messages between the communicating peers.

The remainder of this specification describes how these concepts are mapped to a WebSocket transport.

1.1 Terminology

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].

1.2 Normative References

[AMQP] Godfrey, Robert; Ingham, David; Schloming, Rafael, “Advanced Message Queuing Protocol (AMQP) Version 1.0”, October 2012. OASIS Standard. http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-overview-v1.0-os.html http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-overview-v1.0-os.html

[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997. http://www.ietf.org/rfc/rfc2119.txt.

[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., Berners-Lee, T., "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. http://tools.ietf.org/html/rfc2616.

[RFC4422] Melnikov, A., and Zeilenga, K., “Simple Authentication and Security Layer (SASL)", RFC 4422, June 2006. http://tools.ietf.org/html/rfc4422.

[RFC6455] Fette, I., and Melinkov, A., “The WebSocket Protocol”, December 2011. RFC 6455, December 2011. http://tools.ietf.org/html/rfc6455.

2 Opening a Connection

Opening a protocol session using the AMQP WebSocket binding involves the following sequence of steps:

● Opening a WebSocket connection

● Performing the AMQP protocol version handshake including optional establishment of a SASL security layer [RFC4422]

● Exchanging AMQP frames

These steps are described in the following subsections.

2.1 Opening a WebSocket Connection

The WebSocket Protocol connection MUST be opened as described in Section 4 of the WebSocket specification [RFC6455]. The initiating AMQP endpoint (the WebSocket Client) sends a HTTP GET request to the receiving AMQP endpoint (the WebSocket Server) identifying AMQP 1.0 as the subprotocol being used.

The table below defines how the elements of this HTTP WebSocket upgrade request are used in the context of the AMQP WebSocket binding:

WebSocket request element	Usage in the AMQP WebSocket binding
Request-URI of the HTTP GET request	This binding does not define any semantic meaning to this field. An implementation MAY interpret this field in an implementation-specific manner.
Host HTTP header	Identifies the hostname of the AMQP container. The value provided here SHOULD match that provided later in the hostname field of the open frame, and during SASL negotiation (if used).
Sec-WebSocket-Protocol HTTP header	Identifies the WebSocket subprotocol. For this AMQP WebSocket binding, the value MUST be set to the US-ASCII text string “amqp” which refers to the 1.0 version of the AMQP 1.0 or greater, with version negotiation as defined by AMQP 1.0.

As per the WebSocket specification [RFC6455], if the Server agrees to the WebSocket upgrade to the requested subprotocol then it MUST respond with an HTTP Status-Line with status code 101 (“Switching Protocols”) and echo the requested subprotocol in the Sec-WebSocket-Protocol HTTP header. Alternatively, the Server MAY return a redirect response (HTTP 3XX) and/or request HTTP level authentication. Section 4.2.2 of the Websocket specification [RFC6455] provides full details on the permutations of the Server’s opening handshake.

If the Client does not receive a response with HTTP status code 101 and an HTTP Sec-WebSocket-Protocol equal to the US-ASCII text string “amqp” then the Client MUST close the socket connection. If the Client receives a HTTP 3XX redirect response from the Server, the Client MAY follow the redirect and attempt connection establishment at the provided endpoint. If the response indicates a request for HTTP-level authentication then the Client MAY attempt connection establishment with new authentication credentials. Note that this specification does not define any relationship between any such HTTP-level credentials and the credentials that MAY be later provided as part of a SASL protocol layer negotiation. However, a particular implementation MAY impose some relationship.

An example of a successful upgrade handshake is shown below in Section 2.1.1.

2.1.1 Example

This section is non-normative.

An example WebSocket upgrade handshake to the AMQP WebSocket binding subprotocol is shown below.

The request from the client looks as follows:

GET /examplepath HTTP/1.1

Host: server.example.com

Upgrade: websocket

Connection: Upgrade

Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==

Sec-WebSocket-Protocol: amqp

Sec-WebSocket-Version: 13

The response from the server looks as follows:

HTTP/1.1 101 Switching Protocols

Upgrade: websocket

Connection: Upgrade

Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

Sec-WebSocket-Protocol: amqp

2.2 Establishing a SASL Security Layer

AMQP peers MAY choose to establish a SASL security layer prior to commencing the raw AMQP protocol as defined in Part 5 of the AMQP 1.0 Specification [AMQP]. If SASL is not required then this section is omitted and the connection establishment process continues as defined in the Section below entitled AMQP Protocol Version Handshake.

Note that SASL mechanisms that provide for encryption in addition to authentication are not supported with this AMQP WebSocket binding.

2.2.1 SASL Protocol Header

If a SASL security layer is required then each peer MUST start by sending a protocol header. The protocol header consists of the upper case ASCII letters “AMQP” followed by a protocol id of three, followed by three unsigned bytes representing the major, minor, and revision of the specification version (currently 1 (SASL-MAJOR), 0 (SASLMINOR),0 (SASL-REVISION)). In total this is an 8-octet sequence:

4 octets	1 octet	1 octet	1 octet	1 octet
“AMQP”	%d3	major	minor	revision

This protocol header MUST be sent as the contents of a single WebSocket message.

2.2.2 SASL Negotiation

The SASL negotiation is implemented by the exchange of SASL frames as defined in Section 5.3 of the AMQP 1.0 specification [AMQP].

After successful establishment of the SASL layer then the connection establishment process continues with the AMQP protocol version handshake, as described below.

2.3 AMQP Protocol Version Handshake

Prior to sending any frames on a connection, each peer MUST start by sending a protocol header that indicates the protocol version used on the connection. The protocol header consists of the upper case ASCII letters “AMQP” followed by a protocol id of zero, followed by three unsigned bytes representing the major, minor, and revision of the protocol version (currently 1 (MAJOR), 0 (MINOR), 0 (REVISION)). In total this is an 8-octet sequence:

4 octets	1 octet	1 octet	1 octet	1 octet
“AMQP”	%d0	major	minor	revision

This protocol header MUST be sent as the contents of a single WebSocket message.

More details on the version negotiation process is described in Section 2.2 of the AMQP 1.0 Specification [AMQP].

2.4 Exchanging AMQP Frames

After the protocol version handshake is complete, all traffic over the connection is structured as AMQP frames. The first step is to open an AMQP Connection, via the exchange of AMQP open frames. A single WebSocket connection maps to a single AMQP connection. As is normal for AMQP, there MAY be many AMQP sessions over a single WebSocket Connection / AMQP Connection and there MAY be many Links sharing a single Session.

AMQP frames MUST be sent as binary data payloads of WebSocket messages. There is no mapping between an AMQP frame and a WebSocket message. Therefore, a single AMQP frame MAY be split over one or more consecutive WebSocket messages. Conversely, a single WebSocket message MAY contain one or more AMQP frames. There is also no mapping between an AMQP frame and a WebSocket frame. Therefore, a single AMQP frame MAY be split over one or more consecutive WebSocket frames. Conversely, a single WebSocket frame MAY contain one or more AMQP frames.

2.5 Opening an AMQP Connection

Section 2.7.1 of the AMQP 1.0 specification [AMQP] defines the OPEN performative which includes a “properties” field.

The table below indicates additional properties to be included with the OPEN performative.

OPEN property name

Usage in the AMQP WebSocket binding

redirect-schemes

the list of redirect capable protocol schemes supported by the endpoint.

The client SHOULD send the list of schemes it can attempt to follow when redirected. Redirectable WebSocket schemes include ws and wss.

If omitted by the client, the server MAY send a redirect for any scheme to the client.

The server SHOULD omit this property, since the server cannot follow any redirects sent by the client.

If omitted by the server, the client SHOULD NOT send a redirect to the server.

3 Handling AMQP Redirects

AMQP 1.0 includes two redirect mechanisms, connection-level redirect and link-level redirect. These can be used by one peer to indicate to the corresponding peer that the connection or link should be made to an alternative endpoint.

3.1 Connection-level Redirect

Section 2.8.16 of the AMQP 1.0 specification [AMQP] defines the amqp:connection:redirect error which indicates that the container is no longer available on the current connection and that the peer SHOULD attempt reconnection to the container using the details provided in the associated map.

The table below indicates how the elements from the info map associated with the amqp:connection:redirect error SHOULD be interpreted when reconnecting:

Redirect error info map element	Usage in the AMQP WebSocket binding
hostname	the hostname of the container. This value SHOULD be used in the Host HTTP header of the initial HTTP request. The same value SHOULD be used in the hostname field of the open frame, and during SASL negotiation (if used).
network-host	the DNS hostname or IP address of the machine hosting access to the container. This may refer to the container host machine directly, or an intermediary providing indirect access to the container host machine.
port	the port number of the machine hosting access to the container. This may refer to the container host machine directly, or an intermediary providing indirect access to the container host machine.

To provide further information for redirection when using the WebSocket transport, the following optional elements MAY also be provided in the info map associated with the amqp:connection:redirect error. The table below indicates how these elements SHOULD be interpreted if provided:

Redirect error info map element

Usage in the AMQP WebSocket binding

scheme

the connection scheme for the redirected request.

Acceptable values include ws and wss.

If omitted, the current connection scheme SHOULD be used as the default scheme for the redirected connection

For security reasons, a connection SHOULD NOT be redirected to a less secure transport.

For example, a wss scheme connection SHOULD NOT be directed to a ws scheme connection.

path

the connection path for the redirected request.

This value MUST begin with a leading slash when path is required by the connection scheme. For example, both ws and wss schemes require a path.

If omitted, the current connection path SHOULD be used as the default path for the redirected connection.

This value SHOULD be used as the Request-URI of the WebSocket handshake HTTP GET request.

3.2 Link-level Redirect

Section 2.8.18 of the AMQP 1.0 specification [AMQP] defines the amqp:link:redirect error which indicates that the address provided cannot be resolved to a terminus at the current container.

The table below indicates how the elements from the info map associated with the amqp:link:redirect error SHOULD be interpreted when reconnecting:

Redirect error info map element	Usage in the AMQP WebSocket binding
hostname	the hostname of the container. This value SHOULD be used in the Host HTTP header of the initial HTTP request. The same value SHOULD be used in the hostname field of the open frame, and during SASL negotiation (if used).
network-host	the DNS hostname or IP address of the machine hosting access to the container. This may refer to the container host machine directly, or an intermediary providing indirect access to the container host machine.
port	the port number of the machine hosting access to the container. This may refer to the container host machine directly, or an intermediary providing indirect access to the container host machine.
address	The address of the terminus at the container.

To provide further information for redirection when using the WebSocket transport, the following optional elements MAY also be provided in the info map associated with the amqp:link:redirect error. The table below indicates how these elements SHOULD be interpreted if provided:

Redirect error info map element

Usage in the AMQP WebSocket binding

scheme

the connection scheme for the redirected request.

Acceptable values include ws and wss.

If omitted, the current connection scheme SHOULD be used as the default scheme for the redirected connection

For security reasons, a connection SHOULD NOT be redirected to a less secure transport.

For example, a wss scheme connection SHOULD NOT be directed to a ws scheme connection.

path

the connection path for the redirected request.

This value MUST begin with a leading slash when path is required by the connection scheme. For example, both ws and wss schemes require a path.

If omitted, the current connection path SHOULD be used as the default path for the redirected connection.

This value SHOULD be used as the Request-URI of the WebSocket handshake HTTP GET request.

4 Closing a Connection

In the non-error case, the AMQP connection SHOULD be closed first, followed by the WebSocket connection.

Once the AMQP closing handshake has completed, the WebSocket closing handshake MUST be initiated. As described in [RFC6455] section 5.5.1, the peer node desiring to close the connection sends a WebSocket Close frame. Once the other peer node receives this, it MAY finish transmitting any majority finished transmissions, and then MUST send a WebSocket Close frame in return.

5 Security

This binding supports the use of both the standard WebSocket and secure WebSocket protocols. In either case the connection establishment sequence described above remains the same.

For use in standard, non-secure mode, the WebSocket (“ws”) MUST be used as the transport protocol. In this mode, the TCP/IP socket connection SHOULD be made to port 80. For use in secure mode, the WebSocket over TLS or WebSocket Secure (“wss”) MUST be used as the transport protocol. In this mode, the TCP/IP socket connection SHOULD be made to port 443.

Note that the AMQP specification defines two modes of TLS usage, either with a pure TLS tunnel through which the standard AMQP protocol flows, or an in-place upgrade, in which case the transition to TLS occurs after the AMQP protocol handshake. Note that neither of these modes of TLS usage are supported with the AMQP WebSocket binding. If TLS tunneling is required then the WebSocket Secure (“wss”) protocol MUST be used, as described above.

6 IANA Considerations

This specification requests IANA to register the WebSocket AMQP sub-protocol under the “WebSocket Subprotocol Name” registry with the following data:

Subprotocol Identifier	amqp
Subprotocol Common Name	Advanced Message Queuing Protocol (AMQP) 1.0+
Subprotocol Definition	http://docs.oasis-open.org/amqp-bindmap/amqp-wsb/v1.0/cs01/amqp-wsb-v1.0-cs01.pdf

7 Conformance

An implementation is compliant with this specification if it implements all MUST or REQUIRED level requirements.

Appendix A. Acknowledgments

The following individuals have participated in the creation of this specification and are gratefully acknowledged:

● Raphael Cohn, Individual

● Rob Dolin, Microsoft

● Rob Godfrey, JPMorgan Chase Bank, N.A.

● Steve Huston, Individual

● John Fallows, Kaazing

● David Ingham, Red Hat

● Alex Kritikos, Software AG, Inc.

● Rafael Schloming, Red Hat

● Jakub Scholz, Deutsche Boerse AG

The following individuals were members of the OASIS Advanced Message Queueing Protocol (AMQP) Binding and Mappings (AMQP-BINDMAP) Technical Committee during the creation of this specification and their contributions are gratefully acknowledged:

● Steve Huston, Individual

● Matthew Arrott, Individual

● Allan Beck, JPMorgan Chase Bank, N.A.

● Andrew Braddock, US Department of Homeland Security

● Raphael Cohn, Individual

● Andrew Doddington, Bank of America

● Rob Dolin, Microsoft

● William Henry, Red Hat

● Ram Jeyaraman, Microsoft

● Alex Kritikos, Software AG, Inc.

● Shawn McAllister, Solace Systems

● Dale Moberg, Axway Software

● John O'Hara, Individual

● Jonathan Poulter, Kaazing

● John Fallows, Kaazing

● Oleksandr Rudyy, JPMorgan Chase Bank, N.A.

● Rafael Schloming, Red Hat

● Mark Blair, Credit Suisse

● Laurie Bryson, JPMorgan Chase Bank, N.A.

● Robert Gemmell, JPMorgan Chase Bank, N.A.

● Rob Godfrey, JPMorgan Chase Bank, N.A.

● David Ingham, Red Hat

● Paul Knight, Individual

● Andreas Moravec, Deutsche Boerse AG

● Jakub Scholz, Deutsche Boerse AG

● Wolf Tombe, US Department of Homeland Security

● Timothy Bish, Red Hat

● William Cox, Individual

● Stefan Hagen, Individual

Appendix B. Revision History

Revision	Date	Editor	Changes Made
WD10	18 Apr 2016	John Fallows	Minor grammar and formatting changes.
WD09	30 Mar 2016	John Fallows	Minor grammar and formatting changes. Updated acknowledgments list.
WD08	07 Mar 2016	John Fallows	WebSocket Subprotocol changed to “amqp” AMQP frames not required to align with WebSocket messages or frames WebSocket closing handshake MUST follow AMQP handshake Change all SSL references to TLS WebSocket mapping for AMQP redirect frames
WD07	04 Apr 2014	David Ingham	Fixed typo in Section 2.4.
WD06	03 Apr 2014	David Ingham	Tidied up references and fixed formatting issues in Terminology and References sections.
WD05	02 Apr 2014	David Ingham	Added conformance section.
CSD01 Candidate	25 Feb 2014	David Ingham	Initial version