Transit 完整工作流程

启用 Transit 引擎

1
2
3
4
# 步骤 1：启用 Transit 引擎
vault secrets enable transit
# 解释：启用加密即服务功能
# 挂载到 /transit 路径

Clipboard_Screenshot_1766721060

1
2
# 在自定义路径下启用Transit引擎
vault secrets enable -path=cipherhub-keys transit

Clipboard_Screenshot_1766721096

Vault 支持的密钥种类

Vault Create-Key

Vault Transit 引擎支持创建多种密钥类型，主要可分为

● 对称加密

● 非对称签名/加密

● MAC生成

● 企业版高级功能

您可以根据以下摘要快速了解其核心类型与用途：

核心对称加密密钥（用于加解密数据）

● aes256-gcm96：默认类型。采用 AES-256-GCM 算法，支持密钥派生和收敛加密。

● aes128-gcm96：AES-128-GCM 算法，功能同上。

● chacha20-poly1305：采用 ChaCha20-Poly1305 算法，同样支持派生和收敛加密（注：在FIPS 140-3模式下未认证）。

非对称密钥（用于签名或加密）

签名专用：

● ecdsa-p256 / ecdsa-p384 / ecdsa-p521：基于不同椭圆曲线的 ECDSA 签名算法。

● ed25519：EdDSA 签名算法，也支持密钥派生。

加密与签名两用：

● rsa-2048

● rsa-3072

● rsa-4096

不同长度的RSA密钥，同时支持加密、解密、签名和验证。

MAC生成与验证密钥

● hmac：专用于生成和验证HMAC（基于散列的消息认证码）。

企业版功能与实验性算法

● managed_key：用于对接外部管理的密钥（企业版）。

● CBC模式AES：如 aes128-cbc（企业版）。

● CMAC算法：如 aes128-cmac（企业版）。

● 后量子密码实验算法：如 ml-dsa、slh-dsa、hybrid（企业版，实验性，不应用于生产）。

重要提示：

● 创建密钥时若不指定 type，将默认生成 aes256-gcm96 密钥。

● 密钥类型及其关键参数（如 derived）在创建后无法更改，例如：仅需签名选 ecdsa-p256，需加解密选 aes256-gcm96。

● 企业版功能及实验性算法需特别注意其使用限制。

Clipboard_Screenshot_1766721144

Clipboard_Screenshot_1766721162

创建对称密钥

1
2
# 创建密钥
vault write transit/keys/cipherhub_test_aes_key type="aes256-gcm96" convergent_encryption=true derived=true

Clipboard_Screenshot_1766721194

1
2
# 在自定义路径下创建密钥
vault write cipherhub-keys/keys/custom_aes_key_demo type="aes256-gcm96" convergent_encryption=true derived=true

Clipboard_Screenshot_1766721220

创建密钥时即设置自动轮转

1
2
3
4
# 创建自动轮转的密钥，
# 且convergent_encryption=false 设置为 false
# 即每次加密都使用随机的IV
vault write -f transit/keys/cipherhub-aes-key-random-iv type="aes256-gcm96" convergent_encryption=false auto_rotate_period='1h'

Clipboard_Screenshot_1766721255

对称加密

1
2
3
# 加密数据
PLAIN_TEXT="信用卡号: 4111-1111-1111-1111";PLAIN_TEXT_B64=$(echo -n "$PLAIN_TEXT" | base64);CONTEXT_B64=$(echo -n "密码学人CipherHUB" | base64)
vault write -format=json transit/encrypt/cipherhub_test_aes_key plaintext="$PLAIN_TEXT_B64" context="$CONTEXT_B64"

对称解密

使用正确的密文

1
2
# 步骤 4：解密数据
vault write -format=json transit/decrypt/cipherhub_test_aes_key ciphertext="vault:v1:D5TLbgknvIueSV1TglZZUvinOswuOgRj2azpvcDNiWa3gSG+nowonkjmAZIf6OSQkHlKR5bXet+E5BHc9g==" context="$CONTEXT_B64"

Clipboard_Screenshot_1766721321

使用错误的密文

1
vault write -format=json transit/decrypt/cipherhub_test_aes_key ciphertext="vault:v1:l9geaV+zPnqa+nQztboahdz5WHRmeb8EWAPCRQSRKAqAxRdaNYjlBzMXrj6LY6LQKco2uFuKReEkn3RssQ==" context="$CONTEXT_B64"

