tcp_pairing

Example of the component espressif/esp_iris v0.2.0
# 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"

or download archive (~6.73 KB)