gsasl-mech.h: GNU SASL Reference Manual

gsasl-mech.h

gsasl-mech.h — register new application-defined mechanism

Functions

int	(*Gsasl_init_function) ()
void	(*Gsasl_done_function) ()
int	(*Gsasl_start_function) ()
int	(*Gsasl_step_function) ()
void	(*Gsasl_finish_function) ()
int	(*Gsasl_code_function) ()
int	gsasl_register ()

Types and Values

struct	Gsasl_mechanism_functions
struct	Gsasl_mechanism

Description

The builtin mechanisms should suffice for most applications. Applications can register a new mechanism in the library using application-supplied functions. The mechanism will operate as the builtin mechanisms, and the supplied functions will be invoked when necessary. The application uses the normal logic, e.g., calls gsasl_client_start() followed by a sequence of calls to gsasl_step() and finally gsasl_finish().

Functions

Gsasl_init_function ()

int
(*Gsasl_init_function) (Gsasl *ctx);

The implementation of this function pointer should fail if the mechanism for some reason is not available for further use.

Parameters

ctx

a Gsasl libgsasl handle.

Returns

Returns GSASL_OK iff successful.

Gsasl_done_function ()

void
(*Gsasl_done_function) (Gsasl *ctx);

The implementation of this function pointer deallocate all resources associated with the mechanism.

Parameters

ctx

a Gsasl libgsasl handle.

Gsasl_start_function ()

int
(*Gsasl_start_function) (Gsasl_session *sctx,
                         void **mech_data);

The implementation of this function should start a new authentication process.

Parameters

sctx	a `Gsasl_session` session handle.
mech_data	pointer to void* with mechanism-specific data.

Returns

Returns GSASL_OK iff successful.

Gsasl_step_function ()

int
(*Gsasl_step_function) (Gsasl_session *sctx,
                        void *mech_data,
                        const char *input,
                        size_t input_len,
                        char **output,
                        size_t *output_len);

The implementation of this function should perform one step of the authentication process.

This reads data from the other end (from input and input_len ), processes it (potentially invoking callbacks to the application), and writes data to server (into newly allocated variable output and output_len that indicate the length of output ).

The contents of the output buffer is unspecified if this functions returns anything other than GSASL_OK or GSASL_NEEDS_MORE. If this function return GSASL_OK or GSASL_NEEDS_MORE, however, the output buffer is allocated by this function, and it is the responsibility of caller to deallocate it by calling gsasl_free(output ).

Parameters

sctx	a `Gsasl_session` session handle.
mech_data	pointer to void* with mechanism-specific data.
input	input byte array.
input_len	size of input byte array.
output	newly allocated output byte array.
output_len	pointer to output variable with size of output byte array.

Returns

Returns GSASL_OK if authenticated terminated successfully, GSASL_NEEDS_MORE if more data is needed, or error code.

Gsasl_finish_function ()

void
(*Gsasl_finish_function) (Gsasl_session *sctx,
                          void *mech_data);

The implementation of this function should release all resources associated with the particular authentication process.

Parameters

sctx	a `Gsasl_session` session handle.
mech_data	pointer to void* with mechanism-specific data.

Gsasl_code_function ()

int
(*Gsasl_code_function) (Gsasl_session *sctx,
                        void *mech_data,
                        const char *input,
                        size_t input_len,
                        char **output,
                        size_t *output_len);

The implementation of this function should perform data encoding or decoding for the mechanism, after authentication has completed. This might mean that data is integrity or privacy protected.

The output buffer is allocated by this function, and it is the responsibility of caller to deallocate it by calling gsasl_free(output ).

Parameters

sctx	a `Gsasl_session` session handle.
mech_data	pointer to void* with mechanism-specific data.
input	input byte array.
input_len	size of input byte array.
output	newly allocated output byte array.
output_len	pointer to output variable with size of output byte array.

Returns

Returns GSASL_OK if encoding was successful, otherwise an error code.

gsasl_register ()

int
gsasl_register (Gsasl *ctx,
                const Gsasl_mechanism *mech);

This function initialize given mechanism, and if successful, add it to the list of plugins that is used by the library.

Parameters

ctx	pointer to libgsasl handle.
mech	plugin structure with information about plugin.

Returns

GSASL_OK iff successful, otherwise GSASL_MALLOC_ERROR.

Since: 0.2.0

Types and Values

struct Gsasl_mechanism_functions

struct Gsasl_mechanism_functions {
  Gsasl_init_function init;
  Gsasl_done_function done;
  Gsasl_start_function start;
  Gsasl_step_function step;
  Gsasl_finish_function finish;
  Gsasl_code_function encode;
  Gsasl_code_function decode;
};

Holds all function pointers to implement a mechanism, in either client or server mode.

Members

Gsasl_init_function `init`;	a `Gsasl_init_function()`.
Gsasl_done_function `done`;	a `Gsasl_done_function()`.
Gsasl_start_function `start`;	a `Gsasl_start_function()`.
Gsasl_step_function `step`;	a `Gsasl_step_function()`.
Gsasl_finish_function `finish`;	a `Gsasl_finish_function()`.
Gsasl_code_function `encode`;	a `Gsasl_code_function()`.
Gsasl_code_function `decode`;	a `Gsasl_code_function()`.

struct Gsasl_mechanism

struct Gsasl_mechanism {
  const char *name;

  struct Gsasl_mechanism_functions client;
  struct Gsasl_mechanism_functions server;
};

Holds all implementation details about a mechanism.

Members

const char *`name`;	string holding name of mechanism, e.g., "PLAIN".
struct Gsasl_mechanism_functions `client`;	client-side Gsasl_mechanism_functions structure.
struct Gsasl_mechanism_functions `server`;	server-side Gsasl_mechanism_functions structure.