Eet Envelope 支持华为云KMS

1. 简介

EET（easy-encryption-tool）的 envelope 命令支持使用华为云密钥管理服务（KMS，密码安全中心 DEW）进行信封加密。通过 --kms-backend huaweicloud 可调用华为云 KMS 的 CreateDatakey 和 DecryptDatakey 接口，实现 DEK 的云端生成与解密。

适用场景：

使用华为云 CMK 托管数据密钥
与华为云生态集成（OBS、ECS 等）
合规审计、密钥轮换等需求

相关文档：

2. 华为云 KMS 特殊之处（重要）

与其他云厂商（AWS、腾讯云、阿里云）相比，华为云 KMS 有以下特殊要求，配置时需特别注意：

项目	华为云	AWS / 腾讯云 / 阿里云
project_id	必填，且必须与密钥所在区域一致	不需要
区域与项目	每个区域有独立的 project_id，不能混用	区域与凭据相对独立
凭据来源	AK/SK + project_id 三者缺一不可	通常只需 AK/SK
KeyId 格式	UUID（如 `c89cc78f-424e-40a1-bd37-0d8a809dfb79`）	各云格式不同
enc_dek 存储	信封内存储 key_id + cipher_text + datakey_length（JSON）	各云格式不同

2.1 project_id 必须与区域匹配

华为云采用「项目」模型，每个区域对应一个 project_id。例如：

密钥创建在 华东-上海一（cn-east-3）→ 必须使用 cn-east-3 对应的 project_id
若使用其他区域（如 cn-north-4）的 project_id，会报错：Incorrect IAM authentication information: get token error（401）

如何获取正确的 project_id：

登录华为云控制台
右上角头像 → 我的凭证
左侧 API 凭证 → 下方 项目列表
找到与密钥所在区域一致的项目（如「华东·上海一」对应 cn-east-3）
复制该行的 项目ID（32 位十六进制字符串）

3. 前置条件

3.1 安装 KMS 扩展

1
pip install easy_encryption_tool[kms]

该扩展会安装 huaweicloudsdkkms 及其依赖。

3.2 创建 CMK

在华为云 KMS 控制台创建主密钥（CMK），类型选择「对称」。创建后获得 KeyId，格式示例：c89cc78f-424e-40a1-bd37-0d8a809dfb79。

3.3 获取 AK/SK 和 project_id

在我的凭证 - 访问密钥创建 Access Key 和 Secret Key。同时在项目列表中确认密钥所在区域对应的 project_id。

4. 凭据配置

EET 支持两种凭据来源，按优先级依次尝试：

方式	说明
环境变量	`HUAWEICLOUD_SDK_AK`、`HUAWEICLOUD_SDK_SK`、`HUAWEICLOUD_SDK_PROJECT_ID`
配置文件	`~/.huaweicloud/credentials` 或 `~/.config/huaweicloud/credentials`

4.1 环境变量（推荐）

1
2
3
export HUAWEICLOUD_SDK_AK="your_access_key"
export HUAWEICLOUD_SDK_SK="your_secret_key"
export HUAWEICLOUD_SDK_PROJECT_ID="965d36c2c97c469xxxxxxxxxxxxxxxx"   # 必须与 --kms-region 对应

4.2 配置文件

创建 ~/.huaweicloud/credentials，格式为 JSON：

1
2
3
4
5
{
    "ak": "your_access_key",
    "sk": "your_secret_key",
    "project_id": "965d36c2c97c469xxxxxxxxxxxxxxxx"
}

同时支持 access_key / secret_key、access_key_id / secret_access_key 等别名。

4.3 命令行覆盖 project_id

若使用多区域，可通过 --kms-project-id 覆盖：

1
2
3
eet envelope encrypt --mode kms --kms-backend huaweicloud \
  --kms-key-id xxx --kms-region cn-east-3 \
  --kms-project-id "另一个区域的project_id" -i "data"

5. 参数说明

参数	加密	解密	说明
`--kms-backend`	必选	必选	固定为 `huaweicloud`
`--kms-region`	必选	必选	地域，如 `cn-east-3`（华东-上海一）、`cn-north-4`（华北-北京四）
`--kms-key-id`	必选	可选	加密时指定 CMK KeyId；解密时信封内已含 key_id
`--kms-project-id`	可选	可选	覆盖 project_id（未设置时从环境变量或配置文件读取）
`--kms-endpoint`	可选	可选	自定义 endpoint（专有云等）

5.1 常用地域与 project 对应关系

地域代码	说明	备注
cn-east-3	华东-上海一	常用
cn-east-2	华东-上海二
cn-north-4	华北-北京四
cn-south-1	华南-广州

注意：--kms-region 填地域代码，project_id 需在控制台「项目列表」中按区域查找，二者必须匹配。

6. 命令行加解密（详细示例）

