Class TimeBasedOneTimePasswordGenerator

java.lang.Object

com.eatthepath.otp.TimeBasedOneTimePasswordGenerator

public class TimeBasedOneTimePasswordGenerator
extends Object

Generates time-based one-time passwords (TOTP) as specified in RFC 6238.

TimeBasedOneTimePasswordGenerator instances are thread-safe and may be shared between threads. Note that the generateOneTimePassword(SecretKey, Instant) method (and its relatives) are synchronized; in multi-threaded applications that make heavy use of a shared TimeBasedOneTimePasswordGenerator instance, synchronization may become a performance bottleneck. In that case, callers may benefit from using one TimeBasedOneTimePasswordGenerator instance per thread (for example, with a ThreadLocal).

Author:

Jon Chambers

Field Summary

Fields

Modifier and Type	Field	Description
static final Duration	DEFAULT_TIME_STEP	The default time-step for a time-based one-time password generator (30 seconds).
static final String	TOTP_ALGORITHM_HMAC_SHA1	A string identifier for the HMAC-SHA1 algorithm; HMAC-SHA1 is the default algorithm for TOTP.
static final String	TOTP_ALGORITHM_HMAC_SHA256	A string identifier for the HMAC-SHA256 algorithm.
static final String	TOTP_ALGORITHM_HMAC_SHA512	A string identifier for the HMAC-SHA512 algorithm.

Constructor Summary

Constructors

Constructor	Description
TimeBasedOneTimePasswordGenerator()	Constructs a new time-based one-time password generator with a default time-step (30 seconds), password length (6 decimal digits), and HMAC algorithm ("HmacSHA1").
TimeBasedOneTimePasswordGenerator(Duration timeStep)	Constructs a new time-based one-time password generator with the given time-step and a default password length (6 decimal digits) and HMAC algorithm ("HmacSHA1").
TimeBasedOneTimePasswordGenerator(Duration timeStep, int passwordLength)	Constructs a new time-based one-time password generator with the given time-step and password length and a default HMAC algorithm ("HmacSHA1").
TimeBasedOneTimePasswordGenerator(Duration timeStep, int passwordLength, String algorithm)	Constructs a new time-based one-time password generator with the given time-step, password length, and HMAC algorithm.

Method Summary

Modifier and Type	Method	Description
int	generateOneTimePassword(SecretKey key, Instant timestamp)	Generates a one-time password using the given key and timestamp.
String	generateOneTimePasswordString(SecretKey key, Instant timestamp)	Generates a one-time password using the given key and timestamp and formats it as a string with the system default locale.
String	generateOneTimePasswordString(SecretKey key, Instant timestamp, Locale locale)	Generates a one-time password using the given key and timestamp and formats it as a string with the given locale.
String	getAlgorithm()	Returns the name of the HMAC algorithm used by this generator.
int	getPasswordLength()	Returns the length, in decimal digits, of passwords produced by this generator.
Duration	getTimeStep()	Returns the time step used by this generator.
boolean	validateOneTimePassword(SecretKey key, Instant timestamp, int oneTimePassword)	Checks whether a given one-time password matches the one-time password generated for the given key and timestamp.
boolean	validateOneTimePassword(SecretKey key, Instant timestamp, String oneTimePassword)	Checks whether a given one-time password matches the one-time password generated for the given key and timestamp.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

DEFAULT_TIME_STEP

public static final Duration DEFAULT_TIME_STEP

The default time-step for a time-based one-time password generator (30 seconds).

TOTP_ALGORITHM_HMAC_SHA1

public static final String TOTP_ALGORITHM_HMAC_SHA1

A string identifier for the HMAC-SHA1 algorithm; HMAC-SHA1 is the default algorithm for TOTP.

See Also:

• Constant Field Values

TOTP_ALGORITHM_HMAC_SHA256

public static final String TOTP_ALGORITHM_HMAC_SHA256

A string identifier for the HMAC-SHA256 algorithm.

See Also:

• Constant Field Values

TOTP_ALGORITHM_HMAC_SHA512

public static final String TOTP_ALGORITHM_HMAC_SHA512

A string identifier for the HMAC-SHA512 algorithm.

See Also:

• Constant Field Values

Constructor Details

TimeBasedOneTimePasswordGenerator

public TimeBasedOneTimePasswordGenerator()

Constructs a new time-based one-time password generator with a default time-step (30 seconds), password length (6 decimal digits), and HMAC algorithm ("HmacSHA1").

TimeBasedOneTimePasswordGenerator

public TimeBasedOneTimePasswordGenerator(Duration timeStep)

Constructs a new time-based one-time password generator with the given time-step and a default password length (6 decimal digits) and HMAC algorithm ("HmacSHA1").

Parameters:

timeStep - the time-step for this generator

TimeBasedOneTimePasswordGenerator

public TimeBasedOneTimePasswordGenerator(Duration timeStep,
 int passwordLength)

Constructs a new time-based one-time password generator with the given time-step and password length and a default HMAC algorithm ("HmacSHA1").

Parameters:

timeStep - the time-step for this generator

passwordLength - the length, in decimal digits, of the one-time passwords to be generated; must be between 6 and 8, inclusive

