java.lang.Object

cloud.opencode.base.crypto.otp.Totp

public final class Totp extends Object

RFC 6238 TOTP (Time-Based One-Time Password) implementation RFC 6238 TOTP（基于时间的一次性密码）实现

Generates and verifies time-based one-time passwords as defined in RFC 6238. Built on top of HOTP (RFC 4226) with time-step-based counter derivation.

生成和验证基于时间的一次性密码，符合 RFC 6238 规范。基于 HOTP（RFC 4226），使用时间步长计算计数器。

Features | 主要功能:

Time-based OTP generation per RFC 6238 - 符合 RFC 6238 的基于时间的 OTP 生成
Configurable time period and digit length - 可配置时间步长和位数
Time window verification for clock skew tolerance - 时间窗口验证以容忍时钟偏差
otpauth:// URI generation for QR code provisioning - 生成 otpauth:// URI 用于二维码配置
Builder pattern for flexible configuration - Builder 模式灵活配置

Usage Examples | 使用示例:

// Default SHA-1, 30s period, 6 digits
Totp totp = Totp.sha1();
String code = totp.generate(secret);
boolean valid = totp.verify(secret, code);

// Custom configuration
Totp totp = Totp.builder()
    .algorithm("HmacSHA256")
    .period(60)
    .digits(8)
    .build();

// Generate otpauth URI for QR code
String uri = Totp.generateUri("MyApp", "user@example.com", secret);

Security | 安全性:

Thread-safe: Yes - 线程安全: 是
Null-safe: Yes (validates inputs) - 空值安全: 是（校验输入）

Since:

JDK 25, opencode-base-crypto V1.0.3

Author:

Leon Soo www.LeonSoo.com

See Also:

Nested Class Summary

Nested Classes

Modifier and Type

Class

Description

static final class

Totp.Builder

Builder for constructing Totp instances with custom configuration.
Method Summary

Modifier and Type

Method

Description

String

algorithm()

Returns the HMAC algorithm name.

static Totp.Builder

builder()

Creates a new Builder for configuring a TOTP instance.

int

digits()

Returns the number of digits in generated codes.

String

generate(byte[] secret)

Generates a TOTP code for the current time.

String

generate(byte[] secret, Instant time)

Generates a TOTP code for the specified time.

static String

generateUri(String issuer, String account, byte[] secret)

Generates an otpauth:// URI with default settings (SHA-1, 6 digits, 30s period).

static String

generateUri(String issuer, String account, byte[] secret, String algorithm, int digits, int period)

Generates an otpauth:// URI with full configuration parameters.

int

period()

Returns the time period in seconds.

static Totp

sha1()

Creates a TOTP instance with default settings (SHA-1, 30s period, 6 digits).

static Totp

sha256()

Creates a TOTP instance using SHA-256 (30s period, 6 digits).

static Totp

sha512()

Creates a TOTP instance using SHA-512 (30s period, 6 digits).

boolean

verify(byte[] secret, String code)

Verifies a TOTP code against the current time with default window size (1).

boolean

verify(byte[] secret, String code, int windowSize)

Verifies a TOTP code against the current time with the specified window size.

boolean

verify(byte[] secret, String code, Instant time, int windowSize)

Verifies a TOTP code against the specified time with the given window size.

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- sha1
  
  public static Totp sha1()
  
  Creates a TOTP instance with default settings (SHA-1, 30s period, 6 digits). 创建默认配置的 TOTP 实例（SHA-1、30 秒步长、6 位）
  
  Returns:
  
  a new Totp instance | 新的 Totp 实例
- sha256
  
  public static Totp sha256()
  
  Creates a TOTP instance using SHA-256 (30s period, 6 digits). 创建使用 SHA-256 的 TOTP 实例（30 秒步长、6 位）
  
  Returns:
  
  a new Totp instance | 新的 Totp 实例
- sha512
  
  public static Totp sha512()
  
  Creates a TOTP instance using SHA-512 (30s period, 6 digits). 创建使用 SHA-512 的 TOTP 实例（30 秒步长、6 位）
  
  Returns:
  
  a new Totp instance | 新的 Totp 实例
- builder
  
  public static Totp.Builder builder()
  
  Creates a new Builder for configuring a TOTP instance. 创建新的 Builder 用于配置 TOTP 实例
  
  Returns:
  
  a new Builder | 新的 Builder
