Descripción detallada

Gestión de sesiones de cliente con HSM.

Gestión de sesiones de cliente con HSM. Más...

Definiciones y macros
#define	DN_INIT_PARAM_CONF_FAST_FAIL (128)

Funciones
int AAP_API	DInitialise (DWORD dwReserved)

int AAP_API	DSetLBList (DWORD dwParam, void *pvList, DWORD dwListCount, DWORD dwReserved)

int AAP_API	DGetLBList (DWORD dwParam, void pvList, DWORD pdwListCount, DWORD dwReserved)

int AAP_API	DOpenSession (HSESSIONCTX phSession, DWORD dwParam, BYTE pbData, DWORD dwDataLen, DWORD dwFlags)

int AAP_API	DSetSessionParam (HSESSIONCTX hSession, DWORD dwParam, BYTE *pbData, DWORD dwDataLen, DWORD dwFlags)

int AAP_API	DGetSessionParam (HSESSIONCTX hSession, DWORD dwParam, BYTE pbData, DWORD pdwDataLen, DWORD dwFlags)

int AAP_API	DCloseSession (HSESSIONCTX *phSession, DWORD dwFlags)

int AAP_API	DFinalise ()

Definiciones y macros

◆ DN_INIT_PARAM_CONF_FAST_FAIL

#define DN_INIT_PARAM_CONF_FAST_FAIL (128)

#include <dinamo.h>

Configuración para fallo rápido.

Funciones

◆ DInicializar()

int AAP_API DInitialize ( DWORD dwReservado )

#include <dinamo.h>

Inicializa las bibliotecas cliente Dinamo y las prepara para su uso. Debe invocarse antes que cualquier otra función.

Parámetros

[en] dwReservado Reservado para uso futuro (debe ser 0).

Devolución: 0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Notas: Esta función sólo debe llamarse una vez en cada instancia del programa que carga las librerías. Y antes de que finalice el programa, debe llamarse a la función DFinalize().

Ejemplos: ckd_bchain.c, connect_hsm.c, create_hash.c, crypt_sym.c, download_log.c, eft_validate_cvv.c, export_import_tr31.c, gen_check_oath.c, gen_csr.c, gen_dukpt.c, gen_ecdh.c, gen_xecdh.c, get_hsm_info.c, get_key_info_bchain.c, get_pub_key_bchain.c, get_rt_logs.c, import_export.c, import_export_bchain.c, key_add_remove.c, key_attribute.c, list_keys.c, m_of_n.c, pin_block_translate.c, pkcs7_sign.c, post_put_get_delete_pix.c, sign_check_pix_jws.c, sign_verify.c, sign_verify_bchain.c, sign_verify_dict.c, sign_verify_eddsa.c, sign_verify_pix.c, sign_verify_xml.c, skeep_new_split_recover.c, skeep_probe_match.c, spb_activate_cert.c, spb_enc_dec.c, spb_gen_key_csr.c, spb_get_cert.c, spb_import_p12.c, tokenisation.c, user_add_remove.c, user_otp.c y verify_pin_block.c.

◆ DSetLBList()

int AAP_API DSetLBList	(	DWORD	dwParam,
		vacío *	pvList,
		DWORD	dwListCount,
		DWORD	dwReservado )

#include <dinamo.h>

Define la lista de equilibrio de carga. Esta configuración se realiza en tiempo real.

Parámetros

[en]

dwParam

Especifica cómo se definirá el equilibrio de carga y, en consecuencia, la estructura de datos pasada en el parámetro pvList.

Valor	Significado
DN_LB_LIST	Tipo de pvList: LISTA_BALANCE_CARGA. Defina una o varias listas de equilibrado. Todos los campos de la estructura deben estar rellenados. Pasar la matriz de listas. El número de elementos debe introducirse en `dwListCount` hasta un máximo de DN_MAX_LB_SETS. El número de estructuras HSM_ADDR definido por lista debe ser como máximo DN_MAX_LB_HSM_COUNT.

[en] pvList Puntero a los datos o estructuras especificados en dwParam.

[en] dwListCount Número de listas transmitidas pvList.

[en] dwReservado Reservado para uso futuro (debe ser 0).

Devolución: 0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Notas: Al definir el equilibrio de carga, las sesiones antiguas se cerrarán físicamente en cuanto se cierren. Se crearán nuevas sesiones utilizando las definiciones de la nueva lista de equilibrado. Si la lista definida es exactamente la misma que la lista en ejecución, la lista de equilibrado no se actualizará.
Esta función activará el equilibrio de carga incluso si la variable de equilibrio de carga no está activada.

◆ DGetLBList()

