1 /***************************************************************************** 2 * @file bleplat.h 3 * @author MDG 4 * @brief This file contains the interface of the BLE platform layer 5 * (lower interface of the BLE stack library). 6 * It is included by the STM32WBX BLE stack library. 7 ***************************************************************************** 8 * @attention 9 * 10 * Copyright (c) 2018-2024 STMicroelectronics. 11 * All rights reserved. 12 * 13 * This software is licensed under terms that can be found in the LICENSE file 14 * in the root directory of this software component. 15 * If no LICENSE file comes with this software, it is provided AS-IS. 16 * 17 ***************************************************************************** 18 */ 19 20 #ifndef BLEPLAT_H__ 21 #define BLEPLAT_H__ 22 23 24 #include <stdint.h> 25 26 /* Enumerated values used for the return of the functions: 27 */ 28 enum 29 { 30 BLEPLAT_OK = 0, /* The function did the job and returns an OK status */ 31 BLEPLAT_FULL = -1, /* The function exits because the HW resource is full */ 32 BLEPLAT_BUSY = -2, /* The function is busy and is not available for the 33 requested operation */ 34 BLEPLAT_EOF = -3, /* The function exits and notifies the HW resource 35 (memory for example) reached the end */ 36 BLEPLAT_WARN = -4, /* The function runs the asked operation and notifies 37 that the HW resource is near to be full */ 38 BLEPLAT_ERROR = -5 /* The function exits due to some issue (memory 39 corruption or buffer overflow for example) */ 40 }; 41 42 /* Enumerated values used for the 'type' of NVM functions: 43 */ 44 enum 45 { 46 BLEPLAT_NVM_TYPE_SEC = 0, 47 BLEPLAT_NVM_TYPE_GATT = 1, 48 }; 49 50 /* Enumerated values used for the 'mode' of NVM functions: 51 */ 52 enum 53 { 54 BLEPLAT_NVM_FIRST = 0, 55 BLEPLAT_NVM_NEXT = 1, 56 BLEPLAT_NVM_CURRENT = 2, 57 BLEPLAT_NVM_ALL = 3 58 }; 59 60 /* General functions: 61 */ 62 63 /** 64 * @brief This function is called by the Bluetooth LE stack when it is 65 * initialized or reset (via hci_reset). The user shall call here the 66 * functions to reset the Timer, AES, PKA, NVM and RNG needed for the 67 * Bluetooth LE stack. 68 * @param None 69 * @retval None 70 */ 71 extern void BLEPLAT_Init( void ); 72 73 /* Non Volatile Memory (NVM) interface: 74 */ 75 76 /** 77 * @brief Store data in the NVM 78 * @param type: The type of data to be stored either security data 79 * (BLEPLAT_NVM_TYPE_SEC) or GATT data (BLEPLAT_NVM_TYPE_GATT) 80 * @param data: The data buffer to be stored 81 * @param size: The size of data to be stored 82 * @param extra_data: If there is extra data to be stored too. If not, this 83 * parameter shall be passed with "NULL" value 84 * @param extra_size: The size of extra data 85 * @retval status (BLEPLAT_XX) 86 */ 87 extern int BLEPLAT_NvmAdd( uint8_t type, 88 const uint8_t* data, 89 uint16_t size, 90 const uint8_t* extra_data, 91 uint16_t extra_size ); 92 93 /** 94 * @brief Read data from the NVM 95 * @param mode: The mode of NVM reading: 96 * - BLEPLAT_NVM_FIRST 97 * used to read the first record of NVM 98 * - BLEPLAT_NVM_NEXT 99 * used to read the next record (after a previous call to 100 * BLEPLAT_NvmGet) 101 * - BLEPLAT_NVM_CURRENT 102 * used to read the same record again (after a previous call to 103 * BLEPLAT_NvmGet) 104 * @param type: The type of data to be read, either security data 105 * (BLEPLAT_NVM_TYPE_SEC) or GATT data (BLEPLAT_NVM_TYPE_GATT) 106 * @param offset: The offset from which the NVM starts the read an operation. 107 * @param data: The pointer to data read by the function 108 * @param size: The size of data to be read 109 * @retval status (BLEPLAT_XX) 110 */ 111 extern int BLEPLAT_NvmGet( uint8_t mode, 112 uint8_t type, 113 uint16_t offset, 114 uint8_t* data, 115 uint16_t size ); 116 117 /** 118 * @brief Compare passed data as parameter with data stored in the NVM 119 * @param offset: The offset from which the NVM starts the comparison 120 * @param data: The data to be compared with stored data in the NVM 121 * @param size: The size of data to be compared 122 * @retval status (BLEPLAT_XX) 123 */ 124 extern int BLEPLAT_NvmCompare( uint16_t offset, 125 const uint8_t* data, 126 uint16_t size ); 127 128 /** 129 * @brief Clear a block from the NVM or the whole NVM, storing the security 130 * database (security and GATT records) 131 * @param mode: Mode of deleting data from the NVM, either clear all the 132 * security database (BLEPLAT_NVM_ALL) or the current read NVM block 133 * (BLEPLAT_NVM_CURRENT) 134 * @retval None 135 */ 136 extern void BLEPLAT_NvmDiscard( uint8_t mode ); 137 138 /* Public Key Algorithms (PKA) interface: 139 */ 140 141 /** 142 * @brief Start P-256 public key generation 143 * @param local_private_key: table of 8 x 32-bit words that contains the 144 * P-256 private key (Little Endian format) 145 * @retval status (BLEPLAT_XX) 146 */ 147 extern int BLEPLAT_PkaStartP256Key( const uint32_t* local_private_key ); 148 149 /** 150 * @brief Get result of P-256 public key generation 151 * @param local_public_key: table of 32 x 32-bit words that is filled by the 152 * function with the generated P-256 public key (Little Endian format) 153 * @retval status (BLEPLAT_XX) 154 */ 155 extern void BLEPLAT_PkaReadP256Key( uint32_t* local_public_key ); 156 157 /** 158 * @brief Start DH key computation 159 * @param local_private_key: table of 8 x 32-bit words that contains the 160 * local P-256 private key (Little Endian format) 161 * @param remote_public_key: table of 32 x 32-bit words that contains the 162 * remote P-256 public key (Little Endian format) 163 * @retval status (BLEPLAT_XX) 164 */ 165 extern int BLEPLAT_PkaStartDhKey( const uint32_t* local_private_key, 166 const uint32_t* remote_public_key ); 167 /** 168 * @brief Get result of DH key computation 169 * @param dh_key: table of 8 x 32-bit words that is filled by the function 170 * with the generated DH key (Little Endian format) 171 * @retval status (BLEPLAT_XX) 172 */ 173 extern int BLEPLAT_PkaReadDhKey( uint32_t* dh_key ); 174 175 /** 176 * @brief Callback function implemented by the Bluetooth LE stack that must 177 * be called by the user to inform the Bluetooth LE stack about 178 * completion of P-256 public key generation or DH key computation 179 * @param None 180 * @retval status (BLEPLAT_XX) 181 */ 182 extern void BLEPLATCB_PkaComplete( void ); 183 184 /* Advanced Encryption Standard (AES) interface: 185 */ 186 187 /** 188 * @brief Encrypt a single 128-bit block with a 128-bit key. 189 * @param key: table of 16 bytes that contains the key to use 190 * (Little Endian format) 191 * @param input: table of 16 bytes that contains the block to encrypt 192 * @param output: table of 16 bytes that is filled by the function with the 193 * encrypted block 194 * @retval None 195 */ 196 extern void BLEPLAT_AesEcbEncrypt( const uint8_t* key, 197 const uint8_t* input, 198 uint8_t* output ); 199 200 /** 201 * @brief Set the 128-bit key to be used for CMAC computation. 202 * @param key: table of 16 bytes that contains the key to use 203 * (Little Endian format) 204 * @retval None 205 */ 206 extern void BLEPLAT_AesCmacSetKey( const uint8_t* key ); 207 208 /** 209 * @brief CMAC computation: the function can be called several times with 210 * output_tag set to 0 to append data to the computation. It must be 211 * called once at the end with output_tag not set at 0 to complete 212 * the CMAC computation. 213 * @param input: table of "input_length" bytes that contains the data to 214 * append for the CMAC computation 215 * @param input_length: number of bytes in "input". 216 * @param output_tag: must be set to 0 for append. 217 * Otherwise: table of 16 bytes that is filled by the function with 218 * the computed CMAC tag. 219 * @retval None 220 */ 221 extern void BLEPLAT_AesCmacCompute( const uint8_t* input, 222 uint32_t input_length, 223 uint8_t* output_tag ); 224 225 /* Random Number Generation (RNG) interface: 226 */ 227 228 /** 229 * @brief Get random values. 230 * @param n: number of 32-bit words to read. 231 * @param val: pointer to a 32-bit table of size"n" that are filled with 232 * random values by the function. 233 * @retval None 234 */ 235 extern void BLEPLAT_RngGet( uint8_t n, 236 uint32_t* val ); 237 238 /* Timer interface: 239 */ 240 241 /** 242 * @brief Start the Timer. 243 * @param id: The timer ID to be started 244 * @param timeout: The timeout needed to stop the timer (in ms) 245 * @retval status (BLEPLAT_XX) 246 */ 247 extern uint8_t BLEPLAT_TimerStart( uint16_t id, 248 uint32_t timeout ); 249 250 /** 251 * @brief Stop the Timer 252 * @param id: The timer ID to be stopped 253 * @retval None 254 */ 255 extern void BLEPLAT_TimerStop( uint16_t id ); 256 257 /** 258 * @brief The timer callback function called when the timeout of a given 259 * timer has elapsed 260 * @param id: The timer ID 261 * @retval None 262 */ 263 extern void BLEPLATCB_TimerExpiry( uint16_t id ); 264 265 266 #endif /* BLEPLAT_H__ */ 267
