1SASL client library - draft 2--------------------------- 3 4Version: $Id: library.txt,v 1.2 2011/01/29 23:35:30 agc Exp $ 5 61. Typedefs 7 8Moved to src/*.h 9 102. Public API 11 12saslc_t *saslc_init(const char *appname); - Function takes appname as an 13argument, function allocates and initializes new saslc_t structure, parses 14configuration files if available (/etc/saslc/appname.d/sasl.conf and then 15/etc/saslc/appname.d/mechanism.conf for machanisms which are listed in 16sasl.conf) Function returns pointer to the saslc_t on success and NULL on 17failure. 18 19const char *saslc_strerror(saslc_t *saslc); - function maps last error 20number in saslc to the message string. Returns pointer to the message string 21on success and pointer to the "unknown error" string on failure. 22 23int saslc_end(saslc_t *saslc); - function destroys SASL library context and 24deallocates any resources used. If any sessions are assigned to the context 25then function closes them. It returns 0 on success and -1 on failure. 26 27saslc_sess_t *saslc_sess_init(saslc_t *saslc, const char *mechs); - Function 28creates a new sasl session. If saslc is NULL then default configuration 29settings are used. Mechs is the string which consists of a comma separated 30list of mechanism names. Mechanism used for the authentication is selected 31basing on the configuration. Function allocates saslc_sess_t and performs 32initialization of saslc_sess_t, pointer to it is returned on success and NULL 33is returned on failure. In case of a failure saslc errno is set. 34 35int saslc_sess_setprop(saslc_sess_t *sess, const char *name, 36 const char *value); - Functions sets a property in the session. This 37function is used for setting i.e. callbacks. It returns 0 on success and -1 38on failure. In case of a failure sess errno is set. 39 40NOTE: Property is added to the sess->prop dictionary. 41NOTE: All properties' names should match to [A-Za-z0-9_]+. 42 43const char *saslc_sess_getprop(saslc_sess_t *sess, const char *name); - 44Function gets property from the session. It return pointer to the property 45value on success and NULL on failure. In case of a failure sess errno is 46set. 47 48NOTE: Property is taken from the sess->prop dictionary, if property not exist 49then sess->context->prop is used with added sess->mech->name."-" prefix. 50 51int saslc_sess_cont(saslc_sess_t *sess, const char *in, size_t inlen, 52 char **out, size_t *outlen); - Function performs one step of the SASL 53authentication. Input data of length inlen is passed in the "in" argument. 54Function stores output of length outlen in the out argument and returns 0 on 55success, 1 if more steps of the SASL authentication is needed and -1 on 56failure. In case of a failure sess errno is set. 57 58NOTE: user is responsible for deallocate the output data. 59IMPLEMENTATION: sess->mech->cont(sess, in, inlen, out, outlen) 60 61const char *saslc_sess_strerror(saslc_sess_t *sess); - function maps last 62error number in sess to message string. Returns pointer to the message string 63on success and pointer to the "unknown error" string on failure. 64 65const char *saslc_sess_strmech(saslc_sess_t *sess); - function returns pointer 66to the string contains name of the mechanism used in session. On failure 67function returns pointer to "unknown". 68 69int saslc_sess_encode(saslc_sess_t *sess, const char *in, size_t inlen, 70 char **out, size_t *outlen); - function encodes data using security layer 71negotiated during the authentication. Returns 0 on success, -1 on failure. In 72case of a failure sess errno is set. 73IMPLEMENTATION: sess->mech->encode(sess, in, inlen, out, outlen) 74 75int saslc_sess_decode(saslc_sess_t *sess, const char *in, size_t inlen, 76 char **out, size_t *outlen); - function decodes data using security layer 77negotiated during the authentication. Returns 0 on success, -1 on failure. In 78case of a failure sess errno is set. 79IMPLEMENTATION: sess->mech->decode(sess, in, inlen, out, outlen) 80 81void saslc_sess_end(saslc_sess_t *sess); - function destroys SASL session and 82deallocates any resources used. 83 843. Mechanisms 85 863.1. Global mechanisms table 87 88saslc_mech_list_t *mechanisms; 89 90List of mechanisms, initialized during first call of saslc_start(...); 91 923.3. Mechanisms implementation 93 94Each mechanism will provide const saslc_mech_t structure describing its 95implementation. Mechanisms state is described by saslc_mech_sess_t, using this 96type by mechanism is not mandatory and different struct can be defined by a 97mechanism if necessary. This structure is used only for representing internal 98state of the mechanism session, and wouldn't be used outside of mechanism 99implementation. 100 1013.2. Mechanisms which are going to be implemented 102 103 * ANONYMOUS (create, destroy, cont) 104 * EXTERNAL (create, destroy, cont) 105 * PLAIN (create, destroy, cont) 106 * LOGIN (create, destroy, cont) 107 * CRAM-MD5 (create, destroy, cont) 108 * DIGEST-MD5 (create, destroy, cont, encode, decode) 109 * GSSAPI (create, destroy, cont, encode, decode) 110 1113.3. Example 112 113 Consider ANONYMOUS mechanism as example, its pseudo implementation looks as 114follows: 115 116generic_create(...) { 117 // create mech_sess structure 118 // mech_sess->status = AUTHENTICATION 119} 120 121anon_cont(...) { 122 char *token; 123 124 if ( mech_sess->status != AUTHENTICATION ) { 125 // error handler 126 } 127 128 // get token from session if present, if not use default from 129 // configuration 130 131 // output = token, outlen = lenght(token) 132 // mech_sess->status = AUTHENTICATED... 133 // return 0; 134} 135 136generic_destroy(...) { 137 // destroy mech_sess structure 138 // return 139} 140 141saslc_mech_t anon_mech = { 142 "ANONYMOUS", // const char *name; 143 FLAG_ANONYMOUS, /* mechanism flags */ 144 mech_generic_create; /* create function - creates mechanism 145 instance */ 146 mech_anonymous_cont; /* step function - performs one step of 147 authentication */ 148 NULL; /* encoding function - encodes input 149 according to negotiated security layer */ 150 NULL; /* decoding function - decodes input 151 according to negotiated security layer */ 152 mech_generic_destroy; /* destroy function - destroys mechanism 153 instance */ 154} mech_anonymous; 155 156 1574. Expected usage 158 159Below is presented example and expected usage of the library. 160 161/* creating context */ 162... 163ctx = saslc_init("example"); 164 165if ( ctx == NULL ) { 166 //error handler 167} 168... 169 170 171/* session */ 172sess = saslc_sess_init(ctx, "PLAIN,ANONYMOUS"); 173 174if ( sess == NULL ) { 175 //error handler 176} 177 178if ( strcmp(saslc_sess_strmech(sess),"PLAIN") == 0 ) { 179 saslc_sess_setprop(sess, "USERID", "foo"); 180 saslc_sess_setprop(sess, "PASSWORD", "bar"); 181} else if ( strcmp(saslc_sess_strmech(sess),"ANONYMOUS") == 0 ) { 182 saslc_sess_setprop(sess, "TOKEN", "foo@bar.com"); 183} 184 185// sending auth 186// proto read 187// parse 188 189while ( (last = sasl_sess_cont(sess, in, inlen, out, outlen)) >= 0 ) { 190 // proto send 191 // proto read 192 // parse 193 194 if ( last == 0 ) 195 break; 196} 197 198if ( last == 0 ) { 199 // yay! 200} else { 201 // error handler 202} 203 204... 205/* destroying session and context */ 206saslc_sess_end(sess); 207saslc_end(ctx); 208... 209 210vim:tw=79:spell:spelllang=en 211