1 /***************************************************************************//** 2 * @file 3 * @brief Silicon Labs Secure Engine Manager API. 4 ******************************************************************************* 5 * # License 6 * <b>Copyright 2020 Silicon Laboratories Inc. www.silabs.com</b> 7 ******************************************************************************* 8 * 9 * SPDX-License-Identifier: Zlib 10 * 11 * The licensor of this software is Silicon Laboratories Inc. 12 * 13 * This software is provided 'as-is', without any express or implied 14 * warranty. In no event will the authors be held liable for any damages 15 * arising from the use of this software. 16 * 17 * Permission is granted to anyone to use this software for any purpose, 18 * including commercial applications, and to alter it and redistribute it 19 * freely, subject to the following restrictions: 20 * 21 * 1. The origin of this software must not be misrepresented; you must not 22 * claim that you wrote the original software. If you use this software 23 * in a product, an acknowledgment in the product documentation would be 24 * appreciated but is not required. 25 * 2. Altered source versions must be plainly marked as such, and must not be 26 * misrepresented as being the original software. 27 * 3. This notice may not be removed or altered from any source distribution. 28 * 29 ******************************************************************************/ 30 #ifndef SL_SE_MANAGER_CIPHER_H 31 #define SL_SE_MANAGER_CIPHER_H 32 33 #include "sli_se_manager_features.h" 34 35 #if defined(SLI_MAILBOX_COMMAND_SUPPORTED) 36 37 /// @addtogroup sl_se_manager 38 /// @{ 39 40 /***************************************************************************//** 41 * @addtogroup sl_se_manager_cipher Cipher 42 * 43 * @brief 44 * Symmetric encryption, AEAD and MAC. 45 * 46 * @details 47 * API for performing symmetric encryption, Authenticated Encryption and 48 * Additional Data (AEAD) operations, and computing Message Authentication 49 * Codes (MACs) using the Secure Engine. 50 * 51 * @{ 52 ******************************************************************************/ 53 54 #include "sl_se_manager_key_handling.h" 55 #include "sl_se_manager_types.h" 56 #include "sli_se_manager_mailbox.h" 57 #include "sl_status.h" 58 #include <stdint.h> 59 #include <stdbool.h> 60 #include <stddef.h> 61 62 #ifdef __cplusplus 63 extern "C" { 64 #endif 65 66 // ----------------------------------------------------------------------------- 67 // Prototypes 68 69 /***************************************************************************//** 70 * @brief 71 * AES-ECB block encryption/decryption. 72 * 73 * @param[in] cmd_ctx 74 * Pointer to an SE command context object. 75 * 76 * @param[in] key 77 * Pointer to sl_se_key_descriptor_t structure. 78 * 79 * @param[in] mode 80 * Crypto operation type (encryption or decryption). 81 * 82 * @param[in] length 83 * Length of the input data. 84 * 85 * @param[in] input 86 * Buffer holding the input data. 87 * 88 * @param[out] output 89 * Buffer holding the output data. 90 * 91 * @return 92 * Status code, @ref sl_status.h. 93 ******************************************************************************/ 94 sl_status_t sl_se_aes_crypt_ecb(sl_se_command_context_t *cmd_ctx, 95 const sl_se_key_descriptor_t *key, 96 sl_se_cipher_operation_t mode, 97 size_t length, 98 const unsigned char *input, 99 unsigned char *output); 100 101 /***************************************************************************//** 102 * @brief 103 * AES-CBC buffer encryption/decryption. 104 * 105 * @note 106 * Length should be a multiple of the block size (16 bytes). 107 * 108 * @param[in] cmd_ctx 109 * Pointer to an SE command context object. 110 * 111 * @param[in] key 112 * Pointer to sl_se_key_descriptor_t structure. 113 * 114 * @param[in] mode 115 * Crypto operation type (encryption or decryption). 116 * 117 * @param[in] length 118 * Length of the input data. 119 * 120 * @param[in,out] iv 121 * Initialization vector (updated after use). 122 * 123 * @param[in] input 124 * Buffer holding the input data. 125 * 126 * @param[out] output 127 * Buffer holding the output data. 128 * 129 * @return 130 * Status code, @ref sl_status.h. 131 ******************************************************************************/ 132 sl_status_t sl_se_aes_crypt_cbc(sl_se_command_context_t *cmd_ctx, 133 const sl_se_key_descriptor_t *key, 134 sl_se_cipher_operation_t mode, 135 size_t length, 136 unsigned char iv[16], 137 const unsigned char *input, 138 unsigned char *output); 139 140 /***************************************************************************//** 141 * @brief 142 * AES-CFB128 buffer encryption/decryption. 143 * 144 * @param[in] cmd_ctx 145 * Pointer to an SE command context object. 146 * 147 * @param[in] key 148 * Pointer to sl_se_key_descriptor_t structure. 149 * 150 * @param[in] mode 151 * Crypto operation type (encryption or decryption). 152 * 153 * @param[in] length 154 * Length of the input data. 155 * 156 * @param[in,out] iv_off 157 * Offset in IV (updated after use). 158 * 159 * @param[in,out] iv 160 * Initialization vector (updated after use). 161 * 162 * @param[in] input 163 * Buffer holding the input data. 164 * 165 * @param[out] output 166 * Buffer holding the output data. 167 * 168 * @return 169 * Status code, @ref sl_status.h. 170 ******************************************************************************/ 171 sl_status_t sl_se_aes_crypt_cfb128(sl_se_command_context_t *cmd_ctx, 172 const sl_se_key_descriptor_t *key, 173 sl_se_cipher_operation_t mode, 174 size_t length, 175 uint32_t *iv_off, 176 unsigned char iv[16], 177 const unsigned char *input, 178 unsigned char *output); 179 180 /***************************************************************************//** 181 * @brief 182 * AES-CFB8 buffer encryption/decryption. 183 * 184 * @param[in] cmd_ctx 185 * Pointer to an SE command context object. 186 * 187 * @param[in] key 188 * Pointer to sl_se_key_descriptor_t structure. 189 * 190 * @param[in] mode 191 * Crypto operation type (encryption or decryption). 192 * 193 * @param[in] length 194 * Length of the input data. 195 * 196 * @param[in,out] iv 197 * Initialization vector (updated after use). 198 * 199 * @param[in] input 200 * Buffer holding the input data. 201 * 202 * @param[out] output 203 * Buffer holding the output data. 204 * 205 * @return 206 * Status code, @ref sl_status.h. 207 ******************************************************************************/ 208 sl_status_t sl_se_aes_crypt_cfb8(sl_se_command_context_t *cmd_ctx, 209 const sl_se_key_descriptor_t *key, 210 sl_se_cipher_operation_t mode, 211 size_t length, 212 unsigned char iv[16], 213 const unsigned char *input, 214 unsigned char *output); 215 216 /***************************************************************************//** 217 * @brief 218 * AES-CTR buffer encryption/decryption. 219 * 220 * @warning 221 * Avoid passing in the same buffer for nonce_counter and 222 * stream_block as the incrementation operation of 223 * nonce_counter can lead to corruption of the ciphertext 224 * 225 * @param[in] cmd_ctx 226 * Pointer to an SE command context object. 227 * 228 * @param[in] key 229 * Pointer to sl_se_key_descriptor_t structure. 230 * 231 * @param[in] length 232 * Length of the input data. 233 * 234 * @param[in] nc_off 235 * The offset in the current stream_block (for resuming 236 * within current cipher stream). The offset pointer to 237 * should be 0 at the start of a stream. 238 * 239 * @param[in,out] nonce_counter 240 * The 128-bit nonce and counter. 241 * 242 * @param[in,out] stream_block 243 * The saved stream-block for resuming (updated after use). 244 * 245 * @param[in] input 246 * Buffer holding the input data. 247 * 248 * @param[out] output 249 * Buffer holding the output data. 250 * 251 * @return 252 * Status code, @ref sl_status.h. 253 ******************************************************************************/ 254 sl_status_t sl_se_aes_crypt_ctr(sl_se_command_context_t *cmd_ctx, 255 const sl_se_key_descriptor_t *key, 256 size_t length, 257 uint32_t *nc_off, 258 unsigned char nonce_counter[16], 259 unsigned char stream_block[SLI_SE_AES_CTR_NUM_BLOCKS_BUFFERED * SL_SE_AES_BLOCK_SIZE], 260 const unsigned char *input, 261 unsigned char *output); 262 263 /***************************************************************************//** 264 * @brief 265 * AES-CCM buffer encryption. 266 * 267 * @param[in] cmd_ctx 268 * Pointer to an SE command context object. 269 * 270 * @param[in] key 271 * Pointer to sl_se_key_descriptor_t structure. 272 * 273 * @param[in] length 274 * The length of the input data in Bytes. 275 * 276 * @param[in] iv 277 * Initialization vector (nonce). 278 * 279 * @param[in] iv_len 280 * The length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13. 281 * 282 * @param[in] add 283 * The additional data field. 284 * 285 * @param[in] add_len 286 * The length of additional data in Bytes. 287 * 288 * @param[in] input 289 * The buffer holding the input data. 290 * 291 * @param[out] output 292 * The buffer holding the output data. Must be at least @p length Bytes wide. 293 * 294 * @param[in,out] tag 295 * The buffer holding the tag. 296 * 297 * @param[in] tag_len 298 * The length of the tag to generate in Bytes: 4, 6, 8, 10, 12, 14 or 16. 299 * 300 * @return 301 * Status code, @ref sl_status.h. 302 ******************************************************************************/ 303 sl_status_t sl_se_ccm_encrypt_and_tag(sl_se_command_context_t *cmd_ctx, 304 const sl_se_key_descriptor_t *key, 305 size_t length, 306 const unsigned char *iv, size_t iv_len, 307 const unsigned char *add, size_t add_len, 308 const unsigned char *input, 309 unsigned char *output, 310 unsigned char *tag, size_t tag_len); 311 312 /***************************************************************************//** 313 * @brief 314 * AES-CCM buffer decryption. 315 * 316 * @param[in] cmd_ctx 317 * Pointer to an SE command context object. 318 * 319 * @param[in] key 320 * Pointer to sl_se_key_descriptor_t structure. 321 * 322 * @param[in] length 323 * The length of the input data in Bytes. 324 * 325 * @param[in] iv 326 * Initialization vector. 327 * 328 * @param[in] iv_len 329 * The length of the IV in Bytes: 7, 8, 9, 10, 11, 12, or 13. 330 * 331 * @param[in] add 332 * The additional data field. 333 * 334 * @param[in] add_len 335 * The length of additional data in Bytes. 336 * 337 * @param[in] input 338 * The buffer holding the input data. 339 * 340 * @param[out] output 341 * The buffer holding the output data. Must be at least @p length Bytes wide. 342 * 343 * @param[in] tag 344 * The buffer holding the tag. 345 * 346 * @param[in] tag_len 347 * The length of the tag in Bytes. Must be 4, 6, 8, 10, 12, 14 or 16. 348 * 349 * @return 350 * Status code, @ref sl_status.h. 351 ******************************************************************************/ 352 sl_status_t sl_se_ccm_auth_decrypt(sl_se_command_context_t *cmd_ctx, 353 const sl_se_key_descriptor_t *key, 354 size_t length, 355 const unsigned char *iv, size_t iv_len, 356 const unsigned char *add, size_t add_len, 357 const unsigned char *input, 358 unsigned char *output, 359 const unsigned char *tag, size_t tag_len); 360 361 /***************************************************************************//** 362 * @brief 363 * Prepare a CCM streaming command context object. 364 * 365 * @details 366 * Prepare a CCM streaming command context object to be used in subsequent 367 * CCM streaming function calls. 368 * 369 * @param[in] ccm_ctx 370 * Pointer to a CCM streaming context object. 371 * 372 * @param[in] cmd_ctx 373 * Pointer to a SE command context object. 374 * 375 * @param[in] key 376 * Pointer to sl_se_key_descriptor_t structure. 377 * 378 * @param[in] mode 379 * The operation to perform: SL_SE_ENCRYPT or SL_SE_DECRYPT. 380 * 381 * @param[in] total_message_length 382 * The total length of the text to encrypt/decrypt 383 * 384 * @param[in] iv 385 * The initialization vector (commonly referred to as nonce for CCM). 386 * 387 * @param[in] iv_len 388 * The length of the IV. 389 * 390 * @param[in] add 391 * The buffer holding the additional data. 392 * 393 * @param[in] add_len 394 * The length of the additional data. 395 * 396 * @param[in] tag_len 397 * Encryption: The length of the tag to generate. Must be 0, 4, 6, 8, 10, 12, 14 or 16. 398 * Decryption: The length of the tag to authenticate. Must be 0, 4, 6, 8, 10, 12, 14 or 16. 399 * 400 * @return 401 * Status code, @ref sl_status.h. 402 ******************************************************************************/ 403 sl_status_t sl_se_ccm_multipart_starts(sl_se_ccm_multipart_context_t *ccm_ctx, 404 sl_se_command_context_t *cmd_ctx, 405 const sl_se_key_descriptor_t *key, 406 sl_se_cipher_operation_t mode, 407 uint32_t total_message_length, 408 const uint8_t *iv, 409 size_t iv_len, 410 const uint8_t *add, 411 size_t add_len, 412 size_t tag_len); 413 414 /***************************************************************************//** 415 * @brief 416 * This function feeds an input buffer into an ongoing CCM computation. 417 * 418 * It is called between sl_se_ccm_multipart_starts() and sl_se_ccm_multipart_finish(). 419 * Can be called repeatedly. 420 * 421 * @param[in] ccm_ctx 422 * Pointer to a CCM streaming context object. 423 * 424 * @param[in] cmd_ctx 425 * Pointer to a SE command context object. 426 * 427 * @param[in] key 428 * Pointer to sl_se_key_descriptor_t structure. 429 * 430 * @param[in] length 431 * The length of the input data. This must be a multiple of 16 except in 432 * the last call before sl_se_ccm_multipart_finish(). 433 * 434 * @param[in] input 435 * Buffer holding the input data, must be at least @p length bytes wide. 436 * 437 * @param[out] output 438 * Buffer for holding the output data, must be at least @p length bytes wide. 439 * 440 * @param[out] output_length 441 * Length of data that has been encrypted/decrypted. 442 * 443 * @return 444 * Status code, @ref sl_status.h. 445 ******************************************************************************/ 446 447 sl_status_t sl_se_ccm_multipart_update(sl_se_ccm_multipart_context_t *ccm_ctx, 448 sl_se_command_context_t *cmd_ctx, 449 const sl_se_key_descriptor_t *key, 450 size_t length, 451 const uint8_t *input, 452 uint8_t *output, 453 size_t *output_length); 454 455 /***************************************************************************//** 456 * @brief 457 * Finish a CCM streaming operation and return the resulting CCM tag. 458 * 459 * It is called after sl_se_ccm_multipart_update(). 460 * 461 * @param[in] ccm_ctx 462 * Pointer to a CCM streaming context object. 463 * 464 * @param[in] cmd_ctx 465 * Pointer to an SE command context object. 466 * 467 * @param[in] key 468 * Pointer to sl_se_key_descriptor_t structure. 469 * 470 * @param[in, out] tag 471 * Encryption: The buffer for holding the tag. 472 * Decryption: The tag to authenticate. 473 * 474 * @param[in] tag_size 475 * The size of the tag buffer. Must be equal or greater to the length of the expected tag. 476 * 477 * @param[out] output 478 * Buffer for holding the output data. 479 * 480 * @param[in] output_size 481 * Output buffer size. Must be equal or greater to the stored data from 482 * sl_se_ccm_multipart_update (maximum 16 bytes). 483 * 484 * @param[out] output_length 485 * Length of data that has been encrypted/decrypted. 486 * 487 * @return 488 * Returns SL_SE_INVALID_SIGNATURE if authentication step fails. 489 * Status code, @ref sl_status.h. 490 ******************************************************************************/ 491 sl_status_t sl_se_ccm_multipart_finish(sl_se_ccm_multipart_context_t *ccm_ctx, 492 sl_se_command_context_t *cmd_ctx, 493 const sl_se_key_descriptor_t *key, 494 uint8_t *tag, 495 uint8_t tag_size, 496 uint8_t *output, 497 uint8_t output_size, 498 uint8_t *output_length); 499 500 /***************************************************************************//** 501 * @brief 502 * This function performs GCM encryption or decryption of a buffer. 503 * 504 * @note 505 * For encryption, the output buffer can be the same as the input buffer. 506 * For decryption, the output buffer cannot be the same as input buffer. 507 * If the buffers overlap, the output buffer must trail at least 8 bytes 508 * behind the input buffer. 509 * 510 * @warning 511 * When this function performs a decryption, it outputs the authentication 512 * tag and does not verify that the data is authentic. You should use this 513 * function to perform encryption only. For decryption, use 514 * sl_se_gcm_auth_decrypt() instead. 515 * 516 * @param[in] cmd_ctx 517 * Pointer to an SE command context object. 518 * 519 * @param[in] key 520 * Pointer to sl_se_key_descriptor_t structure. 521 * 522 * @param[in] mode 523 * Crypto operation type (encryption or decryption). 524 * - SL_SE_ENCRYPT: The ciphertext is written to @p output and the 525 * authentication tag is written to @p tag. 526 * - SL_SE_DECRYPT: The plaintext is written to @p output and the 527 * authentication tag is written to @p tag. 528 * Note that this mode is not recommended, because it does 529 * not verify the authenticity of the data. For this 530 * reason, you should use sl_se_gcm_auth_decrypt() instead. 531 * 532 * @param[in] length 533 * The length of the input data, which is equal to the length of the output 534 * data. 535 * 536 * @param[in] iv 537 * The initialization vector. 538 * 539 * @param[in] iv_len 540 * The length of the iv. Must be @b 12 bytes. 541 * 542 * @param[in] add 543 * The buffer holding the additional data. 544 * 545 * @param[in] add_len 546 * The length of the additional data in bytes. 547 * 548 * @param[in] input 549 * The buffer holding the input data. Its size is @b length bytes. 550 * 551 * @param[out] output 552 * The buffer for holding the output data. It must have room for @b length 553 * bytes. 554 * 555 * @param[in] tag_len 556 * The length of the tag to generate (in bytes). 557 * 558 * @param[out] tag 559 * The buffer for holding the tag. 560 * 561 * @return 562 * SL_STATUS_OK when the command was executed successfully, otherwise an 563 * appropriate error code (@ref sl_status.h). 564 ******************************************************************************/ 565 sl_status_t sl_se_gcm_crypt_and_tag(sl_se_command_context_t *cmd_ctx, 566 const sl_se_key_descriptor_t *key, 567 sl_se_cipher_operation_t mode, 568 size_t length, 569 const unsigned char *iv, 570 size_t iv_len, 571 const unsigned char *add, 572 size_t add_len, 573 const unsigned char *input, 574 unsigned char *output, 575 size_t tag_len, 576 unsigned char *tag); 577 578 /***************************************************************************//** 579 * @brief 580 * This function performs a GCM authenticated decryption of a buffer. 581 * 582 * @note 583 * The output buffer cannot be the same as input buffer. If the buffers 584 * overlap, the output buffer must trail at least 8 bytes behind the input 585 * buffer. 586 * 587 * @param[in] cmd_ctx 588 * Pointer to an SE command context object. 589 * 590 * @param[in] key 591 * Pointer to sl_se_key_descriptor_t structure. 592 * 593 * @param[in] length 594 * The length of the ciphertext to decrypt, which is also the length of the 595 * decrypted plaintext. 596 * 597 * @param[in] iv 598 * The initialization vector. 599 * 600 * @param[in] iv_len 601 * The length of the iv. Must be @b 12 bytes. 602 * 603 * @param[in] add 604 * The buffer holding the additional data. 605 * 606 * @param[in] add_len 607 * The length of the additional data in bytes. 608 * 609 * @param[in] tag 610 * The buffer holding the tag to verify. 611 * 612 * @param[in] tag_len 613 * The length of the tag to verify (in bytes). 614 * 615 * @param[in] input 616 * The buffer holding the ciphertext. Its size is @b length bytes. 617 * 618 * @param[out] output 619 * The buffer for holding the decrypted plaintext. It must have room for 620 * @b length bytes. 621 * 622 * @return 623 * SL_STATUS_OK when the command was executed successfully, otherwise an 624 * appropriate error code (@ref sl_status.h). 625 ******************************************************************************/ 626 sl_status_t sl_se_gcm_auth_decrypt(sl_se_command_context_t *cmd_ctx, 627 const sl_se_key_descriptor_t *key, 628 size_t length, 629 const unsigned char *iv, 630 size_t iv_len, 631 const unsigned char *add, 632 size_t add_len, 633 const unsigned char *input, 634 unsigned char *output, 635 size_t tag_len, 636 const unsigned char *tag); 637 638 /***************************************************************************//** 639 * @brief 640 * This function calculates the full generic CMAC on the input buffer with 641 * the provided key. 642 * 643 * @param[in] cmd_ctx 644 * Pointer to an SE command context object. 645 * 646 * @param[in] key 647 * Pointer to sl_se_key_descriptor_t structure. 648 * 649 * @param[in] input 650 * Buffer holding the input data, must be at least @p input_len bytes wide. 651 * 652 * @param[in] input_len 653 * The length of the input data in bytes. 654 * 655 * @param[out] output 656 * Buffer holding the 16-byte output data, must be at least 16 bytes wide. 657 * 658 * @return 659 * Status code, @ref sl_status.h. 660 ******************************************************************************/ 661 sl_status_t sl_se_cmac(sl_se_command_context_t *cmd_ctx, 662 const sl_se_key_descriptor_t *key, 663 const unsigned char *input, 664 size_t input_len, 665 unsigned char *output); 666 667 /***************************************************************************//** 668 * @brief 669 * Prepare a CMAC streaming command context object. 670 * 671 * @details 672 * Prepare a CMAC streaming command context object to be used in subsequent 673 * CMAC streaming function calls. 674 * 675 * @param[in] cmac_ctx 676 * Pointer to a CMAC streaming context object. 677 * 678 * @param[in] cmd_ctx 679 * Pointer to an SE command context object. 680 * 681 * @param[in] key 682 * Pointer to sl_se_key_descriptor_t structure. 683 * 684 * @return 685 * Status code, @ref sl_status.h. 686 ******************************************************************************/ 687 sl_status_t sl_se_cmac_multipart_starts(sl_se_cmac_multipart_context_t *cmac_ctx, 688 sl_se_command_context_t *cmd_ctx, 689 const sl_se_key_descriptor_t *key); 690 691 /***************************************************************************//** 692 * @brief 693 * This function feeds an input buffer into an ongoing CMAC computation. 694 * 695 * @details 696 * It is called between sl_se_cmac_multipart_starts() and sl_se_cmac_multipart_finish(). 697 * Can be called repeatedly. 698 * 699 * @param[in,out] cmac_ctx 700 * Pointer to a CMAC streaming context object. 701 * 702 * @param[in] cmd_ctx 703 * Pointer to an SE command context object. 704 * 705 * @param[in] key 706 * Pointer to sl_se_key_descriptor_t structure. 707 * 708 * @param[in] input 709 * Buffer holding the input data, must be at least @p input_len bytes wide. 710 * 711 * @param[in] input_len 712 * The length of the input data in bytes. 713 * 714 * @return 715 * Status code, @ref sl_status.h. 716 ******************************************************************************/ 717 sl_status_t sl_se_cmac_multipart_update(sl_se_cmac_multipart_context_t *cmac_ctx, 718 sl_se_command_context_t *cmd_ctx, 719 const sl_se_key_descriptor_t *key, 720 const uint8_t *input, 721 size_t input_len); 722 723 /***************************************************************************//** 724 * @brief 725 * Finish a CMAC streaming operation and return the resulting CMAC tag. 726 * 727 * @details 728 * It is called after sl_se_cmac_multipart_update(). 729 * 730 * @param[in,out] cmac_ctx 731 * Pointer to a CMAC streaming context object. 732 * 733 * @param[in] cmd_ctx 734 * Pointer to an SE command context object. 735 * 736 * @param[in] key 737 * Pointer to sl_se_key_descriptor_t structure. 738 * 739 * @param[out] output 740 * Buffer holding the 16-byte CMAC tag, must be at least 16 bytes wide. 741 * 742 * @return 743 * Status code, @ref sl_status.h. 744 ******************************************************************************/ 745 sl_status_t sl_se_cmac_multipart_finish(sl_se_cmac_multipart_context_t *cmac_ctx, 746 sl_se_command_context_t *cmd_ctx, 747 const sl_se_key_descriptor_t *key, 748 uint8_t *output); 749 750 /***************************************************************************//** 751 * @brief 752 * Prepare a GCM streaming command context object. 753 * 754 * @details 755 * Prepare a GCM streaming command context object to be used in subsequent 756 * GCM streaming function calls. 757 * 758 * @param[in, out] gcm_ctx 759 * Pointer to a GCM streaming context object. 760 * 761 * @param[in] cmd_ctx 762 * Pointer to an SE command context object. 763 * 764 * @param[in] key 765 * Pointer to @c sl_se_key_descriptor_t structure specifying the key to use in 766 * the GCM computation. 767 * 768 * @param[in] mode 769 * The operation to perform: SL_SE_ENCRYPT or SL_SE_DECRYPT. 770 * 771 * @param[in] iv 772 * The initialization vector. 773 * 774 * @param[in] iv_len 775 * The length of the IV. 776 * 777 * @param[in] add 778 * The buffer holding the additional data, or NULL if @p add_len is 0. 779 * 780 * @param[in] add_len 781 * The length of the additional data. If 0, @p add is NULL. 782 * 783 * @return 784 * Status code, @ref sl_status.h. 785 ******************************************************************************/ 786 sl_status_t sl_se_gcm_multipart_starts(sl_se_gcm_multipart_context_t *gcm_ctx, 787 sl_se_command_context_t *cmd_ctx, 788 const sl_se_key_descriptor_t *key, 789 sl_se_cipher_operation_t mode, 790 const uint8_t *iv, 791 size_t iv_len, 792 const uint8_t *add, 793 size_t add_len); 794 795 /***************************************************************************//** 796 * @brief 797 * This function feeds an input buffer into an ongoing GCM computation. 798 * 799 * It is called between sl_se_gcm_multipart_starts() and sl_se_gcm_multiapart_finish(). 800 * Can be called repeatedly. 801 * 802 * @param[in, out] gcm_ctx 803 * Pointer to a GCM streaming context object. 804 * 805 * @param[in] cmd_ctx 806 * Pointer to an SE command context object. 807 * 808 * @param[in] key 809 * Pointer to @c sl_se_key_descriptor_t structure specifying the key to used in 810 * the GCM computation. 811 * 812 * @param[in] length 813 * The length of the input data. 814 * 815 * @param[in] input 816 * Buffer holding the input data, must be at least @p length bytes wide. 817 * 818 * @param[out] output 819 * Buffer for holding the output data, must be at least @p length bytes wide. 820 * 821 * @param[out] output_length 822 * Length of data that has been encrypted/decrypted. 823 * 824 * @return 825 * Status code, @ref sl_status.h. 826 ******************************************************************************/ 827 sl_status_t sl_se_gcm_multipart_update(sl_se_gcm_multipart_context_t *gcm_ctx, 828 sl_se_command_context_t *cmd_ctx, 829 const sl_se_key_descriptor_t *key, 830 size_t length, 831 const uint8_t *input, 832 uint8_t *output, 833 size_t *output_length); 834 835 /***************************************************************************//** 836 * @brief 837 * Finish a GCM streaming operation and return the resulting GCM tag. 838 * 839 * It is called after sl_se_gcm_multipart_update(). 840 * 841 * @param[in, out] gcm_ctx 842 * Pointer to a GCM streaming context object. 843 * 844 * @param[in] cmd_ctx 845 * Pointer to an SE command context object. 846 * 847 * @param[in] key 848 * Pointer to @c sl_se_key_descriptor_t structure specifying the key to use in 849 * the GCM computation. 850 * 851 * @param[in, out] tag 852 * Encryption: The buffer for holding the tag. 853 * Decryption: The tag to authenticate. 854 * 855 * @param[in] tag_length 856 * Encryption: Length of the output tag. 857 * Decryption: Length of tag to verify 858 * 859 * @param[out] output 860 * Buffer for holding the output data. 861 * 862 * @param[in] output_size 863 * Output buffer size. Must be equal or greater to the stored data from 864 * sl_se_gcm_multipart_update (stored data is maximum 16 bytes). 865 * 866 * @param[out] output_length 867 * Length of data that has been encrypted/decrypted. 868 * 869 * @return 870 * Returns SL_SE_INVALID_SIGNATURE if authentication step fails. 871 * Status code, @ref sl_status.h. 872 ******************************************************************************/ 873 sl_status_t sl_se_gcm_multipart_finish(sl_se_gcm_multipart_context_t *gcm_ctx, 874 sl_se_command_context_t *cmd_ctx, 875 const sl_se_key_descriptor_t *key, 876 uint8_t *tag, 877 uint8_t tag_length, 878 uint8_t *output, 879 uint8_t output_size, 880 uint8_t *output_length); 881 882 /***************************************************************************//** 883 * @brief 884 * Compute a HMAC on a full message. 885 * 886 * @details 887 * This function computes a Keyed-Hashed Message Authentication Code (HMAC) 888 * for the given input message. HMAC can be used with any iterative 889 * cryptographic hash function, e.g., SHA-1 in combination with a 890 * secret shared key. The cryptographic strength of HMAC depends on the 891 * properties of the underlying hash function. For instance, if the algorithm 892 * is chosen to be SHA-256, it will generate a 32 bytes HMAC. 893 * This function supports SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512. 894 * The key can be of any length. If the key is shorter than the block size 895 * of the hash function the SE will append zeros to the key so the key size 896 * matches the block size of the hash function. If the key is longer than the 897 * block size of the hash function the key will be hashed to 898 * produce a key digest, then append zeros so the resulting 'hashed' key size 899 * matches the block size of the hash function. In any case the minimal 900 * recommended key length is the digest size of the hash function. 901 * 902 * @param[in] cmd_ctx 903 * Pointer to an SE command context object. 904 * 905 * @param[in] key 906 * Pointer to sl_se_key_descriptor_t structure specifying the key to use in 907 * the HMAC computation. 908 * 909 * @param[in] hash_type 910 * Which hashing algorithm to use. 911 * 912 * @param[in] message 913 * Pointer to the message buffer to compute the hash/digest from. 914 * 915 * @param[in] message_len 916 * Number of bytes in message. 917 * 918 * @param[out] output 919 * Pointer to memory buffer to store the final HMAC output. 920 * 921 * @param[in] output_len 922 * The length of the HMAC output memory buffer, must be at least the size 923 * of the corresponding hash type. 924 * 925 * @return Status code, @ref sl_status.h. 926 ******************************************************************************/ 927 sl_status_t sl_se_hmac(sl_se_command_context_t *cmd_ctx, 928 const sl_se_key_descriptor_t *key, 929 sl_se_hash_type_t hash_type, 930 const uint8_t *message, 931 size_t message_len, 932 uint8_t *output, 933 size_t output_len); 934 935 #if (_SILICON_LABS_SECURITY_FEATURE == _SILICON_LABS_SECURITY_FEATURE_VAULT) 936 /***************************************************************************//** 937 * @brief 938 * ChaCha20 buffer encryption/decryption, as defined by RFC8439 section 2.4. 939 * 940 * @param[in] cmd_ctx 941 * Pointer to an SE command context object. 942 * 943 * @param[in] mode 944 * Crypto operation type (encryption or decryption). 945 * 946 * @param[in] key 947 * Pointer to sl_se_key_descriptor_t structure. 948 * 949 * @param[in] length 950 * Length of the input data. 951 * 952 * @param[in] initial_counter 953 * The initial counter value as defined in RFC8439 section 2.4. 954 * 955 * @param[in] nonce 956 * The nonce, also called initialisation vector, as defined in RFC8439 section 957 * 2.4. 958 * 959 * @param[in] input 960 * Buffer holding the input data. 961 * 962 * @param[out] output 963 * Buffer holding the output data. 964 * 965 * @return 966 * Status code, @ref sl_status.h. 967 ******************************************************************************/ 968 sl_status_t sl_se_chacha20_crypt(sl_se_command_context_t *cmd_ctx, 969 sl_se_cipher_operation_t mode, 970 const sl_se_key_descriptor_t *key, 971 size_t length, 972 const unsigned char initial_counter[4], 973 const unsigned char nonce[12], 974 const unsigned char *input, 975 unsigned char *output); 976 977 /***************************************************************************//** 978 * @brief 979 * ChaCha20-Poly1305 authenticated encryption with additional data, as defined 980 * by RFC8439 section 2.8. 981 * 982 * @param[in] cmd_ctx 983 * Pointer to an SE command context object. 984 * 985 * @param[in] key 986 * Pointer to sl_se_key_descriptor_t structure. 987 * 988 * @param[in] length 989 * The length of the input data in bytes. 990 * 991 * @param[in] nonce 992 * The nonce, also called initialisation vector, as defined in RFC8439 section 993 * 2.8. 994 * 995 * @param[in] add 996 * The buffer holding additional authenticated data. Can be NULL if @p add_len 997 * equals 0. 998 * 999 * @param[in] add_len 1000 * The length of the additional authenticated data in bytes. 1001 * 1002 * @param[in] input 1003 * The buffer holding the plaintext input. 1004 * 1005 * @param[out] output 1006 * The buffer holding the ciphertext output. Can be NULL, in which case the 1007 * generated ciphertext will be discarded. Must be at least @p length bytes 1008 * wide. 1009 * 1010 * @param[out] tag 1011 * The buffer holding the tag. This function will produce a 128-bit tag, so 1012 * this buffer must be at least 16 bytes wide. Can be NULL, in which case the 1013 * generated tag will be discarded. 1014 * 1015 * @return 1016 * Status code, @ref sl_status.h. 1017 ******************************************************************************/ 1018 sl_status_t sl_se_chacha20_poly1305_encrypt_and_tag(sl_se_command_context_t *cmd_ctx, 1019 const sl_se_key_descriptor_t *key, 1020 size_t length, 1021 const unsigned char nonce[12], 1022 const unsigned char *add, size_t add_len, 1023 const unsigned char *input, 1024 unsigned char *output, 1025 unsigned char *tag); 1026 1027 /***************************************************************************//** 1028 * @brief 1029 * ChaCha20-Poly1305 authenticated decryption with additional data, as defined 1030 * by RFC8439 section 2.8. 1031 * 1032 * @param[in] cmd_ctx 1033 * Pointer to an SE command context object. 1034 * 1035 * @param[in] key 1036 * Pointer to sl_se_key_descriptor_t structure. 1037 * 1038 * @param[in] length 1039 * The length of the input data in Bytes. 1040 * 1041 * @param[in] nonce 1042 * The nonce, also called initialisation vector, as defined in RFC8439 section 1043 * 2.8. 1044 * 1045 * @param[in] add 1046 * The buffer holding additional authenticated data. Can be NULL if @p add_len 1047 * equals 0. 1048 * 1049 * @param[in] add_len 1050 * The length of the additional authenticated data in bytes. 1051 * 1052 * @param[in] input 1053 * The buffer holding the ciphertext to decrypt. Can be NULL if @p length 1054 * equals 0. 1055 * 1056 * @param[out] output 1057 * The buffer holding the plaintext output. Can be NULL, in which case the 1058 * decrypted plaintext will be discarded, or when @p length equals 0. Must be 1059 * at least @p length bytes wide. 1060 * 1061 * @param[in] tag 1062 * The buffer holding the tag to verify. 1063 * 1064 * @return 1065 * Status code, @ref sl_status.h. 1066 ******************************************************************************/ 1067 sl_status_t sl_se_chacha20_poly1305_auth_decrypt(sl_se_command_context_t *cmd_ctx, 1068 const sl_se_key_descriptor_t *key, 1069 size_t length, 1070 const unsigned char nonce[12], 1071 const unsigned char *add, size_t add_len, 1072 const unsigned char *input, 1073 unsigned char *output, 1074 const unsigned char tag[16]); 1075 1076 /***************************************************************************//** 1077 * @brief 1078 * Generate a Poly1305 MAC (message authentication code) for a given message 1079 * using an ephemeral key derived using ChaCha20. 1080 * 1081 * @note 1082 * This function first derives a Poly1305 key based on a ChaCha20 key and 1083 * nonce, which are input to this function. The key derivation adheres to 1084 * RFC8439 section 2.6. The derived key is then used to calculate a MAC of the 1085 * input data, according to RFC8439 section 2.5. 1086 * 1087 * @param[in] cmd_ctx 1088 * Pointer to an SE command context object. 1089 * 1090 * @param[in] key 1091 * Pointer to sl_se_key_descriptor_t structure containing a ChaCha20 key. 1092 * 1093 * @param[in] length 1094 * The length of the input data in Bytes. 1095 * 1096 * @param[in] nonce 1097 * The nonce, also called initialisation vector, as defined in RFC8439 section 1098 * 2.6. 1099 * 1100 * @param[in] input 1101 * The buffer holding the input data. 1102 * 1103 * @param[out] tag 1104 * The buffer holding the tag. This function will produce a 128-bit tag, so 1105 * this buffer must be at least 16 bytes wide. 1106 * 1107 * @return 1108 * Status code, @ref sl_status.h. 1109 ******************************************************************************/ 1110 sl_status_t sl_se_poly1305_genkey_tag(sl_se_command_context_t *cmd_ctx, 1111 const sl_se_key_descriptor_t *key, 1112 size_t length, 1113 const unsigned char nonce[12], 1114 const unsigned char *input, 1115 unsigned char *tag); 1116 1117 #endif // (_SILICON_LABS_SECURITY_FEATURE == _SILICON_LABS_SECURITY_FEATURE_VAULT) 1118 1119 #if defined(_SILICON_LABS_32B_SERIES_3) 1120 1121 /***************************************************************************//** 1122 * @brief 1123 * Prepare a HMAC streaming command context object to be used in subsequent 1124 * HMAC streaming function calls. 1125 * 1126 * @param[in] cmd_ctx 1127 * Pointer to a SE command context object. 1128 * 1129 * @param[in] key 1130 * Pointer to sl_se_key_descriptor_t structure specifying the key to use in 1131 * the HMAC computation. 1132 * 1133 * @param[in] hash_type 1134 * Which hashing algorithm to use. 1135 * 1136 * @param[in] message 1137 * Pointer to the message buffer to compute the hash/digest from. 1138 * 1139 * @param[in] message_len 1140 * Number of bytes in message. 1141 * 1142 * @param[out] state_out 1143 * Pointer to memory buffer to store the final HMAC output. 1144 * 1145 * @param[in] state_out_len 1146 * The length of the HMAC output memory buffer, must be at least the size 1147 * of the corresponding hash type + 8 bytes. 1148 * 1149 * @return 1150 * Status code, @ref sl_status.h. 1151 ******************************************************************************/ 1152 sl_status_t sl_se_hmac_multipart_starts(sl_se_command_context_t *cmd_ctx, 1153 const sl_se_key_descriptor_t *key, 1154 sl_se_hash_type_t hash_type, 1155 const uint8_t *message, 1156 size_t message_len, 1157 uint8_t *state_out, 1158 size_t state_out_len); 1159 1160 /***************************************************************************//** 1161 * @brief 1162 * This function feeds an input buffer into an ongoing HMAC computation. 1163 * 1164 * @param[in] cmd_ctx 1165 * Pointer to a SE command context object. 1166 * 1167 * @param[in] hash_type 1168 * Which hashing algorithm to use. 1169 * 1170 * @param[in] message 1171 * Pointer to the message buffer to compute the hash/digest from. 1172 * 1173 * @param[in] message_len 1174 * Number of bytes in message. 1175 * 1176 * @param[in,out] state_in_out 1177 * Pointer to memory buffer to store the HMAC state. 1178 * 1179 * @param[in] state_in_out_len 1180 * The length of the HMAC state buffer, must be at least the size 1181 * of the corresponding hash type + 8 bytes. 1182 * 1183 * @return 1184 * Status code, @ref sl_status.h. 1185 ******************************************************************************/ 1186 sl_status_t sl_se_hmac_multipart_update(sl_se_command_context_t *cmd_ctx, 1187 sl_se_hash_type_t hash_type, 1188 const uint8_t *message, 1189 size_t message_len, 1190 uint8_t *state_in_out, 1191 size_t state_in_out_len); 1192 1193 /***************************************************************************//** 1194 * @brief 1195 * Finish a HMAC streaming operation and return the resulting HMAC. 1196 * 1197 * @param[in] cmd_ctx 1198 * Pointer to a SE command context object. 1199 * 1200 * @param[in] key 1201 * Pointer to sl_se_key_descriptor_t structure specifying the key to use in 1202 * the HMAC computation. 1203 * 1204 * @param[in] hash_type 1205 * Which hashing algorithm to use. 1206 * 1207 * @param[in] message 1208 * Pointer to the message buffer to compute the hash/digest from. 1209 * 1210 * @param[in] message_len 1211 * Number of bytes in message. 1212 * 1213 * @param[in] state_in 1214 * Pointer to memory buffer containing the HMAC state. 1215 * 1216 * @param[in] state_in_out_len 1217 * The length of the HMAC state buffer, must be at least the size 1218 * of the corresponding hash type + 8 bytes. 1219 * 1220 * @param[out] output 1221 * Pointer to memory buffer to store the final HMAC output. 1222 * 1223 * @param[in] output_len 1224 * The length of the HMAC output memory buffer, must be at least the size 1225 * of the corresponding hash type. 1226 * 1227 * @return 1228 * Status code, @ref sl_status.h. 1229 ******************************************************************************/ 1230 sl_status_t sl_se_hmac_multipart_finish(sl_se_command_context_t *cmd_ctx, 1231 const sl_se_key_descriptor_t *key, 1232 sl_se_hash_type_t hash_type, 1233 const uint8_t *message, 1234 size_t message_len, 1235 uint8_t *state_in, 1236 size_t state_in_len, 1237 uint8_t *output, 1238 size_t output_len); 1239 1240 #endif // defined(_SILICON_LABS_32B_SERIES_3) 1241 1242 #ifdef __cplusplus 1243 } 1244 #endif 1245 1246 /// @} (end addtogroup sl_se_manager_cipher) 1247 /// @} (end addtogroup sl_se_manager) 1248 1249 #endif // defined(SLI_MAILBOX_COMMAND_SUPPORTED) 1250 1251 #endif // SL_SE_MANAGER_CIPHER_H 1252
