构造请求_数据加密服务 DEW_API参考_如何调用API_华为云

(1)

API 参考

文档版本 29

发布日期 2021-11-30

(2)

非经本公司书面许可，任何单位和个人不得擅自摘抄、复制本文档内容的部分或全部，并不得以任何形式传播。

商标声明

和其他华为商标均为华为技术有限公司的商标。

本文档提及的其他所有商标或注册商标，由各自的所有人拥有。

注意

您购买的产品、服务或特性等应受华为公司商业合同和条款的约束，本文档中描述的全部或部分产品、服务或特性可能不在您的购买或使用范围之内。除非合同另有约定，华为公司对本文档内容不做任何明示或暗示的声明或保证。

由于产品版本升级或其他原因，本文档内容会不定期进行更新。除非另有约定，本文档仅作为使用指导，本文档中的所有陈述、信息和建议不构成任何明示或暗示的担保。

(3)

1 ^{使用前必读}

1.1 概述

欢迎使用数据加密服务（Data Encryption Workshop，DEW）。数据加密服务是一个综合的云上数据加密服务。它可以提供专属加密、密钥管理、凭据管理、密钥对管理等服务，安全可靠的为用户解决了数据安全、密钥安全、密钥管理复杂等问题。其密钥由硬件安全模块（Hardware Security Module，HSM）保护，并与多个华为云服务集成。您也可以借此服务开发自己的加密应用。

在调用数据加密服务API之前，请确保已经充分了解数据加密服务相关概念，详细信息请参见产品介绍。

1.2 调用说明

数据加密服务提供了REST（Representational State Transfer）风格API，支持您通过 HTTPS请求调用，调用方法请参见如何调用API。

1.3 终端节点

终端节点（Endpoint）即调用API的请求地址，不同服务不同区域的终端节点不同，您可以从地区和终端节点中查询服务的终端节点。

数据加密服务的终端节点如下表所示，请您根据业务需要选择对应区域的终端节点。

表1-1 数据加密服务的终端节点

区域名称区域终端节点（Endpoint）协议类型

华北-北京

四 cn-north-4 kms.cn-

north-4.myhuaweicloud.com HTTPS 华北-北京

一 cn-north-1 kms.cn-

north-1.myhuaweicloud.com HTTPS

(8)

区域名称区域终端节点（Endpoint）协议类型华东-上海

二 cn-east-2 kms.cn-

east-2.myhuaweicloud.com HTTPS 华东-上海

一 cn-east-3 kms.cn-

east-3.myhuaweicloud.com HTTPS 华南-广州 cn-south-1 kms.cn-

south-1.myhuaweicloud.com HTTPS 华南-深圳 cn-south-2 kms.cn-

south-2.myhuaweicloud.com HTTPS 西南-贵阳

一 cn-

southwest- 2

kms.cn-

southwest-2.myhuaweicloud.com HTTPS

中国-香港 ap-

southeast- 1

kms.ap-

southeast-1.myhuaweicloud.com HTTPS

亚太-曼谷 ap-

southeast- 2

kms.ap-

亚太-新加坡

ap-southeast- 3

kms.ap-

南非-约翰

内斯堡 af-south-1 kms.af-

south-1.myhuaweicloud.com HTTPS 拉美-圣地

亚哥 la-south-2 kms.la-

south-2.myhuaweicloud.com HTTPS 拉美-墨西

哥城二 la-north-2 kms.la-

north-2.myhuaweicloud.com HTTPS

1.4 约束与限制

您能创建的密钥的数量与配额有关系，具体请参见服务配额。密钥管理服务对单用户每秒可以请求的API操作数量设置为20，即密钥管理服务的TPS性能指标为20TPS。

1.5 基本概念

● 帐号

用户注册时的帐号，帐号对其所拥有的资源及云服务具有完全的访问权限，可以重置用户密码、分配用户权限等。由于帐号是付费主体，为了确保帐号安全，建议您不要直接使用帐号进行日常管理工作，而是创建用户并使用他们进行日常管理工作。

● 用户

(9)

由帐号在IAM中创建的用户，是云服务的使用人员，具有身份凭证（密码和访问密钥）。

