加密算法 #

AES 加密算法 #

类型：AES

标准模式 #

不配置 db-compatible-mode 时，AES 使用标准模式。

可配置属性：

名称	数据类型	是否必填	默认值	说明
aes-key-value	String	是	无	AES 标准模式使用的 KEY
digest-algorithm-name	String	是	无	AES KEY 的摘要算法。可配置项：“MD2”, “MD5”, “SHA-1”, “SHA-224”, “SHA-256”, “SHA-384”, “SHA-512”, “SHA-512/224”, “SHA-512/256”, “SHA3-224”, “SHA3-256”, “SHA3-384”, “SHA3-512”
aes-key-bit-length	String	否	`128`	AES KEY 的 bit 长度，可配置为 `128`、`192`、`256`
aes-mode	String	否	未配置	未配置或配置为空字符串时，保持兼容历史默认行为；显式配置时支持 `"ECB"`, `"CBC"`, `"CTR"`, `"CFB"`, `"OFB"`, `"CTS"`, `"GCM"`, `"CCM"`
aes-iv	String	条件必填	空字符串	`GCM` 和 `CCM` 模式必填；`CBC`、`CTR`、`CFB`、`OFB`、`CTS` 中可选；`ECB` 和默认模式不使用
aes-encoder	String	否	`BASE64`	对密文的编码方式，可配置为 `BASE64`、`HEX`

说明：标准模式需要提供 aes-key-value 和 digest-algorithm-name。aes-key-bit-length 可以省略，默认使用 128。

示例：

aes-key-value: test
digest-algorithm-name: SHA-1

当配置如上参数时，初始化加密算法的处理流程如下：

将用户配置的 aes-key-value 参数值使用 String.getBytes(StandardCharsets.UTF_8) 方法转换为字节数组。本示例中会将 test 转换成 1110100011001010111001101110100；
使用 digest-algorithm-name 指定的摘要算法对步骤 1 中的结果进行摘要处理；
由于 AES 算法使用的密钥有长度要求，因此会对步骤 2 中的结果进行截取操作，以生成符合 AES 算法密钥长度的最终密钥。默认情况下，处理结果的长度为 128 位（bit），可以通过 aes-key-bit-length 参数选择配置。

当显式配置 aes-mode 时，AES 还支持以下模式：

模式	说明	`aes-iv` 配置要求	其他差异
默认模式	不配置 `aes-mode` 或配置为空字符串时的历史兼容行为	不使用	等价于历史默认 AES 行为
ECB	电子密码本模式	不使用	显式配置 `aes-mode: ECB` 时，行为与默认模式一致
CBC	密码分组链接模式	可选；若配置，长度需大于等于 16，内部截取前 16 个字符	适用于需要 IV 的传统块模式
CTR	计数器模式	可选；若配置，长度需大于等于 16，内部截取前 16 个字符	适用于流式处理场景
CFB	密码反馈模式	可选；若配置，长度需大于等于 16，内部截取前 16 个字符	适用于反馈式流处理场景
OFB	输出反馈模式	可选；若配置，长度需大于等于 16，内部截取前 16 个字符	适用于反馈式流处理场景
CTS	密文挪用模式	可选；若配置，长度需大于等于 16，内部截取前 16 个字符	适用于非整块长度明文的块模式场景
GCM	AEAD 模式，同时提供加密和认证能力	必填；长度需大于等于 16，内部截取前 16 个字符	内部固定使用 `128 bit` 认证标签长度，建议配合 `aes-key-bit-length: 256` 使用
CCM	AEAD 模式，同时提供加密和认证能力	必填；长度需在 7 到 13 之间	与 GCM 一样具备认证能力，但 nonce 长度要求不同

示例 1：默认模式（兼容历史配置）

aes-key-value: test
digest-algorithm-name: SHA-1

示例 2：显式配置 ECB 模式

aes-key-value: test
digest-algorithm-name: SHA-1
aes-mode: ECB

示例 3：显式配置 GCM 模式

aes-key-value: test
digest-algorithm-name: SHA-256
aes-key-bit-length: 256
aes-mode: GCM
aes-iv: 1234567890123456

示例 4：显式配置 CCM 模式

aes-key-value: test
digest-algorithm-name: SHA-1
aes-mode: CCM
aes-iv: 123456789012

数据库兼容模式 #

配置 db-compatible-mode 时，AES 按兼容数据库的规则处理密钥、模式、填充、IV 和密文编码，不使用 digest-algorithm-name。

通用属性：

名称	数据类型	是否必填	默认值	说明
db-compatible-mode	String	是	无	兼容数据库类型，支持 `MySQL`、`MariaDB`、`Oracle`、`OceanBase_Oracle`
aes-key-value	String	是	无	AES 数据库兼容模式使用的 KEY

