阿里云-秘钥管理服务-API文档-D

1、密钥管理服务API 文档密钥管理服务/API密钥管理服务/API PAGE 20 PAGE 20API 文档公共部分通讯协议KMS服务只支持使用HTTPS通道发送请求请求方法支持HTTP POST和GET方法发送请求签名机制KMS 服务会对每个访问的请求进行身份验证，用户需要在请求中包含签名（Signature）信息。KMS 通过使用Access Key IDAccess Key SecretMAC（Message Authentication Code）计算的方法来验证请求的发送者身份。Access Key IDAccess Key Secret（可以通过阿里云官方网站申请和管理），Acce

2、ss Key ID；Access Key Secret用户在访问时，按照下面的方法对请求进行签名处理：使用请求参数构造规范化的请求字符串（Canonicalized Query String）按照参数名称的字典顺序对请求中所有的请求参数（包括文档中描述的公共请求参数 和给定了的请求接口的自定义参数，但不能包括公共请求参数中提到 Signature 参数本身）GETURI（即 URI 中?之后由&连接的部分）。UTF-8URL，URL 编码的编码规则是：iA-Z、a-z、0-9_、.、不编码；ii%XYXYASCII16表示。比如英文的双引号（）对应的编码就是 %22iii.UTF-8%XY%Z

3、Aiv（）%20，而不是加号（+）。URL（J.URLEncoder）都是按照application/x-www-form-urlencoded 的 MIME 类型的规则进行编码的。实现时可以直接使用这类方式进行编码，把编码后的字符串中加号（+）替换成%20、星号（*）替换成 %2A、%7E 替换回波浪号（），即可得到上述规则描述的编码字符串。对编码后的参数名称和值使用英文等号（=）进行连接。再把英文等号连接得到的字符串按参数名称的字典顺序依次使用 &符号连接，即得到规范化请求字符串。StringToSign= HTTPMethod + & + percentEncode(/) + & +pe

