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_MAX32572_CTB_H_ 27 #define LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32572_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 { MXC_CTB_CIPHER_ENCRYPTION, MXC_CTB_CIPHER_DECRYPTION } mxc_ctb_cipher_operation_t; 223 224 /***** Function Prototypes *****/ 225 226 /* ************************************************************************* */ 227 /* Global Control/Configuration functions */ 228 /* ************************************************************************* */ 229 230 /** 231 * @brief Enable portions of the CTB 232 * 233 * @param features bit banded value indicating features to enable 234 * see \ref mxc_ctb_features_t for a list of features 235 * 236 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 237 */ 238 int MXC_CTB_Init(uint32_t features); 239 240 /** 241 * @brief Detects what CTB features exist, see \ref mxc_ctb_features_t 242 * 243 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 244 */ 245 uint32_t MXC_CTB_CheckFeatures(void); 246 247 /** 248 * @brief Enable CTB Interrupts 249 * 250 */ 251 void MXC_CTB_EnableInt(void); 252 253 /** 254 * @brief Disable CTB Interrupts 255 * 256 */ 257 void MXC_CTB_DisableInt(void); 258 259 /** 260 * @brief Checks the global CTB Ready Status 261 * 262 * @return Nonzero if ready, zero if not ready or \ref MXC_Error_Codes. 263 */ 264 int MXC_CTB_Ready(void); 265 266 /** 267 * @brief Clears the selected feature's done bits, see \ref mxc_ctb_features_t 268 * 269 * @param features bit banded value indicating features to clear 270 */ 271 void MXC_CTB_DoneClear(uint32_t features); 272 273 /** 274 * @brief Returns CTB features showing operations complete, see \ref mxc_ctb_features_t 275 * 276 * @return CTB features showing operations complete, see \ref mxc_ctb_features_t. 277 */ 278 uint32_t MXC_CTB_Done(void); 279 280 /** 281 * @brief Resets the selected features, see \ref mxc_ctb_features_t 282 * 283 * @param features bit banded value indicating features to reset 284 */ 285 void MXC_CTB_Reset(uint32_t features); 286 287 /** 288 * @brief Disable and reset portions of the CTB 289 * 290 * @param features bit banded value indicating features to shutdown 291 * see \ref mxc_ctb_features_t for a list of features 292 * 293 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 294 */ 295 int MXC_CTB_Shutdown(uint32_t features); 296 297 /** 298 * @brief Check which CTB features are enabled 299 * 300 * @return CTB features showing features enabled, see \ref mxc_ctb_features_t. 301 */ 302 uint32_t MXC_CTB_GetEnabledFeatures(void); 303 304 /** 305 * @brief This function should be called from the CTB ISR Handler 306 * when using Async functions 307 */ 308 void MXC_CTB_Handler(void); 309 310 /************************************/ 311 /* CTB DMA - Used for all features */ 312 /************************************/ 313 314 /** 315 * @brief Set the source the DMA reads from 316 * @note The DMA is unable to read directly from Flash 317 * 318 * @param source The source of the data for DMA read operations 319 * see \ref mxc_ctb_dma_read_source_t for a list of sources 320 */ 321 void MXC_CTB_DMA_SetReadSource(mxc_ctb_dma_read_source_t source); 322 323 /** 324 * @brief Get the source the DMA reads from 325 * 326 * @return The source of the data for DMA read operations 327 * see \ref mxc_ctb_dma_read_source_t for a list of sources 328 */ 329 mxc_ctb_dma_read_source_t MXC_CTB_DMA_GetReadSource(void); 330 331 /** 332 * @brief Set the source the DMA write fifo reads from 333 * 334 * @param source The source of the data for DMA write operations 335 * see \ref mxc_ctb_dma_write_source_t for a list of sources 336 */ 337 void MXC_CTB_DMA_SetWriteSource(mxc_ctb_dma_write_source_t source); 338 339 /** 340 * @brief Set the source the DMA write fifo reads from 341 * 342 * @return The source of the data for DMA write operations 343 * see \ref mxc_ctb_dma_write_source_t for a list of sources 344 */ 345 mxc_ctb_dma_write_source_t MXC_CTB_DMA_GetWriteSource(void); 346 347 /** 348 * @brief Set the source address of the DMA 349 * @note This is only applicable when the read source is memory 350 * The DMA is unable to read directly from Flash 351 * 352 * @param source pointer to the source location 353 */ 354 void MXC_CTB_DMA_SetSource(uint8_t *source); 355 356 /** 357 * @brief Set the destination address of the DMA 358 * 359 * @param dest pointer to destination 360 */ 361 void MXC_CTB_DMA_SetDestination(uint8_t *dest); 362 363 /** 364 * @brief Set the source and destination addresses of the DMA 365 * 366 * @param req request structure that contains the source and destination 367 * information. A destination address of NULL will indicate 368 * that the Read Source has been set as something other than memory. 369 * 370 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 371 */ 372 int MXC_CTB_DMA_SetupOperation(mxc_ctb_dma_req_t *req); 373 374 /** 375 * @brief Start a DMA transfer defined by the request object 376 * Blocks until completion 377 * 378 * @param req request structure that contains the source and destination 379 * information. A destination address of NULL will indicate 380 * that the Read Source has been set as something other than memory. 381 * 382 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 383 */ 384 int MXC_CTB_DMA_DoOperation(mxc_ctb_dma_req_t *req); 385 386 /** 387 * @brief Start a DMA transfer of fixed size 388 * 389 * @param length Number of bytes to transfer 390 * 391 */ 392 void MXC_CTB_DMA_StartTransfer(uint32_t length); 393 394 /* ************************************************************************* */ 395 /* True Random Number Generator (TRNG) functions */ 396 /* ************************************************************************* */ 397 398 /** 399 * @brief Get a random number 400 * 401 * @return A random 32-bit number 402 */ 403 int MXC_CTB_TRNG_RandomInt(void); 404 405 /** 406 * @brief Get a random number of length len 407 * 408 * @param data Pointer to a location to store the number 409 * @param len Length of random number in bytes 410 * 411 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 412 */ 413 int MXC_CTB_TRNG_Random(uint8_t *data, uint32_t len); 414 415 /** 416 * @brief Get a random number of length len, do not block while generating data 417 * @note The user must call MXC_CTB_Handler() in the ISR 418 * 419 * @param data Pointer to a location to store the number 420 * @param len Length of random number in bytes 421 * @param callback Function that will be called when all data has been generated 422 * 423 */ 424 void MXC_CTB_TRNG_RandomAsync(uint8_t *data, uint32_t len, mxc_ctb_complete_cb_t callback); 425 426 /* ************************************************************************* */ 427 /* Error Correction Code (ECC) functions */ 428 /* ************************************************************************* */ 429 430 /*******************************/ 431 /* Low Level Functions */ 432 /*******************************/ 433 434 /** 435 * @brief Enable ECC Calculation 436 * @note ECC calculation is shared with CRC, when ECC is enabled, CRC 437 * computation is not possible 438 */ 439 void MXC_CTB_ECC_Enable(void); 440 441 /** 442 * @brief Disable ECC Calculation 443 * @note ECC calculation is shared with CRC, when ECC is enabled, CRC 444 * computation is not possible 445 */ 446 void MXC_CTB_ECC_Disable(void); 447 448 /** 449 * @brief Get the Result of an ECC Calculation 450 * 451 * @return The result of the ECC calculation 452 */ 453 uint32_t MXC_CTB_ECC_GetResult(void); 454 455 /*******************************/ 456 /* High Level Functions */ 457 /*******************************/ 458 459 /** 460 * @brief Compute the ECC value for a block of data up to 8kB in size 461 * @note This function places the computed ECC value in the appropriate 462 * place in the mxc_ctb_ecc_req_t structure 463 * 464 * @param req Structure containing data for the ECC request 465 * 466 * @return see \ref MXC_Error_Codes for a list of return codes. 467 */ 468 int MXC_CTB_ECC_Compute(mxc_ctb_ecc_req_t *req); 469 470 /** 471 * @brief Check for single or dual bit errors in a block of data 472 * @note This function will also correct single bit errors as needed 473 * 474 * @param req Structure containing data for the ECC request 475 * 476 * @return Positive values for 1 or 2 bit errors, respectively 477 * otherwise, see \ref MXC_Error_Codes for a list of return codes. 478 */ 479 int MXC_CTB_ECC_ErrorCheck(mxc_ctb_ecc_req_t *req); 480 481 /** 482 * @brief Compute the ECC value for a block of data up to 8kB in size 483 * @note This function places the computed ECC value in the appropriate 484 * place in the mxc_ctb_ecc_req_t structure. The user needs to call 485 * MXC_CTB_Handler() in the ISR 486 * 487 * @param req Structure containing data for the ECC request 488 */ 489 void MXC_CTB_ECC_ComputeAsync(mxc_ctb_ecc_req_t *req); 490 491 /** 492 * @brief Check for single or dual bit errors in a block of data 493 * @note This function will also correct single bit errors as needed 494 * The user must call MXC_CTB_Handler() in the ISR. 495 * 496 * @param req Structure containing data for the ECC request 497 */ 498 void MXC_CTB_ECC_ErrorCheckAsync(mxc_ctb_ecc_req_t *req); 499 500 /* ************************************************************************* */ 501 /* Cyclic Redundancy Check (CRC) functions */ 502 /* ************************************************************************* */ 503 504 /*******************************/ 505 /* Low Level Functions */ 506 /*******************************/ 507 508 /** 509 * @brief Set the bit-order of CRC calculation 510 * 511 * @param bitOrder The direction to perform CRC calculation in, \ref mxc_ctb_crc_bitorder_t 512 */ 513 void MXC_CTB_CRC_SetDirection(mxc_ctb_crc_bitorder_t bitOrder); 514 515 /** 516 * @brief Set the bit-order of CRC calculation 517 * 518 * @return The direction of calculation, 1 for MSB first, 0 for LSB first , \ref mxc_ctb_crc_bitorder_t 519 */ 520 mxc_ctb_crc_bitorder_t MXC_CTB_CRC_GetDirection(void); 521 522 /** 523 * @brief Set the Polynomial for CRC calculation 524 * 525 * @param poly The polynomial to use for CRC calculation 526 */ 527 void MXC_CTB_CRC_SetPoly(uint32_t poly); 528 529 /** 530 * @brief Get the polynomial for CRC calculation 531 * 532 * @return The polynomial used in calculation 533 */ 534 uint32_t MXC_CTB_CRC_GetPoly(void); 535 536 /** 537 * @brief Get the result of a CRC calculation 538 * 539 * @return The calculated CRC value 540 */ 541 uint32_t MXC_CTB_CRC_GetResult(void); 542 543 /** 544 * @brief Set the intial value used (the seed) when starting a CRC computation. 545 * 546 * @param seed The value to seed the CRC generator with 547 */ 548 void MXC_CTB_CRC_SetInitialValue(uint32_t seed); 549 550 /** 551 * @brief Set the value that will be bitwise XORed with the final output from the CRC computation. Use 0 to skip the XOR step. 552 * 553 * @param xor The value that will be XORed with the CRC 554 */ 555 void MXC_CTB_CRC_SetFinalXORValue(uint32_t xor); 556 557 /*******************************/ 558 /* High Level Functions */ 559 /*******************************/ 560 561 /** 562 * @brief Perform a CRC computation 563 * @note The result of the CRC calculation will be placed in the 564 * mxc_ctb_crc_req_t structure 565 * 566 * @param req Structure containing the data for calculation 567 * 568 * @return see \ref MXC_Error_Codes for a list of return codes. 569 */ 570 int MXC_CTB_CRC_Compute(mxc_ctb_crc_req_t *req); 571 572 /** 573 * @brief Perform a CRC computation asynchronously 574 * @note The result of the CRC calculation will be placed in the 575 * mxc_ctb_crc_req_t structure. The user must call 576 * MXC_CTB_Handler() in the ISR 577 * 578 * @param req Structure containing the data for calculation 579 */ 580 void MXC_CTB_CRC_ComputeAsync(mxc_ctb_crc_req_t *req); 581 582 /* ************************************************************************* */ 583 /* Hash functions */ 584 /* ************************************************************************* */ 585 586 /***********************/ 587 /* Low Level Functions */ 588 /***********************/ 589 590 /** 591 * @brief Get the block size for a given hash function 592 * 593 * @param function See \ref mxc_ctb_hash_func_t for options 594 * 595 * @return Block size in bytes 596 */ 597 unsigned int MXC_CTB_Hash_GetBlockSize(mxc_ctb_hash_func_t function); 598 599 /** 600 * @brief Get the digest size for a given hash function 601 * 602 * @param function See \ref mxc_ctb_hash_func_t for options 603 * 604 * @return Digest size in bytes 605 */ 606 unsigned int MXC_CTB_Hash_GetDigestSize(mxc_ctb_hash_func_t function); 607 608 /** 609 * @brief Set the algorithm to use for hash computation 610 * 611 * @param function See \ref mxc_ctb_hash_func_t for options 612 */ 613 void MXC_CTB_Hash_SetFunction(mxc_ctb_hash_func_t function); 614 615 /** 616 * @brief Get the algorithm to use for hash computation 617 * 618 * @return See \ref mxc_ctb_hash_func_t for options 619 */ 620 mxc_ctb_hash_func_t MXC_CTB_Hash_GetFunction(void); 621 622 /** 623 * @brief Set whether to use automatic padding of the input data 624 * @note The padding procedure used by hardware is described in the users guide 625 * 626 * @param pad Use hardware padding of the data 627 */ 628 void MXC_CTB_Hash_SetAutoPad(int pad); 629 630 /** 631 * @brief Get whether to use automatic padding of the input data 632 * 633 * @return Using hardware padding of the data 634 */ 635 int MXC_CTB_Hash_GetAutoPad(void); 636 637 /** 638 * @brief Get the result of a hash computation 639 * 640 * @param digest buffer to store the ouctbt of the hash algorithm 641 * @param len location to store the length of the digest 642 */ 643 void MXC_CTB_Hash_GetResult(uint8_t *digest, int *len); 644 645 /** 646 * @brief Set the size of the data input into the hash computation 647 * @note Hash data size is software limited to ~3GB 648 * 649 * @param size Size of the data in bytes 650 */ 651 void MXC_CTB_Hash_SetMessageSize(uint32_t size); 652 653 /** 654 * @brief Set the source of data for the hash computation 655 * 656 * @param source see \ref mxc_ctb_hash_source_t for options 657 */ 658 void MXC_CTB_Hash_SetSource(mxc_ctb_hash_source_t source); 659 660 /** 661 * @brief Get the source of data for the hash computation 662 * 663 * @return See \ref mxc_ctb_hash_source_t for options 664 */ 665 mxc_ctb_hash_source_t MXC_CTB_Hash_GetSource(void); 666 667 /** 668 * @brief Initialize the hash computation unit 669 * @note Call this after setting the hash function and message size 670 * This function blocks until load is complete 671 * 672 */ 673 void MXC_CTB_Hash_InitializeHash(void); 674 675 /************************/ 676 /* High Level Functions */ 677 /************************/ 678 679 /** 680 * @brief Compute a Hash Digest 681 * @note The computed digest will be stored in the req structure 682 * 683 * @param req Structure containing all data needed for a hash computation 684 * 685 * @return See \ref MXC_Error_Codes for a list of return codes 686 */ 687 int MXC_CTB_Hash_Compute(mxc_ctb_hash_req_t *req); 688 689 /** 690 * @brief Compute a Hash Digest 691 * @note The computed digest will be stored in the req structure. The user 692 * must call MXC_CTB_Handler() in the ISR. 693 * 694 * @param req Structure containing all data needed for a hash computation 695 */ 696 void MXC_CTB_Hash_ComputeAsync(mxc_ctb_hash_req_t *req); 697 698 /* ************************************************************************* */ 699 /* Cipher functions */ 700 /* ************************************************************************* */ 701 702 /************************/ 703 /* Low Level Functions */ 704 /************************/ 705 706 /** 707 * @brief Get the key size for a given cipher type 708 * 709 * @param cipher See \ref mxc_ctb_cipher_t for options 710 * 711 * @return Size of the key in bytes 712 */ 713 unsigned int MXC_CTB_Cipher_GetKeySize(mxc_ctb_cipher_t cipher); 714 715 /** 716 * @brief Get the block size for a given cipher type 717 * 718 * @param cipher See \ref mxc_ctb_cipher_t for options 719 * 720 * @return Size of the block in bytes 721 */ 722 unsigned int MXC_CTB_Cipher_GetBlockSize(mxc_ctb_cipher_t cipher); 723 724 /** 725 * @brief Set the block mode used for cipher operations 726 * 727 * @param mode See \ref mxc_ctb_cipher_mode_t for options 728 */ 729 void MXC_CTB_Cipher_SetMode(mxc_ctb_cipher_mode_t mode); 730 731 /** 732 * @brief Get the block mode used for cipher operations 733 * 734 * @return See \ref mxc_ctb_cipher_mode_t for options 735 */ 736 mxc_ctb_cipher_mode_t MXC_CTB_Cipher_GetMode(void); 737 738 /** 739 * @brief Set the cipher type used for cipher operations 740 * 741 * @param cipher See \ref mxc_ctb_cipher_t for options 742 */ 743 void MXC_CTB_Cipher_SetCipher(mxc_ctb_cipher_t cipher); 744 745 /** 746 * @brief Get the cipher type used for cipher operations 747 * 748 * @return See \ref mxc_ctb_cipher_t for options 749 */ 750 mxc_ctb_cipher_t MXC_CTB_Cipher_GetCipher(void); 751 752 /** 753 * @brief Set the source of the key used in cipher operations 754 * 755 * @param source See \ref mxc_ctb_cipher_key_t for options 756 */ 757 void MXC_CTB_Cipher_SetKeySource(mxc_ctb_cipher_key_t source); 758 759 /** 760 * @brief Get the cipher type used for cipher operations 761 * 762 * @return See \ref mxc_ctb_cipher_key_t for options 763 */ 764 mxc_ctb_cipher_key_t MXC_CTB_Cipher_GetKeySource(void); 765 766 /** 767 * @brief Load the cipher key from the selected source 768 * 769 */ 770 void MXC_CTB_Cipher_LoadKey(void); 771 772 /** 773 * @brief Configure for encryption or decryption 774 * 775 * @param operation Set to perform encryption/decryption \ref mxc_ctb_cipher_operation_t 776 */ 777 void MXC_CTB_Cipher_SetOperation(mxc_ctb_cipher_operation_t operation); 778 779 /** 780 * @brief Set the cipher key 781 * @note This only takes effect if software is the selected key source 782 * 783 * @param key buffer containing key 784 * @param len length of key (dependent on cipher used) 785 */ 786 void MXC_CTB_Cipher_SetKey(uint8_t *key, uint32_t len); 787 788 /** 789 * @brief Set the initial value used for cipher operations 790 * 791 * @param iv buffer containing iv 792 * @param len length of initial value 793 */ 794 void MXC_CTB_Cipher_SetIV(uint8_t *iv, uint32_t len); 795 796 /** 797 * @brief Get the initial value used for cipher operations 798 * 799 * @param ivOut buffer containing iv 800 * @param len length of buffer 801 */ 802 void MXC_CTB_Cipher_GetIV(uint8_t *ivOut, uint32_t len); 803 804 /************************/ 805 /* High Level Functions */ 806 /************************/ 807 808 /** 809 * @brief Perform an encryption using the cipher feature 810 * @note The result will be stored in the req structure 811 * 812 * @param req Structure containing data for the encryption 813 * 814 * @return See \ref MXC_Error_Codes for a list of return codes. 815 */ 816 int MXC_CTB_Cipher_Encrypt(mxc_ctb_cipher_req_t *req); 817 818 /** 819 * @brief Perform a decryption using the cipher feature 820 * @note The result will be stored in the req structure 821 * 822 * @param req Structure containing data for the decryption 823 * 824 * @return See \ref MXC_Error_Codes for a list of return codes. 825 */ 826 int MXC_CTB_Cipher_Decrypt(mxc_ctb_cipher_req_t *req); 827 828 /** 829 * @brief Perform an encryption using the cipher feature 830 * @note The result will be stored in the req structure. The user needs 831 * to call MXC_CTB_Handler() in the ISR 832 * 833 * @param req Structure containing data for the encryption 834 */ 835 void MXC_CTB_Cipher_EncryptAsync(mxc_ctb_cipher_req_t *req); 836 837 /** 838 * @brief Perform a decryption 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 decryption 843 */ 844 void MXC_CTB_Cipher_DecryptAsync(mxc_ctb_cipher_req_t *req); 845 846 #ifdef __cplusplus 847 } 848 #endif 849 /**@} end of group ctb */ 850 851 #endif // LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32572_CTB_H_ 852
