共享网关和专属网关、集成KMS、KMS SDK使用流程、KMS API使用流程、自建应用集成KMS-密钥管理服务(KMS)-阿里云帮助中心

KMS 支持通过 SDK 或代理服务 KMS Agent 调用 API，实现密钥管理、密码运算以及凭据值获取等功能，帮助自建应用快速集成 KMS 服务。本文将介绍选择合适网关、鉴权方式和集成方式，以及不同 API 类型的使用方法。

KMS 集成架构概览

自建应用集成 KMS 需要在以下四个维度进行选择：

网关类型：共享网关（公网/VPC）或专属网关（私网）
鉴权方式：RAM 鉴权或应用接入点 AAP 鉴权（不推荐）
集成方式：SDK（阿里云 SDK、凭据 SDK、实例 SDK）或 KMS Agent
API 类型：管控类操作 API、密码运算 API、获取凭据 API

KMS 集成概览图如下所示：

选型指南

根据业务场景，按以下步骤选择合适的网关、鉴权和集成方案：

步骤一：确定网络隔离需求

业务部署在阿里云 VPC 且需要高性能或高安全性：选择 专属网关（私网，数据全链路加密）。
业务部署在非阿里云环境或需要管控操作：选择 共享网关（公网/VPC）。

步骤二：确定 API 能力需求

需要管控操作（创建密钥、凭据等）：必须使用 共享网关 + 阿里云 SDK。
需密码运算：凭据 SDK 或阿里云 SDK（对应网关类型）。
获取凭据：凭据 SDK 或 KMS Agent。
跨语言应用需要简化集成：使用 KMS Agent（仅支持获取凭据）。

接入网关类型

KMS 提供两种访问网关：共享网关和专属网关。

共享网关：为 KMS 服务的全局网络，可通过公网或 VPC 网络访问KMS 服务，同时支持管控类操作和业务操作。
专属网关：为特定 KMS 实例的网络，仅支持私网访问KMS 服务，提供全链路 API 安全保障方案，数据安全性更高，只支持业务类操作。

差异点	共享网关	专属网关
推荐使用场景	业务需要通过 API 操作包括实例、密钥、凭据相关的管控操作，例如创建密钥、创建凭据、创建 KMS 实例等操作。业务部署在非阿里云 VPC 上。非正式环境访问 KMS，例如：内部测试环境。	业务部署在阿里云 VPC。业务类操作例如加解密、获取凭据等操作频繁，对性能要求较高业务数据有较高的安全性要求。
Endpoint	公网、VPC 域名	KMS 私网域名
性能	以加解密性能为例，通过共享网关访问 KMS 时 QPS 为 1000。	以您购买的实例的计算性能规格为准，例如 1000、2000 等。
支持的集成方式	阿里云 SDK、凭据 SDK、KMS Agent。	阿里云 SDK、凭据 SDK、KMS Agent、实例 SDK。
支持的 API	全部 OpenAPI。	OpenAPI-密码运算、OpenAPI-获取凭据值、实例 API（不推荐）。
身份认证和鉴权	RAM 鉴权和 AAP（不推荐）。	RAM 鉴权和 AAP（不推荐）。
CA 证书	无需配置 CA 证书。	需要配置 CA 证书。

集成方式

KMS 提供 SDK 和 KMS Agent 两种集成方式，两者在 API 支持和适用场景上有明显差异。

SDK 和 KMS Agent 对比

维度	SDK（阿里云/凭据/实例）	KMS Agent	集成建议
支持 API	管控类、密码运算、获取凭据	仅获取凭据	需要管控操作：SDK。仅获取凭据：两者均可。
语言支持	Java、Python、Go、C++、PHP、.NET、TypeScript、Swift	任意编程语言（HTTP 接口）	跨语言场景： Agent。
网络部署	直连网关，支持公网/VPC/私网	本地应用访问，HTTP 本地通信	多语言微服务：Agent。直连性能关键： SDK
集成复杂度	语言特定 SDK，签名逻辑内置	简化认证，标准 HTTP 接口，代理管理凭存	快速集成：Agent。完全控制：SDK。

集成流程说明

SDK 集成

KMS SDK 将复杂的签名过程封装在方法内，用户按照接口说明填入必填参数和认证信息即可。KMS SDK 包含阿里云 SDK、凭据 SDK、实例 SDK（不推荐）。

