Skip to main content
Documentation Hub

Claiming

About

In the context of ESP RainMaker, "Claiming" refers to the process by which a chip that supports ESP RainMaker obtains an X.509 certificate from the Claiming Service to securely communicate with the ESP RainMaker cloud. This certificate is essential for establishing a mutually authenticated TLS connection over MQTT, ensuring that only authorized devices can connect. The Claiming Service issues the certificate based on the device's unique identity (such as its MAC address and platform type), and different claiming methods (Host Driven Claiming, Assisted Claiming, Self Claiming) facilitate this process depending on the device and setup.

context
  • The MQTT communication between a node and the ESP RainMaker service uses X.509 certificates based mutually authenticated TLS connection.
  • Claiming happens when the device connects to the ESP RainMaker cloud for the first time.
  • All communication with the Claiming Service happens through HTTP REST APIs. Please refer the Claiming API documentation for details.

Types of Claiming methods​

ESP RainMaker supports three claiming methods to securely fetch cloud credentials:

  1. Host Driven Claiming

    • For all ESP32 series variants
    • The only method of claiming in Private RainMaker Deployment.
    • Credentials are provisioned using the ESP RainMaker CLI in Public RainMaker and Admin CLI in Private RainMaker.

  2. Assisted Claiming (Used for Public RainMaker)

    • For all ESP32 series and default claiming method for ESP32.
    • Mobile app assists the device via Bluetooth LE to obtain cloud credentials during provisioning.

  3. Self Claiming (Used for Public RainMaker)

    • Only available for ESP32-C3, ESP32-S3, and ESP32-S2.
    • Device fetches credentials directly from the Claiming Service using a secret key in eFuse.

Host Driven Claiming (Public/Private RainMaker)​

If you are using Public RainMaker

It is recommended to use Self or Assisted Claiming when evaluating or testing Public RainMaker.

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.

Claiming workflow

The following steps details how host-driven claiming is done on ESP RainMaker CLI (esp-rainmaker/cli):

  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.

Configure region

There are region difference when it comes to RainMaker cli in the Global vs China region.
Click here to set region and login/signup.

"Claim" your board by executing the below.

reminder

Please exit idf.py monitor before proceeding.

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

Notes

  • The CLI reads the MAC address from the board directly, creates an NVS partition image, and flashes to 0x340000 address by default. Please specify the address using --addr if your fctry partition address is different.

  • 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.

host-driven

Assisted Claiming (Public RainMaker only)​

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 SDK from GitHub, with Assisted Claiming and Bluetooth LE provisioning enabled from menuconfig.

Follow these steps to enable Assisted Claiming in menuconfig

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

Self Claiming (Public RainMaker only)​

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.

Claiming Workflow
  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.

host-driven

On this page