SASL mechanism types and functions. A SASL mechanism is an implementation specification for a particular authentication mechanism. To perform the authentication, a mechanism instance needs to be instantiated and have its evaluate method called one or more times with appropriate data and a completion callback, which will be called by the mechanism to indicate the results of the authentication sequence. More...

#include "util/htable.h"
#include "dom.h"

Data Structures
struct	_jw_sasl_mech_fn_table

Typedefs
typedef struct _jw_sasl_mech	jw_sasl_mech

typedef struct _jw_sasl_mech_instance	jw_sasl_mech_instance

typedef bool(*	jw_sasl_mech_init_fn) (jw_sasl_mech_instance instance, jw_htable config, jw_err *err)

typedef void(*	jw_sasl_mech_clean_fn) (jw_sasl_mech_instance *instance)

typedef void(*	jw_sasl_mech_evaluate_complete_fn) (jw_sasl_mech_instance instance, jw_dom_node out_auth_node, bool done, jw_sasl_error sasl_err, void *arg)

typedef void(*	jw_sasl_mech_cdata_evaluate_complete_fn) (jw_sasl_mech_instance instance, uint8_t out, size_t out_len, bool needs_base64_encoding, bool done, jw_sasl_error sasl_err)

typedef bool(*	jw_sasl_mech_cdata_evaluate_fn) (jw_sasl_mech_instance instance, uint8_t in, size_t in_len, jw_sasl_mech_cdata_evaluate_complete_fn cb, jw_err *err)

typedef struct _jw_sasl_mech_fn_table	jw_sasl_mech_fn_table

Enumerations
enum	jw_sasl_error { JW_SASL_ERR_NONE = 0, JW_SASL_ERR_ABORTED = 1, JW_SASL_ERR_ACCOUNT_DISABLED = 2, JW_SASL_ERR_CREDENTIALS_EXPIRED = 3, JW_SASL_ERR_ENCRYPTION_REQUIRED = 4, JW_SASL_ERR_INCORRECT_ENCODING = 5, JW_SASL_ERR_INVALID_AUTHZID = 6, JW_SASL_ERR_INVALID_MECHANISM = 7, JW_SASL_ERR_MALFORMED_REQUEST = 8, JW_SASL_ERR_MECHANISM_TOO_WEAK = 9, JW_SASL_ERR_NOT_AUTHORIZED = 10, JW_SASL_ERR_TEMPORARY_AUTH_FAILURE = 11 }

Functions
JABBERWERX_API bool	jw_sasl_mech_create (const char name, jw_sasl_mech_fn_table fn_table, jw_sasl_mech *mech, jw_err err)

JABBERWERX_API bool	jw_sasl_mech_plain_create (jw_htable config, jw_sasl_mech mech, jw_err err)

JABBERWERX_API bool	jw_sasl_mech_external_create (jw_htable config, jw_sasl_mech mech, jw_err err)

JABBERWERX_API bool	jw_sasl_mech_copy (jw_sasl_mech mech, jw_sasl_mech copy, jw_err err)

JABBERWERX_API void	jw_sasl_mech_destroy (jw_sasl_mech *mech)

JABBERWERX_API const char *	jw_sasl_mech_get_name (jw_sasl_mech *mech)

JABBERWERX_API bool	jw_sasl_mech_instance_create (jw_htable config, jw_sasl_mech mech, jw_sasl_mech_instance *instance, jw_err err)

JABBERWERX_API void	jw_sasl_mech_instance_destroy (jw_sasl_mech_instance *instance)

JABBERWERX_API bool	jw_sasl_mech_instance_evaluate (jw_sasl_mech_instance instance, jw_dom_node in_auth_node, jw_sasl_mech_evaluate_complete_fn cb, void arg, jw_err err)

JABBERWERX_API jw_sasl_mech *	jw_sasl_mech_instance_get_mech (jw_sasl_mech_instance *instance)

