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

Funções
bool	OATHCheck (string masterKeyId, string otp, ref byte[] bBlob)
	Check OTP value.

bool	OATHCheck (string masterKeyId, string otp, ref byte[] bBlob, int dwFlag)
	Check OTP value.

bool	OATHCheck (string masterKeyId, string otp, byte[] bBlob)

bool	OATHCheck (string masterKeyId, string otp, byte[] bBlob, int dwFlag)

byte[]	OATHBlobResync (string szMasterKeyId, string szOTP1, string szOTP2, byte[] bOATHBlob)
	Re-sincroniza um blob OATH através da apresentação de dois valores de OTP contínuos.

byte[]	OATHGetKey (string szMasterKey, byte[] pbInBlob)
	Recupera a semente da chave geradora do blob de OATH.

DinamoApi.OATH_PSKC_TRANSLATE_OUTPUT[]	OATHPskcTranslate (string szMasterKeyId, string szPSK, byte[] pbPSKC)
	Importa sementes envelopadas no padrão PSKC (Portable Symmetric Key Container), RFC 6030.

byte[]	OATHIssueGenerateHOTP (string szMasterKeyId)
	Gera um blob HOATH, ou seja, um token de evento. A semente será gerada de forma aleatória pelo HSM.

byte[]	OATHIssueGenerateHOTP (string szMasterKeyId, byte seedLen)
	Gera um blob HOATH, ou seja, um token de evento a partir de um tamanho de semente.

byte[]	OATHIssueImportHOTP (string szMasterKeyId, byte[] bSeed)
	Immporta um blob HOATH, ou seja, um token de evento a partir de uma semente fornecida.

byte[]	OATHIssueGenerateTOTP (string szMasterKeyId)
	Gera um blob TOTP, ou seja, um token de evento. A semente será gerada de forma aleatória pelo HSM.

byte[]	OATHIssueGenerateTOTP (string szMasterKeyId, short step)
	Gera um blob TOTP, ou seja, um token de evento. A semente será gerada de forma aleatória pelo HSM.

byte[]	OATHIssueGenerateTOTP (string szMasterKeyId, short step, ulong offset)
	Gera um blob TOTP, ou seja, um token de evento. A semente será gerada de forma aleatória pelo HSM.

byte[]	OATHIssueGenerateTOTP (string szMasterKeyId, short step, ulong offset, byte seedLen)
	Gera um blob TOTP, ou seja, um token de evento. A semente será gerada de forma aleatória pelo HSM.

byte[]	OATHIssueImportTOTP (string szMasterKeyId, byte[] bSeed)
	Immporta um blob TOTP, ou seja, um token de evento a partir de uma semente fornecida.

byte[]	OATHIssueImportTOTP (string szMasterKeyId, byte[] bSeed, short step)
	Immporta um blob TOTP, ou seja, um token de evento a partir de uma semente fornecida.

byte[]	OATHIssueImportTOTP (string szMasterKeyId, byte[] bSeed, short step, ulong offset)
	Importa um blob TOTP, ou seja, um token de evento a partir de uma semente fornecida.

string	EncodeBase32 (byte[] data)
	Função utilitária para codificar Base32. Codificação padrão para geradores de OATH em sofware.

string	OATHGetNext (string szMasterKeyId, byte lenOTP, byte[] bBlob)
	Recupera o próximo valor para o OTP.

Funções

◆ OATHCheck() [1/4]

bool OATHCheck	(	string	masterKeyId,
		string	otp,
		ref byte[]	bBlob )

inline

Check OTP value.

Parâmetros

masterKeyId	Nome da chave mestre, utilizada para proteger os blobs, de tamanho máximo DinamoApi.MAX_OBJ_ID_FQN_LEN.
otp	OTP a ser verificado de tamanho mínimo DinamoApi.ISSUE_OATH_MIN_OTP_LEN e máximo DinamoApi.ISSUE_OATH_MAX_OTP_LEN.
bBlob	Array de bytes contendo o blob que será utilizado para a geração do OTP. Este buffer será reescrito com o blob atualizado.

