Las API de los plugins de autentificación por ID de usuario/contraseña

Para el módulo de plugins de ID de usuario/contraseña, debe implementar las API siguientes en el extremo cliente:

  • db2secClientAuthPluginInit
    Nota: La API db2secClientAuthPluginInit toma como entrada un puntero, *logMessage_fn, a una API con el prototipo siguiente:
    SQL_API_RC (SQL_API_FN db2secLogMessage) 
(
db2int32 level,
void    *data,
db2int32 length
);

    La API db2secLogMessage permite que el plugin registre mensajes en db2diag con fines de depuración o información. Esta API la proporciona el sistema de base de datos Db2® , por lo que no es necesario implementarla.

  • db2secClientAuthPluginTerm
  • db2secGenerateInitialCred (Utilizado solamente para gssapi)
  • db2secRemapUserid (Opcional)
  • db2secGetDefaultLoginContext
  • db2secValidatePassword
  • db2secProcessServerPrincipalName (Solamente para GSS-API)
  • db2secFreeToken (Funciones para liberar memoria retenida por la DLL)
  • db2secFreeErrormsg
  • db2secFreeInitInfo
  • La única API que se debe poder resolver externamente es db2secClientAuthPluginInit. Esta API tomará un parámetro void * , que se debe convertir a:
    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
);
}
    o
    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>);
  }

    Debe utilizar la estructura db2secUseridPasswordClientAuthFunctions_1 si está escribiendo un plugin de ID de usuario/contraseña. Debe utilizar la estructura db2secGssapiClientAuthFunctions_1 si está escribiendo un plugin de GSS_API (incluido Kerberos).

Para la biblioteca de plugins de autentificación por ID de usuario/contraseña, debe implementar las API siguientes en el extremo servidor:
  • db2secServerAuthPluginInit

    La API db2secServerAuthPluginInit utiliza como entrada un puntero, *logMessage_fn, que señala hacia la API db2secLogMessage, y un puntero, *getConDetails_fn, que señala hacia la API db2secGetConDetails con los prototipos siguientes:

    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
);

    La API db2secLogMessage permite que el plugin registre mensajes en db2diag con fines de depuración o información. La API db2secGetConDetails permite que el plugin obtenga detalles sobre el cliente que intenta establecer una conexión de base de datos. Tanto la API db2secLogMessage como la API db2secGetConDetails las proporciona el sistema de base de datos DB2 por lo que el usuario no necesita implementarlas. A su vez, la API db2secGetConDetails utiliza como segundo parámetro de entrada el puntero pConDetails, que señala una de las siguientes estructuras:

    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;
    Los valores posibles de conDetailsVersion son DB2SEC_CON_DETAILS_VERSION_1, DB2SEC_CON_DETAILS_VERSION_2, y DB2SEC_CON_DETAILS_VERSION_3, que representan la versión de la API.
    Nota: Al utilizar db2sec_con_details_1, db2sec_con_details_2o db2sec_con_details_3, tenga en cuenta lo siguiente:
    • Los plugins existentes que hacen uso de la estructura db2sec_con_details_1 y el valor DB2SEC_CON_DETAILS_VERSION_1 continúan funcionando de la misma forma en que lo hacían en la versión 8.2 al invocar la API db2GetConDetails. Si esta API se invoca en una plataforma IPv4, se devuelve la dirección IP del cliente en el campo clientIPAddress de la estructura. Si esta API se invoca en una plataforma IPv6, se devuelve el valor 0 en el campo clientIPAddress. Para recuperar la dirección IP del cliente en una plataforma IPv6, se debe cambiar el código del plugin de seguridad para utilizar la estructura db2sec_con_details_2 y el valor DB2SEC_CON_DETAILS_VERSION_2, o la estructura db2sec_con_details_3 y el valor DB2SEC_CON_DETAILS_VERSION_3.
    • Los nuevos plugins deben utilizar la estructura db2sec_con_details_3 y el valor DB2SEC_CON_DETAILS_VERSION_3. Si la API db2secGetConDetails se invoca en una plataforma IPv4, se devuelve la dirección IP del cliente en el campo clientIPAddress de la estructura db2sec_con_details_3; si la API se invoca en una plataforma IPv6, se devuelve la dirección IP del cliente en el campo clientIP6Address de la estructura db2sec_con_details_3. El campo clientProtocol de la estructura de detalles de la conexión se establece en uno de estos valores: SQL_PROTOCOL_TCPIP (IPv4, con v1 de la estructura), SQL_PROTOCOL_TCPIP4 (IPv4, con v2 de la estructura) o SQL_PROTOCOL_TCPIP6 (IPv6, con v2 o v3 de la estructura).
    • La estructura db2sec_con_details_3 es idéntica a la estructura db2sec_con_details_2 exceptuando que esta contiene un campo adicional (clientPlatform) que identifica el tipo de plataforma del cliente (tal como ha informado la capa de comunicaciones) mediante la utilización de las constantes de tipo de plataforma definidas en sqlmon.h, como por ejemplo SQLM_PLATFORM_AIX.
  • db2secServerAuthPluginTerm
  • db2secValidatePassword
  • db2secGetAuthIDs
  • db2secDoesAuthIDExist
  • db2secFreeToken
  • db2secFreeErrormsg
  • La única API que se debe poder resolver externamente es db2secServerAuthPluginInit. Esta API tomará un parámetro void * , que se debe convertir a:
    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;
    o
    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;

    Debe utilizar la estructura db2secUseridPasswordServerAuthFunctions_1 si está escribiendo un plugin de ID de usuario/contraseña. Debe utilizar la estructura db2secGssapiServerAuthFunctions_1 si está escribiendo un plugin de GSS_API (incluido Kerberos).