1 /* --COPYRIGHT--,BSD 2 * Copyright (c) 2017, Texas Instruments Incorporated 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 9 * * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * * Neither the name of Texas Instruments Incorporated nor the names of 17 * its contributors may be used to endorse or promote products derived 18 * from this software without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 * --/COPYRIGHT--*/ 32 #ifndef AES256_H_ 33 #define AES256_H_ 34 35 //***************************************************************************** 36 // 37 //! \addtogroup aes256_api 38 //! @{ 39 // 40 //***************************************************************************** 41 42 //***************************************************************************** 43 // 44 // If building with a C++ compiler, make all of the definitions in this header 45 // have a C binding. 46 // 47 //***************************************************************************** 48 #ifdef __cplusplus 49 extern "C" 50 { 51 #endif 52 53 #include <stdint.h> 54 #include <stdbool.h> 55 #include <ti/devices/msp432p4xx/inc/msp.h> 56 57 /* Module Defines and macro for easy access */ 58 #define AES256_CMSIS(x) ((AES256_Type *) x) 59 60 //***************************************************************************** 61 // 62 // The following are deprecated values. Please refer to documentation for the 63 // correct values to use. 64 // 65 //***************************************************************************** 66 #define Key_128BIT 128 67 #define Key_192BIT 192 68 #define Key_256BIT 256 69 70 //***************************************************************************** 71 // 72 // The following are values that can be passed to the keyLength parameter for 73 // functions: AES256_setCipherKey(), AES256_setDecipherKey(), and 74 // AES256_startSetDecipherKey(). 75 // 76 //***************************************************************************** 77 #define AES256_KEYLENGTH_128BIT 128 78 #define AES256_KEYLENGTH_192BIT 192 79 #define AES256_KEYLENGTH_256BIT 256 80 81 //***************************************************************************** 82 // 83 // The following are values that can be passed toThe following are values that 84 // can be returned by the AES256_getErrorFlagStatus() function. 85 // 86 //***************************************************************************** 87 #define AES256_ERROR_OCCURRED AES256_CTL0_ERRFG 88 #define AES256_NO_ERROR 0x00 89 90 //***************************************************************************** 91 // 92 // The following are values that can be passed toThe following are values that 93 // can be returned by the AES256_isBusy() function. 94 // 95 //***************************************************************************** 96 #define AES256_BUSY AES256_STAT_BUSY 97 #define AES256_NOT_BUSY 0x00 98 99 //***************************************************************************** 100 // 101 // The following are values that can be passed toThe following are values that 102 // can be returned by the AES256_getInterruptFlagStatus() function. 103 // 104 //***************************************************************************** 105 #define AES256_READY_INTERRUPT 0x01 106 #define AES256_NOTREADY_INTERRUPT 0x00 107 108 //***************************************************************************** 109 // 110 // Prototypes for the APIs. 111 // 112 //***************************************************************************** 113 114 //***************************************************************************** 115 // 116 //! \brief Loads a 128, 192 or 256 bit cipher key to AES256 module. 117 //! 118 //! \param moduleInstance is the base address of the AES256 module. 119 //! \param cipherKey is a pointer to an uint8_t array with a length of 16 bytes 120 //! that contains a 128 bit cipher key. 121 //! \param keyLength is the length of the key. 122 //! Valid values are: 123 //! - \b AES256_KEYLENGTH_128BIT 124 //! - \b AES256_KEYLENGTH_192BIT 125 //! - \b AES256_KEYLENGTH_256BIT 126 //! 127 //! \return true if set correctly, false otherwise 128 // 129 //***************************************************************************** 130 extern bool AES256_setCipherKey(uint32_t moduleInstance, 131 const uint8_t *cipherKey, uint_fast16_t keyLength); 132 133 //***************************************************************************** 134 // 135 //! \brief Encrypts a block of data using the AES256 module. 136 //! 137 //! The cipher key that is used for encryption should be loaded in advance by 138 //! using function AES256_setCipherKey() 139 //! 140 //! \param moduleInstance is the base address of the AES256 module. 141 //! \param data is a pointer to an uint8_t array with a length of 16 bytes that 142 //! contains data to be encrypted. 143 //! \param encryptedData is a pointer to an uint8_t array with a length of 16 144 //! bytes in that the encrypted data will be written. 145 //! 146 //! \return None 147 // 148 //***************************************************************************** 149 extern void AES256_encryptData(uint32_t moduleInstance, const uint8_t *data, 150 uint8_t *encryptedData); 151 152 //***************************************************************************** 153 // 154 //! \brief Decrypts a block of data using the AES256 module. 155 //! 156 //! This function requires a pregenerated decryption key. A key can be loaded 157 //! and pregenerated by using function AES256_setDecipherKey() or 158 //! AES256_startSetDecipherKey(). The decryption takes 167 MCLK. 159 //! 160 //! \param moduleInstance is the base address of the AES256 module. 161 //! \param data is a pointer to an uint8_t array with a length of 16 bytes that 162 //! contains encrypted data to be decrypted. 163 //! \param decryptedData is a pointer to an uint8_t array with a length of 16 164 //! bytes in that the decrypted data will be written. 165 //! 166 //! \return None 167 // 168 //***************************************************************************** 169 extern void AES256_decryptData(uint32_t moduleInstance, const uint8_t *data, 170 uint8_t *decryptedData); 171 172 //***************************************************************************** 173 // 174 //! \brief Sets the decipher key. 175 //! 176 //! The API AES256_startSetDecipherKey or AES256_setDecipherKey must be invoked 177 //! before invoking AES256_startDecryptData. 178 //! 179 //! \param moduleInstance is the base address of the AES256 module. 180 //! \param cipherKey is a pointer to an uint8_t array with a length of 16 bytes 181 //! that contains a 128 bit cipher key. 182 //! \param keyLength is the length of the key. 183 //! Valid values are: 184 //! - \b AES256_KEYLENGTH_128BIT 185 //! - \b AES256_KEYLENGTH_192BIT 186 //! - \b AES256_KEYLENGTH_256BIT 187 //! 188 //! \return true if set, false otherwise 189 // 190 //***************************************************************************** 191 extern bool AES256_setDecipherKey(uint32_t moduleInstance, 192 const uint8_t *cipherKey, uint_fast16_t keyLength); 193 194 //***************************************************************************** 195 // 196 //! \brief Clears the AES256 ready interrupt flag. 197 //! 198 //! \param moduleInstance is the base address of the AES256 module. 199 //! 200 //! Modified bits are \b AESRDYIFG of \b AESACTL0 register. 201 //! 202 //! \return None 203 // 204 //***************************************************************************** 205 extern void AES256_clearInterruptFlag(uint32_t moduleInstance); 206 207 //***************************************************************************** 208 // 209 //! \brief Gets the AES256 ready interrupt flag status. 210 //! 211 //! \param moduleInstance is the base address of the AES256 module. 212 //! 213 //! \return One of the following: 214 //! - \b AES256_READY_INTERRUPT 215 //! - \b AES256_NOTREADY_INTERRUPT 216 //! \n indicating the status of the AES256 ready status 217 // 218 //***************************************************************************** 219 extern uint32_t AES256_getInterruptFlagStatus(uint32_t moduleInstance); 220 221 //***************************************************************************** 222 // 223 //! \brief Enables AES256 ready interrupt. 224 //! 225 //! \param moduleInstance is the base address of the AES256 module. 226 //! 227 //! Modified bits are \b AESRDYIE of \b AESACTL0 register. 228 //! 229 //! \return None 230 // 231 //***************************************************************************** 232 extern void AES256_enableInterrupt(uint32_t moduleInstance); 233 234 //***************************************************************************** 235 // 236 //! \brief Disables AES256 ready interrupt. 237 //! 238 //! \param moduleInstance is the base address of the AES256 module. 239 //! 240 //! Modified bits are \b AESRDYIE of \b AESACTL0 register. 241 //! 242 //! \return None 243 // 244 //***************************************************************************** 245 extern void AES256_disableInterrupt(uint32_t moduleInstance); 246 247 //***************************************************************************** 248 // 249 //! \brief Resets AES256 Module immediately. 250 //! 251 //! \param moduleInstance is the base address of the AES256 module. 252 //! 253 //! Modified bits are \b AESSWRST of \b AESACTL0 register. 254 //! 255 //! \return None 256 // 257 //***************************************************************************** 258 extern void AES256_reset(uint32_t moduleInstance); 259 260 //***************************************************************************** 261 // 262 //! \brief Starts an encryption process on the AES256 module. 263 //! 264 //! The cipher key that is used for decryption should be loaded in advance by 265 //! using function AES256_setCipherKey(). This is a non-blocking equivalent pf 266 //! AES256_encryptData(). It is recommended to use the interrupt functionality 267 //! to check for procedure completion then use the AES256_getDataOut() API to 268 //! retrieve the encrypted data. 269 //! 270 //! \param moduleInstance is the base address of the AES256 module. 271 //! \param data is a pointer to an uint8_t array with a length of 16 bytes that 272 //! contains data to be encrypted. 273 //! 274 //! \return None 275 // 276 //***************************************************************************** 277 extern void AES256_startEncryptData(uint32_t moduleInstance, 278 const uint8_t *data); 279 280 //***************************************************************************** 281 // 282 //! \brief Decypts a block of data using the AES256 module. 283 //! 284 //! This is the non-blocking equivalant of AES256_decryptData(). This function 285 //! requires a pregenerated decryption key. A key can be loaded and 286 //! pregenerated by using function AES256_setDecipherKey() or 287 //! AES256_startSetDecipherKey(). The decryption takes 167 MCLK. It is 288 //! recommended to use interrupt to check for procedure completion then use the 289 //! AES256_getDataOut() API to retrieve the decrypted data. 290 //! 291 //! \param moduleInstance is the base address of the AES256 module. 292 //! \param data is a pointer to an uint8_t array with a length of 16 bytes that 293 //! contains encrypted data to be decrypted. 294 //! 295 //! \return None 296 // 297 //***************************************************************************** 298 extern void AES256_startDecryptData(uint32_t moduleInstance, 299 const uint8_t *data); 300 301 //***************************************************************************** 302 // 303 //! \brief Sets the decipher key 304 //! 305 //! The API AES256_startSetDecipherKey() or AES256_setDecipherKey() must be 306 //! invoked before invoking AES256_startDecryptData. 307 //! 308 //! \param moduleInstance is the base address of the AES256 module. 309 //! \param cipherKey is a pointer to an uint8_t array with a length of 16 bytes 310 //! that contains a 128 bit cipher key. 311 //! \param keyLength is the length of the key. 312 //! Valid values are: 313 //! - \b AES256_KEYLENGTH_128BIT 314 //! - \b AES256_KEYLENGTH_192BIT 315 //! - \b AES256_KEYLENGTH_256BIT 316 //! 317 //! \return true if set correctly, false otherwise 318 // 319 //***************************************************************************** 320 extern bool AES256_startSetDecipherKey(uint32_t moduleInstance, 321 const uint8_t *cipherKey, uint_fast16_t keyLength); 322 323 //***************************************************************************** 324 // 325 //! \brief Reads back the output data from AES256 module. 326 //! 327 //! This function is meant to use after an encryption or decryption process 328 //! that was started and finished by initiating an interrupt by use of 329 //! AES256_startEncryptData or AES256_startDecryptData functions. 330 //! 331 //! \param moduleInstance is the base address of the AES256 module. 332 //! \param outputData is a pointer to an uint8_t array with a length of 16 333 //! bytes in that the data will be written. 334 //! 335 //! \return true if data is valid, otherwise false 336 // 337 //***************************************************************************** 338 extern bool AES256_getDataOut(uint32_t moduleInstance, 339 uint8_t *outputData); 340 341 //***************************************************************************** 342 // 343 //! \brief Gets the AES256 module busy status. 344 //! 345 //! \param moduleInstance is the base address of the AES256 module. 346 //! 347 //! \return true if busy, false otherwise 348 // 349 //***************************************************************************** 350 extern bool AES256_isBusy(uint32_t moduleInstance); 351 352 //***************************************************************************** 353 // 354 //! \brief Clears the AES256 error flag. 355 //! 356 //! \param moduleInstance is the base address of the AES256 module. 357 //! 358 //! Modified bits are \b AESERRFG of \b AESACTL0 register. 359 //! 360 //! \return None 361 // 362 //***************************************************************************** 363 extern void AES256_clearErrorFlag(uint32_t moduleInstance); 364 365 //***************************************************************************** 366 // 367 //! \brief Gets the AES256 error flag status. 368 //! 369 //! \param moduleInstance is the base address of the AES256 module. 370 //! 371 //! \return One of the following: 372 //! - \b AES256_ERROR_OCCURRED 373 //! - \b AES256_NO_ERROR 374 //! \n indicating the error flag status 375 // 376 //***************************************************************************** 377 extern uint32_t AES256_getErrorFlagStatus(uint32_t moduleInstance); 378 379 //***************************************************************************** 380 // 381 //! Registers an interrupt handler for the AES interrupt. 382 //! 383 //! \param moduleInstance Instance of the AES256 module 384 //! 385 //! \param intHandler is a pointer to the function to be called when the 386 //! AES interrupt occurs. 387 //! 388 //! This function registers the handler to be called when a AES 389 //! interrupt occurs. This function enables the global interrupt in the 390 //! interrupt controller; specific AES interrupts must be enabled 391 //! via AES256_enableInterrupt(). It is the interrupt handler's responsibility 392 //! to clear the interrupt source via AES256_clearInterrupt(). 393 //! 394 //! \return None. 395 // 396 //***************************************************************************** 397 extern void AES256_registerInterrupt(uint32_t moduleInstance, 398 void (*intHandler)(void)); 399 400 //***************************************************************************** 401 // 402 //! Unregisters the interrupt handler for the AES interrupt 403 //! 404 //! \param moduleInstance Instance of the AES256 module 405 //! 406 //! This function unregisters the handler to be called when AES 407 //! interrupt occurs. This function also masks off the interrupt in the 408 //! interrupt controller so that the interrupt handler no longer is called. 409 //! 410 //! \sa Interrupt_registerInterrupt() for important information about 411 //! registering interrupt handlers. 412 //! 413 //! \return None. 414 // 415 //***************************************************************************** 416 extern void AES256_unregisterInterrupt(uint32_t moduleInstance); 417 418 //***************************************************************************** 419 // 420 //! Returns the current interrupt flag for the peripheral. 421 //! 422 //! \param moduleInstance Instance of the AES256 module 423 //! 424 //! \return The currently triggered interrupt flag for the module. 425 // 426 //***************************************************************************** 427 extern uint32_t AES256_getInterruptStatus(uint32_t moduleInstance); 428 429 //***************************************************************************** 430 // 431 // Mark the end of the C bindings section for C++ compilers. 432 // 433 //***************************************************************************** 434 #ifdef __cplusplus 435 } 436 #endif 437 438 //***************************************************************************** 439 // 440 // Close the Doxygen group. 441 //! @} 442 // 443 //***************************************************************************** 444 445 #endif /* AES256_H_ */ 446 447
