resources/security.xml
<?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>