Class BCryptUtil
java.lang.Object
com.sure.tool.crypto.BCryptUtil
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
FieldsModifier and TypeFieldDescriptionstatic final int默认 work factor(2^10 轮)。static final int最大 work factor。static final int密码最大字节数(OpenBSD 规范,不含追加的终止字节)。static final int最小 work factor。 -
Method Summary
Modifier and TypeMethodDescriptionstatic boolean校验明文密码是否与已存哈希匹配。static Stringgensalt()生成默认 work factor(10)的 BCrypt 盐串。static Stringgensalt(int cost) 生成指定 work factor 的 BCrypt 盐串。static String使用默认 work factor(10)对密码做 BCrypt 哈希。static String使用指定 work factor 对密码做 BCrypt 哈希。static boolean校验哈希串是否为合法 BCrypt 格式。
-
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
使用默认 work factor(10)对密码做 BCrypt 哈希。返回 60 字符哈希串,形如
$2a$10$<盐22字符><哈希31字符>。 每次调用使用 16 字节随机盐,同一密码两次哈希结果不同。- Parameters:
password- 明文密码,不能为 null;UTF-8 编码后不得超过 72 字节- Returns:
- 60 字符 BCrypt 哈希串
- Throws:
NullPointerException- password 为 nullIllegalArgumentException- 密码 UTF-8 编码后超过 72 字节- See Also:
-
hash
使用指定 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 为 nullIllegalArgumentException- 密码超过 72 字节,或 cost 越界- See Also:
-
check
校验明文密码是否与已存哈希匹配。兼容
$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
生成默认 work factor(10)的 BCrypt 盐串。返回形如
$2a$10$<22字符盐>的盐串,可直接作为hash(String, int)的内部盐使用。- Returns:
- 29 字符盐串
- See Also:
-
gensalt
生成指定 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
校验哈希串是否为合法 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(不抛异常)
-