在我的凭证下，您可以查看帐号ID和用户ID。通常在调用API的鉴权过程中，您需要用到帐号、用户和密码等信息。

● 区域（Region）

从地理位置和网络时延维度划分，同一个Region内共享弹性计算、块存储、对象存储、VPC网络、弹性公网IP、镜像等公共服务。Region分为通用Region和专属 Region，通用Region指面向公共租户提供通用云服务的Region；专属Region指只承载同一类业务或只面向特定租户提供业务服务的专用Region。

详情请参见区域和可用区。

● 可用区（AZ，Availability Zone）

一个AZ是一个或多个物理数据中心的集合，有独立的风火水电，AZ内逻辑上再将计算、网络、存储等资源划分成多个集群。一个Region中的多个AZ间通过高速光纤相连，以满足用户跨AZ构建高可用性系统的需求。

● 项目

区域默认对应一个项目，这个项目由系统预置，用来隔离物理区域间的资源（计算资源、存储资源和网络资源），以默认项目为单位进行授权，用户可以访问您帐号中该区域的所有资源。如果您希望进行更加精细的权限控制，可以在区域默认的项目中创建子项目，并在子项目中创建资源，然后以子项目为单位进行授权，使得用户仅能访问特定子项目中资源，使得资源的权限控制更加精确。

图1-1 项目隔离模型

● 企业项目

企业项目是项目的升级版，针对企业不同项目间资源的分组和管理，是逻辑隔离。企业项目中可以包含多个区域的资源，且项目中的资源可以迁入迁出。

关于企业项目ID的获取及企业项目特性的详细信息，请参见企业管理服务用户指南。

1.6 API 版本选择建议

SSH密钥对提供了V3、V2.1和V2两个版本，建议您使用V3版本，能够更好的满足您的需求。

(10)

2 ^{如何调用 API}

2.1 构造请求

本节介绍如何构造REST API的请求，并以调用IAM服务的获取用户Token说明如何调用API，该API获取用户的Token，Token可以用于调用其他API时鉴权。

您还可以通过这个视频教程了解如何构造请求调用API：https://

bbs.huaweicloud.com/videos/102987。

请求 URI

请求URI由如下部分组成。

{URI-scheme} :// {Endpoint} / {resource-path} ? {query-string}

尽管请求URI包含在请求消息头中，但大多数语言或框架都要求您从请求消息中单独传递它，所以在此单独强调。

● URI-scheme：

表示用于传输请求的协议，当前所有API均采用HTTPS协议。

● Endpoint：

指定承载REST服务端点的服务器域名或IP，不同服务不同区域的Endpoint不同，

您可以从地区和终端节点获取。

例如IAM服务在“华北-北京一”区域的Endpoint为“iam.cn- north-1.myhuaweicloud.com”。

● resource-path：

资源路径，也即API访问路径。从具体API的URI模块获取，例如“获取用户 Token”API的resource-path为“/v3/auth/tokens”。

● query-string：

查询参数，是可选部分，并不是每个API都有查询参数。查询参数前面需要带一个

“？”，形式为“参数名=参数取值”，例如“limit=10”，表示查询不超过10条数据。

例如您需要获取IAM在“华北-北京一”区域的Token，则需使用“华北-北京一”区域的Endpoint（iam.cn-north-1.myhuaweicloud.com），并在获取用户Token的URI部分找到resource-path（/v3/auth/tokens），拼接起来如下所示。

(11)

https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens

图2-1 URI 示意图

说明

为查看方便，在每个具体API的URI部分，只给出resource-path部分，并将请求方法写在一起。

这是因为URI-scheme都是HTTPS，同一个服务的Endpoint在同一个区域也相同，所以简洁起见将这两部分省略。

请求方法

HTTP请求方法（也称为操作或动词），它告诉服务你正在请求什么类型的操作。

● GET：请求服务器返回指定资源。

● PUT：请求服务器更新指定资源。

● POST：请求服务器新增资源或执行特殊操作。

● DELETE：请求服务器删除指定资源，如删除对象等。

● HEAD：请求服务器资源头部。

