auth_sasl

## Name

auth_sasl, auth_sasl_ex — SASL implementation

## Synopsis

#include <courierauthsasl.h>

`int rc=auth_sasl(` | const char * | method,
| const char * | initialresponse,
| char * | (*conversation_func)`(`const char *, void *)`)`,
| void * | callback_arg,
| char ** | authtype_ret,
| char ** | authdata_ret`)`;

`int rc=auth_sasl_ex(` | const char * | method,
| const char * | initialresponse,
| const char * | externalauth,
| char * | (*conversation_func)`(`const char *, void *)`)`,
| void * | callback_arg,
| char ** | authtype_ret,
| char ** | authdata_ret`)`;

## DESCRIPTION

`auth_sasl` is a generic SASL server implementation. `method` is the requested SASL method. At this time `auth_sasl` knows how to handle the following SASL methods:

- `LOGIN`

- `PLAIN`

- `CRAM-MD5`

- `CRAM-SHA1`

`initialresponse` is a base64-encoded initial response provided in the client's SASL request. `initialresponse` must be `NULL` if an initial response was not included in the client's SASL request.

`conversation_func` is the application-implemented SASL conversation callback function. `conversation_func` receives a base64-encoded SASL prompt, and the `callback_arg` argument to `auth_sasl`. `conversation_func` must return a buffer containing the base64-encoded reply from the client. `auth_sasl` will free(3) this buffer when it's done. `conversation_func` should return `NULL` to abort the SASL conversation.

`auth_sasl_ex` is a version of `auth_sasl` that recognizes the `EXTERNAL` SASL method. It takes an extra parameter, `externalauth`. This parameter should be set to indicate an login that was authenticated via some other means, such as, perhaps, an SSL certificate, or `NULL` if no externally-authenticated identity was established.

If `method` is not `EXTERNAL`, `auth_sasl_ex` is identical to `auth_sasl`, and `externalauth` is ignored. Otherwise, if `method` is `EXTERNAL` and `externalauth` is not `NULL`, `auth_sasl_ex` returns `AUTHSASL_OK`, and sets `*authtype_ret` and `*authdata_ret` accordingly, so that the subsequent invocation of `auth_generic`() returns authentication information for the login ID specified by `externalauth`.

## RETURNS

If the SASL conversation succesfully completes, `auth_sasl` or `auth_sasl_ex` initializes `*authtype_ret` and `*authdata_ret`. They will be set to a malloc(3)-ed buffers that can be directly passed as arguments to auth_generic(3). It is the application's responsibility to free(3) these buffers when it's done with them.

`auth_sasl` or `auth_sasl_ex` returns `AUTHSASL_OK` when the SASL conversation succesfully completes, and `*authtype_ret` and `*authdata_ret` are succesfully assembled. Any other return indicates an error condition. Right now two error conditions are defined:

`AUTHSASL_ABORTED`

  The SASL conversation was aborted by the client.

`AUTHSASL_ERROR`

  General error (insufficient memory, or some other reason). Check `errno` for any clues.

## SEE ALSO

authlib(3), auth_generic(3).