TOTP

Generador de contraseñas de un solo uso basadas en el tiempo, según la norma RFC 6238. Sirve para producir códigos de verificación cambiantes, lo habitual en la autenticación de dos factores (2FA).

API

TOTP.generate

Genera una contraseña de un solo uso basada en el tiempo.

Devuelve

Argumento	Descripción	Tipo
Object	Un objeto con la OTP y su caducidad	{ otp: string, expires: number }
otp	La contraseña de un solo uso generada	string
expires	Marca de tiempo (en ms) en que la OTP caduca	number

Parámetros

Parámetro	Descripción	Tipo	Por defecto
key	La clave secreta, como cadena codificada en Base32	string	Obligatorio
options	Configuración opcional	Options	Véase abajo

Opciones

Parámetro	Descripción	Tipo	Por defecto
digits	Número de dígitos de la OTP	number	6
algorithm	Algoritmo de hash	'SHA-1' | 'SHA-224' | 'SHA-256' | 'SHA-384' | 'SHA-512' | 'SHA3-224' | 'SHA3-256' | 'SHA3-384' | 'SHA3-512'	'SHA-1'
period	Duración de la ventana de tiempo (segundos)	number	30
timestamp	Marca de tiempo (en ms) con la que se genera la OTP	number	Date.now()

Ejemplo

Uso básico

import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP'; // clave secreta codificada en Base32
const result = TOTP.generate(secret);

console.log(result.otp); // por ejemplo: '341128'
console.log(result.expires); // por ejemplo: 1465324730000 (marca de tiempo)

Cambiar el número de dígitos

import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP';
const result = TOTP.generate(secret, { digits: 8 });

console.log(result.otp); // por ejemplo: '43341128' (8 dígitos)

Cambiar la ventana de tiempo

import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP';
const result = TOTP.generate(secret, { period: 60 }); // ventana de 60 segundos

console.log(result.otp);
console.log(result.expires);

Usar otro algoritmo de hash

import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP';
const result = TOTP.generate(secret, { algorithm: 'SHA-512' });

console.log(result.otp);

Generar la OTP con una marca de tiempo concreta

import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP';
const timestamp = 1465324707000; // marca de tiempo del 2016-06-08
const result = TOTP.generate(secret, { timestamp });

console.log(result.otp); // OTP generada a partir de esa marca de tiempo

Combinar varias opciones

import { TOTP } from 'ranuts';

const secret = 'JBSWY3DPEHPK3PXP';
const result = TOTP.generate(secret, {
  digits: 8,
  algorithm: 'SHA-256',
  period: 60,
});

console.log(result.otp);
console.log(result.expires);

Notas

1. Formato de la clave: la clave ha de ser una cadena codificada en Base32. Si contiene caracteres que no valen, se lanza el error 'Invalid base32 character in key'.

2. Sincronía de los relojes: TOTP depende de que los relojes vayan a la par. Asegúrate de que la hora del cliente y la del servidor coinciden, o la verificación puede fallar.

3. Caducidad: expires devuelve la marca de tiempo en que termina la ventana actual. Al verificar suele admitirse una holgura de una ventana (±1 periodo, por ejemplo).

4. Seguridad: las claves deben guardarse a buen recaudo y nunca escribirse a fuego en el código. Conviene usar variables de entorno o un sistema seguro de gestión de claves.