home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / sasl / sasl.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-05-27  |  48.7 KB  |  1,262 lines
  1. /* This is a proposed C API for support of SASL
  2.  *
  3.  *********************************IMPORTANT*******************************
  4.  * send email to chris.newman@innosoft.com and cyrus-bugs@andrew.cmu.edu *
  5.  * if you need to add new error codes, callback types, property values,  *
  6.  * etc.   It is important to keep the multiple implementations of this   *
  7.  * API from diverging.                                                   *
  8.  *********************************IMPORTANT*******************************
  9.  *
  10.  * Basic Type Summary:
  11.  *  sasl_conn_t       Context for a SASL connection negotiation
  12.  *  sasl_ssf_t        Security layer Strength Factor
  13.  *  sasl_callback_t   A typed client/server callback function and context
  14.  *  sasl_interact_t   A client interaction descriptor
  15.  *  sasl_secret_t     A client password
  16.  *  sasl_rand_t       Random data context structure
  17.  *  sasl_security_properties_t  An application's required security level
  18.  *
  19.  * Callbacks:
  20.  *  sasl_getopt_t     client/server: Get an option value
  21.  *  sasl_logmsg_t     client/server: Log message handler
  22.  *  sasl_getsimple_t  client: Get user/language list
  23.  *  sasl_getsecret_t  client: Get authentication secret
  24.  *  sasl_chalprompt_t client: Display challenge and prompt for response
  25.  *
  26.  * Server only Callbacks:
  27.  *  sasl_authorize_t             user authorization policy callback
  28.  *  sasl_getconfpath_t           get path to search for config file
  29.  *  sasl_server_userdb_checkpass check password and auxprops in userdb
  30.  *  sasl_server_userdb_setpass   set password in userdb
  31.  *  sasl_server_canon_user       canonicalize username routine
  32.  *
  33.  * Client/Server Function Summary:
  34.  *  sasl_done         Release all SASL global state
  35.  *  sasl_dispose      Connection done: Dispose of sasl_conn_t
  36.  *  sasl_getprop      Get property (e.g., user name, security layer info)
  37.  *  sasl_setprop      Set property (e.g., external ssf)
  38.  *  sasl_errdetail    Generate string from last error on connection
  39.  *  sasl_errstring    Translate sasl error code to a string
  40.  *  sasl_encode       Encode data to send using security layer
  41.  *  sasl_decode       Decode data received using security layer
  42.  *  
  43.  * Utility functions:
  44.  *  sasl_encode64     Encode data to send using MIME base64 encoding
  45.  *  sasl_decode64     Decode data received using MIME base64 encoding
  46.  *  sasl_erasebuffer  Erase a buffer
  47.  *
  48.  * Client Function Summary:
  49.  *  sasl_client_init  Load and initialize client plug-ins (call once)
  50.  *  sasl_client_new   Initialize client connection context: sasl_conn_t
  51.  *  sasl_client_start Select mechanism for connection
  52.  *  sasl_client_step  Perform one authentication step
  53.  *
  54.  * Server Function Summary
  55.  *  sasl_server_init  Load and initialize server plug-ins (call once)
  56.  *  sasl_server_new   Initialize server connection context: sasl_conn_t
  57.  *  sasl_listmech     Create list of available mechanisms
  58.  *  sasl_server_start Begin an authentication exchange
  59.  *  sasl_server_step  Perform one authentication exchange step
  60.  *  sasl_checkpass    Check a plaintext passphrase
  61.  *  sasl_checkapop    Check an APOP challenge/response (uses pseudo "APOP"
  62.  *                    mechanism similar to CRAM-MD5 mechanism; optional)
  63.  *  sasl_user_exists  Check if user exists
  64.  *  sasl_setpass      Change a password or add a user entry
  65.  *  sasl_auxprop_request  Request auxiliary properties
  66.  *  sasl_auxprop_getctx   Get auxiliary property context for connection
  67.  *  sasl_auxprop_store    Store a set of auxiliary properties
  68.  *
  69.  * Basic client model:
  70.  *  1. client calls sasl_client_init() at startup to load plug-ins
  71.  *  2. when connection formed, call sasl_client_new()
  72.  *  3. once list of supported mechanisms received from server, client
  73.  *     calls sasl_client_start().  goto 4a
  74.  *  4. client calls sasl_client_step()
  75.  * [4a. If SASL_INTERACT, fill in prompts and goto 4
  76.  *      -- doesn't happen if callbacks provided]
  77.  *  4b. If SASL error, goto 7 or 3
  78.  *  4c. If SASL_OK, continue or goto 6 if last server response was success
  79.  *  5. send message to server, wait for response
  80.  *  5a. On data or success with server response, goto 4
  81.  *  5b. On failure goto 7 or 3
  82.  *  5c. On success with no server response continue
  83.  *  6. continue with application protocol until connection closes
  84.  *     call sasl_getprop/sasl_encode/sasl_decode() if using security layer
  85.  *  7. call sasl_dispose(), may return to step 2
  86.  *  8. call sasl_done() when program terminates
  87.  *
  88.  * Basic Server model:
  89.  *  1. call sasl_server_init() at startup to load plug-ins
  90.  *  2. On connection, call sasl_server_new()
  91.  *  3. call sasl_listmech() and send list to client]
  92.  *  4. after client AUTH command, call sasl_server_start(), goto 5a
  93.  *  5. call sasl_server_step()
  94.  *  5a. If SASL_CONTINUE, output to client, wait response, repeat 5
  95.  *  5b. If SASL error, then goto 7
  96.  *  5c. If SASL_OK, move on
  97.  *  6. continue with application protocol until connection closes
  98.  *     call sasl_getprop to get username
  99.  *     call sasl_getprop/sasl_encode/sasl_decode() if using security layer
  100.  *  7. call sasl_dispose(), may return to step 2
  101.  *  8. call sasl_done() when program terminates
  102.  *
  103.  *************************************************
  104.  * IMPORTANT NOTE: server realms / username syntax
  105.  *
  106.  * If a user name contains a "@", then the rightmost "@" in the user name
  107.  * separates the account name from the realm in which this account is
  108.  * located.  A single server may support multiple realms.  If the
  109.  * server knows the realm at connection creation time (e.g., a server
  110.  * with multiple IP addresses tightly binds one address to a specific
  111.  * realm) then that realm must be passed in the user_realm field of
  112.  * the sasl_server_new call.  If user_realm is non-empty and an
  113.  * unqualified user name is supplied, then the canon_user facility is
  114.  * expected to append "@" and user_realm to the user name.  The canon_user
  115.  * facility may treat other characters such as "%" as equivalent to "@".
  116.  *
  117.  * If the server forbids the use of "@" in user names for other
  118.  * purposes, this simplifies security validation.
  119.  */
  120.  
  121. #ifndef SASL_H
  122. #define SASL_H 1
  123.  
  124. /* Keep in sync with win32/common.mak */
  125. #define SASL_VERSION_MAJOR 2
  126. #define SASL_VERSION_MINOR 1
  127. #define SASL_VERSION_STEP 22
  128.  
  129. /* A convenience macro: same as was defined in the OpenLDAP LDAPDB */
  130. #define SASL_VERSION_FULL ((SASL_VERSION_MAJOR << 16) |\
  131.       (SASL_VERSION_MINOR << 8) | SASL_VERSION_STEP)
  132.  
  133. #include "prop.h"
  134.  
  135. /*************
  136.  * Basic API *
  137.  *************/
  138.  
  139. /* SASL result codes: */
  140. #define SASL_CONTINUE    1   /* another step is needed in authentication */
  141. #define SASL_OK          0   /* successful result */
  142. #define SASL_FAIL       -1   /* generic failure */
  143. #define SASL_NOMEM      -2   /* memory shortage failure */
  144. #define SASL_BUFOVER    -3   /* overflowed buffer */
  145. #define SASL_NOMECH     -4   /* mechanism not supported */
  146. #define SASL_BADPROT    -5   /* bad protocol / cancel */
  147. #define SASL_NOTDONE    -6   /* can't request info until later in exchange */
  148. #define SASL_BADPARAM   -7   /* invalid parameter supplied */
  149. #define SASL_TRYAGAIN   -8   /* transient failure (e.g., weak key) */
  150. #define SASL_BADMAC    -9   /* integrity check failed */
  151. #define SASL_NOTINIT    -12  /* SASL library not initialized */
  152.                              /* -- client only codes -- */
  153. #define SASL_INTERACT    2   /* needs user interaction */
  154. #define SASL_BADSERV    -10  /* server failed mutual authentication step */
  155. #define SASL_WRONGMECH  -11  /* mechanism doesn't support requested feature */
  156.                              /* -- server only codes -- */
  157. #define SASL_BADAUTH    -13  /* authentication failure */
  158. #define SASL_NOAUTHZ    -14  /* authorization failure */
  159. #define SASL_TOOWEAK    -15  /* mechanism too weak for this user */
  160. #define SASL_ENCRYPT    -16  /* encryption needed to use mechanism */
  161. #define SASL_TRANS      -17  /* One time use of a plaintext password will
  162.                 enable requested mechanism for user */
  163. #define SASL_EXPIRED    -18  /* passphrase expired, has to be reset */
  164. #define SASL_DISABLED   -19  /* account disabled */
  165. #define SASL_NOUSER     -20  /* user not found */
  166. #define SASL_BADVERS    -23  /* version mismatch with plug-in */
  167. #define SASL_UNAVAIL    -24  /* remote authentication server unavailable */
  168. #define SASL_NOVERIFY   -26  /* user exists, but no verifier for user */
  169.                  /* -- codes for password setting -- */
  170. #define SASL_PWLOCK     -21  /* passphrase locked */
  171. #define SASL_NOCHANGE   -22  /* requested change was not needed */
  172. #define SASL_WEAKPASS   -27  /* passphrase is too weak for security policy */
  173. #define SASL_NOUSERPASS -28  /* user supplied passwords not permitted */
  174.  
  175. /* max size of a sasl mechanism name */
  176. #define SASL_MECHNAMEMAX 20
  177.  
  178. #ifdef _WIN32
  179. /* Define to have the same layout as a WSABUF */
  180. #ifndef STRUCT_IOVEC_DEFINED
  181. #define STRUCT_IOVEC_DEFINED 1
  182. struct iovec {
  183.     long iov_len;
  184.     char *iov_base;
  185. };
  186. #endif
  187. #else
  188. struct iovec;                     /* Defined in OS headers */
  189. #endif
  190.  
  191.  
  192. /* per-connection SASL negotiation state for client or server
  193.  */
  194. typedef struct sasl_conn sasl_conn_t;
  195.  
  196. /* Plain text password structure.
  197.  *  len is the length of the password, data is the text.
  198.  */
  199. typedef struct sasl_secret {
  200.     unsigned long len;
  201.     unsigned char data[1];        /* variable sized */
  202. } sasl_secret_t;
  203.  
  204. /* random data context structure
  205.  */
  206. typedef struct sasl_rand_s sasl_rand_t;
  207.  
  208. #ifdef __cplusplus
  209. extern "C" {
  210. #endif
  211.  
  212. /****************************
  213.  * Configure Basic Services *
  214.  ****************************/
  215.  
  216. /* the following functions are used to adjust how allocation and mutexes work
  217.  * they must be called before all other SASL functions:
  218.  */
  219.  
  220. /* memory allocation functions which may optionally be replaced:
  221.  */
  222. typedef void *sasl_malloc_t(unsigned long);
  223. typedef void *sasl_calloc_t(unsigned long, unsigned long);
  224. typedef void *sasl_realloc_t(void *, unsigned long);
  225. typedef void sasl_free_t(void *);
  226.  
  227. LIBSASL_API void sasl_set_alloc(sasl_malloc_t *,
  228.                 sasl_calloc_t *,
  229.                 sasl_realloc_t *,
  230.                 sasl_free_t *);
  231.  
  232. /* mutex functions which may optionally be replaced:
  233.  *  sasl_mutex_alloc allocates a mutex structure
  234.  *  sasl_mutex_lock blocks until mutex locked
  235.  *   returns -1 on deadlock or parameter error
  236.  *   returns 0 on success
  237.  *  sasl_mutex_unlock unlocks mutex if it's locked
  238.  *   returns -1 if not locked or parameter error
  239.  *   returns 0 on success
  240.  *  sasl_mutex_free frees a mutex structure
  241.  */
  242. typedef void *sasl_mutex_alloc_t(void);
  243. typedef int sasl_mutex_lock_t(void *mutex);
  244. typedef int sasl_mutex_unlock_t(void *mutex);
  245. typedef void sasl_mutex_free_t(void *mutex);
  246. LIBSASL_API void sasl_set_mutex(sasl_mutex_alloc_t *, sasl_mutex_lock_t *,
  247.                 sasl_mutex_unlock_t *, sasl_mutex_free_t *);
  248.  
  249. /*****************************
  250.  * Security preference types *
  251.  *****************************/
  252.  
  253. /* security layer strength factor -- an unsigned integer usable by the caller
  254.  *  to specify approximate security layer strength desired.  Roughly
  255.  *  correlated to effective key length for encryption.
  256.  * 0   = no protection
  257.  * 1   = integrity protection only
  258.  * 40  = 40-bit DES or 40-bit RC2/RC4
  259.  * 56  = DES
  260.  * 112 = triple-DES
  261.  * 128 = 128-bit RC2/RC4/BLOWFISH
  262.  * 256 = baseline AES
  263.  */
  264. typedef unsigned sasl_ssf_t;
  265.  
  266. /* usage flags provided to sasl_server_new and sasl_client_new:
  267.  */
  268. #define SASL_SUCCESS_DATA    0x0004 /* server supports data on success */
  269. #define SASL_NEED_PROXY      0x0008 /* require a mech that allows proxying */
  270.  
  271. /***************************
  272.  * Security Property Types *
  273.  ***************************/
  274.  
  275. /* Structure specifying the client or server's security policy
  276.  * and optional additional properties.
  277.  */
  278.  
  279. /* These are the various security flags apps can specify. */
  280. /* NOPLAINTEXT          -- don't permit mechanisms susceptible to simple
  281.  *                         passive attack (e.g., PLAIN, LOGIN)
  282.  * NOACTIVE             -- protection from active (non-dictionary) attacks
  283.  *                         during authentication exchange.
  284.  *                         Authenticates server.
  285.  * NODICTIONARY         -- don't permit mechanisms susceptible to passive
  286.  *                         dictionary attack
  287.  * FORWARD_SECRECY      -- require forward secrecy between sessions
  288.  *                         (breaking one won't help break next)
  289.  * NOANONYMOUS          -- don't permit mechanisms that allow anonymous login
  290.  * PASS_CREDENTIALS     -- require mechanisms which pass client
  291.  *               credentials, and allow mechanisms which can pass
  292.  *               credentials to do so
  293.  * MUTUAL_AUTH          -- require mechanisms which provide mutual
  294.  *               authentication
  295.  */
  296. #define SASL_SEC_NOPLAINTEXT      0x0001
  297. #define SASL_SEC_NOACTIVE         0x0002
  298. #define SASL_SEC_NODICTIONARY     0x0004
  299. #define SASL_SEC_FORWARD_SECRECY  0x0008
  300. #define SASL_SEC_NOANONYMOUS      0x0010
  301. #define SASL_SEC_PASS_CREDENTIALS 0x0020
  302. #define SASL_SEC_MUTUAL_AUTH      0x0040
  303. #define SASL_SEC_MAXIMUM          0x00FF
  304.  
  305. typedef struct sasl_security_properties 
  306. { 
  307.     /* security strength factor
  308.      *  min_ssf      = minimum acceptable final level
  309.      *  max_ssf      = maximum acceptable final level
  310.      */ 
  311.     sasl_ssf_t min_ssf;
  312.     sasl_ssf_t max_ssf;
  313.  
  314.     /* Maximum security layer receive buffer size.
  315.      *  0=security layer not supported
  316.      */
  317.     unsigned maxbufsize; 
  318.     
  319.     /* bitfield for attacks to protect against */
  320.     unsigned security_flags;
  321.  
  322.     /* NULL terminated array of additional property names, values */ 
  323.     const char **property_names;
  324.     const char **property_values;
  325. } sasl_security_properties_t; 
  326.  
  327. /******************
  328.  * Callback types *
  329.  ******************/
  330.  
  331. /*
  332.  * Extensible type for a client/server callbacks
  333.  *  id      -- identifies callback type
  334.  *  proc    -- procedure call arguments vary based on id
  335.  *  context -- context passed to procedure
  336.  */
  337. /* Note that any memory that is allocated by the callback needs to be
  338.  * freed by the application, be it via function call or interaction.
  339.  *
  340.  * It may be freed after sasl_*_step returns SASL_OK.  if the mechanism
  341.  * requires this information to persist (for a security layer, for example)
  342.  * it must maintain a private copy.
  343.  */
  344. typedef struct sasl_callback {
  345.     /* Identifies the type of the callback function.
  346.      * Mechanisms must ignore callbacks with id's they don't recognize.
  347.      */
  348.     unsigned long id;
  349.     int (*proc)();   /* Callback function.  Types of arguments vary by 'id' */
  350.     void *context;
  351. } sasl_callback_t;
  352.  
  353. /* callback ids & functions:
  354.  */
  355. #define SASL_CB_LIST_END   0  /* end of list */
  356.  
  357. /* option reading callback -- this allows a SASL configuration to be
  358.  *  encapsulated in the caller's configuration system.  Some implementations
  359.  *  may use default config file(s) if this is omitted.  Configuration items
  360.  *  may be plugin-specific and are arbitrary strings.
  361.  *
  362.  * inputs:
  363.  *  context     -- option context from callback record
  364.  *  plugin_name -- name of plugin (NULL = general SASL option)
  365.  *  option      -- name of option
  366.  * output:
  367.  *  result      -- set to result which persists until next getopt in
  368.  *                 same thread, unchanged if option not found
  369.  *  len         -- length of result (may be NULL)
  370.  * returns:
  371.  *  SASL_OK     -- no error
  372.  *  SASL_FAIL   -- error
  373.  */
  374. typedef int sasl_getopt_t(void *context, const char *plugin_name,
  375.               const char *option,
  376.               const char **result, unsigned *len);
  377. #define SASL_CB_GETOPT       1
  378.  
  379. /* Logging levels for use with the logging callback function. */
  380. #define SASL_LOG_NONE  0    /* don't log anything */
  381. #define SASL_LOG_ERR   1    /* log unusual errors (default) */
  382. #define SASL_LOG_FAIL  2    /* log all authentication failures */
  383. #define SASL_LOG_WARN  3    /* log non-fatal warnings */
  384. #define SASL_LOG_NOTE  4    /* more verbose than LOG_WARN */
  385. #define SASL_LOG_DEBUG 5    /* more verbose than LOG_NOTE */
  386. #define SASL_LOG_TRACE 6    /* traces of internal protocols */
  387. #define SASL_LOG_PASS  7    /* traces of internal protocols, including
  388.                  * passwords */
  389.  
  390. /* logging callback -- this allows plugins and the middleware to
  391.  *  log operations they perform.
  392.  * inputs:
  393.  *  context     -- logging context from the callback record
  394.  *  level       -- logging level; see above
  395.  *  message     -- message to log
  396.  * returns:
  397.  *  SASL_OK     -- no error
  398.  *  SASL_FAIL   -- error
  399.  */
  400. typedef int sasl_log_t(void *context,
  401.                int level,
  402.                const char *message);
  403. #define SASL_CB_LOG        2
  404.  
  405. /* getpath callback -- this allows applications to specify the
  406.  * colon-separated path to search for plugins (by default,
  407.  * taken from an implementation-specific location).
  408.  * inputs:
  409.  *  context     -- getpath context from the callback record
  410.  * outputs:
  411.  *  path    -- colon seperated path
  412.  * returns:
  413.  *  SASL_OK     -- no error
  414.  *  SASL_FAIL   -- error
  415.  */
  416. typedef int sasl_getpath_t(void *context,
  417.                const char **path);
  418.  
  419. #define SASL_CB_GETPATH        3
  420.  
  421. /* verify file callback -- this allows applications to check if they
  422.  * want SASL to use files, file by file.  This is intended to allow
  423.  * applications to sanity check the environment to make sure plugins
  424.  * or the configuration file can't be written to, etc.
  425.  * inputs: 
  426.  *  context     -- verifypath context from the callback record
  427.  *  file        -- full path to file to verify
  428.  *  type        -- type of file to verify (see below)
  429.  
  430.  * returns:
  431.  *  SASL_OK        -- no error (file can safely be used)
  432.  *  SASL_CONTINUE  -- continue WITHOUT using this file
  433.  *  SASL_FAIL      -- error 
  434.  */
  435.  
  436. /* these are the types of files libsasl will ask about */
  437. typedef enum {
  438.     SASL_VRFY_PLUGIN=0,        /* a DLL/shared library plug-in */
  439.     SASL_VRFY_CONF=1,        /* a configuration file */
  440.     SASL_VRFY_PASSWD=2,        /* a password storage file/db */
  441.     SASL_VRFY_OTHER=3        /* some other file */
  442. } sasl_verify_type_t;
  443.  
  444. typedef int sasl_verifyfile_t(void *context,
  445.                               const char *file, sasl_verify_type_t type);
  446. #define SASL_CB_VERIFYFILE  4
  447.  
  448. /* getconfpath callback -- this allows applications to specify the
  449.  * colon-separated path to search for config files (by default,
  450.  * taken from the SASL_CONF_PATH environment variable).
  451.  * inputs:
  452.  *  context     -- getconfpath context from the callback record
  453.  * outputs:
  454.  *  path        -- colon seperated path (allocated on the heap; the
  455.  *                 library will free it using the sasl_free_t *
  456.  *                 passed to sasl_set_callback, or the standard free()
  457.  *                 library call).
  458.  * returns:
  459.  *  SASL_OK     -- no error
  460.  *  SASL_FAIL   -- error
  461.  */
  462. typedef int sasl_getconfpath_t(void *context,
  463.                                char **path);
  464.  
  465. #define SASL_CB_GETCONFPATH  5
  466.  
  467. /* client/user interaction callbacks:
  468.  */
  469. /* Simple prompt -- result must persist until next call to getsimple on
  470.  *  same connection or until connection context is disposed
  471.  * inputs:
  472.  *  context       -- context from callback structure
  473.  *  id            -- callback id
  474.  * outputs:
  475.  *  result        -- set to NUL terminated string
  476.  *                   NULL = user cancel
  477.  *  len           -- length of result
  478.  * returns SASL_OK
  479.  */
  480. typedef int sasl_getsimple_t(void *context, int id,
  481.                  const char **result, unsigned *len);
  482. #define SASL_CB_USER         0x4001  /* client user identity to login as */
  483. #define SASL_CB_AUTHNAME     0x4002  /* client authentication name */
  484. #define SASL_CB_LANGUAGE     0x4003  /* comma separated list of RFC 1766
  485.                           * language codes in order of preference
  486.                       * to be used to localize client prompts
  487.                       * or server error codes */
  488. #define SASL_CB_CNONCE       0x4007  /* caller supplies client-nonce
  489.                       * primarily for testing purposes */
  490.  
  491. /* get a sasl_secret_t (plaintext password with length)
  492.  * inputs:
  493.  *  conn          -- connection context
  494.  *  context       -- context from callback structure
  495.  *  id            -- callback id
  496.  * outputs:
  497.  *  psecret       -- set to NULL to cancel
  498.  *                   set to password structure which must persist until
  499.  *                   next call to getsecret in same connection, but middleware
  500.  *                   will erase password data when it's done with it.
  501.  * returns SASL_OK
  502.  */
  503. typedef int sasl_getsecret_t(sasl_conn_t *conn, void *context, int id,
  504.                  sasl_secret_t **psecret);
  505. #define SASL_CB_PASS         0x4004  /* client passphrase-based secret */
  506.  
  507.  
  508. /* prompt for input in response to a challenge.
  509.  * input:
  510.  *  context   -- context from callback structure
  511.  *  id        -- callback id
  512.  *  challenge -- server challenge
  513.  * output:
  514.  *  result    -- NUL terminated result, NULL = user cancel
  515.  *  len       -- length of result
  516.  * returns SASL_OK
  517.  */
  518. typedef int sasl_chalprompt_t(void *context, int id,
  519.                   const char *challenge,
  520.                   const char *prompt, const char *defresult,
  521.                   const char **result, unsigned *len);
  522. #define SASL_CB_ECHOPROMPT   0x4005 /* challenge and client enterred result */
  523. #define SASL_CB_NOECHOPROMPT 0x4006 /* challenge and client enterred result */
  524.  
  525. /* prompt (or autoselect) the realm to do authentication in.
  526.  *  may get a list of valid realms.
  527.  * input:
  528.  *  context     -- context from callback structure
  529.  *  id          -- callback id
  530.  *  availrealms -- available realms; string list; NULL terminated
  531.  *                 list may be empty.
  532.  * output:
  533.  *  result      -- NUL terminated realm; NULL is equivalent to ""
  534.  * returns SASL_OK
  535.  * result must persist until the next callback
  536.  */
  537. typedef int sasl_getrealm_t(void *context, int id,
  538.                 const char **availrealms,
  539.                 const char **result);
  540. #define SASL_CB_GETREALM (0x4008) /* realm to attempt authentication in */
  541.  
  542. /* server callbacks:
  543.  */
  544.  
  545. /* improved callback to verify authorization;
  546.  *     canonicalization now handled elsewhere
  547.  *  conn           -- connection context
  548.  *  requested_user -- the identity/username to authorize (NUL terminated)
  549.  *  rlen           -- length of requested_user
  550.  *  auth_identity  -- the identity associated with the secret (NUL terminated)
  551.  *  alen           -- length of auth_identity
  552.  *  default_realm  -- default user realm, as passed to sasl_server_new if
  553.  *  urlen          -- length of default realm
  554.  *  propctx        -- auxiliary properties
  555.  * returns SASL_OK on success,
  556.  *         SASL_NOAUTHZ or other SASL response on failure
  557.  */
  558. typedef int sasl_authorize_t(sasl_conn_t *conn,
  559.                  void *context,
  560.                  const char *requested_user, unsigned rlen,
  561.                  const char *auth_identity, unsigned alen,
  562.                  const char *def_realm, unsigned urlen,
  563.                  struct propctx *propctx);
  564. #define SASL_CB_PROXY_POLICY 0x8001
  565.  
  566. /* functions for "userdb" based plugins to call to get/set passwords.
  567.  * the location for the passwords is determined by the caller or middleware.
  568.  * plug-ins may get passwords from other locations.
  569.  */
  570.  
  571. /* callback to verify a plaintext password against the caller-supplied
  572.  * user database.  This is necessary to allow additional <method>s for
  573.  * encoding of the userPassword property.
  574.  *  user          -- NUL terminated user name with user@realm syntax
  575.  *  pass          -- password to check (may not be NUL terminated)
  576.  *  passlen       -- length of password to check
  577.  *  propctx       -- auxiliary properties for user
  578.  */
  579. typedef int sasl_server_userdb_checkpass_t(sasl_conn_t *conn,
  580.                        void *context,
  581.                        const char *user,
  582.                        const char *pass,
  583.                        unsigned passlen,
  584.                        struct propctx *propctx);
  585. #define SASL_CB_SERVER_USERDB_CHECKPASS (0x8005)
  586.  
  587. /* callback to store/change a plaintext password in the user database
  588.  *  user          -- NUL terminated user name with user@realm syntax
  589.  *  pass          -- password to store (may not be NUL terminated)
  590.  *  passlen       -- length of password to store
  591.  *  propctx       -- auxiliary properties (not stored)
  592.  *  flags         -- see SASL_SET_* flags below (SASL_SET_CREATE optional)
  593.  */
  594. typedef int sasl_server_userdb_setpass_t(sasl_conn_t *conn,
  595.                      void *context,
  596.                      const char *user,
  597.                      const char *pass,
  598.                      unsigned passlen,
  599.                      struct propctx *propctx,
  600.                      unsigned flags);
  601. #define SASL_CB_SERVER_USERDB_SETPASS (0x8006)
  602.  
  603. /* callback for a server-supplied user canonicalization function.
  604.  *
  605.  * This function is called directly after the mechanism has the
  606.  * authentication and authorization IDs.  It is called before any
  607.  * User Canonicalization plugin is called.  It has the responsibility
  608.  * of copying its output into the provided output buffers.
  609.  * 
  610.  *  in, inlen     -- user name to canonicalize, may not be NUL terminated
  611.  *                   may be same buffer as out
  612.  *  flags         -- not currently used, supplied by auth mechanism
  613.  *  user_realm    -- the user realm (may be NULL in case of client)
  614.  *  out           -- buffer to copy user name
  615.  *  out_max       -- max length of user name
  616.  *  out_len       -- set to length of user name
  617.  *
  618.  * returns
  619.  *  SASL_OK         on success
  620.  *  SASL_BADPROT    username contains invalid character
  621.  */
  622.  
  623. /* User Canonicalization Function Flags */
  624.  
  625. #define SASL_CU_NONE    0x00 /* Not a valid flag to pass */
  626. /* One of the following two is required */
  627. #define SASL_CU_AUTHID  0x01
  628. #define SASL_CU_AUTHZID 0x02
  629.  
  630. typedef int sasl_canon_user_t(sasl_conn_t *conn,
  631.                   void *context,
  632.                   const char *in, unsigned inlen,
  633.                   unsigned flags,
  634.                   const char *user_realm,
  635.                   char *out,
  636.                   unsigned out_max, unsigned *out_len);
  637.  
  638. #define SASL_CB_CANON_USER (0x8007)
  639.  
  640. /**********************************
  641.  * Common Client/server functions *
  642.  **********************************/
  643.  
  644. /* Types of paths to set (see sasl_set_path below). */
  645. #define SASL_PATH_TYPE_PLUGIN    0
  646. #define SASL_PATH_TYPE_CONFIG    1
  647.  
  648. /* a simpler way to set plugin path or configuration file path
  649.  * without the need to set sasl_getpath_t callback.
  650.  *
  651.  * This function can be called before sasl_server_init/sasl_client_init.
  652.  */  
  653. LIBSASL_API int sasl_set_path (int path_type, char * path);
  654.  
  655. /* get sasl library version information
  656.  * implementation is a vendor-defined string
  657.  * version is a vender-defined representation of the version #.
  658.  *
  659.  * This function is being deprecated in favor of sasl_version_info. */
  660. LIBSASL_API void sasl_version(const char **implementation,
  661.                   int *version);
  662.  
  663. /* Extended version of sasl_version().
  664.  *
  665.  * This function is to be used
  666.  *  for library version display and logging
  667.  *  for bug workarounds in old library versions
  668.  *
  669.  * The sasl_version_info is not to be used for API feature detection.
  670.  *
  671.  * All parameters are optional. If NULL is specified, the value is not returned.
  672.  */
  673. LIBSASL_API void sasl_version_info (const char **implementation,
  674.                 const char **version_string,
  675.                 int *version_major,
  676.                 int *version_minor,
  677.                 int *version_step,
  678.                 int *version_patch);
  679.  
  680. /* dispose of all SASL plugins.  Connection
  681.  * states have to be disposed of before calling this.
  682.  */
  683. LIBSASL_API void sasl_done(void);
  684.  
  685. /* dispose connection state, sets it to NULL
  686.  *  checks for pointer to NULL
  687.  */
  688. LIBSASL_API void sasl_dispose(sasl_conn_t **pconn);
  689.  
  690. /* translate an error number into a string
  691.  * input:
  692.  *  saslerr  -- the error number
  693.  *  langlist -- comma separated list of RFC 1766 languages (may be NULL)
  694.  * results:
  695.  *  outlang  -- the language actually used (may be NULL if don't care)
  696.  * returns:
  697.  *  the error message in UTF-8 (only the US-ASCII subset if langlist is NULL)
  698.  */
  699. LIBSASL_API const char *sasl_errstring(int saslerr,
  700.                        const char *langlist,
  701.                        const char **outlang);
  702.  
  703. /* get detail about the last error that occurred on a connection
  704.  * text is sanitized so it's suitable to send over the wire
  705.  * (e.g., no distinction between SASL_BADAUTH and SASL_NOUSER)
  706.  * input:
  707.  *  conn          -- mandatory connection context
  708.  * returns:
  709.  *  the error message in UTF-8 (only the US-ASCII subset permitted if no
  710.  *  SASL_CB_LANGUAGE callback is present)
  711.  */
  712. LIBSASL_API const char *sasl_errdetail(sasl_conn_t *conn);
  713.  
  714. /* set the error string which will be returned by sasl_errdetail() using
  715.  *  syslog()-style formatting (e.g. printf-style with %m as most recent
  716.  *  errno error)
  717.  *
  718.  *  primarily for use by server callbacks such as the sasl_authorize_t
  719.  *  callback and internally to plug-ins
  720.  *
  721.  * This will also trigger a call to the SASL logging callback (if any)
  722.  * with a level of SASL_LOG_FAIL unless the SASL_NOLOG flag is set.
  723.  *
  724.  * Messages should be sensitive to the current language setting.  If there
  725.  * is no SASL_CB_LANGUAGE callback messages MUST be US-ASCII otherwise UTF-8
  726.  * is used and use of RFC 2482 for mixed-language text is encouraged.
  727.  *
  728.  * if conn is NULL, function does nothing
  729.  */
  730. LIBSASL_API void sasl_seterror(sasl_conn_t *conn, unsigned flags,
  731.                    const char *fmt, ...);
  732. #define SASL_NOLOG       0x01
  733.                
  734. /* get property from SASL connection state
  735.  *  propnum       -- property number
  736.  *  pvalue        -- pointer to value
  737.  * returns:
  738.  *  SASL_OK       -- no error
  739.  *  SASL_NOTDONE  -- property not available yet
  740.  *  SASL_BADPARAM -- bad property number
  741.  */
  742. LIBSASL_API int sasl_getprop(sasl_conn_t *conn, int propnum,
  743.                  const void **pvalue);
  744. #define SASL_USERNAME     0    /* pointer to NUL terminated user name */
  745. #define SASL_SSF          1    /* security layer security strength factor,
  746.                                  * if 0, call to sasl_encode, sasl_decode
  747.                                  * unnecessary */
  748. #define SASL_MAXOUTBUF    2     /* security layer max output buf unsigned */  
  749. #define SASL_DEFUSERREALM 3    /* default realm passed to server_new */
  750.                 /* or set with setprop */
  751. #define SASL_GETOPTCTX    4    /* context for getopt callback */
  752. #define SASL_CALLBACK     7    /* current callback function list */
  753. #define SASL_IPLOCALPORT  8    /* iplocalport string passed to server_new */
  754. #define SASL_IPREMOTEPORT 9    /* ipremoteport string passed to server_new */
  755.  
  756. /* This returns a string which is either empty or has an error message
  757.  * from sasl_seterror (e.g., from a plug-in or callback).  It differs
  758.  * from the result of sasl_errdetail() which also takes into account the
  759.  * last return status code.
  760.  */
  761. #define SASL_PLUGERR     10
  762.  
  763. /* a handle to any delegated credentials or NULL if none is present 
  764.  * is returned by the mechanism. The user will probably need to know
  765.  * which mechanism was used to actually known how to make use of them
  766.  * currently only implemented for the gssapi mechanism */
  767. #define SASL_DELEGATEDCREDS 11  
  768.  
  769. #define SASL_SERVICE      12    /* service passed to sasl_*_new */
  770. #define SASL_SERVERFQDN   13    /* serverFQDN passed to sasl_*_new */
  771. #define SASL_AUTHSOURCE   14    /* name of auth source last used, useful
  772.                  * for failed authentication tracking */
  773. #define SASL_MECHNAME     15    /* active mechanism name, if any */
  774. #define SASL_AUTHUSER     16    /* authentication/admin user */
  775. #define SASL_APPNAME      17    /* application name (used for logging/
  776.                    configuration), same as appname parameter
  777.                    to sasl_server_init */
  778.  
  779. /* GSS-API credential handle for sasl_client_step() or sasl_server_step().
  780.  * The application is responsible for releasing this credential handle. */
  781. #define    SASL_GSS_CREDS      18
  782.  
  783. /* GSS name (gss_name_t) of the peer, as output by gss_inquire_context()
  784.  * or gss_accept_sec_context().
  785.  * On server end this is similar to SASL_USERNAME, but the gss_name_t
  786.  * structure can contain additional attributes associated with the peer.
  787.  */
  788. #define    SASL_GSS_PEER_NAME    19
  789.  
  790. /* Local GSS name (gss_name_t) as output by gss_inquire_context(). This
  791.  * is particularly useful for servers that respond to multiple names. */
  792. #define    SASL_GSS_LOCAL_NAME    20
  793.  
  794.  
  795. /* set property in SASL connection state
  796.  * returns:
  797.  *  SASL_OK       -- value set
  798.  *  SASL_BADPARAM -- invalid property or value
  799.  */
  800. LIBSASL_API int sasl_setprop(sasl_conn_t *conn,
  801.                  int propnum,
  802.                  const void *value);
  803. #define SASL_SSF_EXTERNAL  100    /* external SSF active (sasl_ssf_t *) */
  804. #define SASL_SEC_PROPS     101    /* sasl_security_properties_t */
  805. #define SASL_AUTH_EXTERNAL 102    /* external authentication ID (const char *) */
  806.  
  807. /* If the SASL_AUTH_EXTERNAL value is non-NULL, then a special version of the
  808.  * EXTERNAL mechanism is enabled (one for server-embedded EXTERNAL mechanisms).
  809.  * Otherwise, the EXTERNAL mechanism will be absent unless a plug-in
  810.  * including EXTERNAL is present.
  811.  */
  812.  
  813. /* do precalculations during an idle period or network round trip
  814.  *  may pass NULL to precompute for some mechanisms prior to connect
  815.  *  returns 1 if action taken, 0 if no action taken
  816.  */
  817. LIBSASL_API int sasl_idle(sasl_conn_t *conn);
  818.  
  819. /**************
  820.  * Client API *
  821.  **************/
  822.  
  823. /* list of client interactions with user for caller to fill in
  824.  */
  825. typedef struct sasl_interact {
  826.     unsigned long id;        /* same as client/user callback ID */
  827.     const char *challenge;    /* presented to user (e.g. OTP challenge) */
  828.     const char *prompt;        /* presented to user (e.g. "Username: ") */
  829.     const char *defresult;    /* default result string */
  830.     const void *result;        /* set to point to result */
  831.     unsigned len;        /* set to length of result */
  832. } sasl_interact_t;
  833.  
  834. /* initialize the SASL client drivers
  835.  *  callbacks      -- base callbacks for all client connections;
  836.  *                    must include getopt callback
  837.  * returns:
  838.  *  SASL_OK        -- Success
  839.  *  SASL_NOMEM     -- Not enough memory
  840.  *  SASL_BADVERS   -- Mechanism version mismatch
  841.  *  SASL_BADPARAM  -- missing getopt callback or error in config file
  842.  *  SASL_NOMECH    -- No mechanisms available
  843.  *  ...
  844.  */
  845. LIBSASL_API int sasl_client_init(const sasl_callback_t *callbacks);
  846.  
  847. /* initialize a client exchange based on the specified mechanism
  848.  *  service       -- registered name of the service using SASL (e.g. "imap")
  849.  *  serverFQDN    -- the fully qualified domain name of the server
  850.  *  iplocalport   -- client IPv4/IPv6 domain literal string with port
  851.  *                    (if NULL, then mechanisms requiring IPaddr are disabled)
  852.  *  ipremoteport  -- server IPv4/IPv6 domain literal string with port
  853.  *                    (if NULL, then mechanisms requiring IPaddr are disabled)
  854.  *  prompt_supp   -- list of client interactions supported
  855.  *                   may also include sasl_getopt_t context & call
  856.  *                   NULL prompt_supp = user/pass via SASL_INTERACT only
  857.  *                   NULL proc = interaction supported via SASL_INTERACT
  858.  *  flags         -- server usage flags (see above)
  859.  * in/out:
  860.  *  pconn         -- connection negotiation structure
  861.  *                   pointer to NULL => allocate new
  862.  *
  863.  * Returns:
  864.  *  SASL_OK       -- success
  865.  *  SASL_NOMECH   -- no mechanism meets requested properties
  866.  *  SASL_NOMEM    -- not enough memory
  867.  */
  868. LIBSASL_API int sasl_client_new(const char *service,
  869.                 const char *serverFQDN,
  870.                 const char *iplocalport,
  871.                 const char *ipremoteport,
  872.                 const sasl_callback_t *prompt_supp,
  873.                 unsigned flags,
  874.                 sasl_conn_t **pconn);
  875.  
  876. /* select a mechanism for a connection
  877.  *  mechlist      -- mechanisms server has available (punctuation ignored)
  878.  *                   if NULL, then discard cached info and retry last mech
  879.  * output:
  880.  *  prompt_need   -- on SASL_INTERACT, list of prompts needed to continue
  881.  *                   may be NULL if callbacks provided
  882.  *  clientout     -- the initial client response to send to the server
  883.  *                   will be valid until next call to client_start/client_step
  884.  *                   NULL if mech doesn't include initial client challenge
  885.  *  mech          -- set to mechansm name of selected mechanism (may be NULL)
  886.  *
  887.  * Returns:
  888.  *  SASL_OK       -- success
  889.  *  SASL_NOMEM    -- not enough memory
  890.  *  SASL_NOMECH   -- no mechanism meets requested properties
  891.  *  SASL_INTERACT -- user interaction needed to fill in prompt_need list
  892.  */
  893. LIBSASL_API int sasl_client_start(sasl_conn_t *conn,
  894.                   const char *mechlist,
  895.                   sasl_interact_t **prompt_need,
  896.                   const char **clientout,
  897.                   unsigned *clientoutlen,
  898.                   const char **mech);
  899.  
  900. /* do a single authentication step.
  901.  *  serverin    -- the server message received by the client, MUST have a NUL
  902.  *                 sentinel, not counted by serverinlen
  903.  * output:
  904.  *  prompt_need -- on SASL_INTERACT, list of prompts needed to continue
  905.  *  clientout   -- the client response to send to the server
  906.  *                 will be valid until next call to client_start/client_step
  907.  *
  908.  * returns:
  909.  *  SASL_OK        -- success
  910.  *  SASL_INTERACT  -- user interaction needed to fill in prompt_need list
  911.  *  SASL_BADPROT   -- server protocol incorrect/cancelled
  912.  *  SASL_BADSERV   -- server failed mutual auth
  913.  */
  914. LIBSASL_API int sasl_client_step(sasl_conn_t *conn,
  915.                  const char *serverin,
  916.                  unsigned serverinlen,
  917.                  sasl_interact_t **prompt_need,
  918.                  const char **clientout,
  919.                  unsigned *clientoutlen);
  920.  
  921. /**************
  922.  * Server API *
  923.  **************/
  924.  
  925. /* initialize server drivers, done once per process
  926.  *  callbacks      -- callbacks for all server connections; must include
  927.  *                    getopt callback
  928.  *  appname        -- name of calling application (for lower level logging)
  929.  * results:
  930.  *  state          -- server state
  931.  * returns:
  932.  *  SASL_OK        -- success
  933.  *  SASL_BADPARAM  -- error in config file
  934.  *  SASL_NOMEM     -- memory failure
  935.  *  SASL_BADVERS   -- Mechanism version mismatch
  936.  */
  937. LIBSASL_API int sasl_server_init(const sasl_callback_t *callbacks,
  938.                  const char *appname);
  939.  
  940. /* IP/port syntax:
  941.  *  a.b.c.d;p              where a-d are 0-255 and p is 0-65535 port number.
  942.  *  e:f:g:h:i:j:k:l;p      where e-l are 0000-ffff lower-case hexidecimal
  943.  *  e:f:g:h:i:j:a.b.c.d;p  alternate syntax for previous
  944.  *
  945.  *  Note that one or more "0" fields in f-k can be replaced with "::"
  946.  *  Thus:                 e:f:0000:0000:0000:j:k:l;p
  947.  *  can be abbreviated:   e:f::j:k:l;p
  948.  *
  949.  * A buffer of size 52 is adequate for the longest format with NUL terminator.
  950.  */
  951.  
  952. /* create context for a single SASL connection
  953.  *  service        -- registered name of the service using SASL (e.g. "imap")
  954.  *  serverFQDN     -- Fully qualified domain name of server.  NULL means use
  955.  *                    gethostname() or equivalent.
  956.  *                    Useful for multi-homed servers.
  957.  *  user_realm     -- permits multiple user realms on server, NULL = default
  958.  *  iplocalport    -- server IPv4/IPv6 domain literal string with port
  959.  *                    (if NULL, then mechanisms requiring IPaddr are disabled)
  960.  *  ipremoteport   -- client IPv4/IPv6 domain literal string with port
  961.  *                    (if NULL, then mechanisms requiring IPaddr are disabled)
  962.  *  callbacks      -- callbacks (e.g., authorization, lang, new getopt context)
  963.  *  flags          -- usage flags (see above)
  964.  * returns:
  965.  *  pconn          -- new connection context
  966.  *
  967.  * returns:
  968.  *  SASL_OK        -- success
  969.  *  SASL_NOMEM     -- not enough memory
  970.  */
  971. LIBSASL_API int sasl_server_new(const char *service,
  972.                 const char *serverFQDN,
  973.                 const char *user_realm,
  974.                 const char *iplocalport,
  975.                 const char *ipremoteport,
  976.                 const sasl_callback_t *callbacks,
  977.                 unsigned flags,
  978.                 sasl_conn_t **pconn);
  979.  
  980. /* Return an array of NUL-terminated strings, terminated by a NULL pointer,
  981.  * which lists all possible mechanisms that the library can supply
  982.  *
  983.  * Returns NULL on failure. */
  984. LIBSASL_API const char ** sasl_global_listmech(void);
  985.  
  986. /* This returns a list of mechanisms in a NUL-terminated string
  987.  *  conn          -- the connection to list mechanisms for (either client
  988.  *                   or server)
  989.  *  user          -- restricts mechanisms to those available to that user
  990.  *                   (may be NULL, not used for client case)
  991.  *  prefix        -- appended to beginning of result
  992.  *  sep           -- appended between mechanisms
  993.  *  suffix        -- appended to end of result
  994.  * results:
  995.  *  result        -- NUL terminated result which persists until next
  996.  *                   call to sasl_listmech for this sasl_conn_t
  997.  *  plen          -- gets length of result (excluding NUL), may be NULL
  998.  *  pcount        -- gets number of mechanisms, may be NULL
  999.  *
  1000.  * returns:
  1001.  *  SASL_OK        -- success
  1002.  *  SASL_NOMEM     -- not enough memory
  1003.  *  SASL_NOMECH    -- no enabled mechanisms
  1004.  */
  1005. LIBSASL_API int sasl_listmech(sasl_conn_t *conn,
  1006.                   const char *user,
  1007.                   const char *prefix,
  1008.                   const char *sep,
  1009.                   const char *suffix,
  1010.                   const char **result,
  1011.                   unsigned *plen,
  1012.                   int *pcount);
  1013.  
  1014. /* start a mechanism exchange within a connection context
  1015.  *  mech           -- the mechanism name client requested
  1016.  *  clientin       -- client initial response (NUL terminated), NULL if empty
  1017.  *  clientinlen    -- length of initial response
  1018.  *  serverout      -- initial server challenge, NULL if done 
  1019.  *                    (library handles freeing this string)
  1020.  *  serveroutlen   -- length of initial server challenge
  1021.  * output:
  1022.  *  pconn          -- the connection negotiation state on success
  1023.  *
  1024.  * Same returns as sasl_server_step() or
  1025.  * SASL_NOMECH if mechanism not available.
  1026.  */
  1027. LIBSASL_API int sasl_server_start(sasl_conn_t *conn,
  1028.                   const char *mech,
  1029.                   const char *clientin,
  1030.                   unsigned clientinlen,
  1031.                   const char **serverout,
  1032.                   unsigned *serveroutlen);
  1033.  
  1034. /* perform one step of the SASL exchange
  1035.  *  inputlen & input -- client data
  1036.  *                      NULL on first step if no optional client step
  1037.  *  outputlen & output -- set to the server data to transmit
  1038.  *                        to the client in the next step
  1039.  *                        (library handles freeing this)
  1040.  *
  1041.  * returns:
  1042.  *  SASL_OK        -- exchange is complete.
  1043.  *  SASL_CONTINUE  -- indicates another step is necessary.
  1044.  *  SASL_TRANS     -- entry for user exists, but not for mechanism
  1045.  *                    and transition is possible
  1046.  *  SASL_BADPARAM  -- service name needed
  1047.  *  SASL_BADPROT   -- invalid input from client
  1048.  *  ...
  1049.  */
  1050. LIBSASL_API int sasl_server_step(sasl_conn_t *conn,
  1051.                  const char *clientin,
  1052.                  unsigned clientinlen,
  1053.                  const char **serverout,
  1054.                  unsigned *serveroutlen);
  1055.  
  1056. /* check if an apop exchange is valid
  1057.  *  (note this is an optional part of the SASL API)
  1058.  *  if challenge is NULL, just check if APOP is enabled
  1059.  * inputs:
  1060.  *  challenge     -- challenge which was sent to client
  1061.  *  challen       -- length of challenge, 0 = strlen(challenge)
  1062.  *  response      -- client response, "<user> <digest>" (RFC 1939)
  1063.  *  resplen       -- length of response, 0 = strlen(response)
  1064.  * returns 
  1065.  *  SASL_OK       -- success
  1066.  *  SASL_BADAUTH  -- authentication failed
  1067.  *  SASL_BADPARAM -- missing challenge
  1068.  *  SASL_BADPROT  -- protocol error (e.g., response in wrong format)
  1069.  *  SASL_NOVERIFY -- user found, but no verifier
  1070.  *  SASL_NOMECH   -- mechanism not supported
  1071.  *  SASL_NOUSER   -- user not found
  1072.  */
  1073. LIBSASL_API int sasl_checkapop(sasl_conn_t *conn,
  1074.                    const char *challenge, unsigned challen,
  1075.                    const char *response, unsigned resplen);
  1076.  
  1077. /* check if a plaintext password is valid
  1078.  *   if user is NULL, check if plaintext passwords are enabled
  1079.  * inputs:
  1080.  *  user          -- user to query in current user_domain
  1081.  *  userlen       -- length of username, 0 = strlen(user)
  1082.  *  pass          -- plaintext password to check
  1083.  *  passlen       -- length of password, 0 = strlen(pass)
  1084.  * returns 
  1085.  *  SASL_OK       -- success
  1086.  *  SASL_NOMECH   -- mechanism not supported
  1087.  *  SASL_NOVERIFY -- user found, but no verifier
  1088.  *  SASL_NOUSER   -- user not found
  1089.  */
  1090. LIBSASL_API int sasl_checkpass(sasl_conn_t *conn,
  1091.                    const char *user, unsigned userlen,
  1092.                    const char *pass, unsigned passlen);
  1093.  
  1094. /* check if a user exists on server
  1095.  *  conn          -- connection context
  1096.  *  service       -- registered name of the service using SASL (e.g. "imap")
  1097.  *  user_realm    -- permits multiple user realms on server, NULL = default
  1098.  *  user          -- NUL terminated user name
  1099.  *
  1100.  * returns:
  1101.  *  SASL_OK       -- success
  1102.  *  SASL_DISABLED -- account disabled
  1103.  *  SASL_NOUSER   -- user not found
  1104.  *  SASL_NOVERIFY -- user found, but no usable mechanism
  1105.  *  SASL_NOMECH   -- no mechanisms enabled
  1106.  */
  1107. LIBSASL_API int sasl_user_exists(sasl_conn_t *conn,
  1108.                  const char *service,
  1109.                  const char *user_realm,
  1110.                  const char *user);
  1111.  
  1112. /* set the password for a user
  1113.  *  conn        -- SASL connection
  1114.  *  user        -- user name
  1115.  *  pass        -- plaintext password, may be NULL to remove user
  1116.  *  passlen     -- length of password, 0 = strlen(pass)
  1117.  *  oldpass     -- NULL will sometimes work
  1118.  *  oldpasslen  -- length of password, 0 = strlen(oldpass)
  1119.  *  flags       -- see flags below
  1120.  * 
  1121.  * returns:
  1122.  *  SASL_NOCHANGE  -- proper entry already exists
  1123.  *  SASL_NOMECH    -- no authdb supports password setting as configured
  1124.  *  SASL_NOVERIFY  -- user exists, but no settable password present
  1125.  *  SASL_DISABLED  -- account disabled
  1126.  *  SASL_PWLOCK    -- password locked
  1127.  *  SASL_WEAKPASS  -- password too weak for security policy
  1128.  *  SASL_NOUSERPASS -- user-supplied passwords not permitted
  1129.  *  SASL_FAIL      -- OS error
  1130.  *  SASL_BADPARAM  -- password too long
  1131.  *  SASL_OK        -- successful
  1132.  */
  1133. LIBSASL_API int sasl_setpass(sasl_conn_t *conn,
  1134.                  const char *user,
  1135.                  const char *pass, unsigned passlen,
  1136.                  const char *oldpass, unsigned oldpasslen,
  1137.                  unsigned flags);
  1138. #define SASL_SET_CREATE  0x01   /* create a new entry for user */
  1139. #define SASL_SET_DISABLE 0x02    /* disable user account */
  1140. #define SASL_SET_NOPLAIN 0x04    /* do not store secret in plain text */
  1141. #define SASL_SET_CURMECH_ONLY 0x08    /* set the mechanism specific password only.
  1142.                        fail if no current mechanism */
  1143.  
  1144. /*********************************************************
  1145.  * Auxiliary Property Support -- added by cjn 1999-09-29 *
  1146.  *********************************************************/
  1147.  
  1148. #define SASL_AUX_END      NULL    /* last auxiliary property */
  1149.  
  1150. /* traditional Posix items (should be implemented on Posix systems) */
  1151. #define SASL_AUX_PASSWORD_PROP "userPassword" /* User Password */
  1152. #define SASL_AUX_PASSWORD "*" SASL_AUX_PASSWORD_PROP /* User Password (of authid) */
  1153. #define SASL_AUX_UIDNUM   "uidNumber"    /* UID number for the user */
  1154. #define SASL_AUX_GIDNUM   "gidNumber"    /* GID for the user */
  1155. #define SASL_AUX_FULLNAME "gecos"    /* full name of the user, unix-style */
  1156. #define SASL_AUX_HOMEDIR  "homeDirectory" /* home directory for user */
  1157. #define SASL_AUX_SHELL    "loginShell"    /* login shell for the user */
  1158.  
  1159. /* optional additional items (not necessarily implemented) */
  1160. /* single preferred mail address for user canonically-quoted
  1161.  * RFC821/822 syntax */
  1162. #define SASL_AUX_MAILADDR "mail"
  1163. /* path to unix-style mailbox for user */
  1164. #define SASL_AUX_UNIXMBX  "mailMessageStore"
  1165. /* SMTP mail channel name to use if user authenticates successfully */
  1166. #define SASL_AUX_MAILCHAN "mailSMTPSubmitChannel"
  1167.  
  1168. /* Request a set of auxiliary properties
  1169.  *  conn         connection context
  1170.  *  propnames    list of auxiliary property names to request ending with
  1171.  *               NULL.  
  1172.  *
  1173.  * Subsequent calls will add items to the request list.  Call with NULL
  1174.  * to clear the request list.
  1175.  *
  1176.  * errors
  1177.  *  SASL_OK       -- success
  1178.  *  SASL_BADPARAM -- bad count/conn parameter
  1179.  *  SASL_NOMEM    -- out of memory
  1180.  */
  1181. LIBSASL_API int sasl_auxprop_request(sasl_conn_t *conn,
  1182.                      const char **propnames);
  1183.  
  1184. /* Returns current auxiliary property context.
  1185.  * Use functions in prop.h to access content
  1186.  *
  1187.  *  if authentication hasn't completed, property values may be empty/NULL
  1188.  *
  1189.  *  properties not recognized by active plug-ins will be left empty/NULL
  1190.  *
  1191.  *  returns NULL if conn is invalid.
  1192.  */
  1193. LIBSASL_API struct propctx *sasl_auxprop_getctx(sasl_conn_t *conn);
  1194.  
  1195. /* Store the set of auxiliary properties for the given user.
  1196.  * Use functions in prop.h to set the content.
  1197.  *
  1198.  *  conn         connection context
  1199.  *  ctx          property context from prop_new()/prop_request()/prop_set()
  1200.  *  user         NUL terminated user
  1201.  *
  1202.  * Call with NULL 'ctx' to see if the backend allows storing properties.
  1203.  *
  1204.  * errors
  1205.  *  SASL_OK       -- success
  1206.  *  SASL_NOMECH   -- can not store some/all properties
  1207.  *  SASL_BADPARAM -- bad conn/ctx/user parameter
  1208.  *  SASL_NOMEM    -- out of memory
  1209.  *  SASL_FAIL     -- failed to store
  1210.  */
  1211. LIBSASL_API int sasl_auxprop_store(sasl_conn_t *conn,
  1212.                    struct propctx *ctx, const char *user);
  1213.  
  1214. /**********************
  1215.  * security layer API *
  1216.  **********************/
  1217.  
  1218. /* encode a block of data for transmission using security layer,
  1219.  *  returning the input buffer if there is no security layer.
  1220.  *  output is only valid until next call to sasl_encode or sasl_encodev
  1221.  * returns:
  1222.  *  SASL_OK      -- success (returns input if no layer negotiated)
  1223.  *  SASL_NOTDONE -- security layer negotiation not finished
  1224.  *  SASL_BADPARAM -- inputlen is greater than the SASL_MAXOUTBUF
  1225.  */
  1226. LIBSASL_API int sasl_encode(sasl_conn_t *conn,
  1227.                 const char *input, unsigned inputlen,
  1228.                 const char **output, unsigned *outputlen);
  1229.  
  1230. /* encode a block of data for transmission using security layer
  1231.  *  output is only valid until next call to sasl_encode or sasl_encodev
  1232.  * returns:
  1233.  *  SASL_OK      -- success (returns input if no layer negotiated)
  1234.  *  SASL_NOTDONE -- security layer negotiation not finished
  1235.  *  SASL_BADPARAM -- input length is greater than the SASL_MAXOUTBUF
  1236.  *             or no security layer
  1237.  */
  1238. LIBSASL_API int sasl_encodev(sasl_conn_t *conn,
  1239.                  const struct iovec *invec, unsigned numiov,
  1240.                  const char **output, unsigned *outputlen);
  1241.  
  1242. /* decode a block of data received using security layer
  1243.  *  returning the input buffer if there is no security layer.
  1244.  *  output is only valid until next call to sasl_decode
  1245.  *
  1246.  *  if outputlen is 0 on return, than the value of output is undefined.
  1247.  *  
  1248.  * returns:
  1249.  *  SASL_OK      -- success (returns input if no layer negotiated)
  1250.  *  SASL_NOTDONE -- security layer negotiation not finished
  1251.  *  SASL_BADMAC  -- bad message integrity check
  1252.  */
  1253. LIBSASL_API int sasl_decode(sasl_conn_t *conn,
  1254.                 const char *input, unsigned inputlen,
  1255.                 const char **output, unsigned *outputlen);
  1256.  
  1257. #ifdef __cplusplus
  1258. }
  1259. #endif
  1260.  
  1261. #endif /* SASL_H */
  1262.