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
  17 /*
  18   Callback authentication structure:
  19 */
  20
  21 struct authinfo {
  22         const char *sysusername;
  23         const uid_t *sysuserid;
  24         gid_t sysgroupid;
  25         const char *homedir;
  26
  27         const char *address;
  28         const char *fullname;
  29         const char *maildir;
  30         const char *quota;
  31
  32         const char *passwd;
  33         const char *clearpasswd;        /* For authldap */
  34
  35         const char *options;
  36
  37         } ;
  38 /*
  39         Either sysusername or sysuserid may be NULL, but not both of them.
  40         They, and sysgroupid, specify the authenticated user's system
  41         userid and groupid.  homedir points to the authenticated user's
  42         home directory.  address, fullname, and maildir, are obvious.
  43         quota is populated with any maildir quota (see
  44         maildir/README.maildirquota).
  45
  46         'options' is an optional string that contains per-user custom settings.
  47         See "OPTIONS" above.
  48
  49         After populating this tructure, the lookup function calls the
  50         callback function that's specified in its second argument.  The
  51         callback function receives a pointer to the authinfo structure.
  52
  53         The callback function also receives a context pointer, which is
  54         the third argument to the lookup function.
  55
  56         The lookup function should return a negative value if he userid
  57         does not exist, a positive value if there was a temporary error
  58         looking up the userid, or whatever is the return code from the
  59         callback function, if the user exists.
  60 */
  61
  62
  63 #define AUTHTYPE_LOGIN  "login"         /* authdata is userid\npassword\n */
  64 #define AUTHTYPE_CRAMMD5 "cram-md5"     /* authdata is challenge\nresponse\n */
  65 #define AUTHTYPE_CRAMSHA1 "cram-sha1"   /* authdata is challenge\nresponse\n */
  66 #define AUTHTYPE_CRAMSHA256 "cram-sha256"       /* authdata is challenge\nresponse\n */
  67
  68         /* auth_generic: INTERNAL */
  69
  70 int auth_generic(const char *service,
  71                  const char *authtype,
  72                  char *authdata,
  73                  int (*callback_func)(struct authinfo *, void *),
  74                  void *callback_arg);
  75
  76         /* Login request: */
  77 int auth_login(const char *service,
  78                const char *userid,
  79                const char *passwd,
  80                int (*callback_func)(struct authinfo *, void *),
  81                void *callback_arg);
  82
  83         /* Return account info: */
  84 int auth_getuserinfo(const char *service, const char *uid,
  85                      int (*callback)(struct authinfo *, void *),
  86                      void *arg);
  87
  88         /* Enumerate accounts */
  89 void auth_enumerate( void(*cb_func)(const char *name,
  90                                     uid_t uid,
  91                                     gid_t gid,
  92                                     const char *homedir,
  93                                     const char *maildir,
  94                                     const char *options,
  95                                     void *void_arg),
  96                      void *void_arg);
  97
  98         /* Change the password */
  99 int auth_passwd(const char *service,
 100                 const char *uid,
 101                 const char *opwd,
 102                 const char *npwd);
 103
 104 /* Utility function: parse OPTIONS string for a particular keyword */
 105
 106 extern int auth_getoptionenvint(const char *keyword);
 107 extern char *auth_getoptionenv(const char *keyword);
 108 extern char *auth_getoption(const char *options, const char *keyword);
 109
 110
 111         /*
 112         ** Utility function: typical action in a callback for auth_generic
 113         ** or auth_login.  Does the following:
 114         **
 115         ** Drops root, takes uid/gid in ainfo.
 116         **
 117         ** Changes current directory to the home directory.
 118         **
 119         ** Returns: <0 - fatal error before dropping root.
 120         **          >0 - fatal error after dropping root.
 121         **          =0 - all's OK.
 122         */
 123
 124 int auth_callback_default(struct authinfo *ainfo);
 125
 126         /* Utility function: escape LDAP special characters */
 127
 128 char *courier_auth_ldap_escape(const char *str);
 129 #ifdef  __cplusplus
 130 }
 131 #endif
 132
 133 #endif