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.

...

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 SASL 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 in more detail 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).

...

From the authentication point of view the API flow is much simpler than before:

Instead of the current Proton-C 0.8 situation where the application has to directly read and write AMQP SASL frames using pn_sasl_recv(), pn_sasl_send() etc. the meat of the protocol interchange happens behind the scenes and instead ; the application only has to set up authentication parameters, and then allow the protocol handling loop Proton-C to handle SASL without application intervention.

...

By default the server will adapt to whatever layers the client attempts uses to use to communicate. But the server application can specify that the connection must be encrypted or authenticated (using pn_transport_require_encryption() and pn_transport_require_auth() ). Also if required the server application can force the SASL layer to use the ANONYMOUS mechanism or to exclude some mechanisms that might be installed on the system (by using pn_sasl_force_anonymous() or pn_sasl_exclude_mechs() ). The location and name of the configuration file used by the SASL implementation can be changed by using the pn_sasl_config_name() and pn_sasl_config_path() APIs.

...

• const char *pn_sasl_get_user(pn_sasl_t *sasl)
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 pn_transport_set_user_password().
  The returned value is only reliable after the PN_TRANSPORT_AUTHENTICATED event has been received. 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 authenticated user is returned.
• const char *pn_sasl_get_mech(pn_sasl_t *sasl)
  Return the selected SASL mechanism: The returned value is only reliable after the PN_TRANSPORT_AUTHENTICATED event has been received.
• void pn_sasl_exclude_mechs(pn_sasl_t *sasl, const char *mechs)
Specify SASL mechanisms 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.
  Multiple  mechanisms to exclude are space separated in the string that is passed into this function.
• void pn_sasl_force_anonymous(pn_sasl_t *sasl)
  This is used on either server or client to setup the SASL layer so that it will pre-emptively assume the ANONYMOUS mechanism and immediately send the appropriate frames without needing to do any actual authentication.
  However an important note is that if this is set on  a client and the connected server really does require authentication then the server will fail and disconnect the connection with no useful feedback to the application as the SASL layer state will already be assuming it has authenticated. Conversely if this is set on a server the client will only be offered the ANONYMOUS mechanism and if it does not support that mechanism it will disconnect.
• void pn_sasl_config_name(pn_sasl_t *sasl, const char *name)
  This is used to construct the SASL configuration filename. In the current implementation ".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.
• void pn_sasl_config_path(pn_sasl_t *sasl, const char *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.

Transport

Functions Added

/**

...

• void pn_transport_set_user_password(pn_transport_t *transport, const char *user, const char* password)

• Set the authentication username and password for a client transport

...

...

• If not set then no authentication will be negotiated unless the client

...

• sasl layer is explicitly created (this would be for

...

• something like Kerberos

...

• where the credentials are implicit in the environment, or to explicitly use

...

• the ANONYMOUS SASL mechanism)

...

 *

 * @param[in] transport the transport

 * @param[in] user the username

 * @param[in] password the password corresponding to the username - this will be copied and zeroed out after use

 */

• .

• const char *

...

• pn_transport_

...

• get_user

...

• (pn_transport_t *transport

...

• )

...

 *

• 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

...

• pn_transport_set_user_password()

...

• .

 *

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

...

 *

...

 *

 * @return

• If a the user is anonymous (either no SASL layer is negotiated or the SASL ANONYMOUS mechanism is used)

...

• then the user will be "anonymous"

...

• , otherwise a string containing the user is returned.

 */

• void pn_transport_

...

• set_remote_

...

• hostname(pn_transport_t *transport, const char* fqdn)

...

/**

 * Set the remote FQDN

 *

 * @param[in] transport the transport

 * @param[in] fqdn the remotes Fully qualified domain name

 */

...

• 
  Used on the client to set the fully qualified domain name of the server we are connecting to. This is used to authenticate that we are indeed connected to this host if the SASL mechanism supports it or if we are using SSL.

• void pn_transport_

...

• require_

...

/**

...

• auth(pn_transport_t *transport,

...

• bool required)

• Set whether a non authenticated transport connection is allowed

...

• .

...

• There are several ways within the AMQP protocol suite to get unauthenticated connections:

...

• • Use no SASL layer (with either no

...

• • SSL or

...

• • SSL without client certificates)

...

• • Use an SASL layer but the ANONYMOUS mechanism

...

...

The default if this option is not set is to allow unauthenticated connections.

...

 * @param[in] required boolean is true when authenticated connections are required

 */

...

• void pn_transport_require_

...

• encryption(pn_transport_t *transport, bool required)

...

/**

...

• Set whether a non encrypted transport connection is allowed.
  

 *

...

• There are several ways within the AMQP protocol suite to get encrypted connections:

  ...

  • • Use

  ...

  • • SSL

  ...

  • • Use

  ...

  • • SASL with a mechanism that supports

  ...

  • • security layers

   *

  ...

  • The default if this option is not set is to allow unencrypted connections.

   

  ...

   * @param[in] transport the transport

   * @param[in] required boolean is true when encrypted connections are required

   */

  PN_EXTERN void pn_transport_require_encryption(pn_transport_t *transport, bool required);

  New Events

  • PN_TRANSPORT_AUTHENTICATED
    This event is sent when a server successfully authenticates a client connection (or when it accepts an unauthenticated connection that does not need to be authenticated).On the client it is sent when the client successfully authenticates to the server. If encryption is configured for the connection, it will be also be established by the point at which this event is received. If the authentication or encryption handshake is unsuccessful then both server and client applications will receive a PN_TRANSPORT_ERROR event.

  New Events

  • PN_TRANSPORT_AUTHENTICATED

  Authentication and Encryption Combinations

  ...