1 /* saslplug.h -- API for SASL plug-ins
24 /* callback to lookup a sasl_callback_t for a connection
26 * conn -- the connection to lookup a callback for
27 * callbacknum -- the number of the callback
29 * pproc -- pointer to the callback function (set to NULL on failure)
30 * pcontext -- pointer to the callback context (set to NULL on failure)
33 * SASL_FAIL -- unable to find a callback of the requested type
34 * SASL_INTERACT -- caller must use interaction to get data
36 typedef int sasl_getcallback_t(sasl_conn_t *conn,
37 unsigned long callbackid,
41 /* The sasl_utils structure will remain backwards compatible unless
42 * the SASL_*_PLUG_VERSION is changed incompatibly
43 * higher SASL_UTILS_VERSION numbers indicate more functions are available
45 #define SASL_UTILS_VERSION 4
47 /* utility function set for plug-ins
49 typedef struct sasl_utils {
58 sasl_getopt_t *getopt;
60 /* allocation functions: */
61 sasl_malloc_t *malloc;
62 sasl_calloc_t *calloc;
63 sasl_realloc_t *realloc;
66 /* mutex functions: */
67 sasl_mutex_alloc_t *mutex_alloc;
68 sasl_mutex_lock_t *mutex_lock;
69 sasl_mutex_unlock_t *mutex_unlock;
70 sasl_mutex_free_t *mutex_free;
72 /* MD5 hash and HMAC functions */
73 void (*MD5Init)(MD5_CTX *);
74 void (*MD5Update)(MD5_CTX *, const unsigned char *text, unsigned int len);
75 void (*MD5Final)(unsigned char [16], MD5_CTX *);
76 void (*hmac_md5)(const unsigned char *text, int text_len,
77 const unsigned char *key, int key_len,
79 void (*hmac_md5_init)(HMAC_MD5_CTX *, const unsigned char *key, int len);
80 /* hmac_md5_update() is just a call to MD5Update on inner context */
81 void (*hmac_md5_final)(unsigned char [16], HMAC_MD5_CTX *);
82 void (*hmac_md5_precalc)(HMAC_MD5_STATE *,
83 const unsigned char *key, int len);
84 void (*hmac_md5_import)(HMAC_MD5_CTX *, HMAC_MD5_STATE *);
86 /* mechanism utility functions (same as above): */
87 int (*mkchal)(sasl_conn_t *conn, char *buf, unsigned maxlen,
89 int (*utf8verify)(const char *str, unsigned len);
90 void (*rand)(sasl_rand_t *rpool, char *buf, unsigned len);
91 void (*churn)(sasl_rand_t *rpool, const char *data, unsigned len);
93 /* This allows recursive calls to the sasl_checkpass() routine from
94 * within a SASL plug-in. This MUST NOT be used in the PLAIN mechanism
95 * as sasl_checkpass MAY be a front-end for the PLAIN mechanism.
96 * This is intended for use by the non-standard LOGIN mechanism and
97 * potentially by a future mechanism which uses public-key technology to
98 * set up a lightweight encryption layer just for sending a password.
100 int (*checkpass)(sasl_conn_t *conn,
101 const char *user, unsigned userlen,
102 const char *pass, unsigned passlen);
104 /* Access to base64 encode/decode routines */
105 int (*decode64)(const char *in, unsigned inlen,
106 char *out, unsigned outmax, unsigned *outlen);
107 int (*encode64)(const char *in, unsigned inlen,
108 char *out, unsigned outmax, unsigned *outlen);
111 void (*erasebuffer)(char *buf, unsigned len);
113 /* callback to sasl_getprop() and sasl_setprop() */
114 int (*getprop)(sasl_conn_t *conn, int propnum, const void **pvalue);
115 int (*setprop)(sasl_conn_t *conn, int propnum, const void *value);
117 /* callback function */
118 sasl_getcallback_t *getcallback;
120 /* format a message and then pass it to the SASL_CB_LOG callback
122 * use syslog()-style formatting (printf with %m as a human readable text
123 * (strerror()) for the error specified as the parameter).
124 * The implementation may use a fixed size buffer not smaller
125 * than 512 octets if it securely truncates the message.
127 * level is a SASL_LOG_* level (see sasl.h)
129 void (*log)(sasl_conn_t *conn, int level, const char *fmt, ...);
131 /* callback to sasl_seterror() */
132 void (*seterror)(sasl_conn_t *conn, unsigned flags, const char *fmt, ...);
134 /* spare function pointer */
135 int *(*spare_fptr)();
137 /* auxiliary property utilities */
138 struct propctx *(*prop_new)(unsigned estimate);
139 int (*prop_dup)(struct propctx *src_ctx, struct propctx **dst_ctx);
140 int (*prop_request)(struct propctx *ctx, const char **names);
141 const struct propval *(*prop_get)(struct propctx *ctx);
142 int (*prop_getnames)(struct propctx *ctx, const char **names,
143 struct propval *vals);
144 void (*prop_clear)(struct propctx *ctx, int requests);
145 void (*prop_dispose)(struct propctx **ctx);
146 int (*prop_format)(struct propctx *ctx, const char *sep, int seplen,
147 char *outbuf, unsigned outmax, unsigned *outlen);
148 int (*prop_set)(struct propctx *ctx, const char *name,
149 const char *value, int vallen);
150 int (*prop_setvals)(struct propctx *ctx, const char *name,
151 const char **values);
152 void (*prop_erase)(struct propctx *ctx, const char *name);
153 int (*auxprop_store)(sasl_conn_t *conn,
154 struct propctx *ctx, const char *user);
156 /* for additions which don't require a version upgrade; set to 0 */
157 int (*spare_fptr1)();
158 int (*spare_fptr2)();
162 * output parameters from SASL API
164 * created / destroyed by the glue code, though probably filled in
165 * by a combination of the plugin, the glue code, and the canon_user callback.
168 typedef struct sasl_out_params {
169 unsigned doneflag; /* exchange complete */
171 const char *user; /* canonicalized user name */
172 const char *authid; /* canonicalized authentication id */
174 unsigned ulen; /* length of canonicalized user name */
175 unsigned alen; /* length of canonicalized authid */
177 /* security layer information */
178 unsigned maxoutbuf; /* Maximum buffer size, which will
179 produce buffer no bigger than the
180 negotiated SASL maximum buffer size */
181 sasl_ssf_t mech_ssf; /* Should be set non-zero if negotiation of a
182 * security layer was *attempted*, even if
183 * the negotiation failed */
184 void *encode_context;
185 int (*encode)(void *context, const struct iovec *invec, unsigned numiov,
186 const char **output, unsigned *outputlen);
187 void *decode_context;
188 int (*decode)(void *context, const char *input, unsigned inputlen,
189 const char **output, unsigned *outputlen);
191 /* Pointer to delegated (client's) credentials, if supported by
192 the SASL mechanism */
195 /* for additions which don't require a version upgrade; set to 0 */
196 const void *gss_peer_name;
197 const void *gss_local_name;
198 const char *cbindingname; /* channel binding name from packet */
199 int (*spare_fptr1)();
200 int (*spare_fptr2)();
201 unsigned int cbindingdisp; /* channel binding disposition from client */
206 /* set to 0 initially, this allows a plugin with extended parameters
207 * to work with an older framework by updating version as parameters
215 /* Used by both client and server side plugins */
217 SASL_INFO_LIST_START = 0,
220 } sasl_info_callback_stage_t;
222 /******************************
223 * Channel binding macros **
224 ******************************/
227 SASL_CB_DISP_NONE = 0, /* client did not support CB */
228 SASL_CB_DISP_WANT, /* client supports CB, thinks server does not */
229 SASL_CB_DISP_USED /* client supports and used CB */
230 } sasl_cbinding_disp_t;
232 /* TRUE if channel binding is non-NULL */
233 #define SASL_CB_PRESENT(params) ((params)->cbinding != NULL)
234 /* TRUE if channel binding is marked critical */
235 #define SASL_CB_CRITICAL(params) (SASL_CB_PRESENT(params) && \
236 (params)->cbinding->critical)
238 /******************************
239 * Client Mechanism Functions *
240 ******************************/
243 * input parameters to client SASL plugin
245 * created / destroyed by the glue code
248 typedef struct sasl_client_params {
249 const char *service; /* service name */
250 const char *serverFQDN; /* server fully qualified domain name */
251 const char *clientFQDN; /* client's fully qualified domain name */
252 const sasl_utils_t *utils; /* SASL API utility routines --
253 * for a particular sasl_conn_t,
254 * MUST remain valid until mech_free is
256 const sasl_callback_t *prompt_supp; /* client callback list */
257 const char *iplocalport; /* server IP domain literal & port */
258 const char *ipremoteport; /* client IP domain literal & port */
260 unsigned servicelen; /* length of service */
261 unsigned slen; /* length of serverFQDN */
262 unsigned clen; /* length of clientFQDN */
263 unsigned iploclen; /* length of iplocalport */
264 unsigned ipremlen; /* length of ipremoteport */
266 /* application's security requirements & info */
267 sasl_security_properties_t props;
268 sasl_ssf_t external_ssf; /* external SSF active */
270 /* for additions which don't require a version upgrade; set to 0 */
271 const void *gss_creds; /* GSS credential handle */
272 const sasl_channel_binding_t *cbinding; /* client channel binding */
276 /* Canonicalize a user name from on-wire to internal format
277 * added rjs3 2001-05-23
278 * Must be called once user name aquired if canon_user is non-NULL.
279 * conn connection context
280 * in user name from wire protocol (need not be NUL terminated)
281 * len length of user name from wire protocol (0 = strlen(user))
282 * flags for SASL_CU_* flags
283 * oparams the user, authid, ulen, alen, fields are
284 * set appropriately after canonicalization/copying and
285 * authorization of arguments
287 * responsible for setting user, ulen, authid, and alen in the oparams
290 * default behavior is to strip leading and trailing whitespace, as
291 * well as allocating space for and copying the parameters.
295 * SASL_NOMEM -- out of memory
296 * SASL_BADPARAM -- invalid conn
297 * SASL_BADPROT -- invalid user/authid
299 int (*canon_user)(sasl_conn_t *conn,
300 const char *in, unsigned len,
302 sasl_out_params_t *oparams);
304 int (*spare_fptr1)();
306 unsigned int cbindingdisp;
307 unsigned int spare_int2;
310 /* flags field as passed to sasl_client_new */
313 /* set to 0 initially, this allows a plugin with extended parameters
314 * to work with an older framework by updating version as parameters
318 } sasl_client_params_t;
320 /* features shared between client and server */
321 /* These allow the glue code to handle client-first and server-last issues */
323 /* This indicates that the mechanism prefers to do client-send-first
324 * if the protocol allows it. */
325 #define SASL_FEAT_WANT_CLIENT_FIRST 0x0002
327 /* This feature is deprecated, instead, plugins should set *serverout to
328 * non-NULL and return SASL_OK intelligently to allow flexible use of
329 * server-last semantics */
330 /* #define SASL_FEAT_WANT_SERVER_LAST 0x0004 */
332 /* This feature is deprecated, instead plugins should correctly set
333 * SASL_FEAT_SERVER_FIRST as needed */
334 /* #define SASL_FEAT_INTERNAL_CLIENT_FIRST 0x0008 */
336 /* This indicates that the plugin is server-first only.
337 * Not defining either of SASL_FEAT_SERVER_FIRST or
338 * SASL_FEAT_WANT_CLIENT_FIRST indicates that the mechanism will take care
339 * of the client-first situation internally.
341 #define SASL_FEAT_SERVER_FIRST 0x0010
343 /* This plugin allows proxying */
344 #define SASL_FEAT_ALLOWS_PROXY 0x0020
346 /* server plugin needs old password in order to change password */
347 #define SASL_FEAT_NEED_OLD_PASSWD 0x0040
349 /* server plugin don't use cleartext userPassword attribute */
350 #define SASL_FEAT_DONTUSE_USERPASSWD 0x0080
352 /* Underlying mechanism uses GSS framing */
353 #define SASL_FEAT_GSS_FRAMING 0x0100
355 /* Underlying mechanism supports channel binding */
356 #define SASL_FEAT_CHANNEL_BINDING 0x0200
358 /* client plug-in features */
359 #define SASL_FEAT_NEEDSERVERFQDN 0x0001
361 /* a C object for a client mechanism
363 typedef struct sasl_client_plug {
365 const char *mech_name;
367 /* best mech additional security layer strength factor */
370 /* best security flags, as defined in sasl_security_properties_t */
371 unsigned security_flags;
373 /* features of plugin */
376 /* required prompt ids, NULL = user/pass only */
377 const unsigned long *required_prompts;
379 /* global state for mechanism */
382 /* create context for mechanism, using params supplied
383 * glob_context -- from above
384 * params -- params from sasl_client_new
385 * conn_context -- context for one connection
388 * SASL_NOMEM -- not enough memory
389 * SASL_WRONGMECH -- mech doesn't support security params
391 int (*mech_new)(void *glob_context,
392 sasl_client_params_t *cparams,
393 void **conn_context);
395 /* perform one step of exchange. NULL is passed for serverin on
399 * SASL_INTERACT -- user interaction needed to fill in prompts
400 * SASL_BADPROT -- server protocol incorrect/cancelled
401 * SASL_BADSERV -- server failed mutual auth
403 int (*mech_step)(void *conn_context,
404 sasl_client_params_t *cparams,
405 const char *serverin,
406 unsigned serverinlen,
407 sasl_interact_t **prompt_need,
408 const char **clientout,
409 unsigned *clientoutlen,
410 sasl_out_params_t *oparams);
412 /* dispose of connection context from mech_new
414 void (*mech_dispose)(void *conn_context, const sasl_utils_t *utils);
416 /* free all global space used by mechanism
417 * mech_dispose must be called on all mechanisms first
419 void (*mech_free)(void *glob_context, const sasl_utils_t *utils);
421 /* perform precalculations during a network round-trip
422 * or idle period. conn_context may be NULL
423 * returns 1 if action taken, 0 if no action taken
425 int (*idle)(void *glob_context,
427 sasl_client_params_t *cparams);
429 /* for additions which don't require a version upgrade; set to 0 */
430 int (*spare_fptr1)();
431 int (*spare_fptr2)();
432 } sasl_client_plug_t;
434 #define SASL_CLIENT_PLUG_VERSION 4
436 /* plug-in entry point:
437 * utils -- utility callback functions
438 * max_version -- highest client plug version supported
440 * out_version -- client plug version of result
441 * pluglist -- list of mechanism plug-ins
442 * plugcount -- number of mechanism plug-ins
445 * SASL_NOMEM -- failure
446 * SASL_BADVERS -- max_version too small
447 * SASL_BADPARAM -- bad config string
450 typedef int sasl_client_plug_init_t(const sasl_utils_t *utils,
453 sasl_client_plug_t **pluglist,
457 /* add a client plug-in
459 LIBSASL_API int sasl_client_add_plugin(const char *plugname,
460 sasl_client_plug_init_t *cplugfunc);
462 typedef struct client_sasl_mechanism
467 const sasl_client_plug_t *plug;
468 } client_sasl_mechanism_t;
470 typedef void sasl_client_info_callback_t (client_sasl_mechanism_t *m,
471 sasl_info_callback_stage_t stage,
474 /* Dump information about available client plugins */
475 LIBSASL_API int sasl_client_plugin_info (const char *mech_list,
476 sasl_client_info_callback_t *info_cb,
480 /********************
482 ********************/
484 /* log message formatting routine */
485 typedef void sasl_logmsg_p(sasl_conn_t *conn, const char *fmt, ...);
488 * input parameters to server SASL plugin
490 * created / destroyed by the glue code
493 typedef struct sasl_server_params {
494 const char *service; /* NULL = default service for user_exists
496 const char *appname; /* name of calling application */
497 const char *serverFQDN; /* server default fully qualified domain name
498 * (e.g., gethostname) */
499 const char *user_realm; /* realm for user (NULL = client supplied) */
500 const char *iplocalport; /* server IP domain literal & port */
501 const char *ipremoteport; /* client IP domain literal & port */
503 unsigned servicelen; /* length of service */
504 unsigned applen; /* length of appname */
505 unsigned slen; /* length of serverFQDN */
506 unsigned urlen; /* length of user_realm */
507 unsigned iploclen; /* length of iplocalport */
508 unsigned ipremlen; /* length of ipremoteport */
510 /* This indicates the level of logging desired. See SASL_LOG_*
513 * Plug-ins can ignore this and just pass their desired level to
514 * the log callback. This is primarily used to eliminate logging which
515 * might be a performance problem (e.g., full protocol trace) and
516 * to select between SASL_LOG_TRACE and SASL_LOG_PASS alternatives
520 const sasl_utils_t *utils; /* SASL API utility routines --
521 * for a particular sasl_conn_t,
522 * MUST remain valid until mech_free is
524 const sasl_callback_t *callbacks; /* Callbacks from application */
526 /* application's security requirements */
527 sasl_security_properties_t props;
528 sasl_ssf_t external_ssf; /* external SSF active */
530 /* Pointer to the function which takes the plaintext passphrase and
531 * transitions a user to non-plaintext mechanisms via setpass calls.
532 * (NULL = auto transition not enabled/supported)
534 * If passlen is 0, it defaults to strlen(pass).
535 * returns 0 if no entry added, 1 if entry added
537 int (*transition)(sasl_conn_t *conn, const char *pass, unsigned passlen);
539 /* Canonicalize a user name from on-wire to internal format
540 * added cjn 1999-09-21
541 * Must be called once user name acquired if canon_user is non-NULL.
542 * conn connection context
543 * user user name from wire protocol (need not be NUL terminated)
544 * ulen length of user name from wire protocol (0 = strlen(user))
545 * flags for SASL_CU_* flags
546 * oparams the user, authid, ulen, alen, fields are
547 * set appropriately after canonicalization/copying and
548 * authorization of arguments
550 * responsible for setting user, ulen, authid, and alen in the oparams
553 * default behavior is to strip leading and trailing whitespace, as
554 * well as allocating space for and copying the parameters.
558 * SASL_NOMEM -- out of memory
559 * SASL_BADPARAM -- invalid conn
560 * SASL_BADPROT -- invalid user/authid
562 int (*canon_user)(sasl_conn_t *conn,
563 const char *user, unsigned ulen,
565 sasl_out_params_t *oparams);
567 /* auxiliary property context (see definitions in prop.h)
568 * added cjn 2000-01-30
570 * NOTE: these properties are the ones associated with the
571 * canonicalized "user" (user to login as / authorization id), not
572 * the "authid" (user whose credentials are used / authentication id)
573 * Prefix the property name with a "*" if a property associated with
574 * the "authid" is interesting.
576 struct propctx *propctx;
578 /* for additions which don't require a version upgrade; set to 0 */
579 const void *gss_creds; /* GSS credential handle */
580 const sasl_channel_binding_t *cbinding; /* server channel binding */
583 int (*spare_fptr1)();
584 int (*spare_fptr2)();
589 /* flags field as passed to sasl_server_new */
592 /* set to 0 initially, this allows a plugin with extended parameters
593 * to work with an older framework by updating version as parameters
597 } sasl_server_params_t;
599 /* logging levels (more levels may be added later, if necessary):
601 #define SASL_LOG_NONE 0 /* don't log anything */
602 #define SASL_LOG_ERR 1 /* log unusual errors (default) */
603 #define SASL_LOG_FAIL 2 /* log all authentication failures */
604 #define SASL_LOG_WARN 3 /* log non-fatal warnings */
605 #define SASL_LOG_NOTE 4 /* more verbose than LOG_WARN */
606 #define SASL_LOG_DEBUG 5 /* more verbose than LOG_NOTE */
607 #define SASL_LOG_TRACE 6 /* traces of internal protocols */
608 #define SASL_LOG_PASS 7 /* traces of internal protocols, including
611 /* additional flags for setpass() function below:
613 /* SASL_SET_CREATE create user if pass non-NULL */
614 /* SASL_SET_DISABLE disable user */
615 #define SASL_SET_REMOVE SASL_SET_CREATE /* remove user if pass is NULL */
617 /* features for server plug-in
619 #define SASL_FEAT_SERVICE 0x0200 /* service-specific passwords supported */
620 #define SASL_FEAT_GETSECRET 0x0400 /* sasl_server_{get,put}secret_t callbacks
621 * required by plug-in */
623 /* a C object for a server mechanism
625 typedef struct sasl_server_plug {
627 const char *mech_name;
629 /* best mech additional security layer strength factor */
632 /* best security flags, as defined in sasl_security_properties_t */
633 unsigned security_flags;
635 /* features of plugin */
638 /* global state for mechanism */
641 /* create a new mechanism handler
642 * glob_context -- global context
643 * sparams -- server config params
644 * challenge -- server challenge from previous instance or NULL
645 * challen -- length of challenge from previous instance or 0
647 * conn_context -- connection context
648 * errinfo -- error information
651 * SASL_OK -- successfully created mech instance
652 * SASL_* -- any other server error code
654 int (*mech_new)(void *glob_context,
655 sasl_server_params_t *sparams,
656 const char *challenge,
658 void **conn_context);
660 /* perform one step in exchange
663 * SASL_OK -- success, all done
664 * SASL_CONTINUE -- success, one more round trip
665 * SASL_* -- any other server error code
667 int (*mech_step)(void *conn_context,
668 sasl_server_params_t *sparams,
669 const char *clientin,
670 unsigned clientinlen,
671 const char **serverout,
672 unsigned *serveroutlen,
673 sasl_out_params_t *oparams);
675 /* dispose of a connection state
677 void (*mech_dispose)(void *conn_context, const sasl_utils_t *utils);
679 /* free global state for mechanism
680 * mech_dispose must be called on all mechanisms first
682 void (*mech_free)(void *glob_context, const sasl_utils_t *utils);
684 /* set a password (optional)
685 * glob_context -- global context
686 * sparams -- service, middleware utilities, etc. props ignored
688 * pass -- password/passphrase (NULL = disable/remove/delete)
689 * passlen -- length of password/passphrase
690 * oldpass -- old password/passphrase (NULL = transition)
691 * oldpasslen -- length of password/passphrase
695 * SASL_NOCHANGE -- no change was needed
696 * SASL_NOUSER -- no entry for user
697 * SASL_NOVERIFY -- no mechanism compatible entry for user
698 * SASL_PWLOCK -- password locked
699 * SASL_DIABLED -- account disabled
702 int (*setpass)(void *glob_context,
703 sasl_server_params_t *sparams,
705 const char *pass, unsigned passlen,
706 const char *oldpass, unsigned oldpasslen,
709 /* query which mechanisms are available for user
710 * glob_context -- context
711 * sparams -- service, middleware utilities, etc. props ignored
712 * user -- NUL terminated user name
713 * maxmech -- max number of strings in mechlist (0 = no output)
715 * mechlist -- an array of C string pointers, filled in with
716 * mechanism names available to the user
720 * SASL_NOMEM -- not enough memory
721 * SASL_FAIL -- lower level failure
722 * SASL_DISABLED -- account disabled
723 * SASL_NOUSER -- user not found
724 * SASL_BUFOVER -- maxmech is too small
725 * SASL_NOVERIFY -- user found, but no mechanisms available
727 int (*user_query)(void *glob_context,
728 sasl_server_params_t *sparams,
731 const char **mechlist);
733 /* perform precalculations during a network round-trip
734 * or idle period. conn_context may be NULL (optional)
735 * returns 1 if action taken, 0 if no action taken
737 int (*idle)(void *glob_context,
739 sasl_server_params_t *sparams);
741 /* check if mechanism is available
742 * optional--if NULL, mechanism is available based on ENABLE= in config
744 * If this routine sets conn_context to a non-NULL value, then the call
745 * to mech_new will be skipped. This should not be done unless
746 * there's a significant performance benefit, since it can cause
747 * additional memory allocation in SASL core code to keep track of
748 * contexts potentially for multiple mechanisms.
750 * This is called by the first call to sasl_listmech() for a
751 * given connection context, thus for a given protocol it may
752 * never be called. Note that if mech_avail returns SASL_NOMECH,
753 * then that mechanism is considered disabled for the remainder
754 * of the session. If mech_avail returns SASL_NOTDONE, then a
755 * future call to mech_avail may still return either SASL_OK
758 * returns SASL_OK on success,
759 * SASL_NOTDONE if mech is not available now, but may be later
760 * (e.g. EXTERNAL w/o auth_id)
761 * SASL_NOMECH if mech disabled
763 int (*mech_avail)(void *glob_context,
764 sasl_server_params_t *sparams,
765 void **conn_context);
767 /* for additions which don't require a version upgrade; set to 0 */
768 int (*spare_fptr2)();
769 } sasl_server_plug_t;
771 #define SASL_SERVER_PLUG_VERSION 4
773 /* plug-in entry point:
774 * utils -- utility callback functions
775 * plugname -- name of plug-in (may be NULL)
776 * max_version -- highest server plug version supported
778 * out_version -- server plug-in version of result
779 * pluglist -- list of mechanism plug-ins
780 * plugcount -- number of mechanism plug-ins
783 * SASL_NOMEM -- failure
784 * SASL_BADVERS -- max_version too small
785 * SASL_BADPARAM -- bad config string
788 typedef int sasl_server_plug_init_t(const sasl_utils_t *utils,
791 sasl_server_plug_t **pluglist,
795 * add a server plug-in
797 LIBSASL_API int sasl_server_add_plugin(const char *plugname,
798 sasl_server_plug_init_t *splugfunc);
801 typedef struct server_sasl_mechanism
804 int condition; /* set to SASL_NOUSER if no available users;
805 set to SASL_CONTINUE if delayed plugin loading */
806 char *plugname; /* for AUTHSOURCE tracking */
807 const sasl_server_plug_t *plug;
808 char *f; /* where should i load the mechanism from? */
809 } server_sasl_mechanism_t;
811 typedef void sasl_server_info_callback_t (server_sasl_mechanism_t *m,
812 sasl_info_callback_stage_t stage,
816 /* Dump information about available server plugins (separate functions are
817 used for canon and auxprop plugins) */
818 LIBSASL_API int sasl_server_plugin_info (const char *mech_list,
819 sasl_server_info_callback_t *info_cb,
823 /*********************************************************
824 * user canonicalization plug-in -- added cjn 1999-09-29 *
825 *********************************************************/
827 typedef struct sasl_canonuser {
828 /* optional features of plugin (set to 0) */
831 /* spare integer (set to 0) */
834 /* global state for plugin */
840 /* free global state for plugin */
841 void (*canon_user_free)(void *glob_context, const sasl_utils_t *utils);
843 /* canonicalize a username
844 * glob_context -- global context from this structure
845 * sparams -- server params, note user_realm&propctx elements
846 * user -- user to login as (may not be NUL terminated)
847 * len -- length of user name (0 = strlen(user))
848 * flags -- for SASL_CU_* flags
849 * out -- buffer to copy user name
850 * out_max -- max length of user name
851 * out_len -- set to length of user name
853 * note that the output buffers MAY be the same as the input buffers.
857 * SASL_BADPROT username contains invalid character
859 int (*canon_user_server)(void *glob_context,
860 sasl_server_params_t *sparams,
861 const char *user, unsigned len,
864 unsigned out_umax, unsigned *out_ulen);
866 int (*canon_user_client)(void *glob_context,
867 sasl_client_params_t *cparams,
868 const char *user, unsigned len,
871 unsigned out_max, unsigned *out_len);
873 /* for additions which don't require a version upgrade; set to 0 */
874 int (*spare_fptr1)();
875 int (*spare_fptr2)();
876 int (*spare_fptr3)();
877 } sasl_canonuser_plug_t;
879 #define SASL_CANONUSER_PLUG_VERSION 5
881 /* default name for canonuser plug-in entry point is "sasl_canonuser_init"
882 * similar to sasl_server_plug_init model, except only returns one
883 * sasl_canonuser_plug_t structure;
885 typedef int sasl_canonuser_init_t(const sasl_utils_t *utils,
888 sasl_canonuser_plug_t **plug,
889 const char *plugname);
891 /* add a canonuser plugin
893 LIBSASL_API int sasl_canonuser_add_plugin(const char *plugname,
894 sasl_canonuser_init_t *canonuserfunc);
896 /******************************************************
897 * auxiliary property plug-in -- added cjn 1999-09-29 *
898 ******************************************************/
900 typedef struct sasl_auxprop_plug {
901 /* optional features of plugin (none defined yet, set to 0) */
904 /* spare integer, must be set to 0 */
907 /* global state for plugin */
910 /* free global state for plugin (OPTIONAL) */
911 void (*auxprop_free)(void *glob_context, const sasl_utils_t *utils);
913 /* fill in fields of an auxiliary property context
914 * last element in array has id of SASL_AUX_END
915 * elements with non-0 len should be ignored.
917 void (*auxprop_lookup)(void *glob_context,
918 sasl_server_params_t *sparams,
920 const char *user, unsigned ulen);
922 /* name of the auxprop plugin */
925 /* store the fields/values of an auxiliary property context (OPTIONAL)
927 * if ctx is NULL, just check if storing properties is enabled
931 * SASL_FAIL on failure
933 int (*auxprop_store)(void *glob_context,
934 sasl_server_params_t *sparams,
936 const char *user, unsigned ulen);
937 } sasl_auxprop_plug_t;
939 /* auxprop lookup flags */
940 #define SASL_AUXPROP_OVERRIDE 0x01 /* if clear, ignore auxiliary properties
941 * with non-zero len field. If set,
942 * override value of those properties */
943 #define SASL_AUXPROP_AUTHZID 0x02 /* if clear, we are looking up the
944 * authid flags (prefixed with *), otherwise
945 * we are looking up the authzid flags
948 #define SASL_AUXPROP_PLUG_VERSION 4
950 /* default name for auxprop plug-in entry point is "sasl_auxprop_init"
951 * similar to sasl_server_plug_init model, except only returns one
952 * sasl_auxprop_plug_t structure;
954 typedef int sasl_auxprop_init_t(const sasl_utils_t *utils,
957 sasl_auxprop_plug_t **plug,
958 const char *plugname);
960 /* add an auxiliary property plug-in
962 LIBSASL_API int sasl_auxprop_add_plugin(const char *plugname,
963 sasl_auxprop_init_t *auxpropfunc);
965 typedef void auxprop_info_callback_t (sasl_auxprop_plug_t *m,
966 sasl_info_callback_stage_t stage,
969 /* Dump information about available auxprop plugins (separate functions are
970 used for canon and server authentication plugins) */
971 LIBSASL_API int auxprop_plugin_info (const char *mech_list,
972 auxprop_info_callback_t *info_cb,
979 #endif /* SASLPLUG_H */