`$totp.validate`¶

Description¶

Vérifie un token TOTP.

Syntaxe¶

$totp.validate( secretKey , token [ , options ] )

Paramètres¶

secretKey string

Clé secrète TOTP

token string

Token à vérifier

options string

Paramètres de configuration du validateur. Les options reconnues sont données ci-après.

timestamp string

Timestamp pour lequel le code droit être généré.

window number

Valeur entière représentant la fenêtre de tolérance pour la validation de tokens passés ou futurs.

Ce paramètre a pour but de gérer le décalage d'horloge qu'il peut y avoir entre le serveur et le périphérique depuis lequel le token est généré. Plus la valeur du paramètre est élevé, plus la tolérance est grande.

La table suivante donne un aperçu des tolérances appliquées en fonction de la valeur de window dans le cas où un token a une durée de validité de 30 secondes:

Valeur `window`	Tolérance min	Tolérance max
0 ou 1	0	0
2	0	30 sec
3	-30 sec	30 sec
4	-30 sec	60 sec
5	-60 sec	60 sec
6	-60 sec	90 sec
7	-90 sec	90 sec
8	-90 sec	120 sec
9	-120 sec	120 sec

La valeur par défaut est 3. Ainsi dans ce cas, le token reçu est vérifié pour les timestamps correspondant à now - 30 sec, now et now + 30 sec.

timeStep number

Période de validité d'un token en secondes. Par défaut la durée est de 30 secondes.

length number

Taille des tokens à traiter. La taille par défaut est de 6 chiffres. La taille doit être comprise entre 6 et 8 chiffres.

algo string

Fonction cryptographique utilisée pour gérer la clé secrète. Les valeurs possibles sont "HmacSHA1", "HmacSHA256" et "HmacSHA512".

La valeur par défaut est "HmacSHA1".

Retour¶

Retourne true si le token est valide, sinon false.

Exemple¶

Illustration de la tolérance : le token est comparé aux tokens valables à T-30, T et T+30 secondes. Dans l'exemple, les tests réalisés à t0 et t15 sont donc toujours true. Le test réalisé à t45 est true s'il est réalisé dans la première moitié de la période (15 premières secondes de validité du token) et false ensuite. Le test réalisé à t65 est toujours false.

var key = $totp.genKey();
var code = $totp.getCode(key);

var t0 = $cal.timestamp();
var t15 = $cal.add($cal.timestamp(), 15, "sec");
var t45 = $cal.add($cal.timestamp(), 45, "sec");
var t65 = $cal.add($cal.timestamp(), 65, "sec");

$logger.info(" 0 : " & $totp.validate(key, code, { timestamp: t0 }));   // retourne true
$logger.info("15 : " & $totp.validate(key, code, { timestamp: t15 }));  // retourne true
$logger.info("45 : " & $totp.validate(key, code, { timestamp: t45 }));  // retourne true/false
$logger.info("65 : " & $totp.validate(key, code, { timestamp: t65 }));  // retourne false

Même exemple sans tolérance : au-delà de 30 secondes, le token n'est plus valide. Ainsi dans l'exemple, le test réalisé à t0 est toujours true. Le test réalisé à t15 est true dans la première moitié de la période (15 premières secondes de validité du token) et false ensuite. Les tests réalisés à t45 et t65 sont toujours false.

var key = $totp.genKey();
var code = $totp.getCode(key);

var t0 = $cal.timestamp();
var t15 = $cal.add($cal.timestamp(), 15, "sec");
var t45 = $cal.add($cal.timestamp(), 45, "sec");
var t65 = $cal.add($cal.timestamp(), 65, "sec");

$logger.info(" 0 : " & $totp.validate(key, code, { window: 0, timestamp: t0 }));   // retourne true
$logger.info("15 : " & $totp.validate(key, code, { window: 0, timestamp: t15 }));  // retourne true/false
$logger.info("45 : " & $totp.validate(key, code, { window: 0, timestamp: t45 }));  // retourne false
$logger.info("65 : " & $totp.validate(key, code, { window: 0, timestamp: t65 }));  // retourne false

$totp.validate¶