Descrição detalhada

Autenticação padrão OATH.

Consulte a documentação técnica do HSM sobre detalhes de funcionamento, especificações utilizadas, licenças e nome comercial do módulo.

Funções
int AAP_API	DOATHIssueBlob (HSESSIONCTX hSession, char szMasterKeyId, DWORD dwParamBlobType, void pvParamBlob, DWORD dwParamBlobLen, BYTE pbOTPBlob, DWORD pdwOTPBlobLen, DWORD dwFlags)

int AAP_API	DOATHCheckOTP (HSESSIONCTX hSession, char szMasterKeyId, char szOTP, BYTE pbOATHBlob, DWORD pdwOATHBlobLen, DWORD dwFlags)

int AAP_API	DOATHGetNextOTP (HSESSIONCTX hSession, char szMasterKeyId, BYTE bOTPLen, BYTE pbOATHBlob, DWORD dwOATHBlobLen, char *szOTP, DWORD dwFlags)

int AAP_API	DOATHGetBlobInfo (const HSESSIONCTX hSession, char szMasterKey, BYTE pbInBlob, DWORD dwInBlobLen, DWORD dwOutBlobType, BYTE pbOutInfo, DWORD pdwOutInfoLen, DWORD dwParam)

int AAP_API	DOATHBlobResync (HSESSIONCTX hSession, char szMasterKeyId, char szOTP1, char szOTP2, BYTE pbOATHBlob, DWORD *pdwOATHBlobLen, DWORD dwFlags)

int AAP_API	DOATHPskcTranslate (HSESSIONCTX hSession, char szMasterKey, BYTE pbPSK, BYTE bPSKLen, BYTE pbPSKC, DWORD dwPSKCLen, void pvBlobList, DWORD pdwBlobListQuantity, DWORD dwParam)

Funções

◆ DOATHIssueBlob()

int AAP_API DOATHIssueBlob	(	HSESSIONCTX	hSession,
		char *	szMasterKeyId,
		DWORD	dwParamBlobType,
		void *	pvParamBlob,
		DWORD	dwParamBlobLen,
		BYTE *	pbOTPBlob,
		DWORD *	pdwOTPBlobLen,
		DWORD	dwFlags )

#include <dinamo.h>

Gera ou importa um blob OATH para uso no HSM.

Parâmetros

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

[in] szMasterKeyId Nome da chave mestre, utilizada para proteger os blobs, de tamanho máximo MAX_OBJ_ID_FQN_LEN.

[in]

dwParamBlobType

A tabela seguinte é aceita.

valor	Significado
ISSUE_OATH_GENERATE_HOTP	Tipo de `pvParamBlob:` estrutura ISSUE_OTP_BLOB. Gera blob HOTP no HSM. A semente é gerada dentro do HSM. Os seguintes parâmetros da estrutura devem ser preenchidos: `bSeedLen` e `bTruncationOffset`. Os demais devem estar zerados.
ISSUE_OATH_GENERATE_TOTP	Tipo de `pvParamBlob:` estrutura ISSUE_OTP_BLOB. Gera blob TOTP no HSM. A semente é gerada dentro do HSM. Os seguintes parâmetros da estrutura devem ser preenchidos: `bSeedLen`, `bTruncationOffset`, `wTimeStep` e `otT0`. Os demais devem estar zerados.
ISSUE_OATH_IMPORT_HOTP	Tipo de `pvParamBlob:` estrutura ISSUE_OTP_BLOB. Importa um blob HOTP. A semente é passada por parâmetro. Os seguintes parâmetros da estrutura devem ser preenchidos: `bSeedLen`, `pbSeed` e `bTruncationOffset`. Os demais devem estar zerados.
ISSUE_OATH_IMPORT_TOTP	Tipo de `pvParamBlob:` estrutura ISSUE_OTP_BLOB. Importa um blob TOTP. Semente é passada por parâmetro. Os seguintes parâmetros da estrutura devem ser preenchidos: `bUseDefaultMovingFactor`, `bSeedLen`, `pbSeed`, `bTruncationOffset`, `wTimeStep` e `otT0`. Os demais devem estar zerados.

[in] pvParamBlob Ponteiro para os dados ou estruturas especificados em dwParamBlobType.

[in] dwParamBlobLen Tamanho dos dados ou estrutura especificados em dwParamBlobType.

[out] pbOTPBlob Buffer de tamanho mínimo de ISSUE_OATH_OUTPUT_MAX_BLOB_LEN que conterá o blob gerado.

[in,out] pdwOTPBlobLen Tamanho do buffer apontado por pbOTPBlob. Na entrada deve conter o tamanho do buffer pbOTPBlob na saída conterá o tamanho do blob escrito no buffer alocado.

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

Exemplos: gen_check_oath.c.

◆ DOATHCheckOTP()

int AAP_API DOATHCheckOTP	(	HSESSIONCTX	hSession,
		char *	szMasterKeyId,
		char *	szOTP,
		BYTE *	pbOATHBlob,
		DWORD *	pdwOATHBlobLen,
		DWORD	dwFlags )

