STM32WB/WBA Bluetooth® Low Energy – Encrypted Advertising (EAD)


1. Bluetooth® Low Energy Encrypted Advertising feature

The figure below details the Bluetooth® Low Energy Encrypted Advertising feature.

Bluetooth® Encrypted Advertising feature
Connectivity EAD 1.png


1.1. Principles

Encrypted Advertising Data (EAD) is a feature allowing the encryption of advertising data.
Encrypted advertisement data can be received by any device, but can only be decrypted by devices that have previously exchanged the session key.
This feature allows encrypting a full or partial payload on a given advertising packet. Encrypted Advertising adds a new AD type called Encrypted Advertising Data (type 0x31), encapsulating all AD fields to be encrypted.

The encryption of Encrypted Advertising Data is based on an algorithm using the value of a new characteristic added to the GAP (or other) service.
The characteristic Encrypted Data Key Material is readable and indicatable by an authenticated and authorized device.

Security permissions are defined as "Need authentication to read" and "Need authorization to read". Devices have been previously bonded.

The peer device, which receives advertising reports containing AD-type Encrypted Advertising Data, can decode encrypted data using the previously read Encrypted Data Key Material.

The Encrypted Data Key Material characteristic (UUID: 0x2B88) contains a 24-octet value, which is made up of:

  • session key: 16 bytes = Key material key
  • iv: 8 bytes = Key material initialization vector

The figures below show the Encrypted Data Key Material characteristic and its indication.

Bluetooth® Read Encrypted Data Key Material characteristic
Connectivity read charac.png


Bluetooth® Encrypted Data Key Material characteristic Indication
Connectivity charac indication.png


1.2. How to implement EAD in STM32WB/WBA applications

1.2.1. Peripheral device

Add a new characteristic (Encrypted Data Key Material - UUID = 0x2B88) to the GAP service:

Char_UUID_t  uuid;
uint16_t gap_EncrDataKayMaterial_handle = 0U;
static const uint8_t p_additional_svc_record[1] = {0x03};
uint8_t i;
  
ret = aci_hal_write_config_data(CONFIG_DATA_GAP_ADD_REC_NBR_OFFSET,
                                 CONFIG_DATA_GAP_ADD_REC_NBR_LEN,
                                 (uint8_t*) p_additional_svc_record);
if (ret != BLE_STATUS_SUCCESS)
{
  LOG_INFO_APP("  Fail   : aci_hal_write_config_data command - CONFIG_DATA_GAP_ADD_REC_NBR_OFFSET, result: 0x%02X\n", ret);
}
else
{
  LOG_INFO_APP("  Success: aci_hal_write_config_data command - CONFIG_DATA_GAP_ADD_REC_NBR_OFFSET\n");
}
uint16_t SizeEncDataKeyMaterial_C = sizeof(encryption_key)+sizeof(initialization_vector);
uuid.Char_UUID_16 = ENCRYPTED_DATA_KEY_MATERIAL_UUID;
ret = aci_gatt_add_char(gap_service_handle,
                         UUID_TYPE_16,
                         (Char_UUID_t *) &uuid,
                         SizeEncDataKeyMaterial_C,
                         CHAR_PROP_READ | CHAR_PROP_INDICATE,
                         ATTR_PERMISSION_AUTHEN_READ | ATTR_PERMISSION_AUTHOR_READ,
                         GATT_NOTIFY_ATTRIBUTE_WRITE,
                         0x10,
                         CHAR_VALUE_LEN_CONSTANT,
                         &gap_EncrDataKayMaterial_handle);
