ovotech/mantle

Mantle

镜像概述和主要用途

Mantle是一个Go语言编写的工具，旨在简化字节数组的加密与解密过程。它采用256位AES（高级加密标准）密钥结合Galois/计数器模式（GCM），并集成云KMS服务（目前仅支持Google KMS），通过信封加密（Envelope Encryption）实现多层密钥管理，为敏感数据提供安全、高效的加密解决方案。

核心功能和特性

• 强加密算法：使用256位AES-GCM算法，提供高安全性的数据加密
• 信封加密：采用数据加密密钥（DEK）和KMS加密密钥（KEK）的多层密钥架构
• 云KMS集成：支持Google KMS服务，利用云服务管理加密密钥
• 自动化密钥生成：每次加密自动生成256位DEK和96位nonce（随机数）
• 源文件安全处理：默认零填充并删除源文件（加密时的明文文件或解密时的密文文件）
• 灵活的密文格式：支持自动换行（每40字符）或单行模式，适应不同存储需求

使用场景和适用范围

• 敏感数据加密：适用于需要加密存储的敏感配置、凭证或数据文件
• 自动化环境：可集成到CI/CD流程或自动化脚本中，实现数据加密解密的自动化
• 云环境部署：特别适合在Google Cloud Platform（GCP）环境中使用，与Google KMS无缝集成
• 开发与运维：帮助开发人员和运维人员安全管理应用程序中的敏感信息

详细使用方法和配置说明

安装方式

从二进制发布版安装

可从https://github.com/ovotech/mantle/releases%E4%B8%8B%E8%BD%BDDarwin%E3%80%81Linux%E5%92%8CWindows%E5%B9%B3%E5%8F%B0%E7%9A%84%E4%BA%8C%E8%BF%9B%E5%88%B6%E6%96%87%E4%BB%B6%E3%80%82

测试安装：

bash
$ mantle -h

从源码安装

bash
$ git clone git@github.com:ovotech/mantle.git
$ cd mantle
$ go build
$ ./mantle -h

作为Go依赖安装

bash
$ go get -u github.com/ovotech/mantle

前置准备（GCP环境）

创建KMS密钥环和密钥

需在Google KMS中创建密钥环和密钥（如不存在），以允许工具进行加密/解密操作。

授权配置

• 本地环境：若已安装gcloud并拥有Cloud KMS CryptoKey Encrypter和/或Cloud KMS CryptoKey Decrypter角色，工具可直接使用当前用户权限。
• 服务账号（自动化环境）：
  1. 服务账号需具备Cloud KMS CryptoKey Encrypter和/或Decrypter角色
  2. 将服务账号的key.json文件放置到运行工具的主机上
  3. 设置环境变量：export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

获取密钥资源ID

使用gcloud命令获取KMS密钥的资源ID：

bash
# 列出指定位置的密钥环
$ gcloud kms keyrings list --location <location>

# 列出指定密钥环中的密钥
$ gcloud kms keys list --location <location> --keyring <keyring_name>

上述命令返回的NAME值即为密钥的资源ID，格式如下：

projects/<project_name>/locations/<location>/keyRings/<keyring_name>/cryptoKeys/<key_name>

也可通过Google Cloud Console获取：进入密钥环页面，点击密钥右侧菜单，选择"复制资源ID"。

基本使用示例

加密文件

bash
# 创建明文文件
$ echo "helloworld" > plain.txt

# 执行加密命令（-n指定密钥资源ID）
$ mantle encrypt -n <key_name>

# 加密成功后，明文文件plain.txt将被删除，生成密文文件cipher.txt
$ cat cipher.txt

解密文件

bash
# 执行解密命令
$ mantle decrypt -n <key_name>

# 解密成功后，生成明文文件plain.txt
$ cat plain.txt

Docker部署示例

假设使用ovotech/mantle镜像，可通过以下方式运行：

基本加密命令

bash
docker run -it --rm \
  -v $(pwd):/app \
  -e GOOGLE_APPLICATION_CREDENTIALS=/app/key.json \
  ovotech/mantle encrypt -n <key_name> -f /app/plain.txt

