Chapter 12 Using SASL Authentication

SASL provides the means to use mechanisms other than simple authentication and SSL to authenticate to Sun™ Java System LDAP SDK for C. This chapter describes the process of using a Simple Authentication and Security Layer (SASL) mechanism to authenticate an LDAP client to an LDAP server. It includes the following sections:

Understanding SASL

Determining Supported SASL Mechanisms

To determine the SASL mechanisms supported by an LDAPv3 server, get the root DSE of the server, and check the supportedSASLMechanisms attribute. The values of this attribute are the names of the SASL mechanisms supported by the server.


Note	If the root DSE does not have a supportedSASLMechanisms attribute, the server does not support any SASL mechanisms.

Authenticating Using SASL

To authenticate to the server using a SASL mechanism, call one of the following:

Authentication using a SASL mechanism may take one or more round trips between your client and the server. (The server may send a number of challenges to the client.) You may need to call ldap_sasl_bind_s() several times (or ldap_sasl_bind(), ldap_result(), and ldap_parse_sasl_bind_result() several times) in order to respond to each server challenge.

Synchronous SASL Bind Operation


Note	Before calling the function to perform a SASL bind operation, make sure to specify that your client is LDAPv3 compliant. If you do not, an LDAP_NOT_SUPPORTED result code is returned. See "Specifying the LDAP Version of Your Client" in Chapter 3, "Writing an LDAP Client."

If you want to wait for the results of the SASL bind operation to complete before continuing, call the synchronous ldap_sasl_bind_s() function. This function sends a SASL bind request to the server and blocks other work until the server sends the results of the operation back to your client. ldap_sasl_bind_s() returns one of the following values:

Asynchronous SASL Bind Operation

If you want to perform other work (in parallel) while waiting for the SASL bind operation to complete, do the following:

Call the asynchronous ldap_sasl_bind() function to send an LDAP SASL bind request.

This function returns an LDAP_SUCCESS result code if the request was successfully sent (or an LDAP result code if an error occurred while sending the request). The function also sets the msgidp argument to point to a message ID identifying the SASL bind operation.

Call the ldap_result() function and pass in this message ID to determine whether the server sent a response for this operation to your client.

The ldap_result() function uses the message ID to determine if the server sent a SASL bind response. The function passes back the response in an LDAPMessage structure.

Call the ldap_parse_sasl_bind_result() function to parse the LDAPMessage structure and retrieve information from the server’s response.

If the server sent a challenge to your client, the challenge is specified in the berval structure passed back as the servercredp argument.

Call the ldap_get_lderrno() function to get the LDAP result code for the operation. The function can return one of the following values:

LDAP_SUCCESS if your client successfully authenticated to the server.

LDAP_SASL_BIND_IN_PROGRESS if the server sent a challenge to your client.

If the server returned an LDAP_SASL_BIND_IN_PROGRESS result code, check the servercredp argument for the berval structure containing the server’s challenge.

An LDAP error code, if a problem occurred or if authentication failed.

See the documentation on the return values of the ldap_sasl_bind_s() function for a list of result codes that the server can return for this operation.

If the result code is LDAP_SASL_BIND_IN_PROGRESS and the server passed back another challenge, determine the response to that challenge and call the ldap_sasl_bind() function again to send that response to the server.

You can call ldap_result() and ldap_parse_sasl_bind_result() again to get the next challenge sent from the server, if the result is LDAP_SASL_BIND_IN_PROGRESS again.

Code Example 12-1 is an LDAP client that authenticates using the SASL mechanism named babsmechanism.

Code Example 12-1 Authenticating over SASL


#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
#include "ldap.h"

int
main( int argc, char **argv )
{
LDAP *ld;
LDAPMod mod0;
LDAPMod mod1;
LDAPMod *mods[ 3 ];
char *vals0[ 2 ];
char *vals1[ 2 ];
time_t now;
char buf[ 128 ];
struct berval cred;
struct berval *servcred;
int version;
/* get a handle to an LDAP connection */
if ( (ld = ldap_init( "localhost", 389 )) == NULL ) {
perror( "ldap_init" );
return( 1 );
}
/* Set the LDAP protocol version supported by the client
to 3. (By default, this is set to 2. SASL authentication
is part of version 3 of the LDAP protocol.) */
version = LDAP_VERSION3;
ldap_set_option( ld, LDAP_OPT_PROTOCOL_VERSION, &version );
/* authenticate */
cred.bv_val = "magic";
cred.bv_len = sizeof( "magic" ) - 1;
if ( ldap_sasl_bind_s( ld, "uid=bjensen,ou=people,dc=example,dc=com", \
"babsmechanism", &cred, NULL, NULL, &servcred ) != LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_sasl_bind_s" );
return( 1 );
}
/* get and print the credentials returned by the server */
printf( "Server credentials: %s\n", servcred->bv_val );
/* construct the list of modifications to make */
mod0.mod_op = LDAP_MOD_REPLACE;
mod0.mod_type = "mail";
vals0[0] = "babs@example.com";
vals0[1] = NULL;
mod0.mod_values = vals0;
mod1.mod_op = LDAP_MOD_ADD;
mod1.mod_type = "description";
time( &now );
sprintf( buf, "This entry was modified with the modattrs program on %s",
ctime( &now ));
/* Get rid of \n which ctime put on the end of the time string */
if ( buf[ strlen( buf ) - 1 ] == '\n' ) {
buf[ strlen( buf ) - 1 ] = '\0';
}
vals1[ 0 ] = buf;
vals1[ 1 ] = NULL;
mod1.mod_values = vals1;
mods[ 0 ] = &mod0;
mods[ 1 ] = &mod1;
mods[ 2 ] = NULL;
/* make the change */
if ( ldap_modify_s( ld, "uid=bjensen,ou=people,dc=example,dc=com", mods )
!= LDAP_SUCCESS ) {
ldap_perror( ld, "ldap_modify_s" );
return( 1 );
}
ldap_unbind( ld );
printf( "modification was successful\n" );
return( 0 );
}