auth_sasl, auth_sasl_ex — SASL implementation
#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) ; |
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
.
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.