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