Clipboard_Screenshot_1766721350

查看对称密钥列表

1
2
# 步骤 5：查看密钥列表
vault list transit/keys

Clipboard_Screenshot_1766721377

Clipboard_Screenshot_1766721390

高级功能：对称密钥轮换与重加密

查看密钥当前版本

1
2
3
4
# 场景：合规要求每90天轮换加密密钥
# 1. 查看当前密钥版本
vault read transit/keys/cipherhub_test_aes_key
# 输出显示当前是版本 1

手动轮转密钥

1
2
# 密钥轮转
vault write -f transit/keys/cipherhub_test_aes_key/rotate

Clipboard_Screenshot_1766721484

密钥轮转后对密文重加密

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
# 轮转后的密钥对密文重加密
OLD_CIPHER="vault:v1:D5TLbgknvIueSV1TglZZUvinOswuOgRj2azpvcDNiWa3gSG+nowonkjmAZIf6OSQkHlKR5bXet+E5BHc9g==";
vault write -format=json transit/rewrap/cipherhub_test_aes_key ciphertext="$OLD_CIPHER" context="$CONTEXT_B64"
# 输出
# {
#   "request_id": "f89f2945-c422-959f-746e-a249c6d05126",
#   "lease_id": "",
#   "lease_duration": 0,
#   "renewable": false,
#   "data": {
#     "ciphertext": "vault:v2:kadeaIGgHDFzpaQzuAQKhOonrFqJP5/nS8PDG/z8/cAlcprSvxERao3bHvPTrN7+IqjdzqLjayxV4U3Dtw==",
#     "key_version": 2
#   },
#   "warnings": null,
#   "mount_type": "transit"
# }

Clipboard_Screenshot_1766721525

设置密钥自动轮转

1
2
# 设置密钥每 2h 自动轮转
vault write cipherhub-keys/keys/custom_aes_key_demo/config auto_rotate_period="2h"

Clipboard_Screenshot_1766721552

指定密钥版本加密

1
2
3
4
5
6
PLAIN_TEXT="信用卡号: 4111-1111-1111-1111"
PLAIN_TEXT_B64=$(echo -n "$PLAIN_TEXT" | base64)
 
vault write -format=json transit/encrypt/cipherhub-aes-key-random-iv plaintext="$PLAIN_TEXT_B64" key_version=3
 
vault write -format=json transit/encrypt/cipherhub-aes-key-random-iv plaintext="$PLAIN_TEXT_B64" key_version=7

停止密钥自动轮转

1
vault write transit/keys/cipherhub-aes-key-random-iv/config auto_rotate_period=0

Clipboard_Screenshot_1766721657

裁剪/禁用某个版本之前的密钥

1
2
3
vault write transit/keys/cipherhub-aes-key-random-iv/config min_encryption_version=4 min_decryption_version=4
 
vault write transit/keys/cipherhub-aes-key-random-iv/trim min_available_version=3

修剪命令 (trim) 的作用是设置密钥环的最小可用版本，此版本之前的所有密钥材料将被永久删除且无法恢复

执行此操作有一个重要的安全限制：

● min_available_version（本例中的 3）必须小于或等于当前配置的 min_decryption_version 和 min_encryption_version

● 这确保了Vault不会意外删除当前或未来需要使用的密钥版本。

● min_encryption_version=4: 规定加密、签名等生成新数据的操作，必须使用版本4及以上的密钥。版本1-3的密钥将无法用于新操作。

● min_decryption_version=4: 规定解密、验签等处理已有数据的操作，只能对由版本4及以上密钥生成的数据进行。任何尝试用版本1-3密钥生成的旧数据（如 vault:v1:… 或 vault:v3:…）解密都会失败。

● 将两者都设为 4，等于彻底“禁用”了版本1-3，使其既不能生成新数据，也无法处理旧数据

Transit 签名与验证

创建签名密钥

1
2
# 1. 创建签名密钥
vault write -f transit/keys/cipherhub-signing-key type="ecdsa-p256"

Clipboard_Screenshot_1766721725

对数据摘要签名

