feat(ble/bluedroid): move Encrypted Advertising Data APIs into the host

Provide esp_ble_ead_encrypt/decrypt in Bluedroid and group the GAP Key
Material characteristic under the same EAD Kconfig menu.

docs/conf_common.py

@@ -47,6 +47,7 @@ BLE_DOCS = [
     'api-guides/low-power-mode/low-power-mode-ble.rst',
     'api-reference/bluetooth/bt_le.rst',
     'api-reference/bluetooth/esp_gap_ble.rst',
+    'api-reference/bluetooth/esp_ble_ead.rst',
     'api-reference/bluetooth/esp_gatt_defs.rst',
     'api-reference/bluetooth/esp_gatts.rst',
     'api-reference/bluetooth/esp_gattc.rst',

docs/doxygen/Doxyfile

@@ -85,6 +85,7 @@ INPUT = \
     $(PROJECT_PATH)/components/bt/esp_ble_iso/api/include/esp_ble_iso_common_api.h \
     $(PROJECT_PATH)/components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h \
     $(PROJECT_PATH)/components/bt/host/bluedroid/api/include/api/esp_avrc_api.h \
+    $(PROJECT_PATH)/components/bt/host/bluedroid/api/include/api/esp_ble_ead.h \
     $(PROJECT_PATH)/components/bt/host/bluedroid/api/include/api/esp_bt_defs.h \
     $(PROJECT_PATH)/components/bt/host/bluedroid/api/include/api/esp_bt_device.h \
     $(PROJECT_PATH)/components/bt/host/bluedroid/api/include/api/esp_bt_main.h \

docs/en/api-reference/bluetooth/bt_le.rst

@@ -25,6 +25,10 @@ The Bluetooth LE API in ESP-IDF is organized into the following parts:
 
   Discovers and accesses services on remote servers (central role)
 
+- :doc:`Bluetooth Low Energy Encrypted Advertising Data <esp_ble_ead>`
+
+  Encrypts and decrypts advertising payloads with AES-CCM (Bluetooth Core Specification 5.4)
+
 .. only:: SOC_BLUFI_SUPPORTED
 
    - :doc:`Bluetooth Low Energy BluFi <esp_blufi>`
@@ -41,4 +45,5 @@ Each part typically includes an **Overview**, **Application Examples**, and **AP
    Bluetooth Low Energy GATT Define <esp_gatt_defs>
    Bluetooth Low Energy GATT Server <esp_gatts>
    Bluetooth Low Energy GATT Client <esp_gattc>
+   Bluetooth Low Energy Encrypted Advertising Data <esp_ble_ead>
    :SOC_BLUFI_SUPPORTED: Bluetooth Low Energy BluFi <esp_blufi>

docs/en/api-reference/bluetooth/esp_ble_ead.rst

@@ -0,0 +1,31 @@
+Encrypted Advertising Data (EAD)
+================================
+
+:link_to_translation:`zh_CN:[中文]`
+
+Overview
+--------
+
+Encrypted Advertising Data (EAD) was introduced in Bluetooth Core Specification 5.4. It allows a device to encrypt one or more advertising structures with AES-CCM, so that only peers that hold the corresponding session key and IV can recover the plaintext.
+
+The Bluedroid host exposes this as a pair of synchronous APIs in ``esp_ble_ead.h``. Encryption and decryption are performed in the host and do not require a controller feature bit.
+
+These APIs are compiled when ``CONFIG_BT_BLE_FEAT_ENC_ADV_DATA`` is enabled.
+
+The GAP Key Material characteristic (UUID 0x2B88, ``CONFIG_BT_GATTS_KEY_MATERIAL_CHAR``) is the standard way for a peripheral to publish the session key and IV. Enabling that option also selects the EAD APIs. Call :cpp:func:`esp_ble_gap_set_key_material` to set the value so a peer can read it over an encrypted GATT connection, then decrypt with :cpp:func:`esp_ble_ead_decrypt`.
+
+A central that already has a pre-shared key only needs ``CONFIG_BT_BLE_FEAT_ENC_ADV_DATA``.
+
+Application Examples
+--------------------
+
+- :example:`bluetooth/bluedroid/ble/ble_enc_adv_data/enc_adv_data_prph` demonstrates encrypting advertising data and exposing Key Material through the GAP service.
+
+- :example:`bluetooth/bluedroid/ble/ble_enc_adv_data/enc_adv_data_cent` demonstrates scanning for encrypted advertising data and decrypting it after reading, or using, the Key Material.
+
+In menuconfig, see ``Bluedroid Options`` > ``Encrypted Advertising Data (EAD)``.
+
+API Reference
+-------------
+
+.. include-build-file:: inc/esp_ble_ead.inc

docs/en/api-reference/bluetooth/esp_gap_ble.rst

@@ -10,6 +10,8 @@ Application Examples
 
 - :example:`bluetooth/bluedroid/ble/gatt_security_server` demonstrates how to use ESP BLE security APIs on {IDF_TARGET_NAME} to establish a secure connection and encrypt communication with peer devices while acting as a GATT server.
 
+- :example:`bluetooth/bluedroid/ble/ble_enc_adv_data/enc_adv_data_prph` demonstrates Encrypted Advertising Data and how to publish Key Material with :cpp:func:`esp_ble_gap_set_key_material`. See also :doc:`esp_ble_ead`.
+
 API Reference
 -------------
 

docs/zh_CN/api-reference/bluetooth/bt_le.rst

@@ -25,6 +25,10 @@ ESP-IDF 中的低功耗蓝牙 API 包括以下部分：
 
   发现并访问远程服务器的服务（中心设备角色）
 
+- :doc:`Bluetooth Low Energy Encrypted Advertising Data <esp_ble_ead>`
+
+  使用 AES-CCM 加密和解密广播载荷（蓝牙核心规范 5.4）
+
 .. only:: SOC_BLUFI_SUPPORTED
 
    - :doc:`Bluetooth Low Energy BluFi <esp_blufi>`
@@ -41,4 +45,5 @@ ESP-IDF 中的低功耗蓝牙 API 包括以下部分：
    Bluetooth Low Energy GATT Define <esp_gatt_defs>
    Bluetooth Low Energy GATT Server <esp_gatts>
    Bluetooth Low Energy GATT Client <esp_gattc>
+   Bluetooth Low Energy Encrypted Advertising Data <esp_ble_ead>
    :SOC_BLUFI_SUPPORTED: Bluetooth Low Energy BluFi <esp_blufi>

docs/zh_CN/api-reference/bluetooth/esp_ble_ead.rst

@@ -0,0 +1,31 @@
+加密广播数据 (EAD)
+==================
+
+:link_to_translation:`en:[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。调用 :cpp:func:`esp_ble_gap_set_key_material` 写入特征值后，对端可在加密 GATT 连接上读取，再用 :cpp:func:`esp_ble_ead_decrypt` 解密广播。
+
+若 Central 已持有预共享密钥，只需打开 ``CONFIG_BT_BLE_FEAT_ENC_ADV_DATA``。
+
+应用示例
+--------------------
+
+- :example:`bluetooth/bluedroid/ble/ble_enc_adv_data/enc_adv_data_prph` 演示如何加密广播数据，并通过 GAP 服务提供 Key Material。
+
+- :example:`bluetooth/bluedroid/ble/ble_enc_adv_data/enc_adv_data_cent` 演示如何扫描加密广播数据，并在读取或使用 Key Material 后解密。
+
+在 menuconfig 中见 **Bluedroid Options → Encrypted Advertising Data (EAD)**。
+
+API 参考
+-------------
+
+.. include-build-file:: inc/esp_ble_ead.inc

docs/zh_CN/api-reference/bluetooth/esp_gap_ble.rst

@@ -10,6 +10,8 @@ GAP API
 
 - :example:`bluetooth/bluedroid/ble/gatt_security_server` 演示使用 ESP 低功耗蓝牙 security API，{IDF_TARGET_NAME} 作为 GATT 服务器时如何建立安全连接并加密与对等设备的通信。
 
+- :example:`bluetooth/bluedroid/ble/ble_enc_adv_data/enc_adv_data_prph` 演示加密广播数据，并通过 :cpp:func:`esp_ble_gap_set_key_material` 发布 Key Material。另见 :doc:`esp_ble_ead`。
+
 API 参考
 -------------