/* saslplug.h -- API for SASL plug-ins
*/
#ifndef SASLPLUG_H
#define SASLPLUG_H 1
#ifndef MD5GLOBAL_H
#include "md5global.h"
#endif
#ifndef MD5_H
#include "md5.h"
#endif
#ifndef HMAC_MD5_H
#include "hmac-md5.h"
#endif
#ifndef PROP_H
#include "prop.h"
#endif
#ifdef __cplusplus
extern "C" {
#endif
/* callback to lookup a sasl_callback_t for a connection
* input:
* conn -- the connection to lookup a callback for
* callbacknum -- the number of the callback
* output:
* pproc -- pointer to the callback function (set to NULL on failure)
* pcontext -- pointer to the callback context (set to NULL on failure)
* returns:
* SASL_OK -- no error
* SASL_FAIL -- unable to find a callback of the requested type
* SASL_INTERACT -- caller must use interaction to get data
*/
typedef int (*sasl_callback_ft)(void);
typedef int sasl_getcallback_t(sasl_conn_t *conn,
unsigned long callbackid,
sasl_callback_ft * pproc,
void **pcontext);
/* The sasl_utils structure will remain backwards compatible unless
* the SASL_*_PLUG_VERSION is changed incompatibly
* higher SASL_UTILS_VERSION numbers indicate more functions are available
*/
#define SASL_UTILS_VERSION 4
/* utility function set for plug-ins
*/
typedef struct sasl_utils {
int version;
/* contexts */
sasl_conn_t *conn;
sasl_rand_t *rpool;
void *getopt_context;
/* option function */
sasl_getopt_t *getopt;
/* allocation functions: */
sasl_malloc_t *malloc;
sasl_calloc_t *calloc;
sasl_realloc_t *realloc;
sasl_free_t *free;
/* mutex functions: */
sasl_mutex_alloc_t *mutex_alloc;
sasl_mutex_lock_t *mutex_lock;
sasl_mutex_unlock_t *mutex_unlock;
sasl_mutex_free_t *mutex_free;
/* MD5 hash and HMAC functions */
void (*MD5Init)(MD5_CTX *);
void (*MD5Update)(MD5_CTX *, const unsigned char *text, unsigned int len);
void (*MD5Final)(unsigned char [16], MD5_CTX *);
void (*hmac_md5)(const unsigned char *text, int text_len,
const unsigned char *key, int key_len,
unsigned char [16]);
void (*hmac_md5_init)(HMAC_MD5_CTX *, const unsigned char *key, int len);
/* hmac_md5_update() is just a call to MD5Update on inner context */
void (*hmac_md5_final)(unsigned char [16], HMAC_MD5_CTX *);
void (*hmac_md5_precalc)(HMAC_MD5_STATE *,
const unsigned char *key, int len);
void (*hmac_md5_import)(HMAC_MD5_CTX *, HMAC_MD5_STATE *);
/* mechanism utility functions (same as above): */
int (*mkchal)(sasl_conn_t *conn, char *buf, unsigned maxlen,
unsigned hostflag);
int (*utf8verify)(const char *str, unsigned len);
void (*rand)(sasl_rand_t *rpool, char *buf, unsigned len);
void (*churn)(sasl_rand_t *rpool, const char *data, unsigned len);
/* This allows recursive calls to the sasl_checkpass() routine from
* within a SASL plug-in. This MUST NOT be used in the PLAIN mechanism
* as sasl_checkpass MAY be a front-end for the PLAIN mechanism.
* This is intended for use by the non-standard LOGIN mechanism and
* potentially by a future mechanism which uses public-key technology to
* set up a lightweight encryption layer just for sending a password.
*/
int (*checkpass)(sasl_conn_t *conn,
const char *user, unsigned userlen,
const char *pass, unsigned passlen);
/* Access to base64 encode/decode routines */
int (*decode64)(const char *in, unsigned inlen,
char *out, unsigned outmax, unsigned *outlen);
int (*encode64)(const char *in, unsigned inlen,
char *out, unsigned outmax, unsigned *outlen);
/* erase a buffer */
void (*erasebuffer)(char *buf, unsigned len);
/* callback to sasl_getprop() and sasl_setprop() */
int (*getprop)(sasl_conn_t *conn, int propnum, const void **pvalue);
int (*setprop)(sasl_conn_t *conn, int propnum, const void *value);
/* callback function */
sasl_getcallback_t *getcallback;
/* format a message and then pass it to the SASL_CB_LOG callback
*
* use syslog()-style formatting (printf with %m as a human readable text
* (strerror()) for the error specified as the parameter).
* The implementation may use a fixed size buffer not smaller
* than 512 octets if it securely truncates the message.
*
* level is a SASL_LOG_* level (see sasl.h)
*/
void (*log)(sasl_conn_t *conn, int level, const char *fmt, ...) __attribute__((format(printf, 3, 4)));
/* callback to sasl_seterror() */
void (*seterror)(sasl_conn_t *conn, unsigned flags, const char *fmt, ...) __attribute__((format(printf, 3, 4)));
/* spare function pointer */
int *(*spare_fptr)(void);
/* auxiliary property utilities */
struct propctx *(*prop_new)(unsigned estimate);
int (*prop_dup)(struct propctx *src_ctx, struct propctx **dst_ctx);
int (*prop_request)(struct propctx *ctx, const char **names);
const struct propval *(*prop_get)(struct propctx *ctx);
int (*prop_getnames)(struct propctx *ctx, const char **names,
struct propval *vals);
void (*prop_clear)(struct propctx *ctx, int requests);
void (*prop_dispose)(struct propctx **ctx);
int (*prop_format)(struct propctx *ctx, const char *sep, int seplen,
char *outbuf, unsigned outmax, unsigned *outlen);
int (*prop_set)(struct propctx *ctx, const char *name,
const char *value, int vallen);
int (*prop_setvals)(struct propctx *ctx, const char *name,
const char **values);
void (*prop_erase)(struct propctx *ctx, const char *name);
int (*auxprop_store)(sasl_conn_t *conn,
struct propctx *ctx, const char *user);
/* for additions which don't require a version upgrade; set to 0 */
int (*spare_fptr1)(void);
int (*spare_fptr2)(void);
} sasl_utils_t;
/*
* output parameters from SASL API
*
* created / destroyed by the glue code, though probably filled in
* by a combination of the plugin, the glue code, and the canon_user callback.
*
*/
typedef struct sasl_out_params {
unsigned doneflag; /* exchange complete */
const char *user; /* canonicalized user name */
const char *authid; /* canonicalized authentication id */
unsigned ulen; /* length of canonicalized user name */
unsigned alen; /* length of canonicalized authid */
/* security layer information */
unsigned maxoutbuf; /* Maximum buffer size, which will
produce buffer no bigger than the
negotiated SASL maximum buffer size */
sasl_ssf_t mech_ssf; /* Should be set non-zero if negotiation of a
* security layer was *attempted*, even if
* the negotiation failed */
void *encode_context;
int (*encode)(void *context, const struct iovec *invec, unsigned numiov,
const char **output, unsigned *outputlen);
void *decode_context;
int (*decode)(void *context, const char *input, unsigned inputlen,
const char **output, unsigned *outputlen);
/* Pointer to delegated (client's) credentials, if supported by
the SASL mechanism */
void *client_creds;
/* for additions which don't require a version upgrade; set to 0 */
const void *gss_peer_name;
const void *gss_local_name;
const char *cbindingname; /* channel binding name from packet */
int (*spare_fptr1)(void);
int (*spare_fptr2)(void);
unsigned int cbindingdisp; /* channel binding disposition from client */
int spare_int2;
int spare_int3;
int spare_int4;
/* set to 0 initially, this allows a plugin with extended parameters
* to work with an older framework by updating version as parameters
* are added.
*/
int param_version;
} sasl_out_params_t;
/* Used by both client and server side plugins */
typedef enum {
SASL_INFO_LIST_START = 0,
SASL_INFO_LIST_MECH,
SASL_INFO_LIST_END
} sasl_info_callback_stage_t;
/******************************
* Channel binding macros **
******************************/
typedef enum {
SASL_CB_DISP_NONE = 0, /* client did not support CB */
SASL_CB_DISP_WANT, /* client supports CB, thinks server does not */
SASL_CB_DISP_USED /* client supports and used CB */
} sasl_cbinding_disp_t;
/* TRUE if channel binding is non-NULL */
#define SASL_CB_PRESENT(params) ((params)->cbinding != NULL)
/* TRUE if channel binding is marked critical */
#define SASL_CB_CRITICAL(params) (SASL_CB_PRESENT(params) && \
(params)->cbinding->critical)
/******************************
* Client Mechanism Functions *
******************************/
/*
* input parameters to client SASL plugin
*
* created / destroyed by the glue code
*
*/
typedef struct sasl_client_params {
const char *service; /* service name */
const char *serverFQDN; /* server fully qualified domain name */
const char *clientFQDN; /* client's fully qualified domain name */
const sasl_utils_t *utils; /* SASL API utility routines --
* for a particular sasl_conn_t,
* MUST remain valid until mech_free is
* called */
const sasl_callback_t *prompt_supp; /* client callback list */
const char *iplocalport; /* server IP domain literal & port */
const char *ipremoteport; /* client IP domain literal & port */
unsigned servicelen; /* length of service */
unsigned slen; /* length of serverFQDN */
unsigned clen; /* length of clientFQDN */
unsigned iploclen; /* length of iplocalport */
unsigned ipremlen; /* length of ipremoteport */
/* application's security requirements & info */
sasl_security_properties_t props;
sasl_ssf_t external_ssf; /* external SSF active */
/* for additions which don't require a version upgrade; set to 0 */
const void *gss_creds; /* GSS credential handle */
const sasl_channel_binding_t *cbinding; /* client channel binding */
const sasl_http_request_t *http_request;/* HTTP Digest request method */
void *spare_ptr4;
/* Canonicalize a user name from on-wire to internal format
* added rjs3 2001-05-23
* Must be called once user name aquired if canon_user is non-NULL.
* conn connection context
* in user name from wire protocol (need not be NUL terminated)
* len length of user name from wire protocol (0 = strlen(user))
* flags for SASL_CU_* flags
* oparams the user, authid, ulen, alen, fields are
* set appropriately after canonicalization/copying and
* authorization of arguments
*
* responsible for setting user, ulen, authid, and alen in the oparams
* structure
*
* default behavior is to strip leading and trailing whitespace, as
* well as allocating space for and copying the parameters.
*
* results:
* SASL_OK -- success
* SASL_NOMEM -- out of memory
* SASL_BADPARAM -- invalid conn
* SASL_BADPROT -- invalid user/authid
*/
int (*canon_user)(sasl_conn_t *conn,
const char *in, unsigned len,
unsigned flags,
sasl_out_params_t *oparams);
int (*spare_fptr1)(void);
unsigned int cbindingdisp;
int spare_int2;
int spare_int3;
/* flags field as passed to sasl_client_new */
unsigned flags;
/* set to 0 initially, this allows a plugin with extended parameters
* to work with an older framework by updating version as parameters
* are added.
*/
int param_version;
} sasl_client_params_t;
/* features shared between client and server */
/* These allow the glue code to handle client-first and server-last issues */
/* This indicates that the mechanism prefers to do client-send-first
* if the protocol allows it. */
#define SASL_FEAT_WANT_CLIENT_FIRST 0x0002
/* This feature is deprecated. Instead, plugins should set *serverout to
* non-NULL and return SASL_OK intelligently to allow flexible use of
* server-last semantics
#define SASL_FEAT_WANT_SERVER_LAST 0x0004
*/
/* This feature is deprecated. Instead, plugins should correctly set
* SASL_FEAT_SERVER_FIRST as needed
#define SASL_FEAT_INTERNAL_CLIENT_FIRST 0x0008
*/
/* This indicates that the plugin is server-first only.
* Not defining either of SASL_FEAT_SERVER_FIRST or
* SASL_FEAT_WANT_CLIENT_FIRST indicates that the mechanism
* will handle the client-first situation internally.
*/
#define SASL_FEAT_SERVER_FIRST 0x0010
/* This plugin allows proxying */
#define SASL_FEAT_ALLOWS_PROXY 0x0020
/* server plugin don't use cleartext userPassword attribute */
#define SASL_FEAT_DONTUSE_USERPASSWD 0x0080
/* Underlying mechanism uses GSS framing */
#define SASL_FEAT_GSS_FRAMING 0x0100
/* Underlying mechanism supports channel binding */
#define SASL_FEAT_CHANNEL_BINDING 0x0800
/* This plugin can be used for HTTP authentication */
#define SASL_FEAT_SUPPORTS_HTTP 0x1000
/* client plug-in features */
#define SASL_FEAT_NEEDSERVERFQDN 0x0001
/* a C object for a client mechanism
*/
typedef struct sasl_client_plug {
/* mechanism name */
const char *mech_name;
/* best mech additional security layer strength factor */
sasl_ssf_t max_ssf;
/* best security flags, as defined in sasl_security_properties_t */
unsigned security_flags;
/* features of plugin */
unsigned features;
/* required prompt ids, NULL = user/pass only */
const unsigned long *required_prompts;
/* global state for mechanism */
void *glob_context;
/* create context for mechanism, using params supplied
* glob_context -- from above
* params -- params from sasl_client_new
* conn_context -- context for one connection
* returns:
* SASL_OK -- success
* SASL_NOMEM -- not enough memory
* SASL_WRONGMECH -- mech doesn't support security params
*/
int (*mech_new)(void *glob_context,
sasl_client_params_t *cparams,
void **conn_context);
/* perform one step of exchange. NULL is passed for serverin on
* first step.
* returns:
* SASL_OK -- success
* SASL_INTERACT -- user interaction needed to fill in prompts
* SASL_BADPROT -- server protocol incorrect/cancelled
* SASL_BADSERV -- server failed mutual auth
*/
int (*mech_step)(void *conn_context,
sasl_client_params_t *cparams,
const char *serverin,
unsigned serverinlen,
sasl_interact_t **prompt_need,
const char **clientout,
unsigned *clientoutlen,
sasl_out_params_t *oparams);
/* dispose of connection context from mech_new
*/
void (*mech_dispose)(void *conn_context, const sasl_utils_t *utils);
/* free all global space used by mechanism
* mech_dispose must be called on all mechanisms first
*/
void (*mech_free)(void *glob_context, const sasl_utils_t *utils);
/* perform precalculations during a network round-trip
* or idle period. conn_context may be NULL
* returns 1 if action taken, 0 if no action taken
*/
int (*idle)(void *glob_context,
void *conn_context,
sasl_client_params_t *cparams);
/* for additions which don't require a version upgrade; set to 0 */
int (*spare_fptr1)(void);
int (*spare_fptr2)(void);
} sasl_client_plug_t;
#define SASL_CLIENT_PLUG_VERSION 4
/* plug-in entry point:
* utils -- utility callback functions
* max_version -- highest client plug version supported
* returns:
* out_version -- client plug version of result
* pluglist -- list of mechanism plug-ins
* plugcount -- number of mechanism plug-ins
* results:
* SASL_OK -- success
* SASL_NOMEM -- failure
* SASL_BADVERS -- max_version too small
* SASL_BADPARAM -- bad config string
* ...
*/
typedef int sasl_client_plug_init_t(const sasl_utils_t *utils,
int max_version,
int *out_version,
sasl_client_plug_t **pluglist,
int *plugcount);
/* add a client plug-in
*/
LIBSASL_API int sasl_client_add_plugin(const char *plugname,
sasl_client_plug_init_t *cplugfunc);
typedef struct client_sasl_mechanism
{
int version;
char *plugname;
const sasl_client_plug_t *plug;
} client_sasl_mechanism_t;
typedef void sasl_client_info_callback_t (client_sasl_mechanism_t *m,
sasl_info_callback_stage_t stage,
void *rock);
/* Dump information about available client plugins */
LIBSASL_API int sasl_client_plugin_info (const char *mech_list,
sasl_client_info_callback_t *info_cb,
void *info_cb_rock);
/********************
* Server Functions *
********************/
/* log message formatting routine */
typedef void sasl_logmsg_p(sasl_conn_t *conn, const char *fmt, ...) __attribute__((format(printf, 2, 3)));
/*
* input parameters to server SASL plugin
*
* created / destroyed by the glue code
*
*/
typedef struct sasl_server_params {
const char *service; /* NULL = default service for user_exists
and setpass */
const char *appname; /* name of calling application */
const char *serverFQDN; /* server default fully qualified domain name
* (e.g., gethostname) */
const char *user_realm; /* realm for user (NULL = client supplied) */
const char *iplocalport; /* server IP domain literal & port */
const char *ipremoteport; /* client IP domain literal & port */
unsigned servicelen; /* length of service */
unsigned applen; /* length of appname */
unsigned slen; /* length of serverFQDN */
unsigned urlen; /* length of user_realm */
unsigned iploclen; /* length of iplocalport */
unsigned ipremlen; /* length of ipremoteport */
/* This indicates the level of logging desired. See SASL_LOG_*
* in sasl.h
*
* Plug-ins can ignore this and just pass their desired level to
* the log callback. This is primarily used to eliminate logging which
* might be a performance problem (e.g., full protocol trace) and
* to select between SASL_LOG_TRACE and SASL_LOG_PASS alternatives
*/
int log_level;
const sasl_utils_t *utils; /* SASL API utility routines --
* for a particular sasl_conn_t,
* MUST remain valid until mech_free is
* called */
const sasl_callback_t *callbacks; /* Callbacks from application */
/* application's security requirements */
sasl_security_properties_t props;
sasl_ssf_t external_ssf; /* external SSF active */
/* Pointer to the function which takes the plaintext passphrase and
* transitions a user to non-plaintext mechanisms via setpass calls.
* (NULL = auto transition not enabled/supported)
*
* If passlen is 0, it defaults to strlen(pass).
* returns 0 if no entry added, 1 if entry added
*/
int (*transition)(sasl_conn_t *conn, const char *pass, unsigned passlen);
/* Canonicalize a user name from on-wire to internal format
* added cjn 1999-09-21
* Must be called once user name acquired if canon_user is non-NULL.
* conn connection context
* user user name from wire protocol (need not be NUL terminated)
* ulen length of user name from wire protocol (0 = strlen(user))
* flags for SASL_CU_* flags
* oparams the user, authid, ulen, alen, fields are
* set appropriately after canonicalization/copying and
* authorization of arguments
*
* responsible for setting user, ulen, authid, and alen in the oparams
* structure
*
* default behavior is to strip leading and trailing whitespace, as
* well as allocating space for and copying the parameters.
*
* results:
* SASL_OK -- success
* SASL_NOMEM -- out of memory
* SASL_BADPARAM -- invalid conn
* SASL_BADPROT -- invalid user/authid
*/
int (*canon_user)(sasl_conn_t *conn,
const char *user, unsigned ulen,
unsigned flags,
sasl_out_params_t *oparams);
/* auxiliary property context (see definitions in prop.h)
* added cjn 2000-01-30
*
* NOTE: these properties are the ones associated with the
* canonicalized "user" (user to login as / authorization id), not
* the "authid" (user whose credentials are used / authentication id)
* Prefix the property name with a "*" if a property associated with
* the "authid" is interesting.
*/
struct propctx *propctx;
/* for additions which don't require a version upgrade; set to 0 */
const void *gss_creds; /* GSS credential handle */
const sasl_channel_binding_t *cbinding; /* server channel binding */
const sasl_http_request_t *http_request;/* HTTP Digest request method */
void *spare_ptr4;
int (*spare_fptr1)(void);
int (*spare_fptr2)(void);
int spare_int1;
int spare_int2;
int spare_int3;
/* flags field as passed to sasl_server_new */
unsigned flags;
/* set to 0 initially, this allows a plugin with extended parameters
* to work with an older framework by updating version as parameters
* are added.
*/
int param_version;
} sasl_server_params_t;
/* logging levels (more levels may be added later, if necessary):
*/
#define SASL_LOG_NONE 0 /* don't log anything */
#define SASL_LOG_ERR 1 /* log unusual errors (default) */
#define SASL_LOG_FAIL 2 /* log all authentication failures */
#define SASL_LOG_WARN 3 /* log non-fatal warnings */
#define SASL_LOG_NOTE 4 /* more verbose than LOG_WARN */
#define SASL_LOG_DEBUG 5 /* more verbose than LOG_NOTE */
#define SASL_LOG_TRACE 6 /* traces of internal protocols */
#define SASL_LOG_PASS 7 /* traces of internal protocols, including
* passwords */
/* additional flags for setpass() function below:
*/
/* SASL_SET_CREATE create user if pass non-NULL */
/* SASL_SET_DISABLE disable user */
#define SASL_SET_REMOVE SASL_SET_CREATE /* remove user if pass is NULL */
/* features for server plug-in
*/
#define SASL_FEAT_SERVICE 0x0200 /* service-specific passwords supported */
#define SASL_FEAT_GETSECRET 0x0400 /* sasl_server_{get,put}secret_t callbacks
* required by plug-in */
/* a C object for a server mechanism
*/
typedef struct sasl_server_plug {
/* mechanism name */
const char *mech_name;
/* best mech additional security layer strength factor */
sasl_ssf_t max_ssf;
/* best security flags, as defined in sasl_security_properties_t */
unsigned security_flags;
/* features of plugin */
unsigned features;
/* global state for mechanism */
void *glob_context;
/* create a new mechanism handler
* glob_context -- global context
* sparams -- server config params
* challenge -- server challenge from previous instance or NULL
* challen -- length of challenge from previous instance or 0
* out:
* conn_context -- connection context
* errinfo -- error information
*
* returns:
* SASL_OK -- successfully created mech instance
* SASL_* -- any other server error code
*/
int (*mech_new)(void *glob_context,
sasl_server_params_t *sparams,
const char *challenge,
unsigned challen,
void **conn_context);
/* perform one step in exchange
*
* returns:
* SASL_OK -- success, all done
* SASL_CONTINUE -- success, one more round trip
* SASL_* -- any other server error code
*/
int (*mech_step)(void *conn_context,
sasl_server_params_t *sparams,
const char *clientin,
unsigned clientinlen,
const char **serverout,
unsigned *serveroutlen,
sasl_out_params_t *oparams);
/* dispose of a connection state
*/
void (*mech_dispose)(void *conn_context, const sasl_utils_t *utils);
/* free global state for mechanism
* mech_dispose must be called on all mechanisms first
*/
void (*mech_free)(void *glob_context, const sasl_utils_t *utils);
/* set a password (optional)
* glob_context -- global context
* sparams -- service, middleware utilities, etc. props ignored
* user -- user name
* pass -- password/passphrase (NULL = disable/remove/delete)
* passlen -- length of password/passphrase
* oldpass -- old password/passphrase (NULL = transition)
* oldpasslen -- length of password/passphrase
* flags -- see above
*
* returns:
* SASL_NOCHANGE -- no change was needed
* SASL_NOUSER -- no entry for user
* SASL_NOVERIFY -- no mechanism compatible entry for user
* SASL_PWLOCK -- password locked
* SASL_DIABLED -- account disabled
* etc.
*/
int (*setpass)(void *glob_context,
sasl_server_params_t *sparams,
const char *user,
const char *pass, unsigned passlen,
const char *oldpass, unsigned oldpasslen,
unsigned flags);
/* query which mechanisms are available for user
* glob_context -- context
* sparams -- service, middleware utilities, etc. props ignored
* user -- NUL terminated user name
* maxmech -- max number of strings in mechlist (0 = no output)
* output:
* mechlist -- an array of C string pointers, filled in with
* mechanism names available to the user
*
* returns:
* SASL_OK -- success
* SASL_NOMEM -- not enough memory
* SASL_FAIL -- lower level failure
* SASL_DISABLED -- account disabled
* SASL_NOUSER -- user not found
* SASL_BUFOVER -- maxmech is too small
* SASL_NOVERIFY -- user found, but no mechanisms available
*/
int (*user_query)(void *glob_context,
sasl_server_params_t *sparams,
const char *user,
int maxmech,
const char **mechlist);
/* perform precalculations during a network round-trip
* or idle period. conn_context may be NULL (optional)
* returns 1 if action taken, 0 if no action taken
*/
int (*idle)(void *glob_context,
void *conn_context,
sasl_server_params_t *sparams);
/* check if mechanism is available
* optional--if NULL, mechanism is available based on ENABLE= in config
*
* If this routine sets conn_context to a non-NULL value, then the call
* to mech_new will be skipped. This should not be done unless
* there's a significant performance benefit, since it can cause
* additional memory allocation in SASL core code to keep track of
* contexts potentially for multiple mechanisms.
*
* This is called by the first call to sasl_listmech() for a
* given connection context, thus for a given protocol it may
* never be called. Note that if mech_avail returns SASL_NOMECH,
* then that mechanism is considered disabled for the remainder
* of the session. If mech_avail returns SASL_NOTDONE, then a
* future call to mech_avail may still return either SASL_OK
* or SASL_NOMECH.
*
* returns SASL_OK on success,
* SASL_NOTDONE if mech is not available now, but may be later
* (e.g. EXTERNAL w/o auth_id)
* SASL_NOMECH if mech disabled
*/
int (*mech_avail)(void *glob_context,
sasl_server_params_t *sparams,
void **conn_context);
/* for additions which don't require a version upgrade; set to 0 */
int (*spare_fptr2)(void);
} sasl_server_plug_t;
#define SASL_SERVER_PLUG_VERSION 4
/* plug-in entry point:
* utils -- utility callback functions
* plugname -- name of plug-in (may be NULL)
* max_version -- highest server plug version supported
* returns:
* out_version -- server plug-in version of result
* pluglist -- list of mechanism plug-ins
* plugcount -- number of mechanism plug-ins
* results:
* SASL_OK -- success
* SASL_NOMEM -- failure
* SASL_BADVERS -- max_version too small
* SASL_BADPARAM -- bad config string
* ...
*/
typedef int sasl_server_plug_init_t(const sasl_utils_t *utils,
int max_version,
int *out_version,
sasl_server_plug_t **pluglist,
int *plugcount);
/*
* add a server plug-in
*/
LIBSASL_API int sasl_server_add_plugin(const char *plugname,
sasl_server_plug_init_t *splugfunc);
typedef struct server_sasl_mechanism
{
int version;
int condition; /* set to SASL_NOUSER if no available users;
set to SASL_CONTINUE if delayed plugin loading */
char *plugname; /* for AUTHSOURCE tracking */
const sasl_server_plug_t *plug;
char *f; /* where should i load the mechanism from? */
} server_sasl_mechanism_t;
typedef void sasl_server_info_callback_t (server_sasl_mechanism_t *m,
sasl_info_callback_stage_t stage,
void *rock);
/* Dump information about available server plugins (separate functions are
used for canon and auxprop plugins) */
LIBSASL_API int sasl_server_plugin_info (const char *mech_list,
sasl_server_info_callback_t *info_cb,
void *info_cb_rock);
/*********************************************************
* user canonicalization plug-in -- added cjn 1999-09-29 *
*********************************************************/
typedef struct sasl_canonuser {
/* optional features of plugin (set to 0) */
int features;
/* spare integer (set to 0) */
int spare_int1;
/* global state for plugin */
void *glob_context;
/* name of plugin */
char *name;
/* free global state for plugin */
void (*canon_user_free)(void *glob_context, const sasl_utils_t *utils);
/* canonicalize a username
* glob_context -- global context from this structure
* sparams -- server params, note user_realm&propctx elements
* user -- user to login as (may not be NUL terminated)
* len -- length of user name (0 = strlen(user))
* flags -- for SASL_CU_* flags
* out -- buffer to copy user name
* out_max -- max length of user name
* out_len -- set to length of user name
*
* note that the output buffers MAY be the same as the input buffers.
*
* returns
* SASL_OK on success
* SASL_BADPROT username contains invalid character
*/
int (*canon_user_server)(void *glob_context,
sasl_server_params_t *sparams,
const char *user, unsigned len,
unsigned flags,
char *out,
unsigned out_umax, unsigned *out_ulen);
int (*canon_user_client)(void *glob_context,
sasl_client_params_t *cparams,
const char *user, unsigned len,
unsigned flags,
char *out,
unsigned out_max, unsigned *out_len);
/* for additions which don't require a version upgrade; set to 0 */
int (*spare_fptr1)(void);
int (*spare_fptr2)(void);
int (*spare_fptr3)(void);
} sasl_canonuser_plug_t;
#define SASL_CANONUSER_PLUG_VERSION 5
/* default name for canonuser plug-in entry point is "sasl_canonuser_init"
* similar to sasl_server_plug_init model, except only returns one
* sasl_canonuser_plug_t structure;
*/
typedef int sasl_canonuser_init_t(const sasl_utils_t *utils,
int max_version,
int *out_version,
sasl_canonuser_plug_t **plug,
const char *plugname);
/* add a canonuser plugin
*/
LIBSASL_API int sasl_canonuser_add_plugin(const char *plugname,
sasl_canonuser_init_t *canonuserfunc);
/******************************************************
* auxiliary property plug-in -- added cjn 1999-09-29 *
******************************************************/
typedef struct sasl_auxprop_plug {
/* optional features of plugin (none defined yet, set to 0) */
int features;
/* spare integer, must be set to 0 */
int spare_int1;
/* global state for plugin */
void *glob_context;
/* free global state for plugin (OPTIONAL) */
void (*auxprop_free)(void *glob_context, const sasl_utils_t *utils);
/* fill in fields of an auxiliary property context
* last element in array has id of SASL_AUX_END
* elements with non-0 len should be ignored.
*/
int (*auxprop_lookup)(void *glob_context,
sasl_server_params_t *sparams,
unsigned flags,
const char *user, unsigned ulen);
/* name of the auxprop plugin */
char *name;
/* store the fields/values of an auxiliary property context (OPTIONAL)
*
* if ctx is NULL, just check if storing properties is enabled
*
* returns
* SASL_OK on success
* SASL_FAIL on failure
*/
int (*auxprop_store)(void *glob_context,
sasl_server_params_t *sparams,
struct propctx *ctx,
const char *user, unsigned ulen);
} sasl_auxprop_plug_t;
/* auxprop lookup flags */
#define SASL_AUXPROP_OVERRIDE 0x01 /* if clear, ignore auxiliary properties
* with non-zero len field. If set,
* override value of those properties */
#define SASL_AUXPROP_AUTHZID 0x02 /* if clear, we are looking up the
* authid flags (prefixed with *), otherwise
* we are looking up the authzid flags
* (no prefix) */
/* NOTE: Keep in sync with SASL_CU_<XXX> flags */
#define SASL_AUXPROP_VERIFY_AGAINST_HASH 0x10
#define SASL_AUXPROP_PLUG_VERSION 8
/* default name for auxprop plug-in entry point is "sasl_auxprop_init"
* similar to sasl_server_plug_init model, except only returns one
* sasl_auxprop_plug_t structure;
*/
typedef int sasl_auxprop_init_t(const sasl_utils_t *utils,
int max_version,
int *out_version,
sasl_auxprop_plug_t **plug,
const char *plugname);
/* add an auxiliary property plug-in
*/
LIBSASL_API int sasl_auxprop_add_plugin(const char *plugname,
sasl_auxprop_init_t *auxpropfunc);
typedef void auxprop_info_callback_t (sasl_auxprop_plug_t *m,
sasl_info_callback_stage_t stage,
void *rock);
/* Dump information about available auxprop plugins (separate functions are
used for canon and server authentication plugins) */
LIBSASL_API int auxprop_plugin_info (const char *mech_list,
auxprop_info_callback_t *info_cb,
void *info_cb_rock);
#ifdef __cplusplus
}
#endif
#endif /* SASLPLUG_H */