1 /****************************************************************************** 2 * Filename: pka.h 3 * 4 * Description: PKA header file. 5 * 6 * Copyright (c) 2015 - 2022, Texas Instruments Incorporated 7 * All rights reserved. 8 * 9 * Redistribution and use in source and binary forms, with or without 10 * modification, are permitted provided that the following conditions are met: 11 * 12 * 1) Redistributions of source code must retain the above copyright notice, 13 * this list of conditions and the following disclaimer. 14 * 15 * 2) Redistributions in binary form must reproduce the above copyright notice, 16 * this list of conditions and the following disclaimer in the documentation 17 * and/or other materials provided with the distribution. 18 * 19 * 3) Neither the name of the ORGANIZATION nor the names of its contributors may 20 * be used to endorse or promote products derived from this software without 21 * specific prior written permission. 22 * 23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 24 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 27 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 28 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 29 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 30 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 31 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 32 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 33 * POSSIBILITY OF SUCH DAMAGE. 34 * 35 ******************************************************************************/ 36 37 //***************************************************************************** 38 // 39 //! \addtogroup peripheral_group 40 //! @{ 41 //! \addtogroup pka_api 42 //! @{ 43 // 44 //***************************************************************************** 45 46 #ifndef __PKA_H__ 47 #define __PKA_H__ 48 49 //***************************************************************************** 50 // 51 // If building with a C++ compiler, make all of the definitions in this header 52 // have a C binding. 53 // 54 //***************************************************************************** 55 #ifdef __cplusplus 56 extern "C" 57 { 58 #endif 59 60 #include "../inc/hw_types.h" 61 #include "../inc/hw_memmap.h" 62 #include "../inc/hw_ints.h" 63 #include "../inc/hw_pka.h" 64 #include "../inc/hw_pka_ram.h" 65 #include "interrupt.h" 66 #include "sys_ctrl.h" 67 #include "debug.h" 68 #include <string.h> 69 70 //***************************************************************************** 71 // 72 // Support for DriverLib in ROM: 73 // This section renames all functions that are not "static inline", so that 74 // calling these functions will default to implementation in flash. At the end 75 // of this file a second renaming will change the defaults to implementation in 76 // ROM for available functions. 77 // 78 // To force use of the implementation in flash, e.g. for debugging: 79 // - Globally: Define DRIVERLIB_NOROM at project level 80 // - Per function: Use prefix "NOROM_" when calling the function 81 // 82 //***************************************************************************** 83 #if !defined(DOXYGEN) 84 #define PKAClearPkaRam NOROM_PKAClearPkaRam 85 #define PKAGetOpsStatus NOROM_PKAGetOpsStatus 86 #define PKAArrayAllZeros NOROM_PKAArrayAllZeros 87 #define PKAZeroOutArray NOROM_PKAZeroOutArray 88 #define PKABigNumModStart NOROM_PKABigNumModStart 89 #define PKABigNumModGetResult NOROM_PKABigNumModGetResult 90 #define PKABigNumDivideStart NOROM_PKABigNumDivideStart 91 #define PKABigNumDivideGetQuotient NOROM_PKABigNumDivideGetQuotient 92 #define PKABigNumDivideGetRemainder NOROM_PKABigNumDivideGetRemainder 93 #define PKABigNumCmpStart NOROM_PKABigNumCmpStart 94 #define PKABigNumCmpGetResult NOROM_PKABigNumCmpGetResult 95 #define PKABigNumInvModStart NOROM_PKABigNumInvModStart 96 #define PKABigNumInvModGetResult NOROM_PKABigNumInvModGetResult 97 #define PKABigNumExpModStart NOROM_PKABigNumExpModStart 98 #define PKABigNumExpModGetResult NOROM_PKABigNumExpModGetResult 99 #define PKABigNumMultiplyStart NOROM_PKABigNumMultiplyStart 100 #define PKABigNumMultGetResult NOROM_PKABigNumMultGetResult 101 #define PKABigNumAddStart NOROM_PKABigNumAddStart 102 #define PKABigNumAddGetResult NOROM_PKABigNumAddGetResult 103 #define PKABigNumSubStart NOROM_PKABigNumSubStart 104 #define PKABigNumSubGetResult NOROM_PKABigNumSubGetResult 105 #define PKAEccMultiplyStart NOROM_PKAEccMultiplyStart 106 #define PKAEccMontgomeryMultiplyStart NOROM_PKAEccMontgomeryMultiplyStart 107 #define PKAEccMultiplyGetResult NOROM_PKAEccMultiplyGetResult 108 #define PKAEccAddStart NOROM_PKAEccAddStart 109 #define PKAEccAddGetResult NOROM_PKAEccAddGetResult 110 #define PKAEccVerifyPublicKeyWeierstrassStart NOROM_PKAEccVerifyPublicKeyWeierstrassStart 111 #endif 112 113 114 115 116 //***************************************************************************** 117 // 118 // Function return values 119 // 120 //***************************************************************************** 121 #define PKA_STATUS_SUCCESS 0 //!< Success 122 #define PKA_STATUS_FAILURE 1 //!< Failure 123 #define PKA_STATUS_INVALID_PARAM 2 //!< Invalid parameter 124 #define PKA_STATUS_BUF_UNDERFLOW 3 //!< Buffer underflow 125 #define PKA_STATUS_RESULT_0 4 //!< Result is all zeros 126 #define PKA_STATUS_A_GREATER_THAN_B 5 //!< Big number compare return status if the first big number is greater than the second. 127 #define PKA_STATUS_A_LESS_THAN_B 6 //!< Big number compare return status if the first big number is less than the second. 128 #define PKA_STATUS_EQUAL 7 //!< Big number compare return status if the first big number is equal to the second. 129 #define PKA_STATUS_OPERATION_BUSY 8 //!< PKA operation is in progress. 130 #define PKA_STATUS_OPERATION_RDY 9 //!< No PKA operation is in progress. 131 #define PKA_STATUS_LOCATION_IN_USE 10 //!< Location in PKA RAM is not available 132 #define PKA_STATUS_X_ZERO 11 //!< X coordinate of public key is 0 133 #define PKA_STATUS_Y_ZERO 12 //!< Y coordinate of public key is 0 134 #define PKA_STATUS_X_LARGER_THAN_PRIME 13 //!< X coordinate of public key is larger than the curve prime 135 #define PKA_STATUS_Y_LARGER_THAN_PRIME 14 //!< Y coordinate of public key is larger than the curve prime 136 #define PKA_STATUS_POINT_NOT_ON_CURVE 15 //!< The public key is not on the specified elliptic curve 137 #define PKA_STATUS_RESULT_ADDRESS_INCORRECT 16 //!< The address of the result passed into one of the PKA*GetResult functions is incorrect 138 #define PKA_STATUS_POINT_AT_INFINITY 17 //!< The ECC operation resulted in the point at infinity 139 140 141 //***************************************************************************** 142 // 143 // Length in bytes of NISTP224 parameters. 144 // 145 //***************************************************************************** 146 #define NISTP224_PARAM_SIZE_BYTES 28 147 148 //***************************************************************************** 149 // 150 // Length in bytes of NISTP256 parameters. 151 // 152 //***************************************************************************** 153 #define NISTP256_PARAM_SIZE_BYTES 32 154 155 //***************************************************************************** 156 // 157 // Length in bytes of NISTP384 parameters. 158 // 159 //***************************************************************************** 160 #define NISTP384_PARAM_SIZE_BYTES 48 161 162 //***************************************************************************** 163 // 164 // Length in bytes of NISTP521 parameters. 165 // 166 //***************************************************************************** 167 #define NISTP521_PARAM_SIZE_BYTES 66 168 169 //***************************************************************************** 170 // 171 // Length in bytes of BrainpoolP256R1 parameters. 172 // 173 //***************************************************************************** 174 #define BrainpoolP256R1_PARAM_SIZE_BYTES 32 175 176 //***************************************************************************** 177 // 178 // Length in bytes of BrainpoolP384R1 parameters. 179 // 180 //***************************************************************************** 181 #define BrainpoolP384R1_PARAM_SIZE_BYTES 48 182 183 //***************************************************************************** 184 // 185 // Length in bytes of BrainpoolP512R1 parameters. 186 // 187 //***************************************************************************** 188 #define BrainpoolP512R1_PARAM_SIZE_BYTES 64 189 190 //***************************************************************************** 191 // 192 // Length in bytes of Curve25519 parameters. 193 // 194 //***************************************************************************** 195 #define Curve25519_PARAM_SIZE_BYTES 32 196 197 //***************************************************************************** 198 // 199 // Union for parameters that forces 32-bit alignment on the byte array. 200 // 201 //***************************************************************************** 202 typedef union { 203 uint8_t byte[28]; 204 uint32_t word[28 / sizeof(uint32_t)]; 205 } PKA_EccParam224; 206 207 typedef union { 208 uint8_t byte[32]; 209 uint32_t word[32 / sizeof(uint32_t)]; 210 } PKA_EccParam256; 211 212 typedef union { 213 uint8_t byte[48]; 214 uint32_t word[48 / sizeof(uint32_t)]; 215 } PKA_EccParam384; 216 217 typedef union { 218 uint8_t byte[64]; 219 uint32_t word[64 / sizeof(uint32_t)]; 220 } PKA_EccParam512; 221 222 typedef union { 223 uint8_t byte[68]; 224 uint32_t word[68 / sizeof(uint32_t)]; 225 } PKA_EccParam521; 226 227 //***************************************************************************** 228 // 229 // Struct to keep points in that forces adjacency of X and Y coordinates in 230 // memmory. 231 // 232 //***************************************************************************** 233 234 235 typedef struct PKA_EccPoint224_ { 236 PKA_EccParam224 x; 237 PKA_EccParam224 y; 238 } PKA_EccPoint224; 239 240 typedef struct PKA_EccPoint256_ { 241 PKA_EccParam256 x; 242 PKA_EccParam256 y; 243 } PKA_EccPoint256; 244 245 typedef struct PKA_EccPoint384_ { 246 PKA_EccParam384 x; 247 PKA_EccParam384 y; 248 } PKA_EccPoint384; 249 250 typedef struct PKA_EccPoint512_ { 251 PKA_EccParam512 x; 252 PKA_EccParam512 y; 253 } PKA_EccPoint512; 254 255 typedef struct PKA_EccPoint521_ { 256 PKA_EccParam521 x; 257 PKA_EccParam521 y; 258 } PKA_EccPoint521; 259 260 261 //***************************************************************************** 262 // 263 //! \brief X coordinate of the generator point of the NISTP224 curve. 264 // 265 //***************************************************************************** 266 extern const PKA_EccPoint224 NISTP224_generator; 267 268 //***************************************************************************** 269 // 270 //! \brief Prime of the NISTP224 curve. 271 // 272 //***************************************************************************** 273 extern const PKA_EccParam224 NISTP224_prime; 274 275 276 //***************************************************************************** 277 // 278 //! \brief a constant of the NISTP224 curve when expressed in short 279 //! Weierstrass form (y^3 = x^2 + a*x + b). 280 // 281 //***************************************************************************** 282 extern const PKA_EccParam224 NISTP224_a; 283 284 285 //***************************************************************************** 286 // 287 //! \brief b constant of the NISTP224 curve when expressed in short 288 //! Weierstrass form (y^3 = x^2 + a*x + b). 289 // 290 //***************************************************************************** 291 extern const PKA_EccParam224 NISTP224_b; 292 293 294 //***************************************************************************** 295 // 296 //! \brief Order of the NISTP224 curve. 297 // 298 //***************************************************************************** 299 extern const PKA_EccParam224 NISTP224_order; 300 301 302 303 304 //***************************************************************************** 305 // 306 //! \brief X coordinate of the generator point of the NISTP256 curve. 307 // 308 //***************************************************************************** 309 extern const PKA_EccPoint256 NISTP256_generator; 310 311 //***************************************************************************** 312 // 313 //! \brief Prime of the NISTP256 curve. 314 // 315 //***************************************************************************** 316 extern const PKA_EccParam256 NISTP256_prime; 317 318 319 //***************************************************************************** 320 // 321 //! \brief a constant of the NISTP256 curve when expressed in short 322 //! Weierstrass form (y^3 = x^2 + a*x + b). 323 // 324 //***************************************************************************** 325 extern const PKA_EccParam256 NISTP256_a; 326 327 328 //***************************************************************************** 329 // 330 //! \brief b constant of the NISTP256 curve when expressed in short 331 //! Weierstrass form (y^3 = x^2 + a*x + b). 332 // 333 //***************************************************************************** 334 extern const PKA_EccParam256 NISTP256_b; 335 336 337 //***************************************************************************** 338 // 339 //! \brief Order of the NISTP256 curve. 340 // 341 //***************************************************************************** 342 extern const PKA_EccParam256 NISTP256_order; 343 344 345 346 347 348 //***************************************************************************** 349 // 350 //! \brief X coordinate of the generator point of the NISTP384 curve. 351 // 352 //***************************************************************************** 353 extern const PKA_EccPoint384 NISTP384_generator; 354 355 //***************************************************************************** 356 // 357 //! \brief Prime of the NISTP384 curve. 358 // 359 //***************************************************************************** 360 extern const PKA_EccParam384 NISTP384_prime; 361 362 363 //***************************************************************************** 364 // 365 //! \brief a constant of the NISTP384 curve when expressed in short 366 //! Weierstrass form (y^3 = x^2 + a*x + b). 367 // 368 //***************************************************************************** 369 extern const PKA_EccParam384 NISTP384_a; 370 371 372 //***************************************************************************** 373 // 374 //! \brief b constant of the NISTP384 curve when expressed in short 375 //! Weierstrass form (y^3 = x^2 + a*x + b). 376 // 377 //***************************************************************************** 378 extern const PKA_EccParam384 NISTP384_b; 379 380 381 //***************************************************************************** 382 // 383 //! \brief Order of the NISTP384 curve. 384 // 385 //***************************************************************************** 386 extern const PKA_EccParam384 NISTP384_order; 387 388 389 390 391 //***************************************************************************** 392 // 393 //! \brief X coordinate of the generator point of the NISTP521 curve. 394 // 395 //***************************************************************************** 396 extern const PKA_EccPoint521 NISTP521_generator; 397 398 //***************************************************************************** 399 // 400 //! \brief Prime of the NISTP521 curve. 401 // 402 //***************************************************************************** 403 extern const PKA_EccParam521 NISTP521_prime; 404 405 406 //***************************************************************************** 407 // 408 //! \brief a constant of the NISTP521 curve when expressed in short 409 //! Weierstrass form (y^3 = x^2 + a*x + b). 410 // 411 //***************************************************************************** 412 extern const PKA_EccParam521 NISTP521_a; 413 414 415 //***************************************************************************** 416 // 417 //! \brief b constant of the NISTP521 curve when expressed in short 418 //! Weierstrass form (y^3 = x^2 + a*x + b). 419 // 420 //***************************************************************************** 421 extern const PKA_EccParam521 NISTP521_b; 422 423 424 //***************************************************************************** 425 // 426 //! \brief Order of the NISTP521 curve. 427 // 428 //***************************************************************************** 429 extern const PKA_EccParam521 NISTP521_order; 430 431 432 433 434 //***************************************************************************** 435 // 436 //! \brief X coordinate of the generator point of the BrainpoolP256R1 curve. 437 // 438 //***************************************************************************** 439 extern const PKA_EccPoint256 BrainpoolP256R1_generator; 440 441 //***************************************************************************** 442 // 443 //! \brief Prime of the BrainpoolP256R1 curve. 444 // 445 //***************************************************************************** 446 extern const PKA_EccParam256 BrainpoolP256R1_prime; 447 448 449 //***************************************************************************** 450 // 451 //! \brief a constant of the BrainpoolP256R1 curve when expressed in short 452 //! Weierstrass form (y^3 = x^2 + a*x + b). 453 // 454 //***************************************************************************** 455 extern const PKA_EccParam256 BrainpoolP256R1_a; 456 457 458 //***************************************************************************** 459 // 460 //! \brief b constant of the BrainpoolP256R1 curve when expressed in short 461 //! Weierstrass form (y^3 = x^2 + a*x + b). 462 // 463 //***************************************************************************** 464 extern const PKA_EccParam256 BrainpoolP256R1_b; 465 466 467 //***************************************************************************** 468 // 469 //! \brief Order of the BrainpoolP256R1 curve. 470 // 471 //***************************************************************************** 472 extern const PKA_EccParam256 BrainpoolP256R1_order; 473 474 475 476 477 //***************************************************************************** 478 // 479 //! \brief X coordinate of the generator point of the BrainpoolP384R1 curve. 480 // 481 //***************************************************************************** 482 extern const PKA_EccPoint384 BrainpoolP384R1_generator; 483 484 //***************************************************************************** 485 // 486 //! \brief Prime of the BrainpoolP384R1 curve. 487 // 488 //***************************************************************************** 489 extern const PKA_EccParam384 BrainpoolP384R1_prime; 490 491 492 //***************************************************************************** 493 // 494 //! \brief a constant of the BrainpoolP384R1 curve when expressed in short 495 //! Weierstrass form (y^3 = x^2 + a*x + b). 496 // 497 //***************************************************************************** 498 extern const PKA_EccParam384 BrainpoolP384R1_a; 499 500 501 //***************************************************************************** 502 // 503 //! \brief b constant of the BrainpoolP384R1 curve when expressed in short 504 //! Weierstrass form (y^3 = x^2 + a*x + b). 505 // 506 //***************************************************************************** 507 extern const PKA_EccParam384 BrainpoolP384R1_b; 508 509 510 //***************************************************************************** 511 // 512 //! \brief Order of the BrainpoolP384R1 curve. 513 // 514 //***************************************************************************** 515 extern const PKA_EccParam384 BrainpoolP384R1_order; 516 517 518 519 //***************************************************************************** 520 // 521 //! \brief X coordinate of the generator point of the BrainpoolP512R1 curve. 522 // 523 //***************************************************************************** 524 extern const PKA_EccPoint512 BrainpoolP512R1_generator; 525 526 //***************************************************************************** 527 // 528 //! \brief Prime of the BrainpoolP512R1 curve. 529 // 530 //***************************************************************************** 531 extern const PKA_EccParam512 BrainpoolP512R1_prime; 532 533 534 //***************************************************************************** 535 // 536 //! \brief a constant of the BrainpoolP512R1 curve when expressed in short 537 //! Weierstrass form (y^3 = x^2 + a*x + b). 538 // 539 //***************************************************************************** 540 extern const PKA_EccParam512 BrainpoolP512R1_a; 541 542 543 //***************************************************************************** 544 // 545 //! \brief b constant of the BrainpoolP512R1 curve when expressed in short 546 //! Weierstrass form (y^3 = x^2 + a*x + b). 547 // 548 //***************************************************************************** 549 extern const PKA_EccParam512 BrainpoolP512R1_b; 550 551 552 //***************************************************************************** 553 // 554 //! \brief Order of the BrainpoolP512R1 curve. 555 // 556 //***************************************************************************** 557 extern const PKA_EccParam512 BrainpoolP512R1_order; 558 559 560 561 //***************************************************************************** 562 // 563 //! \brief X coordinate of the generator point of the Curve25519 curve. 564 // 565 //***************************************************************************** 566 extern const PKA_EccPoint256 Curve25519_generator; 567 568 //***************************************************************************** 569 // 570 //! \brief Prime of the Curve25519 curve. 571 // 572 //***************************************************************************** 573 extern const PKA_EccParam256 Curve25519_prime; 574 575 576 //***************************************************************************** 577 // 578 //! \brief a constant of the Curve25519 curve when expressed in Montgomery 579 //! form (By^2 = x^3 + a*x^2 + x). 580 // 581 //***************************************************************************** 582 extern const PKA_EccParam256 Curve25519_a; 583 584 585 //***************************************************************************** 586 // 587 //! \brief b constant of the Curve25519 curve when expressed in Montgomery 588 //! form (By^2 = x^3 + a*x^2 + x). 589 // 590 //***************************************************************************** 591 extern const PKA_EccParam256 Curve25519_b; 592 593 594 //***************************************************************************** 595 // 596 //! \brief Order of the Curve25519 curve. 597 // 598 //***************************************************************************** 599 extern const PKA_EccParam256 Curve25519_order; 600 601 //***************************************************************************** 602 // 603 // Prototypes for the APIs. 604 // 605 //***************************************************************************** 606 607 //***************************************************************************** 608 // 609 //! \brief Zeroizes PKA RAM. 610 //! 611 //! This function uses the zeroization function in PRCM to clear the PKA RAM. 612 // 613 //***************************************************************************** 614 extern void PKAClearPkaRam(void); 615 616 //***************************************************************************** 617 // 618 //! \brief Gets the PKA operation status. 619 //! 620 //! This function gets information on whether any PKA operation is in 621 //! progress or not. This function allows to check the PKA operation status 622 //! before starting any new PKA operation. 623 //! 624 //! \return Returns a status code. 625 //! - \ref PKA_STATUS_OPERATION_BUSY if the PKA operation is in progress. 626 //! - \ref PKA_STATUS_OPERATION_RDY if the PKA operation is not in progress. 627 // 628 //***************************************************************************** 629 extern uint32_t PKAGetOpsStatus(void); 630 631 //***************************************************************************** 632 // 633 //! \brief Checks whether and array only consists of zeros 634 //! 635 //! \param [in] array is the array to check. 636 //! 637 //! \param [in] arrayLength is the length of the array. 638 //! 639 //! \return Returns true if the array contains only zeros and false if one 640 //! or more bits are set. 641 // 642 //***************************************************************************** 643 extern bool PKAArrayAllZeros(const uint8_t *array, uint32_t arrayLength); 644 645 //***************************************************************************** 646 // 647 //! \brief Zeros-out an array 648 //! 649 //! \param [in] array is the array to zero-out. 650 //! 651 //! \param [in] arrayLength is the length of the array. 652 // 653 //***************************************************************************** 654 extern void PKAZeroOutArray(const uint8_t *array, uint32_t arrayLength); 655 656 //***************************************************************************** 657 // 658 //! \brief Starts a big number modulus operation. 659 //! 660 //! This function starts the modulo operation on the big number \c bigNum 661 //! using the divisor \c modulus. The PKA RAM location where the result 662 //! will be available is stored in \c resultPKAMemAddr. 663 //! 664 //! \param [in] bigNum is the pointer to the big number on which modulo operation 665 //! needs to be carried out. 666 //! 667 //! \param [in] bigNumLength is the size of the big number \c bigNum in bytes. 668 //! 669 //! \param [in] modulus is the pointer to the divisor. 670 //! 671 //! \param [in] modulusLength is the size of the divisor \c modulus in bytes. 672 //! 673 //! \param [out] resultPKAMemAddr is the pointer to the result vector location 674 //! which will be set by this function. 675 //! 676 //!\return Returns a status code. 677 //! - \ref PKA_STATUS_SUCCESS if successful in starting the operation. 678 //! - \ref PKA_STATUS_OPERATION_BUSY, if the PKA module is busy doing 679 //! some other operation. 680 //! 681 //! \sa PKABigNumModGetResult() 682 // 683 //***************************************************************************** 684 extern uint32_t PKABigNumModStart(const uint8_t *bigNum, uint32_t bigNumLength, const uint8_t *modulus, uint32_t modulusLength, uint32_t *resultPKAMemAddr); 685 686 //***************************************************************************** 687 // 688 //! \brief Gets the result of the big number modulus operation. 689 //! 690 //! This function gets the result of the big number modulus operation which was 691 //! previously started using the function PKABigNumModStart(). 692 //! The function will zero-out \c resultBuf prior to copying in the result of 693 //! the modulo operation. 694 //! 695 //! \param [out] resultBuf is the pointer to buffer where the result needs to 696 //! be stored. 697 //! 698 //! \param [in] length is the size of the provided buffer in bytes. 699 //! 700 //! \param [in] resultPKAMemAddr is the address of the result location which 701 //! was provided by the start function PKABigNumModStart(). 702 //! 703 //! \return Returns a status code. 704 //! - \ref PKA_STATUS_SUCCESS if successful. 705 //! - \ref PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing 706 //! the operation. 707 //! - \ref PKA_STATUS_RESULT_0 if the result is all zeros. 708 //! - \ref PKA_STATUS_BUF_UNDERFLOW if the \c length is less than the length 709 //! of the result. 710 //! 711 //! \sa PKABigNumModStart() 712 // 713 //***************************************************************************** 714 extern uint32_t PKABigNumModGetResult(uint8_t *resultBuf, uint32_t length, uint32_t resultPKAMemAddr); 715 716 //***************************************************************************** 717 // 718 //! \brief Starts a big number divide operation. 719 //! 720 //! This function starts the dive operation on the big number \c bigNum 721 //! using the \c divisor. The PKA RAM location where the result 722 //! will be available is stored in \c resultPKAMemAddr. 723 //! 724 //! \param [in] dividend is the pointer to the big number to be divided. 725 //! 726 //! \param [in] dividendLength is the size of the big number \c dividend in bytes. 727 //! 728 //! \param [in] divisor is the pointer to the divisor. 729 //! 730 //! \param [in] divisorLength is the size of the \c divisor in bytes. 731 //! 732 //! \param [out] resultQuotientMemAddr is the pointer to the quotient vector location 733 //! which will be set by this function. 734 //! 735 //! \param [out] resultRemainderMemAddr is the pointer to the remainder vector location 736 //! which will be set by this function. 737 //! 738 //!\return Returns a status code. 739 //! - \ref PKA_STATUS_SUCCESS if successful in starting the operation. 740 //! - \ref PKA_STATUS_OPERATION_BUSY, if the PKA module is busy doing 741 //! some other operation. 742 //! 743 //! \sa PKABigNumDivideGetResult() 744 // 745 //***************************************************************************** 746 extern uint32_t PKABigNumDivideStart(const uint8_t *dividend, 747 uint32_t dividendLength, 748 const uint8_t *divisor, 749 uint32_t divisorLength, 750 uint32_t *resultQuotientMemAddr, 751 uint32_t *resultRemainderMemAddr); 752 753 //***************************************************************************** 754 // 755 //! \brief Gets the quotient of the big number divide operation. 756 //! 757 //! This function gets the quotient of the big number divide operation which was 758 //! previously started using the function PKABigNumDivideStart(). 759 //! 760 //! \param [out] resultBuf is the pointer to buffer where the result needs to 761 //! be stored. 762 //! 763 //! \param [in] length is the size of the provided buffer in bytes. 764 //! 765 //! \param [in] resultQuotientMemAddr is the address of the result location which 766 //! was provided by the start function PKABigNumDivideStart(). 767 //! 768 //! \return Returns a status code. 769 //! - \ref PKA_STATUS_SUCCESS if successful. 770 //! - \ref PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing 771 //! the operation. 772 //! - \ref PKA_STATUS_RESULT_0 if the result is all zeros. 773 //! - \ref PKA_STATUS_BUF_UNDERFLOW if the \c length is less than the length 774 //! of the result. 775 //! 776 //! \sa PKABigNumDivideStart() 777 // 778 //***************************************************************************** 779 extern uint32_t PKABigNumDivideGetQuotient(uint8_t *resultBuf, uint32_t *length, uint32_t resultQuotientMemAddr); 780 781 //***************************************************************************** 782 // 783 //! \brief Gets the remainder of the big number divide operation. 784 //! 785 //! This function gets the remainder of the big number divide operation which was 786 //! previously started using the function PKABigNumDivideStart(). 787 //! 788 //! \param [out] resultBuf is the pointer to buffer where the result needs to 789 //! be stored. 790 //! 791 //! \param [in] length is the size of the provided buffer in bytes. 792 //! 793 //! \param [in] resultRemainderMemAddr is the address of the result location which 794 //! was provided by the start function PKABigNumDivideStart(). 795 //! 796 //! \return Returns a status code. 797 //! - \ref PKA_STATUS_SUCCESS if successful. 798 //! - \ref PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing 799 //! the operation. 800 //! - \ref PKA_STATUS_RESULT_0 if the result is all zeros. 801 //! - \ref PKA_STATUS_BUF_UNDERFLOW if the \c length is less than the length 802 //! of the result. 803 //! 804 //! \sa PKABigNumDivideStart() 805 // 806 //***************************************************************************** 807 extern uint32_t PKABigNumDivideGetRemainder(uint8_t *resultBuf, uint32_t *length, uint32_t resultRemainderMemAddr); 808 809 //***************************************************************************** 810 // 811 //! \brief Starts the comparison of two big numbers. 812 //! 813 //! This function starts the comparison of two big numbers pointed by 814 //! \c bigNum1 and \c bigNum2. 815 //! 816 //! \note \c bigNum1 and \c bigNum2 must have same size. 817 //! 818 //! \param [in] bigNum1 is the pointer to the first big number. 819 //! 820 //! \param [in] bigNum2 is the pointer to the second big number. 821 //! 822 //! \param [in] length is the size of the big numbers in bytes. 823 //! 824 //!\return Returns a status code. 825 //! - \ref PKA_STATUS_SUCCESS if successful in starting the operation. 826 //! - \ref PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing 827 //! some other operation. 828 //! 829 //! \sa PKABigNumCmpGetResult() 830 // 831 //***************************************************************************** 832 extern uint32_t PKABigNumCmpStart(const uint8_t *bigNum1, const uint8_t *bigNum2, uint32_t length); 833 834 //***************************************************************************** 835 // 836 //! \brief Gets the result of the comparison operation of two big numbers. 837 //! 838 //! This function provides the results of the comparison of two big numbers 839 //! which was started using the PKABigNumCmpStart(). 840 //! 841 //! \return Returns a status code. 842 //! - \ref PKA_STATUS_OPERATION_BUSY if the operation is in progress. 843 //! - \ref PKA_STATUS_SUCCESS if the two big numbers are equal. 844 //! - \ref PKA_STATUS_A_GREATER_THAN_B if the first number is greater than the second. 845 //! - \ref PKA_STATUS_A_LESS_THAN_B if the first number is less than the second. 846 //! 847 //! \sa PKABigNumCmpStart() 848 // 849 //***************************************************************************** 850 extern uint32_t PKABigNumCmpGetResult(void); 851 852 //***************************************************************************** 853 // 854 //! \brief Starts a big number inverse modulo operation. 855 //! 856 //! This function starts the inverse modulo operation on \c bigNum 857 //! using the divisor \c modulus. 858 //! 859 //! \param [in] bigNum is the pointer to the buffer containing the big number 860 //! (dividend). 861 //! 862 //! \param [in] bigNumLength is the size of the \c bigNum in bytes. 863 //! 864 //! \param [in] modulus is the pointer to the buffer containing the divisor. 865 //! 866 //! \param [in] modulusLength is the size of the divisor in bytes. 867 //! 868 //! \param [out] resultPKAMemAddr is the pointer to the result vector location 869 //! which will be set by this function. 870 //! 871 //! 872 //!\return Returns a status code. 873 //! - \ref PKA_STATUS_SUCCESS if successful in starting the operation. 874 //! - \ref PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing 875 //! some other operation. 876 //! 877 //! \sa PKABigNumInvModGetResult() 878 // 879 //***************************************************************************** 880 extern uint32_t PKABigNumInvModStart(const uint8_t *bigNum, uint32_t bigNumLength, const uint8_t *modulus, uint32_t modulusLength, uint32_t *resultPKAMemAddr); 881 882 883 //***************************************************************************** 884 // 885 //! \brief Gets the result of the big number inverse modulo operation. 886 //! 887 //! This function gets the result of the big number inverse modulo operation 888 //! previously started using the function PKABigNumInvModStart(). 889 //! The function will zero-out \c resultBuf prior to copying in the result of 890 //! the inverse modulo operation. 891 //! 892 //! \param [out] resultBuf is the pointer to buffer where the result needs to be 893 //! stored. 894 //! 895 //! \param [in] length is the size of the provided buffer in bytes. 896 //! 897 //! \param [in] resultPKAMemAddr is the address of the result location which 898 //! was provided by the start function PKABigNumInvModStart(). 899 //! 900 //! \return Returns a status code. 901 //! - \ref PKA_STATUS_SUCCESS if the operation is successful. 902 //! - \ref PKA_STATUS_OPERATION_BUSY if the PKA module is busy performing 903 //! the operation. 904 //! - \ref PKA_STATUS_RESULT_0 if the result is all zeros. 905 //! - \ref PKA_STATUS_BUF_UNDERFLOW if the length of the provided buffer is less 906 //! than the result. 907 //! 908 //! \sa PKABigNumInvModStart() 909 // 910 //***************************************************************************** 911 extern uint32_t PKABigNumInvModGetResult(uint8_t *resultBuf, uint32_t length, uint32_t resultPKAMemAddr); 912 913 //***************************************************************************** 914 // 915 //! \brief Starts a big number modular exponentiation operation. 916 //! 917 //! This function starts the exponentiation operation on \c base with 918 //! \c exponent and modulo \c modulus. 919 //! 920 //! \param [in] base is the pointer to the buffer containing the big number 921 //! to exponentiate. 922 //! 923 //! \param [in] baseLength is the size of the \c base in bytes. 924 //! 925 //! \param [in] exponent is the pointer to the buffer containing the big number 926 //! that exponentiates. 927 //! 928 //! \param [in] exponentLength is the size of the \c exponent in bytes. 929 930 //! \param [in] modulus is the pointer to the buffer containing the divisor. 931 //! 932 //! \param [in] modulusLength is the size of the divisor in bytes. 933 //! 934 //! \param [out] resultPKAMemAddr is the pointer to the result vector location 935 //! which will be set by this function. 936 //! 937 //! 938 //!\return Returns a status code. 939 //! - \ref PKA_STATUS_SUCCESS if successful in starting the operation. 940 //! - \ref PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing 941 //! some other operation. 942 //! 943 //! \sa PKABigNumExpModGetResult() 944 // 945 //***************************************************************************** 946 extern uint32_t PKABigNumExpModStart(const uint8_t *base, uint32_t baseLength, const uint8_t *exponent, uint32_t exponentLength, const uint8_t *modulus, uint32_t modulusLength, uint32_t *resultPKAMemAddr); 947 948 //***************************************************************************** 949 // 950 //! \brief Gets the result of the big number modular exponentiation operation. 951 //! 952 //! This function gets the result of the big number modular exponentiation 953 //! operation previously started using the function PKABigNumExpModStart(). 954 //! The function will zero-out \c resultBuf prior to copying in the result of 955 //! the modular exponentiation operation. 956 //! 957 //! \param [out] resultBuf is the pointer to buffer where the result needs to be 958 //! stored. 959 //! 960 //! \param [in] length is the size of the provided buffer in bytes. 961 //! 962 //! \param [in] resultPKAMemAddr is the address of the result location which 963 //! was provided by the start function PKABigNumExpModStart(). 964 //! 965 //! \return Returns a status code. 966 //! - \ref PKA_STATUS_SUCCESS if the operation is successful. 967 //! - \ref PKA_STATUS_OPERATION_BUSY if the PKA module is busy performing 968 //! the operation. 969 //! - \ref PKA_STATUS_RESULT_0 if the result is all zeros. 970 //! - \ref PKA_STATUS_BUF_UNDERFLOW if the length of the provided buffer is less 971 //! than the result. 972 //! 973 //! \sa PKABigNumExpModStart() 974 // 975 //***************************************************************************** 976 extern uint32_t PKABigNumExpModGetResult(uint8_t *resultBuf, uint32_t length, uint32_t resultPKAMemAddr); 977 978 //***************************************************************************** 979 // 980 //! \brief Starts the multiplication of two big numbers. 981 //! 982 //! \param [in] multiplicand is the pointer to the buffer containing the big 983 //! number multiplicand. 984 //! 985 //! \param [in] multiplicandLength is the size of the multiplicand in bytes. 986 //! 987 //! \param [in] multiplier is the pointer to the buffer containing the big 988 //! number multiplier. 989 //! 990 //! \param [in] multiplierLength is the size of the multiplier in bytes. 991 //! 992 //! \param [out] resultPKAMemAddr is the pointer to the result vector location 993 //! which will be set by this function. 994 //! 995 //!\return Returns a status code. 996 //! - \ref PKA_STATUS_SUCCESS if successful in starting the operation. 997 //! - \ref PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing 998 //! some other operation. 999 //! 1000 //! \sa PKABigNumMultGetResult() 1001 // 1002 //***************************************************************************** 1003 extern uint32_t PKABigNumMultiplyStart(const uint8_t *multiplicand, uint32_t multiplicandLength, const uint8_t *multiplier, uint32_t multiplierLength, uint32_t *resultPKAMemAddr); 1004 1005 //***************************************************************************** 1006 // 1007 //! \brief Gets the result of the big number multiplication. 1008 //! 1009 //! This function gets the result of the multiplication of two big numbers 1010 //! operation previously started using the function PKABigNumMultiplyStart(). 1011 //! 1012 //! \param [out] resultBuf is the pointer to buffer where the result needs to be 1013 //! stored. 1014 //! 1015 //! \param [in, out] resultLength is the address of the variable containing the length of the 1016 //! buffer in bytes. After the operation, the actual length of the resultant is stored 1017 //! at this address. 1018 //! 1019 //! \param [in] resultPKAMemAddr is the address of the result location which 1020 //! was provided by the start function PKABigNumMultiplyStart(). 1021 //! 1022 //! \return Returns a status code. 1023 //! - \ref PKA_STATUS_SUCCESS if the operation is successful. 1024 //! - \ref PKA_STATUS_OPERATION_BUSY if the PKA module is busy performing 1025 //! the operation. 1026 //! - \ref PKA_STATUS_RESULT_0 if the result is all zeros. 1027 //! - \ref PKA_STATUS_FAILURE if the operation is not successful. 1028 //! - \ref PKA_STATUS_BUF_UNDERFLOW if the length of the provided buffer is less 1029 //! then the length of the result. 1030 //! 1031 //! \sa PKABigNumMultiplyStart() 1032 // 1033 //***************************************************************************** 1034 extern uint32_t PKABigNumMultGetResult(uint8_t *resultBuf, uint32_t *resultLength, uint32_t resultPKAMemAddr); 1035 1036 //***************************************************************************** 1037 // 1038 //! \brief Starts the addition of two big numbers. 1039 //! 1040 //! \param [in] bigNum1 is the pointer to the buffer containing the first 1041 //! big number. 1042 //! 1043 //! \param [in] bigNum1Length is the size of the first big number in bytes. 1044 //! 1045 //! \param [in] bigNum2 is the pointer to the buffer containing the second 1046 //! big number. 1047 //! 1048 //! \param [in] bigNum2Length is the size of the second big number in bytes. 1049 //! 1050 //! \param [out] resultPKAMemAddr is the pointer to the result vector location 1051 //! which will be set by this function. 1052 //! 1053 //!\return Returns a status code. 1054 //! - \ref PKA_STATUS_SUCCESS if successful in starting the operation. 1055 //! - \ref PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing 1056 //! some other operation. 1057 //! 1058 //! \sa PKABigNumAddGetResult() 1059 // 1060 //***************************************************************************** 1061 extern uint32_t PKABigNumAddStart(const uint8_t *bigNum1, uint32_t bigNum1Length, const uint8_t *bigNum2, uint32_t bigNum2Length, uint32_t *resultPKAMemAddr); 1062 1063 //***************************************************************************** 1064 // 1065 //! \brief Gets the result of the addition operation on two big numbers. 1066 //! 1067 //! \param [out] resultBuf is the pointer to buffer where the result 1068 //! needs to be stored. 1069 //! 1070 //! \param [in, out] resultLength is the address of the variable containing 1071 //! the length of the buffer. After the operation the actual length of the 1072 //! resultant is stored at this address. 1073 //! 1074 //! \param [in] resultPKAMemAddr is the address of the result location which 1075 //! was provided by the start function PKABigNumAddStart(). 1076 //! 1077 //! 1078 //! \return Returns a status code. 1079 //! - \ref PKA_STATUS_SUCCESS if the operation is successful. 1080 //! - \ref PKA_STATUS_OPERATION_BUSY if the PKA module is busy performing 1081 //! the operation. 1082 //! - \ref PKA_STATUS_RESULT_0 if the result is all zeros. 1083 //! - \ref PKA_STATUS_FAILURE if the operation is not successful. 1084 //! - \ref PKA_STATUS_BUF_UNDERFLOW if the length of the provided buffer is less 1085 //! then the length of the result. 1086 //! 1087 //! \sa PKABigNumAddStart() 1088 // 1089 //***************************************************************************** 1090 extern uint32_t PKABigNumAddGetResult(uint8_t *resultBuf, uint32_t *resultLength, uint32_t resultPKAMemAddr); 1091 1092 //***************************************************************************** 1093 // 1094 //! \brief Starts the subtraction of one big number from another. 1095 //! 1096 //! \param [in] minuend is the pointer to the buffer containing the big number 1097 //! to be subtracted from. 1098 //! 1099 //! \param [in] minuendLength is the size of the minuend in bytes. 1100 //! 1101 //! \param [in] subtrahend is the pointer to the buffer containing the big 1102 //! number to subtract from the \c minuend. 1103 //! 1104 //! \param [in] subtrahendLength is the size of the subtrahend in bytes. 1105 //! 1106 //! \param [out] resultPKAMemAddr is the pointer to the result vector location 1107 //! which will be set by this function. 1108 //! 1109 //!\return Returns a status code. 1110 //! - \ref PKA_STATUS_SUCCESS if successful in starting the operation. 1111 //! - \ref PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing 1112 //! some other operation. 1113 //! 1114 //! \sa PKABigNumSubGetResult() 1115 // 1116 //***************************************************************************** 1117 extern uint32_t PKABigNumSubStart(const uint8_t *minuend, uint32_t minuendLength, const uint8_t *subtrahend, uint32_t subtrahendLength, uint32_t *resultPKAMemAddr); 1118 1119 //***************************************************************************** 1120 // 1121 //! \brief Gets the result of the subtraction operation on two big numbers. 1122 //! 1123 //! \param [out] resultBuf is the pointer to buffer where the result 1124 //! needs to be stored. 1125 //! 1126 //! \param [in, out] resultLength is the address of the variable containing 1127 //! the length of the buffer. After the operation the actual length of the 1128 //! resultant is stored at this address. 1129 //! 1130 //! \param [in] resultPKAMemAddr is the address of the result location which 1131 //! was provided by the start function PKABigNumAddStart(). 1132 //! 1133 //! 1134 //! \return Returns a status code. 1135 //! - \ref PKA_STATUS_SUCCESS if the operation is successful. 1136 //! - \ref PKA_STATUS_OPERATION_BUSY if the PKA module is busy performing 1137 //! the operation. 1138 //! - \ref PKA_STATUS_RESULT_0 if the result is all zeros. 1139 //! - \ref PKA_STATUS_FAILURE if the operation is not successful. 1140 //! - \ref PKA_STATUS_BUF_UNDERFLOW if the length of the provided buffer is less 1141 //! then the length of the result. 1142 //! 1143 //! \sa PKABigNumSubStart() 1144 // 1145 //***************************************************************************** 1146 extern uint32_t PKABigNumSubGetResult(uint8_t *resultBuf, uint32_t *resultLength, uint32_t resultPKAMemAddr); 1147 1148 //***************************************************************************** 1149 // 1150 //! \brief Starts ECC multiplication. 1151 //! 1152 //! \param [in] scalar is pointer to the buffer containing the scalar 1153 //! value to be multiplied. 1154 //! 1155 //! \param [in] curvePointX is the pointer to the buffer containing the 1156 //! X coordinate of the elliptic curve point to be multiplied. 1157 //! The point must be on the given curve. 1158 //! 1159 //! \param [in] curvePointY is the pointer to the buffer containing the 1160 //! Y coordinate of the elliptic curve point to be multiplied. 1161 //! The point must be on the given curve. 1162 //! 1163 //! \param [in] prime is the prime of the curve. 1164 //! 1165 //! \param [in] a is the a constant of the curve when the curve equation is expressed 1166 //! in short Weierstrass form (y^3 = x^2 + a*x + b). 1167 //! 1168 //! \param [in] b is the b constant of the curve when the curve equation is expressed 1169 //! in short Weierstrass form (y^3 = x^2 + a*x + b). 1170 //! 1171 //! \param [in] length is the length of the curve parameters in bytes. 1172 //! 1173 //! \param [out] resultPKAMemAddr is the pointer to the result vector location 1174 //! which will be set by this function. 1175 //! 1176 //!\return Returns a status code. 1177 //! - \ref PKA_STATUS_SUCCESS if successful in starting the operation. 1178 //! - \ref PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing 1179 //! some other operation. 1180 //! 1181 //! \sa PKAEccMultiplyGetResult() 1182 // 1183 //***************************************************************************** 1184 extern uint32_t PKAEccMultiplyStart(const uint8_t *scalar, 1185 const uint8_t *curvePointX, 1186 const uint8_t *curvePointY, 1187 const uint8_t *prime, 1188 const uint8_t *a, 1189 const uint8_t *b, 1190 uint32_t length, 1191 uint32_t *resultPKAMemAddr); 1192 1193 //***************************************************************************** 1194 // 1195 //! \brief Starts ECC Montgomery multiplication. 1196 //! 1197 //! \param [in] scalar is pointer to the buffer containing the scalar 1198 //! value to be multiplied. 1199 //! 1200 //! \param [in] curvePointX is the pointer to the buffer containing the 1201 //! X coordinate of the elliptic curve point to be multiplied. 1202 //! The point must be on the given curve. 1203 //! 1204 //! \param [in] prime is the prime of the curve. 1205 //! 1206 //! \param [in] a is the a constant of the curve when the curve equation is expressed 1207 //! in short Weierstrass form (y^3 = x^2 + a*x + b). 1208 //! 1209 //! \param [in] length is the length of the curve parameters in bytes. 1210 //! 1211 //! \param [out] resultPKAMemAddr is the pointer to the result vector location 1212 //! which will be set by this function. 1213 //! 1214 //!\return Returns a status code. 1215 //! - \ref PKA_STATUS_SUCCESS if successful in starting the operation. 1216 //! - \ref PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing 1217 //! some other operation. 1218 //! 1219 //! \sa PKAEccMultiplyGetResult() 1220 // 1221 //***************************************************************************** 1222 extern uint32_t PKAEccMontgomeryMultiplyStart(const uint8_t *scalar, 1223 const uint8_t *curvePointX, 1224 const uint8_t *prime, 1225 const uint8_t *a, 1226 uint32_t length, 1227 uint32_t *resultPKAMemAddr); 1228 1229 //***************************************************************************** 1230 // 1231 //! \brief Gets the result of ECC multiplication 1232 //! 1233 //! This function gets the result of ECC point multiplication operation on the 1234 //! EC point and the scalar value, previously started using the function 1235 //! PKAEccMultiplyStart(). 1236 //! 1237 //! \param [out] curvePointX is the pointer to the structure where the X coordinate 1238 //! of the resultant EC point will be stored. 1239 //! 1240 //! \param [out] curvePointY is the pointer to the structure where the Y coordinate 1241 //! of the resultant EC point will be stored. 1242 //! 1243 //! \param [in] resultPKAMemAddr is the address of the result location which 1244 //! was provided by the start function PKAEccMultiplyStart(). 1245 //! 1246 //! \param [in] length is the length of the curve parameters in bytes. 1247 //! 1248 //! \return Returns a status code. 1249 //! - \ref PKA_STATUS_SUCCESS if the operation is successful. 1250 //! - \ref PKA_STATUS_OPERATION_BUSY if the PKA module is busy performing 1251 //! the operation. 1252 //! - \ref PKA_STATUS_RESULT_0 if the result is all zeros. 1253 //! - \ref PKA_STATUS_FAILURE if the operation is not successful. 1254 //! 1255 //! \sa PKAEccMultiplyStart() 1256 // 1257 //***************************************************************************** 1258 extern uint32_t PKAEccMultiplyGetResult(uint8_t *curvePointX, uint8_t *curvePointY, uint32_t resultPKAMemAddr, uint32_t length); 1259 1260 //***************************************************************************** 1261 // 1262 //! \brief Starts the ECC addition. 1263 //! 1264 //! \param [in] curvePoint1X is the pointer to the buffer containing the 1265 //! X coordinate of the first elliptic curve point to be added. 1266 //! The point must be on the given curve. 1267 //! 1268 //! \param [in] curvePoint1Y is the pointer to the buffer containing the 1269 //! Y coordinate of the first elliptic curve point to be added. 1270 //! The point must be on the given curve. 1271 //! 1272 //! \param [in] curvePoint2X is the pointer to the buffer containing the 1273 //! X coordinate of the second elliptic curve point to be added. 1274 //! The point must be on the given curve. 1275 //! 1276 //! \param [in] curvePoint2Y is the pointer to the buffer containing the 1277 //! Y coordinate of the second elliptic curve point to be added. 1278 //! The point must be on the given curve. 1279 //! 1280 //! \param [in] prime is the prime of the curve. 1281 //! 1282 //! \param [in] a is the a constant of the curve when the curve equation is expressed 1283 //! in short Weierstrass form (y^3 = x^2 + a*x + b). 1284 //! 1285 //! \param [in] length is the length of the curve parameters in bytes. 1286 //! 1287 //! \param [out] resultPKAMemAddr is the pointer to the result vector location 1288 //! which will be set by this function. 1289 //! 1290 //!\return Returns a status code. 1291 //! - \ref PKA_STATUS_SUCCESS if successful in starting the operation. 1292 //! - \ref PKA_STATUS_OPERATION_BUSY if the PKA module is busy doing 1293 //! some other operation. 1294 //! 1295 //! \sa PKAEccAddGetResult() 1296 // 1297 //***************************************************************************** 1298 extern uint32_t PKAEccAddStart(const uint8_t *curvePoint1X, 1299 const uint8_t *curvePoint1Y, 1300 const uint8_t *curvePoint2X, 1301 const uint8_t *curvePoint2Y, 1302 const uint8_t *prime, 1303 const uint8_t *a, 1304 uint32_t length, 1305 uint32_t *resultPKAMemAddr); 1306 1307 //***************************************************************************** 1308 // 1309 //! \brief Gets the result of the ECC addition 1310 //! 1311 //! This function gets the result of ECC point addition operation on the 1312 //! on the two given EC points, previously started using the function 1313 //! PKAEccAddStart(). 1314 //! 1315 //! \param [out] curvePointX is the pointer to the structure where the X coordinate 1316 //! of the resultant EC point will be stored. 1317 //! 1318 //! \param [out] curvePointY is the pointer to the structure where the Y coordinate 1319 //! of the resultant EC point will be stored. 1320 //! 1321 //! \param [in] resultPKAMemAddr is the address of the result location which 1322 //! was provided by the start function PKAEccAddGetResult(). 1323 //! 1324 //! \param [in] length is the length of the curve parameters in bytes. 1325 //! 1326 //! \return Returns a status code. 1327 //! - \ref PKA_STATUS_SUCCESS if the operation is successful. 1328 //! - \ref PKA_STATUS_OPERATION_BUSY if the PKA module is busy performing the operation. 1329 //! - \ref PKA_STATUS_RESULT_0 if the result is all zeros. 1330 //! - \ref PKA_STATUS_FAILURE if the operation is not successful. 1331 //! 1332 //! \sa PKAEccAddStart() 1333 // 1334 //***************************************************************************** 1335 extern uint32_t PKAEccAddGetResult(uint8_t *curvePointX, uint8_t *curvePointY, uint32_t resultPKAMemAddr, uint32_t length); 1336 1337 1338 //***************************************************************************** 1339 // 1340 //! \brief Begins the validation of a public key against a Short-Weierstrass curve 1341 //! 1342 //! This function validates a public key against a curve. 1343 //! After performing multiple smaller PKA operations in polling mode, 1344 //! it starts an ECC scalar multiplication. 1345 //! 1346 //! The function verifies that: 1347 //! - X and Y are in the range [1, prime - 1] 1348 //! - The point is not the point at infinity 1349 //! - X and Y satisfy the Short-Weierstrass curve equation Y^2 = X^3 + a*X + b mod P 1350 //! - Multiplying the point by the order of the curve yields the point at infinity 1351 //! 1352 //! \param [in] curvePointX is the pointer to the buffer containing the 1353 //! X coordinate of the elliptic curve point to verify. 1354 //! 1355 //! \param [in] curvePointY is the pointer to the buffer containing the 1356 //! Y coordinate of the elliptic curve point to verify. 1357 //! 1358 //! \param [in] prime is the prime of the curve. 1359 //! 1360 //! \param [in] a is the a constant of the curve when the curve equation is expressed 1361 //! in Short-Weierstrass form (y^3 = x^2 + a*x + b). 1362 //! 1363 //! \param [in] b is the b constant of the curve when the curve equation is expressed 1364 //! in Short-Weierstrass form (y^3 = x^2 + a*x + b). 1365 //! 1366 //! \param [in] order is the order of the curve. 1367 //! 1368 //! \param [in] length is the length of the curve parameters in bytes. 1369 //! 1370 //! \return Returns a status code. 1371 //! - \ref PKA_STATUS_SUCCESS if the operation is successful. 1372 //! - \ref PKA_STATUS_OPERATION_BUSY if the PKA module is busy performing the operation. 1373 //! - \ref PKA_STATUS_FAILURE if the operation is not successful. 1374 //! - \ref PKA_STATUS_X_ZERO if X is zero. 1375 //! - \ref PKA_STATUS_Y_ZERO if Y is zero. 1376 //! - \ref PKA_STATUS_X_LARGER_THAN_PRIME if X is larger than the curve prime 1377 //! - \ref PKA_STATUS_Y_LARGER_THAN_PRIME if Y is larger than the curve prime 1378 //! - \ref PKA_STATUS_POINT_NOT_ON_CURVE if X and Y do not satisfy the curve equation 1379 //! 1380 //! \sa PKAEccVerifyPublicKeyGetResult() 1381 // 1382 //***************************************************************************** 1383 extern uint32_t PKAEccVerifyPublicKeyWeierstrassStart(const uint8_t *curvePointX, 1384 const uint8_t *curvePointY, 1385 const uint8_t *prime, 1386 const uint8_t *a, 1387 const uint8_t *b, 1388 const uint8_t *order, 1389 uint32_t length); 1390 1391 //***************************************************************************** 1392 // 1393 // Support for DriverLib in ROM: 1394 // Redirect to implementation in ROM when available. 1395 // 1396 //***************************************************************************** 1397 #if !defined(DRIVERLIB_NOROM) && !defined(DOXYGEN) 1398 #include "../driverlib/rom.h" 1399 #ifdef ROM_PKAClearPkaRam 1400 #undef PKAClearPkaRam 1401 #define PKAClearPkaRam ROM_PKAClearPkaRam 1402 #endif 1403 #ifdef ROM_PKAGetOpsStatus 1404 #undef PKAGetOpsStatus 1405 #define PKAGetOpsStatus ROM_PKAGetOpsStatus 1406 #endif 1407 #ifdef ROM_PKAArrayAllZeros 1408 #undef PKAArrayAllZeros 1409 #define PKAArrayAllZeros ROM_PKAArrayAllZeros 1410 #endif 1411 #ifdef ROM_PKAZeroOutArray 1412 #undef PKAZeroOutArray 1413 #define PKAZeroOutArray ROM_PKAZeroOutArray 1414 #endif 1415 #ifdef ROM_PKABigNumModStart 1416 #undef PKABigNumModStart 1417 #define PKABigNumModStart ROM_PKABigNumModStart 1418 #endif 1419 #ifdef ROM_PKABigNumModGetResult 1420 #undef PKABigNumModGetResult 1421 #define PKABigNumModGetResult ROM_PKABigNumModGetResult 1422 #endif 1423 #ifdef ROM_PKABigNumDivideStart 1424 #undef PKABigNumDivideStart 1425 #define PKABigNumDivideStart ROM_PKABigNumDivideStart 1426 #endif 1427 #ifdef ROM_PKABigNumDivideGetQuotient 1428 #undef PKABigNumDivideGetQuotient 1429 #define PKABigNumDivideGetQuotient ROM_PKABigNumDivideGetQuotient 1430 #endif 1431 #ifdef ROM_PKABigNumDivideGetRemainder 1432 #undef PKABigNumDivideGetRemainder 1433 #define PKABigNumDivideGetRemainder ROM_PKABigNumDivideGetRemainder 1434 #endif 1435 #ifdef ROM_PKABigNumCmpStart 1436 #undef PKABigNumCmpStart 1437 #define PKABigNumCmpStart ROM_PKABigNumCmpStart 1438 #endif 1439 #ifdef ROM_PKABigNumCmpGetResult 1440 #undef PKABigNumCmpGetResult 1441 #define PKABigNumCmpGetResult ROM_PKABigNumCmpGetResult 1442 #endif 1443 #ifdef ROM_PKABigNumInvModStart 1444 #undef PKABigNumInvModStart 1445 #define PKABigNumInvModStart ROM_PKABigNumInvModStart 1446 #endif 1447 #ifdef ROM_PKABigNumInvModGetResult 1448 #undef PKABigNumInvModGetResult 1449 #define PKABigNumInvModGetResult ROM_PKABigNumInvModGetResult 1450 #endif 1451 #ifdef ROM_PKABigNumExpModStart 1452 #undef PKABigNumExpModStart 1453 #define PKABigNumExpModStart ROM_PKABigNumExpModStart 1454 #endif 1455 #ifdef ROM_PKABigNumExpModGetResult 1456 #undef PKABigNumExpModGetResult 1457 #define PKABigNumExpModGetResult ROM_PKABigNumExpModGetResult 1458 #endif 1459 #ifdef ROM_PKABigNumMultiplyStart 1460 #undef PKABigNumMultiplyStart 1461 #define PKABigNumMultiplyStart ROM_PKABigNumMultiplyStart 1462 #endif 1463 #ifdef ROM_PKABigNumMultGetResult 1464 #undef PKABigNumMultGetResult 1465 #define PKABigNumMultGetResult ROM_PKABigNumMultGetResult 1466 #endif 1467 #ifdef ROM_PKABigNumAddStart 1468 #undef PKABigNumAddStart 1469 #define PKABigNumAddStart ROM_PKABigNumAddStart 1470 #endif 1471 #ifdef ROM_PKABigNumAddGetResult 1472 #undef PKABigNumAddGetResult 1473 #define PKABigNumAddGetResult ROM_PKABigNumAddGetResult 1474 #endif 1475 #ifdef ROM_PKABigNumSubStart 1476 #undef PKABigNumSubStart 1477 #define PKABigNumSubStart ROM_PKABigNumSubStart 1478 #endif 1479 #ifdef ROM_PKABigNumSubGetResult 1480 #undef PKABigNumSubGetResult 1481 #define PKABigNumSubGetResult ROM_PKABigNumSubGetResult 1482 #endif 1483 #ifdef ROM_PKAEccMultiplyStart 1484 #undef PKAEccMultiplyStart 1485 #define PKAEccMultiplyStart ROM_PKAEccMultiplyStart 1486 #endif 1487 #ifdef ROM_PKAEccMontgomeryMultiplyStart 1488 #undef PKAEccMontgomeryMultiplyStart 1489 #define PKAEccMontgomeryMultiplyStart ROM_PKAEccMontgomeryMultiplyStart 1490 #endif 1491 #ifdef ROM_PKAEccMultiplyGetResult 1492 #undef PKAEccMultiplyGetResult 1493 #define PKAEccMultiplyGetResult ROM_PKAEccMultiplyGetResult 1494 #endif 1495 #ifdef ROM_PKAEccAddStart 1496 #undef PKAEccAddStart 1497 #define PKAEccAddStart ROM_PKAEccAddStart 1498 #endif 1499 #ifdef ROM_PKAEccAddGetResult 1500 #undef PKAEccAddGetResult 1501 #define PKAEccAddGetResult ROM_PKAEccAddGetResult 1502 #endif 1503 #ifdef ROM_PKAEccVerifyPublicKeyWeierstrassStart 1504 #undef PKAEccVerifyPublicKeyWeierstrassStart 1505 #define PKAEccVerifyPublicKeyWeierstrassStart ROM_PKAEccVerifyPublicKeyWeierstrassStart 1506 #endif 1507 #endif 1508 1509 //***************************************************************************** 1510 // 1511 // Mark the end of the C bindings section for C++ compilers. 1512 // 1513 //***************************************************************************** 1514 #ifdef __cplusplus 1515 } 1516 #endif 1517 1518 #endif // __PKA_H__ 1519 1520 //***************************************************************************** 1521 // 1522 //! Close the Doxygen group. 1523 //! @} 1524 //! @} 1525 // 1526 //***************************************************************************** 1527
