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#
sl_bt_ead_session_key_t#
typedef uint8_t sl_bt_ead_session_key_t[16] [16]
47 of file common/ead_core/sl_bt_ead_core.hsl_bt_ead_iv_t#
typedef uint8_t sl_bt_ead_iv_t[8] [8]
50 of file common/ead_core/sl_bt_ead_core.hsl_bt_ead_randomizer_t#
typedef uint8_t sl_bt_ead_randomizer_t[5] [5]
53 of file common/ead_core/sl_bt_ead_core.hsl_bt_ead_mic_t#
typedef uint8_t sl_bt_ead_mic_t[4] [4]
56 of file common/ead_core/sl_bt_ead_core.hsl_bt_ead_key_material_p#
typedef struct sl_bt_ead_key_material_s* sl_bt_ead_key_material_p
59 of file common/ead_core/sl_bt_ead_core.hsl_bt_ead_nonce_p#
typedef struct sl_bt_ead_nonce_s* sl_bt_ead_nonce_p
62 of file common/ead_core/sl_bt_ead_core.hsl_bt_ead_ad_structure_p#
typedef struct sl_bt_ead_ad_structure_s* sl_bt_ead_ad_structure_p
65 of file common/ead_core/sl_bt_ead_core.hFunction Documentation#
sl_bt_ead_randomizer_update#
sl_status_t sl_bt_ead_randomizer_update (sl_bt_ead_nonce_p nonce)
| 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
140 of file common/ead_core/sl_bt_ead_core.hsl_bt_ead_randomizer_set#
sl_status_t sl_bt_ead_randomizer_set (sl_bt_ead_randomizer_t randomizer, sl_bt_ead_nonce_p nonce)
| [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
Falls back to sl_bt_ead_randomizer_update() if Randomizer is NULL
Returns
sl_status_t
149 of file common/ead_core/sl_bt_ead_core.hsl_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)
| N/A | key_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
174 of file common/ead_core/sl_bt_ead_core.hsl_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)
| [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/A | data | 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
188 of file common/ead_core/sl_bt_ead_core.hsl_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)
| [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/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
204 of file common/ead_core/sl_bt_ead_core.hsl_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)
| [in] | key_material | - Pointer to the key material in the higher layer |
| 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. |
| [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
231 of file common/ead_core/sl_bt_ead_core.hsl_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)
| [in] | ad_info | - Pointer to the AD Data structure to be packed |
| N/A | size | 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
243 of file common/ead_core/sl_bt_ead_core.hsl_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)
| [in] | packed_data | - Pointer to the incoming EAD Data |
| 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
256 of file common/ead_core/sl_bt_ead_core.hMacro Definition Documentation#
SL_BT_EAD_RANDOMIZER_SIZE#
#define SL_BT_EAD_RANDOMIZER_SIZEValue:
sizeof(sl_bt_ead_randomizer_t)
EAD Randomizer size.
89 of file common/ead_core/sl_bt_ead_core.hSL_BT_EAD_KEY_MATERIAL_SIZE#
#define SL_BT_EAD_KEY_MATERIAL_SIZEValue:
sizeof(struct sl_bt_ead_key_material_s)
EAD Key Material size.
92 of file common/ead_core/sl_bt_ead_core.hSL_BT_EAD_SESSION_KEY_SIZE#
#define SL_BT_EAD_SESSION_KEY_SIZEValue:
sizeof(sl_bt_ead_session_key_t)
EAD Session Key size.
95 of file common/ead_core/sl_bt_ead_core.hSL_BT_EAD_NONCE_SIZE#
#define SL_BT_EAD_NONCE_SIZEValue:
sizeof(struct sl_bt_ead_nonce_s)
EAD Nonce size.
98 of file common/ead_core/sl_bt_ead_core.hSL_BT_EAD_IV_SIZE#
#define SL_BT_EAD_IV_SIZEValue:
sizeof(sl_bt_ead_iv_t)
EAD IV size.
101 of file common/ead_core/sl_bt_ead_core.hSL_BT_EAD_MIC_SIZE#
#define SL_BT_EAD_MIC_SIZEValue:
sizeof(sl_bt_ead_mic_t)
EAD Message Integrity Check size.
104 of file common/ead_core/sl_bt_ead_core.hSL_BT_EAD_LENGTH_FIELD_SIZE#
#define SL_BT_EAD_LENGTH_FIELD_SIZEValue:
sizeof(uint8_t)
Advertising Data - header length field size.
107 of file common/ead_core/sl_bt_ead_core.hSL_BT_EAD_TYPE_FIELD_SIZE#
#define SL_BT_EAD_TYPE_FIELD_SIZEValue:
sizeof(uint8_t)
Advertising Data - header AD Type field size.
110 of file common/ead_core/sl_bt_ead_core.hSL_BT_EAD_HEADER_SIZE#
#define SL_BT_EAD_HEADER_SIZEValue:
Advertising Data header size, Core Ver.5.3, Vol 3. Part C, Fig.11.1.
113 of file common/ead_core/sl_bt_ead_core.hSL_BT_EAD_PACKET_OVERHEAD#
#define SL_BT_EAD_PACKET_OVERHEADValue:
EAD Message full packet size overhead.
117 of file common/ead_core/sl_bt_ead_core.hSL_BT_EAD_PACKET_REDUCED_OVERHEAD#
#define SL_BT_EAD_PACKET_REDUCED_OVERHEADValue:
EAD Message packet size overhead without the length field.
122 of file common/ead_core/sl_bt_ead_core.hSL_BT_ENCRYPTED_DATA_AD_TYPE#
#define SL_BT_ENCRYPTED_DATA_AD_TYPEValue:
0x31
Encrypted Data AD Type.
127 of file common/ead_core/sl_bt_ead_core.hSL_BT_ENCRYPTED_DATA_B1_HEADER#
#define SL_BT_ENCRYPTED_DATA_B1_HEADERValue:
0xEA
B1 block, octet 2 (header) for EAD encryption, CSS d11, Part A, 1.23.3.
130 of file common/ead_core/sl_bt_ead_core.hSL_BT_ENCRYPTED_KEY_MATERIAL_UUID#
#define SL_BT_ENCRYPTED_KEY_MATERIAL_UUIDValue:
0x2B88
EAD Key Material Characteristics UUID.
133 of file common/ead_core/sl_bt_ead_core.h