JABBERWERX_API void	jw_sasl_mech_instance_set_data (jw_sasl_mech_instance instance, void data)

JABBERWERX_API void *	jw_sasl_mech_instance_get_data (jw_sasl_mech_instance *instance)

Detailed Description

SASL mechanism types and functions. A SASL mechanism is an implementation specification for a particular authentication mechanism. To perform the authentication, a mechanism instance needs to be instantiated and have its evaluate method called one or more times with appropriate data and a completion callback, which will be called by the mechanism to indicate the results of the authentication sequence.

Copyrights

Typedef Documentation

typedef struct _jw_sasl_mech jw_sasl_mech

A SASL mechanism implementation specification

typedef void(* jw_sasl_mech_cdata_evaluate_complete_fn) (jw_sasl_mech_instance *instance, uint8_t *out, size_t out_len, bool needs_base64_encoding, bool done, jw_sasl_error sasl_err)

Callback function called by the mechanism when data evaluation is complete. The implementor of this function must take ownership of the out parameter and free it after it has been processed.

Invariant: NULL != instance

Parameters

[in]	instance	the mechanism instance
[in]	out	The bytes produced by the mechanism to be sent to the remote endpoint. The encoding of the bytes is mechanism-specific. May be NULL. If not NULL, it will be freed with jw_data_free().
[in]	out_len	The number of bytes pointed to by out. If out is NULL, this must be 0.
[in]	needs_base64_encoding	true if out needs to be base64-encoded before transport
[in]	done	true if the authentication sequence is complete or has encountered an unrecoverable error
[in]	sasl_err	the SASL error code (JW_SASL_ERR_NONE on success)

typedef bool(* jw_sasl_mech_cdata_evaluate_fn) (jw_sasl_mech_instance *instance, uint8_t *in, size_t in_len, jw_sasl_mech_cdata_evaluate_complete_fn cb, jw_err *err)

Function called to submit data for evaluation by the mechanism. The implementor of this function must take ownership of the in parameter and free it after it has been processed.

If returning false, implementors must set err to an appropriate value.

Invariant: NULL != instance; NULL != cb

Parameters

[in]	instance	the mechanism instance
[in]	in	The bytes submitted to the mechanism. The encoding of the bytes is mechanism-specific, but will be base64-decoded and NULL-terminated. May be NULL. If not NULL, it will be freed with jw_data_free() when this function returns true.
[in]	in_len	The number of bytes pointed to by in. If in is NULL, this must be 0.
[in]	cdata_cb	the data evaluation completion callback
[out]	err	the error information (provide NULL to ignore)

Return values

bool	true if the completion callback is guaranteed to execute

typedef void(* jw_sasl_mech_clean_fn) (jw_sasl_mech_instance *instance)

Function called when a mechanism instance is destroyed. If the mechanism has allocated any memory and stored it via jw_sasl_mech_instance_set_data(), this is the place to clean it up.

Invariant: NULL != instance

Parameters

[in] instance the mechanism instance

typedef void(* jw_sasl_mech_evaluate_complete_fn) (jw_sasl_mech_instance *instance, jw_dom_node *out_auth_node, bool done, jw_sasl_error sasl_err, void *arg)

Callback function called by the sasl framework when data evaluation is complete. The implementor of this function must not destroy the context of out_auth_node unless, of course, jw_dom_context_retain() is also called.

Invariant: NULL != instance

Parameters

[in]	instance	the mechanism instance
[in]	out_auth_node	The node to send to the remote endpoint. May be NULL.
[in]	done	true if the authentication sequence is complete or has encountered an unrecoverable error
[in]	sasl_err	the SASL error code (JW_SASL_ERR_NONE on success)
[in]	arg	the user-provided argument to jw_sasl_instance_evaluate()

typedef struct _jw_sasl_mech_fn_table jw_sasl_mech_fn_table

Mechanism implementation function table

typedef bool(* jw_sasl_mech_init_fn) (jw_sasl_mech_instance *instance, jw_htable *config, jw_err *err)

