配置信息加密

本文档说明如何使用 KeyEncrypt 对 etc/config.properties 等配置文件中的敏感值进行加密，并在应用启动时完成解密。

使用场景

当配置文件中包含数据库密码、Ranger 密码、Kafka 密码、ZooKeeper 认证凭据等敏感信息时，可以先使用 KeyEncrypt 生成密文，再将密文写入配置文件。应用启动时通过 KeyEncrypt 读取启动参数中的加密口令和算法，对配置值进行解密。

生成密文

使用 key-encrypt-jasypt-generator.jar 生成密文。该 jar 一般随 AIR 部署包提供，常见路径为 /data/offline_deployment/package：

java -jar key-encrypt-jasypt-generator.jar -a <加密算法> -p <密码> -v <需要加密的值>

参数说明：

参数	说明
`-a`	加密算法，需与应用启动参数 `key.encrypt.jasypt.algorithm` 保持一致。
`-p`	加密密码，需与应用启动参数 `key.encrypt.jasypt.password` 保持一致。
`-v`	需要加密的原始明文值。

示例：

java -jar key-encrypt-jasypt-generator.jar -a PBEWithMD5AndDES -p 'Aloudata@202501011qaz!QAZ' -v 'VPwSrFw2lVfFokJ'

注意

命令中的密码和明文值建议使用单引号包裹，避免 !、$、& 等特殊字符被 Shell 解释。

生成密文后，需要使用 ENC(...) 包裹密文，并写入原配置项的值位置。例如：

jdbc.password=ENC(<生成的密文>)
ranger.admin.password=ENC(<生成的密文>)

ENC(...) 是 KeyEncrypt 识别密文配置的标记，括号内只填写生成器输出的密文内容，不需要再额外加引号。

应用启动配置

使用到加密配置的应用，需要让 JVM 启动时拿到以下 system property。可以直接在启动命令中追加 -D 参数，也可以通过临时环境变量注入这些 -D 参数。

方式一：通过 `-D` 参数指定

-Dkey.encrypt.type=jasypt
-Dkey.encrypt.jasypt.password=<密码>
-Dkey.encrypt.jasypt.algorithm=<加密算法>

示例：

-Dkey.encrypt.type=jasypt -Dkey.encrypt.jasypt.password='Aloudata@202501011qaz!QAZ' -Dkey.encrypt.jasypt.algorithm=PBEWithMD5AndDES

方式二：通过临时环境变量指定

KeyEncrypt 读取的是 JVM system property，因此环境变量方式需要通过 JAVA_TOOL_OPTIONS 或 JDK_JAVA_OPTIONS 临时注入 -D 参数。例如：

export JAVA_TOOL_OPTIONS="-Dkey.encrypt.type=jasypt -Dkey.encrypt.jasypt.password=Aloudata@202501011qaz!QAZ -Dkey.encrypt.jasypt.algorithm=PBEWithMD5AndDES"

也可以只对单次启动命令生效：

JAVA_TOOL_OPTIONS="-Dkey.encrypt.type=jasypt -Dkey.encrypt.jasypt.password=Aloudata@202501011qaz!QAZ -Dkey.encrypt.jasypt.algorithm=PBEWithMD5AndDES" ./bin/launcher run

JDK 9 及以上也可以使用 JDK_JAVA_OPTIONS：

JDK_JAVA_OPTIONS="-Dkey.encrypt.type=jasypt -Dkey.encrypt.jasypt.password=Aloudata@202501011qaz!QAZ -Dkey.encrypt.jasypt.algorithm=PBEWithMD5AndDES" ./bin/launcher run

如果使用 PBEWithHmacSHA*AndAES_* 等 SHA/AES 类算法，按 KeyEncrypt 约定还需要增加 IV 生成器配置。通过 -D 参数指定时追加：

-Dkey.encrypt.jasypt.ivGenerator=random

通过临时环境变量指定时，把该参数一起放入 JAVA_TOOL_OPTIONS 或 JDK_JAVA_OPTIONS：

JAVA_TOOL_OPTIONS="-Dkey.encrypt.type=jasypt -Dkey.encrypt.jasypt.password=<密码> -Dkey.encrypt.jasypt.algorithm=<加密算法> -Dkey.encrypt.jasypt.ivGenerator=random" ./bin/launcher run

