STM32WB-WBA Bluetooth® LE – Encrypted Advertising (EAD)

Revision as of 08:28, 22 May 2024 by Registered User (→‎Example flow of commands)


1. STM32WB-WBA Encrypted Advertising

Bluetooth® Encrypted Advertising feature
Connectivity:Connectivity EAD 1.png


1.1. Principles

Encrypted Advertising Data (EAD) is a feature that adds the ability to encrypt advertising data.
Encrypted advertisement data can be received by any device but can only be decrypted by devices that have previously shared the session key.
This feature allows encrypting the totality or just a sub-set of the payload on a given advertising packet by adding a new AD type called Encrypted Advertising Data (type 0x31) that encapsulates all the AD fields to be encrypted.

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

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

The peer device, receiving advertising reports containing AD type "Encrypted Advertising Data" is able to decode encrypted data using the previously read Encrypted Data Key Material.

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
Bluetooth® Read Encrypted Data Key Material characteristic
Connectivity read charac.png


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


1.2. Encryption of Advertising data

1.2.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 plus 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 minus 9.

1.2.2. Input parameters

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


1.2.3. Output parameters

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


1.3. Transmission of encrypted data

A new AD type called Encrypted Data (0x31) is defined to be 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).

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

Bluetooth® LE Encrypted Data AD type
Connectivity encapsulated data.png



Info white.png Information
The Randomizer field contains a 5-octet random number generated per 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 which the CCM algorithm requires.

1.4. Advertising data

At startup, Peer To Peer EAD Server application starts Advertising.
Data advertised are composed as follows:

P2P Server EAD Advertising packet
Description Length AD Type Value
Encrypted Advertising Data 5 0x31 0x62 0x6F 0x6E 0x6A 0x6F
Device Name 8 0x09 EADS_XX (XX: last byte of BD address)
Manufacturer Data 15 0xFF See table below
Flags 2 0x01 0x06
(GeneralDiscoverable, BrEdrNotSupported)


1.4.1. 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.4.2. 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.5. STM32WB/STM32WBA 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 adverting reports.


See also STM32WB Advertising extension page

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

1.5.1. Example description

1.5.1.1. EAD Client

At reset, EAD Client application initialization

Specific to STM32WB

  • Starts scanning to detect EAD Server application by filtering the Firmware ID of the STMicroelectronics Manufacturer advertising data

Specific to STM32WBA

  • Push B1: Starts scanning to detect EAD Server application by filtering the Firmware ID of the STMicroelectronics Manufacturer advertising data

For STM32WB and STM32WBA

  • Stops Scanning once EAD server detected
  • Push SW3/B3: Connects to the EAD Server to establish the connection.
  • Discovers GAP and GATT Services & Characteristics of the EAD server
  • Enable all GATT server notification characteristics
  • Starts pairing procedure
  • Performs ATT MTU exchange procedure
  • Reads "Encrypted Data Key Material" characteristic
  • Push SW2/B2: Sends disconnection request
  • Push SW1/B1: starts scanning, if Encrypted Advertising Data AD flag is present, decryption is requested and successed.

EAD Peripheral acts as a Peripheral device with the support of GATT Server Layer.

1.5.1.2. EAD Server

At reset, EAD Server application starts one extended advertising set containing an encrypted field.

  • After disconnection, peripheral restarts advertising.

1.5.2. Example flow of commands

Example of flow diagram between EAD Server & EAD Client
STM32WB/STM32WBA P2P EAD Flow Diagram


1.6. On-board buttons configuration

1.6.1. STM32WB and STM32WBA

Button configuration for Bluetooth® Low Energy EAD applications on Nucleo-WB55CG and Nucleo-WBA55CG boards
Application Condition SW1/B1 Click SW1/B1 Long Press SW2/B2 Click SW2/B2 Long Press SW3/B3 Click SW3/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.7. Collector applications 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.8. Code example

A STM32WB EAD code example (peripheral and central) will be shared on STM32-Hotspot GitHub [1]

A STM32WBA EAD code example (peripheral and central) will be shared on STM32-Hotspot GitHub [2]

2. References

No categories assignedEdit