密码编码器使用指南

密码编码器概述

通过第三章的学习，您应该已经对UserDetails接口及其多种实现方式有了清晰认识。如第二章所述，在认证授权流程中，不同参与者负责管理用户凭证的表示形式，其中UserDetailsService和PasswordEncoder等组件都提供了默认实现。本节将重点分析PasswordEncoder的核心机制，图4.1展示了其在Spring Security认证流程中的关键位置。

密码编码的必要性

系统通常不会以明文形式存储密码，而是通过特定转换算法使其难以被直接读取。Spring Security为此专门定义了PasswordEncoder契约。其核心职责体现在两个抽象方法上：

• encode(CharSequence rawPassword)：对原始密码进行转换
• matches(CharSequence rawPassword, String encodedPassword)：验证密码匹配性

这两个方法具有强关联性——通过encode()方法生成的编码结果必须能被同一编码器的matches()方法验证。

基础实现示例

最简单的实现是明文密码编码器（类似NoOpPasswordEncoder）：

public class PlainTextPasswordEncoder implements PasswordEncoder {
   
  @Override
  public String encode(CharSequence rawPassword) {
   
    return rawPassword.toString();
  }

  @Override
  public boolean matches(CharSequence rawPassword, String encodedPassword) {
   
    return rawPassword.equals(encodedPassword);
  }
}

更安全的实现可采用SHA-512哈希算法：

public class Sha512PasswordEncoder implements PasswordEncoder {
   
  @Override
  public String encode(CharSequence rawPassword) {
   
    return hashWithSHA512(rawPassword.toString());
  }

  private String hashWithSHA512(String input) {
   
    // 具体哈希实现代码...
  }
}

内置编码器类型

Spring Security提供了多种开箱即用的实现：

1. NoOpPasswordEncoder
   仅用于示例的明文存储，生产环境严禁使用：

   PasswordEncoder p = NoOpPasswordEncoder.getInstance();
   

2. StandardPasswordEncoder（已弃用）
   基于SHA-256算法，新项目不建议使用

3. Pbkdf2PasswordEncoder
   基于PBKDF2算法，可配置迭代次数：

   PasswordEncoder p = new Pbkdf2PasswordEncoder("secret", 16, 310000, 
                          Pbkdf2PasswordEncoder.SecretKeyFactoryAlgorithm.PBKDF2WithHmacSHA256);
   

4. BCryptPasswordEncoder
   推荐方案，支持强度系数配置：

   PasswordEncoder p = new BCryptPasswordEncoder(4);
   

5. SCryptPasswordEncoder
   需要配置CPU/内存成本等参数

多编码策略委托模式

当系统需要支持多种编码算法时（如逐步升级哈希算法），可采用DelegatingPasswordEncoder：

@Bean
public PasswordEncoder passwordEncoder() {
   
  Map encoders = new HashMap<>();
  encoders.put("noop", NoOpPasswordEncoder.getInstance());
  encoders.put("bcrypt", new BCryptPasswordEncoder());
  return new DelegatingPasswordEncoder("bcrypt", encoders);
}

该实现通过密码前缀（如{bcrypt}$2a$10$...）自动选择对应的编码器，无前缀时使用默认编码器。Spring Security还提供了快捷创建方法：

PasswordEncoder passwordEncoder = PasswordEncoderFactories.createDelegatingPasswordEncoder();

术语辨析

• 编码(Encoding)：任意形式的输入转换
• 加密(Encrypting)：需要密钥的可逆转换
• 哈希(Hashing)：不可逆的单向转换，通常包含加盐机制

表4.1总结了Spring Security认证流程中的核心契约：

PasswordEncoder接口解析

核心方法设计

PasswordEncoder接口定义了密码处理的核心契约，包含三个关键方法：

public interface PasswordEncoder {
   
  String encode(CharSequence rawPassword);
  boolean matches(CharSequence rawPassword, String encodedPassword);
  
  default boolean upgradeEncoding(String encodedPassword) {
    
    return false; 
  }
}

encode()方法：原始密码转换

作为密码编码的入口方法，encode(CharSequence rawPassword)接收原始密码字符序列，返回经过特定算法转换后的字符串。在Spring Security的上下文中，该方法主要用于实现以下两种转换逻辑：

1. 加密处理（如AES等可逆算法）
2. 哈希计算（如SHA系列不可逆算法）

典型实现要求：

• 必须保证幂等性：相同输入始终产生相同输出
• 推荐引入随机盐值增强安全性
• 应当避免输出包含原始密码的任何特征

matches()方法：密码验证核心

matches(CharSequence rawPassword, String encodedPassword)方法构成认证流程的核心校验环节，其实现必须与encode()方法保持严格的逻辑一致性。方法参数包含：

• rawPassword：用户提交的原始密码
• encodedPassword：系统存储的已编码密码

实现要点：

@Override
public boolean matches(CharSequence rawPassword, String encodedPassword) {
   
  // 必须采用与