usr/src/lib/libsasl/include/saslplug.h

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