集成概览-密钥管理服务(KMS)-阿里云帮助中心

密钥管理服务不仅提供可视化操作控制台，还提供OpenAPI在线调试、阿里云SDK、Terraform等调用方式，帮助您更高效地进行开发与部署。

集成流程

版本说明

在线调试2016-01-20版本的API列表，2016-01-20代表的是API版本号而非时间概念，所展示的都是最新的API公开数据，并非自2016-01-20之后就未更新。如何查看API版本，请参见查看API版本。

版本号	说明
2016-01-20	推荐使用

在线调试

为了让开发者能够快速高效地学习和使用云产品OpenAPI，阿里云为用户提供OpenAPI网站。它是一款集OpenAPI智能搜索、文档、在线调试、SDK获取、CodeSample、调用出错诊断、调用统计为一体的产品。您可以在OpenAPI门户中调用阿里云各云产品开放的OpenAPI，查看OpenAPI请求和返回结果。此外，OpenAPI门户会自动生成相应的SDK调用示例，帮助您快速使用阿里云产品。更多信息，请参见什么是OpenAPI。

密钥管理服务支持在阿里云OpenAPI门户进行API调试，在调试之前，您需要提前了解API版本、接入点说明、API参数等信息。您阿里云账号登录OpenAPI网站后，OpenAPI默认使用您的阿里云账号进行在线OpenAPI调试。

调试API入口为：https://next.api.aliyun.com/api/Kms/2016-01-20

登录 OpenAPI 门户后，页面左侧展示 KMS API 列表（如 DescribeRegions），中间区域用于设置接口的输入参数并单击发起调用，右侧面板可查看文档、调用结果、SDK 示例、CLI 示例等信息及返回参数定义。

接入点说明

KMS支持两种网关类型，共享网关和专属网关。您可以通过共享网关执行管控类操作和业务类操作，通过专属网关执行业务类操作。共享网关可通过公网或VPC网络访问，专属网关通过KMS私有网络访问，两种网关的接入点不同。关于两种网关的详细介绍，请参见共享网关和专属网关的差异。

共享网关Endpoint（又称KMS服务Endpoint）

重要

通过共享网关调用密码运算类业务操作，使用前需要开启公网访问开关。具体操作，请参见通过公网访问KMS实例中的密钥。

根据相关资源所在地域，选择对应的服务接入点地址，以获得最低延迟。例如华东1（杭州）的密钥管理服务公网接入地址为kms.cn-hangzhou.aliyuncs.com，VPC接入地址为kms-vpc.cn-hangzhou.aliyuncs.com，更多地址请参见服务接入点。

公网接入地址在全球都可访问。
VPC接入地址只有在阿里云对应的地域内，且是VPC网络类型才可访问。VPC地址的优势：
- 高安全性：VPC服务地址只能在VPC内部访问，提供更高的安全性和隐私性。
- 更快的响应速度：由于VPC服务地址在VPC内部网络中运行，其响应速度通常比公网服务更快，且可以避免公网延迟和带宽限制等问题。
- 更低的成本：VPC服务地址可以使用内部网络通信。

专属网关Endpoint（又称KMS实例Endpoint）

通过KMS私有网络访问，专属网关Endpoint格式为<YOUR_KMS_INSTANCE_ID>.cryptoservice.kms.aliyuncs.com，例如kst-hzz65f176a0ogplgq****.cryptoservice.kms.aliyuncs.com。

说明

请将<YOUR_KMS_INSTANCE_ID>替换为您实际使用的KMS实例ID。
通过专属网关执行业务类操作时，初始化客户端需要增加实例CA证书配置。详细介绍，请参见初始化客户端。

认证方式

使用阿里云SDK通过共享网关和专属网关访问OpenAPI时认证方式相同，支持AK、STS Token、RamRoleArn、ECS实例RAM角色等基于RAM的身份认证方式。详细内容，请参见管理访问凭据、身份、凭据与授权。如何设置访问权限策略，请参见使用RAM进行访问控制。

AccessKey

警告

阿里云账号默认有所有资源的 Administrator 权限且不可修改，为了确保资源安全，建议使用 RAM 用户创建 AccessKey，并根据需求进行最小化授权。

