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