Skip to main content

Claiming

The MQTT communication between a node and the ESP RainMaker service uses X.509 certificates based mutually authenticated TLS connection. In the context of ESP RainMaker, "Claiming" is the process by which the chips that support ESP RainMaker get this certificate from the ESP RainMaker Claiming Service (henceforth referred to as just "Claiming Service").

All communication with the Claiming Service happens through HTTP REST APIs. Please refer the Claiming API documentation for details.

Self Claiming​

Self Claiming is possible only on platforms that have a secret key programmed in the eFuse. That is to say, Self Claiming is available for ESP32-S2, ESP32-C3, and ESP32-S3.

In this process, the firmware itself fetches the credentials from the Claiming Service after connecting to the Internet. This is also the default for all the platforms that support this.

  1. Generate an RSA2048 client key.
  2. Send an Init Claim request to the Claiming Service with the MAC address and platform (esp32s2, esp32c3, or esp32s3) in the payload.
  3. Get a challenge from the Claiming Service and a randomly generated unique auth_id.
  4. Use the secret key programmed in eFuse during chip manufacturing to generate a response with HMAC512.
  5. Send the unique auth_id, the challenge response, and a Certificate Signing Request (CSR, with node_id embedded as the Common Name, CN) to the Claiming Service.
  6. If the response matches the one generated by the Claiming Service, a client certificate will be returned in the response.
  7. Use the client key and certificate to connect to the ESP RainMaker MQTT service.
  8. They are stored persistently so that the same can be used in subsequent boots.

Assisted Claiming​

Assisted Claiming is driven via mobile apps and can be used by all platforms that support Bluetooth LE, but is the default only for ESP32. It is built on top of the Host Driven Claiming APIs, with the difference being that the actual payloads for Assisted Claiming are generated and parsed by the device, instead of the host. No setup like that for Host Driven Claiming is required. Just ensure that you have the latest mobile apps and the latest esp-rainmaker code from GitHub, with Assisted Claiming and Bluetooth LE provisioning enabled from menuconfig.

  • idf.py menuconfig -> ESP RainMaker Config -> Use Assisted Claiming
  • idf.py menuconfig -> ESP RainMaker App Wi-Fi Provisioning -> Provisioning Transport Method (Bluetooth LE)

Once the above features are enabled, if the device does not have the cloud connectivity credentials, during provisioning, it will inform the mobile app about the need of Claiming. Thereafter, the mobile app will exchange data on behalf of the device to get the cloud credentials. Since the mobile app is just assisting the device to get the credentials, this has been called as "Assisted Claiming". The workflow is as below:

Host Driven Claiming​

Recommended to use Self or Assisted Claiming instead.

Host Driven Claiming, as the name suggests, is driven from your development host machine and can be used for all ESP32 variants. It is typically required only if you want to create fctry binaries, which may have some custom data in addition to that required by RainMaker. Moreover, it helps test devices with configuration similar to private RainMaker deployments.

The ESP RainMaker CLI (esp-rainmaker/cli) should be used for the Host Driven Claiming.

  1. Sign-in into the ESP RainMaker account from the host.
  2. Generate an RSA2048 client key.
  3. Send an Init Claim request to the Claiming Service with the MAC address and platform in the payload.
  4. Get a unique node_id in response.
  5. Generate a CSR with CN=node_id and send it in the Claim Verification request.
  6. Get a client certificate from the Claiming Service if the Claim is verified.

Usage​

Please ensure that the ESP RainMaker CLI is set-up using the steps here. "Claim" your board by executing the below.

Please exit idf.py monitor before this.

$ cd /path/to/esp-rainmaker/cli
$ ./rainmaker.py login
$ ./rainmaker.py claim $ESPPORT

Notes​

  • The CLI reads the MAC address from the board directly, creates an NVS partition image, and flashes to appropriate location in flash.
  • The Claim data is saved at the location ~/.espressif/rainmaker/claim_data/. So when you try Claiming again, if the Claim data for the given MAC address is already available here, it will be used directly instead of getting it from the Claiming Service.
  • The Claiming Service will always return the same node_id for the same MAC address for a given user.