Encrypted Advertising Data (EAD)

[中文]

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 esp_ble_gap_set_key_material() to set the value so a peer can read it over an encrypted GATT connection, then decrypt with esp_ble_ead_decrypt().

A central that already has a pre-shared key only needs CONFIG_BT_BLE_FEAT_ENC_ADV_DATA.

Application Examples

In menuconfig, see Bluedroid Options > Encrypted Advertising Data (EAD).

API Reference

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

Parameters:

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

Returns:

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

Parameters:

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

Returns:

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

Was this page helpful?