Package com.eatthepath.otp

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(Key, 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 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:

    • TOTP_ALGORITHM_HMAC_SHA256

      public static final String TOTP_ALGORITHM_HMAC_SHA256
      A string identifier for the HMAC-SHA256 algorithm.
      See Also:

    • TOTP_ALGORITHM_HMAC_SHA512

      public static final String TOTP_ALGORITHM_HMAC_SHA512
      A string identifier for the HMAC-SHA512 algorithm.
      See Also:

  • 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 UncheckedNoSuchAlgorithmException
      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:
      UncheckedNoSuchAlgorithmException - 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:

  • Method Details

    • generateOneTimePassword

      public int generateOneTimePassword(Key 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(Key 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:

    • generateOneTimePasswordString

      public String generateOneTimePasswordString(Key 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

    • 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