Exceções

DinamoException.DinamoException Em caso de erro

Retorna: >Verdadeiro se o OTP passado no parâmetro da função for válido. Nesse caso, é importante a persistência do bBlob retornado para evitar ataques de REPLAY.

Exemplos: oath.cs.

◆ OATHCheck() [2/4]

bool OATHCheck	(	string	masterKeyId,
		string	otp,
		ref byte[]	bBlob,
		int	dwFlag )

inline

Check OTP value.

Parâmetros

masterKeyId Nome da chave mestre, utilizada para proteger os blobs, de tamanho máximo DinamoApi.MAX_OBJ_ID_FQN_LEN.

otp OTP a ser verificado de tamanho mínimo DinamoApi.ISSUE_OATH_MIN_OTP_LEN e máximo DinamoApi.ISSUE_OATH_MAX_OTP_LEN.

bBlob Array de bytes contendo o blob que será utilizado para a geração do OTP. Este buffer será reescrito com o blob atualizado.

dwFlag

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.
DinamoApi.MAX_OTP_LOOK_AHEAD_INTERVAL	Define o valor da janela de look-ahead de autenticação.

Retorna: Verdadeiro se o OTP passado no parâmetro da função for válido. Nesse caso, é importante a persistência do bBlob retornado para evitar ataques de REPLAY.

Exceções

DinamoException.DinamoException Em caso de erro

◆ OATHCheck() [3/4]

bool OATHCheck	(	string	masterKeyId,
		string	otp,
		byte[]	bBlob )

inline

Obsoleto(a): Usar OATHCheck com bBlob como referência.

◆ OATHCheck() [4/4]

bool OATHCheck	(	string	masterKeyId,
		string	otp,
		byte[]	bBlob,
		int	dwFlag )

inline

Obsoleto(a): Usar OATHCheck com bBlob como referência.

◆ OATHBlobResync()

byte[] OATHBlobResync	(	string	szMasterKeyId,
		string	szOTP1,
		string	szOTP2,
		byte[]	bOATHBlob )

inline

Re-sincroniza um blob OATH através da apresentação de dois valores de OTP contínuos.

Parâmetros

szMasterKeyId	Nome da chave mestre, utilizada para proteger os blobs, de tamanho máximo DinamoApi.MAX_OBJ_ID_FQN_LEN.
szOTP1	Primeiro valor do OATH.
szOTP2	Segundo valor do OATH
bOATHBlob	Blob do OATH

Retorna: Blob do OATH resincronizado, resultado da operação.

Exceções

DinamoException.DinamoException Em caso de erro

◆ OATHGetKey()

byte[] OATHGetKey	(	string	szMasterKey,
		byte[]	pbInBlob )

inline

Recupera a semente da chave geradora do blob de OATH.

Parâmetros

szMasterKey	Nome da chave mestre, utilizada para proteger os blobs, de tamanho máximo DinamoApi.MAX_OBJ_ID_FQN_LEN.
pbInBlob	Conteúdo do blob

Retorna: Semente da chave na forma de array de bytes.

Exceções

DinamoException.DinamoException Em caso de erro

Exemplos: oath.cs.

◆ OATHPskcTranslate()

DinamoApi.OATH_PSKC_TRANSLATE_OUTPUT[] OATHPskcTranslate	(	string	szMasterKeyId,
		string	szPSK,
		byte[]	pbPSKC )

inline

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

Parâmetros

szMasterKeyId	Nome da chave mestre, utilizada para proteger os blobs, de tamanho máximo DinamoApi.MAX_OBJ_ID_FQN_LEN.
szPSK	Chave de transporte que protege as sementes informadas em pbPSKC.
pbPSKC	Conteúdo do arquivo contendo as sementes que serão transformadas em blobs no formato do HSM

Retorna: Array de estruturas DinamoApi.OATH_PSKC_TRANSLATE_OUTPUT. Esta estrutura conterá internamente os blobs das sementes traduzidas para o formato do HSM e o identificador de cada semente.

