1. STM32WB-WBA Encrypted Advertising
Bluetooth® Encrypted Advertising feature |
---|
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 |
---|
Bluetooth® Encrypted Data Key Material characteristic Indication |
---|
1.2. How to implement on STM32WB-WBA applications
1.2.1. Peripheral
Add a new characteristic: Encrypted Data Key Material (UUID = 0x2B88) to 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
Discover Encrypted Data Key Material characteristic added to GAP service (among all characteristics).
Before first connection, when peripheral advertises, scanner is not able to decrypt encrypted advertising data.
When devices are bonded and central is able to read the Key Material characteristic, it stores it in flash.
At second connection (devices have been previously bonded), when peripheral advertises, scanner is able to decrypt encrypted advertising data.
If the board is reset, at initialization phase, if Key Material characteristic has been stored in flash, it 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 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.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. 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 |
---|
1.5. Advertising data
At startup, Peer To Peer EAD Server application starts Advertising.
Data advertised are composed as follows:
P2P Server EAD Advertising packet | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
1.5.1. STM32WB
Manufacturer data are encoded following STMicroelectronics BlueST SDK v1 as described below:
STMicroelectronics Manufacturer Advertising data | |||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
1.5.2. STM32WBA
Manufacturer data are encoded following STMicroelectronics BlueST SDK v2 as described below:
STMicroelectronics Manufacturer Advertising data | |||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
1.6. STM32WB/STM32WBA EAD Central and Peripheral applications
See also STM32WB Advertising extension page
EAD Central acts as a Central device with the support of GATT Client Layer.
1.6.1. Example description
1.6.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
- Push SW2 when devices are not connected: clear of security database and flash sector is erased.
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. On STM32WB, characteristic is stored in flash.
- Push SW2/B2: Sends disconnection request
- Push SW1/B1: starts scanning, if Encrypted Advertising Data AD flag is present, decryption is requested and successed.
1.6.1.2. EAD Server
At reset, EAD Server application starts one extended advertising set containing an encrypted field.
- After disconnection, peripheral restarts advertising.
1.6.2. Example flow of commands
Example of flow diagram between EAD Server & EAD Client |
---|
1.6.3. Example flow of commands with a new writable characteristic transmitted from Web Bluetooth or HCI BLE Toolbox
Example of flow diagram between EAD write Server/Client and smartphone |
---|
Example of flow diagram between EAD write Server and EAD write Client after write of Encryption Key Mirror characteristic |
---|
1.7. On-board buttons 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 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.9. 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]