.\" Draft of the SASL Client library API.
.Dd 10 August, 2010
.Dt LIBSASLC 3
.Os
.Sh NAME
.Nm saslc_alloc ,
.Nm saslc_init ,
.Nm saslc_end ,
.Nm saslc_strerror ,
.Nm saslc_sess_strerror ,
.Nm saslc_sess_init ,
.Nm saslc_sess_end ,
.Nm saslc_sess_setprop ,
.Nm saslc_sess_getprop ,
.Nm saslc_sess_getmech ,
.Nm saslc_sess_cont ,
.Nm saslc_sess_encode ,
.Nm saslc_sess_decode 
.Nd Simple Authentication and Security Layer client library
.Sh LIBRARY
.Lb libsaslc
.Sh SYNOPSIS
.In saslc.h
.Ft saslc_t *
.Fn saslc_alloc "void" 
.Ft int
.Fn saslc_end "saslc_t *ctx"
.Ft int
.Fn saslc_init "saslc_t *ctx" "const char *appname" 
.Ft int
.Fn saslc_sess_cont "saslc_sess_t *sess" "const void *in" "size_t inlen" \
"void* *out" "size_t *outlen" 
.Ft int
.Fn saslc_sess_decode "saslc_sess_t *sess" "const void *in" "size_t inlen" \
"void* *out" "size_t *outlen" 
.Ft int
.Fn saslc_sess_encode "saslc_sess_t *sess" "const void *in" "size_t inlen" \
"void* *out" "size_t *outlen" 
.Ft void
.Fn saslc_sess_end "saslc_sess_t *sess" 
.Ft const char *
.Fn saslc_sess_getprop "saslc_sess_t *sess" "const char *name" 
.Ft saslc_sess_t *
.Fn saslc_sess_init "saslc_t *ctx" "const char *mechs" 
.Ft int
.Fn saslc_sess_setprop "saslc_sess_t *sess" "const char *name" \
"const char *value"
.Ft const char *
.Fn saslc_sess_strerror "saslc_sess_t *sess" 
.Ft const char *
.Fn saslc_sess_strmech "saslc_sess_t *sess" 
.Ft const char *
.Fn saslc_strerror "saslc_t *ctx" 
.Sh DESCRIPTION
The
.Fn saslc_alloc
function allocates new saslc context.
.Pp
The
.Fn saslc_init
function initializes sasl context, basing on application name parses
configuration files, sets up default properties and creates available
mechanism list for the context.
.Pp
The
.Fn saslc_end
function destroys and deallocate resources used by the context. Context
shouldn't have got any sessions assigned to it.
.Pp
The
.Fn saslc_sess_init
function creates new session assigned to the
.Ar ctx
context. Function chooses best mechanism which can be used for an authentication
from the
.Ar mechs
list.
.Pp
The
.Fn saslc_sess_end
function ends sasl session.
.Pp
The
.Fn saslc_sess_getprop
function gets property from the session.
.Pp
The
.Fn saslc_sess_setprop
function sets property for the session. If property already exists in the
session, then previous value is replaced by the new value.
.Pp
.Fn saslc_strerror
and
.Fn saslc_sess_strerror
functions get string description of the last error occurred in context or
session.
.Pp
The
.Fn saslc_strmech
function gets mechanism name used in sasl session.
.Pp
The
.Fn saslc_sess_cont
performs one step of the sasl authentication. Input data of length
.Ar inlen
is passed in the
.Ar in
argument. Function stores output of length 
.Ar outlen
in the
.Ar out.
Note that user is responsible for freeing resources allocated for the
.Ar out.
.Pp
.Fn saslc_sess_encode
and
.Fn saslc_sess_decode
encode and decode data using method established during the authentication.
Functions store output of length
.Ar outlen
in the
.Ar out.
.Pp
.Sh RETURN VALUES
Functions
.Fn saslc_init
.Fn saslc_end
.Fn saslc_sess_init
.Fn saslc_sess_cont
.Fn saslc_sess_setprop
.Fn saslc_sess_encode
and
.Fn saslc_sess_decode
return 0 on success and -1 on failure, additionally
.Fn saslc_cont
returns 1 if more SASL authentication steps are needed. The
.Fn saslc_sess_getprop
function returns the property on success, or NULL on failure. The
.Fn saslc_alloc
function returns new context on success, or NULL on failure. Function
.Fn saslc_strmech
returns mechanism name.
Finally,
.Fn saslc_strerror
and
.Fn saslc_sess_strerror
return pointer to the error description string on success and pointer 
to the "unknown error" string on failure.
.Sh STANDARDS
RFC 2195, RFC 2222, RFC 2245, RFC 2595, RFC 2831
.Sh OTHER IMPLEMENTATIONS
There exist other SASL client library implementations include Cyrus SASL
(http://asg.web.cmu.edu/sasl/sasl-library.html) and GNU SASL
(http://www.gnu.org/software/gsasl/).