1 /* 2 * Copyright (c) 2016, Freescale Semiconductor, Inc. 3 * Copyright 2016-2017, 2020 NXP 4 * All rights reserved. 5 * 6 * SPDX-License-Identifier: BSD-3-Clause 7 */ 8 #ifndef FSL_AES_H_ 9 #define FSL_AES_H_ 10 11 #include "fsl_common.h" 12 13 /*! 14 * @addtogroup aes 15 * @{ 16 */ 17 18 /*! @file */ 19 20 /******************************************************************************* 21 * Definitions 22 *******************************************************************************/ 23 24 /*! @name Driver version */ 25 /*! @{ */ 26 /*! @brief Defines LPC AES driver version 2.0.3. 27 * 28 * Change log: 29 * - Version 2.0.3 30 * - Edit aes_one_block() function to be interrupt safe. 31 * - Version 2.0.2 32 * - Fix MISRA-2012 issues 33 * - Version 2.0.1 34 * - GCM constant time tag comparison 35 * - Version 2.0.0 36 * - initial version 37 */ 38 #define FSL_AES_DRIVER_VERSION (MAKE_VERSION(2, 0, 3)) 39 /*! @} */ 40 41 /******************************************************************************* 42 * API 43 *******************************************************************************/ 44 45 #if defined(__cplusplus) 46 extern "C" { 47 #endif /* __cplusplus */ 48 49 /*! 50 * @name AES Functional Operation 51 * @{ 52 */ 53 54 /*! AES block size in bytes */ 55 #define AES_BLOCK_SIZE 16 56 /*! AES Input Vector size in bytes */ 57 #define AES_IV_SIZE 16 58 59 /*! 60 * @brief Sets AES key. 61 * 62 * Sets AES key. 63 * 64 * @param base AES peripheral base address 65 * @param key Input key to use for encryption or decryption 66 * @param keySize Size of the input key, in bytes. Must be 16, 24, or 32. 67 * @return Status from Set Key operation 68 */ 69 status_t AES_SetKey(AES_Type *base, const uint8_t *key, size_t keySize); 70 71 /*! 72 * @brief Encrypts AES using the ECB block mode. 73 * 74 * Encrypts AES using the ECB block mode. 75 * 76 * @param base AES peripheral base address 77 * @param plaintext Input plain text to encrypt 78 * @param[out] ciphertext Output cipher text 79 * @param size Size of input and output data in bytes. Must be multiple of 16 bytes. 80 * @return Status from encrypt operation 81 */ 82 status_t AES_EncryptEcb(AES_Type *base, const uint8_t *plaintext, uint8_t *ciphertext, size_t size); 83 84 /*! 85 * @brief Decrypts AES using the ECB block mode. 86 * 87 * Decrypts AES using the ECB block mode. 88 * 89 * @param base AES peripheral base address 90 * @param ciphertext Input ciphertext to decrypt 91 * @param[out] plaintext Output plain text 92 * @param size Size of input and output data in bytes. Must be multiple of 16 bytes. 93 * @return Status from decrypt operation 94 */ 95 status_t AES_DecryptEcb(AES_Type *base, const uint8_t *ciphertext, uint8_t *plaintext, size_t size); 96 97 /*! 98 * @brief Encrypts AES using CBC block mode. 99 * 100 * @param base AES peripheral base address 101 * @param plaintext Input plain text to encrypt 102 * @param[out] ciphertext Output cipher text 103 * @param size Size of input and output data in bytes. Must be multiple of 16 bytes. 104 * @param iv Input initial vector to combine with the first input block. 105 * @return Status from encrypt operation 106 */ 107 status_t AES_EncryptCbc( 108 AES_Type *base, const uint8_t *plaintext, uint8_t *ciphertext, size_t size, const uint8_t iv[AES_IV_SIZE]); 109 110 /*! 111 * @brief Decrypts AES using CBC block mode. 112 * 113 * @param base AES peripheral base address 114 * @param ciphertext Input cipher text to decrypt 115 * @param[out] plaintext Output plain text 116 * @param size Size of input and output data in bytes. Must be multiple of 16 bytes. 117 * @param iv Input initial vector to combine with the first input block. 118 * @return Status from decrypt operation 119 */ 120 status_t AES_DecryptCbc( 121 AES_Type *base, const uint8_t *ciphertext, uint8_t *plaintext, size_t size, const uint8_t iv[AES_IV_SIZE]); 122 123 /*! 124 * @brief Encrypts AES using CFB block mode. 125 * 126 * @param base AES peripheral base address 127 * @param plaintext Input plain text to encrypt 128 * @param[out] ciphertext Output cipher text 129 * @param size Size of input and output data in bytes. Must be multiple of 16 bytes. 130 * @param iv Input Initial vector to be used as the first input block. 131 * @return Status from encrypt operation 132 */ 133 status_t AES_EncryptCfb( 134 AES_Type *base, const uint8_t *plaintext, uint8_t *ciphertext, size_t size, const uint8_t iv[AES_IV_SIZE]); 135 136 /*! 137 * @brief Decrypts AES using CFB block mode. 138 * 139 * @param base AES peripheral base address 140 * @param ciphertext Input cipher text to decrypt 141 * @param[out] plaintext Output plain text 142 * @param size Size of input and output data in bytes. Must be multiple of 16 bytes. 143 * @param iv Input Initial vector to be used as the first input block. 144 * @return Status from decrypt operation 145 */ 146 status_t AES_DecryptCfb( 147 AES_Type *base, const uint8_t *ciphertext, uint8_t *plaintext, size_t size, const uint8_t iv[AES_IV_SIZE]); 148 149 /*! 150 * @brief Encrypts AES using OFB block mode. 151 * 152 * @param base AES peripheral base address 153 * @param plaintext Input plain text to encrypt 154 * @param[out] ciphertext Output cipher text 155 * @param size Size of input and output data in bytes. 156 * @param iv Input Initial vector to be used as the first input block. 157 * @return Status from encrypt operation 158 */ 159 status_t AES_EncryptOfb( 160 AES_Type *base, const uint8_t *plaintext, uint8_t *ciphertext, size_t size, const uint8_t iv[AES_IV_SIZE]); 161 162 /*! 163 * @brief Decrypts AES using OFB block mode. 164 * 165 * @param base AES peripheral base address 166 * @param ciphertext Input cipher text to decrypt 167 * @param[out] plaintext Output plain text 168 * @param size Size of input and output data in bytes. 169 * @param iv Input Initial vector to be used as the first input block. 170 * @return Status from decrypt operation 171 */ 172 status_t AES_DecryptOfb( 173 AES_Type *base, const uint8_t *ciphertext, uint8_t *plaintext, size_t size, const uint8_t iv[AES_IV_SIZE]); 174 175 /*! 176 * @brief Encrypts or decrypts AES using CTR block mode. 177 * 178 * Encrypts or decrypts AES using CTR block mode. 179 * AES CTR mode uses only forward AES cipher and same algorithm for encryption and decryption. 180 * The only difference between encryption and decryption is that, for encryption, the input argument 181 * is plain text and the output argument is cipher text. For decryption, the input argument is cipher text 182 * and the output argument is plain text. 183 * 184 * @param base AES peripheral base address 185 * @param input Input data for CTR block mode 186 * @param[out] output Output data for CTR block mode 187 * @param size Size of input and output data in bytes 188 * @param[in,out] counter Input counter (updates on return) 189 * @param[out] counterlast Output cipher of last counter, for chained CTR calls. NULL can be passed if chained calls are 190 * not used. 191 * @param[out] szLeft Output number of bytes in left unused in counterlast block. NULL can be passed if chained calls 192 * are not used. 193 * @return Status from crypt operation 194 */ 195 status_t AES_CryptCtr(AES_Type *base, 196 const uint8_t *input, 197 uint8_t *output, 198 size_t size, 199 uint8_t counter[AES_BLOCK_SIZE], 200 uint8_t counterlast[AES_BLOCK_SIZE], 201 size_t *szLeft); 202 203 /*! 204 * @brief Encrypts AES and tags using GCM block mode. 205 * 206 * Encrypts AES and optionally tags using GCM block mode. If plaintext is NULL, only the GHASH is calculated and output 207 * in the 'tag' field. 208 * 209 * @param base AES peripheral base address 210 * @param plaintext Input plain text to encrypt 211 * @param[out] ciphertext Output cipher text. 212 * @param size Size of input and output data in bytes 213 * @param iv Input initial vector 214 * @param ivSize Size of the IV 215 * @param aad Input additional authentication data 216 * @param aadSize Input size in bytes of AAD 217 * @param[out] tag Output hash tag. Set to NULL to skip tag processing. 218 * @param tagSize Input size of the tag to generate, in bytes. Must be 4,8,12,13,14,15 or 16. 219 * @return Status from encrypt operation 220 */ 221 status_t AES_EncryptTagGcm(AES_Type *base, 222 const uint8_t *plaintext, 223 uint8_t *ciphertext, 224 size_t size, 225 const uint8_t *iv, 226 size_t ivSize, 227 const uint8_t *aad, 228 size_t aadSize, 229 uint8_t *tag, 230 size_t tagSize); 231 232 /*! 233 * @brief Decrypts AES and authenticates using GCM block mode. 234 * 235 * Decrypts AES and optionally authenticates using GCM block mode. If ciphertext is NULL, only the GHASH is calculated 236 * and compared with the received GHASH in 'tag' field. 237 * 238 * @param base AES peripheral base address 239 * @param ciphertext Input cipher text to decrypt 240 * @param[out] plaintext Output plain text. 241 * @param size Size of input and output data in bytes 242 * @param iv Input initial vector 243 * @param ivSize Size of the IV 244 * @param aad Input additional authentication data 245 * @param aadSize Input size in bytes of AAD 246 * @param tag Input hash tag to compare. Set to NULL to skip tag processing. 247 * @param tagSize Input size of the tag, in bytes. Must be 4, 8, 12, 13, 14, 15, or 16. 248 * @return Status from decrypt operation 249 */ 250 status_t AES_DecryptTagGcm(AES_Type *base, 251 const uint8_t *ciphertext, 252 uint8_t *plaintext, 253 size_t size, 254 const uint8_t *iv, 255 size_t ivSize, 256 const uint8_t *aad, 257 size_t aadSize, 258 const uint8_t *tag, 259 size_t tagSize); 260 261 #if defined(__cplusplus) 262 } 263 #endif /* __cplusplus */ 264 265 /*! @}*/ 266 /*! @}*/ /* end of group aes */ 267 268 #endif /* FSL_AES_H_ */ 269
