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 ESP32 chip gets 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 viz. 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.

self-claim

  1. Generate an RSA2048 Client key.
  2. Send an Init Claim request to the Claiming Service with the mac address and platform (esp32s2, esp32c3, esp32s3) in the payload.
  3. Get a challenge from the Claiming Service and a randomly generated unique auth_id.
  4. Using the Secret key programmed in efuse during chip manufacturing, generate a response using 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, get a client certificate in response.
  7. Use the client key and certificate to connect to the ESP RainMaker MQTT service.
  8. These are stored in persistent storage so that the same can be used in subsequent boots

Assisted Claiming

Assisted Claiming is driven via the phone apps and can be used by all platforms that support BLE, 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 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 phone apps and the latest esp-rainmaker code from GitHub, with Assisted Claiming and BLE 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 (BLE)

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

self-claim

Host Driven Claiming

Note: Recommended to use Self/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.

host-claim

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 Verify request.
  6. Get a client certificate from the Claiming Service if the Claim Verify request is successful.

Usage

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

Note: 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 and at the end, 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.
← User - Node MappingUser Roles →