Exceções

DinamoException.DinamoException Em caso de erro

◆ OATHIssueGenerateHOTP() [1/2]

byte[] OATHIssueGenerateHOTP ( string szMasterKeyId )

inline

Gera um blob HOATH, ou seja, um token de evento. A semente será gerada de forma aleatória pelo HSM.

Parâmetros

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

Retorna: Blob do OATH, resultado da operação.

Exceções

DinamoException.DinamoException Em caso de erro

Esta função é utilizada quando é possível atribuir uma semente a um soft token. Será gerada uma semente com o tamanho de um SHA1

◆ OATHIssueGenerateHOTP() [2/2]

byte[] OATHIssueGenerateHOTP	(	string	szMasterKeyId,
		byte	seedLen )

inline

Gera um blob HOATH, ou seja, um token de evento a partir de um tamanho de semente.

Parâmetros

szMasterKeyId	Nome da chave mestre, utilizada para proteger os blobs, de tamanho máximo DinamoApi.MAX_OBJ_ID_FQN_LEN
seedLen	Semente no formato binário.

Retorna: Blob do OATH, resultado da operação.

Exceções

DinamoException.DinamoException Em caso de erro

Esta função é utilizada quando a semente é fornecida por um dispositivo de software soft token (por exemplo um app de celular) ou de hadware hard_token (por exemplo um chaveiro gerador de sequencia)

◆ OATHIssueImportHOTP()

byte[] OATHIssueImportHOTP	(	string	szMasterKeyId,
		byte[]	bSeed )

inline

Immporta um blob HOATH, ou seja, um token de evento a partir de uma semente fornecida.

Parâmetros

szMasterKeyId	Nome da chave mestre, utilizada para proteger os blobs, de tamanho máximo DinamoApi.MAX_OBJ_ID_FQN_LEN
bSeed	Semente no formato binário.

Exceções

DinamoException.DinamoException Em caso de erro

Retorna: Blob do OATH, resultado da operação.

◆ OATHIssueGenerateTOTP() [1/4]

byte[] OATHIssueGenerateTOTP ( string szMasterKeyId )

inline

Gera um blob TOTP, ou seja, um token de evento. A semente será gerada de forma aleatória pelo HSM.

Parâmetros

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

Retorna: Blob do OATH, resultado da operação.

Exceções

DinamoException Em caso de erro

Esta função é utilizada quando é possível atribuir uma semente a um soft token

Exemplos: oath.cs.

◆ OATHIssueGenerateTOTP() [2/4]

byte[] OATHIssueGenerateTOTP	(	string	szMasterKeyId,
		short	step )

inline

Gera um blob TOTP, ou seja, um token de evento. A semente será gerada de forma aleatória pelo HSM.

Parâmetros

szMasterKeyId	Nome da chave mestre, utilizada para proteger os blobs, de tamanho máximo DinamoApi.MAX_OBJ_ID_FQN_LEN
step	Intevalo de tempo usado no cálculo, também conhecido como janela de tempo para mudança de valor.

Retorna: Blob do OATH, resultado da operação.

Exceções

DinamoException.DinamoException Em caso de erro

◆ OATHIssueGenerateTOTP() [3/4]

byte[] OATHIssueGenerateTOTP	(	string	szMasterKeyId,
		short	step,
		ulong	offset )

inline

Gera um blob TOTP, ou seja, um token de evento. A semente será gerada de forma aleatória pelo HSM.

Parâmetros

szMasterKeyId	Nome da chave mestre, utilizada para proteger os blobs, de tamanho máximo DinamoApi.MAX_OBJ_ID_FQN_LEN
step	Intevalo de tempo usado no cálculo, também conhecido como janela de tempo para mudança de valor.
offset	Atraso do relógio a ser considerado.

Retorna: Blob do OATH, resultado da operação.

Exceções

DinamoException Em caso de erro

◆ OATHIssueGenerateTOTP() [4/4]

