APIs for user ID/password authentication plug-ins

For the user ID/password plug-in module, you need to implement the following client-side APIs:

db2secClientAuthPluginInit
Note: The db2secClientAuthPluginInit API takes as input a pointer, *logMessage_fn, to an API with the following prototype:
```
SQL_API_RC (SQL_API_FN db2secLogMessage) 
(
db2int32 level,
void    *data,
db2int32 length
);
```
The db2secLogMessage API allows the plug-in to log messages to the db2diag log files for debugging or informational purposes. This API is provided by the Db2® database system, so you do not need to implement it.
db2secClientAuthPluginTerm
db2secGenerateInitialCred (Only used for gssapi)
db2secRemapUserid (Optional)
db2secGetDefaultLoginContext
db2secValidatePassword
db2secProcessServerPrincipalName (This is only for GSS-API)
db2secFreeToken (Functions to free memory held by the DLL)
db2secFreeErrormsg
db2secFreeInitInfo

The only API that must be resolvable externally is db2secClientAuthPluginInit. This API will take a void * parameter, which should be cast to either:

typedef struct db2secUseridPasswordClientAuthFunctions_1
{
db2int32 version;
db2int32 plugintype;
	
SQL_API_RC (SQL_API_FN * db2secGetDefaultLoginContext)
(
char        authid[DB2SEC_MAX_AUTHID_LENGTH],
db2int32   *authidlen,
char        userid[DB2SEC_MAX_USERID_LENGTH],
db2int32   *useridlen,
db2int32    useridtype,
char        usernamespace[DB2SEC_MAX_USERNAMESPACE_LENGTH],
db2int32   *usernamespacelen,
db2int32   *usernamespacetype,
const char *dbname,
db2int32    dbnamelen,
void      **token,
char      **errormsg,
db2int32   *errormsglen
);
/* Optional */
SQL_API_RC (SQL_API_FN * db2secRemapUserid)
(  
char        userid[DB2SEC_MAX_USERID_LENGTH],
db2int32   *useridlen,
char        usernamespace[DB2SEC_MAX_USERNAMESPACE_LENGTH],
db2int32   *usernamespacelen,
db2int32   *usernamespacetype,
char        password[DB2SEC_MAX_PASSWORD_LENGTH],
db2int32   *passwordlen,
char        newpassword[DB2SEC_MAX_PASSWORD_LENGTH],
db2int32   *newpasswordlen,
const char *dbname,
db2int32    dbnamelen,
char      **errormsg,
db2int32   *errormsglen
);	
  
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 *newpassword,
db2int32    newpasswordlen,
const char *dbname,
db2int32    dbnamelen,
db2Uint32   connection_details,
void      **token,
char      **errormsg,
db2int32   *errormsglen
);
  
SQL_API_RC (SQL_API_FN * db2secFreeToken)
(
void     **token,
char     **errormsg,
db2int32  *errormsglen
);
  
SQL_API_RC (SQL_API_FN * db2secFreeErrormsg)
(
char *errormsg
);
        
SQL_API_RC (SQL_API_FN * db2secClientAuthPluginTerm)
( 
char     **errormsg,
db2int32  *errormsglen
);
}

typedef struct db2secGssapiClientAuthFunctions_1
{
db2int32 version;
db2int32 plugintype;
  
SQL_API_RC (SQL_API_FN * db2secGetDefaultLoginContext) 
(
char        authid[DB2SEC_MAX_AUTHID_LENGTH],
db2int32   *authidlen,
char        userid[DB2SEC_MAX_USERID_LENGTH],
db2int32   *useridlen,
db2int32    useridtype,
char        usernamespace[DB2SEC_MAX_USERNAMESPACE_LENGTH],
db2int32   *usernamespacelen,
db2int32   *usernamespacetype,
const char *dbname,
db2int32    dbnamelen,
void      **token,
char      **errormsg,
db2int32   *errormsglen
);
  
SQL_API_RC (SQL_API_FN * db2secProcessServerPrincipalName) 
(
const void *data,
gss_name_t *gssName,
char      **errormsg,
db2int32   *errormsglen
);	

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
);	
  
SQL_API_RC (SQL_API_FN * db2secFreeToken)
(
void      *token,
char     **errormsg,
db2int32  *errormsglen
);
  
