设备证书

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

普通证书

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

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

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

获取证书

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

一机一密

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

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

一型一密

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

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

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

设备如何动态获取证书？

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

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

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

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

如何生成设备唯一标识？

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

• 唯一性：在同一个项目下的所有设备中保持唯一即可。
• 永久性：设备可永久获得该标识，不会发生变化。

在实践中，通常采用以下方式：

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

使用设备唯一标识

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

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

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

• 不预先创建设备，当设备首次调用 证书获取 API 时，如果 device_key（设备唯一标识）不存在，云平台会自动创建新设备。这种方式也称为 设备自动注册。

设备证书获取 HTTP API

基本用法

HTTP URL

http://<endpoint>/device/v1/certificate

或

https://<endpoint>/device/v1/certificate

HTTP Header

以上的 <endpoint> 和 ProjectKey 可以在 设备详情页 > 连接 中找到。

HTTP 请求方法

POST

HTTP 请求正文

HTTP 正文部分使用 JSON 格式，字段如下：

• device_key： 设备唯一标识。由设备端生成，应确保在一个项目中的唯一性。通常使用芯片内置的唯一标识，例如：模组的 IMEI、MAC、UUID 等。

例如：

{
  "device_key": "DEVICE_KEY"
}

HTTP 响应

如果证书获取成功，响应消息如下：

{
  "result": 1,
  "message": "Device found",
  "device": {
   	"id": "DEVICE_ID",
    "name": "DEVICE_NAME",
    "access_token": "ACCESS_TOKEN"
  }
}

如果证书获取失败，响应消息如下:

{
  "result": 0,
  "message": "MESSAGE",
  "errcode": ERRCODE
}

如何自动创建设备？

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

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

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

例如：

{
  "device_key": "DEVICE_KEY",
  "type_key": "TYPE_KEY"
}

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

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

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

{
  "result": 1,
  "message": "Device created",
  "device": {
   	"id": "DEVICE_ID",
    "name": "DEVICE_NAME",
    "access_token": "ACCESS_TOKEN"
  }
}

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

使用产品识别码

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

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

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

• product_key：产品识别码。

例如：

{
  "device_key": "DEVICE_KEY",
  "product_key": "PRODUCT_KEY"
}

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

{
  "result": 1,
  "message": "Device created",
  "device": {
   	"id": "DEVICE_ID",
    "name": "DEVICE_NAME",
    "access_token": "ACCESS_TOKEN"
  }
}

HTTP 响应错误码

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

X.509 证书

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

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

安全芯片

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

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

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