930      阿里云  技术社区[云栖]

公共HTTP参数__API 参考_密钥管理服务-阿里云

通讯协议

KMS服务只支持使用HTTPS通道发送请求。

KMS不支持SSLv2和SSLv3，仅支持TLS1.0及以上。

请求方法

支持HTTP POST和GET方法发送请求

签名机制

KMS 服务会对每个访问的请求进行身份验证，用户需要在请求中包含签名（Signature）信息。KMS 通过使用 Access Key ID 和 Access Key Secret 进行MAC（Message Authentication Code）计算的方法来验证请求的发送者身份。Access Key ID 和 Access Key Secret 由阿里云官方颁发给访问者（可以通过阿里云官方网站申请和管理），其中 Access Key ID 用于标识访问者的身份；Access Key Secret 是用于加密签名字符串和服务器端验证签名字符串的密钥，必须严格保密，只有阿里云和用户知道。

用户在访问时，按照下面的方法对请求进行签名处理：

• 使用请求参数构造规范化的请求字符串（Canonicalized Query String）

  • (a) 按照参数名称的字典顺序对请求中所有的请求参数（包括文档中描述的“公共请求参数”和给定了的请求接口的自定义参数，但不能包括“公共请求参数”中提到 Signature 参数本身）进行排序。注：当使用 GET 方法提交请求时，这些参数就是请求 URI 中的参数部分（即 URI 中“?”之后由“&”连接的部分）。

  • (b) 对每个请求参数的名称和值进行编码。名称和值要使用 UTF-8 字符集进行 URL 编码，URL 编码的编码规则是：

    • i. 对于字符 A-Z、a-z、0-9 以及字符“-”、“_”、“.”、“~”不编码；
    • ii. 对于其他字符编码成 “%XY” 的格式，其中 XY 是字符对应 ASCII 码的 16 进制表示。比如英文的双引号（”）对应的编码就是 %22
    • iii.对于扩展的 UTF-8 字符，编码成 “%XY%ZA…” 的格式；
    • iv. 需要说明的是英文空格（ ）要被编码是 %20，而不是加号（+）。
    • 注：一般支持 URL 编码的库（比如 Java 中的 java.net.URLEncoder）都是按照 “application/x-www-form-urlencoded” 的 MIME 类型的规则进行编码的。实现时可以直接使用这类方式进行编码，把编码后的字符串中加号（+）替换成 %20、星号（*）替换成 %2A、%7E 替换回波浪号（~），即可得到上述规则描述的编码字符串。```

  • (c) 对编码后的参数名称和值使用英文等号（=）进行连接。

  • (d) 再把英文等号连接得到的字符串按参数名称的字典顺序依次使用 &符号连接，即得到规范化请求字符串。

• 使用上一步构造的规范化字符串按照下面的规则构造用于计算签名的字符串：

    StringToSign=
    HTTPMethod + “&” +
    percentEncode(“/”) + ”&” +
    percentEncode(CanonicalizedQueryString)
    其中 HTTPMethod 是提交请求用的 HTTP 方法，比如 GET。
    percentEncode(“/”) 是按照 1.b 中描述的 URL 编码规则对字符 “/” 进行编码得到    的值，即 “%2F”。
    percentEncode(CanonicalizedQueryString) 是对第 1 步中构造的规范化请求字    符串按 1.b 中描述的 URL 编码规则编码后得到的字符串。

• 按照 RFC2104 的定义，使用上面的用于签名的字符串计算签名 HMAC 值。注意：计算签名时使用的 Key 就是用户持有的 Access Key Secret 并加上一个 “&” 字符(ASCII:38)，使用的哈希算法是 SHA1。

• 按照 Base64 编码规则把上面的 HMAC 值编码成字符串，即得到签名值（Signature）。

• 将得到的签名值作为 Signature 参数添加到请求参数中，即完成对请求签名的过程。

注意：得到的签名值在作为最后的请求参数值提交给KMS服务器的时候，要和其他参数一样，按照 RFC3986 的规则进行 URL 编码。

以CreateKey为例,签名前的请求URL为:

https://kms.cn-hangzhou.aliyuncs.com/?Action=CreateKey
&SignatureVersion=1.0
&Format=json
&Version=2016-01-20
&AccessKeyId=testid
&SignatureMethod=HMAC-SHA1
&Timestamp=2016-03-28T03:13:08Z

那么StringToSign就是：

AccessKeyId=testid&Action=CreateKey&Format=json&SignatureMethod=HMAC-SHA1&SignatureVersion=1.0&Timestamp=2016-03-28T03%3A13%3A08Z&Version=2016-01-20

假如使用的Access Key Id是“testid”，Access Key Secret是“testsecret”，用于计算HMAC的Key就是“testsecret&”，则计算得到的签名值是：

41wk2SSX1GJh7fwnc5eqOfiJPFg=   //url编码之后是41wk2SSX1GJh7fwnc5eqOfiJPFg%3D

签名后的请求URL为（注意增加了Signature参数）：

https://kms.cn-hangzhou.aliyuncs.com/?Action=CreateKey
&SignatureVersion=1.0
&Format=json
&Version=2016-01-20
&AccessKeyId=F5856RW8kXMuAPMU
&SignatureMethod=HMAC-SHA1
&Timestamp=2016-03-28T03:13:08Z
&Signature=41wk2SSX1GJh7fwnc5eqOfiJPFg%3D

公共参数

公共请求参数是指每个接口都需要使用到的请求参数。

示例：

https://kms.cn-hangzhou.aliyuncs.com/?
Format=json
&Action=CreateKey
&Version=2016-01-20
&AccessKeyId=testid
&Signature=YlrFhyqDZQ1ThNYARrv3Ptaxqfc%3D
&SignatureMethod=HMAC-SHA1
&Timestamp=2016-03-25T09:36:58Z
&SignatureVersion=1.0

公共返回参数

用户发送的每次接口调用请求，无论成功与否，系统都会返回一个唯一识别码RequestId给用户。

Xml示例：

<KMS>
<RequestId>348d9445-e39a-4d80-907d-298cc6c94447</RequestId>
<!—返回结果数据-->
</KMS>

Json示例：

{
"RequestId": "284b2b80-9b17-4546-a093-adfbae512a54"
}

公共错误

调用接口出错后，将不会返回结果数据。调用方可根据附表 错误代码表 来定位错误原因。当调用出错时，HTTP请求返回一个4xx或5xx的HTTP状态码。返回的消息体中是具体的错误代码及错误信息。另外还包含一个全局唯一的请求ID：RequestId。在调用方找不到错误原因，可以联系阿里云客服，并提供RequestId以及您访问的kms服务的域名，以便我们尽快帮您解决问题。

Xml示例（请求过期）：

<KMS>
<HttpStatus>400</HttpStatus>
<Code>IllegalTimestamp</Code>
<Message>The input parameter "Timestamp" that is mandatory for processing this request is not supplied.</Message>
<RequestId>3b237773-bc2c-4bea-95fc-319a1a5baa68</RequestId>
 </KMS>

Json示例（请求过期）:

{
"HttpStatus": 400
"Code": "IllegalTimestamp"
"Message": "The input parameter "Timestamp" that is mandatory for processing this request is not supplied."
"RequestId": "e85db688-a2d3-44ca-9790-4259f59e90d8"
}

最后更新：2016-11-29 15:53:00

  上一篇： 删除堆栈失败__常见问题_资源编排-阿里云

  下一篇： CreateKey__API 参考_密钥管理服务-阿里云