4.2 SMP安全配对验证:ESP32 BLE HID设备的密钥协商与身份认证工程实践
在BLE HID设备(如蓝牙键盘、鼠标、自拍杆)的实际开发中,配对阶段的安全性直接决定了设备能否被用户信任并稳定连接。SMP(Security Manager Protocol)是BLE协议栈中负责密钥生成、分发与认证的核心协议层。本节不讨论抽象概念,而是聚焦于ESP-IDF框架下如何通过精确配置SMP参数、实现IO能力协商、触发密钥事件并完成端到端验证——所有操作均基于真实硬件行为与协议规范,而非模拟器或理论推演。
4.2.1 SMP配置的本质:从寄存器映射到协议状态机
SMP配置并非简单的API调用堆砌,而是对BLE控制器底层安全状态机的显式建模。ESP32的BLE控制器(BT Controller)在初始化后默认处于“无安全上下文”状态。当GAP层发起配对请求时,SMP模块需依据预设参数决定采用何种密钥协商路径。该决策过程由四个关键配置项共同驱动:
-
静态密钥(Static PIN) :
esp_ble_gap_set_security_param(ESP_BLE_SM_SET_STATIC_PASSKEY, &passkey, sizeof(uint32_t))
此处传入的passkey值(如0x123456)并非明文存储于Flash,而是被BLE控制器内部转换为128位AES密钥种子。其长度固定为4字节(32位),但协议要求必须以大端序填充至16字节缓冲区。若传入非标准长度(如3字节),控制器将截断高位并补零,导致密钥一致性校验失败。 -
认证要求(Authentication Requirements) :
esp_ble_gap_set_security_param(ESP_BLE_SM_SET_AUTHEN_REQ, &auth_req, sizeof(uint8_t))
auth_req是一个位域变量,其bit0-bit3定义如下: -
Bit0(Bonding Flag):
0=不绑定,1=绑定(保存长期密钥至NVS) -
Bit1(MITM Flag):
0=无中间人保护,1=启用MITM(强制输入/显示验证) -
Bit2(SC Flag):
0=传统配对(Legacy Pairing),1=安全连接(Secure Connections) -
Bit3(Key Distribution Flag):保留位
实际项目中常设为0x0C(二进制1100),即启用绑定+MITM+安全连接。此组合强制进入SC模式,绕过传统配对中易受攻击的Just Works流程。 -
IO能力(I/O Capability) :
esp_ble_gap_set_security_param(ESP_BLE_SM_SET_IO_CAPABILITIES, &io_cap, sizeof(uint8_t))
IO能力决定设备在配对时可执行的交互类型,直接影响SMP状态机跳转:
| 值 | 宏定义 | 行为含义 | 典型设备 |
|—|--------|----------|----------|
|0x00|ESP_IO_CAPABILITY_DISPLAY_ONLY| 仅显示6位PIN码,无输入能力 | 智能灯泡 |
|0x01|ESP_IO_CAPABILITY_DISPLAY_YESNO| 显示PIN码并提供Yes/No确认按钮 | 蓝牙音箱 |
|0x02|ESP_IO_CAPABILITY_KEYBOARD_ONLY| 仅支持键盘输入,无显示能力 | 蓝牙键盘 |
|0x03|ESP_IO_CAPABILITY_NO_INPUT_NO_OUTPUT| 无任何IO能力,强制使用Just Works | 心率监测仪 |
|0x04|ESP_IO_CAPABILITY_KEYBOARD_DISPLAY| 同时支持输入与显示(最灵活) | 蓝牙鼠标 |
关键点在于:
IO能力必须与物理硬件能力严格匹配
。若服务端配置为
DISPLAY_ONLY
但实际未实现LCD驱动,则配对将卡在
SM_SEND_SMP_PAIRING_REQUEST
状态,无法推进。
-
密钥分发策略(Key Distribution)
:
esp_ble_gap_set_security_param(ESP_BLE_SM_SET_INIT_KEY, &init_key, sizeof(uint8_t))与esp_ble_gap_set_security_param(ESP_BLE_SM_SET_RESP_KEY, &resp_key, sizeof(uint8_t))
这两个参数分别定义发起端(Initiator)和响应端(Responder)愿意接收/发送的密钥类型: - Bit0(LTK):长期加密密钥(Long Term Key),用于链路加密
- Bit1(IRK):身份解析密钥(Identity Resolving Key),用于私有地址解析
-
Bit2(CSRK):签名加密密钥(Connection Signature Resolving Key),用于数据签名
实际HID设备通常需同时分发LTK与IRK(值设为0x03),确保后续连接可复用绑定信息且支持隐私特性。
工程经验 :曾遇到某键盘固件因误将
init_key设为0x01(仅LTK),导致iOS设备在重连时反复触发配对。原因在于iOS强制要求IRK分发以支持随机地址扫描,而0x01配置拒绝了IRK交换,使SMP状态机回退至SM_WAIT_PAIRING_REQ循环。
4.2.2 密钥事件回调的精准触发机制
SMP配置生效后,BLE协议栈会根据配对流程自动触发一系列事件回调。这些回调并非简单通知,而是开发者介入密钥协商的关键入口点。ESP-IDF中所有SMP事件均通过
esp_ble_gap_cb_t
回调函数统一派发,需在
GAP_EVENT
分支中精确识别:
static void gap_event_handler(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_param_t *param) {
switch (event) {
case ESP_GAP_BLE_SEC_REQ_EVT: {
// 安全请求事件:对端发起配对请求
esp_ble_gap_security_rsp(param->ble_security.ble_req.bd_addr, true);
break;
}
case ESP_GAP_BLE_PASSKEY_REQ_EVT: {
// PIN码请求事件:需向对端回复6位数字
uint32_t passkey = 0x123456; // 实际项目应从Flash读取或动态生成
esp_ble_passkey_reply(param->ble_security.ble_req.bd_addr, true, passkey);
break;
}
case ESP_GAP_BLE_OOB_REQ_EVT: {
// OOB请求事件:需提供16字节OOB数据
uint8_t oob_data[16] = {0};
// 此处应填入预共享的OOB数据(如NFC标签读取值)
esp_ble_oob_req_reply(param->ble_security.ble_req.bd_addr, true, oob_data);
break;
}
case ESP_GAP_BLE_NC_REQ_EVT: {
// 数字比较事件(Numeric Comparison):显示6位数字供用户比对
ESP_LOGI(TAG, "Numeric Comparison: %06u", param->ble_security.nc_req.num_val);
// 硬件实现:驱动OLED显示数字,等待用户按"YES"/"NO"
break;
}
case ESP_GAP_BLE_KEY_EVT: {
// 密钥分发完成事件:获取已协商的密钥
switch (param->ble_security.key.key_type) {
case ESP_LE_KEY_PENC: // LTK
memcpy(ltk, param->ble_security.key.penc_key.ltk, 16);
break;
case ESP_LE_KEY_PID: // IRK
memcpy(irk, param->ble_security.key.pid_key.irk, 16);
break;
}
break;
}
case ESP_GAP_BLE_AUTH_CMPL_EVT: {
// 认证完成事件:配对成功标志
if (param->ble_security.auth_cmpl.success) {
ESP_LOGI(TAG, "Pairing success: %02x:%02x:%02x:%02x:%02x:%02x",
param->ble_security.auth_cmpl.bda[0],
param->ble_security.auth_cmpl.bda[1],
param->ble_security.auth_cmpl.bda[2],
param->ble_security.auth_cmpl.bda[3],
param->ble_security.auth_cmpl.bda[4],
param->ble_security.auth_cmpl.bda[5]);
// 此处应保存绑定信息至NVS
save_bond_info(param->ble_security.auth_cmpl.bda);
}
break;
}
}
}
关键细节解析
:
-
ESP_GAP_BLE_SEC_REQ_EVT
是配对流程的起点,必须立即调用
esp_ble_gap_security_rsp()
响应,否则对端将超时断开。响应参数
true
表示接受配对请求。
-
ESP_GAP_BLE_PASSKEY_REQ_EVT
在MITM启用时必然触发,但
仅当IO能力为
DISPLAY_ONLY
或
DISPLAY_YESNO
时才会由服务端发出
;若服务端为
KEYBOARD_ONLY
,则此事件由客户端触发,服务端需监听
ESP_GAP_BLE_KEY_EVT
接收PIN码。
-
ESP_GAP_BLE_NC_REQ_EVT
仅在SC模式(
auth_req & 0x04
)下出现,其
num_val
字段为随机生成的6位十进制数,需在硬件显示屏实时呈现。用户确认后调用
esp_ble_nc_req_reply(bd_addr, true)
。
-
ESP_GAP_BLE_KEY_EVT
中的
key_type
字段明确指示当前分发的密钥类型,开发者必须根据类型将密钥写入对应缓冲区,不可混用。
踩坑记录 :在调试某蓝牙鼠标时,发现配对后无法维持加密连接。抓包分析显示
ESP_GAP_BLE_KEY_EVT中key_type始终为ESP_LE_KEY_NONE。最终定位到esp_ble_gap_set_security_param()调用顺序错误——在esp_ble_gap_register_callback()之前设置了密钥参数,导致SMP模块未加载配置。修正后问题解决。
4.2.3 OOB配对的硬件级实现:从串口输入到密钥注入
OOB(Out of Band)配对通过独立信道(如NFC、二维码、串口)交换16字节密钥,规避无线信道中的MITM攻击。在ESP32开发板上,常用串口作为OOB信道,但其实现远非简单读取字符串:
串口任务设计要点
// 串口接收任务:专用于OOB密钥输入
void uart_obb_task(void *pvParameters) {
uart_config_t uart_config = {
.baud_rate = 115200,
.data_bits = UART_DATA_8_BITS,
.parity = UART_PARITY_DISABLE,
.stop_bits = UART_STOP_BITS_1,
.flow_ctrl = UART_HW_FLOWCTRL_DISABLE,
.source_clk = UART_SCLK_DEFAULT,
};
uart_driver_install(UART_NUM_0, 256, 0, 0, NULL, 0);
uart_param_config(UART_NUM_0, &uart_config);
uart_set_pin(UART_NUM_0, GPIO_NUM_1, GPIO_NUM_3, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE);
uint8_t rx_buffer[32];
while (1) {
int len = uart_read_bytes(UART_NUM_0, rx_buffer, sizeof(rx_buffer), 100 / portTICK_PERIOD_MS);
if (len > 0 && len <= 16) {
// 关键:严格校验输入长度与格式
bool valid = true;
for (int i = 0; i < len; i++) {
if (rx_buffer[i] < 0x20 || rx_buffer[i] > 0x7E) { // ASCII可打印字符范围
valid = false;
break;
}
}
if (valid) {
// 将ASCII输入转换为二进制密钥(如"1234567890ABCDEF" → 16字节)
uint8_t obb_key[16];
hex_string_to_bytes((char*)rx_buffer, obb_key, len);
// 注入SMP模块
esp_ble_oob_req_reply(current_peer_bda, true, obb_key);
ESP_LOGI(TAG, "OOB key injected");
}
}
vTaskDelay(10 / portTICK_PERIOD_MS);
}
}
格式转换的硬性约束
OOB数据必须满足BLE Core Specification v5.3第3卷H部分要求:
- 若为ASCII字符串,长度必须为16或32字符(对应8或16字节二进制密钥)
- 字符必须为十六进制字符(
0-9
,
A-F
,
a-f
),其余字符视为非法
- 转换函数
hex_string_to_bytes()
需严格实现,示例:
void hex_string_to_bytes(const char* hex_str, uint8_t* out, size_t len) {
for (size_t i = 0; i < len; i += 2) {
char high = hex_str[i];
char low = (i + 1 < len) ? hex_str[i + 1] : '0';
out[i/2] = ((high >= 'A') ? high - 'A' + 10 : high - '0') << 4;
out[i/2] |= (low >= 'A') ? low - 'A' + 10 : low - '0';
}
}
时序关键点
-
OOB请求事件
ESP_GAP_BLE_OOB_REQ_EVT触发后,设备有 30秒超时窗口 接收OOB数据。超时后SMP自动终止配对。 -
串口任务必须在
ESP_GAP_BLE_OOB_REQ_EVT发生后立即激活,且current_peer_bda需在事件中捕获并全局保存。 - 多次输入尝试需清空接收缓冲区,避免残留数据干扰。
实战技巧 :在量产测试中,为避免人工输入错误,可将OOB密钥预烧录至ESP32的eFuse中(使用
efuse_write_field_blob()),配对时直接读取。eFuse密钥不可擦除,安全性远高于Flash存储。
4.2.4 配对模式交叉验证实验:IO能力组合的协议行为分析
不同IO能力组合将触发SMP状态机的不同分支。以下为在ESP32-WROVER-KIT上实测的四种典型场景,所有结果均通过nRF Connect抓包验证:
| 场景 | 服务端IO能力 | 客户端IO能力 | 触发事件序列 | 协议行为说明 |
|---|---|---|---|---|
| A |
KEYBOARD_ONLY
(0x02)
|
DISPLAY_ONLY
(0x00)
|
PASSKEY_REQ
→
KEY_EVT
→
AUTH_CMPL
| 服务端作为响应端需输入PIN,客户端显示PIN。符合HID设备角色分配。 |
| B |
DISPLAY_ONLY
(0x00)
|
KEYBOARD_ONLY
(0x02)
|
PASSKEY_REQ
→
KEY_EVT
→
AUTH_CMPL
|
服务端显示PIN,客户端输入。此时服务端需驱动LCD,否则卡在
PASSKEY_REQ
。
|
| C |
DISPLAY_YESNO
(0x01)
|
DISPLAY_YESNO
(0x01)
|
NC_REQ
→
KEY_EVT
→
AUTH_CMPL
| 双方均显示相同6位数字,用户比对后按”YES”。SC模式强制启用,安全性最高。 |
| D |
NO_INPUT_NO_OUTPUT
(0x03)
|
NO_INPUT_NO_OUTPUT
(0x03)
|
AUTH_CMPL
(无中间事件)
| Just Works模式,无用户交互。仅适用于低安全需求设备(如温湿度传感器)。 |
实验现象深度解读
:
- 场景A中,服务端串口接收到
123456
后,协议栈立即生成LTK并发送
SM_SEND_LTK
指令,客户端收到后返回
SM_RECV_LTK
确认,整个过程耗时约1.2秒。
- 场景C的
NC_REQ
事件中,
num_val
字段在双方设备上显示完全一致,证明SC模式下的P-256椭圆曲线密钥协商正确执行。
- 场景D虽快速完成,但抓包显示
SM_SEND_PAIRING_REQUEST
中
AuthReq
字段的MITM位为
0
,表明链路无中间人保护,任何附近设备均可劫持连接。
重要警告 :切勿在HID设备中使用场景D!曾有某键盘厂商为降低BOM成本采用
NO_INPUT_NO_OUTPUT,导致黑客利用crackle工具在3秒内破解LTK,实现按键记录。
4.2.5 绑定信息的持久化与重连优化
配对成功后,
ESP_GAP_BLE_AUTH_CMPL_EVT
事件中的绑定信息必须可靠存储,否则每次重连都将重复配对流程。ESP-IDF提供NVS(Non-Volatile Storage)组件,但需注意以下陷阱:
NVS分区配置
在
partitions.csv
中必须为BLE绑定信息预留专用分区:
nvs, data, nvs, 0x9000, 0x6000,
nvs_keys, data, nvs_keys, 0xf000, 0x1000,
其中
nvs_keys
分区用于存储加密密钥(LTK、IRK等),因其敏感性需单独隔离。
安全存储实现
typedef struct {
uint8_t bda[6];
uint8_t ltk[16];
uint8_t irk[16];
uint8_t ltk_enc_size; // 加密强度(7-16字节)
uint16_t ediv; // 随机数
uint64_t rand; // 随机数
} bond_info_t;
void save_bond_info(const uint8_t* bda) {
nvs_handle_t handle;
nvs_open("ble_bond", NVS_READWRITE, &handle);
// 以BD_ADDR为key存储结构体
char key[13];
sprintf(key, "%02x%02x%02x%02x%02x%02x",
bda[0], bda[1], bda[2], bda[3], bda[4], bda[5]);
bond_info_t info = {0};
memcpy(info.bda, bda, 6);
// 此处应从SMP事件中提取LTK/IRK等字段
nvs_set_blob(handle, key, &info, sizeof(info));
nvs_commit(handle);
nvs_close(handle);
}
// 重连时自动加载绑定信息
void load_bond_info(const uint8_t* bda) {
nvs_handle_t handle;
nvs_open("ble_bond", NVS_READONLY, &handle);
char key[13];
sprintf(key, "%02x%02x%02x%02x%02x%02x",
bda[0], bda[1], bda[2], bda[3], bda[4], bda[5]);
bond_info_t info;
size_t len = sizeof(info);
if (nvs_get_blob(handle, key, &info, &len) == ESP_OK) {
// 调用esp_ble_gap_set_security_param注入密钥
esp_ble_gap_set_security_param(ESP_BLE_SM_SET_LTK, info.ltk, 16);
esp_ble_gap_set_security_param(ESP_BLE_SM_SET_IRK, info.irk, 16);
}
nvs_close(handle);
}
重连性能优化
-
延迟启动
:在
ESP_GATTS_CONNECT_EVT后延迟100ms再调用esp_ble_set_encryption(),避免与GATT服务发现竞争资源。 - 密钥缓存 :将最近使用的3个设备密钥缓存在RAM中,减少NVS读取次数。
-
绑定清理
:提供AT指令
AT+BOND=DEL,<BD_ADDR>,便于产线测试后清除绑定信息。
4.2.6 故障诊断与调试方法论
当配对失败时,需按层级排查:
第一层:物理层与基础配置
-
使用逻辑分析仪抓取UART输出,确认
ESP_GAP_BLE_AUTH_CMPL_EVT是否到达。若未触发,检查esp_ble_gap_register_callback()是否在esp_bluedroid_init()之后调用。 -
用nRF Connect连接设备,查看广播包中
Flags字段是否包含0x06(LE General Discoverable + BR/EDR Not Supported),缺失则GAP配置错误。
第二层:SMP协议栈状态
-
启用BLE日志:
idf.py menuconfig→Component config→Bluetooth→Bluetooth controller→Bluetooth controller log level设为VERBOSE。 - 关键日志标识:
-
sm_send_pairing_req:发起配对请求 -
sm_recv_pairing_req:收到配对请求 -
sm_start_encryption:开始加密 -
sm_encryption_failed:加密失败(常见于LTK不匹配)
第三层:密钥一致性验证
-
在
ESP_GAP_BLE_KEY_EVT中打印LTK的SHA256哈希:
c uint8_t hash[32]; mbedtls_sha256((const unsigned char*)ltk, 16, hash, 0); ESP_LOG_BUFFER_HEX("LTK_HASH", hash, 4); // 仅打印前4字节用于比对
若服务端与客户端哈希值不一致,必为密钥注入错误。
终极调试技巧 :当所有软件手段失效时,直接测量ESP32的
GPIO12(BT controller debug pin)。该引脚在SMP状态机跳转时产生脉冲,用示波器观察脉冲序列可反推当前状态(如连续3个窄脉冲表示SM_WAIT_PAIRING_REQ)。
配对验证不是一次性的配置任务,而是贯穿产品生命周期的安全基线。每一次修改
auth_req
或
io_cap
,都需重新执行全场景交叉测试。我在开发某款医疗级蓝牙血压计时,曾因未测试
DISPLAY_YESNO
与
KEYBOARD_ONLY
的组合,在FDA认证现场被指出“患者无法确认配对数字”,导致返工两周。真正的嵌入式安全,始于对每个比特的敬畏。
660



被折叠的 条评论
为什么被折叠?



