1 /* 2 * Copyright (c) 2021, Texas Instruments Incorporated 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 9 * * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * * Neither the name of Texas Instruments Incorporated nor the names of 17 * its contributors may be used to endorse or promote products derived 18 * from this software without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33 /*!*************************************************************************** 34 * @file AESCommon.h 35 * 36 * @brief AES common module header for all devices 37 *****************************************************************************/ 38 39 #ifndef ti_drivers_AESCommon_include 40 #define ti_drivers_AESCommon_include 41 42 #include <stdbool.h> 43 #include <stddef.h> 44 #include <stdint.h> 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 /*! 51 * @brief Successful status code. 52 * 53 * Functions return #AES_STATUS_SUCCESS if the function was executed 54 * successfully. 55 */ 56 #define AES_STATUS_SUCCESS ((int_fast16_t)0) 57 58 /*! 59 * @brief Generic error status code. 60 * 61 * Functions return #AES_STATUS_ERROR if the function was not executed 62 * successfully and no more pertinent error code could be returned. 63 */ 64 #define AES_STATUS_ERROR ((int_fast16_t)-1) 65 66 /*! 67 * @brief An error status code returned if the hardware or software resource 68 * is currently unavailable. 69 * 70 * AES driver implementations may have hardware or software limitations on how 71 * many clients can simultaneously perform operations. This status code is 72 * returned if the mutual exclusion mechanism signals that an operation cannot 73 * currently be performed. 74 */ 75 #define AES_STATUS_RESOURCE_UNAVAILABLE ((int_fast16_t)-2) 76 77 /*! 78 * @brief The ongoing operation was canceled. 79 */ 80 #define AES_STATUS_CANCELED ((int_fast16_t)-3) 81 82 /*! 83 * @brief The MAC verification failed. 84 * 85 * Functions return #AES_STATUS_MAC_INVALID if the MAC computed 86 * for the provided (key, message) pair did not match the MAC provided. 87 */ 88 #define AES_STATUS_MAC_INVALID ((int_fast16_t)-4) 89 90 /*! 91 * @brief The operation tried to load a key from the keystore using 92 * an invalid key ID. 93 * 94 * This code is returned if the provided CryptoKey reference 95 * is returned as invalid by the key store module. 96 */ 97 #define AES_STATUS_KEYSTORE_INVALID_ID ((int_fast16_t)-5) 98 99 /*! 100 * @brief The key store module returned a generic error. See key store 101 * documentation for additional details. 102 */ 103 #define AES_STATUS_KEYSTORE_GENERIC_ERROR ((int_fast16_t)-6) 104 105 /*! 106 * @brief The operation requested is not supported. 107 */ 108 #define AES_STATUS_FEATURE_NOT_SUPPORTED ((int_fast16_t)-7) 109 110 /*! 111 * @brief The operation does not support non-word-aligned input and/or output. 112 */ 113 #define AES_STATUS_UNALIGNED_IO_NOT_SUPPORTED ((int_fast16_t)-8) 114 115 /*! 116 * @brief A driver shall use this error code and grow negatively until 117 * (AES_STATUS_RESERVED + 1) if more driver specific error codes 118 * are needed beyond the common codes listed above. 119 * 120 * @note Not to be confused with #AES_STATUS_RESERVED which is for defining 121 * device specific codes if needed for a given driver, while 122 * #AES_STATUS_DRIVER_SPECIFIC_ERROR is for a driver but common across 123 * all devices for which that driver is implemented. 124 * 125 * Example implementation specific status codes: 126 * @code 127 * #define AESXYZ_STATUS_ERROR0 AES_STATUS_DRIVER_SPECIFIC_ERROR - 0 128 * #define AESXYZ_STATUS_ERROR1 AES_STATUS_DRIVER_SPECIFIC_ERROR - 1 129 * #define AESXYZ_STATUS_ERROR2 AES_STATUS_DRIVER_SPECIFIC_ERROR - 2 130 * @endcode 131 */ 132 #define AES_STATUS_DRIVER_SPECIFIC_ERROR ((int_fast16_t)-16) 133 134 /*! 135 * Common AES status code reservation offset. 136 * AES driver implementations should offset status codes with 137 * #AES_STATUS_RESERVED growing negatively. 138 * 139 * Example implementation specific status codes: 140 * @code 141 * #define AESXYZCCXXXX_STATUS_ERROR0 AES_STATUS_RESERVED - 0 142 * #define AESXYZCCXXXX_STATUS_ERROR1 AES_STATUS_RESERVED - 1 143 * #define AESXYZCCXXXX_STATUS_ERROR2 AES_STATUS_RESERVED - 2 144 * @endcode 145 */ 146 #define AES_STATUS_RESERVED ((int_fast16_t)-32) 147 148 /*! 149 * @brief AES Global configuration 150 * 151 * The #AESCommon_Config structure contains a set of pointers used to 152 * characterize the AES driver implementation. 153 */ 154 typedef struct 155 { 156 /*! Pointer to a driver specific data object */ 157 void *object; 158 159 /*! Pointer to a driver specific hardware attributes structure */ 160 void const *hwAttrs; 161 } AESCommon_Config; 162 163 /*! 164 * @brief The return behavior of AES functions 165 * 166 * Not all AES operations exhibit the specified return behavior. Functions 167 * that do not require significant computation and cannot offload that 168 * computation to a background thread behave like regular functions. 169 * Which functions exhibit the specified return behavior is not 170 * implementation dependent. Specifically, a software-backed implementation 171 * run on the same CPU as the application will emulate the return behavior 172 * while not actually offloading the computation to the background thread. 173 * 174 * AES functions exhibiting the specified return behavior have restrictions 175 * on the context from which they may be called. 176 * 177 * | | Task | Hwi | Swi | 178 * |-----------------------------|-------|-------|-------| 179 * |AES_RETURN_BEHAVIOR_CALLBACK | X | X | X | 180 * |AES_RETURN_BEHAVIOR_BLOCKING | X | | | 181 * |AES_RETURN_BEHAVIOR_POLLING | X | X | X | 182 * 183 */ 184 typedef enum 185 { 186 AES_RETURN_BEHAVIOR_CALLBACK = 1, /*!< The function call will return immediately while the 187 * operation goes on in the background. The registered 188 * callback function is called after the operation completes. 189 * The context the callback function is called (task, HWI, SWI) 190 * is implementation-dependent. 191 */ 192 AES_RETURN_BEHAVIOR_BLOCKING = 2, /*!< The function call will block while the operation goes 193 * on in the background. Operation results are available 194 * after the function returns. 195 */ 196 AES_RETURN_BEHAVIOR_POLLING = 4, /*!< The function call will continuously poll a flag while 197 * operation goes on in the background. Operation results 198 * are available after the function returns. 199 */ 200 } AES_ReturnBehavior; 201 202 #ifdef __cplusplus 203 } 204 #endif 205 206 #endif /* ti_drivers_AESCommon__include */ 207
