Class Hotp

java.lang.Object
cloud.opencode.base.crypto.otp.Hotp
public final class Hotp extends Object
RFC 4226 HOTP (HMAC-Based One-Time Password) implementation RFC 4226 HOTP（基于 HMAC 的一次性密码）实现

Generates and verifies HMAC-based one-time passwords as defined in RFC 4226. Supports configurable HMAC algorithms (SHA-1, SHA-256, SHA-512) and digit lengths (6-8).

生成和验证基于 HMAC 的一次性密码，符合 RFC 4226 规范。 支持可配置的 HMAC 算法（SHA-1、SHA-256、SHA-512）和位数（6-8）。

Features | 主要功能:

  • HMAC-based OTP generation per RFC 4226 - 符合 RFC 4226 的 HMAC 一次性密码生成
  • Configurable HMAC algorithm (SHA-1, SHA-256, SHA-512) - 可配置 HMAC 算法
  • Configurable digit length (6-8) - 可配置位数（6-8）
  • Constant-time verification to prevent timing attacks - 常量时间验证防止时序攻击
  • Look-ahead window for counter synchronization - 前瞻窗口用于计数器同步

Usage Examples | 使用示例:

Hotp hotp = Hotp.sha1();
String code = hotp.generate(secret, 0);
boolean valid = hotp.verify(secret, 0, code, 5);

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:

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    algorithm()
    Returns the HMAC algorithm used by this instance.
    String
    generate(byte[] secret, long counter)
    Generates a 6-digit one-time password for the given secret and counter.
    String
    generate(byte[] secret, long counter, int digits)
    Generates a one-time password with the specified number of digits.
    static Hotp
    of(String algorithm)
    Creates an HOTP instance using a custom HMAC algorithm.
    static Hotp
    sha1()
    Creates an HOTP instance using HmacSHA1 (default, compatible with most authenticator apps).
    static Hotp
    sha256()
    Creates an HOTP instance using HmacSHA256.
    static Hotp
    sha512()
    Creates an HOTP instance using HmacSHA512.
    boolean
    verify(byte[] secret, long counter, String code)
    Verifies a one-time password against the given secret and counter (6 digits, no look-ahead).
    boolean
    verify(byte[] secret, long counter, String code, int lookAhead)
    Verifies a one-time password with a look-ahead window for counter synchronization.

    Methods inherited from class Object

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

  • Method Details

    • sha1

      public static Hotp sha1()
      Creates an HOTP instance using HmacSHA1 (default, compatible with most authenticator apps). 创建使用 HmacSHA1 的 HOTP 实例（默认，兼容大多数认证器应用）
      Returns:
      a new Hotp instance using HmacSHA1 | 使用 HmacSHA1 的 Hotp 实例

    • sha256

      public static Hotp sha256()
      Creates an HOTP instance using HmacSHA256. 创建使用 HmacSHA256 的 HOTP 实例
      Returns:
      a new Hotp instance using HmacSHA256 | 使用 HmacSHA256 的 Hotp 实例

    • sha512

      public static Hotp sha512()
      Creates an HOTP instance using HmacSHA512. 创建使用 HmacSHA512 的 HOTP 实例
      Returns:
      a new Hotp instance using HmacSHA512 | 使用 HmacSHA512 的 Hotp 实例

    • of

      public static Hotp of(String algorithm)
      Creates an HOTP instance using a custom HMAC algorithm. 创建使用自定义 HMAC 算法的 HOTP 实例
      Parameters:
      algorithm - the HMAC algorithm name (e.g., "HmacSHA1") | HMAC 算法名称
      Returns:
      a new Hotp instance | 新的 Hotp 实例
      Throws:
      OpenCryptoException - if the algorithm is not available | 当算法不可用时抛出

    • generate

      public String generate(byte[] secret, long counter)
      Generates a 6-digit one-time password for the given secret and counter. 为给定密钥和计数器生成 6 位一次性密码
      Parameters:
      secret - the shared secret key | 共享密钥
      counter - the counter value | 计数器值
      Returns:
      the generated OTP code | 生成的 OTP 验证码
      Throws:
      OpenCryptoException - if generation fails | 当生成失败时抛出

    • generate

      public String generate(byte[] secret, long counter, int digits)
      Generates a one-time password with the specified number of digits. 生成指定位数的一次性密码
      Parameters:
      secret - the shared secret key | 共享密钥
      counter - the counter value | 计数器值
      digits - the number of digits (6-8) | 位数（6-8）
      Returns:
      the generated OTP code | 生成的 OTP 验证码
      Throws:
      OpenCryptoException - if generation fails | 当生成失败时抛出
      IllegalArgumentException - if digits is not 6-8 or secret is null | 当位数不在 6-8 范围或密钥为空时抛出

    • verify

      public boolean verify(byte[] secret, long counter, String code)
      Verifies a one-time password against the given secret and counter (6 digits, no look-ahead). 验证一次性密码（6 位，无前瞻窗口）
      Parameters:
      secret - the shared secret key | 共享密钥
      counter - the expected counter value | 期望的计数器值
      code - the OTP code to verify | 待验证的 OTP 验证码
      Returns:
      true if the code is valid | 验证码有效返回 true
      Throws:
      OpenCryptoException - if verification fails | 当验证失败时抛出

    • verify

      public boolean verify(byte[] secret, long counter, String code, int lookAhead)
      Verifies a one-time password with a look-ahead window for counter synchronization. 使用前瞻窗口验证一次性密码，用于计数器同步
      Parameters:
      secret - the shared secret key | 共享密钥
      counter - the expected counter value | 期望的计数器值
      code - the OTP code to verify | 待验证的 OTP 验证码
      lookAhead - the number of counter values to check ahead (0-100) | 前瞻窗口大小（0-100）
      Returns:
      true if the code matches any counter in [counter, counter+lookAhead] | 验证码匹配任一计数器值时返回 true
      Throws:
      OpenCryptoException - if verification fails | 当验证失败时抛出
      IllegalArgumentException - if lookAhead is negative or code is null | 当前瞻窗口为负数或验证码为空时抛出

    • algorithm

      public String algorithm()
      Returns the HMAC algorithm used by this instance. 返回此实例使用的 HMAC 算法
      Returns:
      the algorithm name | 算法名称