Descrição detalhada

Gerência do HSM.

Definições e Macros
#define	DN_NT_MAX_TARGET_LEN (255)

#define	DN_NTOOL_PING (1)

#define	DN_NTOOL_TRACERT (2)

#define	DN_NTOOL_CROSS_CHECK (100)

#define	DN_WRITE_FILE_OPT_CERT_CHAIN (1)

#define	DN_WRITE_FILE_OPT_NO_CONVERSION (2)

#define	DN_ATOKEN_CACHE_GET_COUNT (0)

#define	DN_ATOKEN_CACHE_GC (1)

#define	DN_S_NSAUTH_ASSOC (1)

#define	DN_S_NSAUTH_RESET (2)

#define	DN_S_NSAUTH_AUTH (3)

#define	DN_S_NSAUTH_eAUTH (4)

#define	DN_S_NSAUTH_CHECK (5)

Definições de Tipos
typedef int(AAP_API *	funcListKeyCallback) (char szKeyName, void pParam, BOOL bFinal)

typedef int(AAP_API *	funcLogEventCallback) (char szEvent, void pParam, BOOL bFinal)

typedef int(AAP_API *	funcReadLocalFileCallback) (BYTE pbData, DWORD pdwDataLen, void pParam, BOOL pbFinal)

typedef int(AAP_API *	funcWriteLocalFileCallback) (BYTE pbData, DWORD dwDataLen, void pParam, BOOL bFinal)

typedef int(AAP_API *	funcListAKeysCallback) (void pvToken, void pParam, BOOL bFinal)

Enumerações
enum	RetCodeMsgType { CODE_MSG = 1 , DESC_MSG }

Funções
int AAP_API	DListObjs (HSESSIONCTX hSession, funcListKeyCallback fncallback, void *pParam)

int AAP_API	DListBlobs (HSESSIONCTX hSession, funcListKeyCallback fncallback, void *pParam)

int AAP_API	DBackupData (HSESSIONCTX hSession, char szBackupFile, char szPin, int nDirection)

int AAP_API	DBackupObject (HSESSIONCTX hSession, DWORD dwOP, char szObjectId, char szPin, BYTE pbData, DWORD pdwDataLen, DWORD dwReserved)

int AAP_API	DGetLogEvents (HSESSIONCTX hSession, funcLogEventCallback fncallback, void *pParam)

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

int AAP_API	DGetHSMTLSCert (char szAddress, int nPort, DWORD dwOutFormat, BYTE ppbOutCert, DWORD pdwOutCertLen, DWORD dwFlags)

int AAP_API	DHSMTool (HSESSIONCTX hSession, DWORD dwOption, const char szTarget, void pvResult, DWORD pdwResultLen, DWORD dwFlags)

int AAP_API	DWriteFileBuffer (HSESSIONCTX hSession, const char szFileId, BYTE pbFile, DWORD dwFileSize, DWORD dwOptions)

int AAP_API	DWriteFile (HSESSIONCTX hSession, char szFileId, DWORD dwFileSize, funcReadLocalFileCallback fncallback, void pParam)

int AAP_API	DReadFile (HSESSIONCTX hSession, char szFileId, funcWriteLocalFileCallback fncallback, void pParam)

int AAP_API	DReadFileBuffer (HSESSIONCTX hSession, const char szFileId, BYTE ppbData, DWORD pdwDataLen, DWORD dwReserved)

int AAP_API	DRemoveObj (HSESSIONCTX hSession, char *szObjId)

int AAP_API	DGetStatLog (HSESSIONCTX hSession, DWORD dwStart, DWORD dwOffset, DWORD pdwLogSize, BYTE *ppbLog)

int AAP_API	DTruncateLog (HSESSIONCTX hSession)

int AAP_API	DFindHSM (DWORD dwServiceType, DWORD dwFilter, void *ppvOutputData, DWORD pdwOutputDataLen, DWORD dwFlags)

int AAP_API	DManageAToken (HSESSIONCTX hSession, BYTE bOP, DN_A_TOKEN_FULL pstATokenFull, funcListAKeysCallback fnCallBack, void pvCallbackParam, DWORD dwParam)

int AAP_API	DManageATokenCache (HSESSIONCTX hSession, DWORD dwOP, void *pOutData, DWORD dwParam)

int AAP_API	DDSBindHSM (HSESSIONCTX hSession, const char *szBindKey, DWORD dwReserved)

int AAP_API	DDSUnbindHSM (HSESSIONCTX hSession, DWORD dwReserved)

int AAP_API	DSCGetShadow (const char szPin, DN_SC_M_OF_N_SHADOW pstShadow, DWORD dwReserved)

int AAP_API	DNSAuthSetState (HSESSIONCTX hSession, DWORD dwAcl, BYTE bState, DN_SC_M_OF_N_SHADOW *pstShadows, DWORD dwShadowsCount, DWORD dwReserved)

int AAP_API	DGetErrorString (int nErrorValue, char szErrorCode, char szErrorDesc)

const char *AAP_API	DGetReturnCodeString (int nErrorValue, RetCodeMsgType eErrorType)

Definições e macros

◆ DN_NT_MAX_TARGET_LEN

#define DN_NT_MAX_TARGET_LEN (255)

#include <dinamo.h>

◆ DN_NTOOL_PING

#define DN_NTOOL_PING (1)

#include <dinamo.h>

◆ DN_NTOOL_TRACERT

#define DN_NTOOL_TRACERT (2)

#include <dinamo.h>

◆ DN_NTOOL_CROSS_CHECK

#define DN_NTOOL_CROSS_CHECK (100)

#include <dinamo.h>

◆ DN_WRITE_FILE_OPT_CERT_CHAIN

