Table of Contents | Previous | Next | Index

Netscape Directory SDK 3.0 for C Programmer’s Guide
     Chapter 18 Functions

ldap_set_rebind_proc()

Sets the rebind function, which is the function called by your client to obtain authentication credentials when following a referral.

Syntax 

#include <ldap.h>
void ldap_set_rebind_proc( LDAP *ld, 
   LDAP_REBINDPROC_CALLBACK *rebindproc, void *arg );

Parameters

This function has the following parameters: 

ld

Connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server. 

rebindproc

Name of the rebind function. 

arg

Pointer to an additional argument that you want to pass to the rebind function.

Description

Call the ldap_set_rebind_proc() function to specify the rebind function (the function called by the LDAP client when following a referral to a new LDAP server). This rebind function is responsible for obtaining the credentials used to authenticate to the new LDAP server.

For example, suppose LDAP server A sends a referral to your client. The referral points your client to LDAP server B. When automatically following the referral, your client calls the rebind function to obtain a DN and credentials; your client uses these to authenticate to server B.

By default, if you do not call ldap_set_rebind_proc() or if you pass NULL for the rebindproc argument, your client authenticates anonymously when following referrals.

The rebind function that you specify with ldap_set_rebind_proc() should have the following prototype:

int LDAP_CALL LDAP_CALLBACK rebindproc( LDAP *ld, char **dnp, char **passwdp, int *authmethodp, int freeit, void *arg );
(LDAP_CALL and LDAP_CALLBACK are used to set up calling conventions, such as Pascal calling conventions on Windows. These are defined in the lber.h header file.)

LDAP clients that are built with the Netscape LDAP C SDK use this procedure when following referrals (the procedure explains what the rebind function is expected to do):

  1. The LDAP server sends a referral back to the client.

  2. The client calls the rebind function, passing 0 as the freeit argument.

  3. The rebind function sets the dnp, passwdp, and authmethodp arguments to point to the following information:

  4. If successful, the rebind function returns LDAP_SUCCESS, and referral processing continues. (If any other value is returned, referral processing stops, and that value is returned as the result code for the original LDAP request.)

  5. The client gets the DN, credentials, and authentication method from the arguments of the rebind function and uses this information to authenticate to the new LDAP server.

  6. The client calls the rebind function again, passing 1 as the freeit argument.

  7. The rebind function frees any memory allocated earlier to specify the DN and credentials.
You need to write a rebind function that does the following:

After you have defined this function, pass the function name to ldap_set_rebind_proc() to register your rebind function.

Note that in order to use the rebind function, the LDAP_OPT_REFERRALS option must be set to LDAP_OPT_ON, so that your client automatically follows referrals. This option is already set to LDAP_OPT_ON by default.

Example

The following example demonstrates how to write and register a rebind function. 

#include "ldap.h"
...
/* Declare your rebind function */
int rebindproc( LDAP *ld, char **dnp, char **passwdp, int *authmethodp, int freeit, void *arg );
...
int main( int argc, char **argv )
{
   LDAP *ld;
   /* Additional argument to be passed to the rebind function */
   char *testarg = "cn=Directory Manager";
   /* Get a handle to an LDAP connection */
   if ( (ld = ldap_init( "directory.myhost.com", 389 )) == NULL ) {
      perror( "ldap_init" );
      return( 1 );
   }
   /* Specify the function used for reauthentication on referrals */
   ldap_set_rebind_proc( ld, rebindproc, (void *)testarg );
   /* Authenticate */ 
   if ( ldap_simple_bind_s( ld, "uid=bjensen,ou=People,o=Airius.com", 
         "hifalutin" ) != LDAP_SUCCESS ) {
      ldap_perror( ld, "ldap_simple_bind_s" );
      return( 1 );
   }
   ...
   /* Your code to interact with the LDAP server */
   ...
}
...
/* rebindproc is the rebind function responsible for providing the DN, 
   credentials, and authentication method used for authenticating the 
   client to other Directory Servers.
   The function should set the following arguments:
   - dnp should point to the DN that will be used for authentication.
   - passwdp should point to the credentials used for authentication.
   - authmethodp should point to the method of authentication to be used 
   (for example, LDAP_AUTH_SIMPLE).
   The function should return LDAP_SUCCESS if successful or an LDAP 
   error code if an error occurs.
   In order to demonstrate how the freeit argument works, this example 
   uses strdup() to copy the DN and password.  You can also just copy 
   string pointers if the DN and password are already available as 
   global variables.
*/
int LDAP_CALL LDAP_CALLBACK rebindproc( LDAP *ld, char **dnp, char **passwdp, int *authmethodp, int freeit, void *arg )
{
   printf( "Rebind function called.\n" );
   switch ( freeit ) {
   /* Your client calls the rebind function with freeit==1 when it needs 
      to free any memory you've allocated. */
   case 1:
      printf( "\tFreeing memory.\n" );
      if ( dnp && *dnp ) {
         free( *dnp );
      }
      if ( passwdp && *passwdp ) {
         free( *passwdp );
      }
      break;
   /* Your client calls the rebind function with freeit==0 when it needs 
   to get the DN, credentials, and authentication method. */
   case 0:
      printf( "\tGetting DN and credentials.\n" );
      *dnp = strdup( "uid=username,o=OtherServerSuffix" );
      *passwdp = strdup( "23skidoo" );
      *authmethodp = LDAP_AUTH_SIMPLE;
      break;
   default:
      printf( "\tUnknown value of freeit argument: %d\n", freeit );
      break;
   }
   /* If you successfully set the DN and credentials, you should return 
      LDAP_SUCCESS.  (Any other return code will stop the client from 
      automatically following the referral. */
   return LDAP_SUCCESS;
}

See Also

ldap_simple_bind(), ldap_simple_bind_s().

Table of Contents | Previous | Next | Index

Last Updated: 10/01/98 17:06:23