The following tables provide brief descriptions of some SASL interfaces.
Table E–1 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 E–2 Basic SASL Client–only Functions
Function |
Description |
---|---|
sasl_client_init |
Called once initially to load and initialize client plug-ins. |
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 E–3 Basic SASL Server Functions (Clients Optional)
Function |
Description |
---|---|
sasl_server_init |
Called once initially to load and initialize server plug-ins. |
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 E–4 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 plug-in. |
sasl_server_add_plugin |
Add a server plug-in. |
sasl_canonuser_add_plugin |
Add a user canonicalization plug-in. |
sasl_auxprop_add_plugin |
Add an auxiliary property plug-in. |
Table E–5 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 E–6 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 E–7 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 E–8 SASL Include Files
Include File |
Comments |
---|---|
sasl/saslplug.h | |
sasl/sasl.h |
Needed for developing plug-ins |
sasl/saslutil.h | |
sasl/prop.h |
Table E–9 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 E–10 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 E–11 SASL Return Codes: Server-Only
Function |
Description |
---|---|
SASL_BADAUTH |
Authentication failure |
SASL_BADVERS |
Version mismatch with plug-in |
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 E–12 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 |