2 * -------------------------------------------
3 * MSP432 DriverLib - v01_04_00_18
4 * -------------------------------------------
6 * --COPYRIGHT--,BSD,BSD
7 * Copyright (c) 2015, Texas Instruments Incorporated
10 * Redistribution and use in source and binary forms, with or without
11 * modification, are permitted provided that the following conditions
14 * * Redistributions of source code must retain the above copyright
15 * notice, this list of conditions and the following disclaimer.
17 * * Redistributions in binary form must reproduce the above copyright
18 * notice, this list of conditions and the following disclaimer in the
19 * documentation and/or other materials provided with the distribution.
21 * * Neither the name of Texas Instruments Incorporated nor the names of
22 * its contributors may be used to endorse or promote products derived
23 * from this software without specific prior written permission.
25 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
26 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
27 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
29 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
30 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
31 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
32 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
33 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
34 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
35 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
40 //*****************************************************************************
42 //! \addtogroup aes256_api
45 //*****************************************************************************
47 //*****************************************************************************
49 // If building with a C++ compiler, make all of the definitions in this header
52 //*****************************************************************************
62 /* Module Defines and macro for easy access */
63 #define AES256_CMSIS(x) ((AES256_Type *) x)
65 //*****************************************************************************
67 // The following are deprecated values. Please refer to documentation for the
68 // correct values to use.
70 //*****************************************************************************
71 #define Key_128BIT 128
72 #define Key_192BIT 192
73 #define Key_256BIT 256
75 //*****************************************************************************
77 // The following are values that can be passed to the keyLength parameter for
78 // functions: AES256_setCipherKey(), AES256_setDecipherKey(), and
79 // AES256_startSetDecipherKey().
81 //*****************************************************************************
82 #define AES256_KEYLENGTH_128BIT 128
83 #define AES256_KEYLENGTH_192BIT 192
84 #define AES256_KEYLENGTH_256BIT 256
86 //*****************************************************************************
88 // The following are values that can be passed toThe following are values that
89 // can be returned by the AES256_getErrorFlagStatus() function.
91 //*****************************************************************************
92 #define AES256_ERROR_OCCURRED AESERRFG
93 #define AES256_NO_ERROR 0x00
95 //*****************************************************************************
97 // The following are values that can be passed toThe following are values that
98 // can be returned by the AES256_isBusy() function.
100 //*****************************************************************************
101 #define AES256_BUSY AESBUSY
102 #define AES256_NOT_BUSY 0x00
104 //*****************************************************************************
106 // The following are values that can be passed toThe following are values that
107 // can be returned by the AES256_getInterruptFlagStatus() function.
109 //*****************************************************************************
110 #define AES256_READY_INTERRUPT 0x01
111 #define AES256_NOTREADY_INTERRUPT 0x00
113 //*****************************************************************************
115 // Prototypes for the APIs.
117 //*****************************************************************************
119 //*****************************************************************************
121 //! \brief Loads a 128, 192 or 256 bit cipher key to AES256 module.
123 //! \param moduleInstance is the base address of the AES256 module.
124 //! \param cipherKey is a pointer to an uint8_t array with a length of 16 bytes
125 //! that contains a 128 bit cipher key.
126 //! \param keyLength is the length of the key.
127 //! Valid values are:
128 //! - \b AES256_KEYLENGTH_128BIT
129 //! - \b AES256_KEYLENGTH_192BIT
130 //! - \b AES256_KEYLENGTH_256BIT
132 //! \return true if set correctly, false otherwise
134 //*****************************************************************************
135 extern bool AES256_setCipherKey(uint32_t moduleInstance,
136 const uint8_t *cipherKey, uint_fast16_t keyLength);
138 //*****************************************************************************
140 //! \brief Encrypts a block of data using the AES256 module.
142 //! The cipher key that is used for encryption should be loaded in advance by
143 //! using function AES256_setCipherKey()
145 //! \param moduleInstance is the base address of the AES256 module.
146 //! \param data is a pointer to an uint8_t array with a length of 16 bytes that
147 //! contains data to be encrypted.
148 //! \param encryptedData is a pointer to an uint8_t array with a length of 16
149 //! bytes in that the encrypted data will be written.
153 //*****************************************************************************
154 extern void AES256_encryptData(uint32_t moduleInstance, const uint8_t *data,
155 uint8_t *encryptedData);
157 //*****************************************************************************
159 //! \brief Decrypts a block of data using the AES256 module.
161 //! This function requires a pregenerated decryption key. A key can be loaded
162 //! and pregenerated by using function AES256_setDecipherKey() or
163 //! AES256_startSetDecipherKey(). The decryption takes 167 MCLK.
165 //! \param moduleInstance is the base address of the AES256 module.
166 //! \param data is a pointer to an uint8_t array with a length of 16 bytes that
167 //! contains encrypted data to be decrypted.
168 //! \param decryptedData is a pointer to an uint8_t array with a length of 16
169 //! bytes in that the decrypted data will be written.
173 //*****************************************************************************
174 extern void AES256_decryptData(uint32_t moduleInstance, const uint8_t *data,
175 uint8_t *decryptedData);
177 //*****************************************************************************
179 //! \brief Sets the decipher key.
181 //! The API AES256_startSetDecipherKey or AES256_setDecipherKey must be invoked
182 //! before invoking AES256_startDecryptData.
184 //! \param moduleInstance is the base address of the AES256 module.
185 //! \param cipherKey is a pointer to an uint8_t array with a length of 16 bytes
186 //! that contains a 128 bit cipher key.
187 //! \param keyLength is the length of the key.
188 //! Valid values are:
189 //! - \b AES256_KEYLENGTH_128BIT
190 //! - \b AES256_KEYLENGTH_192BIT
191 //! - \b AES256_KEYLENGTH_256BIT
193 //! \return true if set, false otherwise
195 //*****************************************************************************
196 extern bool AES256_setDecipherKey(uint32_t moduleInstance,
197 const uint8_t *cipherKey, uint_fast16_t keyLength);
199 //*****************************************************************************
201 //! \brief Clears the AES256 ready interrupt flag.
203 //! \param moduleInstance is the base address of the AES256 module.
205 //! Modified bits are \b AESRDYIFG of \b AESACTL0 register.
209 //*****************************************************************************
210 extern void AES256_clearInterruptFlag(uint32_t moduleInstance);
212 //*****************************************************************************
214 //! \brief Gets the AES256 ready interrupt flag status.
216 //! \param moduleInstance is the base address of the AES256 module.
218 //! \return One of the following:
219 //! - \b AES256_READY_INTERRUPT
220 //! - \b AES256_NOTREADY_INTERRUPT
221 //! \n indicating the status of the AES256 ready status
223 //*****************************************************************************
224 extern uint32_t AES256_getInterruptFlagStatus(uint32_t moduleInstance);
226 //*****************************************************************************
228 //! \brief Enables AES256 ready interrupt.
230 //! \param moduleInstance is the base address of the AES256 module.
232 //! Modified bits are \b AESRDYIE of \b AESACTL0 register.
236 //*****************************************************************************
237 extern void AES256_enableInterrupt(uint32_t moduleInstance);
239 //*****************************************************************************
241 //! \brief Disables AES256 ready interrupt.
243 //! \param moduleInstance is the base address of the AES256 module.
245 //! Modified bits are \b AESRDYIE of \b AESACTL0 register.
249 //*****************************************************************************
250 extern void AES256_disableInterrupt(uint32_t moduleInstance);
252 //*****************************************************************************
254 //! \brief Resets AES256 Module immediately.
256 //! \param moduleInstance is the base address of the AES256 module.
258 //! Modified bits are \b AESSWRST of \b AESACTL0 register.
262 //*****************************************************************************
263 extern void AES256_reset(uint32_t moduleInstance);
265 //*****************************************************************************
267 //! \brief Starts an encryption process on the AES256 module.
269 //! The cipher key that is used for decryption should be loaded in advance by
270 //! using function AES256_setCipherKey(). This is a non-blocking equivalent pf
271 //! AES256_encryptData(). It is recommended to use the interrupt functionality
272 //! to check for procedure completion then use the AES256_getDataOut() API to
273 //! retrieve the encrypted data.
275 //! \param moduleInstance is the base address of the AES256 module.
276 //! \param data is a pointer to an uint8_t array with a length of 16 bytes that
277 //! contains data to be encrypted.
281 //*****************************************************************************
282 extern void AES256_startEncryptData(uint32_t moduleInstance,
283 const uint8_t *data);
285 //*****************************************************************************
287 //! \brief Decypts a block of data using the AES256 module.
289 //! This is the non-blocking equivalant of AES256_decryptData(). This function
290 //! requires a pregenerated decryption key. A key can be loaded and
291 //! pregenerated by using function AES256_setDecipherKey() or
292 //! AES256_startSetDecipherKey(). The decryption takes 167 MCLK. It is
293 //! recommended to use interrupt to check for procedure completion then use the
294 //! AES256_getDataOut() API to retrieve the decrypted data.
296 //! \param moduleInstance is the base address of the AES256 module.
297 //! \param data is a pointer to an uint8_t array with a length of 16 bytes that
298 //! contains encrypted data to be decrypted.
302 //*****************************************************************************
303 extern void AES256_startDecryptData(uint32_t moduleInstance,
304 const uint8_t *data);
306 //*****************************************************************************
308 //! \brief Sets the decipher key
310 //! The API AES256_startSetDecipherKey() or AES256_setDecipherKey() must be
311 //! invoked before invoking AES256_startDecryptData.
313 //! \param moduleInstance is the base address of the AES256 module.
314 //! \param cipherKey is a pointer to an uint8_t array with a length of 16 bytes
315 //! that contains a 128 bit cipher key.
316 //! \param keyLength is the length of the key.
317 //! Valid values are:
318 //! - \b AES256_KEYLENGTH_128BIT
319 //! - \b AES256_KEYLENGTH_192BIT
320 //! - \b AES256_KEYLENGTH_256BIT
322 //! \return true if set correctly, false otherwise
324 //*****************************************************************************
325 extern bool AES256_startSetDecipherKey(uint32_t moduleInstance,
326 const uint8_t *cipherKey, uint_fast16_t keyLength);
328 //*****************************************************************************
330 //! \brief Reads back the output data from AES256 module.
332 //! This function is meant to use after an encryption or decryption process
333 //! that was started and finished by initiating an interrupt by use of
334 //! AES256_startEncryptData or AES256_startDecryptData functions.
336 //! \param moduleInstance is the base address of the AES256 module.
337 //! \param outputData is a pointer to an uint8_t array with a length of 16
338 //! bytes in that the data will be written.
340 //! \return true if data is valid, otherwise false
342 //*****************************************************************************
343 extern bool AES256_getDataOut(uint32_t moduleInstance,
344 uint8_t *outputData);
346 //*****************************************************************************
348 //! \brief Gets the AES256 module busy status.
350 //! \param moduleInstance is the base address of the AES256 module.
352 //! \return true if busy, false otherwise
354 //*****************************************************************************
355 extern bool AES256_isBusy(uint32_t moduleInstance);
357 //*****************************************************************************
359 //! \brief Clears the AES256 error flag.
361 //! \param moduleInstance is the base address of the AES256 module.
363 //! Modified bits are \b AESERRFG of \b AESACTL0 register.
367 //*****************************************************************************
368 extern void AES256_clearErrorFlag(uint32_t moduleInstance);
370 //*****************************************************************************
372 //! \brief Gets the AES256 error flag status.
374 //! \param moduleInstance is the base address of the AES256 module.
376 //! \return One of the following:
377 //! - \b AES256_ERROR_OCCURRED
378 //! - \b AES256_NO_ERROR
379 //! \n indicating the error flag status
381 //*****************************************************************************
382 extern uint32_t AES256_getErrorFlagStatus(uint32_t moduleInstance);
384 //*****************************************************************************
386 //! Registers an interrupt handler for the AES interrupt.
388 //! \param moduleInstance Instance of the AES256 module
390 //! \param intHandler is a pointer to the function to be called when the
391 //! AES interrupt occurs.
393 //! This function registers the handler to be called when a AES
394 //! interrupt occurs. This function enables the global interrupt in the
395 //! interrupt controller; specific AES interrupts must be enabled
396 //! via AES256_enableInterrupt(). It is the interrupt handler's responsibility
397 //! to clear the interrupt source via AES256_clearInterrupt().
401 //*****************************************************************************
402 extern void AES256_registerInterrupt(uint32_t moduleInstance,
403 void (*intHandler)(void));
405 //*****************************************************************************
407 //! Unregisters the interrupt handler for the AES interrupt
409 //! \param moduleInstance Instance of the AES256 module
411 //! This function unregisters the handler to be called when AES
412 //! interrupt occurs. This function also masks off the interrupt in the
413 //! interrupt controller so that the interrupt handler no longer is called.
415 //! \sa Interrupt_registerInterrupt() for important information about
416 //! registering interrupt handlers.
420 //*****************************************************************************
421 extern void AES256_unregisterInterrupt(uint32_t moduleInstance);
423 //*****************************************************************************
425 //! Returns the current interrupt flag for the peripheral.
427 //! \param moduleInstance Instance of the AES256 module
429 //! \return The currently triggered interrupt flag for the module.
431 //*****************************************************************************
432 extern uint32_t AES256_getInterruptStatus(uint32_t moduleInstance);
434 //*****************************************************************************
436 // Mark the end of the C bindings section for C++ compilers.
438 //*****************************************************************************
443 //*****************************************************************************
445 // Close the Doxygen group.
448 //*****************************************************************************
450 #endif /* AES256_H_ */