TimeBasedOneTimePasswordGenerator

public TimeBasedOneTimePasswordGenerator(Duration timeStep,
 int passwordLength,
 String algorithm)
                                  throws NoSuchAlgorithmException

Constructs a new time-based one-time password generator with the given time-step, password length, and HMAC algorithm.

Parameters:

timeStep - the time-step for this generator

passwordLength - the length, in decimal digits, of the one-time passwords to be generated; must be between 6 and 8, inclusive

algorithm - the name of the Mac algorithm to use when generating passwords; TOTP allows for "HmacSHA1", "HmacSHA256", and "HmacSHA512"

Throws:

IllegalArgumentException - if the given algorithm is not an algorithm allowed by RFC 6238 (i.e. "HmacSHA1", "HmacSHA256", or "HmacSHA512")

NoSuchAlgorithmException - if the given algorithm is "HmacSHA512" and the JVM does not support that algorithm; all JVMs are required to support "HmacSHA1" and "HmacSHA256", but are not required to support "HmacSHA512"

See Also:

• TOTP_ALGORITHM_HMAC_SHA1
• TOTP_ALGORITHM_HMAC_SHA256
• TOTP_ALGORITHM_HMAC_SHA512

Method Details

generateOneTimePassword

public int generateOneTimePassword(SecretKey key,
 Instant timestamp)
                            throws InvalidKeyException

Generates a one-time password using the given key and timestamp.

Parameters:

key - the key to be used to generate the password

timestamp - the timestamp for which to generate the password

Returns:

an integer representation of a one-time password; callers will need to format the password for display on their own

Throws:

InvalidKeyException - if the given key is inappropriate for initializing the Mac for this generator

generateOneTimePasswordString

public String generateOneTimePasswordString(SecretKey key,
 Instant timestamp)
                                     throws InvalidKeyException

Generates a one-time password using the given key and timestamp and formats it as a string with the system default locale.

Parameters:

key - the key to be used to generate the password

timestamp - the timestamp for which to generate the password

Returns:

a string representation of a one-time password

Throws:

InvalidKeyException - if the given key is inappropriate for initializing the Mac for this generator

See Also:

• Locale.getDefault()

generateOneTimePasswordString

public String generateOneTimePasswordString(SecretKey key,
 Instant timestamp,
 Locale locale)
                                     throws InvalidKeyException

Generates a one-time password using the given key and timestamp and formats it as a string with the given locale.

Parameters:

key - the key to be used to generate the password

timestamp - the timestamp for which to generate the password

locale - the locale to apply during formatting

Returns:

a string representation of a one-time password

Throws:

InvalidKeyException - if the given key is inappropriate for initializing the Mac for this generator

validateOneTimePassword

public boolean validateOneTimePassword(SecretKey key,
 Instant timestamp,
 String oneTimePassword)
                                throws InvalidKeyException

Checks whether a given one-time password matches the one-time password generated for the given key and timestamp. Note that this method simply checks equality of two one-time passwords; compensating for clock drift, throttling/rate-limiting, clock resynchronization, and so on are all beyond the scope of this method.

Parameters:

key - the key to be used to generate the password

timestamp - the timestamp for which to generate the password

oneTimePassword - the user-provided one-time password to check against the generated one-time password

Returns:

true if and only if the given one-time password matches the one-time password generated for the given key and timestamp; one-time password strings match if they have the correct number of digits (see getPasswordLength()), can be parsed as an integer, and that integer matches the one-time password generated for the given key and timestamp

Throws:

InvalidKeyException - if the given key is inappropriate for initializing the Mac for this generator

NullPointerException - if the given timestamp or one-time password is null

See Also:

• TOTP: Time-Based One-Time Password Algorithm (RFC 6238) - Security Considerations

validateOneTimePassword

public boolean validateOneTimePassword(SecretKey key,
 Instant timestamp,
 int oneTimePassword)
                                throws InvalidKeyException

Checks whether a given one-time password matches the one-time password generated for the given key and timestamp. Note that this method simply checks equality of two one-time passwords; compensating for clock drift, throttling/rate-limiting, clock resynchronization, and so on are all beyond the scope of this method.

Parameters:

key - the key to be used to generate the password

timestamp - the timestamp for which to generate the password

oneTimePassword - the user-provided one-time password to check against the generated one-time password

Returns:

true if and only if the given one-time password matches the one-time password generated for the given key and timestamp

Throws:

InvalidKeyException - if the given key is inappropriate for initializing the Mac for this generator

NullPointerException - if the given timestamp is null

See Also:

• TOTP: Time-Based One-Time Password Algorithm (RFC 6238) - Security Considerations

getTimeStep

public Duration getTimeStep()

Returns the time step used by this generator.

Returns:

the time step used by this generator

getPasswordLength

public int getPasswordLength()

Returns the length, in decimal digits, of passwords produced by this generator.

Returns:

the length, in decimal digits, of passwords produced by this generator

getAlgorithm

public String getAlgorithm()

Returns the name of the HMAC algorithm used by this generator.

Returns:

the name of the HMAC algorithm used by this generator