Page History

...

This function is a helper function that constructs and sends a SASL PLAIN mechanism frame. As directly sending the frames is no longer the responsibility of the application it is not needed, however it is broadly replaced with pn_transport_set_user_password() which allows the client to set the authentication username and password.

Functions Added

...

• 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)
  void pn_sasl_config_path(pn_sasl_t *sasl, const char *path)
  

...

 *

...

• 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.

...

 *

 * @param[in] sasl the SASL layer

 * @param[in] name the configuration name

...

...

• void pn_sasl_config_

...

• path(pn_sasl_t *sasl, const char *

...

/**

 * Set the sasl configuration path

 *

...

• 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

...

• .

...

 *

 * @param[in] sasl the SASL layer

 * @param[in] path the configuration path

 */

...

Transport

Functions Added

/**

 * 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 sometting 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

 */

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

/** 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.

 *

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

 *

 * @param[in] transport the transport

 *

 * @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.

 */

PN_EXTERN const char *pn_transport_get_user(pn_transport_t *transport);

/**

 * Set the remote FQDN

 *

 * @param[in] transport the transport

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

 */

PN_EXTERN void pn_transport_set_remote_hostname(pn_transport_t *transport, const char* fqdn);

/**

 * 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 TLS or TLS 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] transport the transport

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

 */

PN_EXTERN void pn_transport_require_auth(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 TLS/SSL

 * - Use an SASL with a mechanism that supports saecurity 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);

...