1
2
3
4
5
# 对数据摘要签名
DATA_DIGEST=$(echo -n "重要交易数据" | sha256sum | cut -d' ' -f1)
vault write -format=json transit/sign/cipherhub-signing-key input=$(echo -n $DATA_DIGEST | xxd -r -p | base64) hash_algorithm="sha2-256"
# 输出
# vault:v1:MEUCIQDt2oBPx7liTz9Dshxn2vlbBdV20SWafL7XTdQ3ldrBegIgT78zNvn+G4oq2T4iHtXho4CyzTrZuPB0m+7I2qKjG54=

Clipboard_Screenshot_1766721754

验证数据摘要的签名

1
2
3
4
# 3. 验证签名
SIGNATURE="vault:v1:MEUCIQDt2oBPx7liTz9Dshxn2vlbBdV20SWafL7XTdQ3ldrBegIgT78zNvn+G4oq2T4iHtXho4CyzTrZuPB0m+7I2qKjG54="
vault write -format=json transit/verify/cipherhub-signing-key input=$(echo -n $DATA_DIGEST | xxd -r -p | base64) hash_algorithm="sha2-256" signature="$SIGNATURE"
# 返回 valid: true 表示验证通过

Clipboard_Screenshot_1766721791

对数据原文签名

1
2
3
PLAIN_TEXT="这是一份需要签名的原始合同内容。"
INPUT_B64=$(echo -n "$PLAIN_TEXT" | base64)
vault write -format=json transit/sign/cipherhub-signing-key input="$INPUT_B64" hash_algorithm="sha2-256"

Clipboard_Screenshot_1766721819

验证数据原文签名值

1
2
SIGNATURE="vault:v2:MEYCIQCh3ar0EdIuZVL0Qz2GIS112cyQOrX+zgtyBqHu2tLR0wIhAP5Kcg/CVS9kSFoRgIpDWjQkV6ylAsFOUw8KYGW8UHTZ"
vault write -format=json transit/verify/cipherhub-signing-key input="$INPUT_B64" hash_algorithm="sha2-256" signature="$SIGNATURE"

Clipboard_Screenshot_1766721866

轮转签名密钥

1
2
# 轮转签名密钥
vault write -f transit/keys/cipherhub-signing-key/rotate

Clipboard_Screenshot_1766721915

验证存量签名值

1
2
# 使用轮转后的非对称密钥验证存量的签名值
vault write -format=json transit/verify/cipherhub-signing-key input=$(echo -n $DATA_DIGEST | xxd -r -p | base64) hash_algorithm="sha2-256" signature="$SIGNATURE"

Clipboard_Screenshot_1766721939

Transit 非对称RSA密钥加解密/签名验签

创建非对称 RSA 密钥

1
2
3
# 创建RSA加密密钥（选择rsa-2048、rsa-3072或rsa-4096）
# 注意：密钥类型创建后不可更改，请根据安全需求选择
vault write -f transit/keys/cipherhub-rsa-key type="rsa-4096"

Clipboard_Screenshot_1766721972

使用 RSA 公钥加密

1
2
3
4
5
6
7
8
9
# 准备待加密的明文数据（必须Base64编码）
# 重要：Vault要求加密的明文必须是Base64编码格式
# 使用RSA公钥加密数据
# 使用key_type参数指定RSA加密填充方案，常用方案：
# - rsa-oaep: 推荐方案，抗选择密文攻击(默认)
# - pkcs1v15: 旧标准，兼容性好但安全性较低
PLAIN_TEXT="这是一段需要加密的敏感数据：账号12345，金额￥10000.00"
PLAIN_TEXT_B64=$(echo -n "$PLAIN_TEXT" | base64)
vault write -format=json transit/encrypt/cipherhub-rsa-key plaintext="$PLAIN_TEXT_B64" padding_scheme="oaep"

使用 RSA 私钥解密