MySQL 和 MariaDB 兼容模式属性：

名称	数据类型	是否必填	默认值	说明
aes-key-bit-length	String	否	`128`	AES KEY 的 bit 长度，可配置为 `128`、`192`、`256`
aes-mode	String	否	`ECB`	`MySQL` 支持 `"ECB"`, `"CBC"`, `"CFB"`, `"OFB"`；`MariaDB` 支持 `"ECB"`, `"CBC"`, `"CTR"`
aes-iv	String	否	空字符串	配置后长度需大于等于 16，内部截取前 16 个字符；`CBC`、`CFB`、`OFB`、`CTR` 等模式通常需要与数据库侧 IV 保持一致
aes-encoder	String	否	`BASE64`	对密文的编码方式，可配置为 `BASE64`、`HEX`

Oracle 兼容模式属性：

名称	数据类型	是否必填	默认值	说明
aes-key-bit-length	String	否	`aes-key-value` 的字节长度对应 bit 数	需与 `aes-key-value` 字节长度匹配；`aes-key-value` 长度只能为 16、24 或 32 Bytes
aes-mode	String	否	`CBC`	支持 `"CBC"`, `"CFB"`, `"ECB"`, `"OFB"`；当前实现中 `OFB` 按 `ECB` 初始化执行
aes-padding	String	否	`PKCS5Padding`	支持 `PKCS5Padding`、`PKCS5`、`ZeroPadding`、`ZeroBytePadding`、`ZERO`、`NoPadding`、`NONE`
aes-iv	String	否	非 ECB 模式使用 16 个空字节	非 ECB 模式下如显式配置，长度需大于等于 16，内部截取前 16 个字符；ECB 模式不使用
aes-encoder	String	否	`HEX`	对密文的编码方式，可配置为 `BASE64`、`HEX`

OceanBase_Oracle 兼容模式属性：

名称	数据类型	是否必填	默认值	说明
aes-encoder	String	否	`HEX`	对密文的编码方式，可配置为 `BASE64`、`HEX`

说明：OceanBase_Oracle 兼容模式固定使用 256 bit 密钥长度、CBC 模式、PKCS5Padding 和内部固定 IV。aes-key-value 会按 UTF-8 转为字节数组，长度不足 32 Bytes 时补 0x00，超过 32 Bytes 时截取前 32 Bytes。

兼容 MariaDB 的配置示例如下：

示例 1：

# 必须先指定算法兼容 MariaDB
db-compatible-mode: MariaDB
aes-key-value: test_key

那么上述配置和 MariaDB 里如下使用方式等价：

-- AES_ENCRYPT 加密, 并默认对结果进行 TO_BASE64 处理
SELECT TO_BASE64(AES_ENCRYPT('encrypt me', 'test_key'));
+--------------------------------------------------+
| TO_BASE64(AES_ENCRYPT('encrypt me', 'test_key')) |
+--------------------------------------------------+
| 9BZPKT7PCRCiUz/Vpm86iA==                         |
+--------------------------------------------------+
1 row in set (0.001 sec)

-- 先通过 FROM_BASE64 解码，然后通过 AES_DECRYPT 解密，返回原始明文 encrypt me
SELECT AES_DECRYPT(FROM_BASE64('9BZPKT7PCRCiUz/Vpm86iA=='), 'test_key');
+------------------------------------------------------------------+
| AES_DECRYPT(FROM_BASE64('9BZPKT7PCRCiUz/Vpm86iA=='), 'test_key') |
+------------------------------------------------------------------+
| encrypt me                                                       |
+------------------------------------------------------------------+
1 row in set (0.000 sec)

-- 通过 SQL 查询 MariaDB 的默认模式为 ECB 模式
MariaDB [(none)]> SHOW VARIABLES LIKE 'block_encryption_mode';
+-----------------------+-------------+
| Variable_name         | Value       |
+-----------------------+-------------+
| block_encryption_mode | aes-128-ecb |
+-----------------------+-------------+
1 row in set (0.001 sec)

示例 2：

# 必须先指定算法兼容 MariaDB
db-compatible-mode: MariaDB
aes-key-value: test_key
# 通过 HEX 对加密后密文结果进行编码处理
aes-encoder: HEX
# 可选配置，声明模式为 CBC 模式
aes-mode: CBC
# CBC 模式需要和数据库侧加解密函数传入的 IV 保持一致
aes-iv: 1234567890123456

那么上述配置和 MariaDB 里如下使用方式等价：

-- 通过 SQL 修改 MariaDB 的默认模式为 CBC 模式，和上述算法配置保持一致
MariaDB [(none)]> SET block_encryption_mode='aes-128-cbc';
Query OK, 0 rows affected (0.000 sec)

