Chapter 8   Defining Functions for Authentication

This chapter explains how to write a plug-in function to bypass or replace the standard function for authentication with your own function.

Information on authentication with the Netscape Directory Server (Directory Server) is organized in the following sections:

• Understanding Authentication Methods 
• How the Directory Server Identifies Clients 
• How the Authentication Process Works 
• Writing Your Own Authentication Plug-in 
• Writing a Pre-Operation Bind Plug-in
• Using SASL with an LDAP Client




Understanding Authentication Methods


---

Authentication methods for LDAP is described in RFC 2829, which you can find at http://www.ietf.org/rfc/rfc2829.txt

Two methods that you can use to authenticate clients are simple authentication and SASL authentication:

• Simple authentication is described in RFC 2251, which you can find at http://www.ietf.org/rfc/rfc2251.txt
  
  Simple authentication provides minimal facilities for authentication. In the simple authentication method, clients send a DN and password to the server for authentication. The server compares the password sent by the client against the password stored in the client's directory entry.

• Simple Authentication and Security Layer (SASL) is described in RFC 2222, which you can find at http://www.ietf.org/rfc/rfc2222.txt
  
  SASL provides the means to use mechanisms other than simple authentication and SSL to authenticate to the Directory Server.
How the Directory Server Identifies Clients


---

The server keeps track of the identity of the LDAP client through the SLAPI_CONN_DN and SLAPI_CONN_AUTHTYPE parameters.

During an LDAP bind operation, the server authenticates the user and puts the DN and authenticated method in the SLAPI_CONN_DN and SLAPI_CONN_AUTHTYPE parameters.

When an authenticated client requests the server to perform an LDAP operation, the server checks the DN in the SLAPI_CONN_DN parameter to determine if the client has the appropriate access rights.




How the Authentication Process Works


---

When the Directory Server receives an LDAP bind request from a client, it processes the request in the following steps:

1. The server parses the LDAP bind request and retrieves the following information:
   
   
   • The DN as which the client is attempting to authenticate.
     
     
   • The method of authentication used.
     
     
   • Any credentials (such as a password) included in the request.
     
     
   If the method of authentication is LDAP_AUTH_SASL (SASL authentication), the server also retrieves the name of the SASL mechanism used from the LDAP bind request.
   
   
2. The server normalizes the DN retrieved from the request. (See the slapi_dn_normalize() function for more information on normalized DNs.)
   
   
3. The server retrieves any LDAPv3 controls included with the LDAP bind request.
   
   
4. If the method of authentication is LDAP_AUTH_SASL (SASL authentication), the server determines whether or not the SASL mechanism (specified in the request) is supported.
   
   If the SASL mechanism is not supported by the server, the server sends an LDAP_AUTH_METHOD_NOT_SUPPORTED result code back to the client and ends the processing of the bind request.
   
   
5. If the method of authentication is LDAP_AUTH_SIMPLE (simple authentication), the server checks if the DN is an empty string or if there are no credentials.
   
   If the DN is an empty string, if the DN is not specified, or if no credentials are specified, the server assumes that the client is binding anonymously and sends an LDAP_SUCCESS result code back to the client.
   
   The DN and authentication method for the connection, which are used to determine access rights for all operations performed through the connection, are left as NULL and SLAPD_AUTH_NONE, respectively.
   
   
6. If the DN specified in the request is not served by this Directory Server (for example, if the DN is uid=moxcross, o=netscape.com and the directory root of the server is o=example.com), the server sends one of the following two results back to the client and ends the processing of the bind request:
   
   
   • If the server is configured with a default referral (an LDAP URL identifying an LDAP server that handles referrals), the server sends an LDAP_REFERRAL result code back to the client (LDAP_PARTIAL_RESULTS if the client only supports the LDAPv2 protocol).
     
     
   • If the server is not configured with a default referral, the server sends an result code back to the client.
     
     
