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

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

Descrição Detalhada

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

Funções

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:: connecthsm.c, cryptsym.c, downloadlog.c, eftvalidatecvv.c, genecdh.c, gethsminfo.c, getrtlogs.c, hashcreate.c, keyaddremove.c, keyattribute.c, listkeys.c, pkcs7sign.c, signverify.c, spbactivatecert.c, spbencdec.c, spbgetcert.c, spbggenkeycsr.c, spbimportp12.c, useraddremove.c e userOtp.c.

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.

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.

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.

[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.0). 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.

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.0 é 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.

Exemplos:: connecthsm.c, cryptsym.c, downloadlog.c, eftvalidatecvv.c, genecdh.c, gethsminfo.c, getrtlogs.c, hashcreate.c, keyaddremove.c, keyattribute.c, listkeys.c, pkcs7sign.c, signverify.c, spbactivatecert.c, spbencdec.c, spbgetcert.c, spbggenkeycsr.c, spbimportp12.c, useraddremove.c e userOtp.c.

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.

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

[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.

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:: connecthsm.c, cryptsym.c, downloadlog.c, eftvalidatecvv.c, genecdh.c, gethsminfo.c, getrtlogs.c, hashcreate.c, keyaddremove.c, keyattribute.c, listkeys.c, pkcs7sign.c, signverify.c, spbactivatecert.c, spbencdec.c, spbgetcert.c, spbggenkeycsr.c, spbimportp12.c, useraddremove.c e userOtp.c.

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:: connecthsm.c, cryptsym.c, downloadlog.c, eftvalidatecvv.c, genecdh.c, gethsminfo.c, getrtlogs.c, hashcreate.c, keyaddremove.c, keyattribute.c, listkeys.c, pkcs7sign.c, signverify.c, spbactivatecert.c, spbencdec.c, spbgetcert.c, spbggenkeycsr.c, spbimportp12.c, useraddremove.c e userOtp.c.