MariaDB [(none)]> SHOW VARIABLES LIKE 'block_encryption_mode';
+-----------------------+-------------+
| Variable_name         | Value       |
+-----------------------+-------------+
| block_encryption_mode | aes-128-cbc |
+-----------------------+-------------+
1 row in set (0.001 sec)


-- AES_ENCRYPT 加密, 并默认对结果进行 HEX 处理。由于目前处于 CBC 模式，加密参数传入上述配置的 aes-iv: 1234567890123456
MariaDB [(none)]> SELECT HEX(AES_ENCRYPT('encrypt me', 'test_key', '1234567890123456'));
+----------------------------------------------------------------+
| HEX(AES_ENCRYPT('encrypt me', 'test_key', '1234567890123456')) |
+----------------------------------------------------------------+
| A8859EB13BAAF804385F8751F56082B8                               |
+----------------------------------------------------------------+
1 row in set (0.000 sec)


-- 先通过 UNHEX 解码，然后通过 AES_DECRYPT 解密，返回原始明文 encrypt me。由于目前处于 CBC 模式，加密参数传入上述配置的 aes-iv: 1234567890123456
MariaDB [(none)]> SELECT AES_DECRYPT(UNHEX('A8859EB13BAAF804385F8751F56082B8'), 'test_key', '1234567890123456');
+----------------------------------------------------------------------------------------+
| AES_DECRYPT(UNHEX('A8859EB13BAAF804385F8751F56082B8'), 'test_key', '1234567890123456') |
+----------------------------------------------------------------------------------------+
| encrypt me                                                                             |
+----------------------------------------------------------------------------------------+
1 row in set (0.000 sec)

DES 加密算法 #

类型：DES

别名：SphereEx:DES

可配置属性：

名称	数据类型	是否必填	默认值	说明
des-key-value	String	是	无	DES 使用的 KEY。Engine 内部会通过 `digest-algorithm-name` 将该值转换成 64 位 secret key
digest-algorithm-name	String	否	`SHA-256`	DES KEY 的摘要算法，可配置项：“MD2”, “MD5”, “SHA-1”, “SHA-224”, “SHA-256”, “SHA-384”, “SHA-512”, “SHA-512/224”, “SHA-512/256”, “SHA3-224”, “SHA3-256”, “SHA3-384”, “SHA3-512”

说明：digest-algorithm-name 可以省略，默认使用 SHA-256。

示例：

des-key-value: test

当配置如上参数时，初始化加密算法的处理流程如下：

将用户配置的 des-key-value 参数值使用 String.getBytes(StandardCharsets.UTF_8) 方法转换为字节数组。本示例中会将 test 转换成 1110100011001010111001101110100；
使用默认的 SHA-256 摘要算法（可以通过 digest-algorithm-name 参数选择配置）对步骤 1 中的结果进行摘要处理；
由于 DES 算法使用的密钥有长度要求，因此会对步骤 2 中的结果进行截取操作，以生成符合 DES 算法 64 位（bit）密钥长度要求的最终密钥。

DESEDE (3DES) 加密算法 #

类型：DESEDE

别名：SphereEx:DESEDE

可配置属性：

名称	数据类型	是否必填	默认值	说明
desede-key-value	String	是	无	DESEDE 使用的 KEY
desede-key-bit-length	String	否	`192`	DESEDE KEY 的 bit 长度，可配置为 `168`、`192`；当前加解密实现固定按 192 bit 生成密钥，该配置主要用于兼容函数配置与参数校验
digest-algorithm-name	String	否	`SHA-256`	DESEDE KEY 的摘要算法，可配置项：“MD2”, “MD5”, “SHA-1”, “SHA-224”, “SHA-256”, “SHA-384”, “SHA-512”, “SHA-512/224”, “SHA-512/256”, “SHA3-224”, “SHA3-256”, “SHA3-384”, “SHA3-512”

说明：desede-key-bit-length 和 digest-algorithm-name 可以省略，默认分别使用 192 和 SHA-256。

示例：

desede-key-value: test

当配置如上参数时，初始化加密算法的处理流程如下：

将用户配置的 desede-key-value 参数值使用 String.getBytes(StandardCharsets.UTF_8) 方法转换为字节数组。本示例中会将 test 转换成 1110100011001010111001101110100；
使用默认的 SHA-256 摘要算法（可以通过 digest-algorithm-name 参数选择配置）对步骤 1 中的结果进行摘要处理；
由于 DESEDE 算法使用的密钥有长度要求，因此会对步骤 2 中的结果进行截取操作，以生成符合 DESEDE 算法密钥长度的最终密钥。当前加解密实现按 192 位（bit）密钥长度截取。

RC4 加密算法 #

