Package io.mangoo.crypto.totp

Class TOTPBuilder

java.lang.Object
io.mangoo.crypto.totp.TOTPBuilder
public final class TOTPBuilder extends Object
A Time-based One-time Password (TOTP) builder.

This is an implementation of the OATH TOTP algorithm as described by RFC 6238. This implementation supports numeric-only TOTP values ranging from size 6 to 8 (inclusive).

The builder, obtained via a call to the static key(...) method on TOTP, provides methods for configuring the TOTP generation parameters. Once the TOTP configuration is prepared, the builder is used to generate a TOTP using the build() or build(time) methods: 

 // Use a 64 byte shared secret key (we use 64 bytes since we will be using
 // HMAC-SHA-512 when generating the TOTP).
 String sharedSecretKey = "1234567890123456789012345678901234567890123456789012345678901234";
 byte[] key = sharedSecretKey.getBytes("US-ASCII");
 
 // Generate an 8-digit TOTP using a 30 second time step, HMAC-SHA-512, and the
 // 64 byte shared secret key.
 TOTP totp = TOTP.key(key).timeStep(TimeUnit.SECONDS.toMillis(30)).digits(8).hmacSha512().build();
 System.out.println("TOTP = " + totp.value());
 
 // Example of generating a TOTP using the default values: 6-digit, 30 second
 // time-step size, HMAC-SHA-1
 sharedSecretKey = "12345678901234567890"; // 20 bytes
 key = sharedSecretKey.getBytes("US-ASCII");
 totp = TOTP.key(key).build();
 System.out.println("TOTP = " + totp.value());
Author:
Johan Rydell, PortWise, Inc., Johnny Mongiat
See Also:

  • Field Details

    • DEFAULT_TIME_STEP

      public static final long DEFAULT_TIME_STEP
      The default time step size in milliseconds (30000 milliseconds == 30 seconds).

    • DEFAULT_DIGITS

      public static final int DEFAULT_DIGITS
      The default number of digits the TOTP value contains.
      See Also:

    • MIN_ALLOWED_DIGITS

      public static final int MIN_ALLOWED_DIGITS
      The minimum allowed number of digits the TOTP value can contain.
      See Also:

    • MAX_ALLOWED_DIGITS

      public static final int MAX_ALLOWED_DIGITS
      The maximum allowed number of digits the TOTP value can contain.
      See Also:

  • Method Details

    • timeStep

      public TOTPBuilder timeStep(long timeStep)
      Returns this TOTPBuilder instance initialized with the specified timeStep size.
      Parameters:
      timeStep - the time step size in milliseconds
      Returns:
      this TOTPBuilder instance initialized with the specified timeStep size.
      Throws:
      IllegalArgumentException - if timeStep is <= 0.

    • digits

      public TOTPBuilder digits(int digits)
      Returns this TOTPBuilder instance initialized with the specified digits.
      Parameters:
      digits - the number of digits the generated TOTP value should contain (must be between MIN_ALLOWED_DIGITS and MAX_ALLOWED_DIGITS inclusive)
      Returns:
      this TOTPBuilder instance initialized with the specified digits.
      Throws:
      IllegalArgumentException - if digits is not in [MIN_ALLOWED_DIGITS, MAX_ALLOWED_DIGITS].

    • hmacSha

      public TOTPBuilder hmacSha(HmacShaAlgorithm algorithm)
      Returns this TOTPBuilder instance initialized with the specified HMAC-SHA algorithm.
      Parameters:
      algorithm - the HMAC-SHA algorithm used in generating the TOTP value
      Returns:
      this TOTPBuilder instance initialized with the specified HMAC-SHA algorithm.
      Throws:
      NullPointerException - if algorithm is null.

    • hmacSha256

      public TOTPBuilder hmacSha256()
      Returns this TOTPBuilder instance initialized with the HmacShaAlgorithm.HMAC_SHA_256.
      Returns:
      this TOTPBuilder instance initialized with the HmacShaAlgorithm.HMAC_SHA_256.

    • hmacSha512

      public TOTPBuilder hmacSha512()
      Returns this TOTPBuilder instance initialized with the HmacShaAlgorithm.HMAC_SHA_512.
      Returns:
      this TOTPBuilder instance initialized with the HmacShaAlgorithm.HMAC_SHA_512.

    • build

      public TOTP build()
      Build a Time-based One-time Password TOTP using the current system time (current time in milliseconds since the UNIX epoch). Note that the builder instance can be reused for subsequent configuration/generation calls.
      Returns:
      a Time-based One-time Password TOTP instance.

    • build

      public TOTP build(long time)
      Build a Time-based One-time Password TOTP using an arbitrary time. Note that the builder instance can be reused for subsequent configuration/generation calls.
      Parameters:
      time - the time (in milliseconds) (must be >= 0)
      Returns:
      a Time-based One-time Password TOTP instance.
      Throws:
      IllegalArgumentException - if time < 0.