1 /** 2 * @file ctb.h 3 * @brief Crypto Toolbox 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_MAX32690_CTB_H_ 27 #define LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32690_CTB_H_ 28 29 /***** Includes *****/ 30 #include "ctb_regs.h" 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 36 /** 37 * @defgroup ctb CTB 38 * @ingroup periphlibs 39 * @{ 40 */ 41 42 /* IN ADDITION TO THIS HEADER, FCL WILL BE SUPPORTED AND PROVIDED IN BINARY FORM */ 43 /***** Definitions *****/ 44 45 /** 46 * @brief Callback funtion for ctb 47 * 48 */ 49 typedef void (*mxc_ctb_complete_cb_t)(void *req, int result); 50 51 /** 52 * @brief Enumeration type for Crypto Toolbox features 53 * 54 */ 55 typedef enum { 56 MXC_CTB_FEATURE_DMA = 1 << 0, 57 MXC_CTB_FEATURE_ECC = 1 << 1, 58 MXC_CTB_FEATURE_CRC = 1 << 2, 59 MXC_CTB_FEATURE_HASH = 1 << 4, 60 MXC_CTB_FEATURE_CIPHER = 1 << 5, 61 MXC_CTB_FEATURE_TRNG = 1 << 6 62 } mxc_ctb_features_t; 63 64 /* ************************************************************************* */ 65 /* DMA Definitions */ 66 /* ************************************************************************* */ 67 68 /** 69 * @brief Structure for using DMA with CTB 70 * 71 */ 72 struct _mxc_ctb_dma_req_t { 73 uint8_t *sourceBuffer; ///< pointer to source data 74 uint8_t *destBuffer; ///< pointer to destination buffer 75 uint32_t length; ///< length of source data 76 mxc_ctb_complete_cb_t callback; ///< Null callback indicates a blocking operation 77 } typedef mxc_ctb_dma_req_t; 78 79 /** 80 * @brief Enumeration type to select read source channel of DMA 81 * 82 */ 83 typedef enum { 84 MXC_CTB_DMA_READ_FIFO_DMA = MXC_V_CTB_CTRL_RDSRC_DMAORAPB, 85 MXC_CTB_DMA_READ_FIFO_RNG = MXC_V_CTB_CTRL_RDSRC_RNG 86 } mxc_ctb_dma_read_source_t; 87 88 /** 89 * @brief Enumeration type to select write source channel of DMA 90 * 91 */ 92 typedef enum { 93 MXC_CTB_DMA_WRITE_FIFO_CIPHER = MXC_V_CTB_CTRL_WRSRC_CIPHEROUTPUT, 94 MXC_CTB_DMA_WRITE_FIFO_READ_FIFO = MXC_V_CTB_CTRL_WRSRC_READFIFO, 95 MXC_CTB_DMA_WRITE_FIFO_NONE = MXC_V_CTB_CTRL_WRSRC_NONE 96 } mxc_ctb_dma_write_source_t; 97 98 /* ************************************************************************* */ 99 /* ECC Definitions */ 100 /* ************************************************************************* */ 101 102 /** 103 * @brief Structure used to set up ECC request 104 * 105 */ 106 struct _mxc_ctb_ecc_req_t { 107 uint8_t *dataBuffer; 108 uint32_t dataLen; 109 uint32_t checksum; 110 mxc_ctb_complete_cb_t callback; 111 } typedef mxc_ctb_ecc_req_t; 112 113 /** 114 * @brief Structure used to set up CRC request 115 * 116 */ 117 struct _mxc_ctb_crc_req_t { 118 uint8_t *dataBuffer; 119 uint32_t dataLen; 120 uint32_t resultCRC; 121 mxc_ctb_complete_cb_t callback; 122 } typedef mxc_ctb_crc_req_t; 123 124 /** 125 * @brief CRC data bit order 126 * 127 */ 128 typedef enum { MXC_CTB_CRC_LSB_FIRST, MXC_CTB_CRC_MSB_FIRST } mxc_ctb_crc_bitorder_t; 129 130 /* ************************************************************************* */ 131 /* Hash Definitions */ 132 /* ************************************************************************* */ 133 134 /** 135 * @brief Structure used to set up Hash request 136 * 137 */ 138 struct _mxc_ctb_hash_req_t { 139 uint8_t *msg; 140 uint32_t len; 141 uint8_t *hash; 142 mxc_ctb_complete_cb_t callback; 143 } typedef mxc_ctb_hash_req_t; 144 145 /** 146 * @brief Enumeration type to select Hash function 147 * 148 */ 149 typedef enum { 150 MXC_CTB_HASH_DIS = MXC_V_CTB_HASH_CTRL_HASH_DIS, // Disable 151 MXC_CTB_HASH_SHA1 = MXC_V_CTB_HASH_CTRL_HASH_SHA1, // Select SHA1 152 MXC_CTB_HASH_SHA224 = MXC_V_CTB_HASH_CTRL_HASH_SHA224, // Select SHA224 153 MXC_CTB_HASH_SHA256 = MXC_V_CTB_HASH_CTRL_HASH_SHA256, // Select SHA256 154 MXC_CTB_HASH_SHA384 = MXC_V_CTB_HASH_CTRL_HASH_SHA384, // Select SHA384 155 MXC_CTB_HASH_SHA512 = MXC_V_CTB_HASH_CTRL_HASH_SHA512 // Select SHA384 156 } mxc_ctb_hash_func_t; 157 158 /** 159 * @brief Enumeration type to select FIFO source for Hash 160 * 161 */ 162 typedef enum { 163 MXC_CTB_HASH_SOURCE_INFIFO = 0, 164 MXC_CTB_HASH_SOURCE_OUTFIFO = 1 165 } mxc_ctb_hash_source_t; 166 167 /* ************************************************************************* */ 168 /* Cipher Definitions */ 169 /* ************************************************************************* */ 170 171 /** 172 * @brief Structure used to set up Cipher request 173 * 174 */ 175 struct _mxc_ctb_cipher_req_t { 176 uint8_t *plaintext; 177 uint32_t ptLen; 178 uint8_t *iv; 179 uint8_t *ciphertext; 180 mxc_ctb_complete_cb_t callback; 181 } typedef mxc_ctb_cipher_req_t; 182 183 /** 184 * @brief Enumeration type to select Cipher mode 185 * 186 */ 187 typedef enum { 188 MXC_CTB_MODE_ECB = MXC_V_CTB_CIPHER_CTRL_MODE_ECB, ///< Electronic Code Book 189 MXC_CTB_MODE_CBC = MXC_V_CTB_CIPHER_CTRL_MODE_CBC, ///< Cipher Block Chaining 190 MXC_CTB_MODE_CFB = MXC_V_CTB_CIPHER_CTRL_MODE_CFB, ///< Cipher Feedback 191 MXC_CTB_MODE_CTR = MXC_V_CTB_CIPHER_CTRL_MODE_CTR, ///< Counter 192 MXC_CTB_MODE_OFB = MXC_V_CTB_CIPHER_CTRL_MODE_OFB ///< Output Feedback 193 } mxc_ctb_cipher_mode_t; 194 195 /** 196 * @brief Enumeration type to select Cipher function 197 * 198 */ 199 typedef enum { 200 MXC_CTB_CIPHER_DIS = MXC_V_CTB_CIPHER_CTRL_CIPHER_DIS, ///< Disable 201 MXC_CTB_CIPHER_AES128 = MXC_V_CTB_CIPHER_CTRL_CIPHER_AES128, ///< Select AES-128 202 MXC_CTB_CIPHER_AES192 = MXC_V_CTB_CIPHER_CTRL_CIPHER_AES192, ///< Select AES-192 203 MXC_CTB_CIPHER_AES256 = MXC_V_CTB_CIPHER_CTRL_CIPHER_AES256, ///< Select AES-256 204 MXC_CTB_CIPHER_DES = MXC_V_CTB_CIPHER_CTRL_CIPHER_DES, ///< Select DES 205 MXC_CTB_CIPHER_TDES = MXC_V_CTB_CIPHER_CTRL_CIPHER_TDES ///< Select TDES 206 } mxc_ctb_cipher_t; 207 208 /** 209 * @brief Enumeration type to select Cipher key 210 * 211 */ 212 typedef enum { 213 MXC_CTB_CIPHER_KEY_SOFTWARE = 0, 214 MXC_CTB_CIPHER_KEY_AES_KEY2 = 2, 215 MXC_CTB_CIPHER_KEY_AES_KEY3 = 3 216 } mxc_ctb_cipher_key_t; 217 218 /** 219 * @brief Cipher operation 220 * 221 */ 222 typedef enum { 223 MXC_CTB_CIPHER_ENCRYPTION = 0, 224 MXC_CTB_CIPHER_DECRYPTION 225 } mxc_ctb_cipher_operation_t; 226 227 /***** Function Prototypes *****/ 228 229 /* ************************************************************************* */ 230 /* Global Control/Configuration functions */ 231 /* ************************************************************************* */ 232 233 /** 234 * @brief Enable portions of the CTB 235 * 236 * @param features bit banded value indicating features to enable 237 * see \ref mxc_ctb_features_t for a list of features 238 * 239 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 240 */ 241 int MXC_CTB_Init(uint32_t features); 242 243 /** 244 * @brief Detects what CTB features exist, see \ref mxc_ctb_features_t 245 * 246 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 247 */ 248 uint32_t MXC_CTB_CheckFeatures(void); 249 250 /** 251 * @brief Enable CTB Interrupts 252 * 253 */ 254 void MXC_CTB_EnableInt(void); 255 256 /** 257 * @brief Disable CTB Interrupts 258 * 259 */ 260 void MXC_CTB_DisableInt(void); 261 262 /** 263 * @brief Checks the global CTB Ready Status 264 * 265 * @return Nonzero if ready, zero if not ready or \ref MXC_Error_Codes. 266 */ 267 int MXC_CTB_Ready(void); 268 269 /** 270 * @brief Clears the selected feature's done bits, see \ref mxc_ctb_features_t 271 * 272 * @param features bit banded value indicating features to clear 273 */ 274 void MXC_CTB_DoneClear(uint32_t features); 275 276 /** 277 * @brief Returns CTB features showing operations complete, see \ref mxc_ctb_features_t 278 * 279 * @return CTB features showing operations complete, see \ref mxc_ctb_features_t. 280 */ 281 uint32_t MXC_CTB_Done(void); 282 283 /** 284 * @brief Resets the selected features, see \ref mxc_ctb_features_t 285 * 286 * @param features bit banded value indicating features to reset 287 */ 288 void MXC_CTB_Reset(uint32_t features); 289 290 /** 291 * @brief Invalidates the CTB's internal cache. 292 * @note For best security, should be done after every operation 293 */ 294 void MXC_CTB_CacheInvalidate(void); 295 296 /** 297 * @brief Disable and reset portions of the CTB 298 * 299 * @param features bit banded value indicating features to shutdown 300 * see \ref mxc_ctb_features_t for a list of features 301 * 302 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 303 */ 304 int MXC_CTB_Shutdown(uint32_t features); 305 306 /** 307 * @brief Check which CTB features are enabled 308 * 309 * @return CTB features showing features enabled, see \ref mxc_ctb_features_t. 310 */ 311 uint32_t MXC_CTB_GetEnabledFeatures(void); 312 313 /** 314 * @brief This function should be called from the CTB ISR Handler 315 * when using Async functions 316 */ 317 void MXC_CTB_Handler(void); 318 319 /************************************/ 320 /* CTB DMA - Used for all features */ 321 /************************************/ 322 323 /** 324 * @brief Set the source the DMA reads from 325 * @note The DMA is unable to read directly from Flash 326 * 327 * @param source The source of the data for DMA read operations 328 * see \ref mxc_ctb_dma_read_source_t for a list of sources 329 */ 330 void MXC_CTB_DMA_SetReadSource(mxc_ctb_dma_read_source_t source); 331 332 /** 333 * @brief Get the source the DMA reads from 334 * 335 * @return The source of the data for DMA read operations 336 * see \ref mxc_ctb_dma_read_source_t for a list of sources 337 */ 338 mxc_ctb_dma_read_source_t MXC_CTB_DMA_GetReadSource(void); 339 340 /** 341 * @brief Set the source the DMA write fifo reads from 342 * 343 * @param source The source of the data for DMA write operations 344 * see \ref mxc_ctb_dma_write_source_t for a list of sources 345 */ 346 void MXC_CTB_DMA_SetWriteSource(mxc_ctb_dma_write_source_t source); 347 348 /** 349 * @brief Set the source the DMA write fifo reads from 350 * 351 * @return The source of the data for DMA write operations 352 * see \ref mxc_ctb_dma_write_source_t for a list of sources 353 */ 354 mxc_ctb_dma_write_source_t MXC_CTB_DMA_GetWriteSource(void); 355 356 /** 357 * @brief Set the source address of the DMA 358 * @note This is only applicable when the read source is memory 359 * The DMA is unable to read directly from Flash 360 * 361 * @param source pointer to the source location 362 */ 363 void MXC_CTB_DMA_SetSource(uint8_t *source); 364 365 /** 366 * @brief Set the destination address of the DMA 367 * 368 * @param dest pointer to destination 369 */ 370 void MXC_CTB_DMA_SetDestination(uint8_t *dest); 371 372 /** 373 * @brief Set the source and destination addresses of the DMA 374 * 375 * @param req request structure that contains the source and destination 376 * information. A destination address of NULL will indicate 377 * that the Read Source has been set as something other than memory. 378 * 379 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 380 */ 381 int MXC_CTB_DMA_SetupOperation(mxc_ctb_dma_req_t *req); 382 383 /** 384 * @brief Start a DMA transfer defined by the request object 385 * Blocks until completion 386 * 387 * @param req request structure that contains the source and destination 388 * information. A destination address of NULL will indicate 389 * that the Read Source has been set as something other than memory. 390 * 391 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 392 */ 393 int MXC_CTB_DMA_DoOperation(mxc_ctb_dma_req_t *req); 394 395 /** 396 * @brief Start a DMA transfer of fixed size 397 * 398 * @param length Number of bytes to transfer 399 * 400 */ 401 void MXC_CTB_DMA_StartTransfer(uint32_t length); 402 403 /* ************************************************************************* */ 404 /* True Random Number Generator (TRNG) functions */ 405 /* ************************************************************************* */ 406 407 /** 408 * @brief Get a random number 409 * 410 * @return A random 32-bit number 411 */ 412 int MXC_CTB_TRNG_RandomInt(void); 413 414 /** 415 * @brief Get a random number of length len 416 * 417 * @param data Pointer to a location to store the number 418 * @param len Length of random number in bytes 419 * 420 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 421 */ 422 int MXC_CTB_TRNG_Random(uint8_t *data, uint32_t len); 423 424 /** 425 * @brief Get a random number of length len, do not block while generating data 426 * @note The user must call MXC_CTB_Handler() in the ISR 427 * 428 * @param data Pointer to a location to store the number 429 * @param len Length of random number in bytes 430 * @param callback Function that will be called when all data has been generated 431 * 432 */ 433 void MXC_CTB_TRNG_RandomAsync(uint8_t *data, uint32_t len, mxc_ctb_complete_cb_t callback); 434 435 /* ************************************************************************* */ 436 /* Error Correction Code (ECC) functions */ 437 /* ************************************************************************* */ 438 439 /*******************************/ 440 /* Low Level Functions */ 441 /*******************************/ 442 443 /** 444 * @brief Enable ECC Calculation 445 * @note ECC calculation is shared with CRC, when ECC is enabled, CRC 446 * computation is not possible 447 */ 448 void MXC_CTB_ECC_Enable(void); 449 450 /** 451 * @brief Disable ECC Calculation 452 * @note ECC calculation is shared with CRC, when ECC is enabled, CRC 453 * computation is not possible 454 */ 455 void MXC_CTB_ECC_Disable(void); 456 457 /** 458 * @brief Get the Result of an ECC Calculation 459 * 460 * @return The result of the ECC calculation 461 */ 462 uint32_t MXC_CTB_ECC_GetResult(void); 463 464 /*******************************/ 465 /* High Level Functions */ 466 /*******************************/ 467 468 /** 469 * @brief Compute the ECC value for a block of data up to 8kB in size 470 * @note This function places the computed ECC value in the appropriate 471 * place in the mxc_ctb_ecc_req_t structure 472 * 473 * @param req Structure containing data for the ECC request 474 * 475 * @return see \ref MXC_Error_Codes for a list of return codes. 476 */ 477 int MXC_CTB_ECC_Compute(mxc_ctb_ecc_req_t *req); 478 479 /** 480 * @brief Check for single or dual bit errors in a block of data 481 * @note This function will also correct single bit errors as needed 482 * 483 * @param req Structure containing data for the ECC request 484 * 485 * @return Positive values for 1 or 2 bit errors, respectively 486 * otherwise, see \ref MXC_Error_Codes for a list of return codes. 487 */ 488 int MXC_CTB_ECC_ErrorCheck(mxc_ctb_ecc_req_t *req); 489 490 /** 491 * @brief Compute the ECC value for a block of data up to 8kB in size 492 * @note This function places the computed ECC value in the appropriate 493 * place in the mxc_ctb_ecc_req_t structure. The user needs to call 494 * MXC_CTB_Handler() in the ISR 495 * 496 * @param req Structure containing data for the ECC request 497 */ 498 void MXC_CTB_ECC_ComputeAsync(mxc_ctb_ecc_req_t *req); 499 500 /** 501 * @brief Check for single or dual bit errors in a block of data 502 * @note This function will also correct single bit errors as needed 503 * The user must call MXC_CTB_Handler() in the ISR. 504 * 505 * @param req Structure containing data for the ECC request 506 */ 507 void MXC_CTB_ECC_ErrorCheckAsync(mxc_ctb_ecc_req_t *req); 508 509 /* ************************************************************************* */ 510 /* Cyclic Redundancy Check (CRC) functions */ 511 /* ************************************************************************* */ 512 513 /*******************************/ 514 /* Low Level Functions */ 515 /*******************************/ 516 517 /** 518 * @brief Set the bit-order of CRC calculation 519 * 520 * @param bitOrder The direction to perform CRC calculation in, \ref mxc_ctb_crc_bitorder_t 521 */ 522 void MXC_CTB_CRC_SetDirection(mxc_ctb_crc_bitorder_t bitOrder); 523 524 /** 525 * @brief Set the bit-order of CRC calculation 526 * 527 * @return The direction of calculation, 1 for MSB first, 0 for LSB first , \ref mxc_ctb_crc_bitorder_t 528 */ 529 mxc_ctb_crc_bitorder_t MXC_CTB_CRC_GetDirection(void); 530 531 /** 532 * @brief Set the Polynomial for CRC calculation 533 * 534 * @param poly The polynomial to use for CRC calculation 535 */ 536 void MXC_CTB_CRC_SetPoly(uint32_t poly); 537 538 /** 539 * @brief Get the polynomial for CRC calculation 540 * 541 * @return The polynomial used in calculation 542 */ 543 uint32_t MXC_CTB_CRC_GetPoly(void); 544 545 /** 546 * @brief Get the result of a CRC calculation 547 * 548 * @return The calculated CRC value 549 */ 550 uint32_t MXC_CTB_CRC_GetResult(void); 551 552 /** 553 * @brief Set the intial value used (the seed) when starting a CRC computation. 554 * 555 * @param seed The value to seed the CRC generator with 556 */ 557 void MXC_CTB_CRC_SetInitialValue(uint32_t seed); 558 559 /** 560 * @brief Set the value that will be bitwise XORed with the final output from the CRC computation. Use 0 to skip the XOR step. 561 * 562 * @param xor The value that will be XORed with the CRC 563 */ 564 void MXC_CTB_CRC_SetFinalXORValue(uint32_t xor); 565 566 /*******************************/ 567 /* High Level Functions */ 568 /*******************************/ 569 570 /** 571 * @brief Perform a CRC computation 572 * @note The result of the CRC calculation will be placed in the 573 * mxc_ctb_crc_req_t structure 574 * 575 * @param req Structure containing the data for calculation 576 * 577 * @return see \ref MXC_Error_Codes for a list of return codes. 578 */ 579 int MXC_CTB_CRC_Compute(mxc_ctb_crc_req_t *req); 580 581 /** 582 * @brief Perform a CRC computation asynchronously 583 * @note The result of the CRC calculation will be placed in the 584 * mxc_ctb_crc_req_t structure. The user must call 585 * MXC_CTB_Handler() in the ISR 586 * 587 * @param req Structure containing the data for calculation 588 */ 589 void MXC_CTB_CRC_ComputeAsync(mxc_ctb_crc_req_t *req); 590 591 /* ************************************************************************* */ 592 /* Hash functions */ 593 /* ************************************************************************* */ 594 595 /***********************/ 596 /* Low Level Functions */ 597 /***********************/ 598 599 /** 600 * @brief Get the block size for a given hash function 601 * 602 * @param function See \ref mxc_ctb_hash_func_t for options 603 * 604 * @return Block size in bytes 605 */ 606 unsigned int MXC_CTB_Hash_GetBlockSize(mxc_ctb_hash_func_t function); 607 608 /** 609 * @brief Get the digest size for a given hash function 610 * 611 * @param function See \ref mxc_ctb_hash_func_t for options 612 * 613 * @return Digest size in bytes 614 */ 615 unsigned int MXC_CTB_Hash_GetDigestSize(mxc_ctb_hash_func_t function); 616 617 /** 618 * @brief Set the algorithm to use for hash computation 619 * 620 * @param function See \ref mxc_ctb_hash_func_t for options 621 */ 622 void MXC_CTB_Hash_SetFunction(mxc_ctb_hash_func_t function); 623 624 /** 625 * @brief Get the algorithm to use for hash computation 626 * 627 * @return See \ref mxc_ctb_hash_func_t for options 628 */ 629 mxc_ctb_hash_func_t MXC_CTB_Hash_GetFunction(void); 630 631 /** 632 * @brief Set whether to use automatic padding of the input data 633 * @note The padding procedure used by hardware is described in the users guide 634 * 635 * @param pad Use hardware padding of the data 636 */ 637 void MXC_CTB_Hash_SetAutoPad(int pad); 638 639 /** 640 * @brief Get whether to use automatic padding of the input data 641 * 642 * @return Using hardware padding of the data 643 */ 644 int MXC_CTB_Hash_GetAutoPad(void); 645 646 /** 647 * @brief Get the result of a hash computation 648 * 649 * @param digest buffer to store the ouctbt of the hash algorithm 650 * @param len location to store the length of the digest 651 */ 652 void MXC_CTB_Hash_GetResult(uint8_t *digest, int *len); 653 654 /** 655 * @brief Set the size of the data input into the hash computation 656 * @note Hash data size is software limited to ~3GB 657 * 658 * @param size Size of the data in bytes 659 */ 660 void MXC_CTB_Hash_SetMessageSize(uint32_t size); 661 662 /** 663 * @brief Set the source of data for the hash computation 664 * 665 * @param source see \ref mxc_ctb_hash_source_t for options 666 */ 667 void MXC_CTB_Hash_SetSource(mxc_ctb_hash_source_t source); 668 669 /** 670 * @brief Get the source of data for the hash computation 671 * 672 * @return See \ref mxc_ctb_hash_source_t for options 673 */ 674 mxc_ctb_hash_source_t MXC_CTB_Hash_GetSource(void); 675 676 /** 677 * @brief Initialize the hash computation unit 678 * @note Call this after setting the hash function and message size 679 * This function blocks until load is complete 680 * 681 */ 682 void MXC_CTB_Hash_InitializeHash(void); 683 684 /************************/ 685 /* High Level Functions */ 686 /************************/ 687 688 /** 689 * @brief Compute a Hash Digest 690 * @note The computed digest will be stored in the req structure 691 * 692 * @param req Structure containing all data needed for a hash computation 693 * 694 * @return See \ref MXC_Error_Codes for a list of return codes 695 */ 696 int MXC_CTB_Hash_Compute(mxc_ctb_hash_req_t *req); 697 698 /** 699 * @brief Compute a Hash Digest 700 * @note The computed digest will be stored in the req structure. The user 701 * must call MXC_CTB_Handler() in the ISR. 702 * 703 * @param req Structure containing all data needed for a hash computation 704 */ 705 void MXC_CTB_Hash_ComputeAsync(mxc_ctb_hash_req_t *req); 706 707 /* ************************************************************************* */ 708 /* Cipher functions */ 709 /* ************************************************************************* */ 710 711 /************************/ 712 /* Low Level Functions */ 713 /************************/ 714 715 /** 716 * @brief Get the key size for a given cipher type 717 * 718 * @param cipher See \ref mxc_ctb_cipher_t for options 719 * 720 * @return Size of the key in bytes 721 */ 722 unsigned int MXC_CTB_Cipher_GetKeySize(mxc_ctb_cipher_t cipher); 723 724 /** 725 * @brief Get the block size for a given cipher type 726 * 727 * @param cipher See \ref mxc_ctb_cipher_t for options 728 * 729 * @return Size of the block in bytes 730 */ 731 unsigned int MXC_CTB_Cipher_GetBlockSize(mxc_ctb_cipher_t cipher); 732 733 /** 734 * @brief Set the block mode used for cipher operations 735 * 736 * @param mode See \ref mxc_ctb_cipher_mode_t for options 737 */ 738 void MXC_CTB_Cipher_SetMode(mxc_ctb_cipher_mode_t mode); 739 740 /** 741 * @brief Get the block mode used for cipher operations 742 * 743 * @return See \ref mxc_ctb_cipher_mode_t for options 744 */ 745 mxc_ctb_cipher_mode_t MXC_CTB_Cipher_GetMode(void); 746 747 /** 748 * @brief Set the cipher type used for cipher operations 749 * 750 * @param cipher See \ref mxc_ctb_cipher_t for options 751 */ 752 void MXC_CTB_Cipher_SetCipher(mxc_ctb_cipher_t cipher); 753 754 /** 755 * @brief Get the cipher type used for cipher operations 756 * 757 * @return See \ref mxc_ctb_cipher_t for options 758 */ 759 mxc_ctb_cipher_t MXC_CTB_Cipher_GetCipher(void); 760 761 /** 762 * @brief Set the source of the key used in cipher operations 763 * 764 * @param source See \ref mxc_ctb_cipher_key_t for options 765 */ 766 void MXC_CTB_Cipher_SetKeySource(mxc_ctb_cipher_key_t source); 767 768 /** 769 * @brief Get the cipher type used for cipher operations 770 * 771 * @return See \ref mxc_ctb_cipher_key_t for options 772 */ 773 mxc_ctb_cipher_key_t MXC_CTB_Cipher_GetKeySource(void); 774 775 /** 776 * @brief Load the cipher key from the selected source 777 * 778 */ 779 void MXC_CTB_Cipher_LoadKey(void); 780 781 /** 782 * @brief Configure for encryption or decryption 783 * 784 * @param operation Set to perform encryption/decryption \ref mxc_ctb_cipher_operation_t 785 */ 786 void MXC_CTB_Cipher_SetOperation(mxc_ctb_cipher_operation_t operation); 787 788 /** 789 * @brief Set the cipher key 790 * @note This only takes effect if software is the selected key source 791 * 792 * @param key buffer containing key 793 * @param len length of key (dependent on cipher used) 794 */ 795 void MXC_CTB_Cipher_SetKey(uint8_t *key, uint32_t len); 796 797 /** 798 * @brief Set the initial value used for cipher operations 799 * 800 * @param iv buffer containing iv 801 * @param len length of initial value 802 */ 803 void MXC_CTB_Cipher_SetIV(uint8_t *iv, uint32_t len); 804 805 /** 806 * @brief Get the initial value used for cipher operations 807 * 808 * @param ivOut buffer containing iv 809 * @param len length of buffer 810 */ 811 void MXC_CTB_Cipher_GetIV(uint8_t *ivOut, uint32_t len); 812 813 /************************/ 814 /* High Level Functions */ 815 /************************/ 816 817 /** 818 * @brief Perform an encryption using the cipher feature 819 * @note The result will be stored in the req structure 820 * 821 * @param req Structure containing data for the encryption 822 * 823 * @return See \ref MXC_Error_Codes for a list of return codes. 824 */ 825 int MXC_CTB_Cipher_Encrypt(mxc_ctb_cipher_req_t *req); 826 827 /** 828 * @brief Perform a decryption using the cipher feature 829 * @note The result will be stored in the req structure 830 * 831 * @param req Structure containing data for the decryption 832 * 833 * @return See \ref MXC_Error_Codes for a list of return codes. 834 */ 835 int MXC_CTB_Cipher_Decrypt(mxc_ctb_cipher_req_t *req); 836 837 /** 838 * @brief Perform an encryption using the cipher feature 839 * @note The result will be stored in the req structure. The user needs 840 * to call MXC_CTB_Handler() in the ISR 841 * 842 * @param req Structure containing data for the encryption 843 */ 844 void MXC_CTB_Cipher_EncryptAsync(mxc_ctb_cipher_req_t *req); 845 846 /** 847 * @brief Perform a decryption using the cipher feature 848 * @note The result will be stored in the req structure. The user needs 849 * to call MXC_CTB_Handler() in the ISR 850 * 851 * @param req Structure containing data for the decryption 852 */ 853 void MXC_CTB_Cipher_DecryptAsync(mxc_ctb_cipher_req_t *req); 854 855 #ifdef __cplusplus 856 } 857 #endif 858 /**@} end of group ctb */ 859 860 #endif // LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32690_CTB_H_ 861
