The Qpid Proton C transport code is responsible for receiving and sending all the protocol bytes into and out of the Proton-C engine. It encapsulates all the protocol processing. Effectively turning the wire level protocol into more abstract AMQP model state changes and vice versa turning AMQP model state changes into wire level protocol to send.

The transport code is divided into 3 layers that divide up the protocol processing:

• SSL
• SASL
• AMQP

Loosely speaking, SSL is mostly associated with encrypting the connection, SASL with authenticating the connection, and of course AMQP carries the actual messaging protocol we're "really" interested in. However despite common knowledge, actually SSL and SSL can both do encryption and authentication of the connection. It's important to note that the SSL and SASL layers are optional in the sense that if authentication and/or encryption are not required then they need not be used - This will be covered further later on.

In the current Proton codebase (0.8) the SSL layer is fairly comprehensively implemented (using the OpenSSL and Windows SChannel implementations) and allows access to both encryption and authentication (although SSL authentication is somewhat complex to set up and use).

Conversely the SASL layer is very rudimentary and essentially punts to the application to handle the SASL protocol interchange. The SASL code does have some built in capability to use the ANONYMOUS mechanism and some code to simplify implementing the PLAIN SASL protocol exchange. Using the Proton-C 0.8 SASL codebase requires the application to directly read the SASL protocol bytes from the peer process them and send raw protocol bytes back to the peer.

I have been re-implementing the SASL layer using the Cyrus-SASL library which supports many SASL mechanisms via a range of plugins (including ANONYMOUS, EXTERNAL, PLAIN, DIGEST-MD5, CRAM-MD5, GSSAPI etc.) and which is extensible to new SASL mechanisms by writing new mechanism plugins.

This work has led me re-evaluate some of the transport API as a whole as well as more specifically the SASL API which more directly needs reworking because of these changes.

Specifically I'd like to somewhat simplify using authentication and encryption with the transport by unifying the most commonly used concepts into the transport code and only requiring delving directly into the SSL/SASL APIs for more complex uses.

API Changes

SASL

The biggest functional changes happen in the SASL layer code where the API has largely changed, very little backwards compatibility has been kept, because it is fairly clear that very few (if any) people have been using the current API to implement their own SASL mechanisms. If this turns out to be untrue, then we could add some further measure of backwards compatibility as required.

Functions Removed

• void pn_sasl_client(pn_sasl_t *sasl)

• void pn_sasl_server(pn_sasl_t *sasl)

These functions have been deprecated

• pn_sasl_state_t pn_sasl_state(pn_sasl_t *sasl)

• size_t pn_sasl_pending(pn_sasl_t *sasl)

• ssize_t pn_sasl_recv(pn_sasl_t *sasl, char *bytes, size_t size)

• ssize_t pn_sasl_send(pn_sasl_t *sasl, const char *bytes, size_t size)

These functions

• void pn_sasl_mechanisms(pn_sasl_t *sasl, const char *mechanisms)

• const char *pn_sasl_remote_mechanisms(pn_sasl_t *sasl)

These functions

• void pn_sasl_plain(pn_sasl_t *sasl, const char *username, const char *password)

This

Functions Added

/** Retrieve the authenticated user

 *

 * This is usually used at the the server end to find the name of the authenticated user.

 * On the client it will merely return whatever user was passed in to the

 * pn_transport_set_user_password() API.

 *

 * If pn_sasl_outcome() returns a value other than PN_SASL_OK, then there will be no user to return.

 * The returned value is only reliable after the PN_TRANSPORT_AUTHENTICATED event has been received.

 *

 * @param[in] sasl the sasl layer

 *

 * @return

 * If the SASL layer was not negotiated then 0 is returned

 * If the ANONYMOUS mechanism is used then the user will be "anonymous"

 * Otherwise a string containing the user is returned.

 */

PN_EXTERN const char *pn_sasl_get_user(pn_sasl_t *sasl);

/** Return the selected SASL mechanism

 *

 * The returned value is only reliable after the PN_TRANSPORT_AUTHENTICATED event has been received.

 *

 * @param[in] sasl the SASL layer

 *

 * @return The authentication mechanism selected by the SASL layer

 */

PN_EXTERN const char *pn_sasl_get_mech(pn_sasl_t *sasl);

/** SASL mechanism that are not to be considered for authentication

 *

 * This can be used on either the client or the server to restrict the SASL mechanisms that may be used.

 *

 * @param[in] sasl the SASL layer

 * @param[in] mechs space separated list of mechanisms that are not to be allowed for authentication

 */

PN_EXTERN void pn_sasl_exclude_mechs(pn_sasl_t *sasl, const char *mechs);

/**

 * Set the sasl configuration name

 *

 * This is used to construct the SASL configuration filename. In the current implementation

 * it ".conf" is added to the name and the file is looked for in the configuration directory.

 *

 * If not set it will default to "proton-server" for a sasl server and "proton-client"

 * for a client.

 *

 * @param[in] sasl the SASL layer

 * @param[in] name the configuration name

 */

PN_EXTERN void pn_sasl_config_name(pn_sasl_t *sasl, const char *name);

/**

 * Set the sasl configuration path

 *

 * This is used to tell SASL where to look for the configuration file.

 * In the current implementation it can be a colon separated list of directories.

 *

 * The environment variable PN_SASL_CONFIG_PATH can also be used to set this path,

 * but if both methods are used then this pn_sasl_config_path() will take precedence.

 *

 * If not set the underlying implementation default will be used.

 * for a client.

 *

 * @param[in] sasl the SASL layer

 * @param[in] path the configuration path

 */

PN_EXTERN void pn_sasl_config_path(pn_sasl_t *sasl, const char *path);

Transport

Functions Added

New Events

Authentication and Encryption Combinations

This table summarises the possible combinations of SSL and SASL use. The implicit assumption of the table is that there is no point in doing double encryption or double authentication so this is not captured in the table. Double encryption would be using both SSL and SASL to encrypt the connection and likewise double authentication would be using both for authentication.

Classically in protocols where SASL was not optional the way to avoid double authentication was to use the EXTERNAL SASL mechanism. With AMQP, SASL is optional, so if SSL is used for client authentication the SASL layer could be entirely omitted and so using EXTERNAL is not necessary.

Similarly in protocols where the SASL layer is not optional the ANONYMOUS mechanism is used when client authentication is not required. With AMQP as the SASL layer can just be entirely omitted, and the SSL layer if present used only for encryption (and server authentication).

In this table "auth" means client authentication.

• Entries in pink aren't allowed/don't make any sense
• All other entries have some use

The numbered boxes are the combinations that are reasonably important:

1. Anonymous, "public" connection
2. Encrypted connection with client certificate
3. Kerberos or DIGEST-MD5
4. Usually SSL encryption with PLAIN authentication.

• All of the SSL encryption possibilities have some use and all could be used to authenticate the server for the client to avoid "man-in-the-middle" attacks.
• The right 2 columns correspond to an encrypted connection
• The bottom 2 rows correspond to an authenticated connection
  

ssize_t pn_sasl_send(pn_sasl_t *sasl, const char *bytes, size_t size)