#include <dinamo.h>

Verifica um valor OTP para determinado blob OATH.

Parâmetros

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

[in] szMasterKeyId Nome da chave mestre, utilizada para proteger os blobs, de tamanho máximo MAX_OBJ_ID_FQN_LEN.

[in] szOTP OTP a ser verificado de tamanho mínimo ISSUE_OATH_MIN_OTP_LEN e máximo ISSUE_OATH_MAX_OTP_LEN.

[in,out] pbOATHBlob Ponteiro para um buffer contendo o blob que terá o OTP verificado. Este buffer será reescrito com o buffer atualizado.

[in,out] pdwOATHBlobLen Tamanho do buffer pbOATHBlob. Na entrada conterá o tamanho de pbOATHBlob e na saída o tamanho de dados escritos em pbOATHBlob.

[in]

dwFlags

A partir da versão 4.0.2 do firmware pode-se passar, neste parâmetro, o tamanho da janela de look-ahead de autenticação. O padrão é de 10 intervalos para mais ou para menos. No caso de tokens HOTP os intervalos serão contados por quantidade de eventos, no caso dos tokens TOTP serão contados por quantidade de time-steps.

Valor	Significado
0	Utiliza o valor default de 10 intervalos.
1 à MAX_OTP_LOOK_AHEAD_INTERVAL	Define o valor da janela de look-ahead de autenticação.

Também é possível passar neste parâmetro a flag OATH_UPDATE_BLOB, para permitir a atualização do formato do OATH blob. Quando a flag OATH_UPDATE_BLOB é utilizada, deve-se passar o OATH blob atual em pbOATHBlob em um buffer suficientemente grande para comportar o blob atualizado. pdwOATHBlobLen deverá conter o valor do tamanho do buffer passado em pbOATHBlob. O tamanho de pbOATHBlob necessário, é retornado em pdwOATHBlobLen na chamada onde o erro D_OATH_BLOB_UPDATE é retornado. A atualização precisa ser apenas feita após receber o erro D_OATH_BLOB_UPDATE. Ver Anotações para mais detalhes.

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

Anotações: Caso seja retornado o erro D_OATH_BLOB_UPDATE a função retornará em pdwOATHBlobLen o tamanho do buffer que deverá ser utilizado para atualização do OATH blob em uma chamada posterior. Ver detalhes na especificação de OATH_UPDATE_BLOB.

Exemplos: gen_check_oath.c.

◆ DOATHGetNextOTP()

int AAP_API DOATHGetNextOTP	(	HSESSIONCTX	hSession,
		char *	szMasterKeyId,
		BYTE	bOTPLen,
		BYTE *	pbOATHBlob,
		DWORD	dwOATHBlobLen,
		char *	szOTP,
		DWORD	dwFlags )

#include <dinamo.h>

