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.

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.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.

WarningDepending on the peer, it may fall back to Just Works

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.

ImportantA fixed passkey is for the hands-on 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.

WarningProtect Notify subscriptions too

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)
ImportantKey points
  • 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