V2.0 Renew Certificate


当设备证书过期或失效或设备密钥被认为不可信时，需要对证书进行更新，并将新证书与设备进行绑定，同时可以对所申请的证书进行有效期设置。

该 API 支持在 EnOS 2.1.0 及以上环境中使用。

操作权限


使用此 API 前，确保服务账号已被授予包含下列服务和操作权限的策略。有关授权服务账号的更多信息，参见 管理服务账号。


需授权的服务 所需操作权限
证书 Renew

前提条件

  • 该设备存在
  • 该设备所属产品为支持双向认证产品
  • 原旧证书与该设备绑定
  • 原旧证书属于有效状态

请求格式

POST https://{apigw-address}/connect-service/v2.0/certificates?action=renew

请求参数 (URI)

注解

以下非必需字段中，必须提供 assetId 或 productKey + deviceKey 的组合，用于指定设备。

名称 位置（Path/Query） 必需/可选 数据类型 描述
orgId Query 必需 String 资产所属的组织 ID。如何获取 orgId 信息>>
assetId Query 可选（见上述注解） String 资产 ID。如何获取 assetId 信息>>
productKey Query 可选（见上述注解） String 设备的 product key，需与 deviceKey 一起使用。
deviceKey Query 可选（见上述注解） String 设备的 device key，需与 productKey 一起使用。

请求参数 (Body)

名称 必需/可选 数据类型 描述
csr 可选 String 证书请求文件 (Certificate Signing Request), PEM 格式字符串。如果请求中不包含该参数时，则以之前旧证书的请求数据进行重新生成证书。生成CSR文件的方法，参见 创建证书签名申请（CSR）>>
certSn 必需 Integer 需要更新的证书序列号。这是申请证书时返回的 certSN 号，该号也能使用 List Certificate 接口获取。
validDay 可选 Integer 证书的有效期。单位为天。其适用规则见下文。
issueAuthority 可选 String EnOS证书颁发方。如果未声明该参数，则采用默认值RSA。该参数的规则见下文。

validDay适用规则

validDay 遵循以下规则：
  • 如果用户没有指定有效期，则采用默认值，默认值根据具体EnOS环境而异。
  • 如果用户指定了有效期：
    • 如果用户指定的有效期不大于这个设备所属产品的最长证书有效期，则采用用户指定的证书有效期
    • 如果用户指定的有效期大于这个设备所属产品的最长证书有效期，则报错，申请证书失败
    • 如果指定的有效期（不大于产品最长证书有效期的值）大于根证书剩余天数，采用根证书剩余天数。

issueAuthority适用规则

issueAuthority遵循以下规则：

  • 如果不在请求中声明授权颁发方，采用默认值RSA。
  • 如果在请求中声明授权方，目前可选的值是RSA或ECC，可忽略大小写。

issueAuthority取值说明

  • RSA: 要求证书请求文件格式，必须是2048的RSA公钥且签名算法为SHA256withRSA。
  • ECC: 求证书请求文件格式，必须是256位的ECC公钥，公钥算法为prime256v1，且签名算法为SHA256WITHECDSA。

响应参数

名称 数据类型 描述
data DeviceCertRenewResultInfo 结构体 证书绑定信息，见 DeviceCertRenewResultInfo 结构体。

DeviceCertRenewResultInfo 结构体

名称 数据类型 描述
certChainURL String CA根证书链地址。
cert String 申请到的证书内容。
certSn String 证书编号。
caCert String CA根证书。
issueAuthority String 授权颁发方。

错误码

