ON Semiconductor / mbed-os

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   mbed-TFT-example-NCS36510 mbed-Accelerometer-example-NCS36510 mbed-Accelerometer-example-NCS36510

targets/TARGET_Maxim/TARGET_MAX32625/mxc/aes.h@0:098463de4c5d, 2017-01-25 (annotated)

Committer:
group-onsemi
Date:
Wed Jan 25 20:34:15 2017 +0000
Revision:
0:098463de4c5d
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
group-onsemi 0:098463de4c5d 1 /**
group-onsemi 0:098463de4c5d 2 * @file aes.h
group-onsemi 0:098463de4c5d 3 * @brief Advanced Encryption Standard (AES) function prototypes and data types.
group-onsemi 0:098463de4c5d 4 */
group-onsemi 0:098463de4c5d 5
group-onsemi 0:098463de4c5d 6 /* ****************************************************************************
group-onsemi 0:098463de4c5d 7 * Copyright (C) 2016 Maxim Integrated Products, Inc., All Rights Reserved.
group-onsemi 0:098463de4c5d 8 *
group-onsemi 0:098463de4c5d 9 * Permission is hereby granted, free of charge, to any person obtaining a
group-onsemi 0:098463de4c5d 10 * copy of this software and associated documentation files (the "Software"),
group-onsemi 0:098463de4c5d 11 * to deal in the Software without restriction, including without limitation
group-onsemi 0:098463de4c5d 12 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
group-onsemi 0:098463de4c5d 13 * and/or sell copies of the Software, and to permit persons to whom the
group-onsemi 0:098463de4c5d 14 * Software is furnished to do so, subject to the following conditions:
group-onsemi 0:098463de4c5d 15 *
group-onsemi 0:098463de4c5d 16 * The above copyright notice and this permission notice shall be included
group-onsemi 0:098463de4c5d 17 * in all copies or substantial portions of the Software.
group-onsemi 0:098463de4c5d 18 *
group-onsemi 0:098463de4c5d 19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
group-onsemi 0:098463de4c5d 20 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
group-onsemi 0:098463de4c5d 21 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
group-onsemi 0:098463de4c5d 22 * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
group-onsemi 0:098463de4c5d 23 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
group-onsemi 0:098463de4c5d 24 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
group-onsemi 0:098463de4c5d 25 * OTHER DEALINGS IN THE SOFTWARE.
group-onsemi 0:098463de4c5d 26 *
group-onsemi 0:098463de4c5d 27 * Except as contained in this notice, the name of Maxim Integrated
group-onsemi 0:098463de4c5d 28 * Products, Inc. shall not be used except as stated in the Maxim Integrated
group-onsemi 0:098463de4c5d 29 * Products, Inc. Branding Policy.
group-onsemi 0:098463de4c5d 30 *
group-onsemi 0:098463de4c5d 31 * The mere transfer of this software does not imply any licenses
group-onsemi 0:098463de4c5d 32 * of trade secrets, proprietary technology, copyrights, patents,
group-onsemi 0:098463de4c5d 33 * trademarks, maskwork rights, or any other form of intellectual
group-onsemi 0:098463de4c5d 34 * property whatsoever. Maxim Integrated Products, Inc. retains all
group-onsemi 0:098463de4c5d 35 * ownership rights.
group-onsemi 0:098463de4c5d 36 *
group-onsemi 0:098463de4c5d 37 * $Date: 2016-08-02 13:39:05 -0500 (Tue, 02 Aug 2016) $
group-onsemi 0:098463de4c5d 38 * $Revision: 23894 $
group-onsemi 0:098463de4c5d 39 *
group-onsemi 0:098463de4c5d 40 *************************************************************************** */
group-onsemi 0:098463de4c5d 41
group-onsemi 0:098463de4c5d 42 /* Define to prevent redundant inclusion */
group-onsemi 0:098463de4c5d 43 #ifndef _AES_H
group-onsemi 0:098463de4c5d 44 #define _AES_H
group-onsemi 0:098463de4c5d 45
group-onsemi 0:098463de4c5d 46 #include <stdint.h>
group-onsemi 0:098463de4c5d 47 #include "aes_regs.h"
group-onsemi 0:098463de4c5d 48
group-onsemi 0:098463de4c5d 49 #ifdef __cplusplus
group-onsemi 0:098463de4c5d 50 extern "C" {
group-onsemi 0:098463de4c5d 51 #endif
group-onsemi 0:098463de4c5d 52
group-onsemi 0:098463de4c5d 53 /**
group-onsemi 0:098463de4c5d 54 * @defgroup aes Advanced Encryption Standard (AES)
group-onsemi 0:098463de4c5d 55 * @ingroup periphlibs
group-onsemi 0:098463de4c5d 56 * @brief High-level API for AES encryption engine
group-onsemi 0:098463de4c5d 57 * @{
group-onsemi 0:098463de4c5d 58 */
group-onsemi 0:098463de4c5d 59
group-onsemi 0:098463de4c5d 60 /**
group-onsemi 0:098463de4c5d 61 * @page aes_overview Overview and Usage
group-onsemi 0:098463de4c5d 62 * @parblock
group-onsemi 0:098463de4c5d 63 * #### Key/data format in memory
group-onsemi 0:098463de4c5d 64 *
group-onsemi 0:098463de4c5d 65 * The API functions require that key and plain/ciphertext will be stored as a
group-onsemi 0:098463de4c5d 66 * byte array in LSB .. MSB format.
group-onsemi 0:098463de4c5d 67 *
group-onsemi 0:098463de4c5d 68 * As an example, given the key @a 0x139a35422f1d61de3c91787fe0507afd, the proper storage order is:
group-onsemi 0:098463de4c5d 69 * ~~~~~
group-onsemi 0:098463de4c5d 70 * uint8_t key[16] = { 0xfd, 0x7a, 0x50, 0xe0,
group-onsemi 0:098463de4c5d 71 * 0x7f, 0x78, 0x91, 0x3c,
group-onsemi 0:098463de4c5d 72 * 0xde, 0x61, 0x1d, 0x2f,
group-onsemi 0:098463de4c5d 73 * 0x42, 0x35, 0x9a, 0x13 };
group-onsemi 0:098463de4c5d 74 * ~~~~~
group-onsemi 0:098463de4c5d 75 * This is the same order expected by the underlying hardware.
group-onsemi 0:098463de4c5d 76 * @endparblock
group-onsemi 0:098463de4c5d 77 */
group-onsemi 0:098463de4c5d 78
group-onsemi 0:098463de4c5d 79 /* **** Definitions **** */
group-onsemi 0:098463de4c5d 80
group-onsemi 0:098463de4c5d 81 #define MXC_AES_DATA_LEN (128 / 8) /**< Number of bytes in an AES plaintext or cyphertext block (always 128-bits) */
group-onsemi 0:098463de4c5d 82
group-onsemi 0:098463de4c5d 83 #define MXC_AES_KEY_128_LEN (128 / 8) /**< Number of bytes in a AES-128 key */
group-onsemi 0:098463de4c5d 84 #define MXC_AES_KEY_192_LEN (192 / 8) /**< Number of bytes in a AES-192 key */
group-onsemi 0:098463de4c5d 85 #define MXC_AES_KEY_256_LEN (256 / 8) /**< Number of bytes in a AES-256 key */
group-onsemi 0:098463de4c5d 86
group-onsemi 0:098463de4c5d 87 /**
group-onsemi 0:098463de4c5d 88 * Enumeration type for AES key size selection (bits).
group-onsemi 0:098463de4c5d 89 */
group-onsemi 0:098463de4c5d 90 typedef enum {
group-onsemi 0:098463de4c5d 91 MXC_E_AES_MODE_128 = MXC_V_AES_CTRL_KEY_SIZE_128, /**< 128-bit key */
group-onsemi 0:098463de4c5d 92 MXC_E_AES_MODE_192 = MXC_V_AES_CTRL_KEY_SIZE_192, /**< 192-bit key */
group-onsemi 0:098463de4c5d 93 MXC_E_AES_MODE_256 = MXC_V_AES_CTRL_KEY_SIZE_256 /**< 256-bit key */
group-onsemi 0:098463de4c5d 94 } mxc_aes_mode_t;
group-onsemi 0:098463de4c5d 95
group-onsemi 0:098463de4c5d 96 /**
group-onsemi 0:098463de4c5d 97 * Enumeration type for specifying encryption/decrytion and asynchronous or blocking behavior.
group-onsemi 0:098463de4c5d 98 */
group-onsemi 0:098463de4c5d 99 typedef enum {
group-onsemi 0:098463de4c5d 100 MXC_E_AES_ENCRYPT = 0, /**< Encrypt (blocking) */
group-onsemi 0:098463de4c5d 101 MXC_E_AES_ENCRYPT_ASYNC = 1, /**< Encrypt (interrupt-driven) */
group-onsemi 0:098463de4c5d 102 MXC_E_AES_DECRYPT = 2, /**< Decrypt (blocking) */
group-onsemi 0:098463de4c5d 103 MXC_E_AES_DECRYPT_ASYNC = 3 /**< Decrypt (interrupt-driven) */
group-onsemi 0:098463de4c5d 104 } mxc_aes_dir_t;
group-onsemi 0:098463de4c5d 105
group-onsemi 0:098463de4c5d 106 /* **** Function Prototypes **** */
group-onsemi 0:098463de4c5d 107
group-onsemi 0:098463de4c5d 108 /**
group-onsemi 0:098463de4c5d 109 * @brief Configure AES block with keying material
group-onsemi 0:098463de4c5d 110 *
group-onsemi 0:098463de4c5d 111 * @param key 128, 192, or 256 bit keying material
group-onsemi 0:098463de4c5d 112 * @param mode Selects key length, valid modes defined in #mxc_aes_mode_t
group-onsemi 0:098463de4c5d 113 *
group-onsemi 0:098463de4c5d 114 * @return #E_BAD_PARAM Specified @a mode is invalid, see #mxc_aes_mode_t.
group-onsemi 0:098463de4c5d 115 * @return #E_NULL_PTR Invalid/Null pointer for parameter @a key.
group-onsemi 0:098463de4c5d 116 * @return #E_SUCCESS Key and mode set up correctly.
group-onsemi 0:098463de4c5d 117 */
group-onsemi 0:098463de4c5d 118 int AES_SetKey(const uint8_t *key, mxc_aes_mode_t mode);
group-onsemi 0:098463de4c5d 119
group-onsemi 0:098463de4c5d 120
group-onsemi 0:098463de4c5d 121 /**
group-onsemi 0:098463de4c5d 122 * @brief Encrypt/decrypt an input block with the loaded AES key.
group-onsemi 0:098463de4c5d 123 * @note The parameters @a in and @a out should always be 16 bytes
group-onsemi 0:098463de4c5d 124 *
group-onsemi 0:098463de4c5d 125 * @param in Pointer to input array of 16 bytes.
group-onsemi 0:098463de4c5d 126 * @param out Pointer to output array of 16 bytes.
group-onsemi 0:098463de4c5d 127 * @param mode AES key size to use for the transaction, see #mxc_aes_mode_t
group-onsemi 0:098463de4c5d 128 * @param dir Encrypt/Decrypt and Blocking or Asynchronous operation, see #mxc_aes_dir_t.
group-onsemi 0:098463de4c5d 129 *
group-onsemi 0:098463de4c5d 130 * @return #E_SUCCESS Operation completed successfully, output data is stored in @a *out.
group-onsemi 0:098463de4c5d 131 * @return ErrorCode An @link MXC_Error_Codes Error Code@endlink.
group-onsemi 0:098463de4c5d 132 */
group-onsemi 0:098463de4c5d 133 int AES_ECBOp(const uint8_t *in, uint8_t *out, mxc_aes_mode_t mode, mxc_aes_dir_t dir);
group-onsemi 0:098463de4c5d 134
group-onsemi 0:098463de4c5d 135 /**
group-onsemi 0:098463de4c5d 136 * @brief Read the AES output memory, used for asynchronous encryption, and clears interrupt flag.
group-onsemi 0:098463de4c5d 137 * @note The parameter @a out is always 16 bytes
group-onsemi 0:098463de4c5d 138 *
group-onsemi 0:098463de4c5d 139 * @param out Pointer to output array of 16 bytes
group-onsemi 0:098463de4c5d 140 *
group-onsemi 0:098463de4c5d 141 * @return #E_SUCCESS Output data was written to the location pointed to by @a *out
group-onsemi 0:098463de4c5d 142 * @return Error Code indicating the type of error encountered. See @ref MXC_Error_Codes
group-onsemi 0:098463de4c5d 143 * for possible return code values.
group-onsemi 0:098463de4c5d 144 */
group-onsemi 0:098463de4c5d 145 int AES_GetOutput(uint8_t *out);
group-onsemi 0:098463de4c5d 146
group-onsemi 0:098463de4c5d 147 /**
group-onsemi 0:098463de4c5d 148 * @def AES_ECBEncrypt(ptxt, ctxt, mode)s
group-onsemi 0:098463de4c5d 149 * @brief Encrypt a block of plaintext with the loaded AES key, blocks until complete
group-onsemi 0:098463de4c5d 150 * @hideinitializer
group-onsemi 0:098463de4c5d 151 *
group-onsemi 0:098463de4c5d 152 * @param ptxt Pointer to plaintext input array (always 16 bytes)
group-onsemi 0:098463de4c5d 153 * @param ctxt Pointer to ciphertext output array (always 16 bytes)
group-onsemi 0:098463de4c5d 154 * @param mode Selects key length, valid modes found in mxc_aes_mode_t
group-onsemi 0:098463de4c5d 155 */
group-onsemi 0:098463de4c5d 156 #define AES_ECBEncrypt(ptxt, ctxt, mode) AES_ECBOp(ptxt, ctxt, mode, MXC_E_AES_ENCRYPT)
group-onsemi 0:098463de4c5d 157
group-onsemi 0:098463de4c5d 158
group-onsemi 0:098463de4c5d 159 /**
group-onsemi 0:098463de4c5d 160 * @def AES_ECBDecrypt(ctxt, ptxt, mode)
group-onsemi 0:098463de4c5d 161 * @hideinitializer
group-onsemi 0:098463de4c5d 162 * @brief Decrypt a block of ciphertext with the loaded AES key, blocks until complete
group-onsemi 0:098463de4c5d 163 *
group-onsemi 0:098463de4c5d 164 * @param ctxt Pointer to ciphertext output array (always 16 bytes)
group-onsemi 0:098463de4c5d 165 * @param ptxt Pointer to plaintext input array (always 16 bytes)
group-onsemi 0:098463de4c5d 166 * @param mode Selects key length, valid modes found in mxc_aes_mode_t
group-onsemi 0:098463de4c5d 167 */
group-onsemi 0:098463de4c5d 168 #define AES_ECBDecrypt(ctxt, ptxt, mode) AES_ECBOp(ctxt, ptxt, mode, MXC_E_AES_DECRYPT)
group-onsemi 0:098463de4c5d 169
group-onsemi 0:098463de4c5d 170 /**
group-onsemi 0:098463de4c5d 171 * @def AES_ECBEncryptAsync(ptxt, mode)
group-onsemi 0:098463de4c5d 172 * @hideinitializer
group-onsemi 0:098463de4c5d 173 * @brief Starts encryption of a block, enables interrupt, and returns immediately.
group-onsemi 0:098463de4c5d 174 * Use AES_GetOuput() to retrieve result after interrupt fires
group-onsemi 0:098463de4c5d 175 *
group-onsemi 0:098463de4c5d 176 *
group-onsemi 0:098463de4c5d 177 * @param ptxt Pointer to plaintext input array (always 16 bytes)
group-onsemi 0:098463de4c5d 178 * @param mode Selects key length, valid modes found in mxc_aes_mode_t
group-onsemi 0:098463de4c5d 179 */
group-onsemi 0:098463de4c5d 180 #define AES_ECBEncryptAsync(ptxt, mode) AES_ECBOp(ptxt, NULL, mode, MXC_E_AES_ENCRYPT_ASYNC)
group-onsemi 0:098463de4c5d 181
group-onsemi 0:098463de4c5d 182 /**
group-onsemi 0:098463de4c5d 183 * @def AES_ECBDecryptAsync(ctxt, mode)
group-onsemi 0:098463de4c5d 184 * @hideinitializer
group-onsemi 0:098463de4c5d 185 * @brief Starts encryption of a block, enables interrupt, and returns immediately.
group-onsemi 0:098463de4c5d 186 * Use AES_GetOuput() to retrieve result after interrupt fires
group-onsemi 0:098463de4c5d 187 *
group-onsemi 0:098463de4c5d 188 * @param ctxt Pointer to ciphertext output array (always 16 bytes)
group-onsemi 0:098463de4c5d 189 * @param mode Selects key length, valid modes found in mxc_aes_mode_t
group-onsemi 0:098463de4c5d 190 */
group-onsemi 0:098463de4c5d 191 #define AES_ECBDecryptAsync(ctxt, mode) AES_ECBOp(ctxt, NULL, mode, MXC_E_AES_DECRYPT_ASYNC)
group-onsemi 0:098463de4c5d 192
group-onsemi 0:098463de4c5d 193 /**@} end of group aes*/
group-onsemi 0:098463de4c5d 194
group-onsemi 0:098463de4c5d 195 #ifdef __cplusplus
group-onsemi 0:098463de4c5d 196 }
group-onsemi 0:098463de4c5d 197 #endif
group-onsemi 0:098463de4c5d 198
group-onsemi 0:098463de4c5d 199 #endif