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