设备证书

设备证书是由 ZhiLian.Yun 颁发给设备的一组密钥，用于设备连接平台时进行身份验证。根据不同的安全级别需求，ZhiLian.Yun 提供多种类型的设备证书。

普通证书

普通证书包含 ProjectKey 和 AccessToken，设备在连接平台时需要使用这两个密钥完成身份验证。

每个设备在创建后会自动生成唯一的 AccessToken，而 ProjectKey 对项目下的所有设备是相同的。

普通证书适用于大多数的物联网场景和快速原型开发，具有普通的安全级别。

获取证书

通常来说，设备可采用以下两种方式获取设备证书：

一机一密

这种方式需要您在控制台为每个设备获取 AccessToken 和 ProjectKey，通过烧录固件或使用设备配置软件，固化到设备中。

所以，在每个物理设备中，都需要保存不同的 AccessToken，所以称为一机一密。

一型一密

然而，对于量产的设备，我们不可能为每个设备单独烧录证书，需要一种更高效的方式。

这就需要采用设备动态获取证书的方式，即只为设备烧录相同的 ProjectKey，设备上电后通过 HTTP 请求平台的接口，动态获取 AccessToken。这样一来，同一设备类型下的所有设备，只需烧录同一个固件，所以称为一型一密。

在这种方式下，ZhiLian.Yun 为设备提供了 证书获取 API，设备开机后调用 API 获取设备证书，然后再使用设备证书连接云平台。

设备如何动态获取证书？

对于量产及交付客户的设备，通常使用动态获取证书的方式，即实现一型一密。

我们已经知道，设备证书中包含 AccessToken 和 ProjectKey，其中 AccessToken 在每个设备中是不同的，而 ProjectKey 在同一个项目下所有设备中是相同的。

使用设备动态获取证书的方式，不需要在固件代码中写入设备的 AccessToken，而是设备每次开机后，使用设备自有的 设备唯一标识（DeviceKey），通过云平台提供的 动态获取证书 API，获取 AccessToken，然后通过 MQTT 连接云平台。

整个过程的时序原理图大致如下。其中提到的自动创建新设备，在下边的内容中会有详细介绍。

设备动态获得 AccessToken 后，不建议保存在设备的 ROM/Flash 中供后续直接使用。因为考虑到安全性，云平台对设备提供重置 AccessToken 的可能性，以降低证书泄露的风险，故确保设备端获取到最新的证书。

如何生成设备唯一标识？

不同于 AccessToken 由云平台生成，设备唯一标识 则由设备自行生成，只需确保满足以下条件：

唯一性：在同一个项目下的所有设备中保持唯一即可。 永久性：设备可永久获得该标识，不会发生变化。 在实践中，通常采用以下方式：

3G/4G/NBIoT 等蜂窝网络模组，可使用模组的 IMEI 作为设备唯一标识。 WiFi 模组和以太网卡，可使用芯片 ID 或 MAC 地址。 其它模组可使用任何生成唯一 ID的算法。

使用设备唯一标识

使用动态获取证书的设备，在云平台的设备信息中，需要有对应的设备唯一标识（DeviceKey），用于云平台识别设备并下发证书。

在使用中，分为以下两种情况：

预先创建设备，在设备信息中填写对应的设备唯一标识，和证书获取 API 中的 deviceKey 保持一致。在创建设备或编辑设备信息时，可设置设备唯一标识，必须在同一个项目的所有设备中保持唯一。

设备证书获取 HTTP API

设备通过该接口动态获取 accessToken 和 deviceCode，实现一型一密接入。支持 GET 和 POST 两种请求方式。

Request Syntax

POST /device/v1/certificate HTTP/1.1
Project-Key: <ProjectKey>
Content-Type: application/json

{
  "deviceKey": "DEVICE_KEY",
  "typeKey": "TYPE_KEY",
  "productKey": "PRODUCT_KEY",
  "projectKey": "PROJECT_KEY",
  "data": {
    "key1": "value1",
    "key2": "value2"
  }
}

或使用 GET 方式，将参数放在 URL 查询字符串中：

GET /device/v1/certificate?deviceKey=DEVICE_KEY&typeKey=TYPE_KEY HTTP/1.1
Project-Key: <ProjectKey>

Request Body / Query Parameters

字段	类型	必填	说明
deviceKey	string	是	设备端唯一标识。由设备端生成，应确保在一个项目中的唯一性。通常使用芯片内置的唯一标识，例如模组的 IMEI、MAC、UUID 等
typeKey	string	否	平台端设备类型标识。当使用该字段时，如果设备 deviceKey 不存在，平台会自动创建新设备并关联到该设备类型
productKey	string	否	设备端产品识别码。与 typeKey 二选一，平台会在项目中自动查找或创建对应的设备类型
projectKey	string	否	项目密钥。也可通过 Project-Key 请求头传递
data	object	否	设备端附加数据，键值均为字符串