4、rcentEncode(CanonicalizedQueryString)StringToSign= HTTPMethod + & + percentEncode(/) + & +percentEncode(CanonicalizedQueryString)其 中 HTTPMethod 是 提 交 请 求 用 的 HTTP 方 法 ， 比 如 GET 。 percentEncode(/1.bURL/%2F。percentEncode(CanonicalizedQueryString11.bURLRFC2104 HMACKeyAccess Key Secret&(ASCII:38)，使用的哈希算

5、法是SHA1。按照 Base64 编码规则把上面的 HMAC 值编码成字符串，即得到签名值（Signature）。将得到的签名值作为 Signature 参数添加到请求参数中，即完成对请求签名的过程。注意：得到的签名值在作为最后的请求参数值提交给KMS服务器的时候，要和其他参数一样，按照 RFC3986 URL/?Action=CreateKey &SignatureVersion=1.0/?Action=CreateKey &SignatureVersion=1.0&Format=json &Version=2016-01-20 &AccessKeyId=testid&SignatureMe

6、thod=HMAC-SHA1 &Timestamp=2016-03-28T03:13:08ZAccessKeyId=testid&Action=CreateKey&Format=json&SignatureMethod=HMAC- SHA1&SignatureVersion=1.0&Timestamp=2016-03-28T03%3A13%3A08Z&Version=2016-01-20AccessKeyId=testid&Action=CreateKey&Format=json&SignatureMethod=HMAC- SHA1&SignatureVersion=1.0&Timestamp

7、=2016-03-28T03%3A13%3A08Z&Version=2016-01-20假如使用的Access Key Id是testid，Access Key Secret是testsecret，用于计算HMAC的Key就是testsecret&，则计算得到的签名值是：41wk2SSX1GJh7fwnc5eqOfiJPFg= /url编码之后是41wk2SSX1GJh7fwnc5eqOfiJPFg%3D41wk2SSX1GJh7fwnc5eqOfiJPFg= /url编码之后是41wk2SSX1GJh7fwnc5eqOfiJPFg%3D/?Action=CreateKey &Signatur

8、eVersion=1.0/?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公共参数公共请求参数是指每个接口都需要使用到的请求参数。名称类型是否必须描述FormatString否返回值的类型，支持JSON 与 XML。默认为 XML。ActionSt

9、ring是Api名称,目前提供的api有：CreateKey,Genera yeDataKey,Encrypt,D ecrypt,ListKeys,Descr ibeKeyVersionString是API 版本号，为日期形式：YYYY-MM-DD，本版本对应为2016-01-20。AccessKeyIdString是阿里云颁发给用户的访问服务所用的密钥 ID。SignatureString是签名结果串，关于签名的计算方法，请参见上一小节中的签名机制SignatureMethodString是签名方式，目前支持HMAC-SHA1。TimestampString是请求的时间戳。日期格式按照 IS

10、O8601 标准表示，并需要使用UTC 时间。格式为：YYYY-MM-DDThh:mm:ssZ。例如 ，2015-12- 01T12:00:00Z（为北京时间 2015 年 12 月01 日 20 点 0 分 0 秒）。SignatureVersionString是签名算法版本，目前版本是 1.0。/?Format=json &Action=CreateKey /?Format=json &Action=CreateKey &Version=2016-01-20 &AccessKeyId=testid&Signature=YlrFhyqDZQ1ThNYARrv3Ptaxqfc%3D &Sign

11、atureMethod=HMAC-SHA1 &Timestamp=2016-03-25T09:36:58Z&SignatureVersion=1.0公共返回参数348d9445-e39a-4d80-907d-298cc6c94447348d9445-e39a-4d80-907d-298cc6c94447RequestId: 284b2b80-9b17-4546-a093-adfbae512a54RequestId: 284b2b80-9b17-4546-a093-adfbae512a54公共错误错误代码描述HTTP状态码MissingParameterThe parameter is need

12、ed but no provided.InvalidParameterThe specified parameter is not valid.400InvalidAccessKeyId.NotFoun dThe Access Key ID provided does not exist in our records.404IncompleteSignatureThe request signature does not conform to Aliyun standards.400IllegalTimestampThe input parameter Timestamp that is ma

13、ndatory for processing this request is not supplied.400ThrottlingRequest was denied due to request throttling.400InvalidActionThe specified action is not valid.403UnsupportedHTTPMethodThis http method not supported.403UnsupportedParameterThe parameter is not supported.400Forbidden.KeyNotFoundThe spe

14、cified Key is not found.404Forbidden.RAMUser not authorized to operate on the specified resource, or this API doesnt support RAM.403Forbidden.AuthenticationThis operation is forbidden by Aliyun Realname Authentication system.403Forbidden.KmsServiceNotEn abledKms service not Enabled for current user,

15、 please get access permission firstly403Forbidden.InDebtCurrent user is indebted403Forbidden.InDebtOverdueCurrent user is indebted Overdue403Forbidden.ProhibitedByRiskC ontrolCurrent user is Prohibited By Risk Control403InternalFailureInternal Failure500Forbidden.UbsmsInvalidUseri dUserid Invalid Fo

16、r Ubsms403Rejected.LimitExceededUser Key Limit Exceeded400Rejected.StateModifiedFailedkeystate modified failed409Rejected.DisabledThe specified Key is not Enable409调用接口出错后，将不会返回结果数据。调用方可根据附表 错误代码表 来定位错误原因。当调用出错时，HTTP请求返回一个4xx或5xx的HTTP状态码。返回的消息体中是具体的错误代码及错误信息。另外还包含一 个全局唯一的请求ID：RequestId。在调用方找不到错误原因，可

17、以联系阿里云客服，并提供RequestId以及您 访问的kms服务的域名，以便我们尽快帮您解决问题。400400IllegalTimestampTheinputparameterTimestampthatismandatoryforprocessingthisrequestisnot supplied.3b237773-bc2c-4bea-95fc-319a1a5baa68Json示例（请求过期）:HttpStatus: 400Code: IllegalTimestampMessage:TheinputparameterTimestampthatismandatoryforprocessing

18、thisrequestisnotsupplied. RequestId:e85db688-a2d3-44ca-9790-4259f59e90d8创建密钥(CreateKey)创建一个主密钥。主密钥可以直接用来加密少量的数据(少于4 k),但通常当做产生数据密钥 API的输入用以生成可以加密数据的DataKey，详情请看 产生数据密钥 API- 请求格式Description=string&KeyUsage=stringDescription=string&KeyUsage=string请求参数Description含义 : key的描述类型 : String长度: 0 = len(Descri

19、ption) = 8192 是否必须 : 否KeyUsage含义 : 指定key的用途。目前，默认为 ENCRYPT/DECRYPT，即key用于加密和解密类型 : String有效值 : ENCRYPT/DECRYPT是否必须 : 否请求示例/?Action=CreateKey /?Action=CreateKey &Description=test&KeyUsage=ENCRYPT/DECRYPT &返回格式KeyMetadata: CreationDate: string, Description: string, KeyId: string, KeyState: string, Key

20、Usage: string,RequestId:string返回参数KeyMetaDataCreationDateStringDescriptionkey的描述Stringkey的全局唯一标识符StringKeyState主密钥的状态.StringKeyUsage含义 : 指定key的用途。目前，默认为 ENCRYPT/DECRYPT，只支持对称加密和解密StringRequestIdIdString返回示例：/json response/json responseKeyMetadata: CreationDate: 2016-03-25T10:42:40Z,Description: test

21、,KeyId: *, KeyState: Enabled, KeyUsage: ENCRYPT/DECRYPT,RequestId: 3455b9b4-95c1-419d-b310-db6a53b09a39/xml response2016-03-25T10:40:47Ztest*EnabledENCRYPT/DECRYPT6cb4bf6b-d9c9-4660-af5f-2328378e7257产生数据密钥(GenerateDataKey)生成一个密钥，你可以用这个密钥进行本地数据的加密。这个API返回一个DataKey的明文Plaintext以及DataKey加密后的密文Ciphertext

22、Blob 。DataKey的加密是用keyid对应的主密钥加密的。可以调用Decrypt API进行解密注意我们建议您使用以下方式在本地进行数据加密：调用GenerateDataKey API ，使用返回的明文DataKey在本地加密数据，然后删除内存中的明文DataKey。存储加密过的密钥CiphertextBlob和加密后的数据解密数据时，调用Decrypt API，用CiphertextBlob作为参数，调用成功，会返回DataKey的明文Plaintext，用Plaintext对本地加密的数据进行解密请求格式KeyId=string&KeySpec=string&NumberOfByt

23、es=numberKeyId=string&KeySpec=string&NumberOfBytes=number请求参数key的全局唯一标识符StringCiphertextBlob: blob, / blob为base64编码后的String KeyId: string,CiphertextBlob: blob, / blob为base64编码后的String KeyId: string,Plaintext: blob, / blob为base64编码后的String RequestId:stringkey的加密算法以及key大小，目前支持AES_128AES_256AES_256|AES

24、_128NumberOfBytes(同时指定NumberOfBytes和KeySpec时，以NumberOfBytes为准)11024请求示例/?Action=GenerateDataKey /?Action=GenerateDataKey &KeyId=&KeySpec=AES_256 &返回格式返回参数key的全局唯一标识符StringPlaintextDataKey的明文StringCiphertextBlobDataKey加密后的密文StringRequestIdIdString返回示例：/json response/json responseCiphertextBlob: Ciphe

25、rtextBlob, KeyId: KeyId,Plaintext: Plaintext,RequestId: 7021b6ec-4be7-4d3c-8a68-1e85d4d515a0/xml responseCiphertextBlobKeyIdPlaintextf409073c-ba92-4e8d-a535-069f352009a0加密(Encrypt)通过使用客户主密钥加密的明文转换为密文。加密功能有两个基本用例：可以加密最多为4KB任意数据的诸如RSA密钥，数据库密码，或其他敏感的客户信息。如果您是从一个region迁移加密数据到另一个region，可以使用这个API在新的region

26、中加密在前一 个region中用来加密数据的DataKey明文。这提供了新region认可的一个加密后的CiphertextBlob，可以调用新region中的Decrypt进行解密。KeyId=string&Plaintext=blob请求格式KeyId=string&Plaintext=blob请求参数key的全局唯一标识符StringPlaintextString请求示例/?Action=Encrypt /?Action=Encrypt &KeyId=&Plaintext= &返回格式CiphertextBlob: blob, KeyId: string, RequestId:strin

27、g返回参数key的全局唯一标识符StringCiphertextBlobkey加密后的密文StringRequestIdIdString返回示例：/json response/json responseKeyId: your-key-id, KeyId: your-key-id, CiphertextBlob: CiphertextBlob,RequestId: 475f1620-b9d3-4d35-b5c6-3fbdd941423d/xml responseyour-key-idCiphertextBlob5c8b001f-8845-405f-af9d-e1aae273da46解密（Decr

28、ypt）GenerateDataKey Encrypt解密密文CiphertextBlobGenerateDataKey Encrypt请求格式CiphertextBlob=blob /blob为base64编码后的StringCiphertextBlob=blob /blob为base64编码后的String请求参数CiphertextBlobString请求示例/?Action=Decrypt /?Action=Decrypt &CiphertextBlob= &返回格式Plaintext: blob, / blob为base64编码后的String KeyId: string,Reque

29、stId:string返回参数key的全局唯一标识符StringPlaintextkey明文StringRequestIdIdString- 返回示例：/json response/json responseKeyId: KeyId Plaintext: PlaintextRequestId: 207596a2-36d3-4840-b1bd-f87044699bd7/xml responseKeyIdPlaintext4bd560a1-729e-45f1-a3d9-b2a33d61046b列出密钥(ListKeys)返回用户所有的KeyId- 请求格式PageNumber=number&Pag

30、eSize=numberPageNumber=number&PageSize=number请求参数PageNumber含义 : 当前页数类型 : integer有效值: 大于0， 默认值为1是否必须 : 否PageSize含义 : 每页的个数类型 : integer有效值 : 大于0，小于101，默认为10是否必须 : 否请求示例/?Action=ListKeys /?Action=ListKeys &PageNumber=1&PageSize=10 &- 返回格式TotalCount: integer, PageNumber: integer, PageSize: integer, Keys

31、:Key:KeyId: string,KeyId: string,RequestId:string返回参数KeyIdkey的全局唯一标识符StringTotalCountkey的总数integerPageNumberintegerPageSizeintegerRequestIdIdString返回示例：/json response/json responseKeys: Key: KeyId: key1,KeyId: key2,KeyId: key3,TotalCount: 3,PageNumber: 1,PageSize: 10,RequestId: 1fbcd12a-1b7f-468f-84

32、a3-1ff3444dfd8b/xml responsekey1key2key3331101050b8f1-b264-496d-a782-6299cbaf15f8查看密钥详情(DescribeKey)返回指定keyid的相关信息请求格式KeyId=stringKeyId=string请求参数key的全局唯一标识符String请求示例/?Action=DescribeKey /?Action=DescribeKey &KeyId=&返回格式KeyMetadata: CreationDate: string, Description: string, KeyId: string, KeyState

33、: string, KeyUsage: string,RequestId:string返回参数CreationDateStringkey的全局唯一标识符StringKeyStatekey的状态StringKeyUsagekey的用途StringDescriptionkey的描述StringRequestIdIdString返回示例：/json response/json responseKeyMetadata: CreationDate: 2016-03-25T10:42:40Z,Description: test,KeyId: *, KeyState: Enabled, KeyUsage:

34、ENCRYPT/DECRYPT,RequestId: 3455b9b4-95c1-419d-b310-db6a53b09a39/xml response2016-03-25T10:40:47Ztest*EnabledENCRYPT/DECRYPT6cb4bf6b-d9c9-4660-af5f-2328378e7257EnableKey将一个指定的Key标记为启用状态，允许该Key被使用请求格式KeyId=stringKeyId=string请求参数返回格式key的全局唯一标识符StringRequestId:string返回参数RequestIdIdStringDisableKey将一个指定的Key标记为禁用状态，处于禁用状态的Key无法用于加密、解密操作。直到Key恢复到启用状态之 前，原来使用该Key加密的密文也无法解密。请求格式KeyId=stringKeyId