Eet信封加密V2版本

1. 简介

信封加密（Envelope Encryption）是一种混合加密方式：使用 RSA 公钥或云 KMS 加密随机生成的对称密钥（DEK），再用该密钥对实际数据进行 AES-256-GCM 等对称加密。适用于大数据加密、密钥托管等场景。

特点：

单一 blob 格式：加密输出为一个 base64 字符串或二进制文件，解密只需私钥/KMS + 信封
用户只需关注：明文/密文、密钥包装方式（RSA/KMS）、对称算法等核心参数
支持大文件：对称加密高效，RSA 仅加密 32 字节 DEK
安全设计：OAEP-SHA256、结构校验、明文绑定，无 Padding Oracle 风险

2. 模式概览

模式	选项	密钥来源	适用场景
local	`--mode local`（默认）	本地 RSA 公钥/私钥	自管密钥、离线环境
kms	`--mode kms`	云 KMS（如 AWS）	密钥托管、合规审计

模式互斥：local 与 kms 不能混用；-f 与 --kms-* 互斥。

3. 命令行加解密 vs 文件加解密

3.1 区别说明

类型	输入	输出	典型用法
命令行加解密	`-i` 为明文/密文字符串或 base64	默认 stdout（JSON 或 `--raw` 纯结果）	短文本、管道、脚本
文件加解密	`-i file --from-file` 为文件路径	必须 `-o file` 指定输出文件	大文件、备份、批量

3.2 命令行加解密

输入：-i 直接跟字符串；或 -i base64 -e 表示 base64 编码的二进制
输出：默认 JSON（含 result.envelope 或 result.plain）；--raw 仅输出主结果
限制：非文件输入默认最大 64 MB（-l 可调）

3.3 文件加解密

输入：-i /path/to/file --from-file
输出：必须使用 -o /path/to/output，否则报错
加密：-o 写入二进制 blob
解密：-o 写入明文文件

4. Local 模式（RSA）

4.1 前置条件

RSA 公钥/私钥：2048、3072 或 4096 位，PEM 格式
生成密钥对：eet rsa generate -f my_key -s 2048

4.2 命令行加解密（local）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# 加密：明文字符串 → 信封（stdout）
eet envelope encrypt -f pub.pem -i "hello"

# 加密：仅输出 base64 信封（便于管道）
eet envelope encrypt -f pub.pem -i "hello" --raw

# 解密：base64 信封 → 明文（stdout）
ENV=$(eet envelope encrypt -f pub.pem -i "hello" --raw)
eet envelope decrypt -f priv.pem -i "$ENV" --raw

# 管道
eet envelope encrypt -f pub.pem -i "hello" --raw | eet envelope decrypt -f priv.pem -i - --raw

eet envelope encrypt -f ./tests/rsa_demo_4096_rsa_public.pem -i 'hello'

0fe473cb6797122cfff927c76ba2aa7c