类型：RC4

可配置属性：

名称	数据类型	是否必填	默认值	说明
rc4-key-value	String	是	无	RC4 使用的 KEY。通过 `String.getBytes(StandardCharsets.UTF_8)` 计算后的字节数组长度大于等于 5 并且小于 256
rc4-encoder	String	否	`BASE64`	对密文的编码方式，可配置为 `BASE64`、`HEX`

说明：rc4-encoder 可以省略，默认使用 BASE64。

示例：

rc4-key-value: test-sharding

当配置如上参数时，初始化加密算法的处理流程如下：

将用户配置的 rc4-key-value 参数值使用 String.getBytes(StandardCharsets.UTF_8) 方法转换为字节数组，作为 RC4 算法的密钥使用。

本示例中会将 test-sharding 转换成字节数组 [116, 101, 115, 116, 45, 115, 104, 97, 114, 100, 105, 110, 103]，字节数组长度为 13，在算法允许的长度范围内。

SM2 加密算法 #

类型：SM2

别名：SphereEx:SM2

可配置属性：

名称	数据类型	是否必填	默认值	说明
sm2-public-key-value	String	是	无	SM2 算法使用的公钥，BASE64 格式
sm2-private-key-value	String	是	无	SM2 算法使用的私钥，BASE64 格式，私钥会加密存储

说明：SM2 需要提供 sm2-public-key-value 和 sm2-private-key-value。

示例：

sm2-public-key-value: MFkwEwYHKoZIzj0CAQYIKoEcz1UBgi0DQgAE0oppHTfuiESO0DR+9c5g7iRlrbDHgPVeRQzNsskL4ZSHkYvyms76Zv4He95WySnTuZMo0OaQchhRbmXIkXRuyA==
sm2-private-key-value: MIGTAgEAMBMGByqGSM49AgEGCCqBHM9VAYItBHkwdwIBAQQg7ltTxwCxo5gUftPXTLCfDCKCvl7284CRkc/bk4YyzJagCgYIKoEcz1UBgi2hRANCAATSimkdN+6IRI7QNH71zmDuJGWtsMeA9V5FDM2yyQvhlIeRi/Kazvpm/gd73lbJKdO5kyjQ5pByGFFuZciRdG7I

当配置如上参数时，初始化加密算法的处理流程如下：

将用户配置的 sm2-public-key-value 和 sm2-private-key-value 参数值分别进行 BASE64 解码操作，得到对应的二进制公钥和私钥如下：

公钥：110000010110010011000000010011000001100000011100101010100001100100100011001110001111010000001000000001000001100000100000101010100000010001110011001111010101010000000110000010001011010000001101000010000000000000010011010010100010100110100100011101001101111110111010001000010001001000111011010000001101000111111011110101110011100110000011101110001001000110010110101101101100001100011110000000111101010101111001000101000011001100110110110010110010010000101111100001100101001000011110010001100010111111001010011010110011101111101001100110111111100000011101111011110111100101011011001001001010011101001110111001100100110010100011010000111001101001000001110010000110000101000101101110011001011100100010010001011101000110111011001000；

私钥：1100001000000110010011000000100000000100000000001100000001001100000110000001110010101010000110010010001100111000111101000000100000000100000110000010000010101010000001000111001100111101010101000000011000001000101101000001000111100100110000011101110000001000000001000000010000010000100000111011100101101101010011110001110000000010110001101000111001100000010100011111101101001111010111010011001011000010011111000011000010001010000010101111100101111011110110111100111000000010010001100100011100111111011011100100111000011000110010110011001001011010100000000010100000011000001000001010101000000100011100110011110101010100000001100000100010110110100001010001000000001101000010000000000000010011010010100010100110100100........。

SM4 加密算法 #

类型：SM4

可配置属性：

名称	数据类型	是否必填	默认值	说明
sm4-key	String	是	无	SM4 使用的 KEY，16 Bytes 十六进制字符串
sm4-mode	String	是	无	SM4 使用的 MODE，可配置为 `"ECB"`, `"CBC"`, `"OFB"`, `"CFB"`, `"GCM"`, `"CCM"`
sm4-iv	String	条件必填	空字节数组	CBC、OFB、CFB、GCM、CCM 模式必填，十六进制字符串；ECB 模式不使用。CCM 模式长度为 8 Bytes，其他需要 IV 的模式长度为 16 Bytes
sm4-padding	String	是	无	SM4 使用的 PADDING，可配置为 `PKCS5Padding`、`PKCS7Padding`、`NoPadding`；ECB 和 CBC 模式不支持 `NoPadding`，GCM 模式必须使用 `NoPadding`
sm4-encoder	String	否	`HEX`	SM4 编码方式，可配置为 `HEX`、`BASE64`

