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)[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(3)[1].
NOTES¶
- 1.
- auth_generic(3)
auth_generic.html
- 2.
- authlib(3)
authlib.html