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#

sl_bt_ead_key_material_s

sl_bt_ead_nonce_s

sl_bt_ead_ad_structure_s

Functions#

sl_status_t
sl_bt_ead_randomizer_update(sl_bt_ead_nonce_p nonce)
sl_status_t
sl_bt_ead_randomizer_set(sl_bt_ead_randomizer_t randomizer, sl_bt_ead_nonce_p nonce)
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)
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)
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)
sl_status_t
sl_bt_ead_unpack_decrypt(sl_bt_ead_key_material_p key_material, uint8_t **data, uint8_t *length)
sl_status_t
sl_bt_ead_pack_ad_data(sl_bt_ead_ad_structure_p ad_info, uint8_t *size, uint8_t *pack_buf)
sl_status_t
sl_bt_ead_unpack_ad_data(uint8_t *packed_data, sl_bt_ead_ad_structure_p ad_info)

Macros#

#define
SL_BT_EAD_RANDOMIZER_SIZE sizeof(sl_bt_ead_randomizer_t)

EAD Randomizer size.

#define
SL_BT_EAD_KEY_MATERIAL_SIZE sizeof(struct sl_bt_ead_key_material_s)

EAD Key Material size.

#define
SL_BT_EAD_SESSION_KEY_SIZE sizeof(sl_bt_ead_session_key_t)

EAD Session Key size.

#define
SL_BT_EAD_NONCE_SIZE sizeof(struct sl_bt_ead_nonce_s)

EAD Nonce size.

#define
SL_BT_EAD_IV_SIZE sizeof(sl_bt_ead_iv_t)

EAD IV size.

#define
SL_BT_EAD_MIC_SIZE sizeof(sl_bt_ead_mic_t)

EAD Message Integrity Check size.

#define

Advertising Data - header length field size.

#define

Advertising Data - header AD Type field size.

#define

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

#define

EAD Message full packet size overhead.

#define

EAD Message packet size overhead without the length field.

#define

Encrypted Data AD Type.

#define

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

#define

EAD Key Material Characteristics UUID.

Typedef Documentation#

sl_bt_ead_session_key_t#

typedef uint8_t sl_bt_ead_session_key_t[16] [16]

Definition at line 47 of file common/ead_core/sl_bt_ead_core.h

sl_bt_ead_iv_t#

typedef uint8_t sl_bt_ead_iv_t[8] [8]

Definition at line 50 of file common/ead_core/sl_bt_ead_core.h

sl_bt_ead_randomizer_t#

typedef uint8_t sl_bt_ead_randomizer_t[5] [5]

Definition at line 53 of file common/ead_core/sl_bt_ead_core.h

sl_bt_ead_mic_t#

typedef uint8_t sl_bt_ead_mic_t[4] [4]

Definition at line 56 of file common/ead_core/sl_bt_ead_core.h

sl_bt_ead_key_material_p#

typedef struct sl_bt_ead_key_material_s* sl_bt_ead_key_material_p

Definition at line 59 of file common/ead_core/sl_bt_ead_core.h

sl_bt_ead_nonce_p#

typedef struct sl_bt_ead_nonce_s* sl_bt_ead_nonce_p

Definition at line 62 of file common/ead_core/sl_bt_ead_core.h

sl_bt_ead_ad_structure_p#

typedef struct sl_bt_ead_ad_structure_s* sl_bt_ead_ad_structure_p

Definition at line 65 of file common/ead_core/sl_bt_ead_core.h

Function Documentation#

sl_bt_ead_randomizer_update#

sl_status_t sl_bt_ead_randomizer_update (sl_bt_ead_nonce_p nonce)
Parameters
N/Anonce

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


Definition at line 140 of file common/ead_core/sl_bt_ead_core.h

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)
Parameters
[in]randomizer

- Value to be set in the Nonce

[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

Returns

  • sl_status_t


Definition at line 149 of file common/ead_core/sl_bt_ead_core.h

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)
Parameters
N/Akey_material

key_material - Pointer to the key material in the higher layer

[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.

[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


Definition at line 174 of file common/ead_core/sl_bt_ead_core.h

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)
Parameters
[in]key_material

- Pointer to the key material in the higher layer

[in]nonce

- Pointer to the complete EAD Nonce structure

[in]length

- Length of the data to be encrypted

N/Adata

data - Pointer to the original message, contains encrypted message on success.

[out]mic

- Pointer to the mic storage space

Encrypt message in-place using EAD encryption Returns

  • sl_status_t


Definition at line 188 of file common/ead_core/sl_bt_ead_core.h

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)
Parameters
[in]key_material

- Pointer to the key material in the higher layer

[in]nonce

- Pointer to the (received!) Nonce structure

[in]mic

- Message integrity check value of the given message

[in]length

- Length of the data to be decrypted

N/Adata

data - Pointer to the encrypted message, contains decrypted message on success.

Decrypt message in-place that is encrypted with EAD Returns

  • sl_status_t