说明：SM4 需要提供 sm4-key、sm4-mode 和 sm4-padding；需要 IV 的模式还要提供 sm4-iv。sm4-encoder 可以省略，默认使用 HEX。

示例：

# 1.ECB 模式配置示例如下：
sm4-key: 4D744E003D713D054E7E407C350E447E
sm4-mode: ECB
sm4-padding: PKCS5Padding
sm4-encoder: BASE64

# 2.CBC 模式配置示例如下：
sm4-key: f201326119911788cFd30575b81059ac
sm4-iv: e166c3391294E69cc4c620f594fe00d7
sm4-mode: CBC
sm4-padding: PKCS7Padding
sm4-encoder: BASE64

# 3.OFB 模式配置示例如下：
sm4-key: f201326119911788cFd30575b81059ac
sm4-iv: e166c3391294E69cc4c620f594fe00d7
sm4-mode: OFB
sm4-padding: PKCS7Padding
sm4-encoder: BASE64

# 4.CFB 模式配置示例如下：
sm4-key: f201326119911788cFd30575b81059ac
sm4-iv: e166c3391294E69cc4c620f594fe00d7
sm4-mode: CFB
sm4-padding: PKCS7Padding
sm4-encoder: BASE64

# 5.GCM 模式配置示例如下：
sm4-key: f201326119911788cFd30575b81059ac
sm4-iv: e166c3391294E69cc4c620f594fe00d7
sm4-mode: GCM
sm4-padding: NoPadding
sm4-encoder: BASE64

# 6.CCM 模式配置示例如下：
sm4-key: f201326119911788cFd30575b81059ac
sm4-iv: 3132333435363738
sm4-mode: CCM
sm4-padding: NoPadding
sm4-encoder: BASE64

假设用户使用上面的 ECB 配置示例时，初始化加密算法的处理流程如下：

将用户配置的 sm4-key 参数值使用 Hex.decodeHex(key) 方法将用户输入的 16 进制字符串转换为字节数组。本示例中会将 4D744E003D713D054E7E407C350E447E 转换成 1001101011101000100111000000000001111010111000100111101000001010100111001111110010000000111110000110101000011100100010001111110；当然，sm4-iv 参数会做类似处理。

RSA 加密算法 #

类型：RSA

别名：SphereEx:RSA

可配置属性：

名称	数据类型	是否必填	默认值	说明
rsa-public-key-value	String	是	无	RSA 算法使用的公钥，BASE64 格式
rsa-private-key-value	String	是	无	RSA 算法使用的私钥，BASE64 格式，私钥会加密存储

说明：RSA 需要提供 rsa-public-key-value 和 rsa-private-key-value。

示例：

