git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/MSP430FR5969_LaunchPad/driverlib/MSP430FR5xx_6xx/aes256.h

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