Package io.mangoo.crypto.totp

Class 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:
    RFC 6238

    • Field Detail

      • 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:
        Constant Field Values

      • MIN_ALLOWED_DIGITS

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

      • MAX_ALLOWED_DIGITS

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

    • Method Detail

      • 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.

      • 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.

      • 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.