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取值说明¶
RSA: 要求证书请求文件格式,必须是2048的RSA公钥且签名算法为SHA256withRSA。
ECC: 求证书请求文件格式,必须是256位的ECC公钥,公钥算法为prime256v1,且签名算法为SHA256WITHECDSA。
响应参数¶
名称 |
数据类型 |
描述 |
---|---|---|
data |
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 |
设备标识符无效 |
在请求中声明 |
99400 |
Invalid Argument certSn:certSn is missing |
缺少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. |
待更新证书的序列号是必需字段 |
在请求中声明 |
99400 |
Serial number of the new certificate is invalid (less than 0). |
传入的证书序列号无效(小于0) |
确保声明的 |
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());
}
}