Error message handling for security plug-ins

When an error occurs in a security plug-in API, the API can return an ASCII text string in the errormsg field to provide a more specific description of the problem than the return code.

For example, the errormsg string can contain "File /home/db2inst1/mypasswd.txt does not exist." Db2® will write this entire string into the Db2 administration notification log, and will also include a truncated version as a token in some SQL messages. Because tokens in SQL messages can only be of limited length, these messages should be kept short, and important variable portions of these messages should appear at the front of the string. To aid in debugging, consider adding the name of the security plug-in to the error message.

For non-urgent errors, such as password expired errors, the errormsg string will only be dumped when the DIAGLEVEL database manager configuration parameter is set at 4.

The memory for these error messages must be allocated by the security plug-in. Therefore, the plug-ins must also provide an API to free this memory: db2secFreeErrormsg.

The errormsg field will only be checked by Db2 if an API returns a non-zero value. Therefore, the plug-in should not allocate memory for this returned error message if there is no error.

At initialization time a message logging function pointer, logMessage_fn, is passed to the group, client, and server plug-ins. The plug-ins can use the function to log any debugging information to the db2diag log files. For example:

  // Log an message indicate init successful
  (*(logMessage_fn))(DB2SEC_LOG_CRITICAL,
                     "db2secGroupPluginInit successful",
                      strlen("db2secGroupPluginInit successful"));

For more details about each parameter for the db2secLogMessage function, refer to the initialization API for each of the plug-in types.