rsa-public-key-value: MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnkOZVTuURVurYRbFIjtWwSEcCyJ3vwlvlwUEAFsbp0Ub0toFAlkPZ+lSI1xyOw0u0bs/kxItk6kRkOUJcPf9nXCrLHEpxoeN9QBhU86k5c/M2g2C5iIyiJXTYz0R0ddYJWIuz7jXimnQP7uHoLR8PUAT9DMhcG3lK5cT4LDiiqAvuxhVJzlNIDPFJ5U0/XdpJ5oKzJYVal/10pYT0Nt5prx3tFl0uwTgw+NhRWx7IssNfwiqKaD8Cq9/lwb0gtXNxmL8KDCG/8TNj+bfJQD+9y0lQXIenUx+JYCXc32NA9Pb7Js8SHyAvmpkreu4XYzMk4so+OCb1SIxBhbIM1tvuQIDAQAB
rsa-private-key-value: MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCeQ5lVO5RFW6thFsUiO1bBIRwLIne/CW+XBQQAWxunRRvS2gUCWQ9n6VIjXHI7DS7Ruz+TEi2TqRGQ5Qlw9/2dcKsscSnGh431AGFTzqTlz8zaDYLmIjKIldNjPRHR11glYi7PuNeKadA/u4egtHw9QBP0MyFwbeUrlxPgsOKKoC+7GFUnOU0gM8UnlTT9d2knmgrMlhVqX/XSlhPQ23mmvHe0WXS7BODD42FFbHsiyw1/CKopoPwKr3+XBvSC1c3GYvwoMIb/xM2P5t8lAP73LSVBch6dTH4lgJdzfY0D09vsmzxIfIC+amSt67hdjMyTiyj44JvVIjEGFsgzW2+5AgMBAAECggEAQgmO54OuwKoZfq+Tnk8IShnYq8S8FpiHWYqcOtHJXih2DasvP+WNihxPS7X9bCp6CMWLJ4EER4Lac40+PUcdKh6jLi4h8lcJott/wQqOv93PaoUMw54tW9S4mcYXs2mZvC+VvNMyDO1OGenUE/h7hstACDt1joYsg93MS4tDW/gHC9eP7hDANZrHs7db26iiP6D8b7GjB+XL6QFgN1q+o6qXmqzvpePGRj4GYuootpDkuxZoDv3GH1gzHoOQnuPMfOm7cE5ov6DrC7OFNgNKDqn5pvo215RL8yBfJ4a6E32AuOzbjtgASX8x7RQQAIHCuEMU75JO+BDw39QqSszsKQKBgQDSnM+/pGztII/IUyFdtSGoJxu2wDoBEMUshJFLSddtvjBH8tqmTGVIl20TbpB4C4sItj2wpMKEzbjs4+wmw+a7h/tR0NHlGEY7pXgNY9QPOjY8kQJeCsVPMUZqqprT2329xm9OUXdgSgaMgvhfaMvRwU+/ufs6UwtyMIwsKFU2rwKBgQDAXswiWVufUQn/RyiY2bb2+lwG8MLhgKv+ntV/CF0+O2d6Pi+HsFPzrEgNYsWCrnYA9wv9McJQi78mBkQYmKQvWfaTMwLOCLsdK/7icPFSWlACRlDOBHc8XXdliQD29dNaqG6BDkwAZ9AgBjKHEMjQMExmgYnR+VFlWX3bp6ZaFwKBgBtZ8ATkVp0I8INEgH3J6yAKTCgUmLPQuLqKUNAlO8vtuhlt6YVVQIYH3Et8vVhJr3mnKSXKj9RtXwmso9t473sFMtcyNj/5Qg229HtQrpZ3qdl9v3/1CCC7tnhdxZOj2pWNsqDKJaWkl2siCx1g369S2od8oKq3ZDIlKd8GMeLTAoGBAJ/+eBNddImV0hXCLi6qbLUPVvjix4LcDLCxk+maoEqBB7gw/kEBU2GH+UlAy/q7dSOqVQtZlj59bBaJAZvfYDaNwTl+JKgNtOo3TD8zJlKTEJZDuzMNncnUBtio0OeVXxq4mWe251ky/nOUE/Qn7ozQjsp2lJTRonQDsVy+G+ozAoGBAISp1Hb/cWfZWpi2P6+UlN4PJhitpNam6se2PDbQheUn782OdWt9uV8HmeRscXPvobb1nD2pY8mKs32GNAzqikoVzfNcH2nxwopcz+z6WsrUzeLtdEFk9ABkDAAtQnlPpfnjLZVt5rc0Is7VZ9kDmiXiUOUN7eiQeaXnGykH7B5/

当配置如上参数时，初始化加密算法的处理流程如下：

将用户配置的 rsa-public-key-value 和 rsa-private-key-value 参数值分别进行 BASE64 解码操作，得到对应的二进制公钥和私钥如下：

公钥：001100001000001000000001001000100011000000001101000001100000100100101010100001100100......，公钥过长，此处仅部分展示；

私钥：00110000100000100000010010111110000000100000000100000000001100000000110100000110000010010010101010000110010010001000011......，私钥过长，此处仅部分展示。

FPE 加密算法 #

类型：FPE

别名：SphereEx:FPE

可配置属性：

名称	数据类型	是否必填	默认值	说明
fpe-mode	String	否	`FF1`	FPE 模式，支持 `FF1`、`FF3-1`
fpe-key-value	String	是	无	FPE 算法使用的 KEY。`fpe-cipher` 配置为 `AES` 时，KEY 长度可为 16、24 或 32 Bytes；配置为 `SM4` 时，KEY 长度必须为 16 Bytes
fpe-alphabet	String	是	无	FPE 算法使用的字典表，至少包含 2 个不重复字符；明文和密文字符必须全部属于该字典表
fpe-cipher	String	否	`AES`	FPE 内部使用的分组密码类型，支持 `AES`、`SM4`
fpe-tweak	String	否	`FF1` 为空字节数组；`FF3-1` 为 7 个 `0x00` 字节	FPE tweak。`FF3-1` 配置时长度必须为 7 Bytes

说明：FPE 需要提供 fpe-key-value 和 fpe-alphabet。FPE 密文保持明文的字符集和字符长度；二进制存储时，密文字节长度按 明文字符数 * fpe-alphabet 中字符的最大 UTF-8 字节数 计算。

示例：

fpe-key-value: 1234567890abcdef
fpe-alphabet: 0123456789

当配置如上参数时，初始化加密算法的处理流程如下：

将用户配置的 fpe-key-value 参数值使用 String.getBytes(StandardCharsets.UTF_8) 方法转换为字节数组。本示例中会将 1234567890abcdef 转换成 110001001100100011001100110100001101010011011000110111001110000011100100110000011000010110001001100011011001000110010101100110。