代码 类型 描述 解决方法
99400 The specified validity period exceeds the maximum certificate validity period of the product to which this device belongs 指定的有效期，超出了这个设备所属产品的最长证书有效期 validDay 参数修改成有效数值
99400 invalid argument: Device identifier is invalid 设备标识符无效 在请求中声明 assetId 或 productKey + deviceKey 以指定设备
99400 Invalid Argument certSn:certSn is missing 缺少certSn参数 在请求中声明 certSn 参数
99400 The product to which the device belongs is not a product that supports bi-directional authorization. 设备所属产品不是支持双向认证的产品. 更改所属产品的属性为支持双向认证
99400 Call ca error!: Certificate service err info:, code: (code), message: (message content), detail message: (detailed message content) 调用EnOS证书服务参数异常。 详细错误信息原因由message或 detail message给出
99400 Invalid cert request!message: (message content), detail message: (detailed message content) 无效证书请求。 详细错误信息原因由message或 detail message给出
99400 Renew cert is failed!message: (message content), detail message: (detailed message content) 更新证书失败。 详细错误信息原因由message或 detail message给出
99400 Query cert is failed!message: (message content), detail message: (detailed message content) 查询证书失败。 详细错误信息原因由message或 detail message给出
99400 When calling Certificate Services, the call parameters are invalid.message: (message content), detail message: (detailed message content) 当调用证书服务时，调用参数无效。 详细错误信息原因由message或 detail message给出
99400 Serial number of the certificate to be updated is required. 待更新证书的序列号是必需字段 在请求中声明 certSn 参数
99400 Serial number of the new certificate is invalid (less than 0). 传入的证书序列号无效（小于0） 确保声明的 certSn 参数有效
99400 The original certificate has revoked and cannot be updated. 原证书已被撤销，不能被更新 重新申请新证书
99400 The original certificate has expired and cannot be updated. 原证书已过期，不能被更新 重新申请新证书
99400 The certificate list bound to the device does not have the certificate,or the certificate is bound to other devices. 原证书未与设备绑定或绑定另一个设备 确认请求中声明的证书有效
11404 Device cannot be found 设备未找到。 确认该设备确实存在
11833 Certificate already bound to another device 证书已绑定到另一个设备。 更换证书请求文件
99500 Internal error of certificate service 设备连接与管理证书服务内部错误 联系管理员
99500 Internal error of product service. 设备连接与管理产品服务内部错误 联系管理员
99500 Internal error of IoT hub service 设备连接与管理内部服务错误 联系管理员

示例

请求示例

url: https://{apigw-address}/connect-service/v2.0/certificates?assetId=yourDeviceAssetId&action=renew&orgId=yourOrgId
method: POST
requestBody:
{
    "csr":"-----BEGIN NEW CERTIFICATE REQUEST-----\nMIICxDCCAawCAQAwfzELMAkGA1UEBhMCQ04xETAPBgNVBAgMCFNoYW5naGFpMREw\nDwYDVQQHDAhTaGFuZ2hhaTENMAsGA1UECgwERW5PUzERMA8GA1UEAwwITnNQTU1F\ncHExDTALBgNVBAsMBEVuT1MxGTAXBgkqhkiG9w0BCQEWCjB5eGtWY2pwZXIwggEi\nMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDIiuFINos2TgLO6G+yQdKs3hc+\n+Cuael/AB8bP2IlunlDdyrllpWT4ROimDDEUfV/qXzlHYvxBwaL7GKPFPKeoercn\ntS6ttGBkeZXMJwbXdfpXsusubmy8qOZqBofikjZ+CaAuUd6fvEA3aqLHDaHrhtYi\nfoQOBRsuzr16JW79AMjwPdbXA4UtcLlloDEtccJInwlT3F/Ck7CEQ4n8TcNrpfkT\nsVfLaYt1AkdokKD1cKVDp5kYoHr4bUJK+y1vII+hyRnkmazs5AsiMzc5+nllWyq0\nnwptoyqzy7ynu6k/4myUMZBPd4qrbbNuJjvx/wWf0q9RaY9ri8Rdii9q76zlAgMB\nAAGgADANBgkqhkiG9w0BAQsFAAOCAQEAUJeY3lGdFNLd+KifKUjlYqQKRaknsDhg\no2wyxrofzkTSVPR/gxR+lTPaZJdaHoSTylXUPZ2P/NDtclYnw2XVcg8eCZH0B0BA\nZ9V/t8Z8LXxZx++Cm3B6kvt8FtOZpBnqxkKlht28Sh14tKPdLDE684aFrnQjYgS1\nfJdn0W9tEr27GbUf+xmsY5hnPwh7VxcJ1k46eCLZd0Jj2+DdOhqb3nW1Q9I22Fsr\n9z0ccXmY573svl49nd8jAExsin/qJpd3ATZj2PXQ2HJPi38hT/KRYxjmXjQjTF+K\ngw+KmU7UWOpeSZYiHMGN+8krfjT4mbPcCPWePRMSVJjXsXwj7YbLYQ==\n-----END NEW CERTIFICATE REQUEST-----\n",
    "validDay":220,
    "certSn":52770,
    "issueAuthority":"RSA"
}

