db2secGenerateInitialCred API - Generate initial credentials

The db2secGenerateInitialCred API obtains the initial GSS-API credentials based on the user ID and password that are passed in.

For Kerberos, this is the ticket-granting ticket (TGT). The credential handle that is returned in pGSSCredHandle parameter is the handle that is used with the gss_init_sec_context API and must be either an INITIATE or BOTH credential. The db2secGenerateInitialCred API is only called when a user ID, and possibly a password are supplied. Otherwise, the Db2® database manager specifies the value GSS_C_NO_CREDENTIAL when calling the gss_init_sec_context API to signify that the default credential obtained from the current login context is to be used.

API and data structure syntax

     SQL_API_RC ( SQL_API_FN *db2secGenerateInitialCred)
                           ( const char *userid,
                             db2int32 useridlen,
                             const char *usernamespace,
                             db2int32 usernamespacelen,
                             db2int32 usernamespacetype,
                             const char *password,
                             db2int32 passwordlen,
                             const char *newpassword,
                             db2int32 newpasswordlen,
                             const char *dbname,
                             db2int32 dbnamelen,
                             gss_cred_id_t *pGSSCredHandle,
                             void          **InitInfo,
                             char          **errormsg,
                             db2int32 *errormsglen );

db2secGenerateInitialCred API parameters

userid: Input. The user ID whose password is to be verified on the database server.
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.
password: Input. The password to be verified.
passwordlen: Input. Length in bytes of the password parameter value.
newpassword: Input. A new password if the password is to be changed. If no change is requested, the newpassword parameter is set to NULL. If it is not NULL, the API should validate the old password before setting the password to its new value. The API does not have to honor 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.
newpasswordlen: Input. Length in bytes of the newpassword parameter value.
dbname: Input. The name of the database being connected to. The API is free to ignore this parameter, or the API can return the value DB2SEC_PLUGIN_CONNECTION_DISALLOWED if it has a policy of restricting access to certain databases to users who otherwise have valid passwords.
dbnamelen: Input. Length in bytes of the dbname parameter value.
pGSSCredHandle: Output. Pointer to the GSS-API credential handle.
InitInfo: Output. A pointer to data that is not known to Db2. The plug-in can use this memory to maintain a list of resources that are allocated in the process of generating the credential handle. The Db2 database manager calls the db2secFreeInitInfo API at the end of the authentication process, at which point these resources are freed. If the db2secGenerateInitialCred API does not need to maintain such a list, then it should return NULL.
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 db2secGenerateInitialCred API execution is not successful.
Note: For this API, error messages should not be created if the return value indicates a bad user ID or password. An error message should be returned only if there is an internal error in the API that prevented it from completing properly.
errormsglen: Output. A pointer to an integer that indicates the length in bytes of the error message string in errormsg parameter.