● PATCH：请求服务器更新资源的部分内容。当资源不存在的时候，PATCH可能会

去创建一个新的资源。

在获取用户Token的URI部分，您可以看到其请求方法为“POST”，则其请求为：

POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens

请求消息头

附加请求头字段，如指定的URI和HTTP方法所要求的字段。例如定义消息体类型的请求头“Content-Type”，请求鉴权信息等。

如下公共消息头需要添加到请求中。

● Content-Type：消息体的类型（格式），必选，默认取值为“application/

json”，有其他取值时会在具体接口中专门说明。

● X-Auth-Token：用户Token，可选，当使用Token方式认证时，必须填充该字 段。用户Token也就是调用获取用户Token接口的响应值，该接口是唯一不需要认证的接口。

说明

API同时支持使用AK/SK认证，AK/SK认证是使用SDK对请求进行签名，签名过程会自动往请求中添加Authorization（签名认证信息）和X-Sdk-Date（请求发送的时间）请求头。

(12)

POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens Content-Type: application/json

请求消息体

请求消息体通常以结构化格式发出，与请求消息头中Content-type对应，传递除请求消息头之外的内容。若请求消息体中参数支持中文，则中文字符必须为UTF-8编码。

每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消息体为空），GET、DELETE操作类型的接口就不需要消息体，消息体具体内容需要根据具体接口而定。

对于获取用户Token接口，您可以从接口的请求部分看到所需的请求参数及参数说明。将消息体加入后的请求如下所示，加粗的斜体字段需要根据实际值填写，其中

username

为用户名，

domainname

为用户所属的帐号名称，

********

为用户登录密码，

xxxxxxxxxxxxxxxxxx

为project的名称，如“cn-north-1”，您可以从地区和终端节点获取，对应地区和终端节点页面的“区域”字段的值。

说明

scope参数定义了Token的作用域，下面示例中获取的Token仅能访问project下的资源。您还可以设置Token作用域为某个帐号下所有资源或帐号的某个project下的资源，详细定义请参见获取用户Token。

POST https://iam.cn-north-1.myhuaweicloud.com/v3/auth/tokens Content-Type: application/json

{ "auth": { "identity": { "methods": [ "password"

],

"password": { "user": {

"name": "username", "password": "********", "domain": {

"name": "domainname"

} } } }, "scope": { "project": {

"name": "xxxxxxxxxxxxxxxxxx"

} } } }

到这里为止这个请求需要的内容就具备齐全了，您可以使用curl、Postman或直接编写代码等方式发送请求调用API。对于获取用户Token接口，返回的响应消息头中“x- subject-token”就是需要获取的用户Token。有了Token之后，您就可以使用Token认证调用其他API。

2.2 认证鉴权

调用接口有如下两种认证方式，您可以选择其中一种进行认证鉴权。

● Token认证：通过Token认证调用请求。

(13)

● AK/SK认证：通过AK（Access Key ID）/SK（Secret Access Key）加密调用请求。

推荐使用AK/SK认证，其安全性比Token认证要高。

Token 认证

说明

Token的有效期为24小时，需要使用一个Token鉴权时，可以先缓存起来，避免频繁调用。

Token在计算机系统中代表令牌（临时）的意思，拥有Token就代表拥有某种权限。

Token认证就是在调用API的时候将Token加到请求消息头，从而通过身份认证，获得操作API的权限。

Token可通过调用获取用户Token接口获取，调用本服务API需要project级别的 Token，即调用获取用户Token接口时，请求body中auth.scope的取值需要选择 project，如下所示。

{ "auth": { "identity": { "methods": [ "password"

],

"password": { "user": {

"name": "username", "password": "********", "domain": {

"name": "domainname"

} } } }, "scope": { "project": {

"name": "xxxxxxxx"

} } } }

获取Token后，再调用其他接口时，您需要在请求消息头中添加“X-Auth-Token”，

其值即为Token。例如Token值为“ABCDEFJ....”，则调用接口时将“X-Auth-Token:

ABCDEFJ....”加到请求消息头即可，如下所示。

Content-Type: application/json X-Auth-Token: ABCDEFJ....

