JSDoc: Global

Methods

digest(options) → {Buffer}

Digest the one-time passcode options.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Default	Description
`secret`	String			Shared secret key
`counter`	Integer			Counter value
`encoding`	String	<optional>	"ascii"	Key encoding (ascii, hex, base32, base64).
`algorithm`	String	<optional>	"sha1"	Hash algorithm (sha1, sha256, sha512).
`key`	String	<optional>		(DEPRECATED. Use `secret` instead.) Shared secret key

Source:

index.js, line 23

Returns:

The one-time passcode as a buffer.

Type: Buffer

generateSecret(options) → {Object|GeneratedSecret}

Generates a random secret with the set A-Z a-z 0-9 and symbols, of any length (default 32). Returns the secret key in ASCII, hexadecimal, and base32 format, along with the URL used for the QR code for Google Authenticator (an otpauth URL). Use a QR code library to generate a QR code based on the Google Authenticator URL to obtain a QR code you can scan into the app.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Default	Description
`length`	Integer	<optional>	32	Length of the secret
`symbols`	Boolean	<optional>	false	Whether to include symbols
`otpauth_url`	Boolean	<optional>	true	Whether to output a Google Authenticator-compatible otpauth:// URL (only returns otpauth:// URL, no QR code)
`name`	String	<optional>		The name to use with Google Authenticator.
`qr_codes`	Boolean	<optional>	false	(DEPRECATED. Do not use to prevent leaking of secret to a third party. Use your own QR code implementation.) Output QR code URLs for the token.
`google_auth_qr`	Boolean	<optional>	false	(DEPRECATED. Do not use to prevent leaking of secret to a third party. Use your own QR code implementation.) Output a Google Authenticator otpauth:// QR code URL.

Source:

index.js, line 442

Returns:

Type

Object
The generated secret key.

Type

GeneratedSecret

generateSecretASCII(lengthopt, symbolsopt) → {String}

Generates a key of a certain length (default 32) from A-Z, a-z, 0-9, and symbols (if requested).

Parameters:

Name	Type	Attributes	Default	Description
`length`	Integer	<optional>	32	The length of the key.
`symbols`	Boolean	<optional>	false	Whether to include symbols in the key.

Source:

index.js, line 504

Returns:

The generated key.

Type: String

hotp(options) → {String}

Generate a counter-based one-time token. Specify the key and counter, and receive the one-time password for that counter position as a string. You can also specify a token length, as well as the encoding (ASCII, hexadecimal, or base32) and the hashing algorithm to use (SHA1, SHA256, SHA512).

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Default	Description
`secret`	String			Shared secret key
`counter`	Integer			Counter value
`digest`	Buffer	<optional>		Digest, automatically generated by default
`digits`	Integer	<optional>	6	The number of digits for the one-time passcode.
`encoding`	String	<optional>	"ascii"	Key encoding (ascii, hex, base32, base64).
`algorithm`	String	<optional>	"sha1"	Hash algorithm (sha1, sha256, sha512).
`key`	String	<optional>		(DEPRECATED. Use `secret` instead.) Shared secret key
`length`	Integer	<optional>	6	(DEPRECATED. Use `digits` instead.) The number of digits for the one-time passcode.

Source:

index.js, line 88

Returns:

The one-time passcode.

Type: String

hotp.verify(options) → {Boolean}