int AAP_API DGetLBList	(	DWORD	dwParam,
		vacío *	pvList,
		DWORD *	pdwListCount,
		DWORD	dwReservado )

#include <dinamo.h>

Recupera la lista de balanceadores de carga en ejecución.

Parámetros

[en]

dwParam

Especifica cómo se realizará la recuperación del equilibrio de carga y, en consecuencia, la estructura de datos pasada en el parámetro pvList.

Valor	Significado
DN_LB_LIST	Tipo de pvList: LISTA_BALANCE_CARGA. Recibe una o varias listas de equilibrado. El número de listas debe ser igual o superior al número de listas en ejecución. El número de elementos debe introducirse en `dwListCount`. El número de estructuras HSM_ADDR definido por lista debe ser DN_MAX_LB_HSM_COUNT.

[en] pvList Puntero a los datos o estructuras especificados en dwParam. Puede ser NULL para recuperar el número de listas configuradas.

[in,out] pdwListCount La entrada debe contener el número de listas pasadas en pvList. La salida contendrá el número de listas escritas en pvList. Caso pvList es NULL este parámetro recibirá el número de listas esperado.

[en] dwReservado Reservado para uso futuro (debe ser 0).

Devolución: 0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

◆ DOpenSession()

int AAP_API DOpenSession	(	HSESSIONCTX *	phSession,
		DWORD	dwParam,
		BYTE *	pbData,
		DWORD	dwDataLen,
		DWORD	dwFlags )

#include <dinamo.h>

Establece una sesión con Dinamo y devuelve un contexto que utilizarán las demás funciones.

Parámetros

[fuera] phSession Puntero al contexto de sesión. Tras su uso debe liberarse con la función DCloseSession().

[en]

dwParam

Especifica cómo se autenticará la sesión y, en consecuencia, la estructura de datos pasada en el parámetro pbData.

Valor	Significado
SS_USER_PWD	Tipo de pbData: AUTH_PWD Autenticación por usuario y contraseña. Deben rellenarse todos los campos de la estructura.
SS_USR_PWD_EX	Tipo de pbData: AUTH_PWD_EX Autenticación por usuario y contraseña con OTP/Certificado opcional. Se deben rellenar todos los campos de la estructura, solo los de Autenticación Fuerte son opcionales.
SS_ATOKEN	Tipo de pbData: AUTH_ATOKEN Autenticación mediante tokens de acceso. Deben rellenarse todos los campos de la estructura. Consulte la API DManageAToken() para obtener información sobre la gestión de tokens de sesión(Access Tokens).
SS_ANONIMOS	Tipo de pbData: AUTH_PWD_EX o AUTH_PWD Sin autenticación. Sólo deben rellenarse los campos szAddr y nPort de la estructura. En el caso de AUTH_PWD_EX, rellene dwAuthType con SA_AUTH_NONE.
SS_HTTP	Tipo de pbData: AUTH_HTTP Autenticación a través de HTTP en Dinamo Services. Deben rellenarse todos los campos de la estructura. No implementado.
SS_WIN_CREDENTIAL	Tipo de pbData: AUTH_WIN_CREDENTIAL. Deben rellenarse todos los campos de la estructura.

[en] pbData Puntero a los datos o estructuras especificados en dwParam.

[en] dwDataLen Tamaño de los datos o de la estructura especificada en dwParam.

[en]

dwFlags

Cambia ciertos comportamientos de la función, puede ser cero.

Valor	Significado
ENCRYPTED_CONN	Establece una sesión cifrada (TLS v1.2). Los datos viajarán en texto claro si no se especifica esta bandera.
USUARIO_INTERACTIVO	Muestra un diálogo para que el usuario introduzca su identificador (ID) y contraseña o la ruta del archivo que contiene su clave privada y certificado digital. Aún no es compatible.
LB_BYPASS	Ignora las configuraciones de equilibrio de carga. Establecimiento de una sesión en la dirección HSM indicada mediante `pbData`.
CACHE_BYPASS	Ignora la configuración de la caché de sesión y abre esta sesión sin pasar por la caché de sesión.
DS_BYPASS	Ignora la configuración de la sesión Dinamo Services.

Devolución: 0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Notas: El contexto devuelto por esta función debe utilizarse en todas las llamadas posteriores al HSM y liberarse mediante la función DCloseSession() una vez utilizado. En esta llamada se establece una conexión TCP que finaliza cuando se libera el contexto.

: La sesión se establece en texto claro (sin cifrado) si no se especifica el indicador ENCRYPTED_CONN; en caso contrario, se cierra un túnel TLS v1.2 entre los dos extremos del canal.

