LDAP_PLUGIN_REGISTRATION

Edit online

Use the LDAP_PLUGIN_REGISTRATION API or LDAP routine to register an LDAP client plug-in, obtain information about plug-ins that are registered by the application and plug-ins that are defined in ibmldap.conf, and free the array of plug-in information that is returned from the ldap_query_plugin() API.

ldap_register_plugin
ldap_query_plugin
ldap_free_query_plugin

Synopsis

#include ldap.h


int ldap_register_plugin(
       LDAP_File_Plugin_Info *plugin_info)

int ldap_query_plugin(
       LDAP_File_Plugin_Info  plugin_infop )

int ldap_free_query_plugin(
       LDAP_File_Plugin_Info  ***plugin_infop )

typedef struct ldap_file_plugin_info {
    char    *type;              /* plug-in type                */
    char    *subtype;           /* plug-in subtype             */
    char    *path;              /* path to plug-in library     */
    char    *init;              /* initialization routine     */
    char    *paramlist;         /* plug-in parameter list      */
} LDAP_File_Plugin_Info;

Input parameters

plugin_info

A structure that contains information about a specific type of SASL plug-in. An instance of the structure contains the following fields:

type: NULL-terminated string that defines the plug-in type. The only type that is supported is sasl.
subtype: NULL-terminated string that specifies the subtype of the plug-in being registered. When type=sasl, the subtype is used to specify the SASL mechanism that is supported by the plug-in. For example, fingerprint might be specified for any SASL plug-in that supports the fingerprint mechanism.
path: NULL-terminated string that specifies the path to the plug-in shared library. The plug-in path can be a fully qualified path that includes file name, or only the file name with or without the file extension. If only the file name is supplied, the LDAP library attempts to find it using standard operating system search criteria.
init: NULL-terminated string that specifies the initialization routine for the plug-in. If NULL, the name of the initialization routine is assumed to be ldap_plugin_init.
parmlist: NULL-terminated string that specifies arbitrary parameter information that is used by the plug-in. For example, if the plug-in accesses a remote security server, then the remote security server host name is supplied as a value in the parameter list.

plugin_infop

Specifies the address that points to a NULL-terminated array of LDAP_Plugin_Info structures. Each LDAP_Plugin_Info structure that is defined in the list contains information about a registered plug-in. For example:

LDAP_File_Plugin_Info  **plugin_infop;

             rc = ldap_query_plugin (&plugin_infop);

Output parameters

plugin_infop: Upon successful return from ldap_query_plugin(), plugin_infop points to a NULL-terminated array of LDAP_Plugin_Info pointers. If there are no plug-ins that are registered, the plugin_infop data structure is set to NULL and no memory is allocated.

Usage

Two mechanisms are available for making an LDAP client plug-in that is known to the LDAP library:

The plug-in is defined in the ibmldap.conf file.
The plug-in is explicitly registered by the application, by using the ldap_register_plugin() API.

An application can override the definition of a plug-in in the ibmldap.conf file by using the ldap_register_plugin() API. A plug-in is uniquely identified by the combination of its type and subtype. For example, an application can choose to use its own DIGEST-MD5 plug-in as defined in ibmldap.conf, by calling ldap_register_plugin() and defining another shared library with type="sasl" and subtype="DIGEST-MD5". Plug-ins that are registered with the ldap_register_plugin() API are defined for the application.

Finding the plug-in library

When a plug-in is not explicitly registered by the application with the ldap_register_plugin() API, the LDAP library must find the appropriate plug-in shared library. To find information about the plug-in, the LDAP library must find the ibmldap.conf file. The attempt to locate the ibmldap.conf file is made on behalf of the application in whichever of the following events occurs first:

The ldap_register_plugin() API is called.
The ldap_sasl_bind_s() API is called.

After the ibmldap.conf file is accessed, all information in the file is stored internally for subsequent use. The file is not reaccessed until the application is restarted. However, the application can use the ldap_register_plugin() API to add more plug-in definitions, or to override definitions that are obtained from the ibmldap.conf file.

The ibmldap.conf file

The ibmldap.conf file contains information that is required to load and initialize default plug-ins. It can also include more plug-in-specific configuration information. The following types might be defined for each plug-in in the ibmldap.conf file:

The plug-in type (for example, sasl)
The plug-in subtype (for example, mechanism, if type=sasl)
The path to the plug-in shared library
The plug-in initialization routine
The user-defined parameter string

The ibmldap.conf file might contain one or more records, each defining this information for a plug-in. Each record takes the following form:

plugin type  subtype  path  init-routine parameters

For example:

#
#   keyword type   subtype          path               init      parameters
#
    plugin  sasl   fpauth    x:\security\fplib         fpinit    parm2 parm3
    plugin  sasl   hitech    hitechlib                 hitekinit parm5 parm6

This example defines two plug-ins, fpauth and hitek, along with associated information.

Note: If the extension is omitted, then an appropriate extension is assumed for the platform. For example, .a on the AIX® operating system or .dll on a Windows™ operating system. If the fully qualified path is omitted, standard operating system search rules are applied.

Lines beginning with a number sign ( # ) are ignored.

The algorithm that is used to locate the ibmldap.conf file is platform-specific:

On a UNIX™ system, the following search order is used:
1. Query the environment variable IBMLDAP_CONF for the path to the ibmldap.conf file.
2. Look for the ibmldap.conf file in the /etc directory.
On a Windows system, the following search order is used:
1. Query the environment variable IBMLDAP_CONF for the path to the ibmldap.conf file.
2. Look in the current directory for the ibmldap.conf file.
3. Look for the ibmldap.conf file in the \etc directory under the LDAP installation directory. For example, C:\Program Files\IBM\ldap\V11.0.1\etc.

If the SASL plug-in definition is not available, the LDAP library encodes the SASL bind. It transmits it directly to the LDAP server and bypasses the plug-in facility.

Errors