Definition at line 204 of file common/ead_core/sl_bt_ead_core.h

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)
Parameters
[in]key_material

- Pointer to the key material in the higher layer

N/Adata

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.

[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


Definition at line 231 of file common/ead_core/sl_bt_ead_core.h

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)
Parameters
[in]ad_info

- Pointer to the AD Data structure to be packed

N/Asize

size - In: size of the EAD Data buffer, out: packed length

[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


Definition at line 243 of file common/ead_core/sl_bt_ead_core.h

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)
Parameters
[in]packed_data

- Pointer to the incoming EAD Data

N/Aad_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


Definition at line 256 of file common/ead_core/sl_bt_ead_core.h

Macro Definition Documentation#

SL_BT_EAD_RANDOMIZER_SIZE#

#define SL_BT_EAD_RANDOMIZER_SIZE
Value:
sizeof(sl_bt_ead_randomizer_t)

EAD Randomizer size.


Definition at line 89 of file common/ead_core/sl_bt_ead_core.h

SL_BT_EAD_KEY_MATERIAL_SIZE#

#define SL_BT_EAD_KEY_MATERIAL_SIZE
Value:
sizeof(struct sl_bt_ead_key_material_s)

EAD Key Material size.


Definition at line 92 of file common/ead_core/sl_bt_ead_core.h

SL_BT_EAD_SESSION_KEY_SIZE#

#define SL_BT_EAD_SESSION_KEY_SIZE
Value:
sizeof(sl_bt_ead_session_key_t)

EAD Session Key size.


Definition at line 95 of file common/ead_core/sl_bt_ead_core.h

SL_BT_EAD_NONCE_SIZE#

#define SL_BT_EAD_NONCE_SIZE
Value:
sizeof(struct sl_bt_ead_nonce_s)

EAD Nonce size.


Definition at line 98 of file common/ead_core/sl_bt_ead_core.h

SL_BT_EAD_IV_SIZE#

#define SL_BT_EAD_IV_SIZE
Value:
sizeof(sl_bt_ead_iv_t)

EAD IV size.


Definition at line 101 of file common/ead_core/sl_bt_ead_core.h

SL_BT_EAD_MIC_SIZE#

#define SL_BT_EAD_MIC_SIZE
Value:
sizeof(sl_bt_ead_mic_t)

EAD Message Integrity Check size.


Definition at line 104 of file common/ead_core/sl_bt_ead_core.h

SL_BT_EAD_LENGTH_FIELD_SIZE#

#define SL_BT_EAD_LENGTH_FIELD_SIZE
Value:
sizeof(uint8_t)

Advertising Data - header length field size.


Definition at line 107 of file common/ead_core/sl_bt_ead_core.h

SL_BT_EAD_TYPE_FIELD_SIZE#

#define SL_BT_EAD_TYPE_FIELD_SIZE
Value:
sizeof(uint8_t)

Advertising Data - header AD Type field size.


Definition at line 110 of file common/ead_core/sl_bt_ead_core.h

SL_BT_EAD_HEADER_SIZE#

#define SL_BT_EAD_HEADER_SIZE
Value:
(SL_BT_EAD_LENGTH_FIELD_SIZE \
+ SL_BT_EAD_TYPE_FIELD_SIZE)

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


Definition at line 113 of file common/ead_core/sl_bt_ead_core.h

SL_BT_EAD_PACKET_OVERHEAD#

#define SL_BT_EAD_PACKET_OVERHEAD
Value:
(SL_BT_EAD_RANDOMIZER_SIZE \
+ SL_BT_EAD_MIC_SIZE \
+ SL_BT_EAD_HEADER_SIZE)

EAD Message full packet size overhead.


Definition at line 117 of file common/ead_core/sl_bt_ead_core.h

SL_BT_EAD_PACKET_REDUCED_OVERHEAD#

#define SL_BT_EAD_PACKET_REDUCED_OVERHEAD
Value:
(SL_BT_EAD_RANDOMIZER_SIZE \
+ SL_BT_EAD_MIC_SIZE \
+ SL_BT_EAD_TYPE_FIELD_SIZE)

EAD Message packet size overhead without the length field.


Definition at line 122 of file common/ead_core/sl_bt_ead_core.h

SL_BT_ENCRYPTED_DATA_AD_TYPE#

#define SL_BT_ENCRYPTED_DATA_AD_TYPE
Value:
0x31

Encrypted Data AD Type.


Definition at line 127 of file common/ead_core/sl_bt_ead_core.h

SL_BT_ENCRYPTED_DATA_B1_HEADER#

#define SL_BT_ENCRYPTED_DATA_B1_HEADER
Value:
0xEA

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


Definition at line 130 of file common/ead_core/sl_bt_ead_core.h

SL_BT_ENCRYPTED_KEY_MATERIAL_UUID#

#define SL_BT_ENCRYPTED_KEY_MATERIAL_UUID
Value:
0x2B88

EAD Key Material Characteristics UUID.


Definition at line 133 of file common/ead_core/sl_bt_ead_core.h