7. The server puts the information from the bind request into the parameter block:
   
   
   • SLAPI_BIND_TARGET is set to the DN as which the client is authenticating.
     
     
   • SLAPI_BIND_METHOD is set to the authentication method (for example, LDAP_AUTH_SIMPLE or LDAP_AUTH_SASL).
     
     
   • SLAPI_BIND_CREDENTIALS is set to the credentials (for example, the password) included in the request.
     
     
   • SLAPI_BIND_SASLMECHANISM (if the authentication method is LDAP_AUTH_SASL) is set to the name of the SASL mechanism that the client is using for authentication.
     
     
8. If the DN is the root DN or the update DN (the DN of the master entity responsible for replicating the directory), the server authenticates the client.
   
   
   • If the credentials are correct, the server sets theSLAPI_CONN_DN parameter to the DN and the SLAPI_CONN_AUTHTYPE parameter toLDAP_AUTH_SIMPLE. The server sends anLDAP_SUCCESS result code back to the client and ends the processing of the bind request.
     
     
   • If the credentials are incorrect, the server sends anLDAP_INVALID_CREDENTIALS result code back to the client and ends the processing of the bind request.
   
   
9. The server calls any pre-operation bind plug-in functions. If the function returns a non-zero value, the server ends the processing of the bind request.
   
   If you are writing your own plug-in function to handle authentication, you should return a non-zero value so that the server does not attempt to continue processing the bind request.
   
   
10. The server calls the backend bind function. The bind function returns one of the following values:
    
    
    • If the function returns a non-zero value (SLAPI_BIND_FAIL_OR_ANONYMOUS in Netscape Directory Server 4.x), the server ends the processing of the bind request. The bind function is responsible for sending the appropriate result code back to the client before returning a non-zero value.
      
      
    • If the function returns 0 (SLAPI_BIND_SUCCESS in Netscape Directory Server 4.x), the server continues processing the bind request. The server sends the LDAP_SUCCESS result code back to the client. (The bind function does not do this.)
      
      
11. If the backend bind function succeeds, the server sets the SLAPI_CONN_DN parameter to the DN and the SLAPI_CONN_AUTHTYPE parameter to the authentication method.
    
    
12. The server sends an LDAP_SUCCESS result code back to the client and ends the processing of the bind request.
    
    If the client's password is going to expire, the server includes a password expiring control (with the OID 2.16.840.1.113730.3.4.5) with the result sent to the client. If the client is logging in for the first time and needs to change the password, the server includes a password expired control (with the OID 2.16.840.1.113730.3.4.4) with the result sent to the client.




Writing Your Own Authentication Plug-in


---

A situation may arise in which you may want to write and implement your own function for authentication; that is, replace the standard means of authentication with your own function. You can write a pre-operation bind plug-in function (a function that the server calls before processing an LDAP bind request) that performs the authentication and bypasses the default bind functionality. For details, see the next section, Writing a Pre-Operation Bind Plug-in.




Writing a Pre-Operation Bind Plug-in


---

You can define your own pre-operation bind plug-in function to authenticate LDAP clients. The server will call your function during the authentication process (in Step 9). Your function should return a non-zero value to bypass the default backend bind function and the post-operation bind functions.

Note that this means that Step 10 through Step 12 are skipped. Your pre-operation plug-in function is responsible for sending the result code to the client and for setting the DN and authentication method for the connection.

Figure 8-1 summarizes the process of using a pre-operation bind plug-in function to authenticate LDAP clients to the Directory Server.

Figure 8-1    Using a Pre-Operation Bind Plug-in Function to Handle Authentication



Figure 8-2 illustrates the steps that your pre-operation bind plug-in function must take to authenticate LDAP clients to the Directory Server.

Figure 8-2    How Your Pre-Operation Bind Plug-in Function Can Authenticate LDAP Clients



Defining Your Authentication Function

The following sections cover guidelines that you can follow when defining your authentication function:

• Getting and Checking the Bind Parameters
• Getting the Entry and Checking the Credentials
• What to Do If Authentication Fails
• What to Do If Authentication Succeeds