若您结合网关、鉴权、API 的情况选择了合适的 SDK 后，可按照以下流程集成 SDK 以使用 KMS。更多 SDK 集成信息，可参见SDK参考。

SDK 接入流程

SDK 集成遵循以下标准流程：

使用说明

支持密钥和凭据的所有操作（管控类、操作类），其中管控类操作仅支持 SDK 这一种集成方式。
针对不同的语言环境，需要安装对应语言的 SDK。

SDK 类型详细说明

下表汇总三种 SDK 类型在支持 API、网关、鉴权和语言方面的差异，帮助选择合适的 SDK：

SDK 类型	支持的 API	网关及鉴权方式说明	支持的开发语言
凭据 SDK	OpenAPI：获取凭据：GetSecretValue 实例 API（不推荐）：获取凭据：GetSecretValue	共享网关： RAM 鉴权+OpenAPI AAP 鉴权+OpenAPI（不推荐） AAP 鉴权+实例 API（不推荐）专属网关： RAM 鉴权+OpenAPI AAP 鉴权+实例 API（不推荐）	支持 3 种： Java（Java 8 及以上版本） Python Go
阿里云 SDK	OpenAPI：管控类：服务管理、实例管理、密钥管理、凭据管理、标签管理、应用管理业务类：密码运算、获取凭据值	共享网关：RAM 鉴权+OpenAPI 专属网关：RAM 鉴权+OpenAPI	支持 8 种： Java Python Go C++ PHP .NET(C#) TypeScript Swift
实例 SDK（不推荐）	实例 API：密钥接口、凭据接口、生成随机数	共享网关：不支持。专属网关：APP 鉴权+实例 API	支持 5 种： Java（Java 8 及以上版本） Python Go PHP .NET（仅 C#）

KMS Agent 集成

KMS Agent 简化了应用访问 KMS 的身份认证与缓存管理流程，是基于标准化 HTTP 接口提供服务。更多信息，请参见KMS Agent。

使用说明

适用于多语言环境，支持任意编程语言的业务应用调用 KMS Agent
仅支持本地业务应用访问
仅支持获取凭据值，不可管控凭据信息例如修改、删除凭据等操作

KMS Agent 接入流程

开发接入说明

支持的 API

网关类型

鉴权方式

支持的开发语言

OpenAPI：

获取凭据：GetSecretValue

共享网关、专属网关

RAM 鉴权

KMS Agent 是基于标准化 HTTP 接口提供服务，支持任意编程语言的业务应用调用。

KMS API 类型

KMS 提供 OpenAPI 和 KMS 实例 API（不推荐）两大类型的 API，其中按功能区分又分为管控类操作 API、密码运算类 API、获取凭据 API 三大类 API。更多信息可参见API概览、实例 API。

API 类型对比

下表汇总三种 API 类型与集成方式的对应关系，帮助快速定位合适方案：

API 类型	阿里云 SDK	凭据 SDK	实例 SDK	KMS Agent
管控类操作创建、修改、删除密钥和凭据。	支持	不支持	不支持	不支持
密码运算加解密、数字签名等。	支持	不支持	支持	不支持
获取凭据值获取凭据。	支持	支持	支持	支持

管控类操作

管控类操作包括实例、密钥、凭据相关的管控操作，例如创建密钥、创建凭据、创建KMS实例、修改密钥标签等。

管控类操作只能使用阿里云SDK接入，通过访问共享网关Endpoint调用OpenAPI。

密码运算

密码运算操作包括对称加解密、非对称加解密、信封加密、生成数据密钥、数字签名、验证签名等与密码学相关的操作。

密码运算操作可以通过阿里云SDK或者KMS实例SDK接入。

重要

通过共享网关调用密码运算操作API时，需要打开公网访问开关。具体操作，请参见通过公网访问KMS实例中的密钥。

获取凭据值

可以通过凭据SDK、阿里云SDK、实例SDK、KMS Agent访问共享网关或专属网关调用OpenAPI-GetSecretValue或实例API-GetSecretValue（不推荐）获取KMS凭据值。

API接口示例

以下以OpenAPI为例，展示各类型对应接口说明。

管控类

服务管理

API	标题	API概述
DescribeAccountKmsStatus	查询当前阿里云账号的密钥管理服务状态	查询当前阿里云账号的密钥管理服务状态。
OpenKmsService	为当前阿里云账号开通密钥管理服务	为当前阿里云账号开通密钥管理服务。

实例管理

API	标题	API概述
ListKmsInstances	获取实例列表	查询 KMS 实例列表。
ConnectKmsInstance	连接实例并配置网络	启用一个KMS实例。
GetKmsInstance	获取实例	查询一个KMS实例的详情。
UpdateKmsInstanceBindVpc	更新实例分享VPC	更新KMS实例配置的VPC。
ReleaseKmsInstance	释放KMS按量付费实例	释放KMS按量付费实例。
GetDefaultKmsInstance	获取默认KMS实例	获取默认KMS实例。

密钥管理

API	标题	API概述
CreateKey	创建一个主密钥	创建一个主密钥。
ListKeys	查询调用者在调用地域的所有主密钥ID	查询调用者在调用地域的所有主密钥ID。
DescribeKey	返回指定主密钥（CMK）的相关信息	查询用户主密钥（CMK）详情。
UpdateKeyDescription	更新主密钥描述信息	更新主密钥的描述信息。
EnableKey	启用指定的主密钥进行加解密	启用指定的主密钥进行加解密。
DisableKey	禁用指定的主密钥（CMK）进行加解密	禁用指定的主密钥（CMK）进行加解密。
CreateAlias	给主密钥（CMK）创建一个别名	为主密钥（CMK）创建一个别名。
ListAliases	查询当前用户在当前地域的所有别名	查询当前用户在当前地域的所有别名。
ListAliasesByKeyId	查询主密钥（CMK）所有别名	查询与指定主密钥（CMK）对应的所有别名。
DeleteAlias	删除别名	删除别名。
UpdateAlias	更新主密钥（CMK）ID	更新已存在的别名所代表的主密钥（CMK）ID。
GetParametersForImport	获取导入主密钥（CMK）材料的参数	获取导入主密钥材料的参数。
ImportKeyMaterial	导入密钥材料	导入密钥材料。
DeleteKeyMaterial	删除已导入的密钥材料	删除已导入的密钥材料。
ScheduleKeyDeletion	申请删除一个指定的主密钥（CMK)	申请删除一个指定的主密钥（CMK)。
CancelKeyDeletion	撤销密钥删除	撤销密钥删除。
SetDeletionProtection	设置删除保护	为用户主密钥（CMK）开启或关闭删除保护。
UpdateRotationPolicy	更新密钥轮转策略	更新密钥的周期性自动轮转策略。
DescribeKeyVersion	查询指定密钥版本信息	查询指定密钥版本信息。
CreateKeyVersion	为主密钥创建一个新的密钥版本	为用户主密钥（CMK）创建密钥版本。
ListKeyVersions	列出主密钥的所有密钥版本	列出主密钥的所有密钥版本。
SetKeyPolicy	设置密钥策略	为KMS实例中的密钥设置密钥策略。
GetKeyPolicy	查询密钥策略	查询指定密钥的密钥策略。

