Jasypt实现配置文件密码加密

一、引言

在Spring Boot项目的日常开发中，我们经常需要在配置文件中存储敏感信息，如数据库密码、API密钥、第三方服务凭证等。明文存储这些敏感信息存在巨大的安全风险：

• 配置文件可能被误提交到代码仓库，导致敏感信息泄露
• 服务器配置文件可能被未授权人员访问
• 日志打印时可能意外泄露密码信息

**Jasypt（Java Simplified Encryption）**是一个为Spring Boot提供简单加密能力的开源库，它能够帮助我们轻松实现配置文件敏感信息的加密存储。通过Jasypt，我们可以：

• 对配置文件中的敏感字段进行加密存储
• 应用启动时自动解密并注入到Spring环境中
• 支持多种加密算法，灵活性强
• 配置简单，对业务代码无侵入

本文将详细介绍如何在Spring Boot项目中整合Jasypt，实现配置文件密码的安全加密。

二、环境准备

2.1 开发环境要求

2.2 项目结构

本文示例基于标准的Spring Boot项目结构，主要涉及以下文件：

• pom.xml/build.gradle- 项目构建文件
• application.yml/application.properties- 配置文件
• 加密测试类 - 用于生成加密字符串

三、整合步骤

3.1 添加Jasypt依赖

Maven配置方式

在pom.xml中添加Jasypt依赖：

<dependencies><!-- Jasypt Spring Boot Starter --><dependency><groupId>com.github.ulisesbocchio</groupId><artifactId>jasypt-spring-boot-starter</artifactId><version>3.0.5</version></dependency></dependencies>

Gradle配置方式

在build.gradle中添加依赖：

dependencies { implementation 'com.github.ulisesbocchio:jasypt-spring-boot-starter:3.0.5' }

版本选择说明：

• Spring Boot 2.x 项目建议使用jasypt-spring-boot-starter:3.0.5
• Spring Boot 3.x 项目建议使用jasypt-spring-boot-starter:3.0.5（已兼容）

3.2 配置加密密钥

Jasypt需要使用一个加密密钥（盐值）来进行加密和解密操作。这个密钥需要妥善保管，不能泄露。

方式一：配置文件中指定密钥（仅用于开发环境）

# application.ymljasypt:encryptor:# 加密密钥（生产环境建议通过环境变量或命令行参数传入）password:my-secret-key-123456# 加密算法，默认PBEWithMD5AndDESalgorithm:PBEWithMD5AndDES# 获取密钥的IV生成器（初始化向量）iv-generator-classname:org.jasypt.iv.NoIvGenerator

或使用properties格式：

# application.properties jasypt.encryptor.password=my-secret-key-123456 jasypt.encryptor.algorithm=PBEWithMD5AndDES

方式二：环境变量传入密钥（推荐生产环境使用）

# Linux/MacexportJASYPT_ENCRYPTOR_PASSWORD=my-secret-key-123456# WindowssetJASYPT_ENCRYPTOR_PASSWORD=my-secret-key-123456

然后在配置文件中使用占位符：

jasypt:encryptor:password:${JASYPT_ENCRYPTOR_PASSWORD}

3.3 生成加密字符串

在配置文件中使用Jasypt前，需要先生成加密后的字符串。可以通过以下几种方式生成：

方式一：编写加密工具类

