1/*
2 * Copyright 2003 Sun Microsystems, Inc.  All rights reserved.
3 * Use is subject to license terms.
4 */
5
6/* saslplug.h --  API for SASL plug-ins */
7
8#ifndef	_SASL_SASLPLUG_H
9#define	_SASL_SASLPLUG_H
10
11#pragma ident	"%Z%%M%	%I%	%E% SMI"
12
13#ifndef	_SASL_SASL_H
14#include <sasl/sasl.h>
15#endif
16
17#ifndef _MD5_H
18#include <md5.h>
19#endif /* _MD5_H */
20
21#ifdef	__cplusplus
22extern "C" {
23#endif
24
25/* intermediate MD5 context */
26typedef struct HMAC_MD5_CTX_s {
27    MD5_CTX ictx, octx;
28} HMAC_MD5_CTX;
29
30/*
31 * intermediate HMAC state
32 *  values stored in network byte order (Big Endian)
33 */
34typedef struct HMAC_MD5_STATE_s {
35    uint32_t istate[4];
36    uint32_t ostate[4];
37} HMAC_MD5_STATE;
38
39/*
40 * callback to lookup a sasl_callback_t for a connection
41 * input:
42 *  conn        -- the connection to lookup a callback for
43 *  callbacknum -- the number of the callback
44 * output:
45 *  pproc       -- pointer to the callback function (set to NULL on failure)
46 *  pcontext    -- pointer to the callback context (set to NULL on failure)
47 * returns:
48 *  SASL_OK -- no error
49 *  SASL_FAIL -- unable to find a callback of the requested type
50 *  SASL_INTERACT -- caller must use interaction to get data
51 */
52typedef int sasl_getcallback_t(sasl_conn_t *conn,
53				unsigned long callbackid,
54				int (**pproc)(),
55				void **pcontext);
56
57/*
58 * The sasl_utils structure will remain backwards compatible unless
59 * the SASL_*_PLUG_VERSION is changed incompatibly
60 * higher SASL_UTILS_VERSION numbers indicate more functions are available
61 */
62#define	SASL_UTILS_VERSION 4
63
64/* utility function set for plug-ins */
65typedef struct sasl_utils {
66    int version;
67
68	/* contexts */
69    sasl_conn_t *conn;
70    sasl_rand_t *rpool;
71    void *getopt_context;
72
73	/* option function */
74    sasl_getopt_t *getopt;
75
76	/* allocation functions: */
77    sasl_malloc_t *malloc;
78    sasl_calloc_t *calloc;
79    sasl_realloc_t *realloc;
80    sasl_free_t *free;
81
82	/* mutex functions: */
83    sasl_mutex_alloc_t *mutex_alloc;
84    sasl_mutex_lock_t *mutex_lock;
85    sasl_mutex_unlock_t *mutex_unlock;
86    sasl_mutex_free_t *mutex_free;
87
88	/* MD5 hash and HMAC functions */
89    void (*MD5Init)(MD5_CTX *);
90    void (*MD5Update)(MD5_CTX *, const unsigned char *text, unsigned int len);
91    void (*MD5Final)(unsigned char [16], MD5_CTX *);
92    void (*hmac_md5)(const unsigned char *text, int text_len,
93			const unsigned char *key, int key_len,
94			unsigned char [16]);
95    void (*hmac_md5_init)(HMAC_MD5_CTX *, const unsigned char *key, int len);
96	/* hmac_md5_update() is just a call to MD5Update on inner context */
97    void (*hmac_md5_final)(unsigned char [16], HMAC_MD5_CTX *);
98    void (*hmac_md5_precalc)(HMAC_MD5_STATE *,
99				const unsigned char *key, int len);
100    void (*hmac_md5_import)(HMAC_MD5_CTX *, HMAC_MD5_STATE *);
101
102	/* mechanism utility functions (same as above): */
103    int (*mkchal)(sasl_conn_t *conn, char *buf, unsigned maxlen,
104		unsigned hostflag);
105    int (*utf8verify)(const char *str, unsigned len);
106    void (*rand)(sasl_rand_t *rpool, char *buf, unsigned len);
107    void (*churn)(sasl_rand_t *rpool, const char *data, unsigned len);
108
109	/*
110	 * This allows recursive calls to the sasl_checkpass() routine from
111	 * within a SASL plug-in.  This MUST NOT be used in the PLAIN mechanism
112	 * as sasl_checkpass MAY be a front-end for the PLAIN mechanism.
113	 * This is intended for use by the non-standard LOGIN mechanism and
114	 * potentially by a future mechanism which uses public-key technology
115	 * to set up a lightweight encryption layer just for sending a
116	 * password.
117	 */
118    int (*checkpass)(sasl_conn_t *conn,
119		    const char *user, unsigned userlen,
120		    const char *pass, unsigned passlen);
121
122	/* Access to base64 encode/decode routines */
123    int (*decode64)(const char *in, unsigned inlen,
124		    char *out, unsigned outmax, unsigned *outlen);
125    int (*encode64)(const char *in, unsigned inlen,
126		    char *out, unsigned outmax, unsigned *outlen);
127
128	/* erase a buffer */
129    void (*erasebuffer)(char *buf, unsigned len);
130
131	/* callback to sasl_getprop() and sasl_setprop() */
132    int (*getprop)(sasl_conn_t *conn, int propnum, const void **pvalue);
133    int (*setprop)(sasl_conn_t *conn, int propnum, const void *value);
134
135	/* callback function */
136    sasl_getcallback_t *getcallback;
137
138	/*
139	 * format a message and then pass it to the SASL_CB_LOG callback
140	 *
141	 * use syslog()-style formatting (printf with %m as most recent errno
142	 * error).  The implementation may use a fixed size buffer not smaller
143	 * than 512 octets if it securely truncates the message.
144	 *
145	 * level is a SASL_LOG_* level (see sasl.h)
146	 */
147    void (*log)(sasl_conn_t *conn, int level, const char *fmt, ...);
148
149	/* callback to sasl_seterror() */
150    void (*seterror)(sasl_conn_t *conn, unsigned flags, const char *fmt, ...);
151
152	/* spare function pointer */
153    int *(*spare_fptr)();
154
155	/* auxiliary property utilities */
156    struct propctx *(*prop_new)(unsigned estimate);
157    int (*prop_dup)(struct propctx *src_ctx, struct propctx **dst_ctx);
158    int (*prop_request)(struct propctx *ctx, const char **names);
159    const struct propval *(*prop_get)(struct propctx *ctx);
160    int (*prop_getnames)(struct propctx *ctx, const char **names,
161			struct propval *vals);
162    void (*prop_clear)(struct propctx *ctx, int requests);
163    void (*prop_dispose)(struct propctx **ctx);
164    int (*prop_format)(struct propctx *ctx, const char *sep, int seplen,
165		    char *outbuf, unsigned outmax, unsigned *outlen);
166    int (*prop_set)(struct propctx *ctx, const char *name,
167		    const char *value, int vallen);
168    int (*prop_setvals)(struct propctx *ctx, const char *name,
169			const char **values);
170    void (*prop_erase)(struct propctx *ctx, const char *name);
171
172	/* for additions which don't require a version upgrade; set to 0 */
173    int (*spare_fptr1)();
174    int (*spare_fptr2)();
175    int (*spare_fptr3)();
176} sasl_utils_t;
177
178/*
179 * output parameters from SASL API
180 *
181 * created / destroyed by the glue code, though probably filled in
182 * by a combination of the plugin, the glue code, and the canon_user callback.
183 *
184 */
185typedef struct sasl_out_params {
186    unsigned doneflag;		/* exchange complete */
187
188    const char *user;		/* canonicalized user name */
189    const char *authid;		/* canonicalized authentication id */
190
191    unsigned ulen;		/* length of canonicalized user name */
192    unsigned alen;		/* length of canonicalized authid */
193
194	/* security layer information */
195    unsigned maxoutbuf;
196    sasl_ssf_t mech_ssf;    /* Should be set non-zero if negotiation of a */
197			    /* security layer was *attempted*, even if */
198			    /* the negotiation failed */
199    void *encode_context;
200    int (*encode)(void *context, const struct iovec *invec, unsigned numiov,
201		const char **output, unsigned *outputlen);
202    void *decode_context;
203    int (*decode)(void *context, const char *input, unsigned inputlen,
204		const char **output, unsigned *outputlen);
205
206	/* for additions which don't require a version upgrade; set to 0 */
207    void *spare_ptr1;
208    void *spare_ptr2;
209    void *spare_ptr3;
210    void *spare_ptr4;
211    int (*spare_fptr1)();
212    int (*spare_fptr2)();
213    int spare_int1;
214    int spare_int2;
215    int spare_int3;
216    int spare_int4;
217
218	/*
219	 * set to 0 initially, this allows a plugin with extended parameters
220	 * to work with an older framework by updating version as parameters
221	 * are added.
222	 */
223    int param_version;
224} sasl_out_params_t;
225
226/*
227 * Client Mechanism Functions
228 */
229
230/*
231 * input parameters to client SASL plugin
232 *
233 * created / destroyed by the glue code
234 *
235 */
236typedef struct sasl_client_params {
237    const char *service;	/* service name */
238    const char *serverFQDN;	/* server fully qualified domain name */
239    const char *clientFQDN;	/* client's fully qualified domain name */
240    const sasl_utils_t *utils;	/* SASL API utility routines -- */
241				/* for a particular sasl_conn_t, */
242				/* MUST remain valid until mech_free is */
243				/* called */
244    const sasl_callback_t *prompt_supp; /* client callback list */
245    const char *iplocalport;	/* server IP domain literal & port */
246    const char *ipremoteport;	/* client IP domain literal & port */
247
248    unsigned servicelen;	/* length of service */
249    unsigned slen;		/* length of serverFQDN */
250    unsigned clen;		/* length of clientFQDN */
251    unsigned iploclen;		/* length of iplocalport */
252    unsigned ipremlen;		/* length of ipremoteport */
253
254	/* application's security requirements & info */
255    sasl_security_properties_t props;
256    sasl_ssf_t external_ssf;	/* external SSF active */
257
258	/* for additions which don't require a version upgrade; set to 0 */
259    void *spare_ptr1;
260    void *spare_ptr2;
261    void *spare_ptr3;
262    void *spare_ptr4;
263
264	/*
265	 * Canonicalize a user name from on-wire to internal format
266	 *  added rjs3 2001-05-23
267	 *  Must be called once user name aquired if canon_user is non-NULL.
268	 *  conn    connection context
269	 *  in	    user name from wire protocol (need not be NUL terminated)
270	 *  len	    length of user name from wire protocol (0 = strlen(user))
271	 *  flags   for SASL_CU_* flags
272	 *  oparams the user, authid, ulen, alen, fields are
273	 *	    set appropriately after canonicalization/copying and
274	 *	    authorization of arguments
275	 *
276	 *  responsible for setting user, ulen, authid, and alen in the oparams
277	 *  structure
278	 *
279	 *  default behavior is to strip leading and trailing whitespace, as
280	 *  well as allocating space for and copying the parameters.
281	 *
282	 * results:
283	 *  SASL_OK	  -- success
284	 *  SASL_NOMEM    -- out of memory
285	 *  SASL_BADPARAM -- invalid conn
286	 *  SASL_BADPROT  -- invalid user/authid
287	 */
288    int (*canon_user)(sasl_conn_t *conn,
289		    const char *in, unsigned len,
290		    unsigned flags,
291		    sasl_out_params_t *oparams);
292
293    int (*spare_fptr1)();
294
295    int spare_int1;
296    int spare_int2;
297    int spare_int3;
298
299	/* flags field as passed to sasl_client_new */
300    unsigned flags;
301
302	/*
303	 * set to 0 initially, this allows a plugin with extended parameters
304	 * to work with an older framework by updating version as parameters
305	 * are added.
306	 */
307    int param_version;
308} sasl_client_params_t;
309
310/* features shared between client and server */
311/* These allow the glue code to handle client-first and server-last issues */
312
313/*
314 * This indicates that the mechanism prefers to do client-send-first
315 * if the protocol allows it.
316 */
317#define	SASL_FEAT_WANT_CLIENT_FIRST 0x0002
318
319/*
320 * This feature is deprecated, instead, plugins should set *serverout to
321 * non-NULL and return SASL_OK intelligently to allow flexible use of
322 * server-last semantics
323 */
324/* #define	SASL_FEAT_WANT_SERVER_LAST 0x0004 */
325
326/*
327 * This feature is deprecated, instead plugins should correctly set
328 * SASL_FEAT_SERVER_FIRST as needed
329 */
330/* #define	SASL_FEAT_INTERNAL_CLIENT_FIRST 0x0008 */
331
332/*
333 * This indicates that the plugin is server-first only.
334 * Not defining either of SASL_FEAT_SERVER_FIRST or
335 * SASL_FEAT_WANT_CLIENT_FIRST indicates that the mechanism will take care
336 * of the client-first situation internally.
337 */
338#define	SASL_FEAT_SERVER_FIRST 0x0010
339
340/* This plugin allows proxying */
341#define	SASL_FEAT_ALLOWS_PROXY 0x0020
342
343/* client plug-in features */
344#define	SASL_FEAT_NEEDSERVERFQDN 0x0001
345
346/* a C object for a client mechanism */
347typedef struct sasl_client_plug {
348	/* mechanism name */
349    const char *mech_name;
350
351	/* best mech additional security layer strength factor */
352    sasl_ssf_t max_ssf;
353
354	/* best security flags, as defined in sasl_security_properties_t */
355    unsigned security_flags;
356
357	/* features of plugin */
358    unsigned features;
359
360	/* required prompt ids, NULL = user/pass only */
361    const unsigned long *required_prompts;
362
363	/* global state for mechanism */
364    void *glob_context;
365
366	/*
367	 * create context for mechanism, using params supplied
368	 *  glob_context   -- from above
369	 *  params	   -- params from sasl_client_new
370	 *  conn_context   -- context for one connection
371	 * returns:
372	 *  SASL_OK	   -- success
373	 *  SASL_NOMEM	   -- not enough memory
374	 *  SASL_WRONGMECH -- mech doesn't support security params
375	 */
376    int (*mech_new)(void *glob_context,
377		    sasl_client_params_t *cparams,
378		    void **conn_context);
379
380	/*
381	 * perform one step of exchange.  NULL is passed for serverin on
382	 * first step.
383	 * returns:
384	 *  SASL_OK	   -- success
385	 *  SASL_INTERACT  -- user interaction needed to fill in prompts
386	 *  SASL_BADPROT   -- server protocol incorrect/cancelled
387	 *  SASL_BADSERV   -- server failed mutual auth
388	 */
389    int (*mech_step)(void *conn_context,
390		    sasl_client_params_t *cparams,
391		    const char *serverin,
392		    unsigned serverinlen,
393		    sasl_interact_t **prompt_need,
394		    const char **clientout,
395		    unsigned *clientoutlen,
396		    sasl_out_params_t *oparams);
397
398	/* dispose of connection context from mech_new */
399    void (*mech_dispose)(void *conn_context, const sasl_utils_t *utils);
400
401	/*
402	 * free all global space used by mechanism
403	 *  mech_dispose must be called on all mechanisms first
404	 */
405    void (*mech_free)(void *glob_context, const sasl_utils_t *utils);
406
407	/*
408	 * perform precalculations during a network round-trip
409	 *  or idle period.  conn_context may be NULL
410	 *  returns 1 if action taken, 0 if no action taken
411	 */
412    int (*idle)(void *glob_context,
413		void *conn_context,
414		sasl_client_params_t *cparams);
415
416	/* for additions which don't require a version upgrade; set to 0 */
417    int (*spare_fptr1)();
418    int (*spare_fptr2)();
419} sasl_client_plug_t;
420
421#define	SASL_CLIENT_PLUG_VERSION	4
422
423/*
424 * plug-in entry point:
425 *  utils       -- utility callback functions
426 *  max_version -- highest client plug version supported
427 * returns:
428 *  out_version -- client plug version of result
429 *  pluglist    -- list of mechanism plug-ins
430 *  plugcount   -- number of mechanism plug-ins
431 * results:
432 *  SASL_OK       -- success
433 *  SASL_NOMEM    -- failure
434 *  SASL_BADVERS  -- max_version too small
435 *  SASL_BADPARAM -- bad config string
436 *  ...
437 */
438typedef int sasl_client_plug_init_t(const sasl_utils_t *utils,
439				    int max_version,
440				    int *out_version,
441				    sasl_client_plug_t **pluglist,
442				    int *plugcount);
443
444/* add a client plug-in */
445LIBSASL_API int sasl_client_add_plugin(const char *plugname,
446				sasl_client_plug_init_t *cplugfunc);
447
448/*
449 * Server Functions
450 */
451
452/*
453 * input parameters to server SASL plugin
454 *
455 * created / destroyed by the glue code
456 *
457 */
458typedef struct sasl_server_params {
459    const char *service;	/* NULL = default service for user_exists */
460				/* and setpass */
461    const char *appname;	/* name of calling application */
462    const char *serverFQDN;	/* server default fully qualified domain name */
463				/* (e.g., gethostname) */
464    const char *user_realm;	/* realm for user (NULL = client supplied) */
465    const char *iplocalport;	/* server IP domain literal & port */
466    const char *ipremoteport;	/* client IP domain literal & port */
467
468    unsigned servicelen;	/* length of service */
469    unsigned applen;		/* length of appname */
470    unsigned slen;		/* length of serverFQDN */
471    unsigned urlen;		/* length of user_realm */
472    unsigned iploclen;		/* length of iplocalport */
473    unsigned ipremlen;		/* length of ipremoteport */
474
475	/*
476	 * This indicates the level of logging desired.  See SASL_LOG_*
477	 * in sasl.h
478	 *
479	 * Plug-ins can ignore this and just pass their desired level to
480	 * the log callback.  This is primarily used to eliminate logging which
481	 * might be a performance problem (e.g., full protocol trace) and
482	 * to select between SASL_LOG_TRACE and SASL_LOG_PASS alternatives
483	 */
484    int log_level;
485
486    const sasl_utils_t *utils;	/* SASL API utility routines -- */
487				/* for a particular sasl_conn_t, */
488				/* MUST remain valid until mech_free is */
489				/* called */
490
491    const sasl_callback_t *callbacks;	/* Callbacks from application */
492
493	/* application's security requirements */
494    sasl_security_properties_t props;
495    sasl_ssf_t external_ssf;	/* external SSF active */
496
497	/*
498	 * server plug-in calls this when it first has access to the plaintext
499	 *  passphrase.  This is used to transition users via setpass calls.
500	 *  If passlen is 0, it defaults to strlen(pass).
501	 *  returns 0 if no entry added, 1 if entry added
502	 */
503    int (*transition)(sasl_conn_t *conn, const char *pass, unsigned passlen);
504
505	/*
506	 * Canonicalize a user name from on-wire to internal format
507	 *  added cjn 1999-09-21
508	 *  Must be called once user name aquired if canon_user is non-NULL.
509	 *  conn    connection context
510	 *  user    user name from wire protocol (need not be NUL terminated)
511	 *  ulen    length of user name from wire protocol (0 = strlen(user))
512	 *  flags   for SASL_CU_* flags
513	 *  oparams the user, authid, ulen, alen, fields are
514	 *	    set appropriately after canonicalization/copying and
515	 *	    authorization of arguments
516	 *
517	 *  responsible for setting user, ulen, authid, and alen in the oparams
518	 *  structure
519	 *
520	 *  default behavior is to strip leading and trailing whitespace, as
521	 *  well as allocating space for and copying the parameters.
522	 *
523	 * results:
524	 *  SASL_OK	  -- success
525	 *  SASL_NOMEM    -- out of memory
526	 *  SASL_BADPARAM -- invalid conn
527	 *  SASL_BADPROT  -- invalid user/authid
528	 */
529    int (*canon_user)(sasl_conn_t *conn,
530		    const char *user, unsigned ulen,
531		    unsigned flags,
532		    sasl_out_params_t *oparams);
533
534	/*
535	 * auxiliary property context (see definitions in prop.h)
536	 *  added cjn 2000-01-30
537	 *
538	 * NOTE: these properties are the ones associated with the
539	 * canonicalized "user" (user to login as / authorization id), not
540	 * the "authid" (user whose credentials are used / authentication id)
541	 * Prefix the property name with a "*" if a property associated with
542	 * the "authid" is interesting.
543	 */
544    struct propctx *propctx;
545
546	/* for additions which don't require a version upgrade; set to 0 */
547    void *spare_ptr1;
548    void *spare_ptr2;
549    void *spare_ptr3;
550    void *spare_ptr4;
551    int (*spare_fptr1)();
552    int (*spare_fptr2)();
553    int spare_int1;
554    int spare_int2;
555    int spare_int3;
556
557	/* flags field as passed to sasl_server_new */
558    unsigned flags;
559
560	/*
561	 * set to 0 initially, this allows a plugin with extended parameters
562	 * to work with an older framework by updating version as parameters
563	 * are added.
564	 */
565    int param_version;
566} sasl_server_params_t;
567
568/* features for server plug-in */
569#define	SASL_FEAT_SERVICE    0x0200 /* service-specific passwords supported */
570#define	SASL_FEAT_GETSECRET  0x0400 /* sasl_server_{get,put}secret_t */
571				    /* callbacks required by plug-in */
572
573/* a C object for a server mechanism */
574typedef struct sasl_server_plug {
575	/* mechanism name */
576    const char *mech_name;
577
578	/* best mech additional security layer strength factor */
579    sasl_ssf_t max_ssf;
580
581	/* best security flags, as defined in sasl_security_properties_t */
582    unsigned security_flags;
583
584	/* features of plugin */
585    unsigned features;
586
587	/* global state for mechanism */
588    void *glob_context;
589
590	/*
591	 * create a new mechanism handler
592	 *  glob_context  -- global context
593	 *  sparams	  -- server config params
594	 *  challenge	  -- server challenge from previous instance or NULL
595	 *  challen	  -- length of challenge from previous instance or 0
596	 * out:
597	 *  conn_context  -- connection context
598	 *  errinfo	  -- error information
599	 *
600	 * returns:
601	 *  SASL_OK	  -- successfully created mech instance
602	 *  SASL_*	  -- any other server error code
603	 */
604    int (*mech_new)(void *glob_context,
605		    sasl_server_params_t *sparams,
606		    const char *challenge,
607		    unsigned challen,
608		    void **conn_context);
609
610	/*
611	 * perform one step in exchange
612	 *
613	 * returns:
614	 *  SASL_OK	  -- success, all done
615	 *  SASL_CONTINUE -- success, one more round trip
616	 *  SASL_*	  -- any other server error code
617	 */
618    int (*mech_step)(void *conn_context,
619			sasl_server_params_t *sparams,
620			const char *clientin,
621			unsigned clientinlen,
622			const char **serverout,
623			unsigned *serveroutlen,
624			sasl_out_params_t *oparams);
625
626	/* dispose of a connection state */
627    void (*mech_dispose)(void *conn_context, const sasl_utils_t *utils);
628
629	/*
630	 * free global state for mechanism
631	 *  mech_dispose must be called on all mechanisms first
632	 */
633    void (*mech_free)(void *glob_context, const sasl_utils_t *utils);
634
635	/*
636	 * set a password (optional)
637	 *  glob_context  -- global context
638	 *  sparams	  -- service, middleware utilities, etc. props ignored
639	 *  user	  -- user name
640	 *  pass	  -- password/passphrase (NULL = disable/remove/delete)
641	 *  passlen	  -- length of password/passphrase
642	 *  oldpass	  -- old password/passphrase (NULL = transition)
643	 *  oldpasslen    -- length of password/passphrase
644	 *  flags	  -- see above
645	 *
646	 * returns:
647	 *  SASL_NOCHANGE -- no change was needed
648	 *  SASL_NOUSER   -- no entry for user
649	 *  SASL_NOVERIFY -- no mechanism compatible entry for user
650	 *  SASL_PWLOCK   -- password locked
651	 *  SASL_DIABLED  -- account disabled
652	 *  etc.
653	 */
654    int (*setpass)(void *glob_context,
655		    sasl_server_params_t *sparams,
656		    const char *user,
657		    const char *pass, unsigned passlen,
658		    const char *oldpass, unsigned oldpasslen,
659		    unsigned flags);
660
661	/*
662	 * query which mechanisms are available for user
663	 *  glob_context  -- context
664	 *  sparams	  -- service, middleware utilities, etc. props ignored
665	 *  user	  -- NUL terminated user name
666	 *  maxmech	  -- max number of strings in mechlist (0 = no output)
667	 * output:
668	 *  mechlist	  -- an array of C string pointers, filled in with
669	 *		  mechanism names available to the user
670	 *
671	 * returns:
672	 *  SASL_OK	  -- success
673	 *  SASL_NOMEM    -- not enough memory
674	 *  SASL_FAIL	  -- lower level failure
675	 *  SASL_DISABLED -- account disabled
676	 *  SASL_NOUSER   -- user not found
677	 *  SASL_BUFOVER  -- maxmech is too small
678	 *  SASL_NOVERIFY -- user found, but no mechanisms available
679	 */
680    int (*user_query)(void *glob_context,
681		    sasl_server_params_t *sparams,
682		    const char *user,
683		    int maxmech,
684		    const char **mechlist);
685
686	/*
687	 * perform precalculations during a network round-trip
688	 *  or idle period.  conn_context may be NULL (optional)
689	 *  returns 1 if action taken, 0 if no action taken
690	 */
691    int (*idle)(void *glob_context,
692		void *conn_context,
693		sasl_server_params_t *sparams);
694
695	/*
696	 * check if mechanism is available
697	 * TODO - Is this correct?
698	 *  optional--if NULL, mechanism is available based on ENABLE=
699	 * in config
700	 *
701	 *  If this routine sets conn_context to a non-NULL value, then the call
702	 *  to mech_new will be skipped.  This should not be done unless
703	 *  there's a significant performance benefit, since it can cause
704	 *  additional memory allocation in SASL core code to keep track of
705	 *  contexts potentially for multiple mechanisms.
706	 *
707	 *  This is called by the first call to sasl_listmech() for a
708	 *  given connection context, thus for a given protocol it may
709	 *  never be called.  Note that if mech_avail returns SASL_NOMECH,
710	 *  then that mechanism is considered disabled for the remainder
711	 *  of the session.
712	 *
713	 *  returns SASL_OK on success,
714	 *	    SASL_NOMECH if mech disabled
715	 */
716    int (*mech_avail)(void *glob_context,
717		    sasl_server_params_t *sparams,
718		    void **conn_context);
719
720	/* for additions which don't require a version upgrade; set to 0 */
721    int (*spare_fptr2)();
722} sasl_server_plug_t;
723
724#define	SASL_SERVER_PLUG_VERSION 4
725
726/*
727 * plug-in entry point:
728 *  utils         -- utility callback functions
729 *  plugname      -- name of plug-in (may be NULL)
730 *  max_version   -- highest server plug version supported
731 * returns:
732 *  out_version   -- server plug-in version of result
733 *  pluglist      -- list of mechanism plug-ins
734 *  plugcount     -- number of mechanism plug-ins
735 * results:
736 *  SASL_OK       -- success
737 *  SASL_NOMEM    -- failure
738 *  SASL_BADVERS  -- max_version too small
739 *  SASL_BADPARAM -- bad config string
740 *  ...
741 */
742typedef int sasl_server_plug_init_t(const sasl_utils_t *utils,
743				    int max_version,
744				    int *out_version,
745				    sasl_server_plug_t **pluglist,
746				    int *plugcount);
747
748/*
749 * add a server plug-in
750 */
751LIBSASL_API int sasl_server_add_plugin(const char *plugname,
752				sasl_server_plug_init_t *splugfunc);
753
754/*
755 * user canonicalization plug-in -- added cjn 1999-09-29
756 */
757
758typedef struct sasl_canonuser {
759	/* optional features of plugin (set to 0) */
760    int features;
761
762	/* spare integer (set to 0) */
763    int spare_int1;
764
765	/* global state for plugin */
766    void *glob_context;
767
768	/* name of plugin */
769    char *name;
770
771	/* free global state for plugin */
772    void (*canon_user_free)(void *glob_context, const sasl_utils_t *utils);
773
774	/*
775	 * canonicalize a username
776	 *  glob_context    -- global context from this structure
777	 *  sparams	    -- server params, note user_realm&propctx elements
778	 *  user	    -- user to login as (may not be NUL terminated)
779	 *  len		    -- length of user name (0 = strlen(user))
780	 *  flags	    -- for SASL_CU_* flags
781	 *  out		    -- buffer to copy user name
782	 *  out_max	    -- max length of user name
783	 *  out_len	    -- set to length of user name
784	 *
785	 *  note that the output buffers MAY be the same as the input buffers.
786	 *
787	 * returns
788	 *  SASL_OK	    on success
789	 *  SASL_BADPROT    username contains invalid character
790	 */
791    int (*canon_user_server)(void *glob_context,
792			    sasl_server_params_t *sparams,
793			    const char *user, unsigned len,
794			    unsigned flags,
795			    char *out,
796			    unsigned out_umax, unsigned *out_ulen);
797
798    int (*canon_user_client)(void *glob_context,
799			    sasl_client_params_t *cparams,
800			    const char *user, unsigned len,
801			    unsigned flags,
802			    char *out,
803			    unsigned out_max, unsigned *out_len);
804
805	/* for additions which don't require a version upgrade; set to 0 */
806    int (*spare_fptr1)();
807    int (*spare_fptr2)();
808    int (*spare_fptr3)();
809} sasl_canonuser_plug_t;
810
811#define	SASL_CANONUSER_PLUG_VERSION 5
812
813/*
814 * default name for canonuser plug-in entry point is "sasl_canonuser_init"
815 *  similar to sasl_server_plug_init model, except only returns one
816 *  sasl_canonuser_plug_t structure;
817 */
818typedef int sasl_canonuser_init_t(const sasl_utils_t *utils,
819				int max_version,
820				int *out_version,
821				sasl_canonuser_plug_t **plug,
822				const char *plugname);
823
824/* add a canonuser plugin */
825LIBSASL_API int sasl_canonuser_add_plugin(const char *plugname,
826				sasl_canonuser_init_t *canonuserfunc);
827
828/*
829 * auxiliary property plug-in -- added cjn 1999-09-29
830 */
831
832typedef struct sasl_auxprop_plug {
833	/* optional features of plugin (none defined yet, set to 0) */
834    int features;
835
836	/* spare integer, must be set to 0 */
837    int spare_int1;
838
839	/* global state for plugin */
840    void *glob_context;
841
842	/* free global state for plugin (OPTIONAL) */
843    void (*auxprop_free)(void *glob_context, const sasl_utils_t *utils);
844
845	/*
846	 * fill in fields of an auxiliary property context
847	 *  last element in array has id of SASL_AUX_END
848	 *  elements with non-0 len should be ignored.
849	 */
850    void (*auxprop_lookup)(void *glob_context,
851			    sasl_server_params_t *sparams,
852			    unsigned flags,
853			    const char *user, unsigned ulen);
854
855	/* name of the auxprop plugin */
856    char *name;
857
858	/* for additions which don't require a version upgrade; set to 0 */
859    void (*spare_fptr1)();
860} sasl_auxprop_plug_t;
861
862/* auxprop lookup flags */
863#define	SASL_AUXPROP_OVERRIDE 0x01  /* if clear, ignore auxiliary properties */
864				    /* with non-zero len field.  If set, */
865				    /* override value of those properties */
866#define	SASL_AUXPROP_AUTHZID  0x02  /* if clear, we are looking up the */
867				    /* authid flags (prefixed with *), */
868				    /* otherwise we are looking up the */
869				    /* authzid flags (no prefix) */
870
871#define	SASL_AUXPROP_PLUG_VERSION 4
872
873/*
874 * default name for auxprop plug-in entry point is "sasl_auxprop_init"
875 *  similar to sasl_server_plug_init model, except only returns one
876 *  sasl_auxprop_plug_t structure;
877 */
878typedef int sasl_auxprop_init_t(const sasl_utils_t *utils,
879				int max_version,
880				int *out_version,
881				sasl_auxprop_plug_t **plug,
882				const char *plugname);
883
884/* add an auxiliary property plug-in */
885LIBSASL_API int sasl_auxprop_add_plugin(const char *plugname,
886					sasl_auxprop_init_t *auxpropfunc);
887
888#ifdef	__cplusplus
889}
890#endif
891
892#endif /* _SASL_SASLPLUG_H */
893