1 /***************************************************************************** 2 * @file bleplat.h 3 * 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 - if positive or zero, it is the number of copied bytes 110 * - if negative, it is an error status (BLEPLAT_XX) 111 */ 112 extern int BLEPLAT_NvmGet( uint8_t mode, 113 uint8_t type, 114 uint16_t offset, 115 uint8_t* data, 116 uint16_t size ); 117 118 /** 119 * @brief Compare passed data as parameter with data stored in the NVM 120 * @param offset: The offset from which the NVM starts the comparison 121 * @param data: The data to be compared with stored data in the NVM 122 * @param size: The size of data to be compared 123 * @retval - if zero, the comparison was successful (BLEPLAT_OK) 124 * - if positive, the comparison failed 125 * - if negative, it is an error status (BLEPLAT_XX) 126 */ 127 extern int BLEPLAT_NvmCompare( uint16_t offset, 128 const uint8_t* data, 129 uint16_t size ); 130 131 /** 132 * @brief Clear a block from the NVM or the whole NVM, storing the security 133 * database (security and GATT records) 134 * @param mode: Mode of deleting data from the NVM, either clear all the 135 * security database (BLEPLAT_NVM_ALL) or the current read NVM block 136 * (BLEPLAT_NVM_CURRENT) 137 * @retval None 138 */ 139 extern void BLEPLAT_NvmDiscard( uint8_t mode ); 140 141 /* Public Key Algorithms (PKA) interface: 142 */ 143 144 /** 145 * @brief Start P-256 public key generation 146 * @param local_private_key: table of 8 x 32-bit words that contains the 147 * P-256 private key (Little Endian format) 148 * @retval status (BLEPLAT_XX) 149 */ 150 extern int BLEPLAT_PkaStartP256Key( const uint32_t* local_private_key ); 151 152 /** 153 * @brief Get result of P-256 public key generation 154 * @param local_public_key: table of 32 x 32-bit words that is filled by the 155 * function with the generated P-256 public key (Little Endian format) 156 * @retval status (BLEPLAT_XX) 157 */ 158 extern void BLEPLAT_PkaReadP256Key( uint32_t* local_public_key ); 159 160 /** 161 * @brief Start DH key computation 162 * @param local_private_key: table of 8 x 32-bit words that contains the 163 * local P-256 private key (Little Endian format) 164 * @param remote_public_key: table of 32 x 32-bit words that contains the 165 * remote P-256 public key (Little Endian format) 166 * @retval status (BLEPLAT_XX) 167 */ 168 extern int BLEPLAT_PkaStartDhKey( const uint32_t* local_private_key, 169 const uint32_t* remote_public_key ); 170 /** 171 * @brief Get result of DH key computation 172 * @param dh_key: table of 8 x 32-bit words that is filled by the function 173 * with the generated DH key (Little Endian format) 174 * @retval status (BLEPLAT_XX) 175 */ 176 extern int BLEPLAT_PkaReadDhKey( uint32_t* dh_key ); 177 178 /** 179 * @brief Callback function implemented by the Bluetooth LE stack that must 180 * be called by the user to inform the Bluetooth LE stack about 181 * completion of P-256 public key generation or DH key computation 182 * @param None 183 * @retval status (BLEPLAT_XX) 184 */ 185 extern void BLEPLATCB_PkaComplete( void ); 186 187 /* Advanced Encryption Standard (AES) interface: 188 */ 189 190 /** 191 * @brief Encrypt a single 128-bit block with a 128-bit key. 192 * @param key: table of 16 bytes that contains the key to use 193 * (Little Endian format) 194 * @param input: table of 16 bytes that contains the block to encrypt 195 * @param output: table of 16 bytes that is filled by the function with the 196 * encrypted block 197 * @retval None 198 */ 199 extern void BLEPLAT_AesEcbEncrypt( const uint8_t* key, 200 const uint8_t* input, 201 uint8_t* output ); 202 203 /** 204 * @brief Set the 128-bit key to be used for CMAC computation. 205 * @param key: table of 16 bytes that contains the key to use 206 * (Little Endian format) 207 * @retval None 208 */ 209 extern void BLEPLAT_AesCmacSetKey( const uint8_t* key ); 210 211 /** 212 * @brief CMAC computation: the function can be called several times with 213 * output_tag set to 0 to append data to the computation. It must be 214 * called once at the end with output_tag not set at 0 to complete 215 * the CMAC computation. 216 * @param input: table of "input_length" bytes that contains the data to 217 * append for the CMAC computation 218 * @param input_length: number of bytes in "input". 219 * @param output_tag: must be set to 0 for append. 220 * Otherwise: table of 16 bytes that is filled by the function with 221 * the computed CMAC tag. 222 * @retval None 223 */ 224 extern void BLEPLAT_AesCmacCompute( const uint8_t* input, 225 uint32_t input_length, 226 uint8_t* output_tag ); 227 228 /** 229 * @brief CCM computation 230 * 231 * @param mode: CCM mode (0=encryption, 1=decryption) 232 * @param key: AES encryption key (16 bytes) 233 * @param iv_length: IV length (in bytes) 234 * @param iv: IV data 235 * @param add_length: add length (in bytes) 236 * @param add: add data 237 * @param input_length: input data length (in bytes) 238 * @param inputL: original data (to be encrypted or decrypted) 239 * @param tag_length: CCM tag length (in bytes) 240 * @param tag: CCM tag 241 * @param output: result data (encrypted or decrypted) 242 * @retval status (BLEPLAT_XX) 243 */ 244 extern int BLEPLAT_AesCcmCrypt( uint8_t mode, 245 const uint8_t* key, 246 uint8_t iv_length, 247 const uint8_t* iv, 248 uint16_t add_length, 249 const uint8_t* add, 250 uint32_t input_length, 251 const uint8_t* input, 252 uint8_t tag_length, 253 uint8_t* tag, 254 uint8_t* output ); 255 256 /* Random Number Generation (RNG) interface: 257 */ 258 259 /** 260 * @brief Get random values. 261 * @param n: number of 32-bit words to read. 262 * @param val: pointer to a 32-bit table of size"n" that are filled with 263 * random values by the function. 264 * @retval None 265 */ 266 extern void BLEPLAT_RngGet( uint8_t n, 267 uint32_t* val ); 268 269 /* Timer interface: 270 */ 271 272 /** 273 * @brief Start the Timer. 274 * @param id: The timer ID to be started 275 * @param timeout: The timeout needed to stop the timer (in ms) 276 * @retval status (BLEPLAT_XX) 277 */ 278 extern uint8_t BLEPLAT_TimerStart( uint16_t id, 279 uint32_t timeout ); 280 281 /** 282 * @brief Stop the Timer 283 * @param id: The timer ID to be stopped 284 * @retval None 285 */ 286 extern void BLEPLAT_TimerStop( uint16_t id ); 287 288 /** 289 * @brief The timer callback function called when the timeout of a given 290 * timer has elapsed 291 * @param id: The timer ID 292 * @retval None 293 */ 294 extern void BLEPLATCB_TimerExpiry( uint16_t id ); 295 296 297 #endif /* BLEPLAT_H__ */ 298