凭据管理

API	标题	API概述
ListSecrets	查询当前用户在当前地域创建的所有凭据	查询当前用户在当前地域创建的所有凭据。
DeleteSecret	删除凭据对象	删除凭据对象。
CreateSecret	创建凭据	创建凭据并存入凭据的初始版本。
UpdateSecret	更新凭据的元数据	更新凭据的元数据。
UpdateSecretVersionStage	更新凭据的版本状态	更新凭据的版本状态。
UpdateSecretRotationPolicy	更新动态凭据的轮转策略	更新凭据轮转策略。
DescribeSecret	查询凭据的元数据信息	查询凭据的元数据信息。
ListSecretVersionIds	查询凭据的所有版本信息	查询凭据的所有版本信息。
GetRandomPassword	获得一个随机口令字符串	获得一个随机口令字符串。
PutSecretValue	为凭据存入一个新版本的凭据值	为通用凭据存入一个新版本的凭据值。
RestoreSecret	恢复被删除的凭据	恢复被删除的凭据。
RotateSecret	主动轮转动态凭据	立即轮转凭据。
SetSecretPolicy	设置凭据策略	为KMS实例中的凭据钥设置凭据策略。
GetSecretPolicy	查询凭据策略	查询指定凭据的凭据策略。

标签管理

