DB2 Version 10.1 for Linux, UNIX, and Windows

How DB2 loads security plug-ins

So that the DB2® database system has the necessary information to call security plug-in functions, a security plug-in must have a correctly set up initialization function.

Each plug-in library must contain an initialization function with a specific name determined by the plug-in type:

Server side authentication plug-in: db2secServerAuthPluginInit()
Client side authentication plug-in: db2secClientAuthPluginInit()
Group plug-in: db2secGroupPluginInit()

This function is known as the plug-in initialization function. The plug-in initialization function initializes the specified plug-in and provides DB2 with information that it requires to call the plug-in's functions. The plug-in initialization function accepts the following parameters:

The highest version number of the function pointer structure that the DB2 instance invoking the plug-in can support
A pointer to a structure containing pointers to all the APIs requiring implementation
A pointer to a function that adds log messages to the db2diag log files
A pointer to an error message string
The length of the error message

The following is a function signature for the initialization function of a group retrieval plug-in:

   SQL_API_RC SQL_API_FN db2secGroupPluginInit(
     db2int32 version,
     void *group_fns,
     db2secLogMessage *logMessage_fn,
     char **errormsg,
     db2int32  *errormsglen);

Note: If the plug-in library is compiled as C++, all functions must be declared with: extern "C". DB2 relies on the underlying operating system dynamic loader to handle the C++ constructors and destructors used inside of a C++ user-written plug-in library.

The initialization function is the only function in the plug-in library that uses a prescribed function name. The other plug-in functions are referenced through function pointers returned from the initialization function. Server plug-ins are loaded when the DB2 server starts. Client plug-ins are loaded when required on the client. Immediately after DB2 loads a plug-in library, it will resolve the location of this initialization function and call it. The specific task of this function is as follows:

Cast the functions pointer to a pointer to an appropriate functions structure
Specify the pointers to the other functions in the library
Specify the version number of the function pointer structure being returned

DB2 can potentially call the plug-in initialization function more than once. This situation can occur when an application dynamically loads the DB2 client library, unloads it, and reloads it again, then performs authentication functions from a plug-in both before and after reloading. In this situation, the plug-in library might not be unloaded and then re-loaded; however, this behavior varies depending on the operating system.

Another example of DB2 issuing multiple calls to a plug-in initialization function occurs during the execution of stored procedures or federated system calls, where the database server can itself act as a client. If the client and server plug-ins on the database server are in the same file, DB2 could call the plug-in initialization function twice.

If the plug-in detects that db2secGroupPluginInit is called more than once, it should handle this event as if it was directed to terminate and reinitialize the plug-in library. As such, the plug-in initialization function should do the entire cleanup tasks that a call to db2secPluginTerm would do before returning the set of function pointers again.

On a DB2 server running on a UNIX or Linux-based operating system, DB2 can potentially load and initialize plug-in libraries more than once in different processes.