加密广播数据 (EAD)

[English]

概述

加密广播数据 (Encrypted Advertising Data，EAD) 引入于蓝牙核心规范 5.4。设备可以使用 AES-CCM 加密一段或多段广播结构，只有持有对应 Session Key 和 IV 的对端才能还原明文。

Bluedroid host 在 esp_ble_ead.h 中提供一组同步 API。加解密在 host 侧完成，不依赖控制器特性位。

启用 CONFIG_BT_BLE_FEAT_ENC_ADV_DATA 后会编译这些 API。

GAP Key Material 特征 (UUID 0x2B88，CONFIG_BT_GATTS_KEY_MATERIAL_CHAR) 是 Peripheral 发布 Session Key 和 IV 的标准做法。打开该选项会同时选中 EAD 加解密 API。调用 esp_ble_gap_set_key_material() 写入特征值后，对端可在加密 GATT 连接上读取，再用 esp_ble_ead_decrypt() 解密广播。

若 Central 已持有预共享密钥，只需打开 CONFIG_BT_BLE_FEAT_ENC_ADV_DATA。

应用示例

在 menuconfig 中见 Bluedroid Options → Encrypted Advertising Data (EAD)。

API 参考

Header File

  • components/bt/host/bluedroid/api/include/api/esp_ble_ead.h

  • This header file can be included with:

    #include "esp_ble_ead.h"

  • This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

    REQUIRES bt

    or

    PRIV_REQUIRES bt

Functions

esp_err_t esp_ble_ead_encrypt(const uint8_t session_key[ESP_BLE_EAD_KEY_SIZE], const uint8_t iv[ESP_BLE_EAD_IV_SIZE], const uint8_t *payload, size_t payload_size, uint8_t *encrypted_payload)

Encrypt advertising data using AES-CCM.

The resulting data in encrypted_payload has the following layout:

  • Randomizer in the first ESP_BLE_EAD_RANDOMIZER_SIZE bytes

  • Encrypted payload of payload_size bytes

  • MIC in the last ESP_BLE_EAD_MIC_SIZE bytes

The function must be called each time the RPA is updated or the advertising data are modified. payload may contain one or more concatenated advertising structures (length + type + data).

参数:

  • session_key -- [in] 16-byte session key

  • iv -- [in] 8-byte Initialization Vector. Must be changed each time the session key changes

  • payload -- [in] Plaintext advertising data to encrypt

  • payload_size -- [in] Size of plaintext data. Must be greater than 0

  • encrypted_payload -- [out] Output buffer for encrypted data. Size must be at least ESP_BLE_EAD_ENCRYPTED_PAYLOAD_SIZE(payload_size)

返回:

  • ESP_OK: success

  • ESP_ERR_INVALID_ARG: invalid argument

  • ESP_FAIL: encryption failed

esp_err_t esp_ble_ead_decrypt(const uint8_t session_key[ESP_BLE_EAD_KEY_SIZE], const uint8_t iv[ESP_BLE_EAD_IV_SIZE], const uint8_t *encrypted_payload, size_t encrypted_payload_size, uint8_t *payload, size_t payload_capacity)

Decrypt advertising data using AES-CCM.

参数:

  • session_key -- [in] 16-byte session key

  • iv -- [in] 8-byte Initialization Vector

  • encrypted_payload -- [in] Encrypted advertising data (includes randomizer and MIC). This should only contain the advertising data from the received advertising structure, neither the length nor the type

  • encrypted_payload_size -- [in] Size of encrypted data

  • payload -- [out] Output buffer for decrypted data. Use ESP_BLE_EAD_DECRYPTED_PAYLOAD_SIZE to get the right size

  • payload_capacity -- [in] Size of payload in bytes; must be >= ESP_BLE_EAD_DECRYPTED_PAYLOAD_SIZE(encrypted_payload_size)

返回:

  • ESP_OK: success

  • ESP_ERR_INVALID_ARG: invalid argument

  • ESP_FAIL: decryption or authentication failed

Structures

struct esp_ble_ead_key_material_t

Key material structure for EAD.

Public Members

uint8_t session_key[ESP_BLE_EAD_KEY_SIZE]

128-bit session key

uint8_t iv[ESP_BLE_EAD_IV_SIZE]

64-bit Initialization Vector

Macros

ESP_BLE_EAD_KEY_SIZE

BLE Encrypted Advertising Data (EAD)

Based on Bluetooth Core Specification Version 5.4 and Core Specification Supplement v11, Part A 1.23.

Enable CONFIG_BT_BLE_FEAT_ENC_ADV_DATA to compile the encrypt/decrypt APIs. A GATT server that publishes the session key should also enable CONFIG_BT_GATTS_KEY_MATERIAL_CHAR and call esp_ble_gap_set_key_material(). 128-bit session key

ESP_BLE_EAD_IV_SIZE

64-bit Initialization Vector

ESP_BLE_EAD_RANDOMIZER_SIZE

40-bit Randomizer

ESP_BLE_EAD_MIC_SIZE

32-bit Message Integrity Check

ESP_BLE_EAD_NONCE_SIZE

104-bit Nonce (Randomizer + IV)

ESP_BLE_EAD_AAD_SIZE

Additional Authenticated Data size

ESP_BLE_EAD_RANDOMIZER_DIRECTION_BIT

Direction bit position in Randomizer (MSB of last byte). Per Bluetooth Core Spec Supplement v11, Part A 1.23.3.

ESP_BLE_EAD_ENCRYPTED_PAYLOAD_SIZE(payload_size)

Calculate encrypted payload size from plaintext size.

Encrypted payload layout: Randomizer || Ciphertext || MIC

ESP_BLE_EAD_DECRYPTED_PAYLOAD_SIZE(encrypted_size)

Calculate decrypted payload size from encrypted payload size.

此文档对您有帮助吗？