if (ret != BLE_STATUS_SUCCESS)
{
  LOG_INFO_APP("  Fail   : aci_gatt_add_char command   : encryption_key+iv, error code: 0x%2X\n", ret);
}
else
{
  LOG_INFO_APP("  Success: aci_gatt_add_char command   : encryption_key+iv\n");
}
ret = aci_gatt_update_char_value(gap_service_handle, gap_EncrDataKayMaterial_handle, 0, SizeEncDataKeyMaterial_C, (uint8_t *)&char_encr_data_key_mat);
if (ret != BLE_STATUS_SUCCESS)
{
  LOG_INFO_APP("  Fail   : aci_gatt_update_char_value - EncrDataKayMaterial, result: 0x%02X\n", ret);
}
else
{
  LOG_INFO_APP("  Success: aci_gatt_update_char_value - EncrDataKayMaterial\n");
}

1.2.2. Central device

Discover the Encrypted Data Key Material characteristic added to the GAP service (among all other characteristics).

Before the first connection, when the peripheral advertises, the scanner is unable to decrypt encrypted advertising data.
When the devices are bonded and the central is able to read the Key Material characteristic, it stores the characteristic in the flash memory.
For subsequent connections (devices have previously been bonded), when the peripheral advertises, the scanner is now able to decrypt encrypted advertising data.
If the board is reset and if the Key Material characteristic has been stored in the flash memory, at the initialization phase the characteristic is restored and used to decrypt advertising data.

1.3. Encryption of Advertising Data

1.3.1. New ACI introduced in BLE stack

ACI_HAL_EAD_ENCRYPT_DECRYPT

This command encrypts or decrypts data.
When encryption mode is selected, In_Data shall only contain the payload field to encrypt. The command adds the randomizer and MIC fields in the result. The result data length (Out_Data_Length) is equal to the input length + 9.
When decryption mode is selected, In_Data shall contain the full encrypted data (randomizer + payload + MIC). The result data length (Out_Data_Length) is equal to the input length - 9.

1.3.2. Input parameters

Bluetooth® LE aci_hal_ead_encrypt_decrypt input parameters
Connectivity Command Input Param.png


1.3.3. Output parameters

Bluetooth® LE aci_hal_ead_encrypt_decrypt output parameters
Connectivity Command Output Param 2.png


1.4. Encrypted data transmission

A new AD type called Encrypted Data (0x31) is defined and used as a container for the data produced by encrypting the sequence of one or more AD types that need to be secured.

In addition to the data payload, the Encrypted Data AD structure’s data field contains a 40-bit randomizer field and a 32-bit message integrity check (MIC).

The figure below shows an example of an advertising payload which contains one AD type (Local Name) that has been encrypted and encapsulated within the Encrypted Data AD type, and one AD type (Flags) that is included unencrypted.

Bluetooth® Low Energy Encrypted Data AD type
Connectivity encapsulated data.png



Info white.png Information
The Randomizer field contains a 5-octet random number generated according to the requirements for random numbers stated in the Bluetooth Core Specification.

A new Randomizer value must be generated every time the payload value changes. The Randomizer value is used in formulating a nonce (Number Used Once), which the CCM algorithm requires.

1.5. Advertising data

At startup, the peer-to-peer EAD server application starts advertising.

The advertised data are composed as follows:

P2P server EAD advertising packet
Description Length AD Type Value
Encrypted Advertising Data 5 0x31 0x00 0x01 0x02 0x03..0xAA (WB)
Device Name 8 0x09 EADS (WB) or EADS_XX (WBA) (XX: last byte of BD address)
Manufacturer Data 15 0xFF See table below
Flags 2 0x01 0x06
(GeneralDiscoverable, BrEdrNotSupported)


1.5.1. Manufacturer data for STM32WB

Manufacturer data are encoded following STMicroelectronics BlueST SDK v1 as described below:

STMicroelectronics manufacturer advertising data
Byte Index 0 1 2-3 4 5 6 7 8 9 10-15
Function Length Manufacturer ID BlueST SDK Version Firmware ID Option 1 Option 2 Option 3 Option 4 Option 5 Device Address
Value 0x0F 0xFF 0x01 0xE2 - p2p Server EAD 0x00 0x00 0x00 0x00 0x00 0x08E126xxxx


