Developer's Guide to Oracle^® Solaris 11.3 Security

SASL Reference Tables

This appendix provides reference information for SASL, which is an acronym for simple authentication and security layer.

SASL Interface Summaries

The following tables provide brief descriptions of some SASL interfaces.

Table 14  SASL Functions Common to Clients and Servers

Function Description sasl_version Get version information for the SASL library. sasl_done Release all SASL global state. sasl_dispose Dispose of sasl_conn_t when connection is done. sasl_getprop Get property, for example, user name, security layer info. sasl_setprop Set a SASL property. sasl_errdetail Generate string from last error on connection. sasl_errstring Translate SASL error code to a string. sasl_encode Encode data to send using security layer. sasl_encodev Encode a block of data for transmission through the security layer. Uses iovec * as the input parameter. sasl_listmech Create list of available mechanisms. sasl_global_listmech Return an array of all possible mechanisms. Note that this interface is obsolete. sasl_seterror Set the error string to be returned by sasl_errdetail(). sasl_idle Configure saslib to perform calculations during an idle period or during a network round trip. sasl_decode Decode data received using security layer.

Table 15  Basic SASL Client_only Functions

Function Description sasl_client_init Called once initially to load and initialize client plugins. sasl_client_new Initialize client connection. Sets up the sasl_conn_t context. sasl_client_start Select mechanism for connection. sasl_client_step Perform one authentication step.

Table 16  Basic SASL Server Functions (Clients Optional)

Function Description sasl_server_init Called once initially to load and initialize server plugins. sasl_server_new Initialize server connection. Sets up the sasl_conn_t context. sasl_server_start Begin an authentication exchange. sasl_server_step Perform one authentication exchange step. sasl_checkpass Check a plain text passphrase. sasl_checkapop Check an APOP challenge/response. Uses a pseudo APOP mechanism, which is similar to a CRAM-MD5 mechanism. Optional. Note that this interface is obsolete. sasl_user_exists Check whether user exists. sasl_setpass Change a password. Optionally, add a user entry. sasl_auxprop_request Request auxiliary properties. sasl_auxprop_getctx Get auxiliary property context for connection.

Table 17  SASL Functions for Configuring Basic Services

Function Description sasl_set_alloc Assign memory allocation functions. Note that this interface is obsolete. sasl_set_mutex Assign mutex functions. Note that this interface is obsolete. sasl_client_add_plugin Add a client plugin. sasl_server_add_plugin Add a server plugin. sasl_canonuser_add_plugin Add a user canonicalization plugin. sasl_auxprop_add_plugin Add an auxiliary property plugin.

Table 18  SASL Utility Functions

Function Description sasl_decode64 Use base64 to decode. sasl_encode64 Use base64 to encode. sasl_utf8verify Verify that a string is valid UTF-8. sasl_erasebuffer Erase a security-sensitive buffer or password. Implementation might use recovery-resistant erase logic.

Table 19  SASL Property Functions

Function Description prop_clear() Clear values and optionally requests from property context prop_dispose() Dispose of a property context prop_dup() Create new propctx which duplicates the contents of an existing propctx prop_erase() Erase the value of a property prop_format() Format the requested property names into a string prop_get() Return array of the propval structure from the context prop_getnames() Fill in an array of struct propval, given a list of property names prop_new() Create a property context prop_request() Add property names to a request prop_set() Add a property value to the context prop_setvals() Set the values for a property sasl_auxprop_getctx() Get auxiliary property context for connection sasl_auxprop_request() Request auxiliary properties

Table 20  Callback Data Types

Callback Description sasl_getopt_t Get an option value. Used by both clients and servers. sasl_log_t Log message handler. Used by both clients and servers. sasl_getpath_t Get path to search for mechanisms. Used by both clients and servers. sasl_verifyfile_t Verify files for use by SASL. Used by both clients and servers. sasl_canon_user_t User name canonicalization function. Used by both clients and servers. sasl_getsimple_t Get user and language list. Used by clients only. sasl_getsecret_t Get authentication secret. Used by clients only. sasl_chalprompt_t Display challenge and prompt for response. Used by clients only. sasl_getrealm_t Get the authentication realm. Used by clients only. sasl_authorize_t Authorize policy callback. Used by servers only. sasl_server_userdb_checkpass_t Verify plain text password. Used by servers only. sasl_server_userdb_setpass_t Set plain text password. Used by servers only.

Table 21  SASL Include Files

Include File Comments sasl/saslplug.h sasl/sasl.h Needed for developing plugins sasl/saslutil.h sasl/prop.h

Table 22  SASL Return Codes: General

Return Code Description SASL_BADMAC Integrity check failed SASL_BADVERS Mismatch between versions of a mechanism SASL_BADPARAM Invalid parameter supplied SASL_BADPROT Bad protocol, cancel operation SASL_BUFOVER Overflowed buffer SASL_CONTINUE Another step is needed in authentication SASL_FAIL Generic failure SASL_NOMECH Mechanism not supported SASL_NOMEM Insufficient memory to complete operation SASL_NOTDONE Cannot request information until later in exchange SASL_NOTINIT SASL library not initialized SASL_OK Successful result SASL_TRYAGAIN Transient failure, for example, a weak key

Table 23  SASL Return Codes: Client-Only

Function Description SASL_BADSERV Server failed mutual authentication step SASL_INTERACT Needs user interaction SASL_WRONGMECH Mechanism does not support requested feature

Table 24  SASL Return Codes: Server-Only

Function Description SASL_BADAUTH Authentication failure SASL_BADVERS Version mismatch with plugin SASL_DISABLED Account disabled SASL_ENCRYPT Encryption needed to use mechanism SASL_EXPIRED Passphrase expired and needs to be reset SASL_NOAUTHZ Authorization failure SASL_NOUSER User not found SASL_NOVERIFY User exists, but without verifier SASL_TOOWEAK Mechanism too weak for this user SASL_TRANS One-time use of a plain text password enables requested mechanism for user SASL_UNAVAIL Remote authentication server unavailable

Table 25  SASL Return Codes – Password Operations

Function Description SASL_NOCHANGE Requested change not needed SASL_NOUSERPASS User-supplied passwords not permitted SASL_PWLOCK Passphrase locked SASL_WEAKPASS Passphrase too weak for security policy