6.1 加密

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# 加密：明文 → 信封（JSON 输出）
eet envelope encrypt --mode kms --kms-backend huaweicloud \
  --kms-key-id c89cc78f-424e-40a1-bd37-0d8a809dfb79 \
  --kms-region cn-east-3 \
  -i '1234567890 你好密码学人 CipherHUB'

# 仅输出 base64 信封（便于管道或存储）
eet envelope encrypt --mode kms --kms-backend huaweicloud \
  --kms-key-id c89cc78f-424e-40a1-bd37-0d8a809dfb79 \
  --kms-region cn-east-3 \
  -i '1234567890 你好密码学人 CipherHUB' --raw

成功输出示例（JSON）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "metadata": {
    "operation": "encrypt",
    "algorithm": "envelope",
    "parameters": {
      "symmetric_algo": "aes-256-gcm",
      "wrap_key_type": "kms"
    }
  },
  "result": {
    "envelope": "RUVUAQECBnYyLjMuOSQ...（base64 信封）"
  },
  "runtime": {
    "kms_calls": [
      {
        "step": "generate_data_key",
        "api": "GenerateDataKey",
        "status": "success"
      }
    ]
  }
}

6.2 解密

1
2
3
4
# 解密：信封 → 明文（key_id 已存储在信封内，无需再传）
eet envelope decrypt --mode kms --kms-backend huaweicloud \
  --kms-region cn-east-3 \
  -i 'RUVUAQECBnYyLjMuOSQ5MGE4YzlmMi1kMjUxLTRkMDctYTJiMi01N2Y5ODNhMTI3YjMAKOWvhueggeWtpuS6uiBDaXBoZXJIVUIg6buY6K6kIEFBRCDmlbDmja6t8C9L5fne7MDkxp8BsHsia2V5X2lkIjoiYzg5Y2M3OGYtNDI0ZS00MGExLWJkMzctMGQ4YTgwOWRmYjc5IiwiY2lwaGVyX3RleHQiOiIwNTAwNzAwMDk5MzQ0NGQ5YTU0NzNmZTc3YmJkZWUwNzg1NmYxYzM2ZTVmOWMwZWY2MzM4NDRlN2VkMmYzOTg5MGE3M2ExNWRjNTQwN2UzODQzNzcyOTYyNmE0M2YwNDczNGZkN2E2ZTU3NmQyODA5ZjFiMWQxYjkzYmJkNDgzYTZjMDEzMDQwYTI0YWE0OTY2YmE0YWM3ZjYzMzgzOTYzNjMzNzM4NjYyZDM0MzIzNDY1MmQzNDMwNjEzMTJkNjI2NDMzMzcyZDMwNjQzODYxMzgzMDM5NjQ2NjYyMzczOTAwMDAwMDAwMTgxNzE2MTUxNDEzMTIxMTEwMGYwZTBkMGMwYjBhMDkwODA3MDYwNTA0MDMwMjAxNWU3N2MzMDMwZmUxZmNlYTVmZDFiYTA1MWRmNDhlYzIzMjJjYmIyNzkwMTRmMmU1MTQwZDIzN2ZmNjBhMmJlMyIsImRhdGFrZXlfbGVuZ3RoIjoiNDQifQKw+U/Q+43DiuBku8gJ55OD4DPE1cLldnlP4ImJFCckAAAAN9eqbnfGwxl4E5A/F1DZdgelHGl8N/XwXjv5DmKBVTu1kp4Wan2jgmZLx8XkI3gML/bTYhhgTYZVZ55G7Bc8wa46u7ojRkV/uvFqY4yyRn07zkj4lG1eig=='

成功输出示例（JSON）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
{
  "metadata": {
    "operation": "decrypt",
    "algorithm": "envelope"
  },
  "result": {
    "plain": "1234567890 你好密码学人 CipherHUB"
  },
  "runtime": {
    "kms_calls": [
      {
        "step": "decrypt",
        "api": "Decrypt",
        "status": "success"
      }
    ]
  }
}

6.3 管道加解密

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
ENV=$(eet envelope encrypt --mode kms --kms-backend huaweicloud \
  --kms-key-id c89cc78f-424e-40a1-bd37-0d8a809dfb79 \
  --kms-region cn-east-3 -i "hello" --raw)

eet envelope decrypt --mode kms --kms-backend huaweicloud \
  --kms-region cn-east-3 -i "$ENV" --raw

# 或直接管道
eet envelope encrypt --mode kms --kms-backend huaweicloud \
  --kms-key-id c89cc78f-424e-40a1-bd37-0d8a809dfb79 \
  --kms-region cn-east-3 -i "hello" --raw | \
eet envelope decrypt --mode kms --kms-backend huaweicloud \
  --kms-region cn-east-3 -i - --raw

7. 文件加解密

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# 加密：文件 → 信封文件
eet envelope encrypt --mode kms --kms-backend huaweicloud \
  --kms-key-id c89cc78f-424e-40a1-bd37-0d8a809dfb79 \
  --kms-region cn-east-3 \
  -i /path/to/sensitive.db --from-file -o backup.db.env

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

