include/saslplug.h

   1 /* saslplug.h --  API for SASL plug-ins
   2  */
   3
   4 #ifndef SASLPLUG_H
   5 #define SASLPLUG_H 1
   6
   7 #ifndef MD5GLOBAL_H
   8 #include "md5global.h"
   9 #endif
  10 #ifndef MD5_H
  11 #include "md5.h"
  12 #endif
  13 #ifndef HMAC_MD5_H
  14 #include "hmac-md5.h"
  15 #endif
  16 #ifndef PROP_H
  17 #include "prop.h"
  18 #endif
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 /* callback to lookup a sasl_callback_t for a connection
  25  * input:
  26  *  conn        -- the connection to lookup a callback for
  27  *  callbacknum -- the number of the callback
  28  * output:
  29  *  pproc       -- pointer to the callback function (set to NULL on failure)
  30  *  pcontext    -- pointer to the callback context (set to NULL on failure)
  31  * returns:
  32  *  SASL_OK -- no error
  33  *  SASL_FAIL -- unable to find a callback of the requested type
  34  *  SASL_INTERACT -- caller must use interaction to get data
  35  */
  36 typedef int sasl_getcallback_t(sasl_conn_t *conn,
  37                                unsigned long callbackid,
  38                                int (**pproc)(),
  39                                void **pcontext);
  40
  41 /* The sasl_utils structure will remain backwards compatible unless
  42  * the SASL_*_PLUG_VERSION is changed incompatibly
  43  * higher SASL_UTILS_VERSION numbers indicate more functions are available
  44  */
  45 #define SASL_UTILS_VERSION 4
  46
  47 /* utility function set for plug-ins
  48  */
  49 typedef struct sasl_utils {
  50     int version;
  51
  52     /* contexts */
  53     sasl_conn_t *conn;
  54     sasl_rand_t *rpool;
  55     void *getopt_context;
  56
  57     /* option function */
  58     sasl_getopt_t *getopt;
  59
  60     /* allocation functions: */
  61     sasl_malloc_t *malloc;
  62     sasl_calloc_t *calloc;
  63     sasl_realloc_t *realloc;
  64     sasl_free_t *free;
  65
  66     /* mutex functions: */
  67     sasl_mutex_alloc_t *mutex_alloc;
  68     sasl_mutex_lock_t *mutex_lock;
  69     sasl_mutex_unlock_t *mutex_unlock;
  70     sasl_mutex_free_t *mutex_free;
  71
  72     /* MD5 hash and HMAC functions */
  73     void (*MD5Init)(MD5_CTX *);
  74     void (*MD5Update)(MD5_CTX *, const unsigned char *text, unsigned int len);
  75     void (*MD5Final)(unsigned char [16], MD5_CTX *);
  76     void (*hmac_md5)(const unsigned char *text, int text_len,
  77                      const unsigned char *key, int key_len,
  78                      unsigned char [16]);
  79     void (*hmac_md5_init)(HMAC_MD5_CTX *, const unsigned char *key, int len);
  80     /* hmac_md5_update() is just a call to MD5Update on inner context */
  81     void (*hmac_md5_final)(unsigned char [16], HMAC_MD5_CTX *);
  82     void (*hmac_md5_precalc)(HMAC_MD5_STATE *,
  83                              const unsigned char *key, int len);
  84     void (*hmac_md5_import)(HMAC_MD5_CTX *, HMAC_MD5_STATE *);
  85
  86     /* mechanism utility functions (same as above): */
  87     int (*mkchal)(sasl_conn_t *conn, char *buf, unsigned maxlen,
  88                   unsigned hostflag);
  89     int (*utf8verify)(const char *str, unsigned len);
  90     void (*rand)(sasl_rand_t *rpool, char *buf, unsigned len);
  91     void (*churn)(sasl_rand_t *rpool, const char *data, unsigned len);
  92
  93     /* This allows recursive calls to the sasl_checkpass() routine from
  94      * within a SASL plug-in.  This MUST NOT be used in the PLAIN mechanism
  95      * as sasl_checkpass MAY be a front-end for the PLAIN mechanism.
  96      * This is intended for use by the non-standard LOGIN mechanism and
  97      * potentially by a future mechanism which uses public-key technology to
  98      * set up a lightweight encryption layer just for sending a password.
  99      */
 100     int (*checkpass)(sasl_conn_t *conn,
 101                      const char *user, unsigned userlen,
 102                      const char *pass, unsigned passlen);
 103
 104     /* Access to base64 encode/decode routines */
 105     int (*decode64)(const char *in, unsigned inlen,
 106                     char *out, unsigned outmax, unsigned *outlen);
 107     int (*encode64)(const char *in, unsigned inlen,
 108                     char *out, unsigned outmax, unsigned *outlen);
 109
 110     /* erase a buffer */
 111     void (*erasebuffer)(char *buf, unsigned len);
 112
 113     /* callback to sasl_getprop() and sasl_setprop() */
 114     int (*getprop)(sasl_conn_t *conn, int propnum, const void **pvalue);
 115     int (*setprop)(sasl_conn_t *conn, int propnum, const void *value);
 116
 117     /* callback function */
 118     sasl_getcallback_t *getcallback;
 119
 120     /* format a message and then pass it to the SASL_CB_LOG callback
 121      *
 122      * use syslog()-style formatting (printf with %m as a human readable text
 123      * (strerror()) for the error specified as the parameter).
 124      * The implementation may use a fixed size buffer not smaller
 125      * than 512 octets if it securely truncates the message.
 126      *
 127      * level is a SASL_LOG_* level (see sasl.h)
 128      */
 129     void (*log)(sasl_conn_t *conn, int level, const char *fmt, ...);
 130
 131     /* callback to sasl_seterror() */
 132     void (*seterror)(sasl_conn_t *conn, unsigned flags, const char *fmt, ...);
 133
 134     /* spare function pointer */
 135     int *(*spare_fptr)();
 136
 137     /* auxiliary property utilities */
 138     struct propctx *(*prop_new)(unsigned estimate);
 139     int (*prop_dup)(struct propctx *src_ctx, struct propctx **dst_ctx);
 140     int (*prop_request)(struct propctx *ctx, const char **names);
 141     const struct propval *(*prop_get)(struct propctx *ctx);
 142     int (*prop_getnames)(struct propctx *ctx, const char **names,
 143                          struct propval *vals);
 144     void (*prop_clear)(struct propctx *ctx, int requests);
 145     void (*prop_dispose)(struct propctx **ctx);
 146     int (*prop_format)(struct propctx *ctx, const char *sep, int seplen,
 147                        char *outbuf, unsigned outmax, unsigned *outlen);
 148     int (*prop_set)(struct propctx *ctx, const char *name,
 149                     const char *value, int vallen);
 150     int (*prop_setvals)(struct propctx *ctx, const char *name,
 151                         const char **values);
 152     void (*prop_erase)(struct propctx *ctx, const char *name);
 153     int (*auxprop_store)(sasl_conn_t *conn,
 154                          struct propctx *ctx, const char *user);
 155
 156     /* for additions which don't require a version upgrade; set to 0 */
 157     int (*spare_fptr1)();
 158     int (*spare_fptr2)();
 159 } sasl_utils_t;
 160
 161 /*
 162  * output parameters from SASL API
 163  *
 164  * created / destroyed by the glue code, though probably filled in
 165  * by a combination of the plugin, the glue code, and the canon_user callback.
 166  *
 167  */
 168 typedef struct sasl_out_params {
 169     unsigned doneflag;          /* exchange complete */
 170
 171     const char *user;           /* canonicalized user name */
 172     const char *authid;         /* canonicalized authentication id */
 173
 174     unsigned ulen;              /* length of canonicalized user name */
 175     unsigned alen;              /* length of canonicalized authid */
 176
 177     /* security layer information */
 178     unsigned maxoutbuf;         /* Maximum buffer size, which will
 179                                    produce buffer no bigger than the
 180                                    negotiated SASL maximum buffer size */
 181     sasl_ssf_t mech_ssf;   /* Should be set non-zero if negotiation of a
 182                             * security layer was *attempted*, even if
 183                             * the negotiation failed */
 184     void *encode_context;
 185     int (*encode)(void *context, const struct iovec *invec, unsigned numiov,
 186                   const char **output, unsigned *outputlen);
 187     void *decode_context;
 188     int (*decode)(void *context, const char *input, unsigned inputlen,
 189                   const char **output, unsigned *outputlen);
 190
 191     /* Pointer to delegated (client's) credentials, if supported by
 192        the SASL mechanism */
 193     void *client_creds;
 194
 195     /* for additions which don't require a version upgrade; set to 0 */
 196     const void *gss_peer_name;
 197     const void *gss_local_name;
 198     const char *cbindingname;   /* channel binding name from packet */
 199     int (*spare_fptr1)();
 200     int (*spare_fptr2)();
 201     unsigned int cbindingdisp;  /* channel binding disposition from client */
 202     int spare_int2;
 203     int spare_int3;
 204     int spare_int4;
 205
 206     /* set to 0 initially, this allows a plugin with extended parameters
 207      * to work with an older framework by updating version as parameters
 208      * are added.
 209      */
 210     int param_version;
 211 } sasl_out_params_t;
 212
 213
 214
 215 /* Used by both client and server side plugins */
 216 typedef enum  {
 217     SASL_INFO_LIST_START = 0,
 218     SASL_INFO_LIST_MECH,
 219     SASL_INFO_LIST_END
 220 } sasl_info_callback_stage_t;
 221
 222 /******************************
 223  * Channel binding macros     **
 224  ******************************/
 225
 226 typedef enum {
 227     SASL_CB_DISP_NONE = 0,          /* client did not support CB */
 228     SASL_CB_DISP_USED,              /* client supports and used CB */
 229     SASL_CB_DISP_WANT               /* client supports CB, thinks server does not */
 230 } sasl_cbinding_disp_t;
 231
 232 /* TRUE if channel binding is non-NULL */
 233 #define SASL_CB_PRESENT(params)     ((params)->cbinding != NULL)
 234 /* TRUE if channel binding is marked critical */
 235 #define SASL_CB_CRITICAL(params)    (SASL_CB_PRESENT(params) && \
 236                                      (params)->cbinding->critical)
 237
 238 /******************************
 239  * Client Mechanism Functions *
 240  ******************************/
 241
 242 /*
 243  * input parameters to client SASL plugin
 244  *
 245  * created / destroyed by the glue code
 246  *
 247  */
 248 typedef struct sasl_client_params {
 249     const char *service;        /* service name */
 250     const char *serverFQDN;     /* server fully qualified domain name */
 251     const char *clientFQDN;     /* client's fully qualified domain name */
 252     const sasl_utils_t *utils;  /* SASL API utility routines --
 253                                  * for a particular sasl_conn_t,
 254                                  * MUST remain valid until mech_free is
 255                                  * called */
 256     const sasl_callback_t *prompt_supp; /* client callback list */
 257     const char *iplocalport;    /* server IP domain literal & port */
 258     const char *ipremoteport;   /* client IP domain literal & port */
 259
 260     unsigned servicelen;        /* length of service */
 261     unsigned slen;              /* length of serverFQDN */
 262     unsigned clen;              /* length of clientFQDN */
 263     unsigned iploclen;          /* length of iplocalport */
 264     unsigned ipremlen;          /* length of ipremoteport */
 265
 266     /* application's security requirements & info */
 267     sasl_security_properties_t props;
 268     sasl_ssf_t external_ssf;    /* external SSF active */
 269
 270     /* for additions which don't require a version upgrade; set to 0 */
 271     const void *gss_creds;                  /* GSS credential handle */
 272     const sasl_channel_binding_t *cbinding; /* client channel binding */
 273     void *spare_ptr3;
 274     void *spare_ptr4;
 275
 276     /* Canonicalize a user name from on-wire to internal format
 277      *  added rjs3 2001-05-23
 278      *  Must be called once user name aquired if canon_user is non-NULL.
 279      *  conn        connection context
 280      *  in          user name from wire protocol (need not be NUL terminated)
 281      *  len         length of user name from wire protocol (0 = strlen(user))
 282      *  flags       for SASL_CU_* flags
 283      *  oparams     the user, authid, ulen, alen, fields are
 284      *              set appropriately after canonicalization/copying and
 285      *              authorization of arguments
 286      *
 287      *  responsible for setting user, ulen, authid, and alen in the oparams
 288      *  structure
 289      *
 290      *  default behavior is to strip leading and trailing whitespace, as
 291      *  well as allocating space for and copying the parameters.
 292      *
 293      * results:
 294      *  SASL_OK       -- success
 295      *  SASL_NOMEM    -- out of memory
 296      *  SASL_BADPARAM -- invalid conn
 297      *  SASL_BADPROT  -- invalid user/authid
 298      */
 299     int (*canon_user)(sasl_conn_t *conn,
 300                     const char *in, unsigned len,
 301                     unsigned flags,
 302                     sasl_out_params_t *oparams);
 303
 304     int (*spare_fptr1)();
 305
 306     unsigned int cbindingdisp;
 307     unsigned int spare_int2;
 308     int spare_int3;
 309
 310     /* flags field as passed to sasl_client_new */
 311     unsigned flags;
 312
 313     /* set to 0 initially, this allows a plugin with extended parameters
 314      * to work with an older framework by updating version as parameters
 315      * are added.
 316      */
 317     int param_version;
 318 } sasl_client_params_t;
 319
 320 /* features shared between client and server */
 321 /* These allow the glue code to handle client-first and server-last issues */
 322
 323 /* This indicates that the mechanism prefers to do client-send-first
 324  * if the protocol allows it. */
 325 #define SASL_FEAT_WANT_CLIENT_FIRST 0x0002
 326
 327 /* This feature is deprecated, instead, plugins should set *serverout to
 328  * non-NULL and return SASL_OK intelligently to allow flexible use of
 329  * server-last semantics */
 330 /* #define SASL_FEAT_WANT_SERVER_LAST 0x0004 */
 331
 332 /* This feature is deprecated, instead plugins should correctly set
 333  * SASL_FEAT_SERVER_FIRST as needed */
 334 /* #define SASL_FEAT_INTERNAL_CLIENT_FIRST 0x0008 */
 335
 336 /* This indicates that the plugin is server-first only.
 337  * Not defining either of SASL_FEAT_SERVER_FIRST or
 338  * SASL_FEAT_WANT_CLIENT_FIRST indicates that the mechanism will take care
 339  * of the client-first situation internally.
 340  */
 341 #define SASL_FEAT_SERVER_FIRST 0x0010
 342
 343 /* This plugin allows proxying */
 344 #define SASL_FEAT_ALLOWS_PROXY 0x0020
 345
 346 /* server plugin needs old password in order to change password */
 347 #define SASL_FEAT_NEED_OLD_PASSWD 0x0040
 348
 349 /* server plugin don't use cleartext userPassword attribute */
 350 #define SASL_FEAT_DONTUSE_USERPASSWD 0x0080
 351
 352 /* Underlying mechanism uses GSS framing */
 353 #define SASL_FEAT_GSS_FRAMING       0x0100
 354
 355 /* Underlying mechanism supports channel binding */
 356 #define SASL_FEAT_CHANNEL_BINDING  0x0200
 357
 358 /* client plug-in features */
 359 #define SASL_FEAT_NEEDSERVERFQDN 0x0001
 360
 361 /* a C object for a client mechanism
 362  */
 363 typedef struct sasl_client_plug {
 364     /* mechanism name */
 365     const char *mech_name;
 366
 367     /* best mech additional security layer strength factor */
 368     sasl_ssf_t max_ssf;
 369
 370     /* best security flags, as defined in sasl_security_properties_t */
 371     unsigned security_flags;
 372
 373     /* features of plugin */
 374     unsigned features;
 375
 376     /* required prompt ids, NULL = user/pass only */
 377     const unsigned long *required_prompts;
 378
 379     /* global state for mechanism */
 380     void *glob_context;
 381
 382     /* create context for mechanism, using params supplied
 383      *  glob_context   -- from above
 384      *  params         -- params from sasl_client_new
 385      *  conn_context   -- context for one connection
 386      * returns:
 387      *  SASL_OK        -- success
 388      *  SASL_NOMEM     -- not enough memory
 389      *  SASL_WRONGMECH -- mech doesn't support security params
 390      */
 391     int (*mech_new)(void *glob_context,
 392                     sasl_client_params_t *cparams,
 393                     void **conn_context);
 394
 395     /* perform one step of exchange.  NULL is passed for serverin on
 396      * first step.
 397      * returns:
 398      *  SASL_OK        -- success
 399      *  SASL_INTERACT  -- user interaction needed to fill in prompts
 400      *  SASL_BADPROT   -- server protocol incorrect/cancelled
 401      *  SASL_BADSERV   -- server failed mutual auth
 402      */
 403     int (*mech_step)(void *conn_context,
 404                      sasl_client_params_t *cparams,
 405                      const char *serverin,
 406                      unsigned serverinlen,
 407                      sasl_interact_t **prompt_need,
 408                      const char **clientout,
 409                      unsigned *clientoutlen,
 410                      sasl_out_params_t *oparams);
 411
 412     /* dispose of connection context from mech_new
 413      */
 414     void (*mech_dispose)(void *conn_context, const sasl_utils_t *utils);
 415
 416     /* free all global space used by mechanism
 417      *  mech_dispose must be called on all mechanisms first
 418      */
 419     void (*mech_free)(void *glob_context, const sasl_utils_t *utils);
 420
 421     /* perform precalculations during a network round-trip
 422      *  or idle period.  conn_context may be NULL
 423      *  returns 1 if action taken, 0 if no action taken
 424      */
 425     int (*idle)(void *glob_context,
 426                 void *conn_context,
 427                 sasl_client_params_t *cparams);
 428
 429     /* for additions which don't require a version upgrade; set to 0 */
 430     int (*spare_fptr1)();
 431     int (*spare_fptr2)();
 432 } sasl_client_plug_t;
 433
 434 #define SASL_CLIENT_PLUG_VERSION         4
 435
 436 /* plug-in entry point:
 437  *  utils       -- utility callback functions
 438  *  max_version -- highest client plug version supported
 439  * returns:
 440  *  out_version -- client plug version of result
 441  *  pluglist    -- list of mechanism plug-ins
 442  *  plugcount   -- number of mechanism plug-ins
 443  * results:
 444  *  SASL_OK       -- success
 445  *  SASL_NOMEM    -- failure
 446  *  SASL_BADVERS  -- max_version too small
 447  *  SASL_BADPARAM -- bad config string
 448  *  ...
 449  */
 450 typedef int sasl_client_plug_init_t(const sasl_utils_t *utils,
 451                                     int max_version,
 452                                     int *out_version,
 453                                     sasl_client_plug_t **pluglist,
 454                                     int *plugcount);
 455
 456
 457 /* add a client plug-in
 458  */
 459 LIBSASL_API int sasl_client_add_plugin(const char *plugname,
 460                                        sasl_client_plug_init_t *cplugfunc);
 461
 462 typedef struct client_sasl_mechanism
 463 {
 464     int version;
 465
 466     char *plugname;
 467     const sasl_client_plug_t *plug;
 468 } client_sasl_mechanism_t;
 469
 470 typedef void sasl_client_info_callback_t (client_sasl_mechanism_t *m,
 471                                           sasl_info_callback_stage_t stage,
 472                                           void *rock);
 473
 474 /* Dump information about available client plugins */
 475 LIBSASL_API int sasl_client_plugin_info (const char *mech_list,
 476         sasl_client_info_callback_t *info_cb,
 477         void *info_cb_rock);
 478
 479
 480 /********************
 481  * Server Functions *
 482  ********************/
 483
 484 /* log message formatting routine */
 485 typedef void sasl_logmsg_p(sasl_conn_t *conn, const char *fmt, ...);
 486
 487 /*
 488  * input parameters to server SASL plugin
 489  *
 490  * created / destroyed by the glue code
 491  *
 492  */
 493 typedef struct sasl_server_params {
 494     const char *service;        /* NULL = default service for user_exists
 495                                    and setpass */
 496     const char *appname;        /* name of calling application */
 497     const char *serverFQDN;     /* server default fully qualified domain name
 498                                  * (e.g., gethostname) */
 499     const char *user_realm;     /* realm for user (NULL = client supplied) */
 500     const char *iplocalport;    /* server IP domain literal & port */
 501     const char *ipremoteport;   /* client IP domain literal & port */
 502
 503     unsigned servicelen;        /* length of service */
 504     unsigned applen;            /* length of appname */
 505     unsigned slen;              /* length of serverFQDN */
 506     unsigned urlen;             /* length of user_realm */
 507     unsigned iploclen;          /* length of iplocalport */
 508     unsigned ipremlen;          /* length of ipremoteport */
 509
 510     /* This indicates the level of logging desired.  See SASL_LOG_*
 511      * in sasl.h
 512      *
 513      * Plug-ins can ignore this and just pass their desired level to
 514      * the log callback.  This is primarily used to eliminate logging which
 515      * might be a performance problem (e.g., full protocol trace) and
 516      * to select between SASL_LOG_TRACE and SASL_LOG_PASS alternatives
 517      */
 518     int log_level;
 519
 520     const sasl_utils_t *utils;  /* SASL API utility routines --
 521                                  * for a particular sasl_conn_t,
 522                                  * MUST remain valid until mech_free is
 523                                  * called */
 524     const sasl_callback_t *callbacks;   /* Callbacks from application */
 525
 526     /* application's security requirements */
 527     sasl_security_properties_t props;
 528     sasl_ssf_t external_ssf;    /* external SSF active */
 529
 530     /* Pointer to the function which takes the plaintext passphrase and
 531      *  transitions a user to non-plaintext mechanisms via setpass calls.
 532      *  (NULL = auto transition not enabled/supported)
 533      *
 534      *  If passlen is 0, it defaults to strlen(pass).
 535      *  returns 0 if no entry added, 1 if entry added
 536      */
 537     int (*transition)(sasl_conn_t *conn, const char *pass, unsigned passlen);
 538
 539     /* Canonicalize a user name from on-wire to internal format
 540      *  added cjn 1999-09-21
 541      *  Must be called once user name acquired if canon_user is non-NULL.
 542      *  conn        connection context
 543      *  user        user name from wire protocol (need not be NUL terminated)
 544      *  ulen        length of user name from wire protocol (0 = strlen(user))
 545      *  flags       for SASL_CU_* flags
 546      *  oparams     the user, authid, ulen, alen, fields are
 547      *              set appropriately after canonicalization/copying and
 548      *              authorization of arguments
 549      *
 550      *  responsible for setting user, ulen, authid, and alen in the oparams
 551      *  structure
 552      *
 553      *  default behavior is to strip leading and trailing whitespace, as
 554      *  well as allocating space for and copying the parameters.
 555      *
 556      * results:
 557      *  SASL_OK       -- success
 558      *  SASL_NOMEM    -- out of memory
 559      *  SASL_BADPARAM -- invalid conn
 560      *  SASL_BADPROT  -- invalid user/authid
 561      */
 562     int (*canon_user)(sasl_conn_t *conn,
 563                       const char *user, unsigned ulen,
 564                       unsigned flags,
 565                       sasl_out_params_t *oparams);
 566
 567     /* auxiliary property context (see definitions in prop.h)
 568      *  added cjn 2000-01-30
 569      *
 570      * NOTE: these properties are the ones associated with the
 571      * canonicalized "user" (user to login as / authorization id), not
 572      * the "authid" (user whose credentials are used / authentication id)
 573      * Prefix the property name with a "*" if a property associated with
 574      * the "authid" is interesting.
 575      */
 576     struct propctx *propctx;
 577
 578     /* for additions which don't require a version upgrade; set to 0 */
 579     const void *gss_creds;                  /* GSS credential handle */
 580     const sasl_channel_binding_t *cbinding; /* server channel binding */
 581     void *spare_ptr3;
 582     void *spare_ptr4;
 583     int (*spare_fptr1)();
 584     int (*spare_fptr2)();
 585     int spare_int1;
 586     int spare_int2;
 587     int spare_int3;
 588
 589     /* flags field as passed to sasl_server_new */
 590     unsigned flags;
 591
 592     /* set to 0 initially, this allows a plugin with extended parameters
 593      * to work with an older framework by updating version as parameters
 594      * are added.
 595      */
 596     int param_version;
 597 } sasl_server_params_t;
 598
 599 /* logging levels (more levels may be added later, if necessary):
 600  */
 601 #define SASL_LOG_NONE  0        /* don't log anything */
 602 #define SASL_LOG_ERR   1        /* log unusual errors (default) */
 603 #define SASL_LOG_FAIL  2        /* log all authentication failures */
 604 #define SASL_LOG_WARN  3        /* log non-fatal warnings */
 605 #define SASL_LOG_NOTE  4        /* more verbose than LOG_WARN */
 606 #define SASL_LOG_DEBUG 5        /* more verbose than LOG_NOTE */
 607 #define SASL_LOG_TRACE 6        /* traces of internal protocols */
 608 #define SASL_LOG_PASS  7        /* traces of internal protocols, including
 609                                  * passwords */
 610
 611 /* additional flags for setpass() function below:
 612  */
 613 /*      SASL_SET_CREATE                     create user if pass non-NULL */
 614 /*      SASL_SET_DISABLE                    disable user */
 615 #define SASL_SET_REMOVE  SASL_SET_CREATE /* remove user if pass is NULL */
 616
 617 /* features for server plug-in
 618  */
 619 #define SASL_FEAT_SERVICE    0x0200 /* service-specific passwords supported */
 620 #define SASL_FEAT_GETSECRET  0x0400 /* sasl_server_{get,put}secret_t callbacks
 621                                      * required by plug-in */
 622
 623 /* a C object for a server mechanism
 624  */
 625 typedef struct sasl_server_plug {
 626     /* mechanism name */
 627     const char *mech_name;
 628
 629     /* best mech additional security layer strength factor */
 630     sasl_ssf_t max_ssf;
 631
 632     /* best security flags, as defined in sasl_security_properties_t */
 633     unsigned security_flags;
 634
 635     /* features of plugin */
 636     unsigned features;
 637
 638     /* global state for mechanism */
 639     void *glob_context;
 640
 641     /* create a new mechanism handler
 642      *  glob_context  -- global context
 643      *  sparams       -- server config params
 644      *  challenge     -- server challenge from previous instance or NULL
 645      *  challen       -- length of challenge from previous instance or 0
 646      * out:
 647      *  conn_context  -- connection context
 648      *  errinfo       -- error information
 649      *
 650      * returns:
 651      *  SASL_OK       -- successfully created mech instance
 652      *  SASL_*        -- any other server error code
 653      */
 654     int (*mech_new)(void *glob_context,
 655                     sasl_server_params_t *sparams,
 656                     const char *challenge,
 657                     unsigned challen,
 658                     void **conn_context);
 659
 660     /* perform one step in exchange
 661      *
 662      * returns:
 663      *  SASL_OK       -- success, all done
 664      *  SASL_CONTINUE -- success, one more round trip
 665      *  SASL_*        -- any other server error code
 666      */
 667     int (*mech_step)(void *conn_context,
 668                      sasl_server_params_t *sparams,
 669                      const char *clientin,
 670                      unsigned clientinlen,
 671                      const char **serverout,
 672                      unsigned *serveroutlen,
 673                      sasl_out_params_t *oparams);
 674
 675     /* dispose of a connection state
 676      */
 677     void (*mech_dispose)(void *conn_context, const sasl_utils_t *utils);
 678
 679     /* free global state for mechanism
 680      *  mech_dispose must be called on all mechanisms first
 681      */
 682     void (*mech_free)(void *glob_context, const sasl_utils_t *utils);
 683
 684     /* set a password (optional)
 685      *  glob_context  -- global context
 686      *  sparams       -- service, middleware utilities, etc. props ignored
 687      *  user          -- user name
 688      *  pass          -- password/passphrase (NULL = disable/remove/delete)
 689      *  passlen       -- length of password/passphrase
 690      *  oldpass       -- old password/passphrase (NULL = transition)
 691      *  oldpasslen    -- length of password/passphrase
 692      *  flags         -- see above
 693      *
 694      * returns:
 695      *  SASL_NOCHANGE -- no change was needed
 696      *  SASL_NOUSER   -- no entry for user
 697      *  SASL_NOVERIFY -- no mechanism compatible entry for user
 698      *  SASL_PWLOCK   -- password locked
 699      *  SASL_DIABLED  -- account disabled
 700      *  etc.
 701      */
 702     int (*setpass)(void *glob_context,
 703                    sasl_server_params_t *sparams,
 704                    const char *user,
 705                    const char *pass, unsigned passlen,
 706                    const char *oldpass, unsigned oldpasslen,
 707                    unsigned flags);
 708
 709     /* query which mechanisms are available for user
 710      *  glob_context  -- context
 711      *  sparams       -- service, middleware utilities, etc. props ignored
 712      *  user          -- NUL terminated user name
 713      *  maxmech       -- max number of strings in mechlist (0 = no output)
 714      * output:
 715      *  mechlist      -- an array of C string pointers, filled in with
 716      *                   mechanism names available to the user
 717      *
 718      * returns:
 719      *  SASL_OK       -- success
 720      *  SASL_NOMEM    -- not enough memory
 721      *  SASL_FAIL     -- lower level failure
 722      *  SASL_DISABLED -- account disabled
 723      *  SASL_NOUSER   -- user not found
 724      *  SASL_BUFOVER  -- maxmech is too small
 725      *  SASL_NOVERIFY -- user found, but no mechanisms available
 726      */
 727     int (*user_query)(void *glob_context,
 728                       sasl_server_params_t *sparams,
 729                       const char *user,
 730                       int maxmech,
 731                       const char **mechlist);
 732
 733     /* perform precalculations during a network round-trip
 734      *  or idle period.  conn_context may be NULL (optional)
 735      *  returns 1 if action taken, 0 if no action taken
 736      */
 737     int (*idle)(void *glob_context,
 738                 void *conn_context,
 739                 sasl_server_params_t *sparams);
 740
 741     /* check if mechanism is available
 742      *  optional--if NULL, mechanism is available based on ENABLE= in config
 743      *
 744      *  If this routine sets conn_context to a non-NULL value, then the call
 745      *  to mech_new will be skipped.  This should not be done unless
 746      *  there's a significant performance benefit, since it can cause
 747      *  additional memory allocation in SASL core code to keep track of
 748      *  contexts potentially for multiple mechanisms.
 749      *
 750      *  This is called by the first call to sasl_listmech() for a
 751      *  given connection context, thus for a given protocol it may
 752      *  never be called.  Note that if mech_avail returns SASL_NOMECH,
 753      *  then that mechanism is considered disabled for the remainder
 754      *  of the session.  If mech_avail returns SASL_NOTDONE, then a
 755      *  future call to mech_avail may still return either SASL_OK
 756      *  or SASL_NOMECH.
 757      *
 758      *  returns SASL_OK on success,
 759      *          SASL_NOTDONE if mech is not available now, but may be later
 760      *                       (e.g. EXTERNAL w/o auth_id)
 761      *          SASL_NOMECH if mech disabled
 762      */
 763     int (*mech_avail)(void *glob_context,
 764                       sasl_server_params_t *sparams,
 765                       void **conn_context);
 766
 767     /* for additions which don't require a version upgrade; set to 0 */
 768     int (*spare_fptr2)();
 769 } sasl_server_plug_t;
 770
 771 #define SASL_SERVER_PLUG_VERSION 4
 772
 773 /* plug-in entry point:
 774  *  utils         -- utility callback functions
 775  *  plugname      -- name of plug-in (may be NULL)
 776  *  max_version   -- highest server plug version supported
 777  * returns:
 778  *  out_version   -- server plug-in version of result
 779  *  pluglist      -- list of mechanism plug-ins
 780  *  plugcount     -- number of mechanism plug-ins
 781  * results:
 782  *  SASL_OK       -- success
 783  *  SASL_NOMEM    -- failure
 784  *  SASL_BADVERS  -- max_version too small
 785  *  SASL_BADPARAM -- bad config string
 786  *  ...
 787  */
 788 typedef int sasl_server_plug_init_t(const sasl_utils_t *utils,
 789                                     int max_version,
 790                                     int *out_version,
 791                                     sasl_server_plug_t **pluglist,
 792                                     int *plugcount);
 793
 794 /*
 795  * add a server plug-in
 796  */
 797 LIBSASL_API int sasl_server_add_plugin(const char *plugname,
 798                                        sasl_server_plug_init_t *splugfunc);
 799
 800
 801 typedef struct server_sasl_mechanism
 802 {
 803     int version;
 804     int condition; /* set to SASL_NOUSER if no available users;
 805                       set to SASL_CONTINUE if delayed plugin loading */
 806     char *plugname; /* for AUTHSOURCE tracking */
 807     const sasl_server_plug_t *plug;
 808     char *f;       /* where should i load the mechanism from? */
 809 } server_sasl_mechanism_t;
 810
 811 typedef void sasl_server_info_callback_t (server_sasl_mechanism_t *m,
 812                                           sasl_info_callback_stage_t stage,
 813                                           void *rock);
 814
 815
 816 /* Dump information about available server plugins (separate functions are
 817    used for canon and auxprop plugins) */
 818 LIBSASL_API int sasl_server_plugin_info (const char *mech_list,
 819         sasl_server_info_callback_t *info_cb,
 820         void *info_cb_rock);
 821
 822
 823 /*********************************************************
 824  * user canonicalization plug-in -- added cjn 1999-09-29 *
 825  *********************************************************/
 826
 827 typedef struct sasl_canonuser {
 828     /* optional features of plugin (set to 0) */
 829     int features;
 830
 831     /* spare integer (set to 0) */
 832     int spare_int1;
 833
 834     /* global state for plugin */
 835     void *glob_context;
 836
 837     /* name of plugin */
 838     char *name;
 839
 840     /* free global state for plugin */
 841     void (*canon_user_free)(void *glob_context, const sasl_utils_t *utils);
 842
 843     /* canonicalize a username
 844      *  glob_context     -- global context from this structure
 845      *  sparams          -- server params, note user_realm&propctx elements
 846      *  user             -- user to login as (may not be NUL terminated)
 847      *  len              -- length of user name (0 = strlen(user))
 848      *  flags            -- for SASL_CU_* flags
 849      *  out              -- buffer to copy user name
 850      *  out_max          -- max length of user name
 851      *  out_len          -- set to length of user name
 852      *
 853      *  note that the output buffers MAY be the same as the input buffers.
 854      *
 855      * returns
 856      *  SASL_OK         on success
 857      *  SASL_BADPROT    username contains invalid character
 858      */
 859     int (*canon_user_server)(void *glob_context,
 860                              sasl_server_params_t *sparams,
 861                              const char *user, unsigned len,
 862                              unsigned flags,
 863                              char *out,
 864                              unsigned out_umax, unsigned *out_ulen);
 865
 866     int (*canon_user_client)(void *glob_context,
 867                              sasl_client_params_t *cparams,
 868                              const char *user, unsigned len,
 869                              unsigned flags,
 870                              char *out,
 871                              unsigned out_max, unsigned *out_len);
 872
 873     /* for additions which don't require a version upgrade; set to 0 */
 874     int (*spare_fptr1)();
 875     int (*spare_fptr2)();
 876     int (*spare_fptr3)();
 877 } sasl_canonuser_plug_t;
 878
 879 #define SASL_CANONUSER_PLUG_VERSION 5
 880
 881 /* default name for canonuser plug-in entry point is "sasl_canonuser_init"
 882  *  similar to sasl_server_plug_init model, except only returns one
 883  *  sasl_canonuser_plug_t structure;
 884  */
 885 typedef int sasl_canonuser_init_t(const sasl_utils_t *utils,
 886                                   int max_version,
 887                                   int *out_version,
 888                                   sasl_canonuser_plug_t **plug,
 889                                   const char *plugname);
 890
 891 /* add a canonuser plugin
 892  */
 893 LIBSASL_API int sasl_canonuser_add_plugin(const char *plugname,
 894                                   sasl_canonuser_init_t *canonuserfunc);
 895
 896 /******************************************************
 897  * auxiliary property plug-in -- added cjn 1999-09-29 *
 898  ******************************************************/
 899
 900 typedef struct sasl_auxprop_plug {
 901     /* optional features of plugin (none defined yet, set to 0) */
 902     int features;
 903
 904     /* spare integer, must be set to 0 */
 905     int spare_int1;
 906
 907     /* global state for plugin */
 908     void *glob_context;
 909
 910     /* free global state for plugin (OPTIONAL) */
 911     void (*auxprop_free)(void *glob_context, const sasl_utils_t *utils);
 912
 913     /* fill in fields of an auxiliary property context
 914      *  last element in array has id of SASL_AUX_END
 915      *  elements with non-0 len should be ignored.
 916      */
 917     void (*auxprop_lookup)(void *glob_context,
 918                            sasl_server_params_t *sparams,
 919                            unsigned flags,
 920                            const char *user, unsigned ulen);
 921
 922     /* name of the auxprop plugin */
 923     char *name;
 924
 925     /* store the fields/values of an auxiliary property context (OPTIONAL)
 926      *
 927      * if ctx is NULL, just check if storing properties is enabled
 928      *
 929      * returns
 930      *  SASL_OK         on success
 931      *  SASL_FAIL       on failure
 932      */
 933     int (*auxprop_store)(void *glob_context,
 934                          sasl_server_params_t *sparams,
 935                          struct propctx *ctx,
 936                          const char *user, unsigned ulen);
 937 } sasl_auxprop_plug_t;
 938
 939 /* auxprop lookup flags */
 940 #define SASL_AUXPROP_OVERRIDE 0x01 /* if clear, ignore auxiliary properties
 941                                     * with non-zero len field.  If set,
 942                                     * override value of those properties */
 943 #define SASL_AUXPROP_AUTHZID  0x02 /* if clear, we are looking up the
 944                                     * authid flags (prefixed with *), otherwise
 945                                     * we are looking up the authzid flags
 946                                     * (no prefix) */
 947
 948 #define SASL_AUXPROP_PLUG_VERSION 4
 949
 950 /* default name for auxprop plug-in entry point is "sasl_auxprop_init"
 951  *  similar to sasl_server_plug_init model, except only returns one
 952  *  sasl_auxprop_plug_t structure;
 953  */
 954 typedef int sasl_auxprop_init_t(const sasl_utils_t *utils,
 955                                 int max_version,
 956                                 int *out_version,
 957                                 sasl_auxprop_plug_t **plug,
 958                                 const char *plugname);
 959
 960 /* add an auxiliary property plug-in
 961  */
 962 LIBSASL_API int sasl_auxprop_add_plugin(const char *plugname,
 963                                         sasl_auxprop_init_t *auxpropfunc);
 964
 965 typedef void auxprop_info_callback_t (sasl_auxprop_plug_t *m,
 966                                       sasl_info_callback_stage_t stage,
 967                                       void *rock);
 968
 969 /* Dump information about available auxprop plugins (separate functions are
 970    used for canon and server authentication plugins) */
 971 LIBSASL_API int auxprop_plugin_info (const char *mech_list,
 972         auxprop_info_callback_t *info_cb,
 973         void *info_cb_rock);
 974
 975 #ifdef __cplusplus
 976 }
 977 #endif
 978
 979 #endif /* SASLPLUG_H */