跳到主要内容

Claiming

提示

在 ESP RainMaker 的语境中，Claiming 指的是支持 ESP RainMaker 的芯片通过 Claiming 服务获取 X.509 证书，从而与 ESP RainMaker 云端进行安全通信。对于通过 MQTT 建立相互认证的 TLS 连接，X.509 证书帮助确保只有授权设备可以建立连接。Claiming 服务根据设备的唯一身份（如 MAC 地址和平台类型）颁发证书。针对不同设备和配置，Claiming 的方式（主机 Claiming、协助 Claiming、自身 Claiming）也会有所不同。

说明
  • 节点与 ESP RainMaker 服务之间的 MQTT 通信使用的是基于相互认证的 TLS 连接的 X.509 证书。
  • Claiming 发生于设备首次连接 ESP RainMaker 云时。
  • 所有与 Claiming 服务的通信均通过 HTTP REST API 进行。请参考 Claiming API 文档了解详情。

Claiming 方式​

ESP RainMaker 支持三种安全获取云凭证的 Claiming 方式：

  1. 主机 Claiming

    • 适用于所有 ESP32 系列芯片。
    • 私有 RainMaker 部署中唯一支持的 Claiming 方式。
    • 通过 ESP RainMaker CLI 在公有 RainMaker 中配置凭证，通过 Admin CLI 在私有 RainMaker 中进行配置。

  2. 协助 Claiming (仅适用于公有 RainMaker)

    • 适用于所有 ESP32 系列芯片，是 ESP32 系列芯片的默认 Claiming 方式。
    • 移动应用通过 BLE 协助设备在配置过程中获取云凭证。

  3. 自身 Claiming (仅适用于公有 RainMaker)

    • 仅适用于 ESP32-C3、ESP32-S3 和 ESP32-S2。
    • 设备通过 eFuse 密钥直接从 Claiming 服务获取凭证。

主机 Claiming（公有/私有 RainMaker）​

使用公有 RainMaker 时

建议在评估或测试公有 RainMaker 时使用自身 Claiming 或协助 Claiming。

顾名思义，主机 Claiming 由开发主机驱动，适用于所有 ESP32 系列芯片。主机 Claiming 通常仅在需要创建工厂二进制文件时使用，这些文件可能包含 RainMaker 所需数据之外的自定义数据。此外，主机 Claiming 可用于测试与私有 RainMaker 部署类似的设备配置。

Claiming 流程

以下步骤详细说明如何使用 ESP RainMaker CLI (esp-rainmaker/cli) 进行主机 Claiming：

  1. 从主机登录 ESP RainMaker。
  2. 生成 RSA2048 客户端密钥。
  3. 向 Claiming 服务发送包含 MAC 地址和平台的初始化 Claim 请求。
  4. 接收唯一的 node_id。
  5. 使用 CN=node_id 生成 CSR，并通过 Claim 验证请求发送。
  6. 如果 Claim 验证通过，从 Claiming 服务获取客户端证书。
使用方式

请确保按照步骤设置 ESP RainMaker CLI。

配置区域

RainMaker CLI 在全球其他区域与在中国区域存在差异。
点击此处设置区域并登录/注册。

通过以下命令 "Claim" 开发板。

提醒

进行后续操作前，请先退出 idf.py monitor。

$ esp-rainmaker-cli claim $ESPPORT --addr <fctry_partition_address>

注意

  • CLI 直接从开发板读取 MAC 地址，创建 NVS 分区镜像，并默认烧录到地址 0x340000。如果 fctry 分区地址不同，请使用 --addr 指定地址。

  • Claim 数据保存在 ~/.espressif/rainmaker/claim_data/。如果该路径已存在给定 MAC 地址的 Claim 数据，则会直接使用，而无需从 Claiming 服务获取。

  • 对于某一特定用户，Claiming 服务始终会为同一 MAC 地址返回相同的 node_id。

host-driven

协助 Claiming（仅适用于公有 RainMaker）​

协助 Claiming 由移动应用驱动，适用于所有支持 BLE 平台，但仅在 ESP32 中为默认 Claiming 方式。协助 Claiming 基于主机 Claiming API 构建，不同之处在于，协助 Claiming 的实际负载由设备生成和解析，而非由主机生成，因此设置步骤不同于主机 Claiming。只需确保你有最新的移动应用和 GitHub 上的最新 esp-rainmaker SDK，并在 menuconfig 中启用 BLE 配置和协助 Claiming。

按照以下步骤在 menuconfig 中启用协助 Claiming：

启用上述功能后，若设备尚无云连接凭证，配置过程中会通知移动应用进行 Claiming。移动应用随后代表设备与云端交换数据，获取云凭证。由于移动应用仅协助设备获取凭证，因此该过程称为“协助 Claiming”。具体流程如下：

host-driven

自身 Claiming（仅适用于公有 RainMaker）​

自身 Claiming 仅适用于在 eFuse 中烧写了密钥的平台，这意味着自身 Claiming 适用于 ESP32-S2、ESP32-C3 和 ESP32-S3。

在自身 Claiming 流程中，固件在连接到互联网后自行从 Claiming 服务获取凭证。在所有支持自身 Claiming 的平台上，自身 Claiming 为默认 Claiming 方式。

Claiming 流程
  1. 生成 RSA2048 客户端密钥。
  2. 向 Claiming 服务发送包含 MAC 地址和芯片平台（esp32s2、esp32c3 或 esp32s3）的初始化 Claim 请求。
  3. 从 Claiming 服务获取挑战值 (challenge) 和随机生成的唯一 auth_id。
  4. 使用芯片制造过程中烧写到 eFuse 中的密钥生成 HMAC512 响应。
  5. 将唯一的 auth_id、挑战值响应和证书签名请求（CSR，node_id 为通用名称 [Common Name, CN]）发送到 Claiming 服务。
  6. 如果响应与 Claiming 服务生成的响应匹配，将返回客户端证书。
  7. 使用客户端密钥和证书连接到 ESP RainMaker MQTT 服务。
  8. 这些字段会被长期储存，后续启动时仍可使用。

host-driven

On this page