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 - 2012, Intel Corporation. All rights reserved.<BR>
   8 This program and the accompanying materials
   9 are licensed and made available under the terms and conditions of the BSD License
  10 which accompanies this distribution.  The full text of the license may be found at
  11 http://opensource.org/licenses/bsd-license.php
  12
  13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  15
  16 **/
  17
  18 #ifndef __BASE_CRYPT_LIB_H__
  19 #define __BASE_CRYPT_LIB_H__
  20
  21 ///
  22 /// MD4 digest size in bytes
  23 ///
  24 #define MD4_DIGEST_SIZE     16
  25
  26 ///
  27 /// MD5 digest size in bytes
  28 ///
  29 #define MD5_DIGEST_SIZE     16
  30
  31 ///
  32 /// SHA-1 digest size in bytes.
  33 ///
  34 #define SHA1_DIGEST_SIZE    20
  35
  36 ///
  37 /// SHA-256 digest size in bytes
  38 ///
  39 #define SHA256_DIGEST_SIZE  32
  40
  41 ///
  42 /// TDES block size in bytes
  43 ///
  44 #define TDES_BLOCK_SIZE     8
  45
  46 ///
  47 /// AES block size in bytes
  48 ///
  49 #define AES_BLOCK_SIZE      16
  50
  51 ///
  52 /// RSA Key Tags Definition used in RsaSetKey() function for key component identification.
  53 ///
  54 typedef enum {
  55   RsaKeyN,      ///< RSA public Modulus (N)
  56   RsaKeyE,      ///< RSA Public exponent (e)
  57   RsaKeyD,      ///< RSA Private exponent (d)
  58   RsaKeyP,      ///< RSA secret prime factor of Modulus (p)
  59   RsaKeyQ,      ///< RSA secret prime factor of Modules (q)
  60   RsaKeyDp,     ///< p's CRT exponent (== d mod (p - 1))
  61   RsaKeyDq,     ///< q's CRT exponent (== d mod (q - 1))
  62   RsaKeyQInv    ///< The CRT coefficient (== 1/q mod p)
  63 } RSA_KEY_TAG;
  64
  65 //=====================================================================================
  66 //    One-Way Cryptographic Hash Primitives
  67 //=====================================================================================
  68
  69 /**
  70   Retrieves the size, in bytes, of the context buffer required for MD4 hash operations.
  71
  72   If this interface is not supported, then return zero.
  73
  74   @return  The size, in bytes, of the context buffer required for MD4 hash operations.
  75   @retval  0   This interface is not supported.
  76
  77 **/
  78 UINTN
  79 EFIAPI
  80 Md4GetContextSize (
  81   VOID
  82   );
  83
  84 /**
  85   Initializes user-supplied memory pointed by Md4Context as MD4 hash context for
  86   subsequent use.
  87
  88   If Md4Context is NULL, then return FALSE.
  89   If this interface is not supported, then return FALSE.
  90
  91   @param[out]  Md4Context  Pointer to MD4 context being initialized.
  92
  93   @retval TRUE   MD4 context initialization succeeded.
  94   @retval FALSE  MD4 context initialization failed.
  95   @retval FALSE  This interface is not supported.
  96
  97 **/
  98 BOOLEAN
  99 EFIAPI
 100 Md4Init (
 101   OUT  VOID  *Md4Context
 102   );
 103
 104 /**
 105   Makes a copy of an existing MD4 context.
 106
 107   If Md4Context is NULL, then return FALSE.
 108   If NewMd4Context is NULL, then return FALSE.
 109   If this interface is not supported, then return FALSE.
 110
 111   @param[in]  Md4Context     Pointer to MD4 context being copied.
 112   @param[out] NewMd4Context  Pointer to new MD4 context.
 113
 114   @retval TRUE   MD4 context copy succeeded.
 115   @retval FALSE  MD4 context copy failed.
 116   @retval FALSE  This interface is not supported.
 117
 118 **/
 119 BOOLEAN
 120 EFIAPI
 121 Md4Duplicate (
 122   IN   CONST VOID  *Md4Context,
 123   OUT  VOID        *NewMd4Context
 124   );
 125
 126 /**
 127   Digests the input data and updates MD4 context.
 128
 129   This function performs MD4 digest on a data buffer of the specified size.
 130   It can be called multiple times to compute the digest of long or discontinuous data streams.
 131   MD4 context should be already correctly intialized by Md4Init(), and should not be finalized
 132   by Md4Final(). Behavior with invalid context is undefined.
 133
 134   If Md4Context is NULL, then return FALSE.
 135   If this interface is not supported, then return FALSE.
 136
 137   @param[in, out]  Md4Context  Pointer to the MD4 context.
 138   @param[in]       Data        Pointer to the buffer containing the data to be hashed.
 139   @param[in]       DataSize    Size of Data buffer in bytes.
 140
 141   @retval TRUE   MD4 data digest succeeded.
 142   @retval FALSE  MD4 data digest failed.
 143   @retval FALSE  This interface is not supported.
 144
 145 **/
 146 BOOLEAN
 147 EFIAPI
 148 Md4Update (
 149   IN OUT  VOID        *Md4Context,
 150   IN      CONST VOID  *Data,
 151   IN      UINTN       DataSize
 152   );
 153
 154 /**
 155   Completes computation of the MD4 digest value.
 156
 157   This function completes MD4 hash computation and retrieves the digest value into
 158   the specified memory. After this function has been called, the MD4 context cannot
 159   be used again.
 160   MD4 context should be already correctly intialized by Md4Init(), and should not be
 161   finalized by Md4Final(). Behavior with invalid MD4 context is undefined.
 162
 163   If Md4Context is NULL, then return FALSE.
 164   If HashValue is NULL, then return FALSE.
 165   If this interface is not supported, then return FALSE.
 166
 167   @param[in, out]  Md4Context  Pointer to the MD4 context.
 168   @param[out]      HashValue   Pointer to a buffer that receives the MD4 digest
 169                                value (16 bytes).
 170
 171   @retval TRUE   MD4 digest computation succeeded.
 172   @retval FALSE  MD4 digest computation failed.
 173   @retval FALSE  This interface is not supported.
 174
 175 **/
 176 BOOLEAN
 177 EFIAPI
 178 Md4Final (
 179   IN OUT  VOID   *Md4Context,
 180   OUT     UINT8  *HashValue
 181   );
 182
 183 /**
 184   Retrieves the size, in bytes, of the context buffer required for MD5 hash operations.
 185
 186   If this interface is not supported, then return zero.
 187
 188   @return  The size, in bytes, of the context buffer required for MD5 hash operations.
 189   @retval  0   This interface is not supported.
 190
 191 **/
 192 UINTN
 193 EFIAPI
 194 Md5GetContextSize (
 195   VOID
 196   );
 197
 198 /**
 199   Initializes user-supplied memory pointed by Md5Context as MD5 hash context for
 200   subsequent use.
 201
 202   If Md5Context is NULL, then return FALSE.
 203   If this interface is not supported, then return FALSE.
 204
 205   @param[out]  Md5Context  Pointer to MD5 context being initialized.
 206
 207   @retval TRUE   MD5 context initialization succeeded.
 208   @retval FALSE  MD5 context initialization failed.
 209   @retval FALSE  This interface is not supported.
 210
 211 **/
 212 BOOLEAN
 213 EFIAPI
 214 Md5Init (
 215   OUT  VOID  *Md5Context
 216   );
 217
 218 /**
 219   Makes a copy of an existing MD5 context.
 220
 221   If Md5Context is NULL, then return FALSE.
 222   If NewMd5Context is NULL, then return FALSE.
 223   If this interface is not supported, then return FALSE.
 224
 225   @param[in]  Md5Context     Pointer to MD5 context being copied.
 226   @param[out] NewMd5Context  Pointer to new MD5 context.
 227
 228   @retval TRUE   MD5 context copy succeeded.
 229   @retval FALSE  MD5 context copy failed.
 230   @retval FALSE  This interface is not supported.
 231
 232 **/
 233 BOOLEAN
 234 EFIAPI
 235 Md5Duplicate (
 236   IN   CONST VOID  *Md5Context,
 237   OUT  VOID        *NewMd5Context
 238   );
 239
 240 /**
 241   Digests the input data and updates MD5 context.
 242
 243   This function performs MD5 digest on a data buffer of the specified size.
 244   It can be called multiple times to compute the digest of long or discontinuous data streams.
 245   MD5 context should be already correctly intialized by Md5Init(), and should not be finalized
 246   by Md5Final(). Behavior with invalid context is undefined.
 247
 248   If Md5Context is NULL, then return FALSE.
 249   If this interface is not supported, then return FALSE.
 250
 251   @param[in, out]  Md5Context  Pointer to the MD5 context.
 252   @param[in]       Data        Pointer to the buffer containing the data to be hashed.
 253   @param[in]       DataSize    Size of Data buffer in bytes.
 254
 255   @retval TRUE   MD5 data digest succeeded.
 256   @retval FALSE  MD5 data digest failed.
 257   @retval FALSE  This interface is not supported.
 258
 259 **/
 260 BOOLEAN
 261 EFIAPI
 262 Md5Update (
 263   IN OUT  VOID        *Md5Context,
 264   IN      CONST VOID  *Data,
 265   IN      UINTN       DataSize
 266   );
 267
 268 /**
 269   Completes computation of the MD5 digest value.
 270
 271   This function completes MD5 hash computation and retrieves the digest value into
 272   the specified memory. After this function has been called, the MD5 context cannot
 273   be used again.
 274   MD5 context should be already correctly intialized by Md5Init(), and should not be
 275   finalized by Md5Final(). Behavior with invalid MD5 context is undefined.
 276
 277   If Md5Context is NULL, then return FALSE.
 278   If HashValue is NULL, then return FALSE.
 279   If this interface is not supported, then return FALSE.
 280
 281   @param[in, out]  Md5Context  Pointer to the MD5 context.
 282   @param[out]      HashValue   Pointer to a buffer that receives the MD5 digest
 283                                value (16 bytes).
 284
 285   @retval TRUE   MD5 digest computation succeeded.
 286   @retval FALSE  MD5 digest computation failed.
 287   @retval FALSE  This interface is not supported.
 288
 289 **/
 290 BOOLEAN
 291 EFIAPI
 292 Md5Final (
 293   IN OUT  VOID   *Md5Context,
 294   OUT     UINT8  *HashValue
 295   );
 296
 297 /**
 298   Retrieves the size, in bytes, of the context buffer required for SHA-1 hash operations.
 299
 300   If this interface is not supported, then return zero.
 301
 302   @return  The size, in bytes, of the context buffer required for SHA-1 hash operations.
 303   @retval  0   This interface is not supported.
 304
 305 **/
 306 UINTN
 307 EFIAPI
 308 Sha1GetContextSize (
 309   VOID
 310   );
 311
 312 /**
 313   Initializes user-supplied memory pointed by Sha1Context as SHA-1 hash context for
 314   subsequent use.
 315
 316   If Sha1Context is NULL, then return FALSE.
 317   If this interface is not supported, then return FALSE.
 318
 319   @param[out]  Sha1Context  Pointer to SHA-1 context being initialized.
 320
 321   @retval TRUE   SHA-1 context initialization succeeded.
 322   @retval FALSE  SHA-1 context initialization failed.
 323   @retval FALSE  This interface is not supported.
 324
 325 **/
 326 BOOLEAN
 327 EFIAPI
 328 Sha1Init (
 329   OUT  VOID  *Sha1Context
 330   );
 331
 332 /**
 333   Makes a copy of an existing SHA-1 context.
 334
 335   If Sha1Context is NULL, then return FALSE.
 336   If NewSha1Context is NULL, then return FALSE.
 337   If this interface is not supported, then return FALSE.
 338
 339   @param[in]  Sha1Context     Pointer to SHA-1 context being copied.
 340   @param[out] NewSha1Context  Pointer to new SHA-1 context.
 341
 342   @retval TRUE   SHA-1 context copy succeeded.
 343   @retval FALSE  SHA-1 context copy failed.
 344   @retval FALSE  This interface is not supported.
 345
 346 **/
 347 BOOLEAN
 348 EFIAPI
 349 Sha1Duplicate (
 350   IN   CONST VOID  *Sha1Context,
 351   OUT  VOID        *NewSha1Context
 352   );
 353
 354 /**
 355   Digests the input data and updates SHA-1 context.
 356
 357   This function performs SHA-1 digest on a data buffer of the specified size.
 358   It can be called multiple times to compute the digest of long or discontinuous data streams.
 359   SHA-1 context should be already correctly intialized by Sha1Init(), and should not be finalized
 360   by Sha1Final(). Behavior with invalid context is undefined.
 361
 362   If Sha1Context is NULL, then return FALSE.
 363   If this interface is not supported, then return FALSE.
 364
 365   @param[in, out]  Sha1Context  Pointer to the SHA-1 context.
 366   @param[in]       Data         Pointer to the buffer containing the data to be hashed.
 367   @param[in]       DataSize     Size of Data buffer in bytes.
 368
 369   @retval TRUE   SHA-1 data digest succeeded.
 370   @retval FALSE  SHA-1 data digest failed.
 371   @retval FALSE  This interface is not supported.
 372
 373 **/
 374 BOOLEAN
 375 EFIAPI
 376 Sha1Update (
 377   IN OUT  VOID        *Sha1Context,
 378   IN      CONST VOID  *Data,
 379   IN      UINTN       DataSize
 380   );
 381
 382 /**
 383   Completes computation of the SHA-1 digest value.
 384
 385   This function completes SHA-1 hash computation and retrieves the digest value into
 386   the specified memory. After this function has been called, the SHA-1 context cannot
 387   be used again.
 388   SHA-1 context should be already correctly intialized by Sha1Init(), and should not be
 389   finalized by Sha1Final(). Behavior with invalid SHA-1 context is undefined.
 390
 391   If Sha1Context is NULL, then return FALSE.
 392   If HashValue is NULL, then return FALSE.
 393   If this interface is not supported, then return FALSE.
 394
 395   @param[in, out]  Sha1Context  Pointer to the SHA-1 context.
 396   @param[out]      HashValue    Pointer to a buffer that receives the SHA-1 digest
 397                                 value (20 bytes).
 398
 399   @retval TRUE   SHA-1 digest computation succeeded.
 400   @retval FALSE  SHA-1 digest computation failed.
 401   @retval FALSE  This interface is not supported.
 402
 403 **/
 404 BOOLEAN
 405 EFIAPI
 406 Sha1Final (
 407   IN OUT  VOID   *Sha1Context,
 408   OUT     UINT8  *HashValue
 409   );
 410
 411 /**
 412   Retrieves the size, in bytes, of the context buffer required for SHA-256 hash operations.
 413
 414   @return  The size, in bytes, of the context buffer required for SHA-256 hash operations.
 415
 416 **/
 417 UINTN
 418 EFIAPI
 419 Sha256GetContextSize (
 420   VOID
 421   );
 422
 423 /**
 424   Initializes user-supplied memory pointed by Sha256Context as SHA-256 hash context for
 425   subsequent use.
 426
 427   If Sha256Context is NULL, then return FALSE.
 428
 429   @param[out]  Sha256Context  Pointer to SHA-256 context being initialized.
 430
 431   @retval TRUE   SHA-256 context initialization succeeded.
 432   @retval FALSE  SHA-256 context initialization failed.
 433
 434 **/
 435 BOOLEAN
 436 EFIAPI
 437 Sha256Init (
 438   OUT  VOID  *Sha256Context
 439   );
 440
 441 /**
 442   Makes a copy of an existing SHA-256 context.
 443
 444   If Sha256Context is NULL, then return FALSE.
 445   If NewSha256Context is NULL, then return FALSE.
 446   If this interface is not supported, then return FALSE.
 447
 448   @param[in]  Sha256Context     Pointer to SHA-256 context being copied.
 449   @param[out] NewSha256Context  Pointer to new SHA-256 context.
 450
 451   @retval TRUE   SHA-256 context copy succeeded.
 452   @retval FALSE  SHA-256 context copy failed.
 453   @retval FALSE  This interface is not supported.
 454
 455 **/
 456 BOOLEAN
 457 EFIAPI
 458 Sha256Duplicate (
 459   IN   CONST VOID  *Sha256Context,
 460   OUT  VOID        *NewSha256Context
 461   );
 462
 463 /**
 464   Digests the input data and updates SHA-256 context.
 465
 466   This function performs SHA-256 digest on a data buffer of the specified size.
 467   It can be called multiple times to compute the digest of long or discontinuous data streams.
 468   SHA-256 context should be already correctly intialized by Sha256Init(), and should not be finalized
 469   by Sha256Final(). Behavior with invalid context is undefined.
 470
 471   If Sha256Context is NULL, then return FALSE.
 472
 473   @param[in, out]  Sha256Context  Pointer to the SHA-256 context.
 474   @param[in]       Data           Pointer to the buffer containing the data to be hashed.
 475   @param[in]       DataSize       Size of Data buffer in bytes.
 476
 477   @retval TRUE   SHA-256 data digest succeeded.
 478   @retval FALSE  SHA-256 data digest failed.
 479
 480 **/
 481 BOOLEAN
 482 EFIAPI
 483 Sha256Update (
 484   IN OUT  VOID        *Sha256Context,
 485   IN      CONST VOID  *Data,
 486   IN      UINTN       DataSize
 487   );
 488
 489 /**
 490   Completes computation of the SHA-256 digest value.
 491
 492   This function completes SHA-256 hash computation and retrieves the digest value into
 493   the specified memory. After this function has been called, the SHA-256 context cannot
 494   be used again.
 495   SHA-256 context should be already correctly intialized by Sha256Init(), and should not be
 496   finalized by Sha256Final(). Behavior with invalid SHA-256 context is undefined.
 497
 498   If Sha256Context is NULL, then return FALSE.
 499   If HashValue is NULL, then return FALSE.
 500
 501   @param[in, out]  Sha256Context  Pointer to the SHA-256 context.
 502   @param[out]      HashValue      Pointer to a buffer that receives the SHA-256 digest
 503                                   value (32 bytes).
 504
 505   @retval TRUE   SHA-256 digest computation succeeded.
 506   @retval FALSE  SHA-256 digest computation failed.
 507
 508 **/
 509 BOOLEAN
 510 EFIAPI
 511 Sha256Final (
 512   IN OUT  VOID   *Sha256Context,
 513   OUT     UINT8  *HashValue
 514   );
 515
 516
 517 //=====================================================================================
 518 //    MAC (Message Authentication Code) Primitive
 519 //=====================================================================================
 520
 521 /**
 522   Retrieves the size, in bytes, of the context buffer required for HMAC-MD5 operations.
 523
 524   If this interface is not supported, then return zero.
 525
 526   @return  The size, in bytes, of the context buffer required for HMAC-MD5 operations.
 527   @retval  0   This interface is not supported.
 528
 529 **/
 530 UINTN
 531 EFIAPI
 532 HmacMd5GetContextSize (
 533   VOID
 534   );
 535
 536 /**
 537   Initializes user-supplied memory pointed by HmacMd5Context as HMAC-MD5 context for
 538   subsequent use.
 539
 540   If HmacMd5Context is NULL, then return FALSE.
 541   If this interface is not supported, then return FALSE.
 542
 543   @param[out]  HmacMd5Context  Pointer to HMAC-MD5 context being initialized.
 544   @param[in]   Key             Pointer to the user-supplied key.
 545   @param[in]   KeySize         Key size in bytes.
 546
 547   @retval TRUE   HMAC-MD5 context initialization succeeded.
 548   @retval FALSE  HMAC-MD5 context initialization failed.
 549   @retval FALSE  This interface is not supported.
 550
 551 **/
 552 BOOLEAN
 553 EFIAPI
 554 HmacMd5Init (
 555   OUT  VOID         *HmacMd5Context,
 556   IN   CONST UINT8  *Key,
 557   IN   UINTN        KeySize
 558   );
 559
 560 /**
 561   Makes a copy of an existing HMAC-MD5 context.
 562
 563   If HmacMd5Context is NULL, then return FALSE.
 564   If NewHmacMd5Context is NULL, then return FALSE.
 565   If this interface is not supported, then return FALSE.
 566
 567   @param[in]  HmacMd5Context     Pointer to HMAC-MD5 context being copied.
 568   @param[out] NewHmacMd5Context  Pointer to new HMAC-MD5 context.
 569
 570   @retval TRUE   HMAC-MD5 context copy succeeded.
 571   @retval FALSE  HMAC-MD5 context copy failed.
 572   @retval FALSE  This interface is not supported.
 573
 574 **/
 575 BOOLEAN
 576 EFIAPI
 577 HmacMd5Duplicate (
 578   IN   CONST VOID  *HmacMd5Context,
 579   OUT  VOID        *NewHmacMd5Context
 580   );
 581
 582 /**
 583   Digests the input data and updates HMAC-MD5 context.
 584
 585   This function performs HMAC-MD5 digest on a data buffer of the specified size.
 586   It can be called multiple times to compute the digest of long or discontinuous data streams.
 587   HMAC-MD5 context should be already correctly intialized by HmacMd5Init(), and should not be
 588   finalized by HmacMd5Final(). Behavior with invalid context is undefined.
 589
 590   If HmacMd5Context is NULL, then return FALSE.
 591   If this interface is not supported, then return FALSE.
 592
 593   @param[in, out]  HmacMd5Context  Pointer to the HMAC-MD5 context.
 594   @param[in]       Data            Pointer to the buffer containing the data to be digested.
 595   @param[in]       DataSize        Size of Data buffer in bytes.
 596
 597   @retval TRUE   HMAC-MD5 data digest succeeded.
 598   @retval FALSE  HMAC-MD5 data digest failed.
 599   @retval FALSE  This interface is not supported.
 600
 601 **/
 602 BOOLEAN
 603 EFIAPI
 604 HmacMd5Update (
 605   IN OUT  VOID        *HmacMd5Context,
 606   IN      CONST VOID  *Data,
 607   IN      UINTN       DataSize
 608   );
 609
 610 /**
 611   Completes computation of the HMAC-MD5 digest value.
 612
 613   This function completes HMAC-MD5 hash computation and retrieves the digest value into
 614   the specified memory. After this function has been called, the HMAC-MD5 context cannot
 615   be used again.
 616   HMAC-MD5 context should be already correctly intialized by HmacMd5Init(), and should not be
 617   finalized by HmacMd5Final(). Behavior with invalid HMAC-MD5 context is undefined.
 618
 619   If HmacMd5Context is NULL, then return FALSE.
 620   If HashValue is NULL, then return FALSE.
 621   If this interface is not supported, then return FALSE.
 622
 623   @param[in, out]  HmacMd5Context  Pointer to the HMAC-MD5 context.
 624   @param[out]      HashValue       Pointer to a buffer that receives the HMAC-MD5 digest
 625                                    value (16 bytes).
 626
 627   @retval TRUE   HMAC-MD5 digest computation succeeded.
 628   @retval FALSE  HMAC-MD5 digest computation failed.
 629   @retval FALSE  This interface is not supported.
 630
 631 **/
 632 BOOLEAN
 633 EFIAPI
 634 HmacMd5Final (
 635   IN OUT  VOID   *HmacMd5Context,
 636   OUT     UINT8  *HmacValue
 637   );
 638
 639 /**
 640   Retrieves the size, in bytes, of the context buffer required for HMAC-SHA1 operations.
 641
 642   If this interface is not supported, then return zero.
 643
 644   @return  The size, in bytes, of the context buffer required for HMAC-SHA1 operations.
 645   @retval  0   This interface is not supported.
 646
 647 **/
 648 UINTN
 649 EFIAPI
 650 HmacSha1GetContextSize (
 651   VOID
 652   );
 653
 654 /**
 655   Initializes user-supplied memory pointed by HmacSha1Context as HMAC-SHA1 context for
 656   subsequent use.
 657
 658   If HmacSha1Context is NULL, then return FALSE.
 659   If this interface is not supported, then return FALSE.
 660
 661   @param[out]  HmacSha1Context  Pointer to HMAC-SHA1 context being initialized.
 662   @param[in]   Key              Pointer to the user-supplied key.
 663   @param[in]   KeySize          Key size in bytes.
 664
 665   @retval TRUE   HMAC-SHA1 context initialization succeeded.
 666   @retval FALSE  HMAC-SHA1 context initialization failed.
 667   @retval FALSE  This interface is not supported.
 668
 669 **/
 670 BOOLEAN
 671 EFIAPI
 672 HmacSha1Init (
 673   OUT  VOID         *HmacSha1Context,
 674   IN   CONST UINT8  *Key,
 675   IN   UINTN        KeySize
 676   );
 677
 678 /**
 679   Makes a copy of an existing HMAC-SHA1 context.
 680
 681   If HmacSha1Context is NULL, then return FALSE.
 682   If NewHmacSha1Context is NULL, then return FALSE.
 683   If this interface is not supported, then return FALSE.
 684
 685   @param[in]  HmacSha1Context     Pointer to HMAC-SHA1 context being copied.
 686   @param[out] NewHmacSha1Context  Pointer to new HMAC-SHA1 context.
 687
 688   @retval TRUE   HMAC-SHA1 context copy succeeded.
 689   @retval FALSE  HMAC-SHA1 context copy failed.
 690   @retval FALSE  This interface is not supported.
 691
 692 **/
 693 BOOLEAN
 694 EFIAPI
 695 HmacSha1Duplicate (
 696   IN   CONST VOID  *HmacSha1Context,
 697   OUT  VOID        *NewHmacSha1Context
 698   );
 699
 700 /**
 701   Digests the input data and updates HMAC-SHA1 context.
 702
 703   This function performs HMAC-SHA1 digest on a data buffer of the specified size.
 704   It can be called multiple times to compute the digest of long or discontinuous data streams.
 705   HMAC-SHA1 context should be already correctly intialized by HmacSha1Init(), and should not
 706   be finalized by HmacSha1Final(). Behavior with invalid context is undefined.
 707
 708   If HmacSha1Context is NULL, then return FALSE.
 709   If this interface is not supported, then return FALSE.
 710
 711   @param[in, out]  HmacSha1Context Pointer to the HMAC-SHA1 context.
 712   @param[in]       Data            Pointer to the buffer containing the data to be digested.
 713   @param[in]       DataSize        Size of Data buffer in bytes.
 714
 715   @retval TRUE   HMAC-SHA1 data digest succeeded.
 716   @retval FALSE  HMAC-SHA1 data digest failed.
 717   @retval FALSE  This interface is not supported.
 718
 719 **/
 720 BOOLEAN
 721 EFIAPI
 722 HmacSha1Update (
 723   IN OUT  VOID        *HmacSha1Context,
 724   IN      CONST VOID  *Data,
 725   IN      UINTN       DataSize
 726   );
 727
 728 /**
 729   Completes computation of the HMAC-SHA1 digest value.
 730
 731   This function completes HMAC-SHA1 hash computation and retrieves the digest value into
 732   the specified memory. After this function has been called, the HMAC-SHA1 context cannot
 733   be used again.
 734   HMAC-SHA1 context should be already correctly intialized by HmacSha1Init(), and should
 735   not be finalized by HmacSha1Final(). Behavior with invalid HMAC-SHA1 context is undefined.
 736
 737   If HmacSha1Context is NULL, then return FALSE.
 738   If HashValue is NULL, then return FALSE.
 739   If this interface is not supported, then return FALSE.
 740
 741   @param[in, out]  HmacSha1Context  Pointer to the HMAC-SHA1 context.
 742   @param[out]      HashValue        Pointer to a buffer that receives the HMAC-SHA1 digest
 743                                     value (20 bytes).
 744
 745   @retval TRUE   HMAC-SHA1 digest computation succeeded.
 746   @retval FALSE  HMAC-SHA1 digest computation failed.
 747   @retval FALSE  This interface is not supported.
 748
 749 **/
 750 BOOLEAN
 751 EFIAPI
 752 HmacSha1Final (
 753   IN OUT  VOID   *HmacSha1Context,
 754   OUT     UINT8  *HmacValue
 755   );
 756
 757
 758 //=====================================================================================
 759 //    Symmetric Cryptography Primitive
 760 //=====================================================================================
 761
 762 /**
 763   Retrieves the size, in bytes, of the context buffer required for TDES operations.
 764
 765   If this interface is not supported, then return zero.
 766
 767   @return  The size, in bytes, of the context buffer required for TDES operations.
 768   @retval  0   This interface is not supported.
 769
 770 **/
 771 UINTN
 772 EFIAPI
 773 TdesGetContextSize (
 774   VOID
 775   );
 776
 777 /**
 778   Initializes user-supplied memory as TDES context for subsequent use.
 779
 780   This function initializes user-supplied memory pointed by TdesContext as TDES context.
 781   In addtion, it sets up all TDES key materials for subsequent encryption and decryption
 782   operations.
 783   There are 3 key options as follows:
 784   KeyLength = 64,  Keying option 1: K1 == K2 == K3 (Backward compatibility with DES)
 785   KeyLength = 128, Keying option 2: K1 != K2 and K3 = K1 (Less Security)
 786   KeyLength = 192  Keying option 3: K1 != K2 != K3 (Strongest)
 787
 788   If TdesContext is NULL, then return FALSE.
 789   If Key is NULL, then return FALSE.
 790   If KeyLength is not valid, then return FALSE.
 791   If this interface is not supported, then return FALSE.
 792
 793   @param[out]  TdesContext  Pointer to TDES context being initialized.
 794   @param[in]   Key          Pointer to the user-supplied TDES key.
 795   @param[in]   KeyLength    Length of TDES key in bits.
 796
 797   @retval TRUE   TDES context initialization succeeded.
 798   @retval FALSE  TDES context initialization failed.
 799   @retval FALSE  This interface is not supported.
 800
 801 **/
 802 BOOLEAN
 803 EFIAPI
 804 TdesInit (
 805   OUT  VOID         *TdesContext,
 806   IN   CONST UINT8  *Key,
 807   IN   UINTN        KeyLength
 808   );
 809
 810 /**
 811   Performs TDES encryption on a data buffer of the specified size in ECB mode.
 812
 813   This function performs TDES encryption on data buffer pointed by Input, of specified
 814   size of InputSize, in ECB mode.
 815   InputSize must be multiple of block size (8 bytes). This function does not perform
 816   padding. Caller must perform padding, if necessary, to ensure valid input data size.
 817   TdesContext should be already correctly initialized by TdesInit(). Behavior with
 818   invalid TDES context is undefined.
 819
 820   If TdesContext is NULL, then return FALSE.
 821   If Input is NULL, then return FALSE.
 822   If InputSize is not multiple of block size (8 bytes), then return FALSE.
 823   If Output is NULL, then return FALSE.
 824   If this interface is not supported, then return FALSE.
 825
 826   @param[in]   TdesContext  Pointer to the TDES context.
 827   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.
 828   @param[in]   InputSize    Size of the Input buffer in bytes.
 829   @param[out]  Output       Pointer to a buffer that receives the TDES encryption output.
 830
 831   @retval TRUE   TDES encryption succeeded.
 832   @retval FALSE  TDES encryption failed.
 833   @retval FALSE  This interface is not supported.
 834
 835 **/
 836 BOOLEAN
 837 EFIAPI
 838 TdesEcbEncrypt (
 839   IN   VOID         *TdesContext,
 840   IN   CONST UINT8  *Input,
 841   IN   UINTN        InputSize,
 842   OUT  UINT8        *Output
 843   );
 844
 845 /**
 846   Performs TDES decryption on a data buffer of the specified size in ECB mode.
 847
 848   This function performs TDES decryption on data buffer pointed by Input, of specified
 849   size of InputSize, in ECB mode.
 850   InputSize must be multiple of block size (8 bytes). This function does not perform
 851   padding. Caller must perform padding, if necessary, to ensure valid input data size.
 852   TdesContext should be already correctly initialized by TdesInit(). Behavior with
 853   invalid TDES context is undefined.
 854
 855   If TdesContext is NULL, then return FALSE.
 856   If Input is NULL, then return FALSE.
 857   If InputSize is not multiple of block size (8 bytes), then return FALSE.
 858   If Output is NULL, then return FALSE.
 859   If this interface is not supported, then return FALSE.
 860
 861   @param[in]   TdesContext  Pointer to the TDES context.
 862   @param[in]   Input        Pointer to the buffer containing the data to be decrypted.
 863   @param[in]   InputSize    Size of the Input buffer in bytes.
 864   @param[out]  Output       Pointer to a buffer that receives the TDES decryption output.
 865
 866   @retval TRUE   TDES decryption succeeded.
 867   @retval FALSE  TDES decryption failed.
 868   @retval FALSE  This interface is not supported.
 869
 870 **/
 871 BOOLEAN
 872 EFIAPI
 873 TdesEcbDecrypt (
 874   IN   VOID         *TdesContext,
 875   IN   CONST UINT8  *Input,
 876   IN   UINTN        InputSize,
 877   OUT  UINT8        *Output
 878   );
 879
 880 /**
 881   Performs TDES encryption on a data buffer of the specified size in CBC mode.
 882
 883   This function performs TDES encryption on data buffer pointed by Input, of specified
 884   size of InputSize, in CBC mode.
 885   InputSize must be multiple of block size (8 bytes). This function does not perform
 886   padding. Caller must perform padding, if necessary, to ensure valid input data size.
 887   Initialization vector should be one block size (8 bytes).
 888   TdesContext should be already correctly initialized by TdesInit(). Behavior with
 889   invalid TDES context is undefined.
 890
 891   If TdesContext is NULL, then return FALSE.
 892   If Input is NULL, then return FALSE.
 893   If InputSize is not multiple of block size (8 bytes), then return FALSE.
 894   If Ivec is NULL, then return FALSE.
 895   If Output is NULL, then return FALSE.
 896   If this interface is not supported, then return FALSE.
 897
 898   @param[in]   TdesContext  Pointer to the TDES context.
 899   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.
 900   @param[in]   InputSize    Size of the Input buffer in bytes.
 901   @param[in]   Ivec         Pointer to initialization vector.
 902   @param[out]  Output       Pointer to a buffer that receives the TDES encryption output.
 903
 904   @retval TRUE   TDES encryption succeeded.
 905   @retval FALSE  TDES encryption failed.
 906   @retval FALSE  This interface is not supported.
 907
 908 **/
 909 BOOLEAN
 910 EFIAPI
 911 TdesCbcEncrypt (
 912   IN   VOID         *TdesContext,
 913   IN   CONST UINT8  *Input,
 914   IN   UINTN        InputSize,
 915   IN   CONST UINT8  *Ivec,
 916   OUT  UINT8        *Output
 917   );
 918
 919 /**
 920   Performs TDES decryption on a data buffer of the specified size in CBC mode.
 921
 922   This function performs TDES decryption on data buffer pointed by Input, of specified
 923   size of InputSize, in CBC mode.
 924   InputSize must be multiple of block size (8 bytes). This function does not perform
 925   padding. Caller must perform padding, if necessary, to ensure valid input data size.
 926   Initialization vector should be one block size (8 bytes).
 927   TdesContext should be already correctly initialized by TdesInit(). Behavior with
 928   invalid TDES context is undefined.
 929
 930   If TdesContext is NULL, then return FALSE.
 931   If Input is NULL, then return FALSE.
 932   If InputSize is not multiple of block size (8 bytes), then return FALSE.
 933   If Ivec is NULL, then return FALSE.
 934   If Output is NULL, then return FALSE.
 935   If this interface is not supported, then return FALSE.
 936
 937   @param[in]   TdesContext  Pointer to the TDES context.
 938   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.
 939   @param[in]   InputSize    Size of the Input buffer in bytes.
 940   @param[in]   Ivec         Pointer to initialization vector.
 941   @param[out]  Output       Pointer to a buffer that receives the TDES encryption output.
 942
 943   @retval TRUE   TDES decryption succeeded.
 944   @retval FALSE  TDES decryption failed.
 945   @retval FALSE  This interface is not supported.
 946
 947 **/
 948 BOOLEAN
 949 EFIAPI
 950 TdesCbcDecrypt (
 951   IN   VOID         *TdesContext,
 952   IN   CONST UINT8  *Input,
 953   IN   UINTN        InputSize,
 954   IN   CONST UINT8  *Ivec,
 955   OUT  UINT8        *Output
 956   );
 957
 958 /**
 959   Retrieves the size, in bytes, of the context buffer required for AES operations.
 960
 961   If this interface is not supported, then return zero.
 962
 963   @return  The size, in bytes, of the context buffer required for AES operations.
 964   @retval  0   This interface is not supported.
 965
 966 **/
 967 UINTN
 968 EFIAPI
 969 AesGetContextSize (
 970   VOID
 971   );
 972
 973 /**
 974   Initializes user-supplied memory as AES context for subsequent use.
 975
 976   This function initializes user-supplied memory pointed by AesContext as AES context.
 977   In addtion, it sets up all AES key materials for subsequent encryption and decryption
 978   operations.
 979   There are 3 options for key length, 128 bits, 192 bits, and 256 bits.
 980
 981   If AesContext is NULL, then return FALSE.
 982   If Key is NULL, then return FALSE.
 983   If KeyLength is not valid, then return FALSE.
 984   If this interface is not supported, then return FALSE.
 985
 986   @param[out]  AesContext  Pointer to AES context being initialized.
 987   @param[in]   Key         Pointer to the user-supplied AES key.
 988   @param[in]   KeyLength   Length of AES key in bits.
 989
 990   @retval TRUE   AES context initialization succeeded.
 991   @retval FALSE  AES context initialization failed.
 992   @retval FALSE  This interface is not supported.
 993
 994 **/
 995 BOOLEAN
 996 EFIAPI
 997 AesInit (
 998   OUT  VOID         *AesContext,
 999   IN   CONST UINT8  *Key,
1000   IN   UINTN        KeyLength
1001   );
1002
1003 /**
1004   Performs AES encryption on a data buffer of the specified size in ECB mode.
1005
1006   This function performs AES encryption on data buffer pointed by Input, of specified
1007   size of InputSize, in ECB mode.
1008   InputSize must be multiple of block size (16 bytes). This function does not perform
1009   padding. Caller must perform padding, if necessary, to ensure valid input data size.
1010   AesContext should be already correctly initialized by AesInit(). Behavior with
1011   invalid AES context is undefined.
1012
1013   If AesContext is NULL, then return FALSE.
1014   If Input is NULL, then return FALSE.
1015   If InputSize is not multiple of block size (16 bytes), then return FALSE.
1016   If Output is NULL, then return FALSE.
1017   If this interface is not supported, then return FALSE.
1018
1019   @param[in]   AesContext  Pointer to the AES context.
1020   @param[in]   Input       Pointer to the buffer containing the data to be encrypted.
1021   @param[in]   InputSize   Size of the Input buffer in bytes.
1022   @param[out]  Output      Pointer to a buffer that receives the AES encryption output.
1023
1024   @retval TRUE   AES encryption succeeded.
1025   @retval FALSE  AES encryption failed.
1026   @retval FALSE  This interface is not supported.
1027
1028 **/
1029 BOOLEAN
1030 EFIAPI
1031 AesEcbEncrypt (
1032   IN   VOID         *AesContext,
1033   IN   CONST UINT8  *Input,
1034   IN   UINTN        InputSize,
1035   OUT  UINT8        *Output
1036   );
1037
1038 /**
1039   Performs AES decryption on a data buffer of the specified size in ECB mode.
1040
1041   This function performs AES decryption on data buffer pointed by Input, of specified
1042   size of InputSize, in ECB mode.
1043   InputSize must be multiple of block size (16 bytes). This function does not perform
1044   padding. Caller must perform padding, if necessary, to ensure valid input data size.
1045   AesContext should be already correctly initialized by AesInit(). Behavior with
1046   invalid AES context is undefined.
1047
1048   If AesContext is NULL, then return FALSE.
1049   If Input is NULL, then return FALSE.
1050   If InputSize is not multiple of block size (16 bytes), then return FALSE.
1051   If Output is NULL, then return FALSE.
1052   If this interface is not supported, then return FALSE.
1053
1054   @param[in]   AesContext  Pointer to the AES context.
1055   @param[in]   Input       Pointer to the buffer containing the data to be decrypted.
1056   @param[in]   InputSize   Size of the Input buffer in bytes.
1057   @param[out]  Output      Pointer to a buffer that receives the AES decryption output.
1058
1059   @retval TRUE   AES decryption succeeded.
1060   @retval FALSE  AES decryption failed.
1061   @retval FALSE  This interface is not supported.
1062
1063 **/
1064 BOOLEAN
1065 EFIAPI
1066 AesEcbDecrypt (
1067   IN   VOID         *AesContext,
1068   IN   CONST UINT8  *Input,
1069   IN   UINTN        InputSize,
1070   OUT  UINT8        *Output
1071   );
1072
1073 /**
1074   Performs AES encryption on a data buffer of the specified size in CBC mode.
1075
1076   This function performs AES encryption on data buffer pointed by Input, of specified
1077   size of InputSize, in CBC mode.
1078   InputSize must be multiple of block size (16 bytes). This function does not perform
1079   padding. Caller must perform padding, if necessary, to ensure valid input data size.
1080   Initialization vector should be one block size (16 bytes).
1081   AesContext should be already correctly initialized by AesInit(). Behavior with
1082   invalid AES context is undefined.
1083
1084   If AesContext is NULL, then return FALSE.
1085   If Input is NULL, then return FALSE.
1086   If InputSize is not multiple of block size (16 bytes), then return FALSE.
1087   If Ivec is NULL, then return FALSE.
1088   If Output is NULL, then return FALSE.
1089   If this interface is not supported, then return FALSE.
1090
1091   @param[in]   AesContext  Pointer to the AES context.
1092   @param[in]   Input       Pointer to the buffer containing the data to be encrypted.
1093   @param[in]   InputSize   Size of the Input buffer in bytes.
1094   @param[in]   Ivec        Pointer to initialization vector.
1095   @param[out]  Output      Pointer to a buffer that receives the AES encryption output.
1096
1097   @retval TRUE   AES encryption succeeded.
1098   @retval FALSE  AES encryption failed.
1099   @retval FALSE  This interface is not supported.
1100
1101 **/
1102 BOOLEAN
1103 EFIAPI
1104 AesCbcEncrypt (
1105   IN   VOID         *AesContext,
1106   IN   CONST UINT8  *Input,
1107   IN   UINTN        InputSize,
1108   IN   CONST UINT8  *Ivec,
1109   OUT  UINT8        *Output
1110   );
1111
1112 /**
1113   Performs AES decryption on a data buffer of the specified size in CBC mode.
1114
1115   This function performs AES decryption on data buffer pointed by Input, of specified
1116   size of InputSize, in CBC mode.
1117   InputSize must be multiple of block size (16 bytes). This function does not perform
1118   padding. Caller must perform padding, if necessary, to ensure valid input data size.
1119   Initialization vector should be one block size (16 bytes).
1120   AesContext should be already correctly initialized by AesInit(). Behavior with
1121   invalid AES context is undefined.
1122
1123   If AesContext is NULL, then return FALSE.
1124   If Input is NULL, then return FALSE.
1125   If InputSize is not multiple of block size (16 bytes), then return FALSE.
1126   If Ivec is NULL, then return FALSE.
1127   If Output is NULL, then return FALSE.
1128   If this interface is not supported, then return FALSE.
1129
1130   @param[in]   AesContext  Pointer to the AES context.
1131   @param[in]   Input       Pointer to the buffer containing the data to be encrypted.
1132   @param[in]   InputSize   Size of the Input buffer in bytes.
1133   @param[in]   Ivec        Pointer to initialization vector.
1134   @param[out]  Output      Pointer to a buffer that receives the AES encryption output.
1135
1136   @retval TRUE   AES decryption succeeded.
1137   @retval FALSE  AES decryption failed.
1138   @retval FALSE  This interface is not supported.
1139
1140 **/
1141 BOOLEAN
1142 EFIAPI
1143 AesCbcDecrypt (
1144   IN   VOID         *AesContext,
1145   IN   CONST UINT8  *Input,
1146   IN   UINTN        InputSize,
1147   IN   CONST UINT8  *Ivec,
1148   OUT  UINT8        *Output
1149   );
1150
1151 /**
1152   Retrieves the size, in bytes, of the context buffer required for ARC4 operations.
1153
1154   If this interface is not supported, then return zero.
1155
1156   @return  The size, in bytes, of the context buffer required for ARC4 operations.
1157   @retval  0   This interface is not supported.
1158
1159 **/
1160 UINTN
1161 EFIAPI
1162 Arc4GetContextSize (
1163   VOID
1164   );
1165
1166 /**
1167   Initializes user-supplied memory as ARC4 context for subsequent use.
1168
1169   This function initializes user-supplied memory pointed by Arc4Context as ARC4 context.
1170   In addtion, it sets up all ARC4 key materials for subsequent encryption and decryption
1171   operations.
1172
1173   If Arc4Context is NULL, then return FALSE.
1174   If Key is NULL, then return FALSE.
1175   If KeySize does not in the range of [5, 256] bytes, then return FALSE.
1176   If this interface is not supported, then return FALSE.
1177
1178   @param[out]  Arc4Context  Pointer to ARC4 context being initialized.
1179   @param[in]   Key          Pointer to the user-supplied ARC4 key.
1180   @param[in]   KeySize      Size of ARC4 key in bytes.
1181
1182   @retval TRUE   ARC4 context initialization succeeded.
1183   @retval FALSE  ARC4 context initialization failed.
1184   @retval FALSE  This interface is not supported.
1185
1186 **/
1187 BOOLEAN
1188 EFIAPI
1189 Arc4Init (
1190   OUT  VOID         *Arc4Context,
1191   IN   CONST UINT8  *Key,
1192   IN   UINTN        KeySize
1193   );
1194
1195 /**
1196   Performs ARC4 encryption on a data buffer of the specified size.
1197
1198   This function performs ARC4 encryption on data buffer pointed by Input, of specified
1199   size of InputSize.
1200   Arc4Context should be already correctly initialized by Arc4Init(). Behavior with
1201   invalid ARC4 context is undefined.
1202
1203   If Arc4Context is NULL, then return FALSE.
1204   If Input is NULL, then return FALSE.
1205   If Output is NULL, then return FALSE.
1206   If this interface is not supported, then return FALSE.
1207
1208   @param[in]   Arc4Context  Pointer to the ARC4 context.
1209   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.
1210   @param[in]   InputSize    Size of the Input buffer in bytes.
1211   @param[out]  Output       Pointer to a buffer that receives the ARC4 encryption output.
1212
1213   @retval TRUE   ARC4 encryption succeeded.
1214   @retval FALSE  ARC4 encryption failed.
1215   @retval FALSE  This interface is not supported.
1216
1217 **/
1218 BOOLEAN
1219 EFIAPI
1220 Arc4Encrypt (
1221   IN OUT  VOID         *Arc4Context,
1222   IN      CONST UINT8  *Input,
1223   IN      UINTN        InputSize,
1224   OUT     UINT8        *Output
1225   );
1226
1227 /**
1228   Performs ARC4 decryption on a data buffer of the specified size.
1229
1230   This function performs ARC4 decryption on data buffer pointed by Input, of specified
1231   size of InputSize.
1232   Arc4Context should be already correctly initialized by Arc4Init(). Behavior with
1233   invalid ARC4 context is undefined.
1234
1235   If Arc4Context is NULL, then return FALSE.
1236   If Input is NULL, then return FALSE.
1237   If Output is NULL, then return FALSE.
1238   If this interface is not supported, then return FALSE.
1239
1240   @param[in]   Arc4Context  Pointer to the ARC4 context.
1241   @param[in]   Input        Pointer to the buffer containing the data to be decrypted.
1242   @param[in]   InputSize    Size of the Input buffer in bytes.
1243   @param[out]  Output       Pointer to a buffer that receives the ARC4 decryption output.
1244
1245   @retval TRUE   ARC4 decryption succeeded.
1246   @retval FALSE  ARC4 decryption failed.
1247   @retval FALSE  This interface is not supported.
1248
1249 **/
1250 BOOLEAN
1251 EFIAPI
1252 Arc4Decrypt (
1253   IN OUT  VOID   *Arc4Context,
1254   IN      UINT8  *Input,
1255   IN      UINTN  InputSize,
1256   OUT     UINT8  *Output
1257   );
1258
1259 /**
1260   Resets the ARC4 context to the initial state.
1261
1262   The function resets the ARC4 context to the state it had immediately after the
1263   ARC4Init() function call.
1264   Contrary to ARC4Init(), Arc4Reset() requires no secret key as input, but ARC4 context
1265   should be already correctly initialized by ARC4Init().
1266
1267   If Arc4Context is NULL, then return FALSE.
1268   If this interface is not supported, then return FALSE.
1269
1270   @param[in, out]  Arc4Context  Pointer to the ARC4 context.
1271
1272   @retval TRUE   ARC4 reset succeeded.
1273   @retval FALSE  ARC4 reset failed.
1274   @retval FALSE  This interface is not supported.
1275
1276 **/
1277 BOOLEAN
1278 EFIAPI
1279 Arc4Reset (
1280   IN OUT  VOID  *Arc4Context
1281   );
1282
1283 //=====================================================================================
1284 //    Asymmetric Cryptography Primitive
1285 //=====================================================================================
1286
1287 /**
1288   Allocates and initializes one RSA context for subsequent use.
1289
1290   @return  Pointer to the RSA context that has been initialized.
1291            If the allocations fails, RsaNew() returns NULL.
1292
1293 **/
1294 VOID *
1295 EFIAPI
1296 RsaNew (
1297   VOID
1298   );
1299
1300 /**
1301   Release the specified RSA context.
1302
1303   If RsaContext is NULL, then return FALSE.
1304
1305   @param[in]  RsaContext  Pointer to the RSA context to be released.
1306
1307 **/
1308 VOID
1309 EFIAPI
1310 RsaFree (
1311   IN  VOID  *RsaContext
1312   );
1313
1314 /**
1315   Sets the tag-designated key component into the established RSA context.
1316
1317   This function sets the tag-designated RSA key component into the established
1318   RSA context from the user-specified non-negative integer (octet string format
1319   represented in RSA PKCS#1).
1320   If BigNumber is NULL, then the specified key componenet in RSA context is cleared.
1321
1322   If RsaContext is NULL, then return FALSE.
1323
1324   @param[in, out]  RsaContext  Pointer to RSA context being set.
1325   @param[in]       KeyTag      Tag of RSA key component being set.
1326   @param[in]       BigNumber   Pointer to octet integer buffer.
1327                                If NULL, then the specified key componenet in RSA
1328                                context is cleared.
1329   @param[in]       BnSize      Size of big number buffer in bytes.
1330                                If BigNumber is NULL, then it is ignored.
1331
1332   @retval  TRUE   RSA key component was set successfully.
1333   @retval  FALSE  Invalid RSA key component tag.
1334
1335 **/
1336 BOOLEAN
1337 EFIAPI
1338 RsaSetKey (
1339   IN OUT  VOID         *RsaContext,
1340   IN      RSA_KEY_TAG  KeyTag,
1341   IN      CONST UINT8  *BigNumber,
1342   IN      UINTN        BnSize
1343   );
1344
1345 /**
1346   Gets the tag-designated RSA key component from the established RSA context.
1347
1348   This function retrieves the tag-designated RSA key component from the
1349   established RSA context as a non-negative integer (octet string format
1350   represented in RSA PKCS#1).
1351   If specified key component has not been set or has been cleared, then returned
1352   BnSize is set to 0.
1353   If the BigNumber buffer is too small to hold the contents of the key, FALSE
1354   is returned and BnSize is set to the required buffer size to obtain the key.
1355
1356   If RsaContext is NULL, then return FALSE.
1357   If BnSize is NULL, then return FALSE.
1358   If BnSize is large enough but BigNumber is NULL, then return FALSE.
1359   If this interface is not supported, then return FALSE.
1360
1361   @param[in, out]  RsaContext  Pointer to RSA context being set.
1362   @param[in]       KeyTag      Tag of RSA key component being set.
1363   @param[out]      BigNumber   Pointer to octet integer buffer.
1364   @param[in, out]  BnSize      On input, the size of big number buffer in bytes.
1365                                On output, the size of data returned in big number buffer in bytes.
1366
1367   @retval  TRUE   RSA key component was retrieved successfully.
1368   @retval  FALSE  Invalid RSA key component tag.
1369   @retval  FALSE  BnSize is too small.
1370   @retval  FALSE  This interface is not supported.
1371
1372 **/
1373 BOOLEAN
1374 EFIAPI
1375 RsaGetKey (
1376   IN OUT  VOID         *RsaContext,
1377   IN      RSA_KEY_TAG  KeyTag,
1378   OUT     UINT8        *BigNumber,
1379   IN OUT  UINTN        *BnSize
1380   );
1381
1382 /**
1383   Generates RSA key components.
1384
1385   This function generates RSA key components. It takes RSA public exponent E and
1386   length in bits of RSA modulus N as input, and generates all key components.
1387   If PublicExponent is NULL, the default RSA public exponent (0x10001) will be used.
1388
1389   Before this function can be invoked, pseudorandom number generator must be correctly
1390   initialized by RandomSeed().
1391
1392   If RsaContext is NULL, then return FALSE.
1393   If this interface is not supported, then return FALSE.
1394
1395   @param[in, out]  RsaContext           Pointer to RSA context being set.
1396   @param[in]       ModulusLength        Length of RSA modulus N in bits.
1397   @param[in]       PublicExponent       Pointer to RSA public exponent.
1398   @param[in]       PublicExponentSize   Size of RSA public exponent buffer in bytes.
1399
1400   @retval  TRUE   RSA key component was generated successfully.
1401   @retval  FALSE  Invalid RSA key component tag.
1402   @retval  FALSE  This interface is not supported.
1403
1404 **/
1405 BOOLEAN
1406 EFIAPI
1407 RsaGenerateKey (
1408   IN OUT  VOID         *RsaContext,
1409   IN      UINTN        ModulusLength,
1410   IN      CONST UINT8  *PublicExponent,
1411   IN      UINTN        PublicExponentSize
1412   );
1413
1414 /**
1415   Validates key components of RSA context.
1416
1417   This function validates key compoents of RSA context in following aspects:
1418   - Whether p is a prime
1419   - Whether q is a prime
1420   - Whether n = p * q
1421   - Whether d*e = 1  mod lcm(p-1,q-1)
1422
1423   If RsaContext is NULL, then return FALSE.
1424   If this interface is not supported, then return FALSE.
1425
1426   @param[in]  RsaContext  Pointer to RSA context to check.
1427
1428   @retval  TRUE   RSA key components are valid.
1429   @retval  FALSE  RSA key components are not valid.
1430   @retval  FALSE  This interface is not supported.
1431
1432 **/
1433 BOOLEAN
1434 EFIAPI
1435 RsaCheckKey (
1436   IN  VOID  *RsaContext
1437   );
1438
1439 /**
1440   Carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme.
1441
1442   This function carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme defined in
1443   RSA PKCS#1.
1444   If the Signature buffer is too small to hold the contents of signature, FALSE
1445   is returned and SigSize is set to the required buffer size to obtain the signature.
1446
1447   If RsaContext is NULL, then return FALSE.
1448   If MessageHash is NULL, then return FALSE.
1449   If HashSize is not equal to the size of MD5, SHA-1 or SHA-256 digest, then return FALSE.
1450   If SigSize is large enough but Signature is NULL, then return FALSE.
1451   If this interface is not supported, then return FALSE.
1452
1453   @param[in]      RsaContext   Pointer to RSA context for signature generation.
1454   @param[in]      MessageHash  Pointer to octet message hash to be signed.
1455   @param[in]      HashSize     Size of the message hash in bytes.
1456   @param[out]     Signature    Pointer to buffer to receive RSA PKCS1-v1_5 signature.
1457   @param[in, out] SigSize      On input, the size of Signature buffer in bytes.
1458                                On output, the size of data returned in Signature buffer in bytes.
1459
1460   @retval  TRUE   Signature successfully generated in PKCS1-v1_5.
1461   @retval  FALSE  Signature generation failed.
1462   @retval  FALSE  SigSize is too small.
1463   @retval  FALSE  This interface is not supported.
1464
1465 **/
1466 BOOLEAN
1467 EFIAPI
1468 RsaPkcs1Sign (
1469   IN      VOID         *RsaContext,
1470   IN      CONST UINT8  *MessageHash,
1471   IN      UINTN        HashSize,
1472   OUT     UINT8        *Signature,
1473   IN OUT  UINTN        *SigSize
1474   );
1475
1476 /**
1477   Verifies the RSA-SSA signature with EMSA-PKCS1-v1_5 encoding scheme defined in
1478   RSA PKCS#1.
1479
1480   If RsaContext is NULL, then return FALSE.
1481   If MessageHash is NULL, then return FALSE.
1482   If Signature is NULL, then return FALSE.
1483   If HashSize is not equal to the size of MD5, SHA-1, SHA-256 digest, then return FALSE.
1484
1485   @param[in]  RsaContext   Pointer to RSA context for signature verification.
1486   @param[in]  MessageHash  Pointer to octet message hash to be checked.
1487   @param[in]  HashSize     Size of the message hash in bytes.
1488   @param[in]  Signature    Pointer to RSA PKCS1-v1_5 signature to be verified.
1489   @param[in]  SigSize      Size of signature in bytes.
1490
1491   @retval  TRUE   Valid signature encoded in PKCS1-v1_5.
1492   @retval  FALSE  Invalid signature or invalid RSA context.
1493
1494 **/
1495 BOOLEAN
1496 EFIAPI
1497 RsaPkcs1Verify (
1498   IN  VOID         *RsaContext,
1499   IN  CONST UINT8  *MessageHash,
1500   IN  UINTN        HashSize,
1501   IN  UINT8        *Signature,
1502   IN  UINTN        SigSize
1503   );
1504
1505 /**
1506   Retrieve the RSA Private Key from the password-protected PEM key data.
1507
1508   If PemData is NULL, then return FALSE.
1509   If RsaContext is NULL, then return FALSE.
1510   If this interface is not supported, then return FALSE.
1511
1512   @param[in]  PemData      Pointer to the PEM-encoded key data to be retrieved.
1513   @param[in]  PemSize      Size of the PEM key data in bytes.
1514   @param[in]  Password     NULL-terminated passphrase used for encrypted PEM key data.
1515   @param[out] RsaContext   Pointer to new-generated RSA context which contain the retrieved
1516                            RSA private key component. Use RsaFree() function to free the
1517                            resource.
1518
1519   @retval  TRUE   RSA Private Key was retrieved successfully.
1520   @retval  FALSE  Invalid PEM key data or incorrect password.
1521   @retval  FALSE  This interface is not supported.
1522
1523
1524 **/
1525 BOOLEAN
1526 EFIAPI
1527 RsaGetPrivateKeyFromPem (
1528   IN   CONST UINT8  *PemData,
1529   IN   UINTN        PemSize,
1530   IN   CONST CHAR8  *Password,
1531   OUT  VOID         **RsaContext
1532   );
1533
1534 /**
1535   Retrieve the RSA Public Key from one DER-encoded X509 certificate.
1536
1537   If Cert is NULL, then return FALSE.
1538   If RsaContext is NULL, then return FALSE.
1539   If this interface is not supported, then return FALSE.
1540
1541   @param[in]  Cert         Pointer to the DER-encoded X509 certificate.
1542   @param[in]  CertSize     Size of the X509 certificate in bytes.
1543   @param[out] RsaContext   Pointer to new-generated RSA context which contain the retrieved
1544                            RSA public key component. Use RsaFree() function to free the
1545                            resource.
1546
1547   @retval  TRUE   RSA Public Key was retrieved successfully.
1548   @retval  FALSE  Fail to retrieve RSA public key from X509 certificate.
1549   @retval  FALSE  This interface is not supported.
1550
1551 **/
1552 BOOLEAN
1553 EFIAPI
1554 RsaGetPublicKeyFromX509 (
1555   IN   CONST UINT8  *Cert,
1556   IN   UINTN        CertSize,
1557   OUT  VOID         **RsaContext
1558   );
1559
1560 /**
1561   Retrieve the subject bytes from one X.509 certificate.
1562
1563   If Cert is NULL, then return FALSE.
1564   If SubjectSize is NULL, then return FALSE.
1565   If this interface is not supported, then return FALSE.
1566
1567   @param[in]      Cert         Pointer to the DER-encoded X509 certificate.
1568   @param[in]      CertSize     Size of the X509 certificate in bytes.
1569   @param[out]     CertSubject  Pointer to the retrieved certificate subject bytes.
1570   @param[in, out] SubjectSize  The size in bytes of the CertSubject buffer on input,
1571                                and the size of buffer returned CertSubject on output.
1572
1573   @retval  TRUE   The certificate subject retrieved successfully.
1574   @retval  FALSE  Invalid certificate, or the SubjectSize is too small for the result.
1575                   The SubjectSize will be updated with the required size.
1576   @retval  FALSE  This interface is not supported.
1577
1578 **/
1579 BOOLEAN
1580 EFIAPI
1581 X509GetSubjectName (
1582   IN      CONST UINT8  *Cert,
1583   IN      UINTN        CertSize,
1584   OUT     UINT8        *CertSubject,
1585   IN OUT  UINTN        *SubjectSize
1586   );
1587
1588 /**
1589   Verify one X509 certificate was issued by the trusted CA.
1590
1591   If Cert is NULL, then return FALSE.
1592   If CACert is NULL, then return FALSE.
1593   If this interface is not supported, then return FALSE.
1594
1595   @param[in]      Cert         Pointer to the DER-encoded X509 certificate to be verified.
1596   @param[in]      CertSize     Size of the X509 certificate in bytes.
1597   @param[in]      CACert       Pointer to the DER-encoded trusted CA certificate.
1598   @param[in]      CACertSize   Size of the CA Certificate in bytes.
1599
1600   @retval  TRUE   The certificate was issued by the trusted CA.
1601   @retval  FALSE  Invalid certificate or the certificate was not issued by the given
1602                   trusted CA.
1603   @retval  FALSE  This interface is not supported.
1604
1605 **/
1606 BOOLEAN
1607 EFIAPI
1608 X509VerifyCert (
1609   IN  CONST UINT8  *Cert,
1610   IN  UINTN        CertSize,
1611   IN  CONST UINT8  *CACert,
1612   IN  UINTN        CACertSize
1613   );
1614
1615 /**
1616   Construct a X509 object from DER-encoded certificate data.
1617
1618   If Cert is NULL, then return FALSE.
1619   If SingleX509Cert is NULL, then return FALSE.
1620   If this interface is not supported, then return FALSE.
1621
1622   @param[in]  Cert            Pointer to the DER-encoded certificate data.
1623   @param[in]  CertSize        The size of certificate data in bytes.
1624   @param[out] SingleX509Cert  The generated X509 object.
1625
1626   @retval     TRUE            The X509 object generation succeeded.
1627   @retval     FALSE           The operation failed.
1628   @retval     FALSE           This interface is not supported.
1629
1630 **/
1631 BOOLEAN
1632 EFIAPI
1633 X509ConstructCertificate (
1634   IN   CONST UINT8  *Cert,
1635   IN   UINTN        CertSize,
1636   OUT  UINT8        **SingleX509Cert
1637   );
1638
1639 /**
1640   Construct a X509 stack object from a list of DER-encoded certificate data.
1641
1642   If X509Stack is NULL, then return FALSE.
1643   If this interface is not supported, then return FALSE.
1644
1645   @param[in, out]  X509Stack  On input, pointer to an existing X509 stack object.
1646                               On output, pointer to the X509 stack object with new
1647                               inserted X509 certificate.
1648   @param           ...        A list of DER-encoded single certificate data followed
1649                               by certificate size. A NULL terminates the list. The
1650                               pairs are the arguments to X509ConstructCertificate().
1651
1652   @retval     TRUE            The X509 stack construction succeeded.
1653   @retval     FALSE           The construction operation failed.
1654   @retval     FALSE           This interface is not supported.
1655
1656 **/
1657 BOOLEAN
1658 EFIAPI
1659 X509ConstructCertificateStack (
1660   IN OUT  UINT8  **X509Stack,
1661   ...
1662   );
1663
1664 /**
1665   Release the specified X509 object.
1666
1667   If the interface is not supported, then ASSERT().
1668
1669   @param[in]  X509Cert  Pointer to the X509 object to be released.
1670
1671 **/
1672 VOID
1673 EFIAPI
1674 X509Free (
1675   IN  VOID  *X509Cert
1676   );
1677
1678 /**
1679   Release the specified X509 stack object.
1680
1681   If the interface is not supported, then ASSERT().
1682
1683   @param[in]  X509Stack  Pointer to the X509 stack object to be released.
1684
1685 **/
1686 VOID
1687 EFIAPI
1688 X509StackFree (
1689   IN  VOID  *X509Stack
1690   );
1691
1692 /**
1693   Get the signer's certificates from PKCS#7 signed data as described in "PKCS #7:
1694   Cryptographic Message Syntax Standard". The input signed data could be wrapped
1695   in a ContentInfo structure.
1696
1697   If P7Data, CertStack, StackLength, TrustedCert or CertLength is NULL, then
1698   return FALSE. If P7Length overflow, then return FAlSE.
1699   If this interface is not supported, then return FALSE.
1700
1701   @param[in]  P7Data       Pointer to the PKCS#7 message to verify.
1702   @param[in]  P7Length     Length of the PKCS#7 message in bytes.
1703   @param[out] CertStack    Pointer to Signer's certificates retrieved from P7Data.
1704                            It's caller's responsiblity to free the buffer.
1705   @param[out] StackLength  Length of signer's certificates in bytes.
1706   @param[out] TrustedCert  Pointer to a trusted certificate from Signer's certificates.
1707                            It's caller's responsiblity to free the buffer.
1708   @param[out] CertLength   Length of the trusted certificate in bytes.
1709
1710   @retval  TRUE            The operation is finished successfully.
1711   @retval  FALSE           Error occurs during the operation.
1712   @retval  FALSE           This interface is not supported.
1713
1714 **/
1715 BOOLEAN
1716 EFIAPI
1717 Pkcs7GetSigners (
1718   IN  CONST UINT8  *P7Data,
1719   IN  UINTN        P7Length,
1720   OUT UINT8        **CertStack,
1721   OUT UINTN        *StackLength,
1722   OUT UINT8        **TrustedCert,
1723   OUT UINTN        *CertLength
1724   );
1725
1726 /**
1727   Wrap function to use free() to free allocated memory for certificates.
1728
1729   If this interface is not supported, then ASSERT().
1730
1731   @param[in]  Certs        Pointer to the certificates to be freed.
1732
1733 **/
1734 VOID
1735 EFIAPI
1736 Pkcs7FreeSigners (
1737   IN  UINT8        *Certs
1738   );
1739
1740 /**
1741   Creates a PKCS#7 signedData as described in "PKCS #7: Cryptographic Message
1742   Syntax Standard, version 1.5". This interface is only intended to be used for
1743   application to perform PKCS#7 functionality validation.
1744
1745   If this interface is not supported, then return FALSE.
1746
1747   @param[in]  PrivateKey       Pointer to the PEM-formatted private key data for
1748                                data signing.
1749   @param[in]  PrivateKeySize   Size of the PEM private key data in bytes.
1750   @param[in]  KeyPassword      NULL-terminated passphrase used for encrypted PEM
1751                                key data.
1752   @param[in]  InData           Pointer to the content to be signed.
1753   @param[in]  InDataSize       Size of InData in bytes.
1754   @param[in]  SignCert         Pointer to signer's DER-encoded certificate to sign with.
1755   @param[in]  OtherCerts       Pointer to an optional additional set of certificates to
1756                                include in the PKCS#7 signedData (e.g. any intermediate
1757                                CAs in the chain).
1758   @param[out] SignedData       Pointer to output PKCS#7 signedData.
1759   @param[out] SignedDataSize   Size of SignedData in bytes.
1760
1761   @retval     TRUE             PKCS#7 data signing succeeded.
1762   @retval     FALSE            PKCS#7 data signing failed.
1763   @retval     FALSE            This interface is not supported.
1764
1765 **/
1766 BOOLEAN
1767 EFIAPI
1768 Pkcs7Sign (
1769   IN   CONST UINT8  *PrivateKey,
1770   IN   UINTN        PrivateKeySize,
1771   IN   CONST UINT8  *KeyPassword,
1772   IN   UINT8        *InData,
1773   IN   UINTN        InDataSize,
1774   IN   UINT8        *SignCert,
1775   IN   UINT8        *OtherCerts      OPTIONAL,
1776   OUT  UINT8        **SignedData,
1777   OUT  UINTN        *SignedDataSize
1778   );
1779
1780 /**
1781   Verifies the validility of a PKCS#7 signed data as described in "PKCS #7:
1782   Cryptographic Message Syntax Standard". The input signed data could be wrapped
1783   in a ContentInfo structure.
1784
1785   If P7Data, TrustedCert or InData is NULL, then return FALSE.
1786   If P7Length, CertLength or DataLength overflow, then return FAlSE.
1787   If this interface is not supported, then return FALSE.
1788
1789   @param[in]  P7Data       Pointer to the PKCS#7 message to verify.
1790   @param[in]  P7Length     Length of the PKCS#7 message in bytes.
1791   @param[in]  TrustedCert  Pointer to a trusted/root certificate encoded in DER, which
1792                            is used for certificate chain verification.
1793   @param[in]  CertLength   Length of the trusted certificate in bytes.
1794   @param[in]  InData       Pointer to the content to be verified.
1795   @param[in]  DataLength   Length of InData in bytes.
1796
1797   @retval  TRUE  The specified PKCS#7 signed data is valid.
1798   @retval  FALSE Invalid PKCS#7 signed data.
1799   @retval  FALSE This interface is not supported.
1800
1801 **/
1802 BOOLEAN
1803 EFIAPI
1804 Pkcs7Verify (
1805   IN  CONST UINT8  *P7Data,
1806   IN  UINTN        P7Length,
1807   IN  CONST UINT8  *TrustedCert,
1808   IN  UINTN        CertLength,
1809   IN  CONST UINT8  *InData,
1810   IN  UINTN        DataLength
1811   );
1812
1813 /**
1814   Verifies the validility of a PE/COFF Authenticode Signature as described in "Windows
1815   Authenticode Portable Executable Signature Format".
1816
1817   If AuthData is NULL, then return FALSE.
1818   If ImageHash is NULL, then return FALSE.
1819   If this interface is not supported, then return FALSE.
1820
1821   @param[in]  AuthData     Pointer to the Authenticode Signature retrieved from signed
1822                            PE/COFF image to be verified.
1823   @param[in]  DataSize     Size of the Authenticode Signature in bytes.
1824   @param[in]  TrustedCert  Pointer to a trusted/root certificate encoded in DER, which
1825                            is used for certificate chain verification.
1826   @param[in]  CertSize     Size of the trusted certificate in bytes.
1827   @param[in]  ImageHash    Pointer to the original image file hash value. The procudure
1828                            for calculating the image hash value is described in Authenticode
1829                            specification.
1830   @param[in]  HashSize     Size of Image hash value in bytes.
1831
1832   @retval  TRUE   The specified Authenticode Signature is valid.
1833   @retval  FALSE  Invalid Authenticode Signature.
1834   @retval  FALSE  This interface is not supported.
1835
1836 **/
1837 BOOLEAN
1838 EFIAPI
1839 AuthenticodeVerify (
1840   IN  CONST UINT8  *AuthData,
1841   IN  UINTN        DataSize,
1842   IN  CONST UINT8  *TrustedCert,
1843   IN  UINTN        CertSize,
1844   IN  CONST UINT8  *ImageHash,
1845   IN  UINTN        HashSize
1846   );
1847
1848 //=====================================================================================
1849 //    DH Key Exchange Primitive
1850 //=====================================================================================
1851
1852 /**
1853   Allocates and Initializes one Diffie-Hellman Context for subsequent use.
1854
1855   @return  Pointer to the Diffie-Hellman Context that has been initialized.
1856            If the allocations fails, DhNew() returns NULL.
1857            If the interface is not supported, DhNew() returns NULL.
1858
1859 **/
1860 VOID *
1861 EFIAPI
1862 DhNew (
1863   VOID
1864   );
1865
1866 /**
1867   Release the specified DH context.
1868
1869   If the interface is not supported, then ASSERT().
1870
1871   @param[in]  DhContext  Pointer to the DH context to be released.
1872
1873 **/
1874 VOID
1875 EFIAPI
1876 DhFree (
1877   IN  VOID  *DhContext
1878   );
1879
1880 /**
1881   Generates DH parameter.
1882
1883   Given generator g, and length of prime number p in bits, this function generates p,
1884   and sets DH context according to value of g and p.
1885
1886   Before this function can be invoked, pseudorandom number generator must be correctly
1887   initialized by RandomSeed().
1888
1889   If DhContext is NULL, then return FALSE.
1890   If Prime is NULL, then return FALSE.
1891   If this interface is not supported, then return FALSE.
1892
1893   @param[in, out]  DhContext    Pointer to the DH context.
1894   @param[in]       Generator    Value of generator.
1895   @param[in]       PrimeLength  Length in bits of prime to be generated.
1896   @param[out]      Prime        Pointer to the buffer to receive the generated prime number.
1897
1898   @retval TRUE   DH pamameter generation succeeded.
1899   @retval FALSE  Value of Generator is not supported.
1900   @retval FALSE  PRNG fails to generate random prime number with PrimeLength.
1901   @retval FALSE  This interface is not supported.
1902
1903 **/
1904 BOOLEAN
1905 EFIAPI
1906 DhGenerateParameter (
1907   IN OUT  VOID   *DhContext,
1908   IN      UINTN  Generator,
1909   IN      UINTN  PrimeLength,
1910   OUT     UINT8  *Prime
1911   );
1912
1913 /**
1914   Sets generator and prime parameters for DH.
1915
1916   Given generator g, and prime number p, this function and sets DH
1917   context accordingly.
1918
1919   If DhContext is NULL, then return FALSE.
1920   If Prime is NULL, then return FALSE.
1921   If this interface is not supported, then return FALSE.
1922
1923   @param[in, out]  DhContext    Pointer to the DH context.
1924   @param[in]       Generator    Value of generator.
1925   @param[in]       PrimeLength  Length in bits of prime to be generated.
1926   @param[in]       Prime        Pointer to the prime number.
1927
1928   @retval TRUE   DH pamameter setting succeeded.
1929   @retval FALSE  Value of Generator is not supported.
1930   @retval FALSE  Value of Generator is not suitable for the Prime.
1931   @retval FALSE  Value of Prime is not a prime number.
1932   @retval FALSE  Value of Prime is not a safe prime number.
1933   @retval FALSE  This interface is not supported.
1934
1935 **/
1936 BOOLEAN
1937 EFIAPI
1938 DhSetParameter (
1939   IN OUT  VOID         *DhContext,
1940   IN      UINTN        Generator,
1941   IN      UINTN        PrimeLength,
1942   IN      CONST UINT8  *Prime
1943   );
1944
1945 /**
1946   Generates DH public key.
1947
1948   This function generates random secret exponent, and computes the public key, which is
1949   returned via parameter PublicKey and PublicKeySize. DH context is updated accordingly.
1950   If the PublicKey buffer is too small to hold the public key, FALSE is returned and
1951   PublicKeySize is set to the required buffer size to obtain the public key.
1952
1953   If DhContext is NULL, then return FALSE.
1954   If PublicKeySize is NULL, then return FALSE.
1955   If PublicKeySize is large enough but PublicKey is NULL, then return FALSE.
1956   If this interface is not supported, then return FALSE.
1957
1958   @param[in, out]  DhContext      Pointer to the DH context.
1959   @param[out]      PublicKey      Pointer to the buffer to receive generated public key.
1960   @param[in, out]  PublicKeySize  On input, the size of PublicKey buffer in bytes.
1961                                  On output, the size of data returned in PublicKey buffer in bytes.
1962
1963   @retval TRUE   DH public key generation succeeded.
1964   @retval FALSE  DH public key generation failed.
1965   @retval FALSE  PublicKeySize is not large enough.
1966   @retval FALSE  This interface is not supported.
1967
1968 **/
1969 BOOLEAN
1970 EFIAPI
1971 DhGenerateKey (
1972   IN OUT  VOID   *DhContext,
1973   OUT     UINT8  *PublicKey,
1974   IN OUT  UINTN  *PublicKeySize
1975   );
1976
1977 /**
1978   Computes exchanged common key.
1979
1980   Given peer's public key, this function computes the exchanged common key, based on its own
1981   context including value of prime modulus and random secret exponent.
1982
1983   If DhContext is NULL, then return FALSE.
1984   If PeerPublicKey is NULL, then return FALSE.
1985   If KeySize is NULL, then return FALSE.
1986   If KeySize is large enough but Key is NULL, then return FALSE.
1987   If this interface is not supported, then return FALSE.
1988
1989   @param[in, out]  DhContext          Pointer to the DH context.
1990   @param[in]       PeerPublicKey      Pointer to the peer's public key.
1991   @param[in]       PeerPublicKeySize  Size of peer's public key in bytes.
1992   @param[out]      Key                Pointer to the buffer to receive generated key.
1993   @param[in, out]  KeySize            On input, the size of Key buffer in bytes.
1994                                      On output, the size of data returned in Key buffer in bytes.
1995
1996   @retval TRUE   DH exchanged key generation succeeded.
1997   @retval FALSE  DH exchanged key generation failed.
1998   @retval FALSE  KeySize is not large enough.
1999   @retval FALSE  This interface is not supported.
2000
2001 **/
2002 BOOLEAN
2003 EFIAPI
2004 DhComputeKey (
2005   IN OUT  VOID         *DhContext,
2006   IN      CONST UINT8  *PeerPublicKey,
2007   IN      UINTN        PeerPublicKeySize,
2008   OUT     UINT8        *Key,
2009   IN OUT  UINTN        *KeySize
2010   );
2011
2012 //=====================================================================================
2013 //    Pseudo-Random Generation Primitive
2014 //=====================================================================================
2015
2016 /**
2017   Sets up the seed value for the pseudorandom number generator.
2018
2019   This function sets up the seed value for the pseudorandom number generator.
2020   If Seed is not NULL, then the seed passed in is used.
2021   If Seed is NULL, then default seed is used.
2022   If this interface is not supported, then return FALSE.
2023
2024   @param[in]  Seed      Pointer to seed value.
2025                         If NULL, default seed is used.
2026   @param[in]  SeedSize  Size of seed value.
2027                         If Seed is NULL, this parameter is ignored.
2028
2029   @retval TRUE   Pseudorandom number generator has enough entropy for random generation.
2030   @retval FALSE  Pseudorandom number generator does not have enough entropy for random generation.
2031   @retval FALSE  This interface is not supported.
2032
2033 **/
2034 BOOLEAN
2035 EFIAPI
2036 RandomSeed (
2037   IN  CONST  UINT8  *Seed  OPTIONAL,
2038   IN  UINTN         SeedSize
2039   );
2040
2041 /**
2042   Generates a pseudorandom byte stream of the specified size.
2043
2044   If Output is NULL, then return FALSE.
2045   If this interface is not supported, then return FALSE.
2046
2047   @param[out]  Output  Pointer to buffer to receive random value.
2048   @param[in]   Size    Size of randome bytes to generate.
2049
2050   @retval TRUE   Pseudorandom byte stream generated successfully.
2051   @retval FALSE  Pseudorandom number generator fails to generate due to lack of entropy.
2052   @retval FALSE  This interface is not supported.
2053
2054 **/
2055 BOOLEAN
2056 EFIAPI
2057 RandomBytes (
2058   OUT  UINT8  *Output,
2059   IN   UINTN  Size
2060   );
2061
2062 #endif // __BASE_CRYPT_LIB_H__