Renew Certificate¶
当设备证书过期或失效或设备密钥被认为不可信时，需要对证书进行更新，并将新证书与设备进行绑定，同时可以对所申请的证书进行有效期设置。
操作权限¶
| 需授权的资源 | 所需操作权限 |
|---|---|
| 设备管理 | Full Access |
约束条件¶
- 该设备存在
- 该设备所属产品为支持双向认证产品
- 原旧证书与该设备绑定
- 原旧证书属于有效状态
请求格式¶
POST https://{apigw-address}/connect-service/v2.0/certificates?action=renew
请求参数 (URI)¶
注解
以下非必须字段中，必须提供 assetId 或 productKey + deviceKey 的组合，用于指定设备。
| 名称 | 位置 | 必需/可选 | 数据类型 | 描述 |
|---|---|---|---|---|
| orgId | Query | 必需 | String | 资产所属的组织ID。如何获取orgId信息>> |
| assetId | Query | 可选 | String | 资产ID。如何获取Asset ID信息>> |
| productKey | Query | 可选 | String | Product key. |
| deviceKey | Query | 可选 | String | Device key. |
请求参数 (Body)¶
| 名称 | 必需/可选 | 数据类型 | 描述 |
|---|---|---|---|
| csr | 可选 | String | 证书请求文件 (Certificate Signing Request), PEM 格式字符串。如果请求中不包含该参数时，则以之前旧证书的请求数据进行重新生成证书。生成CSR文件的方法，参见 创建证书签名申请（CSR）>> |
| certSn | 必需 | Integer | 需要更新的证书序列号。 |
| 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 | IoT Hub证书服务内部错误 | 联系管理员 |
| 99500 | Internal error of product service. | IoT Hub产品服务内部错误 | 联系管理员 |
| 99500 | Internal error of IoT hub service | IoT Hub 内部服务错误 | 联系管理员 |
示例¶
请求示例¶
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"
}
}
Java SDK 调用示例¶
package com.envisioniot.enos.api.sample.connect_service.cert;
import com.envision.apim.poseidon.config.PConfig;
import com.envision.apim.poseidon.core.Poseidon;
import com.envisioniot.enos.connect_service.v2_1.cert.RenewCertificateRequest;
import com.envisioniot.enos.connect_service.v2_1.cert.RenewCertificateResponse;
import com.envisioniot.enos.connect_service.vo.DeviceIdentifier;
public class RenewCert {
public static void main(String[] args) {
String appKey = "yourAppAccessKey";
String appSecret = "yourAppSecretKey";
String serverUrl = "https://{apigw-address}";
String orgId = "yourOrgId";
// newCert表示CSR文件，为可选项，如不包含该参数，则以旧证书的请求数据重新生成证书。
String newCert = "-----BEGIN NEW CERTIFICATE REQUEST-----\n" +
"MIICwTCCAakCAQAwfDELMAkGA1UEBhMCQ04xETAPBgNVBAgMCFNoYW5naGFpMREw\n" +
"DwYDVQQHDAhTaGFuZ2hhaTENMAsGA1UECgwERW5PUzERMA8GA1UEAwwITVJtSXl6\n" +
"UFcxDTALBgNVBAsMBEVuT1MxFjAUBgkqhkiG9w0BCQEWBzREbmIxVDEwggEiMA0G\n" +
"CSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC+dU5jLAu7Kb88hONou6PycTnv9+3/\n" +
"FFPaHm5I8vPfhh0QL6TcunKpm97Dyds1yHgMCqVT+gWgO4MHFz8TiIb9JKRjHn/6\n" +
"kFea1ccZU9nYGuv+yMGqa340NjN/vP+XpjXm6Xkqw7ujehhNoBuKJZh6+uXlf2yw\n" +
"1gTP9vWJTc7cuiky2jgKl6/47iKEmIMT1xpHVDp16LWX08/aamJESPJ171RFFxf/\n" +
"6z2taiK/z7McXFRHk+SdYGN0iTNZQqoFKi3S9S8FvkLBQF8gHOytZdpnSz6SZwW0\n" +
"DJUv8VGFWQYOVU67BzVR59s0CVM9IdAHntjXm2t3BF0A9kKZa6VDzHpxAgMBAAGg\n" +
"ADANBgkqhkiG9w0BAQsFAAOCAQEASGPYV0t4zPT3XA42SKqNzNEiYvB550/6Vh1y\n" +
"mxD+mQXeyvkZn5OcxtuzrgD7aBVRcT/j+tK4XP8s+ODYiM+VSrqLs+a5ZGmOhHHf\n" +
"36MdmAK8I/dNyHZBiTf+GI5ibul2vaSpYYUwarzMu0azT6+d2qiUl7TqVVIGo4+P\n" +
"PSRp+V+9e4RJ/TKUjAToBazz154tXU5psVmQ1Ac9oF7Y/9AvGTtusLUDHCu3T45J\n" +
"QiwAUsMkSla5HCZEftNV8uC+BR6GktfFGLv3Gx+havoBsi82OPDUbBBtKgbiIQyq\n" +
"bslaLc4GkDZTZPz4st7/ChYOZVJNxz2CAx1JU4VAfjonqChzbw==\n" +
"-----END NEW CERTIFICATE REQUEST-----";
Integer certSn = 2667;
RenewCertificateRequest request = new RenewCertificateRequest();
request.setCertSn(certSn);
request.setCsr(newCert);
//validDay表示证书有效期，为可选项，如不包含该参数，则使用环境默认的有效期。
request.setValidDay(220);
/*
* 使用以下任意一个参数或参数组合以指定设备：
* ASSET_ID
* PRODUCT_KEY + DEVICE_KEY
*/
request.setAssetId(ASSET_ID);
request.setProductKey(PRODUCT_KEY);
request.setDeviceKey(DEVICE_KEY);
request.setOrgId(orgId);
RenewCertificateResponse certRsp = Poseidon.config(PConfig.init().appKey(appKey).appSecret(appSecret).debug())
.url(serverUrl)
.getResponse(request, RenewCertificateResponse.class);
System.out.println(certRsp.getData());
}
}