Spring Boot / Spring Cloud 配置文件加密详解：使用 jasypt-spring-boot 实现 ENC() 加密

文章目录

- - - [一、引言：为什么需要配置文件加密？](#一、引言：为什么需要配置文件加密？)
    - [二、核心工具：jasypt-spring-boot](#二、核心工具：jasypt-spring-boot)
    - [三、安装与依赖](#三、安装与依赖)
    - [四、加密密钥（Password）管理](#四、加密密钥（Password）管理)
    - [五、执行加密](#五、执行加密)
    - - [方法一：命令行工具（使用 `jasypt` CLI）](#方法一：命令行工具（使用 jasypt CLI）)
      - [方法二：Java 工具类](#方法二：Java 工具类)
      - [方法三：使用 `jasypt-spring-boot` 提供的工具（需要将库引入到测试或单独的工具模块）](#方法三：使用 jasypt-spring-boot 提供的工具（需要将库引入到测试或单独的工具模块）)
    - [六、在配置文件中使用加密值](#六、在配置文件中使用加密值)
    - [七、 EncryptablePropertyResolver](#七、 EncryptablePropertyResolver)
    - [八、进阶配置与注意事项](#八、进阶配置与注意事项)
    - [九、总结](#九、总结)
    - 参考文档

一、引言：为什么需要配置文件加密？

在现代软件开发和部署中，应用程序的配置文件（如 application.properties 或 application.yml）常常包含敏感信息，例如：

数据库用户名和密码
第三方服务的 API Key 或 Secret
消息队列的连接凭证
Redis、MongoDB 等中间件的访问密码
加密密钥或证书路径

这些敏感信息如果以明文形式存储在配置文件中，无论是在代码仓库、服务器文件系统还是容器镜像里，都存在极大的安全风险。一旦泄露，可能导致数据被窃取、服务被滥用或系统被攻击。因此，对配置文件中的敏感信息进行加密处理是保障应用安全的重要环节。

本文将详细介绍如何使用 jasypt-spring-boot 库，在 Spring Boot 和 Spring Cloud 项目中实现配置文件内容的加密与解密。

二、核心工具：jasypt-spring-boot

jasypt-spring-boot 是一个集成 Jasypt (Java Simplified Encryption) 的 Spring Boot Starter，它极大地简化了在 Spring Boot 应用中进行属性加密和解密的过程。

Jasypt: 一个强大的 Java 加密库，提供简单的 API 来加密、解密密码、文本、数字等。
jasypt-spring-boot : 将 Jasypt 无缝集成到 Spring Boot 的 Environment 抽象层中，允许开发者使用特定的格式（如 ENC(encrypted_value)）来标记加密后的属性值。Spring Boot 在启动时会自动识别并解密这些值，使应用代码无需关心解密过程。

三、安装与依赖

首先，需要在你的 Spring Boot 项目的 pom.xml（Maven）或 build.gradle（Gradle）文件中添加 jasypt-spring-boot-starter 依赖。

Maven (pom.xml)

xml 复制代码

<dependency>
    <groupId>com.github.ulisesbocchio</groupId>
    <artifactId>jasypt-spring-boot-starter</artifactId>
    <version>3.0.5</version> <!-- 请根据你的 Spring Boot 版本选择合适的 jasypt 版本 -->
</dependency>

Gradle (build.gradle)

groovy 复制代码

dependencies {
    implementation 'com.github.ulisesbocchio:jasypt-spring-boot-starter:3.0.5'
    // ... 其他依赖
}

注意：jasypt-spring-boot 的版本通常需要与你的 Spring Boot 版本兼容。请查阅 GitHub Releases 页面选择正确的版本。

四、加密密钥（Password）管理

Jasypt 加密和解密都需要一个共享的加密密钥（Password）。这个密钥必须被安全地传递给应用。常见的设置方式有：

命令行参数 : java -jar myapp.jar --jasypt.encryptor.password=myStrongPassword
环境变量 : export JASYPT_ENCRYPTOR_PASSWORD=myStrongPassword && java -jar myapp.jar
配置文件 : 在 application.properties 或 application.yml 中设置（强烈不推荐 ，因为这样失去了加密的意义，但可用于测试）。例如：
properties 复制代码
```
# application.properties
jasypt.encryptor.password=myStrongPassword
```
yaml 复制代码
```
# application.yml
jasypt:
  encryptor:
    password: myStrongPassword
```

最佳实践 ：将 jasypt.encryptor.password 通过环境变量或命令行参数的方式传入，避免将其硬编码在配置文件中。

五、执行加密

加密操作可以通过多种方式进行，最常用的是使用命令行工具或编写一个简单的 Java 工具类。

方法一：命令行工具（使用 `jasypt` CLI）

下载 Jasypt 的发行包，解压后在 bin 目录下有各种脚本（encrypt.bat, encrypt.sh 等）。

执行命令：

bash 复制代码

./encrypt.sh input="your-sensitive-value" password="myStrongPassword"

（Windows 用户使用 encrypt.bat）

输出示例：

复制代码

----ENVIRONMENT-----------------
Runtime: Oracle Corporation Java HotSpot(TM) 64-Bit Server VM 25.201-b09
... (其他环境信息)

----ARGUMENTS-------------------
input: your-sensitive-value
password: myStrongPassword
...

----OUTPUT----------------------
UyBtaXNzaW5nIHlvdSB0aGVyZQ== # 这是加密后的值

方法二：Java 工具类

创建一个简单的 Java 类来执行加密：

java 复制代码

import org.jasypt.encryption.StringEncryptor;
import org.jasypt.encryption.pbe.StandardPBEStringEncryptor;
import org.jasypt.encryption.pbe.config.EnvironmentStringPBEConfig;

public class JasyptEncryptionUtil {

    public static void main(String[] args) {
        if (args.length != 1) {
            System.err.println("Usage: java JasyptEncryptionUtil <value_to_encrypt>");
            System.exit(1);
        }
        String valueToEncrypt = args[0];
        String password = System.getenv("JASYPT_ENCRYPTOR_PASSWORD"); // 从环境变量读取密码
        if (password == null || password.isEmpty()) {
             System.err.println("Error: JASYPT_ENCRYPTOR_PASSWORD environment variable is not set.");
             System.exit(2);
        }

        StandardPBEStringEncryptor encryptor = new StandardPBEStringEncryptor();
        EnvironmentStringPBEConfig config = new EnvironmentStringPBEConfig();
        config.setPassword(password); // 设置加密密码
        // 可选：设置算法、迭代次数等
        // config.setAlgorithm("PBEWithMD5AndDES");
        encryptor.setConfig(config);

        String encryptedValue = encryptor.encrypt(valueToEncrypt);
        System.out.println("Encrypted Value: " + encryptedValue);
    }
}

编译并运行：

bash 复制代码

javac -cp "path/to/jasypt-*.jar" JasyptEncryptionUtil.java
export JASYPT_ENCRYPTOR_PASSWORD=myStrongPassword
java -cp ".:path/to/jasypt-*.jar" JasyptEncryptionUtil "your-sensitive-value"

方法三：使用 `jasypt-spring-boot` 提供的工具（需要将库引入到测试或单独的工具模块）

如果你的应用已经包含了 jasypt-spring-boot-starter，你可以利用其内部的 StringEncryptor bean 来加密，但这通常不如前两种方法直接。

六、在配置文件中使用加密值

获得加密后的字符串后，你需要将其放入你的 Spring Boot 配置文件中。jasypt-spring-boot 会自动识别 ENC(encrypted_value) 格式的属性值并进行解密。

application.yml 示例：

yaml 复制代码

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mydb
    username: ENC(U2FsdGVkX1+...) # 加密后的用户名
    password: ENC(U2FsdGVkX1+...) # 加密后的密码
    driver-class-name: com.mysql.cj.jdbc.Driver

myapp:
  api:
    key: ENC(V2FsdGVkX1+...) # 加密后的API Key

application.properties 示例：

properties 复制代码

spring.datasource.url=jdbc:mysql://localhost:3306/mydb
spring.datasource.username=ENC(U2FsdGVkX1+...)
spring.datasource.password=ENC(U2FsdEVkX1+...)
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

myapp.api.key=ENC(V2FsdGVkX1+...)

当 Spring Boot 应用启动时，jasypt-spring-boot 会拦截这些属性的读取请求，检测到 ENC(...) 标记，然后使用配置的密码对其进行解密，并将解密后的原始值注入到相应的 Bean 属性或通过 @Value 注解注入到变量中。

七、 EncryptablePropertyResolver

EncryptablePropertyResolver 是 jasypt-spring-boot 内部使用的一个关键接口，用于解析包含 ENC() 标记的属性值。它扩展了 Spring 的 org.springframework.core.env.PropertyResolver 接口。

当 Environment 尝试解析一个属性时（例如 environment.getProperty("spring.datasource.password")），
jasypt-spring-boot 会提供一个实现了 EncryptablePropertyResolver 的包装器。
这个包装器检查属性值是否以 ENC( 开头且以 ) 结尾。
如果是，则提取括号内的加密字符串，使用 StringEncryptor 解密，并返回解密后的结果。
如果不是，则直接返回原始值。

开发者通常不需要直接与 EncryptablePropertyResolver 交互，jasypt-spring-boot-starter 会自动完成这一过程。

八、进阶配置与注意事项

自定义加密器 : 可以通过配置 jasypt.encryptor.* 属性来自定义加密算法、迭代次数、盐值生成器等。

yaml 复制代码

jasypt:
  encryptor:
    algorithm: PBEWITHHMACSHA512ANDAES_256 # 更强的算法
    iv-generator-classname: org.jasypt.iv.RandomIvGenerator # 使用随机IV
    # ... 其他配置

性能: 加密/解密操作在应用启动时发生，对于运行时性能影响很小。但如果需要频繁读取大量加密属性，可能会有微小开销。
安全性 : 确保加密密钥 jasypt.encryptor.password 的安全性至关重要。不要将其硬编码在代码或配置文件中。使用环境变量、Kubernetes Secrets、HashiCorp Vault 等外部化、安全的密钥管理方案是更好的选择。
Spring Cloud Config : 如果你使用 Spring Cloud Config 作为配置中心，同样可以在 Config Server 端或 Client 端启用 jasypt-spring-boot 来加密和解密从 Config Server 获取的配置。

九、总结

通过 jasypt-spring-boot，我们可以非常方便地在 Spring Boot 和 Spring Cloud 项目中实现配置文件的加密。其核心在于使用 ENC() 标记加密后的值，并通过 jasypt.encryptor.password 来解密。EncryptablePropertyResolver 在后台自动完成了识别、解密和替换的过程。正确管理和保护加密密钥是确保此安全措施有效性的关键。

希望这篇帖子能帮助您理解并应用 Spring Boot / Spring Cloud 的配置文件加密。

Spring Boot / Spring Cloud 配置文件加密详解：使用 jasypt-spring-boot 实现 ENC() 加密

文章目录

一、 引言：为什么需要配置文件加密？

二、 核心工具：jasypt-spring-boot

三、 安装与依赖

四、 加密密钥（Password）管理

五、 执行加密

方法一：命令行工具（使用 jasypt CLI）