1. Bluetooth® Low Energy Encrypted Advertising feature
The figure below details the Bluetooth® Low Energy Encrypted Advertising feature.
| Bluetooth® Encrypted Advertising feature |
|---|
 |
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 |
|---|
 |
| Bluetooth® Encrypted Data Key Material characteristic Indication |
|---|
 |
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 |
|---|
 |
1.3.3. Output parameters
| Bluetooth® LE aci_hal_ead_encrypt_decrypt output parameters |
|---|
 |
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 |
|---|
 |
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 | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
1.5.1. Manufacturer data for STM32WB
Manufacturer data are encoded following STMicroelectronics BlueST SDK v1 as described below:
| STMicroelectronics manufacturer advertising data | |||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
1.5.2. Manufacturer data for STM32WBA
Manufacturer data are encoded following STMicroelectronics BlueST SDK v2 as described below:
| STMicroelectronics manufacturer advertising data | |||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
1.6. STM32WB/WBA EAD central and peripheral applications
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 |
|---|
 |
1.7. On-board button configuration
1.7.1. STM32WB
| Button configuration for Bluetooth® Low Energy EAD applications on Nucleo-WB55CG boards | |||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
1.7.2. STM32WBA
| Button configuration for Bluetooth® Low Energy EAD applications on Nucleo-WBA55CG boards | |||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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