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