Descrição detalhada

Autenticação padrão OATH.

Iniciativa OATH

A iniciativa OATH (Open Authentication) é um colaboração suportada por diversos membros da indústria de segurança para desenvolver uma arquitetura aberta e interoperável de autenticação forte. Este objetivo é conseguido pela definição de padrões abertos disponíveis para todos.

O ecossistema OATH é composto de fabricantes de dispositivos (tokens, chips, smart cards, computadores, celulares, PDAs. tablets), fabricantes de plataformas (serviços web, gerenciadores de identidade, servidores de aplicação, sistemas de federação de identificação), fabricantes de aplicações (VPN, CRM, ERP, DRM, comércio eletrônico, roaming, wi-fi) e integradores de sistema (ISPs, órgãos de governo, bandeiras de cartão de crédito, etc).

Módulo OATH

O HSM pode ser utilizado como gerador de sementes OATH e como autenticador de OTPs (One Time Password). A implementação do HSM está de acordo com os padrões listados abaixo.

Por prover uma fronteira criptográfica segura, ambiente controlado e algoritmos homologados o HSM apresenta vantagens na sua adoção em sistema de autenticação forte.

O módulo OATH do HSM tem três serviços básicos: emissão, autenticação e ressincronização:

a emissão consiste da geração da semente pelo HSM, o que promove a emissão de um blob, que é devolvido para a aplicação para guarda em base de dados. Com o blob mantido em base da dados externa ao HSM, o processo de emissão fica bastante flexível, sem gerar carga no HSM, e mantendo o sigilo e a confidencialidade necessária.
o serviço de autenticação do módulo é certamente o mais utilizado no dia a dia da produção. A aplicação quando precisar realizar uma autenticação dever recuperar o blob na base de dados, enviá-lo ao HSM, receber o resultado juntamente com o blob atualizado, para ser devolvido à base de dados.
o serviço de ressincronização consiste basicamente em abrir a janela de tolerância normal, e solicitar que o usuário informe os OTPs n e n+1.

Cenários de Geração e Autenticação

Nos cenários de geração e autenticação descritos abaixo o que muda é a origem da semente e como ela é recebida pela aplicação para criação do blob e enviada ao usuário (como semente ou embarcada em token físico). Uma vez criado o blob a autenticação em qualquer cenário segue sempre o mesmo formato. Nos cenários abaixo não importa se o token é HOTP ou TOTP.

Cenário I: Token: a semente é gerada pelo fabricante do token e enviada em formato PSKC

a. Geração

Aplicação seleciona ou gera uma chave master;
Aplicação recebe arquivo PSKC e chave de transporte;
Aplicação solicita ao HSM tradução do arquivo PSKC para blob;
HSM retorna blob;
Aplicação recebe o blob, cria relação entre blob e usuário e guarda em base de dados;
Aplicação despacha o token físico para o usuário;

b. Autenticação

Vide abaixo;

Cenário II: Token: a semente é gerada pelo fabricante do token e enviada em texto claro

a. Geração

Aplicação seleciona ou gera uma chave master;
Aplicação recebe uma semente em texto claro;
Aplicação prepara uma estrutura de blob OATH;
Aplicação solicita ao HSM criptografia do blob OATH com a chave master;
HSM retorna dado cifrado, que é o blob;
Aplicação recebe o blob, cria relação entre blob e usuário e guarda em base de dados;
Aplicação despacha o token físico para o usuário;

b. Autenticação

Vide abaixo;

Cenário III: Soft Token: a semente é gerada pelo usuário e recebida em texto claro

a. Geração

Aplicação seleciona ou gera uma chave master;
Usuário gera e exporta semente em sua aplicação OATH (smart phone, desktop, etc);
Usuário envia semente para aplicação;
Aplicação recebe uma semente em texto claro;
Aplicação prepara uma estrutura de dados OATH;
Aplicação solicita ao HSM criptografia da estrutura da dados OATH com a chave master;
HSM retorna estrutura cifrada, que é o blob;
Aplicação recebe o blob, cria relação entre blob e usuário e guarda em base de dados;

b. Autenticação

Vide abaixo;

Cenário IV: Soft Token: HSM gera a semente

a. Geração