您还可以通过这个视频教程了解如何使用Token认证：https://

bbs.huaweicloud.com/videos/101333。

AK/SK 认证

说明

AK/SK签名认证方式仅支持消息体大小12MB以内，12MB以上的请求请使用Token认证。

AK/SK认证就是使用AK/SK对请求进行签名，在请求时将签名信息添加到消息头，从而

(14)

● SK(Secret Access Key)：与访问密钥ID结合使用的密钥，对请求进行加密签名，

可标识发送方，并防止请求被修改。

使用AK/SK认证时，您可以基于签名算法使用AK/SK对请求进行签名，也可以使用专门的签名SDK对请求进行签名。详细的签名方法和SDK使用方法请参见API签名指南。

须知

签名SDK只提供签名功能，与服务提供的SDK不同，使用时请注意。

2.3 返回结果

状态码

请求发送以后，您会收到响应，包含状态码、响应消息头和消息体。

状态码是一组从1xx到5xx的数字代码，状态码表示了请求响应的状态，完整的状态码列表请参见状态码。

对于获取用户Token接口，如果调用后返回状态码为“201”，则表示请求成功。

响应消息头

对应请求消息头，响应同样也有消息头，如“Content-type”。

对于获取用户Token接口，返回如图2-2所示的消息头，其中“x-subject-token”就是需要获取的用户Token。有了Token之后，您就可以使用Token认证调用其他API。

图2-2 获取用户 Token 响应消息头

(15)

响应消息体（可选）

响应消息体通常以结构化格式返回，与响应消息头中Content-type对应，传递除响应消息头之外的内容。

对于获取用户Token接口，返回如下消息体。为篇幅起见，这里只展示部分内容。