#define DN_WRITE_FILE_OPT_CERT_CHAIN (1)

#include <dinamo.h>

◆ DN_WRITE_FILE_OPT_NO_CONVERSION

#define DN_WRITE_FILE_OPT_NO_CONVERSION (2)

#include <dinamo.h>

◆ DN_ATOKEN_CACHE_GET_COUNT

#define DN_ATOKEN_CACHE_GET_COUNT (0)

#include <dinamo.h>

◆ DN_ATOKEN_CACHE_GC

#define DN_ATOKEN_CACHE_GC (1)

#include <dinamo.h>

◆ DN_S_NSAUTH_ASSOC

#define DN_S_NSAUTH_ASSOC (1)

#include <dinamo.h>

Set the associated state.

◆ DN_S_NSAUTH_RESET

#define DN_S_NSAUTH_RESET (2)

#include <dinamo.h>

Reset NSAuth state. Not associated and not authorized.

◆ DN_S_NSAUTH_AUTH

#define DN_S_NSAUTH_AUTH (3)

#include <dinamo.h>

Set the authorized state. Not available yet.

◆ DN_S_NSAUTH_eAUTH

#define DN_S_NSAUTH_eAUTH (4)

#include <dinamo.h>

Set the session's state to authorized. The ACL must be set with DN_S_NSAUTH_ASSOC first.

◆ DN_S_NSAUTH_CHECK

#define DN_S_NSAUTH_CHECK (5)

#include <dinamo.h>

Check the shadow share set. This flag doesn't change the NSAuth state.

Definições dos tipos

◆ funcListKeyCallback

typedef int(AAP_API * funcListKeyCallback) (char *szKeyName, void *pParam, BOOL bFinal)

#include <dinamo.h>

Ponteiro para função de callback para listagem de objetos.

Parâmetros

[in]	szKeyName	Nome do objeto.
[in]	pParam	Ponteiro para um parâmetro passado para a função DListObjs().
[in]	bFinal	Flag que indica o último registro.

Retorna: 0

◆ funcLogEventCallback

typedef int(AAP_API * funcLogEventCallback) (char *szEvent, void *pParam, BOOL bFinal)

#include <dinamo.h>

Ponteiro para função de callback para gravar os eventos gerados pelo servidor.

Parâmetros

[in]	szEvent	Evento do log.
[in]	pParam	Ponteiro para um parâmetro passado na função DgetLogEvents.
[in]	bFinal	Indica o fim do envio de eventos.

Retorna: 0

◆ funcReadLocalFileCallback

typedef int(AAP_API * funcReadLocalFileCallback) (BYTE *pbData, DWORD *pdwDataLen, void *pParam, BOOL *pbFinal)

#include <dinamo.h>

Ponteiro para função de callback para ler o arquivo a ser carregado para o HSM.

Parâmetros

[in]	pbData	Buffer contendo os dados lidos.
[in]	pdwDataLen	Ponteiro para um DWORD contendo o número de bytes lidos do arquivo
[in]	pParam	Ponteiro para um parâmetro passado para a função DWriteFile().
[in]	pbFinal	Flag que indica o fim do arquivo.

Retorna: 0

◆ funcWriteLocalFileCallback

typedef int(AAP_API * funcWriteLocalFileCallback) (BYTE *pbData, DWORD dwDataLen, void *pParam, BOOL bFinal)

#include <dinamo.h>

Ponteiro para função de callback para gravar localmente o arquivo recuperado do HSM.

Parâmetros

[in]	pbData	Buffer com os dados que serão gravados no arquivo.
[in]	dwDataLen	Número de bytes que serão gravados.
[in]	pParam	Ponteiro para um parâmetro passado para a função DWriteFile().
[in]	bFinal	Flag que indica o fim do arquivo.

Retorna: 0

◆ funcListAKeysCallback

typedef int(AAP_API * funcListAKeysCallback) (void *pvToken, void *pParam, BOOL bFinal)

#include <dinamo.h>

Ponteiro para função de callback para listagem de tokens de sessão em DManageAToken().

Parâmetros

[in]	pvToken	Ponteiro que receberá uma estrutura DN_A_TOKEN_FULL que conterá os dados do token de sessão.
[in]	pParam	Ponteiro para um parâmetro passado para a função DManageAToken().
[in]	bFinal	Flag que indica o último registro.

Retorna: 0

Enumerações

◆ RetCodeMsgType

enum RetCodeMsgType

#include <dinamo.h>

Enumeração de tipo de mensagens de códigos de retorno.

Enumeradores
CODE_MSG	Retorna o texto do código de retorno.
DESC_MSG	Retorna a descrição do código de retorno.

Funções

◆ DListObjs()

int AAP_API DListObjs	(	HSESSIONCTX	hSession,
		funcListKeyCallback	fncallback,
		void *	pParam )

#include <dinamo.h>

Lista os objetos armazenadas no Dinamo, entre chaves e arquivos.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	fncallback	Ponteiro para uma função de callback usada para listar os nomes (identificadores) dos objetos.
[in]	pParam	Ponteiro para um parâmetro qualquer que será repassado à função de callback

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

Anotações: As funções da API Dinamo não devem ser chamadas de dentro da função de callback (parâmetro fncallback) usando o mesmo contexto (parâmetro hSession) passado para a função DListObjs(). Quando houver necessidade utilizar um contexto de sessão diferente.

Exemplos: list_keys.c.

◆ DListBlobs()

int AAP_API DListBlobs	(	HSESSIONCTX	hSession,
		funcListKeyCallback	fncallback,
		void *	pParam )

#include <dinamo.h>

Lista os blobs armazenados no Dinamo.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	fncallback	Ponteiro para uma função de callback usada para listar os nomes (identificadores) dos blobs.
[in]	pParam	Ponteiro para um parâmetro qualquer que será repassado à função de callback

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