Gera o próximo OTP à partir de um blob OATH. O OATH blob não será alterado.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szMasterKeyId	Nome da chave mestre, utilizada para proteger os blobs, de tamanho máximo MAX_OBJ_ID_FQN_LEN.
[in]	bOTPLen	Tamanho do OTP que será gerado, podendo ser um valor entre ISSUE_OATH_MIN_OTP_LEN e ISSUE_OATH_MAX_OTP_LEN.
[in]	pbOATHBlob	Ponteiro para um buffer contendo o blob que será utilizado para a geração do OTP. Este buffer não será alterado.
[in]	dwOATHBlobLen	Tamanho do buffer `pbOATHBlob`.
[out]	szOTP	Buffer que conterá o OTP gerado. Deverá ter o tamanho mínimo de `bOTPLen` + 1(terminador nulo).
[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.

Exemplos: gen_check_oath.c.

◆ DOATHGetBlobInfo()

int AAP_API DOATHGetBlobInfo	(	const HSESSIONCTX	hSession,
		char *	szMasterKey,
		BYTE *	pbInBlob,
		DWORD	dwInBlobLen,
		DWORD	dwOutBlobType,
		BYTE *	pbOutInfo,
		DWORD *	pdwOutInfoLen,
		DWORD	dwParam )

#include <dinamo.h>

Recupera as informações internas de um blob OATH.

Parâmetros

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

[in] szMasterKey Nome da chave mestre, utilizada para proteger os blobs, de tamanho máximo MAX_OBJ_ID_FQN_LEN.

[in] pbInBlob Ponteiro para um buffer contendo o blob para extração das informações.

[in] dwInBlobLen Tamanho do buffer pbInBlob.

[in]

dwOutBlobType

Indica o tipo de dado de saída. A seguinte tabela é aceita.

Valor	Significado
OATH_ISSUE_OATH_BLOB_t	Tipo de pbOutInfo: ISSUE_OATH_BLOB_t. O Buffer de pbInBlob precisa ser um blob tipo V1 com tamanho ISSUE_OATH_OUTPUT_BLOB_V1_LEN.
OATH_ISSUE_OATH_INFO_t	Tipo de pbOutInfo: ISSUE_OATH_INFO_t. Esta opção aceita blobs do tipo V1 e V2 com tamanhos ISSUE_OATH_OUTPUT_BLOB_V1_LEN e ISSUE_OATH_OUTPUT_BLOB_V2_LEN, respectivamente.

[out] pbOutInfo Ponteiro para um buffer que receberá as informações do blob. Deve ser de acordo com o descrito em dwOutBlobType.

[in,out] pdwOutInfoLen Tamanho do buffer apontado por pdwOutInfoLen.

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

◆ DOATHBlobResync()

int AAP_API DOATHBlobResync	(	HSESSIONCTX	hSession,
		char *	szMasterKeyId,
		char *	szOTP1,
		char *	szOTP2,
		BYTE *	pbOATHBlob,
		DWORD *	pdwOATHBlobLen,
		DWORD	dwFlags )

#include <dinamo.h>

Re-sincroniza um blob OATH através da apresentação de dois valores de OTP contínuos. Apenas para HOTP(OTP por evento).

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szMasterKeyId	Nome da chave mestre, utilizada para proteger os blobs, de tamanho máximo MAX_OBJ_ID_FQN_LEN.
[in]	szOTP1	OTP a ser verificado de tamanho mínimo ISSUE_OATH_MIN_OTP_LEN e máximo ISSUE_OATH_MAX_OTP_LEN.
[in]	szOTP2	Segundo OTP a ser verificado de tamanho mínimo ISSUE_OATH_MIN_OTP_LEN e máximo ISSUE_OATH_MAX_OTP_LEN.
[in,out]	pbOATHBlob	Ponteiro para um buffer contendo o blob a ser sincronizado. Este buffer será reescrito com o buffer sincronizado.
[in,out]	pdwOATHBlobLen	Tamanho do buffer `pbOATHBlob`. Na entrada conterá o tamanho de `pbOATHBlob` e na saída o tamanho de dados escritos em `pbOATHBlob`.
[in]	dwFlags	Aceita a flag OATH_UPDATE_BLOB, para permitir a atualização do formato do OATH blob. Quando a flag OATH_UPDATE_BLOB é utilizada, deve-se passar o OATH blob atual em `pbOATHBlob` em um buffer suficientemente grande para comportar o blob atualizado. `pdwOATHBlobLen` deverá conter o valor do tamanho do buffer passado em `pbOATHBlob`. O tamanho de `pbOATHBlob` necessário, é retornado em `pdwOATHBlobLen` na chamada onde o erro D_OATH_BLOB_UPDATE é retornado. A atualização precisa ser apenas feita após receber o erro D_OATH_BLOB_UPDATE. Ver Anotações para mais detalhes.

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

Anotações: A partir da versão 4.0.2 do firmware a janela será estendida em 200 intervalos para mais e para menos. No caso de tokens HOTP os intervalos serão contados por quantidade de eventos, no caso dos tokens TOTP serão contados por quantidade de time-steps. Caso seja retornado o erro D_OATH_BLOB_UPDATE a função retornará em pdwOATHBlobLen o tamanho do buffer que deverá ser utilizado para atualização do OATH blob em uma chamada posterior. Ver detalhes na especificação de OATH_UPDATE_BLOB.

◆ DOATHPskcTranslate()

int AAP_API DOATHPskcTranslate	(	HSESSIONCTX	hSession,
		char *	szMasterKey,
		BYTE *	pbPSK,
		BYTE	bPSKLen,
		BYTE *	pbPSKC,
		DWORD	dwPSKCLen,
		void **	pvBlobList,
		DWORD *	pdwBlobListQuantity,
		DWORD	dwParam )

#include <dinamo.h>

Importa sementes envelopadas no padrão PSKC (Portable Symmetric Key Container), RFC 6030.

Parâmetros

[in]	hSession	Contexto adquirido através da função DOpenSession().
[in]	szMasterKey	Nome da chave mestre, utilizada para proteger os blobs, de tamanho máximo MAX_OBJ_ID_FQN_LEN de saída.
[in]	pbPSK	Buffer de tamanho máximo OATH_MAX_PSK_LEN contendo a chave de transporte que protege as sementes informadas em `pbPSKC`.
[in]	bPSKLen	Tamanho do buffer pbPSK.
[in]	pbPSKC	Buffer PSKC contendo as sementes que serão transformadas em blobs no formato do HSM.
[in]	dwPSKCLen	Tamanho do buffer pbPSKC.
[out]	pvBlobList	Ponteiro para ponteiro que apontará para um buffer alocado internamente contendo um array de estruturas OATH_PSKC_TRANSLATE_OUTPUT. Esta estrutura conterá internamente os blobs das sementes traduzidas para o formato do HSM e o identificador de cada semente como na tag "<pskc:Key Id=>".
[out]	pdwBlobListQuantity	Ponteiro para a quantidade de blobs retornados no buffer `pvBlobList`.
[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.