byte[] OATHIssueGenerateTOTP	(	string	szMasterKeyId,
		short	step,
		ulong	offset,
		byte	seedLen )

inline

Gera um blob TOTP, ou seja, um token de evento. A semente será gerada de forma aleatória pelo HSM.

Parâmetros

szMasterKeyId	Nome da chave mestre, utilizada para proteger os blobs, de tamanho máximo DinamoApi.MAX_OBJ_ID_FQN_LEN
step	Intevalo de tempo usado no cálculo, também conhecido como janela de tempo para mudança de valor.
offset	Atraso do relógio a ser considerado.
seedLen	Tamanho da semente.

Retorna: Blob do OATH, resultado da operação.

Exceções

DinamoException Em caso de erro

◆ OATHIssueImportTOTP() [1/3]

byte[] OATHIssueImportTOTP	(	string	szMasterKeyId,
		byte[]	bSeed )

inline

Immporta um blob TOTP, ou seja, um token de evento a partir de uma semente fornecida.

Parâmetros

szMasterKeyId	Nome da chave mestre, utilizada para proteger os blobs, de tamanho máximo DinamoApi.MAX_OBJ_ID_FQN_LEN
bSeed	Semente no formato binário.

Retorna: Blob do OATH, resultado da operação.

Exceções

DinamoException.DinamoException Em caso de erro

◆ OATHIssueImportTOTP() [2/3]

byte[] OATHIssueImportTOTP	(	string	szMasterKeyId,
		byte[]	bSeed,
		short	step )

inline

Immporta um blob TOTP, ou seja, um token de evento a partir de uma semente fornecida.

Parâmetros

szMasterKeyId	Nome da chave mestre, utilizada para proteger os blobs, de tamanho máximo DinamoApi.MAX_OBJ_ID_FQN_LEN
bSeed	Semente no formato binário.
step	Intevalo de tempo usado no cálculo, também conhecido como janela de tempo para mudança de valor.

Retorna: Blob do OATH, resultado da operação.

Exceções

DinamoException.DinamoException Em caso de erro

◆ OATHIssueImportTOTP() [3/3]

byte[] OATHIssueImportTOTP	(	string	szMasterKeyId,
		byte[]	bSeed,
		short	step,
		ulong	offset )

inline

Importa um blob TOTP, ou seja, um token de evento a partir de uma semente fornecida.

Parâmetros

szMasterKeyId	Nome da chave mestre, utilizada para proteger os blobs, de tamanho máximo DinamoApi.MAX_OBJ_ID_FQN_LEN
bSeed	Semente no formato binário.
step	Intevalo de tempo usado no cálculo, também conhecido como janela de tempo para mudança de valor.
offset	Atraso do relógio a ser considerado.

Retorna: Blob do OATH, resultado da operação.

Exceções

DinamoException.DinamoException Em caso de erro

◆ EncodeBase32()

string EncodeBase32 ( byte[] data )

inline

Função utilitária para codificar Base32. Codificação padrão para geradores de OATH em sofware.

Derived from https://github.com/google/google-authenticator-android/blob/master/AuthenticatorApp/src/main/java/com/google/android/apps/authenticator/Base32String.java

Parâmetros

data	Semente gerada

Retorna: Dados codificados em BASE32.

Exemplos: oath.cs.

◆ OATHGetNext()

string OATHGetNext	(	string	szMasterKeyId,
		byte	lenOTP,
		byte[]	bBlob )

inline

Recupera o próximo valor para o OTP.

Parâmetros

szMasterKeyId	Nome da chave mestre, utilizada para proteger os blobs, de tamanho máximo DinamoApi.MAX_OBJ_ID_FQN_LEN
lenOTP	Tamanho do OTP que será gerado, podendo ser um valor entre DinamoApi.ISSUE_OATH_MIN_OTP_LEN e DinamoApi.ISSUE_OATH_MAX_OTP_LEN.
bBlob	Array de bytes contendo o blob que será utilizado para a geração do OTP.

Retorna: Valor do próximo token

Exceções

DinamoException Lança exceção em caso de erro.