mbed official / mbed

The official Mbed 2 C/C++ SDK provides the software platform and libraries to build your applications.

Dependents:   hello SerialTestv11 SerialTestv12 Sierpinski ... more

mbed 2

This is the mbed 2 library. If you'd like to learn about Mbed OS please see the mbed-os docs.

TARGET_MAX32625NEXPAQ/TOOLCHAIN_ARM_STD/aes.h@172:65be27845400, 2019-02-20 (annotated)

Committer:
AnnaBridge
Date:
Wed Feb 20 20:53:29 2019 +0000
Revision:
172:65be27845400
Parent:
171:3a7713b1edbc 
mbed library release version 165

Who changed what in which revision?

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