db2secClientAuthPluginInit API - Initialize client authentication plug-in

Initialization API, for the client authentication plug-in, that the Db2® database manager calls immediately after loading the plug-in.

API and data structure syntax

SQL_API_RC SQL_API_FN db2secClientAuthPluginInit 
                              ( db2int32 version,
                                void *client_fns,
                                db2secLogMessage *logMessage_fn,
                                char    **errormsg,
                                db2int32 *errormsglen );

db2secClientAuthPluginInit API parameters

version
Input. The highest version number of the API that the Db2 database manager currently supports. The DB2SEC_API_VERSION value (in db2secPlugin.h) contains the latest version number of the API that Db2 currently supports.
client_fns
Output. A pointer to memory provided by the Db2 database manager for a db2secGssapiClientAuthFunctions_<version_number> structure (also known as gssapi_client_auth_functions_<version_number>), if GSS-API authentication is used, or a db2secUseridPasswordClientAuthFunctions_<version_number> structure (also known as userid_password_client_auth_functions_<version_number>), if userid/password authentication is used. The db2secGssapiClientAuthFunctions_<version_number> structure and db2secUseridPasswordClientAuthFunctions_<version_number> structure contain pointers to the APIs implemented for the GSS-API authentication plug-in and userid/password authentication plug-in. In future versions of Db2, there might be different versions of the APIs, so the client_fns parameter is cast as a pointer to the gssapi_client_auth_functions_<version_number> structure corresponding to the version the plug-in has implemented.
The first parameter of the gssapi_client_auth_functions_<version_number> structure or the userid_password_client_auth_functions_<version_number> structure tells the Db2 database manager the version of the APIs that the plug-in has implemented.
Note: The casting is done only if the Db2 version is higher or equal to the version of the APIs that the plug-in has implemented.

Inside the gssapi_server_auth_functions_<version_number> or userid_password_server_auth_functions_<version_number> structure, the plugintype parameter should be set to one of DB2SEC_PLUGIN_TYPE_USERID_PASSWORD, DB2SEC_PLUGIN_TYPE_GSSAPI, or DB2SEC_PLUGIN_TYPE_KERBEROS. Other values can be defined in future versions of the API.

logMessage_fn
Input. A pointer to the db2secLogMessage API, which is implemented by the Db2 database manager. The db2secClientAuthPluginInit API can call the db2secLogMessage API to log messages to the db2diag log files for debugging or informational purposes. The first parameter (level) of db2secLogMessage API specifies the type of diagnostic errors that will be recorded in the db2diag log files and the last two parameters are the message string and its length. The valid values for the first parameter of db2secLogMessage API (defined in db2secPlugin.h) are:
  • DB2SEC_LOG_NONE (0) No logging
  • DB2SEC_LOG_CRITICAL (1) Severe Error encountered
  • DB2SEC_LOG_ERROR (2) Error encountered
  • DB2SEC_LOG_WARNING (3) Warning
  • DB2SEC_LOG_INFO (4) Informational

The message text will show up in the db2diag log files only if the value of the 'level' parameter of the db2secLogMessage API is less than or equal to the diaglevel database manager configuration parameter. For example, if you use the DB2SEC_LOG_INFO value, the message text will appear in the db2diag log files only if the diaglevel database manager configuration parameter is set to 4.

errormsg
Output. A pointer to the address of an ASCII error message string allocated by the plug-in that can be returned in this parameter if the db2secClientAuthPluginInit API execution is not successful.
errormsglen
Output. A pointer to an integer that indicates the length in bytes of the error message string in errormsg parameter.