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.