V2.0 Apply Certificate¶

申请证书并绑定证书到指定的设备上，你可以对所申请的证书的有效期做设置。

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

操作权限¶

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

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

前提条件¶

该设备存在。
该设备所属产品支持双向认证。

请求格式¶

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

请求参数 (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）>>
validDay	可选	Integer	证书的有效期。单位为天。如果不在请求中包含该参数，则使用期默认值：730。该参数的值（包括其默认值）适用的规则见下文。
issueAuthority	可选	String	EnOS 颁发证书的加密算法。如果不传该参数，则采用默认值，RSA。该参数的规则见下文。

validDay 适用规则¶

validDay 遵循以下规则：

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

issueAuthority 适用规则¶

issueAuthority遵循以下规则：

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

issueAuthority 取值说明¶

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

响应参数¶

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

DeviceCertApplyResultInfo 结构体¶

名称	数据类型	描述
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 csr:csr is missing	CSR参数缺少。	在请求中传入正确的CSR参数。
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	Duplicate subject by certificate request!message: (message content), detail message: (detailed message content)	请求证书主体重复。	详细错误信息原因由message或 detail message给出。
99400	Revoke cert is failed!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给出。
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: http://{apigw-address}/connect-service/v2.0/certificates?assetId=YourDeviceAssetId&action=apply&orgId=yourOrgId
method: POST
requestBody:
{
    "csr": "-----BEGIN NEW CERTIFICATE REQUEST-----\nMIICpzCCAY8CAQAwYjELMAkGA1UEBhMCQ04xETAPBgNVBAgTCFNoYW5naGFpMREw\nDwYDVQQHEwhTaGFuZ2hhaTENMAsGA1UEChMERW5PUzENMAsGA1UECxMERW5PUzEP\nMA0GA1UEAxMGMjVTWkFsMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA\njWydoAdwoJcpvpNLr1zrsUHUXPCOLwl7jDZsBCWo8aEVv8tn4qI1VG4pqn5nqYzG\n40aoAFz1MBGxPIpjGHWbQfAaRgUlEf352ql6cpP/T1Qm6f8CjECY8vFbl4ABwOye\ncCjZJ7KIXHPF81OWOi2+JDsjDVOp747zuDpNwxkI3lIre3cj9zTa6/L+mAO34W/5\nGyHPTZ3wl7x2eFQMNXnccRoCzeXGOmk0+Cikdr5ERkZogLzW1h6JO2Gm6hAFhxjf\nuKVolAgdkjjiNoN4TTaHH4o+JNBzsV8UR4amtaFo0a+NXjZgwr2V9IMjtjkV6YIe\nHhFRLg5EpJmd4KEOUazwbwIDAQABoAAwDQYJKoZIhvcNAQELBQADggEBAIm5PAnG\ny0AIxDCB0cttTnxmOP8uquva4wnl3ZbX3cNWudzZXXHjCwYRXBhDWHJ1qM8yV1mN\nTJ1irW6Ebwq3kSqW4moJk161gKvspJuHlZhr+8eH0t/z1yLHD4sdf1XAqZ8CtIaG\nZpaOnYmp4bBu/SpfPi+S4VBU48KIc86yBtfQ1GpZiwBTpjiDTG1tyIJe2Vtd26WE\nc2LwBn9zRaFwQQ6AKCdzjGejXcWgXxRgHmxaN1zx3l4xKWR4ZAoON9Hx26RWG7zt\nQlQreoVD/FiERI81OijqrrX0LLAx4CpHVEGhrNykRAdWph47Z5vkNnfaIu2T9HWI\nsYYM5JVl66v3x7I=\n-----END NEW CERTIFICATE REQUEST-----\n",
    "validDay": 250,
    "issueAuthority": "RSA"
}

返回示例¶

{
    "code": 0,
    "msg": "OK",
    "requestId": "6f0c1c93-08f9-404c-a403-b49cbdab2938",
    "data": {
        "certChainURL": "https://{domain-name}/enos/CA/cacert",
        "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-----\nMIIEtTCCA52gAwIBAgICf9AwDQYJKoZIhvcNAQELBQAwgYIxCzAJBgNVBAYTAkNO\nMREwDwYDVQQIDAhTaGFuZ2hhaTERMA8GA1UEBwwIU2hhbmdoYWkxDTALBgNVBAoM\nBEVuT1MxEDAOBgNVBAsMB0VuT1MgQ0ExEDAOBgNVBAMMB0VuT1MgQ0ExGjAYBgkq\nhkiG9w0BCQEWC2NhQGVuaW90LmlvMB4XDTIwMDEwNjEwNDYzM1oXDTIwMDkxMjEw\nNDYzM1owYjELMAkGA1UEBhMCQ04xETAPBgNVBAgTCFNoYW5naGFpMREwDwYDVQQH\nEwhTaGFuZ2hhaTENMAsGA1UEChMERW5PUzENMAsGA1UECxMERW5PUzEPMA0GA1UE\nAxMGMjVTWkFsMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAjWydoAdw\noJcpvpNLr1zrsUHUXPCOLwl7jDZsBCWo8aEVv8tn4qI1VG4pqn5nqYzG40aoAFz1\nMBGxPIpjGHWbQfAaRgUlEf352ql6cpP/T1Qm6f8CjECY8vFbl4ABwOyecCjZJ7KI\nXHPF81OWOi2+JDsjDVOp747zuDpNwxkI3lIre3cj9zTa6/L+mAO34W/5GyHPTZ3w\nl7x2eFQMNXnccRoCzeXGOmk0+Cikdr5ERkZogLzW1h6JO2Gm6hAFhxjfuKVolAgd\nkjjiNoN4TTaHH4o+JNBzsV8UR4amtaFo0a+NXjZgwr2V9IMjtjkV6YIeHhFRLg5E\npJmd4KEOUazwbwIDAQABo4IBUjCCAU4wCQYDVR0TBAIwADAnBglghkgBhvhCAQ0E\nGkVub3MgR2VuZXJhdGVkIENlcnRpZmljYXRlMB0GA1UdDgQWBBRGmiiFkKBySldM\nc8qtiBeXWLtYTDCBtwYDVR0jBIGvMIGsgBSDY8yN93q5kRUb4eaFZh9U24GHGqGB\niKSBhTCBgjELMAkGA1UEBhMCQ04xETAPBgNVBAgMCFNoYW5naGFpMREwDwYDVQQH\nDAhTaGFuZ2hhaTENMAsGA1UECgwERW5PUzEQMA4GA1UECwwHRW5PUyBDQTEQMA4G\nA1UEAwwHRW5PUyBDQTEaMBgGCSqGSIb3DQEJARYLY2FAZW5pb3QuaW+CCQCtwrkl\ngEPzyDA/BglghkgBhvhCAQQEMmh0dHBzOi8vYWxwaGEtcG9ydGFsLWNuNC5lbmlv\ndC5pbzo4MDgxL2Vub3MvQ0EvY3JsMA0GCSqGSIb3DQEBCwUAA4IBAQAeunPZdxzS\nksI1iEr5eG6BVF96dahGtKdNwd8bZqkF0hfZ2OTaXX019lQHpE/KU0wRBSpNXMfq\nwtUlmK4dAzUVhWdW48gNv3jSrdxj2iwK27j7DyMpNup+mKI2AR9AMjhPzVnHXt9M\nNEK7BxTqsPs+I6gFSLr9fUV7kozROm5jEVvvLrEvX68LKvyXAqkYTtPHZlR4oj/v\nDgZwXfE9rFEi9OFYYl0Xm4lSH3HhTh9vxgq08mGtyoUiGi8h6Uy79Slwk40oblE5\n1sV1o+31MDpzQTca1aAsL/g3XL6aLUFziMHzkn5peHuf+njN0tNupNn2CLK1cl2n\nBr9WJ55OFglM\n-----END CERTIFICATE-----\n",
        "certSN": "32720",
        "issueAuthority": "RSA"
    }
}

SDK 示例¶

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

Java
Python