Sessão

Descrição detalhada

Gerência de sessões cliente com o HSM.

Consulte a documentação técnica do HSM.

Definições e Macros
#define	DN_INIT_PARAM_CONF_FAST_FAIL   (128)

Funções
int AAP_API	DInitialize (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	DFinalize ()

Definições e macros

DN_INIT_PARAM_CONF_FAST_FAIL

#define DN_INIT_PARAM_CONF_FAST_FAIL   (128)

#include <dinamo.h>

Configuração para falha rápida.

Funções

DInitialize()

int AAP_API DInitialize

(

DWORD

dwReserved

)

#include <dinamo.h>

Inicializa as bibliotecas cliente Dinamo e as deixa prontas para uso. Deve ser chamada antes de qualquer outra função.

Parâmetros

[in]

dwReserved

Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

Essa função deverá ser chamada apenas uma vez em cada instância do programa que carrega as bibliotecas. E antes da finalização do programa a função DFinalize() deve ser chamada.

Exemplos

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, tokenization.c, user_add_remove.c, user_otp.c e verify_pin_block.c.

DSetLBList()

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

#include <dinamo.h>

Define a lista de balanceamento de carga. Esta configuração é feita em tempo real.

Parâmetros

[in]	dwParam	Especifica como a definição do balanceamento de carga será feita e por conseqüência a estrutura de dados passada no parâmetro pvList. Valor Signficado DN_LB_LIST Tipo de pvList: LOAD_BALANCE_LIST. Define uma ou mais listas de balanceamento. Todos os campos da estrutura devem ser preenchidos. Passar o array das listas. A quantidade de itens deve ser informado em dwListCount até o máximo de DN_MAX_LB_SETS. A quantidade de estruturas HSM_ADDR definidas por lista deverá ser no máximo DN_MAX_LB_HSM_COUNT.
[in]	pvList	Ponteiro para os dados ou estruturas especificados em dwParam.
[in]	dwListCount	Quantidade de listas passadas em pvList.
[in]	dwReserved	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

Ao definir o balanceamento de carga o as sessões antigas serão fechadas fisicamente assim que forem sendo fechadas. As novas sessões serão criadas utilizando as definições da nova lista de balanceamento. Caso a lista definida seja exatamente igual a lista em execução, a lista de balanceamento não será atualizada.
Esta função irá habilitar o balanceamento de carga mesmo que a variável de balanceamento de carga não esteja habilitada.

DGetLBList()

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

#include <dinamo.h>

Recupera a lista de balanceamento de carga em execução.

Parâmetros

[in]	dwParam	Especifica como a recuperação do balanceamento de carga será feita e por conseqüência a estrutura de dados passada no parâmetro pvList. Valor Signficado DN_LB_LIST Tipo de pvList: LOAD_BALANCE_LIST. Recebe uma ou mais listas de balanceamento. A quantidade de listas deve ser igual ou maior do que a quantidade de listas em execução. A quantidade de itens deve ser informado em dwListCount. A quantidade de estruturas HSM_ADDR definidas por lista deverá ser DN_MAX_LB_HSM_COUNT.
[in]	pvList	Ponteiro para os dados ou estruturas especificados em dwParam. Pode ser NULL para recuperar a quantidade de listas configuradas.
[in,out]	pdwListCount	Como entrada deve conter a quantidade de listas passadas em pvList. Como saída conterá a quantidade de listas escritas em pvList. Caso pvList seja NULL este parâmetro receberá a quantidade de listas esperadas.
[in]	dwReserved	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

DOpenSession()

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

#include <dinamo.h>

Estabelece uma sessão com o Dinamo e retorna um contexto que deverá ser usado por todas outras funções.

Parâmetros

[out]	phSession	Ponteiro para o contexto da sessão. Depois do seu uso deverá ser liberado com a função DCloseSession().
[in]	dwParam	Especifica como a autenticação da sessão será feita e por conseqüência a estrutura de dados passada no parâmetro pbData. Valor Signficado SS_USER_PWD Tipo de pbData: AUTH_PWD Autenticação por usuário e senha. Todos os campos da estrutura devem ser preenchidos. SS_USR_PWD_EX Tipo de pbData: AUTH_PWD_EX Autenticação por usuário e senha com OTP/Certificado opcional. Todos os campos da estrutura devem ser preenchidos, apenas os campos de Autenticação forte são opcionais. SS_ATOKEN Tipo de pbData: AUTH_ATOKEN Autenticação por Access Tokens. Todos os campos da estrutura devem ser preenchidos. Veja a API DManageAToken() para informações sobre gerência de tokens de sessão (Access Tokens). SS_ANONYMOUS Tipo de pbData: AUTH_PWD_EX ou AUTH_PWD Sem autenticação. Apenas os campos szAddr e nPort da estrutura devem ser preenchidos. No caso de AUTH_PWD_EX preencher dwAuthType com SA_AUTH_NONE. SS_HTTP Tipo de pbData: AUTH_HTTP Autenticação via HTTP na Dinamo Services. Todos os campos da estrutura devem ser preenchidos. Não implementado. SS_WIN_CREDENTIAL Tipo de pbData: AUTH_WIN_CREDENTIAL. Todos os campos da estrutura devem ser preenchidos.
[in]	pbData	Ponteiro para os dados ou estruturas especificados em dwParam.
[in]	dwDataLen	Tamanho dos dados ou estrutura especificados em dwParam.
[in]	dwFlags	Altera determinados comportamentos da função, pode ser zero. Valor Signficado ENCRYPTED_CONN Estabelece uma sessão cifrada (TLS v1.2). Os dados trafegarão em texto claro se essa flag não for especificada. USER_INTERACTIVE Apresenta um diálogo para que o usuário entre com o seu identificador (ID) e a sua senha ou o caminho do arquivo contendo a sua chave privada e o seu certificado digital. Ainda não suportada. LB_BYPASS Ignora as configurações de balanceamento de carga. Estabelecendo sessão no endereço do HSM indicado por intermédio de pbData. CACHE_BYPASS Ignora as configurações de cache de sessões e abre esta sessão sem passar pelo cache de sessões. DS_BYPASS Ignora as configurações de sessão Dinamo Services.

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

O contexto retornado por essa função deverá ser usado em todas outras chamadas subseqüentes ao HSM e liberado através da função DCloseSession() após o seu uso. Uma conexão TCP é estabelecida nessa chamada e encerrada quando o contexto é liberado.

A sessão é estabelecida em texto claro (sem criptografia) se a flag ENCRYPTED_CONN não for especificada, caso contrário, um túnel TLS v1.2 é fechado entre as duas pontas do canal.

O Dinamo apresenta nativamente um sistema de balanceamento de carga e cache de sessões. Caso o balanceamento de carga esteja ativo e seja necessário garantir uma abertura de sessão em endereço IP específico, utilize o flag LB_BYPASS. Com LB_BYPASS a função DOpenSession irá ignorar a lista de endereços do balanceamento de carga. Não é possível desabilitar ou ignorar por intermédio desta ou outra função de API o cache de sessões do equipamento.

Quando a senha de um usuário estiver expirada a função retornará D_ERR_PWD_EXPIRED. Neste caso, será retornado um handle de sessão válido que poderá ser utilizado apenas para a troca de senha do usuário autenticado. Caso a troca de senha seja feita com sucesso a sessão terá as outras funções habilitadas, caso falhe a troca de senha ou tente fazer qualquer outra operação a sessão será desconectada pelo servidor.

Observação

As sessões do HSM possuem afinidade sessão-thread. O que significa que a mesma sessão não pode ser utilizada em várias threads ao mesmo tempo.

Exemplos

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, tokenization.c, user_add_remove.c, user_otp.c e verify_pin_block.c.

DSetSessionParam()

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

#include <dinamo.h>

Altera os parâmetros da sessão.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	dwParam	Especifica o parâmetro da sessão que deve ser configurado e por conseqüência a estrutura de dados passados no parâmetro pbData. Valor Signficado SP_SESSION_TIMEOUT Tipo de pbData: DWORD Timeout global da sessão em milissegundos. Este valor de timeout se aplica apenas ao cliente. . Ainda não suportado. SP_SEND_TIMEOUT Tipo de pbData: DWORD Tempo limite em milissegundos para a função send do subsistema de rede. SP_RECV_TIMEOUT Tipo de pbData: DWORD Tempo limite em milissegundos para a função recv do subsistema de rede.
[in]	pbData	Ponteiro para os dados ou estruturas especificados em dwParam.
[in]	dwDataLen	Tamanho dos dados ou estrutura especificados em dwParam.
[in]	dwFlags	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

DGetSessionParam()

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

#include <dinamo.h>

Recupera parâmetros da sessão.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	dwParam	Consulte dwParam em DSetSessionParam(). Outros valores de dwParam, exclusivos de DGetSessionParam: Valor Signficado SP_SESSION_ID Tipo de pbData: DWORD Identificador da sessão no servidor. Ainda não suportado. SP_SESSION_CIPHER Tipo de pbData: char * Algoritmos negociados na sessão TLS. Tamanho máximo MAX_CHANNEL_CIPHER_NAME_LEN SP_SESSION_PIX_HTTP_RET Tipo de pbData: long * Código de resposta HTTP da última requisição PIX HTTP (POST, GET...) feita nesta sessão. Esta operação deve ser chamada logo após a chamada da API de requisição PIX. Deve ser chamada utilizando a mesma sessão. Não fazer outras operações entre estas chamadas. SP_SESSION_PIX_HTTP_REQ_DETAILS Tipo de pbData: PIX_HTTP_REQUEST_DETAILS * Detalhes da última requisição PIX HTTP (POST, GET...) feita nesta sessão. Esta operação deve ser chamada logo após a chamada da API de requisição PIX. Deve ser chamada utilizando a mesma sessão. Não fazer outras operações entre estas chamadas. SP_HSM_OP_MODE Tipo de pbData: DWORD * Modo de operação do HSM. Pode ter os valores DN_HSM_OP_NRM, DN_HSM_OP_RM1, DN_HSM_OP_RM2 etc.
[out]	pbData	Ponteiro para os dados ou estruturas especificados em dwParam. Esse parâmetro pode ser NULL para que seja especificada a quantidade de memória necessária.
[in,out]	pdwDataLen	Ponteiro para o tamanho do buffer, em bytes, especificado em pbData. Quando a função retorna, esse parâmetro conterá o tamanho dos dados armazenados em pbData.
[in]	dwFlags	Reservado para uso futuro (deve ser 0).

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

DCloseSession()

int AAP_API DCloseSession	(	HSESSIONCTX *	phSession,
		DWORD	dwFlags )

#include <dinamo.h>

Finaliza uma sessão com o Dinamo e libera o seu contexto.

Parâmetros

[in,out]	phSession	Ponteiro para o contexto da sessão. Quando a função retornar esse parâmetro será igual à NULL.
[in]	dwFlags	Altera determinados comportamentos da função, pode ser zero. Valor Signficado CLOSE_PHYSICALLY Força o fechamento físico da sessão. Caso a sessão esteja em cache, ela será removida do cache e fechada fisicamente.

Retorna

0 (ZERO) se a função for bem sucedida.
Consulte a seção Códigos de Retorno sobre outros valores.

Anotações

O contexto da sessão, depois de liberado se torna inválido para uso em qualquer outra função. Caso o contexto seja usado novamente, a função retornará o código de erro D_INVALID_CONTEXT.

Exemplos

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, tokenization.c, user_add_remove.c, user_otp.c e verify_pin_block.c.

DFinalize()

int AAP_API DFinalize

(

)

#include <dinamo.h>

Finaliza as bibliotecas do cliente Dinamo.

Retorna

0 (ZERO)

Anotações

Essa função deve ser chamada na finalização do programa apenas uma vez. Depois de sua execução qualquer outra função chamada terá um comportamento indefinido.

Exemplos

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, tokenization.c, user_add_remove.c, user_otp.c e verify_pin_block.c.