Verify a counter-based one-time token against the secret and return true if it verifies. Helper function for `hotp.verifyDelta()`` that returns a boolean instead of an object. For more on how to use a window with this, see hotp.verifyDelta.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Default	Description
`secret`	String			Shared secret key
`token`	String			Passcode to validate
`counter`	Integer			Counter value. This should be stored by the application and must be incremented for each request.
`digits`	Integer	<optional>	6	The number of digits for the one-time passcode.
`window`	Integer	<optional>	0	The allowable margin for the counter. The function will check "W" codes in the future against the provided passcode, e.g. if W = 10, and C = 5, this function will check the passcode against all One Time Passcodes between 5 and 15, inclusive.
`encoding`	String	<optional>	"ascii"	Key encoding (ascii, hex, base32, base64).
`algorithm`	String	<optional>	"sha1"	Hash algorithm (sha1, sha256, sha512).

Source:

index.js, line 191

Returns:

Returns true if the token matches within the given window, false otherwise.

Type: Boolean

hotp.verifyDelta(options) → {Object}

Verify a counter-based one-time token against the secret and return the delta. By default, it verifies the token at the given counter value, with no leeway (no look-ahead or look-behind). A token validated at the current counter value will have a delta of 0.

You can specify a window to add more leeway to the verification process. Setting the window param will check for the token at the given counter value as well as window tokens ahead (one-sided window). See param for more info.

verifyDelta() will return the delta between the counter value of the token and the given counter value. For example, if given a counter 5 and a window 10, verifyDelta() will look at tokens from 5 to 15, inclusive. If it finds it at counter position 7, it will return { delta: 2 }.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Default	Description
`secret`	String			Shared secret key
`token`	String			Passcode to validate
`counter`	Integer			Counter value. This should be stored by the application and must be incremented for each request.
`digits`	Integer	<optional>	6	The number of digits for the one-time passcode.
`window`	Integer	<optional>	0	The allowable margin for the counter. The function will check "W" codes in the future against the provided passcode, e.g. if W = 10, and C = 5, this function will check the passcode against all One Time Passcodes between 5 and 15, inclusive.
`encoding`	String	<optional>	"ascii"	Key encoding (ascii, hex, base32, base64).
`algorithm`	String	<optional>	"sha1"	Hash algorithm (sha1, sha256, sha512).

Source:

index.js, line 116

Returns:

On success, returns an object with the counter difference between the client and the server as the delta property (i.e. { delta: 0 }).

Type: Object

otpauthURL(options) → {String}

Generate a Google Authenticator-compatible otpauth:// URL for passing the secret to a mobile device to install the secret.

Authenticator considers TOTP codes valid for 30 seconds. Additionally, the app presents 6 digits codes to the user. According to the documentation, the period and number of digits are currently ignored by the app.

To generate a suitable QR Code, pass the generated URL to a QR Code generator, such as the qr-image module.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Default	Description
`secret`	String			Shared secret key
`label`	String			Used to identify the account with which the secret key is associated, e.g. the user's email address.
`type`	String	<optional>	"totp"	Either "hotp" or "totp".
`counter`	Integer	<optional>		The initial counter value, required for HOTP.
`issuer`	String	<optional>		The provider or service with which the secret key is associated.
`algorithm`	String	<optional>	"sha1"	Hash algorithm (sha1, sha256, sha512).
`digits`	Integer	<optional>	6	The number of digits for the one-time passcode. Currently ignored by Google Authenticator.
`period`	Integer	<optional>	30	The length of time for which a TOTP code will be valid, in seconds. Currently ignored by Google Authenticator.
`encoding`	String	<optional>		Key encoding (ascii, hex, base32, base64). If the key is not encoded in Base-32, it will be reencoded.

Source:

index.js, line 563

See:

https://github.com/google/google-authenticator/wiki/Key-Uri-Format

Throws:

Error if secret or label is missing, or if hotp is used and a counter is missing, if the type is not one of hotp or totp, if the number of digits is non-numeric, or an invalid period is used. Warns if the number of digits is not either 6 or 8 (though 6 is the only one supported by Google Authenticator), and if the hashihng algorithm is not one of the supported SHA1, SHA256, or SHA512.

Returns:

A URL suitable for use with the Google Authenticator.

Type: String

totp(options) → {String}

Generate a time-based one-time token. Specify the key, and receive the one-time password for that time as a string. By default, it uses the current time and a time step of 30 seconds, so there is a new token every 30 seconds. You may override the time step and epoch for custom timing. You can also specify a token length, as well as the encoding (ASCII, hexadecimal, or base32) and the hashing algorithm to use (SHA1, SHA256, SHA512).

Under the hood, TOTP calculates the counter value by finding how many time steps have passed since the epoch, and calls HOTP with that counter value.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Default	Description
`secret`	String			Shared secret key
`time`	Integer	<optional>		Time in seconds with which to calculate counter value. Defaults to `Date.now()`.
`step`	Integer	<optional>	30	Time step in seconds
`epoch`	Integer	<optional>	0	Initial time in seconds since the UNIX epoch from which to calculate the counter value. Defaults to 0 (no offset).
`counter`	Integer	<optional>		Counter value, calculated by default.
`digits`	Integer	<optional>	6	The number of digits for the one-time passcode.
`encoding`	String	<optional>	"ascii"	Key encoding (ascii, hex, base32, base64).
`algorithm`	String	<optional>	"sha1"	Hash algorithm (sha1, sha256, sha512).
`key`	String	<optional>		(DEPRECATED. Use `secret` instead.) Shared secret key
`initial_time`	Integer	<optional>	0	(DEPRECATED. Use `epoch` instead.) Initial time in seconds since the UNIX epoch from which to calculate the counter value. Defaults to 0 (no offset).
`length`	Integer	<optional>	6	(DEPRECATED. Use `digits` instead.) The number of digits for the one-time passcode.

Source:

index.js, line 285

Returns:

The one-time passcode.

Type: String

totp.verify(options) → {Boolean}

Verify a time-based one-time token against the secret and return true if it verifies. Helper function for verifyDelta() that returns a boolean instead of an object. For more on how to use a window with this, see totp.verifyDelta.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Default	Description
`secret`	String			Shared secret key
`token`	String			Passcode to validate
`time`	Integer	<optional>		Time in seconds with which to calculate counter value. Defaults to `Date.now()`.
`step`	Integer	<optional>	30	Time step in seconds
`epoch`	Integer	<optional>	0	Initial time in seconds since the UNIX epoch from which to calculate the counter value. Defaults to 0 (no offset).
`counter`	Integer	<optional>		Counter value, calculated by default.
`digits`	Integer	<optional>	6	The number of digits for the one-time passcode.
`window`	Integer	<optional>	0	The allowable margin for the counter. The function will check "W" codes in the future and the past against the provided passcode, e.g. if W = 5, and C = 1000, this function will check the passcode against all One Time Passcodes between 995 and 1005, inclusive.
`encoding`	String	<optional>	"ascii"	Key encoding (ascii, hex, base32, base64).
`algorithm`	String	<optional>	"sha1"	Hash algorithm (sha1, sha256, sha512).

Source:

index.js, line 370

Returns:

Returns true if the token matches within the given window, false otherwise.

Type: Boolean

totp.verifyDelta(options) → {Object}

Verify a time-based one-time token against the secret and return the delta. By default, it verifies the token at the current time window, with no leeway (no look-ahead or look-behind). A token validated at the current time window will have a delta of 0.

verifyDelta() will return the delta between the counter value of the token and the given counter value. For example, if given a time at counter 1000 and a window of 5, verifyDelta() will look at tokens from 995 to 1005, inclusive. In other words, if the time-step is 30 seconds, it will look at tokens from 2.5 minutes ago to 2.5 minutes in the future, inclusive. If it finds it at counter position 1002, it will return { delta: 2 }. If it finds it at counter position 997, it will return { delta: -3 }.

Parameters:

Name Type Description

options

Object

Properties

Name	Type	Attributes	Default	Description
`secret`	String			Shared secret key
`token`	String			Passcode to validate
`time`	Integer	<optional>		Time in seconds with which to calculate counter value. Defaults to `Date.now()`.
`step`	Integer	<optional>	30	Time step in seconds
`epoch`	Integer	<optional>	0	Initial time in seconds since the UNIX epoch from which to calculate the counter value. Defaults to 0 (no offset).
`counter`	Integer	<optional>		Counter value, calculated by default.
`digits`	Integer	<optional>	6	The number of digits for the one-time passcode.
`window`	Integer	<optional>	0	The allowable margin for the counter. The function will check "W" codes in the future and the past against the provided passcode, e.g. if W = 5, and C = 1000, this function will check the passcode against all One Time Passcodes between 995 and 1005, inclusive.
`encoding`	String	<optional>	"ascii"	Key encoding (ascii, hex, base32, base64).
`algorithm`	String	<optional>	"sha1"	Hash algorithm (sha1, sha256, sha512).

Source:

index.js, line 299

Returns:

On success, returns an object with the time step difference between the client and the server as the delta property (e.g. { delta: 0 }).

Type: Object

Type Definitions

GeneratedSecret

Type:

Object

Properties:

Name	Type	Description
`ascii`	String	ASCII representation of the secret
`hex`	String	Hex representation of the secret
`base32`	String	Base32 representation of the secret
`qr_code_ascii`	String	URL for the QR code for the ASCII secret.
`qr_code_hex`	String	URL for the QR code for the hex secret.
`qr_code_base32`	String	URL for the QR code for the base32 secret.
`google_auth_qr`	String	URL for the Google Authenticator otpauth URL's QR code.
`otpauth_url`	String	Google Authenticator-compatible otpauth URL.

Source:

index.js, line 405