1
2
CIPHERTEXT="vault:v1:Dmd3ye77uc3KH/n0XT3Z3o1K5NO9bjaeU2RLiVO/yrLa9KVag4+40NitqaVV6EsIWQBn9+TPhRUPESbxwdhaIkDIgz1AiAVFlo+UBURt6XlnVwr7tAd3gY9YahYH0GlD0gpjEK5AKwV5hpp4ro+TFzEvMMNEnqdQtkKNRcQLJw0OY+RQ5nwXT+ptxdVsql1Rvhn7h0MNWQVgmzrvEtoyGUVwdKeuFjKSCZ09AQX60CxBt0KV7e/1OB3QXivPf9GjER7UviCynXjvOCs77mvTm4FN9+lL/79I0ctvLd+Yj0Kj0v5Gx6jg97Wu1jE74ne0fzMadGwMyBIv8v/vbYpAdl8mqjUTJjs6wHpkeuItTw571dtqxZZTYWVZ9Nk52fj+1EAgDMkl1BqN6yzov7A4Kgn1jaz666tZgbPjUrZXQviKCkGRa08EhjMQYTLuRThrXwAdRN82BbtVdnZl7a2sEoGAAeWhcjJs/ra5EB7l/mS6DFH6kUMbAIZ0Kn41XasuFB8MHHSURD0FfZIUgvZ61PTelr+IYSoTvxUDdQ/7BjVJeIQZQeNUjhD9VCMOdp0sgdFU6/q6x10bTtVRTP5d7uY6kDfpaYkhSaRr+ce4IUbqpZMQYttdhyRw2+Lj1KVhQGIKclusxAHK4OFEOT6BH4CMOC3YNAy7qXu3lkSNT8Q="
vault write -format=json transit/decrypt/cipherhub-rsa-key ciphertext="$CIPHERTEXT" padding_scheme="oaep"

使用 RSA 私钥签名

1
2
3
4
5
# RSA签名
# 可选的填充模式：pss / pkcs1v15
PLAIN_TEXT="这是一段敏感数据：账号12345，金额￥10000.00"
PLAIN_TEXT_B64=$(echo -n "$PLAIN_TEXT" | base64)
vault write -format=json  transit/sign/cipherhub-rsa-key input="$PLAIN_TEXT_B64" hash_algorithm="sha2-256" signature_algorithm="pss"

使用 RSA 公钥验签

1
2
SIGNATURE="vault:v1:3uLenWnvgH93562ObHk0vn5+xnwUrQvdmacEikDL6zxpYSFgWyFWnVT+uVHMXhE2zbxIJ8dq2YN8vl5AlOTj+CVRCC7/DasSWNHAh8ZQeSmvyclWmBvXK26gXdE7drpStY7FqxsYh/K2y2JbrLHCWpQfEz1yBYOff0Gwq84OS1hQZKfu+EO5RrOwCOGOIT47qXqEqnsJOayxZ+a1MGXIlw37FZ6pS4JLNjFpCYKaoqPvBL0aGQ4cp2RjCh1sweXwdlvlidV+lrZUOWWWW9ruTt+rQG17WDfCOYFTezUl9tO9vW8do2ROPkFgZvJ5nkqhFTh2rf6IAyK+xplIcAFrKNGEXpGOD/5tkFtVUvRH1Shutyb7Hb1Cm6SH4ofS4LaSg3dTHFHKzegOvWnQjq6Z8JbeyUMclpSCzfbV1aQ86Xbmdpc0j1m1zpR/YOWIJq20U9WXKlepI1aFBA3SGN2xRQfCqFTSN978XKr8J6DYRgw8p+UVK1TFAmX3463Rh+tjaNwi1l71AaSBaE2AOC0fGuYp43AlBIvh72JDVvhsIcBes5fJKlqHc+JjghiRxW048LAvrBZ1y6/KZYOFAE9yNuft4rscRGCXXjad9aNvBwI8JJ9Gs8JL4VVmwn4D5PrAsEy3Tiy1DNy+Jx6lP7hH2kBIQZxd0QVkLSKepxbenkU="
vault write transit/verify/cipherhub-rsa-key input="$PLAIN_TEXT_B64" hash_algorithm="sha2-256" signature_algorithm="pss" signature="$SIGNATURE"

轮转 RSA 密钥

1
2
# 轮转RSA密钥
vault write -f transit/keys/cipherhub-rsa-key/rotate

Transit HMAC 密钥

创建 HMAC 密钥

1
2
# 创建HMAC密钥
vault write -f transit/keys/cipherhub-hmac-key type="hmac" key_size=32

计算 HMAC 校验值

1
2
3
4
# 准备数据并生成HMAC（这部分命令与之前相同，不受影响）
PLAIN_TEXT="这是一段需要验证完整性的重要消息"
INPUT_B64=$(echo -n "$PLAIN_TEXT" | base64)
vault write -format=json transit/hmac/cipherhub-hmac-key input="$INPUT_B64" algorithm="sha2-256"