Note	Be sure to check this source file for an example of a pre-operation plug-in function that handles authentication: <server_root>/plugins/slapd/slapi/examples/testbind.c



Getting and Checking the Bind Parameters

Call the slapi_pblock_get() function to get the values of the following parameters:

• SLAPI_BIND_TARGET -- A string value specifying the DN as which the client is attempting to authenticate).
  
  
• SLAPI_BIND_METHOD -- An integer value specifying the authentication method, such as LDAP_AUTH_SIMPLE or LDAP_AUTH_SASL.
  
  
• SLAPI_BIND_CREDENTIALS -- A berval structure containing the credentials sent by the client.

If you plan to support authentication through SASL mechanisms, you should also get the value of the SLAPI_BIND_SASLMECHANISM parameter (a string value specifying the name of the SASL mechanism to use for authentication).

Make sure to check the following:

• Determine if the client is requesting to bind as an anonymous user.
  
  If the SLAPI_BIND_METHOD parameter is LDAP_AUTH_SIMPLE and the SLAPI_BIND_CREDENTIALS parameter is empty or NULL, the client is attempting to bind anonymously.
  
  Call slapi_send_ldap_result() to send the LDAP result code LDAP_SUCCESS back to the client.
  
  
• If the SLAPI_BIND_METHOD parameter specifies a method that you do not recognize or support, call slapi_send_ldap_result() to send an LDAP_STRONG_AUTH_NOT_SUPPORTED result code back to the client.

In both cases, return a non-zero value to prevent the server from calling the default backend function for authentication.




Getting the Entry and Checking the Credentials

Get the entry for the DN specified by the SLAPI_BIND_TARGET parameter, and compare the credentials in the SLAPI_BIND_CREDENTIALS parameter against the known credentials for that entry.

By default, Directory Server 4.x uses the userpassword attribute to store the credentials for an entry. The server encodes the password using the scheme specified in the passwdhash directive of the slapd.conf configuration file. The scheme can be crypt, sha, or "." (for cleartext).

By default, Directory Server 7.x uses the userpassword attribute to store the credentials for an entry. The server encodes the password using the scheme specified in the nsslapd-rootpwstoragescheme or passwordStorageScheme attributes of the cn=config entry contained in the dse.ldif file. The scheme can be any of the following:

• CLEAR -- Means no encryption and can be defined using the clear-password-storage-scheme plug-in.
  
  
• CRYPT -- Means Unix crypt algorithm and can be defined using the crypt-password-storage-scheme plug-in.
  
  
• SHA -- Means Secure Hashing Algorithm and can be defined using the sha-password-storage-scheme plug-in.
  
  
• SSHA -- Means Salted Secure Hashing Algorithm and can be defined using the ssha-password-storage-scheme plug-in.

If you need to compare the client's credentials against the value of the userpassword attribute, you can call the slapi_pw_find_sv() function. This function determines which password scheme was used to store the password and uses the appropriate comparison function to compare a given value against the encrypted value of the userpassword attribute.





What to Do If Authentication Fails

If authentication fails, send one of the following result codes back to the client:

• If no entry matches the DN specified by the client, send an LDAP_NO_SUCH_OBJECT result code back to the client.
  
  When calling the slapi_send_ldap_result() function to send the result code back to the client, specify the closest matching DN as the matched argument.
  
  

• If the client fails to provide the necessary credentials or if credentials cannot be found in the entry, send an LDAP_INAPPROPRIATE_AUTH result code back to the client.
  
  
• If the credentials specified by the client do not match the credentials found in the entry, send an LDAP_INVALID_CREDENTIALS result code back to the client.
  
  
• If a general error occurs, send an LDAP_OPERATIONS_ERROR result code back to the client.
  
  

Your function should also return a non-zero value (SLAPI_BIND_FAIL_OR_ANONYMOUS in Netscape Directory Server 4.x).

You do not need to set any values for the SLAPI_CONN_DN parameter and the SLAPI_CONN_AUTHTYPE parameter. By default, these parameters are set to NULL and LDAP_AUTH_NONE, which indicate that the client has bound anonymously.