API	标题	API概述
GetKmsInstanceQuotaInfos	获取实例配额信息	获取实例配额信息。
ListResourceTags	获取用户主密钥的标签	获取用户主密钥的标签。
TagResource	为主密钥或凭据设置标签	为主密钥、凭据或证书绑定标签。
UntagResource	删除用户主密钥或凭据的指定标签	为主密钥、凭据或证书解绑标签。

应用管理

API	标题	API概述
CreateNetworkRule	创建网络规则	创建一条网络控制规则，设置允许访问KMS的私网IP或私网的网段。
ListNetworkRules	获取网络规则列表	查询网络控制规则列表。
DescribeNetworkRule	获取网络规则	查询一个网络控制规则的详情。
UpdateNetworkRule	更新网络规则	更新一个网络控制规则。
DeleteNetworkRule	删除网络规则	删除一条网络控制规则。
CreatePolicy	创建访问策略	创建一个权限策略，设置允许应用访问的密钥和凭据。
ListPolicies	获取访问策略列表	查询权限策略列表。
DescribePolicy	获取访问策略	查询一个权限策略的详情。
UpdatePolicy	更新访问策略	更新一个权限策略。
DeletePolicy	删除访问策略	删除一条权限策略。
CreateApplicationAccessPoint	创建应用接入点	创建一个应用接入点。
ListApplicationAccessPoints	获取应用接入点列表	查询应用接入点列表。
DescribeApplicationAccessPoint	获取应用接入点	查询一个应用接入点的详情。
UpdateApplicationAccessPoint	更新应用接入点	更新一个应用接入点信息。
DeleteApplicationAccessPoint	删除应用接入点	删除一个应用接入点。
CreateClientKey	创建应用身份凭证	创建一个应用身份凭证（ClientKey）。
ListClientKeys	获取应用身份凭证列表	查询应用身份凭证（ClientKey）列表。
GetClientKey	获取应用身份凭证	获取一个应用身份凭证（ClientKey）信息。
DeleteClientKey	删除应用身份凭证	删除一个应用身份凭证（ClientKey）。

业务类-密码运算

API列表	描述	共享网关	专属网关
Encrypt	使用对称密钥将明文加密为密文。	支持	支持
GenerateDataKey	生成一个随机的数据密钥，用于本地数据加密。	支持	支持
GenerateDataKeyWithoutPlaintext	生成一个随机的数据密钥，用于本地数据加密，且不返回数据密钥明文。	支持	支持
ExportDataKey	使用传入的公钥加密导出数据密钥。	支持	支持
GenerateAndExportDataKey	随机生成一个数据密钥，通过您指定的KMS密钥和公钥加密后，返回使用KMS密钥加密后的数据密钥密文，以及使用公钥加密后的数据密钥密文。	支持	支持
Decrypt	解密密文。	支持	支持
ReEncrypt	对密文进行转加密。即先将密文解密，然后将解密得到的数据或者数据密钥使用新的主密钥再次进行加密，返回加密结果。	支持	不支持
AsymmetricSign	使用非对称密钥进行签名。	支持	支持
AsymmetricVerify	使用非对称密钥进行验签。	支持	支持
AsymmetricDecrypt	使用非对称密钥进行解密。	支持	支持
AsymmetricEncrypt	使用非对称密钥进行加密。	支持	支持
GetPublicKey	获取非对称密钥的公钥。	支持	支持

业务类-获取凭据值

API列表	描述	共享网关	专属网关
GetSecretValue	获取凭据值。	支持	支持

认证与鉴权

KMS 支持 RAM 鉴权和应用接入点 AAP 鉴权（不推荐），更多信息可参见管理 RAM 访问凭据，应用接入点（AAP）管理。

差异点	RAM 鉴权	AAP 鉴权（不推荐）
功能说明	支持自定义灵活权限策略。支持 RAM 角色、STS Token、ECS RAM 角色、AK 等多种方式。	支持自定义灵活权限策略。需要下载保存认证文件 ClientKey，其中包含应用身份凭证内容（ClientKeyContent）和凭证口令（ClientKeyPassword）。
支持的集成方式	阿里云 SDK、凭据 SDK、KMS Agent。	凭据 SDK、实例 SDK。
支持的 API	全部 OpenAPI。	OpenAPI-获取凭据、实例 API。
支持的网关	专属网关、共享网关	专属网关、共享网关说明针对不同的网关要求提供专属网关和共享网关两种模式，具体操作可参见AAP鉴权（不推荐）。