Function called when a mechanism instance is created. Implementors of this function MUST NOT take ownership of the config object.

If returning false, implementors must set err to an appropriate value.

Invariant: NULL != instance

Parameters

[in]	instance	the mechanism instance
[in]	config	A collection of configuration options. This config table may be shared with other objects, so any elements that a mechanism uses or adds should have names with a unique prefix.
[out]	err	the error information (provide NULL to ignore)

Return values

bool	true if the mechanism was initialized successfully

typedef struct _jw_sasl_mech_instance jw_sasl_mech_instance

An instance of a SASL mechanism implementation specification

Enumeration Type Documentation

enum jw_sasl_error

SASL error codes defined in RFC 6120 (section 6.5)

Function Documentation

JABBERWERX_API bool jw_sasl_mech_copy	(	jw_sasl_mech *	mech,
		jw_sasl_mech **	copy,
		jw_err *	err
	)

Copy a SASL mechanism implementation specification.

This function can generate the following errors (set when returning false):

JW_ERR_NO_MEMORY if the mechanism could not be allocated.

Invariant: NULL != mech; NULL != copy

Parameters

[in]	mech	the mechanism specification to copy
[out]	copy	the newly-created mechanism
[out]	err	the error information (provide NULL to ignore)

Return values

bool	true if the mechanism was copied successfully

JABBERWERX_API bool jw_sasl_mech_create	(	const char *	name,
		jw_sasl_mech_fn_table *	fn_table,
		jw_sasl_mech **	mech,
		jw_err *	err
	)

Create a SASL mechanism implementation specification.

Requirements for SASL mechanism names are specified in RFC 4422, section 3.1:

SASL mechanisms are named by character strings, from 1 to 20 characters in length, consisting of ASCII [ASCII] uppercase letters, digits, hyphens, and/or underscores.

This function can generate the following errors (set when returning false):

JW_ERR_NO_MEMORY if the mechanism could not be allocated.
JW_ERR_INVALID_ARG if name is badly formed or if fn_table->evaluate_start_fn is NULL.

Invariant: NULL != name; NULL != fn_table; NULL != mech

Parameters

[in]	name	the mechanism name. This pointer is stored and used internally over the lifetime of the mechanism, and so must not be changed after being submitted here. It is not freed when the mechanism is destroyed. The suggested pattern here is to pass in a static string.
[in]	fn_table	the mechanism implementation function table
[out]	mech	the newly-created mechanism
[out]	err	the error information (provide NULL to ignore)

Return values

bool	true if the mechanism was created successfully

JABBERWERX_API void jw_sasl_mech_destroy ( jw_sasl_mech * mech )

Destroy a SASL mechanism.

NOTE: This function does not destroy the config passed to create().

Parameters

[in] mech The mechanism to clean up

JABBERWERX_API bool jw_sasl_mech_external_create	(	jw_htable *	config,
		jw_sasl_mech **	mech,
		jw_err *	err
	)

Create a default SASL EXTERNAL mechanism implementation specification.

This function can generate the following errors (set when returning false):

JW_ERR_NO_MEMORY if the mechanism could not be allocated.

Invariant: NULL != mech

Parameters

[in]	config	A collection of configuration options. No options are currently defined for jw_sasl_mech_external_create. For the time being, this parameter can be NULL.
[out]	mech	the newly-created mechanism
[out]	err	the error information (provide NULL to ignore)

Return values

bool	true if the mechanism was created successfully

JABBERWERX_API const char* jw_sasl_mech_get_name ( jw_sasl_mech * mech )

Get the name of the given mechanism.

Invariant: mech != NULL

Return values

const char* the mechanism name

JABBERWERX_API bool jw_sasl_mech_instance_create	(	jw_htable *	config,
		jw_sasl_mech *	mech,
		jw_sasl_mech_instance **	instance,
		jw_err *	err
	)