登录RAM 控制台，在页用户面，单击目标 RAM 用户名称。
在认证管理页签下的AccessKey区域，单击创建 AccessKey，并按照指引完成创建。
授予 RAM 用户访问 KMS 的权限。
- 方式一：设置基于身份的策略
  单击 RAM 用户操作列的新增授权，直接绑定 KMS 内置系统权限策略到 RAM 角色。KMS 内置系统权限策略，请参见密钥管理服务系统权限策略参考。
  说明
  同时支持自定义权限策略，具体操作请参见创建自定义权限策略。
- 方式二：设置基于资源的策略
  KMS 支持基于资源的策略，即为单个密钥和凭据设置访问权限，用于控制哪些阿里云账号、RAM 用户、RAM 角色有权限来管理或使用 KMS 密钥、凭据。详细介绍，请参见密钥策略、凭据策略。

ECS RAM角色

ECS RAM 角色是指为 ECS 实例授予的 RAM 角色，该 RAM 角色是一个受信服务为云服务器的普通服务角色。使用实例 RAM 角色可以实现在 ECS 实例内部无需配置 AccessKey 即可获取临时访问凭证（STS Token），从而调用 KMS 的 OpenAPI。

具体操作，请参见实例RAM角色。

登录RAM 控制台，创建可信实体为阿里云服务的 RAM 角色。
- 信任主体类型：选择云服务器。
- 信任主体名称：选择云服务器 ECS。
授予 RAM 角色访问 KMS 的权限。
- 方式一：设置基于身份的策略
  单击 RAM 角色操作列的新增授权，直接绑定 KMS 内置系统权限策略到 RAM 角色。KMS 内置系统权限策略，请参见密钥管理服务系统权限策略参考。
  说明
  同时支持自定义权限策略，具体操作请参见创建自定义权限策略。
- 方式二：设置基于资源的策略
  KMS 支持基于资源的策略，即为单个密钥和凭据设置访问权限，用于控制哪些阿里云账号、RAM 用户、RAM 角色有权限来管理或使用 KMS 密钥、凭据。详细介绍，请参见密钥策略、凭据策略。
登录ECS 管理控制台，将 RAM 角色授予 ECS 实例。

STS Token

通过 STS 服务为 RAM 用户或 RAM 角色颁发一个临时访问凭证（STS Token），可以在限定的有效期内，以符合策略规定的权限访问 KMS，超过有效期后，该凭证自动失效。

登录RAM 控制台，创建 RAM 用户或 RAM 角色。具体操作，请参见创建RAM用户、创建RAM角色。
为 RAM 用户或 RAM 角色授予AliyunSTSAssumeRoleAccess权限。具体操作，请参见管理RAM用户的权限、管理RAM角色的权限。
授予 RAM 用户或 RAM 角色访问 KMS 的权限。
- 方式一：设置基于身份的策略
  单击 RAM 角色或用户操作列的新增授权，直接绑定 KMS 内置系统权限策略。KMS 内置系统权限策略，请参见密钥管理服务系统权限策略参考。
  说明
  同时支持自定义权限策略，具体操作请参见创建自定义权限策略。
- 方式二：设置基于资源的策略
  KMS 支持基于资源的策略，即为单个密钥和凭据设置访问权限，用于控制哪些阿里云账号、RAM 用户、RAM 角色有权限来管理或使用 KMS 密钥、凭据。详细介绍，请参见密钥策略、凭据策略。
使用 RAM 用户或 RAM 角色调用 STS 服务的 AssumeRole 接口获取 STS 临时访问凭证。具体操作，请参见AssumeRole - 获取扮演角色的临时身份凭证。

RamRoleArn

RAM 用户或云产品可以通过扮演角色的方式获取临时权限（STS Token），而不是直接使用长期密钥，降低了密钥泄露的风险。例如，在临时的数据处理任务中，RAM 用户或云产品临时扮演一个具有特定 RamRoleArn 的角色，完成任务后角色权限被收回，减少泄露风险。