Clipboard_Screenshot_1766722086

验证 HMAC 校验值

1
2
3
4
5
# 验证HMAC校验值
PLAIN_TEXT="这是一段需要验证完整性的重要消息"
INPUT_B64=$(echo -n "$PLAIN_TEXT" | base64)
HMAC_VALUE="vault:v1:kzmvOQ2b/N8FmqCKXKdjtGz2kyyVjHiOy86CHd30y2c="
vault write -format=json transit/verify/cipherhub-hmac-key input="$INPUT_B64" hmac="$HMAC_VALUE"

Clipboard_Screenshot_1766722109

手动轮转 HMAC 密钥

1
2
# 手动轮转 hmac 密钥
vault write -f transit/keys/cipherhub-hmac-key/rotate

Transit 引擎核心范式：路径结构与操作类型

Vault Transit 引擎管理密钥的操作具有高度一致的范式。

理解其核心的路径结构和操作分类，是掌握所有密钥操作的关键。

所有Transit操作都遵循一个通用路径模板：

1
<挂载点>/<操作类型>/<密钥名称>[?特定后缀]

例如，如果您的Transit引擎挂载在默认的 transit/ 下，操作一把名为 my_key 的密钥，其范式如下：

操作类型	路径范式	关键动作
管理密钥	transit/keys/<密钥名>	create, read, update, list, delete
使用密钥	transit/<动作>/<密钥名>	encrypt, decrypt, sign, verify, hmac
轮转密钥	transit/keys/<密钥名>/rotate	rotate (立即轮转)
配置密钥	transit/keys/<密钥名>/config	update (如设置自动轮转)

通用命令格式

基于上述路径，大部分操作的命令格式是通用的：

1. 创建/更新密钥：

1
2
3
vault write transit/keys/<密钥名> [参数]
# 示例：创建HMAC密钥
vault write transit/keys/hmac_key type="hmac" key_size=256

2. 读取密钥信息/配置：

1
2
3
vault read transit/keys/<密钥名>
# 或查看配置
vault read transit/keys/<密钥名>/config

3. 使用密钥执行操作（最常用范式）：

1
2
3
4
5
vault write transit/<动作>/<密钥名> [输入参数]
# 示例：加密数据
vault write transit/encrypt/my_rsa_key \
    plaintext="<Base64数据>" \
    key_type="rsa-oaep"

4. 列出与轮转：

1
2
3
4
# 列出所有密钥
vault list transit/keys
# 手动轮转密钥
vault write -f transit/keys/<密钥名>/rotate

注意事项

● Base64编码：向Vault传输数据（如plaintext, input）时，必须先进行Base64编码。

● 版本管理：使用密钥时，可通过 key_version 参数指定版本（如 key_version=2）。解密/验证旧数据时，Vault会自动定位正确的版本。

Transit 完整工作流程#

启用 Transit 引擎#

Vault 支持的密钥种类#

核心对称加密密钥（用于加解密数据）#

非对称密钥（用于签名或加密）#

MAC生成与验证密钥#

企业版功能与实验性算法#

创建对称密钥#

创建密钥时即设置自动轮转#

对称加密#

对称解密#

使用正确的密文#

使用错误的密文#

查看对称密钥列表#

高级功能：对称密钥轮换与重加密#

查看密钥当前版本#

手动轮转密钥#

密钥轮转后对密文重加密#

设置密钥自动轮转#

指定密钥版本加密#

停止密钥自动轮转#

裁剪/禁用某个版本之前的密钥#

Transit 签名与验证#

创建签名密钥#

对数据摘要签名#

验证数据摘要的签名#

对数据原文签名#

验证数据原文签名值#

轮转签名密钥#

验证存量签名值#

Transit 非对称RSA密钥加解密/签名验签#

创建非对称 RSA 密钥#

使用 RSA 公钥加密#

使用 RSA 私钥解密#

使用 RSA 私钥签名#

使用 RSA 公钥验签#

轮转 RSA 密钥#

Transit HMAC 密钥#

创建 HMAC 密钥#

计算 HMAC 校验值#

验证 HMAC 校验值#

手动轮转 HMAC 密钥#

Transit 引擎核心范式：路径结构与操作类型#

通用命令格式#

注意事项#