# Authenticated raw TCP pairing This example combines application-owned Wi-Fi with ESP-Iris challenge-HMAC authentication. A per-device token is provisioned into NVS; each new link proves possession using a fresh challenge without transmitting the token. ## Standalone setup Create this example from the Component Registry, then run the commands below from its directory: ```bash idf.py create-project-from-example "espressif/esp_iris=0.2.0:tcp_pairing" cd tcp_pairing ``` With a source checkout, change to `ESP-Iris/components/esp_iris/examples/tcp_pairing` from the repository root instead. The checked default target is ESP32-S31 with the pinned IDF 6.2 revision. The application owns Wi-Fi credentials and network initialization. After the first build downloads the component, prepare its bundled Gateway: ```bash python esp_iris.py setup python esp_iris.py doctor python esp_iris.py web ``` The launcher uses an isolated cached environment and does not change the IDF Python environment. Close the Gateway before flashing or monitoring its ports. ## Configure private values Create `sdkconfig.local.defaults` in this directory: ```text CONFIG_ESP_IRIS_EXAMPLE_WIFI_SSID="your-ssid" CONFIG_ESP_IRIS_EXAMPLE_WIFI_PASSWORD="your-password" CONFIG_ESP_IRIS_EXAMPLE_PAIRING_TOKEN="64-lowercase-hex-characters" ``` Generate the token with a password manager or another cryptographically secure secret generator. Store the same value in the Gateway's private device-token store. Never commit or log it. The configured token is installed only when ESP-Iris has no token in NVS. Later boots preserve the stored value so `esp_iris_pairing_token_rotate()` remains effective. Reprovision or erase NVS only when intentionally replacing the device identity material. After Iris starts, the example verifies `esp_iris_pairing_token_get()` and immediately wipes its temporary buffer. It also provides `iris_example_provisioning_rotate_token()` as an integration skeleton for a product-owned secure provisioning surface. The skeleton is intentionally not connected to an Iris RPC and never logs the returned token. A product calling it must deliver the replacement out-of-band and wipe the caller-owned buffer. ## Build and flash ```bash idf.py \ -B build-tcp-pairing build idf.py \ -B build-tcp-pairing \ -p /dev/serial/by-id/<programming-port> flash ``` ## Expected result The device logs only its assigned address and TCP port. A Gateway configured with the matching token connects successfully; a missing or incorrect proof is rejected after `CONFIG_ESP_IRIS_AUTH_FAILURE_DELAY_MS`. Return to the [example index](../README.md).
To create a project from this example, run:
idf.py create-project-from-example "espressif/esp_iris=0.2.0:tcp_pairing"