What to Do If Authentication Succeeds

If the authentication is successful, your authentication function should do the following:

• Call slapi_pblock_set() to set the values of the SLAPI_CONN_DN parameter and the SLAPI_CONN_AUTHTYPE parameter to the DN and authentication method.
  
  This sets the DN and authentication method for the connection to the client. (The server uses this DN and method in subsequent operations when checking access rights.)
  
  You can set SLAPI_CONN_AUTHTYPE to one of the following values:
  
  
  • SLAPD_AUTH_NONE represents no authentication. (The client is binding anonymously.)
    
    
  • SLAPD_AUTH_SIMPLE represents the simple authentication method.
    
    
  • SLAPD_AUTH_SSL represents authentication through SSL.
    
    
  • SLAPD_AUTH_SASL represents SASL authentication.
  
  Note that these values differ from the values in the SLAPI_BIND_METHOD parameter. The values listed above are string values defined in the slapi-plugin.h header file, whereas the values of the SLAPI_BIND_METHOD parameter (such as LDAP_AUTH_SIMPLE and LDAP_AUTH_SASL) are integer values defined in the ldap.h header file.
  
  
• If you want to, specify the credentials that you want sent back to the client.
  
  If the value of the SLAPI_BIND_METHOD parameter is LDAP_AUTH_SASL and you want to return a set of credentials to the client, call slapi_pblock_set() to set the SLAPI_BIND_RET_SASLCREDS parameter to the credentials.
  
  

• Send the result of the authentication process back to the client.
  
  Call slapi_send_ldap_result() to send an LDAP_SUCCESS return code to the client.

Make sure that your function returns a non-zero value to bypass the default backend bind function and any post-operation plug-in functions.






Registering the SASL Mechanism

If you are using SASL as the authentication method, you need to register the SASL mechanisms that you plan to use.

In your initialization function (see Writing Plug-in Initialization Functions), call the Functions for Syntax Plug-in function and specify the name of the SASL mechanism. For example:

slapi_register_supported_saslmechanism( "babsmechanism" );

If you do not register your SASL mechanism, the Directory Server will send an LDAP_AUTH_METHOD_NOT_SUPPORTED result code back to the client and will not call your pre-operation bind function.


Note	Be sure to check this source file for an example of a pre-operation plug-in function for SASL authentication with LDAP bind operations: <server_root>/plugins/slapd/slapi/examples/testsaslbind.c




Example of a Pre-Operation Bind Plug-in

The following sections document an example of a pre-operation bind plug-in that handles authentication:

• Example of a Pre-Operation Bind Function
• Example of an Initialization Function
• Registering the Plug-in




Note	Be sure to check this source file for an updated example of a pre-operation plug-in function that handles authentication: <server_root>/plugins/slapd/slapi/examples/testbind.c




Example of a Pre-Operation Bind Function

The following is an example of a pre-operation bind function that authenticates clients and bypasses the default backend bind function. In this example, the function just compares the client's credentials against the value of the userpassword attribute for the entry.


Code Example 8-1   Sample pre-Operation Bind Function

#include <stdio.h>

#include <string.h>

#include "slapi-plugin.h"

/* Pre-operation plug-in function */

int

test_bind( Slapi_PBlock *pb )