1.5.2. Manufacturer data for STM32WBA

Manufacturer data are encoded following STMicroelectronics BlueST SDK v2 as described below:

STMicroelectronics manufacturer advertising data
Byte Index 0 1 2-3 4 5 6 7 8 9 10-15
Function Length Manufacturer ID Company BlueST SDK Version Device ID Firmware ID Option 1 Option 2 Option 3 Device Address
Value 0x0F 0xFF 0x0030 STMicro 0x02 0x8B Nucleo-WBA 0xE2 - p2p Server EAD 0x00 0x00 0x00 0x08E12Axxxx


1.6. STM32WB/WBA EAD central and peripheral applications

Info white.png Information
Either Legacy Advertising or Extended Advertising can be used.

In examples for STM32WB or STM32WBA, extended advertising is used to allow more data in advertising reports.

Refer to the STM32WB Advertising extension page for more details.

EAD Central acts as a central device with the support of the GATT Client Layer.

1.6.1. Example description

1.6.1.1. EAD Client

After reset: EAD Client application initialization

STM32WB-specific:

  • Device starts scanning to detect EAD Server application by filtering the firmware ID of the STMicroelectronics manufacturer advertising data.
  • Push SW2 when devices are not connected; security database is cleared and flash memory sector is erased.

STM32WBA-specific:

  • Push B1: device starts scanning to detect EAD Server application by filtering the firmware ID of the STMicroelectronics manufacturer advertising data

For STM32WB and STM32WBA:

  • Device stops Scanning once the EAD server has been detected.
  • Push SW3/B3: device connects to the EAD Server to establish the connection.
  • Device discovers GAP and GATT services and characteristics of the EAD server.
  • Enable all GATT server notification characteristics.
  • Device starts the pairing procedure.
  • Device performs ATT MTU exchange procedure.
  • Device reads the "Encrypted Data Key Material" characteristic. On STM32WB, the characteristic is stored in the flash memory.
  • Push SW2/B2: device sends a disconnection request.
  • Push SW1/B1: device starts scanning and if the Encrypted Advertising Data AD flag is present, decryption is requested and executed.
1.6.1.2. EAD Server

After reset, the EAD Server application starts one extended advertising set containing an encrypted field.
After disconnection, the peripheral device restarts advertising.

1.6.2. Example flow of commands

The diagram below shows an example of a flow of commands between an EAD server and EAD client.

Flow diagram showing an EAD Server and EAD Client
STM32WB/STM32WBA P2P EAD Flow Diagram


1.7. On-board button configuration

1.7.1. STM32WB

Button configuration for Bluetooth® Low Energy EAD applications on Nucleo-WB55CG boards
Application Condition SW1 Click SW1 Long Press SW2 Click SW2 Long Press SW3 Click SW3 Long Press

EAD Server

Idle / / / / / /
Connected
EAD Client Idle Starts scan, stops when EAD Server is found / Clear security database, flash erase / Sends connection request /
Connected - Sends disconnection request -

1.7.2. STM32WBA

Button configuration for Bluetooth® Low Energy EAD applications on Nucleo-WBA55CG boards
Application Condition B1 Click B1 Long Press B2 Click B2 Long Press B3 Click B3 Long Press

EAD Server

Idle / / / / / /
Connected
EAD Client Idle Starts scan, stops when EAD Server is found / - / Sends connection request /
Connected - Sends disconnection request -

1.8. Collector application compatibility

For STM32WB:
Both projects from STM32WB BLE_p2pServer_EAD_Ext and BLE_p2pClient_EAD_Ext are compatible.

For STM32WBA:
Both projects from STM32WBA BLE_p2pServer_EAD_Ext and BLE_p2pClient_EAD_Ext are compatible.

1.9. Code example

An STM32WB EAD code example (peripheral and central) is available from the STM32-Hotspot GitHub[1].

An STM32WBA EAD code example (peripheral and central) is available from the STM32-Hotspot GitHub[2].

2. References