1 /**************************************************************************/ 2 /* */ 3 /* Copyright (c) Microsoft Corporation. All rights reserved. */ 4 /* */ 5 /* This software is licensed under the Microsoft Software License */ 6 /* Terms for Microsoft Azure RTOS. Full text of the license can be */ 7 /* found in the LICENSE file at https://aka.ms/AzureRTOS_EULA */ 8 /* and in the root directory of this software. */ 9 /* */ 10 /**************************************************************************/ 11 12 13 /**************************************************************************/ 14 /**************************************************************************/ 15 /** */ 16 /** NetX Crypto Component */ 17 /** */ 18 /** AES Encryption */ 19 /** */ 20 /**************************************************************************/ 21 /**************************************************************************/ 22 23 24 /**************************************************************************/ 25 /* */ 26 /* APPLICATION INTERFACE DEFINITION RELEASE */ 27 /* */ 28 /* nx_crypto_aes.h PORTABLE C */ 29 /* 6.1.10 */ 30 /* AUTHOR */ 31 /* */ 32 /* Timothy Stapko, Microsoft Corporation */ 33 /* */ 34 /* DESCRIPTION */ 35 /* */ 36 /* This file defines the basic Application Interface (API) to the */ 37 /* NetX Crypto AES module. */ 38 /* */ 39 /* RELEASE HISTORY */ 40 /* */ 41 /* DATE NAME DESCRIPTION */ 42 /* */ 43 /* 05-19-2020 Timothy Stapko Initial Version 6.0 */ 44 /* 09-30-2020 Timothy Stapko Modified comment(s), */ 45 /* resulting in version 6.1 */ 46 /* 01-31-2022 Timothy Stapko Modified comment(s), */ 47 /* moved inverse key expansion,*/ 48 /* added using RAM tables, */ 49 /* resulting in version 6.1.10 */ 50 /* */ 51 /**************************************************************************/ 52 53 #ifndef NX_CRYPTO_AES_H 54 #define NX_CRYPTO_AES_H 55 56 /* Determine if a C++ compiler is being used. If so, ensure that standard 57 C is used to process the API information. */ 58 #ifdef __cplusplus 59 60 /* Yes, C++ compiler is present. Use standard C. */ 61 extern "C" { 62 63 #endif 64 65 /* Include the ThreadX and port-specific data type file. */ 66 67 #include "nx_crypto.h" 68 #include "nx_crypto_cbc.h" 69 #include "nx_crypto_ctr.h" 70 #include "nx_crypto_ccm.h" 71 #include "nx_crypto_gcm.h" 72 73 74 75 /* Constants. */ 76 #define NX_CRYPTO_BITS_IN_UCHAR ((UINT)0x8) 77 78 /* Helper macros for bit indexing (used by the division operation). */ 79 #define NX_CRYPTO_BIT_POSITION_BYTE_INDEX(x) (x >> 3) /* Divide the bit position by 8 to get the byte array index. */ 80 #define NX_CRYPTO_BIT_POSITION_BIT_VALUE(x) ((UINT)0x1 << (x & 0x7)) /* The bit to set (OR with the byte) is at (bit position % 8). */ 81 82 /* Word-aligned versions. */ 83 #define NX_CRYPTO_BIT_POSITION_WORD_INDEX(x) (x >> 4) /* Divide the bit position by 16 to get the word array index. */ 84 #define NX_CRYPTO_BIT_POSITION_WORD_BIT_VALUE(x) ((UINT)0x1 << (x & 0xF)) /* The bit to set (OR with the byte) is at (bit position % 16). */ 85 86 87 /* AES Support */ 88 89 #define NX_CRYPTO_AES_STATE_ROWS (4) 90 #define NX_CRYPTO_AES_STATE_NB_BYTES (4) 91 92 /* AES expects key sizes in the number of 32-bit words each key takes. */ 93 #define NX_CRYPTO_AES_KEY_SIZE_128_BITS (4) 94 #define NX_CRYPTO_AES_KEY_SIZE_192_BITS (6) 95 #define NX_CRYPTO_AES_KEY_SIZE_256_BITS (8) 96 97 #define NX_CRYPTO_AES_256_KEY_LEN_IN_BITS (256) 98 #define NX_CRYPTO_AES_192_KEY_LEN_IN_BITS (192) 99 #define NX_CRYPTO_AES_128_KEY_LEN_IN_BITS (128) 100 #define NX_CRYPTO_AES_XCBC_MAC_KEY_LEN_IN_BITS (128) 101 102 #define NX_CRYPTO_AES_MAX_KEY_SIZE (NX_CRYPTO_AES_KEY_SIZE_256_BITS) /* Maximum key size in bytes. */ 103 104 #define NX_CRYPTO_AES_BLOCK_SIZE (16) /* The AES block size for all NetX Crypto operations, in bytes. */ 105 #define NX_CRYPTO_AES_BLOCK_SIZE_IN_BITS (128) 106 #define NX_CRYPTO_AES_IV_LEN_IN_BITS (128) 107 #define NX_CRYPTO_AES_CTR_IV_LEN_IN_BITS (64) 108 109 #define NX_CRYPTO_AES_KEY_SCHEDULE_UNKNOWN 0 110 #define NX_CRYPTO_AES_KEY_SCHEDULE_ENCRYPT 1 111 #define NX_CRYPTO_AES_KEY_SCHEDULE_DECRYPT 2 112 113 /* Define NX_CRYPTO_AES_USE_RAM_TABLES to move tables to RAM. */ 114 #ifdef NX_CRYPTO_AES_USE_RAM_TABLES 115 #define NX_CRYPTO_AES_TABLE static 116 #else 117 #define NX_CRYPTO_AES_TABLE static const 118 #endif 119 120 /* Define the control block structure for backward compatibility. */ 121 #define NX_AES NX_CRYPTO_AES 122 123 typedef struct NX_CRYPTO_AES_STRUCT 124 { 125 /* UINT nb; Number of bytes per column, equal to block length / 32 - ALWAYS == 4 */ 126 127 /* AES internal state, 4 rows (32 bits each) of nb bytes */ 128 UINT nx_crypto_aes_state[NX_CRYPTO_AES_STATE_NB_BYTES]; 129 130 /* Number of *words* in the cipher key - can be 4 (128 bits), 6 (192 bits), or 8 (256 bits). */ 131 USHORT nx_crypto_aes_key_size; 132 133 /* Number of AES rounds for the current key. */ 134 UCHAR nx_crypto_aes_rounds; 135 136 /* Use the flag field to indicate the inverse key expansion is done. */ 137 UCHAR nx_crypto_aes_inverse_key_expanded; 138 139 /* The key schedule is as large as the key size (max = 256 bits) with expansion, total 64 UINT words. */ 140 UINT nx_crypto_aes_key_schedule[NX_CRYPTO_AES_MAX_KEY_SIZE * 8]; 141 UINT nx_crypto_aes_decrypt_key_schedule[NX_CRYPTO_AES_MAX_KEY_SIZE * 8]; 142 143 /* Metadata for each mode. */ 144 union 145 { 146 NX_CRYPTO_CBC cbc; 147 NX_CRYPTO_CTR ctr; 148 NX_CRYPTO_GCM gcm; 149 NX_CRYPTO_CCM ccm; 150 } nx_crypto_aes_mode_context; 151 } NX_CRYPTO_AES; 152 153 UINT _nx_crypto_aes_encrypt(NX_CRYPTO_AES *aes_ptr, UCHAR *input, UCHAR *output, UINT length); 154 UINT _nx_crypto_aes_decrypt(NX_CRYPTO_AES *aes_ptr, UCHAR *input, UCHAR *output, UINT length); 155 156 UINT _nx_crypto_aes_key_set(NX_CRYPTO_AES *aes_ptr, UCHAR *key, UINT key_size); 157 158 UINT _nx_crypto_method_aes_init(struct NX_CRYPTO_METHOD_STRUCT *method, 159 UCHAR *key, NX_CRYPTO_KEY_SIZE key_size_in_bits, 160 VOID **handle, 161 VOID *crypto_metadata, 162 ULONG crypto_metadata_size); 163 164 UINT _nx_crypto_method_aes_cleanup(VOID *crypto_metadata); 165 166 UINT _nx_crypto_method_aes_operation(UINT op, /* Encrypt, Decrypt, Authenticate */ 167 VOID *handle, /* Crypto handler */ 168 struct NX_CRYPTO_METHOD_STRUCT *method, 169 UCHAR *key, 170 NX_CRYPTO_KEY_SIZE key_size_in_bits, 171 UCHAR *input, 172 ULONG input_length_in_byte, 173 UCHAR *iv_ptr, 174 UCHAR *output, 175 ULONG output_length_in_byte, 176 VOID *crypto_metadata, 177 ULONG crypto_metadata_size, 178 VOID *packet_ptr, 179 VOID (*nx_crypto_hw_process_callback)(VOID *packet_ptr, UINT status)); 180 181 UINT _nx_crypto_method_aes_cbc_operation(UINT op, /* Encrypt, Decrypt, Authenticate */ 182 VOID *handle, /* Crypto handler */ 183 struct NX_CRYPTO_METHOD_STRUCT *method, 184 UCHAR *key, 185 NX_CRYPTO_KEY_SIZE key_size_in_bits, 186 UCHAR *input, 187 ULONG input_length_in_byte, 188 UCHAR *iv_ptr, 189 UCHAR *output, 190 ULONG output_length_in_byte, 191 VOID *crypto_metadata, 192 ULONG crypto_metadata_size, 193 VOID *packet_ptr, 194 VOID (*nx_crypto_hw_process_callback)(VOID *packet_ptr, UINT status)); 195 196 UINT _nx_crypto_method_aes_ccm_operation(UINT op, /* Encrypt, Decrypt, Authenticate */ 197 VOID *handle, /* Crypto handler */ 198 struct NX_CRYPTO_METHOD_STRUCT *method, 199 UCHAR *key, 200 NX_CRYPTO_KEY_SIZE key_size_in_bits, 201 UCHAR *input, 202 ULONG input_length_in_byte, 203 UCHAR *iv_ptr, 204 UCHAR *output, 205 ULONG output_length_in_byte, 206 VOID *crypto_metadata, 207 ULONG crypto_metadata_size, 208 VOID *packet_ptr, 209 VOID (*nx_crypto_hw_process_callback)(VOID *packet_ptr, UINT status)); 210 211 UINT _nx_crypto_method_aes_gcm_operation(UINT op, /* Encrypt, Decrypt, Authenticate */ 212 VOID *handle, /* Crypto handler */ 213 struct NX_CRYPTO_METHOD_STRUCT *method, 214 UCHAR *key, 215 NX_CRYPTO_KEY_SIZE key_size_in_bits, 216 UCHAR *input, 217 ULONG input_length_in_byte, 218 UCHAR *iv_ptr, 219 UCHAR *output, 220 ULONG output_length_in_byte, 221 VOID *crypto_metadata, 222 ULONG crypto_metadata_size, 223 VOID *packet_ptr, 224 VOID (*nx_crypto_hw_process_callback)(VOID *packet_ptr, UINT status)); 225 226 UINT _nx_crypto_method_aes_ctr_operation(UINT op, /* Encrypt, Decrypt, Authenticate */ 227 VOID *handle, /* Crypto handler */ 228 struct NX_CRYPTO_METHOD_STRUCT *method, 229 UCHAR *key, 230 NX_CRYPTO_KEY_SIZE key_size_in_bits, 231 UCHAR *input, 232 ULONG input_length_in_byte, 233 UCHAR *iv_ptr, 234 UCHAR *output, 235 ULONG output_length_in_byte, 236 VOID *crypto_metadata, 237 ULONG crypto_metadata_size, 238 VOID *packet_ptr, 239 VOID (*nx_crypto_hw_process_callback)(VOID *packet_ptr, UINT status)); 240 241 UINT _nx_crypto_method_aes_xcbc_operation(UINT op, /* Encrypt, Decrypt, Authenticate */ 242 VOID *handle, /* Crypto handler */ 243 struct NX_CRYPTO_METHOD_STRUCT *method, 244 UCHAR *key, 245 NX_CRYPTO_KEY_SIZE key_size_in_bits, 246 UCHAR *input, 247 ULONG input_length_in_byte, 248 UCHAR *iv_ptr, 249 UCHAR *output, 250 ULONG output_length_in_byte, 251 VOID *crypto_metadata, 252 ULONG crypto_metadata_size, 253 VOID *packet_ptr, 254 VOID (*nx_crypto_hw_process_callback)(VOID *packet_ptr, UINT status)); 255 256 #ifdef __cplusplus 257 } 258 #endif 259 260 261 #endif /* NX_CRYPTO_AES_H_ */ 262 263