- generate
  
  public String generate(byte[] secret)
  
  Generates a TOTP code for the current time. 生成当前时间的 TOTP 验证码
  
  Parameters:
  
  secret - the shared secret key | 共享密钥
  
  Returns:
  
  the generated TOTP code | 生成的 TOTP 验证码
- generate
  
  public String generate(byte[] secret, Instant time)
  
  Generates a TOTP code for the specified time. 生成指定时间的 TOTP 验证码
  
  Parameters:
  
  secret - the shared secret key | 共享密钥
  
  time - the time instant to generate for | 生成 TOTP 的时间点
  
  Returns:
  
  the generated TOTP code | 生成的 TOTP 验证码
- verify
  
  public boolean verify(byte[] secret, String code)
  
  Verifies a TOTP code against the current time with default window size (1). 使用默认窗口大小（1）验证当前时间的 TOTP 验证码
  
  Parameters:
  
  secret - the shared secret key | 共享密钥
  
  code - the TOTP code to verify | 待验证的 TOTP 验证码
  
  Returns:
  
  true if the code is valid | 验证码有效返回 true
- verify
  
  public boolean verify(byte[] secret, String code, int windowSize)
  
  Verifies a TOTP code against the current time with the specified window size. 使用指定窗口大小验证当前时间的 TOTP 验证码
  
  Parameters:
  
  secret - the shared secret key | 共享密钥
  
  code - the TOTP code to verify | 待验证的 TOTP 验证码
  
  windowSize - the number of time steps to check before and after (>=0) | 前后检查的时间步数（>=0）
  
  Returns:
  
  true if the code is valid within the window | 在窗口内验证码有效返回 true
- verify
  
  public boolean verify(byte[] secret, String code, Instant time, int windowSize)
  
  Verifies a TOTP code against the specified time with the given window size. 使用指定时间和窗口大小验证 TOTP 验证码
  
  Parameters:
  
  secret - the shared secret key | 共享密钥
  
  code - the TOTP code to verify | 待验证的 TOTP 验证码
  
  time - the time instant to verify against | 验证的时间点
  
  windowSize - the number of time steps to check before and after (>=0) | 前后检查的时间步数（>=0）
  
  Returns:
  
  true if the code is valid within the window | 在窗口内验证码有效返回 true
  
  Throws:
  
  IllegalArgumentException - if windowSize is negative | 当窗口大小为负数时抛出
- period
  
  public int period()
  
  Returns the time period in seconds. 返回时间步长（秒）
  
  Returns:
  
  the period in seconds | 时间步长（秒）
- digits
  
  public int digits()
  
  Returns the number of digits in generated codes. 返回生成验证码的位数
  
  Returns:
  
  the number of digits | 位数
- algorithm
  
  public String algorithm()
  
  Returns the HMAC algorithm name. 返回 HMAC 算法名称
  
  Returns:
  
  the algorithm name | 算法名称
- generateUri
  
  public static String generateUri(String issuer, String account, byte[] secret)
  
  Generates an otpauth:// URI with default settings (SHA-1, 6 digits, 30s period). 生成使用默认设置的 otpauth:// URI（SHA-1、6 位、30 秒步长）
  
  Parameters:
  
  issuer - the issuer name (e.g., company name) | 发行方名称
  
  account - the account name (e.g., email) | 账户名称
  
  secret - the shared secret key | 共享密钥
  
  Returns:
  
  the otpauth URI | otpauth URI
- generateUri
  
  public static String generateUri(String issuer, String account, byte[] secret, String algorithm, int digits, int period)
  
  Generates an otpauth:// URI with full configuration parameters. 生成包含完整配置参数的 otpauth:// URI
  The generated URI follows the Google Authenticator key URI format: otpauth://totp/Issuer:account?secret=BASE32&issuer=Issuer&algorithm=SHA1&digits=6&period=30
  
  Parameters:
  
  issuer - the issuer name (e.g., company name) | 发行方名称
  
  account - the account name (e.g., email) | 账户名称
  
  secret - the shared secret key | 共享密钥
  
  algorithm - the hash algorithm (SHA1, SHA256, SHA512) | 哈希算法
  
  digits - the number of digits (6-8) | 位数（6-8）
  
  period - the time period in seconds | 时间步长（秒）
  
  Returns:
  
  the otpauth URI | otpauth URI

Class Totp

Nested Class Summary

Method Summary

Methods inherited from class Object

Method Details

sha1

sha256

sha512

builder

generate

generate

verify

verify

verify

period

digits

algorithm

generateUri

generateUri