响应示例

{
    "code": 0,
    "msg": "OK",
    "requestId": "3eaf8fb2-9305-4db9-8044-b5632044abf8",
    "data": {
        "certChainURL": "https://{domain-name}/enos/CA/cacert/RSA",
        "caCert": "-----BEGIN CERTIFICATE-----\nMIID7DCCAtSgAwIBAgIJAK3CuSWAQ/PIMA0GCSqGSIb3DQEBCwUAMIGCMQswCQYD\nVQQGEwJDTjERMA8GA1UECAwIU2hhbmdoYWkxETAPBgNVBAcMCFNoYW5naGFpMQ0w\nCwYDVQQKDARFbk9TMRAwDgYDVQQLDAdFbk9TIENBMRAwDgYDVQQDDAdFbk9TIENB\nMRowGAYJKoZIhvcNAQkBFgtjYUBlbmlvdC5pbzAeFw0xOTAyMjYwOTExMzlaFw0y\nOTAyMjMwOTExMzlaMIGCMQswCQYDVQQGEwJDTjERMA8GA1UECAwIU2hhbmdoYWkx\nETAPBgNVBAcMCFNoYW5naGFpMQ0wCwYDVQQKDARFbk9TMRAwDgYDVQQLDAdFbk9T\nIENBMRAwDgYDVQQDDAdFbk9TIENBMRowGAYJKoZIhvcNAQkBFgtjYUBlbmlvdC5p\nbzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMU32ZYkLVcUzdvlASek\npL7oiwK4dCsmNmIIL0JHyfjPoIk34ud0eB3YR/6wv4n4eXkLp51ZOMcfTC/TXGW2\noz3gwhv/hIVg2vtu3sIYiKoL87UtMk1B6nlWdiuNeklGWEzY7nrdUEBjZn0l93Oy\nSmkXT/zPbK0ix5qLAcSuV23zADNihdh7oiUIEk8M4qz1QZWKaU+l7WPEcGZiDkRh\nZ8SWZ3Z4TQZoazDV1EGXTiw0v722O/TsnviTWilFhGsUclW91VzicZQf6NStp6Wc\nJtsGviiN+HPI+gpX2TVl/1lQmom9YPBhwdVzqGPs4NqhTClVkXUSxKSoA4ab42P/\nUBUCAwEAAaNjMGEwHQYDVR0OBBYEFINjzI33ermRFRvh5oVmH1TbgYcaMB8GA1Ud\nIwQYMBaAFINjzI33ermRFRvh5oVmH1TbgYcaMA8GA1UdEwEB/wQFMAMBAf8wDgYD\nVR0PAQH/BAQDAgEGMA0GCSqGSIb3DQEBCwUAA4IBAQACseTlfMbEA0PVbwxTSuNp\npaJ5XBFGqxFkuK5MYYBAVFmqlfSluH39BPJQFCnSNZi16T6vEXuvqqTZOIylE3z1\nVARUg3sHKLIx7sKKA4rFjTb49h48BlQGHHuyapdSJwRHuIqrWuGwgHz7Bi7NZ6EO\ngw+xkfMlEC846mlsRfqxxkFiI69hIkpu5rdO7Ya8uaXJSyAi1J3/gLSidWyyUMFM\nAq1eeWRDY/IrEcb0nRjgObuqE5DVq/1ylpkL+5DAaSiG9vYSpyIacnKxkPlg6ezJ\nqXJM+s3XWxm8/mlqspb5ewHxj6dVw/DOhFky+3l7zHERdWPkHHysEp/IcHB6Vj6y\n-----END CERTIFICATE-----",
        "cert": "-----BEGIN CERTIFICATE-----\nMIIEPDCCAySgAwIBAgIDAM4jMA0GCSqGSIb3DQEBCwUAMIGCMQswCQYDVQQGEwJD\nTjERMA8GA1UECAwIU2hhbmdoYWkxETAPBgNVBAcMCFNoYW5naGFpMQ0wCwYDVQQK\nDARFbk9TMRAwDgYDVQQLDAdFbk9TIENBMRAwDgYDVQQDDAdFbk9TIENBMRowGAYJ\nKoZIhvcNAQkBFgtjYUBlbmlvdC5pbzAeFw0yMDA0MjEwNzA0MDVaFw0yMDExMjcw\nNzA0MDVaMH8xCzAJBgNVBAYTAkNOMREwDwYDVQQIDAhTaGFuZ2hhaTERMA8GA1UE\nBwwIU2hhbmdoYWkxDTALBgNVBAoMBEVuT1MxETAPBgNVBAMMCE5zUE1NRXBxMQ0w\nCwYDVQQLDARFbk9TMRkwFwYJKoZIhvcNAQkBFgoweXhrVmNqcGVyMIIBIjANBgkq\nhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyIrhSDaLNk4CzuhvskHSrN4XPvgrmnpf\nwAfGz9iJbp5Q3cq5ZaVk+ETopgwxFH1f6l85R2L8QcGi+xijxTynqHq3J7UurbRg\nZHmVzCcG13X6V7LrLm5svKjmagaH4pI2fgmgLlHen7xAN2qixw2h64bWIn6EDgUb\nLs69eiVu/QDI8D3W1wOFLXC5ZaAxLXHCSJ8JU9xfwpOwhEOJ/E3Da6X5E7FXy2mL\ndQJHaJCg9XClQ6eZGKB6+G1CSvstbyCPockZ5Jms7OQLIjM3Ofp5ZVsqtJ8KbaMq\ns8u8p7upP+JslDGQT3eKq22zbiY78f8Fn9KvUWmPa4vEXYovau+s5QIDAQABo4G8\nMIG5MAkGA1UdEwQCMAAwJwYJYIZIAYb4QgENBBpFbm9zIEdlbmVyYXRlZCBDZXJ0\naWZpY2F0ZTAdBgNVHQ4EFgQU2+AZzfu8kL4+xUOy1nrulgHLBrcwHwYDVR0jBBgw\nFoAUg2PMjfd6uZEVG+HmhWYfVNuBhxowQwYJYIZIAYb4QgEEBDZodHRwczovL2Fs\ncGhhLXBvcnRhbC1jbjQuZW5pb3QuaW86ODA4MS9lbm9zL0NBL2NybC9SU0EwDQYJ\nKoZIhvcNAQELBQADggEBABonMzhNpDhXLPSwsm2x3xzgsnsYiCzZd+2+T01zN9dt\no/UOrG3OLduZd90DrqKmsTXOhcNsUxrhdFo2sB2N6xEsHhB6vH41LdHHdvAJjEG9\nlKpU9ZX666loa9GUcN1/Lm2+MjBkUw7GBbSZGQBFRII6JDiBWlWzgzvjeTkB4i0u\nHcZ/y/S1Fv5jmF1vxFLvXUiBvljf3YPqVFFGt4WNXvWuDpRG0RRdozo4UkYrlJOD\nkZTFP4jSyROAFvvc4d5TnMtOySvKuAmRD7UmHrDoT/gNd4SG3f3fpTBVsxFHs4FI\nTXllWR55xQv68rEn8VsoUUpPpLzyZ+AmiOocOCCIhQY=\n-----END CERTIFICATE-----\n",
        "certSN": "52771",
        "issueAuthority": "RSA"
    }
}

SDK 示例


你可以在 Github 上获取接入服务的 SDK 示例：