sequenceDiagram participant P as ESP32-C3 (Peripheral) participant C as Phone (Central) Note over P,C: Connected (not yet encrypted) P->>C: Security Request (please encrypt) rect rgba(42,118,221,0.08) Note over P,C: Phase 1: exchange of capabilities C->>P: Pairing Request (IO capability, bonding, MITM, SC …) P->>C: Pairing Response (same) Note over P,C: The "method" is decided from both capabilities end rect rgba(214,96,77,0.08) Note over P,C: Phase 2: key generation Note over P: "Display" passkey 123456 Note over C: User enters the passkey P-->>C: Exchange public keys and confirmation values Note over P,C: LTK (long term key) is created end Note over P,C: Start encryption with the LTK rect rgba(44,160,44,0.08) Note over P,C: Phase 3: key distribution P-->>C: IRK, address, etc. C-->>P: IRK, address, etc. end Note over P,C: If bonding, store the keys
8 BLE security: pairing and bonding
Up to Step 4, anyone nearby can connect to the device, read data and send commands. Communication is not encrypted either, so with a dedicated receiver (sniffer) someone could snoop on the contents. In this chapter we sort out how BLE prevents this.
8.1 Three terms
| Term | Meaning |
|---|---|
| Pairing | The procedure by which two devices create (exchange) keys for encryption |
| Bonding | Storing the keys created by pairing so that subsequent connections can be encrypted without pairing |
| Encryption | Encrypting packets and detecting tampering with AES-CCM in the Link Layer. The keys are obtained via the two items above |
“I paired it, but the next time I connect it asks for the passkey again” happens because it did not bond (did not store the keys), or one side deleted its stored keys.
8.2 The pairing flow
Pairing is performed by the Security Manager (SM) and is divided into three phases.
8.2.1 Phase 1: exchange of capabilities
With the Pairing Request / Response, each side tells the other the following.
| Item | Details | NimBLE setting |
|---|---|---|
| IO Capability | Whether it can display / take input (table below) | ble_hs_cfg.sm_io_cap |
| Bonding | Whether to store keys | ble_hs_cfg.sm_bonding |
| MITM | Whether protection against man-in-the-middle attacks (authentication) is required | ble_hs_cfg.sm_mitm |
| SC | Whether LE Secure Connections is supported | ble_hs_cfg.sm_sc |
| Key distribution | What to send each other in Phase 3 | ble_hs_cfg.sm_our_key_dist / sm_their_key_dist |
8.2.2 IO Capability
| IO Capability | Display | Input | Example |
|---|---|---|---|
| DisplayOnly | Can display digits | None | The ESP32-C3 in this hands-on (the serial log is regarded as the “display”) |
| DisplayYesNo | Can display digits | Yes / No | Device with a screen and two buttons |
| KeyboardOnly | None | Can enter digits | Device with only a numeric keypad |
| NoInputNoOutput | None | None | Sensor with neither screen nor buttons |
| KeyboardDisplay | Can display | Can enter | Smartphone, PC |
8.2.3 Methods (association models)
The combination of both sides’ IO Capabilities determines the pairing method.
| Method | Behaviour | MITM protection | Example combinations |
|---|---|---|---|
| Just Works | No user interaction (or just a “Pair?” confirmation) | None | Either side is NoInputNoOutput |
| Passkey Entry | One side displays 6 digits, the other enters them (or both enter) | Yes | DisplayOnly × KeyboardDisplay (this hands-on) |
| Numeric Comparison | 6 digits shown on both; “yes” if they match | Yes | DisplayYesNo × DisplayYesNo (LE Secure Connections only) |
| Out of Band (OOB) | Key material passed via another channel such as NFC | Yes | Both support OOB |
Since the ESP32-C3 is DisplayOnly and the phone is KeyboardDisplay, it becomes Passkey Entry, with the ESP32-C3 displaying and the phone entering.
Even with DisplayOnly, if the peer is DisplayYesNo or NoInputNoOutput, it becomes Just Works. Keys made with Just Works are “unauthenticated” keys. The characteristics in this hands-on require authenticated keys (*_AUTHEN flags), so access from a peer paired via Just Works is rejected. If “encryption is enough”, you can choose to use only *_ENC.
8.2.4 Phase 2: LE Legacy and LE Secure Connections
There are two generations of key generation.
| LE Legacy Pairing (Bluetooth 4.0+) | LE Secure Connections (Bluetooth 4.2+) | |
|---|---|---|
| How keys are made | A temporary key (TK) is made from the passkey etc., and keys are derived from it | Elliptic-curve Diffie–Hellman key agreement (ECDH, P-256) |
| Resistance to eavesdropping | Weak. If the pairing exchange is sniffed, the passkey (at most 1 million possibilities) can be brute-forced and the key recovered | Strong. Eavesdropping alone does not reveal the key (even with Just Works) |
| Numeric Comparison | No | Yes |
In this hands-on, sm_sc = 1 is set so that LE Secure Connections is used if the peer supports it. If the peer only supports Legacy, it falls back to Legacy (because of CONFIG_BT_NIMBLE_SM_LEGACY=y). If you don’t want to allow Legacy, enable CONFIG_BT_NIMBLE_SM_SC_ONLY.
The security of Passkey Entry assumes the passkey is random each time and unknown to the attacker. This hands-on fixes it to 123456 to keep the steps simple, but this has the weaknesses that
- anyone who knows the passkey can mount a MITM attack
- LE Secure Connections’ Passkey Entry verifies the passkey bit by bit, so if the same passkey is reused, an attacker can gradually learn the passkey from failed pairing attempts
In products, design it so that a random passkey is generated and shown on a screen for every pairing, and if there is no display, consider Numeric Comparison or OOB.
8.2.5 Phase 3: key distribution
After encryption starts, each side sends the other the following keys (chosen with sm_our_key_dist / sm_their_key_dist).
| Key | Flag | Use |
|---|---|---|
| LTK (Long Term Key) | BLE_SM_PAIR_KEY_DIST_ENC |
Used for encryption on the next connection. With LE Secure Connections both sides compute the same LTK, so it is not distributed |
| IRK (Identity Resolving Key) + identity address | BLE_SM_PAIR_KEY_DIST_ID |
Identify the peer from its randomly changing address (RPA) |
| CSRK | BLE_SM_PAIR_KEY_DIST_SIGN |
For signed Writes (rarely used) |
Phones use RPAs, so without getting the IRK, the next time it connects you won’t know it is the same phone and won’t be able to find the stored keys. That is why BLE_SM_PAIR_KEY_DIST_ID is distributed in both directions.
8.3 Bonding and reconnection
When bonded, the following information is stored.
- The peer’s identity address and IRK
- The LTK (encryption key)
- CCCD values (which characteristics were subscribed to)
On the next connection, the Central starts encryption with the stored LTK, so no passkey entry is needed. CCCD values are also restored, so a bonded peer can receive Notify right after reconnecting (NimBLE informs you with BLE_GAP_EVENT_SUBSCRIBE with reason = restore).
sequenceDiagram participant P as ESP32-C3 participant C as Phone Note over P,C: Second and later connections C->>P: Connect P->>C: Security Request C->>P: LL_ENC_REQ (encrypt with the stored LTK) P-->>C: LL_ENC_RSP / START_ENC Note over P,C: Encrypted without passkey entry Note over P: BLE_GAP_EVENT_ENC_CHANGE (bonded=1)
8.3.1 When only one side deletes the keys
A common problem is the state where only one side has the bond information.
| Situation | What happens | Fix |
|---|---|---|
| “Forget this device” was done on the phone | The ESP32-C3 has the old keys, but the phone tries to pair anew | NimBLE informs you with BLE_GAP_EVENT_REPEAT_PAIRING. Delete the old keys and allow re-pairing (implemented in Step 5) |
The ESP32-C3’s flash was erased (erase-flash) |
The phone tries to encrypt with the old keys, but fails because the ESP32-C3 doesn’t have them | Forget the device on the phone too, then pair again |
8.4 ATT permissions: access control
Pairing is meaningless unless you reject access from unencrypted connections. For that we use the characteristic’s permissions.
| NimBLE flag | Condition | ATT error when not met |
|---|---|---|
BLE_GATT_CHR_F_READ_ENC / WRITE_ENC |
Encrypted | Insufficient Encryption (0x0F) |
BLE_GATT_CHR_F_READ_AUTHEN / WRITE_AUTHEN |
Encrypted with a key with MITM protection | Insufficient Authentication (0x05) |
BLE_GATT_CHR_F_NOTIFY_INDICATE_ENC / _AUTHEN |
Same as above, for writes to the CCCD (subscription) | Same as above |
When iOS or Android receives an Insufficient Authentication / Encryption error, it starts pairing automatically. So even if the peripheral doesn’t send a Security Request, the pairing dialog appears as soon as a protected characteristic is touched.
READ_ENC / WRITE_ENC only apply to reading/writing the value. The CCCD is a separate attribute, so without NOTIFY_INDICATE_*, even an unpaired peer can subscribe and receive Notify. In NimBLE’s source too, the CCCD’s permissions are determined solely by the NOTIFY_INDICATE_* flags.
8.5 Security modes and levels
The specification expresses connection security with four levels of LE Security Mode 1.
| Level | Details | This hands-on |
|---|---|---|
| 1 | No encryption | Steps 2–4 |
| 2 | Encrypted, unauthenticated (Just Works) | — |
| 3 | Encrypted, authenticated (Passkey etc.) | Step 5 (when the peer is Legacy) |
| 4 | Authenticated + LE Secure Connections + 128-bit key | Step 5 (when the peer supports SC; almost all current phones) |
- Pairing = creating keys; bonding = storing keys
- The method is decided by the combination of IO Capabilities. DisplayOnly × phone → Passkey Entry
- With LE Secure Connections, eavesdropping alone does not leak keys
- Access control is done with permission flags. Don’t forget
NOTIFY_INDICATE_*for the CCCD - A fixed passkey is for learning. In products, make it random every time