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-MD5 use.
 885
 886   If this interface is not supported, then return NULL.
 887
 888   @return  Pointer to the HMAC_CTX context that has been initialized.
 889            If the allocations fails, HmacMd5New() returns NULL.
 890   @retval  NULL  This interface is not supported.
 891
 892 **/
 893 VOID *
 894 EFIAPI
 895 HmacMd5New (
 896   VOID
 897   );
 898
 899 /**
 900   Release the specified HMAC_CTX context.
 901
 902   If this interface is not supported, then do nothing.
 903
 904   @param[in]  HmacMd5Ctx  Pointer to the HMAC_CTX context to be released.
 905
 906 **/
 907 VOID
 908 EFIAPI
 909 HmacMd5Free (
 910   IN  VOID  *HmacMd5Ctx
 911   );
 912
 913 /**
 914   Set user-supplied key for subsequent use. It must be done before any
 915   calling to HmacMd5Update().
 916
 917   If HmacMd5Context is NULL, then return FALSE.
 918   If this interface is not supported, then return FALSE.
 919
 920   @param[out]  HmacMd5Context  Pointer to HMAC-MD5 context.
 921   @param[in]   Key             Pointer to the user-supplied key.
 922   @param[in]   KeySize         Key size in bytes.
 923
 924   @retval TRUE   Key is set successfully.
 925   @retval FALSE  Key is set unsuccessfully.
 926   @retval FALSE  This interface is not supported.
 927
 928 **/
 929 BOOLEAN
 930 EFIAPI
 931 HmacMd5SetKey (
 932   OUT  VOID         *HmacMd5Context,
 933   IN   CONST UINT8  *Key,
 934   IN   UINTN        KeySize
 935   );
 936
 937 /**
 938   Makes a copy of an existing HMAC-MD5 context.
 939
 940   If HmacMd5Context is NULL, then return FALSE.
 941   If NewHmacMd5Context is NULL, then return FALSE.
 942   If this interface is not supported, then return FALSE.
 943
 944   @param[in]  HmacMd5Context     Pointer to HMAC-MD5 context being copied.
 945   @param[out] NewHmacMd5Context  Pointer to new HMAC-MD5 context.
 946
 947   @retval TRUE   HMAC-MD5 context copy succeeded.
 948   @retval FALSE  HMAC-MD5 context copy failed.
 949   @retval FALSE  This interface is not supported.
 950
 951 **/
 952 BOOLEAN
 953 EFIAPI
 954 HmacMd5Duplicate (
 955   IN   CONST VOID  *HmacMd5Context,
 956   OUT  VOID        *NewHmacMd5Context
 957   );
 958
 959 /**
 960   Digests the input data and updates HMAC-MD5 context.
 961
 962   This function performs HMAC-MD5 digest on a data buffer of the specified size.
 963   It can be called multiple times to compute the digest of long or discontinuous data streams.
 964   HMAC-MD5 context should be initialized by HmacMd5New(), and should not be finalized by
 965   HmacMd5Final(). Behavior with invalid context is undefined.
 966
 967   If HmacMd5Context is NULL, then return FALSE.
 968   If this interface is not supported, then return FALSE.
 969
 970   @param[in, out]  HmacMd5Context  Pointer to the HMAC-MD5 context.
 971   @param[in]       Data            Pointer to the buffer containing the data to be digested.
 972   @param[in]       DataSize        Size of Data buffer in bytes.
 973
 974   @retval TRUE   HMAC-MD5 data digest succeeded.
 975   @retval FALSE  HMAC-MD5 data digest failed.
 976   @retval FALSE  This interface is not supported.
 977
 978 **/
 979 BOOLEAN
 980 EFIAPI
 981 HmacMd5Update (
 982   IN OUT  VOID        *HmacMd5Context,
 983   IN      CONST VOID  *Data,
 984   IN      UINTN       DataSize
 985   );
 986
 987 /**
 988   Completes computation of the HMAC-MD5 digest value.
 989
 990   This function completes HMAC-MD5 hash computation and retrieves the digest value into
 991   the specified memory. After this function has been called, the HMAC-MD5 context cannot
 992   be used again.
 993   HMAC-MD5 context should be initialized by HmacMd5New(), and should not be finalized by
 994   HmacMd5Final(). Behavior with invalid HMAC-MD5 context is undefined.
 995
 996   If HmacMd5Context is NULL, then return FALSE.
 997   If HmacValue is NULL, then return FALSE.
 998   If this interface is not supported, then return FALSE.
 999
1000   @param[in, out]  HmacMd5Context  Pointer to the HMAC-MD5 context.
1001   @param[out]      HmacValue       Pointer to a buffer that receives the HMAC-MD5 digest
1002                                    value (16 bytes).
1003
1004   @retval TRUE   HMAC-MD5 digest computation succeeded.
1005   @retval FALSE  HMAC-MD5 digest computation failed.
1006   @retval FALSE  This interface is not supported.
1007
1008 **/
1009 BOOLEAN
1010 EFIAPI
1011 HmacMd5Final (
1012   IN OUT  VOID   *HmacMd5Context,
1013   OUT     UINT8  *HmacValue
1014   );
1015
1016 /**
1017   Allocates and initializes one HMAC_CTX context for subsequent HMAC-SHA1 use.
1018
1019   If this interface is not supported, then return NULL.
1020
1021   @return  Pointer to the HMAC_CTX context that has been initialized.
1022            If the allocations fails, HmacSha1New() returns NULL.
1023   @return  NULL   This interface is not supported.
1024
1025 **/
1026 VOID *
1027 EFIAPI
1028 HmacSha1New (
1029   VOID
1030   );
1031
1032 /**
1033   Release the specified HMAC_CTX context.
1034
1035   If this interface is not supported, then do nothing.
1036
1037   @param[in]  HmacSha1Ctx  Pointer to the HMAC_CTX context to be released.
1038
1039 **/
1040 VOID
1041 EFIAPI
1042 HmacSha1Free (
1043   IN  VOID  *HmacSha1Ctx
1044   );
1045
1046 /**
1047   Set user-supplied key for subsequent use. It must be done before any
1048   calling to HmacSha1Update().
1049
1050   If HmacSha1Context is NULL, then return FALSE.
1051   If this interface is not supported, then return FALSE.
1052
1053   @param[out]  HmacSha1Context  Pointer to HMAC-SHA1 context.
1054   @param[in]   Key              Pointer to the user-supplied key.
1055   @param[in]   KeySize          Key size in bytes.
1056
1057   @retval TRUE   The Key is set successfully.
1058   @retval FALSE  The Key is set unsuccessfully.
1059   @retval FALSE  This interface is not supported.
1060
1061 **/
1062 BOOLEAN
1063 EFIAPI
1064 HmacSha1SetKey (
1065   OUT  VOID         *HmacSha1Context,
1066   IN   CONST UINT8  *Key,
1067   IN   UINTN        KeySize
1068   );
1069
1070 /**
1071   Makes a copy of an existing HMAC-SHA1 context.
1072
1073   If HmacSha1Context is NULL, then return FALSE.
1074   If NewHmacSha1Context is NULL, then return FALSE.
1075   If this interface is not supported, then return FALSE.
1076
1077   @param[in]  HmacSha1Context     Pointer to HMAC-SHA1 context being copied.
1078   @param[out] NewHmacSha1Context  Pointer to new HMAC-SHA1 context.
1079
1080   @retval TRUE   HMAC-SHA1 context copy succeeded.
1081   @retval FALSE  HMAC-SHA1 context copy failed.
1082   @retval FALSE  This interface is not supported.
1083
1084 **/
1085 BOOLEAN
1086 EFIAPI
1087 HmacSha1Duplicate (
1088   IN   CONST VOID  *HmacSha1Context,
1089   OUT  VOID        *NewHmacSha1Context
1090   );
1091
1092 /**
1093   Digests the input data and updates HMAC-SHA1 context.
1094
1095   This function performs HMAC-SHA1 digest on a data buffer of the specified size.
1096   It can be called multiple times to compute the digest of long or discontinuous data streams.
1097   HMAC-SHA1 context should be initialized by HmacSha1New(), and should not be finalized by
1098   HmacSha1Final(). Behavior with invalid context is undefined.
1099
1100   If HmacSha1Context is NULL, then return FALSE.
1101   If this interface is not supported, then return FALSE.
1102
1103   @param[in, out]  HmacSha1Context Pointer to the HMAC-SHA1 context.
1104   @param[in]       Data            Pointer to the buffer containing the data to be digested.
1105   @param[in]       DataSize        Size of Data buffer in bytes.
1106
1107   @retval TRUE   HMAC-SHA1 data digest succeeded.
1108   @retval FALSE  HMAC-SHA1 data digest failed.
1109   @retval FALSE  This interface is not supported.
1110
1111 **/
1112 BOOLEAN
1113 EFIAPI
1114 HmacSha1Update (
1115   IN OUT  VOID        *HmacSha1Context,
1116   IN      CONST VOID  *Data,
1117   IN      UINTN       DataSize
1118   );
1119
1120 /**
1121   Completes computation of the HMAC-SHA1 digest value.
1122
1123   This function completes HMAC-SHA1 hash computation and retrieves the digest value into
1124   the specified memory. After this function has been called, the HMAC-SHA1 context cannot
1125   be used again.
1126   HMAC-SHA1 context should be initialized by HmacSha1New(), and should not be finalized
1127   by HmacSha1Final(). Behavior with invalid HMAC-SHA1 context is undefined.
1128
1129   If HmacSha1Context is NULL, then return FALSE.
1130   If HmacValue is NULL, then return FALSE.
1131   If this interface is not supported, then return FALSE.
1132
1133   @param[in, out]  HmacSha1Context  Pointer to the HMAC-SHA1 context.
1134   @param[out]      HmacValue        Pointer to a buffer that receives the HMAC-SHA1 digest
1135                                     value (20 bytes).
1136
1137   @retval TRUE   HMAC-SHA1 digest computation succeeded.
1138   @retval FALSE  HMAC-SHA1 digest computation failed.
1139   @retval FALSE  This interface is not supported.
1140
1141 **/
1142 BOOLEAN
1143 EFIAPI
1144 HmacSha1Final (
1145   IN OUT  VOID   *HmacSha1Context,
1146   OUT     UINT8  *HmacValue
1147   );
1148
1149 /**
1150   Allocates and initializes one HMAC_CTX context for subsequent HMAC-SHA256 use.
1151
1152   @return  Pointer to the HMAC_CTX context that has been initialized.
1153            If the allocations fails, HmacSha256New() returns NULL.
1154
1155 **/
1156 VOID *
1157 EFIAPI
1158 HmacSha256New (
1159   VOID
1160   );
1161
1162 /**
1163   Release the specified HMAC_CTX context.
1164
1165   @param[in]  HmacSha256Ctx  Pointer to the HMAC_CTX context to be released.
1166
1167 **/
1168 VOID
1169 EFIAPI
1170 HmacSha256Free (
1171   IN  VOID  *HmacSha256Ctx
1172   );
1173
1174 /**
1175   Set user-supplied key for subsequent use. It must be done before any
1176   calling to HmacSha256Update().
1177
1178   If HmacSha256Context is NULL, then return FALSE.
1179   If this interface is not supported, then return FALSE.
1180
1181   @param[out]  HmacSha256Context  Pointer to HMAC-SHA256 context.
1182   @param[in]   Key                Pointer to the user-supplied key.
1183   @param[in]   KeySize            Key size in bytes.
1184
1185   @retval TRUE   The Key is set successfully.
1186   @retval FALSE  The Key is set unsuccessfully.
1187   @retval FALSE  This interface is not supported.
1188
1189 **/
1190 BOOLEAN
1191 EFIAPI
1192 HmacSha256SetKey (
1193   OUT  VOID         *HmacSha256Context,
1194   IN   CONST UINT8  *Key,
1195   IN   UINTN        KeySize
1196   );
1197
1198 /**
1199   Makes a copy of an existing HMAC-SHA256 context.
1200
1201   If HmacSha256Context is NULL, then return FALSE.
1202   If NewHmacSha256Context is NULL, then return FALSE.
1203   If this interface is not supported, then return FALSE.
1204
1205   @param[in]  HmacSha256Context     Pointer to HMAC-SHA256 context being copied.
1206   @param[out] NewHmacSha256Context  Pointer to new HMAC-SHA256 context.
1207
1208   @retval TRUE   HMAC-SHA256 context copy succeeded.
1209   @retval FALSE  HMAC-SHA256 context copy failed.
1210   @retval FALSE  This interface is not supported.
1211
1212 **/
1213 BOOLEAN
1214 EFIAPI
1215 HmacSha256Duplicate (
1216   IN   CONST VOID  *HmacSha256Context,
1217   OUT  VOID        *NewHmacSha256Context
1218   );
1219
1220 /**
1221   Digests the input data and updates HMAC-SHA256 context.
1222
1223   This function performs HMAC-SHA256 digest on a data buffer of the specified size.
1224   It can be called multiple times to compute the digest of long or discontinuous data streams.
1225   HMAC-SHA256 context should be initialized by HmacSha256New(), and should not be finalized
1226   by HmacSha256Final(). Behavior with invalid context is undefined.
1227
1228   If HmacSha256Context is NULL, then return FALSE.
1229   If this interface is not supported, then return FALSE.
1230
1231   @param[in, out]  HmacSha256Context Pointer to the HMAC-SHA256 context.
1232   @param[in]       Data              Pointer to the buffer containing the data to be digested.
1233   @param[in]       DataSize          Size of Data buffer in bytes.
1234
1235   @retval TRUE   HMAC-SHA256 data digest succeeded.
1236   @retval FALSE  HMAC-SHA256 data digest failed.
1237   @retval FALSE  This interface is not supported.
1238
1239 **/
1240 BOOLEAN
1241 EFIAPI
1242 HmacSha256Update (
1243   IN OUT  VOID        *HmacSha256Context,
1244   IN      CONST VOID  *Data,
1245   IN      UINTN       DataSize
1246   );
1247
1248 /**
1249   Completes computation of the HMAC-SHA256 digest value.
1250
1251   This function completes HMAC-SHA256 hash computation and retrieves the digest value into
1252   the specified memory. After this function has been called, the HMAC-SHA256 context cannot
1253   be used again.
1254   HMAC-SHA256 context should be initialized by HmacSha256New(), and should not be finalized
1255   by HmacSha256Final(). Behavior with invalid HMAC-SHA256 context is undefined.
1256
1257   If HmacSha256Context is NULL, then return FALSE.
1258   If HmacValue is NULL, then return FALSE.
1259   If this interface is not supported, then return FALSE.
1260
1261   @param[in, out]  HmacSha256Context  Pointer to the HMAC-SHA256 context.
1262   @param[out]      HmacValue          Pointer to a buffer that receives the HMAC-SHA256 digest
1263                                       value (32 bytes).
1264
1265   @retval TRUE   HMAC-SHA256 digest computation succeeded.
1266   @retval FALSE  HMAC-SHA256 digest computation failed.
1267   @retval FALSE  This interface is not supported.
1268
1269 **/
1270 BOOLEAN
1271 EFIAPI
1272 HmacSha256Final (
1273   IN OUT  VOID   *HmacSha256Context,
1274   OUT     UINT8  *HmacValue
1275   );
1276
1277 //=====================================================================================
1278 //    Symmetric Cryptography Primitive
1279 //=====================================================================================
1280
1281 /**
1282   Retrieves the size, in bytes, of the context buffer required for TDES operations.
1283
1284   If this interface is not supported, then return zero.
1285
1286   @return  The size, in bytes, of the context buffer required for TDES operations.
1287   @retval  0   This interface is not supported.
1288
1289 **/
1290 UINTN
1291 EFIAPI
1292 TdesGetContextSize (
1293   VOID
1294   );
1295
1296 /**
1297   Initializes user-supplied memory as TDES context for subsequent use.
1298
1299   This function initializes user-supplied memory pointed by TdesContext as TDES context.
1300   In addition, it sets up all TDES key materials for subsequent encryption and decryption
1301   operations.
1302   There are 3 key options as follows:
1303   KeyLength = 64,  Keying option 1: K1 == K2 == K3 (Backward compatibility with DES)
1304   KeyLength = 128, Keying option 2: K1 != K2 and K3 = K1 (Less Security)
1305   KeyLength = 192  Keying option 3: K1 != K2 != K3 (Strongest)
1306
1307   If TdesContext is NULL, then return FALSE.
1308   If Key is NULL, then return FALSE.
1309   If KeyLength is not valid, then return FALSE.
1310   If this interface is not supported, then return FALSE.
1311
1312   @param[out]  TdesContext  Pointer to TDES context being initialized.
1313   @param[in]   Key          Pointer to the user-supplied TDES key.
1314   @param[in]   KeyLength    Length of TDES key in bits.
1315
1316   @retval TRUE   TDES context initialization succeeded.
1317   @retval FALSE  TDES context initialization failed.
1318   @retval FALSE  This interface is not supported.
1319
1320 **/
1321 BOOLEAN
1322 EFIAPI
1323 TdesInit (
1324   OUT  VOID         *TdesContext,
1325   IN   CONST UINT8  *Key,
1326   IN   UINTN        KeyLength
1327   );
1328
1329 /**
1330   Performs TDES encryption on a data buffer of the specified size in ECB mode.
1331
1332   This function performs TDES encryption on data buffer pointed by Input, of specified
1333   size of InputSize, in ECB mode.
1334   InputSize must be multiple of block size (8 bytes). This function does not perform
1335   padding. Caller must perform padding, if necessary, to ensure valid input data size.
1336   TdesContext should be already correctly initialized by TdesInit(). Behavior with
1337   invalid TDES context is undefined.
1338
1339   If TdesContext is NULL, then return FALSE.
1340   If Input is NULL, then return FALSE.
1341   If InputSize is not multiple of block size (8 bytes), then return FALSE.
1342   If Output is NULL, then return FALSE.
1343   If this interface is not supported, then return FALSE.
1344
1345   @param[in]   TdesContext  Pointer to the TDES context.
1346   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.
1347   @param[in]   InputSize    Size of the Input buffer in bytes.
1348   @param[out]  Output       Pointer to a buffer that receives the TDES encryption output.
1349
1350   @retval TRUE   TDES encryption succeeded.
1351   @retval FALSE  TDES encryption failed.
1352   @retval FALSE  This interface is not supported.
1353
1354 **/
1355 BOOLEAN
1356 EFIAPI
1357 TdesEcbEncrypt (
1358   IN   VOID         *TdesContext,
1359   IN   CONST UINT8  *Input,
1360   IN   UINTN        InputSize,
1361   OUT  UINT8        *Output
1362   );
1363
1364 /**
1365   Performs TDES decryption on a data buffer of the specified size in ECB mode.
1366
1367   This function performs TDES decryption on data buffer pointed by Input, of specified
1368   size of InputSize, in ECB mode.
1369   InputSize must be multiple of block size (8 bytes). This function does not perform
1370   padding. Caller must perform padding, if necessary, to ensure valid input data size.
1371   TdesContext should be already correctly initialized by TdesInit(). Behavior with
1372   invalid TDES context is undefined.
1373
1374   If TdesContext is NULL, then return FALSE.
1375   If Input is NULL, then return FALSE.
1376   If InputSize is not multiple of block size (8 bytes), then return FALSE.
1377   If Output is NULL, then return FALSE.
1378   If this interface is not supported, then return FALSE.
1379
1380   @param[in]   TdesContext  Pointer to the TDES context.
1381   @param[in]   Input        Pointer to the buffer containing the data to be decrypted.
1382   @param[in]   InputSize    Size of the Input buffer in bytes.
1383   @param[out]  Output       Pointer to a buffer that receives the TDES decryption output.
1384
1385   @retval TRUE   TDES decryption succeeded.
1386   @retval FALSE  TDES decryption failed.
1387   @retval FALSE  This interface is not supported.
1388
1389 **/
1390 BOOLEAN
1391 EFIAPI
1392 TdesEcbDecrypt (
1393   IN   VOID         *TdesContext,
1394   IN   CONST UINT8  *Input,
1395   IN   UINTN        InputSize,
1396   OUT  UINT8        *Output
1397   );
1398
1399 /**
1400   Performs TDES encryption on a data buffer of the specified size in CBC mode.
1401
1402   This function performs TDES encryption on data buffer pointed by Input, of specified
1403   size of InputSize, in CBC mode.
1404   InputSize must be multiple of block size (8 bytes). This function does not perform
1405   padding. Caller must perform padding, if necessary, to ensure valid input data size.
1406   Initialization vector should be one block size (8 bytes).
1407   TdesContext should be already correctly initialized by TdesInit(). Behavior with
1408   invalid TDES context is undefined.
1409
1410   If TdesContext is NULL, then return FALSE.
1411   If Input is NULL, then return FALSE.
1412   If InputSize is not multiple of block size (8 bytes), then return FALSE.
1413   If Ivec is NULL, then return FALSE.
1414   If Output is NULL, then return FALSE.
1415   If this interface is not supported, then return FALSE.
1416
1417   @param[in]   TdesContext  Pointer to the TDES context.
1418   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.
1419   @param[in]   InputSize    Size of the Input buffer in bytes.
1420   @param[in]   Ivec         Pointer to initialization vector.
1421   @param[out]  Output       Pointer to a buffer that receives the TDES encryption output.
1422
1423   @retval TRUE   TDES encryption succeeded.
1424   @retval FALSE  TDES encryption failed.
1425   @retval FALSE  This interface is not supported.
1426
1427 **/
1428 BOOLEAN
1429 EFIAPI
1430 TdesCbcEncrypt (
1431   IN   VOID         *TdesContext,
1432   IN   CONST UINT8  *Input,
1433   IN   UINTN        InputSize,
1434   IN   CONST UINT8  *Ivec,
1435   OUT  UINT8        *Output
1436   );
1437
1438 /**
1439   Performs TDES decryption on a data buffer of the specified size in CBC mode.
1440
1441   This function performs TDES decryption on data buffer pointed by Input, of specified
1442   size of InputSize, in CBC mode.
1443   InputSize must be multiple of block size (8 bytes). This function does not perform
1444   padding. Caller must perform padding, if necessary, to ensure valid input data size.
1445   Initialization vector should be one block size (8 bytes).
1446   TdesContext should be already correctly initialized by TdesInit(). Behavior with
1447   invalid TDES context is undefined.
1448
1449   If TdesContext is NULL, then return FALSE.
1450   If Input is NULL, then return FALSE.
1451   If InputSize is not multiple of block size (8 bytes), then return FALSE.
1452   If Ivec is NULL, then return FALSE.
1453   If Output is NULL, then return FALSE.
1454   If this interface is not supported, then return FALSE.
1455
1456   @param[in]   TdesContext  Pointer to the TDES context.
1457   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.
1458   @param[in]   InputSize    Size of the Input buffer in bytes.
1459   @param[in]   Ivec         Pointer to initialization vector.
1460   @param[out]  Output       Pointer to a buffer that receives the TDES encryption output.
1461
1462   @retval TRUE   TDES decryption succeeded.
1463   @retval FALSE  TDES decryption failed.
1464   @retval FALSE  This interface is not supported.
1465
1466 **/
1467 BOOLEAN
1468 EFIAPI
1469 TdesCbcDecrypt (
1470   IN   VOID         *TdesContext,
1471   IN   CONST UINT8  *Input,
1472   IN   UINTN        InputSize,
1473   IN   CONST UINT8  *Ivec,
1474   OUT  UINT8        *Output
1475   );
1476
1477 /**
1478   Retrieves the size, in bytes, of the context buffer required for AES operations.
1479
1480   If this interface is not supported, then return zero.
1481
1482   @return  The size, in bytes, of the context buffer required for AES operations.
1483   @retval  0   This interface is not supported.
1484
1485 **/
1486 UINTN
1487 EFIAPI
1488 AesGetContextSize (
1489   VOID
1490   );
1491
1492 /**
1493   Initializes user-supplied memory as AES context for subsequent use.
1494
1495   This function initializes user-supplied memory pointed by AesContext as AES context.
1496   In addition, it sets up all AES key materials for subsequent encryption and decryption
1497   operations.
1498   There are 3 options for key length, 128 bits, 192 bits, and 256 bits.
1499
1500   If AesContext is NULL, then return FALSE.
1501   If Key is NULL, then return FALSE.
1502   If KeyLength is not valid, then return FALSE.
1503   If this interface is not supported, then return FALSE.
1504
1505   @param[out]  AesContext  Pointer to AES context being initialized.
1506   @param[in]   Key         Pointer to the user-supplied AES key.
1507   @param[in]   KeyLength   Length of AES key in bits.
1508
1509   @retval TRUE   AES context initialization succeeded.
1510   @retval FALSE  AES context initialization failed.
1511   @retval FALSE  This interface is not supported.
1512
1513 **/
1514 BOOLEAN
1515 EFIAPI
1516 AesInit (
1517   OUT  VOID         *AesContext,
1518   IN   CONST UINT8  *Key,
1519   IN   UINTN        KeyLength
1520   );
1521
1522 /**
1523   Performs AES encryption on a data buffer of the specified size in ECB mode.
1524
1525   This function performs AES encryption on data buffer pointed by Input, of specified
1526   size of InputSize, in ECB mode.
1527   InputSize must be multiple of block size (16 bytes). This function does not perform
1528   padding. Caller must perform padding, if necessary, to ensure valid input data size.
1529   AesContext should be already correctly initialized by AesInit(). Behavior with
1530   invalid AES context is undefined.
1531
1532   If AesContext is NULL, then return FALSE.
1533   If Input is NULL, then return FALSE.
1534   If InputSize is not multiple of block size (16 bytes), then return FALSE.
1535   If Output is NULL, then return FALSE.
1536   If this interface is not supported, then return FALSE.
1537
1538   @param[in]   AesContext  Pointer to the AES context.
1539   @param[in]   Input       Pointer to the buffer containing the data to be encrypted.
1540   @param[in]   InputSize   Size of the Input buffer in bytes.
1541   @param[out]  Output      Pointer to a buffer that receives the AES encryption output.
1542
1543   @retval TRUE   AES encryption succeeded.
1544   @retval FALSE  AES encryption failed.
1545   @retval FALSE  This interface is not supported.
1546
1547 **/
1548 BOOLEAN
1549 EFIAPI
1550 AesEcbEncrypt (
1551   IN   VOID         *AesContext,
1552   IN   CONST UINT8  *Input,
1553   IN   UINTN        InputSize,
1554   OUT  UINT8        *Output
1555   );
1556
1557 /**
1558   Performs AES decryption on a data buffer of the specified size in ECB mode.
1559
1560   This function performs AES decryption on data buffer pointed by Input, of specified
1561   size of InputSize, in ECB mode.
1562   InputSize must be multiple of block size (16 bytes). This function does not perform
1563   padding. Caller must perform padding, if necessary, to ensure valid input data size.
1564   AesContext should be already correctly initialized by AesInit(). Behavior with
1565   invalid AES context is undefined.
1566
1567   If AesContext is NULL, then return FALSE.
1568   If Input is NULL, then return FALSE.
1569   If InputSize is not multiple of block size (16 bytes), then return FALSE.
1570   If Output is NULL, then return FALSE.
1571   If this interface is not supported, then return FALSE.
1572
1573   @param[in]   AesContext  Pointer to the AES context.
1574   @param[in]   Input       Pointer to the buffer containing the data to be decrypted.
1575   @param[in]   InputSize   Size of the Input buffer in bytes.
1576   @param[out]  Output      Pointer to a buffer that receives the AES decryption output.
1577
1578   @retval TRUE   AES decryption succeeded.
1579   @retval FALSE  AES decryption failed.
1580   @retval FALSE  This interface is not supported.
1581
1582 **/
1583 BOOLEAN
1584 EFIAPI
1585 AesEcbDecrypt (
1586   IN   VOID         *AesContext,
1587   IN   CONST UINT8  *Input,
1588   IN   UINTN        InputSize,
1589   OUT  UINT8        *Output
1590   );
1591
1592 /**
1593   Performs AES encryption on a data buffer of the specified size in CBC mode.
1594
1595   This function performs AES encryption on data buffer pointed by Input, of specified
1596   size of InputSize, in CBC mode.
1597   InputSize must be multiple of block size (16 bytes). This function does not perform
1598   padding. Caller must perform padding, if necessary, to ensure valid input data size.
1599   Initialization vector should be one block size (16 bytes).
1600   AesContext should be already correctly initialized by AesInit(). Behavior with
1601   invalid AES context is undefined.
1602
1603   If AesContext is NULL, then return FALSE.
1604   If Input is NULL, then return FALSE.
1605   If InputSize is not multiple of block size (16 bytes), then return FALSE.
1606   If Ivec is NULL, then return FALSE.
1607   If Output is NULL, then return FALSE.
1608   If this interface is not supported, then return FALSE.
1609
1610   @param[in]   AesContext  Pointer to the AES context.
1611   @param[in]   Input       Pointer to the buffer containing the data to be encrypted.
1612   @param[in]   InputSize   Size of the Input buffer in bytes.
1613   @param[in]   Ivec        Pointer to initialization vector.
1614   @param[out]  Output      Pointer to a buffer that receives the AES encryption output.
1615
1616   @retval TRUE   AES encryption succeeded.
1617   @retval FALSE  AES encryption failed.
1618   @retval FALSE  This interface is not supported.
1619
1620 **/
1621 BOOLEAN
1622 EFIAPI
1623 AesCbcEncrypt (
1624   IN   VOID         *AesContext,
1625   IN   CONST UINT8  *Input,
1626   IN   UINTN        InputSize,
1627   IN   CONST UINT8  *Ivec,
1628   OUT  UINT8        *Output
1629   );
1630
1631 /**
1632   Performs AES decryption on a data buffer of the specified size in CBC mode.
1633
1634   This function performs AES decryption on data buffer pointed by Input, of specified
1635   size of InputSize, in CBC mode.
1636   InputSize must be multiple of block size (16 bytes). This function does not perform
1637   padding. Caller must perform padding, if necessary, to ensure valid input data size.
1638   Initialization vector should be one block size (16 bytes).
1639   AesContext should be already correctly initialized by AesInit(). Behavior with
1640   invalid AES context is undefined.
1641
1642   If AesContext is NULL, then return FALSE.
1643   If Input is NULL, then return FALSE.
1644   If InputSize is not multiple of block size (16 bytes), then return FALSE.
1645   If Ivec is NULL, then return FALSE.
1646   If Output is NULL, then return FALSE.
1647   If this interface is not supported, then return FALSE.
1648
1649   @param[in]   AesContext  Pointer to the AES context.
1650   @param[in]   Input       Pointer to the buffer containing the data to be encrypted.
1651   @param[in]   InputSize   Size of the Input buffer in bytes.
1652   @param[in]   Ivec        Pointer to initialization vector.
1653   @param[out]  Output      Pointer to a buffer that receives the AES encryption output.
1654
1655   @retval TRUE   AES decryption succeeded.
1656   @retval FALSE  AES decryption failed.
1657   @retval FALSE  This interface is not supported.
1658
1659 **/
1660 BOOLEAN
1661 EFIAPI
1662 AesCbcDecrypt (
1663   IN   VOID         *AesContext,
1664   IN   CONST UINT8  *Input,
1665   IN   UINTN        InputSize,
1666   IN   CONST UINT8  *Ivec,
1667   OUT  UINT8        *Output
1668   );
1669
1670 /**
1671   Retrieves the size, in bytes, of the context buffer required for ARC4 operations.
1672
1673   If this interface is not supported, then return zero.
1674
1675   @return  The size, in bytes, of the context buffer required for ARC4 operations.
1676   @retval  0   This interface is not supported.
1677
1678 **/
1679 UINTN
1680 EFIAPI
1681 Arc4GetContextSize (
1682   VOID
1683   );
1684
1685 /**
1686   Initializes user-supplied memory as ARC4 context for subsequent use.
1687
1688   This function initializes user-supplied memory pointed by Arc4Context as ARC4 context.
1689   In addition, it sets up all ARC4 key materials for subsequent encryption and decryption
1690   operations.
1691
1692   If Arc4Context is NULL, then return FALSE.
1693   If Key is NULL, then return FALSE.
1694   If KeySize does not in the range of [5, 256] bytes, then return FALSE.
1695   If this interface is not supported, then return FALSE.
1696
1697   @param[out]  Arc4Context  Pointer to ARC4 context being initialized.
1698   @param[in]   Key          Pointer to the user-supplied ARC4 key.
1699   @param[in]   KeySize      Size of ARC4 key in bytes.
1700
1701   @retval TRUE   ARC4 context initialization succeeded.
1702   @retval FALSE  ARC4 context initialization failed.
1703   @retval FALSE  This interface is not supported.
1704
1705 **/
1706 BOOLEAN
1707 EFIAPI
1708 Arc4Init (
1709   OUT  VOID         *Arc4Context,
1710   IN   CONST UINT8  *Key,
1711   IN   UINTN        KeySize
1712   );
1713
1714 /**
1715   Performs ARC4 encryption on a data buffer of the specified size.
1716
1717   This function performs ARC4 encryption on data buffer pointed by Input, of specified
1718   size of InputSize.
1719   Arc4Context should be already correctly initialized by Arc4Init(). Behavior with
1720   invalid ARC4 context is undefined.
1721
1722   If Arc4Context is NULL, then return FALSE.
1723   If Input is NULL, then return FALSE.
1724   If Output is NULL, then return FALSE.
1725   If this interface is not supported, then return FALSE.
1726
1727   @param[in, out]  Arc4Context  Pointer to the ARC4 context.
1728   @param[in]       Input        Pointer to the buffer containing the data to be encrypted.
1729   @param[in]       InputSize    Size of the Input buffer in bytes.
1730   @param[out]      Output       Pointer to a buffer that receives the ARC4 encryption output.
1731
1732   @retval TRUE   ARC4 encryption succeeded.
1733   @retval FALSE  ARC4 encryption failed.
1734   @retval FALSE  This interface is not supported.
1735
1736 **/
1737 BOOLEAN
1738 EFIAPI
1739 Arc4Encrypt (
1740   IN OUT  VOID         *Arc4Context,
1741   IN      CONST UINT8  *Input,
1742   IN      UINTN        InputSize,
1743   OUT     UINT8        *Output
1744   );
1745
1746 /**
1747   Performs ARC4 decryption on a data buffer of the specified size.
1748
1749   This function performs ARC4 decryption on data buffer pointed by Input, of specified
1750   size of InputSize.
1751   Arc4Context should be already correctly initialized by Arc4Init(). Behavior with
1752   invalid ARC4 context is undefined.
1753
1754   If Arc4Context is NULL, then return FALSE.
1755   If Input is NULL, then return FALSE.
1756   If Output is NULL, then return FALSE.
1757   If this interface is not supported, then return FALSE.
1758
1759   @param[in, out]  Arc4Context  Pointer to the ARC4 context.
1760   @param[in]       Input        Pointer to the buffer containing the data to be decrypted.
1761   @param[in]       InputSize    Size of the Input buffer in bytes.
1762   @param[out]      Output       Pointer to a buffer that receives the ARC4 decryption output.
1763
1764   @retval TRUE   ARC4 decryption succeeded.
1765   @retval FALSE  ARC4 decryption failed.
1766   @retval FALSE  This interface is not supported.
1767
1768 **/
1769 BOOLEAN
1770 EFIAPI
1771 Arc4Decrypt (
1772   IN OUT  VOID   *Arc4Context,
1773   IN      UINT8  *Input,
1774   IN      UINTN  InputSize,
1775   OUT     UINT8  *Output
1776   );
1777
1778 /**
1779   Resets the ARC4 context to the initial state.
1780
1781   The function resets the ARC4 context to the state it had immediately after the
1782   ARC4Init() function call.
1783   Contrary to ARC4Init(), Arc4Reset() requires no secret key as input, but ARC4 context
1784   should be already correctly initialized by ARC4Init().
1785
1786   If Arc4Context is NULL, then return FALSE.
1787   If this interface is not supported, then return FALSE.
1788
1789   @param[in, out]  Arc4Context  Pointer to the ARC4 context.
1790
1791   @retval TRUE   ARC4 reset succeeded.
1792   @retval FALSE  ARC4 reset failed.
1793   @retval FALSE  This interface is not supported.
1794
1795 **/
1796 BOOLEAN
1797 EFIAPI
1798 Arc4Reset (
1799   IN OUT  VOID  *Arc4Context
1800   );
1801
1802 //=====================================================================================
1803 //    Asymmetric Cryptography Primitive
1804 //=====================================================================================
1805
1806 /**
1807   Allocates and initializes one RSA context for subsequent use.
1808
1809   @return  Pointer to the RSA context that has been initialized.
1810            If the allocations fails, RsaNew() returns NULL.
1811
1812 **/
1813 VOID *
1814 EFIAPI
1815 RsaNew (
1816   VOID
1817   );
1818
1819 /**
1820   Release the specified RSA context.
1821
1822   If RsaContext is NULL, then return FALSE.
1823
1824   @param[in]  RsaContext  Pointer to the RSA context to be released.
1825
1826 **/
1827 VOID
1828 EFIAPI
1829 RsaFree (
1830   IN  VOID  *RsaContext
1831   );
1832
1833 /**
1834   Sets the tag-designated key component into the established RSA context.
1835
1836   This function sets the tag-designated RSA key component into the established
1837   RSA context from the user-specified non-negative integer (octet string format
1838   represented in RSA PKCS#1).
1839   If BigNumber is NULL, then the specified key component in RSA context is cleared.
1840
1841   If RsaContext is NULL, then return FALSE.
1842
1843   @param[in, out]  RsaContext  Pointer to RSA context being set.
1844   @param[in]       KeyTag      Tag of RSA key component being set.
1845   @param[in]       BigNumber   Pointer to octet integer buffer.
1846                                If NULL, then the specified key component in RSA
1847                                context is cleared.
1848   @param[in]       BnSize      Size of big number buffer in bytes.
1849                                If BigNumber is NULL, then it is ignored.
1850
1851   @retval  TRUE   RSA key component was set successfully.
1852   @retval  FALSE  Invalid RSA key component tag.
1853
1854 **/
1855 BOOLEAN
1856 EFIAPI
1857 RsaSetKey (
1858   IN OUT  VOID         *RsaContext,
1859   IN      RSA_KEY_TAG  KeyTag,
1860   IN      CONST UINT8  *BigNumber,
1861   IN      UINTN        BnSize
1862   );
1863
1864 /**
1865   Gets the tag-designated RSA key component from the established RSA context.
1866
1867   This function retrieves the tag-designated RSA key component from the
1868   established RSA context as a non-negative integer (octet string format
1869   represented in RSA PKCS#1).
1870   If specified key component has not been set or has been cleared, then returned
1871   BnSize is set to 0.
1872   If the BigNumber buffer is too small to hold the contents of the key, FALSE
1873   is returned and BnSize is set to the required buffer size to obtain the key.
1874
1875   If RsaContext is NULL, then return FALSE.
1876   If BnSize is NULL, then return FALSE.
1877   If BnSize is large enough but BigNumber is NULL, then return FALSE.
1878   If this interface is not supported, then return FALSE.
1879
1880   @param[in, out]  RsaContext  Pointer to RSA context being set.
1881   @param[in]       KeyTag      Tag of RSA key component being set.
1882   @param[out]      BigNumber   Pointer to octet integer buffer.
1883   @param[in, out]  BnSize      On input, the size of big number buffer in bytes.
1884                                On output, the size of data returned in big number buffer in bytes.
1885
1886   @retval  TRUE   RSA key component was retrieved successfully.
1887   @retval  FALSE  Invalid RSA key component tag.
1888   @retval  FALSE  BnSize is too small.
1889   @retval  FALSE  This interface is not supported.
1890
1891 **/
1892 BOOLEAN
1893 EFIAPI
1894 RsaGetKey (
1895   IN OUT  VOID         *RsaContext,
1896   IN      RSA_KEY_TAG  KeyTag,
1897   OUT     UINT8        *BigNumber,
1898   IN OUT  UINTN        *BnSize
1899   );
1900
1901 /**
1902   Generates RSA key components.
1903
1904   This function generates RSA key components. It takes RSA public exponent E and
1905   length in bits of RSA modulus N as input, and generates all key components.
1906   If PublicExponent is NULL, the default RSA public exponent (0x10001) will be used.
1907
1908   Before this function can be invoked, pseudorandom number generator must be correctly
1909   initialized by RandomSeed().
1910
1911   If RsaContext is NULL, then return FALSE.
1912   If this interface is not supported, then return FALSE.
1913
1914   @param[in, out]  RsaContext           Pointer to RSA context being set.
1915   @param[in]       ModulusLength        Length of RSA modulus N in bits.
1916   @param[in]       PublicExponent       Pointer to RSA public exponent.
1917   @param[in]       PublicExponentSize   Size of RSA public exponent buffer in bytes.
1918
1919   @retval  TRUE   RSA key component was generated successfully.
1920   @retval  FALSE  Invalid RSA key component tag.
1921   @retval  FALSE  This interface is not supported.
1922
1923 **/
1924 BOOLEAN
1925 EFIAPI
1926 RsaGenerateKey (
1927   IN OUT  VOID         *RsaContext,
1928   IN      UINTN        ModulusLength,
1929   IN      CONST UINT8  *PublicExponent,
1930   IN      UINTN        PublicExponentSize
1931   );
1932
1933 /**
1934   Validates key components of RSA context.
1935   NOTE: This function performs integrity checks on all the RSA key material, so
1936         the RSA key structure must contain all the private key data.
1937
1938   This function validates key components of RSA context in following aspects:
1939   - Whether p is a prime
1940   - Whether q is a prime
1941   - Whether n = p * q
1942   - Whether d*e = 1  mod lcm(p-1,q-1)
1943
1944   If RsaContext is NULL, then return FALSE.
1945   If this interface is not supported, then return FALSE.
1946
1947   @param[in]  RsaContext  Pointer to RSA context to check.
1948
1949   @retval  TRUE   RSA key components are valid.
1950   @retval  FALSE  RSA key components are not valid.
1951   @retval  FALSE  This interface is not supported.
1952
1953 **/
1954 BOOLEAN
1955 EFIAPI
1956 RsaCheckKey (
1957   IN  VOID  *RsaContext
1958   );
1959
1960 /**
1961   Carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme.
1962
1963   This function carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme defined in
1964   RSA PKCS#1.
1965   If the Signature buffer is too small to hold the contents of signature, FALSE
1966   is returned and SigSize is set to the required buffer size to obtain the signature.
1967
1968   If RsaContext is NULL, then return FALSE.
1969   If MessageHash is NULL, then return FALSE.
1970   If HashSize is not equal to the size of MD5, SHA-1 or SHA-256 digest, then return FALSE.
1971   If SigSize is large enough but Signature is NULL, then return FALSE.
1972   If this interface is not supported, then return FALSE.
1973
1974   @param[in]      RsaContext   Pointer to RSA context for signature generation.
1975   @param[in]      MessageHash  Pointer to octet message hash to be signed.
1976   @param[in]      HashSize     Size of the message hash in bytes.
1977   @param[out]     Signature    Pointer to buffer to receive RSA PKCS1-v1_5 signature.
1978   @param[in, out] SigSize      On input, the size of Signature buffer in bytes.
1979                                On output, the size of data returned in Signature buffer in bytes.
1980
1981   @retval  TRUE   Signature successfully generated in PKCS1-v1_5.
1982   @retval  FALSE  Signature generation failed.
1983   @retval  FALSE  SigSize is too small.
1984   @retval  FALSE  This interface is not supported.
1985
1986 **/
1987 BOOLEAN
1988 EFIAPI
1989 RsaPkcs1Sign (
1990   IN      VOID         *RsaContext,
1991   IN      CONST UINT8  *MessageHash,
1992   IN      UINTN        HashSize,
1993   OUT     UINT8        *Signature,
1994   IN OUT  UINTN        *SigSize
1995   );
1996
1997 /**
1998   Verifies the RSA-SSA signature with EMSA-PKCS1-v1_5 encoding scheme defined in
1999   RSA PKCS#1.
2000
2001   If RsaContext is NULL, then return FALSE.
2002   If MessageHash is NULL, then return FALSE.
2003   If Signature is NULL, then return FALSE.
2004   If HashSize is not equal to the size of MD5, SHA-1, SHA-256 digest, then return FALSE.
2005
2006   @param[in]  RsaContext   Pointer to RSA context for signature verification.
2007   @param[in]  MessageHash  Pointer to octet message hash to be checked.
2008   @param[in]  HashSize     Size of the message hash in bytes.
2009   @param[in]  Signature    Pointer to RSA PKCS1-v1_5 signature to be verified.
2010   @param[in]  SigSize      Size of signature in bytes.
2011
2012   @retval  TRUE   Valid signature encoded in PKCS1-v1_5.
2013   @retval  FALSE  Invalid signature or invalid RSA context.
2014
2015 **/
2016 BOOLEAN
2017 EFIAPI
2018 RsaPkcs1Verify (
2019   IN  VOID         *RsaContext,
2020   IN  CONST UINT8  *MessageHash,
2021   IN  UINTN        HashSize,
2022   IN  CONST UINT8  *Signature,
2023   IN  UINTN        SigSize
2024   );
2025
2026 /**
2027   Retrieve the RSA Private Key from the password-protected PEM key data.
2028
2029   If PemData is NULL, then return FALSE.
2030   If RsaContext is NULL, then return FALSE.
2031   If this interface is not supported, then return FALSE.
2032
2033   @param[in]  PemData      Pointer to the PEM-encoded key data to be retrieved.
2034   @param[in]  PemSize      Size of the PEM key data in bytes.
2035   @param[in]  Password     NULL-terminated passphrase used for encrypted PEM key data.
2036   @param[out] RsaContext   Pointer to new-generated RSA context which contain the retrieved
2037                            RSA private key component. Use RsaFree() function to free the
2038                            resource.
2039
2040   @retval  TRUE   RSA Private Key was retrieved successfully.
2041   @retval  FALSE  Invalid PEM key data or incorrect password.
2042   @retval  FALSE  This interface is not supported.
2043
2044 **/
2045 BOOLEAN
2046 EFIAPI
2047 RsaGetPrivateKeyFromPem (
2048   IN   CONST UINT8  *PemData,
2049   IN   UINTN        PemSize,
2050   IN   CONST CHAR8  *Password,
2051   OUT  VOID         **RsaContext
2052   );
2053
2054 /**
2055   Retrieve the RSA Public Key from one DER-encoded X509 certificate.
2056
2057   If Cert is NULL, then return FALSE.
2058   If RsaContext is NULL, then return FALSE.
2059   If this interface is not supported, then return FALSE.
2060
2061   @param[in]  Cert         Pointer to the DER-encoded X509 certificate.
2062   @param[in]  CertSize     Size of the X509 certificate in bytes.
2063   @param[out] RsaContext   Pointer to new-generated RSA context which contain the retrieved
2064                            RSA public key component. Use RsaFree() function to free the
2065                            resource.
2066
2067   @retval  TRUE   RSA Public Key was retrieved successfully.
2068   @retval  FALSE  Fail to retrieve RSA public key from X509 certificate.
2069   @retval  FALSE  This interface is not supported.
2070
2071 **/
2072 BOOLEAN
2073 EFIAPI
2074 RsaGetPublicKeyFromX509 (
2075   IN   CONST UINT8  *Cert,
2076   IN   UINTN        CertSize,
2077   OUT  VOID         **RsaContext
2078   );
2079
2080 /**
2081   Retrieve the subject bytes from one X.509 certificate.
2082
2083   If Cert is NULL, then return FALSE.
2084   If SubjectSize is NULL, then return FALSE.
2085   If this interface is not supported, then return FALSE.
2086
2087   @param[in]      Cert         Pointer to the DER-encoded X509 certificate.
2088   @param[in]      CertSize     Size of the X509 certificate in bytes.
2089   @param[out]     CertSubject  Pointer to the retrieved certificate subject bytes.
2090   @param[in, out] SubjectSize  The size in bytes of the CertSubject buffer on input,
2091                                and the size of buffer returned CertSubject on output.
2092
2093   @retval  TRUE   The certificate subject retrieved successfully.
2094   @retval  FALSE  Invalid certificate, or the SubjectSize is too small for the result.
2095                   The SubjectSize will be updated with the required size.
2096   @retval  FALSE  This interface is not supported.
2097
2098 **/
2099 BOOLEAN
2100 EFIAPI
2101 X509GetSubjectName (
2102   IN      CONST UINT8  *Cert,
2103   IN      UINTN        CertSize,
2104   OUT     UINT8        *CertSubject,
2105   IN OUT  UINTN        *SubjectSize
2106   );
2107
2108 /**
2109   Retrieve the common name (CN) string from one X.509 certificate.
2110
2111   @param[in]      Cert             Pointer to the DER-encoded X509 certificate.
2112   @param[in]      CertSize         Size of the X509 certificate in bytes.
2113   @param[out]     CommonName       Buffer to contain the retrieved certificate common
2114                                    name string (UTF8). At most CommonNameSize bytes will be
2115                                    written and the string will be null terminated. May be
2116                                    NULL in order to determine the size buffer needed.
2117   @param[in,out]  CommonNameSize   The size in bytes of the CommonName buffer on input,
2118                                    and the size of buffer returned CommonName on output.
2119                                    If CommonName is NULL then the amount of space needed
2120                                    in buffer (including the final null) is returned.
2121
2122   @retval RETURN_SUCCESS           The certificate CommonName retrieved successfully.
2123   @retval RETURN_INVALID_PARAMETER If Cert is NULL.
2124                                    If CommonNameSize is NULL.
2125                                    If CommonName is not NULL and *CommonNameSize is 0.
2126                                    If Certificate is invalid.
2127   @retval RETURN_NOT_FOUND         If no CommonName entry exists.
2128   @retval RETURN_BUFFER_TOO_SMALL  If the CommonName is NULL. The required buffer size
2129                                    (including the final null) is returned in the
2130                                    CommonNameSize parameter.
2131   @retval RETURN_UNSUPPORTED       The operation is not supported.
2132
2133 **/
2134 RETURN_STATUS
2135 EFIAPI
2136 X509GetCommonName (
2137   IN      CONST UINT8  *Cert,
2138   IN      UINTN        CertSize,
2139   OUT     CHAR8        *CommonName,  OPTIONAL
2140   IN OUT  UINTN        *CommonNameSize
2141   );
2142
2143 /**
2144   Retrieve the organization name (O) string from one X.509 certificate.
2145
2146   @param[in]      Cert             Pointer to the DER-encoded X509 certificate.
2147   @param[in]      CertSize         Size of the X509 certificate in bytes.
2148   @param[out]     NameBuffer       Buffer to contain the retrieved certificate organization
2149                                    name string. At most NameBufferSize bytes will be
2150                                    written and the string will be null terminated. May be
2151                                    NULL in order to determine the size buffer needed.
2152   @param[in,out]  NameBufferSize   The size in bytes of the Name buffer on input,
2153                                    and the size of buffer returned Name on output.
2154                                    If NameBuffer is NULL then the amount of space needed
2155                                    in buffer (including the final null) is returned.
2156
2157   @retval RETURN_SUCCESS           The certificate Organization Name retrieved successfully.
2158   @retval RETURN_INVALID_PARAMETER If Cert is NULL.
2159                                    If NameBufferSize is NULL.
2160                                    If NameBuffer is not NULL and *CommonNameSize is 0.
2161                                    If Certificate is invalid.
2162   @retval RETURN_NOT_FOUND         If no Organization Name entry exists.
2163   @retval RETURN_BUFFER_TOO_SMALL  If the NameBuffer is NULL. The required buffer size
2164                                    (including the final null) is returned in the
2165                                    CommonNameSize parameter.
2166   @retval RETURN_UNSUPPORTED       The operation is not supported.
2167
2168 **/
2169 RETURN_STATUS
2170 EFIAPI
2171 X509GetOrganizationName (
2172   IN      CONST UINT8   *Cert,
2173   IN      UINTN         CertSize,
2174   OUT     CHAR8         *NameBuffer,  OPTIONAL
2175   IN OUT  UINTN         *NameBufferSize
2176   );
2177
2178 /**
2179   Verify one X509 certificate was issued by the trusted CA.
2180
2181   If Cert is NULL, then return FALSE.
2182   If CACert is NULL, then return FALSE.
2183   If this interface is not supported, then return FALSE.
2184
2185   @param[in]      Cert         Pointer to the DER-encoded X509 certificate to be verified.
2186   @param[in]      CertSize     Size of the X509 certificate in bytes.
2187   @param[in]      CACert       Pointer to the DER-encoded trusted CA certificate.
2188   @param[in]      CACertSize   Size of the CA Certificate in bytes.
2189
2190   @retval  TRUE   The certificate was issued by the trusted CA.
2191   @retval  FALSE  Invalid certificate or the certificate was not issued by the given
2192                   trusted CA.
2193   @retval  FALSE  This interface is not supported.
2194
2195 **/
2196 BOOLEAN
2197 EFIAPI
2198 X509VerifyCert (
2199   IN  CONST UINT8  *Cert,
2200   IN  UINTN        CertSize,
2201   IN  CONST UINT8  *CACert,
2202   IN  UINTN        CACertSize
2203   );
2204
2205 /**
2206   Construct a X509 object from DER-encoded certificate data.
2207
2208   If Cert is NULL, then return FALSE.
2209   If SingleX509Cert is NULL, then return FALSE.
2210   If this interface is not supported, then return FALSE.
2211
2212   @param[in]  Cert            Pointer to the DER-encoded certificate data.
2213   @param[in]  CertSize        The size of certificate data in bytes.
2214   @param[out] SingleX509Cert  The generated X509 object.
2215
2216   @retval     TRUE            The X509 object generation succeeded.
2217   @retval     FALSE           The operation failed.
2218   @retval     FALSE           This interface is not supported.
2219
2220 **/
2221 BOOLEAN
2222 EFIAPI
2223 X509ConstructCertificate (
2224   IN   CONST UINT8  *Cert,
2225   IN   UINTN        CertSize,
2226   OUT  UINT8        **SingleX509Cert
2227   );
2228
2229 /**
2230   Construct a X509 stack object from a list of DER-encoded certificate data.
2231
2232   If X509Stack is NULL, then return FALSE.
2233   If this interface is not supported, then return FALSE.
2234
2235   @param[in, out]  X509Stack  On input, pointer to an existing or NULL X509 stack object.
2236                               On output, pointer to the X509 stack object with new
2237                               inserted X509 certificate.
2238   @param[in]       Args       VA_LIST marker for the variable argument list.
2239                               A list of DER-encoded single certificate data followed
2240                               by certificate size. A NULL terminates the list. The
2241                               pairs are the arguments to X509ConstructCertificate().
2242
2243   @retval     TRUE            The X509 stack construction succeeded.
2244   @retval     FALSE           The construction operation failed.
2245   @retval     FALSE           This interface is not supported.
2246
2247 **/
2248 BOOLEAN
2249 EFIAPI
2250 X509ConstructCertificateStackV (
2251   IN OUT  UINT8    **X509Stack,
2252   IN      VA_LIST  Args
2253   );
2254
2255 /**
2256   Construct a X509 stack object from a list of DER-encoded certificate data.
2257
2258   If X509Stack is NULL, then return FALSE.
2259   If this interface is not supported, then return FALSE.
2260
2261   @param[in, out]  X509Stack  On input, pointer to an existing or NULL X509 stack object.
2262                               On output, pointer to the X509 stack object with new
2263                               inserted X509 certificate.
2264   @param           ...        A list of DER-encoded single certificate data followed
2265                               by certificate size. A NULL terminates the list. The
2266                               pairs are the arguments to X509ConstructCertificate().
2267
2268   @retval     TRUE            The X509 stack construction succeeded.
2269   @retval     FALSE           The construction operation failed.
2270   @retval     FALSE           This interface is not supported.
2271
2272 **/
2273 BOOLEAN
2274 EFIAPI
2275 X509ConstructCertificateStack (
2276   IN OUT  UINT8  **X509Stack,
2277   ...
2278   );
2279
2280 /**
2281   Release the specified X509 object.
2282
2283   If the interface is not supported, then ASSERT().
2284
2285   @param[in]  X509Cert  Pointer to the X509 object to be released.
2286
2287 **/
2288 VOID
2289 EFIAPI
2290 X509Free (
2291   IN  VOID  *X509Cert
2292   );
2293
2294 /**
2295   Release the specified X509 stack object.
2296
2297   If the interface is not supported, then ASSERT().
2298
2299   @param[in]  X509Stack  Pointer to the X509 stack object to be released.
2300
2301 **/
2302 VOID
2303 EFIAPI
2304 X509StackFree (
2305   IN  VOID  *X509Stack
2306   );
2307
2308 /**
2309   Retrieve the TBSCertificate from one given X.509 certificate.
2310
2311   @param[in]      Cert         Pointer to the given DER-encoded X509 certificate.
2312   @param[in]      CertSize     Size of the X509 certificate in bytes.
2313   @param[out]     TBSCert      DER-Encoded To-Be-Signed certificate.
2314   @param[out]     TBSCertSize  Size of the TBS certificate in bytes.
2315
2316   If Cert is NULL, then return FALSE.
2317   If TBSCert is NULL, then return FALSE.
2318   If TBSCertSize is NULL, then return FALSE.
2319   If this interface is not supported, then return FALSE.
2320
2321   @retval  TRUE   The TBSCertificate was retrieved successfully.
2322   @retval  FALSE  Invalid X.509 certificate.
2323
2324 **/
2325 BOOLEAN
2326 EFIAPI
2327 X509GetTBSCert (
2328   IN  CONST UINT8  *Cert,
2329   IN  UINTN        CertSize,
2330   OUT UINT8        **TBSCert,
2331   OUT UINTN        *TBSCertSize
2332   );
2333
2334 /**
2335   Derives a key from a password using a salt and iteration count, based on PKCS#5 v2.0
2336   password based encryption key derivation function PBKDF2, as specified in RFC 2898.
2337
2338   If Password or Salt or OutKey is NULL, then return FALSE.
2339   If the hash algorithm could not be determined, then return FALSE.
2340   If this interface is not supported, then return FALSE.
2341
2342   @param[in]  PasswordLength  Length of input password in bytes.
2343   @param[in]  Password        Pointer to the array for the password.
2344   @param[in]  SaltLength      Size of the Salt in bytes.
2345   @param[in]  Salt            Pointer to the Salt.
2346   @param[in]  IterationCount  Number of iterations to perform. Its value should be
2347                               greater than or equal to 1.
2348   @param[in]  DigestSize      Size of the message digest to be used (eg. SHA256_DIGEST_SIZE).
2349                               NOTE: DigestSize will be used to determine the hash algorithm.
2350                                     Only SHA1_DIGEST_SIZE or SHA256_DIGEST_SIZE is supported.
2351   @param[in]  KeyLength       Size of the derived key buffer in bytes.
2352   @param[out] OutKey          Pointer to the output derived key buffer.
2353
2354   @retval  TRUE   A key was derived successfully.
2355   @retval  FALSE  One of the pointers was NULL or one of the sizes was too large.
2356   @retval  FALSE  The hash algorithm could not be determined from the digest size.
2357   @retval  FALSE  The key derivation operation failed.
2358   @retval  FALSE  This interface is not supported.
2359
2360 **/
2361 BOOLEAN
2362 EFIAPI
2363 Pkcs5HashPassword (
2364   IN  UINTN        PasswordLength,
2365   IN  CONST CHAR8  *Password,
2366   IN  UINTN        SaltLength,
2367   IN  CONST UINT8  *Salt,
2368   IN  UINTN        IterationCount,
2369   IN  UINTN        DigestSize,
2370   IN  UINTN        KeyLength,
2371   OUT UINT8        *OutKey
2372   );
2373
2374 /**
2375   Encrypts a blob using PKCS1v2 (RSAES-OAEP) schema. On success, will return the
2376   encrypted message in a newly allocated buffer.
2377
2378   Things that can cause a failure include:
2379   - X509 key size does not match any known key size.
2380   - Fail to parse X509 certificate.
2381   - Fail to allocate an intermediate buffer.
2382   - Null pointer provided for a non-optional parameter.
2383   - Data size is too large for the provided key size (max size is a function of key size
2384     and hash digest size).
2385
2386   @param[in]  PublicKey           A pointer to the DER-encoded X509 certificate that
2387                                   will be used to encrypt the data.
2388   @param[in]  PublicKeySize       Size of the X509 cert buffer.
2389   @param[in]  InData              Data to be encrypted.
2390   @param[in]  InDataSize          Size of the data buffer.
2391   @param[in]  PrngSeed            [Optional] If provided, a pointer to a random seed buffer
2392                                   to be used when initializing the PRNG. NULL otherwise.
2393   @param[in]  PrngSeedSize        [Optional] If provided, size of the random seed buffer.
2394                                   0 otherwise.
2395   @param[out] EncryptedData       Pointer to an allocated buffer containing the encrypted
2396                                   message.
2397   @param[out] EncryptedDataSize   Size of the encrypted message buffer.
2398
2399   @retval     TRUE                Encryption was successful.
2400   @retval     FALSE               Encryption failed.
2401
2402 **/
2403 BOOLEAN
2404 EFIAPI
2405 Pkcs1v2Encrypt (
2406   IN   CONST UINT8  *PublicKey,
2407   IN   UINTN        PublicKeySize,
2408   IN   UINT8        *InData,
2409   IN   UINTN        InDataSize,
2410   IN   CONST UINT8  *PrngSeed,  OPTIONAL
2411   IN   UINTN        PrngSeedSize,  OPTIONAL
2412   OUT  UINT8        **EncryptedData,
2413   OUT  UINTN        *EncryptedDataSize
2414   );
2415
2416 /**
2417   The 3rd parameter of Pkcs7GetSigners will return all embedded
2418   X.509 certificate in one given PKCS7 signature. The format is:
2419   //
2420   // UINT8  CertNumber;
2421   // UINT32 Cert1Length;
2422   // UINT8  Cert1[];
2423   // UINT32 Cert2Length;
2424   // UINT8  Cert2[];
2425   // ...
2426   // UINT32 CertnLength;
2427   // UINT8  Certn[];
2428   //
2429
2430   The two following C-structure are used for parsing CertStack more clearly.
2431 **/
2432 #pragma pack(1)
2433
2434 typedef struct {
2435   UINT32    CertDataLength;       // The length in bytes of X.509 certificate.
2436   UINT8     CertDataBuffer[0];    // The X.509 certificate content (DER).
2437 } EFI_CERT_DATA;
2438
2439 typedef struct {
2440   UINT8             CertNumber;   // Number of X.509 certificate.
2441   //EFI_CERT_DATA   CertArray[];  // An array of X.509 certificate.
2442 } EFI_CERT_STACK;
2443
2444 #pragma pack()
2445
2446 /**
2447   Get the signer's certificates from PKCS#7 signed data as described in "PKCS #7:
2448   Cryptographic Message Syntax Standard". The input signed data could be wrapped
2449   in a ContentInfo structure.
2450
2451   If P7Data, CertStack, StackLength, TrustedCert or CertLength is NULL, then
2452   return FALSE. If P7Length overflow, then return FALSE.
2453   If this interface is not supported, then return FALSE.
2454
2455   @param[in]  P7Data       Pointer to the PKCS#7 message to verify.
2456   @param[in]  P7Length     Length of the PKCS#7 message in bytes.
2457   @param[out] CertStack    Pointer to Signer's certificates retrieved from P7Data.
2458                            It's caller's responsibility to free the buffer with
2459                            Pkcs7FreeSigners().
2460                            This data structure is EFI_CERT_STACK type.
2461   @param[out] StackLength  Length of signer's certificates in bytes.
2462   @param[out] TrustedCert  Pointer to a trusted certificate from Signer's certificates.
2463                            It's caller's responsibility to free the buffer with
2464                            Pkcs7FreeSigners().
2465   @param[out] CertLength   Length of the trusted certificate in bytes.
2466
2467   @retval  TRUE            The operation is finished successfully.
2468   @retval  FALSE           Error occurs during the operation.
2469   @retval  FALSE           This interface is not supported.
2470
2471 **/
2472 BOOLEAN
2473 EFIAPI
2474 Pkcs7GetSigners (
2475   IN  CONST UINT8  *P7Data,
2476   IN  UINTN        P7Length,
2477   OUT UINT8        **CertStack,
2478   OUT UINTN        *StackLength,
2479   OUT UINT8        **TrustedCert,
2480   OUT UINTN        *CertLength
2481   );
2482
2483 /**
2484   Wrap function to use free() to free allocated memory for certificates.
2485
2486   If this interface is not supported, then ASSERT().
2487
2488   @param[in]  Certs        Pointer to the certificates to be freed.
2489
2490 **/
2491 VOID
2492 EFIAPI
2493 Pkcs7FreeSigners (
2494   IN  UINT8        *Certs
2495   );
2496
2497 /**
2498   Retrieves all embedded certificates from PKCS#7 signed data as described in "PKCS #7:
2499   Cryptographic Message Syntax Standard", and outputs two certificate lists chained and
2500   unchained to the signer's certificates.
2501   The input signed data could be wrapped in a ContentInfo structure.
2502
2503   @param[in]  P7Data            Pointer to the PKCS#7 message.
2504   @param[in]  P7Length          Length of the PKCS#7 message in bytes.
2505   @param[out] SignerChainCerts  Pointer to the certificates list chained to signer's
2506                                 certificate. It's caller's responsibility to free the buffer
2507                                 with Pkcs7FreeSigners().
2508                                 This data structure is EFI_CERT_STACK type.
2509   @param[out] ChainLength       Length of the chained certificates list buffer in bytes.
2510   @param[out] UnchainCerts      Pointer to the unchained certificates lists. It's caller's
2511                                 responsibility to free the buffer with Pkcs7FreeSigners().
2512                                 This data structure is EFI_CERT_STACK type.
2513   @param[out] UnchainLength     Length of the unchained certificates list buffer in bytes.
2514
2515   @retval  TRUE         The operation is finished successfully.
2516   @retval  FALSE        Error occurs during the operation.
2517
2518 **/
2519 BOOLEAN
2520 EFIAPI
2521 Pkcs7GetCertificatesList (
2522   IN  CONST UINT8  *P7Data,
2523   IN  UINTN        P7Length,
2524   OUT UINT8        **SignerChainCerts,
2525   OUT UINTN        *ChainLength,
2526   OUT UINT8        **UnchainCerts,
2527   OUT UINTN        *UnchainLength
2528   );
2529
2530 /**
2531   Creates a PKCS#7 signedData as described in "PKCS #7: Cryptographic Message
2532   Syntax Standard, version 1.5". This interface is only intended to be used for
2533   application to perform PKCS#7 functionality validation.
2534
2535   If this interface is not supported, then return FALSE.
2536
2537   @param[in]  PrivateKey       Pointer to the PEM-formatted private key data for
2538                                data signing.
2539   @param[in]  PrivateKeySize   Size of the PEM private key data in bytes.
2540   @param[in]  KeyPassword      NULL-terminated passphrase used for encrypted PEM
2541                                key data.
2542   @param[in]  InData           Pointer to the content to be signed.
2543   @param[in]  InDataSize       Size of InData in bytes.
2544   @param[in]  SignCert         Pointer to signer's DER-encoded certificate to sign with.
2545   @param[in]  OtherCerts       Pointer to an optional additional set of certificates to
2546                                include in the PKCS#7 signedData (e.g. any intermediate
2547                                CAs in the chain).
2548   @param[out] SignedData       Pointer to output PKCS#7 signedData. It's caller's
2549                                responsibility to free the buffer with FreePool().
2550   @param[out] SignedDataSize   Size of SignedData in bytes.
2551
2552   @retval     TRUE             PKCS#7 data signing succeeded.
2553   @retval     FALSE            PKCS#7 data signing failed.
2554   @retval     FALSE            This interface is not supported.
2555
2556 **/
2557 BOOLEAN
2558 EFIAPI
2559 Pkcs7Sign (
2560   IN   CONST UINT8  *PrivateKey,
2561   IN   UINTN        PrivateKeySize,
2562   IN   CONST UINT8  *KeyPassword,
2563   IN   UINT8        *InData,
2564   IN   UINTN        InDataSize,
2565   IN   UINT8        *SignCert,
2566   IN   UINT8        *OtherCerts      OPTIONAL,
2567   OUT  UINT8        **SignedData,
2568   OUT  UINTN        *SignedDataSize
2569   );
2570
2571 /**
2572   Verifies the validity of a PKCS#7 signed data as described in "PKCS #7:
2573   Cryptographic Message Syntax Standard". The input signed data could be wrapped
2574   in a ContentInfo structure.
2575
2576   If P7Data, TrustedCert or InData is NULL, then return FALSE.
2577   If P7Length, CertLength or DataLength overflow, then return FALSE.
2578   If this interface is not supported, then return FALSE.
2579
2580   @param[in]  P7Data       Pointer to the PKCS#7 message to verify.
2581   @param[in]  P7Length     Length of the PKCS#7 message in bytes.
2582   @param[in]  TrustedCert  Pointer to a trusted/root certificate encoded in DER, which
2583                            is used for certificate chain verification.
2584   @param[in]  CertLength   Length of the trusted certificate in bytes.
2585   @param[in]  InData       Pointer to the content to be verified.
2586   @param[in]  DataLength   Length of InData in bytes.
2587
2588   @retval  TRUE  The specified PKCS#7 signed data is valid.
2589   @retval  FALSE Invalid PKCS#7 signed data.
2590   @retval  FALSE This interface is not supported.
2591
2592 **/
2593 BOOLEAN
2594 EFIAPI
2595 Pkcs7Verify (
2596   IN  CONST UINT8  *P7Data,
2597   IN  UINTN        P7Length,
2598   IN  CONST UINT8  *TrustedCert,
2599   IN  UINTN        CertLength,
2600   IN  CONST UINT8  *InData,
2601   IN  UINTN        DataLength
2602   );
2603
2604 /**
2605   This function receives a PKCS7 formatted signature, and then verifies that
2606   the specified Enhanced or Extended Key Usages (EKU's) are present in the end-entity
2607   leaf signing certificate.
2608   Note that this function does not validate the certificate chain.
2609
2610   Applications for custom EKU's are quite flexible. For example, a policy EKU
2611   may be present in an Issuing Certificate Authority (CA), and any sub-ordinate
2612   certificate issued might also contain this EKU, thus constraining the
2613   sub-ordinate certificate.  Other applications might allow a certificate
2614   embedded in a device to specify that other Object Identifiers (OIDs) are
2615   present which contains binary data specifying custom capabilities that
2616   the device is able to do.
2617
2618   @param[in]  Pkcs7Signature       The PKCS#7 signed information content block. An array
2619                                    containing the content block with both the signature,
2620                                    the signer's certificate, and any necessary intermediate
2621                                    certificates.
2622   @param[in]  Pkcs7SignatureSize   Number of bytes in Pkcs7Signature.
2623   @param[in]  RequiredEKUs         Array of null-terminated strings listing OIDs of
2624                                    required EKUs that must be present in the signature.
2625   @param[in]  RequiredEKUsSize     Number of elements in the RequiredEKUs string array.
2626   @param[in]  RequireAllPresent    If this is TRUE, then all of the specified EKU's
2627                                    must be present in the leaf signer.  If it is
2628                                    FALSE, then we will succeed if we find any
2629                                    of the specified EKU's.
2630
2631   @retval EFI_SUCCESS              The required EKUs were found in the signature.
2632   @retval EFI_INVALID_PARAMETER    A parameter was invalid.
2633   @retval EFI_NOT_FOUND            One or more EKU's were not found in the signature.
2634
2635 **/
2636 RETURN_STATUS
2637 EFIAPI
2638 VerifyEKUsInPkcs7Signature (
2639   IN  CONST UINT8   *Pkcs7Signature,
2640   IN  CONST UINT32  SignatureSize,
2641   IN  CONST CHAR8   *RequiredEKUs[],
2642   IN  CONST UINT32  RequiredEKUsSize,
2643   IN  BOOLEAN       RequireAllPresent
2644   );
2645
2646 /**
2647   Extracts the attached content from a PKCS#7 signed data if existed. The input signed
2648   data could be wrapped in a ContentInfo structure.
2649
2650   If P7Data, Content, or ContentSize is NULL, then return FALSE. If P7Length overflow,
2651   then return FALSE. If the P7Data is not correctly formatted, then return FALSE.
2652
2653   Caution: This function may receive untrusted input. So this function will do
2654            basic check for PKCS#7 data structure.
2655
2656   @param[in]   P7Data       Pointer to the PKCS#7 signed data to process.
2657   @param[in]   P7Length     Length of the PKCS#7 signed data in bytes.
2658   @param[out]  Content      Pointer to the extracted content from the PKCS#7 signedData.
2659                             It's caller's responsibility to free the buffer with FreePool().
2660   @param[out]  ContentSize  The size of the extracted content in bytes.
2661
2662   @retval     TRUE          The P7Data was correctly formatted for processing.
2663   @retval     FALSE         The P7Data was not correctly formatted for processing.
2664
2665 **/
2666 BOOLEAN
2667 EFIAPI
2668 Pkcs7GetAttachedContent (
2669   IN  CONST UINT8  *P7Data,
2670   IN  UINTN        P7Length,
2671   OUT VOID         **Content,
2672   OUT UINTN        *ContentSize
2673   );
2674
2675 /**
2676   Verifies the validity of a PE/COFF Authenticode Signature as described in "Windows
2677   Authenticode Portable Executable Signature Format".
2678
2679   If AuthData is NULL, then return FALSE.
2680   If ImageHash is NULL, then return FALSE.
2681   If this interface is not supported, then return FALSE.
2682
2683   @param[in]  AuthData     Pointer to the Authenticode Signature retrieved from signed
2684                            PE/COFF image to be verified.
2685   @param[in]  DataSize     Size of the Authenticode Signature in bytes.
2686   @param[in]  TrustedCert  Pointer to a trusted/root certificate encoded in DER, which
2687                            is used for certificate chain verification.
2688   @param[in]  CertSize     Size of the trusted certificate in bytes.
2689   @param[in]  ImageHash    Pointer to the original image file hash value. The procedure
2690                            for calculating the image hash value is described in Authenticode
2691                            specification.
2692   @param[in]  HashSize     Size of Image hash value in bytes.
2693
2694   @retval  TRUE   The specified Authenticode Signature is valid.
2695   @retval  FALSE  Invalid Authenticode Signature.
2696   @retval  FALSE  This interface is not supported.
2697
2698 **/
2699 BOOLEAN
2700 EFIAPI
2701 AuthenticodeVerify (
2702   IN  CONST UINT8  *AuthData,
2703   IN  UINTN        DataSize,
2704   IN  CONST UINT8  *TrustedCert,
2705   IN  UINTN        CertSize,
2706   IN  CONST UINT8  *ImageHash,
2707   IN  UINTN        HashSize
2708   );
2709
2710 /**
2711   Verifies the validity of a RFC3161 Timestamp CounterSignature embedded in PE/COFF Authenticode
2712   signature.
2713
2714   If AuthData is NULL, then return FALSE.
2715   If this interface is not supported, then return FALSE.
2716
2717   @param[in]  AuthData     Pointer to the Authenticode Signature retrieved from signed
2718                            PE/COFF image to be verified.
2719   @param[in]  DataSize     Size of the Authenticode Signature in bytes.
2720   @param[in]  TsaCert      Pointer to a trusted/root TSA certificate encoded in DER, which
2721                            is used for TSA certificate chain verification.
2722   @param[in]  CertSize     Size of the trusted certificate in bytes.
2723   @param[out] SigningTime  Return the time of timestamp generation time if the timestamp
2724                            signature is valid.
2725
2726   @retval  TRUE   The specified Authenticode includes a valid RFC3161 Timestamp CounterSignature.
2727   @retval  FALSE  No valid RFC3161 Timestamp CounterSignature in the specified Authenticode data.
2728
2729 **/
2730 BOOLEAN
2731 EFIAPI
2732 ImageTimestampVerify (
2733   IN  CONST UINT8  *AuthData,
2734   IN  UINTN        DataSize,
2735   IN  CONST UINT8  *TsaCert,
2736   IN  UINTN        CertSize,
2737   OUT EFI_TIME     *SigningTime
2738   );
2739
2740 //=====================================================================================
2741 //    DH Key Exchange Primitive
2742 //=====================================================================================
2743
2744 /**
2745   Allocates and Initializes one Diffie-Hellman Context for subsequent use.
2746
2747   @return  Pointer to the Diffie-Hellman Context that has been initialized.
2748            If the allocations fails, DhNew() returns NULL.
2749            If the interface is not supported, DhNew() returns NULL.
2750
2751 **/
2752 VOID *
2753 EFIAPI
2754 DhNew (
2755   VOID
2756   );
2757
2758 /**
2759   Release the specified DH context.
2760
2761   If the interface is not supported, then ASSERT().
2762
2763   @param[in]  DhContext  Pointer to the DH context to be released.
2764
2765 **/
2766 VOID
2767 EFIAPI
2768 DhFree (
2769   IN  VOID  *DhContext
2770   );
2771
2772 /**
2773   Generates DH parameter.
2774
2775   Given generator g, and length of prime number p in bits, this function generates p,
2776   and sets DH context according to value of g and p.
2777
2778   Before this function can be invoked, pseudorandom number generator must be correctly
2779   initialized by RandomSeed().
2780
2781   If DhContext is NULL, then return FALSE.
2782   If Prime is NULL, then return FALSE.
2783   If this interface is not supported, then return FALSE.
2784
2785   @param[in, out]  DhContext    Pointer to the DH context.
2786   @param[in]       Generator    Value of generator.
2787   @param[in]       PrimeLength  Length in bits of prime to be generated.
2788   @param[out]      Prime        Pointer to the buffer to receive the generated prime number.
2789
2790   @retval TRUE   DH parameter generation succeeded.
2791   @retval FALSE  Value of Generator is not supported.
2792   @retval FALSE  PRNG fails to generate random prime number with PrimeLength.
2793   @retval FALSE  This interface is not supported.
2794
2795 **/
2796 BOOLEAN
2797 EFIAPI
2798 DhGenerateParameter (
2799   IN OUT  VOID   *DhContext,
2800   IN      UINTN  Generator,
2801   IN      UINTN  PrimeLength,
2802   OUT     UINT8  *Prime
2803   );
2804
2805 /**
2806   Sets generator and prime parameters for DH.
2807
2808   Given generator g, and prime number p, this function and sets DH
2809   context accordingly.
2810
2811   If DhContext is NULL, then return FALSE.
2812   If Prime is NULL, then return FALSE.
2813   If this interface is not supported, then return FALSE.
2814
2815   @param[in, out]  DhContext    Pointer to the DH context.
2816   @param[in]       Generator    Value of generator.
2817   @param[in]       PrimeLength  Length in bits of prime to be generated.
2818   @param[in]       Prime        Pointer to the prime number.
2819
2820   @retval TRUE   DH parameter setting succeeded.
2821   @retval FALSE  Value of Generator is not supported.
2822   @retval FALSE  Value of Generator is not suitable for the Prime.
2823   @retval FALSE  Value of Prime is not a prime number.
2824   @retval FALSE  Value of Prime is not a safe prime number.
2825   @retval FALSE  This interface is not supported.
2826
2827 **/
2828 BOOLEAN
2829 EFIAPI
2830 DhSetParameter (
2831   IN OUT  VOID         *DhContext,
2832   IN      UINTN        Generator,
2833   IN      UINTN        PrimeLength,
2834   IN      CONST UINT8  *Prime
2835   );
2836
2837 /**
2838   Generates DH public key.
2839
2840   This function generates random secret exponent, and computes the public key, which is
2841   returned via parameter PublicKey and PublicKeySize. DH context is updated accordingly.
2842   If the PublicKey buffer is too small to hold the public key, FALSE is returned and
2843   PublicKeySize is set to the required buffer size to obtain the public key.
2844
2845   If DhContext is NULL, then return FALSE.
2846   If PublicKeySize is NULL, then return FALSE.
2847   If PublicKeySize is large enough but PublicKey is NULL, then return FALSE.
2848   If this interface is not supported, then return FALSE.
2849
2850   @param[in, out]  DhContext      Pointer to the DH context.
2851   @param[out]      PublicKey      Pointer to the buffer to receive generated public key.
2852   @param[in, out]  PublicKeySize  On input, the size of PublicKey buffer in bytes.
2853                                  On output, the size of data returned in PublicKey buffer in bytes.
2854
2855   @retval TRUE   DH public key generation succeeded.
2856   @retval FALSE  DH public key generation failed.
2857   @retval FALSE  PublicKeySize is not large enough.
2858   @retval FALSE  This interface is not supported.
2859
2860 **/
2861 BOOLEAN
2862 EFIAPI
2863 DhGenerateKey (
2864   IN OUT  VOID   *DhContext,
2865   OUT     UINT8  *PublicKey,
2866   IN OUT  UINTN  *PublicKeySize
2867   );
2868
2869 /**
2870   Computes exchanged common key.
2871
2872   Given peer's public key, this function computes the exchanged common key, based on its own
2873   context including value of prime modulus and random secret exponent.
2874
2875   If DhContext is NULL, then return FALSE.
2876   If PeerPublicKey is NULL, then return FALSE.
2877   If KeySize is NULL, then return FALSE.
2878   If Key is NULL, then return FALSE.
2879   If KeySize is not large enough, then return FALSE.
2880   If this interface is not supported, then return FALSE.
2881
2882   @param[in, out]  DhContext          Pointer to the DH context.
2883   @param[in]       PeerPublicKey      Pointer to the peer's public key.
2884   @param[in]       PeerPublicKeySize  Size of peer's public key in bytes.
2885   @param[out]      Key                Pointer to the buffer to receive generated key.
2886   @param[in, out]  KeySize            On input, the size of Key buffer in bytes.
2887                                      On output, the size of data returned in Key buffer in bytes.
2888
2889   @retval TRUE   DH exchanged key generation succeeded.
2890   @retval FALSE  DH exchanged key generation failed.
2891   @retval FALSE  KeySize is not large enough.
2892   @retval FALSE  This interface is not supported.
2893
2894 **/
2895 BOOLEAN
2896 EFIAPI
2897 DhComputeKey (
2898   IN OUT  VOID         *DhContext,
2899   IN      CONST UINT8  *PeerPublicKey,
2900   IN      UINTN        PeerPublicKeySize,
2901   OUT     UINT8        *Key,
2902   IN OUT  UINTN        *KeySize
2903   );
2904
2905 //=====================================================================================
2906 //    Pseudo-Random Generation Primitive
2907 //=====================================================================================
2908
2909 /**
2910   Sets up the seed value for the pseudorandom number generator.
2911
2912   This function sets up the seed value for the pseudorandom number generator.
2913   If Seed is not NULL, then the seed passed in is used.
2914   If Seed is NULL, then default seed is used.
2915   If this interface is not supported, then return FALSE.
2916
2917   @param[in]  Seed      Pointer to seed value.
2918                         If NULL, default seed is used.
2919   @param[in]  SeedSize  Size of seed value.
2920                         If Seed is NULL, this parameter is ignored.
2921
2922   @retval TRUE   Pseudorandom number generator has enough entropy for random generation.
2923   @retval FALSE  Pseudorandom number generator does not have enough entropy for random generation.
2924   @retval FALSE  This interface is not supported.
2925
2926 **/
2927 BOOLEAN
2928 EFIAPI
2929 RandomSeed (
2930   IN  CONST  UINT8  *Seed  OPTIONAL,
2931   IN  UINTN         SeedSize
2932   );
2933
2934 /**
2935   Generates a pseudorandom byte stream of the specified size.
2936
2937   If Output is NULL, then return FALSE.
2938   If this interface is not supported, then return FALSE.
2939
2940   @param[out]  Output  Pointer to buffer to receive random value.
2941   @param[in]   Size    Size of random bytes to generate.
2942
2943   @retval TRUE   Pseudorandom byte stream generated successfully.
2944   @retval FALSE  Pseudorandom number generator fails to generate due to lack of entropy.
2945   @retval FALSE  This interface is not supported.
2946
2947 **/
2948 BOOLEAN
2949 EFIAPI
2950 RandomBytes (
2951   OUT  UINT8  *Output,
2952   IN   UINTN  Size
2953   );
2954
2955 //=====================================================================================
2956 //    Key Derivation Function Primitive
2957 //=====================================================================================
2958
2959 /**
2960   Derive key data using HMAC-SHA256 based KDF.
2961
2962   @param[in]   Key              Pointer to the user-supplied key.
2963   @param[in]   KeySize          Key size in bytes.
2964   @param[in]   Salt             Pointer to the salt(non-secret) value.
2965   @param[in]   SaltSize         Salt size in bytes.
2966   @param[in]   Info             Pointer to the application specific info.
2967   @param[in]   InfoSize         Info size in bytes.
2968   @param[out]  Out              Pointer to buffer to receive hkdf value.
2969   @param[in]   OutSize          Size of hkdf bytes to generate.
2970
2971   @retval TRUE   Hkdf generated successfully.
2972   @retval FALSE  Hkdf generation failed.
2973
2974 **/
2975 BOOLEAN
2976 EFIAPI
2977 HkdfSha256ExtractAndExpand (
2978   IN   CONST UINT8  *Key,
2979   IN   UINTN        KeySize,
2980   IN   CONST UINT8  *Salt,
2981   IN   UINTN        SaltSize,
2982   IN   CONST UINT8  *Info,
2983   IN   UINTN        InfoSize,
2984   OUT  UINT8        *Out,
2985   IN   UINTN        OutSize
2986   );
2987
2988 #endif // __BASE_CRYPT_LIB_H__