创建用户 AK
1. 登录RAM 控制台，在身份管理 > 用户页面，单击目标 RAM 用户名称。
2. 为 RAM 用户分配系统策略 AliyunSTSAssumeRoleAccess或包含权限操作sts:AssumeRole的自定义策略。
3. 在认证管理页签下的AccessKey区域，单击创建 AccessKey，并按照指引完成创建。
创建 RAM 角色并授权：
1. 在身份管理 > 角色页面，单击创建角色具体操作，请参见创建RAM角色。
2. 授予 RAM 角色访问 KMS 的权限。
  - 方式一：设置基于身份的策略
    单击 RAM 角色操作列的新增授权，直接绑定 KMS 内置系统权限策略到 RAM 角色。KMS 内置系统权限策略，请参见密钥管理服务系统权限策略参考。
    说明
    同时支持自定义权限策略，具体操作请参见创建自定义权限策略。
  - 方式二：设置基于资源的策略
    KMS 支持基于资源的策略，即为单个密钥和凭据设置访问权限，用于控制哪些阿里云账号、RAM 用户、RAM 角色有权限来管理或使用 KMS 密钥、凭据。详细介绍，请参见密钥策略、凭据策略。
获取目标 RAM 角色的 RamRoleArn。具体操作，请参见查看RAM角色。
1. 在身份管理 > 角色页面，单击目标角色名称。
2. 进入角色详情页，在ARN区域可获取 RamRoleArn 信息。
  说明
  RamRoleArn 是 RAM 角色的 ARN 信息，即需要扮演的角色 ID。格式为 acs:ram::$accountID:role/$roleName。$accountID 为阿里云账号 ID。$roleName 为 RAM 角色名称。

集成方式

说明

SDK是最易于集成，且支持度最好的OpenAPI调用方式，推荐您选择使用SDK。

阿里云SDK

阿里云为开发者提供了多种编程语言（Java、C#、Go、Python、Node.js/TypeScript、PHP、C++ 等）的SDK。SDK统一封装了签名逻辑、超时机制、重试机制，并提供了接口请求Request对象和接口返回Response对象，易于开发。更多关于阿里云SDK的介绍，请参见阿里云SDK。

阿里云CLI

阿里云CLI（Alibaba Cloud Command Line Interface）是基于OpenAPI建立的通用命令行工具，您可以借助阿里云CLI实现与阿里云产品的交互，在Shell工具中管理您的阿里云产品。用户可以通过CLI直接输入指令来执行特定操作，而无需依赖图形用户界面（GUI）。更多信息，请参见什么是阿里云CLI。如何获取和使用阿里云CLI命令，请参见CLI 指南。

Terraform

Terraform是一种开源工具，用于安全高效地预览，配置和管理云基础架构和资源，通过将模板转化为内部数据后完成OpenAPI调用，支持多种主流云服务商。Terraform自动计算资源差异并生成执行计划，用户可预览变更影响后再执行，避免意外操作导致的资源损坏或服务中断。更多详情，请参见了解阿里云Terraform。快速使用Terraform编排密钥管理服务，请参见Terraform概述。

通过Terraform编排和使用密钥管理服务，仅部分接口支持。支持的部分普通资源和数据资源清单，请参见密钥管理服务Terraform资源和数据源。

自定义封装API调用

原生HTTP调用需要您自己实现签名算法，并根据接口入参构建自定义请求，发起HTTP调用。签名算法说明参见签名机制，除了需要传入所需业务参数外还需要拼接公共请求参数，详见公共参数。自定义封装接口示例可参考V3版本请求体&签名机制。

注意事项

KMS仅支持使用HTTPS通道发送请求，仅支持TLS 1.0、1.1、1.2版本，不支持SSL v2和SSL v3。
单个阿里云账号调用不同API的每秒请求数（QPS）不同，详情请参见各API文档的QPS限制。更多信息，请参见流量控制与配额管理。

说明
单个阿里云账号下的所有RAM用户共享该阿里云账号的QPS配额。
如果调用API后报错，您可以根据返回的错误码信息，提示检查传入的请求参数及其取值是否正确。更多信息，请参见公共错误码。
您可以记录下调用返回的RequestID或SDK报错信息，通过阿里云OpenAPI诊断平台进行自助诊断。