Anotações: As funções da API Dinamo não devem ser chamadas de dentro da função de callback (parâmetro fncallback) usando o mesmo contexto (parâmetro hSession) passado para a função DListBlobs(). Quando houver necessidade utilizar um contexto de sessão diferente.

◆ DBackupData()

int AAP_API DBackupData	(	HSESSIONCTX	hSession,
		char *	szBackupFile,
		char *	szPin,
		int	nDirection )

#include <dinamo.h>

Cria ou restaura o backup dos objetos (chaves, certificados, etc.) gravados internamente no Dinamo.

Parâmetros

[in] hSession Contexto adquirido através da função DOpenSession().

[in] szBackupFile Caminho do arquivo de backup.

[in] szPin Senha de proteção do arquivo de backup. Devem ser caracteres ASCII. O tamanho deve estar entre MIN_BACKUP_PIN_LEN e MAX_BACKUP_PIN_LEN.

[in]

nDirection

[in] Especifica a ação a ser executada.

Valor	Significado
MAKE_BACKUP	O arquivo de backup será criado, caso exista, será sobrescrito.
MAKE_RESTORE_WITHOUT_NET_CONFIG	Os dados de backup existentes, não incluindo parâmetros de rede, no arquivo indicado por szBackupFile serão restaurados.
MAKE_RESTORE_WITH_NET_CONFIG	Os dados de backup existentes, incluindo parâmetros de rede, no arquivo indicado por szBackupFile serão restaurados.
MAKE_USE_WIN_CREDENTIAL	Utiliza as credenciais do Windows para autenticação. Esta opção deve ser utilizado com uma das outras opções. Passar o target da credencial no campo `szPin`.

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 cria ou recupera uma cópia de segurança (backup) dos objetos armazenados no sistema para ou de um arquivo cifrado. A chave de criptografia e decriptografia é derivada da senha informada pelo usuário. Esta operação de criptografia/decriptografia é independente do modo de armazenamento do objeto no Dinamo (cifrado ou não-cifrado). A cópia de segurança é sempre cifrada. A senha utilizada na geração da cópia de segurança deverá ser usada na restauração. É possível indicar que os parâmetros de rede (endereço IP, máscara, e gateway) sejam ou não restaurados. Para restaurar arquivos grandes, acima de 2147483647 bytes é necessário que o servidor HSM esteja com a versão mínima 3.9.0.2 ou acima.

Observação: Objetos marcados como não exportáveis no Dinamo também serão incluídos na cópia de segurança. Esta operação não é seletiva, ou seja, todos os objetos existentes na área de armazenamento do Dinamo serão copiados.

◆ DBackupObject()

int AAP_API DBackupObject	(	HSESSIONCTX	hSession,
		DWORD	dwOP,
		char *	szObjectId,
		char *	szPin,
		BYTE *	pbData,
		DWORD *	pdwDataLen,
		DWORD	dwReserved )

#include <dinamo.h>

Cria ou restaura o backup de um objeto específico no HSM.

Parâmetros

[in] hSession Contexto adquirido através da função DOpenSession().

[in]

dwOP

Especifica a ação a ser executada.

Valor Significado

D_BACKUP_OBJ Faz o backup do objeto especificado em szObjectId e escreve o conteúdo em pbData. pdwDataLen deverá conter o tamanho do buffer apontado por pbData e ao final da chamada receberá o total de bytes copiados para pbData. Caso pbData seja NULL, pdwDataLen receberá o tamanho do buffer pbData necessário para acomodar o backup. Pode-se utilizar um buffer maior ou igual a D_MAX_BACKUP_OBJ_LEN para evitar uma chamada extra a esta função, apenas para recuperar o tamanho do buffer de backup necessário.

D_RESTORE_OBJ Restaura o backup do objeto. szObjectId deverá conter o nome que o objeto restaurado terá dentro do HSM. pbData deverá conter o buffer do backup que será restaurado e pdwDataLen o tamanho de pbData.

[in] szObjectId Nome do objeto dentro do HSM.

[in] szPin Senha de proteção do arquivo de backup. Devem ser caracteres ASCII. O tamanho deve estar entre MIN_BACKUP_PIN_LEN e MAX_BACKUP_PIN_LEN.

[in,out] pbData Buffer contento o backup do objeto. Ver opções em dwOP para mais detalhes.

[in,out] pdwDataLen Tamanho do backup. Ver opções em dwOP para mais detalhes.