{

char *dn;

int method, rc = LDAP_SUCCESS;

struct berval *credentials;

struct berval **pwvals;

Slapi_PBlock *searchpb = NULL;

Slapi_Entry *e = NULL;

Slapi_Entry **entries = NULL;

Slapi_Attr *attr = NULL;

/* Log a message to the server error log. */

slapi_log_error( SLAPI_LOG_PLUGIN, "test_bind",

"Pre-operation bind function called.\n" );

/* Gets parameters available when processing an LDAP bind

operation. */

if ( slapi_pblock_get( pb, SLAPI_BIND_TARGET, &dn ) != 0 ||

slapi_pblock_get( pb, SLAPI_BIND_METHOD, &method ) != 0 ||

slapi_pblock_get( pb, SLAPI_BIND_CREDENTIALS, &credentials ) != 0 ) {

slapi_log_error( SLAPI_LOG_PLUGIN, "test_bind",

"Could not get parameters for bind operation\n" );

slapi_send_ldap_result( pb, LDAP_OPERATIONS_ERROR,

NULL, NULL, 0, NULL );

return( 1 );

}

/* Check the authentication method */

switch( method ) {

case LDAP_AUTH_SIMPLE:

/* First, get the entry specified by the DN. */

searchpb = slapi_search_internal( dn, LDAP_SCOPE_BASE,

"(objectclass=*)", NULL, NULL, 0 );

if ( searchpb != NULL ) {

slapi_pblock_get( pb, SLAPI_PLUGIN_INTOP_RESULT, &rc );

if ( rc == LDAP_SUCCESS ) {

slapi_pblock_get( searchpb, SLAPI_PLUGIN_INTOP_SEARCH_ENTRIES,

&entries );

if ( entries != NULL && entries[0] != NULL ) {

e = entries[0];

} else {

slapi_log_error( SLAPI_LOG_PLUGIN, "test_bind",

"Could not find entry for %s\n", dn );

rc = LDAP_NO_SUCH_OBJECT;

break;

}

} else {

slapi_log_error( SLAPI_LOG_PLUGIN, "test_bind",

"Could not find entry for %s (error %d)\n", dn, rc );

break;

}

} else {

slapi_log_error( SLAPI_LOG_PLUGIN, "test_bind",

"Could not search for entry\n" );

rc = LDAP_OPERATIONS_ERROR;

break;;

}

/* Next, check the credentials against the userpassword attribute

of that entry. */

if ( e != NULL ) {

if ( slapi_entry_attr_find( e, "userpassword", &attr ) != 0 ) {

slapi_log_error( SLAPI_LOG_PLUGIN, "test_bind",

"Entry has no userpassword attribute\n" );

rc = LDAP_INAPPROPRIATE_AUTH;

break;

}

slapi_attr_get_values( attr, &pwvals );

if ( slapi_pw_find( pwvals, credentials ) != 0 ) {

slapi_log_error( SLAPI_LOG_PLUGIN, "test_bind",

"Credentials are not correct for the entry\n" );

rc = LDAP_INVALID_CREDENTIALS;

break;

}

} else {

/* This should not happen. The previous section of code

already checks for this case. */

slapi_log_error( SLAPI_LOG_PLUGIN, "test_bind",

"Could find entry for %s\n", dn );

rc = LDAP_NO_SUCH_OBJECT;

break;

}

/* Set the DN and the authentication method for the connection. */

if ( slapi_pblock_set( pb, SLAPI_CONN_DN, slapi_ch_strdup( dn ) ) != 0 ||

slapi_pblock_set( pb, SLAPI_CONN_AUTHTYPE, SLAPD_AUTH_SIMPLE ) != 0 ) {

slapi_log_error( SLAPI_LOG_PLUGIN, "testbind_init",

"Failed to set DN and auth method for connection\n" );

rc = LDAP_OPERATIONS_ERROR;

break;

}

/* Send a "success" result code back to the client. */

slapi_log_error( SLAPI_LOG_PLUGIN, "test_bind", "Authenticated: %s\n", dn );

rc = LDAP_SUCCESS;

break;

/* If NONE is specified, the client is requesting to bind anonymously.

Normally, this case should be handled by the server's front-end

before it calls this plug-in function. Just in case this does

get through to the plug-in function, you can handle this by

sending a successful result code back to the client and returning

1.

*/

case LDAP_AUTH_NONE:

slapi_log_error( SLAPI_LOG_PLUGIN, "test_bind", "Authenticating anonymously\n" );

rc = LDAP_SUCCESS;

break;

/* This plug-in does not support any other method of authentication */

case LDAP_AUTH_SASL:

default:

slapi_log_error( SLAPI_LOG_PLUGIN, "test_bind",

"Unsupported authentication method requested: %d\n",

method );

rc = LDAP_AUTH_METHOD_NOT_SUPPORTED;

break;

}

if ( searchpb ) {

slapi_free_search_results_internal( searchpb );

slapi_ch_free( ( void ** )&searchpb );

}

slapi_send_ldap_result( pb, rc, NULL, NULL, 0, NULL );

return( 1 );

}




