Developer's Guide to Oracle Solaris Security

Appendix E 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 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