SQL_API_RC (SQL_API_FN * db2secFreeErrormsg)
(
char *errormsg
);


SQL_API_RC (SQL_API_FN * db2secFreeInitInfo)
(
void      *initInfo,
char     **errormsg,
db2int32  *errormsglen
);
  
SQL_API_RC (SQL_API_FN * db2secClientAuthPluginTerm)
(
char     **errormsg,
db2int32  *errormsglen
);
  
/* GSS-API specific functions -- refer to db2secPlugin.h 
   for parameter list*/

  OM_uint32 (SQL_API_FN * gss_init_sec_context )(<parameter list>);
  OM_uint32 (SQL_API_FN * gss_delete_sec_context )(<parameter list>);
  OM_uint32 (SQL_API_FN * gss_display_status )(<parameter list>);
  OM_uint32 (SQL_API_FN * gss_release_buffer )(<parameter list>);
  OM_uint32 (SQL_API_FN * gss_release_cred )(<parameter list>);
  OM_uint32 (SQL_API_FN * gss_release_name )(<parameter list>);
  }

You should use the db2secUseridPasswordClientAuthFunctions_1 structure if you are writing a user ID/password plug-in. If you are writing a GSS-API (including Kerberos) plug-in, you should use the db2secGssapiClientAuthFunctions_1 structure.

For the user ID/password plug-in library, you will need to implement the following server-side APIs:

db2secServerAuthPluginInit
The db2secServerAuthPluginInit API takes as input a pointer, *logMessage_fn, to the db2secLogMessage API, and a pointer, *getConDetails_fn, to the db2secGetConDetails API with the following prototypes:
```
SQL_API_RC (SQL_API_FN db2secLogMessage)
(
db2int32 level,
void    *data,
db2int32 length
);

SQL_API_RC (SQL_API_FN db2secGetConDetails)
(
db2int32    conDetailsVersion,
const void *pConDetails
);
```
The db2secLogMessage API allows the plug-in to log messages to the db2diag log files for debugging or informational purposes. The db2secGetConDetails API allows the plug-in to obtain details about the client that is trying to attempt to have a database connection. Both the db2secLogMessage API and db2secGetConDetails API are provided by the Db2 database system, so you do not need to implement them. The db2secGetConDetails API in turn, takes as its second parameter,pConDetails, a pointer to one of the following structures:
db2sec_con_details_1:
```
typedef struct db2sec_con_details_1
{
  db2int32  clientProtocol;
  db2Uint32 clientIPAddress;
  db2Uint32 connect_info_bitmap;
  db2int32  dbnameLen;
  char      dbname[DB2SEC_MAX_DBNAME_LENGTH + 1];
} db2sec_con_details_1;
```
db2sec_con_details_2:
```
typedef struct db2sec_con_details_2
{
  db2int32  clientProtocol;     /* See SQL_PROTOCOL_ in sqlenv.h */
  db2Uint32 clientIPAddress;    /* Set if protocol is TCPIP4     */
  db2Uint32 connect_info_bitmap;
  db2int32  dbnameLen;
  char dbname[DB2SEC_MAX_DBNAME_LENGTH + 1];
  db2Uint32 clientIP6Address[4];/* Set if protocol is TCPIP6     */  
} db2sec_con_details_2;
```
db2sec_con_details_3:
```
typedef struct db2sec_con_details_3
{
  db2int32 clientProtocol; /* See SQL_PROTOCOL_ in sqlenv.h */
  db2Uint32 clientIPAddress; /* Set if protocol is TCPIP4 */
  db2Uint32 connect_info_bitmap;
  db2int32 dbnameLen;
  char dbname[DB2SEC_MAX_DBNAME_LENGTH + 1];
  db2Uint32 clientIP6Address[4];/* Set if protocol is TCPIP6 */
  db2Uint32 clientPlatform; /* SQLM_PLATFORM_* from sqlmon.h */
  db2Uint32 _reserved[16];
} db2sec_con_details_3;
```
The possible values for conDetailsVersion are DB2SEC_CON_DETAILS_VERSION_1, DB2SEC_CON_DETAILS_VERSION_2, and DB2SEC_CON_DETAILS_VERSION_3 representing the version of the API.
Note: While using db2sec_con_details_1, db2sec_con_details_2, or db2sec_con_details_3, consider the following:
- Existing plugins that are using the db2sec_con_details_1 structure and the DB2SEC_CON_DETAILS_VERSION_1 value will continue to work as they did with Version 8.2 when calling the db2GetConDetails API. If this API is called on an IPv4 platform, the client IP address is returned in the clientIPAddress field of the structure. If this API is called on an IPv6 platform, a value of 0 is returned in the clientIPAddress field. To retrieve the client IP address on an IPv6 platform, the security plug-in code should be changed to use either the db2sec_con_details_2 structure and the DB2SEC_CON_DETAILS_VERSION_2 value, or the db2sec_con_details_3 structure and the DB2SEC_CON_DETAILS_VERSION_3 value.
- New plugins should use the db2sec_con_details_3 structure and the DB2SEC_CON_DETAILS_VERSION_3 value. If the db2secGetConDetails API is called on an IPv4 platform, the client IP address is returned in the clientIPAddress field of the db2sec_con_details_3 structure and if the API is called on an IPv6 platform the client IP address is returned in the clientIP6Address field of the db2sec_con_details_3 structure. The clientProtocol field of the connection details structure will be set to one of SQL_PROTOCOL_TCPIP (IPv4, with v1 of the structure), SQL_PROTOCOL_TCPIP4 (IPv4, with v2 of the structure) or SQL_PROTOCOL_TCPIP6 (IPv6, with v2 or v3 of the structure).
- The structure db2sec_con_details_3 is identical to the structure db2sec_con_details_2 except that it contains an additional field (clientPlatform) that identifies the client platform type (as reported by the communication layer) using platform type constants defined in sqlmon.h, such as SQLM_PLATFORM_AIX.
db2secServerAuthPluginTerm
db2secValidatePassword
db2secGetAuthIDs
db2secDoesAuthIDExist
db2secFreeToken
db2secFreeErrormsg