: Dinamo incorpora de forma nativa un sistema de equilibrio de carga y caché de sesión. Si el balanceo de carga está activo y necesitas asegurarte de que una sesión se abre en una dirección IP específica, utiliza la bandera LB_BYPASS. Con LB_BYPASS la función DOpenSession ignorará la lista de direcciones de balanceo de carga. No es posible desactivar o eludir la caché de sesión del dispositivo utilizando esta o cualquier otra función de la API.

: Cuando la contraseña de un usuario ha caducado, la función devolverá D_ERR_PWD_EXPIRED. En este caso, se devolverá un manejador de sesión válido, que sólo podrá utilizarse para cambiar la contraseña del usuario autenticado. Si el cambio de contraseña tiene éxito, la sesión tendrá habilitadas las demás funciones. Si el cambio de contraseña falla o si la sesión intenta realizar cualquier otra operación, el servidor desconectará la sesión.

Observación: Las sesiones de HSM tienen afinidad sesión-hilo. Esto significa que la misma sesión no puede ser utilizada por varios hilos al mismo tiempo.

Ejemplos: ckd_bchain.c, connect_hsm.c, create_hash.c, crypt_sym.c, download_log.c, eft_validate_cvv.c, export_import_tr31.c, gen_check_oath.c, gen_csr.c, gen_dukpt.c, gen_ecdh.c, gen_xecdh.c, get_hsm_info.c, get_key_info_bchain.c, get_pub_key_bchain.c, get_rt_logs.c, import_export.c, import_export_bchain.c, key_add_remove.c, key_attribute.c, list_keys.c, m_of_n.c, pin_block_translate.c, pkcs7_sign.c, post_put_get_delete_pix.c, sign_check_pix_jws.c, sign_verify.c, sign_verify_bchain.c, sign_verify_dict.c, sign_verify_eddsa.c, sign_verify_pix.c, sign_verify_xml.c, skeep_new_split_recover.c, skeep_probe_match.c, spb_activate_cert.c, spb_enc_dec.c, spb_gen_key_csr.c, spb_get_cert.c, spb_import_p12.c, tokenisation.c, user_add_remove.c, user_otp.c y verify_pin_block.c.

◆ DSetSessionParam()

int AAP_API DSetSessionParam	(	HSESSIONCTX	hSesión,
		DWORD	dwParam,
		BYTE *	pbData,
		DWORD	dwDataLen,
		DWORD	dwFlags )

#include <dinamo.h>

Modifica los parámetros de la sesión.

Parámetros

[en] hSesión Contexto adquirido a través de la función DOpenSession().

[en]

dwParam

Especifica el parámetro de sesión que se va a configurar y, en consecuencia, la estructura de datos que se pasa en el parámetro pbData.

Valor	Significado
SP_SESSION_TIMEOUT	Tipo de `pbData:` DWORD Tiempo de espera global de la sesión en milisegundos. Este valor de tiempo de espera sólo se aplica al cliente. . Aún no se admite.
SP_SEND_TIMEOUT	Tipo de `pbData:` DWORD Tiempo de espera en milisegundos para la función de envío del subsistema de red.
SP_RECV_TIMEOUT	Tipo de `pbData:` DWORD Tiempo de espera en milisegundos para la función recv del subsistema de red.

[en] pbData Puntero a los datos o estructuras especificados en dwParam.

[en] dwDataLen Tamaño de los datos o de la estructura especificada en dwParam.

[en] dwFlags Reservado para uso futuro (debe ser 0).

Devolución: 0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

◆ DGetSessionParam()

int AAP_API DGetSessionParam	(	HSESSIONCTX	hSesión,
		DWORD	dwParam,
		BYTE *	pbData,
		DWORD *	pdwDataLen,
		DWORD	dwFlags )

#include <dinamo.h>

Recuperar parámetros de sesión.

Parámetros

[en] hSesión Contexto adquirido a través de la función DOpenSession().

[en]

dwParam

Consulte dwParam en DSetSessionParam(). Otros dwParamDGetSessionParam:

