nginstack

Class: TOTP

@nginstack/engine/lib/otp/TOTP~ TOTP

new TOTP()

Classe que agrupa funções de geração e verificação de senhas de uso único baseadas em tempo TOTP (Time-based One-Time Password), conforme RFC 6238.

As chaves informadas nos métodos desta classe devem ser uma sequência de bytes aleatórios ou devem ser geradas por algoritmos de derivação de chaves para fins criptográficos. Elas devem ter um tamanho adequado para o algoritmo de hash adotado e devem ser mantidas em segredo, devendo ser compartilhadas apenas com o gerador e o verificador de senhas.

Esta classe trata as strings como se fossem uma sequência de bytes no formato conhecido como Binary String. É importante observar que a codificação adotada pode ser diferente em outras plataformas, como o Node.js. Para garantir compatibilidade com as senhas geradas por outras plataformas, prefira sempre informar valores do tipo Uint8Array ou ArrayBuffer, evitando a codificação implícita das strings.

Example
const TOTP = require('@nginstack/engine/lib/otp/TOTP.js');
const Crypto = require('@nginstack/engine/lib/crypto/Crypto.js');

const secret = Crypto.randomBytes(20, 'uint8array');
const token = TOTP.generate(secret);
TOTP.verify(token, secret); // >= true

Methods

<static> formatKeyUri(key, userName, issuer [, options])

Formata a chave (segredo compartilhado) em uma URI utilizando o esquema otpauth.

Essa URI pode ser codificada em um QRCode para que possa ser aberta por aplicativos autenticadores, como o Google Authenticator ou o Microsoft Authenticator, permitindo que esses aplicativos possam ser utilizados para gerar as senhas de uso único associadas à chave informada.

Parameters:
Name Type Argument Description
key string | Uint8Array | ArrayBuffer

Chave única que deve ser mantida em segredo e será utilizada pelo algoritmo HMAC para gerar a senha de uso único.
userName string

Nome do usuário que será autenticado.
issuer string

Identificação do sistema. Caso a chave seja utilizada para autenticar usuários do sistema, é recomendado que o nome da base de dados faça parte da identificação do sistema, pois é comum que um usuário se conecte a mais de uma base de dados, como as de produção, homologação e desenvolvimento.
options TOTPOptions <optional>

Parâmetros opcionais do algoritmo TOTP.

<static> generate(key [, options])

Cria uma senha de uso único que pode ser verificada pelo método #verify ou por outros aplicativos que implementem o algoritmo TOTP.

Parameters:
Name Type Argument Description
key string | Uint8Array | ArrayBuffer

Chave única que deve ser mantida em segredo e será utilizada pelo algoritmo HMAC para gerar a senha de uso único.
options TOTPOptions <optional>

Parâmetros opcionais do algoritmo TOTP.
Returns:

Senha de utilização única.

Type
string

<static> verify(otp, key [, options])

Verifica se uma senha de uso único é válida.

É importante garantir que uma senha de uso único verificada por este método não seja reutilizada em mais de uma autenticação, sendo necessário forçar o usuário a aguardar a geração de uma nova senha para realizar uma nova autenticação.

Parameters:
Name Type Argument Description
otp string

Senha de uso único que deverá ser verificada.
key string | Uint8Array | ArrayBuffer

Chave única que deve ser mantida em segredo e será utilizada pelo algoritmo HMAC para gerar a senha de uso único.
options TOTPOptions <optional>

Parâmetros opcionais do algoritmo TOTP.
Returns:

True se a senha informada for válida.

Type
boolean