1 /** 2 * @file crypto.h 3 * @brief TPU communications interface driver. 4 */ 5 6 /****************************************************************************** 7 * 8 * Copyright (C) 2022-2023 Maxim Integrated Products, Inc. (now owned by 9 * Analog Devices, Inc.), 10 * Copyright (C) 2023-2024 Analog Devices, Inc. 11 * 12 * Licensed under the Apache License, Version 2.0 (the "License"); 13 * you may not use this file except in compliance with the License. 14 * You may obtain a copy of the License at 15 * 16 * http://www.apache.org/licenses/LICENSE-2.0 17 * 18 * Unless required by applicable law or agreed to in writing, software 19 * distributed under the License is distributed on an "AS IS" BASIS, 20 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 * See the License for the specific language governing permissions and 22 * limitations under the License. 23 * 24 ******************************************************************************/ 25 26 #ifndef LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32650_TPU_H_ 27 #define LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32650_TPU_H_ 28 29 #include <stdint.h> 30 #include "tpu_regs.h" 31 #include "trng_regs.h" 32 #include "mxc_sys.h" 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 /** 39 * @defgroup tpu TPU 40 * @ingroup periphlibs 41 * @{ 42 */ 43 /* ****** MACROS ****** */ 44 // CRC Polynomials 45 #define MXC_TPU_CRC32_ETHERNET 0xEDB88320 46 #define MXC_TPU_CRC_CCITT 0x00008408 47 #define MXC_TPU_CRC16 0x0000A001 48 #define MXC_TPU_USBDATA 0x80050000 49 #define MXC_TPU_PARITY 0x00000001 50 51 #define DES_DATA_LEN 8 // The byte length for DES data block 52 #define AES_DATA_LEN 16 // The byte length for AES data block 53 #define MAX_KEY_SIZE 32 // Defines maximum key length 54 #define MXC_AES_DATA_LEN \ 55 (128 / \ 56 8) /**< Number of bytes in an AES plaintext or ciphertext block, which are always 128-bits long. */ 57 #define MXC_AES_KEY_128_LEN (128 / 8) /**< Number of bytes in a AES-128 key. */ 58 #define MXC_AES_KEY_192_LEN (192 / 8) /**< Number of bytes in a AES-192 key. */ 59 #define MXC_AES_KEY_256_LEN (256 / 8) /**< Number of bytes in a AES-256 key. */ 60 61 //Macros used for MAA 62 #define MAA_MAX_SIZE 256 // in bytes 63 #define MAA_MAX_WORD_SIZE 2048 // in bits 64 65 /*************************************************************************************************************** 66 DATA STRUCTURES FOR TPU INITIALIZATION 67 ***************************************************************************************************************/ 68 /** 69 * Enumeration type for the TPU Cipher Operation(128/192/256-bit key) 70 */ 71 typedef enum { 72 MXC_TPU_CIPHER_DIS = MXC_V_TPU_CIPHER_CTRL_CIPHER_DIS, // Disable 73 MXC_TPU_CIPHER_AES128 = MXC_V_TPU_CIPHER_CTRL_CIPHER_AES128, // Select AES-128 74 MXC_TPU_CIPHER_AES192 = MXC_V_TPU_CIPHER_CTRL_CIPHER_AES192, // Select AES-192 75 MXC_TPU_CIPHER_AES256 = MXC_V_TPU_CIPHER_CTRL_CIPHER_AES256, // Select AES-256 76 MXC_TPU_CIPHER_DES = MXC_V_TPU_CIPHER_CTRL_CIPHER_DES, // Select DES 77 MXC_TPU_CIPHER_TDEA = MXC_V_TPU_CIPHER_CTRL_CIPHER_TDEA // Select TDEA 78 } mxc_tpu_ciphersel_t; 79 80 /** 81 * Enumeration type to select which key is used in Cipher operations 82 */ 83 typedef enum { 84 MXC_TPU_KEYSRC_CIPHER_KEY = MXC_S_TPU_CIPHER_CTRL_SRC_CIPHERKEY, // Use key in CIPHER_KEY[0:7] 85 MXC_TPU_KEYSRC_AES_KEY0 = MXC_S_TPU_CIPHER_CTRL_SRC_REGFILE, // Use key 0 in AES_KEY registers 86 MXC_TPU_KEYSRC_AES_KEY1 = 87 MXC_S_TPU_CIPHER_CTRL_SRC_QSPIKEY_REGFILE // Use key 1 in AES_KEY registers 88 } mxc_tpu_keysrc_t; 89 90 /** 91 * Enumeration type for the TPU Mode Select 92 */ 93 typedef enum { 94 MXC_TPU_MODE_ECB = MXC_V_TPU_CIPHER_CTRL_MODE_ECB, // Select ECB 95 MXC_TPU_MODE_CBC = MXC_V_TPU_CIPHER_CTRL_MODE_CBC, // Select CBC 96 MXC_TPU_MODE_CFB = MXC_V_TPU_CIPHER_CTRL_MODE_CFB, // Select CFB 97 MXC_TPU_MODE_CTR = MXC_V_TPU_CIPHER_CTRL_MODE_CTR // Select CTR 98 } mxc_tpu_modesel_t; 99 100 /** 101 * Enumeration type for Hash function Select 102 */ 103 typedef enum { 104 MXC_TPU_HASH_DIS = MXC_V_TPU_HASH_CTRL_HASH_DIS, // Disable 105 MXC_TPU_HASH_SHA1 = MXC_V_TPU_HASH_CTRL_HASH_SHA1, // Select SHA1 106 MXC_TPU_HASH_SHA224 = MXC_V_TPU_HASH_CTRL_HASH_SHA224, // Select SHA224 107 MXC_TPU_HASH_SHA256 = MXC_V_TPU_HASH_CTRL_HASH_SHA256, // Select SHA256 108 MXC_TPU_HASH_SHA384 = MXC_V_TPU_HASH_CTRL_HASH_SHA384, // Select SHA384 109 MXC_TPU_HASH_SHA512 = MXC_V_TPU_HASH_CTRL_HASH_SHA512 // Select SHA384 110 } mxc_tpu_hashfunsel_t; 111 112 /** 113 * Enumeration type for MAA initialization 114 */ 115 typedef enum { 116 MXC_TPU_MAA_EXP = MXC_V_TPU_MAA_CTRL_CLC_EXP, // Select exponentiation operation 117 MXC_TPU_MAA_SQ = MXC_V_TPU_MAA_CTRL_CLC_SQ, // Select square operation 118 MXC_TPU_MAA_MUL = MXC_V_TPU_MAA_CTRL_CLC_MULT, // Select multiplication operation 119 MXC_TPU_MAA_SQMUL = 120 MXC_V_TPU_MAA_CTRL_CLC_SQ_MULT, // Select square followed by multiplication operation 121 MXC_TPU_MAA_ADD = MXC_V_TPU_MAA_CTRL_CLC_ADD, // Select add operation 122 MXC_TPU_MAA_SUB = MXC_V_TPU_MAA_CTRL_CLC_SUB // Select subtract operation 123 } mxc_tpu_maa_clcsel_t; 124 125 /*************************************************************************************************************** 126 DRIVER EXPOSED API's 127 ***************************************************************************************************************/ 128 /** 129 * @brief Init TPU system settings 130 * @param clock peripheral clock to use 131 * 132 * @return E_NO_ERROR if successful, E_TIME_OUT otherwise. 133 */ 134 int MXC_TPU_Init(mxc_sys_periph_clock_t clock); 135 136 /** 137 * @brief Shutdown TPU system specific settings 138 */ 139 int MXC_TPU_Shutdown(mxc_sys_periph_clock_t clock); 140 141 /** 142 * @brief Reset the crypto accelerator 143 */ 144 void MXC_TPU_Reset(void); 145 146 /* ************************************************************************* */ 147 /* Cyclic Redundancy Check (CRC) functions */ 148 /* ************************************************************************* */ 149 150 /** 151 * @brief Configure crypto CRC operation 152 * @return #E_SUCCESS CRC algorithm configured successfully 153 */ 154 int MXC_TPU_CRC_Config(void); 155 156 /** 157 * @brief Test the CRC process 158 * @param src Pointer to source message 159 * @param len Specifies size of message in bytes 160 * @param poly Selects the crc polynomial 161 * @param crc Pointer to store crc value 162 * @return #E_NULL_PTR Specified pointers \p src; points to null 163 * @return #E_SUCCESS CRC process completed successfully 164 */ 165 int MXC_TPU_CRC(const uint8_t *src, uint32_t len, uint32_t poly, uint32_t *crc); 166 167 /** 168 * @brief Configure crypto HAM operation 169 * @return #E_SUCCESS HAM algorithm configured successfully 170 */ 171 int MXC_TPU_Ham_Config(void); 172 173 /** 174 * @brief Test the CRC process 175 * @param src Pointer to source message 176 * @param len Specifies size of message in bytes 177 * @param ecc Pointer to store ecc value 178 * @return #E_NULL_PTR Specified pointers \p src; points to null 179 * @return #E_SUCCESS CRC process completed successfully 180 */ 181 int MXC_TPU_Ham(const uint8_t *src, uint32_t len, uint32_t *ecc); 182 183 /* ************************************************************************* */ 184 /* Cipher functions */ 185 /* ************************************************************************* */ 186 187 /** 188 * @brief Get cipher key's size 189 */ 190 unsigned int MXC_TPU_Cipher_Get_Key_Size(mxc_tpu_ciphersel_t cipher); 191 192 /** 193 * @brief Get cipher block's size 194 */ 195 unsigned int MXC_TPU_Cipher_Get_Block_Size(mxc_tpu_ciphersel_t cipher); 196 197 /** 198 * @brief Get number of blocks 199 */ 200 unsigned int MXC_TPU_Cipher_GetLength(mxc_tpu_ciphersel_t cipher, unsigned int data_size); 201 202 /** 203 * @brief Enable Encrypt/Decrypt Cipher Operation 204 * @param enc Enable Encryption or Decryption 205 */ 206 void MXC_TPU_Cipher_EncDecSelect(int enc); 207 208 /** 209 * @brief Configure crypto cipher operation for different modes 210 * @param mode Selects the TPU operation mode 211 * @param cipher Selects the Cipher Operation mode 212 * @return #E_SUCCESS Cipher algorithm configured successfully 213 */ 214 int MXC_TPU_Cipher_Config(mxc_tpu_modesel_t mode, mxc_tpu_ciphersel_t cipher); 215 216 /** 217 * @brief Select the source of the cipher key used in cipher operations 218 * @param key_src Selects the key used in cipher operations 219 * @return #E_SUCCESS Cipher key selected successfully 220 */ 221 int MXC_TPU_Cipher_KeySelect(mxc_tpu_keysrc_t key_src); 222 223 /** 224 * @brief Test Cipher Algorithm 225 * @param src Pointer to the plaintext/ciphertext data 226 * @param iv Pointer to the initial vector data 227 * @param key Pointer to the crypto key 228 * @param cipher Selects the Cipher Operation mode 229 * @param mode Selects the TPU operation mode 230 * @param data_size Specifies length of data in bytes 231 * @param outptr Output buffer 232 * @return #E_NULL_PTR Specified pointers @plaintext; @iv; @key points to null 233 * @return #E_INVALID DES Encryption process failed 234 * @return #E_SUCCESS DES Encryption process completed successfully 235 * */ 236 int MXC_TPU_Cipher_DoOperation(const char *src, const char *iv, const char *key, 237 mxc_tpu_ciphersel_t cipher, mxc_tpu_modesel_t mode, 238 unsigned int data_size, char *outptr); 239 240 /** 241 * @brief The DES encryption process 242 * @param plaintext Pointer to the plaintext data 243 * @param iv Pointer to the initial vector data 244 * @param key Pointer to the crypto key 245 * @param mode Selects the TPU operation mode 246 * @param data_size Specifies length of data in bytes 247 * @param outptr Output buffer 248 * @return #E_NULL_PTR Specified pointers @plaintext; @iv; @key points to null 249 * @return #E_INVALID DES Encryption process failed 250 * @return #E_SUCCESS DES Encryption process completed successfully 251 */ 252 int MXC_TPU_Cipher_DES_Encrypt(const char *plaintext, const char *iv, const char *key, 253 mxc_tpu_modesel_t mode, unsigned int data_size, char *outptr); 254 255 /** 256 * @brief The DES decryption process 257 * @param ciphertext Pointer to the ciphertext data 258 * @param iv Pointer to the initial vector data 259 * @param key Pointer to the crypto key 260 * @param mode Selects the TPU operation mode 261 * @param data_size Specifies length of data in bytes 262 * @param outptr Output buffer 263 * @return #E_NULL_PTR Specified pointers @plaintext; @iv; @key points to null 264 * @return #E_INVALID DES Decryption process failed 265 * @return #E_SUCCESS DES Decryption process completed successfully 266 */ 267 int MXC_TPU_Cipher_DES_Decrypt(const char *ciphertext, const char *iv, const char *key, 268 mxc_tpu_modesel_t mode, unsigned int data_size, char *outptr); 269 270 /** 271 * @brief The TDES encryption process 272 * @param plaintext Pointer to the plaintext data 273 * @param iv Pointer to the initial vector data 274 * @param key Pointer to the crypto key 275 * @param mode Selects the TPU operation mode 276 * @param data_size Specifies length of data in bytes 277 * @param outptr Output buffer 278 * @return #E_NULL_PTR Specified pointers @plaintext; @iv; @key points to null 279 * @return #E_INVALID TDES Encryption process failed 280 * @return #E_SUCCESS TDES Encryption process completed successfully 281 */ 282 int MXC_TPU_Cipher_TDES_Encrypt(const char *plaintext, const char *iv, const char *key, 283 mxc_tpu_modesel_t mode, unsigned int data_size, char *outptr); 284 285 /** 286 * @brief The TDES decryption process 287 * @param ciphertext Pointer to the ciphertext data 288 * @param iv Pointer to the initial vector data 289 * @param key Pointer to the crypto key 290 * @param mode Selects the TPU operation mode 291 * @param data_size Specifies length of data in bytes 292 * @param outptr Output buffer 293 * @return #E_NULL_PTR Specified pointers @plaintext; @iv; @key points to null 294 * @return #E_INVALID TDES Decryption process failed 295 * @return #E_SUCCESS TDES Decryption process completed successfully 296 */ 297 int MXC_TPU_Cipher_TDES_Decrypt(const char *ciphertext, const char *iv, const char *key, 298 mxc_tpu_modesel_t mode, unsigned int data_size, char *outptr); 299 300 /** 301 * @brief The AES encryption process 302 * @param plaintext Pointer to the plaintext data 303 * @param iv Pointer to the initial vector data 304 * @param key Pointer to the crypto key 305 * @param cipher Selects the Cipher Operation mode 306 * @param mode Selects the TPU operation mode 307 * @param data_size Specifies length of data in bytes 308 * @param outptr Output buffer 309 * @return #E_NULL_PTR Specified pointers @plaintext; @iv; @key points to null 310 * @return #E_BAD_PARAM Specified Cipher operation mode @cipher is invalid, see #tpu_ciphersel_t 311 * @return #E_INVALID AES Encryption process failed 312 * @return #E_SUCCESS AES Encryption process completed successfully 313 */ 314 int MXC_TPU_Cipher_AES_Encrypt(const char *plaintext, const char *iv, const char *key, 315 mxc_tpu_ciphersel_t cipher, mxc_tpu_modesel_t mode, 316 unsigned int data_size, char *outptr); 317 318 /** 319 * @brief The AES decryption process 320 * @param ciphertext Pointer to the ciphertext data 321 * @param iv Pointer to the initial vector data 322 * @param key Pointer to the crypto key 323 * @param cipher Selects the Cipher Operation mode 324 * @param mode Selects the TPU operation mode 325 * @param data_size Specifies length of data in bytes 326 * @param outptr Output buffer 327 * @return #E_NULL_PTR Specified pointers @plaintext; @iv; @key points to null 328 * @return #E_BAD_PARAM Specified Cipher operation mode @cipher is invalid, see #tpu_ciphersel_t 329 * @return #E_INVALID AES Encryption process failed 330 * @return #E_SUCCESS AES Encryption process completed successfully 331 */ 332 int MXC_TPU_Cipher_AES_Decrypt(const char *ciphertext, const char *iv, const char *key, 333 mxc_tpu_ciphersel_t cipher, mxc_tpu_modesel_t mode, 334 unsigned int data_size, char *outptr); 335 336 /* ************************************************************************* */ 337 /* Hash functions */ 338 /* ************************************************************************* */ 339 340 /** 341 * @brief Get hash block's size 342 */ 343 unsigned int MXC_TPU_Hash_Get_Block_Size_SHA(mxc_tpu_hashfunsel_t func); 344 345 /** 346 * @brief Get hash digest's size 347 */ 348 unsigned int MXC_TPU_Hash_Get_Dgst_Size(mxc_tpu_hashfunsel_t func); 349 350 /** 351 * @brief Get SHA size 352 */ 353 void MXC_TPU_Hash_SHA_Size(unsigned int *blocks, unsigned int *length, unsigned int *lbyte, 354 mxc_tpu_hashfunsel_t fun); 355 356 /** 357 * @brief Configure crypto hash operation for different hash functions 358 * @param func Selects the hash function 359 * @return #E_SUCCESS Hash algorithm configured successfully 360 */ 361 int MXC_TPU_Hash_Config(mxc_tpu_hashfunsel_t func); 362 363 /** 364 * @brief Test the SHA process 365 * @param fun Selects the hash function 366 * @param msg Pointer to source message 367 * @param byteLen Specifies size of message in bytes 368 * @param digest Digest buffer 369 * @return #E_NULL_PTR Specified pointers \p msg; \p digest points to null 370 * @return #E_SUCCESS SHA process completed successfully 371 */ 372 int MXC_TPU_Hash_SHA(const char *msg, mxc_tpu_hashfunsel_t fun, unsigned int byteLen, char *digest); 373 374 /* ************************************************************************* */ 375 /* True Random Number Generator (TRNG) functions */ 376 /* ************************************************************************* */ 377 378 /** 379 *@brief Reads 8-bit value stored in the data register. 380 *@param trng Pointer to the trng register structure. 381 *@return 8-bit data register value. 382 */ 383 uint8_t MXC_TPU_TRNG_Read8BIT(mxc_trng_regs_t *trng); 384 385 /** 386 *@brief Reads 16-bit value stored in the data register. 387 *@param trng Pointer to the trng register structure. 388 *@return 16-bit data register value. 389 */ 390 uint16_t MXC_TPU_TRNG_Read16BIT(mxc_trng_regs_t *trng); 391 392 /** 393 *@brief Reads 32-bit value stored in the data register. 394 *@param trng Pointer to the trng register structure. 395 *@return 32-bit data register value. 396 */ 397 uint32_t MXC_TPU_TRNG_Read32BIT(mxc_trng_regs_t *trng); 398 399 /** 400 *@brief Generates Random Number of variable length. 401 *@param trng Pointer to the trng register structure. 402 *@param data Pointer to the Data Buffer. 403 *@param len Defines length of data(bytes). 404 */ 405 void MXC_TPU_TRNG_Read(mxc_trng_regs_t *trng, uint8_t *data, int len); 406 407 /** 408 *@brief Generates 256-bits random number automatically. 409 *@param trng Pointer to the trng register structure. 410 */ 411 void MXC_TPU_TRNG_Generate_AES(mxc_trng_regs_t *trng); 412 413 /* ************************************************************************* */ 414 /* Modular Arithmetic Accelerator (MAA) functions */ 415 /* ************************************************************************* */ 416 417 /** 418 * @brief Initialize memory used for MAA 419 */ 420 void MXC_TPU_MAA_Mem_Clear(void); 421 422 /** 423 * @brief Reset the TPU accelerator 424 */ 425 void MXC_TPU_MAA_Reset(void); 426 427 /** 428 * @brief Configure MAA operation with appropriate MAA word size 429 * @param size Defines the number of bits for modular operation 430 * @return #E_BAD_PARAM Specified size \p size, out of range 431 * @return #E_SUCCESS Cipher algorithm configured successfully 432 */ 433 int MXC_TPU_MAA_Init(unsigned int size); 434 435 /** 436 * @brief Release MAA 437 * @details Shuts down the MAA engine and any associated clocks 438 * @return #E_BAD_PARAM if MAA cannot be stopped 439 * @return #E_NO_ERROR otherwise 440 */ 441 int MXC_TPU_MAA_Shutdown(void); 442 443 /** 444 * @brief MAA operation 445 * @param clc Selects the MAA calculation operation 446 * @param multiplier Pointer to multiplier data 447 * @param multiplicand Pointer to multiplicand data 448 * @param exp Pointer to exponent data 449 * @param mod Pointer to modular data 450 * @param result Output buffer 451 * @param len Specifies length to the nearest 32-bit boundary 452 * @return #E_NULL_PTR Specified pointers \p multiplier; \p multiplicand; \p exp; \p mod points to null 453 * @return #E_INVALID Specified MAA calculation operation is invalid 454 * @return #E_BAD_STATE MAA Error occurs 455 * @return #E_SUCCESS MAA process completed successfully 456 * 457 * @note \p multiplier; \p multiplicand; \p exp; \p mod, data must be loaded with zero pad to specified length \p len, or the "garbage bits" will case erroneous results 458 */ 459 int MXC_TPU_MAA_Compute(mxc_tpu_maa_clcsel_t clc, char *multiplier, char *multiplicand, char *exp, 460 char *mod, int *result, unsigned int len); 461 462 /**@} end of group tpu */ 463 464 #ifdef __cplusplus 465 } 466 #endif 467 468 #endif // LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32650_TPU_H_ 469