Valor	Significado
SP_SESSION_ID	Tipo de `pbData:` DWORD Identificador de la sesión en el servidor. Aún no se admite.
SP_SESSION_CIPHER	Tipo de `pbData:` char * Algoritmos negociados en la sesión TLS. Tamaño máximo MAX_CHANNEL_CIPHER_NAME_LEN
SP_SESSION_PIX_HTTP_RET	Tipo de `pbData:` largo * Código de respuesta HTTP de la última petición PIX HTTP (POST, GET...) realizada en esta sesión. Esta operación debe llamarse inmediatamente después de llamar a la API de petición PIX. Debe llamarse utilizando la misma sesión. No realice ninguna otra operación entre estas llamadas.
SP_SESSION_PIX_HTTP_REQ_DETAILS	Tipo de `pbData:` PIX_HTTP_REQUEST_DETAILS * Detalles de la última petición PIX HTTP (POST, GET...) realizada en esta sesión. Esta operación debe llamarse inmediatamente después de llamar a la API de petición PIX. Debe llamarse utilizando la misma sesión. No realice otras operaciones entre estas llamadas.
SP_HSM_OP_MODE	Tipo de `pbData:` DWORD * Modo de funcionamiento del HSM. Puede tener los valores DN_HSM_OP_NRM, DN_HSM_OP_RM1, DN_HSM_OP_RM2 etc.

[fuera] pbData Puntero a los datos o estructuras especificados en dwParam. Este parámetro puede ser NULL para especificar la cantidad de memoria necesaria.

[in,out] pdwDataLen Puntero al tamaño del búfer, en bytes, especificado en pbData. Cuando la función retorne, este parámetro contendrá el tamaño de los datos almacenados en pbData.

[en] dwFlags Reservado para uso futuro (debe ser 0).

Devolución: 0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

◆ DCloseSession()

int AAP_API DCloseSession	(	HSESSIONCTX *	phSession,
		DWORD	dwFlags )

#include <dinamo.h>

Finaliza una sesión con Dinamo y libera su contexto.

Parámetros

[in,out] phSession Puntero al contexto de sesión. Cuando la función devuelva este parámetro, será igual a NULL.

[en]

dwFlags

Cambia ciertos comportamientos de la función, puede ser cero.

Valor	Significado
CERRAR_FÍSICAMENTE	Fuerza el cierre físico de la sesión. Si la sesión está en caché, se eliminará de la caché y se cerrará físicamente.

Devolución: 0 (CERO) si la función tiene éxito.
Consulte la sección Códigos de retorno para conocer otros valores.

Notas: El contexto de sesión, una vez liberado, deja de ser válido para su uso en cualquier otra función. Si se vuelve a utilizar el contexto, la función devolverá el código de error D_INVALID_CONTEXT.

Ejemplos: ckd_bchain.c, connect_hsm.c, create_hash.c, crypt_sym.c, download_log.c, eft_validate_cvv.c, export_import_tr31.c, gen_check_oath.c, gen_csr.c, gen_dukpt.c, gen_ecdh.c, gen_xecdh.c, get_hsm_info.c, get_key_info_bchain.c, get_pub_key_bchain.c, get_rt_logs.c, import_export.c, import_export_bchain.c, key_add_remove.c, key_attribute.c, list_keys.c, m_of_n.c, pin_block_translate.c, pkcs7_sign.c, post_put_get_delete_pix.c, sign_check_pix_jws.c, sign_verify.c, sign_verify_bchain.c, sign_verify_dict.c, sign_verify_eddsa.c, sign_verify_pix.c, sign_verify_xml.c, skeep_new_split_recover.c, skeep_probe_match.c, spb_activate_cert.c, spb_enc_dec.c, spb_gen_key_csr.c, spb_get_cert.c, spb_import_p12.c, tokenisation.c, user_add_remove.c, user_otp.c y verify_pin_block.c.

◆ DFinalizar()

int AAP_API DFinalise ( )

#include <dinamo.h>

Finaliza las bibliotecas cliente Dinamo.

Devolución: 0 (CERO)

Notas: Esta función sólo debe llamarse una vez al final del programa. Después de su ejecución, cualquier otra función llamada tendrá un comportamiento indefinido.

Ejemplos: ckd_bchain.c, connect_hsm.c, create_hash.c, crypt_sym.c, download_log.c, eft_validate_cvv.c, export_import_tr31.c, gen_check_oath.c, gen_csr.c, gen_dukpt.c, gen_ecdh.c, gen_xecdh.c, get_hsm_info.c, get_key_info_bchain.c, get_pub_key_bchain.c, get_rt_logs.c, import_export.c, import_export_bchain.c, key_add_remove.c, key_attribute.c, list_keys.c, m_of_n.c, pin_block_translate.c, pkcs7_sign.c, post_put_get_delete_pix.c, sign_check_pix_jws.c, sign_verify.c, sign_verify_bchain.c, sign_verify_dict.c, sign_verify_eddsa.c, sign_verify_pix.c, sign_verify_xml.c, skeep_new_split_recover.c, skeep_probe_match.c, spb_activate_cert.c, spb_enc_dec.c, spb_gen_key_csr.c, spb_get_cert.c, spb_import_p12.c, tokenisation.c, user_add_remove.c, user_otp.c y verify_pin_block.c.