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 (ESP32-S2 only)
In this process, the ESP32-S2 itself fetches the credentials from the Claiming Service after connecting to the Internet. This is also the default.
- Generate an RSA2048 Client key.
- Send an Init Claim request to the Claiming Service with the mac address and platform (esp32s2) in the payload.
- Get a challenge from the Claiming Service and a randomly generated unique auth_id.
- Using the Secret key programmed in efuse during chip manufacturing, generate a response using HMAC512.
- 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.
- If the response matches the one generated by the Claiming Service, get a client certificate in response.
- Use the client key and certificate to connect to the ESP RainMaker MQTT service.
- These are stored in persistent storage so that the same can be used in subsequent boots
Assisted Claiming (ESP32, ESP32C3 and ESP32S3)
A new type of claiming, called Assisted Claiming has been added, in order to make the claiming for ESP32 simpler. 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:
Host Driven Claiming (ESP32)
Note: Recommended to use Assisted Claiming Instead
Host driven claiming, as the name suggests, is driven from your development host machine. Since ESP32 does not have the secret key programmed in its efuse, this is useful for getting the credentials and using RainMaker on ESP32. This has been enabled by default for all ESP RainMaker accounts.
The ESP RainMaker CLI (esp-rainmaker/cli) should be used for the host driven claiming.
- Sign-in into the ESP RainMaker account from the Host.
- Generate an RSA2048 Client key.
- Send an Init Claim request to the Claiming Service with the mac address and platform in the payload.
- Get a unique node_id in response.
- Generate a CSR with CN=node_id and send it in the Claim Verify request.
- Get a client certificate from the Claiming Service if the Claim Verify request is successful.
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 monitorbefore this
cd /path/to/esp-rainmaker/cli ./rainmaker.py login ./rainmaker.py claim $ESPPORT
- 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.