Aplicação seleciona ou gera uma chave master;
Aplicação solicita emissão de blob OATH;
HSM gera semente, prepara blob e retorna para a aplicação;
Aplicação recebe o blob, cria relação entre blob e usuário e guarda em base de dados;
Aplicação envia o blob para HSM e solicita a semente em texto claro;
Aplicação envia a semente para o usuário, normalmente usando algum canal seguro;
Usuário importa semente para sua aplicação OATH (smart phone, desktop, etc);

b. Autenticação

Vide abaixo;

Autenticação do usuário em qualquer cenário:

Usuário apresenta OTP gerado para aplicação;
Aplicação recupera blob do usuário a partir da base de dados e solicita verificação ao HSM passando blob e OTP;
HSM processa pedido e devolve resultado e o blob processado;
Aplicação recebe o blob e atualiza a base de dados;
Aplicação informa usuário sobre resultado da autenticação;

Glossário

otp: (one time password), senha de uso único
token: dispositivo físico gerador de otp a partir de uma semente, normalmente identificado através de número serial único e com tamanho de um chaveiro. É resistente à violação.
soft token: dispositivo gerador de otp em software, normalmente instalado em dispositivo móvel. É menos seguro que o token físico.
semente: sequência aleatória de bytes usado como material criptográfico diversificador para a geração de otp. Deve ser mantida secreta, desde a geração até a utilização, incluindo o transporte. Cada token ou soft token deve ser associado a uma única semente.
time step: intervalo utilizado como incremento do cálculo TOTP de cada OTP. O tempo em segundos entre cada geração de OTP.
moving factor: intervalo utilizado como incremento do cálculo HOTP de cada OTP. Contado por eventos.
T0: valor UNIX time (segundos desde o EPOCH time) para iniciar a contagem de time steps.
truncation offset: método de truncagem do cálculo HMAC para extração do OTP.
HOTP: (HMAC-based One-time Password Algorithm) padrão de geração de otp a por evento, normalmente disparado pelo usuário, como por exemplo o apertar de um botão no token, ou seja, a cada vez que o usuário pressiona o botão no token, um novo otp é gerado.
TOTP: (Time-based One-time Password Algorithm) padrão de geração de otp por tempo; um novo otp é gerado a cada intervalo definido pelo token, independente de ação de usuário.
blob: (binary large object), estrutura criptografada contendo informações para autenticação de otp.O blob é totalmente opaco fora do HSM. A chave que criptografa o blob é uma AES (128, 192 ou 256 bits). Entre as informações que vão no blob estão a semente, o tipo (HOTP ou TOTP), intervalo de geração e tempo inicial (no caso de TOTP) e mecanismos de proteção contra ataque de replay.
resync: processo de ajuste dos contadores internos de um blob com os valores gerados pelo token físico ou soft token que visa manter a autenticação funcionando corretamente. Normalmente este processo é feito aumentando temporariamente a janela de tolerância e busca de valores de otp pelo HSM, com o usuário informando dois ou mais otps gerados em sequência pelo token.
chave master: chave AES no HSM que criptografa o blob.
chave de transporte: chave que criptografa as sementes correspondentes aos tokens conforme o padrão PSKC, para o transporte entre o fabricante do token e o integrador de sistemas. Normalmente é derivada de senha.
pskc: (Portable Symmetric Key Container), padrão de transporte e entrega segura de sementes, baseado em criptografia simétrica com derivação de chave por senha e formato XML.
tradução pskc: processo de importação das sementes em formato PSKC, decriptografia e geração de blobs individuais para armazenamento em base de dados. O processo de tradução da decriptografia do formato PSKC e criptografia no blob é realizado dentro do HSM. Normalmente um arquivo PSKC contém diversas sementes cifradas sob a mesma chave de transporte; a cada semente irá corresponder um blob.
base de dados: estrutura para armazenamento dos blobs gerados pelo HSM. Pode ser por exemplo um sistema de arquivos ou um SGBD (Sistema de Gerenciamento de Banco de Dados). Não há necessidade de proteção adicional para o blob armazenado, pois seu conteúdo só pode ser acessado com a chave master AES no HSM.

Referências

Inciativa OATH
OATH Reference Architecture Version 2.0
HOTP: An HMAC-Based OTP Algorithm RFC 4226
TOTP - Time-based One-time Password Algorithm RFC 6238
PSKC - Portable Symmetric Key Container, RFC 6030

Autenticação padrão OATH. Mais...

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.