eet envelope decrypt -f ./tests/rsa_demo_4096_rsa_private_cipher.pem -p 1234567890 -i "RUVUAQEBBnYyLjMuNSQyYTQ3ZGFlYy01Y2FlLTQyM2MtOTcyMS04MjBiNzE2M2FiMzYAKOWvhueggeWtpuS6uiBDaXBoZXJIVUIg6buY6K6kIEFBRCDmlbDmja6i+jCTvh4EzLULC1YCABsT89ridG4ckW3cCK/2C4WyrcIDAcOLFPplRnttEv0C4G+giVyFzCBNrIPtyLEnznxVTrMmIUVUbnNwkT1x6PGl4KaaYJcOCQNrSxsZ8W+UQSIIxLctwO6Tz7AjBFLKkPCLBOawER3CP5lhuu9Y32Zq4XS6T8msbFOP6v9loyragk6Zhrzm4OGPdMxO3ihB652vTnS719pqhK/EyyRHPUbFWusdYQ7yQO3x5F1cP8AVlqMLwHxkbZeh+PPVgbvxOujFojk/SibbG0B9nzWtUqVojT+ysrysPbaz4SxmVuah4TzYazU6a2xlcMnO38cbPoJupH6ekTsV+b4ds7fMRTWAxJgF7MZkRGBFaibmAaBvn3qNa7ZPKcjKeJWnNmYO32+wEfqnYI6z93O7RNO3nAj3tEMh/JeXnW1ZEruVC4VZKzRqJFLyNo1wuFPyQisFD1Qx7QCKzfIqZlOXWgs/Y6VPYNuFiMoAa+YMP/qPZALA8KRcP6PBAYuZSslc1hSSYOjNKzvVr1fV4DN7DsWSaYgh4HnGatf5qmGD3wJbtTuPWpMqs3Q3T2l1rpaIqdDBYS8I9voW70+3nzKay8NEmXXn5LFUN0RwUFhsFBQJtUTZwKwPE6obqVWU7EIki4nTosTGEb8wLzBklYb9RVA7+4GynAe7R3LvS0p/9apLzQWOl4cpq0X5iwQpVdYBgzcuHUBiApXQLciWqEZ7yFgihboAAAAVs1B5TfVApWSAjB7Qc5xndvT5FiSsxFt8agi60qSZHYiWu7QplUv3pfs8kpiBdrzNh6rkjVE="

6721a521e16e004bb281d6b0b1be71c3

4.3 文件加解密（local）

1
2
3
4
5
# 加密：文件 → 信封文件（必须 -o）
eet envelope encrypt -f pub.pem -i data.bin --from-file -o data.env

# 解密：信封文件 → 明文文件
eet envelope decrypt -f priv.pem -i data.env --from-file -o plain.txt

eet envelope encrypt -f ./tests/rsa_demo_4096_rsa_public.pem -i ~/Downloads/\[电影天堂www.dytt8899.com\]F1：狂飙飞车-2025_BD国英双语中英双字.mp4/\[电影天堂www.dytt8899.com\]F1：狂飙飞车-2025_BD国英双语中英双字.mp4 --from-file -o tmp_test

eet envelope decrypt -f ./tests/rsa_demo_4096_rsa_private_cipher.pem -p 1234567890 -i tmp_test --from-file -o tmp_plain

QQ_1771861592489

eet envelope decrypt -f ./tests/rsa_demo_4096_rsa_private_cipher.pem -p 1234567890 -i tmp_test --from-file -o tmp_plain

QQ_1771861795927

4.4 私钥密码（解密时）

1
eet envelope decrypt -f priv.pem -p "your_password" -i "$ENV" --raw

5. KMS 模式（云密钥管理）

5.1 前置条件

安装 KMS 扩展：pip install easy_encryption_tool[kms]
配置云凭据：见 5.2 节

5.2 KMS 凭据配置（AWS）

eet 通过 AWS SDK 标准方式读取凭据，不通过 CLI 传入敏感信息。

方式	说明
环境变量	`AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`；可选 `AWS_DEFAULT_REGION`
配置文件	`~/.aws/credentials`、`~/.aws/config`
IAM Role	EC2/ECS/Lambda 等环境中自动使用实例角色

1
2
3
4
# 环境变量示例
export AWS_ACCESS_KEY_ID="your_access_key"
export AWS_SECRET_ACCESS_KEY="your_secret_key"
export AWS_DEFAULT_REGION="us-east-1"

密钥 ID 格式：arn:aws:kms:region:account:key/key-id 或短格式 key-id、alias/alias-name。

5.3 KMS 参数说明

参数	加密	解密	说明
`--kms-backend`	必选	必选	当前仅 `aws`
`--kms-region`	必选	必选	区域，如 `us-east-1`
`--kms-key-id`	必选	可选	加密时指定 KMS 密钥；解密时信封内已含引用
`--kms-endpoint`	可选	可选	自定义 endpoint（私有化部署）

