概述

EET 的功能可归纳为三部分：

类别说明
贴近实际应用envelope 与 structured：信封加密、结构化配置叶子加密，均支持本地模式与云 KMS 模式，让用户一键实现配置文件加密与敏感数据信封加密。
密码学基础原子能力AES/SM4/ZUC 对称加解密，RSA/ECC/SM2 非对称加解密与签名验签，Hash、HMAC 等。
常用工具能力大小端转换、时间戳转换、字符串编码转换、安全随机串、证书解析、Shell 补全等。

安装与入口：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 基础安装
pip install easy-encryption-tool

# 国密（SM2/SM3/SM4/ZUC）
pip install easy-encryption-tool[gmssl]

# 云 KMS 信封加密
pip install easy-encryption-tool[kms]

# 全量
pip install easy-encryption-tool[gmssl,kms]

调用方式：eet 或 easy_encryption_tool。

一、贴近实际应用：envelope 与 structured

这两类能力直接面向「配置与敏感数据保护」，是 EET 中最接近实际业务场景的部分；二者都支持本地模式（Local）和云 KMS 模式，便于在自管密钥与托管密钥之间统一体验。

1.1 信封加密（envelope）

作用：用 RSA 公钥或云 KMS 加密随机生成的对称密钥（DEK），再用 DEK 对数据进行对称加密；输出为单一 blob（base64 或二进制文件），解密时只需私钥/KMS + 信封即可还原。

典型场景：短文本加密、大文件备份、密钥托管、合规审计。

模式概览

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

Local 模式（RSA）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 生成 RSA 密钥对
eet rsa generate -f envelope_key -s 2048 -r

# 加密（明文 → base64 信封）
eet envelope encrypt -f envelope_key_public.pem -i "机密内容"

# 解密
eet envelope decrypt -f envelope_key_private.pem -i "$ENV"

# 文件加解密
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

KMS 模式（云密钥管理）

需安装 easy-encryption-tool[kms]，并配置对应云凭据（环境变量或配置文件）。

支持的 KMS 后端：aws、tencentcloud、aliyun、huaweicloud、googlecloud、hashicorpvault、azure。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# 加密（以 AWS 为例）
eet envelope encrypt --mode kms --kms-backend aws \
  --kms-key-id <key-id> --kms-region us-east-1 -i "data"

# 解密（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 /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

可选参数

  • 对称算法：--symmetric-algo 可选 aes-256-gcm（默认）、sm4-gcm、chacha20-poly1305
  • AAD：--aad 自定义 GCM AAD，加密时写入信封，解密自动读取。

1.2 结构化加密（structured）

作用：对 JSON / YAML / INI 等结构化配置文件做叶子节点级加密，仅敏感字段被替换为密文 token，结构保留、diff 友好；密钥管理复用 envelope 的 DEK 包裹（RSA local 或云 KMS），并支持文件级 MAC 完整性校验。

典型场景：配置文件中的密码、API Key、证书等敏感项加密存储，CI/CD 或 Git 中安全存放配置。

模式与密钥（与 envelope 一致）

  • local：RSA 公钥/私钥
  • kms：与 envelope 相同的 --kms-backend、--kms-key-id、--kms-region 等

基本用法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 加密（local）
eet structured encrypt -i config.json -o config.enc.json -f pub.pem

# 解密（local）
eet structured decrypt -i config.enc.json -o config.json -f priv.pem

# 原地加密/解密（原子写回，与 -o 互斥）
eet structured encrypt -i config.yaml --in-place -f pub.pem
eet structured decrypt -i config.enc.yaml --in-place -f priv.pem

# KMS 模式
eet structured encrypt -i config.json -o config.enc.json --mode kms \
  --kms-backend aws --kms-key-id <id> --kms-region us-east-1
eet structured decrypt -i config.enc.json -o config.json --mode kms \
  --kms-backend aws --kms-region us-east-1

加密范围策略

通过 key 路径或后缀控制「哪些叶子加密」：

选项说明
--encrypted-regex仅匹配该正则的路径加密
--unencrypted-regex匹配该正则的路径不加密
--encrypted-suffix仅 key 以该后缀结尾的加密（如 _secret、_password）
--unencrypted-suffix以该后缀结尾的不加密
--mac-only-encryptedMAC 仅覆盖被加密的叶子（默认 MAC 覆盖全部叶子）

同类策略互斥（encrypted-* 与 unencrypted-* 各选其一）。

文件格式与限制

  • 输入格式：--input-type auto|json|yaml|ini，auto 按扩展名推断
  • 文件大小：加密默认最大 64MB，解密默认 128MB，可用 --max-file-size 调整
  • 叶子密文：加密后为 ENC[EET_AEAD,data:...,iv:...,tag:...,type:...,v:1] 形式，支持类型包括 str、int、float、bool、bytes、time 等；null 默认不加密

设计细节见 EET_STRUCTURED_ENCRYPTION_V1_DESIGN.md。

二、密码学基础原子能力

