API参考
所有文档

          相关参考 Reference

          API参考

          1 简介

          证书管理模块主要用于管理用户的SSL证书,方便用户录入以及查看SSL证书。

          本文档适用于开发人员,主要提供接口为创建证书,查看证书列表等。

          1.1 名词解释

          名词 说明
          certId 证书ID, 全局唯一
          certName 证书自定义名称
          certServerData 服务器证书
          certPrivateData 证书私钥
          certLinkData 证书链数据
          certCommonName 证书通用名称
          certDNSNames 证书包含的域名
          certStartTime 证书生效时间
          certStopTime 证书到期时间
          uploadPublicKey 上传证书公钥,用来加密数据。之后需要使用对应的私钥机密数据
          status 证书使用状态,UNUSED表示未使用,IN_USE表示使用中
          expired 证书是否过期,true表示已经过期
          certType 证书类型,1表示服务端证书,私钥为必填项;2表示客户端证书,私钥为非必填项

          1.2 格式规范

          参数 说明
          certId 格式:“cert-xxxxxxxxxxxx”(12位随机字符串),例子:“cert-5atue8m3sxsv”。

          2.调用方式

          证书服务 API以Restful API的形式提供。

          2.1 请求结构

          2.1.1 通信协议

          目前支持HTTP,暂不支持HTTPS。

          2.1.2 请求方法

          不同类型的API使用不同的请求方法,如下所示:

          API类型 请求方法
          读取资源 GET
          修改资源 PUT
          批量查询/创建资源 POST
          删除资源 DELETE
          获取资源状态 HEAD

          2.1.3 字符编码

          请求和返回结果都使用UTF-8编码。

          2.2 公共参数

          2.2.1 公共请求头

          头域 是否必须 说明
          Authorization 必须 认证机制
          Content-Type 必须 应该总是application/json; charset=utf-8
          x-bce-date 必须 请求时间,格式见[时间格式](#6.2 时间格式)。服务器会比较该时间与当前服务器时间,如果两者相差超过30分钟,则返回RequestExpired错误

          2.2.2 公共响应头

          头域 说明
          Content-Type 总是application/json; charset=utf-8
          x-bce-request-id 对应请求的[requestId](#6.3 RequestId)

          2.2.3 认证机制

          公有云API规范-认证机制

          3.api列表

          3.1 创建证书

          方法 API 说明
          POST /v1/certificate 创建证书

          请求参数

          参数名称 参数类型 是否必须 说明
          certName String 必须 证书的名称。长度限制为1-65个字符,以字母开头,只允许包含字母、数字、’-‘、’/’、’.’、’’,Java正则表达式` ^[a-zA-Z]a-zA-Z0-9\-/\.]{2,64}$`
          certServerData String 必须 服务器证书的数据内容 (Base64编码)
          certPrivateData String 必须 证书的私钥数据内容 (Base64编码)
          certLinkData String 可选 证书链数据内容 (Base64编码)
          certType Integer 可选 证书类型,非必填,默认为1

          返回参数

          返回值为一个certificate对象(只包含certId和certName)。

          可能异常

          异常code 说明
          CertExceedLimit (409) 超过用户最大证书数
          UnmatchedPairParameterInvalidException (400) 证书有效时间不包含当前时间
          PrivateKeyParameterInvalid (400) 私钥解析异常
          CertificateParameterInvalid (400) 证书解析异常
          CertChainParameterInvalid (400) 证书链解析异常
          UnmatchedPairParameterInvalid (400) 公钥私钥不匹配

          请求示例

              POST /v1/certificate HTTP/1.1
              HOST: certificate.baidubce.com
              Authorization: {authorization}
              Content-Type: application/json; charset=utf-8
              x-bce-date: 2014-06-01T23:00:10Z
          
              {
                  "certName": "TestCert",
                  "certServerData": "-----BEGIN CERTIFICATE-----\ngBs4mWchJjzl0IM3B+TrAD...\n-----END CERTIFICATE-----",
                  "certPrivateData": "-----BEGIN RSA PRIVATE KEY-----\n6JCfAxrrh7AoCg0jhqjgN/by0U2jwG/xFe...\n-----END RSA PRIVATE KEY-----"
              }

          返回示例

              HTTP/1.1 200 OK
              Content-Type: application/json; charset=utf-8
              x-bce-request-id: 9ebc57ed-1ff5-480f-b5b1-6847ff54f2b4
          
              {
                  "certId": "cert-5atue8m3sxsv",
                  "certName": "TestCert"
              }

          3.2 修改证书名称

          方法 API 说明
          PUT /v1/certificate/{certId}?certName 修改证书名称

          可能异常

          异常code 说明
          AccessDeniedException 无权限访问
          ResourceNotFoundException 证书不存在

          请求参数

          参数名称 参数类型 是否必须 说明
          certName String 必须 证书名称

          请求示例

              PUT /v1/certificate/cert-5atue8m3sxsv?certName HTTP/1.1
              HOST: certificate.baidubce.com
              Authorization: {authorization}
              Content-Type: application/json; charset=utf-8
              x-bce-date: 2014-06-01T23:00:10Z
          
              {
                  "certName": "TestCert"
              }

          返回示例

              HTTP/1.1 200 OK
              Content-Type: application/json; charset=utf-8
              x-bce-request-id: 9ebc57ed-1ff5-480f-b5b1-6847ff54f2b4

          3.3 根据证书名查询证书

          方法 API 说明
          GET /v1/certificate?certName={certName} 根据证书名查询用户的证书

          请求参数

          参数名称 参数类型 是否必须 说明
          certName String 必须 证书名称

          返回参数

          参数名称 参数类型 说明
          certs List<certificate> 由certificate组成的数组

          请求示例

              GET /v1/certificate?certName=TestCert HTTP/1.1
              HOST: certificate.baidubce.com
              Authorization: {authorization}
              Content-Type: application/json; charset=utf-8
              x-bce-date: 2014-06-01T23:00:10Z

          返回示例

              HTTP/1.1 200 OK
              Content-Type: application/json; charset=utf-8
              x-bce-request-id: 9ebc57ed-1ff5-480f-b5b1-6847ff54f2b4
          
              {
                  "certs": [
                      {
                          "certId": "cert-5atue8m3sxsv",
                          "certName": "TestCert",
                          "certCommonName": "httpstest.baidu.com",
                          "certStartTime": "2014-06-01T23:00:10Z",
                          "certStopTime": "2015-06-01T23:00:10Z",
                          "certCreateTime": "2014-06-01T23:00:10Z",
                          "certUpdateTime": "2014-06-01T23:00:10Z"
                      }
                  ]
              }

          3.4 查看证书列表

          方法 API 说明
          GET /v1/certificate 查看用户的证书列表

          返回参数

          参数名称 参数类型 说明
          certs List<certificate> 由certificate组成的数组

          请求示例

              GET /v1/certificate HTTP/1.1
              HOST: certificate.baidubce.com
              Authorization: {authorization}
              Content-Type: application/json; charset=utf-8
              x-bce-date: 2014-06-01T23:00:10Z

          返回示例

              HTTP/1.1 200 OK
              Content-Type: application/json; charset=utf-8
              x-bce-request-id: 9ebc57ed-1ff5-480f-b5b1-6847ff54f2b4
          
              {
                  "certs": [
                      {
                          "certId": "cert-5atue8m3sxsv",
                          "certName": "TestCert",
                          "certCommonName": "httpstest.baidu.com",
                          "certStartTime": "2014-06-01T23:00:10Z",
                          "certStopTime": "2015-06-01T23:00:10Z",
                          "certCreateTime": "2014-06-01T23:00:10Z",
                          "certUpdateTime": "2014-06-01T23:00:10Z"
                      },
                      {
                          "certId": "cert-xsdfwerdty67",
                          "certName": "TestCertFail",
                          "certCommonName": "httpstestfail.baidu.com",
                          "certStartTime": "2014-06-01T23:00:10Z",
                          "certStopTime": "2015-06-01T23:00:10Z",
                          "certCreateTime": "2014-06-01T23:00:10Z",
                          "certUpdateTime": "2014-06-01T23:00:10Z"
                      }
                  ]
              }

          3.5 查看证书列表详情

          方法 API 说明
          GET /v1/certificate/detail 查看用户的证书列表详情,相比普通的查询证书列表,证书中多了证书域名和使用状态信息

          返回参数

          参数名称 参数类型 说明
          certs List<certificateDetail> 由certificateDetail组成的数组

          certificateDetail参数列表

          参数名称 参数类型 说明
          certId String 证书ID
          certName String 证书名称
          certCommonName String 证书通用名称
          certStartTime DateTime 证书生效时间
          certStopTime DateTime 证书到期时间
          certCreateTime DateTime 证书创建时间
          certUpdateTime DateTime 证书更新时间
          certType Integer 证书类型
          certDNSNames String 证书包含的域名列表,用英文逗号隔开
          status String 证书使用状态,UNUSED表示未使用,IN_USE表示使用中
          expired boolean 证书是否过期

          请求示例

              GET /v1/certificate/detail HTTP/1.1
              HOST: certificate.baidubce.com
              Authorization: {authorization}
              Content-Type: application/json; charset=utf-8
              x-bce-date: 2014-06-01T23:00:10Z

          返回示例

              HTTP/1.1 200 OK
              Content-Type: application/json; charset=utf-8
              x-bce-request-id: 9ebc57ed-1ff5-480f-b5b1-6847ff54f2b4
          
              {
                  "certs": [
                      {
                          "certId": "cert-5atue8m3sxsv",
                          "certName": "TestCert",
                          "certCommonName": "httpstest.baidu.com",
                          "certStartTime": "2014-06-01T23:00:10Z",
                          "certStopTime": "2015-06-01T23:00:10Z",
                          "certCreateTime": "2014-06-01T23:00:10Z",
                          "certUpdateTime": "2014-06-01T23:00:10Z",
                          "certDNSNames": "baidu.com",
                          "status": "IN_USE",
                          "expired": false
                      },
                      {
                          "certId": "cert-xsdfwerdty67",
                          "certName": "TestCertFail",
                          "certCommonName": "httpstestfail.baidu.com",
                          "certStartTime": "2014-06-01T23:00:10Z",
                          "certStopTime": "2015-06-01T23:00:10Z",
                          "certCreateTime": "2014-06-01T23:00:10Z",
                          "certUpdateTime": "2014-06-01T23:00:10Z",
                          "certDNSNames": "baidu.com",
                          "status": "UNUSED",
                          "expired": true
                      }
                  ]
              }

          3.6 获取证书信息(无证书公钥私钥)

          方法 API 说明
          GET /v1/certificate/{certId} 获取证书ID为{certId}的应用信息

          返回参数

          返回值为一个certificate对象

          certificate参数列表

          参数名称 参数类型 说明
          certId String 证书ID
          certName String 证书名称
          certCommonName String 证书通用名称
          certStartTime DateTime 证书生效时间
          certStopTime DateTime 证书到期时间
          certCreateTime DateTime 证书创建时间
          certUpdateTime DateTime 证书更新时间
          certType Integer 证书类型

          可能异常

          异常code 说明
          AccessDeniedException 无权限访问
          ResourceNotFoundException 证书不存在

          请求示例

          GET /v1/certificate/cert-5atue8m3sxsv HTTP/1.1
          HOST: certificate.baidubce.com
          Authorization: {authorization}
          Content-Type: application/json; charset=utf-8
          x-bce-date: 2014-06-01T23:00:10Z

          返回示例

          HTTP/1.1 200 OK
          Content-Type: application/json; charset=utf-8
          x-bce-request-id: 9ebc57ed-1ff5-480f-b5b1-6847ff54f2b4
          
          {
              "certId": "cert-5atue8m3sxsv",
              "certName": "TestCert",
              "certCommonName": "httpstest.baidu.com",
              "certStartTime": "2014-06-01T23:00:10Z",
              "certStopTime": "2015-06-01T23:00:10Z",
              "certCreateTime": "2014-06-01T23:00:10Z",
              "certUpdateTime": "2014-06-01T23:00:10Z",
              "certType": 1
          }

          3.7 删除证书

          方法 API 说明
          DELETE /v1/certificate/{certId} 删除证书

          可能异常

          异常code 说明
          OperationNotAllowedException 证书使用中
          AccessDeniedException 无权限访问
          ResourceNotFoundException 证书不存在

          请求示例

              DELETE /v1/certificate/cert-5atue8m3sxsv HTTP/1.1
              HOST: certificate.baidubce.com
              Authorization: {authorization}
              Content-Type: application/json; charset=utf-8
              x-bce-date: 2014-06-01T23:00:10Z

          返回示例

              HTTP/1.1 200 OK
              Content-Type: application/json; charset=utf-8
              x-bce-request-id: 9ebc57ed-1ff5-480f-b5b1-6847ff54f2b4

          3.8 替换证书(id不变)

          方法 API 说明
          PUT /v1/certificate/{certId}?certData 替换过期且不在使用中的证书

          请求参数

          参数名称 参数类型 是否必须 说明
          certName String 必须 证书的名称。长度限制为1-65个字符,以字母开头,只允许包含字母、数字、’-‘、’/’、’.’、’’,Java正则表达式` ^[a-zA-Z]a-zA-Z0-9\-/\.]{2,64}$`
          certServerData String 必须 服务器证书的数据内容 (Base64编码)
          certPrivateData String 必须 证书的私钥数据内容 (Base64编码)
          certLinkData String 可选 证书链数据内容 (Base64编码)
          certType Integer 可选 证书类型,非必填,默认为1

          可能异常

          异常code 说明
          OperationNotAllowedException(409) 证书使用中或者证书
          AccessDeniedException(403) 证书非本用户或子用户无该证书运维权限
          ResourceNotFoundException(404) 无证书
          CertExceedLimit (409) 超过用户最大证书数
          UnmatchedPairParameterInvalidException (400) 证书有效时间不包含当前时间
          PrivateKeyParameterInvalid (400) 私钥解析异常
          CertificateParameterInvalid (400) 证书解析异常
          CertChainParameterInvalid (400) 证书链解析异常
          UnmatchedPairParameterInvalid (400) 公钥私钥不匹配

          请求示例

              PUT /v1/certificate/cert-5atue8m3sxsv?certData HTTP/1.1	
              HOST: certificate.baidubce.com	
              Authorization: {authorization}	
              Content-Type: application/json; charset=utf-8	
              x-bce-date: 2014-06-01T23:00:10Z	
           	
              {	
                  "certName": "TestCert",	
                  "certServerData": "-----BEGIN CERTIFICATE-----\ngBs4mWchJjzl0IM3B+TrAD...\n-----END CERTIFICATE-----",	
                  "certPrivateData": "-----BEGIN RSA PRIVATE KEY-----\n6JCfAxrrh7AoCg0jhqjgN/by0U2jwG/xFe...\n-----END RSA PRIVATE KEY-----",	
                  	
              }	

          返回示例

              HTTP/1.1 200 OK	
              Content-Type: application/json; charset=utf-8	
              x-bce-request-id: 9ebc57ed-1ff5-480f-b5b1-6847ff54f2b4	

          3.9 获取证书数据(包含私钥)

          方法 API 说明
          GET /v1/certificate/{certId}/rawData 获取证书ID为{certId}的应用信息

          返回参数

          返回值为包含证书私钥的certificate对象

          certificate参数列表

          参数名称 参数类型 说明
          certId String 证书ID
          certName String 证书名称
          certServerData String 公钥证书
          certPrivateKey String 证书私钥
          certLinkData String 证书链,包含多个证书,不包括服务器证书
          certType Integer 证书类型

          可能异常

          异常code 说明
          AccessDeniedException 无权限访问
          ResourceNotFoundException 证书不存在

          请求示例

          GET /v1/certificate/cert-5atue8m3sxsv/rawData HTTP/1.1
          HOST: certificate.baidubce.com
          Authorization: {authorization}
          Content-Type: application/json; charset=utf-8
          x-bce-date: 2014-06-01T23:00:10Z

          返回示例

          HTTP/1.1 200 OK
          Content-Type: application/json; charset=utf-8
          x-bce-request-id: 9ebc57ed-1ff5-480f-b5b1-6847ff54f2b4
          
          {
              "certId": "cert-5atue8m3sxsv",
              "certName": "TestCert",
              "certServerData": "-----BEGIN CERTIFICATE-----\n......data.......\n-----END CERTIFICATE-----",
              "certPrivateKey": "-----BEGIN RSA PRIVATE KEY-----......data......\n-----END RSA PRIVATE KEY-----",
              "certLinkData": "-----BEGIN CERTIFICATE-----\n......data2.......\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\n......data3.......\n-----END CERTIFICATE-----",
              "certType": 1
          }

          6 附表

          6.1 错误状态码

          CODE MESSAGE HTTP Status Code 说明
          OperationNotAllowed Resource status conflict. 409 CONFLICT 资源状态冲突,不能执行请求操作
          ResourceNotFound Resource not found. 404 NOT_FOUND 请求资源不存在
          ParametersNotChanged Parameters not changed. 403 FORBIDDEN 请求参数未发生变化
          ResourceNameDuplicated Resource name duplicated. 409 CONFLICT 资源名称重复
          ParametersInvalid Parameters invalid. 400 BAD REQUEST 请求参数不合法
          AccessDenied Access denied. 403 FORBIDDEN 无权限访问

          6.2 时间格式

          日期与时间的表示有多种方式。为统一起见,除非是约定俗成或者有相应规范的,凡需要日期时间表示的地方一律采用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秒。

          6.3 RequestId

          所有请求都应该唯一地对应一个ID,用于标识该请求。requestId可用于问题定位、性能分析等等多个场景。所有的日志都应该带有requestId以便后续分析。

          上一篇
          第三方机构创建证书
          下一篇
          JAVA-SDK