5.4 命令行加解密（KMS）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# 加密：明文 → 信封（需 key-id、region）
eet envelope encrypt --mode kms --kms-backend aws \
  --kms-key-id arn:aws:kms:us-east-1:123456789:key/xxx \
  --kms-region us-east-1 -i "data"

# 加密：仅输出 base64 信封
eet envelope encrypt --mode kms --kms-backend aws \
  --kms-key-id key-id --kms-region us-east-1 -i "data" --raw

# 解密：信封 → 明文（key-id 可选）
eet envelope decrypt --mode kms --kms-backend aws --kms-region us-east-1 \
  -i "$ENV" --raw

# 管道
eet envelope encrypt --mode kms --kms-backend aws \
  --kms-key-id key-id --kms-region us-east-1 -i "hello" --raw | \
eet envelope decrypt --mode kms --kms-backend aws --kms-region us-east-1 -i - --raw

eet envelope encrypt --mode kms --kms-backend aws --kms-key-id arn:aws:kms:ap-northeast-1:353472442111:key/de1b3cb4-50e8-4186-bc42-e89f14db1397 --kms-region ap-northeast-1 -i 'hello'

QQ_1771847196508

eet envelope decrypt --mode kms --kms-backend aws --kms-region ap-northeast-1 -i 'RUVUAQECBnYyLjMuNSRmMTc0ZWJlNy1hYTc3LTQ5OTEtOWEyMS1jOWYxOTRhOWM1OTcAKOWvhueggeWtpuS6uiBDaXBoZXJIVUIg6buY6K6kIEFBRCDmlbDmja7186Xb+9hlr3dslg4AxQECAQB4DDMsgBVUoNDf3mqxDlZKjgE1xS6BW2WxDRYkSq3sPykBlSc45wFEFGsUB2HiU3rWQQAAAIswgYgGCSqGSIb3DQEHBqB7MHkCAQAwdAYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAwwHT+TE88sfKaZ+uACARCARyHZbFIdfYwTWMEO+uf0QEtkNDlw5RVfpgwrj3rB2prWPGzb+HH8yt9gx7LVDVTMPrzQVfiTRgGIq+94loz+aZNsYrfqOcCVt7CY98yUR+L0Wqtwj0JLakZGf4fY4+r/5bD90MGpFg4AAAAVALDq1NwOGPyam1MGYq2V7vaTyfz/fBIYKVzZD95VX49HYsX7SHXWIQfO96cq3F0Jewcf+KI='

QQ_1771847315363

eet envelope encrypt --mode kms --kms-backend tencentcloud --kms-key-id 7bab23ea-1a0e-11ee-a405-52540078f78b --kms-region ap-guangzhou -i '1234567890 你好密码学人 CipherHUB'

QQ_1771902309908

eet envelope decrypt --mode kms --kms-backend tencentcloud --kms-region ap-guangzhou -i 'RUVUAQECBnYyLjMuNiQ4YzM1M2NmOS1jODczLTRmNDYtOTRmMS01Nzk5NTM2YjI5MGUAKOWvhueggeWtpuS6uiBDaXBoZXJIVUIg6buY6K6kIEFBRCDmlbDmja46Be6lUsk38X5FMw0A0lpCd0hJRmxhck5KZ00rTkdocGRUYjFEVjVlTFhlT3RBQnRnN0FBcnpnZnA2dFZDME1oRkZYVU5WZVVmK2RFV3IrTFcybmVEYnBaS0phbDQ5S3lkRTVnPT0tay1mS1ZQM1dJbEdwZzhtOUxNVzRqRWtRPT0tay0vK2lGbFlkVVB6Q1FaMjk3TDFGdlJQVFJVUktHTmd4endEd05jdUdoc2ZTcG8waEtqek9KRStXMHI0bGRaNzluUjcwaDlWem10bm5udjJVM1NmOGZNeUhxRXBzPUEhSjAHGKZDQ6OGX0F2863JPvGBqvKNPcR7ZXBSG651AAAAN4NpYiYC7wpi1qjFKaMluhTk54wWEhoPQgO/fzmjcNxpdnwrWPLpajkZPu7LNP3DLY1LzXBvouVylwRKuwSTnkYe1t9z5kTBuVcugsUMNDLzHPRwbx284w=='

