/*
* Copyright 2003 Sun Microsystems, Inc. All rights reserved.
* Use is subject to license terms.
*/
/* saslplug.h -- API for SASL plug-ins */
#ifndef _SASL_SASLPLUG_H
#define _SASL_SASLPLUG_H
#pragma ident "%Z%%M% %I% %E% SMI"
#ifndef _SASL_SASL_H
#endif
#ifndef _MD5_H
#include <md5.h>
#endif /* _MD5_H */
#ifdef __cplusplus
extern "C" {
#endif
/* intermediate MD5 context */
typedef struct HMAC_MD5_CTX_s {
} HMAC_MD5_CTX;
/*
* intermediate HMAC state
* values stored in network byte order (Big Endian)
*/
typedef struct HMAC_MD5_STATE_s {
/*
* 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
*/
unsigned long callbackid,
int (**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
*/
/* utility function set for plug-ins */
typedef struct sasl_utils {
int version;
/* contexts */
void *getopt_context;
/* option function */
/* allocation functions: */
/* mutex functions: */
/* MD5 hash and HMAC functions */
unsigned char [16]);
/* hmac_md5_update() is just a call to MD5Update on inner context */
/* mechanism utility functions (same as above): */
unsigned hostflag);
/*
* 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.
*/
/* erase a buffer */
/* callback to sasl_getprop() and sasl_setprop() */
/* callback function */
/*
* format a message and then pass it to the SASL_CB_LOG callback
*
* use syslog()-style formatting (printf with %m as most recent errno
* error). 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)
*/
/* callback to sasl_seterror() */
/* spare function pointer */
int *(*spare_fptr)();
/* auxiliary property utilities */
const char **values);
/* for additions which don't require a version upgrade; set to 0 */
int (*spare_fptr1)();
int (*spare_fptr2)();
int (*spare_fptr3)();
} 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 {
/* security layer information */
unsigned maxoutbuf;
/* security layer was *attempted*, even if */
/* the negotiation failed */
void *encode_context;
void *decode_context;
/* for additions which don't require a version upgrade; set to 0 */
void *spare_ptr1;
void *spare_ptr2;
void *spare_ptr3;
void *spare_ptr4;
int (*spare_fptr1)();
int (*spare_fptr2)();
int spare_int1;
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;
/*
* Client Mechanism Functions
*/
/*
* input parameters to client SASL plugin
*
* created / destroyed by the glue code
*
*/
typedef struct sasl_client_params {
/* for a particular sasl_conn_t, */
/* MUST remain valid until mech_free is */
/* called */
/* application's security requirements & info */
/* for additions which don't require a version upgrade; set to 0 */
void *spare_ptr1;
void *spare_ptr2;
void *spare_ptr3;
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
*/
unsigned flags,
int (*spare_fptr1)();
int spare_int1;
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;
/* 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.
*/
/*
* 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 take care
* of the client-first situation internally.
*/
/* This plugin allows proxying */
/* client plug-in features */
/* 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 */
/* best security flags, as defined in sasl_security_properties_t */
unsigned security_flags;
/* features of plugin */
unsigned features;
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
*/
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_BADSERV -- server failed mutual auth
*/
const char *serverin,
unsigned serverinlen,
const char **clientout,
unsigned *clientoutlen,
/* dispose of connection context from mech_new */
/*
* free all global space used by mechanism
* mech_dispose must be called on all mechanisms first
*/
/*
* 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
*/
void *conn_context,
/* for additions which don't require a version upgrade; set to 0 */
int (*spare_fptr1)();
int (*spare_fptr2)();
/*
* 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
* ...
*/
int max_version,
int *out_version,
int *plugcount);
/* add a client plug-in */
/*
* Server Functions
*/
/*
* input parameters to server SASL plugin
*
* created / destroyed by the glue code
*
*/
typedef struct sasl_server_params {
/* and setpass */
/* (e.g., gethostname) */
/*
* 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;
/* for a particular sasl_conn_t, */
/* MUST remain valid until mech_free is */
/* called */
/* application's security requirements */
/*
* server plug-in calls this when it first has access to the plaintext
* passphrase. This is used to transition users via setpass calls.
* If passlen is 0, it defaults to strlen(pass).
* returns 0 if no entry added, 1 if entry added
*/
/*
* Canonicalize a user name from on-wire to internal format
* added cjn 1999-09-21
* Must be called once user name aquired 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
*/
unsigned flags,
/*
* 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.
*/
/* for additions which don't require a version upgrade; set to 0 */
void *spare_ptr1;
void *spare_ptr2;
void *spare_ptr3;
void *spare_ptr4;
int (*spare_fptr1)();
int (*spare_fptr2)();
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;
/* features for server plug-in */
/* 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 */
/* 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
*/
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
*/
const char *clientin,
unsigned clientinlen,
const char **serverout,
unsigned *serveroutlen,
/* dispose of a connection state */
/*
* free global state for mechanism
* mech_dispose must be called on all mechanisms first
*/
/*
* 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.
*/
const char *user,
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
*/
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
*/
void *conn_context,
/*
* check if mechanism is available
* TODO - Is this correct?
* 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.
*
* returns SASL_OK on success,
* SASL_NOMECH if mech disabled
*/
void **conn_context);
/* for additions which don't require a version upgrade; set to 0 */
int (*spare_fptr2)();
/*
* 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
* ...
*/
int max_version,
int *out_version,
int *plugcount);
/*
* add a server plug-in
*/
/*
* 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 */
/*
* 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
*/
unsigned flags,
char *out,
unsigned flags,
char *out,
/* for additions which don't require a version upgrade; set to 0 */
int (*spare_fptr1)();
int (*spare_fptr2)();
int (*spare_fptr3)();
/*
* 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;
*/
int max_version,
int *out_version,
const char *plugname);
/* add a canonuser plugin */
/*
* 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) */
/*
* 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.
*/
unsigned flags,
/* name of the auxprop plugin */
char *name;
/* for additions which don't require a version upgrade; set to 0 */
void (*spare_fptr1)();
/* auxprop lookup flags */
/* with non-zero len field. If set, */
/* override value of those properties */
/* authid flags (prefixed with *), */
/* otherwise we are looking up the */
/* authzid flags (no prefix) */
/*
* 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;
*/
int max_version,
int *out_version,
const char *plugname);
/* add an auxiliary property plug-in */
#ifdef __cplusplus
}
#endif
#endif /* _SASL_SASLPLUG_H */