1.\" Draft of the SASL Client library API. 2.Dd 10 August, 2010 3.Dt LIBSASLC 3 4.Os 5.Sh NAME 6.Nm saslc_alloc , 7.Nm saslc_init , 8.Nm saslc_end , 9.Nm saslc_strerror , 10.Nm saslc_sess_strerror , 11.Nm saslc_sess_init , 12.Nm saslc_sess_end , 13.Nm saslc_sess_setprop , 14.Nm saslc_sess_getprop , 15.Nm saslc_sess_getmech , 16.Nm saslc_sess_cont , 17.Nm saslc_sess_encode , 18.Nm saslc_sess_decode 19.Nd Simple Authentication and Security Layer client library 20.Sh LIBRARY 21.Lb libsaslc 22.Sh SYNOPSIS 23.In saslc.h 24.Ft saslc_t * 25.Fn saslc_alloc "void" 26.Ft int 27.Fn saslc_end "saslc_t *ctx" 28.Ft int 29.Fn saslc_init "saslc_t *ctx" "const char *appname" 30.Ft int 31.Fn saslc_sess_cont "saslc_sess_t *sess" "const void *in" "size_t inlen" \ 32"void* *out" "size_t *outlen" 33.Ft int 34.Fn saslc_sess_decode "saslc_sess_t *sess" "const void *in" "size_t inlen" \ 35"void* *out" "size_t *outlen" 36.Ft int 37.Fn saslc_sess_encode "saslc_sess_t *sess" "const void *in" "size_t inlen" \ 38"void* *out" "size_t *outlen" 39.Ft void 40.Fn saslc_sess_end "saslc_sess_t *sess" 41.Ft const char * 42.Fn saslc_sess_getprop "saslc_sess_t *sess" "const char *name" 43.Ft saslc_sess_t * 44.Fn saslc_sess_init "saslc_t *ctx" "const char *mechs" 45.Ft int 46.Fn saslc_sess_setprop "saslc_sess_t *sess" "const char *name" \ 47"const char *value" 48.Ft const char * 49.Fn saslc_sess_strerror "saslc_sess_t *sess" 50.Ft const char * 51.Fn saslc_sess_strmech "saslc_sess_t *sess" 52.Ft const char * 53.Fn saslc_strerror "saslc_t *ctx" 54.Sh DESCRIPTION 55The 56.Fn saslc_alloc 57function allocates new saslc context. 58.Pp 59The 60.Fn saslc_init 61function initializes sasl context, basing on application name parses 62configuration files, sets up default properties and creates available 63mechanism list for the context. 64.Pp 65The 66.Fn saslc_end 67function destroys and deallocate resources used by the context. Context 68shouldn't have got any sessions assigned to it. 69.Pp 70The 71.Fn saslc_sess_init 72function creates new session assigned to the 73.Ar ctx 74context. Function chooses best mechanism which can be used for an authentication 75from the 76.Ar mechs 77list. 78.Pp 79The 80.Fn saslc_sess_end 81function ends sasl session. 82.Pp 83The 84.Fn saslc_sess_getprop 85function gets property from the session. 86.Pp 87The 88.Fn saslc_sess_setprop 89function sets property for the session. If property already exists in the 90session, then previous value is replaced by the new value. 91.Pp 92.Fn saslc_strerror 93and 94.Fn saslc_sess_strerror 95functions get string description of the last error occurred in context or 96session. 97.Pp 98The 99.Fn saslc_strmech 100function gets mechanism name used in sasl session. 101.Pp 102The 103.Fn saslc_sess_cont 104performs one step of the sasl authentication. Input data of length 105.Ar inlen 106is passed in the 107.Ar in 108argument. Function stores output of length 109.Ar outlen 110in the 111.Ar out. 112Note that user is responsible for freeing resources allocated for the 113.Ar out. 114.Pp 115.Fn saslc_sess_encode 116and 117.Fn saslc_sess_decode 118encode and decode data using method established during the authentication. 119Functions store output of length 120.Ar outlen 121in the 122.Ar out. 123.Pp 124.Sh RETURN VALUES 125Functions 126.Fn saslc_init 127.Fn saslc_end 128.Fn saslc_sess_init 129.Fn saslc_sess_cont 130.Fn saslc_sess_setprop 131.Fn saslc_sess_encode 132and 133.Fn saslc_sess_decode 134return 0 on success and -1 on failure, additionally 135.Fn saslc_cont 136returns 1 if more SASL authentication steps are needed. The 137.Fn saslc_sess_getprop 138function returns the property on success, or NULL on failure. The 139.Fn saslc_alloc 140function returns new context on success, or NULL on failure. Function 141.Fn saslc_strmech 142returns mechanism name. 143Finally, 144.Fn saslc_strerror 145and 146.Fn saslc_sess_strerror 147return pointer to the error description string on success and pointer 148to the "unknown error" string on failure. 149.Sh STANDARDS 150RFC 2195, RFC 2222, RFC 2245, RFC 2595, RFC 2831 151.Sh OTHER IMPLEMENTATIONS 152There exist other SASL client library implementations include Cyrus SASL 153(http://asg.web.cmu.edu/sasl/sasl-library.html) and GNU SASL 154(http://www.gnu.org/software/gsasl/). 155