5.5 文件加解密（KMS）

1
2
3
4
5
6
7
8
# 加密：文件 → 信封文件
eet envelope encrypt --mode kms --kms-backend aws \
  --kms-key-id key-id --kms-region us-east-1 \
  -i /path/to/sensitive.db --from-file -o backup.db.env

# 解密：信封文件 → 明文文件
eet envelope decrypt --mode kms --kms-backend aws --kms-region us-east-1 \
  -i backup.db.env --from-file -o restored.db

eet envelope encrypt --mode kms --kms-backend aws --kms-key-id arn:aws:kms:ap-northeast-1:353472442111:key/de1b3cb4-50e8-4186-bc42-e89f14db1397 --kms-region ap-northeast-1 -i ~/Downloads/\[电影天堂www.dytt8899.com\]F1：狂飙飞车-2025_BD国英双语中英双字.mp4/\[电影天堂www.dytt8899.com\]F1：狂飙飞车-2025_BD国英双语中英双字.mp4 --from-file -o tmp_test --symmetric-algo sm4-gcm

eet envelope decrypt --mode kms --kms-backend aws --kms-region ap-northeast-1 -i tmp_test --from-file -o tmp_plain

QQ_1771860887037

eet envelope decrypt --mode kms --kms-backend aws --kms-region ap-northeast-1 -i tmp_test --from-file -o tmp_plain

QQ_1771861098428

eet envelope decrypt --mode kms --kms-backend aws --kms-region ap-northeast-1 -i tmp_test --from-file -o tmp_plain

eet envelope encrypt --mode kms --kms-backend tencentcloud --kms-key-id 7bab23ea-1a0e-11ee-a405-52540078f78b --kms-region ap-guangzhou -i ~/Downloads/负载超级低.mp4 --from-file -o tmp_test

eet envelope decrypt --mode kms --kms-backend tencentcloud --kms-region ap-guangzhou -i tmp_test --from-file -o tmp_plain

QQ_1771902767924

5.6 自定义 Endpoint（私有化/专有云）

1
2
3
eet envelope encrypt --mode kms --kms-backend aws \
  --kms-key-id key-id --kms-region custom \
  --kms-endpoint https://kms.internal.example.com -i "data"

6. 输入输出对照表

6.1 加密

输入类型	选项	输出	示例
明文字符串	`-i "text"`	stdout（JSON 或 `--raw` base64）	`eet envelope encrypt -f pub.pem -i "hello" --raw`
Base64 二进制	`-i b64 -e`	stdout	`eet envelope encrypt -f pub.pem -i "$B64" -e --raw`
文件	`-i file --from-file`	必须 `-o file`	`eet envelope encrypt -f pub.pem -i data.bin --from-file -o data.env`

6.2 解密

输入类型	选项	输出	示例
Base64 信封	`-i "base64..."`	stdout（JSON 或 `--raw` 明文）	`eet envelope decrypt -f priv.pem -i "$ENV" --raw`
信封文件	`-i file --from-file`	`-o file` 或 stdout	`eet envelope decrypt -f priv.pem -i data.env --from-file -o plain.txt`
管道	`-i -`	stdout	`cat data.env \| eet envelope decrypt -f priv.pem -i - --raw`

7. 可选参数

选项	默认值	说明
`--symmetric-algo`	aes-256-gcm	对称算法：aes-256-gcm、sm4-gcm、chacha20-poly1305
`--aad`	CipherHUB 默认	GCM AAD，加解密需一致
`-l`	64	非文件输入时的最大大小（MB）
`--raw`	-	仅输出主结果（envelope 或 plain）
`--json` / `--pretty-json`	-	JSON 输出格式

