courierauth.h

   1 #ifndef courierauth_h
   2 #define courierauth_h
   3
   4 /*
   5 ** Copyright 2004 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 #if 0
  17 }
  18 #endif
  19
  20 /*
  21   Callback authentication structure:
  22 */
  23
  24 struct authinfo {
  25         const char *sysusername;
  26         const uid_t *sysuserid;
  27         gid_t sysgroupid;
  28         const char *homedir;
  29
  30         const char *address;
  31         const char *fullname;
  32         const char *maildir;
  33         const char *quota;
  34
  35         const char *passwd;
  36         const char *clearpasswd;        /* For authldap */
  37
  38         const char *options;
  39
  40         } ;
  41 /*
  42         Either sysusername or sysuserid may be NULL, but not both of them.
  43         They, and sysgroupid, specify the authenticated user's system
  44         userid and groupid.  homedir points to the authenticated user's
  45         home directory.  address, fullname, and maildir, are obvious.
  46         quota is populated with any maildir quota (see
  47         maildir/README.maildirquota).
  48
  49         'options' is an optional string that contains per-user custom settings.
  50         See "OPTIONS" above.
  51
  52         After populating this tructure, the lookup function calls the
  53         callback function that's specified in its second argument.  The
  54         callback function receives a pointer to the authinfo structure.
  55
  56         The callback function also receives a context pointer, which is
  57         the third argument to the lookup function.
  58
  59         The lookup function should return a negative value if he userid
  60         does not exist, a positive value if there was a temporary error
  61         looking up the userid, or whatever is the return code from the
  62         callback function, if the user exists.
  63 */
  64
  65
  66 #define AUTHTYPE_LOGIN  "login"         /* authdata is userid\npassword\n */
  67 #define AUTHTYPE_CRAMMD5 "cram-md5"     /* authdata is challenge\nresponse\n */
  68 #define AUTHTYPE_CRAMSHA1 "cram-sha1"   /* authdata is challenge\nresponse\n */
  69 #define AUTHTYPE_CRAMSHA256 "cram-sha256"       /* authdata is challenge\nresponse\n */
  70
  71         /* auth_generic: INTERNAL */
  72
  73 int auth_generic(const char *service,
  74                  const char *authtype,
  75                  char *authdata,
  76                  int (*callback_func)(struct authinfo *, void *),
  77                  void *callback_arg);
  78
  79         /* Login request: */
  80 int auth_login(const char *service,
  81                const char *userid,
  82                const char *passwd,
  83                int (*callback_func)(struct authinfo *, void *),
  84                void *callback_arg);
  85
  86         /* Return account info: */
  87 int auth_getuserinfo(const char *service, const char *uid,
  88                      int (*callback)(struct authinfo *, void *),
  89                      void *arg);
  90
  91         /* Enumerate accounts */
  92 void auth_enumerate( void(*cb_func)(const char *name,
  93                                     uid_t uid,
  94                                     gid_t gid,
  95                                     const char *homedir,
  96                                     const char *maildir,
  97                                     const char *options,
  98                                     void *void_arg),
  99                      void *void_arg);
 100
 101         /* Change the password */
 102 int auth_passwd(const char *service,
 103                 const char *uid,
 104                 const char *opwd,
 105                 const char *npwd);
 106
 107 /* Utility function: parse OPTIONS string for a particular keyword */
 108
 109 extern int auth_getoptionenvint(const char *keyword);
 110 extern char *auth_getoptionenv(const char *keyword);
 111 extern char *auth_getoption(const char *options, const char *keyword);
 112
 113
 114         /*
 115         ** Utility function: typical action in a callback for auth_generic
 116         ** or auth_login.  Does the following:
 117         **
 118         ** Drops root, takes uid/gid in ainfo.
 119         **
 120         ** Changes current directory to the home directory.
 121         **
 122         ** Returns: <0 - fatal error before dropping root.
 123         **          >0 - fatal error after dropping root.
 124         **          =0 - all's OK.
 125         */
 126
 127 int auth_callback_default(struct authinfo *ainfo);
 128
 129 /*
 130 ** If the AUTH_MKHOMEDIR_SKEL environment variable is set, and the
 131 ** authenticated account's home directory does not exist, the home directory
 132 ** gets created, with its initial contents copied from AUTH_MKHOMEDIR_SKEL
 133 ** which must be a directory, typically /etc/skel.
 134 */
 135
 136 int auth_mkhomedir(struct authinfo *info);
 137
 138 /*
 139 ** Like auth_callback_default, but calls auth_mkhomedir().
 140 */
 141
 142 int auth_callback_default_autocreate(struct authinfo *ainfo);
 143
 144         /* Utility function: escape LDAP special characters */
 145
 146 char *courier_auth_ldap_escape(const char *str);
 147
 148 struct cram_callback_info {
 149         struct hmac_hashinfo *h;
 150         char *user;
 151         char *challenge;
 152         char *response;
 153         int (*callback_func)(struct authinfo *, void *);
 154         void *callback_arg;
 155         };
 156
 157 extern int auth_cram_callback(struct authinfo *a, void *vp);
 158
 159 /*
 160 ** auth_get_cram parses out an authentication request.  It checks whether
 161 ** we have the requisite hash function installed, and, if so, base64decodes
 162 ** the challenge and the response.
 163 */
 164
 165 struct hmac_hashinfo;
 166
 167 int auth_get_cram(const char *authtype,                 /* authtype */
 168                   char *authdata,                       /* authdata */
 169
 170                   struct cram_callback_info *craminfo);
 171                 /* Initializes craminfo */
 172
 173 /* auth_get_cram_silent() is auth_get_cram(), but without logging */
 174
 175 int auth_get_cram_silent(const char *authtype, char *authdata,
 176                          struct cram_callback_info *craminfo);
 177
 178 /*
 179 ** auth_verify_cram attempts to verify the secret cookie.
 180 */
 181
 182 int auth_verify_cram(struct hmac_hashinfo *,    /* The hash function */
 183         const char *,                           /* The challenge */
 184         const char *,                           /* The response */
 185         const char *);                          /* Hashed secret, in hex */
 186
 187 #if 0
 188 {
 189 #endif
 190
 191 #ifdef  __cplusplus
 192 }
 193 #endif
 194
 195 #endif