[hcoop/debian/courier-authlib.git] / courierauthsasl.h

#ifndef	courierauthsasl_h
#define	courierauthsasl_h

/*
** Copyright 1998 - 2008 Double Precision, Inc.  See COPYING for
** distribution information.
*/

#include	"courier_auth_config.h"
#include	<sys/types.h>

#ifdef	__cplusplus
extern "C" {
#endif

static const char courierauthsasl_h_rcsid[]="$Id: courierauthsasl.h,v 1.3 2008/12/02 03:41:19 mrsam Exp $";

/*
	These family of functions are used to implement the SASL interface
	on top of authlib.  It is mainly used by the authentication user
	process to build the authentication request data for authmod()
	based upon the SASL challenge/response interaction.
*/

/*
**	auth_sasl searches for the right method, and calls the appropriate
**	sasl function.  authsasl received the following arguments:
**
**	initresponse -- initial response for the authentication request,
**	if provided.  If provided, the actual response MUST BE PROVIDED
**	in initresponse using base64 encoding!!!
**
**	sasl_func -- the callback function which is used to carry out the
**	SASL conversation.  The function receives a single argument, the
**	base64-encoded challenge.  The callback function must return
**	a malloced pointer to the base64-encoded response, or NULL to abort
**	SASL.
**
**	authsasl returns two values, provided via call by reference:
**	the authtype and authdata, suitable for direct arguments to
**	auth_generic().
*/

int auth_sasl(const char *,		/* Method */
	      const char *,		/* Initial response - base64encoded */
	      char *(*)(const char *, void *),
					/* Callback conversation functions */
	      void *,			/* Passthrough arg */
	      char **,			/* Returned - AUTHTYPE */
	      char **);			/* Returned - AUTHDATA */

/*
** auth_sasl_ex() is a version of auth_sasl that takes an extra parameter,
** externalauth. If method is "EXTERNAL" and externalauth is not a NULL pointer
** and does not point to an empty string, it is recognized as a SASL EXTERRNAL
** authentication.
*/

int auth_sasl_ex(const char *method,
		 const char *initresponse,
		 const char *externalauth, /* out-of-band authentified identity */
		 char *(*callback_func)(const char *, void *),
		 void *callback_arg,
		 char **authtype_ptr,
		 char **authdata_ptr);

	/* INTERNAL FUNCTIONS BELOW */

/*
** The authsasl_info is built dynamically by configure, it lists the supported
** SASL methods.  Each method is implemented by a function that's prototyped
** like this:
**
**  int authsasl_function(const char *method, const char *initresponse,
**      char *(*getresp)(const char *),
**
**	char **authtype,
**	char **authdata)
**
** Normally, there's no need to call the appropriate function directly, as
** authsasl() automatically searches this array, and finds one.
**
*/

struct authsasl_info {
	const char *sasl_method;	/* In uppercase */
	int (*sasl_func)(const char *method, const char *initresponse,
			 char *(*getresp)(const char *, void *),
			 void *,
			 char **,
			 char **);
	} ;

extern struct authsasl_info authsasl_list[];
/* Some convenience functions */

char *authsasl_tobase64(const char *, int);
int authsasl_frombase64(char *);

/* Return values from authsasl */

#define	AUTHSASL_OK	0
#define	AUTHSASL_ERROR	-1	/*
				** System error, usually malloc failure,
				** authsasl reports the error to stderr.
				*/

#define	AUTHSASL_ABORTED -2	/*
				** SASL exchange aborted. authsasl does NOT
				** report any errors.
				*/

#ifdef	__cplusplus
}
#endif

