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_meta(3)[1]. 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)[2], auth_generic_meta(3)[1].

NOTES

        1. auth_generic_meta(3)
           http://www.courier-mta.org/authlib/auth_generic.html

        2. authlib(3)
           http://www.courier-mta.org/authlib/authlib.html