Class BCryptUtil

java.lang.Object
com.sure.tool.crypto.BCryptUtil

public final class BCryptUtil extends Object
BCrypt 密码哈希工具,实现 OpenBSD bcrypt(EksBlowfish)方案。

设计目标(默认安全基线):

  • 默认 work factor 为 10(2^10 轮),成本随硬件提升可调(4–30);
  • 盐为 16 字节 SecureRandom 随机值,每次哈希结果唯一;
  • check(String, String) 采用恒定时间比较,不短路、不提前返回;
  • 密码按 UTF-8 编码,超过 72 字节时显式抛出 IllegalArgumentException, 绝不静默截断(与 Spring Security 5+ 行为一致,区别于 Hutool 的截断语义);
  • 与 OpenBSD / Python bcrypt / jBCrypt 输出完全互通($2a$/$2b$/$2y$ 前缀)。

标准参考:Provos & Mazières, "A Future-Adaptable Password Scheme"(1999)。 Blowfish P/S 盒常量与算法结构与 jBCrypt(BSD 许可,Damien Miller)一致。

Since:
1.19.0
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    默认 work factor(2^10 轮)。
    static final int
    最大 work factor。
    static final int
    密码最大字节数(OpenBSD 规范,不含追加的终止字节)。
    static final int
    最小 work factor。
  • Method Summary

    Modifier and Type
    Method
    Description
    static boolean
    check(String password, String hash)
    校验明文密码是否与已存哈希匹配。
    static String
    生成默认 work factor(10)的 BCrypt 盐串。
    static String
    gensalt(int cost)
    生成指定 work factor 的 BCrypt 盐串。
    static String
    hash(String password)
    使用默认 work factor(10)对密码做 BCrypt 哈希。
    static String
    hash(String password, int cost)
    使用指定 work factor 对密码做 BCrypt 哈希。
    static boolean
    校验哈希串是否为合法 BCrypt 格式。

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • DEFAULT_COST

      public static final int DEFAULT_COST
      默认 work factor(2^10 轮)。
      See Also:
    • MIN_COST

      public static final int MIN_COST
      最小 work factor。
      See Also:
    • MAX_COST

      public static final int MAX_COST
      最大 work factor。
      See Also:
    • MAX_PASSWORD_BYTES

      public static final int MAX_PASSWORD_BYTES
      密码最大字节数(OpenBSD 规范,不含追加的终止字节)。
      See Also:
  • Method Details

    • hash

      public static String hash(String password)
      使用默认 work factor(10)对密码做 BCrypt 哈希。

      返回 60 字符哈希串,形如 $2a$10$<盐22字符><哈希31字符>。 每次调用使用 16 字节随机盐,同一密码两次哈希结果不同。

      Parameters:
      password - 明文密码,不能为 null;UTF-8 编码后不得超过 72 字节
      Returns:
      60 字符 BCrypt 哈希串
      Throws:
      NullPointerException - password 为 null
      IllegalArgumentException - 密码 UTF-8 编码后超过 72 字节
      See Also:
    • hash

      public static String hash(String password, int cost)
      使用指定 work factor 对密码做 BCrypt 哈希。

      work factor 为 2 的指数:cost=10 约 1024 轮,cost=12 约 4096 轮。 建议生产环境使用 10–12,交互式登录取 10,高安全场景取 12。

      示例:

      String h = BCryptUtil.hash("P@ssw0rd", 12);
      
      Parameters:
      password - 明文密码,不能为 null;UTF-8 编码后不得超过 72 字节
      cost - work factor,取值范围 [4, 30]
      Returns:
      60 字符 BCrypt 哈希串
      Throws:
      NullPointerException - password 为 null
      IllegalArgumentException - 密码超过 72 字节,或 cost 越界
      See Also:
    • check

      public static boolean check(String password, String hash)
      校验明文密码是否与已存哈希匹配。

      兼容 $2a$、$2b$、$2y$ 三种前缀;比较采用恒定时间 逐字节异或,不因前缀命中差异提前返回,抵抗时序侧信道。

      示例:

      String h = BCryptUtil.hash("P@ssw0rd");
      boolean ok = BCryptUtil.check("P@ssw0rd", h); // true
      
      Parameters:
      password - 待校验明文密码,不能为 null;UTF-8 编码后不得超过 72 字节
      hash - 已存哈希串(形如 $2a$10$...),不能为 null
      Returns:
      匹配返回 true
      Throws:
      IllegalArgumentException - 密码超过 72 字节、password 或 hash 为 null、 hash 格式非法(非 bcrypt 前缀 / cost 越界 / 长度不足)
    • gensalt

      public static String gensalt()
      生成默认 work factor(10)的 BCrypt 盐串。

      返回形如 $2a$10$<22字符盐> 的盐串,可直接作为 hash(String, int) 的内部盐使用。

      Returns:
      29 字符盐串
      See Also:
    • gensalt

      public static String gensalt(int cost)
      生成指定 work factor 的 BCrypt 盐串。

      盐为 16 字节密码学安全随机值,经 BCrypt base64 编码为 22 字符。

      示例:

      String salt = BCryptUtil.gensalt(12);
      
      Parameters:
      cost - work factor,取值范围 [4, 30]
      Returns:
      29 字符盐串(含 $2a$ 前缀与 cost)
      Throws:
      IllegalArgumentException - cost 越界
    • isValid

      public static boolean isValid(String hash)
      校验哈希串是否为合法 BCrypt 格式。

      校验项:非 null、长度 60、前缀为 $2a$/$2b$/$2y$、 cost 为两位数字且在 [4, 30]、盐与哈希段全部由 BCrypt base64 字符组成。 不校验哈希与任何密码的匹配关系。

      示例:

      boolean ok = BCryptUtil.isValid("$2a$10$7EqJtq98hPqEX7fNZaFWoO..."); // true
      
      Parameters:
      hash - 待校验哈希串
      Returns:
      格式合法返回 true;null 或格式非法返回 false(不抛异常)