一致性要求

加密时使用的 -a、-p 必须与应用启动时生效的 key.encrypt.jasypt.algorithm、key.encrypt.jasypt.password 完全一致，否则应用启动后无法解密配置值。不要直接设置 KEY_ENCRYPT_TYPE 这类普通环境变量；KeyEncrypt 需要的是 JVM system property。

加密算法支持情况

以下算法在当前文档环境的 JDK 上进行过实测：

java version "25" 2025-09-16 LTS
Java(TM) SE Runtime Environment (build 25+37-LTS-3491)

实测方式为检查 JCE 是否能通过 Cipher 和 SecretKeyFactory 获取对应算法实现。当前 JDK 25 下 17 种算法均由 SunJCE 提供支持。

可选兼容算法

如果运行环境不支持 AES 256 位算法，可以选择 AES 128 位算法。当前 JDK 25 实测支持。

序号	算法	当前 JDK 25 支持情况	说明
8	`PBEWithHmacSHA1AndAES_128`	支持	AES 128 位，SHA1 HMAC。
9	`PBEWithHmacSHA224AndAES_128`	支持	AES 128 位，SHA224 HMAC。
10	`PBEWithHmacSHA256AndAES_128`	支持	AES 128 位，SHA256 HMAC。
11	`PBEWithHmacSHA384AndAES_128`	支持	AES 128 位，SHA384 HMAC。
12	`PBEWithHmacSHA512AndAES_128`	支持	AES 128 位，SHA512 HMAC。

旧算法

以下算法 JDK 25 仍支持，但属于 DES、3DES、RC2、RC4 等旧算法体系。仅建议用于兼容历史配置，新配置不建议优先选择。

序号	算法	当前 JDK 25 支持情况	说明
1	`PBEWithMD5AndDES`	支持	旧算法，兼容性较好，安全强度较低。
2	`PBEWithMD5AndTripleDES`	支持	旧算法，基于 3DES。
3	`PBEWithSHA1AndDESede`	支持	旧算法，基于 DESede/3DES。
4	`PBEWithSHA1AndRC2_40`	支持	旧算法，RC2 40 位。
5	`PBEWithSHA1AndRC2_128`	支持	旧算法，RC2 128 位。
6	`PBEWithSHA1AndRC4_40`	支持	旧算法，RC4 40 位。
7	`PBEWithSHA1AndRC4_128`	支持	旧算法，RC4 128 位。

配置流程

选择加密算法，建议优先使用 PBEWithHmacSHA256AndAES_256。
选择加密密码，并妥善保存；同一套密文需要使用同一个密码解密。
使用 key-encrypt-jasypt-generator.jar 生成敏感值密文。
使用 ENC(密文) 格式将生成的密文写入应用配置文件，例如 jdbc.password=ENC(<生成的密文>)。
在应用 JVM 启动参数中配置 key.encrypt.type、key.encrypt.jasypt.password、key.encrypt.jasypt.algorithm。
重启应用，并确认应用可以正常读取加密配置。

注意事项

加密密码不要写入普通配置文件，建议通过 JVM 启动参数、环境变量或部署平台的密钥管理能力注入。
同一集群内使用同一份加密配置时，各节点的 key.encrypt.jasypt.password 和 key.encrypt.jasypt.algorithm 必须一致。
更换加密算法或密码后，需要重新生成所有相关密文，并同步更新应用启动参数。
生产环境不要在共享终端或 CI 日志中直接暴露 -p 和 -v 的明文内容。
不同 JDK 版本和安全策略可能影响算法可用性，部署前建议在目标运行环境上执行一次加密命令验证算法是否可用。

序号	算法	当前 JDK 25 支持情况	说明
13	`PBEWithHmacSHA1AndAES_256`	支持	AES 256 位，SHA1 HMAC。
14	`PBEWithHmacSHA224AndAES_256`	支持	AES 256 位，SHA224 HMAC。
15	`PBEWithHmacSHA256AndAES_256`	支持	AES 256 位，SHA256 HMAC，推荐优先使用。
16	`PBEWithHmacSHA384AndAES_256`	支持	AES 256 位，SHA384 HMAC。
17	`PBEWithHmacSHA512AndAES_256`	支持	AES 256 位，SHA512 HMAC。