8. 对称算法与 AAD

默认使用 aes-256-gcm，可通过 --symmetric-algo 指定：

1
2
3
4
# 使用 SM4-GCM（需 easy_gmssl）
eet envelope encrypt --mode kms --kms-backend huaweicloud \
  --kms-key-id key-id --kms-region cn-east-3 \
  -i "data" --symmetric-algo sm4-gcm

自定义 AAD 时，加解密需一致：

1
2
3
4
5
6
eet envelope encrypt --mode kms --kms-backend huaweicloud \
  --kms-key-id key-id --kms-region cn-east-3 \
  -i "data" --aad "my-context-001"

eet envelope decrypt --mode kms --kms-backend huaweicloud \
  --kms-region cn-east-3 -i "$ENV" --aad "my-context-001" --raw

9. 技术说明

9.1 enc_dek 格式（华为云特有）

华为云 DecryptDatakey API 要求显式传入 key_id 和 datakey_cipher_length，因此 EET 在信封的 enc_dek 字段中存储 JSON：

1
2
3
4
5
{
  "key_id": "c89cc78f-424e-40a1-bd37-0d8a809dfb79",
  "cipher_text": "0500700093444d9a5473fe77bbdee07856f1c36e5f9c0ef633844e7ed2f39890a73a15dc5407e38437729626a43f04734fd7a6e576d2809f1b1d1b93bbd483a6c013040a24aa4966ba4ac7f63396363738662d3234652d...",
  "datakey_length": "44"
}

用户无需关心此格式，EET 会自动处理。

9.2 超时配置

默认连接/读取超时 5 秒，与其他 KMS 后端一致。

10. 错误排查

错误	可能原因	解决方式
`Incorrect IAM authentication information: get token error` (401)	project_id 与 region 不匹配；或 AK/SK 错误	在控制台「项目列表」确认 cn-east-3 对应的 project_id，确保 `HUAWEICLOUD_SDK_PROJECT_ID` 与该区域一致
`Huawei Cloud KMS requires credentials...`	未配置 AK/SK 或 project_id	设置环境变量或创建 `~/.huaweicloud/credentials`
`Huawei Cloud KMS requires project_id...`	未配置 project_id	设置 `HUAWEICLOUD_SDK_PROJECT_ID` 或使用 `--kms-project-id`
`Huawei Cloud KMS requires huaweicloudsdkkms`	未安装 KMS 扩展	执行 `pip install easy_encryption_tool[kms]`
`Invalid Huawei Cloud KMS envelope: enc_dek format error`	信封损坏或非华为云 KMS 加密	确保使用华为云 KMS 加密的信封，且未篡改
`kms:cmk:createDataKey` / `kms:dek:create` 权限不足	IAM 用户无 KMS 权限	在 IAM 中为对应用户/角色授予 KMS 相关策略

10.1 401 认证失败常见原因

project_id 填错区域：密钥在 cn-east-3，却使用了 cn-north-4 的 project_id
AK/SK 与 project 不匹配：AK/SK 所属账号/项目与 project_id 不一致
AK/SK 已禁用或过期：在控制台检查访问密钥状态

11. 与 AWS / 腾讯云 / 阿里云对比

项目	华为云	阿里云	腾讯云	AWS
backend	`huaweicloud`	`aliyun`	`tencentcloud`	`aws`
project_id	必填，且需与 region 匹配	不需要	不需要	不需要
凭据	AK/SK + project_id	AK/SK	SecretId/SecretKey	AccessKey/SecretKey
凭据路径	`~/.huaweicloud/credentials`	`~/.aliyun/config.json`	`~/.tccli/default.credential`	`~/.aws/credentials`
KeyId 格式	UUID	`key-xxx` 或 ARN	UUID	ARN 或短格式
enc_dek 格式	JSON（含 key_id）	Base64 字符串	`-k-` 分隔字符串	二进制

1. 简介#

2. 华为云 KMS 特殊之处（重要）#

2.1 project_id 必须与区域匹配#

3. 前置条件#

3.1 安装 KMS 扩展#

3.2 创建 CMK#

3.3 获取 AK/SK 和 project_id#

4. 凭据配置#

4.1 环境变量（推荐）#

4.2 配置文件#

4.3 命令行覆盖 project_id#

5. 参数说明#

5.1 常用地域与 project 对应关系#

6. 命令行加解密（详细示例）#

6.1 加密#

6.2 解密#

6.3 管道加解密#

7. 文件加解密#

8. 对称算法与 AAD#

9. 技术说明#

9.1 enc_dek 格式（华为云特有）#

9.2 超时配置#

10. 错误排查#

10.1 401 认证失败常见原因#

11. 与 AWS / 腾讯云 / 阿里云对比#

12. 参考链接#