SASL Authentication

Authentication takes a variable number of client and server steps depending on the security mechanism that is used. The SASL client calls sasl_client_start() with a list of security mechanisms to use. This list typically comes from the server. libsasl selects the best mechanism to use for this SASL session, according to the available mechanisms and the client's security policy. The client's security policy controls which mechanisms are permitted. The selected mechanism is returned by sasl_client_start(). Sometimes the security mechanism for the client sometimes needs additional information for authentication. For registered callbacks, libsasl calls the specified callback unless the callback function is NULL. If the callback function is NULL, libsasl returns SASL_INTERACT and a request for needed information. If SASL_INTERACT is returned, then sasl_client_start() should be called with the requested information.

If sasl_client_start() returns SASL_CONTINUE or SASL_OK, the client should send the selected mechanism with any resulting authentication data to the server. If any other value is returned, an error has occurred. For example, no mechanism might be available.

The server receives the mechanism that has been selected by the client, along with any authentication data. The server then calls sasl_server_start() to initialize the mechanism data for this session. sasl_server_start() also processes any authentication data. If sasl_server_start() returns SASL_CONTINUE or SASL_OK, the server sends authentication data. If sasl_server_start() returns any other value, an error has occurred such as an unacceptable mechanism or an authentication failure. The authentication must be aborted. The SASL context should be either freed or reused.

This part of the authentication process is illustrated in the following diagram.

Figure 7–4 SASL Authentication: Sending Client Data

If the server call to sasl_server_start() returns SASL_CONTINUE, the server continues to communicate with the client to get all the necessary authentication information. The number of subsequent steps depends on the mechanism. If needed, the client calls sasl_client_step() to process the authentication data from the server and to generate a reply. Similarly, the server can call sasl_server_step() to process the authentication from the client and to generate a reply in turn. This exchange continues until the authentication is complete or until an error has occurred. SASL_OK is returned to indicate that the authentication has successfully completed for the client or server. The SASL mechanism might still have additional data to send to the other side so the other side can complete authentication. When authentication has been achieved on both sides, the server and client can inquire about each other's properties.

The following diagram shows the interactions between the server and client to transfer the additional authentication data.

Figure 7–5 SASL Authentication: Processing Server Data