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