提供可直接复用的加解密、签名验签、摘要与 MAC 能力，便于脚本、测试或与 CipherHUB 等系统对齐。

2.1 对称加密

算法命令模式/说明
AESeet aesAES-256-CBC、AES-256-GCM；key 32 字节，IV 16/Nonce 12
SM4eet sm4SM4-CBC、SM4-GCM；需 easy_gmssl
ZUCeet zuc国密流密码，密文长度=明文长度；key/iv 各 16 字节；需 easy_gmssl

通用参数：-A encrypt|decrypt、-i 输入、-e 表示输入为 base64、-f 表示输入为文件（此时需 -o 指定输出）、-r 随机生成 key/iv、-k/-v 指定 key/iv。

1
2
3
4

# 示例
eet aes -m gcm -A encrypt -i "hello" -r
eet sm4 -m cbc -A encrypt -i ./config.json -f -o ./config.json.enc
eet zuc -A encrypt -i "stream data" -r

2.2 非对称加密与签名

算法命令能力
RSAeet rsagenerate、encrypt、decrypt、sign、verify；支持 2048/3072/4096 位；OAEP/PKCS1v15 加密，PSS/PKCS1v15 签名
ECCeet eccgenerate、ecdh、sign、verify；曲线：secp256r1/384r1/521r1、secp256k1、Ed25519、X25519
SM2eet sm2generate、encrypt、decrypt、sign、verify；需 easy_gmssl；密文格式 C1C3C2/C1C2C3、ASN1/裸字节；签名格式 RS_ASN1/RS
1
2
3
4
5

# 示例
eet rsa generate -f my_rsa -s 2048 -r
eet rsa encrypt -e pem -f my_rsa_public.pem -i "secret message"
eet ecc ecdh -k alice_private.pem -b bob_public.pem
eet sm2 sign -f my_sm2_private.pem -i "message" -p "password"

2.3 哈希与 HMAC

类型命令算法
Hasheet hashSHA256、SHA384、SHA512、SM3（国密，需 easy_gmssl）
HMACeet hmacSHA224/256/384/512、SHA3-224/256/384/512、SM3

支持 -i 文本、-e base64、-f 文件输入。

1
2
3

eet hash -i "hello" -a sha256
eet hash -i ./file.bin -f -a sm3
eet hmac -i "data" -k "secret" -a sha256

三、常用工具能力

面向日常开发与运维的辅助命令，与加解密、编码、时间、字节序等强相关。

3.1 字符串编码转换（convert）

UTF-8 与 Base64、Hex 互转；解码时自动判断输出为 UTF-8 或 Hex/Base64。

1
2
3
4

eet convert utf8-to-base64 -i "hello"
eet convert utf8-to-hex -i "hello"
eet convert base64-decode -i "aGVsbG8="
eet convert hex-decode -i "68656c6c6f"

3.2 时间戳转换（ts）

秒级时间戳与带时区时间字符串互转；默认时区为北京时间（Asia/Shanghai）。

1
2
3
4

eet ts to-datetime -i 1708502400
eet ts to-datetime -i 1708502400 -z America/New_York
eet ts to-ts -i "2024-02-21T12:00:00+08:00"
eet ts list-timezones

3.3 整数与大小端（int-to-bytes）

整数与大端/小端十六进制互转，便于协议或二进制格式处理。

1
2
3
4

eet int-to-bytes to-hex -i 1234567890
eet int-to-bytes to-hex -i 1234567890 -w 4
eet int-to-bytes from-hex -i "00000000499602d2" -e big
eet int-to-bytes from-hex -i "d202964900000000" -e little

3.4 其他

能力命令说明
安全随机串eet random-strCSPRNG 生成指定长度随机字符串；-l 长度，-o 写文件
X.509 证书解析eet cert-parse解析 PEM/DER、国密 SM2 证书（-g）
Shell 补全eet install-completion`–shell zsh
版本与能力eet version / eet --version版本号、运行环境、可选能力（如 KMS 支持）

四、输出格式与规范

  • 默认：彩色 Pretty JSON，含 metadata、result、runtime
  • --json：单行 JSON，便于管道与 jq
  • --raw：仅输出主结果（如 cipher、plain、digest、envelope），便于复制与管道

错误与提示统一通过结构化输出或 messages 字段呈现，敏感信息（密钥、私钥路径、密码）不写入输出。

五、特性小结表

类别内容
应用层envelope（本地/KMS）、structured（JSON/YAML/INI 叶子加密，本地/KMS）
对称加密AES-256-CBC/GCM、SM4-CBC/GCM、ZUC 流密码
非对称RSA、ECC（含 Ed25519/X25519）、SM2
国密SM2、SM3、SM4、ZUC（需 easy_gmssl）
哈希与 MACSHA256/384/512、SHA3、SM3；HMAC
云 KMSAWS、腾讯云、阿里云、华为云、Google Cloud、HashiCorp Vault、Azure（需 [kms]）
工具convert、ts、int-to-bytes、random-str、cert-parse、install-completion