{ "token": {

"expires_at": "2019-02-13T06:52:13.855000Z", "methods": [

"password"

],

"catalog": [ {

"endpoints": [ {

"region_id": "xxxxxxxx", ...

当接口调用出错时，会返回错误码及错误信息说明，错误响应的Body体格式如下所示。

{ "error": {

"message": "The request you have made requires authentication.", "title": "Unauthorized"

} }

其中，error_code表示错误码，error_msg表示错误描述信息。

(16)

3 ^{API 概览}

数据加密服务提供的接口，您可以完整的使用数据加密服务的所有功能。

类型说明

管理加密密钥加密密钥管理接口，包括密钥的创建，查询，修改，删除等接口。

凭据管理服务凭据管理接口，包括凭据的创建，查询，修改，删除等接口。

管理SSH密钥对 SSH密钥对管理接口（最新版本），包括SSH密钥对的创建，

查询，修改，删除等接口。

历史API SSH密钥对管理接口（V2.1和V2版本），包括SSH密钥对的创建，查询，修改，删除等接口。

历史 API

API分类 说明

管理SSH密钥对(V2.1) 查询SSH密钥对列表。

查询SSH密钥对详细信息。

创建SSH密钥对和导入SSH密钥对，同时可选择对私钥进行托管。

根据SSH密钥对的名称，删除指定SSH密钥对。

根据SSH密钥对的名称，修改指定SSH密钥对的描述信息。

管理SSH密钥对(V2.0) 查询SSH密钥对信息列表。

根据SSH密钥对的名称查询指定SSH密钥对。

(17)

API分类 说明

创建SSH密钥对，或把公钥导入华为云中，生成SSH 密钥对。

创建SSH密钥对成功后，请把响应数据中的私钥内容保存到本地文件，用户使用该私钥登录云服务器。为保证云服务器安全，私钥数据只能下载一次，请妥善保管。

根据SSH密钥对的名称，删除指定SSH密钥对。

在同一个租户下可能包含多个用户帐号，将同一租户下目标用户帐号下的密钥对复制到当前用户帐号下。

(18)

4 ^{API 说明}

4.1 管理加密密钥

4.1.1 密钥生命周期管理

4.1.1.1 创建密钥

功能介绍

创建用户主密钥，用户主密钥可以为对称密钥或非对称密钥。

● 对称密钥为长度为256位AES密钥或者128位SM4密钥，可用于小量数据的加密或者用于加密数据密钥。

● 非对称密钥可以为RSA密钥对或者ECC密钥对（包含SM2密钥对），可用于加解密数据、数字签名及验签。

接口约束

别名“/default”为服务默认主密钥的后缀名，由服务自动创建。因此用户创建的主密钥别名不能与服务默认主密钥的别名相同，即后缀名不能为“/default”。对于开通企业项目的用户，服务默认主密钥属于且只能属于默认企业项目下，且不支持企业资源的迁入迁出。服务默认主密钥为用户提供基础的云上加密功能，满足合规要求。因此，在企业多项目下，其他非默认企业项目下的用户均可使用该密钥。若客户有企业管理资源诉求，请自行创建和使用密钥。

调试

您可以在API Explorer中调试该接口。

URI

POST /v1.0/{project_id}/kms/create-key

(19)

表4-1 路径参数

参数是否必选参数类型描述

project_id 是 String 项目ID

请求参数

表4-2 请求 Header 参数

X-Auth-Token 是 String 用户Token。通过调用IAM服务获取用户Token接口获取（响应消息头中X-Subject-Token的值）。

表4-3 请求 Body 参数

key_alias 是 String 非默认主密钥别名，取值范围为 1到255个字符，满足正则匹配

“^[a-zA-Z0-9:/_-]

{1,255}$”，且不与系统服务创建的默认主密钥别名重名。

key_spec 否 String 密钥生成算法，默认为

“AES_256”，枚举如下：

● AES_256

● SM4

● RSA_2048

● RSA_3072

● RSA_4096

● EC_P256

● EC_P384

● SM2

key_usage 否 String 密钥用途，对称密钥默认为

“ENCRYPT_DECRYPT”，非对称密钥默认为

“SIGN_VERIFY”，枚举如下：

● ENCRYPT_DECRYPT

● SIGN_VERIFY

(20)

origin 否 String 密钥来源，默认为“kms”，枚

举如下：

● kms：表示密钥材料由kms生成。

● external：表示密钥材料由外部导入。

enterprise_pro

ject_id 否 String 企业多项目ID。

● 用户未开通企业多项目时，

不需要输入该字段。

● 用户开通企业多项目时，创建资源可以输入该字段。若用户户不输入该字段，默认创建属于默认企业多项目ID

（ID为“0”）的资源。注意：若用户没有默认企业多项目ID（ID为“0”）下的创建权限，则接口报错。

sequence 否 String 请求消息序列号，36字节序列号。例如：

919c82d4-8046-4722-9094-35 c3c6524cff

响应参数

状态码： 200

表4-4 响应 Body 参数

参数参数类型描述

key_info

KeKInfo

object 密钥详细信息。

表4-5 KeKInfo

key_id String 密钥ID。

domain_id String 用户域ID。

状态码： 400

(21)

error Object 错误信息返回体。

表4-7 ErrorDetail

error_code String 错误请求返回的错误码 error_msg String 错误请求返回的错误信息

状态码： 401

状态码： 403

error_code String 错误请求返回的错误码

(22)

状态码： 404

状态码： 500

状态码： 502

(23)

error_msg String 错误请求返回的错误信息

状态码： 504

请求示例

{ "key_alias" : "test"

}

响应示例

状态码： 200 请求已成功

{ "key_info" : {

"key_id" : "bb6a3d22-dc93-47ac-b5bd-88df7ad35f1e", "domain_id" : "b168fe00ff56492495a7d22974df2d0b"

}}

状态码

状态码描述

200 请求已成功

400 请求参数有误

401 被请求的页面需要用户名和密码

(24)

状态码描述

500 服务内部错误

502 请求未完成。服务器从上游服务器收到一个无效的响应

504 网关超时

错误码

请参见错误码。

4.1.1.2 启用密钥

功能介绍

● 功能介绍：启用密钥，密钥启用后才可以使用。

● 说明：密钥为禁用状态才能启用密钥。

调试

URI

POST /v1.0/{project_id}/kms/enable-key

表4-20 路径参数

请求参数

(25)

key_id 是 String 密钥ID，36字节，满足正则匹

配“^[0-9a-z]{8}-[0-9a-z]{4}- [0-9a-z]{4}-[0-9a-z]{4}-[0-9a- z]{12}$”。例如：0d0466b0- e727-4d9c-b35d-

f84bb474a37f。

919c82d4-8046-4722-9094-35 c3c6524cff

响应参数

状态码： 200

key_info

KeyStatusInf

o object

密钥状态信息。

表4-24 KeyStatusInfo

key_id String 密钥ID key_state String 密钥状态：

● 2为启用状态

● 3为禁用状态

● 4为计划删除状态

● 5为等待导入状态

● 7为冻结状态

状态码： 400

(26)

状态码： 401

状态码： 403

状态码： 404

(27)

状态码： 500

状态码： 502

(28)

状态码： 504

请求示例

{ "key_id" : "0d0466b0-e727-4d9c-b35d-f84bb474a37f"

}

响应示例

{ "key_info" : {

"key_id" : "bb6a3d22-dc93-47ac-b5bd-88df7ad35f1e", "key_state" : "2"

}}

状态码

状态码描述

200 请求已成功

403 认证失败

404 资源不存在，资源未找到 500 服务内部错误

504 网关超时

(29)

错误码

4.1.1.3 禁用密钥

功能介绍

● 功能介绍：禁用密钥，密钥禁用后不可以使用。

● 说明：密钥为启用状态才能禁用密钥。

调试

URI

POST /v1.0/{project_id}/kms/disable-key

表4-39 路径参数

请求参数

配“^[0-9a-z]{8}-[0-9a-z]{4}- [0-9a-z]{4}-[0-9a-z]{4}-[0-9a-

(30)

919c82d4-8046-4722-9094-35 c3c6524cff

响应参数

状态码： 200

key_info

KeyStatusInf

o object

密钥状态信息。

表4-43 KeyStatusInfo

状态码： 400

(31)

状态码： 401

状态码： 403

状态码： 404

(32)

状态码： 500

状态码： 502

状态码： 504

(33)

请求示例

}

响应示例

{ "key_info" : {

"key_id" : "bb6a3d22-dc93-47ac-b5bd-88df7ad35f1e", "key_state" : "3"

}}

状态码

状态码描述

200 请求已成功

403 认证失败

(34)

错误码

4.1.1.4 计划删除密钥功能介绍

● 功能介绍：计划多少天后删除密钥，可设置7天～1096天内删除密钥。

调试

URI

POST /v1.0/{project_id}/kms/schedule-key-deletion

表4-58 路径参数

请求参数

f84bb474a37f。

pending_days 是 String 计划多少天后删除密钥，取值为 7到1096。

(35)

919c82d4-8046-4722-9094-35 c3c6524cff

响应参数

状态码： 200

状态码： 400

状态码： 401

(36)

状态码： 403

状态码： 404

(37)

状态码： 500

状态码： 502

状态码： 504

(38)

请求示例

{ "key_id" : "0d0466b0-e727-4d9c-b35d-f84bb474a37f", "pending_days" : "7"

}

响应示例

{ "key_id" : "bb6a3d22-dc93-47ac-b5bd-88df7ad35f1e", "key_state" : "4"

}

状态码

状态码描述

200 请求已成功

403 认证失败

504 网关超时

错误码

4.1.1.5 取消计划删除密钥功能介绍

● 功能介绍：取消计划删除密钥。

● 说明：密钥处于“计划删除”状态才能取消计划删除密钥。

(39)

调试

URI

POST /v1.0/{project_id}/kms/cancel-key-deletion

表4-76 路径参数

请求参数

f84bb474a37f。

919c82d4-8046-4722-9094-35 c3c6524cff

响应参数

状态码： 200

(40)

状态码： 400

状态码： 401

(41)

状态码： 403

状态码： 404

状态码： 500

(42)

状态码： 502

状态码： 504

请求示例

}

响应示例

(43)

{ "key_id" : "bb6a3d22-dc93-47ac-b5bd-88df7ad35f1e", "key_state" : "3"

}

状态码

状态码描述

200 请求已成功

403 认证失败

504 网关超时

错误码

4.1.1.6 修改密钥别名功能介绍

● 功能介绍：修改用户主密钥别名。

● 说明：

– 服务默认主密钥（密钥别名后缀为“/default”）不可以修改。

– 密钥处于“计划删除”状态，密钥别名不可以修改。

调试

URI

POST /v1.0/{project_id}/kms/update-key-alias

表4-94 路径参数

(44)

请求参数

f84bb474a37f。

key_alias 是 String 非默认主密钥别名，取值1到 255字符，满足正则匹配“^[a- zA-Z0-9:/_-]{1,255}$”且后缀不可以为“/default”。

919c82d4-8046-4722-9094-35 c3c6524cff

响应参数

状态码： 200

key_info

KeyAliasInfo

object 密钥别名信息。

表4-98 KeyAliasInfo

(45)

参数参数类型描述 key_alias String 密钥别名。

状态码： 400

状态码： 401

状态码： 403

(46)

状态码： 404

状态码： 500

状态码： 502

(47)

状态码： 504

请求示例

{ "key_id" : "0d0466b0-e727-4d9c-b35d-f84bb474a37f", "key_alias" : "test"

}

响应示例

{

(48)

状态码

状态码描述

200 请求已成功

403 认证失败

504 网关超时

错误码

4.1.1.7 修改密钥描述功能介绍

● 功能介绍：修改用户主密钥描述信息。

● 说明：

– 服务默认主密钥（密钥别名后缀为“/default”）不可以修改。

– 密钥处于“计划删除”状态，密钥描述不可以修改。

调试

URI

POST /v1.0/{project_id}/kms/update-key-description

表4-113 路径参数

(49)

请求参数

f84bb474a37f。

key_descriptio

n 是 String 密钥描述，取值0到255字符。

919c82d4-8046-4722-9094-35 c3c6524cff

响应参数

状态码： 200

key_info

KeyDescripti

onInfo object

密钥描述信息。

表4-117 KeyDescriptionInfo

(50)

状态码： 400

状态码： 401

状态码： 403

(51)

状态码： 404

状态码： 500

状态码： 502

(52)

状态码： 504

请求示例

{ "key_id" : "0d0466b0-e727-4d9c-b35d-f84bb474a37f", "key_description" : "test"

}

响应示例

{ "key_info" : {

"key_id" : "bb6a3d22-dc93-47ac-b5bd-88df7ad35f1e", "key_description" : "test"

}}

(53)

状态码

状态码描述

200 请求已成功

403 认证失败

504 网关超时

错误码

4.1.2 数据密钥管理

4.1.2.1 创建随机数功能介绍

● 功能介绍：生成8~8192bit范围内的随机数。

调试

URI

POST /v1.0/{project_id}/kms/gen-random

表4-132 路径参数

(54)

请求参数

random_data_

length 是 String 随机数的bit位长度。取值为8的倍数，取值范围为8~8192。随机数的bit位长度，取值为

“512”。

919c82d4-8046-4722-9094-35 c3c6524cff

响应参数

状态码： 200

random_data String 随机数16进制表示，两位表示1byte。随机数的长度与用户传入的参数 “random_data_length”

的长度保持一致。

状态码： 400

(55)

状态码： 401

状态码： 403

状态码： 404

(56)

状态码： 500

状态码： 502

(57)

状态码： 504

请求示例

{ "random_data_length" : "512"

}

响应示例

{ "random_data" : "5791C223E87120BE4B98D168F47A58BB2A88834EEADC"

}

状态码

状态码描述

200 请求已成功

403 认证失败

(58)

错误码

4.1.2.2 创建数据密钥

功能介绍

● 功能介绍：创建数据密钥，返回结果包含明文和密文。

调试

URI

POST /v1.0/{project_id}/kms/create-datakey

表4-150 路径参数

请求参数

f84bb474a37f。

(59)

key_spec 否 String 指定生成的密钥bit位长度。有效值：AES_256、AES_128。

● AES_256：表示256比特的对称密钥。

● AES_128：表示128比特的对称密钥。说明：

datakey_length和key_spec 二选一。

● 若datakey_length和 key_spec都为空，默认生成 256bit的密钥。

● 若datakey_length和 key_spec都指定了值，仅 datakey_length生效。

datakey_lengt

h 否 String 密钥bit位长度。取值为8的倍

数，取值范围为8~8192。说明： datakey_length和 key_spec二选一。

919c82d4-8046-4722-9094-35 c3c6524cff

响应参数

状态码： 200

plain_text String DEK明文16进制，两位表示1byte。

cipher_text String DEK密文16进制，两位表示1byte。

(60)

状态码： 401

状态码： 403

(61)

状态码： 404

状态码： 500

状态码： 502

(62)

状态码： 504

请求示例

{ "key_id" : "0d0466b0-e727-4d9c-b35d-f84bb474a37f", "datakey_length" : "512"

}

响应示例

{ "key_id" : "0d0466b0-e727-4d9c-b35d-f84bb474a37f", "plain_text" : "8151014275E426C72EE7D44267XXXXX...", "cipher_text" : "020098009EEAFCE122CAA5927D2XXX..."

}

状态码

状态码描述

200 请求已成功

403 认证失败

404 资源不存在，资源未找到

(63)

状态码描述

500 服务内部错误

504 网关超时

错误码

4.1.2.3 创建不含明文数据密钥功能介绍

● 功能介绍：创建数据密钥，返回结果只包含密文。

调试

URI

POST /v1.0/{project_id}/kms/create-datakey-without-plaintext

表4-168 路径参数

请求参数

(64)

f84bb474a37f。

key_spec 否 String 指定生成的密钥bit位长度。有效值：AES_256、AES_128。

● AES_256：表示256比特的对称密钥。

● AES_128：表示128比特的对称密钥。说明：

datakey_length和key_spec 二选一。

datakey_lengt

h 否 String 密钥bit位长度。取值为8的倍

数，取值范围为8~8192。说明： datakey_length和 key_spec二选一。

919c82d4-8046-4722-9094-35 c3c6524cff

响应参数

状态码： 200

(65)

cipher_text String DEK密文16进制，两位表示1byte。

状态码： 400

状态码： 401

状态码： 403

构造请求_数据加密服务 DEW_API参考_如何调用API_华为云

API 参考

目 录

1 使用前必读... 1

2 如何调用 API...4

3 API 概览... 10

4 API 说明... 12

5 历史 API... 310

6 应用示例... 330

7 权限和授权项...339

A 附录...344

B 修订记录... 360

1 使用前必读

1.1 概述

1.2 调用说明

1.3 终端节点

1.4 约束与限制

1.5 基本概念

1.6 API 版本选择建议

2 如何调用 API

2.1 构造请求

bbs.huaweicloud.com/videos/102987。

请求 URI

请求方法

请求消息头

请求消息体

username

domainname

********

xxxxxxxxxxxxxxxxxx

2.2 认证鉴权

Token 认证

bbs.huaweicloud.com/videos/101333。

AK/SK 认证

2.3 返回结果

状态码

响应消息头

响应消息体（可选）

3 API 概览

历史 API

4 API 说明

4.1 管理加密密钥

4.1.1 密钥生命周期管理

4.1.1.1 创建密钥

功能介绍

接口约束

调试

URI

请求参数

响应参数

KeKInfo

请求示例

响应示例

状态码

错误码

4.1.1.2 启用密钥

功能介绍

调试

URI

请求参数

响应参数

KeyStatusInf

o object

请求示例

响应示例

状态码

错误码

4.1.1.3 禁用密钥

功能介绍

调试

URI

请求参数

响应参数

KeyStatusInf

o object

请求示例

响应示例

状态码

错误码

4.1.1.4 计划删除密钥 功能介绍

目录

1 ^{使用前必读}

2 ^{如何调用 API}

3 ^{API 概览}

4 ^{API 说明}

4.1.1.4 计划删除密钥功能介绍

4.1.1.5 取消计划删除密钥功能介绍

4.1.1.6 修改密钥别名功能介绍

4.1.1.7 修改密钥描述功能介绍

4.1.2.1 创建随机数功能介绍

4.1.2.3 创建不含明文数据密钥功能介绍