Encrypted Advertising Data core API#
Provides simple to use API for Advertising, Periodic Advertising and Scan Response data encryption and decryption that is compatible with the Bluetooth Core Encrypted Advertisement Data (EAD) enhancement. For the usage of the APIs defined in sl_bt_ead_core.h please see esl_core_encrypt_message(void *msg, uint8_t *len) and esl_core_decrypt_message(void *msg, uint8_t *len) functions in esl_tag_crypto.c within ESL Tag core component.
Modules#
Typedefs#
Functions#
Macros#
EAD Randomizer size.
EAD Key Material size.
EAD Session Key size.
EAD Nonce size.
EAD IV size.
EAD Message Integrity Check size.
Advertising Data - header length field size.
Advertising Data - header AD Type field size.
Advertising Data header size, Core Ver.5.3, Vol 3. Part C, Fig.11.1.
EAD Message full packet size overhead.
EAD Message packet size overhead without the length field.
Encrypted Data AD Type.
B1 block, octet 2 (header) for EAD encryption, CSS d11, Part A, 1.23.3.
EAD Key Material Characteristics UUID.
Typedef Documentation#
Function Documentation#
sl_bt_ead_randomizer_update#
sl_status_t sl_bt_ead_randomizer_update (sl_bt_ead_nonce_p nonce)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_bt_ead_nonce_p | N/A | nonce | nonce - Pointer to the EAD Nonce struct to be updated |
Update the Randomizer field of the EAD Nonce value with newly generated value Returns
sl_status_t
sl_bt_ead_randomizer_set#
sl_status_t sl_bt_ead_randomizer_set (sl_bt_ead_randomizer_t randomizer, sl_bt_ead_nonce_p nonce)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_bt_ead_randomizer_t | [in] | randomizer | - Value to be set in the Nonce |
| sl_bt_ead_nonce_p | [out] | nonce | - Pointer to the EAD Nonce struct to be updated |
Set the Randomizer field of the EAD Nonce value manually to a given value Note
Falls back to sl_bt_ead_randomizer_update() if Randomizer is NULL
Returns
sl_status_t
sl_bt_ead_session_init#
sl_status_t sl_bt_ead_session_init (sl_bt_ead_key_material_p key_material, sl_bt_ead_randomizer_t randomizer, sl_bt_ead_nonce_p nonce)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_bt_ead_key_material_p | N/A | key_material | key_material - Pointer to the key material in the higher layer |
| sl_bt_ead_randomizer_t | [in] | randomizer | - Pointer to the desired Randomizer value type or NULL. The Nonce will get a new random value during the invocation if NULL is passed. |
| sl_bt_ead_nonce_p | [out] | nonce | - Pointer to the complete EAD Nonce structure. This can be omitted by advanced users by passing it as NULL, in which case only the session key is prepared. Although passing the nonce is the recommended use case, omitting it can still be useful for efficient in-place decryption when used with sl_bt_ead_unpack_decrypt(). |
(Re)initialize the entire Nonce value with the new key material provided Note
According to the Supplement to the Bluetooth Core Specification v11 Part A, Section 1.23.3: the session key shall be set to a value determined by a higher layer specification or otherwise negotiated between the devices that are sending and receiving the encrypted AD type. Any session keys with at least 128 bits of entropy may be used. The byte order of the session key field will be swapped in-place within the key_material in|out parameter after the invocation!
Returns
sl_status_t
sl_bt_ead_encrypt#
sl_status_t sl_bt_ead_encrypt (sl_bt_ead_key_material_p key_material, sl_bt_ead_nonce_p nonce, uint8_t length, uint8_t * data, sl_bt_ead_mic_t mic)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_bt_ead_key_material_p | [in] | key_material | - Pointer to the key material in the higher layer |
| sl_bt_ead_nonce_p | [in] | nonce | - Pointer to the complete EAD Nonce structure |
| uint8_t | [in] | length | - Length of the data to be encrypted |
| uint8_t * | N/A | data | data - Pointer to the original message, contains encrypted message on success. |
| sl_bt_ead_mic_t | [out] | mic | - Pointer to the mic storage space |
Encrypt message in-place using EAD encryption Returns
sl_status_t
sl_bt_ead_decrypt#
sl_status_t sl_bt_ead_decrypt (sl_bt_ead_key_material_p key_material, sl_bt_ead_nonce_p nonce, sl_bt_ead_mic_t mic, uint8_t length, uint8_t * data)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_bt_ead_key_material_p | [in] | key_material | - Pointer to the key material in the higher layer |
| sl_bt_ead_nonce_p | [in] | nonce | - Pointer to the (received!) Nonce structure |
| sl_bt_ead_mic_t | [in] | mic | - Message integrity check value of the given message |
| uint8_t | [in] | length | - Length of the data to be decrypted |
| uint8_t * | N/A | data | data - Pointer to the encrypted message, contains decrypted message on success. |
Decrypt message in-place that is encrypted with EAD Returns
sl_status_t
sl_bt_ead_unpack_decrypt#
sl_status_t sl_bt_ead_unpack_decrypt (sl_bt_ead_key_material_p key_material, uint8_t ** data, uint8_t * length)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_bt_ead_key_material_p | [in] | key_material | - Pointer to the key material in the higher layer |
| uint8_t ** | N/A | data | data - Reference of the pointer to the full encrypted message in Advertising, Periodic Advertising, and Scan Response data format specified by Core v5.3, Vol 3, Part C, Section 11. Will be updated to the address to the decrypted message on success. |
| uint8_t * | [out] | length | - Length of the decrypted data |
Unpack advertising data that is encrypted with EAD and decrypt the message in place. Note
: This function obfuscates the input data since every operation is done in place for the best possible speed. If the input data memory is allocated on the heap, then its original address and size has to be kept for proper deallocation. Consequently, it's also the caller's responsibility to make a copy of the resulting decrypted message if needed, before freeing up the storage space. Using this method instead of calling sl_bt_ead_unpack_ad_data and then sl_bt_ead_decrypt can be slightly faster, but also requires more care when used.
Returns
sl_status_t
sl_bt_ead_pack_ad_data#
sl_status_t sl_bt_ead_pack_ad_data (sl_bt_ead_ad_structure_p ad_info, uint8_t * size, uint8_t * pack_buf)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_bt_ead_ad_structure_p | [in] | ad_info | - Pointer to the AD Data structure to be packed |
| uint8_t * | N/A | size | size - In: size of the EAD Data buffer, out: packed length |
| uint8_t * | [out] | pack_buf | - Pointer to the complete EAD Data buffer |
Pack encrypted EAD AD_Data to Advertising, Periodic Advertising, and Scan Response data format specified by Core v5.3, Vol 3, Part C, Section 11 Returns
sl_status_t
sl_bt_ead_unpack_ad_data#
sl_status_t sl_bt_ead_unpack_ad_data (uint8_t * packed_data, sl_bt_ead_ad_structure_p ad_info)
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| uint8_t * | [in] | packed_data | - Pointer to the incoming EAD Data |
| sl_bt_ead_ad_structure_p | N/A | ad_info | ad_info - Pointer to the AD Data struct for unpacked results. The 'length' parameter in the struct must be pre-set to the 'ad_data' buffer size. |
Unpack encrypted EAD Data from Advertising, Periodic Advertising, and Scan Response data format specified by Core v5.3, Vol 3, Part C, Section 11 Returns
sl_status_t