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 through one another (for instance a security layer used by the peers to do authentication may be tunneled through a security layer established for encryption purposes).
The framing and protocol definitions for security layers are expected to be defined
externally to the AMQP specification as in the case of TLS [
To establish a TLS session, each peer MUST start by sending a protocol header before
commencing with TLS negotiation. 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
Other than using a protocol id of two, the exchange of TLS protocol headers follows the same
rules specified in the version negotiation section of the transport specification (See
The following diagram illustrates the interaction involved in creating a TLS security layer:
When the use of the TLS security layer is negotiated, the following rules apply:
The TLS client peer and TLS server peer are determined by the TCP client peer and TCP server peer respectively.
The TLS client peer SHOULD use the server name indication extension as described in
RFC-4366 [
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.
The TLS client MUST validate the certificate presented by the TLS server.
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.
In certain situations, such as connecting through firewalls, it may not be possible to establish a TLS security layer using the above procedure. This might be because a deep packet inspecting firewall sees the first few bytes of the connection 'as not being TLS'.
As an alternative, implementations MAY run a pure TLS server, i.e., one that does not expect
the initial TLS-invoking handshake. The IANA service name for this is amqps and the port is
To establish a SASL layer, 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
Other than using a protocol id of three, the exchange of SASL layer headers follows the same
rules specified in the version negotiation section of the transport specification (See
The following diagram illustrates the interaction involved in creating a SASL security layer:
SASL performatives are framed as per
The maximum size of a SASL frame is defined by
The peer acting as the SASL server must announce supported authentication mechanisms using
the
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.
Advertises the available SASL mechanisms that may be used for authentication.
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 ANONYMOUS. The server mechanisms are ordered in decreasing level of preference.
Selects the sasl mechanism and provides the initial response if needed.
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.
A block of opaque data passed to the security mechanism. The contents of this data are defined by the SASL security mechanism.
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.
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.
This field may already have been specified by the server name indication extension as
described in RFC-4366 [
Send the SASL challenge data as defined by the SASL specification.
Challenge information, a block of opaque binary data passed to the security mechanism.
Send the SASL response data as defined by the SASL specification.
A block of opaque data passed to the security mechanism. The contents of this data are defined by the SASL security mechanism.
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.
A reply-code indicating the outcome of the SASL dialog.
The additional-data field carries additional data on successful authentication outcome
as specified by the SASL specification [
Connection authentication succeeded.
Connection authentication failed due to an unspecified problem with the supplied credentials.
Connection authentication failed due to a system error.
Connection authentication failed due to a system error that is unlikely to be corrected without intervention.
Connection authentication failed due to a transient system error.