Sesión

Descripción detallada

Gestión de sesiones de cliente con HSM.

Véase Documentación técnica de HSM.

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

dwReserved

)

#include <dinamo.h>

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

Parámetros

[in]

dwReserved

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, crypt_sym_gcm.c, crypt_sym_gcm_iv_auto .c, download_log.c, eft_calc_arpc.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, pqc_kem_encaps_decaps.c, pqc_kem_encaps_decaps_persistent. c, sc_change_pin .c, sc_copy_set.c, sc_create_svmk. c, sc_erase . c, sc_get_set_label.c, sc_inspect.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_pqc_ml_dsa.c, sign_verify_pqc_slh_dsa.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,
		void *	pvList,
		DWORD	dwListCount,
		DWORD	dwReserved )

#include <dinamo.h>

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

Parámetros

[in]	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: LOAD_BALANCE_LIST. Define una o varias listas de saldos. Todos los campos de la estructura deben estar rellenados. Pasa el array 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 definidas por lista debe ser como máximo DN_MAX_LB_HSM_COUNT.
[in]	pvList	Puntero a los datos o estructuras especificados en dwParam.
[in]	dwListCount	Número de listas pasadas en pvList.
[in]	dwReserved	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

Cuando se define 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,
		void *	pvList,
		DWORD *	pdwListCount,
		DWORD	dwReserved )

#include <dinamo.h>

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

Parámetros

[in]	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: LOAD_BALANCE_LIST. Recibe una o varias listas de equilibrado. El número de listas debe ser igual o mayor que el número de listas en ejecución. El número de elementos debe introducirse en dwListCount. El número de estructuras HSM_ADDR definidas por lista debe ser DN_MAX_LB_HSM_COUNT.
[in]	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 contendrá el número de listas pasadas a pvList. La salida contendrá el número de listas escritas en pvList. Si pvList es NULL, este parámetro recibirá el número de listas esperado.
[in]	dwReserved	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>

Dinamo Establece una sesión con y devuelve un contexto que será utilizado por todas las demás funciones.

Parámetros

[out]	phSession	Puntero al contexto de sesión. Tras su uso debe liberarse con la función DCloseSession().
[in]	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 Dinamo Autenticación a través de HTTP en los servicios. 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.
[in]	pbData	Puntero a los datos o estructuras especificados en dwParam.
[in]	dwDataLen	Tamaño de los datos o de la estructura especificada en dwParam.
[in]	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 Dinamo Ignora la configuración de la sesión Servicios.

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 cuenta de forma nativa con 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, crypt_sym_gcm.c, crypt_sym_gcm_iv_auto.c, download_log.c, eft_calc_arpc .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, pqc_kem_encaps_decaps .c, pqc_kem_encaps_decaps_persistent .c, sc_copy_set. c, sc_create_svmk . 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_pqc_ml_dsa.c, sign_verify_pqc_slh_dsa.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	hSession,
		DWORD	dwParam,
		BYTE *	pbData,
		DWORD	dwDataLen,
		DWORD	dwFlags )

#include <dinamo.h>

Modifica los parámetros de la sesión.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	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 soportado. 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.
[in]	pbData	Puntero a los datos o estructuras especificados en dwParam.
[in]	dwDataLen	Tamaño de los datos o de la estructura especificada en dwParam.
[in]	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	hSession,
		DWORD	dwParam,
		BYTE *	pbData,
		DWORD *	pdwDataLen,
		DWORD	dwFlags )

#include <dinamo.h>

Recuperar parámetros de sesión.

Parámetros

[in]	hSession	Contexto adquirido a través de la función DOpenSession().
[in]	dwParam	Consulte dwParam en DSetSessionParam(). Otros dwParamDGetSessionParam: Valor Significado SP_SESSION_ID Tipo de pbData: DWORD Identificador de sesión de servidor. Aún no soportado. 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: long * PIX Código de respuesta HTTP de la última petición HTTP (POST, GET...) realizada en esta sesión. PIX Esta operación debe llamarse inmediatamente después de llamar a la API de petición. Debe llamarse utilizando la misma sesión. No realice ninguna otra operación entre estas llamadas. SP_SESSION_PIX_HTTP_REQ_DETAILS PIXTipo de pbData: _HTTP_REQUEST_DETAILS * PIX Detalles de la última petición HTTP (POST, GET...) realizada en esta sesión. PIX Esta operación debe llamarse inmediatamente después de llamar a la API de peticiones. Debe llamarse utilizando la misma sesión. No realice ninguna otra operación 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.
[out]	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 regresa, este parámetro contendrá el tamaño de los datos almacenados en pbData.
[in]	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>

Dinamo Finaliza una sesión 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.
[in]	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, crypt_sym_gcm.c, crypt_sym_gcm_iv_auto.c, download_log.c, eft_calc_arpc .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, pqc_kem_encaps_decaps .c, pqc_kem_encaps_decaps_persistent .c, sc_copy_set. c, sc_create_svmk . 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_pqc_ml_dsa.c, sign_verify_pqc_slh_dsa.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 DFinalize

(

)

#include <dinamo.h>

DinamoFinaliza las bibliotecas de clientes .

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, crypt_sym_gcm.c, crypt_sym_gcm_iv_auto .c, download_log.c, eft_calc_arpc.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, pqc_kem_encaps_decaps.c, pqc_kem_encaps_decaps_persistent. c, sc_change_pin .c, sc_copy_set.c, sc_create_svmk. c, sc_erase . c, sc_get_set_label.c, sc_inspect.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_pqc_ml_dsa.c, sign_verify_pqc_slh_dsa.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.