Create a SASL mechanism instance.

For mechanisms managed by a jw_sasl_factory, this function will normally be called by one of the get_best_mech() functions.

This function can generate the following errors (set when returning false):

JW_ERR_NO_MEMORY if the mechanism could not be allocated
any other error that is returned from the mechanism's init_fn

Invariant: NULL != mech; NULL != instance

Parameters

[in]	config	A collection of configuration options that are passed through to the mechanism's init_fn. This function does not require the parameter to be non-NULL, but the mechanism's init_fn might.
[in]	mech	the mechanism specification to instantiate
[out]	instance	the newly-created mechanism instance
[out]	err	the error information (provide NULL to ignore)

Return values

bool	true if the mechanism instance was created successfully

JABBERWERX_API void jw_sasl_mech_instance_destroy ( jw_sasl_mech_instance * instance )

Destroy a SASL mechanism instance.

NOTE: This function does not destroy the config passed to create().

Invariant: NULL != instance

Parameters

[in] instance The mechanism instance to clean up

JABBERWERX_API bool jw_sasl_mech_instance_evaluate	(	jw_sasl_mech_instance *	instance,
		jw_dom_node *	in_auth_node,
		jw_sasl_mech_evaluate_complete_fn	cb,
		void *	arg,
		jw_err *	err
	)

Submit an authentication node for evaluation by the mechanism. This function does not take ownership of the submitted node.

This function can generate the following errors (set when returning false):

JW_ERR_INVALID_ARG if the give node is not relevant to the SASL authentication sequence
JW_ERR_INVALID_STATE if the callback from a previous call to this function has not yet been called
JW_ERR_NO_MEMORY if there is not enough memory to complete this operation
any other error that is returned from the mechanism's evaluate_fn

Note that if this is not the first call to evaluate and the mechanism's evaluate_step_fn is not defined, a default SASL error will be returned to the completion callback.

Invariant: NULL != instance; NULL != cb

Parameters

[in]	instance	the mechanism instance
[in]	in_auth_node	The node submitted to the mechanism. The encoding of any text elements is mechanism-specific. May be NULL, such as when the client is sending the initial authentication request.
[in]	cb	the completion callback
[in]	arg	the opaque argument that will be passed to cb
[out]	err	the error information (provide NULL to ignore)

Return values

bool	true if the completion callback is guaranteed to execute

JABBERWERX_API void* jw_sasl_mech_instance_get_data ( jw_sasl_mech_instance * instance )

Gets the opaque data blob.

Invariant: NULL != instance

Parameters

[in] instance the mechanism instance

Return values

void* the opaque data blob

JABBERWERX_API jw_sasl_mech* jw_sasl_mech_instance_get_mech ( jw_sasl_mech_instance * instance )

Gets the mechanism specification for this instance.

Invariant: NULL != instance

Parameters

[in] instance the mechanism instance

Return values

jw_sasl_mech the mechanism specification

JABBERWERX_API void jw_sasl_mech_instance_set_data	(	jw_sasl_mech_instance *	instance,
		void *	data
	)

Sets an opaque data blob. This function is intended for use only by the mechanism implementation, which can use it to store state.

Invariant: NULL != instance

Parameters

[in]	instance	the mechanism instance
[in]	data	the opaque data blob

JABBERWERX_API bool jw_sasl_mech_plain_create	(	jw_htable *	config,
		jw_sasl_mech **	mech,
		jw_err *	err
	)

Create a default SASL PLAIN mechanism implementation specification.

This function can generate the following errors (set when returning false):

JW_ERR_NO_MEMORY if the mechanism could not be allocated.

Invariant: NULL != mech

Parameters

[in]	config	A collection of configuration options. No options are currently defined for jw_sasl_mech_plain_create. For the time being, this parameter can be NULL.
[out]	mech	the newly-created mechanism
[out]	err	the error information (provide NULL to ignore)

Return values

bool	true if the mechanism was created successfully

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation