Initializing a plug-in

You can initialize an SASL plug-in to work with LDAP client plug-in programming reference.

A typical LDAP SASL plug-in contains two entry points:

An initialization routine
A worker routine, which implements the authentication function

When an instance of an application uses a SASL plug-in for the first time, the LDAP library obtains the configuration information for the plug-in. The configuration information can come from ibmldap.conf or might be supplied explicitly by the application with the ldap_register_plugin() API.

When the configuration information is located, the LDAP library loads the plug-in shared library and call its initialization routine. By default, the name of the initialization routine for a plug-in is ldap_plugin_init(). A different entry point can be defined in ibmldap.conf, or supplied on the ldap_plugin_register() API if the plug-in is explicitly registered by the application.

The plug-in initialization routine is responsible for supplying the address of its worker routine entry point, which actually implements the authentication function. This initialization is done by using ldap_plugin_pblock_set() to define the address of the worker routine entry point in the pblock. For example, the following code segment depicts a typical initialization routine, where authenticate_with_fingerprint is the name of the routine that is provided by the plug-in to run a fingerprint-based authentication:

int ldap_plugin_init ( LDAP_Pblock      *pb )
{
        int rc;
        
        rc =  ldap_plugin_pblock_set ( pb, LDAP_PLUGIN_SASL_BIND_S_FN, ( void * ) 
              authenticate_with_fingerprint );
        if ( rc != LDAP_SUCCESS ) printf("ldap_plugin_init couldn't initialize 
              worker function\n");
        return ( rc );
}

A pblock is an opaque structure in which parameters are stored. A pblock is used to communicate between the LDAP client library and a plug-in. The ldap_plugin_pblock_set and ldap_plugin_pblock_get APIs are provided for your plug-in to set, or get, parameters in the pblock structure.

Using ldap_plugin_pblock_get(), the plug-in can also access configuration parameters. For example, the following code segment depicts how the plug-in can access its configuration information:

   int argc;
   char ** argv;

   rc = ldap_plugin_pblock_get ( pb, LDAP_PLUGIN_ARGC, &argc );
   if (rc != LDAP_SUCCESS)
      return (rc);
   rc = ldap_plugin_pblock_get( pb, LDAP_PLUGIN_ARGV, &argv );
   if (rc != LDAP_SUCCESS)
      return (rc);

If the plug-in initialization processing is significant, and the results are to be preserved and made available to the plug-in worker function, the initialization routine can store the initialization results as private instance data in its shared library. When the plug-in worker function is later called, it can access this private instance data. For example, during initialization, the plug-in might be required to establish a session with a remote security server. Session information can be retained in the private instance data, which can be accessed later by the plug-in worker function.

After your plug-in is correctly initialized, its worker function can be used by the LDAP library. Continuing the example that is shown, if the mechanism supported by the plug-in is userfp, the authenticate_with_fingerprint function of your plug-in is called when the application issues an ldap_sasl_bind_s() function with mechanism="userfp". See Sample worker function for an example of a plug-in worker function.