Example of an Initialization Function

To initialize your plug-in, write an initialization function to do the following:

• Call slapi_pblock_set() to set the SLAPI_PLUGIN_PRE_BIND_FN parameter to the name of your pre-operation bind function. (For details, see Registering Your Plug-in Functions.)
  
  
• If you are using SASL as the authentication method, call the Functions for Syntax Plug-in function to register your SASL mechanism with the Directory Server.

The following is an example of an initialization function that registers the pre-operation bind function.

Code Example 8-2   Sample Function for Registering Pre-Operation Bind Function


#include <stdio.h>

#include <string.h>

#include "slapi-plugin.h"

Slapi_PluginDesc bindpdesc = { "test-bind", "Netscape", "0.5",

"sample bind pre-operation plugin" };

/* Initialization function */

#ifdef _WIN32

__declspec(dllexport)

#endif

int

testbind_init( Slapi_PBlock *pb )

{

/* Register the pre-operation bind function and specify

the server plug-in version. */

if ( slapi_pblock_set( pb, SLAPI_PLUGIN_VERSION, SLAPI_PLUGIN_VERSION_01 ) != 0 || slapi_pblock_set( pb, SLAPI_PLUGIN_DESCRIPTION, (void *)&bindpdesc ) != 0 || slapi_pblock_set( pb, SLAPI_PLUGIN_PRE_BIND_FN, (void *) test_bind ) != 0 ) {

slapi_log_error( SLAPI_LOG_PLUGIN, "testbind_init",

"Failed to set version and function\n" );

return( -1 );

}

return( 0 );

}




Registering the Plug-in

To register the plug-in, follow the instructions appropriate for the Directory Server you're using:

• In Directory Server 4.x, add the plugin preoperation directive to the end of the slapd.ldbm.conf file, which is located in the <server_root>/slapd-<instance_id>/config directory:
  
  plugin preoperation on "my preop plugin" /<server_root>/plugins/slapd/slapi/examples/libtest-plugin.so testauth_init
  
  Each pre-operation and post-operation plug-in is associated with a backend. Make sure that the plugin directive that registers the plug-in is within the database section for that back-end in the server configuration file. (The plugin directive should be added somewhere after the database directive.)

• In current versions of Directory Server, add this to the end of the dse.ldif file, which is located in the <server_root>/slapd-<instance_id>/config directory:
  
  dn: cn=Test Bind,cn=plugins,cn=config
  objectClass: top
  objectClass: nsSlapdPlugin
  objectClass: extensibleObject
  cn: Test Bind
  nsslapd-pluginPath: <server_root>/plugins/slapd/slapi/examples/libtest-plugin.so
  nsslapd-pluginInitfunc: testbind_init
  nsslapd-pluginType: preoperation
  nsslapd-pluginEnabled: on
  nsslapd-plugin-depends-on-type: database
  nsslapd-pluginId: test-bind

Check this source file for an example of a pre-operation plug-in function that handles authentication: <server_root>/plugins/slapd/slapi/examples/testbind.c





Using SASL with an LDAP Client