输入约束：

明文和密文字符必须全部属于 fpe-alphabet。
最小输入长度由 fpe-alphabet 的字符集大小决定，需要满足 radix^length >= 1000000。数字字典 0123456789 的最小输入长度为 6。
FF3-1 模式限制最大输入长度，计算公式为 2 * floor(log(2^96) / log(radix))。数字字典 0123456789 的最大输入长度为 56。

模糊加密算法 #

字符转换模糊查询算法 #

说明：底层存储节点的字符集需要设置为 utf8 或 utf8mb4，collate 设置为 utf8_bin 或 utf8mb4_bin

类型：CHAR_TRANSFORM_LIKE

别名：SphereEx:CHAR_TRANSFORM_LIKE

可配置属性：

名称	数据类型	是否必填	默认值	说明
transform-indexes	String	否	`1,3,5,7,9,11,13,15`	需要转换的字符 bit 位索引，取值范围 0 到 15
unicode-offset	String	否	`19968`	非 ASCII 字符转换后的 Unicode 偏移量，`19968` 对应 `0x4e00`

说明：CHAR_TRANSFORM_LIKE 支持 LIKE 查询，密文字符长度最多为明文的 3 倍。

字符摘要模糊查询算法 #

说明：底层存储节点的字符集需要设置为 utf8 或 utf8mb4，collate 设置为 utf8_bin 或 utf8mb4_bin

类型：CHAR_DIGEST_LIKE

可配置属性：

名称	数据类型	是否必填	默认值	说明
delta	String	否	`1`	字符偏移量
mask	String	否	`3965`	字符掩码
start	String	否	`19968`	非 ASCII 字符转换起始码位，`19968` 对应 `0x4e00`
dict	String	否	内置常用中文字典	字符字典

说明：CHAR_DIGEST_LIKE 支持 LIKE 查询，密文字符长度与明文一致。

脱敏字符摘要算法 #

说明：底层存储节点的字符集需要设置为 utf8 或 utf8mb4

原理：1. 先使用配置的脱敏算法对明文数据进行脱敏；2. 对步骤 1 中脱敏后的数据，使用配置的摘要算法进行摘要

类型：COMPLEX_MASK_LIKE

别名：SphereEx:COMPLEX_MASK_LIKE

可配置属性：

名称	数据类型	是否必填	默认值	说明
like-algorithm-name	String	否	`CHAR_TRANSFORM_LIKE`	like 加密算法名称
mask-algorithm-name	String	否	`KEEP_FIRST_N_LAST_M`	脱敏算法名称

说明：其他配置属性，参考具体使用的 like 加密算法和脱敏算法的配置属性。

示例：

first-n: 3
last-m: 4
replace-char: *

当配置如上参数时，初始化加密算法的处理流程如下：

根据用户配置的 like-algorithm-name 初始化 like 加密算法，此处默认使用 CHAR_TRANSFORM_LIKE 算法。

根据用户配置的 mask-algorithm-name 初始化脱敏算法，此处默认使用 KEEP_FIRST_N_LAST_M 脱敏算法。

其余属性分别为对应的 like 加密算法和脱敏算法中的属性。

排序加密算法 #

OPE 加密算法 #

类型：FASTOPE

别名：SphereEx:FASTOPE

说明：该算法也可以直接当成标准算法使用，无需配置 orderQuery 列，也可以实现排序、比较、范围查询。

可配置属性：

名称	数据类型	是否必填	默认值	说明
alpha-key	String	是	无	OPE 算法使用的随机 double，可以使用 java.security.SecureRandom#nextDouble 生成，取值范围为大于 0.8 且小于 1
factor-e-key	String	是	无	OPE 算法使用的随机 double，可以使用 java.security.SecureRandom#nextDouble 生成，取值范围为大于 0.012 且小于 1
factor-k-key	String	是	无	OPE 算法使用的随机 long，可以使用 java.security.SecureRandom#nextLong 生成
offset	String	否	未配置	OPE 偏移量，取值为 BigInteger 字符串
plain-text-byte-length	String	否	`8`	配置 `offset` 时使用的明文字节长度
charset-name	String	否	`UTF-8`	OPE 算法处理字符串类型时使用的字符集，例如 DM 数据库默认采用 `GB18030` 字符集，OPE 算法需要配置成 `charset-name: 'GB18030'`
legacy-mode	String	否	`false`	是否使用历史编码模式，可配置为 `true` 或 `false`

示例：

alpha-key: '0.8935217796678353'
factor-e-key: '0.9186430364852792'
factor-k-key: '523211953918290'

当配置如上参数时，初始化加密算法的处理流程如下：

