Package io.mangoo.crypto.totp

Class TOTPValidator

  • public final class TOTPValidator
extends Object
    A Time-based One-time Password (TOTP) validator.

    As per RFC 6238 (section 5.2):

    "An OTP generated within the same time step will be the same. When an OTP is received at a validation system, it doesn't know a client's exact timestamp when an OTP was generated. The validation system may typically use the timestamp when an OTP is received for OTP comparison. Due to network latency, the gap (as measured by T, that is, the number of time steps since T0) between the time that the OTP was generated and the time that the OTP arrives at the receiving system may be large. The receiving time at the validation system and the actual OTP generation may not fall within the same time-step window that produced the same OTP. When an OTP is generated at the end of a time-step window, the receiving time most likely falls into the next time-step window. A validation system SHOULD typically set a policy for an acceptable OTP transmission delay window for validation. The validation system should compare OTPs not only with the receiving timestamp but also the past timestamps that are within the transmission delay. A larger acceptable delay window would expose a larger window for attacks. We RECOMMEND that at most one time step is allowed as the network delay."

    Example: 

     // We will let the TOTP generation time == TOTP validation time so validation will succeed.
 final long time = System.currentTimeMillis(); 
 byte[] key = "...";
 TOTP totp = TOTP.key(key).build(time);
 boolean valid = TOTPValidator.window(0).isValid(key, totp.timeStep(), totp.digits(), totp.hmacShaAlgorithm(), totp.value(), time);
 // Should print "TOTP = ..., valid = true"
 System.out.printf("TOTP = %s, valid = %s%n", totp.value(), valid);
    Author:
    Johnny Mongiat
    See Also:
    RFC 6238 (section 5.2)

    • Field Detail

      • DEFAULT_WINDOW

        public static final int DEFAULT_WINDOW
        The default window verification size.
        See Also:
        Constant Field Values

    • Method Detail

      • isValid

        public boolean isValid​(byte[] key,
                       long timeStep,
                       int digits,
                       HmacShaAlgorithm hmacShaAlgorithm,
                       String value)
        Returns true if the specified TOTP value matches the value of the TOTP generated at validation, otherwise false. The current system time (current time in milliseconds since the UNIX epoch) is used as the validation reference time.
        Parameters:
        key - the encoded shared secret key
        timeStep - the time step size in milliseconds
        digits - the number of digits a TOTP should contain
        hmacShaAlgorithm - HmacShaAlgorithm
        value - the TOTP value to validate
        Returns:
        true if the specified TOTP code value matches the code value of the TOTP generated at validation, otherwise false.

      • isValid

        public boolean isValid​(byte[] key,
                       long timeStep,
                       int digits,
                       HmacShaAlgorithm hmacShaAlgorithm,
                       String value,
                       long validationTime)
        Returns true if the specified TOTP value matches the value of the TOTP generated at validation, otherwise false.
        Parameters:
        key - the encoded shared secret key
        timeStep - the time step size in milliseconds
        digits - the number of digits a TOTP should contain
        hmacShaAlgorithm - HmacShaAlgorithm
        value - the TOTP value to validate
        validationTime - the validation reference time in milliseconds
        Returns:
        true if the specified TOTP code value matches the code value of the TOTP generated at validation, otherwise false.