Security & Pairing Protocol
Relevant source files
The following files were used as context for generating this wiki page:
The Security and Pairing Protocol establishes an encrypted and authenticated communication channel between a Muse gadget (ESP32 or Linux-based) and the Muse mobile application. The protocol utilizes Bluetooth Low Energy (BLE) as the primary transport for the initial handshake and exchange of cryptographic credentials.
The protocol implements a custom "Community Pairing v5" suite, which relies on standard cryptographic primitives including P-256 Elliptic Curve Diffie-Hellman (ECDH), HKDF-SHA256 for key derivation, and AES-256-GCM for authenticated encryption of session data.
Sources: linux/AGENTS.md:38-38, esp32/main/pairing_transcript.h:21-23
Cryptographic Suite Specifications
The protocol identifies its cryptographic operations under a specific suite name and uses defined constants for cross-platform compatibility.
| Parameter | Value | Description |
|---|---|---|
| Version | 5 | Current protocol version for pairing. |
| Model | hatch_link | Device model identifier used in transcripts. |
| Cipher Suite | p256-hkdf-sha256-aes-gcm-v1 | Combined cryptographic algorithm stack. |
| Auth Mode | fleet_ecdsa_p256_v1 | Official manufacturer authentication mode. |
| Community Auth | none | Authentication mode for community devices. |
Sources: esp32/main/pairing_transcript.h:21-27
Pairing Handshake Flow
The handshake transitions the device through several states, moving from an idle state to a fully provisioned and secure state. It involves a "Client Hello" from the mobile app, key exchange, transcript verification, and user confirmation.
Handshake Sequence
The following sequence diagram illustrates the communication between the Mobile Application and the Gadget (Responder).
Transcript Construction
A central part of the security handshake is the pairing_transcript. Both parties construct a string containing all session parameters to ensure no man-in-the-middle has tampered with the plaintext exchange.
The transcript includes:
- Protocol version and role identifiers.
device_id,node_id, andmacaddress.firmware_versionandmodel.- Public keys (
mobile_pub,device_pub) and nonces (mobile_nonce,device_nonce). - The selected authentication policy and epoch.
Sources: esp32/main/pairing_transcript.c:26-45
Authentication Policies
The protocol supports different levels of security based on device capabilities and the chosen authentication path.
- confirm_press: Requires the user to physically press a button on the gadget to authorize the pairing. This triggers a timeout (default 60 seconds).
- confirm_app: Used primarily on devices without physical buttons (like some Linux setups). The mobile app's confirmation is used to finalize the bond.
- Manufacturer Attestation: Official devices use
fleet_ecdsa_p256_v1and sign the transcript hash using a protected key stored in eFuse. - Community Mode: Uses
nonefor authentication and an epoch of 0. It does not require a hardware-backed signature.
Sources: esp32/main/pairing_transcript.h:24-28, esp32/main/link_pairing.c:420-449
Session Security (AES-GCM)
Once paired, all subsequent BLE communication is encrypted using AES-256-GCM. The protocol uses two separate 32-byte keys derived from the shared ECDH secret:
- RX Key: Used for messages from the mobile app to the device.
- TX Key: Used for messages from the device to the mobile app.
Authenticated Additional Data (AAD)
To prevent replay attacks, every encrypted envelope includes AAD composed of the session ID, direction (e.g., d2m or m2d), and a strictly incrementing counter.
BLE Interface Security
On ESP32 devices using the NimBLE stack, the muse_ble module enforces security at the GATT level.
- Encryption Requirements: The
STATUSandCMDcharacteristics are flagged withBLE_GATT_CHR_F_READ_ENCandBLE_GATT_CHR_F_WRITE_ENC. - Authentication Requirements: Access to these characteristics requires an authenticated link (
BLE_GATT_CHR_F_READ_AUTHEN). - Pairing Mechanism: The gadget uses
BLE_SM_IO_CAP_DISP_ONLY, generating a 6-digit passkey displayed on the device screen (if applicable) for the user to enter into the mobile app. - Bonding: The protocol supports bonding (
ble_hs_cfg.sm_bonding = 1), allowing the gadget and phone to remember the secure relationship across reconnections.
Sources: esp32/components/muse/muse_ble.c:226-258, esp32/components/muse/muse_ble.c:266-274
Summary of State Management
The gadget maintains a strict state machine to prevent unauthorized provisioning or command execution.
| State | Description |
|---|---|
PAIRING_IDLE | No active session; ready for Hello. |
PAIRING_WAIT_CLIENT_FINISHED | Hello received; keys derived; waiting for client finished message. |
PAIRING_CONFIRM_REQUIRED | Encrypted channel established; waiting for user button press. |
PAIRING_READY | User confirmed; secure session active. |
PAIRING_PROVISIONING | Securely receiving Wi-Fi and account credentials. |
Sources: esp32/main/link_pairing.c:60-66
The Security & Pairing Protocol ensures that even on community hardware, the gadget establishes a trust relationship with the Muse platform, protecting user credentials and providing a secure foundation for remote command execution.