#endif
Commit	Line	Data
d9898ee8	1	#ifndef courierauthsasl_h
	2	#define courierauthsasl_h
	3
	4	/*
8d138742	5	** Copyright 1998 - 2008 Double Precision, Inc. See COPYING for
d9898ee8	6	** distribution information.
	7	*/
	8
	9	#include "courier_auth_config.h"
	10	#include <sys/types.h>
	11
	12	#ifdef __cplusplus
	13	extern "C" {
	14	#endif
	15
8d138742	16	static const char courierauthsasl_h_rcsid[]="$Id: courierauthsasl.h,v 1.3 2008/12/02 03:41:19 mrsam Exp $";
d9898ee8	17
	18	/*
	19	These family of functions are used to implement the SASL interface
	20	on top of authlib. It is mainly used by the authentication user
	21	process to build the authentication request data for authmod()
	22	based upon the SASL challenge/response interaction.
	23	*/
	24
	25	/*
ac40fd9e	26	** auth_sasl searches for the right method, and calls the appropriate
d9898ee8	27	** sasl function. authsasl received the following arguments:
	28	**
	29	** initresponse -- initial response for the authentication request,
	30	** if provided. If provided, the actual response MUST BE PROVIDED
	31	** in initresponse using base64 encoding!!!
	32	**
	33	** sasl_func -- the callback function which is used to carry out the
	34	** SASL conversation. The function receives a single argument, the
	35	** base64-encoded challenge. The callback function must return
	36	** a malloced pointer to the base64-encoded response, or NULL to abort
	37	** SASL.
	38	**
	39	** authsasl returns two values, provided via call by reference:
	40	** the authtype and authdata, suitable for direct arguments to
	41	** auth_generic().
	42	*/
	43
	44	int auth_sasl(const char , / Method */
	45	const char , / Initial response - base64encoded */
	46	char ()(const char , void ),
	47	/* Callback conversation functions */
	48	void , / Passthrough arg */
	49	char *, / Returned - AUTHTYPE */
	50	char *); / Returned - AUTHDATA */
	51
ac40fd9e	52	/*
	53	** auth_sasl_ex() is a version of auth_sasl that takes an extra parameter,
	54	** externalauth. If method is "EXTERNAL" and externalauth is not a NULL pointer
	55	** and does not point to an empty string, it is recognized as a SASL EXTERRNAL
	56	** authentication.
	57	*/
	58
	59	int auth_sasl_ex(const char *method,
	60	const char *initresponse,
	61	const char externalauth, / out-of-band authentified identity */
	62	char (callback_func)(const char , void ),
	63	void *callback_arg,
	64	char **authtype_ptr,
	65	char **authdata_ptr);
d9898ee8	66
	67	/* INTERNAL FUNCTIONS BELOW */
	68
	69	/*
	70	** The authsasl_info is built dynamically by configure, it lists the supported
	71	** SASL methods. Each method is implemented by a function that's prototyped
	72	** like this:
	73	**
	74	** int authsasl_function(const char method, const char initresponse,
	75	** char (getresp)(const char *),
	76	**
	77	char authtype,
	78	char authdata)
	79	**
	80	** Normally, there's no need to call the appropriate function directly, as
	81	** authsasl() automatically searches this array, and finds one.
	82	**
	83	*/
	84
	85	struct authsasl_info {
	86	const char sasl_method; / In uppercase */
	87	int (sasl_func)(const char method, const char *initresponse,
	88	char (getresp)(const char , void ),
	89	void *,
	90	char **,
	91	char **);
	92	} ;
	93
	94	extern struct authsasl_info authsasl_list[];
	95	/* Some convenience functions */
	96
	97	char authsasl_tobase64(const char , int);
	98	int authsasl_frombase64(char *);
	99
	100	/* Return values from authsasl */
	101
	102	#define AUTHSASL_OK 0
	103	#define AUTHSASL_ERROR -1 /*
	104	** System error, usually malloc failure,
	105	** authsasl reports the error to stderr.
	106	*/
	107
	108	#define AUTHSASL_ABORTED -2 /*
	109	** SASL exchange aborted. authsasl does NOT
	110	** report any errors.
	111	*/
	112
	113	#ifdef __cplusplus
	114	}
	115	#endif
	116
	117	#endif