| <?xml version="1.0"?> |
| <?xml-stylesheet type="text/xsl" href="amqp.xsl"?> |
| |
| <!-- |
| Copyright Notice |
| ================ |
| (c) Copyright Bank of America, N.A., Barclays Bank PLC, Cisco Systems, Credit Suisse, Deutsche |
| Boerse, Envoy Technologies Inc., Goldman Sachs, HCL Technologies Ltd, IIT Software GmbH, iMatix |
| Corporation, INETCO Systems Limited, Informatica Corporation, JPMorgan Chase & Co., Kaazing |
| Corporation, N.A, Microsoft Corporation, my-Channels, Novell, Progress Software, Red Hat Inc., |
| Software AG, Solace Systems Inc., StormMQ Ltd., Tervela Inc., TWIST Process Innovations Ltd, |
| VMware, Inc., and WS02 Inc. |
| 2006-2011. All rights reserved. |
| |
| License |
| ======= |
| |
| Bank of America, N.A., Barclays Bank PLC, Cisco Systems, Credit Suisse, Deutsche Boerse, Goldman |
| Sachs, HCL Technologies Ltd, IIT Software GmbH, INETCO Systems Limited, Informatica Corporation, |
| JPMorgan Chase & Co., Kaazing Corporation, N.A, Microsoft Corporation, my-Channels, Novell, |
| Progress Software, Red Hat Inc., Software AG, Solace Systems Inc., StormMQ Ltd., Tervela Inc., |
| TWIST Process Innovations Ltd, VMware, Inc., and WS02 Inc. (collectively, the "Authors") each |
| hereby grants to you a worldwide, perpetual, royalty-free, nontransferable, nonexclusive license |
| to (i) copy, display, distribute and implement the Advanced Message Queuing Protocol ("AMQP") |
| Specification and (ii) the Licensed Claims that are held by the Authors, all for the purpose of |
| implementing the Advanced Message Queuing Protocol Specification. Your license and any rights |
| under this Agreement will terminate immediately without notice from any Author if you bring any |
| claim, suit, demand, or action related to the Advanced Message Queuing Protocol Specification |
| against any Author. Upon termination, you shall destroy all copies of the Advanced Message Queuing |
| Protocol Specification in your possession or control. |
| |
| As used hereunder, "Licensed Claims" means those claims of a patent or patent application, |
| throughout the world, excluding design patents and design registrations, owned or controlled, or |
| that can be sublicensed without fee and in compliance with the requirements of this Agreement, by |
| an Author or its affiliates now or at any future time and which would necessarily be infringed by |
| implementation of the Advanced Message Queuing Protocol Specification. A claim is necessarily |
| infringed hereunder only when it is not possible to avoid infringing it because there is no |
| plausible non-infringing alternative for implementing the required portions of the Advanced |
| Message Queuing Protocol Specification. Notwithstanding the foregoing, Licensed Claims shall not |
| include any claims other than as set forth above even if contained in the same patent as Licensed |
| Claims; or that read solely on any implementations of any portion of the Advanced Message Queuing |
| Protocol Specification that are not required by the Advanced Message Queuing Protocol |
| Specification, or that, if licensed, would require a payment of royalties by the licensor to |
| unaffiliated third parties. Moreover, Licensed Claims shall not include (i) any enabling |
| technologies that may be necessary to make or use any Licensed Product but are not themselves |
| expressly set forth in the Advanced Message Queuing Protocol Specification (e.g., semiconductor |
| manufacturing technology, compiler technology, object oriented technology, networking technology, |
| operating system technology, and the like); or (ii) the implementation of other published |
| standards developed elsewhere and merely referred to in the body of the Advanced Message Queuing |
| Protocol Specification, or (iii) any Licensed Product and any combinations thereof the purpose or |
| function of which is not required for compliance with the Advanced Message Queuing Protocol |
| Specification. For purposes of this definition, the Advanced Message Queuing Protocol |
| Specification shall be deemed to include both architectural and interconnection requirements |
| essential for interoperability and may also include supporting source code artifacts where such |
| architectural, interconnection requirements and source code artifacts are expressly identified as |
| being required or documentation to achieve compliance with the Advanced Message Queuing Protocol |
| Specification. |
| |
| As used hereunder, "Licensed Products" means only those specific portions of products (hardware, |
| software or combinations thereof) that implement and are compliant with all relevant portions of |
| the Advanced Message Queuing Protocol Specification. |
| |
| The following disclaimers, which you hereby also acknowledge as to any use you may make of the |
| Advanced Message Queuing Protocol Specification: |
| |
| THE ADVANCED MESSAGE QUEUING PROTOCOL SPECIFICATION IS PROVIDED "AS IS," AND THE AUTHORS MAKE NO |
| REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF |
| MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS |
| OF THE ADVANCED MESSAGE QUEUING PROTOCOL SPECIFICATION ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE |
| IMPLEMENTATION OF THE ADVANCED MESSAGE QUEUING PROTOCOL SPECIFICATION WILL NOT INFRINGE ANY THIRD |
| PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. |
| |
| THE AUTHORS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL |
| DAMAGES ARISING OUT OF OR RELATING TO ANY USE, IMPLEMENTATION OR DISTRIBUTION OF THE ADVANCED |
| MESSAGE QUEUING PROTOCOL SPECIFICATION. |
| |
| The name and trademarks of the Authors may NOT be used in any manner, including advertising or |
| publicity pertaining to the Advanced Message Queuing Protocol Specification or its contents |
| without specific, written prior permission. Title to copyright in the Advanced Message Queuing |
| Protocol Specification will at all times remain with the Authors. |
| |
| No other rights are granted by implication, estoppel or otherwise. |
| |
| Upon termination of your license or rights under this Agreement, you shall destroy all copies of |
| the Advanced Message Queuing Protocol Specification in your possession or control. |
| |
| Trademarks |
| ========== |
| "JPMorgan", "JPMorgan Chase", "Chase", the JPMorgan Chase logo and the Octagon Symbol are |
| trademarks of JPMorgan Chase & Co. |
| |
| RED HAT is a registered trademarks of Red Hat, Inc. in the US and other countries. |
| |
| Other company, product, or service names may be trademarks or service marks of others. |
| |
| Link to full AMQP specification: |
| ================================= |
| http://www.amqp.org/confluence/display/AMQP/AMQP+Specification |
| --> |
| |
| <!DOCTYPE amqp SYSTEM "amqp.dtd"> |
| |
| <amqp xmlns="http://www.amqp.org/schema/amqp.xsd" |
| name="security" label="working version"> |
| |
| <section name="security-layers" title="Security Layers" label="Security Layers"> |
| <doc> |
| <p> |
| Security Layers are used to establish an authenticated and/or encrypted transport over which |
| regular AMQP traffic can be tunneled. Security Layers may be tunneled over one another (for |
| instance a Security Layer used by the peers to do authentication may be tunneled over a |
| Security Layer established for encryption purposes). |
| </p> |
| |
| <p> |
| The framing and protocol definitions for security layers are expected to be defined |
| externally to the AMQP specification as in the case of TLS. An exception to this is the SASL |
| security layer which depends on its host protocol to provide framing. Because of this we |
| define the frames necessary for SASL to function in <xref name="sasl"/> below. When a |
| security layer terminates (either before or after a secure tunnel is established), the TCP |
| Connection MUST be closed by first shutting down the outgoing stream and then reading the |
| incoming stream until it is terminated. |
| </p> |
| </doc> |
| </section> |
| |
| <section name="tls" title="TLS" label="TLS Security Layer"> |
| <doc> |
| <p> |
| To establish a TLS tunnel, 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 two, |
| followed by three unsigned bytes representing the major, minor, and revision of the |
| specification version (currently <xref name="TLS-MAJOR"/>, <xref name="TLS-MINOR"/>, |
| <xref name="TLS-REVISION"/>). In total this is an 8-octet sequence: |
| </p> |
| |
| <picture><![CDATA[ |
| 4 OCTETS 1 OCTET 1 OCTET 1 OCTET 1 OCTET |
| +----------+---------+---------+---------+----------+ |
| | "AMQP" | %d2 | major | minor | revision | |
| +----------+---------+---------+---------+----------+ |
| ]]> |
| </picture> |
| |
| <p> |
| Other than using a protocol id of two, the exchange of TLS tunnel headers follows the same |
| rules specified in the version negotiation section of the transport specification (See |
| <xref name="version-negotiation"/>). |
| </p> |
| </doc> |
| |
| <doc> |
| <p> |
| The following diagram illustrates the interaction involved in creating a TLS Security Layer: |
| </p> |
| <picture><![CDATA[ |
| TCP Client TCP Server |
| ========================================= |
| AMQP%d2.1.0.0 ---------> |
| <--------- AMQP%d2.1.0.0 |
| : |
| : |
| <TLS negotiation> |
| : |
| : |
| AMQP%d0.1.0.0 ---------> (over TLS secured connection) |
| <--------- AMQP%d0.1.0.0 |
| open ---------> |
| <--------- open |
| ]]> |
| </picture> |
| |
| <p> |
| When the use of the TLS Security Layer is negotiated, the following rules apply: |
| </p> |
| |
| <ul> |
| <li> |
| <p> |
| The TLS client peer and TLS server peer are determined by the TCP client peer and TCP |
| server peer respectively. |
| </p> |
| </li> |
| |
| <li> |
| <p> |
| The TLS client peer SHOULD use the server name indication extension as described in |
| RFC-4366. If it does so, then it is implementation-specific what happens if this |
| differs to hostname in the <xref type="type" name="sasl-init"/> and |
| <xref type="type" name="open"/> frame frames. |
| </p> |
| <p> |
| This field can be used by AMQP proxies to determine the correct back-end service to |
| connect the client to, and to determine the domain to validate the client's |
| credentials against if TLS client certificates are being used. |
| </p> |
| </li> |
| |
| <li> |
| <p> |
| The TLS client MUST validate the certificate presented by the TLS server. |
| </p> |
| </li> |
| |
| <li> |
| <p> |
| Implementations MAY choose to use TLS with unidirectional shutdown, i.e. an application |
| initiating shutdown using close_notify is not obliged to wait for the peer to respond, |
| and MAY close the write-half of the TCP socket. |
| </p> |
| </li> |
| </ul> |
| </doc> |
| |
| <doc title="Alternative Establishment"> |
| <p> |
| In certain situations, such as connecting through firewalls, it may not be possible to |
| establish a TLS security layer using tunnelling. This might be because a deep packet |
| inspecting firewall sees the first few bytes of the connection 'as not being TLS'. |
| </p> |
| |
| <p> |
| As an alternative, implementations MAY run a pure TLS server, i.e., one that does not |
| expect the tunnel negotiation handshake. The IANA service name for this is amqps and the |
| port is <xref name="SECURE-PORT"/> (5671). Implementations may also choose to run this pure |
| TLS server on other ports, should this be operationally required (e.g. to tunnel through a |
| legacy firewall that only expects TLS traffic on port 443). |
| </p> |
| </doc> |
| |
| <definition name="TLS-MAJOR" value="1" label="major protocol version" /> |
| <definition name="TLS-MINOR" value="0" label="minor protocol version" /> |
| <definition name="TLS-REVISION" value="0" label="protocol revision" /> |
| |
| </section> |
| |
| <!-- == Section: sasl ======================================================================== --> |
| |
| <section name="sasl" title="SASL" label="SASL Security Layer"> |
| <doc> |
| <p> |
| To establish a SASL tunnel, 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 <xref name="SASL-MAJOR"/>, <xref name="SASL-MINOR"/>, |
| <xref name="SASL-REVISION"/>). In total this is an 8-octet sequence: |
| </p> |
| |
| <picture><![CDATA[ |
| 4 OCTETS 1 OCTET 1 OCTET 1 OCTET 1 OCTET |
| +----------+---------+---------+---------+----------+ |
| | "AMQP" | %d3 | major | minor | revision | |
| +----------+---------+---------+---------+----------+ |
| ]]> |
| </picture> |
| |
| <p> |
| Other than using a protocol id of three, the exchange of SASL tunnel headers follows the |
| same rules specified in the version negotiation section of the transport specification (See |
| <xref name="version-negotiation"/>). |
| </p> |
| |
| <p> |
| The following diagram illustrates the interaction involved in creating a SASL Security |
| Layer: |
| </p> |
| |
| <picture><![CDATA[ |
| TCP Client TCP Server |
| ========================================= |
| AMQP%d3.1.0.0 ---------> |
| <--------- AMQP%d3.1.0.0 |
| : |
| : |
| <SASL negotiation> |
| : |
| : |
| AMQP%d0.1.0.0 ---------> (over SASL secured connection) |
| <--------- AMQP%d0.1.0.0 |
| open ---------> |
| <--------- open |
| ]]> |
| </picture> |
| </doc> |
| |
| <doc title="SASL Frames"> |
| <p> |
| SASL is negotiated using <xref name="framing"/>. A SASL frame has a type code of 0x01. |
| Bytes 6 and 7 of the header are ignored. Implementations SHOULD set these to 0x00. The |
| extended header is ignored. Implementations SHOULD therefore set DOFF to 0x02. |
| </p> |
| |
| <picture title="SASL Frame"><![CDATA[ |
| type: 0x01 - SASL frame |
| |
| +0 +1 +2 +3 |
| +-----------------------------------+ -. |
| 0 | SIZE | | |
| +-----------------------------------+ |---> Frame Header |
| 4 | DOFF | TYPE | <IGNORED>*1 | | (8 bytes) |
| +-----------------------------------+ -' |
| +-----------------------------------+ -. |
| 8 | ... | | |
| . . |---> Extended Header |
| . <IGNORED>*2 . | (DOFF * 4 - 8) bytes |
| | ... | | |
| +-----------------------------------+ -' |
| +-----------------------------------+ -. |
| 4*DOFF | | | |
| . . | |
| . . | |
| . Sasl Mechanisms / Sasl Init . | |
| . Sasl Challenge / Sasl Response . |---> Frame Body |
| . Sasl Outcome . | (SIZE - DOFF * 4) bytes |
| . . | |
| . . | |
| . ________| | |
| | ... | | |
| +--------------------------+ -' |
| |
| *1 SHOULD be set to 0x0000 |
| *2 Ignored, so DOFF should be set to 0x02 |
| ]]> |
| </picture> |
| |
| <p> |
| The maximum size of a SASL frame is defined by <xref name="MIN-MAX-FRAME-SIZE"/>. There is |
| no mechanism within the SASL negotiation to negotiate a different size. The frame body of a |
| SASL frame may contain exactly one AMQP type, whose type encoding must have |
| <![CDATA[ provides="sasl-frame" ]]>. Receipt of an empty frame is an irrecoverable error. |
| </p> |
| </doc> |
| |
| <doc title="SASL Negotiation"> |
| <p> |
| The peer acting as the SASL Server must announce supported authentication mechanisms using |
| the <xref name="sasl-mechanisms"/> frame. The partner must then choose one of the supported |
| mechanisms and initiate a sasl exchange. |
| </p> |
| |
| <picture title="SASL Exchange"><![CDATA[ |
| SASL Client SASL Server |
| ================================ |
| <-- SASL-MECHANISMS |
| SASL-INIT --> |
| ... |
| <-- SASL-CHALLENGE * |
| SASL-RESPONSE --> |
| ... |
| <-- SASL-OUTCOME |
| -------------------------------- |
| * Note that the SASL |
| challenge/response step may |
| occur zero or more times |
| depending on the details of |
| the SASL mechanism chosen. |
| ]]> |
| </picture> |
| |
| <p> |
| The peer playing the role of the SASL Client and the peer playing the role of the SASL |
| server MUST correspond to the TCP client and server respectively. |
| </p> |
| </doc> |
| |
| <doc title="Security Frame Bodies"/> |
| |
| <!-- - Frame: sasl-mechanisms - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> |
| |
| <type class="composite" name="sasl-mechanisms" source="list" provides="sasl-frame" |
| label="advertise available sasl mechanisms"> |
| <doc> |
| <p> |
| Advertises the available SASL mechanisms that may be used for authentication. |
| </p> |
| </doc> |
| |
| <descriptor name="amqp:sasl-mechanisms:list" code="0x00000000:0x00000040"/> |
| |
| <field name="sasl-server-mechanisms" type="symbol" multiple="true" mandatory="true" |
| label="supported sasl mechanisms"> |
| <doc> |
| <p> |
| A list of the sasl security mechanisms supported by the sending peer. It is invalid |
| for this list to be null or empty. If the sending peer does not require its partner |
| to authenticate with it, then it should send a list of one element with its value as |
| the SASL mechanism <i>ANONYMOUS</i>. The server mechanisms are ordered in decreasing |
| level of preference. |
| </p> |
| </doc> |
| </field> |
| </type> |
| |
| <!-- - Frame: sasl-init - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> |
| |
| <type class="composite" name="sasl-init" source="list" provides="sasl-frame" |
| label="initiate sasl exchange"> |
| <doc> |
| <p>Selects the sasl mechanism and provides the initial response if needed.</p> |
| </doc> |
| |
| <descriptor name="amqp:sasl-init:list" code="0x00000000:0x00000041"/> |
| |
| <field name="mechanism" type="symbol" label="selected security mechanism" mandatory="true"> |
| <doc> |
| <p> |
| The name of the SASL mechanism used for the SASL exchange. If the selected mechanism is |
| not supported by the receiving peer, it MUST close the Connection with the |
| authentication-failure close-code. Each peer MUST authenticate using the highest-level |
| security profile it can handle from the list provided by the partner. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="initial-response" type="binary" label="security response data"> |
| <doc> |
| <p> |
| A block of opaque data passed to the security mechanism. The contents of this data are |
| defined by the SASL security mechanism. |
| </p> |
| </doc> |
| </field> |
| |
| <field name="hostname" type="string" label="the name of the target host"> |
| <doc> |
| <p> |
| The DNS name of the host (either fully qualified or relative) to which the sending peer |
| is connecting. It is not mandatory to provide the hostname. If no hostname is provided |
| the receiving peer should select a default based on its own configuration. |
| </p> |
| |
| <p> |
| This field can be used by AMQP proxies to determine the correct back-end service to |
| connect the client to, and to determine the domain to validate the client's credentials |
| against. |
| </p> |
| |
| <p> |
| This field may already have been specified by the server name indication extension as |
| described in RFC-4366, if a TLS layer is used, in which case this field SHOULD be null |
| or contain the same value. It is undefined what a different value to those already |
| specific means. |
| </p> |
| </doc> |
| </field> |
| </type> |
| |
| <!-- - Frame: sasl-challenge - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> |
| |
| <type class="composite" name="sasl-challenge" source="list" provides="sasl-frame" |
| label="security mechanism challenge"> |
| <doc> |
| <p>Send the SASL challenge data as defined by the SASL specification.</p> |
| </doc> |
| |
| <descriptor name="amqp:sasl-challenge:list" code="0x00000000:0x00000042"/> |
| |
| <field name="challenge" type="binary" label="security challenge data" mandatory="true"> |
| <doc> |
| <p> |
| Challenge information, a block of opaque binary data passed to the security |
| mechanism. |
| </p> |
| </doc> |
| </field> |
| </type> |
| |
| <!-- - Frame: sasl-response - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> |
| |
| <type class="composite" name="sasl-response" source="list" provides="sasl-frame" |
| label="security mechanism response"> |
| <doc> |
| <p>Send the SASL response data as defined by the SASL specification.</p> |
| </doc> |
| |
| <descriptor name="amqp:sasl-response:list" code="0x00000000:0x00000043"/> |
| |
| <field name="response" type="binary" label="security response data" mandatory="true"> |
| <doc> |
| <p> |
| A block of opaque data passed to the security mechanism. The contents of this data are |
| defined by the SASL security mechanism. |
| </p> |
| </doc> |
| </field> |
| </type> |
| |
| <!-- - Frame: sasl-outcome - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> |
| |
| <type class="composite" name="sasl-outcome" source="list" provides="sasl-frame" |
| label="indicates the outcome of the sasl dialog"> |
| <doc> |
| <p> |
| This frame indicates the outcome of the SASL dialog. Upon successful completion of the |
| SASL dialog the Security Layer has been established, and the peers must exchange protocol |
| headers to either start a nested Security Layer, or to establish the AMQP Connection. |
| </p> |
| </doc> |
| |
| <descriptor name="amqp:sasl-outcome:list" code="0x00000000:0x00000044"/> |
| |
| <field name="code" type="sasl-code" mandatory="true" |
| label="indicates the outcome of the sasl dialog"> |
| <doc> |
| <p>A reply-code indicating the outcome of the SASL dialog.</p> |
| </doc> |
| </field> |
| |
| <field name="additional-data" type="binary" label="additional data as specified in RFC-4422"> |
| <doc> |
| <p> |
| The additional-data field carries additional data on successful authentication outcome |
| as specified by the SASL specification (RFC-4422). If the authentication is |
| unsuccessful, this field is not set. |
| </p> |
| </doc> |
| </field> |
| </type> |
| |
| <type class="restricted" name="sasl-code" source="ubyte" |
| label="codes to indicate the outcome of the sasl dialog"> |
| <choice name="ok" value="0"> |
| <doc> |
| <p>Connection authentication succeeded.</p> |
| </doc> |
| </choice> |
| <choice name="auth" value="1"> |
| <doc> |
| <p> |
| Connection authentication failed due to an unspecified problem with the supplied |
| credentials. |
| </p> |
| </doc> |
| </choice> |
| <choice name="sys" value="2"> |
| <doc> |
| <p>Connection authentication failed due to a system error.</p> |
| </doc> |
| </choice> |
| <choice name="sys-perm" value="3"> |
| <doc> |
| <p> |
| Connection authentication failed due to a system error that is unlikely to be corrected |
| without intervention. |
| </p> |
| </doc> |
| </choice> |
| <choice name="sys-temp" value="4"> |
| <doc> |
| <p> |
| Connection authentication failed due to a transient system error. |
| </p> |
| </doc> |
| </choice> |
| </type> |
| |
| <definition name="SASL-MAJOR" value="1" label="major protocol version" /> |
| <definition name="SASL-MINOR" value="0" label="minor protocol version" /> |
| <definition name="SASL-REVISION" value="0" label="protocol revision" /> |
| |
| </section> |
| |
| </amqp> |