The only API that must be resolvable externally is db2secServerAuthPluginInit. This API will take a void * parameter, which should be cast to either:

typedef struct db2secUseridPasswordServerAuthFunctions_1
{
db2int32 version;
db2int32 plugintype;
  
  /* parameter lists left blank for readability
	   see above for parameters */
SQL_API_RC (SQL_API_FN * db2secValidatePassword)(<parameter list>);
SQL_API_RC (SQL_API_FN * db2secGetAuthIDs)(<parameter list);
SQL_API_RC (SQL_API_FN * db2secDoesAuthIDExist)(<parameter list>);
SQL_API_RC (SQL_API_FN * db2secFreeToken)(<parameter list>);
SQL_API_RC (SQL_API_FN * db2secFreeErrormsg)(<parameter list>);
SQL_API_RC (SQL_API_FN * db2secServerAuthPluginTerm)();
} userid_password_server_auth_functions;

typedef struct db2secGssapiServerAuthFunctions_1
{
db2int32 version;
db2int32 plugintype;
gss_buffer_desc serverPrincipalName;
gss_cred_id_t ServerCredHandle;
SQL_API_RC (SQL_API_FN * db2secGetAuthIDs)(<parameter list);
SQL_API_RC (SQL_API_FN * db2secDoesAuthIDExist)(<parameter list>);
SQL_API_RC (SQL_API_FN * db2secFreeErrormsg)(<parameter list>);
SQL_API_RC (SQL_API_FN * db2secServerAuthPluginTerm)();
  
/* GSS-API specific functions
refer to db2secPlugin.h for parameter list*/
OM_uint32 (SQL_API_FN * gss_accept_sec_context )(<parameter list>);
OM_uint32 (SQL_API_FN * gss_display_name )(<parameter list>);
OM_uint32 (SQL_API_FN * gss_delete_sec_context )(<parameter list>);
OM_uint32 (SQL_API_FN * gss_display_status )(<parameter list>);
OM_uint32 (SQL_API_FN * gss_release_buffer )(<parameter list>);
OM_uint32 (SQL_API_FN * gss_release_cred )(<parameter list>);
OM_uint32 (SQL_API_FN * gss_release_name )(<parameter list>);
	
} gssapi_server_auth_functions;

You should use the db2secUseridPasswordServerAuthFunctions_1 structure if you are writing a user ID/password plug-in. If you are writing a GSS-API (including Kerberos) plug-in, you should use the db2secGssapiServerAuthFunctions_1 structure.