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