importorg.jasypt.encryption.pbe.StandardPBEStringEncryptor;importorg.jasypt.encryption.pbe.config.EnvironmentPBEConfig;publicclassJasyptUtil{/** * 加密方法 * @param plainText 明文 * @param password 密钥 * @return 加密后的密文 */publicstaticStringencrypt(StringplainText,Stringpassword){StandardPBEStringEncryptorencryptor=newStandardPBEStringEncryptor();EnvironmentPBEConfigconfig=newEnvironmentPBEConfig();config.setPassword(password);// 设置密钥config.setAlgorithm("PBEWithMD5AndDES");// 设置加密算法encryptor.setConfig(config);returnencryptor.encrypt(plainText);}/** * 解密方法 * @param encryptedText 密文 * @param password 密钥 * @return 解密后的明文 */publicstaticStringdecrypt(StringencryptedText,Stringpassword){StandardPBEStringEncryptorencryptor=newStandardPBEStringEncryptor();EnvironmentPBEConfigconfig=newEnvironmentPBEConfig();config.setPassword(password);config.setAlgorithm("PBEWithMD5AndDES");encryptor.setConfig(config);returnencryptor.decrypt(encryptedText);}publicstaticvoidmain(String[]args){Stringpassword="my-secret-key-123456";StringplainText="root123456";// 加密Stringencrypted=encrypt(plainText,password);System.out.println("加密后的密文: "+encrypted);// 解密验证Stringdecrypted=decrypt(encrypted,password);System.out.println("解密后的明文: "+decrypted);}}

执行结果示例：

加密后的密文: i4Uj+L8k7JGjXwZt3qK9PQ== 解密后的明文: root123456

方式二：使用Spring Boot测试类生成

importorg.jasypt.encryption.pbe.StandardPBEStringEncryptor;importorg.junit.jupiter.api.Test;importorg.springframework.boot.test.context.SpringBootTest;@SpringBootTestpublicclassJasyptEncryptorTest{@TestpublicvoidtestEncrypt(){StandardPBEStringEncryptorencryptor=newStandardPBEStringEncryptor();encryptor.setPassword("my-secret-key-123456");// 与配置文件中的密钥保持一致StringplainText="root123456";Stringencrypted=encryptor.encrypt(plainText);System.out.println("原始密码: "+plainText);System.out.println("加密密码: "+encrypted);System.out.println("解密验证: "+encryptor.decrypt(encrypted));}}

3.4 配置文件中使用加密字符串

将生成的加密字符串包裹在ENC()中，即可在配置文件中使用：

YAML格式配置示例

spring:datasource:driver-class-name:com.mysql.cj.jdbc.Driverurl:jdbc:mysql://localhost:3306/mydb?useSSL=false&serverTimezone=UTCusername:root# 密码使用Jasypt加密后的字符串，用ENC()包裹password:ENC(i4Uj+L8k7JGjXwZt3qK9PQ==)# Redis配置redis:host:localhostport:6379password:ENC(aB3xY9mP5kL2nQ8rT1vW==)# 第三方API配置third-party:api:key:ENC(xY7kL3mN9oP2qR5sT8vW0z==)secret:ENC(pQ4rS7tU0vW2xY5zA8bC==)

Properties格式配置示例

# 数据库配置 spring.datasource.url=jdbc:mysql://localhost:3306/mydb?useSSL=false&serverTimezone=UTC spring.datasource.username=root spring.datasource.password=ENC(i4Uj+L8k7JGjXwZt3qK9PQ==) # Redis配置 redis.host=localhost redis.port=6379 redis.password=ENC(aB3xY9mP5kL2nQ8rT1vW==)

3.5 测试验证

编写测试验证类

importorg.junit.jupiter.api.Test;importorg.springframework.beans.factory.annotation.Value;importorg.springframework.boot.test.context.SpringBootTest;@SpringBootTestpublicclassJasyptIntegrationTest{@Value("${spring.datasource.password}")privateStringdbPassword;@Value("${redis.password}")privateStringredisPassword;@TestpublicvoidtestDecryptedPassword(){System.out.println("数据库密码（已解密）: "+dbPassword);System.out.println("Redis密码（已解密）: "+redisPassword);// 验证解密是否正确assertdbPassword.equals("root123456");assertredisPassword.equals("redis123456");}}

验证步骤

1. 启动应用：确保配置正确，启动Spring Boot应用
2. 查看日志：应用启动成功，无解密错误日志
3. 连接测试：验证数据库、Redis等连接是否正常
4. 测试类执行：运行上述测试类，验证密码解密正确

成功标志：

• 应用正常启动，无异常报错
• 数据库连接成功，可以正常执行SQL
• 测试类断言通过，解密后的密码与原始密码一致

四、高级配置

4.1 密钥外部化配置

环境变量方式（生产环境推荐）

Linux/Mac系统：

# 临时设置（当前终端有效）exportJASYPT_ENCRYPTOR_PASSWORD=production-secret-key-2024# 永久设置（写入 ~/.bashrc 或 ~/.bash_profile）echo'export JASYPT_ENCRYPTOR_PASSWORD=production-secret-key-2024'>>~/.bashrcsource~/.bashrc

Windows系统：

# 临时设置 set JASYPT_ENCRYPTOR_PASSWORD=production-secret-key-2024 # 永久设置（系统环境变量） # 1. 右键"此电脑" -> "属性" -> "高级系统设置" # 2. 点击"环境变量" # 3. 在"系统变量"中添加 JASYPT_ENCRYPTOR_PASSWORD

Docker容器启动方式：

dockerrun -eJASYPT_ENCRYPTOR_PASSWORD=production-secret-key-2024 your-app:latest

配置文件中使用：

jasypt:encryptor:password:${JASYPT_ENCRYPTOR_PASSWORD:default-secret-key}

命令行参数方式

java -jar your-app.jar --jasypt.encryptor.password=production-secret-key-2024

Spring Boot Config Server方式

如果使用Spring Cloud Config，可以在配置中心配置：

# config server的配置文件jasypt:encryptor:password:${JASYPT_ENCRYPTOR_PASSWORD}

4.2 自定义加密算法配置

Jasypt支持多种加密算法，可以根据安全需求选择合适的算法。

常用加密算法对比

配置自定义算法

jasypt:encryptor:password:${JASYPT_ENCRYPTOR_PASSWORD}# 使用更安全的AES-256算法algorithm:PBEWITHHMACSHA512ANDAES_256# 指定IV生成器iv-generator-classname:org.jasypt.iv.RandomIvGenerator# 密钥获取迭代次数key-obtention-iterations:1000# 池大小pool-size:1# 盐值生成器类名salt-generator-classname:org.jasypt.salt.RandomSaltGenerator# 字符串输出类型string-output-type:base64

注意：更改加密算法后，需要重新生成所有加密字符串！

自定义加密器Bean

如果需要更复杂的配置，可以自定义加密器：

importorg.jasypt.encryption.pbe.PooledPBEStringEncryptor;importorg.jasypt.encryption.pbe.config.SimpleStringPBEConfig;importorg.springframework.beans.factory.annotation.Value;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;@ConfigurationpublicclassJasyptConfig{@Value("${jasypt.encryptor.password}")privateStringencryptorPassword;@Bean("jasyptStringEncryptor")publicPooledPBEStringEncryptorstringEncryptor(){PooledPBEStringEncryptorencryptor=newPooledPBEStringEncryptor();SimpleStringPBEConfigconfig=newSimpleStringPBEConfig();config.setPassword(encryptorPassword);config.setAlgorithm("PBEWITHHMACSHA512ANDAES_256");config.setKeyObtentionIterations("1000");config.setPoolSize("1");config.setSaltGeneratorClassName("org.jasypt.salt.RandomSaltGenerator");config.setIvGeneratorClassName("org.jasypt.iv.RandomIvGenerator");config.setStringOutputType("base64");encryptor.setConfig(config);returnencryptor;}}

4.3 敏感字段指定加密

方式一：全局解密（默认）

配置了Jasypt后，所有使用ENC()包裹的字符串都会自动解密：

# 所有ENC()包裹的都会被解密spring:datasource:password:ENC(encrypted-password-1)redis:password:ENC(encrypted-password-2)

方式二：指定特定字段加密

如果只想对某些特定字段进行加密处理，可以在配置中指定前缀：

jasypt:encryptor:password:${JASYPT_ENCRYPTOR_PASSWORD}property:prefix:ENC(suffix:)

方式三：使用注解方式加密

对于程序中的字符串，也可以使用Jasypt注解：

importorg.jasypt.encryption.pbe.StandardPBEStringEncryptor;importorg.springframework.stereotype.Service;@ServicepublicclassEncryptionService{privatefinalStandardPBEStringEncryptorencryptor;publicEncryptionService(StandardPBEStringEncryptorencryptor){this.encryptor=encryptor;}publicStringencrypt(StringplainText){returnencryptor.encrypt(plainText);}publicStringdecrypt(StringencryptedText){returnencryptor.decrypt(encryptedText);}}

五、常见问题解决

5.1 问题一：启动时报"Failed to decrypt"错误

现象：

Error creating bean with name 'dataSource': Failed to decrypt encrypted value ENC(encrypted-password)

原因分析：

• 加密密钥与解密密钥不一致
• 加密算法配置不匹配
• 加密字符串格式错误

解决方案：

1. 检查密钥一致性：确保加密时使用的密钥与配置文件中的密钥完全一致
2. 验证算法配置：确认加密和解密使用相同的算法
3. 重新生成密文：使用当前配置重新生成加密字符串

# 检查配置是否一致jasypt:encryptor:password:${JASYPT_ENCRYPTOR_PASSWORD}algorithm:PBEWithMD5AndDES# 与加密时使用的算法必须一致

5.2 问题二：密钥管理不当导致安全隐患

现象：密钥硬编码在配置文件中，容易被泄露

解决方案：

1. 使用环境变量（推荐）：

jasypt:encryptor:password:${JASYPT_ENCRYPTOR_PASSWORD}

2. 使用外部配置中心：

   • 集成Spring Cloud Config
   • 使用Vault等密钥管理工具
   • 使用K8s Secrets

3. 使用启动参数：

java -jar app.jar --jasypt.encryptor.password=${JASYPT_ENCRYPTOR_PASSWORD}

5.3 问题三：多环境配置管理混乱

现象：开发、测试、生产环境使用不同的密钥，导致配置混乱

解决方案：

方案一：使用Profile隔离配置

# application-dev.ymljasypt:encryptor:password:dev-secret-key# application-test.ymljasypt:encryptor:password:test-secret-key# application-prod.ymljasypt:encryptor:password:${JASYPT_ENCRYPTOR_PASSWORD}

方案二：统一密钥生成脚本

创建加密工具脚本，根据环境生成对应的加密字符串：

publicclassEncryptionGenerator{publicstaticvoidmain(String[]args){Stringenv=args[0];// dev/test/prodStringpassword=getPasswordByEnv(env);StringplainText=args[1];StandardPBEStringEncryptorencryptor=newStandardPBEStringEncryptor();encryptor.setPassword(password);encryptor.setAlgorithm("PBEWithMD5AndDES");Stringencrypted=encryptor.encrypt(plainText);System.out.println(env+"环境加密结果: "+encrypted);}privatestaticStringgetPasswordByEnv(Stringenv){switch(env){case"dev":return"dev-secret-key";case"test":return"test-secret-key";case"prod":returnSystem.getenv("JASYPT_ENCRYPTOR_PASSWORD");default:thrownewIllegalArgumentException("未知环境: "+env);}}}

六、总结

6.1 Jasypt的核心优势

通过本文的实践，我们可以总结出Jasypt的几个核心优势：

1. 配置简单：仅需添加依赖和简单配置即可使用
2. 非侵入性：对业务代码无侵入，通过注解和配置即可实现
3. 灵活性强：支持多种加密算法和配置方式
4. 安全性高：支持密钥外部化管理，避免密钥泄露
5. 社区活跃：有完善的文档和社区支持

6.2 使用注意事项

在实际项目使用中，需要注意以下几点：

安全方面：

• ❌禁止将密钥硬编码在配置文件中并提交到代码仓库
• ✅推荐使用环境变量或密钥管理工具存储密钥
• ✅定期更换密钥，特别是在发生人员变动时
• ✅ 生产环境使用更安全的加密算法（如AES-256）

运维方面：

• 🔐 做好密钥的备份和恢复机制
• 📝 建立完善的密钥管理制度和流程
• 🔄 更换密钥时需要同步更新所有加密配置
• 📊 在日志中避免打印解密后的敏感信息

开发方面：

• 🛠️ 提供便捷的加密工具，提升开发效率
• 📝 在项目README中记录加密配置说明
• 🧪 编写单元测试验证加密解密功能
• 🔍 代码审查时重点检查敏感信息处理

6.3 最佳实践建议

1. 环境隔离：不同环境使用不同的密钥
2. 密钥轮换：建立定期更换密钥的机制
3. 工具化：开发加密工具类，简化加密流程
4. 文档化：完善配置文档，方便团队协作
5. 监控告警：监控解密失败等异常情况

通过合理使用Jasypt，我们可以有效提升Spring Boot项目的安全性，保护敏感配置信息不被泄露。在实际项目中，应该根据自身需求和安全要求，选择合适的配置方案和加密策略。

参考资料：

• Jasypt官方文档
• jasypt-spring-boot-starter GitHub
• Spring Boot官方文档