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