基本解密命令（保留密文文件）

bash
docker run -it --rm \
  -v $(pwd):/app \
  -e GOOGLE_APPLICATION_CREDENTIALS=/app/key.json \
  ovotech/mantle decrypt -n <key_name> -f /app/cipher.txt -r

配置参数说明

工作原理

1. 生成密钥和随机数：执行encrypt命令时，自动生成256位AES数据加密密钥（DEK）和96位nonce
2. 加密数据：使用DEK和nonce加密明文数据
3. 加密DEK：通过云KMS服务加密DEK（信封加密）
4. 生成密文：将加密数据、nonce和加密后的DEK拼接为最终密文

解密过程为上述步骤的逆操作：解析密文得到加密数据、nonce和加密DEK，通过KMS解密DEK，再使用DEK和nonce解密密文数据。

密文结构

密文结构如下：

encryptedData[n]nonce[12]encryptedDEK[113]

• encryptedData：加密后的数据，长度取决于明文长度
• nonce：96位（12字节）随机数
• encryptedDEK：加密后的DEK，长度固定为113字节（Google KMS返回的base64解码后长度）

注意事项

换行符处理

加密时默认每40字符插入换行符，以适应源码存储的行长度限制。可使用-s, --singleLine标志禁用此功能。解密时会自动忽略行尾换行符，无需区分两种模式。

IV（初始向量）生成

Mantle使用Go标准库的***/rand生成IV（即nonce），每次加密生成新的96位（12字节）IV。该库在不同系统上使用安全的随机数生成器（如Linux的getrandom(2)、Windows的CryptGenRandom等）。

源文件处理

默认情况下，加密时会零填充并删除明文文件（plain.txt），解密时会零填充并删除密文文件（cipher.txt）。解密时可使用-r, --retainCipherText标志保留密文文件；加密时无保留明文文件的选项。

示例输出

bash
$ mantle encrypt -n <key_name>

Encrypting...
-----BEGIN (ENCRYPTED DATA + DEK) STRING-----
y+PvJrf0QJKKSp85C0MN6q2v7EhMeorNJG+5FLiN
wV/Wow6eWHFL80x3xl7vIgDVN5CdRAOVpZL2kJV3
coDbctszL5LJHaLL22YVYaJwojETz5Aff4Kss98p
MIRahCJ1D8EFNoBbTAQTUGNJAJGc11YcX3sWpsYB
h3BookBa6KEvnmNFfw8F6M71zpdmByS1p/k8/1Z/
TAX/Dj0wxcm2g/ez7gA0e/vFQXQjJYqSkb0xJuQX
SVaDoXap3HF7NbikcklBPBkDvy408Hogapvh4OF2
vL9tlhGoERUkrWcwXQfcZjk1B3Sjh45UDTHySTs+
m4Eco7MOur6LvfrGKJuX6qJubppxUDv2ZTCeMCrK
d9AjmCqleD/iSthZN1FKjQ3zLowlnsvWIMnaeEC+
h5W8NIjKm4YQCY2yGj3V6AhdBMvujXLX1aYbIHSf
GfIzLhHSKI7vUm0RFN5irblcoC+sBkRf8NAKJAB1
PbjZJT8wZ94zMUnqrUNNCJqzoky5PFiAY0x077co
SHATyRJJAOR2fnkCjptlffrP0/y8Jhs7ogtttzwt
mkJtdbf9ltQw2ak1OJI3h7NC9vLqfDzGQFeO396C
RRt3E3ly9MifB+cFe4Fnowcq0g==
-----END (ENCRYPTED DATA + DEK) STRING-----
Encryption successful, ciphertext available at ./cipher.txt
Wiped 340 bytes from ./plain.txt.

密文为BEGIN和END标记之间的字符串，生成的cipher.txt文件仅包含此密文字符串。

贡献

非常欢迎贡献，如有改进请fork仓库或创建分支并提交PR。