aboutsummaryrefslogtreecommitdiffstats
path: root/contrib/libs/sasl/include/saslplug.h
blob: ab79e68cf65bfeee2f4628b04c65934503c5715b (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
/* saslplug.h --  API for SASL plug-ins
 */

#ifndef SASLPLUG_H
#define SASLPLUG_H 1

#ifndef MD5GLOBAL_H
#include "md5global.h"
#endif
#ifndef MD5_H
#include "md5.h"
#endif
#ifndef HMAC_MD5_H
#include "hmac-md5.h"
#endif
#ifndef PROP_H
#include "prop.h"
#endif

#ifdef __cplusplus
extern "C" {
#endif

/* callback to lookup a sasl_callback_t for a connection
 * input:
 *  conn        -- the connection to lookup a callback for
 *  callbacknum -- the number of the callback
 * output:
 *  pproc       -- pointer to the callback function (set to NULL on failure)
 *  pcontext    -- pointer to the callback context (set to NULL on failure)
 * returns:
 *  SASL_OK -- no error
 *  SASL_FAIL -- unable to find a callback of the requested type
 *  SASL_INTERACT -- caller must use interaction to get data
 */
typedef int (*sasl_callback_ft)(void);
typedef int sasl_getcallback_t(sasl_conn_t *conn,
			       unsigned long callbackid,
			       sasl_callback_ft * pproc,
			       void **pcontext);

/* The sasl_utils structure will remain backwards compatible unless
 * the SASL_*_PLUG_VERSION is changed incompatibly
 * higher SASL_UTILS_VERSION numbers indicate more functions are available
 */
#define SASL_UTILS_VERSION 4

/* utility function set for plug-ins
 */
typedef struct sasl_utils {
    int version;

    /* contexts */
    sasl_conn_t *conn;
    sasl_rand_t *rpool;
    void *getopt_context;

    /* option function */
    sasl_getopt_t *getopt;
    
    /* allocation functions: */
    sasl_malloc_t *malloc;
    sasl_calloc_t *calloc;
    sasl_realloc_t *realloc;
    sasl_free_t *free;

    /* mutex functions: */
    sasl_mutex_alloc_t *mutex_alloc;
    sasl_mutex_lock_t *mutex_lock;
    sasl_mutex_unlock_t *mutex_unlock;
    sasl_mutex_free_t *mutex_free;

    /* MD5 hash and HMAC functions */
    void (*MD5Init)(MD5_CTX *);
    void (*MD5Update)(MD5_CTX *, const unsigned char *text, unsigned int len);
    void (*MD5Final)(unsigned char [16], MD5_CTX *);
    void (*hmac_md5)(const unsigned char *text, int text_len,
		     const unsigned char *key, int key_len,
		     unsigned char [16]);
    void (*hmac_md5_init)(HMAC_MD5_CTX *, const unsigned char *key, int len);
    /* hmac_md5_update() is just a call to MD5Update on inner context */
    void (*hmac_md5_final)(unsigned char [16], HMAC_MD5_CTX *);
    void (*hmac_md5_precalc)(HMAC_MD5_STATE *,
			     const unsigned char *key, int len);
    void (*hmac_md5_import)(HMAC_MD5_CTX *, HMAC_MD5_STATE *);

    /* mechanism utility functions (same as above): */
    int (*mkchal)(sasl_conn_t *conn, char *buf, unsigned maxlen,
		  unsigned hostflag);
    int (*utf8verify)(const char *str, unsigned len);
    void (*rand)(sasl_rand_t *rpool, char *buf, unsigned len);
    void (*churn)(sasl_rand_t *rpool, const char *data, unsigned len);

    /* This allows recursive calls to the sasl_checkpass() routine from
     * within a SASL plug-in.  This MUST NOT be used in the PLAIN mechanism
     * as sasl_checkpass MAY be a front-end for the PLAIN mechanism.
     * This is intended for use by the non-standard LOGIN mechanism and
     * potentially by a future mechanism which uses public-key technology to
     * set up a lightweight encryption layer just for sending a password.
     */
    int (*checkpass)(sasl_conn_t *conn,
		     const char *user, unsigned userlen,
		     const char *pass, unsigned passlen);
    
    /* Access to base64 encode/decode routines */
    int (*decode64)(const char *in, unsigned inlen,
		    char *out, unsigned outmax, unsigned *outlen);
    int (*encode64)(const char *in, unsigned inlen,
		    char *out, unsigned outmax, unsigned *outlen);

    /* erase a buffer */
    void (*erasebuffer)(char *buf, unsigned len);

    /* callback to sasl_getprop() and sasl_setprop() */
    int (*getprop)(sasl_conn_t *conn, int propnum, const void **pvalue);
    int (*setprop)(sasl_conn_t *conn, int propnum, const void *value);

    /* callback function */
    sasl_getcallback_t *getcallback;

    /* format a message and then pass it to the SASL_CB_LOG callback
     *
     * use syslog()-style formatting (printf with %m as a human readable text
     * (strerror()) for the error specified as the parameter).
     * The implementation may use a fixed size buffer not smaller
     * than 512 octets if it securely truncates the message.
     *
     * level is a SASL_LOG_* level (see sasl.h)
     */
    void (*log)(sasl_conn_t *conn, int level, const char *fmt, ...) __attribute__((format(printf, 3, 4)));

    /* callback to sasl_seterror() */
    void (*seterror)(sasl_conn_t *conn, unsigned flags, const char *fmt, ...) __attribute__((format(printf, 3, 4)));

    /* spare function pointer */
    int *(*spare_fptr)(void);

    /* auxiliary property utilities */
    struct propctx *(*prop_new)(unsigned estimate);
    int (*prop_dup)(struct propctx *src_ctx, struct propctx **dst_ctx);
    int (*prop_request)(struct propctx *ctx, const char **names);
    const struct propval *(*prop_get)(struct propctx *ctx);
    int (*prop_getnames)(struct propctx *ctx, const char **names,
			 struct propval *vals);
    void (*prop_clear)(struct propctx *ctx, int requests);
    void (*prop_dispose)(struct propctx **ctx);
    int (*prop_format)(struct propctx *ctx, const char *sep, int seplen,
		       char *outbuf, unsigned outmax, unsigned *outlen);
    int (*prop_set)(struct propctx *ctx, const char *name,
		    const char *value, int vallen);
    int (*prop_setvals)(struct propctx *ctx, const char *name,
			const char **values);
    void (*prop_erase)(struct propctx *ctx, const char *name);
    int (*auxprop_store)(sasl_conn_t *conn,
			 struct propctx *ctx, const char *user);

    /* for additions which don't require a version upgrade; set to 0 */
    int (*spare_fptr1)(void);
    int (*spare_fptr2)(void);
} sasl_utils_t;

/*
 * output parameters from SASL API
 *
 * created / destroyed by the glue code, though probably filled in
 * by a combination of the plugin, the glue code, and the canon_user callback.
 *
 */
typedef struct sasl_out_params {
    unsigned doneflag;		/* exchange complete */

    const char *user;		/* canonicalized user name */
    const char *authid;		/* canonicalized authentication id */

    unsigned ulen;		/* length of canonicalized user name */
    unsigned alen;		/* length of canonicalized authid */

    /* security layer information */
    unsigned maxoutbuf;         /* Maximum buffer size, which will
                                   produce buffer no bigger than the
                                   negotiated SASL maximum buffer size */
    sasl_ssf_t mech_ssf;   /* Should be set non-zero if negotiation of a
	 		    * security layer was *attempted*, even if
			    * the negotiation failed */
    void *encode_context;
    int (*encode)(void *context, const struct iovec *invec, unsigned numiov,
		  const char **output, unsigned *outputlen);
    void *decode_context;
    int (*decode)(void *context, const char *input, unsigned inputlen,
		  const char **output, unsigned *outputlen);
    
    /* Pointer to delegated (client's) credentials, if supported by
       the SASL mechanism */
    void *client_creds;

    /* for additions which don't require a version upgrade; set to 0 */
    const void *gss_peer_name;
    const void *gss_local_name;
    const char *cbindingname;   /* channel binding name from packet */
    int (*spare_fptr1)(void);
    int (*spare_fptr2)(void);
    unsigned int cbindingdisp;  /* channel binding disposition from client */
    int spare_int2;
    int spare_int3;
    int spare_int4;

    /* set to 0 initially, this allows a plugin with extended parameters
     * to work with an older framework by updating version as parameters
     * are added.
     */
    int param_version;
} sasl_out_params_t;



/* Used by both client and server side plugins */
typedef enum  {
    SASL_INFO_LIST_START = 0,
    SASL_INFO_LIST_MECH,
    SASL_INFO_LIST_END
} sasl_info_callback_stage_t;

/******************************
 * Channel binding macros     **
 ******************************/

typedef enum {
    SASL_CB_DISP_NONE = 0,          /* client did not support CB */
    SASL_CB_DISP_WANT,              /* client supports CB, thinks server does not */
    SASL_CB_DISP_USED               /* client supports and used CB */
} sasl_cbinding_disp_t;

/* TRUE if channel binding is non-NULL */
#define SASL_CB_PRESENT(params)     ((params)->cbinding != NULL)
/* TRUE if channel binding is marked critical */
#define SASL_CB_CRITICAL(params)    (SASL_CB_PRESENT(params) && \
				     (params)->cbinding->critical)

/******************************
 * Client Mechanism Functions *
 ******************************/

/*
 * input parameters to client SASL plugin
 *
 * created / destroyed by the glue code
 *
 */
typedef struct sasl_client_params {
    const char *service;	/* service name */
    const char *serverFQDN;	/* server fully qualified domain name */
    const char *clientFQDN;	/* client's fully qualified domain name */
    const sasl_utils_t *utils;	/* SASL API utility routines --
				 * for a particular sasl_conn_t,
				 * MUST remain valid until mech_free is
				 * called */
    const sasl_callback_t *prompt_supp; /* client callback list */
    const char *iplocalport;	/* server IP domain literal & port */
    const char *ipremoteport;	/* client IP domain literal & port */

    unsigned servicelen;	/* length of service */
    unsigned slen;		/* length of serverFQDN */
    unsigned clen;		/* length of clientFQDN */
    unsigned iploclen;		/* length of iplocalport */
    unsigned ipremlen;		/* length of ipremoteport */

    /* application's security requirements & info */
    sasl_security_properties_t props;
    sasl_ssf_t external_ssf;	/* external SSF active */

    /* for additions which don't require a version upgrade; set to 0 */
    const void *gss_creds;                  /* GSS credential handle */
    const sasl_channel_binding_t *cbinding; /* client channel binding */
    const sasl_http_request_t *http_request;/* HTTP Digest request method */
    void *spare_ptr4;

    /* Canonicalize a user name from on-wire to internal format
     *  added rjs3 2001-05-23
     *  Must be called once user name aquired if canon_user is non-NULL.
     *  conn        connection context
     *  in          user name from wire protocol (need not be NUL terminated)
     *  len         length of user name from wire protocol (0 = strlen(user))
     *  flags       for SASL_CU_* flags
     *  oparams     the user, authid, ulen, alen, fields are
     *              set appropriately after canonicalization/copying and
     *              authorization of arguments
     *
     *  responsible for setting user, ulen, authid, and alen in the oparams
     *  structure
     *
     *  default behavior is to strip leading and trailing whitespace, as
     *  well as allocating space for and copying the parameters.
     *
     * results:
     *  SASL_OK       -- success
     *  SASL_NOMEM    -- out of memory
     *  SASL_BADPARAM -- invalid conn
     *  SASL_BADPROT  -- invalid user/authid
     */
    int (*canon_user)(sasl_conn_t *conn,
                    const char *in, unsigned len,
                    unsigned flags,
                    sasl_out_params_t *oparams);

    int (*spare_fptr1)(void);

    unsigned int cbindingdisp;
    int spare_int2;
    int spare_int3;

    /* flags field as passed to sasl_client_new */
    unsigned flags;

    /* set to 0 initially, this allows a plugin with extended parameters
     * to work with an older framework by updating version as parameters
     * are added.
     */
    int param_version;
} sasl_client_params_t;

/* features shared between client and server */
/* These allow the glue code to handle client-first and server-last issues */

/* This indicates that the mechanism prefers to do client-send-first
 * if the protocol allows it. */
#define SASL_FEAT_WANT_CLIENT_FIRST	0x0002

/* This feature is deprecated.  Instead, plugins should set *serverout to
 * non-NULL and return SASL_OK intelligently to allow flexible use of
 * server-last semantics
#define SASL_FEAT_WANT_SERVER_LAST	0x0004
*/

/* This feature is deprecated.  Instead, plugins should correctly set
 * SASL_FEAT_SERVER_FIRST as needed
#define SASL_FEAT_INTERNAL_CLIENT_FIRST	0x0008
*/

/* This indicates that the plugin is server-first only. 
 * Not defining either of SASL_FEAT_SERVER_FIRST or 
 * SASL_FEAT_WANT_CLIENT_FIRST indicates that the mechanism
 * will handle the client-first situation internally.
 */
#define SASL_FEAT_SERVER_FIRST		0x0010

/* This plugin allows proxying */
#define SASL_FEAT_ALLOWS_PROXY		0x0020

/* server plugin don't use cleartext userPassword attribute */
#define SASL_FEAT_DONTUSE_USERPASSWD 	0x0080

/* Underlying mechanism uses GSS framing */
#define SASL_FEAT_GSS_FRAMING	 	0x0100

/* Underlying mechanism supports channel binding */
#define SASL_FEAT_CHANNEL_BINDING	0x0800

/* This plugin can be used for HTTP authentication */
#define SASL_FEAT_SUPPORTS_HTTP	    	0x1000

/* client plug-in features */
#define SASL_FEAT_NEEDSERVERFQDN	0x0001

/* a C object for a client mechanism
 */
typedef struct sasl_client_plug {
    /* mechanism name */
    const char *mech_name;

    /* best mech additional security layer strength factor */
    sasl_ssf_t max_ssf;

    /* best security flags, as defined in sasl_security_properties_t */
    unsigned security_flags;

    /* features of plugin */
    unsigned features;

    /* required prompt ids, NULL = user/pass only */
    const unsigned long *required_prompts;
    
    /* global state for mechanism */
    void *glob_context;
    
    /* create context for mechanism, using params supplied
     *  glob_context   -- from above
     *  params         -- params from sasl_client_new
     *  conn_context   -- context for one connection
     * returns:
     *  SASL_OK        -- success
     *  SASL_NOMEM     -- not enough memory
     *  SASL_WRONGMECH -- mech doesn't support security params
     */
    int (*mech_new)(void *glob_context,
		    sasl_client_params_t *cparams,
		    void **conn_context);
    
    /* perform one step of exchange.  NULL is passed for serverin on
     * first step.
     * returns:
     *  SASL_OK        -- success
     *  SASL_INTERACT  -- user interaction needed to fill in prompts
     *  SASL_BADPROT   -- server protocol incorrect/cancelled
     *  SASL_BADSERV   -- server failed mutual auth
     */
    int (*mech_step)(void *conn_context,
		     sasl_client_params_t *cparams,
		     const char *serverin,
		     unsigned serverinlen,
		     sasl_interact_t **prompt_need,
		     const char **clientout,
		     unsigned *clientoutlen,
		     sasl_out_params_t *oparams);
    
    /* dispose of connection context from mech_new
     */
    void (*mech_dispose)(void *conn_context, const sasl_utils_t *utils);
    
    /* free all global space used by mechanism
     *  mech_dispose must be called on all mechanisms first
     */
    void (*mech_free)(void *glob_context, const sasl_utils_t *utils);
     
    /* perform precalculations during a network round-trip
     *  or idle period.  conn_context may be NULL
     *  returns 1 if action taken, 0 if no action taken
     */
    int (*idle)(void *glob_context,
		void *conn_context,
		sasl_client_params_t *cparams);

    /* for additions which don't require a version upgrade; set to 0 */
    int (*spare_fptr1)(void);
    int (*spare_fptr2)(void);
} sasl_client_plug_t;

#define SASL_CLIENT_PLUG_VERSION         4

/* plug-in entry point:
 *  utils       -- utility callback functions
 *  max_version -- highest client plug version supported
 * returns:
 *  out_version -- client plug version of result
 *  pluglist    -- list of mechanism plug-ins
 *  plugcount   -- number of mechanism plug-ins
 * results:
 *  SASL_OK       -- success
 *  SASL_NOMEM    -- failure
 *  SASL_BADVERS  -- max_version too small
 *  SASL_BADPARAM -- bad config string
 *  ...
 */
typedef int sasl_client_plug_init_t(const sasl_utils_t *utils,
				    int max_version,
				    int *out_version,
				    sasl_client_plug_t **pluglist,
				    int *plugcount);


/* add a client plug-in
 */
LIBSASL_API int sasl_client_add_plugin(const char *plugname,
				       sasl_client_plug_init_t *cplugfunc);

typedef struct client_sasl_mechanism
{
    int version;

    char *plugname;
    const sasl_client_plug_t *plug;
} client_sasl_mechanism_t;

typedef void sasl_client_info_callback_t (client_sasl_mechanism_t *m,
					  sasl_info_callback_stage_t stage,
					  void *rock);

/* Dump information about available client plugins */
LIBSASL_API int sasl_client_plugin_info (const char *mech_list,
	sasl_client_info_callback_t *info_cb,
	void *info_cb_rock);


/********************
 * Server Functions *
 ********************/

/* log message formatting routine */
typedef void sasl_logmsg_p(sasl_conn_t *conn, const char *fmt, ...) __attribute__((format(printf, 2, 3)));

/*
 * input parameters to server SASL plugin
 *
 * created / destroyed by the glue code
 *
 */
typedef struct sasl_server_params {
    const char *service;	/* NULL = default service for user_exists
				   and setpass */
    const char *appname;	/* name of calling application */
    const char *serverFQDN;	/* server default fully qualified domain name
				 * (e.g., gethostname) */
    const char *user_realm;	/* realm for user (NULL = client supplied) */
    const char *iplocalport;	/* server IP domain literal & port */
    const char *ipremoteport;	/* client IP domain literal & port */

    unsigned servicelen;	/* length of service */
    unsigned applen;		/* length of appname */
    unsigned slen;		/* length of serverFQDN */
    unsigned urlen;		/* length of user_realm */
    unsigned iploclen;		/* length of iplocalport */
    unsigned ipremlen;		/* length of ipremoteport */

    /* This indicates the level of logging desired.  See SASL_LOG_*
     * in sasl.h
     *
     * Plug-ins can ignore this and just pass their desired level to
     * the log callback.  This is primarily used to eliminate logging which
     * might be a performance problem (e.g., full protocol trace) and
     * to select between SASL_LOG_TRACE and SASL_LOG_PASS alternatives
     */
    int log_level;

    const sasl_utils_t *utils;	/* SASL API utility routines --
				 * for a particular sasl_conn_t,
				 * MUST remain valid until mech_free is
				 * called */
    const sasl_callback_t *callbacks;	/* Callbacks from application */

    /* application's security requirements */
    sasl_security_properties_t props;
    sasl_ssf_t external_ssf;	/* external SSF active */

    /* Pointer to the function which takes the plaintext passphrase and
     *  transitions a user to non-plaintext mechanisms via setpass calls.
     *  (NULL = auto transition not enabled/supported)
     *
     *  If passlen is 0, it defaults to strlen(pass).
     *  returns 0 if no entry added, 1 if entry added
     */
    int (*transition)(sasl_conn_t *conn, const char *pass, unsigned passlen);

    /* Canonicalize a user name from on-wire to internal format
     *  added cjn 1999-09-21
     *  Must be called once user name acquired if canon_user is non-NULL.
     *  conn        connection context
     *  user        user name from wire protocol (need not be NUL terminated)
     *  ulen        length of user name from wire protocol (0 = strlen(user))
     *  flags       for SASL_CU_* flags
     *  oparams     the user, authid, ulen, alen, fields are
     *              set appropriately after canonicalization/copying and
     *              authorization of arguments
     *
     *  responsible for setting user, ulen, authid, and alen in the oparams
     *  structure
     *
     *  default behavior is to strip leading and trailing whitespace, as
     *  well as allocating space for and copying the parameters.
     *
     * results:
     *  SASL_OK       -- success
     *  SASL_NOMEM    -- out of memory
     *  SASL_BADPARAM -- invalid conn
     *  SASL_BADPROT  -- invalid user/authid
     */
    int (*canon_user)(sasl_conn_t *conn,
		      const char *user, unsigned ulen,
		      unsigned flags,
		      sasl_out_params_t *oparams);
    
    /* auxiliary property context (see definitions in prop.h)
     *  added cjn 2000-01-30
     *
     * NOTE: these properties are the ones associated with the
     * canonicalized "user" (user to login as / authorization id), not
     * the "authid" (user whose credentials are used / authentication id)
     * Prefix the property name with a "*" if a property associated with
     * the "authid" is interesting.
     */
    struct propctx *propctx;

    /* for additions which don't require a version upgrade; set to 0 */
    const void *gss_creds;                  /* GSS credential handle */
    const sasl_channel_binding_t *cbinding; /* server channel binding */
    const sasl_http_request_t *http_request;/* HTTP Digest request method */
    void *spare_ptr4;
    int (*spare_fptr1)(void);
    int (*spare_fptr2)(void);
    int spare_int1;
    int spare_int2;
    int spare_int3;

    /* flags field as passed to sasl_server_new */
    unsigned flags;

    /* set to 0 initially, this allows a plugin with extended parameters
     * to work with an older framework by updating version as parameters
     * are added.
     */
    int param_version;
} sasl_server_params_t;

/* logging levels (more levels may be added later, if necessary):
 */
#define SASL_LOG_NONE  0	/* don't log anything */
#define SASL_LOG_ERR   1	/* log unusual errors (default) */
#define SASL_LOG_FAIL  2	/* log all authentication failures */
#define SASL_LOG_WARN  3	/* log non-fatal warnings */
#define SASL_LOG_NOTE  4	/* more verbose than LOG_WARN */
#define SASL_LOG_DEBUG 5	/* more verbose than LOG_NOTE */
#define SASL_LOG_TRACE 6	/* traces of internal protocols */
#define SASL_LOG_PASS  7	/* traces of internal protocols, including
				 * passwords */

/* additional flags for setpass() function below:
 */
/*      SASL_SET_CREATE                     create user if pass non-NULL */
/*      SASL_SET_DISABLE                    disable user */
#define SASL_SET_REMOVE  SASL_SET_CREATE /* remove user if pass is NULL */

/* features for server plug-in
 */
#define SASL_FEAT_SERVICE    0x0200 /* service-specific passwords supported */
#define SASL_FEAT_GETSECRET  0x0400 /* sasl_server_{get,put}secret_t callbacks
				     * required by plug-in */

/* a C object for a server mechanism
 */
typedef struct sasl_server_plug {
    /* mechanism name */
    const char *mech_name;

    /* best mech additional security layer strength factor */
    sasl_ssf_t max_ssf;

    /* best security flags, as defined in sasl_security_properties_t */
    unsigned security_flags;

    /* features of plugin */
    unsigned features;
    
    /* global state for mechanism */
    void *glob_context;

    /* create a new mechanism handler
     *  glob_context  -- global context
     *  sparams       -- server config params
     *  challenge     -- server challenge from previous instance or NULL
     *  challen       -- length of challenge from previous instance or 0
     * out:
     *  conn_context  -- connection context
     *  errinfo       -- error information
     *
     * returns:
     *  SASL_OK       -- successfully created mech instance
     *  SASL_*        -- any other server error code
     */
    int (*mech_new)(void *glob_context,
		    sasl_server_params_t *sparams,
		    const char *challenge,
		    unsigned challen,
		    void **conn_context);
    
    /* perform one step in exchange
     *
     * returns:
     *  SASL_OK       -- success, all done
     *  SASL_CONTINUE -- success, one more round trip
     *  SASL_*        -- any other server error code
     */
    int (*mech_step)(void *conn_context,
		     sasl_server_params_t *sparams,
		     const char *clientin,
		     unsigned clientinlen,
		     const char **serverout,
		     unsigned *serveroutlen,
		     sasl_out_params_t *oparams);
    
    /* dispose of a connection state
     */
    void (*mech_dispose)(void *conn_context, const sasl_utils_t *utils);
    
    /* free global state for mechanism
     *  mech_dispose must be called on all mechanisms first
     */
    void (*mech_free)(void *glob_context, const sasl_utils_t *utils);
    
    /* set a password (optional)
     *  glob_context  -- global context
     *  sparams       -- service, middleware utilities, etc. props ignored
     *  user          -- user name
     *  pass          -- password/passphrase (NULL = disable/remove/delete)
     *  passlen       -- length of password/passphrase
     *  oldpass       -- old password/passphrase (NULL = transition)
     *  oldpasslen    -- length of password/passphrase
     *  flags         -- see above
     *
     * returns:
     *  SASL_NOCHANGE -- no change was needed
     *  SASL_NOUSER   -- no entry for user
     *  SASL_NOVERIFY -- no mechanism compatible entry for user
     *  SASL_PWLOCK   -- password locked
     *  SASL_DIABLED  -- account disabled
     *  etc.
     */
    int (*setpass)(void *glob_context,
		   sasl_server_params_t *sparams,
		   const char *user,
		   const char *pass, unsigned passlen,
		   const char *oldpass, unsigned oldpasslen,
		   unsigned flags);

    /* query which mechanisms are available for user
     *  glob_context  -- context
     *  sparams       -- service, middleware utilities, etc. props ignored
     *  user          -- NUL terminated user name
     *  maxmech       -- max number of strings in mechlist (0 = no output)
     * output:
     *  mechlist      -- an array of C string pointers, filled in with
     *                   mechanism names available to the user
     *
     * returns:
     *  SASL_OK       -- success
     *  SASL_NOMEM    -- not enough memory
     *  SASL_FAIL     -- lower level failure
     *  SASL_DISABLED -- account disabled
     *  SASL_NOUSER   -- user not found
     *  SASL_BUFOVER  -- maxmech is too small
     *  SASL_NOVERIFY -- user found, but no mechanisms available
     */
    int (*user_query)(void *glob_context,
		      sasl_server_params_t *sparams,
		      const char *user,
		      int maxmech,
		      const char **mechlist);
     
    /* perform precalculations during a network round-trip
     *  or idle period.  conn_context may be NULL (optional)
     *  returns 1 if action taken, 0 if no action taken
     */
    int (*idle)(void *glob_context,
		void *conn_context,
		sasl_server_params_t *sparams);

    /* check if mechanism is available
     *  optional--if NULL, mechanism is available based on ENABLE= in config
     *
     *  If this routine sets conn_context to a non-NULL value, then the call
     *  to mech_new will be skipped.  This should not be done unless
     *  there's a significant performance benefit, since it can cause
     *  additional memory allocation in SASL core code to keep track of
     *  contexts potentially for multiple mechanisms.
     *
     *  This is called by the first call to sasl_listmech() for a
     *  given connection context, thus for a given protocol it may
     *  never be called.  Note that if mech_avail returns SASL_NOMECH,
     *  then that mechanism is considered disabled for the remainder
     *  of the session.  If mech_avail returns SASL_NOTDONE, then a
     *  future call to mech_avail may still return either SASL_OK
     *  or SASL_NOMECH.
     *
     *  returns SASL_OK on success,
     *          SASL_NOTDONE if mech is not available now, but may be later
     *                       (e.g. EXTERNAL w/o auth_id)
     *          SASL_NOMECH if mech disabled
     */
    int (*mech_avail)(void *glob_context,
		      sasl_server_params_t *sparams,
		      void **conn_context);

    /* for additions which don't require a version upgrade; set to 0 */
    int (*spare_fptr2)(void);
} sasl_server_plug_t;

#define SASL_SERVER_PLUG_VERSION 4

/* plug-in entry point:
 *  utils         -- utility callback functions
 *  plugname      -- name of plug-in (may be NULL)
 *  max_version   -- highest server plug version supported
 * returns:
 *  out_version   -- server plug-in version of result
 *  pluglist      -- list of mechanism plug-ins
 *  plugcount     -- number of mechanism plug-ins
 * results:
 *  SASL_OK       -- success
 *  SASL_NOMEM    -- failure
 *  SASL_BADVERS  -- max_version too small
 *  SASL_BADPARAM -- bad config string
 *  ...
 */
typedef int sasl_server_plug_init_t(const sasl_utils_t *utils,
				    int max_version,
				    int *out_version,
				    sasl_server_plug_t **pluglist,
				    int *plugcount);

/* 
 * add a server plug-in
 */
LIBSASL_API int sasl_server_add_plugin(const char *plugname,
				       sasl_server_plug_init_t *splugfunc);


typedef struct server_sasl_mechanism
{
    int version;
    int condition; /* set to SASL_NOUSER if no available users;
		      set to SASL_CONTINUE if delayed plugin loading */
    char *plugname; /* for AUTHSOURCE tracking */
    const sasl_server_plug_t *plug;
    char *f;       /* where should i load the mechanism from? */
} server_sasl_mechanism_t;

typedef void sasl_server_info_callback_t (server_sasl_mechanism_t *m,
					  sasl_info_callback_stage_t stage,
					  void *rock);


/* Dump information about available server plugins (separate functions are
   used for canon and auxprop plugins) */
LIBSASL_API int sasl_server_plugin_info (const char *mech_list,
	sasl_server_info_callback_t *info_cb,
	void *info_cb_rock);


/*********************************************************
 * user canonicalization plug-in -- added cjn 1999-09-29 *
 *********************************************************/

typedef struct sasl_canonuser {
    /* optional features of plugin (set to 0) */
    int features;

    /* spare integer (set to 0) */
    int spare_int1;

    /* global state for plugin */
    void *glob_context;

    /* name of plugin */
    char *name;

    /* free global state for plugin */
    void (*canon_user_free)(void *glob_context, const sasl_utils_t *utils);

    /* canonicalize a username
     *  glob_context     -- global context from this structure
     *  sparams          -- server params, note user_realm&propctx elements
     *  user             -- user to login as (may not be NUL terminated)
     *  len              -- length of user name (0 = strlen(user))
     *  flags            -- for SASL_CU_* flags
     *  out              -- buffer to copy user name
     *  out_max          -- max length of user name
     *  out_len          -- set to length of user name
     *
     *  note that the output buffers MAY be the same as the input buffers.
     *
     * returns
     *  SASL_OK         on success
     *  SASL_BADPROT    username contains invalid character
     */
    int (*canon_user_server)(void *glob_context,
			     sasl_server_params_t *sparams,
			     const char *user, unsigned len,
			     unsigned flags,
			     char *out,
			     unsigned out_umax, unsigned *out_ulen);

    int (*canon_user_client)(void *glob_context,
			     sasl_client_params_t *cparams,
			     const char *user, unsigned len,
			     unsigned flags,
			     char *out,
			     unsigned out_max, unsigned *out_len);

    /* for additions which don't require a version upgrade; set to 0 */
    int (*spare_fptr1)(void);
    int (*spare_fptr2)(void);
    int (*spare_fptr3)(void);
} sasl_canonuser_plug_t;

#define SASL_CANONUSER_PLUG_VERSION 5

/* default name for canonuser plug-in entry point is "sasl_canonuser_init"
 *  similar to sasl_server_plug_init model, except only returns one
 *  sasl_canonuser_plug_t structure;
 */
typedef int sasl_canonuser_init_t(const sasl_utils_t *utils,
				  int max_version,
				  int *out_version,
				  sasl_canonuser_plug_t **plug,
				  const char *plugname);

/* add a canonuser plugin
 */
LIBSASL_API int sasl_canonuser_add_plugin(const char *plugname,
				  sasl_canonuser_init_t *canonuserfunc);

/******************************************************
 * auxiliary property plug-in -- added cjn 1999-09-29 *
 ******************************************************/

typedef struct sasl_auxprop_plug {
    /* optional features of plugin (none defined yet, set to 0) */
    int features;

    /* spare integer, must be set to 0 */
    int spare_int1;

    /* global state for plugin */
    void *glob_context;

    /* free global state for plugin (OPTIONAL) */
    void (*auxprop_free)(void *glob_context, const sasl_utils_t *utils);

    /* fill in fields of an auxiliary property context
     *  last element in array has id of SASL_AUX_END
     *  elements with non-0 len should be ignored.
     */
    int (*auxprop_lookup)(void *glob_context,
			   sasl_server_params_t *sparams,
			   unsigned flags,
			   const char *user, unsigned ulen);

    /* name of the auxprop plugin */
    char *name;

    /* store the fields/values of an auxiliary property context (OPTIONAL)
     *
     * if ctx is NULL, just check if storing properties is enabled
     *
     * returns
     *  SASL_OK         on success
     *  SASL_FAIL       on failure
     */
    int (*auxprop_store)(void *glob_context,
			 sasl_server_params_t *sparams,
			 struct propctx *ctx,
			 const char *user, unsigned ulen);
} sasl_auxprop_plug_t;

/* auxprop lookup flags */
#define SASL_AUXPROP_OVERRIDE 0x01 /* if clear, ignore auxiliary properties
				    * with non-zero len field.  If set,
				    * override value of those properties */
#define SASL_AUXPROP_AUTHZID  0x02 /* if clear, we are looking up the
				    * authid flags (prefixed with *), otherwise
				    * we are looking up the authzid flags
				    * (no prefix) */

/* NOTE: Keep in sync with SASL_CU_<XXX> flags */
#define SASL_AUXPROP_VERIFY_AGAINST_HASH 0x10


#define SASL_AUXPROP_PLUG_VERSION 8

/* default name for auxprop plug-in entry point is "sasl_auxprop_init"
 *  similar to sasl_server_plug_init model, except only returns one
 *  sasl_auxprop_plug_t structure;
 */
typedef int sasl_auxprop_init_t(const sasl_utils_t *utils,
				int max_version,
				int *out_version,
				sasl_auxprop_plug_t **plug,
				const char *plugname);

/* add an auxiliary property plug-in
 */
LIBSASL_API int sasl_auxprop_add_plugin(const char *plugname,
					sasl_auxprop_init_t *auxpropfunc);

typedef void auxprop_info_callback_t (sasl_auxprop_plug_t *m,
			              sasl_info_callback_stage_t stage,
				      void *rock);

/* Dump information about available auxprop plugins (separate functions are
   used for canon and server authentication plugins) */
LIBSASL_API int auxprop_plugin_info (const char *mech_list,
	auxprop_info_callback_t *info_cb,
	void *info_cb_rock);

#ifdef __cplusplus
}
#endif

#endif /* SASLPLUG_H */