所有文档

          密钥管理服务 KMS

          简介

          概述

          密钥管理服务是百度智能云提供的一款密钥管理服务,您可以通过该项服务便捷、安全、可靠的在云上管理密钥类信息。

          如果您是初次调用百度智能云产品的API,可以观看API入门视频指南,快速掌握调用API的方法。

          服务域名

          KMS服务目前支持"华北-北京"、"华南-广州"和"华东-苏州"三个区域。

          区域 访问Endpoint 协议
          华北-北京 bkm.bj.baidubce.com HTTPS
          华南-广州 bkm.gz.baidubce.com HTTPS
          华东-苏州 bkm.su.baidubce.com HTTPS

          API认证机制

          所有API的安全认证一律采用Access Key与请求签名机制。 Access Key由Access Key ID和Secret Access Key组成,均为字符串。 对于每个HTTP请求,使用下面所描述的算法生成一个认证字符串。提交认证字符串放在Authorization头域里。服务端根据生成算法验证认证字符串的正确性。 认证字符串的格式为bce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}

          • version是正整数。
          • timestamp是生成签名时的UTC时间。
          • expirationPeriodInSeconds表示签名有效期限。
          • signedHeaders是签名算法中涉及到的头域列表。头域名之间用分号(;)分隔,如host;x-bce-date。列表按照字典序排列。(本API签名仅使用host和x-bce-date两个header)
          • signature是256位签名的十六进制表示,由64个小写字母组成。

          当百度智能云接收到用户的请求后,系统将使用相同的SK和同样的认证机制生成认证字符串,并与用户请求中包含的认证字符串进行比对。如果认证字符串相同,系统认为用户拥有指定的操作权限,并执行相关操作;如果认证字符串不同,系统将忽略该操作并返回错误码。

          鉴权认证机制的详细内容请参见鉴权认证

          幂等性

          当调用某些接口时如果遇到了请求超时或服务器内部错误,用户可能会尝试重发请求,这时用户通过clientToken参数避免创建出比预期要多的资源,即保证请求的幂等性。

          幂等性基于clientToken,clientToken是一个长度不超过64位的ASCII字符串,通常放在query string里,如http://bcc.bj.baidubce.com/v1/instance?clientToken=be31b98c-5e41-4838-9830-9be700de5a20

          如果用户使用同一个clientToken值调用创建接口,则服务端会返回相同的请求结果。因此用户在遇到错误进行重试的时候,可以通过提供相同的clientToken值,来确保只创建一个资源;如果用户提供了一个已经使用过的clientToken,但其他请求参数(包括queryString和requestBody)不同甚至url Path不同,则会返回IdempotentParameterMismatch的错误代码。

          clientToken的有效期为24小时,以服务端最后一次收到该clientToken为准。也就是说,如果客户端不断发送同一个clientToken,那么该clientToken将长期有效。

          日期与时间规范

          日期与时间的表示有多种方式。为统一起见,除非是约定俗成或者有相应规范的,凡需要日期时间表示的地方一律采用UTC时间,遵循ISO 8601,并做以下约束:

          1. 表示日期一律采用YYYY-MM-DD方式,例如2014-06-01表示2014年6月1日
          2. 表示时间一律采用hh:mm:ss方式,并在最后加一个大写字母Z表示UTC时间。例如23:00:10Z表示UTC时间23点0分10秒。
          3. 凡涉及日期和时间合并表示时,在两者中间加大写字母T,例如2014-06-01T23:00:10Z表示UTC时间2014年6月1日23点0分10秒。

          公共请求头

          头域 类型 说明
          Authorization String 用于验证请求合法性的认证信息。更多参见鉴权认证
          Content-Length String RFC2616中定义的HTTP请求内容的长度
          Content-Type String RFC2616中定义的HTTP请求内容的类型
          Content-MD5 String RFC2616定义的HTTP请求内容的MD5摘要,可以通过携带该字段来验证保存在KMS侧的文件和用户预期的文件是否一致
          Date String HTTP 1.1协议中规定的GMT时间,如Wed, 06 Apr 2016 06:34:40 GMT
          Host String 访问Host值,取值为访问区域对应的Endpoint
          x-bce-date String 当前时间,遵循ISO8601规范,格式如2016-04-06T08:23:49Z

          公共响应头

          头域 类型 说明
          Content-Length String RFC2616中定义的HTTP请求内容长度
          Content-Type String RFC2616中定义的HTTP请求内容的类型
          Connection String 服务器是否断开连接,取值为close或者keep-alive
          Date String HTTP 1.1协议中规定的GMT时间,如Wed, 06 Apr 2016 06:34:40 GMT
          Server String 服务器的名字,取值为BceKms
          x-bce-request-id String 由BCE KMS创建,是请求BceKms的唯一标识
          x-bce-debug-id String 由BCE KMS创建,用于帮助排除故障的标识ID,如果在使用KMS过程中遇到问题,可以在工单中提供该字段便于快速定位问题

          错误码

          当用户访问出错时,KMS返回的错误响应体如下:

          {
          	"code":"AccessDenied"
          	"message":"Access denied"
          	"requestId":"7ab2b34d-614d-478a-ba9b-3049ca7b6479"
          }

          公共错误码

          HTTP状态码 错误码 消息 语义
          403 Forbidden AccessDenied Access denied 拒绝访问
          403 Forbidden SignatureDoesNotMatch The request signature we calculated does not match the signature you provided Authorization头域中附带的签名和服务端计算出的签名不一致
          400 Bad Request InvalidHttpAuthHeader The HTTP authorization header is invalid Authorization头域格式错误
          400 Bad Request MissingHttpAuthHeader You must provide the authorization header 缺少Authorization头域
          403 Forbidden RequestExpired Request has expired 请求的时间戳过期
          403 Forbidden InvalidAccessKeyId The Access Key ID you provided does not exist in our records 无效的Access Key Id
          500 Internal Server Error InternalError We encountered an internal error Please try again 内部服务错误

          密钥管理服务错误码

          HTTP状态码 错误码 消息 语义
          400 Bad Request MasterKeyNumExceed You have attempted to create more master keys than allowed Master Key数目超过限制
          400 Bad Request InvalidPlaintext The plaintext you provided is invalid 无效的待加密明文
          404 Not Found NoSuchMasterKey The specified master key does not exist 不存在该master key
          400 Bad Request InvalidDescription The specified description is invalid 无效的master key描述
          400 Bad Request NotImplemented The API has not been implemented yet 该接口不存在
          400 Bad Request InvalidCiphertext The specified ciphertext is invalid 无效的待解密密文
          400 Bad Request InvalidMasterKeyId The specified master key id is invalid 无效的Master Key Id
          400 Bad Request MissingMasterKeyId You must provide the master key id 缺少Master Key Id字段
          400 Bad Request PlaintextLengthExceed The length of plaintext exceeds the limit 待加密明文长度超过限制
          400 Bad Request MissingPlaintext You must provide the plaintext 缺少明文字段
          400 Bad Request InvalidKeyUsage The specified keyUsage is invalid 无效的keyUsage
          400 Bad Request InvalidPendingWindowInDays The specified pending windows in days is invalid 指定的待删除天数非法
          400 Bad Request InvalidListKeysLimit The specified limit of list keys is invalid 指定的罗列master key的数目限制无效
          400 Bad Request MissingCiphertext You must provide the ciphertext 缺少待加密密文
          400 Bad Request MissingNumberOfBytes You must provide the numberOfBytes 缺少生成密钥的长度的字段
          400 Bad Request InvalidKeySpec The specified keySpec is invalid 非法的keySpec
          400 Bad Request InvalidNumberOfBytes The specified numberOfBytes is invalid 无效的numberOfBytes
          429 Too Many Requests Throttling The rate of your request exceed limit 访问被限速
          400 Bad Request InvalidState The state of the specified key is invalid for your request 指定的Key状态无效
          400 Bad Request InvalidJson The json is malformed or does not meet the requirements 可能是该json格式不正确,或者是不满足该接口要求
          400 Bad Request InvalidMarker The marker you provided is invalid 无效的marker
          400 Bad Request InvalidAction The specified action is not supported 请求参数中action参数的值无效
          400 Bad Request unactivated The account has not activated the kms service 尚未激活KMS服务
          400 Bad Request chargeOverDue this account charge is overdue 账户欠费
          上一篇
          操作指南
          下一篇
          接口介绍