include/saslutil.h

   1 /* saslutil.h -- various utility functions in SASL library
   2  */
   3
   4 #ifndef SASLUTIL_H
   5 #define SASLUTIL_H 1
   6
   7 #ifndef SASL_H
   8 #include "sasl.h"
   9 #endif
  10
  11 #ifdef __cplusplus
  12 extern "C" {
  13 #endif
  14
  15 /* base64 decode
  16  *  in     -- input data
  17  *  inlen  -- length of input data
  18  *  out    -- output data (may be same as in, must have enough space)
  19  *  outmax  -- max size of output buffer
  20  * result:
  21  *  outlen -- actual output length
  22  *
  23  * returns SASL_BADPROT on bad base64,
  24  *  SASL_BUFOVER if result won't fit
  25  *  SASL_OK on success
  26  */
  27 LIBSASL_API int sasl_decode64(const char *in, unsigned inlen,
  28                               char *out, unsigned outmax, unsigned *outlen);
  29
  30 /* base64 encode
  31  *  in      -- input data
  32  *  inlen   -- input data length
  33  *  out     -- output buffer (will be NUL terminated)
  34  *  outmax  -- max size of output buffer
  35  * result:
  36  *  outlen  -- gets actual length of output buffer (optional)
  37  *
  38  * Returns SASL_OK on success, SASL_BUFOVER if result won't fit
  39  */
  40 LIBSASL_API int sasl_encode64(const char *in, unsigned inlen,
  41                               char *out, unsigned outmax, unsigned *outlen);
  42
  43 /* make a challenge string (NUL terminated)
  44  *  buf      -- buffer for result
  45  *  maxlen   -- max length of result
  46  *  hostflag -- 0 = don't include hostname, 1 = include hostname
  47  * returns final length or 0 if not enough space
  48  */
  49 LIBSASL_API int sasl_mkchal(sasl_conn_t *conn, char *buf,
  50                             unsigned maxlen, unsigned hostflag);
  51
  52 /* verify a string is valid UTF-8
  53  * if len == 0, strlen(str) will be used.
  54  * returns SASL_BADPROT on error, SASL_OK on success
  55  */
  56 LIBSASL_API int sasl_utf8verify(const char *str, unsigned len);
  57
  58 /* create random pool seeded with OS-based params */
  59 LIBSASL_API int sasl_randcreate(sasl_rand_t **rpool);
  60
  61 /* free random pool from randcreate */
  62 LIBSASL_API void sasl_randfree(sasl_rand_t **rpool);
  63
  64 /* seed random number generator */
  65 LIBSASL_API void sasl_randseed(sasl_rand_t *rpool, const char *seed,
  66                                unsigned len);
  67
  68 /* generate random octets */
  69 LIBSASL_API void sasl_rand(sasl_rand_t *rpool, char *buf, unsigned len);
  70
  71 /* churn data into random number generator */
  72 LIBSASL_API void sasl_churn(sasl_rand_t *rpool, const char *data,
  73                             unsigned len);
  74
  75 /* erase a security sensitive buffer or password.
  76  *   Implementation may use recovery-resistant erase logic.
  77  */
  78 LIBSASL_API void sasl_erasebuffer(char *pass, unsigned len);
  79
  80 #ifdef WIN32
  81 /* Just in case a different DLL defines this as well */
  82 #if defined(NEED_GETOPT)
  83 LIBSASL_API int getopt(int argc, char **argv, char *optstring);
  84 #endif
  85 LIBSASL_API char * getpass(const char *prompt);
  86 #endif /* WIN32 */
  87
  88 #ifdef __cplusplus
  89 }
  90 #endif
  91
  92 #endif /* SASLUTIL_H */