db2secValidatePassword API - Validate password

Provides a method for performing user ID and password style authentication during a database connect operation.

Note: When the API is run on the client side, the API code is run with the privileges of the user executing the CONNECT statement. This API will only be called on the client side if the authentication configuration parameter is set to CLIENT.

When the API is run on the server side, the API code is run with the privileges of the instance owner.

The plug-in writer should take the previous scenarios into consideration if authentication requires special privileges (such as root level system access on UNIX).

This API must return the value DB2SEC_PLUGIN_OK (success) if the password is valid, or an error code such as DB2SEC_PLUGIN_BADPWD if the password is invalid.

API and data structure syntax

     SQL_API_RC ( SQL_API_FN *db2secValidatePassword) 
                           ( const char *userid,
                             db2int32 useridlen,
                             const char *usernamespace,
                             db2int32 usernamespacelen,
                             db2int32 usernamespacetype,
                             const char *password,
                             db2int32 passwordlen,
                             const char *newpasswd,
                             db2int32 newpasswdlen,
                             const char *dbname,
                             db2int32 dbnamelen,
                             db2Uint32 connection_details,
                             void      **token,
                             char      **errormsg,
                             db2int32 *errormsglen );

db2secValidatePassword API parameters

userid
Input. The user ID whose password is to be verified.
useridlen
Input. Length in bytes of the userid parameter value.
usernamespace
Input. The namespace from which the user ID was obtained.
usernamespacelen
Input. Length in bytes of the usernamespace parameter value.
usernamespacetype
Input. The type of namespace. Valid values for the usernamespacetype parameter (defined in db2secPlugin.h) are:
  • DB2SEC_NAMESPACE_SAM_COMPATIBLE Corresponds to a username style like domain\myname
  • DB2SEC_NAMESPACE_USER_PRINCIPAL Corresponds to a username style like myname@domain.ibm.com
Currently, the Db2® database system only supports the value DB2SEC_NAMESPACE_SAM_COMPATIBLE. When the user ID is not available, the usernamespacetype parameter is set to the value DB2SEC_USER_NAMESPACE_UNDEFINED (defined in db2secPlugin.h).
password
Input. The password to be verified.
passwordlen
Input. Length in bytes of the password parameter value.
newpasswd
Input. A new password, if the password is to be changed. If no change is requested, this parameter is set to NULL. If this parameter is not NULL, the API should validate the old password before changing it to the new password. The API does not have to fulfill a request to change the password, but if it does not, it should immediately return with the return value DB2SEC_PLUGIN_CHANGEPASSWORD_NOTSUPPORTED without validating the old password.
newpasswdlen
Input. Length in bytes of the newpasswd parameter value.
dbname
Input. The name of the database being connected to. The API is free to ignore the dbname parameter, or it can return the value DB2SEC_PLUGIN_CONNECTIONREFUSED if it has a policy of restricting access to certain databases to users who otherwise have valid passwords. This parameter can be NULL.
dbnamelen
Input. Length in bytes of the dbname parameter value. This parameter is set to 0 if dbname parameter is NULL.
connection_details
Input. A 32-bit parameter of which 3 bits are currently used to store the following information:
  • The rightmost bit indicates whether the source of the user ID is the default from the db2secGetDefaultLoginContext API, or was explicitly provided during the connect.
  • The second-from-right bit indicates whether the connection is local (using Inter Process Communication (IPC) or a connect from one of the nodes in the db2nodes.cfg in the partitioned database environment), or remote (through a network or loopback). This gives the API the ability to decide whether clients on the same machine can connect to the Db2 server without a password. Due to the default operating-system-based user ID/password plugin, local connections are permitted without a password from clients on the same machine (assuming the user has connect privileges).
  • The third-from-right bit indicates whether the Db2 database manager is calling the API from the server side or client side.
The bit values are defined in db2secPlugin.h:
  • DB2SEC_USERID_FROM_OS (0x00000001) Indicates that the user ID is obtained from OS and not explicitly given on the connect statement.
  • DB2SEC_CONNECTION_ISLOCAL (0x00000002) Indicates a local connection.
  • DB2SEC_VALIDATING_ON_SERVER_SIDE (0x0000004) Indicates whether the Db2 database manager is calling from the server side or client side to validate password. If this bit value is set, then the Db2 database manager is calling from server side; otherwise, it is calling from the client side.

The Db2 database system default behavior for an implicit authentication is to allow the connection without any password validation. However, plug-in developers can disallow implicit authentication by returning a DB2SEC_PLUGIN_BADPASSWORD error.

token
Input/output. A pointer to data which can be passed as a parameter to subsequent API calls during the current connection. Possible APIs that might be called include db2secGetAuthIDs API and db2secGetGroupsForUser API.
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 db2secValidatePassword 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.