将 alpha-key 和 factor-e-key 参数值转换为 double 类型，将 factor-k-key 转换为 long 类型，后续使用。

查询辅助算法 #

MD5 加密算法 #

类型：MD5

可配置属性：

名称	数据类型	是否必填	默认值	说明
salt	String	否	空字符串	盐值。无长度限制，可以由数字、字母、特殊字符组成。

示例：

salt: 202cb962ac5907

当配置如上参数时，初始化加密算法的处理流程如下：

根据用户配置的 salt（可选）初始化 MD5 算法，后续加密时会拼接明文和 salt，进行摘要操作。

SHA256 加密算法 #

类型：SHA

别名：SphereEx:SHA

示例：

type: SHA

SHA256 算法没有额外的属性配置，初始化加密算法的处理流程如下：

初始化 SHA256 算法，后续加密时会使用 SHA256 算法，对明文进行摘要操作。

SM3 加密算法 #

类型：SM3

可配置属性：

名称	数据类型	是否必填	默认值	说明
sm3-salt	String	否	空字符串	SM3 使用的 SALT（空或 8 Bytes）

说明：sm3-salt 可以省略，默认使用空字符串。

示例：

sm3-salt: test1234

当配置如上参数时，初始化加密算法的处理流程如下：

根据用户配置的 sm3-salt（可选）初始化 SM3 算法，后续加密时会拼接明文和 salt，进行摘要操作。

密钥管理连接器 #

加密算法可以通过 key-manager-connector 引用加密规则中定义的 Key Manager 连接器，让连接器为算法加载密钥类属性。

前文介绍的算法属性表，描述的是算法初始化最终需要拿到的属性；这些属性可以直接写在算法配置中，也可以通过 key-manager-connector 从密钥管理连接器加载，例如密钥、公私钥、IV、padding、encoder 等。

key-manager-connector 的值是 CREATE ENCRYPT KEY MANAGER 中声明的连接器名称。引用的连接器名称需要存在于当前加密规则的 Key Manager 配置中。算法配置和连接器加载结果同时存在同名属性时，连接器加载结果优先。

以下示例演示如何通过 Key Manager 连接器管理 AES 加密密钥，实现密钥与算法配置分离。

步骤 1：定义 Key Manager 全局规则 #

Local 密钥存储仅为展示使用，通过 Key Manager 功能适合对接第三方的 KMS 系统或者第三方的密钥生成接口，对于密钥生成接口，可以将生成的密钥密文存储在 Key Manager 功能中。

ALTER KEY MANAGER RULE (
  DEFAULT_NAMESPACE='default',
  PROVIDER_TYPE='Local',
  STORAGE_TYPE='ZooKeeper',
  PROVIDERS(
    (
      NAME='Local',
      TYPE(
        NAME='Local',
        PROPERTIES(
          'encrypt.encrypt.t_user.user_name.aes-key-value'='123456abc'
        )
      )
    )
  ),
  STORAGES(
    (
      NAME='ZooKeeper',
      TYPE(NAME='ZooKeeper')
    )
  )
);

步骤 2：创建密钥管理连接器 #

创建 Connector，通过 keyMappings 将算法属性 aes-key-value 映射到 Key Manager 中的密钥名称。

CREATE ENCRYPT KEY MANAGER t_user_name_connector (
  TYPE(
    NAME='SPHEREEX_KEY_CONNECTOR',
    PROPERTIES(
      'namespace'='default',
      'keyMappings'='aes-key-value=encrypt.encrypt.t_user.user_name.aes-key-value'
    )
  )
);

其中：

namespace：指定 connector 从哪个密钥命名空间中获取密钥。
keyMappings：指定算法属性名与密钥名称之间的映射关系。左侧 aes-key-value 是 AES 算法需要的参数名，右侧是 Key Manager 中管理的密钥名称。

步骤 3：创建加密规则 #

在加密规则中，AES 算法通过 key-manager-connector 引用连接器获取密钥，同时保留 digest-algorithm-name 等非密钥类属性。

CREATE ENCRYPT RULE t_encrypt (
  COLUMNS (
    (
      NAME=user_name,
      PLAIN=user_name_plain,
      CIPHER=user_name_cipher,
      ENCRYPT_ALGORITHM(
        TYPE(
          NAME='AES',
          PROPERTIES(
            'digest-algorithm-name'='SHA-1',
            'key-manager-connector'='t_user_name_connector'
          )
        )
      )
    )
  )
);

在该模式下，算法配置中不再直接出现明文密钥 aes-key-value，密钥的获取、映射和轮换均由 Key Manager 统一接管。Connector 根据 keyMappings 的定义，从 default 命名空间中查找密钥，并将其填充到 AES 算法的 aes-key-value 属性中。