1SASL client library - draft
2---------------------------
3
4Version: $NetBSD: library.txt,v 1.3 2011/02/11 23:44:42 christos 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