Spring Boot Security配置适配PHP逻辑的HMAC-SHA512密码编码器

• 之前使用Pbkdf2PasswordEncoder报错的根源是算法逻辑完全错配：旧PHP系统用的是单次计算的HMAC-SHA512 + Base64存储逻辑，和带多轮迭代、慢哈希设计的PBKDF2算法没有任何兼容关系，哪怕两者底层都用到SHA512，最终计算结果完全不同。
• 报错Detected a Non-hex character at 1 or 2 position的直接原因是：旧系统存储的是Base64编码的哈希值，而Pbkdf2PasswordEncoder默认会把传入的存储值当成十六进制字符串解析，自然会识别失败。

要1:1对齐旧PHP的计算逻辑，需要逐行匹配base64_encode(hash_hmac("sha512", $p_password, $p_salt, true))的每个环节，核心实现要点：

• 用Java原生javax.crypto.Mac实现HMAC-SHA512计算，完全对齐PHP的二进制输出（对应hash_hmac最后一个参数传true的逻辑，而非默认的十六进制输出）
• 所有字符串转字节环节强制使用UTF-8编码，避免平台默认字符集导致的计算偏差
• 最终哈希结果使用Java标准无换行Base64编码器输出，和PHP的base64_encode输出完全一致
• 比对环节使用恒定时间比较逻辑，避免时序攻击风险

核心实现代码参考：

public class PhpHmacSha512PasswordEncoder implements PasswordEncoder {
    // 全局固定salt如果实际是用户独立存储的，从用户维度上下文获取即可
    private final String globalSalt;
    private static final String HMAC_SHA512 = "HmacSHA512";

    public PhpHmacSha512PasswordEncoder(String globalSalt) {
        this.globalSalt = globalSalt;
    }

    @Override
    public String encode(CharSequence rawPassword) {
        // 旧系统编码器仅用于存量密码校验，不用于生成新密码
        throw new UnsupportedOperationException("Legacy PHP encoder is only for stored credential verification");
    }

    @Override
    public boolean matches(CharSequence rawPassword, String encodedPassword) {
        try {
            Mac mac = Mac.getInstance(HMAC_SHA512);
            SecretKeySpec key = new SecretKeySpec(globalSalt.getBytes(StandardCharsets.UTF_8), HMAC_SHA512);
            mac.init(key);
            byte[] hashBytes = mac.doFinal(rawPassword.toString().getBytes(StandardCharsets.UTF_8));
            String calculatedBase64 = Base64.getEncoder().encodeToString(hashBytes);
            // 恒定时间比对
            return MessageDigest.isEqual(calculatedBase64.getBytes(StandardCharsets.UTF_8),
                    encodedPassword.getBytes(StandardCharsets.UTF_8));
        } catch (Exception e) {
            throw new RuntimeException("HMAC-SHA512 calculation failed", e);
        }
    }
}

前缀规则的必要性 #

必须给数据库中的旧密码记录加上指定编码器的识别前缀，没有前缀的话DelegatingPasswordEncoder无法自动匹配对应编码器，也没法区分新旧密码的处理逻辑。

具体配置步骤 #

1. 定义编码器映射关系：
   • 自定义旧PHP HMAC-SHA512编码器的前缀：{phpHmacSha512}
   • 新用户使用的BCrypt编码器固定前缀：{bcrypt}
2. 构建Bean的代码实现：

@Bean
public PasswordEncoder passwordEncoder() {
    // 初始化旧系统的编码器，替换为旧PHP系统实际的salt值
    PhpHmacSha512PasswordEncoder legacyEncoder = new PhpHmacSha512PasswordEncoder("旧系统实际使用的salt值");
    // 新密码使用的BCrypt编码器
    BCryptPasswordEncoder bcryptEncoder = new BCryptPasswordEncoder();

    // 构建编码器映射关系
    Map<String, PasswordEncoder> encoders = new HashMap<>();
    encoders.put("phpHmacSha512", legacyEncoder);
    encoders.put("bcrypt", bcryptEncoder);

    // 设置默认编码器为BCrypt，新生成的密码自动携带{bcrypt}前缀
    return new DelegatingPasswordEncoder("bcrypt", encoders);
}

3. 存量数据迁移：批量将数据库中所有旧的密码值，在字符串开头拼接上{phpHmacSha512}前缀，比如原存储值为abc123base64xxx，迁移后变为{phpHmacSha512}abc123base64xxx。

• 不要尝试直接复用Pbkdf2PasswordEncoder做旧逻辑适配：PBKDF2需要指定迭代次数、密钥长度，输出逻辑和单次HMAC计算的结果完全无法对齐。
• 字符串编码统一用UTF-8：PHP的字符串默认是字节流，Java如果使用平台默认字符集（比如Windows下的GBK）转字节，会导致HMAC计算结果完全和旧系统不匹配。
• 不要使用带换行的MIME Base64编码：Java的Base64.getMimeEncoder()会在输出中插入换行符，和PHP的base64输出不一致，必须用Base64.getEncoder()。
• 校验逻辑上线后，可在认证通过的回调中检测当前用户的密码前缀，如果是旧的{phpHmacSha512}，就自动用BCrypt重新编码明文密码并更新到数据库，逐步完成存量密码的升级，不需要强制用户批量改密。

内容的提问来源于stack exchange，提问作者TCH