Infisical KMS 指南
这是一个设置助手类技能，帮助用户使用由 Infisical KMS 管理的密钥执行密码学操作。
该技能的核心特性是：密钥默认不可从平台导出（除非在创建时明确设置为可导出），并且在执行密码学操作时不会存储数据。你发送明文或密文，拿回结果，过程不保留任何内容。
不是什么
这一节说明该技能保护的对象与其他技能的区分：
- 如果用户想要存储一个值并在之后读回，应使用 infisical-api / infisical-setup——那是密钥（secret），不是 KMS 密钥。
- 如果用户想用自己从不持有的密钥加密数据，则使用本技能。
- 如果需要用于 TLS 的 X.509 证书，应使用 infisical-pki。
- 如果需要对软件制品签名并带审计轨迹与审批流程，应使用 infisical-pki 的 Code Signing。
- 如果需要短生命周期的数据库凭据，应使用 infisical-dynamic-secrets。
- 如果需要轮换已有的第三方凭据，应使用 infisical-secret-rotation。
最常见的混淆是 secret 与 key。secret 是 Infisical 存储并在请求时返回的值；KMS 密钥是 Infisical 持有且永不返回的密钥——你把操作交给它执行。如果用户说“我想在 Infisical 里存储一个加密密钥”，需要澄清其含义：是把密钥材料作为 secret 存储，还是让 Infisical 管理密钥并执行加密操作。
代码签名也属于 infisical-pki 而非本技能，尽管它也是一种签名操作。本技能用于对任意载荷签名；PKI Code Signing 用于对构建产物签名。
密钥用途（keyUsage）
每个 KMS 密钥在创建时固定拥有恰好一种 keyUsage：
- encrypt-decrypt：用于保护数据，支持 encrypt、decrypt 操作。
- sign-verify：用于证明真实性，支持 sign、verify 操作。
- generate-verify-mac：用于基于共享密钥的消息完整性，支持 generate-mac、verify-mac 操作。
不能用 encrypt-decrypt 类型的密钥执行签名，也不能用 sign-verify 类型的密钥执行加密。应在选择算法之前，先根据用户的实际需求确定用途。
使用流程
- 判断这确实是密钥操作，而不是 secret 存储。
- 选择 keyUsage。
- 选择算法——具体取值见参考文件。
- 确定是否可导出——这一决定在效果上不可逆，值得慎重回答。
- 确定信任根所在——Infisical 自有的 KMS、外部 AWS/GCP KMS，或 HSM。
- 调用相应操作端点。
参考文件
- references/keys-and-operations.md：密钥创建、所有算法取值、全部 API 端点、encrypt/decrypt/sign/verify/MAC、轮换、导入/导出。
- references/external-kms-and-kmip.md：用 AWS KMS 或 GCP KMS 作为 Infisical 后端、HSM 根密钥、KMIP 服务器、Kubernetes 静态加密、Sigstore cosign。
指导原则
- 一律使用 Base64。明文与密文在传输时双向都使用 base64 编码。忘记这一点是最常见的集成错误。
- 算法取值是字面量，且各子系统之间不一致。KMS 对称算法为小写连字符形式（aes-256-gcm）；KMS 非对称与签名算法为大写下划线形式（ECC_NIST_P256、RSASSA_PSS_SHA_256）；KMS 后量子使用下划线（ML_DSA_65），而 PKI 使用连字符（ML-DSA-65）。不要把取值从 infisical-pki 直接搬过来。
- 加密数据密钥，而非大批量数据。KMS 操作是有大小限制的网络调用。对较大载荷应使用信封加密：在本地生成数据密钥，用它加密载荷，仅用 KMS 包裹该数据密钥。
- 密钥默认不可导出，这正是其意义所在。只有在有明确需求时才设置 isExportable，并明确说明这会削弱保证。
- 轮换不会重新加密已有密文。轮换密钥会为新的操作添加新版本；旧密文仍可用旧版本解密。不要暗示轮换会重新保护已有数据。
- 除显而易见的占位符外，绝不打印密钥材料或明文。