sasl.h revision 2
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * *******************************IMPORTANT******************************
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * send email to chris.newman@sun.com and cyrus-bugs@andrew.cmu.edu *
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * if you need to add new error codes, callback types, property values, *
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * etc. It is important to keep the multiple implementations of this *
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * API from diverging. *
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * *******************************IMPORTANT******************************
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Basic Type Summary:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_conn_t Context for a SASL connection negotiation
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_ssf_t Security layer Strength Factor
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_callback_t A typed client/server callback function and context
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_interact_t A client interaction descriptor
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_secret_t A client password
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_rand_t Random data context structure
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_security_properties_t An application's required security level
1b7fc709228029b3f29f1c3de6d817a476f7c583tim szeto * Callbacks:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_getopt_t client/server: Get an option value
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_canon_user_t client/server: Canonicalize username
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_log_t client/server: Log message handler
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_verifyfile_t client/server: Verify file for specified usage
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_getpath_t client/server: Get sasl search path
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Client only Callbacks:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_getrealm_t client: Get available realms
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_getsimple_t client: Get user/language list
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_getsecret_t client: Get authentication secret
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_chalprompt_t client: Display challenge and prompt for response
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Server only Callbacks:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_authorize_t user authorization policy callback
e17f3b2227c590f1d761b9ec4613cfb05982e6abtim szeto * sasl_server_userdb_checkpass_t check password and auxprops in userdb
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sasl_server_userdb_setpass_t set password in userdb
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Client/Server Function Summary:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_done Release all SASL global state
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_dispose Connection done: Dispose of sasl_conn_t
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_getprop Get property (e.g., user name, security layer info)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_setprop Set property (e.g., external ssf)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sasl_errdetail Generate string from last error on connection
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_errstring Translate sasl error code to a string
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_encode Encode data to send using security layer
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sasl_decode Decode data received using security layer
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Utility functions:
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sasl_encode64 Encode data to send using MIME base64 encoding
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sasl_decode64 Decode data received using MIME base64 encoding
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sasl_erasebuffer Erase a buffer
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Client Function Summary:
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sasl_client_init Load and initialize client plug-ins (call once)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sasl_client_new Initialize client connection context: sasl_conn_t
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sasl_client_start Select mechanism for connection
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sasl_client_step Perform one authentication step
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Server Function Summary
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sasl_server_init Load and initialize server plug-ins (call once)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sasl_server_new Initialize server connection context: sasl_conn_t
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sasl_listmech Create list of available mechanisms
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sasl_server_start Begin an authentication exchange
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sasl_server_step Perform one authentication exchange step
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sasl_checkpass Check a plaintext passphrase
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sasl_checkapop Check an APOP challenge/response (uses pseudo "APOP"
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * mechanism similar to CRAM-MD5 mechanism; optional)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sasl_user_exists Check if user exists
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sasl_setpass Change a password or add a user entry
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sasl_auxprop_request Request auxiliary properties
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sasl_auxprop_getctx Get auxiliary property context for connection
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Basic client model:
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * 1. client calls sasl_client_init() at startup to load plug-ins
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * 2. when connection formed, call sasl_client_new()
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * 3. once list of supported mechanisms received from server, client
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * calls sasl_client_start(). goto 4a
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * 4. client calls sasl_client_step()
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * [4a. If SASL_INTERACT, fill in prompts and goto 4
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * -- doesn't happen if callbacks provided]
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * 4b. If SASL error, goto 7 or 3
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * 4c. If SASL_OK, continue or goto 6 if last server response was success
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * 5. send message to server, wait for response
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * 5a. On data or success with server response, goto 4
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * 5b. On failure goto 7 or 3
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * 5c. On success with no server response continue
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * 6. continue with application protocol until connection closes
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * call sasl_getprop/sasl_encode/sasl_decode() if using security layer
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * 7. call sasl_dispose(), may return to step 2
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * 8. call sasl_done() when program terminates
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Basic Server model:
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * 1. call sasl_server_init() at startup to load plug-ins
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * 2. On connection, call sasl_server_new()
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * 3. call sasl_listmech() and send list to client]
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * 4. after client AUTH command, call sasl_server_start(), goto 5a
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * 5. call sasl_server_step()
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * 5a. If SASL_CONTINUE, output to client, wait response, repeat 5
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * 5b. If SASL error, then goto 7
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * 5c. If SASL_OK, move on
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * 6. continue with application protocol until connection closes
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * call sasl_getprop to get username
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * call sasl_getprop/sasl_encode/sasl_decode() if using security layer
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * 7. call sasl_dispose(), may return to step 2
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * 8. call sasl_done() when program terminates
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * ***********************************************
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * IMPORTANT NOTE: server realms / username syntax
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * If a user name contains a "@", then the rightmost "@" in the user name
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * separates the account name from the realm in which this account is
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * located. A single server may support multiple realms. If the
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * server knows the realm at connection creation time (e.g., a server
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * with multiple IP addresses tightly binds one address to a specific
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * realm) then that realm must be passed in the user_realm field of
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * the sasl_server_new call. If user_realm is non-empty and an
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * unqualified user name is supplied, then the canon_user facility is
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * expected to append "@" and user_realm to the user name. The canon_user
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * facility may treat other characters such as "%" as equivalent to "@".
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * If the server forbids the use of "@" in user names for other
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * purposes, this simplifies security validation.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * The following ifdef block is the standard way of creating macros
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * which make exporting from a DLL simpler. All files within this DLL
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * are compiled with the LIBSASL_EXPORTS symbol defined on the command
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * line. this symbol should not be defined on any project that uses
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * this DLL. This way any other project whose source files include
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * this file see LIBSASL_API functions as being imported from a DLL,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * wheras this DLL sees symbols defined with this macro as being
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Under Unix, life is simpler: we just need to mark library functions
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * as extern. (Technically, we don't even have to do that.)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#else /* LIBSASL_EXPORTS */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#endif /* LIBSASL_EXPORTS */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#else /* WIN32 */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#endif /* WIN32 */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Same as above, but used during a variable declaration. Only Unix definition
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * is different, as we can't assign an initial value to an extern variable
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#else /* LIBSASL_EXPORTS */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#endif /* LIBSASL_EXPORTS */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#else /* WIN32 */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#endif /* WIN32 */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte/* SASL result codes: */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_CONTINUE 1 /* another step is needed in authentication */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_NOMEM -2 /* memory shortage failure */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_NOMECH -4 /* mechanism not supported */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_BADPROT -5 /* bad protocol / cancel */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_NOTDONE -6 /* can't request info until later in exchange */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_BADPARAM -7 /* invalid parameter supplied */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_TRYAGAIN -8 /* transient failure (e.g., weak key) */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_BADMAC -9 /* integrity check failed */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_NOTINIT -12 /* SASL library not initialized */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte/* -- client only codes -- */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_INTERACT 2 /* needs user interaction */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_BADSERV -10 /* server failed mutual authentication step */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_WRONGMECH -11 /* mechanism doesn't support requested feature */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte/* -- server only codes -- */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_BADAUTH -13 /* authentication failure */
2a8164df8a5f42c8a00f10c67d7bc84f80ae9c41Zhong Wang#define SASL_NOAUTHZ -14 /* authorization failure */
2a8164df8a5f42c8a00f10c67d7bc84f80ae9c41Zhong Wang#define SASL_TOOWEAK -15 /* mechanism too weak for this user */
2a8164df8a5f42c8a00f10c67d7bc84f80ae9c41Zhong Wang#define SASL_ENCRYPT -16 /* encryption needed to use mechanism */
2a8164df8a5f42c8a00f10c67d7bc84f80ae9c41Zhong Wang#define SASL_TRANS -17 /* One time use of a plaintext password will */
2a8164df8a5f42c8a00f10c67d7bc84f80ae9c41Zhong Wang /* enable requested mechanism for user */
2a8164df8a5f42c8a00f10c67d7bc84f80ae9c41Zhong Wang#define SASL_EXPIRED -18 /* passphrase expired, has to be reset */
2a8164df8a5f42c8a00f10c67d7bc84f80ae9c41Zhong Wang#define SASL_BADVERS -23 /* version mismatch with plug-in */
2a8164df8a5f42c8a00f10c67d7bc84f80ae9c41Zhong Wang#define SASL_UNAVAIL -24 /* remote authentication server unavailable */
2a8164df8a5f42c8a00f10c67d7bc84f80ae9c41Zhong Wang#define SASL_NOVERIFY -26 /* user exists, but no verifier for user */
2a8164df8a5f42c8a00f10c67d7bc84f80ae9c41Zhong Wang/* -- codes for password setting -- */
2a8164df8a5f42c8a00f10c67d7bc84f80ae9c41Zhong Wang#define SASL_NOCHANGE -22 /* requested change was not needed */
2a8164df8a5f42c8a00f10c67d7bc84f80ae9c41Zhong Wang#define SASL_WEAKPASS -27 /* passphrase is too weak for security policy */
2a8164df8a5f42c8a00f10c67d7bc84f80ae9c41Zhong Wang#define SASL_NOUSERPASS -28 /* user supplied passwords not permitted */
2a8164df8a5f42c8a00f10c67d7bc84f80ae9c41Zhong Wang/* max size of a sasl mechanism name */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte/* Define to have the same layout as a WSABUF */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte/* per-connection SASL negotiation state for client or server */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Plain text password structure.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * len is the length of the password, data is the text.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortetypedef struct sasl_secret {
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte unsigned long len;
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte/* random data context structure */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Configure Basic Services
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * the following functions are used to adjust how allocation and mutexes work
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * they must be called before all other SASL functions:
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/* The following function is obsolete */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * memory allocation functions which may optionally be replaced:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortetypedef void *sasl_malloc_t(unsigned long);
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortetypedef void *sasl_calloc_t(unsigned long, unsigned long);
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortetypedef void *sasl_realloc_t(void *, unsigned long);
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortetypedef void sasl_free_t(void *);
1b7fc709228029b3f29f1c3de6d817a476f7c583tim szeto/* The following function is obsolete */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * mutex functions which may optionally be replaced:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_mutex_alloc allocates a mutex structure
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_mutex_lock blocks until mutex locked
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * returns -1 on deadlock or parameter error
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * returns 0 on success
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_mutex_unlock unlocks mutex if it's locked
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * returns -1 if not locked or parameter error
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * returns 0 on success
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * sasl_mutex_free frees a mutex structure
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortetypedef void *sasl_mutex_alloc_t(void);
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteLIBSASL_API void sasl_set_mutex(sasl_mutex_alloc_t *, sasl_mutex_lock_t *,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Security preference types
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * security layer strength factor -- an unsigned integer usable by the caller
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * to specify approximate security layer strength desired. Roughly
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * correlated to effective key length for encryption.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * 0 = no protection
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * 1 = integrity protection only
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * 40 = 40-bit DES or 40-bit RC2/RC4
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * 112 = triple-DES
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * 128 = 128-bit RC2/RC4/BLOWFISH
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * 256 = baseline AES
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortetypedef unsigned sasl_ssf_t;
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte/* usage flags provided to sasl_server_new and sasl_client_new: */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_SUCCESS_DATA 0x0004 /* server supports data on success */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_NEED_PROXY 0x0008 /* require a mech that allows proxying */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Security Property Types
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Structure specifying the client or server's security policy
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * and optional additional properties.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte/* These are the various security flags apps can specify. */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * NOPLAINTEXT -- don't permit mechanisms susceptible to simple
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * passive attack (e.g., PLAIN, LOGIN)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * NOACTIVE -- protection from active (non-dictionary) attacks
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * during authentication exchange.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Authenticates server.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * NODICTIONARY -- don't permit mechanisms susceptible to passive
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * dictionary attack
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * FORWARD_SECRECY -- require forward secrecy between sessions
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * (breaking one won't help break next)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * NOANONYMOUS -- don't permit mechanisms that allow anonymous login
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * PASS_CREDENTIALS -- require mechanisms which pass client
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * credentials, and allow mechanisms which can pass
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * credentials to do so
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * MUTUAL_AUTH -- require mechanisms which provide mutual
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * authentication
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * security strength factor
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * min_ssf = minimum acceptable final level
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * max_ssf = maximum acceptable final level
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Maximum security layer receive buffer size.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * 0=security layer not supported
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte/* bitfield for attacks to protect against */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte/* NULL terminated array of additional property names, values */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Callback types
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Extensible type for a client/server callbacks
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * id -- identifies callback type
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * proc -- procedure call arguments vary based on id
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * context -- context passed to procedure
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Note that any memory that is allocated by the callback needs to be
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * freed by the application, be it via function call or interaction.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * It may be freed after sasl_*_step returns SASL_OK. if the mechanism
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * requires this information to persist (for a security layer, for example)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * it must maintain a private copy.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortetypedef struct sasl_callback {
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Identifies the type of the callback function.
1b7fc709228029b3f29f1c3de6d817a476f7c583tim szeto * Mechanisms must ignore callbacks with id's they don't recognize.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte unsigned long id;
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto int (*proc)(); /* Callback function. Types of arguments vary by 'id' */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * callback ids & functions:
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * option reading callback -- this allows a SASL configuration to be
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * encapsulated in the caller's configuration system. Some implementations
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * may use default config file(s) if this is omitted. Configuration items
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * may be plugin-specific and are arbitrary strings.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * context -- option context from callback record
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * plugin_name -- name of plugin (NULL = general SASL option)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * option -- name of option
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * result -- set to result which persists until next getopt in
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * same thread, unchanged if option not found
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * len -- length of result (may be NULL)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_OK -- no error
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_FAIL -- error
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortetypedef int sasl_getopt_t(void *context, const char *plugin_name,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte const char *option,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte/* Logging levels for use with the logging callback function. */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_LOG_ERR 1 /* log unusual errors (default) */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_LOG_FAIL 2 /* log all authentication failures */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_LOG_WARN 3 /* log non-fatal warnings */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_LOG_NOTE 4 /* more verbose than LOG_WARN */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_LOG_DEBUG 5 /* more verbose than LOG_NOTE */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_LOG_TRACE 6 /* traces of internal protocols */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_LOG_PASS 7 /* traces of internal protocols, including */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte /* passwords */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * logging callback -- this allows plugins and the middleware to
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * log operations they perform.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * context -- logging context from the callback record
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * level -- logging level; see above
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * message -- message to log
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_OK -- no error
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_FAIL -- error
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte const char *message);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * getpath callback -- this allows applications to specify the
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * colon-separated path to search for plugins (by default,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * taken from an implementation-specific location).
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * context -- getpath context from the callback record
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * path -- colon separated path
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_OK -- no error
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_FAIL -- error
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte const char **path);
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte/* Callback to get the location of the sasl config */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * verify file callback -- this allows applications to check if they
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * want SASL to use files, file by file. This is intended to allow
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * applications to sanity check the environment to make sure plugins
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * or the configuration file can't be written to, etc.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * context -- verifypath context from the callback record
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * file -- full path to file to verify
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * type -- type of file to verify (see below)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_OK -- no error (file can safely be used)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_CONTINUE -- continue WITHOUT using this file
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_FAIL -- error
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte/* these are the types of files libsasl will ask about */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortetypedef enum {
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte SASL_VRFY_PLUGIN = 0, /* a DLL/shared library plug-in */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte SASL_VRFY_PASSWD = 2, /* a password storage file/db */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte/* client/user interaction callbacks: */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Simple prompt -- result must persist until next call to getsimple on
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * same connection or until connection context is disposed
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * context -- context from callback structure
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * id -- callback id
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * result -- set to NUL terminated string
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * NULL = user cancel
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * len -- length of result
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * returns SASL_OK
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortetypedef int sasl_getsimple_t(void *context, int id,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_CB_USER 0x4001 /* client user identity to login as */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_CB_AUTHNAME 0x4002 /* client authentication name */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * comma separated list of RFC 1766
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * language codes in order of preference
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * to be used to localize client prompts
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * or server error codes
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte /* caller supplies client-nonce primarily for testing purposes */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * get a sasl_secret_t (plaintext password with length)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * conn -- connection context
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * context -- context from callback structure
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * id -- callback id
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * psecret -- set to NULL to cancel
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * set to password structure which must persist until
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * next call to getsecret in same connection, but middleware
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * will erase password data when it's done with it.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * returns SASL_OK
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortetypedef int sasl_getsecret_t(sasl_conn_t *conn, void *context, int id,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_CB_PASS 0x4004 /* client passphrase-based secret */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * prompt for input in response to a challenge.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * context -- context from callback structure
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * id -- callback id
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * challenge -- server challenge
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * result -- NUL terminated result, NULL = user cancel
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * len -- length of result
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * returns SASL_OK
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortetypedef int sasl_chalprompt_t(void *context, int id,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_CB_ECHOPROMPT 0x4005 /* challenge and client enterred result */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_CB_NOECHOPROMPT 0x4006 /* challenge and client enterred result */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * prompt (or autoselect) the realm to do authentication in.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * may get a list of valid realms.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * context -- context from callback structure
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * id -- callback id
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * availrealms -- available realms; string list; NULL terminated
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * list may be empty.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * result -- NUL terminated realm; NULL is equivalent to ""
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * returns SASL_OK
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * result must persist until the next callback
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortetypedef int sasl_getrealm_t(void *context, int id,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte const char **result);
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_CB_GETREALM (0x4008) /* realm to attempt authentication in */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte/* server callbacks: */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * improved callback to verify authorization;
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * canonicalization now handled elsewhere
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * conn -- connection context
1b7fc709228029b3f29f1c3de6d817a476f7c583tim szeto * requested_user -- the identity/username to authorize (NUL terminated)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * rlen -- length of requested_user
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * auth_identity -- the identity associated with the secret (NUL terminated)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * alen -- length of auth_identity
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * default_realm -- default user realm, as passed to sasl_server_new if
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * urlen -- length of default realm
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * propctx -- auxiliary properties
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * returns SASL_OK on success,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_NOAUTHZ or other SASL response on failure
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * functions for "userdb" based plugins to call to get/set passwords.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * the location for the passwords is determined by the caller or middleware.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * plug-ins may get passwords from other locations.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * callback to verify a plaintext password against the caller-supplied
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * user database. This is necessary to allow additional <method>s for
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * encoding of the userPassword property.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * user -- NUL terminated user name with user@realm syntax
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * pass -- password to check (may not be NUL terminated)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * passlen -- length of password to check
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * propctx -- auxiliary properties for user
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Fortetypedef int sasl_server_userdb_checkpass_t(sasl_conn_t *conn,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte const char *user,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte const char *pass,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * callback to store/change a plaintext password in the user database
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * user -- NUL terminated user name with user@realm syntax
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * pass -- password to store (may not be NUL terminated)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * passlen -- length of password to store
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * propctx -- auxiliary properties (not stored)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * flags -- see SASL_SET_* flags below (SASL_SET_CREATE optional)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetotypedef int sasl_server_userdb_setpass_t(sasl_conn_t *conn,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto const char *user,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto const char *pass,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * callback for a server-supplied user canonicalization function.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * This function is called directly after the mechanism has the
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * authentication and authorization IDs. It is called before any
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * User Canonicalization plugin is called. It has the responsibility
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * of copying its output into the provided output buffers.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * in, inlen -- user name to canonicalize, may not be NUL terminated
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * may be same buffer as out
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * flags -- not currently used, supplied by auth mechanism
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * user_realm -- the user realm (may be NULL in case of client)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * out -- buffer to copy user name
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * out_max -- max length of user name
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * out_len -- set to length of user name
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_OK on success
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_BADPROT username contains invalid character
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/* User Canonicalization Function Flags */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_CU_NONE 0x00 /* Not a valid flag to pass */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/* One of the following two is required */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Common Client/server functions
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * get sasl library version information
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * implementation is a vendor-defined string
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * version is a vender-defined representation of the version #
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoLIBSASL_API void sasl_version(const char **implementation,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * dispose of all SASL plugins. Connection
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * states have to be disposed of before calling this.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * dispose connection state, sets it to NULL
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * checks for pointer to NULL
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoLIBSASL_API void sasl_dispose(sasl_conn_t **pconn);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * translate an error number into a string
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * saslerr -- the error number
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * langlist -- comma separated list of RFC 1766 languages (may be NULL)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * outlang -- the language actually used (may be NULL if don't care)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * the error message in UTF-8 (only the US-ASCII subset if langlist is NULL)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoLIBSASL_API const char *sasl_errstring(int saslerr,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto const char **outlang);
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * get detail about the last error that occurred on a connection
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * text is sanitized so it's suitable to send over the wire
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * (e.g., no distinction between SASL_BADAUTH and SASL_NOUSER)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * conn -- mandatory connection context
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * the error message in UTF-8 (only the US-ASCII subset permitted if no
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_CB_LANGUAGE callback is present)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteLIBSASL_API const char *sasl_errdetail(sasl_conn_t *conn);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * set the error string which will be returned by sasl_errdetail() using
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * syslog()-style formatting (e.g. printf-style with %m as most recent
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * errno error)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * primarily for use by server callbacks such as the sasl_authorize_t
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * callback and internally to plug-ins
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * This will also trigger a call to the SASL logging callback (if any)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * with a level of SASL_LOG_FAIL unless the SASL_NOLOG flag is set.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Messages should be sensitive to the current language setting. If there
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * is no SASL_CB_LANGUAGE callback messages MUST be US-ASCII otherwise UTF-8
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * is used and use of RFC 2482 for mixed-language text is encouraged.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * if conn is NULL, function does nothing
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoLIBSASL_API void sasl_seterror(sasl_conn_t *conn, unsigned flags,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte const char *fmt, ...);
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * get property from SASL connection state
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * propnum -- property number
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * pvalue -- pointer to value
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_OK -- no error
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_NOTDONE -- property not available yet
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_BADPARAM -- bad property number
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoLIBSASL_API int sasl_getprop(sasl_conn_t *conn, int propnum,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto const void **pvalue);
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_USERNAME 0 /* pointer to NUL terminated user name */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_SSF 1 /* security layer security strength factor, */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto /* if 0, call to sasl_encode, sasl_decode */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte /* unnecessary */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_MAXOUTBUF 2 /* security layer max output buf unsigned */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#define SASL_DEFUSERREALM 3 /* default realm passed to server_new */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto /* or set with setprop */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_GETOPTCTX 4 /* context for getopt callback */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_CALLBACK 7 /* current callback function list */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_IPLOCALPORT 8 /* iplocalport string passed to server_new */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_IPREMOTEPORT 9 /* ipremoteport string passed to server_new */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_SERVICE 12 /* service passed to sasl_*_new */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_SERVERFQDN 13 /* serverFQDN passed to sasl_*_new */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_AUTHSOURCE 14 /* name of auth source last used, useful */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto /* for failed authentication tracking */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_MECHNAME 15 /* active mechanism name, if any */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_AUTHUSER 16 /* authentication/admin user */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * This returns a string which is either empty or has an error message
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * from sasl_seterror (e.g., from a plug-in or callback). It differs
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * from the result of sasl_errdetail() which also takes into account the
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * last return status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * set property in SASL connection state
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_OK -- value set
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_BADPARAM -- invalid property or value
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto const void *value);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_SSF_EXTERNAL 100 /* external SSF active (sasl_ssf_t *) */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_SEC_PROPS 101 /* sasl_security_properties_t */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_AUTH_EXTERNAL 102 /* external authentication ID (const char *) */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * If the SASL_AUTH_EXTERNAL value is non-NULL, then a special version of the
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * EXTERNAL mechanism is enabled (one for server-embedded EXTERNAL mechanisms).
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Otherwise, the EXTERNAL mechanism will be absent unless a plug-in
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * including EXTERNAL is present.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * do precalculations during an idle period or network round trip
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * may pass NULL to precompute for some mechanisms prior to connect
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * returns 1 if action taken, 0 if no action taken
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Client API
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * list of client interactions with user for caller to fill in
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetotypedef struct sasl_interact {
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto unsigned long id; /* same as client/user callback ID */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto const char *challenge; /* presented to user (e.g. OTP challenge) */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto const char *prompt; /* presented to user (e.g. "Username: ") */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto const char *defresult; /* default result string */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * initialize the SASL client drivers
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * callbacks -- base callbacks for all client connections;
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * must include getopt callback
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_OK -- Success
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_NOMEM -- Not enough memory
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_BADVERS -- Mechanism version mismatch
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_BADPARAM -- missing getopt callback or error in config file
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_NOMECH -- No mechanisms available
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoLIBSASL_API int sasl_client_init(const sasl_callback_t *callbacks);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * initialize a client exchange based on the specified mechanism
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * service -- registered name of the service using SASL (e.g. "imap")
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * serverFQDN -- the fully qualified domain name of the server
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * iplocalport -- client IPv4/IPv6 domain literal string with port
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * (if NULL, then mechanisms requiring IPaddr are disabled)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * ipremoteport -- server IPv4/IPv6 domain literal string with port
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * (if NULL, then mechanisms requiring IPaddr are disabled)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * prompt_supp -- list of client interactions supported
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * may also include sasl_getopt_t context & call
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * NULL prompt_supp = user/pass via SASL_INTERACT only
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * NULL proc = interaction supported via SASL_INTERACT
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * flags -- server usage flags (see above)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * pconn -- sasl connection
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_OK -- success
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_NOMECH -- no mechanism meets requested properties
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_NOMEM -- not enough memory
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoLIBSASL_API int sasl_client_new(const char *service,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * select a mechanism for a connection
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * mechlist -- list of mechanisms to use (punctuation ignored)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * prompt_need -- on SASL_INTERACT, list of prompts needed to continue
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * may be NULL if callbacks provided
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * clientout -- the initial client response to send to the server
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * will be valid until next call to client_start/client_step
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * NULL if mech doesn't include initial client challenge
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * mech -- set to mechansm name of selected mechanism (may be NULL)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_OK -- success
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_NOMEM -- not enough memory
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_NOMECH -- no mechanism meets requested properties
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_INTERACT -- user interaction needed to fill in prompt_need list
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoLIBSASL_API int sasl_client_start(sasl_conn_t *conn,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte const char **clientout,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto const char **mech);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * do a single authentication step.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * serverin -- the server message received by the client, MUST have a NUL
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sentinel, not counted by serverinlen
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * prompt_need -- on SASL_INTERACT, list of prompts needed to continue
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * clientout -- the client response to send to the server
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * will be valid until next call to client_start/client_step
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_OK -- success
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_INTERACT -- user interaction needed to fill in prompt_need list
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_BADPROT -- server protocol incorrect/cancelled
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_BADSERV -- server failed mutual auth
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteLIBSASL_API int sasl_client_step(sasl_conn_t *conn,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto const char **clientout,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Server API
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * initialize server drivers, done once per process
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * callbacks -- callbacks for all server connections; must include
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * getopt callback
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * appname -- name of calling application (for lower level logging)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * state -- server state
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_OK -- success
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_BADPARAM -- error in config file
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_NOMEM -- memory failure
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_BADVERS -- Mechanism version mismatch
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoLIBSASL_API int sasl_server_init(const sasl_callback_t *callbacks,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto const char *appname);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * a.b.c.d:p where a-d are 0-255 and p is 0-65535 port number.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * [e:f:g:h:i:j:k:l]:p where e-l are 0000-ffff lower-case hexidecimal
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * [e:f:g:h:i:j:a.b.c.d]:p alternate syntax for previous
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Note that one or more "0" fields in f-k can be replaced with "::"
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Thus: [e:f:0000:0000:0000:j:k:l]:p
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * can be abbreviated: [e:f::j:k:l]:p
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * A buffer of size 52 is adequate for the longest format with NUL terminator.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * create context for a single SASL connection
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * service -- registered name of the service using SASL (e.g. "imap")
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * serverFQDN -- Fully qualified domain name of server. NULL means use
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * gethostname() or equivalent.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Useful for multi-homed servers.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * user_realm -- permits multiple user realms on server, NULL = default
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * iplocalport -- server IPv4/IPv6 domain literal string with port
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * (if NULL, then mechanisms requiring IPaddr are disabled)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * ipremoteport -- client IPv4/IPv6 domain literal string with port
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * (if NULL, then mechanisms requiring IPaddr are disabled)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * callbacks -- callbacks (e.g., authorization, lang, new getopt context)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * flags -- usage flags (see above)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * pconn -- new connection context
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_OK -- success
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_NOMEM -- not enough memory
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteLIBSASL_API int sasl_server_new(const char *service,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/* The following function is obsolete */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Return an array of NUL-terminated strings, terminated by a NULL pointer,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * which lists all possible mechanisms that the library can supply
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Returns NULL on failure.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoLIBSASL_API const char ** sasl_global_listmech(void);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * This returns a list of mechanisms in a NUL-terminated string
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * conn -- the connection to list mechanisms for (either client
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * or server)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * user -- restricts mechanisms to those available to that user
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * (may be NULL, not used for client case)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * prefix -- appended to beginning of result
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * sep -- appended between mechanisms
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * suffix -- appended to end of result
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * result -- NUL terminated result which persists until next
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * call to sasl_listmech for this sasl_conn_t
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * plen -- gets length of result (excluding NUL), may be NULL
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * pcount -- gets number of mechanisms, may be NULL
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_OK -- success
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_NOMEM -- not enough memory
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_NOMECH -- no enabled mechanisms
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto const char *user,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto const char *prefix,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto const char *sep,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto const char *suffix,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte const char **result,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * start a mechanism exchange within a connection context
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * mech -- the mechanism name client requested
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * clientin -- client initial response (NUL terminated), NULL if empty
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * clientinlen -- length of initial response
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * serverout -- initial server challenge, NULL if done
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * (library handles freeing this string)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * serveroutlen -- length of initial server challenge
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * pconn -- the connection negotiation state on success
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Same returns as sasl_server_step() or
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_NOMECH if mechanism not available.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteLIBSASL_API int sasl_server_start(sasl_conn_t *conn,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto const char *mech,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto const char **serverout,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * perform one step of the SASL exchange
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * inputlen & input -- client data
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * NULL on first step if no optional client step
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * outputlen & output -- set to the server data to transmit
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * to the client in the next step
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * (library handles freeing this)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_OK -- exchange is complete.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_CONTINUE -- indicates another step is necessary.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_TRANS -- entry for user exists, but not for mechanism
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * and transition is possible
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_BADPARAM -- service name needed
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_BADPROT -- invalid input from client
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteLIBSASL_API int sasl_server_step(sasl_conn_t *conn,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte const char **serverout,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/* The following function is obsolete */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * check if an apop exchange is valid
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * (note this is an optional part of the SASL API)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * if challenge is NULL, just check if APOP is enabled
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * challenge -- challenge which was sent to client
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * challen -- length of challenge, 0 = strlen(challenge)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * response -- client response, "<user> <digest>" (RFC 1939)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * resplen -- length of response, 0 = strlen(response)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_OK -- success
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_BADAUTH -- authentication failed
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_BADPARAM -- missing challenge
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_BADPROT -- protocol error (e.g., response in wrong format)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_NOVERIFY -- user found, but no verifier
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_NOMECH -- mechanism not supported
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_NOUSER -- user not found
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * check if a plaintext password is valid
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * if user is NULL, check if plaintext passwords are enabled
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * user -- user to query in current user_domain
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * userlen -- length of username, 0 = strlen(user)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * pass -- plaintext password to check
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * passlen -- length of password, 0 = strlen(pass)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_OK -- success
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_NOMECH -- mechanism not supported
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_NOVERIFY -- user found, but no verifier
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_NOUSER -- user not found
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * check if a user exists on server
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * conn -- connection context
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * service -- registered name of the service using SASL (e.g. "imap")
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * user_realm -- permits multiple user realms on server, NULL = default
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * user -- NUL terminated user name
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_OK -- success
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_DISABLED -- account disabled
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_NOUSER -- user not found
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_NOVERIFY -- user found, but no usable mechanism
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_NOMECH -- no mechanisms enabled
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoLIBSASL_API int sasl_user_exists(sasl_conn_t *conn,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto const char *service,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto const char *user);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * set the password for a user
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * conn -- SASL connection
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * user -- user name
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * pass -- plaintext password, may be NULL to remove user
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * passlen -- length of password, 0 = strlen(pass)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * oldpass -- NULL will sometimes work
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * oldpasslen -- length of password, 0 = strlen(oldpass)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * flags -- see flags below
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_NOCHANGE -- proper entry already exists
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_NOMECH -- no authdb supports password setting as configured
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_NOVERIFY -- user exists, but no settable password present
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_DISABLED -- account disabled
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_PWLOCK -- password locked
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_WEAKPASS -- password too weak for security policy
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_NOUSERPASS -- user-supplied passwords not permitted
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_FAIL -- OS error
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_BADPARAM -- password too long
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_OK -- successful
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte const char *user,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_SET_CREATE 0x01 /* create a new entry for user */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_SET_REMOVE SASL_SET_CREATE /* remove user if pass is NULL */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_SET_DISABLE 0x02 /* disable user account */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Auxiliary Property Support -- added by cjn 1999-09-29
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_AUX_END NULL /* last auxiliary property */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/* traditional Posix items (should be implemented on Posix systems) */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_AUX_PASSWORD "*userPassword" /* User Password (of authid) */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_AUX_UIDNUM "uidNumber" /* UID number for the user */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_AUX_GIDNUM "gidNumber" /* GID for the user */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_AUX_FULLNAME "gecos" /* full name of the user, unix-style */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_AUX_HOMEDIR "homeDirectory" /* home directory for user */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define SASL_AUX_SHELL "loginShell" /* login shell for the user */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/* optional additional items (not necessarily implemented) */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * single preferred mail address for user canonically-quoted
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * RFC821/822 syntax
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte/* path to unix-style mailbox for user */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte/* SMTP mail channel name to use if user authenticates successfully */
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Request a set of auxiliary properties
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * conn connection context
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * propnames list of auxiliary property names to request ending with
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Subsequent calls will add items to the request list. Call with NULL
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * to clear the request list.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_OK -- success
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_BADPARAM -- bad count/conn parameter
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_NOMEM -- out of memory
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteLIBSASL_API int sasl_auxprop_request(sasl_conn_t *conn,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte const char **propnames);
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Returns current auxiliary property context.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * Use functions in prop.h to access content
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * if authentication hasn't completed, property values may be empty/NULL
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * properties not recognized by active plug-ins will be left empty/NULL
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * returns NULL if conn is invalid.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn ForteLIBSASL_API struct propctx *sasl_auxprop_getctx(sasl_conn_t *conn);
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * security layer API
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * encode a block of data for transmission using security layer,
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * returning the input buffer if there is no security layer.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * output is only valid until next call to sasl_encode or sasl_encodev
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_OK -- success (returns input if no layer negotiated)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_NOTDONE -- security layer negotiation not finished
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_BADPARAM -- inputlen is greater than the SASL_MAXOUTBUF
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * encode a block of data for transmission using security layer
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * output is only valid until next call to sasl_encode or sasl_encodev
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_OK -- success (returns input if no layer negotiated)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_NOTDONE -- security layer negotiation not finished
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * SASL_BADPARAM -- input length is greater than the SASL_MAXOUTBUF
e17f3b2227c590f1d761b9ec4613cfb05982e6abtim szeto * or no security layer
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * decode a block of data received using security layer
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * returning the input buffer if there is no security layer.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * output is only valid until next call to sasl_decode
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * if outputlen is 0 on return, than the value of output is undefined.
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_OK -- success (returns input if no layer negotiated)
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_NOTDONE -- security layer negotiation not finished
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte * SASL_BADMAC -- bad message integrity check
fcf3ce441efd61da9bb2884968af01cb7c1452ccJohn Forte#endif /* _SASL_SASL_H */