[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 cria ou recupera uma cópia de segurança (backup) de um objeto específico (uma chave por exemplo) para ou de um arquivo cifrado. A cópia de segurança é sempre cifrada com duas camadas: primeiro com a chave Server Master Key (SVMK) do HSM e segundo com a chave de criptografia derivada da senha informada pelo usuário. A senha utilizada na geração da cópia de segurança deverá ser usada na restauração.

Como o objeto saí cifrado pela SVMK, só poderá ser restaurado em HSMs Dinamo inicializados com esta mesma SVMK. Do ponto de vista de segurança o objeto contido no backup continua protegida pela fronteira criptográfica do HSM.

Linhas diferentes de modelos de HSM Dinamo podem ter métodos diferentes de derivação de SVMK a partir da semente. Os backups gerados em modelos XP e ST são interoperáveis entre si, mas não com backups de modelo Pocket.

Observação: O backup pode ser realizado com objetos exportáveis ou não-exportáveis e este estado é preservado na operação de restore. Apenas o objeto especificado em szObjectId será incluído no backup.

◆ DGetLogEvents()

int AAP_API DGetLogEvents	(	HSESSIONCTX	hSession,
		funcLogEventCallback	fncallback,
		void *	pParam )

#include <dinamo.h>

Recupera os eventos de log gerados pelo servidor.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	fncallback	Ponteiro para uma função de callback usada para gravar os eventos gerados pelo servidor.
[in]	pParam	Ponteiro para um parâmetro qualquer que será repassado à função de callback.

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

Anotações: Esta opção permite que um programa receba mensagens de log geradas internamente no Dinamo; o programa passa a receber uma cópia de todas as mensagens de log. Há um limite de 03 (três) receptores simultaneamente em modo de recebimento de notificações de eventos, para evitar degradação de desempenho do HSM. As mensagens enviadas continuam sendo gravadas no arquivo interno do servidor. O primeiro valor hexadecimal mostrado na linha de log é um timestamp e o segundo é um ID usado internamente.

Exemplos: get_rt_logs.c.

◆ DAdmOperation()

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

#include <dinamo.h>

Executa operações administrativas no servidor.

Parâmetros

[in] hSession Contexto adquirido através da função DOpenSession().

[in]

dwParam

Especifica a operação que será executada e por conseqüência a estrutura ou dados passados no parâmetro pbData.

Valor	Signficado
AO_SHUTDOWN	Tipo de `pbData:` NULL Desliga o HSM. Neste momento será preciso uma intervenção manual para que o servidor fique disponível novamente, ou seja, será preciso ligar o equipamento e inserir o cartão de operação. Ainda não suportado
AO_RESTART	Tipo de `pbData:` NULL Reinicia o HSM. Neste momento será preciso uma intervenção manual para que o servidor fique disponível novamente, ou seja, inserir o cartão de operação. Ainda não suportado.
AO_KEEPALIVE	Tipo de `pbData:` NULL Executa uma simples troca de mensagens entre o cliente e o servidor a fim de manter a conexão estabelecida.
AO_SET_DATE_TIME	Tipo de `pbData:` struct tm (time.h) Define data e hora do HSM. Deve ser passado o horário GMT (Greenwich Mean Time) padrão (sem fuso horário).
AO_SET_PWD_SEC_POLICY	Tipo de `pbData:` PWD_SEC_POLICY Define os parâmetros da política de segurança do HSM.
AO_GET_PWD_SEC_POLICY	Tipo de `pbData:` PWD_SEC_POLICY Recupera os parâmetros da política de segurança do HSM.
AO_SET_TLS_BUNDLE	Tipo de `pbData:` TLS_BUNDLE_INFO Define a chave e certificado que serão utilizados pelo TLS do HSM.
AO_EFTD_ACTIVATE	Tipo de `pbData:` NULL Ativa o módulo EFTd. Atualmente apenas o usuário DN_EFTD_DEFAULT_USER é permitido para esta operação.
AO_EFTD_DEACTIVATE	Tipo de `pbData:` NULL Desativa o módulo EFTd. Atualmente apenas o usuário DN_EFTD_DEFAULT_USER é permitido para esta operação.
AO_EFTD_RESET_CONF	Tipo de `pbData:` NULL Retorna as configurações do módulo EFTd para os parâmetros de fábrica. Apenas usuários com permissões de ACL_USR_REMOTE_INFO ou ACL_SYS_OPERATOR são autorizados para esta operação.
AO_EFTD_GET_CONF	Tipo de `pbData:` *DN_EFTD_CONF Recupera configurações do módulo EFTd. Apenas usuários com permissões de ACL_USR_REMOTE_INFO ou ACL_SYS_OPERATOR são autorizados para esta operação.
AO_EFTD_SET_MSG_HEADER_LEN	Tipo de `pbData:` *BYTE Define o tamanho do header das mensagens do módulo EFTd. Aceita valores entre DN_EFTD_MIN_MSG_HEADER_LEN e DN_EFTD_MAX_MSG_HEADER_LEN. Apenas usuários com permissões de ACL_USR_REMOTE_INFO ou ACL_SYS_OPERATOR são autorizados para esta operação.
AO_EFTD_SET_PIN_LEN	Tipo de `pbData:` *BYTE Define o tamanho do pin do módulo EFTd. Aceita valores entre DN_EFTD_MIN_PIN_LEN e DN_EFTD_MAX_PIN_LEN. Apenas usuários com permissões de ACL_USR_REMOTE_INFO ou ACL_SYS_OPERATOR são autorizados para esta operação.
AO_GET_GLOBAL_OBJ_STATS	Tipo de `pbData:` *DN_GLOBAL_OBJ_STATS Recupera as estatísticas globais de objetos. Apenas usuários com permissões de ACL_USR_REMOTE_INFO ou ACL_SYS_OPERATOR são autorizados para esta operação.
AO_GET_SEC_POLICY_GFLAGS	Tipo de `pbData:` *DWORD Recupera as flags de segurança do HSM. Apenas usuários com permissões de ACL_USR_REMOTE_INFO ou ACL_SYS_OPERATOR são autorizados para esta operação.
AO_SET_SEC_POLICY_GFLAGS	Tipo de `pbData:` DWORD Define as flags de segurança do HSM. Apenas usuários com permissões de ACL_USR_REMOTE_INFO ou ACL_SYS_OPERATOR são autorizados para esta operação. Ver valores suportados nas observações.

[in] pbData Ponteiro para os dados ou estruturas especificados em dwParam.

[in] dwDataLen Tamanho dos dados ou estrutura especificados em dwParam.

[in]

dwFlags

Deve ser 0 ou algum dos valores abaixo.

Valor	Signficado
AO_KEEPALIVE_FLAG_NOISELESS	Tipo de `dwParam:` AO_KEEPALIVE Faz com que a operação de keep alive não gere logs no HSM.

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

Anotações: A opção AO_KEEPALIVE executa um teste para indicação de ‘vida’ (heartbeat) do serviço do Dinamo. O resultado positivo a este teste mostra que o HSM está processando corretamente as requisições de clientes e seu estado interno é consistente e íntegro. Pode ser usado por exemplo pelas equipes de monitoração e suporte para indicação de status OK do Dinamo.

As opções AO_GET_SEC_POLICY_GFLAGS e AO_SET_SEC_POLICY_GFLAGS suportam os seguintes valores:

Valor	Significado
DN_SEPOL_GF_ENABLE_HTTP_X509_SA	Habilita a autenticação de clientes HTTP por certificados X.509.
DN_SEPOL_GF_ENABLE_NSA_API_AUTH	Habilita a autenticação de partição M de N via API.

Exemplos: connect_hsm.c.

◆ DGetHSMTLSCert()

int AAP_API DGetHSMTLSCert	(	char *	szAddress,
		int	nPort,
		DWORD	dwOutFormat,
		BYTE **	ppbOutCert,
		DWORD *	pdwOutCertLen,
		DWORD	dwFlags )

#include <dinamo.h>

Recupera o certificado do HSM utilizado no TLS.

Parâmetros

[in] szAddress Endereço do HSM.

[in] nPort Porta de acesso ao HSM. A porta padrão é DEFAULT_PORT.

[in]

dwOutFormat

Formato de saída do certificado.

Valor	Signficado
CERT_OUT_DER	Exporta o certificado do servidor no formato X.509 DER.
CERT_OUT_DER	Exporta o certificado do servidor no formato X.509 PEM.

[in] ppbOutCert Ponteiro de ponteiro com o certificado no formato especificado em dwOutFormat. Este ponteiro deve ser liberado com DFree.

[in] pdwOutCertLen Tamanho do certificado apontado em ppbOutCert.

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

◆ DHSMTool()

int AAP_API DHSMTool	(	HSESSIONCTX	hSession,
		DWORD	dwOption,
		const char *	szTarget,
		void **	pvResult,
		DWORD *	pdwResultLen,
		DWORD	dwFlags )

#include <dinamo.h>

Executa ferramentas de teste a partir do HSM.

Parâmetros

[in] hSession Contexto adquirido através da função DOpenSession().

[in]

dwOption

Opção de operação.

Valor	Signficado
DN_NTOOL_PING	Executa uma operação de PING a partir do HSM. `pvResult` conterá uma string.
DN_NTOOL_TRACERT	Executa uma operação de TRACERT a partir do HSM. `pvResult` conterá uma string.
DN_NTOOL_CROSS_CHECK	Executa uma operação de cross-check a partir do HSM. `pvResult` conterá um vetor de estruturas CROSS_CHECK_NODE.

[in] szTarget Endereço de destino da operação que será executada. Tamanho máximo de DN_NT_MAX_TARGET_LEN.

[out] pvResult Ponteiro de ponteiro que conterá o resultado do comando executado. Este ponteiro deve ser liberado com DFree.

[out] pdwResultLen Tamanho do buffer retornado em pvResult.

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

◆ DWriteFileBuffer()

int AAP_API DWriteFileBuffer	(	HSESSIONCTX	hSession,
		const char *	szFileId,
		BYTE *	pbFile,
		DWORD	dwFileSize,
		DWORD	dwOptions )

#include <dinamo.h>

Importa um arquivo para dentro do HSM.

Parâmetros

[in] hSession Contexto adquirido através da função DOpenSession().

[in] szFileId Identificador do novo arquivo dentro do HSM.

[in] pbFile Buffer contendo os arquivo que será importado.

[in]

dwFileSize

Tamanho do arquivo a ser carregado.

[in] dwOptions Valor

Significado

DN_WRITE_FILE_OPT_CERT_CHAIN

O arquivo informado é uma cadeia de certificados. Não usar esta opção com outros tipos de arquivo.

DN_WRITE_FILE_OPT_NO_CONVERSION

O arquivo será importado sem conversão de formato.

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

Anotações

O arquivo gravado é opaco para o HSM, é protegido pela SVMK (Server Master Key) e será sempre um objeto exportável.
O tamanho máximo por arquivo aceito pelo HSM é de 64 Kb.
Os arquivos enviados para o HSM, descritos na tabela abaixo, terão seus tipos detectados automaticamente.

Tipo	Formato
Certificados X.509	DER ou PEM
CRL(Certificate Revocation List) ou LCR(Lista de Certificados Revogados)	DER ou PEM
Cadeias de certificados PKCS#7	DER ou PEM (detecção de PEM é necessário uso da flag DN_WRITE_FILE_OPT_CERT_CHAIN)

Exemplos: pkcs7_sign.c, sign_check_pix_jws.c, sign_verify_dict.c, sign_verify_pix.c e sign_verify_xml.c.

◆ DWriteFile()

int AAP_API DWriteFile	(	HSESSIONCTX	hSession,
		char *	szFileId,
		DWORD	dwFileSize,
		funcReadLocalFileCallback	fncallback,
		void *	pParam )

#include <dinamo.h>

Importa um arquivo para dentro do HSM.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szFileId	Identificador do novo arquivo dentro do HSM.
[in]	dwFileSize	Tamanho do arquivo a ser carregado.
[in]	fncallback	Ponteiro para uma função de callback usada para ler o arquivo a ser carregado.
[in]	pParam	Ponteiro para um parâmetro qualquer que será repassado à função de callback.

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

Anotações

O arquivo gravado é opaco para o HSM e não será cifrado internamente e será sempre um objeto exportável.
O tamanho máximo por arquivo aceito pelo HSM é de 512kb.
Os arquivos enviados para o HSM, descritos na tabela abaixo, terão seus tipos detectados automaticamente.

Tipo	Formato
Certificados X.509	DER
CRL(Certificate Revocation List) ou LCR(Lista de Certificados Revogados)	DER
Cadeias de certificados PKCS#7	DER

◆ DReadFile()

int AAP_API DReadFile	(	HSESSIONCTX	hSession,
		char *	szFileId,
		funcWriteLocalFileCallback	fncallback,
		void *	pParam )

#include <dinamo.h>

Exporta uma arquivo do HSM.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szFileId	Identificador do arquivo dentro do HSM.
[in]	fncallback	Ponteiro para uma função de callback usada para gravar o arquivo recuperado.
[in]	pParam	Ponteiro para um parâmetro qualquer que será repassado à função de callback.

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

Anotações: Esta API não deve ser usada para exportação de chaves.

◆ DReadFileBuffer()

int AAP_API DReadFileBuffer	(	HSESSIONCTX	hSession,
		const char *	szFileId,
		BYTE **	ppbData,
		DWORD *	pdwDataLen,
		DWORD	dwReserved )

#include <dinamo.h>

Exporta uma arquivo do HSM para um buffer.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szFileId	Identificador do arquivo dentro do HSM.
[out]	ppbData	Ponteiro que receberá os dados do arquivo lido. A memória é alocada internamente. A memória deve liberada com DFree().
[out]	pdwDataLen	Recebe o tamanho do buffer alocado em `ppbData`.
[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: Esta API não deve ser usada para exportação de chaves.

◆ DRemoveObj()

int AAP_API DRemoveObj	(	HSESSIONCTX	hSession,
		char *	szObjId )

#include <dinamo.h>

Remove um objeto armazenado no Dinamo, seja ele uma chave ou um arquivo.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szObjId	Identificador do objeto dentro do HSM. Este identificador não deve conter espaços ou caracteres especiais. Caracteres maiúsculos e minúsculos são diferenciados (case-sensitive).

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

Exemplos: ckd_bchain.c, gen_ecdh.c, gen_xecdh.c, get_key_info_bchain.c, get_pub_key_bchain.c, import_export_bchain.c e sign_verify_bchain.c.

◆ DGetStatLog()

int AAP_API DGetStatLog	(	HSESSIONCTX	hSession,
		DWORD	dwStart,
		DWORD	dwOffset,
		DWORD *	pdwLogSize,
		BYTE **	ppbLog )

#include <dinamo.h>

Recupera o conteúdo do log do servidor.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	dwStart	Posição inicial, em bytes, do log a ser recuperado. Para receber todo o conteúdo do log indique GET_LOG_START_FULL.
[in]	dwOffset	Quantidade, em bytes, a ser recuperada a partir da posição inicial indicada por `dwStart`. Para receber todo o conteúdo do log indique GET_LOG_END_FULL .
[out]	pdwLogSize	Ponteiro para DWORD que irá conter a quantidade, em bytes, do log recuperado.
[out]	ppbLog	Ponteiro para ponteiro que irá conter o log recuperado do servidor. A alocação de memória é feita internamente pela biblioteca. A aplicação chamadora é responsável por liberar a memória alocada. Consulte a função DFree().

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

Veja também: DGetStatLogSize(), DTruncateLog()

Exemplos: download_log.c.

◆ DTruncateLog()

int AAP_API DTruncateLog ( HSESSIONCTX hSession )

#include <dinamo.h>

Permite apagar o conteúdo do log do servidor.

Parâmetros

[in] hSession Contexto adquirido através da função DOpenSession().

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

Veja também: DGetStatLogSize(), DGetStatLog()

◆ DFindHSM()

int AAP_API DFindHSM	(	DWORD	dwServiceType,
		DWORD	dwFilter,
		void **	ppvOutputData,
		DWORD *	pdwOutputDataLen,
		DWORD	dwFlags )

#include <dinamo.h>

Busca, utilizando protocolo SLP via multicast, os HSMs disponíveis na rede.

Parâmetros

[in]

dwServiceType

Define o tipo de serviço do HSM que será procurado.

Valor	Signficado
DN_FIND_SRVC_TYPE_IP	Lista todos os serviços tipo IP encontrados. Lista todas as interfaces IP disponíveis. O mesmo HSM pode ser listado mais de uma vez com IPs diferentes. O valor de `dwFilter` deve ser DN_FIND_FILTER_TYPE_ALL.
DN_FIND_SRVC_TYPE_AAP	Lista todos os serviços tipo AAP encontrados. Lista todos os HSMs que estejam com o serviço executando.
DN_FIND_SRVC_TYPE_ALL	Lista todos os tipos de serviço.

[in]

dwFilter

Define o tipo de filtro a ser utilizado na busca.

Valor	Signficado
DN_FIND_FILTER_TYPE_POCKET	Lista todos os HSMs Pocket encontrados.
DN_FIND_FILTER_TYPE_HSM	Lista todos os HSM DINAMO ST ou XP encontrados.
DN_FIND_FILTER_TYPE_ALL	Lista todos os HSM DINAMO ST, XP ou Pocket encontrados.

[out] ppvOutputData Ponteiro de ponteiro, do tipo SLP_SRVR_INFO, que irá conter a lista de HSMs encontrados. A alocação de memória é feita internamente pela biblioteca. A aplicação chamadora é responsável por liberar a memória alocada. Consulte a função DFree().

[out] pdwOutputDataLen Ponteiro para DWORD que irá conter a quantidade de estruturas (descritas em dwOutputType) retornadas em ppvOutputData.

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

Anotações: A busca é feita utilizando protocolo SLP (Service Location Protocol) via multicast. Todos os HSMs que se encontrarem acessíveis e com o serviço executando poderão aparecer nesta lista.

◆ DManageAToken()

int AAP_API DManageAToken	(	HSESSIONCTX	hSession,
		BYTE	bOP,
		DN_A_TOKEN_FULL *	pstATokenFull,
		funcListAKeysCallback	fnCallBack,
		void *	pvCallbackParam,
		DWORD	dwParam )

#include <dinamo.h>

Gerencia tokens de sessão (Access Tokens) do próprio usuário.

Observação: No projeto da aplicação leve em conta o fato de os Access Tokens serem voláteis, conforme detalhado abaixo.

Sobre autenticação usando tokens de sessão consulte a função DOpenSession() com a opção SS_ATOKEN.

Parâmetros

[in] hSession Contexto adquirido através da função DOpenSession().

[in]

bOP

Especifica a operação que será executada.

Valor	Signficado
DN_A_TOKEN_OP_ISSUE	Emite um token de sessão. Preencher o parâmetro `qwExpiration` de entrada em `pstATokenFull`, que no retorno da API receberá o token emitido. Passar NULL em `fnCallBack` e `pvCallbackParam`.
DN_A_TOKEN_OP_REVOKE	Revoga um token de sessão, caso ele exista. Preencher o parâmetro `Key` de entrada em `pstATokenFull`. Passar NULL em `fnCallBack` e `pvCallbackParam`.
DN_A_TOKEN_OP_L_ISSUE	Emite um token de sessão. Apenas para o HSM conectado, não faz replicação do token de sessão. Preencher o parâmetro `qwExpiration` de entrada em `pstATokenFull`, que no retorno da API receberá o token emitido. Passar NULL em `fnCallBack` e `pvCallbackParam`.
DN_A_TOKEN_OP_L_REVOKE	Revoga um token de sessão, caso ele exista. Apenas para o HSM conectado, não faz replicação do token de sessão. Preencher o parâmetro `Key` de entrada em `pstATokenFull`. Passar NULL em `fnCallBack` e `pvCallbackParam`.
DN_A_TOKEN_OP_LIST	Lista todos tokens ativos deste usuário. Deve ser passado a função de callback em `fnCallBack`. Passar NULL em `pstATokenFull`;

[in,out] pstATokenFull Ponteiro para uma estrutura do tipo DN_A_TOKEN_FULL. Ver opção de bOP para instruções de preenchimento da estrutura.

[in] fnCallBack Ponteiro para a função de callback do tipo funcListAKeysCallback. Pode ser NULL. Ver opção de bOP para instruções de preenchimento da estrutura.

[in] pvCallbackParam Ponteiro para um parâmetro qualquer que será repassado à função de callback. Pode ser NULL.

[in] dwParam 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

Os Access Tokens são mantidos em memória volátil, e desta maneira são apagados quando o HSM é reiniciado. Apesar de serem voláteis, os Access Tokens são replicados entre HSMs.

A limpeza de Access Tokens expirados acontece em 2 momentos:

quando um usuário que tem um Access Tokens expirado faz uma tentativa de login utilizando Access Tokens. Limpa apenas os próprios Access Tokens.
utilizando a função DManageATokenCache(). Limpa todos os Access Tokens expirados do HSM.

O limite máximo de Access Tokens emitidos por HSM pode ser visto na tabela abaixo.

Modelo	Limite máximo
Pocket	1024
XP	1 Milhão
ST	1 Milhão

Esta operação está disponível à partir da versão 3.17 do firmware do HSM. A implementação de Access Tokens anterior à versão 3.17 do firmware é legada.

As aplicações, que utilizam esta funcionalidade, deverão atualizar o cliente do HSM para a versão 3.2.18 ou superior, juntamente com o firmware do HSM para a versão 3.17 ou superior.

Não há compatibilidade entre versões novas e antigas de cliente e firmware do HSM.

◆ DManageATokenCache()

int AAP_API DManageATokenCache	(	HSESSIONCTX	hSession,
		DWORD	dwOP,
		void *	pOutData,
		DWORD	dwParam )

#include <dinamo.h>

Gerencia o cache dos tokens de sessão (Access Tokens) de todo HSM. Esta funcionalidade é indicada para o controle granular de autenticação de aplicações, onde a emissão de tokens é gerenciada pelo security officer.

Sobre autenticação usando tokens de sessão consulte a função DOpenSession() com a opção SS_ATOKEN. A emissão de Access Tokens é feita utilizando a função DManageAToken().

Parâmetros

[in] hSession Contexto adquirido através da função DOpenSession().

[in]

dwOP

Especifica a operação que será executada.

Valor	Signficado
DN_ATOKEN_CACHE_GET_COUNT	Recupera a quantidade de tokens de sessão de todo HSM. Passar em `pOutData` um DWORD que receberá a quantidade total de tokens de sessão do HSM.
DN_ATOKEN_CACHE_GC	Executa o Garbage Collector de tokens de sessão do HSM. Esta opção faz a limpeza de todos os Access Tokens do HSM que não forem mais válidos. Passar NULL em `pOutData`.

[out] pOutData Dados de saída. Ver opções de uso em dwOP.

[in] dwParam 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: Esta operação está disponível à partir da versão 3.17 do firmware do HSM e a partir da versão 3.2.18 do cliente do HSM.
A opção DN_ATOKEN_CACHE_GC deve ser chamada periodicamente pela aplicação para manter os níveis do cache de Access Tokens sob controle. O horário de execução do GC deve ser programado levando em conta os momentos de maiores cargas de trabalho do HSM.

◆ DDSBindHSM()

int AAP_API DDSBindHSM	(	HSESSIONCTX	hSession,
		const char *	szBindKey,
		DWORD	dwReserved )

#include <dinamo.h>

Associa um HSM à uma conta Dinamo Services.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szBindKey	Chave de vínculo. Gerada no site da Dinamo Services.
[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.

◆ DDSUnbindHSM()

int AAP_API DDSUnbindHSM	(	HSESSIONCTX	hSession,
		DWORD	dwReserved )

#include <dinamo.h>

Desassocia um HSM de uma conta Dinamo Services.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[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.

◆ DSCGetShadow()

int AAP_API DSCGetShadow	(	const char *	szPin,
		DN_SC_M_OF_N_SHADOW *	pstShadow,
		DWORD	dwReserved )

#include <dinamo.h>

Lê a shadow de um cartão Smart-card M de N Dinamo.

Parâmetros

[in]	szPin	PIN do cartão. Deve ser uma string numérica ASCII com tamanho máximo de DN_SC_MAX_PIN_LEN.
[out]	pstShadow	Dados da shadow lida.
[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.

◆ DNSAuthSetState()

int AAP_API DNSAuthSetState	(	HSESSIONCTX	hSession,
		DWORD	dwAcl,
		BYTE	bState,
		DN_SC_M_OF_N_SHADOW *	pstShadows,
		DWORD	dwShadowsCount,
		DWORD	dwReserved )

#include <dinamo.h>

Define o estado de autorização do M de N de partição.

Parâmetros

[in] hSession Contexto adquirido através da função DOpenSession().

[in]

dwAcl

ACL do usuário.

Valor	Significado
NSAUTH_ACL_NOP	Sem permissão.
NSAUTH_ACL_OBJ_OPEN	Permissão para abrir/utilizar objetos. Definido por padrão.
NSAUTH_ACL_OBJ_EXPORT	Permissão para exportar objetos.
NSAUTH_ACL_OBJ_DEL	Permissão para deletar objetos.
NSAUTH_ACL_OBJ_BLOCK	Permissão para bloquear objetos.
NSAUTH_ACL_NS_DEL	Permissão para deletar o namespace. O usuário deve estar no estado associado para poder ser removido.

[in]

bState

Estado a ser definido.

Valor	Significado
DN_S_NSAUTH_ASSOC	Define o estado associado. Informar o ACL do usuário.
DN_S_NSAUTH_RESET	Reseta o estado NSAuth. Não associado e não autorizado. Passar NSAUTH_ACL_NOP em `dwAcl`.
DN_S_NSAUTH_AUTH	Define o estado autorizado. Não disponível ainda.
DN_S_NSAUTH_eAUTH	Define o estado da sessão como autorizado. O ACL deve ser definido com DN_S_NSAUTH_ASSOC primeiro. Passar NSAUTH_ACL_NOP em `dwAcl`.
DN_S_NSAUTH_CHECK	Verifica o conjunto de shadows. Esta flag não altera o estado NSAuth. Passar NSAUTH_ACL_NOP em `dwAcl`.

[in] pstShadows Dados das shadows dos Smart-cards da partição M de N.

[in] dwShadowsCount Número de shadows em pstShadows.

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

◆ DGetErrorString()

int AAP_API DGetErrorString	(	int	nErrorValue,
		char *	szErrorCode,
		char *	szErrorDesc )

#include <dinamo.h>

Obsoleto(a): Esta API está descontinuada, utilizar DGetReturnCodeString().

◆ DGetReturnCodeString()

const char *AAP_API DGetReturnCodeString	(	int	nErrorValue,
		RetCodeMsgType	eErrorType )

#include <dinamo.h>

Recupera a descrição de um código de retorno das APIs DINAMO.

Parâmetros

[in] nErrorValue Código de retorno.

[in]

eErrorType

Tipo da string de retorno.

Valor	Signficado
CODE_MSG	Retorna o texto do código de retorno.
DESC_MSG	Retorna a descrição do código de retorno.

Retorna: Retorna a string de acordo com o definido em eErrorType.

Descrição detalhada

Definições e Macros

Definições de Tipos

Enumerações

Funções

Definições e macros

◆ DN_NT_MAX_TARGET_LEN

◆ DN_NTOOL_PING

◆ DN_NTOOL_TRACERT

◆ DN_NTOOL_CROSS_CHECK

◆ DN_WRITE_FILE_OPT_CERT_CHAIN

◆ DN_WRITE_FILE_OPT_NO_CONVERSION

◆ DN_ATOKEN_CACHE_GET_COUNT

◆ DN_ATOKEN_CACHE_GC

◆ DN_S_NSAUTH_ASSOC

◆ DN_S_NSAUTH_RESET

◆ DN_S_NSAUTH_AUTH

◆ DN_S_NSAUTH_eAUTH

◆ DN_S_NSAUTH_CHECK

Definições dos tipos

◆ funcListKeyCallback

◆ funcLogEventCallback

◆ funcReadLocalFileCallback

◆ funcWriteLocalFileCallback

◆ funcListAKeysCallback

Enumerações

◆ RetCodeMsgType

Funções

◆ DListObjs()

◆ DListBlobs()

◆ DBackupData()

◆ DBackupObject()

◆ DGetLogEvents()

◆ DAdmOperation()

◆ DGetHSMTLSCert()

◆ DHSMTool()

◆ DWriteFileBuffer()

◆ DWriteFile()

◆ DReadFile()

◆ DReadFileBuffer()

◆ DRemoveObj()

◆ DGetStatLog()

◆ DTruncateLog()

◆ DFindHSM()

◆ DManageAToken()

◆ DManageATokenCache()

◆ DDSBindHSM()

◆ DDSUnbindHSM()

◆ DSCGetShadow()

◆ DNSAuthSetState()

◆ DGetErrorString()

◆ DGetReturnCodeString()