全部产品
存储与CDN 数据库 安全 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网 钉钉智能硬件

公共HTTP参数

更新时间:2017-11-16 14:48:18

通讯协议

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) 再把英文等号连接得到的字符串按参数名称的字典顺序依次使用 &符号连接,即得到规范化请求字符串。

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

    1. StringToSign=
    2. HTTPMethod + “&” +
    3. percentEncode(“/”) + ”&” +
    4. percentEncode(CanonicalizedQueryString)
    5. 其中 HTTPMethod 是提交请求用的 HTTP 方法,比如 GET
    6. percentEncode(“/”) 是按照 1.b 中描述的 URL 编码规则对字符 “/” 进行编码得到 的值,即 “%2F”。
    7. percentEncode(CanonicalizedQueryString) 是对第 1 步中构造的规范化请求字 符串按 1.b 中描述的 URL 编码规则编码后得到的字符串。
  • 按照 RFC2104 的定义,使用上面的用于签名的字符串计算签名 HMAC 值。注意:计算签名时使用的 Key 就是用户持有的 Access Key Secret 并加上一个 “&” 字符(ASCII:38),使用的哈希算法是 SHA1。

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

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

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

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

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

那么CanonicalizedQueryString就是:

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

所以StrToSign应该是:

  1. GET&%2F&AccessKeyId%3Dtestid&Action%3DCreateKey&Format%3Djson&SignatureMethod%3DHMAC-SHA1&SignatureVersion%3D1.0&Timestamp%3D2016-03-28T03%253A13%253A08Z&Version%3D2016-01-20

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

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

签名后的请求URL为(注意增加了Signature参数):

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

公共参数

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

名称 类型 是否必须 描述
Format String 返回值的类型,支持 JSON 与 XML。默认为 XML。
Action String API名称。
Version String API 版本号,为日期形式:YYYY-MM-DD,本版本对应为 2016-01-20。
AccessKeyId String 阿里云颁发给用户的访问服务所用的密钥 ID。
Signature String 签名结果串,关于签名的计算方法,请参见上一小节中的签名机制
SignatureMethod String 签名方式,目前支持 HMAC-SHA1。
Timestamp String 请求的时间戳。日期格式按照 ISO8601 标准表示,并需要使用 UTC 时间。格式为:YYYY-MM-DDThh:mm:ssZ。例如,2015-12-01T12:00:00Z(为北京时间 2015 年 12 月 01 日 20 点 0 分 0 秒)。
SignatureVersion String 签名算法版本,目前版本是 1.0。

示例:

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

公共返回参数

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

Xml示例:

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

Json示例:

  1. {
  2. "RequestId": "284b2b80-9b17-4546-a093-adfbae512a54"
  3. }

公共错误

错误代码 描述 HTTP状态码
InternalFailure Internal Failure 500
SerivceUnvailableTemporary Service Unvailable Temporary 503
InvalidAccessKeyId.NotFound The Access Key ID provided does not exist in our records. 404
Forbidden.KeyNotFound The specified Key is not found. 404
Forbidden.NoPermission This operation is forbidden by permission system. 403
Forbidden.AccessKey This AccessKey is not enabled. 403
ParseRequestParameterException server parse parameters exception,please check your input params. 400
MissingParameter The parameter “< parameter name >” is needed but no provided. 400
InvalidParameter The specified parameter “< parameter name >” is not valid. 400
IncompleteSignature The request signature does not conform to Aliyun standards. 400
IllegalTimestamp The input parameter “Timestamp” that is mandatory for processing this request is not supplied. 400
UnsupportedHTTPMethod This http method not supported. 403
Forbidden.UbsmsInvalidUserid Userid Invalid For Ubsms 403
Forbidden.UbsmsInvalidBid Your account partner does not have KMS Service 403
Forbidden.KmsServiceNotEnabled Kms service not Enabled for current user, please get access permission firstly 403
Forbidden.ProhibitedByRiskControl Current user is Prohibited By Risk Control 403
Forbidden.InDebtOverdue Current user is indebted Overdue 403
Forbidden.InDebt Current user is indebted 403
Rejected.LimitExceeded User Key Limit Exceeded 400
Rejected.Disabled The specified Key is not Enable 409
Rejected.StateModifiedFailed keystate modified failed 409

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

Xml示例(请求过期):

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

Json示例(请求过期):

  1. {
  2. "HttpStatus": 400
  3. "Code": "IllegalTimestamp"
  4. "Message": "The input parameter "Timestamp" that is mandatory for processing this request is not supplied."
  5. "RequestId": "e85db688-a2d3-44ca-9790-4259f59e90d8"
  6. }
本文导读目录