1
2
3
# 自定义 AAD（加解密需相同）
eet envelope encrypt -f pub.pem -i "data" --aad "my-context-001"
eet envelope decrypt -f priv.pem -i "$ENV" --aad "my-context-001" --raw

8. 典型场景

8.1 短文本加密（命令行）

1
2
eet envelope encrypt -f recipient_pub.pem -i "机密内容" --raw > message.env
eet envelope decrypt -f recipient_priv.pem -i "$(cat message.env)" --raw

8.2 大文件备份（文件）

1
2
eet envelope encrypt -f backup_key.pem -i /path/to/sensitive.db --from-file -o backup.db.env
eet envelope decrypt -f backup_key.pem -i backup.db.env --from-file -o restored.db

8.3 管道串联

1
2
eet envelope encrypt -f pub.pem -i "pipeline data" --raw | \
  eet envelope decrypt -f priv.pem -i - --raw

8.4 从 JSON 提取 envelope 再解密

1
2
ENV=$(eet envelope encrypt -f pub.pem -i "data" --json | jq -r '.result.envelope')
eet envelope decrypt -f priv.pem -i "$ENV" --raw

9. 输出格式

9.1 加密输出

默认：JSON，含 metadata、result.envelope（base64）、runtime
--raw：仅输出 envelope base64
-o file：写入二进制 blob，不输出到 stdout

9.2 解密输出

默认：JSON，含 metadata、result.plain（base64）、runtime
--raw：仅输出明文
-o file：写入明文文件

10. 错误与注意事项

10.1 解密失败

统一返回：Decryption failed: invalid envelope or wrong key.
不区分具体原因，避免信息泄露。

10.2 常见约束

文件加密：--from-file 时必须指定 -o
互斥：-e 与 --from-file 不能同时使用
模式：local 与 kms 互斥；信封的 wrap_key_type 须与解密 mode 一致
AAD：加解密需使用相同 AAD
密钥规格：local 模式仅支持 RSA 2048/3072/4096

1. 简介#

2. 模式概览#

3. 命令行加解密 vs 文件加解密#

3.1 区别说明#

3.2 命令行加解密#

3.3 文件加解密#

4. Local 模式（RSA）#

4.1 前置条件#

4.2 命令行加解密（local）#

4.3 文件加解密（local）#

4.4 私钥密码（解密时）#

5. KMS 模式（云密钥管理）#

5.1 前置条件#

5.2 KMS 凭据配置（AWS）#

5.3 KMS 参数说明#

5.4 命令行加解密（KMS）#

5.5 文件加解密（KMS）#

5.6 自定义 Endpoint（私有化/专有云）#

6. 输入输出对照表#

6.1 加密#

6.2 解密#

7. 可选参数#

8. 典型场景#

8.1 短文本加密（命令行）#

8.2 大文件备份（文件）#

8.3 管道串联#

8.4 从 JSON 提取 envelope 再解密#

9. 输出格式#

9.1 加密输出#

9.2 解密输出#

10. 错误与注意事项#

10.1 解密失败#

10.2 常见约束#

1. 简介

2. 模式概览

3. 命令行加解密 vs 文件加解密

3.1 区别说明

3.2 命令行加解密

3.3 文件加解密

4. Local 模式（RSA）

4.1 前置条件

4.2 命令行加解密（local）

4.3 文件加解密（local）

4.4 私钥密码（解密时）

5. KMS 模式（云密钥管理）

5.1 前置条件

5.2 KMS 凭据配置（AWS）

5.3 KMS 参数说明

5.4 命令行加解密（KMS）

5.5 文件加解密（KMS）

5.6 自定义 Endpoint（私有化/专有云）

6. 输入输出对照表

6.1 加密

6.2 解密

7. 可选参数

8. 典型场景

8.1 短文本加密（命令行）

8.2 大文件备份（文件）

8.3 管道串联

8.4 从 JSON 提取 envelope 再解密

9. 输出格式

9.1 加密输出

9.2 解密输出

10. 错误与注意事项

10.1 解密失败

10.2 常见约束