courierauthsasl.h

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