TIP

typeKey 和 productKey 必须填写其中一项，才能实现设备自动注册。

Response Syntax

HTTP/1.1 200 OK
Content-type: application/json

{
  "code": 200,
  "message": "Device found",
  "data": {
    "id": "DEVICE_ID",
    "name": "DEVICE_NAME",
    "deviceCode": "deviceCode",
    "accessToken": "accessToken"
  }
}

Response Body

字段	类型	说明
id	string	设备 ID
name	string	设备名称
deviceCode	string	设备编码，后续接口中会用到
accessToken	string	设备访问令牌，用于数据上报和 MQTT 连接

cURL 示例

curl -X POST "https://<endpoint>/device/v1/certificate" \
  -H "Project-Key: <ProjectKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceKey": "DEVICE_KEY",
    "typeKey": "TYPE_KEY"
  }'

如何自动创建设备？

在实际项目中，当有大量设备接入时，我们可以不用在控制台预先创建每个设备，而是使用设备自动创建功能。

要实现设备自动创建，同样使用上边的设备证书获取 API，在请求正文 JSON 中增加以下字段：

typeKey：设备类型标识 TypeKey。当使用该字段时，如果设备 deviceKey 不存在，平台则会自动创建新设备，并关联到该设备类型。 例如：

{
  "deviceKey": "DEVICE_KEY",
  "typeKey": "TYPE_KEY"
}

typeKey 的获取方式很简单，进入设备类型的 设置 > 自动创建设备，复制这里的 TypeKey。如下图：

同时要开启允许设备自动创建，这时设备自动注册功能正式启用。

当设备成功创建后，API 返回信息如下：

{
  "code": 200,
  "message": "Device created",
  "data": {
    "id": "DEVICE_ID",
    "name": "DEVICE_NAME",
    "deviceCode": "DEVICE_CODE",
    "accessToken": "ACCESS_TOKEN"
  }
}

当使用设备自动注册时，请确保您的项目中有足够的设备数量配额，如果配额达到上限，新设备将无法自动注册。

使用产品识别码

以上我们通过设备类型的 TypeKey ，实现了自动创建设备。但这种方式只能将新设备创建在固定的设备类型下，如果您希望客户或合作伙伴拿到设备，可以部署到自己的项目中，就需要您对固件进行修改，或者让客户配置新的 TypeKey，这显然给客户带来不好的体验。

更好的方式是，通过使用 产品识别码，您不需要为设备指定具体的设备类型 TypeKey，平台会在项目中自动查找该产品识别码对应的设备类型，或自动创建新的设备类型。

同样使用上边的设备证书获取 API，在请求正文 JSON 中增加以下字段：

productKey：产品识别码。 例如：

{
  "deviceKey": "DEVICE_KEY",
  "productKey": "PRODUCT_KEY"
}

当设备成功创建后，API 返回信息如下：

{
  "code": 200,
  "message": "Device created",
  "data": {
    "id": "DEVICE_ID",
    "name": "DEVICE_NAME",
    "deviceCode": "DEVICE_CODE",
    "accessToken": "ACCESS_TOKEN"
  }
}

HTTP 响应错误码

动态获取证书 HTTP API 失败时，响应消息中的 code 错误码说明如下：

code	说明
435	未指定 projectKey
434	未指定 deviceKey
400	项目不存在
401	设备不存在
417	设备类型不存在
431	设备类型创建失败
436	产品识别码不存在
432	设备类型不允许自动创建设备
433	设备类型不是直连设备或网关，无法创建设备
437	设备数量已达到上限，无法创建设备
411	创建设备失败

X.509 证书

在一些对通信安全要求严格的物联网领域，比如智能门锁、电力控制等，您可以使用基于 X.509 TLS 的 MQTT 安全认证方式。

目前 ZhiLian.Yun 在专有区和私有区中支持该认证方式。

安全芯片

不论是哪种设备证书类型，考虑到设备固件代码或云平台用户账号等存在泄露的可能性，导致证书仍然有泄露的风险。

通过 SE 安全芯片可以实现设备端证书的独立加密存储，以及设备和云平台的双向认证，达到更高的安全级别。

ZhiLian.Yun 面向智能设备厂商和安全级别较高的物联网场景，联合加密芯片合作厂商，提供包括加密芯片和证书服务器在内的 SE 整体解决方案。