Package io.github.pratiyush.totp.internal

Class TOTPEngine

java.lang.Object

io.github.pratiyush.totp.internal.TOTPEngine

public final class TOTPEngine
extends Object

Core TOTP engine implementing RFC 6238.

This class contains the actual TOTP algorithm implementation with security-focused design:

• Constant-time code comparison to prevent timing attacks
• Configurable time drift tolerance
• Support for all RFC-specified algorithms

Thread Safety

This class is thread-safe. The engine is stateless and all operations are independent.

RFC Compliance

Implements TOTP as specified in RFC 6238, built on the HOTP algorithm from RFC 4226.

See Also:

• RFC 6238 - TOTP
• RFC 4226 - HOTP

Field Summary

Fields

Modifier and Type	Field	Description
static final int	MIN_SECRET_BYTES	Minimum secret length in bytes for security

Method Summary

Modifier and Type	Method	Description
static boolean	constantTimeEquals(String a, String b)	Constant-time string comparison.
static String	generateCode(byte[] secret, long counter, TOTPConfig config)	Generates a TOTP code for the given secret and counter.
static String	generateCode(byte[] secret, TOTPConfig config, TOTPClock clock)	Generates a TOTP code for the current time.
static String	generateCodeAt(byte[] secret, Instant instant, TOTPConfig config)	Generates a TOTP code for a specific instant.
static boolean	isValidCodeFormat(String code, int expectedDigits)	Checks if a code string has valid format.
static void	validateBase32Secret(String base32Secret)	Validates a Base32 encoded secret.
static void	validateSecret(byte[] secret)	Validates that the secret meets minimum security requirements.
static boolean	verifyCode(byte[] secret, String code, TOTPConfig config, TOTPClock clock)	Verifies a TOTP code using constant-time comparison.
static Integer	verifyCodeWithOffset(byte[] secret, String code, TOTPConfig config, TOTPClock clock)	Verifies a code and returns the matching counter offset if valid.

Methods inherited from class java.lang.Object

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

Field Details

MIN_SECRET_BYTES

public static final int MIN_SECRET_BYTES

Minimum secret length in bytes for security

See Also:

• Constant Field Values

Method Details

generateCode

public static String generateCode(byte[] secret,
 long counter,
 TOTPConfig config)
                           throws TOTPException

Generates a TOTP code for the given secret and counter.

This is the core HOTP algorithm from RFC 4226, used by TOTP with a time-based counter.

Parameters:

secret - the decoded secret key

counter - the time-based counter (T = floor(time / period))

config - the TOTP configuration

Returns:

the generated OTP code as a zero-padded string

Throws:

TOTPException - if generation fails

generateCode

public static String generateCode(byte[] secret,
 TOTPConfig config,
 TOTPClock clock)
                           throws TOTPException

Generates a TOTP code for the current time.

Parameters:

secret - the decoded secret key

config - the TOTP configuration

clock - the clock to use for time

Returns:

the generated OTP code

Throws:

TOTPException - if generation fails

generateCodeAt

public static String generateCodeAt(byte[] secret,
 Instant instant,
 TOTPConfig config)
                             throws TOTPException

Generates a TOTP code for a specific instant.

Parameters:

secret - the decoded secret key

instant - the time to generate for

config - the TOTP configuration

Returns:

the generated OTP code

Throws:

TOTPException - if generation fails

verifyCode

public static boolean verifyCode(byte[] secret,
 String code,
 TOTPConfig config,
 TOTPClock clock)
                          throws TOTPException

Verifies a TOTP code using constant-time comparison.

This method checks the provided code against codes generated for time windows within the configured drift tolerance.

Security

Uses constant-time comparison to prevent timing attacks. The verification time is independent of the code's correctness.

Parameters:

secret - the decoded secret key

code - the code to verify

config - the TOTP configuration

clock - the clock to use for time

Returns:

true if the code is valid

Throws:

TOTPException - if verification fails due to invalid input

verifyCodeWithOffset

public static Integer verifyCodeWithOffset(byte[] secret,
 String code,
 TOTPConfig config,
 TOTPClock clock)
                                    throws TOTPException

Verifies a code and returns the matching counter offset if valid.

This variant is useful for replay attack prevention, as the offset can be used to track which time window was used.

Parameters:

secret - the decoded secret key

code - the code to verify

config - the TOTP configuration

clock - the clock to use

Returns:

the counter offset (-drift to +drift) if valid, or null if invalid

Throws:

TOTPException - if verification fails due to invalid input

validateSecret

public static void validateSecret(byte[] secret)
                           throws TOTPException

Validates that the secret meets minimum security requirements.

Parameters:

secret - the secret to validate

Throws:

TOTPException - if the secret is invalid

validateBase32Secret

public static void validateBase32Secret(String base32Secret)
                                 throws TOTPException

Validates a Base32 encoded secret.

Parameters:

base32Secret - the Base32 encoded secret

Throws:

TOTPException - if invalid

isValidCodeFormat

public static boolean isValidCodeFormat(String code,
 int expectedDigits)

Checks if a code string has valid format.

Parameters:

code - the code to check

expectedDigits - expected number of digits

Returns:

true if format is valid

constantTimeEquals

public static boolean constantTimeEquals(String a,
 String b)

Constant-time string comparison.

Uses MessageDigest.isEqual(byte[], byte[]) which provides constant-time comparison to prevent timing attacks.

Parameters:

a - first string

b - second string

Returns:

true if strings are equal