---
If you intend to use SASL as the method for authenticating clients, you need to enable your LDAP clients to use SASL.
In your client, call the ldap_sasl_bind() or ldap_sasl_bind_s() function to request authentication using SASL. To parse credentials from an asynchronous SASL bind operation, call ldap_parse_sasl_bind_result(). These functions are part of the Netscape LDAP C SDK 3.0.
The syntax for these functions are listed below:
LDAP_API(int) LDAP_CALL ldap_sasl_bind( LDAP *ld, const char *dn,
const char *mechanism, struct berval *cred,
LDAPControl **serverctrls, LDAPControl **clientctrls, int *msgidp );
LDAP_API(int) LDAP_CALL ldap_sasl_bind_s( LDAP *ld, const char *dn,
const char *mechanism, struct berval *cred,
LDAPControl **serverctrls, LDAPControl **clientctrls,
struct berval **servercredp );
The parameters are described below:
• ld is the connection handle, which is a pointer to the LDAP structure containing information about the connection to the LDAP server.
  
  
• dn is the distinguished name (DN) as which your client is attempting to authenticate.
  
  
• mechanism is the name of the SASL mechanism that you want to use for authentication (the mechanism that you register in the initialization function for your server plug-in).
  
  
• cred is a pointer to the berval structure containing the credentials that you want to use for authentication.
  
  
• serverctrls is a pointer to an array of LDAPControl structures representing the LDAPv3 server controls that you want passed to the server for the bind operation.
  
  
• clientctrls is a pointer to an array of LDAPControl structures representing the LDAPv3 client controls applicable to the bind operation.
  
  
• msgidp is a pointer to the message ID for this bind operation. To check the result of this operation, call the ldap_result() function and the ldap_parse_sasl_bind_result() function.
  
  
• servercredp is a pointer to a pointer to the berval structure containing any credentials returned by the server. These are the credentials that you set as the value of the SLAPI_BIND_RET_SASLCREDS parameter in your pre-operation bind plug-in function.
If you are call the ldap_sasl_bind() function, you need to call the ldap_result() function to get the result of the authentication attempt:
LDAP_API(int) LDAP_CALL ldap_result( LDAP *ld, int msgid, \
int all, struct timeval *timeout, LDAPMessage **result );
The parameters are described below:
• ld is the connection handle, which is a pointer to the LDAP structure containing information about the connection to the LDAP server.
  
  
• msgidp is the message ID returned as the last argument of the ldap_sasl_bind() function.
  
  
• all applies to LDAP search operations. Since this is not an LDAP search operation, you can pass NULL for this argument.
  
  
• timeout is the maximum interval to wait for the selection to complete. If timeout is a NULL pointer, the select blocks indefinitely. To effect a poll, the timeout parameter should be a non-NULL pointer, pointing to a zero-valued timeval structure.
  
  
• result is a pointer to an LDAPMessage structure containing the results of the bind operation. You need to pass this to the ldap_parse_sasl_bind_result() function.
After callingldap_result(), you need to call the ldap_parse_sasl_bind_result() function to parse the results and retrieve the LDAP result code and any credentials returned by the server:
LDAP_API(int) LDAP_CALL ldap_parse_sasl_bind_result( LDAP *ld, \
LDAPMessage *res, struct berval **servercredp, int freeit);
The parameters are described below:
• ld is the connection handle, which is a pointer to the LDAP structure containing information about the connection to the LDAP server.
  
  
• res is a pointer to the LDAPMessage structure containing the results that you want to parse.
  
  
• servercredp is a pointer to a pointer to the berval structure containing any credentials returned by the server. These are the credentials that you set as the value of the SLAPI_BIND_RET_SASLCREDS parameter in your pre-operation bind plug-in function.
  
  
• freeit specifies whether or not the result (the LDAPMessage structure) should be freed after the error code is extracted. If 0, the result is not freed. If non-zero, the result is freed.
The following example is an LDAP client that authenticates using the SASL method named babsmechanism.
Code Example 8-3   LDAP Client Authenticating Using SASL Method

#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. Extended operations

are 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,o=example.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,o=example.com", mods )

!= LDAP_SUCCESS ) {

ldap_perror( ld, "ldap_modify_s" );

return( 1 );

}

ldap_unbind( ld );

printf( "modification was successful\n" );

return( 0 );

}




Previous

Contents

Index

DocHome

Next
---
© 2001 Sun Microsystems, Inc. Portions copyright 1999, 2002-2004 Netscape Communications Corporation. All rights reserved.
Read the Full Copyright and Third-Party Acknowledgments.

last updated November 26, 2004