📦 Alibabacloud Kms Secret Manage — 阿里云KMS密钥管理

技能文档

该技能提供阿里云密钥管理服务（KMS）密钥管理的核心功能，支持密钥的CRUD操作。

场景描述

KMS密钥管理服务用于安全存储、管理和访问敏感信息，例如：

• 数据库连接凭证
• API密钥
• OAuth令牌
• 证书私钥
• 其他需要安全存储的敏感数据

架构： 阿里云KMS服务 + 密钥管理（密钥管家）

graph TB
User[应用/用户] --> KMS[KMS密钥管理]
KMS --> Secret[通用密钥]
Secret --> V1[版本1]
Secret --> V2[版本2]
Secret --> VN[版本N]
KMS --> Rotation[轮换密钥]
Rotation --> RDS[RDS托管密钥]
Rotation --> RAM[RAM托管密钥]
Rotation --> ECS[ECS托管密钥]
Rotation --> Redis[Redis托管密钥]
Rotation --> PolarDB[PolarDB托管密钥]

环境配置

依赖项：阿里云CLI。如果出现"command not found"错误，请参阅references/cli-installation-guide.md进行安装。

超时配置

为CLI命令设置适当的超时以避免挂起：

# 设置超时环境变量（秒）
export ALIBABA_CLOUD_CONNECT_TIMEOUT=30
export ALIBABA_CLOUD_READ_TIMEOUT=30

或使用命令行标志：

aliyun kms  --connect-timeout 30 --read-timeout 30 ...

推荐超时值：

• 连接超时：30秒
• 读取超时：30秒

安全规则

- 禁止：读取、打印或显示AK/SK值
- 禁止：要求用户直接在对话中输入AK/SK
- 敏感数据掩码：GetSecretValue返回的密钥值默认被掩码（例如），仅在用户明确要求时明文输出

RAM权限要求

确保执行用户具有以下KMS权限。详细策略请参阅references/ram-policies.md。

最小权限（只读）：

kms:DescribeSecret, kms:ListSecrets, kms:GetSecretValue, kms:ListSecretVersionIds, kms:GetSecretPolicy

完整权限（读写）：

kms:CreateSecret, kms:DeleteSecret, kms:UpdateSecret, kms:DescribeSecret, kms:ListSecrets, kms:GetSecretValue, kms:PutSecretValue, kms:ListSecretVersionIds, kms:UpdateSecretVersionStage, kms:UpdateSecretRotationPolicy, kms:RotateSecret, kms:RestoreSecret, kms:SetSecretPolicy, kms:GetSecretPolicy, kms:ListKmsInstances, kms:ListKeys, kms:CreateKey

核心工作流

1. 创建密钥

创建密钥需要先获取KMS实例ID和加密密钥ID，然后执行创建。

# 步骤1：获取KMS实例ID
aliyun kms ListKmsInstances --PageNumber 1 --PageSize 10 --region  --user-agent AlibabaCloud-Agent-Skills
# → 提取 KmsInstances.KmsInstance[0].KmsInstanceId
# 步骤2：获取加密密钥ID
aliyun kms ListKeys --Filters '[{"Key":"KeySpec","Values":["Aliyun_AES_256"]},{"Key":"DKMSInstanceId","Values":[""]}]' --PageNumber 1 --PageSize 10 --region  --user-agent AlibabaCloud-Agent-Skills
# → 提取 Keys.Key[0].KeyId
# 步骤3：创建密钥（需要DKMSInstanceId和EncryptionKeyId）
aliyun kms CreateSecret --SecretName "" --SecretData "" --VersionId "" --EncryptionKeyId "" --DKMSInstanceId "" --region  --user-agent AlibabaCloud-Agent-Skills

2. 列出密钥

aliyun kms ListSecrets --region  --user-agent AlibabaCloud-Agent-Skills

3. 获取密钥值

安全策略：
- 如果用户未明确请求密钥值：仅提供CLI命令或Python代码脚本。不要执行。
- 如果用户明确请求获取/检索/显示密钥值：先提供命令/脚本，然后在用户确认后执行。

CLI命令：

aliyun kms GetSecretValue --SecretName "" --region  --user-agent AlibabaCloud-Agent-Skills

Python SDK示例：

from alibabacloud_tea_openapi.client import Client as OpenApiClient
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_credentials.client import Client as CredentialClient
from alibabacloud_tea_util import models as util_models
credential = CredentialClient()
config = open_api_models.Config(credential=credential)
config.endpoint = 'kms..aliyuncs.com'
client = OpenApiClient(config)
params = open_api_models.Params(
    action='GetSecretValue',
    version='2016-01-20',
    protocol='HTTPS',
    method='POST',
    auth_type='AK',
    style='RPC',
    pathname='/',
    req_body_type='json',
    body_type='json'
)
body = {'SecretName': ''}
runtime = util_models.RuntimeOptions()
request = open_api_models.OpenApiRequest(body=body)
response = client.call_api(params, request, runtime)
print(response.body)

注意：
- 仅在用户明确确认后执行检索
- 密钥值包含敏感信息，应谨慎处理
- 始终提醒用户在安全环境中执行（私密终端、无屏幕共享、无日志记录）

4. 删除密钥

删除前的预检查（安全要求）：

在强制删除密钥之前，始终验证其是否存在并检查是否仍在使用中：

# 步骤1：描述密钥以验证存在并检查元数据
aliyun kms DescribeSecret --SecretName "" --region  --user-agent AlibabaCloud-Agent-Skills
# → 检查SecretName、CreateTime和其他元数据以确认这是正确的密钥

如果DescribeSecret返回错误（密钥不存在）：

• 停止并告知用户："密钥不存在，无需删除"

如果DescribeSecret成功：

• 审查密钥元数据
• 在继续强制删除之前与用户确认

# 步骤2：强制删除（立即删除，无法恢复）
aliyun kms DeleteSecret --SecretName "" --ForceDeleteWithoutRecovery true --region  --user-agent AlibabaCloud-Agent-Skills

幂等性：如果返回Forbidden.ResourceNotFound错误，表示密钥不存在，视为删除成功并继续后续操作。

5. 更新密钥值

aliyun kms PutSecretValue --SecretName "" --SecretData "" --VersionId "" --region  --user-agent AlibabaCloud-Agent-Skills

6. 描述密钥

aliyun kms DescribeSecret --SecretName "" --region  --user-agent AlibabaCloud-Agent-Skills

7. 列出密钥版本

aliyun kms ListSecretVersionIds --SecretName "" --IncludeDeprecated true --region  --user-agent AlibabaCloud-Agent-Skills

8. 配置轮换策略

aliyun kms UpdateSecretRotationPolicy --SecretName "" --EnableAutomaticRotation true --RotationInterval 7d --region  --user-agent AlibabaCloud-Agent-Skills

9. 恢复已删除的密钥

aliyun kms RestoreSecret --SecretName "" --region  --user-agent AlibabaCloud-Agent-Skills

幂等性*：如果返回Rejected.ResourceInUse错误，表示密钥已恢复或未被删除，视为恢复成功并继续后续操作。

高级功能

有关托管凭证和其他高级功能，请参阅references/managed-credentials.md。

参考链接