Package io.github.pratiyush.totp

Class TOTP

java.lang.Object
io.github.pratiyush.totp.TOTP
public final class TOTP extends Object
Main entry point for TOTP operations.

This class provides a clean, secure API for generating and verifying Time-based One-Time Passwords as specified in RFC 6238.

Quick Start


 // Generate a secret for a new user
 String secret = SecretGenerator.generate(Algorithm.SHA256);
 
 // Create TOTP instance with default config
 TOTP totp = TOTP.defaultInstance();
 
 // Generate a code
 String code = totp.generate(secret);
 
 // Verify a code from user
 boolean valid = totp.verify(secret, userProvidedCode);

Custom Configuration


 TOTP totp = TOTP.builder()
         .config(TOTPConfig.sha256Config())
         .replayGuard(new InMemoryReplayGuard(Duration.ofMinutes(2)))
         .build();

Security Features

  • Constant-time verification: Prevents timing attacks
  • Replay protection: Optional guard against code reuse
  • Secure memory: Secrets cleared from memory after use
  • Input validation: Strict parameter checking

Thread Safety

Instances of this class are thread-safe when the optional ReplayGuard is also thread-safe (which InMemoryReplayGuard is).

Since:
1.0.0
Version:
1.0.0
Author:
Pratiyush Kumar Singh
See Also:

  • Method Details

    • defaultInstance

      public static TOTP defaultInstance()
      Returns a TOTP instance with default configuration.

      Uses SHA-1 algorithm, 6 digits, 30-second period, and 1 step drift. This is compatible with Google Authenticator.

      Returns:
      default TOTP instance

    • builder

      public static TOTP.Builder builder()
      Returns a builder for creating custom TOTP instances.
      Returns:
      new builder

    • generate

      public String generate(String base32Secret) throws TOTPException
      Generates a TOTP code for the current time.
      Parameters:
      base32Secret - the Base32 encoded secret
      Returns:
      the generated code
      Throws:
      TOTPException - if generation fails

    • generateAt

      public String generateAt(String base32Secret, Instant instant) throws TOTPException
      Generates a TOTP code for a specific instant.

      Useful for testing or generating future/past codes.

      Parameters:
      base32Secret - the Base32 encoded secret
      instant - the time to generate for
      Returns:
      the generated code
      Throws:
      TOTPException - if generation fails

    • generateForCounter

      public String generateForCounter(String base32Secret, long counter) throws TOTPException
      Generates a TOTP code for a specific counter value.

      Low-level method for advanced use cases.

      Parameters:
      base32Secret - the Base32 encoded secret
      counter - the TOTP counter value
      Returns:
      the generated code
      Throws:
      TOTPException - if generation fails

    • verify

      public boolean verify(String base32Secret, String code) throws TOTPException
      Verifies a TOTP code.

      This method uses constant-time comparison and optionally checks the replay guard to prevent code reuse.

      Parameters:
      base32Secret - the Base32 encoded secret
      code - the code to verify
      Returns:
      true if the code is valid
      Throws:
      TOTPException - if verification fails due to invalid input

    • verify

      public boolean verify(String base32Secret, String code, @Nullable String userId) throws TOTPException
      Verifies a TOTP code with user-specific replay protection.

      The userId is combined with the code to create a unique key for replay protection. This prevents the same code from being used by different users and tracks usage per-user.

      Parameters:
      base32Secret - the Base32 encoded secret
      code - the code to verify
      userId - optional user identifier for replay protection
      Returns:
      true if the code is valid and not replayed
      Throws:
      TOTPException - if verification fails due to invalid input

    • verifyWithDetails

      public TOTP.VerificationResult verifyWithDetails(String base32Secret, String code) throws TOTPException
      Verifies a code and returns detailed result.
      Parameters:
      base32Secret - the Base32 encoded secret
      code - the code to verify
      Returns:
      verification result with details
      Throws:
      TOTPException - if verification fails due to invalid input

    • getCurrentCounter

      public long getCurrentCounter()
      Returns the current TOTP counter value.
      Returns:
      current counter

    • getSecondsRemaining

      public int getSecondsRemaining()
      Returns seconds remaining until the current code expires.
      Returns:
      seconds remaining

    • getConfig

      public TOTPConfig getConfig()
      Returns the configuration.
      Returns:
      the TOTP configuration

    • getClock

      public TOTPClock getClock()
      Returns the clock being used.
      Returns:
      the TOTP clock