CryptoPkg/Include/Library/BaseCryptLib.h

   1 /** @file
   2   Defines base cryptographic library APIs.
   3   The Base Cryptographic Library provides implementations of basic cryptography
   4   primitives (Hash Serials, HMAC, RSA, Diffie-Hellman, etc) for UEFI security
   5   functionality enabling.
   6
   7 Copyright (c) 2009 - 2020, Intel Corporation. All rights reserved.<BR>
   8 SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10 **/
  11
  12 #ifndef __BASE_CRYPT_LIB_H__
  13 #define __BASE_CRYPT_LIB_H__
  14
  15 #include <Uefi/UefiBaseType.h>
  16
  17 ///
  18 /// MD5 digest size in bytes
  19 ///
  20 #define MD5_DIGEST_SIZE     16
  21
  22 ///
  23 /// SHA-1 digest size in bytes.
  24 ///
  25 #define SHA1_DIGEST_SIZE    20
  26
  27 ///
  28 /// SHA-256 digest size in bytes
  29 ///
  30 #define SHA256_DIGEST_SIZE  32
  31
  32 ///
  33 /// SHA-384 digest size in bytes
  34 ///
  35 #define SHA384_DIGEST_SIZE  48
  36
  37 ///
  38 /// SHA-512 digest size in bytes
  39 ///
  40 #define SHA512_DIGEST_SIZE  64
  41
  42 ///
  43 /// SM3 digest size in bytes
  44 ///
  45 #define SM3_256_DIGEST_SIZE 32
  46
  47 ///
  48 /// TDES block size in bytes
  49 ///
  50 #define TDES_BLOCK_SIZE     8
  51
  52 ///
  53 /// AES block size in bytes
  54 ///
  55 #define AES_BLOCK_SIZE      16
  56
  57 ///
  58 /// RSA Key Tags Definition used in RsaSetKey() function for key component identification.
  59 ///
  60 typedef enum {
  61   RsaKeyN,      ///< RSA public Modulus (N)
  62   RsaKeyE,      ///< RSA Public exponent (e)
  63   RsaKeyD,      ///< RSA Private exponent (d)
  64   RsaKeyP,      ///< RSA secret prime factor of Modulus (p)
  65   RsaKeyQ,      ///< RSA secret prime factor of Modules (q)
  66   RsaKeyDp,     ///< p's CRT exponent (== d mod (p - 1))
  67   RsaKeyDq,     ///< q's CRT exponent (== d mod (q - 1))
  68   RsaKeyQInv    ///< The CRT coefficient (== 1/q mod p)
  69 } RSA_KEY_TAG;
  70
  71 //=====================================================================================
  72 //    One-Way Cryptographic Hash Primitives
  73 //=====================================================================================
  74
  75 /**
  76   Retrieves the size, in bytes, of the context buffer required for MD5 hash operations.
  77
  78   If this interface is not supported, then return zero.
  79
  80   @return  The size, in bytes, of the context buffer required for MD5 hash operations.
  81   @retval  0   This interface is not supported.
  82
  83 **/
  84 UINTN
  85 EFIAPI
  86 Md5GetContextSize (
  87   VOID
  88   );
  89
  90 /**
  91   Initializes user-supplied memory pointed by Md5Context as MD5 hash context for
  92   subsequent use.
  93
  94   If Md5Context is NULL, then return FALSE.
  95   If this interface is not supported, then return FALSE.
  96
  97   @param[out]  Md5Context  Pointer to MD5 context being initialized.
  98
  99   @retval TRUE   MD5 context initialization succeeded.
 100   @retval FALSE  MD5 context initialization failed.
 101   @retval FALSE  This interface is not supported.
 102
 103 **/
 104 BOOLEAN
 105 EFIAPI
 106 Md5Init (
 107   OUT  VOID  *Md5Context
 108   );
 109
 110 /**
 111   Makes a copy of an existing MD5 context.
 112
 113   If Md5Context is NULL, then return FALSE.
 114   If NewMd5Context is NULL, then return FALSE.
 115   If this interface is not supported, then return FALSE.
 116
 117   @param[in]  Md5Context     Pointer to MD5 context being copied.
 118   @param[out] NewMd5Context  Pointer to new MD5 context.
 119
 120   @retval TRUE   MD5 context copy succeeded.
 121   @retval FALSE  MD5 context copy failed.
 122   @retval FALSE  This interface is not supported.
 123
 124 **/
 125 BOOLEAN
 126 EFIAPI
 127 Md5Duplicate (
 128   IN   CONST VOID  *Md5Context,
 129   OUT  VOID        *NewMd5Context
 130   );
 131
 132 /**
 133   Digests the input data and updates MD5 context.
 134
 135   This function performs MD5 digest on a data buffer of the specified size.
 136   It can be called multiple times to compute the digest of long or discontinuous data streams.
 137   MD5 context should be already correctly initialized by Md5Init(), and should not be finalized
 138   by Md5Final(). Behavior with invalid context is undefined.
 139
 140   If Md5Context is NULL, then return FALSE.
 141   If this interface is not supported, then return FALSE.
 142
 143   @param[in, out]  Md5Context  Pointer to the MD5 context.
 144   @param[in]       Data        Pointer to the buffer containing the data to be hashed.
 145   @param[in]       DataSize    Size of Data buffer in bytes.
 146
 147   @retval TRUE   MD5 data digest succeeded.
 148   @retval FALSE  MD5 data digest failed.
 149   @retval FALSE  This interface is not supported.
 150
 151 **/
 152 BOOLEAN
 153 EFIAPI
 154 Md5Update (
 155   IN OUT  VOID        *Md5Context,
 156   IN      CONST VOID  *Data,
 157   IN      UINTN       DataSize
 158   );
 159
 160 /**
 161   Completes computation of the MD5 digest value.
 162
 163   This function completes MD5 hash computation and retrieves the digest value into
 164   the specified memory. After this function has been called, the MD5 context cannot
 165   be used again.
 166   MD5 context should be already correctly initialized by Md5Init(), and should not be
 167   finalized by Md5Final(). Behavior with invalid MD5 context is undefined.
 168
 169   If Md5Context is NULL, then return FALSE.
 170   If HashValue is NULL, then return FALSE.
 171   If this interface is not supported, then return FALSE.
 172
 173   @param[in, out]  Md5Context  Pointer to the MD5 context.
 174   @param[out]      HashValue   Pointer to a buffer that receives the MD5 digest
 175                                value (16 bytes).
 176
 177   @retval TRUE   MD5 digest computation succeeded.
 178   @retval FALSE  MD5 digest computation failed.
 179   @retval FALSE  This interface is not supported.
 180
 181 **/
 182 BOOLEAN
 183 EFIAPI
 184 Md5Final (
 185   IN OUT  VOID   *Md5Context,
 186   OUT     UINT8  *HashValue
 187   );
 188
 189 /**
 190   Computes the MD5 message digest of a input data buffer.
 191
 192   This function performs the MD5 message digest of a given data buffer, and places
 193   the digest value into the specified memory.
 194
 195   If this interface is not supported, then return FALSE.
 196
 197   @param[in]   Data        Pointer to the buffer containing the data to be hashed.
 198   @param[in]   DataSize    Size of Data buffer in bytes.
 199   @param[out]  HashValue   Pointer to a buffer that receives the MD5 digest
 200                            value (16 bytes).
 201
 202   @retval TRUE   MD5 digest computation succeeded.
 203   @retval FALSE  MD5 digest computation failed.
 204   @retval FALSE  This interface is not supported.
 205
 206 **/
 207 BOOLEAN
 208 EFIAPI
 209 Md5HashAll (
 210   IN   CONST VOID  *Data,
 211   IN   UINTN       DataSize,
 212   OUT  UINT8       *HashValue
 213   );
 214
 215 /**
 216   Retrieves the size, in bytes, of the context buffer required for SHA-1 hash operations.
 217
 218   If this interface is not supported, then return zero.
 219
 220   @return  The size, in bytes, of the context buffer required for SHA-1 hash operations.
 221   @retval  0   This interface is not supported.
 222
 223 **/
 224 UINTN
 225 EFIAPI
 226 Sha1GetContextSize (
 227   VOID
 228   );
 229
 230 /**
 231   Initializes user-supplied memory pointed by Sha1Context as SHA-1 hash context for
 232   subsequent use.
 233
 234   If Sha1Context is NULL, then return FALSE.
 235   If this interface is not supported, then return FALSE.
 236
 237   @param[out]  Sha1Context  Pointer to SHA-1 context being initialized.
 238
 239   @retval TRUE   SHA-1 context initialization succeeded.
 240   @retval FALSE  SHA-1 context initialization failed.
 241   @retval FALSE  This interface is not supported.
 242
 243 **/
 244 BOOLEAN
 245 EFIAPI
 246 Sha1Init (
 247   OUT  VOID  *Sha1Context
 248   );
 249
 250 /**
 251   Makes a copy of an existing SHA-1 context.
 252
 253   If Sha1Context is NULL, then return FALSE.
 254   If NewSha1Context is NULL, then return FALSE.
 255   If this interface is not supported, then return FALSE.
 256
 257   @param[in]  Sha1Context     Pointer to SHA-1 context being copied.
 258   @param[out] NewSha1Context  Pointer to new SHA-1 context.
 259
 260   @retval TRUE   SHA-1 context copy succeeded.
 261   @retval FALSE  SHA-1 context copy failed.
 262   @retval FALSE  This interface is not supported.
 263
 264 **/
 265 BOOLEAN
 266 EFIAPI
 267 Sha1Duplicate (
 268   IN   CONST VOID  *Sha1Context,
 269   OUT  VOID        *NewSha1Context
 270   );
 271
 272 /**
 273   Digests the input data and updates SHA-1 context.
 274
 275   This function performs SHA-1 digest on a data buffer of the specified size.
 276   It can be called multiple times to compute the digest of long or discontinuous data streams.
 277   SHA-1 context should be already correctly initialized by Sha1Init(), and should not be finalized
 278   by Sha1Final(). Behavior with invalid context is undefined.
 279
 280   If Sha1Context is NULL, then return FALSE.
 281   If this interface is not supported, then return FALSE.
 282
 283   @param[in, out]  Sha1Context  Pointer to the SHA-1 context.
 284   @param[in]       Data         Pointer to the buffer containing the data to be hashed.
 285   @param[in]       DataSize     Size of Data buffer in bytes.
 286
 287   @retval TRUE   SHA-1 data digest succeeded.
 288   @retval FALSE  SHA-1 data digest failed.
 289   @retval FALSE  This interface is not supported.
 290
 291 **/
 292 BOOLEAN
 293 EFIAPI
 294 Sha1Update (
 295   IN OUT  VOID        *Sha1Context,
 296   IN      CONST VOID  *Data,
 297   IN      UINTN       DataSize
 298   );
 299
 300 /**
 301   Completes computation of the SHA-1 digest value.
 302
 303   This function completes SHA-1 hash computation and retrieves the digest value into
 304   the specified memory. After this function has been called, the SHA-1 context cannot
 305   be used again.
 306   SHA-1 context should be already correctly initialized by Sha1Init(), and should not be
 307   finalized by Sha1Final(). Behavior with invalid SHA-1 context is undefined.
 308
 309   If Sha1Context is NULL, then return FALSE.
 310   If HashValue is NULL, then return FALSE.
 311   If this interface is not supported, then return FALSE.
 312
 313   @param[in, out]  Sha1Context  Pointer to the SHA-1 context.
 314   @param[out]      HashValue    Pointer to a buffer that receives the SHA-1 digest
 315                                 value (20 bytes).
 316
 317   @retval TRUE   SHA-1 digest computation succeeded.
 318   @retval FALSE  SHA-1 digest computation failed.
 319   @retval FALSE  This interface is not supported.
 320
 321 **/
 322 BOOLEAN
 323 EFIAPI
 324 Sha1Final (
 325   IN OUT  VOID   *Sha1Context,
 326   OUT     UINT8  *HashValue
 327   );
 328
 329 /**
 330   Computes the SHA-1 message digest of a input data buffer.
 331
 332   This function performs the SHA-1 message digest of a given data buffer, and places
 333   the digest value into the specified memory.
 334
 335   If this interface is not supported, then return FALSE.
 336
 337   @param[in]   Data        Pointer to the buffer containing the data to be hashed.
 338   @param[in]   DataSize    Size of Data buffer in bytes.
 339   @param[out]  HashValue   Pointer to a buffer that receives the SHA-1 digest
 340                            value (20 bytes).
 341
 342   @retval TRUE   SHA-1 digest computation succeeded.
 343   @retval FALSE  SHA-1 digest computation failed.
 344   @retval FALSE  This interface is not supported.
 345
 346 **/
 347 BOOLEAN
 348 EFIAPI
 349 Sha1HashAll (
 350   IN   CONST VOID  *Data,
 351   IN   UINTN       DataSize,
 352   OUT  UINT8       *HashValue
 353   );
 354
 355 /**
 356   Retrieves the size, in bytes, of the context buffer required for SHA-256 hash operations.
 357
 358   @return  The size, in bytes, of the context buffer required for SHA-256 hash operations.
 359
 360 **/
 361 UINTN
 362 EFIAPI
 363 Sha256GetContextSize (
 364   VOID
 365   );
 366
 367 /**
 368   Initializes user-supplied memory pointed by Sha256Context as SHA-256 hash context for
 369   subsequent use.
 370
 371   If Sha256Context is NULL, then return FALSE.
 372
 373   @param[out]  Sha256Context  Pointer to SHA-256 context being initialized.
 374
 375   @retval TRUE   SHA-256 context initialization succeeded.
 376   @retval FALSE  SHA-256 context initialization failed.
 377
 378 **/
 379 BOOLEAN
 380 EFIAPI
 381 Sha256Init (
 382   OUT  VOID  *Sha256Context
 383   );
 384
 385 /**
 386   Makes a copy of an existing SHA-256 context.
 387
 388   If Sha256Context is NULL, then return FALSE.
 389   If NewSha256Context is NULL, then return FALSE.
 390   If this interface is not supported, then return FALSE.
 391
 392   @param[in]  Sha256Context     Pointer to SHA-256 context being copied.
 393   @param[out] NewSha256Context  Pointer to new SHA-256 context.
 394
 395   @retval TRUE   SHA-256 context copy succeeded.
 396   @retval FALSE  SHA-256 context copy failed.
 397   @retval FALSE  This interface is not supported.
 398
 399 **/
 400 BOOLEAN
 401 EFIAPI
 402 Sha256Duplicate (
 403   IN   CONST VOID  *Sha256Context,
 404   OUT  VOID        *NewSha256Context
 405   );
 406
 407 /**
 408   Digests the input data and updates SHA-256 context.
 409
 410   This function performs SHA-256 digest on a data buffer of the specified size.
 411   It can be called multiple times to compute the digest of long or discontinuous data streams.
 412   SHA-256 context should be already correctly initialized by Sha256Init(), and should not be finalized
 413   by Sha256Final(). Behavior with invalid context is undefined.
 414
 415   If Sha256Context is NULL, then return FALSE.
 416
 417   @param[in, out]  Sha256Context  Pointer to the SHA-256 context.
 418   @param[in]       Data           Pointer to the buffer containing the data to be hashed.
 419   @param[in]       DataSize       Size of Data buffer in bytes.
 420
 421   @retval TRUE   SHA-256 data digest succeeded.
 422   @retval FALSE  SHA-256 data digest failed.
 423
 424 **/
 425 BOOLEAN
 426 EFIAPI
 427 Sha256Update (
 428   IN OUT  VOID        *Sha256Context,
 429   IN      CONST VOID  *Data,
 430   IN      UINTN       DataSize
 431   );
 432
 433 /**
 434   Completes computation of the SHA-256 digest value.
 435
 436   This function completes SHA-256 hash computation and retrieves the digest value into
 437   the specified memory. After this function has been called, the SHA-256 context cannot
 438   be used again.
 439   SHA-256 context should be already correctly initialized by Sha256Init(), and should not be
 440   finalized by Sha256Final(). Behavior with invalid SHA-256 context is undefined.
 441
 442   If Sha256Context is NULL, then return FALSE.
 443   If HashValue is NULL, then return FALSE.
 444
 445   @param[in, out]  Sha256Context  Pointer to the SHA-256 context.
 446   @param[out]      HashValue      Pointer to a buffer that receives the SHA-256 digest
 447                                   value (32 bytes).
 448
 449   @retval TRUE   SHA-256 digest computation succeeded.
 450   @retval FALSE  SHA-256 digest computation failed.
 451
 452 **/
 453 BOOLEAN
 454 EFIAPI
 455 Sha256Final (
 456   IN OUT  VOID   *Sha256Context,
 457   OUT     UINT8  *HashValue
 458   );
 459
 460 /**
 461   Computes the SHA-256 message digest of a input data buffer.
 462
 463   This function performs the SHA-256 message digest of a given data buffer, and places
 464   the digest value into the specified memory.
 465
 466   If this interface is not supported, then return FALSE.
 467
 468   @param[in]   Data        Pointer to the buffer containing the data to be hashed.
 469   @param[in]   DataSize    Size of Data buffer in bytes.
 470   @param[out]  HashValue   Pointer to a buffer that receives the SHA-256 digest
 471                            value (32 bytes).
 472
 473   @retval TRUE   SHA-256 digest computation succeeded.
 474   @retval FALSE  SHA-256 digest computation failed.
 475   @retval FALSE  This interface is not supported.
 476
 477 **/
 478 BOOLEAN
 479 EFIAPI
 480 Sha256HashAll (
 481   IN   CONST VOID  *Data,
 482   IN   UINTN       DataSize,
 483   OUT  UINT8       *HashValue
 484   );
 485
 486 /**
 487   Retrieves the size, in bytes, of the context buffer required for SHA-384 hash operations.
 488
 489   @return  The size, in bytes, of the context buffer required for SHA-384 hash operations.
 490
 491 **/
 492 UINTN
 493 EFIAPI
 494 Sha384GetContextSize (
 495   VOID
 496   );
 497
 498 /**
 499   Initializes user-supplied memory pointed by Sha384Context as SHA-384 hash context for
 500   subsequent use.
 501
 502   If Sha384Context is NULL, then return FALSE.
 503
 504   @param[out]  Sha384Context  Pointer to SHA-384 context being initialized.
 505
 506   @retval TRUE   SHA-384 context initialization succeeded.
 507   @retval FALSE  SHA-384 context initialization failed.
 508
 509 **/
 510 BOOLEAN
 511 EFIAPI
 512 Sha384Init (
 513   OUT  VOID  *Sha384Context
 514   );
 515
 516 /**
 517   Makes a copy of an existing SHA-384 context.
 518
 519   If Sha384Context is NULL, then return FALSE.
 520   If NewSha384Context is NULL, then return FALSE.
 521   If this interface is not supported, then return FALSE.
 522
 523   @param[in]  Sha384Context     Pointer to SHA-384 context being copied.
 524   @param[out] NewSha384Context  Pointer to new SHA-384 context.
 525
 526   @retval TRUE   SHA-384 context copy succeeded.
 527   @retval FALSE  SHA-384 context copy failed.
 528   @retval FALSE  This interface is not supported.
 529
 530 **/
 531 BOOLEAN
 532 EFIAPI
 533 Sha384Duplicate (
 534   IN   CONST VOID  *Sha384Context,
 535   OUT  VOID        *NewSha384Context
 536   );
 537
 538 /**
 539   Digests the input data and updates SHA-384 context.
 540
 541   This function performs SHA-384 digest on a data buffer of the specified size.
 542   It can be called multiple times to compute the digest of long or discontinuous data streams.
 543   SHA-384 context should be already correctly initialized by Sha384Init(), and should not be finalized
 544   by Sha384Final(). Behavior with invalid context is undefined.
 545
 546   If Sha384Context is NULL, then return FALSE.
 547
 548   @param[in, out]  Sha384Context  Pointer to the SHA-384 context.
 549   @param[in]       Data           Pointer to the buffer containing the data to be hashed.
 550   @param[in]       DataSize       Size of Data buffer in bytes.
 551
 552   @retval TRUE   SHA-384 data digest succeeded.
 553   @retval FALSE  SHA-384 data digest failed.
 554
 555 **/
 556 BOOLEAN
 557 EFIAPI
 558 Sha384Update (
 559   IN OUT  VOID        *Sha384Context,
 560   IN      CONST VOID  *Data,
 561   IN      UINTN       DataSize
 562   );
 563
 564 /**
 565   Completes computation of the SHA-384 digest value.
 566
 567   This function completes SHA-384 hash computation and retrieves the digest value into
 568   the specified memory. After this function has been called, the SHA-384 context cannot
 569   be used again.
 570   SHA-384 context should be already correctly initialized by Sha384Init(), and should not be
 571   finalized by Sha384Final(). Behavior with invalid SHA-384 context is undefined.
 572
 573   If Sha384Context is NULL, then return FALSE.
 574   If HashValue is NULL, then return FALSE.
 575
 576   @param[in, out]  Sha384Context  Pointer to the SHA-384 context.
 577   @param[out]      HashValue      Pointer to a buffer that receives the SHA-384 digest
 578                                   value (48 bytes).
 579
 580   @retval TRUE   SHA-384 digest computation succeeded.
 581   @retval FALSE  SHA-384 digest computation failed.
 582
 583 **/
 584 BOOLEAN
 585 EFIAPI
 586 Sha384Final (
 587   IN OUT  VOID   *Sha384Context,
 588   OUT     UINT8  *HashValue
 589   );
 590
 591 /**
 592   Computes the SHA-384 message digest of a input data buffer.
 593
 594   This function performs the SHA-384 message digest of a given data buffer, and places
 595   the digest value into the specified memory.
 596
 597   If this interface is not supported, then return FALSE.
 598
 599   @param[in]   Data        Pointer to the buffer containing the data to be hashed.
 600   @param[in]   DataSize    Size of Data buffer in bytes.
 601   @param[out]  HashValue   Pointer to a buffer that receives the SHA-384 digest
 602                            value (48 bytes).
 603
 604   @retval TRUE   SHA-384 digest computation succeeded.
 605   @retval FALSE  SHA-384 digest computation failed.
 606   @retval FALSE  This interface is not supported.
 607
 608 **/
 609 BOOLEAN
 610 EFIAPI
 611 Sha384HashAll (
 612   IN   CONST VOID  *Data,
 613   IN   UINTN       DataSize,
 614   OUT  UINT8       *HashValue
 615   );
 616
 617 /**
 618   Retrieves the size, in bytes, of the context buffer required for SHA-512 hash operations.
 619
 620   @return  The size, in bytes, of the context buffer required for SHA-512 hash operations.
 621
 622 **/
 623 UINTN
 624 EFIAPI
 625 Sha512GetContextSize (
 626   VOID
 627   );
 628
 629 /**
 630   Initializes user-supplied memory pointed by Sha512Context as SHA-512 hash context for
 631   subsequent use.
 632
 633   If Sha512Context is NULL, then return FALSE.
 634
 635   @param[out]  Sha512Context  Pointer to SHA-512 context being initialized.
 636
 637   @retval TRUE   SHA-512 context initialization succeeded.
 638   @retval FALSE  SHA-512 context initialization failed.
 639
 640 **/
 641 BOOLEAN
 642 EFIAPI
 643 Sha512Init (
 644   OUT  VOID  *Sha512Context
 645   );
 646
 647 /**
 648   Makes a copy of an existing SHA-512 context.
 649
 650   If Sha512Context is NULL, then return FALSE.
 651   If NewSha512Context is NULL, then return FALSE.
 652   If this interface is not supported, then return FALSE.
 653
 654   @param[in]  Sha512Context     Pointer to SHA-512 context being copied.
 655   @param[out] NewSha512Context  Pointer to new SHA-512 context.
 656
 657   @retval TRUE   SHA-512 context copy succeeded.
 658   @retval FALSE  SHA-512 context copy failed.
 659   @retval FALSE  This interface is not supported.
 660
 661 **/
 662 BOOLEAN
 663 EFIAPI
 664 Sha512Duplicate (
 665   IN   CONST VOID  *Sha512Context,
 666   OUT  VOID        *NewSha512Context
 667   );
 668
 669 /**
 670   Digests the input data and updates SHA-512 context.
 671
 672   This function performs SHA-512 digest on a data buffer of the specified size.
 673   It can be called multiple times to compute the digest of long or discontinuous data streams.
 674   SHA-512 context should be already correctly initialized by Sha512Init(), and should not be finalized
 675   by Sha512Final(). Behavior with invalid context is undefined.
 676
 677   If Sha512Context is NULL, then return FALSE.
 678
 679   @param[in, out]  Sha512Context  Pointer to the SHA-512 context.
 680   @param[in]       Data           Pointer to the buffer containing the data to be hashed.
 681   @param[in]       DataSize       Size of Data buffer in bytes.
 682
 683   @retval TRUE   SHA-512 data digest succeeded.
 684   @retval FALSE  SHA-512 data digest failed.
 685
 686 **/
 687 BOOLEAN
 688 EFIAPI
 689 Sha512Update (
 690   IN OUT  VOID        *Sha512Context,
 691   IN      CONST VOID  *Data,
 692   IN      UINTN       DataSize
 693   );
 694
 695 /**
 696   Completes computation of the SHA-512 digest value.
 697
 698   This function completes SHA-512 hash computation and retrieves the digest value into
 699   the specified memory. After this function has been called, the SHA-512 context cannot
 700   be used again.
 701   SHA-512 context should be already correctly initialized by Sha512Init(), and should not be
 702   finalized by Sha512Final(). Behavior with invalid SHA-512 context is undefined.
 703
 704   If Sha512Context is NULL, then return FALSE.
 705   If HashValue is NULL, then return FALSE.
 706
 707   @param[in, out]  Sha512Context  Pointer to the SHA-512 context.
 708   @param[out]      HashValue      Pointer to a buffer that receives the SHA-512 digest
 709                                   value (64 bytes).
 710
 711   @retval TRUE   SHA-512 digest computation succeeded.
 712   @retval FALSE  SHA-512 digest computation failed.
 713
 714 **/
 715 BOOLEAN
 716 EFIAPI
 717 Sha512Final (
 718   IN OUT  VOID   *Sha512Context,
 719   OUT     UINT8  *HashValue
 720   );
 721
 722 /**
 723   Computes the SHA-512 message digest of a input data buffer.
 724
 725   This function performs the SHA-512 message digest of a given data buffer, and places
 726   the digest value into the specified memory.
 727
 728   If this interface is not supported, then return FALSE.
 729
 730   @param[in]   Data        Pointer to the buffer containing the data to be hashed.
 731   @param[in]   DataSize    Size of Data buffer in bytes.
 732   @param[out]  HashValue   Pointer to a buffer that receives the SHA-512 digest
 733                            value (64 bytes).
 734
 735   @retval TRUE   SHA-512 digest computation succeeded.
 736   @retval FALSE  SHA-512 digest computation failed.
 737   @retval FALSE  This interface is not supported.
 738
 739 **/
 740 BOOLEAN
 741 EFIAPI
 742 Sha512HashAll (
 743   IN   CONST VOID  *Data,
 744   IN   UINTN       DataSize,
 745   OUT  UINT8       *HashValue
 746   );
 747
 748 /**
 749   Retrieves the size, in bytes, of the context buffer required for SM3 hash operations.
 750
 751   @return  The size, in bytes, of the context buffer required for SM3 hash operations.
 752
 753 **/
 754 UINTN
 755 EFIAPI
 756 Sm3GetContextSize (
 757   VOID
 758   );
 759
 760 /**
 761   Initializes user-supplied memory pointed by Sm3Context as SM3 hash context for
 762   subsequent use.
 763
 764   If Sm3Context is NULL, then return FALSE.
 765
 766   @param[out]  Sm3Context  Pointer to SM3 context being initialized.
 767
 768   @retval TRUE   SM3 context initialization succeeded.
 769   @retval FALSE  SM3 context initialization failed.
 770
 771 **/
 772 BOOLEAN
 773 EFIAPI
 774 Sm3Init (
 775   OUT  VOID  *Sm3Context
 776   );
 777
 778 /**
 779   Makes a copy of an existing SM3 context.
 780
 781   If Sm3Context is NULL, then return FALSE.
 782   If NewSm3Context is NULL, then return FALSE.
 783   If this interface is not supported, then return FALSE.
 784
 785   @param[in]  Sm3Context     Pointer to SM3 context being copied.
 786   @param[out] NewSm3Context  Pointer to new SM3 context.
 787
 788   @retval TRUE   SM3 context copy succeeded.
 789   @retval FALSE  SM3 context copy failed.
 790   @retval FALSE  This interface is not supported.
 791
 792 **/
 793 BOOLEAN
 794 EFIAPI
 795 Sm3Duplicate (
 796   IN   CONST VOID  *Sm3Context,
 797   OUT  VOID        *NewSm3Context
 798   );
 799
 800 /**
 801   Digests the input data and updates SM3 context.
 802
 803   This function performs SM3 digest on a data buffer of the specified size.
 804   It can be called multiple times to compute the digest of long or discontinuous data streams.
 805   SM3 context should be already correctly initialized by Sm3Init(), and should not be finalized
 806   by Sm3Final(). Behavior with invalid context is undefined.
 807
 808   If Sm3Context is NULL, then return FALSE.
 809
 810   @param[in, out]  Sm3Context     Pointer to the SM3 context.
 811   @param[in]       Data           Pointer to the buffer containing the data to be hashed.
 812   @param[in]       DataSize       Size of Data buffer in bytes.
 813
 814   @retval TRUE   SM3 data digest succeeded.
 815   @retval FALSE  SM3 data digest failed.
 816
 817 **/
 818 BOOLEAN
 819 EFIAPI
 820 Sm3Update (
 821   IN OUT  VOID        *Sm3Context,
 822   IN      CONST VOID  *Data,
 823   IN      UINTN       DataSize
 824   );
 825
 826 /**
 827   Completes computation of the SM3 digest value.
 828
 829   This function completes SM3 hash computation and retrieves the digest value into
 830   the specified memory. After this function has been called, the SM3 context cannot
 831   be used again.
 832   SM3 context should be already correctly initialized by Sm3Init(), and should not be
 833   finalized by Sm3Final(). Behavior with invalid SM3 context is undefined.
 834
 835   If Sm3Context is NULL, then return FALSE.
 836   If HashValue is NULL, then return FALSE.
 837
 838   @param[in, out]  Sm3Context     Pointer to the SM3 context.
 839   @param[out]      HashValue      Pointer to a buffer that receives the SM3 digest
 840                                   value (32 bytes).
 841
 842   @retval TRUE   SM3 digest computation succeeded.
 843   @retval FALSE  SM3 digest computation failed.
 844
 845 **/
 846 BOOLEAN
 847 EFIAPI
 848 Sm3Final (
 849   IN OUT  VOID   *Sm3Context,
 850   OUT     UINT8  *HashValue
 851   );
 852
 853 /**
 854   Computes the SM3 message digest of a input data buffer.
 855
 856   This function performs the SM3 message digest of a given data buffer, and places
 857   the digest value into the specified memory.
 858
 859   If this interface is not supported, then return FALSE.
 860
 861   @param[in]   Data        Pointer to the buffer containing the data to be hashed.
 862   @param[in]   DataSize    Size of Data buffer in bytes.
 863   @param[out]  HashValue   Pointer to a buffer that receives the SM3 digest
 864                            value (32 bytes).
 865
 866   @retval TRUE   SM3 digest computation succeeded.
 867   @retval FALSE  SM3 digest computation failed.
 868   @retval FALSE  This interface is not supported.
 869
 870 **/
 871 BOOLEAN
 872 EFIAPI
 873 Sm3HashAll (
 874   IN   CONST VOID  *Data,
 875   IN   UINTN       DataSize,
 876   OUT  UINT8       *HashValue
 877   );
 878
 879 //=====================================================================================
 880 //    MAC (Message Authentication Code) Primitive
 881 //=====================================================================================
 882
 883 /**
 884   Allocates and initializes one HMAC_CTX context for subsequent HMAC-SHA256 use.
 885
 886   @return  Pointer to the HMAC_CTX context that has been initialized.
 887            If the allocations fails, HmacSha256New() returns NULL.
 888
 889 **/
 890 VOID *
 891 EFIAPI
 892 HmacSha256New (
 893   VOID
 894   );
 895
 896 /**
 897   Release the specified HMAC_CTX context.
 898
 899   @param[in]  HmacSha256Ctx  Pointer to the HMAC_CTX context to be released.
 900
 901 **/
 902 VOID
 903 EFIAPI
 904 HmacSha256Free (
 905   IN  VOID  *HmacSha256Ctx
 906   );
 907
 908 /**
 909   Set user-supplied key for subsequent use. It must be done before any
 910   calling to HmacSha256Update().
 911
 912   If HmacSha256Context is NULL, then return FALSE.
 913   If this interface is not supported, then return FALSE.
 914
 915   @param[out]  HmacSha256Context  Pointer to HMAC-SHA256 context.
 916   @param[in]   Key                Pointer to the user-supplied key.
 917   @param[in]   KeySize            Key size in bytes.
 918
 919   @retval TRUE   The Key is set successfully.
 920   @retval FALSE  The Key is set unsuccessfully.
 921   @retval FALSE  This interface is not supported.
 922
 923 **/
 924 BOOLEAN
 925 EFIAPI
 926 HmacSha256SetKey (
 927   OUT  VOID         *HmacSha256Context,
 928   IN   CONST UINT8  *Key,
 929   IN   UINTN        KeySize
 930   );
 931
 932 /**
 933   Makes a copy of an existing HMAC-SHA256 context.
 934
 935   If HmacSha256Context is NULL, then return FALSE.
 936   If NewHmacSha256Context is NULL, then return FALSE.
 937   If this interface is not supported, then return FALSE.
 938
 939   @param[in]  HmacSha256Context     Pointer to HMAC-SHA256 context being copied.
 940   @param[out] NewHmacSha256Context  Pointer to new HMAC-SHA256 context.
 941
 942   @retval TRUE   HMAC-SHA256 context copy succeeded.
 943   @retval FALSE  HMAC-SHA256 context copy failed.
 944   @retval FALSE  This interface is not supported.
 945
 946 **/
 947 BOOLEAN
 948 EFIAPI
 949 HmacSha256Duplicate (
 950   IN   CONST VOID  *HmacSha256Context,
 951   OUT  VOID        *NewHmacSha256Context
 952   );
 953
 954 /**
 955   Digests the input data and updates HMAC-SHA256 context.
 956
 957   This function performs HMAC-SHA256 digest on a data buffer of the specified size.
 958   It can be called multiple times to compute the digest of long or discontinuous data streams.
 959   HMAC-SHA256 context should be initialized by HmacSha256New(), and should not be finalized
 960   by HmacSha256Final(). Behavior with invalid context is undefined.
 961
 962   If HmacSha256Context is NULL, then return FALSE.
 963   If this interface is not supported, then return FALSE.
 964
 965   @param[in, out]  HmacSha256Context Pointer to the HMAC-SHA256 context.
 966   @param[in]       Data              Pointer to the buffer containing the data to be digested.
 967   @param[in]       DataSize          Size of Data buffer in bytes.
 968
 969   @retval TRUE   HMAC-SHA256 data digest succeeded.
 970   @retval FALSE  HMAC-SHA256 data digest failed.
 971   @retval FALSE  This interface is not supported.
 972
 973 **/
 974 BOOLEAN
 975 EFIAPI
 976 HmacSha256Update (
 977   IN OUT  VOID        *HmacSha256Context,
 978   IN      CONST VOID  *Data,
 979   IN      UINTN       DataSize
 980   );
 981
 982 /**
 983   Completes computation of the HMAC-SHA256 digest value.
 984
 985   This function completes HMAC-SHA256 hash computation and retrieves the digest value into
 986   the specified memory. After this function has been called, the HMAC-SHA256 context cannot
 987   be used again.
 988   HMAC-SHA256 context should be initialized by HmacSha256New(), and should not be finalized
 989   by HmacSha256Final(). Behavior with invalid HMAC-SHA256 context is undefined.
 990
 991   If HmacSha256Context is NULL, then return FALSE.
 992   If HmacValue is NULL, then return FALSE.
 993   If this interface is not supported, then return FALSE.
 994
 995   @param[in, out]  HmacSha256Context  Pointer to the HMAC-SHA256 context.
 996   @param[out]      HmacValue          Pointer to a buffer that receives the HMAC-SHA256 digest
 997                                       value (32 bytes).
 998
 999   @retval TRUE   HMAC-SHA256 digest computation succeeded.
1000   @retval FALSE  HMAC-SHA256 digest computation failed.
1001   @retval FALSE  This interface is not supported.
1002
1003 **/
1004 BOOLEAN
1005 EFIAPI
1006 HmacSha256Final (
1007   IN OUT  VOID   *HmacSha256Context,
1008   OUT     UINT8  *HmacValue
1009   );
1010
1011 //=====================================================================================
1012 //    Symmetric Cryptography Primitive
1013 //=====================================================================================
1014
1015 /**
1016   Retrieves the size, in bytes, of the context buffer required for AES operations.
1017
1018   If this interface is not supported, then return zero.
1019
1020   @return  The size, in bytes, of the context buffer required for AES operations.
1021   @retval  0   This interface is not supported.
1022
1023 **/
1024 UINTN
1025 EFIAPI
1026 AesGetContextSize (
1027   VOID
1028   );
1029
1030 /**
1031   Initializes user-supplied memory as AES context for subsequent use.
1032
1033   This function initializes user-supplied memory pointed by AesContext as AES context.
1034   In addition, it sets up all AES key materials for subsequent encryption and decryption
1035   operations.
1036   There are 3 options for key length, 128 bits, 192 bits, and 256 bits.
1037
1038   If AesContext is NULL, then return FALSE.
1039   If Key is NULL, then return FALSE.
1040   If KeyLength is not valid, then return FALSE.
1041   If this interface is not supported, then return FALSE.
1042
1043   @param[out]  AesContext  Pointer to AES context being initialized.
1044   @param[in]   Key         Pointer to the user-supplied AES key.
1045   @param[in]   KeyLength   Length of AES key in bits.
1046
1047   @retval TRUE   AES context initialization succeeded.
1048   @retval FALSE  AES context initialization failed.
1049   @retval FALSE  This interface is not supported.
1050
1051 **/
1052 BOOLEAN
1053 EFIAPI
1054 AesInit (
1055   OUT  VOID         *AesContext,
1056   IN   CONST UINT8  *Key,
1057   IN   UINTN        KeyLength
1058   );
1059
1060 /**
1061   Performs AES encryption on a data buffer of the specified size in CBC mode.
1062
1063   This function performs AES encryption on data buffer pointed by Input, of specified
1064   size of InputSize, in CBC mode.
1065   InputSize must be multiple of block size (16 bytes). This function does not perform
1066   padding. Caller must perform padding, if necessary, to ensure valid input data size.
1067   Initialization vector should be one block size (16 bytes).
1068   AesContext should be already correctly initialized by AesInit(). Behavior with
1069   invalid AES context is undefined.
1070
1071   If AesContext is NULL, then return FALSE.
1072   If Input is NULL, then return FALSE.
1073   If InputSize is not multiple of block size (16 bytes), then return FALSE.
1074   If Ivec is NULL, then return FALSE.
1075   If Output is NULL, then return FALSE.
1076   If this interface is not supported, then return FALSE.
1077
1078   @param[in]   AesContext  Pointer to the AES context.
1079   @param[in]   Input       Pointer to the buffer containing the data to be encrypted.
1080   @param[in]   InputSize   Size of the Input buffer in bytes.
1081   @param[in]   Ivec        Pointer to initialization vector.
1082   @param[out]  Output      Pointer to a buffer that receives the AES encryption output.
1083
1084   @retval TRUE   AES encryption succeeded.
1085   @retval FALSE  AES encryption failed.
1086   @retval FALSE  This interface is not supported.
1087
1088 **/
1089 BOOLEAN
1090 EFIAPI
1091 AesCbcEncrypt (
1092   IN   VOID         *AesContext,
1093   IN   CONST UINT8  *Input,
1094   IN   UINTN        InputSize,
1095   IN   CONST UINT8  *Ivec,
1096   OUT  UINT8        *Output
1097   );
1098
1099 /**
1100   Performs AES decryption on a data buffer of the specified size in CBC mode.
1101
1102   This function performs AES decryption on data buffer pointed by Input, of specified
1103   size of InputSize, in CBC mode.
1104   InputSize must be multiple of block size (16 bytes). This function does not perform
1105   padding. Caller must perform padding, if necessary, to ensure valid input data size.
1106   Initialization vector should be one block size (16 bytes).
1107   AesContext should be already correctly initialized by AesInit(). Behavior with
1108   invalid AES context is undefined.
1109
1110   If AesContext is NULL, then return FALSE.
1111   If Input is NULL, then return FALSE.
1112   If InputSize is not multiple of block size (16 bytes), then return FALSE.
1113   If Ivec is NULL, then return FALSE.
1114   If Output is NULL, then return FALSE.
1115   If this interface is not supported, then return FALSE.
1116
1117   @param[in]   AesContext  Pointer to the AES context.
1118   @param[in]   Input       Pointer to the buffer containing the data to be encrypted.
1119   @param[in]   InputSize   Size of the Input buffer in bytes.
1120   @param[in]   Ivec        Pointer to initialization vector.
1121   @param[out]  Output      Pointer to a buffer that receives the AES encryption output.
1122
1123   @retval TRUE   AES decryption succeeded.
1124   @retval FALSE  AES decryption failed.
1125   @retval FALSE  This interface is not supported.
1126
1127 **/
1128 BOOLEAN
1129 EFIAPI
1130 AesCbcDecrypt (
1131   IN   VOID         *AesContext,
1132   IN   CONST UINT8  *Input,
1133   IN   UINTN        InputSize,
1134   IN   CONST UINT8  *Ivec,
1135   OUT  UINT8        *Output
1136   );
1137
1138 //=====================================================================================
1139 //    Asymmetric Cryptography Primitive
1140 //=====================================================================================
1141
1142 /**
1143   Allocates and initializes one RSA context for subsequent use.
1144
1145   @return  Pointer to the RSA context that has been initialized.
1146            If the allocations fails, RsaNew() returns NULL.
1147
1148 **/
1149 VOID *
1150 EFIAPI
1151 RsaNew (
1152   VOID
1153   );
1154
1155 /**
1156   Release the specified RSA context.
1157
1158   If RsaContext is NULL, then return FALSE.
1159
1160   @param[in]  RsaContext  Pointer to the RSA context to be released.
1161
1162 **/
1163 VOID
1164 EFIAPI
1165 RsaFree (
1166   IN  VOID  *RsaContext
1167   );
1168
1169 /**
1170   Sets the tag-designated key component into the established RSA context.
1171
1172   This function sets the tag-designated RSA key component into the established
1173   RSA context from the user-specified non-negative integer (octet string format
1174   represented in RSA PKCS#1).
1175   If BigNumber is NULL, then the specified key component in RSA context is cleared.
1176
1177   If RsaContext is NULL, then return FALSE.
1178
1179   @param[in, out]  RsaContext  Pointer to RSA context being set.
1180   @param[in]       KeyTag      Tag of RSA key component being set.
1181   @param[in]       BigNumber   Pointer to octet integer buffer.
1182                                If NULL, then the specified key component in RSA
1183                                context is cleared.
1184   @param[in]       BnSize      Size of big number buffer in bytes.
1185                                If BigNumber is NULL, then it is ignored.
1186
1187   @retval  TRUE   RSA key component was set successfully.
1188   @retval  FALSE  Invalid RSA key component tag.
1189
1190 **/
1191 BOOLEAN
1192 EFIAPI
1193 RsaSetKey (
1194   IN OUT  VOID         *RsaContext,
1195   IN      RSA_KEY_TAG  KeyTag,
1196   IN      CONST UINT8  *BigNumber,
1197   IN      UINTN        BnSize
1198   );
1199
1200 /**
1201   Gets the tag-designated RSA key component from the established RSA context.
1202
1203   This function retrieves the tag-designated RSA key component from the
1204   established RSA context as a non-negative integer (octet string format
1205   represented in RSA PKCS#1).
1206   If specified key component has not been set or has been cleared, then returned
1207   BnSize is set to 0.
1208   If the BigNumber buffer is too small to hold the contents of the key, FALSE
1209   is returned and BnSize is set to the required buffer size to obtain the key.
1210
1211   If RsaContext is NULL, then return FALSE.
1212   If BnSize is NULL, then return FALSE.
1213   If BnSize is large enough but BigNumber is NULL, then return FALSE.
1214   If this interface is not supported, then return FALSE.
1215
1216   @param[in, out]  RsaContext  Pointer to RSA context being set.
1217   @param[in]       KeyTag      Tag of RSA key component being set.
1218   @param[out]      BigNumber   Pointer to octet integer buffer.
1219   @param[in, out]  BnSize      On input, the size of big number buffer in bytes.
1220                                On output, the size of data returned in big number buffer in bytes.
1221
1222   @retval  TRUE   RSA key component was retrieved successfully.
1223   @retval  FALSE  Invalid RSA key component tag.
1224   @retval  FALSE  BnSize is too small.
1225   @retval  FALSE  This interface is not supported.
1226
1227 **/
1228 BOOLEAN
1229 EFIAPI
1230 RsaGetKey (
1231   IN OUT  VOID         *RsaContext,
1232   IN      RSA_KEY_TAG  KeyTag,
1233   OUT     UINT8        *BigNumber,
1234   IN OUT  UINTN        *BnSize
1235   );
1236
1237 /**
1238   Generates RSA key components.
1239
1240   This function generates RSA key components. It takes RSA public exponent E and
1241   length in bits of RSA modulus N as input, and generates all key components.
1242   If PublicExponent is NULL, the default RSA public exponent (0x10001) will be used.
1243
1244   Before this function can be invoked, pseudorandom number generator must be correctly
1245   initialized by RandomSeed().
1246
1247   If RsaContext is NULL, then return FALSE.
1248   If this interface is not supported, then return FALSE.
1249
1250   @param[in, out]  RsaContext           Pointer to RSA context being set.
1251   @param[in]       ModulusLength        Length of RSA modulus N in bits.
1252   @param[in]       PublicExponent       Pointer to RSA public exponent.
1253   @param[in]       PublicExponentSize   Size of RSA public exponent buffer in bytes.
1254
1255   @retval  TRUE   RSA key component was generated successfully.
1256   @retval  FALSE  Invalid RSA key component tag.
1257   @retval  FALSE  This interface is not supported.
1258
1259 **/
1260 BOOLEAN
1261 EFIAPI
1262 RsaGenerateKey (
1263   IN OUT  VOID         *RsaContext,
1264   IN      UINTN        ModulusLength,
1265   IN      CONST UINT8  *PublicExponent,
1266   IN      UINTN        PublicExponentSize
1267   );
1268
1269 /**
1270   Validates key components of RSA context.
1271   NOTE: This function performs integrity checks on all the RSA key material, so
1272         the RSA key structure must contain all the private key data.
1273
1274   This function validates key components of RSA context in following aspects:
1275   - Whether p is a prime
1276   - Whether q is a prime
1277   - Whether n = p * q
1278   - Whether d*e = 1  mod lcm(p-1,q-1)
1279
1280   If RsaContext is NULL, then return FALSE.
1281   If this interface is not supported, then return FALSE.
1282
1283   @param[in]  RsaContext  Pointer to RSA context to check.
1284
1285   @retval  TRUE   RSA key components are valid.
1286   @retval  FALSE  RSA key components are not valid.
1287   @retval  FALSE  This interface is not supported.
1288
1289 **/
1290 BOOLEAN
1291 EFIAPI
1292 RsaCheckKey (
1293   IN  VOID  *RsaContext
1294   );
1295
1296 /**
1297   Carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme.
1298
1299   This function carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme defined in
1300   RSA PKCS#1.
1301   If the Signature buffer is too small to hold the contents of signature, FALSE
1302   is returned and SigSize is set to the required buffer size to obtain the signature.
1303
1304   If RsaContext is NULL, then return FALSE.
1305   If MessageHash is NULL, then return FALSE.
1306   If HashSize is not equal to the size of MD5, SHA-1 or SHA-256 digest, then return FALSE.
1307   If SigSize is large enough but Signature is NULL, then return FALSE.
1308   If this interface is not supported, then return FALSE.
1309
1310   @param[in]      RsaContext   Pointer to RSA context for signature generation.
1311   @param[in]      MessageHash  Pointer to octet message hash to be signed.
1312   @param[in]      HashSize     Size of the message hash in bytes.
1313   @param[out]     Signature    Pointer to buffer to receive RSA PKCS1-v1_5 signature.
1314   @param[in, out] SigSize      On input, the size of Signature buffer in bytes.
1315                                On output, the size of data returned in Signature buffer in bytes.
1316
1317   @retval  TRUE   Signature successfully generated in PKCS1-v1_5.
1318   @retval  FALSE  Signature generation failed.
1319   @retval  FALSE  SigSize is too small.
1320   @retval  FALSE  This interface is not supported.
1321
1322 **/
1323 BOOLEAN
1324 EFIAPI
1325 RsaPkcs1Sign (
1326   IN      VOID         *RsaContext,
1327   IN      CONST UINT8  *MessageHash,
1328   IN      UINTN        HashSize,
1329   OUT     UINT8        *Signature,
1330   IN OUT  UINTN        *SigSize
1331   );
1332
1333 /**
1334   Verifies the RSA-SSA signature with EMSA-PKCS1-v1_5 encoding scheme defined in
1335   RSA PKCS#1.
1336
1337   If RsaContext is NULL, then return FALSE.
1338   If MessageHash is NULL, then return FALSE.
1339   If Signature is NULL, then return FALSE.
1340   If HashSize is not equal to the size of MD5, SHA-1, SHA-256 digest, then return FALSE.
1341
1342   @param[in]  RsaContext   Pointer to RSA context for signature verification.
1343   @param[in]  MessageHash  Pointer to octet message hash to be checked.
1344   @param[in]  HashSize     Size of the message hash in bytes.
1345   @param[in]  Signature    Pointer to RSA PKCS1-v1_5 signature to be verified.
1346   @param[in]  SigSize      Size of signature in bytes.
1347
1348   @retval  TRUE   Valid signature encoded in PKCS1-v1_5.
1349   @retval  FALSE  Invalid signature or invalid RSA context.
1350
1351 **/
1352 BOOLEAN
1353 EFIAPI
1354 RsaPkcs1Verify (
1355   IN  VOID         *RsaContext,
1356   IN  CONST UINT8  *MessageHash,
1357   IN  UINTN        HashSize,
1358   IN  CONST UINT8  *Signature,
1359   IN  UINTN        SigSize
1360   );
1361
1362 /**
1363   Retrieve the RSA Private Key from the password-protected PEM key data.
1364
1365   If PemData is NULL, then return FALSE.
1366   If RsaContext is NULL, then return FALSE.
1367   If this interface is not supported, then return FALSE.
1368
1369   @param[in]  PemData      Pointer to the PEM-encoded key data to be retrieved.
1370   @param[in]  PemSize      Size of the PEM key data in bytes.
1371   @param[in]  Password     NULL-terminated passphrase used for encrypted PEM key data.
1372   @param[out] RsaContext   Pointer to new-generated RSA context which contain the retrieved
1373                            RSA private key component. Use RsaFree() function to free the
1374                            resource.
1375
1376   @retval  TRUE   RSA Private Key was retrieved successfully.
1377   @retval  FALSE  Invalid PEM key data or incorrect password.
1378   @retval  FALSE  This interface is not supported.
1379
1380 **/
1381 BOOLEAN
1382 EFIAPI
1383 RsaGetPrivateKeyFromPem (
1384   IN   CONST UINT8  *PemData,
1385   IN   UINTN        PemSize,
1386   IN   CONST CHAR8  *Password,
1387   OUT  VOID         **RsaContext
1388   );
1389
1390 /**
1391   Retrieve the RSA Public Key from one DER-encoded X509 certificate.
1392
1393   If Cert is NULL, then return FALSE.
1394   If RsaContext is NULL, then return FALSE.
1395   If this interface is not supported, then return FALSE.
1396
1397   @param[in]  Cert         Pointer to the DER-encoded X509 certificate.
1398   @param[in]  CertSize     Size of the X509 certificate in bytes.
1399   @param[out] RsaContext   Pointer to new-generated RSA context which contain the retrieved
1400                            RSA public key component. Use RsaFree() function to free the
1401                            resource.
1402
1403   @retval  TRUE   RSA Public Key was retrieved successfully.
1404   @retval  FALSE  Fail to retrieve RSA public key from X509 certificate.
1405   @retval  FALSE  This interface is not supported.
1406
1407 **/
1408 BOOLEAN
1409 EFIAPI
1410 RsaGetPublicKeyFromX509 (
1411   IN   CONST UINT8  *Cert,
1412   IN   UINTN        CertSize,
1413   OUT  VOID         **RsaContext
1414   );
1415
1416 /**
1417   Retrieve the subject bytes from one X.509 certificate.
1418
1419   If Cert is NULL, then return FALSE.
1420   If SubjectSize is NULL, then return FALSE.
1421   If this interface is not supported, then return FALSE.
1422
1423   @param[in]      Cert         Pointer to the DER-encoded X509 certificate.
1424   @param[in]      CertSize     Size of the X509 certificate in bytes.
1425   @param[out]     CertSubject  Pointer to the retrieved certificate subject bytes.
1426   @param[in, out] SubjectSize  The size in bytes of the CertSubject buffer on input,
1427                                and the size of buffer returned CertSubject on output.
1428
1429   @retval  TRUE   The certificate subject retrieved successfully.
1430   @retval  FALSE  Invalid certificate, or the SubjectSize is too small for the result.
1431                   The SubjectSize will be updated with the required size.
1432   @retval  FALSE  This interface is not supported.
1433
1434 **/
1435 BOOLEAN
1436 EFIAPI
1437 X509GetSubjectName (
1438   IN      CONST UINT8  *Cert,
1439   IN      UINTN        CertSize,
1440   OUT     UINT8        *CertSubject,
1441   IN OUT  UINTN        *SubjectSize
1442   );
1443
1444 /**
1445   Retrieve the common name (CN) string from one X.509 certificate.
1446
1447   @param[in]      Cert             Pointer to the DER-encoded X509 certificate.
1448   @param[in]      CertSize         Size of the X509 certificate in bytes.
1449   @param[out]     CommonName       Buffer to contain the retrieved certificate common
1450                                    name string (UTF8). At most CommonNameSize bytes will be
1451                                    written and the string will be null terminated. May be
1452                                    NULL in order to determine the size buffer needed.
1453   @param[in,out]  CommonNameSize   The size in bytes of the CommonName buffer on input,
1454                                    and the size of buffer returned CommonName on output.
1455                                    If CommonName is NULL then the amount of space needed
1456                                    in buffer (including the final null) is returned.
1457
1458   @retval RETURN_SUCCESS           The certificate CommonName retrieved successfully.
1459   @retval RETURN_INVALID_PARAMETER If Cert is NULL.
1460                                    If CommonNameSize is NULL.
1461                                    If CommonName is not NULL and *CommonNameSize is 0.
1462                                    If Certificate is invalid.
1463   @retval RETURN_NOT_FOUND         If no CommonName entry exists.
1464   @retval RETURN_BUFFER_TOO_SMALL  If the CommonName is NULL. The required buffer size
1465                                    (including the final null) is returned in the
1466                                    CommonNameSize parameter.
1467   @retval RETURN_UNSUPPORTED       The operation is not supported.
1468
1469 **/
1470 RETURN_STATUS
1471 EFIAPI
1472 X509GetCommonName (
1473   IN      CONST UINT8  *Cert,
1474   IN      UINTN        CertSize,
1475   OUT     CHAR8        *CommonName,  OPTIONAL
1476   IN OUT  UINTN        *CommonNameSize
1477   );
1478
1479 /**
1480   Retrieve the organization name (O) string from one X.509 certificate.
1481
1482   @param[in]      Cert             Pointer to the DER-encoded X509 certificate.
1483   @param[in]      CertSize         Size of the X509 certificate in bytes.
1484   @param[out]     NameBuffer       Buffer to contain the retrieved certificate organization
1485                                    name string. At most NameBufferSize bytes will be
1486                                    written and the string will be null terminated. May be
1487                                    NULL in order to determine the size buffer needed.
1488   @param[in,out]  NameBufferSize   The size in bytes of the Name buffer on input,
1489                                    and the size of buffer returned Name on output.
1490                                    If NameBuffer is NULL then the amount of space needed
1491                                    in buffer (including the final null) is returned.
1492
1493   @retval RETURN_SUCCESS           The certificate Organization Name retrieved successfully.
1494   @retval RETURN_INVALID_PARAMETER If Cert is NULL.
1495                                    If NameBufferSize is NULL.
1496                                    If NameBuffer is not NULL and *CommonNameSize is 0.
1497                                    If Certificate is invalid.
1498   @retval RETURN_NOT_FOUND         If no Organization Name entry exists.
1499   @retval RETURN_BUFFER_TOO_SMALL  If the NameBuffer is NULL. The required buffer size
1500                                    (including the final null) is returned in the
1501                                    CommonNameSize parameter.
1502   @retval RETURN_UNSUPPORTED       The operation is not supported.
1503
1504 **/
1505 RETURN_STATUS
1506 EFIAPI
1507 X509GetOrganizationName (
1508   IN      CONST UINT8   *Cert,
1509   IN      UINTN         CertSize,
1510   OUT     CHAR8         *NameBuffer,  OPTIONAL
1511   IN OUT  UINTN         *NameBufferSize
1512   );
1513
1514 /**
1515   Verify one X509 certificate was issued by the trusted CA.
1516
1517   If Cert is NULL, then return FALSE.
1518   If CACert is NULL, then return FALSE.
1519   If this interface is not supported, then return FALSE.
1520
1521   @param[in]      Cert         Pointer to the DER-encoded X509 certificate to be verified.
1522   @param[in]      CertSize     Size of the X509 certificate in bytes.
1523   @param[in]      CACert       Pointer to the DER-encoded trusted CA certificate.
1524   @param[in]      CACertSize   Size of the CA Certificate in bytes.
1525
1526   @retval  TRUE   The certificate was issued by the trusted CA.
1527   @retval  FALSE  Invalid certificate or the certificate was not issued by the given
1528                   trusted CA.
1529   @retval  FALSE  This interface is not supported.
1530
1531 **/
1532 BOOLEAN
1533 EFIAPI
1534 X509VerifyCert (
1535   IN  CONST UINT8  *Cert,
1536   IN  UINTN        CertSize,
1537   IN  CONST UINT8  *CACert,
1538   IN  UINTN        CACertSize
1539   );
1540
1541 /**
1542   Construct a X509 object from DER-encoded certificate data.
1543
1544   If Cert is NULL, then return FALSE.
1545   If SingleX509Cert is NULL, then return FALSE.
1546   If this interface is not supported, then return FALSE.
1547
1548   @param[in]  Cert            Pointer to the DER-encoded certificate data.
1549   @param[in]  CertSize        The size of certificate data in bytes.
1550   @param[out] SingleX509Cert  The generated X509 object.
1551
1552   @retval     TRUE            The X509 object generation succeeded.
1553   @retval     FALSE           The operation failed.
1554   @retval     FALSE           This interface is not supported.
1555
1556 **/
1557 BOOLEAN
1558 EFIAPI
1559 X509ConstructCertificate (
1560   IN   CONST UINT8  *Cert,
1561   IN   UINTN        CertSize,
1562   OUT  UINT8        **SingleX509Cert
1563   );
1564
1565 /**
1566   Construct a X509 stack object from a list of DER-encoded certificate data.
1567
1568   If X509Stack is NULL, then return FALSE.
1569   If this interface is not supported, then return FALSE.
1570
1571   @param[in, out]  X509Stack  On input, pointer to an existing or NULL X509 stack object.
1572                               On output, pointer to the X509 stack object with new
1573                               inserted X509 certificate.
1574   @param[in]       Args       VA_LIST marker for the variable argument list.
1575                               A list of DER-encoded single certificate data followed
1576                               by certificate size. A NULL terminates the list. The
1577                               pairs are the arguments to X509ConstructCertificate().
1578
1579   @retval     TRUE            The X509 stack construction succeeded.
1580   @retval     FALSE           The construction operation failed.
1581   @retval     FALSE           This interface is not supported.
1582
1583 **/
1584 BOOLEAN
1585 EFIAPI
1586 X509ConstructCertificateStackV (
1587   IN OUT  UINT8    **X509Stack,
1588   IN      VA_LIST  Args
1589   );
1590
1591 /**
1592   Construct a X509 stack object from a list of DER-encoded certificate data.
1593
1594   If X509Stack is NULL, then return FALSE.
1595   If this interface is not supported, then return FALSE.
1596
1597   @param[in, out]  X509Stack  On input, pointer to an existing or NULL X509 stack object.
1598                               On output, pointer to the X509 stack object with new
1599                               inserted X509 certificate.
1600   @param           ...        A list of DER-encoded single certificate data followed
1601                               by certificate size. A NULL terminates the list. The
1602                               pairs are the arguments to X509ConstructCertificate().
1603
1604   @retval     TRUE            The X509 stack construction succeeded.
1605   @retval     FALSE           The construction operation failed.
1606   @retval     FALSE           This interface is not supported.
1607
1608 **/
1609 BOOLEAN
1610 EFIAPI
1611 X509ConstructCertificateStack (
1612   IN OUT  UINT8  **X509Stack,
1613   ...
1614   );
1615
1616 /**
1617   Release the specified X509 object.
1618
1619   If the interface is not supported, then ASSERT().
1620
1621   @param[in]  X509Cert  Pointer to the X509 object to be released.
1622
1623 **/
1624 VOID
1625 EFIAPI
1626 X509Free (
1627   IN  VOID  *X509Cert
1628   );
1629
1630 /**
1631   Release the specified X509 stack object.
1632
1633   If the interface is not supported, then ASSERT().
1634
1635   @param[in]  X509Stack  Pointer to the X509 stack object to be released.
1636
1637 **/
1638 VOID
1639 EFIAPI
1640 X509StackFree (
1641   IN  VOID  *X509Stack
1642   );
1643
1644 /**
1645   Retrieve the TBSCertificate from one given X.509 certificate.
1646
1647   @param[in]      Cert         Pointer to the given DER-encoded X509 certificate.
1648   @param[in]      CertSize     Size of the X509 certificate in bytes.
1649   @param[out]     TBSCert      DER-Encoded To-Be-Signed certificate.
1650   @param[out]     TBSCertSize  Size of the TBS certificate in bytes.
1651
1652   If Cert is NULL, then return FALSE.
1653   If TBSCert is NULL, then return FALSE.
1654   If TBSCertSize is NULL, then return FALSE.
1655   If this interface is not supported, then return FALSE.
1656
1657   @retval  TRUE   The TBSCertificate was retrieved successfully.
1658   @retval  FALSE  Invalid X.509 certificate.
1659
1660 **/
1661 BOOLEAN
1662 EFIAPI
1663 X509GetTBSCert (
1664   IN  CONST UINT8  *Cert,
1665   IN  UINTN        CertSize,
1666   OUT UINT8        **TBSCert,
1667   OUT UINTN        *TBSCertSize
1668   );
1669
1670 /**
1671   Derives a key from a password using a salt and iteration count, based on PKCS#5 v2.0
1672   password based encryption key derivation function PBKDF2, as specified in RFC 2898.
1673
1674   If Password or Salt or OutKey is NULL, then return FALSE.
1675   If the hash algorithm could not be determined, then return FALSE.
1676   If this interface is not supported, then return FALSE.
1677
1678   @param[in]  PasswordLength  Length of input password in bytes.
1679   @param[in]  Password        Pointer to the array for the password.
1680   @param[in]  SaltLength      Size of the Salt in bytes.
1681   @param[in]  Salt            Pointer to the Salt.
1682   @param[in]  IterationCount  Number of iterations to perform. Its value should be
1683                               greater than or equal to 1.
1684   @param[in]  DigestSize      Size of the message digest to be used (eg. SHA256_DIGEST_SIZE).
1685                               NOTE: DigestSize will be used to determine the hash algorithm.
1686                                     Only SHA1_DIGEST_SIZE or SHA256_DIGEST_SIZE is supported.
1687   @param[in]  KeyLength       Size of the derived key buffer in bytes.
1688   @param[out] OutKey          Pointer to the output derived key buffer.
1689
1690   @retval  TRUE   A key was derived successfully.
1691   @retval  FALSE  One of the pointers was NULL or one of the sizes was too large.
1692   @retval  FALSE  The hash algorithm could not be determined from the digest size.
1693   @retval  FALSE  The key derivation operation failed.
1694   @retval  FALSE  This interface is not supported.
1695
1696 **/
1697 BOOLEAN
1698 EFIAPI
1699 Pkcs5HashPassword (
1700   IN  UINTN        PasswordLength,
1701   IN  CONST CHAR8  *Password,
1702   IN  UINTN        SaltLength,
1703   IN  CONST UINT8  *Salt,
1704   IN  UINTN        IterationCount,
1705   IN  UINTN        DigestSize,
1706   IN  UINTN        KeyLength,
1707   OUT UINT8        *OutKey
1708   );
1709
1710 /**
1711   Encrypts a blob using PKCS1v2 (RSAES-OAEP) schema. On success, will return the
1712   encrypted message in a newly allocated buffer.
1713
1714   Things that can cause a failure include:
1715   - X509 key size does not match any known key size.
1716   - Fail to parse X509 certificate.
1717   - Fail to allocate an intermediate buffer.
1718   - Null pointer provided for a non-optional parameter.
1719   - Data size is too large for the provided key size (max size is a function of key size
1720     and hash digest size).
1721
1722   @param[in]  PublicKey           A pointer to the DER-encoded X509 certificate that
1723                                   will be used to encrypt the data.
1724   @param[in]  PublicKeySize       Size of the X509 cert buffer.
1725   @param[in]  InData              Data to be encrypted.
1726   @param[in]  InDataSize          Size of the data buffer.
1727   @param[in]  PrngSeed            [Optional] If provided, a pointer to a random seed buffer
1728                                   to be used when initializing the PRNG. NULL otherwise.
1729   @param[in]  PrngSeedSize        [Optional] If provided, size of the random seed buffer.
1730                                   0 otherwise.
1731   @param[out] EncryptedData       Pointer to an allocated buffer containing the encrypted
1732                                   message.
1733   @param[out] EncryptedDataSize   Size of the encrypted message buffer.
1734
1735   @retval     TRUE                Encryption was successful.
1736   @retval     FALSE               Encryption failed.
1737
1738 **/
1739 BOOLEAN
1740 EFIAPI
1741 Pkcs1v2Encrypt (
1742   IN   CONST UINT8  *PublicKey,
1743   IN   UINTN        PublicKeySize,
1744   IN   UINT8        *InData,
1745   IN   UINTN        InDataSize,
1746   IN   CONST UINT8  *PrngSeed,  OPTIONAL
1747   IN   UINTN        PrngSeedSize,  OPTIONAL
1748   OUT  UINT8        **EncryptedData,
1749   OUT  UINTN        *EncryptedDataSize
1750   );
1751
1752 /**
1753   The 3rd parameter of Pkcs7GetSigners will return all embedded
1754   X.509 certificate in one given PKCS7 signature. The format is:
1755   //
1756   // UINT8  CertNumber;
1757   // UINT32 Cert1Length;
1758   // UINT8  Cert1[];
1759   // UINT32 Cert2Length;
1760   // UINT8  Cert2[];
1761   // ...
1762   // UINT32 CertnLength;
1763   // UINT8  Certn[];
1764   //
1765
1766   The two following C-structure are used for parsing CertStack more clearly.
1767 **/
1768 #pragma pack(1)
1769
1770 typedef struct {
1771   UINT32    CertDataLength;       // The length in bytes of X.509 certificate.
1772   UINT8     CertDataBuffer[0];    // The X.509 certificate content (DER).
1773 } EFI_CERT_DATA;
1774
1775 typedef struct {
1776   UINT8             CertNumber;   // Number of X.509 certificate.
1777   //EFI_CERT_DATA   CertArray[];  // An array of X.509 certificate.
1778 } EFI_CERT_STACK;
1779
1780 #pragma pack()
1781
1782 /**
1783   Get the signer's certificates from PKCS#7 signed data as described in "PKCS #7:
1784   Cryptographic Message Syntax Standard". The input signed data could be wrapped
1785   in a ContentInfo structure.
1786
1787   If P7Data, CertStack, StackLength, TrustedCert or CertLength is NULL, then
1788   return FALSE. If P7Length overflow, then return FALSE.
1789   If this interface is not supported, then return FALSE.
1790
1791   @param[in]  P7Data       Pointer to the PKCS#7 message to verify.
1792   @param[in]  P7Length     Length of the PKCS#7 message in bytes.
1793   @param[out] CertStack    Pointer to Signer's certificates retrieved from P7Data.
1794                            It's caller's responsibility to free the buffer with
1795                            Pkcs7FreeSigners().
1796                            This data structure is EFI_CERT_STACK type.
1797   @param[out] StackLength  Length of signer's certificates in bytes.
1798   @param[out] TrustedCert  Pointer to a trusted certificate from Signer's certificates.
1799                            It's caller's responsibility to free the buffer with
1800                            Pkcs7FreeSigners().
1801   @param[out] CertLength   Length of the trusted certificate in bytes.
1802
1803   @retval  TRUE            The operation is finished successfully.
1804   @retval  FALSE           Error occurs during the operation.
1805   @retval  FALSE           This interface is not supported.
1806
1807 **/
1808 BOOLEAN
1809 EFIAPI
1810 Pkcs7GetSigners (
1811   IN  CONST UINT8  *P7Data,
1812   IN  UINTN        P7Length,
1813   OUT UINT8        **CertStack,
1814   OUT UINTN        *StackLength,
1815   OUT UINT8        **TrustedCert,
1816   OUT UINTN        *CertLength
1817   );
1818
1819 /**
1820   Wrap function to use free() to free allocated memory for certificates.
1821
1822   If this interface is not supported, then ASSERT().
1823
1824   @param[in]  Certs        Pointer to the certificates to be freed.
1825
1826 **/
1827 VOID
1828 EFIAPI
1829 Pkcs7FreeSigners (
1830   IN  UINT8        *Certs
1831   );
1832
1833 /**
1834   Retrieves all embedded certificates from PKCS#7 signed data as described in "PKCS #7:
1835   Cryptographic Message Syntax Standard", and outputs two certificate lists chained and
1836   unchained to the signer's certificates.
1837   The input signed data could be wrapped in a ContentInfo structure.
1838
1839   @param[in]  P7Data            Pointer to the PKCS#7 message.
1840   @param[in]  P7Length          Length of the PKCS#7 message in bytes.
1841   @param[out] SignerChainCerts  Pointer to the certificates list chained to signer's
1842                                 certificate. It's caller's responsibility to free the buffer
1843                                 with Pkcs7FreeSigners().
1844                                 This data structure is EFI_CERT_STACK type.
1845   @param[out] ChainLength       Length of the chained certificates list buffer in bytes.
1846   @param[out] UnchainCerts      Pointer to the unchained certificates lists. It's caller's
1847                                 responsibility to free the buffer with Pkcs7FreeSigners().
1848                                 This data structure is EFI_CERT_STACK type.
1849   @param[out] UnchainLength     Length of the unchained certificates list buffer in bytes.
1850
1851   @retval  TRUE         The operation is finished successfully.
1852   @retval  FALSE        Error occurs during the operation.
1853
1854 **/
1855 BOOLEAN
1856 EFIAPI
1857 Pkcs7GetCertificatesList (
1858   IN  CONST UINT8  *P7Data,
1859   IN  UINTN        P7Length,
1860   OUT UINT8        **SignerChainCerts,
1861   OUT UINTN        *ChainLength,
1862   OUT UINT8        **UnchainCerts,
1863   OUT UINTN        *UnchainLength
1864   );
1865
1866 /**
1867   Creates a PKCS#7 signedData as described in "PKCS #7: Cryptographic Message
1868   Syntax Standard, version 1.5". This interface is only intended to be used for
1869   application to perform PKCS#7 functionality validation.
1870
1871   If this interface is not supported, then return FALSE.
1872
1873   @param[in]  PrivateKey       Pointer to the PEM-formatted private key data for
1874                                data signing.
1875   @param[in]  PrivateKeySize   Size of the PEM private key data in bytes.
1876   @param[in]  KeyPassword      NULL-terminated passphrase used for encrypted PEM
1877                                key data.
1878   @param[in]  InData           Pointer to the content to be signed.
1879   @param[in]  InDataSize       Size of InData in bytes.
1880   @param[in]  SignCert         Pointer to signer's DER-encoded certificate to sign with.
1881   @param[in]  OtherCerts       Pointer to an optional additional set of certificates to
1882                                include in the PKCS#7 signedData (e.g. any intermediate
1883                                CAs in the chain).
1884   @param[out] SignedData       Pointer to output PKCS#7 signedData. It's caller's
1885                                responsibility to free the buffer with FreePool().
1886   @param[out] SignedDataSize   Size of SignedData in bytes.
1887
1888   @retval     TRUE             PKCS#7 data signing succeeded.
1889   @retval     FALSE            PKCS#7 data signing failed.
1890   @retval     FALSE            This interface is not supported.
1891
1892 **/
1893 BOOLEAN
1894 EFIAPI
1895 Pkcs7Sign (
1896   IN   CONST UINT8  *PrivateKey,
1897   IN   UINTN        PrivateKeySize,
1898   IN   CONST UINT8  *KeyPassword,
1899   IN   UINT8        *InData,
1900   IN   UINTN        InDataSize,
1901   IN   UINT8        *SignCert,
1902   IN   UINT8        *OtherCerts      OPTIONAL,
1903   OUT  UINT8        **SignedData,
1904   OUT  UINTN        *SignedDataSize
1905   );
1906
1907 /**
1908   Verifies the validity of a PKCS#7 signed data as described in "PKCS #7:
1909   Cryptographic Message Syntax Standard". The input signed data could be wrapped
1910   in a ContentInfo structure.
1911
1912   If P7Data, TrustedCert or InData is NULL, then return FALSE.
1913   If P7Length, CertLength or DataLength overflow, then return FALSE.
1914   If this interface is not supported, then return FALSE.
1915
1916   @param[in]  P7Data       Pointer to the PKCS#7 message to verify.
1917   @param[in]  P7Length     Length of the PKCS#7 message in bytes.
1918   @param[in]  TrustedCert  Pointer to a trusted/root certificate encoded in DER, which
1919                            is used for certificate chain verification.
1920   @param[in]  CertLength   Length of the trusted certificate in bytes.
1921   @param[in]  InData       Pointer to the content to be verified.
1922   @param[in]  DataLength   Length of InData in bytes.
1923
1924   @retval  TRUE  The specified PKCS#7 signed data is valid.
1925   @retval  FALSE Invalid PKCS#7 signed data.
1926   @retval  FALSE This interface is not supported.
1927
1928 **/
1929 BOOLEAN
1930 EFIAPI
1931 Pkcs7Verify (
1932   IN  CONST UINT8  *P7Data,
1933   IN  UINTN        P7Length,
1934   IN  CONST UINT8  *TrustedCert,
1935   IN  UINTN        CertLength,
1936   IN  CONST UINT8  *InData,
1937   IN  UINTN        DataLength
1938   );
1939
1940 /**
1941   This function receives a PKCS7 formatted signature, and then verifies that
1942   the specified Enhanced or Extended Key Usages (EKU's) are present in the end-entity
1943   leaf signing certificate.
1944   Note that this function does not validate the certificate chain.
1945
1946   Applications for custom EKU's are quite flexible. For example, a policy EKU
1947   may be present in an Issuing Certificate Authority (CA), and any sub-ordinate
1948   certificate issued might also contain this EKU, thus constraining the
1949   sub-ordinate certificate.  Other applications might allow a certificate
1950   embedded in a device to specify that other Object Identifiers (OIDs) are
1951   present which contains binary data specifying custom capabilities that
1952   the device is able to do.
1953
1954   @param[in]  Pkcs7Signature       The PKCS#7 signed information content block. An array
1955                                    containing the content block with both the signature,
1956                                    the signer's certificate, and any necessary intermediate
1957                                    certificates.
1958   @param[in]  Pkcs7SignatureSize   Number of bytes in Pkcs7Signature.
1959   @param[in]  RequiredEKUs         Array of null-terminated strings listing OIDs of
1960                                    required EKUs that must be present in the signature.
1961   @param[in]  RequiredEKUsSize     Number of elements in the RequiredEKUs string array.
1962   @param[in]  RequireAllPresent    If this is TRUE, then all of the specified EKU's
1963                                    must be present in the leaf signer.  If it is
1964                                    FALSE, then we will succeed if we find any
1965                                    of the specified EKU's.
1966
1967   @retval EFI_SUCCESS              The required EKUs were found in the signature.
1968   @retval EFI_INVALID_PARAMETER    A parameter was invalid.
1969   @retval EFI_NOT_FOUND            One or more EKU's were not found in the signature.
1970
1971 **/
1972 RETURN_STATUS
1973 EFIAPI
1974 VerifyEKUsInPkcs7Signature (
1975   IN  CONST UINT8   *Pkcs7Signature,
1976   IN  CONST UINT32  SignatureSize,
1977   IN  CONST CHAR8   *RequiredEKUs[],
1978   IN  CONST UINT32  RequiredEKUsSize,
1979   IN  BOOLEAN       RequireAllPresent
1980   );
1981
1982 /**
1983   Extracts the attached content from a PKCS#7 signed data if existed. The input signed
1984   data could be wrapped in a ContentInfo structure.
1985
1986   If P7Data, Content, or ContentSize is NULL, then return FALSE. If P7Length overflow,
1987   then return FALSE. If the P7Data is not correctly formatted, then return FALSE.
1988
1989   Caution: This function may receive untrusted input. So this function will do
1990            basic check for PKCS#7 data structure.
1991
1992   @param[in]   P7Data       Pointer to the PKCS#7 signed data to process.
1993   @param[in]   P7Length     Length of the PKCS#7 signed data in bytes.
1994   @param[out]  Content      Pointer to the extracted content from the PKCS#7 signedData.
1995                             It's caller's responsibility to free the buffer with FreePool().
1996   @param[out]  ContentSize  The size of the extracted content in bytes.
1997
1998   @retval     TRUE          The P7Data was correctly formatted for processing.
1999   @retval     FALSE         The P7Data was not correctly formatted for processing.
2000
2001 **/
2002 BOOLEAN
2003 EFIAPI
2004 Pkcs7GetAttachedContent (
2005   IN  CONST UINT8  *P7Data,
2006   IN  UINTN        P7Length,
2007   OUT VOID         **Content,
2008   OUT UINTN        *ContentSize
2009   );
2010
2011 /**
2012   Verifies the validity of a PE/COFF Authenticode Signature as described in "Windows
2013   Authenticode Portable Executable Signature Format".
2014
2015   If AuthData is NULL, then return FALSE.
2016   If ImageHash is NULL, then return FALSE.
2017   If this interface is not supported, then return FALSE.
2018
2019   @param[in]  AuthData     Pointer to the Authenticode Signature retrieved from signed
2020                            PE/COFF image to be verified.
2021   @param[in]  DataSize     Size of the Authenticode Signature in bytes.
2022   @param[in]  TrustedCert  Pointer to a trusted/root certificate encoded in DER, which
2023                            is used for certificate chain verification.
2024   @param[in]  CertSize     Size of the trusted certificate in bytes.
2025   @param[in]  ImageHash    Pointer to the original image file hash value. The procedure
2026                            for calculating the image hash value is described in Authenticode
2027                            specification.
2028   @param[in]  HashSize     Size of Image hash value in bytes.
2029
2030   @retval  TRUE   The specified Authenticode Signature is valid.
2031   @retval  FALSE  Invalid Authenticode Signature.
2032   @retval  FALSE  This interface is not supported.
2033
2034 **/
2035 BOOLEAN
2036 EFIAPI
2037 AuthenticodeVerify (
2038   IN  CONST UINT8  *AuthData,
2039   IN  UINTN        DataSize,
2040   IN  CONST UINT8  *TrustedCert,
2041   IN  UINTN        CertSize,
2042   IN  CONST UINT8  *ImageHash,
2043   IN  UINTN        HashSize
2044   );
2045
2046 /**
2047   Verifies the validity of a RFC3161 Timestamp CounterSignature embedded in PE/COFF Authenticode
2048   signature.
2049
2050   If AuthData is NULL, then return FALSE.
2051   If this interface is not supported, then return FALSE.
2052
2053   @param[in]  AuthData     Pointer to the Authenticode Signature retrieved from signed
2054                            PE/COFF image to be verified.
2055   @param[in]  DataSize     Size of the Authenticode Signature in bytes.
2056   @param[in]  TsaCert      Pointer to a trusted/root TSA certificate encoded in DER, which
2057                            is used for TSA certificate chain verification.
2058   @param[in]  CertSize     Size of the trusted certificate in bytes.
2059   @param[out] SigningTime  Return the time of timestamp generation time if the timestamp
2060                            signature is valid.
2061
2062   @retval  TRUE   The specified Authenticode includes a valid RFC3161 Timestamp CounterSignature.
2063   @retval  FALSE  No valid RFC3161 Timestamp CounterSignature in the specified Authenticode data.
2064
2065 **/
2066 BOOLEAN
2067 EFIAPI
2068 ImageTimestampVerify (
2069   IN  CONST UINT8  *AuthData,
2070   IN  UINTN        DataSize,
2071   IN  CONST UINT8  *TsaCert,
2072   IN  UINTN        CertSize,
2073   OUT EFI_TIME     *SigningTime
2074   );
2075
2076 //=====================================================================================
2077 //    DH Key Exchange Primitive
2078 //=====================================================================================
2079
2080 /**
2081   Allocates and Initializes one Diffie-Hellman Context for subsequent use.
2082
2083   @return  Pointer to the Diffie-Hellman Context that has been initialized.
2084            If the allocations fails, DhNew() returns NULL.
2085            If the interface is not supported, DhNew() returns NULL.
2086
2087 **/
2088 VOID *
2089 EFIAPI
2090 DhNew (
2091   VOID
2092   );
2093
2094 /**
2095   Release the specified DH context.
2096
2097   If the interface is not supported, then ASSERT().
2098
2099   @param[in]  DhContext  Pointer to the DH context to be released.
2100
2101 **/
2102 VOID
2103 EFIAPI
2104 DhFree (
2105   IN  VOID  *DhContext
2106   );
2107
2108 /**
2109   Generates DH parameter.
2110
2111   Given generator g, and length of prime number p in bits, this function generates p,
2112   and sets DH context according to value of g and p.
2113
2114   Before this function can be invoked, pseudorandom number generator must be correctly
2115   initialized by RandomSeed().
2116
2117   If DhContext is NULL, then return FALSE.
2118   If Prime is NULL, then return FALSE.
2119   If this interface is not supported, then return FALSE.
2120
2121   @param[in, out]  DhContext    Pointer to the DH context.
2122   @param[in]       Generator    Value of generator.
2123   @param[in]       PrimeLength  Length in bits of prime to be generated.
2124   @param[out]      Prime        Pointer to the buffer to receive the generated prime number.
2125
2126   @retval TRUE   DH parameter generation succeeded.
2127   @retval FALSE  Value of Generator is not supported.
2128   @retval FALSE  PRNG fails to generate random prime number with PrimeLength.
2129   @retval FALSE  This interface is not supported.
2130
2131 **/
2132 BOOLEAN
2133 EFIAPI
2134 DhGenerateParameter (
2135   IN OUT  VOID   *DhContext,
2136   IN      UINTN  Generator,
2137   IN      UINTN  PrimeLength,
2138   OUT     UINT8  *Prime
2139   );
2140
2141 /**
2142   Sets generator and prime parameters for DH.
2143
2144   Given generator g, and prime number p, this function and sets DH
2145   context accordingly.
2146
2147   If DhContext is NULL, then return FALSE.
2148   If Prime is NULL, then return FALSE.
2149   If this interface is not supported, then return FALSE.
2150
2151   @param[in, out]  DhContext    Pointer to the DH context.
2152   @param[in]       Generator    Value of generator.
2153   @param[in]       PrimeLength  Length in bits of prime to be generated.
2154   @param[in]       Prime        Pointer to the prime number.
2155
2156   @retval TRUE   DH parameter setting succeeded.
2157   @retval FALSE  Value of Generator is not supported.
2158   @retval FALSE  Value of Generator is not suitable for the Prime.
2159   @retval FALSE  Value of Prime is not a prime number.
2160   @retval FALSE  Value of Prime is not a safe prime number.
2161   @retval FALSE  This interface is not supported.
2162
2163 **/
2164 BOOLEAN
2165 EFIAPI
2166 DhSetParameter (
2167   IN OUT  VOID         *DhContext,
2168   IN      UINTN        Generator,
2169   IN      UINTN        PrimeLength,
2170   IN      CONST UINT8  *Prime
2171   );
2172
2173 /**
2174   Generates DH public key.
2175
2176   This function generates random secret exponent, and computes the public key, which is
2177   returned via parameter PublicKey and PublicKeySize. DH context is updated accordingly.
2178   If the PublicKey buffer is too small to hold the public key, FALSE is returned and
2179   PublicKeySize is set to the required buffer size to obtain the public key.
2180
2181   If DhContext is NULL, then return FALSE.
2182   If PublicKeySize is NULL, then return FALSE.
2183   If PublicKeySize is large enough but PublicKey is NULL, then return FALSE.
2184   If this interface is not supported, then return FALSE.
2185
2186   @param[in, out]  DhContext      Pointer to the DH context.
2187   @param[out]      PublicKey      Pointer to the buffer to receive generated public key.
2188   @param[in, out]  PublicKeySize  On input, the size of PublicKey buffer in bytes.
2189                                  On output, the size of data returned in PublicKey buffer in bytes.
2190
2191   @retval TRUE   DH public key generation succeeded.
2192   @retval FALSE  DH public key generation failed.
2193   @retval FALSE  PublicKeySize is not large enough.
2194   @retval FALSE  This interface is not supported.
2195
2196 **/
2197 BOOLEAN
2198 EFIAPI
2199 DhGenerateKey (
2200   IN OUT  VOID   *DhContext,
2201   OUT     UINT8  *PublicKey,
2202   IN OUT  UINTN  *PublicKeySize
2203   );
2204
2205 /**
2206   Computes exchanged common key.
2207
2208   Given peer's public key, this function computes the exchanged common key, based on its own
2209   context including value of prime modulus and random secret exponent.
2210
2211   If DhContext is NULL, then return FALSE.
2212   If PeerPublicKey is NULL, then return FALSE.
2213   If KeySize is NULL, then return FALSE.
2214   If Key is NULL, then return FALSE.
2215   If KeySize is not large enough, then return FALSE.
2216   If this interface is not supported, then return FALSE.
2217
2218   @param[in, out]  DhContext          Pointer to the DH context.
2219   @param[in]       PeerPublicKey      Pointer to the peer's public key.
2220   @param[in]       PeerPublicKeySize  Size of peer's public key in bytes.
2221   @param[out]      Key                Pointer to the buffer to receive generated key.
2222   @param[in, out]  KeySize            On input, the size of Key buffer in bytes.
2223                                      On output, the size of data returned in Key buffer in bytes.
2224
2225   @retval TRUE   DH exchanged key generation succeeded.
2226   @retval FALSE  DH exchanged key generation failed.
2227   @retval FALSE  KeySize is not large enough.
2228   @retval FALSE  This interface is not supported.
2229
2230 **/
2231 BOOLEAN
2232 EFIAPI
2233 DhComputeKey (
2234   IN OUT  VOID         *DhContext,
2235   IN      CONST UINT8  *PeerPublicKey,
2236   IN      UINTN        PeerPublicKeySize,
2237   OUT     UINT8        *Key,
2238   IN OUT  UINTN        *KeySize
2239   );
2240
2241 //=====================================================================================
2242 //    Pseudo-Random Generation Primitive
2243 //=====================================================================================
2244
2245 /**
2246   Sets up the seed value for the pseudorandom number generator.
2247
2248   This function sets up the seed value for the pseudorandom number generator.
2249   If Seed is not NULL, then the seed passed in is used.
2250   If Seed is NULL, then default seed is used.
2251   If this interface is not supported, then return FALSE.
2252
2253   @param[in]  Seed      Pointer to seed value.
2254                         If NULL, default seed is used.
2255   @param[in]  SeedSize  Size of seed value.
2256                         If Seed is NULL, this parameter is ignored.
2257
2258   @retval TRUE   Pseudorandom number generator has enough entropy for random generation.
2259   @retval FALSE  Pseudorandom number generator does not have enough entropy for random generation.
2260   @retval FALSE  This interface is not supported.
2261
2262 **/
2263 BOOLEAN
2264 EFIAPI
2265 RandomSeed (
2266   IN  CONST  UINT8  *Seed  OPTIONAL,
2267   IN  UINTN         SeedSize
2268   );
2269
2270 /**
2271   Generates a pseudorandom byte stream of the specified size.
2272
2273   If Output is NULL, then return FALSE.
2274   If this interface is not supported, then return FALSE.
2275
2276   @param[out]  Output  Pointer to buffer to receive random value.
2277   @param[in]   Size    Size of random bytes to generate.
2278
2279   @retval TRUE   Pseudorandom byte stream generated successfully.
2280   @retval FALSE  Pseudorandom number generator fails to generate due to lack of entropy.
2281   @retval FALSE  This interface is not supported.
2282
2283 **/
2284 BOOLEAN
2285 EFIAPI
2286 RandomBytes (
2287   OUT  UINT8  *Output,
2288   IN   UINTN  Size
2289   );
2290
2291 //=====================================================================================
2292 //    Key Derivation Function Primitive
2293 //=====================================================================================
2294
2295 /**
2296   Derive key data using HMAC-SHA256 based KDF.
2297
2298   @param[in]   Key              Pointer to the user-supplied key.
2299   @param[in]   KeySize          Key size in bytes.
2300   @param[in]   Salt             Pointer to the salt(non-secret) value.
2301   @param[in]   SaltSize         Salt size in bytes.
2302   @param[in]   Info             Pointer to the application specific info.
2303   @param[in]   InfoSize         Info size in bytes.
2304   @param[out]  Out              Pointer to buffer to receive hkdf value.
2305   @param[in]   OutSize          Size of hkdf bytes to generate.
2306
2307   @retval TRUE   Hkdf generated successfully.
2308   @retval FALSE  Hkdf generation failed.
2309
2310 **/
2311 BOOLEAN
2312 EFIAPI
2313 HkdfSha256ExtractAndExpand (
2314   IN   CONST UINT8  *Key,
2315   IN   UINTN        KeySize,
2316   IN   CONST UINT8  *Salt,
2317   IN   UINTN        SaltSize,
2318   IN   CONST UINT8  *Info,
2319   IN   UINTN        InfoSize,
2320   OUT  UINT8        *Out,
2321   IN   UINTN        OutSize
2322   );
2323
2324 #endif // __BASE_CRYPT_LIB_H__