-
Notifications
You must be signed in to change notification settings - Fork 228
General Usage for Time Based Token
◄ Back (Verify The Token)
Next (General Usage for Counter-Based Token) ►
var speakeasy = require("speakeasy");
// Generate a secret key.
var secret = speakeasy.generateSecret({length: 20});
// secret key is 20 characters long
// Access using secret.ascii, secret.hex, or secret.base32.
// Generate a time-based token based on the base-32 key.
// HOTP (counter-based tokens) can also be used if `totp` is replaced by
// `hotp` (i.e. speakeasy.hotp()) and a `counter` is given in the options.
var token = speakeasy.totp({
secret: secret.base32,
encoding: 'base32'
});
// Returns token for the secret at the current time
// Compare this to user input
// Verify a given token
var tokenValidates = speakeasy.totp.verify({
secret: secret.base32,
encoding: 'base32',
token: '123456',
window: 6
});
// Returns true if the token matches
A TOTP is incremented every step
time-step seconds. By default, the time-step
is 30 seconds. You may change the time-step using the step
option, with units
in seconds.
// Verify a given token is within 3 time-steps (+/- 2 minutes) from the server
// time-step.
var tokenDelta = speakeasy.totp.verifyDelta({
secret: secret.base32,
encoding: 'base32',
token: '123456',
window: 2,
step: 60
});
// Returns {delta: 0} where the delta is the time step difference
// between the given token and the current time
var token = speakeasy.totp({
secret: secret.base32,
encoding: 'base32',
time: 1453667708 // specified in seconds
});
// Verify a time-based token for a custom time
var tokenValidates = speakeasy.totp.verify({
secret: secret.base32,
encoding: 'base32',
token: token,
time: 1453667708
});
The default encoding (when encoding
is not specified) is ascii
.
// Specifying an ASCII token for TOTP
// (encoding is 'ascii' by default)
var token = speakeasy.totp({
secret: secret.ascii
});
// Specifying a hex token for TOTP
var token = speakeasy.totp({
secret: secret.hex,
encoding: 'hex'
});
The default hash algorithm is SHA1.
// Specifying SHA256
var token = speakeasy.totp({
secret: secret.ascii,
algorithm: 'sha256'
});
// Specifying SHA512
var token = speakeasy.totp({
secret: secret.ascii,
algorithm: 'sha512'
});
// Generate a secret, if needed
var secret = speakeasy.generateSecret();
// By default, generateSecret() returns an otpauth_url for totp, SHA1 and
// 'SecretKey' label
// otpauth:https://totp/SecretKey?secret=<secret>
// Use otpauthURL() to get a custom authentication URL for SHA512
var url = speakeasy.otpauthURL({ secret: secret.ascii, label: 'Name of Secret',
algorithm: 'sha512' });
// otpauth:https://totp/Name%20of%20Secret?secret=<secret>&algorithm=SHA512
// Use otpauthURL() to get a custom authentication URL for SHA512, issuer
// and digits
var url = speakeasy.otpauthURL({ secret: secret.base32, label: 'Name of Secret',
algorithm: 'sha512', issuer:'Company', digits: 6, encoding: 'base32' });
// otpauth:https://totp/Name%20of%20Secret?secret=<secret>&issuer=Company&algorithm=SHA512&digits=6
// Pass URL into a QR code generator
How this works:
Verify a TOTP token at the current time with a window of 2. Since the default time step is 30 seconds, and TOTP has a two-sided window, this will check tokens between [current time minus two tokens before] and [current time plus two tokens after]. In other words, with a time step of 30 seconds, it will check the token at the current time, plus the tokens at the current time minus 30 seconds, minus 60 seconds, plus 30 seconds, and plus 60 seconds – basically, it will check tokens between a minute ago and a minute from now. It will return a { delta: n }
where n
is the difference between the current time step and the counter position at which the token was found, or undefined
if it was not found within the window. See the totp․verifyDelta(options)
documentation for more info.
var verified = speakeasy.totp.verifyDelta({
secret: secret.ascii,
token: '123456',
window: 2
});
The mechanics of TOTP windows are the same as for HOTP, as shown above, just with two-sided windows, meaning that the delta
value can be negative if the token is found before the given time or counter.
var secret = 'rNONHRni6BAk7y2TiKrv';
// By way of example, we will force TOTP to return tokens at time 1453853945
// and at time 1453854005 (60 seconds ahead, or 2 steps ahead)
var token1 = speakeasy.totp({ secret: secret, time: 1453853945 }); // 625175
var token3 = speakeasy.totp({ secret: secret, time: 1453854005 }); // 222636
var token2 = speakeasy.totp({ secret: secret, time: 1453854065 }); // 013052
// We can check the time at token 3, 1453853975, with token 1, but use a window
// of 2 With a time step of 30 seconds, this will check all tokens from 60
// seconds before the time to 60 seconds after the time
speakeasy.totp.verifyDelta({ secret: secret, token: token1, window: 2,
time: 1453854005 });
// => { delta: -2 }
// token is valid because because token is 60 seconds before time
speakeasy.totp.verify({ secret: secret, token: token1, window: 2, time: 1453854005 });
// => true
// token is valid because because token is 0 seconds before time
speakeasy.totp.verify({ secret: secret, token: token3, window: 2, time: 1453854005 });
// => true
// token is valid because because token is 60 seconds after time
speakeasy.totp.verify({ secret: secret, token: token2, window: 2, time: 1453854005 });
// This signifies that the given token, token1, is -2 steps away from
// the given time, which means that it is the token for the value at
// (-2 * time step) = (-2 * 30 seconds) = 60 seconds ago.
As shown previously, you can also change verifyDelta()
to verify()
to simply return a boolean if the given token is within the given window.