Encrypted Advertising Data core API#

sl_bt_ead_session_key_t#

typedef uint8_t sl_bt_ead_session_key_t[16] [16]

sl_bt_ead_iv_t#

typedef uint8_t sl_bt_ead_iv_t[8] [8]

sl_bt_ead_randomizer_t#

typedef uint8_t sl_bt_ead_randomizer_t[5] [5]

sl_bt_ead_mic_t#

typedef uint8_t sl_bt_ead_mic_t[4] [4]

sl_bt_ead_key_material_p#

typedef struct sl_bt_ead_key_material_s* sl_bt_ead_key_material_p

sl_bt_ead_nonce_p#

typedef struct sl_bt_ead_nonce_s* sl_bt_ead_nonce_p

sl_bt_ead_ad_structure_p#

typedef struct sl_bt_ead_ad_structure_s* sl_bt_ead_ad_structure_p

sl_bt_ead_store_key#

sl_status_t sl_bt_ead_store_key (psa_key_usage_t key_usage, psa_key_lifetime_t lifetime, sl_bt_ead_key_material_p key_material, psa_key_id_t * key_id)

Store the key from EAD Key material Note

• In case of unsuccessful return, the original input key material will remain untouched, and therefore, as it's still sensitive data, the caller shall take care of handling it securely (e.g., to sanitize).

Returns

• sl_status_t

sl_bt_ead_delete_key#

sl_status_t sl_bt_ead_delete_key (sl_bt_ead_key_material_p key_material)

Delete EAD key material from both volatile and, if applicable, non-volatile storage. Returns

• sl_status_t

sl_bt_ead_randomizer_update#

sl_status_t sl_bt_ead_randomizer_update (sl_bt_ead_nonce_p nonce)

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)

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)

(Re)initialize the entire Nonce value with the IV from the key material given 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. sl_bt_ead_store_key() has to be called once on the key material after said key negotiation before the session init 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)

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)

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)

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)

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)

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

SL_BT_EAD_RANDOMIZER_SIZE#

#define SL_BT_EAD_RANDOMIZER_SIZE

sizeof(sl_bt_ead_randomizer_t)

EAD Randomizer size.

SL_BT_EAD_KEY_MATERIAL_SIZE#

#define SL_BT_EAD_KEY_MATERIAL_SIZE

sizeof(struct sl_bt_ead_key_material_s)

EAD Key Material size.

SL_BT_EAD_SESSION_KEY_SIZE#

#define SL_BT_EAD_SESSION_KEY_SIZE

sizeof(sl_bt_ead_session_key_t)

EAD Session Key size.

SL_BT_EAD_NONCE_SIZE#

#define SL_BT_EAD_NONCE_SIZE

sizeof(struct sl_bt_ead_nonce_s)

EAD Nonce size.

SL_BT_EAD_IV_SIZE#

#define SL_BT_EAD_IV_SIZE

sizeof(sl_bt_ead_iv_t)

EAD IV size.

SL_BT_EAD_MIC_SIZE#

#define SL_BT_EAD_MIC_SIZE

sizeof(sl_bt_ead_mic_t)

EAD Message Integrity Check size.

SL_BT_EAD_LENGTH_FIELD_SIZE#

#define SL_BT_EAD_LENGTH_FIELD_SIZE

sizeof(uint8_t)

Advertising Data - header length field size.

SL_BT_EAD_TYPE_FIELD_SIZE#

#define SL_BT_EAD_TYPE_FIELD_SIZE

sizeof(uint8_t)

Advertising Data - header AD Type field size.

SL_BT_EAD_HEADER_SIZE#

#define SL_BT_EAD_HEADER_SIZE

Advertising Data header size, Core Ver.5.3, Vol 3. Part C, Fig.11.1.

SL_BT_EAD_PACKET_OVERHEAD#

#define SL_BT_EAD_PACKET_OVERHEAD

EAD Message full packet size overhead.

SL_BT_EAD_PACKET_REDUCED_OVERHEAD#

#define SL_BT_EAD_PACKET_REDUCED_OVERHEAD

EAD Message packet size overhead without the length field.

SL_BT_ENCRYPTED_DATA_AD_TYPE#

#define SL_BT_ENCRYPTED_DATA_AD_TYPE

0x31

Encrypted Data AD Type.

SL_BT_ENCRYPTED_DATA_B1_HEADER#

#define SL_BT_ENCRYPTED_DATA_B1_HEADER

0xEA

B1 block, octet 2 (header) for EAD encryption, CSS d11, Part A, 1.23.3.

SL_BT_ENCRYPTED_KEY_MATERIAL_UUID#

#define SL_BT_ENCRYPTED_KEY_MATERIAL_UUID

0x2B88

EAD Key Material Characteristics UUID.