跳至主要內容

设备证书

约 2212 字大约 7 分钟

设备证书

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

普通证书

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

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

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

获取证书

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

一机一密

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

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

一型一密

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

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

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

设备如何动态获取证书?

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

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

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

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

提示

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

如何生成设备唯一标识?

不同于 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

NameValue
Project-KeyProjectKey
Content-Typeapplication/json

以上的 <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 错误码说明如下:

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

X.509 证书

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

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

安全芯片

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

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

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