Class StateParameter

java.lang.Object
cloud.opencode.base.oauth2.security.StateParameter
public final class StateParameter extends Object
OAuth2 State Parameter Utility OAuth2 State 参数工具类

Generates and validates cryptographically secure state parameters for OAuth2 authorization flows, preventing CSRF attacks as specified in RFC 6749 Section 10.12.

生成和验证用于 OAuth2 授权流程的加密安全 state 参数， 防止 RFC 6749 第 10.12 节中规定的 CSRF 攻击。

Features | 主要功能:

  • Cryptographically secure random state generation - 加密安全的随机 state 生成
  • URL-safe Base64 encoding - URL 安全的 Base64 编码
  • Constant-time validation to prevent timing attacks - 恒定时间验证防止时序攻击
  • Timestamped state with expiration support - 带时间戳的 state 及过期支持

Usage Examples | 使用示例:

// Generate a state parameter
String state = StateParameter.generate();

// Generate with custom size
String longState = StateParameter.generate(64);

// Validate state from callback
boolean valid = StateParameter.validate(expectedState, actualState);

// Generate with timestamp for expiration checks
StateParameter.StateData data = StateParameter.generateWithTimestamp();
if (data.isExpired(Duration.ofMinutes(10))) {
    // state has expired
}

Security | 安全性:

  • Uses SecureRandom for cryptographic randomness - 使用 SecureRandom 生成加密随机数
  • Constant-time comparison via MessageDigest.isEqual(byte[], byte[]) - 通过 MessageDigest.isEqual 进行恒定时间比较
  • Minimum 16 bytes (128 bits) of entropy - 最少 16 字节（128 位）熵

Thread Safety | 线程安全:

This class is thread-safe. All methods are stateless or use thread-safe components.

此类是线程安全的。所有方法都是无状态的或使用线程安全的组件。

Since:
JDK 25, opencode-base-oauth2 V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • generate

      public static String generate()
      Generate a 32-byte cryptographically random state parameter, URL-safe Base64 encoded. 生成 32 字节加密随机 state 参数，URL 安全 Base64 编码。
      Returns:
      the URL-safe Base64 encoded state string | URL 安全 Base64 编码的 state 字符串

    • generate

      public static String generate(int bytes)
      Generate a cryptographically random state parameter with custom size, URL-safe Base64 encoded. 使用自定义大小生成加密随机 state 参数，URL 安全 Base64 编码。
      Parameters:
      bytes - the number of random bytes (minimum 16) | 随机字节数（最少 16）
      Returns:
      the URL-safe Base64 encoded state string | URL 安全 Base64 编码的 state 字符串
      Throws:
      IllegalArgumentException - if bytes is less than 16 | 如果 bytes 小于 16

    • validate

      public static boolean validate(String expected, String actual)
      Validate a state parameter using constant-time comparison to prevent timing attacks. 使用恒定时间比较验证 state 参数，防止时序攻击。
      Parameters:
      expected - the expected state value | 期望的 state 值
      actual - the actual state value from callback | 回调中的实际 state 值
      Returns:
      true if the values match | 如果值匹配返回 true

    • generateWithTimestamp

      public static StateParameter.StateData generateWithTimestamp()
      Generate a state parameter with a creation timestamp for expiration checks. 生成带有创建时间戳的 state 参数，用于过期检查。
      Returns:
      the state data containing state string and creation timestamp | 包含 state 字符串和创建时间戳的 state 数据